@juspay/neurolink 11.1.1 → 11.2.1

package/dist/lib/auth/index.d.ts

@@ -14,6 +14,7 @@ export { ANTHROPIC_OAUTH_BASE_URL, DEFAULT_SCOPES, DEFAULT_REDIRECT_URI, DEFAULT
 export { AnthropicOAuth } from "./anthropicOAuth.js";
 export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenValidationError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "../types/index.js";
 export { createAnthropicOAuth, createAnthropicOAuthConfig, hasAnthropicOAuthCredentials, startCallbackServer, stopCallbackServer, performOAuthFlow, } from "./anthropicOAuth.js";
+export { CODEX_CLIENT_ID, CODEX_AUTH_URL, CODEX_TOKEN_URL, CODEX_REDIRECT_URI, CODEX_DEFAULT_SCOPES, CODEX_BACKEND_BASE_URL, CODEX_RESPONSES_URL, CODEX_USAGE_URL, CODEX_USER_AGENT, CODEX_ORIGINATOR, decodeCodexAccessToken, decodeCodexEmail, resolveCodexAccountId, importCodexAuthFile, refreshCodexToken, codexTokenNeedsRefresh, } from "./codexOAuth.js";
 export { TokenStore, tokenStore, defaultTokenStore } from "./tokenStore.js";
 export { TokenStoreError } from "../types/index.js";
 export { AccountPool } from "./accountPool.js";

package/dist/lib/auth/index.js

@@ -23,6 +23,10 @@ export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthToke
 export { createAnthropicOAuth, createAnthropicOAuthConfig, hasAnthropicOAuthCredentials, startCallbackServer, stopCallbackServer, performOAuthFlow, } from "./anthropicOAuth.js";
 // OAuth types (canonical definitions in types/subscriptionTypes.ts)
 // =============================================================================
+// CODEX (ChatGPT) OAUTH - subscription pool support
+// =============================================================================
+export { CODEX_CLIENT_ID, CODEX_AUTH_URL, CODEX_TOKEN_URL, CODEX_REDIRECT_URI, CODEX_DEFAULT_SCOPES, CODEX_BACKEND_BASE_URL, CODEX_RESPONSES_URL, CODEX_USAGE_URL, CODEX_USER_AGENT, CODEX_ORIGINATOR, decodeCodexAccessToken, decodeCodexEmail, resolveCodexAccountId, importCodexAuthFile, refreshCodexToken, codexTokenNeedsRefresh, } from "./codexOAuth.js";
+// =============================================================================
 // TOKEN STORE - Secure Token Storage
 // =============================================================================
 // Main TokenStore class and instances

package/dist/lib/providers/configuredOpenAICompat.d.ts

@@ -0,0 +1,24 @@
+import type { AIProviderName } from "../constants/enums.js";
+import type { OpenAICompatCatalogEntry, OpenAICompatCredentials } from "../types/index.js";
+import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
+/**
+ * Generic OpenAI-compatible provider driven entirely by an
+ * OpenAICompatCatalogEntry. Replaces a hand-written subclass for any
+ * provider whose only differences from its siblings are credentials, base
+ * URL, model defaults, and error-classification rules — see
+ * OPENAI_COMPAT_CATALOG in openaiCompatCatalog.ts for the entries.
+ *
+ * If a provider needs a real hook override (adjustRequestBody,
+ * adjustBodyAfter400, getChatCompletionsURL, getAuthHeaders,
+ * suppressResponseFormatWithTools, ...) it does NOT belong in the catalog —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts).
+ */
+export declare class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvider {
+    private readonly entry;
+    constructor(entry: OpenAICompatCatalogEntry, modelName?: string, sdk?: unknown, credentials?: OpenAICompatCredentials);
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    protected getFallbackModelName(): string;
+    protected getFallbackModels(): string[];
+    protected formatProviderError(error: unknown): Error;
+}

package/dist/lib/providers/configuredOpenAICompat.js

@@ -0,0 +1,60 @@
+import { logger } from "../utils/logger.js";
+import { redactUrlCredentials } from "../utils/logSanitize.js";
+import { getProviderModel, resolveOpenAICompatConfig, } from "../utils/providerConfig.js";
+import { classifyProviderError } from "../utils/errorClassifier.js";
+import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
+/**
+ * Generic OpenAI-compatible provider driven entirely by an
+ * OpenAICompatCatalogEntry. Replaces a hand-written subclass for any
+ * provider whose only differences from its siblings are credentials, base
+ * URL, model defaults, and error-classification rules — see
+ * OPENAI_COMPAT_CATALOG in openaiCompatCatalog.ts for the entries.
+ *
+ * If a provider needs a real hook override (adjustRequestBody,
+ * adjustBodyAfter400, getChatCompletionsURL, getAuthHeaders,
+ * suppressResponseFormatWithTools, ...) it does NOT belong in the catalog —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts).
+ */
+export class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvider {
+    entry;
+    constructor(entry, modelName, sdk, credentials) {
+        const { apiKey, baseURL } = resolveOpenAICompatConfig(entry, credentials);
+        // BaseProvider's constructor calls `this.getDefaultModel()` /
+        // `this.getProviderName()` synchronously inside `super()`, before this
+        // class's own constructor body (or field initializers) ever run — so
+        // `this.entry` is not yet assigned at that point and those overrides
+        // would read `undefined.modelEnvVar`. `entry.providerName` is always
+        // defined, so passing it straight through makes the base constructor's
+        // `providerName || this.getProviderName()` short-circuit; resolving the
+        // model up front and always passing a truthy `modelName` does the same
+        // for `getDefaultModel()`. Both overrides remain correct for any call
+        // made after construction, once `this.entry` is set below.
+        const resolvedModelName = modelName || getProviderModel(entry.modelEnvVar, entry.defaultModel);
+        super(entry.providerName, resolvedModelName, sdk, { baseURL, apiKey });
+        this.entry = entry;
+        logger.debug(`${entry.configOptions.providerName} Provider initialized`, {
+            modelName: this.modelName,
+            providerName: this.providerName,
+            baseURL: redactUrlCredentials(this.config.baseURL),
+        });
+    }
+    getProviderName() {
+        return this.entry.providerName;
+    }
+    getDefaultModel() {
+        return getProviderModel(this.entry.modelEnvVar, this.entry.defaultModel);
+    }
+    getFallbackModelName() {
+        return this.entry.fallbackModelName;
+    }
+    getFallbackModels() {
+        return this.entry.fallbackModels;
+    }
+    formatProviderError(error) {
+        // classifyProviderError handles TimeoutError internally (always maps
+        // to NetworkError, ahead of any rule table) — no local pre-check
+        // needed or wanted here; see this task's design note.
+        return classifyProviderError(error, this.entry.errorRules, this.entry.providerName, this.modelName);
+    }
+}
+//# sourceMappingURL=configuredOpenAICompat.js.map

package/dist/lib/providers/openaiCompatCatalog.d.ts

@@ -0,0 +1,24 @@
+import type { OpenAICompatCatalogEntry } from "../types/index.js";
+/**
+ * Config-driven catalog of the 7 zero-quirk OpenAI-compatible providers.
+ * Each entry fully replaces what used to be a hand-written
+ * OpenAIChatCompletionsProvider subclass — see ConfiguredOpenAICompatProvider
+ * for the class that reads these entries, and providerRegistry.ts for the
+ * registration loop that consumes this array.
+ *
+ * `errorRules` mirrors each provider's LIVE `formatProviderError` rule array
+ * (post plan-07/wave-2 migration), not the original hand-rolled ladder these
+ * providers had when plan 05 was first drafted: every provider below now
+ * keeps only its bespoke rule(s) — auth, plus Groq's model_decommissioned and
+ * xAI's insufficient_quota — before spreading the SAME exported
+ * `DEFAULT_ERROR_RULES` constant that the live subclasses spread (never an
+ * inlined copy, so this catalog cannot drift from that table independently).
+ * See plan-05/progress.md Ruling R4 for the full rationale.
+ *
+ * To add a new zero-quirk OpenAI-compatible provider: add one entry here.
+ * Do NOT add a provider here if it needs any hook override beyond the 3
+ * mandatory ones (getProviderName/getDefaultModel/formatProviderError) —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts, and
+ * Task 14's docs task for the deciding criteria).
+ */
+export declare const OPENAI_COMPAT_CATALOG: readonly OpenAICompatCatalogEntry[];

package/dist/lib/providers/openaiCompatCatalog.js

@@ -0,0 +1,272 @@
+import { AIProviderName } from "../constants/enums.js";
+import { CloudflareModels, FireworksModels, GroqModels, MistralModels, PerplexityModels, TogetherAIModels, XaiModels, } from "../constants/enums.js";
+import { AuthenticationError, InvalidModelError, ProviderError, } from "../types/index.js";
+import { DEFAULT_ERROR_RULES } from "../utils/errorClassifier.js";
+import { createCloudflareConfig, createFireworksConfig, createGroqConfig, createMistralConfig, createPerplexityConfig, createTogetherAIConfig, createXaiConfig, } from "../utils/providerConfig.js";
+function buildCloudflareBaseURL(accountId) {
+    return `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`;
+}
+/**
+ * Config-driven catalog of the 7 zero-quirk OpenAI-compatible providers.
+ * Each entry fully replaces what used to be a hand-written
+ * OpenAIChatCompletionsProvider subclass — see ConfiguredOpenAICompatProvider
+ * for the class that reads these entries, and providerRegistry.ts for the
+ * registration loop that consumes this array.
+ *
+ * `errorRules` mirrors each provider's LIVE `formatProviderError` rule array
+ * (post plan-07/wave-2 migration), not the original hand-rolled ladder these
+ * providers had when plan 05 was first drafted: every provider below now
+ * keeps only its bespoke rule(s) — auth, plus Groq's model_decommissioned and
+ * xAI's insufficient_quota — before spreading the SAME exported
+ * `DEFAULT_ERROR_RULES` constant that the live subclasses spread (never an
+ * inlined copy, so this catalog cannot drift from that table independently).
+ * See plan-05/progress.md Ruling R4 for the full rationale.
+ *
+ * To add a new zero-quirk OpenAI-compatible provider: add one entry here.
+ * Do NOT add a provider here if it needs any hook override beyond the 3
+ * mandatory ones (getProviderName/getDefaultModel/formatProviderError) —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts, and
+ * Task 14's docs task for the deciding criteria).
+ */
+export const OPENAI_COMPAT_CATALOG = [
+    {
+        providerName: AIProviderName.GROQ,
+        aliases: ["groq"],
+        apiKeyEnvVar: "GROQ_API_KEY",
+        baseURLEnvVar: "GROQ_BASE_URL",
+        defaultBaseURL: "https://api.groq.com/openai/v1",
+        configOptions: createGroqConfig(),
+        modelEnvVar: "GROQ_MODEL",
+        defaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
+        registryDefaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: GroqModels.LLAMA_3_1_8B_INSTANT,
+        fallbackModels: [
+            GroqModels.LLAMA_3_3_70B_VERSATILE,
+            GroqModels.LLAMA_3_1_8B_INSTANT,
+            GroqModels.GEMMA_2_9B_IT,
+            GroqModels.MIXTRAL_8X7B_32768,
+            GroqModels.LLAMA_3_2_90B_VISION_PREVIEW,
+            GroqModels.LLAMA_3_2_11B_VISION_PREVIEW,
+        ],
+        // KNOWN GAP (not reproducible by this data-only array — flagged for PR C,
+        // see plan-05/task-A-report.md): live GroqProvider.formatProviderError()
+        // intercepts TimeoutError and returns a plain ProviderError BEFORE ever
+        // calling classifyProviderError, overriding that function's own
+        // (non-overridable) rule that TimeoutError always maps to NetworkError.
+        // ConfiguredOpenAICompatProvider.formatProviderError() has no such
+        // pre-check hook, so migrating Groq onto it as-is would silently
+        // reclassify Groq timeouts as NetworkError. This entry's errorRules
+        // still mirrors Groq's live rule array faithfully for every other error
+        // shape; the TimeoutError special case is a structural gap in
+        // ConfiguredOpenAICompatProvider, not a data error here.
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Groq API key. Check GROQ_API_KEY. Get one at https://console.groq.com/keys",
+            },
+            {
+                match: (ctx) => /model_decommissioned/i.test(ctx.message),
+                errorClass: InvalidModelError,
+                message: (ctx) => `Groq model '${ctx.modelName}' was decommissioned. Pick a current model from https://console.groq.com/docs/models.`,
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.XAI,
+        aliases: ["xai", "grok"],
+        apiKeyEnvVar: "XAI_API_KEY",
+        baseURLEnvVar: "XAI_BASE_URL",
+        defaultBaseURL: "https://api.x.ai/v1",
+        configOptions: createXaiConfig(),
+        modelEnvVar: "XAI_MODEL",
+        defaultModel: XaiModels.GROK_3,
+        registryDefaultModel: XaiModels.GROK_3,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: XaiModels.GROK_3_MINI,
+        fallbackModels: [
+            XaiModels.GROK_3,
+            XaiModels.GROK_3_MINI,
+            XaiModels.GROK_2_LATEST,
+            XaiModels.GROK_2_VISION_LATEST,
+            XaiModels.GROK_BETA,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid xAI API key. Please check your XAI_API_KEY environment variable. Get one at https://console.x.ai/",
+            },
+            {
+                match: (ctx) => /insufficient_quota|quota exceeded/i.test(ctx.message),
+                errorClass: ProviderError,
+                message: "xAI account has insufficient quota. Top up at https://console.x.ai/",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.TOGETHER_AI,
+        aliases: ["together-ai", "together"],
+        apiKeyEnvVar: "TOGETHER_API_KEY",
+        baseURLEnvVar: "TOGETHER_BASE_URL",
+        defaultBaseURL: "https://api.together.xyz/v1",
+        configOptions: createTogetherAIConfig(),
+        modelEnvVar: "TOGETHER_MODEL",
+        defaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+        registryDefaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
+        fallbackModels: [
+            TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_405B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_70B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
+            TogetherAIModels.MIXTRAL_8X22B_INSTRUCT,
+            TogetherAIModels.QWEN_2_5_72B_INSTRUCT_TURBO,
+            TogetherAIModels.DEEPSEEK_R1,
+            TogetherAIModels.DEEPSEEK_V3,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Together AI API key. Get one at https://api.together.xyz/settings/api-keys",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.FIREWORKS,
+        aliases: ["fireworks"],
+        apiKeyEnvVar: "FIREWORKS_API_KEY",
+        baseURLEnvVar: "FIREWORKS_BASE_URL",
+        defaultBaseURL: "https://api.fireworks.ai/inference/v1",
+        configOptions: createFireworksConfig(),
+        modelEnvVar: "FIREWORKS_MODEL",
+        defaultModel: FireworksModels.DEEPSEEK_V4_PRO,
+        registryDefaultModel: FireworksModels.DEEPSEEK_V4_PRO,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: FireworksModels.DEEPSEEK_V4_PRO,
+        fallbackModels: [
+            FireworksModels.DEEPSEEK_V4_PRO,
+            FireworksModels.GLM_5P1,
+            FireworksModels.GLM_5,
+            FireworksModels.KIMI_K2P6,
+            FireworksModels.KIMI_K2P5,
+            FireworksModels.GPT_OSS_120B,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Fireworks API key. Get one at https://fireworks.ai/account/api-keys",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.PERPLEXITY,
+        aliases: ["perplexity", "pplx"],
+        apiKeyEnvVar: "PERPLEXITY_API_KEY",
+        baseURLEnvVar: "PERPLEXITY_BASE_URL",
+        defaultBaseURL: "https://api.perplexity.ai",
+        configOptions: createPerplexityConfig(),
+        modelEnvVar: "PERPLEXITY_MODEL",
+        defaultModel: PerplexityModels.SONAR,
+        registryDefaultModel: PerplexityModels.SONAR,
+        registryDefaultModelChecksEnvVar: true,
+        // Perplexity's live class does NOT override getFallbackModelName() — it
+        // inherits the base class default "gpt-3.5-turbo". Preserved here
+        // verbatim, not "fixed" to a Perplexity model — that's a real,
+        // pre-existing quirk this plan is not authorized to change.
+        fallbackModelName: "gpt-3.5-turbo",
+        fallbackModels: [
+            PerplexityModels.SONAR,
+            PerplexityModels.SONAR_PRO,
+            PerplexityModels.SONAR_REASONING,
+            PerplexityModels.SONAR_REASONING_PRO,
+            PerplexityModels.SONAR_DEEP_RESEARCH,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Perplexity API key. Get one at https://www.perplexity.ai/settings/api",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.MISTRAL,
+        aliases: ["mistral"],
+        apiKeyEnvVar: "MISTRAL_API_KEY",
+        baseURLEnvVar: "MISTRAL_BASE_URL",
+        defaultBaseURL: "https://api.mistral.ai/v1",
+        configOptions: createMistralConfig(),
+        modelEnvVar: "MISTRAL_MODEL",
+        defaultModel: MistralModels.MISTRAL_SMALL_2506,
+        // The one documented registry-vs-class default-model quirk (see this
+        // plan's "Design reference" section): the registry passes the bare
+        // literal MISTRAL_LARGE_LATEST with no env-var check, while
+        // MistralProvider.getDefaultModel() checks MISTRAL_MODEL and defaults to
+        // MISTRAL_SMALL_2506. Preserved exactly, not reconciled.
+        registryDefaultModel: MistralModels.MISTRAL_LARGE_LATEST,
+        registryDefaultModelChecksEnvVar: false,
+        fallbackModelName: MistralModels.MISTRAL_SMALL_2506,
+        fallbackModels: [
+            MistralModels.MISTRAL_SMALL_2506,
+            MistralModels.MISTRAL_LARGE_LATEST,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /API_KEY_INVALID|Invalid API key|Unauthorized/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Mistral API key. Please check your MISTRAL_API_KEY environment variable.",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.CLOUDFLARE,
+        aliases: ["cloudflare", "workers-ai", "cf-ai"],
+        apiKeyEnvVar: "CLOUDFLARE_API_KEY",
+        computedBaseURL: {
+            envVar: "CLOUDFLARE_ACCOUNT_ID",
+            missingValueMessage: "CLOUDFLARE_ACCOUNT_ID is required (or pass credentials.cloudflare.accountId). Get the account id from https://dash.cloudflare.com/",
+            build: buildCloudflareBaseURL,
+        },
+        configOptions: createCloudflareConfig(),
+        modelEnvVar: "CLOUDFLARE_MODEL",
+        defaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
+        registryDefaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: CloudflareModels.LLAMA_3_1_8B_FAST,
+        fallbackModels: [
+            CloudflareModels.LLAMA_3_3_70B_FAST,
+            CloudflareModels.LLAMA_3_1_70B_INSTRUCT,
+            CloudflareModels.LLAMA_3_1_8B_FAST,
+            CloudflareModels.LLAMA_3_2_11B_VISION,
+            CloudflareModels.MISTRAL_7B_INSTRUCT_V0_2,
+            CloudflareModels.QWEN_1P5_14B_CHAT_AWQ,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Cloudflare API key. Use a token with Workers AI Read+Write scope. Get one at https://dash.cloudflare.com/profile/api-tokens",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+];
+//# sourceMappingURL=openaiCompatCatalog.js.map

package/dist/lib/proxy/accountCooldown.js

@@ -2,7 +2,8 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { AsyncMutex } from "../utils/asyncMutex.js";
-import { ACCOUNT_COOLING_REASONS } from "./routingEvidence.js";
+import { logger } from "../utils/logger.js";
+import { ACCOUNT_COOLING_REASONS, MAX_COOLDOWN_MS_BY_REASON, } from "./routingEvidence.js";
 import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
 const COOLDOWN_FILE = "account-cooldowns.json";
 const VALID_REASONS = new Set(ACCOUNT_COOLING_REASONS);
@@ -32,13 +33,45 @@ function isPersistedCooldown(value) {
         typeof candidate.reason === "string" &&
         VALID_REASONS.has(candidate.reason));
 }
+/**
+ * Cap a persisted cooldown at what its reason can plausibly mean, measured from
+ * when it was written.
+ *
+ * Entries written before per-reason ceilings existed can hold a wildly
+ * out-of-range wait — a "session" cooldown running for days, from a single stale
+ * reset timestamp. Clamping on load heals those without operator action.
+ * Clamping rather than dropping keeps a legitimate long weekly cooldown intact.
+ */
+function sanitizePersistedCooldown(accountKey, entry) {
+    const ceiling = MAX_COOLDOWN_MS_BY_REASON[entry.reason];
+    if (ceiling === undefined) {
+        return entry;
+    }
+    const latest = entry.updatedAt + ceiling;
+    if (entry.coolingUntil <= latest) {
+        return entry;
+    }
+    // Announce it: an account silently parked far beyond what its reason can mean
+    // is exactly the condition that is hard to diagnose from the outside, and this
+    // runs once per process so it cannot become noise.
+    const hours = (ms) => (ms / 3_600_000).toFixed(1);
+    logger.always(`[proxy] cooldown clamp: ${accountKey} ${entry.reason} entry healed from ` +
+        `${hours(entry.coolingUntil - entry.updatedAt)}h to ` +
+        `${hours(ceiling)}h — the stored wait exceeded what "${entry.reason}" can mean`);
+    return { ...entry, coolingUntil: latest };
+}
 async function ensureAccountCooldownsLoaded() {
     if (!cacheLoaded) {
         if (!cacheLoadPromise) {
             cacheLoadPromise = (async () => {
                 try {
                     const parsed = JSON.parse(await readFile(getCooldownFilePath(), "utf8"));
-                    memoryCache = Object.fromEntries(Object.entries(parsed).filter((entry) => isPersistedCooldown(entry[1])));
+                    memoryCache = Object.fromEntries(Object.entries(parsed)
+                        .filter((entry) => isPersistedCooldown(entry[1]))
+                        .map(([key, entry]) => [
+                        key,
+                        sanitizePersistedCooldown(key, entry),
+                    ]));
                 }
                 catch {
                     memoryCache = {};

package/dist/lib/proxy/accountQuota.d.ts

@@ -9,7 +9,14 @@
  * updates an in-memory cache and debounces disk writes so the request/response
  * path is never blocked by file I/O.
  */
-import type { AccountQuota } from "../types/index.js";
+import type { AccountQuota, AccountQuotaWindow } from "../types/index.js";
+/**
+ * Collapse a wire model id to its family by dropping the snapshot date, so
+ * `claude-fable-5-20260115` and `claude-fable-5-20260320` both tag the same
+ * scoped window. Without this a window would stop matching the day Anthropic
+ * ships a new snapshot.
+ */
+export declare function modelFamilyToken(model: string): string;
 /** Read and normalize Anthropic's authoritative top-level unified status. */
 export declare function getUnifiedRateLimitStatus(headers: Headers | Record<string, string>): string | undefined;
 /**
@@ -20,13 +27,32 @@ export declare function getUnifiedRateLimitStatus(headers: Headers | Record<stri
  * fallback percentage together with an allowed overage status, which is the
  * equivalent provider state.
  */
-export declare function isQuotaOverageAvailable(quota: Pick<AccountQuota, "fallbackPercentage" | "fallbackStatus" | "overageStatus" | "overageInUse" | "upgradePaths"> | null | undefined): boolean;
+export declare function isQuotaOverageAvailable(quota: Pick<AccountQuota, "fallbackPercentage" | "fallbackStatus" | "overageStatus" | "overageInUse" | "overageEnabled" | "overageDisabledReason" | "upgradePaths"> | null | undefined): boolean;
 /**
  * Parse Anthropic rate-limit / quota headers into an `AccountQuota`.
  * Returns `null` when key headers are absent.
  * Pure computation — no I/O, no blocking.
  */
-export declare function parseQuotaHeaders(headers: Headers | Record<string, string>): AccountQuota | null;
+export declare function parseQuotaHeaders(headers: Headers | Record<string, string>, opts?: {
+    model?: string;
+    now?: number;
+}): AccountQuota | null;
+/**
+ * Merge dynamic limit windows across snapshots from different sources.
+ *
+ * The two sources see different things and neither is a superset: the usage API
+ * reports every plan bucket but only when explicitly refreshed, while response
+ * headers report only the window(s) touched by the request just served — but do
+ * so continuously. A plain overwrite in either direction loses real data, which
+ * is why a header capture used to erase the model-scoped windows a `/limits`
+ * refresh had just fetched.
+ */
+export declare function mergeQuotaWindows(existing: AccountQuotaWindow[] | undefined, incoming: AccountQuotaWindow[] | undefined): AccountQuotaWindow[] | undefined;
+/**
+ * Fold a freshly observed snapshot onto the previous one for the same account,
+ * preserving dynamic windows the new snapshot does not carry.
+ */
+export declare function mergeQuotaSnapshot(previous: AccountQuota | undefined, incoming: AccountQuota): AccountQuota;
 /**
  * Initialise the quota module with a custom file path.
  * When set, all reads/writes go to this path instead of the default