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.
Chat golden fixtures
This directory holds the reference outputs for the mobile chat view's parser port
(docs/mobile-chat-view.md). The TypeScript implementation is the reference. nodeterm-ios keeps
a byte-identical copy of this directory, and its Swift port must reproduce every expected/*.json
from the same inputs.
Every input is synthetic. The inputs are built by src/core/chat-fixtures.test.ts from the
record shapes measured on real Claude transcripts. None of them is a slice of a real transcript,
because real transcripts carry customer data. Do not add one.
Regenerate
UPDATE_CHAT_FIXTURES=1 npx vitest run src/core/chat-fixtures.test.ts
This command rewrites inputs/, pending/, decision-cases.json and expected/. Without the
variable, the test requires every file to equal what the code produces, so a parser change that
moves one byte of output fails here. After regenerating, refresh the iOS copy in the same change.
Layout
| path | what it is |
|---|---|
inputs/<name>.jsonl |
A synthetic Claude transcript. |
expected/<name>.pages.json |
The page sequence the phone's pager produces from that transcript (see below). |
pending/<name>.json |
A held PermissionRequest hook payload, in the same form as the pending file the hook writes. |
decision-cases.json |
[{name, pending, answer}]: each answer that is tried against a pending file. |
expected/<case>.decision.json |
The buildPermissionDecision result for that case, as it is returned: {ok:true, content, decision} or {ok:false, reason}. |
answer-cases.json |
[{name, answer}]: raw answers given to the shape check alone. |
expected/<case>.answer.json |
parsePermissionAnswer(answer) verbatim. null means the shape check refuses the answer. |
The test also requires inputs/, pending/, expected/ and the top-level *-cases.json files to
hold exactly the generated set.
A regenerate removes files that no case produces any more, so a copy taken from this directory never
carries a stale case. Regenerating is refused when CI is set.
Every expected file is JSON.stringify(value, null, 2) + "\n". Keys appear in the order the TS
code builds them. Optional keys (model, effort, at, key, a tool part's id/body/
result/questions) are absent when unset. They are never null, and never present with an
undefined value.
The pager (the Swift port must replicate this exactly)
The pager mirrors parseGrowingWindow in src/core/transcript-ipc.ts, one page at a time:
- The first request is
before = null(end of file) andmaxBytes = 262144. - Read the window:
end = before ?? size,windowStart = max(0, end - maxBytes). The buffer starts one byte earlier (start = windowStart - 1) whenwindowStart > 0. This lookbehind byte is the only way to recognise a line that begins exactly on the window edge. CallparseChatWindow(buffer, start). - While the result has
noCompleteLine,start != 0andmaxBytes < 5242880, setmaxBytes = min(5242880, maxBytes * 4)and re-read the samebefore. - Record the step. If
olderCursorisnull, stop. Otherwise the next request isbefore = olderCursor,maxBytes = 524288.
Each entry in *.pages.json is one step:
{ before: number|null, maxBytes: number (requested), grownMaxBytes: number (after growth),
start: number (absolute offset of the buffer's first byte, lookbehind included),
parse: { messages, olderCursor, unmatchedResults, model?, effort?, noCompleteLine } }
parse is parseChatWindow's return value, verbatim. The test also checks that every step equals
what the real desktop producer (readChatTranscript with that page) serves. The pager is therefore
the production paging, not a second implementation of it.
What each fixture pins
| fixture | pins |
|---|---|
plain-turns |
User/assistant text, markdown (headings, lists, a blockquote, code fences), string and array user content, two text blocks in one message, and non-ASCII text. Metadata-only records (file-history-snapshot, system) yield no message. |
tools-cross-page |
A tool_use that lands in the second (older) page while its tool_result lands in the tail. The tail carries it in unmatchedResults, and the older page carries the tool part with its id so the port can attach it. One tool call is matched inside the tail. It also shows the summarizeResult rules: three lines joined, capped at 500. The desktop renderer folds a run of two or more consecutive agent tool calls into one block, except the run at the END of the thread while the agent is working or waiting on a prompt (the live turn; the end is measured before any optimistic "Queued" prompt bubbles drawn after it), and the parser output is unchanged, so a port that renders a thread should fold the same runs. |
plan-mode |
An ExitPlanMode tool call with input:{plan}. The tool part carries the full plan as body and the approval text as result. |
ask-question |
AskUserQuestion with a single-select and a multi-select question: the rendered body, the parsed questions (the same reader the answer controls match on) and each result. |
utf8-edge |
Multi-byte characters on the window boundaries. The tail window (EOF − 262144) opens inside a 4-byte emoji of one line, which must be dropped as the partial line and never decoded torn. The second page (524288) starts exactly on the first byte of a multi-byte line, which is kept only because of the lookbehind \n. The straddled line reappears whole in that page. The test asserts both placements. |
huge-last-line |
The last line is a ~600 KB user record with a base64 image. The 262144 tail has no complete line, so it grows to 1048576. The message still shows its text part, and paging continues from the grown window's olderCursor. |
model-effort |
model/effort across records that go medium→xhigh and change model. The newest assistant record wins. |
model-effort-no-carry |
ONE record answers both fields. The newest record states no effort, so the key is absent, and an older record's value is never carried forward (same rule as parseLatestUsage). |
model-effort-synthetic |
A <synthetic> record (an API error or interrupt, with no effort) is skipped entirely, so both fields come from the real record before it. |
model-effort-utf16 |
The 100-character cap counts UTF-16 code units (Swift utf16.count), not bytes or scalars. A model of 50 × U+1F9EA (100 units) is kept, and an effort of 101 units is absent. |
thinking |
Thinking blocks (thinking, redacted_thinking). The reader drops them by default: a thinking-only record yields no message, and a mixed record keeps only its text. The port must match this. (The desktop ⌘M panel opts in with page.thinking: true and then gets a {kind:"thinking", text, ms?} part for each block whose thinking text is non-blank: text is capped at 16384 UTF-16 units, and ms is this record's timestamp minus that of the newest user record before it (a prompt, a tool_result or a hidden meta line), present only when both stamps exist and the gap is ≥ 0 — see the ChatPart doc in src/shared/types.ts. The phone's chat.page never sets it, so these fixtures are unchanged.) |
local-commands |
Slash-command records (see Local commands below). An isMeta caveat is skipped; /model plus its ANSI-coloured <local-command-stdout> become ONE assistant tool part {name:"/model", arg:"", result}; /effort with padded args (trimmed) answered on <local-command-stderr>; /compact with an arg longer than the 200-unit cap; /exit with an empty stdout (no result); a skill invocation (<command-message> before <command-name>) whose isMeta array body is skipped; a stdout with no command right before it (its own command output tool, capped to three lines); and a user message that only mentions <command-name> in prose (stays a user message). |
bash-mode |
! bash-mode records: <bash-input> becomes a tool part named ! with the command as arg; the ONE following record carrying <bash-stdout>…</bash-stdout><bash-stderr>…</bash-stderr> sets its result (non-empty parts joined by \n, lines kept, the BASH_OUTPUT_MAX cap), including an empty stdout with a stderr, and a command that printed nothing (result: ""). |
meta-turns |
isMeta rule 1: a peer hand-back (promptSource + origin.kind:"peer" + turnOrigin), a scheduled wakeup (turnOrigin:"scheduled" + scheduledTaskId), an auto-continuation (origin.kind:"auto-continuation"), a promptSource-only, an origin-only and a turnOrigin-only record (the last two with no promptSource, so each field is pinned on its own) are all KEPT; the caveat and a skill body (none of the three fields) are skipped. Three of the kept records then render as system chips (see System-injected records): BOTH origin.kind:"peer" records — the hand-back and the origin-only one — as Agent message, and the auto-continuation as System; the others stay user messages. |
system-records |
Every rule of System-injected records: a full agent completion (nested <usage>, a result over three lines), a status + summary completion, a monitor <event>, a summary alone (the notified result), a repeated <task-id> with a summary over the 200-unit cap, a whole element with no origin, the same whole element sent by a human (origin.kind:"human", and promptSource:"typed" with no origin; both stay user messages), two malformed notifications (unknown tags only; plain prose), a message that only MENTIONS the element (stays a user message), a subagent <agent-message> hand-back with its frame lines, a <cross-session-message> (its from-name is the arg), a report over the 16384-unit cap, a peer record with no element, an auto-continuation and a multi-line coordinator prompt. |
teammate-messages |
Rule 2b of System-injected records: an idle notification with a report, one with no fields, a failed one (failureReason), a plain message whose summary is escaped (") and whose body quotes the close tag, a record holding two elements (a report, then a message), an unverified sender (verified="false"), the same text typed by a human (by origin and by promptSource alone — both stay user messages), the frame line with no element and an element with no teammate_id (both stay user messages). |
pasted-content |
Pasted content: a span between typed lines, backtick runs inside (a five-backtick fence) and the same id twice, an array text part beside an image, a pasted <task-notification> (stays the user's paste), a close tag with a different id inside a span (content), an empty paste, a same-id open nested inside a span (the span ends at the FIRST close), text that is not the CLI's grammar (no id, an upper-case or three- or five-digit id, a missing newline after the open or before the close: all left as typed) and an unclosed span (left as typed). |
queued-prompts |
Queued prompts: a typed prompt queued mid-turn (between a tool result and the reply), one with no origin, an array prompt with an image (its text block only), a paste inside one (fenced, as in a typed prompt), and six attachments that stay hidden: a task notification, a peer message (isMeta), a coordinator message, a non-human origin, a blank prompt and a non-queued_command attachment. |
abandoned-prompts |
Abandoned prompts: a queued prompt cancelled with Esc (its parent is the interrupt marker) and a sent-then-edited array prompt are hidden; a raw /compact left beside its command record is hidden and the command stays; a prompt the model answered before a re-send, a prompt whose only later sibling is a sidechain record, a prompt typed during a pending tool call (its later sibling is the tool-result record), and the newest unanswered prompt are all kept. |
rich is a second desktop-only opt-in, beside thinking: the ⌘M panel reads with
page.rich: true (ChatParseOptions.rich) to get the parts only it draws. The fixtures never set
it, and neither does the phone's chat.page (the relay host forwards only before / maxBytes), so
nothing above changes. What it adds:
- An
{kind:"image", mediaType, data}part for each{type:"image", source:{type:"base64", media_type, data}}block of a user record's content array, in content order, whenmedia_typeis one ofimage/png,image/jpeg,image/gif,image/webp(CHAT_IMAGE_TYPES) anddatais a non-empty string. Any other type (image/svg+xmlincluded) or source yields no part. An image inside atool_resultis tool output and never becomes one. An image-only record yields no message without the option and a user message with it. - A
diff: {filePath, oldText, newText}on anEdittool part ({file_path, old_string, new_string}) or aWriteone ({file_path, content},oldText: ""), read from the call's input whenfile_pathis a non-empty string and the texts are strings (an emptynew_stringis a deletion and still a diff). Each text over 65536 UTF-16 units is cut there (one unit earlier when the cut would split a surrogate pair) andTOOL_BODY_TRUNCATEDappended — and, unlike a toolbody, no closing fence line is added for a code block the cut left open: the text is file content, not markdown (capText). Any other shape yields nodiff;argandresultare unchanged. - A
{type:"system", subtype:"compact_boundary", compactMetadata}record becomes ONE assistant message with ONE tool part{name:"Compaction", arg, result?}:argiscompactMetadata.trigger(""when not a string; its first 200 UTF-16 units,CHAT_TOOL_ARG_MAX), andresultis"<preTokens> → <postTokens> tokens"(plain digits, U+2192) only when both are finite numbers. It is a system record (a turn boundary, never folded). Thetype:"user"record withisCompactSummary: true(the summary the model continues from) is skipped. - A
bodyon aTodoWritetool part: one line pertodositem with a non-blankcontent(- [x] …completed,- [ ] **…** _(in progress)_in progress, else- [ ] …), capped like any toolbody.
Decision cases: plan restore / acceptEdits / manual / revise (the revise text is trimmed),
question single / multi (labels joined with , ) / free text (trimmed), and three refusals: a
partial answer (two questions, one answered), an unknown label, and a tool mismatch (a plan answer
against a held Bash). The pipeline is
parsePendingRequest(file text) → parsePermissionAnswer(answer) → buildPermissionDecision.
Two more refusals come from the length cap (ANSWER_TEXT_MAX_CHARS, 8000 UTF-16 units): a revise
message and a free-text answer one unit over it.
A decision's content is itself a JSON string: it is the exact text the hook prints to Claude.
Its inner key order and escaping are those of JSON.stringify: hookSpecificOutput →
hookEventName → decision → behavior → updatedInput / updatedPermissions / message, and
within updatedInput, the pending file's own tool_input keys followed by answers. The port must
reproduce it byte for byte (the hook script matches a fixed prefix, PERMISSION_DECISION_PREFIX),
or at the very least compare it structurally after parsing. The prefix check alone requires the
first bytes to match exactly.
Where each refusal happens matters, and the port must put it in the same layer.
answer-*.answer.json records the SHAPE check: a plan mode:'auto' and an unknown kind are
refused there (null). An over-long text is NOT refused there: answer-revise-too-long-parses
parses, and the cap is applied by buildPermissionDecision (plan-revise-too-long-refused,
question-free-text-too-long-refused). Text of exactly 8000 units is accepted (plan-revise-at-cap,
question-free-text-at-cap), so a port with a lower cap fails too.
Local commands (the Swift port must replicate this exactly)
parseChatRecords (src/core/transcript-reader.ts, classifyLocalCommand) applies these rules,
on the paged and unpaged paths alike:
- A
type:"user"record withisMeta === trueis skipped entirely (no message, noateffect) only when it carries none ofpromptSource,origin,turnOrigin(each counts when the key is present with a non-nullvalue). That skips the local-command caveat, skill bodies and injected reminders. AnisMetarecord carrying any of the three starts a turn (a peer / subagent hand-back, a scheduled or loop wakeup, an auto-continuation) and is parsed like any other user record: the System-injected records rules first (a peer or auto-continuation record becomes a system chip there), otherwise the rules below, otherwise a user text message. - Only a user record whose
message.contentis a string is examined. It must consist ONLY of whole tags<t>…</t>(tmatches[a-z-]+; content non-greedy up to the matching close tag), separated by whitespace (JS\s), each tag name at most once. Anything else in it (prose, an unknown tag, a repeated tag) makes it an ordinary user text message. - Tags only from {
command-name,command-message,command-args}, any order, with a non-blank trimmedcommand-name→ command: an assistant message with one part{kind:"tool", name:<command-name trimmed>, arg:<command-args trimmed, "" when absent>}. Slash tags with a blank or missingcommand-nameare ordinary user text. Tags only from {bash-input} → command withname:"!",arg:<bash-input trimmed>.argis capped like a tool call's arg (toolArg): trimmed FIRST, then its first 200 UTF-16 units (CHAT_TOOL_ARG_MAX,String.prototype.slice(0, 200)). - Tags only from {
local-command-stdout,local-command-stderr} (slash family) or only from {bash-stdout,bash-stderr} (bash family) → output. Its text is each tag's content, in record order, with ANSI escapes removed (\x1b[CSI[0-?]*[ -/]*[@-~], then OSC\x1b][^\x07\x1b]*(\x07|\x1b\\), then two-byte\x1b[@-_]), trimmed, empty parts dropped, joined by\n. The bash family's text then keeps its lines, capped at its first 16384 UTF-16 units (BASH_OUTPUT_MAX: the chat view shows the first line under the command and the rest when opened); the slash family's is capped like a tool result (first three lines joined by a space, first 500 UTF-16 units). An empty slash text produces nothing. - An output sets
resulton the command's tool part when the last pushed message is a command of the same family that has no result yet — for the bash family even when it is empty ("": the command ran and printed nothing); for the slash family only when it is non-empty. Otherwise a non-empty output is pushed as its own assistant message{kind:"tool", name:"command output", arg:"", result}, and an empty one pushes nothing. Any pushed message ends the wait, and so does an attached output (a second output does not overwrite). A record that pushes nothing does NOT end it: a skippedisMetarecord, an empty slash output, an empty bash output with no command waiting, a metadata-only record, a thinking-only assistant record or a tool_result-only user record. - "Trimmed" everywhere in these rules means JS
String.prototype.trim, which strips JS\s: ASCII whitespace plus U+00A0, U+FEFF, U+1680, U+2000–U+200A, U+2028, U+2029, U+202F, U+205F and U+3000. Swift's.whitespacesAndNewlinesis a different set (it lacks U+FEFF and adds U+0085, for example), so the port needs its own predicate. The same set is the "whitespace between tags" of rule 2. - A command message carries
key/atlike any other message; an attached output changes neither. No new role, part kind or field: a v1 decoder reads these as ordinary tool parts.
System-injected records (the Swift port must replicate this exactly)
Claude Code writes a background task's completion, another session's message and an
auto-continuation as type:"user" records. They are not the user's words. parseChatRecords
(classifySystemRecord, src/core/transcript-reader.ts) applies these rules to a user record
whose message.content is a string with a non-blank trim, BEFORE the local-command rules above
(array content is never classified: none of these kinds was measured with it). The kind is
origin.kind when origin is an object and kind a string, else none.
Each result is ONE assistant message with ONE part {kind:"tool", name, arg, result}; result is
absent when it is "". It carries key / at like any other message and, like any pushed
message, ends a local command's wait for its output. No new role, part kind or field.
Every \s in this section and the next is JS \s — the same set trim strips (Local commands
rule 6). ICU's \s (Swift NSRegularExpression / Regex) is a different set: it lacks U+000B and
U+FEFF, among others, so the port needs its own predicate. The regexes here are the SPECIFICATION;
the TS code implements each with indexOf scans in linear time (a backtracking regex over many
unclosed tags is quadratic: 1 MB ≈ 20 s), and the port must be linear too. The equivalences the
linear scans rely on: tag = the first <n>, then the first </n> after it (no close after the
first open means no close after any later one); the peer element = for each name, the first open
followed by > or \s, its first >, and the last </name> if that lies after the > (only the
first such open can match); the earlier of the two names wins.
Helpers (trim is JS String.prototype.trim, see Local commands rule 6; every cap counts UTF-16
units, String.prototype.slice(0, n), and may split a surrogate pair exactly as JS does):
firstLine(t)=t.trim(), split on\n, the first piece, trimmed, first 200 units.full(t)=t.trim(), first 16384 units (SYSTEM_RESULT_MAX).tag(t, n)= the content of the FIRST match of<n>([\s\S]*?)</n>int(anywhere, nested or not), trimmed;""when there is none.summarize(t)=summarizeResult: split on\n, the first three pieces joined by a space, the first 500 units.- The fallback for name N is
{name: N, arg: firstLine(content), result: full(content)}.
- Background task (
name:"Background task") when the kind istask-notification, OR when there is NO kind,promptSourceis UNSET or"system", and the whole string is exactly ONE element: it matches^\s*<task-notification>([\s\S]*)</task-notification>\s*$AND the captured inner text contains neither<task-notification>nor</task-notification>. ThepromptSourcetest is an ALLOWLIST, not a list of human sources:"typed","queued","suggestion_accepted","sdk"and any value added later never match. UNSET means the key is absent (TS=== undefined); a presentnullis NOT unset and never matches either — the TS code is the reference here. (A human who types or pastes one element is recorded exactly like that, withorigin.kind:"human"/promptSource:"typed", measured on CLI 2.1.285; any other kind,humanincluded, is never matched by content.) Then, over the whole string:summary = tag("summary"),status = tag("status"),body = tag("result"), ortag("event")when that is"". When all three are""→ the fallback. Otherwisearg= the first 200 units ofsummary, andresult=summarize(text)wheretext=status + ": " + bodywhen both are non-empty, else whichever is non-empty, else the neutral marker"notified"(TASK_NOTIFIED_RESULT: a summary with neither a status nor a body still reads as finished, not as a tool that is running; neutral rather than "done", because such a notification is often a start). So a Background task part always has aresult. Other child tags (task-id,tool-use-id,output-file,note,usage,task-type,worktree, …) are never read, and no XML entity is decoded. - Agent message (
name:"Agent message") when the kind ispeer. Find the first (leftmost) match of<(agent-message|cross-session-message)(\s[^>]*)?>([\s\S]*)</\1>(greedy: up to the LAST close tag of the same name). No match → the fallback. Otherwisebody= group 3 trimmed; everything outside the element (the "Another Claude session sent a message:" line, the instruction trailer) is dropped.fromName= group 1 of(?:^|\s)from-name="([^"]*)"matched on group 2 (""when group 2 is absent or has no match), trimmed.arg= the first 200 units offromNamewhen it is non-empty, elsefirstLine(body);result=full(body). 2b. Agent message for an agent team's teammate writing to the lead (measured on CLI 2.1.285–2.1.316: noorigin, nopromptSource, noisMeta) when there is NO kind (originabsent — a presentorigin, evennull, never matches),promptSourceis UNSET or"system", the string STARTS with one ofAnother Claude session sent a message:\n,Another Claude session sent a message while you were working:\n,A peer session sent a message while you were working:\n, and at least one element follows. Elements, from the end of that line: skip\s; an element starts with<teammate-messagefollowed by one\s, its attributes run to the first>, and it needs a non-empty (trimmed)teammate_id; else stop. Attributes arename="value"pairs (the first of a name wins); a value's"'&<>are decoded in ONE pass. The body starts after the>(and one\nright after it, if any) and ends at the first</teammate-message>after which, skipping\s, comes the end of the string or the next<teammate-message; if no close qualifies, at the LAST</teammate-message>(when that lies at or after the body's start, else stop). Parsing stops after an element ended by the fallback or by the end of the string; what follows (the trailer) is dropped. No element → not this rule (rule 4). Per element:from=firstLine(teammate_id),summary=firstLine(summary)when non-blank,verified="false"= unverified. The body (trimmed) is an idle notification when it starts with{, parses as a JSON object, and hastype:"idle_notification"and a stringfrom; thenoutcome=failed/was interrupted/finishedforidleReasonfailed/interrupted/ anything else,failureReason= itsfirstLinewhen a non-blank string,result=fullof a non-blank stringresult. Each element's text: idle =from + " " + outcome, then": " + failureReasonwhen present, then"\n" + resultwhen present; plain =summary + "\n" + bodywhen both are non-empty, else whichever is (body capped at 16384 units first).arg= the first 200 units of the distinct senders in order (from,+ " (unverified)"when unverified) joined by", ";result=fullof the element texts joined by"\n\n". The desktop's opt-inrichread draws ateammatepart per element instead (not on the wire). - System (
name:"System") when the kind isauto-continuationorcoordinator: the fallback. - Anything else is not a system record, and the rules above apply unchanged.
The find-bar index (parseTranscriptLines) classifies the same records (string content; a
whitespace-only string is not classified) and indexes the part instead of user text: one
{role:"tool", text:"$ " + name} line (+ " " + arg when arg is non-empty), then
{role:"tool", text: result} when result is non-empty — so an agent's report stays searchable.
Pasted content (the Swift port must replicate this exactly)
A human paste keeps its user bubble, but claude records it inside the typed text in its own grammar
(rht in the 2.1.285 binary): <pasted_content id="XXXX"> + \n + body + \n +
</pasted_content id="XXXX">, where XXXX is exactly four lowercase hex digits ([0-9a-f]) and the
two tags carry the same id. Only that grammar is a span; anything else (no id, another id shape, a
missing newline) is typed text and stays as is. Every user text that reaches a message — string
content that is not a system record or a local command, and each text part of array content whose
text is a string (a non-string text is passed through untouched) — goes through
expandPastedContent (src/shared/chat-system-records.ts):
- The spans are the non-overlapping matches, left to right, of
<pasted_content id="([0-9a-f]{4})">\n([\s\S]*?)\n</pasted_content id="\1">. The body (group 2) ends at the FIRST close marker (\n</pasted_content id="+ the same id +">) that starts at or after the body's first unit — the CLI's ownindexOf. So a close tag with a different id inside a span is content, a same-id open nested inside a span does not extend it, and an empty body is<pasted_content id="XXXX">\n\n</pasted_content id="XXXX">. An open with no such close is left as typed, and scanning resumes one unit after that open. (Implemented linearly: one pass collects every close marker by id, and a per-id pointer only moves forward.) fence= backticks,max(3, L + 1)of them, whereLis the longest run of consecutive backticks in the body (0 when none).- The span is replaced by
"\n" + fence + "\n" + body + "\n" + fence + "\n". Text outside the spans is kept byte for byte.
The find-bar index applies the same transform to the user lines it emits. Titles do NOT: the
recent-conversations list and the transcript index read with expandPastes:false, so a prompt that
starts with a paste still starts with < (and is skipped as a title), and no title carries a fence.
Queued prompts (the Swift port must replicate this exactly)
A prompt the user submits while a turn is running is never a user record. Claude Code hands it to
the model at the next tool boundary of the SAME turn as an attachment record whose
attachment.type is queued_command (measured on 2.1.281–2.1.285). Most queued attachments are not
the user typing: task notifications and peer or coordinator messages queue the same way. An
attachment record becomes ONE user message, at its own line (key = its offset, at = its
timestamp), only when all of these hold (queuedHumanPrompt, src/core/transcript-reader.ts):
attachment.typeisqueued_commandandattachment.commandModeis"prompt";attachment.isMetais nottrue;attachment.originis absent/null, or an object whosekindis"human";- its text is not empty after trimming. The text is
attachment.promptwhen it is a string; when it is an array, thetextof each element whosetypeistextand whosetextis a string, non-empty ones joined by\n; otherwise empty.
The text then goes through expandPastedContent like any other user text (see Pasted content),
and the find-bar index emits the same user line. Every other attachment yields nothing.
Abandoned prompts (the Swift port must replicate this exactly)
A transcript is a tree: each record names its parentUuid, and the model is sent the chain from the
newest record back to the root. When a prompt's request is cancelled before anything answers it
(Esc on a queued prompt, or Esc right after sending, which puts the text back in the input), Claude
Code leaves the prompt in the file and attaches the next prompt to the SAME parent. The model never
saw the cancelled one, so parseChatRecords (abandonedPromptUuids) skips it, on the paged and
unpaged paths alike, before every other rule (it pushes nothing and moves no clock).
Over the records of the read (a paged read: the window's complete lines), a record is skipped when all of these hold:
typeis"user",isSidechainis nottrueandisMetais nottrue;uuidandparentUuidare both strings;- its
message.contentis a non-blank string (JStrim), or an array that has an element withtype:"text"and a non-empty stringtextand no element withtype:"tool_result"; - no record in the read has
parentUuidequal to itsuuid(any record type counts); - a LATER record in the read has the same
parentUuid,type"user"or"assistant",isSidechainnottrue, a differentuuid, and amessage.contentthat is NOT an array holding an element withtype:"tool_result".
The last clause of rule 5 is measured: a prompt typed while a tool call is pending interrupts the call, and Claude Code attaches the prompt and the call's tool-result record to the same parent (the interrupt marker and the answer hang off the result). That prompt has no child and a later sibling, yet the request that follows carries its text.
Both checks see only the read's records, so on a paged read a sibling in a NEWER window is not seen and the prompt is shown, exactly as before this rule. Measured over 133 real transcripts (5,886 prompts): 6 records match, and the model received none of them. A second set (306 transcripts, 2,899 prompts) gave 9 matches before the tool-result clause, one of them the answered prompt above, and 8 after it.
Renderer rules that follow from these records (desktop; iOS notes)
- Turn grouping (
assistantTurnEnds,src/renderer/lib/chatThread.ts): a message that is an assistant message with exactly ONE tool part namedBackground task,Agent messageorSystem— or, on the desktop'srichread, onlyteammateparts — (isSystemRecordMessage) is a turn BOUNDARY, like a user message: it gets no action row and it splits the assistant runs around it, so answer → notification → reply keeps two Copy rows and two times. A local-command chip (#991) is not a boundary. The phone copies per message (ChatScreen.copyText), not per turn, so it has no grouping to mirror today. - Unconfirmed sends (
unconfirmedSends,src/renderer/lib/chatPaging.ts): a composer send delivered as a bracketed paste may be recorded as ONE<pasted_content>span, which the reader renders fenced. A trailing optimistic send whose trimmed textShas no exact match is therefore also confirmed by a user message whose trimmed text equalsfencePasted(S).trim()(one-for-one, same freshness rule as the exact match). iOSChatPaging.swiftmakes the same second comparison. - Reply detection (iOS only; the desktop has no counterpart): the phone's post-send checks
(
ChatPaging.replyArrived,ChatScreen.replyFacts) look for an assistant message after the sent prompt. A system-record chip (theisSystemRecordMessageshape above) is assistant-role only because the wire has no other role for it; it is not the agent's reply, so it is never counted as one.
Sizes
Most inputs are a few KB. Three inputs have to be larger than a page to exercise paging:
tools-cross-page (290 KB), 790 KB, which is one 512 KB page plus one 256 KB tail by
construction) and utf8-edge (huge-last-line (~1.1 MB). Their filler is deterministic lorem ipsum, and the
base64 image is generated by a seeded generator.
Other agents
Each agent with its own reader keeps its fixtures in a subdirectory with its own README, generated by its own test; the pager and step format are the ones above.
codex/— codex rollouts (src/core/codex-chat.ts,src/core/codex-chat-fixtures.test.ts).gemini/— gemini session files (src/core/gemini-chat.ts), one capped page; see its README.grok/— grokchat_history.jsonl(src/core/grok-chat.ts), one capped page; see its README.opencode/— syntheticopencode exportdocuments (src/core/opencode-chat.ts), one page; seeopencode/README.mdand the "opencode" section below.copilot/— copilot session journals (src/core/copilot-chat.ts); its rules are the "Copilot" section below.
Copilot (copilot/)
The same contract for GitHub Copilot CLI's reader (src/core/copilot-chat.ts). Its session journal
is <COPILOT_HOME>/session-state/<sessionId>/events.jsonl (COPILOT_HOME defaults to
~/.copilot; the snap package writes under ~/snap/copilot-cli/common/.copilot), one session
event per line in the envelope {type, data, [agentId], id, timestamp, parentId}. The record
shapes were measured on copilot 1.0.88 (a real CLI run in BYOK mode against a local fake model,
so every byte of content was synthetic) and cross-checked against the CLI's own
schemas/session-events.schema.json. The inputs here are synthetic too.
UPDATE_CHAT_FIXTURES=1 npx vitest run src/core/copilot-chat-fixtures.test.ts
| path | what it is |
|---|---|
copilot/inputs/<name>.jsonl |
A synthetic copilot session journal. |
copilot/expected/<name>.pages.json |
The page sequence, in exactly the format of the claude set above. |
The pager and the window rules are the claude ones, byte for byte (256 KiB tail, 512 KiB older
pages, ×4 growth to 5 MiB, one lookbehind byte, olderCursor, noCompleteLine): the journal is
append-only JSONL (compaction APPENDS session.compaction_* events; measured), so core reuses
parseChatWindow and parseGrowingWindow with copilot's record parser. key is the line's
absolute byte offset, a tool part's id is the call id, both only on a paged read.
Record rules (the Swift port must replicate this exactly)
parseCopilotRecords, applied to each complete line in order:
- A blank line is ignored. A line that is not JSON, not a JSON object, has no string
typeor no objectdatais skipped (and counted in the reader's diagnosticskipped, which is never on the wire). - Sub-agent events are dropped, by the CLI's own test: a non-empty string
agentIdon the envelope, OR a non-empty stringdata.agentId, OR a non-empty stringdata.parentToolCallId. A sub-agent's turns belong to thetaskcall whose result the main thread already shows. at=Date.parse(timestamp)in epoch ms when the envelope'stimestampis a parseable non-empty string, else absent.user.message:data.contentmust be a string (else skipped). It becomes{role:"user", parts:[{kind:"text", text: content}]}(verbatim, untrimmed) only whencontent.trim()is non-empty AND the source is one copilot's own timeline shows:data.sourceabsent,null,"user", or a string starting withcommand-,schedule-orautopilot-. Any other source (skill-*injections,agent-*inter-agent prompts, a non-string) is hidden.transformedContent(the model-facing text with injected datetime/instructions) andattachmentsare never read.assistant.message:data.content(absent ornull="") must be a string anddata.toolRequests(absent ornull=[]) an array, else the record is skipped. On a paged read,modelis set todata.modelwhen it is a string of 1..100 UTF-16 units and CLEARED otherwise, for every main-threadassistant.message(so the newest one decides, even one that yields no parts; never carried forward). Parts, in order: a text part whencontent.trim()is non-empty (text verbatim); then per request, which must be an object with non-empty stringnameandtoolCallId(else that one request is skipped):{kind:"tool", name, arg}, plusid: toolCallIdwhen paged. Pushed as an assistant message only when it has parts.reasoningText,reasoningOpaque,encryptedContentand theassistant.reasoningevent are never read.- The
argrule:argumentsa string (acustomtool such asapply_patch) → its first 200 UTF-16 units. A plain object → the first ofcommand,path,file_path,pattern,url,query,description,prompt,skill,question,intentwhose value is a NON-EMPTY STRING (a non-string under an earlier key does not stop the search), first 200 units, untrimmed. Anything else →"". tool.user_requested(a tool the USER ran,!cmdshell mode being abashcall): non-empty stringtoolNameandtoolCallIdrequired (else skipped). WithtoolName === "bash"and a stringarguments.command:{kind:"tool", name:"!", arg: command.trim().slice(0, 200)}— the claude!line's shape. Otherwise{kind:"tool", name: toolName, arg: <arg rule>}.idwhen paged. Pushed as its own assistant message. (Schema-derived:-pmode cannot produce it, so this shape was not captured from a live run.)tool.execution_complete: non-empty stringtoolCallIdrequired (else skipped). Witherror=data.error.messageif a string else"", andcontent=data.result.contentif a string else"": the text is"Error: " + errorwhendata.success !== trueanderroris non-empty, elsecontent.result= that text split on\n, the first three lines joined by a space, the first 500 UTF-16 units (claude'ssummarizeResult). An empty result sets nothing. Otherwise it is set on the tool part registered under that call id (a later completion overwrites; a later registration of the same id replaces the earlier part as the target); with no such part, a paged read carries it inunmatchedResults(JSMaporder: first insertion wins the position, a later one the value).session.error/session.warning/session.info:data.messagemust be a string (else skipped); pushed as an assistant text part"Error: "/"Warning: "/"Info: "+ message — the same three notices copilot's own chat adapter (ACP) emits.- Every other type yields nothing and is not counted:
session.start/resume/shutdown,system.message(the ~44 KB system prompt), turn boundaries, permissions, hooks,abort, compaction, model/mode/plan changes,system.notification,skill.invoked,subagent.*,session.binary_asset,tool.execution_start, and any type a newer CLI adds. effortis never set: copilot records no per-response effort.
| fixture | pins |
|---|---|
plain-turns |
Prompts and markdown answers, non-ASCII, two assistant messages in one turn, a resume and a model change in between (the second model wins); the system prompt and all bookkeeping yield nothing. |
tools |
Nine tool calls: the arg rule per tool (bash→command, view/create/edit→path, grep→pattern, sql→query before description, apply_patch's raw string, read_bash→"", a 200-unit cap), a denied call's Error: result, a >3-line result, a 500-unit cap, an empty result (no key), and a failure with no error message falling back to its content. |
tools-cross-page |
A call in the older page, its completion in the tail: the tail carries it in unmatchedResults, the older page has the tool part with its id and no result. |
subagent |
A task call with a sub-agent's full event run (envelope agentId, its own prompt, messages, tool calls and model): only the task part and its result reach the thread. |
notices |
session.error / session.warning / session.info rendered; abort, compaction, notifications, skill bodies, context/plan/mode changes, hooks, binary assets and an unknown type rendered as nothing. |
hidden-prompts |
Which source values show a prompt, and that blank prompts, the empty autopilot continuation and attachments add nothing. |
reasoning |
No reasoning, on the event or on a message; a reasoning-only message and a whitespace-only message yield nothing. |
model |
The newest main-thread message's model; a newer sub-agent message does not count. |
model-absent |
The newest main-thread message states no model: the key is absent (not carried forward). |
model-utf16 |
50 × U+1F9EA (exactly 100 UTF-16 units) is kept. |
model-over-cap |
101 units: absent. |
user-requested |
A user ! bash command (name:"!", trimmed arg) and a user-requested view, each with its result. |
malformed |
Thirteen unreadable or ill-shaped lines, plus a good message holding two bad tool requests, between good ones: the good ones render, and a bad tool request costs only itself. |
huge-last-line |
A tool result carrying an image for the model (~300 KB) is the last line: the tail grows past 256 KiB and the result still attaches. |
opencode
opencode/ holds the fixtures for the opencode reader (src/core/opencode-chat.ts): synthetic
opencode export documents and the parse + page the desktop serves for each. opencode has no
transcript file (SQLite since 1.18), so a read is ONE page (olderCursor: null). Its rules and
layout are in opencode/README.md; regenerate with
UPDATE_CHAT_FIXTURES=1 npx vitest run src/core/opencode-chat.fixtures.test.ts.