@livekit/agents 1.1.0 → 1.2.0

package/dist/audio.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,16 +17,30 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var audio_exports = {};
 __export(audio_exports, {
   AudioByteStream: () => AudioByteStream,
-  calculateAudioDuration: () => calculateAudioDuration
+  audioFramesFromFile: () => audioFramesFromFile,
+  calculateAudioDurationSeconds: () => calculateAudioDurationSeconds,
+  loopAudioFramesFromFile: () => loopAudioFramesFromFile
 });
 module.exports = __toCommonJS(audio_exports);
+var import_ffmpeg = __toESM(require("@ffmpeg-installer/ffmpeg"), 1);
 var import_rtc_node = require("@livekit/rtc-node");
+var import_fluent_ffmpeg = __toESM(require("fluent-ffmpeg"), 1);
 var import_log = require("./log.cjs");
-function calculateAudioDuration(frame) {
+var import_stream_channel = require("./stream/stream_channel.cjs");
+import_fluent_ffmpeg.default.setFfmpegPath(import_ffmpeg.default.path);
+function calculateAudioDurationSeconds(frame) {
   return Array.isArray(frame) ? frame.reduce((sum, a) => sum + a.samplesPerChannel / a.sampleRate, 0) : frame.samplesPerChannel / frame.sampleRate;
 }
 class AudioByteStream {
@@ -76,9 +92,79 @@ class AudioByteStream {
     return frames;
   }
 }
+function audioFramesFromFile(filePath, options = {}) {
+  var _a;
+  const sampleRate = options.sampleRate ?? 48e3;
+  const numChannels = options.numChannels ?? 1;
+  const audioStream = new AudioByteStream(sampleRate, numChannels);
+  const channel = (0, import_stream_channel.createStreamChannel)();
+  const logger = (0, import_log.log)();
+  const command = (0, import_fluent_ffmpeg.default)(filePath).inputOptions([
+    "-probesize",
+    "32",
+    "-analyzeduration",
+    "0",
+    "-fflags",
+    "+nobuffer+flush_packets",
+    "-flags",
+    "low_delay"
+  ]).format("s16le").audioChannels(numChannels).audioFrequency(sampleRate);
+  let commandRunning = true;
+  const onClose = () => {
+    logger.debug("Audio file playback aborted");
+    channel.close();
+    if (commandRunning) {
+      commandRunning = false;
+      command.kill("SIGKILL");
+    }
+  };
+  const outputStream = command.pipe();
+  (_a = options.abortSignal) == null ? void 0 : _a.addEventListener("abort", onClose, { once: true });
+  outputStream.on("data", (chunk) => {
+    const arrayBuffer = chunk.buffer.slice(
+      chunk.byteOffset,
+      chunk.byteOffset + chunk.byteLength
+    );
+    const frames = audioStream.write(arrayBuffer);
+    for (const frame of frames) {
+      channel.write(frame);
+    }
+  });
+  outputStream.on("end", () => {
+    const frames = audioStream.flush();
+    for (const frame of frames) {
+      channel.write(frame);
+    }
+    commandRunning = false;
+    channel.close();
+  });
+  outputStream.on("error", (err) => {
+    logger.error(err);
+    commandRunning = false;
+    onClose();
+  });
+  return channel.stream();
+}
+async function* loopAudioFramesFromFile(filePath, options = {}) {
+  var _a;
+  const frames = [];
+  const logger = (0, import_log.log)();
+  for await (const frame of audioFramesFromFile(filePath, options)) {
+    frames.push(frame);
+    yield frame;
+  }
+  while (!((_a = options.abortSignal) == null ? void 0 : _a.aborted)) {
+    for (const frame of frames) {
+      yield frame;
+    }
+  }
+  logger.debug("Audio file playback loop finished");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AudioByteStream,
-  calculateAudioDuration
+  audioFramesFromFile,
+  calculateAudioDurationSeconds,
+  loopAudioFramesFromFile
 });
 //# sourceMappingURL=audio.cjs.map

package/dist/audio.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/audio.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { AudioFrame } from '@livekit/rtc-node';\nimport { log } from './log.js';\nimport type { AudioBuffer } from './utils.js';\n\nexport function calculateAudioDuration(frame: AudioBuffer) {\n  // TODO(AJS-102): use frame.durationMs once available in rtc-node\n  return Array.isArray(frame)\n    ? frame.reduce((sum, a) => sum + a.samplesPerChannel / a.sampleRate, 0)\n    : frame.samplesPerChannel / frame.sampleRate;\n}\n\n/** AudioByteStream translates between LiveKit AudioFrame packets and raw byte data. */\nexport class AudioByteStream {\n  #sampleRate: number;\n  #numChannels: number;\n  #bytesPerFrame: number;\n  #buf: Int8Array;\n  #logger = log();\n\n  constructor(sampleRate: number, numChannels: number, samplesPerChannel: number | null = null) {\n    this.#sampleRate = sampleRate;\n    this.#numChannels = numChannels;\n\n    if (samplesPerChannel === null) {\n      samplesPerChannel = Math.floor(sampleRate / 10); // 100ms by default\n    }\n\n    this.#bytesPerFrame = numChannels * samplesPerChannel * 2; // 2 bytes per sample (Int16)\n    this.#buf = new Int8Array();\n  }\n\n  write(data: ArrayBuffer): AudioFrame[] {\n    this.#buf = new Int8Array([...this.#buf, ...new Int8Array(data)]);\n\n    const frames: AudioFrame[] = [];\n    while (this.#buf.length >= this.#bytesPerFrame) {\n      const frameData = this.#buf.slice(0, this.#bytesPerFrame);\n      this.#buf = this.#buf.slice(this.#bytesPerFrame);\n\n      frames.push(\n        new AudioFrame(\n          new Int16Array(frameData.buffer),\n          this.#sampleRate,\n          this.#numChannels,\n          frameData.length / 2,\n        ),\n      );\n    }\n\n    return frames;\n  }\n\n  flush(): AudioFrame[] {\n    if (this.#buf.length % (2 * this.#numChannels) !== 0) {\n      this.#logger.warn('AudioByteStream: incomplete frame during flush, dropping');\n      return [];\n    }\n\n    const frames = [\n      new AudioFrame(\n        new Int16Array(this.#buf.buffer),\n        this.#sampleRate,\n        this.#numChannels,\n        this.#buf.length / 2,\n      ),\n    ];\n\n    this.#buf = new Int8Array(); // Clear buffer after flushing\n    return frames;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,sBAA2B;AAC3B,iBAAoB;AAGb,SAAS,uBAAuB,OAAoB;AAEzD,SAAO,MAAM,QAAQ,KAAK,IACtB,MAAM,OAAO,CAAC,KAAK,MAAM,MAAM,EAAE,oBAAoB,EAAE,YAAY,CAAC,IACpE,MAAM,oBAAoB,MAAM;AACtC;AAGO,MAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,cAAU,gBAAI;AAAA,EAEd,YAAY,YAAoB,aAAqB,oBAAmC,MAAM;AAC5F,SAAK,cAAc;AACnB,SAAK,eAAe;AAEpB,QAAI,sBAAsB,MAAM;AAC9B,0BAAoB,KAAK,MAAM,aAAa,EAAE;AAAA,IAChD;AAEA,SAAK,iBAAiB,cAAc,oBAAoB;AACxD,SAAK,OAAO,IAAI,UAAU;AAAA,EAC5B;AAAA,EAEA,MAAM,MAAiC;AACrC,SAAK,OAAO,IAAI,UAAU,CAAC,GAAG,KAAK,MAAM,GAAG,IAAI,UAAU,IAAI,CAAC,CAAC;AAEhE,UAAM,SAAuB,CAAC;AAC9B,WAAO,KAAK,KAAK,UAAU,KAAK,gBAAgB;AAC9C,YAAM,YAAY,KAAK,KAAK,MAAM,GAAG,KAAK,cAAc;AACxD,WAAK,OAAO,KAAK,KAAK,MAAM,KAAK,cAAc;AAE/C,aAAO;AAAA,QACL,IAAI;AAAA,UACF,IAAI,WAAW,UAAU,MAAM;AAAA,UAC/B,KAAK;AAAA,UACL,KAAK;AAAA,UACL,UAAU,SAAS;AAAA,QACrB;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA,EAEA,QAAsB;AACpB,QAAI,KAAK,KAAK,UAAU,IAAI,KAAK,kBAAkB,GAAG;AACpD,WAAK,QAAQ,KAAK,0DAA0D;AAC5E,aAAO,CAAC;AAAA,IACV;AAEA,UAAM,SAAS;AAAA,MACb,IAAI;AAAA,QACF,IAAI,WAAW,KAAK,KAAK,MAAM;AAAA,QAC/B,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK,KAAK,SAAS;AAAA,MACrB;AAAA,IACF;AAEA,SAAK,OAAO,IAAI,UAAU;AAC1B,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../src/audio.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport ffmpegInstaller from '@ffmpeg-installer/ffmpeg';\nimport { AudioFrame } from '@livekit/rtc-node';\nimport ffmpeg from 'fluent-ffmpeg';\nimport type { ReadableStream } from 'node:stream/web';\nimport { log } from './log.js';\nimport { createStreamChannel } from './stream/stream_channel.js';\nimport type { AudioBuffer } from './utils.js';\n\nffmpeg.setFfmpegPath(ffmpegInstaller.path);\n\nexport interface AudioDecodeOptions {\n  sampleRate?: number;\n  numChannels?: number;\n  /**\n   * Audio format hint (e.g., 'mp3', 'ogg', 'wav', 'opus')\n   * If not provided, FFmpeg will auto-detect\n   */\n  format?: string;\n  abortSignal?: AbortSignal;\n}\n\nexport function calculateAudioDurationSeconds(frame: AudioBuffer) {\n  // TODO(AJS-102): use frame.durationMs once available in rtc-node\n  return Array.isArray(frame)\n    ? frame.reduce((sum, a) => sum + a.samplesPerChannel / a.sampleRate, 0)\n    : frame.samplesPerChannel / frame.sampleRate;\n}\n\n/** AudioByteStream translates between LiveKit AudioFrame packets and raw byte data. */\nexport class AudioByteStream {\n  #sampleRate: number;\n  #numChannels: number;\n  #bytesPerFrame: number;\n  #buf: Int8Array;\n  #logger = log();\n\n  constructor(sampleRate: number, numChannels: number, samplesPerChannel: number | null = null) {\n    this.#sampleRate = sampleRate;\n    this.#numChannels = numChannels;\n\n    if (samplesPerChannel === null) {\n      samplesPerChannel = Math.floor(sampleRate / 10); // 100ms by default\n    }\n\n    this.#bytesPerFrame = numChannels * samplesPerChannel * 2; // 2 bytes per sample (Int16)\n    this.#buf = new Int8Array();\n  }\n\n  write(data: ArrayBuffer): AudioFrame[] {\n    this.#buf = new Int8Array([...this.#buf, ...new Int8Array(data)]);\n\n    const frames: AudioFrame[] = [];\n    while (this.#buf.length >= this.#bytesPerFrame) {\n      const frameData = this.#buf.slice(0, this.#bytesPerFrame);\n      this.#buf = this.#buf.slice(this.#bytesPerFrame);\n\n      frames.push(\n        new AudioFrame(\n          new Int16Array(frameData.buffer),\n          this.#sampleRate,\n          this.#numChannels,\n          frameData.length / 2,\n        ),\n      );\n    }\n\n    return frames;\n  }\n\n  flush(): AudioFrame[] {\n    if (this.#buf.length % (2 * this.#numChannels) !== 0) {\n      this.#logger.warn('AudioByteStream: incomplete frame during flush, dropping');\n      return [];\n    }\n\n    const frames = [\n      new AudioFrame(\n        new Int16Array(this.#buf.buffer),\n        this.#sampleRate,\n        this.#numChannels,\n        this.#buf.length / 2,\n      ),\n    ];\n\n    this.#buf = new Int8Array(); // Clear buffer after flushing\n    return frames;\n  }\n}\n\n/**\n * Decode an audio file into AudioFrame instances\n *\n * @param filePath - Path to the audio file\n * @param options - Decoding options\n * @returns AsyncGenerator that yields AudioFrame objects\n *\n * @example\n * ```typescript\n * for await (const frame of audioFramesFromFile('audio.ogg', { sampleRate: 48000 })) {\n *   console.log('Frame:', frame.samplesPerChannel, 'samples');\n * }\n * ```\n */\nexport function audioFramesFromFile(\n  filePath: string,\n  options: AudioDecodeOptions = {},\n): ReadableStream<AudioFrame> {\n  const sampleRate = options.sampleRate ?? 48000;\n  const numChannels = options.numChannels ?? 1;\n\n  const audioStream = new AudioByteStream(sampleRate, numChannels);\n  const channel = createStreamChannel<AudioFrame>();\n  const logger = log();\n\n  // TODO (Brian): decode WAV using a custom decoder instead of FFmpeg\n  const command = ffmpeg(filePath)\n    .inputOptions([\n      '-probesize',\n      '32',\n      '-analyzeduration',\n      '0',\n      '-fflags',\n      '+nobuffer+flush_packets',\n      '-flags',\n      'low_delay',\n    ])\n    .format('s16le') // signed 16-bit little-endian PCM to be consistent cross-platform\n    .audioChannels(numChannels)\n    .audioFrequency(sampleRate);\n\n  let commandRunning = true;\n\n  const onClose = () => {\n    logger.debug('Audio file playback aborted');\n\n    channel.close();\n    if (commandRunning) {\n      commandRunning = false;\n      command.kill('SIGKILL');\n    }\n  };\n\n  const outputStream = command.pipe();\n  options.abortSignal?.addEventListener('abort', onClose, { once: true });\n\n  outputStream.on('data', (chunk: Buffer) => {\n    const arrayBuffer = chunk.buffer.slice(\n      chunk.byteOffset,\n      chunk.byteOffset + chunk.byteLength,\n    ) as ArrayBuffer;\n\n    const frames = audioStream.write(arrayBuffer);\n    for (const frame of frames) {\n      channel.write(frame);\n    }\n  });\n\n  outputStream.on('end', () => {\n    const frames = audioStream.flush();\n    for (const frame of frames) {\n      channel.write(frame);\n    }\n    commandRunning = false;\n    channel.close();\n  });\n\n  outputStream.on('error', (err: Error) => {\n    logger.error(err);\n    commandRunning = false;\n    onClose();\n  });\n\n  return channel.stream();\n}\n\n/**\n * Loop audio frames from a file indefinitely\n *\n * @param filePath - Path to the audio file\n * @param options - Decoding options\n * @returns AsyncGenerator that yields AudioFrame objects in an infinite loop\n */\nexport async function* loopAudioFramesFromFile(\n  filePath: string,\n  options: AudioDecodeOptions = {},\n): AsyncGenerator<AudioFrame, void, unknown> {\n  const frames: AudioFrame[] = [];\n  const logger = log();\n\n  for await (const frame of audioFramesFromFile(filePath, options)) {\n    frames.push(frame);\n    yield frame;\n  }\n\n  while (!options.abortSignal?.aborted) {\n    for (const frame of frames) {\n      yield frame;\n    }\n  }\n\n  logger.debug('Audio file playback loop finished');\n}\n"],"mappings":"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","names":["ffmpeg","ffmpegInstaller"]}

package/dist/audio.d.cts

@@ -1,6 +1,18 @@
+/// <reference types="node" resolution-mode="require"/>
 import { AudioFrame } from '@livekit/rtc-node';
+import type { ReadableStream } from 'node:stream/web';
 import type { AudioBuffer } from './utils.js';
-export declare function calculateAudioDuration(frame: AudioBuffer): number;
+export interface AudioDecodeOptions {
+    sampleRate?: number;
+    numChannels?: number;
+    /**
+     * Audio format hint (e.g., 'mp3', 'ogg', 'wav', 'opus')
+     * If not provided, FFmpeg will auto-detect
+     */
+    format?: string;
+    abortSignal?: AbortSignal;
+}
+export declare function calculateAudioDurationSeconds(frame: AudioBuffer): number;
 /** AudioByteStream translates between LiveKit AudioFrame packets and raw byte data. */
 export declare class AudioByteStream {
     #private;
@@ -8,4 +20,27 @@ export declare class AudioByteStream {
     write(data: ArrayBuffer): AudioFrame[];
     flush(): AudioFrame[];
 }
+/**
+ * Decode an audio file into AudioFrame instances
+ *
+ * @param filePath - Path to the audio file
+ * @param options - Decoding options
+ * @returns AsyncGenerator that yields AudioFrame objects
+ *
+ * @example
+ * ```typescript
+ * for await (const frame of audioFramesFromFile('audio.ogg', { sampleRate: 48000 })) {
+ *   console.log('Frame:', frame.samplesPerChannel, 'samples');
+ * }
+ * ```
+ */
+export declare function audioFramesFromFile(filePath: string, options?: AudioDecodeOptions): ReadableStream<AudioFrame>;
+/**
+ * Loop audio frames from a file indefinitely
+ *
+ * @param filePath - Path to the audio file
+ * @param options - Decoding options
+ * @returns AsyncGenerator that yields AudioFrame objects in an infinite loop
+ */
+export declare function loopAudioFramesFromFile(filePath: string, options?: AudioDecodeOptions): AsyncGenerator<AudioFrame, void, unknown>;
 //# sourceMappingURL=audio.d.ts.map

package/dist/audio.d.ts

@@ -1,6 +1,18 @@
+/// <reference types="node" resolution-mode="require"/>
 import { AudioFrame } from '@livekit/rtc-node';
+import type { ReadableStream } from 'node:stream/web';
 import type { AudioBuffer } from './utils.js';
-export declare function calculateAudioDuration(frame: AudioBuffer): number;
+export interface AudioDecodeOptions {
+    sampleRate?: number;
+    numChannels?: number;
+    /**
+     * Audio format hint (e.g., 'mp3', 'ogg', 'wav', 'opus')
+     * If not provided, FFmpeg will auto-detect
+     */
+    format?: string;
+    abortSignal?: AbortSignal;
+}
+export declare function calculateAudioDurationSeconds(frame: AudioBuffer): number;
 /** AudioByteStream translates between LiveKit AudioFrame packets and raw byte data. */
 export declare class AudioByteStream {
     #private;
@@ -8,4 +20,27 @@ export declare class AudioByteStream {
     write(data: ArrayBuffer): AudioFrame[];
     flush(): AudioFrame[];
 }
+/**
+ * Decode an audio file into AudioFrame instances
+ *
+ * @param filePath - Path to the audio file
+ * @param options - Decoding options
+ * @returns AsyncGenerator that yields AudioFrame objects
+ *
+ * @example
+ * ```typescript
+ * for await (const frame of audioFramesFromFile('audio.ogg', { sampleRate: 48000 })) {
+ *   console.log('Frame:', frame.samplesPerChannel, 'samples');
+ * }
+ * ```
+ */
+export declare function audioFramesFromFile(filePath: string, options?: AudioDecodeOptions): ReadableStream<AudioFrame>;
+/**
+ * Loop audio frames from a file indefinitely
+ *
+ * @param filePath - Path to the audio file
+ * @param options - Decoding options
+ * @returns AsyncGenerator that yields AudioFrame objects in an infinite loop
+ */
+export declare function loopAudioFramesFromFile(filePath: string, options?: AudioDecodeOptions): AsyncGenerator<AudioFrame, void, unknown>;
 //# sourceMappingURL=audio.d.ts.map

package/dist/audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,UAKxD;AAED,uFAAuF;AACvF,qBAAa,eAAe;;gBAOd,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAM,GAAG,IAAW;IAY5F,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE;IAqBtC,KAAK,IAAI,UAAU,EAAE;CAkBtB"}
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,WAAW,UAK/D;AAED,uFAAuF;AACvF,qBAAa,eAAe;;gBAOd,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAM,GAAG,IAAW;IAY5F,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE;IAqBtC,KAAK,IAAI,UAAU,EAAE;CAkBtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CAAC,UAAU,CAAC,CAmE5B;AAED;;;;;;GAMG;AACH,wBAAuB,uBAAuB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAgB3C"}

package/dist/audio.js

@@ -1,6 +1,10 @@
+import ffmpegInstaller from "@ffmpeg-installer/ffmpeg";
 import { AudioFrame } from "@livekit/rtc-node";
+import ffmpeg from "fluent-ffmpeg";
 import { log } from "./log.js";
-function calculateAudioDuration(frame) {
+import { createStreamChannel } from "./stream/stream_channel.js";
+ffmpeg.setFfmpegPath(ffmpegInstaller.path);
+function calculateAudioDurationSeconds(frame) {
   return Array.isArray(frame) ? frame.reduce((sum, a) => sum + a.samplesPerChannel / a.sampleRate, 0) : frame.samplesPerChannel / frame.sampleRate;
 }
 class AudioByteStream {
@@ -52,8 +56,78 @@ class AudioByteStream {
     return frames;
   }
 }
+function audioFramesFromFile(filePath, options = {}) {
+  var _a;
+  const sampleRate = options.sampleRate ?? 48e3;
+  const numChannels = options.numChannels ?? 1;
+  const audioStream = new AudioByteStream(sampleRate, numChannels);
+  const channel = createStreamChannel();
+  const logger = log();
+  const command = ffmpeg(filePath).inputOptions([
+    "-probesize",
+    "32",
+    "-analyzeduration",
+    "0",
+    "-fflags",
+    "+nobuffer+flush_packets",
+    "-flags",
+    "low_delay"
+  ]).format("s16le").audioChannels(numChannels).audioFrequency(sampleRate);
+  let commandRunning = true;
+  const onClose = () => {
+    logger.debug("Audio file playback aborted");
+    channel.close();
+    if (commandRunning) {
+      commandRunning = false;
+      command.kill("SIGKILL");
+    }
+  };
+  const outputStream = command.pipe();
+  (_a = options.abortSignal) == null ? void 0 : _a.addEventListener("abort", onClose, { once: true });
+  outputStream.on("data", (chunk) => {
+    const arrayBuffer = chunk.buffer.slice(
+      chunk.byteOffset,
+      chunk.byteOffset + chunk.byteLength
+    );
+    const frames = audioStream.write(arrayBuffer);
+    for (const frame of frames) {
+      channel.write(frame);
+    }
+  });
+  outputStream.on("end", () => {
+    const frames = audioStream.flush();
+    for (const frame of frames) {
+      channel.write(frame);
+    }
+    commandRunning = false;
+    channel.close();
+  });
+  outputStream.on("error", (err) => {
+    logger.error(err);
+    commandRunning = false;
+    onClose();
+  });
+  return channel.stream();
+}
+async function* loopAudioFramesFromFile(filePath, options = {}) {
+  var _a;
+  const frames = [];
+  const logger = log();
+  for await (const frame of audioFramesFromFile(filePath, options)) {
+    frames.push(frame);
+    yield frame;
+  }
+  while (!((_a = options.abortSignal) == null ? void 0 : _a.aborted)) {
+    for (const frame of frames) {
+      yield frame;
+    }
+  }
+  logger.debug("Audio file playback loop finished");
+}
 export {
   AudioByteStream,
-  calculateAudioDuration
+  audioFramesFromFile,
+  calculateAudioDurationSeconds,
+  loopAudioFramesFromFile
 };
 //# sourceMappingURL=audio.js.map

package/dist/audio.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/audio.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { AudioFrame } from '@livekit/rtc-node';\nimport { log } from './log.js';\nimport type { AudioBuffer } from './utils.js';\n\nexport function calculateAudioDuration(frame: AudioBuffer) {\n  // TODO(AJS-102): use frame.durationMs once available in rtc-node\n  return Array.isArray(frame)\n    ? frame.reduce((sum, a) => sum + a.samplesPerChannel / a.sampleRate, 0)\n    : frame.samplesPerChannel / frame.sampleRate;\n}\n\n/** AudioByteStream translates between LiveKit AudioFrame packets and raw byte data. */\nexport class AudioByteStream {\n  #sampleRate: number;\n  #numChannels: number;\n  #bytesPerFrame: number;\n  #buf: Int8Array;\n  #logger = log();\n\n  constructor(sampleRate: number, numChannels: number, samplesPerChannel: number | null = null) {\n    this.#sampleRate = sampleRate;\n    this.#numChannels = numChannels;\n\n    if (samplesPerChannel === null) {\n      samplesPerChannel = Math.floor(sampleRate / 10); // 100ms by default\n    }\n\n    this.#bytesPerFrame = numChannels * samplesPerChannel * 2; // 2 bytes per sample (Int16)\n    this.#buf = new Int8Array();\n  }\n\n  write(data: ArrayBuffer): AudioFrame[] {\n    this.#buf = new Int8Array([...this.#buf, ...new Int8Array(data)]);\n\n    const frames: AudioFrame[] = [];\n    while (this.#buf.length >= this.#bytesPerFrame) {\n      const frameData = this.#buf.slice(0, this.#bytesPerFrame);\n      this.#buf = this.#buf.slice(this.#bytesPerFrame);\n\n      frames.push(\n        new AudioFrame(\n          new Int16Array(frameData.buffer),\n          this.#sampleRate,\n          this.#numChannels,\n          frameData.length / 2,\n        ),\n      );\n    }\n\n    return frames;\n  }\n\n  flush(): AudioFrame[] {\n    if (this.#buf.length % (2 * this.#numChannels) !== 0) {\n      this.#logger.warn('AudioByteStream: incomplete frame during flush, dropping');\n      return [];\n    }\n\n    const frames = [\n      new AudioFrame(\n        new Int16Array(this.#buf.buffer),\n        this.#sampleRate,\n        this.#numChannels,\n        this.#buf.length / 2,\n      ),\n    ];\n\n    this.#buf = new Int8Array(); // Clear buffer after flushing\n    return frames;\n  }\n}\n"],"mappings":"AAGA,SAAS,kBAAkB;AAC3B,SAAS,WAAW;AAGb,SAAS,uBAAuB,OAAoB;AAEzD,SAAO,MAAM,QAAQ,KAAK,IACtB,MAAM,OAAO,CAAC,KAAK,MAAM,MAAM,EAAE,oBAAoB,EAAE,YAAY,CAAC,IACpE,MAAM,oBAAoB,MAAM;AACtC;AAGO,MAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU,IAAI;AAAA,EAEd,YAAY,YAAoB,aAAqB,oBAAmC,MAAM;AAC5F,SAAK,cAAc;AACnB,SAAK,eAAe;AAEpB,QAAI,sBAAsB,MAAM;AAC9B,0BAAoB,KAAK,MAAM,aAAa,EAAE;AAAA,IAChD;AAEA,SAAK,iBAAiB,cAAc,oBAAoB;AACxD,SAAK,OAAO,IAAI,UAAU;AAAA,EAC5B;AAAA,EAEA,MAAM,MAAiC;AACrC,SAAK,OAAO,IAAI,UAAU,CAAC,GAAG,KAAK,MAAM,GAAG,IAAI,UAAU,IAAI,CAAC,CAAC;AAEhE,UAAM,SAAuB,CAAC;AAC9B,WAAO,KAAK,KAAK,UAAU,KAAK,gBAAgB;AAC9C,YAAM,YAAY,KAAK,KAAK,MAAM,GAAG,KAAK,cAAc;AACxD,WAAK,OAAO,KAAK,KAAK,MAAM,KAAK,cAAc;AAE/C,aAAO;AAAA,QACL,IAAI;AAAA,UACF,IAAI,WAAW,UAAU,MAAM;AAAA,UAC/B,KAAK;AAAA,UACL,KAAK;AAAA,UACL,UAAU,SAAS;AAAA,QACrB;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA,EAEA,QAAsB;AACpB,QAAI,KAAK,KAAK,UAAU,IAAI,KAAK,kBAAkB,GAAG;AACpD,WAAK,QAAQ,KAAK,0DAA0D;AAC5E,aAAO,CAAC;AAAA,IACV;AAEA,UAAM,SAAS;AAAA,MACb,IAAI;AAAA,QACF,IAAI,WAAW,KAAK,KAAK,MAAM;AAAA,QAC/B,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK,KAAK,SAAS;AAAA,MACrB;AAAA,IACF;AAEA,SAAK,OAAO,IAAI,UAAU;AAC1B,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../src/audio.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport ffmpegInstaller from '@ffmpeg-installer/ffmpeg';\nimport { AudioFrame } from '@livekit/rtc-node';\nimport ffmpeg from 'fluent-ffmpeg';\nimport type { ReadableStream } from 'node:stream/web';\nimport { log } from './log.js';\nimport { createStreamChannel } from './stream/stream_channel.js';\nimport type { AudioBuffer } from './utils.js';\n\nffmpeg.setFfmpegPath(ffmpegInstaller.path);\n\nexport interface AudioDecodeOptions {\n  sampleRate?: number;\n  numChannels?: number;\n  /**\n   * Audio format hint (e.g., 'mp3', 'ogg', 'wav', 'opus')\n   * If not provided, FFmpeg will auto-detect\n   */\n  format?: string;\n  abortSignal?: AbortSignal;\n}\n\nexport function calculateAudioDurationSeconds(frame: AudioBuffer) {\n  // TODO(AJS-102): use frame.durationMs once available in rtc-node\n  return Array.isArray(frame)\n    ? frame.reduce((sum, a) => sum + a.samplesPerChannel / a.sampleRate, 0)\n    : frame.samplesPerChannel / frame.sampleRate;\n}\n\n/** AudioByteStream translates between LiveKit AudioFrame packets and raw byte data. */\nexport class AudioByteStream {\n  #sampleRate: number;\n  #numChannels: number;\n  #bytesPerFrame: number;\n  #buf: Int8Array;\n  #logger = log();\n\n  constructor(sampleRate: number, numChannels: number, samplesPerChannel: number | null = null) {\n    this.#sampleRate = sampleRate;\n    this.#numChannels = numChannels;\n\n    if (samplesPerChannel === null) {\n      samplesPerChannel = Math.floor(sampleRate / 10); // 100ms by default\n    }\n\n    this.#bytesPerFrame = numChannels * samplesPerChannel * 2; // 2 bytes per sample (Int16)\n    this.#buf = new Int8Array();\n  }\n\n  write(data: ArrayBuffer): AudioFrame[] {\n    this.#buf = new Int8Array([...this.#buf, ...new Int8Array(data)]);\n\n    const frames: AudioFrame[] = [];\n    while (this.#buf.length >= this.#bytesPerFrame) {\n      const frameData = this.#buf.slice(0, this.#bytesPerFrame);\n      this.#buf = this.#buf.slice(this.#bytesPerFrame);\n\n      frames.push(\n        new AudioFrame(\n          new Int16Array(frameData.buffer),\n          this.#sampleRate,\n          this.#numChannels,\n          frameData.length / 2,\n        ),\n      );\n    }\n\n    return frames;\n  }\n\n  flush(): AudioFrame[] {\n    if (this.#buf.length % (2 * this.#numChannels) !== 0) {\n      this.#logger.warn('AudioByteStream: incomplete frame during flush, dropping');\n      return [];\n    }\n\n    const frames = [\n      new AudioFrame(\n        new Int16Array(this.#buf.buffer),\n        this.#sampleRate,\n        this.#numChannels,\n        this.#buf.length / 2,\n      ),\n    ];\n\n    this.#buf = new Int8Array(); // Clear buffer after flushing\n    return frames;\n  }\n}\n\n/**\n * Decode an audio file into AudioFrame instances\n *\n * @param filePath - Path to the audio file\n * @param options - Decoding options\n * @returns AsyncGenerator that yields AudioFrame objects\n *\n * @example\n * ```typescript\n * for await (const frame of audioFramesFromFile('audio.ogg', { sampleRate: 48000 })) {\n *   console.log('Frame:', frame.samplesPerChannel, 'samples');\n * }\n * ```\n */\nexport function audioFramesFromFile(\n  filePath: string,\n  options: AudioDecodeOptions = {},\n): ReadableStream<AudioFrame> {\n  const sampleRate = options.sampleRate ?? 48000;\n  const numChannels = options.numChannels ?? 1;\n\n  const audioStream = new AudioByteStream(sampleRate, numChannels);\n  const channel = createStreamChannel<AudioFrame>();\n  const logger = log();\n\n  // TODO (Brian): decode WAV using a custom decoder instead of FFmpeg\n  const command = ffmpeg(filePath)\n    .inputOptions([\n      '-probesize',\n      '32',\n      '-analyzeduration',\n      '0',\n      '-fflags',\n      '+nobuffer+flush_packets',\n      '-flags',\n      'low_delay',\n    ])\n    .format('s16le') // signed 16-bit little-endian PCM to be consistent cross-platform\n    .audioChannels(numChannels)\n    .audioFrequency(sampleRate);\n\n  let commandRunning = true;\n\n  const onClose = () => {\n    logger.debug('Audio file playback aborted');\n\n    channel.close();\n    if (commandRunning) {\n      commandRunning = false;\n      command.kill('SIGKILL');\n    }\n  };\n\n  const outputStream = command.pipe();\n  options.abortSignal?.addEventListener('abort', onClose, { once: true });\n\n  outputStream.on('data', (chunk: Buffer) => {\n    const arrayBuffer = chunk.buffer.slice(\n      chunk.byteOffset,\n      chunk.byteOffset + chunk.byteLength,\n    ) as ArrayBuffer;\n\n    const frames = audioStream.write(arrayBuffer);\n    for (const frame of frames) {\n      channel.write(frame);\n    }\n  });\n\n  outputStream.on('end', () => {\n    const frames = audioStream.flush();\n    for (const frame of frames) {\n      channel.write(frame);\n    }\n    commandRunning = false;\n    channel.close();\n  });\n\n  outputStream.on('error', (err: Error) => {\n    logger.error(err);\n    commandRunning = false;\n    onClose();\n  });\n\n  return channel.stream();\n}\n\n/**\n * Loop audio frames from a file indefinitely\n *\n * @param filePath - Path to the audio file\n * @param options - Decoding options\n * @returns AsyncGenerator that yields AudioFrame objects in an infinite loop\n */\nexport async function* loopAudioFramesFromFile(\n  filePath: string,\n  options: AudioDecodeOptions = {},\n): AsyncGenerator<AudioFrame, void, unknown> {\n  const frames: AudioFrame[] = [];\n  const logger = log();\n\n  for await (const frame of audioFramesFromFile(filePath, options)) {\n    frames.push(frame);\n    yield frame;\n  }\n\n  while (!options.abortSignal?.aborted) {\n    for (const frame of frames) {\n      yield frame;\n    }\n  }\n\n  logger.debug('Audio file playback loop finished');\n}\n"],"mappings":"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","names":[]}

package/dist/beta/index.cjs

@@ -0,0 +1,29 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var beta_exports = {};
+__export(beta_exports, {
+  TaskGroup: () => import_workflows.TaskGroup
+});
+module.exports = __toCommonJS(beta_exports);
+var import_workflows = require("./workflows/index.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TaskGroup
+});
+//# sourceMappingURL=index.cjs.map

package/dist/beta/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/beta/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport {\n  TaskGroup,\n  type TaskCompletedEvent,\n  type TaskGroupOptions,\n  type TaskGroupResult,\n} from './workflows/index.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,uBAKO;","names":[]}

package/dist/beta/index.d.cts

@@ -0,0 +1,2 @@
+export { TaskGroup, type TaskCompletedEvent, type TaskGroupOptions, type TaskGroupResult, } from './workflows/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/beta/index.d.ts

@@ -0,0 +1,2 @@
+export { TaskGroup, type TaskCompletedEvent, type TaskGroupOptions, type TaskGroupResult, } from './workflows/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/beta/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/beta/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC"}

package/dist/beta/index.js

@@ -0,0 +1,7 @@
+import {
+  TaskGroup
+} from "./workflows/index.js";
+export {
+  TaskGroup
+};
+//# sourceMappingURL=index.js.map

package/dist/beta/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/beta/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport {\n  TaskGroup,\n  type TaskCompletedEvent,\n  type TaskGroupOptions,\n  type TaskGroupResult,\n} from './workflows/index.js';\n"],"mappings":"AAGA;AAAA,EACE;AAAA,OAIK;","names":[]}

package/dist/beta/workflows/index.cjs

@@ -0,0 +1,29 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var workflows_exports = {};
+__export(workflows_exports, {
+  TaskGroup: () => import_task_group.TaskGroup
+});
+module.exports = __toCommonJS(workflows_exports);
+var import_task_group = require("./task_group.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TaskGroup
+});
+//# sourceMappingURL=index.cjs.map

package/dist/beta/workflows/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/beta/workflows/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport {\n  TaskGroup,\n  type TaskCompletedEvent,\n  type TaskGroupOptions,\n  type TaskGroupResult,\n} from './task_group.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,wBAKO;","names":[]}

package/dist/beta/workflows/index.d.cts

@@ -0,0 +1,2 @@
+export { TaskGroup, type TaskCompletedEvent, type TaskGroupOptions, type TaskGroupResult, } from './task_group.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/beta/workflows/index.d.ts

@@ -0,0 +1,2 @@
+export { TaskGroup, type TaskCompletedEvent, type TaskGroupOptions, type TaskGroupResult, } from './task_group.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/beta/workflows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/beta/workflows/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/beta/workflows/index.js

@@ -0,0 +1,7 @@
+import {
+  TaskGroup
+} from "./task_group.js";
+export {
+  TaskGroup
+};
+//# sourceMappingURL=index.js.map

package/dist/beta/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/beta/workflows/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport {\n  TaskGroup,\n  type TaskCompletedEvent,\n  type TaskGroupOptions,\n  type TaskGroupResult,\n} from './task_group.js';\n"],"mappings":"AAGA;AAAA,EACE;AAAA,OAIK;","names":[]}

package/dist/beta/workflows/task_group.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var task_group_exports = {};
+__export(task_group_exports, {
+  TaskGroup: () => TaskGroup
+});
+module.exports = __toCommonJS(task_group_exports);
+var import_zod = require("zod");
+var import_llm = require("../../llm/index.cjs");
+var import_agent = require("../../voice/agent.cjs");
+class OutOfScopeError extends import_llm.ToolError {
+  targetTaskIds;
+  constructor(targetTaskIds) {
+    super("out_of_scope");
+    this.targetTaskIds = targetTaskIds;
+  }
+}
+class TaskGroup extends import_agent.AgentTask {
+  _summarizeChatCtx;
+  _returnExceptions;
+  _visitedTasks = /* @__PURE__ */ new Set();
+  _registeredFactories = /* @__PURE__ */ new Map();
+  _taskCompletedCallback;
+  _currentTask;
+  constructor(options = {}) {
+    const { summarizeChatCtx = true, returnExceptions = false, chatCtx, onTaskCompleted } = options;
+    super({ instructions: "*empty*", chatCtx });
+    this._summarizeChatCtx = summarizeChatCtx;
+    this._returnExceptions = returnExceptions;
+    this._taskCompletedCallback = onTaskCompleted;
+  }
+  add(task, { id, description }) {
+    this._registeredFactories.set(id, { taskFactory: task, id, description });
+    return this;
+  }
+  async onEnter() {
+    const taskStack = [...this._registeredFactories.keys()];
+    const taskResults = {};
+    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 import_llm.LLM)) {
+          throw new Error("summarizeChatCtx requires a standard LLM on the session");
+        }
+        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 });
+  }
+  buildOutOfScopeTool(activeTaskId) {
+    if (this._visitedTasks.size === 0) {
+      return void 0;
+    }
+    const regressionTaskIds = new Set(this._visitedTasks);
+    regressionTaskIds.delete(activeTaskId);
+    if (regressionTaskIds.size === 0) {
+      return void 0;
+    }
+    const taskRepr = {};
+    for (const [id, info] of this._registeredFactories) {
+      if (regressionTaskIds.has(id)) {
+        taskRepr[id] = info.description;
+      }
+    }
+    const taskIdValues = [...regressionTaskIds];
+    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 (0, import_llm.tool)({
+      description,
+      flags: import_llm.ToolFlag.IGNORE_ON_ENTER,
+      parameters: import_zod.z.object({
+        task_ids: import_zod.z.array(import_zod.z.enum(taskIdValues)).describe("The IDs of the tasks requested")
+      }),
+      execute: async ({ task_ids }) => {
+        for (const tid of task_ids) {
+          if (!registeredFactories.has(tid) || !visitedTasks.has(tid)) {
+            throw new import_llm.ToolError(`Unable to regress, invalid task id ${tid}`);
+          }
+        }
+        if (currentTask && !currentTask.done) {
+          currentTask.complete(new OutOfScopeError(task_ids));
+        }
+      }
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TaskGroup
+});
+//# sourceMappingURL=task_group.cjs.map