feat(litellm): forward taskId as X-Zoo-Session-ID request header

[awschmeder]

Related GitHub Issue

Closes: #590

Description

The LiteLLMHandler now forwards the active task ID as an X-Zoo-Session-ID HTTP request header so LiteLLM proxy operators can correlate individual API calls back to a specific Zoo Code conversation thread.

Implementation details:

• Added a requestHeaders map built from metadata?.taskId; the header is only sent when a task ID is present (no-op for callers that do not supply one).
• Passed as the second argument to client.chat.completions.create(requestOptions, { headers: requestHeaders }), chained with the existing .withResponse() pattern -- no changes to the mock shape in existing tests were needed.
• Follows the x-<vendor>-session-id convention used by Claude Code (x-claude-code-session-id) and GitHub Copilot (x-copilot-session-id).
• completePrompt is intentionally unchanged -- it receives no metadata/taskId, so there is no session ID to forward.

Test Procedure

Automated: cd src && npx vitest run api/providers/__tests__/lite-llm.spec.ts -- all 30 tests pass (28 pre-existing + 2 new).

New tests added in describe("session ID header"):

1. Asserts X-Zoo-Session-ID equals the taskId when metadata is provided.
2. Asserts the header is absent when no taskId is provided.

Manual: configure Zoo Code with a LiteLLM proxy and inspect proxy logs -- requests should show x-zoo-session-id tagged with the conversation task UUID.

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above). (Issue [ENHANCEMENT] Send X-Zoo-Session-ID header to LiteLLM proxy for per-conversation request correlation #590 filed; awaiting maintainer approval/assignment.)
• Scope: My changes are focused on the linked issue (one major feature/fix per PR).
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes (if applicable).
• Documentation Impact: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Screenshots / Videos

N/A -- no UI changes.

Documentation Updates

• No documentation updates are required.

Additional Notes

The header name X-Zoo-Session-ID was chosen (over X-Zoo-Task-ID used by the Zoo Gateway) to match LiteLLMs native session-tracking header convention and align with the industry pattern.

Get in Touch

awschmeder on Discord.

Summary by CodeRabbit

• New Features

  • Task IDs are now automatically forwarded to the LiteLLM service via request headers when available, enabling improved request tracking and correlation.

• Tests

  • Added test coverage for header functionality, including scenarios with and without task IDs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 750de012-7991-43eb-a440-39e889582703

📥 Commits

Reviewing files that changed from the base of the PR and between ed868c6 and dc2c8a3.

📒 Files selected for processing (3)

• .changeset/litellm-session-id-header.md
• src/api/providers/__tests__/lite-llm.spec.ts
• src/api/providers/lite-llm.ts

---

📝 Walkthrough

Walkthrough

This PR adds per-conversation request correlation to LiteLLM by forwarding the active task ID as an X-Zoo-Session-ID request header. The implementation conditionally includes this header when a task ID exists, includes test coverage for both presence and absence cases, and documents the change via a patch release entry.

Changes

LiteLLM Session ID Header

Layer / File(s)	Summary
LiteLLM session ID header implementation and tests src/api/providers/lite-llm.ts, src/api/providers/__tests__/lite-llm.spec.ts, .changeset/litellm-session-id-header.md	LiteLLMHandler.createMessage sets X-Zoo-Session-ID header from metadata.taskId when present and passes headers to the OpenAI streaming API call. Test suite verifies header inclusion when taskId is provided and omission when absent. Changeset documents the patch release.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

---

🐰 A session ID hops along the wire,
LiteLLM logs now climb much higher,
Per-task correlation flows with ease,
Conversations tracked with perfect peace. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: forwarding taskId as X-Zoo-Session-ID header in LiteLLM requests, which matches the core implementation.
Description check	✅ Passed	The description follows the template with all major sections completed: linked issue, detailed implementation approach, comprehensive test procedure, and checklist items addressed.
Linked Issues check	✅ Passed	The PR fulfills all requirements from issue #590: forwards taskId as X-Zoo-Session-ID header, only when taskId is present, and follows the x--session-id convention.
Out of Scope Changes check	✅ Passed	All changes directly relate to the linked issue #590 objective: the changeset, test additions, and implementation are focused on the LiteLLM session ID header feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[awschmeder]

ZooCode session trace viewed in LiteLLM admin panel after fix - each LLM call is linked under the same session ID

Main log shows 6 sequential LLM calls collapsed into one log entry:

Admin can click into the log entry and view each call trace in the session, thanks to LiteLLM-compatible session ID header injection.