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.

feat(core): export readChatTranscript; paged chat reports model/effort

reviewe5bf65cc07bc
diff --git a/src/core/transcript-ipc.test.ts b/src/core/transcript-ipc.test.ts
index 9936439b8..b059f8d42 100644
--- a/src/core/transcript-ipc.test.ts
+++ b/src/core/transcript-ipc.test.ts
@@ -8,7 +8,7 @@ import os from 'os'
import path from 'path'
import { fakePlatform } from './platform-fake'
import { initPlatform, resetPlatformForTests } from './platform'
-import { registerTranscriptIpc } from './transcript-ipc'
+import { readChatTranscript, registerTranscriptIpc } from './transcript-ipc'
import { rememberGrokSessionDir } from './grok-session'
import { IPC } from '../shared/ipc'
import type { ChatTranscriptResult, TranscriptLine } from '../shared/types'
@@ -294,6 +294,34 @@ describe('registerTranscriptIpc — paged chat reads', () => {
return lines(...out)
}
+ it('readChatTranscript is what the IPC handler serves (same result for the same query)', async () => {
+ writeTranscript(
+ lines(
+ userLine('merhaba'),
+ { type: 'assistant', effort: 'xhigh', message: { model: 'claude-opus-5-5', content: [{ type: 'text', text: 'selam' }] } }
+ )
+ )
+ registerTranscriptIpc()
+ const q = { sessionId: SID, cwd: CWD, accountId: undefined, nodeId: undefined, agentId: undefined }
+ for (const page of [undefined, { maxBytes: 65536 }]) {
+ const viaIpc = await paged(page)
+ const direct = await readChatTranscript(q, page, {})
+ expect(direct).toStrictEqual(viaIpc)
+ }
+ const pagedRes = await readChatTranscript(q, { maxBytes: 65536 }, {})
+ expect(pagedRes.model).toBe('claude-opus-5-5')
+ expect(pagedRes.effort).toBe('xhigh')
+ })
+
+ it('the legacy (unpaged) result gains no model/effort keys', async () => {
+ writeTranscript(
+ lines({ type: 'assistant', effort: 'high', message: { model: 'claude-opus-5', content: [{ type: 'text', text: 'x' }] } })
+ )
+ registerTranscriptIpc()
+ const res = await chat()
+ expect(Object.keys(res).sort()).toEqual(['found', 'messages'])
+ })
+
it('legacy (no page) result carries none of the paging fields', async () => {
writeTranscript(lines(userLine('merhaba')))
registerTranscriptIpc()
diff --git a/src/core/transcript-ipc.ts b/src/core/transcript-ipc.ts
index 0a5c5d3ee..d4e4fca3b 100644
--- a/src/core/transcript-ipc.ts
+++ b/src/core/transcript-ipc.ts
@@ -171,6 +171,58 @@ export async function resolveTranscript(
return p
}
+/** What a chat read is asked for — the IPC channel's positional arguments, named. */
+export interface ChatReadQuery {
+ sessionId?: string
+ cwd?: string
+ accountId?: string
+ nodeId?: string
+ agentId?: string
+}
+
+/**
+ * The `chat:read-transcript` read, callable without the IPC seam — the relay's `chat.page` verb
+ * serves the phone through it, so the phone and the ⌘M panel can never read a session differently.
+ * `rawPage` is untrusted (IPC / WS bridge / relay) and validated here; absent = the legacy unpaged
+ * read, byte for byte. Paged claude results also carry `model` / `effort` (see `parseChatWindow`).
+ */
+export async function readChatTranscript(
+ q: ChatReadQuery,
+ rawPage: unknown,
+ deps: TranscriptIpcDeps
+): Promise<ChatTranscriptResult> {
+ const { sessionId, cwd, accountId, nodeId, agentId } = q
+ // Validated FIRST: it arrived over IPC / the WS bridge, and `before` reaches a remote shell
+ // line. `null` = no page asked for = the legacy read below, byte for byte.
+ const page = normalizeChatPage(rawPage)
+ // Routed by agent BEFORE anything claude-shaped runs. `resolveTranscript` below falls back to
+ // the newest claude transcript for the cwd when its sessionId leg misses, and a grok id always
+ // misses — so reaching that fallback with a grok node would answer with a stranger's
+ // conversation. The remote leg is claude-only too (its reader tails claude's file), so a grok
+ // node is served locally or not at all rather than being handed the wrong host's claude log.
+ if (agentId === 'grok') {
+ const gp = sessionId ? await locateGrok(sessionId) : undefined
+ // Grok does NOT page: its history is small and its reader has no byte-offset keys, so a
+ // paged request gets the whole (capped) read with `olderCursor: null` — "nothing older to
+ // fetch" — and no carried results. Keys are absent; the panel falls back to its own.
+ const paging = page ? { olderCursor: null, unmatchedResults: [] } : {}
+ if (!gp) return { messages: [], found: false, ...paging }
+ const buf = await readCappedTail(gp)
+ return buf === undefined
+ ? { messages: [], found: false, ...paging }
+ : { messages: chatMessagesFromGrok(buf), found: true, ...paging }
+ }
+ if (page) return readChatPage({ sessionId, cwd, accountId, nodeId }, page, deps)
+ const remote = deps.readRemote ? await deps.readRemote({ sessionId, cwd, accountId, nodeId }) : null
+ // A resolved-but-unreadable remote file is NOT "no conversation yet" — the read failed
+ // (master down, transcript gone), and the panel must be able to say so.
+ if (remote !== null) return { messages: parseChatMessages(remote.split('\n')), found: !!remote }
+ const p = await resolveTranscript({ sessionId, cwd, accountId }, deps.pathFor)
+ return p
+ ? { messages: await readChatMessages(p), found: true }
+ : { messages: [], found: false }
+}
+
export function registerTranscriptIpc(deps: TranscriptIpcDeps = {}): void {
const remoteText = (q: TranscriptQuery): Promise<string | null> =>
deps.readRemote ? deps.readRemote(q) : Promise.resolve(null)
@@ -220,43 +272,14 @@ export function registerTranscriptIpc(deps: TranscriptIpcDeps = {}): void {
platform().handle(
IPC.chatReadTranscript,
- async (
+ (
sessionId: string | undefined,
cwd: string | undefined,
accountId: string | undefined,
nodeId: string | undefined,
agentId: string | undefined,
rawPage?: unknown
- ): Promise<ChatTranscriptResult> => {
- // Validated FIRST: it arrived over IPC / the WS bridge, and `before` reaches a remote shell
- // line. `null` = no page asked for = the legacy read below, byte for byte.
- const page = normalizeChatPage(rawPage)
- // Routed by agent BEFORE anything claude-shaped runs. `resolveTranscript` below falls back to
- // the newest claude transcript for the cwd when its sessionId leg misses, and a grok id always
- // misses — so reaching that fallback with a grok node would answer with a stranger's
- // conversation. The remote leg is claude-only too (its reader tails claude's file), so a grok
- // node is served locally or not at all rather than being handed the wrong host's claude log.
- if (agentId === 'grok') {
- const gp = sessionId ? await locateGrok(sessionId) : undefined
- // Grok does NOT page: its history is small and its reader has no byte-offset keys, so a
- // paged request gets the whole (capped) read with `olderCursor: null` — "nothing older to
- // fetch" — and no carried results. Keys are absent; the panel falls back to its own.
- const paging = page ? { olderCursor: null, unmatchedResults: [] } : {}
- if (!gp) return { messages: [], found: false, ...paging }
- const buf = await readCappedTail(gp)
- return buf === undefined
- ? { messages: [], found: false, ...paging }
- : { messages: chatMessagesFromGrok(buf), found: true, ...paging }
- }
- if (page) return readChatPage({ sessionId, cwd, accountId, nodeId }, page, deps)
- const remote = await remoteText({ sessionId, cwd, accountId, nodeId })
- // A resolved-but-unreadable remote file is NOT "no conversation yet" — the read failed
- // (master down, transcript gone), and the panel must be able to say so.
- if (remote !== null) return { messages: parseChatMessages(remote.split('\n')), found: !!remote }
- const p = await resolveTranscript({ sessionId, cwd, accountId }, deps.pathFor)
- return p
- ? { messages: await readChatMessages(p), found: true }
- : { messages: [], found: false }
- }
+ ): Promise<ChatTranscriptResult> =>
+ readChatTranscript({ sessionId, cwd, accountId, nodeId, agentId }, rawPage, deps)
)
}
diff --git a/src/core/transcript-reader.test.ts b/src/core/transcript-reader.test.ts
index 0e85ad8a6..92c83f645 100644
--- a/src/core/transcript-reader.test.ts
+++ b/src/core/transcript-reader.test.ts
@@ -127,6 +127,59 @@ const textOfMsg = (m: { parts: Array<{ kind: string; text?: string }> }): string
m.parts.map((p) => p.text ?? '').join('')
describe('parseChatWindow — pure window parsing', () => {
+ it('a paged window reports the newest assistant model and effort', () => {
+ const lines =
+ [
+ JSON.stringify({
+ type: 'assistant',
+ timestamp: '2026-09-25T19:37:29.097Z',
+ effort: 'medium',
+ message: { model: 'claude-opus-5-5', content: [{ type: 'text', text: 'a' }] }
+ }),
+ JSON.stringify({
+ type: 'assistant',
+ timestamp: '2026-09-25T19:37:30.078Z',
+ effort: 'xhigh',
+ message: { model: 'claude-fable-5-1', content: [{ type: 'text', text: 'b' }] }
+ })
+ ].join('\n') + '\n'
+ const r = parseChatWindow(Buffer.from(lines), 0)
+ expect(r.model).toBe('claude-fable-5-1')
+ expect(r.effort).toBe('xhigh')
+ })
+
+ it('a window with no assistant record reports neither (keys absent, not undefined-valued)', () => {
+ const r = parseChatWindow(Buffer.from(JSON.stringify({ type: 'user', message: { content: 'hi' } }) + '\n'), 0)
+ expect(r.model).toBeUndefined()
+ expect(r.effort).toBeUndefined()
+ expect('model' in r).toBe(false)
+ expect('effort' in r).toBe(false)
+ })
+
+ it('model/effort: non-strings, over-long values and the <synthetic> error record are ignored', () => {
+ const rec = (o: object): string => JSON.stringify({ type: 'assistant', ...o }) + '\n'
+ const buf = Buffer.from(
+ rec({ effort: 'high', message: { model: 'claude-opus-5', content: [{ type: 'text', text: 'a' }] } }) +
+ rec({ effort: 'x'.repeat(101), message: { model: 'm'.repeat(101), content: [] } }) +
+ rec({ effort: 7, message: { model: 42, content: [] } }) +
+ // Claude writes an API-error line as model `<synthetic>` with no effort — not a model.
+ rec({ message: { model: '<synthetic>', content: [{ type: 'text', text: 'API Error' }] } })
+ )
+ const r = parseChatWindow(buf, 0)
+ expect(r.model).toBe('claude-opus-5')
+ expect(r.effort).toBe('high')
+ })
+
+ it('model/effort come only from records INSIDE the window (a partial first line is not read)', () => {
+ const l1 = JSON.stringify({ type: 'assistant', effort: 'low', message: { model: 'old', content: [] } }) + '\n'
+ const l2 = JSON.stringify({ type: 'user', message: { content: 'hi' } }) + '\n'
+ const file = Buffer.from(l1 + l2)
+ const start = Buffer.byteLength(l1) - 5
+ const r = parseChatWindow(file.subarray(start), start)
+ expect(r.model).toBeUndefined()
+ expect(r.effort).toBeUndefined()
+ })
+
it('a window starting at 0 parses every line and reports it reached the start', () => {
const file = Buffer.from(said('user', 'a') + said('assistant', 'b'))
const r = parseChatWindow(file, 0)
diff --git a/src/core/transcript-reader.ts b/src/core/transcript-reader.ts
index b645d9075..4fc0a3e9a 100644
--- a/src/core/transcript-reader.ts
+++ b/src/core/transcript-reader.ts
@@ -141,6 +141,19 @@ export async function readTranscriptLines(filePath: string): Promise<TranscriptL
interface ChatRecordsOut {
messages: ChatMessage[]
unmatched: Map<string, string>
+ /** PAGED only: the newest assistant record's `message.model` / `effort` (see `assistantMeta`). */
+ model?: string
+ effort?: string
+}
+
+/** Longest `model` / `effort` value a paged read reports; anything longer is not a model name. */
+const CHAT_META_MAX_CHARS = 100
+/** The model claude stamps on a line it wrote itself (an API error, an interrupt) — not a model. */
+const SYNTHETIC_MODEL = '<synthetic>'
+
+/** A string field worth reporting as chat metadata, else undefined. */
+function metaString(v: unknown): string | undefined {
+ return typeof v === 'string' && v.length > 0 && v.length <= CHAT_META_MAX_CHARS ? v : undefined
}
/** A transcript line's ISO `timestamp` as epoch ms; undefined when absent or not a date string. */
function lineTime(v: unknown): number | undefined {
@@ -157,6 +170,12 @@ function parseChatRecords(
const unmatched = new Map<string, string>()
const toolById = new Map<string, Extract<ChatPart, { kind: 'tool' }>>()
let at: number | undefined
+ // Each updated independently from every assistant record (paged only), so the newest record that
+ // states one wins. Measured: claude's `<synthetic>` error lines carry no `effort` and a fake
+ // model, and older CLIs wrote no `effort` at all — neither may blank a value an earlier record in
+ // the same window stated.
+ let model: string | undefined
+ let effort: string | undefined
const push = (m: ChatMessage, offset: number): void => {
// `at` rides BOTH paths (additive): the time the line was written, for the thread's relative
// timestamp. Absent when the line states none — never a made-up time.
@@ -165,7 +184,7 @@ function parseChatRecords(
}
for (const { raw, offset } of records) {
if (!raw.trim()) continue
- let o: { type?: string; timestamp?: unknown; message?: { content?: unknown } }
+ let o: { type?: string; timestamp?: unknown; effort?: unknown; message?: { content?: unknown; model?: unknown } }
try {
o = JSON.parse(raw)
} catch {
@@ -173,6 +192,12 @@ function parseChatRecords(
}
at = lineTime(o.timestamp)
const content = o.message?.content
+ if (paged && o.type === 'assistant') {
+ const m = metaString(o.message?.model)
+ if (m && m !== SYNTHETIC_MODEL) model = m
+ const e = metaString(o.effort)
+ if (e) effort = e
+ }
if (o.type === 'assistant' && Array.isArray(content)) {
const parts: ChatPart[] = []
for (const c of content as Array<{
@@ -227,7 +252,12 @@ function parseChatRecords(
push({ role: 'user', parts: [{ kind: 'text', text: content }] }, offset)
}
}
- return { messages, unmatched }
+ const out: ChatRecordsOut = { messages, unmatched }
+ // Keys only when stated: an absent key, never `model: undefined`, keeps the output deterministic
+ // (and JSON-identical) for the ports locked to it.
+ if (model !== undefined) out.model = model
+ if (effort !== undefined) out.effort = effort
+ return out
}
export function parseChatMessages(rawLines: string[]): ChatMessage[] {
@@ -242,6 +272,10 @@ export interface ChatWindowParse {
messages: ChatMessage[]
olderCursor: number | null
unmatchedResults: ChatCarriedToolResult[]
+ /** The newest assistant record's model / effort among this window's complete lines. Absent (the
+ * key, not just the value) when no such record states one. */
+ model?: string
+ effort?: string
/**
* The window (not starting at 0) held no complete line: one record is bigger than the whole
* window. Explicit rather than inferred from "no messages", because a window of complete lines
@@ -293,11 +327,13 @@ export function parseChatWindow(buf: Buffer, bufStart: number): ChatWindowParse
if (to > from) records.push({ raw: buf.toString('utf8', from, to), offset: bufStart + from })
from = to + 1
}
- const { messages, unmatched } = parseChatRecords(records, true)
+ const { messages, unmatched, model, effort } = parseChatRecords(records, true)
return {
messages,
olderCursor,
unmatchedResults: [...unmatched].map(([id, result]) => ({ id, result })),
+ ...(model !== undefined ? { model } : {}),
+ ...(effort !== undefined ? { effort } : {}),
noCompleteLine: false
}
}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 725455e9c..d01932b5f 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -2879,6 +2879,13 @@ export interface ChatTranscriptResult {
* the same `id` when an older page arrives. Always `[]` from a reader that does not page.
*/
unmatchedResults?: ChatCarriedToolResult[]
+ /**
+ * PAGED claude reads only: the newest assistant record's `message.model` in the returned window
+ * (`<synthetic>` error lines skipped). Absent when the window has none, and on the legacy read.
+ */
+ model?: string
+ /** PAGED claude reads only: the newest assistant record's top-level `effort` in the window. */
+ effort?: string
}
/**