Merge branch 'feature/hub-header-rates' into unify/skills-20261114

# Conflicts:
#	docs/requirements/README.md
#	orchestrator/templates/page-resources.js
#	orchestrator/templates/page-settings.js
#	skills/kvb-check-score/scripts/score.py
#	tests/test_resources_sample.py
This commit is contained in:
Kevin Veen-Birkenbach committed 2026-11-14 22:02:20 +00:00
commit f824ea27cf
28 files changed
+1449 -102

No files matched your search

+113
View File
@@ -0,0 +1,113 @@
# 014 - Header Rates
## User Story
As the operator, I want a chip in the hub's header that shows how much work
gets done, how many tokens it costs and how loaded the host is per minute,
hour, day, week, month, year or in total, so that I see the pace of the agents
at a glance on every screen.
## Decisions (operator-confirmed 2026-11-14; do not re-litigate)
1. **Rates per period**: the operator picks minute, hour, day, week, month,
year or total. Per period the chip shows the work items as three separate
kinds (register tasks done, commits, key results met), the tokens, and
the average CPU %, RAM %, VRAM (used and %), swap % and disk usage over
that period. Total means since records begin: totals for counts,
all-time averages for gauges.
2. **Exact windows on the server**: `/api/rates` returns one small JSON for
all periods, each window ending now. Sources: the sampler's
`samples.jsonl` and `tokens.jsonl`, the register's `rasci.json` (a task's
`end` once done) and the score journal `scores.jsonl` (a row with a sha is
a commit, counted once per remote and sha); the hub's existing readers
read them, no second parser.
3. **Daily buckets kept forever**: the sampler's retention folds rows older
than 90 days into one row per day, kept forever, with `mean_row` and the
bucket folding; a folded row carries `span`, the seconds its rows sampled,
and `width`, its bucket's seconds; the gauges weight every row by its span
(a raw row 60 s) and a row whose bucket straddles a window start by the
share inside. Token rows of a day that ended more than 90 days ago fold
into one row per day, agent and model with `width`, kept forever; a window
reaching back before the first token row is an estimate (≈, source total)
scaled from the token rows there are.
4. **KR met timestamp**: `rasci.py kr <task> met <n>` records `met_at` with
`stamp()` when the key result turns met, `open <n>` drops it. A key result
met without `met_at` stays so when met again, never counts in a window,
but counts in total. The commit table after a commit (`score.py
--commit-table <repo> --commit <sha>`) appends a journal row with the full
sha and the commit time unless one for that remote and sha exists, so the
commits count.
5. **Extrapolation from the next longer window**: a period without an event
of a kind takes the shortest longer window (hour, day, week, ..., total)
that holds some and scales it to the period; the chip shows it with ≈ and
names the source window in a tooltip, the API with
`approx: true, source: "<period>"`. Token rows are hourly, so the minute
always takes a longer window. Gauges never extrapolate; a gauge without a
sample shows n/a.
6. **Chip and popover**: the chip shows the period picker and 2 to 3 chosen
metrics; a click opens a table of every metric and every period. Period
and chip metrics persist in the hub settings (`rates`), which need no
passkey. The chip fetches `/api/rates` on the page's refresh tick at most
every 60 s.
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes" --> A1
subgraph A["🗄️ A · Data"]
A1["🧩 Daily folding, met_at, /api/rates, settings"] --> A2{"🧪 Unit and integration green?"}
A2 -- "🔴 no: fix" --> A1
end
A2 -- "🟢 yes" --> B1
subgraph B["📊 B · Chip"]
B1["🏷️ Header chip, popover table"] --> B2{"🧪 E2E green?"}
B2 -- "🔴 no: fix" --> B1
B2 -- "🟢 yes" --> BF{"💬 Operator feedback on screenshots?"}
BF -- "✏️ changes" --> B1
end
BF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
```
## Acceptance Criteria
### Data
- [ ] Each period counts the events inside its window; total counts every
event, also those without a time.
- [ ] A token row counts in a window by the share of its hour inside it.
- [ ] Gauges average every window across raw rows, 15-minute means and daily
means, each weighted by its span.
- [ ] An empty minute takes the hour, an empty hour the day, marked approx
with the source; a gauge without a sample is null.
- [ ] Retention folds days older than 90 days into one row each, idempotent,
and keeps them forever.
- [ ] `met_at` is set when a key result turns met, kept on a second met,
never added to one met before it existed, and dropped on open.
### Chip
- [ ] The chip sits right of the Live chip, shows the chosen period and
metrics and never widens the header at 1920, 1366 or 390.
- [ ] A period change and a metric swap persist over a reload.
- [ ] The popover opens on click and closes on Escape, a second click and a
click outside.
### Tests
- [ ] Unit: window sums and averages per period and row tier,
extrapolation, daily folding, `met_at`, the settings round trip.
- [ ] Integration: the hub serves `/api/rates` from fixture files.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: chip, persisted
period, popover open and close; screenshots for the checkpoint.
## Known Limits
- Tokens before the first token row are unknown; the windows reaching back
before it show a scaled estimate.
- A cold `/api/rates` call decodes every sample row; on a year of samples the
JSON decoding alone takes about 180 ms.
+1
View File
@@ -15,3 +15,4 @@ skill defines the format.
- [009 - Code Graph by Default](009-code-graph-by-default.md)
- [010 - Security Scan Cache per File](010-security-scan-cache-per-file.md)
- [011 - Test Result Cache](011-test-result-cache.md)
- [014 - Header Rates](014-header-rates.md)