Files
pipelines/app/notes/run-tokens.md
T
alan d3a2369d1f Stage rows show cached share and cost; Changes explain no_patch_reason
Timeline stage rows add the cached share (when cache_known) and a positive
cost: 20.1M tokens · 97% cached · $1.42. The file viewer words each server
no_patch_reason, keeping the old truncated/binary text as the fallback.
2026-11-04 17:26:31 +00:00

52 lines
2.9 KiB
Markdown

# Run token usage beside size
Runs that spend 20M+ tokens now show it the way they show disk size.
## Server (payload)
- `RunSummary.usage` (`protocol.RunUsage`) moved up from `RunDetail`, so
`list_runs` rows carry the run total too. `get_run` still sends `usage` at
the same JSON key, now through the embedded summary.
- The list fills it with one grouped `step_usage` aggregate per 100-run batch
(`internal/pipeline/run_usage.go`), using the same column sums as the
history-wide stats (`usageSumColumns` in `stats.go`). It is joined to
`run_steps`, so orphaned usage rows (reported: about 650 rows, 1.47B tokens,
left by an Oct 19 history wipe) no longer count in stats or per-run totals.
The rows are not deleted. If a wiped run id was reused, an orphan row that
matches a new run's (run_id, sequence) still cannot be told apart.
- `StageUsage` now keeps `tokens_reasoning`, `cache_read` and `cache_write`
with `cache_known` (the runner dropped them before). They are JSON keys in
`usage_json`, so old rows need no migration: they lack `cache_known`, so
their cache share is unknown, not zero. Run totals add `cache_known_stages`
and `cache_known` (every token-reporting stage recorded the split).
## App
- `lib/features/runs/domain/run_tokens.dart`: parsing and formatting.
`22.4M tokens`, `≥9.1M tokens` when `tokens_known_stages < stages`. Nothing
is estimated, and a row without `usage` (an older server) shows nothing.
- List row: tokens after the size, in both the full and the compact subtitle.
- Sort: `Most tokens` (`most_tokens`) after `Largest first`, flat like it.
Runs without a reported total sort last.
- Summary: `Size on disk`, `Tokens` (`22.4M · 2.1M fresh, 20.3M cached ·
1.8M in, 240K out`; fresh is total minus cache reads, shown only when
`cache_known`) and `Cost`.
- Stage rows: the Timeline row subtitle adds `· 20.1M tokens · 97% cached ·
$1.42` (`stageTokenRowLabel`). The cached share (cache reads over the total,
rounded) appears only when the stage recorded `cache_known`; the cost only
when positive, to two places, `<$0.01` below half a cent. The visit facts
add `Tokens` and `Cost` (`Not reported` stays there).
- Cost is shown only when a positive `cost_usd` was reported. Subscription
models report `cost_known` with no amount, which shows as `Not reported`.
The stats page's `Reported cost` uses the same rule.
- `usage` is no longer treated as detail-only in
`RunsController.acceptRunDetail`, so opening a run refreshes its row's total.
## Evidence
Fixture: `tool/probe_usage_fixture.dart`, opt-in `?usage=1` on the capture
entry (run 7: 340 MB, 22.4M tokens, mostly cached, $1.42; run 6: partial
≥9.1M). Captures were taken with `tool/capture` at 560x1000 and 1400x900:
the list, the sort sheet, Most tokens, the run 7 Summary and Timeline, the
build and plan visits, and the no-usage (old-server) list and Summary.