npm - @bitkyc08/opencodex - Versions diffs - 2.46.0 → 2.47.0-preview.20260908 - Mend

@bitkyc08/opencodex 2.46.0 → 2.47.0-preview.20260908

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (66) hide show

package/README.md +22 -0
package/SPONSORS.md +105 -0
package/gui/dist/assets/index-B8ZZ0ivI.css +1 -0
package/gui/dist/assets/index-CNTWhC5F.js +115 -0
package/gui/dist/index.html +2 -2
package/package.json +2 -1
package/src/adapters/cursor/protobuf-request.ts +34 -21
package/src/adapters/cursor/tool-guidance.ts +2 -2
package/src/adapters/cursor/tool-result-normalize.ts +22 -2
package/src/adapters/exec-tool-result-normalize.ts +87 -0
package/src/adapters/kiro.ts +29 -18
package/src/adapters/responses-code-mode.ts +14 -4
package/src/adapters/tool-catalog-nudge.ts +2 -2
package/src/bridge.ts +40 -24
package/src/claude/inbound.ts +21 -6
package/src/claude/outbound.ts +43 -26
package/src/cli/capabilities.ts +27 -0
package/src/cli/integrations.ts +1 -1
package/src/cli/models-runtime-subcommands.ts +2 -0
package/src/cli/models-runtime.ts +108 -1
package/src/cli/observe.ts +18 -3
package/src/cli/usage-report.ts +6 -1
package/src/clients/config-export.ts +5 -3
package/src/codex/auth-api.ts +36 -0
package/src/codex/catalog/provider-fetch.ts +2 -1
package/src/codex/quota-auto-refresh-state.ts +8 -0
package/src/codex/quota-auto-refresh.ts +157 -27
package/src/codex/warmup.ts +5 -0
package/src/config/provider-validation.ts +70 -1
package/src/config.ts +73 -1
package/src/generated/compatibility-version.json +67 -55
package/src/lib/json-byte-size.ts +61 -0
package/src/lib/provider-outbound.ts +11 -10
package/src/oauth/index.ts +42 -8
package/src/oauth/orcarouter.ts +200 -0
package/src/providers/key-store.ts +22 -0
package/src/providers/registry.ts +78 -29
package/src/responses/citation-markers.ts +56 -24
package/src/responses/reasoning-envelope.ts +53 -19
package/src/server/auth-cors.ts +8 -0
package/src/server/chat-completions.ts +7 -0
package/src/server/chat-native.ts +65 -3
package/src/server/claude-messages.ts +30 -10
package/src/server/effort-policy.ts +183 -1
package/src/server/management/agent-settings-routes.ts +50 -9
package/src/server/management/config-routes.ts +2 -0
package/src/server/management/logs-usage-routes.ts +11 -3
package/src/server/management/model-routes.ts +65 -1
package/src/server/management/model-rows.ts +5 -0
package/src/server/management/provider-routes.ts +99 -6
package/src/server/management/route-registry.ts +2 -0
package/src/server/management/usage-aggregate-cache.ts +14 -7
package/src/server/responses/compact.ts +3 -2
package/src/server/responses/core.ts +16 -2
package/src/server/startup-health-cache.ts +31 -9
package/src/types/config.ts +5 -0
package/src/types/provider.ts +4 -0
package/src/usage/cost.ts +27 -31
package/src/usage/summary.ts +52 -9
package/src/usage/time-range.ts +48 -0
package/src/usage/user-cost-overlays.ts +35 -3
package/src/vision/anthropic-describe.ts +46 -2
package/src/web-search/anthropic-executor.ts +49 -3
package/src/web-search/parse.ts +1 -1
package/gui/dist/assets/index-B72RPblC.js +0 -115
package/gui/dist/assets/index-BFgUC17B.css +0 -1

package/gui/dist/index.html CHANGED Viewed

@@ -16,8 +16,8 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-B72RPblC.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BFgUC17B.css">
+    <script type="module" crossorigin src="/assets/index-CNTWhC5F.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-B8ZZ0ivI.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.46.0",
+  "version": "2.47.0-preview.20260908",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",
@@ -24,6 +24,7 @@
     "assets/claude-code-models.gif",
     "assets/codex-app-picker.png",
     "README.md",
+    "SPONSORS.md",
     "AGENTS_INSTALL.md",
     "LICENSE"
   ],

package/src/adapters/cursor/protobuf-request.ts CHANGED Viewed

@@ -58,6 +58,7 @@ import {
   buildCursorToolDefinitions,
   cursorToolWireName,
   cursorRequestHasShellAlias,
+  cursorRequestUsesCodeMode,
   CURSOR_SHELL_ALIAS_SYSTEM_NOTE,
   OCX_RESPONSES_TOOL_PROVIDER,
 } from "./tool-definitions";
@@ -222,6 +223,7 @@ function assistantRootText(
 function rootPromptMessages(
   request: CursorRunRequest,
   requestScope: CursorBlobRequestScopeToken,
+  codeMode: boolean,
   /**
    * Calls indexed from the FULL history. The checkpoint path replays only a suffix of
    * `rawMessages`, so a result in that suffix can have its originating call before the cut; indexing
@@ -389,10 +391,10 @@ function rootPromptMessages(
       if (!echoToolResultInRoot) continue;
       // #1920: the prefix must reflect the NORMALIZED error state (an empty
       // node_repl result is an error even when the runtime said isError=false).
-      const prefix = normalizedToolResult(message, contentToText(message.content)).isError ? "[Tool Error]" : "[Tool Result]";
+      const prefix = normalizedToolResult(message, contentToText(message.content), codeMode).isError ? "[Tool Error]" : "[Tool Result]";
       // The bound compares in full-history space: this loop's `i` is already full-history on the
       // full-replay path, and `knownCallsOffset` re-bases it when only a suffix is replayed.
-      const text = `${prefix}\n${toolResultToText(message, callBefore(replayedCalls, decodeCursorCallId(message.toolCallId), knownCallsOffset + i))}`;
+      const text = `${prefix}\n${toolResultToText(message, callBefore(replayedCalls, decodeCursorCallId(message.toolCallId), knownCallsOffset + i), codeMode)}`;
       pushDeduped(toolResultRootPayload(text), "toolResult", { messageIndex: i, text }, text);
     }
   }
@@ -829,6 +831,7 @@ function countImages(parts: DecodedResultPart[] | undefined): number {
  */
 function toolResultContentItems(
   message: OcxToolResultMessage,
+  codeMode: boolean,
   decoded?: DecodedResultPart[],
   maxImages = Number.POSITIVE_INFINITY,
   normalizedText?: NormalizedToolResult,
@@ -839,10 +842,10 @@ function toolResultContentItems(
   })];
   if (!parts) {
     const normalized = normalizedText
-      ?? normalizedToolResult(message, typeof message.content === "string" ? message.content : "");
+      ?? normalizedToolResult(message, typeof message.content === "string" ? message.content : "", codeMode);
     return textItem(normalized.text);
   }
-  const normalized = normalizedText ?? normalizedDecodedTextResult(message, parts);
+  const normalized = normalizedText ?? normalizedDecodedTextResult(message, parts, codeMode);
   if (normalized) {
     // #1920/#1866: empty or failure-state Computer Use / node_repl results are
     // normalized before they reach the native wire. Pure-text part arrays use
@@ -1058,8 +1061,9 @@ function toolCallsByCallId(messages: readonly OcxMessage[]): Map<string, Extract
 function toolResultToText(
   message: OcxToolResultMessage,
   call?: Extract<OcxAssistantContentPart, { type: "toolCall" }>,
+  codeMode = false,
 ): string {
-  const normalized = normalizedToolResult(message, contentToText(message.content));
+  const normalized = normalizedToolResult(message, contentToText(message.content), codeMode);
   return [
     "[tool_result]",
     `call_id: ${decodeCursorCallId(message.toolCallId)}`,
@@ -1075,12 +1079,16 @@ function toolResultToText(
  * Shared #1920 normalization entry: pure-text results only. Image-bearing or
  * encrypted results pass through untouched (their content is not plain text).
  */
-function normalizedToolResult(message: OcxToolResultMessage, text: string): NormalizedToolResult {
-  if (message.containsEncryptedContent) return { text, isError: message.isError };
+function normalizedToolResult(message: OcxToolResultMessage, text: string, codeMode: boolean): NormalizedToolResult {
+  if (message.containsEncryptedContent
+    || (Array.isArray(message.content) && message.content.some(part => part.type !== "text"))) {
+    return { text, isError: message.isError };
+  }
   return normalizeCursorToolResultText(text, {
     toolName: message.toolName,
     toolNamespace: message.toolNamespace,
     isError: message.isError,
+    codeMode,
   });
 }
@@ -1092,9 +1100,10 @@ function normalizedToolResult(message: OcxToolResultMessage, text: string): Norm
 function normalizedDecodedTextResult(
   message: OcxToolResultMessage,
   parts: DecodedResultPart[],
+  codeMode: boolean,
 ): NormalizedToolResult | undefined {
   if (parts.some(part => part.kind !== "text")) return undefined;
-  return normalizedToolResult(message, parts.map(part => part.kind === "text" ? part.text : "").join("\n"));
+  return normalizedToolResult(message, parts.map(part => part.kind === "text" ? part.text : "").join("\n"), codeMode);
 }
 function argBytes(value: unknown): Uint8Array {
@@ -1109,6 +1118,7 @@ function toolCallStep(
   part: Extract<OcxAssistantContentPart, { type: "toolCall" }>,
   requestScope: CursorBlobRequestScopeToken,
   result?: OcxToolResultMessage,
+  codeMode = false,
 ): Uint8Array {
   const args: Record<string, Uint8Array> = {};
   for (const [key, value] of Object.entries(part.arguments ?? {})) args[key] = argBytes(value);
@@ -1130,7 +1140,7 @@ function toolCallStep(
               providerIdentifier: OCX_RESPONSES_TOOL_PROVIDER,
               args,
             }),
-            ...(result ? { result: toolResultPart(result, decodedResult, maxImages) } : {}),
+            ...(result ? { result: toolResultPart(result, codeMode, decodedResult, maxImages) } : {}),
           }),
         },
       }),
@@ -1151,17 +1161,17 @@ function toolCallStep(
   return storeCursorBlob(encoded, requestScope);
 }
-function toolResultPart(message: OcxToolResultMessage, decoded?: DecodedResultPart[], maxImages?: number) {
+function toolResultPart(message: OcxToolResultMessage, codeMode: boolean, decoded?: DecodedResultPart[], maxImages?: number) {
   const parts = decoded ?? decodeResultParts(message);
   const normalized = parts
-    ? normalizedDecodedTextResult(message, parts)
-    : normalizedToolResult(message, typeof message.content === "string" ? message.content : "");
+    ? normalizedDecodedTextResult(message, parts, codeMode)
+    : normalizedToolResult(message, typeof message.content === "string" ? message.content : "", codeMode);
   return create(McpToolResultSchema, {
     result: {
       case: "success",
       value: create(McpSuccessSchema, {
         isError: normalized?.isError ?? message.isError,
-        content: toolResultContentItems(message, parts, maxImages, normalized),
+        content: toolResultContentItems(message, codeMode, parts, maxImages, normalized),
       }),
     },
   });
@@ -1199,6 +1209,7 @@ function lastActionIndex(messages: readonly OcxMessage[] | undefined): number {
 function conversationTurns(
   request: CursorRunRequest,
   requestScope: CursorBlobRequestScopeToken,
+  codeMode: boolean,
   historyMessageStart = 0,
   /** Calls indexed from the FULL history; see {@link rootPromptMessages}. */
   knownCalls?: Map<string, Extract<OcxAssistantContentPart, { type: "toolCall" }>>,
@@ -1269,7 +1280,7 @@ function conversationTurns(
         // #1920/#1866: this external-replay site bypasses toolResultToText, so it
         // must consume the normalizer directly — cursor/grok-4.6 is the exact
         // reported repro path for empty Computer Use results.
-        const normalized = normalizedToolResult(message, contentToText(message.content));
+        const normalized = normalizedToolResult(message, contentToText(message.content), codeMode);
         const prefix = normalized.isError ? "[Tool Error]" : "[Tool Result]";
         // Name the invocation here as well, for the same reason the root replay does: a result with
         // no visible originating call reads as an interrupted attempt (devlog 260829 000_rca).
@@ -1285,13 +1296,13 @@ function conversationTurns(
       }
       const priorCall = pendingToolCalls.get(message.toolCallId);
       if (priorCall) {
-        current.steps.push(toolCallStep(priorCall, requestScope, message));
+        current.steps.push(toolCallStep(priorCall, requestScope, message, codeMode));
         pendingToolCalls.delete(message.toolCallId);
       } else {
         current.steps.push(storeCursorBlob(toBinary(ConversationStepSchema, create(ConversationStepSchema, {
           message: {
             case: "assistantMessage",
-            value: create(AssistantMessageSchema, { text: toolResultToText(message) }),
+            value: create(AssistantMessageSchema, { text: toolResultToText(message, undefined, codeMode) }),
           },
         })), requestScope));
       }
@@ -1368,6 +1379,9 @@ function buildPreparedCursorRunRequest(
   options?: { estimateInputTokens?: boolean },
 ): PreparedCursorRunRequest {
   const rawText = activePromptText(request);
+  // Use the same visible catalog as mcp_tools, including tool_choice, for every history path.
+  const visibleTools = cursorToolsForActivePrompt(request.tools, rawText, request.toolChoice);
+  const codeMode = cursorRequestUsesCodeMode(visibleTools, request.toolChoice);
   const lastRole = request.messages.at(-1)?.role;
   const text = lastRole === "user" || lastRole === "developer"
     ? appendCursorGenericToolUseHint(request.tools, rawText)
@@ -1471,7 +1485,7 @@ function buildPreparedCursorRunRequest(
         // against the raw limit left a band of a few hundred bytes below it where the checkpoint was kept,
         // the suffix budget collapsed, and the newest tool result vanished. Adding `systemBytes` moved the
         // band without closing it. Asking pruning what survived cannot drift from what pruning does.
-        const suffixRoots = rootPromptMessages(suffixRequest, requestScope, fullHistoryCalls, suffixStart, carriedRoots);
+        const suffixRoots = rootPromptMessages(suffixRequest, requestScope, codeMode, fullHistoryCalls, suffixStart, carriedRoots);
         const suffixSystemCount = systemPromptBlobs(suffixRequest).length;
         // A tool continuation whose own result did not survive is worthless: that result is the whole
         // reason the turn exists. "Kept SOMETHING" is not enough either — inside the band this fix first
@@ -1543,7 +1557,7 @@ function buildPreparedCursorRunRequest(
           // checkpoint is re-decoded and re-abandoned each turn until TTL, which is wasted work rather
           // than wrong output (audit r8 rounds 3 and 4).
         } else {
-        const suffixTurns = conversationTurns(suffixRequest, requestScope, suffixRoots.historyMessageStart, fullHistoryCalls, suffixStart);
+        const suffixTurns = conversationTurns(suffixRequest, requestScope, codeMode, suffixRoots.historyMessageStart, fullHistoryCalls, suffixStart);
         const suffixHistoryIds = suffixRoots.ids.slice(suffixSystemCount);
         const suffixHistorySerialized = suffixRoots.serialized.slice(suffixSystemCount);
         conversationState = create(ConversationStateStructureSchema, {
@@ -1573,10 +1587,10 @@ function buildPreparedCursorRunRequest(
     }
   }
   if (!conversationState) {
-    rootPromptMessagesState = rootPromptMessages(request, requestScope);
+    rootPromptMessagesState = rootPromptMessages(request, requestScope, codeMode);
     conversationState = create(ConversationStateStructureSchema, {
       rootPromptMessagesJson: rootPromptMessagesState.ids,
-      turns: conversationTurns(request, requestScope, rootPromptMessagesState.historyMessageStart),
+      turns: conversationTurns(request, requestScope, codeMode, rootPromptMessagesState.historyMessageStart),
       todos: [],
       pendingToolCalls: [],
       previousWorkspaceUris: [],
@@ -1590,7 +1604,6 @@ function buildPreparedCursorRunRequest(
   }
   // Hoisted out of the mcp_tools spread below so the estimate can read the same
   // filtered definitions the wire carries. Both helpers are pure.
-  const visibleTools = cursorToolsForActivePrompt(request.tools, rawText, request.toolChoice);
   const mcpToolDefs = buildCursorToolDefinitions(visibleTools, request.toolChoice);
   // The envelope is measured HERE, on the final root set, and nowhere else.
   //

package/src/adapters/cursor/tool-guidance.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import type { OcxRequestOptions, OcxTool } from "../../types";
-import { CODE_MODE_RESULT_ECHO_SENTENCE } from "../exec-tool-result-normalize";
+import { CODE_MODE_HOST_CONTRACT_SENTENCE, CODE_MODE_RESULT_ECHO_SENTENCE } from "../exec-tool-result-normalize";
 import { CODEX_SHELL_BRIDGE_TOOL_NAMES, CODEX_TOOL_SEARCH_TOOL, CODEX_UNIFIED_EXEC_TOOL, clientSemanticToolNameFromCursorWire, cursorRequestAdvertisesApplyPatch, cursorRequestHasExecutionPath, cursorRequestHasShellAlias, cursorRequestUsesCodeMode, cursorToolAllowedByChoice, cursorToolWireName, isCodexShellBridgeToolName, isCursorExecutionPathTool, isCursorStructuredEditToolName } from "./tool-naming";
 export const CURSOR_SHELL_ALIAS_SYSTEM_NOTE =
@@ -187,7 +187,7 @@ export function buildCursorToolGuidanceSystemNote(
       ? `\`${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` : ""}. Nested \`tools.apply_patch(input)\` is host-executed: the string must begin exactly with \`*** Begin Patch\` and end with \`*** End Patch\`, each marker line being three asterisks, one space, the two words, then end of line with no further asterisks. OpenCodex does not rewrite JavaScript inside exec, so extra asterisks on a marker line are rejected by Codex before the file is touched.`
       : undefined,
     codeMode
-      ? CODE_MODE_RESULT_ECHO_SENTENCE + " There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers."
+      ? CODE_MODE_RESULT_ECHO_SENTENCE + " There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers. " + CODE_MODE_HOST_CONTRACT_SENTENCE
       : undefined,
     codeMode
       ? "NEVER attempt Cursor-native Shell, Read, Grep, List, or any tool absent from the catalog — they are not executed in this environment and every probe wastes a turn. The exec code cell (with its nested helpers) is the ONLY execution surface; go to it directly on the FIRST attempt and do not narrate switching surfaces."

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

@@ -10,9 +10,12 @@
  */
 import {
+  CODE_MODE_HOST_RECOVERY_PREFIX,
   EMPTY_EXEC_OUTPUT_MESSAGE,
   EMPTY_EXEC_OUTPUT_REGEX,
   FAILED_EXEC_OUTPUT_MESSAGE,
+  annotateCodeModeHostFailure,
+  isCodexCodeModeExecResult,
   isFailedEmptyExecWrapper,
   isCodexExecBridgeTool,
 } from "../exec-tool-result-normalize";
@@ -83,7 +86,13 @@ export interface NormalizedToolResultText {
  */
 export function normalizeCursorToolResultText(
   text: string,
-  options: { toolName?: string; toolNamespace?: string; isError?: boolean } = {},
+  options: {
+    toolName?: string;
+    toolNamespace?: string;
+    isError?: boolean;
+    /** True only when the request's visible catalog is Codex code mode. */
+    codeMode?: boolean;
+  } = {},
 ): NormalizedToolResultText {
   const isError = options.isError === true;
   const computerUse = isNodeReplOrComputerUseTool(options.toolName, options.toolNamespace);
@@ -104,7 +113,18 @@ export function normalizeCursorToolResultText(
       changed: true,
     };
   }
-  if (!isError) {
+  // Replayed guidance and successful wrappers must not enter the legacy substring matcher.
+  if (text.includes(CODE_MODE_HOST_RECOVERY_PREFIX)
+    || /^(?:Script completed|Command finished|Execution finished)\b/.test(text.trimStart())) {
+    return { text, isError, changed: false };
+  }
+  // The request's visible catalog establishes provenance; the name alone also matches structured
+  // exec tools. Host guidance preserves Cursor's original error status.
+  if (options.codeMode === true && isCodexCodeModeExecResult(options.toolName, options.toolNamespace)) {
+    const hostFailure = annotateCodeModeHostFailure(text, options);
+    if (hostFailure !== undefined) return { text: hostFailure, isError, changed: true };
+  }
+  if (computerUse && !isError) {
     for (const { marker, guidance } of RUNTIME_FAILURE_GUIDANCE) {
       if (text.includes(marker)) {
         return { text: `${text}\n[recovery: ${guidance}]`, isError: true, changed: true };

package/src/adapters/exec-tool-result-normalize.ts CHANGED Viewed

@@ -115,6 +115,93 @@ export const EMPTY_EXEC_OUTPUT_MESSAGE =
 export const CODE_MODE_RESULT_ECHO_SENTENCE =
   "Nothing in the isolate is echoed automatically: a bare trailing `await tools.<name>(...)` or final expression value is DISCARDED, and the cell reports empty output. Pass anything you need to read to `text(...)` (or `notify(...)`) in the same cell — for example `text(JSON.stringify(await tools.exec_command({cmd: 'ls'})))` — and treat an empty result as your own missing `text(...)` call rather than a failed command or lost context.";
+/**
+ * Host rules a routed model most often breaks on its first code-mode edit or wait, stated BEFORE
+ * the call. Wording tracks the Codex host (0.153.2), probed live on 2026-09-07: a non-string
+ * argument to `apply_patch` throws "expects a string input"; a body whose first line is not the
+ * bare marker (decorated `*** Begin Patch ***`, a code fence, prose) throws "The first line of the
+ * patch must be '*** Begin Patch'" — surrounding newlines are tolerated; ES imports throw
+ * "Unsupported import in exec"; a command that outlives `yield_time_ms` returns `session_id` for
+ * `write_stdin` polling. xai/grok-4.6 hit the first two, abandoned apply_patch for heredoc writes,
+ * blocked a turn in a shell sleep loop, and died once on an import. None of that is repairable in
+ * the proxy (devlog/_plan/260905_apply_patch_envelope_gap/010 MODE B); it is a contract the proxy
+ * had not stated.
+ */
+export const CODE_MODE_HOST_CONTRACT_SENTENCE =
+  "Host contract for the nested helpers: `tools.apply_patch(patch)` takes exactly one string, never an object such as `{input: ...}`; the patch text opens with the bare marker line `*** Begin Patch` and closes with the bare marker line `*** End Patch`, written without a code fence, prose, or extra asterisks on those lines (blank lines or indentation around the markers are tolerated; a decorated or missing marker is rejected). The isolate has no `import`, `require`, or module loader; use the globals the exec tool description lists (for example `tools`, `text`, `notify`, `store`/`load`, `ALL_TOOLS`). For a command that may outlive `yield_time_ms`, let `tools.exec_command` return a `session_id` and poll it on later calls with `tools.write_stdin({session_id, chars: \"\"})` instead of blocking a shell in a sleep loop.";
+/**
+ * Post-hoc half of the host contract: the four host strings a routed model reads inside a
+ * non-error exec result, each paired with the rule it broke. Matched case-insensitively because
+ * the host writes "Unsupported import in exec: <spec>" while Cursor's earlier marker was
+ * lowercase; one table, one owner, so this text and the pre-call sentence cannot drift.
+ */
+export const CODE_MODE_HOST_FAILURE_GUIDANCE: ReadonlyArray<{ marker: string; guidance: string }> = [
+  {
+    marker: "expects a string input",
+    guidance: "tools.apply_patch takes exactly one string argument; pass the patch text itself, not an object such as {input: ...}.",
+  },
+  {
+    marker: "the first line of the patch must be",
+    guidance: "The patch text must open with the bare marker line `*** Begin Patch`: no code fence, prose, or extra asterisks on that line (blank lines or indentation before it are tolerated).",
+  },
+  {
+    marker: "the last line of the patch must be",
+    guidance: "The patch text must close with the bare marker line `*** End Patch`: no trailing text or extra asterisks on that line (blank lines after it are tolerated).",
+  },
+  {
+    marker: "unsupported import in exec",
+    guidance: "Imports are not available in this exec context; use the injected globals (tools, text, notify, store, load, ALL_TOOLS) instead.",
+  },
+];
+/** Prefix of every recovery line this module appends; callers use it to recognise replayed annotations. */
+export const CODE_MODE_HOST_RECOVERY_PREFIX = "[recovery: ";
+// Only a leading failure envelope or a complete host diagnostic establishes error context.
+// Do not search for this prefix inside output: successful source reads can quote any of these.
+const CODE_MODE_HOST_ERROR_PREFIX = /^(?:Script failed(?:[ \t]*(?:\r?\n|$)|:)|Script error:|(?:Error|TypeError|SyntaxError):|tool `apply_patch` expects a string input\b|apply_patch verification failed:|Unsupported import in exec:)/i;
+/** Namespaces under which Cursor displays Codex's own Responses tools (see cursor/tool-naming.ts). */
+const CODEX_RESPONSES_DISPLAY_NAMESPACES: ReadonlySet<string> = new Set(["opencodex-responses", "mcp__opencodex-responses"]);
+/** Flattened spellings of the same code-mode exec when a client folds the namespace into the name. */
+const CODEX_CODE_MODE_EXEC_ALIASES: ReadonlySet<string> = new Set(["exec", "mcp__opencodex-responses__exec", "mcp_opencodex-responses_exec"]);
+/**
+ * The code-mode `exec` tool by NAME — bare, or under Codex's own `opencodex-responses` display
+ * namespace, matched exactly. The four host strings above originate only in that isolate, so flat
+ * shell bridges (`exec_command`, `shell`, …) and every other namespace (`mcp__docker`,
+ * `mcp__foreign-opencodex-responses`) are excluded: an unrelated server's output that quotes the
+ * phrase must not receive Codex guidance. Narrower than `isCodexExecBridgeTool` on purpose; the
+ * empty-output repair keeps the wider gate. Callers that KNOW the catalog shape (Kiro's
+ * `codeModeExecName`, the Responses body gate) add that check on top; this predicate alone cannot
+ * tell a structured tool named `exec` from the freeform one.
+ */
+export function isCodexCodeModeExecResult(toolName?: string, toolNamespace?: string): boolean {
+  if (!toolName) return false;
+  const lower = toolName.toLowerCase();
+  if (toolNamespace !== undefined) return CODEX_RESPONSES_DISPLAY_NAMESPACES.has(toolNamespace) && lower === "exec";
+  return CODEX_CODE_MODE_EXEC_ALIASES.has(lower);
+}
+/**
+ * Append a one-line recovery hint when a code-mode exec result starts with a host error context
+ * and carries a known diagnostic. Successful wrappers and unframed phrase quotations pass through.
+ * Returns undefined when the tool/context/marker does not match or a recovery line is already
+ * present (a replayed result must not grow a second one). Never touches error status.
+ */
+export function annotateCodeModeHostFailure(
+  text: string,
+  options: { toolName?: string; toolNamespace?: string } = {},
+): string | undefined {
+  if (!isCodexCodeModeExecResult(options.toolName, options.toolNamespace)) return undefined;
+  if (text.includes(CODE_MODE_HOST_RECOVERY_PREFIX)) return undefined;
+  if (!CODE_MODE_HOST_ERROR_PREFIX.test(text.trimStart())) return undefined;
+  const lower = text.toLowerCase();
+  const hit = CODE_MODE_HOST_FAILURE_GUIDANCE.find(({ marker }) => lower.includes(marker));
+  return hit ? `${text}\n${CODE_MODE_HOST_RECOVERY_PREFIX}${hit.guidance}]` : undefined;
+}
 /**
  * Codex exec / shell-bridge tool names (flat and MCP-prefixed display aliases). An empty result
  * here is almost always a code-mode cell that never called text()/notify().

package/src/adapters/kiro.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 import { decodeEventStream } from "../lib/eventstream-decoder";
 import { estimateTokens } from "../lib/token-estimate";
 import { debugProviderDiagnostic } from "../lib/debug";
+import { isDebugEnabled } from "../lib/debug-settings";
 import { resolveKiroApiRegion, resolveKiroRequestProfile } from "../oauth/kiro";
 import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
 import { modelRecordValue } from "../reasoning-effort";
@@ -44,7 +45,7 @@ import { extractKiroImages, normalizeKiroImages, type KiroImage } from "./kiro-i
 import { sniffImageDimensions } from "./anthropic-image-guard";
 import { fetchKiroWithRetry, noteKiroTransientThrottle } from "./kiro-retry";
 import { convertKiroToolContext } from "./kiro-tools";
-import { EMPTY_EXEC_OUTPUT_MESSAGE, normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize";
+import { EMPTY_EXEC_OUTPUT_MESSAGE, annotateCodeModeHostFailure, normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize";
 import { identifyRoutedModel } from "./identity";
 import { buildNonOpenAIToolCatalogNudgeFromNames, isBareShellBridgeTool, isCodexCodeModeExecTool } from "./tool-catalog-nudge";
 import {
@@ -755,11 +756,17 @@ export function buildKiroPayload(
       // the task instead of calling text()/notify(). Checked before `text.trim()` because the
       // wrapper form ("Script completed\nWall time ...\nOutput:\n") is non-blank and would
       // otherwise pass through as if it were real output.
-      const normalizedExecText = normalizeEmptyExecToolResultText(text, {
-        toolName: tr.toolName,
-        toolNamespace: tr.toolNamespace,
-      });
-      const resultText = normalizedExecText ?? (text.trim() ? text : KIRO_EMPTY_TOOL_RESULT_MESSAGE);
+      const execOptions = { toolName: tr.toolName, toolNamespace: tr.toolNamespace };
+      const normalizedExecText = normalizeEmptyExecToolResultText(text, execOptions);
+      // A host failure string inside a non-empty exec result gets the rule it broke appended, but
+      // only when this request's emitted catalog is genuinely code mode (`codeModeExecName` above):
+      // a structured tool named exec, or exec beside a shell bridge, never ran the isolate. This is
+      // the only substitution the grouping path below also carries: whitespace and empty/failed
+      // wrappers keep their existing raw policy.
+      const annotatedExecText = normalizedExecText === undefined && codeModeExecName !== undefined
+        ? annotateCodeModeHostFailure(text, execOptions)
+        : undefined;
+      const resultText = normalizedExecText ?? annotatedExecText ?? (text.trim() ? text : KIRO_EMPTY_TOOL_RESULT_MESSAGE);
       const images = extractKiroImages(tr.content);
       const toolUseId = normalizeToolId(tr.toolCallId);
       const call = priorCalls.get(toolUseId);
@@ -768,7 +775,7 @@ export function buildKiroPayload(
       }
       // Keep real whitespace and failed wrappers, but no empty-success wrapper boilerplate.
       const rawGroupText = text.length > 0 && (!text.trim() || normalizedExecText !== EMPTY_EXEC_OUTPUT_MESSAGE)
-        ? text : undefined;
+        ? (annotatedExecText ?? text) : undefined;
       const last = turns.at(-1);
       if (
         adjacentResult?.rawId === tr.toolCallId
@@ -2114,17 +2121,21 @@ export function createKiroAdapter(provider: OcxProviderConfig): ProviderAdapter
     const rawContextInputEstimate = estimateKiroPayloadInputTokens(built.payload, parsed.modelId);
     const contextInputEstimate = calibrateKiroEstimate(built.conversationId, rawContextInputEstimate);
     const body = JSON.stringify(built.payload);
-    debugProviderDiagnostic("kiro", "request", {
-      region,
-      requestedModel: parsed.modelId,
-      completionMode: built.completionMode,
-      bodyBytes: new TextEncoder().encode(body).length,
-      messageCount: kiroPayloadMessages(parsed).length,
-      toolCount: parsed.context.tools?.length ?? 0,
-      hasProfileArn: Boolean(profileArn),
-      wireClient,
-      hasPreviousResponseId: Boolean(parsed.previousResponseId),
-    });
+    // Every field below is evaluated before the call, so an unguarded call re-encodes the
+    // whole request body on each request even when provider debug is off. Gate the details.
+    if (isDebugEnabled()) {
+      debugProviderDiagnostic("kiro", "request", {
+        region,
+        requestedModel: parsed.modelId,
+        completionMode: built.completionMode,
+        bodyBytes: new TextEncoder().encode(body).length,
+        messageCount: kiroPayloadMessages(parsed).length,
+        toolCount: parsed.context.tools?.length ?? 0,
+        hasProfileArn: Boolean(profileArn),
+        wireClient,
+        hasPreviousResponseId: Boolean(parsed.previousResponseId),
+      });
+    }
     return {
       request: {
         url: kiroRuntimeEndpoint(provider, region),

package/src/adapters/responses-code-mode.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import { toolChoiceToolPredicate, type OcxParsedRequest, type OcxProviderConfig } from "../types";
 import { isOpenAiOperatedResponsesDestination } from "../providers/openai-tiers";
-import { CODE_MODE_RESULT_ECHO_SENTENCE, normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize";
+import { CODE_MODE_HOST_CONTRACT_SENTENCE, CODE_MODE_RESULT_ECHO_SENTENCE, annotateCodeModeHostFailure, normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize";
 import { isBareShellBridgeTool, isCodexCodeModeExecTool } from "./tool-catalog-nudge";
 function record(value: unknown): value is Record<string, unknown> {
@@ -29,6 +29,14 @@ function withExecInputGuidance(tool: unknown): unknown {
   } } };
 }
+/** Append each sentence a replayed instructions string does not already carry, in order. */
+function appendMissing(instructions: string, sentences: readonly string[]): string {
+  return sentences.reduce(
+    (acc, sentence) => acc.includes(sentence) ? acc : [acc, sentence].filter(Boolean).join("\n\n"),
+    instructions,
+  );
+}
 /** Native routed Responses needs the same first-call/output contract as translated adapters. */
 export function normalizeResponsesCodeMode(body: unknown, parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown {
   if (!record(body) || parsed._compactionRequest || isOpenAiOperatedResponsesDestination(provider)) return body;
@@ -42,8 +50,7 @@ export function normalizeResponsesCodeMode(body: unknown, parsed: OcxParsedReque
     .map(item => item.call_id));
   return {
     ...body,
-    instructions: instructions.includes(CODE_MODE_RESULT_ECHO_SENTENCE)
-      ? instructions : [instructions, CODE_MODE_RESULT_ECHO_SENTENCE].filter(Boolean).join("\n\n"),
+    instructions: appendMissing(instructions, [CODE_MODE_RESULT_ECHO_SENTENCE, CODE_MODE_HOST_CONTRACT_SENTENCE]),
     ...(Array.isArray(body.tools) ? { tools: body.tools.map(withExecInputGuidance) } : {}),
     ...(input ? { input: input.map(item => {
       if (!record(item)) return item;
@@ -52,7 +59,10 @@ export function normalizeResponsesCodeMode(body: unknown, parsed: OcxParsedReque
       }
       if ((item.type !== "function_call_output" && item.type !== "custom_tool_call_output") || !execCalls.has(item.call_id)) return item;
       const text = textOnlyOutput(item.output);
-      const normalized = text === undefined ? undefined : normalizeEmptyExecToolResultText(text, { toolName: "exec" });
+      const normalized = text === undefined
+        ? undefined
+        : normalizeEmptyExecToolResultText(text, { toolName: "exec" })
+          ?? annotateCodeModeHostFailure(text, { toolName: "exec" });
       return normalized === undefined ? item : { ...item, output: normalized };
     }) } : {}),
   };

package/src/adapters/tool-catalog-nudge.ts CHANGED Viewed

@@ -5,7 +5,7 @@ import {
   type OcxTool,
   type OcxProviderConfig,
 } from "../types";
-import { CODE_MODE_RESULT_ECHO_SENTENCE } from "./exec-tool-result-normalize";
+import { CODE_MODE_HOST_CONTRACT_SENTENCE, CODE_MODE_RESULT_ECHO_SENTENCE } from "./exec-tool-result-normalize";
 // Tool names that exist only in OTHER agent harnesses (Claude Code and friends). Naming one
 // here tells a routed model not to call it unless this turn's catalog really lists it.
@@ -121,7 +121,7 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(
     "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
     "Names mentioned only in instructions, tool descriptions, argument descriptions, or nested helper APIs are not additional top-level tools.",
     verifiedCodeModeExecName
-      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. " + CODE_MODE_RESULT_ECHO_SENTENCE + " Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch`, each marker line being three asterisks, one space, the two words, then end of line with no further asterisks. OpenCodex does not rewrite JavaScript inside exec, so extra asterisks on a marker line are rejected by Codex before the file is touched."
+      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. " + CODE_MODE_RESULT_ECHO_SENTENCE + " Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch`, each marker line being three asterisks, one space, the two words, then end of line with no further asterisks. OpenCodex does not rewrite JavaScript inside exec, so extra asterisks on a marker line are rejected by Codex before the file is touched. " + CODE_MODE_HOST_CONTRACT_SENTENCE
       : "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
     unavailableNeighborNames.length > 0
       ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."