Feat: Agent-neutral timeline turns and tools (#1559)

CLAUDE.md

@@ -526,7 +526,7 @@ When `session.enabled` is true (default) and `listener.session_api_addr` is non-
 | `GET /` | text | One-line-per-endpoint index. Answers "is this the session API, and on the right port?" — the reason a 404 here was worth replacing. |
 | `GET /v1/sessions` | `application/json` | List active sessions: `{sessions: [{id, createdAt, updatedAt, eventCount, title, agent, totalTokens, costMicros, avoidedMicros, saturated, active, promptContext, inferenceHost, inferenceHostFromHistory, procs, lastRequestAt, linkedTo, linkedAll}]}`. `id`, `createdAt`, `updatedAt`, `eventCount` and `active` are always present; every other field is `omitempty` — absent rather than zero, on the standing rule that an unknown value must not render as a real one. (Do not read that off the position of `active`: it sits among the `omitempty` fields.) **`procs`** are the processes (`<pid>.<start>`) whose own session header named the session, and **`linkedTo`/`linkedAll`** — on a `pending:<agent>@<pid>.<start>` bucket only, computed when the list is read (`session.Link`) — say which sessions that process named its calls belong to (`{session, first, last}`) and whether every request in the bucket came before one of them. A pending bucket is never renamed into a session: agentop hides a `linkedAll` bucket that links to one session and merges its calls into that session's timeline. **`inferenceHost`** is the host of the session's most recent request that carried an inference parse — after a redirect, the server it was sent to rather than the host the client named — folded at append time, latest wins, and left alone by tunnel rows, MCP calls, responses and denials; agentop's sessions-table `SERVER` column names a session's inference server from it, and both `S`'s result line and `agentop server remove`'s warning count running sessions by it. **`inferenceHostFromHistory`** is `true` when that host came only from the archive's fold, because no request the proxy's entry for the session holds has set it — a session resumed after a restart that has sent no inference since. On a local install the inference-router keeps its pins in the plugin store (`~/.cortex/plugin-state.json`), which a restart keeps, so both of agentop's counts include such a session. **`title` is a suggestion, not an identifier:** the proxy derives it from the session's own events (a `/rename`, else a `<user_query>`, else ordinary user prose, with `<system-reminder>` blocks excised), so it is a display convenience and nothing addresses a session by it. Absent when nothing in the events named it. **Folded at append time and FIRST-WINS, except that a `/rename` always overrides** — so ordinary conversation does not re-title a session on every turn, and a `/rename` survives eviction of the event that carried it. agentop reads this field as a FALLBACK: its TITLE column prefers a harvested Claude Code transcript title and uses the served title only for a session the harvest cannot name. That precedence is fixed rather than a judgement about which string is better — both sides rank candidates their own way and do not agree on every session. That is the case worth having: an agent with no transcript tree on the operator's disk still routes through the proxy, so a row that used to render blank now has a name. agentop deliberately still treats such a row as unnamed for its own re-harvest backoff, so a served title does not stop it looking for a harvested one. **`?archived=true` adds history** where the proxy runs a session archive (`session.archive`, laptop only — see the chatty-traffic gotcha): every session the archive holds and memory does not, marked `resident: false`, plus a top-level `archive` object — `{bytes, maxBytes, retentionDays}` and, only when nonzero, `droppedEvents`, `writeErrors`, `droppedRenames`, `paused`, any of which means the history has gaps. A session in both is listed once, as its resident row. **That row covers the session's whole history**: `eventCount`, `totalTokens`, `costMicros`, `avoidedMicros`, `currencies`, `saturated`, `title`, `agent`, `createdAt`, `promptContext` and `inferenceHost` continue from the archive's fold of what came before this process's entry, each by its own rule, in the default list too — so with an archive and `session.max_events` unset (the default) a restart changes no figure, and without an archive they start over. Without an archive the parameter is ignored and no `archive` object is sent, which is how a client tells "no history here" from "no history yet". |
 | `GET /v1/sessions/{id}` | `application/json` | The session's most recent events. `?limit=N` (default 500, max 2000) sets the window; `?before=<seq>` returns the page ending just before that event, so the whole session is reachable by paging backward from the tail. `totalEvents` is the session's true length and `oldestSeq` the oldest event the store still holds — both present only when this response is not the whole session, so a client can tell "this is the beginning" from "there is more behind me" without a second request. 404 if unknown/expired. **One response is still not a full snapshot:** with `session.max_events` unset a session can hold thousands of events, and one real session's whole history encoded to 1.1GB — 17s to write, against clients that time out in 10. That cap is why `before` exists — until it did, a session past 2000 events had a beginning no request could reach at any limit, while still costing memory. The response is written one event at a time rather than encoded whole, so serving it costs the proxy heap proportional to one event; see the chatty-traffic gotcha below. **With a session archive, a page continues from disk** below the oldest event memory holds: a session resumed after a restart pages back through its whole history, one evicted from memory is served instead of 404'd, and `totalEvents`/`oldestSeq` describe the merged history. `GET /v1/sessions/{id}/events/{seq}` falls back to the archive the same way, and answers 404 rather than a neighbour when neither holds that seq. |
-| `GET /v1/sessions/{id}/timeline` | `application/json` | The session as spans for agentop's Timeline pane: Claude Code agents (main and subagents, linked by the `Agent` call that spawned them), model turns, tool calls (request to result, matched by tool-use id), subagent returns, and every host request or tunnel. Computed from memory plus the archive, cached per session until its newest event changes; `?from=`/`?to=` clip. Fields and rules in [`docs/session-api.md`](docs/session-api.md#get-v1sessionsidtimeline--agents-tools-and-hosts-on-one-time-axis). |
+| `GET /v1/sessions/{id}/timeline` | `application/json` | The session as spans for agentop's Timeline pane: agents (any known client on a single `main` row; Claude Code additionally its subagent tree, linked by the `Agent` call that spawned them), model turns (labeled by model), tool calls (request to result, matched by tool-use id — Anthropic `tool_result`, Responses API `function_call_output`, or chat-completions `tool_call_id`), subagent returns, and every host request or tunnel. Computed from memory plus the archive, cached per session until its newest event changes; `?from=`/`?to=` clip. Fields and rules in [`docs/session-api.md`](docs/session-api.md#get-v1sessionsidtimeline--agents-tools-and-hosts-on-one-time-axis). |
 | `DELETE /v1/sessions` | `application/json` | Clear every session: the store, and the session archive where one runs. **The cost ledger is kept** — spend totals, no content. Answers `{sessions, archivedSessions, bytes}`; a failed disk half is a 500 adding `archiveError`, with memory cleared regardless (the store clears under its lock before the archive is waited on, up to 10s). **State-changing on an unauthenticated API, so it is guarded against a browser**, each guard pinned by its own test in `core/sessionapi/clear_test.go`: DELETE only (a cross-site DELETE needs a preflight this server never approves; a simple cross-site POST needs none); a loopback `Host` — exactly `localhost`, `127.0.0.1` or `::1`, which defeats DNS rebinding; no `Origin` header; and `WithClearAllowed`, which `cmd/cortex` sets from `listener.bind_loopback_only`. A refusal is a 403 `{"error": ...}`. agentop's `X` drives it. |
 | `DELETE /v1/sessions/{id}` | `application/json` | Erase one session: the store's entry and, where the archive runs, its files — a session only the archive holds too. **The same four guards as `DELETE /v1/sessions`** (pinned again in `core/sessionapi/delete_test.go`) and the same answer, each count 0 or 1; **404** when neither half held the id, **500** with `archiveError` when the disk half failed (memory is erased regardless). The cost ledger, usage totals and inference-router pins are kept. An agent still using the session brings it back with its next request. agentop's `x` drives it, one request per session for an agent-wide erase. |
 | `GET /v1/events` | `text/event-stream` | SSE stream of new events. Optional `?session=<id>` filters to one session. Heartbeat every 30s. |

cmd/agentop/tui/timeline_pane.go

@@ -837,10 +837,19 @@ func (m *model) cursorStrip(lay tlLayout) string {
 		parts = append(parts, sanitizeLabel(p))
 	}
 	if len(parts) == 0 {
+		// The turn covering the cell names its model, so a client running several models side
+		// by side (Bob's classifier beside its main turns) reads apart.
+		suffix := ""
+		for _, tu := range m.timeline.tl.Turns {
+			if tu.Model != "" && !cell.from.Before(tu.Start) && (tu.End == nil || cell.from.Before(*tu.End)) {
+				suffix = " (" + sanitizeLabel(tu.Model) + " turn)"
+				break
+			}
+		}
 		if h, ok := m.cellHost(lay, cell); ok {
-			return styleMuted.Render(head + "no tool running; a request to " + sanitizeLabel(h.Host) + "  [enter] events")
+			return styleMuted.Render(head + "no tool running" + suffix + "; a request to " + sanitizeLabel(h.Host) + "  [enter] events")
 		}
-		return styleMuted.Render(head + "no tool running in this cell")
+		return styleMuted.Render(head + "no tool running" + suffix + " in this cell")
 	}
 	if len(parts) > 1 {
 		head += fmt.Sprintf("(%d) ", len(parts))

cmd/agentop/tui/timeline_pane_test.go

@@ -1306,3 +1306,23 @@ func TestTimelineWaits_AskUserQuestionIsWaitingOnYou(t *testing.T) {
 		t.Errorf("an open question's wait has tail %d, want the capped %d", ax.tail, timelineTailCells)
 	}
 }
+
+// A cell inside a turn that carries a model names it, so a client running several models
+// side by side (Bob's classifier beside its main turns) reads apart.
+func TestTimelineStrip_NamesTheTurnModel(t *testing.T) {
+	m := timelineModel(t, 140, 46)
+	m.timeline.windowIdx = 3
+	lay, _ := m.timelineLayoutNow()
+	m.timeline.cursor = cellOf(t, lay, 5) // main's first model call: no tool yet
+	for i := range m.timeline.tl.Turns {
+		if tu := &m.timeline.tl.Turns[i]; tu.Agent == timeline.MainAgent && tu.Start.Equal(tlAt(0)) {
+			tu.Model = "premium-ide"
+		}
+	}
+	m.timeline.layoutKey = tlLayoutKey{}
+	lay, _ = m.timelineLayoutNow()
+	strip := stripANSI(m.cursorStrip(lay))
+	if !strings.Contains(strip, "premium-ide") {
+		t.Errorf("strip = %q, want the turn's model named", strip)
+	}
+}

core/pipeline/extensions.go

@@ -321,6 +321,13 @@ type InferenceMessage struct {
 	// same content — tens of percent apart on a deeply nested tool result.
 	// Comparable across messages from one client; not across clients.
 	ContentBytes int `json:"contentBytes,omitempty"`
+
+	// ToolUseID is the tool_call_id of a chat-completions "role":"tool" result message:
+	// the id of the assistant tool_calls entry it answers. The parser also records the
+	// result in InferenceExtension.ToolResults, so a consumer walking both must skip the
+	// message half of a pair this id names — the result would otherwise count twice.
+	// Empty on every other message.
+	ToolUseID string `json:"toolUseId,omitempty"`
 }
 
 // RawJSON is a JSON value held exactly as it arrived, rather than decoded into Go values.

core/plugins/cpex/cmf_body.go

@@ -716,6 +716,9 @@ func inferenceToCMFParts(inf *pipeline.InferenceExtension) []cmfPart {
 	for _, m := range inf.Messages {
 		switch {
 		case m.Content == "":
+		case m.Role == roleTool && m.ToolUseID != "":
+			// A chat-completions result the parser also recorded in ToolResults; the
+			// loop below emits the id-carrying copy, so this one would count twice.
 		case m.Role == roleTool:
 			parts = append(parts, cmfPart{Kind: cmfPartToolResult, Content: m.Content})
 		default:

core/plugins/cpex/cmf_inference.go

@@ -408,7 +408,10 @@ func inferenceToolResultsCustom(inf *pipeline.InferenceExtension) (count int, re
 		count++
 	}
 	for _, m := range inf.Messages {
-		if m.Role == roleTool {
+		// A chat-completions result the parser also recorded in ToolResults (named by its
+		// ToolUseID) is added by the loop below; adding the message copy too would count it
+		// twice in the policy input.
+		if m.Role == roleTool && m.ToolUseID == "" {
 			add("", m.Content, false)
 		}
 	}

core/plugins/cpex/cmf_inference_test.go

@@ -586,3 +586,34 @@ func TestApplyInferenceRequestMod_NoMessagesFailsClosed(t *testing.T) {
 		t.Fatalf("unchanged: mutated=%v err=%v", mutated, err)
 	}
 }
+
+// The parser records a chat-completions tool result in BOTH places: the role:"tool"
+// message (now carrying its tool_call_id) and inf.ToolResults. The two were disjoint
+// sources when these walkers were written; a result present in both must count once.
+func TestInferenceToCMFParts_ParserShapedToolResultCountsOnce(t *testing.T) {
+	inf := &pipeline.InferenceExtension{Messages: []pipeline.InferenceMessage{
+		{Role: "user", Content: "read .env"},
+		{Role: "tool", Content: "TOKEN=xyz", ToolUseID: "call_1"},
+	}, ToolResults: []pipeline.InferenceToolResult{{ToolUseID: "call_1", Content: "TOKEN=xyz"}}}
+	parts := inferenceToCMFParts(inf)
+	want := []cmfPart{
+		{Kind: cmfPartText, Text: "read .env"},
+		{Kind: cmfPartToolResult, CorrelationID: "call_1", Content: "TOKEN=xyz"},
+	}
+	if !reflect.DeepEqual(parts, want) {
+		t.Fatalf("parts = %+v, want %+v", parts, want)
+	}
+}
+
+func TestInferenceToolResultsCustom_ParserShapedToolResultCountsOnce(t *testing.T) {
+	inf := &pipeline.InferenceExtension{Messages: []pipeline.InferenceMessage{
+		{Role: "tool", Content: "TOKEN=xyz", ToolUseID: "call_1"},
+	}, ToolResults: []pipeline.InferenceToolResult{{ToolUseID: "call_1", Content: "TOKEN=xyz"}}}
+	count, results := inferenceToolResultsCustom(inf)
+	if count != 1 || len(results) != 1 {
+		t.Fatalf("count = %d, results = %+v; want the result once", count, results)
+	}
+	if results["0"].(map[string]any)["tool_use_id"] != "call_1" {
+		t.Fatalf("results = %+v, want the id-carrying copy", results)
+	}
+}

core/plugins/inferenceparser/plugin.go

@@ -147,8 +147,20 @@ func parseOpenAIRequest(body []byte) *pipeline.InferenceExtension {
 			Role:         msg.Role,
 			Content:      msg.Content,
 			ContentBytes: msg.ContentBytes,
+			ToolUseID:    msg.ToolCallID,
 		})
 	}
+	// A chat-completions tool result is a "role":"tool" message naming the call it answers
+	// by tool_call_id — the pairing key the timeline's tool spans close on. Anthropic and
+	// the Responses API surface theirs through the same ToolResults field.
+	for _, msg := range req.Messages {
+		if msg.Role == "tool" && msg.ToolCallID != "" {
+			ext.ToolResults = append(ext.ToolResults, pipeline.InferenceToolResult{
+				ToolUseID: msg.ToolCallID,
+				Content:   msg.Content,
+			})
+		}
+	}
 	for _, tool := range req.Tools {
 		if tool.Function.Name == "" {
 			continue
@@ -963,19 +975,24 @@ type inferenceMessage struct {
 	Role         string
 	Content      string
 	ContentBytes int
+	// ToolCallID is the tool_call_id of a chat-completions "role":"tool" result message:
+	// the id of the assistant tool_calls entry it answers. Empty on every other role.
+	ToolCallID string
 }
 
 func (m *inferenceMessage) UnmarshalJSON(data []byte) error {
 	var raw struct {
-		Role    string          `json:"role"`
-		Content json.RawMessage `json:"content"`
+		Role       string          `json:"role"`
+		Content    json.RawMessage `json:"content"`
+		ToolCallID string          `json:"tool_call_id"`
 	}
 	if err := json.Unmarshal(data, &raw); err != nil {
 		return err
 	}
 	m.Role = raw.Role
 	m.Content = flattenContent(raw.Content)
 	m.ContentBytes = contentBytes(raw.Content)
+	m.ToolCallID = raw.ToolCallID
 	return nil
 }
 

core/plugins/inferenceparser/toolresults_test.go

@@ -0,0 +1,39 @@
+package inferenceparser
+
+import "testing"
+
+// A chat-completions tool result is a "role":"tool" message naming the call it answers by
+// tool_call_id. Those ids are the pairing key the timeline's tool spans close on, so they
+// must reach InferenceExtension.ToolResults; the result text stays in Messages, where
+// settle's cost math reads it.
+func TestChatCompletionsToolResultsCarryTheCallID(t *testing.T) {
+	body := []byte(`{"model":"premium-ide","messages":[
+		{"role":"user","content":"list the files"},
+		{"role":"assistant","content":"","tool_calls":[{"id":"call_1","type":"function",
+			"function":{"name":"read_dir","arguments":"{\"path\":\"/tmp\"}"}}]},
+		{"role":"tool","tool_call_id":"call_1","content":"file_a\nfile_b"},
+		{"role":"tool","tool_call_id":"","content":"no id"}]}`)
+	ext := parseOpenAIRequest(body)
+	if ext == nil {
+		t.Fatal("request not parsed")
+	}
+	if len(ext.ToolResults) != 1 {
+		t.Fatalf("ToolResults = %+v, want only the call_1 result (an empty id pairs with nothing)", ext.ToolResults)
+	}
+	r := ext.ToolResults[0]
+	if r.ToolUseID != "call_1" || r.Content != "file_a\nfile_b" {
+		t.Fatalf("ToolResults[0] = %+v, want {call_1 file_a\\nfile_b}", r)
+	}
+	var toolMsg bool
+	for _, m := range ext.Messages {
+		if m.Role == "tool" && m.Content == "file_a\nfile_b" {
+			toolMsg = true
+			if m.ToolUseID != "call_1" {
+				t.Fatalf("role:tool message ToolUseID = %q, want call_1", m.ToolUseID)
+			}
+		}
+	}
+	if !toolMsg {
+		t.Fatal("role:tool message content missing from Messages")
+	}
+}

core/session/timeline/agents.go

@@ -167,7 +167,7 @@ func buildAgents(t *Timeline, events []pipeline.SessionEvent) {
 		}
 		st.prev = msgs
 
-		turn := Turn{Agent: c.agent, Start: c.req.At, Resent: resent, Seq: c.req.Seq}
+		turn := Turn{Agent: c.agent, Start: c.req.At, Resent: resent, Seq: c.req.Seq, Model: inf.Model}
 		if c.resp == nil {
 			t.Turns = append(t.Turns, turn)
 			continue
@@ -356,8 +356,10 @@ func pairCalls(events []pipeline.SessionEvent) []call {
 	return calls
 }
 
-// agentOf names the agent that sent a request. Only Claude Code's requests are attributed:
-// AgentRole is set by its cc_is_subagent marker, and Subagent by its agent id header.
+// 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.
+// Every other known client gets the single main row — nothing on the wire says which of
+// its calls belong together beyond that.
 func agentOf(e *pipeline.SessionEvent) (string, bool) {
 	switch {
 	case e.Subagent != "":
@@ -366,12 +368,20 @@ func agentOf(e *pipeline.SessionEvent) (string, bool) {
 		return UnseparatedAgent, true
 	case e.Inference.AgentRole == pipeline.AgentRoleMain:
 		return MainAgent, true
+	case e.Client != nil && pipeline.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 *pipeline.InferenceExtension) bool {
-	if len(inf.Tools) == 0 && inf.ToolCount == 0 {
+	if inf.AgentRole != "" && len(inf.Tools) == 0 && inf.ToolCount == 0 {
 		return true
 	}
 	for i := len(inf.Messages) - 1; i >= 0; i-- {

core/session/timeline/timeline.go

@@ -86,6 +86,9 @@ type Turn struct {
 	// retry, so the time before it went to retrying rather than to the user, who added nothing.
 	Resent bool   `json:"resent,omitempty"`
 	Seq    uint64 `json:"seq"`
+	// Model is the model the call asked for, so a client that runs several models side by
+	// side (Bob's premium-ide turns beside its security classifier) reads apart.
+	Model string `json:"model,omitempty"`
 }
 
 // Tool is one tool call: from the response that requested it to the agent's first request