@providerkit/core 0.21.1 → 0.23.0

package/src/errors.ts

@@ -15,7 +15,7 @@ import type { FilePart } from "./types.ts";
 
 /** What kind of failure this is, named by what actually fixes it. */
 export type ErrorKind =
-  /** Our own cancel — the caller pressed Stop. Never retried. */
+  /** Our own cancel: the caller pressed Stop. Never retried. */
   | "aborted"
   /** Our own deadline, or the provider's 408. Retry. */
   | "timeout"
@@ -24,13 +24,13 @@ export type ErrorKind =
   /** Theirs, and temporary: 5xx, Anthropic's 529, "overloaded". Retry, and
    *  worth trying a different model. */
   | "overload"
-  /** 429 per-minute throttle. Wait — or rotate to another key or model. */
+  /** 429 per-minute throttle. Wait, or rotate to another key or model. */
   | "rate"
   /** Balance or usage window exhausted. Waiting minutes will not fix it. */
   | "quota"
   /** The plan never included this API. Neither a new key nor a top-up fixes it. */
   | "entitlement"
-  /** 401/403 — the key is wrong, not the request. */
+  /** 401/403: the key is wrong, not the request. */
   | "auth"
   /** The model id does not exist or is not served here. */
   | "model"
@@ -38,7 +38,7 @@ export type ErrorKind =
   | "context"
   /** Safety filter or refusal. */
   | "content"
-  /** Any other 4xx — a bug in what we sent. */
+  /** Any other 4xx: a bug in what we sent. */
   | "invalid"
   | "unknown";
 
@@ -81,7 +81,7 @@ export function isBackupEligible(kind: ErrorKind): boolean {
  * 1. Caller aborts are never retryable.
  * 2. An explicit `shouldRetry` directive on ProviderError (e.g. from server `x-should-retry`)
  * 3. Non-retryable kinds (quota, context, model, entitlement, content, invalid) return false.
- * 4. Excessive retry-after waits (exceeding `maxWaitMs`) return false — long waits belong to fallbacks.
+ * 4. Excessive retry-after waits (exceeding `maxWaitMs`) return false. Long waits belong to fallbacks.
  * 5. Transient kinds (rate, overload, network, timeout) return true.
  * 6. Transport-level network faults (fetch failed, connection lost, SSL blips) return true.
  */
@@ -115,7 +115,7 @@ export class ProviderError extends Error {
   readonly window?: RateLimitWindow;
   /** Explicit server directive (`x-should-retry`), overriding default classification. */
   readonly shouldRetry?: boolean;
-  /** The provider's own response body, truncated — the actual reason, which is
+  /** The provider's own response body, truncated. It carries the actual reason,
    *  otherwise lost behind "400 status code (no body)". */
   readonly body?: string;
 
@@ -213,7 +213,7 @@ export function messageOf(err: unknown): string {
  * Everything readable about the failure as one searchable string: the message
  * plus the parsed provider body. SDKs park the parsed body on `.error`, and
  * that is where the real reason lives ("max_tokens too large", the quotaId,
- * `"type": "billing_error"`). Scanned as TEXT — the error-type strings
+ * `"type": "billing_error"`). Scanned as text: the error-type strings
  * serialize into it, so no JSON walking is needed.
  */
 function bodyTextOf(err: unknown): string {
@@ -293,7 +293,7 @@ function isAbort(err: unknown): boolean {
  * A transport fault: the socket died before or during the response, so there
  * is NO status and no body for the patterns below to read.
  *
- * The chain is walked because the useful code is rarely on the thrown error —
+ * The chain is walked because the useful code is rarely on the thrown error:
  * it sits on `cause`, sometimes several wrappers deep. Without this walk every
  * network blip classifies as permanent, and a long run dies on its first
  * hiccup, which is the single likeliest way to lose a minutes-long job.
@@ -343,6 +343,12 @@ const CONTEXT_PATTERNS: readonly RegExp[] = [
   // "input length and `max_tokens` exceed context limit: 188059 + 20000 > 200000"
   /input length and `?max_tokens`? exceed context limit/i,
   /exceed(?:s|ed)? (?:the )?context limit/i,
+  // GitHub Copilot: "prompt token count of 270000 exceeds the limit of 128000",
+  // code `model_max_prompt_tokens_exceeded`. No other wording here reads it,
+  // so it landed on `invalid` and the conversation never compacted. cc-proxy
+  // shipped the same two patterns for the same reason (0.1.51).
+  /model_max_prompt_tokens_exceeded/i,
+  /prompt token count of \d+ exceeds the limit/i,
   // Scoped to the thing that overflowed: a bare "exceeds the maximum" also
   // covers image counts and per-minute token rates, which compaction can't fix.
   /exceeds? the (?:model'?s? )?maximum (?:input |prompt |context )?(?:tokens?|length|context)/i,
@@ -455,7 +461,7 @@ const CONTENT_PATTERNS: readonly RegExp[] = [
  * A throttle said in words rather than in a 429.
  *
  * Every other kind has body evidence; rate had only the status, which is
- * exactly the evidence an in-band failure lacks — an SSE response is already
+ * exactly the evidence an in-band failure lacks. An SSE response is already
  * 200 when the throttle lands, so the reason arrives as a payload with no
  * status line at all. Checked below the status branches, so it only ever
  * catches what would otherwise fall through to "unknown".
@@ -501,18 +507,18 @@ const matches = (patterns: readonly RegExp[], text: string): boolean =>
  * The kind of failure, from whatever was thrown.
  *
  * Body patterns outrank status for the 4xx family; within them, context beats
- * entitlement beats quota beats auth — each earlier category's fix is useless
+ * entitlement beats quota beats auth. Each earlier category's fix is useless
  * for the later ones.
  */
 /**
- * The kind of a failure that arrived as an HTTP response — a status and a body,
+ * The kind of a failure that arrived as an HTTP response: a status and a body,
  * with nothing thrown.
  *
  * `classify` below is for a caught error, and it reads `status` and the body
  * text off that error when they are not passed separately. A response has no
  * error object, so callers were inventing one to fill the slot: a bare body
  * string, the same text twice, a `{ status, error }` literal. All three are
- * inert — nothing on them can satisfy `isAbort` or `isTransportFailure` — so
+ * inert (nothing on them can satisfy `isAbort` or `isTransportFailure`), so
  * they were three spellings of `undefined`.
  */
 export function classifyHttp(status: number | undefined, body: string): ErrorKind {
@@ -568,7 +574,7 @@ export function classify(err: unknown, status?: number, body?: string): ErrorKin
 /**
  * How long the provider asked us to wait, in ms. Two dialects: Gemini's
  * RetryInfo (`"retryDelay": "52s"`, inside the body) and the `Retry-After`
- * header, which SDKs keep on the error. Honouring it beats guessing — a
+ * header, which SDKs keep on the error. Honouring it beats guessing: a
  * backoff shorter than the window just burns an attempt.
  */
 export function parseRetryAfterMs(err: unknown, body?: string): number | undefined {
@@ -652,6 +658,25 @@ export function parseContextOverflow(err: unknown, body?: string): ContextOverfl
   return undefined;
 }
 
+/**
+ * The HTTP status an in-band error's type stands for when it states none:
+ * Anthropic's types, then OpenAI's, read from `type` and then from a slug
+ * `code`. cc-proxy's table. A Map, so a type named after an Object method
+ * finds nothing rather than a function.
+ */
+const STATUS_BY_TYPE: ReadonlyMap<string, number> = new Map([
+  ["invalid_request_error", 400],
+  ["authentication_error", 401],
+  ["permission_error", 403],
+  ["not_found_error", 404],
+  ["request_too_large", 413],
+  ["rate_limit_error", 429],
+  ["api_error", 500],
+  ["server_error", 500],
+  ["internal_server_error", 500],
+  ["overloaded_error", 529],
+]);
+
 /**
  * A failure the backend reports INSIDE an already-200 stream.
  *
@@ -664,24 +689,39 @@ export function parseContextOverflow(err: unknown, body?: string): ContextOverfl
  * completion: retry sees nothing to retry, and a key pool never rotates off an
  * exhausted key.
  *
- * `error` is the vendor's own payload, whatever shape it came in — the numeric
+ * `error` is the vendor's own payload, whatever shape it came in: the numeric
  * HTTP `code` Gemini and OpenRouter use, the slug OpenAI and Anthropic put in
  * `code`/`type`, the canonical `status` name. The whole thing serializes into
  * the searchable body, so RetryInfo's `retryDelay` is honoured wherever it sits.
  *
+ * A number is a status only from 400 to 599. Vendors put their own codes in
+ * the same field: Z.ai's 1113 is an empty balance, and read as a status it was
+ * past 500, which skips the 4xx body patterns that name it quota and lands on
+ * overload. With no status stated, the error's type says which one it stands
+ * for (`STATUS_BY_TYPE`), and the body still outranks it (invariant 3).
+ *
  * `unknown` is floored to "overload" rather than kept: a stream that dies after
  * its headers is by construction a transient upstream fault, and "unknown" is
- * never retried. Everything the body DOES name keeps its own kind — which is
- * what tells the caller to wait, rotate a key, or compact instead of retrying
- * a failure that will repeat.
+ * never retried. Only an error with no status and no type it knows gets there.
+ * Before the type was read, one `invalid_request_error` in words no pattern
+ * knew was floored too: retried, then walked across every backup, cooling each
+ * for 30s, on a request that fails the same way everywhere. Everything the
+ * body does name keeps its own kind, which is what tells the caller to wait,
+ * rotate a key, or compact instead of retrying a failure that will repeat.
  */
 export function streamError(provider: string, error: unknown): ProviderError {
   const body = JSON.stringify(error ?? {}) ?? "";
-  const status =
-    readNumber(error, "code") ?? readNumber(error, "status") ?? readNumber(error, "status_code");
+  const status = [
+    readNumber(error, "code"),
+    readNumber(error, "status"),
+    readNumber(error, "status_code"),
+  ].find((value) => value !== undefined && value >= 400 && value < 600);
   const code =
     readString(error, "code") ?? readString(error, "status") ?? readString(error, "type");
-  const kind = classifyHttp(status, body);
+  const typeStatus =
+    STATUS_BY_TYPE.get(readString(error, "type") ?? "") ??
+    STATUS_BY_TYPE.get(readString(error, "code") ?? "");
+  const kind = classifyHttp(status ?? typeStatus, body);
   return new ProviderError(
     provider,
     kind === "unknown" ? "overload" : kind,
@@ -697,7 +737,7 @@ export function streamError(provider: string, error: unknown): ProviderError {
 }
 
 /** The reset a stream error carries: the body's clock, plus the rate-limit
- *  headers the ChatGPT backend mirrors INTO its error frame — the only place a
+ *  headers the ChatGPT backend mirrors into its error frame, the only place a
  *  failure after the 200 can say which window ran out. */
 function readReset(error: unknown, body: string) {
   const raw =
@@ -720,7 +760,7 @@ function readReset(error: unknown, body: string) {
  * read it: a caller that never checks the finish keeps half an answer as if it
  * were the whole one, the ledger records a billed turn as free, and no pool
  * learns the endpoint is dropping streams. cc-proxy shipped the same fix
- * (0.1.39) for the same reason — "instead of marking affected streamed
+ * (0.1.39) for the same reason: "instead of marking affected streamed
  * responses as successful".
  *
  * `network`, because that is what it is: the same failure as a socket that
@@ -736,7 +776,7 @@ export function streamCut(provider: string): ProviderError {
   );
 }
 
-/** The loggable surface of a failure — so a dead run never reads
+/** The failure details you can log, so a dead run never reads
  *  "400 status code (no body)". */
 export function describeProviderError(err: unknown): Record<string, unknown> {
   if (err instanceof ProviderError) {

package/src/fallback.ts

@@ -1,8 +1,9 @@
 import { classify, parseRetryAfterMs, ProviderError, type ErrorKind } from "./errors.ts";
 import type { RateLimitWindow } from "./rate-limit.ts";
 import type { ProviderPresetId } from "./presets.ts";
+import { sleep } from "./retry.ts";
 import type { Provider, ProviderChunk } from "./types.ts";
-import { withWatchdog, type WatchdogOptions } from "./watchdog.ts";
+import { STREAM_PROGRESS_MS, withWatchdog, type WatchdogOptions } from "./watchdog.ts";
 import { createPresetProvider, type PresetProviderConfig } from "./providers/factory.ts";
 
 /** Retry intervals when the server supplies no deadline, not estimates of when
@@ -30,6 +31,20 @@ export interface FallbackOptions<T> {
     retryAtMs: number;
     window?: RateLimitWindow;
   }) => void;
+  /** Where cooldowns live; a private Map when omitted. Hand one store to every
+   *  pool that holds the same candidate and a lockout learned in one chain
+   *  benches it in all of them, instead of each chain spending a call to find
+   *  the same weekly wall. Pools sharing a store must share `cooldownMs` too: a
+   *  bench set by one pool is honoured by the others, so a kind one of them
+   *  turned off (`null`) would still divert its calls whenever another pool
+   *  benched the candidate for it. */
+  cooldowns?: CooldownStore<T>;
+  /** How long a recovery probe may go without a first chunk before another
+   *  call may replace it. A probe that hung used to hold its candidate out of
+   *  service for good. Defaults to the watchdog's progress clock
+   *  (`STREAM_PROGRESS_MS`): a call silent that long is one the watchdog
+   *  would already have killed. */
+  probeStaleMs?: number;
   /** Inject a clock for deterministic tests. */
   now?: () => number;
 }
@@ -93,11 +108,53 @@ export function withConfiguredFallbacks(
   );
 }
 
-interface Cooldown {
+/** One candidate's bench, as a pool records it. */
+export interface Cooldown {
   retryAtMs: number;
   kind: ErrorKind;
   window?: RateLimitWindow;
-  probing: boolean;
+  /** The one call let through once the bench expired. Only that call clears
+   *  it, and `settled` resolves at its first chunk or its end. */
+  probe?: { since: number; settled: Promise<void>; settle(): void };
+}
+
+/** Where a pool keeps its benches. A `Map` fits, and so does a `WeakMap` keyed
+ *  by providers, which lets a bench go when its provider does. `get` must
+ *  return the very object `set` was given: the probe is tracked on it. */
+export interface CooldownStore<T> {
+  get(candidate: T): Cooldown | undefined;
+  set(candidate: T, cooldown: Cooldown): void;
+  delete(candidate: T): unknown;
+}
+
+function openProbe(since: number): NonNullable<Cooldown["probe"]> {
+  let settle = (): void => {};
+  const settled = new Promise<void>((resolve) => {
+    settle = resolve;
+  });
+  return { since, settled, settle };
+}
+
+/** How many times a call that found nothing free waits on a probe before it
+ *  fails. The first wait covers a probe that answers or fails. The second
+ *  covers one that ended with neither (its own caller stopped it) and was
+ *  taken over by another waiter. Past that the caller's own retry decides. */
+const PROBE_WAITS = 2;
+
+/** Resolve when any probe settles or `ms` passes. Rejects with the caller's
+ *  reason on abort, and leaves no timer running once a probe wins. */
+async function waitForProbe(
+  settled: readonly Promise<void>[],
+  ms: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  const done = new AbortController();
+  const wake = signal ? AbortSignal.any([signal, done.signal]) : done.signal;
+  try {
+    await Promise.race([...settled, sleep(Math.max(0, ms), wake)]);
+  } finally {
+    done.abort();
+  }
 }
 
 /** The whole chain is unavailable. Fail promptly instead of holding a request
@@ -126,7 +183,8 @@ export class NoAvailableProviderError extends ProviderError {
  *  a background timer, vendor SDK, database or global singleton. */
 export class FallbackPool<T> {
   private readonly candidates: readonly T[];
-  private readonly cooldowns = new Map<T, Cooldown>();
+  private readonly cooldowns: CooldownStore<T>;
+  private readonly probeStaleMs: number;
   private readonly now: () => number;
 
   constructor(
@@ -146,14 +204,21 @@ export class FallbackPool<T> {
       }
     }
     this.candidates = [...candidates];
+    this.cooldowns = options.cooldowns ?? new Map();
+    this.probeStaleMs = options.probeStaleMs ?? STREAM_PROGRESS_MS;
+    if (!Number.isFinite(this.probeStaleMs) || this.probeStaleMs < 0) {
+      throw new Error("providerkit: probeStaleMs must be finite, non-negative milliseconds");
+    }
     this.now = options.now ?? Date.now;
   }
 
   /** Clear a cooldown after replacing a key or fixing configuration. Omit the
-   *  candidate to clear all. Does not interrupt calls already in flight. */
+   *  candidate to clear all of this pool's own; a shared store keeps the benches
+   *  of candidates only other pools hold. Does not interrupt calls in flight. */
   reset(...selection: [] | [T]): void {
-    if (selection.length === 0) this.cooldowns.clear();
-    else this.cooldowns.delete(selection[0]);
+    for (const candidate of selection.length === 0 ? this.candidates : selection) {
+      this.cooldowns.delete(candidate);
+    }
   }
 
   status(): Array<{
@@ -163,12 +228,12 @@ export class FallbackPool<T> {
     kind?: ErrorKind;
     window?: RateLimitWindow;
   }> {
-    return this.candidates.map((candidate) => ({
-      candidate,
-      retryAtMs: 0,
-      probing: false,
-      ...this.cooldowns.get(candidate),
-    }));
+    return this.candidates.map((candidate) => {
+      const cooldown = this.cooldowns.get(candidate);
+      if (!cooldown) return { candidate, retryAtMs: 0, probing: false };
+      const { probe, ...bench } = cooldown;
+      return { candidate, ...bench, probing: probe !== undefined };
+    });
   }
 
   /** Buffered calls only: do not wrap an agent turn that has run side effects. */
@@ -192,74 +257,107 @@ export class FallbackPool<T> {
     signal?.throwIfAborted();
     let hasFailed = false;
     let lastError: unknown;
-    for (const candidate of this.candidates) {
-      signal?.throwIfAborted();
-      const previous = this.cooldowns.get(candidate);
-      if (previous && (previous.retryAtMs > this.now() || previous.probing)) continue;
-      // One recovery probe after expiry. Healthy endpoints still allow normal
-      // concurrency; only a known failed endpoint gets a single probe.
-      if (previous) previous.probing = true;
-      const controller = new AbortController();
-      const inner = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
-      let emitted = false;
-      let attemptFailed = false;
-      const startedWithCooldown = previous !== undefined;
-      try {
-        for await (const chunk of attempt(candidate, inner)) {
+    for (let round = 0; ; round++) {
+      const probing: Array<NonNullable<Cooldown["probe"]>> = [];
+      for (const candidate of this.candidates) {
+        signal?.throwIfAborted();
+        const previous = this.cooldowns.get(candidate);
+        if (previous && previous.retryAtMs > this.now()) continue;
+        if (previous?.probe && this.now() - previous.probe.since < this.probeStaleMs) {
+          probing.push(previous.probe);
+          continue;
+        }
+        // One recovery probe after expiry. Healthy endpoints still allow normal
+        // concurrency; only a known failed endpoint gets a single probe. A stale
+        // one is replaced: it hung, and holding the candidate for it is an outage.
+        const probe = previous ? openProbe(this.now()) : undefined;
+        if (previous) previous.probe = probe;
+        const controller = new AbortController();
+        const inner = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+        let emitted = false;
+        try {
+          for await (const chunk of attempt(candidate, inner)) {
+            inner.throwIfAborted();
+            if (!emitted) {
+              this.recovered(candidate, previous);
+              probe?.settle();
+            }
+            emitted = true;
+            yield chunk;
+          }
           inner.throwIfAborted();
-          emitted = true;
-          // Only a call that was admitted as a recovery probe (started while on cooldown)
-          // is authorized to clear that cooldown upon succeeding.
-          if (startedWithCooldown && this.cooldowns.get(candidate) === previous) {
-            this.cooldowns.delete(candidate);
+          if (!emitted) this.recovered(candidate, previous);
+          return;
+        } catch (error) {
+          signal?.throwIfAborted();
+          const kind = classify(error);
+          if (kind === "aborted") throw error;
+          const configured = this.options.cooldownMs?.[kind];
+          const interval = configured === undefined ? DEFAULT_FALLBACK_COOLDOWNS[kind] : configured;
+          if (interval === undefined || interval === null) throw error;
+          const now = this.now();
+          const after = parseRetryAfterMs(error);
+          const reset = error instanceof ProviderError ? error.resetAtMs : undefined;
+          const hints = [reset, after === undefined ? undefined : now + after].filter(
+            (value): value is number => value !== undefined && Number.isFinite(value),
+          );
+          const retryAtMs = Math.max(
+            now,
+            ...(hints.length ? hints : [now + interval]),
+            this.cooldowns.get(candidate)?.retryAtMs ?? 0,
+          );
+          const window = error instanceof ProviderError ? error.window : undefined;
+          this.cooldowns.set(candidate, { retryAtMs, kind, window });
+          this.options.onCooldown?.({ candidate, error, kind, retryAtMs, window });
+          hasFailed = true;
+          lastError = error;
+          if (emitted) throw error;
+        } finally {
+          controller.abort();
+          // Only the owner releases its probe. Clearing whatever probe was set
+          // let a stale probe that ended late free the one that replaced it, and
+          // any call that did not fail let a second probe in.
+          if (probe) {
+            if (previous?.probe === probe) previous.probe = undefined;
+            probe.settle();
           }
-          yield chunk;
-        }
-        inner.throwIfAborted();
-        if (startedWithCooldown && this.cooldowns.get(candidate) === previous) {
-          this.cooldowns.delete(candidate);
         }
-        return;
-      } catch (error) {
-        signal?.throwIfAborted();
-        const kind = classify(error);
-        if (kind === "aborted") throw error;
-        const configured = this.options.cooldownMs?.[kind];
-        const interval = configured === undefined ? DEFAULT_FALLBACK_COOLDOWNS[kind] : configured;
-        if (interval === undefined || interval === null) throw error;
-        const now = this.now();
-        const after = parseRetryAfterMs(error);
-        const reset = error instanceof ProviderError ? error.resetAtMs : undefined;
-        const hints = [reset, after === undefined ? undefined : now + after].filter(
-          (value): value is number => value !== undefined && Number.isFinite(value),
-        );
-        const retryAtMs = Math.max(
-          now,
-          ...(hints.length ? hints : [now + interval]),
-          this.cooldowns.get(candidate)?.retryAtMs ?? 0,
+      }
+      if (hasFailed) throw lastError;
+      // Nothing was free, and a probe is deciding whether something will be.
+      // Failing here answered a 0 ms retry, which `withRetry` spent at once: at
+      // 70 concurrent calls every one but the probe failed. Wait for a probe to
+      // answer or end, or until the oldest goes stale, then look again.
+      if (probing.length > 0 && round < PROBE_WAITS) {
+        const staleAt = Math.min(...probing.map((probe) => probe.since + this.probeStaleMs));
+        await waitForProbe(
+          probing.map((probe) => probe.settled),
+          staleAt - this.now(),
+          signal,
         );
-        const window = error instanceof ProviderError ? error.window : undefined;
-        this.cooldowns.set(candidate, { retryAtMs, kind, window, probing: false });
-        this.options.onCooldown?.({ candidate, error, kind, retryAtMs, window });
-        attemptFailed = true;
-        hasFailed = true;
-        lastError = error;
-        if (emitted) throw error;
-      } finally {
-        controller.abort();
-        const current = this.cooldowns.get(candidate);
-        if (current && current.probing && !attemptFailed) {
-          current.probing = false;
-        }
+        continue;
       }
+      // Every candidate is cooling, or its probe outlasted the waits; a probe
+      // still in flight makes the next opportunity now.
+      const retryAtMs = Math.min(
+        ...this.status().map((entry) => Math.max(this.now(), entry.retryAtMs)),
+      );
+      throw new NoAvailableProviderError(retryAtMs, this.now());
+    }
+  }
+
+  /** An answer proves the candidate serves again. It lifts the bench this call
+   *  was admitted under as the probe, and any bench a sibling set while it ran:
+   *  a call that started before one stray 401 and then answered used to leave
+   *  a busy primary benched for an hour. Rate and quota stay. A call that
+   *  started before the throttle proves nothing about the window, and lifting
+   *  it walks every caller back into the 429. */
+  private recovered(candidate: T, admittedUnder: Cooldown | undefined): void {
+    const current = this.cooldowns.get(candidate);
+    if (!current) return;
+    if (current === admittedUnder || (current.kind !== "rate" && current.kind !== "quota")) {
+      this.cooldowns.delete(candidate);
     }
-    if (hasFailed) throw lastError;
-    // If all expired candidates are already being probed, the next opportunity
-    // is now. Other callers need not wait for those probes or start duplicates.
-    const retryAtMs = Math.min(
-      ...this.status().map((entry) => Math.max(this.now(), entry.retryAtMs)),
-    );
-    throw new NoAvailableProviderError(retryAtMs, this.now());
   }
 }
 

package/src/image.ts

@@ -16,7 +16,7 @@ export interface ImageLimits {
   minSide: number;
   /** Smallest area, in square pixels. */
   minArea: number;
-  /** Largest decoded size — width × height × bytes per pixel — in bytes. */
+  /** Largest decoded size in bytes (width × height × bytes per pixel). */
   maxDecodedBytes: number;
   /** Most images in one request. The newest win; older ones become notes. */
   maxImages: number;

package/src/jev.ts

@@ -34,7 +34,7 @@ export type JevInstructions = string | Record<string, unknown> | readonly unknow
 export interface ChoiceQuestion<Option extends string = string> {
   type: "choice";
   instructions?: JevInstructions;
-  /** Each option, mapped to what it means — `null` when its name says it all.
+  /** Each option, mapped to what it means. Use `null` when its name says it all.
    *  TypeSafe takes up to 255. */
   criteria: Record<Option, unknown>;
 }
@@ -64,7 +64,7 @@ export interface ChoiceAnswer<Option extends string = string> {
    *  because a caller acting on it needs more than the pick: the runner-up,
    *  P(yes) when the pick was no, a joint probability across two questions. */
   probabilities: Record<Option, number>;
-  /** How peaked `probabilities` is, 0 to 1 — NOT the probability of the pick.
+  /** How peaked `probabilities` is, from 0 to 1. Not the probability of the pick.
    *  TypeSafe's own example spreads 0.57 / 0.43 and reports 0.35, so reading
    *  it as P(pick) would put the pick below the option it beat. Null when the
    *  host sent none. */
@@ -90,7 +90,7 @@ export interface ScoreAnswer {
 
 export type JevAnswer = ChoiceAnswer | NoulAnswer | ScoreAnswer;
 
-/** The answer type a question gets back — a choice's options carry through. */
+/** The answer type a question gets back. A choice's options carry through. */
 export type AnswerTo<Q> =
   Q extends ChoiceQuestion<infer Option extends string>
     ? ChoiceAnswer<Option>
@@ -101,12 +101,12 @@ export type AnswerTo<Q> =
         : never;
 
 export interface JevReply<Q extends Record<string, JevQuestion>> {
-  /** One per question — `null` when that answer did not pass the checks in
+  /** One per question. `null` when that answer did not pass the checks in
    *  `readAnswer`. Each fails alone: in a fan-out, a malformed answer to a
    *  question the caller never acts on must not cost the one it does. */
   answers: { [Id in keyof Q]: AnswerTo<Q[Id]> | null };
   usage: TokenUsage;
-  /** The model that answered, as the host names it — `jev-1.13.0` on
+  /** The model that answered, as the host names it: `jev-1.13.0` on
    *  TypeSafe, `typesafe/jev-1.13-20260917` on OpenRouter. */
   model: string;
 }
@@ -139,8 +139,8 @@ export interface JevClient {
   ): Promise<JevReply<Q>>;
   /** Proves the key, the account and the model work, with one real question:
    *  about 40 input tokens, a few millionths of a dollar. A free read (a
-   *  model list, a balance) proves only the key — not that this account can
-   *  run this model — and Vercel has none. Throws the classified failure. */
+   *  model list, a balance) proves only the key, not that this account can
+   *  run this model. Vercel has no such free read. Throws the classified failure. */
   checkKey(opts?: { signal?: AbortSignal }): Promise<void>;
 }
 
@@ -158,7 +158,7 @@ interface HostRow {
   url(config: JevConfig): string;
   headers(config: JevConfig, model: string): Record<string, string>;
   body(model: string, state: unknown, questions: Record<string, JevQuestion>): unknown;
-  /** The reply in TypeSafe's own shape — `{ model, answers, usage }` —
+  /** The reply in TypeSafe's own shape (`{ model, answers, usage }`),
    *  whatever the host wrapped it in. */
   unwrap(json: unknown): Record<string, unknown> | undefined;
 }
@@ -228,7 +228,7 @@ const HOSTS: Record<JevHost, HostRow> = {
  * `providerMetadata.typesafe.confidence`, and usage is camelCase.
  *
  * ponytail: read from @jkudish/jev-agent-tools' adapter, not from a recorded
- * reply — no Vercel key has run it here. If a real reply disagrees, this
+ * reply. No Vercel key has run it here. If a real reply disagrees, this
  * function is the whole fix.
  */
 function fromVercel(json: unknown): Record<string, unknown> | undefined {
@@ -282,7 +282,7 @@ function distribution(value: unknown, keys: readonly string[]): Record<string, n
 }
 
 /**
- * One answer, checked against the question that asked it — or null.
+ * One answer, checked against the question that asked it, or null.
  *
  * A Jev answer usually becomes an action (a click, a label, a route), so it is
  * read fail-closed: the right type; for a choice, a pick among the offered
@@ -291,7 +291,7 @@ function distribution(value: unknown, keys: readonly string[]): Record<string, n
  * the pick.
  *
  * `ask` runs this on every answer. It is exported for the app that has to
- * keep its own request — its own error copy, its own auth refresh — and can
+ * keep its own request (its own error copy, its own auth refresh) and can
  * still take the checks.
  */
 export function readAnswer<Q extends JevQuestion>(question: Q, raw: unknown): AnswerTo<Q> | null;