@juspay/neurolink 10.9.1 → 10.10.1

package/dist/lib/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";
@@ -29,6 +30,7 @@ import { toAnthropicImageBlock, fileToAnthropicBlock, } from "../anthropicImageB
 import { resolveSamplingParams } from "../../models/modelRegistry.js";
 import { createChunkQueue, createDeferredAnalytics, stringifyToolInput, } from "../openaiChatCompletionsClient.js";
 import { ANTHROPIC_BETA_HEADERS } from "./constants.js";
+import { appendFinalResultInstruction, appendFinalResultTool, FINAL_RESULT_TOOL_NAME, stringifyFinalResultInput, } from "./structuredOutput.js";
 // AnthropicProviderConfig is imported from types/providers.ts
 // Re-export for backward compatibility
 // Configuration helpers - now using consolidated utility
@@ -166,35 +168,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 +567,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 +622,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 +954,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++;
@@ -1083,7 +1064,11 @@ export class AnthropicProvider extends BaseProvider {
             supportedUrls: {},
             doGenerate: async (options) => {
                 await refreshAuth();
-                const { system, messages } = messagesToAnthropic(options.prompt);
+                const built = messagesToAnthropic(options.prompt);
+                const messages = built.messages;
+                // `let`: the additive structured-output path below appends the
+                // final_result instruction to the system prompt.
+                let system = built.system;
                 let tools = (options.tools ?? [])
                     .filter((t) => t.type === "function")
                     .map((t) => {
@@ -1127,6 +1112,24 @@ export class AnthropicProvider extends BaseProvider {
                     ];
                     toolChoice = { type: "tool", name: jsonTool };
                 }
+                // Additive structured output: when the caller wants a schema AND real
+                // tools, the forced-json path above cannot be used (it replaces the
+                // tools array), and the AI-SDK experimental_output path is excluded
+                // for this surface by structuredOutputPolicy. GenerationHandler hands
+                // the JSON Schema down here instead, and we APPEND a `final_result`
+                // tool — tool_choice stays auto, so every real tool keeps working and
+                // the model self-selects final_result when it is ready to answer.
+                const finalResultSchema = options.providerOptions?.anthropic
+                    ?.finalResultSchema;
+                let finalResultActive = false;
+                if (!jsonTool && finalResultSchema) {
+                    const appended = appendFinalResultTool(tools, finalResultSchema);
+                    tools = appended.tools;
+                    finalResultActive = appended.applied;
+                    if (appended.applied) {
+                        system = appendFinalResultInstruction(system);
+                    }
+                }
                 // Extended thinking passthrough (providerOptions.anthropic.thinking).
                 const thinking = options.providerOptions?.anthropic?.thinking;
                 // Prompt-cache parity with the native Vertex+Claude path: upstream
@@ -1199,6 +1202,7 @@ export class AnthropicProvider extends BaseProvider {
                     timeoutController?.cleanup();
                 }
                 const content = [];
+                let finalResultText;
                 for (const block of response.content) {
                     if (block.type === "thinking") {
                         content.push({ type: "reasoning", text: block.thinking });
@@ -1218,6 +1222,12 @@ export class AnthropicProvider extends BaseProvider {
                                 text: stringifyToolInput(block.input),
                             });
                         }
+                        else if (finalResultActive &&
+                            block.name === FINAL_RESULT_TOOL_NAME) {
+                            // Internal pattern: never surfaced as a tool call. Its arguments
+                            // ARE the structured answer.
+                            finalResultText = stringifyToolInput(block.input);
+                        }
                         else {
                             content.push({
                                 type: "tool-call",
@@ -1228,12 +1238,29 @@ export class AnthropicProvider extends BaseProvider {
                         }
                     }
                 }
+                // final_result is terminal — parity with the native Claude-on-Vertex
+                // and Gemini loops, which break out of the tool loop the moment it
+                // arrives. Reasoning blocks are kept; any prose preamble and any tool
+                // calls issued alongside it are dropped so `text` is exactly the
+                // structured payload and the AI-SDK loop stops here.
+                if (finalResultText !== undefined) {
+                    const reasoning = content.filter((part) => part.type === "reasoning");
+                    content.length = 0;
+                    content.push(...reasoning, { type: "text", text: finalResultText });
+                    logger.debug("[Anthropic] Extracted structured output from final_result tool (generate)", { chars: finalResultText.length });
+                }
                 const cacheRead = response.usage.cache_read_input_tokens ?? 0;
                 const cacheWrite = response.usage.cache_creation_input_tokens ?? 0;
                 return {
                     content,
                     finishReason: {
-                        unified: mapAnthropicStopReason(response.stop_reason),
+                        // A final_result call ends the turn: the provider reports
+                        // stop_reason "tool_use", but no tool call is surfaced, so
+                        // reporting "tool-calls" would misread as a step-capped turn.
+                        // `raw` still carries the provider's verbatim stop_reason.
+                        unified: finalResultText !== undefined
+                            ? "stop"
+                            : mapAnthropicStopReason(response.stop_reason),
                         raw: response.stop_reason ?? "stop",
                     },
                     usage: {
@@ -1254,7 +1281,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 +1335,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;
     }
-    async executeStream(options, _analysisSchema) {
+    /**
+     * 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 executeStreamInCaptureScope(options, _analysisSchema) {
         // Refresh OAuth token if needed before making any API request.
         await this.refreshAuthIfNeeded();
         this.validateStreamOptions(options);
@@ -1326,6 +1388,9 @@ export class AnthropicProvider extends BaseProvider {
         let anthropicTools;
         let payload;
         let shouldUseTools;
+        // True once the additive `final_result` tool is in the request — the
+        // streaming twin of the doGenerate path above.
+        let finalResultActive = false;
         try {
             // options.tools is pre-merged by BaseProvider.stream() with base tools
             // (MCP/built-in) + user-provided tools (RAG, etc.)
@@ -1340,6 +1405,18 @@ export class AnthropicProvider extends BaseProvider {
             // convert to the Anthropic Messages payload (system + content blocks).
             const built = await this.buildMessagesForStream(options);
             payload = messagesToAnthropic(built);
+            // Schema + tools: append final_result rather than pinning tool_choice to
+            // a json tool, so the real tools stay callable for the whole turn.
+            // Unlike generate, no plumbing is needed — this is a native loop, so the
+            // caller's Zod/JSON schema is right here on the options.
+            if (options.schema && anthropicTools && anthropicTools.length > 0) {
+                const appended = appendFinalResultTool(anthropicTools, convertZodToJsonSchema(options.schema));
+                anthropicTools = appended.tools;
+                finalResultActive = appended.applied;
+                if (appended.applied) {
+                    payload.system = appendFinalResultInstruction(payload.system);
+                }
+            }
         }
         catch (setupErr) {
             timeoutController?.cleanup();
@@ -1424,6 +1501,14 @@ export class AnthropicProvider extends BaseProvider {
             ...(totalCacheRead > 0 ? { cacheReadTokens: totalCacheRead } : {}),
             ...(totalCacheWrite > 0 ? { cacheCreationTokens: totalCacheWrite } : {}),
         });
+        // Structured-output turns are delivered as ONE chunk, not incrementally:
+        // a caller that passed a schema needs parseable JSON, and text deltas
+        // emitted before the model calls final_result would prefix the payload
+        // with prose and break every JSON.parse on the consumer side. Same
+        // contract as the native Vertex loops. Non-schema streams are untouched
+        // and stay fully incremental.
+        let bufferedText = "";
+        let finalResultText;
         const runLoop = async () => {
             const conversation = payload.messages.slice();
             for (let step = 0; step < maxSteps; step++) {
@@ -1517,7 +1602,12 @@ export class AnthropicProvider extends BaseProvider {
                         const delta = event.delta;
                         if (delta.type === "text_delta") {
                             textAcc.set(event.index, (textAcc.get(event.index) ?? "") + delta.text);
-                            pushChunk({ content: delta.text });
+                            if (finalResultActive) {
+                                bufferedText += delta.text;
+                            }
+                            else {
+                                pushChunk({ content: delta.text });
+                            }
                         }
                         else if (delta.type === "thinking_delta") {
                             const acc = thinkingAcc.get(event.index) ?? {
@@ -1553,6 +1643,20 @@ export class AnthropicProvider extends BaseProvider {
                     }
                 }
                 lastStop = stopReason;
+                // final_result is terminal: its arguments ARE the answer, so the turn
+                // ends here and any tool calls issued alongside it are not executed
+                // (parity with the native Vertex loops). It is never executed as a
+                // tool, never recorded in toolsUsed, and never stored as a tool
+                // execution — the pattern stays invisible to callers.
+                if (finalResultActive) {
+                    const finalCall = [...toolAcc.values()].find((acc) => acc.name === FINAL_RESULT_TOOL_NAME);
+                    if (finalCall) {
+                        finalResultText = stringifyFinalResultInput(finalCall.inputJson);
+                        lastStop = "end_turn";
+                        logger.debug("[Anthropic] Extracted structured output from final_result tool (stream)", { chars: finalResultText.length });
+                        break;
+                    }
+                }
                 if (stopReason !== "tool_use" || toolAcc.size === 0) {
                     break;
                 }
@@ -1695,6 +1799,19 @@ export class AnthropicProvider extends BaseProvider {
             throw this.formatProviderError(error);
         })
             .finally(() => {
+            // Deliver the buffered structured-output turn: `finalResultText` when
+            // the model called final_result, otherwise the prose it produced
+            // instead — never nothing, so a model that ignores the instruction
+            // degrades to today's plain-text behaviour rather than an empty
+            // stream. In `finally` so a turn that dies mid-loop still surfaces
+            // the text it had already buffered, exactly as the unbuffered path
+            // surfaces its partial deltas.
+            if (finalResultActive) {
+                const output = finalResultText ?? bufferedText;
+                if (output.length > 0) {
+                    pushChunk({ content: output });
+                }
+            }
             timeoutController?.cleanup();
             pushChunk({ done: true });
         });
@@ -1758,15 +1875,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/lib/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;