fix: preserve valid completions reasoning replay

steipete · steipete · commit 8d3d9753a6ba · 2026-05-15T11:28:24.000+01:00
diff --git a/src/agents/openai-transport-stream.test.ts b/src/agents/openai-transport-stream.test.ts
@@ -5327,17 +5327,8 @@ describe("openai transport stream", () => {
   });
 });
 
-describe("buildOpenAICompletionsParams strips response-only reasoning fields", () => {
-  // OpenRouter and other OpenAI-Completions providers echo `reasoning_details`
-  // (array) and `reasoning_content` (string) in response choices to expose the
-  // model's chain of thought. If those fields leak back into a follow-up
-  // request, OpenRouter rejects the call with HTTP 500 ("Internal Server
-  // Error"). buildOpenAICompletionsParams must scrub them before the wire.
-  // Repro recipe (verified against live OpenRouter):
-  //   POST /chat/completions with messages[*].reasoning_details: "..." => 500
-  //   Same body without that key                                       => 200
-
-  const baseModel = {
+describe("buildOpenAICompletionsParams sanitizes reasoning replay fields", () => {
+  const openRouterModel = {
     id: "deepseek/deepseek-v4-flash",
     name: "DeepSeek v4 Flash",
     api: "openai-completions",
@@ -5350,6 +5341,19 @@ describe("buildOpenAICompletionsParams strips response-only reasoning fields", (
     maxTokens: 8192,
   } satisfies Model<"openai-completions">;
 
+  const openAIModel = {
+    id: "gpt-5.4-mini",
+    name: "GPT-5.4 Mini",
+    api: "openai-completions",
+    provider: "openai",
+    baseUrl: "https://api.openai.com/v1",
+    reasoning: true,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200_000,
+    maxTokens: 8192,
+  } satisfies Model<"openai-completions">;
+
   function getAssistantMessage(params: { messages: unknown }) {
     expect(Array.isArray(params.messages)).toBe(true);
     const list = params.messages as Array<Record<string, unknown>>;
@@ -5358,13 +5362,80 @@ describe("buildOpenAICompletionsParams strips response-only reasoning fields", (
     return assistant as Record<string, unknown>;
   }
 
-  it("removes reasoning_details, reasoning_content, and reasoning from assistant replay", () => {
+  function buildReplayParams(model: Model<"openai-completions">, thinkingSignature: string) {
+    return buildOpenAICompletionsParams(
+      model,
+      {
+        systemPrompt: "system",
+        messages: [
+          { role: "user", content: "hello" },
+          {
+            role: "assistant",
+            provider: model.provider,
+            api: model.api,
+            model: model.id,
+            stopReason: "stop",
+            timestamp: 0,
+            content: [
+              {
+                type: "thinking",
+                thinking: "Need to answer politely.",
+                thinkingSignature,
+              },
+              { type: "text", text: "Hello!" },
+            ],
+          },
+          { role: "user", content: "again" },
+        ],
+        tools: [],
+      } as never,
+      undefined,
+    ) as { messages: unknown };
+  }
+
+  it.each(["reasoning_details", "reasoning_content", "reasoning", "reasoning_text"])(
+    "strips %s from stock OpenAI Chat Completions assistant replay",
+    (thinkingSignature) => {
+      const assistant = getAssistantMessage(buildReplayParams(openAIModel, thinkingSignature));
+
+      expect(assistant).not.toHaveProperty("reasoning_details");
+      expect(assistant).not.toHaveProperty("reasoning_content");
+      expect(assistant).not.toHaveProperty("reasoning");
+      expect(assistant).not.toHaveProperty("reasoning_text");
+    },
+  );
+
+  it("normalizes OpenRouter string reasoning_details to reasoning", () => {
+    const assistant = getAssistantMessage(buildReplayParams(openRouterModel, "reasoning_details"));
+
+    expect(assistant).not.toHaveProperty("reasoning_details");
+    expect(assistant.reasoning).toBe("Need to answer politely.");
+  });
+
+  it.each(["reasoning", "reasoning_content"])(
+    "preserves OpenRouter %s string reasoning replay",
+    (thinkingSignature) => {
+      const assistant = getAssistantMessage(buildReplayParams(openRouterModel, thinkingSignature));
+
+      expect(assistant[thinkingSignature]).toBe("Need to answer politely.");
+    },
+  );
+
+  it("normalizes OpenRouter reasoning_text to reasoning", () => {
+    const assistant = getAssistantMessage(buildReplayParams(openRouterModel, "reasoning_text"));
+
+    expect(assistant).not.toHaveProperty("reasoning_text");
+    expect(assistant.reasoning).toBe("Need to answer politely.");
+  });
+
+  it("preserves OpenRouter array reasoning_details from tool-call signatures", () => {
+    const reasoningDetail = { type: "reasoning.encrypted", id: "rs_1", data: "ciphertext" };
     const params = buildOpenAICompletionsParams(
-      baseModel,
+      openRouterModel,
       {
         systemPrompt: "system",
         messages: [
-          { role: "user", content: "你好" },
+          { role: "user", content: "lookup" },
           {
             role: "assistant",
             provider: "openrouter",
@@ -5374,23 +5445,30 @@ describe("buildOpenAICompletionsParams strips response-only reasoning fields", (
             timestamp: 0,
             content: [
               {
-                type: "thinking",
-                thinking: "User said hi, I should respond politely.",
-                thinkingSignature: "considering",
+                type: "toolCall",
+                id: "call_1",
+                name: "lookup",
+                arguments: { query: "weather" },
+                thoughtSignature: JSON.stringify(reasoningDetail),
               },
-              { type: "text", text: "Hello!" },
             ],
           },
-          { role: "user", content: "再来一个" },
+          {
+            role: "toolResult",
+            toolCallId: "call_1",
+            toolName: "lookup",
+            content: [{ type: "text", text: "sunny" }],
+            isError: false,
+            timestamp: 1,
+          },
+          { role: "user", content: "answer" },
         ],
         tools: [],
       } as never,
       undefined,
     ) as { messages: unknown };
 
     const assistant = getAssistantMessage(params);
-    expect(assistant).not.toHaveProperty("reasoning_details");
-    expect(assistant).not.toHaveProperty("reasoning_content");
-    expect(assistant).not.toHaveProperty("reasoning");
+    expect(assistant.reasoning_details).toEqual([reasoningDetail]);
   });
 });
diff --git a/src/agents/openai-transport-stream.ts b/src/agents/openai-transport-stream.ts
@@ -2376,27 +2376,61 @@ function injectToolCallThoughtSignatures(
   }
 }
 
-// OpenRouter / many OpenAI-Completions providers ECHO `reasoning_details`
-// (array) and `reasoning_content` (string) inside response choices to surface
-// the model's chain of thought. Some downstream message builders inadvertently
-// preserve those fields when persisting an assistant turn, so they get
-// replayed verbatim on the next request. The Chat Completions request schema
-// does NOT accept either field on input messages — and worse, OpenRouter
-// rejects the call with a generic HTTP 500 ("Internal Server Error") instead
-// of a 4xx with a parse error, which makes the failure look like an upstream
-// outage. Always strip them from outgoing messages before we hit the wire.
-//
-// This is a defensive guard at the last possible point in the pipeline; the
-// underlying serializer (pi-ai's `convertMessages`) is the one that ought to
-// drop these, but until that is fixed upstream we cannot let a single stale
-// reasoning echo break every subsequent turn for the session.
-const COMPLETIONS_RESPONSE_ONLY_MESSAGE_FIELDS = [
+const COMPLETIONS_REASONING_REPLAY_FIELDS = [
   "reasoning_details",
   "reasoning_content",
   "reasoning",
+  "reasoning_text",
 ] as const;
 
-function stripCompletionsResponseOnlyFields(messages: unknown): void {
+function stripCompletionsReasoningReplayFields(record: Record<string, unknown>): void {
+  for (const field of COMPLETIONS_REASONING_REPLAY_FIELDS) {
+    if (field in record) {
+      delete record[field];
+    }
+  }
+}
+
+function sanitizeOpenRouterReasoningReplayFields(record: Record<string, unknown>): void {
+  const reasoningDetails = record.reasoning_details;
+  if (typeof reasoningDetails === "string") {
+    if (reasoningDetails.length > 0 && typeof record.reasoning !== "string") {
+      record.reasoning = reasoningDetails;
+    }
+    delete record.reasoning_details;
+  } else if (reasoningDetails !== undefined && !Array.isArray(reasoningDetails)) {
+    delete record.reasoning_details;
+  }
+
+  if ("reasoning" in record && typeof record.reasoning !== "string") {
+    delete record.reasoning;
+  }
+  if ("reasoning_content" in record && typeof record.reasoning_content !== "string") {
+    delete record.reasoning_content;
+  }
+
+  const reasoningText = record.reasoning_text;
+  if (
+    typeof reasoningText === "string" &&
+    reasoningText.length > 0 &&
+    typeof record.reasoning !== "string" &&
+    typeof record.reasoning_content !== "string"
+  ) {
+    record.reasoning = reasoningText;
+  }
+  if ("reasoning_text" in record) {
+    delete record.reasoning_text;
+  }
+}
+
+// OpenAI Chat Completions assistant-message input does not define reasoning
+// replay fields, while OpenRouter documents a compatible pass-back contract.
+// Keep OpenRouter's valid shapes, but normalize leaked string reasoning_details
+// from pi-ai thinking signatures before a follow-up request hits the wire.
+function sanitizeCompletionsReasoningReplayFields(
+  messages: unknown,
+  options: { preserveOpenRouterReasoning: boolean },
+): void {
   if (!Array.isArray(messages)) {
     return;
   }
@@ -2408,10 +2442,10 @@ function stripCompletionsResponseOnlyFields(messages: unknown): void {
     if (record.role !== "assistant") {
       continue;
     }
-    for (const field of COMPLETIONS_RESPONSE_ONLY_MESSAGE_FIELDS) {
-      if (field in record) {
-        delete record[field];
-      }
+    if (options.preserveOpenRouterReasoning) {
+      sanitizeOpenRouterReasoningReplayFields(record);
+    } else {
+      stripCompletionsReasoningReplayFields(record);
     }
   }
 }
@@ -2431,7 +2465,9 @@ export function buildOpenAICompletionsParams(
     : context;
   let messages = convertMessages(model as never, completionsContext, compat as never);
   injectToolCallThoughtSignatures(messages as unknown[], context, model);
-  stripCompletionsResponseOnlyFields(messages);
+  sanitizeCompletionsReasoningReplayFields(messages, {
+    preserveOpenRouterReasoning: compat.thinkingFormat === "openrouter",
+  });
   if (compat.strictMessageKeys) {
     messages = stripCompletionMessagesToRoleContent(messages) as typeof messages;
   }
