@juspay/neurolink 11.25.3 → 11.26.0

package/dist/neurolink.js

@@ -73,6 +73,7 @@ import { getConversationMessages, storeConversationTurn, } from "./utils/convers
 // 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 { interleaveTTSStream } from "./utils/ttsStream.js";
 import { resolveLifecycleTimeoutMs } from "./utils/lifecycleTimeout.js";
 import { cloneOptionsForCallIsolation } from "./utils/cloneOptions.js";
 import { coerceJsonToSchema, recoverScalarRoot, schemaAccepts, } from "./utils/json/coerce.js";
@@ -6376,7 +6377,9 @@ Current user's request: ${currentInput}`;
      *
      * // Consume the stream
      * for await (const chunk of result.stream) {
-     *   process.stdout.write(chunk.content);
+     *   if ("content" in chunk) {
+     *     process.stdout.write(chunk.content);
+     *   }
      * }
      *
      * // Advanced streaming with options
@@ -6684,15 +6687,17 @@ Current user's request: ${currentInput}`;
                 (!!(options.tools && Object.keys(options.tools).length > 0) ||
                     this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options
                 .thinking?.thinkingLevel);
-            // TTS Mode 2 deferred: stream() emits text first, then synthesizes the
-            // accumulated response into a single audio chunk at end-of-stream and
-            // resolves `streamResult.audio` with the same TTSResult. The resolver is
+            // Streaming TTS deferred: stream() always synthesizes the streamed AI
+            // response when TTS is enabled, regardless of generate()'s
+            // input-vs-response `useAiResponse` switch. It resolves
+            // `streamResult.audio` with the aggregate TTSResult. The resolver is
             // plumbed explicitly through the params bag (M11: previously a
             // `_streamTtsResolve` cast on the caller's options object — fragile if
             // the same options object was reused across concurrent stream() calls).
             const ttsOptions = options.tts;
-            const wantsStreamTtsMode2 = !!(ttsOptions?.enabled && ttsOptions?.useAiResponse);
+            const wantsStreamTtsMode2 = ttsOptions?.enabled === true;
             let resolveStreamTtsAudio;
+            let streamTtsMetadata;
             const streamTtsAudioPromise = wantsStreamTtsMode2
                 ? new Promise((resolve) => {
                     resolveStreamTtsAudio = resolve;
@@ -6707,12 +6712,16 @@ Current user's request: ${currentInput}`;
                 streamId,
                 originalPrompt,
                 ttsResolver: resolveStreamTtsAudio,
+                ttsMetadataSink: (metadata) => {
+                    streamTtsMetadata = metadata;
+                },
             })));
             if (streamSttTranscription) {
                 streamResult.transcription = streamSttTranscription;
             }
             if (streamTtsAudioPromise) {
                 streamResult.audio = streamTtsAudioPromise;
+                streamResult.ttsMetadata = streamTtsMetadata;
             }
             return streamResult;
         }
@@ -7243,7 +7252,7 @@ Current user's request: ${currentInput}`;
         return result;
     }
     async runStandardStreamRequest(params) {
-        const { options, streamSpan, spanStartTime, startTime, hrTimeStart, streamId, originalPrompt, ttsResolver, } = params;
+        const { options, streamSpan, spanStartTime, startTime, hrTimeStart, streamId, originalPrompt, ttsResolver, ttsMetadataSink, } = params;
         logger.debug("[NeuroLink] Running standard stream request", {
             streamId,
             provider: options.provider,
@@ -7265,6 +7274,17 @@ Current user's request: ${currentInput}`;
                 sessionId: enhancedOptions.context?.sessionId,
             });
             const { stream: mcpStream, provider: providerName, usage: streamUsage, model: streamModel, finishReason: streamFinishReason, toolCalls: streamToolCalls, toolResults: streamToolResults, analytics: streamAnalytics, metadata: providerStreamMetadata, } = await this.createMCPStream(enhancedOptions);
+            let streamedTTSResult;
+            const { stream: incrementalStream, ttsMetadata: streamTtsMetadata } = await this.createIncrementalTTSStream({
+                stream: mcpStream,
+                ttsOptions: enhancedOptions.tts,
+                providerName,
+                fallbackProvider: enhancedOptions.provider,
+                onComplete: (result) => {
+                    streamedTTSResult = result;
+                },
+            });
+            ttsMetadataSink?.(streamTtsMetadata);
             const streamState = {
                 finishReason: streamFinishReason ?? "stop",
                 toolCalls: streamToolCalls,
@@ -7313,7 +7333,7 @@ Current user's request: ${currentInput}`;
                 // NoOutputGeneratedError, and we want fallback to fire there.
                 let realOutputChunks = 0;
                 try {
-                    for await (const chunk of mcpStream) {
+                    for await (const chunk of incrementalStream) {
                         chunkCount++;
                         const isNoOutputSentinel = chunk !== null &&
                             typeof chunk === "object" &&
@@ -7369,26 +7389,22 @@ Current user's request: ${currentInput}`;
                         !enhancedOptions.disableInternalFallback &&
                         streamState.toolCalls.length === 0 &&
                         streamState.toolResults.length === 0) {
-                        yield* self.handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, (content) => {
+                        const fallbackStream = self.handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, (content) => {
                             accumulatedContent += content;
                         });
+                        const { stream: incrementalFallback } = await self.createIncrementalTTSStream({
+                            stream: fallbackStream,
+                            ttsOptions: enhancedOptions.tts,
+                            providerName,
+                            fallbackProvider: enhancedOptions.provider,
+                            ttsMetadata: streamTtsMetadata,
+                            onComplete: (result) => {
+                                streamedTTSResult = result;
+                            },
+                        });
+                        yield* incrementalFallback;
                     }
-                    // TTS Mode 2 for stream(): synthesize the accumulated response
-                    // and yield ONE final audio chunk so callers iterating the stream
-                    // get the audio inline; also resolve `streamResult.audio` so the
-                    // ergonomic `await result.audio` pattern works post-iteration.
-                    // m5: synthesis logic lives in a dedicated helper to keep this
-                    // generator under the max-lines-per-function lint budget.
-                    const ttsModeResult = await self.synthesizeStreamModeTwo({
-                        ttsOptions: enhancedOptions.tts,
-                        providerName,
-                        fallbackProvider: enhancedOptions.provider,
-                        accumulatedContent,
-                        ttsResolver,
-                    });
-                    if (ttsModeResult.audioChunk) {
-                        yield ttsModeResult.audioChunk;
-                    }
+                    ttsResolver?.(streamedTTSResult);
                     resolvedUsage = streamUsage;
                     if (!resolvedUsage && streamAnalytics) {
                         try {
@@ -7625,72 +7641,70 @@ Current user's request: ${currentInput}`;
             });
         }
         catch (error) {
+            ttsResolver?.(undefined);
             if (options.disableInternalFallback) {
                 throw error;
             }
             return this.handleStreamError(error, options, startTime, streamId, undefined, undefined);
         }
     }
-    /**
-     * TTS Mode 2 synthesis helper for the stream() pipeline.
-     *
-     * m5 — extracted from runStandardStreamRequest so the surrounding generator
-     * stays under the max-lines-per-function lint budget. Behaviour preserved
-     * exactly:
-     * - When Mode 2 is enabled (`tts.enabled && tts.useAiResponse`) AND the
-     *   model produced non-empty content: synthesises one final audio buffer
-     *   and returns it as an `audioChunk` for the caller to `yield`. Resolves
-     *   `ttsResolver` with the `TTSResult`.
-     * - When Mode 2 is enabled but synthesis fails: logs a warning and resolves
-     *   `ttsResolver` with `undefined`.
-     * - When Mode 2 is requested but skipped (empty content / wrong mode):
-     *   resolves `ttsResolver` with `undefined` early so callers awaiting
-     *   `result.audio` unblock before the surrounding `finally` cleanup
-     *   completes (Issue 7 latency micro-opt — the finally block also resolves
-     *   defensively, so this is a redundant early signal, not a coverage fix).
-     */
-    async synthesizeStreamModeTwo(params) {
-        const { ttsOptions, providerName, fallbackProvider, accumulatedContent, ttsResolver, } = params;
-        if (!ttsOptions?.enabled ||
-            !ttsOptions.useAiResponse ||
-            accumulatedContent.trim().length === 0) {
-            ttsResolver?.(undefined);
-            return {};
-        }
-        try {
-            const { TTSProcessor } = await import("./utils/ttsProcessor.js");
-            // ttsOptions.provider takes precedence; otherwise fall back to the
-            // chat provider ID ONLY when it happens to be a registered TTS handler
-            // (e.g. "google-ai" works for both LLM and TTS). For LLM-only IDs like
-            // "anthropic", we'd otherwise complete generation and then fail synth —
-            // surface that mismatch up front instead.
-            const candidate = ttsOptions.provider ?? fallbackProvider ?? providerName;
-            const ttsProvider = candidate && TTSProcessor.supports(candidate) ? candidate : undefined;
-            if (!ttsProvider) {
-                throw new Error(`No TTS provider resolved for stream Mode 2 (set tts.provider explicitly — chat provider "${candidate ?? "<unset>"}" is not a registered TTS handler)`);
-            }
-            const ttsResult = await TTSProcessor.synthesize(accumulatedContent, ttsProvider, ttsOptions);
-            ttsResolver?.(ttsResult);
-            return {
-                audioChunk: {
-                    type: "tts_audio",
-                    audio: {
-                        data: ttsResult.buffer,
-                        format: ttsResult.format,
-                        index: 0,
-                        isFinal: true,
-                        cumulativeSize: ttsResult.size,
-                        voice: ttsResult.voice,
-                        sampleRate: ttsResult.sampleRate,
-                    },
-                },
-            };
+    /** Wrap one provider stream with incremental TTS synthesis. */
+    async createIncrementalTTSStream(params) {
+        const { stream, ttsOptions, providerName, fallbackProvider, onComplete } = params;
+        if (!ttsOptions?.enabled) {
+            onComplete(undefined);
+            return { stream };
+        }
+        const { TTSProcessor } = await import("./utils/ttsProcessor.js");
+        const concreteFallback = fallbackProvider === "auto" ? undefined : fallbackProvider;
+        const candidate = ttsOptions.provider ?? concreteFallback ?? providerName;
+        const ttsProvider = candidate && TTSProcessor.supports(candidate) ? candidate : undefined;
+        const ttsMetadata = params.ttsMetadata ?? {
+            attempted: ttsProvider !== undefined,
+            success: false,
+        };
+        ttsMetadata.attempted = ttsProvider !== undefined;
+        ttsMetadata.success = false;
+        delete ttsMetadata.error;
+        delete ttsMetadata.latency;
+        const ttsStartedAt = Date.now();
+        let completionRecorded = false;
+        const recordCompletion = (result, error) => {
+            if (completionRecorded) {
+                return;
+            }
+            completionRecorded = true;
+            ttsMetadata.success = error === undefined && result !== undefined;
+            if (error) {
+                ttsMetadata.error = error;
+            }
+            else {
+                delete ttsMetadata.error;
+            }
+            ttsMetadata.latency = Date.now() - ttsStartedAt;
+            onComplete(result);
+        };
+        if (!ttsProvider) {
+            logger.warn(`[NeuroLink.stream] No TTS provider resolved for incremental streaming (set tts.provider explicitly — chat provider "${candidate ?? "<unset>"}" is not a registered TTS handler)`);
+            recordCompletion(undefined);
+            return { stream, ttsMetadata };
         }
-        catch (ttsError) {
-            logger.warn(`[NeuroLink.stream] Stream TTS Mode 2 synthesis failed: ${ttsError instanceof Error ? ttsError.message : String(ttsError)}`);
-            ttsResolver?.(undefined);
-            return {};
+        return {
+            stream: interleaveTTSStream({
+                stream,
+                provider: ttsProvider,
+                options: ttsOptions,
+                onComplete: recordCompletion,
+            }),
+            ttsMetadata,
+        };
+    }
+    /** Prevent provider fallback streams from duplicating outer streaming TTS. */
+    deferProviderStreamTTS(options) {
+        if (options.tts?.enabled) {
+            return { ...options, tts: undefined };
         }
+        return options;
     }
     /**
      * Prepare stream options: initialize memory, MCP, retrieval, orchestration,
@@ -7966,7 +7980,7 @@ Current user's request: ${currentInput}`;
                     context: enhancedOptions.context,
                 });
             const fallbackResult = await fallbackProvider.stream({
-                ...enhancedOptions,
+                ...this.deferProviderStreamTTS(enhancedOptions),
                 model: fallbackRoute.model,
                 conversationMessages,
             });
@@ -8395,7 +8409,7 @@ Current user's request: ${currentInput}`;
                         }),
                     }, "NeuroLink.createMCPStream");
                     const poolStreamResult = await poolStreamProvider.stream({
-                        ...options,
+                        ...this.deferProviderStreamTTS(options),
                         provider: poolStreamProviderName,
                         model: poolStreamModel,
                         region: poolStreamRegion,
@@ -8467,7 +8481,7 @@ Current user's request: ${currentInput}`;
         // 🔧 FIX: Pass enhanced system prompt to real streaming
         // Tools will be accessed through the streamText call in executeStream
         const streamResult = await provider.stream({
-            ...options,
+            ...this.deferProviderStreamTTS(options),
             systemPrompt: enhancedSystemPrompt, // Use enhanced prompt with tool descriptions
             conversationMessages,
         });

package/dist/providers/anthropic/client.js

@@ -1738,7 +1738,28 @@ export class AnthropicProvider extends BaseProvider {
                     }
                 }
             })();
-            const result = await resultPromise;
+            // `pump` is detached: it starts draining the engine's channel the moment
+            // it is created, and `await pump` below is the only thing that adopts its
+            // rejection. When resultPromise rejects, that line is never reached, so
+            // pump's rejection stays unhandled — and an unhandled rejection
+            // TERMINATES the consumer's process. Measured: a caller that correctly
+            // try/catches a streaming error still died with ERR_UNHANDLED_REJECTION,
+            // exit code 1, with no way to defend against it from outside this
+            // library. The rejection carried the raw SDK error, distinct from the
+            // formatted one the caller received, which is why the existing
+            // `loopPromise.catch` guard below does not cover it.
+            //
+            // Same shape googleAiStudio/client.ts and googleVertex/client.ts already
+            // use at every one of their pump sites; Anthropic was the only provider
+            // missing it.
+            let result;
+            try {
+                result = await resultPromise;
+            }
+            catch (error) {
+                await pump.catch(() => { });
+                throw error;
+            }
             await pump;
             totalInput += result.usage.inputTokens;
             totalOutput += result.usage.outputTokens;

package/dist/types/stream.d.ts

@@ -10,7 +10,7 @@ import type { JsonValue, UnknownRecord } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage } from "./conversation.js";
 import type { StreamNoOutputSentinel } from "./noOutputSentinel.js";
-import type { AdditionalMemoryUser, GenerateStopReason, ToolExecutionCaptureOptions } from "./generate.js";
+import type { AdditionalMemoryUser, GenerateStopReason, TTSMetadata, ToolExecutionCaptureOptions } from "./generate.js";
 import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js";
 import type { TTSChunk, TTSOptions, TTSResult } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
@@ -169,6 +169,21 @@ export type StreamChunk = {
     /** TTS audio chunk data */
     audio: TTSChunk;
 };
+/** Provider-level chunks accepted by NeuroLink's core streaming pipeline. */
+export type ProviderStreamChunk = {
+    content: string;
+} | {
+    type: "audio";
+    audio: AudioChunk;
+} | {
+    type: "tts_audio";
+    audio: TTSChunk;
+} | {
+    type: "image";
+    imageOutput: {
+        base64: string;
+    };
+};
 export type StreamOptions = {
     /**
      * Opt this stream call into the knowledge grounding configured on the
@@ -699,13 +714,36 @@ export type StreamResult = {
     /** STT transcription result (when stt option is used) */
     transcription?: STTResult;
     /**
-     * TTS Mode 2 result (when `tts.enabled && tts.useAiResponse`).
-     * Resolves with the synthesized audio after the stream completes;
-     * resolves to undefined if TTS was not enabled or synthesis failed.
-     * The same audio is also yielded as a final chunk on `stream` for callers
-     * that prefer to consume it inline.
+     * Streaming TTS result (when `tts.enabled`). `stream()` synthesizes the AI
+     * response incrementally; `useAiResponse` continues to select input vs
+     * response synthesis for non-streaming generation.
+     * Resolves with the synthesized audio after the caller drains `stream` to
+     * completion; like other stream-final fields, it remains pending while the
+     * lazy stream is unconsumed. It resolves with the aggregate of whatever
+     * segments were synthesized: a synthesis failure part-way through still
+     * resolves with the earlier segments rather than discarding them. It resolves
+     * to undefined only when no segment was produced — TTS was not enabled, no
+     * handler resolved for the requested provider, the model stream errored, every
+     * synthesis failed, or the caller stopped draining `stream` before it ended
+     * (an abandoned stream settles undefined rather than a partial aggregate).
+     * Audio is also yielded incrementally as ordered
+     * `tts_audio` chunks. Each chunk, including the final one, contains only its
+     * own buffered segment. The aggregate is a byte concatenation of those
+     * independently synthesized segments, so what it is depends on the format's
+     * framing: for frame- or sample-stream formats (`mp3`, `mpeg`, `mpga`,
+     * `pcm16`) it is one playable stream; for header-bearing container formats
+     * (`wav`, `flac`, `m4a`, `mp4`, `webm`) it is not a valid file, because each
+     * segment carries its own header; for `ogg`/`opus` it is a chained stream that
+     * some decoders read only through its first segment. Use the individual chunk
+     * buffers when each segment must be a valid container file.
      */
     audio?: Promise<TTSResult | undefined>;
+    /**
+     * Outcome metadata for streaming TTS synthesis. This is a mutable reference
+     * whose success and latency fields are finalized asynchronously; read it
+     * after draining `stream`.
+     */
+    ttsMetadata?: TTSMetadata;
 };
 /**
  * Enhanced provider type with stream method

package/dist/types/tts.d.ts

@@ -34,6 +34,9 @@ export type TTSOptions = {
     /**
      * Use the AI-generated response for TTS instead of the input text
      *
+     * This switch applies to non-streaming generation. `stream()` always
+     * synthesizes the streamed AI response incrementally when TTS is enabled.
+     *
      * When false or undefined (default): TTS will synthesize the input text/prompt directly without calling AI generation
      * When true: TTS will synthesize the AI-generated response after generation completes
      *
@@ -78,6 +81,12 @@ export type TTSOptions = {
     play?: boolean;
     /** Override TTS provider (e.g., "elevenlabs", "openai-tts", "azure-tts") */
     provider?: TTSProviderName;
+    /**
+     * Minimum buffered text length before incremental stream synthesis flushes
+     * at a sentence boundary. The provider's maximum text length remains a hard
+     * upper bound. Defaults to 120 characters.
+     */
+    streamingBufferSize?: number;
 };
 /**
  * TTS audio result returned from generation

package/dist/types/tts.js

@@ -60,5 +60,11 @@ export function isValidTTSOptions(options) {
             return false;
         }
     }
+    if (opts.streamingBufferSize !== undefined) {
+        if (!Number.isInteger(opts.streamingBufferSize) ||
+            opts.streamingBufferSize < 1) {
+            return false;
+        }
+    }
     return true;
 }

package/dist/utils/ttsProcessor.d.ts

@@ -6,7 +6,7 @@
  *
  * @module utils/ttsProcessor
  */
-import type { TTSOptions, TTSResult, TTSHandler } from "../types/index.js";
+import type { TTSChunk, TTSOptions, TTSResult, TTSHandler } from "../types/index.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { NeuroLinkError } from "./errorHandling.js";
 /**
@@ -20,6 +20,12 @@ export declare const TTS_ERROR_CODES: {
     readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
     readonly INVALID_INPUT: "TTS_INVALID_INPUT";
 };
+/** Internal signal raised after all buffered segments have been attempted. */
+export declare class IncrementalTTSSynthesisError extends Error {
+    readonly firstError: unknown;
+    readonly failedSegments: readonly number[];
+    constructor(firstError: unknown, failedSegments: number[]);
+}
 /**
  * TTS Error class for text-to-speech specific errors
  */
@@ -156,4 +162,17 @@ export declare class TTSProcessor {
      * ```
      */
     static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Incrementally synthesize sentence-buffered text chunks.
+     *
+     * Text is flushed at a sentence boundary after `streamingBufferSize`
+     * characters, or hard-split before the provider's maximum text length.
+     * Each segment goes through `synthesize()`, preserving the existing handler
+     * registry, validation, error normalization, and telemetry seam.
+     *
+     * The most recent successful audio chunk is held until another succeeds or
+     * the input ends, so exactly one real audio chunk carries `isFinal: true`
+     * without emitting a separate empty terminator chunk.
+     */
+    static synthesizeStream(textChunks: AsyncIterable<string>, provider: string, options: TTSOptions, shouldStop?: () => boolean): AsyncGenerator<TTSChunk>;
 }

package/dist/utils/ttsProcessor.js

@@ -22,6 +22,75 @@ export const TTS_ERROR_CODES = {
     SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
     INVALID_INPUT: "TTS_INVALID_INPUT",
 };
+const DEFAULT_STREAMING_BUFFER_SIZE = 120;
+const SENTENCE_BOUNDARY = /[.!?]+(?:["')\]]+)?(?=\s|$)/g;
+/** Internal signal raised after all buffered segments have been attempted. */
+export class IncrementalTTSSynthesisError extends Error {
+    firstError;
+    failedSegments;
+    constructor(firstError, failedSegments) {
+        super(`Incremental TTS failed for ${failedSegments.length} segment${failedSegments.length === 1 ? "" : "s"}`);
+        this.name = "IncrementalTTSSynthesisError";
+        this.firstError = firstError;
+        this.failedSegments = [...failedSegments];
+    }
+}
+function findSentenceEnds(text) {
+    const ends = [];
+    for (const match of text.matchAll(SENTENCE_BOUNDARY)) {
+        ends.push((match.index ?? 0) + match[0].length);
+    }
+    return ends;
+}
+const HIGH_SURROGATE_START = 0xd800;
+const HIGH_SURROGATE_END = 0xdbff;
+const LOW_SURROGATE_START = 0xdc00;
+const LOW_SURROGATE_END = 0xdfff;
+/**
+ * Move a split index off the middle of a surrogate pair.
+ *
+ * The cap is measured in UTF-16 code units, so a hard split can land between
+ * the two halves of an astral character (emoji, rarer CJK). That would end one
+ * segment with a lone high surrogate and start the next with its low half, and
+ * providers receive U+FFFD instead of the character. Backing the split off by
+ * one code unit keeps the pair whole in the next segment.
+ *
+ * A split at index 1 is left alone: backing off would yield an empty segment
+ * with an unchanged remainder, and a cap that small cannot hold the pair anyway.
+ */
+function avoidSurrogateSplit(text, splitAt) {
+    if (splitAt <= 1 || splitAt >= text.length) {
+        return splitAt;
+    }
+    const high = text.charCodeAt(splitAt - 1);
+    const low = text.charCodeAt(splitAt);
+    const splitsPair = high >= HIGH_SURROGATE_START &&
+        high <= HIGH_SURROGATE_END &&
+        low >= LOW_SURROGATE_START &&
+        low <= LOW_SURROGATE_END;
+    return splitsPair ? splitAt - 1 : splitAt;
+}
+function takeBufferedSegment(buffer, flushBoundary, maxTextLength, inputComplete) {
+    const cappedText = buffer.slice(0, maxTextLength);
+    const sentenceEnds = findSentenceEnds(cappedText);
+    let splitAt = buffer.length >= flushBoundary ? sentenceEnds.at(-1) : undefined;
+    if (splitAt === undefined && buffer.length >= maxTextLength) {
+        splitAt = sentenceEnds.at(-1) ?? maxTextLength;
+    }
+    if (splitAt === undefined && inputComplete && buffer.trim()) {
+        splitAt = Math.min(buffer.length, maxTextLength);
+    }
+    if (splitAt === undefined) {
+        return undefined;
+    }
+    splitAt = avoidSurrogateSplit(buffer, splitAt);
+    const segment = buffer.slice(0, splitAt).trim();
+    const remainder = buffer.slice(splitAt).trimStart();
+    if (!segment) {
+        return { segment: "", remainder };
+    }
+    return { segment, remainder };
+}
 /**
  * TTS Error class for text-to-speech specific errors
  */
@@ -289,4 +358,102 @@ export class TTSProcessor {
             });
         }
     }
+    /**
+     * Incrementally synthesize sentence-buffered text chunks.
+     *
+     * Text is flushed at a sentence boundary after `streamingBufferSize`
+     * characters, or hard-split before the provider's maximum text length.
+     * Each segment goes through `synthesize()`, preserving the existing handler
+     * registry, validation, error normalization, and telemetry seam.
+     *
+     * The most recent successful audio chunk is held until another succeeds or
+     * the input ends, so exactly one real audio chunk carries `isFinal: true`
+     * without emitting a separate empty terminator chunk.
+     */
+    static async *synthesizeStream(textChunks, provider, options, shouldStop) {
+        const handler = this.getHandler(provider);
+        const maxTextLength = Math.max(1, handler?.maxTextLength ?? this.DEFAULT_MAX_TEXT_LENGTH);
+        const requestedBoundary = options.streamingBufferSize ?? DEFAULT_STREAMING_BUFFER_SIZE;
+        const flushBoundary = Math.min(Math.max(1, Math.trunc(requestedBoundary)), maxTextLength);
+        let buffer = "";
+        let chunkIndex = 0;
+        let cumulativeSize = 0;
+        let cumulativeDuration = 0;
+        let pendingChunk;
+        let segmentNumber = 0;
+        let firstFailure;
+        const failedSegments = [];
+        const synthesizeSegment = async (segment) => {
+            const currentSegment = ++segmentNumber;
+            try {
+                const result = await this.synthesize(segment, provider, options);
+                cumulativeSize += result.size;
+                cumulativeDuration += result.duration ?? 0;
+                return {
+                    data: result.buffer,
+                    format: result.format,
+                    index: chunkIndex++,
+                    isFinal: false,
+                    cumulativeSize,
+                    estimatedDuration: cumulativeDuration || undefined,
+                    voice: result.voice,
+                    sampleRate: result.sampleRate,
+                };
+            }
+            catch (error) {
+                if (failedSegments.length === 0) {
+                    firstFailure = error;
+                }
+                failedSegments.push(currentSegment);
+                logger.warn(`[TTSProcessor] Incremental synthesis skipped a buffered segment: ${error instanceof Error ? error.message : String(error)}`);
+                return undefined;
+            }
+        };
+        for await (const textChunk of textChunks) {
+            if (shouldStop?.()) {
+                break;
+            }
+            buffer += textChunk;
+            while (!shouldStop?.()) {
+                const buffered = takeBufferedSegment(buffer, flushBoundary, maxTextLength, false);
+                if (!buffered) {
+                    break;
+                }
+                buffer = buffered.remainder;
+                if (!buffered.segment) {
+                    continue;
+                }
+                const chunk = await synthesizeSegment(buffered.segment);
+                if (chunk) {
+                    if (pendingChunk) {
+                        yield pendingChunk;
+                    }
+                    pendingChunk = chunk;
+                }
+            }
+        }
+        while (!shouldStop?.()) {
+            const buffered = takeBufferedSegment(buffer, flushBoundary, maxTextLength, true);
+            if (!buffered) {
+                break;
+            }
+            buffer = buffered.remainder;
+            if (!buffered.segment) {
+                continue;
+            }
+            const chunk = await synthesizeSegment(buffered.segment);
+            if (chunk) {
+                if (pendingChunk) {
+                    yield pendingChunk;
+                }
+                pendingChunk = chunk;
+            }
+        }
+        if (pendingChunk) {
+            yield { ...pendingChunk, isFinal: true };
+        }
+        if (failedSegments.length > 0) {
+            throw new IncrementalTTSSynthesisError(firstFailure, failedSegments);
+        }
+    }
 }

package/dist/utils/ttsStream.d.ts

@@ -0,0 +1,15 @@
+import type { TTSChunk, TTSMetadata, TTSOptions, TTSResult } from "../types/index.js";
+/**
+ * Preserve source-stream backpressure while interleaving incremental TTS audio.
+ * Source chunks are yielded before their derived audio, and TTS failures degrade
+ * to the unchanged source stream.
+ */
+export declare function interleaveTTSStream<T>(params: {
+    stream: AsyncIterable<T>;
+    provider: string;
+    options: TTSOptions;
+    onComplete?: (result: TTSResult | undefined, error?: NonNullable<TTSMetadata["error"]>) => void;
+}): AsyncGenerator<T | {
+    type: "tts_audio";
+    audio: TTSChunk;
+}>;