rovecode 0.3.2

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
+    }
+  };
+}

package/src/providers/router.ts

@@ -0,0 +1,294 @@
+/** Role router + provider fallback chains (port #14). ModelRef resolver + StreamFn wrapper —
+ *  NO second agent loop (ADR-003): the wrapper makes one bounded pass over a chain's remaining
+ *  candidates inside a single stream invocation; same-model retry/backoff is the port-#23
+ *  withRetry wrapper, which sits INSIDE this wrap (retries exhaust before the chain advances).
+ *
+ *  Role table (oh-my-pi, MIT — research/source_snapshots/can1357-oh-my-pi):
+ *  - Role names ported as the documented SUBSET default/smol/plan/commit/task of OMP's
+ *    ModelRole union (packages/coding-agent/src/config/model-roles.ts:22-32; full set adds
+ *    slow/vision/designer/tiny/advisor). Config shape mirrors OMP's `modelRoles` record
+ *    (config/settings-schema.ts:668, :6315 — Record<role, selector>).
+ *  - Missing/unknown role → the "default" role (config/model-resolver.ts:1017
+ *    DEFAULT_MODEL_ROLE; configured-value-else-defaults resolution :1155-1189).
+ *  - Precedence: explicit request selector > configured role chain > default chain, per
+ *    OMP's resolveEffectiveAgentModelSelection (model-resolver.ts:1229-1261
+ *    requestModel > settingsOverride > agentModel > default).
+ *  - Selector grammar: "provider/model" split on the FIRST slash so model ids keep their own
+ *    slashes (model-resolver.ts:214-216); comma-separated ordered candidate lists
+ *    (model-resolver.ts:1051-1055 normalizeModelPatternList); per-role ordered chains as in
+ *    OMP's priority.json:2-23 (rolePriorityDefaults, model-resolver.ts:1110-1113).
+ *  - NOT ported: OMP's fuzzy/glob matching, thinking-level suffixes, custom role aliases and
+ *    alias cycle guard (rovecode chains are flat ModelRefs — no aliases, so no cycles).
+ *
+ *  Fallback chains (gemini-cli, Apache-2.0 @0bd1d43 — research/source_snapshots/
+ *  google-gemini-gemini-cli, packages/core/src):
+ *  - Ordered chain, "the first model in the chain is the primary model"
+ *    (availability/modelPolicy.ts:52-56 ModelPolicyChain).
+ *  - Trigger conditions ported from utils/retry.ts isRetryableError (:170-209): advance on
+ *    HTTP 429 or 5xx; NEVER on 400 (:193-194 "Explicitly do not retry 400"); non-HTTP
+ *    transport failures (fetch failed / network codes / incomplete stream JSON) are
+ *    retryable (:49-62, :122-123, :141-147, :180-189). gemini-cli additionally retries 499;
+ *    the bar pins 429/5xx, so 499 is deliberately NOT retryable here (documented deviation).
+ *  - Aborts never advance the chain (retry.ts:337-339 rethrows AbortError untouched).
+ *  - On failure the handler picks the FIRST AVAILABLE later candidate and never falls back
+ *    to the failed model itself (fallback/handler.ts:59-76); the switch is STICKY for the
+ *    session via activateFallbackMode (handler.ts:163-169). Sticky here = per wrapped
+ *    StreamFn, reset when a chain exhausts (rovecode simplification: gemini-cli instead tracks
+ *    per-model health and marks models healthy again on success, retry.ts:330-334).
+ *  - gemini-cli retries the new model immediately (retry.ts:404, :459 `attempt = 0; continue`)
+ *    inside its retryWithBackoff loop; rovecode tries each candidate ONCE per invocation — no
+ *    delays, no attempt reset (ADR-003: no second loop). Status is read from the seam's
+ *    error TEXT ("HTTP <status>: <body>" — built by src/providers/stream-errors.ts httpErrorTurn), the same
+ *    message-sniffing fallback gemini-cli itself uses (retry.ts:553-558).
+ *  - Mid-stream failure: gemini-cli re-streams and signals the consumer with a RETRY event
+ *    (core/geminiChat.ts:655-679). Rovecode's StreamEvent grammar (core/types.ts:47-50) has no
+ *    such variant and is shared/untouchable, so forwarded text_delta events from a failed
+ *    attempt simply stand; canonical content is the terminal turn only (core/loop.ts
+ *    collectTurn:219-226), so the final message is never corrupted. The "note" on each
+ *    advance is therefore an onNote CALLBACK, not a StreamEvent.
+ *  - Exhausted chain → terminal turn with stopReason "error"; this wrapper NEVER throws
+ *    (ADR-003 seam contract), even when the wrapped stream does.
+ *  - A SINGLE-candidate chain has nothing to advance to: a retryable failure is yielded
+ *    UNTOUCHED — no exhausted-rewrite, no note — so plain provider errors survive verbatim
+ *    (R2 #14 LOW/MED-4).
+ *  - A requested model outside every configured chain is a passthrough singleton, unless
+ *    `looseFallback` is set (runtime sets it when chains are explicit user config): then the
+ *    request is PREPENDED to the default chain — gemini-cli's shape, where "the first model
+ *    in the chain is the primary model" is whatever was requested and configured fallbacks
+ *    follow (R2 #14 MED-3).
+ *  - The candidate that produced each terminal turn is recorded per turn object (servedBy)
+ *    so the loop stamps Message.origin with the model that SERVED, not the one it asked
+ *    for (R2 #14 HIGH-2). */
+
+import type { AssistantTurn, ModelRef, StreamFn, StreamEvent, TokenUsage } from "../core/types.ts";
+
+// ---------- roles (OMP subset, documented above) ----------
+
+export type ModelRole = "default" | "smol" | "plan" | "commit" | "task";
+
+export const MODEL_ROLES: readonly ModelRole[] = ["default", "smol", "plan", "commit", "task"];
+
+export interface RouterNote {
+  /** Chain identity: role name when the model belongs to a configured role chain,
+   *  else "provider/model" of the loose (passthrough) model. */
+  chain: string;
+  from: ModelRef;
+  /** Next candidate, or null when this failure exhausted the chain. */
+  to: ModelRef | null;
+  /** The failed turn's error text, e.g. "HTTP 429: ...". */
+  reason: string;
+}
+
+export interface RouterConfig {
+  /** Role → primary ModelRef or ordered fallback chain (first = primary,
+   *  gemini-cli modelPolicy.ts:52-56). `default` is required; other roles optional. */
+  roles: Partial<Record<ModelRole, ModelRef | readonly ModelRef[]>> & { default: ModelRef | readonly ModelRef[] };
+  /** Keep fallback switches for later calls on the same wrapped stream (gemini-cli
+   *  activateFallbackMode, handler.ts:163-169). Default true; exhaustion resets. */
+  sticky?: boolean;
+  /** Treat the default chain as the fallback pool for models outside EVERY configured
+   *  chain: the requested model is prepended as the primary (header: MED-3). Default
+   *  false — a synthesized single-model default (no explicit chain config) must not
+   *  drag loose models onto a placeholder ref. */
+  looseFallback?: boolean;
+  /** Advance notification — see header for why this is a callback, not a StreamEvent. */
+  onNote?: (note: RouterNote) => void;
+}
+
+export interface Router {
+  /** Full ordered chain for a role; unknown/unconfigured roles get the default chain. */
+  chain(role: string): readonly ModelRef[];
+  /** Primary ModelRef for a role. `explicit` (request selector or ModelRef) wins over the
+   *  role table — OMP request>config precedence (model-resolver.ts:1229-1261). */
+  resolve(role: string, explicit?: string | ModelRef): ModelRef;
+  /** Wrap a StreamFn with chain-advance-on-failure. Non-turn events pass through live. */
+  wrap(stream: StreamFn): StreamFn;
+}
+
+// ---------- selector parsing (OMP model-resolver.ts:214-216, :1051-1055) ----------
+
+/** "provider/model" split on the FIRST slash (model ids keep their own slashes, e.g.
+ *  "kaesra/zai-org/glm-5.3-flash"); no slash → model on `defaultProvider`. */
+export function parseModelRef(selector: string, defaultProvider: string): ModelRef {
+  const s = selector.trim();
+  const slash = s.indexOf("/");
+  if (slash <= 0) return { provider: defaultProvider, model: s };
+  return { provider: s.slice(0, slash), model: s.slice(slash + 1) };
+}
+
+/** Comma-separated ordered candidate list → ModelRef chain. */
+export function parseModelChain(selectors: string, defaultProvider: string): ModelRef[] {
+  return selectors
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => parseModelRef(s, defaultProvider));
+}
+
+const ROLE_ENV: Record<ModelRole, string> = {
+  default: "ROVECODE_MODEL_DEFAULT",
+  smol: "ROVECODE_MODEL_SMOL",
+  plan: "ROVECODE_MODEL_PLAN",
+  commit: "ROVECODE_MODEL_COMMIT",
+  task: "ROVECODE_MODEL_TASK",
+};
+
+/** Role table from env (ROVECODE_MODEL_DEFAULT/SMOL/PLAN/COMMIT/TASK, each a comma-separated
+ *  "provider/model" chain). Unset default → [fallback] (the provider-derived model). */
+export function roleTableFromEnv(
+  fallback: ModelRef,
+  env: Record<string, string | undefined> = process.env,
+): RouterConfig["roles"] {
+  const roles: Partial<Record<ModelRole, ModelRef[]>> = {};
+  for (const role of MODEL_ROLES) {
+    const raw = env[ROLE_ENV[role]];
+    if (raw && raw.trim().length > 0) {
+      const chain = parseModelChain(raw, fallback.provider);
+      if (chain.length > 0) roles[role] = chain;
+    }
+  }
+  return { ...roles, default: roles.default ?? [fallback] };
+}
+
+// ---------- failure classification (gemini-cli retry.ts:170-209; rovecode stream.ts:78,109,171) ----------
+
+export interface StreamErrorClass {
+  /** HTTP status parsed from the seam's "HTTP <status>: ..." error text, if present. */
+  status?: number;
+  /** Advance-the-chain eligible: 429, 5xx, or a non-HTTP transport failure. */
+  retryable: boolean;
+}
+
+export function classifyStreamError(error: string | undefined): StreamErrorClass {
+  const m = /^HTTP (\d{3})\b/.exec(error ?? "");
+  if (m) {
+    const status = Number(m[1]);
+    return { status, retryable: status === 429 || (status >= 500 && status < 600) };
+  }
+  // `config: …` (providers/registry.ts dispatcher: unknown provider, missing key) — a configuration
+  // mistake neither a retry nor the next chain candidate can fix; the human can. Never retryable.
+  if ((error ?? "").startsWith("config: ")) return { retryable: false };
+  // No HTTP prefix → the fetch itself failed (network/SSL/parse) — retryable per
+  // gemini-cli retry.ts:49-62,122-123,141-147,180-189.
+  return { retryable: true };
+}
+
+// ---------- served-model tagging (R2 #14 HIGH-2) ----------
+
+/** ModelRef that actually produced a terminal turn, keyed on the turn object itself — a
+ *  WeakMap side-channel because the StreamEvent grammar (core/types.ts:49-52) is shared/
+ *  untouchable (no new event variant, no new turn field). Per-invocation by construction:
+ *  each terminal turn is a distinct object. Unwrapped streams never mark their turns, so
+ *  consumers fall back to the model they asked for. */
+const SERVED = new WeakMap<AssistantTurn, ModelRef>();
+
+/** The chain candidate that served `turn`, when the router produced it. loop.ts stamps
+ *  Message.origin with this so /cost prices the model that ANSWERED after a fallback. */
+export function servedBy(turn: AssistantTurn): ModelRef | undefined {
+  return SERVED.get(turn);
+}
+
+// ---------- router ----------
+
+const sameRef = (a: ModelRef, b: ModelRef): boolean => a.provider === b.provider && a.model === b.model;
+const refKey = (m: ModelRef): string => `${m.provider}/${m.model}`;
+const zeroUsage = (): TokenUsage => ({ input: 0, output: 0 });
+const errorTurn = (error: string): AssistantTurn => ({ parts: [], stopReason: "error", usage: zeroUsage(), error });
+
+export function createRouter(config: RouterConfig): Router {
+  const table = new Map<ModelRole, readonly ModelRef[]>();
+  for (const role of MODEL_ROLES) {
+    const entry = config.roles[role];
+    if (!entry) continue;
+    const chain: readonly ModelRef[] = Array.isArray(entry) ? entry : [entry];
+    if (chain.length > 0) table.set(role, chain);
+  }
+  const defaults = table.get("default");
+  // Factory-time misconfiguration (empty default chain) is a programmer error and may
+  // throw; the ADR-003 never-throw contract applies to the stream path below.
+  if (!defaults) throw new Error("router: roles.default must contain at least one ModelRef");
+
+  const chainFor = (role: string): readonly ModelRef[] => table.get(role as ModelRole) ?? defaults;
+
+  /** Chain containing `model`: prefer the role whose chain HEAD is the model (that is what
+   *  resolve() hands the loop), else the first role chain containing it anywhere, else —
+   *  under `looseFallback` — the model PREPENDED to the default chain (header: MED-3; the
+   *  request stays the primary, configured models become its fallbacks), else a singleton
+   *  passthrough chain. Scan order = MODEL_ROLES order (deterministic). */
+  const locate = (model: ModelRef): { key: string; chain: readonly ModelRef[]; index: number } => {
+    let containing: { key: string; chain: readonly ModelRef[]; index: number } | null = null;
+    for (const role of MODEL_ROLES) {
+      const chain = table.get(role);
+      if (!chain) continue;
+      const idx = chain.findIndex((c) => sameRef(c, model));
+      if (idx === 0) return { key: role, chain, index: 0 };
+      if (idx > 0 && containing === null) containing = { key: role, chain, index: idx };
+    }
+    if (containing) return containing;
+    // model ∉ any chain (the scan above covered `default`), so the prepend never duplicates
+    const chain = config.looseFallback === true ? [model, ...defaults] : [model];
+    return { key: refKey(model), chain, index: 0 };
+  };
+
+  return {
+    chain: chainFor,
+
+    resolve(role: string, explicit?: string | ModelRef): ModelRef {
+      const chain = chainFor(role);
+      const head = chain[0]!; // chains in `table` are never empty
+      if (explicit !== undefined) {
+        return typeof explicit === "string" ? parseModelRef(explicit, head.provider) : explicit;
+      }
+      return head;
+    },
+
+    wrap(stream: StreamFn): StreamFn {
+      const sticky = config.sticky ?? true;
+      const survivors = new Map<string, number>(); // chain key → sticky start index
+      return async function* (model, messages, options): AsyncGenerator<StreamEvent> {
+        const { key, chain, index } = locate(model);
+        const start = sticky
+          ? Math.min(Math.max(index, survivors.get(key) ?? 0), chain.length - 1)
+          : index;
+        let last: AssistantTurn | null = null;
+        for (let i = start; i < chain.length; i++) {
+          const candidate = chain[i]!;
+          let turn: AssistantTurn | null = null;
+          let streamed = false; // any delta reached the consumer from THIS candidate
+          try {
+            for await (const ev of stream(candidate, messages, options)) {
+              if (ev.type === "turn") turn = ev.turn;
+              else { if (ev.type === "text_delta" || ev.type === "reasoning_delta") streamed = true; yield ev; } // deltas pass through live (header: mid-stream failure note)
+            }
+          } catch (e) {
+            // Defensive: the seam contract says streams never throw; if one does, keep the
+            // never-throw guarantee here by folding it into an error turn.
+            turn = errorTurn(e instanceof Error ? e.message : String(e));
+          }
+          const t: AssistantTurn = turn ?? errorTurn("stream ended without a terminal turn");
+          const aborted = options?.signal?.aborted === true; // retry.ts:337-339: aborts never advance
+          // chain.length === 1: nothing to advance to — surface the provider error untouched,
+          // no exhausted-rewrite, no note (header: LOW/MED-4).
+          // streamed: part of an answer already reached the screen — a re-drive on the next candidate would
+          // print a second answer under the first; the failure stands (retry.ts applies the same rule)
+          if (t.stopReason !== "error" || aborted || streamed || !classifyStreamError(t.error).retryable || chain.length === 1) {
+            SERVED.set(t, candidate); // header: HIGH-2 — this candidate produced the turn
+            yield { type: "turn", turn: t }; // success or non-retryable: NO advance
+            return;
+          }
+          last = t;
+          const next = i + 1 < chain.length ? chain[i + 1]! : null;
+          if (sticky && next !== null) survivors.set(key, i + 1); // handler.ts:163-169 sticky switch
+          config.onNote?.({ chain: key, from: candidate, to: next, reason: t.error ?? "error" });
+        }
+        if (sticky) survivors.delete(key); // exhausted: reset so recovered models get retried
+        const tried = chain.length - start;
+        const exhausted = errorTurn(
+          `model chain '${key}' exhausted (${tried} candidate${tried === 1 ? "" : "s"} failed); last: ${last?.error ?? "unknown error"}`,
+        );
+        SERVED.set(exhausted, chain[chain.length - 1]!); // last candidate attempted (status honesty)
+        yield { type: "turn", turn: exhausted };
+      };
+    },
+  };
+}

package/src/providers/sse.ts

@@ -0,0 +1,26 @@
+/** SSE line reader shared by the streaming adapters (moved VERBATIM out of stream.ts — aion port #75 — so a
+ *  second wire (the Codex Responses wire, not in this build yet) can import it without importing stream.ts).
+ *  Yields every `data:` payload except the `[DONE]` sentinel; `event:` lines, comments and blank lines
+ *  are skipped — the OpenAI Responses stream names its event in the payload's `type` field, so the
+ *  `event:` line carries nothing the consumer needs (codex codex-api/src/sse/responses.rs:843-845 fixtures
+ *  pair `event:` + `data:` lines the same way). */
+
+export async function* sseLines(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  const reader = body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += dec.decode(value, { stream: true });
+    const lines = buf.split("\n");
+    buf = lines.pop() ?? "";
+    for (const l of lines) {
+      const t = l.trim();
+      if (t.startsWith("data:")) {
+        const payload = t.slice(5).trim();
+        if (payload && payload !== "[DONE]") yield payload;
+      }
+    }
+  }
+}