[AAASM-3509] ✨ (dashboard): Build the Cost & Budget page (replace ComingSoon)

[Chisanan232]

Description

Builds the real Cost & Budget page in the OSS dashboard, replacing the <ComingSoon name="Cost & Budget" /> stub at /costs. Implemented per design/v1/hi-fi/costs.jsx, composed entirely from existing OSS blocks:

• KPI strip — total spend / top consumer / budget utilisation / blocked-by-budget, derived from GET /api/v1/costs (useCostSummaryQuery) via the new pure deriveCostKpis helper. Daily/monthly aware.
• Per-team budget bars — TeamBudgetBar over joinTeamRows(overview, costs), with a Daily/Monthly period toggle (reused SegmentedControl). Green/amber/red is the shared bucketForBudget threshold (ok <80% · warn 80–95% · danger ≥95%).
• Per-agent cost breakdown — the reused analytics CostBreakdownPanel (own filter + query), as on /analytics.

Reused, not reimplemented: CostBreakdownPanel, useCostSummaryQuery / joinTeamRows (features/teams/api), TeamBudgetBar, budgetThreshold / bucketForBudget, SegmentedControl.

Note on data: the OSS /api/v1/costs summary only carries an org-level budget limit (TeamCostEntry has spend but no per-team limit), so per-team utilisation is each team's spend against the org limit — its share of the org budget — rather than a per-team configured limit. The design's budget-tree / sparkline / 7-day-history tabs depend on window.* mocks with no OSS data source and are out of scope for this page.

Light / dark: every colour is a theme token (--paper*, --ink*, --line*, --ok/--warn/--danger), which auto-invert under :root[data-theme="dark"]. No hex/white/black literals (verified by grep) — the bug class fixed in AAASM-3506/3507. The reused TeamBudgetBar and CostBreakdownPanel are already token-driven.

Type of Change

• ✨ New feature (replaces a stub; the ticket is filed as a 🐛 since the route shipped a placeholder)

Breaking Changes

• No

Related Issues

• Related Jira ticket: AAASM-3509

Testing

• Unit tests added / updated — dashboard/src/pages/CostsPage.test.tsx (vitest + RTL): KPI strip figures, red (danger) team bar at ≥95% burn, ok bar otherwise, period toggle switching to monthly figures, empty + error states, and the reused breakdown panel.
• Manual testing performed — N/A live (page is auth-gated and needs a running gateway); validated via the full suite + production build.

Local results (in dashboard/):

• pnpm type-check — clean
• pnpm lint — clean (--max-warnings 0)
• pnpm test — 144 files, 1271 tests passing (6 new)
• pnpm build — succeeds

Screenshots — light + dark (Playwright, local preview)

Light theme:

Dark theme:

Captured via Playwright on a local preview (mocked gateway) during UI review; committed under design/v1/screenshots/aaasm-3509/. Full evidence incl. the workflow video is attached to AAASM-3509.

Checklist

• Code follows project style guidelines
• Self-review of the diff completed
• Documentation updated if behaviour changed
• Commits are small and follow the Gitmoji convention

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 64.58333% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
dashboard/src/pages/CostsPage.tsx	64.51%	1 Missing and 10 partials ⚠️
dashboard/src/features/costs/costKpis.ts	64.70%	0 Missing and 6 partials ⚠️

📢 Thoughts on this report? Let us know!

[Chisanan232]

🔎 Review (Claude Code)

CI: ✅ green — CI Success, Dashboard tests + coverage (1271 tests), Dashboard build, aa-cli build compat (dashboard embed), CodeQL all pass. ❌ only codecov/patch (coverage acceptance, non-required) — ignorable.

Scope vs AAASM-3509: ✅ Matches. Replaces the <ComingSoon> stub at /costs with the real surface, composed from existing OSS blocks per design/v1/hi-fi/costs.jsx:

• KPI strip — total spend / top consumer / budget utilisation / blocked-by-budget (via deriveCostKpis over /api/v1/costs), daily/monthly aware.
• Per-team budget bars — TeamBudgetBar over joinTeamRows(overview, costs) with a Daily/Monthly SegmentedControl toggle; green/amber/red via the shared bucketForBudget threshold (ok <80% · warn 80–95% · danger ≥95%).
• Per-agent cost breakdown — the reused analytics CostBreakdownPanel.

Documented caveat — per-team bars are spend vs org limit: The OSS /api/v1/costs (TeamCostEntry) carries spend but no per-team limit, so each team's bar shows its spend against the org limit (its share of the org budget), not a per-team configured limit. This is clearly documented in the PR body, the page subtitle/hint ("daily spend vs org limit"), and the deriveCostKpis docstring. Assessment: acceptable for the OSS page — it's an honest representation of the only data the OSS API exposes, the limitation is surfaced to the operator in-UI, and the per-team configured-limit surface is a cloud feature (AAASM-398/1772). No silent misrepresentation. Recommend leaving a follow-up ticket if/when the OSS API gains per-team limits.

Front-end visual verification (Playwright, bundled Chromium, 1440×1024, network-mocked, ws aborted):

Check	Light	Dark
dataset.theme matches requested	✅ light	✅ dark
KPI strip populates ($842.37 / top agent / 84.2% / blocked=1)	✅	✅
Per-team bars render w/ correct colour coding (alpha 98% red · beta 85% amber · gamma 42% green)	✅	✅
Cost Breakdown panel present + legend totals computed ($640 / $415)	✅	✅
Body bg inverts (rgb 245,244,240 → 20,19,15), token-driven, no hardcoded colours	✅	✅
Layout intact	✅	✅
Console errors	0	0

Daily→Monthly period toggle verified live: total spend updates $842.37 → $18230.55 (recorded video attached to the ticket).

Minor (non-blocking) observation: in the full-page headless capture the Recharts bar series in the breakdown panel did not paint, although the legend totals computed correctly from the data — a known ResponsiveContainer 0-width-at-screenshot artifact in headless full-page mode, not a code defect (same component already ships on /analytics). Worth a quick eyeball in a real browser but not a blocker.

Evidence: costs-light.png, costs-dark.png, costs-period-toggle.webm attached to AAASM-3509.

Verdict: ✅ Ready — light + dark both PASS, scope matches the ticket, org-limit caveat is documented and acceptable, 0 console errors. CI green except the ignorable codecov acceptance check.

(UI review by Claude Code.)