@juspay/neurolink 11.2.0 → 11.2.2

package/dist/proxy/codexAccountUsage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Codex account enumeration + usage/quota normalisation.
+ *
+ * Mirrors `accountUsage.ts` (Anthropic) for the Codex pool. Codex reports two
+ * rate-limit windows — `primary` (short) and `secondary` (weekly) — which we
+ * map onto the shared AccountQuota session/weekly fields so the same routing,
+ * cooldown, and display code works for both providers.
+ */
+import type { AccountQuota, CodexRateLimits, CodexUsageFetchResult, ProxyPassthroughAccount } from "../types/index.js";
+export declare const CODEX_ACCOUNT_PREFIX = "codex:";
+/** Enumerate Codex OAuth accounts from the token store for usage refresh. */
+export declare function listCodexAccountsForUsage(): Promise<ProxyPassthroughAccount[]>;
+/** Normalise a Codex rate-limit block into the shared AccountQuota shape. */
+export declare function codexRateLimitsToQuota(rateLimits: CodexRateLimits | null | undefined, now?: number): AccountQuota;
+/**
+ * Parse Codex rate-limit information from response headers. The ChatGPT backend
+ * returns a JSON rate-limit blob in `x-codex-ratelimit` / `x-codex-active-limit`
+ * on some responses; parse defensively and return null when absent.
+ */
+export declare function parseCodexRateLimitHeaders(headers: Headers, now?: number): AccountQuota | null;
+/** Fetch the usage/limits window for one Codex account. */
+export declare function fetchCodexAccountUsage(account: ProxyPassthroughAccount, options?: {
+    timeoutMs?: number;
+}): Promise<CodexUsageFetchResult>;
+/** Decode plan type from an account's access token (display convenience). */
+export declare function codexAccountPlanType(account: ProxyPassthroughAccount): string | undefined;

package/dist/proxy/codexAccountUsage.js

@@ -0,0 +1,173 @@
+/**
+ * Codex account enumeration + usage/quota normalisation.
+ *
+ * Mirrors `accountUsage.ts` (Anthropic) for the Codex pool. Codex reports two
+ * rate-limit windows — `primary` (short) and `secondary` (weekly) — which we
+ * map onto the shared AccountQuota session/weekly fields so the same routing,
+ * cooldown, and display code works for both providers.
+ */
+import { tokenStore } from "../auth/tokenStore.js";
+import { CODEX_ORIGINATOR, CODEX_USAGE_URL, CODEX_USER_AGENT, decodeCodexAccessToken, resolveCodexAccountId, } from "../auth/codexOAuth.js";
+import { logger } from "../utils/logger.js";
+export const CODEX_ACCOUNT_PREFIX = "codex:";
+/** Enumerate Codex OAuth accounts from the token store for usage refresh. */
+export async function listCodexAccountsForUsage() {
+    const keys = await tokenStore.listByPrefix(CODEX_ACCOUNT_PREFIX);
+    const accounts = [];
+    for (const key of keys) {
+        if (await tokenStore.isDisabled(key)) {
+            continue;
+        }
+        const tokens = await tokenStore.loadTokens(key);
+        if (!tokens) {
+            continue;
+        }
+        const label = key.slice(CODEX_ACCOUNT_PREFIX.length) || key;
+        accounts.push({
+            key,
+            label,
+            token: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt,
+            type: tokens.tokenType === "Bearer" ? "oauth" : "api_key",
+        });
+    }
+    return accounts;
+}
+function toFraction(percent) {
+    if (typeof percent !== "number" || !Number.isFinite(percent)) {
+        return 0;
+    }
+    // Codex reports 0-100; clamp and normalise to 0-1.
+    return Math.min(1, Math.max(0, percent / 100));
+}
+function windowResetEpochSeconds(window, nowSeconds) {
+    if (!window) {
+        return 0;
+    }
+    if (typeof window.resets_at === "number" &&
+        Number.isFinite(window.resets_at) &&
+        window.resets_at > 0) {
+        // Tolerate ms epochs (~year 2100 ceiling in seconds).
+        return window.resets_at > 4_102_444_800
+            ? Math.floor(window.resets_at / 1000)
+            : window.resets_at;
+    }
+    const relative = typeof window.resets_in_seconds === "number"
+        ? window.resets_in_seconds
+        : window.reset_after;
+    if (typeof relative === "number" &&
+        Number.isFinite(relative) &&
+        relative > 0) {
+        return nowSeconds + Math.floor(relative);
+    }
+    return 0;
+}
+function deriveWindowStatus(usedFraction) {
+    return usedFraction >= 1 ? "rejected" : "allowed";
+}
+function toQuotaWindow(kind, group, window, nowSeconds) {
+    if (!window) {
+        return null;
+    }
+    const used = toFraction(window.used_percent);
+    return {
+        kind,
+        group,
+        used,
+        status: deriveWindowStatus(used),
+        resetsAt: windowResetEpochSeconds(window, nowSeconds),
+        isActive: true,
+    };
+}
+/** Normalise a Codex rate-limit block into the shared AccountQuota shape. */
+export function codexRateLimitsToQuota(rateLimits, now = Date.now()) {
+    const nowSeconds = Math.floor(now / 1000);
+    const primary = rateLimits?.primary ?? null;
+    const secondary = rateLimits?.secondary ?? null;
+    const sessionUsed = toFraction(primary?.used_percent);
+    const weeklyUsed = toFraction(secondary?.used_percent);
+    const windows = [];
+    const primaryWindow = toQuotaWindow("session", "session", primary, nowSeconds);
+    const secondaryWindow = toQuotaWindow("weekly_all", "weekly", secondary, nowSeconds);
+    if (primaryWindow) {
+        windows.push(primaryWindow);
+    }
+    if (secondaryWindow) {
+        windows.push(secondaryWindow);
+    }
+    return {
+        sessionUsed,
+        sessionStatus: deriveWindowStatus(sessionUsed),
+        sessionResetAt: windowResetEpochSeconds(primary, nowSeconds),
+        weeklyUsed,
+        weeklyStatus: deriveWindowStatus(weeklyUsed),
+        weeklyResetAt: windowResetEpochSeconds(secondary, nowSeconds),
+        // Codex has no overage/fallback concept; keep neutral defaults.
+        fallbackPercentage: 0,
+        overageStatus: "rejected",
+        lastUpdated: now,
+        windows: windows.length > 0 ? windows : undefined,
+        windowsUpdatedAt: windows.length > 0 ? now : undefined,
+        source: "usage-api",
+    };
+}
+/**
+ * Parse Codex rate-limit information from response headers. The ChatGPT backend
+ * returns a JSON rate-limit blob in `x-codex-ratelimit` / `x-codex-active-limit`
+ * on some responses; parse defensively and return null when absent.
+ */
+export function parseCodexRateLimitHeaders(headers, now = Date.now()) {
+    const raw = headers.get("x-codex-ratelimit") ??
+        headers.get("x-codex-active-limit") ??
+        null;
+    if (!raw) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const rateLimits = "rate_limits" in parsed && parsed.rate_limits
+            ? parsed.rate_limits
+            : parsed;
+        return codexRateLimitsToQuota(rateLimits, now);
+    }
+    catch {
+        return null;
+    }
+}
+/** Fetch the usage/limits window for one Codex account. */
+export async function fetchCodexAccountUsage(account, options = {}) {
+    if (account.type !== "oauth") {
+        return { ok: false, reason: "not_oauth" };
+    }
+    const accountId = resolveCodexAccountId(account.token);
+    try {
+        const response = await fetch(CODEX_USAGE_URL, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${account.token}`,
+                ...(accountId ? { "chatgpt-account-id": accountId } : {}),
+                originator: CODEX_ORIGINATOR,
+                "User-Agent": CODEX_USER_AGENT,
+                Accept: "application/json",
+            },
+            signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+        });
+        if (response.status === 401 || response.status === 403) {
+            return { ok: false, reason: "auth" };
+        }
+        if (!response.ok) {
+            return { ok: false, reason: "http" };
+        }
+        const usage = (await response.json());
+        return { ok: true, quota: codexRateLimitsToQuota(usage.rate_limits) };
+    }
+    catch (error) {
+        logger.debug(`Codex usage fetch failed for ${account.label}: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false, reason: "network" };
+    }
+}
+/** Decode plan type from an account's access token (display convenience). */
+export function codexAccountPlanType(account) {
+    return decodeCodexAccessToken(account.token).planType;
+}

package/dist/proxy/proxyAnalysis.js

@@ -100,7 +100,13 @@ function routingCandidateValue(value) {
         "sessionStatus",
         "weeklyStatus",
     ];
-    const optionalNullableStringFields = ["fallbackStatus", "upgradePaths"];
+    const optionalNullableStringFields = [
+        "fallbackStatus",
+        "upgradePaths",
+        "scopedModel",
+        "scopedStatus",
+    ];
+    const optionalNullableNumberFields = ["scopedUsed", "scopedResetAt"];
     if (!stringValue(candidate.account) ||
         typeof candidate.accountType !== "string" ||
         !ROUTING_ACCOUNT_TYPES.has(candidate.accountType) ||
@@ -139,6 +145,7 @@ function routingCandidateValue(value) {
             "lastRefreshAttemptAt",
             "lastRefreshSuccessAt",
             "nextRefreshEligibleAt",
+            ...optionalNullableNumberFields,
         ].some((field) => field in candidate &&
             candidate[field] !== undefined &&
             !isNullableFiniteNumber(candidate[field])) ||
@@ -192,6 +199,10 @@ function routingCandidateValue(value) {
         weeklyStatus: candidate.weeklyStatus,
         weeklyUsed: candidate.weeklyUsed,
         weeklyResetAt: candidate.weeklyResetAt,
+        scopedModel: candidate.scopedModel,
+        scopedStatus: candidate.scopedStatus,
+        scopedUsed: candidate.scopedUsed,
+        scopedResetAt: candidate.scopedResetAt,
     };
 }
 function routingDecisionValue(value) {

package/dist/proxy/proxyConfig.js

@@ -238,6 +238,16 @@ export function validateProxyConfig(config) {
             normalizedQuotaRouting !== "false") {
             errors.push("routing.quota-routing must be a boolean");
         }
+        // Without this a typo (`use-overage: nevr`) loads cleanly and silently
+        // falls back to "auto" — the operator asked to block paid extra usage and
+        // gets provider-driven overage instead.
+        const rawUseOverage = routing["use-overage"] ?? routing.useOverage;
+        if (rawUseOverage !== undefined &&
+            !["auto", "always", "never"].includes(typeof rawUseOverage === "string"
+                ? rawUseOverage.trim().toLowerCase()
+                : "")) {
+            errors.push("routing.use-overage must be auto, always, or never");
+        }
         const rawAutoFallback = routing["auto-fallback"] ?? routing.autoFallback;
         const normalizedAutoFallback = typeof rawAutoFallback === "string"
             ? rawAutoFallback.trim().toLowerCase()
@@ -417,6 +427,20 @@ function parseRoutingConfig(raw) {
             logger.warn(`[proxy-config] Ignoring routing.quotaRouting: expected boolean, got ${typeof rawQuotaRouting}`);
         }
     }
+    const rawUseOverage = raw["use-overage"] ?? raw.useOverage;
+    if (rawUseOverage !== undefined) {
+        const normalized = typeof rawUseOverage === "string"
+            ? rawUseOverage.trim().toLowerCase()
+            : "";
+        if (normalized === "auto" ||
+            normalized === "always" ||
+            normalized === "never") {
+            result.useOverage = normalized;
+        }
+        else {
+            logger.warn(`[proxy-config] Ignoring routing.useOverage: expected auto|always|never, got ${String(rawUseOverage)}`);
+        }
+    }
     const rawAutoFallback = raw["auto-fallback"] ?? raw.autoFallback;
     if (rawAutoFallback !== undefined) {
         if (typeof rawAutoFallback === "boolean") {

package/dist/proxy/routingEvidence.d.ts

@@ -1,6 +1,17 @@
 /** Schema-v1 routing evidence values shared by emitters and offline readers. */
 export declare const PROXY_ACCOUNT_ROUTING_STRATEGIES: readonly ["round-robin", "fill-first"];
 export declare const PROXY_ACCOUNT_ROUTING_MODES: readonly ["quota", "primary", "round_robin", "single_account"];
-export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "session_reset", "weekly_reset", "weekly_utilization"];
+export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "scoped_headroom", "session_reset", "weekly_reset", "weekly_utilization", "scoped_utilization"];
 export declare const PROXY_ACCOUNT_TYPES: readonly ["oauth", "api_key"];
 export declare const ACCOUNT_COOLING_REASONS: readonly ["weekly", "session", "unified", "transient", "auth"];
+/**
+ * Longest a cooldown may last for each reason, measured from when it was set.
+ *
+ * A reason names a specific provider window, so it also bounds the wait: a
+ * "session" cooldown describes a 5-hour window and can never legitimately run
+ * for days. Without a per-reason ceiling a single bogus reset timestamp parks an
+ * account for as long as the global 8-day clamp allows — observed in the wild as
+ * a 206-hour "session" cooldown. Values carry slack so a genuine window that
+ * resets slightly late is not cut short.
+ */
+export declare const MAX_COOLDOWN_MS_BY_REASON: Record<string, number>;

package/dist/proxy/routingEvidence.js

@@ -21,9 +21,11 @@ export const PROXY_ACCOUNT_ROUTING_REASONS = [
     // decisions must never select a production request for quota discovery.
     "quota_probe",
     "session_headroom",
+    "scoped_headroom",
     "session_reset",
     "weekly_reset",
     "weekly_utilization",
+    "scoped_utilization",
 ];
 export const PROXY_ACCOUNT_TYPES = ["oauth", "api_key"];
 export const ACCOUNT_COOLING_REASONS = [
@@ -33,3 +35,24 @@ export const ACCOUNT_COOLING_REASONS = [
     "transient",
     "auth",
 ];
+/**
+ * Longest a cooldown may last for each reason, measured from when it was set.
+ *
+ * A reason names a specific provider window, so it also bounds the wait: a
+ * "session" cooldown describes a 5-hour window and can never legitimately run
+ * for days. Without a per-reason ceiling a single bogus reset timestamp parks an
+ * account for as long as the global 8-day clamp allows — observed in the wild as
+ * a 206-hour "session" cooldown. Values carry slack so a genuine window that
+ * resets slightly late is not cut short.
+ */
+export const MAX_COOLDOWN_MS_BY_REASON = {
+    session: 5 * 60 * 60 * 1000 + 15 * 60 * 1000,
+    weekly: 7 * 24 * 60 * 60 * 1000 + 12 * 60 * 60 * 1000,
+    // No named window bounds this one: it fires when the 5h/7d statuses still read
+    // "allowed" and the provider's own Retry-After is the only signal. Generous on
+    // purpose — truncating a provider-directed wait just re-hammers the account on
+    // a shorter cycle — while still refusing an absurd multi-day park.
+    unified: 12 * 60 * 60 * 1000,
+    transient: 15 * 60 * 1000,
+    auth: 5 * 60 * 1000,
+};

package/dist/proxy/runtimeConfig.js

@@ -228,6 +228,7 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         : "[missing]")
         .digest("hex")
         .slice(0, 16);
+    const useOverage = routing?.useOverage ?? "auto";
     const fingerprintSource = JSON.stringify({
         strategy,
         passthrough: options.passthrough,
@@ -237,6 +238,7 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         quotaRoutingEnabled,
         sessionSoftLimit,
         sessionResetToleranceMs,
+        useOverage,
     });
     const configHash = createHash("sha256")
         .update(fingerprintSource)
@@ -256,6 +258,7 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
             quotaRoutingEnabled,
             sessionSoftLimit,
             sessionResetToleranceMs,
+            useOverage,
         }),
         configFilePresent,
         envFilePresent,

package/dist/server/routes/claudeProxyRoutes.d.ts

@@ -12,7 +12,7 @@
 import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import { ProxyTracer } from "../../proxy/proxyTracer.js";
 import { isPermanentRefreshFailure } from "../../proxy/tokenRefresh.js";
-import type { AccountAllowlist, AccountAdmissionLease, AccountCooldownPlan, AccountQuota, AccountUsageFetchResult, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyLimitsRefreshResponse, ProxyQuotaCooldownUpdate, ProxyPassthroughAccount, QueuedAccountAdmission, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
+import type { AccountAllowlist, AccountAdmissionLease, AccountCooldownPlan, AccountQuota, AccountQuotaWindow, AccountUsageFetchResult, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicEntitlementFailure, AnthropicLoopState, AnthropicScopedExhaustion, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyLimitsRefreshResponse, ProxyQuotaCooldownUpdate, ProxyOveragePolicy, ProxyPassthroughAccount, QueuedAccountAdmission, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
 declare function tryAcquireAccountAdmission(accountKey: string, capacity: number | undefined): AccountAdmissionLease | undefined;
 declare function enqueueAccountAdmission(accountKey: string, capacity: number): QueuedAccountAdmission;
 declare function acquireAccountAdmission(accountKey: string, capacity: number, abortSignal?: AbortSignal, timeoutMs?: number): Promise<AccountAdmissionLease | undefined>;
@@ -54,7 +54,7 @@ declare function resetEpochToMs(resetEpoch: number | undefined, now: number): nu
  * burst / acceleration limit) is transient: honor retry-after as a floor,
  * allow a couple of jittered same-account retries, then a short cooldown.
  */
-declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number, unifiedStatus?: string | undefined): AccountCooldownPlan;
+declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number, unifiedStatus?: string | undefined, policy?: ProxyOveragePolicy): AccountCooldownPlan;
 /**
  * Proactively cool an account when a SUCCESS response reveals a window has just
  * flipped to "rejected" (the boundary request that spends the last of the quota
@@ -62,7 +62,7 @@ declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: nu
  * its reset so the next request skips it instead of discovering the limit via a
  * 429, except when the provider explicitly enables paid overage.
  */
-declare function reconcileCooldownFromQuota(state: RuntimeAccountState, quota: AccountQuota, now: number): ProxyQuotaCooldownUpdate;
+declare function reconcileCooldownFromQuota(state: RuntimeAccountState, quota: AccountQuota, now: number, policy?: ProxyOveragePolicy): ProxyQuotaCooldownUpdate;
 /**
  * Seed each account's runtime quota from the persisted snapshots in
  * ~/.neurolink/account-quotas.json (keyed by label). Runtime state is
@@ -88,6 +88,47 @@ declare function refreshAccountLimits(options?: {
     accountFilter?: string;
     snapshotOnly?: boolean;
 }): Promise<ProxyLimitsRefreshResponse>;
+/**
+ * Publish the operator's extra-usage policy for paths that cannot receive it
+ * explicitly. Callers that make a routing or cooldown decision take it as a
+ * parameter instead — see {@link isOverageUsable} — so a concurrent request or
+ * a hot config reload cannot change the answer mid-flight.
+ *
+ * `undefined` means "no runtime config on this path", which is not a request to
+ * clear an operator's setting, so the current value is kept.
+ */
+declare function setOveragePolicy(policy: ProxyOveragePolicy | undefined): void;
+/**
+ * Find the model-scoped quota window that applies to the requested model.
+ *
+ * Two sources describe the same cap differently: response headers carry the wire
+ * id of the model just served, while the usage API reports a DISPLAY name
+ * ("Fable", "Claude Opus 4.6"). So an exact wire-id match is tried first and
+ * display-name containment over alphanumeric-normalized forms is the fallback.
+ * Among equally specific matches the freshest observation wins, which favours
+ * the continuously-updated header window over a manually-refreshed one.
+ *
+ * Returns null whenever the account reports no applicable, still-fresh scoped
+ * cap — the common case.
+ */
+declare function matchScopedQuotaWindow(quota: AccountQuota | undefined, requestedModel: string | undefined, now?: number): AccountQuotaWindow | null;
+/**
+ * Split a candidate set by whether each account can still serve the requested
+ * model under its model-scoped cap.
+ *
+ * An account is scoped out only on evidence strong enough to act on: a fresh
+ * window, a reset that is actually ticking, a rejected/spent reading, and no
+ * paid extra usage to absorb the overflow. Anything weaker leaves the account
+ * eligible — a stale or mis-parsed window must never be able to empty the pool.
+ *
+ * `exhaustion` is populated only when every candidate is scoped out AND the
+ * evidence is trustworthy, which is what lets the caller report "switch model"
+ * instead of a generic rate limit.
+ */
+declare function evaluateScopedExhaustion(accounts: ProxyPassthroughAccount[], requestedModel: string | undefined, now?: number, policy?: ProxyOveragePolicy): {
+    eligible: ProxyPassthroughAccount[];
+    exhaustion: AnthropicScopedExhaustion | null;
+};
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
  * spend the overall weekly allowance that expires SOONEST first, so quota
@@ -112,7 +153,7 @@ declare function refreshAccountLimits(options?: {
  * Cooling/rejected accounts sort last, soonest-back-to-service first, as
  * last resort.
  */
-declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number): ProxyPassthroughAccount[];
+declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number, requestedModel?: string): ProxyPassthroughAccount[];
 declare function scheduleAdaptiveQuotaRefreshes(accounts: ProxyPassthroughAccount[], orderedAccounts: ProxyPassthroughAccount[], sessionSoftLimit: number, routingMetrics?: ReadonlyMap<string, ProxyAccountSortMetrics>): void;
 declare function scheduleHandoffQuotaRefresh(current: ProxyPassthroughAccount, candidate: ProxyPassthroughAccount | undefined, handoffEpoch: number, sessionSoftLimit: number): void;
 declare function buildRoutingDecision(args: {
@@ -158,6 +199,8 @@ declare function buildClaudeAnthropicFailureResponse(args: {
         body: string;
         contentType?: string;
     } | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
+    scopedExhaustion: AnthropicScopedExhaustion | null;
     sawNetworkError: boolean;
     sawTransientFailure: boolean;
     sawRateLimit: boolean;
@@ -231,6 +274,7 @@ declare function handleAnthropicAuthRetry(args: {
     }) => void;
     lastError: unknown;
     authFailureMessage: string | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
     sawRateLimit: boolean;
     sawTransientFailure: boolean;
     sawNetworkError: boolean;
@@ -270,6 +314,7 @@ declare function handleAnthropicNonOkResponse(args: {
         body: string;
         contentType?: string;
     } | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
 }): Promise<AnthropicNonOkResult>;
 /**
  * Detect Anthropic's anti-abuse / request-construction 429.
@@ -286,6 +331,7 @@ declare function fetchAnthropicAccountResponse(args: {
     url: string;
     headers: Record<string, string>;
     finalBodyStr: string;
+    requestedModel?: string;
     account: ProxyPassthroughAccount;
     accountState: RuntimeAccountState;
     enabledAccounts: ProxyPassthroughAccount[];
@@ -341,6 +387,29 @@ export declare function isInvalidRequestError(status: number, errBody: string):
  * rather than a terminal client-facing 400.
  */
 export declare function isSubscriptionBetaRejection(status: number, errBody: string): boolean;
+/**
+ * An entitlement rejection: Anthropic refuses THIS credential on organization
+ * or plan policy, e.g. `403 permission_error` /
+ * "OAuth authentication is currently not allowed for this organization."
+ *
+ * The taxonomy makes this safe to rotate on: `permission_error` is reserved for
+ * credential/organization permission, distinct from `invalid_request_error`
+ * (request shape) and `not_found_error`, both already terminal above. No
+ * `permission_error` is caused by the request body, so the identical request
+ * can succeed on a different account.
+ *
+ * Deliberately broad — rotation is cheap and reversible. Persisting the block
+ * is gated on the narrower {@link isDurableEntitlementBlock}.
+ */
+export declare function isAccountEntitlementError(status: number, errBody: string): boolean;
+/**
+ * Whether an entitlement rejection is specific enough to disable the account
+ * until someone re-enables it. Narrower than {@link isAccountEntitlementError}
+ * because disabling is sticky and user-visible: an unrecognised
+ * `permission_error` should rotate through the pool and surface a 403, never
+ * durably remove a credential on a guess.
+ */
+export declare function isDurableEntitlementBlock(status: number, errBody: string): boolean;
 /**
  * Backward-compatible alias — delegates to the shared translation engine.
  */
@@ -374,7 +443,7 @@ export declare const __testHooks: {
     scheduleAdaptiveQuotaRefreshes: typeof scheduleAdaptiveQuotaRefreshes;
     scheduleHandoffQuotaRefresh: typeof scheduleHandoffQuotaRefresh;
     getQuotaRefreshState: (key: string) => import("../../index.js").ProxyQuotaRefreshRuntimeState;
-    buildQuotaRoutingDecision: (accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number) => ProxyAccountRoutingDecision | undefined;
+    buildQuotaRoutingDecision: (accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number, requestedModel?: string) => ProxyAccountRoutingDecision | undefined;
     buildRoutingDecision: typeof buildRoutingDecision;
     resetEpochToMs: typeof resetEpochToMs;
     seedRuntimeQuotasFromDisk: typeof seedRuntimeQuotasFromDisk;
@@ -413,5 +482,10 @@ export declare const __testHooks: {
     shouldAttemptClaudeFallback: typeof shouldAttemptClaudeFallback;
     executeClaudeFallbackWithRetry: typeof executeClaudeFallbackWithRetry;
     buildClaudeAnthropicFailureResponse: typeof buildClaudeAnthropicFailureResponse;
+    isAccountEntitlementError: typeof isAccountEntitlementError;
+    isDurableEntitlementBlock: typeof isDurableEntitlementBlock;
+    evaluateScopedExhaustion: typeof evaluateScopedExhaustion;
+    matchScopedQuotaWindow: typeof matchScopedQuotaWindow;
+    setOveragePolicy: typeof setOveragePolicy;
 };
 export {};