@yansigit/opencodex 2.32.0 → 2.33.0

package/src/adapters/base.ts

@@ -19,6 +19,8 @@ export interface IncomingMeta {
    * anthropic adapter consumes it; others ignore it.
    */
   imageTierBias?: number;
+  /** Provider-scoped structured error observation; never receives ordinary model payloads. */
+  onProviderError?: (error: { code?: string; status?: number; message?: string }) => void;
 }
 
 export interface ProviderAdapter {
@@ -81,7 +83,7 @@ export interface AdapterRequest {
     /** Client tool-search names actually lowered to upstream function calls for this request. */
     convertedRoutedToolSearchNames?: ReadonlySet<string>;
     /** Upstream-only aliases for namespace tools flattened in this request. */
-    convertedRoutedNamespaceToolAliases?: ReadonlyMap<string, { namespace: string; name: string }>;
+    convertedRoutedNamespaceToolAliases?: ReadonlyMap<string, { namespace: string; name: string; kind: "function" | "custom" }>;
     /** Releases observation of a serialized request body after its final fetch attempt settles. */
     releaseBodyObservation?: () => void;
     /** Exact reasoning parameter emitted by the adapter, for request-log diagnostics only. */

package/src/adapters/command-code.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { opendir } from "node:fs/promises";
@@ -12,7 +12,7 @@ import { commandCodeReasoningEfforts, refreshCommandCodeReasoningEfforts } from
 import { identifyRoutedModel } from "./identity";
 import { buildNonOpenAIToolCatalogNudgeForTools } from "./tool-catalog-nudge";
 import { parseDataUrl } from "./image";
-import { EMPTY_COMMAND_CODE_PROJECT_CONTEXT, loadCommandCodeProjectContext } from "./command-code-project-context";
+import { redactSecretString } from "../lib/redact";
 
 // Retain the short ids emitted by the first local integration. New requests use the live catalog's
 // provider-native IDs directly; this map is compatibility-only and is not a model fallback list.
@@ -27,6 +27,23 @@ function canonicalCommandCodeModelId(modelId: string): string {
   return Object.hasOwn(COMMAND_CODE_MODEL_ALIASES, modelId) ? COMMAND_CODE_MODEL_ALIASES[modelId]! : modelId;
 }
 
+/** Surface Command Code's JSON error message to sidecar callers instead of a bare HTTP status. */
+export function formatCommandCodeErrorBody(_status: number, _headers: Headers, payloadText: string): string {
+  try {
+    const payload = JSON.parse(payloadText) as unknown;
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return "";
+    const error = (payload as Record<string, unknown>).error;
+    const message = error && typeof error === "object" && !Array.isArray(error)
+      ? (error as Record<string, unknown>).message
+      : undefined;
+    return typeof message === "string" && message.trim()
+      ? redactSecretString(message.trim()).slice(0, 400)
+      : "";
+  } catch {
+    return "";
+  }
+}
+
 /** Flatten tool-result content for the text-only wire output, keeping an `[image]` marker per image part in content order. */
 function toolResultText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
@@ -210,6 +227,24 @@ function projectSlug(cwd: string): string {
   return cwd.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase().slice(0, 64) || "workspace";
 }
 
+export function commandCodeSessionId(parsed: OcxParsedRequest): string {
+  // Shared prompt-cache cohorts intentionally do not identify one conversation. Keep them out
+  // of upstream session affinity or unrelated conversations can pin to the same worker.
+  const threadId = parsed._clientThreadId?.trim();
+  const replayId = parsed._reasoningReplayScope?.clientThreadId?.trim();
+  const cacheKey = !parsed._promptCacheKeyIsSharedCohort ? parsed.options.promptCacheKey?.trim() : undefined;
+  const identity = threadId
+    ? ["thread", threadId]
+    : replayId
+      ? ["replay", replayId]
+      : cacheKey
+        ? ["cache", cacheKey]
+        : undefined;
+  if (!identity) return randomUUID();
+  const hex = createHash("sha256").update(`command-code:${identity[0]}\0${identity[1]}`).digest("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+
 interface GitWorkspaceInfo {
   isGitRepo: boolean;
   currentBranch: string;
@@ -451,6 +486,7 @@ export function createCommandCodeAdapter(provider: OcxProviderConfig): ProviderA
   const executor = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
   return {
     name: "command-code",
+    formatErrorBody: formatCommandCodeErrorBody,
     async buildRequest(parsed: OcxParsedRequest): Promise<AdapterRequest> {
       if (!provider.apiKey) throw new Error("Command Code credential missing — run ocx login command-code");
       const cwd = currentWorkingDirectory();
@@ -463,11 +499,8 @@ export function createCommandCodeAdapter(provider: OcxProviderConfig): ProviderA
         ...(choiceInstruction ? [choiceInstruction] : []),
       ].join("\n\n"), parsed.modelId);
       const reasoningEffort = supportedCommandCodeEffort(provider, parsed.modelId, parsed.options.reasoning);
-      const projectContext = provider.projectContext === "on"
-        ? await loadCommandCodeProjectContext(cwd)
-        : EMPTY_COMMAND_CODE_PROJECT_CONTEXT;
       const body = {
-        config: await commandCodeConfig(cwd), ...projectContext,
+        config: await commandCodeConfig(cwd), memory: "", taste: null, skills: null,
         permissionMode: "standard", mode: "agent",
         params: {
           model: canonicalCommandCodeModelId(parsed.modelId),
@@ -490,7 +523,7 @@ export function createCommandCodeAdapter(provider: OcxProviderConfig): ProviderA
         "x-cli-environment": "production",
         "x-taste-learning": "false",
         "x-co-flag": "false",
-        "x-session-id": randomUUID(),
+        "x-session-id": commandCodeSessionId(parsed),
       };
       if (cwd) headers["x-project-slug"] = projectSlug(cwd);
       return {

package/src/adapters/cursor/live-transport.ts

@@ -108,7 +108,7 @@ const CURSOR_STREAM_SILENCE_FAIL_MS = 30_000;
  * for this long is equally stuck — the server is alive but the turn is not progressing.
  * Reset on every decoded frame that is not liveness-only.
  */
-const CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS = 90_000;
+const CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS = 180_000;
 /**
  * After `turnEnded` is decoded, the application turn is complete. A server that keeps
  * HTTP/2 open past this point cannot hold the turn hostage (senpi #1062): we close our side

package/src/adapters/cursor/protobuf-events.ts

@@ -176,6 +176,7 @@ export interface CursorProtobufEventState {
    */
   syntheticStructuredEditToolNames?: ReadonlySet<string>;
   translatorBudget?: TranslatorBudget;
+  textToolCallBuffer?: string;
 }
 
 
@@ -329,7 +330,7 @@ function isCompleteJson(text: string): boolean {
 
 /** Schema-normalize a JSON-text argument blob for a named tool, if a schema is known. */
 function normalizeJsonText(text: string, toolName: string | undefined, state: CursorProtobufEventState): string {
-  const schema = toolSchemaForWireName(state, toolName);
+  const schema = toolSchemaForWireName(state, toolName) ?? (toolName ? defaultShellBridgeArgNormalizeSchema(toolName) : undefined);
   if (!schema) return text;
   try {
     const parsed = JSON.parse(text);
@@ -1240,14 +1241,159 @@ export function mapCursorProtobufServerMessage(
     return [];
   }
 
+const TOOL_CALL_START_PREFIX = "[TOOL_CALL]";
+const TOOL_CALL_ARGS_MARKER = "[ARGS]";
+
+function findPotentialMarkerPrefix(text: string): number {
+  for (let len = Math.min(TOOL_CALL_START_PREFIX.length - 1, text.length); len >= 1; len--) {
+    const candidate = text.slice(text.length - len);
+    if (TOOL_CALL_START_PREFIX.startsWith(candidate)) {
+      return text.length - len;
+    }
+  }
+  return -1;
+}
+
+function parseCursorTextToolCalls(text: string, state: CursorProtobufEventState): CursorServerMessage[] {
+  if (!state.clientToolNames) {
+    return text ? [{ type: "text", text: normalizeCursorTextToolMarkers(text) }] : [];
+  }
+
+  let remaining = (state.textToolCallBuffer ?? "") + text;
+  state.textToolCallBuffer = undefined;
+
+  if (!remaining) return [];
+
+  const out: CursorServerMessage[] = [];
+
+  while (remaining.length > 0) {
+    const startIndex = remaining.indexOf(TOOL_CALL_START_PREFIX);
+    if (startIndex === -1) {
+      const partialIndex = findPotentialMarkerPrefix(remaining);
+      if (partialIndex !== -1) {
+        if (partialIndex > 0) {
+          out.push({ type: "text", text: normalizeCursorTextToolMarkers(remaining.slice(0, partialIndex)) });
+        }
+        state.textToolCallBuffer = remaining.slice(partialIndex);
+        break;
+      }
+      out.push({ type: "text", text: normalizeCursorTextToolMarkers(remaining) });
+      break;
+    }
+
+    // Check if the candidate at startIndex is actually a tool call
+    const candidateAfter = remaining.slice(startIndex + TOOL_CALL_START_PREFIX.length);
+    const argsPos = candidateAfter.indexOf(TOOL_CALL_ARGS_MARKER);
+    const namePart = argsPos !== -1 ? candidateAfter.slice(0, argsPos).trim() : candidateAfter;
+    const isCandidateValid = namePart.length > 0 && namePart.length <= 64 && /^[a-zA-Z0-9_-]+$/.test(namePart);
+
+    if (!isCandidateValid && argsPos === -1) {
+      // Not a valid tool call and no [ARGS]; treat as plain text
+      out.push({ type: "text", text: normalizeCursorTextToolMarkers(remaining) });
+      break;
+    }
+
+    if (startIndex > 0) {
+      out.push({ type: "text", text: normalizeCursorTextToolMarkers(remaining.slice(0, startIndex)) });
+      remaining = remaining.slice(startIndex);
+      continue;
+    }
+
+    const argsMarkerIndex = remaining.indexOf(TOOL_CALL_ARGS_MARKER, TOOL_CALL_START_PREFIX.length);
+    if (argsMarkerIndex === -1) {
+      const nameCandidate = remaining.slice(TOOL_CALL_START_PREFIX.length);
+      if (nameCandidate.length > 64 || /[^a-zA-Z0-9_-]/.test(nameCandidate)) {
+        out.push({ type: "text", text: normalizeCursorTextToolMarkers(remaining) });
+        break;
+      }
+      state.textToolCallBuffer = remaining;
+      break;
+    }
+
+    const rawName = remaining.slice(TOOL_CALL_START_PREFIX.length, argsMarkerIndex).trim();
+    const wireName = normalizeCursorWireName(rawName);
+    const advertisedName = resolveAdvertisedClientToolName(state, wireName);
+
+    if (!advertisedName) {
+      const endOfMarker = argsMarkerIndex + TOOL_CALL_ARGS_MARKER.length;
+      out.push({ type: "text", text: normalizeCursorTextToolMarkers(remaining.slice(0, endOfMarker)) });
+      remaining = remaining.slice(endOfMarker);
+      continue;
+    }
+
+    const argsStart = argsMarkerIndex + TOOL_CALL_ARGS_MARKER.length;
+    let argsEnd = -1;
+    const trimmedOffset = remaining.slice(argsStart).search(/\S/);
+    if (trimmedOffset !== -1 && remaining[argsStart + trimmedOffset] === "{") {
+      let depth = 0;
+      let inString = false;
+      let escape = false;
+      const jsonStart = argsStart + trimmedOffset;
+      for (let i = jsonStart; i < remaining.length; i++) {
+        const char = remaining[i];
+        if (escape) {
+          escape = false;
+          continue;
+        }
+        if (char === "\\") {
+          escape = true;
+          continue;
+        }
+        if (char === '"') {
+          inString = !inString;
+          continue;
+        }
+        if (!inString) {
+          if (char === "{") depth++;
+          else if (char === "}") {
+            depth--;
+            if (depth === 0) {
+              argsEnd = i + 1;
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    if (argsEnd === -1) {
+      state.textToolCallBuffer = remaining;
+      break;
+    }
+
+    const argsJson = remaining.slice(argsStart, argsEnd).trim();
+    const toolCallId = `call_${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
+
+    const recordEvents = recordToolCall(state, toolCallId, wireName);
+    out.push(...recordEvents);
+    if (!recordEvents.some(e => e.type === "error")) {
+      const open = state.openToolCalls.get(toolCallId);
+      if (open) open.args = argsJson;
+      let finalArgs = normalizeJsonText(argsJson, wireName, state);
+      if (state.freeformToolNames?.has(open?.name ?? "") && !cursorFreeformWrapperValid(finalArgs)) {
+        try {
+          const parsed = JSON.parse(finalArgs) as unknown;
+          if (typeof parsed === "string") {
+            finalArgs = JSON.stringify({ input: parsed });
+          }
+        } catch {
+          finalArgs = JSON.stringify({ input: finalArgs });
+        }
+      }
+      out.push(...commitToolCall(state, toolCallId, finalArgs));
+    }
+
+    remaining = remaining.slice(argsEnd);
+  }
+
+  return out;
+}
+
   if (serverMessage.message.case !== "interactionUpdate") return [];
   const update = serverMessage.message.value.message;
   switch (update.case) {
     case "textDelta":
-      // #2305: fold Cursor display aliases inside textual pseudo tool-call markers back to
-      // the advertised wire name before any client sees the text. Real frames are already
-      // normalized structurally (mcpWireNameFromArgs above).
-      return update.value.text ? [{ type: "text", text: normalizeCursorTextToolMarkers(update.value.text) }] : [];
+      return update.value.text ? parseCursorTextToolCalls(update.value.text, state) : [];
     case "thinkingDelta":
       return update.value.text ? [{ type: "thinking", thinking: update.value.text }] : [];
     case "toolCallStarted": {
@@ -1364,18 +1510,23 @@ export function resolvedTurnUsage(state: CursorProtobufEventState): OcxUsage {
  */
 export function finalizeTurnEvents(state: CursorProtobufEventState): CursorServerMessage[] {
   state.terminated = true;
+  const prefixEvents: CursorServerMessage[] = [];
+  if (state.textToolCallBuffer) {
+    prefixEvents.push({ type: "text", text: normalizeCursorTextToolMarkers(state.textToolCallBuffer) });
+    state.textToolCallBuffer = undefined;
+  }
   if (state.openToolCalls.size > 0) {
     const openCallIds = [...state.openToolCalls.keys()];
     const openIds = openCallIds.join(", ");
     // Clear so a second turnEnded (should not happen, but defensive) doesn't re-emit.
     for (const callId of openCallIds) state.translatorBudget?.closeCall(callId);
     state.openToolCalls.clear();
-    return [{ type: "error", message: `Cursor stream ended with incomplete tool call(s): ${openIds}. Arguments may be truncated; the call was not committed.` }];
+    return [...prefixEvents, { type: "error", message: `Cursor stream ended with incomplete tool call(s): ${openIds}. Arguments may be truncated; the call was not committed.` }];
   }
   // Surface the absolute context size (when Cursor reported a checkpoint) as both totalTokens and
   // the estimated input side of Codex's visible `input + output` counter. Codex status lines can
   // render the additive pair instead of total_tokens, so leaving inputTokens at 0 makes a 16k-context
   // first turn display as "9 used". Keep outputTokens as the per-turn delta and clamp the inferred
   // input to 0 in case Cursor reports a checkpoint smaller than the streamed output delta.
-  return [{ type: "done", usage: resolvedTurnUsage(state) }];
+  return [...prefixEvents, { type: "done", usage: resolvedTurnUsage(state) }];
 }

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

@@ -1,7 +1,7 @@
 import { create, fromBinary, toBinary, toJson } from "@bufbuild/protobuf";
 import { fromJson, type JsonValue } from "@bufbuild/protobuf";
 import { ValueSchema } from "@bufbuild/protobuf/wkt";
-import type { OcxAssistantContentPart, OcxMessage, OcxToolResultMessage } from "../../types";
+import type { OcxAssistantContentPart, OcxMessage, OcxRequestOptions, OcxToolResultMessage } from "../../types";
 import { namespacedToolName } from "../../types";
 import type { CursorRunRequest } from "./types";
 import { cursorNeedsExternalToolContinuation, isCursorExternalWireModel } from "./discovery";
@@ -165,9 +165,26 @@ function truncateToolResultBlob(entry: RootBlobCandidate, maxBytes: number): Roo
   return markerOnly.byteLength <= maxBytes ? markerOnly : null;
 }
 
+function structuredOutputPrompt(textFormat: OcxRequestOptions["textFormat"]): string | undefined {
+  if (!textFormat) return undefined;
+  if (textFormat.type === "json_schema" && textFormat.schema) {
+    return [
+      "Your response must be a single valid JSON object strictly conforming to this JSON schema:",
+      JSON.stringify(textFormat.schema),
+      "Do not include any surrounding markdown fences, preamble, or commentary; return raw JSON only.",
+    ].join("\n");
+  }
+  if (textFormat.type === "json_object") {
+    return "Your response must be a single valid JSON object. Do not include any markdown fences or commentary; return raw JSON only.";
+  }
+  return undefined;
+}
+
 function systemPromptBlobs(request: CursorRunRequest): RootBlobCandidate[] {
   const prompts = request.system.length > 0 ? [...request.system] : ["You are a helpful assistant."];
   if (cursorRequestHasShellAlias(request.tools)) prompts.push(CURSOR_SHELL_ALIAS_SYSTEM_NOTE);
+  const structuredPrompt = structuredOutputPrompt(request.textFormat);
+  if (structuredPrompt) prompts.push(structuredPrompt);
   const cursorToolGuidance = buildCursorToolGuidanceSystemNote(
     cursorToolsForActivePrompt(request.tools, activePromptText(request), request.toolChoice),
     request.toolChoice,
@@ -190,10 +207,11 @@ function assistantRootText(
 // Cursor builds the actual model prompt from rootPromptMessagesJson (turns[] is UI/display metadata),
 // so prior history must be replayed here or a ResumeAction has nothing model-visible to continue from.
 // The active user message is excluded because it travels in the action. When the continuation cannot
-// rely on native MCP turn state, tool results stay assistant-role text with a [Tool Result] /
-// [Tool Error] marker so Cursor does not wrap them as `<user_query>` (#1992). Native resume models
-// already carry the paired MCP result on turns[], so that marker is omitted from root replay — Auto
-// few-shot-mimics it as chat text otherwise. Each entry is a SHA-256 blob ID.
+// rely on native MCP turn state, tool results stay assistant-role text so Cursor does not wrap them
+// as `<user_query>` (#1992). External replay uses a neutral "Tool output" label; protocol markers
+// such as [Tool Result] are reserved for native wire encoding because external models echo them.
+// Native resume models already carry the paired MCP result on turns[], so it is omitted from root
+// replay. Each entry is a SHA-256 blob ID.
 function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobRequestScopeToken): {
   ids: Uint8Array[];
   byteLength: number;
@@ -246,14 +264,10 @@ function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobR
       }
       // Assistant tool CALLS are intentionally NOT replayed as visible "[Tool Call]" text here.
     } else if (message.role === "toolResult") {
-      // Native resume models already receive the paired MCP result through turns[]. Replaying
-      // the same payload as assistant-role "[Tool Result]" / "[tool_result]" text teaches Auto
-      // to echo that envelope as chat instead of continuing from the structured result.
+      // Native resume models already receive the paired MCP result through turns[]. External
+      // replay uses neutral text here so models do not echo protocol envelopes as chat.
       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 text = `${prefix}\n${toolResultToText(message)}`;
+      const text = externalToolResultToText(message);
       entries.push(rootBlobCandidate(
         toolResultRootPayload(text),
         "toolResult",
@@ -538,6 +552,12 @@ function toolResultToText(message: OcxToolResultMessage): string {
   ].join("\n");
 }
 
+function externalToolResultToText(message: OcxToolResultMessage): string {
+  const normalized = normalizedToolResult(message, contentToText(message.content));
+  const label = normalized.isError ? "Tool error" : "Tool output";
+  return `${label} for ${namespacedToolName(message.toolNamespace, message.toolName)} (call_id: ${message.toolCallId}, is_error: ${normalized.isError}):\n${normalized.text}`;
+}
+
 /**
  * Shared #1920 normalization entry: pure-text results only. Image-bearing or
  * encrypted results pass through untouched (their content is not plain text).
@@ -721,12 +741,10 @@ 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 prefix = normalized.isError ? "[Tool Error]" : "[Tool Result]";
         current.steps.push(storeCursorBlob(toBinary(ConversationStepSchema, create(ConversationStepSchema, {
           message: {
             case: "assistantMessage",
-            value: create(AssistantMessageSchema, { text: `${prefix}\n${normalized.text}` }),
+            value: create(AssistantMessageSchema, { text: externalToolResultToText(message) }),
           },
         })), requestScope));
         continue;

package/src/adapters/cursor/request-builder.ts

@@ -442,9 +442,10 @@ export function createCursorRequest(
     rawMessages: parsed.context.messages,
     ...(parsed._compactionRequest === true || parsed._contextCompactionBoundary === true ? { contextUsageReset: true } : {}),
     ...(parsed._compactionRequest === true ? { contextUsageStoreCheckpoints: false } : {}),
-    ...(budget.tools.length ? { tools: budget.tools } : {}),
-    ...(parsed.options.toolChoice ? { toolChoice: parsed.options.toolChoice } : {}),
-    ...(parsed.options.parallelToolCalls !== undefined ? { parallelToolCalls: parsed.options.parallelToolCalls } : {}),
+   ...(budget.tools.length ? { tools: budget.tools } : {}),
+   ...(parsed.options.toolChoice ? { toolChoice: parsed.options.toolChoice } : {}),
+    ...(parsed.options.textFormat ? { textFormat: parsed.options.textFormat } : {}),
+   ...(parsed.options.parallelToolCalls !== undefined ? { parallelToolCalls: parsed.options.parallelToolCalls } : {}),
   };
   const resolved = resolveCursorCheckpoint(parsed, request, options);
   if ("reason" in resolved) {

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

@@ -48,6 +48,24 @@ export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
     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." },
+    sandbox_permissions: {
+      type: "string",
+      enum: ["use_default", "require_escalated"],
+      description: "Per-command sandbox override. Defaults to use_default; use require_escalated for unsandboxed execution.",
+    },
+    justification: {
+      type: "string",
+      description: "User-facing approval question for require_escalated; omit otherwise.",
+    },
+    prefix_rule: {
+      type: "array",
+      items: { type: "string" },
+      description: "Reusable approval prefix for cmd, only with sandbox_permissions: require_escalated; for example [\"git\", \"pull\"].",
+    },
+    login: {
+      type: "boolean",
+      description: "True runs the shell with -l/-i semantics; false disables them. Defaults to true.",
+    },
   },
   required: ["cmd"],
   additionalProperties: false,
@@ -109,6 +127,10 @@ export const CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA = {
     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." },
+    sandbox_permissions: { type: "string" },
+    justification: { type: "string" },
+    prefix_rule: { type: "array" },
+    login: { type: "boolean" },
   },
   required: ["command"],
 } as const;
@@ -651,7 +673,7 @@ export function buildCursorToolGuidanceSystemNote(
     // 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` : ""}. Nested \`tools.apply_patch(input)\` is host-executed: the string must begin exactly with \`*** Begin Patch\` and end with \`*** End Patch\` (no trailing \`***\` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated \`*** Begin Patch ***\` envelope is rejected by Codex before the file is touched.`
+      ? `\`${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\"})\`. When commands require network access, file writes outside workspace, or fail due to sandbox/permission restrictions, pass \`sandbox_permissions: "require_escalated"\` and a clear \`justification: "..."\` to \`tools.exec_command\`. 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` : ""}. Your tool list may display tools under a longer \`mcp_opencodex-responses_*\` name; call whichever your list shows. Nested \`tools.apply_patch(input)\` is host-executed: the string must begin exactly with \`*** Begin Patch\` and end with \`*** End Patch\` (no trailing \`***\` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated \`*** Begin Patch ***\` envelope is rejected by Codex before the file is touched.`
       : 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."
@@ -665,6 +687,9 @@ export function buildCursorToolGuidanceSystemNote(
     hasBareExec
       ? `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,
+    hasBareExec
+      ? 'When a command requires network access, file writes outside workspace, or fails due to sandbox restrictions, include `sandbox_permissions: "require_escalated"` and `justification: "..."`.'
+      : 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.",
     hasBareExec
@@ -686,6 +711,7 @@ export function buildCursorToolGuidanceSystemNote(
       ? `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.",
+    "When pursuing a multi-step task, check, or verification, do not stop or narrate intended future actions in plain text; immediately call the tool to execute the next step until the task is complete.",
     hasBareExec
       ? `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,

package/src/adapters/cursor/types.ts

@@ -25,9 +25,10 @@ export interface CursorRunRequest {
    * hydration). History stays text-only. data: URLs only in this slice.
    */
   selectedImages?: readonly ResolvedCursorImage[];
-  tools?: OcxTool[];
-  toolChoice?: OcxRequestOptions["toolChoice"];
-  parallelToolCalls?: boolean;
+ tools?: OcxTool[];
+ toolChoice?: OcxRequestOptions["toolChoice"];
+  textFormat?: OcxRequestOptions["textFormat"];
+ parallelToolCalls?: boolean;
   /**
    * Clear provider-private context-usage carry-forward before this run. Used when Codex starts a
    * newly observed compacted context epoch, so pre-compaction totals are not over-reported while

package/src/adapters/cursor.ts

@@ -208,6 +208,14 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         };
 
         const runOnce = async (activeRequest: ReturnType<typeof createCursorRequest>) => {
+          const effort = _parsed.options.reasoning;
+          const isHeavyReasoning = effort === "high"
+            || effort === "max"
+            || effort === "xhigh"
+            || activeRequest.modelId.includes("grok-4.6")
+            || activeRequest.modelId.includes("kimi-k3")
+            || activeRequest.modelId.includes("opus-4-8");
+          const heartbeatOnlyMs = isHeavyReasoning ? 300_000 : 180_000;
           await runCursorTurnWithRetry(
             makeTransport,
             {
@@ -216,6 +224,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
               translatorBudget: incoming.translatorBudget,
               requestDeclaresFullAccess: cursorRequestDeclaresFullAccess(activeRequest),
               sessionId: activeRequest.conversationId,
+              streamHeartbeatOnlyFailMs: heartbeatOnlyMs,
               ...(incoming.providerFetch ? { fetch: incoming.providerFetch } : {}),
             },
             activeRequest,

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

@@ -38,9 +38,9 @@ const REPLAY_TTL_MS = 60 * 60 * 1000; // 1h
 export const ANTIGRAVITY_REPLAY_MAX_ENTRIES = 10_240;
 const REPLAY_EVICT_BATCH = 128;
 const REPLAY_MAX_CALLS_PER_SESSION = 256;
-export const ANTIGRAVITY_REPLAY_MAX_BYTES_PER_SESSION = 2 * 1024 * 1024;
+export const ANTIGRAVITY_REPLAY_MAX_BYTES_PER_SESSION = 8 * 1024 * 1024;
 export const ANTIGRAVITY_REPLAY_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
-const REPLAY_MAX_SIGNATURE_BYTES = 64 * 1024;
+const REPLAY_MAX_SIGNATURE_BYTES = 1024 * 1024;
 /** Fixed 64-hex outer key length, counted once per session entry. */
 const REPLAY_SESSION_KEY_BYTES = 64;
 const REPLAY_SNAPSHOT_FILE = "antigravity-replay.json";

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

@@ -11,6 +11,13 @@ import { antigravityUserAgent } from "./client-fingerprint";
  */
 export const ANTIGRAVITY_REQUEST_UA = antigravityUserAgent();
 
+/**
+ * Bypass sentinel for Google Cloud Code Assist (Antigravity).
+ * When a historical functionCall part lacks a thought_signature, Antigravity rejects
+ * the request with HTTP 400 unless this sentinel is provided.
+ */
+export const ANTIGRAVITY_SIGNATURE_BYPASS_SENTINEL = "skip_thought_signature_validator";
+
 /**
  * Whether a stored `OcxToolCall.thoughtSignature` is a REAL upstream Gemini signature versus a
  * foreign id that must not be forwarded to Gemini/Antigravity.

package/src/adapters/google-errors.ts

@@ -2,7 +2,10 @@ import { parseUpstreamJsonPayload, safeUpstreamErrorString, sanitizeUpstreamErro
 
 /** Pull the human detail out of the Google API error envelope `{error:{message,status,code}}`. */
 function googleErrorDetail(payloadText: string): { message?: string; status?: string } {
-  const trimmed = payloadText.trim();
+  let trimmed = payloadText.trim();
+  if (trimmed.startsWith("data:")) {
+    trimmed = trimmed.replace(/^data:\s*/, "").trim();
+  }
   if (!trimmed || (!trimmed.startsWith("{") && !trimmed.startsWith("["))) {
     return { message: trimmed || undefined };
   }
@@ -18,7 +21,8 @@ function googleErrorDetail(payloadText: string): { message?: string; status?: st
 const ANTIGRAVITY_GEO_BLOCKED_MARKER = "user location is not supported for the api use";
 
 export function isAntigravityGeoBlockedBody(payloadText: string): boolean {
-  return payloadText.toLowerCase().includes(ANTIGRAVITY_GEO_BLOCKED_MARKER);
+  const lower = payloadText.toLowerCase();
+  return lower.includes(ANTIGRAVITY_GEO_BLOCKED_MARKER) || lower.includes("location is not supported");
 }
 
 function classifyGoogle(label: string, status: number | undefined, enumStatus: string | undefined, text: string): string {