cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/protocol/turn-provenance.d.ts

@@ -1,11 +1,10 @@
 import type { LanguageModelV3CallOptions } from "@ai-sdk/provider";
 /** Mirrors MAX_TURN_STATE_SESSIONS; evicted sessions re-hydrate from disk. */
 export declare const MAX_PROVENANCE_SESSIONS = 256;
-export type TurnProvenance = {
-    conversationId: string;
-    /** Tool call ids emitted in the latest non-empty step. */
+type EmittedStep = {
+    /** Tool call ids emitted in the step. */
     toolCallIds: string[];
-    /** Whitespace-free text emitted in the latest non-empty step (first 4 KiB). */
+    /** Whitespace-free text emitted in the step (first 4 KiB). */
     text: string;
     /**
      * Whitespace-free reasoning and text of the same step in emission order
@@ -15,6 +14,17 @@ export type TurnProvenance = {
      */
     textWithReasoning: string;
 };
+/** The latest non-empty step, as fields of the record itself. */
+export type TurnProvenance = EmittedStep & {
+    conversationId: string;
+    /**
+     * The latest step has not finished: it is still streaming, or the host
+     * stopped it. The host may keep only what it read of it, or drop it.
+     */
+    unfinished?: boolean;
+    /** The step before an unfinished one, which the host's history may still end on. */
+    previous?: EmittedStep;
+};
 export type ForeignHistoryReason = "foreign-assistant";
 /**
  * Mark the start of one host step (one doStream). The previous step stays
@@ -28,6 +38,10 @@ export declare function recordEmittedPart(sessionKey: string, conversationId: st
     delta?: unknown;
     toolCallId?: unknown;
 }): void;
+/** The host step's stream finished normally; an empty step leaves the previous one recorded. */
+export declare function finishEmittedStep(sessionKey: string, conversationId: string): void;
+/** The finished step goes on in the same host step (a progress-only continuation Run). */
+export declare function resumeEmittedStep(sessionKey: string, conversationId: string): void;
 /**
  * Bind provenance to the conversation a Run was opened on. A reminted
  * conversation starts with an empty record, so it never inherits the previous
@@ -50,3 +64,4 @@ export declare function detectForeignHistory(input: {
     conversationId: string;
     prompt: LanguageModelV3CallOptions["prompt"];
 }): ForeignHistoryReason | undefined;
+export {};

package/dist/protocol/turn-provenance.js

@@ -37,10 +37,18 @@ function entryFor(sessionKey, conversationId) {
 function appendCapped(value, delta) {
     return value.length < MAX_TEXT_CHARS ? (value + delta).slice(0, MAX_TEXT_CHARS) : value;
 }
+function hasContent(step) {
+    return step.toolCallIds.length > 0 || !!step.text || !!step.textWithReasoning;
+}
+function copyStep(step) {
+    return { toolCallIds: [...step.toolCallIds], text: step.text, textWithReasoning: step.textWithReasoning };
+}
 function contentEntry(sessionKey, conversationId) {
     const entry = entryFor(sessionKey, conversationId);
     if (entry.stepPending) {
+        entry.previous = hasContent(entry) ? copyStep(entry) : undefined;
         entry.stepPending = false;
+        entry.unfinished = true;
         entry.toolCallIds = [];
         entry.text = "";
         entry.textWithReasoning = "";
@@ -73,6 +81,21 @@ export function recordEmittedPart(sessionKey, conversationId, part) {
             entry.toolCallIds.push(part.toolCallId);
     }
 }
+/** The host step's stream finished normally; an empty step leaves the previous one recorded. */
+export function finishEmittedStep(sessionKey, conversationId) {
+    const entry = provenanceBySession.get(sessionKey);
+    if (!entry || entry.conversationId !== conversationId || entry.stepPending)
+        return;
+    entry.unfinished = false;
+    entry.previous = undefined;
+}
+/** The finished step goes on in the same host step (a progress-only continuation Run). */
+export function resumeEmittedStep(sessionKey, conversationId) {
+    const entry = provenanceBySession.get(sessionKey);
+    if (!entry || entry.conversationId !== conversationId || entry.stepPending)
+        return;
+    entry.unfinished = true;
+}
 /**
  * Bind provenance to the conversation a Run was opened on. A reminted
  * conversation starts with an empty record, so it never inherits the previous
@@ -87,13 +110,19 @@ export function getTurnProvenance(sessionKey) {
         return undefined;
     return {
         conversationId: entry.conversationId,
-        toolCallIds: [...entry.toolCallIds],
-        text: entry.text,
-        textWithReasoning: entry.textWithReasoning,
+        ...copyStep(entry),
+        ...(entry.unfinished ? { unfinished: true } : {}),
+        ...(entry.unfinished && entry.previous ? { previous: copyStep(entry.previous) } : {}),
     };
 }
 export function restoreTurnProvenance(sessionKey, value) {
-    touch(sessionKey, { ...value, toolCallIds: [...value.toolCallIds], stepPending: false });
+    touch(sessionKey, {
+        conversationId: value.conversationId,
+        ...copyStep(value),
+        ...(value.unfinished ? { unfinished: true } : {}),
+        ...(value.unfinished && value.previous ? { previous: copyStep(value.previous) } : {}),
+        stepPending: false,
+    });
 }
 export function resetTurnProvenanceForTests() {
     provenanceBySession.clear();
@@ -101,20 +130,31 @@ export function resetTurnProvenanceForTests() {
 export function serializeTurnProvenance(value) {
     return JSON.stringify(value);
 }
+function parseStep(value) {
+    return {
+        toolCallIds: Array.isArray(value.toolCallIds)
+            ? value.toolCallIds.filter((id) => typeof id === "string").slice(0, MAX_TOOL_CALL_IDS)
+            : [],
+        text: typeof value.text === "string" ? value.text.slice(0, MAX_TEXT_CHARS) : "",
+        textWithReasoning: typeof value.textWithReasoning === "string"
+            ? value.textWithReasoning.slice(0, MAX_TEXT_CHARS)
+            : "",
+    };
+}
 export function parseTurnProvenance(raw) {
     try {
         const value = JSON.parse(raw);
         if (typeof value.conversationId !== "string" || !value.conversationId)
             return undefined;
+        const unfinished = value.unfinished === true;
+        const previous = unfinished && value.previous && typeof value.previous === "object"
+            ? parseStep(value.previous)
+            : undefined;
         return {
             conversationId: value.conversationId,
-            toolCallIds: Array.isArray(value.toolCallIds)
-                ? value.toolCallIds.filter((id) => typeof id === "string").slice(0, MAX_TOOL_CALL_IDS)
-                : [],
-            text: typeof value.text === "string" ? value.text.slice(0, MAX_TEXT_CHARS) : "",
-            textWithReasoning: typeof value.textWithReasoning === "string"
-                ? value.textWithReasoning.slice(0, MAX_TEXT_CHARS)
-                : "",
+            ...parseStep(value),
+            ...(unfinished ? { unfinished } : {}),
+            ...(previous ? { previous } : {}),
         };
     }
     catch {
@@ -158,17 +198,34 @@ export function detectForeignHistory(input) {
     // A turn carrying only typed reasoning gives no evidence either way.
     if (toolCallIds.length === 0 && !text)
         return undefined;
-    if (toolCallIds.some((id) => entry.toolCallIds.includes(id)))
-        return undefined;
+    const host = { toolCallIds, text: text.slice(0, MAX_TEXT_CHARS), textWithReasoning: textWithReasoning.slice(0, MAX_TEXT_CHARS) };
     // Compare against the latest step only: a foreign "Done." must not match an
-    // older Cursor turn that happened to contain the same words. Same model: the
-    // host keeps our reasoning typed, so its text parts match our text. After a
-    // model switch OpenCode 1.x replays that reasoning as text parts in place,
-    // so the turn matches our reasoning and text in emission order instead.
-    if (entry.text && text.slice(0, MAX_TEXT_CHARS) === entry.text)
-        return undefined;
-    if (entry.textWithReasoning && textWithReasoning.slice(0, MAX_TEXT_CHARS) === entry.textWithReasoning) {
+    // older Cursor turn that happened to contain the same words.
+    if (sameStep(entry, host))
         return undefined;
+    if (entry.unfinished) {
+        // A stopped step: the host drops it when it holds nothing, so its history
+        // still ends on the step before. Otherwise it keeps what it had read,
+        // which can miss the last parts this provider emitted.
+        if (entry.previous && sameStep(entry.previous, host))
+            return undefined;
+        // A tool call this provider did not emit makes the turn someone else's.
+        if (host.toolCallIds.length === 0) {
+            if (host.text && entry.text.startsWith(host.text))
+                return undefined;
+            if (host.textWithReasoning && entry.textWithReasoning.startsWith(host.textWithReasoning))
+                return undefined;
+        }
     }
     return "foreign-assistant";
 }
+function sameStep(step, host) {
+    if (host.toolCallIds.some((id) => step.toolCallIds.includes(id)))
+        return true;
+    // Same model: the host keeps our reasoning typed, so its text parts match our
+    // text. After a model switch OpenCode 1.x replays that reasoning as text
+    // parts in place, so the turn matches our reasoning and text in emission order.
+    if (step.text && host.text === step.text)
+        return true;
+    return !!step.textWithReasoning && host.textWithReasoning === step.textWithReasoning;
+}

package/dist/replay-safety.d.ts

@@ -1,10 +1,24 @@
 import type { CursorProviderError } from "./errors.js";
-export type ReplayBarrierReason = "visible-text" | "visible-reasoning" | "display-tool-lifecycle" | "non-control-exec" | "stateful-interaction" | "unknown-or-malformed-frame";
+export type ReplayBarrierReason = "visible-text" | "visible-reasoning" | "visible-tool-row" | "display-tool-lifecycle" | "non-control-exec" | "stateful-interaction" | "unknown-or-malformed-frame";
+/** Plain Run-owned state retained across host tool-step pump calls. */
+export type ReplaySafetyState = {
+    statefulBarrier?: ReplayBarrierReason;
+    /** Every exec needs its owner's host result; ids can restart on a resumed Run. */
+    execs?: Array<{
+        sessionId: string;
+        id: number;
+    }>;
+    /** History cannot represent opaque interactions, unknown frames or started display work. */
+    historyRebaseUnsafe?: boolean;
+};
 export declare class AttemptReplaySafety {
     private readonly sessionId;
+    private readonly state;
     private barrierReason;
-    constructor(sessionId: string);
+    private stateful;
+    constructor(sessionId: string, state?: ReplaySafetyState);
     markBarrier(reason: ReplayBarrierReason): void;
+    recordExec(id: unknown): void;
     applyTo(failure: CursorProviderError): CursorProviderError;
 }
 export type DecodedReplayFrame = {
@@ -13,11 +27,15 @@ export type DecodedReplayFrame = {
     kv?: Record<string, unknown>;
     execControl?: Record<string, unknown>;
     interactionQuery?: Record<string, unknown>;
-    checkpointBytes?: Uint8Array;
 };
 export type ReplayFrameAnalysis = {
-    semanticProgress: boolean;
     barrier?: ReplayBarrierReason;
 };
+/**
+ * Field numbers and wire types of a frame, nested three levels, without any
+ * payload bytes: `1:2{16:2{1:0}}`. Compare it with `agent.proto` when a frame
+ * is classified unknown.
+ */
+export declare function describeFrameLayout(payload: Uint8Array, depth?: number): string;
 /** Classify one decoded server frame without performing any protocol side effects. */
 export declare function analyzeReplayFrame(payload: Uint8Array, decoded: DecodedReplayFrame): ReplayFrameAnalysis;

package/dist/replay-safety.js

@@ -1,28 +1,71 @@
 import { trace } from "./debug.js";
 import { readAllFieldsStrict } from "./protocol/struct.js";
+/** Host output without execution authority: sending the turn again repeats no side effect. */
+const OUTPUT_ONLY_BARRIERS = new Set([
+    "visible-text", "visible-reasoning", "visible-tool-row",
+]);
 export class AttemptReplaySafety {
     sessionId;
+    state;
     barrierReason;
-    constructor(sessionId) {
+    stateful = false;
+    constructor(sessionId, state = {}) {
         this.sessionId = sessionId;
+        this.state = state;
+        this.stateful = state.statefulBarrier !== undefined;
     }
     markBarrier(reason) {
+        if (!OUTPUT_ONLY_BARRIERS.has(reason)) {
+            this.stateful = true;
+            this.state.statefulBarrier ??= reason;
+            if (reason !== "non-control-exec")
+                this.state.historyRebaseUnsafe = true;
+        }
         if (this.barrierReason)
             return;
         this.barrierReason = reason;
         trace(`replay barrier: reason=${reason} sessionId=${this.sessionId}`);
     }
+    recordExec(id) {
+        const execs = this.state.execs ??= [];
+        if (typeof id !== "number" || !Number.isSafeInteger(id)
+            || execs.some(exec => exec.sessionId === this.sessionId && exec.id === id)) {
+            this.state.historyRebaseUnsafe = true;
+            return;
+        }
+        execs.push({ sessionId: this.sessionId, id });
+    }
     applyTo(failure) {
-        failure.replaySafe = this.barrierReason === undefined && failure.replaySafe;
+        failure.replaySafe = this.barrierReason === undefined && !this.stateful && failure.replaySafe;
         if (this.barrierReason) {
-            trace(`replay suppressed: reason=${this.barrierReason} sessionId=${this.sessionId}`);
+            failure.replayBarrier = this.stateful ? "stateful" : "output-only";
+            trace(`replay suppressed: reason=${this.barrierReason} barrier=${failure.replayBarrier} ` +
+                `sessionId=${this.sessionId}`);
         }
         return failure;
     }
 }
-const INTERACTION_UPDATE_FIELDS = new Set([1, 2, 3, 4, 7, 13, 14, 16, 17]);
+// Field numbers follow Cursor CLI 2026.09.28 `agent.v1`; the extracted
+// agent.proto lags the live server.
+// `InteractionUpdate` oneof members this client recognizes. Besides the
+// declared ones: `thinking_completed` #5 (duration), `token_delta` #8 (count),
+// `tool_call_delta` #15 (argument stream, like `partial_tool_call` #7),
+// `context_injection_state` #23 (status of a client injection, which Cursor
+// CLI only shows for queued steers), `routed_model` #24 (display name) and
+// `tool_requests_listed` #27 (count) carry no output and no state. Other
+// members stay barriers.
+const INTERACTION_UPDATE_FIELDS = new Set([1, 2, 3, 4, 5, 7, 8, 13, 14, 15, 16, 17, 23, 24, 27]);
+/** `InteractionUpdate.message_started_at_ms` #25: a timestamp beside the oneof member. */
+const INTERACTION_UPDATE_STARTED_AT = 25;
 const INTERACTION_QUERY_FIELDS = new Set([2, 3, 4, 7, 8, 9, 10, 11, 12, 13, 14]);
 const TOP_LEVEL_FIELDS = new Set([1, 2, 3, 4, 5, 7]);
+/** `AgentServerMessage.ttft_breakdown` #8: timing metrics beside the oneof member. */
+const SERVER_MESSAGE_TTFT = 8;
+/** At most one occurrence of an optional field, with the expected wire type. */
+function optionalField(fields, fn, wt) {
+    const matches = fields.filter((field) => field.fn === fn);
+    return matches.length <= 1 && matches.every((field) => field.wt === wt);
+}
 function nestedFields(topLevel, field) {
     if (topLevel?.fn !== field || topLevel.wt !== 2 || !topLevel.bytes)
         return [];
@@ -37,8 +80,14 @@ function analyzeExecWire(topLevel) {
         exactMcpState: exactVariant(36),
     };
 }
+// `KvServerMessage` = id #1, oneof get #2 / set #3, `span_context` #4 (tracing);
+// Cursor sends the span on live KV requests.
 function validKvWire(topLevel) {
-    const variants = nestedFields(topLevel, 4).filter((field) => field.fn !== 1);
+    const fields = nestedFields(topLevel, 4);
+    const spans = fields.filter((field) => field.fn === 4);
+    if (spans.length > 1 || spans.some((field) => field.wt !== 2))
+        return false;
+    const variants = fields.filter((field) => field.fn !== 1 && field.fn !== 4);
     const variant = variants.length === 1 ? variants[0] : undefined;
     const args = variant?.wt === 2 && variant.bytes
         ? (readAllFieldsStrict(variant.bytes) ?? [])
@@ -53,14 +102,23 @@ function validKvWire(topLevel) {
 function validInteractionUpdateWire(topLevel, decoded) {
     if (!decoded)
         return true;
-    const fields = nestedFields(topLevel, 1);
+    const all = nestedFields(topLevel, 1);
+    if (!optionalField(all, INTERACTION_UPDATE_STARTED_AT, 0))
+        return false;
+    const fields = all.filter((field) => field.fn !== INTERACTION_UPDATE_STARTED_AT);
     const update = fields.length === 1 ? fields[0] : undefined;
     if (!update || update.wt !== 2 || !INTERACTION_UPDATE_FIELDS.has(update.fn))
         return false;
     if (![1, 4].includes(update.fn))
         return true;
     const delta = update.bytes ? (readAllFieldsStrict(update.bytes) ?? []) : [];
-    return delta.length === 1 && delta[0].fn === 1 && delta[0].wt === 2;
+    const text = delta.filter((field) => field.fn === 1);
+    // #2 is `TextDeltaUpdate.is_server_notice` (bool) or
+    // `ThinkingDeltaUpdate.thinking_style` (enum); both varints.
+    const flag = delta.filter((field) => field.fn === 2);
+    return text.length === 1 && text[0].wt === 2
+        && optionalField(delta, 2, 0)
+        && delta.length === text.length + flag.length;
 }
 function validInteractionQueryWire(topLevel, decoded) {
     if (!decoded)
@@ -81,25 +139,29 @@ function decodedMatchesWire(topLevel, decoded) {
         || (topLevel?.fn === 5 && !decoded.execControl)
         || (topLevel?.fn === 7 && !decoded.interactionQuery));
 }
-function hasSemanticProgress(decoded) {
-    const update = decoded.interactionUpdate;
-    const text = update?.text_delta?.text;
-    const thinking = update?.thinking_delta?.text;
-    return (typeof text === "string" && text.length > 0)
-        || (typeof thinking === "string" && thinking.length > 0)
-        || !!update?.turn_ended
-        || !!update?.tool_call_started
-        || !!update?.tool_call_completed
-        || !!decoded.exec
-        || !!decoded.kv
-        || !!decoded.execControl
-        || !!decoded.interactionQuery
-        || !!decoded.checkpointBytes?.length;
+/**
+ * Field numbers and wire types of a frame, nested three levels, without any
+ * payload bytes: `1:2{16:2{1:0}}`. Compare it with `agent.proto` when a frame
+ * is classified unknown.
+ */
+export function describeFrameLayout(payload, depth = 3) {
+    const fields = readAllFieldsStrict(payload);
+    if (!fields)
+        return "?";
+    return fields.map((field) => {
+        const nested = depth > 1 && field.wt === 2 && field.bytes && field.bytes.length > 0
+            ? readAllFieldsStrict(field.bytes)
+            : undefined;
+        const inner = nested && nested.length > 0 ? `{${describeFrameLayout(field.bytes, depth - 1)}}` : "";
+        return `${field.fn}:${field.wt}${inner}`;
+    }).join(",");
 }
 /** Classify one decoded server frame without performing any protocol side effects. */
 export function analyzeReplayFrame(payload, decoded) {
-    const topLevelFields = readAllFieldsStrict(payload) ?? [];
-    const topLevel = topLevelFields.length === 1 ? topLevelFields[0] : undefined;
+    const allTopLevel = readAllFieldsStrict(payload) ?? [];
+    const ttftValid = optionalField(allTopLevel, SERVER_MESSAGE_TTFT, 2);
+    const topLevelFields = allTopLevel.filter((field) => field.fn !== SERVER_MESSAGE_TTFT);
+    const topLevel = ttftValid && topLevelFields.length === 1 ? topLevelFields[0] : undefined;
     const exec = analyzeExecWire(topLevel);
     const validKv = validKvWire(topLevel);
     const malformed = !topLevel
@@ -119,8 +181,5 @@ export function analyzeReplayFrame(payload, decoded) {
     else if (topLevel.fn === 2 && !exec.exactRequestContext && !exec.exactMcpState) {
         barrier = "non-control-exec";
     }
-    return {
-        semanticProgress: hasSemanticProgress(decoded),
-        barrier,
-    };
+    return { barrier };
 }

package/dist/retry-budget.d.ts

@@ -0,0 +1,21 @@
+import { type CursorProviderError } from "./errors.js";
+/** Plain data shared by the plugin and SDK copies, for one logical user turn. */
+export type RetryBudget = {
+    server: number;
+    transport: number;
+    retries: number;
+    stallStartedAt?: number;
+    /** A plain-text host continuation is admitted only after we requested a host retry. */
+    hostRetryPending?: boolean;
+    hostRetryKey?: string;
+};
+export declare function newRetryBudget(): RetryBudget;
+/** A host retry or tool continuation must not mint a fresh retry allowance. */
+export declare function turnRetryBudget(sessionKey: string | undefined, turnKey: string, continuationKey?: string): RetryBudget;
+export declare function forgetRetryBudget(sessionKey: string | undefined, budget?: RetryBudget): void;
+export declare function endlessRetriesEnabled(): boolean;
+/** CLI's incomplete-stream error is explicitly transport; an idle deadline is server. */
+export declare function retryCategory(failure: CursorProviderError): "server" | "transport";
+/** Reserve one retry before either reopening locally or handing it to OpenCode. */
+export declare function reserveRetry(budget: RetryBudget, failure: CursorProviderError, maxAttempts?: number, now?: number): void;
+export declare function resetRetryBudgetsForTests(): void;

package/dist/retry-budget.js

@@ -0,0 +1,94 @@
+import { CursorRetryExhaustedError } from "./errors.js";
+import { processShared } from "./process-shared.js";
+const budgets = () => processShared("run-retry-budgets.v1", () => new Map());
+const MAX_SESSIONS = 1_024;
+const MAX_TURNS_PER_SESSION = 16;
+export function newRetryBudget() {
+    return { server: 0, transport: 0, retries: 0 };
+}
+/** A host retry or tool continuation must not mint a fresh retry allowance. */
+export function turnRetryBudget(sessionKey, turnKey, continuationKey) {
+    if (!sessionKey)
+        return newRetryBudget();
+    const sessions = budgets();
+    let turns = sessions.get(sessionKey);
+    if (!turns) {
+        turns = new Map();
+    }
+    sessions.delete(sessionKey);
+    sessions.set(sessionKey, turns);
+    const lookup = (key) => {
+        const direct = turns.get(key);
+        return direct ? [key, direct] : [...turns].find(([, budget]) => budget.hostRetryKey === key);
+    };
+    let entry = lookup(turnKey);
+    let budget = entry?.[1];
+    const currentKey = turnKey;
+    if (entry)
+        turnKey = entry[0];
+    if (!budget && continuationKey !== undefined) {
+        entry = lookup(continuationKey);
+        const previous = entry?.[1];
+        if (previous?.hostRetryPending) {
+            budget = previous;
+            budget.hostRetryKey = currentKey;
+            turnKey = entry[0];
+        }
+    }
+    if (!budget) {
+        budget = newRetryBudget();
+    }
+    budget.hostRetryPending = false;
+    turns.delete(turnKey);
+    turns.set(turnKey, budget);
+    // Abandoned host retries and ephemeral helpers never reach turn_ended.
+    // Bound their lookup records; live recovery loops retain their budget object.
+    while (turns.size > MAX_TURNS_PER_SESSION)
+        turns.delete(turns.keys().next().value);
+    while (sessions.size > MAX_SESSIONS)
+        sessions.delete(sessions.keys().next().value);
+    return budget;
+}
+export function forgetRetryBudget(sessionKey, budget) {
+    if (!sessionKey)
+        return;
+    const sessions = budgets();
+    const turns = sessions.get(sessionKey);
+    if (!turns)
+        return;
+    if (!budget)
+        sessions.delete(sessionKey);
+    else {
+        for (const [key, value] of turns)
+            if (value === budget)
+                turns.delete(key);
+        if (turns.size === 0)
+            sessions.delete(sessionKey);
+    }
+}
+export function endlessRetriesEnabled() {
+    return process.env.CURSOR_ENDLESS_RETRIES === "1" || process.env.CURSOR_ENDLESS_RETRIES === "true";
+}
+/** CLI's incomplete-stream error is explicitly transport; an idle deadline is server. */
+export function retryCategory(failure) {
+    return failure.origin === "transport"
+        && failure.code !== "CURSOR_READ_IDLE_TIMEOUT" ? "transport" : "server";
+}
+/** Reserve one retry before either reopening locally or handing it to OpenCode. */
+export function reserveRetry(budget, failure, maxAttempts, now = Date.now()) {
+    const category = retryCategory(failure);
+    const stalled = failure.code === "CURSOR_SEMANTIC_IDLE_TIMEOUT";
+    if (!stalled)
+        budget.stallStartedAt = undefined;
+    const stallExpired = stalled && budget.stallStartedAt !== undefined && now - budget.stallStartedAt >= 180_000;
+    if (stallExpired || (!endlessRetriesEnabled() && (budget[category] >= (category === "server" ? 3 : 10)
+        || (maxAttempts !== undefined && budget.retries >= maxAttempts - 1))))
+        throw new CursorRetryExhaustedError(budget.retries + 1, failure);
+    if (stalled)
+        budget.stallStartedAt ??= now;
+    budget[category]++;
+    budget.retries++;
+}
+export function resetRetryBudgetsForTests() {
+    budgets().clear();
+}

package/dist/runtime-files.d.ts

@@ -0,0 +1,23 @@
+export declare const MAX_RUNTIME_WRITE_BYTES: number;
+export declare const MAX_RUNTIME_READ_BYTES: number;
+export declare const RUNTIME_FILE_TTL_MS: number;
+export declare const MAX_RUNTIME_SPILL_BYTES: number;
+export declare const MAX_RUNTIME_SPILL_FILES = 128;
+export type RuntimeLayout = {
+    root: string;
+    agentTools: string;
+    terminals: string;
+};
+/** The one provider-owned layout, pinned by the RequestContext's project root. */
+export declare function runtimeLayout(root: string, create?: boolean): RuntimeLayout;
+export declare function runtimeRootFromContext(context: Record<string, unknown> | undefined): string | undefined;
+export declare function maintainRuntimeFiles(layout: RuntimeLayout, now?: number): void;
+/** Native internal filesystem requests never enter the host's workspace tools. */
+export declare function runtimeExecMessages(message: Record<string, unknown>, context: Record<string, unknown> | undefined, allowTools: boolean): Promise<Uint8Array[] | undefined>;
+/**
+ * Age-based cleanup. A live supervisor rewrites its record every second, so a
+ * terminal record or job untouched for the TTL is finished, was never
+ * started, or was orphaned by a crash or reboot. Only deletions are budgeted:
+ * young entries early in directory order cannot stall later cleanup.
+ */
+export declare function sweepRuntimeFiles(layout: RuntimeLayout, now?: number): void;