From 416208214f4ccc46cb3f8641ad14695b960a6298 Mon Sep 17 00:00:00 2001 From: Mariusz Sabath Date: Fri, 20 Nov 2026 13:05:42 -0500 Subject: [PATCH 1/3] Refactor: Share the tool-call pairing between the timeline and the export MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Signed-off-by: Mariusz Sabath --- core/model/imports_test.go | 2 + core/session/timeline/agents.go | 316 ++++--------- core/session/timeline/timeline_test.go | 18 - core/session/toolpair/toolpair.go | 588 +++++++++++++++++++++++++ core/session/toolpair/toolpair_test.go | 348 +++++++++++++++ 5 files changed, 1013 insertions(+), 259 deletions(-) create mode 100644 core/session/toolpair/toolpair.go create mode 100644 core/session/toolpair/toolpair_test.go diff --git a/core/model/imports_test.go b/core/model/imports_test.go index c10c15f21..1b63247e5 100644 --- a/core/model/imports_test.go +++ b/core/model/imports_test.go @@ -18,6 +18,7 @@ import ( _ "github.com/rossoctl/cortex/core/session" _ "github.com/rossoctl/cortex/core/session/archive" _ "github.com/rossoctl/cortex/core/session/timeline" + _ "github.com/rossoctl/cortex/core/session/toolpair" _ "github.com/rossoctl/cortex/core/sessionexport" ) @@ -32,6 +33,7 @@ var dataOnly = []string{ "github.com/rossoctl/cortex/core/session", "github.com/rossoctl/cortex/core/session/archive", "github.com/rossoctl/cortex/core/session/timeline", + "github.com/rossoctl/cortex/core/session/toolpair", "github.com/rossoctl/cortex/core/sessionexport", "github.com/rossoctl/cortex/core/attribution", "github.com/rossoctl/cortex/core/parse/a2a", diff --git a/core/session/timeline/agents.go b/core/session/timeline/agents.go index 7374d1354..f47225c66 100644 --- a/core/session/timeline/agents.go +++ b/core/session/timeline/agents.go @@ -2,7 +2,6 @@ package timeline import ( "encoding/json" - "fmt" "regexp" "slices" "strings" @@ -10,6 +9,7 @@ import ( "unicode/utf8" "github.com/rossoctl/cortex/core/model" + "github.com/rossoctl/cortex/core/session/toolpair" ) // progressPrompt is the instruction Claude Code appends when it asks a model for a subagent's @@ -80,38 +80,89 @@ type toolArgs struct { To string `json:"to"` } +// lostFor maps a toolpair reason to this package's Lost bool. +// +// THE ONE PLACE THE TWO VOCABULARIES MEET. toolpair names WHY a call got no result (spec T31); +// Tool.Lost only says that it did not, because that is what agentop decodes and its JSON is a +// wire contract. A call still being waited on is NOT lost — it has no End at all — which is why +// the zero reason is absent from this list rather than defaulting into it. Changing either side +// means reading the other: toolpair.EndReason's doc, and Tool.Lost's. +func lostFor(r toolpair.EndReason) bool { + switch r { + case toolpair.ReasonEndedRun, toolpair.ReasonAbandoned, toolpair.ReasonStopped, toolpair.ReasonLost: + return true + } + return false +} + func buildAgents(t *Timeline, events []model.SessionEvent) { - calls := pairCalls(events) - if len(calls) == 0 { + // The tool calls, the background jobs and the subagent returns all come from one walk over + // the same events, in core/session/toolpair — shared with the export, which needs the same + // pairing and the same five closing cases. Everything below is what only a timeline wants: + // turns, the agent tree, and the spans' previews. + paired := toolpair.Calls(events, toolpair.Options{Returns: true, Arguments: true, AgentResults: true}) + if len(paired.Turns) == 0 { return } + // The same pairs toolpair already resolved: pairing decides each request's agent, drops the + // agent's own housekeeping calls and resolves a reused request id, and doing it twice over + // one session measured ~30% of a whole build. + calls := make([]call, len(paired.Turns)) + for i, tn := range paired.Turns { + calls[i] = call{req: tn.Req, resp: tn.Resp, agent: tn.Agent} + } + t.scanned = paired.ScannedBytes + for _, j := range paired.Jobs { + t.Jobs = append(t.Jobs, Job{Agent: j.Agent, ID: j.ID, ToolUseID: j.ToolUseID, Start: j.Start, End: j.End, Seq: j.Seq}) + } + for _, r := range paired.Returns { + t.Returns = append(t.Returns, Return{Agent: r.Agent, Into: r.Into, At: r.At, Seq: r.Seq}) + } + var spawns []*spawn + // EXACT CAPACITY, AND A SPAWN HOLDS A POINTER INTO THIS SLICE. One Tool per paired call, so + // the append below never reallocates and the &t.Tools[…] a spawn keeps stays valid until + // linkAgents has consumed it. Growing this slice later, or appending to it anywhere else in + // this function, would leave those pointers addressing a stale array. + t.Tools = make([]Tool, 0, len(paired.Calls)) + for i := range paired.Calls { + k := &paired.Calls[i] + var a toolArgs + _ = json.Unmarshal([]byte(k.Arguments), &a) + lost := lostFor(k.EndReason) + end := k.End + if lost && end == nil { + // A LOST SPAN ENDS AT ITS START HERE, where toolpair leaves it open. The two + // consumers want opposite things from the same fact: this pane draws a lost call as + // a tick on the axis, so it needs an end, while the export must NOT carry a + // zero-length duration — a 0 ms call passes a `durationMs > 0` filter and drags a + // p50 toward zero (spec T16). So the zero-length end is this projection's, not the + // pairing's. TestLostSpansSurviveClip and the four TestToolOf…IsLost tests pin it. + at := k.Start + end = &at + } + t.Tools = append(t.Tools, Tool{ + Agent: k.Agent, ID: k.ToolUseID, Name: k.Name, Start: k.Start, End: end, + Preview: preview(k.Name, a), Error: k.IsError, Lost: lost, Seq: k.CallSeq, + }) + if k.Name == "Agent" || k.Name == "Task" { + sp := &spawn{by: k.Agent, turnAt: k.AskedAt, desc: a.Description, typ: a.SubagentType, tool: &t.Tools[len(t.Tools)-1]} + if m := spawnedIDRe.FindStringSubmatch(paired.AgentResults[k.ToolUseID]); m != nil { + sp.childID = m[1] + } + spawns = append(spawns, sp) + } + } type agentState struct { first time.Time prev []model.InferenceMessage } agents := map[string]*agentState{} - jobs := map[string]int{} // background job id → index in t.Jobs var order []string - ends := map[string]map[string]*model.InferenceToolResult{} // agent → tool id → first result - endAt := map[string]map[string]time.Time{} - results := map[string]string{} // tool id → result text, for Agent calls only - agentTools := map[string]bool{} - seenReturn := map[string]bool{} - stopped := map[string]time.Time{} // agent → its latest : its run ended - // A run that ends with SubagentHandback returns twice: its at once, and a - // that Claude Code sends later, often with the parent's next request. - // handedBack: the agent's latest response called SubagentHandback. delivered: that report - // then reached a parent. A later request of the agent clears both: it runs again. - handedBack, delivered := map[string]bool{}, map[string]bool{} - var askedAt []time.Time // per t.Tools entry: when the request that asked for it started - var spawns []*spawn var calBytes, calTokens int64 // sums over the turns that set t.bytesPerToken for _, c := range calls { inf := c.req.Inference - delete(handedBack, c.agent) - delete(delivered, c.agent) st, known := agents[c.agent] if !known { st = &agentState{first: c.req.At} @@ -119,83 +170,12 @@ func buildAgents(t *Timeline, events []model.SessionEvent) { order = append(order, c.agent) } - // Tool ends: the first request in this agent that carries a tool's result. - for i := range inf.ToolResults { - r := &inf.ToolResults[i] - if ends[c.agent] == nil { - ends[c.agent], endAt[c.agent] = map[string]*model.InferenceToolResult{}, map[string]time.Time{} - } - if _, seen := ends[c.agent][r.ToolUseID]; !seen { - ends[c.agent][r.ToolUseID], endAt[c.agent][r.ToolUseID] = r, c.req.At - if agentTools[r.ToolUseID] { - results[r.ToolUseID] = r.Content - } - if m := backgroundRe.FindStringSubmatch(r.Content); m != nil { - if _, dup := jobs[m[1]]; !dup { - jobs[m[1]] = len(t.Jobs) - t.Jobs = append(t.Jobs, Job{Agent: c.agent, ID: m[1], ToolUseID: r.ToolUseID, Start: c.req.At, Seq: c.req.Seq}) - } - } - if m := stoppedRe.FindStringSubmatch(r.Content); m != nil { - if j, ok := jobs[m[1]]; ok && t.Jobs[j].End == nil { - at := c.req.At - t.Jobs[j].End = &at - } - } - } - } - - // Returns: scan only the messages this agent has not sent before. A conversation - // re-sends its whole history every turn, so scanning all of it is quadratic in turns - // (0.26-0.47GB of text on real sessions against 35-42MB new). - // - // Not for pre-#1459 subagent traffic: every subagent shares that one bucket, so each - // request's history differs from the last one's and every scan would be a full one. - msgs := inf.Messages - k := commonPrefix(st.prev, msgs) // A call that sends its predecessor's conversation unchanged added nothing: a retry. + // 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) resent := known && len(msgs) > 0 && k == len(msgs) && k == len(st.prev) && c.agent != UnseparatedAgent - if c.agent == UnseparatedAgent { - k = len(msgs) - } - for mi, m := range msgs[k:] { - if m.Role == "assistant" { - continue // an agent quoting the markers is not a delivery - } - t.scanned += len(m.Content) - for _, re := range []*regexp.Regexp{agentMessageRe, taskIDRe} { - for _, idx := range re.FindAllStringSubmatchIndex(m.Content, -1) { - from := m.Content[idx[2]:idx[3]] - tail := m.Content[idx[0]:min(len(m.Content), idx[1]+200)] - // Keyed by the message's position in the history as well as its text: a - // fork re-sends its parent's deliveries at the same positions, while a - // second, identically worded hand-back lands at a new one. - key := fmt.Sprintf("%s\x00%d\x00%s", from, k+mi, tail) - if seenReturn[key] { - continue // a fork inherits its parent's history, deliveries included - } - seenReturn[key] = true - // The notification after a delivered hand-back is not a return: it came a median - // 22s and up to hours later, and riding on the user's next prompt it labelled the - // user's time as waiting on the subagent. - if re == agentMessageRe && handedBack[from] { - delivered[from] = true - } - if re == agentMessageRe || !delivered[from] { - t.Returns = append(t.Returns, Return{Agent: from, Into: c.agent, At: c.req.At, Seq: c.req.Seq}) - } - // Only a notification says the run ended: an can arrive mid-run. - if re == taskIDRe && c.req.At.After(stopped[from]) { - stopped[from] = c.req.At - } - // A background job ends at the first notification naming it. - if j, ok := jobs[from]; ok && t.Jobs[j].End == nil { - at := c.req.At - t.Jobs[j].End = &at - } - } - } - } st.prev = msgs turn := Turn{Agent: c.agent, Start: c.req.At, Resent: resent, Seq: c.req.Seq, Model: inf.Model, requestID: c.req.RequestID} @@ -203,7 +183,7 @@ func buildAgents(t *Timeline, events []model.SessionEvent) { t.Turns = append(t.Turns, turn) continue } - end := responseEnd(c.req, c.resp) + end := toolpair.ResponseEnd(c.req, c.resp) turn.End = &end if out := c.resp.Inference; out != nil { turn.Finish = out.FinishReason @@ -225,23 +205,6 @@ func buildAgents(t *Timeline, events []model.SessionEvent) { } turn.Error = c.resp.Phase == model.SessionDenied || c.resp.Error != nil || c.resp.StatusCode >= 400 || failed t.Turns = append(t.Turns, turn) - if c.resp.Inference == nil { - continue - } - for _, tc := range c.resp.Inference.ToolCalls { - var a toolArgs - _ = json.Unmarshal([]byte(tc.Arguments), &a) - tool := Tool{Agent: c.agent, ID: tc.ID, Name: tc.Name, Start: end, Preview: preview(tc.Name, a), Seq: c.resp.Seq} - t.Tools = append(t.Tools, tool) - askedAt = append(askedAt, c.req.At) - if tc.Name == "SubagentHandback" { - handedBack[c.agent] = true - } - if tc.Name == "Agent" || tc.Name == "Task" { - agentTools[tc.ID] = true - spawns = append(spawns, &spawn{by: c.agent, turnAt: c.req.At, desc: a.Description, typ: a.SubagentType}) - } - } } if calTokens > 0 { @@ -261,48 +224,6 @@ func buildAgents(t *Timeline, events []model.SessionEvent) { } } - // Close each tool on its agent's first request carrying its result. Claude Code runs a - // tool while the response that asked for it is still streaming, so that request can be - // recorded before the response finished: clamp rather than draw a negative span. - // - // A tool that ends the run by design, with no result, ended it at the response that asked - // for it: a workflow agent stops at its StructuredOutput call, and no request carries that - // call's result. That response's other tools get no result either, and a workflow agent - // gets no notification to close them. A Bob subtask stops at its end_subtask call the same - // way. A response's tools share its Seq. - endedRun := map[uint64]bool{} - for _, tool := range t.Tools { - if _, ok := endAt[tool.Agent][tool.ID]; !ok && (tool.Name == "SubagentHandback" || tool.Name == "StructuredOutput" || tool.Name == "end_subtask") { - endedRun[tool.Seq] = true - } - } - si := 0 - for i := range t.Tools { - tool := &t.Tools[i] - if at, ok := endAt[tool.Agent][tool.ID]; ok { - if at.Before(tool.Start) { - at = tool.Start - } - tool.End = &at - tool.Error = ends[tool.Agent][tool.ID].IsError - } else if endedRun[tool.Seq] || lastTurn[tool.Agent].After(tool.Start) || stopped[tool.Agent].After(askedAt[i]) { - // The agent moved on without the result, or its run ended without it (the response - // ended the run, or the agent was stopped). The run can end while the asking response - // still streams, so compare the notification with that request's start. A resumed - // run's request starts after the earlier notification. - at := tool.Start - tool.End, tool.Lost = &at, true - } - if tool.Name == "Agent" || tool.Name == "Task" { - sp := spawns[si] - si++ - sp.tool = tool - if m := spawnedIDRe.FindStringSubmatch(results[tool.ID]); m != nil { - sp.childID = m[1] - } - } - } - first := make(map[string]time.Time, len(agents)) for id, st := range agents { first[id] = st.first @@ -397,93 +318,6 @@ func linkAgents(order []string, first map[string]time.Time, calls []call, spawns return out } -// pairCalls returns the session's Claude Code inference calls in request order, each with the -// agent that made it. Progress-label calls and tool-less side calls (titler, classifier, -// security monitor) are dropped: they are not an agent's work, and on a live session they were -// more than half of the main role's requests. -func pairCalls(events []model.SessionEvent) []call { - var calls []call - byReq := map[string]int{} - for i := range events { - e := &events[i] - if e.Direction != model.Outbound { - continue - } - switch e.Phase { - case model.SessionRequest: - if e.Inference == nil { - continue - } - id, ok := agentOf(e) - // A transcript holds only real turns, and no tool manifest, so an imported call is never a side call. - if !ok || (!e.Imported() && isSideCall(e.Inference)) { - continue - } - byReq[e.RequestID] = len(calls) - calls = append(calls, call{req: e, agent: id}) - case model.SessionResponse, model.SessionDenied: - if j, ok := byReq[e.RequestID]; ok && calls[j].resp == nil { - calls[j].resp = e - } - } - } - return calls -} - -// agentOf names the agent that sent a request. Claude Code's requests carry their own -// markers: AgentRole from its cc_is_subagent header, Subagent from its agent id header. -// A Bob child task carries Subagent from its own X-Task-Id (it sends X-Parent-Task-Id). -// Every other request of a known client gets the single main row — nothing on the wire -// says which of its calls belong together beyond that. -func agentOf(e *model.SessionEvent) (string, bool) { - switch { - case e.Subagent != "": - return e.Subagent, true - case e.Inference.AgentRole == model.AgentRoleSubagent: - return UnseparatedAgent, true - case e.Inference.AgentRole == model.AgentRoleMain: - return MainAgent, true - case e.Client != nil && model.IsKnownAgent(e.Client.Name): - return MainAgent, true - } - return "", false -} - -// isSideCall drops a call that is not an agent's work. The no-tools rule is Claude Code only -// (AgentRole set): it holds because Claude always sends a manifest on real turns, while another -// client's tool-less calls (Bob's security classifier) are real turns with real cost. The prompt -// literals run for every client: they match Claude's own progress and recap prompt text, which -// no other client sends, and a recap storm reads as turns on any session that carries one — -// including pre-marker Claude Code traffic, attributed by client name alone. -func isSideCall(inf *model.InferenceExtension) bool { - if inf.AgentRole != "" && len(inf.Tools) == 0 && inf.ToolCount == 0 { - return true - } - for i := len(inf.Messages) - 1; i >= 0; i-- { - if m := inf.Messages[i]; m.Role != "system" { - return strings.Contains(m.Content, progressPrompt) || strings.Contains(m.Content, recapPrompt) - } - } - return false -} - -// commonPrefix is how many leading messages cur shares with prev. The store interns repeated -// message content, so equal strings usually share a backing array and compare in O(1). -func commonPrefix(prev, cur []model.InferenceMessage) int { - k := 0 - for k < len(prev) && k < len(cur) && prev[k].Role == cur[k].Role && prev[k].Content == cur[k].Content { - k++ - } - return k -} - -func responseEnd(req, resp *model.SessionEvent) time.Time { - if resp.Duration > 0 { - return req.At.Add(resp.Duration) - } - return resp.At -} - func preview(name string, a toolArgs) string { var s string switch { diff --git a/core/session/timeline/timeline_test.go b/core/session/timeline/timeline_test.go index e586b466c..b4641065b 100644 --- a/core/session/timeline/timeline_test.go +++ b/core/session/timeline/timeline_test.go @@ -552,24 +552,6 @@ func TestOnlyNewMessagesAreScanned(t *testing.T) { } } -func TestCommonPrefix(t *testing.T) { - a, b, c := user("a"), user("b"), user("c") - for _, tc := range []struct { - prev, cur []pipeline.InferenceMessage - want int - }{ - {nil, []pipeline.InferenceMessage{a}, 0}, - {[]pipeline.InferenceMessage{a, b}, []pipeline.InferenceMessage{a, b, c}, 2}, - {[]pipeline.InferenceMessage{a, b}, []pipeline.InferenceMessage{a, c}, 1}, // history rewritten - {[]pipeline.InferenceMessage{a, b, c}, []pipeline.InferenceMessage{a, b}, 2}, // compacted shorter - {[]pipeline.InferenceMessage{{Role: "system", Content: "a"}}, []pipeline.InferenceMessage{a}, 0}, - } { - if got := commonPrefix(tc.prev, tc.cur); got != tc.want { - t.Errorf("commonPrefix(%v, %v) = %d, want %d", tc.prev, tc.cur, got, tc.want) - } - } -} - // A parent can resume a subagent with SendMessage after its first hand-back; the row runs to // the last one. func TestReturnedAtIsTheLastReturn(t *testing.T) { diff --git a/core/session/toolpair/toolpair.go b/core/session/toolpair/toolpair.go new file mode 100644 index 000000000..578c02ac7 --- /dev/null +++ b/core/session/toolpair/toolpair.go @@ -0,0 +1,588 @@ +// Package toolpair pairs a session's tool calls with their results. +// +// A tool call is emitted on one response and its result arrives inside a LATER request's +// conversation, so neither event alone says how long the call took. Pairing them needs the +// tool-use id, a forward walk and per-agent state. This package is that walk, and it is shared +// 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. +// +// WHY A SHARED PACKAGE RATHER THAN A SECOND IMPLEMENTATION. Closing a call correctly has five +// cases beyond "its result arrived", and each one was a bug before it was a case: a call that +// ends the run by design and never gets a result, an agent that moved on without one, a run +// stopped by a , a result that lands before the asking response finished +// (clamped, not negative), and a result that only acknowledges a background job. Five +// regression tests in core/session/timeline pin them. A consumer reimplementing this would +// drift from those tests, silently, in the direction of plausible-looking latency figures. +// +// THE MESSAGE SCAN COMES WITH IT, AND THAT IS THE PRICE OF THE ABOVE. Two of the closing cases +// are only knowable from message text: a says a run ended, and a tool +// result's "Command running in background" says the call merely started a job. So this package +// scans the new messages of every request, which is also where the timeline's Returns and Jobs +// come from — hence Result carries those too, for the one consumer that wants them. The scan +// cannot be reduced to the task-notification match alone: it must skip the history each request +// re-sends (commonPrefix), or it is quadratic in turns — 0.26-0.47GB of text against 35-42MB +// new, on real sessions. core/session/timeline's TestBuildBudget enforces the consequence. +// +// NO ARGUMENT TEXT AND NO RESULT TEXT LEAVE THIS PACKAGE unless a caller asks. A Call carries +// the SIZE of a result, never its content, and carries a call's arguments only under +// Options.Arguments — which core/sessionexport does not set, so an export's Call values hold no +// argument bytes at all, rather than holding them beside a field nobody reads. The timeline sets +// it, because its preview is built from them. +package toolpair + +import ( + "fmt" + "regexp" + "strings" + "time" + + "github.com/rossoctl/cortex/core/model" +) + +// MainAgent and UnseparatedAgent are the two synthetic agent keys. A request that names no +// subagent is the main agent's; one that declares the subagent role without an id joins the +// 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. +const ( + MainAgent = "main" + UnseparatedAgent = "subagents" +) + +// The two ways a background subagent's result reaches the agent that started it, and the two +// markers a background shell job leaves. Each names its subject by the id Claude Code sends as +// X-Claude-Code-Agent-Id, which the proxy records as SessionEvent.Subagent, so a return links +// to its row without any text matching. +var ( + agentMessageRe = regexp.MustCompile(`\s*([A-Za-z0-9_-]+)`) + // backgroundRe is Claude Code's result for a shell command it started in the background; + // the command's later names the same id. + backgroundRe = regexp.MustCompile(`^Command running in background with ID: ([A-Za-z0-9_-]+)`) + // stoppedRe is TaskStop's result. A stopped job gets no , so without it + // the job stays open and covers every later wait of its agent. + stoppedRe = regexp.MustCompile(`^\{"message":"Successfully stopped (?:task: |background command )([A-Za-z0-9_-]+)`) +) + +// EndReason says how a tool call ended. Its ZERO VALUE MEANS STILL OPEN, which is a different +// fact from ReasonLost: a call the agent is still waiting on has no duration yet, while a lost +// one never will. core/session/timeline draws the first as a tick and the second as a +// bar, and its fixture test asserts one open call and eight lost ones on a real session. +// +// Only ReasonResult and ReasonBackground have an end. For the other three a consumer has a +// start and no duration — see Call.End. +type EndReason string + +const ( + // ReasonResult is the ordinary case: a later request carried the call's result. + ReasonResult EndReason = "result" + // ReasonBackground is a result that only ACKNOWLEDGED a job that keeps running. The call's + // end is the acknowledgement, so its duration is real but it is not the command's: that + // time is in a Job and is not counted here. A consumer totalling tool time undercounts by + // however long such commands ran, which is why this is a reason of its own rather than + // folded into ReasonResult. + ReasonBackground EndReason = "background" + // ReasonEndedRun is a call that ends its run by design and therefore never gets a result: a + // workflow agent's StructuredOutput, a subagent's SubagentHandback, a Bob subtask's + // end_subtask. Every other call of the same response ends this way too. + ReasonEndedRun EndReason = "ended_run" + // ReasonStopped is a call still open when its agent's run was stopped. + ReasonStopped EndReason = "stopped" + // ReasonAbandoned is a call whose agent asked again without ever carrying its result. + ReasonAbandoned EndReason = "abandoned" + // ReasonLost is open with no reason established. Reserved: Calls does not currently return + // it, because every no-result case it can see has a more specific reason. A consumer should + // treat it as "no result, cause unknown" rather than assuming it never appears. + ReasonLost EndReason = "lost" +) + +// HasEnd says whether r is a reason that carries a duration. The five no-result reasons leave +// Call.End nil, and a consumer that renders a missing end as a zero-length call reports it as +// an instant one — which drags a p50 toward zero. +func (r EndReason) HasEnd() bool { return r == ReasonResult || r == ReasonBackground } + +// Call is one tool call the model asked for, with when it started, how it ended, and the keys +// that place it among its siblings and against the events either side. +type Call struct { + // Agent is which caller under one session id made the call: MainAgent, UnseparatedAgent, or + // a subagent's own id. An opaque key, not a label — every map in this package is keyed by + // it, and a result only closes a call of the SAME agent. + Agent string + + // ToolUseID is the model's id for the call, and the key its result is matched by. + // + // INTERNAL TO A PAIRING. core/sessionexport must not export it: it joins a record back to a + // conversation, which is the one thing a content-free export must not offer. The timeline + // does carry it, because agentop addresses a span by it. + ToolUseID string + + // Name is the tool's name, verbatim as the model emitted it. + Name string + + // 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 + // when the proxy recorded it. + Start time.Time + + // End is when the result arrived, and is nil for every reason that has no end. Clamped up to + // Start when a result lands first: Claude Code runs a tool while the response that asked for + // it is still streaming, so that request can be recorded before the response finished, and + // the honest answer is a zero-length call rather than a negative one. + End *time.Time + + EndReason EndReason + + // IsError is whether the result said it was an error. False when there was no result. + IsError bool + + // ResultBytes is the size of the result's content. A SIZE, NEVER THE CONTENT: the effort a + // call returned is a number an export may carry, and the text is not. + ResultBytes int + + // CallSeq is the seq of the response that asked for this call; ResultSeq the seq of the + // request that carried its result, and 0 when none did. Together they let a consumer rejoin + // a call to the events either side of it WITHOUT the tool-use id. + CallSeq uint64 + ResultSeq uint64 + + // CallIndex is the call's position among the calls its response asked for, from 0, in the + // order the model emitted them; SiblingN is how many that response asked for in total. + // SiblingN is 1 for a lone call, so SiblingN > 1 is the batch predicate. + // + // Both exist because a batch is otherwise unorderable and uncountable: its calls share a + // Start by construction (see Calls), so timestamps cannot put them back in order. + CallIndex int + SiblingN int + + // AskedAt is when the asking REQUEST started, and ModelDur is how long its response took. + // Carried so a consumer gets the model time beside the tool time without a second lookup, + // and because the stopped comparison needs the request's own start rather than the call's. + AskedAt time.Time + ModelDur time.Duration + + // Arguments is the call's arguments as the model emitted them, and is EMPTY UNLESS THE + // CALLER SET Options.Arguments. It is argument text — a Bash command line is effectively a + // secret — so a consumer that must not hold it does not ask for it, and then cannot leak it + // through a log line or a reflective marshal either. + Arguments string +} + +// Job is a background shell command: from the tool result that acknowledged it to the +// naming that id, or to the TaskStop result that stopped it. Its starting +// call ends at the acknowledgement, so without this the agent looks idle while the job runs. +type Job struct { + Agent string + ID string + ToolUseID string // the call whose result started the job + Start time.Time + End *time.Time + Seq uint64 +} + +// Return is a subagent's result reaching another agent's context. +type Return struct { + Agent string + Into string + At time.Time + Seq uint64 +} + +// Options asks for the outputs a caller actually wants. The message scan runs either way — +// two closing cases depend on it — so these skip the bookkeeping and the allocations, not the +// work. core/sessionexport passes the zero value. +type Options struct { + // Returns fills Result.Returns. + Returns bool + // Arguments fills Call.Arguments. See that field: off means an export's Call values hold no + // argument bytes at all. + Arguments bool + // AgentResults fills Result.AgentResults. + AgentResults bool +} + +// Result is what one walk produced. +type Result struct { + // Calls is every tool call, in the order its asking response appeared, then by CallIndex. + Calls []Call + // Turns is every accepted request beside its response, in request order. See Turn. + Turns []Turn + // Jobs is every background shell command the scan saw acknowledged. + Jobs []Job + // Returns is every subagent result delivered into another agent's context. Empty unless + // Options.Returns. + Returns []Return + // AgentResults maps an Agent-or-Task call's tool-use id to its result text, for a caller + // that links a spawned subagent to the call that started it. Empty unless + // Options.AgentResults. CONTENT: only the timeline asks for this. + AgentResults map[string]string + // ScannedBytes is how much message text the scan read, for the budget test that guards the + // incremental skip. + ScannedBytes int +} + +// Turn is one accepted inference request beside its response, as the pairing resolved them. +// +// RETURNED SO A CONSUMER DOES NOT WALK AGAIN. The timeline needs the same request/response +// pairs for its own turns and its agent tree, and pairing is not free: it decides each +// request's agent, drops the agent's own housekeeping calls, and resolves a reused request id. +// Doing that twice over one session measured ~30% of a whole timeline build. +type Turn struct { + Req, Resp *model.SessionEvent + Agent string +} + +// call is one inference request and, once seen, its response. +type call struct { + req, resp *model.SessionEvent + agent string +} + +// Calls walks events and returns every tool call paired with its result. +// +// events must be one session's, in seq order. The walk buffers nothing beyond its own maps: it +// is one forward pass, then one closing pass over the calls it collected. +func Calls(events []model.SessionEvent, opts Options) Result { + var res Result + calls := pairCalls(events) + if len(calls) == 0 { + return res + } + // PREALLOCATED, because a Call is ~192 bytes and a real session has thousands: letting the + // slice double copies megabytes for nothing, and this walk is on the timeline's 50ms budget + // (core/session/timeline's TestBuildBudget). + n := 0 + for _, c := range calls { + if c.resp != nil && c.resp.Inference != nil { + n += len(c.resp.Inference.ToolCalls) + } + } + if n > 0 { + res.Calls = make([]Call, 0, n) + } + + // prev is the conversation the agent sent last time, for the incremental scan. + prev := map[string][]model.InferenceMessage{} + jobs := map[string]int{} // background job id → index in res.Jobs + // ends is agent → tool-use id → the first result that closed it. One map rather than the + // timeline's two parallel ones, because an export needs the carrying request's SEQ as well + // as its time and parallel maps are how those drift apart. + ends := map[string]map[string]toolEnd{} + // bgAck marks a tool-use id whose result only acknowledged a background job. + bgAck := map[string]bool{} + agentTools := map[string]bool{} + seenReturn := map[string]bool{} + stopped := map[string]time.Time{} // agent → its latest : its run ended + // A run that ends with SubagentHandback returns twice: its at once, and a + // that Claude Code sends later, often with the parent's next request. + handedBack, delivered := map[string]bool{}, map[string]bool{} + lastAsk := map[string]time.Time{} // agent → its latest request's At + if opts.AgentResults { + res.AgentResults = map[string]string{} + } + + for _, c := range calls { + inf := c.req.Inference + delete(handedBack, c.agent) + delete(delivered, c.agent) + + // Tool ends: the first request in this agent that carries a tool's result. + for i := range inf.ToolResults { + r := &inf.ToolResults[i] + if ends[c.agent] == nil { + ends[c.agent] = map[string]toolEnd{} + } + if _, seen := ends[c.agent][r.ToolUseID]; seen { + continue + } + ends[c.agent][r.ToolUseID] = toolEnd{at: c.req.At, seq: c.req.Seq, isError: r.IsError, bytes: len(r.Content)} + if opts.AgentResults && agentTools[r.ToolUseID] { + res.AgentResults[r.ToolUseID] = r.Content + } + if m := backgroundRe.FindStringSubmatch(r.Content); m != nil { + bgAck[r.ToolUseID] = true + if _, dup := jobs[m[1]]; !dup { + jobs[m[1]] = len(res.Jobs) + res.Jobs = append(res.Jobs, Job{Agent: c.agent, ID: m[1], ToolUseID: r.ToolUseID, Start: c.req.At, Seq: c.req.Seq}) + } + } + if m := stoppedRe.FindStringSubmatch(r.Content); m != nil { + if j, ok := jobs[m[1]]; ok && res.Jobs[j].End == nil { + at := c.req.At + res.Jobs[j].End = &at + } + } + } + + // Returns and run-ended markers: scan only the messages this agent has not sent before. + // A conversation re-sends its whole history every turn, so scanning all of it is + // quadratic in turns. + // + // Not for pre-#1459 subagent traffic: every subagent shares that one bucket, so each + // request's history differs from the last one's and every scan would be a full one. + msgs := inf.Messages + k := CommonPrefix(prev[c.agent], msgs) + if c.agent == UnseparatedAgent { + k = len(msgs) + } + for mi, m := range msgs[k:] { + if m.Role == "assistant" { + continue // an agent quoting the markers is not a delivery + } + res.ScannedBytes += len(m.Content) + for _, re := range []*regexp.Regexp{agentMessageRe, taskIDRe} { + for _, idx := range re.FindAllStringSubmatchIndex(m.Content, -1) { + from := m.Content[idx[2]:idx[3]] + tail := m.Content[idx[0]:min(len(m.Content), idx[1]+200)] + // Keyed by the message's position in the history as well as its text: a + // fork re-sends its parent's deliveries at the same positions, while a + // second, identically worded hand-back lands at a new one. + key := fmt.Sprintf("%s\x00%d\x00%s", from, k+mi, tail) + if seenReturn[key] { + continue // a fork inherits its parent's history, deliveries included + } + seenReturn[key] = true + // The notification after a delivered hand-back is not a return: it came a + // median 22s and up to hours later, and riding on the user's next prompt it + // labelled the user's time as waiting on the subagent. + if re == agentMessageRe && handedBack[from] { + delivered[from] = true + } + if opts.Returns && (re == agentMessageRe || !delivered[from]) { + res.Returns = append(res.Returns, Return{Agent: from, Into: c.agent, At: c.req.At, Seq: c.req.Seq}) + } + // Only a notification says the run ended: an can arrive mid-run. + if re == taskIDRe && c.req.At.After(stopped[from]) { + stopped[from] = c.req.At + } + // A background job ends at the first notification naming it. + if j, ok := jobs[from]; ok && res.Jobs[j].End == nil { + at := c.req.At + res.Jobs[j].End = &at + } + } + } + } + prev[c.agent] = msgs + if lastAsk[c.agent].Before(c.req.At) { + lastAsk[c.agent] = c.req.At + } + + if c.resp == nil || c.resp.Inference == nil { + continue + } + end := ResponseEnd(c.req, c.resp) + tcs := c.resp.Inference.ToolCalls + for i, tc := range tcs { + k := Call{ + Agent: c.agent, + ToolUseID: tc.ID, + Name: tc.Name, + Start: end, + CallSeq: c.resp.Seq, + CallIndex: i, + SiblingN: len(tcs), + AskedAt: c.req.At, + ModelDur: c.resp.Duration, + } + if opts.Arguments { + k.Arguments = tc.Arguments + } + res.Calls = append(res.Calls, k) + if tc.Name == "SubagentHandback" { + handedBack[c.agent] = true + } + if tc.Name == "Agent" || tc.Name == "Task" { + agentTools[tc.ID] = true + } + } + } + + res.Turns = make([]Turn, len(calls)) + for i, c := range calls { + res.Turns[i] = Turn{Req: c.req, Resp: c.resp, Agent: c.agent} + } + closeCalls(res.Calls, ends, bgAck, stopped, lastAsk) + return res +} + +// toolEnd is the first result that closed a call: when it arrived, which request carried it, +// and the two facts a consumer may keep about it. NOT ITS CONTENT — the size is the effort +// proxy an export may carry, and the text never leaves this package. +type toolEnd struct { + at time.Time + seq uint64 + isError bool + bytes int +} + +// endsRun are the tool calls that end their run by design, so neither they nor any sibling of +// the same response ever gets a result. +var endsRun = map[string]bool{"SubagentHandback": true, "StructuredOutput": true, "end_subtask": true} + +// closeCalls decides each call's end and reason, in place. +// +// PRECEDENCE, AND ONE DECISION THE TIMELINE LEFT UNSPECIFIED. A result wins over every +// no-result reason. Among the no-result reasons, ended_run wins (it is a property of the call +// itself), then stopped, then abandoned. The timeline tests all three in one disjunction +// (`endedRun || lastTurn || stopped`), so a call that satisfies both stopped and abandoned had +// no defined answer before this package named one: stopped is the more specific fact — a run +// was ended by something — where abandoned only says the agent asked again. The choice changes +// no timeline behaviour, because both map to the same Lost bool. +func closeCalls( + calls []Call, + ends map[string]map[string]toolEnd, + bgAck map[string]bool, + stopped map[string]time.Time, + lastAsk map[string]time.Time, +) { + // A response whose calls end the run gives its OTHER calls no result either, and no + // notification arrives to close them. Keyed by the response's seq, which a response's calls + // share. + endedRun := map[uint64]bool{} + for i := range calls { + k := &calls[i] + if _, ok := ends[k.Agent][k.ToolUseID]; !ok && endsRun[k.Name] { + endedRun[k.CallSeq] = true + } + } + for i := range calls { + k := &calls[i] + if e, ok := ends[k.Agent][k.ToolUseID]; ok { + at := e.at + if at.Before(k.Start) { + at = k.Start + } + k.End = &at + k.IsError, k.ResultBytes, k.ResultSeq = e.isError, e.bytes, e.seq + if bgAck[k.ToolUseID] { + k.EndReason = ReasonBackground + } else { + k.EndReason = ReasonResult + } + continue + } + switch { + case endedRun[k.CallSeq]: + k.EndReason = ReasonEndedRun + case stopped[k.Agent].After(k.AskedAt): + // The run ended while the call was open. Compared against the asking REQUEST's + // start, not the call's: a run can end while the asking response still streams, and + // a resumed run's request starts after the earlier notification. + k.EndReason = ReasonStopped + case lastAsk[k.Agent].After(k.Start): + k.EndReason = ReasonAbandoned + } + // Anything else is still open: the zero EndReason, with no End. + } +} + +// pairCalls walks events once and returns each accepted inference request beside its response. +// +// FIRST RESPONSE WINS. A client that reuses a request id loses the earlier request's response +// rather than overwriting the later one. +func pairCalls(events []model.SessionEvent) []call { + var calls []call + byReq := map[string]int{} + for i := range events { + e := &events[i] + if e.Direction != model.Outbound { + continue + } + switch e.Phase { + case model.SessionRequest: + if e.Inference == nil { + continue + } + id, ok := agentOf(e) + // A side call carries the agent's whole context to ask for a status line or an + // away recap, so it is not the agent working. An imported transcript has no such + // calls to tell apart. + if !ok || (!e.Imported() && isSideCall(e.Inference)) { + continue + } + byReq[e.RequestID] = len(calls) + calls = append(calls, call{req: e, agent: id}) + case model.SessionResponse, model.SessionDenied: + if j, ok := byReq[e.RequestID]; ok && calls[j].resp == nil { + calls[j].resp = e + } + } + } + return calls +} + +// CommonPrefix is how many leading messages cur shares with prev. The store interns repeated +// message content, so equal strings usually share a backing array and compare in O(1). +func CommonPrefix(prev, cur []model.InferenceMessage) int { + k := 0 + for k < len(prev) && k < len(cur) && prev[k].Role == cur[k].Role && prev[k].Content == cur[k].Content { + k++ + } + return k +} + +// ResponseEnd is when a response finished: its request's start plus the measured duration, +// falling back to the response event's own timestamp when nothing measured it. +func ResponseEnd(req, resp *model.SessionEvent) time.Time { + if resp.Duration > 0 { + return req.At.Add(resp.Duration) + } + return resp.At +} + +// agentOf is which agent a request belongs to, and whether it counts as agent traffic at all. +func agentOf(e *model.SessionEvent) (string, bool) { + if e.Subagent != "" { + return e.Subagent, true + } + if e.Inference != nil { + switch e.Inference.AgentRole { + case model.AgentRoleSubagent: + return UnseparatedAgent, true + case model.AgentRoleMain: + return MainAgent, true + } + } + if e.Client != nil && model.IsKnownAgent(e.Client.Name) { + return MainAgent, true + } + return "", false +} + +// progressPrompt is the instruction Claude Code appends when it asks a model for a subagent's +// 3-5 word status line. Those calls carry the subagent's whole context and tool list, so only +// their last message tells them apart from the subagent's real turns; Claude Code can send +// system messages after it (a count). They are a third of all subagent calls on +// real sessions. +const progressPrompt = "Describe your most recent action in 3-5 words" + +// recapPrompt asks for the summary Claude Code shows when the user comes back to an idle +// session. The same shape as a progress label: whole context and tool list, told apart only by +// its last message. Counted as a turn it was the agent working while the user was away, and two +// recaps of an unchanged conversation read as a retry: 74 hours of it on one session. +const recapPrompt = "The user stepped away and is coming back" + +// isSideCall drops a call that is not an agent's work. The no-tools rule is Claude Code only +// (AgentRole set): it holds because Claude always sends a manifest on real turns, while another +// client's tool-less calls (Bob's security classifier) are real turns with real cost. The prompt +// literals run for every client: they match Claude's own progress and recap prompt text, which +// no other client sends, and a recap storm reads as turns on any session that carries one — +// including pre-marker Claude Code traffic, attributed by client name alone. +// +// SKIPS TRAILING SYSTEM MESSAGES, NOT NON-USER ONES: Claude Code appends a system message after +// the prompt, and the message the literals must be tested against is the last non-system one. +func isSideCall(inf *model.InferenceExtension) bool { + if inf.AgentRole != "" && len(inf.Tools) == 0 && inf.ToolCount == 0 { + return true + } + for i := len(inf.Messages) - 1; i >= 0; i-- { + if m := inf.Messages[i]; m.Role != "system" { + return strings.Contains(m.Content, progressPrompt) || strings.Contains(m.Content, recapPrompt) + } + } + return false +} diff --git a/core/session/toolpair/toolpair_test.go b/core/session/toolpair/toolpair_test.go new file mode 100644 index 000000000..3bb4df8e8 --- /dev/null +++ b/core/session/toolpair/toolpair_test.go @@ -0,0 +1,348 @@ +package toolpair + +import ( + "testing" + "time" + + "github.com/rossoctl/cortex/core/model" +) + +// The builders below are a deliberate, minimal copy of core/session/timeline's test helpers. +// +// WHY A COPY RATHER THAN A SHARED PACKAGE. The timeline's helpers are unexported and written +// against the core/pipeline aliases, so sharing them means either exporting them from a package +// under core/session that imports core/pipeline — a trap, since the data packages must not reach +// the plugin engine (core/model's imports_test) — or rewriting ~70 test functions in the one +// change whose whole value is proving the timeline's behaviour did not move. 30 lines of +// scaffolding is the cheaper duplicate. Promote both to a shared helper if a third consumer +// appears (#505's OTLP emitter). + +var t0 = time.Date(2026, 11, 20, 9, 0, 0, 0, time.UTC) + +func at(s float64) time.Time { return t0.Add(time.Duration(s * float64(time.Second))) } + +// tools is the manifest every agent request carries; a request without one is a side call. +var manifest = []model.InferenceTool{{Name: "Bash"}} + +type rec struct { + events []model.SessionEvent + n int +} + +func (r *rec) add(e model.SessionEvent) { + e.Seq = uint64(len(r.events) + 1) + e.Direction = model.Outbound + r.events = append(r.events, e) +} + +func (r *rec) id() string { r.n++; return "req" + string(rune('a'+r.n-1)) } + +// turn records one model call by agent (empty = main), sending msgs and answering with calls. +func (r *rec) turn(agent string, start, dur float64, msgs []model.InferenceMessage, results []model.InferenceToolResult, finish string, calls ...model.InferenceToolCall) { + role := model.AgentRoleMain + if agent != "" { + role = model.AgentRoleSubagent + } + id := r.id() + r.add(model.SessionEvent{At: at(start), Phase: model.SessionRequest, RequestID: id, Subagent: agent, + Inference: &model.InferenceExtension{AgentRole: role, Tools: manifest, Messages: msgs, ToolResults: results, Stream: true}}) + r.add(model.SessionEvent{At: at(start + dur), Phase: model.SessionResponse, RequestID: id, Subagent: agent, + StatusCode: 200, Duration: time.Duration(dur * float64(time.Second)), + Inference: &model.InferenceExtension{FinishReason: finish, ToolCalls: calls}}) +} + +func user(s string) model.InferenceMessage { + return model.InferenceMessage{Role: "user", Content: s} +} + +func result(id, content string) model.InferenceToolResult { + return model.InferenceToolResult{ToolUseID: id, Content: content} +} + +func callOf(t *testing.T, cs []Call, toolUseID string) Call { + t.Helper() + for _, c := range cs { + if c.ToolUseID == toolUseID { + return c + } + } + t.Fatalf("no call %q among %d", toolUseID, len(cs)) + return Call{} +} + +// TestCallRunsFromItsResponseEndToItsResult is the ordinary case, and the one every other test +// here is a deviation from. +func TestCallRunsFromItsResponseEndToItsResult(t *testing.T) { + var r rec + r.turn("", 0, 2, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash", Arguments: `{"command":"ls"}`}) + r.turn("", 5, 1, []model.InferenceMessage{user("go")}, []model.InferenceToolResult{result("t1", "out")}, "end_turn") + + got := Calls(r.events, Options{}) + if len(got.Calls) != 1 { + t.Fatalf("calls = %d, want 1", len(got.Calls)) + } + c := got.Calls[0] + if !c.Start.Equal(at(2)) { + t.Errorf("Start = %v, want %v (the asking response's end)", c.Start, at(2)) + } + if c.End == nil || !c.End.Equal(at(5)) { + t.Errorf("End = %v, want %v (the request carrying its result)", c.End, at(5)) + } + if c.EndReason != ReasonResult { + t.Errorf("EndReason = %q, want %q", c.EndReason, ReasonResult) + } + if c.CallSeq != 2 || c.ResultSeq != 3 { + t.Errorf("CallSeq/ResultSeq = %d/%d, want 2/3", c.CallSeq, c.ResultSeq) + } + if c.ResultBytes != 3 { + t.Errorf("ResultBytes = %d, want 3", c.ResultBytes) + } + if c.ModelDur != 2*time.Second { + t.Errorf("ModelDur = %v, want 2s", c.ModelDur) + } +} + +// TestResultBeforeItsResponseIsClampedToStart: Claude Code runs a tool while the response that +// asked for it still streams, so the carrying request can be recorded first. A zero-length call +// is the honest answer; a negative one is not. +func TestResultBeforeItsResponseIsClampedToStart(t *testing.T) { + var r rec + r.turn("", 0, 10, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash"}) + r.turn("", 4, 1, []model.InferenceMessage{user("go")}, []model.InferenceToolResult{result("t1", "x")}, "end_turn") + + c := callOf(t, Calls(r.events, Options{}).Calls, "t1") + if c.End == nil || !c.End.Equal(c.Start) { + t.Errorf("End = %v, want it clamped to Start %v", c.End, c.Start) + } +} + +// TestResultInAnotherAgentDoesNotCloseTheCall pins the per-agent keying: two agents can use the +// same tool-use id, and a result only closes its own agent's call. +func TestResultInAnotherAgentDoesNotCloseTheCall(t *testing.T) { + var r rec + r.turn("sub1", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash"}) + r.turn("sub2", 2, 1, []model.InferenceMessage{user("go")}, []model.InferenceToolResult{result("t1", "x")}, "end_turn") + + c := callOf(t, Calls(r.events, Options{}).Calls, "t1") + if c.End != nil { + t.Errorf("End = %v, want nil: another agent's result must not close it", c.End) + } +} + +// TestBatchSharesAStartAndIsOrdered: a response's calls share a start by construction, so +// CallIndex is the only thing that can put them back in the order the model asked. +func TestBatchSharesAStartAndIsOrdered(t *testing.T) { + var r rec + r.turn("", 0, 2, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Read"}, + model.InferenceToolCall{ID: "t2", Name: "Bash"}, + model.InferenceToolCall{ID: "t3", Name: "Edit"}) + + got := Calls(r.events, Options{}).Calls + if len(got) != 3 { + t.Fatalf("calls = %d, want 3", len(got)) + } + for i, want := range []string{"Read", "Bash", "Edit"} { + if got[i].Name != want || got[i].CallIndex != i { + t.Errorf("call %d = %q index %d, want %q index %d", i, got[i].Name, got[i].CallIndex, want, i) + } + if got[i].SiblingN != 3 { + t.Errorf("call %d SiblingN = %d, want 3", i, got[i].SiblingN) + } + if !got[i].Start.Equal(at(2)) { + t.Errorf("call %d Start = %v, want %v", i, got[i].Start, at(2)) + } + } +} + +// TestBackgroundAcknowledgementIsItsOwnReason is T32: the call ends at the acknowledgement, so +// its duration is real but is not the command's. Marked, not folded into "result", so a +// consumer can count how much tool time is missing. +func TestBackgroundAcknowledgementIsItsOwnReason(t *testing.T) { + var r rec + r.turn("", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash"}) + r.turn("", 3, 1, []model.InferenceMessage{user("go")}, + []model.InferenceToolResult{result("t1", "Command running in background with ID: job7")}, "end_turn") + + got := Calls(r.events, Options{}) + c := callOf(t, got.Calls, "t1") + if c.EndReason != ReasonBackground { + t.Errorf("EndReason = %q, want %q", c.EndReason, ReasonBackground) + } + if c.End == nil { + t.Fatal("End = nil, want the acknowledgement's time: a background call does have a duration") + } + if len(got.Jobs) != 1 || got.Jobs[0].ID != "job7" { + t.Errorf("Jobs = %+v, want one job7", got.Jobs) + } +} + +// TestEndedRunCallsGetNoResultAndSayWhy: a StructuredOutput ends the run, so neither it nor any +// sibling of the same response is ever answered. +func TestEndedRunCallsGetNoResultAndSayWhy(t *testing.T) { + var r rec + r.turn("", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "StructuredOutput"}, + model.InferenceToolCall{ID: "t2", Name: "Bash"}) + + got := Calls(r.events, Options{}).Calls + for _, id := range []string{"t1", "t2"} { + c := callOf(t, got, id) + if c.EndReason != ReasonEndedRun { + t.Errorf("%s EndReason = %q, want %q", id, c.EndReason, ReasonEndedRun) + } + if c.End != nil { + t.Errorf("%s End = %v, want nil", id, c.End) + } + } +} + +// TestAbandonedCallIsNamedAsSuch: the agent asked again without ever carrying the result. +func TestAbandonedCallIsNamedAsSuch(t *testing.T) { + var r rec + r.turn("", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash"}) + r.turn("", 5, 1, []model.InferenceMessage{user("again")}, nil, "end_turn") + + c := callOf(t, Calls(r.events, Options{}).Calls, "t1") + if c.EndReason != ReasonAbandoned { + t.Errorf("EndReason = %q, want %q", c.EndReason, ReasonAbandoned) + } + if c.End != nil { + t.Errorf("End = %v, want nil", c.End) + } +} + +// TestOpenCallHasNoReason is the distinction the zero value exists for: a call still being +// waited on is not a lost one, and must not read as a 0 ms call. +func TestOpenCallHasNoReason(t *testing.T) { + var r rec + r.turn("sub1", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash"}) + + c := callOf(t, Calls(r.events, Options{}).Calls, "t1") + if c.EndReason != "" { + t.Errorf("EndReason = %q, want empty (still open)", c.EndReason) + } + if c.End != nil { + t.Errorf("End = %v, want nil", c.End) + } + if c.EndReason.HasEnd() { + t.Error("HasEnd() = true for an open call") + } +} + +// TestStoppedWinsOverAbandoned pins the one precedence the timeline left unspecified: a call can +// satisfy both, and a stopped run is the more specific fact. +func TestStoppedWinsOverAbandoned(t *testing.T) { + var r rec + // A subagent opens a call, then the main agent carries the notification that ended that + // run — and the subagent also asked again later, which alone would read as abandoned. + r.turn("sub1", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash"}) + r.turn("", 5, 1, []model.InferenceMessage{user("\nsub1")}, nil, "end_turn") + r.turn("sub1", 9, 1, []model.InferenceMessage{user("more")}, nil, "end_turn") + + c := callOf(t, Calls(r.events, Options{}).Calls, "t1") + if c.EndReason != ReasonStopped { + t.Errorf("EndReason = %q, want %q", c.EndReason, ReasonStopped) + } +} + +// TestArgumentsAreAbsentUnlessAsked is the privacy property core/sessionexport relies on: its +// Call values hold no argument bytes at all, rather than holding them beside a field it does +// not read. +func TestArgumentsAreAbsentUnlessAsked(t *testing.T) { + const secret = "SECRET-COMMAND-DO-NOT-EXPORT" + var r rec + r.turn("", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash", Arguments: `{"command":"` + secret + `"}`}) + + if got := callOf(t, Calls(r.events, Options{}).Calls, "t1").Arguments; got != "" { + t.Errorf("Arguments = %q, want empty without Options.Arguments", got) + } + if got := callOf(t, Calls(r.events, Options{Arguments: true}).Calls, "t1").Arguments; got == "" { + t.Error("Arguments empty with Options.Arguments: the timeline needs them for its preview") + } +} + +// TestResultContentNeverReachesACall: a Call carries the size and the error flag, never the text. +func TestResultContentNeverReachesACall(t *testing.T) { + const secret = "SECRET-RESULT-DO-NOT-EXPORT" + var r rec + r.turn("", 0, 1, []model.InferenceMessage{user("go")}, nil, "tool_use", + model.InferenceToolCall{ID: "t1", Name: "Bash"}) + r.turn("", 3, 1, []model.InferenceMessage{user("go")}, + []model.InferenceToolResult{{ToolUseID: "t1", Content: secret, IsError: true}}, "end_turn") + + c := callOf(t, Calls(r.events, Options{}).Calls, "t1") + if c.ResultBytes != len(secret) { + t.Errorf("ResultBytes = %d, want %d", c.ResultBytes, len(secret)) + } + if !c.IsError { + t.Error("IsError = false, want true") + } + for _, s := range []string{c.Name, c.Arguments, c.Agent, c.ToolUseID, string(c.EndReason)} { + if s == secret { + t.Errorf("result content reached a Call field: %q", s) + } + } +} + +// TestReturnsAreOptional: the scan runs either way — two closing cases need it — but a consumer +// that does not want Returns does not pay for the slice. +func TestReturnsAreOptional(t *testing.T) { + var r rec + r.turn("", 0, 1, []model.InferenceMessage{user(``)}, nil, "end_turn") + + if got := Calls(r.events, Options{}).Returns; len(got) != 0 { + t.Errorf("Returns = %+v, want none without Options.Returns", got) + } + if got := Calls(r.events, Options{Returns: true}).Returns; len(got) != 1 { + t.Errorf("Returns = %+v, want one with Options.Returns", got) + } +} + +// TestOnlyNewMessagesAreScanned guards the incremental skip. Without it the scan is quadratic in +// turns, which core/session/timeline's TestBuildBudget measures as a 10-100x cliff. +func TestOnlyNewMessagesAreScanned(t *testing.T) { + var r rec + history := []model.InferenceMessage{user("aaaa"), user("bbbb")} + r.turn("", 0, 1, history, nil, "end_turn") + r.turn("", 2, 1, append(append([]model.InferenceMessage{}, history...), user("cc")), nil, "end_turn") + + got := Calls(r.events, Options{}).ScannedBytes + if want := 4 + 4 + 2; got != want { + t.Errorf("ScannedBytes = %d, want %d: the second turn must rescan nothing", got, want) + } +} + +// TestNoEventsIsNoCalls — a session with nothing paired must not panic or allocate. +func TestNoEventsIsNoCalls(t *testing.T) { + if got := Calls(nil, Options{}); len(got.Calls) != 0 || len(got.Jobs) != 0 { + t.Errorf("Calls(nil) = %+v, want empty", got) + } +} + +// TestCommonPrefix moved here with the function it tests. +func TestCommonPrefix(t *testing.T) { + a, b, c := user("a"), user("b"), user("c") + for _, tc := range []struct { + prev, cur []model.InferenceMessage + want int + }{ + {nil, []model.InferenceMessage{a}, 0}, + {[]model.InferenceMessage{a, b}, []model.InferenceMessage{a, b, c}, 2}, + {[]model.InferenceMessage{a, b}, []model.InferenceMessage{a, c}, 1}, // history rewritten + {[]model.InferenceMessage{a, b, c}, []model.InferenceMessage{a, b}, 2}, // compacted shorter + {[]model.InferenceMessage{{Role: "system", Content: "a"}}, []model.InferenceMessage{a}, 0}, + } { + if got := CommonPrefix(tc.prev, tc.cur); got != tc.want { + t.Errorf("CommonPrefix(%v, %v) = %d, want %d", tc.prev, tc.cur, got, tc.want) + } + } +} From 84d4e09dc3f2464e98ae3ad785a6f0ee2e5326b7 Mon Sep 17 00:00:00 2001 From: Mariusz Sabath Date: Fri, 20 Nov 2026 19:09:50 -0500 Subject: [PATCH 2/3] Fix: Remove the extraction's dead duplicates and make lostFor fail closed 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) Signed-off-by: Mariusz Sabath --- core/session/timeline/agents.go | 59 +++++++------------ core/session/timeline/agents_lostfor_test.go | 34 +++++++++++ core/session/toolpair/toolpair.go | 60 +++++++++++++------- 3 files changed, 96 insertions(+), 57 deletions(-) create mode 100644 core/session/timeline/agents_lostfor_test.go diff --git a/core/session/timeline/agents.go b/core/session/timeline/agents.go index f47225c66..7702c0333 100644 --- a/core/session/timeline/agents.go +++ b/core/session/timeline/agents.go @@ -12,33 +12,16 @@ import ( "github.com/rossoctl/cortex/core/session/toolpair" ) -// progressPrompt is the instruction Claude Code appends when it asks a model for a subagent's -// 3-5 word status line. Those calls carry the subagent's whole context and tool list, so only -// their last user message tells them apart from the subagent's real turns; Claude Code can send -// system messages after it (a count). They are a third of all subagent calls on -// real sessions, and drawing them would bury the turns that matter. -const progressPrompt = "Describe your most recent action in 3-5 words" - -// recapPrompt asks for the summary Claude Code shows when the user comes back to an idle -// session. The same shape as a progress label: whole context and tool list, told apart only by -// its last user message. Drawn as a turn it was the agent working while the user was away, and -// two recaps of an unchanged conversation read as a retry: 74 hours of it on one session. -const recapPrompt = "The user stepped away and is coming back" - -// The two ways a background subagent's result reaches the agent that started it. Both name the -// subagent by the id Claude Code sends as X-Claude-Code-Agent-Id, the id the proxy records as -// SessionEvent.Subagent, so a return links to its row without any text matching. -var ( - agentMessageRe = regexp.MustCompile(`\s*([A-Za-z0-9_-]+)`) - spawnedIDRe = regexp.MustCompile(`agentId: ([A-Za-z0-9_-]+)`) - // backgroundRe is Claude Code's result for a shell command it started in the background; - // the command's later names the same id. - backgroundRe = regexp.MustCompile(`^Command running in background with ID: ([A-Za-z0-9_-]+)`) - // stoppedRe is TaskStop's result. A stopped job gets no , so without it - // the job stays open and covers every later wait of its agent. - stoppedRe = regexp.MustCompile(`^\{"message":"Successfully stopped (?:task: |background command )([A-Za-z0-9_-]+)`) -) +// spawnedIDRe reads the subagent id out of an Agent call's result ("agentId: …"), which is how +// a spawned subagent is linked to the call that started it. +// +// THE ONLY MARKER PATTERN LEFT HERE. The agent-message, task-notification, background-job and +// TaskStop patterns moved to core/session/toolpair with the scan that uses them. They are NOT +// duplicated back: Go does not report an unused package-level var, so a copy here would compile, +// pass vet, read as live beside this one — and silently do nothing when someone widened it, +// because the pattern that runs is in the other package. Same for the progress and recap prompt +// literals, which are matched against live traffic and change when Claude Code rewords them. +var spawnedIDRe = regexp.MustCompile(`agentId: ([A-Za-z0-9_-]+)`) // failedFinish are the finish reasons of a reply that did not complete: none at all, a refusal // (Anthropic "refusal", OpenAI chat "content_filter"), and a Responses API status of "failed" or @@ -84,16 +67,18 @@ type toolArgs struct { // // THE ONE PLACE THE TWO VOCABULARIES MEET. toolpair names WHY a call got no result (spec T31); // Tool.Lost only says that it did not, because that is what agentop decodes and its JSON is a -// wire contract. A call still being waited on is NOT lost — it has no End at all — which is why -// the zero reason is absent from this list rather than defaulting into it. Changing either side -// means reading the other: toolpair.EndReason's doc, and Tool.Lost's. -func lostFor(r toolpair.EndReason) bool { - switch r { - case toolpair.ReasonEndedRun, toolpair.ReasonAbandoned, toolpair.ReasonStopped, toolpair.ReasonLost: - return true - } - return false -} +// wire contract. +// +// DERIVED FROM HasEnd RATHER THAN A LIST OF REASONS, so that it FAILS CLOSED. Naming the +// no-result reasons here means a reason added to toolpair later matches none of them and reads +// as false — and a lost call with Lost false renders as still running, forever, on a pane whose +// whole job is showing what finished. Asking "does this reason carry an end" instead inverts +// that: a new reason is lost until someone says otherwise, which is the safe default and needs +// no edit here. +// +// The empty reason is the one that must not be lost: it means still open, which is a different +// fact — no End at all rather than an end equal to its start. +func lostFor(r toolpair.EndReason) bool { return r != "" && !r.HasEnd() } func buildAgents(t *Timeline, events []model.SessionEvent) { // The tool calls, the background jobs and the subagent returns all come from one walk over diff --git a/core/session/timeline/agents_lostfor_test.go b/core/session/timeline/agents_lostfor_test.go new file mode 100644 index 000000000..7c6ce3ffb --- /dev/null +++ b/core/session/timeline/agents_lostfor_test.go @@ -0,0 +1,34 @@ +package timeline + +import ( + "testing" + + "github.com/rossoctl/cortex/core/session/toolpair" +) + +// TestLostForFailsClosedOnAnUnknownReason is the guard on the mapping's DIRECTION. +// +// lostFor used to name the no-result reasons, so a reason added to toolpair later matched none +// of them and read as "not lost" — and a call that ended without a result then rendered as +// still running, forever, on a pane whose job is showing what finished. Deriving it from HasEnd +// inverts that: an unknown reason is lost until someone says otherwise. A future reason must +// not need an edit here, and this test fails if the derivation goes back to a list. +func TestLostForFailsClosedOnAnUnknownReason(t *testing.T) { + if !lostFor(toolpair.EndReason("some_reason_added_later")) { + t.Error("lostFor(unknown) = false, want true: an unrecognised reason must read as lost, not as open") + } + // The zero reason is the one exception: still open is not a kind of loss. + if lostFor("") { + t.Error(`lostFor("") = true, want false: an open call has no end at all`) + } + for _, r := range []toolpair.EndReason{toolpair.ReasonResult, toolpair.ReasonBackground} { + if lostFor(r) { + t.Errorf("lostFor(%q) = true, want false: it carries an end", r) + } + } + for _, r := range []toolpair.EndReason{toolpair.ReasonEndedRun, toolpair.ReasonStopped, toolpair.ReasonAbandoned} { + if !lostFor(r) { + t.Errorf("lostFor(%q) = false, want true", r) + } + } +} diff --git a/core/session/toolpair/toolpair.go b/core/session/toolpair/toolpair.go index 578c02ac7..5fb7500fb 100644 --- a/core/session/toolpair/toolpair.go +++ b/core/session/toolpair/toolpair.go @@ -67,13 +67,15 @@ var ( stoppedRe = regexp.MustCompile(`^\{"message":"Successfully stopped (?:task: |background command )([A-Za-z0-9_-]+)`) ) -// EndReason says how a tool call ended. Its ZERO VALUE MEANS STILL OPEN, which is a different -// fact from ReasonLost: a call the agent is still waiting on has no duration yet, while a lost -// one never will. core/session/timeline draws the first as a tick and the second as a -// bar, and its fixture test asserts one open call and eight lost ones on a real session. +// EndReason says how a tool call ended. Its ZERO VALUE MEANS STILL OPEN, which is a fact of +// its own and not a kind of loss: a call the agent is still waiting on has no duration YET, +// where one that ended without a result never will. core/session/timeline draws the second as +// a tick and leaves the first with no end at all, and its fixture test asserts one open call +// and eight closed-without-result ones on a real session. // -// Only ReasonResult and ReasonBackground have an end. For the other three a consumer has a -// start and no duration — see Call.End. +// Only ReasonResult and ReasonBackground have an end — ask HasEnd rather than listing the +// others, so that a reason added later is handled by default. For the rest a consumer has a +// start and no duration; see Call.End. type EndReason string const ( @@ -93,15 +95,24 @@ const ( ReasonStopped EndReason = "stopped" // ReasonAbandoned is a call whose agent asked again without ever carrying its result. ReasonAbandoned EndReason = "abandoned" - // ReasonLost is open with no reason established. Reserved: Calls does not currently return - // it, because every no-result case it can see has a more specific reason. A consumer should - // treat it as "no result, cause unknown" rather than assuming it never appears. - ReasonLost EndReason = "lost" ) -// HasEnd says whether r is a reason that carries a duration. The five no-result reasons leave -// Call.End nil, and a consumer that renders a missing end as a zero-length call reports it as -// an instant one — which drags a p50 toward zero. +// NO "lost" REASON, DELIBERATELY. An earlier draft reserved one for "no result, cause unknown", +// and nothing ever returned it: every no-result case this package can see has a more specific +// reason, and a call with none of them is not lost — it is STILL OPEN, which the zero value +// says. A reserved constant a producer never produces is worse than its absence, because the +// consumer this package exists for would reasonably switch on it and ship a dead branch, or +// read it as the catch-all for "no result" and miss the three reasons above. Add one only +// alongside the code that returns it. + +// HasEnd says whether r is a reason that carries a duration. +// +// THE PREDICATE TO BRANCH ON, not a list of the reasons that do not. A consumer naming the +// no-result reasons has to be edited when one is added, and the edit it forgets reads as +// "this call has an end" — so a call that ended without a result renders as still running. +// Asking this instead fails the safe way round. The no-result reasons leave Call.End nil, and +// a consumer that renders a missing end as a zero-length call reports it as an instant one, +// which drags a p50 toward zero. func (r EndReason) HasEnd() bool { return r == ReasonResult || r == ReasonBackground } // Call is one tool call the model asked for, with when it started, how it ended, and the keys @@ -158,6 +169,12 @@ type Call struct { CallIndex int SiblingN int + // FIVE FIELDS BELOW HAVE NO READER YET, and are here for core/sessionexport (spec T23, T29, + // T30): ResultSeq, CallIndex, SiblingN, AskedAt and ModelDur. The timeline reads none of + // them. They are ungated, unlike Arguments and AgentResults, because each is a scalar the + // walk already holds — gating them would cost an Options branch per field to save a few + // bytes, where Arguments and the result map gate real content and real allocations. + // AskedAt is when the asking REQUEST started, and ModelDur is how long its response took. // Carried so a consumer gets the model time beside the tool time without a second lookup, // and because the stopped comparison needs the request's own start rather than the call's. @@ -535,17 +552,20 @@ func ResponseEnd(req, resp *model.SessionEvent) time.Time { } // agentOf is which agent a request belongs to, and whether it counts as agent traffic at all. +// +// e.Inference MUST BE NON-NIL, which pairCalls guarantees before it calls this. Not a nil check +// but a precondition, deliberately: tolerating a nil Inference here would let the Client +// fallback below answer MainAgent for an event that is not a model call at all, which is a +// turn invented out of a tunnel row rather than a crash someone would notice. func agentOf(e *model.SessionEvent) (string, bool) { if e.Subagent != "" { return e.Subagent, true } - if e.Inference != nil { - switch e.Inference.AgentRole { - case model.AgentRoleSubagent: - return UnseparatedAgent, true - case model.AgentRoleMain: - return MainAgent, true - } + switch e.Inference.AgentRole { + case model.AgentRoleSubagent: + return UnseparatedAgent, true + case model.AgentRoleMain: + return MainAgent, true } if e.Client != nil && model.IsKnownAgent(e.Client.Name) { return MainAgent, true From 410966ee15f4cbf4b01b03467dc6d5769ba76ecb Mon Sep 17 00:00:00 2001 From: Mariusz Sabath Date: Fri, 20 Nov 2026 19:54:05 -0500 Subject: [PATCH 3/3] Fix: Alias the agent keys, and scope the export claims to what ships 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) Signed-off-by: Mariusz Sabath --- core/session/timeline/timeline.go | 11 ++++++-- core/session/toolpair/toolpair.go | 44 ++++++++++++++++++++++--------- 2 files changed, 41 insertions(+), 14 deletions(-) diff --git a/core/session/timeline/timeline.go b/core/session/timeline/timeline.go index f1b8d6f7b..a971ed444 100644 --- a/core/session/timeline/timeline.go +++ b/core/session/timeline/timeline.go @@ -18,14 +18,21 @@ import ( "time" "github.com/rossoctl/cortex/core/model" + "github.com/rossoctl/cortex/core/session/toolpair" ) // MainAgent is the agent id of the main conversation. -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 +// are written in two files drift in silence: the comparison simply stops matching, and every +// subagent turn reads as a fresh agent. Taking the value from the producer makes that +// impossible rather than unlikely. +const MainAgent = toolpair.MainAgent // UnseparatedAgent holds subagent traffic recorded before the proxy captured Claude Code's // agent id header (#1459): AgentRole says "subagent" but nothing says which one. -const UnseparatedAgent = "subagents" +const UnseparatedAgent = toolpair.UnseparatedAgent // Kind classifies a host span. type Kind string diff --git a/core/session/toolpair/toolpair.go b/core/session/toolpair/toolpair.go index 5fb7500fb..91f200a75 100644 --- a/core/session/toolpair/toolpair.go +++ b/core/session/toolpair/toolpair.go @@ -5,8 +5,12 @@ // tool-use id, a forward walk and per-agent state. This package is that walk, and it is shared // 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. +// - core/session/timeline draws the spans in agentop's Timeline pane. It is the only caller +// today. +// - core/sessionexport WILL project them to content-free records for GET /v1/export +// (rossoctl/cortex#1906 §2). Nothing imports this package from there yet, so every claim +// below about what the export does or does not read is a statement about that design, not +// about shipped code. // // WHY A SHARED PACKAGE RATHER THAN A SECOND IMPLEMENTATION. Closing a call correctly has five // cases beyond "its result arrived", and each one was a bug before it was a case: a call that @@ -27,9 +31,10 @@ // // NO ARGUMENT TEXT AND NO RESULT TEXT LEAVE THIS PACKAGE unless a caller asks. A Call carries // the SIZE of a result, never its content, and carries a call's arguments only under -// Options.Arguments — which core/sessionexport does not set, so an export's Call values hold no -// argument bytes at all, rather than holding them beside a field nobody reads. The timeline sets -// it, because its preview is built from them. +// Options.Arguments. The timeline sets it, because its preview is built from them; the export +// is designed not to, so that its Call values will hold no argument bytes at all rather than +// holding them beside a field nobody reads. That property is a claim about the export PR, and +// it is that PR's test that will hold it. package toolpair import ( @@ -46,7 +51,9 @@ import ( // 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. +// consumer: the dependency runs the other way. THESE ARE THE DEFINITIONS — the timeline's +// exported MainAgent and UnseparatedAgent alias them rather than respelling the strings, so the +// keys it compares against cannot drift from the keys assigned here. const ( MainAgent = "main" UnseparatedAgent = "subagents" @@ -169,11 +176,21 @@ type Call struct { CallIndex int SiblingN int - // FIVE FIELDS BELOW HAVE NO READER YET, and are here for core/sessionexport (spec T23, T29, - // T30): ResultSeq, CallIndex, SiblingN, AskedAt and ModelDur. The timeline reads none of - // them. They are ungated, unlike Arguments and AgentResults, because each is a scalar the - // walk already holds — gating them would cost an Options branch per field to save a few - // bytes, where Arguments and the result map gate real content and real allocations. + // FIVE FIELDS HAVE NO PRODUCTION READER YET: ResultSeq, CallIndex, SiblingN, ModelDur and + // ResultBytes. They are for core/sessionexport (spec T23, T29, T30, T14); only AskedAt is + // read here, by the timeline. This package's own tests cover all five. + // + // SHIPPED NOW RATHER THAN WITH THEIR READER, DELIBERATELY, and the trade is worth stating + // because core/ is consumed outside this repo, so each one is external API from this commit. + // 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 + // that is not a breaking change to anything — nothing outside this module reads them. + // + // They are ungated, unlike Arguments and AgentResults, because each is a scalar the walk + // already holds: gating would cost an Options branch per field to save a few bytes, where + // those two gate real content and real allocations. // AskedAt is when the asking REQUEST started, and ModelDur is how long its response took. // Carried so a consumer gets the model time beside the tool time without a second lookup, @@ -210,7 +227,10 @@ type Return struct { // Options asks for the outputs a caller actually wants. The message scan runs either way — // two closing cases depend on it — so these skip the bookkeeping and the allocations, not the -// work. core/sessionexport passes the zero value. +// work. The timeline sets all three; the export is expected to pass the zero value. +// +// Every false path is exercised only by this package's tests today, for the same reason the +// doc above gives: the export caller does not exist yet. type Options struct { // Returns fills Result.Returns. Returns bool