Repository navigation
Refactor: Share the tool-call pairing between the timeline and the export - #2041
Conversation
…port The export needs per-tool timing (#1906 §2), and the pairing that produces it already exists inside buildAgents. Closing a call correctly has five cases beyond "its result arrived" -- a call that ends the run by design, an agent that moved on, a run stopped by a notification, a result that lands before its asking response finished, and a result that only acknowledges a background job -- and five regression tests pin them. A second implementation would drift from those tests in the direction of plausible-looking latency figures, so core/session/toolpair is the one walk both consumers call. The message scan comes with it, and that is the price. Two closing cases are only knowable from message text, and that same scan is where the timeline's Returns and Jobs come from, so Result carries those too for the one consumer that wants them. It cannot be reduced to the task-notification match alone: it must skip the history each request re-sends, or it is quadratic in turns. Options gates the outputs an export does not want, not the scan. Two things the new boundary makes explicit that were implicit before: EndReason names WHY a call got no result, where Tool.Lost only said that it did not. Its zero value means still open, which is a different fact from lost -- one has no duration yet, the other never will. lostFor is the single place the two vocabularies meet. The precedence between stopped and abandoned was undefined here (one disjunction tested all three), and a call can satisfy both; stopped wins, as the more specific fact. No Lost value changes. A lost span ends at its start in the TIMELINE's projection, not in the pairing. The pane draws such a call as a tick and needs an end; the export must not carry a zero-length duration, since a 0ms call passes a durationMs > 0 filter and drags a p50 toward zero. The regression suite caught this the first time the projection omitted it. Cost, measured on BenchmarkBuild over the 6k-event fixture: 7.90ms against 7.01ms before (+13%), 6.27MB against 6.48MB (-3%), 32,083 allocs against 32,202 (-0.4%). The time is the shared scan; memory and allocations come out slightly ahead because both slices are now preallocated. Getting there needed two fixes the profile found rather than intuition: a Call is 192 bytes, so letting its slice double copied megabytes, and the pairing ran twice until Result carried its Turns back for the timeline's own use. TestBuildBudget still passes with headroom under race. The timeline suite, core/sessionapi and all five importer packages pass unchanged. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com>
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 48 minutes. View limit details
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. |
…osed Self-review of #2041 found six dead-code defects. Two mattered. The extraction left agentMessageRe, taskIDRe, backgroundRe, stoppedRe, progressPrompt and recapPrompt behind in the timeline with no readers: the live copies are in toolpair. Go does not report an unused package-level var, so vet passed and no test failed. The failure mode is the one the shared package exists to prevent -- someone widens taskIDRe to tolerate an attribute, edits the copy that compiles and reads as live beside the still-used spawnedIDRe, and nothing changes, because the pattern that runs is in the other package. The prompt literals are worse: they are matched against live traffic and get rewritten when Claude Code rewords them, and a stale edit there brings back the recap storm their own comment says cost 74 hours on one session. Deleted, with a note on spawnedIDRe saying why nothing comes back. lostFor named the no-result reasons, so it failed OPEN: a reason added to toolpair later would match none of them, read as "not lost", and render a call that ended without a result as still running, forever, on a pane whose job is showing what finished. It is now r != "" && !r.HasEnd(), which fails closed -- an unknown reason is lost until someone says otherwise -- and gives HasEnd its only caller, so one predicate decides the partition instead of two hand-kept lists. A test pins the direction and fails if it goes back to a list. Also dropped ReasonLost, which was documented, exported and never returned: every no-result case has a more specific reason, and a call with none of them is still open, which the zero value says. A reserved constant a producer never produces is a trap for the consumer this package was written for -- it would switch on it and ship a dead branch, or read it as the catch-all and miss the other three. The comment in its place says to add one alongside the code that returns it. Two smaller ones: agentOf's e.Inference nil check was unreachable and implied a nil tolerance that would have let the Client fallback invent a main-agent turn from a non-inference event, so it is a stated precondition now; and the five Call fields with no reader yet say which spec requirement they are for and why they are ungated where Arguments is not. Dropping four regexp compilations also took BenchmarkBuild from 7.90ms to 7.50ms, so the refactor is now +7% over baseline rather than +13%, with memory and allocations still slightly ahead. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com>
huang195
left a comment
There was a problem hiding this comment.
Summary
I found no behaviour change. I compared the old buildAgents with toolpair.Calls and closeCalls case by case. The old lastTurn is the maximum request At for each agent, and lastAsk is the same value. The endedRun key, the clamp, the Error flag, the Jobs and Returns order, and the spawn links are also the same. buildAgents is the only writer of t.Tools, so the new make drops nothing. The three comments below are suggestions. They do not block the merge.
I ran go vet, gofmt -l and go test -race on core/session/toolpair, core/session/timeline, core/model and core/sessionapi at 84d4e09. All of them pass.
Author: mrsabath (MEMBER — maintainer)
Areas reviewed: Go (core/session/toolpair, core/session/timeline, core/model)
Agent/IDE config (.claude/.vscode): none
Commits: 2 commits, all signed-off: yes
CI status: passing
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com
| // because two consumers need the same answer from the same events: | ||
| // | ||
| // - core/session/timeline draws the spans in agentop's Timeline pane. | ||
| // - core/sessionexport projects them to content-free records for GET /v1/export. |
There was a problem hiding this comment.
suggestion: This doc comment uses the present tense for core/sessionexport. At this commit, core/sessionexport does not import toolpair. The same problem occurs at line 213 ("core/sessionexport passes the zero value") and in the Arguments field comment ("which core/sessionexport does not set"). A reader can think that the export path is live and that it already has the privacy property. Write "will project" and "will pass", or add these sentences in the PR that adds the export caller.
| CallIndex int | ||
| SiblingN int | ||
|
|
||
| // FIVE FIELDS BELOW HAVE NO READER YET, and are here for core/sessionexport (spec T23, T29, |
There was a problem hiding this comment.
suggestion: No production code in this PR reads ResultSeq, CallIndex, SiblingN, ModelDur or ResultBytes. (AskedAt has readers.) The false paths of Options also have no caller except the tests. The comment says this clearly, but I recommend that you add these fields in the export PR. Then the export's tests set the shape of the fields, and this PR stays a pure move. If the spec changes (T23, T29, T30), an exported field with no reader must change in a second PR, because core/ is used outside this repo.
| // shared bucket, because pre-#1459 traffic cannot be told apart. | ||
| // | ||
| // Spelled here rather than imported from core/session/timeline, which is this package's | ||
| // consumer: the dependency runs the other way. The timeline re-exports its own copies. |
There was a problem hiding this comment.
nit: The comment says that the timeline "re-exports" these constants. But core/session/timeline/timeline.go:24 and :28 declare their own literals, "main" and "subagents". buildAgents compares the agent keys from toolpair with the timeline's UnseparatedAgent (the resent line). If one literal changes, that comparison fails silently. Declare them in the timeline as const MainAgent = toolpair.MainAgent and const UnseparatedAgent = toolpair.UnseparatedAgent. Then the comment is true and the two values cannot drift.
clawgenti
left a comment
There was a problem hiding this comment.
Summary
Dobra robota, Mariusz. The extraction does what the PR says. I didn't just trust the suite here: I wrote a throwaway test that dumps Build() JSON for the real background-agents fixture (with zero and non-zero now) and for the 6k synthetic session, then ran it on base 3847526 and on this head. The output is byte-identical on all three, 8 lost spans included. lostFor, the stopped-over-abandoned precedence, the exact-capacity t.Tools behind the spawn pointers, lastAsk vs the old lastTurn, and the endedRun-by-response-seq rule all check out against the old disjunction. Nothing blocks.
One thing to tease you about, because you profiled so carefully: the +13% is not "the shared scan". It's CommonPrefix now running twice per request, once in toolpair.Calls and again in buildAgents for resent. That's the same "pairing ran twice" lesson you already applied to Turns, done halfway. See inline, it's an easy one. There are also two small notes on comments.
Author: mrsabath (MEMBER — maintainer)
Areas reviewed: Go (core/session/toolpair, core/session/timeline, core/model import guard), tests, perf claims
Agent/IDE config (.claude/.vscode): none
Commits: 2 commits, all signed-off: yes
CI status: passing (annotations are only the usual cache/Node 20 warnings, no hidden test failures)
What I ran locally:
go vet ./session/... ./model/...: cleango test -raceonsession/timeline,session/toolpair,model,sessionapi,sessionexport: all ok- the same three core packages merged with current
main(f409488, which touches the timeline tests): ok - base vs head
Build()differential: identical BenchmarkBuild+ pprof, base vs head (see inline)
Na zdrowie, and on to step 2 🍻
| // commonPrefix is cheap here: the store interns message content, so equal strings | ||
| // usually share a backing array. | ||
| msgs := inf.Messages | ||
| k := toolpair.CommonPrefix(st.prev, msgs) |
There was a problem hiding this comment.
suggestion: Mariusz, you blamed the +13% on the shared scan, but pprof says it's this line. 😄 toolpair.Calls has already computed exactly this CommonPrefix(prev[agent], msgs), with the same per-agent prev and the same order, and here we compare the whole history a second time.
On my box (BenchmarkBuild, -benchtime=60x, with a CPU profile):
| base | head | |
|---|---|---|
| ns/op | ~26–30 ms | ~39–48 ms |
commonPrefix flat |
0.58 s (26%) | 1.31 s (37%) |
The prefix compare doubled, and that's the whole regression. Regexps and pairCalls hardly moved. The synthetic session probably doesn't intern its strings the way the store does, so real sessions should pay less, but it's the same "walked twice" trap the Turns field already fixed.
Cheap fix: put the prefix length on toolpair.Turn (e.g. Prefix int, the value before the UnseparatedAgent override), and here do resent := known && len(msgs) > 0 && tn.Prefix == len(msgs) && tn.Prefix == len(st.prev) && .... That also lets agentState.prev go. Not blocking, since TestBuildBudget has headroom, but the "time is the shared scan" line in the description isn't quite true as it stands, kolego.
| // shared bucket, because pre-#1459 traffic cannot be told apart. | ||
| // | ||
| // Spelled here rather than imported from core/session/timeline, which is this package's | ||
| // consumer: the dependency runs the other way. The timeline re-exports its own copies. |
There was a problem hiding this comment.
suggestion: "The timeline re-exports its own copies" is true, but the copies are literals (timeline.go:24,28: const MainAgent = "main", const UnseparatedAgent = "subagents"). They aren't aliases. buildAgents compares the agent that toolpair.agentOf produced against timeline.UnseparatedAgent (the resent check). So if someone renames one side, it compiles, passes vet, and the retry detection quietly switches on for the shared bucket. That's exactly the silent-drift story your own spawnedIDRe comment warns about. 😉 Timeline imports toolpair now anyway, so const MainAgent = toolpair.MainAgent (same for UnseparatedAgent) costs nothing and closes it.
|
|
||
| // Start is when the call began: the end of the response that asked for it, so EVERY call has | ||
| // one, including a call that never finished. Derived as the asking request's At plus the | ||
| // response's measured Duration — never from the response event's own timestamp, which is |
There was a problem hiding this comment.
nit: "never from the response event's own timestamp" — but ResponseEnd does fall back to resp.At when Duration == 0. Maybe "from the response event's own timestamp only when nothing measured the response". The export will read these docs as a contract, so never deserves to actually mean never. Same spirit: "core/sessionexport passes the zero value" (l.213) and "which core/sessionexport does not set" are written in the present tense about code that lands in step 2. A "will" would keep a reader from going to look for it.
Addresses @huang195's three suggestions on #2041. The agent keys were spelled twice. toolpair assigns "main" and "subagents", and the timeline declared its own literals with the same values -- then compared the keys it was handed against its own copy (buildAgents' resent line, agentLabel). Two literals that must be equal and live in two files drift in silence: the comparison stops matching and every subagent turn reads as a fresh agent, with no compile error anywhere. The timeline's constants now alias toolpair's, so the values cannot differ and the package doc's claim about where they are defined is true. The package doc used the present tense for core/sessionexport, which does not import this package yet, so the privacy property it describes read as shipped rather than designed. Every such claim now says which PR will hold it, and Options notes that its false paths have no caller but the tests for the same reason. On the five fields with no production reader -- ResultSeq, CallIndex, SiblingN, ModelDur, ResultBytes -- I kept them rather than deferring to the export PR, and said why in the comment. Deferring means a second PR reopening Calls and closeCalls to carry values this walk already computes, and the tests that pin them belong with the pairing. The real point stands, though: core/ is consumed outside this repo, so they are external API from this commit. The comment now states the condition that makes the exposure acceptable -- the names and meanings are not settled until the export lands, and a spec change to T23/T29/T30 before then rewrites them here and breaks nothing, because nothing outside this module reads them. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com>
clawgenti
left a comment
There was a problem hiding this comment.
Cześć Mariusz! 🇵🇱 The commit on top answers the last round properly: comment-only plus const MainAgent = toolpair.MainAgent, no logic moved, and every claim in the new text checks out against the code it describes. My compliments especially on the "SHIPPED NOW RATHER THAN WITH THEIR READER" paragraph — a struct field with no caller today is exactly the thing that gets added quietly, and saying out loud that the names stay provisional until the export lands is the honest version of it. I checked that one too: ResultSeq, CallIndex, SiblingN, ModelDur and ResultBytes are each asserted in toolpair_test.go, and AskedAt is the one the timeline reads (spawn.turnAt), so "five" and "only AskedAt" are both right.
Credit first, and it is earned: the extraction is faithful, and I re-ran the differential at this head rather than the last one. Build() over the real background-agents fixture serialises byte-identically to base 3847526 — 308 tools, 397 turns, 9 returns, scanned=2831 on both sides, every span including the 8 lost ones. Call is exactly 192 bytes (unsafe.Sizeof), the number your profile-driven fix was built on. And the guards genuinely bite: deleting the r != "" half of lostFor fails 9 tests; adding ReasonStopped to HasEnd fails 2. Both mutations restored, both probes deleted, git status clean.
Must-fix: none. Nothing here blocks a merge.
The rest are suggestions and nits:
- (suggestion) The differential has no coverage of the Jobs path. The only fixture has
jobs=0— 397 turns and 308 tools, and not one background job — so byte-identity proves the calls/turns/returns projections and says nothing aboutres.Jobs. The five closing cases are pinned by unit tests, so this is coverage rather than correctness; but the export will readJobs, and a second fixture carrying aCommand running in background with ID:result and its<task-notification>would make the differential cover the wholeResult. - (suggestion) The +13% has one owner, and it is not the shared scan. Here
BenchmarkBuildgoes 32.5 ms → 39.9 ms (+23%, three runs each, same fixture), while B/op and allocs reproduce your figures exactly (6,482,093 → 6,271,167; 32,202 → 32,084). That isCommonPrefixrunning twice per request — once inCalls()for the scan, once inbuildAgentsforresent— which the review at84d4e09dflagged and this commit does not touch. Worth carrying into step 2 rather than leaving to a later perf pass. - (nit)
timeline's copy of the agent keys is an alias now, but the doc comment aboveUnseparatedAgentstill describes the pre-#1459 traffic without saying thattoolpairowns the value. One clause ("defined in core/session/toolpair; aliased here") would save the next reader the search.
Trzymam kciuki — this is ready. 🍻
Author: mrsabath (MEMBER — maintainer)
Areas reviewed: Go (core/session/toolpair, core/session/timeline, core/model import guard), tests, doc comments, perf claims
Agent/IDE config (.claude/.vscode): none
Commits: 3 commits, all signed-off: yes
CI status: in progress at this head — the new commit restarted the Go jobs (30 success, 6 running). Green at 84d4e09d (all checks pass).
Verified by:
go build,go vet ./session/... ./model/...,gofmt -l session/toolpair session/timeline: clean at410966eego testonsession/timeline,session/toolpair,model, run twice: ok (noTestBuildBudgetfailure; one first-run flake at 56 ms on a cold cache, five consecutive clean runs after)- differential probe:
Build()JSON, base3847526vs this head,testdata/claude-code-background-agents.json.gz— identical, 272,326 bytes each unsafe.Sizeofprobe:Call=192 Job=88 Return=64 Turn=32 Result=112- mutation 1 (
lostForwithout the open guard): 9 failures; mutation 2 (HasEndcoveringReasonStopped): 2 failures — both restored BenchmarkBuild -benchtime=10x -count=3, both trees- both probes deleted;
git status --porcelainempty
Generated by RepoMan github-pr-review@235a7f7 (https://github.com/rossoctl/agent-skills/blob/235a7f7620139ee3e4ab0872b8439591fe52e8c1/skills/github-pr-review/SKILL.md).
clawgenti
left a comment
There was a problem hiding this comment.
Summary
No i proszę, Mariusz: three commits in and the extraction is still a pure move. The new 410966e only changes comments and turns the timeline's two agent keys into aliases of the toolpair constants. The values are identical ("main" and "subagents"), they are still untyped string constants, and every reader in cmd/agentop/tui (timeline.MainAgent, timeline.UnseparatedAgent) compiles unchanged. So the byte-identical Build() result I checked on 84d4e09 still holds, and huang195's three points are addressed. Nothing blocks. Approving.
Two small notes are inline. Both are about the new comments, which is fair, since you write comments like contracts. 😉 My two notes on the previous round are also still open, and you pushed this commit three minutes after I posted them, so I think you didn't see them yet: agents.go:162 (CommonPrefix now runs twice per request, and that is where the +13% / +7% comes from, not the shared scan) and toolpair.go:145 ("never from the response event's own timestamp", while ResponseEnd does fall back to resp.At). I'm not posting them again. Neither one blocks. Szkoda tylko, bo the first one is the cheapest perf win in the PR.
Author: mrsabath (MEMBER — maintainer)
Areas reviewed: Go (core/session/toolpair, core/session/timeline, core/model import guard), the delta 84d4e09..410966e, CI
Agent/IDE config (.claude/.vscode): none
Commits: 3 commits, all signed-off: yes
CI status: passing. The only annotations are a cache-restore warning and a macOS queue notice. The Go CI jobs have no continue-on-error steps, so a green job cannot hide a failing test.
What I ran at 410966e:
go vet ./session/... ./model/...andgofmt -l: cleango test -raceonsession/toolpair,session/timeline,model,sessionapi,session/importer/...(all five clients plus sqlitecli): all okcmd/agentop:go build ./...andgo vet ./tui/: ok
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com
| const MainAgent = "main" | ||
| // | ||
| // ALIASED, NOT RESPELLED. core/session/toolpair assigns these keys and this package compares | ||
| // against them (buildAgents' resent line, and agentLabel). Two literals that must be equal and |
There was a problem hiding this comment.
nit: Good change. The comment around it is a bit off, though:
agentLabeldoesn't exist in this package.agentLabel/agentLabelInlive incore/session(summary.go,fold.go) and have nothing to do with these keys. The comparison you mean islinkAgents'switch id { case MainAgent: … case UnseparatedAgent: … }(agents.go:253-261).- "every subagent turn reads as a fresh agent" is not what drift would actually do. If
UnseparatedAgentdrifted, thec.agent != UnseparatedAgentguard on theresentline would stop excluding the shared bucket, so its turns would start being flagged as retries.linkAgentswould also miss thecase, so the bucket would lose its "subagents (not separated)" label and go through spawn matching like a real subagent.
The argument for aliasing is the same either way. Only the example should match the code. Something like (buildAgents' resent guard, and linkAgents' label switch) … the shared bucket's turns read as retries and it is linked as if it were a real subagent.
| // Adding them later means a second PR reopening Calls and closeCalls to carry values this | ||
| // walk already computes, and the pairing tests that pin them live here, not in the export. | ||
| // So the exposure is accepted on one condition: THESE NAMES AND MEANINGS ARE NOT SETTLED | ||
| // until the export lands. A spec change to T23/T29/T30 before then changes them here, and |
There was a problem hiding this comment.
nit: This paragraph says two things that don't fit together. Line 184 says "core/ is consumed outside this repo, so each one is external API from this commit". Line 189 says a later rename "is not a breaking change to anything — nothing outside this module reads them". The second claim is only true on the day of the merge. The moment someone outside this module reads SiblingN, it stops being true, and a Go comment buried in a struct doesn't warn them. If you want the "not settled" condition to hold, give the fields a marker that a reader actually sees, for example // Unstable: may change until core/sessionexport lands (#1906 §2). on each of the five. Otherwise just say it plainly: "a change before then may break an external reader, and that is accepted." Na razie it reads like a promise the package can't keep. 🙂
Addresses @clawgenti's second pass on #2009. Both must-fixes were places where the fourth revision's own new text claimed more than the code supports. "No case produces lost" was false. endStrandedTools is a FIFTH closing case this spec never mentioned: Build runs it after the pairing, and it gives a tool an End at a failed model-host dial without marking it Lost. So a call can have an end and none of the four reasons -- which T35 says cannot happen on an exported record, and which T17 would drop as still open. endReason gains `stranded`, with the duration it really has. The honest part of that fix is the implementation note: the pairing package cannot see this case today. core/session/toolpair was extracted from buildAgents alone, and endStrandedTools needs the agents, turns and hosts the pairing has none of. Either the host-failure times reach the pairing or the export applies the stranding pass over the records it is about to write; that is left Open rather than guessed, because it changes the pairing's inputs. The T10 fix left a hole. toolSource "unknown" was covered by neither T10 (built-in, verbatim) nor T11 (MCP, hashed), and the field table still said "the name, verbatim" without qualification. T10a says unknown follows T11: the branch is on "provably a built-in", never on "provably MCP", because a hashed built-in costs a reader one unreadable label where a cleartext MCP name costs a customer's identity. T10's own standard -- an implementer who reads one requirement and not the next still lands on the safe behaviour -- is what makes this a separate requirement rather than an inference. Also from that review: the guide's lost-span filter had the same blind spot as the first item, since a stranded span is neither lost nor open, so a reader filtering both still totals an outage as tool time; the #1924 row cited a claim 7.1 stopped making two revisions ago; and T35 said five fields where its table names six. Every code reference now names a symbol instead of a line. All eleven line pins were correct when written and wrong a day later, because #2041 moves every one of them into core/session/toolpair. A reader who checks a stale pin, finds unrelated code and stops trusting the rest is the failure this avoids. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com>
Addresses @clawgenti's third pass on #2009. The fifth revision added the stranded closing case and left it half-wired; this finishes it. The guide had the duration backwards. It said a stranded span's duration is the outage rather than the tool. It is the opposite: endStrandedTools exists to cut the outage off, and its own doc records that the dial it cuts at "fell within 0.1s of the tool's real end every time", after one 9-minute Bash drew as 8 hours. A reader following the old sentence would have discarded the one class of span the proxy has already corrected. What the guide should warn about is the RESULT, not the duration: a stranded span may have none, or one that arrived hours later, so "has an end and is not lost" does not mean "its result arrived". It also now says that only a failed dial is caught this way, so a long tail can still be an outage of another kind. T16 said "a call with no result carries no duration", which stranded contradicts. The rule is "no END, no duration": durationMs is present exactly when endReason.HasEnd(). A note keeps #2041 in step, where HasEnd is result || background today and must gain stranded, or omitempty drops the duration of a stranded call that measured 0ms. The late-result case is specified rather than left hanging. When the result does arrive, buildAgents ends the call on it and the stranding pass moves End back to the dial, so both reasons apply. stranded wins, because it is the one that explains the duration; resultSeq stays present, since a request did carry the result; and durationMs ends at the dial, not at resultSeq. That is the one place where those two disagree, and the callSeq/resultSeq row implied otherwise. Also: "a call with none of the four reasons still has End == nil" was the sentence the previous commit message itself called false, still sitting 15 lines below the paragraph that disproves it -- four to five, and the closing count of reasons-without-a-result recounted with stranded among them. The remaining `lost` wording in the record section is gone, since T31 has no such reason, and the toolpair references now say #2041's, because that package does not exist on main. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com>
The eighth revision's interim-behaviour paragraph said a stranded call exports as `abandoned` with no duration. That is one of three outcomes, and the smallest. Probed against #2041's `closeCalls` at `410966e`: - `closeCalls` checks for a result before every no-result reason, so a stranded call whose result arrived late exports as `result` with the outage inside `durationMs` — the 9-minute `Bash` that drew as 8 hours. That INFLATES the heavy tail, the opposite direction from the undercount the paragraph described. - A failed dial is a CONNECT with no `Inference`, which `pairCalls` skips, so it never advances `lastAsk`. A stranded call whose session never resumed keeps the zero reason and T17 drops the record whole. - Only the middle case — the agent asked again without the result — reads as `abandoned`. §10 now states all three in a table, and names the first as the one that matters for a tier table. Also this round: - §2.2 names `endStrandedTools` as a fifth case that runs after the pairing, so "reading that code is what sized this spec" covers the case that later broke it. The two references that pointed at §2.2 for the stranding route now point at §4.4a, where the two options are. - The `stranded` row drops the last unqualified "the duration is the tool's": the cut is matched by host, so another agent's blip can end a call early. The guide already says "usually"; the row now agrees. - "fifth closing case" is scoped to §2.2's count, since #2041's `toolpair` counts five of its own and `stranded` would be its sixth. - T35 keeps a measured zero for `inputBytes`, `resultBytes` and `gapMs` distinguishable from an unmeasured field. T14 reserves absence for "not measured" and T24 for an agent's first turn, so `omitempty` would turn an empty result into "not measured" and a sub-millisecond gap into "first turn". - T37's `user` gap is qualified: a background job from an earlier `Bash` can span one, so a duty cycle from `user` gaps is an upper bound on idleness. T27's sandbox-occupancy claim is scoped to foreground work. - "T31 is the one requirement NOT ready" is scoped to T28–T37 and says why T32's open row does not count. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com>
…cy claim (#2009) * Docs: Say the timeline already answers per-tool latency The export guide listed per-tool latency under what no export answers, two lines above the sentence that sends a reader to the timeline for names. A reader took the first as the capability being absent, when what is absent is only the names on a record: GET /v1/sessions/{id}/timeline pairs each call with its result by tool-use id and returns named spans with a start and an end, so the question is answered today, without a prompt. Keep both reasons names stay off a record, and state the limit as the shape it is -- a name list on a response record carries no tool-use id, so it could not pair. Add the two rules that cost accuracy when totalling those spans. A batch of parallel calls shares one window rather than carrying a duration each, so charging every member the whole window overcounts; measured at 15.7% of spans (42 of 267) on one 30-day archive. A lost span sets end equal to start and so passes an end != null filter as a 0 ms call. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Spec the toolCall export record #1906 asks for tool names on the record. Measuring it first changed the shape: a name list on a response record cannot carry per-tool timing, because the pairing key is the tool-use id and no record holds one, and 15.7% of tool spans (42 of 267, on a 30-day archive) share one window with the other calls of their batch rather than carrying a duration each. A list has nowhere to say that, so a consumer dividing a response's time by its toolCallCount is wrong for one call in six, in the direction that inflates. So the record is a sibling on the same NDJSON stream, discriminated by kind, carrying a paired duration with the batch marked explicitly. The tool-use id stays inside the proxy: the export ships the measurement the key yields, never the key. Record what the measurement found, since the design traces to it: inference is 80.3% of measured work (4.1:1 against tools), the heavy tier is 1.9% of calls and 55.4% of work, and Bash is 78% of calls but 97.4% of tool time. The two views reconcile to 2.2%, so a record derived archive-side will not contradict the timeline. Four items are left open for review, not guessed: whether an MCP tool name is gated or hashed, the opt-in switch, which of three places the pairing runs, and the per-session bound it needs. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Add the gap split and the collection/export boundary to the spec Two things the first draft buried, both raised in review. Nothing here needs new capture. Tool arguments and tool result content are already collected AND already on disk: archive/format.go interns ToolResults[i].Content and HistoryToolCalls[i].Arguments, so a 30-day archive holds every command line and every result. The export carries none of it by construction. A new 2.0 says so, because the rest of 2 read like a capability gap and it is not one: this is a projection change. It also separates the two decisions the first draft let blur, since "just export what we collect" is true for names and timing and false for arguments. Content is Tier 3, with redaction (#1921) and its own route (#1925), not a flag on this record. T0 pins that. The first draft also carried a tool duration with no inter-call gap at all, which cannot answer occupancy: a duration says how long the sandbox was busy, never how long it sat idle holding resources. 4.3a adds the split, and rests on the one asymmetry that makes it sound -- model time is MEASURED, so only the leftover gap needs classifying. modelMs copies the asking response's duration, gapMs is the time since the previous call ended, and gapKind names it user, tool or inference from toolCallCount, which is already in the record. The classifier is already validated: on the reference archive it split AskUserQuestion (p50 62.6s) from Bash (p50 201ms) by three orders of magnitude without seeing a tool name, and user wait is 72.6% of gap time -- idle that costs no sandbox occupancy, which is the whole point of separating it. Two limits come with it. An approval wait lands inside a tool gap and cannot be told from execution, which is the largest error in any density figure built from this (T26, 7.1a); and a user gap is meaningless without a stated ceiling, since the same data totals 24.8h at 300s and 539h uncapped (T27). #1924 is the fix for both, so 8 now says the two should be planned together. Correct 2.1 and 2.2 while here: today's record has no per-tool timing of any kind, and the timeline's pairing is derived, not stored. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Correct four measurement claims and redefine the gap Addresses @webchang's review on #2009, which read the draft against the code and against a converter written for it. Four claims were wrong. 7.1 contradicted 3.1. A span runs from the asking response's end to the next request carrying the result, and both boundaries are model traffic, so a tool that touches nothing on the network still gets a span -- 3.1's own Edit at p50 35ms is one. The "local calls are invisible" claim was #1810's gap classification misapplied, where no proxied traffic inside a gap is how a local call is INFERRED. 7.1 now states the real limit: the proxy sees the gap around a tool, never inside it. New 7.1b separates sizing the model leg from sizing a sandbox host, which this record cannot do -- a host is bounded by concurrent commands and the memory each holds, and no field here measures either. It carries the join keys for a sandbox-side record instead. 3.2 and 3.3 double-counted shared windows and priced AskUserQuestion as tool time. 3 now states three method rules and every figure is re-derived: the ratio moves 4.1 to 4.2:1, the long band 55.4% to 61.7% of work. The shared- window overcount is 1.9%, smaller than 3.4's span share suggests, because batched calls are short. New 3.5: durationMs is a client round trip including permission waits, which the first draft said only of the gap. So the ratio counts approval waits as tool time for any tool that prompts, and no rule in 3 removes that. 4.3a's gap was undefinable. T24's interval always contained modelMs while T25 classified a different one, so 5's example could not be checked against either. Now one named interval -- from the previous response's end to the next request -- with modelMs outside it by construction and the fourth gapKind dropped as an artifact of the old definition. Record shape follows: startedAt replaces at and is always present, so a call with no result can still be placed (T29); seq is gone, having collided with the event record's and been undefined for an unresolved call; callIndex orders a batch (T30); a closed endReason replaces the lost flag and names the timeline's four closing cases apart (T31). T28 gives event records an explicit kind. T32 says background jobs are out of scope rather than leaving it ambiguous. T33 drops a call whose asking response is below a since floor. Also: T11 takes a keyed hash, since a namespaced name is guessable and an unkeyed digest reversible; T10 exports a name verbatim, as the built-in vocabulary differs per client; T12 records that the 96-byte cut is bytes; T14 adds inputBytes; T9's planted secrets must cover message and result text, which the closing cases read; 1.1 calls /timeline content-light, not content- free, since Tool.Preview carries 80 runes of argument text. 10 splits into what the review settled and what is still open. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Say where a tool runs is unknowable, and mark a backgrounded call Addresses @webchang's three follow-ups on #2009. 7.1b was too narrow. The question is not whether a remote sandbox is involved, it is WHERE a tool runs, and a model proxy cannot see that at all: a built-in Bash, Read or Edit may run on the developer's machine or in a sandbox the agent sends its tools to, and an MCP tool may be served over stdio locally or over HTTP remotely. So the record measures each call as the AGENT saw it and says nothing about the work's location or its cost there. Each candidate host also measures the call differently -- a sandbox's own timing excludes the transport leg this record includes -- so the two disagree and neither is wrong. toolSource says what kind of tool it is, never where it ran, and the proxy must not infer a site from it. Cortex therefore specifies no sandbox-side record. T34 guarantees the join keys instead -- sessionId, startedAt, callSeq + callIndex, agentRole -- so a consumer holding a host's own records joins them on its side. T32 changes from "out of scope" to marked. A backgrounded call now ends background with durationMs measuring the acknowledgement only, so a count of those calls says how much tool time is missing instead of it hiding inside result. A job record is still left for later, with the warning that a backgrounded command overlaps later calls, so summed per-command time can exceed a session's wall-clock tool time. T3 and 3.3: banding is an analyzer's policy, not a property of the record. The export carries each call's raw durationMs and startedAt and names no bands, which also takes the short/medium/long naming question out of this spec. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Scope T10 to built-in names, and close the review's loose ends Addresses @huang195's and @clawgenti's reviews on #2009. Both found the same must-fix independently. T10 said a tool name is exported verbatim "whatever its source", which licensed shipping mcp__acme-billing-prod__refund in clear text and disagreed with T11's keyed hash two lines below. It is a privacy rule, so an implementer who reads one requirement and not the next has to land on the safe behaviour: T10 is now about built-in names and defers to T11 for the rest. The widened wording came from answering a different review point about per-client vocabularies; the scope was collateral. The rest were suggestions, all correct: endReason loses `lost`. No case produces it -- a call with none of the four reasons still has End == nil, which means still open, and T17 does not export an open call. A vocabulary entry a producer never emits is a trap for the consumer. The implementation dropped the same constant for the same reason. T35 names the five fields written even at zero. The export's zero-means-absent rule would otherwise drop a real callIndex: 0 -- the first call of every batch, and a T34 join key -- and a duration of 0 on a result clamped to its call's start. T28 is scoped to an opted-in stream. Adding kind to every record of a plain export would make T20's byte-identical promise false. inputBytes was defined in T14 and missing from both the example and the field table. T36 and T37 are new, from @clawgenti: modelMs and gapMs belong to the asking response, so every record of a batch repeats them -- summing modelMs counts a batch's inference parallelN times, in the numerator of T2's ratio, where durationShared does not mark it; and a response that asks for no tool produces no record at all, so an aggregate ratio needs the event records either way. A `tool` gap also overlaps the previous calls' own durations, so adding gap time to tool time double-counts the same wall clock. 2.2 claimed a background job extends a Bash span. It does not: the span ends at the acknowledgement and the job becomes a separate timeline.Job. T32 had it right, so the two contradicted each other, and 6's implementer would have looked for code that does not exist. Stale figures corrected to 3's: 4.2:1 rather than 4.1:1, over 97% rather than 97.4%, 14% rather than 15.7% in both the spec and the guide, and the 44.8 h gap total now names the 1800 s ceiling that T27 itself requires. The guide also said a batch always shares an end; it shares a start always and an end only when the results return together. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Name the stranded closing case, and hash an unknown tool source Addresses @clawgenti's second pass on #2009. Both must-fixes were places where the fourth revision's own new text claimed more than the code supports. "No case produces lost" was false. endStrandedTools is a FIFTH closing case this spec never mentioned: Build runs it after the pairing, and it gives a tool an End at a failed model-host dial without marking it Lost. So a call can have an end and none of the four reasons -- which T35 says cannot happen on an exported record, and which T17 would drop as still open. endReason gains `stranded`, with the duration it really has. The honest part of that fix is the implementation note: the pairing package cannot see this case today. core/session/toolpair was extracted from buildAgents alone, and endStrandedTools needs the agents, turns and hosts the pairing has none of. Either the host-failure times reach the pairing or the export applies the stranding pass over the records it is about to write; that is left Open rather than guessed, because it changes the pairing's inputs. The T10 fix left a hole. toolSource "unknown" was covered by neither T10 (built-in, verbatim) nor T11 (MCP, hashed), and the field table still said "the name, verbatim" without qualification. T10a says unknown follows T11: the branch is on "provably a built-in", never on "provably MCP", because a hashed built-in costs a reader one unreadable label where a cleartext MCP name costs a customer's identity. T10's own standard -- an implementer who reads one requirement and not the next still lands on the safe behaviour -- is what makes this a separate requirement rather than an inference. Also from that review: the guide's lost-span filter had the same blind spot as the first item, since a stranded span is neither lost nor open, so a reader filtering both still totals an outage as tool time; the #1924 row cited a claim 7.1 stopped making two revisions ago; and T35 said five fields where its table names six. Every code reference now names a symbol instead of a line. All eleven line pins were correct when written and wrong a day later, because #2041 moves every one of them into core/session/toolpair. A reader who checks a stale pin, finds unrelated code and stops trusting the rest is the failure this avoids. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Finish wiring stranded, and fix its duration in the guide Addresses @clawgenti's third pass on #2009. The fifth revision added the stranded closing case and left it half-wired; this finishes it. The guide had the duration backwards. It said a stranded span's duration is the outage rather than the tool. It is the opposite: endStrandedTools exists to cut the outage off, and its own doc records that the dial it cuts at "fell within 0.1s of the tool's real end every time", after one 9-minute Bash drew as 8 hours. A reader following the old sentence would have discarded the one class of span the proxy has already corrected. What the guide should warn about is the RESULT, not the duration: a stranded span may have none, or one that arrived hours later, so "has an end and is not lost" does not mean "its result arrived". It also now says that only a failed dial is caught this way, so a long tail can still be an outage of another kind. T16 said "a call with no result carries no duration", which stranded contradicts. The rule is "no END, no duration": durationMs is present exactly when endReason.HasEnd(). A note keeps #2041 in step, where HasEnd is result || background today and must gain stranded, or omitempty drops the duration of a stranded call that measured 0ms. The late-result case is specified rather than left hanging. When the result does arrive, buildAgents ends the call on it and the stranding pass moves End back to the dial, so both reasons apply. stranded wins, because it is the one that explains the duration; resultSeq stays present, since a request did carry the result; and durationMs ends at the dial, not at resultSeq. That is the one place where those two disagree, and the callSeq/resultSeq row implied otherwise. Also: "a call with none of the four reasons still has End == nil" was the sentence the previous commit message itself called false, still sitting 15 lines below the paragraph that disproves it -- four to five, and the closing count of reasons-without-a-result recounted with stranded among them. The remaining `lost` wording in the record section is gone, since T31 has no such reason, and the toolpair references now say #2041's, because that package does not exist on main. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Add the stranded caveats the last commit claimed were already there The sixth revision's message said the guide now warns about a stranded span's missing result and about only a failed dial being caught. It did not. The edit landed on the duration and stopped there, and the message described the intent rather than the result -- the second time in this PR, so: verified by reading the rendered sections back this time, not by grepping for a phrase. The guide now carries both caveats. An end and no `lost` does not mean a result came back, so an error rate or a result-size join over those spans is counting something else; and only a failed dial is cut, so an upstream 502 or a client hanging up mid-handshake leaves its outage inside the span, and a long tail can still be an outage rather than a slow tool. Four smaller corrections, all from the same review: The stranding cut is matched by HOST, not by agent. Its documented shortcut is that a blip in any other agent, a parent included, ends a tool whose own branch had no success first -- so a subagent's long Bash can be cut where the main agent retried, and two agents stranded by one outage both end at its first failure. That bounds what `stranded` claims: cut at an outage this agent could not be proven to have survived, not at this agent's own failure. Worth naming, since the reason exists to explain a duration. The "every time" and "its next attempt on that host" wording overstated both and is gone. The reasons-that-can-occur-without-a-result count is recounted with `stranded` among them -- also claimed done last time and not done. `stranded` wins over `background` as well as over `result`: the cut can land before an acknowledgement too, and the reason that explains the duration wins. The durationMs row no longer says `stranded` has "an end without a result", which contradicted the late-result paragraph above it. T11a settles the HMAC key's lifecycle, which T11 left unsaid (CodeRabbit). Generated once on first use, 32 random bytes, 0600, read back unchanged, and never rotated: a key that changes re-labels every MCP tool from that point and splits one tool's history into two series a consumer cannot rejoin. A lost key is the same event, and the old labels are unrecoverable -- which is the property that made a keyed hash safe to ship. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Say resultSeq answers whether a result arrived, and that T31 is not ready Two must-fixes carried forward from the pass that landed 84 seconds before the previous push. The endReason field-table row said it was "the only thing that says whether a result arrived". Four other places in the same revision contradict it, and they are right: stranded occurs both with a late result and without one, so resultSeq is what answers that question. The row was introduced while fixing an unrelated nit about a derived flag, and it was the last place still disagreeing -- in the table an implementer actually builds from. Section 10 claimed nothing blocks implementation while T31's stranding route sat Open in two paragraphs and in no 10.2 row. It has the row now, names T31 as the one requirement not ready, and states the interim behaviour: a stranded call matches abandoned and therefore exports with no duration, and since a closed lid strands the long call rather than the short one, that undercount lands in the heavy tail. So 10.2 now says not to publish a tier table from these records until #2046 closes. Three smaller ones from the same review. The stranded row dropped the "no success in between" condition, which is what makes the dial a tool's end rather than any later failure. T11a's read-or-create is last-writer-wins for an export where it is not for the gateway -- two exports racing on first use would each generate a key and re-label the earlier one's MCP tools -- so the implementation note says to create under a lock or at service start. And the guide said a stranded span's duration IS the tool's, where the spec now correctly says usually: the cut is matched by host, so another agent's failure can end a call that was still running. The PR body is rewritten. It still carried the first draft's numbers -- 22 requirements, 4.1:1, 15.7% -- and listed four items as open that 10.1 settled, so a squash-merge from it would have shipped the oldest figures in the PR. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: State all three stranded outcomes, and fix the §2.2 route pointers The eighth revision's interim-behaviour paragraph said a stranded call exports as `abandoned` with no duration. That is one of three outcomes, and the smallest. Probed against #2041's `closeCalls` at `410966e`: - `closeCalls` checks for a result before every no-result reason, so a stranded call whose result arrived late exports as `result` with the outage inside `durationMs` — the 9-minute `Bash` that drew as 8 hours. That INFLATES the heavy tail, the opposite direction from the undercount the paragraph described. - A failed dial is a CONNECT with no `Inference`, which `pairCalls` skips, so it never advances `lastAsk`. A stranded call whose session never resumed keeps the zero reason and T17 drops the record whole. - Only the middle case — the agent asked again without the result — reads as `abandoned`. §10 now states all three in a table, and names the first as the one that matters for a tier table. Also this round: - §2.2 names `endStrandedTools` as a fifth case that runs after the pairing, so "reading that code is what sized this spec" covers the case that later broke it. The two references that pointed at §2.2 for the stranding route now point at §4.4a, where the two options are. - The `stranded` row drops the last unqualified "the duration is the tool's": the cut is matched by host, so another agent's blip can end a call early. The guide already says "usually"; the row now agrees. - "fifth closing case" is scoped to §2.2's count, since #2041's `toolpair` counts five of its own and `stranded` would be its sixth. - T35 keeps a measured zero for `inputBytes`, `resultBytes` and `gapMs` distinguishable from an unmeasured field. T14 reserves absence for "not measured" and T24 for an agent's first turn, so `omitempty` would turn an empty result into "not measured" and a sub-millisecond gap into "first turn". - T37's `user` gap is qualified: a background job from an earlier `Bash` can span one, so a duty cycle from `user` gaps is an upper bound on idleness. T27's sandbox-occupancy claim is scoped to foreground work. - "T31 is the one requirement NOT ready" is scoped to T28–T37 and says why T32's open row does not count. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> * Docs: Scope the user gap to its agent, and keep a backgrounded call marked Two consequences of the last commit, both caught in review. Each is a case where one field was carrying two facts. T37's `user` gap is AGENT-LOCAL. T25 classifies a gap from the previous response of the same agent, so a parent waiting on a human can have a subagent running a tool beside it, and the parent's gap is `user` either way. T25's `user` row said "Nothing else can be happening", which is false in that case and was false before this PR. Two things can run inside a `user` gap: a background job from an earlier `Bash` (T32), and another agent's tool or inference. So a `user` gap answers "was THIS agent idle", and a sandbox duty cycle has to union the busy intervals across agents instead; summed `user` gaps are an upper bound on sandbox idleness, not the figure. T25, T27 and T37 now agree on this. T32a adds `backgrounded`. §4.4a makes `stranded` win over `background` when both apply, which is right — `stranded` explains the duration — but `endReason` holds one value, so that rule silently deleted T32's per-call marking of a backgrounded command, for exactly the calls whose timing is already least trustworthy. A backgrounded `Bash` now sets `backgrounded: true` whatever its `endReason`, and a consumer counting missing job time filters on the field rather than the reason. The `endReason` field-table row no longer claims no separate flag derives from it. Also: the requirement count is 41 (T32a joins T10a and T11a), and §10's normative list names T32a. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Mariusz Sabath <mrsabath@gmail.com> --------- Signed-off-by: Mariusz Sabath <mrsabath@gmail.com>
Step 1 of the
toolCallexport record (#1906 §2): the pairing both consumers need, extracted so it exists once.Design:
2026-11-19-tool-call-export-record-design.md§6 Option A, in #2009 (docs-only, review that first). This PR is code-only; the two do not overlap.No behaviour change. The timeline produces byte-identical output — the existing suite is the gate, and it caught a real bug (below).
Why extract rather than reimplement
The export needs per-tool timing, and the pairing that produces it already lives inside
buildAgents. Closing a call correctly has five cases beyond "its result arrived":StructuredOutput,SubagentHandback,end_subtask)<task-notification>Five regression tests pin them. A second implementation would drift from those tests silently, in the direction of plausible-looking latency figures. So
core/session/toolpairis the one walk both call.What the extraction costs, honestly
The message scan comes with it. Two of those closing cases are only knowable from message text, and that same scan is where the timeline's
ReturnsandJobscome from — soResultcarries those too, for the one consumer that wants them. It cannot be reduced to the task-notification match alone: it must skip the history each request re-sends, or it is quadratic in turns (0.26–0.47 GB of text against 35–42 MB new, on real sessions).Optionsgates the outputs an export does not want, not the scan. The package is ~250 lines, not ~80.Two things the boundary makes explicit
EndReasonnames why a call got no result, whereTool.Lostonly said that it did. Its zero value means still open — a different fact from lost: one has no duration yet, the other never will.lostForis the single place the two vocabularies meet.It also settles a precedence the timeline left undefined: one disjunction tested
endedRun || lastTurn || stopped, and a call can satisfy bothstoppedandabandoned.stoppednow wins as the more specific fact. NoLostvalue changes.A lost span ends at its start in the timeline's projection, not in the pairing. The pane draws such a call as a tick and needs an end; the export must not carry a zero-length duration, since a 0 ms call passes a
durationMs > 0filter and drags a p50 toward zero (spec T16). The regression suite caught this the first time the projection omitted it — fourTestToolOf…IsLosttests plusTestLostSpansSurviveClip.Performance, measured
BenchmarkBuildover the 6k-event fixture:The time is the shared scan. Memory and allocations come out slightly ahead because both slices are now preallocated.
Getting there needed two fixes the profile found, not intuition — the first attempt was +42% time and +31% memory:
Callis 192 bytes, so letting its slice double copied megabytes per build.Resultcarried itsTurnsback for the timeline's own use. That alone was ~30% of a build.TestBuildBudgetstill passes with headroom under-race.Verification
go vetwhole core module-raceon all 14 touched packagescmd/cortex,cmd/cortex-envoy,profile-tagsgo mod tidy -diff× 7 modulesgofmt, pre-commitAlso green unchanged:
core/sessionapiand all five importer packages (bob,claude,codex,opencode,pi), which exerciseBuildagainst real transcripts from five clients — the only coverage of theImported()branch in the pairing.Two unrelated pre-existing failures, verified identical on clean
origin/main: three DST tests incost/ledgerandcost/usage(Cuba stopped observing the rule the fixtures assume — one failure says so itself), and twoServerPickertests inagentop/tui. Worth someone pinning tzdata for the first set.Reviewer notes
rectest helpers now coexist, one againstcore/pipelineintimeline, one againstcore/modelintoolpair. Deliberate: the timeline's are unexported and pipeline-flavoured, so sharing them means rewriting ~70 test functions inside the one change whose value is proving nothing moved. 30 lines is the cheaper duplicate. Promote if feat(authbridge): first-class OpenTelemetry for the proxy #505's OTLP emitter becomes a third consumer.core/model/imports_test.gogainstoolpairat both sites, so a futurecore/pipelineimport from it names the right package instead of blamingtimeline.agentopalready reconstructs two of the new facts (EndsRunfromLost && endsRunTools[Name],Parallelfrom matching end timestamps). ExposingEndReason/SiblingNwould need atimeline.ToolJSON change, so it is out of scope here and worth a follow-up.ToolCallrecord and MCP hashing, walk integration,?include=toolCallsand--with-tool-calls, the content tests, and docs.Assisted-By: Claude (Anthropic AI) noreply@anthropic.com