@livekit/agents 1.0.2 → 1.0.4

package/dist/voice/speech_handle.cjs

@@ -22,12 +22,18 @@ __export(speech_handle_exports, {
 });
 module.exports = __toCommonJS(speech_handle_exports);
 var import_utils = require("../utils.cjs");
+var import_agent = require("./agent.cjs");
 class SpeechHandle {
-  constructor(id, allowInterruptions, stepIndex, parent) {
-    this.id = id;
-    this.allowInterruptions = allowInterruptions;
-    this.stepIndex = stepIndex;
+  constructor(_id, _allowInterruptions, _stepIndex, parent) {
+    this._id = _id;
+    this._allowInterruptions = _allowInterruptions;
+    this._stepIndex = _stepIndex;
     this.parent = parent;
+    this.doneFut.await.finally(() => {
+      for (const callback of this.doneCallbacks) {
+        callback(this);
+      }
+    });
   }
   /** Priority for messages that should be played after all other messages in the queue */
   static SPEECH_PRIORITY_LOW = 0;
@@ -36,21 +42,58 @@ class SpeechHandle {
   /** Priority for important messages that should be played before others. */
   static SPEECH_PRIORITY_HIGH = 10;
   interruptFut = new import_utils.Future();
-  authorizeFut = new import_utils.Future();
-  playoutDoneFut = new import_utils.Future();
-  _chatMessage;
+  authorizedEvent = new import_utils.Event();
+  scheduledFut = new import_utils.Future();
+  doneFut = new import_utils.Future();
+  generations = [];
+  /** @internal */
+  _tasks = [];
+  _chatItems = [];
+  _numSteps = 1;
+  itemAddedCallbacks = /* @__PURE__ */ new Set();
+  doneCallbacks = /* @__PURE__ */ new Set();
   static create(options) {
-    const { allowInterruptions = false, stepIndex = 0, parent } = options ?? {};
+    const { allowInterruptions = true, stepIndex = 0, parent } = options ?? {};
     return new SpeechHandle((0, import_utils.shortuuid)("speech_"), allowInterruptions, stepIndex, parent);
   }
   get interrupted() {
     return this.interruptFut.done;
   }
-  get done() {
-    return this.playoutDoneFut.done;
+  get numSteps() {
+    return this._numSteps;
+  }
+  get id() {
+    return this._id;
+  }
+  get scheduled() {
+    return this.scheduledFut.done;
+  }
+  get allowInterruptions() {
+    return this._allowInterruptions;
+  }
+  /**
+   * Allow or disallow interruptions on this SpeechHandle.
+   *
+   * When set to false, the SpeechHandle will no longer accept any incoming
+   * interruption requests until re-enabled. If the handle is already
+   * interrupted, clearing interruptions is not allowed.
+   *
+   * @param value - true to allow interruptions, false to disallow
+   * @throws Error If attempting to disable interruptions when already interrupted
+   */
+  set allowInterruptions(value) {
+    if (this.interrupted && !value) {
+      throw new Error(
+        "Cannot set allow_interruptions to False, the SpeechHandle is already interrupted"
+      );
+    }
+    this._allowInterruptions = value;
+  }
+  done() {
+    return this.doneFut.done;
   }
-  get chatMessage() {
-    return this._chatMessage;
+  get chatItems() {
+    return this._chatItems;
   }
   /**
    * Interrupt the current speech generation.
@@ -59,43 +102,122 @@ class SpeechHandle {
    *
    * @returns The same speech handle that was interrupted.
    */
-  interrupt() {
-    if (!this.allowInterruptions) {
-      throw new Error("interruptions are not allowed");
+  interrupt(force = false) {
+    if (!force && !this.allowInterruptions) {
+      throw new Error("This generation handle does not allow interruptions");
     }
-    if (this.done) return this;
-    this.interruptFut.resolve();
+    this._cancel();
     return this;
   }
-  then(callback) {
-    return this.playoutDoneFut.await.finally(() => callback(this));
-  }
+  /**
+   * Waits for the entire assistant turn to complete playback.
+   *
+   * This method waits until the assistant has fully finished speaking,
+   * including any finalization steps beyond initial response generation.
+   * This is appropriate to call when you want to ensure the speech output
+   * has entirely played out, including any tool calls and response follow-ups.
+   */
   async waitForPlayout() {
-    return this.playoutDoneFut.await;
+    const store = import_agent.asyncLocalStorage.getStore();
+    if (store && (store == null ? void 0 : store.functionCall)) {
+      throw new Error(
+        `Cannot call 'SpeechHandle.waitForPlayout()' from inside the function tool '${store.functionCall.name}'. This creates a circular wait: the speech handle is waiting for the function tool to complete, while the function tool is simultaneously waiting for the speech handle.
+To wait for the assistant's spoken response prior to running this tool, use RunContext.wait_for_playout() instead.`
+      );
+    }
   }
   async waitIfNotInterrupted(aw) {
     const allTasksPromise = Promise.all(aw);
     const fs = [allTasksPromise, this.interruptFut.await];
     await Promise.race(fs);
   }
+  addDoneCallback(callback) {
+    this.doneCallbacks.add(callback);
+  }
+  removeDoneCallback(callback) {
+    this.doneCallbacks.delete(callback);
+  }
   /** @internal */
-  _setChatMessage(chatMessage) {
-    if (this.done) {
-      throw new Error("cannot set chat message after speech has been played");
+  _cancel() {
+    if (this.done()) {
+      return this;
+    }
+    if (!this.interruptFut.done) {
+      this.interruptFut.resolve();
     }
-    this._chatMessage = chatMessage;
+    return this;
+  }
+  /** @internal */
+  _authorizeGeneration() {
+    const fut = new import_utils.Future();
+    this.generations.push(fut);
+    this.authorizedEvent.set();
   }
   /** @internal */
-  _authorizePlayout() {
-    this.authorizeFut.resolve();
+  _clearAuthorization() {
+    this.authorizedEvent.clear();
   }
   /** @internal */
   async _waitForAuthorization() {
-    return this.authorizeFut.await;
+    await this.authorizedEvent.wait();
   }
   /** @internal */
-  _markPlayoutDone() {
-    this.playoutDoneFut.resolve();
+  async _waitForGeneration(stepIdx = -1) {
+    if (this.generations.length === 0) {
+      throw new Error("cannot use wait_for_generation: no active generation is running.");
+    }
+    const index = stepIdx === -1 ? this.generations.length - 1 : stepIdx;
+    const generation = this.generations[index];
+    if (!generation) {
+      throw new Error(`Generation at index ${index} not found.`);
+    }
+    return generation.await;
+  }
+  /** @internal */
+  async _waitForScheduled() {
+    return this.scheduledFut.await;
+  }
+  /** @internal */
+  _markGenerationDone() {
+    if (this.generations.length === 0) {
+      throw new Error("cannot use mark_generation_done: no active generation is running.");
+    }
+    const lastGeneration = this.generations[this.generations.length - 1];
+    if (lastGeneration && !lastGeneration.done) {
+      lastGeneration.resolve();
+    }
+  }
+  /** @internal */
+  _markDone() {
+    if (!this.doneFut.done) {
+      this.doneFut.resolve();
+      if (this.generations.length > 0) {
+        this._markGenerationDone();
+      }
+    }
+  }
+  /** @internal */
+  _markScheduled() {
+    if (!this.scheduledFut.done) {
+      this.scheduledFut.resolve();
+    }
+  }
+  /** @internal */
+  _addItemAddedCallback(callback) {
+    this.itemAddedCallbacks.add(callback);
+  }
+  /** @internal */
+  _removeItemAddedCallback(callback) {
+    this.itemAddedCallbacks.delete(callback);
+  }
+  /** @internal */
+  _itemAdded(items) {
+    for (const item of items) {
+      for (const cb of this.itemAddedCallbacks) {
+        cb(item);
+      }
+      this._chatItems.push(item);
+    }
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/voice/speech_handle.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/voice/speech_handle.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { ChatMessage } from '../llm/index.js';\nimport { Future, shortuuid } from '../utils.js';\n\nexport class SpeechHandle {\n  /** Priority for messages that should be played after all other messages in the queue */\n  static SPEECH_PRIORITY_LOW = 0;\n  /** Every speech generates by the VoiceAgent defaults to this priority. */\n  static SPEECH_PRIORITY_NORMAL = 5;\n  /** Priority for important messages that should be played before others. */\n  static SPEECH_PRIORITY_HIGH = 10;\n\n  private interruptFut = new Future();\n  private authorizeFut = new Future();\n  private playoutDoneFut = new Future();\n\n  private _chatMessage?: ChatMessage;\n\n  constructor(\n    readonly id: string,\n    readonly allowInterruptions: boolean,\n    readonly stepIndex: number,\n    readonly parent?: SpeechHandle,\n  ) {}\n\n  static create(options: {\n    allowInterruptions?: boolean;\n    stepIndex?: number;\n    parent?: SpeechHandle;\n  }) {\n    const { allowInterruptions = false, stepIndex = 0, parent } = options ?? {};\n\n    return new SpeechHandle(shortuuid('speech_'), allowInterruptions, stepIndex, parent);\n  }\n\n  get interrupted(): boolean {\n    return this.interruptFut.done;\n  }\n\n  get done(): boolean {\n    return this.playoutDoneFut.done;\n  }\n\n  get chatMessage(): ChatMessage | undefined {\n    return this._chatMessage;\n  }\n\n  /**\n   * Interrupt the current speech generation.\n   *\n   * @throws Error If this speech handle does not allow interruptions.\n   *\n   * @returns The same speech handle that was interrupted.\n   */\n  interrupt(): SpeechHandle {\n    if (!this.allowInterruptions) {\n      throw new Error('interruptions are not allowed');\n    }\n\n    if (this.done) return this;\n\n    this.interruptFut.resolve();\n    return this;\n  }\n\n  then(callback: (sh: SpeechHandle) => void) {\n    return this.playoutDoneFut.await.finally(() => callback(this));\n  }\n\n  async waitForPlayout() {\n    return this.playoutDoneFut.await;\n  }\n\n  async waitIfNotInterrupted(aw: Promise<unknown>[]): Promise<void> {\n    const allTasksPromise = Promise.all(aw);\n    const fs: Promise<unknown>[] = [allTasksPromise, this.interruptFut.await];\n    await Promise.race(fs);\n  }\n\n  /** @internal */\n  _setChatMessage(chatMessage: ChatMessage) {\n    if (this.done) {\n      throw new Error('cannot set chat message after speech has been played');\n    }\n    this._chatMessage = chatMessage;\n  }\n\n  /** @internal */\n  _authorizePlayout() {\n    this.authorizeFut.resolve();\n  }\n\n  /** @internal */\n  async _waitForAuthorization() {\n    return this.authorizeFut.await;\n  }\n\n  /** @internal */\n  _markPlayoutDone() {\n    this.playoutDoneFut.resolve();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,mBAAkC;AAE3B,MAAM,aAAa;AAAA,EAcxB,YACW,IACA,oBACA,WACA,QACT;AAJS;AACA;AACA;AACA;AAAA,EACR;AAAA;AAAA,EAjBH,OAAO,sBAAsB;AAAA;AAAA,EAE7B,OAAO,yBAAyB;AAAA;AAAA,EAEhC,OAAO,uBAAuB;AAAA,EAEtB,eAAe,IAAI,oBAAO;AAAA,EAC1B,eAAe,IAAI,oBAAO;AAAA,EAC1B,iBAAiB,IAAI,oBAAO;AAAA,EAE5B;AAAA,EASR,OAAO,OAAO,SAIX;AACD,UAAM,EAAE,qBAAqB,OAAO,YAAY,GAAG,OAAO,IAAI,WAAW,CAAC;AAE1E,WAAO,IAAI,iBAAa,wBAAU,SAAS,GAAG,oBAAoB,WAAW,MAAM;AAAA,EACrF;AAAA,EAEA,IAAI,cAAuB;AACzB,WAAO,KAAK,aAAa;AAAA,EAC3B;AAAA,EAEA,IAAI,OAAgB;AAClB,WAAO,KAAK,eAAe;AAAA,EAC7B;AAAA,EAEA,IAAI,cAAuC;AACzC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,YAA0B;AACxB,QAAI,CAAC,KAAK,oBAAoB;AAC5B,YAAM,IAAI,MAAM,+BAA+B;AAAA,IACjD;AAEA,QAAI,KAAK,KAAM,QAAO;AAEtB,SAAK,aAAa,QAAQ;AAC1B,WAAO;AAAA,EACT;AAAA,EAEA,KAAK,UAAsC;AACzC,WAAO,KAAK,eAAe,MAAM,QAAQ,MAAM,SAAS,IAAI,CAAC;AAAA,EAC/D;AAAA,EAEA,MAAM,iBAAiB;AACrB,WAAO,KAAK,eAAe;AAAA,EAC7B;AAAA,EAEA,MAAM,qBAAqB,IAAuC;AAChE,UAAM,kBAAkB,QAAQ,IAAI,EAAE;AACtC,UAAM,KAAyB,CAAC,iBAAiB,KAAK,aAAa,KAAK;AACxE,UAAM,QAAQ,KAAK,EAAE;AAAA,EACvB;AAAA;AAAA,EAGA,gBAAgB,aAA0B;AACxC,QAAI,KAAK,MAAM;AACb,YAAM,IAAI,MAAM,sDAAsD;AAAA,IACxE;AACA,SAAK,eAAe;AAAA,EACtB;AAAA;AAAA,EAGA,oBAAoB;AAClB,SAAK,aAAa,QAAQ;AAAA,EAC5B;AAAA;AAAA,EAGA,MAAM,wBAAwB;AAC5B,WAAO,KAAK,aAAa;AAAA,EAC3B;AAAA;AAAA,EAGA,mBAAmB;AACjB,SAAK,eAAe,QAAQ;AAAA,EAC9B;AACF;","names":[]}
+{"version":3,"sources":["../../src/voice/speech_handle.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { ChatItem } from '../llm/index.js';\nimport { Event, Future, shortuuid } from '../utils.js';\nimport type { Task } from '../utils.js';\nimport { asyncLocalStorage } from './agent.js';\n\nexport class SpeechHandle {\n  /** Priority for messages that should be played after all other messages in the queue */\n  static SPEECH_PRIORITY_LOW = 0;\n  /** Every speech generates by the VoiceAgent defaults to this priority. */\n  static SPEECH_PRIORITY_NORMAL = 5;\n  /** Priority for important messages that should be played before others. */\n  static SPEECH_PRIORITY_HIGH = 10;\n\n  private interruptFut = new Future<void>();\n  private authorizedEvent = new Event();\n  private scheduledFut = new Future<void>();\n  private doneFut = new Future<void>();\n\n  private generations: Future<void>[] = [];\n  /** @internal */\n  _tasks: Task<void>[] = [];\n  private _chatItems: ChatItem[] = [];\n  private _numSteps = 1;\n\n  private itemAddedCallbacks: Set<(item: ChatItem) => void> = new Set();\n  private doneCallbacks: Set<(sh: SpeechHandle) => void> = new Set();\n\n  constructor(\n    private _id: string,\n    private _allowInterruptions: boolean,\n    /** @internal */\n    public _stepIndex: number,\n    readonly parent?: SpeechHandle,\n  ) {\n    this.doneFut.await.finally(() => {\n      for (const callback of this.doneCallbacks) {\n        callback(this);\n      }\n    });\n  }\n\n  static create(options?: {\n    allowInterruptions?: boolean;\n    stepIndex?: number;\n    parent?: SpeechHandle;\n  }) {\n    const { allowInterruptions = true, stepIndex = 0, parent } = options ?? {};\n\n    return new SpeechHandle(shortuuid('speech_'), allowInterruptions, stepIndex, parent);\n  }\n\n  get interrupted(): boolean {\n    return this.interruptFut.done;\n  }\n\n  get numSteps(): number {\n    return this._numSteps;\n  }\n\n  get id(): string {\n    return this._id;\n  }\n\n  get scheduled(): boolean {\n    return this.scheduledFut.done;\n  }\n\n  get allowInterruptions(): boolean {\n    return this._allowInterruptions;\n  }\n\n  /**\n   * Allow or disallow interruptions on this SpeechHandle.\n   *\n   * When set to false, the SpeechHandle will no longer accept any incoming\n   * interruption requests until re-enabled. If the handle is already\n   * interrupted, clearing interruptions is not allowed.\n   *\n   * @param value - true to allow interruptions, false to disallow\n   * @throws Error If attempting to disable interruptions when already interrupted\n   */\n  set allowInterruptions(value: boolean) {\n    if (this.interrupted && !value) {\n      throw new Error(\n        'Cannot set allow_interruptions to False, the SpeechHandle is already interrupted',\n      );\n    }\n    this._allowInterruptions = value;\n  }\n\n  done(): boolean {\n    return this.doneFut.done;\n  }\n\n  get chatItems(): ChatItem[] {\n    return this._chatItems;\n  }\n\n  /**\n   * Interrupt the current speech generation.\n   *\n   * @throws Error If this speech handle does not allow interruptions.\n   *\n   * @returns The same speech handle that was interrupted.\n   */\n  interrupt(force: boolean = false): SpeechHandle {\n    if (!force && !this.allowInterruptions) {\n      throw new Error('This generation handle does not allow interruptions');\n    }\n\n    this._cancel();\n    return this;\n  }\n\n  /**\n   * Waits for the entire assistant turn to complete playback.\n   *\n   * This method waits until the assistant has fully finished speaking,\n   * including any finalization steps beyond initial response generation.\n   * This is appropriate to call when you want to ensure the speech output\n   * has entirely played out, including any tool calls and response follow-ups.\n   */\n  async waitForPlayout(): Promise<void> {\n    const store = asyncLocalStorage.getStore();\n    if (store && store?.functionCall) {\n      throw new Error(\n        `Cannot call 'SpeechHandle.waitForPlayout()' from inside the function tool '${store.functionCall.name}'. ` +\n          'This creates a circular wait: the speech handle is waiting for the function tool to complete, ' +\n          'while the function tool is simultaneously waiting for the speech handle.\\n' +\n          \"To wait for the assistant's spoken response prior to running this tool, use RunContext.wait_for_playout() instead.\",\n      );\n    }\n  }\n\n  async waitIfNotInterrupted(aw: Promise<unknown>[]): Promise<void> {\n    const allTasksPromise = Promise.all(aw);\n    const fs: Promise<unknown>[] = [allTasksPromise, this.interruptFut.await];\n    await Promise.race(fs);\n  }\n\n  addDoneCallback(callback: (sh: SpeechHandle) => void) {\n    this.doneCallbacks.add(callback);\n  }\n\n  removeDoneCallback(callback: (sh: SpeechHandle) => void) {\n    this.doneCallbacks.delete(callback);\n  }\n\n  /** @internal */\n  _cancel(): SpeechHandle {\n    if (this.done()) {\n      return this;\n    }\n\n    if (!this.interruptFut.done) {\n      this.interruptFut.resolve();\n    }\n\n    return this;\n  }\n\n  /** @internal */\n  _authorizeGeneration(): void {\n    const fut = new Future<void>();\n    this.generations.push(fut);\n    this.authorizedEvent.set();\n  }\n\n  /** @internal */\n  _clearAuthorization(): void {\n    this.authorizedEvent.clear();\n  }\n\n  /** @internal */\n  async _waitForAuthorization(): Promise<void> {\n    await this.authorizedEvent.wait();\n  }\n\n  /** @internal */\n  async _waitForGeneration(stepIdx: number = -1): Promise<void> {\n    if (this.generations.length === 0) {\n      throw new Error('cannot use wait_for_generation: no active generation is running.');\n    }\n\n    const index = stepIdx === -1 ? this.generations.length - 1 : stepIdx;\n    const generation = this.generations[index];\n    if (!generation) {\n      throw new Error(`Generation at index ${index} not found.`);\n    }\n    return generation.await;\n  }\n\n  /** @internal */\n  async _waitForScheduled(): Promise<void> {\n    return this.scheduledFut.await;\n  }\n\n  /** @internal */\n  _markGenerationDone(): void {\n    if (this.generations.length === 0) {\n      throw new Error('cannot use mark_generation_done: no active generation is running.');\n    }\n\n    const lastGeneration = this.generations[this.generations.length - 1];\n    if (lastGeneration && !lastGeneration.done) {\n      lastGeneration.resolve();\n    }\n  }\n\n  /** @internal */\n  _markDone(): void {\n    if (!this.doneFut.done) {\n      this.doneFut.resolve();\n      if (this.generations.length > 0) {\n        this._markGenerationDone(); // preemptive generation could be cancelled before being scheduled\n      }\n    }\n  }\n\n  /** @internal */\n  _markScheduled(): void {\n    if (!this.scheduledFut.done) {\n      this.scheduledFut.resolve();\n    }\n  }\n\n  /** @internal */\n  _addItemAddedCallback(callback: (item: ChatItem) => void): void {\n    this.itemAddedCallbacks.add(callback);\n  }\n\n  /** @internal */\n  _removeItemAddedCallback(callback: (item: ChatItem) => void): void {\n    this.itemAddedCallbacks.delete(callback);\n  }\n\n  /** @internal */\n  _itemAdded(items: ChatItem[]): void {\n    for (const item of items) {\n      for (const cb of this.itemAddedCallbacks) {\n        cb(item);\n      }\n      this._chatItems.push(item);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/voice/speech_handle.d.cts

@@ -1,8 +1,10 @@
-import type { ChatMessage } from '../llm/index.js';
+import type { ChatItem } from '../llm/index.js';
+import type { Task } from '../utils.js';
 export declare class SpeechHandle {
-    readonly id: string;
-    readonly allowInterruptions: boolean;
-    readonly stepIndex: number;
+    private _id;
+    private _allowInterruptions;
+    /** @internal */
+    _stepIndex: number;
     readonly parent?: SpeechHandle | undefined;
     /** Priority for messages that should be played after all other messages in the queue */
     static SPEECH_PRIORITY_LOW: number;
@@ -11,18 +13,42 @@ export declare class SpeechHandle {
     /** Priority for important messages that should be played before others. */
     static SPEECH_PRIORITY_HIGH: number;
     private interruptFut;
-    private authorizeFut;
-    private playoutDoneFut;
-    private _chatMessage?;
-    constructor(id: string, allowInterruptions: boolean, stepIndex: number, parent?: SpeechHandle | undefined);
-    static create(options: {
+    private authorizedEvent;
+    private scheduledFut;
+    private doneFut;
+    private generations;
+    /** @internal */
+    _tasks: Task<void>[];
+    private _chatItems;
+    private _numSteps;
+    private itemAddedCallbacks;
+    private doneCallbacks;
+    constructor(_id: string, _allowInterruptions: boolean, 
+    /** @internal */
+    _stepIndex: number, parent?: SpeechHandle | undefined);
+    static create(options?: {
         allowInterruptions?: boolean;
         stepIndex?: number;
         parent?: SpeechHandle;
     }): SpeechHandle;
     get interrupted(): boolean;
-    get done(): boolean;
-    get chatMessage(): ChatMessage | undefined;
+    get numSteps(): number;
+    get id(): string;
+    get scheduled(): boolean;
+    get allowInterruptions(): boolean;
+    /**
+     * Allow or disallow interruptions on this SpeechHandle.
+     *
+     * When set to false, the SpeechHandle will no longer accept any incoming
+     * interruption requests until re-enabled. If the handle is already
+     * interrupted, clearing interruptions is not allowed.
+     *
+     * @param value - true to allow interruptions, false to disallow
+     * @throws Error If attempting to disable interruptions when already interrupted
+     */
+    set allowInterruptions(value: boolean);
+    done(): boolean;
+    get chatItems(): ChatItem[];
     /**
      * Interrupt the current speech generation.
      *
@@ -30,17 +56,42 @@ export declare class SpeechHandle {
      *
      * @returns The same speech handle that was interrupted.
      */
-    interrupt(): SpeechHandle;
-    then(callback: (sh: SpeechHandle) => void): Promise<void>;
+    interrupt(force?: boolean): SpeechHandle;
+    /**
+     * Waits for the entire assistant turn to complete playback.
+     *
+     * This method waits until the assistant has fully finished speaking,
+     * including any finalization steps beyond initial response generation.
+     * This is appropriate to call when you want to ensure the speech output
+     * has entirely played out, including any tool calls and response follow-ups.
+     */
     waitForPlayout(): Promise<void>;
     waitIfNotInterrupted(aw: Promise<unknown>[]): Promise<void>;
+    addDoneCallback(callback: (sh: SpeechHandle) => void): void;
+    removeDoneCallback(callback: (sh: SpeechHandle) => void): void;
+    /** @internal */
+    _cancel(): SpeechHandle;
     /** @internal */
-    _setChatMessage(chatMessage: ChatMessage): void;
+    _authorizeGeneration(): void;
     /** @internal */
-    _authorizePlayout(): void;
+    _clearAuthorization(): void;
     /** @internal */
     _waitForAuthorization(): Promise<void>;
     /** @internal */
-    _markPlayoutDone(): void;
+    _waitForGeneration(stepIdx?: number): Promise<void>;
+    /** @internal */
+    _waitForScheduled(): Promise<void>;
+    /** @internal */
+    _markGenerationDone(): void;
+    /** @internal */
+    _markDone(): void;
+    /** @internal */
+    _markScheduled(): void;
+    /** @internal */
+    _addItemAddedCallback(callback: (item: ChatItem) => void): void;
+    /** @internal */
+    _removeItemAddedCallback(callback: (item: ChatItem) => void): void;
+    /** @internal */
+    _itemAdded(items: ChatItem[]): void;
 }
 //# sourceMappingURL=speech_handle.d.ts.map

package/dist/voice/speech_handle.d.ts

@@ -1,8 +1,10 @@
-import type { ChatMessage } from '../llm/index.js';
+import type { ChatItem } from '../llm/index.js';
+import type { Task } from '../utils.js';
 export declare class SpeechHandle {
-    readonly id: string;
-    readonly allowInterruptions: boolean;
-    readonly stepIndex: number;
+    private _id;
+    private _allowInterruptions;
+    /** @internal */
+    _stepIndex: number;
     readonly parent?: SpeechHandle | undefined;
     /** Priority for messages that should be played after all other messages in the queue */
     static SPEECH_PRIORITY_LOW: number;
@@ -11,18 +13,42 @@ export declare class SpeechHandle {
     /** Priority for important messages that should be played before others. */
     static SPEECH_PRIORITY_HIGH: number;
     private interruptFut;
-    private authorizeFut;
-    private playoutDoneFut;
-    private _chatMessage?;
-    constructor(id: string, allowInterruptions: boolean, stepIndex: number, parent?: SpeechHandle | undefined);
-    static create(options: {
+    private authorizedEvent;
+    private scheduledFut;
+    private doneFut;
+    private generations;
+    /** @internal */
+    _tasks: Task<void>[];
+    private _chatItems;
+    private _numSteps;
+    private itemAddedCallbacks;
+    private doneCallbacks;
+    constructor(_id: string, _allowInterruptions: boolean, 
+    /** @internal */
+    _stepIndex: number, parent?: SpeechHandle | undefined);
+    static create(options?: {
         allowInterruptions?: boolean;
         stepIndex?: number;
         parent?: SpeechHandle;
     }): SpeechHandle;
     get interrupted(): boolean;
-    get done(): boolean;
-    get chatMessage(): ChatMessage | undefined;
+    get numSteps(): number;
+    get id(): string;
+    get scheduled(): boolean;
+    get allowInterruptions(): boolean;
+    /**
+     * Allow or disallow interruptions on this SpeechHandle.
+     *
+     * When set to false, the SpeechHandle will no longer accept any incoming
+     * interruption requests until re-enabled. If the handle is already
+     * interrupted, clearing interruptions is not allowed.
+     *
+     * @param value - true to allow interruptions, false to disallow
+     * @throws Error If attempting to disable interruptions when already interrupted
+     */
+    set allowInterruptions(value: boolean);
+    done(): boolean;
+    get chatItems(): ChatItem[];
     /**
      * Interrupt the current speech generation.
      *
@@ -30,17 +56,42 @@ export declare class SpeechHandle {
      *
      * @returns The same speech handle that was interrupted.
      */
-    interrupt(): SpeechHandle;
-    then(callback: (sh: SpeechHandle) => void): Promise<void>;
+    interrupt(force?: boolean): SpeechHandle;
+    /**
+     * Waits for the entire assistant turn to complete playback.
+     *
+     * This method waits until the assistant has fully finished speaking,
+     * including any finalization steps beyond initial response generation.
+     * This is appropriate to call when you want to ensure the speech output
+     * has entirely played out, including any tool calls and response follow-ups.
+     */
     waitForPlayout(): Promise<void>;
     waitIfNotInterrupted(aw: Promise<unknown>[]): Promise<void>;
+    addDoneCallback(callback: (sh: SpeechHandle) => void): void;
+    removeDoneCallback(callback: (sh: SpeechHandle) => void): void;
+    /** @internal */
+    _cancel(): SpeechHandle;
     /** @internal */
-    _setChatMessage(chatMessage: ChatMessage): void;
+    _authorizeGeneration(): void;
     /** @internal */
-    _authorizePlayout(): void;
+    _clearAuthorization(): void;
     /** @internal */
     _waitForAuthorization(): Promise<void>;
     /** @internal */
-    _markPlayoutDone(): void;
+    _waitForGeneration(stepIdx?: number): Promise<void>;
+    /** @internal */
+    _waitForScheduled(): Promise<void>;
+    /** @internal */
+    _markGenerationDone(): void;
+    /** @internal */
+    _markDone(): void;
+    /** @internal */
+    _markScheduled(): void;
+    /** @internal */
+    _addItemAddedCallback(callback: (item: ChatItem) => void): void;
+    /** @internal */
+    _removeItemAddedCallback(callback: (item: ChatItem) => void): void;
+    /** @internal */
+    _itemAdded(items: ChatItem[]): void;
 }
 //# sourceMappingURL=speech_handle.d.ts.map

package/dist/voice/speech_handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"speech_handle.d.ts","sourceRoot":"","sources":["../../src/voice/speech_handle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,qBAAa,YAAY;IAerB,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,kBAAkB,EAAE,OAAO;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,MAAM,CAAC;IAjBlB,wFAAwF;IACxF,MAAM,CAAC,mBAAmB,SAAK;IAC/B,0EAA0E;IAC1E,MAAM,CAAC,sBAAsB,SAAK;IAClC,2EAA2E;IAC3E,MAAM,CAAC,oBAAoB,SAAM;IAEjC,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,cAAc,CAAgB;IAEtC,OAAO,CAAC,YAAY,CAAC,CAAc;gBAGxB,EAAE,EAAE,MAAM,EACV,kBAAkB,EAAE,OAAO,EAC3B,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,0BAAc;IAGhC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,YAAY,CAAC;KACvB;IAMD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,IAAI,WAAW,IAAI,WAAW,GAAG,SAAS,CAEzC;IAED;;;;;;OAMG;IACH,SAAS,IAAI,YAAY;IAWzB,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,IAAI;IAInC,cAAc;IAId,oBAAoB,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,gBAAgB;IAChB,eAAe,CAAC,WAAW,EAAE,WAAW;IAOxC,gBAAgB;IAChB,iBAAiB;IAIjB,gBAAgB;IACV,qBAAqB;IAI3B,gBAAgB;IAChB,gBAAgB;CAGjB"}
+{"version":3,"file":"speech_handle.d.ts","sourceRoot":"","sources":["../../src/voice/speech_handle.ts"],"names":[],"mappings":"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"}