@naced/llm-multi-rate-limiter 0.1.0 → 0.1.2

package/lib/config-resolve.js

@@ -0,0 +1,259 @@
+/**
+ * Pure configuration-resolution helpers.
+ *
+ * Kept free of Cordis, schemastery and timers so the unit tests can exercise
+ * the precedence rules, the wildcard matcher and the 429 cooldown machine with
+ * plain objects.
+ *
+ * Precedence for one call (`provider/model`):
+ *
+ *     models["<provider>/<model>"]      exact model key
+ *   > models["<pattern with *>"]        wildcard model key (most specific first)
+ *   > providers["<provider>"]           provider-wide tier
+ *   > defaults                          global tier
+ *
+ * @module dsh-llm-multi-rate-limiter/config-resolve
+ */
+
+/** Sliding-window width. `maxRpm` is "per minute", so the window is a minute. */
+export const WINDOW_MS = 60_000;
+
+/** Chars that would change the meaning of the generated regexp. */
+const REGEXP_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+
+function escapeRegExp(text) {
+  return text.replace(REGEXP_SPECIALS, "\\$&");
+}
+
+/**
+ * Compile a `*`-wildcard key into a matcher.
+ *
+ * `*` matches any run of characters that does not cross a `/`, so
+ * `openai/*` matches `openai/gpt-5.1` but not `openai/gpt-5.1/turbo`, and
+ * `*` alone matches every provider/model pair.
+ *
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+export function compilePattern(pattern) {
+  const source = pattern.split("*").map(escapeRegExp).join("[^/]*");
+  return new RegExp(`^${source}$`);
+}
+
+/** True when `key` contains a wildcard and is therefore a pattern, not a key. */
+export function isPattern(key) {
+  return key.includes("*");
+}
+
+/** Number of literal characters a pattern pins down — its specificity score. */
+function specificity(pattern) {
+  return pattern.length - pattern.split("*").length + 1;
+}
+
+/**
+ * Find the override that applies to `key` in a `{ key: override }` dict.
+ *
+ * Exact keys always win over patterns. When several patterns match, the most
+ * specific one wins (most literal characters); remaining ties break on the
+ * longer pattern so the choice is stable across runs.
+ *
+ * @param {Record<string, object> | undefined} dict
+ * @param {string} key
+ * @returns {{ override: object, matched: string } | undefined}
+ */
+export function matchOverride(dict, key) {
+  if (dict === null || typeof dict !== "object") return undefined;
+
+  const exact = dict[key];
+  if (exact !== null && typeof exact === "object") return { override: exact, matched: key };
+
+  /** @type {Array<{ pattern: string, override: object, score: number }>} */
+  const candidates = [];
+  for (const [pattern, override] of Object.entries(dict)) {
+    if (!isPattern(pattern)) continue;
+    if (override === null || typeof override !== "object") continue;
+    if (!compilePattern(pattern).test(key)) continue;
+    candidates.push({ pattern, override, score: specificity(pattern) });
+  }
+  if (candidates.length === 0) return undefined;
+
+  candidates.sort((a, b) => b.score - a.score || b.pattern.length - a.pattern.length);
+  return { override: candidates[0].override, matched: candidates[0].pattern };
+}
+
+/** Provider half of a `provider/model` key. */
+export function providerOf(key) {
+  const slash = key.indexOf("/");
+  return slash === -1 ? key : key.slice(0, slash);
+}
+
+/**
+ * Flatten the four config tiers into the flat shape the strategies understand.
+ *
+ * @param {object} cfg plain config (`{ defaults, providers, models }`)
+ * @param {string} key `provider/model` of the call being limited
+ * @returns {{ maxConcurrent: number, maxRpm: number, burstSize: number,
+ *   refillRate: number, windowMs: number, source: "model" | "provider" | "defaults",
+ *   matchedKey: string }}
+ */
+export function resolveModelConfig(cfg, key) {
+  const defaults = cfg?.defaults ?? {};
+  const modelHit = matchOverride(cfg?.models, key);
+  const providerId = providerOf(key);
+  const providerHit = matchOverride(cfg?.providers, providerId);
+
+  const model = modelHit?.override ?? {};
+  const provider = providerHit?.override ?? {};
+  const source = modelHit !== undefined ? "model" : providerHit !== undefined ? "provider" : "defaults";
+
+  const maxRpm = model.maxRpm ?? provider.maxRpm ?? defaults.maxRpm ?? 60;
+  // A model/provider that sets maxRpm but not refillRate gets a refill derived
+  // from ITS maxRpm, so "maxRpm: 20" alone behaves as 20 per minute. When the
+  // winning tier does not touch maxRpm, the narrower tier's refillRate (if any)
+  // is used as-is.
+  const explicitRefill = model.refillRate ?? provider.refillRate;
+  const refillRate = explicitRefill
+    ?? ((model.maxRpm ?? provider.maxRpm) != null
+      ? maxRpm / 60
+      : defaults.refillRate ?? maxRpm / 60);
+
+  return {
+    maxConcurrent: model.maxConcurrent ?? provider.maxConcurrent ?? defaults.maxConcurrent ?? 5,
+    maxRpm,
+    burstSize: model.burstSize ?? provider.burstSize ?? defaults.burstSize ?? 10,
+    refillRate,
+    windowMs: WINDOW_MS,
+    source,
+    matchedKey: modelHit?.matched ?? providerHit?.matched ?? "(defaults)",
+  };
+}
+
+/** Scale one resolved config down by `factor` (never below the usable floor). */
+export function scaleConfig(resolved, factor) {
+  if (!(factor < 1)) return resolved;
+  return {
+    ...resolved,
+    maxRpm: Math.max(1, Math.round(resolved.maxRpm * factor)),
+    burstSize: Math.max(1, Math.round(resolved.burstSize * factor)),
+    refillRate: Math.max(0.01, resolved.refillRate * factor),
+  };
+}
+
+/**
+ * Per-model 429 cooldown.
+ *
+ * A rate limiter that only counts requests cannot know that the provider
+ * throttled us for a reason of its own (a shared quota, a burst it did not
+ * like). Treating a `RATE_LIMIT` failure from the provider as a signal keeps
+ * the next calls from walking into the same wall: the model's rate is scaled
+ * down for `cooldownMs`, then restored after `recoverAfter` clean calls.
+ *
+ * Pure state machine: the caller supplies `now`, so tests need no clock.
+ */
+export class CooldownTracker {
+  /** @type {Map<string, { until: number, factor: number, clean: number }>} */
+  #state = new Map();
+
+  /**
+   * @param {{ enabled?: boolean, cooldownMs?: number, factor?: number, recoverAfter?: number }} options
+   */
+  constructor(options = {}) {
+    this.enabled = options.enabled !== false;
+    /** How long a throttled model stays slowed down. */
+    this.cooldownMs = Number.isFinite(options.cooldownMs) ? options.cooldownMs : 30_000;
+    /** Rate multiplier applied while cooling (0 < factor < 1). */
+    this.factor = Number.isFinite(options.factor) ? Math.min(0.9, Math.max(0.05, options.factor)) : 0.5;
+    /** Clean calls required before the full rate is restored. */
+    this.recoverAfter = Number.isFinite(options.recoverAfter) ? Math.max(1, options.recoverAfter) : 3;
+  }
+
+  /** Re-read policy fields from the live config. */
+  configure(options = {}) {
+    if (typeof options.enabled === "boolean") this.enabled = options.enabled;
+    if (Number.isFinite(options.cooldownMs)) this.cooldownMs = options.cooldownMs;
+    if (Number.isFinite(options.factor)) this.factor = Math.min(0.9, Math.max(0.05, options.factor));
+    if (Number.isFinite(options.recoverAfter)) this.recoverAfter = Math.max(1, options.recoverAfter);
+  }
+
+  /**
+   * Current rate multiplier for `key` (1 when not cooling).
+   *
+   * @param {string} key
+   * @param {number} [now]
+   */
+  factorFor(key, now = Date.now()) {
+    const entry = this.#state.get(key);
+    if (entry === undefined) return 1;
+    if (entry.until > now) return entry.factor;
+    // Cooldown elapsed: stay scaled down until enough clean calls have passed.
+    return entry.clean >= this.recoverAfter ? 1 : entry.factor;
+  }
+
+  /**
+   * Record a provider-side `RATE_LIMIT` failure.
+   *
+   * @param {string} key
+   * @param {number} [now]
+   * @param {number} [retryAfterMs] provider hint, when known
+   * @returns {{ until: number, factor: number } | undefined}
+   */
+  recordFailure(key, now = Date.now(), retryAfterMs = undefined) {
+    if (!this.enabled) return undefined;
+    const hold = Number.isFinite(retryAfterMs) && retryAfterMs > 0
+      ? Math.max(this.cooldownMs, retryAfterMs)
+      : this.cooldownMs;
+    const entry = { until: now + hold, factor: this.factor, clean: 0 };
+    this.#state.set(key, entry);
+    return entry;
+  }
+
+  /**
+   * Record a call that completed without a provider-side 429, retiring the
+   * cooldown once enough of them have accumulated.
+   *
+   * @param {string} key
+   * @param {number} [now]
+   */
+  recordSuccess(key, now = Date.now()) {
+    const entry = this.#state.get(key);
+    if (entry === undefined) return;
+    if (entry.until > now) return; // still cooling: a success does not end it early
+    entry.clean += 1;
+    if (entry.clean >= this.recoverAfter) this.#state.delete(key);
+  }
+
+  /** True while `key` is inside its cooldown window. */
+  isCooling(key, now = Date.now()) {
+    const entry = this.#state.get(key);
+    return entry !== undefined && entry.until > now;
+  }
+
+  /** Milliseconds until the cooldown ends (0 when not cooling). */
+  remainingMs(key, now = Date.now()) {
+    const entry = this.#state.get(key);
+    return entry === undefined ? 0 : Math.max(0, entry.until - now);
+  }
+
+  /** Drop every cooldown (config reset / panel action). */
+  clear() {
+    this.#state.clear();
+  }
+
+  /** Drop the state of one model. */
+  forget(key) {
+    this.#state.delete(key);
+  }
+
+  /** JSON-safe view for the status channel. */
+  snapshot(now = Date.now()) {
+    const models = {};
+    for (const [key, entry] of this.#state) {
+      models[key] = {
+        cooling: entry.until > now,
+        remainingMs: Math.max(0, entry.until - now),
+        factor: entry.factor,
+      };
+    }
+    return models;
+  }
+}

package/lib/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Type declarations for the host entry point.
+ *
+ * The plugin ships no build step, so these are hand-written against the shapes
+ * `lib/index.js` actually uses. The `Config` export is a schemastery schema
+ * (validated at load time by Cordis); it is typed as `unknown` rather than
+ * pretending to model schemastery's builder.
+ */
+
+/** Limits shared by the `defaults`, `providers` and `models` tiers. */
+export interface RateLimitTier {
+  /** Max concurrent in-flight requests for this tier. */
+  maxConcurrent?: number;
+  /** Max requests per minute for this tier. */
+  maxRpm?: number;
+  /** Burst capacity (token-bucket only). */
+  burstSize?: number;
+  /** Tokens refilled per second (token-bucket only). */
+  refillRate?: number;
+}
+
+/** A `models` override. Keys may be exact (`provider/model`) or wildcarded (`provider/*`). */
+export interface ModelOverride extends RateLimitTier {
+  /** Set `false` to exempt this model (or pattern) from limiting entirely. */
+  enabled?: boolean;
+}
+
+/** Adaptive back-off applied after the provider answers 429. */
+export interface CooldownConfig {
+  /** Master switch for the 429 cooldown. */
+  enabled?: boolean;
+  /** How long the reduced rate lasts, in milliseconds. */
+  cooldownMs?: number;
+  /** Rate multiplier while cooling, in `(0, 1)`. Defaults to `0.5`. */
+  factor?: number;
+  /** Clean calls required before the full rate is restored. */
+  recoverAfter?: number;
+}
+
+/** Shape of this plugin's profile-entry config (all fields optional). */
+export interface RateLimiterConfig {
+  /** Master switch for the limiter. */
+  enabled?: boolean;
+  /** Algorithm used for every model unless a tier says otherwise. */
+  strategy?: "token-bucket" | "sliding-window";
+  /** Global tier, applied when neither a provider nor a model tier matches. */
+  defaults?: RateLimitTier;
+  /** Per-provider tier, keyed by provider id (wildcards accepted). */
+  providers?: Record<string, RateLimitTier>;
+  /** Per-model tier, keyed by `provider/model` (wildcards accepted). */
+  models?: Record<string, ModelOverride>;
+  /** Adaptive back-off after provider-side throttling. */
+  cooldown?: CooldownConfig;
+  /** `queue` waits for capacity; `reject` fails the call immediately. */
+  onThrottled?: "queue" | "reject";
+  /** How long a queued call may wait before it is refused. */
+  maxQueueWaitMs?: number;
+}
+
+/**
+ * Structural subset of the Cordis `Context` that `apply` relies on.
+ *
+ * Declared locally so consumers do not need `@deepseek-ai/cordis` installed to
+ * type-check against this package.
+ */
+export interface HostContext {
+  logger?: (scope: string) => {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+  };
+  on(event: string, listener: (...args: any[]) => any): () => void;
+  effect(effect: () => (() => void) | void, label?: string): void;
+  inject(dependencies: string[], callback: (ctx: any) => void): void;
+  fiber?: unknown;
+  [key: string]: unknown;
+}
+
+/** Plugin name as registered in `cordis.patch.yml`. */
+export declare const name: string;
+
+/** Settings namespace / profile entry id. */
+export declare const SETTINGS_NS: string;
+
+/** schemastery schema for the profile entry's `config`. */
+export declare const Config: unknown;
+
+/**
+ * Cordis plugin entry point. Registers the `llm/stream` interceptor, the
+ * settings presentation opt-out and the status RPC channel.
+ */
+export declare function apply(ctx: HostContext, config?: RateLimiterConfig): void;

package/lib/index.js

@@ -22,6 +22,11 @@
 import { TokenBucketStrategy } from "./strategies/token-bucket.js";
 import { SlidingWindowStrategy } from "./strategies/sliding-window.js";
 import { Config } from "./types/config.js";
+import {
+  CooldownTracker,
+  resolveModelConfig,
+  scaleConfig,
+} from "./config-resolve.js";
 import { CHANNEL, createChannelRoute, createStatusChannel } from "./status-rpc.js";
 
 const name = "llm-multi-rate-limiter";
@@ -38,6 +43,10 @@ const SETTINGS_NS = "llm-multi-rate-limiter";
 const EVENT_RING_LIMIT = 64;
 /** Events carried by one snapshot (the panel shows these). */
 const SNAPSHOT_EVENT_COUNT = 8;
+/** How often idle, unconfigured limiters are dropped from the map. */
+const IDLE_SWEEP_MS = 60_000;
+/** A limiter with no override and no activity for this long is released. */
+const IDLE_LIMITER_MS = 10 * 60_000;
 
 /* ── Helpers ─────────────────────────────────────────────────────────── */
 
@@ -46,7 +55,9 @@ const FALLBACK = {
   enabled: true,
   strategy: "token-bucket",
   defaults: { maxConcurrent: 5, maxRpm: 60, burstSize: 10, refillRate: 1 },
+  providers: {},
   models: {},
+  cooldown: { enabled: true, cooldownMs: 30_000, factor: 0.5, recoverAfter: 3 },
   onThrottled: "queue",
   maxQueueWaitMs: 60_000,
 };
@@ -74,41 +85,21 @@ function read(ref, fallback) {
   return ref;
 }
 
-/**
- * Merge defaults + per-model overrides into a flat config object that both
- * strategy constructors understand.
- *
- * @param cfg - plain config object (`{ enabled, strategy, defaults, models, ... }`).
- * @param key - `"provider/model"` of the call being limited.
- */
-function resolveModelConfig(cfg, key) {
-  const o = cfg.models?.[key] ?? {};
-  const d = cfg.defaults ?? {};
-  const maxRpm = o.maxRpm ?? d.maxRpm ?? 60;
-  // When a model overrides maxRpm but not refillRate, derive refillRate from
-  // the model's maxRpm — this is the most common case ("set maxRpm=3").
-  // When model doesn't override maxRpm, use the defaults' refillRate as-is.
-  const refillRate = o.refillRate ?? (o.maxRpm != null ? o.maxRpm / 60 : d.refillRate ?? (maxRpm / 60));
-  return {
-    maxConcurrent: o.maxConcurrent ?? d.maxConcurrent ?? 5,
-    maxRpm,
-    burstSize:     o.burstSize     ?? d.burstSize     ?? 10,
-    refillRate,
-    windowMs:      d.windowMs      ?? 60_000,
-  };
-}
-
 /**
  * Ensure a rate-limiting strategy instance exists (or is updated) for `key`.
+ *
+ * @param {Map<string, TokenBucketStrategy | SlidingWindowStrategy>} limiters
+ * @param {string} key
+ * @param {ReturnType<typeof resolveModelConfig>} merged resolved tier config
+ * @param {string} strategyName
  */
-function ensureLimiter(limiters, key, cfg) {
-  const merged = resolveModelConfig(cfg, key);
+function ensureLimiter(limiters, key, merged, strategyName) {
   const existing = limiters.get(key);
   if (existing) {
     existing.update(merged);
     return existing;
   }
-  const strategy = cfg.strategy === "sliding-window"
+  const strategy = strategyName === "sliding-window"
     ? new SlidingWindowStrategy(merged)
     : new TokenBucketStrategy(merged);
   limiters.set(key, strategy);
@@ -117,21 +108,44 @@ function ensureLimiter(limiters, key, cfg) {
 
 /**
  * Build a terminal StreamChunk for rate-limiting failures.
- * Uses `kind: "aborted"` when the caller's AbortSignal fired, so the agent
- * loop treats it as a cancellation rather than a retryable error.
- * Otherwise uses `kind: "error"` with `RATE_LIMIT` code, which the
- * `dsh-llm-retry` plugin can catch and back off.
+ *
+ * The failure code matters: `dsh-llm-retry` only retries the codes its policy
+ * lists (by default `RATE_LIMIT`, `SERVER`, `TIMEOUT`, `TRANSPORT`,
+ * `EMPTY_RESPONSE`). A queue timeout is a LOCAL decision — retrying it just
+ * parks the caller in another queue — so it carries its own code, which no
+ * default policy retries. A provider-side 429 keeps `RATE_LIMIT`, because
+ * retrying THAT is exactly what the retry plugin is for.
+ *
+ * `kind: "aborted"` is used when the caller's AbortSignal fired, so the agent
+ * loop treats it as a cancellation rather than a failure.
  */
-function terminalChunk(modelKey, signal) {
+function terminalChunk(modelKey, code, signal) {
   const aborted = signal?.aborted === true;
+  const failure = {
+    code,
+    message: aborted
+      ? `Rate limit: ${modelKey} (aborted while waiting)`
+      : `Rate limit: ${modelKey} was not granted a slot in time`,
+  };
   return {
     type: "finish",
-    reason: aborted
-      ? { kind: "aborted", failure: { code: "RATE_LIMIT", message: `Rate limit: ${modelKey} (aborted)` } }
-      : { kind: "error", failure: { code: "RATE_LIMIT", message: `Rate limit exceeded for ${modelKey}` } },
+    reason: aborted ? { kind: "aborted", failure } : { kind: "error", failure },
   };
 }
 
+/** True when a stream chunk reports that the PROVIDER throttled the call. */
+function isProviderRateLimit(chunk) {
+  return chunk?.type === "finish"
+    && chunk.reason?.kind === "error"
+    && chunk.reason?.failure?.code === "RATE_LIMIT";
+}
+
+/** Optional `retryAfterMs` hint carried by a provider failure, when present. */
+function retryAfterOf(chunk) {
+  const hint = chunk?.reason?.failure?.retryAfterMs;
+  return Number.isFinite(hint) && hint > 0 ? hint : undefined;
+}
+
 /* ── Plugin entry ────────────────────────────────────────────────────── */
 
 /**
@@ -151,7 +165,9 @@ function apply(ctx, config) {
       enabled: read(config?.enabled, FALLBACK.enabled),
       strategy: read(config?.strategy, FALLBACK.strategy),
       defaults: read(config?.defaults, FALLBACK.defaults),
+      providers: read(config?.providers, FALLBACK.providers),
       models: read(config?.models, FALLBACK.models),
+      cooldown: read(config?.cooldown, FALLBACK.cooldown),
       onThrottled: read(config?.onThrottled, FALLBACK.onThrottled),
       maxQueueWaitMs: read(config?.maxQueueWaitMs, FALLBACK.maxQueueWaitMs),
     };
@@ -159,6 +175,8 @@ function apply(ctx, config) {
 
   /** @type {Map<string, TokenBucketStrategy | SlidingWindowStrategy>} */
   const limiters = new Map();
+  /** Adaptive back-off state after provider 429s. */
+  const cooldown = new CooldownTracker(FALLBACK.cooldown);
 
   // ── Live statistics (read by the status RPC channel) ───────
   // Counters are plain numbers so a snapshot is always JSON-safe.
@@ -168,6 +186,7 @@ function apply(ctx, config) {
     rejected: 0,
     timeouts: 0,
     aborted: 0,
+    throttledByProvider: 0,
     totalWaitMs: 0,
   };
   /** Bumped on every recorded event and on reset — the panel's change cursor. */
@@ -187,7 +206,15 @@ function apply(ctx, config) {
     const models = {};
     for (const [key, limiter] of limiters) {
       try {
-        models[key] = limiter.getStatus();
+        const status = limiter.getStatus();
+        const factor = cooldown.factorFor(key);
+        models[key] = {
+          ...status,
+          // Effective limit after any 429 penalty — what the panel should show.
+          effectiveMaxRpm: factor < 1 ? Math.max(1, Math.round((status.maxRpm ?? 0) * factor)) : status.maxRpm,
+          cooling: cooldown.isCooling(key),
+          cooldownRemainingMs: cooldown.remainingMs(key),
+        };
       } catch {
         // A strategy that cannot report status must not break the whole panel.
       }
@@ -198,6 +225,10 @@ function apply(ctx, config) {
       enabled: cfg.enabled !== false,
       strategy: cfg.strategy,
       onThrottled: cfg.onThrottled,
+      cooldown: {
+        enabled: cfg.cooldown?.enabled !== false,
+        models: cooldown.snapshot(),
+      },
       totals: { ...totals },
       models,
       events: eventRing.slice(-SNAPSHOT_EVENT_COUNT),
@@ -208,9 +239,42 @@ function apply(ctx, config) {
   function resetTotals() {
     for (const key of Object.keys(totals)) totals[key] = 0;
     eventRing.length = 0;
+    cooldown.clear();
     rev += 1;
   }
 
+  /** Drop limiters that no tier configures and nothing has touched for a while. */
+  function sweepIdleLimiters() {
+    if (limiters.size === 0) return;
+    const cfg = readConfig();
+    const now = Date.now();
+    for (const [key, limiter] of limiters) {
+      if (now - (limiter.lastUsedAt ?? 0) < IDLE_LIMITER_MS) continue;
+      let status;
+      try {
+        status = limiter.getStatus();
+      } catch {
+        status = undefined;
+      }
+      // Never drop a limiter with work in flight or queued behind it.
+      if (status && ((status.concurrent ?? 0) > 0 || (status.reserved ?? 0) > 0 || (status.queued ?? 0) > 0)) continue;
+      // A model that still has an explicit override stays visible even when idle.
+      if (resolveModelConfig(cfg, key).source !== "defaults") continue;
+      try {
+        limiter.dispose();
+      } catch {
+        // Disposal is best-effort; dropping the map entry is what matters.
+      }
+      limiters.delete(key);
+      cooldown.forget(key);
+      rev += 1;
+    }
+  }
+
+  const sweepTimer = setInterval(sweepIdleLimiters, IDLE_SWEEP_MS);
+  // Node's unref keeps the timer from holding the process open on shutdown.
+  sweepTimer.unref?.();
+
   // ── Settings presentation (dynamic inject) ─────────────────
   // This plugin ships its own browser page, so it opts out of any
   // schema-generated page. Wrapped in ctx.inject so a host WITHOUT a settings
@@ -248,7 +312,7 @@ function apply(ctx, config) {
   //      'cannot get property "webServer" without inject'. Registering the
   //      route on our own fiber (which injects webServer below) avoids that
   //      while still using the framework's own 403/401 fence.
-  //      Still unfixed in 0.1.7-rc.1 (dsh-client-connection/lib/index.js:798
+  //      Still unfixed in 0.2.1-rc.2 (dsh-client-connection/lib/index.js:1013
   //      keeps `inject = ["credentials"]`), so the fallback still fires.
   ctx.inject(["connection"], (scopedCtx) => {
     const connection = scopedCtx.get("connection");
@@ -350,12 +414,20 @@ function apply(ctx, config) {
 
     try {
       const cfg = readConfig();
+      cooldown.configure(cfg.cooldown);
 
       if (!cfg.enabled || cfg.models?.[modelKey]?.enabled === false) {
         // Global switch off, or per-model opt-out: zero-touch pass-through.
         passThrough = true;
       } else {
-        limiter = ensureLimiter(limiters, modelKey, cfg);
+        // Resolve the tier chain (model > provider > defaults) and apply any
+        // 429 penalty currently in force for this model.
+        const resolved = resolveModelConfig(cfg, modelKey);
+        const factor = cooldown.factorFor(modelKey);
+        const effective = factor < 1 ? scaleConfig(resolved, factor) : resolved;
+
+        limiter = ensureLimiter(limiters, modelKey, effective, cfg.strategy);
+        limiter.lastUsedAt = Date.now();
         totals.requests += 1;
 
         if (cfg.onThrottled === "reject") {
@@ -371,7 +443,8 @@ function apply(ctx, config) {
             totals.rejected += 1;
             recordEvent({ event: "rejected", model: modelKey });
             logger?.warn("model %C rejected — rate limit reached", modelKey);
-            refused = terminalChunk(modelKey, options.signal);
+            // Local decision: not a retryable provider condition.
+            refused = terminalChunk(modelKey, "RATE_LIMIT_REJECTED", options.signal);
           }
         } else {
           // Queue mode — park until a slot opens.
@@ -396,7 +469,8 @@ function apply(ctx, config) {
               "model %C %s after %d ms",
               modelKey, aborted ? "aborted" : "queue timeout", permit.waitMs,
             );
-            refused = terminalChunk(modelKey, options.signal);
+            // Own code: a queue timeout must not be retried into another queue.
+            refused = terminalChunk(modelKey, "RATE_LIMIT_QUEUE_TIMEOUT", options.signal);
           }
         }
       }
@@ -433,19 +507,43 @@ function apply(ctx, config) {
     // ── Phase 2: run the real LLM call ─────────────────────────
     // Queue mode does not take a concurrent slot inside acquire().
     if (!slotTaken) limiter.acquireSlot();
+    const activeLimiter = limiter;
     try {
-      yield* next();
+      // Pass chunks straight through while watching for a provider 429: the
+      // stream stays streaming, and the cooldown learns from the failure.
+      for await (const chunk of next()) {
+        if (isProviderRateLimit(chunk)) {
+          const retryAfterMs = retryAfterOf(chunk);
+          const entry = cooldown.recordFailure(modelKey, Date.now(), retryAfterMs);
+          totals.throttledByProvider += 1;
+          recordEvent({
+            event: "throttled",
+            model: modelKey,
+            cooldownMs: entry === undefined ? 0 : Math.max(0, entry.until - Date.now()),
+          });
+          logger?.warn(
+            "provider throttled %C; slowing to %d%% for %d ms",
+            modelKey,
+            Math.round((entry?.factor ?? 1) * 100),
+            entry === undefined ? 0 : Math.max(0, entry.until - Date.now()),
+          );
+        }
+        yield chunk;
+      }
+      cooldown.recordSuccess(modelKey);
     } finally {
-      limiter.releaseSlot();
+      activeLimiter.releaseSlot();
       recordEvent({ event: "completed", model: modelKey });
     }
   });
 
   // ── Teardown ──
   ctx.effect(() => () => {
+    clearInterval(sweepTimer);
     disposeLlmListener();
     for (const limiter of limiters.values()) limiter.dispose();
     limiters.clear();
+    cooldown.clear();
   }, "rate-limiter: dispose llm/stream listener");
 
   logger?.info("rate limiter active — llm/stream interceptor registered");