rovecode 0.3.3 → 0.4.0-beta.2

package/src/providers/responses.ts

@@ -1,209 +0,0 @@
-/** OpenAI Responses API wire (aion port #75, brought over 2026-09-07) — the second OpenAI adapter beside stream.ts's
- *  /chat/completions pair. ADR-003 seam: ONE StreamFn, errors cross as stopReason "error" / "aborted", never a throw.
- *  Hand-rolled fetch + SSE exactly like stream.ts (no `openai` npm dependency). providers/wire-select.ts decides per
- *  call which of the two wires a request takes; this module never imports stream.ts at runtime (it shares sse.ts,
- *  stream-errors.ts, usage.ts, thinking.ts, catalog.ts and wire-responses.ts with it).
- *
- *  Request: POST <baseUrl>/responses `{ model, instructions?, input, tools?, stream: true, store: false,
- *  max_output_tokens?, reasoning? }`. `max_output_tokens` is max(cap, 16) — cap = model.maxTokens, the stream.ts rule
- *  — and is OMITTED on the ChatGPT Codex backend (a URL containing chatgpt.com/backend-api; pi's codex path never
- *  sends it), which also gets the `OpenAI-Beta: responses=experimental` + `originator: rovecode` headers.
- *  `reasoning: { effort, summary: "auto" }` is the Responses spelling of rovecode's ONE thinking dial
- *  (providers/thinking.ts thinkingPlan — the same dialect table stream.ts spreads as `reasoning_effort`; auto sends
- *  nothing, a model the catalog or the dialect marks without a reasoning mode sends nothing).
- *  NOT brought over: `include: ["reasoning.encrypted_content"]` and the reasoning item as a message part — rovecode
- *  has no reasoning MessagePart to replay it from (wire-responses.ts header), so asking the provider for encrypted
- *  content we would then discard is cost without product. Reasoning TEXT still streams live as reasoning_delta.
- *  Pattern sources, MIT — earendil-works/pi packages/ai/src/api: openai-responses.ts:290-302 (store:false,
- *  stream:true, max_output_tokens), :32-33 (the 16-token floor the API enforces), :323-332 (reasoning effort +
- *  summary "auto"); openai-codex-responses.ts:549-556 (`instructions`), :45 + :633-639 (chatgpt.com/backend-api →
- *  codex/responses), :1607-1609 + :1622 (chatgpt-account-id, originator, `OpenAI-Beta: responses=experimental`,
- *  accept text/event-stream); openai-responses-shared.ts:440,:463 (output slots keyed by output_index), :597-668
- *  (the deltas), :680-739 (output_item.done finalises a slot: message text authoritative, function_call arguments
- *  parsed), :757-759 (a stream without a terminal event is an error), :762-792 (stop mapping), :592-594 (a tool call
- *  overrides a completed stop), :742-755 (`<code>: <message>` for response.failed / error events).
- *  Pattern source, Apache-2.0 at pattern level (no code copied) — openai/codex: codex-rs/codex-api/src/sse/
- *  responses.rs:357-518 (the event set a client consumes; :843-845 fixtures pair `event:` and `data:` lines),
- *  codex-rs/model-provider-info/src/lib.rs:40 (CHATGPT_CODEX_BASE_URL), codex-rs/core/src/client.rs:688 (an
- *  `originator` header on every request — the value is `rovecode` here; codex's own OpenAI-Beta value is
- *  websocket-only, so `responses=experimental` is pi's). NOTICE entry: THIRD_PARTY_NOTICES.md, `## openai/codex`.
- *  NOT ported: `previous_response_id`, `prompt_cache_key` / `prompt_cache_retention`, `text.verbosity`,
- *  `service_tier`, `parallel_tool_calls`, `tool_choice`, strict / grammar / custom tools, developer-role items,
- *  the websocket and zstd transports, pi's retry loop (rovecode's withRetry + router classify the error turn as
- *  for chat completions) and codex's error taxonomy. Selection is static — no runtime 404 → chat re-issue.
- *
- *  Events (`data:` payloads through sse.ts; `event:` lines are ignored — `type` names the event):
- *  `response.output_text.delta` / `response.refusal.delta` → text_delta (and the abort-salvage buffer);
- *  `response.reasoning_summary_text.delta` / `response.reasoning_text.delta` → reasoning_delta — NEVER into the
- *  text buffer, never a text part (`…summary_part.done` → one "\n\n" reasoning_delta);
- *  `response.function_call_arguments.delta` accumulates per output_index (a tool_call_delta once the slot knows
- *  its call id and name); `response.output_item.done` finalises the slot (a reasoning item finalises to nothing);
- *  `response.completed` → tool_use when a tool_call part exists, else end_turn; `response.incomplete` → length for
- *  max_output_tokens, else error naming the reason; `response.failed` / `error` → error "<code>: <message>"; no
- *  terminal event → error. Usage: `response.usage` through core/usage.ts normalizeUsage (input_tokens −
- *  input_tokens_details.cached_tokens, cacheRead; reasoning_tokens are not carried — TokenUsage has no field for
- *  them and normalizeUsage does not expose them). Non-2xx → httpErrorTurn (status + Retry-After for withRetry / the
- *  router); a thrown fetch or abort → failedTurn (an aborted turn keeps the streamed text, never a tool_call
- *  fragment). No header, token or account id ever reaches an error text or an event (oauth/common.ts hygiene rule). */
-
-import type { AssistantTurn, Message, MessagePart, ModelRef, StopReason, StreamEvent, StreamFn, StreamOptions, TokenUsage } from "../core/types.ts";
-import { normalizeUsage } from "../core/usage.ts";
-import { supportsImages } from "./catalog.ts";
-import { sseLines } from "./sse.ts";
-import { failedTurn, fetchFirstByte, httpErrorTurn } from "./stream-errors.ts";
-import { thinkingPlan } from "./thinking.ts";
-import { toResponsesInput, toResponsesTools } from "./wire-responses.ts";
-
-/** the same opts as openaiCompatStreaming — oauth/seam.ts MakeStream is unchanged */
-export interface ResponsesAdapterOptions { baseUrl: string; apiKey: string; headers?: Record<string, string> }
-
-/** the API rejects max_output_tokens below 16 (pi openai-responses.ts:32-33) */
-export const RESPONSES_MIN_OUTPUT_TOKENS = 16;
-/** the ChatGPT Codex backend: no max_output_tokens, plus the two headers below (pi openai-codex-responses.ts) */
-export const CODEX_BACKEND = /chatgpt\.com\/backend-api/;
-export const CODEX_HEADERS: Readonly<Record<string, string>> = { "OpenAI-Beta": "responses=experimental", originator: "rovecode" };
-export const NO_TERMINAL_EVENT = "OpenAI Responses stream ended before a terminal response event";
-
-export interface ResponsesRequest { url: string; headers: Record<string, string>; body: Record<string, unknown> }
-
-/** the Responses spelling of the thinking dial: the word the OpenAI-compatible dialect would put in `reasoning_effort`
- *  (or OpenRouter's `reasoning.effort`) becomes `reasoning: { effort, summary: "auto" }`; nothing when the dial sends
- *  nothing (auto, a model without a reasoning mode, the catalog's `reasoning: false` stamp) */
-export function responsesReasoning(model: ModelRef): { reasoning?: { effort: string; summary: "auto" } } {
-  const fields = thinkingPlan(model, "openai").fields;
-  const nested = fields.reasoning as { effort?: unknown } | undefined;
-  const word = typeof fields.reasoning_effort === "string" ? fields.reasoning_effort : typeof nested?.effort === "string" ? nested.effort : undefined;
-  return word === undefined ? {} : { reasoning: { effort: word, summary: "auto" } };
-}
-
-/** URL, headers and body for one call (header rules); exported so the request shape is testable without fetch */
-export function responsesRequest(opts: ResponsesAdapterOptions, model: ModelRef, messages: Message[], options?: StreamOptions): ResponsesRequest {
-  const url = opts.baseUrl.replace(/\/$/, "") + "/responses";
-  const codex = CODEX_BACKEND.test(url);
-  const { instructions, input } = toResponsesInput(messages, { vision: supportsImages(model) !== false, model }); // port #34 vision gate (stream.ts wireOptions rule)
-  const cap = model.maxTokens;
-  const body: Record<string, unknown> = {
-    model: model.model,
-    ...(instructions !== undefined ? { instructions } : {}),
-    input,
-    ...(options?.tools?.length ? { tools: toResponsesTools(options.tools) } : {}),
-    stream: true,
-    store: false,
-    ...(cap && !codex ? { max_output_tokens: Math.max(cap, RESPONSES_MIN_OUTPUT_TOKENS) } : {}),
-    ...responsesReasoning(model),
-  };
-  const headers: Record<string, string> = { "content-type": "application/json", accept: "text/event-stream", ...(codex ? CODEX_HEADERS : {}), ...opts.headers, authorization: `Bearer ${opts.apiKey}` };
-  return { url, headers, body };
-}
-
-// ---------- SSE state ----------
-
-type Slot = { kind: "message"; text: string } | { kind: "function_call"; callId: string; name: string; args: string } | { kind: "reasoning" };
-interface Item { type?: string; id?: string; call_id?: string; name?: string; arguments?: string; content?: { type?: string; text?: string; refusal?: string }[]; summary?: { text?: string }[] }
-interface Event {
-  type?: string; output_index?: number; delta?: string; arguments?: string; item?: Item; code?: string; message?: string;
-  response?: { usage?: unknown; incomplete_details?: { reason?: string } | null; error?: { code?: string; message?: string } | null };
-}
-
-function newSlot(item: Item | undefined): Slot | undefined {
-  if (item?.type === "message") return { kind: "message", text: "" };
-  if (item?.type === "function_call") return { kind: "function_call", callId: item.call_id ?? "", name: item.name ?? "", args: item.arguments ?? "" };
-  if (item?.type === "reasoning") return { kind: "reasoning" };
-  return undefined;
-}
-
-/** the part an `output_item.done` item finalises to (pi shared.ts:680-739); undefined for an empty message and for a
- *  reasoning item (no reasoning MessagePart here — header) */
-function finishedPart(item: Item, slot: Slot | undefined, index: number): MessagePart | undefined {
-  if (item.type === "message") {
-    const text = item.content ? item.content.map((c) => (c.type === "refusal" ? c.refusal ?? "" : c.text ?? "")).join("") : slot?.kind === "message" ? slot.text : "";
-    return text ? { kind: "text", text } : undefined;
-  }
-  if (item.type === "function_call") {
-    const fc = slot?.kind === "function_call" ? slot : undefined;
-    const raw = item.arguments ?? fc?.args ?? "";
-    let args: unknown = {};
-    try { args = JSON.parse(raw || "{}"); } catch { args = { _raw: raw }; }
-    return { kind: "tool_call", id: item.call_id || fc?.callId || item.id || `fc${index}`, tool: item.name || fc?.name || "unknown", args };
-  }
-  return undefined;
-}
-
-/** the same normalization the stream.ts adapters apply (cached share subtracted, zero fields dropped) */
-function turnUsage(raw: unknown): TokenUsage {
-  const u = normalizeUsage(raw);
-  return { input: u.input, output: u.output, cacheRead: u.cacheRead || undefined, cacheWrite: u.cacheWrite || undefined };
-}
-
-// ---------- the adapter ----------
-
-export function openaiResponsesStream(opts: ResponsesAdapterOptions): StreamFn {
-  return async function* (model: ModelRef, messages: Message[], options?: StreamOptions): AsyncGenerator<StreamEvent> {
-    let turn: AssistantTurn;
-    let buffer = ""; // text deltas only — the abort salvage (failedTurn); reasoning deltas never land here
-    try {
-      const req = responsesRequest(opts, model, messages, options);
-      const res = await fetchFirstByte(req.url, { method: "POST", headers: req.headers, body: JSON.stringify(req.body), signal: options?.signal });
-      if (!res.ok || !res.body) {
-        yield { type: "turn", turn: await httpErrorTurn(res) }; // status + Retry-After recorded for withRetry (stream-errors.ts)
-        return;
-      }
-      const slots = new Map<number, Slot>();
-      const parts = new Map<number, MessagePart>();
-      let usage: TokenUsage = { input: 0, output: 0 };
-      let terminal: { stop: StopReason; error?: string } | undefined;
-      for await (const line of sseLines(res.body)) {
-        const ev = JSON.parse(line) as Event;
-        const idx = ev.output_index ?? 0;
-        switch (ev.type) {
-          case "response.output_item.added": { const s = newSlot(ev.item); if (s) slots.set(idx, s); break; }
-          case "response.output_text.delta":
-          case "response.refusal.delta": {
-            if (!ev.delta) break;
-            const s: Slot = slots.get(idx) ?? { kind: "message", text: "" };
-            if (s.kind === "message") { s.text += ev.delta; slots.set(idx, s); }
-            buffer += ev.delta;
-            yield { type: "text_delta", text: ev.delta };
-            break;
-          }
-          case "response.reasoning_summary_text.delta":
-          case "response.reasoning_text.delta": if (ev.delta) yield { type: "reasoning_delta", text: ev.delta }; break;
-          case "response.reasoning_summary_part.done": yield { type: "reasoning_delta", text: "\n\n" }; break;
-          case "response.function_call_arguments.delta": {
-            if (!ev.delta) break;
-            const s: Slot = slots.get(idx) ?? { kind: "function_call", callId: "", name: "", args: "" };
-            if (s.kind !== "function_call") break;
-            s.args += ev.delta;
-            slots.set(idx, s);
-            if (s.callId && s.name) yield { type: "tool_call_delta", id: s.callId, tool: s.name, argsDelta: ev.delta };
-            break;
-          }
-          case "response.function_call_arguments.done": { const s = slots.get(idx); if (s?.kind === "function_call" && typeof ev.arguments === "string") s.args = ev.arguments; break; }
-          case "response.output_item.done": {
-            if (ev.item) { const p = finishedPart(ev.item, slots.get(idx), idx); if (p) parts.set(idx, p); }
-            slots.delete(idx);
-            break;
-          }
-          case "response.completed":
-          case "response.incomplete": {
-            if (ev.response?.usage) usage = turnUsage(ev.response.usage);
-            const reason = ev.response?.incomplete_details?.reason;
-            terminal = ev.type === "response.completed" ? { stop: "end_turn" } : reason === "max_output_tokens" ? { stop: "length" } : { stop: "error", error: `Response incomplete: ${reason ?? "no reason given"}` };
-            break;
-          }
-          case "response.failed": { const e = ev.response?.error; terminal = { stop: "error", error: `${e?.code || "unknown"}: ${e?.message || "no message"}` }; break; }
-          case "error": terminal = { stop: "error", error: `${ev.code || "unknown"}: ${ev.message || "no message"}` }; break;
-          default: break; // response.created / in_progress / content_part.* / *_part.added / *.done text echoes: nothing to do
-        }
-      }
-      if (!terminal) terminal = { stop: "error", error: NO_TERMINAL_EVENT }; // pi shared.ts:757-759 — never end_turn
-      const ordered = [...parts].sort((a, b) => a[0] - b[0]).map(([, p]) => p);
-      turn = terminal.stop === "error"
-        ? { parts: [], stopReason: "error", usage, error: terminal.error }
-        : { parts: ordered, stopReason: terminal.stop === "end_turn" && ordered.some((p) => p.kind === "tool_call") ? "tool_use" : terminal.stop, usage };
-    } catch (e) {
-      turn = failedTurn(e, options?.signal, buffer); // mid-stream abort: the text already streamed survives, tool fragments do not
-    }
-    yield { type: "turn", turn };
-  };
-}

package/src/providers/retry.ts

@@ -1,234 +0,0 @@
-/** 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
-    }
-  };
-}