@juspay/neurolink 11.2.3 → 11.3.0

package/dist/core/handlerRegistry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export declare class HandlerRegistry<THandler> {
+    private readonly scopeName;
+    private readonly handlers;
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName: string);
+    register(providerName: string, handler: THandler): void;
+    supports(providerName: string): boolean;
+    get(providerName: string): THandler | undefined;
+    list(): string[];
+    clear(): void;
+}

package/dist/core/handlerRegistry.js

@@ -0,0 +1,61 @@
+import { logger } from "../utils/logger.js";
+import { sanitizeForLog } from "../utils/logSanitize.js";
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export class HandlerRegistry {
+    scopeName;
+    handlers = new Map();
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName) {
+        this.scopeName = scopeName;
+    }
+    register(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)) {
+            // Every caller today passes a literal provider slug, but this class is
+            // generic over an arbitrary string — sanitize before logging it so a
+            // future caller building the key from untrusted input can't leak a
+            // bearer token/API key through this warning.
+            logger.warn(`[${this.scopeName}] Overwriting existing handler for provider: ${sanitizeForLog(key)}`);
+        }
+        this.handlers.set(key, handler);
+    }
+    supports(providerName) {
+        if (!providerName) {
+            return false;
+        }
+        return this.handlers.has(providerName.toLowerCase());
+    }
+    get(providerName) {
+        return this.handlers.get(providerName.toLowerCase());
+    }
+    list() {
+        return Array.from(this.handlers.keys());
+    }
+    clear() {
+        this.handlers.clear();
+        logger.debug(`[${this.scopeName}] Cleared all handlers`);
+    }
+}

package/dist/core/loopEngine.d.ts

@@ -0,0 +1,23 @@
+import type { AgenticLoopAdapter, AgenticLoopOptions, AgenticLoopResult } from "../types/index.js";
+/**
+ * Run one adapter-parameterized agentic tool-calling turn. Owns the
+ * maxSteps-bounded loop, generic tool dispatch (with an opt-in
+ * TOOL_NOT_FOUND/failure-strike breaker — see AgenticLoopAdapter.toolFailureBreaker),
+ * per-step usage accumulation, a single optional malformed-call retry,
+ * chunk emission through streamChannel, and a pre-first-chunk 429/5xx
+ * retry (via withProviderRetry) around every adapter.executeStep() call.
+ * The retry wrap is unconditional and adapter-agnostic — every migrated
+ * provider gets it for free, not just the ones that had a hand-rolled
+ * version before migration (see Verified Fact 4-adjacent note in Task 4
+ * Step 1 and the Risks & Rollback "Deliberate behavior changes" list for
+ * which families are gaining this for the first time). Everything
+ * wire-format-specific (building the request, parsing the SDK response,
+ * serializing tool results back into the conversation, mapping the raw
+ * stop reason) is delegated to `adapter`.
+ */
+export declare function runAgenticLoop<TConversation>(adapter: AgenticLoopAdapter<TConversation>, initialConversation: TConversation, options: AgenticLoopOptions): {
+    stream: AsyncIterable<{
+        content: string;
+    }>;
+    resultPromise: Promise<AgenticLoopResult<TConversation>>;
+};

package/dist/core/loopEngine.js

@@ -0,0 +1,245 @@
+import { createStreamChannel } from "./streamChannel.js";
+import { logger } from "../utils/logger.js";
+import { withProviderRetry } from "../utils/providerRetry.js";
+/**
+ * Marks a step error that occurred AFTER at least one chunk had already
+ * been streamed to the consumer for this step. Retrying at that point
+ * would duplicate or interleave already-emitted output, so this wrapper
+ * deliberately carries none of the original error's status/retry
+ * metadata (`.statusCode`/`.status`, no APICallError/NeuroLinkError
+ * branding) — that makes `withProviderRetry`'s internal
+ * `isRetryableProviderError()` check return false via its duck-typed
+ * fallback, which ends the retry loop on the very next classification
+ * instead of sleeping and re-invoking `adapter.executeStep`. The engine
+ * unwraps back to the original `cause` before it ever reaches the
+ * caller — see the try/catch around the `withProviderRetry` call below.
+ */
+class PostEmissionStepError extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+    }
+}
+function sumUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0) || undefined,
+        cacheWriteTokens: (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0) || undefined,
+        reasoningTokens: (a.reasoningTokens ?? 0) + (b.reasoningTokens ?? 0) || undefined,
+    };
+}
+/**
+ * Run one adapter-parameterized agentic tool-calling turn. Owns the
+ * maxSteps-bounded loop, generic tool dispatch (with an opt-in
+ * TOOL_NOT_FOUND/failure-strike breaker — see AgenticLoopAdapter.toolFailureBreaker),
+ * per-step usage accumulation, a single optional malformed-call retry,
+ * chunk emission through streamChannel, and a pre-first-chunk 429/5xx
+ * retry (via withProviderRetry) around every adapter.executeStep() call.
+ * The retry wrap is unconditional and adapter-agnostic — every migrated
+ * provider gets it for free, not just the ones that had a hand-rolled
+ * version before migration (see Verified Fact 4-adjacent note in Task 4
+ * Step 1 and the Risks & Rollback "Deliberate behavior changes" list for
+ * which families are gaining this for the first time). Everything
+ * wire-format-specific (building the request, parsing the SDK response,
+ * serializing tool results back into the conversation, mapping the raw
+ * stop reason) is delegated to `adapter`.
+ */
+export function runAgenticLoop(adapter, initialConversation, options) {
+    const channel = createStreamChannel();
+    const internalAbort = new AbortController();
+    const onCallerAbort = () => internalAbort.abort();
+    options.abortSignal?.addEventListener("abort", onCallerAbort);
+    if (options.abortSignal?.aborted) {
+        internalAbort.abort();
+    }
+    const failedTools = new Map();
+    let malformedRetryUsed = false;
+    const resultPromise = (async () => {
+        let conversation = initialConversation;
+        let usage = { inputTokens: 0, outputTokens: 0 };
+        let finalText = "";
+        let rawStopReason;
+        const allToolCalls = [];
+        const allToolExecutions = [];
+        let hadToolCallsAtCap = false;
+        try {
+            for (let step = 0; step < adapter.maxSteps; step++) {
+                if (internalAbort.signal.aborted) {
+                    break;
+                }
+                if (adapter.planReclaim) {
+                    const reclaimed = adapter.planReclaim(conversation, step);
+                    if (reclaimed) {
+                        conversation = reclaimed.conversation;
+                    }
+                }
+                const request = adapter.buildStepRequest(conversation, step);
+                // Pre-first-chunk 429/5xx retry: watch whether THIS attempt of
+                // THIS step pushes anything to the shared channel before it
+                // throws. `hasEmitted` resets at the top of every attempt
+                // withProviderRetry makes; the instant an attempt emits and then
+                // throws, the thrown error is rewrapped as a PostEmissionStepError
+                // (no status/branding info survives the rewrap), which
+                // isRetryableProviderError() duck-types as non-retryable — so
+                // withProviderRetry gives up immediately instead of sleeping and
+                // re-invoking executeStep, which would duplicate/interleave
+                // output already sent to the consumer. The original error (not
+                // the wrapper) is what the caller of runAgenticLoop ultimately
+                // sees, via the unwrap in the catch below.
+                let hasEmitted = false;
+                const watchedChannel = {
+                    push: (chunk) => {
+                        hasEmitted = true;
+                        channel.push(chunk);
+                    },
+                };
+                let stepResult;
+                try {
+                    stepResult = await withProviderRetry(async () => {
+                        hasEmitted = false;
+                        try {
+                            return await adapter.executeStep(request, watchedChannel, internalAbort.signal);
+                        }
+                        catch (err) {
+                            throw hasEmitted ? new PostEmissionStepError(err) : err;
+                        }
+                    }, undefined, // no OTel span threaded through the engine today; adapters instrument their own steps if they need span-level detail
+                    `${adapter.providerLabel}.step`);
+                }
+                catch (err) {
+                    throw err instanceof PostEmissionStepError ? err.cause : err;
+                }
+                usage = sumUsage(usage, stepResult.usage);
+                rawStopReason = stepResult.rawStopReason;
+                if (adapter.isMalformedStep?.(stepResult) &&
+                    !malformedRetryUsed &&
+                    !internalAbort.signal.aborted) {
+                    malformedRetryUsed = true;
+                    logger.warn(`[${adapter.providerLabel}] Malformed function call at step ${step + 1}/${adapter.maxSteps}; retrying once.`);
+                    conversation =
+                        adapter.buildMalformedRetryNote?.(conversation) ?? conversation;
+                    continue;
+                }
+                if (stepResult.toolCalls.length === 0) {
+                    finalText = stepResult.text || finalText;
+                    break;
+                }
+                if (step === adapter.maxSteps - 1) {
+                    hadToolCallsAtCap = true;
+                }
+                const toolResults = [];
+                for (const call of stepResult.toolCalls) {
+                    allToolCalls.push(call);
+                    const breaker = adapter.toolFailureBreaker;
+                    const failInfo = breaker ? failedTools.get(call.name) : undefined;
+                    if (breaker && failInfo && failInfo.count >= breaker.maxRetries) {
+                        const output = {
+                            error: `TOOL_PERMANENTLY_FAILED: "${call.name}" has failed ${failInfo.count} times. Last error: ${failInfo.lastError}.`,
+                            status: "permanently_failed",
+                            do_not_retry: true,
+                        };
+                        toolResults.push({
+                            ...call,
+                            output,
+                            error: output.error,
+                            permanentlyFailed: true,
+                        });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                        continue;
+                    }
+                    const tool = options.tools?.[call.name];
+                    if (!tool?.execute) {
+                        const output = breaker
+                            ? {
+                                error: `TOOL_NOT_FOUND: "${call.name}" does not exist.`,
+                                status: "permanently_failed",
+                                do_not_retry: true,
+                            }
+                            : { error: `Tool not found: ${call.name}` };
+                        toolResults.push({
+                            ...call,
+                            output,
+                            error: output.error,
+                            permanentlyFailed: !!breaker,
+                        });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                        continue;
+                    }
+                    try {
+                        const output = await tool.execute(call.args, {
+                            toolCallId: call.id,
+                            abortSignal: internalAbort.signal,
+                        });
+                        toolResults.push({ ...call, output });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        if (breaker) {
+                            const current = failedTools.get(call.name) ?? {
+                                count: 0,
+                                lastError: "",
+                            };
+                            current.count++;
+                            current.lastError = message;
+                            failedTools.set(call.name, current);
+                        }
+                        const output = { error: message, status: "failed" };
+                        toolResults.push({ ...call, output, error: message });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                    }
+                }
+                conversation = adapter.buildToolResultMessages(conversation, stepResult, toolResults);
+            }
+            const finishReason = adapter.mapFinishReason(rawStopReason, hadToolCallsAtCap);
+            return {
+                text: finalText,
+                toolCalls: allToolCalls,
+                toolExecutions: allToolExecutions,
+                usage,
+                finishReason,
+                rawStopReason,
+                conversation,
+            };
+        }
+        catch (err) {
+            // Must run before the finally block's channel.close(): a consumer
+            // parked in the channel's iterable is woken by whichever of
+            // error()/close() runs first, and close() alone would let a
+            // stream-only consumer observe a clean end of stream for a turn that
+            // actually failed. Calling error() here — synchronously, inside this
+            // catch — guarantees it lands before close(), with no dependence on
+            // microtask scheduling (unlike an outer promise-chained catch handler
+            // on this IIFE, which would run in a later microtask after `finally`
+            // already closed the channel).
+            channel.error(err);
+            throw err;
+        }
+        finally {
+            // close() after error() is harmless: it only flips `done`, and
+            // streamChannel.error() keeps its error state intact regardless of a
+            // later close() call.
+            channel.close();
+            options.abortSignal?.removeEventListener("abort", onCallerAbort);
+        }
+    })();
+    return { stream: channel.iterable, resultPromise };
+}

package/dist/core/nativeToolFormat.d.ts

@@ -0,0 +1,33 @@
+import type { NativeAnthropicToolDeclaration, NativeToolDeclarationsResult, Tool } from "../types/index.js";
+/**
+ * Convert a NeuroLink tool record into the wire-format a native
+ * (non-AI-SDK) provider SDK expects. Absorbs the direct-Anthropic
+ * provider's `toolsToAnthropic` — previously duplicated between the
+ * streaming loop's pre-loop snapshot and its mid-turn discovery-hydration
+ * call site (both in anthropic/client.ts). Gemini's `functionDeclarations`
+ * shape was already centralized in `buildNativeToolDeclarations`; this
+ * function is a thin facade over it so every native provider calls one
+ * entry point.
+ *
+ * Scope note: Vertex's Claude-on-Vertex `input_schema` builder
+ * (`buildAnthropicToolDeclaration` in googleVertex/client.ts) is
+ * deliberately NOT routed through this function. Despite the superficial
+ * similarity, it is not a byte-for-byte duplicate of `toolsToAnthropic`: it
+ * strips the converted schema down to `{type, properties, required}` only
+ * (dropping any other JSON-Schema keywords `convertZodToJsonSchema` may
+ * produce), it always runs `inlineJsonSchema` (Anthropic-direct never has),
+ * it prefers `parameters` over `inputSchema` (the opposite fallback order
+ * from Anthropic-direct), and it has no `cache_control` support of its own
+ * because Vertex applies cache breakpoints later via the separate
+ * `applyVertexAnthropicCacheBreakpoints` pass. Collapsing these into one
+ * shared implementation would risk a live tool-calling regression on one
+ * provider or the other; see the Task 2 report for the full comparison.
+ *
+ * These are genuine TS overload declarations, not redeclarations: the base
+ * `no-redeclare` ESLint rule doesn't understand the overload-signatures +
+ * implementation pattern (the TS-aware `@typescript-eslint/no-redeclare`
+ * variant would, but isn't enabled project-wide), so each signature below
+ * is individually exempted.
+ */
+export declare function toNativeToolDeclarations(tools: Record<string, Tool>, format: "input_schema"): NativeAnthropicToolDeclaration[] | undefined;
+export declare function toNativeToolDeclarations(tools: Record<string, Tool>, format: "functionDeclarations"): NativeToolDeclarationsResult;

package/dist/core/nativeToolFormat.js

@@ -0,0 +1,30 @@
+import { buildNativeToolDeclarations } from "../providers/googleNativeGemini3/utils.js";
+import { cacheControlOf } from "../providers/anthropic/cacheControl.js";
+import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
+// eslint-disable-next-line no-redeclare -- TS overload implementation signature, not a redeclaration
+export function toNativeToolDeclarations(tools, format) {
+    if (format === "functionDeclarations") {
+        return buildNativeToolDeclarations(tools);
+    }
+    const entries = Object.entries(tools ?? {});
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return entries.map(([name, tool]) => {
+        const t = tool;
+        const rawSchema = t.inputSchema ?? t.parameters;
+        const input_schema = (rawSchema
+            ? convertZodToJsonSchema(rawSchema)
+            : { type: "object", properties: {} });
+        // GenerationHandler marks the last tool definition with a cache
+        // breakpoint when prompt caching is active — keep honoring it.
+        const cc = cacheControlOf(tool);
+        const declaration = {
+            name,
+            ...(t.description ? { description: t.description } : {}),
+            input_schema,
+            ...(cc ? { cache_control: cc } : {}),
+        };
+        return declaration;
+    });
+}

package/dist/core/streamChannel.d.ts

@@ -0,0 +1,10 @@
+import type { StreamChannel } from "../types/index.js";
+/**
+ * Create a push-based channel bridging a background producer (an agentic
+ * tool-calling loop) with an async-iterable consumer, enabling truly
+ * incremental streaming: values are yielded to the caller as they arrive
+ * rather than being buffered until the producer finishes.
+ */
+export declare function createStreamChannel<T = {
+    content: string;
+}>(): StreamChannel<T>;

package/dist/core/streamChannel.js

@@ -0,0 +1,76 @@
+/**
+ * Create a push-based channel bridging a background producer (an agentic
+ * tool-calling loop) with an async-iterable consumer, enabling truly
+ * incremental streaming: values are yielded to the caller as they arrive
+ * rather than being buffered until the producer finishes.
+ */
+export function createStreamChannel() {
+    const queue = [];
+    let done = false;
+    let fatalError = undefined;
+    // Tracked separately from `fatalError`: a producer can legitimately
+    // reject with `undefined` (e.g. `throw undefined`), and `fatalError !==
+    // undefined` would then be indistinguishable from "no error occurred",
+    // closing the stream cleanly instead of surfacing the failure.
+    let hasError = false;
+    let notify = null;
+    function wake() {
+        if (notify) {
+            const fn = notify;
+            notify = null;
+            fn();
+        }
+    }
+    function push(value) {
+        if (done) {
+            return;
+        }
+        queue.push(value);
+        wake();
+    }
+    function close() {
+        done = true;
+        wake();
+    }
+    function error(err) {
+        done = true;
+        fatalError = err;
+        hasError = true;
+        wake();
+    }
+    let readIndex = 0;
+    async function* iterable() {
+        try {
+            while (true) {
+                if (readIndex < queue.length) {
+                    yield queue[readIndex++];
+                    // Periodically compact consumed entries to avoid unbounded retention.
+                    if (readIndex > 1024 && readIndex * 2 >= queue.length) {
+                        queue.splice(0, readIndex);
+                        readIndex = 0;
+                    }
+                }
+                else if (done) {
+                    if (hasError) {
+                        throw fatalError instanceof Error
+                            ? fatalError
+                            : new Error(String(fatalError));
+                    }
+                    return;
+                }
+                else {
+                    await new Promise((resolve) => {
+                        notify = resolve;
+                    });
+                }
+            }
+        }
+        finally {
+            // Consumer stopped reading (disconnect/cancel): stop buffering.
+            done = true;
+            queue.length = 0;
+            notify?.();
+        }
+    }
+    return { push, close, error, iterable: iterable() };
+}

package/dist/factories/providerRegistry.d.ts

@@ -1,14 +1,4 @@
 import type { ProviderRegistryOptions } from "../types/index.js";
-import { AIProviderName } from "../constants/enums.js";
-/**
- * Static module -> provider-ID manifest for every provider registered below.
- * Module names (file/dir under src/lib/providers/) intentionally differ from
- * their canonical IDs (e.g. amazonBedrock -> "bedrock", googleVertex ->
- * "vertex"); static scanners that cannot resolve the dynamic import() calls
- * use this mapping to confirm a module is registered. Enforced at runtime so
- * the registry cannot silently drift from this manifest.
- */
-export declare const PROVIDER_MODULE_TO_ID: Readonly<Record<string, AIProviderName>>;
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -43,12 +33,10 @@ export declare class ProviderRegistry {
      * (avoids circular dependencies; see CLAUDE.md).
      *
      * Not registered (by design): index.ts, providerTypeUtils.ts,
-     * openaiChatCompletionsBase.ts, openaiChatCompletionsClient.ts,
-     * anthropicImageBlocks.ts (shared base/helper modules), anthropicBaseProvider.ts
-     * (legacy; anthropic.ts is live), googleNativeGemini3.ts (shared helpers).
-     * Filename != provider ID (e.g. amazonBedrock -> "bedrock"); the
-     * statically-scannable PROVIDER_MODULE_TO_ID manifest maps every registered
-     * module to its provider ID and is enforced below (Pattern Analysis #1178/#1317).
+     * anthropicBaseProvider.ts (legacy; anthropic.ts is live),
+     * googleNativeGemini3.ts (shared helpers). Filename != provider ID
+     * (e.g. amazonBedrock -> "bedrock"); static scanners that miss dynamic
+     * imports may false-positive (Pattern Analysis #1178).
      */
     private static _doRegister;
     /**

package/dist/factories/providerRegistry.js

@@ -3,46 +3,6 @@ import { logger } from "../utils/logger.js";
 import { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, HuggingFaceModels, DeepSeekModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "./providerDescriptors.js";
 import { OPENAI_COMPAT_CATALOG } from "../providers/openaiCompatCatalog.js";
-/**
- * Static module -> provider-ID manifest for every provider registered below.
- * Module names (file/dir under src/lib/providers/) intentionally differ from
- * their canonical IDs (e.g. amazonBedrock -> "bedrock", googleVertex ->
- * "vertex"); static scanners that cannot resolve the dynamic import() calls
- * use this mapping to confirm a module is registered. Enforced at runtime so
- * the registry cannot silently drift from this manifest.
- */
-export const PROVIDER_MODULE_TO_ID = {
-    amazonBedrock: AIProviderName.BEDROCK,
-    amazonSagemaker: AIProviderName.SAGEMAKER,
-    anthropic: AIProviderName.ANTHROPIC,
-    azureOpenai: AIProviderName.AZURE,
-    cloudflare: AIProviderName.CLOUDFLARE,
-    cohere: AIProviderName.COHERE,
-    deepseek: AIProviderName.DEEPSEEK,
-    fireworks: AIProviderName.FIREWORKS,
-    googleAiStudio: AIProviderName.GOOGLE_AI,
-    googleVertex: AIProviderName.VERTEX,
-    groq: AIProviderName.GROQ,
-    huggingFace: AIProviderName.HUGGINGFACE,
-    ideogram: AIProviderName.IDEOGRAM,
-    jina: AIProviderName.JINA,
-    litellm: AIProviderName.LITELLM,
-    llamaCpp: AIProviderName.LLAMACPP,
-    lmStudio: AIProviderName.LM_STUDIO,
-    mistral: AIProviderName.MISTRAL,
-    nvidiaNim: AIProviderName.NVIDIA_NIM,
-    ollama: AIProviderName.OLLAMA,
-    openAI: AIProviderName.OPENAI,
-    openaiCompatible: AIProviderName.OPENAI_COMPATIBLE,
-    openRouter: AIProviderName.OPENROUTER,
-    perplexity: AIProviderName.PERPLEXITY,
-    recraft: AIProviderName.RECRAFT,
-    replicate: AIProviderName.REPLICATE,
-    stability: AIProviderName.STABILITY,
-    togetherAi: AIProviderName.TOGETHER_AI,
-    voyage: AIProviderName.VOYAGE,
-    xai: AIProviderName.XAI,
-};
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -94,12 +54,10 @@ export class ProviderRegistry {
      * (avoids circular dependencies; see CLAUDE.md).
      *
      * Not registered (by design): index.ts, providerTypeUtils.ts,
-     * openaiChatCompletionsBase.ts, openaiChatCompletionsClient.ts,
-     * anthropicImageBlocks.ts (shared base/helper modules), anthropicBaseProvider.ts
-     * (legacy; anthropic.ts is live), googleNativeGemini3.ts (shared helpers).
-     * Filename != provider ID (e.g. amazonBedrock -> "bedrock"); the
-     * statically-scannable PROVIDER_MODULE_TO_ID manifest maps every registered
-     * module to its provider ID and is enforced below (Pattern Analysis #1178/#1317).
+     * anthropicBaseProvider.ts (legacy; anthropic.ts is live),
+     * googleNativeGemini3.ts (shared helpers). Filename != provider ID
+     * (e.g. amazonBedrock -> "bedrock"); static scanners that miss dynamic
+     * imports may false-positive (Pattern Analysis #1178).
      */
     // eslint-disable-next-line max-lines-per-function
     static async _doRegister() {
@@ -270,16 +228,6 @@ export class ProviderRegistry {
                 const { RecraftProvider } = await import("../providers/recraft.js");
                 return new RecraftProvider(modelName, sdk, undefined, recraftCreds);
             }, process.env.RECRAFT_MODEL || RecraftModels.RECRAFT_V3, ["recraft"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.RECRAFT));
-            const unregistered = Object.entries(PROVIDER_MODULE_TO_ID).filter(([module, id]) => {
-                if (!ProviderFactory.hasProvider(id)) {
-                    logger.error(`[ProviderRegistry] drift: module "${module}" not registered as "${id}"`);
-                    return true;
-                }
-                return false;
-            });
-            if (unregistered.length > 0) {
-                throw new Error(`ProviderRegistry drift: ${unregistered.length} module(s) in PROVIDER_MODULE_TO_ID are not registered`);
-            }
             logger.debug("All AI providers registered successfully");
             // ===== TTS HANDLER REGISTRATION =====
             try {

package/dist/lib/core/handlerRegistry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export declare class HandlerRegistry<THandler> {
+    private readonly scopeName;
+    private readonly handlers;
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName: string);
+    register(providerName: string, handler: THandler): void;
+    supports(providerName: string): boolean;
+    get(providerName: string): THandler | undefined;
+    list(): string[];
+    clear(): void;
+}