@iislee/opencodex 2.11.0 → 2.31.0

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

@@ -7,12 +7,25 @@ import { McpToolDefinitionSchema, McpToolsSchema, type McpToolDefinition } from
 export const OCX_RESPONSES_TOOL_PROVIDER = "opencodex-responses";
 export const CODEX_EXEC_COMMAND_TOOL = "exec_command";
 export const CODEX_SHELL_COMMAND_TOOL = "shell_command";
+/** Codex Desktop unified-exec client tool. Companion of `wait`; not an `exec_command` schema alias. */
+export const CODEX_UNIFIED_EXEC_TOOL = "exec";
+export const CODEX_WAIT_TOOL = "wait";
 export const CODEX_APPLY_PATCH_TOOL = "apply_patch";
+export const CURSOR_EDIT_FILE_TOOL = "edit_file";
+export const CURSOR_MULTI_EDIT_TOOL = "multi_edit";
+export const CURSOR_STRUCTURED_EDIT_TOOLS = [CURSOR_EDIT_FILE_TOOL, CURSOR_MULTI_EDIT_TOOL] as const;
 export const CURSOR_EXEC_COMMAND_TOOL = CODEX_EXEC_COMMAND_TOOL;
 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.';
+  '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.';
 const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
+const NEIGHBOR_AGENT_TOOL_ALIASES: Record<(typeof NEIGHBOR_AGENT_TOOL_NAMES)[number], readonly string[]> = {
+  Read: ["read", "read_file"],
+  Grep: ["grep"],
+  Glob: ["glob", "find"],
+  Bash: ["bash", "shell"],
+  LS: ["ls"],
+};
 
 export const CURSOR_GENERIC_TOOL_USE_USER_HINT = [
   "For generic tool-use/count demos, satisfy the request with repeated Codex shell bridge calls (`shell_command` or `exec_command`) for harmless commands.",
@@ -23,8 +36,7 @@ export const CURSOR_GENERIC_TOOL_USE_USER_HINT = [
   "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 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.",
+  "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 or an equivalent listed client tool.",
 ].join(" ");
 
 export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
@@ -41,6 +53,47 @@ export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
   additionalProperties: false,
 } as const;
 
+/**
+ * Structured single-replacement schema advertised to Cursor models in addition to the freeform
+ * `apply_patch` tool. Cursor-trained models reliably emit exact-match replacements (the native
+ * Edit shape) but cannot produce Codex's freeform patch grammar, so every file edit attempt on the
+ * Cursor route produced malformed `apply_patch` payloads that the Codex client rejected locally
+ * (#1017). Calls to this tool are converted server-side into a valid apply_patch payload.
+ */
+export const CURSOR_EDIT_FILE_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    file_path: { type: "string", description: "Path of the file to edit, relative to the workspace root." },
+    old_string: { type: "string", description: "Exact text to replace. Must match the current file content, including line breaks." },
+    new_string: { type: "string", description: "Replacement text. Empty removes the matched text." },
+  },
+  required: ["file_path", "old_string", "new_string"],
+  additionalProperties: false,
+} as const;
+
+/** Structured multi-replacement schema; mirrors Cursor's native MultiEdit shape. */
+export const CURSOR_MULTI_EDIT_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    file_path: { type: "string", description: "Path of the file to edit, relative to the workspace root." },
+    edits: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          old_string: { type: "string", description: "Exact text to replace. Must match the current file content, including line breaks." },
+          new_string: { type: "string", description: "Replacement text. Empty removes the matched text." },
+        },
+        required: ["old_string", "new_string"],
+        additionalProperties: false,
+      },
+      description: "Ordered replacement edits for this file. Each old_string must match the current file content.",
+    },
+  },
+  required: ["file_path", "edits"],
+  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
@@ -123,6 +176,59 @@ export function isBareCodexShellBridgeTool(tool: Pick<OcxTool, "namespace" | "na
   return !tool.namespace && isCodexShellBridgeToolName(tool.name);
 }
 
+function isCursorResponsesProvider(namespace: string | undefined): boolean {
+  return !namespace || namespace === OCX_RESPONSES_TOOL_PROVIDER;
+}
+
+const CURSOR_EXECUTION_PATH_TOOL_NAMES = [
+  CODEX_UNIFIED_EXEC_TOOL,
+  CODEX_EXEC_COMMAND_TOOL,
+  CODEX_SHELL_COMMAND_TOOL,
+] as const;
+
+/** True for the Codex execution path that must survive Cursor transport truncation. */
+export function isCursorExecutionPathTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
+  return isCursorResponsesProvider(tool.namespace)
+    && (CURSOR_EXECUTION_PATH_TOOL_NAMES as readonly string[]).includes(tool.name);
+}
+
+/** `wait` only resumes a yielded exec cell; it is unusable without an execution-path tool. */
+export function isCursorWaitTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
+  return isCursorResponsesProvider(tool.namespace) && tool.name === CODEX_WAIT_TOOL;
+}
+
+/**
+ * True for Codex's unified-exec "code mode" tool: a freeform `exec` whose body is JavaScript
+ * evaluated in a V8 isolate, not a shell command string.
+ */
+export function isCursorCodeModeExecTool(
+  tool: Pick<OcxTool, "namespace" | "name" | "freeform">,
+): boolean {
+  return isCursorResponsesProvider(tool.namespace)
+    && tool.name === CODEX_UNIFIED_EXEC_TOOL
+    && tool.freeform === true;
+}
+
+/**
+ * Codex code mode advertises ONE freeform `exec` tool and no bare shell bridge. Shell, file
+ * edits, and MCP calls are reachable only as nested `tools.<name>(...)` helpers described inside
+ * that tool's own description, so a flat catalog scan cannot see them.
+ *
+ * This matters because the shell-bridge guidance below is written for a flat catalog. Emitting
+ * "call \`exec_command\`" into a code-mode turn names a top-level tool that does not exist: the
+ * model calls it, gets nothing back, and burns turns rediscovering the real contract from error
+ * messages (empty output until \`text()\` is called, \`require is not defined\` because the isolate
+ * is not Node, \`apply_patch\` rejected because it too is only a nested helper here).
+ */
+export function cursorRequestUsesCodeMode(
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): boolean {
+  const catalog = tools ?? [];
+  const visible = catalog.filter(tool => cursorToolAllowedByChoice(tool, toolChoice, catalog));
+  return visible.some(isCursorCodeModeExecTool) && !visible.some(isBareCodexShellBridgeTool);
+}
+
 /** @deprecated Prefer isBareCodexShellBridgeTool; kept for older call sites/tests. */
 function isBareCodexExecCommandTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
   return isBareCodexShellBridgeTool(tool);
@@ -132,6 +238,12 @@ export function cursorRequestHasShellAlias(tools: readonly Pick<OcxTool, "namesp
   return tools?.some(isBareCodexExecCommandTool) ?? false;
 }
 
+function cursorRequestHasExecutionPath(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+): boolean {
+  return tools?.some(isCursorExecutionPathTool) ?? false;
+}
+
 export function cursorRequestAdvertisesApplyPatch(
   tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
   toolChoice?: OcxRequestOptions["toolChoice"],
@@ -140,6 +252,73 @@ export function cursorRequestAdvertisesApplyPatch(
   return catalog.some(tool => !tool.namespace && tool.name === CODEX_APPLY_PATCH_TOOL && tool.freeform === true && cursorToolAllowedByChoice(tool, toolChoice, catalog));
 }
 
+export function isCursorStructuredEditToolName(name: string): boolean {
+  return (CURSOR_STRUCTURED_EDIT_TOOLS as readonly string[]).includes(name);
+}
+
+/** Internal provenance gate for synthetic edits after prompt filtering and catalog budgeting. */
+export function isCursorSyntheticStructuredEditTool(
+  tool: Pick<OcxTool, "namespace" | "name" | "cursorStructuredEdit">,
+): boolean {
+  return !tool.namespace && tool.cursorStructuredEdit === true && isCursorStructuredEditToolName(tool.name);
+}
+
+/**
+ * Synthetic structured edit tools for the Cursor route (#1017).
+ *
+ * Codex exposes `apply_patch` as a freeform custom tool whose body must be the exact Codex patch
+ * grammar (`*** Begin Patch` envelope, `@@` hunks, `-`/`+` prefixes). Cursor-trained models are
+ * trained on exact-match edit tools instead and emit malformed patch text on every attempt, which
+ * the Codex client then rejects locally ("invalid hunk"). When the request advertises the freeform
+ * `apply_patch` tool, also advertise Cursor-native-shaped `edit_file` / `multi_edit` tools; the
+ * adapter converts their exact-match replacements into a valid apply_patch payload (see
+ * protobuf-events.translateStructuredEditCall).
+ *
+ * Never widened when the caller pinned an explicit tool choice: a forced `apply_patch` selection
+ * must not gain sibling tools the client did not ask for.
+ */
+export function cursorStructuredEditTools(
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): OcxTool[] {
+  if (!cursorRequestAdvertisesApplyPatch(tools, toolChoice)) return [];
+  if (toolChoice && toolChoice !== "auto" && toolChoice !== "required") return [];
+  // Never shadow an already-advertised bare tool with the same name (a client catalog could
+  // legitimately expose its own `edit_file` / `multi_edit` MCP-style tools).
+  const existingBareNames = new Set(
+    (tools ?? []).filter(tool => !tool.namespace).map(tool => tool.name),
+  );
+  const candidates: OcxTool[] = [
+    {
+      name: CURSOR_EDIT_FILE_TOOL,
+      cursorStructuredEdit: true,
+      description:
+        "Replace one block of text in a file. OpenCodex converts the replacement into a Codex apply_patch change. Copy old_string and new_string with their exact leading whitespace — Codex may locate a line after trimming indent, but it writes new_string verbatim, so stripped indent silently corrupts the file. An empty old_string with a non-empty new_string creates a new file (Add File). If the same text appears more than once, the first match is updated. Matching is line-based, so an edit cannot add or remove only the file's final newline, and old_string/new_string that are identical after line normalization are rejected as a no-op.",
+      parameters: { ...CURSOR_EDIT_FILE_INPUT_SCHEMA },
+    },
+    {
+      name: CURSOR_MULTI_EDIT_TOOL,
+      cursorStructuredEdit: true,
+      description:
+        "Apply several text replacements to one file. OpenCodex converts them into one Codex apply_patch change. Copy each old_string/new_string with exact leading whitespace. If a later edit's old_string is the text after an earlier replacement, OpenCodex folds those edits into one original-file hunk. Independent edits stay separate hunks. An empty old_string with a non-empty new_string creates a new file (Add File); do not mix that with an independent Update on the same path. If the same text appears more than once, the first match is updated. Matching is line-based, so an edit cannot add or remove only the file's final newline, and identical old/new after line normalization are rejected as a no-op.",
+      parameters: { ...CURSOR_MULTI_EDIT_INPUT_SCHEMA },
+    },
+  ];
+  return candidates.filter(tool => !existingBareNames.has(tool.name));
+}
+
+/**
+ * True when this request actually advertises the synthetic structured edit tools (`edit_file` /
+ * `multi_edit`) — i.e. a freeform `apply_patch` is advertised, no tool-choice pin blocks widening,
+ * and neither name is shadowed by an existing bare tool in the client catalog.
+ */
+export function cursorRequestAdvertisesStructuredEdits(
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): boolean {
+  return cursorStructuredEditTools(tools, toolChoice).length > 0;
+}
+
 export function cursorToolWireName(tool: Pick<OcxTool, "namespace" | "name">): string {
   return namespacedToolName(tool.namespace, tool.name);
 }
@@ -157,6 +336,26 @@ export function normalizeCursorWireName(name: string): string {
   return name.startsWith(CURSOR_MCP_DISPLAY_PREFIX) ? name.slice(CURSOR_MCP_DISPLAY_PREFIX.length) : name;
 }
 
+/**
+ * #2305: some models emit a TEXTUAL pseudo tool call ("[TOOL_CALL]name[ARGS]{...}")
+ * instead of a real frame, using Cursor's display alias as the name. Text-mode clients
+ * (Pi) parse that text and then cannot dispatch the undeclared display name. Rewrite the
+ * display alias to the advertised wire name ONLY inside the marker pair — prose that
+ * merely mentions the alias stays untouched, and the scope guard is the exact
+ * `mcp_${OCX_RESPONSES_TOOL_PROVIDER}_` prefix, never generic `mcp_`.
+ * Known limit (recorded in devlog 230): a marker split across two streaming deltas is
+ * not rewritten; tail-buffering is deferred until a live trace shows split markers.
+ */
+const CURSOR_TEXT_TOOL_MARKER = new RegExp(
+  String.raw`\[TOOL_CALL\](${CURSOR_MCP_DISPLAY_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\[\]]+)\[ARGS\]`,
+  "g",
+);
+
+export function normalizeCursorTextToolMarkers(text: string): string {
+  if (!text.includes(CURSOR_MCP_DISPLAY_PREFIX)) return text;
+  return text.replace(CURSOR_TEXT_TOOL_MARKER, (_match, name: string) => `[TOOL_CALL]${normalizeCursorWireName(name)}[ARGS]`);
+}
+
 export function responsesToolNameFromCursorWire(name: string, cursorToolNameMap?: ReadonlyMap<string, string>): string {
   const normalized = normalizeCursorWireName(name);
   if (!cursorToolNameMap) return normalized;
@@ -286,7 +485,7 @@ export function shouldUseNativeExecOnlyForGenericToolUse(
   text: string,
 ): boolean {
   const trimmed = text.trim();
-  if (trimmed.length === 0 || !cursorRequestHasShellAlias(tools) || !isGenericToolUseCountDemoPrompt(trimmed)) return false;
+  if (trimmed.length === 0 || !cursorRequestHasExecutionPath(tools) || !isGenericToolUseCountDemoPrompt(trimmed)) return false;
   return !/\b(?:mcp|resource|resources|tool_search|plugin|plugins|app connector|github)\b/i.test(trimmed)
     && !/(?:리소스|플러그인|깃허브|github)/i.test(trimmed);
 }
@@ -297,7 +496,7 @@ export function cursorToolsForActivePrompt<T extends Pick<OcxTool, "namespace" |
   toolChoice?: OcxRequestOptions["toolChoice"],
 ): readonly T[] | undefined {
   if (!shouldUseNativeExecOnlyForGenericToolUse(tools, activeText)) return tools;
-  const execTools = tools?.filter(isBareCodexExecCommandTool);
+  const execTools = tools?.filter(isCursorExecutionPathTool);
   const catalog = tools ?? [];
   if (execTools?.length && !execTools.some(tool => cursorToolAllowedByChoice(tool, toolChoice, catalog))) return tools;
   return execTools && execTools.length > 0 ? execTools : tools;
@@ -352,7 +551,12 @@ export function nonEmptyShellBridgeCommandFromArgs(
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
   const record = parsed as Record<string, unknown>;
-  for (const key of shellBridgeRequiredCommandKeys(toolName, schema)) {
+  const requiredKeys = shellBridgeRequiredCommandKeys(toolName, schema);
+  const candidateKeys = new Set<"cmd" | "command">([
+    ...requiredKeys,
+    requiredKeys.includes("cmd") ? "command" : "cmd",
+  ]);
+  for (const key of candidateKeys) {
     const value = record[key];
     if (typeof value === "string" && value.trim().length > 0) return value.trim();
   }
@@ -385,9 +589,14 @@ function quotedNames(names: readonly string[]): string {
   return names.map(name => `\`${name}\``).join(", ");
 }
 
+function advertisedCoversNeighbor(wireNames: readonly string[], neighbor: (typeof NEIGHBOR_AGENT_TOOL_NAMES)[number]): boolean {
+  const advertised = new Set(wireNames.map(name => name.toLowerCase()));
+  if (advertised.has(neighbor.toLowerCase())) return true;
+  return NEIGHBOR_AGENT_TOOL_ALIASES[neighbor].some(alias => advertised.has(alias.toLowerCase()));
+}
+
 function unavailableNeighborAgentToolNames(wireNames: readonly string[]): string[] {
-  const advertised = new Set(wireNames);
-  return NEIGHBOR_AGENT_TOOL_NAMES.filter(name => !advertised.has(name));
+  return NEIGHBOR_AGENT_TOOL_NAMES.filter(name => !advertisedCoversNeighbor(wireNames, name));
 }
 
 function discoveryToolLabel(wireNames: readonly string[]): string | undefined {
@@ -413,14 +622,25 @@ export function buildCursorToolGuidanceSystemNote(
   const listedNames = quotedNames(wireNames);
   const shellBridgeNames = wireNames.filter(isCodexShellBridgeToolName);
   const hasBareExec = shellBridgeNames.length > 0;
+  const codeMode = cursorRequestUsesCodeMode(tools, toolChoice);
+  // Code mode describes how the freeform exec tool works; it does not suppress the rest of the
+  // catalog. A turn can advertise freeform `exec` AND ordinary top-level tools at once, and
+  // telling the model those are "not separate top-level tools" would make it refuse tools that
+  // are right there in its catalog. Name the ones that stay callable instead.
+  const codeModeOtherTopLevelNames = codeMode
+    ? wireNames.filter(name => name !== CODEX_UNIFIED_EXEC_TOOL && !isCodexShellBridgeToolName(name))
+    : [];
   const shellBridgeLabel = quotedNames(shellBridgeNames.length > 0 ? shellBridgeNames : [...CODEX_SHELL_BRIDGE_TOOL_NAMES]);
   const hasApplyPatch = cursorRequestAdvertisesApplyPatch(tools, toolChoice);
+  const structuredEditNames = tools
+    ?.filter(tool => !tool.namespace && isCursorStructuredEditToolName(tool.name))
+    .map(tool => tool.name) ?? [];
   const discoveryTools = discoveryToolLabel(wireNames);
   const unavailableNeighborNames = unavailableNeighborAgentToolNames(wireNames);
   // Host-shell-neutral: the Codex client executes bridge commands, and may differ from
   // the OpenCodex proxy OS (LAN/SSH remote-proxy). Always cover PowerShell 5.1 pitfalls.
   const hostShellNote = hasBareExec
-    ? "Match shell syntax to the Codex client host that runs the bridge (not only the proxy OS). Windows PowerShell 5.1: no CMD `cd /d`, no bash heredocs (`<<EOF`); `&&`/`||` are unsupported parser errors — prefer the bridge working-directory argument for directory changes, and use `if ($?) { ... }` for success-gated follow-up steps; do not treat `;` as a substitute for `&&`. POSIX: use portable commands. After a shell failure, make at most one corrected bridge attempt, then report the error and stop — do not repeat equivalent failing commands."
+    ? "Match shell syntax to the Codex client host that runs the bridge (not only the proxy OS). Windows PowerShell 5.1: no CMD `cd /d`, no bash heredocs (`<<EOF`); `&&`/`||` are unsupported parser errors — prefer the bridge working-directory argument for directory changes, and use `if ($?) { ... }` for success-gated follow-up steps; do not treat `;` as a substitute for `&&`. POSIX: use portable commands (`cat`/`ls`/`rg`); never emit Get-Content or Get-ChildItem unless the host shell is PowerShell. After a shell failure, make at most one corrected bridge attempt, then report the error and stop — do not repeat equivalent failing commands."
     : undefined;
   const notes = [
     `Cursor tool calls: available tool names are exactly ${listedNames}.`,
@@ -428,6 +648,14 @@ export function buildCursorToolGuidanceSystemNote(
     unavailableNeighborNames.length > 0
       ? `This turn does not expose neighboring-agent tool names ${quotedNames(unavailableNeighborNames)}; do not call or suggest them unless the catalog lists them.`
       : undefined,
+    // Code mode: shell/edit/MCP live inside freeform `exec` as nested helpers. Without this the
+    // model probes for a top-level shell tool that is not there.
+    codeMode
+      ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description and the isolate global \`ALL_TOOLS\` (not \`tools.ALL_TOOLS\`) for helpers this turn provides; absence from the top-level catalog or from \`exec\`'s description is not absence. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\` or \`shell_command\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}.`
+      : undefined,
+    codeMode
+      ? "In code mode the isolate returns nothing on its own: call `text(...)` (or `notify(...)`) on any value you need to see, or the call completes with empty output. There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers."
+      : undefined,
     hasBareExec
       ? `${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,
@@ -435,7 +663,7 @@ export function buildCursorToolGuidanceSystemNote(
       ? "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
-      ? "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`."
+      ? `Prefer the Codex shell bridge over Cursor-native Shell/Read. If a Cursor-native file read, directory listing, grep, or shell operation is rejected, continue with the listed catalog tool ${shellBridgeLabel}.`
       : undefined,
     hostShellNote,
     "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.",
@@ -443,7 +671,9 @@ export function buildCursorToolGuidanceSystemNote(
       ? `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."
+      ? structuredEditNames.length > 0
+        ? `For file edits, prefer the structured edit tools ${quotedNames(structuredEditNames)} — they take replacements that OpenCodex converts into Codex \`apply_patch\` changes. Include exact leading whitespace in old_string/new_string. Use \`apply_patch\` directly only with a \`*** Begin Patch\` envelope and bare \`@@\` hunks (never git-style \`@@ -n,m +n,m @@\`); never emit patch-like plain text as tool arguments.`
+        : "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 Codex shell-bridge invocation/result; do not collapse several requested tools into one chained shell command."
@@ -457,7 +687,7 @@ export function buildCursorToolGuidanceSystemNote(
       : undefined,
     "Do not count or report a tool call unless a tool result was actually returned.",
     hasBareExec
-      ? `If a Cursor-native file read, directory listing, grep, or shell operation is rejected by the runtime, silently use ${shellBridgeLabel} with an equivalent host-shell-safe command (POSIX: \`cat\`/\`ls\`/\`rg\`; Windows PowerShell: \`Get-Content\`/\`Get-ChildItem\`/\`Select-String\`). Do not tell the user access is blocked. 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, use ${shellBridgeLabel} with an equivalent host-shell-safe command (POSIX: \`cat\`/\`ls\`/\`rg\`; Windows PowerShell: \`Get-Content\`/\`Get-ChildItem\`/\`Select-String\`). For file edits, use ${structuredEditNames.length > 0 ? `the structured edit tools (${quotedNames(structuredEditNames)}) or ` : ""}\`apply_patch\` when available.`
       : undefined,
   ].filter((note): note is string => typeof note === "string");
   return notes.join(" ");

package/src/adapters/cursor/tool-result-normalize.ts

@@ -0,0 +1,92 @@
+/**
+ * Cursor tool-result normalization for Computer Use / node_repl surfaces (#1920/#1866).
+ *
+ * Scoped re-implementation of PR #1920 per the 260818 campaign disposition
+ * (REDESIGN-SMALL: "apply formatted.text at native toolResultPart + decode test").
+ * Only empty-output and known-failure-state normalization ships here; screenshot
+ * stripping and AXTree text compaction from the original PR are deliberately out
+ * of scope (the native path already bounds step size by real serialized bytes,
+ * dropping images oldest-first — see toolCallStep in protobuf-request.ts).
+ */
+
+const COMPUTER_USE_TOOL_NAMES = new Set([
+  "node_repl",
+  "node_repl__js",
+  "mcp__node_repl__js",
+  "get_app_state",
+  "list_apps",
+  "screenshot",
+  "computer_use",
+]);
+
+function isNodeReplOrComputerUseTool(toolName?: string, toolNamespace?: string): boolean {
+  if (toolNamespace && (toolNamespace === "mcp__node_repl" || toolNamespace.includes("node_repl") || toolNamespace.includes("computer_use"))) {
+    return true;
+  }
+  if (!toolName) return false;
+  const lower = toolName.toLowerCase();
+  if (COMPUTER_USE_TOOL_NAMES.has(lower)) return true;
+  return lower.startsWith("mcp__node_repl") || lower.startsWith("mcp__computer_use");
+}
+
+/** Failure states the Computer Use / node_repl runtime reports as PLAIN TEXT inside a non-error result. */
+const RUNTIME_FAILURE_GUIDANCE: ReadonlyArray<{ marker: string; guidance: string }> = [
+  {
+    marker: "SkyComputerUseError",
+    guidance: "The Computer Use runtime rejected this action. Re-check application state with get_app_state before retrying.",
+  },
+  {
+    marker: "sky is not defined",
+    guidance: "The sky binding is unavailable in this context; Computer Use calls only work inside the privileged node_repl session.",
+  },
+  {
+    marker: "has already been declared",
+    guidance: "The node_repl session keeps earlier declarations; rename the variable or use var/reassignment instead of redeclaring.",
+  },
+  {
+    marker: "unsupported import in exec",
+    guidance: "Imports are not available in this exec context; use the injected globals instead.",
+  },
+];
+
+/** Matches exec wrappers whose only payload is an empty-output marker. */
+const EMPTY_EXEC_OUTPUT_REGEX = /^(?:(?:Script completed|Script failed|Command finished|Execution finished)[^\n]*\n+)?(?:Wall time[^\n]*\n+)?(?:Output:\s*)?(?:<empty>)?\s*$/;
+
+export interface NormalizedToolResultText {
+  text: string;
+  isError: boolean;
+  /** True when normalization changed either field (lets callers skip work on the common path). */
+  changed: boolean;
+}
+
+/**
+ * Normalize a Cursor-bound tool-result TEXT payload:
+ *  - blank / empty-exec-wrapper output on Computer Use or node_repl tools becomes an
+ *    actionable error instead of an empty string the model silently accepts;
+ *  - known runtime failure states reported as plain text are marked isError with a
+ *    one-line recovery hint appended.
+ * Everything else passes through byte-identical.
+ */
+export function normalizeCursorToolResultText(
+  text: string,
+  options: { toolName?: string; toolNamespace?: string; isError?: boolean } = {},
+): NormalizedToolResultText {
+  const isError = options.isError === true;
+  const computerUse = isNodeReplOrComputerUseTool(options.toolName, options.toolNamespace);
+  if (computerUse && EMPTY_EXEC_OUTPUT_REGEX.test(text.trim())) {
+    return {
+      text: "[empty output: the tool ran but produced no stdout or return value. Verify application state with get_app_state, or make the script emit output.]",
+      isError: true,
+      changed: true,
+    };
+  }
+  if (!isError) {
+    for (const { marker, guidance } of RUNTIME_FAILURE_GUIDANCE) {
+      if (text.includes(marker)) {
+        return { text: `${text}\n[recovery: ${guidance}]`, isError: true, changed: true };
+      }
+    }
+  }
+  return { text, isError, changed: false };
+}
+

package/src/adapters/cursor/transport.ts

@@ -12,16 +12,33 @@ export interface CursorTransport {
    * accepted is never replayed. Absent (undefined) is treated as "committed" — safe by default.
    */
   requestCommitted?(): boolean;
+  /**
+   * Last ConversationStateStructure captured from conversationCheckpointUpdate on this transport.
+   * Test and adapter seams use this instead of reaching into LiveCursorTransport.
+   */
+  capturedConversationCheckpoint?(): Uint8Array | undefined;
 }
 
 export interface CursorTransportFactoryInput {
   provider: OcxProviderConfig;
   translatorBudget: TranslatorBudget;
   headers?: Headers;
+  /** Router-prepared fetch that preserves provider overrides and per-request pacing. */
+  fetch?: typeof globalThis.fetch;
   /** Pre-first-frame deadline (dial + first server frame). Defaults to 30s when omitted. */
   firstFrameTimeoutMs?: number;
   /** Grace (ms) between close() and the force-destroy fallback after a first-frame timeout. Defaults to 1s. */
   timeoutDestroyGraceMs?: number;
+  /**
+   * T04 watchdog: maximum inbound decoded-frame silence (ms) after the first frame before the
+   * turn is failed. Defaults to 30s.
+   */
+  streamSilenceFailMs?: number;
+  /**
+   * T04 watchdog: maximum heartbeat/checkpoint-only traffic (ms) without turn progress before
+   * the turn is failed. Defaults to 90s.
+   */
+  streamHeartbeatOnlyFailMs?: number;
   /**
    * Grace window (ms) before a drained client-tool turn is finalized, so a sibling tool call
    * announced in a later receive chunk can revoke a premature finalize. Defaults to 50ms.
@@ -33,6 +50,11 @@ export interface CursorTransportFactoryInput {
    * native local exec authorization because the text is caller-controlled.
    */
   requestDeclaresFullAccess?: boolean;
+  /**
+   * Stable Cursor Connect `x-session-id` across transport rebuilds for the same
+   * client thread. Distinct from the per-transport native-exec/shell owner.
+   */
+  sessionId?: string;
 }
 
 export type CursorTransportFactory = (input: CursorTransportFactoryInput) => CursorTransport;

package/src/adapters/cursor/types.ts

@@ -1,15 +1,30 @@
 import type { OcxUsage } from "../../types";
 import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
 import type { CursorRoutingLevel } from "./discovery";
+import type { CursorCheckpointInvalidationReason } from "./checkpoint-store";
+import type { ResolvedCursorImage } from "./images";
+
+export interface CursorRequestedModelParameter {
+  id: string;
+  value: string;
+}
 
 export interface CursorRunRequest {
   modelId: string;
+  /** Cursor model-picker parameters encoded through AgentRunRequest.requested_model. */
+  requestedModelParameters?: readonly CursorRequestedModelParameter[];
   /** Cursor Router optimization parameter; valid only while modelId is the `default` wire model. */
   routingLevel?: CursorRoutingLevel;
   conversationId: string;
   system: string[];
   messages: CursorRequestMessage[];
-  rawMessages?: OcxMessage[];
+  rawMessages?: readonly OcxMessage[];
+  /**
+   * Images for the active user/developer turn. Encoded as SelectedImage blobIdWithData refs under
+   * UserMessage.selected_context (bytes live in the request-scoped KV store for getBlobArgs
+   * hydration). History stays text-only. data: URLs only in this slice.
+   */
+  selectedImages?: readonly ResolvedCursorImage[];
   tools?: OcxTool[];
   toolChoice?: OcxRequestOptions["toolChoice"];
   parallelToolCalls?: boolean;
@@ -24,6 +39,18 @@ export interface CursorRunRequest {
    * pre-compaction history being summarized and must not become the next turn's carry-forward total.
    */
   contextUsageStoreCheckpoints?: boolean;
+  /**
+   * Reuse a previously captured ConversationStateStructure instead of rebuilding historical
+   * root/turn blobs. Absent means the existing full-replay path.
+   */
+  checkpointBytes?: Uint8Array;
+  continuationMode?: "full-replay" | "checkpoint";
+  checkpointInvalidationReason?: CursorCheckpointInvalidationReason;
+  /**
+   * When set with checkpointBytes, only this suffix of rawMessages is replayed onto the
+   * decoded ConversationStateStructure. Used for tool-result continuations.
+   */
+  checkpointSuffixStart?: number;
 }
 
 export interface CursorRequestMessage {