@yansigit/opencodex 2.31.0

package/src/adapters/cursor/arg-normalize.ts

@@ -0,0 +1,104 @@
+/**
+ * Schema-aware argument key normalization for Cursor tool calls.
+ *
+ * Cursor-trained models sometimes emit argument keys that differ from the tool's declared schema
+ * (e.g. `filepath` instead of `path`, `cmd` instead of `command`). This module maps common aliases
+ * to the canonical key name ONLY when the tool schema declares that canonical key. Keys already
+ * matching the schema are never touched.
+ *
+ * Derived from opencode-cursor reference (src/provider/tool-schema-compat.ts).
+ */
+
+const KEY_ALIASES = new Map<string, string>([
+  ["filepath", "path"],
+  ["filename", "path"],
+  ["file", "path"],
+  ["targetpath", "path"],
+  ["directorypath", "path"],
+  ["dir", "path"],
+  ["folder", "path"],
+  ["directory", "path"],
+  ["targetdirectory", "path"],
+  ["targetfile", "path"],
+  ["globpattern", "pattern"],
+  ["filepattern", "pattern"],
+  ["searchpattern", "pattern"],
+  ["includepattern", "include"],
+  ["workingdirectory", "cwd"],
+  ["workdir", "cwd"],
+  ["currentdirectory", "cwd"],
+  ["cmd", "command"],
+  ["script", "command"],
+  ["shellcommand", "command"],
+  ["terminalcommand", "command"],
+  ["contents", "content"],
+  ["text", "content"],
+  ["body", "content"],
+  ["data", "content"],
+  ["payload", "content"],
+  ["streamcontent", "content"],
+  ["oldstring", "old_string"],
+  ["newstring", "new_string"],
+  ["oldtext", "old_string"],
+  ["newtext", "new_string"],
+  ["oldcontent", "old_string"],
+  ["newcontent", "new_string"],
+  ["recursive", "force"],
+]);
+
+/**
+ * Extract the set of declared property names from a JSON Schema parameters object.
+ * Handles the common `{ type: "object", properties: { ... } }` shape.
+ */
+function schemaPropertyNames(schema: unknown): Set<string> | undefined {
+  if (!schema || typeof schema !== "object") return undefined;
+  const obj = schema as Record<string, unknown>;
+  const props = obj.properties;
+  if (!props || typeof props !== "object") return undefined;
+  return new Set(Object.keys(props as Record<string, unknown>));
+}
+
+/**
+ * Normalize argument keys against the tool's declared schema. Keys not in the schema that have a
+ * known alias pointing to a schema-declared key are renamed. Explicitly supplied canonical keys
+ * always win over aliases, regardless of object property insertion order — conflicting aliases
+ * are discarded rather than left beside the canonical key.
+ *
+ * Returns the original object reference if no changes were needed (cheap identity check for callers).
+ */
+export function normalizeArgKeys(args: Record<string, unknown>, toolSchema: unknown): Record<string, unknown> {
+  const declared = schemaPropertyNames(toolSchema);
+  if (!declared || declared.size === 0) return args;
+
+  const suppliedCanonical = new Set<string>();
+  for (const key of Object.keys(args)) {
+    if (declared.has(key)) suppliedCanonical.add(key);
+  }
+
+  let changed = false;
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (declared.has(key)) {
+      result[key] = value;
+      continue;
+    }
+    const canonical = KEY_ALIASES.get(key.toLowerCase());
+    if (canonical && declared.has(canonical)) {
+      // Canonical was explicitly supplied (any order) — drop the alias entirely.
+      if (suppliedCanonical.has(canonical)) {
+        changed = true;
+        continue;
+      }
+      // First alias fills the canonical slot; later aliases for the same key are discarded.
+      if (!(canonical in result)) {
+        result[canonical] = value;
+        changed = true;
+      } else {
+        changed = true;
+      }
+      continue;
+    }
+    result[key] = value;
+  }
+  return changed ? result : args;
+}

package/src/adapters/cursor/checkpoint-store.ts

@@ -0,0 +1,303 @@
+import { createHash } from "node:crypto";
+import { fromBinary } from "@bufbuild/protobuf";
+import { ConversationStateStructureSchema, type ConversationStateStructure } from "./gen/agent_pb";
+import {
+  createCursorBlobCheckpointLease,
+  pinCursorBlobIdsForCheckpoint,
+  releaseCursorBlobRequestScope,
+  type CursorBlobRequestScopeToken,
+} from "./native-exec";
+
+export const CURSOR_CHECKPOINT_TTL_MS = 15 * 60_000;
+export const CURSOR_CHECKPOINT_MAX_ENTRIES = 64;
+export const CURSOR_CHECKPOINT_MAX_TOTAL_BYTES = 16 * 1024 * 1024;
+
+export type CursorCheckpointInvalidationReason =
+  | "missing_ref"
+  | "expired"
+  | "decode_failed"
+  | "conversation_changed"
+  | "identity_changed"
+  | "model_changed"
+  | "compaction"
+  | "trailing_tool_result"
+  | "force_fresh"
+  | "upstream_invalid_argument"
+  | "lineage_mismatch";
+
+export interface CursorCheckpointSnapshot {
+  ref: string;
+  conversationId: string;
+  identityScope: string;
+  modelId: string;
+  checkpointBytes: Uint8Array;
+  createdAt: number;
+  lastAccessAt: number;
+  blobLease?: CursorBlobRequestScopeToken;
+  coveredMessageCount?: number;
+  prefixDigest?: string;
+  systemDigest?: string;
+}
+
+interface CursorCheckpointStore {
+  snapshots: Map<string, CursorCheckpointSnapshot>;
+  prefixIndex: Map<string, Set<string>>;
+  totalBytes: number;
+}
+
+const store: CursorCheckpointStore = {
+  snapshots: new Map(),
+  prefixIndex: new Map(),
+  totalBytes: 0,
+};
+
+let nowFn = (): number => Date.now();
+let scheduleFn = (fn: () => void, ms: number): ReturnType<typeof setTimeout> => {
+  const timer = setTimeout(fn, ms);
+  timer.unref?.();
+  return timer;
+};
+let clearScheduleFn = (timer: ReturnType<typeof setTimeout>): void => {
+  clearTimeout(timer);
+};
+let pruneTimer: ReturnType<typeof setTimeout> | undefined;
+
+function now(): number {
+  return nowFn();
+}
+
+export function installCursorCheckpointClockForTests(input: {
+  now?: () => number;
+  schedule?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+  clear?: (timer: ReturnType<typeof setTimeout>) => void;
+}): void {
+  if (input.now) nowFn = input.now;
+  if (input.schedule) scheduleFn = input.schedule;
+  if (input.clear) clearScheduleFn = input.clear;
+}
+
+export function resetCursorCheckpointClockForTests(): void {
+  nowFn = () => Date.now();
+  scheduleFn = (fn, ms) => {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return timer;
+  };
+  clearScheduleFn = timer => {
+    clearTimeout(timer);
+  };
+  stopPruneTimer();
+}
+
+function stopPruneTimer(): void {
+  if (pruneTimer !== undefined) clearScheduleFn(pruneTimer);
+  pruneTimer = undefined;
+}
+
+function schedulePrune(at = now()): void {
+  stopPruneTimer();
+  let nextExpiry = Number.POSITIVE_INFINITY;
+  for (const snapshot of store.snapshots.values()) {
+    nextExpiry = Math.min(nextExpiry, snapshot.lastAccessAt + CURSOR_CHECKPOINT_TTL_MS);
+  }
+  if (!Number.isFinite(nextExpiry)) return;
+  pruneTimer = scheduleFn(() => {
+    pruneTimer = undefined;
+    prune();
+    schedulePrune();
+  }, Math.max(0, nextExpiry - at));
+}
+
+function prune(at = now()): void {
+  for (const [ref, snapshot] of store.snapshots) {
+    if (at - snapshot.lastAccessAt > CURSOR_CHECKPOINT_TTL_MS) deleteSnapshot(ref);
+  }
+  while (store.snapshots.size > CURSOR_CHECKPOINT_MAX_ENTRIES || store.totalBytes > CURSOR_CHECKPOINT_MAX_TOTAL_BYTES) {
+    const oldest = store.snapshots.keys().next().value;
+    if (oldest === undefined) break;
+    deleteSnapshot(oldest);
+  }
+  schedulePrune(at);
+}
+
+function indexPrefix(digest: string | undefined, ref: string): void {
+  if (!digest) return;
+  const refs = store.prefixIndex.get(digest) ?? new Set<string>();
+  refs.add(ref);
+  store.prefixIndex.set(digest, refs);
+}
+
+function unindexPrefix(digest: string | undefined, ref: string): void {
+  if (!digest) return;
+  const refs = store.prefixIndex.get(digest);
+  if (!refs) return;
+  refs.delete(ref);
+  if (refs.size === 0) store.prefixIndex.delete(digest);
+}
+
+function deleteSnapshot(ref: string): void {
+  const existing = store.snapshots.get(ref);
+  if (!existing) return;
+  if (existing.blobLease) releaseCursorBlobRequestScope(existing.blobLease);
+  unindexPrefix(existing.prefixDigest, ref);
+  store.snapshots.delete(ref);
+  store.totalBytes = Math.max(0, store.totalBytes - existing.checkpointBytes.byteLength);
+}
+
+function collectStateBlobIds(state: ConversationStateStructure, ids: Uint8Array[]): void {
+  ids.push(
+    ...state.rootPromptMessagesJson,
+    ...state.turns,
+    ...state.turnsOld,
+    ...state.todos,
+    ...state.summaryArchives,
+  );
+  if (state.summary) ids.push(state.summary);
+  if (state.summaryArchive) ids.push(state.summaryArchive);
+  if (state.plan) ids.push(state.plan);
+  for (const value of Object.values(state.fileStates)) ids.push(value);
+  for (const value of Object.values(state.fileStatesV2)) {
+    if (value.content) ids.push(value.content);
+    if (value.initialContent) ids.push(value.initialContent);
+  }
+  for (const nested of Object.values(state.subagentStates)) {
+    if (nested.conversationState) collectStateBlobIds(nested.conversationState, ids);
+  }
+}
+
+function collectCheckpointBlobIds(checkpointBytes: Uint8Array): Uint8Array[] | undefined {
+  try {
+    const ids: Uint8Array[] = [];
+    collectStateBlobIds(fromBinary(ConversationStateStructureSchema, checkpointBytes), ids);
+    return ids.filter(id => id.byteLength > 0);
+  } catch {
+    return undefined;
+  }
+}
+
+export function cursorCheckpointRefHash(ref: string): string {
+  return createHash("sha256").update("ocx:cursor:ckpt-ref:").update(ref).digest("hex").slice(0, 16);
+}
+
+export function commitCursorCheckpoint(input: {
+  conversationId: string;
+  identityScope?: string;
+  modelId: string;
+  checkpointBytes: Uint8Array;
+  coveredMessageCount?: number;
+  prefixDigest?: string;
+  systemDigest?: string;
+}): string | undefined {
+  if (!input.conversationId || !input.modelId || input.checkpointBytes.byteLength === 0) return undefined;
+  if (input.checkpointBytes.byteLength > CURSOR_CHECKPOINT_MAX_TOTAL_BYTES) return undefined;
+  prune();
+  const createdAt = now();
+  const ref = createHash("sha256")
+    .update("ocx:cursor:ckpt:")
+    .update(input.conversationId)
+    .update("|")
+    .update(input.identityScope?.trim() || "local")
+    .update("|")
+    .update(input.modelId)
+    .update("|")
+    .update(String(createdAt))
+    .update("|")
+    .update(input.checkpointBytes)
+    .digest("hex")
+    .slice(0, 32);
+  const snapshot: CursorCheckpointSnapshot = {
+    ref,
+    conversationId: input.conversationId,
+    identityScope: input.identityScope?.trim() || "local",
+    modelId: input.modelId,
+    checkpointBytes: input.checkpointBytes.slice(),
+    createdAt,
+    lastAccessAt: createdAt,
+    ...(input.coveredMessageCount !== undefined ? { coveredMessageCount: input.coveredMessageCount } : {}),
+    ...(input.prefixDigest ? { prefixDigest: input.prefixDigest } : {}),
+    ...(input.systemDigest ? { systemDigest: input.systemDigest } : {}),
+  };
+  const blobIds = collectCheckpointBlobIds(input.checkpointBytes);
+  if (blobIds === undefined) return undefined;
+  if (blobIds.length > 0) {
+    const lease = createCursorBlobCheckpointLease(ref);
+    if (!pinCursorBlobIdsForCheckpoint(blobIds, lease)) {
+      releaseCursorBlobRequestScope(lease);
+      return undefined;
+    }
+    snapshot.blobLease = lease;
+  }
+  deleteSnapshot(ref);
+  store.snapshots.set(ref, snapshot);
+  store.totalBytes += snapshot.checkpointBytes.byteLength;
+  indexPrefix(snapshot.prefixDigest, ref);
+  prune(createdAt);
+  return store.snapshots.has(ref) ? ref : undefined;
+}
+
+export function getCursorCheckpointForPrefix(input: {
+  prefixDigest: string;
+  systemDigest: string;
+  coveredMessageCount: number;
+  identityScope?: string;
+  modelId: string;
+}): CursorCheckpointSnapshot | undefined {
+  prune();
+  const refs = store.prefixIndex.get(input.prefixDigest);
+  if (!refs || refs.size !== 1) return undefined;
+  const [ref] = refs;
+  if (!ref) return undefined;
+  const snapshot = getCursorCheckpoint(ref);
+  if (!snapshot) return undefined;
+  const identityScope = input.identityScope?.trim() || "local";
+  if (snapshot.systemDigest !== input.systemDigest) return undefined;
+  if (snapshot.coveredMessageCount !== input.coveredMessageCount) return undefined;
+  if (snapshot.identityScope !== identityScope) return undefined;
+  if (snapshot.modelId !== input.modelId) return undefined;
+  return snapshot;
+}
+
+export function getLatestCursorCheckpoint(
+  match: (snapshot: CursorCheckpointSnapshot) => boolean,
+): CursorCheckpointSnapshot | undefined {
+  prune();
+  let found: CursorCheckpointSnapshot | undefined;
+  for (const snapshot of store.snapshots.values()) {
+    if (match(snapshot)) found = snapshot;
+  }
+  return found ? getCursorCheckpoint(found.ref) : undefined;
+}
+
+export function getCursorCheckpoint(ref: string | undefined): CursorCheckpointSnapshot | undefined {
+  if (!ref) return undefined;
+  prune();
+  const snapshot = store.snapshots.get(ref);
+  if (!snapshot) return undefined;
+  const at = now();
+  if (at - snapshot.lastAccessAt > CURSOR_CHECKPOINT_TTL_MS) {
+    deleteSnapshot(ref);
+    return undefined;
+  }
+  snapshot.lastAccessAt = at;
+  store.snapshots.delete(ref);
+  store.snapshots.set(ref, snapshot);
+  return snapshot;
+}
+
+export function invalidateCursorCheckpoint(ref: string | undefined): void {
+  if (!ref) return;
+  deleteSnapshot(ref);
+}
+
+export function clearCursorCheckpointsForTests(): void {
+  stopPruneTimer();
+  for (const ref of [...store.snapshots.keys()]) deleteSnapshot(ref);
+  store.snapshots.clear();
+  store.prefixIndex.clear();
+  store.totalBytes = 0;
+  resetCursorCheckpointClockForTests();
+}
+
+export function cursorCheckpointStoreMetricsForTests(): { count: number; totalBytes: number } {
+  return { count: store.snapshots.size, totalBytes: store.totalBytes };
+}

package/src/adapters/cursor/cursor-errors.ts

@@ -0,0 +1,288 @@
+import { redactSecretString } from "../../lib/redact";
+
+const ABSOLUTE_PATH_PATTERN = /(?:\/Users\/[^ "';,]+|\/home\/[^ "';,]+|[A-Za-z]:\\Users\\[^ "';,]+)/g;
+// Cursor error messages can contain raw credential key=value pairs beyond what the shared
+// redactSecretString covers. We handle the additional transport-specific patterns locally.
+const CURSOR_CREDENTIAL_PATTERN = /\b(authorization|auth[_-]?token|cursor[_-]?token)=([^&\s"',;]+)/gi;
+
+function sanitize(value: string): string {
+  return redactSecretString(value)
+    .replace(CURSOR_CREDENTIAL_PATTERN, "$1=[REDACTED]")
+    .replace(ABSOLUTE_PATH_PATTERN, "[REDACTED_PATH]");
+}
+
+function errorMessage(value: unknown): string {
+  if (value instanceof Error) return value.message;
+  if (typeof value === "string") return value;
+  return String(value ?? "");
+}
+
+function errorCode(value: unknown): string {
+  if (typeof value !== "object" || !value || !("code" in value)) return "";
+  const code = (value as { code?: unknown }).code;
+  return code === undefined || code === null ? "" : String(code);
+}
+
+/**
+ * True when Cursor intentionally cancelled the HTTP/2 stream after a client-tool suspend.
+ * These are expected between multi-turn Responses bridge cycles, not upstream failures.
+ */
+/**
+ * A Cursor stream that ended cleanly at the HTTP/2 layer while a client tool call was still
+ * open — no `turnEnded`, no error trailer, just EOF. The call's buffered arguments are lost,
+ * so the turn is truncated: reporting it as success would hand Codex a turn whose tool call
+ * silently never happened. Not retryable — the request is committed once the session connects.
+ */
+export class CursorStreamTruncatedError extends Error {
+  constructor(
+    public readonly openCallIds: readonly string[],
+    public readonly framesReceived: number,
+  ) {
+    super(
+      `Cursor stream ended without terminating the turn; ${openCallIds.length} tool call(s) left incomplete `
+      + `(${openCallIds.join(", ")}) after ${framesReceived} frame(s). Arguments may be truncated; the call was not committed.`,
+    );
+    this.name = "CursorStreamTruncatedError";
+  }
+}
+
+/**
+ * A cancel-shaped stream failure that WE did not request. `cancelCursorRun` is the only place
+ * that cancels our own stream, and it sets `expectedClose` first, so a cancel arriving without it
+ * came from Cursor or the network and is a real transport failure.
+ *
+ * It carries its own message on purpose. Left as a raw `NGHTTP2_CANCEL` error, the text is
+ * re-matched downstream (`classifyCursorError`) and labelled "Cursor stream suspended" — a turn
+ * that failed unexpectedly would report an intentional suspension and misdirect diagnosis.
+ */
+export class CursorUnexpectedCancelError extends Error {
+  /**
+   * The originating error's transport code (typically `NGHTTP2_CANCEL`), re-exposed so the
+   * per-turn `turn-failed` diagnostic still records how the stream actually died. Wrapping
+   * without this made the summary for exactly this failure the one with no code.
+   */
+  public readonly code?: string;
+
+  constructor(public readonly cause?: unknown) {
+    super("Cursor connection was cancelled by the server before the turn completed");
+    this.name = "CursorUnexpectedCancelError";
+    const causeCode = errorCode(cause);
+    if (causeCode) this.code = causeCode;
+  }
+}
+
+export function isCursorBenignCancelError(value: unknown): boolean {
+  // An unexpected cancel is never benign, however it is spelled. This class is raised only when
+  // the transport knows WE did not request the cancel, so its provenance outranks the code match
+  // below — otherwise the adapter would re-decide the same question from the error code alone
+  // and swallow a real transport failure (cursor.ts:181).
+  if (value instanceof CursorUnexpectedCancelError) return false;
+  const message = errorMessage(value).toLowerCase();
+  const code = errorCode(value).toUpperCase();
+  if (code === "NGHTTP2_CANCEL") return true;
+  if (message.includes("nghttp2_cancel")) return true;
+  if (message.includes("cursor stream suspended")) return true;
+  return false;
+}
+
+/**
+ * True when the turn was torn down by an `AbortSignal` rather than by a transport fault.
+ *
+ * This is deliberately NOT part of `isCursorBenignCancelError`: an abort mid-turn is a real
+ * failure and must still surface. It is only meaningful in combination with a terminal frame
+ * having already been emitted, where it means "the answer landed and then the connection went
+ * away" (#1527).
+ */
+export function isCursorAbortError(value: unknown): boolean {
+  const message = errorMessage(value).toLowerCase();
+  if (message.includes("cursor request was aborted")) return true;
+  const name = (value as { name?: unknown })?.name;
+  return typeof name === "string" && name === "AbortError";
+}
+
+/**
+ * True when Cursor Connect rejected the turn with invalid_argument.
+ * Seen after stepCompleted on brittle external-model continuations.
+ */
+export function isCursorInvalidArgumentError(value: unknown): boolean {
+  const code = errorCode(value).toLowerCase();
+  if (code === "invalid_argument") return true;
+  const message = errorMessage(value).toLowerCase();
+  return message.includes("invalid_argument");
+}
+
+const QUOTA_RATE_CUES = ["too many requests", "quota", "rate limit", "rate-limit", "throttl"];
+/**
+ * A bare `resource_exhausted` end-stream with no detail beyond a generic error wrapper
+ * ("Error" or empty tail) and zero tokens billed is the shape Cursor's backend emits when
+ * the request payload exceeded its context window — not when quota ran out (senpi #1009,
+ * #1036: same wording, two causes). Quota rejections always carry an explicit rate cue
+ * ("too many requests", "quota exhausted"), so the ABSENCE of those cues plus the
+ * absence of a size phrase means payload overflow. Classifying it as 429 makes Codex
+ * back off instead of compacting, which burns retries on an unfixable-by-retry failure.
+ */
+const BARE_RE_TAILS = new Set(["error", "", "resource_exhausted", "resource exhausted"]);
+
+/**
+ * Size prior for bare resource_exhausted classification (devlog 260, live probe 210):
+ * a plan-gated model returns the SAME bare RE shape on a ~20-token prompt that a real
+ * payload overflow produces, so the message alone cannot separate "compact and retry"
+ * from "this account cannot use this model". When the caller can supply how large the
+ * request actually was relative to the model's window, a small request keeps the
+ * 429-class mapping; only a plausibly-large one classifies as overflow. Unknown
+ * sizes keep today's overflow mapping so the prior only ever REMOVES false overflows
+ * it can prove.
+ */
+export interface CursorSizeContext {
+  estimatedInputTokens?: number;
+  contextWindow?: number;
+}
+
+const OVERFLOW_MIN_FRACTION = 0.5;
+
+function bareReLooksLikeOverflow(context?: CursorSizeContext): boolean {
+  if (!context) return true;
+  const { estimatedInputTokens, contextWindow } = context;
+  if (estimatedInputTokens === undefined || contextWindow === undefined || contextWindow <= 0) return true;
+  return estimatedInputTokens >= OVERFLOW_MIN_FRACTION * contextWindow;
+}
+
+export function isCursorZeroTokenResourceExhausted(lowerMessage: string): boolean {
+  if (!lowerMessage.includes("resource_exhausted") && !lowerMessage.includes("resource exhausted")) return false;
+  // Any explicit quota/rate cue wins: this is a real 429.
+  if (QUOTA_RATE_CUES.some(cue => lowerMessage.includes(cue))) return false;
+  // An explicit size phrase also wins (already handled by the existing classifier).
+  if (isCursorRequestTooLargeDetail(lowerMessage)) return false;
+  // Extract the tail after the resource_exhausted marker. If it names a specific
+  // non-quota, non-size cause, this is NOT bare overflow.
+  const idx = Math.max(
+    lowerMessage.indexOf("resource_exhausted"),
+    lowerMessage.indexOf("resource exhausted"),
+  );
+  const tail = lowerMessage.slice(idx + "resource_exhausted".length).trim().replace(/^[:\s]+/, "").trim();
+  if (!BARE_RE_TAILS.has(tail)) return false;
+  return true;
+}
+
+const REQUEST_TOO_LARGE_PATTERNS: (string | RegExp)[] = [
+  "tool catalog too large",
+  "tool registration too large",
+  "too many tools",
+  "message too large",
+  "payload too large",
+  "request too large",
+  // Size cue required somewhere: a bare "request exceeds ... limit" (concurrency/quota
+  // shape) must NOT match, but "request body/size exceeds ... limit" and
+  // "request exceeds maximum allowed size" are deterministic overflow (WP3 r1/r2).
+  /request exceeds .*size/,
+  /request (?:body|size) exceeds .*(?:size|limit)/,
+  "maximum allowed size",
+];
+
+/**
+ * True when a resource_exhausted detail names a request-size overflow rather than quota.
+ * Quota/rate cues are rejected FIRST: "resource_exhausted while loading tool catalog: quota
+ * exhausted" is rate limiting, not a too-large request, even though it mentions the catalog.
+ */
+export function isCursorRequestTooLargeDetail(lowerMessage: string): boolean {
+  if (QUOTA_RATE_CUES.some(cue => lowerMessage.includes(cue))) return false;
+  return REQUEST_TOO_LARGE_PATTERNS.some(pattern =>
+    typeof pattern === "string" ? lowerMessage.includes(pattern) : pattern.test(lowerMessage),
+  );
+}
+
+/**
+ * Classify a Cursor transport/Connect/gRPC error message into an actionable category.
+ * The returned prefix string is recognized by `src/lib/errors.ts` `classifyError` keywords,
+ * so bridge-level error mapping produces the right Codex error type (rate_limit, auth, etc.).
+ */
+export function classifyCursorError(message: string, sizeContext?: CursorSizeContext): string {
+  const lower = message.toLowerCase();
+
+  if (isCursorBenignCancelError(message)) return "Cursor stream suspended";
+
+  if (
+    lower.includes("resource_exhausted") ||
+    lower.includes("resource exhausted")
+  ) {
+    // gRPC RESOURCE_EXHAUSTED is quota/rate exhaustion unless the detail names a
+    // request-size overflow (tool catalog/registration). Only the latter is a
+    // client-fixable 400; everything else surfaces as a 429 so Codex backs off
+    // instead of hammering retries (live evidence: 6x 400 retry storm, devlog
+    // 260723_cursor_context_continuity/000_plan.md).
+    if (isCursorRequestTooLargeDetail(lower)) return "Cursor resource limit exceeded";
+    // A bare resource_exhausted with no quota cue and no size phrase is payload
+    // overflow, not rate limiting. Classifying it as 429 makes Codex back off on a
+    // failure that only compaction can fix (senpi #1009 / #1036; research unit T01).
+    // Refinement (devlog 260): plan-gated models emit the same bare shape on tiny
+    // requests — when the caller proves the request was small, keep the 429 class.
+    if (isCursorZeroTokenResourceExhausted(lower)) {
+      return bareReLooksLikeOverflow(sizeContext) ? "Cursor context limit exceeded" : "Cursor rate limit exceeded";
+    }
+    return "Cursor rate limit exceeded";
+  }
+
+  if (
+    lower.includes("rate limit") ||
+    lower.includes("rate-limit") ||
+    lower.includes("too many requests") ||
+    lower.includes("throttling")
+  ) return "Cursor rate limit exceeded";
+
+  if (
+    lower.includes("unauthenticated") ||
+    lower.includes("unauthorized") ||
+    lower.includes("permission_denied") ||
+    lower.includes("permission denied") ||
+    lower.includes("forbidden") ||
+    lower.includes("invalid token") ||
+    lower.includes("expired token") ||
+    lower.includes("authentication") ||
+    lower.includes("access denied")
+  ) return "Cursor authentication failed";
+
+  if (
+    lower.includes("unavailable") ||
+    lower.includes("overloaded") ||
+    lower.includes("temporarily") ||
+    lower.includes("server is busy")
+  ) return "Cursor server overloaded";
+
+  if (
+    lower.includes("invalid") ||
+    lower.includes("not found") ||
+    lower.includes("unsupported") ||
+    lower.includes("malformed") ||
+    lower.includes("unimplemented")
+  ) return "Cursor invalid request";
+
+  if (
+    lower.includes("timed out") ||
+    lower.includes("timeout") ||
+    lower.includes("etimedout") ||
+    lower.includes("deadline")
+  ) return "Cursor request timed out";
+
+  if (
+    lower.includes("econnreset") ||
+    lower.includes("econnrefused") ||
+    lower.includes("goaway") ||
+    lower.includes("nghttp2") ||
+    lower.includes("socket hang up") ||
+    lower.includes("connection reset")
+  ) return "Cursor connection failed";
+
+  return "Cursor upstream error";
+}
+
+/**
+ * Produce a user-facing, secret-safe Cursor error message with an actionable category prefix.
+ * Mirrors `safeKiroErrorMessage` / `safeKiroHttpErrorMessage` in kiro-errors.ts.
+ */
+export function safeCursorErrorMessage(rawMessage: string, sizeContext?: CursorSizeContext): string {
+  const prefix = classifyCursorError(rawMessage, sizeContext);
+  const detail = sanitize(rawMessage)
+    .replace(/resource[_ ]exhausted/gi, "resource limit exceeded")
+    .slice(0, 500);
+  return detail ? `${prefix}: ${detail}` : prefix;
+}