@juspay/neurolink 10.9.1 → 10.10.0

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.

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

@@ -87,6 +87,83 @@ export type AnthropicRateLimitInfo = {
      * Retry-After header value in seconds (present on 429 responses)
      */
     retryAfter?: number;
+    /**
+     * Subscription (OAuth) window utilization, 0.0-1.0 of capacity USED, from
+     * `anthropic-ratelimit-unified-5h-utilization`.
+     *
+     * Anthropic publishes utilization for subscription windows, never an
+     * absolute remaining count — there is no message or token figure to report.
+     * `sessionLeftPct` below is the derived "how much is left".
+     */
+    sessionUtilization?: number;
+    /** "allowed" | "throttled" | "rejected" for the 5h window. */
+    sessionStatus?: string;
+    /** Unix epoch seconds at which the 5h window resets. */
+    sessionResetAt?: number;
+    /** Whole-percent capacity remaining in the 5h window (100 - utilization). */
+    sessionLeftPct?: number;
+    /** 7d window utilization, 0.0-1.0 of capacity USED. */
+    weeklyUtilization?: number;
+    weeklyStatus?: string;
+    weeklyResetAt?: number;
+    weeklyLeftPct?: number;
+    /** Authoritative top-level unified status; can be "rejected" even while both
+     *  sub-windows still report "allowed". */
+    unifiedStatus?: string;
+    /** Whether overage is permitted once a window is exhausted. */
+    overageStatus?: string;
+};
+/**
+ * Per-request limit snapshot as observed by the Anthropic provider.
+ *
+ * Assembled from response headers on every request — whether the provider is
+ * talking directly to Anthropic (both auth methods) or through the NeuroLink
+ * Claude proxy. The `account`/`pool`/`servedBy` fields are populated only by
+ * the proxy, which is the only party that knows them.
+ */
+export type ClaudeLimitSnapshot = {
+    /** Rate-limit figures parsed from `anthropic-ratelimit-*` headers. */
+    rateLimit: AnthropicRateLimitInfo;
+    /**
+     * Provenance of the quota numbers. "snapshot" means the proxy reported a
+     * previously captured reading rather than one from this response; "none"
+     * means no Anthropic account served the request (e.g. a fallback provider).
+     * Absent when talking directly to Anthropic, where any figures are live.
+     */
+    quotaSource?: "live" | "snapshot" | "none";
+    /** Proxy account label that served the request. */
+    account?: string;
+    /** "oauth" | "api_key" | "passthrough". */
+    accountType?: string;
+    /** Upstream that produced the response — "anthropic" or a fallback provider. */
+    servedBy?: string;
+    /** Epoch ms until which the serving account is cooling. */
+    accountCoolingUntil?: number;
+    accountCoolingReason?: string;
+    /** Proxy account-pool headroom at response time. */
+    pool?: {
+        available?: number;
+        cooling?: number;
+        bestSessionLeftPct?: number;
+    };
+    /** Anthropic request id, for correlating with provider-side logs. */
+    requestId?: string;
+    /** HTTP status of the response the snapshot came from. */
+    status?: number;
+    /** Epoch ms when this snapshot was captured. */
+    capturedAt: number;
+};
+/**
+ * Per-request capture slot the Anthropic fetch wrapper writes into.
+ *
+ * Held in AsyncLocalStorage for the duration of a generate/stream call, so
+ * concurrent calls on one provider instance cannot see each other's limits.
+ * `headers` keeps the raw response header bag so the AI-SDK model adapter can
+ * report real response headers.
+ */
+export type ClaudeLimitCaptureSlot = {
+    snapshot?: ClaudeLimitSnapshot;
+    headers?: Record<string, string>;
 };
 /**
  * Response metadata including rate limit information

package/dist/providers/anthropic/client.d.ts

@@ -1,6 +1,6 @@
 import { type AIProviderName } from "../../constants/enums.js";
 import { BaseProvider } from "../../core/baseProvider.js";
-import type { AnthropicProviderConfig, StreamOptions, StreamResult, ValidationSchema, EnhancedGenerateResult, TextGenerationOptions, AnthropicAuthMethod, AnthropicResponseMetadata, ClaudeSubscriptionTier, ClaudeUsageInfo } from "../../types/index.js";
+import type { AnthropicProviderConfig, StreamOptions, StreamResult, ValidationSchema, EnhancedGenerateResult, TextGenerationOptions, AnthropicAuthMethod, AnthropicRateLimitInfo, AnthropicResponseMetadata, ClaudeSubscriptionTier, ClaudeUsageInfo } from "../../types/index.js";
 import type { LanguageModel } from "../../types/index.js";
 /**
  * Anthropic Provider v2 - BaseProvider Implementation
@@ -103,12 +103,18 @@ export declare class AnthropicProvider extends BaseProvider {
      */
     getLastResponseMetadata(): AnthropicResponseMetadata | null;
     /**
-     * Update response metadata from API response headers.
-     * This should be called after each API request to track rate limits.
-     * @param headers - Response headers from the API
-     * @param requestId - Optional request ID
+     * Update response metadata from a captured limit snapshot.
+     *
+     * Takes already-parsed rate-limit info rather than raw headers: parsing now
+     * lives in `rateLimitCapture`, which is the only layer that sees the raw
+     * response and understands both header families (unified subscription
+     * windows and legacy per-tier counters).
+     *
+     * @param rateLimit - Parsed rate-limit figures
+     * @param requestId - Optional Anthropic request ID
+     * @param usageUpdate - Optional token counts to fold into usage tracking
      */
-    protected updateResponseMetadata(headers: Headers | Record<string, string>, requestId?: string, usageUpdate?: {
+    protected updateResponseMetadata(rateLimit: AnthropicRateLimitInfo, requestId?: string, usageUpdate?: {
         inputTokens?: number;
         outputTokens?: number;
     }): void;
@@ -127,7 +133,16 @@ export declare class AnthropicProvider extends BaseProvider {
      * BaseProvider so that expired tokens are renewed automatically.
      */
     generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
-    protected executeStream(options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    /**
+     * Fold a captured snapshot into the provider's usage bookkeeping and log it.
+     *
+     * `updateResponseMetadata` had no callers before this — the metadata it
+     * maintains, and the public `getLastResponseMetadata()` / `getUsageInfo()`
+     * that read it, were never populated by anything.
+     */
+    private recordLimitSnapshot;
+    protected executeStream(options: StreamOptions, analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    private executeStreamInCaptureScope;
     isAvailable(): Promise<boolean>;
     getModel(): LanguageModel;
 }