Skip to content

Latest commit

 

History

History
1335 lines (1194 loc) · 80.6 KB

session-api.md

File metadata and controls

1335 lines (1194 loc) · 80.6 KB

Session Events API

When session.enabled is true (the default) and listener.session_api_addr is non-empty (default :9094; :47601 on a local install), the proxy exposes the captured session store over HTTP. Intended for operators debugging the plugin pipeline — via kubectl port-forward in a cluster, or directly on a laptop — and for the agentop TUI.

Trust model: no authentication. Bind only on in-cluster addresses, never behind ingress. Payloads may contain raw user messages, LLM completions, and tool results. Where listener.bind_loopback_only is set (a local install), every route answers 403 to a request whose Host is not localhost, 127.0.0.1 or ::1, or that carries an Origin header, so a web page cannot read it through DNS rebinding. The stats server applies the same check.

Endpoints

Method & Path Format Purpose
GET / text One-line-per-endpoint index — answers "is this the session API, and on the right port?"
GET /v1/sessions application/json List active sessions (see below)
GET /v1/sessions/{id} application/json The session's most recent events; ?limit=N and ?before=<seq> page backward. ?view=summary omits the large payloads
GET /v1/sessions/{id}/events/{seq} application/json One event by its sequence number
GET /v1/sessions/{id}/timeline application/json The session as spans: Claude Code agents, tool calls, subagent spawns and returns, and hosts (see below)
GET /v1/sessions/{id}/search application/json The seqs of the session's events whose bodies or capture hold ?q=, as the detail view shows them (see below)
DELETE /v1/sessions application/json Clear every session: the store, and the session archive where one runs. The cost ledger is kept
DELETE /v1/sessions/{id} application/json Erase one session: the store's entry and, where the archive runs, its files (see below)
GET /v1/events text/event-stream SSE stream of new events; ?session=<id> filters to one session. Heartbeat every 30s
GET /v1/export application/x-ndjson The session archive as content-free records, one per event — the export for offline analysis; ?session=<id> and ?since=<duration> select. A walk that dies past its first record resets the connection rather than ending the body cleanly, so a truncated export reaches a client as an error (session-export.md)
GET /v1/pipeline application/json Active pipeline composition, per plugin: name, direction, position, capabilities, runtime config. onError is sent only when it is not the default — in practice observe, since an on_error: off plugin is not built. A plugin under observe runs and records, but its rejections, body writes and redirects are dropped (header writes still apply), so its config says what it would do. agentop renders this as the Pipeline pane (P)
GET /v1/plugins application/json Catalog of every registered plugin, active or not. 404 when the binary built its session API without WithCatalog. agentop renders this as the Catalog pane (C)
GET /v1/usage application/json Windowed usage aggregation — the aggregate behind agentop cost; parameters and semantics in pricing.md
POST /v1/import application/json, or application/x-ndjson with progress Laptop only: import agent transcripts from disk into the archive and the cost ledger (see below). 404 otherwise
POST /v1/ingest NDJSON in, 204 out Praxis mode only: rows that cortex-gateway records (see below). 404 otherwise
GET /v1/ingest/stats application/json Praxis mode only: the ingestion counters (see below). 404 otherwise
GET /healthz text Liveness probe

GET /v1/sessions

{"sessions": [{
  "id": "…", "createdAt": "…", "updatedAt": "…", "eventCount": 42, "active": true,
  "title": "…", "agent": "claude-code", "totalTokens": 1186300, "costMicros": 254600,
  "avoidedMicros": 3700, "promptContext": {"tokens": 16384, "stated": true,
  "at": "2026-10-15T20:01:02Z", "msgs": 12}, "inferenceHost": "api.anthropic.com",
  "procs": ["41963.1791718279766260000"], "lastRequestAt": "…"
}, {
  "id": "pending:claude-code@41963.1791718279766260000", "eventCount": 12, "…": "…",
  "linkedTo": [{"session": "…", "first": "…", "last": "…"}], "linkedAll": true
}]}

id, createdAt, updatedAt, eventCount and active are always present; every other field is omitted rather than zero when unknown. The fields worth knowing by name:

  • title is a suggestion, not an identifier — derived from the session's own events (a /rename, else a <user_query>, else ordinary user prose, with <system-reminder> blocks excised). Folded at append time and first-wins, except that a /rename always overrides. Nothing addresses a session by its title. agentop's TITLE column uses it only as a fallback, after a harvested Claude Code transcript title. For its re-harvest backoff, agentop still treats a row with only a served title as unnamed, so it keeps looking for the harvested title.
  • inferenceHost — 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. Tunnel rows, MCP calls, responses and denials leave it as it was: an event with no inference parse must not clear it. agentop's sessions-table SERVER column reads it, and so do the count of running sessions on S's result line and the warning from agentop server remove. inferenceHostFromHistory is true when that host came only from the archive's fold, because no request the proxy's current entry for the session holds has set it. 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 resumed session.
  • procs — the processes, <pid>.<start>, whose own session header named this session. Recorded from each request's proc and sessionHeader, and continued from the archive's fold like the other figures.
  • projects — the distinct project labels that the session's events carried, most recent first, at most 8. Folded at append time, and continued from the archive's fold like the other figures. Absent on default and on pending buckets.
  • source is "imported:<agent>" while every event of the session is imported (see POST /v1/import). It is absent when the session has one or more live events. So a live request for an imported session gives it a live event, and the mark goes.
  • Pending buckets. A coding agent's calls before its process names a session are recorded under pending:<agent>@<pid>.<start> (or pending:<agent> when the process could not be looked up), carrying their proc. Nothing renames a bucket. Instead, when the list is read, a bucket whose process later named a session gets linkedTo — the sessions it named that its calls belong to, each with the first and last request that named it; a call belongs to the first session its process named at or after it — and linkedAll when every request in it falls before one of them. A response goes where its request went. agentop hides a linkedAll bucket that links to one session and shows its calls inside it; a bucket linked to two sessions, or with calls after its process's last claim, stays a row of its own.
  • ?archived=true adds history where the proxy runs a session archive (session.archive, laptop only): 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, droppedCaptures, paused, any of which means the history has gaps. A session in both is listed once, as its resident row, and that row covers the session's whole history: eventCount, totalTokens, costMicros, title, agent, createdAt and the rest continue from the archive's fold of what came before this process's entry. This applies to the default list too, not only with ?archived=true: with an archive and session.max_events unset, a restart changes no figure. Without an archive, the figures start over at a restart, the parameter is ignored, and no archive object is sent. That is how a client tells "no history here" from "no history yet".

GET /v1/sessions/{id} — snapshots and paging

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 for an unknown or expired session.

One response is 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 over a gigabyte. The response is written one event at a time rather than encoded whole, so serving it costs the proxy heap proportional to one event — but a client that reads it all still pays for all of it. Page with before rather than raising limit.

?view=summary omits the large payloads. agentop sends it on each session page fetch (the events table). It does not send it on GET /v1/sessions/{id}/timeline. The script SDK (core/plugins/script/sdk/cortex.py) sends it too. The proxy then removes these fields from each event in the response:

  • inference: messages, tools, toolCalls, toolResults and historyToolCalls. It adds messageCount, toolCount and toolCallCount, the lengths of messages, tools and toolCalls. Each one is absent when it is zero.
  • a2a: artifact.
  • mcp: params and result.

All other fields stay, which includes inference.completion, a2a.parts and plugins. The stored events do not change. The value must be exactly summary. With any other value, the proxy sends full events. GET /v1/sessions/{id}/events/{seq} always returns the full event. /v1/events streams full events.

The response echoes "view": "summary" when it applied the summary. A proxy that does not know the parameter ignores it. It sends full events and no view field. So a client that asked for the summary reads view to know which it got. Do not infer it from missing bodies: a session with no inference traffic has no bodies to omit.

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.

?raw=1 adds the exact bytes (#1494), under raw, when the archive holds a capture for the event. Only the archive holds them, so raw is absent without an archive, for an event that was not captured or predates capture, and for the second or so before the archive flushes a new event. A request event's raw:

Field What it is
request the body as the agent sent it
forwarded the body as Cortex sent it upstream; absent when no plugin rewrote it
requestHeaders the request headers, without credential headers
query the URL's raw query

A response event's raw has response: {status, headers, body, decoded, truncated, incomplete}. body is up to 10 MiB of the body as it came off the wire, in its Content-Encoding, unless decoded says the proxy decompressed it to read it for a plugin. truncated means it was longer, and incomplete means it was not read to its end: the stream broke off, or the proxy, a plugin or the client stopped it. A body that is not valid UTF-8 — every compressed body — is in requestBase64, forwardedBase64 or bodyBase64 instead. An unknown raw value is ignored, so an older proxy answers with the event alone.

GET /v1/sessions/{id}/timeline — agents, tools and hosts on one time axis

This is the endpoint for per-tool and per-call timings, and it carries no prompts. Each tools[] entry is a named span with start, end and a preview of the tool's own argument; each turns[] entry is one model call. Both are derived from the events, so neither needs the message bodies — reach for this rather than a cortex-session-dump --full, which does carry them. Worked queries are under Reading timings out below.

The session's history as spans, for agentop's Timeline pane. Computed from the whole session: memory first, then the archive behind it (a 6,000-event session takes a few milliseconds; reading one that is only on disk takes over a second). The result is cached per session until its newest event changes, however long that takes; an unanswered request still ages out on each read, as it would on a fresh compute. A pane refreshing every second costs one compute per new event, and a session only on disk is read once. Reads at most 50,000 events, newest first; truncated: true says older ones exist. 404 for an unknown session. ?from= and ?to= (RFC 3339) keep only the spans that overlap the range; agents is always the whole list.

{"id": "…", "lastSeq": 1225, "start": "…", "end": "…",
 "agents":  [{"id": "main", "label": "main agent"},
             {"id": "a1bf9707ee0e71012", "parent": "main", "label": "Survey the code",
              "type": "Explore", "spawnTool": "toolu_…", "spawnedAt": "…", "returnedAt": "…"}],
 "turns":   [{"agent": "main", "start": "…", "end": "…", "finish": "tool_use", "seq": 12,
              "outputTokens": 850}],
 "jobs":    [{"agent": "main", "id": "bk42", "toolUseId": "toolu_…", "start": "…", "end": "…", "seq": 40}],
 "tools":   [{"agent": "main", "id": "toolu_…", "name": "Bash", "start": "…", "end": "…",
              "preview": "go test ./...", "seq": 13}],
 "returns": [{"agent": "a1bf9707ee0e71012", "into": "main", "at": "…", "seq": 90}],
 "hosts":   [{"host": "api.github.com", "kind": "tunnel", "start": "…", "end": "…", "status": 200, "seq": 7}]}

seq does not mean the same event on every span, which matters when joining. A span's seq is the event it was derived FROM, and that is not the same end of the exchange in each case:

Span Its seq is So to join it to an event
turns[] the request event token counts are on the response — pair by requestId, not by this seq
tools[] the response that asked for the tool joins directly to that response's inference
jobs[], returns[] the request that carried the result as turns[]
hosts[] the event the row came from —

Joining turns[].seq to a response event therefore matches nothing and yields an empty result rather than an error. Use tools[].seq when you want tokens beside a span, or pair turns by requestId.

The two endpoints read to different depths. This one reads up to 50,000 events; GET /v1/sessions/{id} caps ?limit at 2,000. So on a session larger than that, a join against a single events page silently covers only the newest 2,000 events — page with ?before= to the same depth, or expect spans with no matching event.

Turns and tools are attributed to any known client (Claude Code, Bob, Codex, OpenCode, Pi — the canonical name parsed from the User-Agent); each gets a single main row, and every model call is a turn, including classifier side calls, labeled by model. Claude Code additionally gets its subagent tree, returns and background jobs — those key on the agent ids and marker strings (agentRole, subagent, parentSubagent) no other client sends. Requests from unknown clients render as host rows only.

Bob child tasks are agent rows too, keyed by subagent and parented to main. A subtask (subagentKind: "subtask") has type: "subtask" and the label subtask <id>. A subagent keeps the label subagent <id>. A Bob child has no spawn link: nothing on the wire names the call that started it.

  • A turn is one model call, request to end of response. Left out: progress-label and away-recap calls (matched by their prompt text in the last non-system message — Claude's own prompt strings, applied to every client), and Claude Code's tool-less side calls (titler, classifier). Another client's side calls are kept, cost and all. error marks a call that failed: an upstream error, a refusal, the client giving up, a finish of content_filter, failed or cancelled, or a response with no finish reason when the request asked for a stream or the reply came as one, which is a stream cut mid-reply. A buffered reply to a buffered request, parsed as inference, with no finish reason is complete, not an error: Bob's router call answers with a model name only. resent marks a call that sent its agent's previous call's conversation again unchanged: a retry. outputTokens is the output token count of the finished response (inference.outputTokens of the response row). liveTokens is on an open turn only. It estimates the tokens that the response sent so far: the bytes the forward proxy read, divided by the session's bytes per output token. The ratio comes from the session's finished turns that streamed for 5 s or more (durationMs − ttfbMs of the response row). A session with no such turn has no liveTokens. The envoy-sidecar (ext_proc) and the reverse proxy do not give liveTokens. liveTokens is calculated on each read. It is not part of the cached timeline.
  • A tool runs from the response that requested it to the agent's first request carrying its result (inference.toolResults[].toolUseId). A tool Claude Code started while the response was still streaming can have its result recorded first; its end is clamped to its start. A CONNECT to a model host that could not be dialed, after the tool started and before its result, ends it there unless its agent, or an agent below it, made a successful turn in between: the agent tried to report back and the network was gone, so the result arrived only when it came back, or never. A failure the agent recovered from is a blip and ends nothing. A tool with neither has no end and is still running. preview is up to 80 characters of the command, path or description.
  • An agent links to the Agent tool call that started it by the id the call's result names (agentId: …). A fork's result names none, so a fork takes its parent's earliest unmatched spawn. Requests recorded before the proxy captured agent ids are one subagents agent.
  • A return is a subagent's result reaching another agent: <agent-message from="…"> or <task-notification> in a message that agent had not sent before. A run that ends with SubagentHandback returns at its <agent-message>. The <task-notification> that Claude Code sends after it is not a return: it comes later, often with the user's next prompt.
  • A job is a background shell command, from the tool result that acknowledged it (Command running in background with ID: …) to the first <task-notification> naming that id, or to the TaskStop result that stopped it (a stopped job gets no notification). Its tool call ends at the acknowledgement, so the job is what shows it still running. A job with no end is one no notification or TaskStop named: still running, or never reported, as a server left running when its agent exited is. A job whose agent was cut off ends where its tools do: at the first failed dial to a model host after the agent's last call. Absent when the session started none.

Hosts are every outbound request paired with its response, every opaque tunnel, and every denial. kind is llm, mcp, http or tunnel, and h:443 shares h's row.

end absent means still in flight. A span that never got an answer but provably stopped is lost and ends where it started: a turn or tool whose agent moved on, a SubagentHandback or a workflow agent's final StructuredOutput (each ends the run, and no result follows) and every tool asked for beside it, a subagent's tool still open at a <task-notification> naming that agent, or a request more than ten minutes old.

GET /v1/sessions/{id}/search — find the events whose bodies hold a text

agentop's events pane uses this for its details search. The events list carries view=summary, which drops the bodies, so agentop checks the summaries it holds, and this route checks what the summary drops.

curl -s 'localhost:9094/v1/sessions/<id>/search?q=retry%20budget'
{"seqs":[12,14,40],"lastSeq":980,"schemaVersion":1}
  • seqs is ascending: every event of the session that matches, in memory and in the archive. lastSeq is the newest seq the pass read. A client that holds a newer event asks again.
  • The match is a case-insensitive substring, folded rune by rune with unicode.ToLower, as agentop's / folds.
  • What it reads, only where the event detail view shows it for the event's phase (sessionapi.DetailKeys):
    • request: inference.messages, inference.tools (a tool's parameters as JSON), inference.toolResults, the history tool calls, mcp.params
    • response: inference.toolCalls, mcp.result, a2a.artifact
    • the key names in those parts, as the view shows them
    • where the archive holds a capture: its body blocks (keys and values when a block is JSON, its text when not), the keys and values between blocks, the headers, the query, and a response's status. Image and document blocks and binary bodies are skipped: the view shows them as labels.
  • It does not read the fields the summary keeps (agentop checks those), the labels agentop writes itself in the raw part (forwarded as sent, [image … KB]), a match that spans a key and its value, or the quotes and punctuation the view draws around the keys and values it reads.
  • Errors: an empty q is 400 ({"error":"q is required"}). An unknown session is 404 with {"error":"session not found"}. A proxy that predates the route answers the mux's plain-text 404, which is how a client tells the two apart. An archive read that fails is 500: an answer without part of the history could say "no match" where there is one.
  • Cost: one pass. A long string that many events share is checked one time. On a 10,767-event laptop session, the pass took about 4 s, with a peak heap of 149 MB (95 MB with GOGC=25). One plain read of the same archive peaks at about 130 MB. The pass keeps a result for each long string that the events of one segment share, and drops it at the next segment. It keeps none for a capture's text, which no two events share. The pass stops when the client closes the connection, and agentop closes it when its search is dropped.

DELETE /v1/sessions

Clears every session: the in-memory 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, for up to 10s.

This is the one state-changing route pair on an unauthenticated API, so both are guarded against a browser: DELETE only (a cross-site DELETE needs a preflight this server never approves), a loopback Host (localhost, 127.0.0.1 or ::1, which defeats DNS rebinding), no Origin header, and the server must have been built with clearing allowed (listener.bind_loopback_only on a local install). A refusal is a 403 {"error": ...}. Each guard is pinned by its own test in core/sessionapi/clear_test.go. agentop's X drives it.

An erased session comes back on the next agentop import while its transcript is still on disk. It comes back as an imported session. The erase keeps a forget record of the session, so the import does not count its cost again. This applies to both DELETE routes. See POST /v1/import.

DELETE /v1/sessions/{id} — erase one session

Erases 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 in core/sessionapi/delete_test.go) and the same answer shape, 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 — see laptop-service.md for the user-facing story. The next agentop import brings an erased session back from its transcript, as an imported session. Its cost is not counted again: the erase kept the ledger rows, and a forget record tells the import which turns those rows hold.

POST /v1/import — transcript import (laptop only)

Reads the transcripts that an agent keeps on disk, and writes each session into the session archive and the cost ledger. The sessions then show in agentop as ordinary sessions with an imported mark. agentop import drives this route (see cmd/agentop/README.md).

The route exists only when the archive is on and the session API is loopback-only (listener.bind_loopback_only, as on a local install). Otherwise the answer is 404. The route reads only the agent's own store. It does not accept a path, events or files from the caller.

The body is JSON, at most 4 KiB:

{"agent": "claude-code", "since": "2026-10-01T00:00:00-04:00", "dryRun": true}
  • agent selects one source. Empty selects every source. An unknown agent is a 400 that names the supported agents.
  • since (RFC 3339) skips a transcript file that was last changed before it.
  • dryRun counts what an import would do and writes nothing.
  • progress asks for progress lines before the report (see below).

Bad JSON is a 400. One import runs at a time: a second request while one runs gets 409, and the first one continues. After these checks the route sends the 200 header at once, and then does the work. So an error of one agent is in the body, not in the status:

{"dryRun": true, "agents": [{"agent": "claude-code", "imported": 12, "replaced": 3,
  "skippedLive": 40, "skippedCurrent": 7, "skippedLines": 2, "skippedExpired": 1,
  "unreadable": 1, "notImported": 5, "stopped": "archive full", "error": "…"}]}

skippedExpired, unreadable, notImported, stopped and error are sent only when they are set.

Progress. With "progress": true the body is application/x-ndjson: one JSON object on each line. The report above is the last line. Before it, each agent sends progress lines, at most 4 a second:

{"progress": {"agent": "claude-code", "done": 940, "total": 1805}}

total is the number of sessions that the source found, and done counts each session that the source finished, skipped sessions too. The first line has done: 0, and the last line of an agent has done equal to total. A skipped session is fast and a parsed session is slow, so done does not grow at a steady rate. An older proxy ignores progress and sends only the report.

Live sessions and re-import. The import applies these rules to each session in order:

  1. A session with live events is skipped and never changed (skippedLive). Live events are in memory, or in the archive without the imported mark.
  2. An imported copy that is as new as the transcript is skipped (skippedCurrent).
  3. A newer transcript replaces the imported copy (replaced). Only its new turns go to the cost ledger.
  4. A session that the archive does not hold is imported (imported).

Rule 4 also applies to an erased session, and to a session that the day limit or the size limit removed. The next import writes it again in full, as an imported session. The ledger kept the rows of the removed session, so the import must not count them again. The archive keeps a forget record for this:

  • When the archive removes a session (x, a clear X, session.archive.retention_days or session.archive.max_bytes), it adds one line to forgotten.jsonl in the archive dir, next to data/: {"id":"<session id>","from":<unix ms>,"to":<unix ms>}. from is the time the archive first wrote the session, and to is its last request.
  • It writes a line only for a session with tokens or cost, and only when the cost ledger is on. A clear does not remove forgotten.jsonl.
  • The import does not send a turn inside that span to the cost ledger. A turn in the minute before from counts as inside the span. It sends a turn after to. It sends a turn before the span only when no ledger row of the same project is near it that the proxy wrote live or that an earlier import wrote: a fork copies its parent's turns, and the ledger can already hold them for the parent.
  • A replace by an import also adds a line for the old copy, before it deletes that copy. If the write of the new copy fails, the next import uses the line.
  • A line is kept until its to is older than cost_ledger.retention_days plus 1 day. After that the ledger has no rows of the session to protect.

A new session has no record. A session that was removed before Cortex kept forget records has no record too. For such a session, the import does not count any turn that is near a live ledger row, or near a row that an earlier import wrote. The rows have no session id, so this check can also skip a turn when only another session of the same project made a row in that minute.

What an import writes:

  • Each imported event has source: "imported:<agent>". A live event has no source. The session summary has the mark only while all its events are imported.
  • The cost record of an imported turn has source: "transcript". Cortex prices a Claude Code turn and a Codex turn at today's rates. A Bob turn keeps Bob's own cost (see Sources). A turn with no usage has no cost record.
  • The ledger row of an imported turn has source: "transcript". A live row has no source.
  • An imported turn with no cost record has no ledger row, from every source. The live proxy records such a turn as one request at $0, so the request count and the priced share of an import can be lower than those of live traffic. When a later import finds the usage of the turn, that import adds the row.
  • A turn before the ledger's retention cutoff goes to the archive only.
  • An imported segment is kept for retention_days from its newest event. A session older than that is skipped (skippedExpired). The Claude Code source checks this, and Rule 1, before it reads the files: a file's mtime is not older than its newest line. So an old transcript with no turns counts here too.
  • The import stops before a session that would take the archive above 90% of max_bytes. Then stopped is "archive full", and notImported counts the sessions left.
  • One line that the source does not recognize, in a session that the import parses, is skipped and counted (skippedLines). It does not stop the import.
  • A session whose main transcript cannot be read is skipped and counted (unreadable). The proxy logs the path and the error.
  • LAST 1H and the usage pane's hour windows show imported turns only after the next proxy restart. The import does not feed them.

Sources. Claude Code (claude-code), Bob (bob), Codex (codex), OpenCode (opencode) and Pi (pi) are supported. The proxy answers any other agent with an error that names the supported agents.

The Claude Code source reads ~/.claude/projects/<project>/<uuid>.jsonl, or the same path under CLAUDE_CONFIG_DIR when that variable is set. Each event has the claude-code client and the project of the transcript's working directory. A <synthetic> assistant line is not a turn: Claude Code writes it itself, for an API error or "No response requested.".

The Bob source reads ~/.bob/db/bob.db. It runs sqlite3 -readonly -json as a subprocess, and adds no SQLite driver to Cortex. When sqlite3 is not on PATH, the bob result has an error that names the program, and the other agents continue. When bob.db does not exist, the source imports nothing.

  • One Bob task is one session. The session id is the task id (X-Task-Id).
  • A subtask is in the session of its root task. Its events have subagent set to the subtask's id and subagentKind: "subtask".
  • Bob keeps a subagent's turns in the messages of the parent's spawn_subagent tool row. They are in the session of the root task, with subagent set to _meta.subagentId and subagentKind: "subagent". A nested message with no _meta.timestamp has the time of the message before it, or of the parent's spawning turn. When the subagent's task has its own rows, the import reads those rows and not the spawn row.
  • A message gives one turn per session. The spawn row of a resumed subagent holds its earlier messages again, and they are context only.
  • The messages of a start_subtask tool row is a copy of the subtask's own rows, and the import does not read it.
  • Each event has the bob client, the model alias that Bob records (for example premium-ide), and the project of tasks.directory. When that is empty, the project is the task's workspace.
  • The cost of a Bob turn is Bob's own figure (_meta.spend.cost), with source: "transcript" and provenance: "authoritative". Cortex does not price Bob turns from its rate table. The rate table gives the unit only: the record's currency is the unit of the Bob endpoint (Bobcoins on a local install), and so is the ledger row's. totalTokens is Bob's contextTokens. Bob records no split into input and output tokens.
  • Bob Shell and Bob IDE both write bob.db. The source does not read the older ~/.bob/tmp/*/chats/*.json files or the IDE's globalStorage/ibm.bob-code/tasks.

The Codex source reads ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl, or the same path under CODEX_HOME when that variable is set. It also reads a rollout that Codex compressed to .jsonl.zst. It does not import a rollout from archived_sessions/. When the sessions/ directory does not exist, the source imports nothing.

  • The session id is the rollout's session_meta.session_id, else its id. This is the value that Codex sends in the Session-Id header.
  • The rollout of a subagent is in the session of its root, with subagent set to the subagent's thread id.
  • Each event has the codex client, the model of the turn (turn_context.model), and the project of the turn's working directory.
  • Cortex prices a Codex turn at today's rates, from the usage of its token_usage_record or token_count line. A tool result does not end a turn, because some Codex versions write token_count after the tool results. A turn with no usage has no cost record and no ledger row. When a later import finds its usage, that import adds the row.

The OpenCode source reads $XDG_DATA_HOME/opencode/opencode.db, or ~/.local/share/opencode/opencode.db when XDG_DATA_HOME is not set. It runs sqlite3 -readonly -json as a subprocess, as the Bob source does. When sqlite3 is not on PATH, the opencode result has an error that names the program. When the database does not exist, the source imports nothing.

  • The session id is the id that OpenCode sends as X-Session-Id: parent_id for a subagent, fork_session_id for a fork, else the session's own id.
  • A subagent's events are in the session of its parent, with subagent set to the subagent's own id.
  • A fork's own turns are in the session of its source. The fork's copies of the earlier messages of the source give no turns.
  • Each event has the opencode client with OpenCode's version, the model id that OpenCode records, and the project of the session's directory.
  • Cortex prices each turn at today's rates, with the OpenCode Zen endpoint (opencode.ai) for the rate lookup. A Zen *-free model prices as zero. Output tokens include OpenCode's reasoning tokens. A turn with no token counts gets no cost.
  • OpenCode does not store its system prompt or its tool list, so an imported request has neither.

The Pi source reads ~/.pi/agent/sessions/<dir>/<time>_<id>.jsonl, or the same path under $PI_CODING_AGENT_DIR/sessions/ when that variable is set in the proxy's environment.

  • One Pi session file is one session. The session id is the id of the file's session header line. It is the same id that the extension from agentop configure pi sends as x-session-id.
  • A file with no session header is counted as unreadable.
  • A fork (a header with parentSession) is its own session. The import does not follow parentSession.
  • Each event has the pi client and the project of the header's cwd.
  • Each assistant message is one turn, error turns included. The request holds the conversation that Pi sent: the turn's own branch of the entry tree, and after a compaction the summary and the kept entries.
  • A Pi turn is priced at today's rates through the pricing table, by model id. The import does not use Pi's own usage.cost. A turn with no token counts (for example an error turn) has no cost.

POST /v1/ingest — rows from cortex-gateway (praxis mode)

Registered only when praxis.enabled and listener.bind_loopback_only are both set; otherwise this route and GET /v1/ingest/stats answer 404 and no erase mark is kept. The design is in superpowers/specs/2026-11-07-praxis-mode-design.md, Section 1.

Auth and guards, in order:

  1. A non-loopback Host, or an Origin header: 403.
  2. No Authorization: Bearer <token>: 401. Cortex reads the token from the file that CORTEX_GATEWAY_TOKEN_FILE names.

A browser cannot add Authorization to a simple cross-site POST, so the token is the protection and the guards are a second layer.

The body is NDJSON, one line per row, on one long-lived stream. A line over 64 MiB is discarded and refused. A refused line does not close the stream. When the body ends, the answer is 204. On shutdown, Cortex ends each open stream at once; lines still queued in the gateway are lost and counted there.

Line format, version 1:

{"v":1, "schemaVersion":1, "op":"append", "requestId":"…", "startedAt":"<RFC 3339, ns, UTC>",
 "session":"<recording session>", "event":{ "...SessionEvent wire JSON..." },
 "capture":{"original":"<base64>", "forwarded":null, "header":{"Name":["v"]}, "query":"",
            "response":{"status":200, "header":{}, "body":"<base64>", "decoded":true,
                        "truncated":false, "ended":true, "incomplete":false}},
 "cost":{"headers":{"X-Litellm-Response-Cost":"0.01", "Content-Type":"application/json"}}}

A request row carries original, header and query; a response row carries response only. A capture the producer dropped is {"dropped": true}. cost is on response rows only.

A response row's inference leaves out the request-only fields: messages, tools, toolResults, historyToolCalls and historyThinking. They are most of a line's bytes, and the request row carries them already. Cortex puts them back from the request row of the same requestId, so the stored response row is the same as in direct mode. A field the response row carries is kept. When the producer dropped the request row, the response row is stored without them.

What Cortex does with a line:

  • Files it under session; an empty session goes to the active session, then to default, as a listener files it.
  • Assigns seq, sessionId and at. The producer's values are not kept.
  • Removes the producer's plugins.cost and plugins.litellm-budget-track, and settles a response row again from cost.headers and its own rate table.
  • Keeps a capture only for an event with inference, removes credentials from its headers and query again, and keeps a response capture only after the request capture of the same requestId (held for up to 1 hour).
  • Decodes up to 8 lines of a stream at the same time (at most one per CPU), and files them one at a time, in stream order.
  • Drops a line whose startedAt is before an erase of its session (DELETE /v1/sessions/{id} or DELETE /v1/sessions) in the last 10 minutes, so a queued row cannot bring an erased session back. A dropped line also releases its tunnel join, and the tunnel then writes no row.
  • Joins the line to the forward proxy's state for the same requestId (each join is kept for up to 60 s):
    • A request row of a TLS-bridged request goes through its CONNECT tunnel's pairing path, so the tunnel's open row and its request row pair as in direct mode. A tunnel that closes before its row arrives waits for the row. A join that expires settles the tunnel as in direct mode.
    • When Cortex cut the response itself (proxy_error, such as its idle read cutoff), Cortex's error replaces the one the gateway recorded, and the row keeps the status the client got, as in direct mode.

Refusal reasons: bad_json, version (v is not 1), schema (schemaVersion is not this API's), op (not append), line_cap, erased.

GET /v1/ingest/stats

The ingestion counters, since start. The same loopback and Origin guards as POST /v1/ingest; no token.

{"ingest_lines_total": 120,
 "ingest_refused_total": {"bad_json":0, "version":0, "schema":0, "op":0, "line_cap":0, "erased":1},
 "ingest_captures_dropped_total": 0}

Quick examples

The agentop TUI handles port-forward + connection automatically — pick a pod from the Namespaces → Pods picker. For raw HTTP exploration, set up your own port-forward first:

POD=$(kubectl get pod -n team1 -l app.kubernetes.io/name=weather-agent \
  -o jsonpath='{.items[0].metadata.name}')
kubectl port-forward -n team1 $POD 9094:9094 &

# List sessions
curl -s http://localhost:9094/v1/sessions | jq

# Snapshot the most recently updated session
SID=$(curl -s http://localhost:9094/v1/sessions | jq -r '.sessions[0].id')
curl -s "http://localhost:9094/v1/sessions/$SID" | jq

# Page backward: the oldest event this response carries is the next cursor.
# Repeat until the first event's seq equals oldestSeq — that is the beginning.
curl -s "http://localhost:9094/v1/sessions/$SID?limit=500" \
  | jq '{cursor: .events[0].seq, oldestSeq, totalEvents}'
curl -s "http://localhost:9094/v1/sessions/$SID?limit=500&before=<cursor>" | jq '.events|length'

# Live tail every event
curl -N http://localhost:9094/v1/events

# Live tail a single session
curl -N "http://localhost:9094/v1/events?session=$SID"

Reading timings out

Per-tool and per-call latency without downloading prompts. All of this is a local install on :47601; in a cluster use the port-forward above. Queries below are against a real 2,911-event session.

WHAT EACH QUERY DOWNLOADS, because "no prompts" is a property of the query, not of the API:

Query Endpoint Carries
per-tool latency, Bash previews /timeline spans only — no message bodies, but preview IS tool-argument text (a shell line, a path, a URL)
per-call tokens, models ?view=summary no messages, tools, toolCalls or toolResults — but view=summary KEEPS inference.completion and a2a.parts, because the / search reads them, so every model reply is in the response
untruncated Bash command full event view everything, prompts included; jq discards them after the download

So /timeline is the only one of the three that never transfers a message body. It is not prompt-free: its preview fields copy tool-argument text, and a search query or a task description can repeat prompt text verbatim. For the other two, the body reaches your shell and jq filters it — fine on a laptop, worth knowing before piping it anywhere.

Pick a session. ?archived=true is the important part — without it you see only what is still in memory, which on a laptop is a fraction of the history.

API=http://localhost:47601
curl -s "$API/v1/sessions?archived=true" | jq -r '
  (["EVENTS","AGENT","SESSION"]|@tsv),
  ([.sessions[] | select(.id | startswith("pending:") | not)]
   | sort_by(-(.eventCount//0)) | .[]
   | [(.eventCount//0), (.agent//"-"), .id] | @tsv)' | column -t

Skip the pending: buckets: those are an agent's calls from before its process named a session, which are real traffic but not a session to analyse.

Copy one id into SID — every query below uses it:

SID=<paste-a-session-id>
# or take the largest:
SID=$(curl -s "$API/v1/sessions?archived=true" | jq -r '
  [.sessions[] | select(.id | startswith("pending:") | not)]
  | sort_by(-(.eventCount//0)) | .[0].id')

Per-tool latency. jq's fromdateiso8601 cannot parse these timestamps — they carry fractional seconds and a numeric offset — so parse the parts. Dropping the fraction costs the sub-second resolution that separates Edit from Read; ignoring the offset makes any span that crosses a DST transition an hour out, so ts below subtracts it.

curl -s "$API/v1/sessions/$SID/timeline" | jq -r '
  def ts: capture("^(?<b>[^.Z+]+)(\\.(?<f>[0-9]+))?(?<sign>[+-])(?<oh>[0-9]{2}):(?<om>[0-9]{2})$|^(?<bz>[^.Z]+)(\\.(?<fz>[0-9]+))?Z$")
          | if .b then (.b+"Z"|fromdateiso8601) + (if .f then (".\(.f)"|tonumber) else 0 end)
                       - (((.oh|tonumber)*3600 + (.om|tonumber)*60) * (if .sign=="-" then -1 else 1 end))
            else (.bz+"Z"|fromdateiso8601) + (if .fz then (".\(.fz)"|tonumber) else 0 end) end;
  def pct(a;p): (a|length) as $n | if $n==0 then null else a[(($n-1)*p)|round] end;
  [.tools[] | select(.end != null and (.lost // false) == false)
   | {name, ms: ((((.end|ts)-(.start|ts))*1000)|round), err: (.error//false)}]
  | group_by(.name)
  | map({name:.[0].name, n:length, ms:(map(.ms)|sort), errs:(map(select(.err))|length)})
  | map({name,n,errs, p50:pct(.ms;0.5), p95:pct(.ms;0.95), total_s:((.ms|add)/1000|round)})
  | sort_by(-.total_s)
  | (["TOOL","N","ERRS","P50ms","P95ms","TOTALs"]|@tsv),
    (.[]|[.name,.n,.errs,.p50,.p95,.total_s]|@tsv)' | column -t
TOOL             N    ERRS  P50ms  P95ms   TOTALs
Bash             452  9     487    65029   6260
AskUserQuestion  7    0     37419  409509  703
WebFetch         34   1     14448  26565   440
WebSearch        12   0     15448  15458   206
Edit             87   1     48     201     6
Read             5    0     24     57      0

(An excerpt — the single-call tools are left out for width.)

TWO SPAN STATES TO FILTER, for different reasons.

  • No end — still running. Not a zero: ts would run capture on null and the whole query fails with null (null) cannot be matched, as it is not a string. Hence select(.end != null).
  • lost: true — never answered but provably stopped, and end is set EQUAL TO start (timeline.go: "its End is its Start, so it draws as a tick rather than a bar"). This one is the false zero, and it passes an end != null filter. Hence (.lost // false) == false.

Drop the lost filter and a session with many unanswered calls reports a p50 near zero.

The command a Bash call ran. preview is the tool's own argument (command, file_path, url, …), capped at 80 characters, and never message content:

curl -s "$API/v1/sessions/$SID/timeline" \
  | jq -r '.tools[] | select(.name=="Bash") | "\(.seq)\t\(.preview)"' | column -t -s $'\t'

For the untruncated command, read it off the response event. Pull the command key specifically rather than dumping all arguments — WebFetch arguments carry a prompt, and Agent/Task carry subagent instructions:

curl -s "$API/v1/sessions/$SID?limit=2000" | jq -r '
  .events[] | select(.phase=="response" and .inference.toolCalls != null)
  | .inference.toolCalls[] | select(.name=="Bash")
  | (try (.arguments | fromjson) catch {}) | select(.command) | .command'

LLM latency and tokens per call. view=summary keeps both — it drops message bodies, not measurements:

curl -s "$API/v1/sessions/$SID?limit=2000&view=summary" | jq -r '
  (["SEQ","MODEL","MS","TTFB","INPUT","CACHE_R","CACHE_W","OUTPUT"]|@tsv),
  (.events[] | select(.phase=="response" and .inference != null) | .inference as $i
   | [.seq, ($i.model//"-"), (.durationMs//"-"), (.ttfbMs//"-"),
      ($i.inputTokens//0), ($i.cacheReadTokens//0),
      ($i.cacheWriteTokens//0), ($i.outputTokens//0)]|@tsv)' | column -t

Do not add promptTokens to the cache fields: it is a legacy aggregate already equal to inputTokens + cacheReadTokens + cacheWriteTokens, so summing it with the split double-counts every cached token. reasoningTokens is likewise a subset of outputTokens. See Event schema.

Tool spans beside token counts. Join on tools[].seq, which is the response seq (see the seq table under /timeline). Pass the JSON through files — --argjson puts it in argv and a large session exceeds the limit with Argument list too long:

D=$(mktemp -d)
curl -s "$API/v1/sessions/$SID/timeline" -o "$D/tl.json"
curl -s "$API/v1/sessions/$SID?limit=2000&view=summary" -o "$D/ev.json"
jq -n --slurpfile tl "$D/tl.json" --slurpfile ev "$D/ev.json" -r '
  ([$tl[0].tools[] | {seq, name}] | group_by(.seq)
   | map({key:(.[0].seq|tostring), value:(map(.name)|join(","))}) | from_entries) as $tools
  | (["SEQ","MS","INPUT","CACHE_R","OUTPUT","TOOLS_ASKED"]|@tsv),
    ($ev[0].events[] | select(.phase=="response" and .inference != null) | .inference as $i
     | [.seq, (.durationMs//"-"), ($i.inputTokens//0), ($i.cacheReadTokens//0),
        ($i.outputTokens//0), ($tools[(.seq|tostring)] // "")]|@tsv)' | column -t
rm -rf "$D"

On a session over 2,000 events the events side covers only the newest 2,000, so spans older than that have no token row. Page with ?before= to the same depth when that matters.

Schema version

Each JSON response that carries events has one top-level schemaVersion field. The events in it do not carry one each. The value is now 1 (SchemaVersion in core/sessionapi/server.go). These responses carry it:

  • GET /v1/sessions/{id}, beside id and events.
  • GET /v1/sessions/{id}/events/{seq}. This response is the event object, so the field is one more key in that object.

The rule for the number:

  • It increases when a field of the response or of an event changes its meaning or is removed.
  • It does not increase when a field is added. A client ignores keys it does not know.
  • A response with no schemaVersion comes from a proxy older than the field. Read it as version 1.

/v1/events frames do not carry it. Each frame is one bare event, with no envelope to hold the field. The golden file core/pipeline/testdata/session-event.golden.json holds an event with every field set, and a test fails when the event wire form changes.

Event schema

Every event on /v1/sessions/{id} and /v1/events carries:

  • sessionId — the id of the session the store added the event to. The store sets it on every event, which includes outbound MCP and inference events. Their protocols have no session id of their own. ?session= on /v1/events filters on this field. A rekey writes the new id into every event the store holds for that session.
  • at, direction, phase — when, which side, what stage. phase is one of "request", "response", or "denied" (terminal denial from a pipeline plugin — typically a jwt-validation failure).
  • seq — the event's position in its session, counting from 1, and the cursor ?before= takes. Gaps are normal: FIFO eviction drops a prefix, and a pinned intent can sit far ahead of the retained tail. Unique within one incarnation of a session, not forever: trimming never reuses numbers, but whole-session eviction deletes the counter with the entry, so a session re-created under the same id restarts at 1. A cursor does not identify the incarnation, and the store cannot tell a re-created session from a trimmed one. A cursor from before that point that is above every event held gets the tail. One that is not, such as before=10 on a re-created session with 20 events, gets events below it (up to 1 to 9 here), and the client misses events 10 to 20. Within one incarnation, order by seq. Across pages that may span a re-creation, order by at, then seq: at is not unique. For example, a bridged tunnel's open row takes the time of its first request. A session archive moves that boundary out to disk: numbering continues across restarts for as long as the archive holds the session, and a rekey into an id the archive already holds is refused (the session keeps its old id), because the two numberings would collide. A proxy that predates paging sends no seq, which is how a client tells it cannot page there.
  • source — "imported:<agent>" on an event that POST /v1/import wrote. Absent on a live event. The proxy did not see an imported exchange, so such an event has no host and no capture.
  • a2a / mcp / inference — protocol parser payloads (one at most).
  • invocations — per-plugin invocation records for every plugin that ran on the pipeline pass, structured {inbound: [...], outbound: [...]}. Each entry carries plugin, action (see the vocabulary below), reason (machine-stable code), and optional plugin-specific context.
  • plugins — escape-hatch map for plugin-specific observability: keys are plugin names, values the raw JSON each plugin emitted. See plugin-reference.md for the producer contract.
  • identity, host, statusCode, error, durationMs — request-level context. A 502 here is not always the upstream's answer: when the exchange with the upstream fails — timeout, refusal, DNS, TLS, a body that breaks off mid-read — the proxy synthesizes the 502 itself, with error.kind saying which (upstream_timeout, upstream_refused, upstream_dns, upstream_tls, else upstream_error) and error.message naming the address but never the request URL, whose query string can carry an API key. In praxis mode, a 503 with error.kind: "gateway_unavailable" is the forward proxy's own answer when cortex-gateway is not ready (its startup probe has not passed) or refuses the dial. The forward proxy then records the request row and the 503 response row itself, because the gateway never saw the request. error.kind: "proxy_error" is the one that is the proxy's own: a buffered response over the listener's maxBodySize (1MB inbound, 10MB outbound), and on the streamed arms the 5-minute idle read cutoff and the per-frame cap. A streamed response that breaks off mid-body has no 502 to synthesize — the status is already on the wire. Both proxies abort the client's connection (h1 reset, h2 RST_STREAM) rather than end it cleanly, so the agent cannot read a cut stream as complete. On the forward proxy's three relay arms (SSE relay, SSE passthrough, unbuffered copy) the row keeps the sent status, with the failure in error (upstream_error for the upstream's break, proxy_error for the proxy's own cuts) and the sent status as error.code. Such rows count as errors in /v1/usage although their status is 200, and the Finisher sees OutcomeError (classifyBrokenStream resets pctx.StatusCode to zero while the row keeps the sent status). A skip_hosts stream aborts the same way and records nothing. Where the upstream did answer, error.code keeps the status it sent, while statusCode stays what the client got. A 499 with error.kind: "client_canceled" is the client hanging up first — since neither proxy times out a slow upstream, that is how a hung one usually ends. It counts as an error in /v1/usage but stays out of the 5xx series, and logs no WARN. On all of these the Finisher sees OutcomeError with Outcome.StatusCode 0: that zero marks the request as an error, so the event and the outcome disagree about the status on purpose. A 421 with error.kind: "misdirected_request" is a bridged request whose Host names another host or port than its tunnel's CONNECT target: the forward proxy refuses it before the pipeline runs and forwards nothing, and both rows name the CONNECT target as host, because policy keyed on the client's Host would judge a destination the bytes never reach. A 426 with error.kind: "upgrade_declined" is the forward proxy's own answer to a WebSocket upgrade on OpenAI's Responses API (chatgpt.com or api.openai.com) that it will not carry: every one under listener.responses_websockets: decline, and under the default, parse, one it cannot (not decrypted, or a plugin that rewrites response bodies or redirects requests). Nothing is forwarded, and a client such as Codex reads it as "use HTTPS" and retries at once over HTTPS. (Under parse, an HTTP/2 client is refused 400 by Go's HTTP/2 server before the handler runs.) The 426 is not counted as an error in /v1/usage, and the Finisher sees an allow with status 426. v0.9.4's decline_responses_websockets is still read when the new key is unset (true = decline, false = forward), with a startup warning; both set is refused. A carried socket's turn the client ends early (Codex's Esc) is a 200 with error.kind: "turn_interrupted", as an HTTPS stream the client leaves part way keeps its 200, and is not counted as an error either. Every other WebSocket upgrade — and a Responses one under forward — is forwarded (#1488): the 101 the origin answers with is spliced onto the client's connection (the upgrade is normalized to Connection: Upgrade / Upgrade: websocket, which net/http pins to HTTP/1.1). An upgrade is both headers, on both sides: a request needs Connection: upgrade as well as Upgrade: websocket or it is stripped and takes the ordinary path, and a 101 that switches to another protocol than the one requested is refused 502 before the hijack. Either check missing turns a plain request into an opaque pipe no plugin inspects. Once spliced, the frames after it are relayed uninspected, and the session records the request row plus a 101 response row paired to it by requestId, carrying bytesUp and bytesDown for the whole WebSocket session — the one response row besides a tunnel close that carries both — with durationMs covering the session and ttfbMs the handshake. Because that durationMs is a session lifetime rather than a request latency, the 101 row is excluded from /v1/usage exactly as a tunnel row is: folding it would drag the latency mean toward WebSocket lifetimes (one 10-minute session moved a host's mean from 500ms to 6.4s in testing), its frames are opaque so there is no model, token or cost to attribute, and counting it would add one Request whose latency is its whole lifetime. On the timeline the lifetime is the point, so the field stays. That exclusion is outbound only. The reverse proxy also records a 101, but at handshake time (ReverseProxy hands off the connection instead of copying a body, so a deferred record would never fire), so its durationMs is the handshake latency — an ordinary request figure. An inbound WebSocket handshake is therefore still counted as a Request. A relay that ended in an error carries error.kind: "proxy_error" on the 101 row, so a session that broke mid-stream is distinguishable from one that closed cleanly; an ordinary close is not marked. A 403 with error.kind: "destination_private" is the egress guard's refusal (listener.egress_guard): the destination resolved into loopback, link-local, private or this host's own address space and no permit covered it. Also the proxy's own answer rather than the upstream's, and also not counted as an error — the guard did what it was configured to. The Finisher sees an allow with status 403, as for the 426. A 403 destination_denied is the egress allow list's refusal (listener.egress_allow_hosts, or MOCA_EGRESS_ALLOW): the destination was not on the deny-by-default list, and the proxy refused it by name — header X-Moca-Egress-Error, text/plain body destination_denied: <host>\n — before the pipeline, before DNS and before any dial. Off-list CONNECT targets, absolute-form hosts and the target a plugin's redirect moved a request to all land this way, as a phase: "denied" row carrying an egress-allowlist invocation whose details.host names the host; the row's own host is the full authority, as every outbound row's is. The two 403s compose: the allow list judges the name before DNS, the guard the address at the dial, so an allow-list entry is not a permit for the guard. A request whose body could not be buffered never reached the pipeline, so its request row carries no parse and no Finisher runs: over the forward proxy's maxRequestBodySize (32 MiB) it is a 413 proxy_error with an empty error.code; a client that hung up mid-upload gets a 499 client_canceled, which here does log a WARN (request body unreadable); anything else unreadable is a 400 request_unreadable. An opaque CONNECT that could not be dialed reports the same one layer down, as tunnelReason: "dial-failed" with error.kind: "dial_failed".
  • ttfbMs — on a delivered response row, the wall time from request entry to the upstream's response headers arriving. durationMs − ttfbMs is then how long the body took — for a streamed completion, the stream time. The pair separates a slow-to-answer origin from one that answered and then trickled, which durationMs alone cannot (#1251). All three listeners set pctx.ResponseHeadersAt at their own headers-arrival moment, and every response-event builder derives the figure with pipeline.DurationBetween; a new listener or builder must do the same. The row is recorded when the listener is finished with the body — after the read on a buffered path, after the relay on a streamed or unbuffered one — so the difference really is the body's time. The one exception is the envoy-sidecar listener with a pipeline no plugin of which reads bodies: the row is recorded at the headers while Envoy relays the body unseen, and ttfb is left absent there rather than reported as a figure equal to the whole duration. Absent when the exchange failed before headers (the 502 cases above), on request rows, and on tunnel rows — an opaque tunnel has no headers to time. agentop's detail pane renders the split as a timing: line.
  • requestedHost — present only when a plugin redirected the request: the host the client asked for. host is where the request actually went, and usage, the cost ledger and pricing all follow host.
  • inference.requestedModel — present only when a plugin changed the model: the model the client asked for. inference.model is the model the request was sent for, which settlement prices.
  • inference.thinkingType, inference.thinkingDisplay, inference.effort — what the request asked for: thinking.type and thinking.display (for example adaptive and summarized), and the effort level from the field the dialect uses (output_config.effort, reasoning_effort or reasoning.effort). Absent when the request did not state them.
  • inference.anthropicBeta — the request's anthropic-beta header, every value joined with a comma.
  • inference.historyThinking, inference.responseThinking — counts of the thinking blocks the client sent back and the model returned: blocks, redacted, textBytes, signatureBytes, redactedBytes. Absent when there were none. A history block with signatureBytes and no textBytes came back as an encrypted signature only.
  • inference.servedModel — on a response row, present only when the upstream named a model other than inference.model: the x-litellm-model-name response header (a LiteLLM gateway's deployment, for example bedrock/us.anthropic.claude-opus-4-6-v1 for claude-opus-4-6), else the response body's own model field (a provider's dated version). Absent when the upstream answered under the requested name, as Ollama does. For display only: pricing still follows inference.model. agentop's detail pane shows it on a served: line.
  • inference.messages — the conversation the request sent, in order. Each item has a role and a content. An Anthropic request's top-level system prompt is the first item, with role system. content keeps only the text blocks. contentBytes is the wire size of the content value as the client sent it, so a message with no text still shows its size. It is a byte count of the raw JSON, not a token count.
  • inference.messages[].toolCallNames, toolUseIds, toolUseId — the tool blocks of a message. toolCallNames names the tools that an assistant message called, joined by , in call order. toolUseIds gives the ids of the message's tool calls or tool results, joined by , in block order. They key into inference.historyToolCalls and inference.toolResults. Only a chat-completions role: "tool" message has a toolUseId: the id of the call that the message answers.
  • inference.historyToolCalls — the tool calls that earlier assistant turns made, as the client sent them back in this request: id, name and arguments. inference.toolCalls is a different list: the calls that the model asks for in this response. No compiled plugin reads historyToolCalls.
  • inference.temperature, inference.maxTokens, inference.topP, inference.stream — the request's sampling settings and stream flag, as sent. maxTokens is max_tokens, or max_output_tokens on the Responses API. Each is absent when the request did not state it. stream is also absent when it is false.
  • inference.tools, inference.toolChoice — the tools that the request declared and its tool_choice value. Each tool has a name, a description and parameters, the JSON schema as the client sent it.
  • inference.streamedResponse — true when the response came as an SSE stream. inference.stream is what the request asked for. The two can differ: a gateway can answer a non-streaming request with a stream. Pricing reads streamedResponse to know if a token count is final.
  • inference.completion, inference.finishReason, inference.toolCalls — on a response row: the model's text, the provider's stop reason, and the tool calls that the model asks for. Each tool call has an id, a name and arguments, the raw JSON text from the model.
  • inference.inputTokens, inference.cacheReadTokens, inference.cacheWriteTokens, inference.outputTokens, inference.reasoningTokens — on a response row: the token counts that the provider reported, by kind. inputTokens are the uncached prompt tokens. reasoningTokens are a part of outputTokens.
  • inference.presentKinds — a bitmask of the token kinds that the provider reported: input 1, cache read 2, cache write 4, output 8, reasoning 16. A zero count with its bit set means that the provider reported zero. A zero count without its bit means that the provider did not report that kind.
  • inference.promptTokens, inference.completionTokens, inference.totalTokens — older totals that the parser calculates from the split counts. promptTokens is input plus cache read plus cache write. completionTokens is output. totalTokens is the provider's own total when it sent one, else prompt plus output.
  • inference.messageCount, inference.toolCount, inference.toolCallCount — set only on a view=summary copy, which removes messages, tools and toolCalls: how many items each list had. Zero means "not stated". When the list is present, use its length. toolCount is the manifest the request offered; toolCallCount is how many calls the response made of it.
  • inference.isAction, mcp.isAction, a2a.isAction — the parser's classification. It is true on every inference row. It is true on the MCP methods tools/call, prompts/get and resources/read, and on the A2A methods message/send and message/stream. It is absent on protocol mechanics. See Classifying requests.
  • mcp.method, mcp.rpcId, mcp.params — the JSON-RPC method, id and params of an MCP request. A notification has no rpcId. The two methods that follow occur only on a configured MCP path. A body-less DELETE with an Mcp-Session-Id header has the method $transport/terminate. A body-less GET has the method $transport/stream.
  • mcp.result, mcp.error — on a response row: the JSON-RPC result, or the error object with code, message and data.
  • a2a.method, a2a.rpcId — the JSON-RPC method and id of an A2A request.
  • a2a.sessionId, a2a.taskId, a2a.messageId, a2a.role, a2a.parts — from the request's params. sessionId is contextId, else the older sessionId, else params.message.contextId. taskId is params.message.taskId, else params.id for a tasks/* method with a task id param, else the older params.taskId. When the request has none, the response sets sessionId and taskId. A Task result gives its id. messageId, role and parts come from params.message. Each part has a kind and a content: the text of a text part, the data or uri of a file part, or the JSON text of a data part.
  • a2a.finalStatus, a2a.artifact, a2a.errorMessage — on a response row: the last task state that the response carried (for example completed or failed) and the artifact text. A stream that ends with no final status event gives its last state, for example working. When the state is failed, errorMessage is the first text part of the status message. In a stream, the parser joins the text of each artifact event. The joined text has a maximum of 64 KiB. A Task event in a stream replaces the joined artifact-update text with the last text part of the Task's artifacts.
  • bytesUp, bytesDown — body bytes, one direction per row: a request row carries bytesUp, the body as forwarded (so a rewrite is reflected); a response row carries bytesDown, the body as it came back from the destination. Headers are not counted. A tunnel close and a forwarded WebSocket's 101 response row are the rows carrying both. Zero means the listener counted nothing, not that the body was empty — every listener buffers bodies only when a plugin asks, so an unbuffered request reports zero. A response relayed straight through is counted, not zero: both proxies record the row after they finish relaying it (#1251), so the bytes that crossed their own process are on the row. The one arm that still reports zero is the envoy-sidecar listener with a body-free pipeline — it asked Envoy not to send it the bytes, so zero there means "not asked to see", not "not counted" (core/listener/parity's TestDivergence_InboundResponseBodyCountWhenNoPluginReadsIt pins it). A response row's bytesDown is the body as it came back, not as delivered, because extproc records the row before it emits a response mutator's replacement. Everywhere else the three listeners count the same figure for the same response; core/listener/internal/bodycount and the parity fixtures hold that line.
  • tunnel, tunnelReason — an opaque CONNECT (or transparent-redirect) tunnel records two rows sharing a requestId: the open (phase: "request", tunnelReason saying why the bytes stayed opaque) and the close (phase: "response"), carrying the CONNECT's own status, the duration, and the bytes each way (up = client to destination; opaque bytes have no body/header split). The close's status is 200, or 502 with the dial error when the destination could not be reached and no TLS bridge took the connection (tunnelReason: "dial-failed"). Where the bridge is enabled for the port the CONNECT is answered 200 first, because a redirect can still apply, and a bridge that then declines closes with that 200 and the dial error. It is not the destination's status: that travels inside the client's end-to-end TLS. A bridged tunnel's open is recorded with its first decrypted request — in that request's session, directly before it, stamped with its time — and records no close, because the request carries its own response; a bridged tunnel that recorded no request gets its open and a close when it ends. Tunnel rows are kept out of /v1/usage: a tunnel's lifetime is not a request latency. tunnelReason: "websocket" is the one that is not opaque: a Responses API WebSocket the forward proxy carries (listener.responses_websockets). Its open is the handshake GET, its close is status 101 with the whole socket's duration and bytes, and every turn on it records its own ordinary POST request and response rows between the two, parsed and priced like an HTTPS turn. A turn runs on the pipeline it began on, so a hot reload never splits one. tunnelReason: "dest-private" is the egress guard's refusal: the close row carries 403 and error.kind: "destination_private", and no tunnel was ever opened to the destination — the same refusal a plain request gets, one layer down. Under tls_bridge.fail_closed three more refusals close a tunnel row: origin-unverified with 502 and error.kind: "upstream_unverified" (also for a probe timeout; error.message says which), sni-mismatch with 421 and "misdirected_request", and refused-non-tls with 200 and "not_tls".
  • dialAddr — present on a tunnel's open row when the egress guard is on: the address the guard checked and the proxy dialed, "ip:port". Together with host it is the audit trail against DNS rebinding — "asked for the name, dialed this address" — because under the guard the proxy never dials an address it did not check. Absent when the guard is off and on rows that dialed nothing.
  • httpMethod, httpPath — the HTTP verb and query-stripped, percent-decoded path, so a request no parser recognized is still identifiable. On an opaque tunnel httpMethod is CONNECT and httpPath is absent. Note a secret in a path segment (a bot token, a webhook path) does survive on this unauthenticated surface — worth knowing before exporting events off-box.
  • project — the git repo root of the agent process's cwd. The agent process is the one that proc names, else the client process. A linked worktree gives its main repo. A cwd with no repo gives the cwd itself. The home dir is shown as ~, so a terminal agent started in home gives ~. A cwd of / gives "". At most 256 runes: a longer label keeps its tail, cut to start at a /. The proxy reads it once per connection, so a process that changes its cwd keeps the old label until it opens a new connection. Absent on every listener that has no PID (transparent, the VM control path, extproc, reverseproxy, transparentproxy) and when session.process_attribution is off. In praxis mode the request and response rows that cortex-gateway sends through POST /v1/ingest have no project: only the forward proxy's own rows have it. /v1/usage?group=project totals cost by this label; an event with no project is counted under unknown. See pricing.md.
  • subagent — present on rows from a Claude Code subagent or agent-team teammate: the X-Claude-Code-Agent-Id the request carried. For a subagent it is the same id that names its files under ~/.claude/projects/<dir>/<session>/subagents/agent-<id>.*. Absent on the main conversation's rows and on every other client's, and absent too when the value was not usable (a control character, over 128 bytes), which is refused rather than cleaned up. Context.Subagent resolves it and ResolveClient pins it, so no plugin can re-file a row. The row is still filed in its parent conversation's session, so the header must not be added to session.id_headers. This key names an agent; it does not say the row is a subagent's. inference.agentRole says that, and on a teammate's row it is main while subagent is set. It is present also on rows from a Bob child task (a subagent or a subtask): the child's own X-Task-Id, when the request also sends a different, usable X-Parent-Task-Id. The Claude Code header wins when a request sends both.
  • subagentKind — Bob only: subtask when the request's tool list has end_subtask, else subagent. It is subagent also when no inference parser ran. Absent on Claude Code rows and on every row without a Bob subagent.
  • parentSubagent — the agent that started the one subagent names, from X-Claude-Code-Parent-Agent-Id, under the same rules. Claude Code sends it only when the spawner was itself an agent, so on a row that names a subagent an absent parentSubagent means the conversation started it. The two keys together give a row's place in the session's tree of agents.

Invocation action vocabulary

Every plugin emits one of these 5 action values per invocation, so operators can scan a timeline without memorizing plugin-specific verbs:

action Meaning Example
allow Gate plugin permitted the request jwt-validation on valid token
deny Gate plugin rejected the request; pipeline stops jwt-validation on bad token, token-exchange on IdP failure
skip Plugin ran but didn't act on this message jwt-validation on a bypass path; parser whose body didn't match
modify Plugin mutated the message token-exchange replaced the Authorization header
observe Plugin attached diagnostic data without changing flow a2a-parser, mcp-parser, inference-parser when they match

Use reason to discriminate within an action — skip/path_bypass vs skip/no_matching_route tell different stories at the detail-pane level but both scan as "skip" in the at-a-glance timeline.

agentop's ACTION column adds two values that are rendering, not plugin output: — when nothing acted, and tunnel for an opaque CONNECT. Neither is ever emitted by a plugin, and neither is a verdict on the request.

Producer-side contract: the authoritative definition of the 5-value vocabulary, the Invocation struct fields, and which diagnostic fields each plugin type populates lives in plugin-reference.md. This table is the consumer-side summary.

Gotchas

  • Denied requests (401 / 503) land as phase: "denied" events when at least one pipeline plugin appended an Invocation before rejecting. If you're debugging an unauthorized-access pattern, the default-session bucket (GET /v1/sessions/default) is where denial events aggregate.

  • Which listener records a row. The listeners do not record the same rows:

    • The forward proxy and the reverse proxy record a request row and a response row for every request that the pipeline sees. The forward proxy does not record an agent's polls of its own service.
    • The envoy-sidecar listener (ext_proc) records a row only when the row has content: a parser result (a2a, mcp or inference), an invocation, or a plugin payload. A request that no plugin marked leaves no row.
    • When a plugin rejects a response, only the forward proxy records a phase: "denied" row. ext_proc and the reverse proxy record no row for that deny. The reverse proxy's missing row is a known gap, a sibling of #1045 (see errorHandler in core/listener/reverseproxy/server.go).

    core/listener/parity pins each difference (TestDivergence_*RowWhenNothingToRecord, TestDivergence_OutboundResponseDeny, TestParity_InboundResponseDenyRecordsNoRow).

  • Disabling: set session.enabled: false to turn off the store (and implicitly the API). The session archive is separate — session.archive.enabled: false stops it without touching the in-memory store, and turning the store off with the archive explicitly on is refused at load. Setting listener.session_api_addr: "" alone is not supported as a selective disable — the preset refills it; if you need store-on-API-off, raise an issue.

  • Memory: the store keeps every event a session produces by default — session.max_events is unset and session.ttl defaults to never. What bounds memory by default is session.max_sessions (100, oldest-used evicted first). See laptop-service.md for the retention story and the archive's bounds.