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

[davidzhao]

What

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:

source	meaning
audio_activity	barge-in from VAD / STT activity
user_turn	a committed user turn preempting the reply
programmatic	session.interrupt(), a tool, teardown

The pipeline and say paths also stamp lk.playout.position, how many seconds had actually played when the user cut in. No events: the UI renders spans and attributes, so the interruption detail lives on the turn.

Agent handoff

update_agent() spans a new 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 and TTS)

The attempt span carries lk.fallback.label / lk.fallback.index for the provider that served the request; a failover shows as gen_ai.request.model (expected) differing from gen_ai.response.model (served) on the request span. STT fallback is left for the deferred STT-events work since STT has no request span to hang these on yet.

Text input

• keyterm_detection span around the keyterm-detection LLM pass (stt_context_options.keyterm_detection), nested under the agent_turn that answers the user message (the conversation event fires from that reply: it is the agent's work on the turn), falling back to agent_session when there is no reply. Its llm_request used to sit directly under agent_turn, looking like a second inference step. Attributes are counts only (lk.keyterms.count/added/removed) plus model and provider; the terms themselves stay in the session report as lk.pii.keyterms.

• Fallback adapters report who serves. FallbackAdapter.model / .provider (LLM, TTS, STT) follow the active instance: the primary before any traffic, then whichever last served, like metrics_metadata already did. llm_node, tts_node, start_agent_activity and the adapter's own request span therefore name a real model instead of FallbackAdapter/livekit. Because request attributes are stamped when a request starts, a failover mid-request is recorded on the response side: gen_ai.response.model and gen_ai.provider.name of the instance that answered are set on the adapter request span and on llm_node/tts_node when the node finishes. The serving run carries the instance's gen_ai.request.model and gen_ai.provider.name next to lk.fallback.label/index. Usage metrics needed no change: the inner streams already emit them with their own model and the adapters suppress their own.

Tests

tests/test_coverage_spans.py: barge-in source and playout position through a fake session, the update_agent span with drain/on_exit/start nested, the LLM fallback serving provider, and interrupt-source precedence.

Not in this layer

STT events on the turn (deferred behind eou_wait feedback), realtime session lifecycle, and IPC high-ping / CPU pressure events.

Stacked on #7134.

🤖 Generated with Claude Code

[chenghao-mou]

nit: I don't think this is used?

[chenghao-mou]

lgtm, two nits

[chenghao-mou]

I wonder if we should expose the source as a parameter here. We still call .interrupt() in the following cases:

• The realtime path and superseded-turn path still interrupt without setting audio_activity or user_turn. Both regressions failed.

[chenghao-mou]

we should record here too if this has pushed some audio.