@goodandready/dsh-key-rotation 0.8.77 → 0.8.79

package/lib/ops-webhook.js

@@ -1,218 +1,2 @@
-import crypto from 'node:crypto';
-// lib/ops-webhook.js — webhook interactive action route (#312 split from routes-ops.js, #388 telegram secret-token & answerCallbackQuery).
-import {
-  json,
-  readJson,
-} from './http-bridge.js';
-import { bestEffort } from './best-effort.js';
-import { WEBHOOK_ACTION_PATH } from './ops-paths.js';
-import { resolveAction } from './webhook.js';
-
-function constantTimeEqual(a, b) {
-  if (typeof a !== 'string' || typeof b !== 'string') return false;
-  const aBuf = Buffer.from(a);
-  const bBuf = Buffer.from(b);
-  return aBuf.length === bBuf.length && crypto.timingSafeEqual(aBuf, bBuf);
-}
-
-function getHeader(headers, name) {
-  if (!headers || typeof headers !== 'object') return '';
-  const target = name.toLowerCase();
-  for (const [k, v] of Object.entries(headers)) {
-    if (k.toLowerCase() === target) return String(v ?? '');
-  }
-  return '';
-}
-
-/**
- * @param {object} ctx cordis context
- * @param {object} deps live dependencies from apply()
- */
-export function registerWebhookActionRoute(ctx, deps) {
-  const {
-    buildRuntime,
-    poolState,
-    setRotationDisabled,
-    circuitBreaker,
-  } = deps;
-
-ctx.effect(() => ctx.webServer.register({
-  kind: 'exact',
-  path: WEBHOOK_ACTION_PATH,
-  handler: async (req, res) => {
-    if (req.method !== 'POST') { json(res, 405, { error: { code: 'method', message: 'POST only' } }); return; }
-    const runtime = buildRuntime();
-    const expected = runtime.webhookActionToken;
-    if (!expected) { json(res, 503, { error: { code: 'no-token', message: 'dsh-key-rotation: webhookActionToken is not configured' } }); return; }
-
-    const authHeader = getHeader(req.headers, 'authorization');
-    const secretHeader = getHeader(req.headers, 'x-telegram-bot-api-secret-token');
-    const bearerMatch = constantTimeEqual(authHeader, `Bearer ${expected}`);
-    const secretMatch = constantTimeEqual(secretHeader, expected);
-    if (!bearerMatch && !secretMatch) {
-      json(res, 401, { error: { code: 'unauthorized', message: 'dsh-key-rotation: bad webhook action token' } });
-      return;
-    }
-
-    let body;
-    try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
-
-    // #222 / #388: Telegram setWebhook registration helper
-    if (typeof body?.setWebhook === 'object' && body.setWebhook) {
-      const botToken = typeof body.setWebhook.botToken === 'string' ? body.setWebhook.botToken : '';
-      if (!botToken) { json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: setWebhook.botToken required' } }); return; }
-      const TELEGRAM_BOT_TOKEN_RE = /^[0-9]{5,16}:[a-zA-Z0-9_-]{20,50}$/;
-      if (!TELEGRAM_BOT_TOKEN_RE.test(botToken)) {
-        json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: invalid telegram bot token format' } });
-        return;
-      }
-      const rawUrl = typeof body.setWebhook.url === 'string' ? body.setWebhook.url.trim() : '';
-      if (!rawUrl || !rawUrl.startsWith('https://')) {
-        json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: explicit public https url required in setWebhook.url' } });
-        return;
-      }
-      try {
-        const hookRes = await fetch(`https://api.telegram.org/bot${botToken}/setWebhook`, {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({
-            url: rawUrl,
-            secret_token: expected,
-            allowed_updates: ['callback_query'],
-          }),
-          signal: AbortSignal.timeout(10000),
-        });
-        const hookData = await hookRes.json().catch(() => ({}));
-        json(res, 200, { ok: hookRes.ok, url: rawUrl, secret_token_set: true, telegram: hookData });
-      } catch (e) {
-        json(res, 502, { error: { code: 'telegram-failed', message: String(e?.message ?? e) } });
-      }
-      return;
-    }
-
-    const callbackQueryId = typeof body?.callback_query?.id === 'string'
-      ? body.callback_query.id
-      : (typeof body?.callback_query?.id === 'number' ? String(body.callback_query.id) : '');
-    const botToken = typeof body?.botToken === 'string' ? body.botToken : '';
-
-    const respond = async (statusCode, payload, answerText) => {
-      if (callbackQueryId) {
-        payload.method = 'answerCallbackQuery';
-        payload.callback_query_id = callbackQueryId;
-        payload.text = answerText || payload.error?.message || 'OK';
-        if (botToken) {
-          await bestEffort('telegram-answerCallbackQuery', () => fetch(`https://api.telegram.org/bot${botToken}/answerCallbackQuery`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ callback_query_id: callbackQueryId, text: payload.text }),
-            signal: AbortSignal.timeout(5000),
-          }), ctx?.logger);
-        }
-      }
-      json(res, statusCode, payload);
-    };
-
-    // Accept callback payloads from formatInteractive (Telegram/Discord/Slack) or plain {action}
-    let action = typeof body?.action === 'string' ? body.action : '';
-    if (!action && typeof body?.data === 'string') {
-      try { action = String(JSON.parse(body.data)?.id ?? ''); } catch { action = ''; }
-    }
-    if (!action && typeof body?.callback_data === 'string') {
-      try { action = String(JSON.parse(body.callback_data)?.id ?? ''); } catch { action = ''; }
-    }
-    // #222 / #388: Telegram update envelope {update_id, callback_query:{id, data}}
-    if (!action && typeof body?.callback_query?.data === 'string') {
-      try {
-        const parsed = JSON.parse(body.callback_query.data);
-        action = typeof parsed?.id === 'string' ? parsed.id : String(parsed ?? '');
-      } catch {
-        action = body.callback_query.data;
-      }
-    }
-    action = resolveAction(action);
-    if (!action) {
-      await respond(400, { error: { code: 'bad-action', message: 'dsh-key-rotation: no action in payload' } }, 'No action in payload');
-      return;
-    }
-    const provider = action.startsWith('pause-') || action.startsWith('reset-') ? action.replace(/^(pause|reset)-/, '') : '';
-    try {
-      if (action === 'disable-rotation') {
-        setRotationDisabled(true);
-        (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.('[dsh-key-rotation] rotation DISABLED via webhook action');
-        await respond(200, { ok: true, action }, 'Rotation disabled');
-        return;
-      }
-      if (action === 'enable-rotation') {
-        setRotationDisabled(false);
-        await respond(200, { ok: true, action }, 'Rotation enabled');
-        return;
-      }
-      if (action.startsWith('pause-') || action.startsWith('reset-')) {
-        const st = poolState.get(provider);
-        if (!st) {
-          await respond(404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }, `Pool not found: ${provider}`);
-          return;
-        }
-        if (action.startsWith('pause-')) {
-          const until = Date.now() + 3600000; // 1h pause
-          let found = false;
-          for (const [key, s] of poolState.entries()) {
-            if (key === provider || key.startsWith(provider + '::')) {
-              found = true;
-              for (const ref of (s.failedUntil ? [...s.failedUntil.keys()] : [])) {
-                s.failedUntil.set(ref, Math.max(s.failedUntil.get(ref) ?? 0, until));
-              }
-            }
-          }
-          for (const p of buildRuntime().poolByRef.values()) {
-            if (p.provider === provider || p.base === provider || p.base?.startsWith(provider + '::')) {
-              found = true;
-              for (const ref of p.refs) p.state?.failedUntil?.set(ref, Math.max(p.state?.failedUntil?.get(ref) ?? 0, until));
-            }
-          }
-          if (!found) {
-            await respond(404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }, `Pool not found: ${provider}`);
-            return;
-          }
-          (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] pool ${provider} PAUSED 1h via webhook action`);
-          await respond(200, { ok: true, action, provider, until }, `Pool ${provider} paused 1h`);
-          return;
-        }
-        let found = false;
-        let cleared = 0;
-        for (const [key, s] of poolState.entries()) {
-          if (key === provider || key.startsWith(provider + '::')) {
-            found = true;
-            cleared += s.failedUntil ? s.failedUntil.size : 0;
-            s.failedUntil?.clear();
-            s.failCounts?.clear();
-            s.authFailCounts?.clear();
-            s.brokenUntil?.clear();
-            s.revokedRefs?.clear();
-            s.tokenUsage?.clear();
-            s.switches = 0;
-            s.lastReason = undefined;
-            s.lastSwitchAt = undefined;
-          }
-        }
-        if (!found) {
-          await respond(404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }, `Pool not found: ${provider}`);
-          return;
-        }
-        let circuitReset = false;
-        const br = circuitBreaker ?? buildRuntime().breaker;
-        if (br) {
-          if (typeof br.reset === 'function') { br.reset(provider); circuitReset = true; }
-          else if (typeof br.onSuccess === 'function') { br.onSuccess(provider); circuitReset = true; }
-        }
-        (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] pool ${provider} RESET via webhook action (circuitReset=${circuitReset})`);
-        await respond(200, { ok: true, action, provider, cleared, circuitReset }, `Pool ${provider} reset`);
-        return;
-      }
-      await respond(400, { error: { code: 'unknown-action', message: `dsh-key-rotation: unknown action '${action}'` } }, `Unknown action: ${action}`);
-    } catch (e) {
-      await respond(500, { error: { code: 'action-failed', message: String(e?.message ?? e) } }, 'Action failed');
-    }
-  },
-}), 'dsh-key-rotation: webhook-action');
-}
+// lib/ops-webhook.js — Re-export facade for lib/routes/ (#522).
+export * from "./routes/webhook.js";

package/lib/pool-selection.js

@@ -1,4 +1,4 @@
-// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512, #548).
+// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512, #548, #549).
 // Extracted from lib/pool.js to enforce < 600 line modularity standard.
 
 import {
@@ -8,11 +8,18 @@ import {
   SESSION_TTL_MS,
 } from './session-router.js';
 
+import {
+  QuotaRunway,
+  defaultQuotaRunway,
+} from './quota-runway.js';
+
 export {
   SessionRouter,
   defaultSessionRouter,
   MAX_SESSIONS,
   SESSION_TTL_MS,
+  QuotaRunway,
+  defaultQuotaRunway,
 };
 
 export const MAX_SESSION_STICKY_ENTRIES = MAX_SESSIONS;
@@ -103,11 +110,13 @@ export function selectPool(modelPoolByProvider, providerToPool, provider, model)
 
 /**
  * Sort candidate refs according to pool routing strategy.
+ * Preemptively deprioritizes keys projected to exhaust their quota before reset (#549).
  * Returns a new array; does not mutate input.
  */
 export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
   if (!Array.isArray(refs) || refs.length <= 1) return (refs ?? []).slice();
-  const list = refs.slice();
+  let list = refs.slice();
+
   if (strategy === 'sticky') {
     const router = getOrCreateSessionRouter(deps.pool);
     let chosenKey = null;
@@ -133,19 +142,16 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
         list.unshift(last);
       }
     }
-    return list;
-  }
-  if (strategy === 'tier-priority') {
+  } else if (strategy === 'tier-priority') {
     const tiers = deps.tiers || (deps.pool && deps.pool.tiers) || {};
-    return list.sort((a, b) => {
+    list = list.sort((a, b) => {
       const ta = (tiers[a] && Number(tiers[a]) >= 1) ? Number(tiers[a]) : 1;
       const tb = (tiers[b] && Number(tiers[b]) >= 1) ? Number(tiers[b]) : 1;
       return ta - tb;
     });
-  }
-  if (strategy === 'least-loaded' && deps.concurrencyTracker && typeof deps.concurrencyTracker.getActive === 'function') {
+  } else if (strategy === 'least-loaded' && deps.concurrencyTracker && typeof deps.concurrencyTracker.getActive === 'function') {
     const weights = deps.weights || (deps.pool && deps.pool.weightsMap) || {};
-    return list.sort((a, b) => {
+    list = list.sort((a, b) => {
       const ca = deps.concurrencyTracker.getActive(a) ?? 0;
       const cb = deps.concurrencyTracker.getActive(b) ?? 0;
       const wa = (weights[a] && Number(weights[a]) > 0) ? Number(weights[a]) : 1;
@@ -155,9 +161,8 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
       if (scoreA !== scoreB) return scoreA - scoreB;
       return ca - cb;
     });
-  }
-  if (strategy === 'lowest-latency' && deps.latencyHistogram && typeof deps.latencyHistogram.snapshot === 'function') {
-    return list.sort((a, b) => {
+  } else if (strategy === 'lowest-latency' && deps.latencyHistogram && typeof deps.latencyHistogram.snapshot === 'function') {
+    list = list.sort((a, b) => {
       const sa = deps.latencyHistogram.snapshot(a);
       const sb = deps.latencyHistogram.snapshot(b);
       const la = (sa && Number.isFinite(sa.p95)) ? sa.p95 : ((sa && Number.isFinite(sa.avg)) ? sa.avg : 500);
@@ -165,6 +170,25 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
       return la - lb;
     });
   }
+
+  // Preemptively deprioritize keys projected to exhaust before quota window reset (#549)
+  const runway = deps.quotaRunway ?? deps.pool?.state?.quotaRunway;
+  if (runway && typeof runway.isExhaustingBeforeReset === 'function' && list.length > 1) {
+    const now = typeof deps.now === 'function' ? deps.now() : (Number(deps.now) || Date.now());
+    const healthy = [];
+    const exhausting = [];
+    for (const ref of list) {
+      if (runway.isExhaustingBeforeReset(ref, now)) {
+        exhausting.push(ref);
+      } else {
+        healthy.push(ref);
+      }
+    }
+    if (healthy.length > 0 && exhausting.length > 0) {
+      return healthy.concat(exhausting);
+    }
+  }
+
   return list;
 }
 
@@ -221,4 +245,3 @@ export function budgetVerdict(spend, budget) {
   const ratio = spend / budget;
   return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
 }
-

package/lib/pool-state.js

@@ -1,5 +1,7 @@
 // Shared runtime shape for fresh and persisted pools. Hydrate in place so cached
 // runtime pools, persistence and timers continue to observe the same object.
+import { KeyStateMachine } from './key-state-machine.js';
+
 const MAP_FIELDS = [
   'failedUntil', 'failCounts', 'authFailCounts', 'brokenUntil', 'costPerKey',
   'lastUsedAt', 'usageCounts', 'byModel', 'usageDays', 'quotaWindows', 'costDays',
@@ -18,6 +20,7 @@ export function initializePoolState(state = {}) {
   if (!Array.isArray(state.events)) state.events = [];
   if (!Number.isSafeInteger(state.pointer) || state.pointer < 0) state.pointer = 0;
   if (typeof state.lastUsed !== 'string') state.lastUsed = null;
+  if (!state.keyStateMachine) state.keyStateMachine = new KeyStateMachine();
   return state;
 }
 

package/lib/pool.js

@@ -195,6 +195,7 @@ export function pickNext(pool, now, refsCount = pool.refs.length) {
 /** Apply a failed-key cooldown to pool state. Pure: returns next state shape. */
 export function applyCooldown(pool, ref, cooldownMs, now = Date.now()) {
   unstickFailedKey(pool, ref);
+  pool?.state?.keyStateMachine?.transitionToCooldown(ref, { cooldownMs }, now);
   return {
     ...pool,
     state: {
@@ -231,10 +232,9 @@ export function recordFailure(pool, ref, now, baseMs, maxMs, isSoft = false, jit
     pool.state.failCounts.set(ref, next);
   }
   let backoff = computeBackoff(baseMs, next || 1, maxMs, isSoft);
-  if (jitter) {
-    backoff = applyJitter(backoff);
-  }
+  if (jitter) backoff = applyJitter(backoff);
   pool.state.failedUntil.set(ref, now + backoff);
+  pool.state?.keyStateMachine?.transitionToCooldown(ref, { cooldownMs: backoff, reason: isSoft ? 'SOFT_FAILURE' : 'FAILURE' }, now);
   return backoff;
 }
 
@@ -245,6 +245,7 @@ export function recordSuccess(pool, ref, now = Date.now()) {
   pool.state.quotaWindows?.delete(ref);
   if (!pool.state.lastSuccessAt) pool.state.lastSuccessAt = new Map();
   pool.state.lastSuccessAt.set(ref, now);
+  pool.state?.keyStateMachine?.activate(ref, { reason: 'SUCCESS' }, now);
 }
 
 /** Decay penalty failCounts for stable keys that haven't failed in decayIntervalMs. */
@@ -376,12 +377,9 @@ export function parseDurationToSeconds(v) {
 /** Check if a key reference is in maintenance/paused mode. */
 export function isKeyPaused(pool, ref) {
   if (!pool || !ref) return false;
-  if (pool.pausedRefs instanceof Set && pool.pausedRefs.has(ref)) return true;
-  if (Array.isArray(pool.pausedRefs) && pool.pausedRefs.includes(ref)) return true;
-  if (pool.state && pool.state.pausedRefs instanceof Set && pool.state.pausedRefs.has(ref)) return true;
-  if (pool.state && Array.isArray(pool.state.pausedRefs) && pool.state.pausedRefs.includes(ref)) return true;
-  if (pool.basePool) return isKeyPaused(pool.basePool, ref);
-  return false;
+  if (pool.pausedRefs?.has?.(ref) || pool.pausedRefs?.includes?.(ref)) return true;
+  if (pool.state?.pausedRefs?.has?.(ref) || pool.state?.pausedRefs?.includes?.(ref)) return true;
+  return pool.basePool ? isKeyPaused(pool.basePool, ref) : false;
 }
 
 /** Extract rate-limit info from an object that may carry response headers. */
@@ -578,12 +576,9 @@ export function resetCircuitForProvider(circuitBreaker, provider) {
 /** Check if a key reference is permanently revoked due to auth/401 failure (#369). */
 export function isKeyRevoked(pool, ref) {
   if (!pool || !ref) return false;
-  if (pool.revokedRefs instanceof Set && pool.revokedRefs.has(ref)) return true;
-  if (Array.isArray(pool.revokedRefs) && pool.revokedRefs.includes(ref)) return true;
-  if (pool.state && pool.state.revokedRefs instanceof Set && pool.state.revokedRefs.has(ref)) return true;
-  if (pool.state && Array.isArray(pool.state.revokedRefs) && pool.state.revokedRefs.includes(ref)) return true;
-  if (pool.basePool) return isKeyRevoked(pool.basePool, ref);
-  return false;
+  if (pool.revokedRefs?.has?.(ref) || pool.revokedRefs?.includes?.(ref)) return true;
+  if (pool.state?.revokedRefs?.has?.(ref) || pool.state?.revokedRefs?.includes?.(ref)) return true;
+  return pool.basePool ? isKeyRevoked(pool.basePool, ref) : false;
 }
 
 /** Check if a key reference is in active recoverable or permanent quarantine (#427). */

package/lib/quota-runway.js

@@ -0,0 +1,222 @@
+// lib/quota-runway.js — Predictive Quota Runway and burn rate estimation (#549).
+// Estimates time to quota exhaustion and preemptively rotates keys before hitting HTTP 429.
+
+export const MINUTE = 60 * 1000;
+export const HOUR = 60 * MINUTE;
+export const DAY = 24 * HOUR;
+
+export const DEFAULT_WINDOW_DURATIONS = {
+  minute: MINUTE,
+  fiveMinute: 5 * MINUTE,
+  hourly: HOUR,
+  daily: DAY,
+  monthly: 30 * DAY,
+};
+
+/**
+ * Bounds percentage value to [0, 100].
+ * @param {number|unknown} value
+ * @returns {number}
+ */
+export function clampPercent(value) {
+  const num = Number(value);
+  return Number.isFinite(num) ? Math.max(0, Math.min(100, num)) : 0;
+}
+
+/**
+ * Estimates when a quota window reaches 100% at the average burn rate observed.
+ *
+ * @param {object|undefined} window
+ * @param {number} window.percentUsed Current percentage used (0..100)
+ * @param {string|number} window.resetsAt ISO timestamp or epoch ms when window resets
+ * @param {number} durationMs Window duration in milliseconds
+ * @param {number} [now] Current epoch timestamp in milliseconds
+ * @returns {{
+ *   etaMs: number,
+ *   resetsAtMs: number,
+ *   exhaustsBeforeReset: boolean,
+ *   burnRatePerSec: number
+ * } | null}
+ */
+export function estimateRunway(window, durationMs, now = Date.now()) {
+  if (!window || window.resetsAt == null || !durationMs || durationMs <= 0) return null;
+
+  const resetsAtMs = typeof window.resetsAt === 'number' ? window.resetsAt : Date.parse(window.resetsAt);
+  if (!Number.isFinite(resetsAtMs) || resetsAtMs <= now) return null;
+
+  const used = clampPercent(window.percentUsed);
+  const timeToReset = resetsAtMs - now;
+
+  // Already 100% or more: exhausts immediately
+  if (used >= 100) {
+    return {
+      etaMs: 0,
+      resetsAtMs,
+      exhaustsBeforeReset: true,
+      burnRatePerSec: 0,
+    };
+  }
+
+  const startedAt = resetsAtMs - durationMs;
+  const elapsed = Math.max(1, now - startedAt);
+  const ratePerMs = used / elapsed;
+
+  if (!Number.isFinite(ratePerMs) || ratePerMs <= 0) {
+    return {
+      etaMs: Number.POSITIVE_INFINITY,
+      resetsAtMs,
+      exhaustsBeforeReset: false,
+      burnRatePerSec: 0,
+    };
+  }
+
+  const remainingPercent = 100 - used;
+  const etaMs = remainingPercent / ratePerMs;
+  const exhaustsBeforeReset = etaMs < timeToReset;
+  const burnRatePerSec = ratePerMs * 1000;
+
+  return {
+    etaMs,
+    resetsAtMs,
+    exhaustsBeforeReset,
+    burnRatePerSec,
+  };
+}
+
+/**
+ * Stateful Quota Runway tracker for credentials and pools.
+ */
+export class QuotaRunway {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.slidingWindowMs]
+   */
+  constructor(options = {}) {
+    this.slidingWindowMs = options.slidingWindowMs ?? (5 * MINUTE);
+    /** @type {Map<string, Array<{ at: number, amount: number }>>} */
+    this.samples = new Map();
+    /** @type {Map<string, { limit: number, remaining: number, resetsAtMs: number, durationMs: number }>} */
+    this.knownLimits = new Map();
+  }
+
+  /**
+   * Records usage tokens or requests for a key.
+   * @param {string} keyRef
+   * @param {number} amount
+   * @param {number} [now]
+   */
+  recordUsage(keyRef, amount, now = Date.now()) {
+    if (!keyRef || !amount || amount <= 0) return;
+    let list = this.samples.get(keyRef);
+    if (!list) {
+      list = [];
+      this.samples.set(keyRef, list);
+    }
+    list.push({ at: now, amount });
+    this._prune(keyRef, now);
+  }
+
+  /**
+   * Updates key limits detected from response headers or provider metadata.
+   * @param {string} keyRef
+   * @param {object} limits
+   * @param {number} [limits.limit]
+   * @param {number} [limits.remaining]
+   * @param {number|string} [limits.resetsAt]
+   * @param {number} [limits.durationMs]
+   * @param {number} [now]
+   */
+  updateLimits(keyRef, limits, now = Date.now()) {
+    if (!keyRef || !limits) return;
+    const limit = Number(limits.tpmLimit ?? limits.rpmLimit ?? limits.limit);
+    const remaining = Number(limits.remainingTokens ?? limits.remainingRequests ?? limits.remaining);
+    const resetSec = Number(limits.resetTokens ?? limits.resetRequests ?? limits.retryAfter);
+
+    let resetsAtMs = NaN;
+    if (Number.isFinite(resetSec)) {
+      resetsAtMs = now + (resetSec * 1000);
+    } else if (limits.resetsAt || limits.resetAt) {
+      const at = limits.resetsAt || limits.resetAt;
+      resetsAtMs = typeof at === 'number' ? at : Date.parse(at);
+    }
+
+    const durationMs = Number(limits.durationMs) || DEFAULT_WINDOW_DURATIONS.minute;
+
+    if (Number.isFinite(limit) && Number.isFinite(remaining) && Number.isFinite(resetsAtMs)) {
+      this.knownLimits.set(keyRef, {
+        limit,
+        remaining,
+        resetsAtMs,
+        durationMs,
+      });
+    }
+  }
+
+  /**
+   * Checks if key is projected to exhaust its quota before the current window resets.
+   * @param {string} keyRef
+   * @param {number} [now]
+   * @returns {boolean}
+   */
+  isExhaustingBeforeReset(keyRef, now = Date.now()) {
+    const assessment = this.assessRunway(keyRef, now);
+    return Boolean(assessment?.exhaustsBeforeReset);
+  }
+
+  /**
+   * Returns complete runway assessment for a key.
+   * @param {string} keyRef
+   * @param {number} [now]
+   * @returns {{
+   *   exhaustsBeforeReset: boolean,
+   *   etaMs: number,
+   *   burnRatePerSec: number,
+   *   timeToResetMs: number
+   * } | null}
+   */
+  assessRunway(keyRef, now = Date.now()) {
+    if (!keyRef) return null;
+
+    const limits = this.knownLimits.get(keyRef);
+    if (!limits || limits.resetsAtMs <= now) {
+      return null;
+    }
+
+    const { limit, remaining, resetsAtMs, durationMs } = limits;
+    if (limit <= 0) return null;
+
+    const used = Math.max(0, limit - remaining);
+    const percentUsed = (used / limit) * 100;
+
+    const estimate = estimateRunway(
+      { percentUsed, resetsAt: resetsAtMs },
+      durationMs,
+      now,
+    );
+
+    if (!estimate) return null;
+
+    return {
+      exhaustsBeforeReset: estimate.exhaustsBeforeReset,
+      etaMs: estimate.etaMs,
+      burnRatePerSec: estimate.burnRatePerSec,
+      timeToResetMs: resetsAtMs - now,
+    };
+  }
+
+  _prune(keyRef, now) {
+    const list = this.samples.get(keyRef);
+    if (!list) return;
+    const cutoff = now - this.slidingWindowMs;
+    while (list.length > 0 && list[0].at < cutoff) {
+      list.shift();
+    }
+  }
+
+  clear() {
+    this.samples.clear();
+    this.knownLimits.clear();
+  }
+}
+
+export const defaultQuotaRunway = new QuotaRunway();