feat(agents): expose interrupted speech data on SpeechHandle

[pouya-commos]

Summary

Expose two new getters on SpeechHandle so application code can recover from agent interruptions:

• generatedText — full text the model produced before the speech was interrupted (null if not interrupted or no text was generated).
• spokenText — text that was actually heard by the listener before interruption (null if not interrupted).

Motivation

When an agent is interrupted mid-response (especially while delivering a tool result), the caller may have heard nothing or only a fragment. Today the SDK correctly truncates the server-side conversation, but SpeechHandle.chatItems only retains the spoken portion — the full generated text is discarded, so application code has no way to detect what was lost and re-state it on the next turn.

This data already exists internally in agent_activity.ts at the moment of interruption (textOut.text = full model output, playbackEv.synchronizedTranscript = what was spoken). This PR just plumbs it onto the handle.

Changes

• agents/src/voice/speech_handle.ts — add _generatedText / _spokenText private fields, generatedText / spokenText public getters, and an internal _setInterruptionData(generatedText, spokenText) setter (marked @internal, matching _markDone, _itemAdded, etc.).
• agents/src/voice/agent_activity.ts — populate the fields in both _pipelineReplyTaskImpl (traditional STT→LLM→TTS) and _realtimeGenerationTaskImpl (realtime / multimodal) at the point where forwardedText is finalized, so non-interrupted speeches incur no overhead and both pipelines behave the same.

Usage

session.on(AgentSessionEventTypes.SpeechCreated, (ev) => {
  ev.speechHandle.addDoneCallback(() => {
    if (ev.speechHandle.interrupted) {
      const generated = ev.speechHandle.generatedText; // "Yes, we rent skid steers. We have mini, medium, and large units."
      const spoken = ev.speechHandle.spokenText;       // "Yes," (or "" if nothing was heard)
      // Application can now implement recovery logic
    }
  });
});

Test plan

• pnpm build succeeds
• pnpm api:check succeeds (or pnpm api:update is run if the public API report needs regenerating)
• pnpm test passes existing voice/agent_activity tests
• Manual: run an agent (e.g. examples/src/basic_agent.ts), interrupt it mid-utterance, and verify generatedText / spokenText reflect the model's full output and the truncated heard portion respectively
• Verify both traditional pipeline and a realtime plugin (e.g. openai/realtime) populate the fields

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 771aeac

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 26 packages

Name	Type
@livekit/agents	Patch
@livekit/agents-plugin-anam	Patch
@livekit/agents-plugin-assemblyai	Patch
@livekit/agents-plugin-baseten	Patch
@livekit/agents-plugin-bey	Patch
@livekit/agents-plugin-cartesia	Patch
@livekit/agents-plugin-cerebras	Patch
@livekit/agents-plugin-deepgram	Patch
@livekit/agents-plugin-elevenlabs	Patch
@livekit/agents-plugin-google	Patch
@livekit/agents-plugin-hedra	Patch
@livekit/agents-plugin-inworld	Patch
@livekit/agents-plugin-lemonslice	Patch
@livekit/agents-plugin-livekit	Patch
@livekit/agents-plugin-mistral	Patch
@livekit/agents-plugin-neuphonic	Patch
@livekit/agents-plugin-openai	Patch
@livekit/agents-plugin-phonic	Patch
@livekit/agents-plugin-resemble	Patch
@livekit/agents-plugin-rime	Patch
@livekit/agents-plugin-runway	Patch
@livekit/agents-plugin-sarvam	Patch
@livekit/agents-plugin-silero	Patch
@livekit/agents-plugins-test	Patch
@livekit/agents-plugin-trugen	Patch
@livekit/agents-plugin-xai	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[CLAassistant]

All committers have signed the CLA.

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 7 additional findings in Devin Review.