@yansigit/opencodex 2.31.0

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-retry.ts

@@ -0,0 +1,132 @@
+import type { CursorRunRequest, CursorServerMessage } from "./types";
+import type { CursorTransport, CursorTransportFactory, CursorTransportFactoryInput } from "./transport";
+import { abortError, retryBackoffDelayMs, sleepWithAbort } from "../../lib/upstream-retry";
+import { debugProviderDiagnostic } from "../../lib/debug";
+import { safeCursorErrorMessage } from "./cursor-errors";
+
+// Compat: historical name for the shared abortable sleep, kept for external callers.
+export { sleepWithAbort as abortAwareSleep } from "../../lib/upstream-retry";
+
+export const CURSOR_RETRY_ATTEMPTS = 3;
+export const CURSOR_RETRY_BASE_MS = 250;
+export const CURSOR_RETRY_MAX_MS = 2_000;
+
+/**
+ * True only for clearly transient failures that occur BEFORE the run request is committed to the
+ * wire (connection refused/reset/timeout, immediate HTTP/2 GOAWAY, gRPC/Connect "unavailable").
+ * Conservative by design: auth, invalid-request, and anything ambiguous is non-retryable so we
+ * never replay a turn the Cursor server might already have accepted.
+ */
+export function isRetryableCursorError(err: unknown): boolean {
+  const code = typeof err === "object" && err && "code" in err ? String((err as { code?: unknown }).code ?? "") : "";
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  const haystack = `${code} ${message}`.toLowerCase();
+  if (/auth|unauthor|forbidden|invalid|permission|denied|not found|unsupported/.test(haystack)) return false;
+  if (/resource.exhausted|resource_exhausted|rate limit|too many requests|throttl/.test(haystack)) return false;
+  if (haystack.includes("nghttp2_cancel") || haystack.includes("stream suspended")) return false;
+  return (
+    haystack.includes("econnreset") ||
+    haystack.includes("econnrefused") ||
+    haystack.includes("etimedout") ||
+    haystack.includes("enetunreach") ||
+    haystack.includes("eai_again") ||
+    haystack.includes("goaway") ||
+    (haystack.includes("nghttp2") && !haystack.includes("nghttp2_cancel")) ||
+    haystack.includes("socket hang up") ||
+    haystack.includes("connection reset") ||
+    haystack.includes("unavailable") ||
+    haystack.includes("timed out")
+  );
+}
+
+export function cursorRetryDelayMs(attempt: number): number {
+  return retryBackoffDelayMs(attempt, {
+    baseDelayMs: CURSOR_RETRY_BASE_MS,
+    maxDelayMs: CURSOR_RETRY_MAX_MS,
+  });
+}
+
+/**
+ * A transport is safe to retry only if it explicitly reports the run request was never committed.
+ * A transport without `requestCommitted` is treated as committed (not retryable) — fail safe.
+ */
+function requestUncommitted(transport: CursorTransport): boolean {
+  return typeof transport.requestCommitted === "function" && transport.requestCommitted() === false;
+}
+
+/**
+ * Run a Cursor turn with bounded retry on pre-commit transient failures.
+ *
+ * `onEvent` receives every server message. Retry happens only when ALL hold:
+ *  - nothing has been emitted yet this turn,
+ *  - the failing transport reports the run request was not committed to the wire,
+ *  - the error is a transient pre-commit failure.
+ * Otherwise the error propagates (the adapter maps it to a user-facing message).
+ */
+export async function runCursorTurnWithRetry(
+  makeTransport: (input: CursorTransportFactoryInput) => CursorTransport,
+  input: CursorTransportFactoryInput,
+  request: CursorRunRequest,
+  signal: AbortSignal | undefined,
+  onEvent: (message: CursorServerMessage, transport: CursorTransport) => void,
+): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    if (signal?.aborted) throw abortError(signal);
+    const transport = makeTransport(input);
+    let emittedAny = false;
+    let closed = false;
+    // Best-effort close: a cleanup failure must never replace the run outcome (or kill
+    // a viable retry) — the caller needs the run error / success, not the close error.
+    const closeOnce = async (): Promise<void> => {
+      if (closed) return;
+      closed = true;
+      try {
+        await transport.close?.();
+      } catch (err) {
+        debugProviderDiagnostic("cursor", "close-error", {
+          attempt,
+          reason: safeCursorErrorMessage(err instanceof Error ? err.message : String(err)),
+        });
+      }
+    };
+    try {
+      for await (const message of transport.run(request, signal)) {
+        emittedAny = true;
+        onEvent(message, transport);
+      }
+      return;
+    } catch (err) {
+      const canRetry =
+        !emittedAny &&
+        attempt < CURSOR_RETRY_ATTEMPTS - 1 &&
+        !signal?.aborted &&
+        requestUncommitted(transport) &&
+        isRetryableCursorError(err);
+      if (!canRetry) {
+        debugProviderDiagnostic("cursor", "no-retry", {
+          attempt,
+          reason: safeCursorErrorMessage(err instanceof Error ? err.message : String(err)),
+          emittedAny,
+          committed: !requestUncommitted(transport),
+          aborted: !!signal?.aborted,
+        });
+        throw err;
+      }
+      const backoffMs = cursorRetryDelayMs(attempt);
+      debugProviderDiagnostic("cursor", "retry", {
+        attempt,
+        reason: safeCursorErrorMessage(err instanceof Error ? err.message : String(err)),
+        backoffMs,
+      });
+      // End the failed attempt BEFORE the backoff: holding the dead transport open
+      // through the sleep wastes its connection, and the next attempt must never
+      // start before this one's close settles.
+      await closeOnce();
+      await sleepWithAbort(backoffMs, signal);
+    } finally {
+      await closeOnce();
+    }
+  }
+}
+
+export type { CursorTransportFactory };

package/src/adapters/cursor/transport.ts

@@ -0,0 +1,79 @@
+import type { OcxProviderConfig } from "../../types";
+import type { CursorClientMessage, CursorRunRequest, CursorServerMessage } from "./types";
+import type { TranslatorBudget } from "../../lib/translator-budget";
+
+export interface CursorTransport {
+  run(request: CursorRunRequest, signal?: AbortSignal): AsyncIterable<CursorServerMessage>;
+  writeClient(message: CursorClientMessage): void | Promise<void>;
+  close?(): void | Promise<void>;
+  /**
+   * Whether the run request has been committed to the wire. The retry orchestrator only re-dials
+   * failures that happened BEFORE this becomes true, so a turn the Cursor server may already have
+   * 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.
+   */
+  clientToolFinalizeGraceMs?: number;
+  /**
+   * True when inbound request text carries the legacy Codex full-access sandbox marker.
+   * This is retained as diagnostic/context only; exec-policy.ts does not trust it as
+   * 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;
+
+export class CursorTransportDisabledError extends Error {
+  readonly code = "cursor_transport_disabled";
+
+  constructor(message = "live Cursor transport is disabled") {
+    super(message);
+    this.name = "CursorTransportDisabledError";
+  }
+}
+
+export function createDisabledCursorTransport(): CursorTransport {
+  return {
+    async *run() {
+      throw new CursorTransportDisabledError();
+    },
+    writeClient() {},
+    close() {},
+  };
+}

package/src/adapters/cursor/types.ts

@@ -0,0 +1,79 @@
+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?: 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;
+  /**
+   * 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
+   * historical previous_response_id replay remains idempotent.
+   */
+  contextUsageReset?: boolean;
+  /**
+   * Defaults to true. Set false for compaction summarizer turns: their checkpoints describe the
+   * 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 {
+  role: "user" | "assistant" | "developer" | "tool";
+  content: string;
+}
+
+export type CursorServerMessage =
+  | { type: "text"; text: string }
+  | { type: "thinking"; thinking: string }
+  | { type: "tool_call_start"; id: string; name: string }
+  | { type: "tool_call_delta"; arguments: string }
+  | { type: "tool_call_end"; id?: string }
+  | { type: "done"; usage?: OcxUsage }
+  | { type: "error"; message: string; usage?: OcxUsage }
+  | { type: "heartbeat" }
+  | { type: "kv_get"; key: string }
+  | { type: "kv_set"; key: string; value: Uint8Array }
+  | { type: "exec"; execCase: string; requestId: string }
+  /** A native exec/MCP action ran locally; retrying this turn could duplicate its side effects. */
+  | { type: "local_side_effect" };
+
+export type CursorClientMessage =
+  | { type: "kv_value"; key: string; value?: Uint8Array }
+  | { type: "kv_stored"; key: string }
+  | { type: "exec_result"; requestId: string; ok: boolean; message: string };