Add RubyLLM::Agents.track for multi-agent request grouping

[adham90]

Summary

• Adds RubyLLM::Agents.track block wrapper that collects every Result produced by agent calls inside it, aggregates cost/token/timing stats, and returns a TrackReport
• Injects shared request_id and tags into execution records automatically, enabling grouped observability
• Adds a Requests dashboard page to browse and inspect tracked multi-agent workflows
• Supports nesting, error capture, shared defaults (tenant, tags), and all 12 result types via a Trackable mixin

What's included

Core (lib/ruby_llm/agents/)

• Tracker — internal collector that accumulates Results during a tracked block using Thread.current
• TrackReport — public aggregation class with total_cost, total_tokens, duration_ms, cost_breakdown, models_used, errors, all_successful?, and more
• Results::Trackable mixin — included in all 12 result classes (text, embedding, speech, transcription, 8 image types) for automatic tracker registration
• BaseAgent integration — merges tracker defaults (tenant, tags) into agent options
• Instrumentation middleware — injects request_id and tags from the active tracker into execution records

Dashboard (app/)

• RequestsController with index (grouped by request_id, sortable, paginated) and show (execution timeline, summary stats)
• Views with consistent design matching the existing dashboard aesthetic
• Navigation links added to both desktop and mobile layouts

Example app & seeds

• SummarizeAgent + ClassifyAgent tracking examples with comprehensive usage docs
• 8 diverse seed request scenarios (customer support, content pipeline, error handling, batch processing, streaming conversation, multi-model, in-progress, single-agent)

Tests (TDD — 116 new specs)

• tracker_spec.rb — 10 specs for Tracker internals
• track_report_spec.rb — 30 specs for TrackReport aggregation
• result_tracking_spec.rb — 7 specs for Result hook across all types
• track_integration_spec.rb — 19 specs for .track method (nesting, errors, defaults)
• track_instrumentation_spec.rb — 5 specs for request_id/tags injection
• requests_controller_spec.rb — 8 specs for dashboard controller

Usage

report = RubyLLM::Agents.track(request_id: "support_123", tags: { workflow: "support" }) do
  summary = SummarizeAgent.call(text: ticket.body)
  category = ClassifyAgent.call(message: summary.content)
end

report.total_cost      # => 0.0023
report.call_count      # => 2
report.all_successful? # => true
report.models_used     # => ["gpt-4o-mini", "gpt-4o"]

Test plan

• All 116 new specs pass
• Full test suite runs with no new failures (4,242 examples)
• StandardRB lint passes
• Seeds run successfully in example app
• Dashboard pages render with seeded data

🤖 Generated with Claude Code