@juspay/neurolink 11.27.0 → 11.29.0

package/dist/factories/providerRegistry.js

@@ -3,6 +3,7 @@ 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";
+import { providerChoicesFor } from "./mediaHandlerCatalog.js";
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -229,16 +230,23 @@ export class ProviderRegistry {
                 return new RecraftProvider(modelName, sdk, undefined, recraftCreds);
             }, process.env.RECRAFT_MODEL || RecraftModels.RECRAFT_V3, ["recraft"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.RECRAFT));
             logger.debug("All AI providers registered successfully");
+            // ===== MEDIA HANDLER REGISTRATION =====
+            // Single registration path (Task 11): each ecosystem barrel (voice,
+            // adapters/video, avatar, music) owns its own provider-name catalog
+            // wiring (MEDIA_HANDLER_CATALOG, Task 8) and exposes an idempotent
+            // registerDefault*Handlers() function (Task 10) that constructs and
+            // registers every shipped handler whose backing credentials are
+            // present in process.env. This block's only job is to invoke each of
+            // the six functions via dynamic import — no hand-rolled
+            // `new XHandler()` + `registerHandler()` calls live here anymore.
+            // Each ecosystem keeps its own try/catch so one broken import can't
+            // take down the other five (matches the previous block's isolation).
             // ===== TTS HANDLER REGISTRATION =====
             try {
-                // Create handler instance and register explicitly
-                const { GoogleTTSHandler } = await import("../adapters/tts/googleTTSHandler.js");
-                const { TTSProcessor } = await import("../utils/ttsProcessor.js");
-                const googleHandler = new GoogleTTSHandler();
-                TTSProcessor.registerHandler("google-ai", googleHandler);
-                TTSProcessor.registerHandler("vertex", googleHandler);
-                logger.debug("TTS handlers registered successfully", {
-                    providers: ["google-ai", "vertex"],
+                const { registerDefaultTTSHandlers } = await import("../voice/index.js");
+                registerDefaultTTSHandlers();
+                logger.debug("TTS handler registration attempted", {
+                    providers: providerChoicesFor("tts"),
                 });
             }
             catch (ttsError) {
@@ -247,91 +255,12 @@ export class ProviderRegistry {
                 });
                 // Don't throw - TTS is optional functionality
             }
-            // New TTS providers
-            try {
-                const { TTSProcessor } = await import("../utils/ttsProcessor.js");
-                const { OpenAITTS } = await import("../voice/providers/OpenAITTS.js");
-                TTSProcessor.registerHandler("openai-tts", new OpenAITTS());
-            }
-            catch (err) {
-                logger.debug(`[ProviderRegistry] openai-tts registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            try {
-                const { TTSProcessor } = await import("../utils/ttsProcessor.js");
-                const { ElevenLabsTTS } = await import("../voice/providers/ElevenLabsTTS.js");
-                const elevenLabsHandler = new ElevenLabsTTS();
-                TTSProcessor.registerHandler("elevenlabs", elevenLabsHandler);
-                TTSProcessor.registerHandler("elevenlabs-tts", elevenLabsHandler);
-            }
-            catch (err) {
-                logger.debug(`[ProviderRegistry] elevenlabs registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            try {
-                const { TTSProcessor } = await import("../utils/ttsProcessor.js");
-                const { AzureTTS } = await import("../voice/providers/AzureTTS.js");
-                TTSProcessor.registerHandler("azure-tts", new AzureTTS());
-            }
-            catch (err) {
-                logger.debug(`[ProviderRegistry] azure-tts registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            // Fish Audio and Cartesia also auto-register via the voice/index.ts
-            // barrel side-effect. The supports() guard here keeps registration
-            // idempotent across entry points — same handler, no overwrite warning.
-            try {
-                const { TTSProcessor } = await import("../utils/ttsProcessor.js");
-                if (!TTSProcessor.supports("fish-audio")) {
-                    const { FishAudioTTS } = await import("../voice/providers/FishAudioTTS.js");
-                    TTSProcessor.registerHandler("fish-audio", new FishAudioTTS());
-                }
-            }
-            catch (err) {
-                logger.debug(`[ProviderRegistry] fish-audio registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            try {
-                const { TTSProcessor } = await import("../utils/ttsProcessor.js");
-                if (!TTSProcessor.supports("cartesia")) {
-                    const { CartesiaTTS } = await import("../voice/providers/CartesiaTTS.js");
-                    TTSProcessor.registerHandler("cartesia", new CartesiaTTS());
-                }
-            }
-            catch (err) {
-                logger.debug(`[ProviderRegistry] cartesia registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-            }
             // ===== STT HANDLER REGISTRATION =====
             try {
-                const { STTProcessor } = await import("../utils/sttProcessor.js");
-                try {
-                    const { OpenAISTT } = await import("../voice/providers/OpenAISTT.js");
-                    const openAISTT = new OpenAISTT();
-                    STTProcessor.registerHandler("whisper", openAISTT);
-                    STTProcessor.registerHandler("openai-stt", openAISTT);
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] whisper/openai-stt registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { DeepgramSTT } = await import("../voice/providers/DeepgramSTT.js");
-                    STTProcessor.registerHandler("deepgram", new DeepgramSTT());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] deepgram registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { GoogleSTT } = await import("../voice/providers/GoogleSTT.js");
-                    STTProcessor.registerHandler("google-stt", new GoogleSTT());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] google-stt registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { AzureSTT } = await import("../voice/providers/AzureSTT.js");
-                    STTProcessor.registerHandler("azure-stt", new AzureSTT());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] azure-stt registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                logger.debug("STT handlers registered successfully", {
-                    providers: ["whisper", "deepgram", "google-stt", "azure-stt"],
+                const { registerDefaultSTTHandlers } = await import("../voice/index.js");
+                registerDefaultSTTHandlers();
+                logger.debug("STT handler registration attempted", {
+                    providers: providerChoicesFor("stt"),
                 });
             }
             catch (sttError) {
@@ -341,33 +270,21 @@ export class ProviderRegistry {
             }
             // ===== REALTIME HANDLER REGISTRATION =====
             try {
-                const { RealtimeProcessor } = await import("../voice/RealtimeVoiceAPI.js");
-                // M9 + NEW4: track per-handler registration outcomes so the final
-                // log accurately reflects which voice providers succeeded vs which
-                // were skipped — instead of unconditionally claiming "registered
-                // successfully" or hiding failures at debug level.
+                const { registerDefaultRealtimeHandlers, RealtimeProcessor } = await import("../voice/index.js");
+                registerDefaultRealtimeHandlers();
+                // M9 + NEW4: registerDefaultRealtimeHandlers() swallows per-handler
+                // construction failures internally (it's a shared, idempotent
+                // barrel function used by every entry point — see voice/index.ts),
+                // so the exact per-handler exception text the old inline block
+                // captured is no longer available here. Recover per-name pass/fail
+                // via supports() instead so getRegistrationReport() stays truthful
+                // for callers that poll it.
+                const realtimeNames = providerChoicesFor("realtime");
                 const realtimeOutcomes = {};
-                try {
-                    const { OpenAIRealtime } = await import("../voice/providers/OpenAIRealtime.js");
-                    RealtimeProcessor.registerHandler("openai-realtime", new OpenAIRealtime());
-                    realtimeOutcomes["openai-realtime"] = "ok";
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    realtimeOutcomes["openai-realtime"] = msg;
-                    // M9: promote per-handler failures to error level so users can
-                    // see which shipped voice provider failed to register at startup.
-                    logger.error(`[ProviderRegistry] openai-realtime registration failed: ${msg}`);
-                }
-                try {
-                    const { GeminiLive } = await import("../voice/providers/GeminiLive.js");
-                    RealtimeProcessor.registerHandler("gemini-live", new GeminiLive());
-                    realtimeOutcomes["gemini-live"] = "ok";
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    realtimeOutcomes["gemini-live"] = msg;
-                    logger.error(`[ProviderRegistry] gemini-live registration failed: ${msg}`);
+                for (const name of realtimeNames) {
+                    realtimeOutcomes[name] = RealtimeProcessor.supports(name)
+                        ? "ok"
+                        : "registration failed or handler unavailable";
                 }
                 // NEW4: report the actual per-handler outcomes instead of an
                 // unconditional success log. Stored on the registry so callers can
@@ -375,7 +292,7 @@ export class ProviderRegistry {
                 ProviderRegistry.realtimeRegistration = realtimeOutcomes;
                 const skipped = Object.entries(realtimeOutcomes).filter(([, v]) => v !== "ok");
                 if (skipped.length === 0) {
-                    logger.info("[ProviderRegistry] Realtime handlers registered: openai-realtime, gemini-live");
+                    logger.info(`[ProviderRegistry] Realtime handlers registered: ${realtimeNames.join(", ")}`);
                 }
                 else {
                     logger.warn(`[ProviderRegistry] Realtime handlers partial: ${skipped.length} skipped`, { outcomes: realtimeOutcomes });
@@ -390,67 +307,22 @@ export class ProviderRegistry {
             }
             // ===== VIDEO HANDLER REGISTRATION =====
             try {
-                const { VideoProcessor } = await import("../utils/videoProcessor.js");
-                try {
-                    const { VertexVideoHandler } = await import("../adapters/video/vertexVideoHandler.js");
-                    VideoProcessor.registerHandler("vertex", new VertexVideoHandler());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] vertex video registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { KlingVideoHandler } = await import("../adapters/video/klingVideoHandler.js");
-                    VideoProcessor.registerHandler("kling", new KlingVideoHandler());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] kling video registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { RunwayVideoHandler } = await import("../adapters/video/runwayVideoHandler.js");
-                    VideoProcessor.registerHandler("runway", new RunwayVideoHandler());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] runway video registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { ReplicateVideoHandler } = await import("../adapters/video/replicateVideoHandler.js");
-                    VideoProcessor.registerHandler("replicate", new ReplicateVideoHandler());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] replicate video registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                logger.debug("Video handlers registered");
+                const { registerDefaultVideoHandlers } = await import("../adapters/video/index.js");
+                registerDefaultVideoHandlers();
+                logger.debug("Video handler registration attempted", {
+                    providers: providerChoicesFor("video"),
+                });
             }
             catch (err) {
                 logger.warn(`[ProviderRegistry] video registration block failed: ${err instanceof Error ? err.message : String(err)}`);
             }
             // ===== AVATAR HANDLER REGISTRATION =====
             try {
-                const { AvatarProcessor } = await import("../utils/avatarProcessor.js");
-                try {
-                    const { DIDAvatar } = await import("../avatar/providers/DIDAvatar.js");
-                    AvatarProcessor.registerHandler("d-id", new DIDAvatar());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] d-id avatar registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { ReplicateAvatar } = await import("../avatar/providers/ReplicateAvatar.js");
-                    const replicateAvatar = new ReplicateAvatar();
-                    AvatarProcessor.registerHandler("replicate", replicateAvatar);
-                    AvatarProcessor.registerHandler("musetalk", replicateAvatar);
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] replicate avatar registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { HeyGenAvatar } = await import("../avatar/providers/HeyGenAvatar.js");
-                    AvatarProcessor.registerHandler("heygen", new HeyGenAvatar());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] heygen avatar registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                logger.debug("Avatar handlers registered");
+                const { registerDefaultAvatarHandlers } = await import("../avatar/index.js");
+                registerDefaultAvatarHandlers();
+                logger.debug("Avatar handler registration attempted", {
+                    providers: providerChoicesFor("avatar"),
+                });
             }
             catch (avatarError) {
                 logger.warn("Failed to register Avatar handlers - Avatar functionality will be unavailable", {
@@ -461,40 +333,11 @@ export class ProviderRegistry {
             }
             // ===== MUSIC HANDLER REGISTRATION =====
             try {
-                const { MusicProcessor } = await import("../utils/musicProcessor.js");
-                try {
-                    const { BeatovenMusic } = await import("../music/providers/BeatovenMusic.js");
-                    MusicProcessor.registerHandler("beatoven", new BeatovenMusic());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] beatoven music registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { ReplicateMusic } = await import("../music/providers/ReplicateMusic.js");
-                    const replicateMusic = new ReplicateMusic();
-                    MusicProcessor.registerHandler("replicate", replicateMusic);
-                    MusicProcessor.registerHandler("musicgen", replicateMusic);
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] replicate music registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { ElevenLabsMusic } = await import("../music/providers/ElevenLabsMusic.js");
-                    const elevenLabsMusic = new ElevenLabsMusic();
-                    MusicProcessor.registerHandler("elevenlabs-music", elevenLabsMusic);
-                    MusicProcessor.registerHandler("elevenlabs-sound", elevenLabsMusic);
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] elevenlabs-music registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                try {
-                    const { LyriaMusic } = await import("../music/providers/LyriaMusic.js");
-                    MusicProcessor.registerHandler("lyria", new LyriaMusic());
-                }
-                catch (err) {
-                    logger.debug(`[ProviderRegistry] lyria music registration skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                logger.debug("Music handlers registered");
+                const { registerDefaultMusicHandlers } = await import("../music/index.js");
+                registerDefaultMusicHandlers();
+                logger.debug("Music handler registration attempted", {
+                    providers: providerChoicesFor("music"),
+                });
             }
             catch (musicError) {
                 logger.warn("Failed to register Music handlers - Music functionality will be unavailable", {

package/dist/index.d.ts

@@ -67,10 +67,7 @@ export { STTProcessor } from "./utils/sttProcessor.js";
 export { AzureTTS, AzureTTSHandler, CartesiaTTS, CartesiaTTSHandler, ElevenLabsTTS, ElevenLabsTTSHandler, FishAudioTTS, FishAudioTTSHandler, GoogleTTSHandler, OpenAITTS, OpenAITTSHandler, AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, BaseRealtimeHandler, GeminiLive, GeminiLiveHandler, OpenAIRealtime, OpenAIRealtimeHandler, RealtimeProcessor, RealtimeError, STTError, VoiceError, registerDefaultRealtimeHandlers, registerDefaultSTTHandlers, registerDefaultTTSHandlers, } from "./voice/index.js";
 export { BeatovenMusic, BeatovenMusicHandler, ElevenLabsMusic, ElevenLabsMusicHandler, LyriaMusic, LyriaMusicHandler, registerDefaultMusicHandlers, ReplicateMusic, ReplicateMusicHandler, } from "./music/index.js";
 export { DIDAvatar, DIDAvatarHandler, HeyGenAvatar, HeyGenAvatarHandler, registerDefaultAvatarHandlers, ReplicateAvatar, ReplicateAvatarHandler, } from "./avatar/index.js";
-export { KlingVideoHandler } from "./adapters/video/klingVideoHandler.js";
-export { ReplicateVideoHandler } from "./adapters/video/replicateVideoHandler.js";
-export { RunwayVideoHandler } from "./adapters/video/runwayVideoHandler.js";
-export { VertexVideoHandler, isVertexVideoConfigured, } from "./adapters/video/vertexVideoHandler.js";
+export { isVertexVideoConfigured, KlingVideoHandler, registerDefaultVideoHandlers, ReplicateVideoHandler, RunwayVideoHandler, VertexVideoHandler, } from "./adapters/video/index.js";
 export { ImageGenService } from "./image-gen/ImageGenService.js";
 export { HITLManager } from "./hitl/hitlManager.js";
 export { ProviderRegistry } from "./factories/providerRegistry.js";

package/dist/index.js

@@ -125,11 +125,8 @@ registerDefaultRealtimeHandlers, registerDefaultSTTHandlers, registerDefaultTTSH
 export { BeatovenMusic, BeatovenMusicHandler, ElevenLabsMusic, ElevenLabsMusicHandler, LyriaMusic, LyriaMusicHandler, registerDefaultMusicHandlers, ReplicateMusic, ReplicateMusicHandler, } from "./music/index.js";
 // Avatar handlers
 export { DIDAvatar, DIDAvatarHandler, HeyGenAvatar, HeyGenAvatarHandler, registerDefaultAvatarHandlers, ReplicateAvatar, ReplicateAvatarHandler, } from "./avatar/index.js";
-// Video handlers (live under adapters/video; no separate video/ barrel)
-export { KlingVideoHandler } from "./adapters/video/klingVideoHandler.js";
-export { ReplicateVideoHandler } from "./adapters/video/replicateVideoHandler.js";
-export { RunwayVideoHandler } from "./adapters/video/runwayVideoHandler.js";
-export { VertexVideoHandler, isVertexVideoConfigured, } from "./adapters/video/vertexVideoHandler.js";
+// Video handlers
+export { isVertexVideoConfigured, KlingVideoHandler, registerDefaultVideoHandlers, ReplicateVideoHandler, RunwayVideoHandler, VertexVideoHandler, } from "./adapters/video/index.js";
 // Image generation + HITL — surfaced from their dedicated barrels
 export { ImageGenService } from "./image-gen/ImageGenService.js";
 export { HITLManager } from "./hitl/hitlManager.js";

package/dist/music/index.d.ts

@@ -7,9 +7,12 @@
  * Use `MusicProcessor.generate(provider, options)` to dispatch to the
  * registered handler for `provider`.
  *
- * Importing this module also auto-registers every shipped music handler
- * whose backing API key is present in `process.env`. Registration is
- * idempotent and silently skipped if a provider is already registered or
+ * Importing this module does NOT register any handlers as a side effect.
+ * Call `registerDefaultMusicHandlers()` explicitly (or go through
+ * `ProviderRegistry.registerAllProviders()`, which every documented
+ * `NeuroLink` entry point already calls) to register every shipped music
+ * handler whose backing API key is present in `process.env`. Registration
+ * is idempotent and silently skipped if a provider is already registered or
  * its constructor throws (e.g. missing optional native dependency).
  *
  * @module music

package/dist/music/index.js

@@ -7,13 +7,17 @@
  * Use `MusicProcessor.generate(provider, options)` to dispatch to the
  * registered handler for `provider`.
  *
- * Importing this module also auto-registers every shipped music handler
- * whose backing API key is present in `process.env`. Registration is
- * idempotent and silently skipped if a provider is already registered or
+ * Importing this module does NOT register any handlers as a side effect.
+ * Call `registerDefaultMusicHandlers()` explicitly (or go through
+ * `ProviderRegistry.registerAllProviders()`, which every documented
+ * `NeuroLink` entry point already calls) to register every shipped music
+ * handler whose backing API key is present in `process.env`. Registration
+ * is idempotent and silently skipped if a provider is already registered or
  * its constructor throws (e.g. missing optional native dependency).
  *
  * @module music
  */
+import { MEDIA_HANDLER_CATALOG } from "../factories/mediaHandlerCatalog.js";
 import { logger } from "../utils/logger.js";
 import { MusicProcessor } from "../utils/musicProcessor.js";
 export { MUSIC_ERROR_CODES, MusicError, MusicProcessor, } from "../utils/musicProcessor.js";
@@ -31,20 +35,21 @@ import { BeatovenMusic } from "./providers/BeatovenMusic.js";
 import { ElevenLabsMusic } from "./providers/ElevenLabsMusic.js";
 import { LyriaMusic } from "./providers/LyriaMusic.js";
 import { ReplicateMusic } from "./providers/ReplicateMusic.js";
-const MUSIC_HANDLER_CANDIDATES = [
-    { name: "beatoven", factory: () => new BeatovenMusic() },
-    {
-        name: "elevenlabs-music",
-        aliases: ["elevenlabs-sound"],
-        factory: () => new ElevenLabsMusic(),
-    },
-    { name: "lyria", factory: () => new LyriaMusic() },
-    {
-        name: "replicate",
-        aliases: ["musicgen"],
-        factory: () => new ReplicateMusic(),
-    },
-];
+// Provider names + aliases are the Task-8 catalog's job — only the factory
+// (which needs the imported handler class) stays local to this module.
+const MUSIC_HANDLER_FACTORIES = {
+    beatoven: () => new BeatovenMusic(),
+    "elevenlabs-music": () => new ElevenLabsMusic(),
+    lyria: () => new LyriaMusic(),
+    replicate: () => new ReplicateMusic(),
+};
+const MUSIC_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kind === "music").map((entry) => {
+    const factory = MUSIC_HANDLER_FACTORIES[entry.name];
+    if (!factory) {
+        throw new Error(`[music] no handler factory for catalog entry "${entry.name}"`);
+    }
+    return { name: entry.name, aliases: entry.aliases, factory };
+});
 /**
  * Register every shipped music handler whose backing credentials are
  * present in the environment. Safe to call multiple times — existing
@@ -87,7 +92,3 @@ export function registerDefaultMusicHandlers() {
         }
     }
 }
-// Run once at module import so consumers who follow the documented
-// `nl.generate(...)` flow get every configured handler without manually
-// calling `registerHandler`.
-registerDefaultMusicHandlers();

package/dist/neurolink.js

@@ -34,6 +34,7 @@ import { buildToolRoutingCatalog, buildRoutingQueryFromHistory, resolveToolRouti
 import { ToolRoutingCache } from "./core/toolRoutingCache.js";
 import { DEFAULT_RECENT_TURNS, KnowledgeGroundingEngine, } from "./knowledge/index.js";
 import { AIProviderFactory } from "./core/factory.js";
+import { resolveRequestKind } from "./core/resolveRequestKind.js";
 import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderFactory } from "./factories/providerFactory.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
@@ -3576,13 +3577,16 @@ Current user's request: ${currentInput}`;
             }
             return this.generateWithWorkflow(options);
         }
-        if (options.output?.mode === "music") {
+        // Single source of truth for "what kind of request is this" — see
+        // resolveRequestKind's doc comment for the full precedence table.
+        const requestKind = resolveRequestKind(options, options.model);
+        if (requestKind === "music") {
             return this.generateWithMusic(options, generateSpan);
         }
-        if (options.output?.mode === "avatar") {
+        if (requestKind === "avatar") {
             return this.generateWithAvatar(options, generateSpan);
         }
-        if (options.output?.mode !== "ppt") {
+        if (requestKind !== "ppt") {
             return null;
         }
         if (options.stt?.enabled && options.stt?.audio) {
@@ -4382,6 +4386,13 @@ Current user's request: ${currentInput}`;
         if (!providerName) {
             throw new Error('output.music.provider is required (e.g. "beatoven", "elevenlabs-music", "lyria", "replicate").');
         }
+        // This early-dispatch path never creates an AI provider, so
+        // ProviderRegistry.registerAllProviders() has NOT necessarily run —
+        // with the module-scope auto-registration retired, the handlers must
+        // be registered here explicitly. registerDefaultMusicHandlers() is
+        // idempotent (skip-if-registered), so the repeat call is free.
+        const { registerDefaultMusicHandlers } = await import("./music/index.js");
+        registerDefaultMusicHandlers();
         const { MusicProcessor } = await import("./utils/musicProcessor.js");
         const musicResult = await MusicProcessor.generate(providerName, {
             ...musicOptions,
@@ -4414,6 +4425,11 @@ Current user's request: ${currentInput}`;
         if (!providerName) {
             throw new Error('output.avatar.provider is required (e.g. "d-id", "heygen", "replicate").');
         }
+        // Same early-dispatch registration as generateWithMusic above: no AI
+        // provider is created on this path, so the retired module-scope
+        // auto-run must be replaced by an explicit (idempotent) call here.
+        const { registerDefaultAvatarHandlers } = await import("./avatar/index.js");
+        registerDefaultAvatarHandlers();
         const { AvatarProcessor } = await import("./utils/avatarProcessor.js");
         const avatarResult = await AvatarProcessor.generate(providerName, avatarOptions);
         generateSpan.setAttribute("neurolink.avatar.provider", providerName);

package/dist/types/dispatch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Types backing resolveRequestKind() (src/lib/core/resolveRequestKind.ts) —
+ * the single function that decides which of NeuroLink's output modes a
+ * generate/stream request is asking for.
+ */
+export type RequestKind = "text" | "image" | "video" | "music" | "avatar" | "tts-direct" | "ppt";
+/**
+ * Narrow structural subset of TextGenerationOptions/GenerateOptions that
+ * resolveRequestKind() actually reads. Kept intentionally minimal (rather
+ * than importing the full options type) so this module has no dependency
+ * on the wider options type graph.
+ */
+export type RequestKindInput = {
+    output?: {
+        mode?: string;
+        format?: string;
+    };
+    tts?: {
+        enabled?: boolean;
+        useAiResponse?: boolean;
+    };
+};

package/dist/types/dispatch.js

@@ -0,0 +1,6 @@
+/**
+ * Types backing resolveRequestKind() (src/lib/core/resolveRequestKind.ts) —
+ * the single function that decides which of NeuroLink's output modes a
+ * generate/stream request is asking for.
+ */
+export {};

package/dist/types/generate.d.ts

@@ -802,23 +802,12 @@ export type ToolExecutionCaptureOptions = {
  */
 export type GenerateStopReason = "completed" | "step-cap" | "context-cap" | "time-limit" | "stalled" | "aborted" | "provider-error";
 /**
- * Generate function result type - Primary output format
- * Future-ready for multi-modal outputs while maintaining text focus
+ * Media generation/processing outputs shared by GenerateResult and
+ * TextGenerationResult. Extracted so both result types intersect (&) this
+ * single definition instead of each declaring its own drifting copy of the
+ * same audio/video/avatar/music/ppt/image/transcription fields.
  */
-export type GenerateResult = {
-    content: string;
-    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
-    knowledge?: KnowledgeGroundingMetadata;
-    /**
-     * Parsed structured object when a `schema` was requested. Populated from
-     * AI-SDK experimental_output, or from text-mode coercion (balanced-scan +
-     * jsonrepair). Prefer this over JSON.parse(content) — it never requires the
-     * caller to re-parse hand-escaped model text.
-     */
-    structuredData?: unknown;
-    outputs?: {
-        text: string;
-    };
+export type MediaGenerationOutputs = {
     /**
      * Text-to-Speech audio result
      *
@@ -911,9 +900,31 @@ export type GenerateResult = {
      * ```
      */
     ppt?: PPTGenerationResult;
+    /** Standard format for image generation */
     imageOutput?: {
         base64: string;
     } | null;
+    /** STT transcription result (present when stt.enabled is true and audio input was provided) */
+    transcription?: STTResult;
+};
+/**
+ * Generate function result type - Primary output format
+ * Future-ready for multi-modal outputs while maintaining text focus
+ */
+export type GenerateResult = {
+    content: string;
+    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
+    knowledge?: KnowledgeGroundingMetadata;
+    /**
+     * Parsed structured object when a `schema` was requested. Populated from
+     * AI-SDK experimental_output, or from text-mode coercion (balanced-scan +
+     * jsonrepair). Prefer this over JSON.parse(content) — it never requires the
+     * caller to re-parse hand-escaped model text.
+     */
+    structuredData?: unknown;
+    outputs?: {
+        text: string;
+    };
     provider?: string;
     model?: string;
     finishReason?: string;
@@ -1013,8 +1024,6 @@ export type GenerateResult = {
     reasoning?: string;
     /** Token count for reasoning content */
     reasoningTokens?: number;
-    /** STT transcription result (present when stt.enabled is true and audio input was provided) */
-    transcription?: STTResult;
     retries?: {
         count: number;
         errors: Array<{
@@ -1033,7 +1042,7 @@ export type GenerateResult = {
      * absolute `requestsRemaining` / `tokensRemaining`.
      */
     limits?: ClaudeLimitSnapshot;
-};
+} & MediaGenerationOutputs;
 /**
  * Unified options for both generation and streaming
  * Supports factory patterns and domain configuration
@@ -1467,23 +1476,6 @@ export type TextGenerationResult = {
     }>;
     analytics?: AnalyticsData;
     evaluation?: EvaluationData;
-    audio?: TTSResult;
-    /** Outcome of TTS synthesis, including the failure reason. */
-    ttsMetadata?: TTSMetadata;
-    /** STT transcription result (present when stt input was processed) */
-    transcription?: STTResult;
-    /** Video generation result */
-    video?: VideoGenerationResult;
-    /** Avatar (talking-head) generation result */
-    avatar?: AvatarResult;
-    /** Music generation result */
-    music?: MusicResult;
-    /** PowerPoint generation result */
-    ppt?: PPTGenerationResult;
-    /** Image generation output */
-    imageOutput?: {
-        base64: string;
-    } | null;
     /** Gemini 3 thought signature for reasoning continuity across turns */
     thoughtSignature?: string;
     /** Thinking/reasoning text from provider (Anthropic thinking blocks, Gemini thought parts, DeepSeek/NIM reasoning_content) */
@@ -1497,7 +1489,7 @@ export type TextGenerationResult = {
             message: string;
         }>;
     };
-};
+} & MediaGenerationOutputs;
 /**
  * Enhanced result type with optional analytics/evaluation
  */

package/dist/types/index.d.ts

@@ -79,9 +79,11 @@ export * from "./video.js";
 export * from "./avatar.js";
 export * from "./music.js";
 export * from "./replicate.js";
+export * from "./mediaCatalog.js";
 export * from "./safeFetch.js";
 export * from "./modelPool.js";
 export * from "./requestRouter.js";
 export * from "./classifierRouter.js";
 export * from "./agentNetwork.js";
 export * from "./localUsage.js";
+export * from "./dispatch.js";