@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/chat/inbound.ts

@@ -92,11 +92,32 @@ function userContentToBlocks(content: unknown): Rec[] {
       continue;
     }
     const videoUrl = videoUrlFromPart(raw);
-    if (videoUrl) blocks.push({ type: "input_video", video_url: videoUrl });
+    if (videoUrl) {
+      blocks.push({ type: "input_video", video_url: videoUrl });
+      continue;
+    }
+    const file = fileFromPart(raw);
+    if (file) blocks.push(file);
   }
   return blocks;
 }
 
+/**
+ * A Chat Completions `file` part carrying inline bytes, as the Responses `input_file` block.
+ *
+ * Nothing here recognized the shape, so the part reached the end of the loop with no branch and
+ * was dropped in silence (#5212). A part with no inline bytes is still not translatable and is
+ * left to the untranslated-media refusal, which runs before this loop.
+ */
+function fileFromPart(part: Rec): Rec | null {
+  if (part.type !== "file" && part.type !== "input_file") return null;
+  const file = isRec(part.file) ? part.file : part;
+  const fileData = file.file_data;
+  if (typeof fileData !== "string" || fileData.length === 0) return null;
+  const filename = typeof file.filename === "string" && file.filename.length > 0 ? file.filename : undefined;
+  return { type: "input_file", file_data: fileData, ...(filename ? { filename } : {}) };
+}
+
 /**
  * The assistant's prior thinking, as plaintext, from either Chat spelling.
  *
@@ -146,7 +167,27 @@ function pushSystemText(parts: string[], content: unknown): void {
   if (text) parts.push(text);
 }
 
-function toolCallsToItems(toolCalls: unknown, input: Rec[], knownNameByCallId: Map<string, string>): void {
+/**
+ * A mid-conversation instruction, as the input item the rest of the pipeline already reads.
+ *
+ * The role is `developer` rather than `system` for two reasons that both bite. The native
+ * ChatGPT backend refuses a `role:"system"` item inside `input`, and canonical forwarding
+ * folds every message-shaped `system` item back onto `instructions`
+ * (src/adapters/openai-responses/canonical-forward.ts), which would undo the placement one hop
+ * later. `developer` is first-class in responsesRequestSchema, survives parseRequest as a
+ * chronological conversation message, and is exactly what src/claude/inbound.ts already emits
+ * for the same shape.
+ */
+function developerInstructionItem(text: string): Rec {
+  return { type: "message", role: "developer", content: [{ type: "input_text", text }] };
+}
+
+function toolCallsToItems(
+  toolCalls: unknown,
+  input: Rec[],
+  knownNameByCallId: Map<string, string>,
+  awaitingToolResult: Set<string>,
+): void {
   if (!Array.isArray(toolCalls)) return;
   for (const raw of toolCalls) {
     if (!isRec(raw)) continue;
@@ -166,6 +207,7 @@ function toolCallsToItems(toolCalls: unknown, input: Rec[], knownNameByCallId: M
     if (!name) throw new ChatCompletionsRequestError("tool_calls entries require function.name");
     knownNameByCallId.set(callId, name);
     input.push({ type: "function_call", call_id: callId, name, arguments: args });
+    awaitingToolResult.add(callId);
   }
 }
 
@@ -218,11 +260,67 @@ function toolChoiceToResponses(choice: unknown, body: Rec): void {
     body.tool_choice = { type: "function", name };
     return;
   }
+  if (choice.type === "allowed_tools") {
+    body.tool_choice = allowedToolsChoiceToResponses(choice);
+    return;
+  }
   if (isRec(choice.function) && typeof choice.function.name === "string") {
     body.tool_choice = { type: "function", name: choice.function.name };
   }
 }
 
+/**
+ * Chat Completions nests the subset under `allowed_tools`, Responses carries `mode`/`tools`
+ * on the choice itself, and each entry names its tool under a member keyed by its own type
+ * (`{"type":"function","function":{"name"}}`) rather than a flat `name`. Neither level lines up
+ * with `mapToolChoice`, so an unflattened choice fell past every branch and the caller's subset
+ * was dropped while the full catalogue was still advertised (#5211).
+ *
+ * An entry nobody can name is refused rather than skipped: dropping one widens the very subset
+ * the caller sent this field to narrow.
+ */
+function allowedToolsChoiceToResponses(choice: Rec): Rec {
+  const spec = isRec(choice.allowed_tools) ? choice.allowed_tools : choice;
+  if (!Array.isArray(spec.tools) || spec.tools.length === 0) {
+    throw new ChatCompletionsRequestError("tool_choice.allowed_tools requires a non-empty tools array");
+  }
+  return {
+    type: "allowed_tools",
+    mode: spec.mode === "required" ? "required" : "auto",
+    tools: spec.tools.map(allowedToolEntryToResponses),
+  };
+}
+
+/** Hosted entries are named by their type alone; a function or custom entry must carry a name. */
+const HOSTED_ALLOWED_TOOL_TYPES = new Set([
+  "web_search",
+  "web_search_preview",
+  "image_generation",
+  "image_gen",
+  "tool_search",
+]);
+const NAMED_ALLOWED_TOOL_TYPES = new Set(["function", "custom"]);
+
+function allowedToolEntryToResponses(raw: unknown): Rec {
+  if (!isRec(raw)) {
+    throw new ChatCompletionsRequestError("tool_choice.allowed_tools.tools entries must be objects");
+  }
+  const type = typeof raw.type === "string" && raw.type.length > 0 ? raw.type : "function";
+  if (!NAMED_ALLOWED_TOOL_TYPES.has(type) && !HOSTED_ALLOWED_TOOL_TYPES.has(type)) {
+    // An unknown selector kind is not a narrower subset, it is a subset nobody can evaluate.
+    throw new ChatCompletionsRequestError(`unsupported tool_choice.allowed_tools.tools entry type: ${type}`);
+  }
+  const nested = isRec(raw[type]) ? raw[type] as Rec : undefined;
+  const name = typeof raw.name === "string" && raw.name.length > 0
+    ? raw.name
+    : nested !== undefined && typeof nested.name === "string" && nested.name.length > 0
+      ? nested.name
+      : undefined;
+  if (name !== undefined) return { type, name };
+  if (HOSTED_ALLOWED_TOOL_TYPES.has(type)) return { type };
+  throw new ChatCompletionsRequestError("tool_choice.allowed_tools.tools entries require a name");
+}
+
 function responseFormatToText(format: unknown): Rec | undefined {
   if (format === undefined) return undefined;
   if (!isRec(format)) throw new ChatCompletionsRequestError("response_format must be an object");
@@ -291,21 +389,54 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
   // Recover replace-style tool calls incrementally instead of rebuilding the
   // call-id index from the entire translated transcript for every message.
   const knownNameByCallId = new Map<string, string>();
+  // Tool calls whose result has not arrived yet. Several adapters need a call and its output
+  // to stay adjacent — Kiro refuses an interrupted pair (src/adapters/kiro/payload.ts) and the
+  // Anthropic and Google mappers synthesize a missing result — so an instruction that arrives
+  // inside an open batch waits for the batch to drain instead of splitting it.
+  const awaitingToolResult = new Set<string>();
+  const heldInstructions: string[] = [];
+  const releaseHeldInstructions = (): void => {
+    if (heldInstructions.length === 0) return;
+    input.push(developerInstructionItem(heldInstructions.join("\n\n")));
+    heldInstructions.length = 0;
+  };
+  // A user or assistant turn ends any open tool batch, so held text rejoins the timeline
+  // before that turn rather than drifting past it.
+  const beginConversationTurn = (): void => {
+    releaseHeldInstructions();
+    awaitingToolResult.clear();
+  };
 
   for (const msg of raw.messages) {
     if (!isRec(msg)) continue;
     const role = typeof msg.role === "string" ? msg.role : "";
     switch (role) {
       case "system":
-      case "developer":
-        pushSystemText(systemParts, msg.content);
+      case "developer": {
+        // A leading block is this request's instructions and keeps that treatment: it is the
+        // prompt head, and hoisting it is what the upstream prefix cache wants.
+        if (input.length === 0) {
+          pushSystemText(systemParts, msg.content);
+          break;
+        }
+        // Past the first turn the slot carries meaning. `U1 -> A1 -> D2 -> U2` says D2 applies
+        // to U2 and not to U1, and folding it into `instructions` moved it ahead of both while
+        // rewriting the prompt head on every turn that carried one. The outbound adapter has
+        // preserved this slot since #4161; the position was already gone by the time it ran.
+        const text = contentToText(msg.content).trim();
+        if (!text) break;
+        if (awaitingToolResult.size > 0) heldInstructions.push(text);
+        else input.push(developerInstructionItem(text));
         break;
+      }
       case "user": {
+        beginConversationTurn();
         const blocks = userContentToBlocks(msg.content);
         if (blocks.length > 0) input.push({ type: "message", role: "user", content: blocks });
         break;
       }
       case "assistant": {
+        beginConversationTurn();
         // A reasoning item precedes the assistant message it belongs to: the
         // Responses assistant item schema admits only output content blocks, so there
         // is no attachment point on the message itself, and the parser buffers a
@@ -328,7 +459,9 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
         }
         const blocks = assistantContentToBlocks(msg.content);
         if (blocks.length > 0) input.push({ type: "message", role: "assistant", content: blocks });
-        if (msg.tool_calls !== undefined) toolCallsToItems(msg.tool_calls, input, knownNameByCallId);
+        if (msg.tool_calls !== undefined) {
+          toolCallsToItems(msg.tool_calls, input, knownNameByCallId, awaitingToolResult);
+        }
         break;
       }
       case "function": {
@@ -351,12 +484,15 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
           ? blocks.filter(part => part.type === "input_text" || part.type === "input_image")
           : contentToText(msg.content);
         input.push({ type: "function_call_output", call_id: callId, output });
+        awaitingToolResult.delete(callId);
+        if (awaitingToolResult.size === 0) releaseHeldInstructions();
         break;
       }
       default:
         break;
     }
   }
+  releaseHeldInstructions();
 
   if (input.length === 0 && systemParts.length === 0) {
     throw new ChatCompletionsRequestError("messages must include at least one user/assistant/tool turn");

package/src/claude/desktop-3p.ts

@@ -473,6 +473,12 @@ export function removeDesktop3pStandardPivot(
   options: Desktop3pConfigLibraryOptions & {
     appliedFingerprint?: string | null; unlink?: (path: string) => void;
     lifecycleLockDeps?: ClientLifecycleLockDeps;
+    /**
+     * The desired-state guard below exists for OFF flows racing a concurrent enable. A
+     * mode switch (gateway → first-party) removes the profile while the integration stays
+     * ON on purpose, so the caller opts out of that guard.
+     */
+    replaceWhileEnabled?: boolean;
   } = {},
 ): Desktop3pRemovalResult {
   const libraryPath = resolveDesktop3pConfigLibraryPath(options);
@@ -488,7 +494,7 @@ export function removeDesktop3pStandardPivot(
       }
       const latest = readConfigDiagnostics();
       if (latest.source === "fallback") return { ok: false, changed: false, kind: "unsafe", libraryPath, reason: "desktop_config_invalid" };
-      if (claudeDesktopIntegrationEnabled(latest.config)) {
+      if (!options.replaceWhileEnabled && claudeDesktopIntegrationEnabled(latest.config)) {
         const observed = inspectDesktop3pConfigLibrary(options);
         if (observed.kind === "not_installed" || observed.kind === "no_owned_state") {
           return { ok: true, changed: false, kind: "noop", libraryPath };

package/src/claude/desktop-first-party.ts

@@ -0,0 +1,183 @@
+/**
+ * Claude Desktop first-party mode.
+ *
+ * Desktop has two ways to reach opencodex:
+ *
+ *   - `first-party` (default): the app keeps its ordinary claude.ai login, Chat tab, connectors
+ *     and remote control. Only the Claude Code process it spawns for the Code tab (and that
+ *     process's subagents) is redirected, through the `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` env
+ *     in `~/.claude/settings.json` (src/claude/intercept/settings.ts) and the server's intercept
+ *     pair (src/claude/intercept/runtime.ts). Nothing is written under Desktop's config library.
+ *   - `gateway`: the historical third-party deployment profile (src/claude/desktop-3p.ts). The
+ *     whole app is switched to a gateway build; picker entries are opencodex aliases.
+ *
+ * The two are mutually exclusive on disk: applying one removes the other. The mode is persisted
+ * in `claudeCode.desktopMode`; installs that predate the field but already carry an applied
+ * gateway profile keep `gateway` until they explicitly re-apply, so an update never flips a
+ * working Desktop under the operator.
+ */
+import { getConfigDir } from "../config/paths";
+import type { OcxConfig } from "../types";
+import { claudeInterceptCaCertPath, ensureLocalInterceptCa } from "./intercept/local-ca";
+import { claudeInterceptEnabled, claudeInterceptProxyPort } from "./intercept/runtime";
+import {
+  applyClaudeInterceptSettings,
+  buildClaudeInterceptEnv,
+  captureClaudeInterceptSettingsRollback,
+  inspectClaudeInterceptSettings,
+  removeClaudeInterceptSettings,
+  type ClaudeInterceptEnv,
+  type ClaudeInterceptSettingsState,
+  type ClaudeInterceptSettingsWrite,
+} from "./intercept/settings";
+
+export const CLAUDE_DESKTOP_MODES = ["first-party", "gateway"] as const;
+export type ClaudeDesktopMode = typeof CLAUDE_DESKTOP_MODES[number];
+export const DEFAULT_CLAUDE_DESKTOP_MODE: ClaudeDesktopMode = "first-party";
+
+export function isClaudeDesktopMode(value: unknown): value is ClaudeDesktopMode {
+  return typeof value === "string" && (CLAUDE_DESKTOP_MODES as readonly string[]).includes(value);
+}
+
+type DesktopModeConfig = Pick<OcxConfig, "claudeCode">;
+
+/**
+ * Effective Desktop mode. An explicit `claudeCode.desktopMode` wins; otherwise a persisted
+ * gateway apply marker (`desktopProfile.appliedFingerprint`) means a pre-existing gateway
+ * install and keeps `gateway`; everything else is the first-party default.
+ */
+export function resolveClaudeDesktopMode(config: DesktopModeConfig): ClaudeDesktopMode {
+  const explicit = config.claudeCode?.desktopMode;
+  if (isClaudeDesktopMode(explicit)) return explicit;
+  if (config.claudeCode?.desktopProfile?.appliedFingerprint) return "gateway";
+  return DEFAULT_CLAUDE_DESKTOP_MODE;
+}
+
+/**
+ * Config mutation that records the applied Desktop mode. Switching to first-party also drops
+ * the gateway apply marker: the profile assignments stay for a later gateway apply, but a
+ * stale `appliedFingerprint` must not make `resolveClaudeDesktopMode` read `gateway` again
+ * should the explicit marker ever go missing.
+ */
+export function recordClaudeDesktopMode(
+  config: DesktopModeConfig,
+  mode: ClaudeDesktopMode,
+): { changed: boolean; value: true } {
+  const claudeCode = config.claudeCode ?? {};
+  const profile = claudeCode.desktopProfile;
+  const dropMarker = mode === "first-party" && profile !== undefined
+    && (profile.appliedFingerprint !== undefined || profile.appliedAt !== undefined);
+  if (claudeCode.desktopMode === mode && !dropMarker) return { changed: false, value: true };
+  if (dropMarker) {
+    const { appliedFingerprint: _fingerprint, appliedAt: _at, ...rest } = profile;
+    config.claudeCode = { ...claudeCode, desktopMode: mode, desktopProfile: rest };
+  } else {
+    config.claudeCode = { ...claudeCode, desktopMode: mode };
+  }
+  return { changed: true, value: true };
+}
+
+/**
+ * Mode an *apply* without an explicit choice should use. The first-party default only holds
+ * where the intercept proxy actually runs; with it disabled (or on a client role) an implied
+ * first-party apply would point Claude Code at a proxy that never starts, so fall back to the
+ * gateway profile. An explicit `desktopMode: "first-party"` is still honoured (and refused
+ * later with `intercept_disabled`, which names the fix).
+ */
+export function resolveClaudeDesktopApplyMode(
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">,
+): ClaudeDesktopMode {
+  const resolved = resolveClaudeDesktopMode(config);
+  if (resolved === "gateway" || isClaudeDesktopMode(config.claudeCode?.desktopMode)) return resolved;
+  return claudeInterceptEnabled(config) ? "first-party" : "gateway";
+}
+
+export interface DesktopFirstPartyTarget {
+  proxyPort: number;
+  caCertPath: string;
+  env: ClaudeInterceptEnv;
+}
+
+/** The settings env a first-party apply on this machine writes (CA is created on demand). */
+export function desktopFirstPartyTarget(
+  config: Pick<OcxConfig, "claudeCode" | "port">,
+  opencodexConfigDir = getConfigDir(),
+): DesktopFirstPartyTarget {
+  const proxyPort = claudeInterceptProxyPort(config, config.port ?? 10100);
+  const caCertPath = claudeInterceptCaCertPath(opencodexConfigDir);
+  return { proxyPort, caCertPath, env: buildClaudeInterceptEnv(proxyPort, caCertPath) };
+}
+
+export interface DesktopFirstPartyInspection {
+  /** False when the server will not run the intercept pair (client role, intercept disabled). */
+  interceptEnabled: boolean;
+  proxyPort: number;
+  caCertPath: string;
+  settings: ClaudeInterceptSettingsState;
+  /** settings.json carries exactly the env the current config would write. */
+  applied: boolean;
+  /** Ours, but for an older port/config directory. Re-apply refreshes it. */
+  stale: boolean;
+}
+
+export interface DesktopFirstPartyOptions {
+  opencodexConfigDir?: string;
+  claudeConfigDir?: string;
+}
+
+/** Prepare rollback before replacing a gateway, without changing settings. */
+export function captureDesktopFirstPartyRollback(
+  config: Pick<OcxConfig, "claudeCode" | "port">,
+  options: DesktopFirstPartyOptions = {},
+): () => boolean {
+  return captureClaudeInterceptSettingsRollback(
+    desktopFirstPartyTarget(config, options.opencodexConfigDir).env, options.claudeConfigDir,
+  );
+}
+
+export function inspectDesktopFirstParty(
+  config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole">,
+  options: DesktopFirstPartyOptions = {},
+): DesktopFirstPartyInspection {
+  const target = desktopFirstPartyTarget(config, options.opencodexConfigDir);
+  const settings = inspectClaudeInterceptSettings(target.env, options.claudeConfigDir);
+  return {
+    interceptEnabled: claudeInterceptEnabled(config),
+    proxyPort: target.proxyPort,
+    caCertPath: target.caCertPath,
+    settings,
+    applied: settings.kind === "applied",
+    stale: settings.kind === "stale",
+  };
+}
+
+export type DesktopFirstPartyApplyResult =
+  | { ok: true; changed: boolean; path: string; env: ClaudeInterceptEnv; proxyPort: number }
+  | { ok: false; reason: "intercept_disabled" | "ca_unavailable" | "unreadable" | "foreign_env"; path: string };
+
+/**
+ * Write the first-party env into Claude Code's settings. Creates the local CA first so the
+ * path we point `NODE_EXTRA_CA_CERTS` at exists before Claude Code ever reads it.
+ */
+export function applyDesktopFirstParty(
+  config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole">,
+  options: DesktopFirstPartyOptions = {},
+): DesktopFirstPartyApplyResult {
+  const opencodexConfigDir = options.opencodexConfigDir ?? getConfigDir();
+  const target = desktopFirstPartyTarget(config, opencodexConfigDir);
+  if (!claudeInterceptEnabled(config)) return { ok: false, reason: "intercept_disabled", path: "" };
+  try {
+    ensureLocalInterceptCa(opencodexConfigDir);
+  } catch {
+    return { ok: false, reason: "ca_unavailable", path: target.caCertPath };
+  }
+  const written = applyClaudeInterceptSettings(target.env, options.claudeConfigDir);
+  if (!written.ok) return { ok: false, reason: written.reason, path: written.path };
+  return { ok: true, changed: written.changed, path: written.path, env: target.env, proxyPort: target.proxyPort };
+}
+
+/** Remove the first-party env. Only values anchored on our CA path are touched. */
+export function removeDesktopFirstParty(options: DesktopFirstPartyOptions = {}): ClaudeInterceptSettingsWrite {
+  const caCertPath = claudeInterceptCaCertPath(options.opencodexConfigDir ?? getConfigDir());
+  return removeClaudeInterceptSettings(caCertPath, options.claudeConfigDir);
+}

package/src/claude/desktop-gateway-state.ts

@@ -0,0 +1,41 @@
+import { mutatePersistedConfig } from "../config";
+import type { OcxConfig } from "../types";
+import { emptyDesktopProfile, type DesktopProfile } from "./desktop-profile";
+
+/** Record the bytes already committed by the gateway writer, before cleanup of
+ * the previous mode. Mode and fingerprint belong to one config transaction. */
+export function recordCommittedDesktopGateway(
+  config: Pick<OcxConfig, "claudeCode">,
+  profile: DesktopProfile | undefined,
+  fingerprint: string | undefined,
+  appliedAt: string,
+): void {
+  const { appliedFingerprint: _oldFingerprint, appliedAt: _oldTime, ...base } = profile ?? emptyDesktopProfile();
+  config.claudeCode = {
+    ...config.claudeCode,
+    desktopMode: "gateway",
+    desktopProfile: {
+      ...structuredClone(base),
+      ...(fingerprint ? { appliedFingerprint: fingerprint, appliedAt } : {}),
+    },
+  };
+}
+
+export function persistCommittedDesktopGateway(
+  snapshot: OcxConfig,
+  profile: DesktopProfile | undefined,
+  fingerprint: string | undefined,
+): { ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" | "unavailable" } {
+  const appliedAt = new Date().toISOString();
+  try {
+    const outcome = mutatePersistedConfig(current => {
+      recordCommittedDesktopGateway(current, profile, fingerprint, appliedAt);
+      return { changed: true, value: true };
+    });
+    if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
+    recordCommittedDesktopGateway(snapshot, profile, fingerprint, appliedAt);
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: "unavailable" };
+  }
+}

package/src/claude/inbound-content-options.ts

@@ -35,6 +35,12 @@ export function toolsToResponses(tools: unknown): Rec[] | undefined {
         // call, so carry the source intent instead of the destination default. A
         // non-boolean value is not a valid Anthropic opt-in and must not become one.
         strict: typeof raw.strict === "boolean" ? raw.strict : false,
+        // Anthropic restricts who may invoke a tool through allowed_callers. Nothing read it,
+        // so the restriction never reached the internal tool and every destination rebuilt the
+        // declaration without it while the request still succeeded (#5210).
+        ...(Array.isArray(raw.allowed_callers)
+          ? { allowed_callers: raw.allowed_callers.filter((c): c is string => typeof c === "string") }
+          : {}),
       });
       continue;
     }

package/src/claude/inbound.ts

@@ -19,6 +19,7 @@ import { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, f
 import { systemToInstructions, toolsToResponses, toolChoiceToResponses } from "./inbound-content-options";
 import { stabilizeClaudeInstructionsForPromptCache } from "./inbound-cache-stabilize";
 import { decodeReasoningEnvelope, encodeReasoningEnvelope, OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
+import { inlineDocumentMarker } from "../responses/inline-document";
 import { createTranslatorBudget, type TranslatorBudget } from "../lib/translator-budget";
 
 
@@ -41,6 +42,26 @@ function imageBlockToInputImage(block: Rec): Rec | null {
   return null;
 }
 
+function documentTitle(block: Rec): string | undefined {
+  return typeof block.title === "string" && block.title.length > 0 ? block.title : undefined;
+}
+
+/** An Anthropic base64 document as the Responses `input_file` block that carries its bytes. */
+function documentBlockToInputFile(block: Rec): Rec | null {
+  const source = block.source;
+  if (!isRec(source) || source.type !== "base64") return null;
+  const mediaType = typeof source.media_type === "string" && source.media_type.length > 0
+    ? source.media_type
+    : "application/octet-stream";
+  if (typeof source.data !== "string" || source.data.length === 0) return null;
+  const title = documentTitle(block);
+  return {
+    type: "input_file",
+    file_data: `data:${mediaType};base64,${source.data}`,
+    ...(title !== undefined ? { filename: title } : {}),
+  };
+}
+
 function toolResultOutput(block: Rec): string | Rec[] {
   const isError = block.is_error === true;
   const content = block.content;
@@ -55,9 +76,11 @@ function toolResultOutput(block: Rec): string | Rec[] {
         const img = imageBlockToInputImage(item);
         if (img) out.push(img);
       } else if (item.type === "document") {
-        // Same marker as the user-message document case below: the model should see the
-        // attachment happened instead of an empty tool output.
-        out.push({ type: "input_text", text: `[document${typeof item.title === "string" ? `: ${item.title}` : ""}]` });
+        // Tool output has no structured document carrier on this route — the Responses tool
+        // output vocabulary has no input_file block, and every adapter's tool-result path
+        // flattens to text — so this keeps the #939 marker. The user-message branch below is
+        // where bytes survive. Recorded as the remaining half of #5212.
+        out.push({ type: "input_text", text: inlineDocumentMarker(documentTitle(item)) });
       }
     }
     if (isError) out.unshift({ type: "input_text", text: "[tool error]" });
@@ -208,9 +231,12 @@ function userMessageToItems(content: unknown, input: Rec[], elide: SkillElisionC
         break;
       }
       case "document":
-        // No Responses equivalent for raw document blocks; surface the title so the
-        // model at least sees the attachment happened.
-        pending.push({ type: "input_text", text: `[document${typeof raw.title === "string" ? `: ${raw.title}` : ""}]` });
+        // A base64 document now rides the Responses input_file block, so a target with a
+        // counterpart receives the bytes instead of a sentence about them (#5212). Every other
+        // source is a reference this route cannot dereference, and keeps the marker #939
+        // introduced — which is also what a target with no document representation still sees.
+        pending.push(documentBlockToInputFile(raw)
+          ?? { type: "input_text", text: inlineDocumentMarker(documentTitle(raw)) });
         break;
       default:
         break; // thinking/redacted_thinking never appear in user messages; ignore unknowns