@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/adapters/devin.ts

@@ -192,6 +192,35 @@ async function resolveWireModelUid(
  */
 export const resolveWireModelUidForTests = resolveWireModelUid;
 
+const positiveTokenCount = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+
+/**
+ * Read a per-model token count for the exact UID selected for this turn.
+ *
+ * Tries the selected UID and then its collapsed base id, preferring the
+ * canonical spelling and accepting dotted or case-folded saved hints — the same
+ * normalization the inference request applies to the model id. Where several
+ * spellings match one id, the smallest wins: a ceiling stated twice is
+ * satisfied by the lower statement.
+ */
+function devinModelTokenHint(
+  record: Record<string, number> | undefined,
+  modelUid: string,
+): number | undefined {
+  if (!record) return undefined;
+  for (const id of [modelUid, collapseDevinModelUid(modelUid)]) {
+    const exact = Object.hasOwn(record, id) ? positiveTokenCount(record[id]) : undefined;
+    if (exact !== undefined) return exact;
+    const matches = Object.entries(record)
+      .filter(([key]) => normalizeDevinModelId(key).toLowerCase() === id.toLowerCase())
+      .map(([, value]) => positiveTokenCount(value))
+      .filter((value): value is number => value !== undefined);
+    if (matches.length > 0) return Math.min(...matches);
+  }
+  return undefined;
+}
+
 /**
  * Resolve the INPUT ceiling for the exact UID selected for this turn. Catalog
  * ClientModelConfig #18 and CompletionConfiguration #3 both carry input tokens;
@@ -204,33 +233,50 @@ function resolveDevinMaxInputTokens(
   modelUid: string,
   liveWindow?: number,
 ): number | undefined {
-  const positive = (value: unknown): number | undefined =>
-    typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
-  const baseId = collapseDevinModelUid(modelUid);
-  const configured = (record: Record<string, number> | undefined): number | undefined => {
-    if (!record) return undefined;
-    for (const id of [modelUid, baseId]) {
-      // Prefer the canonical spelling; retain dotted/case-folded saved hints,
-      // matching the model-id normalization used for the inference request.
-      const exact = Object.hasOwn(record, id) ? positive(record[id]) : undefined;
-      if (exact !== undefined) return exact;
-      const matches = Object.entries(record)
-        .filter(([key]) => normalizeDevinModelId(key).toLowerCase() === id.toLowerCase())
-        .map(([, value]) => positive(value))
-        .filter((value): value is number => value !== undefined);
-      if (matches.length > 0) return Math.min(...matches);
-    }
-    return undefined;
-  };
-  const contextHint = configured(provider.modelContextWindows) ?? positive(provider.contextWindow);
-  const inputHint = configured(provider.modelMaxInputTokens);
-  const ceilings = [positive(liveWindow), contextHint, inputHint]
+  const contextHint = devinModelTokenHint(provider.modelContextWindows, modelUid)
+    ?? positiveTokenCount(provider.contextWindow);
+  const inputHint = devinModelTokenHint(provider.modelMaxInputTokens, modelUid);
+  const ceilings = [positiveTokenCount(liveWindow), contextHint, inputHint]
     .filter((value): value is number => value !== undefined);
   return ceilings.length > 0 ? Math.min(...ceilings) : undefined;
 }
 
-/** Pure test seam; runtime uses the same resolver immediately before dispatch. */
+/**
+ * Resolve the OUTPUT ceiling for this turn, highest authority first:
+ *
+ * 1. the caller's explicit `max_output_tokens`, forwarded unchanged — an
+ *    explicit cap is a request, so a small one is never widened into a
+ *    configured larger one;
+ * 2. the configured per-model cap (`modelMaxOutputTokens`), read through the
+ *    same UID-aware hint lookup the input ceiling uses;
+ * 3. the provider-wide `defaultMaxOutputTokens`;
+ * 4. undefined, which leaves the cloud-direct encoder's own 8192 fallback in
+ *    place for a provider that configured nothing.
+ *
+ * This is NOT the history ceiling, and the two must not collapse into one
+ * number. CompletionConfiguration #2 is the output cap and #3 is the context
+ * window, so feeding a context window into this resolver would ask Cognition to
+ * generate a whole window's worth of output. Nothing here reads
+ * `contextWindow` or `modelContextWindows` for that reason.
+ *
+ * Step 1 keeps the caller's raw value rather than `positiveTokenCount`: the
+ * inbound parser owns what a caller may send, and re-filtering here would
+ * silently promote a rejected value to a configured cap the caller never asked
+ * for.
+ */
+function resolveDevinMaxOutputTokens(
+  provider: OcxProviderConfig,
+  modelUid: string,
+  requested: number | undefined,
+): number | undefined {
+  if (typeof requested === "number") return requested;
+  return devinModelTokenHint(provider.modelMaxOutputTokens, modelUid)
+    ?? positiveTokenCount(provider.defaultMaxOutputTokens);
+}
+
+/** Pure test seams; runtime uses the same resolvers immediately before dispatch. */
 export const resolveDevinMaxInputTokensForTests = resolveDevinMaxInputTokens;
+export const resolveDevinMaxOutputTokensForTests = resolveDevinMaxOutputTokens;
 
 export class DevinMissingCredentialError extends Error {
   constructor() {
@@ -285,6 +331,9 @@ function mapOcxContentToWire(content: string | OcxContentPart[] | undefined): st
   for (const part of content) {
     if (part.type === "text" && part.text) {
       out.push({ type: "text", text: part.text });
+    } else if (part.type === "document") {
+      // No Devin document field; the marker keeps the turn from disappearing entirely.
+      out.push({ type: "text", text: part.text });
     } else if (part.type === "image") {
       const m = part.imageUrl.match(/^data:([^;]+);base64,(.+)$/);
       if (m) out.push({ type: "image", mimeType: m[1]!, base64Data: m[2]! });
@@ -590,6 +639,9 @@ export function createDevinAdapter(
         const maxInputTokens = resolveDevinMaxInputTokens(
           provider, modelUid, catalog?.byUid.get(modelUid)?.contextWindow,
         );
+        const maxOutputTokens = resolveDevinMaxOutputTokens(
+          provider, modelUid, parsed.options.maxOutputTokens,
+        );
         // The reset-retry wrapper waits out a 429 that states its own recovery
         // delay ("limit will reset in 35 seconds") and replays the identical
         // request — but only while zero events have been yielded, so a
@@ -606,7 +658,7 @@ export function createDevinAdapter(
           // input hint used to force every model through the 128k default.
           completionOpts: {
             ...(maxInputTokens !== undefined ? { maxInputTokens } : {}),
-            ...(typeof parsed.options.maxOutputTokens === "number" ? { maxOutputTokens: parsed.options.maxOutputTokens } : {}),
+            ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
             ...(typeof parsed.options.temperature === "number" ? { temperature: parsed.options.temperature } : {}),
             ...(typeof parsed.options.topP === "number" ? { topP: parsed.options.topP } : {}),
           },

package/src/adapters/google-antigravity-wire.ts

@@ -45,8 +45,11 @@ function firstUserText(parsed: OcxParsedRequest): string | undefined {
   for (const msg of parsed.context.messages) {
     if (msg.role !== "user") continue;
     if (typeof msg.content === "string") return msg.content;
-    const first = (msg.content as OcxContentPart[]).find(p => p.type === "text" && typeof p.text === "string");
-    if (first && first.type === "text") return first.text;
+    // A document part carries text too: ignoring it left a document-only opening turn with no
+    // anchor, which silently downgrades the deterministic session id to a random one.
+    const first = (msg.content as OcxContentPart[])
+      .find(p => (p.type === "text" || p.type === "document") && typeof p.text === "string");
+    if (first && (first.type === "text" || first.type === "document")) return first.text;
   }
   return undefined;
 }

package/src/adapters/google-errors.ts

@@ -66,7 +66,13 @@ function classifyGoogle(label: string, status: number | undefined, enumStatus: s
   if (status === 401 || enumStatus === "UNAUTHENTICATED" || lower.includes("unauthenticated") || lower.includes("invalid authentication") || lower.includes("expired")) {
     return `${label} authentication failed`;
   }
-  if (status === 403 || enumStatus === "PERMISSION_DENIED" || lower.includes("permission_denied") || lower.includes("permission denied") || lower.includes("access denied")) {
+  // Keep Google's explicit enum in the normalized text. Responses/combo handling receives
+  // only this string, so dropping it would let location wording override the authoritative
+  // permission reason during downstream classification.
+  if (enumStatus === "PERMISSION_DENIED") {
+    return `${label} access denied (PERMISSION_DENIED)`;
+  }
+  if (status === 403 || lower.includes("permission_denied") || lower.includes("permission denied") || lower.includes("access denied")) {
     return `${label} access denied`;
   }
   // Google rejects unsupported geographic / datacenter locations with HTTP 400

package/src/adapters/google.ts

@@ -15,6 +15,7 @@ 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";
@@ -346,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);
@@ -465,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 => ({
@@ -478,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: {

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;
+}