Skip to content

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.

docs(grok): describe updates.jsonl from measurement, in all four places

Xavi Guardia5e9665f6cefe
diff --git a/docs/grok-agent.md b/docs/grok-agent.md
index 405ea5186..573cda909 100644
--- a/docs/grok-agent.md
+++ b/docs/grok-agent.md
@@ -215,6 +215,16 @@ $GROK_HOME/ # $GROK_HOME, else ~/.grok
hooks/*.json # all merged; nodeterm-status.json is ours
sessions/<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 the
diff --git a/src/core/agents/grok-paths.ts b/src/core/agents/grok-paths.ts
index 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 a
diff --git a/src/core/grok-session.ts b/src/core/grok-session.ts
index 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 search
diff --git a/src/main/handoff/render-grok.ts b/src/main/handoff/render-grok.ts
index 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 that
diff --git a/src/shared/agents/config.capabilities.test.ts b/src/shared/agents/config.capabilities.test.ts
index 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)