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

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

Closes: #590

LiteLLM recognizes X-<vendor>-Session-ID headers for per-conversation
request correlation in logs and spend tracking. This follows the same
convention used by Claude Code (x-claude-code-session-id) and GitHub
Copilot (x-copilot-session-id).

The header is injected only when metadata.taskId is present, passed as
the second argument to client.chat.completions.create() alongside the
existing .withResponse() pattern so no existing tests need to change.

* docs(litellm): clarify X-Zoo-Session-ID header distinction from Zoo gateways

* test(litellm): add empty-string taskId case for X-Zoo-Session-ID header guard

Author: awschmeder

.changeset/litellm-session-id-header.md

@@ -0,0 +1,5 @@
+---
+"zoo-code": patch
+---
+
+Forward the active task ID to the LiteLLM proxy as an `X-Zoo-Session-ID` request header so individual conversations can be correlated in LiteLLM logs and spend tracking. The header is only sent when a task ID is present, and follows the `x-<vendor>-session-id` convention used by Claude Code (`x-claude-code-session-id`) and GitHub Copilot (`x-copilot-session-id`).

src/api/providers/__tests__/lite-llm.spec.ts

@@ -1117,4 +1117,61 @@ describe("LiteLLMHandler", () => {
 			expect(id1).not.toBe(id2)
 		})
 	})
+
+	describe("session ID header", () => {
+		const mockStream = {
+			async *[Symbol.asyncIterator]() {
+				yield {
+					choices: [{ delta: { content: "ok" } }],
+					usage: { prompt_tokens: 1, completion_tokens: 1 },
+				}
+			},
+		}
+
+		it("should send the X-Zoo-Session-ID header when a taskId is provided", async () => {
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "hi" }], {
+				taskId: "task-123",
+			})
+			for await (const _chunk of generator) {
+				// drain the stream
+			}
+
+			const requestHeaders = mockCreate.mock.calls[0][1]?.headers
+			expect(requestHeaders).toMatchObject({ "X-Zoo-Session-ID": "task-123" })
+		})
+
+		it("should not send the X-Zoo-Session-ID header when no taskId is provided", async () => {
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "hi" }])
+			for await (const _chunk of generator) {
+				// drain the stream
+			}
+
+			const requestHeaders = mockCreate.mock.calls[0][1]?.headers
+			expect(requestHeaders).not.toHaveProperty("X-Zoo-Session-ID")
+		})
+
+		it("should not send the X-Zoo-Session-ID header when taskId is an empty string", async () => {
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "hi" }], {
+				taskId: "",
+			})
+			for await (const _chunk of generator) {
+				// drain the stream
+			}
+
+			const requestHeaders = mockCreate.mock.calls[0][1]?.headers
+			expect(requestHeaders).not.toHaveProperty("X-Zoo-Session-ID")
+		})
+	})
 })

src/api/providers/lite-llm.ts

@@ -223,8 +223,22 @@ export class LiteLLMHandler extends RouterProvider implements SingleCompletionHa
 			requestOptions.temperature = this.options.modelTemperature ?? 0
 		}
 
+		// LiteLLM recognizes X-<vendor>-Session-ID for per-conversation request correlation.
+		// This header enables LiteLLM to group related API calls by task for logging and tracing.
+		// Unlike Zoo gateways (which use X-Zoo-Task-ID to correlate requests across multiple
+		// models within a single conversation), this header is specific to the LiteLLM provider
+		// and facilitates provider-level logging and debugging on LiteLLM's admin panel.
+		// Matches the convention used by Claude Code (x-claude-code-session-id) and
+		// GitHub Copilot (x-copilot-session-id).
+		const requestHeaders: Record<string, string> = {}
+		if (metadata?.taskId) {
+			requestHeaders["X-Zoo-Session-ID"] = metadata.taskId
+		}
+
 		try {
-			const { data: completion } = await this.client.chat.completions.create(requestOptions).withResponse()
+			const { data: completion } = await this.client.chat.completions
+				.create(requestOptions, { headers: requestHeaders })
+				.withResponse()
 
 			let lastUsage