Repository navigation
feat(crew-log): serve the Context panel from the usage fold - #15367
Conversation
|
Intent: Make one session's Context panel answerable from a projection the crew log already feeds, so opening it costs one memoised fold read instead of parsing 14 days of every session's turn records. |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the one-time cold refold every slot's usage fold takes after upgrade (state_version +9 retires all savepoints) stays acceptable on long-lived, many-unit installations. Suggestions
[DESIGN-REVIEWED] 96edd70 Description read[DESCRIPTION-READ] d01f03647d39c6c33a42c627d3ad68a7857b0d766dc779da4b6180990b25e471 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The backward-clock unit-ordering fix covers only the usage fold; the timeline fold's identical front-trimmed window still rides the header clock. Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: make the Context tab answer from the crew log's usage fold instead of re-scanning every installation shard — a FIX (performance defect, cause-level: the duplicate
[FIRST-PRINCIPLES-REVIEWED] 96edd70 Description read[DESCRIPTION-READ] c5f493f5fdb83153528ad2af0e3494cea5f0b14da56e2fb48857c13f6f43fd49 That sha256 names the PR description this verdict read. Recompute it with |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsNo findings that block the merge. FINDING — website/src/pages/ContextBreakdownPanel.tsx:615 — FINDING — docs/system-specs/modules/metrics.md:1055 — the spec says the occupancy pair comes from the turn "that reported the largest occupancy" while [OPUS-REVIEWED] 96edd70 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
82b2186 to
4c907f1
Compare
4c907f1 to
c49a032
Compare
|
|
span=e8fb475c29c4 [WATCH] in-place row edit against
|
|
span=131784e56e85 [SUGGESTION] "self-heal" overstates the crew-log-off case -- fixed in
|
|
span=eb1e4f0bd577 item 3, occupancy pair duplicated across both stores -- rebutted, and the wording that invited it is fixed in
|
|
span=b7ae743a80d8 item 7, fields with no counted consumer -- needs-a-decision. The count is correct; what it implies is the question.
|
|
Branch ownership -- please do not push to
|
adbe1e6 to
d5d948f
Compare
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS Sessions recorded with the crew log off now get a permanently empty panel whose copy — "…recorded for this session yet." — promises data that will never come. Watch
[UX-REVIEWED] 96edd70 Description read[DESCRIPTION-READ] e7a1fae3bbd5cc34d620623a74176b5d5a0a1f0a40fef9092f0850a18fe6c83a That sha256 names everything this verdict read: the PR description, plus the 4 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
d5d948f to
f4bc098
Compare
d11fd25 to
cd4bc40
Compare
cd4bc40 to
a5c5bcf
Compare
|
Owned by conductor session chat-1875 (worker W-G3). Head
Tree verified locally: mypy clean (2007 files), flake8/isort clean on touched paths, 1145 scoped tests pass, gateway boot e2e turn passes. Please do not push or rebase this branch while this round runs. |
|
Owned by conductor session chat-1875 (worker W-G3). Head
Local gates: mypy clean (2007 files), flake8/isort/black clean, 1017 scoped tests pass, gateway boot e2e turn passes. Please do not push or rebase this branch while this round runs. |
|
Owned by conductor session chat-1875 (worker W-G3). Head GPT F1 ( Opus on |
|
Rebased onto main 9d98cba. New head: 985ab39 (still 2 commits, authors kept). One conflict, in test/test_crew_log_checkpoint.py, inside the
Checks on the rebased tree, all exit 0:
|
Opening one session's Context panel scanned up to 14 days of every session's
token records to find the rows belonging to that one slot. This serves the same
panel from a projection the crew log already maintains, so the read is one
memoised fold instead of a directory walk whose cost grows with every other
session on the box.
The `usage` fold gains a bounded per-turn window. Each row carries the turn's
composition as `label -> chars`, deliberately not the entry's own
`[{kind, chars, tokens}]` list: measured at the cap (200 rows x 64 sources with
labels at `TEXT_LIMIT`) the list shape is 3,319,357 B against 808,912 B for the
mapping, and the slot-fold cache's per-member ceiling is 995,342 B, so the list
shape does not fit. Per-turn per-source tokens also have no reader and are not an
independent measurement -- the writer derives each one from that source's chars at
a fixed ratio. `CONTEXT_TURNS_LIMIT` is 200, the same posture as `TIMELINE_LIMIT`
and defined beside it.
Occupancy rides on the ROW, as `used` with the `used_window` it was measured
against, rather than as one session-wide pair. The reader is bounded to a day
window and a session-wide maximum cannot be narrowed to it afterwards: on a long
session the fullest turn is usually older than every row in the span. The reading
comes from the provider on `turn/completed` rather than from `tokens.input`,
because billing sums every model call a turn made, so a tool-using turn bills
past the window it would be divided by.
Two guards scope that stamp, and neither covers the other's case. The `_closed`
seal tells two FINISHED runs of one ordinal apart, since each closer marks its own
tail run. A unit counter off `session/opened` tells apart a run that was never
closed at all: a unit cut off mid-turn leaves its rows unsealed, and the next
unit's same-ordinal turn would stamp an unmeasured turn with its own reading.
Removing the seal reddens the two attempt tests; removing the unit term or
freezing the counter reddens the cross-unit test.
Each row also carries its own `ordinal`, assigned before any truncation, so a
reader shows the turn's true number directly. No dropped-turn count rides on the
payload: a whole-session total applied to an array index cannot answer for a
narrower window, because the index counts only the rows still present AND inside
the window. That is what the count got wrong, so the count is gone rather than
rescoped, and the ordinal gap is the record of what was trimmed.
A row carries only what its one reader asks for. `tokens`, `tokens_estimated`,
`sources_omitted` and `step` are not on it: `context_trace` shapes rows to the
`ContextTrace` interface, which declares none of them, and a row's token count is
the writer's own fixed-ratio split of the same `chars` rather than an independent
measurement. The session-wide counts they would have duplicated -- `tokens`,
`estimated_turns`, `by_source` -- are accumulated separately and unaffected.
`context_trace()` now reads `read_slot_projection(slot, "usage")` and shapes to
the existing `ContextTrace` TypeScript interface. A contract test reads
`ContextBreakdownPanel.tsx` so the shape cannot drift from its only consumer. The
old scan is deleted rather than kept alongside for comparison. There is no
read-through fallback to the token shards: this release stops writing
`ctx_blocks`, and the scan was bounded to `days`, so a fallback would serve at
most that many days and then nothing -- a read path with a provable expiry date is
worse than none.
`context/composed` gains an optional `phase`, which the panel reads to split the
one-off session-start injection out before the chart scales. It is stated by the
composer, never derived here: the guess available to a fold, the first row of a
unit, is wrong for the rebuild a mid-session replay triggers. Existing rows
without it still fold, with a test.
`context/composed` and `request/configured` are emitted after every dispatch
gate, beside `on_turn_started`, so a refused turn leaves no phantom row. Only the
`usage` fold's `state_version` moves. #15078 is the trivial-rebase neighbour on
`_FOLD_STATE_PINS`.
One 200-row window with realistic 40-source rows measures 808,912 B at the cap.
Co-authored-by: kirocrew-agent <agent@kirocrew.local>
…, and count composition-less turns Reads the ``ordinal`` the fold assigns onto each context row so the Context panel shows a turn's true number and an exact "earlier turns not shown" count, independent of how many rows the window dropped or the day view excluded. Ranks the occupancy peak by the highest ``used / used_window`` ratio (the fullest turn) rather than the largest absolute ``used``, so a model switch that moves the window no longer crowns a proportionally-emptier turn; a reading with no stated window is not a valid peak candidate. Derives the ordinal from the durable turn history rather than a composition-only counter: a turn that ran but composed nothing (a refusal, or a turn reusing the prompt already in context) still consumes an ordinal, so the number a later row carries reflects every turn before it. The turn-composed signal is keyed on the closing turn's (unit, turn) identity, held as a JSON-native list so it survives a checkpoint round-trip. Bumps the usage fold state_version and re-records its savepoint pin.
|
buluoray
left a comment
There was a problem hiding this comment.
LGTM. I checked this at head 96edd70.
context_trace now does one memoised read of the slot's usage projection (dashboard/handlers/usage.py:777) instead of scanning every token shard for ctx_blocks. context_trace was the only reader of ctx_blocks on main, so nothing is dropped without a replacement. The peak is ranked by ratio (usage.py:883, used * peak_window >= peak_used * row_used_window). Composition-less and refused turns each take one ordinal through _count_turn_ordinal (crew_log/projection.py:1780, :1789), and the occupancy reach-back stops at the unit boundary and the seal. The composition is emitted only after every dispatch-gate refusal returns, so a refused turn writes nothing. Retained fields are bounded (200 rows, 64 sources per row, keyed labels, 10,000-key memo), and state_version is bumped so old savepoints refold cold. App callers still get the SEL-audited 404.
Mutations, each restored from a backup:
- comparing the peak on absolute
usedreddenstest_peak_is_the_fullest_ratio_not_the_largest_used_across_a_switch - dropping the composition-less ordinal advance reddens 3 tests, including
test_a_retried_composition_less_turn_takes_ONE_ordinal - dropping the unit check on the reach-back reddens
test_usage_an_interrupted_units_open_row_is_not_stamped_by_the_next_unit
Crew-log, context-trace and usage suites: 905 passed, 0 failed. Frontend vitest was not run here; I read the TSX.
The first-principles and UX CONCERNS are advisory. The timeline clock-ordering fix is a sibling fold outside this diff, and the empty-panel copy for installs with the crew log disabled, plus flatter charts for pre-upgrade sessions, are low-frequency UX follow-ups.
Merge order with #15781 (non-blocking, but whichever lands second must handle it): the two conflict in crew_log/projection.py, and the interaction is semantic as well as textual. #15781 charges slot-fold cache cells per row via _SLOT_FOLD_ROW_BYTES, and a fold missing from that table is charged one 64 KiB row. Here usage becomes a slot-read fold holding up to ~800 KB, and its size justification cites the radar ceiling #15781 removes. The rebase should give usage a count_rows and a measured row cost, keep this PR's state_version bump, and keep the usage branch in _slot_units_for_fold, which #15781's version does not have.
Problem / Motivation
Goal: Open the Context tab and get the same answer without reading two weeks of every session's turn records.
no linked issue: this came from a work item (CREW-18723), not a filed bug, and nothing
open covers it -- the nearest, #13232 and #4749, are about the SIZE of the context this
panel measures, which this PR does not change. The three numbers cited below (#14975,
#15078, #15183) are neighbouring PRs named for merge-order reasons, so none of them
should close when this merges.
To draw one session's context chart, the dashboard opened every token-usage
shard file in a 14-day window, parsed every line in each, and threw away all
but the lines belonging to that one session. The work scales with how busy the
whole installation has been, not with the session being looked at. On a machine
that runs many sessions, most of what it reads is other sessions' turns.
The same numbers were already being recorded a second time. Every turn writes a
context/composedentry to the crew log carrying the identical block sizes, andthe
usagefold already folds it -- but only into a running per-source total. Itkept no per-turn rows, so the panel could not be answered from it.
Why it matters
Every open of the Context tab pays for the whole installation's turn volume. It
gets slower as the machine is used more, and it is slowest exactly when someone
is debugging a busy session.
It also stored the injection breakdown twice, and only one copy was ever read: the
token row's
ctx_blocksandphaseexisted for this one reader and nothing else.Not a goal
comment on this PR). The earlier line "No change to what the panel shows or how it
looks. No frontend file is touched." is WITHDRAWN. The panel keeps its layout and its
set of sections. Two visible things change on purpose, both consequences of the fold
being the source: (1) each turn row is labelled with its true ordinal from the log
rather than a window-local index, so a session's "Turn 3" may read "Turn 43" after
upgrade; (2) the "earlier turns not shown" line derives from those ordinals and
therefore covers turns the fold's newest-200 window dropped as well as turns outside
the day filter.
ContextBreakdownPanel.tsxis in scope for exactly those two changesand the screenshot evidence shows them.
capture-session-breakdown.mjswas named inthe amendment as in scope too; in the end it needed no change and is not in this diff.
What changed (motivation → approach → change)
The reader was scanning for a fact the crew log already had. The
usagefold insrc/kiro_crew/crew_log/projection.pynow keeps the per-turn rows,context_traceinsrc/kiro_crew/dashboard/handlers/usage.pyis one fold read, andsrc/kiro_crew/crew_log/emit.pywithsrc/kiro_crew/crew_log/entry_types.pyrecord thetwo facts the panel needs and the writer already had.
context.turns, newest 200, oldest dropped firstturn/completedcarries the reading and its window as one paircontext/composedctx_blocks/phaseon the token rowA row stores
label -> chars, not the entry's own{kind, chars, tokens}list.Per-source tokens are the writer's own split of
charsandcontext.by_sourcealreadysums them. The fold is read per session key, so its state lands in the slot-fold cache,
ceiling 995,342 bytes. At every limit's maximum the shipped shape is 808,912 and the list
shape 3,319,357: it does not merely cost more, it does not fit.
context/composedrecordssession_startorper_turn. The chart pulls thesession-start injection out before scaling the bars: it is many times the size of every
other composition and would flatten them all. Only the composer knows which it built, so
it is recorded, not guessed -- the available guess, a session's first composition, is
wrong for the rebuild a mid-session replay triggers.
turn/completedcarries the provider's occupancy reading with the window it was takenagainst, and the fold stamps both onto that turn's rows. The Session Breakdown tree
divides one by the other, so both halves are load-bearing: token counts cannot be the
numerator (billing, summed over every model call, so a tool-using turn exceeds the window
it would divide by) and the denominator must come from the same turn, because a model
switch moves the window. It sits on the ROW because the reader is bounded to
daysand asession-wide maximum cannot be narrowed afterwards. Rows are REPLACED, not edited: the
fold shares row dicts with snapshots already handed to readers.
Each row carries its own
ordinal, assigned before truncation, so a reader shows theturn's true number and needs no dropped-turn count on the wire. A turn's ordinal is keyed
by its crew-log unit and turn number, and the unit moves only on the
session/openedthat starts a unit (
resumedfalse). A retry, a rewind, a regenerate and a re-attachmentafter a gateway restart all stay inside one unit, so each reads back the turn's ordinal;
only a new unit (a new session, or a compaction) starts a new key space.
History, and the crew-log switch. A session predating this fold reads with an
unstated
phaseand no occupancy until its next turn closes; that heals. One recordedwith the crew log OFF reads empty and stays empty while it is off -- this panel now
depends on that switch, which
api_context_tracestates. No shard fallback: this releasestops writing
ctx_blocksand the scan was bounded todays, so a fallback would serveat most that many days and nothing after.
The occupancy pair sits in both stores, unlike
ctx_blocks: it has four live readers(
context_occupancy,slot_turn_usage,cost_breakdown, the Telemetry drilldown).Only the
usagefold'sstate_versionmoves (per-fold versions landed in #14975), sothis retires that fold's savepoints and leaves the other five standing. #15078 adds a
different fold and edits the same
_FOLD_STATE_PINSblock, so whichever merges secondtakes a trivial rebase there; the folds do not overlap. #15183 edits
ContextBreakdownPanel.tsxbut not theContextTraceinterface, so the contract testbelow holds in either merge order.
test/test_usage.pyleaves.github/black-baseline.txt: formatting made itblack-clean, and the ratchet requires a graduated entry be pruned. 926 remain listed.
Backwards compatibility
Compatible: the payload gains a per-row
ordinaland keeps every field the paneldeclares.
ContextBreakdownPanel.tsxreads that ordinal; its tests andSessionBreakdownTree.test.tsxmove with it.turn/completedgainscontextas an OPTIONAL object, written only when the providerreported occupancy. The two synthesized closers (the in-process failed one and
crash-repair) cannot know it and continue to omit it, which is why it is optional
rather than required; a turn with no reading folds as unmeasured.
context/composedgainsphaseas an OPTIONAL field, and the writer omits the keyentirely when it has no phase to state -- which is the shape every entry already on
disk has.
test_a_composition_written_without_a_phase_still_foldspins that: itasserts the written entry carries no
phasekey, then that the entry folds, the turnreads as an unstated phase, and every other field is unaffected. Declaring the field
requiredor making the writer always stamp it both fail that test. Without it, oneupgrade would empty the panel for every session recorded before the field existed.
Breaking for one internal caller:
_build_token_recordandpersist_token_recordno longer accept
ctx_blocksorphase, and the row no longer carries them.Writer sweep on
origin/main @ ee817d5e6685f895933f7d366145bd0bca4f7c57: onecaller passed them (
chat_runner.py, updated here); a repo-wide grep finds noreader of either stored field outside the tests that pinned the write. Rows
already on disk keep both fields and stay valid JSON -- no reader looks at them.
Tests
test/metrics/test_context_trace.pyis rewritten to write a real crew log, sowriter, fold and reader are exercised together instead of three fixtures agreeing
with each other.
as a literal. The old code path is not kept alive to compare against -- two
implementations agreeing says nothing about either being right.
regenerate of turn 1 -- the regenerate reads ordinal 1 and the next new turn is 2.
Keying by the per-attachment counter instead gives 1, 2, 3.
(the fixtures bill far more than they occupy, so a peak taken from billing shows);
the window comes from the turn that produced the peak, proved with a session whose
fullest turn ran on a small window and whose later, emptier turn moved to a large
one; a reading whose window the provider did not state reports no window rather
than borrowing another turn's.
read_context_tokenswasunpacked into, read from the source. Nothing else here reaches that dict literal, so
a hardcoded
0would otherwise leave every test green and the panel empty.ContextBreakdownPanel.tsx's own interface text, so a field the panel declaresand the reader stops sending fails here. Each assertion carries a control proving
the extraction found a real interface.
oldest row first and reports how many.
measures under the slot-fold cache-member ceiling, and the rejected row shape
measures over it. The first test also compares its own window against one built
with a single shared value, because sharing understates the measurement downward
-- a ceiling check alone would still pass and the guard would go quiet.
phaseis additive: a composition written without the key still folds and readsas unstated, which is what keeps every crew log already on disk readable.
later zero window, a fold value that is not a context view. Each is a guard that
answers a damaged log, reached by planting the folded value.
Mutation passes drove the test set rather than the reverse. Survivors that became
tests: a later zero window taken as current, a row's recorded total replaced by the sum
of its blocks, a kept non-positive block, a kept undated row, and the runner passing a
hardcoded
0for the occupancy reading. One survivor became a code change instead --a first-seen branch whose window assignment a later peak almost always overwrote, so
the pair is now set in exactly one place and the untestable branch is gone. The budget
test likewise compares its window against a shared-value build, because sharing
understates the measurement downward and a ceiling check alone stayed green.
Manual verification
The fold and the reader were driven end to end over a real crew log outside
pytest: two turns composed with both phases, the payload read back, and every
field checked against what the writer recorded -- the same path the parity test
now pins.
Screenshots / video
The Context panel now reads its per-turn window from the usage fold, and review
surfaced two turn-history bugs the panel had to consume: the backend window drops
its oldest per-turn rows once a session passes 200 turns (session-start rows
are now preserved as the chart's anchor), and the "earlier turns not shown" count
has to be true for turns dropped by the fold as well as those the chart clips from
its own front. Each row now carries the
ordinalit was assigned before any trim,so the count comes off the first shown row's own number rather than a summed
whole-session total, which is what made the earlier arithmetic wrong on any window
narrower than the fold's. Below, the panel is driven with a session-start row plus
34 per-turn rows whose ordinals begin at 41: the chart shows the newest 30, keeps
the session-start injection listed above it, and the chip reads 44 earlier turns
not shown.
Committed under
temp-screenshots/rather than attached because the availablegh(2.62) predates--attach(2.99); the same-repo UX lane reads committedmedia under that path the same way it reads a description attachment.
Related Issues
N/A -- no tracked issue; this PR carries the context.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)