Skip to content

Refactor: Share the tool-call pairing between the timeline and the export - #2041

Merged
mrsabath merged 3 commits into
mainfrom
feat/toolcall-export-record
Nov 21, 2026
Merged

mrsabath merged 3 commits into
mainfrom
feat/toolcall-export-record

Conversation

@mrsabath

Copy link
Copy Markdown
Member

Step 1 of the toolCall export 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":

  • a call that ends the run by design and never gets a result (StructuredOutput, SubagentHandback, end_subtask)
  • an agent that moved on without the result
  • a run stopped by a <task-notification>
  • a result that lands before its asking response finished (clamped, not negative)
  • a result that only acknowledges a background job

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/toolpair is 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 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 (0.26–0.47 GB of text against 35–42 MB new, on real sessions). Options gates the outputs an export does not want, not the scan. The package is ~250 lines, not ~80.

Two things the boundary makes explicit

EndReason names why a call got no result, where Tool.Lost only said that it did. Its zero value means still open — a different fact from lost: one has no duration yet, the other never will. lostFor is 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 both stopped and abandoned. stopped now 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 0 ms call passes a durationMs > 0 filter and drags a p50 toward zero (spec T16). The regression suite caught this the first time the projection omitted it — four TestToolOf…IsLost tests plus TestLostSpansSurviveClip.

Performance, measured

BenchmarkBuild over the 6k-event fixture:

before after
time 7.01 ms 7.90 ms +13%
memory 6.48 MB 6.27 MB −3%
allocs 32,202 32,083 −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, not intuition — the first attempt was +42% time and +31% memory:

  1. A Call is 192 bytes, so letting its slice double copied megabytes per build.
  2. The pairing ran twice, once per package, until Result carried its Turns back for the timeline's own use. That alone was ~30% of a build.

TestBuildBudget still passes with headroom under -race.

Verification

Suite Result
go vet whole core module clean
Full core test suite 99 packages ok
-race on all 14 touched packages all ok
agentop TUI tool/timeline tests 152 pass
cmd/cortex, cmd/cortex-envoy, profile-tags build + vet ok
go mod tidy -diff × 7 modules all tidy
gofmt, pre-commit clean

Also green unchanged: core/sessionapi and all five importer packages (bob, claude, codex, opencode, pi), which exercise Build against real transcripts from five clients — the only coverage of the Imported() branch in the pairing.

Two unrelated pre-existing failures, verified identical on clean origin/main: three DST tests in cost/ledger and cost/usage (Cuba stopped observing the rule the fixtures assume — one failure says so itself), and two ServerPicker tests in agentop/tui. Worth someone pinning tzdata for the first set.

Reviewer notes

  • Two rec test helpers now coexist, one against core/pipeline in timeline, one against core/model in toolpair. 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.go gains toolpair at both sites, so a future core/pipeline import from it names the right package instead of blaming timeline.
  • agentop already reconstructs two of the new facts (EndsRun from Lost && endsRunTools[Name], Parallel from matching end timestamps). Exposing EndReason/SiblingN would need a timeline.Tool JSON change, so it is out of scope here and worth a follow-up.
  • Still to come on this branch: the ToolCall record and MCP hashing, walk integration, ?include=toolCalls and --with-tool-calls, the content tests, and docs.

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

…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>
@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You'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.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: dd42a3b3-645a-46c1-9f2b-9aa9a166cbf1
Commits

Reviewing files that changed from the base of the PR and between f409488 and 410966e.

Files selected for processing: 7

  • core/model/imports_test.go
  • core/session/timeline/agents.go
  • core/session/timeline/agents_lostfor_test.go
  • core/session/timeline/timeline.go
  • core/session/timeline/timeline_test.go
  • core/session/toolpair/toolpair.go
  • core/session/toolpair/toolpair_test.go
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

Share

…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>
@mrsabath mrsabath added the ready-for-ai-review Request automated AI code review from clawgenti label Nov 21, 2026
@mrsabath
mrsabath marked this pull request as ready for review November 21, 2026 00:43
@mrsabath
mrsabath requested a review from a team as a code owner November 21, 2026 00:43

@huang195 huang195 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread core/session/toolpair/toolpair.go Outdated
// 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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread core/session/toolpair/toolpair.go Outdated
CallIndex int
SiblingN int

// FIVE FIELDS BELOW HAVE NO READER YET, and are here for core/sessionexport (spec T23, T29,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread core/session/toolpair/toolpair.go Outdated
// 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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 clawgenti left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/...: clean
  • go test -race on session/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)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread core/session/toolpair/toolpair.go Outdated
// 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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 clawgenti left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. (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 about res.Jobs. The five closing cases are pinned by unit tests, so this is coverage rather than correctness; but the export will read Jobs, and a second fixture carrying a Command running in background with ID: result and its <task-notification> would make the differential cover the whole Result.
  2. (suggestion) The +13% has one owner, and it is not the shared scan. Here BenchmarkBuild goes 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 is CommonPrefix running twice per request — once in Calls() for the scan, once in buildAgents for resent — which the review at 84d4e09d flagged and this commit does not touch. Worth carrying into step 2 rather than leaving to a later perf pass.
  3. (nit) timeline's copy of the agent keys is an alias now, but the doc comment above UnseparatedAgent still describes the pre-#1459 traffic without saying that toolpair owns 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 at 410966ee
  • go test on session/timeline, session/toolpair, model, run twice: ok (no TestBuildBudget failure; one first-run flake at 56 ms on a cold cache, five consecutive clean runs after)
  • differential probe: Build() JSON, base 3847526 vs this head, testdata/claude-code-background-agents.json.gz — identical, 272,326 bytes each
  • unsafe.Sizeof probe: Call=192 Job=88 Return=64 Turn=32 Result=112
  • mutation 1 (lostFor without the open guard): 9 failures; mutation 2 (HasEnd covering ReasonStopped): 2 failures — both restored
  • BenchmarkBuild -benchtime=10x -count=3, both trees
  • both probes deleted; git status --porcelain empty

Generated by RepoMan github-pr-review@235a7f7 (https://github.com/rossoctl/agent-skills/blob/235a7f7620139ee3e4ab0872b8439591fe52e8c1/skills/github-pr-review/SKILL.md).

@clawgenti clawgenti left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/... and gofmt -l: clean
  • go test -race on session/toolpair, session/timeline, model, sessionapi, session/importer/... (all five clients plus sqlitecli): all ok
  • cmd/agentop: go build ./... and go 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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Good change. The comment around it is a bit off, though:

  • agentLabel doesn't exist in this package. agentLabel/agentLabelIn live in core/session (summary.go, fold.go) and have nothing to do with these keys. The comparison you mean is linkAgents' 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 UnseparatedAgent drifted, the c.agent != UnseparatedAgent guard on the resent line would stop excluding the shared bucket, so its turns would start being flagged as retries. linkAgents would also miss the case, 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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. 🙂

mrsabath added a commit that referenced this pull request Nov 21, 2026
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>
mrsabath added a commit that referenced this pull request Nov 21, 2026
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>
@mrsabath
mrsabath merged commit 0847c58 into main Nov 21, 2026
38 checks passed
@mrsabath
mrsabath deleted the feat/toolcall-export-record branch November 21, 2026 02:18
@github-project-automation github-project-automation Bot moved this from New/ToDo to Done in Rossoctl Issue Prioritization Nov 21, 2026
mrsabath added a commit that referenced this pull request Nov 21, 2026
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>
mrsabath added a commit that referenced this pull request Nov 21, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-ai-review Request automated AI code review from clawgenti

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants