@aexol/spectral 0.9.222 → 0.9.224

package/dist/agent/index.d.ts

@@ -50,6 +50,19 @@ export declare function buildSubagentSystemPrompt(baseSystemPrompt: string | und
  */
 export declare function createSubagentSessionManagerSnapshot(sessionManager: ExtensionContext["sessionManager"]): Pick<ReadonlySessionManager, "getBranch" | "getSessionId">;
 export declare function resolveSubagentTools(cwd: string, ext: ExtensionAPI, ctx: ExtensionContext): AgentTool[];
+/** Test hook: replace the run-level retry sleep (e.g. with an instant/collecting stub). */
+export declare function setSubagentRetrySleepForTesting(fn?: (ms: number, signal?: AbortSignal) => Promise<void>): void;
+/**
+ * Resolve the max number of child-run attempts for the run-level retry loop.
+ * An explicit tool param (clamped to 0-10) overrides everything — including a
+ * globally disabled retry switch. Without the param, the session default
+ * (3 retries) applies unless retry is explicitly disabled, in which case a
+ * single attempt is made.
+ */
+export declare function resolveSubagentMaxAttempts(explicit: number | undefined, settings: {
+    enabled?: boolean;
+    maxRetries?: number;
+} | undefined): number;
 export default function subagentExtension(ext: ExtensionAPI, opts?: {
     disabledAgents?: string[];
     emitSubagentEvent?: (event: ServerEvent) => void;

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AAuGxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AA0JD;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AA6BD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAycD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAqBpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AAuGxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AA4JD;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AA6BD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAqHD,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAC9C,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACtD,IAAI,CAEN;AAmBD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC9D,MAAM,CAiBR;AA2eD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CA2aN"}

package/dist/agent/index.js

@@ -28,10 +28,11 @@
  *     (`share_project_observation`, `receive_agent_observations`,
  *     `compact_context`, `subagent`) remain excluded
  */
-import { agentLoop } from "../sdk/agent-core/index.js";
+import { agentLoop, agentLoopContinue, } from "../sdk/agent-core/index.js";
 import { buildIsolatedRequestTimePrunedMessagesResult, COMPACT_CONTEXT_TOOL_NAME, } from "../memory/tools/compact-context.js";
-import { StringEnum } from "../sdk/ai/index.js";
+import { isRateLimitError, isTransientApiError, isContextOverflow, isPaymentRequiredError, StringEnum, streamSimple, } from "../sdk/ai/index.js";
 import { mutateSystemPrompt } from "../sdk/coding-agent/core/system-prompt-mutator.js";
+import { sleep } from "../sdk/coding-agent/utils/sleep.js";
 import { Type } from "typebox";
 import { discoverAgents, agentMetadataBlock, } from "./agents.js";
 import { loadAgentSettings } from "../server/handlers/agent-settings.js";
@@ -334,15 +335,17 @@ async function mapWithConcurrencyLimit(items, concurrency, fn) {
     return results;
 }
 /**
- * Wraps `runSingleAgent` with an independent per-subagent timeout.
+ * Runs a child agent with an independent per-subagent timeout.
  *
  * Combines the parent's abort signal with a fresh timeout AbortController so
  * that no single subagent can exhaust the parent prompt's full timeout budget.
+ * The budget covers the WHOLE child run including any resume retries (see
+ * `runSingleAgent`), so wall time stays bounded by SUBAGENT_TIMEOUT_MS.
  * On timeout, returns a clear error result instead of throwing so the parent
  * agent can continue (e.g. stop a chain, or surface the error as the tool
  * result for parallel/single modes).
  */
-async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx) {
+async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries) {
     const timeoutMs = SUBAGENT_TIMEOUT_MS;
     const timeoutSeconds = timeoutMs / 1000;
     const controller = new AbortController();
@@ -356,7 +359,7 @@ async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cw
             signal.addEventListener("abort", onParentAbort, { once: true });
     }
     try {
-        const result = await runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, controller.signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx);
+        const result = await runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, controller.signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries);
         // If the timeout fired (and parent signal did not), surface a clean
         // timeout error result rather than a bare "aborted" result.
         if (controller.signal.aborted &&
@@ -379,10 +382,61 @@ async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cw
         clearTimeout(timeoutId);
     }
 }
+/**
+ * Backoff sleep for the run-level retry loop; overridable in tests. Abort-aware
+ * (mirrors the main session's abortable retry sleep): it rejects as soon as the
+ * run signal aborts instead of stalling for the full delay.
+ */
+let retrySleep = (ms, signal) => sleep(ms, signal);
+/** Test hook: replace the run-level retry sleep (e.g. with an instant/collecting stub). */
+export function setSubagentRetrySleepForTesting(fn) {
+    retrySleep = fn ?? ((ms, signal) => sleep(ms, signal));
+}
+/** Upper bound for the tool-level `maxRetries` param (defense against bad values). */
+const SUBAGENT_MAX_RETRIES_CAP = 10;
+/**
+ * Minimal assistant-shaped probe used to ask `isContextOverflow` about a bare
+ * error string during retry classification.
+ */
+function buildOverflowProbe(errorMessage) {
+    return {
+        role: "assistant",
+        content: [],
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        stopReason: "error",
+        errorMessage,
+    };
+}
+/**
+ * Resolve the max number of child-run attempts for the run-level retry loop.
+ * An explicit tool param (clamped to 0-10) overrides everything — including a
+ * globally disabled retry switch. Without the param, the session default
+ * (3 retries) applies unless retry is explicitly disabled, in which case a
+ * single attempt is made.
+ */
+export function resolveSubagentMaxAttempts(explicit, settings) {
+    // Non-finite values (NaN/Infinity) from direct internal callers are treated
+    // as absent — otherwise `1 + NaN` would poison the attempts cap and loop.
+    const capped = explicit !== undefined && Number.isFinite(explicit)
+        ? Math.max(0, Math.min(SUBAGENT_MAX_RETRIES_CAP, Math.floor(explicit)))
+        : undefined;
+    if (capped !== undefined)
+        return 1 + capped;
+    if (settings && settings.enabled === false)
+        return 1;
+    // Settings-derived values are hardened the same way as the explicit param:
+    // a non-finite maxRetries would otherwise poison the cap (`segments >= NaN`
+    // is never true → unbounded retries).
+    const settingsRetries = Number.isFinite(settings?.maxRetries)
+        ? Math.min(SUBAGENT_MAX_RETRIES_CAP, settings.maxRetries)
+        : undefined;
+    const retries = settingsRetries ?? 3;
+    return 1 + retries;
+}
 // ---------------------------------------------------------------------------
 // Core — run a single subagent in-process via agentLoop
 // ---------------------------------------------------------------------------
-async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx) {
+async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries) {
     const normalizedAgentName = agentName.replace(/^@/, "");
     const agent = agents.find((a) => a.name === normalizedAgentName);
     if (!agent) {
@@ -493,7 +547,29 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             });
         }
     };
+    // Run-level retry policy for the resume loop below (mirrors
+    // AgentSession._prepareRetry + its settings-driven backoff).
+    const retrySettings = ctx.settingsManager?.getRetrySettings?.();
+    const maxSegments = resolveSubagentMaxAttempts(maxRetries, retrySettings);
+    const baseDelayMs = Number.isFinite(retrySettings?.baseDelayMs)
+        ? retrySettings?.baseDelayMs
+        : 2000;
     try {
+        // Provider retry settings: subagents must inherit the same configurable
+        // retry policy as the main session (see sdk.ts streamFn wrapper) instead
+        // of silently falling back to provider SDK defaults (e.g. OpenAI's
+        // maxRetries=2 is too few for multi-minute outages). `ctx.settingsManager`
+        // is optional on ExtensionContext — when absent the wrapper below simply
+        // forwards options untouched, so provider/SDK defaults still apply.
+        // Optional call: symmetric with getRetrySettings?.() above — partial
+        // settingsManager stubs (extension contexts, tests) must not throw.
+        const providerRetrySettings = ctx.settingsManager?.getProviderRetrySettings?.();
+        const subagentStreamFn = (streamModel, streamContext, options) => streamSimple(streamModel, streamContext, {
+            ...options,
+            timeoutMs: options?.timeoutMs ?? providerRetrySettings?.timeoutMs,
+            maxRetries: options?.maxRetries ?? providerRetrySettings?.maxRetries,
+            maxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings?.maxRetryDelayMs,
+        });
         // Invocation-local hook state; never reuse the parent extension context/runtime.
         const config = {
             model,
@@ -523,81 +599,166 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                 }
             },
         };
-        const stream = agentLoop([{ role: "user", content: [{ type: "text", text: task }], timestamp: Date.now() }], {
+        const initialPrompt = [
+            {
+                role: "user",
+                content: [{ type: "text", text: task }],
+                timestamp: Date.now(),
+            },
+        ];
+        const baseContext = {
             systemPrompt: `${effectivePrompt}\n\n---\n\n# Task\n\n${task}`,
             messages: [],
             tools,
-        }, config, signal);
+        };
         // Collect messages from the stream
         const collectedMessages = [];
         let hadError = false;
-        for await (const event of stream) {
-            if (signal?.aborted) {
-                hadError = true;
-                break;
-            }
-            onInternalEvent?.(event, parentToolCallId);
-            if (event.type === "message_update" && event.message?.role === "assistant") {
-                // Forward streaming text/thinking deltas so the UI can show the
-                // subagent process as it's generated, not just the final result.
-                const inner = event.assistantMessageEvent;
-                if (inner?.type === "text_delta" && inner.delta) {
-                    streamingText += inner.delta;
-                    emitUpdate();
+        let segments = 0;
+        // One child run may span several segments: the first one starts the
+        // loop, any later one resumes it. Tool results already recorded in
+        // `collectedMessages` are part of the resumed context, so tools are
+        // never re-executed by a retry.
+        const consumeStream = async (stream) => {
+            for await (const event of stream) {
+                if (signal?.aborted) {
+                    hadError = true;
+                    break;
                 }
-                else if (inner?.type === "thinking_delta" && inner.delta) {
-                    thinkingText += inner.delta;
-                    if (inner.metadata) {
-                        thinkingMetadata = { ...(thinkingMetadata ?? {}), ...inner.metadata };
+                onInternalEvent?.(event, parentToolCallId);
+                if (event.type === "message_update" && event.message?.role === "assistant") {
+                    // Forward streaming text/thinking deltas so the UI can show the
+                    // subagent process as it's generated, not just the final result.
+                    const inner = event.assistantMessageEvent;
+                    if (inner?.type === "text_delta" && inner.delta) {
+                        streamingText += inner.delta;
+                        emitUpdate();
                     }
-                    emitUpdate();
-                }
-                continue;
-            }
-            if (event.type === "message_end" && event.message) {
-                const msg = event.message;
-                collectedMessages.push(msg);
-                if (msg.role === "assistant") {
-                    // Reset streaming accumulator — final text is now in messages
-                    streamingText = "";
-                    currentResult.usage.turns++;
-                    const usage = msg.usage;
-                    if (usage) {
-                        currentResult.usage.input += usage.input || 0;
-                        currentResult.usage.output += usage.output || 0;
-                        currentResult.usage.cacheRead += usage.cacheRead || 0;
-                        currentResult.usage.cacheWrite += usage.cacheWrite || 0;
-                        currentResult.usage.cost += usage.cost?.total || 0;
-                        currentResult.usage.contextTokens = usage.totalTokens || 0;
+                    else if (inner?.type === "thinking_delta" && inner.delta) {
+                        thinkingText += inner.delta;
+                        if (inner.metadata) {
+                            thinkingMetadata = { ...(thinkingMetadata ?? {}), ...inner.metadata };
+                        }
+                        emitUpdate();
                     }
-                    if (!currentResult.model && msg.model)
-                        currentResult.model = msg.model;
-                    if (msg.stopReason)
-                        currentResult.stopReason = msg.stopReason;
-                    if (msg.errorMessage)
-                        currentResult.errorMessage = msg.errorMessage;
-                    if (msg.stopReason === "error" || msg.stopReason === "aborted") {
-                        hadError = true;
+                    continue;
+                }
+                if (event.type === "message_end" && event.message) {
+                    const msg = event.message;
+                    collectedMessages.push(msg);
+                    if (msg.role === "assistant") {
+                        // Reset streaming accumulator — final text is now in messages
+                        streamingText = "";
+                        currentResult.usage.turns++;
+                        const usage = msg.usage;
+                        if (usage) {
+                            currentResult.usage.input += usage.input || 0;
+                            currentResult.usage.output += usage.output || 0;
+                            currentResult.usage.cacheRead += usage.cacheRead || 0;
+                            currentResult.usage.cacheWrite += usage.cacheWrite || 0;
+                            currentResult.usage.cost += usage.cost?.total || 0;
+                            currentResult.usage.contextTokens = usage.totalTokens || 0;
+                        }
+                        if (!currentResult.model && msg.model)
+                            currentResult.model = msg.model;
+                        if (msg.stopReason)
+                            currentResult.stopReason = msg.stopReason;
+                        if (msg.errorMessage)
+                            currentResult.errorMessage = msg.errorMessage;
+                        if (msg.stopReason === "error" || msg.stopReason === "aborted") {
+                            hadError = true;
+                        }
                     }
+                    currentResult.messages = [...collectedMessages];
+                    emitUpdate();
+                }
+                if (event.type === "tool_execution_end" && event.isError) {
+                    emitUpdate();
+                }
+                if (event.type === "agent_end" && event.error) {
+                    hadError = true;
+                    currentResult.errorMessage = event.error;
+                    currentResult.stderr = event.error;
                 }
-                currentResult.messages = [...collectedMessages];
-                emitUpdate();
             }
-            if (event.type === "tool_execution_end" && event.isError) {
-                emitUpdate();
+        };
+        for (;;) {
+            segments++;
+            // Per-segment transient state: a resumed segment must be able to
+            // succeed without inheriting the previous segment's failure flags.
+            hadError = false;
+            streamingText = "";
+            // Drop thinking accumulated by the failed segment so the live sheet
+            // shows the resumed segment's reasoning, not stale text.
+            thinkingText = "";
+            thinkingMetadata = undefined;
+            currentResult.stopReason = undefined;
+            currentResult.errorMessage = undefined;
+            currentResult.stderr = "";
+            // Resume (segments > 1) continues the child with its existing
+            // transcript through `agentLoopContinue` — the same mechanism the
+            // main session uses (Agent.continue → runAgentLoopContinue) — so
+            // already-executed tools are NOT re-run. Only when there is nothing
+            // to resume from (empty transcript) do we fall back to a fresh
+            // `agentLoop` call, which then re-emits the initial prompt.
+            const canResume = collectedMessages.length > 0 &&
+                collectedMessages[collectedMessages.length - 1].role !== "assistant";
+            const stream = segments === 1 || !canResume
+                ? agentLoop(initialPrompt, baseContext, config, signal, subagentStreamFn)
+                : agentLoopContinue({ ...baseContext, messages: [...collectedMessages] }, config, signal, subagentStreamFn);
+            await consumeStream(stream);
+            // Drain the stream result (already consumed by iteration, but ensure cleanup)
+            try {
+                await stream.result();
             }
-            if (event.type === "agent_end" && event.error) {
-                hadError = true;
-                currentResult.errorMessage = event.error;
-                currentResult.stderr = event.error;
+            catch {
+                // Stream result error — already handled by message events
             }
-        }
-        // Drain the stream result (already consumed by iteration, but ensure cleanup)
-        try {
-            await stream.result();
-        }
-        catch {
-            // Stream result error — already handled by message events
+            // ── Run-level retry decision (mirrors AgentSession._prepareRetry) ──
+            if (segments >= maxSegments)
+                break;
+            if (currentResult.stopReason !== "error")
+                break;
+            // Abort after a completed segment (parent stop or budget timeout):
+            // never retry, and never sleep into a phantom extra segment.
+            if (signal?.aborted)
+                break;
+            const errorMessage = currentResult.errorMessage || "";
+            // Payment required (402) is a billing problem — retries cannot help.
+            // Explicit for parity with AgentSession._isRetryableError.
+            if (isPaymentRequiredError(errorMessage))
+                break;
+            // Context overflow is a hard failure, not transient. It must be
+            // checked before the classifiers because overflow messages can
+            // contain bare status-code-like numerals (e.g. "501234 tokens >
+            // 500000 maximum").
+            if (isContextOverflow(buildOverflowProbe(errorMessage), model.contextWindow)) {
+                break;
+            }
+            if (!isRateLimitError(errorMessage) && !isTransientApiError(errorMessage)) {
+                break;
+            }
+            // Drop the failed assistant message(s) so the child resumes AT the
+            // failed turn instead of re-running it. Several trailing assistant
+            // messages are possible: the in-loop retry emits a failed assistant
+            // message before popping it from the loop context.
+            while (collectedMessages.length > 0 &&
+                collectedMessages[collectedMessages.length - 1].role === "assistant") {
+                collectedMessages.pop();
+            }
+            currentResult.messages = [...collectedMessages];
+            try {
+                await retrySleep(baseDelayMs * 2 ** (segments - 1), signal);
+            }
+            catch {
+                // Aborted during the backoff window (the sleep rejects on abort):
+                // fall through to the check below instead of throwing out of the
+                // child run.
+            }
+            // Abort during the backoff window: break so the attempt annotation
+            // counts only completed segments.
+            if (signal?.aborted)
+                break;
         }
         currentResult.exitCode = hadError ? 1 : 0;
         if (signal?.aborted) {
@@ -605,6 +766,12 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             currentResult.stopReason = "aborted";
             currentResult.errorMessage = "Subagent was aborted";
         }
+        if (segments > 1) {
+            currentResult.attempts = segments;
+            if (currentResult.exitCode !== 0 && currentResult.errorMessage) {
+                currentResult.errorMessage = `${currentResult.errorMessage} (failed after ${segments} attempts)`;
+            }
+        }
         return currentResult;
     }
     catch (err) {
@@ -652,6 +819,11 @@ const SubagentParams = Type.Object({
     cwd: Type.Optional(Type.String({
         description: "Working directory for the agent process (single mode)",
     })),
+    maxRetries: Type.Optional(Type.Integer({
+        description: "Max automatic resume retries after a transient provider failure: the child resumes at the failed turn instead of restarting, so its tools are not re-executed (overrides the configured retry count and a disabled retry switch; 0-10).",
+        minimum: 0,
+        maximum: 10,
+    })),
 });
 // ---------------------------------------------------------------------------
 // Extension entry point
@@ -834,7 +1006,7 @@ export default function subagentExtension(ext, opts) {
                             }
                         }
                         : undefined;
-                    const result = await runSingleAgentWithTimeout(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), _toolCallId, emitSubagentToolProgress, ext, ctx);
+                    const result = await runSingleAgentWithTimeout(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), _toolCallId, emitSubagentToolProgress, ext, ctx, params.maxRetries);
                     results.push(result);
                     const isError = result.exitCode !== 0 ||
                         result.stopReason === "error" ||
@@ -861,7 +1033,9 @@ export default function subagentExtension(ext, opts) {
                     const output = truncateOutput(getFinalOutput(r.messages) || "(no output)", SUBAGENT_OUTPUT_LIMIT);
                     const status = r.exitCode === 0
                         ? "completed"
-                        : "failed";
+                        : r.attempts && r.attempts > 1
+                            ? `failed (after ${r.attempts} attempts)`
+                            : "failed";
                     return `[step ${idx + 1} - ${r.agent}] ${status}:\n${output}`;
                 });
                 return {
@@ -919,7 +1093,7 @@ export default function subagentExtension(ext, opts) {
                             allResults[index] = partial.details.results[0];
                             emitParallelUpdate();
                         }
-                    }, makeDetails("parallel"), _toolCallId, emitSubagentToolProgress, ext, ctx);
+                    }, makeDetails("parallel"), _toolCallId, emitSubagentToolProgress, ext, ctx, params.maxRetries);
                     allResults[index] = result;
                     emitParallelUpdate();
                     return result;
@@ -927,7 +1101,12 @@ export default function subagentExtension(ext, opts) {
                 const successCount = results.filter((r) => r.exitCode === 0).length;
                 const summaries = results.map((r) => {
                     const output = truncateOutput(getFinalOutput(r.messages), SUBAGENT_OUTPUT_LIMIT);
-                    return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}:\n${output || "(no output)"}`;
+                    const status = r.exitCode === 0
+                        ? "completed"
+                        : r.attempts && r.attempts > 1
+                            ? `failed (after ${r.attempts} attempts)`
+                            : "failed";
+                    return `[${r.agent}] ${status}:\n${output || "(no output)"}`;
                 });
                 return {
                     content: [
@@ -941,7 +1120,7 @@ export default function subagentExtension(ext, opts) {
             }
             // ── Single mode ─────────────────────────────────────────────
             if (params.agent && params.task) {
-                const result = await runSingleAgentWithTimeout(ctx.cwd, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"), _toolCallId, emitSubagentToolProgress, ext, ctx);
+                const result = await runSingleAgentWithTimeout(ctx.cwd, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"), _toolCallId, emitSubagentToolProgress, ext, ctx, params.maxRetries);
                 const isError = result.exitCode !== 0 ||
                     result.stopReason === "error" ||
                     result.stopReason === "aborted";

package/dist/sdk/agent-core/agent-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../../src/sdk/agent-core/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,WAAW,EAUZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,EAEb,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAoCzE;;;GAGG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CA2BzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAkCzC;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,YAAY,EAAE,CAAC,CAiBzB;AAsxBD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAYlG"}
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../../src/sdk/agent-core/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,WAAW,EAWZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,EAEb,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAiCzE;;;GAGG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CA2BzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAkCzC;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,YAAY,EAAE,CAAC,CAiBzB;AAsxBD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAYlG"}

package/dist/sdk/agent-core/agent-loop.js

@@ -2,15 +2,13 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { EventStream, formatPaymentRequiredMessage, formatRateLimitRetryMessage, getRateLimitRetryDelayMs, isPaymentRequiredError, MAX_RATE_LIMIT_RETRIES, streamSimple, isRateLimitError, validateToolArguments, } from "../ai/index.js";
+import { EventStream, formatPaymentRequiredMessage, formatRateLimitRetryMessage, getRateLimitRetryDelayMs, isPaymentRequiredError, MAX_RATE_LIMIT_RETRIES, streamSimple, isRateLimitError, isTransientApiError, validateToolArguments, } from "../ai/index.js";
 /** Maximum consecutive tool call errors before terminating the loop. */
 const MAX_CONSECUTIVE_TOOL_ERRORS = 10;
 /** Maximum retries for transient provider API errors. */
 const MAX_API_RETRIES = 3;
 /** Base backoff (ms) for transient API error retries; doubles per attempt. */
 const API_RETRY_BASE_MS = 1000;
-/** Shared transient-error classifier (excluding rate limits, which get their own schedule). */
-const TRANSIENT_API_ERROR_RE = /overloaded|529|timeout|network|econnreset|fetch failed|socket connection was closed|connection.?closed|connection.?reset|socket hang up|other side closed|reset before headers|upstream.?connect|http2 request did not get a response/i;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Interval between keepalive ticks during long retry waits. */
 const RETRY_WAIT_TICK_MS = 30_000;
@@ -211,7 +209,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 const isTransientError = !signal?.aborted &&
                     !isPaymentRequiredError(errorMsg) &&
                     !isRateLimitError(errorMsg) &&
-                    TRANSIENT_API_ERROR_RE.test(errorMsg);
+                    isTransientApiError(errorMsg);
                 if (isTransientError && apiRetryCount < MAX_API_RETRIES) {
                     apiRetryCount++;
                     const backoffMs = API_RETRY_BASE_MS * Math.pow(2, apiRetryCount - 1); // 1000, 2000, 4000

package/dist/sdk/ai/index.d.ts

@@ -17,6 +17,7 @@ export * from "./utils/json-parse.js";
 export type { OAuthAuthInfo, OAuthCredentials, OAuthDeviceCodeInfo, OAuthLoginCallbacks, OAuthPrompt, OAuthProvider, OAuthProviderId, OAuthProviderInfo, OAuthProviderInterface, OAuthSelectOption, OAuthSelectPrompt, } from "./utils/oauth/types.js";
 export * from "./utils/overflow.js";
 export * from "./utils/rate-limit-retry.js";
+export * from "./utils/transient-error.js";
 export * from "./utils/typebox-helpers.js";
 export * from "./utils/validation.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/sdk/ai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sdk/ai/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,YAAY,EACX,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,GACjB,MAAM,wBAAwB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sdk/ai/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,YAAY,EACX,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,GACjB,MAAM,wBAAwB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC"}

package/dist/sdk/ai/index.js

@@ -15,5 +15,6 @@ export * from "./utils/event-stream.js";
 export * from "./utils/json-parse.js";
 export * from "./utils/overflow.js";
 export * from "./utils/rate-limit-retry.js";
+export * from "./utils/transient-error.js";
 export * from "./utils/typebox-helpers.js";
 export * from "./utils/validation.js";

package/dist/sdk/ai/utils/transient-error.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Transient provider-error classification shared by the agent-core agent
+ * loop and the coding-agent auto-retry.
+ *
+ * Companion module to rate-limit-retry.ts, which is re-exported here so
+ * retry call sites can classify an error from a single import. Rate limits
+ * (HTTP 429) always take priority over this classifier — they follow their
+ * own long 25-attempt backoff schedule — while every other transient
+ * signal (overload, HTTP 5xx, "temporarily unavailable", network /
+ * connection / stream failures) retries with a short backoff.
+ *
+ * Payment required (HTTP 402) and context-overflow errors are also not
+ * covered here; callers exclude them before consulting this classifier
+ * because retrying cannot help in those cases.
+ *
+ * @module @spectral/ai/utils/transient-error
+ */
+export { isRateLimitError } from "./rate-limit-retry.js";
+/**
+ * Check whether an error message (which may embed a raw provider JSON blob)
+ * describes a transient API failure worth retrying — overload, HTTP 5xx,
+ * "temporarily unavailable", or a network/connection/stream failure.
+ *
+ * Rate limits (429) are intentionally NOT matched here; call sites must
+ * check `isRateLimitError` first so they keep their own long schedule.
+ */
+export declare function isTransientApiError(message: string): boolean;
+//# sourceMappingURL=transient-error.d.ts.map

package/dist/sdk/ai/utils/transient-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient-error.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/utils/transient-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AA8BzD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist/sdk/ai/utils/transient-error.js

@@ -0,0 +1,55 @@
+/**
+ * Transient provider-error classification shared by the agent-core agent
+ * loop and the coding-agent auto-retry.
+ *
+ * Companion module to rate-limit-retry.ts, which is re-exported here so
+ * retry call sites can classify an error from a single import. Rate limits
+ * (HTTP 429) always take priority over this classifier — they follow their
+ * own long 25-attempt backoff schedule — while every other transient
+ * signal (overload, HTTP 5xx, "temporarily unavailable", network /
+ * connection / stream failures) retries with a short backoff.
+ *
+ * Payment required (HTTP 402) and context-overflow errors are also not
+ * covered here; callers exclude them before consulting this classifier
+ * because retrying cannot help in those cases.
+ *
+ * @module @spectral/ai/utils/transient-error
+ */
+export { isRateLimitError } from "./rate-limit-retry.js";
+/**
+ * One classifier for every transient provider-API failure signal:
+ *
+ * - overload: `overloaded`, `529` as a standalone token (e.g. Anthropic
+ *   `overloaded_error`); word-bounded so token counts like `529000` never
+ *   match
+ * - server errors: `500`, `502`, `503`, `504`, `unavailable`,
+ *   `internal error`, `server error`
+ * - temporary provider hiccups: `temporarily` (e.g. "model temporarily
+ *   unavailable")
+ * - timeouts and network/connection failures: `timeout`, `timed?.?out`,
+ *   `network`, `econnreset`, `fetch failed`, `connection.*closed`,
+ *   `connection.*reset`, `connection.*error`, `connection.*refused`,
+ *   `connection.*lost`, `socket hang up`, `websocket.*closed`,
+ *   `websocket.*error`, `other side closed`, `socket connection was
+ *   closed`, `reset before headers`, `upstream.*connect`, `http2 request
+ *   did not get a response`
+ * - provider wrapper errors and premature stream endings:
+ *   `provider.*returned.*error`, `ended without`,
+ *   `stream ended before message_stop`, `terminated`, `retry delay`
+ *
+ * Consumers must check `isRateLimitError` first: rate limits have their own
+ * retry schedule, and this classifier deliberately does not match 429 /
+ * "rate limit" / "too many requests".
+ */
+const TRANSIENT_API_ERROR_RE = /overloaded|\b529\b|timeout|timed?.?out|network|econnreset|fetch failed|socket connection was closed|connection.?closed|connection.?reset|connection.?error|connection.?refused|connection.?lost|socket hang up|websocket.?closed|websocket.?error|other side closed|reset before headers|upstream.?connect|http2 request did not get a response|provider.?returned.?error|ended without|stream ended before message_stop|terminated|retry delay|\b5(?:00|02|03|04)\b|unavailable|temporarily|internal.?error|server.?error/i;
+/**
+ * Check whether an error message (which may embed a raw provider JSON blob)
+ * describes a transient API failure worth retrying — overload, HTTP 5xx,
+ * "temporarily unavailable", or a network/connection/stream failure.
+ *
+ * Rate limits (429) are intentionally NOT matched here; call sites must
+ * check `isRateLimitError` first so they keep their own long schedule.
+ */
+export function isTransientApiError(message) {
+    return TRANSIENT_API_ERROR_RE.test(message);
+}