feat(desktop): add Token Usage screen for AI provider limits, cost & usage

Closed
IK
3mo ago
+2321-1

What & why

fixes #5733

Adds a Token Usage screen to the desktop sidebar that shows, per AI provider, how much quota is left, when it resets, and 30-day cost — so you can see you're about to hit a rate limit before an agent run does.

Everything is computed on-device. No telemetry, nothing sent to Superset servers; credential files are read-only and refreshed tokens stay in memory.

What's included

  • Main-process collector (src/main/lib/usage/) — polls providers every 5 min, persists the last snapshot to ~/.superset/usage-snapshot.json, emits updates over an EventEmitter. Per-provider 10s timeout, 429 backoff, last-good-value fallback.
  • Real limit data (verified live):
    • Claude — reads the live OAuth token from the Claude Code-credentials Keychain entry and harvests the anthropic-ratelimit-unified-{5h,7d}-* headers from a minimal /v1/messages probe → real 5-hour + weekly windows with reserve/pace projection.
    • Codex — reads the rate_limits snapshot Codex writes into its rollout session logs (passive, zero quota cost) → real weekly/monthly + Spark windows, credits, and plan.
    • Copilot / Gemini — show identity/cost or a "not signed in" state until authed (no fabricated data).
  • Cost stats estimated locally from CLI logs at API rates, with a bundled pricing table (cache-read/write priced separately).
  • Ambient indicators — tray menu section + worst-window % tooltip, sidebar dot badge (amber ≥80%, red ≥95%), and 80%/95% native notifications. All toggleable from a settings popover.
  • tRPC router (usage.*) using the observable subscription pattern; renderer route at /usage.

No feature gating — it's a local utility that benefits every user running agents.

How I tested it

  • bun run typecheck and bun run lint both pass clean (lint exit 0, warnings-as-errors).

  • Claude limits verified live against a real Pro account — confirmed the anthropic-ratelimit-unified-5h/7d headers return real utilization + reset times.

  • Codex limits verified against real ~/.codex/sessions/**/rollout-*.jsonl files — confirmed rate_limits.primary/secondary, credits, and plan_type parse correctly.

  • Cost parsing validated against real ~/.claude/projects and ~/.codex logs; format guards return null (not a crash) on unknown shapes.

  • Renders safely with no provider credentials — every provider falls back to a "no data yet" state.

    Checklist

    • PR title follows conventional commits (type(scope): subject)
    • bun run lint and bun run typecheck pass (CI fails on lint warnings too)
    • "Allow edits from maintainers" is checked on fork PRs

Summary by cubic

Adds a Token Usage screen in the desktop app to show provider limits, remaining quota, and 30‑day cost so you can spot limits before runs fail. All data is computed on-device from provider headers and local CLI logs—no telemetry.

  • New Features

    • Main-process usage collector: polls every 5 min, 10s timeout, 429 backoff, persists last snapshot to ~/.superset/usage-snapshot.json, emits updates.
    • Providers: Claude (live unified 5h/7d headers via OAuth; plan/email), Codex (rate_limits, credits, plan from rollout logs), Copilot & Gemini (auth/plan state; no fabricated data).
    • Cost: local estimates from Claude/Codex logs with a bundled pricing table (cache reads/writes priced separately); 30‑day buckets and today’s spend.
    • UI: new /usage route with provider cards, rate‑limit bars, cost stats, and a 30‑day mini chart; “No data yet” strip for other agents.
    • Tray and alerts: tray section with per‑provider % and reset hints, “View details” action, tooltip shows worst %, sidebar dot badge (amber ≥80%, red ≥95%), native notifications at 80%/95%.
    • Settings: popover to toggle sidebar badge, tray percentage, and notifications; settings persisted per user.
    • API: usage.* tRPC router for get/refresh/subscribe plus settings; menu router gains navigate to open /usage.
    • Lifecycle: collector starts with the app and disposes on quit; tray menu/tooltip refresh on usage updates and setting changes.

  • Bug Fixes

    • Claude: surface probe failures as card messages and cancel probe response bodies to avoid socket leaks.
    • Cost data: align 30‑day buckets to local midnight and fall back to file modified time when Codex timestamps are missing.

Summary by CodeRabbit

  • New Features
    • Added a Token Usage dashboard with provider cards, cost/token summaries, daily activity charts, and rate-limit windows, plus a manual refresh action.
    • Added live usage tracking for major providers and a sidebar gauge badge that reflects the worst active window, with optional notifications.
    • Enhanced the desktop tray with provider usage/tooltips and a “view details” section, kept in sync automatically; added settings to control badge and percentage display.
  • Bug Fixes
    • Improved resilience for missing/expired credentials, partial/unavailable usage data, rate-limit backoff behavior, and approximate cost reporting.