@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/adapters/google.ts

@@ -1,5 +1,5 @@
 import type { AdapterFetchContext, AdapterRequest, ProviderAdapter } from "./base";
-import { debugDroppedFrame } from "../lib/debug";
+import { debugDroppedFrame, debugProviderDiagnosticLazy } from "../lib/debug";
 import { createToolCallIdAllocator } from "./tool-call-id";
 import { createImageBudget, materializeInlineImage, MAX_ENCODED_BYTES_PER_IMAGE, artifactHttpUrl } from "../images/artifacts";
 import type {
@@ -15,13 +15,16 @@ import type {
   OcxUsage,
 } from "../types";
 import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
+import type { OcxTool } from "../types";
 import { contentPartsToText, parseDataUrl } from "./image";
 import { getVertexAccessToken } from "../lib/gcp-adc";
 import { fetchAntigravityWithRetry, fetchVertexWithRetry } from "./google-http";
 import { safeAntigravityHttpErrorMessage, safeVertexHttpErrorMessage } from "./google-errors";
 import { isVertexTruncatedTurn, vertexTruncationErrorMessage } from "./google-truncation";
-import { ANTIGRAVITY_REQUEST_UA, antigravitySessionId, isLikelyRealThoughtSignature, sanitizeAntigravityClaudeSignatures } from "./google-antigravity-wire";
+import { ANTIGRAVITY_REQUEST_UA, antigravitySessionAnchor, antigravitySessionId, isLikelyRealThoughtSignature, sanitizeAntigravityClaudeSignatures } from "./google-antigravity-wire";
+import { summarizeGoogleWireShape } from "./google-wire-shape";
 import { compileGoogleWireBody } from "./google-wire-compiler";
+import type { GoogleToolSchemaLossReport, GoogleToolSchemaProfile } from "./google-tool-schema";
 import { identifyRoutedModel } from "./identity";
 import {
   antigravityUsesReplayCache,
@@ -344,6 +347,13 @@ function messagesToGeminiFormat(
               parts.push(data ? { inline_data: { mime_type: data.mediaType, data: data.base64 } } : { text: `[video: ${p.videoUrl}]` });
               continue;
             }
+            if (p.type === "document") {
+              // Gemini takes document bytes through the same inline_data part as images and
+              // video. The marker on the part is the fallback for wires without one, not this
+              // wire's best effort (#5212).
+              parts.push({ inline_data: { mime_type: p.mediaType, data: p.data } });
+              continue;
+            }
             // Drop empty/malformed text instead of emitting `{ text: "" }` or a bare `{}` part.
             const textPart = geminiTextPart(p.text);
             if (textPart) parts.push(textPart);
@@ -463,9 +473,7 @@ function messagesToGeminiFormat(
 
 function toolsToGeminiFormat(parsed: OcxParsedRequest): unknown[] | undefined {
   if (!parsed.context.tools?.length) return undefined;
-  const tools = isAllowedToolChoice(parsed.options.toolChoice)
-    ? parsed.context.tools.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools))
-    : parsed.context.tools;
+  const tools = advertisedGeminiTools(parsed);
   if (tools.length === 0) return undefined;
   return [{
     functionDeclarations: tools.map(t => ({
@@ -476,19 +484,37 @@ function toolsToGeminiFormat(parsed: OcxParsedRequest): unknown[] | undefined {
   }];
 }
 
+/** The declarations this request actually advertises, after any allowed-tools filter. */
+function advertisedGeminiTools(parsed: OcxParsedRequest): readonly OcxTool[] {
+  const declared = parsed.context.tools ?? [];
+  return isAllowedToolChoice(parsed.options.toolChoice)
+    ? declared.filter(toolChoiceToolPredicate(parsed.options.toolChoice, declared))
+    : declared;
+}
+
 /**
  * Client tool_choice enforcement on the wire. The catalog nudge states the same contract in
  * prose, but without functionCallingConfig the model is free to ignore it. "auto" stays absent
  * so the common case is byte-identical. The allowedTools variant already filters the
  * declarations in toolsToGeminiFormat; only its "required" half needs a wire mode.
+ *
+ * A caller that declares strict tools is asking for its argument schemas to be enforced, and
+ * Gemini expresses that as VALIDATED. The mode existed and was plumbed end to end, but was only
+ * ever reachable by matching a model name, so a strict declaration arrived as an ordinary
+ * unvalidated AUTO turn and the response looked the same either way (#5210). VALIDATED replaces
+ * AUTO only: ANY and NONE are stronger constraints the caller asked for explicitly, and
+ * overwriting either of them would lose the choice this function exists to enforce.
  */
 function toolChoiceToGeminiToolConfig(parsed: OcxParsedRequest): Record<string, unknown> | undefined {
   const choice = parsed.options.toolChoice;
-  if (!choice || choice === "auto") return undefined;
+  const validated = advertisedGeminiTools(parsed).some(t => t.strict === true)
+    ? { functionCallingConfig: { mode: "VALIDATED" } }
+    : undefined;
+  if (!choice || choice === "auto") return validated;
   if (choice === "none") return { functionCallingConfig: { mode: "NONE" } };
   if (choice === "required") return { functionCallingConfig: { mode: "ANY" } };
   if (isAllowedToolChoice(choice)) {
-    return choice.mode === "required" ? { functionCallingConfig: { mode: "ANY" } } : undefined;
+    return choice.mode === "required" ? { functionCallingConfig: { mode: "ANY" } } : validated;
   }
   return {
     functionCallingConfig: {
@@ -737,6 +763,14 @@ function invalidGoogleShapeEvent(
 }
 
 export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapter {
+  const toolSchemaPolicy = provider.googleToolSchemaPolicy ?? "compatible";
+  const toolSchemaProfile = {
+    endpointClass: provider.googleMode ?? "ai-studio",
+  } satisfies GoogleToolSchemaProfile;
+  const reportToolSchemaLoss = (report: GoogleToolSchemaLossReport): void => {
+    if (!report.lossy && report.uncertainComparisons === 0) return;
+    debugProviderDiagnosticLazy("google", "google-tool-schema-loss", () => ({ ...report }));
+  };
   // Per-request closure: resolveAdapter builds a fresh adapter per request (server.ts), so buildRequest
   // can stash the CCA model/session for parseStream's reasoning-replay observation.
   let antigravityModel: string | undefined;
@@ -799,7 +833,11 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
     ...(provider.googleMode === "vertex" || provider.googleMode === "cloud-code-assist"
       ? {
           fetchResponse: (request: AdapterRequest, ctx?: AdapterFetchContext): Promise<Response> =>
-            (provider.googleMode === "cloud-code-assist" ? fetchAntigravityWithRetry : fetchVertexWithRetry)(request, ctx),
+            (provider.googleMode === "cloud-code-assist" ? fetchAntigravityWithRetry : fetchVertexWithRetry)(
+              request,
+              ctx,
+              { toolSchemaProfile, toolSchemaPolicy },
+            ),
           formatErrorBody: (status: number, _headers: Headers, payloadText: string): string =>
             (provider.googleMode === "cloud-code-assist" ? safeAntigravityHttpErrorMessage : safeVertexHttpErrorMessage)(status, payloadText),
         }
@@ -970,7 +1008,8 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
           const fcc = (existing.functionCallingConfig ?? {}) as Record<string, unknown>;
           draftRequest.toolConfig = { ...existing, functionCallingConfig: { ...fcc, mode: "VALIDATED" } };
         }
-        const compiled = compileGoogleWireBody(draftRequest);
+        const compiled = compileGoogleWireBody(draftRequest, toolSchemaProfile, toolSchemaPolicy);
+        reportToolSchemaLoss(compiled.toolSchemaLossReport);
         const request = compiled.body;
         restoreGoogleToolName = compiled.restoreToolName;
         // Compile names before replay: signatures are keyed by the exact provider-visible name.
@@ -989,6 +1028,20 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
           // Vertex and AI Studio share one decision. A second check here would append a
           // duplicate nudge whenever signature sanitization reshapes the tail afterwards.
         }
+        // Opt-in structural description of the request that is about to leave (#5008).
+        //
+        // Passed as a BUILDER, not a value: the lazy form gates before invoking it, so a session
+        // with provider debug off never pays the walk, and it evaluates the projection inside its
+        // own try/catch, so a throw in here cannot turn a built request into a rejected one. The
+        // projection only reads `request`, so the bytes below are the same either way.
+        debugProviderDiagnosticLazy("google", "antigravity-wire-shape", () => summarizeGoogleWireShape(request, {
+          sessionAnchor: antigravitySessionAnchor(parsed),
+          // Signed at translation time, from client history or the durable store. The
+          // Antigravity session cache signs afterwards, inside applyAntigravityReplay, and the
+          // projection attributes that remainder to the cache rather than to this count.
+          historySignedCalls: replayedCallIds.length,
+          replayScopeBound: parsed._reasoningReplayScope !== undefined,
+        }));
         const envelope = {
           model: wireModelId,
           // The envelope's `userAgent` field is a protocol constant ("antigravity"), distinct from
@@ -1006,7 +1059,8 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
       }
 
       if (provider.googleMode === "vertex") {
-        const compiled = compileGoogleWireBody(body);
+        const compiled = compileGoogleWireBody(body, toolSchemaProfile, toolSchemaPolicy);
+        reportToolSchemaLoss(compiled.toolSchemaLossReport);
         restoreGoogleToolName = compiled.restoreToolName;
         const vertexProject = provider.project || process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT || "api-key";
         const vertexLocation = provider.location || process.env.GOOGLE_CLOUD_LOCATION || "global";
@@ -1052,7 +1106,8 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
       if (!apiKey) throw new Error("google (AI Studio) requires a non-empty API key");
       headers["x-goog-api-key"] = apiKey;
 
-      const compiled = compileGoogleWireBody(body);
+      const compiled = compileGoogleWireBody(body, toolSchemaProfile, toolSchemaPolicy);
+      reportToolSchemaLoss(compiled.toolSchemaLossReport);
       restoreGoogleToolName = compiled.restoreToolName;
       return { url, method: "POST", headers, body: JSON.stringify(compiled.body) };
     },

package/src/adapters/image.ts

@@ -18,6 +18,9 @@ export function parseDataUrl(url: string): { mediaType: string; base64: string }
  */
 export function contentPartsToText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
-  const text = content.map(p => p.type === "text" ? p.text : p.type === "image" ? "[image]" : "[video]").join("");
+  // A document carries its own marker, so this wire states the attachment instead of
+  // mislabelling it as a video.
+  const text = content.map(p =>
+    p.type === "text" || p.type === "document" ? p.text : p.type === "image" ? "[image]" : "[video]").join("");
   return text || "[image]";
 }

package/src/adapters/input-media-guard.ts

@@ -1,31 +1,45 @@
 import type { ProviderAdapter } from "./base";
 import { untranslatedInputMediaMessage, untranslatedResponsesInputMedia } from "../responses/input-media";
+import { unrepresentableDeclaration } from "./declaration-carrier";
+import type { AdapterWire } from "./registry";
+import type { OcxParsedRequest } from "../types";
 
 /**
  * Refuse unrepresentable input at the final translated-adapter boundary. The registry
  * applies this after wire resolution; Responses passthrough (including Azure) opts
  * out because it uses the original body rather than the lossy normalized content.
+ *
+ * Two of the three checks are wire-scoped, and that is the point. A constraint the normalized
+ * request CAN carry — a caller restriction on a tool, an attached document's bytes — still has
+ * to reach a wire that can express it. Leaving that to each adapter means an adapter that never
+ * learned about the carrier rebuilds without it and answers normally, so the allowlist in
+ * `declaration-carrier.ts` is default-deny and this is the one place every registered adapter
+ * passes through.
  */
-export function withInputMediaGuard<T extends ProviderAdapter>(adapter: T): T {
+export function withInputMediaGuard<T extends ProviderAdapter>(adapter: T, wire: AdapterWire): T {
+  const refusal = (parsed: OcxParsedRequest): string | undefined => {
+    const kind = untranslatedResponsesInputMedia(parsed._rawBody);
+    return kind ? untranslatedInputMediaMessage(kind) : unrepresentableDeclaration(parsed, wire);
+  };
   const build = adapter.buildRequest.bind(adapter);
   adapter.buildRequest = (parsed, incoming) => {
-    const kind = untranslatedResponsesInputMedia(parsed._rawBody);
-    if (kind) throw new Error(untranslatedInputMediaMessage(kind));
+    const message = refusal(parsed);
+    if (message) throw new Error(message);
     return build(parsed, incoming);
   };
 
   const runTurn = adapter.runTurn?.bind(adapter);
   if (runTurn) {
     adapter.runTurn = async (parsed, incoming, emit) => {
-      const kind = untranslatedResponsesInputMedia(parsed._rawBody);
-      if (kind) {
+      const message = refusal(parsed);
+      if (message) {
         emit({
           type: "error",
           status: 400,
           errorType: "invalid_request_error",
           code: "unsupported_input_modality",
           retryable: false,
-          message: untranslatedInputMediaMessage(kind),
+          message,
         });
         return;
       }
@@ -37,9 +51,7 @@ export function withInputMediaGuard<T extends ProviderAdapter>(adapter: T): T {
   if (localTerminal) {
     // This hook is outside the builder's error catch. Decline its success shortcut;
     // the ordinary buildRequest path then returns the established client-safe 400.
-    adapter.localTerminal = parsed => untranslatedResponsesInputMedia(parsed._rawBody)
-      ? undefined
-      : localTerminal(parsed);
+    adapter.localTerminal = parsed => refusal(parsed) ? undefined : localTerminal(parsed);
   }
   return adapter;
 }

package/src/adapters/kiro/usage.ts

@@ -12,14 +12,15 @@ import type { KiroHistoryEntry } from "./wire";
 
 export function userContentText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
-  return content.map(p => (p.type === "text" ? p.text : "")).filter(Boolean).join("\n");
+  // A document carries its own marker: dropping it built an empty user turn that Kiro rejects.
+  return content.map(p => (p.type === "text" || p.type === "document" ? p.text : "")).filter(Boolean).join("\n");
 }
 
 export function usageContentText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
   return content
     .map(p => {
-      if (p.type === "text") return p.text;
+      if (p.type === "text" || p.type === "document") return p.text;
       if (p.type === "image") return `[image:${p.detail ?? "auto"}]`;
       return "";
     })

package/src/adapters/kiro-tool-fallback.ts

@@ -9,7 +9,7 @@ function contentText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
   return content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "image") return `[image:${part.detail ?? "auto"}]`;
       return "";
     })

package/src/adapters/ollama-native.ts

@@ -262,6 +262,12 @@ function contentToNative(
       text += part.text;
       continue;
     }
+    // No Ollama document carrier: keep the marker rather than falling through to the image
+    // branch below, which would read a nonexistent imageUrl.
+    if (part.type === "document") {
+      text += part.text;
+      continue;
+    }
     // Ollama's native /api/chat message shape carries `images: string[]` and has no video
     // counterpart, so a video part is refused rather than silently dropped or mis-sent as an image.
     if (part.type === "video") throw new Error(`ollama-native cannot send video content in ${label}`);

package/src/adapters/openai-chat/developer-role.ts

@@ -0,0 +1,61 @@
+import type { OcxProviderConfig } from "../../types";
+
+/**
+ * The role a `developer` message carries on the Chat wire, decided in one place for both the
+ * translated adapter and the native passthrough.
+ *
+ * `developer` belongs to the Chat Completions role set, but not every OpenAI-compatible gateway
+ * accepts it: one that does not answers `400 role 'developer' is not allowed` and the turn never
+ * starts. #5213 removed a hostname test that decided the role, which was right — a gateway
+ * proxying OpenAI accepts the role and the hostname cannot say so.
+ *
+ * `foldDeveloperRoleToSystem` is tri-state and only two of its states say anything about the
+ * destination: `true` records an upstream known to reject the role, `false` one known to accept
+ * it, and absent means nobody has recorded either. Returning `undefined` for the absent state
+ * instead of a role keeps the recorded fact separate from the default a route applies to
+ * silence, which is what lets the native route honour the first without inheriting the second.
+ *
+ * This decides the role and only the role. Which slot the message occupies is the caller's
+ * decision and must not change with this value.
+ */
+export function explicitChatDeveloperWireRole(
+  provider: OcxProviderConfig,
+): "developer" | "system" | undefined {
+  if (provider.foldDeveloperRoleToSystem === undefined) return undefined;
+  return provider.foldDeveloperRoleToSystem ? "system" : "developer";
+}
+
+/**
+ * The translated route's role: the recorded one, or `system` when nothing is recorded.
+ *
+ * The unrecorded state folds because the two mistakes are not symmetrical. Sending `developer`
+ * to a destination that rejects it fails the request outside this repository, where no test here
+ * can reach it; sending `system` to one that would have accepted `developer` costs the role name
+ * and nothing else.
+ */
+export function translatedChatDeveloperWireRole(provider: OcxProviderConfig): "developer" | "system" {
+  return explicitChatDeveloperWireRole(provider) ?? "system";
+}
+
+/**
+ * Apply a recorded role to a caller-supplied `messages` array, leaving every other field of
+ * every message, and the order of all of them, exactly as they arrived.
+ *
+ * The native route forwards the caller's messages verbatim, so an operator who recorded that a
+ * destination rejects the role still sent `developer` there and the turn failed upstream with a
+ * 400. Only an explicit record changes anything here: with the key unset, or set to the role the
+ * message already carries, the same array reference is returned and the wire is byte-identical
+ * to the one the caller sent.
+ */
+export function applyExplicitChatDeveloperRole(messages: unknown, provider: OcxProviderConfig): unknown {
+  const role = explicitChatDeveloperWireRole(provider);
+  if (role === undefined || role === "developer" || !Array.isArray(messages)) return messages;
+  let rewritten = false;
+  const applied = messages.map(message => {
+    if (typeof message !== "object" || message === null || Array.isArray(message)) return message;
+    if ((message as { role?: unknown }).role !== "developer") return message;
+    rewritten = true;
+    return { ...(message as Record<string, unknown>), role };
+  });
+  return rewritten ? applied : messages;
+}

package/src/adapters/openai-chat/messages.ts

@@ -1,13 +1,14 @@
 import { isNativeOpenAIChatTarget, stripBracketedModelSuffix } from "./wire";
 import { reasoningDetailSegmentForWire } from "./response-events";
+import { translatedChatDeveloperWireRole } from "./developer-role";
 import { isVolcengineArkPaygChatTarget } from "./tool-schema";
 import { contentPartsToText } from "../image";
 import { EMPTY_TOOL_OUTPUT_ANNOTATION, isWhitespaceOnlyTextPartArray } from "../empty-tool-output-annotation";
 import { identifyRoutedModel } from "../identity";
 import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "../tool-catalog-nudge";
-import { registryEntryForProviderDestination } from "../../providers/registry";
 import { peekReasoningForCall } from "../../responses/reasoning-replay-cache";
-import type { OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall } from "../../types";
+import { inlineDocumentDataUrl } from "../../responses/inline-document";
+import type { OcxAssistantMessage, OcxContentPart, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall } from "../../types";
 import { modelInList, namespacedToolName } from "../../types";
 
 /**
@@ -21,13 +22,6 @@ import { modelInList, namespacedToolName } from "../../types";
  */
 const VIDEO_UNSUPPORTED_MARKER = "[video omitted: the translated Chat route has no video mapping]";
 
-export function developerSystemText(message: OcxMessage): string | undefined {
-  if (message.role !== "developer") return undefined;
-  if (typeof message.content === "string") return message.content;
-  if (message.content.some(part => part.type === "image")) return undefined;
-  return message.content.map(part => (part as OcxTextContent).text).join("");
-}
-
 /**
  * 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
@@ -121,21 +115,26 @@ export function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProv
   };
 
   const nativeOpenAI = isNativeOpenAIChatTarget(provider);
-  // Hoisting a newly appended reminder rewrites the reusable prompt prefix.
-  // Keep this compatibility exception on the destination/model tested with OCG.
-  const chronologicalSystem = parsed.modelId === "deepseek-v4.1-flash"
-    && registryEntryForProviderDestination(provider)?.id === "opencode-go";
+  // Which role a developer message carries, and why the unrecorded state folds, is stated once
+  // in ./developer-role.ts and read from there by the native passthrough as well. Either way the
+  // message keeps the slot it arrived in — only the role changes, never the position.
+  const developerWireRole = translatedChatDeveloperWireRole(provider);
+  // A developer message keeps the slot it arrived in. Hoisting its text into the leading
+  // system block moved a mid-conversation instruction ahead of every turn it was written to
+  // follow, and the caller saw an ordinary answer either way (#5213). The Claude inbound mints
+  // chronological developer items for exactly this reason (#4161), so the two halves of the
+  // route were working against each other on every host but api.openai.com. Placement is now
+  // uniform; which ROLE that slot carries is decided separately below.
+  //
+  // One destination already had the chronological behaviour, keyed to a model and a registry
+  // id, because hoisting a newly appended reminder rewrites the reusable prompt prefix. That is
+  // a property of prompt-prefix caching rather than of that destination, and it is now what
+  // every destination gets.
   const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
     ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
     : undefined;
-  const developerSystemParts = nativeOpenAI || chronologicalSystem
-    ? []
-    : 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) {
@@ -152,20 +151,23 @@ export function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProv
       case "developer": {
         const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
         const hasImages = parts?.some(p => p.type === "image") ?? false;
+        // A document has a structured counterpart on this wire, so it needs the parts array for
+        // the same reason an image does: flattening it to a string would drop the bytes.
+        const hasStructured = hasImages || (parts?.some(p => p.type === "document") ?? false);
         let chatMsg: Record<string, unknown>;
-        if (msg.role === "developer" && !hasImages) {
-          if (!nativeOpenAI && !chronologicalSystem) break;
+        if (msg.role === "developer" && !hasStructured) {
           const text = typeof msg.content === "string"
             ? msg.content
             : parts!.map(p => (p as OcxTextContent).text).join("");
-          // A non-text timeline part (video, for example) serializes to nothing here.
-          // The generic path drops such a message; the chronological exception must not
-          // turn it into an empty system message that some upstreams reject.
+          // A non-text timeline part (video, for example) serializes to nothing here. The
+          // generic user path drops such a message, and emitting a content-free system
+          // message instead is rejected by some upstreams. Native OpenAI keeps its existing
+          // empty-developer wire, which is a separate question from placement.
           if (!nativeOpenAI && text.length === 0) break;
-          chatMsg = { role: nativeOpenAI ? "developer" : "system", content: text };
+          chatMsg = { role: developerWireRole, content: text };
         } else if (typeof msg.content === "string") {
           chatMsg = { role: "user", content: msg.content };
-        } else if (!hasImages) {
+        } else if (!hasStructured) {
           // A video part has no `text`, so joining it produced "" and the whole message
           // was dropped: a video-only or text-plus-video turn vanished silently. OpenAI's
           // Chat Completions wire has no video content part, so state the omission
@@ -183,13 +185,30 @@ export function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProv
             if (p.type === "image") {
               return { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } };
             }
+            // Chat Completions carries an attached document as a file part with inline bytes,
+            // the direct counterpart of the Anthropic document block the caller sent.
+            if (p.type === "document") {
+              return {
+                type: "file",
+                file: {
+                  file_data: inlineDocumentDataUrl(p),
+                  ...(p.filename !== undefined ? { filename: p.filename } : {}),
+                },
+              };
+            }
             // Previously this produced { type: "text", text: undefined } for a video
             // part — a malformed part, worse than a drop because it can fail upstream
             // schema validation.
             if (p.type === "video") return { type: "text", text: VIDEO_UNSUPPORTED_MARKER };
             return { type: "text", text: (p as OcxTextContent).text };
           });
-          chatMsg = { role: "user", content: chatParts };
+          // A developer message with images keeps the user-compatible shape it has always had on
+          // this wire. One carrying only a document has no such precedent, and demoting it would
+          // undo the role this adapter just finished preserving.
+          chatMsg = {
+            role: msg.role === "developer" && !hasImages ? developerWireRole : "user",
+            content: chatParts,
+          };
         }
         if (pendingToolCalls.length > 0) deferredBarrierMessages.push(chatMsg);
         else out.push(chatMsg);

package/src/adapters/openai-chat/parallel-tool-calls.ts

@@ -0,0 +1,32 @@
+import type { OcxProviderConfig } from "../../types";
+
+/**
+ * The `parallel_tool_calls` value for a translated Chat request, or `undefined` to omit the key.
+ *
+ * A provider has three states here, not two, and the third is the default for every provider that
+ * never configured the knob. While the call site only branched on the two configured states, a
+ * caller's own explicit `parallel_tool_calls: false` reached the parser, was carried on
+ * `options.parallelToolCalls`, and was then dropped on the way to the wire — the upstream stayed
+ * free to emit concurrent calls and the response looked entirely normal (#5211).
+ *
+ * Only an explicit request-side `false` is forwarded in the unset state. `true` is already the
+ * upstream default, so emitting it would introduce the knob to strict OpenAI-compatible hosts
+ * that have never had to accept it, which is the reason the configured opt-out below omits the
+ * key rather than sending `false`.
+ */
+export function chatParallelToolCallsWireValue(
+  provider: OcxProviderConfig,
+  requested: boolean | undefined,
+): boolean | undefined {
+  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, but a
+    // self-hosted gateway that DOES honor it and keeps emitting parallel calls without it can opt
+    // in via pinParallelToolCallsFalse.
+    const pinned = provider.baseUrl === "https://integrate.api.nvidia.com/v1"
+      || provider.pinParallelToolCallsFalse === true;
+    return pinned ? false : undefined;
+  }
+  if (provider.parallelToolCalls === true) return requested !== false;
+  return requested === false ? false : undefined;
+}

package/src/adapters/openai-chat/passthrough.ts

@@ -1,6 +1,7 @@
 import { openAIChatTransport, stripBracketedModelSuffix } from "./wire";
 import type { AdapterRequest } from "../base";
 import { frameAgentRouterMessages } from "../agentrouter";
+import { applyExplicitChatDeveloperRole } from "./developer-role";
 import { openRouterProviderPayload, resolveOpenRouterRouting } from "../../providers/openrouter-routing";
 import { resolveVercelGatewayRouting, vercelGatewayProviderPayload } from "../../providers/vercel-gateway-routing";
 import { fastPolicyForModel } from "../../providers/service-tier";
@@ -9,6 +10,8 @@ import { debugProviderDiagnostic } from "../../lib/debug";
 import { isDebugEnabled } from "../../lib/debug-settings";
 import { modelRecordValue } from "../../reasoning-effort";
 import { modelInList, type OcxProviderConfig } from "../../types";
+import { chatParallelToolCallsWireValue } from "./parallel-tool-calls";
+import { applyExplicitChatReasoningWirePolicy } from "./reasoning-wire";
 
 const CHAT_PASSTHROUGH_FIELDS = [
   "audio",
@@ -54,16 +57,37 @@ export function buildOpenAIChatPassthroughRequest(
 
   const body: Record<string, unknown> = {
     model: provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(modelId) : modelId,
-    messages: frameAgentRouterMessages(provider.baseUrl, rawBody.messages),
+    // The caller's messages are forwarded as they arrived, with one exception: an operator who
+    // recorded that this destination rejects the `developer` role gets that role converted in
+    // place. Verbatim was not neutral there — it sent the role anyway and the turn failed
+    // upstream with a 400 before the model saw it. An unrecorded destination is still verbatim,
+    // and the conversion changes the role of those messages and nothing else, so the position
+    // of every message and every other field survive unchanged.
+    messages: applyExplicitChatDeveloperRole(
+      frameAgentRouterMessages(provider.baseUrl, rawBody.messages),
+      provider,
+    ),
     stream,
   };
   for (const field of CHAT_PASSTHROUGH_FIELDS) {
     if (rawBody[field] !== undefined) body[field] = rawBody[field];
   }
   const rawEfforts = modelRecordValue(provider.modelReasoningEfforts, modelId) ?? provider.reasoningEfforts;
-  if (modelInList(provider.noReasoningModels, modelId) || rawEfforts?.length === 0) {
+  const reasoningDisabled = modelInList(provider.noReasoningModels, modelId) || rawEfforts?.length === 0;
+  if (reasoningDisabled) {
     delete body.reasoning_effort;
   }
+  const hasTools = Array.isArray(rawBody.tools) && rawBody.tools.length > 0;
+  const requestedEffort = typeof body.reasoning_effort === "string" ? body.reasoning_effort : undefined;
+  applyExplicitChatReasoningWirePolicy({
+    provider,
+    modelId,
+    hasTools,
+    requestedEffort,
+    wireEffort: requestedEffort,
+    reasoningDisabled,
+    body,
+  });
 
   const openRouterRouting = resolveOpenRouterRouting(provider, modelId);
   if (openRouterRouting) body.provider = openRouterProviderPayload(openRouterRouting);
@@ -107,13 +131,13 @@ export function buildOpenAIChatPassthroughRequest(
   if (provider.promptCacheKey && rawBody.prompt_cache_key !== undefined) {
     body.prompt_cache_key = rawBody.prompt_cache_key;
   }
-  if (Array.isArray(rawBody.tools) && rawBody.tools.length > 0) {
-    if (provider.parallelToolCalls === true) {
-      body.parallel_tool_calls = rawBody.parallel_tool_calls !== false;
-    } else if (provider.parallelToolCalls === false
-        && (provider.baseUrl === "https://integrate.api.nvidia.com/v1" || provider.pinParallelToolCallsFalse === true)) {
-      body.parallel_tool_calls = false;
-    }
+  if (hasTools) {
+    // Same three provider states as the translated path, and the same defect in the unset one:
+    // a caller's explicit false was dropped here too (#5211). The native route reads the bit off
+    // the raw request rather than the parsed options, since nothing projects this body.
+    const requested = typeof rawBody.parallel_tool_calls === "boolean" ? rawBody.parallel_tool_calls : undefined;
+    const parallelToolCalls = chatParallelToolCallsWireValue(provider, requested);
+    if (parallelToolCalls !== undefined) body.parallel_tool_calls = parallelToolCalls;
   }
   if (stream) {
     const callerOptions = rawBody.stream_options !== null