@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/adapters/openai-chat.ts

@@ -1,6 +1,6 @@
 import type { AdapterRequest, ProviderAdapter } from "./base";
 import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall, OcxUsage } from "../types";
-import { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
+import { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
 import { mapReasoningEffort, modelRecordValue } from "../reasoning-effort";
 import { debugProviderDiagnostic } from "../lib/debug";
 import { sseFieldValue } from "../lib/sse-decoder";
@@ -23,7 +23,14 @@ import {
 // Z.AI needs this because its OpenAI path rejects glm-5.2[1m] with 400 code 1211;
 // unflagged OpenAI-compatible providers and the Anthropic adapter keep ids verbatim.
 export function stripBracketedModelSuffix(modelId: string): string {
-  return modelId.replace(/\[[^\]]*\]\s*$/, "");
+  const suffixEnd = modelId.trimEnd().length;
+  if (suffixEnd === 0 || modelId[suffixEnd - 1] !== "]") return modelId;
+
+  let suffixStart = -1;
+  for (let i = suffixEnd - 2; i >= 0 && modelId[i] !== "]"; i--) {
+    if (modelId[i] === "[") suffixStart = i;
+  }
+  return suffixStart === -1 ? modelId : modelId.slice(0, suffixStart);
 }
 
 // 260715 (issue #126): surface upstream error detail through the web-search sidecar loop.
@@ -48,14 +55,12 @@ function extractErrorDetail(parsed: unknown): string | undefined {
   if (typeof parsed === "string") return parsed.trim() || undefined;
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
   const obj = parsed as Record<string, unknown>;
-  // OpenAI shape: { error: { message } } or { error: "..." }
   const err = obj.error;
   if (typeof err === "string" && err.trim()) return err.trim();
   if (err !== null && typeof err === "object" && !Array.isArray(err)) {
     const msg = (err as Record<string, unknown>).message;
     if (typeof msg === "string" && msg.trim()) return msg.trim();
   }
-  // FastAPI/pydantic shape (NVIDIA NIM): { detail: "..." } or { detail: [{ msg, loc }, ...] }
   const det = obj.detail;
   if (typeof det === "string" && det.trim()) return det.trim();
   if (Array.isArray(det)) {
@@ -66,15 +71,11 @@ function extractErrorDetail(parsed: unknown): string | undefined {
       .filter(m => m.length > 0);
     if (msgs.length > 0) return msgs.join("; ");
   }
-  // Generic fallbacks: { message } / RFC7807 { title }
   if (typeof obj.message === "string" && obj.message.trim()) return obj.message.trim();
   if (typeof obj.title === "string" && obj.title.trim()) return obj.title.trim();
   return undefined;
 }
 
-// ClinePass live responses observed 2026-08-02 wrap non-stream Chat Completions in
-// `{ success, error, data }`; its public Chat Completions docs do not currently describe that
-// envelope. Keep ordinary OpenAI-shaped responses on the direct path.
 function unwrapChatCompletionPayload(json: Record<string, unknown>): Record<string, unknown> {
   if ((json.error !== undefined && json.error !== null) || Array.isArray(json.choices)) return json;
   const data = json.data;
@@ -169,6 +170,18 @@ function invalidChoicesEvent(usage?: OcxUsage): Extract<AdapterEvent, { type: "e
   };
 }
 
+function invalidToolCallsEvent(usage?: OcxUsage): Extract<AdapterEvent, { type: "error" }> {
+  return {
+    type: "error",
+    message: "upstream response contained invalid tool calls",
+    ...(usage !== undefined ? { usage } : {}),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 function developerSystemText(message: OcxMessage): string | undefined {
   if (message.role !== "developer") return undefined;
   if (typeof message.content === "string") return message.content;
@@ -176,18 +189,34 @@ function developerSystemText(message: OcxMessage): string | undefined {
   return message.content.map(part => (part as OcxTextContent).text).join("");
 }
 
+function isNativeOpenAIChatTarget(provider: OcxProviderConfig): boolean {
+  try {
+    return new URL(provider.baseUrl).hostname === "api.openai.com";
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Chat-completions image_url parts for images carried inside a tool result (issue #888). role:"tool"
  * content is text-only on every chat provider, so these ride in a follow-up user message instead of
  * being flattened to the "[image]" marker the model can't actually see. Data URLs and remote https
  * URLs are both valid in image_url.url, unlike Gemini inline_data which needs base64.
  */
+function toolResultTextForWire(content: string | OcxContentPart[]): string {
+  if (typeof content === "string") return content;
+  const text = content.filter((p) => p.type === "text").map((p) => (p as OcxTextContent).text).join("");
+  if (text) {
+    const untransportableImages = content.filter((p) => p.type === "image" && !p.imageUrl).length;
+    return `${text}${"[image]".repeat(untransportableImages)}`;
+  }
+  return contentPartsToText(content);
+}
+
 function toolResultImageChatParts(content: string | OcxContentPart[]): unknown[] {
   if (typeof content === "string") return [];
   const parts: unknown[] = [];
   for (const p of content) {
-    // Skip parts without a usable URL (the tool-output parser accepts the empty file_id shape):
-    // a {"url":""} part would fail the whole request where the "[image]" marker degrades safely.
     if (p.type !== "image" || !p.imageUrl) continue;
     parts.push({ type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } });
   }
@@ -197,17 +226,8 @@ function toolResultImageChatParts(content: string | OcxContentPart[]): unknown[]
 function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] {
   const out: unknown[] = [];
   const { context, options } = parsed;
-  // Mirror the bridge's replay-cache scope (issue #950): provider call ids are
-  // not globally unique, so reasoning must not cross conversation boundaries.
   const replayCacheScope = parsed._clientThreadId ?? "global";
 
-  // 260718 dangling tool_calls hardening (devlog/_plan/260718_dangling_toolcall_hardening):
-  // strict chat providers (Kimi/Moonshot) 400 when an assistant tool_call is not answered
-  // immediately by role:"tool" messages. Repair order: (1) reattach a real result to its
-  // original call (barrier messages are DEFERRED until the open tool round closes),
-  // (2) synthesize an explicit unavailable-result only when no real result exists,
-  // (3) manufacture an orphan assistant call only when no call occurrence matches at all.
-  // Occurrences are kept as an ordered list (never a Map) so duplicated ids survive.
   interface PendingToolCall { id: string; name: string }
   let pendingToolCalls: PendingToolCall[] = [];
   let deferredBarrierMessages: unknown[] = [];
@@ -230,10 +250,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
     deferredBarrierMessages = [];
   };
 
-  // Tool-result images collected during the open round land in ONE user vision message once the
-  // round closes — never inside it, where strict providers (Kimi/Moonshot) 400 on interleaved
-  // user messages. Released before deferred barriers so the images stay adjacent to the results
-  // they came from (mirrors google.ts sibling inline_data parts and the Kiro carrier images).
   const flushToolResultImages = (): void => {
     if (pendingToolResultImageParts.length === 0) return;
     out.push({
@@ -246,9 +262,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
     pendingToolResultImageParts = [];
   };
 
-  // Close an unresolved tool round with explicit unavailable-result messages. The wording
-  // must not claim interruption, success, failure, or user intent: execution status is
-  // UNKNOWN, and for user-input tools this must not read as an answer.
   const flushPendingToolCalls = (): void => {
     if (pendingToolCalls.length === 0) return;
     for (const call of pendingToolCalls) {
@@ -263,28 +276,21 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
     releaseDeferredBarriers();
   };
 
+  const nativeOpenAI = isNativeOpenAIChatTarget(provider);
   const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
     ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
     : undefined;
-  // Chat templates used by LM Studio, llama.cpp, and other strict OpenAI-compatible
-  // backends require every system instruction to precede conversation history. Codex can
-  // append developer reminders after user turns, so fold text-only developer messages into
-  // the single leading system message instead of emitting role:"system" in place. Developer
-  // messages with images cannot be represented as system content and remain user-compatible
-  // vision messages at their original position below.
-  const developerSystemParts = context.messages
-    .map(developerSystemText)
-    .filter((part): part is string => part !== undefined && part.length > 0);
+  const developerSystemParts = nativeOpenAI
+    ? []
+    : context.messages
+      .map(developerSystemText)
+      .filter((part): part is string => part !== undefined && part.length > 0);
   const systemParts = [
     ...(context.systemPrompt ?? []),
     ...developerSystemParts,
     ...(toolCatalogNudge ? [toolCatalogNudge] : []),
   ];
   if (systemParts.length > 0) {
-    // Codex sends its GPT-5 identity prompt for EVERY model (the per-model catalog
-    // base_instructions is ignored at request time). Neutralize that one identity line
-    // so routed, non-OpenAI models don't misreport themselves as GPT-5 / OpenAI — without
-    // leaking the proxy identity into the payload.
     const wireModelId = provider.modelSuffixBracketStrip
       ? stripBracketedModelSuffix(parsed.modelId)
       : parsed.modelId;
@@ -298,24 +304,23 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
       case "developer": {
         const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
         const hasImages = parts?.some(p => p.type === "image") ?? false;
-        if (msg.role === "developer" && !hasImages) break;
         let chatMsg: Record<string, unknown>;
-        if (typeof msg.content === "string") {
+        if (msg.role === "developer" && !hasImages) {
+          if (!nativeOpenAI) break;
+          const text = typeof msg.content === "string"
+            ? msg.content
+            : parts!.map(p => (p as OcxTextContent).text).join("");
+          chatMsg = { role: "developer", content: text };
+        } else if (typeof msg.content === "string") {
           chatMsg = { role: "user", content: msg.content };
+        } else if (!hasImages) {
+          chatMsg = { role: "user", content: parts!.map(p => (p as OcxTextContent).text).join("") };
         } else {
-          if (!hasImages) {
-            chatMsg = { role: "user", content: parts!.map(p => (p as OcxTextContent).text).join("") };
-          } else {
-            // Vision: chat-completions content-parts array. Images are only valid on the user role,
-            // and the data URL goes straight into image_url.url (never the token-exploding text path).
-            const chatParts = parts!.map(p => p.type === "image"
-              ? { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }
-              : { type: "text", text: (p as OcxTextContent).text });
-            chatMsg = { role: "user", content: chatParts };
-          }
+          const chatParts = parts!.map(p => p.type === "image"
+            ? { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }
+            : { type: "text", text: (p as OcxTextContent).text });
+          chatMsg = { role: "user", content: chatParts };
         }
-        // A barrier must not split an open tool round: defer it until the round closes
-        // (real result arrives) or the round is synthesized shut.
         if (pendingToolCalls.length > 0) deferredBarrierMessages.push(chatMsg);
         else out.push(chatMsg);
         break;
@@ -326,15 +331,8 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
         const thinkingParts = aMsg.content.filter(p => p.type === "thinking") as OcxThinkingContent[];
         const toolCalls = aMsg.content.filter(p => p.type === "toolCall") as OcxToolCall[];
         const chatMsg: Record<string, unknown> = { role: "assistant" };
-        if (textParts.length > 0) {
-          chatMsg.content = textParts.map(p => p.text).join("");
-        }
+        if (textParts.length > 0) chatMsg.content = textParts.map(p => p.text).join("");
         let reasoningContent = thinkingParts.map(p => p.thinking).join("");
-        // History transformations (compaction, lost assistant turn, resumed
-        // threads) can strip the reasoning item while the tool round survives.
-        // Re-attach the reasoning the bridge recorded for these call ids so
-        // preserveReasoningContentModels providers (DeepSeek thinking mode)
-        // never receive a bare tool-call continuation (issue #950).
         if (
           reasoningContent.length === 0
           && toolCalls.length > 0
@@ -347,16 +345,24 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
           // recorded under every call id — join unique texts only.
           if (cached.length > 0) {
             reasoningContent = [...new Set(cached)].join("\n");
+          } else if (modelInList(provider.requiresReasoningPlaceholderModels ?? provider.preserveReasoningContentModels, parsed.modelId)) {
+            // Fallback (extends #950, closes #1193): the replay cache is
+            // bounded (64 entries / 256 KiB / 1 h TTL) and always misses on
+            // long sessions, and some tool rounds carry no recorded reasoning
+            // at all. DeepSeek thinking mode rejects ANY tool_call assistant
+            // message missing reasoning_content with HTTP 400, so inject a
+            // minimal placeholder rather than emit a bare continuation the
+            // upstream will reject. Scoped to requiresReasoningPlaceholderModels
+            // (defaulting to the preserve list): preserve-listed providers with
+            // toggleable thinking (MiniMax low effort) opt out with `[]` so
+            // non-thinking histories are never given a fabricated placeholder.
+            reasoningContent = " ";
           }
         }
         if (reasoningContent.length > 0 && modelInList(provider.preserveReasoningContentModels, parsed.modelId)) {
           chatMsg.reasoning_content = reasoningContent;
         }
-        // Skip empty assistant messages: chat APIs like DeepSeek reject an assistant message
-        // with neither content, tool calls, nor a provider-supported reasoning_content field.
         if (chatMsg.content === undefined && toolCalls.length === 0 && chatMsg.reasoning_content === undefined) break;
-        // A new assistant starts while a previous round is still open: close the previous
-        // round synthetically first so its tool_calls are never left dangling.
         flushPendingToolCalls();
         const wireToolCalls = toolCalls.map(tc => {
           let id = tc.id;
@@ -370,8 +376,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
             type: "function",
             function: { name: namespacedToolName(tc.namespace, tc.name), arguments: JSON.stringify(tc.arguments) },
           }));
-          // "" instead of null: strict validators (xAI: "Each message must have at least one
-          // content element", langchain#34140) reject content-less assistant history entries.
           if (!chatMsg.content) chatMsg.content = emptyAssistantContent(provider);
         }
         if (chatMsg.reasoning_content !== undefined && chatMsg.content === undefined && chatMsg.tool_calls === undefined) {
@@ -385,12 +389,10 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
         let toolCallId = msg.toolCallId;
         const matchIdx = toolCallId ? pendingToolCalls.findIndex(c => c.id === toolCallId) : -1;
         if (matchIdx >= 0 && toolCallId) {
-          // Real result reattached to its original call. Barriers were deferred, so the
-          // tool message lands immediately inside the open round.
           out.push({
             role: "tool",
             tool_call_id: toolCallId,
-            content: contentPartsToText(msg.content),
+            content: toolResultTextForWire(msg.content),
           });
           pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
           pendingToolCalls.splice(matchIdx, 1);
@@ -400,23 +402,31 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
           }
         } else {
           if (!toolCallId) toolCallId = `call_orphan_${out.length}`;
-          // No matching call in the open round. Close any unresolved round first so the
-          // synthesized orphan pair never splits it, then keep the historical repair:
-          // WS turns can arrive with only tool outputs; chat-completions providers reject a bare
-          // role:"tool" message unless an assistant tool_call with the same id immediately precedes it.
           flushPendingToolCalls();
           const name = safeToolName(msg.toolName);
-          // The orphan repair synthesizes an assistant tool call for a result
-          // whose assistant turn was lost; carry the recorded reasoning so the
-          // replayed round stays valid for thinking-mode providers (#950).
           const cachedReasoning =
             toolCallId && modelInList(provider.preserveReasoningContentModels, parsed.modelId)
               ? peekReasoningForCall(toolCallId, replayCacheScope)
               : undefined;
+          // Same fallback as the main-assistant path: never emit a bare orphan
+          // tool_call continuation on a thinking-mode provider — inject a
+          // placeholder when the replay cache missed (the bounded cache can
+          // always miss on long sessions), or DeepSeek thinking mode 400s.
+          // Gate on the preserve list too: reasoning_content is only ever
+          // serialized for preserve-listed models, so a requires-only custom
+          // entry must not fabricate it on this path (P2 on #1205).
+          // `||` (not `??`): the cache never stores empty strings, but treat a
+          // falsy hit as a miss so the placeholder still fires.
+          const orphanReasoning =
+            cachedReasoning
+            || (modelInList(provider.preserveReasoningContentModels, parsed.modelId)
+              && modelInList(provider.requiresReasoningPlaceholderModels ?? provider.preserveReasoningContentModels, parsed.modelId)
+              ? " "
+              : undefined);
           out.push({
             role: "assistant",
             content: emptyAssistantContent(provider),
-            ...(cachedReasoning ? { reasoning_content: cachedReasoning } : {}),
+            ...(orphanReasoning ? { reasoning_content: orphanReasoning } : {}),
             tool_calls: [{
               id: toolCallId,
               type: "function",
@@ -427,7 +437,7 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
           out.push({
             role: "tool",
             tool_call_id: toolCallId,
-            content: contentPartsToText(msg.content),
+            content: toolResultTextForWire(msg.content),
           });
           pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
           flushToolResultImages();
@@ -437,8 +447,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
     }
   }
 
-  // Trailing dangle: a turn interrupted after the assistant requested tools leaves the
-  // round open; close it synthetically (then release any deferred barriers in order).
   flushPendingToolCalls();
   releaseDeferredBarriers();
   return out;
@@ -544,11 +552,6 @@ function isXaiSchemaTarget(provider: OcxProviderConfig): boolean {
   }
 }
 
-// Volcengine Ark regional endpoints. Ark validates an assistant message's text field as a
-// REQUIRED parameter and treats "" as absent, so a tool-call-only assistant in history 400s with
-// `MissingParameter: input.content.text` (#796). Every other OpenAI-compatible provider accepts
-// "", and xAI actively requires it ("Each message must have at least one content element"), so
-// the two contracts are in direct conflict and this cannot be a global change.
 const VOLCENGINE_ARK_HOSTNAMES = new Set([
   "ark.cn-beijing.volces.com",
   "ark.ap-southeast.volces.com",
@@ -562,35 +565,10 @@ function isVolcengineArkTarget(provider: OcxProviderConfig): boolean {
   }
 }
 
-/**
- * Placeholder content for an assistant history entry carrying only tool calls or reasoning.
- *
- * UNVERIFIED HYPOTHESIS for Ark. The reported error names `input.content.text`, a nested path,
- * which suggests Ark wants the structured content form `[{type:"text",text:""}]` rather than a
- * bare string — no string value, `""` or `" "`, exposes a `content.text` path at all. But Ark's
- * published examples only show array content for MULTIMODAL USER input, never for an assistant
- * history entry, so this shape is inferred from the error message and not confirmed by the docs
- * or by a live request. The empty inner text at least adds no tokens either way.
- *
- * Confirm against a real Ark endpoint before relying on this; #796 records what is still missing.
- *
- * Every other provider keeps the bare `""`, which xAI's validator specifically requires ("Each
- * message must have at least one content element"), so this cannot be applied globally.
- */
 function emptyAssistantContent(provider: OcxProviderConfig): string | { type: "text"; text: string }[] {
   return isVolcengineArkTarget(provider) ? [{ type: "text", text: "" }] : "";
 }
 
-/**
- * Providers like Kimi and DeepSeek reject function parameter schemas whose root
- * `type` is missing or `null` — JSON Schema requires `"object"` at the root of
- * function parameters. Add `type: "object"` at the root while preserving
- * `oneOf`, `$defs`, and every other schema key.
- *
- * This mirrors `normalizeFunctionToolSchema` in openai-responses.ts, which
- * applies the same root-only normalization unconditionally on the responses
- * path. Nested schema content is intentionally left untouched.
- */
 function ensureRootObjectType(parameters: unknown): Record<string, unknown> {
   if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
     return { type: "object", properties: {} };
@@ -634,12 +612,7 @@ function normalizeXaiToolParameters(parameters: unknown): Record<string, unknown
 
 function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] | undefined {
   if (!parsed.context.tools || parsed.context.tools.length === 0) return undefined;
-  const allowed = isAllowedToolChoice(parsed.options.toolChoice)
-    ? new Set(parsed.options.toolChoice.allowedTools)
-    : undefined;
-  const tools = allowed
-    ? parsed.context.tools.filter(t => toolAllowedByChoice(t, allowed))
-    : parsed.context.tools;
+  const tools = parsed.context.tools.filter(toolChoiceToolPredicate(parsed.options.toolChoice));
   if (tools.length === 0) return undefined;
   const xaiTarget = isXaiSchemaTarget(provider);
   const formatted = tools.flatMap(t => {
@@ -649,13 +622,13 @@ function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig
 
     if (parameters === undefined) return [];
     return [{
-    type: "function",
-    function: {
-      name: namespacedToolName(t.namespace, t.name),
-      description: t.description,
-      parameters,
-      ...(t.strict !== undefined ? { strict: t.strict } : {}),
-    },
+      type: "function",
+      function: {
+        name: namespacedToolName(t.namespace, t.name),
+        ...(t.description ? { description: t.description } : {}),
+        parameters,
+        ...(t.strict !== undefined ? { strict: t.strict } : {}),
+      },
     }];
   });
   return formatted.length > 0 ? formatted : undefined;
@@ -678,9 +651,18 @@ function toolsToChatFormatForProvider(parsed: OcxParsedRequest, provider: OcxPro
   });
 }
 
-function toolChoiceToChatFormat(tc: OcxParsedRequest["options"]["toolChoice"], tools: OcxParsedRequest["context"]["tools"]): unknown {
+function toolChoiceToChatFormat(
+  tc: OcxParsedRequest["options"]["toolChoice"],
+  tools: OcxParsedRequest["context"]["tools"],
+  provider: OcxProviderConfig,
+): unknown {
   if (!tc) return undefined;
-  if (isAllowedToolChoice(tc)) return tc.mode === "required" ? "required" : "auto";
+  if (isAllowedToolChoice(tc)) {
+    if (tc.mode === "required" && tc.allowedTools.length === 1 && isNativeOpenAIChatTarget(provider)) {
+      return { type: "function", function: { name: resolveToolChoiceWireName(tools, tc.allowedTools[0]) } };
+    }
+    return tc.mode === "required" ? "required" : "auto";
+  }
   if (tc === "auto" || tc === "none" || tc === "required") return tc;
   if ("name" in tc) return { type: "function", function: { name: resolveToolChoiceWireName(tools, tc.name) } };
   return undefined;
@@ -732,7 +714,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
 
       const messages = messagesToChatFormat(parsed, provider);
       const tools = toolsToChatFormatForProvider(parsed, provider);
-      const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools);
+      const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools, provider);
 
       const body: Record<string, unknown> = {
         model: provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(parsed.modelId) : parsed.modelId,
@@ -759,24 +741,41 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       if (parsed.options.stopSequences !== undefined) body.stop = parsed.options.stopSequences;
       const reasoningDisabled = modelInList(provider.noReasoningModels, parsed.modelId);
       const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
+      const nativeOpenAI = isNativeOpenAIChatTarget(provider);
       let reasoningLog: AdapterRequest["reasoningLog"];
-      // ClinePass live requests observed 2026-08-02 require this gateway-specific object; the
-      // public API docs do not currently specify its request shape.
       if (!reasoningDisabled && provider.reasoningWireFormat === "gateway-object" && parsed.options.reasoning === "none") {
-        body.reasoning = { enabled: false };
-        reasoningLog = {
-          effectiveEffort: "none",
-          wireField: "reasoning.enabled",
-          wireValue: false,
-        };
-      } else if (reasoningEffort !== undefined) {
-        if (provider.reasoningWireFormat === "gateway-object") {
-          body.reasoning = { enabled: true, effort: reasoningEffort };
+        if (nativeOpenAI) {
+          body.reasoning_effort = "none";
           reasoningLog = {
-            effectiveEffort: reasoningEffort,
-            wireField: "reasoning.effort",
-            wireValue: reasoningEffort,
+            effectiveEffort: "none",
+            wireField: "reasoning_effort",
+            wireValue: "none",
           };
+        } else {
+          body.reasoning = { enabled: false };
+          reasoningLog = {
+            effectiveEffort: "none",
+            wireField: "reasoning.enabled",
+            wireValue: false,
+          };
+        }
+      } else if (reasoningEffort !== undefined) {
+        if (provider.reasoningWireFormat === "gateway-object") {
+          if (nativeOpenAI) {
+            body.reasoning_effort = reasoningEffort;
+            reasoningLog = {
+              effectiveEffort: reasoningEffort,
+              wireField: "reasoning_effort",
+              wireValue: reasoningEffort,
+            };
+          } else {
+            body.reasoning = { enabled: true, effort: reasoningEffort };
+            reasoningLog = {
+              effectiveEffort: reasoningEffort,
+              wireField: "reasoning.effort",
+              wireValue: reasoningEffort,
+            };
+          }
         } else if (modelInList(provider.thinkingBudgetModels, parsed.modelId)) {
           const budget = thinkingBudgetForEffort(parsed, reasoningEffort, maxTokens);
           if (budget !== undefined) {
@@ -788,9 +787,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
             };
           }
         } else if (modelInList(provider.thinkingToggleModels, parsed.modelId)) {
-          // Vendor thinking-toggle wire: the mapped value is sent as `thinking: {type}` because
-          // these models ignore/reject reasoning_effort. Most use enabled/disabled; MiniMax-M3
-          // uses adaptive/disabled.
           if (reasoningEffort === "enabled" || reasoningEffort === "disabled" || reasoningEffort === "adaptive") {
             body.thinking = { type: reasoningEffort };
             reasoningLog = {
@@ -814,17 +810,9 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       if (parsed.options.frequencyPenalty !== undefined && !modelInList(provider.noPenaltyModels, parsed.modelId)) {
         body.frequency_penalty = parsed.options.frequencyPenalty;
       }
-      // prompt_cache_key is an OpenAI-specific chat extension; strict backends (Groq,
-      // Cerebras, etc.) reject unknown fields. Only forward when the provider opts in.
       if (provider.promptCacheKey && parsed.options.promptCacheKey !== undefined) {
         body.prompt_cache_key = parsed.options.promptCacheKey;
       }
-      // Responses `text.format` -> chat `response_format`. json_object maps 1:1; json_schema
-      // re-nests the flattened Responses fields under `json_schema` — the exact inverse of
-      // responseFormatToText in src/chat/inbound.ts. Forwarded unconditionally (like `stop`):
-      // response_format is a first-class Chat Completions field, it is only present when the
-      // caller explicitly asked for structured output, and a backend that rejects it should
-      // fail loud rather than silently return prose the caller will try to JSON.parse.
       const textFormat = parsed.options.textFormat;
       if (textFormat?.type === "json_object") {
         body.response_format = { type: "json_object" };
@@ -841,30 +829,25 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       }
 
       if (tools) {
-        // Default-ON for chat-completions providers (user decision 260709): the buffered
-        // parser assembles multi-call streams safely, so `parallelToolCalls: false` is the
-        // only per-provider opt-out; Codex's request bit can still force false per request.
-        // Rationale + provider evidence: devlog/_plan/260709_parallel_tool_calls.
-        body.parallel_tool_calls = provider.parallelToolCalls === false
-          ? false
-          : parsed.options.parallelToolCalls !== false;
-      }
-      if (parsed.stream) {
-        body.stream_options = { include_usage: true };
+        if (provider.parallelToolCalls === false) {
+          // NIM documents the Boolean defaulting to false and kimi rejects true; pin the
+          // wire bit so Codex cannot opt in via request.options. Other opted-out providers
+          // omit the field so strict OpenAI-compatible hosts never see an unsupported knob.
+          if (provider.baseUrl === "https://integrate.api.nvidia.com/v1") {
+            body.parallel_tool_calls = false;
+          }
+        } else if (provider.parallelToolCalls === true) {
+          body.parallel_tool_calls = parsed.options.parallelToolCalls !== false;
+        }
       }
+      if (parsed.stream) body.stream_options = { include_usage: true };
 
       const url = `${provider.baseUrl}/chat/completions`;
       const headers: Record<string, string> = { "Content-Type": "application/json" };
-      // Precedence preserved from pre-#128 behavior: apiKey Authorization first, then
-      // provider.headers may override (user/registry-configured headers win). Registry
-      // staticHeaders (e.g. opencode-free x-opencode-client) flow in via derive.ts and
-      // never carry Authorization, so keyless providers are unaffected.
       if (hasCredential) headers["Authorization"] = `Bearer ${provider.apiKey}`;
       if (provider.headers) Object.assign(headers, provider.headers);
 
       const bodyJson = JSON.stringify(body);
-      // Never log pathname/query — tenant-scoped hosts (e.g. Cloudflare
-      // /accounts/<account_id>/ai/v1) would otherwise leak account identifiers (#452).
       if (isDebugEnabled()) {
         let host = "upstream";
         try { host = new URL(url).host; } catch { /* keep fallback */ }
@@ -899,14 +882,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       const budgetEncoder = new TextEncoder();
       let buffer = "";
       let bufferBytes = 0;
-      // Streamed tool calls are BUFFERED until a terminal signal, then flushed as atomic
-      // start/delta/end sequences. The bridge treats text/reasoning deltas as barriers that
-      // close an open tool-call item (bridge.ts closeCurrentToolCall on text_delta), so
-      // emitting calls incrementally would orphan later argument deltas whenever a provider
-      // interleaves content — and parallel tool calls (multiple ids, index-keyed continuation
-      // chunks, whole-chunk calls) cannot be represented live without overlapping sequences.
-      // Keyed by `index` (OpenAI wire standard), falling back to `id`, falling back to the
-      // last-seen call for providers that omit both on continuation chunks.
       interface PendingToolCall { key: string; id: string; name: string; args: string; argsBytes: number }
       const pendingToolCalls: PendingToolCall[] = [];
       let toolCallSeq = 0;
@@ -917,8 +892,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         return calls;
       };
       const flushToolCalls = function* (): Generator<AdapterEvent> {
-        // Do not treat flushed tool calls as user-facing output for the finish-less EOF
-        // fallback — incomplete tool args must stay on the truncation path.
         for (const call of closeToolCalls()) {
           if (!call.id) call.id = `call_${++toolCallSeq}`;
           yield { type: "tool_call_start", id: call.id, name: call.name };
@@ -934,25 +907,13 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         return "terminate";
       };
       let pendingUsage: OcxUsage | undefined;
-      // Track terminal signals so a socket EOF without any terminator can fail closed instead of
-      // being reported as a clean completion (silent truncation). A graceful close is either an
-      // explicit `[DONE]` sentinel OR a chunk carrying a non-null `finish_reason` (some
-      // OpenAI-compatible providers omit `[DONE]` but do send finish_reason).
       let finishReason: string | undefined;
-      // Only answer text enables the finish-less EOF fallback. Reasoning-only streams can be
-      // suppressed by hideThinkingSummary and must not complete as empty successful turns.
       let sawUserFacingOutput = false;
 
-      // Single per-line handler shared by the streaming loop and the EOF residual-frame flush, so
-      // a final frame is parsed identically wherever it lands (no duplicated, drift-prone parsing).
-      // Yields adapter events and returns "terminate" for a terminal frame ([DONE] / error) that
-      // must end the stream, or "continue" otherwise. Mutates the closure's terminal-signal state.
       const handleDataLine = function* (line: string): Generator<AdapterEvent, "continue" | "terminate"> {
         const rawPayload = sseFieldValue(line, "data");
         if (rawPayload === null) return "continue";
         const payload = rawPayload.trim();
-        // A bare `data:` line carries nothing (heartbeat-style keep-alive on some gateways);
-        // it is not a malformed frame, just nothing to parse.
         if (payload.length === 0) return "continue";
         if (payload === "[DONE]") {
           yield* flushToolCalls();
@@ -968,42 +929,20 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           yield { type: "error", message: "malformed upstream SSE data frame" };
           return "terminate";
         }
-        // Validate the shape instead of asserting it. `JSON.parse` yields a value, not necessarily
-        // an object — `JSON.parse("null")` returns null without throwing, so the catch above never
-        // sees it and the `chunk.error` read below crashed the stream mid-flight.
-        //
-        // Skip rather than terminate: `data: null` is emitted as a benign padding frame BETWEEN
-        // content deltas by real OpenAI-compatible routes (issue #1219), so failing here would
-        // discard the finish_reason chunk and [DONE] still in flight and turn a healthy response
-        // into a failed turn. Skipping cannot mask a genuinely broken stream — a stream carrying
-        // only such frames still sets neither finishReason nor sawUserFacingOutput and so trips
-        // the EOF truncation guard below. An unparseable frame stays terminal.
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-          return "continue";
-        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return "continue";
         const chunk = parsed as Record<string, unknown>;
 
-        // A 200/OK chat-completions stream may carry an inline provider error envelope
-        // instead of a clean [DONE]. Surface it as a terminal error so the bridge emits a
-        // classified response.failed (bridge case "error") — never a truncated completion.
         if (chunk.error !== undefined && chunk.error !== null) {
           const event = upstreamErrorEvent(chunk.error, pendingUsage);
           debugProviderDiagnostic("openai-chat", "stream-error", { message: event.message });
           return yield* terminateWithError(event);
         }
 
-        if (chunk.usage) {
-          // Record usage but keep parsing: some providers send usage and the final content
-          // delta in the SAME chunk; a bail here would drop that content. The choices
-          // guard below no-ops a usage-only chunk.
-          pendingUsage = usageFromOpenAIChat(chunk.usage as Record<string, unknown>);
-        }
+        if (chunk.usage) pendingUsage = usageFromOpenAIChat(chunk.usage as Record<string, unknown>);
 
         const choices = chunk.choices;
         if (choices === undefined) return "continue";
-        if (!Array.isArray(choices)) {
-          return yield* terminateWithError(invalidChoicesEvent(pendingUsage));
-        }
+        if (!Array.isArray(choices)) return yield* terminateWithError(invalidChoicesEvent(pendingUsage));
         if (choices.length === 0) return "continue";
         const rawChoice = choices[0];
         if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
@@ -1019,34 +958,39 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           debugProviderDiagnostic("openai-chat", "stream-error", { message: event.message });
           return yield* terminateWithError(event);
         }
-        // Observe the terminator BEFORE the delta guard: a finish-only chunk (finish_reason set,
-        // no delta) is a graceful close and must record finishReason even though we skip it below.
-        if (typeof choice.finish_reason === "string" && choice.finish_reason) {
-          finishReason = choice.finish_reason;
-        }
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) finishReason = choice.finish_reason;
         const delta = choice.delta;
         if (delta) {
           const reasoningText = reasoningTextFrom(delta);
-          if (reasoningText !== undefined) {
-            yield { type: "reasoning_raw_delta", text: reasoningText };
-          }
+          if (reasoningText !== undefined) yield { type: "reasoning_raw_delta", text: reasoningText };
           if (typeof delta.content === "string" && delta.content.length > 0) {
             sawUserFacingOutput = true;
             yield { type: "text_delta", text: delta.content };
           }
 
-          const toolCalls = delta.tool_calls as { index?: number; id?: string; function?: { name?: string; arguments?: string } }[] | undefined;
-          if (toolCalls) {
-            for (const tc of toolCalls) {
+          const rawToolCalls = delta.tool_calls;
+          if (rawToolCalls !== undefined) {
+            // A claimed tool-call payload is not benign padding. Dropping it can leave the
+            // matching result permanently orphaned, so malformed nested shapes fail closed
+            // through the adapter error channel instead of escaping as TypeError (#1325).
+            if (!Array.isArray(rawToolCalls)) {
+              return yield* terminateWithError(invalidToolCallsEvent(pendingUsage));
+            }
+            for (const rawToolCall of rawToolCalls) {
+              if (!isRecord(rawToolCall)) {
+                return yield* terminateWithError(invalidToolCallsEvent(pendingUsage));
+              }
+              const tc = rawToolCall as {
+                index?: number;
+                id?: string;
+                function?: { name?: string; arguments?: string };
+              };
               const key = typeof tc.index === "number"
                 ? `i:${tc.index}`
                 : tc.id
-                ? `id:${tc.id}`
-                : pendingToolCalls[pendingToolCalls.length - 1]?.key;
+                  ? `id:${tc.id}`
+                  : pendingToolCalls[pendingToolCalls.length - 1]?.key;
               let call = key !== undefined ? pendingToolCalls.find(c => c.key === key) : undefined;
-              // Mixed keying rescue: a call opened under an index key must still absorb an
-              // id-only continuation for the same provider id (and vice versa) instead of
-              // splitting into two calls that share one call_id downstream.
               if (!call && tc.id) call = pendingToolCalls.find(c => c.id === tc.id);
               if (!call) {
                 call = { key: key ?? `seq:${pendingToolCalls.length}`, id: "", name: "", args: "", argsBytes: 0 };
@@ -1074,11 +1018,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           }
         }
 
-        // Any non-empty finish_reason ends the generation: flush assembled tool calls as
-        // atomic sequences (covers "tool_calls" AND providers that close tool turns with "stop").
-        if (typeof choice.finish_reason === "string" && choice.finish_reason) {
-          yield* flushToolCalls();
-        }
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) yield* flushToolCalls();
         return "continue";
       };
 
@@ -1117,21 +1057,9 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           }
         }
 
-        // Some providers send the terminal `data:` frame (carrying the final delta, finish_reason,
-        // and/or usage) WITHOUT a trailing newline before closing the socket, so it never crosses
-        // the split("\n") boundary and stays in `buffer`. Run it through the SAME handler so its
-        // content/tool-calls are emitted and its terminal signal observed — otherwise a genuinely
-        // complete stream loses its last frame and may be falsely failed below.
         if (buffer.length > 0) {
           if ((yield* handleDataLine(buffer)) === "terminate") return;
         }
-        // Reader EOF. Prefer failing closed before flushing pending tool calls so the bridge
-        // never sees a fabricated tool_call_end on a truncated mid-assembly stream.
-        //
-        // Checked BEFORE flushToolCalls(), because that helper emits tool_call_end and there is no
-        // taking it back: a half-assembled argument string would reach the client as a completed
-        // call. Tool calls are buffered here (unlike the Anthropic adapter, which forwards
-        // fragments live), so this adapter can still decide.
         const sawFinish = finishReason !== undefined;
         if (!sawFinish && pendingToolCalls.length > 0) {
           debugProviderDiagnostic("openai-chat", "stream-truncated", {
@@ -1142,9 +1070,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           yield { type: "error", message: "upstream stream ended mid tool call without a terminal signal — possible truncation" };
           return;
         }
-        // Finish-less EOF is only safe when answer text was emitted. Reasoning-only / usage-only
-        // truncations must stay on the error path (hideThinkingSummary can suppress reasoning).
-        // Trailing usage alone is not a terminal signal for this adapter (#735 / restore #773).
         if (!sawFinish && !sawUserFacingOutput) {
           debugProviderDiagnostic("openai-chat", "stream-truncated", {
             finishReason: finishReason ?? null,
@@ -1154,7 +1079,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           return;
         }
         yield* flushToolCalls();
-        // Graceful close that omitted [DONE] but delivered finish_reason and/or answer text.
         const stopReason = stopReasonFor(finishReason);
         yield { type: "done", usage: pendingUsage, ...(stopReason ? { stopReason } : {}) };
       } catch (error) {
@@ -1183,60 +1107,64 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       const responseBytes = new TextEncoder().encode(JSON.stringify(json)).byteLength;
       budget.chargeRetained(responseBytes, { kind: "retained_collectors" });
       try {
-      const payload = unwrapChatCompletionPayload(json);
-      const usage = usageFromOpenAIChat(payload.usage as Record<string, unknown> | undefined);
-      if (json.success === false && payload.error === undefined) {
-        return [{
-          type: "error",
-          message: "upstream reported failure without an error payload",
-          ...(usage ? { usage } : {}),
-        }];
-      }
-      if (payload.error !== undefined && payload.error !== null) {
-        return [upstreamErrorEvent(payload.error, usage)];
-      }
-
-      const events: AdapterEvent[] = [];
-      const choices = payload.choices as {
-        message?: Record<string, unknown>;
-        finish_reason?: unknown;
-        error?: OpenAIChatError;
-      }[] | undefined;
-      if (!Array.isArray(choices) || choices.length === 0) {
-        return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
-      }
-      const rawChoice = choices[0];
-      if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
-        return [invalidChoicesEvent(usage)];
-      }
-      const choice = rawChoice;
-      if (choice.finish_reason === "error") return [upstreamErrorEvent(choice.error, usage)];
-      if (!choice.message) return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
-
-      const msg = choice.message;
-      const reasoningText = reasoningTextFrom(msg);
-      if (reasoningText !== undefined) {
-        events.push({ type: "reasoning_raw_delta", text: reasoningText });
-      }
-      if (typeof msg.content === "string") {
-        events.push({ type: "text_delta", text: msg.content });
-      }
-      const toolCalls = msg.tool_calls as { id: string; function: { name: string; arguments: string } }[] | undefined;
-      if (toolCalls) {
-        for (const tc of toolCalls) {
-          events.push({ type: "tool_call_start", id: tc.id, name: tc.function.name });
-          events.push({ type: "tool_call_delta", arguments: tc.function.arguments });
-          events.push({ type: "tool_call_end" });
+        const payload = unwrapChatCompletionPayload(json);
+        const usage = usageFromOpenAIChat(payload.usage as Record<string, unknown> | undefined);
+        if (json.success === false && payload.error === undefined) {
+          return [{
+            type: "error",
+            message: "upstream reported failure without an error payload",
+            ...(usage ? { usage } : {}),
+          }];
         }
-      }
-      const stopReason = stopReasonFor(choice.finish_reason);
-      events.push({
-        type: "done",
-        usage,
-        ...(stopReason ? { stopReason } : {}),
-      });
-      retainTranslatedEventBatch(events, budget);
-      return events;
+        if (payload.error !== undefined && payload.error !== null) return [upstreamErrorEvent(payload.error, usage)];
+
+        const events: AdapterEvent[] = [];
+        const choices = payload.choices as {
+          message?: Record<string, unknown>;
+          finish_reason?: unknown;
+          error?: OpenAIChatError;
+        }[] | undefined;
+        if (!Array.isArray(choices) || choices.length === 0) {
+          return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
+        }
+        const rawChoice = choices[0];
+        if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
+          return [invalidChoicesEvent(usage)];
+        }
+        const choice = rawChoice;
+        if (choice.finish_reason === "error") return [upstreamErrorEvent(choice.error, usage)];
+        if (!choice.message) return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
+
+        const msg = choice.message;
+        const reasoningText = reasoningTextFrom(msg);
+        if (reasoningText !== undefined) events.push({ type: "reasoning_raw_delta", text: reasoningText });
+        if (typeof msg.content === "string") events.push({ type: "text_delta", text: msg.content });
+        const rawToolCalls = msg.tool_calls;
+        if (rawToolCalls !== undefined) {
+          if (!Array.isArray(rawToolCalls)) return [invalidToolCallsEvent(usage)];
+          for (const rawToolCall of rawToolCalls) {
+            if (!isRecord(rawToolCall) || !isRecord(rawToolCall.function)) {
+              return [invalidToolCallsEvent(usage)];
+            }
+            const id = rawToolCall.id;
+            const name = rawToolCall.function.name;
+            const args = rawToolCall.function.arguments;
+            if (typeof id !== "string" || typeof name !== "string" || typeof args !== "string") {
+              return [invalidToolCallsEvent(usage)];
+            }
+            events.push({ type: "tool_call_start", id, name });
+            events.push({ type: "tool_call_delta", arguments: args });
+            events.push({ type: "tool_call_end" });
+          }
+        }
+        const stopReason = stopReasonFor(choice.finish_reason);
+        events.push({
+          type: "done",
+          usage,
+          ...(stopReason ? { stopReason } : {}),
+        });
+        retainTranslatedEventBatch(events, budget);
+        return events;
       } finally {
         budget.releaseRetained(responseBytes, { kind: "retained_collectors" });
       }