docs/trace-panel-spec.md

Trace panel — implementation spec

Status: built (2026-07-29) · Branch: worktree-session-sharing · PR: huggingface/agent-manager#8

A handoff document. Everything here was verified against this codebase and the live Hub on 2026-07-27/28. Read docs/session-sharing.md for the wider design; this file is only the panel, and is written to be self-contained.

§11 records what actually shipped, including four places where the implementation departed from this spec on purpose. Sections 1–10 are the brief as written; where they disagree with §11, §11 is the code.

1. What to build

A read-only panel inside Agent Manager that renders one agent session as a readable conversation — turns, tool calls, thinking blocks, token counts — close in spirit to the Hugging Face agent trace viewer (Data Studio's session modal).

Two sources, same component:

1. A local session of your own — the immediate value, and the only way to exercise all five readers against real data. Ship this first.
2. An accepted incoming trace — a bundle downloaded from a Hub dataset, landing in DATA_DIR/traces/<envelope-id>/. The receive half is not built yet.

The panel also hosts Fork and Handoff buttons (see §8 of the design doc), but those are not required for a first version.

2. Hard constraints

These are not style preferences; each one has already caused an incident in this repo.

• No LLM calls, anywhere. The whole feature is deterministic parsing. The operator has explicitly ruled out inline model calls in Agent Manager.
• Nothing heavy on the event loop. A single session here is 6.15 MB. This app has wedged on synchronous work before — see server/src/watchdog.js, a worker thread that exists solely to report main-thread stalls, with breadcrumbs (mark/tracked) around the known-heavy paths. Parse off the request path, or in a child process as server/src/share.js does.
• Virtualize the message list from the start. The Hub's own session modal fails to render our 2.13 MB single-row dataset. Do not assume a session fits in the DOM.
• Do not extend the Overview's memoized parse. traces.js parses every session on a poll and memoizes by mtime; making those parsers also retain every turn would balloon memory across all sessions. Add a separate on-demand function for one session — put it in traces.js so the line-shape knowledge stays in one file and drift is visible in review, but keep it out of buildTraces()/traceDigests().
• The filesystem is a FUSE bucket and it lies. Stale directory listings (a file written seconds earlier reading as absent), exec bits stripped from node_modules/.bin and git hooks, and paths occasionally materialised as directories (.git/hooks/pre-commit, ~/.gemini/projects.json, and historically opencode.json — see the guard at runner.js:415). Retry before concluding a file is missing.

3. Where it plugs in — already done

Piece	State
trace in the CLI catalog	✅ server/src/config.js:69 — bin: null, run: null, colour #7c8cf8
Treated as a passive panel, never launched	✅ server/src/runner.js:135 returns 'idle' for files and trace
Pane dispatch	⬜ web/src/App.tsx:423 — currently s.cli === 'files' ? <FilesPane/> : <TerminalPane/>; add a branch
Component	⬜ new web/src/components/TracePane.tsx
Reader endpoint	⬜ new, see §5

Model your component on web/src/components/FilesPane.tsx (181 lines) — the existing passive, non-process pane. It shows the house style: plain fetch through web/src/api.ts, no state library, CSS appended to web/src/styles.css with flat .kebab-case class names. There is no modal/dialog framework; .welcome-backdrop + .welcome-card in styles.css is the established overlay pattern (ShareDialog.tsx uses it).

4. Why the digest is NOT enough

The operator initially expected the existing digest would do. It will not, and here is the precise reason so nobody re-litigates it:

traces.js emptyDigest() (line 48) returns lastPromptText, lastAssistantText, sinceTurns, sinceToolCalls, sinceTools (tool names and counts only), sinceFiles, sinceTokens, running, and turnsLog. And turnsLog:

• is reset at the start of every request — traces.js:60, commented "arrows only walk the current request's turns";
• is capped at MAX_TURNS_LOG (24, traces.js:56);
• holds only { answer, answerMd, ts } — assistant text, with no paired user prompt.

So the digest is a "what did this agent just do" summary that powers the Overview card. It carries no conversation history, no tool arguments, no tool results and no thinking blocks — exactly what a viewer needs. A full parse is required.

5. The reader

Suggested shape — one function, one session, on demand:

// server/src/traces.js  (NOT part of buildTraces/traceDigests)
export async function readTrace(session, { offset = 0, limit = 200 } = {}) → {
  harness, sessionId, model, cwd, firstTs, lastTs, total,
  turns: [ Turn, … ]   // ordered oldest→newest, sliced by offset/limit
}

type Turn = {
  role: 'user' | 'assistant' | 'system' | 'tool';
  text: string;             // rendered as markdown for assistant/user
  thinking?: string;        // collapsed by default
  ts?: number;              // epoch ms
  model?: string;
  usage?: { in: number; out: number; cacheRead: number };
  toolCalls?: { id: string; name: string; args: unknown }[];
  toolResult?: { id: string; content: string; isError?: boolean };
};

Paginate at the API rather than sending 6 MB. Endpoint suggestion: GET /api/trace/:sessionId?offset=&limit= for a live session, and GET /api/trace/bundle/:envelopeId?offset=&limit= for an accepted one.

Locating the file is already solved — reuse findTrace(session, allSessions) exported from server/src/share.js. It returns { src, sessionId? }, handles all five harnesses, prefers the per-session pin where one exists (sessionUuid, codexSessionId, opencodeSessionId), falls back to attribution by recorded working directory, and refuses to guess when two sessions of the same harness share a folder. It also skips codex's guardian/subagent rollouts. Do not reimplement this.

6. The five formats — verified line shapes

scripts/share-session.mjs already contains working readers for all five, written and tested against real and faithful-synthetic data. Read it before writing anything: the knowledge below is what it encodes, and reusing it avoids a second source of truth.

Claude Code — $CLAUDE_CONFIG_DIR/projects/<cwd-slug>/<uuid>.jsonl

One JSON object per line; the filename is the session id.

• {type:'user', timestamp, cwd, gitBranch, message:{role:'user', content: string | [{type:'text',text}]}}
• {type:'assistant', timestamp, uuid, message:{id, model, role:'assistant', content:[{type:'text',text} | {type:'thinking',thinking} | {type:'tool_use',id,name,input}], usage:{input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens}}}
• Tool results come back as type:'user' lines carrying toolUseResult and a content:[{type:'tool_result',tool_use_id,content}].
• Dedupe assistant lines by message.id — streaming writes the same message id more than once, and counting naively double-counts turns and tokens.
• Skip isMeta and sourceToolUseID user lines; they are not prompts.
• file-history-snapshot / file-history-delta lines embed whole file contents. The share pipeline drops them outright. A viewer should ignore them too.

Codex — $CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl

Everything is wrapped in payload.

• {type:'session_meta', payload:{cwd, timestamp, thread_source?, source?}} — if thread_source === 'subagent' or source.subagent, this is an internal guardian rollout, not the user's conversation. Refuse it.
• {type:'response_item', payload:{type:'message', role, content:[{text}]}} — codex wraps environment/instruction blobs as role:'user' items whose text starts with <; skip those or your prompt count is wrong.
• {type:'response_item', payload:{type:'function_call'|'custom_tool_call'|'local_shell_call'|'web_search_call', name, arguments}} — apply_patch carries touched paths in its patch header: /\*\*\* (?:Update|Add|Delete) File: ([^\n"]+)/.
• {type:'event_msg', payload:{type:'token_count', info:{total_token_usage:{input_tokens, cached_input_tokens, output_tokens, total_tokens}}}} — cumulative per run, so keep the last one, and subtract cached_input_tokens from input_tokens to match Claude's "fresh input" convention.
• {type:'event_msg', payload:{type:'task_complete', last_agent_message}} — the authoritative final answer for a task.

OpenClaw — $OPENCLAW_HOME/.openclaw/agents/<agent>/sessions/<uuid>.jsonl

Already close to the Hub's STS shape: {type:'message', timestamp, message:{role, content: string | [{type,text|name|input}], usage:{input,output,cacheRead}}}. Content blocks whose type matches /tool/i are tool calls.

opencode — SQLite, ${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db

A session is a query, not a file.

• session(id, directory, title, time_created, time_updated, tokens_input, tokens_output, tokens_cache_read)
• message(id, session_id, time_created, data) — data is JSON with role
• part(id, message_id, session_id, time_created, data) — data is JSON with type: 'text' | 'tool' | 'step-finish', plus text, tool, state.input, state.output
• Never copy or ship this database: account.access_token, account.refresh_token and a credential table live in it. Select one conversation.
• Live data is on local disk via a symlink with a durable copy synced to the bucket (commit 1dfb753), precisely because a synchronous read of a FUSE-backed sqlite froze the whole server. Open read-only, and never on a hot path.

Hermes — SQLite, ~/.hermes/state.db

• sessions(id, cwd, title, started_at, input_tokens, output_tokens, cache_read_tokens)
• messages(id, session_id, role, content, timestamp, tool_name, token_count, active) — flat content; a row with tool_name set is a tool interaction. timestamp is seconds (multiply by 1000). Same FUSE/symlink note as opencode.
• Hermes has no per-session pin in Agent Manager, so it is attributed by cwd.
• Alternative worth knowing: hermes sessions export --format trace emits Claude-Code JSONL specifically for the HF viewer, and --redact exists. We chose direct SQLite reads for one code path with opencode; either is defensible.

7. What the Hub's viewer does, for reference

Verified live. A dataset containing raw session .jsonl files gets auto-tagged format:agent-traces, and the Hub aggregates one file into one row, deriving columns: harness, session_id, prompt, messages, tools, metadata, sent_at, num_user_messages, num_tool_calls, trace, file_path.

Clicking the row opens a Session modal showing: user/assistant turns with role badges and timestamps, the model name as a chip, per-turn token counts (491↓ 520↑ (1,408 cached)), a collapsible Thinking block with a one-line preview, collapsed N tool call (bash) summaries, rendered markdown including tables, and a Collapsed/Expanded toggle.

It is embeddable and deep-linkable — …/embed/viewer/default/train?row=0 renders the modal inside an iframe. We deliberately do not use it: it cannot render a gated repo (the private path), and a brand-new dataset took ~50 minutes to become viewable. Both are recorded in the design doc. It remains the visual reference, and it is what a public share gets for free in a browser.

Live examples to look at: thomwolf/am-session-sharing-design (public, renders), thomwolf/am-session-sharing-design-gated (gated, shows the gate).

8. Suggested v1 scope

Ordered by value. The operator asked for full fidelity with everything collapsed by default.

1. Ordered turns with role, timestamp, markdown-rendered text
2. Thinking blocks — collapsed, one-line preview
3. Tool calls — collapsed, showing name and a short argument summary; expand for full args
4. Tool results — collapsed, truncated with an expand
5. Per-turn token counts and the model chip
6. Search / filter within the session
7. Header: harness, model, window, totals — reuse the stats the share manifest already computes

Skip: statistics panels, prev/next row navigation, editing anything. The panel is read-only.

9. Traps that cost me time

• const does not hoist. Twice I put helpers or accumulators after the loop that used them and got a temporal-dead-zone crash on the first line parsed. Declare state above.
• Verify your success checks. I once printed "ok" from a grep that matched a comment, and another time from head's exit status rather than the compiler's. Both hid real failures.
• tsc/vite cannot execute from node_modules/.bin on the FUSE mount (exec bit stripped). Run them as node node_modules/typescript/bin/tsc …, or install into /tmp.
• web/ and server/ have no node_modules in the repo — deps live at /app/*/node_modules in the container. Symlink them for local runs.
• Test the server on a spare port with PORT=… DATA_DIR=/tmp/… node src/index.js, and PUBLIC_DIR=<worktree>/web/dist to serve a locally built UI. Never pkill -f a pattern that could match /app/server/src/index.js — that is the live Space at PID 1.
• The app has no authentication at all; it only serves a usable backend while the Space is private (visibility.js, index.js:142). A fresh DATA_DIR starts with the Welcome overlay, which intercepts clicks — POST /api/welcome/seen to dismiss it in tests.

10. Open questions for whoever builds this

1. Where does "open the trace" live? A button on the session row next to Share, an item in the pane header, or an entry in the Overview card? A trace session needs creating and pointing at a source, and the session record has no field for that yet — suggest traceSource: { kind: 'session' | 'bundle', ref: string }.
2. Does one panel follow a live session as it grows, or is it a frozen snapshot? Following means re-polling and appending; frozen is simpler and matches "trace".
3. How much tool output to retain in memory once expanded — a single Bash result here can be hundreds of KB.

11. As built (2026-07-29)

Landed. Files: server/src/traces.js (reader appended at the bottom), server/src/index.js (two routes), web/src/components/TracePane.tsx (new), web/src/api.ts, web/src/types.ts, web/src/styles.css, plus the entry point in App.tsx / Sidebar.tsx.

Four deliberate departures from §5–§8

1. Blocks, not a Turn with a single toolResult. §5's shape can't represent the transcripts. Claude emits tool results on a separate type:'user' line, and parallel calls finish out of order, so one toolResult slot per turn silently drops all but one. readTrace() returns { role, kind?, ts?, model?, usage?, blocks: [...] } with a makeStitcher() that files each result next to its own call by tool_use_id — which is also what makes the collapsed 3 tool calls (Bash, Read) row possible at all.
2. kind: 'final' on the last assistant turn before each prompt. Corrected 2026-07-29: the original claim here — that codex's task_complete is an authoritative answer separate from the response_item text, and that non-final text should render dimmed — was wrong on both counts. task_complete.last_agent_message is byte-identical to the preceding assistant message in every task of the rollout checked, so treating it as separate rendered all 8 answers twice; and the Hub emphasises the final turn with an accent rule rather than dimming the others. markFinalTurns() now derives the final turn for every harness in one reverse pass, and task_complete only marks it.
3. Codex gets a stitcher too. Codex writes a call and its output as two separate top-level items, so before this every call and every result was its own row and nothing ever folded. Caught in testing: 0 paired, 1 standalone → 1 paired, 0 standalone.
4. Environment blobs become role:'system', not dropped. Claude's <system-reminder>, codex's <-prefixed user items, and codex's whole role:'developer' stream are context, not prompts. Dimmed and collapsed behind their own tag name rather than hidden, because removing them makes the conversation read wrong — but one of them here is 27 KB, so expanded they bury the session before it starts. The Hub instead labels these "User" and expands them, or omits them entirely; this is a deliberate divergence.

The three open questions in §10, as answered

1. Entry point: a Trace button on the session row, next to Share. traceSource was kept verbatim, and is only needed for a pane pointed at something else — a plain agent session reads its own transcript, so GET /api/trace/<agent-session-id> works with no new record. Panes are reused per source rather than piling up.
2. Frozen per read, cheap to follow: the memo key includes mtimeMs+size, so re-requesting after the file grows reparses and total climbs. No incremental machinery.
3. Capped at parse time, 20 000 chars per block, with more reported so the UI says "+412 KB not retained" instead of pretending.

trace is a passive pane, like files

PASSIVE_CLIS = ['files', 'trace'] in server/src/config.js, mirrored as isPassive() in web/src/types.ts. It gates: the agent list in /api/meta, buildTraces(), the input route (a trace pane refuses keystrokes), the Overview cards, archiving, the quickstart picker, the group cart, and a group's agent count. Adding a third passive pane type now means one array.

Verified against real data

• 9.46 MB live Claude transcript (this session): 634 ms full parse, worst event-loop block 2 ms, 82 MB RSS; second call 3 ms off the memo. Counts reconciled against an independent pass over the raw file — 259 text blocks = 228 assistant + 28 prompts + 3 reminders, exactly; 466/467 tool results filed next to their call.
• Real opencode db (3.4 MB): 79 turns, 57 thinking blocks, 98/101 results paired. The two guesses flagged in the drop were both confirmed against the live schema (state.input / state.output, reasoning.text) — and session.model is a JSON blob, not a string.
• A real STS bundle produced by scripts/share-session.mjs and read back through readTraceBundle() — which is how an accepted trace will arrive.
• codex / openclaw / hermes fixtures built from the shapes in parseCodex and share-session.mjs's converters. Hermes's seconds-not-milliseconds timestamps render as correct dates; codex guardian rollouts are refused with trace-not-user-conversation.
• Headless Chromium over CDP (no playwright in this image) against the built bundle, for each harness: pane mounts, header reads Claude Code | claude-opus-5 | 555 turns | 1,840,279↓ 398,440↑ (138,147,880 cached), 14 rows in the DOM for 555 turns, folds open, scrolling to 70 % pages in with no placeholders left, search reports what it searched, zero JS exceptions.
• Refusals render as sentences, not failures: an unsupported CLI, a missing transcript, a guardian rollout, a missing bundle. Bad bundle refs are rejected at write and read.

Two bugs this testing caught that a curl check would not

• A bundle manifest stores harness as an object ({id,name,version}) while an STS session line stores a string. Both reach harnessLabel, which the header renders directly — React throws on an object child. Hence label().
• Claude sessions had no token total in the header: usage is per-message there, so the session sum has to be accumulated (usageSum), while codex and the db-backed harnesses keep their own authoritative total.

Not done

• Fork / Handoff are header slots only (design doc §8).
• Search is client-side over fetched turns and says so; server-side wants a ?q= returning matching offsets — a small addition to pageOf().
• No compaction block is ever produced; Claude's type:'summary' / system lines and attachment lines are ignored. The block type exists for when that's wired up.
• The incoming half (accept/decline on an inbox PR) is out of scope as of 2026-07-29 — see the scope note at the top of docs/session-sharing.md. A bundle source is populated by pasting a dataset URL into the sidebar's Trace button, which is the intended flow.

12. Comparison against the Hub's own viewer (2026-07-29)

Done on a real private share, thomwolf/codex-session-019fac81, by rendering the Hub's Trace tab in headless Chromium and scraping it in document order, then taking an independent census of the 393-line file so the arbiter was the data rather than either renderer. Reproduce with Network.setExtraHTTPHeaders carrying a bearer token — the Hub serves the blob page and its viewer with one.

Findings are in §11's list and in commit 08714a5. What is worth keeping here:

Both agree on totals, not on attribution. The Hub's first assistant row claims 16 tool calls (exec_command, apply_patch, write_stdin) and then exactly 1 tool call for each of the next five turns. The file has 2, 2, 1, 3, 6, 7 between successive assistant texts. Both sum to 21, so nothing is lost — but the per-turn attribution differs, and the file backs ours. Its first row's token figure (354↑, 31,488 cached) is likewise the last model call of that task shown on the task's first row.

The Hub has no System or Developer row type. Measured: System: 0, Developer: 0 across the rendered window. It shows <recommended_plugins> as a User turn, expanded as markdown, and omits codex's seven role:'developer' messages entirely.

Two streams, and the same content in both. This is the single most important thing about the codex format and it is documented at normalizeCodex in traces.js: response_item is what went to and from the model, event_msg is what the TUI showed. agent_message duplicates the assistant response_items exactly; agent_reasoning arrives first and repeats what a later reasoning item's summary entries contain, so dedupe per ENTRY, not per joined string; and web searches exist ONLY as web_search_end.

Encrypted reasoning is normal. 49 of 56 reasoning items carried only encrypted_content. Say so in the UI; do not leave the impression the model didn't think.