@juspay/neurolink 10.9.0 → 10.10.0

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;
 }

package/dist/providers/anthropic/client.js

@@ -11,6 +11,7 @@ import { streamAnalyticsCollector } from "../../core/streamAnalytics.js";
 import { getModelCapabilities, getRecommendedModelForTier, isModelAvailableForTier, } from "../../models/anthropicModels.js";
 import { createOAuthFetch } from "../../proxy/oauthFetch.js";
 import { createProxyFetch } from "../../proxy/proxyFetch.js";
+import { getCapturedLimitSnapshot, getCapturedResponseHeaders, logClaudeLimitSnapshot, runInLimitCaptureScope, setLimitSpanAttributes, withLimitCapture, wrapFetchWithLimitCapture, } from "./rateLimitCapture.js";
 import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { logger } from "../../utils/logger.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
@@ -166,35 +167,10 @@ const detectAuthMethod = (oauthToken) => {
     });
     return method;
 };
-/**
- * Parse rate limit information from Anthropic API response headers.
- * @param headers - Response headers from Anthropic API
- * @returns Parsed rate limit information
- */
-const parseRateLimitHeaders = (headers) => {
-    const getHeader = (name) => {
-        if (headers instanceof Headers) {
-            return headers.get(name);
-        }
-        return headers[name] || headers[name.toLowerCase()] || null;
-    };
-    const parseNumber = (value) => {
-        if (!value) {
-            return undefined;
-        }
-        const num = parseInt(value, 10);
-        return isNaN(num) ? undefined : num;
-    };
-    return {
-        requestsLimit: parseNumber(getHeader("anthropic-ratelimit-requests-limit")),
-        requestsRemaining: parseNumber(getHeader("anthropic-ratelimit-requests-remaining")),
-        requestsReset: getHeader("anthropic-ratelimit-requests-reset") || undefined,
-        tokensLimit: parseNumber(getHeader("anthropic-ratelimit-tokens-limit")),
-        tokensRemaining: parseNumber(getHeader("anthropic-ratelimit-tokens-remaining")),
-        tokensReset: getHeader("anthropic-ratelimit-tokens-reset") || undefined,
-        retryAfter: parseNumber(getHeader("retry-after")),
-    };
-};
+// Rate-limit header parsing lives in `rateLimitCapture.ts`, which sees the raw
+// fetch Response and understands both header families (unified subscription
+// windows and the legacy per-tier counters). The module-private copy that used
+// to sit here parsed only the legacy family and had no callers.
 // ───────────────────────────────────────────────────────────────────────────
 // Native Messages-API conversion helpers (NeuroLink/V3 shapes → Anthropic)
 // ───────────────────────────────────────────────────────────────────────────
@@ -590,7 +566,10 @@ export class AnthropicProvider extends BaseProvider {
             client = new Anthropic({
                 apiKey: "oauth-authenticated", // Placeholder, actual auth is in fetch wrapper
                 // Note: No headers passed - fetch wrapper sets oauth-2025-04-20 beta header
-                fetch: oauthFetch,
+                // Limit capture wraps the OAuth fetch so subscription quota headers
+                // (anthropic-ratelimit-unified-*) are recorded on every request —
+                // streaming and non-streaming alike.
+                fetch: wrapFetchWithLimitCapture(oauthFetch),
                 timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
                 // The SDK's built-in retry honors Retry-After hints without any
                 // upper bound (a 429 with retry-after: 8549 sleeps 2.4h per retry,
@@ -642,7 +621,10 @@ export class AnthropicProvider extends BaseProvider {
                 apiKey: apiKeyToUse,
                 defaultHeaders: headers,
                 ...(normalizedBaseURL && { baseURL: normalizedBaseURL }),
-                fetch: createProxyFetch(),
+                // Same capture as the OAuth branch: works for direct API-key traffic
+                // (legacy requests/tokens counters) and for the NeuroLink Claude proxy
+                // (verbatim unified quota plus x-neurolink-* account/pool state).
+                fetch: wrapFetchWithLimitCapture(createProxyFetch()),
                 timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
                 // See the OAuth-path client above: unbounded Retry-After sleeps in
                 // the SDK's retry loop must never stall fallback orchestration.
@@ -971,24 +953,22 @@ export class AnthropicProvider extends BaseProvider {
         return this.lastResponseMetadata;
     }
     /**
-     * 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
      */
-    updateResponseMetadata(headers, requestId, usageUpdate) {
+    updateResponseMetadata(rateLimit, requestId, usageUpdate) {
         this.lastResponseMetadata = {
-            rateLimit: parseRateLimitHeaders(headers),
-            requestId: requestId ||
-                (headers instanceof Headers
-                    ? headers.get("x-request-id") || undefined
-                    : headers["x-request-id"]),
-            serverTiming: headers instanceof Headers
-                ? headers.get("server-timing") || undefined
-                : headers["server-timing"],
+            rateLimit,
+            ...(requestId ? { requestId } : {}),
         };
-        // Update usage tracking
-        const rateLimit = this.lastResponseMetadata.rateLimit;
         if (this.usageInfo) {
             this.usageInfo.requestCount++;
             this.usageInfo.messagesUsed++;
@@ -1254,7 +1234,10 @@ export class AnthropicProvider extends BaseProvider {
                     response: {
                         id: response.id,
                         modelId: response.model,
-                        headers: {},
+                        // Real response headers, captured by the fetch wrapper. This used
+                        // to be a hardcoded `{}`, which silently discarded every
+                        // rate-limit and quota header Anthropic returns.
+                        headers: getCapturedResponseHeaders() ?? {},
                         body: response,
                     },
                 };
@@ -1305,9 +1288,41 @@ export class AnthropicProvider extends BaseProvider {
      */
     async generate(optionsOrPrompt, analysisSchema) {
         await this.refreshAuthIfNeeded();
-        return super.generate(optionsOrPrompt, analysisSchema);
+        // Open a per-request capture scope around the whole turn. Scoping here
+        // rather than on the instance is what makes it concurrency-safe: several
+        // generate() calls can be in flight on one provider instance, and an
+        // instance field would attribute one call's limits to another.
+        const { result, snapshot } = await withLimitCapture(() => super.generate(optionsOrPrompt, analysisSchema));
+        if (result && snapshot) {
+            this.recordLimitSnapshot(snapshot);
+            result.limits = snapshot;
+            if (result.analytics) {
+                result.analytics.limits = snapshot;
+            }
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    recordLimitSnapshot(snapshot) {
+        this.updateResponseMetadata(snapshot.rateLimit, snapshot.requestId);
+        setLimitSpanAttributes(snapshot);
+        logClaudeLimitSnapshot(snapshot, this.modelName);
+    }
+    async executeStream(options, analysisSchema) {
+        // The capture scope must outlive this call: the SSE loop keeps running in
+        // the background after executeStream returns, and its per-step HTTP
+        // requests are what carry the limit headers. AsyncLocalStorage.run
+        // propagates into every continuation started inside, so the whole stream
+        // lifetime shares one slot.
+        return runInLimitCaptureScope(() => this.executeStreamInCaptureScope(options, analysisSchema));
     }
-    async executeStream(options, _analysisSchema) {
+    async executeStreamInCaptureScope(options, _analysisSchema) {
         // Refresh OAuth token if needed before making any API request.
         await this.refreshAuthIfNeeded();
         this.validateStreamOptions(options);
@@ -1758,15 +1773,25 @@ export class AnthropicProvider extends BaseProvider {
             // stream consumers and session cost tracking saw no usage at all.
             // Chained off finishPromise so requestDuration reflects the DRAINED
             // stream, not the milliseconds it took to construct this result object.
-            analytics: finishPromise.then(() => streamAnalyticsCollector.createAnalytics(this.providerName, modelId, {
-                textStream: (async function* () { })(),
-                usage: usagePromise,
-                finishReason: finishPromise,
-            }, Date.now() - streamStartTime, {
-                requestId: options.requestId ??
-                    `${this.providerName}-stream-${Date.now()}`,
-                streamingMode: true,
-            })),
+            analytics: finishPromise.then(async () => {
+                const analytics = await streamAnalyticsCollector.createAnalytics(this.providerName, modelId, {
+                    textStream: (async function* () { })(),
+                    usage: usagePromise,
+                    finishReason: finishPromise,
+                }, Date.now() - streamStartTime, {
+                    requestId: options.requestId ??
+                        `${this.providerName}-stream-${Date.now()}`,
+                    streamingMode: true,
+                });
+                // Still inside the capture scope opened by executeStream, so this sees
+                // the limits reported by the last upstream step of the stream.
+                const snapshot = getCapturedLimitSnapshot();
+                if (snapshot && analytics) {
+                    this.recordLimitSnapshot(snapshot);
+                    analytics.limits = snapshot;
+                }
+                return analytics;
+            }),
         };
     }
     async isAvailable() {

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

@@ -0,0 +1,82 @@
+/**
+ * Anthropic rate-limit / quota header capture.
+ *
+ * Anthropic returns limit state on the response headers of every request:
+ * `anthropic-ratelimit-unified-*` for subscription (OAuth) accounts,
+ * `anthropic-ratelimit-{requests,tokens}-*` for API-key accounts. The NeuroLink
+ * Claude proxy forwards those verbatim and adds `x-neurolink-*` for what only
+ * it knows (which account served the request, pool headroom, whether the
+ * numbers are live or a carried-over snapshot).
+ *
+ * None of it used to reach the SDK: `doGenerate` returned a hardcoded empty
+ * header bag and the streaming loop never looked. The capture point here is the
+ * `fetch` the Anthropic SDK is constructed with — it is invoked exactly once
+ * per HTTP request on BOTH the streaming and non-streaming paths, so a single
+ * wrapper covers everything without touching the SSE loop or switching the
+ * non-streaming call to `.withResponse()`.
+ *
+ * Scoping is per-request via AsyncLocalStorage rather than a field on the
+ * provider: a provider instance is shared across concurrent calls, so an
+ * instance field would race and attribute one request's limits to another.
+ *
+ * @module providers/anthropic/rateLimitCapture
+ */
+import type { AnthropicRateLimitInfo, ClaudeLimitSnapshot } from "../../types/index.js";
+/**
+ * Parse both Anthropic rate-limit header families into a single shape.
+ *
+ * Which family is present depends on the account type, so every field is
+ * optional and absence is normal rather than an error.
+ */
+export declare function parseAnthropicLimitHeaders(headers: Headers): AnthropicRateLimitInfo;
+/**
+ * Build a snapshot from a response, or undefined when the response carries
+ * neither Anthropic rate-limit headers nor NeuroLink proxy metadata.
+ */
+export declare function buildLimitSnapshot(headers: Headers, status: number, now?: number): ClaudeLimitSnapshot | undefined;
+/**
+ * Wrap a fetch so every response's limit headers are captured into the
+ * enclosing `withLimitCapture` scope. A no-op outside such a scope.
+ *
+ * Capture never alters the response and never throws — a parsing failure must
+ * not be able to break a request that the provider would otherwise complete.
+ */
+export declare function wrapFetchWithLimitCapture(inner: typeof fetch): typeof fetch;
+/**
+ * Run `body` in a capture scope and return its result alongside whatever limit
+ * snapshot the underlying HTTP request(s) produced.
+ */
+export declare function withLimitCapture<T>(body: () => Promise<T>): Promise<{
+    result: T;
+    snapshot?: ClaudeLimitSnapshot;
+}>;
+/**
+ * Current scope's snapshot, if any. Lets a long-running loop (the streaming
+ * path) read limits mid-flight without unwinding the scope.
+ */
+export declare function getCapturedLimitSnapshot(): ClaudeLimitSnapshot | undefined;
+/** Raw headers of the most recent captured response in this scope. */
+export declare function getCapturedResponseHeaders(): Record<string, string> | undefined;
+/** Enter a capture scope without wrapping a single call — for streaming, where
+ *  the scope must outlive the function that opened it. */
+export declare function runInLimitCaptureScope<T>(body: () => T): T;
+/**
+ * Attach limit state to the currently active OTel span.
+ *
+ * Uses the active span rather than threading one down from the generation
+ * layer: that layer is provider-agnostic and should not learn about Anthropic
+ * quota headers just to record them. The active span during a turn is the one
+ * already carrying `gen_ai.usage.*` and `neurolink.cost`, so "what did this
+ * cost" and "how much is left" answer from the same trace.
+ */
+export declare function setLimitSpanAttributes(snapshot: ClaudeLimitSnapshot): void;
+/**
+ * Emit one structured line per request describing remaining capacity.
+ *
+ * Leads with headroom ("how much is left") because that is the figure an
+ * operator acts on; the raw utilization stays available on the snapshot for
+ * anything computing against it. Escalates to WARN when the session window is
+ * nearly spent or the provider has already flagged the account as
+ * throttled/rejected.
+ */
+export declare function logClaudeLimitSnapshot(snapshot: ClaudeLimitSnapshot, model?: string, now?: number): void;