@juspay/neurolink 11.25.4 → 11.26.0

package/dist/core/baseProvider.d.ts

@@ -72,6 +72,11 @@ export declare abstract class BaseProvider implements AIProvider {
      * that supplied `onError`).
      */
     private fireLifecycleErrorCallback;
+    /**
+     * Build the fake-stream output and apply the same incremental TTS wrapper
+     * used by the standard NeuroLink stream path.
+     */
+    private createFakeStreamingOutput;
     /**
      * Execute fake streaming - extracted method for reusability
      */

package/dist/core/baseProvider.js

@@ -1,6 +1,6 @@
 import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { directAgentTools } from "../agent/directTools.js";
-import { isImageGenerationModel } from "../core/constants.js";
+import { isImageGenerationModel } from "./constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { ATTR, tracers } from "../telemetry/index.js";
@@ -13,6 +13,7 @@ import { duckTypedStatusCode, extractRetryAfterMsFromError, } from "../utils/pro
 import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
+import { interleaveTTSStream } from "../utils/ttsStream.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";
@@ -486,6 +487,61 @@ export class BaseProvider {
             logger.warn("[lifecycle] onError callback error:", e);
         }
     }
+    /**
+     * Build the fake-stream output and apply the same incremental TTS wrapper
+     * used by the standard NeuroLink stream path.
+     */
+    createFakeStreamingOutput(result, options, onTTSComplete) {
+        const incrementalTTS = options.tts?.enabled === true;
+        const source = (async function* () {
+            if (result?.content) {
+                const words = result.content.split(/(\s+)/);
+                let buffer = "";
+                for (let i = 0; i < words.length; i++) {
+                    buffer += words[i];
+                    const shouldYield = i === words.length - 1 ||
+                        buffer.length > 50 ||
+                        /[.!?;,]\s*$/.test(buffer);
+                    if (shouldYield && buffer.trim()) {
+                        yield { content: buffer };
+                        buffer = "";
+                        await new Promise((resolve) => {
+                            setTimeout(resolve, Math.random() * 9 + 1);
+                        });
+                    }
+                }
+                if (buffer.trim()) {
+                    yield { content: buffer };
+                }
+            }
+            if (result?.imageOutput) {
+                yield { type: "image", imageOutput: result.imageOutput };
+            }
+            if (result?.audio && !incrementalTTS) {
+                yield {
+                    type: "tts_audio",
+                    audio: {
+                        data: result.audio.buffer,
+                        format: result.audio.format,
+                        index: 0,
+                        isFinal: true,
+                        cumulativeSize: result.audio.size,
+                        voice: result.audio.voice,
+                        sampleRate: result.audio.sampleRate,
+                    },
+                };
+            }
+        })();
+        if (!incrementalTTS || !options.tts) {
+            return source;
+        }
+        return interleaveTTSStream({
+            stream: source,
+            provider: options.tts.provider ?? options.provider ?? this.providerName,
+            options: options.tts,
+            onComplete: onTTSComplete,
+        });
+    }
     /**
      * Execute fake streaming - extracted method for reusability
      */
@@ -525,10 +581,10 @@ export class BaseProvider {
                 skipToolPromptInjection: options.skipToolPromptInjection,
                 timeout: options.timeout,
                 stt: options.stt,
-                // Forward TTS options too — without this, the fake-streaming fallback
-                // path silently drops `tts` and the resulting StreamResult never
-                // produces a `tts_audio` chunk even when synthesis was requested.
-                tts: options.tts,
+                // Streaming TTS is synthesized incrementally by
+                // createFakeStreamingOutput; do not let generate() perform a duplicate
+                // input- or whole-response synthesis first.
+                tts: options.tts?.enabled ? undefined : options.tts,
             };
             logger.debug(`Calling generate for fake streaming`, {
                 provider: this.providerName,
@@ -545,58 +601,45 @@ export class BaseProvider {
                 hasImageOutput: !!result?.imageOutput,
                 timestamp: Date.now(),
             });
-            // Create a synthetic stream from the generate result that simulates progressive delivery
-            return {
-                stream: (async function* () {
-                    if (result?.content) {
-                        // Split content into words for more natural streaming
-                        const words = result.content.split(/(\s+)/); // Keep whitespace
-                        let buffer = "";
-                        for (let i = 0; i < words.length; i++) {
-                            buffer += words[i];
-                            // Yield chunks of roughly 5-10 words or at punctuation
-                            const shouldYield = i === words.length - 1 || // Last word
-                                buffer.length > 50 || // Buffer getting long
-                                /[.!?;,]\s*$/.test(buffer); // End of sentence/clause
-                            if (shouldYield && buffer.trim()) {
-                                yield { content: buffer };
-                                buffer = "";
-                                // Small delay to simulate streaming (1-10ms)
-                                await new Promise((resolve) => {
-                                    setTimeout(resolve, Math.random() * 9 + 1);
-                                });
-                            }
+            const incrementalTTS = options.tts?.enabled === true;
+            const ttsProvider = options.tts?.provider ?? options.provider ?? this.providerName;
+            const ttsStartedAt = Date.now();
+            let resolveAudio;
+            let audioSettled = false;
+            const audio = incrementalTTS
+                ? new Promise((resolve) => {
+                    resolveAudio = resolve;
+                }).catch(() => undefined)
+                : undefined;
+            const ttsMetadata = incrementalTTS
+                ? {
+                    attempted: TTSProcessor.supports(ttsProvider),
+                    success: false,
+                }
+                : result?.ttsMetadata;
+            const onTTSComplete = incrementalTTS
+                ? (ttsResult, error) => {
+                    if (audioSettled) {
+                        return;
+                    }
+                    audioSettled = true;
+                    if (ttsMetadata) {
+                        ttsMetadata.success =
+                            error === undefined && ttsResult !== undefined;
+                        if (error) {
+                            ttsMetadata.error = error;
                         }
-                        // Yield all remaining content
-                        if (buffer.trim()) {
-                            yield { content: buffer };
+                        else {
+                            delete ttsMetadata.error;
                         }
+                        ttsMetadata.latency = Date.now() - ttsStartedAt;
                     }
-                    // 🔧 CRITICAL FIX: Yield image output if present
-                    if (result?.imageOutput) {
-                        yield {
-                            type: "image",
-                            imageOutput: result.imageOutput,
-                        };
-                    }
-                    // Yield synthesized audio so callers using stream() with tts.enabled
-                    // still receive a tts_audio chunk on the fake-streaming fallback
-                    // path (matches the discriminator used by the real streaming path).
-                    if (result?.audio) {
-                        yield {
-                            type: "tts_audio",
-                            audio: {
-                                data: result.audio.buffer,
-                                format: result.audio.format,
-                                index: 0,
-                                isFinal: true,
-                                cumulativeSize: result.audio.size,
-                                voice: result.audio.voice,
-                                sampleRate: result.audio.sampleRate,
-                            },
-                        };
-                    }
-                })(),
+                    resolveAudio?.(ttsResult);
+                }
+                : undefined;
+            // Create a synthetic stream from the generate result that simulates progressive delivery
+            return {
+                stream: this.createFakeStreamingOutput(result, options, onTTSComplete),
                 usage: result?.usage,
                 provider: result?.provider,
                 model: result?.model,
@@ -618,6 +661,8 @@ export class BaseProvider {
                 // 🔧 FIX: Include analytics and evaluation from generate result
                 analytics: result?.analytics,
                 evaluation: result?.evaluation,
+                audio,
+                ttsMetadata,
             };
         }
         catch (error) {

package/dist/neurolink.d.ts

@@ -945,7 +945,9 @@ export declare class NeuroLink {
      *
      * // 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
@@ -1031,25 +1033,10 @@ export declare class NeuroLink {
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
     private runStandardStreamRequest;
-    /**
-     * 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).
-     */
-    private synthesizeStreamModeTwo;
+    /** Wrap one provider stream with incremental TTS synthesis. */
+    private createIncrementalTTSStream;
+    /** Prevent provider fallback streams from duplicating outer streaming TTS. */
+    private deferProviderStreamTTS;
     /**
      * Prepare stream options: initialize memory, MCP, retrieval, orchestration,
      * Ollama tool auto-disable, factory processing, and tool detection.

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/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;
 }