@bitkyc08/opencodex 2.7.39 → 2.7.40

package/src/adapters/cursor/tool-definitions.ts

@@ -1,27 +1,32 @@
 import { create, fromJson, toBinary, type JsonValue } from "@bufbuild/protobuf";
 import { ValueSchema } from "@bufbuild/protobuf/wkt";
 import type { OcxRequestOptions, OcxTool } from "../../types";
-import { namespacedToolName } from "../../types";
+import { namespacedToolName, toolChoiceAliases } from "../../types";
 import { McpToolDefinitionSchema, McpToolsSchema, type McpToolDefinition } from "./gen/agent_pb";
 
 export const OCX_RESPONSES_TOOL_PROVIDER = "opencodex-responses";
 export const CODEX_EXEC_COMMAND_TOOL = "exec_command";
+export const CODEX_SHELL_COMMAND_TOOL = "shell_command";
 export const CODEX_APPLY_PATCH_TOOL = "apply_patch";
 export const CURSOR_EXEC_COMMAND_TOOL = CODEX_EXEC_COMMAND_TOOL;
-export const CURSOR_SHELL_ALIAS_SYSTEM_NOTE = 'Shell commands use the `exec_command` tool with JSON arguments like {"cmd":"..."}.';
-export const CURSOR_SHELL_ALIAS_USER_HINT = "Use exec_command for this shell command.";
+export const CODEX_SHELL_BRIDGE_TOOL_NAMES = [CODEX_EXEC_COMMAND_TOOL, CODEX_SHELL_COMMAND_TOOL] as const;
+export const CURSOR_SHELL_ALIAS_SYSTEM_NOTE =
+  'Shell commands use the Codex shell bridge tool shown in this turn\'s catalog (`shell_command` or `exec_command`) with JSON arguments like {"cmd":"..."}. The long `mcp_opencodex-responses_*` display name is the same tool. Prefer it over Cursor-native Shell; never say native shell is blocked.';
+export const CURSOR_SHELL_ALIAS_USER_HINT =
+  "Use the Codex shell bridge tool listed this turn (`shell_command` or `exec_command`, including the long `mcp_opencodex-responses_*` name). Prefer that bridge over Cursor-native Shell/Read. Never say phrases like \"Native shell access is blocked\" or \"Shell access is blocked\" — silently use the bridge unless that bridge tool itself fails.";
 const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
 
 export const CURSOR_GENERIC_TOOL_USE_USER_HINT = [
-  "For generic tool-use/count demos, satisfy the request with repeated `exec_command` calls for harmless commands.",
-  "`exec_command` is the Codex Responses bridge exec tool exposed through Cursor's tool protocol; do not describe it as an external MCP server tool.",
+  "For generic tool-use/count demos, satisfy the request with repeated Codex shell bridge calls (`shell_command` or `exec_command`) for harmless commands.",
+  "`shell_command` / `exec_command` are the Codex Responses shell bridge exposed through Cursor's tool protocol; do not describe them as an external MCP server tool.",
   "Do not use `run_shell` unless this turn's tool catalog lists it.",
-  "A request for N tools means N separate `exec_command` invocations/results; never satisfy it with one chained shell command such as `cmd1 && cmd2`.",
-  "For independent read-only or output-only commands, emit all requested `exec_command` calls in the same response before waiting when the runtime supports parallel tool calls.",
+  "A request for N tools means N separate shell-bridge invocations/results; never satisfy it with one chained shell command such as `cmd1 && cmd2`.",
+  "For independent read-only or output-only commands, emit all requested shell-bridge calls in the same response before waiting when the runtime supports parallel tool calls.",
   "The Cursor bridge may suspend after the first returned bridge tool call, so emit sibling calls together before any result is needed.",
-  "If parallel emission is unavailable, continue with separate `exec_command` calls until the requested count has returned.",
+  "If parallel emission is unavailable, continue with separate shell-bridge calls until the requested count has returned.",
   "Do not use `tool_search`, external MCP, or resource discovery just to pad the count unless explicitly asked.",
   "Do not suggest or switch to neighboring-agent tools such as `Grep`, `Read`, `Glob`, `Bash`, or `LS` unless this turn's catalog lists those exact names.",
+  "Never tell the user that shell or read access is blocked, disabled, or denied unless the Codex shell bridge tool itself fails. Do not narrate Cursor-native Shell/Read routing.",
 ].join(" ");
 
 export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
@@ -38,8 +43,91 @@ export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
   additionalProperties: false,
 } as const;
 
+/**
+ * Responses/Codex-side schema used ONLY for arg-key normalization after Cursor returns a call.
+ * Cursor models are trained to emit `cmd`; Codex `shell_command` / `exec_command` validate
+ * `command`. Keeping `cmd` out of this schema lets `normalizeArgKeys` rewrite `cmd` → `command`.
+ */
+export const CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA = {
+  type: "object",
+  properties: {
+    command: { type: "string", description: "Shell command to execute." },
+    workdir: { type: "string", description: "Working directory for the command. Defaults to the turn cwd." },
+    shell: { type: "string", description: "Shell binary to launch. Defaults to the user's default shell." },
+    tty: { type: "boolean", description: "True allocates a PTY for the command; false or omitted uses plain pipes." },
+    yield_time_ms: { type: "number", description: "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms." },
+    max_output_tokens: { type: "number", description: "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy." },
+    max_output_chars: { type: "number", description: "Output character budget when the Responses tool uses chars instead of tokens." },
+  },
+  required: ["command"],
+} as const;
+
+export function isCodexShellBridgeToolName(name: string): boolean {
+  return (CODEX_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).includes(name);
+}
+
+/**
+ * Direct key lookup, then shell_command/exec_command sibling aliases when the key is a bridge name.
+ * Used for catalog admission, schema normalize maps, and Responses name maps (#399).
+ */
+export function resolveShellBridgeAliasKey<T>(
+  key: string,
+  lookup: (name: string) => T | undefined,
+): T | undefined {
+  const direct = lookup(key);
+  if (direct !== undefined) return direct;
+  if (!isCodexShellBridgeToolName(key)) return undefined;
+  for (const alias of CODEX_SHELL_BRIDGE_TOOL_NAMES) {
+    if (alias === key) continue;
+    const hit = lookup(alias);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+
+export function cursorToolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
+  const aliases = new Set(toolChoiceAliases(tool));
+  if (isBareCodexShellBridgeTool(tool)) {
+    for (const alias of CODEX_SHELL_BRIDGE_TOOL_NAMES) aliases.add(alias);
+  }
+  return [...aliases];
+}
+
+function catalogHasBareCodexShellBridge(
+  catalog: readonly Pick<OcxTool, "namespace" | "name">[],
+): boolean {
+  return catalog.some(isBareCodexShellBridgeTool);
+}
+
+/**
+ * Catalog-aware tool_choice matching for Cursor.
+ * When a bare Codex shell bridge is in the catalog, raw `shell_command` / `exec_command`
+ * choices select only that bridge (never a namespaced remote with the same raw name).
+ * When no bare bridge exists, raw bridge names may select a namespaced tool by raw name.
+ * Explicit wire names (`mcp__remote__exec_command`) always match the namespaced tool.
+ */
+function cursorToolChoiceMatches(
+  tool: Pick<OcxTool, "namespace" | "name">,
+  choiceName: string,
+  catalog: readonly Pick<OcxTool, "namespace" | "name">[],
+): boolean {
+  if (isCodexShellBridgeToolName(choiceName)) {
+    if (catalogHasBareCodexShellBridge(catalog)) {
+      return isBareCodexShellBridgeTool(tool);
+    }
+    return tool.name === choiceName || cursorToolWireName(tool) === choiceName;
+  }
+  if (tool.name === choiceName || cursorToolWireName(tool) === choiceName) return true;
+  return cursorToolChoiceAliases(tool).includes(choiceName);
+}
+
+export function isBareCodexShellBridgeTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
+  return !tool.namespace && isCodexShellBridgeToolName(tool.name);
+}
+
+/** @deprecated Prefer isBareCodexShellBridgeTool; kept for older call sites/tests. */
 function isBareCodexExecCommandTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
-  return !tool.namespace && tool.name === CODEX_EXEC_COMMAND_TOOL;
+  return isBareCodexShellBridgeTool(tool);
 }
 
 export function cursorRequestHasShellAlias(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined): boolean {
@@ -50,7 +138,8 @@ export function cursorRequestAdvertisesApplyPatch(
   tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
   toolChoice?: OcxRequestOptions["toolChoice"],
 ): boolean {
-  return tools?.some(tool => !tool.namespace && tool.name === CODEX_APPLY_PATCH_TOOL && tool.freeform === true && cursorToolAllowedByChoice(tool, toolChoice)) ?? false;
+  const catalog = tools ?? [];
+  return catalog.some(tool => !tool.namespace && tool.name === CODEX_APPLY_PATCH_TOOL && tool.freeform === true && cursorToolAllowedByChoice(tool, toolChoice, catalog));
 }
 
 export function cursorToolWireName(tool: Pick<OcxTool, "namespace" | "name">): string {
@@ -60,8 +149,9 @@ export function cursorToolWireName(tool: Pick<OcxTool, "namespace" | "name">): s
 /**
  * Cursor's harness shows MCP tools to the model as `mcp_<providerIdentifier>_<toolName>`; models
  * sometimes call that display name verbatim instead of the advertised short name (live 20:41/21:00
- * sessions: `mcp_opencodex-responses_exec_command`). Fold the display prefix back to the advertised
- * wire name so both spellings resolve to the same client tool instead of "unknown Responses tool".
+ * sessions: `mcp_opencodex-responses_exec_command` / `mcp_opencodex-responses_shell_command`).
+ * Fold the display prefix back to the advertised wire name, and treat `shell_command` /
+ * `exec_command` as the same Codex shell bridge, so alias thrash does not become "tool not found".
  */
 const CURSOR_MCP_DISPLAY_PREFIX = `mcp_${OCX_RESPONSES_TOOL_PROVIDER}_`;
 
@@ -71,15 +161,60 @@ export function normalizeCursorWireName(name: string): string {
 
 export function responsesToolNameFromCursorWire(name: string, cursorToolNameMap?: ReadonlyMap<string, string>): string {
   const normalized = normalizeCursorWireName(name);
-  return cursorToolNameMap?.get(normalized) ?? normalized;
+  if (!cursorToolNameMap) return normalized;
+  return resolveShellBridgeAliasKey(normalized, alias => cursorToolNameMap.get(alias)) ?? normalized;
 }
 
+/** Schema advertised to Cursor for this tool (may use Cursor-preferred field names like `cmd`). */
 export function cursorToolInputSchema(tool: OcxTool): unknown {
   return isBareCodexExecCommandTool(tool) ? CURSOR_EXEC_COMMAND_INPUT_SCHEMA : (tool.parameters ?? {});
 }
 
+/**
+ * Schema used to normalize completed Cursor tool args back to Responses/Codex field names.
+ * Must NOT reuse `cursorToolInputSchema` for the shell bridge: advertising `cmd` while also
+ * treating `cmd` as canonical prevents the `cmd` → `command` rewrite Codex requires (#399).
+ */
+export function cursorToolArgNormalizeSchema(tool: OcxTool): unknown {
+  if (isBareCodexShellBridgeTool(tool)) {
+    return shellBridgeArgNormalizeSchema(tool);
+  }
+  return tool.parameters ?? {};
+}
+
+function shellBridgeArgNormalizeSchema(tool: OcxTool): unknown {
+  const parameters = tool.parameters;
+  if (!parameters || typeof parameters !== "object") return CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA;
+  const base = parameters as Record<string, unknown>;
+  const rawProps = base.properties && typeof base.properties === "object"
+    ? { ...(base.properties as Record<string, unknown>) }
+    : {};
+  const required = Array.isArray(base.required) ? [...base.required as unknown[]] : [];
+  const requiresCommand = required.includes("command") || "command" in rawProps;
+  const requiresCmd = required.includes("cmd") || "cmd" in rawProps;
+  const shouldRewriteCmdToCommand = tool.name === CODEX_SHELL_COMMAND_TOOL || requiresCommand;
+
+  if (!shouldRewriteCmdToCommand && requiresCmd) {
+    return parameters;
+  }
+
+  // Drop Cursor-preferred aliases so normalizeArgKeys can rewrite them to Responses keys.
+  delete rawProps.cmd;
+  const properties = {
+    ...CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA.properties,
+    ...rawProps,
+    command: rawProps.command ?? CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA.properties.command,
+  };
+  return {
+    ...base,
+    type: "object",
+    properties,
+    required: requiresCommand ? required : ["command"],
+  };
+}
+
 function activeTextMentionsExecCommand(text: string): boolean {
-  return /\bexec_command\b/i.test(text);
+  return /\b(?:exec_command|shell_command)\b/i.test(text);
 }
 
 function looksLikeShellCommandRequest(text: string): boolean {
@@ -127,9 +262,9 @@ function cursorGenericToolUseHint(text: string): string {
   const count = requestedCursorToolUseCount(text);
   if (!count) return CURSOR_GENERIC_TOOL_USE_USER_HINT;
   return [
-    `This turn requests ${count} tool uses: emit exactly ${count} separate \`exec_command\` function calls/results.`,
-    `One \`exec_command\` containing chained commands counts as 1 tool call, not ${count}.`,
-    `Prefer one parallel tool-call batch containing all ${count} independent \`exec_command\` calls before waiting for results.`,
+    `This turn requests ${count} tool uses: emit exactly ${count} separate Codex shell bridge function calls/results (\`shell_command\` or \`exec_command\`).`,
+    `One shell-bridge call containing chained commands counts as 1 tool call, not ${count}.`,
+    `Prefer one parallel tool-call batch containing all ${count} independent shell-bridge calls before waiting for results.`,
     CURSOR_GENERIC_TOOL_USE_USER_HINT,
   ].join(" ");
 }
@@ -176,7 +311,8 @@ export function cursorToolsForActivePrompt<T extends Pick<OcxTool, "namespace" |
 ): readonly T[] | undefined {
   if (!shouldUseNativeExecOnlyForGenericToolUse(tools, activeText)) return tools;
   const execTools = tools?.filter(isBareCodexExecCommandTool);
-  if (execTools?.length && !execTools.some(tool => cursorToolAllowedByChoice(tool, toolChoice))) return tools;
+  const catalog = tools ?? [];
+  if (execTools?.length && !execTools.some(tool => cursorToolAllowedByChoice(tool, toolChoice, catalog))) return tools;
   return execTools && execTools.length > 0 ? execTools : tools;
 }
 
@@ -199,13 +335,17 @@ export function appendCursorShellAliasHint(
   return `${text}${text.endsWith("\n") ? "\n" : "\n\n"}${CURSOR_SHELL_ALIAS_USER_HINT}`;
 }
 
-export function cursorToolAllowedByChoice(tool: Pick<OcxTool, "namespace" | "name">, toolChoice: OcxRequestOptions["toolChoice"] | undefined): boolean {
+export function cursorToolAllowedByChoice(
+  tool: Pick<OcxTool, "namespace" | "name">,
+  toolChoice: OcxRequestOptions["toolChoice"] | undefined,
+  catalog: readonly Pick<OcxTool, "namespace" | "name">[] = [tool],
+): boolean {
   if (!toolChoice || toolChoice === "auto" || toolChoice === "required") return true;
   if (toolChoice === "none") return false;
   if ("allowedTools" in toolChoice) {
-    return toolChoice.allowedTools.includes(tool.name) || toolChoice.allowedTools.includes(cursorToolWireName(tool));
+    return toolChoice.allowedTools.some(choiceName => cursorToolChoiceMatches(tool, choiceName, catalog));
   }
-  return tool.name === toolChoice.name || cursorToolWireName(tool) === toolChoice.name;
+  return cursorToolChoiceMatches(tool, toolChoice.name, catalog);
 }
 
 function quotedNames(names: readonly string[]): string {
@@ -232,13 +372,15 @@ export function buildCursorToolGuidanceSystemNote(
   if (!tools?.length) return undefined;
   const wireNames = [...new Set(
     tools
-      .filter(tool => cursorToolAllowedByChoice(tool, toolChoice))
+      .filter(tool => cursorToolAllowedByChoice(tool, toolChoice, tools))
       .map(tool => cursorToolWireName(tool)),
   )];
   if (wireNames.length === 0) return undefined;
 
   const listedNames = quotedNames(wireNames);
-  const hasBareExec = wireNames.includes(CODEX_EXEC_COMMAND_TOOL);
+  const shellBridgeNames = wireNames.filter(isCodexShellBridgeToolName);
+  const hasBareExec = shellBridgeNames.length > 0;
+  const shellBridgeLabel = quotedNames(shellBridgeNames.length > 0 ? shellBridgeNames : [...CODEX_SHELL_BRIDGE_TOOL_NAMES]);
   const hasApplyPatch = cursorRequestAdvertisesApplyPatch(tools, toolChoice);
   const discoveryTools = discoveryToolLabel(wireNames);
   const unavailableNeighborNames = unavailableNeighborAgentToolNames(wireNames);
@@ -249,31 +391,34 @@ export function buildCursorToolGuidanceSystemNote(
       ? `This turn does not expose neighboring-agent tool names ${quotedNames(unavailableNeighborNames)}; do not call or suggest them unless the catalog lists them.`
       : undefined,
     hasBareExec
-      ? "`exec_command` is the Codex Responses bridge exec tool for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool."
+      ? `${shellBridgeLabel} is the Codex Responses shell bridge for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool. \`shell_command\` and \`exec_command\` are aliases of the same bridge.`
+      : undefined,
+    hasBareExec
+      ? "Your tool list may display it under a longer `mcp_opencodex-responses_shell_command` / `mcp_opencodex-responses_exec_command` name; those are the SAME tool — call whichever your list shows, and do not comment on the naming difference to the user."
       : undefined,
     hasBareExec
-      ? "Your tool list may display it under the longer name `mcp_opencodex-responses_exec_command`; both names are the SAME tool — call whichever your list shows, and do not comment on the naming difference to the user."
+      ? "Never tell the user that shell or read access is blocked, disabled, or denied unless the Codex shell bridge tool itself fails. Prefer the bridge over Cursor-native Shell/Read; do not narrate phrases like \"Native shell access is blocked\" — silently call `shell_command` / `exec_command`."
       : undefined,
     "Cursor product features (Chronicle, screen recording, Notes, Plans, background agents) are available only if this turn's catalog lists a matching tool; do not offer or promise them otherwise.",
     hasBareExec
-      ? "For file read/search/listing, use `exec_command` when no more specific listed tool is available."
+      ? `For file read/search/listing, use ${shellBridgeLabel} when no more specific listed tool is available.`
       : undefined,
     hasApplyPatch
       ? "For file edits, use the `apply_patch` tool, not built-in file write/delete tools."
       : undefined,
     hasBareExec
-      ? "For tool-count demos, each counted tool must be a separate `exec_command` invocation/result; do not collapse several requested tools into one chained shell command."
+      ? "For tool-count demos, each counted tool must be a separate Codex shell-bridge invocation/result; do not collapse several requested tools into one chained shell command."
       : undefined,
     "For independent read-only tool-count or batch requests, prefer one response containing multiple tool calls before waiting for results when the runtime supports parallel tool calls.",
     hasBareExec
-      ? "For bridge tool-count batches, emit sibling `exec_command` calls together before any result is needed because the bridge may suspend after a returned tool call."
+      ? "For bridge tool-count batches, emit sibling shell-bridge calls together before any result is needed because the bridge may suspend after a returned tool call."
       : undefined,
     discoveryTools
       ? `Use ${discoveryTools} only for explicit discovery/resource tasks, not generic tool-count demos.`
       : undefined,
     "Do not count or report a tool call unless a tool result was actually returned.",
     hasBareExec
-      ? "If a built-in file read, directory listing, grep, or shell operation is rejected by the runtime, use \`exec_command\` with the equivalent shell command instead (e.g. \`cat\`, \`ls\`, \`rg\`, \`grep\`). For file edits, use \`apply_patch\` when available."
+      ? `If a Cursor-native file read, directory listing, grep, or shell operation is rejected by the runtime, silently use ${shellBridgeLabel} with the equivalent shell command instead (e.g. \`cat\`, \`ls\`, \`rg\`, \`grep\`). Do not tell the user access is blocked. For file edits, use \`apply_patch\` when available.`
       : undefined,
   ].filter((note): note is string => typeof note === "string");
   return notes.join(" ");
@@ -291,7 +436,7 @@ export function buildCursorToolDefinitions(
   toolChoice?: OcxRequestOptions["toolChoice"],
 ): McpToolDefinition[] {
   if (!tools?.length) return [];
-  return tools.filter(tool => cursorToolAllowedByChoice(tool, toolChoice)).map(tool => {
+  return tools.filter(tool => cursorToolAllowedByChoice(tool, toolChoice, tools)).map(tool => {
     const wireName = cursorToolWireName(tool);
     return create(McpToolDefinitionSchema, {
       name: wireName,

package/src/adapters/openai-chat.ts

@@ -61,6 +61,13 @@ function extractErrorDetail(parsed: unknown): string | undefined {
   return undefined;
 }
 
+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("");
+}
+
 function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] {
   const out: unknown[] = [];
   const { context, options } = parsed;
@@ -112,7 +119,20 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
   const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
     ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
     : undefined;
-  const systemParts = [...(context.systemPrompt ?? []), ...(toolCatalogNudge ? [toolCatalogNudge] : [])];
+  // Chat templates used by LM Studio, llama.cpp, and other strict OpenAI-compatible
+  // backends require every system instruction to precede conversation history. Codex can
+  // append developer reminders after user turns, so fold text-only developer messages into
+  // the single leading system message instead of emitting role:"system" in place. Developer
+  // messages with images cannot be represented as system content and remain user-compatible
+  // vision messages at their original position below.
+  const developerSystemParts = context.messages
+    .map(developerSystemText)
+    .filter((part): part is string => part !== undefined && part.length > 0);
+  const systemParts = [
+    ...(context.systemPrompt ?? []),
+    ...developerSystemParts,
+    ...(toolCatalogNudge ? [toolCatalogNudge] : []),
+  ];
   if (systemParts.length > 0) {
     // Codex sends its GPT-5 identity prompt for EVERY model (the per-model catalog
     // base_instructions is ignored at request time). Neutralize that one identity line
@@ -126,18 +146,19 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
     switch (msg.role) {
       case "user":
       case "developer": {
-        const role = msg.role === "developer" ? "system" : "user";
+        const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
+        const hasImages = parts?.some(p => p.type === "image") ?? false;
+        if (msg.role === "developer" && !hasImages) break;
         let chatMsg: Record<string, unknown>;
         if (typeof msg.content === "string") {
-          chatMsg = { role, content: msg.content };
+          chatMsg = { role: "user", content: msg.content };
         } else {
-          const parts = msg.content as OcxContentPart[];
-          if (!parts.some(p => p.type === "image")) {
-            chatMsg = { role, content: parts.map(p => (p as OcxTextContent).text).join("") };
+          if (!hasImages) {
+            chatMsg = { role: "user", content: parts!.map(p => (p as OcxTextContent).text).join("") };
           } else {
             // Vision: chat-completions content-parts array. Images are only valid on the user role,
             // and the data URL goes straight into image_url.url (never the token-exploding text path).
-            const chatParts = parts.map(p => p.type === "image"
+            const chatParts = parts!.map(p => p.type === "image"
               ? { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }
               : { type: "text", text: (p as OcxTextContent).text });
             chatMsg = { role: "user", content: chatParts };

package/src/adapters/openai-responses.ts

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
 import type { IncomingMeta, ProviderAdapter } from "./base";
-import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../types";
+import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../types";
 import { catalogModelSupportsReasoningSummaries } from "../codex/catalog";
-import { decodeCompactionSummary, SUMMARY_PREFIX } from "../responses/compaction";
+import { COMPACT_PROMPT, decodeCompactionSummary, SUMMARY_PREFIX } from "../responses/compaction";
+import { decodeServerSentEvents } from "../lib/sse-decoder";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
 import { modelRecordValue } from "../reasoning-effort";
 
@@ -518,6 +520,81 @@ function stripUnsupportedHostedTools(body: unknown): unknown {
   return tools.length === body.tools.length ? body : { ...body, tools };
 }
 
+/** Replace every `input_image` part under a routed-compaction body with a short marker. */
+function stripInputImagesDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripInputImagesDeep);
+  if (!isPlainObject(value)) return value;
+  if (value.type === "input_image") {
+    return { type: "input_text", text: "[image omitted for compaction]" };
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) out[key] = stripInputImagesDeep(entry);
+  return out;
+}
+
+/**
+ * Rewrite a compaction turn for an upstream that does not speak Codex's private
+ * `compaction_trigger` item: drop the trigger and the whole tool surface, and ask
+ * for the handoff summary in plain terms instead (#422).
+ *
+ * The adapter builds from `parsed._rawBody`, so the summarizer prompt that
+ * handleResponses() pushed onto `parsed.context` never reaches the wire — it has to
+ * be applied here. Images go too: a summary needs no pixels, and a text-only
+ * gateway would reject them.
+ */
+function buildRoutedCompactionBody(body: unknown): unknown {
+  if (!isPlainObject(body)) return body;
+  const { tools: _tools, tool_choice: _toolChoice, parallel_tool_calls: _parallel, ...rest } = body;
+  const input = Array.isArray(body.input) ? body.input : [];
+  const kept = input.filter(item => !isPlainObject(item)
+    // `additional_tools` is how Codex Desktop's responses-lite shape carries tools;
+    // leaving it in would break the no-tools invariant even with `tools` removed.
+    || (item.type !== "compaction_trigger" && item.type !== "additional_tools"));
+  return {
+    ...rest,
+    input: [
+      ...(stripInputImagesDeep(kept) as unknown[]),
+      { type: "message", role: "user", content: [{ type: "input_text", text: COMPACT_PROMPT }] },
+    ],
+  };
+}
+
+/** Read the Responses `usage` block, if the gateway sent one. */
+function usageFromResponsesPayload(payload: unknown): OcxUsage | undefined {
+  if (!isPlainObject(payload) || !isPlainObject(payload.usage)) return undefined;
+  const usage = payload.usage;
+  const inputTokens = typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
+  const outputTokens = typeof usage.output_tokens === "number" ? usage.output_tokens : 0;
+  if (inputTokens === 0 && outputTokens === 0) return undefined;
+  return {
+    inputTokens,
+    outputTokens,
+    ...(typeof usage.total_tokens === "number" ? { totalTokens: usage.total_tokens } : {}),
+  };
+}
+
+function responsesPayloadText(response: unknown): string {
+  if (!isPlainObject(response) || !Array.isArray(response.output)) return "";
+  return response.output
+    .filter(item => isPlainObject(item) && item.type === "message")
+    .flatMap(item => (Array.isArray((item as Record<string, unknown>).content)
+      ? (item as { content: unknown[] }).content
+      : []))
+    .filter(part => isPlainObject(part) && part.type === "output_text")
+    .map(part => String((part as { text?: unknown }).text ?? ""))
+    .join("");
+}
+
+function responsesErrorMessage(payload: unknown): string {
+  if (!isPlainObject(payload)) return "upstream compaction failed";
+  const err = payload.error;
+  if (typeof err === "string") return err;
+  if (isPlainObject(err) && typeof err.message === "string") return err.message;
+  const incomplete = payload.incomplete_details;
+  if (isPlainObject(incomplete) && typeof incomplete.reason === "string") return incomplete.reason;
+  return "upstream compaction failed";
+}
+
 export function createResponsesPassthroughAdapter(provider: OcxProviderConfig): ProviderAdapter & { passthrough: true } {
   return {
     name: "openai-responses",
@@ -573,6 +650,12 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         outBody = repairOversizedReplayCallIds(outBody);
       }
       outBody = stripUnsupportedReasoningSummaryDelivery(outBody, parsed.modelId);
+      // Same predicate as the routedCompaction gate in handleResponses(): an
+      // authMode check would let a noncanonical custom forward provider skip this
+      // rewrite while the server still routes it as a summarizer turn (#422).
+      if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
+        outBody = buildRoutedCompactionBody(outBody);
+      }
       return {
         url,
         method: "POST",
@@ -585,8 +668,71 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       };
     },
 
-    async *parseStream(): AsyncGenerator<AdapterEvent> {
-      yield { type: "error", message: "passthrough adapter should not parse stream" };
+    // The passthrough normally relays the upstream stream verbatim and never parses.
+    // The exception is a routed compaction turn: the server drives this adapter like
+    // an ordinary one so the bridge can build the single compaction item (#422).
+    async *parseStream(response: Response): AsyncGenerator<AdapterEvent> {
+      if (!response.body) {
+        yield { type: "error", message: "passthrough adapter received no response body" };
+        return;
+      }
+      let deltas = "";
+      let doneText = "";
+      let snapshot = "";
+      let usage: OcxUsage | undefined;
+      for await (const event of decodeServerSentEvents(response.body)) {
+        let payload: unknown;
+        try { payload = JSON.parse(event.data); } catch { continue; }
+        if (!isPlainObject(payload)) continue;
+        switch (payload.type) {
+          case "response.output_text.delta":
+            if (typeof payload.delta === "string") deltas += payload.delta;
+            break;
+          case "response.output_text.done":
+            if (typeof payload.text === "string") doneText += payload.text;
+            break;
+          case "response.failed":
+          case "error":
+            yield { type: "error", message: responsesErrorMessage(payload.response ?? payload) };
+            return;
+          case "response.incomplete":
+            yield { type: "incomplete", reason: responsesErrorMessage(payload.response ?? payload) };
+            return;
+          case "response.completed":
+            snapshot = responsesPayloadText(payload.response);
+            usage = usageFromResponsesPayload(payload.response);
+            break;
+        }
+      }
+      // Gateways differ in which of these they emit; prefer the authoritative
+      // completed snapshot so text is never double-counted.
+      const text = snapshot || doneText || deltas;
+      if (text) yield { type: "text_delta", text };
+      yield { type: "done", ...(usage ? { usage } : {}) };
+    },
+
+    async parseResponse(response: Response): Promise<AdapterEvent[]> {
+      let payload: unknown;
+      try { payload = await response.json(); } catch {
+        return [{ type: "error", message: "malformed upstream compaction response" }];
+      }
+      if (!isPlainObject(payload)) {
+        return [{ type: "error", message: "malformed upstream compaction response" }];
+      }
+      if (payload.error || payload.status === "failed") {
+        return [{ type: "error", message: responsesErrorMessage(payload) }];
+      }
+      if (payload.status === "incomplete") {
+        return [{ type: "incomplete", reason: responsesErrorMessage(payload) }];
+      }
+      const text = responsesPayloadText(payload);
+      if (!text) {
+        // A completed turn with no usable text cannot become a summary; saying so is
+        // better than installing an empty compaction as replacement history.
+        return [{ type: "error", message: "upstream compaction returned no summary text" }];
+      }
+      const usage = usageFromResponsesPayload(payload);
+      return [{ type: "text_delta", text }, { type: "done", ...(usage ? { usage } : {}) }];
     },
   };
 }

package/src/bridge.ts

@@ -456,6 +456,17 @@ export function bridgeToResponsesSSE(
             if (event.type !== "done" && event.type !== "incomplete" && event.type !== "error") continue;
           }
           switch (event.type) {
+            case "assistant_boundary": {
+              // A guarded continuation starts a fresh assistant output item while keeping the
+              // intermediate, suspicious text in the same Responses turn.
+              if (currentMsg) closeCurrentMessage();
+              if (currentReasoning) closeCurrentReasoning();
+              if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
+              if (currentToolCall) closeCurrentToolCall();
+              flushHiddenReasoningEnvelope();
+              break;
+            }
             case "text_delta": {
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
@@ -971,6 +982,12 @@ export function buildResponseJSON(
 
   for (const e of events) {
     switch (e.type) {
+      case "assistant_boundary":
+        flushText();
+        flushSummaryReasoning();
+        flushRawReasoning();
+        flushToolCall();
+        break;
       case "text_delta":
         if (currentText && currentTextPhase !== e.phase) flushText();
         if (currentSummaryReasoning) flushSummaryReasoning();
@@ -1062,7 +1079,9 @@ export function buildResponseJSON(
   flushSummaryReasoning();
   flushRawReasoning();
   flushToolCall();
-  if (options?.compaction && !errorEvent) {
+  // A truncated turn must never be installed as replacement history: emit the
+  // compaction item only when the turn actually completed (#422).
+  if (options?.compaction && !errorEvent && !incompleteEvent && stopReason !== "max_tokens") {
     output.push({ type: "compaction", id: `cmp_${uuid()}`, encrypted_content: encodeCompactionSummary(compactionText) });
   }