@juspay/neurolink 9.71.0 → 9.73.0

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

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

@@ -0,0 +1,24 @@
+/**
+ * LiveKit server-side room operations: create a room with metadata, and
+ * dispatch a named agent to a room.
+ *
+ * Wraps `livekit-server-sdk` (an optional dependency, imported dynamically) so
+ * consumers route all LiveKit *server* calls through `@juspay/neurolink/livekit`
+ * — they never depend on the SDK directly. Mirrors `mintJoinToken`.
+ */
+import type { LiveKitServerCredentials } from "../../types/index.js";
+export declare function createVoiceRoom(req: LiveKitServerCredentials & {
+    room: string;
+    metadata?: string;
+    emptyTimeoutSeconds?: number;
+    departureTimeoutSeconds?: number;
+}): Promise<void>;
+/**
+ * Explicitly dispatch a named agent to a room. The long-lived worker registered
+ * under `agentName` receives the job and forks a child to run the call.
+ */
+export declare function dispatchVoiceAgent(req: LiveKitServerCredentials & {
+    room: string;
+    agentName: string;
+    metadata?: string;
+}): Promise<void>;

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

@@ -0,0 +1,31 @@
+/**
+ * LiveKit server-side room operations: create a room with metadata, and
+ * dispatch a named agent to a room.
+ *
+ * Wraps `livekit-server-sdk` (an optional dependency, imported dynamically) so
+ * consumers route all LiveKit *server* calls through `@juspay/neurolink/livekit`
+ * — they never depend on the SDK directly. Mirrors `mintJoinToken`.
+ */
+const toHttpUrl = (url) => url.replace(/^ws/, "http");
+export async function createVoiceRoom(req) {
+    const { RoomServiceClient } = await import("livekit-server-sdk");
+    const client = new RoomServiceClient(toHttpUrl(req.url), req.apiKey, req.apiSecret);
+    await client.createRoom({
+        name: req.room,
+        metadata: req.metadata ?? "",
+        emptyTimeout: req.emptyTimeoutSeconds ?? 300,
+        departureTimeout: req.departureTimeoutSeconds ?? 20,
+    });
+}
+/**
+ * Explicitly dispatch a named agent to a room. The long-lived worker registered
+ * under `agentName` receives the job and forks a child to run the call.
+ */
+export async function dispatchVoiceAgent(req) {
+    const { AgentDispatchClient } = await import("livekit-server-sdk");
+    const client = new AgentDispatchClient(toHttpUrl(req.url), req.apiKey, req.apiSecret);
+    await client.createDispatch(req.room, req.agentName, {
+        metadata: req.metadata ?? "",
+    });
+}
+//# sourceMappingURL=roomDispatch.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Gemini function-calling schema sanitizer.
+ *
+ * Normalises an MCP tool's JSON Schema into the subset Gemini's function-calling
+ * accepts. `@google/genai`'s processJsonSchema crashes on untyped nodes,
+ * `$ref`/`$defs`, and some `anyOf`/`oneOf` shapes, so we rebuild a clean tree:
+ * every node gets a concrete `type`, unions collapse to their first concrete
+ * branch, and unsupported keywords are dropped.
+ *
+ * Pure, dependency-free, and assertion-free — values arrive as `unknown` and are
+ * narrowed with the `isRecord` guard. Safe to reuse for any Gemini tool path.
+ */
+/**
+ * Rebuild a JSON Schema node into the Gemini-safe subset. Returns a fresh object
+ * with a concrete `type` on every node.
+ */
+export declare function sanitizeSchema(node: unknown): Record<string, unknown>;
+/** Tool parameters must be an object schema; force it and sanitize the tree. */
+export declare function sanitizeToolParameters(schema: unknown): Record<string, unknown>;
+/**
+ * Walk a (sanitized) schema and return the first node the google plugin would
+ * turn into `undefined` — which genai then crashes on. Returns a human-readable
+ * path/reason, or `null` if the schema is safe. After `sanitizeSchema` this
+ * should always be `null`; if not, it names the exact offending path.
+ */
+export declare function findSchemaIssue(node: unknown, pathPrefix?: string): string | null;

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

@@ -0,0 +1,144 @@
+/**
+ * Gemini function-calling schema sanitizer.
+ *
+ * Normalises an MCP tool's JSON Schema into the subset Gemini's function-calling
+ * accepts. `@google/genai`'s processJsonSchema crashes on untyped nodes,
+ * `$ref`/`$defs`, and some `anyOf`/`oneOf` shapes, so we rebuild a clean tree:
+ * every node gets a concrete `type`, unions collapse to their first concrete
+ * branch, and unsupported keywords are dropped.
+ *
+ * Pure, dependency-free, and assertion-free — values arrive as `unknown` and are
+ * narrowed with the `isRecord` guard. Safe to reuse for any Gemini tool path.
+ */
+const GEMINI_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "array",
+    "object",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The first concrete (non-`"null"`-typed) branch of an `anyOf`/`oneOf`/`allOf`
+ * union, or `undefined` when there is no union to collapse.
+ */
+function firstConcreteUnionBranch(schema) {
+    const union = schema.anyOf ?? schema.oneOf ?? schema.allOf;
+    if (!Array.isArray(union)) {
+        return undefined;
+    }
+    return union.find((branch) => isRecord(branch) && branch.type !== "null");
+}
+function resolveSchemaType(schema) {
+    if (typeof schema.type === "string") {
+        return GEMINI_TYPES.has(schema.type) ? schema.type : "string";
+    }
+    if (Array.isArray(schema.type)) {
+        const named = schema.type.find((entry) => typeof entry === "string" && entry !== "null");
+        if (named !== undefined && GEMINI_TYPES.has(named)) {
+            return named;
+        }
+    }
+    if (isRecord(schema.properties)) {
+        return "object";
+    }
+    if (schema.items !== undefined) {
+        return "array";
+    }
+    return "string";
+}
+function sanitizeObjectMembers(schema, out) {
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const sanitizedProperties = {};
+    for (const [key, value] of Object.entries(properties)) {
+        sanitizedProperties[key] = sanitizeSchema(value);
+    }
+    out.properties = sanitizedProperties;
+    if (Array.isArray(schema.required)) {
+        out.required = schema.required.filter((name) => typeof name === "string" && name in sanitizedProperties);
+    }
+    if (Object.keys(sanitizedProperties).length === 0) {
+        out.additionalProperties = true;
+    }
+}
+/**
+ * Rebuild a JSON Schema node into the Gemini-safe subset. Returns a fresh object
+ * with a concrete `type` on every node.
+ */
+export function sanitizeSchema(node) {
+    if (!isRecord(node)) {
+        return { type: "string" };
+    }
+    const out = {};
+    if (typeof node.description === "string") {
+        out.description = node.description;
+    }
+    if (typeof node.type !== "string") {
+        const branch = firstConcreteUnionBranch(node);
+        if (branch !== undefined) {
+            const merged = sanitizeSchema(branch);
+            return out.description
+                ? { ...merged, description: out.description }
+                : merged;
+        }
+    }
+    const type = resolveSchemaType(node);
+    out.type = type;
+    if (Array.isArray(node.enum)) {
+        out.enum = node.enum;
+    }
+    if (type === "object") {
+        sanitizeObjectMembers(node, out);
+    }
+    if (type === "array") {
+        out.items = sanitizeSchema(node.items);
+    }
+    return out;
+}
+/** Tool parameters must be an object schema; force it and sanitize the tree. */
+export function sanitizeToolParameters(schema) {
+    const sanitized = sanitizeSchema(schema ?? {});
+    if (sanitized.type !== "object") {
+        return { type: "object", properties: {}, additionalProperties: true };
+    }
+    return sanitized;
+}
+/**
+ * Walk a (sanitized) schema and return the first node the google plugin would
+ * turn into `undefined` — which genai then crashes on. Returns a human-readable
+ * path/reason, or `null` if the schema is safe. After `sanitizeSchema` this
+ * should always be `null`; if not, it names the exact offending path.
+ */
+export function findSchemaIssue(node, pathPrefix = "$") {
+    if (!isRecord(node)) {
+        return `${pathPrefix}: not an object schema`;
+    }
+    if (typeof node.type !== "string") {
+        return `${pathPrefix}: missing string "type"`;
+    }
+    if (node.type === "object") {
+        const properties = isRecord(node.properties) ? node.properties : undefined;
+        const isEmpty = properties === undefined || Object.keys(properties).length === 0;
+        if (isEmpty &&
+            (node.additionalProperties === undefined ||
+                node.additionalProperties === null)) {
+            return `${pathPrefix}: empty object schema without additionalProperties (plugin → undefined)`;
+        }
+        if (properties !== undefined) {
+            for (const [key, value] of Object.entries(properties)) {
+                const childIssue = findSchemaIssue(value, `${pathPrefix}.${key}`);
+                if (childIssue) {
+                    return childIssue;
+                }
+            }
+        }
+    }
+    if (node.type === "array") {
+        return findSchemaIssue(node.items, `${pathPrefix}[]`);
+    }
+    return null;
+}
+//# sourceMappingURL=schemaSanitizer.js.map