@juspay/neurolink 11.25.4 → 11.26.1

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/routing/classifierRouter.js

@@ -160,7 +160,13 @@ export class ClassifierRouter {
         const mode = DIFFICULTY_RANK_MODE[difficulty];
         const originalIndex = new Map(members.map((m, i) => [m, i]));
         const num = (v) => (typeof v === "number" ? v : NEUTRAL);
-        return [...members].sort((a, b) => {
+        const isFullyUnmeasured = (m) => {
+            const meta = this.metaFor(m);
+            return meta.cost === undefined && meta.quality === undefined;
+        };
+        const measured = members.filter((m) => !isFullyUnmeasured(m));
+        const unmeasured = members.filter(isFullyUnmeasured);
+        const sortMeasured = (pool) => [...pool].sort((a, b) => {
             const ma = this.metaFor(a);
             const mb = this.metaFor(b);
             let delta;
@@ -185,6 +191,11 @@ export class ClassifierRouter {
             // Stable: preserve declared pool order on a tie.
             return (originalIndex.get(a) ?? 0) - (originalIndex.get(b) ?? 0);
         });
+        // The unmeasured bucket ranks after every measured member, but WITHIN the
+        // bucket the same comparator still applies: with cost/quality both
+        // NEUTRAL it falls through to the weight tie-break, preserving the
+        // documented weight contract that a plain append would silently drop.
+        return [...sortMeasured(measured), ...sortMeasured(unmeasured)];
     }
     /** Tool narrowing: per-difficulty directive, then classifier hints. */
     selectTools(decision) {
@@ -223,7 +234,10 @@ export class ClassifierRouter {
         if (needsEnrichment && member.model) {
             try {
                 const info = ModelResolver.resolveModel(member.model);
-                if (info) {
+                if (!info) {
+                    this.deps.logger?.debug?.(`[ClassifierRouter] metaFor: no registry match for ${member.provider}/${member.model}`);
+                }
+                else {
                     if (cost === undefined) {
                         cost = info.pricing.inputCostPer1K + info.pricing.outputCostPer1K;
                     }
@@ -251,8 +265,8 @@ export class ClassifierRouter {
                     }
                 }
             }
-            catch {
-                // Enrichment is best-effort; ignore registry lookup failures.
+            catch (err) {
+                this.deps.logger?.warn?.(`[ClassifierRouter] metaFor: registry lookup threw for ${member.provider}/${member.model}`, { error: err instanceof Error ? err.message : String(err) });
             }
         }
         const meta = { cost, quality, capabilities };

package/dist/types/providers.d.ts

@@ -1885,6 +1885,24 @@ export type ProviderDescriptor = {
     localRuntime: boolean;
     /** How ProviderHealthChecker should verify this provider is reachable. */
     healthCheck: "env-only" | "models-probe" | "live-generate";
+    /**
+     * Membership + order in the default health sweep
+     * (`ProviderHealthChecker.checkAllProvidersHealth` with no explicit
+     * list). Lower number = checked and reported first; the sweep's array
+     * order is behaviour for its first-healthy fallback consumers. Absent =
+     * not part of the default sweep. Replaces the hand-maintained 8-provider
+     * array that lived in providerHealth.ts.
+     */
+    defaultHealthSweepPriority?: number;
+    /**
+     * Preference rank for `getBestHealthyProvider`'s default auto-selection
+     * (lower = tried first). Deliberately a SEPARATE ordering from the sweep:
+     * auto-select prefers local/cheap runtimes (litellm, ollama) before cloud
+     * providers, while the sweep reports the majors first. Absent = not in
+     * the default preference list. Replaces the second hand-maintained array
+     * that lived inline as getBestHealthyProvider's default parameter.
+     */
+    autoSelectPreference?: number;
     setupUrl?: string;
     timeouts?: {
         generateMs?: number;

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/providerHealth.js

@@ -9,6 +9,7 @@ import { basename } from "path";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
 import { ProviderFactory } from "../factories/providerFactory.js";
+import { PROVIDER_DESCRIPTORS } from "../factories/providerDescriptors.js";
 export class ProviderHealthChecker {
     static healthCache = new Map();
     static DEFAULT_TIMEOUT = 5000; // 5 seconds
@@ -1382,16 +1383,13 @@ export class ProviderHealthChecker {
      * Prioritizes healthy providers over configured but unhealthy ones
      * Uses fast, cached health checks to avoid blocking initialization
      */
-    static async getBestHealthyProvider(preferredProviders = [
-        "litellm",
-        "ollama",
-        "openai",
-        "anthropic",
-        "vertex",
-        "google-ai",
-        "bedrock",
-        "azure",
-    ]) {
+    static async getBestHealthyProvider(
+    // Auto-select preference comes from the descriptors too — a SEPARATE
+    // ordering from the sweep (local/cheap runtimes first), carried by
+    // autoSelectPreference rather than defaultHealthSweepPriority.
+    preferredProviders = PROVIDER_DESCRIPTORS.filter((d) => d.autoSelectPreference !== undefined)
+        .sort((a, b) => (a.autoSelectPreference ?? 0) - (b.autoSelectPreference ?? 0))
+        .map((d) => d.name)) {
         const healthStatuses = await this.checkAllProvidersHealth({
             includeConnectivityTest: false, // Quick config check only
             cacheResults: true,
@@ -1424,16 +1422,13 @@ export class ProviderHealthChecker {
      * Get health status for all registered providers
      */
     static async checkAllProvidersHealth(options = {}) {
-        const providers = [
-            AIProviderName.VERTEX,
-            AIProviderName.GOOGLE_AI,
-            AIProviderName.ANTHROPIC,
-            AIProviderName.OPENAI,
-            AIProviderName.BEDROCK,
-            AIProviderName.AZURE,
-            AIProviderName.LITELLM,
-            AIProviderName.OLLAMA,
-        ];
+        // Sweep membership and ORDER come from the descriptors. Order is
+        // behaviour: auto-select takes the first healthy provider, so the
+        // priority field, not the descriptor array's layout, decides preference.
+        const providers = PROVIDER_DESCRIPTORS.filter((d) => d.defaultHealthSweepPriority !== undefined)
+            .sort((a, b) => (a.defaultHealthSweepPriority ?? 0) -
+            (b.defaultHealthSweepPriority ?? 0))
+            .map((d) => d.name);
         const healthChecks = providers.map((provider) => this.checkProviderHealth(provider, options));
         const results = await Promise.allSettled(healthChecks);
         return results.map((result, index) => {

package/dist/utils/retryHandler.d.ts

@@ -13,17 +13,6 @@ import type { RetryOptions } from "../types/index.js";
  * @returns Calculated delay in milliseconds
  */
 export declare function calculateBackoffDelay(attempt: number, initialDelay?: number, multiplier?: number, maxDelay?: number, addJitter?: boolean): number;
-/**
- * Error types that are typically retryable
- */
-export declare class NetworkError extends Error {
-    readonly cause?: Error | undefined;
-    constructor(message: string, cause?: Error | undefined);
-}
-export declare class TemporaryError extends Error {
-    readonly cause?: Error | undefined;
-    constructor(message: string, cause?: Error | undefined);
-}
 /**
  * Default retry configuration
  */

package/dist/utils/retryHandler.js

@@ -4,6 +4,7 @@
  */
 import { logger } from "./logger.js";
 import { SYSTEM_LIMITS } from "../core/constants.js";
+import { NetworkError } from "../types/index.js";
 /**
  * Calculate exponential backoff delay with jitter
  * @param attempt - Current attempt number (1-based)
@@ -24,25 +25,6 @@ export function calculateBackoffDelay(attempt, initialDelay = SYSTEM_LIMITS.DEFA
         : 0;
     return cappedDelay + jitter;
 }
-/**
- * Error types that are typically retryable
- */
-export class NetworkError extends Error {
-    cause;
-    constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-        this.name = "NetworkError";
-    }
-}
-export class TemporaryError extends Error {
-    cause;
-    constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-        this.name = "TemporaryError";
-    }
-}
 /**
  * Default retry configuration
  */
@@ -52,8 +34,11 @@ export const DEFAULT_RETRY_CONFIG = {
     maxDelay: SYSTEM_LIMITS.DEFAULT_MAX_DELAY,
     backoffMultiplier: SYSTEM_LIMITS.DEFAULT_BACKOFF_MULTIPLIER,
     retryCondition: (error) => {
-        // Retry on network errors, timeouts, and specific HTTP errors
-        if (error instanceof NetworkError || error instanceof TemporaryError) {
+        // Retry on network errors, timeouts, and specific HTTP errors. The
+        // instanceof now matches the canonical types/errors.js NetworkError —
+        // the local shadow class this file used to declare matched nothing the
+        // rest of the SDK ever threw.
+        if (error instanceof NetworkError) {
             return true;
         }
         // Retry on timeout errors

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