@cursor/bdk 0.2.11 → 0.2.12

package/dist/internal/store-api-protocol.d.ts

@@ -110,4 +110,55 @@ export type MemoryReadResponse = {
  * (`{ code, error }`) with a matching HTTP status.
  */
 export declare const memoryReadResponseSchema: z.ZodType<MemoryReadResponse>;
+/**
+ * Live session relay: the engine posts batches of session events, and the
+ * service keeps them only while a viewer is watching that session. The
+ * stored transcript stays the durable copy.
+ */
+export declare const STORE_API_SESSION_LIVE_CALL = "session.live";
+/**
+ * Cap on one serialized live event. A larger event crosses as a stub with
+ * `liveTruncated: true`; viewers reread the stored transcript after the turn.
+ */
+export declare const SESSION_LIVE_MAX_EVENT_BYTES: number;
+/** Cap on one batch's serialized `events`, enforced on both sides. */
+export declare const SESSION_LIVE_MAX_BATCH_BYTES: number;
+export declare const SESSION_LIVE_MAX_BATCH_EVENTS = 500;
+/**
+ * One session event as it crosses the live wire. `index` orders and
+ * deduplicates events; everything else passes through.
+ */
+export type SessionLiveEventWire = {
+    index: number;
+    type: string;
+} & Record<string, unknown>;
+export declare const sessionLiveEventWireSchema: z.ZodType<SessionLiveEventWire>;
+/** `session.live` validated payload. An empty batch is a subscription probe. */
+export type SessionLiveWirePayload = {
+    sessionId: string;
+    events: SessionLiveEventWire[];
+};
+export declare const sessionLivePayloadSchema: z.ZodType<SessionLiveWirePayload>;
+/** The versioned request body for the `session.live` call. */
+export type SessionLiveEnvelope = {
+    v: typeof STORE_API_PROTOCOL_VERSION;
+    call: typeof STORE_API_SESSION_LIVE_CALL;
+    payload: SessionLiveWirePayload;
+};
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export declare const sessionLiveEnvelopeSchema: z.ZodType<SessionLiveEnvelope>;
+/**
+ * `session.live` success body. `subscribed` says whether a viewer is
+ * watching (the service kept nothing when false), `recheckAfterMs` is the
+ * earliest next probe while unsubscribed, and `replayFromIndex` asks the
+ * engine to resend its local log from that index.
+ */
+export type SessionLiveResponse = {
+    v: typeof STORE_API_PROTOCOL_VERSION;
+    ok: true;
+    subscribed: boolean;
+    recheckAfterMs: number;
+    replayFromIndex: number | null;
+};
+export declare const sessionLiveResponseSchema: z.ZodType<SessionLiveResponse>;
 //# sourceMappingURL=store-api-protocol.d.ts.map

package/dist/internal/store-api-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store-api-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/store-api-protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store-api-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/store-api-protocol.ts"],"names":[],"mappings":"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"}

package/dist/internal/store-api-protocol.js

@@ -53,7 +53,7 @@ export const memoryAppendPayloadSchema = z.object({
         .string()
         .min(1)
         .max(256)
-        .refine(name => !name.includes("/") && !name.includes("\\") && name !== "." && name !== "..", {
+        .refine((name) => !name.includes("/") && !name.includes("\\") && name !== "." && name !== "..", {
         message: "agent must be a single store key segment",
     }),
     record: turnMemoryRecordWireSchema,
@@ -82,7 +82,7 @@ export const memoryReadPayloadSchema = z.object({
         .string()
         .min(1)
         .max(256)
-        .refine(name => !name.includes("/") && !name.includes("\\") && name !== "." && name !== "..", {
+        .refine((name) => !name.includes("/") && !name.includes("\\") && name !== "." && name !== "..", {
         message: "agent must be a single store key segment",
     }),
 });
@@ -106,3 +106,40 @@ export const memoryReadResponseSchema = z.object({
     })
         .nullable(),
 });
+/**
+ * Live session relay: the engine posts batches of session events, and the
+ * service keeps them only while a viewer is watching that session. The
+ * stored transcript stays the durable copy.
+ */
+export const STORE_API_SESSION_LIVE_CALL = "session.live";
+/**
+ * Cap on one serialized live event. A larger event crosses as a stub with
+ * `liveTruncated: true`; viewers reread the stored transcript after the turn.
+ */
+export const SESSION_LIVE_MAX_EVENT_BYTES = 16 * 1024;
+/** Cap on one batch's serialized `events`, enforced on both sides. */
+export const SESSION_LIVE_MAX_BATCH_BYTES = 256 * 1024;
+export const SESSION_LIVE_MAX_BATCH_EVENTS = 500;
+export const sessionLiveEventWireSchema = z
+    .object({
+    index: z.number().int().min(0),
+    type: z.string().min(1),
+})
+    .passthrough();
+export const sessionLivePayloadSchema = z.object({
+    sessionId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),
+    events: z.array(sessionLiveEventWireSchema).max(SESSION_LIVE_MAX_BATCH_EVENTS),
+});
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export const sessionLiveEnvelopeSchema = z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    call: z.literal(STORE_API_SESSION_LIVE_CALL),
+    payload: sessionLivePayloadSchema,
+});
+export const sessionLiveResponseSchema = z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    ok: z.literal(true),
+    subscribed: z.boolean(),
+    recheckAfterMs: z.number().int().min(0),
+    replayFromIndex: z.number().int().min(0).nullable(),
+});

package/dist/internal/store-mirror.js

@@ -13,11 +13,11 @@ import { FileConflictError } from "../files.js";
  */
 export async function mirrorToStore(args) {
     await Promise.all([...args.desired].map(([key, body]) => putLastWriterWins(args.sink, key, body)));
-    const listed = await Promise.all([args.prefix, ...(args.legacyPrefixes ?? [])].map(prefix => args.sink.list(prefix)));
+    const listed = await Promise.all([args.prefix, ...(args.legacyPrefixes ?? [])].map((prefix) => args.sink.list(prefix)));
     await Promise.all(listed
         .flat()
-        .filter(entry => !args.desired.has(entry.key))
-        .map(entry => args.sink.delete(entry.key)));
+        .filter((entry) => !args.desired.has(entry.key))
+        .map((entry) => args.sink.delete(entry.key)));
 }
 /**
  * Same refusals as local materialization's `resolveInside`: a rel that
@@ -31,7 +31,7 @@ export function storeRelPath(relPath, what) {
         relPath.includes("\\") ||
         posix.isAbsolute(relPath) ||
         relPath.endsWith("/") ||
-        relPath.split("/").some(seg => seg === ".." || seg === ".") ||
+        relPath.split("/").some((seg) => seg === ".." || seg === ".") ||
         posix.normalize(relPath) !== relPath) {
         throw new Error(`Refusing ${what} path "${relPath}" (must be a normalized relative path)`);
     }

package/dist/internal/stream-progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-progress.d.ts","sourceRoot":"","sources":["../../src/internal/stream-progress.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,cAAc,CA2NjB"}
+{"version":3,"file":"stream-progress.d.ts","sourceRoot":"","sources":["../../src/internal/stream-progress.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,cAAc,CAmOjB"}

package/dist/internal/stream-progress.js

@@ -124,6 +124,10 @@ export function createStreamProgress(options) {
                     write(`    ${mark} ${c.bold(event.data.connection)} ${c.dim(event.data.decision === "approve" ? "connected" : "denied")}\n`);
                     break;
                 }
+                case "action.tool_retry": {
+                    write(`    ${c.yellow("↻")} ${c.bold(event.data.toolName)} ${c.dim(`again as try ${event.data.attempt} (${event.data.reason})`)}\n`);
+                    break;
+                }
                 case "action.result": {
                     if (event.data.toolName === "task" && event.data.parentCallId === undefined) {
                         break;

package/dist/internal/terminal-style.js

@@ -69,7 +69,7 @@ export function terminalHyperlink(url, label, enabled = colorEnabledFor()) {
 export function formatTerminalBox(lines, options) {
     const color = options?.color ?? IDENTITY;
     const padding = options?.padding ?? 1;
-    const contentWidth = Math.max(options?.minWidth ?? 0, ...lines.map(line => visibleWidth(line)), 1);
+    const contentWidth = Math.max(options?.minWidth ?? 0, ...lines.map((line) => visibleWidth(line)), 1);
     const inner = contentWidth + padding * 2;
     const padLine = (line) => {
         const extra = contentWidth - visibleWidth(line);
@@ -78,7 +78,7 @@ export function formatTerminalBox(lines, options) {
     const paint = (line) => color(line);
     const box = [
         paint(`╭${"─".repeat(inner)}╮`),
-        ...lines.map(line => paint(padLine(line))),
+        ...lines.map((line) => paint(padLine(line))),
         paint(`╰${"─".repeat(inner)}╯`),
     ].join("\n");
     return box;

package/dist/internal/tool-call-retry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Transient retry for a read-effect tool call that already executed.
+ *
+ * Writes, unclassified tools, dry-run stubs, approval denials, and
+ * validation failures never reach this helper. Auth, elicitation, and a
+ * timeout that already ran long enough to repeat are not transient.
+ *
+ * Backoff is full jitter (base 500ms, cap 4s) and at most 10s asleep per
+ * call. An attempt that already ran longer than 15s is not retried, so
+ * one slow call plus the backoff budget stays under 30s. Sleep yields the
+ * event loop, so a timer can still fire during the wait.
+ */
+import { type Meter } from "@opentelemetry/api";
+import type { ToolEffect } from "../types.js";
+/** Total tries, including the first, for a read-effect call. */
+export declare const TOOL_RETRY_DEFAULT_MAX_ATTEMPTS = 3;
+export declare const TOOL_RETRY_BACKOFF_BASE_MS = 500;
+export declare const TOOL_RETRY_BACKOFF_CAP_MS = 4000;
+/** Cumulative sleep per call. */
+export declare const TOOL_RETRY_BACKOFF_BUDGET_MS = 10000;
+/**
+ * An attempt slower than this is not retried. Paired with the backoff
+ * budget, the extra wait stays under 30s.
+ */
+export declare const TOOL_RETRY_MAX_ATTEMPT_MS = 15000;
+/** Quiet-stream limit the extra wait must stay under. */
+export declare const TOOL_RETRY_STALL_FAIL_MS = 30000;
+export type ToolRetryReason = "transport" | "http_429" | "http_502" | "http_503" | "http_504" | "mcp_transient";
+export type ToolRetryOutcome = "recovered" | "exhausted" | "not_eligible";
+export interface ToolRetryNotice {
+    /** The try that is about to run (2 = first retry). */
+    readonly attempt: number;
+    readonly reason: ToolRetryReason;
+    readonly backoffMs: number;
+    readonly connection?: string;
+}
+/**
+ * Vendor-reported MCP `isError` result. Distinct from a thrown transport
+ * failure so the classifier can require an explicit transient phrase.
+ */
+export declare class McpToolError extends Error {
+    readonly connection: string;
+    readonly toolName: string;
+    readonly vendorMessage: string;
+    constructor(args: {
+        connection: string;
+        toolName: string;
+        vendorMessage: string;
+    });
+}
+export type ToolFailureVerdict = {
+    readonly transient: false;
+} | {
+    readonly transient: true;
+    readonly reason: ToolRetryReason;
+    readonly retryAfterMs?: number;
+};
+type SleepFn = (ms: number, signal: AbortSignal | undefined) => Promise<void>;
+/** @internal Test seam. `undefined` restores the real timer. */
+export declare function setToolRetrySleepForTests(sleep: SleepFn | undefined): void;
+/** @internal Test seam. `undefined` restores `Math.random`. */
+export declare function setToolRetryRandomForTests(random: (() => number) | undefined): void;
+/** @internal Test seam. `undefined` restores the global meter. */
+export declare function setToolRetryMeterForTests(meter: Meter | undefined): void;
+export declare function classifyToolFailure(error: unknown): ToolFailureVerdict;
+/**
+ * Full-jitter delay for the backoff after `failedAttempt` (1 = first try
+ * failed). `Retry-After` replaces the jittered delay and is still capped.
+ * Returns `undefined` when the cumulative budget is already spent.
+ */
+export declare function toolRetryBackoffMs(args: {
+    failedAttempt: number;
+    random: number;
+    retryAfterMs?: number;
+    spentMs: number;
+}): number | undefined;
+export declare function retryReadOnlyToolCall<T>(args: {
+    toolName: string;
+    connection?: string;
+    effect: ToolEffect | undefined;
+    signal?: AbortSignal;
+    now?: () => number;
+    onRetry?: (notice: ToolRetryNotice) => void;
+    execute: () => T | Promise<T>;
+}): Promise<T>;
+export {};
+//# sourceMappingURL=tool-call-retry.d.ts.map

package/dist/internal/tool-call-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-retry.d.ts","sourceRoot":"","sources":["../../src/internal/tool-call-retry.ts"],"names":[],"mappings":"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"}

package/dist/internal/tool-call-retry.js

@@ -0,0 +1,387 @@
+/**
+ * Transient retry for a read-effect tool call that already executed.
+ *
+ * Writes, unclassified tools, dry-run stubs, approval denials, and
+ * validation failures never reach this helper. Auth, elicitation, and a
+ * timeout that already ran long enough to repeat are not transient.
+ *
+ * Backoff is full jitter (base 500ms, cap 4s) and at most 10s asleep per
+ * call. An attempt that already ran longer than 15s is not retried, so
+ * one slow call plus the backoff budget stays under 30s. Sleep yields the
+ * event loop, so a timer can still fire during the wait.
+ */
+import { metrics } from "@opentelemetry/api";
+/** Total tries, including the first, for a read-effect call. */
+export const TOOL_RETRY_DEFAULT_MAX_ATTEMPTS = 3;
+export const TOOL_RETRY_BACKOFF_BASE_MS = 500;
+export const TOOL_RETRY_BACKOFF_CAP_MS = 4_000;
+/** Cumulative sleep per call. */
+export const TOOL_RETRY_BACKOFF_BUDGET_MS = 10_000;
+/**
+ * An attempt slower than this is not retried. Paired with the backoff
+ * budget, the extra wait stays under 30s.
+ */
+export const TOOL_RETRY_MAX_ATTEMPT_MS = 15_000;
+/** Quiet-stream limit the extra wait must stay under. */
+export const TOOL_RETRY_STALL_FAIL_MS = 30_000;
+const METRIC_NAME = "agent_sdk.tool.retry";
+const TRANSIENT_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "EPIPE",
+    "ETIMEDOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CLOSED",
+]);
+const TRANSIENT_HTTP_STATUS = new Set([429, 502, 503, 504]);
+const MAX_CAUSE_DEPTH = 8;
+const ENDPOINT_DEADLINE = /tool call timed out after \d+\s*ms/i;
+const TIMEOUT_WORD = /timed?\s*out|\btimeout\b/i;
+const OVERSIZE = /too large|\boversize\b|payload exceeds|result exceeds/i;
+const AUTH_TEXT = /needsauth|needs authorization|\belicitation\b|\bunauthorized\b/i;
+const TRANSPORT_TEXT = /econnreset|econnrefused|socket hang up|fetch failed|eai_again|und_err_connect|und_err_socket|connection closed/i;
+const HTTP_STATUS_TEXT = /\b(?:HTTP\s*)?(429|502|503|504)\b/i;
+const MCP_TRANSIENT_TEXT = /rate limit|temporarily unavailable|(?<!do not )try again/i;
+const RETRY_AFTER_TEXT = /retry-after[^\d]{0,16}(\d+(?:\.\d+)?)/i;
+/**
+ * Vendor-reported MCP `isError` result. Distinct from a thrown transport
+ * failure so the classifier can require an explicit transient phrase.
+ */
+export class McpToolError extends Error {
+    constructor(args) {
+        super(args.vendorMessage === ""
+            ? `${args.connection} tool ${args.toolName} failed`
+            : args.vendorMessage);
+        this.name = "McpToolError";
+        this.connection = args.connection;
+        this.toolName = args.toolName;
+        this.vendorMessage = args.vendorMessage;
+    }
+}
+let sleepImpl = defaultSleep;
+let randomImpl = Math.random;
+let meterOverride;
+let counterCache;
+/** @internal Test seam. `undefined` restores the real timer. */
+export function setToolRetrySleepForTests(sleep) {
+    sleepImpl = sleep ?? defaultSleep;
+}
+/** @internal Test seam. `undefined` restores `Math.random`. */
+export function setToolRetryRandomForTests(random) {
+    randomImpl = random ?? Math.random;
+}
+/** @internal Test seam. `undefined` restores the global meter. */
+export function setToolRetryMeterForTests(meter) {
+    meterOverride = meter;
+    counterCache = undefined;
+}
+export function classifyToolFailure(error) {
+    return classifyAtDepth(error, 0);
+}
+/**
+ * Full-jitter delay for the backoff after `failedAttempt` (1 = first try
+ * failed). `Retry-After` replaces the jittered delay and is still capped.
+ * Returns `undefined` when the cumulative budget is already spent.
+ */
+export function toolRetryBackoffMs(args) {
+    const remaining = TOOL_RETRY_BACKOFF_BUDGET_MS - args.spentMs;
+    if (remaining <= 0) {
+        return undefined;
+    }
+    const unit = Math.min(Math.max(args.random, 0), 1);
+    const exp = TOOL_RETRY_BACKOFF_BASE_MS * 2 ** Math.max(0, args.failedAttempt - 1);
+    const jittered = unit * Math.min(TOOL_RETRY_BACKOFF_CAP_MS, exp);
+    const chosen = args.retryAfterMs !== undefined && Number.isFinite(args.retryAfterMs) && args.retryAfterMs >= 0
+        ? args.retryAfterMs
+        : jittered;
+    return Math.min(chosen, TOOL_RETRY_BACKOFF_CAP_MS, remaining);
+}
+export async function retryReadOnlyToolCall(args) {
+    const maxAttempts = TOOL_RETRY_DEFAULT_MAX_ATTEMPTS;
+    const eligible = args.effect === "read";
+    if (!eligible) {
+        try {
+            return await args.execute();
+        }
+        catch (error) {
+            if (classifyToolFailure(error).transient) {
+                recordOutcome("not_eligible");
+            }
+            throw error;
+        }
+    }
+    const now = args.now ?? Date.now;
+    let spentMs = 0;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        throwIfAborted(args.signal);
+        const started = now();
+        try {
+            const result = await args.execute();
+            if (attempt > 1) {
+                recordOutcome("recovered");
+            }
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            if (args.signal?.aborted === true) {
+                throw abortError(args.signal);
+            }
+            const elapsed = now() - started;
+            const verdict = classifyToolFailure(error);
+            const slow = elapsed > TOOL_RETRY_MAX_ATTEMPT_MS;
+            const canRetry = verdict.transient && !slow && attempt < maxAttempts;
+            if (!canRetry) {
+                if (verdict.transient && (slow || attempt >= maxAttempts)) {
+                    recordOutcome(attempt > 1 ? "exhausted" : "not_eligible");
+                }
+                else if (attempt > 1) {
+                    recordOutcome("exhausted");
+                }
+                if (attempt > 1) {
+                    throw exhaustedError(attempt, error);
+                }
+                throw error;
+            }
+            const delay = toolRetryBackoffMs({
+                failedAttempt: attempt,
+                random: randomImpl(),
+                retryAfterMs: verdict.retryAfterMs,
+                spentMs,
+            });
+            if (delay === undefined) {
+                recordOutcome("exhausted");
+                throw exhaustedError(attempt, error);
+            }
+            const notice = {
+                attempt: attempt + 1,
+                reason: verdict.reason,
+                backoffMs: delay,
+                ...(args.connection === undefined ? {} : { connection: args.connection }),
+            };
+            args.onRetry?.(notice);
+            await sleepImpl(delay, args.signal);
+            spentMs += delay;
+            throwIfAborted(args.signal);
+        }
+    }
+    recordOutcome("exhausted");
+    throw exhaustedError(maxAttempts, lastError);
+}
+function recordOutcome(outcome) {
+    const counter = retryCounter();
+    counter?.add(1, { outcome });
+}
+function retryCounter() {
+    if (counterCache !== undefined) {
+        return counterCache;
+    }
+    const meter = meterOverride ?? metrics.getMeter("@cursor/bdk");
+    counterCache = meter.createCounter(METRIC_NAME, {
+        description: "Read-only tool retries by outcome",
+    });
+    return counterCache;
+}
+function exhaustedError(attempts, error) {
+    const detail = error instanceof Error && error.message !== "" ? error.message : "unknown error";
+    const wrapped = new Error(`failed after ${attempts} attempts: ${detail}`);
+    wrapped.cause = error;
+    return wrapped;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw abortError(signal);
+    }
+}
+function abortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error) {
+        return reason;
+    }
+    const error = new Error("The turn was aborted.");
+    error.name = "AbortError";
+    return error;
+}
+function defaultSleep(ms, signal) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        if (signal?.aborted === true) {
+            clearTimeout(timer);
+            reject(abortError(signal));
+            return;
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function classifyAtDepth(error, depth) {
+    if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
+        return { transient: false };
+    }
+    if (isVeto(error)) {
+        return { transient: false };
+    }
+    const status = httpStatus(error);
+    if (status !== undefined && status >= 400 && status <= 499 && status !== 429) {
+        return { transient: false };
+    }
+    const retryAfterMs = readRetryAfterMs(error);
+    if (status !== undefined && TRANSIENT_HTTP_STATUS.has(status)) {
+        return { transient: true, reason: httpReason(status), retryAfterMs };
+    }
+    const code = errorCode(error);
+    if (code !== undefined && TRANSIENT_CODES.has(code)) {
+        return { transient: true, reason: "transport", retryAfterMs };
+    }
+    if (code !== undefined && code.startsWith("UND_ERR_") && /CONNECT|SOCKET/.test(code)) {
+        return { transient: true, reason: "transport", retryAfterMs };
+    }
+    // A vendor isError string is not a transport failure. Only the MCP
+    // allowlist retries it.
+    if (error instanceof McpToolError) {
+        const vendor = classifyMcpVendorMessage(error.vendorMessage, retryAfterMs);
+        if (vendor !== undefined) {
+            return vendor;
+        }
+        return classifyAtDepth(error.cause, depth + 1);
+    }
+    if (TRANSPORT_TEXT.test(error.message)) {
+        return { transient: true, reason: "transport", retryAfterMs };
+    }
+    const fromText = error.message.match(HTTP_STATUS_TEXT);
+    if (fromText !== null) {
+        const parsed = Number(fromText[1]);
+        if (TRANSIENT_HTTP_STATUS.has(parsed)) {
+            return { transient: true, reason: httpReason(parsed), retryAfterMs };
+        }
+    }
+    if (error instanceof AggregateError) {
+        for (const inner of error.errors) {
+            const verdict = classifyAtDepth(inner, depth + 1);
+            if (verdict.transient) {
+                return verdict;
+            }
+        }
+    }
+    return classifyAtDepth(error.cause, depth + 1);
+}
+function classifyMcpVendorMessage(vendorMessage, retryAfterMs) {
+    if (MCP_TRANSIENT_TEXT.test(vendorMessage)) {
+        return { transient: true, reason: "mcp_transient", retryAfterMs };
+    }
+    const fromText = vendorMessage.match(HTTP_STATUS_TEXT);
+    if (fromText !== null) {
+        const parsed = Number(fromText[1]);
+        if (TRANSIENT_HTTP_STATUS.has(parsed)) {
+            return { transient: true, reason: httpReason(parsed), retryAfterMs };
+        }
+    }
+    return undefined;
+}
+function isVeto(error) {
+    if (error.name === "McpNeedsAuthError" || error.name === "UnauthorizedError") {
+        return true;
+    }
+    const text = `${error.name}\n${error.message}`;
+    if (AUTH_TEXT.test(text) || OVERSIZE.test(text) || ENDPOINT_DEADLINE.test(text)) {
+        return true;
+    }
+    const status = httpStatus(error);
+    if (status === 401 || status === 403 || status === 413) {
+        return true;
+    }
+    return timeoutLongerThanAttemptCap(text);
+}
+function timeoutLongerThanAttemptCap(text) {
+    if (!TIMEOUT_WORD.test(text)) {
+        return false;
+    }
+    for (const match of text.matchAll(/(\d+)\s*ms\b/gi)) {
+        if (Number(match[1]) > TOOL_RETRY_MAX_ATTEMPT_MS) {
+            return true;
+        }
+    }
+    for (const match of text.matchAll(/(\d+(?:\.\d+)?)\s*(?:seconds|\bsec\b|\bs\b)/gi)) {
+        if (Number(match[1]) * 1000 > TOOL_RETRY_MAX_ATTEMPT_MS) {
+            return true;
+        }
+    }
+    return false;
+}
+function httpReason(status) {
+    switch (status) {
+        case 429:
+            return "http_429";
+        case 502:
+            return "http_502";
+        case 504:
+            return "http_504";
+        default:
+            return "http_503";
+    }
+}
+function httpStatus(error) {
+    const record = error;
+    for (const value of [record.status, record.statusCode]) {
+        if (typeof value === "number" && Number.isInteger(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function errorCode(error) {
+    const code = error.code;
+    return typeof code === "string" && code.length > 0 ? code : undefined;
+}
+function readRetryAfterMs(error) {
+    const record = error;
+    const header = record.headers?.get?.("retry-after") ?? record.headers?.get?.("Retry-After");
+    const fromHeader = parseRetryAfter(header);
+    if (fromHeader !== undefined) {
+        return fromHeader;
+    }
+    if (typeof record.retryAfter === "number" && Number.isFinite(record.retryAfter)) {
+        return record.retryAfter * 1000;
+    }
+    if (typeof record.retryAfter === "string") {
+        const parsed = parseRetryAfter(record.retryAfter);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    const match = error.message.match(RETRY_AFTER_TEXT);
+    if (match !== null) {
+        return Number(match[1]) * 1000;
+    }
+    return undefined;
+}
+function parseRetryAfter(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        return undefined;
+    }
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, seconds * 1000);
+    }
+    const date = Date.parse(trimmed);
+    if (Number.isNaN(date)) {
+        return undefined;
+    }
+    return Math.max(0, date - Date.now());
+}