@juspay/neurolink 9.71.0 → 9.73.0

package/dist/types/config.d.ts

@@ -9,6 +9,7 @@ import type { ConversationMemoryConfig } from "./conversation.js";
 import type { ObservabilityConfig } from "./observability.js";
 import type { AuthProvider, AuthProviderType, AuthProviderConfig, Auth0Config, ClerkConfig, FirebaseConfig, SupabaseConfig, WorkOSConfig, BetterAuthConfig, JWTConfig, OAuth2Config, CognitoConfig, KeycloakConfig, AuthenticatedContext } from "./auth.js";
 import type { NeurolinkCredentials } from "./providers.js";
+import type { ToolRoutingConfig } from "./toolRouting.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -66,6 +67,13 @@ export type NeurolinkConstructorConfig = {
      * provider is preserved across the chain; only the model name changes.
      */
     modelChain?: string[];
+    /**
+     * Pre-call tool routing: a cheap router LLM picks the tool servers
+     * relevant to each stream() turn and the unpicked servers' tools are
+     * dropped from the request via `excludeTools`. Fails open (all tools) on
+     * any router failure. See {@link ToolRoutingConfig}.
+     */
+    toolRouting?: ToolRoutingConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/index.d.ts

@@ -50,6 +50,7 @@ export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";

package/dist/types/index.js

@@ -51,6 +51,7 @@ export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";

package/dist/types/livekit.d.ts

@@ -155,6 +155,7 @@ export type LiveKitVoiceAgentConfig = {
     conversationIdPrefix?: string;
     /** Optional user id recorded alongside memory. */
     userId?: string;
+    greeting?: string;
     /** Silero VAD tuning (stricter = ignores background noise). */
     vad?: LiveKitVadConfig;
     /** Turn-detection tuning (VAD vs STT endpointing, delays). */
@@ -367,3 +368,136 @@ export type LiveKitEventBridgeHandle = {
     /** Remove all listeners and stop publishing. Idempotent. */
     dispose: () => void;
 };
+/**
+ * Credentials for LiveKit server-side REST calls (room create, agent dispatch).
+ * `url` accepts `ws(s)://` or `http(s)://`; helpers convert it to https.
+ */
+export type LiveKitServerCredentials = {
+    url: string;
+    apiKey: string;
+    apiSecret: string;
+};
+/**
+ * Realtime voice configuration resolved from the environment.
+ *
+ * In speech-to-speech mode one realtime model (Gemini Live on Vertex) does STT,
+ * reasoning, TTS, and turn detection — so there is no separate STT/TTS/VAD/EOU
+ * config. `resolveRealtimeVoiceConfig` fills every field from `process.env`
+ * (with defaults); `RealtimeVoiceAgentConfig` lets a caller override any of them.
+ */
+export type RealtimeVoiceConfig = {
+    /** Vertex project id (from VERTEX_PROJECT / GOOGLE_AUTH_* / GOOGLE_CLOUD_PROJECT_ID). */
+    project: string | undefined;
+    /** Vertex location; native-audio Live is served on `global`, not regionally. */
+    location: string;
+    /** Realtime model id (e.g. "gemini-live-2.5-flash"). */
+    model: string;
+    /** Optional Gemini voice name; omit for the plugin default. */
+    voice: string | undefined;
+    /** Response modality: "AUDIO" (native S2S) or "TEXT" (half-cascade). */
+    responseModality: string;
+    /** System prompt / instructions for the agent. */
+    systemPrompt: string;
+    /** Opening line the agent speaks on connect ("" disables). */
+    greeting: string;
+    /** Whether to bridge Lighthouse MCP tools as Gemini function tools. */
+    toolsEnabled: boolean;
+    /** Full URL of the MCP server the tools are bridged from. */
+    mcpUrl: string;
+    /** Grace period after the caller leaves before the job shuts down (ms). */
+    emptyRoomGraceMs: number;
+    /** Deadline for a participant to join before the job shuts down (ms). */
+    joinDeadlineMs: number;
+    /** How long a HITL confirmation waits before being treated as a decline (ms). */
+    hitlTimeoutMs: number;
+    /** Interval for the RSS/heap metrics log (ms). */
+    metricsIntervalMs: number;
+};
+/** A single log record handed to a `RealtimeVoiceAgentConfig.onLog` sink. */
+export type RealtimeVoiceLogEntry = {
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    timestamp: number;
+    data?: unknown;
+};
+export type RealtimeVoiceLogContext = {
+    room: string;
+};
+/**
+ * Options for `defineRealtimeVoiceAgent`. Every field is optional: omitted
+ * values fall back to `resolveRealtimeVoiceConfig()` (i.e. the environment), so
+ * a caller can use `defineRealtimeVoiceAgent()` with no arguments and configure
+ * everything via env.
+ */
+export type RealtimeVoiceAgentConfig = {
+    project?: string;
+    location?: string;
+    model?: string;
+    voice?: string;
+    responseModality?: string;
+    systemPrompt?: string;
+    greeting?: string;
+    /** MCP tool bridging overrides. */
+    tools?: {
+        enabled?: boolean;
+        mcpUrl?: string;
+    };
+    /** Data-channel topic for outbound events (default "ai-events"). */
+    eventsTopic?: string;
+    /** Data-channel topic for inbound control messages (default "ai-control"). */
+    controlTopic?: string;
+    /**
+     * Optional sink for the agent's own logs. When set, the realtime agent wires
+     * NeuroLink's logger to this callback for the duration of the call, so a host
+     * can forward worker logs into its logging pipeline. Each record is tagged
+     * with per-call context (the room name). Subject to the logger's level gate:
+     * without debug mode only `error` records are emitted (set `NEUROLINK_DEBUG`).
+     */
+    onLog?: (entry: RealtimeVoiceLogEntry, ctx: RealtimeVoiceLogContext) => void;
+};
+/** Auth token + base64 MCP execution context decoded from a room's metadata. */
+export type LiveKitRoomCallContext = {
+    /** Lighthouse access JWT used as `x-auth-token` to the MCP server. */
+    authToken: string;
+    /** base64(JSON) MCP execution context used as `x-context` (or "" if absent). */
+    xContext: string;
+};
+/** Publishes a single voice event envelope onto the room data channel. */
+export type RealtimeEventPublisher = (type: LiveKitVoiceEventType, data: Record<string, unknown>) => void;
+/** Requests a HITL confirmation and resolves to the user's decision. */
+export type RealtimeConfirmationRequester = (toolName: string, args: Record<string, unknown>) => Promise<boolean>;
+/** Handle returned by `attachRealtimeEventBridge`. */
+export type RealtimeEventBridgeHandle = {
+    /** Publish an outbound event to the browser (data packet or text stream). */
+    publishEvent: RealtimeEventPublisher;
+    /** Open a HITL prompt and await the browser's decision (timeout = decline). */
+    requestConfirmation: RealtimeConfirmationRequester;
+    /** Remove the control-channel listener and clear pending confirmations. */
+    dispose: () => void;
+};
+/** Inputs to `attachRealtimeEventBridge`. */
+export type RealtimeEventBridgeParams = {
+    /** The LiveKit room for this call (from the job context). */
+    room: LiveKitBridgeRoom;
+    /** HITL confirmation timeout in ms before a request is auto-declined. */
+    hitlTimeoutMs?: number;
+    /** Outbound events topic (default "ai-events"). */
+    eventsTopic?: string;
+    /** Inbound control topic (default "ai-control"). */
+    controlTopic?: string;
+    /** Payloads larger than this are sent via the chunked text stream (default 12000). */
+    maxInlineBytes?: number;
+};
+/** Inputs to `buildRealtimeMcpTools`. */
+export type BuildRealtimeMcpToolsParams = {
+    /** Full URL of the MCP server (e.g. ".../ai/mcp/v2"). */
+    mcpUrl: string;
+    /** Lighthouse access JWT forwarded as `x-auth-token`. */
+    authToken: string;
+    /** base64(JSON) execution context forwarded as `x-context`. */
+    xContext: string;
+    /** Publishes tool start/result events to the browser. */
+    publishEvent: RealtimeEventPublisher;
+    /** Opens a HITL confirmation for destructive tools and awaits the decision. */
+    requestConfirmation: RealtimeConfirmationRequester;
+};

package/dist/types/toolRouting.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Pre-call tool routing — configuration and catalog types.
+ *
+ * Host applications can register large numbers of custom tools (typically MCP
+ * server tools) whose names are prefixed with their server id
+ * (`${serverId}_${toolName}`). When tool routing is enabled, a cheap router
+ * LLM call runs once per `stream()` turn, picks the servers relevant to the
+ * user query, and the tools of every unpicked server are appended to the
+ * request's `excludeTools` denylist before the main model call.
+ *
+ * Denylist semantics are deliberate: the router only knows the declared
+ * server catalog — a strict subset of the real tool set. Excluding unpicked
+ * servers leaves NeuroLink's built-in direct tools, always-include servers,
+ * and any tools outside the catalog untouched. The whole mechanism fails
+ * open: any router failure resolves to an empty exclusion list (all tools),
+ * identical to routing being disabled.
+ */
+import type { GenerateOptions, GenerateResult } from "./generate.js";
+/** One routable server as declared by the host application. */
+export type ToolRoutingServerDescriptor = {
+    /**
+     * Server id. Must be the prefix used when the host registered the server's
+     * tools (`${id}_${toolName}`) — tool names are grouped by this prefix.
+     */
+    id: string;
+    /** Routing-grade server description shown to the router LLM. */
+    description: string;
+};
+/**
+ * LLM settings for the router call. Fields omitted here fall back to the
+ * stream call's own provider/model/region, so the router uses the same model
+ * as the main chat call unless explicitly overridden.
+ */
+export type ToolRoutingModelConfig = {
+    provider?: string;
+    model?: string;
+    region?: string;
+    /** Router sampling temperature. Default: 0. */
+    temperature?: number;
+};
+/** Constructor-level configuration for pre-call tool routing. */
+export type ToolRoutingConfig = {
+    /** Master switch. Routing runs only when true AND the server catalog is non-empty. */
+    enabled: boolean;
+    /**
+     * Routable server catalog. Hosts that only know their servers after
+     * constructing NeuroLink can supply it later via
+     * `neurolink.setToolRoutingServers()` instead.
+     */
+    servers?: ToolRoutingServerDescriptor[];
+    /**
+     * Server ids whose tools are always kept and never offered to the router
+     * (e.g. utility / reasoning / chart servers every turn may need).
+     */
+    alwaysIncludeServerIds?: string[];
+    /** Hard ceiling for the router LLM call before failing open. Default: 15000. */
+    timeoutMs?: number;
+    /** Router LLM override. Defaults to the stream call's provider/model/region at temperature 0. */
+    routerModel?: ToolRoutingModelConfig;
+    /**
+     * Override for the instruction text placed before the user query in the
+     * router prompt (role + task framing). When omitted, the SDK built-in
+     * default is used. The server catalog, user query, and output rules are
+     * always appended by the SDK regardless of this value.
+     */
+    routerPromptPrefix?: string;
+};
+/** Catalog entry pairing a server descriptor with its registered tool names. */
+export type ToolRoutingCatalogEntry = {
+    id: string;
+    description: string;
+    /** Registered tool names for this server, i.e. `${serverId}_${toolName}`. */
+    toolNames: string[];
+};
+/** Parameters for `resolveToolRoutingExclusions()`. */
+export type ToolRoutingResolutionParams = {
+    /** Full catalog; always-include servers are filtered out internally. */
+    catalog: ToolRoutingCatalogEntry[];
+    /** Server ids never offered to the router. */
+    alwaysIncludeServerIds: string[];
+    /** Current user query (the stream input text, before memory enrichment). */
+    userQuery: string;
+    /** Instruction text placed before the user query. Defaults to the SDK built-in. */
+    routerPromptPrefix?: string;
+    /** Router LLM settings, already resolved against the stream call's options. */
+    routerModel: ToolRoutingModelConfig;
+    /** Timeout for the router call in milliseconds. */
+    timeoutMs: number;
+    /** Invokes the router LLM — `NeuroLink.generate` bound by the caller. */
+    generateFn: (options: GenerateOptions) => Promise<GenerateResult>;
+};

package/dist/types/toolRouting.js

@@ -0,0 +1,18 @@
+/**
+ * Pre-call tool routing — configuration and catalog types.
+ *
+ * Host applications can register large numbers of custom tools (typically MCP
+ * server tools) whose names are prefixed with their server id
+ * (`${serverId}_${toolName}`). When tool routing is enabled, a cheap router
+ * LLM call runs once per `stream()` turn, picks the servers relevant to the
+ * user query, and the tools of every unpicked server are appended to the
+ * request's `excludeTools` denylist before the main model call.
+ *
+ * Denylist semantics are deliberate: the router only knows the declared
+ * server catalog — a strict subset of the real tool set. Excluding unpicked
+ * servers leaves NeuroLink's built-in direct tools, always-include servers,
+ * and any tools outside the catalog untouched. The whole mechanism fails
+ * open: any router failure resolves to an empty exclusion list (all tools),
+ * identical to routing being disabled.
+ */
+export {};

package/dist/voice/livekit/brain.js

@@ -61,7 +61,7 @@ export function createVoiceBrain(config) {
         });
         for await (const chunk of result.stream) {
             if (signal?.aborted) {
-                logger.debug("[LiveKitBrain] Turn aborted mid-stream; stopping");
+                logger.debug("voice.brain.turnAborted", { reason: "signal-aborted" });
                 return;
             }
             const delta = extractTextDelta(chunk);

package/dist/voice/livekit/config.d.ts

@@ -7,7 +7,7 @@
  *
  * See docs/features/livekit-voice-agent.md.
  */
-import type { LiveKitServerConfig, LiveKitBrainDefaults } from "../../types/index.js";
+import type { LiveKitServerConfig, LiveKitBrainDefaults, RealtimeVoiceConfig } from "../../types/index.js";
 /**
  * Resolve LiveKit server connection settings from the environment.
  *
@@ -23,6 +23,17 @@ export declare function resolveLiveKitServerConfig(): LiveKitServerConfig;
  * `VOICE_LLM_MODEL`.
  */
 export declare function resolveBrainDefaults(): LiveKitBrainDefaults;
+/**
+ * Resolve the realtime (Gemini Live speech-to-speech) voice configuration from
+ * the environment.
+ *
+ * Every value has a safe default so a worker can run with no realtime-specific
+ * env at all. Vertex `project` is resolved from `VERTEX_PROJECT`, then the
+ * service-account project (`GOOGLE_AUTH_BREEZE_PROJECT_ID`), then
+ * `GOOGLE_CLOUD_PROJECT_ID`. The MCP URL is `VOICE_MCP_URL` if set, otherwise
+ * `${LIGHTHOUSE_URL}/ai/mcp/v2`.
+ */
+export declare function resolveRealtimeVoiceConfig(): RealtimeVoiceConfig;
 /**
  * Resolve the semantic end-of-utterance (EOU) turn-detection settings.
  *

package/dist/voice/livekit/config.js

@@ -25,6 +25,22 @@ function readEnv(name, fallback) {
     }
     return fallback;
 }
+function readOptionalEnv(name) {
+    const value = process.env[name];
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function readNumberEnv(name, fallback) {
+    const raw = process.env[name];
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        const parsed = Number(raw.trim());
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return fallback;
+}
 /**
  * Resolve LiveKit server connection settings from the environment.
  *
@@ -51,6 +67,44 @@ export function resolveBrainDefaults() {
         model: readEnv("VOICE_LLM_MODEL", DEFAULT_LLM_MODEL),
     };
 }
+const DEFAULT_REALTIME_MODEL = "gemini-live-2.5-flash";
+const DEFAULT_REALTIME_LOCATION = "global";
+const DEFAULT_RESPONSE_MODALITY = "AUDIO";
+const DEFAULT_SYSTEM_PROMPT = "You are a concise voice assistant for a merchant dashboard. Keep replies short and spoken.";
+const DEFAULT_GREETING = "Briefly greet the merchant and ask how you can help with their store today.";
+const DEFAULT_LIGHTHOUSE_URL = "http://localhost:5173";
+const DEFAULT_MCP_PATH = "/ai/mcp/v2";
+/**
+ * Resolve the realtime (Gemini Live speech-to-speech) voice configuration from
+ * the environment.
+ *
+ * Every value has a safe default so a worker can run with no realtime-specific
+ * env at all. Vertex `project` is resolved from `VERTEX_PROJECT`, then the
+ * service-account project (`GOOGLE_AUTH_BREEZE_PROJECT_ID`), then
+ * `GOOGLE_CLOUD_PROJECT_ID`. The MCP URL is `VOICE_MCP_URL` if set, otherwise
+ * `${LIGHTHOUSE_URL}/ai/mcp/v2`.
+ */
+export function resolveRealtimeVoiceConfig() {
+    const lighthouseUrl = readEnv("LIGHTHOUSE_URL", DEFAULT_LIGHTHOUSE_URL);
+    const mcpUrl = readEnv("VOICE_MCP_URL", `${lighthouseUrl}${DEFAULT_MCP_PATH}`);
+    return {
+        project: readOptionalEnv("VERTEX_PROJECT") ??
+            readOptionalEnv("GOOGLE_AUTH_BREEZE_PROJECT_ID") ??
+            readOptionalEnv("GOOGLE_CLOUD_PROJECT_ID"),
+        location: readEnv("VERTEX_LOCATION", DEFAULT_REALTIME_LOCATION),
+        model: readEnv("VOICE_LIVE_MODEL", DEFAULT_REALTIME_MODEL),
+        voice: readOptionalEnv("VOICE_S2S_VOICE"),
+        responseModality: readEnv("VOICE_RESPONSE_MODALITY", DEFAULT_RESPONSE_MODALITY).toUpperCase(),
+        systemPrompt: readEnv("VOICE_SYSTEM_PROMPT", DEFAULT_SYSTEM_PROMPT),
+        greeting: readEnv("VOICE_GREETING", DEFAULT_GREETING),
+        toolsEnabled: readEnv("VOICE_S2S_TOOLS", "").toLowerCase() === "true",
+        mcpUrl,
+        emptyRoomGraceMs: readNumberEnv("VOICE_EMPTY_ROOM_GRACE_MS", 30_000),
+        joinDeadlineMs: readNumberEnv("VOICE_JOIN_DEADLINE_MS", 60_000),
+        hitlTimeoutMs: readNumberEnv("VOICE_HITL_TIMEOUT_MS", 45_000),
+        metricsIntervalMs: readNumberEnv("VOICE_METRICS_INTERVAL_MS", 10_000),
+    };
+}
 const EOU_TRUTHY = new Set(["1", "true", "english", "en", "on", "yes"]);
 /**
  * Resolve the semantic end-of-utterance (EOU) turn-detection settings.

package/dist/voice/livekit/eventBridge.js

@@ -191,7 +191,7 @@ export async function attachEventBridge(params) {
         const json = JSON.stringify(envelope);
         const bytes = encoder.encode(json);
         const onError = (transport) => (error) => {
-            logger.warn("[LiveKitEventBridge] Failed to publish event", {
+            logger.warn("voice.bridge.publishFailed", {
                 transport,
                 type: event.type,
                 error: error instanceof Error ? error.message : String(error),
@@ -304,7 +304,7 @@ export async function attachEventBridge(params) {
             parsed = JSON.parse(decoder.decode(payload));
         }
         catch (error) {
-            logger.warn("[LiveKitEventBridge] Dropping malformed control message", {
+            logger.warn("voice.bridge.controlMalformed", {
                 error: error instanceof Error ? error.message : String(error),
             });
             return;
@@ -332,7 +332,7 @@ export async function attachEventBridge(params) {
     };
     room.on(RoomEvent.DataReceived, onData);
     publish({ type: "status", data: { state: "listening" } });
-    logger.info("[LiveKitEventBridge] Attached", {
+    logger.info("voice.bridge.attached", {
         eventsTopic,
         controlTopic,
         filtered: include !== undefined,
@@ -353,7 +353,7 @@ export async function attachEventBridge(params) {
             emitter.off(STREAM_END_EVENT, onStreamComplete);
             emitter.off(STREAM_ERROR_EVENT, onStreamError);
             room.off(RoomEvent.DataReceived, onData);
-            logger.info("[LiveKitEventBridge] Disposed");
+            logger.info("voice.bridge.disposed", {});
         },
     };
 }

package/dist/voice/livekit/index.d.ts

@@ -8,8 +8,15 @@
  * See docs/features/livekit-voice-agent.md.
  */
 export { createVoiceBrain } from "./brain.js";
-export { resolveLiveKitServerConfig, resolveBrainDefaults } from "./config.js";
+export { resolveLiveKitServerConfig, resolveBrainDefaults, resolveRealtimeVoiceConfig, } from "./config.js";
 export { attachEventBridge } from "./eventBridge.js";
+export { attachRealtimeEventBridge } from "./realtimeEventBridge.js";
 export { mintJoinToken } from "./tokens.js";
+export { createVoiceRoom, dispatchVoiceAgent } from "./roomDispatch.js";
 export { defineVoiceAgent } from "./voiceAgent.js";
-export { startVoiceAgentWorker } from "./voiceAgentWorker.js";
+export { defineRealtimeVoiceAgent } from "./realtimeVoiceAgent.js";
+export { startVoiceAgentWorker, startRealtimeVoiceAgentWorker, installVoiceWorkerProcessGuards, } from "./voiceAgentWorker.js";
+export { ensureVertexAdc, clearGeminiApiKeyEnv } from "./vertexAuth.js";
+export { readCallContextFromRoom } from "./roomContext.js";
+export { sanitizeSchema, sanitizeToolParameters, findSchemaIssue, } from "./schemaSanitizer.js";
+export { buildRealtimeMcpTools, mcpResultToText } from "./realtimeMcpTools.js";

package/dist/voice/livekit/index.js

@@ -8,8 +8,15 @@
  * See docs/features/livekit-voice-agent.md.
  */
 export { createVoiceBrain } from "./brain.js";
-export { resolveLiveKitServerConfig, resolveBrainDefaults } from "./config.js";
+export { resolveLiveKitServerConfig, resolveBrainDefaults, resolveRealtimeVoiceConfig, } from "./config.js";
 export { attachEventBridge } from "./eventBridge.js";
+export { attachRealtimeEventBridge } from "./realtimeEventBridge.js";
 export { mintJoinToken } from "./tokens.js";
+export { createVoiceRoom, dispatchVoiceAgent } from "./roomDispatch.js";
 export { defineVoiceAgent } from "./voiceAgent.js";
-export { startVoiceAgentWorker } from "./voiceAgentWorker.js";
+export { defineRealtimeVoiceAgent } from "./realtimeVoiceAgent.js";
+export { startVoiceAgentWorker, startRealtimeVoiceAgentWorker, installVoiceWorkerProcessGuards, } from "./voiceAgentWorker.js";
+export { ensureVertexAdc, clearGeminiApiKeyEnv } from "./vertexAuth.js";
+export { readCallContextFromRoom } from "./roomContext.js";
+export { sanitizeSchema, sanitizeToolParameters, findSchemaIssue, } from "./schemaSanitizer.js";
+export { buildRealtimeMcpTools, mcpResultToText } from "./realtimeMcpTools.js";

package/dist/voice/livekit/realtimeEventBridge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Realtime data-channel event bridge.
+ *
+ * The cascaded bridge (`eventBridge.ts`) is driven by NeuroLink's event emitter.
+ */
+import type { RealtimeEventBridgeHandle, RealtimeEventBridgeParams } from "../../types/index.js";
+/**
+ * Attach the realtime event bridge to a room.
+ *
+ * Returns `publishEvent` (worker → browser), `requestConfirmation` (HITL
+ * round-trip), and `dispose` (remove the control listener, decline anything
+ * still pending).
+ */
+export declare function attachRealtimeEventBridge(params: RealtimeEventBridgeParams): Promise<RealtimeEventBridgeHandle>;

package/dist/voice/livekit/realtimeEventBridge.js

@@ -0,0 +1,160 @@
+/**
+ * Realtime data-channel event bridge.
+ *
+ * The cascaded bridge (`eventBridge.ts`) is driven by NeuroLink's event emitter.
+ */
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+const DEFAULT_EVENTS_TOPIC = "ai-events";
+const DEFAULT_CONTROL_TOPIC = "ai-control";
+const DEFAULT_MAX_INLINE_BYTES = 12_000;
+const DEFAULT_HITL_TIMEOUT_MS = 45_000;
+const hitlControlMessageSchema = z.object({
+    action: z.enum(["hitl:accept", "hitl:reject"]),
+    confirmationId: z.string(),
+});
+/**
+ * Attach the realtime event bridge to a room.
+ *
+ * Returns `publishEvent` (worker → browser), `requestConfirmation` (HITL
+ * round-trip), and `dispose` (remove the control listener, decline anything
+ * still pending).
+ */
+export async function attachRealtimeEventBridge(params) {
+    const { room } = params;
+    const eventsTopic = params.eventsTopic ?? DEFAULT_EVENTS_TOPIC;
+    const controlTopic = params.controlTopic ?? DEFAULT_CONTROL_TOPIC;
+    const maxInlineBytes = params.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+    const hitlTimeoutMs = params.hitlTimeoutMs ?? DEFAULT_HITL_TIMEOUT_MS;
+    const { RoomEvent } = await import("@livekit/rtc-node");
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    let seq = 0;
+    let disposed = false;
+    const startedAt = Date.now();
+    const publishEvent = (type, data) => {
+        if (disposed) {
+            return;
+        }
+        const participant = room.localParticipant;
+        if (!participant) {
+            return;
+        }
+        try {
+            seq += 1;
+            const json = JSON.stringify({ seq, ts: Date.now(), type, data });
+            const bytes = encoder.encode(json);
+            const via = bytes.byteLength <= maxInlineBytes ? "data" : "stream";
+            logger.debug("realtime.bridge.publish", {
+                ms: Date.now() - startedAt,
+                seq,
+                type,
+                via,
+                bytes: bytes.byteLength,
+            });
+            if (via === "data") {
+                void participant.publishData(bytes, {
+                    reliable: true,
+                    topic: eventsTopic,
+                });
+            }
+            else {
+                void participant.sendText(json, { topic: eventsTopic });
+            }
+        }
+        catch {
+            /* non-fatal — the UI bridge is best-effort */
+        }
+    };
+    // HITL: WRITE-labeled tools pause for user confirmation. We publish a
+    // `hitl-prompt`, the UI replies on the control topic, and we resolve the
+    // pending request by confirmationId. A timeout is treated as a decline so a
+    // turn can never hang waiting on the user.
+    const pendingHitl = new Map();
+    let hitlSeq = 0;
+    const onData = (...args) => {
+        const payload = args[0];
+        const topic = args[3];
+        if (topic !== controlTopic || !(payload instanceof Uint8Array)) {
+            return;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(decoder.decode(payload));
+        }
+        catch {
+            return;
+        }
+        const message = hitlControlMessageSchema.safeParse(raw);
+        if (!message.success) {
+            return;
+        }
+        const { action, confirmationId } = message.data;
+        const resolver = pendingHitl.get(confirmationId);
+        if (resolver) {
+            logger.debug("realtime.bridge.controlReceived", {
+                action,
+                confirmationId,
+            });
+            pendingHitl.delete(confirmationId);
+            resolver(action === "hitl:accept");
+        }
+        else {
+            logger.warn("realtime.bridge.controlUnmatched", {
+                action,
+                confirmationId,
+            });
+        }
+    };
+    room.on(RoomEvent.DataReceived, onData);
+    const requestConfirmation = (toolName, args) => {
+        if (disposed) {
+            logger.warn("realtime.bridge.hitlDisposed", { toolName });
+            return Promise.resolve(false);
+        }
+        hitlSeq += 1;
+        const confirmationId = `hitl_${seq}_${hitlSeq}`;
+        publishEvent("hitl-prompt", {
+            confirmationId,
+            toolName,
+            actionType: `Run ${toolName}`,
+            arguments: args ?? {},
+        });
+        logger.info("realtime.bridge.hitlPrompt", { toolName, confirmationId });
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                pendingHitl.delete(confirmationId);
+                logger.warn("realtime.bridge.hitlTimeout", {
+                    toolName,
+                    confirmationId,
+                    timeoutMs: hitlTimeoutMs,
+                });
+                resolve(false);
+            }, hitlTimeoutMs);
+            pendingHitl.set(confirmationId, (approved) => {
+                clearTimeout(timer);
+                logger.info("realtime.bridge.hitlResolved", {
+                    toolName,
+                    confirmationId,
+                    approved,
+                });
+                resolve(approved);
+            });
+        });
+    };
+    return {
+        publishEvent,
+        requestConfirmation,
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            room.off(RoomEvent.DataReceived, onData);
+            for (const [, resolver] of pendingHitl) {
+                resolver(false);
+            }
+            pendingHitl.clear();
+        },
+    };
+}