rovecode 0.4.0-beta.2 → 0.4.0

package/src/providers/registry.ts

@@ -0,0 +1,302 @@
+/** Live provider registry — the ADAPTER half of the provider layer, over provider-config.ts (data).
+ *
+ *  One registry per runtime. stream() returns a DISPATCHING StreamFn: every call resolves
+ *  `model.provider` against the live snapshot (hot reload — provider-config.ts), so a provider added
+ *  from another terminal, by `rovecode provider add`, by `/provider add` in the TUI or by the agent's
+ *  provider_edit tool serves the very next model call. No restart, no runtime rebuild. Concrete
+ *  adapters (stream.ts) are cached per provider id and rebuilt when baseUrl, protocol, key or
+ *  headers change — a rotated key takes effect on the next call too.
+ *
+ *  Seam contract (ADR-003): the dispatcher never throws. An unknown provider or a missing key is ONE
+ *  error turn whose text starts with `config: ` — router.ts classifyStreamError treats that prefix
+ *  as non-retryable, so neither the same-model retry (port #23) nor a fallback chain (port #14)
+ *  spins on a configuration mistake; the text tells the human exactly how to fix it.
+ *
+ *  Because the dispatcher honours model.provider per call, cross-provider fallback chains
+ *  (ROVECODE_MODEL_<ROLE>=a/x,b/y) now really route each candidate to its own endpoint.
+ *
+ *  Secrets: this module reads keys to build adapters and to redact them from probe errors
+ *  (scrubSecret). Nothing here prints or returns a key; formatProviderList shows key SOURCES. */
+
+import type { AssistantTurn, Message, ModelRef, StreamEvent, StreamFn, StreamOptions } from "../core/types.ts";
+import { fetchModels, providerStream, providerStreaming, wantsStreaming, type ProviderConfig as WireProviderConfig } from "./stream.ts";
+import {
+  ProviderConfig, isConfigured, parseSelector, pickDefault, providersPathFor, readProvidersFile, validateSpec, writeProvidersFile,
+  type FileScope, type ProviderSnapshot, type ProviderSpec, type ResolvedProvider,
+} from "./provider-config.ts";
+import { next } from "../core/voice.ts";
+
+export type AdapterFactory = (p: ResolvedProvider, opts: { sse: boolean }) => StreamFn;
+
+/** stream.ts ProviderConfig for a resolved provider (a keyless provider sends an empty bearer). */
+export function toWireConfig(p: ResolvedProvider): WireProviderConfig {
+  return {
+    id: p.id, baseUrl: p.baseUrl, apiKey: p.apiKey ?? "", protocol: p.protocol,
+    ...(p.defaultModel !== undefined ? { defaultModel: p.defaultModel } : {}),
+    ...(p.headers !== undefined ? { headers: p.headers } : {}),
+  };
+}
+
+export const defaultAdapterFactory: AdapterFactory = (p, { sse }) => {
+  const wire = toWireConfig(p);
+  // both protocols stream (openai SSE chunks, anthropic Messages events); `sse` is off only when
+  // ROVECODE_STREAM asked for the one-shot JSON adapters
+  return sse ? providerStreaming(wire) : providerStream(wire);
+};
+
+/** Error-text prefix the router/retry classifier treats as non-retryable (router.ts). */
+export const CONFIG_ERROR_PREFIX = "config: ";
+
+export function configErrorTurn(text: string): AssistantTurn {
+  return { parts: [], stopReason: "error", usage: { input: 0, output: 0 }, error: CONFIG_ERROR_PREFIX + text };
+}
+
+/** Replace a secret wherever it leaked into text (some proxies echo request headers in error bodies). */
+export function scrubSecret(text: string, secret: string | null | undefined): string {
+  return secret !== null && secret !== undefined && secret.length > 0 ? text.split(secret).join("…") : text;
+}
+
+export interface RegistryOptions {
+  env?: NodeJS.ProcessEnv;
+  /** test seam: build adapters without touching the network */
+  adapterFactory?: AdapterFactory;
+  /** provider-config.ts reload throttle (ms); tests pass 0 */
+  throttleMs?: number;
+}
+
+export class ProviderRegistry {
+  readonly cwd: string;
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly cfg: ProviderConfig;
+  private readonly factory: AdapterFactory;
+  private readonly adapters = new Map<string, { sig: string; fn: StreamFn }>();
+
+  constructor(cwd: string, opts: RegistryOptions = {}) {
+    this.cwd = cwd;
+    this.env = opts.env ?? process.env;
+    this.factory = opts.adapterFactory ?? defaultAdapterFactory;
+    this.cfg = new ProviderConfig(cwd, this.env, opts.throttleMs);
+  }
+
+  snapshot(): ProviderSnapshot { return this.cfg.snapshot(); }
+  list(): ResolvedProvider[] { return this.snapshot().providers; }
+  ids(): string[] { return this.list().map((p) => p.id); }
+  get(id: string): ResolvedProvider | undefined { return this.list().find((p) => p.id === id); }
+  /** at least one provider has a key (or needs none) */
+  configured(): boolean { return this.list().some(isConfigured); }
+  warnings(): string[] { return this.snapshot().warnings; }
+  /** fires after every rebuild: external file edits (detected lazily) and in-process add/remove/setDefault */
+  onChange(cb: (snap: ProviderSnapshot) => void): () => void { return this.cfg.onChange(cb); }
+  /** re-read now (in-process writers call it right after writing) and notify listeners */
+  refresh(): ProviderSnapshot { this.cfg.invalidate(); return this.cfg.snapshot(); }
+
+  /** default provider + model with env ROVECODE_MODEL layered on top; null when nothing is configured */
+  defaultRef(): ModelRef | null {
+    const d = pickDefault(this.snapshot());
+    if (d === null) return null;
+    return { provider: d.provider.id, model: this.env["ROVECODE_MODEL"] ?? d.model ?? "" };
+  }
+
+  /** stream.ts-shaped config of the default provider (Runtime.provider compatibility) */
+  defaultConfig(): WireProviderConfig | null {
+    const d = pickDefault(this.snapshot());
+    if (d === null) return null;
+    return { ...toWireConfig(d.provider), ...(d.model !== undefined ? { defaultModel: d.model } : {}) };
+  }
+
+  defaultSelector(): string | undefined { return this.snapshot().defaultSelector; }
+
+  /** "provider/model" or a bare model on `currentProvider`. A leading segment counts as a provider
+   *  only when it names one, so "zai-org/glm-5.3" stays a model id on the current provider. The
+   *  current provider is not validated (it may be "mock" or an injected test stream): a bare model
+   *  always lands there, exactly as `/model <id>` always did. */
+  resolveSelector(selector: string, currentProvider: string): ModelRef | { error: string } {
+    const s = selector.trim();
+    if (s.length === 0) return { error: "empty model selector" };
+    const i = s.indexOf("/");
+    if (i > 0) {
+      const head = s.slice(0, i);
+      const tail = s.slice(i + 1).trim();
+      if (this.get(head) !== undefined) return tail.length > 0 ? { provider: head, model: tail } : { error: `"${s}" names no model — use ${head}/<model>` };
+    }
+    return { provider: currentProvider, model: s };
+  }
+
+  add(spec: ProviderSpec, scope: FileScope = "user"): ResolvedProvider | { error: string } {
+    const { id, ...raw } = spec;
+    const v = validateSpec(id, raw);
+    if ("error" in v) return v;
+    if (this.get(id)?.scope === "env") return { error: `"custom" is reserved for the ROVECODE_BASE_URL/ROVECODE_API_KEY pair — pick another id` };
+    const path = providersPathFor(scope, this.cwd);
+    const { data } = readProvidersFile(path);
+    const { id: _id, ...rest } = v.spec;
+    data.providers = { ...(data.providers ?? {}), [id]: rest };
+    writeProvidersFile(path, data);
+    this.refresh();
+    return this.get(id)!;
+  }
+
+  remove(id: string): { removed: FileScope[] } | { error: string } {
+    const p = this.get(id);
+    if (p === undefined) return { error: `unknown provider "${id}" — known: ${this.ids().join(" ")}` };
+    if (p.scope === "builtin") return { error: `"${id}" is built in; drop its key with \`rovecode auth remove ${id}\` instead` };
+    if (p.scope === "env") return { error: `"custom" comes from ROVECODE_BASE_URL/ROVECODE_API_KEY — unset those env vars` };
+    const removed: FileScope[] = [];
+    for (const scope of ["user", "project"] as const) {
+      const path = providersPathFor(scope, this.cwd);
+      const { data } = readProvidersFile(path);
+      if (data.providers !== undefined && id in data.providers) {
+        delete data.providers[id];
+        if (Object.keys(data.providers).length === 0) delete data.providers;
+        writeProvidersFile(path, data);
+        removed.push(scope);
+      }
+    }
+    this.refresh();
+    return { removed };
+  }
+
+  setDefault(selector: string, scope: FileScope = "user"): ModelRef | { error: string } {
+    const sel = parseSelector(selector);
+    const p = this.get(sel.provider);
+    if (p === undefined) return { error: `unknown provider "${sel.provider}" — known: ${this.ids().join(" ")}` };
+    const model = sel.model ?? p.defaultModel;
+    if (model === undefined) return { error: `"${selector}" names no model and ${p.id} has no default — use ${p.id}/<model>` };
+    const path = providersPathFor(scope, this.cwd);
+    const { data } = readProvidersFile(path);
+    data.default = `${p.id}/${model}`;
+    writeProvidersFile(path, data);
+    this.refresh();
+    return { provider: p.id, model };
+  }
+
+  keyHint(p: ResolvedProvider): string {
+    return `no API key for provider "${p.id}" — I can't call it without one. ${next(`rovecode auth set ${p.id}`)} (masked prompt) · or /provider key ${p.id} <key> in the TUI · or set ${p.keyEnv}`;
+  }
+
+  async models(id: string): Promise<{ ok: true; models: string[]; source: "file" | "endpoint" } | { ok: false; error: string }> {
+    const p = this.get(id);
+    if (p === undefined) return { ok: false, error: `unknown provider "${id}" — known: ${this.ids().join(" ")}` };
+    if (p.models !== undefined && p.models.length > 0) return { ok: true, models: p.models, source: "file" };
+    if (!isConfigured(p)) return { ok: false, error: this.keyHint(p) };
+    const list = await fetchModels(toWireConfig(p), true);
+    return { ok: true, models: list.map((m) => m.id), source: "endpoint" };
+  }
+
+  /** One tiny real call ("ping", ≤8 output tokens): proves url + key + model together. */
+  async probe(id: string, model?: string): Promise<{ ok: boolean; model: string; detail: string }> {
+    const p = this.get(id);
+    if (p === undefined) return { ok: false, model: model ?? "", detail: `unknown provider "${id}" — known: ${this.ids().join(" ")}` };
+    if (!isConfigured(p)) return { ok: false, model: model ?? "", detail: this.keyHint(p) };
+    const m = model ?? p.defaultModel;
+    if (m === undefined) return { ok: false, model: "", detail: `${p.id} has no default model — pass one: test ${p.id} <model>` };
+    const probeMsg: Message = { id: "probe", role: "user", parts: [{ kind: "text", text: "ping" }], parentId: null, createdAt: Date.now() };
+    const t0 = Date.now();
+    let turn: AssistantTurn | undefined;
+    try {
+      for await (const ev of this.adapterFor(p)({ provider: p.id, model: m, maxTokens: 8 }, [probeMsg], { tools: [] })) if (ev.type === "turn") turn = ev.turn;
+    } catch (e) {
+      return { ok: false, model: m, detail: scrubSecret(e instanceof Error ? e.message : String(e), p.apiKey) };
+    }
+    if (turn === undefined) return { ok: false, model: m, detail: "stream produced no turn" };
+    if (turn.stopReason === "error") return { ok: false, model: m, detail: scrubSecret(turn.error ?? "stream error", p.apiKey) };
+    return { ok: true, model: m, detail: `ok in ${Date.now() - t0} ms (${turn.usage.input} in / ${turn.usage.output} out tokens)` };
+  }
+
+  /** The dispatching StreamFn (see the header). */
+  stream(): StreamFn {
+    const self = this;
+    return async function* (model: ModelRef, messages: Message[], options?: StreamOptions): AsyncGenerator<StreamEvent> {
+      const p = self.get(model.provider);
+      if (p === undefined) {
+        yield { type: "turn", turn: configErrorTurn(`provider "${model.provider}" is not configured — I can't route to it. ${next(`rovecode provider add ${model.provider} <baseUrl> [--protocol openai|anthropic]`)} (or /provider add in the TUI); known: ${self.ids().join(" ")}`) };
+        return;
+      }
+      if (!isConfigured(p)) { yield { type: "turn", turn: configErrorTurn(self.keyHint(p)) }; return; }
+      yield* self.adapterFor(p)(model, messages, options);
+    };
+  }
+
+  private adapterFor(p: ResolvedProvider): StreamFn {
+    const sse = wantsStreaming({ ROVECODE_STREAM: this.env["ROVECODE_STREAM"] }); // default ON
+    const sig = [p.baseUrl, p.protocol, p.apiKey ?? "", JSON.stringify(p.headers ?? {}), sse ? "sse" : "json"].join("");
+    const hit = this.adapters.get(p.id);
+    if (hit !== undefined && hit.sig === sig) return hit.fn;
+    const fn = this.factory(p, { sse });
+    this.adapters.set(p.id, { sig, fn });
+    return fn;
+  }
+}
+
+// ---------- shared CLI / TUI helpers ----------
+
+export const ADD_USAGE = "add <id> <baseUrl> [--protocol openai|anthropic] [--key-env NAME] [--model <id>] [--no-key] [--project]";
+
+export interface AddArgs { spec: ProviderSpec; scope: FileScope; promptKey: boolean }
+
+/** Parse `add` words (CLI argv tail or TUI slash args) into a validated spec + scope. `--key` (CLI:
+ *  prompt for the secret afterwards) is recorded, never a value. Pure; never throws. */
+export function parseAddArgs(words: readonly string[]): AddArgs | { error: string } {
+  const pos: string[] = [];
+  const raw: Record<string, unknown> = {};
+  let scope: FileScope = "user";
+  let promptKey = false;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i]!;
+    const value = (): string | { error: string } => {
+      const v = words[i + 1];
+      if (v === undefined || v.startsWith("-")) return { error: `${w} needs a value — ${ADD_USAGE}` };
+      i++;
+      return v;
+    };
+    switch (w) {
+      case "--protocol": { const v = value(); if (typeof v !== "string") return v; raw["protocol"] = v; break; }
+      case "--key-env": { const v = value(); if (typeof v !== "string") return v; raw["keyEnv"] = v; break; }
+      case "--model": { const v = value(); if (typeof v !== "string") return v; raw["defaultModel"] = v; break; }
+      case "--scope": {
+        const v = value(); if (typeof v !== "string") return v;
+        if (v !== "user" && v !== "project") return { error: "--scope must be user or project" };
+        scope = v; break;
+      }
+      case "--project": scope = "project"; break;
+      case "--user": scope = "user"; break;
+      case "--no-key": raw["noKey"] = true; break;
+      case "--key": promptKey = true; break;
+      default:
+        if (w.startsWith("-")) return { error: `unknown flag ${w} — ${ADD_USAGE}` };
+        pos.push(w);
+    }
+  }
+  const [id, baseUrl] = pos;
+  if (id === undefined || baseUrl === undefined) return { error: `usage: ${ADD_USAGE}` };
+  raw["baseUrl"] = baseUrl;
+  const v = validateSpec(id, raw);
+  if ("error" in v) return v;
+  return { spec: v.spec, scope, promptKey };
+}
+
+/** One row per provider — key SOURCE only, never the value. */
+export function formatProviderLine(p: ResolvedProvider): string {
+  const key = p.keySource === "stored" ? "key: stored"
+    : p.keySource === "env" ? `key: env ${p.keyEnv}`
+    : p.keySource === "inline" ? "key: ROVECODE_API_KEY"
+    : p.noKey === true ? "key: not needed"
+    : `key: NONE (rovecode auth set ${p.id} · or set ${p.keyEnv})`;
+  return `${p.id.padEnd(12)} ${p.protocol.padEnd(9)} ${p.baseUrl.padEnd(40)} ${key}${p.defaultModel !== undefined ? `  model: ${p.defaultModel}` : ""}  [${p.scope}]`;
+}
+
+/** Listing for `rovecode provider list`, `/provider list` and the provider_list tool. Built-in providers
+ *  without a key are folded into a count unless `all` — sixteen dead rows hide the live ones. */
+export function formatProviderList(reg: ProviderRegistry, opts: { all?: boolean } = {}): string {
+  const d = reg.defaultRef();
+  const all = reg.list();
+  const rows = all.filter((p) => opts.all === true || isConfigured(p) || p.scope !== "builtin");
+  const lines = [d !== null
+    ? `default → ${d.provider}/${d.model || "(no model — pass one with /model or ROVECODE_MODEL)"}${reg.defaultSelector() !== undefined ? `  (providers.json default: ${reg.defaultSelector()})` : ""}`
+    : `default → none yet. ${next("rovecode setup")} (or rovecode provider add <id> <baseUrl>, then rovecode auth set <id>)`];
+  lines.push(...rows.map(formatProviderLine));
+  const hidden = all.length - rows.length;
+  if (hidden > 0) lines.push(`(+${hidden} built-in providers without a key — \`list --all\` shows them)`);
+  lines.push(...reg.warnings().map((w) => `warning: ${w}`));
+  return lines.join("\n");
+}

package/src/providers/response-validation.ts

@@ -0,0 +1,80 @@
+/** Fail closed on malformed provider envelopes and tool calls, before any side effect. */
+import type { AssistantTurn, StopReason } from "../core/types.ts";
+
+export function rejectProviderError(json: unknown): void {
+  if (json === null || typeof json !== "object") throw new Error("invalid provider response: expected an object");
+  const error = (json as { error?: unknown }).error;
+  if (error !== undefined) {
+    const message = typeof error === "object" && error !== null ? (error as { message?: unknown }).message : error;
+    throw new Error(`provider error: ${typeof message === "string" ? message : JSON.stringify(error)}`);
+  }
+}
+export function openAiStop(reason: string | null | undefined): StopReason {
+  if (reason === "length") return "length";
+  if (reason === "tool_calls") return "tool_use";
+  if (reason === "stop") return "end_turn";
+  throw new Error(`OpenAI response has invalid or missing finish reason: ${reason ?? "missing"}`);
+}
+export function anthropicStop(reason: string | null | undefined): StopReason {
+  if (reason === "max_tokens") return "length";
+  if (reason === "tool_use") return "tool_use";
+  if (reason === "end_turn" || reason === "stop_sequence") return "end_turn";
+  throw new Error(`Anthropic response has invalid or missing finish reason: ${reason ?? "missing"}`);
+}
+/** The leading balanced {...} of `s`, or null — bracket/brace counting that respects strings and
+ *  escapes. Only ever called on arguments that FAILED JSON.parse, to test one specific pathology. */
+function leadingJsonObject(s: string): string | null {
+  const start = s.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0, inStr = false, esc = false;
+  for (let i = start; i < s.length; i++) {
+    const ch = s[i]!;
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") { depth--; if (depth === 0) return s.slice(0, i + 1); }
+  }
+  return null;
+}
+
+export function parseToolArgs(raw: string, truncated: boolean): unknown {
+  if (typeof raw !== "string") throw new Error("invalid tool arguments: expected JSON string");
+  try { return JSON.parse(raw || "{}"); }
+  catch {
+    // A proxy family REPEATS the whole arguments object in every SSE delta instead of streaming
+    // fragments (the same bug that repeats the tool NAME — stream.ts absorbs that half), so the
+    // accumulator holds the identical JSON two or more times: "{…}{…}". An EXACT repeat of a
+    // parseable leading object is that pathology and nothing a model can legitimately produce —
+    // rescue the first copy instead of failing the whole turn.
+    const first = leadingJsonObject(raw);
+    if (first !== null) {
+      const rest = raw.slice(first.length);
+      if (rest.length > 0 && rest.length % first.length === 0 && rest === first.repeat(rest.length / first.length)) {
+        try { return JSON.parse(first); } catch { /* not the pathology after all — fall through */ }
+      }
+    }
+    // Length-limited calls never execute; retain fragments for the loop's failed result.
+    if (truncated) return { _raw: raw };
+    throw new Error("invalid tool arguments: expected complete JSON object");
+  }
+}
+export function validateToolCalls(parts: AssistantTurn["parts"], stop: StopReason): void {
+  const ids = new Set<string>();
+  for (const p of parts) {
+    if (p.kind !== "tool_call") continue;
+    if (typeof p.id !== "string" || !p.id.trim() || typeof p.tool !== "string" || !p.tool.trim()) {
+      throw new Error("invalid tool call: missing id or name");
+    }
+    if (ids.has(p.id)) throw new Error(`invalid tool call: duplicate id ${p.id}`);
+    ids.add(p.id);
+    if (stop !== "length" && (p.args === null || typeof p.args !== "object" || Array.isArray(p.args))) {
+      throw new Error("invalid tool arguments: expected JSON object");
+    }
+  }
+  if (stop === "tool_use" && ids.size === 0) throw new Error("provider requested tool use without any tool calls");
+}

package/src/providers/retry.ts

@@ -0,0 +1,234 @@
+/** Same-model retry with exponential backoff (port #23). A StreamFn wrapper — NO second agent
+ *  loop (ADR-003): bounded re-invocations of the SAME (model, messages, options) inside one
+ *  stream invocation, the way the router makes one bounded pass over chain candidates. Wired
+ *  INSIDE the router (`router.wrap(withRetry(stream))`, cli/runtime.ts) so retries exhaust on
+ *  candidate N before the chain advances to N+1, and the router's notes stay one-per-ADVANCE.
+ *
+ *  Source: gemini-cli (Apache-2.0 @0bd1d43 — research/source_snapshots/google-gemini-gemini-cli,
+ *  packages/core/src/utils):
+ *  - retryWithBackoff loop shape: attempt counter vs maxAttempts, delay doubling up to
+ *    maxDelayMs (retry.ts:296-310, :494-501, :517-524); defaults 10 attempts / 5s initial /
+ *    30s max (retry.ts:20, :42-47).
+ *  - Retryable set: 429 and 5xx; "Explicitly do not retry 400" (retry.ts:193-199); transport
+ *    failures without a status are retryable (retry.ts:49-62, :174-189). Shared with the router
+ *    through classifyStreamError (router.ts) — one classifier, two consumers (gemini-cli's 499
+ *    is excluded there, documented deviation).
+ *  - Aborts pass through untouched (retry.ts:337-340); the backoff sleep itself is abortable
+ *    (delay.ts:22-48: timeout + abort listener, both cleared on settle).
+ *  - A server-suggested delay is a FLOOR on the next sleep (retry.ts:472-476
+ *    `Math.max(currentDelay, retryDelayMs)`); a suggestion beyond the cap is terminal — no wait,
+ *    immediate fallback (googleQuotaErrors.ts:120 MAX_RETRYABLE_DELAY_SECONDS, :286-289). Here
+ *    the suggestion is the HTTP Retry-After header (RFC 9110 §10.2.3: delay-seconds or
+ *    HTTP-date), OpenAI's retry-after-ms, or Anthropic's ratelimit-reset timestamps, all recorded
+ *    by stream-errors.ts; the cap is the per-invocation total budget and the run's own deadline.
+ *  - Deviations: FULL jitter — delay = U[0,1) × min(max, base·2ⁿ) (AWS "Exponential Backoff And
+ *    Jitter") instead of gemini-cli's ±30% around the current delay (retry.ts:494-495) or +20%
+ *    over the server floor (:478): fewer synchronized retries, and the schedule is pinnable with
+ *    an injected random. A total wall-clock cap per invocation (gemini-cli has none): with a
+ *    fallback chain every candidate pays the retry budget, so it is kept short. No content-based
+ *    retry (:314-328), no quota classification / fallback dialog (:342-420) — the router owns
+ *    model fallback. A thrown inner stream is folded into an error turn (never-throw) but NOT
+ *    retried: a seam-contract violation is a harness bug, not a provider outcome.
+ *  - Per-invocation state only: attempt counter and deadline live inside one generator run;
+ *    nothing is remembered across calls (unlike the router's sticky switch).
+ *  - IDEMPOTENCY (2026-09-04): a retry is taken only while NOTHING has been streamed to the consumer.
+ *    Once a text or reasoning delta has gone out, a failure ends the turn — with the partial text kept as
+ *    the turn's parts and an error that says so — because a re-drive would print a second answer under
+ *    the first (the router applies the same rule to its chain advance). Deltas from a failed attempt that
+ *    streamed nothing cannot exist, so the "pass through live" rule and this one never meet.
+ *
+ *  Env (retryOptionsFromEnv, read once by cli/runtime.ts):
+ *  - ROVECODE_RETRY_MAX      retries after the first attempt; 0 disables. Default 3 (→ 4 attempts;
+ *                        upstream 10 attempts — a fallback chain multiplies attempts per candidate).
+ *  - ROVECODE_RETRY_BASE_MS  cap of the first backoff in ms. Default 1000 (upstream 5000; full jitter
+ *                        halves the expected wait — ~0.5 s, 1 s, 2 s, 4 s expected).
+ *  Fixed: max backoff 20 s, total budget 60 s per invocation, and never past StreamOptions.deadlineAt
+ *  (the run's --max-seconds clock). */
+
+import type { AssistantTurn, ModelRef, StreamEvent, StreamFn } from "../core/types.ts";
+import { classifyStreamError } from "./router.ts";
+import { httpErrorMeta, providerMessage } from "./stream-errors.ts";
+
+export const DEFAULT_MAX_RETRIES = 3;
+export const DEFAULT_BASE_MS = 1_000;
+export const DEFAULT_MAX_DELAY_MS = 20_000;
+export const DEFAULT_TOTAL_MS = 60_000;
+
+export interface RetryNote {
+  model: ModelRef;
+  /** Attempts made so far (the one that just failed); the retry about to happen is attempt+1. */
+  attempt: number;
+  /** attempts the policy allows in total (maxRetries + 1) — for "(2/4)" */
+  maxAttempts: number;
+  delayMs: number;
+  /** The failed turn's error text, e.g. "HTTP 429: ...". */
+  reason: string;
+  /** the HTTP status when the failure was a response; undefined for a transport failure */
+  status?: number;
+  /** Parsed server wait hint (Retry-After / retry-after-ms / anthropic-ratelimit-*-reset) when the error turn carried one. */
+  retryAfterMs?: number;
+}
+
+/** why the wrapper stopped retrying a retryable failure */
+export type GiveUpWhy = "attempts" | "budget" | "deadline";
+export interface GiveUpNote extends Omit<RetryNote, "delayMs"> { why: GiveUpWhy; delayMs?: number }
+
+export interface RetryOptions {
+  /** Retries after the first attempt (ROVECODE_RETRY_MAX). 0 = never retry. */
+  maxRetries?: number;
+  /** Cap of the first backoff, doubling per attempt (ROVECODE_RETRY_BASE_MS). */
+  baseMs?: number;
+  /** Ceiling for the doubling backoff term. */
+  maxDelayMs?: number;
+  /** Wall-clock budget per invocation incl. sleeps; a wait that would end past it is not taken. */
+  totalMs?: number;
+  /** Retry visibility — a note-style callback, not a StreamEvent (grammar is shared/untouchable). */
+  onRetry?: (note: RetryNote) => void;
+  /** the last word: a retryable failure that will not be retried (attempts, budget or the run's deadline) */
+  onGiveUp?: (note: GiveUpNote) => void;
+  /** Test seams: abortable sleep, jitter source, clock (epoch ms — also anchors HTTP-date). */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  random?: () => number;
+  now?: () => number;
+}
+
+/** Abortable sleep (delay.ts:22-48 shape) on a REF'D setTimeout — Bun unrefs AbortSignal.timeout
+ *  timers, so a sleep built on one could not hold the process/test runner — plus an abort
+ *  listener; whichever settles first clears the other. Resolves (never rejects) on abort: the
+ *  caller re-checks signal.aborted. */
+export function sleepMs(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal?.aborted) { resolve(); return; }
+    const settle = (): void => { clearTimeout(timer); signal?.removeEventListener("abort", settle); resolve(); };
+    const timer = setTimeout(settle, ms);
+    signal?.addEventListener("abort", settle, { once: true });
+  });
+}
+
+/** RFC 9110 §10.2.3 Retry-After: delay-seconds (non-negative; a fractional value is tolerated)
+ *  or an HTTP-date, converted to ms from `now` (a past date → 0). Unparseable → undefined. */
+export function parseRetryAfter(value: string | undefined, now: number): number | undefined {
+  const v = value?.trim();
+  if (!v) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(v)) return Math.round(Number(v) * 1000);
+  const at = Date.parse(v);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+}
+
+/** the server's wait hint for a failed turn, whichever header it used: the largest of Retry-After,
+ *  retry-after-ms and the Anthropic ratelimit reset timestamps (RFC 3339) — the longest wait is the
+ *  one that will actually clear the limit */
+export function serverWaitMs(turn: AssistantTurn, now: number): number | undefined {
+  const meta = httpErrorMeta(turn);
+  if (!meta) return undefined;
+  const hints: number[] = [];
+  const ra = parseRetryAfter(meta.retryAfter, now);
+  if (ra !== undefined) hints.push(ra);
+  if (meta.retryAfterMs !== undefined && /^\d+(?:\.\d+)?$/.test(meta.retryAfterMs.trim())) hints.push(Math.round(Number(meta.retryAfterMs)));
+  if (meta.resetAt !== undefined) { const at = Date.parse(meta.resetAt); if (!Number.isNaN(at)) hints.push(Math.max(0, at - now)); }
+  return hints.length ? Math.max(...hints) : undefined;
+}
+
+/** Env knobs (header). Blank/invalid/out-of-range values fall back to the defaults;
+ *  ROVECODE_RETRY_MAX=0 is honored (retry off). */
+export function retryOptionsFromEnv(env: Record<string, string | undefined> = process.env): RetryOptions {
+  return { maxRetries: envInt(env.ROVECODE_RETRY_MAX, DEFAULT_MAX_RETRIES, 0), baseMs: envInt(env.ROVECODE_RETRY_BASE_MS, DEFAULT_BASE_MS, 1) };
+}
+
+function envInt(raw: string | undefined, dflt: number, min: number): number {
+  if (raw === undefined || raw.trim() === "") return dflt;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= min ? Math.floor(n) : dflt;
+}
+
+const errorTurn = (error: string): AssistantTurn => ({ parts: [], stopReason: "error", usage: { input: 0, output: 0 }, error });
+
+// ---------- the human's words ----------
+
+/** one noun phrase per failure class — what the notice and the give-up line lead with */
+export function failureWord(status: number | undefined, error: string): string {
+  if (status === 429) return "rate limited";
+  if (status === 529 || status === 503) return "overloaded";
+  if (status !== undefined && status >= 500) return `server error (HTTP ${status})`;
+  if (status !== undefined) return `HTTP ${status}`;
+  if (/^no response from /.test(error)) return "no response";
+  return "connection failed";
+}
+
+const fmtSeconds = (ms: number): string => { const s = ms / 1000; return `${s >= 10 ? Math.round(s) : Math.round(s * 10) / 10} s`; };
+
+/** "anthropic: overloaded — retrying in 4 s (2/4)" */
+export function describeRetry(n: RetryNote): string {
+  return `${n.model.provider}: ${failureWord(n.status, n.reason)} — retrying in ${fmtSeconds(n.delayMs)} (${n.attempt + 1}/${n.maxAttempts})`;
+}
+
+/** "anthropic: overloaded (HTTP 529) — gave up after 4 attempts: Overloaded" */
+export function describeGiveUp(n: GiveUpNote): string {
+  const why = n.why === "attempts" ? `gave up after ${n.attempt} attempt${n.attempt === 1 ? "" : "s"}`
+    : n.why === "deadline" ? `not retried: the run's time limit is closer than the ${fmtSeconds(n.delayMs ?? 0)} wait`
+    : `not retried: the ${fmtSeconds(n.delayMs ?? 0)} wait would pass the retry budget`;
+  const status = n.status !== undefined && !/HTTP/.test(failureWord(n.status, n.reason)) ? ` (HTTP ${n.status})` : "";
+  const msg = providerMessage(n.reason);
+  return `${n.model.provider}: ${failureWord(n.status, n.reason)}${status} — ${why}${msg ? `: ${msg}` : ""}`;
+}
+
+/** Wrap a StreamFn: a retryable failed turn (429 / 5xx / transport, never 400, never abort, never after
+ *  a delta went out) is re-driven against the SAME model with the same args after an abortable
+ *  full-jitter backoff, until it succeeds, a non-retryable outcome lands, or a cap (attempts / total
+ *  budget / the run's deadline) stops it — then the LAST turn is yielded untouched so the router sees
+ *  the genuine provider error. Never throws (ADR-003). */
+export function withRetry(inner: StreamFn, opts: RetryOptions = {}): StreamFn {
+  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const baseMs = opts.baseMs ?? DEFAULT_BASE_MS;
+  const maxDelayMs = opts.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const totalMs = opts.totalMs ?? DEFAULT_TOTAL_MS;
+  const sleep = opts.sleep ?? sleepMs;
+  const random = opts.random ?? Math.random;
+  const now = opts.now ?? Date.now;
+  return async function* (model, messages, options): AsyncGenerator<StreamEvent> {
+    const startedAt = now();
+    for (let attempt = 1; ; attempt++) {
+      let turn: AssistantTurn | null = null;
+      let streamed = ""; // every text delta this attempt let through — the answer the consumer has already seen
+      try {
+        for await (const ev of inner(model, messages, options)) {
+          if (ev.type === "turn") turn = ev.turn;
+          else { if (ev.type === "text_delta") streamed += ev.text; else if (ev.type === "reasoning_delta") streamed ||= " "; yield ev; } // deltas pass through live (header)
+        }
+      } catch (e) {
+        yield { type: "turn", turn: errorTurn(e instanceof Error ? e.message : String(e)) }; // folded, not retried (header)
+        return;
+      }
+      if (turn === null) { yield { type: "turn", turn: errorTurn("stream ended without a terminal turn") }; return; }
+      const meta = httpErrorMeta(turn);
+      const status = meta?.status ?? classifyStreamError(turn.error).status;
+      // retry.ts:337-340: aborts never retry; 400/4xx-non-429 and non-error turns stand as they are
+      if (turn.stopReason !== "error" || options?.signal?.aborted === true || !classifyStreamError(turn.error).retryable) {
+        yield { type: "turn", turn };
+        return;
+      }
+      if (streamed.length > 0) {
+        // idempotency (header): part of the answer is on the screen — end the turn, keep that text as the
+        // turn's parts (the loop stores it and the summary shows it above the error), say why no retry
+        const kept = streamed.trim().length > 0 && turn.parts.length === 0 ? [{ kind: "text" as const, text: streamed }] : turn.parts;
+        yield { type: "turn", turn: { ...turn, parts: kept, error: `${turn.error ?? "provider stream failed"} — the connection dropped after part of the answer had arrived; not retried, a retry would repeat it` } };
+        return;
+      }
+      const note = { model, attempt, maxAttempts: maxRetries + 1, reason: turn.error ?? "error", ...(status !== undefined ? { status } : {}) };
+      // retries off (ROVECODE_RETRY_MAX=0): nothing was ever going to be retried, so there is no giving up to announce
+      if (attempt > maxRetries) { if (maxRetries > 0) opts.onGiveUp?.({ ...note, why: "attempts" }); yield { type: "turn", turn }; return; }
+      const retryAfterMs = serverWaitMs(turn, now());
+      const cap = Math.min(maxDelayMs, baseMs * 2 ** (attempt - 1));
+      const delayMs = Math.max(Math.round(random() * cap), retryAfterMs ?? 0); // full jitter, server floor (retry.ts:476)
+      const withHint = retryAfterMs !== undefined ? { retryAfterMs } : {};
+      // budget: a wait that would end past the deadline is not taken — the failure surfaces now
+      // and the router may advance at once (googleQuotaErrors.ts:286-289 shape)
+      if (now() - startedAt + delayMs > totalMs) { opts.onGiveUp?.({ ...note, ...withHint, delayMs, why: "budget" }); yield { type: "turn", turn }; return; }
+      // the run's own clock (--max-seconds): a wait that ends past it would only be cut off at the turn boundary
+      if (options?.deadlineAt !== undefined && now() + delayMs > options.deadlineAt) { opts.onGiveUp?.({ ...note, ...withHint, delayMs, why: "deadline" }); yield { type: "turn", turn }; return; }
+      opts.onRetry?.({ ...note, delayMs, ...withHint });
+      await sleep(delayMs, options?.signal);
+      if (options?.signal?.aborted) { yield { type: "turn", turn }; return; } // abort landed during backoff: last turn stands
+    }
+  };
+}