@bitkyc08/opencodex 2.56.0 → 2.58.0

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

@@ -11,13 +11,19 @@ import {
   isCodexShellBridgeToolName,
   isCursorStructuredEditToolName,
   normalizeCursorWireName,
-  normalizeCursorTextToolMarkers,
   OCX_RESPONSES_TOOL_PROVIDER,
   resolveShellBridgeAliasKey,
   responsesToolNameFromCursorWire,
 } from "./tool-definitions";
+import {
+  drainCursorTextToolCalls,
+  type DrainedTextToolCall,
+  type SuppressedTextToolCallScan,
+} from "./text-toolcall";
+import { recordObservedCursorContextWindow } from "./discovery";
 import type { CursorServerMessage } from "./types";
 import type { TranslatorBudget } from "../../lib/translator-budget";
+import { CURSOR_INCOMPLETE_TOOL_CALL_MESSAGE_PREFIX } from "./cursor-errors";
 
 const DEFAULT_CONTEXT_USAGE_MAX_ENTRIES = 200;
 const DEFAULT_CONTEXT_USAGE_TTL_MS = 60 * 60 * 1_000;
@@ -176,6 +182,23 @@ export interface CursorProtobufEventState {
    */
   syntheticStructuredEditToolNames?: ReadonlySet<string>;
   translatorBudget?: TranslatorBudget;
+  /**
+   * Incomplete `[TOOL_CALL]…[ARGS]{` prefix held across `textDelta` frames so a
+   * marker split by the stream cannot leak into assistant text.
+   */
+  pendingTextToolCall?: string;
+  /** Constant-space scanner used after an incomplete textual marker exceeds its retained byte cap. */
+  suppressedTextToolCall?: SuppressedTextToolCallScan;
+  /** Parsed textual fallback calls held until turn finalization establishes that no real frame won. */
+  bufferedTextToolCalls?: DrainedTextToolCall[];
+  /** True once this turn carries any real client-tool frame, including an incomplete one. */
+  sawRealClientToolCall?: boolean;
+  /** Monotonic id suffix for tool calls promoted from text markers. */
+  textToolCallSeq?: number;
+  /** Wire model id used to record checkpoint `maxTokens` for the next turn. */
+  wireModelId?: string;
+  /** Normalized Cursor identity scope that owns the observed checkpoint ceiling. */
+  identityScope: string;
 }
 
 
@@ -215,6 +238,10 @@ export function createCursorProtobufEventState(options: {
    */
   estimatedInputTokens?: number;
   translatorBudget?: TranslatorBudget;
+  /** Wire model id for recording checkpoint `maxTokens` into the process-local window map. */
+  wireModelId?: string;
+  /** Cursor request identity scope; normalized identically to request-builder continuity. */
+  identityScope?: string;
 } = {}): CursorProtobufEventState {
   return {
     // Cursor provides no authoritative usage frame; token counts are heuristic estimates from
@@ -244,6 +271,8 @@ export function createCursorProtobufEventState(options: {
       && options.estimatedInputTokens > 0
       ? { estimatedInputTokens: options.estimatedInputTokens }
       : {}),
+    ...(options.wireModelId?.trim() ? { wireModelId: options.wireModelId.trim() } : {}),
+    identityScope: options.identityScope?.trim() || "local",
   };
 }
 
@@ -1048,6 +1077,7 @@ export function mapSyntheticMcpExecToToolEvents(
 ): CursorServerMessage[] {
   if (args.providerIdentifier !== OCX_RESPONSES_TOOL_PROVIDER) return [];
   if (options.state?.terminated) return [];
+  if (options.state) options.state.sawRealClientToolCall = true;
   if (options.allowEmptyArgs !== true && !hasMcpArgBytes(args)) return [];
   const cursorWireName = mcpWireNameFromArgs(args);
   if (!cursorWireName) return [{ type: "error", message: "Cursor requested a Responses tool without a tool name" }];
@@ -1117,6 +1147,11 @@ function recordToolCall(state: CursorProtobufEventState, callId: string, cursorW
   return [];
 }
 
+function recordRealToolCall(state: CursorProtobufEventState, callId: string, cursorWireName: string): CursorServerMessage[] {
+  state.sawRealClientToolCall = true;
+  return recordToolCall(state, callId, cursorWireName);
+}
+
 /**
  * Emit a completed client tool call as one atomic unit: `tool_call_start` (deferred from open time),
  * the full normalized arguments delta when present, then `tool_call_end`. The call must already be
@@ -1232,33 +1267,70 @@ export function mapCursorProtobufServerMessage(
   if (state.terminated) return [];
 
   if (serverMessage.message.case === "conversationCheckpointUpdate") {
-    const usedTokens = serverMessage.message.value.tokenDetails?.usedTokens ?? 0;
+    const tokenDetails = serverMessage.message.value.tokenDetails;
+    const usedTokens = tokenDetails?.usedTokens ?? 0;
     // `usedTokens` is the ABSOLUTE conversation context size, not a per-turn output delta. Track it
     // separately (monotonic max) and surface it as `done.usage.totalTokens`; folding it into
     // `outputTokens` (which also accumulates `tokenDelta`) double-counts in Codex. See contextTokens.
     observeContextTokens(state, usedTokens);
+    // First checkpoints often send maxTokens=0 (senpi). Only a positive ceiling
+    // replaces the id heuristic for the next turn's overflow vs 429 size prior.
+    if (state.wireModelId) {
+      recordObservedCursorContextWindow(state.wireModelId, tokenDetails?.maxTokens, {
+        identityScope: state.identityScope,
+      });
+    }
     return [];
   }
 
   if (serverMessage.message.case !== "interactionUpdate") return [];
   const update = serverMessage.message.value.message;
   switch (update.case) {
-    case "textDelta":
-      // #2305: fold Cursor display aliases inside textual pseudo tool-call markers back to
-      // the advertised wire name before any client sees the text. Real frames are already
-      // normalized structurally (mcpWireNameFromArgs above).
-      return update.value.text ? [{ type: "text", text: normalizeCursorTextToolMarkers(update.value.text) }] : [];
+    case "textDelta": {
+      // Textual `[TOOL_CALL]name[ARGS]{…}` is not assistant prose. Leaving it in
+      // the text channel (even after #2305 renamed the display alias) leaks a
+      // synthetic protocol marker that later turns few-shot-mimic as inert text.
+      // Strip complete markers, buffer advertised fallbacks until finalize,
+      // and hold or suppress-scan an incomplete opener across deltas.
+      const chunk = update.value.text ?? "";
+      if (!chunk && !state.pendingTextToolCall && !state.suppressedTextToolCall) return [];
+      const drained = drainCursorTextToolCalls(
+        state.pendingTextToolCall ?? "",
+        chunk,
+        state.suppressedTextToolCall,
+      );
+      if (drained.pending) state.pendingTextToolCall = drained.pending;
+      else delete state.pendingTextToolCall;
+      if (drained.suppressed) state.suppressedTextToolCall = drained.suppressed;
+      else delete state.suppressedTextToolCall;
+      const out: CursorServerMessage[] = [];
+      if (drained.text) out.push({ type: "text", text: drained.text });
+      for (const call of drained.calls) {
+        const advertised = resolveAdvertisedClientToolName(state, call.name);
+        if (
+          state.sawRealClientToolCall
+          || !state.clientToolNames
+          || !advertised
+          || (state.bufferedTextToolCalls?.length ?? 0) >= state.maxClientToolCalls
+        ) continue;
+        (state.bufferedTextToolCalls ??= []).push({
+          name: advertised,
+          args: normalizeJsonText(call.args, advertised, state),
+        });
+      }
+      return out;
+    }
     case "thinkingDelta":
       return update.value.text ? [{ type: "thinking", thinking: update.value.text }] : [];
     case "toolCallStarted": {
       const name = mcpCursorWireName(update.value.toolCall);
       // Record the open call but defer the outward tool_call_start to completion (atomic emission).
-      return name ? recordToolCall(state, update.value.callId, name) : [];
+      return name ? recordRealToolCall(state, update.value.callId, name) : [];
     }
     case "partialToolCall": {
       const out: CursorServerMessage[] = [];
       const name = mcpCursorWireName(update.value.toolCall);
-      if (name) out.push(...recordToolCall(state, update.value.callId, name));
+      if (name) out.push(...recordRealToolCall(state, update.value.callId, name));
       if (out.some(event => event.type === "error")) return out;
       // Buffer cumulative args; do not emit a delta. Args are emitted once, normalized, at completion.
       if (state.openToolCalls.has(update.value.callId)) {
@@ -1274,6 +1346,7 @@ export function mapCursorProtobufServerMessage(
       const out: CursorServerMessage[] = [];
       if (state.completedToolCalls.has(update.value.callId)) return [];
       const name = mcpCursorWireName(update.value.toolCall);
+      if (name) state.sawRealClientToolCall = true;
       const args = mcpArgsFromToolCall(update.value.toolCall);
       const openBeforeStart = state.openToolCalls.get(update.value.callId);
       // Empty-arg completion handling:
@@ -1362,20 +1435,46 @@ export function resolvedTurnUsage(state: CursorProtobufEventState): OcxUsage {
  * with corrupt/empty arguments. Emit an explicit error instead of done (fail-closed).
  * Mirrors kiro-truncation.ts behavior.
  */
+/**
+ * True when this turn holds textual fallback tool calls that only turn finalization can emit.
+ *
+ * Cursor can close a stream with a clean Connect END_STREAM and no turnEnded frame. The transport
+ * finalizes that path only for a turn it can see is unfinished, and a turn whose entire visible
+ * text was a stripped marker looks empty from the outside. Without this the deferred fallback
+ * would be dropped exactly when the marker was the turn's only content.
+ */
+export function hasBufferedTextToolCalls(state: CursorProtobufEventState): boolean {
+  return (state.bufferedTextToolCalls?.length ?? 0) > 0;
+}
+
 export function finalizeTurnEvents(state: CursorProtobufEventState): CursorServerMessage[] {
   state.terminated = true;
+  delete state.pendingTextToolCall;
+  delete state.suppressedTextToolCall;
+  const bufferedTextToolCalls = state.bufferedTextToolCalls ?? [];
+  delete state.bufferedTextToolCalls;
   if (state.openToolCalls.size > 0) {
     const openCallIds = [...state.openToolCalls.keys()];
     const openIds = openCallIds.join(", ");
     // Clear so a second turnEnded (should not happen, but defensive) doesn't re-emit.
     for (const callId of openCallIds) state.translatorBudget?.closeCall(callId);
     state.openToolCalls.clear();
-    return [{ type: "error", message: `Cursor stream ended with incomplete tool call(s): ${openIds}. Arguments may be truncated; the call was not committed.` }];
+    return [{ type: "error", message: `${CURSOR_INCOMPLETE_TOOL_CALL_MESSAGE_PREFIX} ${openIds}. Arguments may be truncated; the call was not committed.` }];
+  }
+  const out: CursorServerMessage[] = [];
+  if (!state.sawRealClientToolCall) {
+    for (const call of bufferedTextToolCalls) {
+      state.textToolCallSeq = (state.textToolCallSeq ?? 0) + 1;
+      const callId = `textcall_${state.textToolCallSeq}`;
+      out.push(...recordToolCall(state, callId, call.name));
+      if (state.openToolCalls.has(callId)) out.push(...commitToolCall(state, callId, call.args));
+    }
   }
   // Surface the absolute context size (when Cursor reported a checkpoint) as both totalTokens and
   // the estimated input side of Codex's visible `input + output` counter. Codex status lines can
   // render the additive pair instead of total_tokens, so leaving inputTokens at 0 makes a 16k-context
   // first turn display as "9 used". Keep outputTokens as the per-turn delta and clamp the inferred
   // input to 0 in case Cursor reports a checkpoint smaller than the streamed output delta.
-  return [{ type: "done", usage: resolvedTurnUsage(state) }];
+  out.push({ type: "done", usage: resolvedTurnUsage(state) });
+  return out;
 }

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

@@ -75,6 +75,8 @@ export const CURSOR_ROUTING_LEVEL_PARAMETER_ID = "optimization";
 export const CURSOR_EXTERNAL_ROOT_BLOB_LIMIT = 192;
 /** Approximate prompt-size guard; tool schemas and protocol framing consume context separately. */
 export const CURSOR_EXTERNAL_ROOT_BYTE_LIMIT = 512 * 1024;
+/** Honest placeholder when native Composer history has a toolCall with no matching toolResult. */
+export const CURSOR_MISSING_TOOL_RESULT = "[missing tool_result for this tool_use in history]";
 /**
  * Byte budget for the serialized arguments named inside ONE replayed tool-result envelope. The
  * invocation identifies the call; the result is the payload. Without an independent cap, a single
@@ -1218,6 +1220,20 @@ function argBytes(value: unknown): Uint8Array {
   }
 }
 
+function missingToolResultFor(
+  part: Extract<OcxAssistantContentPart, { type: "toolCall" }>,
+): OcxToolResultMessage {
+  return {
+    role: "toolResult",
+    toolCallId: part.id,
+    toolName: part.name,
+    ...(part.namespace ? { toolNamespace: part.namespace } : {}),
+    content: CURSOR_MISSING_TOOL_RESULT,
+    isError: true,
+    timestamp: 0,
+  };
+}
+
 function toolCallStep(
   part: Extract<OcxAssistantContentPart, { type: "toolCall" }>,
   requestScope: CursorBlobRequestScopeToken,
@@ -1332,7 +1348,9 @@ function conversationTurns(
   const pendingToolCalls = new Map<string, Extract<OcxAssistantContentPart, { type: "toolCall" }>>();
   const flush = () => {
     if (!current) return;
-    for (const part of pendingToolCalls.values()) current.steps.push(toolCallStep(part, requestScope));
+    for (const part of pendingToolCalls.values()) {
+      current.steps.push(toolCallStep(part, requestScope, missingToolResultFor(part), codeMode));
+    }
     turns.push(storeCursorBlob(toBinary(ConversationTurnStructureSchema, create(ConversationTurnStructureSchema, {
       turn: {
         case: "agentConversationTurn",

package/src/adapters/cursor/text-toolcall.ts

@@ -0,0 +1,230 @@
+/**
+ * Quarantine textual pseudo tool-call markers that Cursor models emit inside
+ * `textDelta` instead of (or in addition to) real `toolCall*` frames.
+ *
+ * `#2305` only rewrote the display alias *inside* `[TOOL_CALL]…[ARGS]`. The
+ * marker still reached Codex/Claude as assistant text, which few-shot-mimics
+ * later calls as inert text and stalls multi-tool turns. This drain strips
+ * every complete marker from visible text and yields the parsed calls so the
+ * protobuf mapper can promote advertised names onto the real tool-call path.
+ *
+ * Incomplete markers (split across streaming deltas) stay in `pending` until
+ * the JSON object closes. Once the retained prefix exceeds the byte cap, the
+ * parser switches to a constant-space suppressed scan until the object closes.
+ */
+import { debugProviderDiagnostic } from "../../lib/debug";
+import { normalizeCursorWireName } from "./tool-naming";
+
+export const MAX_PENDING_TEXT_TOOLCALL_BYTES = 64 * 1024;
+const TOOL_CALL_OPEN = /\[TOOL_CALL\]/gi;
+
+export interface DrainedTextToolCall {
+  readonly name: string;
+  readonly args: string;
+}
+
+export interface SuppressedTextToolCallScan {
+  phase: "args-tag" | "json-start" | "json";
+  argsTagProgress: number;
+  depth: number;
+  inString: boolean;
+  escape: boolean;
+}
+
+export interface DrainTextToolCallsResult {
+  readonly text: string;
+  readonly pending: string;
+  readonly calls: readonly DrainedTextToolCall[];
+  readonly suppressed?: SuppressedTextToolCallScan;
+}
+
+function findJsonObjectEnd(source: string, start: number): number | undefined {
+  if (source[start] !== "{") return undefined;
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  for (let i = start; i < source.length; i++) {
+    const ch = source[i];
+    if (inString) {
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === "\"") inString = false;
+      continue;
+    }
+    if (ch === "\"") {
+      inString = true;
+      continue;
+    }
+    if (ch === "{") depth += 1;
+    else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return undefined;
+}
+
+function byteLength(text: string): number {
+  return new TextEncoder().encode(text).byteLength;
+}
+
+function newSuppressedScan(): SuppressedTextToolCallScan {
+  return {
+    phase: "args-tag",
+    argsTagProgress: 0,
+    depth: 0,
+    inString: false,
+    escape: false,
+  };
+}
+
+const ARGS_TAG = "[args]";
+
+function consumeSuppressedScan(
+  state: SuppressedTextToolCallScan,
+  source: string,
+  start = 0,
+): { readonly state?: SuppressedTextToolCallScan; readonly resumeAt: number } {
+  for (let i = start; i < source.length; i++) {
+    const ch = source[i] ?? "";
+    if (state.phase === "args-tag") {
+      const lower = ch.toLowerCase();
+      if (lower === ARGS_TAG[state.argsTagProgress]) {
+        state.argsTagProgress += 1;
+        if (state.argsTagProgress === ARGS_TAG.length) {
+          state.phase = "json-start";
+          state.argsTagProgress = 0;
+        }
+      } else {
+        state.argsTagProgress = lower === ARGS_TAG[0] ? 1 : 0;
+      }
+      continue;
+    }
+    if (state.phase === "json-start") {
+      if (/\s/.test(ch)) continue;
+      if (ch !== "{") {
+        debugProviderDiagnostic("cursor", "text-toolcall-invalid-arguments", {
+          reason: "arguments-did-not-start-with-object",
+        });
+        return { resumeAt: source.length };
+      }
+      state.phase = "json";
+      state.depth = 1;
+      continue;
+    }
+    if (state.inString) {
+      if (state.escape) {
+        state.escape = false;
+      } else if (ch === "\\") {
+        state.escape = true;
+      } else if (ch === "\"") {
+        state.inString = false;
+      }
+      continue;
+    }
+    if (ch === "\"") state.inString = true;
+    else if (ch === "{") state.depth += 1;
+    else if (ch === "}") {
+      state.depth -= 1;
+      if (state.depth === 0) return { resumeAt: i + 1 };
+    }
+  }
+  return { state, resumeAt: source.length };
+}
+
+function holdOrSuppress(hold: string, afterOpen: number): Pick<DrainTextToolCallsResult, "pending" | "suppressed"> {
+  if (byteLength(hold) <= MAX_PENDING_TEXT_TOOLCALL_BYTES) return { pending: hold };
+  const suppressed = newSuppressedScan();
+  const scanned = consumeSuppressedScan(suppressed, hold, afterOpen);
+  return scanned.state ? { pending: "", suppressed: scanned.state } : { pending: "" };
+}
+
+/**
+ * Fold `pending + chunk`, emit surrounding prose, and extract every complete
+ * `[TOOL_CALL]name[ARGS]{…}` block. Names are folded through
+ * `normalizeCursorWireName` so `mcp_opencodex-responses_*` display aliases
+ * become the advertised wire name before promotion.
+ */
+export function drainCursorTextToolCalls(
+  pending: string,
+  chunk: string,
+  suppressed?: SuppressedTextToolCallScan,
+): DrainTextToolCallsResult {
+  let combined = pending + chunk;
+  if (suppressed) {
+    const scanned = consumeSuppressedScan(suppressed, chunk);
+    if (scanned.state) return { text: "", pending: "", calls: [], suppressed: scanned.state };
+    combined = chunk.slice(scanned.resumeAt);
+  }
+  let cursor = 0;
+  let text = "";
+  const calls: DrainedTextToolCall[] = [];
+  const opener = new RegExp(TOOL_CALL_OPEN.source, TOOL_CALL_OPEN.flags);
+
+  while (cursor < combined.length) {
+    opener.lastIndex = cursor;
+    const match = opener.exec(combined);
+    if (!match || match.index === undefined) {
+      text += combined.slice(cursor);
+      return { text, pending: "", calls };
+    }
+
+    text += combined.slice(cursor, match.index);
+    const afterOpen = match.index + match[0].length;
+    const rest = combined.slice(afterOpen);
+    const argsTag = rest.match(/^([^\[\]]*)\[ARGS\]/i);
+    if (!argsTag) {
+      const hold = combined.slice(match.index);
+      return { text, calls, ...holdOrSuppress(hold, afterOpen - match.index) };
+    }
+
+    const name = argsTag[1]?.trim() ?? "";
+    let jsonStart = afterOpen + argsTag[0].length;
+    while (jsonStart < combined.length && /\s/.test(combined[jsonStart] ?? "")) jsonStart += 1;
+    if (jsonStart >= combined.length) {
+      const hold = combined.slice(match.index);
+      return { text, calls, ...holdOrSuppress(hold, afterOpen - match.index) };
+    }
+    if (combined[jsonStart] !== "{") {
+      debugProviderDiagnostic("cursor", "text-toolcall-invalid-arguments", {
+        reason: "arguments-did-not-start-with-object",
+        ...(name ? { toolName: normalizeCursorWireName(name) } : {}),
+      });
+      // No delimiter identifies where a non-JSON payload ends. Resume marker
+      // scanning after `[ARGS]`, while suppressing the malformed payload itself.
+      opener.lastIndex = jsonStart;
+      const nextMarker = opener.exec(combined);
+      if (!nextMarker || nextMarker.index === undefined) return { text, pending: "", calls };
+      cursor = nextMarker.index;
+      continue;
+    }
+
+    const jsonEnd = findJsonObjectEnd(combined, jsonStart);
+    if (jsonEnd === undefined) {
+      const hold = combined.slice(match.index);
+      return { text, calls, ...holdOrSuppress(hold, afterOpen - match.index) };
+    }
+
+    const args = combined.slice(jsonStart, jsonEnd);
+    try {
+      JSON.parse(args);
+      if (name.length > 0) {
+        calls.push({ name: normalizeCursorWireName(name), args });
+      }
+    } catch {
+      debugProviderDiagnostic("cursor", "text-toolcall-invalid-arguments", {
+        reason: "arguments-json-parse-failed",
+        ...(name ? { toolName: normalizeCursorWireName(name) } : {}),
+      });
+    }
+    cursor = jsonEnd;
+  }
+
+  return { text, pending: "", calls };
+}

package/src/adapters/cursor/thread-continuity.ts

@@ -158,3 +158,70 @@ export function cursorOverflowRemintCountForTests(): number {
   pruneOverflowRemints(now());
   return overflowRemintByScope.size;
 }
+
+/** Max next-turn conversation-id rotations after incomplete client-tool streams per retained scope. */
+export const CURSOR_INCOMPLETE_TOOL_REMINT_MAX = 3;
+export const CURSOR_INCOMPLETE_TOOL_REMINT_TTL_MS = CURSOR_OVERFLOW_REMINT_TTL_MS;
+export const CURSOR_INCOMPLETE_TOOL_REMINT_MAX_ENTRIES = CURSOR_OVERFLOW_REMINT_MAX_ENTRIES;
+
+type IncompleteToolRemintState = {
+  remintCount: number;
+  updatedAt: number;
+};
+
+const incompleteToolRemintByScope = new Map<string, IncompleteToolRemintState>();
+
+function pruneIncompleteToolRemints(at: number): void {
+  for (const [scopeKey, entry] of incompleteToolRemintByScope) {
+    if (at - entry.updatedAt > CURSOR_INCOMPLETE_TOOL_REMINT_TTL_MS) {
+      incompleteToolRemintByScope.delete(scopeKey);
+    }
+  }
+  while (incompleteToolRemintByScope.size > CURSOR_INCOMPLETE_TOOL_REMINT_MAX_ENTRIES) {
+    const oldest = incompleteToolRemintByScope.keys().next().value;
+    if (oldest === undefined) break;
+    incompleteToolRemintByScope.delete(oldest);
+  }
+}
+
+/** Incomplete-tool and overflow recovery share ownership scope, but keep independent budgets. */
+export function cursorIncompleteToolRemintScopeKey(
+  threadOwner: string | undefined,
+  identityScope?: string,
+): string | null {
+  return cursorOverflowRemintScopeKey(threadOwner, identityScope);
+}
+
+/** Record one incomplete-tool remint; returns false when the independent cap is exhausted. */
+export function recordCursorIncompleteToolRemint(scopeKey: string): boolean {
+  const at = now();
+  pruneIncompleteToolRemints(at);
+  const existing = incompleteToolRemintByScope.get(scopeKey);
+  if (existing && existing.remintCount >= CURSOR_INCOMPLETE_TOOL_REMINT_MAX) {
+    existing.updatedAt = at;
+    incompleteToolRemintByScope.delete(scopeKey);
+    incompleteToolRemintByScope.set(scopeKey, existing);
+    return false;
+  }
+  const entry = existing ?? { remintCount: 0, updatedAt: at };
+  entry.remintCount += 1;
+  entry.updatedAt = at;
+  incompleteToolRemintByScope.delete(scopeKey);
+  incompleteToolRemintByScope.set(scopeKey, entry);
+  pruneIncompleteToolRemints(at);
+  return true;
+}
+
+/** A clean turn replenishes this recovery without changing the overflow retry budget. */
+export function clearCursorIncompleteToolRemint(scopeKey: string): void {
+  incompleteToolRemintByScope.delete(scopeKey);
+}
+
+export function clearCursorIncompleteToolRemintForTests(): void {
+  incompleteToolRemintByScope.clear();
+}
+
+export function cursorIncompleteToolRemintCountForTests(): number {
+  pruneIncompleteToolRemints(now());
+  return incompleteToolRemintByScope.size;
+}

package/src/adapters/cursor/types.ts

@@ -11,6 +11,11 @@ export interface CursorRequestedModelParameter {
 
 export interface CursorRunRequest {
   modelId: string;
+  /**
+   * Normalized Cursor identity scope carried from request parsing so checkpoint
+   * observations stay scope-local. Transport metadata only; never serialized on the wire.
+   */
+  _cursorIdentityScope?: string;
   /** Cursor model-picker parameters encoded through AgentRunRequest.requested_model. */
   requestedModelParameters?: readonly CursorRequestedModelParameter[];
   /** Cursor Router optimization parameter; valid only while modelId is the `default` wire model. */