fix(providers): sanitize DeepSeek history

egavrin · devagent · egavrin · commit 586afa84547f · 2026-04-24T18:56:22.000+03:00
- Normalize DeepSeek request history before sending it to the API

- Prune unreplayable legacy tool calls and orphan tool results

- Preserve reasoning for complete tool-use turns

Co-Authored-By: devagent &lt;devagent@egavrin&gt;
diff --git a/packages/providers/src/deepseek.ts b/packages/providers/src/deepseek.ts
@@ -31,6 +31,16 @@ interface DeepSeekUsage {
   readonly completion_tokens?: number | null;
 }
 
+interface PreparedDeepSeekHistory {
+  readonly messages: Array<Record<string, unknown>>;
+  readonly validToolCallIds: ReadonlySet<string>;
+}
+
+interface NormalizedDeepSeekTurn {
+  readonly messages: Array<Record<string, unknown>>;
+  readonly validToolCallIds: ReadonlySet<string>;
+}
+
 /**
  * DeepSeek's thinking-mode Chat Completions protocol has one non-OpenAI quirk:
  * assistant tool-call messages must be replayed with reasoning_content.
@@ -93,7 +103,7 @@ function buildRequestBody(
   const caps = resolveCapabilities(config.capabilities);
   const body: Record<string, unknown> = {
     model: config.model,
-    messages: messages.map(convertDeepSeekMessage),
+    messages: prepareDeepSeekHistory(messages),
     stream: true,
     stream_options: { include_usage: true },
     max_tokens: config.maxTokens ?? caps.defaultMaxTokens,
@@ -116,13 +126,96 @@ function buildRequestBody(
   return body;
 }
 
-function convertDeepSeekMessage(message: Message): Record<string, unknown> {
-  if (message.role === MessageRole.SYSTEM) {
-    return { role: "system", content: message.content ?? "" };
+function prepareDeepSeekHistory(messages: ReadonlyArray<Message>): Array<Record<string, unknown>> {
+  const prepared = normalizeDeepSeekHistory(messages);
+  validateDeepSeekHistory(prepared);
+  return prepared.messages;
+}
+
+function normalizeDeepSeekHistory(messages: ReadonlyArray<Message>): PreparedDeepSeekHistory {
+  const validToolCallIds = new Set<string>();
+  const converted: Array<Record<string, unknown>> = [];
+  let turn: Message[] = [];
+
+  for (const message of messages) {
+    if (message.role === MessageRole.SYSTEM) {
+      flushDeepSeekTurn(turn, converted, validToolCallIds);
+      turn = [];
+      converted.push({ role: "system", content: message.content ?? "" });
+      continue;
+    }
+    if (message.role === MessageRole.USER) {
+      flushDeepSeekTurn(turn, converted, validToolCallIds);
+      turn = [];
+      converted.push({ role: "user", content: message.content ?? "" });
+      continue;
+    }
+    turn.push(message);
   }
-  if (message.role === MessageRole.USER) {
-    return { role: "user", content: message.content ?? "" };
+  flushDeepSeekTurn(turn, converted, validToolCallIds);
+
+  return { messages: converted, validToolCallIds };
+}
+
+function flushDeepSeekTurn(
+  turn: ReadonlyArray<Message>,
+  converted: Array<Record<string, unknown>>,
+  validToolCallIds: Set<string>,
+): void {
+  if (turn.length === 0) return;
+  const normalized = normalizeDeepSeekTurn(turn);
+  for (const id of normalized.validToolCallIds) validToolCallIds.add(id);
+  converted.push(...normalized.messages);
+}
+
+function normalizeDeepSeekTurn(turn: ReadonlyArray<Message>): NormalizedDeepSeekTurn {
+  const droppedToolCallIds = collectUnreplayableDeepSeekToolCallIds(turn);
+  const validToolCallIds = collectReplayableDeepSeekToolCallIds(turn);
+  const hasToolUse = validToolCallIds.size > 0;
+  const messages: Array<Record<string, unknown>> = [];
+
+  for (const message of turn) {
+    if (shouldDropDeepSeekToolResult(message, droppedToolCallIds, validToolCallIds)) continue;
+    const normalized = convertDeepSeekTurnMessage(message, droppedToolCallIds, hasToolUse);
+    if (normalized) messages.push(normalized);
+  }
+
+  return { messages, validToolCallIds };
+}
+
+function collectUnreplayableDeepSeekToolCallIds(messages: ReadonlyArray<Message>): Set<string> {
+  const dropped = new Set<string>();
+  for (const message of messages) {
+    if (message.role !== MessageRole.ASSISTANT || message.thinking || !message.toolCalls?.length) continue;
+    for (const toolCall of message.toolCalls) dropped.add(toolCall.callId);
+  }
+  return dropped;
+}
+
+function collectReplayableDeepSeekToolCallIds(messages: ReadonlyArray<Message>): Set<string> {
+  const valid = new Set<string>();
+  for (const message of messages) {
+    if (message.role !== MessageRole.ASSISTANT || !message.thinking || !message.toolCalls?.length) continue;
+    for (const toolCall of message.toolCalls) valid.add(toolCall.callId);
   }
+  return valid;
+}
+
+function shouldDropDeepSeekToolResult(
+  message: Message,
+  droppedToolCallIds: ReadonlySet<string>,
+  validToolCallIds: ReadonlySet<string>,
+): boolean {
+  if (message.role !== MessageRole.TOOL) return false;
+  if (!message.toolCallId) return true;
+  return droppedToolCallIds.has(message.toolCallId) || !validToolCallIds.has(message.toolCallId);
+}
+
+function convertDeepSeekTurnMessage(
+  message: Message,
+  droppedToolCallIds: ReadonlySet<string>,
+  hasToolUse: boolean,
+): Record<string, unknown> | null {
   if (message.role === MessageRole.TOOL) {
     return {
       role: "tool",
@@ -135,22 +228,90 @@ function convertDeepSeekMessage(message: Message): Record<string, unknown> {
     role: "assistant",
     content: message.content ?? "",
   };
-  if (message.thinking && message.toolCalls?.length) {
-    converted["reasoning_content"] = message.thinking;
+  if (!message.toolCalls?.length) {
+    if (message.thinking && hasToolUse) converted["reasoning_content"] = message.thinking;
+    return hasToolUse && !message.thinking ? null : converted;
   }
-  if (message.toolCalls?.length) {
-    converted["tool_calls"] = message.toolCalls.map((toolCall) => ({
-      id: toolCall.callId,
-      type: "function",
-      function: {
-        name: toolCall.name,
-        arguments: JSON.stringify(toolCall.arguments),
-      },
-    }));
+  if (!message.thinking) {
+    return hasToolUse ? null : message.content?.trim() ? converted : null;
   }
+
+  const toolCalls = message.toolCalls.filter((toolCall) => !droppedToolCallIds.has(toolCall.callId));
+  if (toolCalls.length === 0) return message.content?.trim() ? converted : null;
+
+  converted["reasoning_content"] = message.thinking;
+  converted["tool_calls"] = toolCalls.map(convertDeepSeekToolCall);
   return converted;
 }
 
+function convertDeepSeekToolCall(toolCall: NonNullable<Message["toolCalls"]>[number]): Record<string, unknown> {
+  return {
+    id: toolCall.callId,
+    type: "function",
+    function: {
+      name: toolCall.name,
+      arguments: JSON.stringify(toolCall.arguments),
+    },
+  };
+}
+
+function validateDeepSeekHistory(prepared: PreparedDeepSeekHistory): void {
+  for (const turn of splitDeepSeekHistoryTurns(prepared.messages)) {
+    const hasToolUse = turn.some((message) => readDeepSeekToolCalls(message).length > 0);
+    for (const message of turn) {
+      validateDeepSeekAssistantMessage(message, hasToolUse);
+      validateDeepSeekToolMessage(message, prepared.validToolCallIds);
+    }
+  }
+}
+
+function splitDeepSeekHistoryTurns(messages: ReadonlyArray<Record<string, unknown>>): Array<Array<Record<string, unknown>>> {
+  const turns: Array<Array<Record<string, unknown>>> = [];
+  let current: Array<Record<string, unknown>> = [];
+  for (const message of messages) {
+    if (message["role"] === "user" || message["role"] === "system") {
+      if (current.length > 0) turns.push(current);
+      current = [message];
+    } else {
+      current.push(message);
+    }
+  }
+  if (current.length > 0) turns.push(current);
+  return turns;
+}
+
+function validateDeepSeekAssistantMessage(message: Record<string, unknown>, hasToolUse: boolean): void {
+  if (message["role"] !== "assistant") return;
+  const toolCalls = readDeepSeekToolCalls(message);
+  for (const toolCall of toolCalls) {
+    if (typeof toolCall.id !== "string" || toolCall.id.length === 0) {
+      throw new ProviderError("DeepSeek history error: assistant tool calls require non-empty ids");
+    }
+  }
+  if (toolCalls.length > 0 && typeof message["reasoning_content"] !== "string") {
+    throw new ProviderError("DeepSeek history error: assistant tool calls require reasoning_content");
+  }
+  if (toolCalls.length === 0 && "reasoning_content" in message && !hasToolUse) {
+    throw new ProviderError("DeepSeek history error: final assistant messages must not include reasoning_content");
+  }
+}
+
+function validateDeepSeekToolMessage(
+  message: Record<string, unknown>,
+  validToolCallIds: ReadonlySet<string>,
+): void {
+  if (message["role"] !== "tool") return;
+  const toolCallId = message["tool_call_id"];
+  if (typeof toolCallId !== "string" || !validToolCallIds.has(toolCallId)) {
+    throw new ProviderError("DeepSeek history error: tool result does not match an assistant tool call");
+  }
+}
+
+function readDeepSeekToolCalls(message: Record<string, unknown>): Array<{ id?: unknown }> {
+  const toolCalls = message["tool_calls"];
+  return Array.isArray(toolCalls) ? toolCalls as Array<{ id?: unknown }> : [];
+}
+
 function convertDeepSeekTool(tool: ToolSpec): Record<string, unknown> {
   return {
     type: "function",
diff --git a/packages/providers/src/index.test.ts b/packages/providers/src/index.test.ts
@@ -265,7 +265,7 @@ describe("DeepSeek registry provider", () => {
     expect(body["tools"]).toBeDefined();
   });
 
-  it("only replays DeepSeek reasoning_content for assistant tool calls", async () => {
+  it("replays DeepSeek reasoning_content for complete tool-use turns", async () => {
     const fetchMock = vi.fn().mockResolvedValue(makeChatStreamingResponse());
     globalThis.fetch = fetchMock as typeof globalThis.fetch;
 
@@ -316,9 +316,150 @@ describe("DeepSeek registry provider", () => {
     expect(body.messages?.[3]).toEqual({
       role: "assistant",
       content: "Final answer.",
+      reasoning_content: "This should stay local after the turn.",
     });
   });
 
+  it("omits DeepSeek reasoning_content for non-tool final answers", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeChatStreamingResponse());
+    globalThis.fetch = fetchMock as typeof globalThis.fetch;
+
+    const registry = createDefaultRegistry();
+    const provider = registry.get("deepseek", {
+      model: "deepseek-v4-pro",
+      apiKey: "test-key",
+      capabilities: {
+        useResponsesApi: false,
+        reasoning: true,
+        supportsTemperature: false,
+      },
+    });
+
+    await collectChunks(provider.chat([
+      { role: MessageRole.USER, content: "answer directly" },
+      {
+        role: MessageRole.ASSISTANT,
+        content: "Final answer.",
+        thinking: "No tool use happened.",
+      },
+      { role: MessageRole.USER, content: "what next?" },
+    ]));
+
+    const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as {
+      messages?: Array<Record<string, unknown>>;
+    };
+    expect(body.messages?.[1]).toEqual({
+      role: "assistant",
+      content: "Final answer.",
+    });
+  });
+
+  it("prunes unreplayable legacy DeepSeek tool-call history", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeChatStreamingResponse());
+    globalThis.fetch = fetchMock as typeof globalThis.fetch;
+
+    const registry = createDefaultRegistry();
+    const provider = registry.get("deepseek", {
+      model: "deepseek-v4-pro",
+      apiKey: "test-key",
+      capabilities: {
+        useResponsesApi: false,
+        reasoning: true,
+        supportsTemperature: false,
+      },
+    });
+
+    await collectChunks(provider.chat([
+      { role: MessageRole.USER, content: "first task" },
+      {
+        role: MessageRole.ASSISTANT,
+        content: "",
+        thinking: "Valid tool reasoning.",
+        toolCalls: [{ name: "run_command", arguments: { cmd: "pwd" }, callId: "call_valid" }],
+      },
+      { role: MessageRole.TOOL, toolCallId: "call_valid", content: "/tmp/project" },
+      {
+        role: MessageRole.ASSISTANT,
+        content: "Legacy visible text.",
+        toolCalls: [
+          { name: "read_file", arguments: { path: "a.ts" }, callId: "call_legacy_a" },
+          { name: "read_file", arguments: { path: "b.ts" }, callId: "call_legacy_b" },
+        ],
+      },
+      { role: MessageRole.TOOL, toolCallId: "call_legacy_a", content: "a" },
+      { role: MessageRole.TOOL, toolCallId: "call_legacy_b", content: "b" },
+      { role: MessageRole.TOOL, toolCallId: "call_orphan", content: "orphan" },
+      { role: MessageRole.USER, content: "next task" },
+      {
+        role: MessageRole.ASSISTANT,
+        content: "Legacy visible text without valid tool use.",
+        toolCalls: [
+          { name: "read_file", arguments: { path: "c.ts" }, callId: "call_legacy_c" },
+        ],
+      },
+      { role: MessageRole.TOOL, toolCallId: "call_legacy_c", content: "c" },
+      { role: MessageRole.USER, content: "final task" },
+    ]));
+
+    const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as {
+      messages?: Array<Record<string, unknown>>;
+    };
+    expect(body.messages).toEqual([
+      { role: "user", content: "first task" },
+      {
+        role: "assistant",
+        content: "",
+        reasoning_content: "Valid tool reasoning.",
+        tool_calls: [{
+          id: "call_valid",
+          type: "function",
+          function: {
+            name: "run_command",
+            arguments: "{\"cmd\":\"pwd\"}",
+          },
+        }],
+      },
+      { role: "tool", tool_call_id: "call_valid", content: "/tmp/project" },
+      { role: "user", content: "next task" },
+      { role: "assistant", content: "Legacy visible text without valid tool use." },
+      { role: "user", content: "final task" },
+    ]);
+  });
+
+  it("rejects malformed normalized DeepSeek tool-call history locally", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeChatStreamingResponse());
+    globalThis.fetch = fetchMock as typeof globalThis.fetch;
+
+    const registry = createDefaultRegistry();
+    const provider = registry.get("deepseek", {
+      model: "deepseek-v4-pro",
+      apiKey: "test-key",
+      capabilities: {
+        useResponsesApi: false,
+        reasoning: true,
+        supportsTemperature: false,
+      },
+    });
+
+    let message = "";
+    try {
+      await collectChunks(provider.chat([
+        { role: MessageRole.USER, content: "first task" },
+        {
+          role: MessageRole.ASSISTANT,
+          content: "",
+          thinking: "Reasoning exists but the tool id is broken.",
+          toolCalls: [{ name: "run_command", arguments: { cmd: "pwd" }, callId: "" }],
+        },
+      ]));
+    } catch (err) {
+      message = err instanceof Error ? err.message : String(err);
+    }
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(message).toContain("assistant tool calls require non-empty ids");
+  });
+
   it("classifies DeepSeek JSON errors without leaking credentials", async () => {
     const fetchMock = vi.fn().mockResolvedValue(new Response(
       JSON.stringify({ error: { message: "The `reasoning_content` in the thinking mode must be passed back to the API." } }),
