@providerkit/core 0.21.1 → 0.23.0

package/src/providers/responses.ts

@@ -10,8 +10,11 @@
 // The event names arrive on the SSE `event:` line and are repeated inside each
 // payload's own `type`. The transport yields only `data:` payloads, so this
 // adapter reads `type` — which is what survives, and what gateways agree on.
+import { repairHistory } from "../context.ts";
 import { fileRefused, ProviderError, streamCut, streamError } from "../errors.ts";
-import { streamSse, apiUrl } from "../transport.ts";
+import { streamSse, apiUrl, parseFrame } from "../transport.ts";
+import { parseRateLimitReset } from "../rate-limit.ts";
+import { settleToolCalls } from "../tool-args.ts";
 import type {
   ChatMessage,
   ContentPart,
@@ -39,7 +42,7 @@ export interface ResponsesConfig extends ProviderFallbackConfig {
   effort?: Effort;
   maxTokens?: number;
   fetchImpl?: typeof fetch;
-  /** Extra request headers — where a subscription backend's account id goes
+  /** Extra request headers, where a subscription backend's account id goes
    *  (`ChatGPT-Account-Id`), which those backends reject the request without. */
   headers?: Record<string, string>;
   /** Header that carries `StreamOptions.sessionId`. When set and a call has no
@@ -50,7 +53,7 @@ export interface ResponsesConfig extends ProviderFallbackConfig {
    * The ChatGPT subscription surface serves it at `/backend-api/codex/responses`
    * with no version segment, so that backend needs
    * `{ baseUrl: "https://chatgpt.com/backend-api/codex", path: "/responses" }`.
-   * Without the override the POST 404s, and a 404 classifies as "model" — the
+   * Without the override the POST 404s, and a 404 classifies as "model". The
    * user is told the model id does not exist when the path was the problem.
    */
   path?: string;
@@ -82,13 +85,26 @@ function reasoningEffort(model: string, effort: Effort): string {
 }
 
 /**
- * `response.incomplete` means the turn was cut short, and the seam has one word
- * for that: "length". `content_filter` is the only other reason this shape
- * documents; anything new stays on "length" rather than reporting a clean stop,
- * because a caller that believes a truncated answer finished will act on it.
+ * The finish an `incomplete` turn stands for. This shape documents two
+ * reasons, and each has its own finish: `max_output_tokens` is the output cap
+ * (`length`) and `content_filter` the filter.
+ *
+ * Any other reason, or none, says only that the turn did not end on purpose.
+ * It used to read as `length`, so an empty turn was told to raise a maxTokens
+ * it never hit. It is thrown as `overload` instead, the transient fault
+ * cc-proxy answers it with (a 503). Nothing about the request is wrong, so it
+ * is retried if nothing was emitted yet; if something was, the error reaches
+ * the caller after it (invariant 1). It is read before reasoning and usage go
+ * out, like a failed terminal, so that retry stays open.
  */
-function mapIncompleteReason(reason: string | undefined): FinishReason {
-  return reason === "content_filter" ? "content_filter" : "length";
+function incompleteFinish(provider: string, reason: string | undefined): FinishReason {
+  if (reason === "max_output_tokens") return "length";
+  if (reason === "content_filter") return "content_filter";
+  throw new ProviderError(
+    provider,
+    "overload",
+    `${provider}: the turn stopped early, reason: ${reason ?? "none given"}`,
+  );
 }
 
 // ── input items ───────────────────────────────────────────────────────────
@@ -141,8 +157,8 @@ function partsToResponses(
   });
 }
 
-/** A tool result is a bare string unless it carried images — then the content-
- *  array form, the only way to hand this shape a screenshot back. */
+/** A tool result is a bare string unless it carried images. Then it uses the
+ *  content-array form, the only way to hand this shape a screenshot back. */
 function toolOutput(
   content: string,
   images: readonly ImagePart[],
@@ -157,7 +173,7 @@ function toolOutput(
 /**
  * Flatten a history into `instructions` plus the input item list.
  *
- * This shape has no system ROLE — the system prompt is a top-level
+ * This shape has no system role. The system prompt is a top-level
  * `instructions` string, and everything else is items. One assistant turn can
  * become several items (its text, then one `function_call` per tool it asked
  * for), which is why a message maps to a list rather than to one item.
@@ -244,7 +260,7 @@ interface ResponsesUsage {
 
 interface ResponsesItem {
   type?: string;
-  /** The output item's own id (`fc_…`) — what the argument deltas reference. */
+  /** The output item's own id (`fc_…`), which the argument deltas reference. */
   id?: string;
   /** The id a `function_call_output` must quote on the next turn. */
   call_id?: string;
@@ -263,7 +279,7 @@ interface ResponsesEvent {
   arguments?: string;
   item?: ResponsesItem;
   response?: {
-    /** `completed`, `incomplete` or `failed` — stated on the terminal event,
+    /** `completed`, `incomplete` or `failed`, stated on the terminal event,
      *  and not always the one its `type` implies. */
     status?: string;
     usage?: ResponsesUsage;
@@ -282,8 +298,11 @@ interface ResponsesEvent {
   headers?: Record<string, unknown>;
 }
 
+/** One window of the snapshot: the `x-codex-<slot>-*` header numbers as JSON. */
 interface CodexWindow {
   used_percent?: number;
+  window_minutes?: number;
+  reset_at?: number;
   reset_after_seconds?: number;
 }
 
@@ -297,28 +316,46 @@ interface CodexRateLimits {
 /**
  * The quota wall a `codex.rate_limits` snapshot reports, if it is one.
  *
- * The snapshot rides ahead of the first output on every turn and is telemetry
- * — a full window the account's credits cover, or that the backend still
+ * The snapshot rides ahead of the first output on every turn and is telemetry.
+ * A full window the account's credits cover, or that the backend still
  * `allowed`, lets the turn proceed. It is only the reason when the stream then
  * closes without a response: that close is a spent window, not a dropped
- * socket, and retrying it walks every backup into the same wall. The fuller
- * window binds; cc-proxy took the primary's clock first and told a weekly wall
- * to come back in a few hours.
+ * socket, and retrying it walks every backup into the same wall.
+ *
+ * Which window, and when it lifts, comes from the same parser as the headers
+ * the snapshot mirrors: the fuller window binds, and the later reset when both
+ * are full. cc-proxy took the primary's clock first and told a weekly wall to
+ * come back in a few hours. The window is named so a caller can say "weekly"
+ * instead of "the limit", which reads as the 5-hour one.
  */
 function quotaWall(event: ResponsesEvent, provider: string): ProviderError | undefined {
   const limits = event.rate_limits;
   if (!limits?.limit_reached || limits.allowed) return undefined;
   if (event.credits?.has_credits || event.credits?.unlimited) return undefined;
-  const windows = [limits.primary, limits.secondary].filter((w): w is CodexWindow => !!w);
-  const binding = windows.sort((a, b) => (b.used_percent ?? 0) - (a.used_percent ?? 0))[0];
-  const after = binding?.reset_after_seconds;
-  return new ProviderError(provider, "quota", `${provider}: the usage limit has been reached`, {
-    ...(after !== undefined && after >= 0
-      ? { retryAfterMs: after * 1000, resetAtMs: Date.now() + after * 1000 }
-      : {}),
+  const now = Date.now();
+  const { window, resetAtMs } = parseRateLimitReset(codexHeaders(limits), now);
+  const named = window ? ` (${window} window)` : "";
+  const message = `${provider}: the usage limit has been reached${named}`;
+  return new ProviderError(provider, "quota", message, {
+    ...(resetAtMs !== undefined ? { retryAfterMs: resetAtMs - now, resetAtMs } : {}),
+    window,
   });
 }
 
+/** The snapshot as the `x-codex-*` headers it mirrors, rebuilt the way
+ *  cc-proxy's `event_headers` does, so one parser reads both. */
+function codexHeaders(limits: CodexRateLimits): Headers {
+  const headers = new Headers();
+  for (const slot of ["primary", "secondary"] as const) {
+    for (const [field, value] of Object.entries(limits[slot] ?? {})) {
+      if (typeof value === "number") {
+        headers.set(`x-codex-${slot}-${field.replaceAll("_", "-")}`, String(value));
+      }
+    }
+  }
+  return headers;
+}
+
 function usageChunk(usage: ResponsesUsage): ProviderChunk {
   return {
     type: "usage",
@@ -336,8 +373,8 @@ function usageChunk(usage: ResponsesUsage): ProviderChunk {
   };
 }
 
-/** What has already gone out for one in-flight function call — identity and
- *  arguments both — so the authoritative snapshot on `.done` can be diffed
+/** What has already gone out for one in-flight function call (identity and
+ *  arguments), so the authoritative snapshot on `.done` can be diffed
  *  against it instead of duplicated. */
 interface PendingCall {
   index: number;
@@ -373,8 +410,11 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
       const model = opts.model ?? config.model;
       const museContributor = isMuseSparkContributor(model);
       const requestTools = museContributor && opts.toolChoice === "none" ? [] : tools;
+      // Repaired before the images are gated: an orphaned result becomes a user
+      // note that keeps its images, and those must meet the limits too.
+      const sent = repairHistory(messages).messages;
       const { instructions, input } = toResponsesInput(
-        config.imageLimits ? gateImages(messages, config.imageLimits) : messages,
+        config.imageLimits ? gateImages(sent, config.imageLimits) : sent,
         id,
       );
 
@@ -457,9 +497,10 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
       const pendingFor = (itemId?: string, callId?: string) =>
         (itemId ? pending.get(itemId) : undefined) ?? (callId ? pending.get(callId) : undefined);
       let nextIndex = 0;
-      // This shape never states a stop reason on a clean finish, so it is
-      // inferred from whether the turn produced a function call.
-      let sawToolCall = false;
+      // Every call the turn opened, kept past its `.done`. This shape never
+      // states a stop reason on a clean finish, so it is inferred from whether
+      // there are any, and the terminal event checks each one can run.
+      const calls: PendingCall[] = [];
       let wall: ProviderError | undefined;
       let produced = false;
       const reasoningItems: unknown[] = [];
@@ -482,13 +523,9 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
       })) {
-        let event: ResponsesEvent;
-        try {
-          event = JSON.parse(data) as ResponsesEvent;
-        } catch {
-          continue; // a keep-alive or a frame we do not model
-        }
+        const event = parseFrame<ResponsesEvent>(data, id);
         if (event.type?.endsWith(".delta") || event.type === "response.output_item.added") {
           produced = true;
         }
@@ -515,7 +552,6 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
             // turn came back as a nameless call with empty arguments.
             const key = item.id ?? item.call_id;
             if (!key) break;
-            sawToolCall = true;
             const index = nextIndex++;
             // Normally empty here, but a backend that already has the whole
             // call sends it in the skeleton.
@@ -526,6 +562,7 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
               name: item.name ?? "",
               streamed: seeded,
             };
+            calls.push(call);
             pending.set(key, call);
             if (item.call_id) pending.set(item.call_id, call);
             // Only the fields the skeleton actually states. An empty `id` here
@@ -582,20 +619,24 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
 
             if (!known) {
               // A backend that emits neither the skeleton nor the deltas — the
-              // whole call arrives here or not at all. Without a `call_id`
-              // there is nothing to answer it with: the caller's
-              // `function_call_output` would quote `""` and take a 400 reading
-              // "No tool output found for function call" one turn later, so the
-              // call is dropped rather than handed over unrunnable. Dropping is
-              // only possible here, where nothing has been streamed for it yet.
-              if (!item.call_id) break;
-              sawToolCall = true;
+              // whole call arrives here or not at all. A call with no `call_id`
+              // used to be dropped, because the caller's `function_call_output`
+              // would quote `""` and take a 400 one turn later. Dropped, the
+              // model's call silently never happened. It gets an id at the
+              // terminal event instead (`settleToolCalls`).
+              const call: PendingCall = {
+                index: nextIndex++,
+                id: item.call_id ?? "",
+                name: item.name ?? "",
+                streamed: snapshot,
+              };
+              calls.push(call);
               yield {
                 type: "delta",
                 toolCalls: [
                   {
-                    index: nextIndex++,
-                    id: item.call_id,
+                    index: call.index,
+                    ...(item.call_id ? { id: item.call_id } : {}),
                     ...(item.name ? { name: item.name } : {}),
                     arguments: snapshot,
                   },
@@ -617,6 +658,8 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
               ...(item.name && item.name !== known.name ? { name: item.name } : {}),
               ...(tail ? { arguments: tail } : {}),
             };
+            known.id = item.call_id || known.id;
+            known.name = item.name || known.name;
             if (Object.keys(restated).length > 0) {
               yield { type: "delta", toolCalls: [{ index: known.index, ...restated }] };
             }
@@ -635,16 +678,27 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
             if (response?.status === "failed" || response?.error) {
               throw streamError(id, response.error ?? { message: "response failed" });
             }
+            // Any other status (`cancelled`, `queued`, one added later) says
+            // nothing about the answer being whole. Read as a clean stop, it
+            // was a finished turn nobody retried. Theirs, so `overload`.
+            const status = response?.status;
+            if (status !== undefined && status !== "completed" && status !== "incomplete") {
+              throw new ProviderError(id, "overload", `${id} ended the turn as "${status}"`, {
+                code: status,
+              });
+            }
+            let finishReason: FinishReason = calls.length > 0 ? "tool_calls" : "stop";
+            if (status === "incomplete") {
+              finishReason = incompleteFinish(id, response?.incomplete_details?.reason);
+            } else {
+              // Checked on a whole turn only: a cut one may have lost a call's
+              // name to the cut, and nobody runs a cut turn's calls.
+              const minted = settleToolCalls(id, calls);
+              if (minted.length > 0) yield { type: "delta", toolCalls: minted };
+            }
             yield* reasoningChunk();
             if (response?.usage) yield usageChunk(response.usage);
-            if (response?.status === "incomplete") {
-              yield {
-                type: "finish",
-                finishReason: mapIncompleteReason(response.incomplete_details?.reason),
-              };
-              return;
-            }
-            yield { type: "finish", finishReason: sawToolCall ? "tool_calls" : "stop" };
+            yield { type: "finish", finishReason };
             return;
           }
 
@@ -655,13 +709,11 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
           case "response.incomplete": {
             // A turn that ran out of output tokens still billed for its input,
             // and this event carries usage in the same shape as `completed`.
+            const finishReason = incompleteFinish(id, event.response?.incomplete_details?.reason);
             yield* reasoningChunk();
             const usage = event.response?.usage;
             if (usage) yield usageChunk(usage);
-            yield {
-              type: "finish",
-              finishReason: mapIncompleteReason(event.response?.incomplete_details?.reason),
-            };
+            yield { type: "finish", finishReason };
             return;
           }
 

package/src/providers/zai.ts

@@ -13,8 +13,8 @@ export type ZaiCodingConfig = Omit<AnthropicConfig, "baseUrl" | "id" | "bearer">
  *  adapter.
  *
  *  Dialect notes, measured 2026-09-13 against the live endpoint on
- *  `glm-5.3-flash`: an absent thinking field means the MODEL's default —
- *  thinking ON — so `effort: "none"` is sent as an explicit
+ *  `glm-5.3-flash`: an absent thinking field means the model's default
+ *  (thinking on), so `effort: "none"` is sent as an explicit
  *  `thinking: { type: "disabled" }`; `low`–`max` ride the standard thinking
  *  budgets, which the endpoint accepts. Images force a thinking block even
  *  under `disabled` (the model's choice, billed as output). */

package/src/rate-limit.ts

@@ -32,12 +32,20 @@ export type RateLimitWindow = "5h" | "weekly" | "monthly";
 export interface RateLimitReset {
   /** Absolute time the binding window resets, when any header disclosed it. */
   resetAtMs?: number;
-  /** Server-requested wait (`retry-after`) — what a retry policy honours. */
+  /** Server-requested wait (`retry-after`), which a retry policy honours. */
   retryAfterMs?: number;
   /** Which subscription window bound, when it could be named at all. */
   window?: RateLimitWindow;
+  /** How full the binding window is, as the headers report it (1 is full).
+   *  Set only when a window's fill rode the response: Anthropic's unified
+   *  5h/7d headers, or the ChatGPT backend's `x-codex-*` ones. */
+  utilization?: number;
 }
 
+/** A window's fill off a response that reported one: what
+ *  `StreamOptions.onRateLimit` receives. */
+export type RateLimitReading = RateLimitReset & { utilization: number; resetAtMs: number };
+
 const RETRY_AFTER = "retry-after";
 const RETRY_AFTER_MS = "retry-after-ms";
 const UNIFIED_5H = "anthropic-ratelimit-unified-5h-";
@@ -58,7 +66,7 @@ const RESET_HEADERS = [
 ];
 
 /**
- * The ChatGPT backend's two windows. Both ride every response — the slots are
+ * The ChatGPT backend's two windows. Both ride every response. The slots are
  * "primary" and "secondary", NOT "5h" and "weekly", so the window is named by
  * its own `-window-minutes` (300 and 10080 in every capture), and its
  * `-used-percent` says which one is full. Recorded by cc-proxy off a live turn
@@ -66,11 +74,23 @@ const RESET_HEADERS = [
  */
 const CODEX_SLOTS = ["primary", "secondary"] as const;
 
+/** One window as a response reports it: how full, and when it resets. */
+interface WindowReading {
+  window?: RateLimitWindow;
+  utilization?: number;
+  reset?: number;
+}
+type Dated = WindowReading & { utilization: number; reset: number };
+
 function windowForMinutes(minutes: number | undefined): RateLimitWindow | undefined {
   return minutes !== undefined && minutes > 0 ? windowForMs(minutes * 60_000) : undefined;
 }
 
-function codexWindow(headers: Headers, slot: (typeof CODEX_SLOTS)[number], now: number) {
+function codexWindow(
+  headers: Headers,
+  slot: (typeof CODEX_SLOTS)[number],
+  now: number,
+): WindowReading {
   const name = (suffix: string) => headers.get(`x-codex-${slot}-${suffix}`);
   const percent = numeric(name("used-percent"));
   const after = numeric(name("reset-after-seconds"));
@@ -154,7 +174,7 @@ function parseRetryAfter(value: string | null, now: number): number | undefined
  * Anthropic's `anthropic-ratelimit-unified-*` pair rides on every OAuth
  * response, so both windows are always reported and only one of them is the
  * reason for this 429. API-key accounts get the `anthropic-ratelimit-*-reset`
- * RFC 3339 timestamps instead. Everything is optional — an unrecognized shape
+ * RFC 3339 timestamps instead. Everything is optional: an unrecognized shape
  * yields an empty result, and the caller falls back to its generic message.
  */
 export function parseRateLimitReset(headers: Headers, now = Date.now()): RateLimitReset {
@@ -185,10 +205,18 @@ export function parseRateLimitReset(headers: Headers, now = Date.now()): RateLim
       reset: unixSecondsToMs(headers.get(`${UNIFIED_7D}reset`)),
     },
     ...CODEX_SLOTS.map((slot) => codexWindow(headers, slot, now)),
-  ].filter((w) => w.utilization !== undefined && w.reset !== undefined && w.reset > now);
-  const binding = windows.sort((a, b) => (b.utilization ?? 0) - (a.utilization ?? 0))[0];
+  ].filter(
+    (w): w is Dated => w.utilization !== undefined && w.reset !== undefined && w.reset > now,
+  );
+  // The fuller window binds. Between two as full as each other (both spent,
+  // usually) the later reset does: the request passes only once both have
+  // cleared, and waiting out the earlier one walks into the other wall. On a
+  // dead heat the later slot wins (the sort is stable), as cc-proxy's `max_by`
+  // does.
+  const binding = windows.sort((a, b) => a.utilization - b.utilization || a.reset - b.reset).at(-1);
   if (binding) {
     if (binding.window) result.window = binding.window;
+    result.utilization = binding.utilization;
     // The window's own reset outranks retry-after: it names the real horizon,
     // where retry-after names the next polite attempt.
     if (binding.reset !== undefined) result.resetAtMs = binding.reset;
@@ -270,7 +298,7 @@ function parseProseRetryMs(text: string): number | undefined {
  * Other providers and gateways (LiteLLM, Cloudflare, Ollama) report countdowns in prose:
  * `Rate limit exceeded. Try again in 20s.`
  * The window name is inferred from the wait itself, and only past the floor
- * above — a sub-minute retry is a throttle, not a subscription window.
+ * above. A sub-minute retry is a throttle, not a subscription window.
  */
 export function parseUsageLimitBody(bodyText: string, now = Date.now()): RateLimitReset {
   let body: unknown;

package/src/retry.ts

@@ -28,6 +28,17 @@ export interface RetryOptions {
   /** Maximum acceptable wait. A longer server deadline ends retry so an outer
    *  fallback can switch provider; it is never shortened to retry too early. */
   maxDelayMs?: number;
+  /**
+   * How long recovery may go on, counted from the FIRST failure. A retry
+   * starts only if it would start before then, its wait included. An attempt
+   * already running is never cut. Default 60s; `Infinity` turns it off.
+   *
+   * Without it the worst case is every attempt in full plus every wait: three
+   * stalled streams at the watchdog's 300s each is a quarter of an hour before
+   * the caller hears anything. The clock starts at the first failure, not at
+   * the call, so a long healthy run that then fails still gets its recovery.
+   */
+  budgetMs?: number;
   /** Aborts the wait as well as the work, so Stop lands promptly. */
   signal?: AbortSignal;
   /** Decide retryability. Default: transient kinds only. */
@@ -40,6 +51,7 @@ export interface RetryOptions {
 const DEFAULT_MAX_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_MS = 1_000;
 const DEFAULT_MAX_DELAY_MS = 30_000;
+const DEFAULT_BUDGET_MS = 60_000;
 
 /**
  * Full-jitter exponential backoff: a random delay in
@@ -92,9 +104,32 @@ function delayFor(err: unknown, attempt: number, opts: RetryOptions): number | n
 
 const defaultShouldRetry = (err: unknown, _attempt: number): boolean => isRetryable(err);
 
+/** The moment the recovery budget runs out, fixed at the first failure. */
+const budgetEnd = (opts: RetryOptions): number => Date.now() + (opts.budgetMs ?? DEFAULT_BUDGET_MS);
+
+/**
+ * Wait out the delay before the next attempt, or rethrow `err` unchanged when
+ * there is none: the server's deadline is past `maxDelayMs`, or the next
+ * attempt would start past the budget.
+ */
+async function waitToRetry(
+  err: unknown,
+  attempt: number,
+  opts: RetryOptions,
+  budgetEndsAt: number,
+): Promise<void> {
+  const delayMs = delayFor(err, attempt, opts);
+  if (delayMs === null || Date.now() + delayMs >= budgetEndsAt) throw err;
+  opts.onRetry?.({ error: err, attempt, delayMs });
+  await (opts.sleep ?? sleep)(delayMs, opts.signal);
+  // A timer can wake long after it was due (a suspended worker, a throttled
+  // tab). The budget is about when the attempt starts, not when it was meant to.
+  if (Date.now() >= budgetEndsAt) throw err;
+}
+
 /**
- * Run `fn`, retrying transient failures with backoff. For one-shot calls —
- * a title, a summary, a compaction pass.
+ * Run `fn`, retrying transient failures with backoff. For one-shot calls such
+ * as a title, a summary or a compaction pass.
  */
 export async function withRetry<T>(
   fn: (attempt: number) => Promise<T>,
@@ -102,7 +137,7 @@ export async function withRetry<T>(
 ): Promise<T> {
   const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
   const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
-  const nap = opts.sleep ?? sleep;
+  let budgetEndsAt: number | undefined;
 
   let lastError: unknown;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -114,17 +149,15 @@ export async function withRetry<T>(
       // A caller's Stop is never a transient failure, whatever it looks like.
       if (opts.signal?.aborted) throw err;
       if (attempt >= maxAttempts || !shouldRetry(err, attempt)) throw err;
-      const delayMs = delayFor(err, attempt, opts);
-      if (delayMs === null) throw err;
-      opts.onRetry?.({ error: err, attempt, delayMs });
-      await nap(delayMs, opts.signal);
+      budgetEndsAt ??= budgetEnd(opts);
+      await waitToRetry(err, attempt, opts, budgetEndsAt);
     }
   }
   throw lastError;
 }
 
 /**
- * The streaming twin — with the rule that makes it safe: a retry happens only
+ * The streaming twin of `withRetry`. A retry happens only
  * while NOTHING has been yielded yet.
  *
  * `factory` is re-invoked per attempt and gets a fresh signal, so an abandoned
@@ -138,7 +171,7 @@ export async function* withStreamRetry<T>(
 ): AsyncGenerator<T> {
   const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
   const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
-  const nap = opts.sleep ?? sleep;
+  let budgetEndsAt: number | undefined;
 
   let lastError: unknown;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -163,10 +196,8 @@ export async function* withStreamRetry<T>(
       if (opts.signal?.aborted) throw err;
       // Rule 2: past the first chunk there is no going back.
       if (emitted || attempt >= maxAttempts || !shouldRetry(err, attempt)) throw err;
-      const delayMs = delayFor(err, attempt, opts);
-      if (delayMs === null) throw err;
-      opts.onRetry?.({ error: err, attempt, delayMs });
-      await nap(delayMs, opts.signal);
+      budgetEndsAt ??= budgetEnd(opts);
+      await waitToRetry(err, attempt, opts, budgetEndsAt);
     } finally {
       opts.signal?.removeEventListener("abort", onOuterAbort);
       // Abandoning mid-iteration (the consumer broke out, or we are retrying)
@@ -182,7 +213,7 @@ export interface BackupModelOptions {
   models: string[];
   /**
    * Whether a failure may fall through to the remaining models. Default:
-   * overload and rate limits only — those are per-model-endpoint, and nothing
+   * overload and rate limits only. Those are per-model-endpoint, and nothing
    * else on the list is. An auth failure or an invalid request would land
    * identically on every backup.
    */
@@ -226,7 +257,7 @@ export async function withBackupModels<T>(
 }
 
 /**
- * The streaming twin — carrying the same commitment rule as `withStreamRetry`.
+ * The streaming twin of `withBackupModels`, with the same commitment rule as `withStreamRetry`.
  *
  * This is the correction worth naming: walking to a backup model AFTER chunks
  * have already reached the consumer replays the answer from the top, in a

package/src/schema.ts

@@ -70,19 +70,19 @@ export function clampToSchema(value: unknown, node: unknown): unknown {
  * Whether OpenAI's `strict` schema mode will accept this schema.
  *
  * Strict is the only JSON mode that actually guarantees the shape, so it is
- * worth having — but it demands more than JSON Schema does: every property an
+ * worth having, but it demands more than JSON Schema does: every property an
  * object lists must ALSO be required, and every object must close itself with
  * `additionalProperties: false`, all the way down. A schema with one optional
  * field is not "mostly strict"; it is a flat 400 naming a nested path rather
  * than the rule it broke.
  *
  * That trap is the reason this exists. An agent's response schema grows
- * optional fields naturally — a `data` block only some flows fill, the fields
- * one step collects — and a caller who adds one wants their answer, not a
+ * optional fields naturally (a `data` block only some flows fill, the fields
+ * one step collects). A caller who adds one wants their answer, not a
  * lecture about a mode they never asked for. So the OpenAI-shape adapters ask
  * this and drop to plain (unenforced) schema mode instead of failing the turn.
  *
- * Anything it cannot verify — a `$ref`, a composed `allOf` — answers false:
+ * Anything it cannot verify (a `$ref`, a composed `allOf`) answers false:
  * the cost of guessing wrong that way is unenforced output, and the cost of
  * guessing wrong the other way is a request that cannot succeed at all.
  */
@@ -97,7 +97,7 @@ export function clampToSchema(value: unknown, node: unknown): unknown {
  *
  * Two shapes need it, which is why the wording lives here rather than in one of
  * them. Anthropic has never had a schema mode. The OpenAI dialect falls back to
- * plain JSON mode on every gateway — `json_object` asks for valid JSON and says
+ * plain JSON mode on every gateway: `json_object` asks for valid JSON and says
  * nothing whatsoever about its shape.
  */
 export function schemaPrompt(schema: unknown): string {
@@ -134,8 +134,8 @@ export function isStrictSchema(node: unknown): boolean {
   );
 }
 
-/** Keywords whose value is a schema, a list of schemas, or a map of them —
- *  the only places a `pattern` can mean a regex. Everything else (`default`,
+/** Keywords whose value is a schema, a list of schemas, or a map of them.
+ *  These are the only places a `pattern` can mean a regex. Everything else (`default`,
  *  `examples`, `enum`, property NAMES) is data and is left alone. */
 const SCHEMA_SLOTS = [
   "items",
@@ -156,7 +156,7 @@ const SCHEMA_MAPS = ["properties", "patternProperties", "$defs", "definitions",
  * A tool schema with every `pattern` constraint removed.
  *
  * The ChatGPT backend compiles tool schemas with OpenAI's own regex dialect and
- * answers a pattern it cannot read with a 400 for the WHOLE request — strict
+ * answers a pattern it cannot read with a 400 for the whole request, strict
  * or not. Claude Code's Artifact tool carries one, and every request that
  * offered it failed (cc-proxy #141/#142). Losing the constraint costs a
  * validation the caller's tool runner repeats anyway; the 400 costs the turn.