feat(agents): add first-run diagnostics

[shizhigu]

Summary

• Add a structured diagnostics layer for first-run checks, with stable JSON output and Rich table rendering.
• Add python agent.py doctor with --json, --online, --deep, and --strict.
• Run lightweight preflight diagnostics before console, dev, start, and connect; only fatal results block startup.
• Add backwards-compatible plugin diagnostic metadata/hooks and initial metadata for OpenAI, Deepgram, Cartesia, ElevenLabs, Silero, and Turn Detector.
• Document the first-run workflow in the root README and examples README.

The default doctor path is intentionally side-effect-free: it does not create rooms, call model providers, download files, mutate env, or write local files. --online only does a safe LiveKit URL/connectivity check, and --deep only runs checks that plugins explicitly expose.

A few compatibility edges are pinned by tests: legacy plugins stay quiet, plugin metadata imports are lazy so plugin import remains compatible with older agents installs, console --text skips audio-device preflight, empty CLI credential strings do not clear AgentServer values, credential-like details are redacted in JSON output, and Python versions newer than the tested range warn instead of blocking.

Non-goals

• doctor does not validate provider tokens by calling provider APIs.
• doctor does not download model files or create LiveKit rooms.
• The plugin metadata is declarative; dynamic provider health checks can be added later behind explicit deep checks.

Tests

• uv run --extra mcp pytest tests/test_cli_doctor.py tests/test_plugin_diagnostics.py tests/test_plugin_diagnostic_metadata.py tests/test_drain_timeout.py
  • 35 passed
• make check
• git diff --check
• LIVEKIT_URL=wss://diagnostics-test.livekit.cloud LIVEKIT_API_KEY=api-key LIVEKIT_API_SECRET=api-secret uv run examples/voice_agents/basic_agent.py doctor --json

[CLAassistant]

All committers have signed the CLA.

[devin-ai-integration]

✅ Devin Review: No Issues Found

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

View in Devin Review to see 6 additional findings.