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..7702c0333 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,35 +9,19 @@ 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 -// 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 @@ -80,38 +63,91 @@ 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. +// +// 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) { - 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 +155,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 +168,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 +190,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 +209,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 +303,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/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/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/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..91f200a75 --- /dev/null +++ b/core/session/toolpair/toolpair.go @@ -0,0 +1,628 @@ +// 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. 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 +// 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. 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 ( + "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. 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" +) + +// 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 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 — 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 ( + // 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" +) + +// 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 +// 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 + + // 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, + // 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. 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 + // 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. +// +// 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 + } + 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) + } + } +}