@juspay/neurolink 12.41.3 → 12.41.4

package/dist/core/baseProvider.js

@@ -24,7 +24,7 @@ import { sanitizeErrorCause } from "../utils/logSanitize.js";
 import { createAnalytics as buildAnalytics } from "./analytics.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { duckTypedStatusCode, extractRetryAfterMsFromError, } from "../utils/providerRetry.js";
-import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
+import { getLifecycleMiddlewareConfig, hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
 import { interleaveTTSStream } from "../utils/ttsStream.js";
@@ -51,18 +51,6 @@ import { generateOnceNative } from "../utils/nativeSingleShot.js";
 import { validateExecutionControl } from "../utils/parameterValidation.js";
 import { extractTokenUsage } from "../utils/tokenUtils.js";
 import { preserveLiveStreamAccessors } from "../utils/streamResultAccessors.js";
-/**
- * Read the consumer-facing lifecycle callbacks buried inside a request's
- * middleware blob. The parameter is `unknown` on purpose: request options
- * arrive as several structurally-unrelated shapes (StreamOptions,
- * TextGenerationOptions), and the lifecycle branch is an optional add-on
- * none of them declare — a single structural view keeps the read cast-free
- * at every call site.
- */
-function getLifecycleMiddlewareConfig(options) {
-    return options?.middleware
-        ?.middlewareConfig?.lifecycle?.config;
-}
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -819,9 +807,32 @@ export class BaseProvider {
                     yield chunk;
                 }
                 if (onFinish) {
+                    // Read `result.usage` / `result.finishReason` here, after the
+                    // drain loop above has fully exhausted `upstreamIterable` — the
+                    // same point native background-loop providers (Vertex's Gemini3
+                    // and Claude paths) resolve these fields by, whether they are
+                    // plain values set before `result` was returned or live getters
+                    // preserved through `withStreamModelFallback`
+                    // (`preserveLiveStreamAccessors`). Both fields are generic
+                    // `StreamResult` members for every provider, not Vertex-specific,
+                    // so this enrichment is additive for all of them: only present
+                    // when `result` actually carries a value, never a synthesized
+                    // default (a provider that never populated these fields keeps
+                    // getting the exact same bare `{text, duration}` payload as
+                    // before).
+                    const { usage, finishReason } = result;
                     await safeFire(() => onFinish({
                         text: accumulated,
                         duration: Date.now() - startTime,
+                        ...(usage
+                            ? {
+                                usage: {
+                                    promptTokens: usage.input ?? 0,
+                                    completionTokens: usage.output ?? 0,
+                                },
+                            }
+                            : {}),
+                        ...(finishReason ? { finishReason } : {}),
                     }), "onFinish");
                 }
             }

package/dist/middleware/builtin/lifecycle.js

@@ -1,6 +1,6 @@
 import { logger } from "../../utils/logger.js";
 import { isRecoverableError } from "../../utils/errorHandling.js";
-import { fireOnErrorOnce } from "../../utils/lifecycleCallbacks.js";
+import { fireOnErrorOnce, isLifecycleStreamCallbacksOwnedByBaseProvider, } from "../../utils/lifecycleCallbacks.js";
 /**
  * Normalize a thrown value to an `Error` while preserving structured
  * fields (`code`, `status`, `statusCode`, `retryAfter`, `details`,
@@ -88,19 +88,42 @@ export function createLifecycleMiddleware(config = {}) {
                 if (!config.onChunk && !config.onFinish && !config.onError) {
                     return result;
                 }
+                // BaseProvider.wrapStreamWithLifecycleCallbacks already fires
+                // onChunk/onFinish for this exact config object, from NeuroLink's
+                // own normalized stream, for every NeuroLink-internal stream() call
+                // regardless of provider/transport. When that marker is present,
+                // firing onChunk/onFinish here too would deliver each one twice —
+                // once from these raw, provider-shaped V3 chunks, once from
+                // BaseProvider's normalized ones. onError is NOT covered by this
+                // flag: it keeps its own, independent dedup via `fireOnErrorOnce`'s
+                // shared fired-marker below, unchanged.
+                const streamCallbacksOwnedByBaseProvider = isLifecycleStreamCallbacksOwnedByBaseProvider(config);
                 let sequenceNumber = 0;
                 let accumulatedText = "";
                 const transformStream = new TransformStream({
                     transform(chunk, controller) {
                         try {
-                            if (chunk.type === "text-delta") {
-                                accumulatedText += chunk.textDelta;
+                            // V3 stream parts carry the delta on `delta` (see
+                            // LanguageModelV3StreamPart in types/aiCompat.ts); `textDelta`
+                            // is a V2-era AI-SDK field that V3 providers (e.g. Bedrock's
+                            // bridge, this package's own openaiChatCompletionsBase) never
+                            // set. Reading `chunk.textDelta` alone silently produced
+                            // `undefined`, which string-concatenated into a literal
+                            // "undefined" per chunk. Falling back to `textDelta` keeps any
+                            // caller still emitting the older shape working unchanged.
+                            const textDelta = chunk.type === "text-delta"
+                                ? (chunk.delta ?? chunk.textDelta)
+                                : undefined;
+                            if (chunk.type === "text-delta" && textDelta !== undefined) {
+                                accumulatedText += textDelta;
                             }
-                            if (config.onChunk && chunk.type) {
+                            if (config.onChunk &&
+                                chunk.type &&
+                                !streamCallbacksOwnedByBaseProvider) {
                                 try {
                                     const callbackResult = config.onChunk({
                                         type: chunk.type,
-                                        textDelta: chunk.type === "text-delta" ? chunk.textDelta : undefined,
+                                        textDelta,
                                         sequenceNumber: sequenceNumber++,
                                     });
                                     Promise.resolve(callbackResult).catch((e) => {
@@ -124,7 +147,7 @@ export function createLifecycleMiddleware(config = {}) {
                         }
                     },
                     flush() {
-                        if (config.onFinish) {
+                        if (config.onFinish && !streamCallbacksOwnedByBaseProvider) {
                             try {
                                 const callbackResult = config.onFinish({
                                     text: accumulatedText,

package/dist/neurolink.js

@@ -79,7 +79,7 @@ import { tracers } from "./telemetry/tracers.js";
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 // Enhanced error handling imports
 import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
-import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "./utils/lifecycleCallbacks.js";
+import { hasLifecycleErrorFired, markLifecycleErrorFired, markLifecycleStreamCallbacksOwnedByBaseProvider, } from "./utils/lifecycleCallbacks.js";
 import { interleaveTTSStream } from "./utils/ttsStream.js";
 import { resolveLifecycleTimeoutMs } from "./utils/lifecycleTimeout.js";
 import { cloneOptionsForCallIsolation } from "./utils/cloneOptions.js";
@@ -782,6 +782,20 @@ export class NeuroLink {
         if (!options.onFinish && !options.onError && !options.onChunk) {
             return;
         }
+        const config = {
+            ...options.middleware?.middlewareConfig?.lifecycle?.config,
+            ...(options.onFinish !== undefined ? { onFinish: options.onFinish } : {}),
+            ...(options.onError !== undefined ? { onError: options.onError } : {}),
+            ...(options.onChunk !== undefined ? { onChunk: options.onChunk } : {}),
+        };
+        // BaseProvider.wrapStreamWithLifecycleCallbacks unconditionally wraps
+        // every provider's stream() result and fires onChunk/onFinish from
+        // there, reliably, for this exact config object. Stamp it so the
+        // model-level lifecycle middleware (builtin/lifecycle.ts) skips its own
+        // onChunk/onFinish firing for it instead of delivering each one twice.
+        // See markLifecycleStreamCallbacksOwnedByBaseProvider's doc comment for
+        // why generate()'s config below is never stamped this way.
+        markLifecycleStreamCallbacksOwnedByBaseProvider(config);
         options.middleware = {
             ...options.middleware,
             middlewareConfig: {
@@ -789,18 +803,7 @@ export class NeuroLink {
                 lifecycle: {
                     ...options.middleware?.middlewareConfig?.lifecycle,
                     enabled: true,
-                    config: {
-                        ...options.middleware?.middlewareConfig?.lifecycle?.config,
-                        ...(options.onFinish !== undefined
-                            ? { onFinish: options.onFinish }
-                            : {}),
-                        ...(options.onError !== undefined
-                            ? { onError: options.onError }
-                            : {}),
-                        ...(options.onChunk !== undefined
-                            ? { onChunk: options.onChunk }
-                            : {}),
-                    },
+                    config,
                 },
             },
         };

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

@@ -271,6 +271,26 @@ export declare class GoogleVertexProvider extends BaseProvider {
      * this for free via the AI SDK `wrapStream` middleware; native @google/genai
      * bypasses that wrapper, so native consumers need their lifecycle
      * callbacks invoked from here.
+     *
+     * `BaseProvider.stream()` always passes the result this method returns
+     * through `wrapStreamWithLifecycleCallbacks` afterwards too (that wrapper
+     * has "no early return when there are no callbacks" — see its own doc
+     * comment) — so unconditionally firing here double-fires onChunk/onFinish
+     * for every native Vertex stream. `isLifecycleStreamCallbacksOwnedByBaseProvider`
+     * reads the SAME nested lifecycle config off the SAME `options` object
+     * `wrapStreamWithLifecycleCallbacks` reads from (NeuroLink.applyStreamLifecycleMiddleware
+     * stamps it before either method runs), so both sites agree on which one
+     * actually fires without a second, Vertex-specific marker — and without
+     * relying on a Symbol on the `StreamResult` itself, which would not
+     * survive `withStreamModelFallback`'s rebuild of a plain forwarding object
+     * between this method and `wrapStreamWithLifecycleCallbacks`.
+     *
+     * onError is deliberately NOT gated by that marker — same precedent as
+     * `middleware/builtin/lifecycle.ts`'s `wrapStream` ("onError is NOT
+     * covered by this flag: it keeps its own, independent dedup via
+     * fireOnErrorOnce's shared fired-marker"). `fireOnErrorOnce` stamps the
+     * error so `BaseProvider`'s own catch (which checks
+     * `hasLifecycleErrorFired`) skips its own fire for the same failure.
      */
     private wrapStreamResultWithLifecycle;
     /**

package/dist/providers/googleVertex/client.js

@@ -22,6 +22,7 @@ import { FileDetector } from "../../utils/fileDetector.js";
 import { mergeMediaFileAliases, normalizeVisionImageFormats, processUnifiedFilesArray, } from "../../utils/messageBuilder.js";
 import { logger } from "../../utils/logger.js";
 import { drainDetachedPump } from "../../utils/drainDetachedPump.js";
+import { fireOnErrorOnce, getLifecycleMiddlewareConfig, isLifecycleStreamCallbacksOwnedByBaseProvider, } from "../../utils/lifecycleCallbacks.js";
 import { GEMINI_ELISION_NOTE, planGeminiLoopReclaim, previewGeminiToolResponseText, } from "../../context/geminiLoopGuard.js";
 import { ANTHROPIC_ELISION_NOTE, planAnthropicLoopReclaim, previewAnthropicToolResultText, } from "../../context/anthropicLoopGuard.js";
 import { hasRestrictedOutputLimit, RESTRICTED_OUTPUT_TOKEN_LIMIT, toVertexAnthropicModelId, } from "../../utils/modelDetection.js";
@@ -5618,24 +5619,47 @@ export class GoogleVertexProvider extends BaseProvider {
      * this for free via the AI SDK `wrapStream` middleware; native @google/genai
      * bypasses that wrapper, so native consumers need their lifecycle
      * callbacks invoked from here.
+     *
+     * `BaseProvider.stream()` always passes the result this method returns
+     * through `wrapStreamWithLifecycleCallbacks` afterwards too (that wrapper
+     * has "no early return when there are no callbacks" — see its own doc
+     * comment) — so unconditionally firing here double-fires onChunk/onFinish
+     * for every native Vertex stream. `isLifecycleStreamCallbacksOwnedByBaseProvider`
+     * reads the SAME nested lifecycle config off the SAME `options` object
+     * `wrapStreamWithLifecycleCallbacks` reads from (NeuroLink.applyStreamLifecycleMiddleware
+     * stamps it before either method runs), so both sites agree on which one
+     * actually fires without a second, Vertex-specific marker — and without
+     * relying on a Symbol on the `StreamResult` itself, which would not
+     * survive `withStreamModelFallback`'s rebuild of a plain forwarding object
+     * between this method and `wrapStreamWithLifecycleCallbacks`.
+     *
+     * onError is deliberately NOT gated by that marker — same precedent as
+     * `middleware/builtin/lifecycle.ts`'s `wrapStream` ("onError is NOT
+     * covered by this flag: it keeps its own, independent dedup via
+     * fireOnErrorOnce's shared fired-marker"). `fireOnErrorOnce` stamps the
+     * error so `BaseProvider`'s own catch (which checks
+     * `hasLifecycleErrorFired`) skips its own fire for the same failure.
      */
     wrapStreamResultWithLifecycle(options, result, startTime) {
         const onChunk = options.onChunk;
         const onFinish = options
             .onFinish;
-        const onError = options
-            .onError;
+        // `StreamOptions.onError` is already properly typed as `OnErrorCallback`
+        // (unlike the two casts above, kept from before that field existed on
+        // the type) — read directly so `fireOnErrorOnce` below gets it without
+        // a cast.
+        const onError = options.onError;
         if (typeof onChunk !== "function" &&
             typeof onFinish !== "function" &&
             typeof onError !== "function") {
             return result;
         }
+        const streamCallbacksOwnedByBaseProvider = isLifecycleStreamCallbacksOwnedByBaseProvider(getLifecycleMiddlewareConfig(options));
         const originalIterable = result.stream;
         let accumulated = "";
         let sequence = 0;
-        const provider = this.providerName;
         const fireOnChunk = (payload) => {
-            if (typeof onChunk !== "function") {
+            if (typeof onChunk !== "function" || streamCallbacksOwnedByBaseProvider) {
                 return;
             }
             try {
@@ -5647,7 +5671,8 @@ export class GoogleVertexProvider extends BaseProvider {
             }
         };
         const fireOnFinish = (payload) => {
-            if (typeof onFinish !== "function") {
+            if (typeof onFinish !== "function" ||
+                streamCallbacksOwnedByBaseProvider) {
                 return;
             }
             try {
@@ -5686,21 +5711,18 @@ export class GoogleVertexProvider extends BaseProvider {
                     });
                 }
                 catch (err) {
-                    if (typeof onError === "function") {
-                        try {
-                            const errInst = err instanceof Error ? err : new Error(String(err));
-                            const cbResult = onError({
-                                error: errInst,
-                                duration: Date.now() - startTime,
-                                recoverable: false,
-                            });
-                            Promise.resolve(cbResult).catch((e) => logger.warn(`[${provider}] onError callback rejected: ${e instanceof Error ? e.message : String(e)}`));
-                        }
-                        catch (e) {
-                            logger.warn(`[${provider}] onError callback threw: ${e instanceof Error ? e.message : String(e)}`);
-                        }
-                    }
-                    throw err;
+                    const errInst = err instanceof Error ? err : new Error(String(err));
+                    fireOnErrorOnce(onError, errInst, {
+                        error: errInst,
+                        duration: Date.now() - startTime,
+                        recoverable: false,
+                    });
+                    // Rethrow the normalized `errInst` (not the raw `err`) so the
+                    // fired-mark `fireOnErrorOnce` just stamped on it propagates to
+                    // BaseProvider's own catch (`hasLifecycleErrorFired`), which
+                    // would otherwise see an unstamped error and fire onError again
+                    // for the same logical failure.
+                    throw errInst;
                 }
             },
         };

package/dist/utils/lifecycleCallbacks.d.ts

@@ -27,7 +27,36 @@
  * structuredClone / cross-realm postMessage where a closed-over
  * WeakSet does not.
  */
-import type { LifecycleErrorPayload, OnErrorCallback } from "../types/index.js";
+import type { LifecycleErrorPayload, LifecycleMiddlewareConfig, OnErrorCallback } from "../types/index.js";
+/**
+ * Read the consumer-facing lifecycle callbacks buried inside a request's
+ * middleware blob. The parameter is `unknown` on purpose: request options
+ * arrive as several structurally-unrelated shapes (StreamOptions,
+ * TextGenerationOptions), and the lifecycle branch is an optional add-on
+ * none of them declare — a single structural view keeps the read cast-free
+ * at every call site.
+ *
+ * Shared (moved out of `BaseProvider`) because two independent firing sites
+ * now need the same read: `BaseProvider.wrapStreamWithLifecycleCallbacks`
+ * (every provider's stream) and `GoogleVertexProvider.wrapStreamResultWithLifecycle`
+ * (Vertex's own native-stream firer, which must check the SAME
+ * `isLifecycleStreamCallbacksOwnedByBaseProvider` marker on the SAME nested
+ * config object that BaseProvider's wrapper reads from `options`, so that
+ * both sites agree on who owns firing without a second marker).
+ */
+export declare function getLifecycleMiddlewareConfig(options: unknown): LifecycleMiddlewareConfig | undefined;
+/**
+ * Stamp a stream lifecycle config object with
+ * `STREAM_CALLBACKS_OWNED_BY_BASE_PROVIDER`. See that symbol's doc comment
+ * for who may call this (only `applyStreamLifecycleMiddleware`) and why.
+ */
+export declare function markLifecycleStreamCallbacksOwnedByBaseProvider(config: object): void;
+/**
+ * True when `markLifecycleStreamCallbacksOwnedByBaseProvider` already
+ * stamped this config. The model-level lifecycle middleware reads this to
+ * decide whether to fire its own onChunk/onFinish for a stream config.
+ */
+export declare function isLifecycleStreamCallbacksOwnedByBaseProvider(config: unknown): boolean;
 /**
  * Returns true when `markLifecycleErrorFired` or a previous
  * `fireOnErrorOnce` call has already stamped this error.

package/dist/utils/lifecycleCallbacks.js

@@ -28,6 +28,99 @@
  * WeakSet does not.
  */
 const ON_ERROR_FIRED = Symbol.for("neurolink.onErrorFired");
+/**
+ * Read the consumer-facing lifecycle callbacks buried inside a request's
+ * middleware blob. The parameter is `unknown` on purpose: request options
+ * arrive as several structurally-unrelated shapes (StreamOptions,
+ * TextGenerationOptions), and the lifecycle branch is an optional add-on
+ * none of them declare — a single structural view keeps the read cast-free
+ * at every call site.
+ *
+ * Shared (moved out of `BaseProvider`) because two independent firing sites
+ * now need the same read: `BaseProvider.wrapStreamWithLifecycleCallbacks`
+ * (every provider's stream) and `GoogleVertexProvider.wrapStreamResultWithLifecycle`
+ * (Vertex's own native-stream firer, which must check the SAME
+ * `isLifecycleStreamCallbacksOwnedByBaseProvider` marker on the SAME nested
+ * config object that BaseProvider's wrapper reads from `options`, so that
+ * both sites agree on who owns firing without a second marker).
+ */
+export function getLifecycleMiddlewareConfig(options) {
+    return options?.middleware
+        ?.middlewareConfig?.lifecycle?.config;
+}
+/**
+ * Marks a stream lifecycle config as "BaseProvider.wrapStreamWithLifecycleCallbacks
+ * already fires onChunk/onFinish for this config, authoritatively, from
+ * NeuroLink's own normalized stream — the model-level lifecycle middleware
+ * (middleware/builtin/lifecycle.ts) must not ALSO fire them from the raw
+ * per-provider V3 chunks it sees."
+ *
+ * Only `NeuroLink.applyStreamLifecycleMiddleware()` stamps a config with this
+ * marker, and only for stream()'s config: it is the one function that builds
+ * a lifecycle config fresh from stream()'s top-level onChunk/onFinish/onError
+ * options, for a call that unconditionally passes through
+ * `BaseProvider.wrapStreamWithLifecycleCallbacks` afterwards — see that
+ * method's doc comment ("the only point every provider's stream passes
+ * through unconditionally"). Without this marker both layers fire
+ * onChunk/onFinish for the same logical stream: once (unreliable, raw,
+ * provider-shape-dependent) from the model-level middleware, once (reliable,
+ * normalized) from BaseProvider.
+ *
+ * `NeuroLink.applyGenerateLifecycleMiddleware()` must NEVER stamp its config
+ * this way. BaseProvider has no equivalent guaranteed-delivery layer for
+ * generate()'s onFinish: `BaseProvider.finalizeNativeGenerate`'s own doc
+ * comment states onFinish is deliberately NOT fired there because "the
+ * native paths now wrap their model, so the lifecycle middleware fires it" —
+ * the model-level middleware is the SOLE firing site for every native
+ * generate loop that goes through the model wrap (sagemaker,
+ * openaiChatCompletionsBase, anthropic). The one generate path that bypasses
+ * the model wrap (GoogleVertex's native @google/genai loop) fires onFinish
+ * itself via `BaseProvider.fireGenerateOnFinish` precisely because the
+ * middleware never runs for it. Stamping the generate config would make the
+ * model-level middleware suppress its own firing with nothing left to fire
+ * it, silently breaking onFinish for every one of those providers.
+ *
+ * A config a consumer builds directly — e.g. calling the exported
+ * `createLifecycleMiddleware` and applying it to their own model via the
+ * `ai` package's `wrapLanguageModel`, entirely outside NeuroLink's
+ * BaseProvider/stream()/generate() call path — is never stamped, so that
+ * standalone use keeps firing onChunk/onFinish exactly as before (CLAUDE.md
+ * rule 5: public SDK API must not break existing callers).
+ *
+ * Symbol-stamped on the object itself (not a typed field) for the same
+ * reason as `ON_ERROR_FIRED` above: it survives across separate module
+ * copies of the same config object where a closed-over WeakSet would not.
+ */
+const STREAM_CALLBACKS_OWNED_BY_BASE_PROVIDER = Symbol.for("neurolink.lifecycleStreamCallbacksOwnedByBaseProvider");
+/**
+ * Stamp a stream lifecycle config object with
+ * `STREAM_CALLBACKS_OWNED_BY_BASE_PROVIDER`. See that symbol's doc comment
+ * for who may call this (only `applyStreamLifecycleMiddleware`) and why.
+ */
+export function markLifecycleStreamCallbacksOwnedByBaseProvider(config) {
+    try {
+        Object.defineProperty(config, STREAM_CALLBACKS_OWNED_BY_BASE_PROVIDER, {
+            value: true,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    catch {
+        // Non-extensible config object — worst case is the pre-fix double fire.
+    }
+}
+/**
+ * True when `markLifecycleStreamCallbacksOwnedByBaseProvider` already
+ * stamped this config. The model-level lifecycle middleware reads this to
+ * decide whether to fire its own onChunk/onFinish for a stream config.
+ */
+export function isLifecycleStreamCallbacksOwnedByBaseProvider(config) {
+    if (config === null || typeof config !== "object") {
+        return false;
+    }
+    return (config[STREAM_CALLBACKS_OWNED_BY_BASE_PROVIDER] === true);
+}
 function stampFired(error) {
     try {
         Object.defineProperty(error, ON_ERROR_FIRED, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.41.3",
+  "version": "12.41.4",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {