@juspay/neurolink 9.69.3 → 9.70.0

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

@@ -0,0 +1,360 @@
+/**
+ * Data-channel event bridge.
+ *
+ * Connects NeuroLink's event emitter to the LiveKit room's data channel: it
+ * forwards NeuroLink events (text deltas, tool start/result, HITL prompts,
+ * stream lifecycle) to the browser as small versioned envelopes, and accepts
+ * control messages (HITL responses) back, re-emitting them onto the emitter so
+ * NeuroLink's HITL manager resolves.
+ *
+ * This is the WebRTC counterpart of the chat-mode SSE controller: same event
+ * source, different transport. The browser renders the envelopes (transcript,
+ * tool status, charts, confirmation prompts).
+ *
+ * `@livekit/rtc-node` is an optional dependency, imported dynamically only for
+ * the `RoomEvent` enum value. All payloads arrive typed as `unknown` and are
+ * narrowed with runtime guards — no type assertions.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+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;
+/** NeuroLink emitter event names this bridge forwards. */
+const USER_TEXT_EVENT = "voice:user-transcript";
+const TEXT_EVENT = "response:chunk";
+const TOOL_START_EVENT = "tool:start";
+const TOOL_END_EVENT = "tool:end";
+const HITL_REQUEST_EVENT = "hitl:confirmation-request";
+const STREAM_START_EVENT = "stream:start";
+const STREAM_COMPLETE_EVENT = "stream:complete";
+const STREAM_END_EVENT = "stream:end";
+const STREAM_ERROR_EVENT = "stream:error";
+/** Read a property off a non-null object as `unknown` without a type assertion. */
+function readProp(source, key) {
+    return Reflect.get(source, key);
+}
+/** Narrow an unknown value to a non-null object, or `undefined`. */
+function asObject(value) {
+    return typeof value === "object" && value !== null ? value : undefined;
+}
+/** Extract the text delta from a `response:chunk` payload. */
+function readTextDelta(payload) {
+    return typeof payload === "string" && payload.length > 0
+        ? payload
+        : undefined;
+}
+/** Extract tool fields from a `tool:start` / `tool:end` payload. */
+function readToolFields(payload) {
+    const obj = asObject(payload);
+    if (!obj) {
+        return undefined;
+    }
+    const toolName = readProp(obj, "toolName");
+    const tool = readProp(obj, "tool");
+    const name = typeof toolName === "string"
+        ? toolName
+        : typeof tool === "string"
+            ? tool
+            : undefined;
+    if (name === undefined) {
+        return undefined;
+    }
+    const fields = { name };
+    const executionId = readProp(obj, "executionId");
+    if (typeof executionId === "string") {
+        fields.id = executionId;
+    }
+    const input = readProp(obj, "input");
+    if (input !== undefined) {
+        fields.input = input;
+    }
+    const result = readProp(obj, "result");
+    if (result !== undefined) {
+        fields.result = result;
+    }
+    const success = readProp(obj, "success");
+    if (typeof success === "boolean") {
+        fields.success = success;
+    }
+    const error = readProp(obj, "error");
+    if (typeof error === "string") {
+        fields.error = error;
+    }
+    return fields;
+}
+/** Extract the HITL prompt fields from a `hitl:confirmation-request` payload. */
+function readHitlPrompt(payload) {
+    const event = asObject(payload);
+    if (!event) {
+        return undefined;
+    }
+    const inner = asObject(readProp(event, "payload"));
+    if (!inner) {
+        return undefined;
+    }
+    const confirmationId = readProp(inner, "confirmationId");
+    const toolName = readProp(inner, "toolName");
+    if (typeof confirmationId !== "string" || typeof toolName !== "string") {
+        return undefined;
+    }
+    const data = {
+        confirmationId,
+        toolName,
+    };
+    const actionType = readProp(inner, "actionType");
+    if (typeof actionType === "string") {
+        data.actionType = actionType;
+    }
+    const args = readProp(inner, "arguments");
+    if (args !== undefined) {
+        data.arguments = args;
+    }
+    const timeoutMs = readProp(inner, "timeoutMs");
+    if (typeof timeoutMs === "number") {
+        data.timeoutMs = timeoutMs;
+    }
+    const allowModification = readProp(inner, "allowModification");
+    if (typeof allowModification === "boolean") {
+        data.allowModification = allowModification;
+    }
+    return { type: "hitl-prompt", data };
+}
+/** Narrow a decoded inbound message to a control message, or `undefined`. */
+function readControlMessage(value) {
+    const obj = asObject(value);
+    if (!obj) {
+        return undefined;
+    }
+    const action = readProp(obj, "action");
+    const confirmationId = readProp(obj, "confirmationId");
+    if (typeof confirmationId !== "string") {
+        return undefined;
+    }
+    if (action === "hitl:accept") {
+        const message = {
+            action: "hitl:accept",
+            confirmationId,
+        };
+        const modifiedArguments = readProp(obj, "modifiedArguments");
+        if (modifiedArguments !== undefined) {
+            message.modifiedArguments = modifiedArguments;
+        }
+        return message;
+    }
+    if (action === "hitl:reject") {
+        const message = {
+            action: "hitl:reject",
+            confirmationId,
+        };
+        const reason = readProp(obj, "reason");
+        if (typeof reason === "string") {
+            message.reason = reason;
+        }
+        return message;
+    }
+    return undefined;
+}
+/**
+ * Attach the data-channel event bridge to a room.
+ *
+ * Returns a handle whose `dispose()` removes every listener and stops
+ * publishing; it is safe to call more than once.
+ */
+export async function attachEventBridge(params) {
+    const { room, emitter, options } = params;
+    const eventsTopic = options?.eventsTopic ?? DEFAULT_EVENTS_TOPIC;
+    const controlTopic = options?.controlTopic ?? DEFAULT_CONTROL_TOPIC;
+    const maxInlineBytes = options?.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+    const include = options?.include && options.include.length > 0
+        ? new Set(options.include)
+        : undefined;
+    const { RoomEvent } = await import("@livekit/rtc-node");
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    let seq = 0;
+    let disposed = false;
+    function publish(event) {
+        if (disposed) {
+            return;
+        }
+        if (include && !include.has(event.type)) {
+            return;
+        }
+        const localParticipant = room.localParticipant;
+        if (!localParticipant) {
+            return;
+        }
+        seq += 1;
+        const envelope = Object.assign({ seq, ts: Date.now() }, event);
+        const json = JSON.stringify(envelope);
+        const bytes = encoder.encode(json);
+        const onError = (transport) => (error) => {
+            logger.warn("[LiveKitEventBridge] Failed to publish event", {
+                transport,
+                type: event.type,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        };
+        if (bytes.byteLength <= maxInlineBytes) {
+            void localParticipant
+                .publishData(bytes, { reliable: true, topic: eventsTopic })
+                .catch(onError("publishData"));
+        }
+        else {
+            // Large payloads (e.g. chart data) exceed a single reliable data packet;
+            // the chunked text stream handles arbitrary sizes.
+            void localParticipant
+                .sendText(json, { topic: eventsTopic })
+                .catch(onError("sendText"));
+        }
+    }
+    // --- Outbound: NeuroLink emitter → data channel ---------------------------
+    const onUserText = (...args) => {
+        const payload = asObject(args[0]);
+        if (!payload) {
+            return;
+        }
+        const text = readProp(payload, "text");
+        const final = readProp(payload, "final");
+        const replacesPrevious = readProp(payload, "replacesPrevious");
+        if (typeof text === "string" && text.trim().length > 0) {
+            const data = {
+                text,
+                final: final === true,
+            };
+            if (replacesPrevious === true) {
+                data.replacesPrevious = true;
+            }
+            publish({ type: "user-text", data });
+        }
+    };
+    const onText = (...args) => {
+        const delta = readTextDelta(args[0]);
+        if (delta !== undefined) {
+            publish({ type: "text", data: { delta } });
+        }
+    };
+    const onToolStart = (...args) => {
+        const fields = readToolFields(args[0]);
+        if (fields) {
+            publish({
+                type: "tool-start",
+                data: { id: fields.id, name: fields.name, input: fields.input },
+            });
+        }
+    };
+    const onToolEnd = (...args) => {
+        const fields = readToolFields(args[0]);
+        if (fields) {
+            publish({
+                type: "tool-result",
+                data: {
+                    id: fields.id,
+                    name: fields.name,
+                    result: fields.result,
+                    success: fields.success,
+                    error: fields.error,
+                },
+            });
+        }
+    };
+    const onHitlRequest = (...args) => {
+        const event = readHitlPrompt(args[0]);
+        if (event) {
+            publish(event);
+        }
+    };
+    const onStreamStart = () => {
+        publish({ type: "status", data: { state: "thinking" } });
+    };
+    const onStreamComplete = () => {
+        publish({ type: "done", data: {} });
+    };
+    const onStreamError = (...args) => {
+        const obj = asObject(args[0]);
+        const message = obj ? readProp(obj, "message") : undefined;
+        publish({
+            type: "status",
+            data: {
+                state: "error",
+                detail: typeof message === "string" ? message : undefined,
+            },
+        });
+    };
+    emitter.on(USER_TEXT_EVENT, onUserText);
+    emitter.on(TEXT_EVENT, onText);
+    emitter.on(TOOL_START_EVENT, onToolStart);
+    emitter.on(TOOL_END_EVENT, onToolEnd);
+    emitter.on(HITL_REQUEST_EVENT, onHitlRequest);
+    emitter.on(STREAM_START_EVENT, onStreamStart);
+    emitter.on(STREAM_COMPLETE_EVENT, onStreamComplete);
+    emitter.on(STREAM_END_EVENT, onStreamComplete);
+    emitter.on(STREAM_ERROR_EVENT, onStreamError);
+    // --- Inbound: data channel → NeuroLink emitter (HITL responses) -----------
+    const onData = (...args) => {
+        const payload = args[0];
+        const topic = args[3];
+        if (topic !== controlTopic || !(payload instanceof Uint8Array)) {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(decoder.decode(payload));
+        }
+        catch (error) {
+            logger.warn("[LiveKitEventBridge] Dropping malformed control message", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        const message = readControlMessage(parsed);
+        if (!message) {
+            return;
+        }
+        const responsePayload = {
+            confirmationId: message.confirmationId,
+            approved: message.action === "hitl:accept",
+            metadata: { timestamp: new Date().toISOString(), responseTime: 0 },
+        };
+        if (message.action === "hitl:reject" && message.reason !== undefined) {
+            responsePayload.reason = message.reason;
+        }
+        if (message.action === "hitl:accept" &&
+            message.modifiedArguments !== undefined) {
+            responsePayload.modifiedArguments = message.modifiedArguments;
+        }
+        emitter.emit("hitl:confirmation-response", {
+            type: "hitl:confirmation-response",
+            payload: responsePayload,
+        });
+    };
+    room.on(RoomEvent.DataReceived, onData);
+    publish({ type: "status", data: { state: "listening" } });
+    logger.info("[LiveKitEventBridge] Attached", {
+        eventsTopic,
+        controlTopic,
+        filtered: include !== undefined,
+    });
+    return {
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            emitter.off(USER_TEXT_EVENT, onUserText);
+            emitter.off(TEXT_EVENT, onText);
+            emitter.off(TOOL_START_EVENT, onToolStart);
+            emitter.off(TOOL_END_EVENT, onToolEnd);
+            emitter.off(HITL_REQUEST_EVENT, onHitlRequest);
+            emitter.off(STREAM_START_EVENT, onStreamStart);
+            emitter.off(STREAM_COMPLETE_EVENT, onStreamComplete);
+            emitter.off(STREAM_END_EVENT, onStreamComplete);
+            emitter.off(STREAM_ERROR_EVENT, onStreamError);
+            room.off(RoomEvent.DataReceived, onData);
+            logger.info("[LiveKitEventBridge] Disposed");
+        },
+    };
+}
+//# sourceMappingURL=eventBridge.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Public entry point for the LiveKit voice agent integration.
+ *
+ * Exposed to consumers as `@juspay/neurolink/livekit`. Re-exports runtime
+ * values only; type definitions live in `src/lib/types/livekit.ts` and are
+ * available from the main type exports.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+export { createVoiceBrain } from "./brain.js";
+export { resolveLiveKitServerConfig, resolveBrainDefaults } from "./config.js";
+export { attachEventBridge } from "./eventBridge.js";
+export { mintJoinToken } from "./tokens.js";
+export { defineVoiceAgent } from "./voiceAgent.js";
+export { startVoiceAgentWorker } from "./voiceAgentWorker.js";

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

@@ -0,0 +1,16 @@
+/**
+ * Public entry point for the LiveKit voice agent integration.
+ *
+ * Exposed to consumers as `@juspay/neurolink/livekit`. Re-exports runtime
+ * values only; type definitions live in `src/lib/types/livekit.ts` and are
+ * available from the main type exports.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+export { createVoiceBrain } from "./brain.js";
+export { resolveLiveKitServerConfig, resolveBrainDefaults } from "./config.js";
+export { attachEventBridge } from "./eventBridge.js";
+export { mintJoinToken } from "./tokens.js";
+export { defineVoiceAgent } from "./voiceAgent.js";
+export { startVoiceAgentWorker } from "./voiceAgentWorker.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * LiveKit join-token minting.
+ *
+ * Mints a short-lived JWT a browser uses to join a room. The token is signed
+ * locally with the LiveKit API key/secret — no network call and no room
+ * pre-creation (rooms are auto-created on first join).
+ *
+ * `livekit-server-sdk` is an optional dependency and is imported dynamically so
+ * the core package does not require it unless the LiveKit voice agent is used.
+ *
+ */
+import type { LiveKitTokenRequest } from "../../types/index.js";
+/**
+ * Mint a LiveKit join token for an authenticated participant.
+ *
+ * Grants `roomJoin` plus publish/subscribe for the named room. The room is
+ * created automatically by LiveKit when the first participant joins.
+ */
+export declare function mintJoinToken(req: LiveKitTokenRequest): Promise<string>;

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

@@ -0,0 +1,51 @@
+/**
+ * LiveKit join-token minting.
+ *
+ * Mints a short-lived JWT a browser uses to join a room. The token is signed
+ * locally with the LiveKit API key/secret — no network call and no room
+ * pre-creation (rooms are auto-created on first join).
+ *
+ * `livekit-server-sdk` is an optional dependency and is imported dynamically so
+ * the core package does not require it unless the LiveKit voice agent is used.
+ *
+ */
+const DEFAULT_TTL_SECONDS = 600;
+/**
+ * Upper bound on join-token lifetime (1 hour). A join token only needs to live
+ * long enough for the participant to connect, so capping it keeps token-expiry
+ * controls meaningful even if a caller requests a very large `ttlSeconds`.
+ */
+const MAX_TTL_SECONDS = 3600;
+/**
+ * Resolve a safe token lifetime. Non-finite or non-positive requests fall back
+ * to the default; anything above the ceiling is clamped to `MAX_TTL_SECONDS`.
+ */
+function resolveTtlSeconds(ttlSeconds) {
+    if (ttlSeconds === undefined ||
+        !Number.isFinite(ttlSeconds) ||
+        ttlSeconds <= 0) {
+        return DEFAULT_TTL_SECONDS;
+    }
+    return Math.min(Math.floor(ttlSeconds), MAX_TTL_SECONDS);
+}
+/**
+ * Mint a LiveKit join token for an authenticated participant.
+ *
+ * Grants `roomJoin` plus publish/subscribe for the named room. The room is
+ * created automatically by LiveKit when the first participant joins.
+ */
+export async function mintJoinToken(req) {
+    const { AccessToken } = await import("livekit-server-sdk");
+    const token = new AccessToken(req.apiKey, req.apiSecret, {
+        identity: req.identity,
+        ttl: resolveTtlSeconds(req.ttlSeconds),
+    });
+    token.addGrant({
+        roomJoin: true,
+        room: req.room,
+        canPublish: true,
+        canSubscribe: true,
+    });
+    return token.toJwt();
+}
+//# sourceMappingURL=tokens.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * LiveKit Agents agent definition.
+ *
+ * `defineVoiceAgent` returns the agent object placed as the default export of a
+ * worker entry file. The framework runs it as a Job (one per call, in its own
+ * process): it connects to the room, builds the NeuroLink brain via the
+ * supplied factory, wires Silero VAD + STT/TTS plugins, and overrides `llmNode`
+ * so every turn is generated by `neurolink.stream()`.
+ *
+ * `@livekit/agents` and the plugins are optional dependencies, imported
+ * dynamically so the core package does not require them unless the LiveKit
+ * voice agent is used. Type-only imports are erased at build time and add no
+ * runtime dependency.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { Agent as JobAgent } from "@livekit/agents";
+import type { LiveKitVoiceAgentConfig } from "../../types/index.js";
+/**
+ * Define a LiveKit voice agent backed by NeuroLink.
+ *
+ * Place the result as the default export of the worker entry file:
+ *
+ * ```ts
+ * export default defineVoiceAgent({
+ *   createNeuroLink: async () => buildConfiguredNeuroLink(),
+ *   stt: { provider: "deepgram" },
+ *   tts: { provider: "elevenlabs" },
+ * });
+ * ```
+ */
+export declare function defineVoiceAgent(config: LiveKitVoiceAgentConfig): JobAgent;