@aragon-agent/core 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -9,6 +9,49 @@ were written.
 
 ### Added
 
+- **`llm/retry.ts` — retry with exponential backoff, ON BY DEFAULT.**
+  `RETRY_LIMITS`, `DEFAULT_RETRY_POLICY`, `isRetryableError`,
+  `computeBackoffDelay`, `parseRetryAfterMs` and `withRetry` are exported from the
+  root barrel (75 → 81 runtime exports). `ProviderRegistry.stream()` wraps every
+  provider stream, so the agent loop, every subagent and `ProviderRegistry`
+  itself inherit retry with no call-site changes.
+
+  A transient failure — 429, 529, 5xx, DNS/TLS/ECONNRESET, 408 — is now retried
+  up to **10 times** with an increasing, equal-jittered interval
+  (1 s → 2 → 4 → 8 → 16 → 30 s, capped at 30 s per wait) under a **240 s**
+  wall-clock budget measured from the first failure. `auth_error`,
+  `invalid_request`, `context_overflow` and `unknown` are never retried: ten
+  retries of a bad API key is three minutes of looking broken.
+
+  A user abort is never retried, and this is the load-bearing detail:
+  `wrapFetchError` marks an `AbortError` `retryable: true`, so
+  `isRetryableError` reads `signal.aborted` **before** `err.retryable`. An
+  aborted request yields no further event of any kind — in particular no `error`
+  — so nothing fabricates a network failure out of Esc.
+
+  `Retry-After` (and `x-ratelimit-reset-after` /
+  `anthropic-ratelimit-requests-reset` / `anthropic-ratelimit-input-tokens-reset`)
+  is honoured as a **floor**, never a replacement, and a value above 60 s is
+  surfaced immediately rather than waited out.
+
+- **Three new `StreamEvent` variants** — `RetryScheduledEvent`,
+  `RetryAttemptEvent`, `StreamRestartEvent`. Additive: `consumeStream` ignores
+  anything that is not `done`/`error`, and a consumer with a `default` branch is
+  unaffected. `retry_scheduled` carries `resumeAt` (an absolute instant) rather
+  than a tick stream, so a UI owns its own clock.
+
+- **`ProviderRegistry` holds a policy.** New `ProviderRegistryOptions`,
+  `setRetryPolicy(policy | null)` and `getRetryPolicy()`;
+  `initProviders(options?)` forwards them. `undefined` means the product default,
+  an explicit `null` means opt out.
+
+- **`LLMError` gains a 7th optional field `retryAfterMs`**, and
+  `classifyHttpError` an optional 4th parameter `headers?: Headers`. Both
+  additive; every existing call site compiles unchanged.
+
+- **`Agent` pauses its idle watchdog across a backoff.** A 30 s wait would
+  otherwise be read as a wedged call and abort the run at `idleTimeout`.
+
 - **`llm/output-limits.ts` — one authority for the output-token cap.**
   `DEFAULT_MAX_OUTPUT_TOKENS` (64000), `MIN_MAX_OUTPUT_TOKENS`,
   `SAFE_FALLBACK_MAX_OUTPUT_TOKENS`, `ABSOLUTE_MAX_OUTPUT_TOKENS`,
@@ -41,6 +84,40 @@ were written.
 
 ### Changed
 
+- **BEHAVIOUR CHANGE — retry is on by default for embedders.** A failing call
+  that used to end immediately can now take up to ~3 minutes to fail. The budget
+  bounds it; `initProviders({ retryPolicy: null })` or `setRetryPolicy(null)`
+  restores the old behaviour exactly, and `maxRetries: 0` short-circuits the
+  wrapper so the opted-out path is byte-identical.
+
+- **BEHAVIOUR CHANGE — a truncated stream is now a loud error instead of a
+  silent success.** All three adapters used to end their SSE loop by
+  *unconditionally* yielding `done` with whatever had accumulated. A stream
+  closed gracefully mid-answer — a proxy idle cut, a load-balancer timeout, an
+  HTTP/2 GOAWAY, `[DONE]` never arriving — therefore surfaced as **success
+  carrying a truncated answer**, which no layer above the adapter could tell from
+  a real one. Each adapter now tracks its own terminal sentinel
+  (`message_stop` / `[DONE]` **or** a `finish_reason` / a chunk carrying
+  `finishReason`) and yields a retryable `network_error` when the stream ends
+  without it. Consequences:
+
+  - the mid-answer disconnection case is now retried and recovered;
+  - `ProviderRegistry.complete()` / `provider.complete()` change from returning a
+    partial `AssistantMessage` to **throwing** for a truncated stream;
+  - an **abort** is explicitly excluded and still yields `done`, and an empty but
+    complete turn is still a success.
+
+  This is deliberately **not** behind the retry switch: an adapter that reports a
+  truncated stream honestly should do so whether or not retry is enabled.
+
+- **HTTP 408 is now `errorType: 'timeout'`, `retryable: true`** (it used to fall
+  into `unknown` / non-retryable).
+
+- **`ProviderRegistry.complete()` now routes through `this.stream()`** instead of
+  `provider.complete()`. Behaviour-preserving — all three adapters implement
+  `complete` as exactly `consumeStream(this.stream(request))` — except that the
+  registry's version is now the retrying one.
+
 - `ModelRegistry.buildRuntimeModel` defaults `maxOutputTokens` to
   `DEFAULT_MAX_OUTPUT_TOKENS` rather than a private `16384`, the built-in
   Anthropic catalog entries carry their real ceilings, and `registerDefaults` /
@@ -49,6 +126,21 @@ were written.
   product default for every model — neither API reports an output ceiling, and
   claiming otherwise outranked the correct value for every small model.
 
+### Notes
+
+- **`streamLLM` / `completeLLM` diverge from a registry you build yourself.**
+  They resolve through `getProviderRegistry()`, which lazily calls
+  `initProviders()` with no arguments, so they always carry
+  `DEFAULT_RETRY_POLICY` and do not observe a policy installed elsewhere. For one
+  policy everywhere, call `setProviderRegistry(initProviders({ retryPolicy }))`
+  once at startup.
+
+- **A half-open connection is still not covered** (no FIN, no RST). It produces
+  no event, so `withRetry` never wakes and the idle watchdog aborts the run. A
+  per-attempt stall timer is not safe at this layer: Anthropic's `ping` frames
+  are swallowed by the adapter, so a long extended-thinking pause and a dead
+  socket look identical at the `StreamEvent` layer.
+
 ## 0.3.0
 
 ### Added

package/dist/engine/agent.d.ts

@@ -131,6 +131,23 @@ export declare class Agent {
      * Listener errors are caught and logged to prevent crashing the loop.
      */
     private emit;
+    /**
+     * Suspend the idle watchdog across a retry backoff, and resume it when the
+     * next attempt goes out (llm-api-retry-backoff §4.6).
+     *
+     * `withRetry` waits up to `maxDelayMs` between attempts and emits nothing while
+     * it does. That is indistinguishable from a wedged network call to the
+     * watchdog, which is right for a wedged call and wrong for a wait the engine
+     * itself scheduled. `pause()` swallows the subsequent `kick()` by design and
+     * `resume()` restarts the window from now; both are idempotent.
+     *
+     * A `retry_scheduled` never followed by a `retry_attempt` — an abort during the
+     * wait — leaves the watchdog deaf, and that is bounded rather than leaked:
+     * `runLoopWithLifecycle`'s `finally` calls `watchdog.stop()`, and `stop()`
+     * clears `paused` for exactly this reason. DO NOT "simplify" that line out of
+     * `stop()`.
+     */
+    private applyRetryWatchdogPolicy;
     /**
      * Synchronize the ToolRegistry with the provided tool array.
      * Removes tools no longer present and adds new ones.

package/dist/engine/agent.js

@@ -218,6 +218,11 @@ export class Agent {
      * Listener errors are caught and logged to prevent crashing the loop.
      */
     emit(event) {
+        // BEFORE THE LISTENERS. A listener that throws is caught below, but the
+        // policy still has to have been applied — otherwise a bad subscriber leaves
+        // the watchdog armed across a 30-second backoff and the run is aborted for
+        // being "idle" while it is provably waiting on purpose.
+        this.applyRetryWatchdogPolicy(event);
         for (const listener of this.listeners) {
             try {
                 listener(event);
@@ -228,6 +233,31 @@ export class Agent {
         }
         this.watchdog.kick();
     }
+    /**
+     * Suspend the idle watchdog across a retry backoff, and resume it when the
+     * next attempt goes out (llm-api-retry-backoff §4.6).
+     *
+     * `withRetry` waits up to `maxDelayMs` between attempts and emits nothing while
+     * it does. That is indistinguishable from a wedged network call to the
+     * watchdog, which is right for a wedged call and wrong for a wait the engine
+     * itself scheduled. `pause()` swallows the subsequent `kick()` by design and
+     * `resume()` restarts the window from now; both are idempotent.
+     *
+     * A `retry_scheduled` never followed by a `retry_attempt` — an abort during the
+     * wait — leaves the watchdog deaf, and that is bounded rather than leaked:
+     * `runLoopWithLifecycle`'s `finally` calls `watchdog.stop()`, and `stop()`
+     * clears `paused` for exactly this reason. DO NOT "simplify" that line out of
+     * `stop()`.
+     */
+    applyRetryWatchdogPolicy(event) {
+        if (event.type !== 'message_update')
+            return;
+        const t = event.streamEvent.type;
+        if (t === 'retry_scheduled')
+            this.watchdog.pause();
+        else if (t === 'retry_attempt')
+            this.watchdog.resume();
+    }
     /**
      * Synchronize the ToolRegistry with the provided tool array.
      * Removes tools no longer present and adds new ones.

package/dist/index.d.ts

@@ -5,17 +5,20 @@
  * Other tasks will expand this file as more modules are added (engine, tools,
  * sandbox).
  */
-export type { ContentPart, TextContentPart, ImageContentPart, ContentBlock, TextBlock, ThinkingBlock, ToolCallBlock, Message, UserMessage, AssistantMessage, ToolResultMessage, StopReason, TokenUsage, ThinkingLevel, StreamEvent, TextDeltaEvent, ThinkingStartEvent, ThinkingDeltaEvent, ToolCallStartEvent, ToolCallDeltaEvent, ToolCallEndEvent, DoneEvent, ErrorEvent, ToolDefinition, JSONSchema, ModelInfo, ModelCost, } from './llm/types.js';
+export type { ContentPart, TextContentPart, ImageContentPart, ContentBlock, TextBlock, ThinkingBlock, ToolCallBlock, Message, UserMessage, AssistantMessage, ToolResultMessage, StopReason, TokenUsage, ThinkingLevel, StreamEvent, TextDeltaEvent, ThinkingStartEvent, ThinkingDeltaEvent, ToolCallStartEvent, ToolCallDeltaEvent, ToolCallEndEvent, DoneEvent, ErrorEvent, RetryScheduledEvent, RetryAttemptEvent, StreamRestartEvent, ToolDefinition, JSONSchema, ModelInfo, ModelCost, } from './llm/types.js';
 export { THINKING_BUDGET } from './llm/types.js';
 export type { LLMProvider, LLMRequest, LLMErrorType, } from './llm/provider.js';
 export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js';
 export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
 export type { OutputLimitInput, OutputLimitResolution, CeilingSource, } from './llm/output-limits.js';
 export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
+export { RETRY_LIMITS, DEFAULT_RETRY_POLICY, isRetryableError, computeBackoffDelay, parseRetryAfterMs, withRetry, } from './llm/retry.js';
+export type { RetryPolicy, RetryDecision, WithRetryOptions, } from './llm/retry.js';
 export type { OutputLimitFailure, RecoveryAttempt, RecoveryOptions, TokenField, } from './llm/output-limit-recovery.js';
 export type { SSEEvent } from './llm/stream-utils.js';
 export { parseSSEStream, consumeStream, } from './llm/stream-utils.js';
 export { ProviderRegistry, initProviders, getProviderRegistry, setProviderRegistry, streamLLM, completeLLM, } from './llm/providers/index.js';
+export type { ProviderRegistryOptions } from './llm/providers/index.js';
 export { AnthropicProvider } from './llm/providers/anthropic.js';
 export { OpenAIProvider } from './llm/providers/openai.js';
 export { GoogleProvider } from './llm/providers/google.js';

package/dist/index.js

@@ -13,6 +13,17 @@ export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js'
 // ---------------------------------------------------------------------------
 export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
 export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
+// ---------------------------------------------------------------------------
+// Retry & exponential backoff — the authority for "a provider call failed, now
+// what". Installed by default on `ProviderRegistry.stream()`; opt out with
+// `initProviders({ retryPolicy: null })` or `setRetryPolicy(null)`.
+//
+// `normalizePolicy` and `decide` are deliberately NOT here: they are the
+// implementation of the two entry points below, nobody outside the module has a
+// reason to call them, and promoting them would add two symbols to the frozen
+// public surface for nothing.
+// ---------------------------------------------------------------------------
+export { RETRY_LIMITS, DEFAULT_RETRY_POLICY, isRetryableError, computeBackoffDelay, parseRetryAfterMs, withRetry, } from './llm/retry.js';
 export { parseSSEStream, consumeStream, } from './llm/stream-utils.js';
 // ---------------------------------------------------------------------------
 // Provider registry

package/dist/llm/provider.d.ts

@@ -79,13 +79,36 @@ export declare class LLMError extends Error {
     readonly retryable: boolean;
     readonly statusCode?: number | undefined;
     readonly raw?: unknown | undefined;
-    constructor(message: string, provider: string, errorType: LLMErrorType, retryable: boolean, statusCode?: number | undefined, raw?: unknown | undefined);
+    /**
+     * The wait the SERVER asked for, in ms (llm-api-retry-backoff §4.4).
+     *
+     * A 7th OPTIONAL POSITIONAL FIELD, so every existing construction site
+     * compiles unchanged. Read structurally by `withRetry` — never through
+     * `instanceof LLMError`, for the reason `isRetryableError` records.
+     */
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, provider: string, errorType: LLMErrorType, retryable: boolean, statusCode?: number | undefined, raw?: unknown | undefined, 
+    /**
+     * The wait the SERVER asked for, in ms (llm-api-retry-backoff §4.4).
+     *
+     * A 7th OPTIONAL POSITIONAL FIELD, so every existing construction site
+     * compiles unchanged. Read structurally by `withRetry` — never through
+     * `instanceof LLMError`, for the reason `isRetryableError` records.
+     */
+    retryAfterMs?: number | undefined);
 }
 /**
  * Classify an HTTP status code into an {@link LLMErrorType} and determine
  * whether the request is retryable.
+ *
+ * `headers` is OPTIONAL and additive: when supplied, a server-stated
+ * `Retry-After` (or a provider rate-limit reset header) rides out on
+ * `LLMError.retryAfterMs`, which is the only channel a retry policy has for
+ * honouring it. Adapters that cannot reach the headers — Anthropic's IN-STREAM
+ * `error` event, which arrives after the connection is already open — simply
+ * omit it and fall back to the plain backoff ladder.
  */
-export declare function classifyHttpError(statusCode: number, body: string, provider: string): LLMError;
+export declare function classifyHttpError(statusCode: number, body: string, provider: string, headers?: Headers): LLMError;
 /**
  * Wrap a network-level fetch error (DNS, TLS, abort, etc.) into an LLMError.
  */

package/dist/llm/provider.js

@@ -1,27 +1,56 @@
 /**
  * LLM Provider interface, request types, and error classification.
  */
+/**
+ * A DELIBERATE MODULE CYCLE, and it is safe for one specific reason:
+ * `retry.ts` imports `LLMError` from here and uses it only INSIDE a function
+ * body, while this module uses `parseRetryAfterMs` only inside
+ * `classifyHttpError`. Neither side touches the other's binding during module
+ * evaluation, so whichever loads first the other's top level completes cleanly.
+ *
+ * A future top-level `LLMError` reference in `retry.ts`, or a top-level
+ * `parseRetryAfterMs` call here, WOULD hit the TDZ and throw at import time.
+ * Keep both usages inside functions.
+ */
+import { parseRetryAfterMs } from './retry.js';
 export class LLMError extends Error {
     provider;
     errorType;
     retryable;
     statusCode;
     raw;
-    constructor(message, provider, errorType, retryable, statusCode, raw) {
+    retryAfterMs;
+    constructor(message, provider, errorType, retryable, statusCode, raw, 
+    /**
+     * The wait the SERVER asked for, in ms (llm-api-retry-backoff §4.4).
+     *
+     * A 7th OPTIONAL POSITIONAL FIELD, so every existing construction site
+     * compiles unchanged. Read structurally by `withRetry` — never through
+     * `instanceof LLMError`, for the reason `isRetryableError` records.
+     */
+    retryAfterMs) {
         super(message);
         this.provider = provider;
         this.errorType = errorType;
         this.retryable = retryable;
         this.statusCode = statusCode;
         this.raw = raw;
+        this.retryAfterMs = retryAfterMs;
         this.name = 'LLMError';
     }
 }
 /**
  * Classify an HTTP status code into an {@link LLMErrorType} and determine
  * whether the request is retryable.
+ *
+ * `headers` is OPTIONAL and additive: when supplied, a server-stated
+ * `Retry-After` (or a provider rate-limit reset header) rides out on
+ * `LLMError.retryAfterMs`, which is the only channel a retry policy has for
+ * honouring it. Adapters that cannot reach the headers — Anthropic's IN-STREAM
+ * `error` event, which arrives after the connection is already open — simply
+ * omit it and fall back to the plain backoff ladder.
  */
-export function classifyHttpError(statusCode, body, provider) {
+export function classifyHttpError(statusCode, body, provider, headers) {
     let errorType;
     let retryable;
     switch (statusCode) {
@@ -41,6 +70,13 @@ export function classifyHttpError(statusCode, body, provider) {
             errorType = 'auth_error';
             retryable = false;
             break;
+        // A REQUEST TIMEOUT IS TRANSIENT, and it used to fall into `default` ->
+        // `unknown` / non-retryable. The abort exclusion that makes `timeout` safe to
+        // retry lives in `isRetryableError` (check 1), not here.
+        case 408:
+            errorType = 'timeout';
+            retryable = true;
+            break;
         case 429:
             errorType = 'rate_limit';
             retryable = true;
@@ -61,7 +97,8 @@ export function classifyHttpError(statusCode, body, provider) {
     }
     // Truncate body for the error message to avoid huge payloads
     const truncated = body.length > 300 ? body.slice(0, 300) + '...' : body;
-    return new LLMError(`${provider} API error ${statusCode}: ${truncated}`, provider, errorType, retryable, statusCode, body);
+    const retryAfterMs = parseRetryAfterMs(headers);
+    return new LLMError(`${provider} API error ${statusCode}: ${truncated}`, provider, errorType, retryable, statusCode, body, retryAfterMs);
 }
 /**
  * Wrap a network-level fetch error (DNS, TLS, abort, etc.) into an LLMError.

package/dist/llm/providers/anthropic.js

@@ -64,7 +64,13 @@ export class AnthropicProvider {
         }
         if (!response.ok) {
             // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
-            yield { type: 'error', error: classifyHttpError(response.status, errorBody, this.id) };
+            // `response.headers` carries `Retry-After` / `anthropic-ratelimit-*-reset`
+            // out on `LLMError.retryAfterMs`; without it a 429 that stated a wait is
+            // retried on the plain ladder instead of when the server said to.
+            yield {
+                type: 'error',
+                error: classifyHttpError(response.status, errorBody, this.id, response.headers),
+            };
             return;
         }
         if (!response.body) {
@@ -243,14 +249,42 @@ export class AnthropicProvider {
                         break;
                 }
             }
-            // Stream ended without message_stop — emit done with what we have
-            const message = {
-                role: 'assistant',
-                content: contentBlocks,
-                usage,
-                stopReason,
+            // ---- The terminal-sentinel contract (llm-api-retry-backoff §4.5a) ----
+            //
+            // Reaching here means the SSE ended WITHOUT `message_stop`: that case
+            // `return`s from inside the loop above, and so does the in-stream `error`
+            // case. No `sawTerminal` flag is needed for this adapter precisely because
+            // of those two returns — the absence is the signal. (`openai.ts` and
+            // `google.ts` DO need a flag, because their terminal frames only `break`.)
+            //
+            // TWO VERY DIFFERENT SITUATIONS SHARE THIS LINE, and conflating them is how
+            // every user abort would become a fake network error (constraint 1 / R-17):
+            //
+            //  - the request was ABORTED. `parseSSEStream` `break`s on
+            //    `signal.aborted` rather than throwing, so Esc lands here. An abort is
+            //    not a provider failure, and `agent-loop` discards the `done` anyway.
+            //  - the stream was TRUNCATED — a proxy idle cut, a load-balancer timeout,
+            //    an HTTP/2 GOAWAY, `message_stop` never arriving. This USED to yield
+            //    `done` with partial content, which is indistinguishable from success
+            //    at every layer above and is the single failure the retry machinery
+            //    exists to recover. It is now a retryable `network_error`.
+            //
+            // An empty-but-complete turn is unaffected: Anthropic always sends
+            // `message_stop`, so a model that emits zero content still returns above.
+            if (request.signal?.aborted) {
+                const message = {
+                    role: 'assistant',
+                    content: contentBlocks,
+                    usage,
+                    stopReason,
+                };
+                yield { type: 'done', message, usage };
+                return;
+            }
+            yield {
+                type: 'error',
+                error: new LLMError(`${this.id} stream truncated before message_stop`, this.id, 'network_error', true),
             };
-            yield { type: 'done', message, usage };
         }
         catch (err) {
             yield { type: 'error', error: wrapFetchError(err, this.id) };

package/dist/llm/providers/google.js

@@ -58,7 +58,12 @@ export class GoogleProvider {
         }
         if (!response.ok) {
             // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
-            yield { type: 'error', error: classifyHttpError(response.status, errorBody, this.id) };
+            // `response.headers` carries `Retry-After` out on `LLMError.retryAfterMs`
+            // so a 429 waits as long as the server asked rather than only the ladder.
+            yield {
+                type: 'error',
+                error: classifyHttpError(response.status, errorBody, this.id, response.headers),
+            };
             return;
         }
         if (!response.body) {
@@ -70,6 +75,15 @@ export class GoogleProvider {
         const contentBlocks = [];
         let textAccumulator = '';
         let stopReason;
+        /**
+         * Whether a terminal chunk arrived (§4.5a). Google's terminator is a
+         * candidate carrying `finishReason`; unlike Anthropic's `message_stop` it
+         * does not `return`, so the flag is what tells a completed stream from a
+         * truncated one. Set AT THE FRAME, never inferred from
+         * `contentBlocks.length` — a model that legitimately produces nothing and
+         * stops is a success, not a truncation (constraint 2).
+         */
+        let sawTerminal = false;
         try {
             for await (const sse of parseSSEStream(response.body, request.signal)) {
                 const raw = sse.data.trim();
@@ -96,6 +110,7 @@ export class GoogleProvider {
                 // Finish reason
                 const finishReason = candidate.finishReason;
                 if (finishReason) {
+                    sawTerminal = true;
                     stopReason = mapFinishReason(finishReason);
                 }
                 const content = candidate.content;
@@ -127,6 +142,19 @@ export class GoogleProvider {
                     }
                 }
             }
+            // ---- The terminal-sentinel contract (§4.5a) -------------------------
+            //
+            // An abort is NOT a truncation: `parseSSEStream` `break`s on
+            // `signal.aborted` and lands here, and reporting that as a retryable
+            // `network_error` would re-create the trap `isRetryableError` check 1
+            // closes (constraint 1 / R-17). Signal first; that path yields `done`.
+            if (!sawTerminal && !request.signal?.aborted) {
+                yield {
+                    type: 'error',
+                    error: new LLMError(`${this.id} stream truncated before a terminal chunk`, this.id, 'network_error', true),
+                };
+                return;
+            }
             // Flush text
             if (textAccumulator) {
                 contentBlocks.push({ type: 'text', text: textAccumulator });

package/dist/llm/providers/index.d.ts

@@ -4,10 +4,33 @@
  */
 import type { AssistantMessage, ModelInfo, StreamEvent } from '../types.js';
 import type { LLMProvider, LLMRequest } from '../provider.js';
+import { type RetryPolicy } from '../retry.js';
+export interface ProviderRegistryOptions {
+    /**
+     * Retry policy for `stream()` and (through it) `complete()`.
+     *
+     * `undefined` and `null` MEAN DIFFERENT THINGS, exactly as they do for
+     * `PersistedConfig.maxTokens`: absent means "the product default"
+     * (`DEFAULT_RETRY_POLICY`), explicit `null` means "the user said no".
+     */
+    retryPolicy?: RetryPolicy | null;
+}
 export declare class ProviderRegistry {
     private readonly providers;
+    private retryPolicy;
+    constructor(options?: ProviderRegistryOptions);
     /** Register a provider. Overwrites any existing registration with the same id. */
     register(provider: LLMProvider): void;
+    /**
+     * Install a retry policy live, or `null` to opt out entirely.
+     *
+     * A METHOD RATHER THAN A CONSTRUCTOR-ONLY CONCERN because the CLI's `/retry
+     * off` has to take effect in the running session: persisting the setting and
+     * changing nothing until the next launch is the failure users report as "the
+     * setting does nothing".
+     */
+    setRetryPolicy(policy: RetryPolicy | null): void;
+    getRetryPolicy(): RetryPolicy | null;
     /** Retrieve a provider by id. */
     get(id: string): LLMProvider | undefined;
     /** Return all registered providers. */
@@ -15,7 +38,22 @@ export declare class ProviderRegistry {
     /** Check whether a provider is registered. */
     has(id: string): boolean;
     /**
-     * Convenience: stream a completion through the named provider.
+     * Convenience: stream a completion through the named provider, WITH RETRY.
+     *
+     * THIS IS THE SEAM THE WHOLE RETRY FEATURE HANGS ON (llm-api-retry-backoff
+     * §5.2). Wrapping here rather than inside each adapter is what lets the retry
+     * see the commit point, the abort signal and the whole event stream at once,
+     * and it is why the lead agent, every subagent and `completeLLM` all inherit
+     * retry with zero call-site changes.
+     *
+     * The thunk captures `request` WHOLE, so every attempt sends the same body —
+     * including any `max_tokens` that `sendWithOutputLimitRecovery` repaired on the
+     * way through, because that repair lives inside `provider.stream()` and re-runs
+     * per attempt.
+     *
+     * `maxRetries <= 0` returns the adapter's iterator DIRECTLY rather than a
+     * wrapper that happens to never retry: an opted-out caller is then byte- and
+     * allocation-identical to a pre-feature build.
      *
      * @throws {LLMError} if the provider is not registered.
      */
@@ -23,6 +61,14 @@ export declare class ProviderRegistry {
     /**
      * Convenience: non-streaming completion through the named provider.
      *
+     * ROUTED THROUGH `this.stream()`, NOT `provider.complete()`, and that is not
+     * optional (§5.4). All three adapters implement `complete` as exactly
+     * `consumeStream(this.stream(request))`, so this is behaviour-preserving — the
+     * only difference is that the registry's version is now the RETRYING one.
+     * Calling `provider.complete()` here would leave `completeLLM` as the one
+     * public entry point with no retry at all, which is exactly the kind of hole
+     * that gets discovered in production.
+     *
      * @throws {LLMError} if the provider is not registered.
      */
     complete(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
@@ -39,14 +85,27 @@ export declare class ProviderRegistry {
 /**
  * Create and populate a {@link ProviderRegistry} with all built-in providers.
  * Call this once at server startup.
+ *
+ * `options` is additive and source-compatible: every existing `initProviders()`
+ * call site compiles unchanged and gets `DEFAULT_RETRY_POLICY`.
  */
-export declare function initProviders(): ProviderRegistry;
+export declare function initProviders(options?: ProviderRegistryOptions): ProviderRegistry;
 /**
  * Get (or lazily create) the global singleton provider registry.
  *
  * Prefer calling `initProviders()` explicitly at startup and passing the
  * registry around.  This singleton exists as a convenience for modules that
  * cannot easily receive the registry through dependency injection.
+ *
+ * IT IS A SEPARATE REGISTRY AND IT KEEPS THE PRODUCT DEFAULT RETRY POLICY
+ * (llm-api-retry-backoff §5.3). It is built here with `initProviders()` and no
+ * arguments, and a host that constructs its own registry (the CLI does) never
+ * installs it — so `streamLLM` / `completeLLM` retry with
+ * `DEFAULT_RETRY_POLICY` and do NOT observe that host's `/retry off` equivalent.
+ * Harmless while nothing calls those two helpers, and deliberately not "fixed"
+ * by having a UI mutate process-wide state. An embedder that wants one policy
+ * everywhere calls `setProviderRegistry(initProviders({ retryPolicy }))` once at
+ * startup.
  */
 export declare function getProviderRegistry(): ProviderRegistry;
 /**