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): say what the capture measured about grok's transcript path

Xavi Guardia5e9f9dd759cd
diff --git a/src/main/index.ts b/src/main/index.ts
index 13aa071f4..94b47c36c 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -2712,7 +2712,10 @@ app.whenReady().then(async () => {
hookServer.setRawListener((agentId, nodeId, payload, _meta) => {
if (agentId === 'grok') {
// This branch records two associations, neither of which grok's envelope states outright.
- // Everything the claude path does below hangs off `transcript_path`, and grok has none. Core
+ // Everything the claude path does below hangs off `transcript_path`. Grok DOES send one --
+ // `transcriptPath`, MEASURED on 1.0.13 in 14 of 15 captured payloads -- but it names
+ // `updates.jsonl`, which holds no readable conversation, so this path deliberately ignores
+ // the advertised value and derives the session directory instead. Core
// owns the node/session/directory transition (`applyGrokHookSession`) so desktop and Server
// Edition cannot implement different event branches — including the one thing only it does:
// PostCompact mints a NEW session id, so the PRIOR id is retired there and not only on
@@ -2722,8 +2725,8 @@ app.whenReady().then(async () => {
// mirror. `plan` carries the decoded event/session/cwd, so the dialect is still decoded in
// exactly one place.
const plan = applyGrokHookSession(nodeId, payload, nodeContextSession)
- // Context meter: grok's numbers are NOT in the transcript, so there is nothing here for
- // `transcript_path` to point at even once grok starts sending one. They live in
+ // Context meter: grok's numbers are NOT in the transcript, so the advertised `transcriptPath`
+ // has nothing here to point at. They live in
// `signals.json`, the sibling of `chat_history.jsonl`, which is why this tail is tracked from
// the DERIVED directory rather than from a hook field — and why it is created with
// `wholeFile` (that file is rewritten in place, not appended to).
diff --git a/src/server/agent-status.test.ts b/src/server/agent-status.test.ts
index 328b0a8cb..541ee874b 100644
--- a/src/server/agent-status.test.ts
+++ b/src/server/agent-status.test.ts
@@ -353,7 +353,9 @@ describe('wireAgentStatus — the grok raw-listener branch', () => {
const fh = fakeHooks()
const ctx = recTail()
wireAgentStatus(platform, { hooks: fh.hooks as never, contextTail: ctx.tail as never })
- // grok's own dialect: camelCase keys, snake_case event VALUE, and no transcript_path at all.
+ // grok's own dialect: camelCase keys, snake_case event VALUE. It DOES send `transcriptPath`,
+ // omitted here because nothing on this path reads it: the transcript is derived from
+ // (cwd, sessionId), and the advertised path names `updates.jsonl`, the wrong file.
fh.fireRaw('grok', 'g1', {
hookEventName: 'user_prompt_submit',
sessionId: 'gs-1',
diff --git a/src/server/agent-status.ts b/src/server/agent-status.ts
index 9bc149679..ffde928e1 100644
--- a/src/server/agent-status.ts
+++ b/src/server/agent-status.ts
@@ -203,7 +203,10 @@ export function wireAgentStatus(
hooks.setRawListener((agentId, nodeId, payload, _meta) => {
if (agentId === 'grok') {
// This branch records two associations, neither of which grok's envelope states outright.
- // Everything the claude path does below hangs off `transcript_path`, and grok has none. Core
+ // Everything the claude path does below hangs off `transcript_path`. Grok DOES send one --
+ // `transcriptPath`, MEASURED on 1.0.13 in 14 of 15 captured payloads -- but it names
+ // `updates.jsonl`, which holds no readable conversation, so this path deliberately ignores
+ // the advertised value and derives the session directory instead. Core
// owns the node/session/directory transition (`applyGrokHookSession`) so desktop and Server
// Edition cannot implement different event branches — including the one thing only it does:
// PostCompact mints a NEW session id, so the PRIOR id is retired there and not only on
@@ -213,8 +216,8 @@ export function wireAgentStatus(
// mirror. `plan` carries the decoded event/session/cwd, so the dialect is still decoded in
// exactly one place.
const plan = applyGrokHookSession(nodeId, payload, nodeContextSession)
- // Context meter: grok's numbers are NOT in the transcript, so there is nothing here for
- // `transcript_path` to point at even once grok starts sending one. They live in
+ // Context meter: grok's numbers are NOT in the transcript, so the advertised `transcriptPath`
+ // has nothing here to point at. They live in
// `signals.json`, the sibling of `chat_history.jsonl`, which is why this tail is tracked from
// the DERIVED directory rather than from a hook field — and why it is created with
// `wholeFile` (that file is rewritten in place, not appended to).
diff --git a/src/shared/agents/normalize.ts b/src/shared/agents/normalize.ts
index b9663b26c..dc2e09cbe 100644
--- a/src/shared/agents/normalize.ts
+++ b/src/shared/agents/normalize.ts
@@ -575,8 +575,10 @@ export function normalizeOpencode(env: RawHookEnvelope): NormalizedAgentEvent |
// session, and the branch never had one. Hooks registered through the grok SDK convert the top-level keys to
// snake_case instead, so both spellings occur in the wild — hence every field is read twice and
// the event name is CANONICALIZED (lowercased, letters only) rather than compared literally.
-// There is deliberately no `transcript_path` in this envelope: grok's transcript is DERIVED from
-// (cwd, sessionId), which is why the shells' raw listeners need `grokRawFields` below.
+// `transcript_path` is deliberately absent from THIS envelope -- but not from the wire. Grok does
+// send `transcriptPath` (MEASURED on 1.0.13, 14 of 15 payloads) and it names `updates.jsonl`, the
+// file that holds no readable conversation. The transcript is DERIVED from (cwd, sessionId)
+// instead, which is why the shells' raw listeners need `grokRawFields` below.
interface GrokPayload {
hookEventName?: string
hook_event_name?: string