@juspay/neurolink 9.72.0 → 9.73.0

package/dist/lib/voice/livekit/realtimeMcpTools.js

@@ -0,0 +1,194 @@
+/**
+ * MCP tools → Gemini function tools bridge (realtime mode).
+ *
+ * In speech-to-speech mode Gemini owns the tool loop, so an external MCP
+ * server's tools are registered as LiveKit/Gemini function tools rather than
+ * NeuroLink tools. This connects to the MCP server as the calling user
+ * (`x-auth-token` + base64 `x-context`), sanitizes each tool's schema into the
+ * Gemini-safe subset, wires WRITE-labeled (destructive) tools through a HITL
+ * confirmation, and forwards tool start/result events to the browser bridge.
+ *
+ * `@livekit/agents` and `@modelcontextprotocol/sdk` are imported dynamically so
+ * the core package does not require them unless the realtime agent is used.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+import { findSchemaIssue, sanitizeToolParameters } from "./schemaSanitizer.js";
+/**
+ * The fields of an MCP tool result we render: text content parts and the error
+ * flag. The result crosses a network boundary from an external MCP server, so it
+ * is decoded with a schema (other content kinds — image, resource — are dropped).
+ */
+const toolResultSchema = z.object({
+    isError: z.boolean().optional(),
+    content: z
+        .array(z.object({ type: z.string().optional(), text: z.string().optional() }))
+        .optional(),
+});
+/** Flatten an MCP tool result's text content into a single string for the model. */
+export function mcpResultToText(result) {
+    const decoded = toolResultSchema.safeParse(result);
+    if (!decoded.success) {
+        return "Tool returned no content.";
+    }
+    const text = (decoded.data.content ?? [])
+        .map((part) => (part.type === "text" && part.text ? part.text : ""))
+        .filter(Boolean)
+        .join("\n")
+        .trim();
+    if (decoded.data.isError) {
+        return `Tool error: ${text || "unknown error"}`;
+    }
+    return text || "Tool returned no content.";
+}
+/**
+ * The function-result text returned to Gemini when the user rejects a HITL tool.
+ * Scope the rejection to THIS attempt — a "never retry" wording made the model
+ * refuse the tool permanently even when the user later asked for it again.
+ */
+function buildHitlDeclineMessage(toolName) {
+    return (`The user reviewed the request to run "${toolName}" and chose to reject it, ` +
+        `so it was NOT executed this time. Do not run it right now. Briefly let the user know ` +
+        `you didn't proceed because they declined, and ask if there's anything else. ` +
+        `If the user later asks for "${toolName}" again or says to go ahead, you may run it then — ` +
+        `this rejection applies only to this request, not to all future requests.`);
+}
+/**
+ * Register a tool handler under the name variants the model might call:
+ *   1. the Gemini-safe full name (hyphens → underscores; Gemini rewrites these
+ *      itself, so the rewritten form must be registered or the round-trip fails)
+ *   2. the bare short name (the model often drops the server prefix)
+ * First registration wins, so a unique full name is never shadowed by a generic
+ * short name. Returns the aliases actually registered.
+ */
+function registerToolAliases(toolContext, mcpToolName, handler) {
+    const safeFullName = mcpToolName.replace(/[^a-zA-Z0-9_]/g, "_");
+    const shortName = safeFullName.includes("_")
+        ? safeFullName.slice(safeFullName.lastIndexOf("_") + 1)
+        : safeFullName;
+    const candidates = [safeFullName, shortName].filter((name, index, all) => name.length > 0 && all.indexOf(name) === index);
+    const registered = [];
+    for (const alias of candidates) {
+        if (alias in toolContext) {
+            continue; // taken by another tool — don't clobber
+        }
+        toolContext[alias] = handler;
+        registered.push(alias);
+    }
+    return registered;
+}
+/**
+ * Connect to the MCP server as the calling user and bridge every tool into a
+ * LiveKit `ToolContext`. Returns the tool map + the client (close on shutdown).
+ * The server already scopes the tool list by `x-context`, so no client-side
+ * filtering is needed.
+ */
+export async function buildRealtimeMcpTools(params) {
+    const { mcpUrl, authToken, xContext, publishEvent, requestConfirmation } = params;
+    const { llm } = await import("@livekit/agents");
+    const { Client: McpClient } = await import("@modelcontextprotocol/sdk/client/index.js");
+    const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    const transport = new StreamableHTTPClientTransport(new URL(mcpUrl), {
+        requestInit: {
+            headers: { "x-auth-token": authToken, "x-context": xContext },
+        },
+    });
+    const client = new McpClient({ name: "neurolink-realtime-voice", version: "1.0.0" }, { capabilities: {} });
+    logger.info("realtime.mcp.connecting", {
+        mcpUrl,
+        hasAuthToken: authToken !== "",
+        hasContext: xContext !== "",
+    });
+    await client.connect(transport);
+    try {
+        const { tools: mcpTools } = await client.listTools();
+        logger.info("realtime.mcp.toolsListed", { count: mcpTools.length });
+        const toolContext = {};
+        const skipped = [];
+        for (const mcpTool of mcpTools) {
+            const parameters = sanitizeToolParameters(mcpTool.inputSchema);
+            const issue = findSchemaIssue(parameters);
+            if (issue) {
+                skipped.push(mcpTool.name);
+                logger.warn("realtime.mcp.toolSkipped", {
+                    tool: mcpTool.name,
+                    issue,
+                    rawInputSchema: JSON.stringify(mcpTool.inputSchema),
+                });
+                continue;
+            }
+            const requiresConfirmation = mcpTool.annotations?.destructiveHint === true;
+            const handler = llm.tool({
+                description: mcpTool.description ?? mcpTool.name,
+                parameters,
+                execute: async (args) => {
+                    if (requiresConfirmation) {
+                        const approved = await requestConfirmation(mcpTool.name, args ?? {});
+                        if (!approved) {
+                            logger.info("realtime.tool.hitlRejected", {
+                                tool: mcpTool.name,
+                            });
+                            return buildHitlDeclineMessage(mcpTool.name);
+                        }
+                        logger.info("realtime.tool.hitlApproved", { tool: mcpTool.name });
+                    }
+                    logger.info("realtime.tool.invoke", {
+                        tool: mcpTool.name,
+                        args: args ?? {},
+                    });
+                    publishEvent("tool-start", { name: mcpTool.name });
+                    const startedAt = Date.now();
+                    try {
+                        const result = await client.callTool({
+                            name: mcpTool.name,
+                            arguments: args ?? {},
+                        });
+                        const text = mcpResultToText(result);
+                        logger.info("realtime.tool.result", {
+                            tool: mcpTool.name,
+                            isError: result.isError === true,
+                            chars: text.length,
+                            ms: Date.now() - startedAt,
+                        });
+                        // Forward the RAW result so the client can extract a
+                        // chart/UIComponent and clear the in-progress indicator.
+                        publishEvent("tool-result", { name: mcpTool.name, result });
+                        return text;
+                    }
+                    catch (error) {
+                        logger.error("realtime.tool.error", {
+                            tool: mcpTool.name,
+                            ms: Date.now() - startedAt,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        publishEvent("tool-result", { name: mcpTool.name, result: null });
+                        return `Tool ${mcpTool.name} failed: ${String(error)}`;
+                    }
+                },
+            });
+            const aliases = registerToolAliases(toolContext, mcpTool.name, handler);
+            logger.info("realtime.mcp.toolRegistered", {
+                tool: mcpTool.name,
+                aliases,
+                hitl: requiresConfirmation,
+            });
+        }
+        logger.info("realtime.mcp.connected", {
+            registered: Object.keys(toolContext).length,
+            skipped: skipped.length,
+            skippedTools: skipped,
+        });
+        return { tools: toolContext, client };
+    }
+    catch (error) {
+        await client.close().catch((closeError) => {
+            logger.warn("realtime.mcp.closeFailed", {
+                error: closeError instanceof Error ? closeError.message : String(closeError),
+            });
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=realtimeMcpTools.js.map

package/dist/lib/voice/livekit/realtimeVoiceAgent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * LiveKit Agents agent definition — realtime (Gemini Live speech-to-speech).
+ *
+ * `defineRealtimeVoiceAgent` returns the agent object placed as the default
+ * export of a worker entry file. Unlike the cascaded `defineVoiceAgent`
+ * (Silero VAD → STT → NeuroLink → TTS), here a single realtime model (Gemini
+ * Live on Vertex) does STT + reasoning + TTS + turn detection over one
+ *
+ * `@livekit/agents`, `@livekit/agents-plugin-google`, `@livekit/rtc-node`, and
+ * `@google/genai` are imported dynamically so the core package does not require
+ * them unless the realtime agent is used. Type-only imports are erased at build.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { JobContext } from "@livekit/agents";
+import type { RealtimeVoiceAgentConfig } from "../../types/index.js";
+/**
+ * Define a realtime (Gemini Live S2S) LiveKit voice agent.
+ *
+ * Place the result as the default export of the worker entry file and launch it
+ * with `startRealtimeVoiceAgentWorker`. With no `config` everything is resolved
+ * from the environment (see `resolveRealtimeVoiceConfig`).
+ */
+export declare function defineRealtimeVoiceAgent(config?: RealtimeVoiceAgentConfig): {
+    entry: (ctx: JobContext) => Promise<void>;
+};

package/dist/lib/voice/livekit/realtimeVoiceAgent.js

@@ -0,0 +1,362 @@
+/**
+ * LiveKit Agents agent definition — realtime (Gemini Live speech-to-speech).
+ *
+ * `defineRealtimeVoiceAgent` returns the agent object placed as the default
+ * export of a worker entry file. Unlike the cascaded `defineVoiceAgent`
+ * (Silero VAD → STT → NeuroLink → TTS), here a single realtime model (Gemini
+ * Live on Vertex) does STT + reasoning + TTS + turn detection over one
+ *
+ * `@livekit/agents`, `@livekit/agents-plugin-google`, `@livekit/rtc-node`, and
+ * `@google/genai` are imported dynamically so the core package does not require
+ * them unless the realtime agent is used. Type-only imports are erased at build.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+import { resolveRealtimeVoiceConfig } from "./config.js";
+import { ensureVertexAdc, clearGeminiApiKeyEnv } from "./vertexAuth.js";
+import { readCallContextFromRoom } from "./roomContext.js";
+import { attachRealtimeEventBridge } from "./realtimeEventBridge.js";
+import { buildRealtimeMcpTools } from "./realtimeMcpTools.js";
+const realtimeLogEventSchema = z.object({
+    level: z.enum(["debug", "info", "warn", "error"]),
+    message: z.string(),
+    timestamp: z.number(),
+    data: z.unknown().optional(),
+});
+/**
+ * Install the per-call job lifecycle: shut down when the caller leaves, log
+ * connection transitions, run the empty-room / join-deadline watchdog, and reap
+ * the worker (parent) + this job (child) on shutdown.
+ *
+ * In `connect` mode the worker does NOT exit when a job shuts down, so the child
+ * must SIGTERM its parent and hard-exit itself.
+ */
+async function installRealtimeJobLifecycle(ctx, cfg) {
+    const { RoomEvent } = await import("@livekit/rtc-node");
+    const joinedAt = Date.now();
+    ctx.room.on(RoomEvent.ParticipantDisconnected, () => {
+        if (ctx.room.remoteParticipants.size === 0) {
+            logger.info("realtime.room.participantLeft", {
+                remotes: 0,
+                action: "shutdown",
+            });
+            ctx.shutdown("participant left");
+        }
+    });
+    const logConn = (label) => (...args) => {
+        if (!logger.shouldLog("debug")) {
+            return;
+        }
+        logger.debug("realtime.room.connection", {
+            event: label,
+            remotes: ctx.room.remoteParticipants.size,
+            ...(args.length ? { detail: JSON.stringify(args).slice(0, 200) } : {}),
+        });
+    };
+    ctx.room.on(RoomEvent.Disconnected, (...args) => {
+        logConn("Disconnected")(...args);
+        ctx.shutdown("room disconnected");
+    });
+    ctx.room.on(RoomEvent.Reconnecting, logConn("Reconnecting"));
+    ctx.room.on(RoomEvent.Reconnected, logConn("Reconnected"));
+    ctx.room.on(RoomEvent.ConnectionStateChanged, logConn("ConnectionStateChanged"));
+    ctx.room.on(RoomEvent.ConnectionQualityChanged, logConn("ConnectionQualityChanged"));
+    let sawParticipant = ctx.room.remoteParticipants.size > 0;
+    let emptySince = null;
+    const emptyRoomWatchdog = setInterval(() => {
+        const remotes = ctx.room.remoteParticipants.size;
+        if (remotes > 0) {
+            sawParticipant = true;
+            emptySince = null;
+            return;
+        }
+        if (sawParticipant) {
+            emptySince ??= Date.now();
+            if (Date.now() - emptySince >= cfg.emptyRoomGraceMs) {
+                logger.info("realtime.watchdog.emptyRoom", {
+                    graceMs: cfg.emptyRoomGraceMs,
+                    action: "shutdown",
+                });
+                ctx.shutdown("empty-room watchdog");
+            }
+        }
+        else if (Date.now() - joinedAt >= cfg.joinDeadlineMs) {
+            logger.info("realtime.watchdog.joinDeadline", {
+                joinDeadlineMs: cfg.joinDeadlineMs,
+                action: "shutdown",
+            });
+            ctx.shutdown("join-deadline watchdog");
+        }
+    }, 5000);
+    emptyRoomWatchdog.unref?.();
+    ctx.addShutdownCallback(async () => {
+        clearInterval(emptyRoomWatchdog);
+    });
+    if (process.env.LK_REALTIME_CONNECT_MODE === "true") {
+        ctx.addShutdownCallback(async () => {
+            const parentPid = process.ppid;
+            logger.info("realtime.reap.parent", {
+                mode: "connect",
+                jobPid: process.pid,
+                parentPid,
+            });
+            if (typeof parentPid === "number" && parentPid > 1) {
+                try {
+                    process.kill(parentPid, "SIGTERM");
+                }
+                catch {
+                    logger.debug("realtime.reap.parentGone", { parentPid });
+                }
+            }
+            setTimeout(() => {
+                process.exit(0);
+            }, 1000);
+        });
+    }
+}
+/** Merge caller overrides over the env-resolved realtime config. */
+function resolveConfig(overrides) {
+    const base = resolveRealtimeVoiceConfig();
+    return {
+        ...base,
+        project: overrides.project ?? base.project,
+        location: overrides.location ?? base.location,
+        model: overrides.model ?? base.model,
+        voice: overrides.voice ?? base.voice,
+        responseModality: overrides.responseModality ?? base.responseModality,
+        systemPrompt: overrides.systemPrompt ?? base.systemPrompt,
+        greeting: overrides.greeting ?? base.greeting,
+        toolsEnabled: overrides.tools?.enabled ?? base.toolsEnabled,
+        mcpUrl: overrides.tools?.mcpUrl ?? base.mcpUrl,
+    };
+}
+/**
+ * Define a realtime (Gemini Live S2S) LiveKit voice agent.
+ *
+ * Place the result as the default export of the worker entry file and launch it
+ * with `startRealtimeVoiceAgentWorker`. With no `config` everything is resolved
+ * from the environment (see `resolveRealtimeVoiceConfig`).
+ */
+export function defineRealtimeVoiceAgent(config = {}) {
+    const cfg = resolveConfig(config);
+    const eventsTopic = config.eventsTopic;
+    const controlTopic = config.controlTopic;
+    const onLog = config.onLog;
+    async function entry(ctx) {
+        // The Gemini Live WS authenticates to Vertex via ADC; materialise it and
+        // force ADC (not an API key) auth before any realtime connection.
+        ensureVertexAdc();
+        clearGeminiApiKeyEnv();
+        logger.info("realtime.config", {
+            model: cfg.model,
+            location: cfg.location,
+            project: cfg.project ?? null,
+            voice: cfg.voice ?? null,
+            modality: cfg.responseModality,
+            toolsEnabled: cfg.toolsEnabled,
+            mcpUrl: cfg.mcpUrl,
+        });
+        await ctx.connect();
+        const connectedAt = Date.now();
+        const sinceConnect = () => Date.now() - connectedAt;
+        if (onLog) {
+            const room = ctx.room.name ?? "unknown";
+            logger.setEventEmitter({
+                emit: (event, ...args) => {
+                    if (event === "log-event") {
+                        const decoded = realtimeLogEventSchema.safeParse(args[0]);
+                        if (decoded.success) {
+                            try {
+                                onLog(decoded.data, { room });
+                            }
+                            catch {
+                                /* a log sink must never break the call */
+                            }
+                        }
+                    }
+                    return true;
+                },
+            });
+            ctx.addShutdownCallback(async () => {
+                logger.clearEventEmitter();
+            });
+        }
+        logger.info("realtime.room.joined", {
+            room: ctx.room.name ?? "unknown",
+            model: cfg.model,
+            location: cfg.location,
+            ms: sinceConnect(),
+        });
+        await installRealtimeJobLifecycle(ctx, cfg);
+        const { voice } = await import("@livekit/agents");
+        const google = await import("@livekit/agents-plugin-google");
+        const { Modality } = await import("@google/genai");
+        const bridge = await attachRealtimeEventBridge({
+            room: ctx.room,
+            hitlTimeoutMs: cfg.hitlTimeoutMs,
+            ...(eventsTopic !== undefined ? { eventsTopic } : {}),
+            ...(controlTopic !== undefined ? { controlTopic } : {}),
+        });
+        ctx.addShutdownCallback(async () => {
+            bridge.dispose();
+        });
+        let agentTools;
+        if (cfg.toolsEnabled) {
+            const { authToken, xContext } = readCallContextFromRoom(ctx.room.metadata);
+            if (xContext === "") {
+                logger.warn("realtime.mcp.noContext", {
+                    reason: "room-metadata-missing-context",
+                    action: "running-without-tools",
+                });
+            }
+            else {
+                try {
+                    const toolset = await buildRealtimeMcpTools({
+                        mcpUrl: cfg.mcpUrl,
+                        authToken,
+                        xContext,
+                        publishEvent: bridge.publishEvent,
+                        requestConfirmation: bridge.requestConfirmation,
+                    });
+                    agentTools = toolset.tools;
+                    logger.info("realtime.mcp.enabled", {
+                        mcpUrl: cfg.mcpUrl,
+                        toolCount: Object.keys(toolset.tools).length,
+                        hasAuthToken: authToken !== "",
+                    });
+                    ctx.addShutdownCallback(async () => {
+                        await toolset.client.close();
+                    });
+                }
+                catch (error) {
+                    logger.error("realtime.mcp.setupFailed", {
+                        mcpUrl: cfg.mcpUrl,
+                        error: error instanceof Error ? error.message : String(error),
+                        action: "running-without-tools",
+                    });
+                }
+            }
+        }
+        const modality = Object.values(Modality).find((value) => value === cfg.responseModality);
+        const modelOptions = {
+            vertexai: true,
+            model: cfg.model,
+            // Emit text transcripts of BOTH sides; LiveKit forwards them to the room.
+            inputAudioTranscription: {},
+            outputAudioTranscription: {},
+        };
+        if (modality !== undefined) {
+            modelOptions.modalities = [modality];
+        }
+        if (cfg.project) {
+            modelOptions.project = cfg.project;
+        }
+        if (cfg.location) {
+            modelOptions.location = cfg.location;
+        }
+        if (cfg.voice) {
+            modelOptions.voice = cfg.voice;
+        }
+        const session = new voice.AgentSession({
+            llm: new google.realtime.RealtimeModel(modelOptions),
+        });
+        const agent = new voice.Agent({
+            instructions: cfg.systemPrompt,
+            ...(agentTools ? { tools: agentTools } : {}),
+        });
+        agent.transcriptionNode = async (textStream, _modelSettings) => {
+            const [forUi, forDownstream] = textStream.tee();
+            void (async () => {
+                const reader = forUi.getReader();
+                let chunkCount = 0;
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done) {
+                            break;
+                        }
+                        const chunk = typeof value === "string" ? value : (value.text ?? "");
+                        if (chunk) {
+                            chunkCount += 1;
+                            if (chunkCount === 1) {
+                                logger.debug("realtime.session.assistantFirstChunk", {
+                                    ms: sinceConnect(),
+                                    preview: chunk.slice(0, 30),
+                                });
+                            }
+                            bridge.publishEvent("text", { delta: chunk });
+                        }
+                    }
+                }
+                catch {
+                    /* best-effort live streaming */
+                }
+            })();
+            return forDownstream;
+        };
+        session.on(voice.AgentSessionEventTypes.MetricsCollected, (ev) => {
+            const metrics = ev.metrics;
+            if (metrics.type !== "realtime_model_metrics") {
+                return;
+            }
+            const inAudio = metrics.inputTokenDetails.audioTokens;
+            const outAudio = metrics.outputTokenDetails.audioTokens;
+            const inText = Math.max(0, metrics.inputTokens - inAudio);
+            const outText = Math.max(0, metrics.outputTokens - outAudio);
+            logger.info("realtime.usage", {
+                inputTokens: metrics.inputTokens,
+                inputAudioTokens: inAudio,
+                inputTextTokens: inText,
+                outputTokens: metrics.outputTokens,
+                outputAudioTokens: outAudio,
+                outputTextTokens: outText,
+            });
+        });
+        // --- Session events → browser ------------------------------------------
+        session.on(voice.AgentSessionEventTypes.UserInputTranscribed, (ev) => {
+            logger.debug("realtime.session.userTranscript", {
+                ms: sinceConnect(),
+                final: ev.isFinal,
+                transcript: ev.transcript,
+            });
+            bridge.publishEvent("user-text", {
+                text: ev.transcript,
+                final: ev.isFinal,
+            });
+        });
+        session.on(voice.AgentSessionEventTypes.AgentStateChanged, (ev) => {
+            logger.debug("realtime.session.stateChanged", {
+                ms: sinceConnect(),
+                from: ev.oldState,
+                to: ev.newState,
+            });
+            bridge.publishEvent("status", { state: ev.newState });
+        });
+        session.on(voice.AgentSessionEventTypes.ConversationItemAdded, (ev) => {
+            if (ev.item.type === "message" &&
+                ev.item.role === "assistant" &&
+                ev.item.textContent) {
+                logger.debug("realtime.session.turnDone", { ms: sinceConnect() });
+                bridge.publishEvent("done", {});
+            }
+        });
+        session.on(voice.AgentSessionEventTypes.Error, (ev) => {
+            logger.error("realtime.session.error", {
+                ms: sinceConnect(),
+                error: ev.error,
+            });
+            bridge.publishEvent("status", { state: "error" });
+        });
+        await session.start({ agent, room: ctx.room });
+        logger.info("realtime.session.start", { ms: sinceConnect() });
+        bridge.publishEvent("status", { state: "listening" });
+        if (cfg.greeting.trim().length > 0) {
+            logger.info("realtime.session.greeting", { ms: sinceConnect() });
+            session.generateReply({ instructions: cfg.greeting });
+        }
+    }
+    return { entry };
+}
+//# sourceMappingURL=realtimeVoiceAgent.js.map

package/dist/lib/voice/livekit/roomContext.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-call context from LiveKit room metadata.
+ *
+ * The manager (e.g. a Lighthouse `/start` endpoint) pre-creates the room with
+ * `base64(JSON({ authToken, mcpContext }))` metadata, built from the caller's
+ * session. The worker reads it on join — nothing per-call comes from worker env.
+ * Returns the MCP `x-auth-token` and the base64(JSON) `x-context` the server
+ * expects.
+ *
+ * The metadata is untrusted input, so it is decoded with a zod schema rather
+ * than a trusted `JSON.parse` cast.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { LiveKitRoomCallContext } from "../../types/index.js";
+/**
+ * Decode `{ authToken, mcpContext }` from a room's base64(JSON) metadata.
+ *
+ * `authToken` may be empty (demo/guest, where the MCP server gates on the
+ * context's `demoMode`); `xContext` is the re-encoded base64(JSON) of
+ * `mcpContext`, or `""` when no context was supplied or the metadata is invalid.
+ */
+export declare function readCallContextFromRoom(roomMetadata: string | undefined): LiveKitRoomCallContext;

package/dist/lib/voice/livekit/roomContext.js

@@ -0,0 +1,57 @@
+/**
+ * Per-call context from LiveKit room metadata.
+ *
+ * The manager (e.g. a Lighthouse `/start` endpoint) pre-creates the room with
+ * `base64(JSON({ authToken, mcpContext }))` metadata, built from the caller's
+ * session. The worker reads it on join — nothing per-call comes from worker env.
+ * Returns the MCP `x-auth-token` and the base64(JSON) `x-context` the server
+ * expects.
+ *
+ * The metadata is untrusted input, so it is decoded with a zod schema rather
+ * than a trusted `JSON.parse` cast.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import { Buffer } from "node:buffer";
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+/** Shape the manager writes into room metadata. `mcpContext` is opaque here. */
+const roomMetadataSchema = z.object({
+    authToken: z.string().optional(),
+    mcpContext: z.unknown().optional(),
+});
+/** Decode the base64(JSON) metadata string into an `unknown`, or `undefined`. */
+function decodeBase64Json(encoded) {
+    try {
+        return JSON.parse(Buffer.from(encoded, "base64").toString("utf-8"));
+    }
+    catch (error) {
+        logger.error(`[RealtimeVoiceAgent] room metadata is not valid base64 JSON: ${String(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Decode `{ authToken, mcpContext }` from a room's base64(JSON) metadata.
+ *
+ * `authToken` may be empty (demo/guest, where the MCP server gates on the
+ * context's `demoMode`); `xContext` is the re-encoded base64(JSON) of
+ * `mcpContext`, or `""` when no context was supplied or the metadata is invalid.
+ */
+export function readCallContextFromRoom(roomMetadata) {
+    const empty = { authToken: "", xContext: "" };
+    if (!roomMetadata) {
+        logger.warn("[RealtimeVoiceAgent] room has no metadata — MCP auth/context unavailable.");
+        return empty;
+    }
+    const decoded = roomMetadataSchema.safeParse(decodeBase64Json(roomMetadata));
+    if (!decoded.success) {
+        logger.error(`[RealtimeVoiceAgent] room metadata has unexpected shape: ${decoded.error.message}`);
+        return empty;
+    }
+    const { authToken, mcpContext } = decoded.data;
+    const xContext = mcpContext === undefined || mcpContext === null
+        ? ""
+        : Buffer.from(JSON.stringify(mcpContext), "utf-8").toString("base64");
+    return { authToken: authToken ?? "", xContext };
+}
+//# sourceMappingURL=roomContext.js.map