@cortexkit/anthropic-auth-core 1.4.0 → 1.5.0

package/dist/accounts.d.ts

@@ -53,8 +53,13 @@ export type AccountStorage = {
     quota?: {
         enabled?: boolean;
         checkIntervalMinutes?: number;
+        refreshEveryNRequests?: number;
         minimumRemaining?: Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
         failClosedOnUnknownQuota?: boolean;
+        mainQuota?: OAuthQuotaSnapshot;
+        mainQuotaCheckedAt?: number;
+        mainQuotaToken?: string;
+        mainLastQuotaApiError?: AccountOperationError;
     };
     claudeCache?: {
         enabled?: boolean;
@@ -85,6 +90,7 @@ export type AccountManagerOptions = {
     now?: () => number;
     fetchImpl?: typeof fetch;
     configPath?: string;
+    quotaManager?: import('./quota-manager.ts').QuotaManager;
 };
 export type AccountRefreshError = {
     accountId: string;
@@ -124,7 +130,24 @@ export declare function buildRefreshOperationError(input: {
 }): AccountOperationError;
 export declare function refreshBackoffActive(error: AccountOperationError | undefined, refreshToken: string | undefined, now: number): boolean;
 export declare function formatRefreshBackoffMessage(error: AccountOperationError, now: number): string;
+export declare function buildQuotaOperationError(input: {
+    error: unknown;
+    now: number;
+    previous?: AccountOperationError;
+}): AccountOperationError;
+export declare function quotaBackoffActive(error: AccountOperationError | undefined, now: number): boolean;
+export declare function formatQuotaBackoffMessage(error: AccountOperationError, now: number): string;
 export declare function getQuotaCheckIntervalMs(storage: AccountStorage | null): number;
+export declare function getPersistedMainQuota(storage: AccountStorage | null): {
+    quota: OAuthQuotaSnapshot;
+    checkedAt: number;
+    tokenFingerprint?: string;
+} | null;
+/**
+ * How often (in requests) to force a quota refresh, independent of the timer.
+ * Returns 0 when disabled (default).
+ */
+export declare function getQuotaRefreshEveryNRequests(storage: AccountStorage | null): number;
 export declare function quotaSnapshotPassesPolicy(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null): boolean;
 export declare function getQuotaNextRefreshAt(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null, now: number): number;
 export declare function fetchOAuthQuotaSnapshot(input: {
@@ -142,7 +165,13 @@ export declare class FallbackAccountManager {
     private readonly refreshPromises;
     private refreshTimer;
     private quotaTimer;
+    readonly quotaManager: import('./quota-manager.ts').QuotaManager | null;
     constructor(options?: AccountManagerOptions);
+    /**
+     * Seed QuotaManager from persisted account.quota if no cache entry exists
+     * yet. Prevents unnecessary API calls when the on-disk snapshot is fresh.
+     */
+    private seedFallbackQuota;
     load(): Promise<AccountStorage | null>;
     save(storage: AccountStorage): Promise<void>;
     startBackgroundRefresh(): void;
@@ -150,9 +179,18 @@ export declare class FallbackAccountManager {
     getUsableFallbackAccounts(existingStorage?: AccountStorage | null): Promise<OAuthAccount[]>;
     markUsed(account: OAuthAccount): Promise<void>;
     accountPassesQuotaPolicy(account: OAuthAccount, storage: AccountStorage | null): boolean;
+    /**
+     * Return the account with its quota overlaid from the unified QuotaManager
+     * cache (token-bound) when available, so quota-policy decisions use the same
+     * source of truth as the staleness check. Falls back to the stored
+     * account.quota when no manager is wired or the cache has no entry.
+     */
+    private quotaPolicyAccount;
     refreshDueAccounts(): Promise<void>;
     refreshQuotaForDueAccounts(): Promise<void>;
-    refreshQuotaForAllAccounts(): Promise<{
+    refreshQuotaForAllAccounts(options?: {
+        force?: boolean;
+    }): Promise<{
         storage: AccountStorage | null;
         errors: AccountRefreshError[];
     }>;

package/dist/accounts.js

@@ -16,6 +16,9 @@ const DEFAULT_REFRESH_INTERVAL_MINUTES = 10;
 const MIN_REFRESH_RETRY_DELAY_MS = 5 * 60_000;
 const MAX_REFRESH_RETRY_DELAY_MS = 60 * 60_000;
 const NON_TRANSIENT_REFRESH_RETRY_DELAY_MS = 24 * 60 * 60_000;
+const MIN_QUOTA_RETRY_DELAY_MS = 60_000;
+const MAX_QUOTA_RETRY_DELAY_MS = 15 * 60_000;
+const NON_TRANSIENT_QUOTA_RETRY_DELAY_MS = 5 * 60_000;
 const DEFAULT_QUOTA_CHECK_INTERVAL_MINUTES = 5;
 const DEFAULT_MINIMUM_REMAINING = {
     five_hour: 0,
@@ -452,10 +455,51 @@ export function formatRefreshBackoffMessage(error, now) {
     const seconds = Math.max(1, Math.ceil(((error.nextRetryAt ?? now) - now) / 1000));
     return `Claude OAuth refresh is backed off for ${seconds}s after: ${error.message}`;
 }
+export function buildQuotaOperationError(input) {
+    const previousRetryCount = input.previous?.retryCount ?? 0;
+    const retryCount = previousRetryCount + 1;
+    const delay = isTransientQuotaError(input.error)
+        ? Math.min(MAX_QUOTA_RETRY_DELAY_MS, MIN_QUOTA_RETRY_DELAY_MS * 2 ** Math.min(retryCount - 1, 6))
+        : NON_TRANSIENT_QUOTA_RETRY_DELAY_MS;
+    return {
+        message: formatErrorMessage(input.error),
+        checkedAt: input.now,
+        nextRetryAt: input.now + delay,
+        retryCount,
+    };
+}
+export function quotaBackoffActive(error, now) {
+    if (!error?.nextRetryAt || error.nextRetryAt <= now)
+        return false;
+    return true;
+}
+export function formatQuotaBackoffMessage(error, now) {
+    const seconds = Math.max(1, Math.ceil(((error.nextRetryAt ?? now) - now) / 1000));
+    return `Quota API backed off for ${seconds}s after: ${error.message}`;
+}
 export function getQuotaCheckIntervalMs(storage) {
     const minutes = storage?.quota?.checkIntervalMinutes ?? DEFAULT_QUOTA_CHECK_INTERVAL_MINUTES;
     return Math.max(1, minutes) * 60_000;
 }
+export function getPersistedMainQuota(storage) {
+    if (!storage?.quota?.mainQuota || !storage.quota.mainQuotaCheckedAt)
+        return null;
+    return {
+        quota: storage.quota.mainQuota,
+        checkedAt: storage.quota.mainQuotaCheckedAt,
+        tokenFingerprint: storage.quota.mainQuotaToken,
+    };
+}
+/**
+ * How often (in requests) to force a quota refresh, independent of the timer.
+ * Returns 0 when disabled (default).
+ */
+export function getQuotaRefreshEveryNRequests(storage) {
+    const n = storage?.quota?.refreshEveryNRequests;
+    return typeof n === 'number' && Number.isFinite(n) && n > 0
+        ? Math.floor(n)
+        : 0;
+}
 function failClosedOnUnknownQuota(storage) {
     return (storage?.quota?.failClosedOnUnknownQuota ??
         DEFAULT_FAIL_CLOSED_ON_UNKNOWN_QUOTA);
@@ -597,10 +641,11 @@ function recordRefreshError(account, error, now) {
     });
 }
 function recordQuotaRefreshError(account, error, now) {
-    account.lastQuotaRefreshError = {
-        message: formatErrorMessage(error),
-        checkedAt: now,
-    };
+    account.lastQuotaRefreshError = buildQuotaOperationError({
+        error,
+        now,
+        previous: account.lastQuotaRefreshError,
+    });
     if (error instanceof ClaudeOAuthRefreshError) {
         recordRefreshError(account, error, now);
     }
@@ -618,10 +663,33 @@ export class FallbackAccountManager {
     refreshPromises = new Map();
     refreshTimer = null;
     quotaTimer = null;
+    quotaManager;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
         this.fetchImpl = options.fetchImpl ?? fetch;
         this.configPath = options.configPath ?? getAccountStoragePath();
+        this.quotaManager = options.quotaManager ?? null;
+    }
+    /**
+     * Seed QuotaManager from persisted account.quota if no cache entry exists
+     * yet. Prevents unnecessary API calls when the on-disk snapshot is fresh.
+     */
+    seedFallbackQuota(account, storage) {
+        if (!this.quotaManager)
+            return;
+        if (this.quotaManager.getFallback(account.id, account.access))
+            return;
+        if (!account.quota)
+            return;
+        const checkedAt = Math.max(account.quota.five_hour?.checkedAt ?? 0, account.quota.seven_day?.checkedAt ?? 0);
+        if (checkedAt <= 0)
+            return;
+        const checkInterval = getQuotaCheckIntervalMs(storage);
+        this.quotaManager.setFallback(account.id, {
+            quota: account.quota,
+            refreshAfter: checkedAt + checkInterval,
+            checkedAt,
+        }, account.access);
     }
     async load() {
         return loadAccounts(this.configPath);
@@ -671,11 +739,23 @@ export class FallbackAccountManager {
                     next = await this.refreshAccount(next, storage);
                     changed = true;
                 }
-                if (quotaIsStale(next, storage, this.now())) {
+                this.seedFallbackQuota(next, storage);
+                const stale = this.quotaManager
+                    ? this.quotaManager.isFallbackStale(next.id, next.access)
+                    : quotaIsStale(next, storage, this.now());
+                // Skip the request-time refresh when this account's quota API is
+                // backed off (recent 429/5xx). Hitting it again would extend the
+                // backoff; evaluate policy on the cached/seeded quota instead. Mirrors
+                // the background refreshQuotaForDueAccounts() guard.
+                if (stale &&
+                    !quotaBackoffActive(next.lastQuotaRefreshError, this.now())) {
                     next = await this.refreshAccountQuota(next, storage);
                     changed = true;
                 }
-                if (this.accountPassesQuotaPolicy(next, storage))
+                // Single source of truth: evaluate quota policy from the unified
+                // QuotaManager cache (the same source as the staleness check above) so
+                // an active-route refresh that updated only the cache is not ignored.
+                if (this.accountPassesQuotaPolicy(this.quotaPolicyAccount(next), storage))
                     usable.push(next);
             }
             catch (error) {
@@ -708,6 +788,18 @@ export class FallbackAccountManager {
     accountPassesQuotaPolicy(account, storage) {
         return quotaSnapshotPassesPolicy(account.quota, storage);
     }
+    /**
+     * Return the account with its quota overlaid from the unified QuotaManager
+     * cache (token-bound) when available, so quota-policy decisions use the same
+     * source of truth as the staleness check. Falls back to the stored
+     * account.quota when no manager is wired or the cache has no entry.
+     */
+    quotaPolicyAccount(account) {
+        if (!this.quotaManager)
+            return account;
+        const cached = this.quotaManager.getFallback(account.id, account.access)?.quota;
+        return cached ? { ...account, quota: cached } : account;
+    }
     async refreshDueAccounts() {
         const storage = await this.load();
         if (!storage || !refreshEnabled(storage))
@@ -719,11 +811,11 @@ export class FallbackAccountManager {
             if (!tokenNeedsRefresh(account, storage, this.now()))
                 continue;
             if (refreshBackoffActive(account.lastRefreshError, account.refresh, this.now())) {
-                log('[refresh] fallback oauth skipped backoff', {
-                    accountId: account.id,
-                    nextRetryAt: account.lastRefreshError?.nextRetryAt,
-                    retryCount: account.lastRefreshError?.retryCount,
-                });
+                // Backoff skips are steady-state while a fallback account is waiting for
+                // its next retry. Logging every background tick from every OpenCode
+                // process creates noise without adding new diagnostic signal; the
+                // failure/backoff itself is recorded when the refresh attempt fails and
+                // shown by /claude-quota.
                 continue;
             }
             try {
@@ -767,7 +859,16 @@ export class FallbackAccountManager {
                     next = await this.refreshAccount(next, storage);
                     changed = true;
                 }
-                if (!quotaIsStale(next, storage, this.now()))
+                if (quotaBackoffActive(next.lastQuotaRefreshError, this.now())) {
+                    continue;
+                }
+                this.seedFallbackQuota(next, storage);
+                // Use QuotaManager staleness when available (shared cache);
+                // fall back to per-account on-disk staleness otherwise.
+                const stale = this.quotaManager
+                    ? this.quotaManager.isFallbackStale(next.id, next.access)
+                    : quotaIsStale(next, storage, this.now());
+                if (!stale)
                     continue;
                 await this.refreshAccountQuota(next, storage);
                 changed = true;
@@ -782,11 +883,12 @@ export class FallbackAccountManager {
         if (changed)
             await this.save(storage);
     }
-    async refreshQuotaForAllAccounts() {
+    async refreshQuotaForAllAccounts(options = {}) {
         const storage = await this.load();
         const errors = [];
         if (!storage || !quotaEnabled(storage))
             return { storage, errors };
+        const force = options.force ?? false;
         let changed = false;
         for (const account of storage.accounts) {
             if (account.enabled === false)
@@ -802,7 +904,10 @@ export class FallbackAccountManager {
                     next = await this.refreshAccount(next, storage);
                     changed = true;
                 }
-                if (!quotaIsStale(next, storage, this.now())) {
+                // force (manual /claude-quota) bypasses the staleness skip to fetch
+                // fresh numbers on demand. refreshAccountQuota still respects 429
+                // backoff via QuotaManager.refreshFallback.
+                if (!force && !quotaIsStale(next, storage, this.now())) {
                     if (next.lastQuotaRefreshError) {
                         next.lastQuotaRefreshError = undefined;
                         updateStoredAccount(storage, next);
@@ -948,12 +1053,18 @@ export class FallbackAccountManager {
         if (!target.access) {
             throw new Error(`Fallback account ${account.id} has no access token`);
         }
-        try {
-            target.quota = await fetchOAuthQuotaSnapshot({
-                accessToken: target.access,
+        // Unify on the shared QuotaManager when present: it adds inflight
+        // deduplication and 429 backoff gating around the same quota API. Fall back
+        // to a direct fetch only when no QuotaManager is wired (e.g. in isolation).
+        const fetchSnapshot = (accessToken) => this.quotaManager
+            ? this.quotaManager.refreshFallback(target.id, accessToken)
+            : fetchOAuthQuotaSnapshot({
+                accessToken,
                 fetchImpl: this.fetchImpl,
                 now: this.now,
             });
+        try {
+            target.quota = await fetchSnapshot(target.access);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -964,14 +1075,22 @@ export class FallbackAccountManager {
             });
             if (!target.access)
                 throw error;
-            target.quota = await fetchOAuthQuotaSnapshot({
-                accessToken: target.access,
-                fetchImpl: this.fetchImpl,
-                now: this.now,
-            });
+            // 401 does not arm QuotaManager backoff, so this retry proceeds.
+            target.quota = await fetchSnapshot(target.access);
         }
         target.lastQuotaRefreshError = undefined;
         updateStoredAccount(storage, target);
+        // Sync to shared QuotaManager so all consumers see the same cache. The
+        // refreshFallback path already cached the snapshot; re-set here so
+        // refreshAfter reflects this storage's check interval consistently.
+        if (this.quotaManager && target.quota) {
+            const now = this.now();
+            this.quotaManager.setFallback(target.id, {
+                quota: target.quota,
+                refreshAfter: now + getQuotaCheckIntervalMs(storage),
+                checkedAt: now,
+            }, target.access);
+        }
         return target;
     }
 }

package/dist/cachekeep.d.ts

@@ -73,6 +73,7 @@ export declare class CacheKeepManager {
         trackedSessions: number;
         nextPrewarmAt: number | undefined;
     };
+    trackedCount(): number;
     track(input: {
         sessionId?: string | null;
         url: string;

package/dist/cachekeep.js

@@ -205,6 +205,9 @@ export class CacheKeepManager {
             : undefined;
         return { trackedSessions: targets.length, nextPrewarmAt };
     }
+    trackedCount() {
+        return this.targets.size;
+    }
     track(input) {
         if (!input.sessionId)
             return { tracked: false, reason: 'missing session id' };

package/dist/constants.js

@@ -36,7 +36,9 @@ export const OPENCODE_IDENTITY_PREFIX = 'You are OpenCode';
 export const CLAUDE_CODE_IDENTITY = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
 export const PARALLEL_TOOL_CALLS_SYSTEM_PROMPT = [
     '<use_parallel_tool_calls>',
-    'For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.',
+    'For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling independent tools in parallel whenever possible. For example, when reading 3 known files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple independent read-only commands like `ls` or `list_dir`, run all of those commands in parallel. Err on the side of maximizing parallel tool calls for independent work rather than running too many tools sequentially.',
+    '',
+    'Do not parallelize tool calls when one call depends on the output of another call. If a tool call needs an ID, filename, search result, or any other value returned by a previous tool call, run the first call, wait for its result, then run the dependent call using the real returned value. Never invent placeholder IDs, guessed task IDs, or other guessed values for dependent tool calls just to place them in the same parallel block.',
     '</use_parallel_tool_calls>',
 ].join('\n');
 export const CCH_SALT = '59cf53e54c78';

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from './dump.ts';
 export * from './fast.ts';
 export * from './logger.ts';
 export * from './pkce.ts';
+export * from './quota-manager.ts';
 export * from './quotas.ts';
 export * from './relay.ts';
 export * from './routing.ts';

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./dump.js";
 export * from "./fast.js";
 export * from "./logger.js";
 export * from "./pkce.js";
+export * from "./quota-manager.js";
 export * from "./quotas.js";
 export * from "./relay.js";
 export * from "./routing.js";

package/dist/quota-manager.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Unified quota cache and API gateway.
+ *
+ * Single source of truth for main + fallback quota state. All consumers
+ * share one QuotaManager instance so they see the same in-memory cache.
+ * Handles deduplication, rate-limiting (429 backoff), and staleness.
+ */
+import type { AccountOperationError, AccountStorage, OAuthAccount, OAuthQuotaSnapshot } from './accounts.ts';
+/**
+ * Stable, non-reversible fingerprint of an access token. Used to detect a
+ * main-account switch so a different account's persisted/cached quota is never
+ * reused. Not a secret — a truncated SHA-256, safe to persist alongside quota.
+ */
+export declare function tokenFingerprint(token: string): string;
+export type QuotaEntry = {
+    quota: OAuthQuotaSnapshot;
+    refreshAfter: number;
+    checkedAt: number;
+};
+export type QuotaManagerOptions = {
+    storage: AccountStorage | null;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    onMainQuotaFetched?: (quota: OAuthQuotaSnapshot, checkedAt: number, tokenFingerprint: string) => void;
+    onApiError?: (error: AccountOperationError) => void;
+};
+export declare class QuotaManager {
+    private main;
+    private mainTokenFp;
+    private fallbacks;
+    private fallbackTokenFps;
+    private inflightMain;
+    private inflightFallbacks;
+    private mainLastApiError;
+    private fallbackApiErrors;
+    private fallbackErrorTokenFps;
+    private apiGate;
+    private lastApiCallAt;
+    private storage;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly onMainQuotaFetched;
+    private readonly onApiError;
+    constructor(opts: QuotaManagerOptions);
+    /**
+     * Cached main quota entry. Pass the live access token to enforce token
+     * binding: if the cached entry was produced by a different token (main
+     * account switched), it is dropped and null is returned so the caller
+     * refetches for the current account. Called without a token (e.g. for
+     * display) it returns whatever is cached.
+     */
+    getMain(accessToken?: string): QuotaEntry | null;
+    /**
+     * Cached fallback quota entry. Pass the live access token to enforce token
+     * binding: if the entry was produced by a different token (account re-login),
+     * it is dropped and null is returned so the caller refetches.
+     */
+    getFallback(accountId: string, accessToken?: string): QuotaEntry | null;
+    getAllFallbacks(): Map<string, QuotaEntry>;
+    setMain(accessToken: string, entry: QuotaEntry): void;
+    setFallback(accountId: string, entry: QuotaEntry, accessToken?: string): void;
+    refreshMain(accessToken: string): Promise<OAuthQuotaSnapshot>;
+    refreshFallback(accountId: string, accessToken: string): Promise<OAuthQuotaSnapshot>;
+    refreshAllFallbacks(accounts: OAuthAccount[]): Promise<void>;
+    /**
+     * Fire-and-forget refresh. Does not await, swallows errors.
+     */
+    refreshMainInBackground(accessToken: string): void;
+    isMainStale(): boolean;
+    isFallbackStale(accountId: string, accessToken?: string): boolean;
+    shouldRefreshOnRequestCount(requestCount: number): boolean;
+    /**
+     * Combined check: should a refresh happen right now?
+     * True if main is stale by time OR triggered by request count.
+     */
+    needsRefresh(requestCount: number): boolean;
+    updateStorage(storage: AccountStorage | null): void;
+    /**
+     * Seed fallback cache entries from persisted account.quota data.
+     * Only seeds accounts that don't already have a cache entry.
+     * Prevents unnecessary API calls when persisted quota is still fresh.
+     */
+    seedFallbacksFromAccounts(accounts: OAuthAccount[]): void;
+    /**
+     * Whether the MAIN quota API is currently in backoff. Scoped to the main
+     * account — a fallback account's 429 never reports here.
+     */
+    isBackedOff(): boolean;
+    /**
+     * Whether a specific fallback account's quota API is in backoff.
+     */
+    isFallbackBackedOff(accountId: string, accessToken?: string): boolean;
+    getLastApiError(): AccountOperationError | undefined;
+    /** Minimum gap between consecutive quota API calls (ms). */
+    private static readonly API_CALL_GAP_MS;
+    private static fallbackInflightKey;
+    /**
+     * Serialize API calls through a shared gate so only one
+     * quota API request runs at a time, with a minimum gap
+     * between calls. Prevents concurrent and rapid-fire calls
+     * from triggering Anthropic's rate limits.
+     */
+    private _enqueueApiFetch;
+    private _fetchMain;
+    private _fetchFallback;
+    private static isAuthError;
+    /** Main quota failure: arms main-only backoff and persists via onApiError. */
+    private _handleMainFetchError;
+    /**
+     * Fallback quota failure: arms backoff for THIS account only. Never touches
+     * main backoff state and never calls onApiError (which persists the main
+     * quota error) — the per-account error is recorded by the caller via the
+     * account's lastQuotaRefreshError.
+     */
+    private _handleFallbackFetchError;
+}

package/dist/quota-manager.js

@@ -0,0 +1,432 @@
+/**
+ * Unified quota cache and API gateway.
+ *
+ * Single source of truth for main + fallback quota state. All consumers
+ * share one QuotaManager instance so they see the same in-memory cache.
+ * Handles deduplication, rate-limiting (429 backoff), and staleness.
+ */
+import { createHash } from 'node:crypto';
+import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, quotaBackoffActive, } from "./accounts.js";
+// Capture real setTimeout before tests can mock globalThis.setTimeout
+const nativeSetTimeout = globalThis.setTimeout;
+/**
+ * Stable, non-reversible fingerprint of an access token. Used to detect a
+ * main-account switch so a different account's persisted/cached quota is never
+ * reused. Not a secret — a truncated SHA-256, safe to persist alongside quota.
+ */
+export function tokenFingerprint(token) {
+    return createHash('sha256').update(token).digest('hex').slice(0, 16);
+}
+// ---------------------------------------------------------------------------
+// Class
+// ---------------------------------------------------------------------------
+export class QuotaManager {
+    // --- State ---
+    main = null;
+    mainTokenFp = null;
+    fallbacks = new Map();
+    // Fingerprint of the access token that produced each fallback cache entry, so
+    // a re-login (credential change) for the same account id invalidates the
+    // stale entry instead of being treated as fresh.
+    fallbackTokenFps = new Map();
+    // --- Inflight deduplication ---
+    inflightMain = null;
+    inflightFallbacks = new Map();
+    // --- Rate-limiting (scoped per route so a fallback 429 never backs off the
+    // main account or vice versa) ---
+    mainLastApiError = undefined;
+    fallbackApiErrors = new Map();
+    fallbackErrorTokenFps = new Map();
+    // --- Serial API gate (prevents concurrent quota API calls) ---
+    apiGate = Promise.resolve();
+    lastApiCallAt = 0;
+    // --- Config ---
+    storage;
+    fetchImpl;
+    now;
+    onMainQuotaFetched;
+    onApiError;
+    constructor(opts) {
+        this.storage = opts.storage;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.now = opts.now ?? Date.now;
+        this.onMainQuotaFetched = opts.onMainQuotaFetched;
+        this.onApiError = opts.onApiError;
+        // Seed main quota from persisted storage, bound to the token fingerprint
+        // that produced it. refreshMain() drops this seed if the live token's
+        // fingerprint differs (main-account switch), preventing stale wrong-account
+        // quota from being served during backoff.
+        const persisted = getPersistedMainQuota(opts.storage);
+        if (persisted) {
+            this.main = {
+                quota: persisted.quota,
+                refreshAfter: getQuotaNextRefreshAt(persisted.quota, opts.storage, persisted.checkedAt),
+                checkedAt: persisted.checkedAt,
+            };
+            this.mainTokenFp = persisted.tokenFingerprint ?? null;
+        }
+        // Seed backoff state from persisted storage
+        const persistedError = opts.storage?.quota?.mainLastQuotaApiError;
+        if (persistedError && quotaBackoffActive(persistedError, this.now())) {
+            this.mainLastApiError = persistedError;
+        }
+    }
+    // =========================================================================
+    // Get (synchronous, from cache)
+    // =========================================================================
+    /**
+     * Cached main quota entry. Pass the live access token to enforce token
+     * binding: if the cached entry was produced by a different token (main
+     * account switched), it is dropped and null is returned so the caller
+     * refetches for the current account. Called without a token (e.g. for
+     * display) it returns whatever is cached.
+     */
+    getMain(accessToken) {
+        if (accessToken &&
+            this.main &&
+            this.mainTokenFp &&
+            this.mainTokenFp !== tokenFingerprint(accessToken)) {
+            this.main = null;
+            this.mainTokenFp = null;
+        }
+        return this.main;
+    }
+    /**
+     * Cached fallback quota entry. Pass the live access token to enforce token
+     * binding: if the entry was produced by a different token (account re-login),
+     * it is dropped and null is returned so the caller refetches.
+     */
+    getFallback(accountId, accessToken) {
+        const entry = this.fallbacks.get(accountId) ?? null;
+        if (!accessToken || !entry)
+            return entry;
+        const fp = this.fallbackTokenFps.get(accountId);
+        if (fp !== tokenFingerprint(accessToken)) {
+            this.fallbacks.delete(accountId);
+            this.fallbackTokenFps.delete(accountId);
+            return null;
+        }
+        return entry;
+    }
+    getAllFallbacks() {
+        return this.fallbacks;
+    }
+    // =========================================================================
+    // Set (manual inject — seeding from persisted account.quota on boot)
+    // =========================================================================
+    setMain(accessToken, entry) {
+        this.mainTokenFp = tokenFingerprint(accessToken);
+        this.main = entry;
+    }
+    setFallback(accountId, entry, accessToken) {
+        this.fallbacks.set(accountId, entry);
+        if (accessToken) {
+            this.fallbackTokenFps.set(accountId, tokenFingerprint(accessToken));
+        }
+        else {
+            this.fallbackTokenFps.delete(accountId);
+        }
+    }
+    // =========================================================================
+    // Refresh (async, deduplicated, rate-limited)
+    // =========================================================================
+    async refreshMain(accessToken) {
+        // If the main account/token changed, invalidate the cache (including a
+        // persisted seed) BEFORE the backoff short-circuit so a different account's
+        // stale quota is never returned while the quota API is backed off.
+        const fp = tokenFingerprint(accessToken);
+        if (this.mainTokenFp && this.mainTokenFp !== fp) {
+            this.main = null;
+            this.mainTokenFp = null;
+        }
+        // Deduplicate — return in-flight promise if already fetching
+        if (this.inflightMain)
+            return this.inflightMain;
+        // Rate-limit — if API recently 429'd, return stale or throw
+        if (this.isBackedOff()) {
+            if (this.main)
+                return this.main.quota;
+            throw new Error('Quota API rate-limited — try again later');
+        }
+        this.inflightMain = this._fetchMain(accessToken);
+        return this.inflightMain;
+    }
+    async refreshFallback(accountId, accessToken) {
+        // Deduplicate per account+token so a same-label re-login never joins a
+        // quota probe that was started with the previous credentials.
+        const inflightKey = QuotaManager.fallbackInflightKey(accountId, accessToken);
+        const inflight = this.inflightFallbacks.get(inflightKey);
+        if (inflight)
+            return inflight;
+        // Rate-limit — scoped to THIS fallback account only
+        if (this.isFallbackBackedOff(accountId, accessToken)) {
+            const cached = this.getFallback(accountId, accessToken);
+            if (cached)
+                return cached.quota;
+            throw new Error('Quota API rate-limited — try again later');
+        }
+        const promise = this._fetchFallback(accountId, accessToken);
+        this.inflightFallbacks.set(inflightKey, promise);
+        return promise;
+    }
+    async refreshAllFallbacks(accounts) {
+        const now = this.now();
+        for (const account of accounts) {
+            if (account.enabled === false)
+                continue;
+            if (!account.access)
+                continue;
+            const cached = this.getFallback(account.id, account.access);
+            if (cached && now < cached.refreshAfter)
+                continue;
+            try {
+                await this.refreshFallback(account.id, account.access);
+            }
+            catch {
+                // Best-effort — keep stale cache entry if fetch fails
+            }
+        }
+    }
+    /**
+     * Fire-and-forget refresh. Does not await, swallows errors.
+     */
+    refreshMainInBackground(accessToken) {
+        if (this.inflightMain)
+            return;
+        if (this.isBackedOff())
+            return;
+        void this.refreshMain(accessToken).catch(() => { });
+    }
+    // =========================================================================
+    // Staleness queries
+    // =========================================================================
+    isMainStale() {
+        if (!this.main)
+            return true;
+        return this.now() >= this.main.refreshAfter;
+    }
+    isFallbackStale(accountId, accessToken) {
+        // Token-aware: a credential change invalidates the entry (treated as stale).
+        const entry = this.getFallback(accountId, accessToken);
+        if (!entry)
+            return true;
+        return this.now() >= entry.refreshAfter;
+    }
+    shouldRefreshOnRequestCount(requestCount) {
+        const everyN = getQuotaRefreshEveryNRequests(this.storage);
+        if (everyN <= 0)
+            return false;
+        return requestCount > 0 && requestCount % everyN === 0;
+    }
+    /**
+     * Combined check: should a refresh happen right now?
+     * True if main is stale by time OR triggered by request count.
+     */
+    needsRefresh(requestCount) {
+        return this.isMainStale() || this.shouldRefreshOnRequestCount(requestCount);
+    }
+    // =========================================================================
+    // Config
+    // =========================================================================
+    updateStorage(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Seed fallback cache entries from persisted account.quota data.
+     * Only seeds accounts that don't already have a cache entry.
+     * Prevents unnecessary API calls when persisted quota is still fresh.
+     */
+    seedFallbacksFromAccounts(accounts) {
+        const checkInterval = getQuotaCheckIntervalMs(this.storage);
+        for (const account of accounts) {
+            if (account.enabled === false)
+                continue;
+            if (this.getFallback(account.id, account.access))
+                continue;
+            if (!account.quota)
+                continue;
+            const checkedAt = Math.max(account.quota.five_hour?.checkedAt ?? 0, account.quota.seven_day?.checkedAt ?? 0);
+            if (checkedAt <= 0)
+                continue;
+            this.setFallback(account.id, {
+                quota: account.quota,
+                refreshAfter: checkedAt + checkInterval,
+                checkedAt,
+            }, account.access);
+        }
+    }
+    /**
+     * Whether the MAIN quota API is currently in backoff. Scoped to the main
+     * account — a fallback account's 429 never reports here.
+     */
+    isBackedOff() {
+        return quotaBackoffActive(this.mainLastApiError, this.now());
+    }
+    /**
+     * Whether a specific fallback account's quota API is in backoff.
+     */
+    isFallbackBackedOff(accountId, accessToken) {
+        if (accessToken) {
+            const errorFp = this.fallbackErrorTokenFps.get(accountId);
+            if (errorFp !== tokenFingerprint(accessToken))
+                return false;
+        }
+        return quotaBackoffActive(this.fallbackApiErrors.get(accountId), this.now());
+    }
+    getLastApiError() {
+        return this.mainLastApiError;
+    }
+    // =========================================================================
+    // Private
+    // =========================================================================
+    /** Minimum gap between consecutive quota API calls (ms). */
+    static API_CALL_GAP_MS = 1_000;
+    static fallbackInflightKey(accountId, accessToken) {
+        return JSON.stringify([accountId, tokenFingerprint(accessToken)]);
+    }
+    /**
+     * Serialize API calls through a shared gate so only one
+     * quota API request runs at a time, with a minimum gap
+     * between calls. Prevents concurrent and rapid-fire calls
+     * from triggering Anthropic's rate limits.
+     */
+    _enqueueApiFetch(fn) {
+        const gatedFn = async () => {
+            // Wait until minimum gap since last API call
+            const elapsed = this.now() - this.lastApiCallAt;
+            if (elapsed < QuotaManager.API_CALL_GAP_MS) {
+                await new Promise((r) => {
+                    const id = nativeSetTimeout(r, QuotaManager.API_CALL_GAP_MS - elapsed);
+                    if (typeof id === 'object' && 'unref' in id)
+                        id.unref();
+                });
+            }
+            this.lastApiCallAt = this.now();
+            return fn();
+        };
+        const queued = this.apiGate.then(gatedFn, gatedFn);
+        this.apiGate = queued.catch(() => { });
+        return queued;
+    }
+    async _fetchMain(accessToken) {
+        return this._enqueueApiFetch(async () => {
+            try {
+                // Re-check backoff inside gate — may have been set by
+                // a preceding queued call while we waited
+                if (this.isBackedOff()) {
+                    if (this.main)
+                        return this.main.quota;
+                    throw new Error('Quota API rate-limited — try again later');
+                }
+                const fileLock = await acquireRefreshFileLock({
+                    name: 'opencode-main-quota-refresh',
+                    ttlMs: 30_000,
+                });
+                if (!fileLock) {
+                    if (this.main)
+                        return this.main.quota;
+                    throw new Error('Quota refresh is already in progress');
+                }
+                try {
+                    const quota = await fetchOAuthQuotaSnapshot({
+                        accessToken,
+                        fetchImpl: this.fetchImpl,
+                        now: this.now,
+                    });
+                    const now = this.now();
+                    this.mainTokenFp = tokenFingerprint(accessToken);
+                    this.main = {
+                        quota,
+                        refreshAfter: getQuotaNextRefreshAt(quota, this.storage, now),
+                        checkedAt: now,
+                    };
+                    this.mainLastApiError = undefined;
+                    this.onMainQuotaFetched?.(quota, now, this.mainTokenFp);
+                    return quota;
+                }
+                catch (error) {
+                    this._handleMainFetchError(error);
+                    throw error;
+                }
+                finally {
+                    await fileLock.release();
+                }
+            }
+            finally {
+                this.inflightMain = null;
+            }
+        });
+    }
+    async _fetchFallback(accountId, accessToken) {
+        return this._enqueueApiFetch(async () => {
+            try {
+                // Re-check backoff inside gate — scoped to this fallback account
+                if (this.isFallbackBackedOff(accountId, accessToken)) {
+                    const cached = this.getFallback(accountId, accessToken);
+                    if (cached)
+                        return cached.quota;
+                    throw new Error('Quota API rate-limited — try again later');
+                }
+                const quota = await fetchOAuthQuotaSnapshot({
+                    accessToken,
+                    fetchImpl: this.fetchImpl,
+                    now: this.now,
+                });
+                const now = this.now();
+                this.setFallback(accountId, {
+                    quota,
+                    refreshAfter: now + getQuotaCheckIntervalMs(this.storage),
+                    checkedAt: now,
+                }, accessToken);
+                this.fallbackApiErrors.delete(accountId);
+                this.fallbackErrorTokenFps.delete(accountId);
+                return quota;
+            }
+            catch (error) {
+                this._handleFallbackFetchError(accountId, accessToken, error);
+                throw error;
+            }
+            finally {
+                this.inflightFallbacks.delete(QuotaManager.fallbackInflightKey(accountId, accessToken));
+            }
+        });
+    }
+    // A 401 is an auth/token problem, not a rate limit. The caller refreshes the
+    // token and retries; backing off the quota API here would block that retry,
+    // so surface 401s without recording backoff state.
+    static isAuthError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return /quota check failed: 401\b/.test(message);
+    }
+    /** Main quota failure: arms main-only backoff and persists via onApiError. */
+    _handleMainFetchError(error) {
+        if (QuotaManager.isAuthError(error))
+            return;
+        this.mainLastApiError = buildQuotaOperationError({
+            error,
+            now: this.now(),
+            previous: this.mainLastApiError,
+        });
+        this.onApiError?.(this.mainLastApiError);
+    }
+    /**
+     * Fallback quota failure: arms backoff for THIS account only. Never touches
+     * main backoff state and never calls onApiError (which persists the main
+     * quota error) — the per-account error is recorded by the caller via the
+     * account's lastQuotaRefreshError.
+     */
+    _handleFallbackFetchError(accountId, accessToken, error) {
+        if (QuotaManager.isAuthError(error))
+            return;
+        const tokenFp = tokenFingerprint(accessToken);
+        const previous = this.fallbackErrorTokenFps.get(accountId) === tokenFp
+            ? this.fallbackApiErrors.get(accountId)
+            : undefined;
+        this.fallbackApiErrors.set(accountId, buildQuotaOperationError({
+            error,
+            now: this.now(),
+            previous,
+        }));
+        this.fallbackErrorTokenFps.set(accountId, tokenFp);
+    }
+}

package/dist/relay.js

@@ -241,6 +241,12 @@ function toBinaryChunk(data) {
 function parseRelayControlMessage(data) {
     return JSON.parse(data);
 }
+function relayControlErrorMessage(message) {
+    const detail = message.message || 'relay websocket error';
+    return message.status
+        ? `relay websocket error ${message.status}: ${detail}`
+        : detail;
+}
 class PersistentRelaySession {
     config;
     affinity;
@@ -561,7 +567,7 @@ class PersistentRelaySession {
             }
             const error = message.status === 409
                 ? new RelayStateMismatchError(message.message || 'state mismatch')
-                : new Error(message.message || 'relay websocket error');
+                : new Error(relayControlErrorMessage(message));
             this.failPending(error);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/anthropic-auth-core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "repository": {
     "type": "git",