@iislee/opencodex 2.11.0

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,52 @@
+import type { OcxUsage } from "../../types";
+import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
+import type { CursorRoutingLevel } from "./discovery";
+
+export interface CursorRunRequest {
+  modelId: string;
+  /** 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 } : {}),
+        });
+      }
+    },
+  };
+}

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

@@ -0,0 +1,303 @@
+import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
+
+/**
+ * Antigravity (Cloud Code Assist) thoughtSignature reasoning-replay cache.
+ *
+ * Gemini-3 interleaved thinking is stateless upstream: each model content part carries a
+ * `thoughtSignature` that MUST be echoed back on the matching part in the next request, or the
+ * upstream rejects the turn (HTTP 400). We observe signatures on the response stream, cache them
+ * per `model + session`, and re-inject them into the outgoing `request.contents` on the next turn.
+ *
+ * Mirrors CLIProxyAPI `internal/runtime/executor/antigravity_reasoning_replay.go`. Gemini-only;
+ * Claude-on-Antigravity uses inline signature sanitization instead (see google-antigravity-wire).
+ */
+
+interface ReplayCall {
+  signature: string;
+  sizeBytes: number;
+  touchedAtMs: number;
+}
+
+interface ReplayEntry {
+  /** thoughtSignature keyed by functionCall identity (name + canonical args). */
+  byCall: Map<string, ReplayCall>;
+  bytes: number;
+  expiresAtMs: number;
+  oldestAtMs: number | null;
+}
+
+const MIN_SIGNATURE_LEN = 16;
+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_TOTAL_BYTES = 64 * 1024 * 1024;
+const REPLAY_MAX_SIGNATURE_BYTES = 64 * 1024;
+
+interface ReplayLimits {
+  maxCallsPerSession: number;
+  maxBytesPerSession: number;
+  maxSignatureBytes: number;
+}
+
+const DEFAULT_REPLAY_LIMITS: ReplayLimits = {
+  maxCallsPerSession: REPLAY_MAX_CALLS_PER_SESSION,
+  maxBytesPerSession: ANTIGRAVITY_REPLAY_MAX_BYTES_PER_SESSION,
+  maxSignatureBytes: REPLAY_MAX_SIGNATURE_BYTES,
+};
+
+const replayCache = new Map<string, ReplayEntry>();
+const utf8 = new TextEncoder();
+let replayLimits = { ...DEFAULT_REPLAY_LIMITS };
+let replayBytes = 0;
+let replayOldestSessionKey: string | undefined;
+let replayOldestAt: number | null = null;
+
+function replayKey(model: string, sessionId: string): string {
+  return `${model}::session:${sessionId}`;
+}
+
+/** Recursively canonicalize a JSON value: object keys sorted, arrays preserved. */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.keys(value as Record<string, unknown>).sort()
+    .map(k => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`);
+  return `{${entries.join(",")}}`;
+}
+
+/** Stable identity for a functionCall part: name + recursively canonicalized args. */
+function functionCallKey(name: unknown, args: unknown): string | undefined {
+  if (typeof name !== "string" || name.length === 0) return undefined;
+  let argsKey = "";
+  try {
+    argsKey = canonicalJson(args ?? {});
+  } catch {
+    argsKey = "";
+  }
+  return `${name}::${argsKey}`;
+}
+
+function extractSignature(part: Record<string, unknown>): string | undefined {
+  const direct = part.thoughtSignature ?? part.thought_signature;
+  if (typeof direct === "string" && direct.length >= MIN_SIGNATURE_LEN) return direct;
+  const extra = part.extra_content as { google?: { thought_signature?: unknown } } | undefined;
+  const nested = extra?.google?.thought_signature;
+  if (typeof nested === "string" && nested.length >= MIN_SIGNATURE_LEN) return nested;
+  return undefined;
+}
+
+function deleteReplaySession(key: string): number {
+  const entry = replayCache.get(key);
+  if (!entry) return 0;
+  replayCache.delete(key);
+  replayBytes -= entry.bytes;
+  if (replayOldestSessionKey === key) recomputeReplayOldestCandidate();
+  return entry.bytes;
+}
+
+function recomputeReplayOldestCandidate(): void {
+  replayOldestSessionKey = undefined;
+  replayOldestAt = null;
+  for (const [key, entry] of replayCache) {
+    if (entry.oldestAtMs === null || (replayOldestAt !== null && entry.oldestAtMs >= replayOldestAt)) continue;
+    replayOldestSessionKey = key;
+    replayOldestAt = entry.oldestAtMs;
+  }
+}
+
+function refreshReplaySessionCandidate(key: string, entry: ReplayEntry): void {
+  entry.oldestAtMs = entry.byCall.values().next().value?.touchedAtMs ?? null;
+  if (replayOldestSessionKey === key) {
+    recomputeReplayOldestCandidate();
+    return;
+  }
+  if (entry.oldestAtMs !== null && (replayOldestAt === null || entry.oldestAtMs < replayOldestAt)) {
+    replayOldestSessionKey = key;
+    replayOldestAt = entry.oldestAtMs;
+  }
+}
+
+function deleteExpiredReplaySessions(now: number): void {
+  for (const [key, entry] of replayCache) if (entry.expiresAtMs <= now) deleteReplaySession(key);
+}
+
+export function sweepExpiredAntigravityReplay(now = Date.now()): number {
+  const before = replayCache.size;
+  deleteExpiredReplaySessions(now);
+  return before - replayCache.size;
+}
+
+function deleteReplayCall(entry: ReplayEntry, callKey: string): number {
+  const call = entry.byCall.get(callKey);
+  if (!call) return 0;
+  entry.byCall.delete(callKey);
+  entry.bytes -= call.sizeBytes;
+  replayBytes -= call.sizeBytes;
+  return call.sizeBytes;
+}
+
+function evictInnerCalls(entry: ReplayEntry): void {
+  while (
+    entry.byCall.size > replayLimits.maxCallsPerSession
+    || entry.bytes > replayLimits.maxBytesPerSession
+  ) {
+    const oldest = entry.byCall.keys().next().value;
+    if (oldest === undefined) break;
+    deleteReplayCall(entry, oldest);
+  }
+}
+
+function evictIfNeeded(): void {
+  if (replayCache.size > ANTIGRAVITY_REPLAY_MAX_ENTRIES) {
+    const oldest = [...replayCache.entries()]
+      .sort((a, b) => a[1].expiresAtMs - b[1].expiresAtMs)
+      .slice(0, REPLAY_EVICT_BATCH);
+    for (const [key] of oldest) deleteReplaySession(key);
+  }
+  while (replayBytes > ANTIGRAVITY_REPLAY_MAX_TOTAL_BYTES) {
+    const oldestKey = [...replayCache.entries()]
+      .sort((a, b) => a[1].expiresAtMs - b[1].expiresAtMs)[0]?.[0];
+    if (oldestKey === undefined) return;
+    deleteReplaySession(oldestKey);
+  }
+}
+
+/** Gemini/Flash/Agent use the replay cache; Claude does not (inline sanitization instead). */
+export function antigravityUsesReplayCache(model: string): boolean {
+  return !/claude/i.test(model);
+}
+
+/**
+ * Observe a parsed CCA chunk's `candidates[0].content.parts` and record thought signatures keyed by
+ * the functionCall identity (name + args). Accumulates across the whole session so a sequential
+ * multi-step tool loop keeps EVERY prior call's signature, not just the latest part-index slot.
+ * `parts` is the already-unwrapped `response.candidates[0].content.parts`.
+ */
+export function observeAntigravityReplay(model: string, sessionId: string, parts: unknown[]): void {
+  if (!antigravityUsesReplayCache(model) || !Array.isArray(parts) || parts.length === 0) return;
+  const now = Date.now();
+  deleteExpiredReplaySessions(now);
+  const key = replayKey(model, sessionId);
+  const entry = replayCache.get(key) ?? {
+    byCall: new Map<string, ReplayCall>(),
+    bytes: 0,
+    expiresAtMs: 0,
+    oldestAtMs: null,
+  };
+  let inserted = false;
+  for (const raw of parts) {
+    if (!raw || typeof raw !== "object") continue;
+    const part = raw as Record<string, unknown>;
+    const sig = extractSignature(part);
+    if (!sig) continue;
+    const fc = part.functionCall as { name?: unknown; args?: unknown } | undefined;
+    const ck = fc ? functionCallKey(fc.name, fc.args) : undefined;
+    if (!ck) continue; // only function-call signatures are replayable by identity
+    const signatureBytes = utf8.encode(sig).byteLength;
+    const sizeBytes = utf8.encode(ck).byteLength + signatureBytes;
+    if (signatureBytes > replayLimits.maxSignatureBytes || sizeBytes > replayLimits.maxBytesPerSession) continue;
+    deleteReplayCall(entry, ck);
+    entry.byCall.set(ck, { signature: sig, sizeBytes, touchedAtMs: now });
+    entry.bytes += sizeBytes;
+    replayBytes += sizeBytes;
+    inserted = true;
+  }
+  if (!inserted) return;
+  evictInnerCalls(entry);
+  entry.expiresAtMs = now + REPLAY_TTL_MS;
+  replayCache.set(key, entry);
+  refreshReplaySessionCandidate(key, entry);
+  evictIfNeeded();
+  enforceAppOwnedMemoryBudget();
+}
+
+/**
+ * Re-inject cached thought signatures into the outgoing `request.contents`, matched by functionCall
+ * identity across ALL model turns (not just the last one). Only fills a functionCall part that
+ * lacks a real signature. Returns the same array reference (mutated in place).
+ */
+export function applyAntigravityReplay(model: string, sessionId: string, contents: unknown[]): unknown[] {
+  if (!antigravityUsesReplayCache(model) || !Array.isArray(contents)) return contents;
+  const now = Date.now();
+  deleteExpiredReplaySessions(now);
+  const entry = replayCache.get(replayKey(model, sessionId));
+  if (!entry) {
+    return contents;
+  }
+  let touched = false;
+  for (const c of contents as { role?: string; parts?: unknown[] }[]) {
+    if (!c || typeof c !== "object" || c.role !== "model" || !Array.isArray(c.parts)) continue;
+    for (const raw of c.parts) {
+      if (!raw || typeof raw !== "object") continue;
+      const part = raw as Record<string, unknown>;
+      const fc = part.functionCall as { name?: unknown; args?: unknown } | undefined;
+      if (!fc) continue;
+      if (part.thoughtSignature !== undefined || part.thought_signature !== undefined) continue;
+      const ck = functionCallKey(fc.name, fc.args);
+      const call = ck ? entry.byCall.get(ck) : undefined;
+      if (call && ck) {
+        part.thoughtSignature = call.signature;
+        entry.byCall.delete(ck);
+        entry.byCall.set(ck, { ...call, touchedAtMs: now });
+        touched = true;
+      }
+    }
+  }
+  if (touched) refreshReplaySessionCandidate(replayKey(model, sessionId), entry);
+  return contents;
+}
+
+/** Drop the cache entry when upstream rejects a signature (clear-on-invalid). */
+export function clearAntigravityReplay(model: string, sessionId: string): void {
+  deleteReplaySession(replayKey(model, sessionId));
+}
+
+export function antigravityReplayMetrics(): {
+  sessions: number;
+  calls: number;
+  totalBytes: number;
+  largestSessionBytes: number;
+} {
+  let calls = 0;
+  let largestSessionBytes = 0;
+  for (const entry of replayCache.values()) {
+    calls += entry.byCall.size;
+    largestSessionBytes = Math.max(largestSessionBytes, entry.bytes);
+  }
+  return { sessions: replayCache.size, calls, totalBytes: replayBytes, largestSessionBytes };
+}
+
+export function antigravityReplayRetainedStoreSnapshot(): {
+  count: number;
+  bytes: number;
+  evictableBytes: number;
+  pinnedBytes: number;
+  oldestAt: number | null;
+} {
+  return {
+    count: replayCache.size,
+    bytes: replayBytes,
+    evictableBytes: replayBytes,
+    pinnedBytes: 0,
+    oldestAt: replayOldestAt,
+  };
+}
+
+export function evictOldestAntigravityReplayForBudget(): number {
+  return replayOldestSessionKey === undefined ? 0 : deleteReplaySession(replayOldestSessionKey);
+}
+
+export function setAntigravityReplayLimitsForTests(limits?: Partial<ReplayLimits>): void {
+  __resetAntigravityReplayCache();
+  replayLimits = limits ? { ...DEFAULT_REPLAY_LIMITS, ...limits } : { ...DEFAULT_REPLAY_LIMITS };
+}
+
+/** Test seam. */
+export function __resetAntigravityReplayCache(): void {
+  replayCache.clear();
+  replayBytes = 0;
+  replayOldestSessionKey = undefined;
+  replayOldestAt = null;
+}