@juspay/neurolink 12.49.20 → 12.51.0

package/dist/utils/conversationTurnIdentity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Message identity and metadata for a stored conversation turn.
+ *
+ * Both memory managers store a turn as a user message followed by an assistant
+ * message. When the caller supplies a `turnId` the two messages get stable ids
+ * (`${turnId}:user`, `${turnId}:assistant`), which lets a repeated store of the
+ * same turn be recognised and skipped. When the caller sets neither a
+ * `turnId` nor a `modality`, nothing here changes what is stored: ids stay
+ * random and no metadata is added, so typed chat is byte-for-byte as before.
+ */
+import type { ChatMessage, ChatMessageMetadata, StoreConversationTurnOptions, TurnMessageIdentity } from "../types/index.js";
+export declare function userTurnMessageId(turnId: string): string;
+export declare function assistantTurnMessageId(turnId: string): string;
+/** Identity and metadata for the user message of a turn. */
+export declare function userTurnIdentity(options: Pick<StoreConversationTurnOptions, "turnId" | "modality">): TurnMessageIdentity;
+/** Identity and metadata for the assistant message of a turn. */
+export declare function assistantTurnIdentity(options: Pick<StoreConversationTurnOptions, "turnId" | "modality" | "interrupted" | "callEnded">, thoughtSignature?: string): TurnMessageIdentity;
+/** `id` and optional `metadata` of a stored message, ready to spread into it. */
+export declare function turnMessageFields(identity: TurnMessageIdentity): {
+    id: string;
+    metadata?: ChatMessageMetadata;
+};
+/** True when a turn with this id is already among the session's recent messages. */
+export declare function isTurnAlreadyStored(messages: ReadonlyArray<Pick<ChatMessage, "id">>, turnId: string | undefined): boolean;

package/dist/utils/conversationTurnIdentity.js

@@ -0,0 +1,81 @@
+/**
+ * Message identity and metadata for a stored conversation turn.
+ *
+ * Both memory managers store a turn as a user message followed by an assistant
+ * message. When the caller supplies a `turnId` the two messages get stable ids
+ * (`${turnId}:user`, `${turnId}:assistant`), which lets a repeated store of the
+ * same turn be recognised and skipped. When the caller sets neither a
+ * `turnId` nor a `modality`, nothing here changes what is stored: ids stay
+ * random and no metadata is added, so typed chat is byte-for-byte as before.
+ */
+import { randomUUID } from "node:crypto";
+import { logger } from "./logger.js";
+/** How far back a repeated `turnId` is looked for. A turn is always the newest thing in a session. */
+const DUPLICATE_LOOKBACK_MESSAGES = 200;
+export function userTurnMessageId(turnId) {
+    return `${turnId}:user`;
+}
+export function assistantTurnMessageId(turnId) {
+    return `${turnId}:assistant`;
+}
+/** Identity and metadata for the user message of a turn. */
+export function userTurnIdentity(options) {
+    const metadata = {};
+    if (options.modality) {
+        metadata.modality = options.modality;
+    }
+    if (options.turnId) {
+        metadata.turnId = options.turnId;
+    }
+    return {
+        id: options.turnId ? userTurnMessageId(options.turnId) : undefined,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    };
+}
+/** Identity and metadata for the assistant message of a turn. */
+export function assistantTurnIdentity(options, thoughtSignature) {
+    const metadata = {};
+    if (thoughtSignature) {
+        metadata.thoughtSignature = thoughtSignature;
+    }
+    if (options.modality) {
+        metadata.modality = options.modality;
+    }
+    if (options.turnId) {
+        metadata.turnId = options.turnId;
+    }
+    if (options.interrupted) {
+        metadata.interrupted = true;
+    }
+    if (options.callEnded) {
+        metadata.callEnded = true;
+    }
+    return {
+        id: options.turnId ? assistantTurnMessageId(options.turnId) : undefined,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    };
+}
+/** `id` and optional `metadata` of a stored message, ready to spread into it. */
+export function turnMessageFields(identity) {
+    return {
+        id: identity.id ?? randomUUID(),
+        ...(identity.metadata ? { metadata: identity.metadata } : {}),
+    };
+}
+/** True when a turn with this id is already among the session's recent messages. */
+export function isTurnAlreadyStored(messages, turnId) {
+    if (!turnId) {
+        return false;
+    }
+    const assistantId = assistantTurnMessageId(turnId);
+    const start = Math.max(0, messages.length - DUPLICATE_LOOKBACK_MESSAGES);
+    for (let index = messages.length - 1; index >= start; index -= 1) {
+        if (messages[index].id === assistantId) {
+            logger.debug("[conversationTurnIdentity] Turn already stored, skipping", {
+                turnId,
+            });
+            return true;
+        }
+    }
+    return false;
+}

package/dist/utils/modelChoices.js

@@ -2,16 +2,19 @@
  * Centralized model choices for CLI commands
  * Derives choices from model enums to ensure consistency
  */
-import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, SageMakerModels, OpenRouterModels, NvidiaNimModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, LayaModels, XorModels, PerplexityDeciderModels, CloudflareClefModels, ReplicateModels, } from "../constants/enums.js";
-import { getCatalogJsonEntries } from "../providers/catalog/loader.js";
+import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, SageMakerModels, OpenRouterModels, NvidiaNimModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, XorModels, PerplexityDeciderModels, CloudflareClefModels, ReplicateModels, } from "../constants/enums.js";
+import { getCatalogJsonEntries, getDecideCatalogEntries, } from "../providers/catalog/loader.js";
 /**
  * Looks up the JSON catalog entry for a provider, if it is one of the 11
  * JSON-catalog providers. Used to short-circuit the hand tables below so a
  * catalog provider's models are always sourced from its catalog JSON, never
- * from stale hand-written duplicates.
+ * from stale hand-written duplicates. A decide provider's entry is searched
+ * after the chat catalog (the two never share an id), so its models need no
+ * hand-written rows either.
  */
 function catalogEntryFor(provider) {
-    return getCatalogJsonEntries().find((entry) => entry.id === provider);
+    return (getCatalogJsonEntries().find((entry) => entry.id === provider) ??
+        getDecideCatalogEntries().find((entry) => entry.id === provider));
 }
 /**
  * Derives CLI-prompt entries for a catalog provider. Uses the curated
@@ -374,24 +377,6 @@ const TOP_MODELS_CONFIG = {
             description: "Preview build of Jev",
         },
     ],
-    [AIProviderName.LAYA]: [
-        {
-            model: LayaModels.TYPED_DECISIONS,
-            description: "Recommended - Laya fine-tuned for typed decisions",
-        },
-        {
-            model: LayaModels.MULTILINGUAL,
-            description: "Laya, 100+ languages",
-        },
-        {
-            model: LayaModels.ENGLISH,
-            description: "Laya, English base checkpoint (512-token window)",
-        },
-        {
-            model: LayaModels.AUTO,
-            description: "Let Laya pick a checkpoint by language",
-        },
-    ],
     [AIProviderName.XOR]: [
         {
             model: XorModels.XOR_1_1,
@@ -460,7 +445,6 @@ export const DEFAULT_MODELS = {
     [AIProviderName.IDEOGRAM]: IdeogramModels.IDEOGRAM_V3,
     [AIProviderName.RECRAFT]: RecraftModels.RECRAFT_V3,
     [AIProviderName.TYPESAFE]: TypeSafeModels.JEV_LATEST,
-    [AIProviderName.LAYA]: LayaModels.TYPED_DECISIONS,
     [AIProviderName.XOR]: XorModels.XOR_1_1,
     [AIProviderName.PERPLEXITY_DECIDER]: PerplexityDeciderModels.PPLX_DECIDER_V1_27B,
     [AIProviderName.CLOUDFLARE_CLEF]: CloudflareClefModels.CLEF,
@@ -496,7 +480,6 @@ const MODEL_ENUMS = {
     [AIProviderName.IDEOGRAM]: IdeogramModels,
     [AIProviderName.RECRAFT]: RecraftModels,
     [AIProviderName.TYPESAFE]: TypeSafeModels,
-    [AIProviderName.LAYA]: LayaModels,
     [AIProviderName.XOR]: XorModels,
     [AIProviderName.PERPLEXITY_DECIDER]: PerplexityDeciderModels,
     [AIProviderName.CLOUDFLARE_CLEF]: CloudflareClefModels,
@@ -695,7 +678,10 @@ export function getPopularModelsAcrossProviders() {
     }
     // JSON-catalog providers are excluded from TOP_MODELS_CONFIG above; merge
     // their models in here, derived the same way getTopModelChoices() does.
-    for (const entry of getCatalogJsonEntries()) {
+    for (const entry of [
+        ...getCatalogJsonEntries(),
+        ...getDecideCatalogEntries(),
+    ]) {
         pushTop2(entry.id, catalogTopModels(entry));
     }
     return popularModels;

package/dist/utils/providerConfig.d.ts

@@ -400,11 +400,6 @@ export declare function resolveOpenAICompatConfig(entry: OpenAICompatConfigInput
  * TypeSafe (Jev) — the `decide` inference type. Not a text provider.
  */
 export declare function createTypeSafeConfig(): ProviderConfigOptions;
-/**
- * Laya — the `decide` inference type. Not a text provider, and it has no
- * built-in endpoint: LAYA_BASE_URL is required alongside the key.
- */
-export declare function createLayaConfig(): ProviderConfigOptions;
 /**
  * XOR — the `decide` inference type. Not a text provider, and it has no
  * built-in endpoint: XOR_BASE_URL is required alongside the key.

package/dist/utils/providerConfig.js

@@ -1324,23 +1324,6 @@ export function createTypeSafeConfig() {
         ],
     };
 }
-/**
- * Laya — the `decide` inference type. Not a text provider, and it has no
- * built-in endpoint: LAYA_BASE_URL is required alongside the key.
- */
-export function createLayaConfig() {
-    return {
-        providerName: "Laya",
-        envVarName: "LAYA_API_KEY",
-        setupUrl: "https://github.com/NandhaKishorM/laya",
-        description: "API key for your Laya endpoint",
-        instructions: [
-            "1. Run a Laya server, or use a LiteLLM proxy with a pass-through route to one",
-            "2. Set LAYA_BASE_URL to its base URL (NeuroLink calls <LAYA_BASE_URL>/predict)",
-            "3. Set LAYA_API_KEY to the key it accepts (on LiteLLM, a virtual key with that route in its Allowed Routes)",
-        ],
-    };
-}
 /**
  * XOR — the `decide` inference type. Not a text provider, and it has no
  * built-in endpoint: XOR_BASE_URL is required alongside the key.

package/dist/voice/livekit/brain.js

@@ -37,16 +37,17 @@ function extractTextDelta(chunk) {
 export function createVoiceBrain(config) {
     const { neurolink, provider, model, systemPrompt, temperature, maxTokens, userId, } = config;
     async function* streamReply(turn) {
-        const { transcript, conversationId, signal } = turn;
+        const { transcript, conversationId, signal, ephemeral } = turn;
         if (signal?.aborted) {
             return;
         }
-        const context = {
-            sessionId: conversationId,
-            conversationId,
-        };
-        if (userId !== undefined) {
-            context.userId = userId;
+        // No sessionId means no history read and no turn stored for this call.
+        const context = ephemeral
+            ? {}
+            : { sessionId: conversationId, conversationId };
+        const turnUserId = turn.userId ?? userId;
+        if (!ephemeral && turnUserId !== undefined) {
+            context.userId = turnUserId;
         }
         const result = await neurolink.stream({
             input: { text: transcript },
@@ -56,6 +57,8 @@ export function createVoiceBrain(config) {
             temperature,
             maxTokens,
             context,
+            // Every turn through this brain is spoken; stored messages are marked so.
+            modality: "voice",
             abortSignal: signal,
             disableTools: false,
         });

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

@@ -18,5 +18,7 @@ export { defineRealtimeVoiceAgent } from "./realtimeVoiceAgent.js";
 export { startVoiceAgentWorker, startRealtimeVoiceAgentWorker, installVoiceWorkerProcessGuards, } from "./voiceAgentWorker.js";
 export { ensureVertexAdc, clearGeminiApiKeyEnv } from "./vertexAuth.js";
 export { readCallContextFromRoom } from "./roomContext.js";
+export { signVoiceMemoryBinding, verifyVoiceMemoryBinding, isValidVoiceSessionId, isValidVoiceUserId, VOICE_MEMORY_SECRET_ENV, VOICE_MEMORY_BINDING_VERSION, VOICE_MEMORY_MAX_TTL_SECONDS, } from "./memoryBinding.js";
+export { createVoiceTurnRecorder } from "./turnRecorder.js";
 export { sanitizeSchema, sanitizeToolParameters, findSchemaIssue, } from "./schemaSanitizer.js";
 export { buildRealtimeMcpTools, mcpResultToText } from "./realtimeMcpTools.js";

package/dist/voice/livekit/index.js

@@ -18,5 +18,7 @@ export { defineRealtimeVoiceAgent } from "./realtimeVoiceAgent.js";
 export { startVoiceAgentWorker, startRealtimeVoiceAgentWorker, installVoiceWorkerProcessGuards, } from "./voiceAgentWorker.js";
 export { ensureVertexAdc, clearGeminiApiKeyEnv } from "./vertexAuth.js";
 export { readCallContextFromRoom } from "./roomContext.js";
+export { signVoiceMemoryBinding, verifyVoiceMemoryBinding, isValidVoiceSessionId, isValidVoiceUserId, VOICE_MEMORY_SECRET_ENV, VOICE_MEMORY_BINDING_VERSION, VOICE_MEMORY_MAX_TTL_SECONDS, } from "./memoryBinding.js";
+export { createVoiceTurnRecorder } from "./turnRecorder.js";
 export { sanitizeSchema, sanitizeToolParameters, findSchemaIssue, } from "./schemaSanitizer.js";
 export { buildRealtimeMcpTools, mcpResultToText } from "./realtimeMcpTools.js";

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

@@ -0,0 +1,47 @@
+/**
+ * Signed memory binding for a voice call.
+ *
+ * A voice worker persists a call's turns to a conversation, so it has to know
+ * WHOSE conversation and WHICH one — and it must not take either from anything
+ * a participant can influence. The manager that creates the room (for example
+ * a `/start` endpoint) already holds the verified session, so it signs a small
+ * binding and writes it into the room metadata next to `authToken` and
+ * `mcpContext`:
+ *
+ *   base64(JSON({ authToken, mcpContext, memory: { userId, sessionId, exp, sig } }))
+ *
+ * The worker verifies the signature with the same shared secret. The signature
+ * covers the room name, so a binding copied into another room does not verify.
+ * Room metadata is readable by participants, so this does not hide the ids; it
+ * stops anyone without the secret from choosing them.
+ *
+ * Everything here fails closed. A missing secret, a missing or malformed
+ * binding, a bad signature or an expired binding all yield `{ ok: false }`, and
+ * the caller carries on with the call, storing nothing.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { VoiceMemoryBinding, VoiceMemoryBindingInput, VoiceMemoryBindingVerdict, VoiceMemoryBindingVerifyInput } from "../../types/index.js";
+/** Domain-separation label that starts every signed message. */
+export declare const VOICE_MEMORY_BINDING_VERSION = "neurolink.voice.memory.v1";
+/** Environment variable the worker reads the shared secret from when none is passed in. */
+export declare const VOICE_MEMORY_SECRET_ENV = "NEUROLINK_VOICE_MEMORY_SECRET";
+/** Longest expiry, counted from now, that a worker accepts (24 hours). */
+export declare const VOICE_MEMORY_MAX_TTL_SECONDS: number;
+/** A conversation id a voice call may append to: letters, digits, "_" and "-", up to 128, no ":". */
+export declare function isValidVoiceSessionId(value: unknown): value is string;
+/** A user id a voice call may be bound to: 1 to 256 characters, no whitespace or control characters. */
+export declare function isValidVoiceUserId(value: unknown): value is string;
+/**
+ * Sign a binding for a room. Throws on an unusable secret or invalid ids: the
+ * signer is the trusted side, and a binding it cannot sign correctly is a bug
+ * to surface there, not something to paper over.
+ */
+export declare function signVoiceMemoryBinding(input: VoiceMemoryBindingInput): VoiceMemoryBinding;
+/**
+ * Read and verify the memory binding in a room's metadata.
+ *
+ * Never throws and never logs ids. `reason` says why a binding was rejected so
+ * the caller can log it.
+ */
+export declare function verifyVoiceMemoryBinding(input: VoiceMemoryBindingVerifyInput): VoiceMemoryBindingVerdict;

package/dist/voice/livekit/memoryBinding.js

@@ -0,0 +1,152 @@
+/**
+ * Signed memory binding for a voice call.
+ *
+ * A voice worker persists a call's turns to a conversation, so it has to know
+ * WHOSE conversation and WHICH one — and it must not take either from anything
+ * a participant can influence. The manager that creates the room (for example
+ * a `/start` endpoint) already holds the verified session, so it signs a small
+ * binding and writes it into the room metadata next to `authToken` and
+ * `mcpContext`:
+ *
+ *   base64(JSON({ authToken, mcpContext, memory: { userId, sessionId, exp, sig } }))
+ *
+ * The worker verifies the signature with the same shared secret. The signature
+ * covers the room name, so a binding copied into another room does not verify.
+ * Room metadata is readable by participants, so this does not hide the ids; it
+ * stops anyone without the secret from choosing them.
+ *
+ * Everything here fails closed. A missing secret, a missing or malformed
+ * binding, a bad signature or an expired binding all yield `{ ok: false }`, and
+ * the caller carries on with the call, storing nothing.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Buffer } from "node:buffer";
+import { z } from "zod";
+/** Domain-separation label that starts every signed message. */
+export const VOICE_MEMORY_BINDING_VERSION = "neurolink.voice.memory.v1";
+/** Environment variable the worker reads the shared secret from when none is passed in. */
+export const VOICE_MEMORY_SECRET_ENV = "NEUROLINK_VOICE_MEMORY_SECRET";
+/** Longest expiry, counted from now, that a worker accepts (24 hours). */
+export const VOICE_MEMORY_MAX_TTL_SECONDS = 24 * 60 * 60;
+/** A secret shorter than this is treated as absent. */
+const MIN_SECRET_LENGTH = 16;
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+// Whitespace and control characters are refused; ":" is allowed because the
+// chat user id is itself composed with it (customer:merchant:shop).
+// eslint-disable-next-line no-control-regex
+const USER_ID_PATTERN = /^[^\s\u0000-\u001f\u007f]{1,256}$/u;
+/** A conversation id a voice call may append to: letters, digits, "_" and "-", up to 128, no ":". */
+export function isValidVoiceSessionId(value) {
+    return typeof value === "string" && SESSION_ID_PATTERN.test(value);
+}
+/** A user id a voice call may be bound to: 1 to 256 characters, no whitespace or control characters. */
+export function isValidVoiceUserId(value) {
+    return typeof value === "string" && USER_ID_PATTERN.test(value);
+}
+function usableSecret(secret) {
+    return typeof secret === "string" && secret.length >= MIN_SECRET_LENGTH;
+}
+/**
+ * What is signed. A JSON array, not a delimiter-joined string, so no choice of
+ * field values can make two different bindings produce the same message.
+ */
+function signedMessage(room, userId, sessionId, exp) {
+    return JSON.stringify([
+        VOICE_MEMORY_BINDING_VERSION,
+        room,
+        userId,
+        sessionId,
+        exp,
+    ]);
+}
+function signature(secret, message) {
+    return createHmac("sha256", secret).update(message).digest();
+}
+/**
+ * Sign a binding for a room. Throws on an unusable secret or invalid ids: the
+ * signer is the trusted side, and a binding it cannot sign correctly is a bug
+ * to surface there, not something to paper over.
+ */
+export function signVoiceMemoryBinding(input) {
+    const { room, userId, sessionId, secret } = input;
+    if (!room) {
+        throw new Error("A voice memory binding needs the room name");
+    }
+    if (!usableSecret(secret)) {
+        throw new Error(`The voice memory secret must be at least ${MIN_SECRET_LENGTH} characters`);
+    }
+    if (!isValidVoiceUserId(userId)) {
+        throw new Error("Invalid voice memory userId");
+    }
+    if (!isValidVoiceSessionId(sessionId)) {
+        throw new Error("Invalid voice memory sessionId");
+    }
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const ttl = input.ttlSeconds ?? 2 * 60 * 60;
+    if (!Number.isInteger(ttl) ||
+        ttl <= 0 ||
+        ttl > VOICE_MEMORY_MAX_TTL_SECONDS) {
+        throw new Error(`ttlSeconds must be a whole number between 1 and ${VOICE_MEMORY_MAX_TTL_SECONDS}`);
+    }
+    const exp = now + ttl;
+    const sig = signature(secret, signedMessage(room, userId, sessionId, exp)).toString("base64url");
+    return { userId, sessionId, exp, sig };
+}
+const bindingSchema = z.object({
+    userId: z.string(),
+    sessionId: z.string(),
+    exp: z.number().int(),
+    sig: z.string(),
+});
+const roomMetadataSchema = z.object({ memory: z.unknown().optional() });
+function decodeMetadata(encoded) {
+    try {
+        return JSON.parse(Buffer.from(encoded, "base64").toString("utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read and verify the memory binding in a room's metadata.
+ *
+ * Never throws and never logs ids. `reason` says why a binding was rejected so
+ * the caller can log it.
+ */
+export function verifyVoiceMemoryBinding(input) {
+    const { roomMetadata, roomName, secret } = input;
+    if (!usableSecret(secret)) {
+        return { ok: false, reason: "no-secret" };
+    }
+    if (!roomName || !roomMetadata) {
+        return { ok: false, reason: "no-binding" };
+    }
+    const metadata = roomMetadataSchema.safeParse(decodeMetadata(roomMetadata));
+    if (!metadata.success || metadata.data.memory === undefined) {
+        return { ok: false, reason: "no-binding" };
+    }
+    const parsed = bindingSchema.safeParse(metadata.data.memory);
+    if (!parsed.success) {
+        return { ok: false, reason: "malformed" };
+    }
+    const { userId, sessionId, exp, sig } = parsed.data;
+    if (!isValidVoiceUserId(userId) || !isValidVoiceSessionId(sessionId)) {
+        return { ok: false, reason: "malformed" };
+    }
+    const expected = signature(secret, signedMessage(roomName, userId, sessionId, exp));
+    const presented = Buffer.from(sig, "base64url");
+    if (presented.length !== expected.length ||
+        !timingSafeEqual(presented, expected)) {
+        return { ok: false, reason: "bad-signature" };
+    }
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    if (exp <= now) {
+        return { ok: false, reason: "expired" };
+    }
+    if (exp - now > VOICE_MEMORY_MAX_TTL_SECONDS) {
+        return { ok: false, reason: "expiry-too-far" };
+    }
+    return { ok: true, userId, sessionId, exp };
+}

package/dist/voice/livekit/realtimeMcpTools.js

@@ -94,7 +94,18 @@ function registerToolAliases(toolContext, mcpToolName, handler) {
  * filtering is needed.
  */
 export async function buildRealtimeMcpTools(params) {
-    const { mcpUrl, authToken, xContext, publishEvent, requestConfirmation, toolTimeoutMs = DEFAULT_TOOL_TIMEOUT_MS, } = params;
+    const { mcpUrl, authToken, xContext, publishEvent, requestConfirmation, toolTimeoutMs = DEFAULT_TOOL_TIMEOUT_MS, onToolStart, onToolEnd, } = params;
+    // Observers feed the turn recorder; a fault in one must never reach the tool.
+    const observe = (notify) => {
+        try {
+            notify();
+        }
+        catch (error) {
+            logger.warn("realtime.tool.observerFailed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
     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");
@@ -147,6 +158,7 @@ export async function buildRealtimeMcpTools(params) {
                         args: args ?? {},
                     });
                     publishEvent("tool-start", { name: mcpTool.name });
+                    observe(() => onToolStart?.({ name: mcpTool.name, args: args ?? {} }));
                     const startedAt = Date.now();
                     try {
                         // Third argument is RequestOptions; the SDK aborts the in-flight
@@ -167,6 +179,12 @@ export async function buildRealtimeMcpTools(params) {
                         // 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 });
+                        observe(() => onToolEnd?.({
+                            name: mcpTool.name,
+                            ...(result.isError === true
+                                ? { error: text }
+                                : { result: text }),
+                        }));
                         return text;
                     }
                     catch (error) {
@@ -176,6 +194,7 @@ export async function buildRealtimeMcpTools(params) {
                             error: error instanceof Error ? error.message : String(error),
                         });
                         publishEvent("tool-result", { name: mcpTool.name, result: null });
+                        observe(() => onToolEnd?.({ name: mcpTool.name, error: String(error) }));
                         return `Tool ${mcpTool.name} failed: ${String(error)}`;
                     }
                 },

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

@@ -0,0 +1,22 @@
+/**
+ * Per-call memory for the realtime (speech-to-speech) voice agent.
+ *
+ * Decides, once per call and before anything else is wired, whether this call
+ * may be remembered: the room metadata must carry a memory binding that
+ * verifies against the shared secret and the actual room name. If it does, a
+ * NeuroLink instance is built, the conversation's recent history is read for
+ * seeding, and a turn recorder is created that writes each finished exchange
+ * through `recordConversationTurn`. If it does not, the call proceeds exactly
+ * as it would without memory, and a warning says why (never the ids).
+ *
+ * The shutdown flush is registered here, before the job lifecycle installs its
+ * process reaper. LiveKit starts every shutdown callback in registration order
+ * and the reaper exits the process about a second later, so the flush gets a
+ * budget below that second and starts first.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { JobContext } from "@livekit/agents";
+import type { RealtimeCallMemory, RealtimeVoiceMemoryConfig } from "../../types/index.js";
+/** Verify the call's binding and prepare its recorder; `undefined` means "no memory for this call". */
+export declare function setUpRealtimeCallMemory(ctx: Pick<JobContext, "room" | "addShutdownCallback">, config: RealtimeVoiceMemoryConfig | undefined): Promise<RealtimeCallMemory | undefined>;

package/dist/voice/livekit/realtimeMemory.js

@@ -0,0 +1,111 @@
+/**
+ * Per-call memory for the realtime (speech-to-speech) voice agent.
+ *
+ * Decides, once per call and before anything else is wired, whether this call
+ * may be remembered: the room metadata must carry a memory binding that
+ * verifies against the shared secret and the actual room name. If it does, a
+ * NeuroLink instance is built, the conversation's recent history is read for
+ * seeding, and a turn recorder is created that writes each finished exchange
+ * through `recordConversationTurn`. If it does not, the call proceeds exactly
+ * as it would without memory, and a warning says why (never the ids).
+ *
+ * The shutdown flush is registered here, before the job lifecycle installs its
+ * process reaper. LiveKit starts every shutdown callback in registration order
+ * and the reaper exits the process about a second later, so the flush gets a
+ * budget below that second and starts first.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import { logger } from "../../utils/logger.js";
+import { VOICE_MEMORY_SECRET_ENV, verifyVoiceMemoryBinding, } from "./memoryBinding.js";
+import { createVoiceTurnRecorder } from "./turnRecorder.js";
+const DEFAULT_FLUSH_BUDGET_MS = 800;
+/** Verify the call's binding and prepare its recorder; `undefined` means "no memory for this call". */
+export async function setUpRealtimeCallMemory(ctx, config) {
+    if (!config) {
+        return undefined;
+    }
+    const verdict = verifyVoiceMemoryBinding({
+        roomMetadata: ctx.room.metadata,
+        roomName: ctx.room.name,
+        secret: config.secret ?? process.env[VOICE_MEMORY_SECRET_ENV],
+    });
+    if (!verdict.ok) {
+        logger.warn("realtime.memory.bindingRejected", {
+            reason: verdict.reason,
+            action: "continuing-without-memory",
+        });
+        return undefined;
+    }
+    const { userId, sessionId } = verdict;
+    let neurolink;
+    try {
+        neurolink = await config.createNeuroLink();
+    }
+    catch (error) {
+        logger.error("realtime.memory.setupFailed", {
+            error: error instanceof Error ? error.message : String(error),
+            action: "continuing-without-memory",
+        });
+        return undefined;
+    }
+    let publish;
+    const recorder = createVoiceTurnRecorder({
+        ...(config.settleMs !== undefined ? { settleMs: config.settleMs } : {}),
+        write: async (turn) => {
+            const result = await neurolink.recordConversationTurn({
+                sessionId,
+                userId,
+                userMessage: turn.userMessage,
+                aiResponse: turn.aiResponse,
+                modality: "voice",
+                turnId: turn.turnId,
+                interrupted: turn.interrupted,
+                callEnded: turn.callEnded,
+                startTime: turn.startTime,
+                ...(turn.events ? { events: turn.events } : {}),
+            });
+            if (!result.recorded) {
+                logger.debug("realtime.memory.turnSkipped", {
+                    reason: result.reason,
+                    turnId: turn.turnId,
+                });
+            }
+        },
+        onPermanentFailure: (turn) => {
+            publish?.("memory", { state: "not-saved", turnId: turn.turnId });
+        },
+    });
+    ctx.addShutdownCallback(async () => {
+        const stats = await recorder.flush(config.flushBudgetMs ?? DEFAULT_FLUSH_BUDGET_MS);
+        logger.info("realtime.memory.flushed", { ...stats });
+    });
+    let seed = [];
+    if (config.seed !== false && neurolink.getConversationSeed) {
+        try {
+            seed = await neurolink.getConversationSeed({
+                sessionId,
+                userId,
+                ...(config.seed?.maxTurns !== undefined
+                    ? { maxTurns: config.seed.maxTurns }
+                    : {}),
+                ...(config.seed?.maxChars !== undefined
+                    ? { maxChars: config.seed.maxChars }
+                    : {}),
+            });
+        }
+        catch (error) {
+            logger.warn("realtime.memory.seedFailed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    logger.info("realtime.memory.enabled", { seeded: seed.length });
+    return {
+        recorder,
+        seed,
+        setPublisher: (publisher) => {
+            publish = publisher;
+        },
+    };
+}