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
// Reads what nodeterm needs from a grok session DIRECTORY. Grok's hook envelope carries no
// transcript path (claude's does), but every event carries `cwd` and `sessionId` — and grok stores
// 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.
//
// 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
// the other's tree. The choice is made once, at the IPC handler.
import fs from 'fs'
import path from 'path'
import { GROK_SUMMARY_FILE, isSafeGrokSessionId } from './agents/grok-paths'
import { writeFileAtomic } from './fs-atomic'
import { platform } from './platform'
/** Read at most this much of summary.json — it is small, and a capped read bounds a corrupt file. */
const SUMMARY_MAX_BYTES = 256 * 1024
export interface GrokSessionMeta {
/** The session's own name — what `/resume` shows and what the node title adopts. */
title: string | null
/** grok's model id, for anything that needs the model (e.g. the context window). */
model: string | null
}
/**
* Title keys in PREFERENCE order.
*
* MEASURED (grok 1.0.13, 2026-09-02): `/rename <name>` typed into a live session rewrites
* **`generated_title`** in place — the same field the model-generated name uses — and no `title`
* key ever appears in `summary.json`. Grok does not distinguish a manual title from a generated one
* the way claude's `custom-title` / `ai-title` pair does.
*
* `'title'` stays first as forward compatibility: a key absent from every file costs one failed
* lookup and can never produce a wrong name. If a future grok splits the two, a manual title wins.
*
* `session_summary` is the fallback for a session too young to have `generated_title` yet. Measured
* across 49 local summary.json files (1.0.13): 20 of them carry `session_summary` and no
* `generated_title`; where both exist they are identical in 28 of 29; the longest value in the
* corpus is 49 characters. It is accepted only under SESSION_SUMMARY_TITLE_MAX: a longer value is
* **refused, not truncated**, because this result is adopted as the node title with no other length
* cap on the path (header, sidebar, kanban card, window title, project.json). Null is the node
* keeping its own name; a truncated sentence is a wrong name.
*/
const TITLE_KEYS = ['title', 'generated_title', 'session_summary'] as const
/** Longest observed title in the 1.0.13 corpus is 49 characters. 80 is "a title, generously". */
const SESSION_SUMMARY_TITLE_MAX = 80
/** Pure: the meta from a summary.json body. null when this is not a summary object at all. */
export function pickGrokSessionMeta(summaryJson: string): GrokSessionMeta | null {
let o: unknown
try {
o = JSON.parse(summaryJson)
} catch {
return null
}
if (!o || typeof o !== 'object' || Array.isArray(o)) return null
const rec = o as Record<string, unknown>
let title: string | null = null
for (const k of TITLE_KEYS) {
const v = rec[k]
if (typeof v !== 'string') continue
const trimmed = v.trim()
if (!trimmed) continue
if (k === 'session_summary' && trimmed.length > SESSION_SUMMARY_TITLE_MAX) continue
title = trimmed
break
}
const model = typeof rec.current_model_id === 'string' ? rec.current_model_id : null
return { title, model }
}
/** Read a session directory's summary.json. null when it is absent or unreadable. */
export async function readGrokSessionMeta(sessionDir: string): Promise<GrokSessionMeta | null> {
try {
const fd = await fs.promises.open(path.join(sessionDir, GROK_SUMMARY_FILE), 'r')
try {
const buf = Buffer.alloc(SUMMARY_MAX_BYTES)
const { bytesRead } = await fd.read(buf, 0, SUMMARY_MAX_BYTES, 0)
return pickGrokSessionMeta(buf.subarray(0, bytesRead).toString('utf-8'))
} finally {
await fd.close()
}
} catch {
return null
}
}
// The hook-fed association: sessionId → its resolved session directory. Populated by the shells'
// raw listeners (which see cwd + sessionId together) so every later read is a direct open. Bounded
// because a long-lived app can see many sessions; the oldest entry is dropped first.
//
// PERSISTED since 2026-09, and the distinction matters: persisting is not scanning. A scan is what
// claude does — it searches its transcript tree for a session id — and it is exactly the behaviour
// that made nodes adopt each other's names, which is why grok derives instead. What is written here
// is only what a hook already TOLD us, so a restart recovers facts we were given rather than
// guessing at facts we were not. Before this, a grok node's name went blank after every app restart
// until that session next fired a hook: correct, but silently unhelpful for a session sitting idle.
const MAX_TRACKED_SESSIONS = 512
const sessionDirs = new Map<string, string>()
/** Where the map lives. Under userDataDir like every other derived cache, so a managed-account or
* Server Edition install keeps its own. */
function mapFile(): string {
return path.join(platform().userDataDir, 'grok-session-dirs.json')
}
/** Writes are debounced and never awaited by the hook path: a raw listener must not block on disk,
* and a burst of events for one session would otherwise be a burst of writes. */
const PERSIST_DEBOUNCE_MS = 1000
let persistTimer: ReturnType<typeof setTimeout> | null = null
let loaded = false
function schedulePersist(): void {
if (persistTimer) return
persistTimer = setTimeout(() => {
persistTimer = null
void persistGrokSessionDirs()
}, PERSIST_DEBOUNCE_MS)
// Never hold the process open for a cache write.
persistTimer.unref?.()
}
/** Write the map. Atomic (rule 14): a torn file here is a map that resolves nothing AND cannot be
* repaired, which is worse than no file at all. Failures are swallowed on purpose — this is a
* cache, and losing it costs a name until the next hook, exactly the pre-persistence behaviour. */
export async function persistGrokSessionDirs(): Promise<void> {
try {
await writeFileAtomic(mapFile(), JSON.stringify(Object.fromEntries(sessionDirs)), {
mode: 0o600
})
} catch {
// Cache write failed. Nothing to say and nothing to do: the in-memory map is unaffected.
}
}
/**
* Load the map from disk, once per process. Called lazily by the first read rather than at boot, so
* neither shell needs a new startup step to keep the two in sync (invariant 11 by construction).
*
* Every entry is re-validated with `isSafeGrokSessionId` before it is trusted: this file is written
* by us, but it sits in a directory a user can edit, and the values end up as filesystem paths. A
* corrupt or hand-edited file yields an EMPTY map, never a partial one built from whatever parsed.
*/
function loadOnce(): void {
if (loaded) return
loaded = true
try {
const raw = fs.readFileSync(mapFile(), 'utf8')
const parsed: unknown = JSON.parse(raw)
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return
for (const [id, dir] of Object.entries(parsed as Record<string, unknown>)) {
if (typeof dir !== 'string' || !dir) continue
if (!isSafeGrokSessionId(id)) continue
if (sessionDirs.size >= MAX_TRACKED_SESSIONS) break
// An entry already learned from a live hook wins: it is newer by definition.
if (!sessionDirs.has(id)) sessionDirs.set(id, dir)
}
} catch {
// Absent (first run), unreadable, or not JSON — all mean "no remembered map", which is the
// pre-persistence behaviour and never a wrong answer.
}
}
export function rememberGrokSessionDir(sessionId: string, dir: string): void {
if (!sessionId || !dir) return
loadOnce()
// Re-insert so the map's iteration order is least-recently-SEEN first: that is what makes the
// eviction below drop the session nobody has heard from, not whichever one happened to be first.
if (sessionDirs.has(sessionId)) sessionDirs.delete(sessionId)
sessionDirs.set(sessionId, dir)
if (sessionDirs.size > MAX_TRACKED_SESSIONS) {
const oldest = sessionDirs.keys().next().value
if (oldest !== undefined) sessionDirs.delete(oldest)
}
schedulePersist()
}
export function grokSessionDirFor(sessionId: string | undefined): string | undefined {
if (!sessionId) return undefined
loadOnce()
return sessionDirs.get(sessionId)
}
export function forgetGrokSession(sessionId: string | undefined): void {
if (!sessionId) return
loadOnce()
if (sessionDirs.delete(sessionId)) schedulePersist()
}
/** Test seam: drop the in-memory map AND the load flag, so a test can simulate a process restart
* without a new process. */
export function _resetGrokSessionDirsForTests(): void {
sessionDirs.clear()
loaded = false
if (persistTimer) {
clearTimeout(persistTimer)
persistTimer = null
}
}
/**
* Reads a REMOTE grok session's `summary.json` on its own host.
*
* Returns `{ text }` for a session this reader owns (even when the body is empty — that is "remote
* and unreadable", which must not become a local lookup), and `null` for a session it does not own,
* which routes to the local map.
*/
export type GrokRemoteSummaryReader = (
sessionId: string
) => Promise<{ text: string } | null>
/** The session NAME for a sessionId we have seen a hook for. null when unknown or unnamed. */
export async function readGrokSessionName(
sessionId: string,
remote?: GrokRemoteSummaryReader
): Promise<string | null> {
// A REMOTE (SSH) node's session lives on the HOST. The shells derive the directory from the LOCAL
// sessions root with the host's `cwd`, which is a path on the wrong machine — §8.4. So the remote
// reader is asked FIRST, and its answer is final:
//
// `{ text }` this session is remote. Parse that text and stop. An empty/unreadable body means
// NO NAME — never the local map. Falling back would answer a question about the
// host with a fact about this machine, and "could not read" and "does not exist"
// are different facts that must stay different (rule 9).
// `null` this session is not remote. Use the local map, exactly as before.
//
// Same shape as claude's `setRemoteTranscriptReader`, deliberately: one remote idiom, not two.
if (remote) {
const r = await remote(sessionId)
if (r) return pickGrokSessionMeta(r.text)?.title ?? null
}
const dir = grokSessionDirFor(sessionId)
if (!dir) return null
return (await readGrokSessionMeta(dir))?.title ?? null
}