docs(examples), test: fix first-run docs and timing flake

[shizhigu]

Summary

This keeps the examples first-run docs accurate and folds in the small AgentSession timing-test stabilization that was already opened as #5597.

The docs part fixes stale example paths and expands examples/.env.example so a new user can see the common LiveKit/provider variables without hunting through every example. The test part fixes the repeated CI failure this PR hit twice in tests/test_agent_session.py::test_tool_call: wall-clock event emission can be a little late under CI scheduler load, but duration/playback-position checks stay strict.

I folded #5597 into this PR so reviewers do not have to reason about a docs PR blocked by a separate test-only PR.

What changed

• Expanded examples/.env.example with commented, opt-in variables for common example categories.
• Fixed stale README paths in avatar and telephony examples.
• Removed voice-agent README entries for files that are no longer present.
• Updated the examples README Python version from 3.9 to 3.10.
• Split deterministic timestamp checks from wall-clock event timestamp checks in tests/test_agent_session.py.
• Kept early wall-clock assertions explicit while allowing a small extra late margin for event emission under CI load.

Testing

• make check
• PYTHONPATH="$PWD" uv run ruff check tests/test_agent_session.py
• PYTHONPATH="$PWD" uv run ruff format --check tests/test_agent_session.py
• PYTHONPATH="$PWD" uv run pytest tests/test_agent_session.py::test_generate_reply
• Earlier targeted run on this branch: PYTHONPATH="$PWD" uv run pytest tests/test_agent_session.py::test_tool_call tests/test_agent_session.py::test_interruption_before_speaking tests/test_agent_session.py::test_generate_reply tests/test_agent_session.py::test_preemptive_generation -q
  • 7 passed
• Earlier full file run on this branch: PYTHONPATH="$PWD" uv run pytest tests/test_agent_session.py -q
  • 20 passed
• git diff --check

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[shizhigu]

The current unit-tests failure is unrelated to this docs-only diff. It is the existing tests/test_agent_session.py::test_tool_call timing flake that also showed up on prior runs. I opened #5597 with a focused test fix so this PR does not need to carry unrelated test changes.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🟡 Incomplete transformation: wall-clock timestamp check not converted in test_start_boundary_does_not_block_vad_interruption

The PR systematically converts all check_timestamp(*.created_at - t_origin, ...) calls to check_wallclock_event_timestamp(...) to use asymmetric tolerance (tighter early, looser late) and stabilize CI flakiness. However, line 757 in test_start_boundary_does_not_block_vad_interruption still uses the old check_timestamp with the symmetric max_abs_diff=0.75 for a wall-clock created_at - t_origin comparison. The new function's docstring at tests/test_agent_session.py:1094 explicitly states: "Use this for created_at event timestamps; keep check_timestamp for deterministic pipeline durations, playback positions, and same-turn deltas." This test remains susceptible to the same CI flakiness the PR aims to fix.

(Refers to line 757)

---

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