@juspay/neurolink 11.24.1 → 11.25.0

package/dist/core/baseProvider.js

@@ -247,8 +247,14 @@ export class BaseProvider {
             return this.wrapStreamWithLifecycleCallbacks(realStreamResult, options);
         }
         catch (realStreamError) {
-            // Don't retry on terminal/abort errors — only fall back for
-            // "real streaming with tools is unsupported" style failures.
+            // The fallback is BROAD, not narrow: only the terminal errors listed
+            // below (abort, timeout, 401/403, quota, rate limit, authentication)
+            // re-throw. Every other failure — including a genuine configuration or
+            // programming error — is masked as a degraded fake stream whenever
+            // tools are enabled. Narrowing this to "streaming with tools is
+            // unsupported" failures would change behaviour for every provider at
+            // once, so it needs its own characterization PR first; until then this
+            // comment records what the code does, not what a narrower design would.
             const errMsg = realStreamError instanceof Error
                 ? realStreamError.message
                 : String(realStreamError);

package/dist/neurolink.js

@@ -7354,7 +7354,17 @@ Current user's request: ${currentInput}`;
                     // Reviewer follow-up: fire fallback when no *non-sentinel*
                     // output was produced — sentinel-only and truly empty streams
                     // both qualify, but media-only streams (audio/image) do not.
+                    //
+                    // fallbackOnMaxSteps: false exempts one no-output shape — a turn
+                    // the provider reports as ended at the caller's own maxSteps bound
+                    // (metadata.stopReason "step-cap", a mutable reference the native
+                    // loops fill by drain time). That bound is the caller's budget,
+                    // not a provider failure, and retrying it on another provider
+                    // spends that provider's tokens to exceed a budget the caller set.
+                    const cappedByCallerBudget = enhancedOptions.fallbackOnMaxSteps === false &&
+                        providerStreamMetadata?.stopReason === "step-cap";
                     if (realOutputChunks === 0 &&
+                        !cappedByCallerBudget &&
                         !metadata.fallbackAttempted &&
                         !enhancedOptions.disableInternalFallback &&
                         streamState.toolCalls.length === 0 &&

package/dist/providers/anthropic/client.js

@@ -1455,6 +1455,13 @@ export class AnthropicProvider extends BaseProvider {
         const client = this.client;
         const toolsUsed = [];
         const streamStartTime = Date.now();
+        // Mutable-reference contract from StreamResult.metadata: created before
+        // the loop and filled once the turn drains, because wrapper spreads
+        // snapshot top-level result fields before the loop resolves. This is how
+        // the Gemini/Vertex native paths already report their resolved outcome;
+        // without it a consumer (e.g. the SDK's no-output fallback gate) cannot
+        // tell a step-capped turn from a failed one.
+        const turnMetadata = {};
         // Hoisted out of runLoop so the error path can resolve the usage
         // accumulated by steps that completed BEFORE the failure — those steps
         // were billed and must not be reported as zero.
@@ -1738,6 +1745,20 @@ export class AnthropicProvider extends BaseProvider {
             totalCacheRead += result.usage.cacheReadTokens ?? 0;
             totalCacheWrite += result.usage.cacheWriteTokens ?? 0;
             lastStop = result.rawStopReason ?? lastStop;
+            turnMetadata.finishReason = result.finishReason;
+            if (result.rawStopReason) {
+                turnMetadata.rawFinishReason = result.rawStopReason;
+            }
+            // "tool-calls" after a drained turn means the model still wanted tools
+            // when the step budget ran out — the engine breaks at maxSteps, and a
+            // model turn that finished normally maps to "stop". The one other
+            // producer of stop_reason "tool_use" at turn end is a final_result
+            // call (structured output), which `finalResultText` identifies, so it
+            // must not read as a capped turn.
+            if (result.finishReason === "tool-calls" &&
+                finalResultText === undefined) {
+                turnMetadata.stopReason = "step-cap";
+            }
             resolveUsage(buildDeferredUsage());
             resolveFinish(lastStop ?? "stop");
         };
@@ -1822,6 +1843,7 @@ export class AnthropicProvider extends BaseProvider {
             model: this.modelName,
             toolCalls: [],
             toolResults: [],
+            metadata: turnMetadata,
             // Wire the deferred usage/finish promises into the analytics collector
             // (mirrors openaiChatCompletionsBase). Without this the loop computed a
             // fully correct aggregate that was consumed only by the OTel span —

package/dist/providers/googleVertex/client.js

@@ -3337,6 +3337,55 @@ export class GoogleVertexProvider extends BaseProvider {
             const contextGuard = createContextGuard(getContextWindowSize("vertex", modelName));
             const failedTools = new Map();
             try {
+                // Restores the per-tool observation the hand-rolled dispatch had.
+                // The execution runs INSIDE the span's context so spans the tool opens
+                // itself nest under this call rather than dangling beside the turn, and
+                // the settled RESULT is inspected — an MCP tool reports failure in its
+                // payload, so an observation that only watches for throws records a
+                // failed call as successful.
+                //
+                // Stream path only: the generate twin never had per-tool spans, and
+                // giving it them here would be behaviour GAINED under cover of a
+                // migration. Shared with resolveToolOnMiss below: the old dispatch
+                // opened the span before the executor lookup, so a tool hydrated
+                // mid-turn was observed exactly like one declared up front.
+                const withToolSpan = (toolCallName, run) => {
+                    const toolSpan = tracers.mcp.startSpan("ai.toolCall", {
+                        kind: SpanKind.INTERNAL,
+                        attributes: {
+                            [LANGFUSE_ATTR.OBSERVATION_TYPE]: "tool",
+                            [ATTR.GEN_AI_TOOL_NAME]: toolCallName,
+                            "ai.toolCall.name": toolCallName,
+                        },
+                    }, turnContext);
+                    const finish = (output, errorMessage) => {
+                        toolSpan.setAttribute("ai.toolCall.result", spanJsonAttribute(output));
+                        toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(output));
+                        if (errorMessage) {
+                            toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_LEVEL, "ERROR");
+                            toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_STATUS_MESSAGE, errorMessage);
+                            toolSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: errorMessage,
+                            });
+                        }
+                        else {
+                            toolSpan.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        toolSpan.end();
+                    };
+                    return otelContext.with(otelTrace.setSpan(turnContext, toolSpan), async () => {
+                        try {
+                            const result = await run();
+                            finish(result, extractMcpToolErrorMessage(result));
+                            return result;
+                        }
+                        catch (error) {
+                            finish({ error: true }, error instanceof Error ? error.message : String(error));
+                            throw error;
+                        }
+                    });
+                };
                 // Executors handed to the engine, taken through the turn's
                 // DedupExecuteMap so an identical repeated call is answered from the
                 // per-turn cache rather than run again (BZ-3327). `.get()` returns the
@@ -3358,53 +3407,7 @@ export class GoogleVertexProvider extends BaseProvider {
                             toolTimeoutMs: toolExecTimeoutMs,
                             abortSignal: internalAbort.signal,
                             onProgress: () => turnClock.noteProgress(),
-                            // Restores the per-tool observation the hand-rolled dispatch had.
-                            // The execution runs INSIDE the span's context so spans the tool opens
-                            // itself nest under this call rather than dangling beside the turn, and
-                            // the settled RESULT is inspected — an MCP tool reports failure in its
-                            // payload, so an observation that only watches for throws records a
-                            // failed call as successful.
-                            //
-                            // Stream path only: the generate twin never had per-tool spans, and
-                            // giving it them here would be behaviour GAINED under cover of a
-                            // migration.
-                            withToolSpan: (toolCallName, run) => {
-                                const toolSpan = tracers.mcp.startSpan("ai.toolCall", {
-                                    kind: SpanKind.INTERNAL,
-                                    attributes: {
-                                        [LANGFUSE_ATTR.OBSERVATION_TYPE]: "tool",
-                                        [ATTR.GEN_AI_TOOL_NAME]: toolCallName,
-                                        "ai.toolCall.name": toolCallName,
-                                    },
-                                }, turnContext);
-                                const finish = (output, errorMessage) => {
-                                    toolSpan.setAttribute("ai.toolCall.result", spanJsonAttribute(output));
-                                    toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(output));
-                                    if (errorMessage) {
-                                        toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_LEVEL, "ERROR");
-                                        toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_STATUS_MESSAGE, errorMessage);
-                                        toolSpan.setStatus({
-                                            code: SpanStatusCode.ERROR,
-                                            message: errorMessage,
-                                        });
-                                    }
-                                    else {
-                                        toolSpan.setStatus({ code: SpanStatusCode.OK });
-                                    }
-                                    toolSpan.end();
-                                };
-                                return otelContext.with(otelTrace.setSpan(turnContext, toolSpan), async () => {
-                                    try {
-                                        const result = await run();
-                                        finish(result, extractMcpToolErrorMessage(result));
-                                        return result;
-                                    }
-                                    catch (error) {
-                                        finish({ error: true }, error instanceof Error ? error.message : String(error));
-                                        throw error;
-                                    }
-                                });
-                            },
+                            withToolSpan,
                         }),
                     };
                 }
@@ -3538,6 +3541,10 @@ export class GoogleVertexProvider extends BaseProvider {
                                 toolTimeoutMs: toolExecTimeoutMs,
                                 abortSignal: internalAbort.signal,
                                 onProgress: () => turnClock.noteProgress(),
+                                // Same observation as an up-front executor: the hand-rolled
+                                // dispatch spanned at the call, after the executor lookup, so
+                                // a hydrated tool was never the one unobserved call in a turn.
+                                withToolSpan,
                             }),
                         };
                     },

package/dist/types/stream.d.ts

@@ -409,6 +409,17 @@ export type StreamOptions = {
      * Used by the Claude proxy so the proxy itself can own fallback order.
      */
     disableInternalFallback?: boolean;
+    /**
+     * Whether a turn that ended at the caller's own `maxSteps` bound may still
+     * trigger the internal no-output provider fallback. Reaching `maxSteps` is
+     * a budget the caller set, not a provider failure, but such a turn can end
+     * with no text output and would otherwise be retried on a different
+     * provider — spending that provider's tokens because the caller's own
+     * budget ran out. Set `false` to surface the capped turn as-is
+     * (`metadata.stopReason === "step-cap"`). Default (unset/true) preserves
+     * the existing fallback behaviour.
+     */
+    fallbackOnMaxSteps?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.
      * When true, tools are ONLY passed natively via the provider's `tools` parameter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.24.1",
+  "version": "11.25.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {