@srouterhq/server 0.0.0-stage → 0.9.0

package/dist/services/quota-forecast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-forecast.d.ts","sourceRoot":"","sources":["../../src/services/quota-forecast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAczD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAKvC,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAKlD,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;mDAC+C;IAC/C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,mEAAmE;IACnE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gEAAgE;IAChE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;oFAEgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,wEAAwE;IACxE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAInC;;2DAEuD;IACvD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;sBAGkB;IAClB,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AASD,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAYzE;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAef;AAiDD,wBAAgB,gBAAgB,CAC9B,IAAI,yBAAyB,EAAE,GAAG,SAAa,GAC9C,kBAAkB,EAAE,CAmCtB"}

package/dist/services/quota-forecast.js

@@ -0,0 +1,150 @@
+import { getQuotaStateForKeys, inferPoolForPlatform } from './provider-quota.js';
+import { getDb } from '../db/index.js';
+// Daily free-tier balance forecast (#1104). Free tiers reset on a per-account
+// window (usually UTC midnight) and the only way to know how much headroom is
+// left before that reset is to read what the providers themselves reported.
+// This is a pure aggregation over `getQuotaStateForKeys()` — no new tables, no
+// extra probes — so it costs nothing beyond the query the health view already
+// runs.
+//
+// The value it adds over the raw rows: one number per platform that answers
+// "can I keep calling this platform for the rest of today?", plus a
+// low-balance warning an agent can gate on BEFORE sending a request that would
+// 429.
+export const LOW_BALANCE_THRESHOLD = 0.1; // <10% of the daily window left → warn
+export const LOW_BALANCE_ABSOLUTE = 20; // ...or fewer than 20 requests left
+// The absolute floor is a statement about big windows: "20 left" is alarming
+// out of 14400/day and unremarkable out of 30/day. Below this limit the
+// percentage rule alone decides, otherwise a small tier would warn from its
+// first request onwards and the flag would mean nothing.
+export const LOW_BALANCE_ABSOLUTE_MIN_LIMIT = 200;
+// Rate observation window: look at requests in the last N minutes to estimate
+// current consumption speed. Ten minutes covers bursty usage while ignoring
+// sub-hour lulls; shorter windows would jitter, longer ones would lag.
+export const RATE_OBSERVATION_WINDOW_MINUTES = 10;
+export const MIN_FORECAST_REQUESTS = 3;
+function secondsUntilReset(resetAt) {
+    if (!resetAt)
+        return null;
+    const ms = new Date(resetAt).getTime() - Date.now();
+    if (Number.isNaN(ms) || ms <= 0)
+        return null;
+    return Math.floor(ms / 1000);
+}
+export function getRecentQuotaActivity(now) {
+    const sqliteUtc = (ms) => new Date(ms).toISOString().slice(0, 19).replace('T', ' ');
+    const since = sqliteUtc(now - RATE_OBSERVATION_WINDOW_MINUTES * 60_000);
+    const rows = getDb().prepare(`
+    SELECT platform, key_id AS keyId, model_id AS modelId, COUNT(*) AS count
+      FROM requests
+     WHERE created_at >= ? AND datetime(created_at) >= ? AND datetime(created_at) <= ?
+       AND status = 'success'
+     GROUP BY platform, key_id, model_id
+  `).all(since, since, sqliteUtc(now));
+    return rows.map(row => ({ platform: row.platform, keyId: row.keyId,
+        pool: inferPoolForPlatform(row.platform, row.modelId), count: Number(row.count) }));
+}
+export function estimateExhaustionAt(remaining, ratePerMin, resetAt, now) {
+    // No observed rate → no honest projection. Rates too low to matter are
+    // excluded at the caller level (rate_per_min itself is null).
+    if (ratePerMin === null || ratePerMin <= 0)
+        return null;
+    // Remaining is known (caller checks) and limit is positive (enforced below).
+    const minutesUntilEmpty = remaining / ratePerMin;
+    const secondsFromNow = Math.ceil(minutesUntilEmpty * 60);
+    const ms = now + secondsFromNow * 1000;
+    // Never project past the natural window reset: if the window expires first,
+    // we have headroom even if the request count would otherwise exhaust the
+    // pool — the quota header tracks the remaining *before* reset, not absolute
+    // spending.
+    const resetMs = resetAt ? new Date(resetAt).getTime() : Infinity;
+    if (!Number.isFinite(ms) || Number.isNaN(resetMs) || ms >= resetMs || ms <= now)
+        return null;
+    return new Date(ms).toISOString();
+}
+function entryFor(row, ratePerMin, now) {
+    // Only request-based windows are predictable from quota headers; token pools
+    // reset semantics vary too much across providers to forecast honestly.
+    if (row.metric !== 'requests')
+        return null;
+    // Without a known limit there is no window to forecast — nothing to warn on.
+    if (typeof row.limit !== 'number' || row.limit <= 0)
+        return null;
+    const limit = row.limit;
+    const remaining = typeof row.remaining === 'number' ? row.remaining : null;
+    // An unknown `remaining` says nothing about consumption: reporting the whole
+    // limit as used would read as an exhausted pool when it may be untouched.
+    const used = remaining === null ? null : Math.max(0, limit - remaining);
+    let remainingPct = null;
+    let lowBalance = false;
+    if (remaining !== null) {
+        remainingPct = Math.max(0, Math.min(100, Math.round((remaining / limit) * 100)));
+        const absoluteApplies = limit >= LOW_BALANCE_ABSOLUTE_MIN_LIMIT;
+        lowBalance = (absoluteApplies && remaining <= LOW_BALANCE_ABSOLUTE)
+            || remaining / limit < LOW_BALANCE_THRESHOLD;
+    }
+    // Rate projection is gated on remaining being known (unknown remaining makes
+    // any rate look like a free lunch until the next quota refresh).
+    if (remaining === null)
+        ratePerMin = null;
+    const estimatedExhaustionAt = (remaining !== null && ratePerMin !== null && remaining > 0)
+        ? estimateExhaustionAt(remaining, ratePerMin, row.resetAt ?? null, now)
+        : null;
+    return {
+        platform: row.platform,
+        pool: row.quotaPoolKey ?? `${row.platform}::default`,
+        used,
+        remaining,
+        limit,
+        remaining_pct: remainingPct,
+        reset_at: row.resetAt ?? null,
+        low_balance: lowBalance,
+        seconds_until_reset: secondsUntilReset(row.resetAt ?? null),
+        rate_per_min: ratePerMin,
+        estimated_exhaustion_at: estimatedExhaustionAt,
+    };
+}
+// Dedupe to the TIGHTEST row per platform+pool: a platform with several keys
+// sharing one account pool reports the same window per key, and the number that
+// matters for "can I keep calling" is the least headroom left.
+export function getQuotaForecast(rows = getQuotaStateForKeys(), now = Date.now()) {
+    const byKey = new Map();
+    const activity = rows.length ? getRecentQuotaActivity(now) : [];
+    const counts = new Map();
+    for (const row of activity) {
+        const identity = JSON.stringify([row.platform, row.pool, row.keyId]);
+        counts.set(identity, (counts.get(identity) ?? 0) + row.count);
+    }
+    const poolKeys = new Map();
+    for (const row of rows) {
+        if (row.metric !== 'requests')
+            continue;
+        const pool = JSON.stringify([row.platform, row.quotaPoolKey]);
+        const keys = poolKeys.get(pool) ?? new Set();
+        keys.add(JSON.stringify([row.platform, row.quotaPoolKey, row.keyId]));
+        poolKeys.set(pool, keys);
+    }
+    for (const row of rows) {
+        const keys = poolKeys.get(JSON.stringify([row.platform, row.quotaPoolKey])) ?? [];
+        let count = 0;
+        for (const key of keys)
+            count += counts.get(key) ?? 0;
+        const rate = count < MIN_FORECAST_REQUESTS ? null : Math.round(count / RATE_OBSERVATION_WINDOW_MINUTES * 100) / 100;
+        const entry = entryFor(row, rate, now);
+        if (!entry)
+            continue;
+        // `pool` already carries its platform ("groq::account"), so it is the key.
+        const key = entry.pool;
+        const prev = byKey.get(key);
+        if (!prev || (entry.remaining_pct ?? Infinity) < (prev.remaining_pct ?? Infinity)) {
+            byKey.set(key, entry);
+        }
+    }
+    return [...byKey.values()].sort((a, b) => {
+        // Low-balance pools first — the ones the caller most needs to see.
+        if (a.low_balance !== b.low_balance)
+            return a.low_balance ? -1 : 1;
+        return a.platform.localeCompare(b.platform);
+    });
+}
+//# sourceMappingURL=quota-forecast.js.map

package/dist/services/quota-forecast.js.map

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

package/dist/services/quota-outlook.d.ts

@@ -0,0 +1,4 @@
+import type { QuotaOutlookResponse } from '@srouter/shared/types.js';
+/** Local activity is measurable even without provider quota headers. No probes or writes. */
+export declare function getQuotaOutlook(): QuotaOutlookResponse;
+//# sourceMappingURL=quota-outlook.d.ts.map

package/dist/services/quota-outlook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-outlook.d.ts","sourceRoot":"","sources":["../../src/services/quota-outlook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAwBvF,6FAA6F;AAC7F,wBAAgB,eAAe,IAAI,oBAAoB,CA8DtD"}

package/dist/services/quota-outlook.js

@@ -0,0 +1,92 @@
+import { getQuotaStateForKeys } from './provider-quota.js';
+import { estimateExhaustionAt, getRecentQuotaActivity, MIN_FORECAST_REQUESTS, RATE_OBSERVATION_WINDOW_MINUTES } from './quota-forecast.js';
+const WARNING_REMAINING_RATIO = 0.2;
+const WARNING_EXHAUSTION_MS = 2 * 60 * 60_000;
+const MAX_OBSERVATION_AGE_MS = RATE_OBSERVATION_WINDOW_MINUTES * 60_000;
+function utcMillis(value) {
+    if (!value)
+        return NaN;
+    return Date.parse(value.includes('T') ? value : value.replace(' ', 'T') + 'Z');
+}
+function unavailableReason(row, now) {
+    if (row.limit == null || !Number.isFinite(row.limit) || row.limit <= 0
+        || row.remaining == null || !Number.isFinite(row.remaining) || row.remaining < 0 || row.remaining > row.limit)
+        return 'quota_not_reported';
+    const observed = utcMillis(row.observedAt);
+    const reset = utcMillis(row.resetAt);
+    if (!Number.isFinite(observed) || observed > now || now - observed > MAX_OBSERVATION_AGE_MS
+        || (Number.isFinite(reset) && reset <= now))
+        return 'stale_observation';
+    if (!Number.isFinite(row.confidence) || row.confidence < 0.7)
+        return 'low_confidence';
+    return Number.isFinite(reset) ? null : 'reset_not_reported';
+}
+/** Local activity is measurable even without provider quota headers. No probes or writes. */
+export function getQuotaOutlook() {
+    const now = Date.now();
+    const activity = getRecentQuotaActivity(now);
+    const counts = new Map();
+    for (const row of activity)
+        counts.set(row.pool, (counts.get(row.pool) ?? 0) + row.count);
+    const selected = new Map();
+    const rank = (row) => {
+        const reason = unavailableReason(row, now);
+        return reason === null ? 0 : reason === 'reset_not_reported' ? 1 : reason === 'quota_not_reported' ? 3 : 2;
+    };
+    for (const row of getQuotaStateForKeys({ normalizeExpired: false })) {
+        if (row.metric !== 'requests')
+            continue;
+        const previous = selected.get(row.quotaPoolKey);
+        // A stale legacy key must not hide a current account reading. Among usable
+        // readings, retain the tightest pool balance (same rounded-percent tie break).
+        const score = (value) => value.limit != null && value.limit > 0 && value.remaining != null
+            ? Math.round(value.remaining / value.limit * 100) : Infinity;
+        if (!previous || rank(row) < rank(previous) || (rank(row) === rank(previous) && score(row) < score(previous))) {
+            selected.set(row.quotaPoolKey, row);
+        }
+    }
+    const pools = [];
+    for (const row of selected.values()) {
+        const reason = unavailableReason(row, now);
+        const count = counts.get(row.quotaPoolKey) ?? 0;
+        const rate = Math.round(count / RATE_OBSERVATION_WINDOW_MINUTES * 100) / 100;
+        const known = reason !== 'quota_not_reported';
+        const resetMs = utcMillis(row.resetAt);
+        const resetAt = Number.isFinite(resetMs) ? new Date(resetMs).toISOString() : null;
+        const exhaustion = reason === null && count >= MIN_FORECAST_REQUESTS && row.remaining > 0
+            ? estimateExhaustionAt(row.remaining, rate, resetAt, now) : null;
+        const status = reason === 'quota_not_reported' ? 'unknown'
+            : reason === 'stale_observation' ? 'stale'
+                : reason ? 'unavailable'
+                    : row.remaining === 0 ? 'exhausted'
+                        : count < MIN_FORECAST_REQUESTS ? 'insufficient_data'
+                            : exhaustion ? 'forecast' : 'resets_first';
+        let warning = null;
+        if (reason === null) {
+            if (row.remaining / row.limit < WARNING_REMAINING_RATIO)
+                warning = 'low_balance';
+            else if (exhaustion && Date.parse(exhaustion) - now <= WARNING_EXHAUSTION_MS)
+                warning = 'exhausting_soon';
+        }
+        pools.push({
+            platform: row.platform, pool: row.quotaPoolKey, limit: row.limit, remaining: row.remaining,
+            remainingPct: known ? Math.round(row.remaining / row.limit * 100) : null,
+            observedAt: row.observedAt, resetAt,
+            recentRequestCount: count, ratePerMin: rate, estimatedExhaustionAt: exhaustion,
+            unavailableReason: reason, status, warning,
+        });
+    }
+    // Providers without any quota observations still have locally recorded usage.
+    for (const row of activity) {
+        if (selected.has(row.pool) || pools.some(pool => pool.pool === row.pool))
+            continue;
+        const count = counts.get(row.pool);
+        pools.push({ platform: row.platform, pool: row.pool, limit: null, remaining: null, remainingPct: null,
+            observedAt: null, resetAt: null, recentRequestCount: count, ratePerMin: Math.round(count / RATE_OBSERVATION_WINDOW_MINUTES * 100) / 100,
+            estimatedExhaustionAt: null, unavailableReason: 'quota_not_reported', status: 'unknown', warning: null });
+    }
+    pools.sort((a, b) => Number(Boolean(b.warning)) - Number(Boolean(a.warning)) || a.pool.localeCompare(b.pool));
+    return { generatedAt: new Date(now).toISOString(), observationWindowMinutes: RATE_OBSERVATION_WINDOW_MINUTES,
+        minimumRequests: MIN_FORECAST_REQUESTS, pools };
+}
+//# sourceMappingURL=quota-outlook.js.map

package/dist/services/quota-outlook.js.map

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

package/dist/services/ratelimit.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Concurrent in-flight requests allowed per key, or null for unlimited.
+ *
+ * Some free tiers meter concurrency per credential rather than per minute, so
+ * parallel streams on one key mostly 429 each other. But most do not, and
+ * capping by default would serialise every provider and cost real throughput —
+ * so this is opt-in. There is deliberately no built-in per-platform table: the
+ * providers that behave this way are not documented well enough to assert a
+ * number for them here, and a wrong default is worse than none.
+ *
+ * `MAX_CONCURRENT_REQUESTS_PER_KEY_<PLATFORM>` sets it for one platform;
+ * `MAX_CONCURRENT_REQUESTS_PER_KEY` sets a fallback for all of them.
+ */
+export declare function getKeyConcurrencyLimit(platform: string): number | null;
+/** Requests this process currently has in flight against one platform+key. */
+export declare function inFlightForKey(platform: string, keyId: number, now?: number): number;
+/** False when this key already has its allowed number of requests in the air.
+ *  Always true when no cap is configured, which is the default. */
+export declare function canUseKeyConcurrency(platform: string, keyId: number, now?: number): boolean;
+/** Take a lease for an attempt about to be dispatched. Returns the id to release. */
+export declare function acquireLease(platform: string, modelId: string, keyId: number, tokens: number, now?: number): number;
+/** Release a lease. Idempotent, so a double release from overlapping cleanup
+ *  paths is harmless. */
+export declare function releaseLease(leaseId: number): void;
+/** Test seam: drop all leases. */
+export declare function resetLeases(): void;
+export declare function canMakeRequest(platform: string, modelId: string, keyId: number, limits: {
+    rpm: number | null;
+    rpd: number | null;
+    tpm: number | null;
+    tpd: number | null;
+}): boolean;
+export declare function canUseTokens(platform: string, modelId: string, keyId: number, estimatedTokens: number, limits: {
+    tpm: number | null;
+    tpd: number | null;
+}): boolean;
+export interface WindowLimits {
+    rpm: number | null;
+    rpd: number | null;
+    tpm: number | null;
+    tpd: number | null;
+}
+/** Drop the memoised window snapshot. Tests use it to make a write visible
+ *  immediately; production relies on the TTL. */
+export declare function invalidateWindowUsage(): void;
+/**
+ * Share of its binding rate-limit window a model has already consumed, as a
+ * 0..1 fraction (0 idle, 1 exhausted). null = no opinion: the model declares no
+ * window limits, has no routable key to measure, or the database is unreachable.
+ *
+ * Which key's numbers to report matters, and the answer is the same one the
+ * dashboard's usage badge settled on (#921): the guardrail asks "how close is
+ * this model to being unroutable", so it must follow the key the router would
+ * pick NEXT, not the worst key on the account. A platform with one exhausted
+ * key and one idle key routes perfectly well, so we take the ELIGIBLE key with
+ * the MOST headroom.
+ *
+ * In-flight leases are deliberately not counted. They exist to close the
+ * check-then-act race on the hard gates; this is a steering signal averaged over
+ * a whole window, and folding a per-request quantity into a cached snapshot
+ * would buy noise, not accuracy.
+ */
+export declare function modelWindowUsedFraction(model: {
+    platform: string;
+    modelId: string;
+    keyId?: number | null;
+}, limits: WindowLimits, now?: number): number | null;
+export declare function getProviderDailyRequestCap(platform: string): number | null;
+/** Account-wide requests-per-minute cap, or null when the provider has none.
+ *  `PROVIDER_MINUTE_REQUEST_CAP_<PLATFORM>=0` disables the gate for that platform. */
+export declare function getProviderMinuteRequestCap(platform: string): number | null;
+export declare function getProviderDailyTokenCap(platform: string): number | null;
+export declare function providerDailyRequestCount(platform: string, keyId: number, now?: number): number;
+export declare function canUseProvider(platform: string, keyId: number, now?: number): boolean;
+/** Requests in the last minute for a provider account+key, across every model. */
+export declare function providerMinuteRequestCount(platform: string, keyId: number, now?: number): number;
+export declare function canUseProviderMinute(platform: string, keyId: number, now?: number): boolean;
+export declare function providerDailyTokenCount(platform: string, keyId: number, now?: number): number;
+export declare function canUseProviderTokens(platform: string, keyId: number, modelId: string, estimatedTokens: number, now?: number): boolean;
+export declare function recordRequest(platform: string, modelId: string, keyId: number): void;
+export declare function recordTokens(platform: string, modelId: string, keyId: number, tokens: number): void;
+export type CooldownSource = 'heuristic' | 'authoritative' | 'credit' | 'tier';
+export declare const COOLDOWN_CEILING_KEY = "routing_cooldown_ceiling_ms";
+export declare const MIN_COOLDOWN_CEILING_MS: number;
+export declare const MAX_COOLDOWN_CEILING_MS: number;
+/** The configured ceiling in ms, or null when unset/invalid (no cap). Read
+ *  through a try/catch like every other DB touch in this module so a failure
+ *  before the DB is ready degrades to "no cap" instead of throwing mid-route. */
+export declare function getCooldownCeilingMs(): number | null;
+/** null clears the ceiling (back to the uncapped ladder). */
+export declare function setCooldownCeilingMs(value: number | null): void;
+/** Apply the operator ceiling to one of OUR heuristic bench durations. */
+export declare function capCooldownMs(durationMs: number): number;
+export declare function getNextCooldownDuration(platform: string, modelId: string, keyId: number): number;
+export declare const PAYMENT_REQUIRED_COOLDOWN_MS: number;
+/** The 402 bench with the operator ceiling applied (#952). */
+export declare function getPaymentRequiredCooldownMs(): number;
+export declare const MODEL_FORBIDDEN_COOLDOWN_MS: number;
+/** The 403 tier bench with the operator ceiling applied (#952). */
+export declare function getModelForbiddenCooldownMs(): number;
+export declare function recentHitCount(platform: string, modelId: string, keyId: number, now: number, windowMs?: number): number;
+export interface CooldownDecision {
+    durationMs: number;
+    source: CooldownSource;
+}
+export declare const LOCAL_ENDPOINT_COOLDOWN_MS = 5000;
+export declare function isLocalEndpointKey(keyId: number): boolean;
+/** Test hook: the locality verdict is cached per key id for the process
+ *  lifetime (see above); tests that rewrite api_keys rows need a reset. */
+export declare function resetKeyLocalityCache(): void;
+export interface CooldownLimitOptions {
+    /** Whether the triggering failure is an actual provider quota signal (a real
+     *  429 / rate-limit-classified error — see isRateLimitSignal in
+     *  lib/error-classify.ts). Timeouts, 5xx and transport errors are retryable
+     *  but carry no quota information, so they must not feed the null-limits
+     *  exhaustion heuristic below (#592) — they get the short transient bench.
+     *  Defaults to true: legacy callers without error context (fusion's
+     *  empty-completion benches) keep their pre-#592 behavior. */
+    quotaSignal?: boolean;
+}
+export declare function getCooldownDurationForLimit(platform: string, modelId: string, keyId: number, limits: {
+    rpd: number | null;
+    tpd: number | null;
+}, retryAfterMs?: number | null, opts?: CooldownLimitOptions): number;
+/**
+ * Same verdict as getCooldownDurationForLimit, plus the provenance the
+ * cooldown-probe recovery job needs: 'authoritative' when an explicit provider
+ * Retry-After actually determined the expiry (a fact — never probed early),
+ * 'heuristic' when the duration is our own transient/escalation guess (probe-
+ * eligible). A Retry-After SHORTER than our bench does not make the cooldown
+ * authoritative: everything past the provider's own retry time is our guess.
+ */
+export declare function getCooldownDecisionForLimit(platform: string, modelId: string, keyId: number, limits: {
+    rpd: number | null;
+    tpd: number | null;
+}, retryAfterMs?: number | null, opts?: CooldownLimitOptions): CooldownDecision;
+/**
+ * Delete every already-expired cooldown, on disk and in memory, and return how
+ * many rows went. Expiry is otherwise purely lazy: isOnCooldown drops a row only
+ * when something asks about that exact (platform, model, key), so a row whose
+ * model was retired, whose key was deleted, or that simply outlived a process
+ * that had every route benched is never collected — the table only grows, and
+ * every cooldown query (status rollups, the probe scan, penalty inspector) pays
+ * for the dead rows. Called once at boot (index.ts) so a restart starts clean.
+ */
+export declare function cleanupExpiredCooldowns(now?: number): number;
+export declare function setCooldown(platform: string, modelId: string, keyId: number, durationMs?: number, source?: CooldownSource): void;
+export declare function isOnCooldown(platform: string, modelId: string, keyId: number): boolean;
+export interface ActiveCooldown {
+    platform: string;
+    modelId: string;
+    keyId: number;
+    expiresAtMs: number;
+    remainingMs: number;
+}
+/**
+ * Active cooldowns for the given keys, grouped by key id. Batched into one query
+ * so the dashboard can render "why is this key idle?" without N round-trips.
+ * Without this, a key benched by an escalated cooldown (up to 24h) is invisible:
+ * it reads as healthy and enabled while the router silently skips it.
+ */
+export declare function getActiveCooldownsForKeys(keyIds: number[], now?: number): Map<number, ActiveCooldown[]>;
+/**
+ * Drop every cooldown for one key, in memory and on disk, and return how many
+ * were cleared. Escalated cooldowns can bench a key for up to 24h off a single
+ * bad window; an operator who has fixed the cause (raised a quota, waited out a
+ * provider incident) otherwise has no way back except restarting and waiting.
+ */
+export declare function clearCooldownsForKey(keyId: number): number;
+/**
+ * Drop EVERY cooldown (all keys, all models), the escalation-ladder counters
+ * and the null-limits hit windows — the "my whole pool is stuck" escape hatch
+ * (#952). Returns how many active benches were lifted. Penalties and the
+ * model-failure windows live elsewhere; services/penalty-inspector.ts
+ * composes all three into one clear.
+ */
+export declare function clearAllCooldowns(now?: number): number;
+export interface ProbeableCooldown {
+    platform: string;
+    modelId: string;
+    keyId: number;
+    expiresAtMs: number;
+    setAtMs: number | null;
+}
+/**
+ * Active cooldowns whose expiry is OUR OWN guess ('heuristic'), i.e. the only
+ * ones probe-based early recovery may touch. Authoritative/credit/tier rows are
+ * excluded at the query so the prober cannot even see them. Deliberately
+ * DB-only, no in-memory fallback: the probe job is a best-effort optimisation,
+ * and when the DB is unavailable the right amount of probing is none.
+ */
+export declare function getProbeableCooldowns(now?: number): ProbeableCooldown[];
+/**
+ * Clear ONE model+key cooldown before its timer expires, after a probe showed
+ * the key is serving again. Narrower than clearCooldownsForKey (the operator
+ * override): the escalation history in cooldownHits is deliberately kept, so a
+ * key that 429s again right after an early recovery re-enters the ladder where
+ * it left off instead of starting back at 2 minutes.
+ */
+export declare function clearCooldownEarly(platform: string, modelId: string, keyId: number): void;
+/**
+ * Soonest moment any active cooldown expires, in ms since epoch, or null when
+ * nothing is cooling down. Used to tell an exhausted caller roughly when to
+ * retry (#423) instead of the bare "wait for rate limits to reset".
+ */
+export declare function getSoonestCooldownExpiry(now?: number): number | null;
+export declare function getRateLimitStatus(platform: string, modelId: string, keyId: number, limits: {
+    rpm: number | null;
+    rpd: number | null;
+    tpm: number | null;
+    tpd: number | null;
+}): {
+    rpm: {
+        used: number;
+        limit: number | null;
+    };
+    rpd: {
+        used: number;
+        limit: number | null;
+    };
+    tpm: {
+        used: number;
+        limit: number | null;
+    };
+};
+export type LearnedLimitKind = 'tpm' | 'tpd' | 'rpm' | 'rpd';
+export interface LearnedLimit {
+    kind: LearnedLimitKind;
+    limit: number;
+}
+/**
+ * Pure parser: pull a provider-reported ceiling out of an error message. Returns
+ * null unless BOTH a numeric "Limit N" and a confident axis (TPM/TPD/RPM/RPD)
+ * are present — guessing the axis would write the wrong column and mis-route
+ * every future request, so we refuse to guess.
+ */
+export declare function parseProviderLimit(message: string | undefined | null): LearnedLimit | null;
+/**
+ * Persist a provider-reported limit onto the model row, but ONLY when it makes
+ * us more conservative: fill a NULL (unknown) limit, or LOWER an existing one
+ * that was too high. Never raises a limit — hitting a ceiling means our pre-check
+ * already let too much through, so the true limit is at or below what we used.
+ * Returns the learned limit when a row was actually changed, else null.
+ * DB-guarded (no-op when the DB is unavailable), like the rest of this module.
+ */
+export declare function learnLimitFromError(modelDbId: number, err: {
+    message?: string;
+}): LearnedLimit | null;
+//# sourceMappingURL=ratelimit.d.ts.map

package/dist/services/ratelimit.d.ts.map

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