@juspay/neurolink 12.28.4 → 12.29.0

package/CHANGELOG.md

@@ -1,8 +1,15 @@
-## [12.28.4](https://github.com/juspay/neurolink/compare/v12.28.3...v12.28.4) (2026-09-26)
+## [12.29.0](https://github.com/juspay/neurolink/compare/v12.28.4...v12.29.0) (2026-09-26)
+
+### Features
+
+- **(providers):** onboard Novita and Morph as catalog providers ([d8a566d](https://github.com/juspay/neurolink/commit/d8a566d2dd9b8f1d7cb73ea5d69d7a42913f9085))
+- **(tts):** stream Google audio natively and add a voices command ([ce538d0](https://github.com/juspay/neurolink/commit/ce538d022a7249ee24fd4965f0d8627d3a667918)), closes [#528](https://github.com/juspay/neurolink/issues/528)
 
 ### Bug Fixes
 
-- **(benchmarks):** port the Mac run's guards to the Linux TUA-Bench driver ([d7f41ef](https://github.com/juspay/neurolink/commit/d7f41efa6933db59d9d46e87961bfaad6d81bf13))
+- **(health):** stop silently excluding most providers from the health sweep ([eda0239](https://github.com/juspay/neurolink/commit/eda0239ffb8e89d73fa33353044c4f0202701ad1)), closes [#1744](https://github.com/juspay/neurolink/issues/1744)
+- **(logger):** route log events per NeuroLink instance so worker bridges attribute truthfully ([163a0fd](https://github.com/juspay/neurolink/commit/163a0fdc719077f801de21fb0b533d5f28fa5015))
+- **(sdk):** stop four public surfaces accepting input and dropping it ([be2ee44](https://github.com/juspay/neurolink/commit/be2ee44e6cdd1061a681bd113a0861374b562282)), closes [#1576](https://github.com/juspay/neurolink/issues/1576) [#1576](https://github.com/juspay/neurolink/issues/1576) [#1550](https://github.com/juspay/neurolink/issues/1550)
 
 ## [11.2.3](https://github.com/juspay/neurolink/compare/v11.2.2...v11.2.3) (2026-08-19)
 

package/dist/adapters/tts/googleTTSHandler.d.ts

@@ -1,4 +1,4 @@
-import type { TTSOptions, TTSResult, TTSVoice, TTSHandler } from "../../types/index.js";
+import type { TTSChunk, TTSOptions, TTSResult, TTSVoice, TTSHandler } from "../../types/index.js";
 export declare class GoogleTTSHandler implements TTSHandler {
     private client;
     private voicesCache;
@@ -59,6 +59,76 @@ export declare class GoogleTTSHandler implements TTSHandler {
      * @returns Audio buffer with metadata
      */
     synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Voice names Google's streaming endpoint will synthesize.
+     *
+     * Streaming is not a property of the API, it is a property of the voice:
+     * every other family is rejected outright with `INVALID_ARGUMENT:
+     * Currently, only Chirp 3: HD voices are supported for streaming
+     * synthesis`. Measured against the live API — `Chirp3-HD` (en-US, en-GB and
+     * de-DE), `Chirp-HD` and `Journey` all stream; `Neural2` and `Studio` are
+     * refused. The locale prefix is required so a malformed name cannot reach
+     * the wire and fail a segment that the buffered path would have served.
+     */
+    private static readonly STREAMING_VOICE_PATTERN;
+    /**
+     * Sample rate requested for streamed audio, in Hz.
+     *
+     * Reported on every chunk so a consumer can interpret headerless `PCM`
+     * bytes. Google honours the request — 16000 was measured returning
+     * proportionally fewer bytes for the same text — and 24000 matches what
+     * `getSampleRate()` reports for the buffered path.
+     */
+    private static readonly STREAMING_SAMPLE_RATE_HZ;
+    /**
+     * How long a stream may go without delivering a response before it is
+     * treated as stalled.
+     *
+     * Deliberately an *idle* bound rather than a bound on the whole call, which
+     * is what `DEFAULT_API_TIMEOUT_MS` gives `synthesize()`. Streaming produces
+     * audio at roughly playback speed, so a total bound would fail a long but
+     * perfectly healthy segment purely for being long.
+     */
+    private static readonly STREAMING_IDLE_TIMEOUT_MS;
+    /**
+     * Map a requested audio format to a streaming audio encoding, or
+     * `undefined` when streaming cannot produce it.
+     *
+     * Only formats with direct wire proof of incremental delivery appear here.
+     * `PCM` delivered 41 reads with the first at 697ms and the body complete at
+     * 6131ms; `OGG_OPUS` delivered 11 reads with the first at 443ms. `MP3` and
+     * `LINEAR16` — both valid for `synthesizeSpeech` — are rejected by the
+     * streaming endpoint as unsupported encodings, so `mp3` and `wav` take the
+     * buffered path. `mp3` being the default format is why a caller has to opt
+     * in to streaming by asking for one of these two.
+     */
+    private static mapStreamingFormat;
+    /**
+     * Coerce one streaming response into its audio payload, or `undefined` when
+     * it carries none.
+     *
+     * The generated response type says `audioContent` is `Uint8Array | string |
+     * null`, and which one arrives depends on how the transport was configured
+     * — so both are handled rather than trusted.
+     */
+    private static streamedAudio;
+    /**
+     * Stream one pre-validated segment's audio as Google produces it.
+     *
+     * Returns `undefined` — the contract's "not incrementally deliverable"
+     * signal — unless the voice and the format are both ones the streaming
+     * endpoint was measured to accept, and the text is not SSML.
+     * `StreamingSynthesisInput` has no `ssml` field at all, so markup that
+     * `synthesize()` would honour has to stay on the buffered path rather than
+     * be sent as literal text.
+     *
+     * Every non-empty response is yielded as it arrives and carries `isFinal:
+     * false`. `TTSProcessor` recomputes indexes, cumulative sizes and finality
+     * globally across segments and discards whatever a handler reports, so
+     * labelling the last response here would buy nothing and would cost a
+     * one-response lookahead.
+     */
+    synthesizeStream(text: string, options?: TTSOptions): AsyncIterable<TTSChunk> | undefined;
     /**
      * Extract language code from a Google Cloud voice name
      *

package/dist/adapters/tts/googleTTSHandler.js

@@ -1,6 +1,7 @@
 import { TTSError, TTS_ERROR_CODES } from "../../utils/ttsProcessor.js";
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 import { logger } from "../../utils/logger.js";
+import { attachStreamCancel } from "../../utils/streamCancellation.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../../observability/index.js";
 export class GoogleTTSHandler {
     client = null;
@@ -265,6 +266,238 @@ export class GoogleTTSHandler {
             });
         }
     }
+    /**
+     * Voice names Google's streaming endpoint will synthesize.
+     *
+     * Streaming is not a property of the API, it is a property of the voice:
+     * every other family is rejected outright with `INVALID_ARGUMENT:
+     * Currently, only Chirp 3: HD voices are supported for streaming
+     * synthesis`. Measured against the live API — `Chirp3-HD` (en-US, en-GB and
+     * de-DE), `Chirp-HD` and `Journey` all stream; `Neural2` and `Studio` are
+     * refused. The locale prefix is required so a malformed name cannot reach
+     * the wire and fail a segment that the buffered path would have served.
+     */
+    static STREAMING_VOICE_PATTERN = /^[a-z]{2,3}-[A-Z]{2}-(?:Chirp3-HD|Chirp-HD|Journey)-/;
+    /**
+     * Sample rate requested for streamed audio, in Hz.
+     *
+     * Reported on every chunk so a consumer can interpret headerless `PCM`
+     * bytes. Google honours the request — 16000 was measured returning
+     * proportionally fewer bytes for the same text — and 24000 matches what
+     * `getSampleRate()` reports for the buffered path.
+     */
+    static STREAMING_SAMPLE_RATE_HZ = 24000;
+    /**
+     * How long a stream may go without delivering a response before it is
+     * treated as stalled.
+     *
+     * Deliberately an *idle* bound rather than a bound on the whole call, which
+     * is what `DEFAULT_API_TIMEOUT_MS` gives `synthesize()`. Streaming produces
+     * audio at roughly playback speed, so a total bound would fail a long but
+     * perfectly healthy segment purely for being long.
+     */
+    static STREAMING_IDLE_TIMEOUT_MS = 30 * 1000;
+    /**
+     * Map a requested audio format to a streaming audio encoding, or
+     * `undefined` when streaming cannot produce it.
+     *
+     * Only formats with direct wire proof of incremental delivery appear here.
+     * `PCM` delivered 41 reads with the first at 697ms and the body complete at
+     * 6131ms; `OGG_OPUS` delivered 11 reads with the first at 443ms. `MP3` and
+     * `LINEAR16` — both valid for `synthesizeSpeech` — are rejected by the
+     * streaming endpoint as unsupported encodings, so `mp3` and `wav` take the
+     * buffered path. `mp3` being the default format is why a caller has to opt
+     * in to streaming by asking for one of these two.
+     */
+    static mapStreamingFormat(format) {
+        switch (format) {
+            case "pcm16":
+                return "PCM";
+            case "ogg":
+            case "opus":
+                return "OGG_OPUS";
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Coerce one streaming response into its audio payload, or `undefined` when
+     * it carries none.
+     *
+     * The generated response type says `audioContent` is `Uint8Array | string |
+     * null`, and which one arrives depends on how the transport was configured
+     * — so both are handled rather than trusted.
+     */
+    static streamedAudio(response) {
+        if (response === null || typeof response !== "object") {
+            return undefined;
+        }
+        const audioContent = response.audioContent;
+        if (audioContent instanceof Uint8Array) {
+            return audioContent.byteLength > 0
+                ? Buffer.from(audioContent.buffer, audioContent.byteOffset, audioContent.byteLength)
+                : undefined;
+        }
+        if (typeof audioContent === "string" && audioContent.length > 0) {
+            const decoded = Buffer.from(audioContent, "base64");
+            return decoded.length > 0 ? decoded : undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Stream one pre-validated segment's audio as Google produces it.
+     *
+     * Returns `undefined` — the contract's "not incrementally deliverable"
+     * signal — unless the voice and the format are both ones the streaming
+     * endpoint was measured to accept, and the text is not SSML.
+     * `StreamingSynthesisInput` has no `ssml` field at all, so markup that
+     * `synthesize()` would honour has to stay on the buffered path rather than
+     * be sent as literal text.
+     *
+     * Every non-empty response is yielded as it arrives and carries `isFinal:
+     * false`. `TTSProcessor` recomputes indexes, cumulative sizes and finality
+     * globally across segments and discards whatever a handler reports, so
+     * labelling the last response here would buy nothing and would cost a
+     * one-response lookahead.
+     */
+    synthesizeStream(text, options = {}) {
+        const voiceId = options.voice;
+        if (voiceId === undefined ||
+            !GoogleTTSHandler.STREAMING_VOICE_PATTERN.test(voiceId)) {
+            return undefined;
+        }
+        const format = options.format ?? "mp3";
+        const audioEncoding = GoogleTTSHandler.mapStreamingFormat(format);
+        if (audioEncoding === undefined) {
+            return undefined;
+        }
+        if (text.trimStart().startsWith("<speak")) {
+            return undefined;
+        }
+        const languageCode = this.extractLanguageCode(voiceId);
+        const sampleRateHertz = GoogleTTSHandler.STREAMING_SAMPLE_RATE_HZ;
+        const handler = this;
+        // Typed off the client rather than named: Critical Rule 2 puts every type
+        // ALIAS in src/lib/types/, and a gax duplex handle that exists only for
+        // the cancel hook below does not belong in the public type surface.
+        let active;
+        let cancelled = false;
+        let idleTimedOut = false;
+        const stream = (async function* () {
+            const client = await handler.getClient();
+            // `getClient()` can span a dynamic import on a process's first call, a
+            // real gap the `attachStreamCancel` hook below can fire inside. Without
+            // this check, a cancellation that lands before `active` even exists
+            // (it is assigned two lines below) sets `cancelled` and calls
+            // `active?.cancel()` as a no-op, and the generator would carry on and
+            // open a duplex the caller already abandoned.
+            if (cancelled) {
+                return;
+            }
+            const startedAt = Date.now();
+            const duplex = client.streamingSynthesize();
+            active = duplex;
+            let idleTimer;
+            const armIdleTimer = () => {
+                clearTimeout(idleTimer);
+                idleTimer = setTimeout(() => {
+                    idleTimedOut = true;
+                    // `.cancel()`, not `.destroy()`: this object is a
+                    // `gax.CancellableStream` wrapping a real gRPC duplex, and only
+                    // `.cancel()` reaches `ClientDuplexStreamImpl.cancel()` ->
+                    // `call.cancelWithStatus(CANCELLED, ...)`, which actually tells
+                    // Google's server to stop. `.destroy()` only tears down the local
+                    // Node stream — the server-side synthesis (and its billing) keeps
+                    // running until the RPC's own ~5-minute deadline elapses on its
+                    // own.
+                    duplex.cancel();
+                }, GoogleTTSHandler.STREAMING_IDLE_TIMEOUT_MS);
+            };
+            let index = 0;
+            let cumulativeSize = 0;
+            try {
+                duplex.write({
+                    streamingConfig: {
+                        voice: { name: voiceId, languageCode },
+                        streamingAudioConfig: {
+                            audioEncoding,
+                            sampleRateHertz,
+                            speakingRate: options.speed ?? 1.0,
+                        },
+                    },
+                });
+                duplex.write({ input: { text } });
+                duplex.end();
+                armIdleTimer();
+                for await (const response of duplex) {
+                    // Clear rather than re-arm here: the bound is on time spent
+                    // waiting for the SERVER, not on time spent suspended at the
+                    // `yield` below waiting for THIS generator's own consumer. Arming
+                    // unconditionally on every response (the prior behaviour) started
+                    // the clock running before that suspension, so a consumer slower
+                    // than STREAMING_IDLE_TIMEOUT_MS to pull the next chunk destroyed
+                    // a healthy duplex and reported its own backpressure as a network
+                    // stall. The timer is re-armed only once real waiting resumes:
+                    // immediately, for an empty read that loops back to the next
+                    // `duplex` response, or after the consumer has resumed us.
+                    clearTimeout(idleTimer);
+                    const data = GoogleTTSHandler.streamedAudio(response);
+                    if (data === undefined) {
+                        armIdleTimer();
+                        continue;
+                    }
+                    cumulativeSize += data.length;
+                    yield {
+                        data,
+                        format,
+                        index: index++,
+                        isFinal: false,
+                        cumulativeSize,
+                        voice: voiceId,
+                        sampleRate: sampleRateHertz,
+                    };
+                    armIdleTimer();
+                }
+                logger.debug(`[GoogleTTSHandler] Streamed ${cumulativeSize} bytes in ${Date.now() - startedAt}ms`);
+            }
+            catch (err) {
+                if (cancelled) {
+                    // The consumer stopped and the cancel hook destroyed the stream
+                    // underneath an in-flight read. That is not a synthesis failure.
+                    return;
+                }
+                if (err instanceof TTSError) {
+                    throw err;
+                }
+                const message = err instanceof Error ? err.message : "Unknown error";
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                    message: idleTimedOut
+                        ? `Google TTS streaming synthesis stalled for ${GoogleTTSHandler.STREAMING_IDLE_TIMEOUT_MS}ms`
+                        : `Google TTS streaming synthesis failed: ${message}`,
+                    category: idleTimedOut
+                        ? ErrorCategory.NETWORK
+                        : ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: true,
+                    context: { voice: voiceId, audioEncoding },
+                    originalError: err instanceof Error ? err : undefined,
+                });
+            }
+            finally {
+                clearTimeout(idleTimer);
+                active = undefined;
+                // Same reasoning as the idle timer above: `.cancel()` signals the
+                // server this call is done (a no-op on one that already finished
+                // normally), where `.destroy()` only ever tore down the local end.
+                duplex.cancel();
+            }
+        })();
+        return attachStreamCancel(stream, () => {
+            cancelled = true;
+            active?.cancel();
+        });
+    }
     /**
      * Extract language code from a Google Cloud voice name
      *
@@ -306,6 +539,27 @@ export class GoogleTTSHandler {
             case "ogg":
             case "opus":
                 return "OGG_OPUS";
+            case "pcm16":
+                // pcm16 is a real, supported format — just not on THIS (buffered)
+                // endpoint. Reaching this branch means `synthesizeStream()` already
+                // declined the request (wrong voice family, or SSML text, both of
+                // which return `undefined` silently), so a caller who picked a
+                // perfectly valid streaming voice/format pair but tripped the SSML
+                // gate would otherwise see the same generic "unsupported format" as
+                // someone who picked a fundamentally wrong combination. Naming the
+                // actual requirement here, once, is cheaper than threading the
+                // disqualifying reason back from `synthesizeStream()`.
+                throw new TTSError({
+                    code: TTS_ERROR_CODES.INVALID_INPUT,
+                    message: "Google Cloud TTS's buffered synthesis does not support pcm16 output. " +
+                        "pcm16 is only delivered via native streaming, which requires a " +
+                        "Chirp3-HD, Chirp-HD, or Journey voice and plain (non-SSML) text — " +
+                        "check that both conditions hold, or request a different format.",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                    context: { format },
+                });
             default:
                 throw new TTSError({
                     code: TTS_ERROR_CODES.INVALID_INPUT,