feat(telemetry): interruption detail, handoff span, fallback events, text input

[davidzhao]

Port of livekit/agents#7137. Stacked on #2498.

Description

Smaller coverage gaps on existing spans, each of which came up when reading a trace and not being able to answer a question from it.

Interruptions. agent_turn carried a single lk.interrupted boolean. It now also carries lk.interruption.source, set by the caller that knows the cause: audio_activity (barge-in from VAD / STT activity), user_turn (a committed user turn preempting the reply), programmatic (session.interrupt(), a tool, teardown). The first cause wins. The pipeline and say paths also stamp lk.playout.position, how many seconds had actually played when the user cut in.

A cancelled preemptive attempt names why it was dropped too: SpeechHandle._cancel takes the cause like interrupt. An attempt superseded by more of the user's turn (a later preemptive trigger, or the transcript changing at commit) is user_turn, one dropped by a barge-in is audio_activity; a cancel with no cause (teardown, a pause) still reads as programmatic. A cloud export showed such attempts, cancelled while the user kept talking, labelled programmatic.

Agent handoff. updateAgent() spans an update_agent bar (parent agent_session) with lk.previous_agent_label and lk.agent_label. The old agent's drain_agent_activity (with on_exit inside) and the new agent's start_agent_activity nest under it. The initial start stays under session_start.

Fallback adapters (LLM, TTS, STT). FallbackAdapter.model / .provider follow the instance that serves next, so llm_node, tts_node and start_agent_activity name a real model instead of the adapter. The attempt span carries lk.fallback.label / lk.fallback.index, and a failover mid-request is recorded on the response side: gen_ai.response.model and gen_ai.provider.name of the serving instance on the adapter's request span and on llm_node / tts_node. Usage metrics needed no change.

Text input. A keyterm_detection span around the keyterm-detection LLM pass, nested under the agent_turn that answers the user message (falling back to agent_session), so its llm_request no longer looks like a second inference step. Attributes are counts only (lk.keyterms.count/added/removed) plus model and provider; the terms stay in the session report as PII.

Changes Made

• voice/speech_handle.ts: InterruptionSource, interrupt(force, source); voice/agent_activity.ts: recordInterruption, source threaded through every interrupt path, lk.playout.position; voice/agent_session.ts: update_agent span.
• llm|tts|stt/fallback_adapter.ts: nextInstance(), model / provider overrides, served-instance attribution; llm/llm.ts, tts/tts.ts: protected request-span getters.
• voice/keyterm_detection.ts: keyterm_detection span.
• telemetry/trace_types.ts: eight new attributes (none PII).

Adaptations from the Python source

• lk.agent_label / lk.previous_agent_label use agent.id.
• recordInterruption also stamps lk.interrupted=true: the JS say and realtime paths never set it before (only the pipeline reply did).
• STT: the now-unused _activeStt last-served tracking is removed with the getters that read it.
• Python's llm_fallback_adapter span name has no JS counterpart; the adapter's request span keeps the fixed llm_request name and is found through its llm_request_run child.

Testing

• New voice/coverage_spans.test.ts (barge-in source and playout position through a fake session, update_agent nesting, LLM fallback serving provider, first-cause-wins) and voice/keyterm_detection_span.test.ts; fallback adapter tests updated for next-instance identity; agent_session_handoff.test.ts accepts the threaded trace context.
• Full agents suite green; build, typecheck, lint, API report updated.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: cd08174

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

This PR includes changesets to release 39 packages

Name	Type
@livekit/agents	Patch
@livekit/agents-plugin-anam	Patch
@livekit/agents-plugin-anthropic	Patch
@livekit/agents-plugin-assemblyai	Patch
@livekit/agents-plugin-azure	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-did	Patch
@livekit/agents-plugin-elevenlabs	Patch
@livekit/agents-plugin-fishaudio	Patch
@livekit/agents-plugin-google	Patch
@livekit/agents-plugin-hume	Patch
@livekit/agents-plugin-inworld	Patch
@livekit/agents-plugin-krisp	Patch
@livekit/agents-plugin-lemonslice	Patch
@livekit/agents-plugin-liveavatar	Patch
@livekit/agents-plugin-livekit	Patch
@livekit/agents-plugin-meta	Patch
@livekit/agents-plugin-minimax	Patch
@livekit/agents-plugin-mistral	Patch
@livekit/agents-plugin-mistralai	Patch
@livekit/agents-plugin-neuphonic	Patch
@livekit/agents-plugin-openai	Patch
@livekit/agents-plugin-perplexity	Patch
@livekit/agents-plugin-phonic	Patch
@livekit/agents-plugin-protoface	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-plugin-soniox	Patch
@livekit/agents-plugin-tavus	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