feat(usage): Cost & token analytics dashboard

[juanludataanalyst]

Overview

Add a Usage tab to the Houston desktop app that gives users visibility into their AI spending and token consumption across all agents, with real-time cost calculation based on Anthropic and OpenAI pricing.

Feature description

The new Usage view surfaces metrics that currently live hidden in session history files and makes them actionable at a glance:

• KPI cards — total spend, total sessions, cache efficiency %, avg cost per session
• Daily trend chart — bar chart of cost (or tokens when no pricing data) over the last 14 days
• Breakdown by model — token + cost share per model with progress bars
• Breakdown by agent — token + cost share per agent, with per-agent cache hit %
• Activity by hour — local-timezone histogram of when the user works
• Live cost calculator — accurate Anthropic pricing including cache_creation_tokens priced at 1.25× input, and cached read tokens at the discounted rate
• OpenAI / Codex support — gpt-4o, gpt-5, gpt-5-codex, o3, o4-mini family entries in the pricing table; automatic codex alias resolution

Implementation notes

• use-cost-analytics.ts — reads all session-result.json files from every agent folder; aggregates per-session cost using a PRICING table keyed on model prefix (longest-key-first to avoid prefix-match bugs)
• token-pricing.ts — pure pricing logic extracted for testability (no Zustand/Tauri deps), with Jest coverage for Anthropic and OpenAI edge cases
• date-utils.ts — shared isoToLocalDate that converts UTC ISO timestamps to local calendar dates; avoids streak miscounting for UTC-offset users (e.g. a UTC-5 user at 11 pm shows up in tomorrow's UTC bucket)

UI improvements needed

The initial implementation works functionally but has opportunities to improve visual consistency and theme support:

• Color palette — some accent colors (e.g. the bg-foreground/70 bars in the model/agent breakdown) don't use the Houston brand tokens (primary, accent). Progress bars and highlighted values should use the existing Houston design system colors.
• Dark / light theme — the SVG bar and line charts compute colors via getComputedStyle at mount time. If the user switches themes at runtime the chart colors can get stuck until the component remounts. The color resolution should be reactive to theme changes.
• Chart color — the bar chart currently inherits foreground from CSS variables, which is correct, but does not distinguish between cost bars and token bars visually. Using a contextual accent (e.g. primary for cost, muted-foreground for tokens) would add clarity.
• KPI card highlight — the highlight prop currently applies text-foreground font-semibold, which works, but aligning with the brand accent color would feel more intentional.

Related

• Builds on the session runner's TokenUsage struct (engine) which now exposes cache_creation_tokens
• See also: task timeline + time-saved ROI (separate issue/PR)