@livekit/agents 1.0.47 → 1.0.48

package/src/utils.ts

@@ -173,6 +173,11 @@ export class Future<T = void> {
     this.#rejected = true;
     this.#error = error;
     this.#rejectPromise(error);
+    // Python calls Future.exception() right after set_exception() to silence
+    // "exception was never retrieved" warnings. In JS, consume the rejection
+    // immediately so Node does not emit unhandled-rejection noise before a
+    // later await/catch observes it.
+    void this.#await.catch(() => undefined);
   }
 }
 

package/src/voice/agent.ts

@@ -302,6 +302,17 @@ export class Agent<UserData = any> {
     this._agentActivity.updateChatCtx(chatCtx);
   }
 
+  // TODO(parity): Add when AgentConfigUpdate is ported to ChatContext.
+  async updateTools(tools: ToolContext): Promise<void> {
+    if (!this._agentActivity) {
+      this._tools = { ...tools };
+      this._chatCtx = this._chatCtx.copy({ toolCtx: this._tools });
+      return;
+    }
+
+    await this._agentActivity.updateTools(tools);
+  }
+
   static default = {
     async sttNode(
       agent: Agent,

package/src/voice/agent_activity.ts

@@ -23,6 +23,7 @@ import {
   type RealtimeSession,
   type ToolChoice,
   type ToolContext,
+  ToolFlag,
 } from '../llm/index.js';
 import type { LLMError } from '../llm/llm.js';
 import { isSameToolChoice, isSameToolContext } from '../llm/tool_context.js';
@@ -83,6 +84,12 @@ import { SpeechHandle } from './speech_handle.js';
 import { setParticipantSpanAttributes } from './utils.js';
 
 export const agentActivityStorage = new AsyncLocalStorage<AgentActivity>();
+export const onEnterStorage = new AsyncLocalStorage<OnEnterData>();
+
+interface OnEnterData {
+  session: AgentSession;
+  agent: Agent;
+}
 
 interface PreemptiveGeneration {
   speechHandle: SpeechHandle;
@@ -312,6 +319,8 @@ export class AgentActivity implements RecognitionHooks {
       }
     }
 
+    // TODO(parity): Record initial AgentConfigUpdate in chat context
+
     // metrics and error handling
     if (this.llm instanceof LLM) {
       this.llm.on('metrics_collected', this.onMetricsCollected);
@@ -354,11 +363,13 @@ export class AgentActivity implements RecognitionHooks {
     if (runOnEnter) {
       this._onEnterTask = this.createSpeechTask({
         taskFn: () =>
-          tracer.startActiveSpan(async () => this.agent.onEnter(), {
-            name: 'on_enter',
-            context: trace.setSpan(ROOT_CONTEXT, startSpan),
-            attributes: { [traceTypes.ATTR_AGENT_LABEL]: this.agent.id },
-          }),
+          onEnterStorage.run({ session: this.agentSession, agent: this.agent }, () =>
+            tracer.startActiveSpan(async () => this.agent.onEnter(), {
+              name: 'on_enter',
+              context: trace.setSpan(ROOT_CONTEXT, startSpan),
+              attributes: { [traceTypes.ATTR_AGENT_LABEL]: this.agent.id },
+            }),
+          ),
         inlineTask: true,
         name: 'AgentActivity_onEnter',
       });
@@ -446,6 +457,20 @@ export class AgentActivity implements RecognitionHooks {
     }
   }
 
+  // TODO: Add when AgentConfigUpdate is ported to ChatContext.
+  async updateTools(tools: ToolContext): Promise<void> {
+    this.agent._tools = { ...tools };
+
+    if (this.realtimeSession) {
+      await this.realtimeSession.updateTools(tools);
+    }
+
+    if (this.llm instanceof LLM) {
+      // for realtime LLM, we assume the server will remove unvalid tool messages
+      await this.updateChatCtx(this.agent._chatCtx.copy({ toolCtx: tools }));
+    }
+  }
+
   updateOptions({ toolChoice }: { toolChoice?: ToolChoice | null }): void {
     if (toolChoice !== undefined) {
       this.toolChoice = toolChoice;
@@ -1129,12 +1154,25 @@ export class AgentActivity implements RecognitionHooks {
         instructions = `${this.agent.instructions}\n${instructions}`;
       }
 
+      // Filter out tools with IGNORE_ON_ENTER flag when generateReply is called inside onEnter
+      const onEnterData = onEnterStorage.getStore();
+      const shouldFilterTools =
+        onEnterData?.agent === this.agent && onEnterData?.session === this.agentSession;
+
+      const tools = shouldFilterTools
+        ? Object.fromEntries(
+            Object.entries(this.agent.toolCtx).filter(
+              ([, fnTool]) => !(fnTool.flags & ToolFlag.IGNORE_ON_ENTER),
+            ),
+          )
+        : this.agent.toolCtx;
+
       const task = this.createSpeechTask({
         taskFn: (abortController: AbortController) =>
           this.pipelineReplyTask(
             handle,
             chatCtx ?? this.agent.chatCtx,
-            this.agent.toolCtx,
+            tools,
             {
               toolChoice: toOaiToolChoice(toolChoice !== undefined ? toolChoice : this.toolChoice),
             },

package/src/voice/room_io/room_io.ts

@@ -21,7 +21,7 @@ import type { WritableStreamDefaultWriter } from 'node:stream/web';
 import { ATTRIBUTE_PUBLISH_ON_BEHALF, TOPIC_CHAT } from '../../constants.js';
 import { log } from '../../log.js';
 import { IdentityTransform } from '../../stream/identity_transform.js';
-import { Future, Task } from '../../utils.js';
+import { Future, Task, waitForAbort } from '../../utils.js';
 import { type AgentSession } from '../agent_session.js';
 import {
   AgentSessionEventTypes,
@@ -177,7 +177,10 @@ export class RoomIO {
       : this.inputOptions.participantIdentity ?? null;
   }
   private async init(signal: AbortSignal): Promise<void> {
-    await this.roomConnectedFuture.await;
+    await Promise.race([this.roomConnectedFuture.await, waitForAbort(signal)]);
+    if (signal.aborted) {
+      return;
+    }
 
     for (const participant of this.room.remoteParticipants.values()) {
       this.onParticipantConnected(participant);
@@ -186,7 +189,15 @@ export class RoomIO {
       return;
     }
 
-    const participant = await this.participantAvailableFuture.await;
+    const participant = await Promise.race([
+      this.participantAvailableFuture.await,
+      waitForAbort(signal),
+    ]);
+
+    if (!participant) {
+      return;
+    }
+
     this.setParticipant(participant.identity);
 
     // init agent outputs

package/src/voice/testing/fake_llm.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type { ChatContext } from '../../llm/chat_context.js';
+import { FunctionCall } from '../../llm/chat_context.js';
+import { LLMStream as BaseLLMStream, LLM, type LLMStream } from '../../llm/llm.js';
+import type { ToolChoice, ToolContext } from '../../llm/tool_context.js';
+import { type APIConnectOptions, DEFAULT_API_CONNECT_OPTIONS } from '../../types.js';
+import { delay } from '../../utils.js';
+
+export interface FakeLLMResponse {
+  input: string;
+  type?: 'llm';
+  content?: string;
+  ttft?: number;
+  duration?: number;
+  toolCalls?: Array<{ name: string; args: Record<string, unknown> }>;
+}
+
+export class FakeLLM extends LLM {
+  private readonly responseMap = new Map<string, FakeLLMResponse>();
+
+  constructor(responses: FakeLLMResponse[] = []) {
+    super();
+    for (const response of responses) {
+      this.responseMap.set(response.input, {
+        type: 'llm',
+        ttft: 0,
+        duration: 0,
+        ...response,
+      });
+    }
+  }
+
+  label(): string {
+    return 'fake-llm';
+  }
+
+  chat({
+    chatCtx,
+    toolCtx,
+    connOptions = DEFAULT_API_CONNECT_OPTIONS,
+  }: {
+    chatCtx: ChatContext;
+    toolCtx?: ToolContext;
+    connOptions?: APIConnectOptions;
+    parallelToolCalls?: boolean;
+    toolChoice?: ToolChoice;
+    extraKwargs?: Record<string, unknown>;
+  }): LLMStream {
+    return new FakeLLMStream(this, {
+      chatCtx,
+      toolCtx,
+      connOptions,
+    });
+  }
+
+  lookup(input: string): FakeLLMResponse | undefined {
+    return this.responseMap.get(input);
+  }
+}
+
+class FakeLLMStream extends BaseLLMStream {
+  private readonly fake: FakeLLM;
+
+  constructor(
+    fake: FakeLLM,
+    params: { chatCtx: ChatContext; toolCtx?: ToolContext; connOptions: APIConnectOptions },
+  ) {
+    super(fake, params);
+    this.fake = fake;
+  }
+
+  protected async run(): Promise<void> {
+    const input = this.getInputText();
+    const decision = this.fake.lookup(input);
+    if (!decision) {
+      return;
+    }
+
+    const startedAt = Date.now();
+    if ((decision.ttft ?? 0) > 0) {
+      await delay(decision.ttft!);
+    }
+
+    const content = decision.content ?? '';
+    const chunkSize = 3;
+    for (let i = 0; i < content.length; i += chunkSize) {
+      this.queue.put({
+        id: 'fake',
+        delta: { role: 'assistant', content: content.slice(i, i + chunkSize) },
+      });
+    }
+
+    if (decision.toolCalls && decision.toolCalls.length > 0) {
+      const calls = decision.toolCalls.map((tc, index) =>
+        FunctionCall.create({
+          callId: `fake_call_${index}`,
+          name: tc.name,
+          args: JSON.stringify(tc.args),
+        }),
+      );
+      this.queue.put({
+        id: 'fake',
+        delta: { role: 'assistant', toolCalls: calls },
+      });
+    }
+
+    const elapsed = Date.now() - startedAt;
+    const waitMs = Math.max(0, (decision.duration ?? 0) - elapsed);
+    if (waitMs > 0) {
+      await delay(waitMs);
+    }
+  }
+
+  private getInputText(): string {
+    const items = this.chatCtx.items;
+    if (items.length === 0) {
+      throw new Error('No input text found');
+    }
+
+    for (const item of items) {
+      if (item.type === 'message' && item.role === 'system') {
+        const text = item.textContent ?? '';
+        const lines = text.split('\n');
+        const tail = lines[lines.length - 1] ?? '';
+        if (lines.length > 1 && tail.startsWith('instructions:')) {
+          return tail;
+        }
+      }
+    }
+
+    const last = items[items.length - 1]!;
+    if (last.type === 'message' && last.role === 'user') return last.textContent ?? '';
+    if (last.type === 'function_call_output') return last.output;
+    throw new Error('No input text found');
+  }
+}

package/src/voice/testing/index.ts

@@ -48,3 +48,5 @@ export {
   type MessageAssertOptions,
   type RunEvent,
 } from './types.js';
+
+export { FakeLLM, type FakeLLMResponse } from './fake_llm.js';