@juspay/neurolink 11.30.0 → 12.0.1

package/dist/core/baseProvider.js

@@ -15,6 +15,7 @@ import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifec
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
 import { interleaveTTSStream } from "../utils/ttsStream.js";
+import { attachStreamCancel, cancelStream, releaseIterator, } from "../utils/streamCancellation.js";
 import { TimeoutError as AsyncTimeoutError, withTimeoutFn, } from "../utils/async/withTimeout.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
@@ -383,11 +384,20 @@ export class BaseProvider {
         // Arrow, like `safeFire` above: the generator is a plain function expression, so
         // `this` is not bound inside it.
         const classifyStreamError = (e) => this.classifyStreamError(e);
+        // Hold the upstream iterator rather than letting `for await` create one
+        // internally, so the cancel hook below can close it directly. Iterating
+        // `upstreamIterable` is equivalent to iterating `originalStream` — same
+        // iterator, same early-exit `return()` semantics — it just leaves a handle
+        // reachable from outside the generator.
+        const upstreamIterator = originalStream[Symbol.asyncIterator]();
+        const upstreamIterable = {
+            [Symbol.asyncIterator]: () => upstreamIterator,
+        };
         const wrappedStream = (async function* () {
             let accumulated = "";
             let seq = 0;
             try {
-                for await (const chunk of originalStream) {
+                for await (const chunk of upstreamIterable) {
                     const textPart = chunk &&
                         typeof chunk === "object" &&
                         "content" in chunk &&
@@ -434,6 +444,15 @@ export class BaseProvider {
                 throw classifyStreamError(err);
             }
         })();
+        // A consumer that breaks out of the stream cannot reach this generator
+        // through `.return()` while it is parked awaiting the provider — that
+        // request queues behind the in-flight `next()`. The hook closes the
+        // upstream directly and forwards the request to any wrapper below, so
+        // abandoning a stream really does release the provider connection.
+        attachStreamCancel(wrappedStream, () => {
+            cancelStream(originalStream);
+            releaseIterator(upstreamIterator);
+        });
         return { ...result, stream: wrappedStream };
     }
     /**

package/dist/neurolink.js

@@ -1229,9 +1229,23 @@ export class NeuroLink {
             });
         });
         // Fire-and-forget: registrations complete before any generate/stream call
-        // because those calls await initializeMCP() which is slower
+        // because those calls await initializeMCP() which is slower.
+        //
+        // The rejection handler is not decoration. registerTool() throws on a
+        // failed name/description validation (mcp/toolRegistry.ts), and that throw
+        // is not inside a try — so a rejected registration on a `void`-detached
+        // one-argument `.then()` would be an unhandled rejection, which terminates
+        // the process. Today the tool names come from createFileTools(), which are
+        // internal constants that pass validation, so this is latent rather than
+        // live; it stops being latent the moment a name is derived from anything
+        // outside this file. Losing one tool registration is the intended failure
+        // mode here — losing the host process is not.
         void Promise.all(registrations).then(() => {
             logger.debug(`[NeuroLink] Registered ${Object.keys(fileTools).length} file reference tools`);
+        }, (error) => {
+            logger.warn("[NeuroLink] File tool registration failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
         });
     }
     /**
@@ -1253,7 +1267,15 @@ export class NeuroLink {
             // registerTool is async but its core logic is synchronous (Map.set).
             // We fire-and-forget here but tools are available immediately after
             // the synchronous validation + map insertion completes.
-            void this.toolRegistry.registerTool(toolId, toolInfo, {
+            //
+            // The .catch() at the end of this call is required for the same reason
+            // as in registerFileTools() above: registerTool() throws on failed
+            // validation, and an unhandled rejection off a `void`-detached call
+            // terminates the process rather than failing this one registration.
+            // Latent today (createTaskTools() supplies internal, valid names), and
+            // cheap to keep correct.
+            void this.toolRegistry
+                .registerTool(toolId, toolInfo, {
                 execute: async (params) => {
                     try {
                         const result = await toolDef.execute(params, {
@@ -1276,6 +1298,12 @@ export class NeuroLink {
                 },
                 description: toolDef.description,
                 inputSchema: {},
+            })
+                .catch((error) => {
+                logger.warn("[NeuroLink] Task tool registration failed", {
+                    toolId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
             });
         }
         logger.debug(`[NeuroLink] Registered ${Object.keys(taskTools).length} task tools`);

package/dist/utils/streamCancellation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Out-of-band cancellation for chained async streams.
+ *
+ * `AsyncGenerator.prototype.return()` is the obvious way to tell a stream its
+ * consumer has gone away, and it does not work through a chain of generators.
+ * The request is *queued* behind whatever `next()` is already in flight; it
+ * cannot interrupt an `await`. A provider stream is wrapped several times
+ * (lifecycle in `baseProvider`, MCP and pool wrappers in `neurolink`), and
+ * during a pull every one of those layers is parked inside an `await` on the
+ * layer below. So none of them can unwind, the innermost source is never
+ * closed, and a teardown that waits for that to happen waits forever.
+ *
+ * This module is the side channel that does work. A wrapper registers a
+ * cancel callback on the stream object it returns; the callback closes its own
+ * upstream iterator and forwards the request further down. Because these are
+ * ordinary function calls rather than generator protocol, they run immediately
+ * — no queue, no dependence on any pending `next()` settling.
+ *
+ * Registration is optional and reading is defensive, so a stream that knows
+ * nothing about this behaves exactly as it did before.
+ */
+/**
+ * Register `cancel` as `stream`'s teardown hook and return the same object.
+ *
+ * Non-enumerable so the property never shows up in spreads, `JSON.stringify`
+ * or logging of a stream handle.
+ */
+export declare function attachStreamCancel<S extends object>(stream: S, cancel: () => void): S;
+/**
+ * Invoke `stream`'s cancel hook if it has one.
+ *
+ * Never throws. This runs from `finally` blocks during teardown, where the
+ * consumer has already stopped listening — an exception here would replace
+ * whatever outcome the caller was actually returning with a cleanup error.
+ */
+export declare function cancelStream(stream: unknown): void;
+/**
+ * Close `iterator` without waiting for it and without surfacing a rejection.
+ *
+ * Deliberately not awaited: on a generator that is parked mid-`await` this
+ * promise may never settle, which is the whole failure this module exists to
+ * avoid. The call still propagates whenever the iterator can act on it.
+ */
+export declare function releaseIterator(iterator: {
+    return?: (value?: unknown) => unknown;
+}): void;

package/dist/utils/streamCancellation.js

@@ -0,0 +1,109 @@
+/**
+ * Out-of-band cancellation for chained async streams.
+ *
+ * `AsyncGenerator.prototype.return()` is the obvious way to tell a stream its
+ * consumer has gone away, and it does not work through a chain of generators.
+ * The request is *queued* behind whatever `next()` is already in flight; it
+ * cannot interrupt an `await`. A provider stream is wrapped several times
+ * (lifecycle in `baseProvider`, MCP and pool wrappers in `neurolink`), and
+ * during a pull every one of those layers is parked inside an `await` on the
+ * layer below. So none of them can unwind, the innermost source is never
+ * closed, and a teardown that waits for that to happen waits forever.
+ *
+ * This module is the side channel that does work. A wrapper registers a
+ * cancel callback on the stream object it returns; the callback closes its own
+ * upstream iterator and forwards the request further down. Because these are
+ * ordinary function calls rather than generator protocol, they run immediately
+ * — no queue, no dependence on any pending `next()` settling.
+ *
+ * Registration is optional and reading is defensive, so a stream that knows
+ * nothing about this behaves exactly as it did before.
+ */
+const STREAM_CANCEL = Symbol.for("neurolink.streamCancel");
+/**
+ * Swallow a rejection from a thenable teardown result.
+ *
+ * An unhandled rejection **terminates the process** — a caller doing everything
+ * right still dies, with the stack pointing at library internals it never
+ * called. Teardown runs after the consumer has stopped listening, so there is
+ * nobody left to hand the error to; dropping it is the only correct outcome,
+ * and dropping it deliberately is what keeps it from becoming fatal.
+ */
+function suppressRejection(result) {
+    if (result !== null &&
+        typeof result === "object" &&
+        typeof result.then === "function" &&
+        typeof result.catch === "function") {
+        void result.catch(() => { });
+    }
+}
+/**
+ * Register `cancel` as `stream`'s teardown hook and return the same object.
+ *
+ * Non-enumerable so the property never shows up in spreads, `JSON.stringify`
+ * or logging of a stream handle.
+ */
+export function attachStreamCancel(stream, cancel) {
+    Object.defineProperty(stream, STREAM_CANCEL, {
+        value: cancel,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+    return stream;
+}
+/**
+ * Invoke `stream`'s cancel hook if it has one.
+ *
+ * Never throws. This runs from `finally` blocks during teardown, where the
+ * consumer has already stopped listening — an exception here would replace
+ * whatever outcome the caller was actually returning with a cleanup error.
+ */
+export function cancelStream(stream) {
+    if (stream === null || stream === undefined) {
+        return;
+    }
+    if (typeof stream !== "object" && typeof stream !== "function") {
+        return;
+    }
+    try {
+        // The property read is inside the try, not before it. Reading a symbol off
+        // an arbitrary object can execute user code — a Proxy trap or a throwing
+        // getter — and this function is documented as never throwing because it
+        // runs from teardown `finally` blocks, where an exception would replace
+        // the outcome the caller was actually returning with a cleanup error.
+        const hook = stream[STREAM_CANCEL];
+        if (typeof hook !== "function") {
+            return;
+        }
+        // `attachStreamCancel` types the hook as `() => void`, but nothing stops a
+        // caller registering an `async` function — whose rejection would otherwise
+        // be unhandled, and therefore fatal to the process.
+        suppressRejection(hook());
+    }
+    catch {
+        // Teardown is best-effort by definition.
+    }
+}
+/**
+ * Close `iterator` without waiting for it and without surfacing a rejection.
+ *
+ * Deliberately not awaited: on a generator that is parked mid-`await` this
+ * promise may never settle, which is the whole failure this module exists to
+ * avoid. The call still propagates whenever the iterator can act on it.
+ */
+export function releaseIterator(iterator) {
+    try {
+        // Read the method inside the try, for the same reason `cancelStream` does:
+        // `iterator` is whatever an upstream handed us, and a Proxy trap or a
+        // throwing getter turns a property access into arbitrary user code.
+        const release = iterator.return;
+        if (typeof release !== "function") {
+            return;
+        }
+        suppressRejection(release.call(iterator, undefined));
+    }
+    catch {
+        // Best-effort, as above.
+    }
+}

package/dist/utils/ttsStream.js

@@ -3,6 +3,7 @@ import { sanitizeErrorCause } from "./logSanitize.js";
 import { logger } from "./logger.js";
 import { IncrementalTTSSynthesisError, TTS_ERROR_CODES, TTSProcessor, } from "./ttsProcessor.js";
 import { TimeoutError as AsyncTimeoutError } from "./async/withTimeout.js";
+import { cancelStream } from "./streamCancellation.js";
 function getStreamingTTSErrorDetails(error) {
     const incrementalFailure = error instanceof IncrementalTTSSynthesisError ? error : undefined;
     const cause = incrementalFailure?.firstError ?? error;
@@ -122,6 +123,20 @@ function aggregateTTSChunks(chunks) {
         sampleRate: last.sampleRate,
     };
 }
+/**
+ * Upper bound on how long stream teardown may wait for upstream iterators to
+ * acknowledge `.return()`. Closing an iterator is bookkeeping, not work, so a
+ * responsive upstream finishes far inside this; an unresponsive one is exactly
+ * the case that must not block the consumer. The timer is unref'd so a pending
+ * grace period never by itself keeps the process alive.
+ */
+const RELEASE_GRACE_MS = 5_000;
+function releaseGraceTimer() {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, RELEASE_GRACE_MS);
+        timer.unref?.();
+    });
+}
 /**
  * Preserve source-stream backpressure while interleaving incremental TTS audio.
  * Source chunks are yielded before their derived audio, and TTS failures degrade
@@ -208,6 +223,12 @@ export async function* interleaveTTSStream(params) {
     finally {
         if (!completed) {
             cancelled = true;
+            // Tell the upstream chain out of band, before asking politely via
+            // `.return()` below. When the consumer breaks mid-pull every wrapper
+            // beneath is parked inside an `await` and cannot process a queued
+            // `return()`, so this side channel is the only thing that actually
+            // reaches — and closes — the provider stream at the bottom.
+            cancelStream(stream);
         }
         textQueue.end();
         const releases = [];
@@ -217,7 +238,19 @@ export async function* interleaveTTSStream(params) {
         if (nextAudio && audioIterator.return) {
             releases.push(Promise.resolve().then(() => audioIterator.return?.(undefined)));
         }
-        await Promise.allSettled(releases);
+        // Cleanup must not be able to outlive the consumer that abandoned this
+        // stream. `.return()` on an async generator parked inside an `await` is
+        // queued behind the in-flight `next()` and cannot interrupt it, so when an
+        // upstream pull never settles these promises settle *never* — not late.
+        // Awaiting them unbounded turned a consumer's `break` into a permanent
+        // hang: the caller's `for await` never returned, with no error and no way
+        // to defend against it from outside this module.
+        //
+        // The releases are still issued, and still propagate normally whenever the
+        // upstream is responsive — which is every case where awaiting them was
+        // doing anything useful. We only stop making the consumer's exit depend on
+        // an upstream that may never answer.
+        await Promise.race([Promise.allSettled(releases), releaseGraceTimer()]);
         if (!completed) {
             onComplete?.(undefined);
         }

package/dist/voice/livekit/realtimeEventBridge.js

@@ -52,18 +52,39 @@ export async function attachRealtimeEventBridge(params) {
                 via,
                 bytes: bytes.byteLength,
             });
-            if (via === "data") {
-                void participant.publishData(bytes, {
-                    reliable: true,
-                    topic: eventsTopic,
+            // Both calls are detached on purpose — the bridge must never make the
+            // caller wait on the UI. But `void` alone does NOT make a rejection
+            // harmless, and the try/catch below cannot help: a synchronous catch
+            // never sees a rejected promise. Measured — a rejecting publish with
+            // this exact shape leaves the catch untouched and, with no
+            // unhandledRejection handler installed, terminates the process:
+            //   SYNC_CATCH_FIRED = false · UNHANDLED_COUNT = 1 · exit 1
+            // These are network calls to a peer that can disconnect mid-publish, so
+            // the rejection is ordinary, not exotic. Attaching a handler is what
+            // actually makes the bridge best-effort, which is what the catch below
+            // only claimed. Same class as the detached-pump crash in anthropic.
+            const publishFailed = (error) => {
+                logger.debug("realtime.bridge.publishFailed", {
+                    seq,
+                    type,
+                    via,
+                    error: error instanceof Error ? error.message : String(error),
                 });
+            };
+            if (via === "data") {
+                void participant
+                    .publishData(bytes, { reliable: true, topic: eventsTopic })
+                    .catch(publishFailed);
             }
             else {
-                void participant.sendText(json, { topic: eventsTopic });
+                void participant
+                    .sendText(json, { topic: eventsTopic })
+                    .catch(publishFailed);
             }
         }
         catch {
-            /* non-fatal — the UI bridge is best-effort */
+            /* non-fatal — covers the synchronous half only (encode/stringify);
+               the detached publishes carry their own handler above. */
         }
     };
     // HITL: WRITE-labeled tools pause for user confirmation. We publish a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.30.0",
+  "version": "12.0.1",
   "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": {