Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* The turn-scoped transcript oracle (architecture §2.7, D3).
*
* Claude Code writes `<config>/projects/<slug(realpath cwd)>/<uuid>.jsonl` for the
* session claudish started with `--session-id <uuid>`, and subagents write
* `<uuid>/subagents/agent-<id>.jsonl`. The follower tails both, partial-line safe, and
* reduces the records into the facts the settle rule (`settle-rule.ts`) reads.
*
* Turns are segmented by claudish's OWN deliveries, never by user records: turn N owns
* every record whose byte offset is past N's offset (taken BEFORE delivery) and before
* N+1's offset, so evidence from an earlier turn can never satisfy a later one (C3, H12).
*
* Record shapes are pinned by the phase-2 captures of Claude Code 2.1.290
* (`ai-docs/reports/mcp-magmux-panes/phase2-captures.md`), notably:
* - the witness is a main-chain user record whose text equals the typed line
* (`origin.kind:"human"`; for `/compact` with no `origin`), or a
* `<command-name>/x</command-name>` record;
* - between the last assistant record and `turn_duration` Claude Code writes
* `attachment/prompt_snapshot` and state records, so "directly followed" means "no
* `stop_hook_summary` in between";
* - a background agent is recognised by its RESULT (`toolUseResult.isAsync`), not by
* `run_in_background` in the input — haiku launched one with neither flag set;
* - an `isMeta` user record after the last assistant message is Claude Code waking the
* model itself (the `max_tokens` continuation "Output token limit hit…", the refusal
* companion), so the turn is not over;
* - Read returns `toolUseResult.file {content, startLine, numLines, totalLines}`;
* `offset:0` reports `startLine:0` for content that starts at file line 1, and CRs
* are stripped.
*/
import {
closeSync,
existsSync,
fstatSync,
openSync,
readSync,
readdirSync,
realpathSync,
statSync,
} from "node:fs";
import { join } from "node:path";
import type { SlotStep } from "./contract.js";
import { RECENT_STEP_LIMIT, stepOf } from "./slot-steps.js";
export type Witness =
| { kind: "text"; text: string } // typed plain line or the file-reference instruction (exact)
/** slash command: its `<command-name>` record, or the plain user record of the typed `line` */
| { kind: "command"; name: string; line?: string }
/**
* A prompt a HUMAN typed (the interactive driver, hook-system §7.5): matched by
* provenance, never by text. See `isHumanPrompt`.
*/
| { kind: "human" };
export interface TurnDelivery {
/** absolute path of the turn file the child must Read */
file: string;
/** the exact bytes written to it */
text: string;
}
export interface ReadCoverage {
linesReturned: number;
complete: boolean;
reads: number;
completedAtOffset: number | null;
}
export interface TurnView {
index: number;
acceptedAt: string | null; // ISO of the witness record; null until accepted
acceptedOffset: number | null;
/** assistant text blocks after the witness, in order (excl. isApiErrorMessage); for a file-delivered
* turn only those after the Read result that completed coverage */
assistantText: string[];
lastAssistant: { messageId: string; stopReason: string | null; isApiError: boolean } | null;
turnDurationAfterLast: { pendingBackgroundAgentCount: number | null } | null;
stopHookSummaryAfterLast: boolean;
interruptAfterLast: { forToolUse: boolean } | null;
/** a main-chain user record that wakes the model (task notification, Stop-hook feedback, an isMeta
* continuation) arrived after the last assistant record, and no assistant record followed it yet */
wakingAfterLast: boolean;
/** the latest unresolved tool_use; `input` is the tool's raw input (the question text of an AskUserQuestion) */
pendingTool: { id: string; name: string; input?: unknown } | null;
agentsLaunched: number;
agentsCompleted: number;
backgroundShellsOpen: string[];
apiError: { status: number | null; category: string | null; text: string } | null;
compactions: number;
delivery: { file: string; lines: number } | null;
readCoverage: ReadCoverage;
preambleBytes: number;
/** offset of the last main-chain chat record (user or assistant) of this turn */
lastChatOffset: number | null;
/** a local command's `<local-command-stdout>` after its witness (ANSI removed); null otherwise */
localCommandOutput: string | null;
/** the last RECENT_STEP_LIMIT steps of this turn, oldest first (SlotRow.recent); [] before the first */
recent: SlotStep[];
/**
* Before the witness: the offset of the first main-chain record that shows the model
* working without any prompt of this turn (an assistant record, or a task notification
* waking it). The interactive driver reads it as a re-wake of the turn it settled
* (D23); panes never open a turn ahead of their own delivery and ignore it.
*/
unwitnessedChatOffset: number | null;
}
export interface SessionFacts {
stopHooksSeen: boolean;
provenHookless: boolean;
}
export interface TranscriptView {
availability: "ok" | "absent" | "empty" | "off";
current: TurnView | null;
settledTurns: number;
usage: { tokensIn: number; tokensOut: number };
toolCalls: number;
lastAppendAt: number | null;
session: SessionFacts;
}
/* ───────────────────────────── pure reducer ───────────────────────────── */
interface ReadState {
delivery: TurnDelivery;
fileLines: string[];
required: number;
covered: Set<number>;
reads: number;
readIds: Set<string>;
completedAtOffset: number | null;
lastReadOffset: number | null;
}
interface TurnState {
index: number;
offset: number;
witness: Witness;
acceptedAt: string | null;
acceptedOffset: number | null;
texts: Array<{ offset: number; text: string }>;
lastAssistant: {
messageId: string;
stopReason: string | null;
isApiError: boolean;
offset: number;
} | null;
td: { pendingBackgroundAgentCount: number | null } | null;
stopHookAfterLast: boolean;
interrupt: { forToolUse: boolean } | null;
waking: boolean;
pending: Map<string, string>; // tool_use id → name
pendingInput: Map<string, unknown>; // tool_use id → input
agents: Set<string>;
agentsDone: Set<string>;
shells: Map<string, string>; // backgroundTaskId → command
shellToolIds: Map<string, string>; // tool_use id → command (until its result names the task id)
apiError: TurnView["apiError"];
compactions: number;
read: ReadState | null;
lastChatOffset: number | null;
localOutput: { text: string; offset: number } | null;
/** at most RECENT_STEP_LIMIT, oldest dropped first */
steps: SlotStep[];
unwitnessedChat: number | null;
}
export interface FollowerState {
turns: TurnState[];
usage: Map<string, { in: number; out: number }>;
toolUseIds: Set<string>;
/** main-chain assistant message ids, in first-seen order, each once (the monitor's replies) */
mainAssistantIds: string[];
mainAssistantSeen: Set<string>;
session: SessionFacts;
records: number;
resolvePath: (p: string) => string;
}
export function initialFollowerState(
resolvePath: (p: string) => string = safeRealpath
): FollowerState {
return {
turns: [],
usage: new Map(),
toolUseIds: new Set(),
mainAssistantIds: [],
mainAssistantSeen: new Set(),
session: { stopHooksSeen: false, provenHookless: false },
records: 0,
resolvePath,
};
}
export function safeRealpath(p: string): string {
try {
return realpathSync(p);
} catch {
return p;
}
}
// Transcript records are untyped JSON written by Claude Code; every read below is guarded.
// biome-ignore lint/suspicious/noExplicitAny: raw JSON records, narrowed field by field
type Rec = Record<string, any>;
function contentOf(r: Rec): unknown {
return r.message?.content;
}
/** Text of a user record: a string content, or its text blocks joined. */
export function userText(r: Rec): string {
const c = contentOf(r);
if (typeof c === "string") return c;
if (!Array.isArray(c)) return "";
return c
.filter((b) => b?.type === "text" && typeof b.text === "string")
.map((b) => b.text)
.join("");
}
function hasToolResult(r: Rec): boolean {
const c = contentOf(r);
return Array.isArray(c) && c.some((b) => b?.type === "tool_result");
}
function isMainUser(r: Rec): boolean {
return r.type === "user" && !r.isSidechain;
}
/**
* A local slash command's own records: `<local-command-caveat>`, `<command-name>` and
* `<local-command-stdout>`. Claude Code writes them for a command the user ran in the
* REPL (captured: `/exit` in 2.1.282/2.1.285, `/model`, `/compact` in 2.1.291); they
* never wake the model, so they are never a re-wake of a settled turn.
*/
const LOCAL_COMMAND_RE =
/^\s*<(local-command-caveat|command-name|local-command-stdout|local-command-stderr)>/;
function isLocalCommandText(text: string): boolean {
return LOCAL_COMMAND_RE.test(text);
}
function isTaskNotification(r: Rec): boolean {
return r.origin?.kind === "task-notification" || userText(r).includes("<task-notification>");
}
/**
* A `<task-notification>` Claude Code absorbed into a turn still running: a main-chain
* `attachment` with `attachment.type:"queued_command"` (captured 2.1.263 and 2.1.301). The
* prefix test keeps out a peer `<agent-message>` that merely quotes one.
*/
function queuedTaskNotification(r: Rec): string | null {
const a = r.type === "attachment" ? r.attachment : null;
if (a?.type !== "queued_command" || typeof a.prompt !== "string") return null;
return a.prompt.startsWith("<task-notification>") ? a.prompt : null;
}
function taskIdOf(text: string): string | null {
const m = text.match(/<task-id>([^<]+)<\/task-id>/);
return m ? (m[1] ?? "").trim() : null;
}
/** A `system/local_command` record (2.1.287+ `/color`): the command line or its stdout. */
function isLocalCommandSystem(r: Rec): boolean {
return r.type === "system" && r.subtype === "local_command" && !r.isSidechain;
}
const INTERRUPT_PREFIX = "[Request interrupted by user";
/**
* A prompt a human typed, by PROVENANCE (hook-system §3.2, §7.5): a main-chain user
* record that is not `isMeta`, carries no `tool_result`, and is none of the records
* Claude Code writes on its own — a task notification, a local command's records, an
* interrupt marker, a compact summary. When the record carries `origin` (2.1.290+ always
* does for typed prompts), `origin.kind` must be `"human"`. A background notification
* (`origin.kind: "task-notification"`) therefore never reads as a human turn, so a D23
* re-wake stays the turn it woke.
*/
export function isHumanPrompt(record: Record<string, unknown>): boolean {
const r = record as Rec;
if (!isMainUser(r) || r.isMeta || hasToolResult(r) || r.isCompactSummary) return false;
if (isTaskNotification(r)) return false;
const text = userText(r);
if (!text.trim() || isLocalCommandText(text) || text.startsWith(INTERRUPT_PREFIX)) return false;
const origin = r.origin;
if (origin !== undefined && origin !== null) return origin?.kind === "human";
return true;
}
function matchesWitness(r: Rec, w: Witness): boolean {
if (w.kind === "human") return isHumanPrompt(r);
// Some local commands are written as system records, not user records (captured:
// 2.1.291 `/color yellow` → two `system/local_command` records).
if (w.kind === "command" && isLocalCommandSystem(r))
return String(r.content ?? "").includes(`<command-name>/${w.name}</command-name>`);
if (!isMainUser(r) || hasToolResult(r)) return false;
const text = userText(r);
if (w.kind === "text") return !r.isMeta && text.trim() === w.text.trim();
// `/compact` writes its <command-name> record only AFTER compaction finishes, which takes
// minutes on a real context; the plain record of the typed line is written at submit
// (captured: 2.1.290 and 2.1.291, `"content":"/compact"`, no isMeta), so it is the witness.
if (w.line !== undefined && !r.isMeta && text.trim() === w.line.trim()) return true;
return text.includes(`<command-name>/${w.name}</command-name>`);
}
function recordUsage(state: FollowerState, r: Rec): void {
if (r.type !== "assistant") return;
const m = r.message;
const id = m?.id;
if (typeof id !== "string") return;
const u = m.usage ?? {};
const num = (x: unknown) => (typeof x === "number" && Number.isFinite(x) ? x : 0);
state.usage.set(id, {
in: num(u.input_tokens) + num(u.cache_creation_input_tokens) + num(u.cache_read_input_tokens),
out: num(u.output_tokens),
});
for (const b of m.content ?? [])
if (b?.type === "tool_use" && typeof b.id === "string") state.toolUseIds.add(b.id);
}
function turnFor(state: FollowerState, offset: number): TurnState | null {
for (let i = state.turns.length - 1; i >= 0; i--) {
const t = state.turns[i];
if (t && offset > t.offset) return t;
}
return null;
}
/** Strip a trailing CR: Read returns CRLF files with LF line ends (captured). */
function stripCr(s: string): string {
return s.endsWith("\r") ? s.slice(0, -1) : s;
}
function newReadState(d: TurnDelivery): ReadState {
const fileLines = d.text.split("\n").map(stripCr);
// Read numbers the empty line after a final newline; coverage does not require it.
const required =
fileLines.length > 0 && fileLines[fileLines.length - 1] === ""
? fileLines.length - 1
: fileLines.length;
return {
delivery: d,
fileLines,
required,
covered: new Set(),
reads: 0,
readIds: new Set(),
completedAtOffset: null,
lastReadOffset: null,
};
}
/** Lines a Read result returned, as [fileLineNumber, text] pairs. */
function returnedLines(r: Rec, block: Rec): Array<[number, string]> {
const f = r.toolUseResult?.file;
if (f && typeof f.content === "string") return fileResultLines(f);
return renderedLines(blockText(block));
}
/** `toolUseResult.file`: `offset:0` reports `startLine:0` for content that starts at line 1. */
function fileResultLines(f: Rec): Array<[number, string]> {
const start = Math.max(1, typeof f.startLine === "number" ? f.startLine : 1);
let lines = (f.content as string).split("\n").map(stripCr);
if (typeof f.numLines === "number") lines = lines.slice(0, f.numLines);
return lines.map((t: string, k: number) => [start + k, t]);
}
function blockText(block: Rec): string {
if (typeof block.content === "string") return block.content;
if (Array.isArray(block.content)) return block.content.map((c: Rec) => c?.text ?? "").join("");
return "";
}
/** Fallback: parse the numbered rendering `N\t<line>` (labels start at 0 for offset:0). */
function renderedLines(text: string): Array<[number, string]> {
const out: Array<[number, string]> = [];
let shift = 0;
let first = true;
for (const line of text.split("\n")) {
const m = line.match(/^\s*(\d+)\t(.*)$/);
if (!m) continue;
const label = Number(m[1]);
if (first) {
shift = label === 0 ? 1 : 0;
first = false;
}
out.push([label + shift, stripCr(m[2] ?? "")]);
}
return out;
}
function applyReadUse(state: FollowerState, t: TurnState, block: Rec): void {
if (!t.read || block?.type !== "tool_use" || block.name !== "Read") return;
const fp = block.input?.file_path;
if (typeof fp !== "string") return;
if (state.resolvePath(fp) === state.resolvePath(t.read.delivery.file))
t.read.readIds.add(block.id);
}
function applyReadResult(t: TurnState, r: Rec, block: Rec, offset: number): void {
const rs = t.read;
if (!rs || block?.type !== "tool_result" || !rs.readIds.has(block.tool_use_id)) return;
rs.lastReadOffset = offset;
if (block.is_error) return;
rs.reads++;
for (const [n, text] of returnedLines(r, block)) {
if (n >= 1 && n <= rs.fileLines.length && rs.fileLines[n - 1] === text) rs.covered.add(n);
}
if (rs.completedAtOffset === null && isComplete(rs)) rs.completedAtOffset = offset;
}
function isComplete(rs: ReadState): boolean {
for (let n = 1; n <= rs.required; n++) if (!rs.covered.has(n)) return false;
return true;
}
function applyAssistant(state: FollowerState, t: TurnState, r: Rec, offset: number): void {
const m = r.message ?? {};
const isApiError = r.isApiErrorMessage === true;
t.lastAssistant = {
messageId: String(m.id ?? ""),
stopReason: m.stop_reason ?? null,
isApiError,
offset,
};
t.lastChatOffset = offset;
t.td = null;
t.stopHookAfterLast = false;
t.interrupt = null;
t.waking = false;
t.apiError = isApiError ? apiErrorOf(r) : null;
if (isApiError) return;
const at = typeof r.timestamp === "string" ? r.timestamp : new Date().toISOString();
for (const b of m.content ?? []) {
applyAssistantBlock(state, t, b, offset);
const step = stepOf(b, at);
if (step) {
t.steps.push(step);
if (t.steps.length > RECENT_STEP_LIMIT) t.steps.shift();
}
}
}
function apiErrorOf(r: Rec): TurnView["apiError"] {
const text = (r.message?.content ?? [])
.filter((b: Rec) => b?.type === "text")
.map((b: Rec) => b.text)
.join("");
return {
status: typeof r.apiErrorStatus === "number" ? r.apiErrorStatus : null,
category: typeof r.error === "string" ? r.error : null,
text,
};
}
function applyAssistantBlock(state: FollowerState, t: TurnState, b: Rec, offset: number): void {
if (b?.type === "text" && typeof b.text === "string" && b.text.length > 0) {
t.texts.push({ offset, text: b.text });
return;
}
if (b?.type !== "tool_use" || typeof b.id !== "string") return;
t.pending.set(b.id, String(b.name ?? ""));
t.pendingInput.set(b.id, b.input);
if (b.name === "Bash" && b.input?.run_in_background)
t.shellToolIds.set(b.id, String(b.input?.command ?? ""));
applyReadUse(state, t, b);
}
function applyToolResults(t: TurnState, r: Rec, blocks: Rec[], offset: number): void {
const tur = r.toolUseResult && typeof r.toolUseResult === "object" ? r.toolUseResult : null;
for (const b of blocks) {
if (b?.type !== "tool_result") continue;
t.pending.delete(b.tool_use_id);
t.pendingInput.delete(b.tool_use_id);
// A background agent is recognised by its result, not by run_in_background in its input.
if (tur?.isAsync === true && typeof tur.agentId === "string") t.agents.add(tur.agentId);
if (typeof tur?.backgroundTaskId === "string")
t.shells.set(tur.backgroundTaskId, t.shellToolIds.get(b.tool_use_id) ?? "");
applyReadResult(t, r, b, offset);
}
}
const STDOUT_RE = /^\s*<local-command-(stdout|stderr)>([\s\S]*?)<\/local-command-\1>/;
// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences in local-command output
const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
/**
* A command turn's settle evidence (§2.7): the `<local-command-stdout>` record a LOCAL
* command writes after its `<command-name>` witness, with no assistant message (captured:
* `/compact`, `/model x` in 2.1.291). A command that prompts the model (`/pear`) writes
* none and settles like any other turn.
*/
function applyLocalCommandRecord(t: TurnState, text: string, offset: number): void {
if (t.witness.kind !== "command" || t.lastAssistant || t.localOutput) return;
const m = text.match(STDOUT_RE);
if (!m) return;
t.localOutput = { text: (m[2] ?? "").replace(ANSI_RE, "").trim(), offset };
t.lastChatOffset = offset;
}
function applyNotification(t: TurnState, text: string): void {
const id = taskIdOf(text);
if (!id) return;
if (t.agents.has(id)) t.agentsDone.add(id);
t.shells.delete(id);
}
/**
* Completes the agent or closes the shell only, never waking and never chat activity: the
* attachment rides an API request already in flight, and the assistant record that answers it
* follows (1,133 of 1,134 corpus notification attachments; the other was a file still being
* written).
*/
function applyQueuedNotification(t: TurnState, r: Rec): void {
const text = queuedTaskNotification(r);
if (text) applyNotification(t, text);
}
function applyUser(t: TurnState, r: Rec, offset: number): void {
const c = contentOf(r);
if (Array.isArray(c) && c.some((b) => b?.type === "tool_result")) {
applyToolResults(t, r, c as Rec[], offset);
return;
}
if (r.isCompactSummary) {
t.compactions++;
return;
}
const text = userText(r);
if (isLocalCommandText(text)) {
applyLocalCommandRecord(t, text, offset);
return;
}
if (text.startsWith(INTERRUPT_PREFIX)) {
t.interrupt = { forToolUse: text.includes("for tool use") };
t.pending.clear();
t.pendingInput.clear();
return;
}
if (isTaskNotification(r)) applyNotification(t, text);
if (t.lastAssistant && !t.interrupt) {
t.waking = true;
t.lastChatOffset = offset;
}
}
function acceptIfWitness(t: TurnState, r: Rec, offset: number): void {
if (!matchesWitness(r, t.witness)) return;
t.acceptedAt = typeof r.timestamp === "string" ? r.timestamp : new Date().toISOString();
t.acceptedOffset = offset;
t.lastChatOffset = offset;
}
/** One main-chain assistant message id, once: Claude Code writes one record per content block. */
function noteMainAssistant(state: FollowerState, r: Rec): void {
const id = r.type === "assistant" ? r.message?.id : undefined;
if (typeof id !== "string" || !id) return;
if (state.mainAssistantSeen.has(id)) return;
state.mainAssistantSeen.add(id);
state.mainAssistantIds.push(id);
}
/** Pure: fold one main-transcript record at byte `offset` into the state. */
export function applyRecord(
state: FollowerState,
record: Record<string, unknown>,
offset: number
): FollowerState {
const r = record as Rec;
state.records++;
recordUsage(state, r);
if (r.isSidechain) return state;
noteMainAssistant(state, r);
if (r.type === "system" && r.subtype === "stop_hook_summary") {
state.session.stopHooksSeen = true;
state.session.provenHookless = false;
}
const t = turnFor(state, offset);
if (!t) return state;
if (t.acceptedAt === null) {
acceptIfWitness(t, r, offset);
if (t.acceptedAt === null && t.unwitnessedChat === null && wakesModel(r))
t.unwitnessedChat = offset;
return state;
}
if (r.type === "assistant") applyAssistant(state, t, r, offset);
else if (r.type === "user") applyUser(t, r, offset);
else if (isLocalCommandSystem(r)) applyLocalCommandRecord(t, String(r.content ?? ""), offset);
else if (r.type === "system" && r.subtype === "stop_hook_summary") {
if (t.lastAssistant) t.stopHookAfterLast = true;
} else if (r.type === "system" && r.subtype === "turn_duration") applyTurnDuration(state, t, r);
applyQueuedNotification(t, r); // attachment records only; the predicate rejects every other type
// compact_boundary carries no turn fact; compactions are counted on the isCompactSummary record
return state;
}
/** A main-chain record that shows the model working with no prompt: its reply, or a notification. */
function wakesModel(r: Rec): boolean {
if (r.type === "assistant") return true;
return isMainUser(r) && !hasToolResult(r) && isTaskNotification(r);
}
function applyTurnDuration(state: FollowerState, t: TurnState, r: Rec): void {
const la = t.lastAssistant;
if (!la || t.waking) return;
const p = r.pendingBackgroundAgentCount;
t.td = { pendingBackgroundAgentCount: typeof p === "number" ? p : null };
// `end_turn` → `turn_duration` with no stop_hook_summary between proves the session has no
// Stop hooks (attachments and state records in between are normal: prompt_snapshot, mode, …).
const proves =
!t.stopHookAfterLast && !t.interrupt && la.stopReason === "end_turn" && !la.isApiError;
if (proves && !state.session.stopHooksSeen) state.session.provenHookless = true;
}
/** Fold one subagent record: usage, tool calls, and a Read of the turn file delegated to a subagent. */
export function applySubagentRecord(
state: FollowerState,
record: Record<string, unknown>,
offsetKey: number
): FollowerState {
const r = record as Rec;
recordUsage(state, r);
const t = state.turns[state.turns.length - 1];
if (!t?.read || t.acceptedAt === null) return state;
if (r.type === "assistant") for (const b of r.message?.content ?? []) applyReadUse(state, t, b);
if (r.type === "user" && Array.isArray(contentOf(r)))
for (const b of contentOf(r) as Rec[]) applyReadResult(t, r, b, offsetKey);
return state;
}
/**
* Open turn `t`. Only the newest turn can ever receive a record (offsets only grow and the
* new turn's offset is taken after a poll), so the previous turn's state, which can hold a
* whole task file and every text block, is dropped here rather than kept for the session.
*/
export function openTurnState(
state: FollowerState,
t: { index: number; offset: number; witness: Witness; delivery?: TurnDelivery | null }
): FollowerState {
state.turns.length = 0;
state.turns.push({
index: t.index,
offset: t.offset,
witness: t.witness,
acceptedAt: null,
acceptedOffset: null,
texts: [],
lastAssistant: null,
td: null,
stopHookAfterLast: false,
interrupt: null,
waking: false,
pending: new Map(),
pendingInput: new Map(),
agents: new Set(),
agentsDone: new Set(),
shells: new Map(),
shellToolIds: new Map(),
apiError: null,
compactions: 0,
read: t.delivery ? newReadState(t.delivery) : null,
lastChatOffset: null,
localOutput: null,
steps: [],
unwitnessedChat: null,
});
return state;
}
export function turnView(t: TurnState): TurnView {
const rs = t.read;
let texts = t.texts;
let preambleBytes = 0;
if (rs) {
const cut = rs.completedAtOffset ?? rs.lastReadOffset;
if (cut !== null) {
const before = texts.filter((x) => x.offset < cut);
preambleBytes = before.reduce((n, x) => n + Buffer.byteLength(x.text), 0);
texts = texts.filter((x) => x.offset > cut);
}
}
const pendingEntry = [...t.pending.entries()].pop();
return {
index: t.index,
acceptedAt: t.acceptedAt,
acceptedOffset: t.acceptedOffset,
assistantText: texts.map((x) => x.text),
lastAssistant: t.lastAssistant
? {
messageId: t.lastAssistant.messageId,
stopReason: t.lastAssistant.stopReason,
isApiError: t.lastAssistant.isApiError,
}
: null,
turnDurationAfterLast: t.td,
stopHookSummaryAfterLast: t.stopHookAfterLast,
interruptAfterLast: t.interrupt,
wakingAfterLast: t.waking,
pendingTool: pendingEntry
? { id: pendingEntry[0], name: pendingEntry[1], input: t.pendingInput.get(pendingEntry[0]) }
: null,
agentsLaunched: t.agents.size,
agentsCompleted: [...t.agents].filter((a) => t.agentsDone.has(a)).length,
backgroundShellsOpen: [...t.shells.values()],
apiError: t.apiError,
compactions: t.compactions,
delivery: rs ? { file: rs.delivery.file, lines: rs.fileLines.length } : null,
readCoverage: rs
? {
linesReturned: rs.covered.size,
complete: isComplete(rs),
reads: rs.reads,
completedAtOffset: rs.completedAtOffset,
}
: { linesReturned: 0, complete: true, reads: 0, completedAtOffset: null },
preambleBytes,
lastChatOffset: t.lastChatOffset,
localCommandOutput: t.localOutput?.text ?? null,
recent: [...t.steps],
unwitnessedChatOffset: t.unwitnessedChat,
};
}
/* ───────────────────────────── file tailing ───────────────────────────── */
/**
* Partial-line-safe tail. The remainder after the last newline is kept as BYTES and a
* line is decoded only once it is complete, so a poll that lands inside a multi-byte
* character can never decode either half as U+FFFD; offsets are byte positions.
*/
export class Tail {
offset = 0;
private rest: Buffer = Buffer.alloc(0);
constructor(readonly path: string) {}
/** Read again from byte `offset` (a line start): the next `read()` returns every line from there. */
seek(offset: number): void {
this.offset = Math.max(0, offset);
this.rest = Buffer.alloc(0);
}
/** Read appended bytes; return complete lines with the byte offset each starts at. */
read(): Array<{ offset: number; line: string }> {
let fd: number;
try {
fd = openSync(this.path, "r");
} catch {
return [];
}
try {
const size = fstatSync(fd).size;
if (size <= this.offset) return [];
const chunk = Buffer.alloc(size - this.offset);
const got = readSync(fd, chunk, 0, chunk.length, this.offset);
this.offset += got;
const fresh = chunk.subarray(0, got);
const buf = this.rest.length ? Buffer.concat([this.rest, fresh]) : fresh;
let pos = this.offset - buf.length;
const out: Array<{ offset: number; line: string }> = [];
let start = 0;
let nl = buf.indexOf(0x0a, start);
while (nl >= 0) {
out.push({ offset: pos, line: buf.toString("utf8", start, nl) });
pos += nl + 1 - start;
start = nl + 1;
nl = buf.indexOf(0x0a, start);
}
this.rest = Buffer.from(buf.subarray(start));
return out;
} finally {
closeSync(fd);
}
}
}
export class TranscriptFollower {
private state: FollowerState;
private main: Tail;
private subs = new Map<string, Tail>();
private lastAppend: number | null = null;
private settled = 0;
private savingOff = false;
private clock: () => number;
constructor(
readonly path: string,
readonly subagentsDir: string,
opts: { now?: () => number; resolvePath?: (p: string) => string } = {}
) {
this.state = initialFollowerState(opts.resolvePath);
this.main = new Tail(path);
this.clock = opts.now ?? Date.now;
}
/** Read appended bytes of the main transcript and every subagent file. True when anything was new. */
poll(): boolean {
let any = false;
for (const { offset, line } of this.main.read()) {
any = true;
const rec = parse(line);
// Offsets are 1-based positions past the line start so a record AT the turn offset
// (written after the mark) is strictly greater than it.
if (rec) applyRecord(this.state, rec, offset + 1);
}
if (this.pollSubagents()) any = true;
if (any) this.lastAppend = this.clock();
return any;
}
private subagentFiles(): string[] {
if (!existsSync(this.subagentsDir)) return [];
try {
return readdirSync(this.subagentsDir).filter((f) => f.endsWith(".jsonl"));
} catch {
return [];
}
}
private pollSubagents(): boolean {
let any = false;
for (const f of this.subagentFiles()) {
let tail = this.subs.get(f);
if (!tail) {
tail = new Tail(join(this.subagentsDir, f));
this.subs.set(f, tail);
}
for (const { line } of tail.read()) {
any = true;
const rec = parse(line);
if (rec) applySubagentRecord(this.state, rec, this.main.offset + 1);
}
}
return any;
}
/** Current byte offset of the main transcript (after a poll). The turn boundary. */
size(): number {
return this.main.offset;
}
openTurn(t: {
index: number;
offset: number;
witness: Witness;
delivery?: TurnDelivery | null;
}): void {
openTurnState(this.state, t);
}
/**
* Re-open turn `t` from its own offset and fold its records again. The interactive
* driver does this on a re-wake (D23): it had opened the NEXT turn after the settle,
* so the continuation's records were read into a turn that never accepted them. Usage,
* tool ids and assistant ids are keyed, so folding a record twice counts it once.
*/
rewindTo(t: {
index: number;
offset: number;
witness: Witness;
delivery?: TurnDelivery | null;
}): void {
this.main.seek(t.offset);
openTurnState(this.state, t);
this.poll();
}
markSettled(): void {
this.settled++;
}
/** Main-chain assistant message ids seen so far, in first-seen order, each once. */
assistantMessageIds(): readonly string[] {
return this.state.mainAssistantIds;
}
markSavingOff(): void {
this.savingOff = true;
}
view(): TranscriptView {
const t = this.state.turns[this.state.turns.length - 1] ?? null;
let tokensIn = 0;
let tokensOut = 0;
for (const u of this.state.usage.values()) {
tokensIn += u.in;
tokensOut += u.out;
}
let availability: TranscriptView["availability"];
if (this.savingOff) availability = "off";
else if (!existsSync(this.path)) availability = "absent";
else if (t && t.acceptedAt === null && fileSize(this.path) <= t.offset) availability = "empty";
else if (!t && fileSize(this.path) === 0) availability = "empty";
else availability = "ok";
return {
availability,
current: t ? turnView(t) : null,
settledTurns: this.settled,
usage: { tokensIn, tokensOut },
toolCalls: this.state.toolUseIds.size,
lastAppendAt: this.lastAppend,
session: { ...this.state.session },
};
}
}
/**
* The byte offset of the line holding the LAST human prompt in a transcript, or null
* when it holds none. The interactive driver opens a turn there when it learns a session
* id from a proxy request rather than minting it (`--resume`, `--continue`,
* `--fork-session`, `/clear`): Claude Code writes the prompt before it sends the
* request that names the session, so the prompt is already on disk and is the turn's
* witness.
*/
export function lastHumanPromptOffset(path: string): number | null {
const tail = new Tail(path);
let found: number | null = null;
for (const { offset, line } of tail.read()) {
const rec = parse(line);
if (rec && isHumanPrompt(rec)) found = offset;
}
return found;
}
function fileSize(p: string): number {
try {
return statSync(p).size;
} catch {
return 0;
}
}
function parse(line: string): Record<string, unknown> | null {
if (!line.trim()) return null;
try {
const v = JSON.parse(line);
return v && typeof v === "object" ? (v as Record<string, unknown>) : null;
} catch {
return null;
}
}