Add session recording exporter hook

[sairavuri-sudo]

Summary

Refs #5853.

This adds first-class hooks for third-party observability backends to consume completed session recordings and link exported artifacts back to the agent_session span.

Changes:

• Add public AgentSession.recording_path for the current session audio recording path.
• Add public RecordingExporter and RecordingExportResult types.
• Add recording_exporter= to AgentSession.start(...).
• Run the exporter during JobContext._on_session_end() after the existing LiveKit Cloud upload attempt.
• Attach exporter-produced lk.recording_url, lk.recording_id, and opt-in lk.recording_path attributes to the session span.
• Defer ending the job-scoped session span until session-end finalization has had a chance to attach recording references.

Security note: raw local paths are not emitted automatically. lk.recording_path is only set when an exporter explicitly returns a recording_path; exporters can prefer governed artifact IDs or signed URLs instead.

Testing

• uv run pytest tests/test_recording.py --unit
• uv run ruff check livekit-agents/livekit/agents/voice/recording_exporter.py livekit-agents/livekit/agents/voice/agent_session.py livekit-agents/livekit/agents/job.py livekit-agents/livekit/agents/telemetry/trace_types.py livekit-agents/livekit/agents/voice/__init__.py livekit-agents/livekit/agents/__init__.py tests/test_recording.py
• make type-check
• uv run pytest --unit

[CLAassistant]

All committers have signed the CLA.

[sairavuri-sudo]

@theomonnom @davidzhao I pushed a follow-up commit addressing the Devin review comments:

• deferred session spans are ended before a restarted primary session creates a replacement agent_session span
• recording_exporter now fails fast when it cannot run: outside an active JobContext or on a non-primary AgentSession

I reran:

• uv run pytest tests/test_recording.py --unit (30 passed)
• touched-file ruff check
• make type-check
• uv run pytest --unit (848 passed, 4 skipped)

Could one of you, or someone from the Agents team, confirm whether this API direction works? I am happy to adjust the shape or split out the smaller recording_path piece if that is easier to review.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🚩 OTel context token not detached on session close (pre-existing)

In _aclose_impl, self._session_ctx_token is never detached — it's only detached on restart in start() at agent_session.py:714-716. This means after a primary session closes, the OTel context token remains attached until the process exits or the session restarts. This is pre-existing behavior (the old code also didn't detach in _aclose_impl), so it's not introduced by this PR, but it's worth noting as the deferred span pattern makes this more visible.

(Refers to lines 1060-1069)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[sairavuri-sudo]

@longcw @chenghao-mou looping you in because this touches AgentSession/job session-end recording export and RecorderIO-adjacent lifecycle. CI is green, CLA is signed, and Devin’s introduced findings have been addressed in adb03a4.

Devin also flagged one OTel context-token cleanup item as pre-existing; I have left that out of this PR to keep the change focused, but can address it separately if maintainers prefer.

Would appreciate a quick API-direction check, especially whether the exporter-result shape, primary-session restriction, and trace attributes are aligned with the project direction.