Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(grok): describe updates.jsonl from measurement, in all four places
Xavi Guardia5e9665f6cefe
diff --git a/docs/grok-agent.md b/docs/grok-agent.mdindex 405ea5186..573cda909 100644--- a/docs/grok-agent.md+++ b/docs/grok-agent.md@@ -215,6 +215,16 @@ $GROK_HOME/ # $GROK_HOME, else ~/.grokhooks/*.json # all merged; nodeterm-status.json is ourssessions/<url-encoded cwd>/<session-id>/summary.json updates.jsonl chat_history.jsonl signals.json plan.json subagents/++Which of those is the conversation is the question this integration got wrong for months, so it is+worth stating exactly (measured on 1.0.13 across 29 local sessions, 2026-09-02):++| File | What it is |+|---|---|+| `chat_history.jsonl` | **the conversation**, one settled message per line — `system`, `user`, `assistant`, `tool_result`, `backend_tool_call`, `reasoning`. Read by context links, the ⌘M panel and transfer. |+| `updates.jsonl` | the ACP event **stream** (`session/update`). It is not empty of conversation — `agent_message_chunk`, `user_message_chunk`, `agent_thought_chunk` are all there — but they arrive as CHUNKS interleaved with `tool_call`/`tool_call_update`, `hook_execution`, `plan`, compaction and subagent events. Reading a message out of it means reassembling one. **Grok's hook payloads advertise THIS path as the transcript**, which is the whole trap: following the advertisement opens a real file, parses to nothing, and yields an empty transcript with no error. |+| `signals.json` | the meter's three numbers, plus 63 unrelated metrics. |+| `summary.json` | the session title and model. |```Path rules, all unit-tested in `grok-paths.test.ts`: the cwd is `encodeURIComponent`'d to name thediff --git a/src/core/agents/grok-paths.ts b/src/core/agents/grok-paths.tsindex 536a23bb1..6ac7df573 100644--- a/src/core/agents/grok-paths.ts+++ b/src/core/agents/grok-paths.ts@@ -25,7 +25,12 @@ import { isSafeRemoteHome } from '../remote-safety'export const GROK_HOOK_FILE = 'nodeterm-status.json'export const GROK_SUMMARY_FILE = 'summary.json'export const GROK_SIGNALS_FILE = 'signals.json'+/** The ACP event stream. Named here for completeness and read by NOTHING — see `grok-session.ts`+ * for why: it carries message CHUNKS interleaved with tool-call, hook and compaction events, while+ * the settled conversation is one message per line in the file below. grok's hook payloads+ * advertise THIS path as the transcript, which is the trap. */export const GROK_UPDATES_FILE = 'updates.jsonl'+/** The conversation. What context links, the ⌘M panel and cross-agent transfer read. */export const GROK_CHAT_HISTORY_FILE = 'chat_history.jsonl'/** grok URL-encodes the cwd to name a session group; past this many BYTES it switches to adiff --git a/src/core/grok-session.ts b/src/core/grok-session.tsindex 215b30976..11263f90e 100644--- a/src/core/grok-session.ts+++ b/src/core/grok-session.ts@@ -3,9 +3,29 @@// a session at `$GROK_HOME/sessions/<url-encoded cwd>/<id>/`. So the directory is DERIVED, never// searched, and this module only ever reads inside a directory a hook told us about.//-// Documented contents (shipped 1.0.0): summary.json (`generated_title`, `session_summary`,-// `current_model_id`, `info`, timestamps, counts), signals.json (token usage, tool/turn counters),-// updates.jsonl (authoritative conversation log), chat_history.jsonl (raw model messages).+// Contents, MEASURED on 1.0.13 across 29 local sessions (2026-09-02) — the previous version of this+// comment called `updates.jsonl` the "authoritative conversation log" and `chat_history.jsonl` "raw+// model messages", which is backwards where it matters and is the single most expensive false claim+// in this integration: it sends a reader to build against the file that cannot be read message by+// message.+//+// summary.json `generated_title`, `session_summary`, `current_model_id`, `info`,+// timestamps, counts.+// signals.json the context meter's numbers — `contextTokensUsed`, `contextWindowTokens`+// and grok's own `contextWindowUsage` — plus 63 unrelated metrics.+// chat_history.jsonl THE CONVERSATION, one settled message per line (`system`, `user`,+// `assistant`, `tool_result`, `backend_tool_call`, `reasoning`). This is what+// context links, the ⌘M panel and cross-agent transfer read.+// updates.jsonl the ACP event STREAM (`session/update` notifications). It is not empty of+// conversation — `agent_message_chunk`, `user_message_chunk` and+// `agent_thought_chunk` are in there — but it carries CHUNKS interleaved with+// `tool_call`/`tool_call_update`, `hook_execution`, `plan`, compaction and+// subagent events, so reading a message out of it means reassembling it.+// `chat_history.jsonl` is the same conversation already settled.+//+// The trap: grok's hook payloads advertise `updates.jsonl` as the transcript path, so following the+// advertisement is the obvious move and it fails SILENTLY — a real file opens, our line parser finds+// no `type` field on any line, and the caller gets an empty transcript with nothing logged.//// This is grok's reader, and `transcript-reader.ts` stays claude's: a "shared" reader that knows two// storage layouts is two readers in a trench coat, and the one thing neither must ever do is searchdiff --git a/src/main/handoff/render-grok.ts b/src/main/handoff/render-grok.tsindex 28606f77d..16132cac3 100644--- a/src/main/handoff/render-grok.ts+++ b/src/main/handoff/render-grok.ts@@ -1,9 +1,12 @@// Renders a grok chat history .jsonl (~/.grok/sessions/<cwd>/<id>/chat_history.jsonl) to full// Markdown. No size cap, no summarization.//-// The file is `chat_history.jsonl`, NOT the `updates.jsonl` grok's hook payloads advertise: that-// sibling holds no readable conversation, and rendering it produces an empty handoff rather than an-// error. `core/handoff/locate.ts` is where that choice is made and pinned.+// The file is `chat_history.jsonl`, NOT the `updates.jsonl` grok's hook payloads advertise. Being+// precise about the sibling, because an overstatement here would be the same sin this integration+// keeps paying for: `updates.jsonl` DOES carry conversation, as `agent_message_chunk` /+// `user_message_chunk` interleaved with tool-call, hook and compaction events (measured across 29+// sessions). What it does not carry is a settled message per line, so `linesFromGrok` finds no+// `type` on any of them and renders an empty handoff rather than an error. `core/handoff/locate.ts` is where that choice is made and pinned.//// Shape knowledge is NOT duplicated here. `linesFromGrok` (core/context-link-render.ts) already// parses every measured line type from a real session, including the `synthetic_reason` rule thatdiff --git a/src/shared/agents/config.capabilities.test.ts b/src/shared/agents/config.capabilities.test.tsindex 56dc1c773..bc7d73235 100644--- a/src/shared/agents/config.capabilities.test.ts+++ b/src/shared/agents/config.capabilities.test.ts@@ -182,8 +182,9 @@ describe('grok capabilities', () => {it('reads a linked node, on the same already-installed skill the canvas verb uses', () => {// The leaf that had to exist first: `locateGrok` (core/handoff/locate.ts), resolving the// session directory a hook reported and returning `chat_history.jsonl` — NOT the- // `updates.jsonl` grok's payloads advertise, which parses to nothing and would show the- // linked agent an empty transcript with no error. Discovery needs no installer of its own,+ // `updates.jsonl` grok's payloads advertise. That sibling is the ACP event stream: it does carry+ // conversation, but as CHUNKS interleaved with tool-call and hook events, so our line parser+ // finds no `type` on any line and the linked agent gets an empty transcript with no error. Discovery needs no installer of its own,// and that is now MEASURED rather than assumed: on 1.0.13, `grok inspect --json` lists// `get-linked-context` as `vendor: 'claude', compatibilityStatus: 'enabled'`.expect(canContextLink('grok')).toBe(true)