@juspay/neurolink 11.2.3 → 11.3.0

package/dist/providers/openaiChatCompletionsBase.js

@@ -36,7 +36,8 @@ import { resolveToolChoice } from "../utils/toolChoice.js";
 import { transformToolExecutions } from "../utils/transformationUtils.js";
 import { withProviderRetry } from "../utils/providerRetry.js";
 import { resolveDeferredTool } from "../tools/toolDiscovery.js";
-import { buildAPIError, buildBody, buildToolsForOpenAI, buildWireToolNameMaps, createChunkQueue, createDeferredAnalytics, ensureJsonWordInBody, estimateWireTokens, mapNeuroLinkToolChoice, mergeUsage, messageBuilderToOpenAI, parseSSEStream, stringifyToolOutput, stripTrailingSlash, v3ResponseFormatToOpenAI, v3ToolChoiceToOpenAI, v3ToolsToOpenAI, } from "./openaiChatCompletionsClient.js";
+import { buildAPIError, buildBody, buildToolsForOpenAI, buildWireToolNameMaps, createDeferredAnalytics, ensureJsonWordInBody, estimateWireTokens, mapNeuroLinkToolChoice, mergeUsage, messageBuilderToOpenAI, parseSSEStream, stringifyToolOutput, stripTrailingSlash, v3ResponseFormatToOpenAI, v3ToolChoiceToOpenAI, v3ToolsToOpenAI, } from "./openaiChatCompletionsClient.js";
+import { createStreamChannel } from "../core/streamChannel.js";
 /**
  * Safety margin (tokens) when fitting `max_tokens` to a runtime-discovered
  * context window: the char-based input estimate and the backend's own prompt
@@ -647,7 +648,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         const toolsUsed = [];
         const toolExecutionSummaries = [];
         const { usagePromise, finishPromise, resolveUsage, resolveFinish } = createDeferredAnalytics();
-        const { pushChunk, nextChunk } = createChunkQueue();
+        const channel = createStreamChannel();
         // Per-provider lifecycle hook (e.g. OTel span wrap for LiteLLM).
         const lifecycle = this.onStreamStart(modelId);
         const loopPromise = this.runStreamLoop({
@@ -665,7 +666,8 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             emitter,
             toolsUsed,
             toolExecutionSummaries,
-            pushChunk,
+            pushChunk: channel.push,
+            closeChannel: channel.close,
             resolveUsage,
             resolveFinish,
         });
@@ -695,11 +697,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         const transformedStream = async function* () {
             let contentYielded = 0;
             try {
-                for (;;) {
-                    const chunk = await nextChunk();
-                    if ("done" in chunk) {
-                        break;
-                    }
+                for await (const chunk of channel.iterable) {
                     if ("content" in chunk &&
                         typeof chunk.content === "string" &&
                         chunk.content.length > 0) {
@@ -707,7 +705,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                     }
                     yield chunk;
                 }
-                // Surface any error that the loop threw after we drained the queue.
+                // Surface any error that the loop threw after we drained the channel.
                 await loopPromise;
                 // No-output path: stream completed normally but yielded zero text.
                 // Build an enriched sentinel + stamp the active OTel span so
@@ -782,7 +780,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         return result;
     }
     async runStreamLoop(args) {
-        const { maxSteps, modelId, url, fetchImpl, abortSignal, options, conversation, openAITools, openAIToolChoice, toolsRecord, toolNameFromWire, emitter, toolsUsed, toolExecutionSummaries, pushChunk, resolveUsage, resolveFinish, } = args;
+        const { maxSteps, modelId, url, fetchImpl, abortSignal, options, conversation, openAITools, openAIToolChoice, toolsRecord, toolNameFromWire, emitter, toolsUsed, toolExecutionSummaries, pushChunk, closeChannel, resolveUsage, resolveFinish, } = args;
         // Hoisted above the try so the catch can resolve the usage accumulated
         // by steps that completed BEFORE the failure — those steps were billed.
         let stepFinish = null;
@@ -905,7 +903,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             }
             resolveUsage(toDeferredUsage());
             resolveFinish(stepFinish ?? "stop");
-            pushChunk({ done: true });
+            closeChannel();
             return {
                 finishReason: stepFinish ?? "stop",
                 usage: stepUsage,
@@ -919,7 +917,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             // instead of zeroing the whole turn.
             resolveUsage(toDeferredUsage());
             resolveFinish("error");
-            pushChunk({ done: true });
+            closeChannel();
             throw err;
         }
     }

package/dist/providers/openaiChatCompletionsClient.d.ts

@@ -13,7 +13,7 @@
  * Nothing here imports from "ai" or "@ai-sdk/*". The whole point of this
  * module is to be the native replacement for the AI SDK's OpenAI wrapper.
  */
-import type { OpenAICompatBuildBodyArgs, OpenAICompatChatMessage, OpenAICompatChatRequest, OpenAICompatChatTool, OpenAICompatMessage, OpenAICompatMessageContent, OpenAICompatResponseFormat, OpenAICompatSSEResult, OpenAICompatStreamChunk, OpenAICompatToolChoiceWire, OpenAICompatUsage, OpenAICompatV3CallToolChoice, OpenAICompatV3CallTools, DeferredUsage, Tool } from "../types/index.js";
+import type { OpenAICompatBuildBodyArgs, OpenAICompatChatMessage, OpenAICompatChatRequest, OpenAICompatChatTool, OpenAICompatMessage, OpenAICompatMessageContent, OpenAICompatResponseFormat, OpenAICompatSSEResult, OpenAICompatToolChoiceWire, OpenAICompatUsage, OpenAICompatV3CallToolChoice, OpenAICompatV3CallTools, DeferredUsage, Tool } from "../types/index.js";
 export declare const stripTrailingSlash: (s: string) => string;
 /**
  * Build a bijective original ↔ wire tool-name map. Returns undefined when
@@ -67,8 +67,4 @@ export declare const createDeferredAnalytics: () => {
     resolveUsage: (u: DeferredUsage) => void;
     resolveFinish: (reason: string) => void;
 };
-export declare const createChunkQueue: () => {
-    pushChunk: (c: OpenAICompatStreamChunk) => void;
-    nextChunk: () => Promise<OpenAICompatStreamChunk>;
-};
 export declare const mergeUsage: (a: OpenAICompatUsage | undefined, b: OpenAICompatUsage | undefined) => OpenAICompatUsage | undefined;

package/dist/providers/openaiChatCompletionsClient.js

@@ -649,32 +649,6 @@ export const createDeferredAnalytics = () => {
     });
     return { usagePromise, finishPromise, resolveUsage, resolveFinish };
 };
-// Single-producer / single-consumer chunk queue. The streaming loop pushes
-// `{content}` deltas as they arrive from SSE and a final `{done:true}` when
-// it finishes; the consumer's AsyncIterable pulls from `nextChunk()`.
-export const createChunkQueue = () => {
-    const chunkQueue = [];
-    let pendingResolve;
-    const pushChunk = (c) => {
-        if (pendingResolve) {
-            const r = pendingResolve;
-            pendingResolve = undefined;
-            r(c);
-        }
-        else {
-            chunkQueue.push(c);
-        }
-    };
-    const nextChunk = () => new Promise((resolve) => {
-        if (chunkQueue.length > 0) {
-            resolve(chunkQueue.shift());
-        }
-        else {
-            pendingResolve = resolve;
-        }
-    });
-    return { pushChunk, nextChunk };
-};
 export const mergeUsage = (a, b) => {
     if (!a) {
         return b;

package/dist/types/index.d.ts

@@ -32,12 +32,14 @@ export * from "./hitl.js";
 export * from "./isolatedAgent.js";
 export * from "./knowledge.js";
 export * from "./livekit.js";
+export * from "./loopEngine.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";
 export * from "./memory.js";
 export * from "./middleware.js";
 export * from "./model.js";
 export * from "./multimodal.js";
+export * from "./nativeTools.js";
 export * from "./observability.js";
 export * from "./openaiCompatible.js";
 export * from "./ppt.js";
@@ -51,6 +53,7 @@ export * from "./server.js";
 export * from "./service.js";
 export * from "./skills.js";
 export * from "./stream.js";
+export * from "./streaming.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";

package/dist/types/index.js

@@ -33,12 +33,14 @@ export * from "./hitl.js";
 export * from "./isolatedAgent.js";
 export * from "./knowledge.js";
 export * from "./livekit.js";
+export * from "./loopEngine.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";
 export * from "./memory.js";
 export * from "./middleware.js";
 export * from "./model.js";
 export * from "./multimodal.js";
+export * from "./nativeTools.js";
 export * from "./observability.js";
 export * from "./openaiCompatible.js";
 export * from "./ppt.js";
@@ -52,6 +54,7 @@ export * from "./server.js";
 export * from "./service.js";
 export * from "./skills.js";
 export * from "./stream.js";
+export * from "./streaming.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";

package/dist/types/loopEngine.d.ts

@@ -0,0 +1,78 @@
+export type AgenticLoopToolCall = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+export type AgenticLoopUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+};
+export type AgenticLoopStepResult<TRaw = unknown> = {
+    text: string;
+    reasoning?: string;
+    toolCalls: AgenticLoopToolCall[];
+    usage: AgenticLoopUsage;
+    /** Provider's own raw stop/finish-reason string, e.g. "tool_use", "MAX_TOKENS" */
+    rawStopReason: string | undefined;
+    /** Adapter-private accumulated response data needed by buildToolResultMessages
+     *  (e.g. Anthropic's ordered content blocks, Gemini's rawResponseParts). */
+    raw: TRaw;
+};
+export type AgenticLoopToolCallResult = AgenticLoopToolCall & {
+    output: unknown;
+    error?: string;
+    permanentlyFailed?: boolean;
+};
+export type AgenticLoopStepRequest = {
+    raw: unknown;
+};
+export type AgenticLoopReclaimResult<TConversation> = {
+    conversation: TConversation;
+};
+export type AgenticLoopToolFailureBreaker = {
+    maxRetries: number;
+};
+export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
+    readonly providerLabel: string;
+    readonly maxSteps: number;
+    /** Pre-existing per-family flat timeout, used as createTurnClock's deadline default. */
+    readonly defaultTurnTimeoutMs?: number;
+    readonly stallTimeoutMs?: number;
+    /** Set only for adapter instances whose client has the TOOL_NOT_FOUND strike breaker today: both Gemini adapters (AI Studio, Vertex+Gemini) AND the Vertex+Claude call to createAnthropicLoopAdapter — NOT the native-Anthropic call to that same factory, and not Bedrock. See Verified Fact 4. */
+    readonly toolFailureBreaker?: AgenticLoopToolFailureBreaker;
+    buildStepRequest(conversation: TConversation, step: number): AgenticLoopStepRequest;
+    executeStep(request: AgenticLoopStepRequest, channel: {
+        push(chunk: {
+            content: string;
+        }): void;
+    }, signal: AbortSignal): Promise<AgenticLoopStepResult<TRaw>>;
+    buildToolResultMessages(conversation: TConversation, stepResult: AgenticLoopStepResult<TRaw>, toolResults: AgenticLoopToolCallResult[]): TConversation;
+    mapFinishReason(rawStopReason: string | undefined, hadToolCalls: boolean): string;
+    /** Optional: in-turn context-budget reclaim, called once per step before buildStepRequest. */
+    planReclaim?(conversation: TConversation, step: number): AgenticLoopReclaimResult<TConversation> | undefined;
+    /** Optional: Vertex+Gemini-only single-retry-on-malformed-call. */
+    isMalformedStep?(stepResult: AgenticLoopStepResult<TRaw>): boolean;
+    buildMalformedRetryNote?(conversation: TConversation): TConversation;
+};
+export type AgenticLoopOptions = {
+    tools?: Record<string, {
+        execute?: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;
+    }>;
+    abortSignal?: AbortSignal;
+};
+export type AgenticLoopResult<TConversation> = {
+    text: string;
+    toolCalls: AgenticLoopToolCall[];
+    toolExecutions: Array<{
+        name: string;
+        input: Record<string, unknown>;
+        output: unknown;
+    }>;
+    usage: AgenticLoopUsage;
+    finishReason: string;
+    rawStopReason: string | undefined;
+    conversation: TConversation;
+};

package/dist/types/loopEngine.js

@@ -0,0 +1 @@
+export {};

package/dist/types/nativeTools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Wire formats accepted by `toNativeToolDeclarations` (src/lib/core/nativeToolFormat.ts).
+ * `"input_schema"` is Anthropic's native Messages-API tool shape;
+ * `"functionDeclarations"` is the @google/genai SDK shape shared by the
+ * Gemini-family native providers (Google AI Studio, Vertex+Gemini).
+ */
+export type NativeToolFormat = "input_schema" | "functionDeclarations";
+/** A single tool declaration in Anthropic's native `input_schema` wire format. */
+export type NativeAnthropicToolDeclaration = {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+    cache_control?: {
+        type: "ephemeral";
+    };
+};

package/dist/types/nativeTools.js

@@ -0,0 +1 @@
+export {};

package/dist/types/openaiCompatible.d.ts

@@ -203,8 +203,6 @@ export type OpenAICompatSSEResult = {
 export type OpenAICompatStreamChunk = {
     content: string;
     reasoning?: string;
-} | {
-    done: true;
 };
 export type ToolExecutionSummaryInternal = {
     toolCallId: string;
@@ -232,6 +230,8 @@ export type StreamLoopArgs = {
     toolsUsed: string[];
     toolExecutionSummaries: ToolExecutionSummaryInternal[];
     pushChunk: (chunk: OpenAICompatStreamChunk) => void;
+    /** Signals the channel that no further chunks will arrive (success or error path alike). */
+    closeChannel: () => void;
     resolveUsage: (u: {
         promptTokens: number;
         completionTokens: number;

package/dist/types/providers.d.ts

@@ -1740,19 +1740,6 @@ export type CollectedChunkResult = {
      */
     reasoningTokens?: number;
 };
-/** Push-based text channel for incremental streaming. */
-export type TextChannel = {
-    /** Push a text chunk to the consumer. */
-    push: (text: string) => void;
-    /** Signal that no more chunks will arrive. */
-    close: () => void;
-    /** Signal that the producer encountered a fatal error. */
-    error: (err: unknown) => void;
-    /** Async iterable consumed by the StreamResult. */
-    iterable: AsyncIterable<{
-        content: string;
-    }>;
-};
 /** Language model object shape (LanguageModelV2/V3). */
 export type LanguageModelObject = {
     readonly modelId: string;

package/dist/types/streaming.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared push-based channel bridging a background producer (an agentic
+ * tool-calling loop) with an async-iterable consumer. Replaces the two
+ * independently-invented primitives this type unifies: the OpenAI-family
+ * `createChunkQueue` (pull-based, in-band `{done:true}` sentinel) and the
+ * Gemini-family `createTextChannel` (push-based, out-of-band close/error).
+ */
+export type StreamChannel<T = {
+    content: string;
+}> = {
+    push(value: T): void;
+    close(): void;
+    error(err: unknown): void;
+    readonly iterable: AsyncIterable<T>;
+};

package/dist/types/streaming.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/avatarProcessor.d.ts

@@ -43,7 +43,7 @@ export declare class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export declare class AvatarProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register an avatar handler for a specific provider.
      */
@@ -63,6 +63,10 @@ export declare class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): AvatarHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate an avatar video via the registered handler.

package/dist/utils/avatarProcessor.js

@@ -13,6 +13,7 @@ import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { NeuroLinkError } from "./errorHandling.js";
 import { logger } from "./logger.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Avatar-specific error codes.
  */
@@ -47,38 +48,26 @@ export class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export class AvatarProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("AvatarProcessor");
     /**
      * Register an avatar handler for a specific provider.
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const key = providerName.toLowerCase();
-        if (this.handlers.has(key)) {
-            logger.warn(`[AvatarProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[AvatarProcessor] Registered avatar handler: ${key}`);
     }
     /**
      * Check if a provider has a registered avatar handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered avatar handler by provider name.
@@ -87,7 +76,13 @@ export class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

package/dist/utils/musicProcessor.d.ts

@@ -42,7 +42,7 @@ export declare class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export declare class MusicProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register a music handler for a specific provider.
      */
@@ -62,6 +62,10 @@ export declare class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): MusicHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate a music track via the registered handler.

package/dist/utils/musicProcessor.js

@@ -13,6 +13,7 @@ import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { NeuroLinkError } from "./errorHandling.js";
 import { logger } from "./logger.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Music-specific error codes.
  */
@@ -46,38 +47,26 @@ export class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export class MusicProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("MusicProcessor");
     /**
      * Register a music handler for a specific provider.
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const key = providerName.toLowerCase();
-        if (this.handlers.has(key)) {
-            logger.warn(`[MusicProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[MusicProcessor] Registered music handler: ${key}`);
     }
     /**
      * Check if a provider has a registered music handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered music handler by provider name.
@@ -86,7 +75,13 @@ export class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

package/dist/utils/sttProcessor.d.ts

@@ -27,11 +27,10 @@ import type { STTOptions, STTResult, STTHandler } from "../types/index.js";
 export declare class STTProcessor {
     /**
      * Handler registry mapping provider names to STT handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Default maximum audio duration for STT transcription (in seconds)
      *
@@ -72,6 +71,15 @@ export declare class STTProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName: string): STTHandler | undefined;
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders(): string[];
+    /**
+     * Removes every registered STT handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers(): void;
     /**
      * Check if a provider is supported (has a registered STT handler)
      *

package/dist/utils/sttProcessor.js

@@ -10,6 +10,7 @@ import { logger } from "./logger.js";
 import { STT_ERROR_CODES } from "../types/index.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { STTError } from "../voice/errors.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
 /**
  * STT processor class for orchestrating speech-to-text operations
@@ -31,11 +32,10 @@ import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../
 export class STTProcessor {
     /**
      * Handler registry mapping provider names to STT handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    static handlers = new Map();
+    static registry = new HandlerRegistry("STTProcessor");
     /**
      * Default maximum audio duration for STT transcription (in seconds)
      *
@@ -66,17 +66,10 @@ export class STTProcessor {
      * ```
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const normalizedName = providerName.toLowerCase();
-        if (this.handlers.has(normalizedName)) {
-            logger.warn(`[STTProcessor] Overwriting existing handler for provider: ${normalizedName}`);
-        }
-        this.handlers.set(normalizedName, handler);
+        const normalizedName = providerName
+            ? providerName.toLowerCase()
+            : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[STTProcessor] Registered STT handler for provider: ${normalizedName}`);
     }
     /**
@@ -89,8 +82,20 @@ export class STTProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName) {
-        const normalizedName = providerName.toLowerCase();
-        return this.handlers.get(normalizedName);
+        return this.registry.get(providerName);
+    }
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders() {
+        return this.registry.list();
+    }
+    /**
+     * Removes every registered STT handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     /**
      * Check if a provider is supported (has a registered STT handler)
@@ -110,8 +115,7 @@ export class STTProcessor {
             logger.error("[STTProcessor] Provider name is required for supports check");
             return false;
         }
-        const normalizedName = providerName.toLowerCase();
-        const isSupported = this.handlers.has(normalizedName);
+        const isSupported = this.registry.supports(providerName);
         if (!isSupported) {
             logger.debug(`[STTProcessor] Provider ${providerName} is not supported`);
         }
@@ -192,7 +196,7 @@ export class STTProcessor {
                     retriable: false,
                     context: {
                         provider,
-                        availableProviders: Array.from(this.handlers.keys()),
+                        availableProviders: this.registry.list(),
                     },
                 });
             }

package/dist/utils/ttsProcessor.d.ts

@@ -54,11 +54,10 @@ export declare class TTSError extends NeuroLinkError {
 export declare class TTSProcessor {
     /**
      * Handler registry mapping provider names to TTS handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Default maximum text length for TTS synthesis (in bytes)
      *
@@ -100,6 +99,15 @@ export declare class TTSProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName: string): TTSHandler | undefined;
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders(): string[];
+    /**
+     * Removes every registered TTS handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers(): void;
     /**
      * Check if a provider is supported (has a registered TTS handler)
      *