fix(voice): expose speech handle generation errors

.changeset/speech-handle-exception.md

@@ -0,0 +1,5 @@
+---
+'@livekit/agents': patch
+---
+
+Expose speech generation errors via `SpeechHandle.exception()`.

agents/src/voice/agent_activity.ts

@@ -75,6 +75,7 @@ import {
   Future,
   IdleTimeoutError,
   Task,
+  asError,
   cancelAndWait,
   delay,
   isDevMode,
@@ -3902,7 +3903,17 @@ export class AgentActivity implements RecognitionHooks {
         return;
       }
 
-      const generationEvent = await generationPromise;
+      let generationEvent: GenerationCreatedEvent;
+      try {
+        generationEvent = await generationPromise;
+      } catch (error) {
+        const cause = asError(error);
+        this.logger.error(cause, 'failed to generate a reply');
+        speechHandle._markDone(cause);
+        this.agentSession._updateAgentState('listening');
+        return;
+      }
+
       await this.realtimeGenerationTask(
         speechHandle,
         generationEvent,

agents/src/voice/speech_handle.test.ts

@@ -116,6 +116,47 @@ describe('SpeechHandle - awaitable protocol', () => {
   });
 });
 
+describe('SpeechHandle.exception', () => {
+  it('does not throw from await when generation failed', async () => {
+    const handle = SpeechHandle.create();
+    const error = new Error('generate_reply timed out.');
+
+    handle._markDone(error);
+
+    const result = await handle;
+    expect(result).toBe(handle);
+
+    await handle.waitForPlayout();
+    expect(handle.exception()).toBe(error);
+  });
+
+  it('returns undefined when generation did not fail', async () => {
+    const handle = SpeechHandle.create();
+    handle._markDone();
+
+    await handle;
+    expect(handle.exception()).toBeUndefined();
+  });
+
+  it('throws if the handle is not done yet', () => {
+    const handle = SpeechHandle.create();
+
+    expect(() => handle.exception()).toThrow('SpeechHandle is not done yet');
+  });
+
+  it('ignores errors after the handle is already done', () => {
+    const handle = SpeechHandle.create();
+    const first = new Error('first');
+    const second = new Error('second');
+
+    handle._markDone(first);
+    handle._markDone();
+    handle._markDone(second);
+
+    expect(handle.exception()).toBe(first);
+  });
+});
+
 describe('SpeechHandle - simulated tool-call deadlock scenario', () => {
   // Models the previously-broken pattern:
   //

agents/src/voice/speech_handle.ts

@@ -93,6 +93,8 @@ export class SpeechHandle {
   /** @internal - used by AgentTask/RunResult final output plumbing */
   _maybeRunFinalOutput?: unknown;
 
+  private error?: Error;
+
   private itemAddedCallbacks: Set<(item: ChatItem) => void> = new Set();
   private doneCallbacks: Set<(sh: SpeechHandle) => void> = new Set();
 
@@ -183,6 +185,20 @@ export class SpeechHandle {
     return this.doneFut.done;
   }
 
+  /**
+   * Return the error that caused this speech to fail, if any.
+   *
+   * Awaiting a SpeechHandle never throws; call this method after the handle is
+   * done to check whether the generation failed.
+   */
+  exception(): Error | undefined {
+    if (!this.doneFut.done) {
+      throw new Error('SpeechHandle is not done yet');
+    }
+
+    return this.error;
+  }
+
   get chatItems(): ChatItem[] {
     return this._chatItems;
   }
@@ -357,8 +373,9 @@ export class SpeechHandle {
   }
 
   /** @internal */
-  _markDone(): void {
+  _markDone(error?: Error): void {
     if (!this.doneFut.done) {
+      this.error = error;
       this.doneFut.resolve();
     }
 

agents/src/voice/testing/run_result.test.ts

@@ -9,7 +9,7 @@ import { ToolContext, tool } from '../../llm/tool_context.js';
 import { Agent } from '../agent.js';
 import { performToolExecutions } from '../generation.js';
 import { SpeechHandle } from '../speech_handle.js';
-import { activeMockTools, withMockTools } from './run_result.js';
+import { RunResult, activeMockTools, withMockTools } from './run_result.js';
 
 class AgentA extends Agent {
   constructor() {
@@ -180,3 +180,16 @@ describe('withMockTools', () => {
     expect(output.output[0]?.toolCallOutput?.isError).toBe(true);
   });
 });
+
+describe('RunResult', () => {
+  it('propagates speech handle errors', async () => {
+    const runResult = new RunResult();
+    const handle = SpeechHandle.create();
+    const error = new Error('generate_reply timed out.');
+
+    runResult._watchHandle(handle);
+    handle._markDone(error);
+
+    await expect(runResult.wait()).rejects.toThrow('generate_reply timed out.');
+  });
+});

agents/src/voice/testing/run_result.ts

@@ -243,6 +243,12 @@ export class RunResult<T = unknown> {
       return;
     }
 
+    const speechError = this.lastSpeechHandle.exception();
+    if (speechError) {
+      this.doneFut.reject(speechError);
+      return;
+    }
+
     const finalOutput = this.lastSpeechHandle._maybeRunFinalOutput;
     if (finalOutput instanceof Error) {
       this.doneFut.reject(finalOutput);