@providerkit/core 0.7.1 → 0.8.0

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2EAA2E;AAC3E,mEAAmE;AACnE,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,0BAA0B;AAE1B;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AAGzE,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC;AACpD,CAAC;AA4GD,MAAM,CAAC,MAAM,WAAW,GAAe;IACrC,WAAW,EAAE,CAAC;IACd,iBAAiB,EAAE,CAAC;IACpB,YAAY,EAAE,CAAC;CAChB,CAAC;AAwGF;kEACkE;AAClE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAoC,EACpC,KAAa;IAEb,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,4EAA4E;IAC5E,4EAA4E;IAC5E,yEAAyE;IACzE,6DAA6D;IAC7D,IAAI,gBAAuC,CAAC;IAC5C,IAAI,KAAK,GAAe,WAAW,CAAC;IACpC,IAAI,YAAY,GAAwB,IAAI,CAAC;IAC7C,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,OAAO;gBAAE,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC;YACzC,IAAI,KAAK,CAAC,SAAS;gBAAE,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC;YAClD,IAAI,KAAK,CAAC,gBAAgB,EAAE,MAAM;gBAAE,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,CAAC;QAChF,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACjD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACtB,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACzD,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QACpC,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI;QACJ,SAAS;QACT,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,KAAK;QACL,YAAY;QACZ,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgC;IAC7D,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,OAAO,CAAC;QACjD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,gBAAgB,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC;QAC9F,yEAAyE;QACzE,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,IAAe;IACvC,OAAO,QAAQ,IAAI,CAAC,QAAQ,WAAW,IAAI,CAAC,IAAI,EAAE,CAAC;AACrD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@providerkit/core",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "The layer under your agent loop: one seam for every LLM provider, plus the failure handling you only learn in production.",
   "type": "module",
   "license": "MIT",

package/src/errors.ts

@@ -10,6 +10,8 @@
 // read before the status — status alone gives the wrong advice ("retry" for an
 // empty balance, "check your key" for a plan that never included the API).
 
+import { parseUsageLimitBody, type RateLimitWindow } from "./rate-limit.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. */
@@ -67,6 +69,9 @@ export class ProviderError extends Error {
   /** Honoured when the provider said how long to wait (Retry-After, or
    *  Gemini's RetryInfo.retryDelay). */
   readonly retryAfterMs?: number;
+  /** Absolute reset of the binding limit. Can be days beyond Retry-After. */
+  readonly resetAtMs?: number;
+  readonly window?: RateLimitWindow;
   /** The provider's own response body, truncated — the actual reason, which is
    *  otherwise lost behind "400 status code (no body)". */
   readonly body?: string;
@@ -79,6 +84,8 @@ export class ProviderError extends Error {
       status?: number;
       code?: string;
       retryAfterMs?: number;
+      resetAtMs?: number;
+      window?: RateLimitWindow;
       body?: string;
       cause?: unknown;
     } = {},
@@ -90,6 +97,8 @@ export class ProviderError extends Error {
     this.status = opts.status;
     this.code = opts.code;
     this.retryAfterMs = opts.retryAfterMs;
+    this.resetAtMs = opts.resetAtMs;
+    this.window = opts.window;
     this.body = opts.body;
   }
 
@@ -113,6 +122,7 @@ export class ProviderError extends Error {
       status,
       code,
       retryAfterMs: parseRetryAfterMs(err, body),
+      ...parseUsageLimitBody(body),
       body: body.slice(0, 2_000) || undefined,
       cause: err,
     });
@@ -411,7 +421,13 @@ export function classify(err: unknown, status?: number, body?: string): ErrorKin
  * backoff shorter than the window just burns an attempt.
  */
 export function parseRetryAfterMs(err: unknown, body?: string): number | undefined {
+  // Adapters already normalized the response headers. Re-parsing only the body
+  // discarded this property and made retries ignore their own Retry-After.
+  const normalized = readNumber(err, "retryAfterMs");
+  if (normalized !== undefined && Number.isFinite(normalized) && normalized >= 0) return normalized;
   const text = body ?? bodyTextOf(err);
+  const usageLimit = parseUsageLimitBody(text);
+  if (usageLimit.retryAfterMs !== undefined) return usageLimit.retryAfterMs;
   const delay = text.match(/"?retryDelay"?\s*[:=]\s*"?(\d+(?:\.\d+)?)s"?/i);
   if (delay?.[1]) return Math.round(parseFloat(delay[1]) * 1000);
 
@@ -467,6 +483,7 @@ export function streamError(provider: string, error: unknown): ProviderError {
       ...(status !== undefined ? { status } : {}),
       ...(code ? { code } : {}),
       retryAfterMs: parseRetryAfterMs(error, body),
+      ...parseUsageLimitBody(body),
       body: body.slice(0, 2_000),
     },
   );
@@ -482,6 +499,8 @@ export function describeProviderError(err: unknown): Record<string, unknown> {
       status: err.status,
       code: err.code,
       retryAfterMs: err.retryAfterMs,
+      resetAtMs: err.resetAtMs,
+      window: err.window,
       error: err.message,
       body: err.body,
     };

package/src/fallback.ts

@@ -0,0 +1,228 @@
+import { classify, parseRetryAfterMs, ProviderError, type ErrorKind } from "./errors.ts";
+import type { RateLimitWindow } from "./rate-limit.ts";
+import type { Provider, ProviderChunk } from "./types.ts";
+
+/** Retry intervals when the server supplies no deadline, not estimates of when
+ *  it will recover. A server deadline always wins over these defaults. */
+export const DEFAULT_FALLBACK_COOLDOWNS: Readonly<Partial<Record<ErrorKind, number>>> = Object.freeze({
+  rate: 60_000,
+  quota: 3_600_000,
+  timeout: 30_000,
+  network: 30_000,
+  overload: 30_000,
+  auth: 3_600_000,
+  entitlement: 3_600_000,
+  model: 3_600_000,
+});
+
+export interface FallbackOptions<T> {
+  /** Per-kind intervals in ms; null stops fallback for that kind. Adding a kind
+   *  opts it into fallback. Cancellation is never overridable. */
+  cooldownMs?: Partial<Record<ErrorKind, number | null>>;
+  onCooldown?: (info: {
+    candidate: T;
+    error: unknown;
+    kind: ErrorKind;
+    retryAtMs: number;
+    window?: RateLimitWindow;
+  }) => void;
+  /** Inject a clock for deterministic tests. */
+  now?: () => number;
+}
+
+/** Standard options that any provider config can accept to configure fallbacks inline. */
+export interface ProviderFallbackConfig {
+  /** Secondary and tertiary providers to try if this provider fails/exhausts. */
+  fallbacks?: readonly Provider[];
+  /** Custom cooldown or telemetry options for the fallback pool. */
+  fallbackOptions?: FallbackOptions<Provider>;
+}
+
+/**
+ * Wrap a primary provider with its fallbacks if any are specified.
+ * Returns the primary provider untouched when fallbacks is empty or omitted.
+ */
+export function withConfiguredFallbacks(
+  primary: Provider,
+  config?: ProviderFallbackConfig,
+): Provider {
+  if (!config?.fallbacks || config.fallbacks.length === 0) return primary;
+  return withFallbackProviders([primary, ...config.fallbacks], config.fallbackOptions);
+}
+
+interface Cooldown {
+  retryAtMs: number;
+  kind: ErrorKind;
+  window?: RateLimitWindow;
+  probing: boolean;
+}
+
+/** The whole chain is unavailable. Fail promptly instead of holding a request
+ *  open for hours. `retryAtMs` names its next opportunity, not a sleep to cap. */
+export class NoAvailableProviderError extends ProviderError {
+  readonly retryAtMs: number;
+
+  constructor(retryAtMs: number, now: number) {
+    super("fallback", "rate", "All configured providers are unavailable. Retry after the cooldown.", {
+      resetAtMs: retryAtMs,
+      retryAfterMs: Math.max(0, retryAtMs - now),
+    });
+    this.name = "NoAvailableProviderError";
+    this.retryAtMs = retryAtMs;
+  }
+}
+
+/** Ordered candidates with cooldowns shared across calls. Keep one pool alive
+ *  per credential set: rebuilding it per request forgets a weekly lockout.
+ *  State is in-memory and process-local; `status` and `reset` expose it without
+ *  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 now: () => number;
+
+  constructor(candidates: readonly T[], private readonly options: FallbackOptions<T> = {}) {
+    if (candidates.length === 0) throw new Error("providerkit: supply a primary before its backups");
+    if (new Set(candidates).size !== candidates.length) {
+      throw new Error("providerkit: each fallback candidate must appear only once");
+    }
+    for (const value of Object.values(options.cooldownMs ?? {})) {
+      if (value !== null && value !== undefined && (!Number.isFinite(value) || value < 0)) {
+        throw new Error("providerkit: fallback cooldowns must be finite, non-negative milliseconds");
+      }
+    }
+    this.candidates = [...candidates];
+    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. */
+  reset(...selection: [] | [T]): void {
+    if (selection.length === 0) this.cooldowns.clear();
+    else this.cooldowns.delete(selection[0]);
+  }
+
+  status(): Array<{ candidate: T; retryAtMs: number; probing: boolean; kind?: ErrorKind; window?: RateLimitWindow }> {
+    return this.candidates.map((candidate) => ({
+      candidate,
+      retryAtMs: 0,
+      probing: false,
+      ...this.cooldowns.get(candidate),
+    }));
+  }
+
+  /** Buffered calls only: do not wrap an agent turn that has run side effects. */
+  async with<R>(attempt: (candidate: T, signal: AbortSignal) => Promise<R>, signal?: AbortSignal): Promise<R> {
+    for await (const result of this.stream(async function* (candidate, inner) {
+      yield await attempt(candidate, inner);
+    }, signal)) return result;
+    throw new Error("providerkit: fallback attempt ended without a result");
+  }
+
+  /** Only a pre-output failure can switch provider. A later failure still
+   *  cools the endpoint for FUTURE calls but never restarts the current answer. */
+  async *stream<R>(
+    attempt: (candidate: T, signal: AbortSignal) => AsyncIterable<R>,
+    signal?: AbortSignal,
+  ): AsyncGenerator<R> {
+    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)) {
+          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);
+          }
+          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,
+        );
+        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;
+        }
+      }
+    }
+    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());
+  }
+}
+
+export interface FallbackProvider extends Provider {
+  readonly fallbacks: FallbackPool<Provider>;
+}
+
+/** Compose bound provider/model pairs. Identity names the configured primary;
+ *  chunk.source names the endpoint that answered. Per-call model overrides
+ *  apply ONLY to the primary because model ids are endpoint-specific.
+ *  Keep this provider alive across calls so its cooldowns survive. */
+export function withFallbackProviders(
+  providers: readonly Provider[],
+  options: FallbackOptions<Provider> = {},
+): FallbackProvider {
+  const fallbacks = new FallbackPool(providers, options);
+  const primary = providers[0]!;
+  return {
+    id: primary.id,
+    model: primary.model,
+    fallbacks,
+    createStream(messages, tools, opts = {}) {
+      return fallbacks.stream(async function* (provider, signal): AsyncGenerator<ProviderChunk> {
+        const { model: override, ...rest } = opts;
+        const model = provider === primary ? (override ?? provider.model) : provider.model;
+        for await (const chunk of provider.createStream(messages, tools, { ...rest, model, signal })) {
+          yield { ...chunk, source: chunk.source ?? { provider: provider.id, model } };
+        }
+      }, opts.signal);
+    },
+  };
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./types.ts";
 export * from "./errors.ts";
 export * from "./retry.ts";
+export * from "./fallback.ts";
 export * from "./key-pool.ts";
 export * from "./watchdog.ts";
 export * from "./usage.ts";

package/src/providers/anthropic.ts

@@ -3,6 +3,7 @@ import { streamError } from "../errors.ts";
 import { schemaPrompt } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
+import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 import type {
   JsonOutput,
   ChatMessage,
@@ -15,7 +16,7 @@ import type {
   ToolDefinition,
 } from "../types.ts";
 
-export interface AnthropicConfig {
+export interface AnthropicConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
   /** Any endpoint speaking the Anthropic Messages dialect — a proxy or gateway.
@@ -219,7 +220,7 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "anthropic";
 
-  return {
+  const provider: Provider = {
     id,
     model: config.model,
 
@@ -382,4 +383,5 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       }
     },
   };
+  return withConfiguredFallbacks(provider, config);
 }

package/src/providers/factory.ts

@@ -21,8 +21,9 @@ import {
   type ProviderPresetId,
 } from "../presets.ts";
 import type { Effort, Provider } from "../types.ts";
+import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 
-export interface PresetProviderConfig {
+export interface PresetProviderConfig extends ProviderFallbackConfig {
   /** The credential: an API key for `key`/`bearer` presets, an ACCESS TOKEN
    *  for `oauth` ones. Acquiring the token is the caller's job. */
   apiKey: string;
@@ -58,11 +59,15 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
   }
   const headers = { ...preset.headers, ...config.headers };
 
+  const { fallbacks: _fallbacks, fallbackOptions: _fallbackOptions, ...baseConfig } = config;
+
+  let provider: Provider;
   switch (preset.shape) {
     case "anthropic":
       // `key` rides Anthropic's native x-api-key; coding plans and OAuth
       // tokens read Bearer (measured across the family's coding endpoints).
-      return createAnthropicProvider({
+      provider = createAnthropicProvider({
+        ...baseConfig,
         apiKey: config.apiKey,
         model,
         effort: config.effort,
@@ -76,8 +81,10 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         ...(preset.explicitNone ? { explicitNone: true } : {}),
         fetchImpl: config.fetchImpl,
       });
+      break;
     case "openai":
-      return createOpenAIProvider({
+      provider = createOpenAIProvider({
+        ...baseConfig,
         id,
         apiKey: config.apiKey,
         model,
@@ -88,8 +95,10 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         ...(config.providerOrder ? { providerOrder: config.providerOrder } : {}),
         fetchImpl: config.fetchImpl,
       });
+      break;
     case "responses":
-      return createResponsesProvider({
+      provider = createResponsesProvider({
+        ...baseConfig,
         apiKey: config.apiKey,
         model,
         effort: config.effort,
@@ -99,8 +108,10 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         headers,
         fetchImpl: config.fetchImpl,
       });
+      break;
     case "gemini":
-      return createGeminiProvider({
+      provider = createGeminiProvider({
+        ...baseConfig,
         apiKey: config.apiKey,
         model,
         effort: config.effort,
@@ -109,5 +120,8 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         headers,
         fetchImpl: config.fetchImpl,
       });
+      break;
   }
+
+  return withConfiguredFallbacks(provider, config);
 }

package/src/providers/gemini.ts

@@ -9,6 +9,7 @@ import { streamError } from "../errors.ts";
 import { schemaPrompt } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
+import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 import type {
   ChatMessage,
   Effort,
@@ -22,7 +23,7 @@ import type {
   ToolDefinition,
 } from "../types.ts";
 
-export interface GeminiConfig {
+export interface GeminiConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
   /** Any endpoint speaking the Generative Language REST dialect — a proxy or
@@ -247,7 +248,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "gemini";
 
-  return {
+  const provider: Provider = {
     id,
     model: config.model,
 
@@ -409,4 +410,6 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       }
     },
   };
+
+  return withConfiguredFallbacks(provider, config);
 }

package/src/providers/openai.ts

@@ -18,8 +18,9 @@ import type {
 } from "../types.ts";
 import { toDataUri } from "../types.ts";
 import { isStrictSchema, schemaPrompt } from "../schema.ts";
+import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 
-export interface OpenAIConfig {
+export interface OpenAIConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
   /** Any OpenAI-compatible endpoint. Defaults to OpenAI itself. */
@@ -305,7 +306,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "openai";
 
-  return {
+  const provider: Provider = {
     id,
     model: config.model,
 
@@ -489,4 +490,6 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       }
     },
   };
+
+  return withConfiguredFallbacks(provider, config);
 }

package/src/providers/responses.ts

@@ -25,8 +25,9 @@ import type {
 } from "../types.ts";
 import { toDataUri } from "../types.ts";
 import { isStrictSchema } from "../schema.ts";
+import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 
-export interface ResponsesConfig {
+export interface ResponsesConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
   /** Any endpoint speaking the Responses format. Defaults to OpenAI itself. */
@@ -226,7 +227,7 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "openai-responses";
 
-  return {
+  const provider: Provider = {
     id,
     model: config.model,
 
@@ -463,4 +464,6 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
       // included, was already yielded as it arrived.
     },
   };
+
+  return withConfiguredFallbacks(provider, config);
 }

package/src/rate-limit.ts

@@ -215,3 +215,25 @@ export function parseUsageLimitBody(bodyText: string, now = Date.now()): RateLim
   }
   return result;
 }
+
+/** Read both places an endpoint can report its reset. A short Retry-After is
+ *  not evidence that a longer subscription window has lifted. */
+export function parseRateLimitResponse(
+  headers: Headers,
+  bodyText: string,
+  now = Date.now(),
+): RateLimitReset {
+  const header = parseRateLimitReset(headers, now);
+  const body = parseUsageLimitBody(bodyText, now);
+  const resetAtMs = Math.max(header.resetAtMs ?? 0, body.resetAtMs ?? 0);
+  const retryAfterMs = header.retryAfterMs ?? body.retryAfterMs;
+  const window =
+    body.resetAtMs !== undefined && body.resetAtMs > (header.resetAtMs ?? 0)
+      ? body.window
+      : (header.window ?? body.window);
+  return {
+    ...(resetAtMs > 0 ? { resetAtMs } : {}),
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    ...(window ? { window } : {}),
+  };
+}

package/src/retry.ts

@@ -13,12 +13,14 @@
 //
 //  3. Honour the provider's own number. When it says `Retry-After: 30`, a
 //     one-second backoff is three wasted attempts before the same wait.
-import { classify, isBackupEligible, isTransient, parseRetryAfterMs } from "./errors.ts";
+import { classify, isBackupEligible, isTransient, parseRetryAfterMs, ProviderError } from "./errors.ts";
 
 export interface RetryOptions {
   /** Total attempts including the first. Default 3. */
   maxAttempts?: number;
   baseDelayMs?: number;
+  /** 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;
   /** Aborts the wait as well as the work, so Stop lands promptly. */
   signal?: AbortSignal;
@@ -67,12 +69,17 @@ export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
-/** The delay before the next attempt: the provider's own figure when it gave
- *  one, capped, else full-jitter backoff. */
-function delayFor(err: unknown, attempt: number, opts: RetryOptions): number {
+/** null means the server deadline exceeds this call's wait budget. */
+function delayFor(err: unknown, attempt: number, opts: RetryOptions): number | null {
   const asked = parseRetryAfterMs(err);
   const cap = opts.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
-  if (asked !== undefined) return Math.min(asked, cap);
+  const resetWait = err instanceof ProviderError && err.resetAtMs !== undefined
+    ? Math.max(0, err.resetAtMs - Date.now())
+    : undefined;
+  if (asked !== undefined || resetWait !== undefined) {
+    const wait = Math.max(asked ?? 0, resetWait ?? 0);
+    return wait > cap ? null : wait;
+  }
   return backoffMs(attempt, opts.baseDelayMs ?? DEFAULT_BASE_DELAY_MS, cap);
 }
 
@@ -101,6 +108,7 @@ export async function withRetry<T>(
       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);
     }
@@ -149,6 +157,7 @@ export async function* withStreamRetry<T>(
       // 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);
     } finally {

package/src/transport.ts

@@ -4,7 +4,8 @@
 //
 // Adapters keep only their per-event mapping; everything about being an HTTP
 // client lives here once.
-import { classifyHttp, isTransportFailure, ProviderError } from "./errors.ts";
+import { classifyHttp, isTransportFailure, parseRetryAfterMs, ProviderError } from "./errors.ts";
+import { parseRateLimitResponse } from "./rate-limit.ts";
 
 export interface RequestInit_ {
   url: string;
@@ -63,12 +64,14 @@ export function retryAfterFromHeaders(headers: Headers, now = Date.now()): numbe
 async function errorFor(provider: string, res: Response): Promise<ProviderError> {
   const text = await res.text().catch(() => "");
   const kind = classifyHttp(res.status, text);
+  const reset = parseRateLimitResponse(res.headers, text);
   const message = text
     ? `${provider} ${res.status}: ${text.slice(0, 500)}`
     : `${provider} ${res.status} ${res.statusText}`;
   return new ProviderError(provider, kind, message, {
     status: res.status,
-    retryAfterMs: retryAfterFromHeaders(res.headers),
+    ...reset,
+    retryAfterMs: retryAfterFromHeaders(res.headers) ?? parseRetryAfterMs({}, text),
     body: text.slice(0, 2_000) || undefined,
   });
 }

package/src/types.ts

@@ -139,6 +139,9 @@ export const EMPTY_USAGE: TokenUsage = {
 /** Normalized streaming chunk — every provider's shape collapses into this. */
 export interface ProviderChunk {
   type: "delta" | "usage" | "finish";
+  /** The selected endpoint and model when a fallback provider emits this chunk.
+   *  Per-call metadata, never shared mutable state on the provider object. */
+  source?: { provider: string; model: string };
   content?: string;
   reasoning?: string;
   /** OpenRouter's normalized reasoning payload — hand it back on the next
@@ -230,6 +233,8 @@ export interface Provider {
 
 export interface Completion {
   text: string;
+  /** Present when the stream identifies the endpoint that answered. */
+  provider?: string;
   reasoning: string;
   /** Present only where the provider sent one. See ChatMessage.reasoningDetails. */
   reasoningDetails?: unknown[];
@@ -253,7 +258,9 @@ export async function drainStream(
   let reasoningDetails: unknown[] | undefined;
   let usage: TokenUsage = EMPTY_USAGE;
   let finishReason: FinishReason | null = null;
+  let source: ProviderChunk["source"];
   for await (const chunk of stream) {
+    if (chunk.source) source = chunk.source;
     if (chunk.type === "delta") {
       if (chunk.content) text += chunk.content;
       if (chunk.reasoning) reasoning += chunk.reasoning;
@@ -270,7 +277,8 @@ export async function drainStream(
     ...(reasoningDetails ? { reasoningDetails } : {}),
     usage,
     finishReason,
-    model,
+    model: source?.model ?? model,
+    ...(source ? { provider: source.provider } : {}),
   };
 }