@providerkit/core 0.7.1 → 0.8.1

package/dist/types.d.ts

@@ -112,6 +112,12 @@ export declare 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
@@ -195,6 +201,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[];

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -37,7 +37,10 @@ export async function drainStream(stream, model) {
     let reasoningDetails;
     let usage = EMPTY_USAGE;
     let finishReason = null;
+    let source;
     for await (const chunk of stream) {
+        if (chunk.source)
+            source = chunk.source;
         if (chunk.type === "delta") {
             if (chunk.content)
                 text += chunk.content;
@@ -59,7 +62,8 @@ export async function drainStream(stream, model) {
         ...(reasoningDetails ? { reasoningDetails } : {}),
         usage,
         finishReason,
-        model,
+        model: source?.model ?? model,
+        ...(source ? { provider: source.provider } : {}),
     };
 }
 /**

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.1",
   "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,254 @@
+import { classify, parseRetryAfterMs, ProviderError, type ErrorKind } from "./errors.ts";
+import type { RateLimitWindow } from "./rate-limit.ts";
+import type { ProviderPresetId } from "./presets.ts";
+import type { Provider, ProviderChunk } from "./types.ts";
+import { createPresetProvider, type PresetProviderConfig } from "./providers/factory.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;
+}
+
+/**
+ * A fallback named by PRESET id rather than hand-built: the endpoint, auth
+ * style, effort dialect and every measured quirk come from the presets table,
+ * so a consumer writes neither a baseUrl nor a model-spelling rule. A
+ * hand-built `Provider` is still accepted wherever a spec is.
+ */
+export interface FallbackSpec extends PresetProviderConfig {
+  preset: ProviderPresetId;
+}
+
+export type FallbackCandidate = Provider | FallbackSpec;
+
+function resolveFallback(candidate: FallbackCandidate): Provider {
+  if (typeof candidate === "object" && candidate !== null && "createStream" in candidate) {
+    return candidate;
+  }
+  const { preset, ...config } = candidate;
+  return createPresetProvider(preset, config);
+}
+
+/** 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:
+   *  hand-built `Provider`s, preset-id `FallbackSpec`s, or both. */
+  fallbacks?: readonly FallbackCandidate[];
+  /** 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.map(resolveFallback)],
+    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 } : {}),
+  };
+}