@juspay/neurolink 13.8.17 → 13.8.19

package/dist/utils/ssrfGuard.js

@@ -26,6 +26,29 @@
  */
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
+import { redactUrlForError } from "./logSanitize.js";
+/**
+ * Parse `url` and enforce the scheme rule. HTTPS only unless the caller
+ * explicitly allowed `http:`; nothing else is ever a download URL.
+ */
+function parseGuardedUrl(url, options) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: "${url}"`);
+    }
+    if (parsed.protocol === "https:") {
+        return parsed;
+    }
+    if (parsed.protocol === "http:" && options?.allowInsecure === true) {
+        return parsed;
+    }
+    throw new Error(options?.allowInsecure === true
+        ? `Only HTTP(S) URLs are permitted; got "${parsed.protocol}//" in "${url}"`
+        : `Only HTTPS URLs are permitted; got "${parsed.protocol}//" in "${url}"`);
+}
 /**
  * Blocked IPv4 CIDRs.
  *
@@ -302,7 +325,7 @@ export async function assertSafeUrl(url) {
         return; // routable IP literal — safe
     }
     if (literalCheck !== "not-an-ip") {
-        throw new Error(`URL "${url}" rejected: ${literalCheck}`);
+        throw new Error(`URL "${redactUrlForError(url)}" rejected: ${literalCheck}`);
     }
     // Hostname — resolve BOTH A and AAAA. Reject if either family yields a
     // blocked address (closes off the "publish AAAA public, A private" attack).
@@ -316,7 +339,7 @@ export async function assertSafeUrl(url) {
  * @throws {Error} when resolution fails entirely or any address is blocked
  *   (all-must-pass — the caller may connect to any address in the set).
  */
-async function resolveAndValidateHost(url, host) {
+async function resolveAndValidateHost(url, host, allowPrivate = false) {
     const [a, aaaa] = await Promise.allSettled([
         lookup(host, { family: 4, all: true }),
         lookup(host, { family: 6, all: true }),
@@ -350,11 +373,28 @@ async function resolveAndValidateHost(url, host) {
                 ? aaaa.reason.message
                 : String(aaaa.reason)
             : "ok";
-        throw new Error(`URL "${url}" rejected: hostname ${host} could not be resolved (A: ${aErr}; AAAA: ${aaaaErr})`);
+        // Keep the resolver's own error on the chain (and its code, e.g.
+        // ENOTFOUND) so a caller's retry classification and cause-aware redaction
+        // see the real failure rather than this wrapper.
+        const resolverError = a.status === "rejected" && a.reason instanceof Error
+            ? a.reason
+            : aaaa.status === "rejected" && aaaa.reason instanceof Error
+                ? aaaa.reason
+                : undefined;
+        const unresolved = new Error(`URL "${redactUrlForError(url)}" rejected: hostname ${host} could not be resolved (A: ${aErr}; AAAA: ${aaaaErr})`, resolverError ? { cause: resolverError } : undefined);
+        const resolverCode = resolverError
+            ?.code;
+        if (resolverCode !== undefined) {
+            unresolved.code = resolverCode;
+        }
+        throw unresolved;
+    }
+    if (allowPrivate) {
+        return { v4: v4Addresses, v6: v6Addresses };
     }
     for (const addr of v4Addresses) {
         if (isBlockedIPv4(addr)) {
-            throw new Error(`URL "${url}" rejected: hostname ${host} resolves to ${addr} (IPv4 in blocked range)`);
+            throw new Error(`URL "${redactUrlForError(url)}" rejected: hostname ${host} resolves to ${addr} (IPv4 in blocked range)`);
         }
     }
     for (const addr of v6Addresses) {
@@ -362,7 +402,7 @@ async function resolveAndValidateHost(url, host) {
         // addresses are caught.
         const reason = checkHostLiteral(addr.toLowerCase());
         if (reason && reason !== "not-an-ip") {
-            throw new Error(`URL "${url}" rejected: hostname ${host} resolves to ${addr} (IPv6 ${reason})`);
+            throw new Error(`URL "${redactUrlForError(url)}" rejected: hostname ${host} resolves to ${addr} (IPv6 ${reason})`);
         }
     }
     return { v4: v4Addresses, v6: v6Addresses };
@@ -395,31 +435,28 @@ const INTERNAL_HOST_SUFFIXES = [
  *
  * Same throw semantics as {@link assertSafeUrl}.
  */
-export function assertSafeUrlForProxy(url) {
-    let parsed;
-    try {
-        parsed = new URL(url);
-    }
-    catch {
-        throw new Error(`Invalid URL: "${url}"`);
-    }
-    if (parsed.protocol !== "https:") {
-        throw new Error(`Only HTTPS URLs are permitted; got "${parsed.protocol}//" in "${url}"`);
-    }
+export function assertSafeUrlForProxy(url, options) {
+    const parsed = parseGuardedUrl(url, options);
     const host = stripBrackets(parsed.hostname).toLowerCase();
     const literalCheck = checkHostLiteral(host);
     if (literalCheck === null) {
         return; // routable IP literal
     }
     if (literalCheck !== "not-an-ip") {
-        throw new Error(`URL "${url}" rejected: ${literalCheck}`);
+        if (options?.allowPrivateNetwork === true) {
+            return; // a blocked range the caller explicitly opened
+        }
+        throw new Error(`URL "${redactUrlForError(url)}" rejected: ${literalCheck}`);
+    }
+    if (options?.allowPrivateNetwork === true) {
+        return; // internal names are exactly what the caller asked to reach
     }
     const name = host.endsWith(".") ? host.slice(0, -1) : host;
     if (!name.includes(".")) {
-        throw new Error(`URL "${url}" rejected: "${name}" is a single-label host name`);
+        throw new Error(`URL "${redactUrlForError(url)}" rejected: "${name}" is a single-label host name`);
     }
     if (INTERNAL_HOST_SUFFIXES.some((suffix) => name === suffix || name.endsWith(`.${suffix}`))) {
-        throw new Error(`URL "${url}" rejected: "${name}" is an internal host name`);
+        throw new Error(`URL "${redactUrlForError(url)}" rejected: "${name}" is an internal host name`);
     }
 }
 /**
@@ -439,31 +476,26 @@ export function assertSafeUrlForProxy(url) {
  * This is the canonical entry point for binary downloads where DNS-rebinding
  * pinning matters — see `safeFetch.ts`.
  */
-export async function validateAndResolveUrl(url) {
-    let parsed;
-    try {
-        parsed = new URL(url);
-    }
-    catch {
-        throw new Error(`Invalid URL: "${url}"`);
-    }
-    if (parsed.protocol !== "https:") {
-        throw new Error(`Only HTTPS URLs are permitted; got "${parsed.protocol}//" in "${url}"`);
-    }
+export async function validateAndResolveUrl(url, options) {
+    const parsed = parseGuardedUrl(url, options);
     const host = stripBrackets(parsed.hostname).toLowerCase();
+    // Only an explicit opt-in relaxes the range check; the default stays the
+    // server path's deny list. The resolve-and-pin step runs either way, so an
+    // opened-up caller still gets rebinding protection.
+    const allowPrivate = options?.allowPrivateNetwork === true;
     // IP literal — normalise + check, return canonical form
     const v4 = normalizeIPv4(host);
     if (v4) {
-        if (isBlockedIPv4(v4)) {
-            throw new Error(`URL "${url}" rejected: IPv4 ${host} → ${v4} is in a blocked range`);
+        if (!allowPrivate && isBlockedIPv4(v4)) {
+            throw new Error(`URL "${redactUrlForError(url)}" rejected: IPv4 ${host} → ${v4} is in a blocked range`);
         }
         return { url, ip: v4, family: 4, addresses: [{ ip: v4, family: 4 }] };
     }
     if (host.includes(":")) {
         const v4FromMapped = extractIPv4FromMapped(host);
         if (v4FromMapped) {
-            if (isBlockedIPv4(v4FromMapped)) {
-                throw new Error(`URL "${url}" rejected: IPv4-mapped IPv6 ${host} → ${v4FromMapped} is in a blocked range`);
+            if (!allowPrivate && isBlockedIPv4(v4FromMapped)) {
+                throw new Error(`URL "${redactUrlForError(url)}" rejected: IPv4-mapped IPv6 ${host} → ${v4FromMapped} is in a blocked range`);
             }
             return {
                 url,
@@ -474,10 +506,10 @@ export async function validateAndResolveUrl(url) {
         }
         const expanded = expandIPv6(host);
         if (!expanded) {
-            throw new Error(`URL "${url}" rejected: IPv6 ${host} could not be parsed`);
+            throw new Error(`URL "${redactUrlForError(url)}" rejected: IPv6 ${host} could not be parsed`);
         }
-        if (isBlockedIPv6(expanded)) {
-            throw new Error(`URL "${url}" rejected: IPv6 ${host} is in a blocked range`);
+        if (!allowPrivate && isBlockedIPv6(expanded)) {
+            throw new Error(`URL "${redactUrlForError(url)}" rejected: IPv6 ${host} is in a blocked range`);
         }
         return { url, ip: host, family: 6, addresses: [{ ip: host, family: 6 }] };
     }
@@ -485,7 +517,7 @@ export async function validateAndResolveUrl(url) {
     // set. Validating the same answer we hand to the connect layer also
     // removes the rebinding window the previous separate `lookup()` left
     // between validation and pinning.
-    const { v4: v4Addresses, v6: v6Addresses } = await resolveAndValidateHost(url, host);
+    const { v4: v4Addresses, v6: v6Addresses } = await resolveAndValidateHost(url, host, allowPrivate);
     const addresses = [
         ...v4Addresses.map((ip) => ({ ip, family: 4 })),
         ...v6Addresses.map((ip) => ({ ip, family: 6 })),
@@ -494,7 +526,7 @@ export async function validateAndResolveUrl(url) {
     if (!first) {
         // Both lookups "succeeded" but returned zero addresses — treat exactly
         // like a resolution failure rather than pinning nothing.
-        throw new Error(`URL "${url}" rejected: hostname ${host} resolved to an empty address set`);
+        throw new Error(`URL "${redactUrlForError(url)}" rejected: hostname ${host} resolved to an empty address set`);
     }
     return { url, ip: first.ip, family: first.family, addresses };
 }

package/dist/voice/eval/sttEvalStore.d.ts

@@ -3,21 +3,44 @@ export declare class STTEvalStore {
     private readonly _dir;
     private readonly _maxCalls;
     private readonly _maxSegments;
+    private readonly _maxBytes;
+    private _totalBytes;
     private readonly _calls;
     /** Per call: the tail of its accept queue, so batches apply and append in arrival order. */
     private readonly _queues;
     private _ready;
     private readonly _langfuse;
     constructor(options?: ServerSTTEvalOptions);
-    accept(batch: ServerSTTEvalBatchRequest): Promise<ServerSTTEvalBatchResponse>;
-    list(): Promise<ServerSTTEvalCallSummary[]>;
-    report(callId: string, includeSegments?: boolean): Promise<ServerSTTEvalReport | undefined>;
+    /** Bytes of segments held in memory right now, across every call. */
+    get heldBytes(): number;
+    /**
+     * Take a batch. `owner` is the authenticated caller, when the server
+     * identified one: a call created with an owner accepts batches only from
+     * that owner, and `undefined` is returned for anyone else's.
+     */
+    accept(batch: ServerSTTEvalBatchRequest, owner?: string): Promise<ServerSTTEvalBatchResponse | undefined>;
+    /** Calls visible to `owner`: theirs and the unowned ones (see `_visibleTo`). */
+    list(owner?: string): Promise<ServerSTTEvalCallSummary[]>;
+    report(callId: string, includeSegments?: boolean, owner?: string): Promise<ServerSTTEvalReport | undefined>;
+    /**
+     * A call an identified caller created is theirs alone. A call with no owner
+     * (made under no authentication or a shared key) is visible to everyone, as
+     * every call was before owners existed.
+     */
+    private _visibleTo;
     private _reportOf;
     /** Runs `task` after every earlier task for the same call has settled. */
     private _serial;
     private _create;
     private _apply;
     private _callFor;
+    private _charge;
+    /**
+     * Drop the least recently updated calls while there are more than
+     * `maxCalls`, or while the held segments exceed `maxBytes`; a dropped call
+     * is still on disk when there is a directory. The newest call is never
+     * dropped, so a single call larger than the budget stays.
+     */
     private _evict;
     private _fileFor;
     /** Replays the directory once; every caller awaits the same load. */

package/dist/voice/eval/sttEvalStore.js

@@ -21,13 +21,21 @@ import { phoneticKey } from "../codeMix.js";
 import { STTEvalLangfuseExporter, sttEvalLangfuseConfigFromEnv, } from "./sttEvalLangfuse.js";
 const DEFAULT_MAX_CALLS = 1000;
 const DEFAULT_MAX_SEGMENTS = 50_000;
+/** Bytes of segments held in memory across every call. */
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
 /** Words per side above which a speaker is aligned in time windows instead of whole. */
 const FULL_ALIGN_MAX_WORDS = 4000;
 const WINDOW_S = 300;
+/** Roughly what a segment costs in memory: its JSON, which is what is kept. */
+function segmentBytes(segment) {
+    return JSON.stringify(segment).length;
+}
 export class STTEvalStore {
     _dir;
     _maxCalls;
     _maxSegments;
+    _maxBytes;
+    _totalBytes = 0;
     _calls = new Map();
     /** Per call: the tail of its accept queue, so batches apply and append in arrival order. */
     _queues = new Map();
@@ -38,19 +46,36 @@ export class STTEvalStore {
         this._dir = dir ? dir : undefined;
         this._maxCalls = Math.max(1, options.maxCalls ?? DEFAULT_MAX_CALLS);
         this._maxSegments = Math.max(1, options.maxSegmentsPerCall ?? DEFAULT_MAX_SEGMENTS);
+        this._maxBytes = Math.max(1, options.maxBytes ?? DEFAULT_MAX_BYTES);
         const langfuse = sttEvalLangfuseConfigFromEnv();
         this._langfuse = langfuse
             ? new STTEvalLangfuseExporter(langfuse)
             : undefined;
     }
-    async accept(batch) {
+    /** Bytes of segments held in memory right now, across every call. */
+    get heldBytes() {
+        return this._totalBytes;
+    }
+    /**
+     * Take a batch. `owner` is the authenticated caller, when the server
+     * identified one: a call created with an owner accepts batches only from
+     * that owner, and `undefined` is returned for anyone else's.
+     */
+    async accept(batch, owner) {
         await this._load();
         return this._serial(batch.call_id, async () => {
-            const call = (await this._callFor(batch.call_id)) ?? this._create(batch);
+            const held = await this._callFor(batch.call_id);
+            if (held && !this._visibleTo(held, owner)) {
+                return undefined;
+            }
+            const call = held ?? this._create(batch, owner);
             const counts = this._apply(call, batch);
             if (this._dir) {
                 try {
-                    await appendFile(this._fileFor(batch.call_id), `${JSON.stringify(batch)}\n`, "utf8");
+                    const stored = owner
+                        ? { ...batch, owner }
+                        : batch;
+                    await appendFile(this._fileFor(batch.call_id), `${JSON.stringify(stored)}\n`, "utf8");
                 }
                 catch (error) {
                     logger.warn("[stt-eval] could not persist batch", {
@@ -73,16 +98,28 @@ export class STTEvalStore {
             };
         });
     }
-    async list() {
+    /** Calls visible to `owner`: theirs and the unowned ones (see `_visibleTo`). */
+    async list(owner) {
         await this._load();
         return [...this._calls.values()]
+            .filter((call) => this._visibleTo(call, owner))
             .sort((a, b) => b.updatedAt - a.updatedAt)
             .map(summarize);
     }
-    async report(callId, includeSegments = false) {
+    async report(callId, includeSegments = false, owner) {
         await this._load();
         const call = await this._callFor(callId);
-        return call ? this._reportOf(call, includeSegments) : undefined;
+        return call && this._visibleTo(call, owner)
+            ? this._reportOf(call, includeSegments)
+            : undefined;
+    }
+    /**
+     * A call an identified caller created is theirs alone. A call with no owner
+     * (made under no authentication or a shared key) is visible to everyone, as
+     * every call was before owners existed.
+     */
+    _visibleTo(call, owner) {
+        return call.owner === undefined || call.owner === owner;
     }
     _reportOf(call, includeSegments) {
         const ordered = [...call.segments.values()].sort((a, b) => timeOf(a) - timeOf(b));
@@ -128,7 +165,7 @@ export class STTEvalStore {
         });
         return run;
     }
-    _create(batch) {
+    _create(batch, owner) {
         const call = {
             callId: batch.call_id,
             room: batch.room ?? null,
@@ -137,6 +174,8 @@ export class STTEvalStore {
             batches: new Set(),
             segments: new Map(),
             updatedAt: Date.now(),
+            bytes: 0,
+            ...(owner ? { owner } : {}),
         };
         this._calls.set(batch.call_id, call);
         return call;
@@ -146,8 +185,10 @@ export class STTEvalStore {
         let updated = 0;
         let ignored = 0;
         for (const segment of batch.segments) {
-            if (call.segments.has(segment.id)) {
+            const previous = call.segments.get(segment.id);
+            if (previous) {
                 updated++;
+                this._charge(call, -segmentBytes(previous));
             }
             else if (call.segments.size >= this._maxSegments) {
                 ignored++;
@@ -157,6 +198,7 @@ export class STTEvalStore {
                 inserted++;
             }
             call.segments.set(segment.id, { ...segment });
+            this._charge(call, segmentBytes(segment));
         }
         call.batches.add(batch.batch);
         call.final = call.final || batch.final === true;
@@ -173,17 +215,38 @@ export class STTEvalStore {
         if (held || !this._dir) {
             return held;
         }
-        // Evicted from memory but still on disk.
+        // Evicted from memory but still on disk. Replaying re-registers the call
+        // and its bytes; the next eviction pass trims the budget again.
         const text = await readFile(this._fileFor(callId), "utf8").catch(() => undefined);
-        return text === undefined ? undefined : this._replay(text);
+        if (text === undefined) {
+            return undefined;
+        }
+        const call = this._replay(text);
+        this._evict();
+        return call;
     }
+    _charge(call, delta) {
+        call.bytes += delta;
+        this._totalBytes = Math.max(0, this._totalBytes + delta);
+    }
+    /**
+     * Drop the least recently updated calls while there are more than
+     * `maxCalls`, or while the held segments exceed `maxBytes`; a dropped call
+     * is still on disk when there is a directory. The newest call is never
+     * dropped, so a single call larger than the budget stays.
+     */
     _evict() {
-        while (this._calls.size > this._maxCalls) {
+        while (this._calls.size > 1 &&
+            (this._calls.size > this._maxCalls || this._totalBytes > this._maxBytes)) {
             const oldest = this._calls.keys().next().value;
             if (oldest === undefined) {
                 return;
             }
+            const call = this._calls.get(oldest);
             this._calls.delete(oldest);
+            if (call) {
+                this._totalBytes = Math.max(0, this._totalBytes - call.bytes);
+            }
         }
     }
     _fileFor(callId) {
@@ -210,8 +273,10 @@ export class STTEvalStore {
             // Replay order is filesystem order; keep the most recent calls.
             const recent = [...this._calls.values()].sort((a, b) => a.updatedAt - b.updatedAt);
             this._calls.clear();
+            this._totalBytes = 0;
             for (const call of recent) {
                 this._calls.set(call.callId, call);
+                this._totalBytes += call.bytes;
             }
             this._evict();
         }
@@ -231,7 +296,7 @@ export class STTEvalStore {
             }
             try {
                 const batch = JSON.parse(line);
-                call = call ?? this._create(batch);
+                call = call ?? this._create(batch, batch.owner);
                 this._apply(call, batch);
                 for (const segment of batch.segments) {
                     lastSeen = Math.max(lastSeen, segment.received_at * 1000);

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

@@ -0,0 +1,18 @@
+/**
+ * Marks an agent object so the `@livekit/agents` job process accepts it.
+ *
+ * Since 1.9 the framework's `isAgent` gate (what the job process runs on the
+ * entry file's default export) no longer looks for an `entry` function: it
+ * checks for the registry symbol `Symbol.for("livekit.agents.AgentDefinition")`
+ * that `defineAgent` stamps, and an unmarked object fails with "Unable to load
+ * agent: Missing or invalid default export". `defineVoiceAgent` and
+ * `defineRealtimeVoiceAgent` return their object through this helper so an
+ * entry file's `export default defineVoiceAgent({...})` keeps working.
+ *
+ * The symbol is read from the global registry rather than imported, because
+ * `@livekit/agents` is an optional dependency this module only ever imports
+ * dynamically. The property is defined exactly as `defineAgent` defines it, so a
+ * consumer that additionally wraps the result in `defineAgent` redefines an
+ * identical property, which is permitted.
+ */
+export declare function markAgentDefinition<T extends object>(agent: T): T;

package/dist/voice/livekit/agentDefinition.js

@@ -0,0 +1,22 @@
+/**
+ * Marks an agent object so the `@livekit/agents` job process accepts it.
+ *
+ * Since 1.9 the framework's `isAgent` gate (what the job process runs on the
+ * entry file's default export) no longer looks for an `entry` function: it
+ * checks for the registry symbol `Symbol.for("livekit.agents.AgentDefinition")`
+ * that `defineAgent` stamps, and an unmarked object fails with "Unable to load
+ * agent: Missing or invalid default export". `defineVoiceAgent` and
+ * `defineRealtimeVoiceAgent` return their object through this helper so an
+ * entry file's `export default defineVoiceAgent({...})` keeps working.
+ *
+ * The symbol is read from the global registry rather than imported, because
+ * `@livekit/agents` is an optional dependency this module only ever imports
+ * dynamically. The property is defined exactly as `defineAgent` defines it, so a
+ * consumer that additionally wraps the result in `defineAgent` redefines an
+ * identical property, which is permitted.
+ */
+const AGENT_DEFINITION_SYMBOL = Symbol.for("livekit.agents.AgentDefinition");
+export function markAgentDefinition(agent) {
+    Object.defineProperty(agent, AGENT_DEFINITION_SYMBOL, { value: true });
+    return agent;
+}

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

@@ -20,7 +20,7 @@ import type { BuildRealtimeMcpToolsParams } from "../../types/index.js";
 export declare function mcpResultToText(result: unknown): string;
 /**
  * Connect to the MCP server as the calling user and bridge every tool into a
- * LiveKit `ToolContext`. Returns the tool map + the client (close on shutdown).
+ * LiveKit `ToolContext`. Returns that context + the client (close on shutdown).
  * The server already scopes the tool list by `x-context`, so no client-side
  * filtering is needed.
  */

package/dist/voice/livekit/realtimeMcpTools.js

@@ -73,7 +73,7 @@ function buildHitlDeclineMessage(toolName) {
  * First registration wins, so a unique full name is never shadowed by a generic
  * short name. Returns the aliases actually registered.
  */
-function registerToolAliases(toolContext, mcpToolName, handler) {
+function registerToolAliases(registry, mcpToolName, handler) {
     const safeFullName = mcpToolName.replace(/[^a-zA-Z0-9_]/g, "_");
     const shortName = safeFullName.includes("_")
         ? safeFullName.slice(safeFullName.lastIndexOf("_") + 1)
@@ -81,17 +81,17 @@ function registerToolAliases(toolContext, mcpToolName, handler) {
     const candidates = [safeFullName, shortName].filter((name, index, all) => name.length > 0 && all.indexOf(name) === index);
     const registered = [];
     for (const alias of candidates) {
-        if (alias in toolContext) {
+        if (alias in registry) {
             continue; // taken by another tool — don't clobber
         }
-        toolContext[alias] = handler;
+        registry[alias] = handler;
         registered.push(alias);
     }
     return registered;
 }
 /**
  * Connect to the MCP server as the calling user and bridge every tool into a
- * LiveKit `ToolContext`. Returns the tool map + the client (close on shutdown).
+ * LiveKit `ToolContext`. Returns that context + the client (close on shutdown).
  * The server already scopes the tool list by `x-context`, so no client-side
  * filtering is needed.
  */
@@ -126,7 +126,7 @@ export async function buildRealtimeMcpTools(params) {
     try {
         const { tools: mcpTools } = await client.listTools();
         logger.info("realtime.mcp.toolsListed", { count: mcpTools.length });
-        const toolContext = {};
+        const registry = {};
         const skipped = [];
         for (const mcpTool of mcpTools) {
             const parameters = sanitizeToolParameters(mcpTool.inputSchema);
@@ -209,15 +209,16 @@ export async function buildRealtimeMcpTools(params) {
                     }
                 },
             });
-            const aliases = registerToolAliases(toolContext, mcpTool.name, handler);
+            const aliases = registerToolAliases(registry, mcpTool.name, handler);
             logger.info("realtime.mcp.toolRegistered", {
                 tool: mcpTool.name,
                 aliases,
                 hitl: requiresConfirmation,
             });
         }
+        const toolContext = new llm.ToolContext(registry);
         logger.info("realtime.mcp.connected", {
-            registered: Object.keys(toolContext).length,
+            registered: Object.keys(registry).length,
             skipped: skipped.length,
             skippedTools: skipped,
         });

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

@@ -15,7 +15,7 @@
  *
  * See docs/features/livekit-voice-agent.md.
  */
-import type { JobContext } from "@livekit/agents";
+import type { AgentDefinition } from "@livekit/agents";
 import type { RealtimeVoiceAgentConfig } from "../../types/index.js";
 /**
  * Define a realtime (speech-to-speech) LiveKit voice agent: Gemini Live by
@@ -25,6 +25,4 @@ import type { RealtimeVoiceAgentConfig } from "../../types/index.js";
  * with `startRealtimeVoiceAgentWorker`. With no `config` everything is resolved
  * from the environment (see `resolveRealtimeVoiceConfig`).
  */
-export declare function defineRealtimeVoiceAgent(config?: RealtimeVoiceAgentConfig): {
-    entry: (ctx: JobContext) => Promise<void>;
-};
+export declare function defineRealtimeVoiceAgent(config?: RealtimeVoiceAgentConfig): AgentDefinition;

package/dist/voice/livekit/realtimeVoiceAgent.js

@@ -15,8 +15,10 @@
  *
  * See docs/features/livekit-voice-agent.md.
  */
+import { ReadableStream } from "node:stream/web";
 import { z } from "zod";
 import { logger } from "../../utils/logger.js";
+import { markAgentDefinition } from "./agentDefinition.js";
 import { resolveRealtimeVoiceConfig } from "./config.js";
 import { ensureVertexAdc, clearGeminiApiKeyEnv } from "./vertexAuth.js";
 import { createRealtimeLlm, requireXaiApiKey } from "./realtimeModel.js";
@@ -232,7 +234,7 @@ export function defineRealtimeVoiceAgent(config = {}) {
                     : {}),
             });
         await installRealtimeJobLifecycle(ctx, cfg);
-        const { voice } = await import("@livekit/agents");
+        const { voice, toStream } = await import("@livekit/agents");
         const realtimeLlm = await createRealtimeLlm(cfg);
         const bridge = await attachRealtimeEventBridge({
             room: ctx.room,
@@ -271,7 +273,7 @@ export function defineRealtimeVoiceAgent(config = {}) {
                     agentTools = toolset.tools;
                     logger.info("realtime.mcp.enabled", {
                         mcpUrl: cfg.mcpUrl,
-                        toolCount: Object.keys(toolset.tools).length,
+                        toolCount: Object.keys(toolset.tools.functionTools).length,
                         hasAuthToken: authToken !== "",
                     });
                     ctx.addShutdownCallback(async () => {
@@ -311,7 +313,12 @@ export function defineRealtimeVoiceAgent(config = {}) {
             ...(seededChatCtx ? { chatCtx: seededChatCtx } : {}),
         });
         agent.transcriptionNode = async (textStream, _modelSettings) => {
-            const [forUi, forDownstream] = textStream.tee();
+            // 1.9 hands the node a ReadableStream or a bare AsyncIterable; only a
+            // stream has tee(), so mirror the framework default and wrap the latter.
+            const source = textStream instanceof ReadableStream
+                ? textStream
+                : toStream(textStream);
+            const [forUi, forDownstream] = source.tee();
             void (async () => {
                 const reader = forUi.getReader();
                 let chunkCount = 0;
@@ -363,18 +370,22 @@ export function defineRealtimeVoiceAgent(config = {}) {
         });
         // --- Session events → browser ------------------------------------------
         session.on(voice.AgentSessionEventTypes.UserInputTranscribed, (ev) => {
+            // agents-plugin-xai >= 1.9 emits only the *completed* transcription and
+            // flags it `isFinal: false`; without this every xAI user turn would be
+            // published as interim and the recorder would never see a final line.
+            const final = ev.isFinal || cfg.backend === "xai";
             logger.debug("realtime.session.userTranscript", {
                 ms: sinceConnect(),
-                final: ev.isFinal,
+                final,
                 transcript: ev.transcript,
             });
             bridge.publishEvent("user-text", {
                 text: ev.transcript,
-                final: ev.isFinal,
+                final,
             });
             recorder?.userTranscript({
                 text: ev.transcript,
-                final: ev.isFinal,
+                final,
             });
         });
         session.on(voice.AgentSessionEventTypes.AgentStateChanged, (ev) => {
@@ -416,5 +427,5 @@ export function defineRealtimeVoiceAgent(config = {}) {
             session.generateReply({ instructions: cfg.greeting });
         }
     }
-    return { entry };
+    return markAgentDefinition({ entry });
 }

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

@@ -14,7 +14,7 @@
  *
  * See docs/features/livekit-voice-agent.md.
  */
-import type { Agent as JobAgent } from "@livekit/agents";
+import type { AgentDefinition } from "@livekit/agents";
 import type { LiveKitVoiceAgentConfig } from "../../types/index.js";
 /**
  * Define a LiveKit voice agent backed by NeuroLink.
@@ -29,4 +29,4 @@ import type { LiveKitVoiceAgentConfig } from "../../types/index.js";
  * });
  * ```
  */
-export declare function defineVoiceAgent(config: LiveKitVoiceAgentConfig): JobAgent;
+export declare function defineVoiceAgent(config: LiveKitVoiceAgentConfig): AgentDefinition;