@juspay/neurolink 10.11.3 → 10.12.0

package/dist/proxy/accountUsage.js

@@ -0,0 +1,288 @@
+/**
+ * On-Demand Account Usage Fetch
+ *
+ * Manual refetch path for account limits: queries Anthropic's OAuth usage
+ * endpoint (the same call Claude Code's /usage makes) to get FRESH session /
+ * weekly / model-scoped windows for an account without consuming any tokens
+ * and without starting a 5h session window.
+ *
+ * This complements — never replaces — the passive header capture in
+ * accountQuota.ts: `usageToQuota` normalizes the endpoint payload into the
+ * same `AccountQuota` shape so refreshed data flows through the existing
+ * save/merge/cooldown chain.
+ *
+ * Only OAuth (Bearer) accounts have subscription windows; api_key accounts
+ * are skipped and keep their header-derived absolute limits.
+ */
+import { logger } from "../utils/logger.js";
+import { tokenStore } from "../auth/tokenStore.js";
+import { CLAUDE_CLI_USER_AGENT, OAUTH_BETA_HEADERS, } from "../auth/anthropicOAuth.js";
+import { needsRefresh, refreshTokenFromLatest, isPermanentRefreshFailure, persistTokens, } from "./tokenRefresh.js";
+import { isAccountAllowed } from "./accountSelection.js";
+export const ANTHROPIC_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const USAGE_FETCH_TIMEOUT_MS = 10_000;
+/**
+ * Enumerate stored Anthropic accounts for a usage refresh.
+ * Read-only: no token refresh, no disable side effects — those decisions
+ * belong to the caller (fetchAccountUsage / the routing path respectively).
+ */
+export async function listAnthropicAccountsForUsage(allowlist) {
+    const accounts = [];
+    const compoundKeys = await tokenStore.listByPrefix("anthropic:");
+    for (const key of compoundKeys) {
+        if (!isAccountAllowed(key, allowlist)) {
+            continue;
+        }
+        if (await tokenStore.isDisabled(key)) {
+            continue;
+        }
+        const tokens = await tokenStore.loadTokens(key);
+        if (!tokens) {
+            continue;
+        }
+        // Full suffix after the first ":" — a label may itself contain colons,
+        // and the quota store and `auth list` rendering key by the full label.
+        const separatorIndex = key.indexOf(":");
+        accounts.push({
+            key,
+            label: separatorIndex >= 0 ? key.slice(separatorIndex + 1) : key,
+            token: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt,
+            type: tokens.tokenType === "Bearer" ? "oauth" : "api_key",
+            persistTarget: { providerKey: key },
+        });
+    }
+    return accounts;
+}
+async function requestUsage(token) {
+    try {
+        const response = await fetch(ANTHROPIC_USAGE_URL, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "anthropic-beta": OAUTH_BETA_HEADERS,
+                "user-agent": CLAUDE_CLI_USER_AGENT,
+                accept: "application/json",
+            },
+            signal: AbortSignal.timeout(USAGE_FETCH_TIMEOUT_MS),
+        });
+        return { response };
+    }
+    catch (err) {
+        return { networkError: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Fetch fresh usage windows for one account. Return-not-throw.
+ * Refreshes an expiring/expired token first (de-duped, rotation-safe), and
+ * retries once through a forced refresh on a 401.
+ */
+export async function fetchAccountUsage(account) {
+    if (account.type !== "oauth") {
+        return {
+            ok: false,
+            reason: "not_oauth",
+            error: "api_key accounts have no subscription usage windows",
+        };
+    }
+    const runRefresh = async () => {
+        const result = await refreshTokenFromLatest(account, account.persistTarget);
+        if (result.success) {
+            if (account.persistTarget) {
+                await persistTokens(account.persistTarget, account);
+            }
+            return null;
+        }
+        if (isPermanentRefreshFailure(result)) {
+            return {
+                ok: false,
+                reason: "auth",
+                error: "reauth required (refresh token rejected)",
+                status: result.status,
+            };
+        }
+        const tokenExpired = account.expiresAt
+            ? account.expiresAt <= Date.now()
+            : false;
+        return tokenExpired
+            ? {
+                ok: false,
+                reason: "auth",
+                error: "token expired and refresh failed",
+                status: result.status,
+            }
+            : null; // token still valid — attempt the fetch with it
+    };
+    let refreshedThisCall = false;
+    if (needsRefresh(account)) {
+        refreshedThisCall = true;
+        const failure = await runRefresh();
+        if (failure) {
+            return failure;
+        }
+    }
+    let { response, networkError } = await requestUsage(account.token);
+    if (response?.status === 401 && account.refreshToken && !refreshedThisCall) {
+        const failure = await runRefresh();
+        if (failure) {
+            return failure;
+        }
+        ({ response, networkError } = await requestUsage(account.token));
+    }
+    if (!response) {
+        return {
+            ok: false,
+            reason: "network",
+            error: networkError ?? "network failure",
+        };
+    }
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        logger.debug(`[account-usage] usage fetch failed for ${account.label}`, {
+            status: response.status,
+            body: body.slice(0, 300),
+        });
+        return {
+            ok: false,
+            reason: response.status === 401 || response.status === 403 ? "auth" : "http",
+            error: `usage endpoint returned HTTP ${response.status}`,
+            status: response.status,
+        };
+    }
+    try {
+        const usage = (await response.json());
+        return { ok: true, usage };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: "parse",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Normalization (pure CPU — unit-testable, no I/O)
+// ---------------------------------------------------------------------------
+const REJECTED_SEVERITIES = new Set([
+    "rejected",
+    "exceeded",
+    "over_limit",
+    "blocked",
+]);
+/**
+ * "rejected" iff the window is fully used or the provider severity marks it
+ * exhausted; anything unknown stays "allowed". Conservative on purpose: a
+ * wrong "rejected" would park an account, a wrong "allowed" just delays
+ * parking until the passive capture or the reset. Raw severity is preserved
+ * on the window so nothing is lost.
+ */
+function deriveWindowStatus(percent, severity) {
+    const sev = severity?.trim().toLowerCase();
+    if ((typeof percent === "number" && percent >= 100) ||
+        (sev !== undefined && REJECTED_SEVERITIES.has(sev))) {
+        return "rejected";
+    }
+    return "allowed";
+}
+/** ISO-8601 → unix seconds; 0 when absent/unparseable (matches headers). */
+function isoToEpochSeconds(value) {
+    if (!value) {
+        return 0;
+    }
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? 0 : Math.floor(ms / 1000);
+}
+function toFraction(percent) {
+    return typeof percent === "number" && Number.isFinite(percent)
+        ? percent / 100
+        : undefined;
+}
+function mapUsageLimit(entry) {
+    const window = {
+        kind: entry.kind ?? "unknown",
+        used: toFraction(entry.percent) ?? 0,
+        status: deriveWindowStatus(entry.percent, entry.severity),
+        resetsAt: isoToEpochSeconds(entry.resets_at),
+    };
+    if (entry.group !== undefined) {
+        window.group = entry.group;
+    }
+    if (entry.severity !== null && entry.severity !== undefined) {
+        window.severity = entry.severity;
+    }
+    if (entry.is_active !== null && entry.is_active !== undefined) {
+        window.isActive = entry.is_active;
+    }
+    const scopeModel = entry.scope?.model?.display_name;
+    if (scopeModel) {
+        window.scopeModel = scopeModel;
+    }
+    const scopeSurface = entry.scope?.surface;
+    if (scopeSurface) {
+        window.scopeSurface = scopeSurface;
+    }
+    return window;
+}
+/**
+ * Normalize a usage-endpoint payload into the `AccountQuota` shape used by
+ * the passive header path, so a refresh writes through the exact same
+ * save/merge/cooldown chain.
+ *
+ * `prior` supplies fields the usage payload cannot express (fallback and
+ * upgrade-path signals) so `isQuotaOverageAvailable` behaves identically
+ * before and after a refresh. `unifiedStatus` is deliberately never set:
+ * fabricating it would let the reconcile path treat a refresh like a
+ * unified-rejected 429.
+ */
+export function usageToQuota(usage, opts) {
+    const limits = Array.isArray(usage.limits) ? usage.limits : [];
+    if (!usage.five_hour && !usage.seven_day && limits.length === 0) {
+        return null;
+    }
+    const { now, prior } = opts;
+    const windows = limits.map(mapUsageLimit);
+    const sessionLimit = limits.find((entry) => entry.kind === "session");
+    const weeklyLimit = limits.find((entry) => entry.kind === "weekly_all");
+    const sessionPct = usage.five_hour?.utilization ?? sessionLimit?.percent ?? undefined;
+    const weeklyPct = usage.seven_day?.utilization ?? weeklyLimit?.percent ?? undefined;
+    // A refresh must never replace a known reset with 0: the payload omits
+    // `resets_at` for untouched windows, and a zero reset would stop
+    // reconcileCooldownFromQuota from parking a rejected window and make the
+    // routing metrics treat it as non-ticking. A stale prior reset degrades
+    // gracefully (past resets are ignored / freshened downstream).
+    const sessionResetAt = isoToEpochSeconds(usage.five_hour?.resets_at) ||
+        isoToEpochSeconds(sessionLimit?.resets_at) ||
+        (prior?.sessionResetAt ?? 0);
+    const weeklyResetAt = isoToEpochSeconds(usage.seven_day?.resets_at) ||
+        isoToEpochSeconds(weeklyLimit?.resets_at) ||
+        (prior?.weeklyResetAt ?? 0);
+    const overageEnabled = usage.extra_usage?.is_enabled;
+    const overageStatus = overageEnabled === true
+        ? "allowed"
+        : overageEnabled === false
+            ? "rejected"
+            : (prior?.overageStatus ?? "unknown");
+    const quota = {
+        sessionUsed: toFraction(sessionPct) ?? prior?.sessionUsed ?? 0,
+        sessionStatus: deriveWindowStatus(sessionPct, sessionLimit?.severity),
+        sessionResetAt,
+        weeklyUsed: toFraction(weeklyPct) ?? prior?.weeklyUsed ?? 0,
+        weeklyStatus: deriveWindowStatus(weeklyPct, weeklyLimit?.severity),
+        weeklyResetAt,
+        fallbackPercentage: prior?.fallbackPercentage ?? 0,
+        overageStatus,
+        lastUpdated: now,
+        windows,
+        windowsUpdatedAt: now,
+        source: "usage-api",
+    };
+    if (prior?.fallbackStatus !== undefined) {
+        quota.fallbackStatus = prior.fallbackStatus;
+    }
+    if (prior?.upgradePaths !== undefined) {
+        quota.upgradePaths = prior.upgradePaths;
+    }
+    return quota;
+}

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, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyQuotaCooldownUpdate, ProxyPassthroughAccount, QueuedAccountAdmission, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
+import type { AccountAllowlist, AccountAdmissionLease, AccountCooldownPlan, AccountQuota, 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";
 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>;
@@ -74,6 +74,18 @@ declare function reconcileCooldownFromQuota(state: RuntimeAccountState, quota: A
  * gracefully because past reset timestamps are ignored by resetEpochToMs.
  */
 declare function seedRuntimeQuotasFromDisk(accounts: ProxyPassthroughAccount[]): Promise<void>;
+/**
+ * Fetch fresh limits from Anthropic's usage endpoint for every eligible OAuth
+ * account and write them through the exact same chain the passive header
+ * capture uses (runtime state → cooldown reconciliation → debounced disk
+ * snapshot), so routing and `auth list` see the refreshed windows and the
+ * automatic path keeps working unchanged on top of them.
+ */
+declare function refreshAccountLimits(options?: {
+    accountAllowlist?: AccountAllowlist;
+    accountFilter?: string;
+    snapshotOnly?: boolean;
+}): Promise<ProxyLimitsRefreshResponse>;
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
  * spend the overall weekly allowance that expires SOONEST first, so quota
@@ -345,6 +357,8 @@ export declare const __testHooks: {
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;
     planCooldownFor429: typeof planCooldownFor429;
     reconcileCooldownFromQuota: typeof reconcileCooldownFromQuota;
+    refreshAccountLimits: typeof refreshAccountLimits;
+    clearLimitsRefreshStateForTests: () => void;
     isRetryableNetworkError: typeof isRetryableNetworkError;
     isPermanentRefreshFailure: typeof isPermanentRefreshFailure;
     getStreamFailureDetails: typeof getStreamFailureDetails;

package/dist/server/routes/claudeProxyRoutes.js

@@ -17,6 +17,7 @@ import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_
 import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from "../../proxy/accountCooldown.js";
 import { anthropicAccountKeysEqual, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
 import { getUnifiedRateLimitStatus, isQuotaOverageAvailable, loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
+import { fetchAccountUsage, listAnthropicAccountsForUsage, usageToQuota, } from "../../proxy/accountUsage.js";
 import { buildProxyLimitHeaders, summarizePoolHeadroom, } from "../../proxy/quotaHeaders.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
 import { buildAnthropicModelsListResponse, buildTranslationOptions, extractText, extractToolArgs, extractUsageFromStreamResult, handleTranslatedJsonRequest, handleTranslatedStreamRequest, hasTranslatedOutput, } from "../../proxy/proxyTranslationEngine.js";
@@ -639,6 +640,127 @@ async function seedRuntimeQuotasFromDisk(accounts) {
         // Non-fatal: seeding is best-effort; ordering falls back to probe-first.
     }
 }
+// ---------------------------------------------------------------------------
+// Manual limits refresh (GET /limits)
+// ---------------------------------------------------------------------------
+/** Minimum spacing between usage-endpoint fetches for one account. Bounds
+ *  abuse of the ungated endpoint; inside the window the last reading is
+ *  returned as "throttled" (still fresher than any passive snapshot). */
+const MIN_USAGE_REFETCH_INTERVAL_MS = 15_000;
+const lastUsageFetchAt = new Map();
+let limitsRefreshInFlight = null;
+const USAGE_REFRESH_CONCURRENCY = 4;
+/**
+ * Fetch fresh limits from Anthropic's usage endpoint for every eligible OAuth
+ * account and write them through the exact same chain the passive header
+ * capture uses (runtime state → cooldown reconciliation → debounced disk
+ * snapshot), so routing and `auth list` see the refreshed windows and the
+ * automatic path keeps working unchanged on top of them.
+ */
+async function refreshAccountLimits(options = {}) {
+    const fetchedAt = Date.now();
+    const allAccounts = await listAnthropicAccountsForUsage(options.accountAllowlist);
+    const accounts = options.accountFilter
+        ? allAccounts.filter((account) => account.label === options.accountFilter ||
+            account.key === options.accountFilter)
+        : allAccounts;
+    const persisted = await loadAccountQuotas().catch(() => ({}));
+    const buildResult = (account, status, quota, error) => {
+        const state = accountRuntimeState.get(account.key);
+        const result = {
+            account: account.label,
+            key: account.key,
+            type: account.type,
+            status,
+            quota: quota ?? state?.quota ?? persisted[account.label] ?? null,
+        };
+        if (error !== undefined) {
+            result.error = error;
+        }
+        if (state?.coolingUntil && state.coolingUntil > Date.now()) {
+            result.coolingUntil = state.coolingUntil;
+            if (state.coolingReason) {
+                result.coolingReason = state.coolingReason;
+            }
+        }
+        return result;
+    };
+    if (options.snapshotOnly) {
+        return {
+            fetchedAt,
+            snapshot: true,
+            results: accounts.map((account) => buildResult(account, "snapshot", null)),
+        };
+    }
+    const results = new Array(accounts.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = nextIndex++;
+            if (index >= accounts.length) {
+                return;
+            }
+            const account = accounts[index];
+            if (account.type !== "oauth") {
+                results[index] = buildResult(account, "skipped_api_key", null);
+                continue;
+            }
+            const lastFetch = lastUsageFetchAt.get(account.key) ?? 0;
+            if (Date.now() - lastFetch < MIN_USAGE_REFETCH_INTERVAL_MS) {
+                results[index] = buildResult(account, "throttled", null);
+                continue;
+            }
+            lastUsageFetchAt.set(account.key, Date.now());
+            // Isolate failures per account: an unexpected rejection must not abort
+            // the Promise.all sweep and turn the whole /limits response into a 502.
+            try {
+                const fetchResult = await fetchAccountUsage(account);
+                // `=== false` (not `!ok`) — the react-hooks sub-build compiles this
+                // file without strictNullChecks, where negated boolean-discriminant
+                // narrowing does not apply.
+                if (fetchResult.ok === false) {
+                    results[index] = buildResult(account, "error", null, fetchResult.error);
+                    continue;
+                }
+                const state = getOrCreateRuntimeState(account.key);
+                const capturedAt = Date.now();
+                const quota = usageToQuota(fetchResult.usage, {
+                    now: capturedAt,
+                    prior: state.quota ?? persisted[account.label] ?? null,
+                });
+                if (!quota) {
+                    results[index] = buildResult(account, "error", null, "usage payload had no recognizable limit windows");
+                    continue;
+                }
+                // Guard against a passive header capture that landed mid-fetch: never
+                // replace a fresher runtime snapshot with an older reading.
+                if (quota.lastUpdated >= (state.quota?.lastUpdated ?? 0)) {
+                    state.quota = quota;
+                }
+                const cooldownUpdate = reconcileCooldownFromQuota(state, quota, capturedAt);
+                if (cooldownUpdate?.kind === "cooled") {
+                    await saveAccountCooldown(account.key, cooldownUpdate.coolingUntil, cooldownUpdate.coolingReason).catch(() => {
+                        // Non-fatal: cooldown is already active in memory.
+                    });
+                }
+                else if (cooldownUpdate?.kind === "cleared") {
+                    await clearAccountCooldown(account.key, cooldownUpdate.coolingUntil).catch(() => {
+                        // Non-fatal: the next successful response will reconcile again.
+                    });
+                }
+                await saveAccountQuota(account.label, quota).catch(() => {
+                    // Non-fatal: quota persistence is best-effort
+                });
+                results[index] = buildResult(account, "refreshed", quota);
+            }
+            catch (err) {
+                results[index] = buildResult(account, "error", null, err instanceof Error ? err.message : String(err));
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(USAGE_REFRESH_CONCURRENCY, accounts.length || 1) }, () => worker()));
+    return { fetchedAt, snapshot: false, results };
+}
 /** Quota-aware selection is on by default; disable with
  *  NEUROLINK_PROXY_QUOTA_ROUTING=off|false|0. Only affects the fill-first
  *  strategy (round-robin keeps strict rotation). */
@@ -5037,6 +5159,45 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                 description: "Count tokens for a messages request",
                 tags: ["claude-proxy", "tokens"],
             },
+            // =====================================================================
+            // GET /limits -- Fresh account limits from Anthropic's usage endpoint
+            // =====================================================================
+            {
+                method: "GET",
+                path: `${basePath}/limits`,
+                handler: async (ctx) => {
+                    const effectiveAllowlist = runtimeConfigProvider
+                        ? runtimeConfigProvider().accountAllowlist
+                        : accountAllowlist;
+                    const snapshotOnly = ctx.query?.snapshot === "true" || ctx.query?.snapshot === "1";
+                    const accountFilter = ctx.query?.account;
+                    return withSpan({
+                        name: "neurolink.http.claudeProxy.limits",
+                        tracer: tracers.http,
+                        attributes: { "http.route": `${basePath}/limits` },
+                    }, async () => {
+                        // Single-flight: concurrent full refreshes share one sweep.
+                        if (!snapshotOnly && !accountFilter) {
+                            if (!limitsRefreshInFlight) {
+                                limitsRefreshInFlight = refreshAccountLimits({
+                                    accountAllowlist: effectiveAllowlist,
+                                }).finally(() => {
+                                    limitsRefreshInFlight = null;
+                                });
+                            }
+                            return limitsRefreshInFlight;
+                        }
+                        return refreshAccountLimits({
+                            accountAllowlist: effectiveAllowlist,
+                            accountFilter,
+                            snapshotOnly,
+                        });
+                    });
+                },
+                description: "Fetch fresh per-account limits from Anthropic (usage API). " +
+                    "?account=<label> for one account, ?snapshot=true for stored state",
+                tags: ["claude-proxy", "limits"],
+            },
         ],
     };
 }
@@ -5340,6 +5501,11 @@ export const __testHooks = {
     maybeResetPrimaryToHome,
     planCooldownFor429,
     reconcileCooldownFromQuota,
+    refreshAccountLimits,
+    clearLimitsRefreshStateForTests: () => {
+        lastUsageFetchAt.clear();
+        limitsRefreshInFlight = null;
+    },
     isRetryableNetworkError,
     isPermanentRefreshFailure,
     getStreamFailureDetails,

package/dist/types/cli.d.ts

@@ -11,6 +11,7 @@ import type { PPTGenerationResult } from "./ppt.js";
 import type { AvatarResult } from "./avatar.js";
 import type { MusicResult } from "./music.js";
 import type { OAuthTokens } from "./auth.js";
+import type { AccountQuota } from "./proxy.js";
 import type { ClaudeSubscriptionTier } from "./subscription.js";
 import type { ServerFramework } from "./server.js";
 import type { AuthProviderType } from "./auth.js";
@@ -947,6 +948,8 @@ export type AuthCommandArgs = BaseCommandArgs & {
     label?: string;
     account?: string;
     force?: boolean;
+    /** `auth list --refresh`: fetch fresh limits from Anthropic before listing */
+    refresh?: boolean;
     /** Path to the proxy config YAML, used by set-/get-/clear-primary */
     config?: string;
     /** Email passed to `auth set-primary <email>` */
@@ -954,6 +957,15 @@ export type AuthCommandArgs = BaseCommandArgs & {
     /** Yargs positional arguments */
     _?: (string | number)[];
 };
+/** Outcome of the `auth list --refresh` fresh-limit fetch. */
+export type AuthListRefreshOutcome = {
+    /** How the fresh limits were obtained ("none" when every path failed). */
+    via: "proxy" | "direct" | "none";
+    /** Freshly fetched quotas keyed by account label; null when none fetched. */
+    quotas: Record<string, AccountQuota> | null;
+    /** Per-account and transport errors, already formatted for display. */
+    errors: string[];
+};
 /** Telemetry command arguments */
 export type TelemetryCommandArgs = {
     format?: "text" | "json" | "table";

package/dist/types/proxy.d.ts

@@ -943,6 +943,107 @@ export type AccountQuota = {
     overageStatus: string;
     /** Epoch ms when we last captured this data */
     lastUpdated: number;
+    /** Dynamic per-plan limit buckets from the usage API `limits[]` array
+     *  (session / weekly_all / model-scoped weeklies such as Fable / future
+     *  kinds). Absent on purely header-sourced snapshots. */
+    windows?: AccountQuotaWindow[];
+    /** Epoch ms when `windows` was last refreshed from the usage API. */
+    windowsUpdatedAt?: number;
+    /** Provenance of this snapshot's numbers. */
+    source?: AccountQuotaSource;
+};
+/** Where an AccountQuota snapshot came from.
+ *  - "headers"   : passive capture of anthropic-ratelimit-unified-* response
+ *                  headers on a routed request (the automatic path).
+ *  - "usage-api" : an explicit refresh against Anthropic's OAuth usage
+ *                  endpoint (manual refetch path). */
+export type AccountQuotaSource = "headers" | "usage-api";
+/** One dynamic limit bucket from the usage API. Provider vocabulary (`kind`,
+ *  `group`, `severity`) is preserved verbatim so buckets Anthropic adds later
+ *  survive storage and display without a code change. */
+export type AccountQuotaWindow = {
+    /** Provider kind, verbatim ("session", "weekly_all", "weekly_scoped", ...). */
+    kind: string;
+    /** Provider group, verbatim ("session" | "weekly" | future values). */
+    group?: string;
+    /** 0.0-1.0 utilization (provider percent / 100). */
+    used: number;
+    /** Provider severity, verbatim ("normal", ...). */
+    severity?: string;
+    /** Derived "allowed" | "rejected" (see usageToQuota status mapping). */
+    status: string;
+    /** Unix timestamp (seconds) when this window resets; 0 when unparseable. */
+    resetsAt: number;
+    isActive?: boolean;
+    /** Model display name for model-scoped windows (e.g. "Fable"). */
+    scopeModel?: string;
+    /** Surface scope when the provider reports one. */
+    scopeSurface?: string;
+};
+/** One utilization window from the OAuth usage endpoint (wire shape, loose). */
+export type AnthropicUsageWindow = {
+    /** 0-100 percent (note: NOT the 0-1 fraction used by headers). */
+    utilization?: number | null;
+    /** ISO-8601 timestamp. */
+    resets_at?: string | null;
+};
+/** One entry of the usage endpoint's generic `limits[]` array (wire shape). */
+export type AnthropicUsageLimit = {
+    kind?: string;
+    group?: string;
+    /** 0-100 percent. */
+    percent?: number | null;
+    severity?: string | null;
+    resets_at?: string | null;
+    scope?: {
+        model?: {
+            id?: string | null;
+            display_name?: string | null;
+        } | null;
+        surface?: string | null;
+    } | null;
+    is_active?: boolean | null;
+};
+/** Response body of GET https://api.anthropic.com/api/oauth/usage (loose —
+ *  unknown keys are ignored, known keys may be absent or null). */
+export type AnthropicUsageResponse = {
+    five_hour?: AnthropicUsageWindow | null;
+    seven_day?: AnthropicUsageWindow | null;
+    limits?: AnthropicUsageLimit[] | null;
+    extra_usage?: {
+        is_enabled?: boolean | null;
+    } | null;
+};
+/** Outcome of one account's usage-endpoint fetch. Return-not-throw. */
+export type AccountUsageFetchResult = {
+    ok: true;
+    usage: AnthropicUsageResponse;
+} | {
+    ok: false;
+    reason: "not_oauth" | "auth" | "http" | "network" | "parse";
+    error: string;
+    status?: number;
+};
+/** Per-account result inside a GET /limits response. */
+export type ProxyLimitsAccountResult = {
+    /** Account label (quota-store key). */
+    account: string;
+    /** Token-store key ("anthropic:<label>"). */
+    key: string;
+    type: ProxyAccountType;
+    status: "refreshed" | "throttled" | "skipped_api_key" | "snapshot" | "error";
+    /** Fresh quota on "refreshed"; last known snapshot otherwise (may be null). */
+    quota: AccountQuota | null;
+    error?: string;
+    coolingUntil?: number;
+    coolingReason?: AccountCoolingReason;
+};
+/** Response body of the proxy's GET /limits endpoint. */
+export type ProxyLimitsRefreshResponse = {
+    fetchedAt: number;
+    /** True when served from stored state without contacting Anthropic. */
+    snapshot: boolean;
+    results: ProxyLimitsAccountResult[];
 };
 /**
  * Provenance of the quota numbers attached to a single proxy response.