@iislee/opencodex 2.11.0 → 2.35.0

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

@@ -0,0 +1,308 @@
+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: {
+  conversationId: string;
+  prefixDigest: string;
+  systemDigest: string;
+  coveredMessageCount: number;
+  identityScope?: string;
+  modelId: string;
+}): CursorCheckpointSnapshot | undefined {
+  prune();
+  const refs = store.prefixIndex.get(input.prefixDigest);
+  if (!refs) return undefined;
+  const identityScope = input.identityScope?.trim() || "local";
+  let foundRef: string | undefined;
+  for (const ref of refs) {
+    const snapshot = store.snapshots.get(ref);
+    if (!snapshot) continue;
+    if (snapshot.conversationId !== input.conversationId) continue;
+    if (snapshot.systemDigest !== input.systemDigest) continue;
+    if (snapshot.coveredMessageCount !== input.coveredMessageCount) continue;
+    if (snapshot.identityScope !== identityScope) continue;
+    if (snapshot.modelId !== input.modelId) continue;
+    if (foundRef) return undefined;
+    foundRef = ref;
+  }
+  return getCursorCheckpoint(foundRef);
+}
+
+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

@@ -27,7 +27,56 @@ function errorCode(value: unknown): string {
  * 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;
@@ -36,6 +85,21 @@ export function isCursorBenignCancelError(value: unknown): boolean {
   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.
@@ -48,6 +112,58 @@ export function isCursorInvalidArgumentError(value: unknown): boolean {
 }
 
 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",
@@ -80,7 +196,7 @@ export function isCursorRequestTooLargeDetail(lowerMessage: string): boolean {
  * 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): string {
+export function classifyCursorError(message: string, sizeContext?: CursorSizeContext): string {
   const lower = message.toLowerCase();
 
   if (isCursorBenignCancelError(message)) return "Cursor stream suspended";
@@ -94,9 +210,16 @@ export function classifyCursorError(message: string): string {
     // 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).
-    return isCursorRequestTooLargeDetail(lower)
-      ? "Cursor resource limit exceeded"
-      : "Cursor rate limit exceeded";
+    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 (
@@ -118,6 +241,21 @@ export function classifyCursorError(message: string): string {
     lower.includes("access denied")
   ) return "Cursor authentication failed";
 
+  // gRPC FAILED_PRECONDITION is deterministic and non-retryable (unlike UNAVAILABLE):
+  // the backend rejected the call because the account/plan state does not allow it —
+  // seen live when a plan-gated model (e.g. claude-fable-5) runs on a plan without it.
+  // Leaving it as "Cursor upstream error" (502) made clients retry it as overload.
+  //
+  // This MUST precede the overload keywords. The explicit gRPC status code is a
+  // structured signal from the backend; the keywords are inference over free text. A
+  // plan-gated rejection routinely reads "failed_precondition: model unavailable for
+  // this plan", which matched "unavailable" first and came back as a retryable
+  // overload — the exact misclassification this branch was added to stop. Checking the
+  // code first lets the deterministic signal win over the words around it.
+  if (lower.includes("failed_precondition") || lower.includes("failed precondition")) {
+    return "Cursor invalid request";
+  }
+
   if (
     lower.includes("unavailable") ||
     lower.includes("overloaded") ||
@@ -156,8 +294,8 @@ export function classifyCursorError(message: string): string {
  * 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): string {
-  const prefix = classifyCursorError(rawMessage);
+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);