@juspay/neurolink 11.27.0 → 11.28.0

package/dist/cli/factories/commandFactory.d.ts

@@ -300,6 +300,7 @@ export declare class CLICommandFactory {
         };
         videoProvider: {
             type: "string";
+            choices: string[];
             description: string;
         };
         videoOutput: {
@@ -328,6 +329,7 @@ export declare class CLICommandFactory {
         };
         avatarProvider: {
             type: "string";
+            choices: string[];
             description: string;
         };
         avatarImage: {
@@ -362,6 +364,7 @@ export declare class CLICommandFactory {
         };
         musicProvider: {
             type: "string";
+            choices: string[];
             description: string;
         };
         musicDuration: {
@@ -1190,6 +1193,7 @@ export declare const commonOptions: {
     };
     videoProvider: {
         type: "string";
+        choices: string[];
         description: string;
     };
     videoOutput: {
@@ -1218,6 +1222,7 @@ export declare const commonOptions: {
     };
     avatarProvider: {
         type: "string";
+        choices: string[];
         description: string;
     };
     avatarImage: {
@@ -1252,6 +1257,7 @@ export declare const commonOptions: {
     };
     musicProvider: {
         type: "string";
+        choices: string[];
         description: string;
     };
     musicDuration: {

package/dist/cli/factories/commandFactory.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import chalk from "chalk";
 import ora from "ora";
 import { ModelResolver } from "../../models/modelResolver.js";
+import { providerChoicesFor } from "../../factories/mediaHandlerCatalog.js";
 import { globalSession } from "../../session/globalSessionState.js";
 // Use TokenUsage from standard types - no local interface needed
 import { ContextFactory, } from "../../types/index.js";
@@ -333,7 +334,7 @@ export class CLICommandFactory {
         },
         ttsProvider: {
             type: "string",
-            choices: ["google-ai", "vertex", "openai-tts", "elevenlabs", "azure-tts"],
+            choices: providerChoicesFor("tts"),
             description: "TTS provider (overrides --provider for speech synthesis)",
         },
         ttsFormat: {
@@ -381,7 +382,7 @@ export class CLICommandFactory {
         },
         sttProvider: {
             type: "string",
-            choices: ["whisper", "deepgram", "google-stt", "azure-stt"],
+            choices: providerChoicesFor("stt"),
             description: "STT provider to use",
         },
         sttLanguage: {
@@ -401,6 +402,7 @@ export class CLICommandFactory {
         },
         videoProvider: {
             type: "string",
+            choices: providerChoicesFor("video"),
             description: "Video provider override (e.g., 'vertex' (default), 'kling', 'runway', 'replicate')",
         },
         videoOutput: {
@@ -430,6 +432,7 @@ export class CLICommandFactory {
         // Avatar Generation options (D-ID, HeyGen, MuseTalk via Replicate)
         avatarProvider: {
             type: "string",
+            choices: providerChoicesFor("avatar"),
             description: "Avatar provider (e.g., 'd-id' (default), 'heygen', 'replicate', 'musetalk')",
         },
         avatarImage: {
@@ -465,6 +468,7 @@ export class CLICommandFactory {
         // Music Generation options (Beatoven, ElevenLabs, Lyria, MusicGen via Replicate)
         musicProvider: {
             type: "string",
+            choices: providerChoicesFor("music"),
             description: "Music provider (e.g., 'beatoven' (default), 'elevenlabs-music', 'lyria', 'replicate', 'musicgen')",
         },
         musicDuration: {

package/dist/core/baseProvider.js

@@ -1,5 +1,6 @@
 import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { directAgentTools } from "../agent/directTools.js";
+import { defaultProviderFor } from "../factories/mediaHandlerCatalog.js";
 import { isImageGenerationModel } from "./constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
@@ -2139,9 +2140,10 @@ export class BaseProvider {
         }
         // Get prompt text
         const prompt = options.prompt || options.input?.text || "";
-        // Honor output.video.provider — when omitted, fall back to "vertex"
-        // for backward compatibility with the original implementation.
-        const requestedProvider = options.output?.video?.provider ?? "vertex";
+        // Honor output.video.provider — when omitted, fall back to the
+        // catalog-derived default (currently "vertex") for backward
+        // compatibility with the original implementation.
+        const requestedProvider = options.output?.video?.provider ?? defaultProviderFor("video");
         if (!VideoProcessor.supports(requestedProvider)) {
             throw new VideoError({
                 code: VIDEO_ERROR_CODES.PROVIDER_NOT_SUPPORTED,

package/dist/factories/mediaHandlerCatalog.d.ts

@@ -0,0 +1,18 @@
+import type { MediaHandlerDescriptor, MediaHandlerKind } from "../types/index.js";
+/**
+ * Static catalog of every shipped media-handler provider, across all six
+ * ecosystems (TTS, STT, Realtime, Video, Avatar, Music). Pure data — no
+ * factory functions, no class imports — mirroring the
+ * src/lib/factories/providerDescriptors.ts pattern for text/image
+ * providers.
+ *
+ * Entries mirror providerRegistry.ts's hand-constructed TTS/STT/Realtime/
+ * Video/Avatar/Music registration blocks (registerAllProviders()) exactly —
+ * this file states today's truth, not an aspirational shape. Keep it in
+ * sync if those blocks change.
+ */
+export declare const MEDIA_HANDLER_CATALOG: readonly MediaHandlerDescriptor[];
+/** Every selectable provider name for `kind`, primaries and aliases both. */
+export declare function providerChoicesFor(kind: MediaHandlerKind): string[];
+/** The first-listed primary provider name for `kind` — used as a fallback default. */
+export declare function defaultProviderFor(kind: MediaHandlerKind): string;

package/dist/factories/mediaHandlerCatalog.js

@@ -0,0 +1,65 @@
+/**
+ * Static catalog of every shipped media-handler provider, across all six
+ * ecosystems (TTS, STT, Realtime, Video, Avatar, Music). Pure data — no
+ * factory functions, no class imports — mirroring the
+ * src/lib/factories/providerDescriptors.ts pattern for text/image
+ * providers.
+ *
+ * Entries mirror providerRegistry.ts's hand-constructed TTS/STT/Realtime/
+ * Video/Avatar/Music registration blocks (registerAllProviders()) exactly —
+ * this file states today's truth, not an aspirational shape. Keep it in
+ * sync if those blocks change.
+ */
+export const MEDIA_HANDLER_CATALOG = [
+    // --- TTS ---
+    { kind: "tts", name: "google-ai", aliases: ["vertex"] },
+    { kind: "tts", name: "openai-tts" },
+    { kind: "tts", name: "elevenlabs", aliases: ["elevenlabs-tts"] },
+    { kind: "tts", name: "azure-tts" },
+    { kind: "tts", name: "fish-audio" },
+    { kind: "tts", name: "cartesia" },
+    // --- STT ---
+    { kind: "stt", name: "whisper", aliases: ["openai-stt"] },
+    { kind: "stt", name: "deepgram" },
+    { kind: "stt", name: "google-stt" },
+    { kind: "stt", name: "azure-stt" },
+    // --- Realtime ---
+    { kind: "realtime", name: "openai-realtime" },
+    { kind: "realtime", name: "gemini-live" },
+    // --- Video ---
+    { kind: "video", name: "vertex" },
+    { kind: "video", name: "kling" },
+    { kind: "video", name: "runway" },
+    { kind: "video", name: "replicate" },
+    // --- Avatar ---
+    { kind: "avatar", name: "d-id" },
+    { kind: "avatar", name: "replicate", aliases: ["musetalk"] },
+    { kind: "avatar", name: "heygen" },
+    // --- Music ---
+    { kind: "music", name: "beatoven" },
+    { kind: "music", name: "replicate", aliases: ["musicgen"] },
+    { kind: "music", name: "elevenlabs-music", aliases: ["elevenlabs-sound"] },
+    { kind: "music", name: "lyria" },
+];
+/** Every selectable provider name for `kind`, primaries and aliases both. */
+export function providerChoicesFor(kind) {
+    const choices = [];
+    for (const entry of MEDIA_HANDLER_CATALOG) {
+        if (entry.kind !== kind) {
+            continue;
+        }
+        choices.push(entry.name);
+        if (entry.aliases) {
+            choices.push(...entry.aliases);
+        }
+    }
+    return choices;
+}
+/** The first-listed primary provider name for `kind` — used as a fallback default. */
+export function defaultProviderFor(kind) {
+    const first = MEDIA_HANDLER_CATALOG.find((entry) => entry.kind === kind);
+    if (!first) {
+        throw new Error(`No media handler catalog entries registered for kind "${kind}"`);
+    }
+    return first.name;
+}

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();