@juspay/neurolink 12.49.19 → 12.50.0

package/dist/types/generate.d.ts

@@ -584,6 +584,10 @@ export type GenerateOptions = {
      * compel a tool call on every step, and the loop would only end when
      * `maxSteps` ran out. `"auto"` and `"none"` are applied unchanged on every
      * step. Vertex, Google AI Studio and Bedrock do not honour `toolChoice`.
+     *
+     * A named tool that the request does not declare is not sent, because the
+     * provider would reject the request: a warning is logged and the step uses
+     * `"auto"`.
      */
     toolChoice?: ToolChoice<Record<string, Tool>>;
     /**
@@ -606,7 +610,9 @@ export type GenerateOptions = {
      * Optional callback that runs before each step in a multi-step generation.
      *
      * Honoured field of the result: `toolChoice`, applied to that step only
-     * and taking precedence over `toolChoice` / `toolChoiceSteps`.
+     * and taking precedence over `toolChoice` / `toolChoiceSteps`. A named tool
+     * the request does not declare is ignored with a warning, as if the hook had
+     * returned no `toolChoice`.
      *
      * Not honoured — accepted for source compatibility with the former Vercel
      * AI SDK `experimental_prepareStep` shape, but ignored by every native
@@ -1799,6 +1805,17 @@ export type StepToolChoiceInput = {
     model: string;
     /** The turn's abort signal; a pending `prepareStep` is released when it fires. */
     abortSignal?: AbortSignal;
+    /**
+     * The tools this request declares, keyed by SDK-side tool name. When given,
+     * a forced single-tool choice naming a tool outside it is not sent: a
+     * provider answers a request that forces a function its own tools list
+     * lacks with a 400. A loop that re-declares hydrated tools in the same
+     * step (the streaming loops) passes the live record, because discovery
+     * hydrates tools into it between steps; a loop that sends a fixed tools
+     * array (the shared generate loop) passes the names of that array.
+     * Absent means the choice is not checked.
+     */
+    declaredTools?: Readonly<Record<string, unknown>>;
 };
 /**
  * Inputs to the shared native generate loop (`core/nativeGenerateLoop.ts`).

package/dist/types/livekit.d.ts

@@ -11,6 +11,7 @@
  */
 import type { NeuroLinkEvents, TypedEventEmitter } from "./common.js";
 import type { StreamOptions, StreamResult } from "./stream.js";
+import type { ConversationSeedMessage, ConversationSeedOptions, RecordConversationTurnOptions, RecordConversationTurnResult, StreamEventSequence } from "./conversation.js";
 /**
  * Minimal structural shape of the NeuroLink instance the brain depends on.
  *
@@ -57,6 +58,18 @@ export type LiveKitBrainTurn = {
     conversationId: string;
     /** Cancellation signal; aborting stops the in-flight LLM and tool calls. */
     signal?: AbortSignal;
+    /**
+     * User the conversation belongs to for THIS call, overriding the brain's
+     * static `userId`. A call whose memory binding verified passes the bound
+     * user here so the turn is stored under the person on the call.
+     */
+    userId?: string;
+    /**
+     * Run this turn without reading or writing conversation memory. Used for the
+     * agent's opening greeting on a bound call, which is an instruction to the
+     * agent and must not land in the person's conversation as something they said.
+     */
+    ephemeral?: boolean;
 };
 /**
  * The brain's public surface: stream the assistant reply as text deltas.
@@ -155,6 +168,15 @@ export type LiveKitVoiceAgentConfig = {
     conversationIdPrefix?: string;
     /** Optional user id recorded alongside memory. */
     userId?: string;
+    /**
+     * Per-call memory identity. When set, the call's room metadata is checked
+     * for a signed memory binding (see `signVoiceMemoryBinding`); a binding that
+     * verifies replaces `userId` and the room-derived conversation id for that
+     * call, and the turns the brain streams are stamped as voice. A call whose
+     * binding is missing or does not verify runs with the static `userId` and
+     * the room-derived conversation id exactly as before.
+     */
+    memory?: LiveKitVoiceAgentMemoryConfig;
     greeting?: string;
     /** Silero VAD tuning (stricter = ignores background noise). */
     vad?: LiveKitVadConfig;
@@ -170,6 +192,11 @@ export type LiveKitVoiceAgentConfig = {
      */
     events?: LiveKitEventBridgeConfig;
 };
+/** Per-call memory identity for the cascaded voice agent. */
+export type LiveKitVoiceAgentMemoryConfig = {
+    /** Shared secret the binding is signed with. Defaults to `NEUROLINK_VOICE_MEMORY_SECRET`. */
+    secret?: string;
+};
 /** Options for `startVoiceAgentWorker` — launches the LiveKit Agents worker. */
 export type LiveKitWorkerLaunchOptions = {
     /**
@@ -208,7 +235,7 @@ export type LiveKitTokenRequest = {
     ttlSeconds?: number;
 };
 /** Discriminant tags for outbound voice events. */
-export type LiveKitVoiceEventType = "user-text" | "text" | "tool-start" | "tool-result" | "status" | "hitl-prompt" | "done";
+export type LiveKitVoiceEventType = "user-text" | "text" | "tool-start" | "tool-result" | "status" | "hitl-prompt" | "done" | "memory";
 /**
  * A user STT transcript for display. Interim partials stream with
  * `final: false`; the end-of-utterance result has `final: true`. The client
@@ -277,15 +304,32 @@ export type LiveKitVoiceHitlPromptEvent = {
         allowModification?: boolean;
     };
 };
-/** The current turn has finished. */
+/**
+ * The current turn has finished. `turnId` is set when the call's turns are
+ * being recorded: it is the id the stored messages carry (`${turnId}:user`,
+ * `${turnId}:assistant`), so a client can merge its live copy with history.
+ */
 export type LiveKitVoiceDoneEvent = {
     type: "done";
     data: {
         reason?: string;
+        turnId?: string;
+    };
+};
+/**
+ * Something about how the call is being remembered. `not-saved` means a turn
+ * could not be stored after retries; the call carries on, and a client may
+ * show a quiet note on that turn.
+ */
+export type LiveKitVoiceMemoryEvent = {
+    type: "memory";
+    data: {
+        state: "not-saved";
+        turnId: string;
     };
 };
 /** Discriminated union of all outbound voice events (before enveloping). */
-export type LiveKitVoiceEvent = LiveKitVoiceUserTextEvent | LiveKitVoiceTextEvent | LiveKitVoiceToolStartEvent | LiveKitVoiceToolResultEvent | LiveKitVoiceStatusEvent | LiveKitVoiceHitlPromptEvent | LiveKitVoiceDoneEvent;
+export type LiveKitVoiceEvent = LiveKitVoiceUserTextEvent | LiveKitVoiceTextEvent | LiveKitVoiceToolStartEvent | LiveKitVoiceToolResultEvent | LiveKitVoiceStatusEvent | LiveKitVoiceHitlPromptEvent | LiveKitVoiceDoneEvent | LiveKitVoiceMemoryEvent;
 /**
  * Wire format published to the browser: a `LiveKitVoiceEvent` plus a monotonic
  * sequence number and a timestamp so the client can order and de-duplicate.
@@ -442,6 +486,14 @@ export type RealtimeVoiceAgentConfig = {
         enabled?: boolean;
         mcpUrl?: string;
     };
+    /**
+     * Persist the call's turns to conversation memory and seed the model with
+     * the conversation's recent history. Off unless set. Takes effect only for
+     * a call whose room metadata carries a verified memory binding; otherwise
+     * the call runs exactly as it would without this option, and nothing is
+     * stored.
+     */
+    memory?: RealtimeVoiceMemoryConfig;
     /** Data-channel topic for outbound events (default "ai-events"). */
     eventsTopic?: string;
     /** Data-channel topic for inbound control messages (default "ai-control"). */
@@ -455,6 +507,186 @@ export type RealtimeVoiceAgentConfig = {
      */
     onLog?: (entry: RealtimeVoiceLogEntry, ctx: RealtimeVoiceLogContext) => void;
 };
+/**
+ * The part of a NeuroLink instance a voice agent needs to persist and seed a
+ * call's turns. The real `NeuroLink` instance satisfies it.
+ */
+export type LiveKitMemoryNeuroLink = {
+    recordConversationTurn: (options: RecordConversationTurnOptions) => Promise<RecordConversationTurnResult>;
+    getConversationSeed?: (options: ConversationSeedOptions) => Promise<ConversationSeedMessage[]>;
+};
+/** Memory options for `defineRealtimeVoiceAgent`. */
+export type RealtimeVoiceMemoryConfig = {
+    /**
+     * Builds the NeuroLink instance, with conversation memory configured the
+     * same way the web app's is (same store, key prefix and lifetime), inside
+     * the job process. Called once per call, only after a binding verified.
+     */
+    createNeuroLink: () => LiveKitMemoryNeuroLink | Promise<LiveKitMemoryNeuroLink>;
+    /** Shared secret the binding is signed with. Defaults to `NEUROLINK_VOICE_MEMORY_SECRET`. */
+    secret?: string;
+    /** How long a closed reply waits for its user transcript before being dropped (default 1500 ms). */
+    settleMs?: number;
+    /** How long shutdown waits for pending writes (default 800 ms; the worker is reaped about 1 s after shutdown starts). */
+    flushBudgetMs?: number;
+    /** History seeding at call start. `false` turns it off. Defaults: 10 exchanges, 6000 characters. */
+    seed?: false | {
+        maxTurns?: number;
+        maxChars?: number;
+    };
+};
+/** One finished exchange of a voice call, as handed to the writer. */
+export type VoiceTurnRecord = {
+    /** The assistant message id, or a synthetic id for a turn cut off by shutdown or barge-in. */
+    turnId: string;
+    userMessage: string;
+    aiResponse: string;
+    /** The reply was cut off. */
+    interrupted: boolean;
+    /** The call ended while this exchange was open. */
+    callEnded: boolean;
+    startTime: Date;
+    /** Tool events of the exchange, in the shape typed chat stores. */
+    events?: StreamEventSequence[];
+};
+/** A recorder's current exchange: what has been heard and said since the last reply closed. */
+export type VoiceTurnOpenExchange = {
+    userSegments: string[];
+    assistantPartial: string;
+    assistantStarted: boolean;
+    events: StreamEventSequence[];
+    startedAt: number;
+};
+/** A reply that finished before its user transcript arrived, waiting out the settle window. */
+export type VoiceTurnClosedExchange = {
+    turnId: string;
+    assistantText: string;
+    interrupted: boolean;
+    events: StreamEventSequence[];
+    startedAt: number;
+    timer: ReturnType<typeof setTimeout>;
+};
+/** The recorder returned by `createVoiceTurnRecorder`. */
+export type VoiceTurnRecorder = {
+    /** A final transcript segment of what the user said. Interim segments are ignored. */
+    userTranscript: (segment: {
+        text: string;
+        final: boolean;
+    }) => void;
+    /** A piece of the assistant's reply as it is produced. */
+    assistantDelta: (delta: string) => void;
+    /** The assistant's message was added: the reply is complete (or was cut off). */
+    assistantMessage: (message: {
+        id: string;
+        text: string;
+        interrupted?: boolean;
+    }) => void;
+    /**
+     * The next assistant-only reply is the agent's opening greeting, not an
+     * answer: it is skipped and never paired with the user's first question.
+     * Call it once, when the agent is about to speak its greeting.
+     */
+    expectGreeting: () => void;
+    /** A tool call started in the current exchange. */
+    toolStart: (call: {
+        name: string;
+        args?: unknown;
+    }) => void;
+    /** A tool call finished in the current exchange. */
+    toolEnd: (call: {
+        name: string;
+        result?: unknown;
+        error?: string;
+    }) => void;
+    /**
+     * Shutdown: close what is open, then wait for pending writes — but no longer
+     * than `budgetMs`. Safe to call more than once.
+     */
+    flush: (budgetMs: number) => Promise<VoiceTurnRecorderStats>;
+    /** Counters, for logs and tests. */
+    stats: () => VoiceTurnRecorderStats;
+};
+/** What a realtime call needs from its memory once its binding verified. */
+export type RealtimeCallMemory = {
+    recorder: VoiceTurnRecorder;
+    /** Recent history to seed the model with; empty when there is none or seeding is off. */
+    seed: ConversationSeedMessage[];
+    /** Late-bound publisher, set once the event bridge exists, for the not-saved notice. */
+    setPublisher: (publish: (type: LiveKitVoiceEventType, data: Record<string, unknown>) => void) => void;
+};
+/** Counters of a recorder, for logs and tests. */
+export type VoiceTurnRecorderStats = {
+    written: number;
+    failed: number;
+    dropped: number;
+    pending: number;
+};
+/** Options for `createVoiceTurnRecorder`. */
+export type VoiceTurnRecorderOptions = {
+    /** Stores one exchange. Throwing means "not stored"; the recorder retries. */
+    write: (record: VoiceTurnRecord) => Promise<void>;
+    /** A write succeeded. */
+    onRecorded?: (record: VoiceTurnRecord) => void;
+    /** A write failed after every retry. The call continues. */
+    onPermanentFailure?: (record: VoiceTurnRecord, error: unknown) => void;
+    /** How long a closed reply waits for its user transcript (default 1500 ms). */
+    settleMs?: number;
+    /** Retries after the first failed attempt (default 2). */
+    retries?: number;
+    /** Base delay between attempts; grows linearly (default 250 ms). */
+    retryDelayMs?: number;
+    /** Appended to a reply that was cut off by the call ending. */
+    callEndedNote?: string;
+    /** Stored as the reply when the call ended with the user's turn unanswered. */
+    noReplyNote?: string;
+    /** Prefix of synthetic turn ids (default: a random id). */
+    callId?: string;
+    /** Clock, for tests. */
+    now?: () => number;
+};
+/** A signed memory binding as it appears in room metadata under `memory`. */
+export type VoiceMemoryBinding = {
+    userId: string;
+    sessionId: string;
+    /** Expiry, Unix seconds. */
+    exp: number;
+    /** base64url(HMAC-SHA256) over the room name, userId, sessionId and exp. */
+    sig: string;
+};
+/** Input to `signVoiceMemoryBinding`. */
+export type VoiceMemoryBindingInput = {
+    /** The LiveKit room name the binding is for. */
+    room: string;
+    userId: string;
+    sessionId: string;
+    secret: string;
+    /** Lifetime in seconds (default 7200, at most 86400). */
+    ttlSeconds?: number;
+    /** Current time, Unix seconds (default: now). */
+    now?: number;
+};
+/** Input to `verifyVoiceMemoryBinding`. */
+export type VoiceMemoryBindingVerifyInput = {
+    /** The room's base64(JSON) metadata string. */
+    roomMetadata: string | undefined;
+    /** The room name as LiveKit reports it for the joined room. */
+    roomName: string | undefined;
+    secret: string | undefined;
+    /** Current time, Unix seconds (default: now). */
+    now?: number;
+};
+/** Why a binding was not accepted. */
+export type VoiceMemoryBindingRejection = "no-secret" | "no-binding" | "malformed" | "bad-signature" | "expired" | "expiry-too-far";
+/** Result of `verifyVoiceMemoryBinding`. */
+export type VoiceMemoryBindingVerdict = {
+    ok: true;
+    userId: string;
+    sessionId: string;
+    exp: number;
+} | {
+    ok: false;
+    reason: VoiceMemoryBindingRejection;
+};
 /** Auth token + base64 MCP execution context decoded from a room's metadata. */
 export type LiveKitRoomCallContext = {
     /** Lighthouse access JWT used as `x-auth-token` to the MCP server. */
@@ -509,4 +741,15 @@ export type BuildRealtimeMcpToolsParams = {
      * model can talk about.
      */
     toolTimeoutMs?: number;
+    /** Observes a tool call as it starts. A throwing observer never affects the call. */
+    onToolStart?: (call: {
+        name: string;
+        args: Record<string, unknown>;
+    }) => void;
+    /** Observes a tool call as it ends, with its result as text or its error. */
+    onToolEnd?: (call: {
+        name: string;
+        result?: string;
+        error?: string;
+    }) => void;
 };

package/dist/types/sdk.d.ts

@@ -12,7 +12,7 @@ export type { AnalyticsData, TokenUsage } from "./analytics.js";
 export type { BaseCommandArgs, CommandResult, GenerateCommandArgs, CliGenerateResult, MCPCommandArgs, ModelsCommandArgs, CliStreamChunk, } from "./cli.js";
 export type { ErrorInfo, FunctionParameters, JsonArray, JsonObject, JsonValue, ProcessResult, Result, TestFunction, TestResult, Unknown, UnknownArray, UnknownRecord, } from "./common.js";
 export type { Content, ImageContent, MultimodalMessage, ProcessedImage, ProviderImageFormat, ProviderMultimodalPayload, TextContent, VisionCapability, } from "./content.js";
-export type { ChatMessage, ChatMessageMetadata, ToolResultData, ConversationMemoryConfig, ConversationMemoryError, ConversationMemoryEvents, MessageContent, MultimodalChatMessage, RedisConversationObject, RedisStorageConfig, SessionIdentifier, SessionMemory, SessionMetadata, StoreConversationTurnOptions, } from "./conversation.js";
+export type { ChatMessage, ChatMessageMetadata, ToolResultData, ConversationMemoryConfig, ConversationMemoryError, ConversationMemoryEvents, ConversationModality, ConversationSeedMessage, ConversationSeedOptions, MessageContent, MultimodalChatMessage, RecordConversationTurnOptions, RecordConversationTurnResult, RedisConversationObject, RedisStorageConfig, SessionIdentifier, SessionMemory, SessionMetadata, StoreConversationTurnOptions, } from "./conversation.js";
 export type { DomainConfig, DomainConfigOptions, DomainEvaluationCriteria, DomainTemplate, DomainType, DomainValidationRule, } from "./domain.js";
 export type { EnhancedEvaluationResult, EvaluationContext, EvaluationCriteria, EvaluationData, EvaluationRequest, } from "./evaluation.js";
 export type { ExternalMCPConfigValidation, ExternalMCPManagerConfig, ExternalMCPOperationResult, ExternalMCPServerEvents, ExternalMCPServerHealth, ExternalMCPServerInstance, ExternalMCPServerStatus, ExternalMCPToolContext, ExternalMCPToolInfo, ExternalMCPToolResult, } from "./externalMcp.js";

package/dist/types/stream.d.ts

@@ -9,7 +9,7 @@ import type { TokenUsage } from "./analytics.js";
 import type { JsonValue, UnknownRecord } from "./common.js";
 import type { TerminalAgentModeOption, TerminalAgentModeVersion } from "./agentMode.js";
 import type { Content, ImageWithAltText } from "./content.js";
-import type { ChatMessage, ToolReplayMode } from "./conversation.js";
+import type { ChatMessage, ConversationModality, ToolReplayMode } from "./conversation.js";
 import type { StreamNoOutputSentinel } from "./noOutputSentinel.js";
 import type { GenerateStopReason, TTSMetadata, ToolExecutionCaptureOptions } from "./generate.js";
 import type { MemoryCallOptions } from "./memory.js";
@@ -666,6 +666,13 @@ export type StreamOptions = {
     workflow?: string;
     workflowConfig?: WorkflowConfig;
     enableSummarization?: boolean;
+    /**
+     * How this turn was entered. Stamped on the stored messages' metadata so
+     * history readers can tell a spoken turn from a typed one. Leave it unset
+     * for typed input: the stored turn is then identical to what it was before
+     * the field existed.
+     */
+    modality?: ConversationModality;
     /**
      * Maximum cumulative cost (USD) for this session.
      * Once the session spend reaches this limit, subsequent stream() calls

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/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;