feat(console): Analytics dashboard for cross-agent spend (#344)

[duyet]

First slice of #344 (part of #347): a dedicated Console Analytics page for cross-agent estimated spend, token mix, and declared delegation.

Rebased onto origin/main (2988ab72, includes Monitor #444, HITL #448, output_file #447). Does not close #344.

Why

Dashboard KPIs and the Usage tables are tenant-global and shallow. An operator with many agents cannot answer “who is spending?” or “who can call whom?” from one screen. The existing APIs already carry enough for an honest first cut.

Scope

• New /analytics route, sidebar item, command-palette entry (g y).
• Range chips 1d | 7d | 30d (default 7d) via GET /v1/usage?group_by=agent&days=N.
• KPI strip: estimated spend, tokens, sessions, agents with usage.
• Token mix by kind (not by model).
• Cost by agent (top 10 + Others) at the same Sonnet-class rates as GET /v1/agents/:id/stats.
• Daily trend: sandbox-active seconds area chart (what daily[] actually contains).
• Declared delegation from GET /v1/agents multiagent rosters. Ranked list always, compact SVG node-link on desktop.
• Docs: AGENTS.md, docs/features.md, landing Multi-Agent card.
• verify-oma recipe console-analytics for the signed-out gate. Rebase kept console-login-mobile from main.

Usage, Dashboard, CLI, and the control-plane API are unchanged. No charting library. No new endpoint.

Tradeoffs

usage_events has no model id, and daily[] is { date, active_seconds, runs } only. Scanning session event logs for call_agent_* would miss the “no new endpoint / page load < 2s” bar. This slice therefore:

• Estimates USD at Sonnet-class rates ($3 in / $15 out per MTok). Cache/reasoning tokens count in totals but are not priced, same as agent stats.
• Labels token mix as by kind, not by model.
• Charts daily sandbox seconds, not daily cost/tokens.
• Shows the callable-agent roster, not observed call counts (≥3). Call-count graphs need event-log aggregation (follow-up, still Console: Analytics dashboard — cross-agent cost, tokens, and delegation #344).

Those limits are labeled in the UI so the page does not pretend to have data we do not store.

Blast Radius

• Console nav and /analytics only (plus a one-line landing-card sentence).
• GET /v1/usage and GET /v1/agents are already used by Usage/Dashboard. Analytics adds a range-scoped usage fetch with staleTime: 5 min.
• Unauthenticated /analytics still hits AppShell and redirects to /login.
• Rebase conflict files: .cursor/skills/verify-oma/SKILL.md and control-oma.mjs (kept both console-login-mobile and console-analytics). Other likely-conflict surfaces auto-merged: AppSidebar, CommandPalette, AGENTS.md, docs/features.md, FeaturesSection.

Verification

• pnpm --filter managed-agents-console typecheck — pass (after rebase)
• pnpm --filter managed-agents-console test — 69 files, 496 tests pass
• Targeted: Analytics, snapshot, AppSidebar, Usage, AgentMonitorTab, AgentHub
• test/integration/recovery-do.test.ts “does NOT clobber its own heartbeat” — pass locally. Not in this PR’s diff. Prior CI failure on run 33789233067 treated as stale-base / flake; not rewritten.
• verify-oma (no secrets, Console only, API worker not started):
  • launch console → doctor → drive console-analytics
  • Signed-out /analytics redirected to /login; Welcome back visible
  • analytics-charts / analytics-empty skipped (no session)
  • Evidence: .cursor/skills/verify-oma/artifacts/2026-09-03T19-00-01-199Z/console-analytics/

  

Summary by Sourcery

Add a cross-agent Console Analytics view for estimated spend, token usage, activity, and declared delegation using existing APIs.

New Features:

• Add a Console Analytics page with selectable usage ranges, cross-agent spend and token KPIs, token-kind mix, per-agent cost rankings, daily activity trends, and declared delegation views.
• Expose Analytics through the Console sidebar, command palette, and keyboard navigation.

Enhancements:

• Document the Analytics page and clarify the existing Usage page's role and analytics limitations.

Documentation:

• Document Analytics data sources, estimates, token categories, daily activity metrics, and delegation semantics.

Tests:

• Add unit and page coverage for analytics calculations, rendering, range selection, error and empty states, navigation, and verification flows.

Chores:

• Extend the verify-oma Console recipe to cover the authenticated route gate and signed-in Analytics entry point.

[sourcery-ai]

Sorry @duyet, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 10 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 80045c8a-eb86-4a38-9b84-b0efc772e9a0

---

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.}

[sourcery-ai]

Reviewer's Guide

This PR adds a protected Console Analytics experience that derives honest cross-agent spend, token-kind, sandbox-activity, and declared-delegation views from existing APIs, with responsive no-library SVG visualizations, navigation/documentation updates, and focused unit, UI, and verification coverage.

Sequence diagram for loading the protected Analytics route

sequenceDiagram
    actor Operator
    participant AppShell
    participant Analytics
    participant UsageAPI as Usage API
    participant AgentsAPI as Agents API

    Operator->>AppShell: navigate to /analytics
    alt unauthenticated
        AppShell-->>Operator: redirect to /login
    else authenticated
        AppShell->>Analytics: render Analytics
        Analytics->>UsageAPI: GET /v1/usage?group_by=agent&days=7
        Analytics->>AgentsAPI: GET /v1/agents?limit=100
        UsageAPI-->>Analytics: usage summary
        AgentsAPI-->>Analytics: agent roster
        Analytics-->>Operator: render KPIs and SVG views
    end

Loading

Flow diagram for Analytics data derivation

flowchart TD
    Usage[Range-scoped usage payload] --> KPIs[KPI strip: spend, tokens, sessions, agents]
    Usage --> TokenMix[Token mix by kind]
    Usage --> Cost[Cost by agent: top 10 plus Others]
    Usage --> Daily[Daily sandbox-active seconds]
    Agents[Agent multiagent rosters] --> Delegation[Declared delegation edges]
    Delegation --> Roster[Ranked roster and desktop node-link view]

Loading

File-Level Changes

Change	Details	Files
Adds a protected cross-agent Analytics page backed by existing usage and agent APIs.	Registers the /analytics route and adds sidebar, command-palette, and g y navigation entries. Fetches range-scoped usage for 1d, 7d, or 30d with a five-minute cache, while independently loading agent rosters. Renders KPI cards, token-kind mix, Sonnet-rate estimated spend, top-10 agent costs with Others, daily sandbox activity, and empty/error/loading states. Documents that spend is an estimate, cache/reasoning tokens are unpriced, daily data is sandbox seconds, and delegation is declared configuration rather than observed calls.	apps/console/src/pages/Analytics.tsx apps/console/src/main.tsx apps/console/src/components/AppSidebar.tsx apps/console/src/components/CommandPalette.tsx apps/console/src/lib/route-chords.ts apps/console/src/pages/Usage.tsx AGENTS.md docs/features.md apps/web/src/components/FeaturesSection.astro
Introduces pure analytics transformation and SVG visualization utilities without adding a charting dependency.	Aggregates token kinds and estimates input/output cost using the existing Sonnet-class rates. Derives token mix, ranked per-agent cost, top-10 aggregation, usage-agent counts, daily buckets, and roster delegation edges. Implements responsive SVG area/line chart, token mix bar, horizontal cost bars, and desktop-only delegation graph components.	apps/console/src/lib/analytics-snapshot.ts apps/console/src/components/analytics/DailyAreaChart.tsx apps/console/src/components/analytics/DelegationRoster.tsx apps/console/src/components/analytics/HorizontalBarList.tsx apps/console/src/components/analytics/TokenMixBar.tsx
Expands automated coverage for analytics behavior, derived calculations, navigation, and signed-out verification.	Tests API query parameters, range switching, rendered analytics sections, error retry, empty periods, and absence of charting libraries. Tests cost/ranking, token aggregation, delegation edge resolution, and SVG path generation. Adds a console-analytics verify-oma recipe and explicitly distinguishes the authentication gate from session-required chart verification.	apps/console/src/pages/Analytics.test.tsx apps/console/src/lib/analytics-snapshot.test.ts apps/console/src/components/AppSidebar.test.tsx .cursor/skills/verify-oma/SKILL.md .cursor/skills/verify-oma/control-oma.mjs .cursor/skills/verify-oma/features/README.md .cursor/skills/verify-oma/features/console-analytics.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#344	Add a dedicated, navigable /analytics page with 1d/7d/30d selection, spend and token KPIs, cost-by-agent visualization, token distribution, and daily cost/token trends using inline charts.	❌	The PR adds the route, navigation, range selector, KPIs, cost-by-agent bars, and inline SVG charts, but it does not implement the requested model-based token distribution or daily cost/token trend. It instead shows token mix by kind and daily sandbox-active seconds, which the PR explicitly identifies as limitations.
#344	Provide an agent-to-agent delegation graph based on observed delegation events, showing labeled edges with call counts and only edges meeting the threshold of at least three calls, with a ranked-list fallback on mobile.	❌	The PR displays declared multiagent roster relationships rather than observed event-log delegation. Its edges have no call counts, no ≥3-call threshold, and therefore do not provide the requested delegation topology. It does hide the SVG graph on mobile and shows a list, but the underlying data does not meet the objective.
#344	Derive analytics from existing usage and event-log data without new backend endpoints or a charting dependency, while caching results and supporting the specified responsive behavior and performance target.	❌	The PR correctly uses existing endpoints, adds no backend endpoint or charting library, and configures a five-minute query stale time. However, it does not derive delegation from the event log, and the implemented page is a reduced first slice rather than the full responsive analytics experience described by the issue. The PR itself states that the missing by-model and observed call-count data require follow-up work.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sourcery assessment

Approved.