Skip to content

feat(settings): usage statistics page - #1300

Merged
xiaozhou26 merged 6 commits into
mainfrom
feat/usage-stats
Nov 15, 2026
Merged

xiaozhou26 merged 6 commits into
mainfrom
feat/usage-stats

Conversation

@xiaozhou26

Copy link
Copy Markdown
Contributor

Closes #1299

Summary

Adds Settings → Usage statistics: token usage across all conversations, by day and by model, fed by the new K-brain endpoint GET /v1/usage/stats (Stack-Cairn/K-brain#209, released in v0.107.34). The section shows only when the host can reach the endpoint; when the bundled K-brain lacks capabilities.usage_stats (or the route returns 404) it shows an "update LiveAgent" notice instead of an error.

  • Overview cards: total tokens (input / output), sessions and turns, active days and longest streak, top model, longest session, current streak, and estimated cost when K-brain can price at least one model (the card is hidden when costUSD is null).
  • Activity heatmap: last 52 weeks, Sunday first, 52 equal columns with no horizontal scroll, month labels on the week holding the 1st. Daily / weekly / cumulative views; weekly and cumulative highlight the whole column. Colour levels use quartiles of the active values in the current view, so one very large day doesn't wash out the rest.
  • Daily trend: last 7 / 30 days, gaps filled, one line per top model; the Y max is the highest single point among the lines shown. The tooltip shows the day total and each model.
  • Model distribution: donut plus per-model list (share, tokens, provider); more than six models fold into "Other models".
  • Compact units follow the locale (万/亿 in Chinese, K/M/B in English) with a "tokens" unit; numbers are monospace. Charts are hand-written SVG/CSS, no new dependency.
  • Plumbing: the desktop app calls K-brain directly (health check, then stats). The WebUI uses a new usage.stats gateway request (UsageStatsRequest / UsageStatsResponse, desktop capability USAGE_STATS_V1), relayed by the desktop host (Rust) or the gateway's own K-brain client (Go). Both relays return "unsupported" when K-brain lacks the capability. days is 1–1100 (the UI sends 371) and the browser's IANA time zone is passed as tz.
  • Release: bundled K-brain pinned to v0.107.34 (66a0e3f). All 8 asset hashes match the release's SHA256SUMS.

Screenshots

These were captured from the real app UI (the desktop frontend's Vite dev server in headless Chromium driven by Playwright, not the desktop window) against a real K-brain built from 66a0e3f with a temp HOME and data dir. The session data is synthetic: a seeded generator wrote 330 days of sessions in K-brain's session format, using made-up project names, model names (atlas-large, nova-pro, …) and prices. None of it is real usage. Every number on the page was checked against the /v1/usage/stats JSON fetched at the same time. The unavailable notice comes from the v0.107.32 release binary, which has no usage endpoint.

Light Dark
Heatmap tooltip Trend tooltip
Empty data dir K-brain without usage stats

Tests

  • node --test: usage logic and section tests in crates/agent-gui/test/settings/usage-stats*.test.mjs, 22/22 pass. They cover gap filling, Sunday-first weeks, cumulative series, month label anchoring, quartile levels, >6-slice folding, the Y-max rule, units and capability gating.
  • Gateway web usage-stats-settings.test.mjs plus a case in gateway-v2-adapters.test.mjs: 22/22 pass. The full WebUI pnpm test also passes.
  • Gateway Go: internal/kbrain/usage_stats_test.go and pbws/usage_stats_test.go; go test ./... passes.
  • Desktop Rust: cargo test --lib services::gateway, 126 passed.
  • pnpm typecheck:ui, typecheck:gui and typecheck:webui are clean, and pnpm lint is clean.
  • node --test scripts/release/verify-kbrain-packaging.test.mjs: 6 passed with the new pin.
  • End-to-end in the real app (see Screenshots):
    • totals, cards, model rows and both tooltips match the API;
    • Refresh picks up a newly added session;
    • an empty data dir shows the empty state;
    • an old K-brain, and a proxy that advertises the capability but returns 404, both show the update notice.

Known limitations

  • Usage from model calls that never become a stored message (compaction, review, failed requests) isn't counted per day, so totals can be slightly lower than a conversation's own counter.
  • A running subagent's usage appears only after it finishes.

Settings → 用量统计 shows K-brain's token usage across all sessions:
metric cards (total tokens, sessions, active days, top model, longest
session, current streak, and estimated cost when K-brain prices it), a
52-week Sunday-first heatmap with daily/weekly/cumulative views, a
7/30-day per-model trend and a model share donut that folds more than
six models into the top five plus "other models". Charts are plain
SVG/CSS on the settings tokens and work in light and dark themes.

The page is read-only. It loads when opened and on Refresh, shows
loading, error with retry, empty and "update to see usage" states, and
is listed only for hosts that can fetch usage.

- Desktop: checks /v1/health capabilities.usage_stats, then calls
  GET /v1/usage/stats?days=371&tz=<browser zone>.
- WebUI: new usage.stats request through the Gateway
  (UsageStatsRequest/UsageStatsResponse, desktop capability
  USAGE_STATS_V1). The desktop relay and the Gateway's direct K-brain
  relay answer "unsupported" when K-brain lacks the capability or 404s.
- Pure logic (parsing, gap filling, weeks, month labels, model merge,
  Y max, 万/亿 and K/M/B units) lives in lib/usage/usageStats.ts with
  node tests; Rust and Go relay tests cover the forwarding.
On the desktop, a K-brain that advertises usage_stats but answers 404 for
/v1/usage/stats now gets the unavailable state instead of an error, the
same as the desktop and Gateway relays.
K-brain accepts days=1..1100 for /v1/usage/stats. The desktop and Gateway
relays capped requests at 731; align them (the page still asks for 371).
A share of the busiest value let one large day push every other cell to the
lightest step. Levels now come from the 25th/50th/75th percentiles of the
values with usage in the current view (one sample per day for daily, per
week for weekly and cumulative). The largest value is always the top step,
so ties at the top and a map of equal values show at full strength.
@xiaozhou26
xiaozhou26 merged commit 11468af into main Nov 15, 2026
14 checks passed
@xiaozhou26
xiaozhou26 deleted the feat/usage-stats branch November 15, 2026 13:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Usage statistics page for token usage across sessions

1 participant