feat(litellm): handle reasoning_content and reasoning fields in streaming (#449)

* feat(litellm): handle reasoning_content and reasoning fields in streaming

LiteLLMHandler was not processing reasoning/thinking fields from the
stream delta, causing reasoning output from DeepSeek, QwQ, and other
reasoning models routed through LiteLLM to be silently dropped.

Mirrors the reasoning extraction already present in
BaseOpenAiCompatibleProvider: checks for `reasoning_content` first,
falls back to `reasoning`, skips empty/whitespace-only values.

* test(litellm): add reasoning field handling coverage

Add tests verifying that reasoning_content and reasoning delta fields
are correctly yielded as reasoning chunks, that reasoning_content takes
precedence when both fields are present, and that empty/whitespace-only
values are silently ignored.

* test(litellm): cover falsy reasoning field branch on line 241

Add a test case where reasoning_content is undefined and reasoning is an empty string. This exercises the `|| ""` fallback in the reasoning delta handler, which was previously uncovered.

* refactor(reasoning): extract delta reasoning helper and fix fallback bug

Replaces the for-of/break pattern in lite-llm.ts and
base-openai-compatible-provider.ts with a shared
extractReasoningFromDelta helper. The previous form short-circuited as
soon as the reasoning_content key existed, so a delta carrying
reasoning_content: null (or '') alongside a populated reasoning field
would drop the model's thinking output entirely. The helper picks the
first field that is both a string and non-blank, restoring the intended
fallback chain across LiteLLM and every base-OpenAI-compatible provider.

* fix(reasoning): preserve whitespace-only chunks in streamed deltas

The previous trim-based guard in extractReasoningFromDelta dropped any
delta whose reasoning_content / reasoning payload contained only
whitespace. OpenAI-compatible streams routinely emit single-character
chunks (a lone " " between words or "\n\n" between paragraphs), and
discarding them collapsed word and paragraph boundaries once callers
concatenated the chunks into the accumulated reasoning string.

Replace the trim guard with explicit length-based fallthrough so:
- " ", "\n\n", etc. flow through verbatim
- null / non-string / empty-string still cascade to the next field
- the original reasoning_content: null + reasoning: "real" fix is kept

* Revert "fix(reasoning): preserve whitespace-only chunks in streamed deltas"

This reverts commit 64c3fcf.

* Reapply "fix(reasoning): preserve whitespace-only chunks in streamed deltas"

This reverts commit 860d1f7.

* test(reasoning): align base-openai-compatible tests with whitespace-preserving extractor

The extractor now passes whitespace-only reasoning chunks through verbatim so
streamed word/paragraph boundaries survive concatenation. Update the two
expectations that still assumed the old trim-and-drop behavior.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Oh Daewoong <dw.oh@samsung.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: 3 people

src/api/providers/__tests__/base-openai-compatible-provider.spec.ts

@@ -229,7 +229,7 @@ describe("BaseOpenAiCompatibleProvider", () => {
 	})
 
 	describe("reasoning_content field", () => {
-		it("should filter out whitespace-only reasoning_content", async () => {
+		it("should preserve whitespace-only reasoning_content so streamed boundaries survive concatenation", async () => {
 			mockCreate.mockImplementationOnce(() => {
 				return {
 					[Symbol.asyncIterator]: () => ({
@@ -262,8 +262,12 @@ describe("BaseOpenAiCompatibleProvider", () => {
 				chunks.push(chunk)
 			}
 
-			// Should only have the regular content, not the whitespace-only reasoning
-			expect(chunks).toEqual([{ type: "text", text: "Regular content" }])
+			expect(chunks).toEqual([
+				{ type: "reasoning", text: "\n" },
+				{ type: "reasoning", text: "   " },
+				{ type: "reasoning", text: "\t\n  " },
+				{ type: "text", text: "Regular content" },
+			])
 		})
 
 		it("should yield non-empty reasoning_content", async () => {
@@ -295,9 +299,9 @@ describe("BaseOpenAiCompatibleProvider", () => {
 				chunks.push(chunk)
 			}
 
-			// Should only yield the non-empty reasoning content
 			expect(chunks).toEqual([
 				{ type: "reasoning", text: "Thinking step 1" },
+				{ type: "reasoning", text: "\n" },
 				{ type: "reasoning", text: "Thinking step 2" },
 			])
 		})

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

@@ -719,6 +719,201 @@ describe("LiteLLMHandler", () => {
 		})
 	})
 
+	describe("reasoning field handling", () => {
+		it("should yield reasoning chunks from reasoning_content delta", async () => {
+			const mockStream = {
+				async *[Symbol.asyncIterator]() {
+					yield {
+						choices: [{ delta: { reasoning_content: "Let me think..." } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { content: "The answer is 42." } }],
+						usage: { prompt_tokens: 20, completion_tokens: 10 },
+					}
+				},
+			}
+
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "What is the answer?" }])
+			const results = []
+			for await (const chunk of generator) {
+				results.push(chunk)
+			}
+
+			const reasoningChunk = results.find((c) => c.type === "reasoning")
+			expect(reasoningChunk).toBeDefined()
+			expect(reasoningChunk).toMatchObject({ type: "reasoning", text: "Let me think..." })
+
+			const textChunk = results.find((c) => c.type === "text")
+			expect(textChunk).toMatchObject({ type: "text", text: "The answer is 42." })
+		})
+
+		it("should yield reasoning chunks from reasoning delta field", async () => {
+			const mockStream = {
+				async *[Symbol.asyncIterator]() {
+					yield {
+						choices: [{ delta: { reasoning: "Analyzing the problem..." } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { content: "Done." } }],
+						usage: { prompt_tokens: 10, completion_tokens: 5 },
+					}
+				},
+			}
+
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "Solve this." }])
+			const results = []
+			for await (const chunk of generator) {
+				results.push(chunk)
+			}
+
+			const reasoningChunk = results.find((c) => c.type === "reasoning")
+			expect(reasoningChunk).toBeDefined()
+			expect(reasoningChunk).toMatchObject({ type: "reasoning", text: "Analyzing the problem..." })
+		})
+
+		it("should prefer reasoning_content over reasoning when both are present", async () => {
+			const mockStream = {
+				async *[Symbol.asyncIterator]() {
+					yield {
+						choices: [
+							{ delta: { reasoning_content: "from_reasoning_content", reasoning: "from_reasoning" } },
+						],
+						usage: { prompt_tokens: 5, completion_tokens: 5 },
+					}
+				},
+			}
+
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "Test." }])
+			const results = []
+			for await (const chunk of generator) {
+				results.push(chunk)
+			}
+
+			const reasoningChunks = results.filter((c) => c.type === "reasoning")
+			expect(reasoningChunks).toHaveLength(1)
+			expect(reasoningChunks[0]).toMatchObject({ type: "reasoning", text: "from_reasoning_content" })
+		})
+
+		it("should not yield reasoning chunk when reasoning field is present but falsy", async () => {
+			const mockStream = {
+				async *[Symbol.asyncIterator]() {
+					yield {
+						choices: [{ delta: { reasoning_content: undefined } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { reasoning: "" } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { content: "Hello" } }],
+						usage: { prompt_tokens: 5, completion_tokens: 5 },
+					}
+				},
+			}
+
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "Hi" }])
+			const results = []
+			for await (const chunk of generator) {
+				results.push(chunk)
+			}
+
+			const reasoningChunks = results.filter((c) => c.type === "reasoning")
+			expect(reasoningChunks).toHaveLength(0)
+		})
+
+		it("should preserve whitespace-only reasoning chunks so streamed boundaries survive concatenation", async () => {
+			const mockStream = {
+				async *[Symbol.asyncIterator]() {
+					yield {
+						choices: [{ delta: { reasoning_content: "Let's" } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { reasoning_content: " " } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { reasoning_content: "think" } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { reasoning_content: "\n\n" } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { reasoning_content: "next" } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { content: "Hello" } }],
+						usage: { prompt_tokens: 5, completion_tokens: 5 },
+					}
+				},
+			}
+
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "Hi" }])
+			const results = []
+			for await (const chunk of generator) {
+				results.push(chunk)
+			}
+
+			const reasoningChunks = results.filter((c) => c.type === "reasoning")
+			expect(reasoningChunks.map((c) => (c as { text: string }).text).join("")).toBe("Let's think\n\nnext")
+		})
+
+		it("should fall back to reasoning when reasoning_content is null on the same delta", async () => {
+			const mockStream = {
+				async *[Symbol.asyncIterator]() {
+					yield {
+						choices: [{ delta: { reasoning_content: null, reasoning: "fallback thinking" } }],
+						usage: null,
+					}
+					yield {
+						choices: [{ delta: { content: "Answer." } }],
+						usage: { prompt_tokens: 5, completion_tokens: 5 },
+					}
+				},
+			}
+
+			mockCreate.mockReturnValue({
+				withResponse: vi.fn().mockResolvedValue({ data: mockStream }),
+			})
+
+			const generator = handler.createMessage("system", [{ role: "user", content: "Test." }])
+			const results = []
+			for await (const chunk of generator) {
+				results.push(chunk)
+			}
+
+			const reasoningChunks = results.filter((c) => c.type === "reasoning")
+			expect(reasoningChunks).toHaveLength(1)
+			expect(reasoningChunks[0]).toMatchObject({ type: "reasoning", text: "fallback thinking" })
+		})
+	})
+
 	describe("tool ID normalization", () => {
 		it("should truncate tool IDs longer than 64 characters", async () => {
 			const optionsWithBedrock: ApiHandlerOptions = {

src/api/providers/base-openai-compatible-provider.ts

@@ -14,6 +14,7 @@ import { BaseProvider } from "./base-provider"
 import { handleOpenAIError } from "./utils/openai-error-handler"
 import { calculateApiCostOpenAI } from "../../shared/cost"
 import { getApiRequestTimeout } from "./utils/timeout-config"
+import { extractReasoningFromDelta } from "./utils/extract-reasoning"
 
 type BaseOpenAiCompatibleProviderOptions<ModelName extends string> = ApiHandlerOptions & {
 	providerName: string
@@ -147,16 +148,9 @@ export abstract class BaseOpenAiCompatibleProvider<ModelName extends string>
 				}
 			}
 
-			if (delta) {
-				for (const key of ["reasoning_content", "reasoning"] as const) {
-					if (key in delta) {
-						const reasoning_content = ((delta as any)[key] as string | undefined) || ""
-						if (reasoning_content?.trim()) {
-							yield { type: "reasoning", text: reasoning_content }
-						}
-						break
-					}
-				}
+			const reasoningText = extractReasoningFromDelta(delta)
+			if (reasoningText) {
+				yield { type: "reasoning", text: reasoningText }
 			}
 
 			// Emit raw tool call chunks - NativeToolCallParser handles state management

src/api/providers/lite-llm.ts

@@ -13,6 +13,7 @@ import { sanitizeOpenAiCallId } from "../../utils/tool-id"
 
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
 import { RouterProvider } from "./router-provider"
+import { extractReasoningFromDelta } from "./utils/extract-reasoning"
 
 /**
  * LiteLLM provider handler
@@ -235,6 +236,11 @@ export class LiteLLMHandler extends RouterProvider implements SingleCompletionHa
 					yield { type: "text", text: delta.content }
 				}
 
+				const reasoningText = extractReasoningFromDelta(delta)
+				if (reasoningText) {
+					yield { type: "reasoning", text: reasoningText }
+				}
+
 				// Handle tool calls in stream - emit partial chunks for NativeToolCallParser
 				if (delta?.tool_calls) {
 					for (const toolCall of delta.tool_calls) {

src/api/providers/utils/__tests__/extract-reasoning.spec.ts

@@ -0,0 +1,63 @@
+// npx vitest run api/providers/utils/__tests__/extract-reasoning.spec.ts
+
+import { extractReasoningFromDelta } from "../extract-reasoning"
+
+describe("extractReasoningFromDelta", () => {
+	it("returns reasoning_content when present and non-blank", () => {
+		expect(extractReasoningFromDelta({ reasoning_content: "thinking..." })).toBe("thinking...")
+	})
+
+	it("returns reasoning when reasoning_content is missing", () => {
+		expect(extractReasoningFromDelta({ reasoning: "analyzing" })).toBe("analyzing")
+	})
+
+	it("prefers reasoning_content over reasoning when both are non-blank", () => {
+		expect(
+			extractReasoningFromDelta({
+				reasoning_content: "from_content",
+				reasoning: "from_reasoning",
+			}),
+		).toBe("from_content")
+	})
+
+	it("falls back to reasoning when reasoning_content is null on the same delta", () => {
+		expect(
+			extractReasoningFromDelta({
+				reasoning_content: null,
+				reasoning: "fallback",
+			}),
+		).toBe("fallback")
+	})
+
+	it("falls back to reasoning when reasoning_content is empty string", () => {
+		expect(
+			extractReasoningFromDelta({
+				reasoning_content: "",
+				reasoning: "fallback",
+			}),
+		).toBe("fallback")
+	})
+
+	it("preserves whitespace-only payloads so streamed chunks keep word and paragraph boundaries", () => {
+		expect(extractReasoningFromDelta({ reasoning_content: " " })).toBe(" ")
+		expect(extractReasoningFromDelta({ reasoning: "\n\n" })).toBe("\n\n")
+	})
+
+	it("falls back to reasoning when reasoning_content is an empty string but does not skip whitespace", () => {
+		expect(
+			extractReasoningFromDelta({
+				reasoning_content: "",
+				reasoning: "\n\n",
+			}),
+		).toBe("\n\n")
+	})
+
+	it("returns undefined when neither field is present", () => {
+		expect(extractReasoningFromDelta({ content: "hi" })).toBeUndefined()
+	})
+
+	it("returns undefined for nullish input", () => {
+		expect(extractReasoningFromDelta(null)).toBeUndefined()
+		expect(extractReasoningFromDelta(undefined)).toBeUndefined()
+	})
+})

src/api/providers/utils/extract-reasoning.ts

@@ -0,0 +1,25 @@
+/**
+ * Extracts reasoning text from a streaming delta object.
+ *
+ * Prefers `reasoning_content` (DeepSeek-R1 / QwQ style) and falls back to
+ * `reasoning` (OpenRouter style). Whitespace-only payloads (e.g. a lone " "
+ * or "\n\n" between paragraphs) are preserved so streamed reasoning keeps
+ * word and paragraph boundaries once chunks are concatenated downstream.
+ *
+ * The fallback only fires when the current field is missing, non-string,
+ * or an empty string — a delta with `reasoning_content: null` and a
+ * populated `reasoning` still resolves to the populated field.
+ */
+export function extractReasoningFromDelta(delta: unknown): string | undefined {
+	if (!delta) return undefined
+
+	const d = delta as { reasoning_content?: unknown; reasoning?: unknown }
+
+	if (typeof d.reasoning_content === "string" && d.reasoning_content.length > 0) {
+		return d.reasoning_content
+	}
+	if (typeof d.reasoning === "string" && d.reasoning.length > 0) {
+		return d.reasoning
+	}
+	return undefined
+}