@juspay/neurolink 10.9.0 → 10.10.0

package/dist/lib/proxy/quotaHeaders.js

@@ -0,0 +1,189 @@
+/**
+ * Proxy response quota headers.
+ *
+ * The proxy already knows, per request, exactly how much subscription capacity
+ * the serving account has left — it parses Anthropic's `anthropic-ratelimit-*`
+ * headers to route on them (see `accountQuota.ts`). Historically none of that
+ * reached the client: only the SSE path forwarded a small legacy allowlist, and
+ * every JSON/error path dropped headers entirely.
+ *
+ * This module turns that state into response headers in two layers:
+ *
+ * 1. **Verbatim passthrough** of Anthropic's own `anthropic-ratelimit-*` and
+ *    `retry-after` headers. This is the load-bearing part: a proxied response
+ *    then looks byte-identical to a direct one, so a consumer needs exactly one
+ *    parser for both.
+ * 2. **`x-neurolink-*`** for what only the proxy can know — which account
+ *    served the request, pool headroom, whether the numbers are live or stale,
+ *    and the derived "how much is left" percentages.
+ *
+ * Pure CPU, no I/O — safe on the hot path and directly unit-testable.
+ *
+ * @module proxy/quotaHeaders
+ */
+/** Upstream headers forwarded to the client untouched. */
+const UPSTREAM_PREFIX = "anthropic-ratelimit-";
+const UPSTREAM_EXTRA_HEADERS = ["retry-after"];
+/**
+ * A value beyond ~year 2100 expressed in seconds is already milliseconds —
+ * same heuristic the cooldown planner uses, kept in sync deliberately so
+ * "resets in" and the actual cooldown never disagree.
+ */
+const EPOCH_SECONDS_CEILING = 4_102_444_800;
+/**
+ * Strip anything that cannot legally appear in a header value.
+ *
+ * Account labels originate from user email addresses, so this is not
+ * theoretical: a CR/LF in a label would let a crafted account name inject
+ * additional response headers. Non-ASCII is dropped rather than encoded —
+ * these are diagnostic values, not content.
+ */
+function sanitizeHeaderValue(value) {
+    return value.replace(/[^\x20-\x7E]/g, "").trim();
+}
+/** Epoch seconds (or ms) → seconds from now, floored at 0. Undefined when the
+ *  timestamp is absent, zero, or already in the past. */
+function secondsUntil(resetEpoch, now) {
+    if (!resetEpoch || resetEpoch <= 0) {
+        return undefined;
+    }
+    const ms = resetEpoch > EPOCH_SECONDS_CEILING ? resetEpoch : resetEpoch * 1000;
+    if (ms <= now) {
+        return undefined;
+    }
+    return Math.round((ms - now) / 1000);
+}
+/**
+ * Convert a 0.0-1.0 utilization fraction into a whole-percent "left" figure.
+ *
+ * Anthropic publishes utilization (used), never remaining, for subscription
+ * windows — there is no absolute message or token count to report, so the
+ * honest derived form is a percentage. Clamped because a utilization above 1.0
+ * (overage) would otherwise produce a negative "left".
+ */
+export function utilizationToLeftPct(used) {
+    if (!Number.isFinite(used)) {
+        return 0;
+    }
+    return Math.max(0, Math.min(100, Math.round((1 - used) * 100)));
+}
+/**
+ * Copy Anthropic's rate-limit headers verbatim from an upstream response.
+ *
+ * Covers both header families: the unified subscription windows
+ * (`unified-5h-*`, `unified-7d-*`) and the legacy per-tier counters
+ * (`requests-remaining`, `tokens-remaining`, ...) that API-key accounts get.
+ * Which family is present depends on the serving account type, which is why
+ * `x-neurolink-account-type` accompanies them.
+ */
+export function pickUpstreamRateLimitHeaders(headers) {
+    const picked = {};
+    const consider = (key, value) => {
+        const lower = key.toLowerCase();
+        if (lower.startsWith(UPSTREAM_PREFIX) ||
+            UPSTREAM_EXTRA_HEADERS.includes(lower)) {
+            const clean = sanitizeHeaderValue(value);
+            if (clean) {
+                picked[lower] = clean;
+            }
+        }
+    };
+    if (typeof headers.forEach === "function") {
+        headers.forEach((value, key) => consider(key, value));
+        return picked;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === "string") {
+            consider(key, value);
+        }
+    }
+    return picked;
+}
+/**
+ * Build the `x-neurolink-*` half of the contract from proxy-side state.
+ *
+ * Always emits `x-neurolink-quota-source` — even when it is "none". A consumer
+ * that sees quota numbers with no provenance cannot tell a fresh reading from a
+ * snapshot carried over from a previous request, and would happily log stale
+ * capacity as current.
+ */
+export function buildQuotaResponseHeaders(context, now = Date.now()) {
+    const headers = {
+        "x-neurolink-quota-source": context.source,
+    };
+    const set = (name, value) => {
+        if (value === undefined || value === null) {
+            return;
+        }
+        const clean = sanitizeHeaderValue(String(value));
+        if (clean) {
+            headers[name] = clean;
+        }
+    };
+    set("x-neurolink-account", context.accountLabel);
+    set("x-neurolink-account-type", context.accountType);
+    set("x-neurolink-served-by", context.servedBy);
+    set("x-neurolink-attempt", context.attempt);
+    set("x-neurolink-account-cooling-until", context.coolingUntil);
+    set("x-neurolink-account-cooling-reason", context.coolingReason);
+    if (context.pool) {
+        set("x-neurolink-pool-available", context.pool.available);
+        set("x-neurolink-pool-cooling", context.pool.cooling);
+        set("x-neurolink-pool-best-session-left", context.pool.bestSessionLeftPct);
+    }
+    const quota = context.quota;
+    if (quota && context.source !== "none") {
+        set("x-neurolink-quota-session-left-pct", utilizationToLeftPct(quota.sessionUsed));
+        set("x-neurolink-quota-session-status", quota.sessionStatus);
+        set("x-neurolink-quota-session-resets-in", secondsUntil(quota.sessionResetAt, now));
+        set("x-neurolink-quota-weekly-left-pct", utilizationToLeftPct(quota.weeklyUsed));
+        set("x-neurolink-quota-weekly-status", quota.weeklyStatus);
+        set("x-neurolink-quota-weekly-resets-in", secondsUntil(quota.weeklyResetAt, now));
+        set("x-neurolink-quota-unified-status", quota.unifiedStatus);
+        set("x-neurolink-quota-overage-status", quota.overageStatus);
+        set("x-neurolink-quota-fallback-pct", Math.round((quota.fallbackPercentage ?? 0) * 100));
+        set("x-neurolink-quota-updated-at", quota.lastUpdated);
+    }
+    return headers;
+}
+/**
+ * Full response header set: upstream verbatim + proxy-derived.
+ *
+ * Upstream headers are applied first so a `x-neurolink-*` key can never be
+ * shadowed by an upstream one (they share no names today, but the ordering
+ * makes the precedence explicit rather than incidental).
+ */
+export function buildProxyLimitHeaders(args) {
+    return {
+        ...(args.upstreamHeaders
+            ? pickUpstreamRateLimitHeaders(args.upstreamHeaders)
+            : {}),
+        ...buildQuotaResponseHeaders(args.context, args.now),
+    };
+}
+/** Compute pool headroom from the runtime account states backing a request. */
+export function summarizePoolHeadroom(entries, now = Date.now()) {
+    let available = 0;
+    let cooling = 0;
+    let bestSessionLeftPct;
+    for (const entry of entries) {
+        const isCooling = !!entry.coolingUntil && entry.coolingUntil > now;
+        if (isCooling) {
+            cooling += 1;
+            continue;
+        }
+        available += 1;
+        if (entry.quota) {
+            const left = utilizationToLeftPct(entry.quota.sessionUsed);
+            if (bestSessionLeftPct === undefined || left > bestSessionLeftPct) {
+                bestSessionLeftPct = left;
+            }
+        }
+    }
+    return {
+        available,
+        cooling,
+        ...(bestSessionLeftPct !== undefined ? { bestSessionLeftPct } : {}),
+    };
+}
+//# sourceMappingURL=quotaHeaders.js.map

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

@@ -77,6 +77,8 @@ export declare function recordFinalSuccess(accountLabel?: string, accountType?:
 export declare function recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
 export declare function recordFinalError(status: number, accountLabel?: string, accountType?: string, details?: ProxyTerminalErrorDetails): void;
 export declare function getStats(): ProxyStats;
+/** Return the process-local coherent snapshot without filesystem reconciliation. */
+export declare function getUsageSnapshot(): ProxyUsageStatsSnapshot;
 export declare function getReconciledStats(): Promise<ProxyStats>;
 export declare function getReconciledUsageSnapshot(): Promise<ProxyUsageStatsSnapshot>;
 export declare function getAccountStats(label: string): AccountStats | undefined;

package/dist/lib/proxy/usageStats.js

@@ -1121,6 +1121,10 @@ export function recordFinalError(status, accountLabel, accountType, details) {
 export function getStats() {
     return defaultStore.getStats();
 }
+/** Return the process-local coherent snapshot without filesystem reconciliation. */
+export function getUsageSnapshot() {
+    return defaultStore.getUsageSnapshot();
+}
 export async function getReconciledStats() {
     return defaultStore.reconcile();
 }

package/dist/lib/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 { 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";
 import { tracers } from "../../telemetry/tracers.js";
@@ -426,6 +427,56 @@ function resetEpochToMs(resetEpoch, now) {
     const ms = resetEpoch > 4_102_444_800 ? resetEpoch : resetEpoch * 1000;
     return ms > now ? ms : undefined;
 }
+/**
+ * Publish limit/quota headers for this response onto the request context.
+ *
+ * Every response path funnels through here so the header contract is defined
+ * once. The proxy runtime copies `ctx.responseHeaders` onto JSON and error
+ * responses, and merges them into streaming Responses for keys those don't
+ * already set — so a single call covers both shapes.
+ */
+function publishLimitHeaders(ctx, args) {
+    try {
+        const pool = args.poolAccounts
+            ? summarizePoolHeadroom(args.poolAccounts.map((account) => {
+                const state = accountRuntimeState.get(account.key);
+                return {
+                    ...(state?.coolingUntil !== undefined
+                        ? { coolingUntil: state.coolingUntil }
+                        : {}),
+                    ...(state?.quota ? { quota: state.quota } : {}),
+                };
+            }))
+            : undefined;
+        const headers = buildProxyLimitHeaders({
+            ...(args.upstreamHeaders
+                ? { upstreamHeaders: args.upstreamHeaders }
+                : {}),
+            context: {
+                quota: args.quota ?? null,
+                source: args.source,
+                ...(args.account ? { accountLabel: args.account.label } : {}),
+                ...((args.accountType ?? args.account?.type)
+                    ? { accountType: args.accountType ?? args.account?.type }
+                    : {}),
+                ...(args.servedBy ? { servedBy: args.servedBy } : {}),
+                ...(args.attempt !== undefined ? { attempt: args.attempt } : {}),
+                ...(args.accountState?.coolingUntil !== undefined
+                    ? { coolingUntil: args.accountState.coolingUntil }
+                    : {}),
+                ...(args.accountState?.coolingReason
+                    ? { coolingReason: args.accountState.coolingReason }
+                    : {}),
+                ...(pool ? { pool } : {}),
+            },
+        });
+        ctx.responseHeaders = { ...(ctx.responseHeaders ?? {}), ...headers };
+    }
+    catch (error) {
+        // Diagnostics must never break a response that is otherwise fine.
+        logger.debug(`[proxy] failed to publish limit headers: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 /** Clamp a cooldown target epoch-ms into [now+MIN, now+MAX]. */
 function clampCooldownUntil(untilMs, now) {
     return Math.min(Math.max(untilMs, now + MIN_COOLDOWN_MS), now + MAX_COOLDOWN_MS);
@@ -1466,6 +1517,20 @@ async function handleClaudePassthroughRequest(args) {
         upstreamResponseHeaders[key] = value;
     });
     tracer?.logUpstreamResponseHeaders(upstreamResponseHeaders);
+    // Passthrough uses the caller's own credentials, so there is no account pool
+    // to report — but the upstream quota headers are still the caller's real
+    // limits. Published before the ok/non-ok split so a 429 carries them too.
+    {
+        const passthroughQuota = parseQuotaHeaders(response.headers);
+        publishLimitHeaders(ctx, {
+            upstreamHeaders: response.headers,
+            quota: passthroughQuota,
+            source: passthroughQuota ? "live" : "none",
+            accountType: "passthrough",
+            servedBy: "anthropic",
+            attempt: 1,
+        });
+    }
     if (!response.ok) {
         const errorText = await response.text();
         recordAttemptError("passthrough", "passthrough", response.status, response.status === 429 ? "quota" : undefined);
@@ -1572,7 +1637,7 @@ function trackUpstreamReadableStream(source) {
     return { stream, outcome: tracker.outcome };
 }
 async function handleClaudePassthroughStreamResponse(args) {
-    const { bodyStr, response, tracer, requestStartTime, upstreamSpan, upstreamResponseHeaders, logProxyBody, logFinalRequest, } = args;
+    const { ctx, bodyStr, response, tracer, requestStartTime, upstreamSpan, upstreamResponseHeaders, logProxyBody, logFinalRequest, } = args;
     const responseHeaders = { ...upstreamResponseHeaders };
     const { stream: clientCaptureStream, capture: clientCapture } = createRawStreamCapture();
     const responseBody = response.body;
@@ -1754,7 +1819,13 @@ async function handleClaudePassthroughStreamResponse(args) {
     const clientStream = streamSource.pipeThrough(clientCaptureStream);
     return new Response(clientStream, {
         status: response.status,
-        headers: responseHeaders,
+        // Upstream headers first, then the proxy's own — passthrough already
+        // forwarded everything Anthropic sent, so this only adds the x-neurolink-*
+        // fields the client cannot derive on its own.
+        headers: {
+            ...responseHeaders,
+            ...(ctx.responseHeaders ?? {}),
+        },
     });
 }
 async function handleClaudePassthroughJsonResponse(args) {
@@ -2244,6 +2315,14 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 attemptCount: fallbackPlan.attempts.slice(1).length,
                 reason: "fallback_success",
             });
+            // A different provider produced this response — say so, and report no
+            // quota. Emitting the last Anthropic snapshot here would attribute one
+            // provider's capacity to another's output.
+            publishLimitHeaders(ctx, {
+                quota: null,
+                source: "none",
+                servedBy: fallback.provider,
+            });
             return { response };
         }
         catch (fallbackErr) {
@@ -2320,6 +2399,13 @@ async function tryAutoClaudeFallback(args) {
             attemptCount: 1,
             reason: "fallback_success",
         });
+        // See the configured-chain path: never attribute Anthropic quota to a
+        // response another provider produced.
+        publishLimitHeaders(ctx, {
+            quota: null,
+            source: "none",
+            servedBy: "auto-provider",
+        });
         return { response };
     }
     catch (fallbackErr) {
@@ -2441,7 +2527,7 @@ function buildClaudeAnthropicFailureResponse(args) {
     });
 }
 async function handleAnthropicSuccessfulResponse(args) {
-    const { ctx, body, account, accountState, response, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, } = args;
+    const { ctx, body, account, accountState, response, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, poolAccounts, logFinalRequest, } = args;
     accountState.consecutiveRefreshFailures = 0;
     logger.always(`[proxy] ← ${response.status} account=${account.label}`);
     const quota = parseQuotaHeaders(response.headers);
@@ -2470,6 +2556,20 @@ async function handleAnthropicSuccessfulResponse(args) {
         responseHeaders[key] = value;
     });
     tracer?.logUpstreamResponseHeaders(responseHeaders);
+    // Surface limits to the client. `quota` is non-null only when this upstream
+    // response actually carried the unified headers; otherwise fall back to the
+    // account's last snapshot and label it as such, so a consumer never mistakes
+    // a carried-over reading for a fresh one.
+    publishLimitHeaders(ctx, {
+        upstreamHeaders: response.headers,
+        quota: quota ?? accountState.quota ?? null,
+        source: quota ? "live" : accountState.quota ? "snapshot" : "none",
+        account,
+        accountState,
+        servedBy: "anthropic",
+        attempt: attemptNumber,
+        ...(poolAccounts ? { poolAccounts } : {}),
+    });
     if (body.stream) {
         return handleAnthropicStreamingSuccessResponse({
             ctx,
@@ -2506,7 +2606,7 @@ async function handleAnthropicSuccessfulResponse(args) {
     });
 }
 async function handleAnthropicStreamingSuccessResponse(args) {
-    const { account, accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, } = args;
+    const { ctx, account, accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, } = args;
     if (!response.body) {
         recordAttemptError(account.label, account.type, 502);
         logAttempt(502, "stream_error", "No response body from upstream");
@@ -2703,6 +2803,7 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         },
     });
     const { response: result, telemetryDone } = attachAnthropicSuccessStreamTelemetry({
+        ctx,
         account,
         response,
         responseHeaders,
@@ -2742,7 +2843,7 @@ function recordCommittedAnthropicStreamAttemptFailure(outcome, account) {
     }
 }
 function attachAnthropicSuccessStreamTelemetry(args) {
-    const { account, response, responseHeaders, remainingStream, streamOutcome, tracer, requestStartTime, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { ctx, account, response, responseHeaders, remainingStream, streamOutcome, tracer, requestStartTime, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
     const { stream: clientCaptureStream, capture: clientCapture } = createRawStreamCapture();
     let streamSource = remainingStream;
     let telemetryDone;
@@ -2952,23 +3053,18 @@ function attachAnthropicSuccessStreamTelemetry(args) {
         }
     }
     const clientStream = streamSource.pipeThrough(clientCaptureStream);
+    // Limit headers published on the context are applied here rather than left
+    // to the runtime wrapper: this Response goes straight to the client on every
+    // mount (proxy runtime and the generic server adapters alike), so the
+    // streaming path has to carry them itself. The previous five-name allowlist
+    // forwarded only the legacy counters and dropped the unified subscription
+    // windows entirely.
     const clientResponseHeaders = {
+        ...(ctx.responseHeaders ?? {}),
         "content-type": "text/event-stream",
         "cache-control": "no-cache",
         connection: "keep-alive",
     };
-    for (const headerName of [
-        "retry-after",
-        "anthropic-ratelimit-requests-remaining",
-        "anthropic-ratelimit-requests-limit",
-        "anthropic-ratelimit-tokens-remaining",
-        "anthropic-ratelimit-tokens-limit",
-    ]) {
-        const value = response.headers.get(headerName);
-        if (value) {
-            clientResponseHeaders[headerName] = value;
-        }
-    }
     return {
         response: new Response(clientStream, {
             status: response.status,
@@ -4612,6 +4708,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                     logProxyBody,
                     logFinalRequest,
                     onStreamTerminal: admissionLease.release,
+                    poolAccounts: enabledAccounts,
                 });
                 if ("retryNextAccount" in successResult) {
                     if (successResult.failure) {
@@ -4674,6 +4771,24 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         }
         loopState.fallbackFailureMessage = fallbackFailureMessage;
     }
+    // Terminal failure — usually "every account is rate-limited". This is the
+    // response a caller most needs limit data on, and historically the one that
+    // carried none. No single account served it, so report the account we would
+    // have tried first plus pool headroom, explicitly marked as a snapshot.
+    {
+        const primary = orderedAccounts[0];
+        const primaryState = primary
+            ? accountRuntimeState.get(primary.key)
+            : undefined;
+        publishLimitHeaders(ctx, {
+            quota: primaryState?.quota ?? null,
+            source: primaryState?.quota ? "snapshot" : "none",
+            ...(primary ? { account: primary } : {}),
+            ...(primaryState ? { accountState: primaryState } : {}),
+            attempt: loopState.attemptNumber,
+            poolAccounts: enabledAccounts,
+        });
+    }
     return buildClaudeAnthropicFailureResponse({
         tracer,
         requestStartTime,

package/dist/lib/types/analytics.d.ts

@@ -3,6 +3,7 @@
  * Comprehensive usage tracking, performance metrics, and cost analysis types
  */
 import type { JsonValue, UnknownRecord } from "./common.js";
+import type { ClaudeLimitSnapshot } from "./subscription.js";
 /**
  * Token usage information (consolidated from multiple sources)
  */
@@ -45,6 +46,13 @@ export type AnalyticsData = {
     elapsedMs?: number;
     /** Verbatim provider finish/stop reason for the terminal model call. */
     rawFinishReason?: string;
+    /**
+     * Account limit state observed on this request — subscription window
+     * headroom, reset times, and (via the NeuroLink Claude proxy) which account
+     * served it and how much the pool has left. Present for Anthropic traffic
+     * whose response carried rate-limit headers.
+     */
+    limits?: ClaudeLimitSnapshot;
 };
 /**
  * Stream Analytics Data - Enhanced for performance tracking

package/dist/lib/types/generate.d.ts

@@ -3,6 +3,7 @@ import type { RAGConfig } from "./rag.js";
 import type { KnowledgeGroundingMetadata, KnowledgeRequestScope } from "./knowledge.js";
 import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, TokenUsage } from "./analytics.js";
+import type { ClaudeLimitSnapshot } from "./subscription.js";
 import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
@@ -963,6 +964,17 @@ export type GenerateResult = {
             message: string;
         }>;
     };
+    /**
+     * Account limit state for this request, parsed from Anthropic's
+     * `anthropic-ratelimit-*` response headers (plus the NeuroLink Claude
+     * proxy's `x-neurolink-*` additions when routed through it).
+     *
+     * Subscription windows report utilization, so headroom is a percentage
+     * (`sessionLeftPct`) rather than an absolute count — Anthropic publishes no
+     * remaining message or token figure for them. API-key accounts do carry
+     * absolute `requestsRemaining` / `tokensRemaining`.
+     */
+    limits?: ClaudeLimitSnapshot;
 };
 /**
  * Unified options for both generation and streaming

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

@@ -944,6 +944,49 @@ export type AccountQuota = {
     /** Epoch ms when we last captured this data */
     lastUpdated: number;
 };
+/**
+ * Provenance of the quota numbers attached to a single proxy response.
+ *  - "live"     : parsed from THIS upstream response's headers.
+ *  - "snapshot" : the last known snapshot for the serving account; the upstream
+ *                 response carried no quota headers.
+ *  - "none"     : no Anthropic account served this request (fallback provider,
+ *                 or a failure before any account was reached).
+ *
+ * Consumers must not treat "snapshot" as current. Without this distinction a
+ * stale reading is indistinguishable from a fresh one.
+ */
+export type ProxyQuotaSource = "live" | "snapshot" | "none";
+/** Aggregate account-pool headroom at the moment a response was produced. */
+export type ProxyPoolHeadroom = {
+    /** Accounts eligible to serve a request right now (not cooling/disabled). */
+    available: number;
+    /** Accounts currently in a cooldown window. */
+    cooling: number;
+    /** Best session headroom across available accounts, as a percentage 0-100.
+     *  Undefined when no available account has a quota snapshot. */
+    bestSessionLeftPct?: number;
+};
+/**
+ * Everything the proxy knows about limits and routing for one response.
+ * Consumed by `buildQuotaResponseHeaders` — kept as data (not headers) so the
+ * assembly stays pure and testable.
+ */
+export type ProxyQuotaHeaderContext = {
+    quota: AccountQuota | null;
+    source: ProxyQuotaSource;
+    /** Account label that served the request; omitted for fallback/no-account. */
+    accountLabel?: string;
+    accountType?: string;
+    /** Which upstream actually produced the response ("anthropic" or a fallback
+     *  provider name). Lets a consumer avoid attributing quota to the wrong one. */
+    servedBy?: string;
+    /** 1-based attempt index within the routing loop. */
+    attempt?: number;
+    /** Epoch ms until which the serving account is cooling, when applicable. */
+    coolingUntil?: number;
+    coolingReason?: AccountCoolingReason;
+    pool?: ProxyPoolHeadroom;
+};
 /** Why an account is currently cooling. Drives cooldown duration and logging.
  *  - "weekly"    : 7d unified limit rejected — cool until the weekly reset.
  *  - "session"   : 5h unified limit rejected — cool until the session reset.
@@ -1246,6 +1289,8 @@ export type ProxyLifecycleLoggerSnapshot = {
     invalidDrops: number;
     writeDrops: number;
     writeFailures: number;
+    /** Events requeued after a transient lifecycle metadata write failure. */
+    writeRetries: number;
     pending: number;
     inFlight: number;
     flushing: boolean;
@@ -1257,12 +1302,15 @@ export type ProxyLifecycleLoggerOptions = {
     queueCapacity?: number;
     batchSize?: number;
     flushIntervalMs?: number;
+    /** Bounded retries for a metadata batch that cannot be appended immediately. */
+    maxWriteRetries?: number;
 };
 /** Serialized lifecycle line awaiting a bounded batch write. */
 export type QueuedProxyLifecycleEvent = {
     logDir: string;
     date: string;
     record: Record<string, unknown>;
+    writeRetries: number;
 };
 /** Percentile summary used by offline proxy log analysis. */
 export type ProxyLatencySummary = {
@@ -2167,6 +2215,8 @@ export type StatusStats = {
     terminalErrorDetailsComparable?: boolean;
     terminalErrorDetailsMissing?: number;
     terminalErrorDetailsExcess?: number;
+    /** Whether this status response reconciled shared state or used local memory. */
+    snapshotSource?: "reconciled" | "memory";
     accounts?: {
         label: string;
         type: string;