@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/adapters/cursor/catalog.ts

@@ -3,6 +3,7 @@ import {
   normalizeCursorClaudeId,
   type NormalizedCursorClaudeId,
 } from "./claude-id";
+import { createHash } from "node:crypto";
 
 /**
  * Cursor umbrella catalog — the single source of truth for cursor model
@@ -599,7 +600,7 @@ export function resolveCursorSelection(
   pickedId: string,
   reasoning: string | undefined,
   liveMaxModeIds?: ReadonlySet<string>,
-  options: { fast?: boolean } = {},
+  options: { fast?: boolean; liveRosterScope?: string } = {},
 ): CursorResolvedSelection {
   const parsed = parseCursorVariantId(pickedId);
   if (!parsed.known) {
@@ -617,7 +618,10 @@ export function resolveCursorSelection(
   const requested = parsed.level ?? reasoning;
   const effort = cursorVariantEffort(spec, requested);
   const requestedClaude = normalizeCursorClaudeId(pickedId);
-  const claudeIdentity = liveCursorClaudeWireIdentities.get(parsed.baseId)
+  const scopedClaudeIdentities = options.liveRosterScope
+    ? liveCursorClaudeWireIdentitiesByScope.get(options.liveRosterScope)
+    : liveCursorClaudeWireIdentities;
+  const claudeIdentity = scopedClaudeIdentities?.get(parsed.baseId)
     ?? (requestedClaude
       ? { sourceBaseId: requestedClaude.sourceBaseId, spelling: requestedClaude.spelling }
       : undefined);
@@ -626,7 +630,9 @@ export function resolveCursorSelection(
     ? `${capability.wirePrefix}${canonicalId}`
     : canonicalId;
   const ultraRequested = parsed.ultra || reasoning?.toLowerCase() === "ultra";
-  const evidence = liveMaxModeIds ?? liveCursorMaxModeBases;
+  const evidence = liveMaxModeIds
+    ?? (options.liveRosterScope ? liveCursorMaxModeBasesByScope.get(options.liveRosterScope) : undefined)
+    ?? liveCursorMaxModeBases;
   const maxModeArmed = capability.maxModeVerified === true || evidence.has(parsed.baseId);
   return { wireId, canonicalId, maxMode: ultraRequested && maxModeArmed, known: true };
 }
@@ -639,15 +645,36 @@ export function resolveCursorSelection(
  */
 let liveCursorMaxModeBases: ReadonlySet<string> = new Set();
 let liveCursorClaudeWireIdentities: ReadonlyMap<string, CursorLiveClaudeWireIdentity> = new Map();
+const liveCursorMaxModeBasesByScope = new Map<string, ReadonlySet<string>>();
+const liveCursorClaudeWireIdentitiesByScope = new Map<string, ReadonlyMap<string, CursorLiveClaudeWireIdentity>>();
+const liveCursorRosterScopesByProvider = new Map<string, Set<string>>();
+
+/** Non-secret key binding live roster evidence to one upstream destination and credential. */
+export function cursorLiveRosterScope(baseUrl: string | undefined, credential: string): string {
+  const destination = (baseUrl?.trim().replace(/\/+$/, "") || "https://api2.cursor.sh");
+  return createHash("sha256")
+    .update("ocx:cursor:live-roster\0")
+    .update(destination)
+    .update("\0")
+    .update(credential)
+    .digest("hex");
+}
 
-export function recordLiveCursorClaudeModels(liveIds: readonly string[]): void {
+export function recordLiveCursorClaudeModels(liveIds: readonly string[], scope?: { provider: string; key: string }): void {
   const next = new Map<string, CursorLiveClaudeWireIdentity>();
   for (const rawId of liveIds) {
     const n = normalizeCursorClaudeId(rawId.startsWith("cursor-") ? rawId.slice(7) : rawId);
     if (!n || !CURSOR_CAPABILITIES[n.canonicalBaseId]) continue;
     if (!next.has(n.canonicalBaseId)) next.set(n.canonicalBaseId, { sourceBaseId: n.sourceBaseId, spelling: n.spelling });
   }
-  liveCursorClaudeWireIdentities = next;
+  if (scope) {
+    liveCursorClaudeWireIdentitiesByScope.set(scope.key, next);
+    const scopes = liveCursorRosterScopesByProvider.get(scope.provider) ?? new Set<string>();
+    scopes.add(scope.key);
+    liveCursorRosterScopesByProvider.set(scope.provider, scopes);
+  } else {
+    liveCursorClaudeWireIdentities = next;
+  }
 }
 
 export function liveCursorClaudeWireIdentitiesForTests(): ReadonlyMap<string, CursorLiveClaudeWireIdentity> {
@@ -656,15 +683,32 @@ export function liveCursorClaudeWireIdentitiesForTests(): ReadonlyMap<string, Cu
 
 export function resetLiveCursorClaudeWireIdentitiesForTests(): void {
   liveCursorClaudeWireIdentities = new Map();
+  liveCursorClaudeWireIdentitiesByScope.clear();
+  liveCursorRosterScopesByProvider.clear();
 }
 
-export function recordLiveCursorMaxModeModels(liveIds: readonly string[]): void {
+export function recordLiveCursorMaxModeModels(liveIds: readonly string[], scope?: { provider: string; key: string }): void {
   const bases = new Set<string>();
   for (const id of liveIds) {
     const parsed = parseCursorVariantId(id);
     if (parsed.known) bases.add(parsed.baseId);
   }
-  liveCursorMaxModeBases = bases;
+  if (scope) liveCursorMaxModeBasesByScope.set(scope.key, bases);
+  else liveCursorMaxModeBases = bases;
+}
+
+export function clearLiveCursorRosterState(provider?: string): void {
+  if (!provider) {
+    liveCursorClaudeWireIdentitiesByScope.clear();
+    liveCursorMaxModeBasesByScope.clear();
+    liveCursorRosterScopesByProvider.clear();
+    return;
+  }
+  for (const scope of liveCursorRosterScopesByProvider.get(provider) ?? []) {
+    liveCursorClaudeWireIdentitiesByScope.delete(scope);
+    liveCursorMaxModeBasesByScope.delete(scope);
+  }
+  liveCursorRosterScopesByProvider.delete(provider);
 }
 
 export function liveCursorMaxModeBasesForTests(): ReadonlySet<string> {

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

@@ -42,6 +42,7 @@ export interface CursorCheckpointSnapshot {
   coveredMessageCount?: number;
   prefixDigest?: string;
   systemDigest?: string;
+  toolSuspended?: boolean;
 }
 
 interface CursorCheckpointStore {
@@ -229,6 +230,7 @@ export function commitCursorCheckpoint(input: {
   coveredMessageCount?: number;
   prefixDigest?: string;
   systemDigest?: string;
+  toolSuspended?: boolean;
 }): string | undefined {
   if (!input.conversationId || !input.modelId || input.checkpointBytes.byteLength === 0) return undefined;
   if (input.checkpointBytes.byteLength > CURSOR_CHECKPOINT_MAX_TOTAL_BYTES) return undefined;
@@ -258,6 +260,7 @@ export function commitCursorCheckpoint(input: {
     ...(input.coveredMessageCount !== undefined ? { coveredMessageCount: input.coveredMessageCount } : {}),
     ...(input.prefixDigest ? { prefixDigest: input.prefixDigest } : {}),
     ...(input.systemDigest ? { systemDigest: input.systemDigest } : {}),
+    ...(input.toolSuspended ? { toolSuspended: true } : {}),
   };
   const blobIds = collectCheckpointBlobIds(input.checkpointBytes);
   if (blobIds === undefined) return undefined;

package/src/adapters/cursor/discovery.ts

@@ -305,15 +305,18 @@ export function isCursorRouterModelId(modelId: string): boolean {
 export function filterCursorConfiguredModelsByLiveDiscovery<T extends { id: string }>(
   configured: readonly T[],
   liveIds: readonly string[],
+  maxModeLiveIds: readonly string[] = [],
 ): T[] {
-  return configured.filter(model =>
-    !CURSOR_KNOWN_UNCALLABLE_MODEL_IDS.has(model.id)
-    && (
-      isCursorRouterModelId(model.id)
-      // Synthetic ultra rows ride their base model's account availability.
-      || isCursorModelAvailableForAccount(cursorUltraBaseModelId(model.id) ?? model.id, liveIds)
-    ),
-  );
+  return configured.filter(model => {
+    if (CURSOR_KNOWN_UNCALLABLE_MODEL_IDS.has(model.id)) return false;
+    if (isCursorRouterModelId(model.id)) return true;
+    const ultraBase = cursorUltraBaseModelId(model.id);
+    return isCursorModelAvailableForAccount(ultraBase ?? model.id, liveIds)
+      // Successful discovery is authoritative: synthetic ultra rows additionally require the
+      // account-specific Max Mode capability. Discovery failures bypass this filter and retain
+      // the static seed under the caller's existing degraded-catalog policy.
+      && (ultraBase === undefined || isCursorModelAvailableForAccount(ultraBase, maxModeLiveIds));
+  });
 }
 
 /**

package/src/adapters/cursor/live-transport.ts

@@ -87,7 +87,7 @@ import {
   type BackgroundShellTerminationReport,
 } from "./native-exec-shell";
 import type { CursorClientMessage, CursorRunRequest, CursorServerMessage } from "./types";
-import type { CursorTransport, CursorTransportFactoryInput } from "./transport";
+import type { CursorStreamHealthClock, CursorTransport, CursorTransportFactoryInput } from "./transport";
 import { CursorHttp1BidiConnection } from "./http1-bidi";
 import { isPinnedHttp1 } from "../../lib/upstream-http-version";
 
@@ -107,6 +107,16 @@ const CURSOR_STREAM_SILENCE_FAIL_MS = 30_000;
  * Reset on every decoded frame that is not liveness-only.
  */
 const CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS = 90_000;
+/**
+ * The production T04 clock. The watchdog reads time and schedules its one timer through this
+ * object so a test can supply a clock it advances by hand; nothing else about the transport's
+ * timers moves with it.
+ */
+const REAL_STREAM_HEALTH_CLOCK: CursorStreamHealthClock = {
+  now: () => Date.now(),
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: timer => clearTimeout(timer),
+};
 /**
  * After `turnEnded` is decoded, the application turn is complete. A server that keeps
  * HTTP/2 open past this point cannot hold the turn hostage (senpi #1062): we close our side
@@ -494,6 +504,8 @@ class LiveCursorTransport implements CursorTransport {
   private lastInboundFrameAt = 0;
   private lastMeaningfulFrameAt = 0;
   private streamHealthFail?: (error: Error) => void;
+  /** Time source for the T04 watchdog only; the globals unless a test injects one. */
+  private readonly streamHealthClock: CursorStreamHealthClock;
   private committed = false;
   private expectedClose = false;
   /**
@@ -542,6 +554,7 @@ class LiveCursorTransport implements CursorTransport {
     // so the transport-level race test can drive it deterministically.
     this.clientToolFinalizeGraceMs = input.clientToolFinalizeGraceMs ?? CLIENT_TOOL_FINALIZE_GRACE_MS;
     this.activeClientToolFinalizeGraceMs = this.clientToolFinalizeGraceMs;
+    this.streamHealthClock = input.streamHealthClock ?? REAL_STREAM_HEALTH_CLOCK;
     // Desktop (computer-use / record-screen) executors are available even with no MCP servers.
     this.desktopDeps = desktopDepsFromConfig(input.provider.desktopExecutor);
     this.execContext = {
@@ -847,7 +860,7 @@ class LiveCursorTransport implements CursorTransport {
 
   private clearStreamHealthTimer(): void {
     if (this.streamHealthTimer) {
-      clearTimeout(this.streamHealthTimer);
+      this.streamHealthClock.clearTimeout(this.streamHealthTimer);
       this.streamHealthTimer = undefined;
     }
     this.streamHealthFail = undefined;
@@ -858,24 +871,28 @@ class LiveCursorTransport implements CursorTransport {
    * failAndClear; the timer owns nothing else. Never armed before the first decoded
    * frame (the first-frame timer covers dial + first response), and disarmed by
    * every settle / expected-close path alongside the other timers.
+   *
+   * Both clocks and the timer go through `streamHealthClock`, which is the globals in
+   * production. The `elapsedMs` diagnostic below deliberately stays on the wall clock,
+   * because `turnStartedAt` is stamped there and the pair has to subtract coherently.
    */
   private armStreamHealthTimer(fail: (error: Error) => void): void {
-    if (this.streamHealthTimer) clearTimeout(this.streamHealthTimer);
+    if (this.streamHealthTimer) this.streamHealthClock.clearTimeout(this.streamHealthTimer);
     if (this.expectedClose) return;
     this.streamHealthFail = fail;
     const silenceMs = this.input.streamSilenceFailMs ?? CURSOR_STREAM_SILENCE_FAIL_MS;
     const heartbeatOnlyMs = this.input.streamHeartbeatOnlyFailMs ?? CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS;
-    const now = Date.now();
+    const now = this.streamHealthClock.now();
     const deadline = Math.min(
       this.lastInboundFrameAt + silenceMs,
       this.lastMeaningfulFrameAt + heartbeatOnlyMs,
     );
-    this.streamHealthTimer = setTimeout(() => {
+    this.streamHealthTimer = this.streamHealthClock.setTimeout(() => {
       this.streamHealthTimer = undefined;
       const failFn = this.streamHealthFail;
       if (!failFn || this.expectedClose) return;
-      const stalledFor = Date.now() - this.lastInboundFrameAt;
-      const meaningfulStalledFor = Date.now() - this.lastMeaningfulFrameAt;
+      const stalledFor = this.streamHealthClock.now() - this.lastInboundFrameAt;
+      const meaningfulStalledFor = this.streamHealthClock.now() - this.lastMeaningfulFrameAt;
       if (stalledFor < silenceMs && meaningfulStalledFor < heartbeatOnlyMs) {
         // A frame landed between arming and firing — re-arm for the fresh deadline.
         this.armStreamHealthTimer(failFn);
@@ -906,7 +923,7 @@ class LiveCursorTransport implements CursorTransport {
    * heartbeat-only threshold.
    */
   private noteInboundFrame(livenessOnly: boolean): void {
-    const now = Date.now();
+    const now = this.streamHealthClock.now();
     this.lastInboundFrameAt = now;
     if (!livenessOnly) this.lastMeaningfulFrameAt = now;
     if (this.streamHealthFail) this.armStreamHealthTimer(this.streamHealthFail);
@@ -1288,7 +1305,7 @@ class LiveCursorTransport implements CursorTransport {
       const decodedUpdate = decoded.message.case === "interactionUpdate" ? decoded.message.value.message?.case : undefined;
       const livenessOnly = decodedUpdate === "heartbeat" || decoded.message.case === "conversationCheckpointUpdate";
       if (!this.streamHealthFail) {
-        const now = Date.now();
+        const now = this.streamHealthClock.now();
         this.lastInboundFrameAt = now;
         this.lastMeaningfulFrameAt = now;
         this.streamHealthFail = failAndClear;

package/src/adapters/cursor/protobuf-request.ts

@@ -741,7 +741,7 @@ function contentText(message: OcxMessage): string {
   if (typeof message.content === "string") return message.content;
   return message.content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "thinking") return part.thinking;
       if (part.type === "image") return undefined;
       return undefined;
@@ -754,7 +754,7 @@ function contentToText(content: OcxToolResultMessage["content"]): string {
   if (typeof content === "string") return content;
   return content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "image") return CURSOR_VISION_IMAGE_HISTORY_MARKER;
       return undefined;
     })
@@ -767,7 +767,7 @@ function historyContentText(message: OcxMessage): string {
   if (message.role === "toolResult" || typeof message.content === "string") return contentText(message);
   return message.content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "thinking") return part.thinking;
       if (part.type === "image") return CURSOR_VISION_IMAGE_HISTORY_MARKER;
       return undefined;
@@ -836,6 +836,9 @@ function decodeResultParts(message: OcxToolResultMessage): DecodedResultPart[] |
   return content.map((part): DecodedResultPart => {
     if (part.type === "text") return { kind: "text", text: part.text };
     if (part.type === "video") return { kind: "text", text: "[video]" };
+    // Without this the document falls through to decodeInlineImage(part.imageUrl) below and is
+    // treated as an image it is not.
+    if (part.type === "document") return { kind: "text", text: part.text };
     const decoded = decodeInlineImage(part.imageUrl);
     return decoded ? { kind: "image", ...decoded } : { kind: "undecodable" };
   });

package/src/adapters/cursor/request-builder.ts

@@ -213,7 +213,7 @@ export function cursorRequestEmitsFastVariant(parsed: OcxParsedRequest): boolean
  * instead: current Cursor clients send the matching Grok base id plus `effort` and `fast` parameters.
  * A fully-qualified id (one that is not a known effort base) passes through unchanged.
  */
-function normalizeCursorModelId(modelId: string, reasoning?: string, fast?: boolean): {
+function normalizeCursorModelId(modelId: string, reasoning?: string, fast?: boolean, liveRosterScope?: string): {
   modelId: string;
   requestedModelParameters?: readonly CursorRequestedModelParameter[];
   routingLevel?: CursorRoutingLevel;
@@ -239,7 +239,7 @@ function normalizeCursorModelId(modelId: string, reasoning?: string, fast?: bool
       ],
     };
   }
-  const resolved = resolveCursorSelection(id, reasoning, undefined, { fast });
+  const resolved = resolveCursorSelection(id, reasoning, undefined, { fast, liveRosterScope });
   return {
     ...selection,
     ...(resolved.maxMode ? { maxMode: true } : {}),
@@ -251,6 +251,9 @@ function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): stri
   switch (part.type) {
     case "text":
       return part.text;
+    case "document":
+      // Cursor has no document carrier; the marker keeps the turn from serializing to nothing.
+      return part.text;
     case "thinking":
       return part.thinking;
     case "image":
@@ -407,6 +410,8 @@ export function cursorCoveredPrefixDigest(parsed: OcxParsedRequest, coveredMessa
 export interface CreateCursorRequestOptions {
   /** Force a brand-new Cursor conversation id even when remembered state exists. */
   forceFreshConversation?: boolean;
+  /** Credential-bound scope for live Cursor model spelling and Max-Mode evidence. */
+  liveRosterScope?: string;
 }
 
 function lookupPrefixSnapshot(
@@ -476,7 +481,13 @@ function resolveCursorCheckpoint(
   if (cursorCheckpointModelAffinityId(snapshot.modelId) !== cursorCheckpointModelAffinityId(request.modelId)) {
     return { reason: "model_changed" };
   }
-  if (parsed.context.messages.at(-1)?.role !== "toolResult" && cursorState?.checkpointUsable === false) {
+  // The continuation state only exists on the ref path; a ref-less prefix hit carries
+  // the suspension on the snapshot itself, or a non-toolResult request could resume
+  // bytes upstream serialized mid-tool-call.
+  if (
+    parsed.context.messages.at(-1)?.role !== "toolResult"
+    && (snapshot.toolSuspended === true || cursorState?.checkpointUsable === false)
+  ) {
     return { reason: "trailing_tool_result" };
   }
   const lineage = lineageMismatch(parsed, snapshot);
@@ -493,7 +504,12 @@ export function createCursorRequest(
   const visibleTools = cursorToolsForActivePrompt(parsed.context.tools, activeText, parsed.options.toolChoice);
   const budget = applyCursorToolBudget(visibleTools, parsed.options.toolChoice);
   const limitNote = catalogLimitNote(budget.tools, budget.omitted);
-  const model = normalizeCursorModelId(parsed.modelId, parsed.options.reasoning, cursorFastRequested(parsed));
+  const model = normalizeCursorModelId(
+    parsed.modelId,
+    parsed.options.reasoning,
+    cursorFastRequested(parsed),
+    options.liveRosterScope,
+  );
   const request: CursorRunRequest = {
     modelId: model.modelId,
     ...(model.requestedModelParameters ? { requestedModelParameters: model.requestedModelParameters } : {}),

package/src/adapters/cursor/transport.ts

@@ -55,6 +55,25 @@ export interface CursorTransportFactoryInput {
    * client thread. Distinct from the per-transport native-exec/shell owner.
    */
   sessionId?: string;
+  /**
+   * Test-only clock for the T04 inbound stream-health watchdog. Production omits it and the
+   * transport uses the global timers; injecting here must not change scheduling semantics.
+   *
+   * It exists because the watchdog's contract — a meaningful frame re-arms both deadlines — can
+   * only be asserted against real timers by keeping a synthetic server delivering frames faster
+   * than the silence budget for several multiples of it. That is an assertion about how busy the
+   * machine is, and it failed in the unsharded macOS lane for exactly that reason while the
+   * watchdog was working correctly. With the clock injected, virtual time advances only where
+   * the test says it does, so no amount of runner contention can expire a deadline.
+   */
+  streamHealthClock?: CursorStreamHealthClock;
+}
+
+/** The three time primitives the T04 watchdog uses. Production binds all three to the globals. */
+export interface CursorStreamHealthClock {
+  now(): number;
+  setTimeout(callback: () => void, ms: number): ReturnType<typeof setTimeout>;
+  clearTimeout(timer: ReturnType<typeof setTimeout>): void;
 }
 
 export type CursorTransportFactory = (input: CursorTransportFactoryInput) => CursorTransport;

package/src/adapters/cursor.ts

@@ -61,6 +61,7 @@ import {
   CursorTransportDisabledError,
   type CursorTransportFactory,
 } from "./cursor/transport";
+import { cursorLiveRosterScope } from "./cursor/catalog";
 
 export const CURSOR_API_URL = "https://api2.cursor.sh";
 
@@ -172,9 +173,11 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         // 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.
+        let liveRosterScope: string | undefined;
         if (!_parsed._cursorIdentityScope) {
           try {
             const token = resolveCursorToken(provider, incoming.headers);
+            liveRosterScope = cursorLiveRosterScope(provider.baseUrl, token);
             _parsed._cursorIdentityScope = createHash("sha256")
               .update("ocx:cursor:acct:")
               .update(token)
@@ -183,11 +186,17 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           } catch {
             /* Missing credential is handled by the live transport path below. */
           }
+        } else {
+          try {
+            liveRosterScope = cursorLiveRosterScope(provider.baseUrl, resolveCursorToken(provider, incoming.headers));
+          } catch {
+            /* Missing credential is handled by the live transport path below. */
+          }
         }
         const inheritedCheckpointRef = _parsed._providerContinuation?.cursor?.checkpointRef;
         const previousConversationId = _parsed._cursorConversationId;
         let request = {
-          ...createCursorRequest(_parsed),
+          ...createCursorRequest(_parsed, { liveRosterScope }),
           _cursorIdentityScope: _parsed._cursorIdentityScope?.trim() || "local",
         };
         requestSizeContext = cursorRequestSizeContext(request);
@@ -254,6 +263,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             coveredMessageCount,
             prefixDigest: cursorCoveredPrefixDigest(_parsed, coveredMessageCount),
             systemDigest: cursorInstructionDigest(_parsed),
+            toolSuspended: toolSuspendedCommit,
           });
           if (!checkpointRef) return;
           if (previousRef && previousRef !== checkpointRef) invalidateCursorCheckpoint(previousRef);
@@ -263,7 +273,8 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
               ...(_parsed._providerContinuation?.cursor ?? {}),
               conversationId: activeRequest.conversationId,
               // A tool-suspended checkpoint is only usable by the immediate trailing-toolResult
-              // continuation; the request-builder guard keys on checkpointUsable=false for that.
+              // continuation; the request-builder guard keys on this checkpointUsable=false and
+              // the snapshot's persisted toolSuspended flag for that.
               checkpointUsable: !toolSuspendedCommit,
               checkpointRef,
             },
@@ -439,7 +450,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           lastTransport = undefined;
           _parsed._cursorConversationId = undefined;
           const next = {
-            ...createCursorRequest(_parsed, { forceFreshConversation: true }),
+            ...createCursorRequest(_parsed, { forceFreshConversation: true, liveRosterScope }),
             _cursorIdentityScope: _parsed._cursorIdentityScope?.trim() || "local",
           };
           rekeyContextUsage(failedConversationId, next.conversationId);

package/src/adapters/declaration-carrier.ts

@@ -0,0 +1,45 @@
+// Type-only: erased at compile time, so this does not create an import cycle with the registry.
+import type { AdapterWire } from "./registry";
+import type { OcxMessage, OcxParsedRequest } from "../types";
+import { toolRestrictsCallers } from "../types";
+
+/**
+ * Wires that can actually carry a constraint, as a default-deny allowlist.
+ *
+ * A per-adapter opt-in is the wrong shape for this: an adapter that never learned about a
+ * carrier rebuilds the declaration or the message without it and returns a normal completion,
+ * which is exactly the silent widening this batch exists to remove. Listing the wires that CAN
+ * carry it means a new wire refuses until someone teaches it, and adding a member to
+ * `AdapterWire` makes the omission visible here rather than at a customer's upstream.
+ */
+const CALLER_RESTRICTION_WIRES: ReadonlySet<AdapterWire> = new Set<AdapterWire>(["anthropic"]);
+const INLINE_DOCUMENT_WIRES: ReadonlySet<AdapterWire> = new Set<AdapterWire>([
+  "anthropic",
+  "openai-chat",
+  "google",
+]);
+
+/** A fixed-vocabulary refusal, or `undefined` when this wire can hold everything the request carries. */
+export function unrepresentableDeclaration(parsed: OcxParsedRequest, wire: AdapterWire): string | undefined {
+  if (!CALLER_RESTRICTION_WIRES.has(wire) && parsed.context.tools?.some(toolRestrictsCallers)) {
+    // The name is deliberately absent: it is caller-controlled and would put client metadata
+    // into an error body.
+    return "OpenCodex cannot express tools[].allowed_callers on this route. "
+      + "Route the request to an Anthropic-protocol provider, or remove the caller restriction.";
+  }
+  if (!INLINE_DOCUMENT_WIRES.has(wire) && parsed.context.messages.some(carriesDocument)) {
+    return "OpenCodex cannot translate document input on this route. "
+      + "Use a native input wire that supports the attachment, or convert it to text first.";
+  }
+  return undefined;
+}
+
+/**
+ * Typed structurally rather than as `OcxContentPart[]`: an assistant turn's content is
+ * `OcxAssistantContentPart[]`, which carries thinking and tool-call members and is not
+ * assignable to the user-content union. Only the discriminant is read here.
+ */
+function carriesDocument(message: OcxMessage): boolean {
+  const content: unknown = message.content;
+  return Array.isArray(content) && (content as ReadonlyArray<{ type: string }>).some(part => part.type === "document");
+}

package/src/adapters/devin/cloud-direct/chat.ts

@@ -1055,6 +1055,8 @@ export interface CloudChatRequest {
   catalog?: CacheEntry | null;
   /** Abort signal — closes the fetch stream. */
   signal?: AbortSignal;
+  /** Executor for the inference POST only; catalog and JWT RPCs retain their own transport. */
+  executor?: typeof globalThis.fetch;
 }
 
 export class CloudChatError extends Error {
@@ -1216,7 +1218,7 @@ export async function* streamChatEvents(req: CloudChatRequest): AsyncGenerator<C
 
   let resp: Response;
   try {
-    resp = await fetch(`${host}/exa.api_server_pb.ApiServerService/GetChatMessage`, {
+    resp = await (req.executor ?? globalThis.fetch)(`${host}/exa.api_server_pb.ApiServerService/GetChatMessage`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/connect+proto',

package/src/adapters/devin/cloud-direct/stated-reset-retry.ts

@@ -5,7 +5,9 @@
  * is idempotent; ambiguous transport failures still propagate unchanged.
  */
 import { parseRetryAfterFromMessage } from '../../../lib/retry-delay.js';
-import { abortError, sleepWithAbort } from '../../../lib/upstream-retry.js';
+import type { AdapterFetchContext } from '../../base.js';
+import { createAdapterPhysicalSend } from '../../physical-send.js';
+import { abortError, SendBudgetExhaustedError, sleepWithAbort } from '../../../lib/upstream-retry.js';
 import { CloudChatError, streamChatEvents, type CloudChatEvent, type CloudChatRequest } from './chat.js';
 
 /** 1 initial attempt plus at most 2 replays. */
@@ -33,6 +35,11 @@ export interface StatedResetRetryOptions {
   maxReplays?: number;
   /** CUMULATIVE wait allowance, not a fresh allowance on every failure. */
   maxWaitMs?: number;
+  /** Request-wide execution authority. Absent preserves context-free callers' unlimited fetch. */
+  execution?: Pick<
+    AdapterFetchContext,
+    "executor" | "sendBudget" | "onPhysicalSend" | "onRecoveryWithheld"
+  >;
 }
 
 function replayLimit(value: number | undefined): number {
@@ -59,15 +66,34 @@ export async function* streamChatEventsWithResetRetry(
   const sleep = options?.sleep ?? sleepWithAbort;
   const maxReplays = replayLimit(options?.maxReplays);
   const maxWaitMs = waitLimit(options?.maxWaitMs);
+  const execution = options?.execution;
+  // One sender owns the whole invocation so ordinals span the initial POST and both replays.
+  // Its executor remains lazy: replay admission happens after the provider-stated wait, never
+  // while a reservation could be held for up to an hour.
+  const send = execution
+    ? createAdapterPhysicalSend({ ...execution, abortSignal: req.signal })
+    : undefined;
   let replays = 0;
   let waitedMs = 0;
+  let replaySourceError: CloudChatError | undefined;
   while (true) {
     // Check again after sleeping: cancellation can race with timer completion.
     // A pre-aborted request must not even enter a custom transport.
     if (req.signal?.aborted) throw abortError(req.signal);
     let yielded = false;
     try {
-      for await (const event of stream(req)) {
+      const recovery = replays > 0 ? "rate-limit-429" as const : undefined;
+      const attemptRequest = send
+        ? {
+            ...req,
+            executor: ((input, init) => send({
+              url: typeof input === "string" ? input : input instanceof URL ? input.href : input.url,
+              ...(recovery ? { sendClass: "auth-recovery" as const, recovery } : {}),
+              dispatch: executor => executor(input, init),
+            })) as typeof globalThis.fetch,
+          }
+        : req;
+      for await (const event of stream(attemptRequest)) {
         // Latch before yielding, so a consumer-injected error is post-output.
         yielded = true;
         yield event;
@@ -75,14 +101,24 @@ export async function* streamChatEventsWithResetRetry(
       return;
     } catch (error) {
       if (req.signal?.aborted) throw abortError(req.signal);
-      const waitSec = !yielded
+      if (!yielded && error instanceof SendBudgetExhaustedError && replaySourceError) {
+        // The provider's refusal is the real upstream answer. A local cap can withhold its
+        // recovery, but replacing the 429 would erase the status and stated reset metadata.
+        execution?.onRecoveryWithheld?.({ reason: "retry-send-budget" });
+        throw replaySourceError;
+      }
+      const retryableError = !yielded
         && error instanceof CloudChatError
         && error.status === 429
-        ? parseRetryAfterFromMessage(error.message)
+        ? error
+        : undefined;
+      const waitSec = retryableError
+        ? parseRetryAfterFromMessage(retryableError.message)
         : undefined;
       const waitMs = waitSec === undefined ? undefined : waitSec * 1000;
       if (
-        waitMs === undefined
+        retryableError === undefined
+        || waitMs === undefined
         || replays >= maxReplays
         || waitMs > maxWaitMs - waitedMs
       ) {
@@ -91,6 +127,7 @@ export async function* streamChatEventsWithResetRetry(
         throw error;
       }
       replays += 1;
+      replaySourceError = retryableError;
       // Charge the complete scheduled wait once, before sleeping. This is a
       // sleep allowance, not a wall-clock deadline on generation or timer
       // scheduling: waking a few milliseconds late must not reject an already