@livekit/agents 1.0.47 → 1.0.48

package/dist/voice/testing/fake_llm.js.map

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

package/dist/voice/testing/index.cjs

@@ -22,6 +22,7 @@ __export(testing_exports, {
   AssertionError: () => import_run_result.AssertionError,
   EventAssert: () => import_run_result.EventAssert,
   EventRangeAssert: () => import_run_result.EventRangeAssert,
+  FakeLLM: () => import_fake_llm.FakeLLM,
   FunctionCallAssert: () => import_run_result.FunctionCallAssert,
   FunctionCallOutputAssert: () => import_run_result.FunctionCallOutputAssert,
   MessageAssert: () => import_run_result.MessageAssert,
@@ -35,12 +36,14 @@ __export(testing_exports, {
 module.exports = __toCommonJS(testing_exports);
 var import_run_result = require("./run_result.cjs");
 var import_types = require("./types.cjs");
+var import_fake_llm = require("./fake_llm.cjs");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentHandoffAssert,
   AssertionError,
   EventAssert,
   EventRangeAssert,
+  FakeLLM,
   FunctionCallAssert,
   FunctionCallOutputAssert,
   MessageAssert,

package/dist/voice/testing/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/voice/testing/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Testing utilities for agent evaluation.\n *\n * @example\n * ```typescript\n * import { AgentSession, Agent, voice } from '@livekit/agents';\n *\n * const session = new AgentSession({ llm });\n * await session.start(agent);\n *\n * const result = await session.run({ userInput: 'Hello' });\n * result.expect.nextEvent().isMessage({ role: 'assistant' });\n * result.expect.noMoreEvents();\n * ```\n *\n * @packageDocumentation\n */\n\nexport {\n  AgentHandoffAssert,\n  AssertionError,\n  EventAssert,\n  EventRangeAssert,\n  FunctionCallAssert,\n  FunctionCallOutputAssert,\n  MessageAssert,\n  RunAssert,\n  RunResult,\n} from './run_result.js';\n\nexport {\n  isAgentHandoffEvent,\n  isChatMessageEvent,\n  isFunctionCallEvent,\n  isFunctionCallOutputEvent,\n  type AgentHandoffAssertOptions,\n  type AgentHandoffEvent,\n  type ChatMessageEvent,\n  type EventType,\n  type FunctionCallAssertOptions,\n  type FunctionCallEvent,\n  type FunctionCallOutputAssertOptions,\n  type FunctionCallOutputEvent,\n  type MessageAssertOptions,\n  type RunEvent,\n} from './types.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBA,wBAUO;AAEP,mBAeO;","names":[]}
+{"version":3,"sources":["../../../src/voice/testing/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Testing utilities for agent evaluation.\n *\n * @example\n * ```typescript\n * import { AgentSession, Agent, voice } from '@livekit/agents';\n *\n * const session = new AgentSession({ llm });\n * await session.start(agent);\n *\n * const result = await session.run({ userInput: 'Hello' });\n * result.expect.nextEvent().isMessage({ role: 'assistant' });\n * result.expect.noMoreEvents();\n * ```\n *\n * @packageDocumentation\n */\n\nexport {\n  AgentHandoffAssert,\n  AssertionError,\n  EventAssert,\n  EventRangeAssert,\n  FunctionCallAssert,\n  FunctionCallOutputAssert,\n  MessageAssert,\n  RunAssert,\n  RunResult,\n} from './run_result.js';\n\nexport {\n  isAgentHandoffEvent,\n  isChatMessageEvent,\n  isFunctionCallEvent,\n  isFunctionCallOutputEvent,\n  type AgentHandoffAssertOptions,\n  type AgentHandoffEvent,\n  type ChatMessageEvent,\n  type EventType,\n  type FunctionCallAssertOptions,\n  type FunctionCallEvent,\n  type FunctionCallOutputAssertOptions,\n  type FunctionCallOutputEvent,\n  type MessageAssertOptions,\n  type RunEvent,\n} from './types.js';\n\nexport { FakeLLM, type FakeLLMResponse } from './fake_llm.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBA,wBAUO;AAEP,mBAeO;AAEP,sBAA8C;","names":[]}

package/dist/voice/testing/index.d.cts

@@ -17,4 +17,5 @@
  */
 export { AgentHandoffAssert, AssertionError, EventAssert, EventRangeAssert, FunctionCallAssert, FunctionCallOutputAssert, MessageAssert, RunAssert, RunResult, } from './run_result.js';
 export { isAgentHandoffEvent, isChatMessageEvent, isFunctionCallEvent, isFunctionCallOutputEvent, type AgentHandoffAssertOptions, type AgentHandoffEvent, type ChatMessageEvent, type EventType, type FunctionCallAssertOptions, type FunctionCallEvent, type FunctionCallOutputAssertOptions, type FunctionCallOutputEvent, type MessageAssertOptions, type RunEvent, } from './types.js';
+export { FakeLLM, type FakeLLMResponse } from './fake_llm.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -17,4 +17,5 @@
  */
 export { AgentHandoffAssert, AssertionError, EventAssert, EventRangeAssert, FunctionCallAssert, FunctionCallOutputAssert, MessageAssert, RunAssert, RunResult, } from './run_result.js';
 export { isAgentHandoffEvent, isChatMessageEvent, isFunctionCallEvent, isFunctionCallOutputEvent, type AgentHandoffAssertOptions, type AgentHandoffEvent, type ChatMessageEvent, type EventType, type FunctionCallAssertOptions, type FunctionCallEvent, type FunctionCallOutputAssertOptions, type FunctionCallOutputEvent, type MessageAssertOptions, type RunEvent, } from './types.js';
+export { FakeLLM, type FakeLLMResponse } from './fake_llm.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/voice/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/voice/testing/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,aAAa,EACb,SAAS,EACT,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,+BAA+B,EACpC,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/voice/testing/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,aAAa,EACb,SAAS,EACT,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,+BAA+B,EACpC,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/voice/testing/index.js

@@ -15,11 +15,13 @@ import {
   isFunctionCallEvent,
   isFunctionCallOutputEvent
 } from "./types.js";
+import { FakeLLM } from "./fake_llm.js";
 export {
   AgentHandoffAssert,
   AssertionError,
   EventAssert,
   EventRangeAssert,
+  FakeLLM,
   FunctionCallAssert,
   FunctionCallOutputAssert,
   MessageAssert,

package/dist/voice/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/voice/testing/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Testing utilities for agent evaluation.\n *\n * @example\n * ```typescript\n * import { AgentSession, Agent, voice } from '@livekit/agents';\n *\n * const session = new AgentSession({ llm });\n * await session.start(agent);\n *\n * const result = await session.run({ userInput: 'Hello' });\n * result.expect.nextEvent().isMessage({ role: 'assistant' });\n * result.expect.noMoreEvents();\n * ```\n *\n * @packageDocumentation\n */\n\nexport {\n  AgentHandoffAssert,\n  AssertionError,\n  EventAssert,\n  EventRangeAssert,\n  FunctionCallAssert,\n  FunctionCallOutputAssert,\n  MessageAssert,\n  RunAssert,\n  RunResult,\n} from './run_result.js';\n\nexport {\n  isAgentHandoffEvent,\n  isChatMessageEvent,\n  isFunctionCallEvent,\n  isFunctionCallOutputEvent,\n  type AgentHandoffAssertOptions,\n  type AgentHandoffEvent,\n  type ChatMessageEvent,\n  type EventType,\n  type FunctionCallAssertOptions,\n  type FunctionCallEvent,\n  type FunctionCallOutputAssertOptions,\n  type FunctionCallOutputEvent,\n  type MessageAssertOptions,\n  type RunEvent,\n} from './types.js';\n"],"mappings":"AAsBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAWK;","names":[]}
+{"version":3,"sources":["../../../src/voice/testing/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Testing utilities for agent evaluation.\n *\n * @example\n * ```typescript\n * import { AgentSession, Agent, voice } from '@livekit/agents';\n *\n * const session = new AgentSession({ llm });\n * await session.start(agent);\n *\n * const result = await session.run({ userInput: 'Hello' });\n * result.expect.nextEvent().isMessage({ role: 'assistant' });\n * result.expect.noMoreEvents();\n * ```\n *\n * @packageDocumentation\n */\n\nexport {\n  AgentHandoffAssert,\n  AssertionError,\n  EventAssert,\n  EventRangeAssert,\n  FunctionCallAssert,\n  FunctionCallOutputAssert,\n  MessageAssert,\n  RunAssert,\n  RunResult,\n} from './run_result.js';\n\nexport {\n  isAgentHandoffEvent,\n  isChatMessageEvent,\n  isFunctionCallEvent,\n  isFunctionCallOutputEvent,\n  type AgentHandoffAssertOptions,\n  type AgentHandoffEvent,\n  type ChatMessageEvent,\n  type EventType,\n  type FunctionCallAssertOptions,\n  type FunctionCallEvent,\n  type FunctionCallOutputAssertOptions,\n  type FunctionCallOutputEvent,\n  type MessageAssertOptions,\n  type RunEvent,\n} from './types.js';\n\nexport { FakeLLM, type FakeLLMResponse } from './fake_llm.js';\n"],"mappings":"AAsBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAWK;AAEP,SAAS,eAAqC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livekit/agents",
-  "version": "1.0.47",
+  "version": "1.0.48",
   "description": "LiveKit Agents - Node.js",
   "main": "dist/index.js",
   "require": "dist/index.cjs",

package/src/beta/index.ts

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+export {
+  TaskGroup,
+  type TaskCompletedEvent,
+  type TaskGroupOptions,
+  type TaskGroupResult,
+} from './workflows/index.js';

package/src/beta/workflows/index.ts

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+export {
+  TaskGroup,
+  type TaskCompletedEvent,
+  type TaskGroupOptions,
+  type TaskGroupResult,
+} from './task_group.js';

package/src/beta/workflows/task_group.ts

@@ -0,0 +1,194 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import type { ChatContext } from '../../llm/chat_context.js';
+import { LLM, ToolError, ToolFlag, tool } from '../../llm/index.js';
+import { AgentTask } from '../../voice/agent.js';
+
+interface FactoryInfo {
+  taskFactory: () => AgentTask;
+  id: string;
+  description: string;
+}
+
+export interface TaskGroupResult {
+  taskResults: Record<string, unknown>;
+}
+
+export interface TaskCompletedEvent {
+  agentTask: AgentTask;
+  taskId: string;
+  result: unknown;
+}
+
+class OutOfScopeError extends ToolError {
+  readonly targetTaskIds: string[];
+
+  constructor(targetTaskIds: string[]) {
+    super('out_of_scope');
+    this.targetTaskIds = targetTaskIds;
+  }
+}
+
+export interface TaskGroupOptions {
+  summarizeChatCtx?: boolean;
+  returnExceptions?: boolean;
+  chatCtx?: ChatContext;
+  onTaskCompleted?: (event: TaskCompletedEvent) => Promise<void>;
+}
+
+export class TaskGroup extends AgentTask<TaskGroupResult> {
+  private _summarizeChatCtx: boolean;
+  private _returnExceptions: boolean;
+  private _visitedTasks = new Set<string>();
+  private _registeredFactories = new Map<string, FactoryInfo>();
+  private _taskCompletedCallback?: (event: TaskCompletedEvent) => Promise<void>;
+  private _currentTask?: AgentTask;
+
+  constructor(options: TaskGroupOptions = {}) {
+    const { summarizeChatCtx = true, returnExceptions = false, chatCtx, onTaskCompleted } = options;
+
+    super({ instructions: '*empty*', chatCtx });
+
+    this._summarizeChatCtx = summarizeChatCtx;
+    this._returnExceptions = returnExceptions;
+    this._taskCompletedCallback = onTaskCompleted;
+  }
+
+  add(task: () => AgentTask, { id, description }: { id: string; description: string }): this {
+    this._registeredFactories.set(id, { taskFactory: task, id, description });
+    return this;
+  }
+
+  async onEnter(): Promise<void> {
+    const taskStack = [...this._registeredFactories.keys()];
+    const taskResults: Record<string, unknown> = {};
+
+    while (taskStack.length > 0) {
+      const taskId = taskStack.shift()!;
+      const factoryInfo = this._registeredFactories.get(taskId)!;
+
+      this._currentTask = factoryInfo.taskFactory();
+
+      const sharedChatCtx = this._chatCtx.copy();
+      await this._currentTask.updateChatCtx(sharedChatCtx);
+
+      const outOfScopeTool = this.buildOutOfScopeTool(taskId);
+      if (outOfScopeTool) {
+        await this._currentTask.updateTools({
+          ...this._currentTask.toolCtx,
+          out_of_scope: outOfScopeTool,
+        });
+      }
+
+      try {
+        this._visitedTasks.add(taskId);
+        const res = await this._currentTask.run();
+        taskResults[taskId] = res;
+
+        if (this._taskCompletedCallback) {
+          await this._taskCompletedCallback({
+            agentTask: this._currentTask,
+            taskId,
+            result: res,
+          });
+        }
+      } catch (e) {
+        if (e instanceof OutOfScopeError) {
+          taskStack.unshift(taskId);
+          for (let i = e.targetTaskIds.length - 1; i >= 0; i--) {
+            taskStack.unshift(e.targetTaskIds[i]!);
+          }
+          continue;
+        }
+
+        if (this._returnExceptions) {
+          taskResults[taskId] = e;
+          continue;
+        } else {
+          this.complete(e instanceof Error ? e : new Error(String(e)));
+          return;
+        }
+      }
+    }
+
+    try {
+      if (this._summarizeChatCtx) {
+        const sessionLlm = this.session.llm;
+        if (!(sessionLlm instanceof LLM)) {
+          throw new Error('summarizeChatCtx requires a standard LLM on the session');
+        }
+
+        // TODO(parity): Add excludeConfigUpdate when AgentConfigUpdate is ported
+        const ctxToSummarize = this._chatCtx.copy({
+          excludeInstructions: true,
+          excludeHandoff: true,
+          excludeEmptyMessage: true,
+          excludeFunctionCall: true,
+        });
+
+        const summarizedChatCtx = await ctxToSummarize._summarize(sessionLlm, {
+          keepLastTurns: 0,
+        });
+        await this.updateChatCtx(summarizedChatCtx);
+      }
+    } catch (e) {
+      this.complete(new Error(`failed to summarize the chat_ctx: ${e}`));
+      return;
+    }
+
+    this.complete({ taskResults });
+  }
+
+  private buildOutOfScopeTool(activeTaskId: string) {
+    if (this._visitedTasks.size === 0) {
+      return undefined;
+    }
+
+    const regressionTaskIds = new Set(this._visitedTasks);
+    regressionTaskIds.delete(activeTaskId);
+
+    if (regressionTaskIds.size === 0) {
+      return undefined;
+    }
+
+    const taskRepr: Record<string, string> = {};
+    for (const [id, info] of this._registeredFactories) {
+      if (regressionTaskIds.has(id)) {
+        taskRepr[id] = info.description;
+      }
+    }
+
+    const taskIdValues = [...regressionTaskIds] as [string, ...string[]];
+
+    const description =
+      'Call to regress to other tasks according to what the user requested to modify, return the corresponding task ids. ' +
+      'For example, if the user wants to change their email and there is a task with id "email_task" with a description of "Collect the user\'s email", return the id ("get_email_task"). ' +
+      'If the user requests to regress to multiple tasks, such as changing their phone number and email, return both task ids in the order they were requested. ' +
+      `The following are the IDs and their corresponding task description. ${JSON.stringify(taskRepr)}`;
+
+    const currentTask = this._currentTask;
+    const registeredFactories = this._registeredFactories;
+    const visitedTasks = this._visitedTasks;
+
+    return tool({
+      description,
+      flags: ToolFlag.IGNORE_ON_ENTER,
+      parameters: z.object({
+        task_ids: z.array(z.enum(taskIdValues)).describe('The IDs of the tasks requested'),
+      }),
+      execute: async ({ task_ids }: { task_ids: string[] }) => {
+        for (const tid of task_ids) {
+          if (!registeredFactories.has(tid) || !visitedTasks.has(tid)) {
+            throw new ToolError(`Unable to regress, invalid task id ${tid}`);
+          }
+        }
+
+        if (currentTask && !currentTask.done) {
+          currentTask.complete(new OutOfScopeError(task_ids));
+        }
+      },
+    });
+  }
+}

package/src/index.ts

@@ -9,6 +9,7 @@
  * @see {@link https://docs.livekit.io/agents/overview | LiveKit Agents documentation}
  * @packageDocumentation
  */
+import * as beta from './beta/index.js';
 import * as cli from './cli.js';
 import * as inference from './inference/index.js';
 import * as ipc from './ipc/index.js';
@@ -37,4 +38,4 @@ export * from './version.js';
 export { createTimedString, isTimedString, type TimedString } from './voice/io.js';
 export * from './worker.js';
 
-export { cli, inference, ipc, llm, metrics, stream, stt, telemetry, tokenize, tts, voice };
+export { beta, cli, inference, ipc, llm, metrics, stream, stt, telemetry, tokenize, tts, voice };

package/src/llm/chat_context.test.ts

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { describe, expect, it } from 'vitest';
+import { initializeLogger } from '../log.js';
+import { FakeLLM } from '../voice/testing/fake_llm.js';
 import {
   type AudioContent,
   ChatContext,
@@ -13,6 +15,8 @@ import {
   ReadonlyChatContext,
 } from './chat_context.js';
 
+initializeLogger({ pretty: false, level: 'error' });
+
 describe('ChatContext.toJSON', () => {
   it('should match snapshot for empty context', () => {
     const context = new ChatContext();
@@ -283,6 +287,50 @@ describe('ChatContext.toJSON', () => {
   });
 });
 
+describe('ChatContext._summarize', () => {
+  it('keeps chronological timestamps with summary + tail', async () => {
+    const ctx = new ChatContext();
+    ctx.addMessage({ role: 'system', content: 'System prompt', createdAt: 0 });
+    ctx.addMessage({ role: 'user', content: 'hello', createdAt: 1000 });
+    ctx.addMessage({ role: 'assistant', content: 'hi there', createdAt: 2000 });
+    ctx.insert(
+      new FunctionCallOutput({
+        callId: 'call_1',
+        name: 'lookup',
+        output: '{"ok":true}',
+        isError: false,
+        createdAt: 3500,
+      }),
+    );
+    ctx.addMessage({ role: 'user', content: 'my color is blue', createdAt: 3000 });
+    ctx.addMessage({ role: 'assistant', content: 'noted', createdAt: 4000 });
+
+    const fake = new FakeLLM([
+      {
+        input: 'Conversation to summarize:\n\nuser: hello\nassistant: hi there',
+        content: 'condensed head',
+      },
+    ]);
+
+    await ctx._summarize(fake, { keepLastTurns: 1 });
+
+    const summary = ctx.items.find(
+      (item) =>
+        item.type === 'message' && item.role === 'assistant' && item.extra?.is_summary === true,
+    );
+    expect(summary).toBeDefined();
+    if (!summary || summary.type !== 'message') {
+      throw new Error('summary message is missing');
+    }
+
+    expect(summary.createdAt).toBeCloseTo(2999.999, 6);
+
+    const createdAts = ctx.items.map((item) => item.createdAt);
+    const sorted = [...createdAts].sort((a, b) => a - b);
+    expect(createdAts).toEqual(sorted);
+  });
+});
+
 describe('ReadonlyChatContext with immutable array', () => {
   it('should have readonly property set to true', () => {
     const items: ChatItem[] = [

package/src/llm/chat_context.ts

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { AudioFrame, VideoFrame } from '@livekit/rtc-node';
 import { createImmutableArray, shortuuid } from '../utils.js';
+import type { LLM } from './llm.js';
 import { type ProviderFormat, toChatCtx } from './provider_format/index.js';
 import type { JSONObject, JSONValue, ToolContext } from './tool_context.js';
 
@@ -95,12 +96,15 @@ export class ChatMessage {
 
   createdAt: number;
 
+  extra: Record<string, unknown>;
+
   constructor(params: {
     role: ChatRole;
     content: ChatContent[] | string;
     id?: string;
     interrupted?: boolean;
     createdAt?: number;
+    extra?: Record<string, unknown>;
   }) {
     const {
       role,
@@ -108,12 +112,14 @@ export class ChatMessage {
       id = shortuuid('item_'),
       interrupted = false,
       createdAt = Date.now(),
+      extra = {},
     } = params;
     this.id = id;
     this.role = role;
     this.content = Array.isArray(content) ? content : [content];
     this.interrupted = interrupted;
     this.createdAt = createdAt;
+    this.extra = extra;
   }
 
   static create(params: {
@@ -122,6 +128,7 @@ export class ChatMessage {
     id?: string;
     interrupted?: boolean;
     createdAt?: number;
+    extra?: Record<string, unknown>;
   }) {
     return new ChatMessage(params);
   }
@@ -401,6 +408,7 @@ export class AgentHandoffItem {
   }
 }
 
+// TODO(parity): Add AgentConfigUpdate type to ChatItem union
 export type ChatItem = ChatMessage | FunctionCall | FunctionCallOutput | AgentHandoffItem;
 
 export class ChatContext {
@@ -431,6 +439,7 @@ export class ChatContext {
     id?: string;
     interrupted?: boolean;
     createdAt?: number;
+    extra?: Record<string, unknown>;
   }): ChatMessage {
     const msg = new ChatMessage(params);
     if (params.createdAt !== undefined) {
@@ -463,11 +472,13 @@ export class ChatContext {
     return idx !== -1 ? idx : undefined;
   }
 
+  // TODO(parity): Add excludeConfigUpdate option when AgentConfigUpdate is ported
   copy(
     options: {
       excludeFunctionCall?: boolean;
       excludeInstructions?: boolean;
       excludeEmptyMessage?: boolean;
+      excludeHandoff?: boolean;
       toolCtx?: ToolContext<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
     } = {},
   ): ChatContext {
@@ -475,6 +486,7 @@ export class ChatContext {
       excludeFunctionCall = false,
       excludeInstructions = false,
       excludeEmptyMessage = false,
+      excludeHandoff = false,
       toolCtx,
     } = options;
     const items: ChatItem[] = [];
@@ -500,6 +512,10 @@ export class ChatContext {
         continue;
       }
 
+      if (excludeHandoff && item.type === 'agent_handoff') {
+        continue;
+      }
+
       if (toolCtx !== undefined && isToolCallOrOutput(item) && toolCtx[item.name] === undefined) {
         continue;
       }
@@ -510,6 +526,7 @@ export class ChatContext {
     return new ChatContext(items);
   }
 
+  // TODO(parity): Add excludeConfigUpdate option when AgentConfigUpdate is ported
   merge(
     other: ChatContext,
     options: {
@@ -762,6 +779,112 @@ export class ChatContext {
     return true;
   }
 
+  async _summarize(llm: LLM, options: { keepLastTurns?: number } = {}): Promise<ChatContext> {
+    const { keepLastTurns = 2 } = options;
+
+    const toSummarize: ChatMessage[] = [];
+    for (const item of this._items) {
+      if (item.type !== 'message') continue;
+      if (item.role !== 'user' && item.role !== 'assistant') continue;
+      if (item.extra?.is_summary === true) continue;
+
+      const text = (item.textContent ?? '').trim();
+      if (text) {
+        toSummarize.push(item);
+      }
+    }
+
+    if (toSummarize.length === 0) {
+      return this;
+    }
+
+    const tailN = Math.max(0, Math.min(toSummarize.length, keepLastTurns * 2));
+    let head: ChatMessage[];
+    let tail: ChatMessage[];
+    if (tailN === 0) {
+      head = toSummarize;
+      tail = [];
+    } else {
+      head = toSummarize.slice(0, -tailN);
+      tail = toSummarize.slice(-tailN);
+    }
+
+    if (head.length === 0) {
+      return this;
+    }
+
+    const sourceText = head
+      .map((m) => `${m.role}: ${(m.textContent ?? '').trim()}`)
+      .join('\n')
+      .trim();
+
+    if (!sourceText) {
+      return this;
+    }
+
+    // TODO: refactor this into LLMStream.collect API.
+    const promptCtx = new ChatContext();
+    promptCtx.addMessage({
+      role: 'system',
+      content:
+        'Compress older chat history into a short, faithful summary.\n' +
+        'Focus on user goals, constraints, decisions, key facts/preferences/entities, and pending tasks.\n' +
+        'Exclude chit-chat and greetings. Be concise.',
+    });
+    promptCtx.addMessage({
+      role: 'user',
+      content: `Conversation to summarize:\n\n${sourceText}`,
+    });
+
+    const chunks: string[] = [];
+    for await (const chunk of llm.chat({ chatCtx: promptCtx })) {
+      if (chunk.delta?.content) {
+        chunks.push(chunk.delta.content);
+      }
+    }
+
+    const summary = chunks.join('').trim();
+    if (!summary) {
+      return this;
+    }
+
+    const tailStartTs = tail.length > 0 ? tail[0]!.createdAt : Infinity;
+
+    const preserved: ChatItem[] = [];
+    for (const it of this._items) {
+      if (
+        (it.type === 'function_call' || it.type === 'function_call_output') &&
+        it.createdAt < tailStartTs
+      ) {
+        continue;
+      }
+
+      if (it.type === 'message' && (it.role === 'user' || it.role === 'assistant')) {
+        continue;
+      }
+
+      preserved.push(it);
+    }
+
+    this._items = preserved;
+
+    const createdAtHint =
+      tail.length > 0 ? tail[0]!.createdAt - 1e-3 : head[head.length - 1]!.createdAt + 1e-3;
+
+    this.addMessage({
+      role: 'assistant',
+      content: `[history summary]\n${summary}`,
+      createdAt: createdAtHint,
+      extra: { is_summary: true },
+    });
+
+    for (const msg of tail) {
+      this.insert(msg);
+    }
+
+    return this;
+  }
+
   /**
    * Indicates whether the context is read-only
    */

package/src/llm/index.ts

@@ -6,6 +6,7 @@ export {
   isFunctionTool,
   tool,
   ToolError,
+  ToolFlag,
   type AgentHandoff,
   type FunctionTool,
   type ProviderDefinedTool,

package/src/llm/tool_context.ts

@@ -80,6 +80,13 @@ export class ToolError extends Error {
   }
 }
 
+export const ToolFlag = {
+  NONE: 0,
+  IGNORE_ON_ENTER: 1 << 0,
+} as const;
+
+export type ToolFlag = (typeof ToolFlag)[keyof typeof ToolFlag];
+
 export interface AgentHandoff {
   /**
    * The agent to handoff to.
@@ -178,6 +185,8 @@ export interface FunctionTool<
    */
   execute: ToolExecuteFunction<Parameters, UserData, Result>;
 
+  flags: number;
+
   [FUNCTION_TOOL_SYMBOL]: true;
 }
 
@@ -242,10 +251,12 @@ export function tool<
   description,
   parameters,
   execute,
+  flags,
 }: {
   description: string;
   parameters: Schema;
   execute: ToolExecuteFunction<InferToolInput<Schema>, UserData, Result>;
+  flags?: number;
 }): FunctionTool<InferToolInput<Schema>, UserData, Result>;
 
 /**
@@ -254,10 +265,12 @@ export function tool<
 export function tool<UserData = UnknownUserData, Result = unknown>({
   description,
   execute,
+  flags,
 }: {
   description: string;
   parameters?: never;
   execute: ToolExecuteFunction<Record<string, never>, UserData, Result>;
+  flags?: number;
 }): FunctionTool<Record<string, never>, UserData, Result>;
 
 /**
@@ -295,6 +308,7 @@ export function tool(tool: any): any {
       description: tool.description,
       parameters,
       execute: tool.execute,
+      flags: tool.flags ?? ToolFlag.NONE,
       [TOOL_SYMBOL]: true,
       [FUNCTION_TOOL_SYMBOL]: true,
     };