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 records an interrupted event with 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. The false-interruption path records a playout_paused event when a barge-in pauses playout and a false_interruption event with lk.false_interruption.resumed when the timer resolves it.

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 request span gets a fallback_provider_failed event per provider that failed (lk.fallback.label, lk.fallback.index) and, on success, lk.fallback.label / lk.fallback.index for the provider that served the request. STT fallback is left for the deferred STT-events work since STT has no request span to hang these on yet.

Text input

A text_input event on agent_session (participant identity under PII, byte size) when a lk.chat text stream arrives.

• 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. fallback_provider_failed events and the serving run carry 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, LLM fallback events and the 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]

Found by Codex:

AgentActivity.start() creates long-lived background tasks in _start_session(). Because this span is current here, asyncio.create_task() copies it into those tasks. Detaching in finally only restores this task, so later STT or scheduling spans can still use the ended update_agent span as their parent. Could we keep the root context current while creating those tasks and pass the handoff context only to the lifecycle spans?