@juspay/neurolink 11.29.2 → 12.0.0

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,90 @@
+/**
+ * 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");
+/**
+ * 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;
+        }
+        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) {
+    if (typeof iterator.return !== "function") {
+        return;
+    }
+    try {
+        const result = iterator.return(undefined);
+        if (result &&
+            typeof result.catch === "function" &&
+            typeof result.then === "function") {
+            void result.catch(() => { });
+        }
+    }
+    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.29.2",
+  "version": "12.0.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": {
@@ -83,6 +83,7 @@
     "test:media": "pnpm exec tsx test/continuous-test-suite-media-gen.ts",
     "test:media-registry-collisions": "pnpm exec tsx test/continuous-test-suite-media-registry-collisions.ts",
     "test:memory": "pnpm exec tsx test/continuous-test-suite-memory.ts",
+    "test:proxy-sharing": "pnpm run build && pnpm exec tsx test/continuous-test-suite-proxy-sharing.ts",
     "test:openai-compat-streaming-retry": "pnpm exec tsx test/continuous-test-suite-openai-compat-streaming-retry.ts",
     "test:anthropic-streaming-retry": "pnpm exec tsx test/continuous-test-suite-anthropic-streaming-retry.ts",
     "test:adjust-body-after-400": "pnpm exec tsx test/continuous-test-suite-adjust-body-after-400.ts",