@remodex/rmx 1.0.2

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,57 @@
+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;
+}
+
+export interface CursorTransportFactoryInput {
+  provider: OcxProviderConfig;
+  translatorBudget: TranslatorBudget;
+  headers?: Headers;
+  /** 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;
+  /**
+   * 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;
+}
+
+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,59 @@
+import type { OcxUsage } from "../../types";
+import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
+import type { CursorRoutingLevel } from "./discovery";
+
+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[];
+  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;
+}
+
+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 };

package/src/adapters/cursor.ts

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import type { AdapterEvent, OcxProviderConfig } from "../types";
+import type { ProviderAdapter } from "./base";
+import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
+import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
+import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErrorMessage } from "./cursor/cursor-errors";
+import { isCursorExternalWireModel } from "./cursor/discovery";
+import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
+import { mapCursorServerMessage } from "./cursor/message-mapper";
+import { createCursorRequest } from "./cursor/request-builder";
+import {
+  createLiveCursorTransport,
+  CursorMissingCredentialError,
+  rekeyCursorContextUsage,
+  resolveCursorToken,
+} from "./cursor/live-transport";
+import { rememberCursorThreadConversation } from "./cursor/thread-continuity";
+import { runCursorTurnWithRetry } from "./cursor/transport-retry";
+import {
+  createDisabledCursorTransport,
+  CursorTransportDisabledError,
+  type CursorTransportFactory,
+} from "./cursor/transport";
+
+export const CURSOR_API_URL = "https://api2.cursor.sh";
+
+export {
+  CURSOR_EXEC_CASES_DENIED,
+  cursorExecDeniedMessage,
+  type CursorDeniedExecCase,
+} from "./cursor/exec-policy";
+
+const CURSOR_TRANSPORT_DISABLED_MESSAGE = [
+  "An explicit disabled Cursor transport was injected.",
+  "Production Cursor requests use live transport when a Cursor access token is configured.",
+].join(" ");
+
+export interface CursorAdapterDeps {
+  createTransport?: CursorTransportFactory;
+  kv?: CursorKvStore;
+  /** Test seam: observe/replace context-usage rekeying on conversation-id rotation. */
+  rekeyContextUsage?: (fromConversationId: string, toConversationId: string) => void;
+}
+
+function safeCursorTransportError(err: unknown): string {
+  if (err instanceof CursorTransportDisabledError) return CURSOR_TRANSPORT_DISABLED_MESSAGE;
+  if (err instanceof CursorMissingCredentialError) {
+    return "Cursor live transport is enabled, but no Cursor access token is configured. Set provider.apiKey or OPENCODEX_CURSOR_TEST_TOKEN.";
+  }
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : undefined;
+  if (message) return safeCursorErrorMessage(message);
+  return "Cursor upstream error: transport failed before completion.";
+}
+
+export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAdapterDeps = {}): ProviderAdapter {
+  return {
+    name: "cursor",
+
+    buildRequest() {
+      return {
+        url: provider.baseUrl || CURSOR_API_URL,
+        method: "POST",
+        headers: {},
+        body: "",
+      };
+    },
+
+    async *parseStream(): AsyncGenerator<AdapterEvent> {
+      yield {
+        type: "error",
+        message: "Cursor adapter uses runTurn; the fetch/parseStream path is disabled.",
+      };
+    },
+
+    async runTurn(_parsed, incoming, emit) {
+      if (incoming.abortSignal?.aborted) {
+        emit({ type: "error", message: "Cursor turn was aborted before start." });
+        return;
+      }
+      try {
+        const makeTransport = deps.createTransport ?? createLiveCursorTransport;
+        const kv = deps.kv ?? createCursorKvStore({}, incoming.translatorBudget);
+        const rekeyContextUsage = deps.rekeyContextUsage ?? rekeyCursorContextUsage;
+        // Namespace thread→conversation derivation by the authenticated Cursor credential so
+        // shared-proxy tenants with different Cursor accounts cannot collide on a parent thread id.
+        // Prefer an already-set auth scope (e.g. Codex pool account) when present.
+        if (!_parsed._cursorIdentityScope) {
+          try {
+            const token = resolveCursorToken(provider, incoming.headers);
+            _parsed._cursorIdentityScope = createHash("sha256")
+              .update("ocx:cursor:acct:")
+              .update(token)
+              .digest("hex")
+              .slice(0, 16);
+          } catch {
+            /* Missing credential is handled by the live transport path below. */
+          }
+        }
+        const previousConversationId = _parsed._cursorConversationId;
+        let request = createCursorRequest(_parsed);
+        // The builder may derive a stable provider id from the client thread when Responses state
+        // is unavailable. Rekey only existing state; there is nothing to migrate on a fresh turn,
+        // and isolated helper/compaction turns must never inherit or donate the parent's usage state.
+        if (
+          previousConversationId
+          && request.conversationId !== previousConversationId
+          && _parsed._cursorIsolateConversation !== true
+        ) {
+          rekeyContextUsage(previousConversationId, request.conversationId);
+        }
+        _parsed._cursorConversationId = request.conversationId;
+        let emittedOutput = false;
+        let replayUnsafe = false;
+        const lastRawIsToolResult = _parsed.context.messages.at(-1)?.role === "toolResult";
+
+        const runOnce = async (activeRequest: ReturnType<typeof createCursorRequest>) => {
+          await runCursorTurnWithRetry(
+            makeTransport,
+            {
+              provider,
+              headers: incoming.headers,
+              translatorBudget: incoming.translatorBudget,
+              requestDeclaresFullAccess: cursorRequestDeclaresFullAccess(activeRequest),
+            },
+            activeRequest,
+            incoming.abortSignal,
+            (message, activeTransport) => {
+              if (incoming.abortSignal?.aborted) {
+                emit({ type: "error", message: "Cursor turn was aborted." });
+                return;
+              }
+              if (message.type === "local_side_effect") replayUnsafe = true;
+              const events = mapCursorServerMessage(message, {
+                kv,
+                writeClient: clientMessage => {
+                  void activeTransport.writeClient(clientMessage);
+                },
+              });
+              for (const event of events) {
+                if (event.type !== "heartbeat") emittedOutput = true;
+                emit(event);
+              }
+            },
+          );
+        };
+
+        try {
+          await runOnce(request);
+        } catch (err) {
+          // One-shot fallback for external-model Connect invalid_argument before any
+          // non-heartbeat output. Retries apply only to safe plain-user turns; tool-result
+          // resumes, local exec/MCP side effects, and already-emitted output fail closed.
+          if (
+            !isCursorInvalidArgumentError(err)
+            || !isCursorExternalWireModel(request.modelId)
+            || lastRawIsToolResult
+            || emittedOutput
+            || replayUnsafe
+            || incoming.abortSignal?.aborted
+          ) {
+            throw err;
+          }
+          const failedConversationId = request.conversationId;
+          _parsed._cursorConversationId = undefined;
+          request = createCursorRequest(_parsed, { forceFreshConversation: true });
+          rekeyContextUsage(failedConversationId, request.conversationId);
+          _parsed._cursorConversationId = request.conversationId;
+          // Persist recovery for store:false clients that only send a parent thread id, so the
+          // next turn does not recompute the stale deterministic thread hash. Isolated helper /
+          // compaction turns must not park their throwaway id under the parent thread key.
+          if (_parsed._clientThreadId && _parsed._cursorIsolateConversation !== true) {
+            rememberCursorThreadConversation(
+              _parsed._clientThreadId,
+              request.conversationId,
+              _parsed._cursorIdentityScope,
+            );
+          }
+          await runOnce(request);
+        }
+      } catch (err) {
+        if (isCursorBenignCancelError(err)) return;
+        const partialUsage = (err as { partialUsage?: import("../types").OcxUsage }).partialUsage;
+        emit({
+          type: "error",
+          message: isTranslatorBudgetExceededError(err)
+            ? "upstream translation buffer exceeded the safe limit"
+            : safeCursorTransportError(err),
+          ...(isTranslatorBudgetExceededError(err)
+            ? { status: 502, errorType: "upstream_error", code: "translation_buffer_limit" }
+            : {}),
+          ...(partialUsage ? { usage: partialUsage } : {}),
+        });
+      }
+    },
+  };
+}