feat: Agent phase observability — structured traces with frontend timeline

[ryaneggz]

Summary

• Adds spec and implementation plan for Agent Phase Observability & Trace Visualization
• Structured spans per agent phase (planner, generator, evaluator, handoff, tool_call, retrieval) with timing, token counts, model, cost, and error info
• Frontend swimlane timeline component for visual phase drill-down
• Optional OpenTelemetry OTLP export for external observability tools

Closes #904

Implementation Plan

Five phases outlined in .claude/plans/agent-observability.md:

1. Schema & Storage — Pydantic models, SQLAlchemy model, Alembic migration, repo layer
2. Span Lifecycle & Instrumentation — tracing.py utilities, @trace_phase decorator, context propagation
3. REST API — Thread trace endpoints with auth and pagination
4. Frontend Timeline — Swimlane visualization with colored phase blocks, hover tooltips, click drill-down
5. OpenTelemetry Export — Optional OTLP exporter, zero overhead when disabled

Test plan

• Unit tests for span lifecycle, context propagation, timing accuracy
• Unit tests for trace repo CRUD operations
• Integration tests for API endpoints (roundtrip create + fetch)
• Vitest component tests for timeline rendering and interaction
• Manual verification of timeline in thread view
• OTLP export verification with Jaeger (when configured)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6a417085-a3ee-43fb-93cd-018aa62e7ff4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agent-observability

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}