@crossworks/voice-client 0.230.43

package/LICENSE.md

@@ -0,0 +1,135 @@
+# License
+
+Mantle is **dual-licensed** by Cross Works Engineering (Pty) Ltd:
+
+1. **Public license — Functional Source License 1.1 (MIT Future), reproduced in
+   full below.** Free to use, self-host, modify, and run for any purpose that is
+   not a Competing Use (see the _Permitted Purpose_ clause). Two years after each
+   version is first published, that version automatically converts to the MIT
+   license.
+2. **Commercial license — see [`LICENSE-COMMERCIAL.md`](./LICENSE-COMMERCIAL.md).**
+   A paid agreement that lifts the FSL's _Competing Use_ restriction for partners
+   who want to embed Mantle in a commercial product or offer it as a service
+   during the two-year window. Contact **licensing@crossworks.engineering**.
+
+For a plain-language explanation of how the two licenses fit together and what the
+key terms mean, see [`LICENSING.md`](./LICENSING.md). Third-party open-source
+components bundled with Mantle are attributed in
+[`THIRD-PARTY-NOTICES.md`](./THIRD-PARTY-NOTICES.md).
+
+The "Change Date" for each release is **two years after that release is first made
+available** under this license; on the Change Date that release becomes available
+under the MIT license (the _Grant of Future License_ below).
+
+---
+
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Cross Works Engineering (Pty) Ltd
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@crossworks/voice-client",
+  "version": "0.230.43",
+  "description": "Browser-safe surface of the voice/model layer — provider catalogue, model catalogs, audio tags, and the adapter type/metadata contract. Zero deps by design: nothing here may reach the network adapters or node builtins (the jackdaw-repo-split P0 boundary).",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossworks-engineering/mantle"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/adapters/registry.ts

@@ -0,0 +1,296 @@
+/**
+ * Adapter registry — provider id → dispatcher lookup, per capability.
+ *
+ * Built-in adapters self-register at module load via the import chain
+ * in `./index.ts`. Apps that want to add custom adapters at runtime
+ * call `registerTtsAdapter(...)` etc. before the first use.
+ *
+ * Resolution is intentionally strict: if no adapter is registered for
+ * a given `providerId`, the lookup returns null and the runtime
+ * surfaces a clear "not yet wired" error rather than guessing. The
+ * catalog's `wired` flag is derived from these registries so the UI
+ * stays honest about which providers can actually be called.
+ */
+
+import type { Provider, ProviderCapability, ProviderId } from '../providers';
+import type {
+  ChatDispatcher,
+  EmbeddingDispatcher,
+  ImageGenDispatcher,
+  SttDispatcher,
+  TtsDispatcher,
+  VisionDispatcher,
+} from './types';
+import { withChatRetry } from './retry';
+
+const CHAT = new Map<ProviderId, ChatDispatcher>();
+const TTS = new Map<ProviderId, TtsDispatcher>();
+const STT = new Map<ProviderId, SttDispatcher>();
+const VISION = new Map<ProviderId, VisionDispatcher>();
+const IMAGE_GEN = new Map<ProviderId, ImageGenDispatcher>();
+const EMBEDDING = new Map<ProviderId, EmbeddingDispatcher>();
+
+export type WiredCapability = 'chat' | 'tts' | 'stt' | 'vision' | 'image_gen' | 'embedding';
+
+/**
+ * STATIC mirror of which providers have a registered adapter, per capability —
+ * the source of truth for `isProviderWired` and the settings UI.
+ *
+ * Why static and not "read the live Maps above": the built-in adapters only land
+ * in those Maps when `./index.ts` runs its `register*Adapter(...)` chain, which
+ * pulls in node-only deps (undici / node:crypto). The browser bundle imports the
+ * adapter-free `@mantle/voice/client` leaf, so client-side the Maps are EMPTY —
+ * reading them there reported EVERY provider as "not wired". This pure-data table
+ * gives the correct answer in both bundles. It's kept in lockstep with the live
+ * registrations by `registry.test.ts` (register an adapter without adding it here
+ * → the drift test fails). Mirror `adapters/index.ts` exactly when editing.
+ */
+export const WIRED_PROVIDERS: Record<WiredCapability, ReadonlySet<ProviderId>> = {
+  chat: new Set<ProviderId>([
+    'openrouter',
+    'anthropic',
+    'google',
+    'xai',
+    'huggingface',
+    'deepseek',
+    'copilot',
+    'custom',
+    'local',
+  ]),
+  tts: new Set<ProviderId>(['openrouter', 'openai', 'elevenlabs', 'xai', 'google']),
+  stt: new Set<ProviderId>([
+    'openrouter',
+    'openai',
+    'xai',
+    'elevenlabs',
+    'deepgram',
+    'assemblyai',
+    'google',
+  ]),
+  vision: new Set<ProviderId>(['openai', 'anthropic', 'google', 'xai', 'openrouter']),
+  image_gen: new Set<ProviderId>(['openrouter', 'openai', 'xai', 'google', 'huggingface']),
+  embedding: new Set<ProviderId>(['openrouter', 'openai', 'google', 'mistral', 'cohere', 'local']),
+};
+
+function mapFor(capability: WiredCapability): ReadonlyMap<ProviderId, unknown> {
+  return {
+    chat: CHAT,
+    tts: TTS,
+    stt: STT,
+    vision: VISION,
+    image_gen: IMAGE_GEN,
+    embedding: EMBEDDING,
+  }[capability];
+}
+
+/** Live-registry provider ids for a capability — used by the drift test to prove
+ *  WIRED_PROVIDERS matches what `adapters/index.ts` actually registered. */
+export function registeredProviderIds(capability: WiredCapability): ProviderId[] {
+  return [...mapFor(capability).keys()];
+}
+
+// ─── Chat ────────────────────────────────────────────────────────────
+
+export function registerChatAdapter(adapter: ChatDispatcher): void {
+  CHAT.set(adapter.providerId, adapter);
+}
+
+export function getChatAdapter(providerId: string): ChatDispatcher | null {
+  const adapter = CHAT.get(providerId as ProviderId) ?? null;
+  if (!adapter) return null;
+  // OpenRouter's SDK already retries transient errors internally; wrapping it
+  // would compound attempt counts. The native-fetch adapters (anthropic /
+  // google / xai / huggingface / deepseek) have no retry of their own, so wrap
+  // those once here for uniform 429/5xx/network/timeout backoff.
+  if (adapter.providerId === 'openrouter') return adapter;
+  return withChatRetry(adapter);
+}
+
+export function listChatAdapters(): ChatDispatcher[] {
+  return Array.from(CHAT.values());
+}
+
+// ─── TTS ─────────────────────────────────────────────────────────────
+
+export function registerTtsAdapter(adapter: TtsDispatcher): void {
+  TTS.set(adapter.providerId, adapter);
+}
+
+export function getTtsAdapter(providerId: string): TtsDispatcher | null {
+  return TTS.get(providerId as ProviderId) ?? null;
+}
+
+export function listTtsAdapters(): TtsDispatcher[] {
+  return Array.from(TTS.values());
+}
+
+// ─── STT ─────────────────────────────────────────────────────────────
+
+export function registerSttAdapter(adapter: SttDispatcher): void {
+  STT.set(adapter.providerId, adapter);
+}
+
+export function getSttAdapter(providerId: string): SttDispatcher | null {
+  return STT.get(providerId as ProviderId) ?? null;
+}
+
+export function listSttAdapters(): SttDispatcher[] {
+  return Array.from(STT.values());
+}
+
+// ─── Vision (interface ready, no adapters yet) ───────────────────────
+
+export function registerVisionAdapter(adapter: VisionDispatcher): void {
+  VISION.set(adapter.providerId, adapter);
+}
+
+export function getVisionAdapter(providerId: string): VisionDispatcher | null {
+  return VISION.get(providerId as ProviderId) ?? null;
+}
+
+/**
+ * Provider ids whose vision adapter can read a PDF NATIVELY — i.e. implements
+ * `extractDocument`. This is the SELF-MAINTAINING source of truth for "which
+ * providers a Document worker can use natively": it reads the adapter registry,
+ * so the moment a new adapter (e.g. Google) gains `extractDocument`, it appears
+ * here with no second list to update. Native-PDF capability is a fact about OUR
+ * adapter code, not something the provider's API advertises — so the registry
+ * is the only honest place to derive it.
+ */
+export function nativeDocumentProviders(): ProviderId[] {
+  const out: ProviderId[] = [];
+  for (const [id, adapter] of VISION) {
+    if (typeof adapter.extractDocument === 'function') out.push(id);
+  }
+  return out;
+}
+
+// ─── Image generation (interface ready, no adapters yet) ─────────────
+
+export function registerImageGenAdapter(adapter: ImageGenDispatcher): void {
+  IMAGE_GEN.set(adapter.providerId, adapter);
+}
+
+export function getImageGenAdapter(providerId: string): ImageGenDispatcher | null {
+  return IMAGE_GEN.get(providerId as ProviderId) ?? null;
+}
+
+// ─── Embedding ───────────────────────────────────────────────────────
+
+export function registerEmbeddingAdapter(adapter: EmbeddingDispatcher): void {
+  EMBEDDING.set(adapter.providerId, adapter);
+}
+
+export function getEmbeddingAdapter(providerId: string): EmbeddingDispatcher | null {
+  return EMBEDDING.get(providerId as ProviderId) ?? null;
+}
+
+export function listEmbeddingAdapters(): EmbeddingDispatcher[] {
+  return Array.from(EMBEDDING.values());
+}
+
+// ─── Capability check (used by UI to derive `wired` flag) ────────────
+
+/**
+ * Verify the providers catalog and the adapter registry agree on
+ * "what each provider supports". Returns an array of drift problems
+ * (empty when consistent). Each problem is the human-readable
+ * sentence we surface to the dev log or to the failing test.
+ *
+ * The drift we care about: a registered adapter exists for a
+ * (provider, capability) pair that the providers catalog does NOT
+ * declare. Symptom in production: provider dropdown filters in the
+ * worker form (which read the catalog's `capabilities`) hide the
+ * provider for that kind, even though the runtime would happily
+ * accept it. We hit this exact bug when xai-tts + google-tts
+ * shipped — adapters registered, catalog still said chat-only —
+ * and the TTS dropdown wouldn't list either.
+ *
+ * Catalog without adapter is the OTHER direction and is FINE — it
+ * means "we plan to wire this; not yet." That's the documented
+ * "not yet wired" state and isn't a bug.
+ *
+ * Called from `./index.ts` once on module load (dev-log warning) and
+ * exercised explicitly in catalog-consistency.test.ts so a missed
+ * catalog edit fails CI.
+ */
+export function findAdapterCatalogDrift(
+  providers: ReadonlyArray<{ id: string; capabilities: readonly string[] }>,
+): string[] {
+  const problems: string[] = [];
+  const catalogById = new Map(providers.map((p) => [p.id as string, p.capabilities]));
+
+  function check(
+    label: 'chat' | 'tts' | 'stt' | 'vision' | 'image_gen' | 'embedding',
+    registry: Map<ProviderId, { adapterName: string }>,
+  ): void {
+    for (const [providerId, adapter] of registry) {
+      const caps = catalogById.get(providerId);
+      if (!caps) {
+        problems.push(
+          `${adapter.adapterName} is registered, but provider id '${providerId}' is not in SUPPORTED_PROVIDERS.`,
+        );
+        continue;
+      }
+      if (!caps.includes(label)) {
+        problems.push(
+          `${adapter.adapterName} is registered, but the providers catalog for '${providerId}' does not list '${label}' in capabilities. ` +
+            `Add '${label}' to the entry in packages/voice/src/providers.ts so the worker-form dropdown surfaces this provider for ${label} workers.`,
+        );
+      }
+    }
+  }
+
+  check('chat', CHAT);
+  check('tts', TTS);
+  check('stt', STT);
+  check('vision', VISION);
+  check('image_gen', IMAGE_GEN);
+  check('embedding', EMBEDDING);
+
+  return problems;
+}
+
+/**
+ * Is the given provider wired (i.e. has a registered adapter) for the
+ * given capability? Drives the "wired" / "not yet wired" hint in the
+ * settings UI so the catalog stays honest.
+ */
+export function isProviderWired(providerId: string, capability: WiredCapability): boolean {
+  const id = providerId as ProviderId;
+  // Union of the STATIC table (covers the built-in adapters — and is the ONLY
+  // thing visible in the adapter-free browser bundle, where the live Maps are
+  // empty) and the LIVE registry (honours adapters registered at runtime, e.g.
+  // custom/hot-swapped). No 'openai' chat carve-out: OpenAI has no direct chat
+  // adapter (it's reached via the `openrouter` provider with an `openai/*`
+  // model), so for chat it is honestly "not wired" — surfacing it as wired only
+  // produced an empty model dropdown.
+  return (WIRED_PROVIDERS[capability]?.has(id) ?? false) || mapFor(capability).has(id);
+}
+
+/**
+ * For each capability the provider's catalog DECLARES, return whether
+ * an adapter is registered for it. Drives the api-keys form's
+ * per-provider wired-status summary so operators see exactly what a
+ * key for this provider will be usable for (vs. the binary
+ * "any-capability-wired" check which misclassifies partially-wired
+ * providers like Mistral/Cohere — both declare chat but only wire
+ * embedding).
+ *
+ * Returns wired + unwired arrays preserving the catalog's declared
+ * order. UI typically renders wired ones first (the usable
+ * capabilities) and unwired ones separately as "supported but not
+ * dispatched by Mantle yet."
+ */
+export function wiredCapabilitiesFor(provider: Provider): {
+  wired: ProviderCapability[];
+  unwired: ProviderCapability[];
+} {
+  const wired: ProviderCapability[] = [];
+  const unwired: ProviderCapability[] = [];
+  for (const cap of provider.capabilities) {
+    if (isProviderWired(provider.id, cap)) wired.push(cap);
+    else unwired.push(cap);
+  }
+  return { wired, unwired };
+}

package/src/adapters/retry.ts

@@ -0,0 +1,193 @@
+/**
+ * Retry/backoff for the chat dispatch path.
+ *
+ * The native-fetch chat adapters (anthropic / google / xai / huggingface /
+ * deepseek) were each a single `fetch` that threw on the first non-OK
+ * response — so a momentary 429 or 503 on ANY tool-loop iteration aborted the
+ * whole turn (the responder dropped the inbound message; a multi-iteration
+ * tool run lost all prior work). Only OpenRouter had resilience, via its SDK's
+ * built-in retries.
+ *
+ * `withChatRetry` wraps a ChatDispatcher so the direct-provider adapters get
+ * uniform, configurable retry on transient errors (429, 408/409/425, 5xx,
+ * network blips, and the adapters' own 60s fetch timeout) with exponential
+ * backoff + jitter, honoring `Retry-After` when the provider sends it. It is
+ * applied once at the `getChatAdapter` registry boundary, so every chat call
+ * site (responder, web assistant, extractor, summarizer, reflector,
+ * heartbeats, invoke_agent) is covered without opting in.
+ *
+ * OpenRouter is intentionally NOT wrapped — its SDK already retries, and
+ * double-wrapping would compound attempt counts. See registry.getChatAdapter.
+ */
+import type { ChatDispatcher, ChatOptions, ChatResult } from './types';
+
+/** Default attempts AFTER the first try (so 2 ⇒ up to 3 total calls). */
+export const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 8_000;
+/** Cap an honored Retry-After so a pathological header can't stall a turn. */
+const RETRY_AFTER_CAP_MS = 30_000;
+
+/** Transient HTTP statuses worth retrying. */
+const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
+
+/**
+ * Structured error the native-fetch chat adapters throw on a non-OK response.
+ * Carries the status + parsed Retry-After so the retry wrapper can decide
+ * cleanly (no message parsing). The `message` is byte-identical to the plain
+ * `Error` the adapters threw before (`<provider> chat <status>: <body…>`), so
+ * existing wire-shape tests and log scrapers are unaffected.
+ */
+export class ChatHttpError extends Error {
+  readonly provider: string;
+  readonly status: number;
+  readonly retryAfterMs?: number;
+  readonly body?: string;
+  constructor(opts: { provider: string; status: number; body?: string; retryAfterMs?: number }) {
+    super(`${opts.provider} chat ${opts.status}: ${(opts.body ?? '').slice(0, 400)}`);
+    this.name = 'ChatHttpError';
+    this.provider = opts.provider;
+    this.status = opts.status;
+    this.retryAfterMs = opts.retryAfterMs;
+    this.body = opts.body;
+  }
+}
+
+/**
+ * Parse a `Retry-After` header (RFC 7231: delta-seconds or HTTP-date) into ms.
+ * Returns undefined when absent/unparseable.
+ */
+export function parseRetryAfterMs(headers?: Headers | null): number | undefined {
+  // Defensive `?.get?.` — real `fetch` always gives a Headers, but tests (and
+  // some mocked transports) hand back a plain object with no headers.
+  const raw = headers?.get?.('retry-after');
+  if (!raw) return undefined;
+  const secs = Number(raw);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+  const when = Date.parse(raw);
+  if (Number.isFinite(when)) return Math.max(0, when - Date.now());
+  return undefined;
+}
+
+/**
+ * An empty or truncated 2xx body that `JSON.parse` choked on — the signature of
+ * an upstream timeout / dropped connection that still returned 200 (or a cut-off
+ * stream). Transient: the same request usually succeeds on retry. (Caught in
+ * prod: a 16-step assistant turn died here after a 34s upstream stall returned
+ * an empty body — see openrouter-chat.ts.)
+ *
+ * We match only the families that CANNOT arise from a complete payload, because
+ * a complete-but-invalid body is a genuine bug we must not mask behind retries:
+ *
+ *   - "Unexpected end of JSON input"  — `''`, whitespace, or input ending where
+ *                                       a value was expected. Always truncation.
+ *   - "Unterminated string in JSON"   — a string opened and never closed. Only
+ *                                       reachable by running out of input.
+ *
+ * Deliberately NOT matched: `Expected ',' or '}' after property value…`,
+ * `Expected ':' after property name…`, `Expected property name or '}'…`. Those
+ * fire for BOTH a mid-object truncation and a malformed-but-complete body, and
+ * the message alone cannot tell them apart — only the byte offset versus the
+ * body length could, which this signature doesn't receive. Retrying a real
+ * malformed payload would turn one loud bug into three silent ones.
+ *
+ * ⚠️ The message strings are V8's, and V8 has changed them before: this used to
+ * claim it covered truncation generally, which was true on older Node where
+ * every cut-off body said "Unexpected end of JSON input". Modern V8 emits
+ * specific messages per failure shape, so that claim had quietly become false
+ * for most truncations. The tests below parse REAL malformed JSON rather than
+ * asserting hand-written message strings, so the next V8 wording change fails
+ * them instead of silently narrowing this again.
+ */
+export function isEmptyJsonBodyError(err: unknown): boolean {
+  if (!(err instanceof SyntaxError)) return false;
+  return (
+    /unexpected end of (json )?input/i.test(err.message) ||
+    /unterminated string in json/i.test(err.message)
+  );
+}
+
+/** Decide whether an adapter error is worth retrying, and after how long. */
+export function classifyChatError(err: unknown): {
+  retry: boolean;
+  retryAfterMs?: number;
+} {
+  if (err instanceof ChatHttpError) {
+    return { retry: RETRYABLE_STATUS.has(err.status), retryAfterMs: err.retryAfterMs };
+  }
+  // Defensive: any error exposing a numeric HTTP status (e.g. an SDK error).
+  const status = (err as { status?: unknown } | null)?.status;
+  if (typeof status === 'number') return { retry: RETRYABLE_STATUS.has(status) };
+  // The adapters' own `AbortSignal.timeout(60_000)` fires a TimeoutError; a
+  // bare AbortError is USUALLY that timeout too — but since the Stop wiring,
+  // ChatOptions CAN carry a caller-supplied signal (a user Stop), and
+  // retrying against an aborted signal just burns backoff sleeps.
+  // `withChatRetry` short-circuits that case (it can see the signal; this
+  // classifier only sees the error). What reaches here is transient — retry.
+  const name = (err as { name?: string } | null)?.name;
+  if (name === 'TimeoutError' || name === 'AbortError') return { retry: true };
+  // Raw fetch network failures surface as TypeError ("fetch failed", ECONNRESET,
+  // DNS, …). The wrapper only guards a network call, so this is a blip — retry.
+  if (err instanceof TypeError) return { retry: true };
+  // Empty/truncated JSON body — an upstream stall that returned no parseable
+  // payload. Transient, and not covered by the status/network checks above.
+  if (isEmptyJsonBodyError(err)) return { retry: true };
+  const msg = String((err as { message?: unknown } | null)?.message ?? '');
+  if (/fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up/i.test(msg)) {
+    return { retry: true };
+  }
+  return { retry: false };
+}
+
+function describeError(err: unknown): string {
+  if (err instanceof ChatHttpError) return `HTTP ${err.status}`;
+  if (isEmptyJsonBodyError(err)) return 'empty/truncated response';
+  const name = (err as { name?: string } | null)?.name;
+  return name && name !== 'Error' ? name : 'network error';
+}
+
+export interface ChatRetryConfig {
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+}
+
+/**
+ * Wrap a ChatDispatcher with retry/backoff on its `chat` call. Per-call
+ * `opts.maxRetries` overrides the config default; 0 disables. All other
+ * dispatcher members (providerId, adapterName, discoverModels, staticCatalog)
+ * are preserved unchanged.
+ */
+export function withChatRetry(
+  adapter: ChatDispatcher,
+  config: ChatRetryConfig = {},
+): ChatDispatcher {
+  const base = config.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  const max = config.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const chat = async (opts: ChatOptions): Promise<ChatResult> => {
+    const maxRetries = opts.maxRetries ?? config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    let attempt = 0;
+    for (;;) {
+      try {
+        return await adapter.chat(opts);
+      } catch (err) {
+        // A caller-aborted signal (user Stop) is not transient: every retry
+        // would abort identically after a pointless backoff sleep. Surface it
+        // immediately — the tool loop / run-turn recognise the stop.
+        if (opts.signal?.aborted) throw err;
+        const { retry, retryAfterMs } = classifyChatError(err);
+        if (!retry || attempt >= maxRetries) throw err;
+        attempt += 1;
+        const delay =
+          retryAfterMs != null
+            ? Math.min(retryAfterMs, RETRY_AFTER_CAP_MS)
+            : Math.round(Math.random() * Math.min(max, base * 2 ** (attempt - 1)));
+        console.warn(
+          `[chat-retry] ${adapter.adapterName} ${opts.model}: ${describeError(err)} — retry ${attempt}/${maxRetries} in ${delay}ms`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  };
+  return { ...adapter, chat };
+}