@spexcode/transcript 0.7.0-next.0

package/dist/frames.d.ts

@@ -0,0 +1,44 @@
+import { type TranscriptRead, type TranscriptReader, type TranscriptTool, type TranscriptTurn } from './turns.js';
+export type StreamTool = Readonly<Omit<TranscriptTool, 'output'> & {
+    output?: null;
+}>;
+export type StreamTurn = Readonly<Omit<TranscriptTurn, 'tools'> & {
+    tools?: readonly StreamTool[];
+}>;
+export type StreamFrame = Readonly<Omit<TranscriptRead, 'turns'> & {
+    kind: 'full' | 'delta';
+    turns: readonly StreamTurn[];
+    removed?: readonly string[];
+}>;
+export type TranscriptErrorFrame = Readonly<{
+    revision: string;
+    from: number;
+    to: number;
+    error: string;
+    reason: string;
+}>;
+export type TranscriptFrame = StreamFrame | TranscriptErrorFrame;
+export declare const isErrorFrame: (frame: TranscriptFrame) => frame is TranscriptErrorFrame;
+export declare const ABSENT_REVISION = "absent";
+export declare const withheld: (read: TranscriptRead) => Omit<StreamFrame, "kind">;
+export declare class FrameProducer {
+    private primed;
+    private sent;
+    private counters;
+    next(read: TranscriptRead): StreamFrame | null;
+    reset(): void;
+}
+export declare const absentFrame: (from: number, to: number) => StreamFrame;
+export type FrameStream = Readonly<{
+    publish(now?: number): Promise<TranscriptFrame | null>;
+    close(): void;
+}>;
+export declare function openFrameStream(reader: TranscriptReader, threadId: string, from: number, clock?: () => number): FrameStream;
+export type HeldTranscript = Readonly<{
+    turns: readonly StreamTurn[];
+}>;
+export type MergedFrame = Readonly<{
+    state: HeldTranscript;
+    payload: TranscriptErrorFrame | (Omit<StreamFrame, 'kind' | 'removed'>);
+}>;
+export declare function mergeTranscriptFrame(state: HeldTranscript, frame: TranscriptFrame): MergedFrame;

package/dist/frames.js

@@ -0,0 +1,85 @@
+import { TranscriptReadError } from './turns.js';
+export const isErrorFrame = (frame) => 'error' in frame;
+// The revision an absent source reports: the thread has not started writing. Not an error.
+export const ABSENT_REVISION = 'absent';
+export const withheld = (read) => ({
+    ...read,
+    turns: read.turns.map((turn) => turn.tools
+        ? { ...turn, tools: turn.tools.map((tool) => tool.output === undefined ? tool : { ...tool, output: null }) }
+        : turn),
+});
+// THE PRODUCER'S HALF. Feed it every read of the open interval; it returns the frame that read is worth — the
+// first one is the whole interval (`full`), every later one a `delta` holding only the turns that are new or
+// changed since the previous frame (a turn changes when a call in it gains its result) and the ids the turn cap
+// evicted; the counters are always absolute — or `null` when the read changed nothing the subscriber holds.
+export class FrameProducer {
+    primed = false; // a `full` frame has been delivered on this stream
+    sent = new Map(); // turn id → the serialized turn the subscriber holds
+    counters = ''; // the absolute counters as last sent
+    next(read) {
+        const held = withheld(read);
+        const next = new Map(held.turns.map((turn) => [turn.id, JSON.stringify(turn)]));
+        const changed = held.turns.filter((turn) => this.sent.get(turn.id) !== next.get(turn.id));
+        const removed = [...this.sent.keys()].filter((turnId) => !next.has(turnId));
+        const counters = `${held.truncated}:${held.omittedTurns}:${held.omittedBytes}:${held.outOfOrderEvents}`;
+        if (this.primed && !changed.length && !removed.length && counters === this.counters)
+            return null;
+        const frame = this.primed ? { ...held, kind: 'delta', turns: changed, removed } : { ...held, kind: 'full' };
+        this.sent = next;
+        this.counters = counters;
+        this.primed = true;
+        return frame;
+    }
+    // the next frame is `full` again — a subscriber that reconnects, or a source that vanished, holds nothing
+    reset() { this.primed = false; this.sent = new Map(); this.counters = ''; }
+}
+export const absentFrame = (from, to) => ({ kind: 'full', revision: ABSENT_REVISION, from, to, turns: [], truncated: false, omittedTurns: 0, omittedBytes: 0, outOfOrderEvents: 0 });
+export function openFrameStream(reader, threadId, from, clock = () => Date.now()) {
+    let last;
+    let tail = null; // opened on the first non-absent revision
+    const producer = new FrameProducer();
+    return {
+        async publish(now = clock()) {
+            const revision = reader.revision(threadId) ?? ABSENT_REVISION;
+            if (revision === last)
+                return null;
+            last = revision;
+            const to = Math.max(from + 1, now);
+            if (revision === ABSENT_REVISION) {
+                producer.reset();
+                return absentFrame(from, to);
+            }
+            try {
+                return producer.next(await (tail ??= reader.tail(threadId, from)).advance(to));
+            }
+            catch (error) {
+                if (!(error instanceof TranscriptReadError))
+                    throw error;
+                return { revision, from, to, error: error.message, reason: error.reason };
+            }
+        },
+        close() { tail?.close(); tail = null; },
+    };
+}
+export function mergeTranscriptFrame(state, frame) {
+    if (isErrorFrame(frame))
+        return { state, payload: frame };
+    const { kind, removed, turns: incoming, ...rest } = frame;
+    if (kind !== 'delta') {
+        const turns = [...(incoming || [])];
+        return { state: { turns }, payload: { ...rest, turns } };
+    }
+    const gone = new Set(removed || []);
+    const turns = state.turns.filter((turn) => !gone.has(turn.id));
+    const index = new Map(turns.map((turn, at) => [turn.id, at]));
+    for (const turn of incoming || []) {
+        const at = index.get(turn.id);
+        if (at === undefined) {
+            index.set(turn.id, turns.length);
+            turns.push(turn);
+        }
+        else
+            turns[at] = turn;
+    }
+    return { state: { turns }, payload: { ...rest, turns } };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './turns.js';
+export * from './parsers.js';
+export * from './readers.js';
+export * from './frames.js';
+export * from './live.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './turns.js';
+export * from './parsers.js';
+export * from './readers.js';
+export * from './frames.js';
+export * from './live.js';

package/dist/live.d.ts

@@ -0,0 +1,16 @@
+import { type TranscriptRange, type TranscriptRead, type TranscriptReader, type TranscriptTail } from './turns.js';
+import { type Parse } from './parsers.js';
+export declare class LiveTranscript implements TranscriptReader {
+    private readonly parse;
+    readonly threadId: string;
+    private readonly events;
+    private writes;
+    private readonly listeners;
+    constructor(parse: Parse, threadId: string);
+    push(native: unknown): boolean;
+    onChange(listener: () => void): () => void;
+    private own;
+    revision(threadId: string): string | null;
+    read(threadId: string, range: TranscriptRange): Promise<TranscriptRead>;
+    tail(threadId: string, from: number): TranscriptTail;
+}

package/dist/live.js

@@ -0,0 +1,65 @@
+import { TranscriptReadError } from './turns.js';
+import { IntervalCollector } from './parsers.js';
+// THE IN-MEMORY SOURCE. A headless controller already holds the harness's native events as they stream past —
+// Claude's `stream-json` lines, an app-server's notifications — so a transcript need not be re-read from the
+// file the harness also writes. Push each native event here, through the same parser the file reader uses, and
+// this is a `TranscriptReader` like any other: the frame protocol, the interval read, and every renderer work
+// unchanged, and `onChange` lets a producer publish on arrival instead of on a tick. One instance is one thread.
+export class LiveTranscript {
+    parse;
+    threadId;
+    events = [];
+    writes = 0;
+    listeners = new Set();
+    constructor(parse, threadId) {
+        this.parse = parse;
+        this.threadId = threadId;
+    }
+    // `true` when the record meant something to the parser; an unrecognized record is not an error — a native
+    // stream carries plenty the transcript does not show (control replies, usage, the result envelope)
+    push(native) {
+        const event = this.parse(native);
+        if (!event)
+            return false;
+        this.events.push(event);
+        this.writes++;
+        for (const listener of this.listeners)
+            listener();
+        return true;
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    own(threadId) {
+        if (threadId !== this.threadId)
+            throw new TranscriptReadError('missing', `live transcript holds thread ${this.threadId}, not ${threadId}`);
+    }
+    // `null` until the first event lands: the thread has not started, which the frame protocol reads as absent
+    revision(threadId) {
+        this.own(threadId);
+        return this.writes ? `${this.writes}` : null;
+    }
+    async read(threadId, range) {
+        this.own(threadId);
+        const collector = new IntervalCollector(range);
+        for (const event of this.events)
+            collector.add(event);
+        return collector.finish(`${this.writes}`, 'live');
+    }
+    // the cursor is an index into the event list: each advance collects only what was pushed since the last one
+    tail(threadId, from) {
+        this.own(threadId);
+        const collector = new IntervalCollector({ from, to: from });
+        let consumed = 0;
+        return {
+            advance: async (to) => {
+                collector.extend(to);
+                for (; consumed < this.events.length; consumed++)
+                    collector.add(this.events[consumed]);
+                return collector.finish(`${this.writes}`, 'live');
+            },
+            close: () => { },
+        };
+    }
+}

package/dist/parsers.d.ts

@@ -0,0 +1,47 @@
+import { type TranscriptRange, type TranscriptRead } from './turns.js';
+export declare const MAX_TURNS = 200;
+export declare const MAX_OUTPUT_BYTES: number;
+export type MutableTool = {
+    id: string;
+    name: string;
+    input?: string;
+    output?: string;
+    outputLines: number;
+    outputBytes: number;
+};
+export type MutableTurn = {
+    id: string | null;
+    at: number;
+    role: 'user' | 'assistant';
+    text?: string;
+    tools: MutableTool[];
+};
+export type ParsedEvent = {
+    at: number | null;
+    turn: MutableTurn | null;
+    toolOutputs?: readonly {
+        id: string;
+        text: string;
+    }[];
+};
+export type Parse = (value: unknown) => ParsedEvent | null;
+export declare function claudeEvent(value: unknown): ParsedEvent | null;
+export declare function codexEvent(value: unknown): ParsedEvent | null;
+export declare function piEvent(value: unknown): ParsedEvent | null;
+export declare function opencodeEvents(value: unknown): ParsedEvent[];
+export declare class IntervalCollector {
+    readonly turns: MutableTurn[];
+    private readonly byTool;
+    private readonly evicted;
+    private readonly synthesized;
+    sawTimestamp: boolean;
+    omittedTurns: number;
+    omittedBytes: number;
+    outOfOrderEvents: number;
+    private pastRange;
+    private readonly range;
+    constructor(range: TranscriptRange);
+    extend(to: number): void;
+    add(event: ParsedEvent): boolean;
+    finish(revision: string, harness: string): TranscriptRead;
+}

package/dist/parsers.js

@@ -0,0 +1,285 @@
+import { TranscriptReadError } from './turns.js';
+// ONE PARSER PER HARNESS. Each function turns one native record — a line of Claude's project JSONL (which is
+// also exactly what its `--output-format stream-json` prints), a Codex rollout line, a pi session line, an
+// OpenCode export — into the normalized event the interval collector consumes. The same parser serves a file
+// being tailed ([[transcript-reader]]) and an event stream held in memory ([[live-transcript]]): the source is
+// where bytes come from, the parser is what they mean, and neither knows the other.
+export const MAX_TURNS = 200;
+export const MAX_OUTPUT_BYTES = 64 * 1024;
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+const items = (value) => Array.isArray(value) ? value : [];
+const string = (value) => typeof value === 'string' && value.trim() ? value : null;
+const idOf = (value) => {
+    if (!value)
+        return null;
+    for (const key of ['id', 'uuid', 'message_id', 'messageId', 'call_id', 'callId', 'client_id', 'clientId']) {
+        const found = string(value[key]);
+        if (found)
+            return found;
+    }
+    return null;
+};
+const timestamp = (value) => {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    const numeric = Number(value);
+    if (Number.isFinite(numeric))
+        return numeric;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+const at = (value) => {
+    if (!value)
+        return null;
+    for (const key of ['timestamp', 'created_at', 'createdAt', 'created', 'time']) {
+        const candidate = timestamp(value[key]);
+        if (candidate !== null)
+            return candidate;
+    }
+    return null;
+};
+const compact = (value) => {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+};
+const lineCount = (value) => value ? value.split(/\r?\n/).length : 0;
+// --- the four native shapes --------------------------------------------------------------------------------
+export function claudeEvent(value) {
+    const entry = object(value);
+    const message = object(entry?.message);
+    if (!entry || !message)
+        return null;
+    const eventAt = at(entry) ?? at(message);
+    if (eventAt === null)
+        return { at: null, turn: null };
+    if (entry.type === 'user' && message.role === 'user') {
+        const blocks = items(message.content);
+        const text = typeof message.content === 'string'
+            ? string(message.content)
+            : blocks.map((block) => string(object(block)?.text)).filter(Boolean).join('\n') || null;
+        const outputs = blocks.flatMap((block) => {
+            const b = object(block);
+            const id = string(b?.tool_use_id);
+            return b?.type === 'tool_result' && id ? [{ id, text: compact(b?.content ?? '') }] : [];
+        });
+        if (outputs.length)
+            return { at: eventAt, turn: null, toolOutputs: outputs };
+        if (text)
+            return { at: eventAt, turn: { id: idOf(entry) ?? idOf(message), at: eventAt, role: 'user', text, tools: [] } };
+    }
+    if (entry.type === 'assistant' && message.role === 'assistant') {
+        const turn = { id: idOf(entry) ?? idOf(message), at: eventAt, role: 'assistant', tools: [] };
+        for (const blockValue of items(message.content)) {
+            const block = object(blockValue);
+            if (block?.type === 'text')
+                turn.text = [turn.text, string(block.text)].filter(Boolean).join('\n') || undefined;
+            if (block?.type === 'tool_use') {
+                const id = string(block.id) ?? `tool-${turn.tools.length}`;
+                turn.tools.push({ id, name: string(block.name) ?? 'tool', input: block.input === undefined ? undefined : compact(block.input), outputLines: 0, outputBytes: 0 });
+            }
+        }
+        return { at: eventAt, turn };
+    }
+    return null;
+}
+export function codexEvent(value) {
+    const entry = object(value);
+    const payload = object(entry?.payload);
+    if (!entry || !payload)
+        return null;
+    const eventAt = at(payload) ?? at(entry);
+    if (eventAt === null)
+        return { at: null, turn: null };
+    const type = string(payload.type);
+    if ((entry.type === 'event_msg' && type === 'user_message')
+        || (entry.type === 'response_item' && (type === 'message' || type === 'input_message') && payload.role === 'user')) {
+        const text = typeof payload.message === 'string' ? payload.message : compact(payload.message ?? payload.content ?? '');
+        return text ? { at: eventAt, turn: { id: idOf(payload) ?? idOf(entry), at: eventAt, role: 'user', text, tools: [] } } : null;
+    }
+    // commentary AND the final answer are both what the agent said; only structured reasoning stays private
+    if (entry.type === 'event_msg' && type === 'agent_message') {
+        const text = string(payload.message ?? payload.text);
+        return text ? { at: eventAt, turn: { id: idOf(payload) ?? idOf(entry), at: eventAt, role: 'assistant', text, tools: [] } } : null;
+    }
+    if (entry.type === 'response_item' && (type === 'custom_tool_call' || type === 'function_call')) {
+        const id = string(payload.call_id ?? payload.id) ?? 'tool';
+        return { at: eventAt, turn: { id: idOf(payload) ?? idOf(entry), at: eventAt, role: 'assistant', tools: [{ id, name: string(payload.name ?? payload.tool_name) ?? 'tool', input: payload.input === undefined && payload.arguments === undefined ? undefined : compact(payload.input ?? payload.arguments), outputLines: 0, outputBytes: 0 }] } };
+    }
+    if (entry.type === 'response_item' && (type === 'custom_tool_call_output' || type === 'function_call_output')) {
+        const id = string(payload.call_id ?? payload.id);
+        const output = payload.output ?? payload.result ?? '';
+        return id ? { at: eventAt, turn: null, toolOutputs: [{ id, text: compact(output) }] } : null;
+    }
+    return null;
+}
+const blockText = (content) => typeof content === 'string'
+    ? string(content)
+    : items(content).map((block) => string(object(block)?.text)).filter(Boolean).join('\n') || null;
+export function piEvent(value) {
+    const entry = object(value);
+    const message = object(entry?.message);
+    if (!entry || entry.type !== 'message' || !message)
+        return null;
+    const eventAt = at(entry) ?? at(message);
+    if (eventAt === null)
+        return { at: null, turn: null };
+    if (message.role === 'user') {
+        const text = blockText(message.content);
+        return text ? { at: eventAt, turn: { id: idOf(entry) ?? idOf(message), at: eventAt, role: 'user', text, tools: [] } } : null;
+    }
+    if (message.role === 'assistant') {
+        const turn = { id: idOf(entry) ?? idOf(message), at: eventAt, role: 'assistant', tools: [] };
+        for (const blockValue of items(message.content)) {
+            const block = object(blockValue);
+            if (block?.type === 'text')
+                turn.text = [turn.text, string(block.text)].filter(Boolean).join('\n') || undefined;
+            if (block?.type === 'toolCall') {
+                const id = string(block.id) ?? `tool-${turn.tools.length}`;
+                turn.tools.push({ id, name: string(block.name) ?? 'tool', input: block.arguments === undefined ? undefined : compact(block.arguments), outputLines: 0, outputBytes: 0 });
+            }
+        }
+        return { at: eventAt, turn };
+    }
+    if (message.role === 'toolResult') {
+        const id = string(message.toolCallId);
+        return id ? { at: eventAt, turn: null, toolOutputs: [{ id, text: blockText(message.content) ?? compact(message.content ?? '') }] } : null;
+    }
+    return null;
+}
+// OpenCode's export is one JSON document, not a line stream: every message arrives with its parts, and a tool
+// part already carries its own result — so its turn is complete on arrival, and a part still running simply has
+// no output yet.
+export function opencodeEvents(value) {
+    const events = [];
+    for (const messageValue of items(object(value)?.messages)) {
+        const message = object(messageValue);
+        const info = object(message?.info);
+        if (!message || !info)
+            continue;
+        const eventAt = at(object(info.time)) ?? at(info);
+        if (eventAt === null) {
+            events.push({ at: null, turn: null });
+            continue;
+        }
+        const role = info.role === 'user' ? 'user' : info.role === 'assistant' ? 'assistant' : null;
+        if (!role)
+            continue;
+        const turn = { id: idOf(info) ?? idOf(message), at: eventAt, role, tools: [] };
+        for (const partValue of items(message.parts)) {
+            const part = object(partValue);
+            if (part?.type === 'text')
+                turn.text = [turn.text, string(part.text)].filter(Boolean).join('\n') || undefined;
+            if (part?.type === 'tool' && role === 'assistant') {
+                const state = object(part.state);
+                const status = (string(state?.status) ?? '').toLowerCase();
+                const tool = { id: string(part.callID ?? part.id) ?? `tool-${turn.tools.length}`, name: string(part.tool) ?? 'tool', input: state?.input === undefined ? undefined : compact(state.input), outputLines: 0, outputBytes: 0 };
+                if (/completed|error|cancelled/.test(status)) {
+                    const output = compact(state?.output ?? state?.error ?? '');
+                    tool.output = output.slice(0, MAX_OUTPUT_BYTES);
+                    tool.outputBytes = Buffer.byteLength(output);
+                    tool.outputLines = lineCount(output);
+                }
+                turn.tools.push(tool);
+            }
+        }
+        if (role === 'user' && !turn.text)
+            continue;
+        events.push({ at: eventAt, turn });
+    }
+    return events;
+}
+// --- reading an interval ------------------------------------------------------------------------------------
+// Collects the interval's turns from any event source. Caps keep the NEWEST turns, because a live tail and a
+// closed stretch are both read for what happened last; every dropped turn or byte is counted, never hidden.
+export class IntervalCollector {
+    turns = [];
+    byTool = new Map();
+    evicted = new Set();
+    synthesized = new Map(); // `<role>@<at>` → how many turns already wore it
+    sawTimestamp = false;
+    omittedTurns = 0;
+    omittedBytes = 0;
+    outOfOrderEvents = 0;
+    pastRange = false;
+    range;
+    constructor(range) { this.range = { from: range.from, to: range.to }; }
+    // the open interval's end is "now" and moves; extending it never revisits what was already collected
+    extend(to) { if (to > this.range.to)
+        this.range.to = to; }
+    // returns true once the source has moved past `to` (the caller may then bound its lookahead)
+    add(event) {
+        const eventAt = event.at;
+        if (eventAt === null)
+            return this.pastRange;
+        this.sawTimestamp = true;
+        if (!this.pastRange && eventAt > this.range.to)
+            this.pastRange = true;
+        else if (this.pastRange && eventAt <= this.range.to)
+            this.outOfOrderEvents++;
+        if (eventAt < this.range.from || eventAt > this.range.to)
+            return this.pastRange;
+        if (event.toolOutputs) {
+            for (const output of event.toolOutputs) {
+                const bytes = Buffer.byteLength(output.text);
+                const tool = this.byTool.get(output.id);
+                if (!tool || this.evicted.has(output.id)) {
+                    this.omittedBytes += bytes;
+                    continue;
+                }
+                tool.outputBytes += bytes;
+                tool.outputLines += lineCount(output.text);
+                if (tool.output === undefined)
+                    tool.output = '';
+                const remaining = Math.max(0, MAX_OUTPUT_BYTES - Buffer.byteLength(tool.output));
+                tool.output += output.text.slice(0, remaining);
+                if (bytes > remaining)
+                    this.omittedBytes += bytes - remaining;
+            }
+        }
+        else if (event.turn) {
+            // the parsed event is never written to: an in-memory source ([[live-transcript]]) collects the same
+            // event again on every read, so the collector works on its own copy of the turn and its calls
+            const turn = { ...event.turn, tools: event.turn.tools.map((tool) => ({ ...tool })) };
+            // a turn without a native id gets one from its place in the thread — deterministic across re-reads of an
+            // append-only source, which is what lets a subscriber match it between frames
+            if (turn.id === null) {
+                const base = `${turn.role}@${turn.at}`;
+                const seen = this.synthesized.get(base) ?? 0;
+                this.synthesized.set(base, seen + 1);
+                turn.id = seen ? `${base}#${seen}` : base;
+            }
+            this.turns.push(turn);
+            for (const tool of turn.tools)
+                this.byTool.set(tool.id, tool);
+            if (this.turns.length > MAX_TURNS) {
+                const dropped = this.turns.shift();
+                for (const tool of dropped.tools)
+                    this.evicted.add(tool.id);
+                this.omittedTurns++;
+            }
+        }
+        return this.pastRange;
+    }
+    finish(revision, harness) {
+        if (!this.sawTimestamp)
+            throw new TranscriptReadError('invalid', `${harness} transcript has no reliable timestamps; interval reads are unavailable`);
+        return {
+            revision,
+            from: this.range.from,
+            to: this.range.to,
+            turns: this.turns.map((turn) => ({ ...turn, id: turn.id, tools: turn.tools.length ? turn.tools.map((tool) => ({ ...tool })) : undefined })),
+            truncated: this.omittedTurns > 0 || this.omittedBytes > 0 || this.outOfOrderEvents > 0,
+            omittedTurns: this.omittedTurns,
+            omittedBytes: this.omittedBytes,
+            outOfOrderEvents: this.outOfOrderEvents,
+        };
+    }
+}

package/dist/readers.d.ts

@@ -0,0 +1,10 @@
+import { type TranscriptReader } from './turns.js';
+export declare function claudeTranscriptPath(threadId: string, root?: string): string | null;
+export declare function codexRolloutPath(threadId: string, root?: string): string | null;
+export declare function piSessionPath(threadId: string, root?: string): string | null;
+export declare const claudeTranscript: TranscriptReader;
+export declare const codexTranscript: TranscriptReader;
+export declare const piTranscript: TranscriptReader;
+export declare function opencodeTranscriptReader(root?: string, load?: (threadId: string) => string): TranscriptReader;
+export declare const opencodeTranscript: TranscriptReader;
+export declare function unsupportedTranscript(harness: string): TranscriptReader;

package/dist/readers.js

@@ -0,0 +1,296 @@
+import { execFileSync } from 'node:child_process';
+import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { TranscriptReadError } from './turns.js';
+import { IntervalCollector, claudeEvent, codexEvent, opencodeEvents, piEvent } from './parsers.js';
+// THE NATIVE-THREAD READERS. Each harness keeps its conversation somewhere private — Claude's project JSONL,
+// Codex's rollout, pi's session JSONL, OpenCode's store behind `opencode export` — and this module is the only
+// place that knows where. It answers exactly one question for every harness: "what happened in this thread
+// between `from` and `to`?", as normalized turns, through the three reader verbs of [[transcript]].
+const POST_RANGE_LOOKAHEAD_LINES = 256;
+const children = (dir) => { try {
+    return readdirSync(dir).sort().reverse();
+}
+catch {
+    return [];
+} };
+// --- where each harness keeps the thread ------------------------------------------------------------------
+const projectTranscriptRoot = () => join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects');
+export function claudeTranscriptPath(threadId, root = projectTranscriptRoot()) {
+    for (const project of children(root)) {
+        const path = join(root, project, `${threadId}.jsonl`);
+        try {
+            if (statSync(path).isFile())
+                return path;
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+const codexSessionsDir = () => join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
+// Walk newest day first and return on the first hit; the walk is exhaustive rather than capped, because
+// future-dated junk under sessions/ sorts above every real day and a cap once masked every real rollout.
+export function codexRolloutPath(threadId, root = codexSessionsDir()) {
+    for (const year of children(root))
+        for (const month of children(join(root, year)))
+            for (const day of children(join(root, year, month))) {
+                const dir = join(root, year, month, day);
+                const file = children(dir).find((name) => name.includes(threadId));
+                if (file)
+                    return join(dir, file);
+            }
+    return null;
+}
+const piSessionsRoot = () => join(process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent'), 'sessions');
+const piSessionPaths = new Map();
+export function piSessionPath(threadId, root = piSessionsRoot()) {
+    const key = `${root}:${threadId}`;
+    const cached = piSessionPaths.get(key);
+    if (cached) {
+        try {
+            if (statSync(cached).isFile())
+                return cached;
+        }
+        catch {
+            piSessionPaths.delete(key);
+        }
+    }
+    for (const directory of children(root))
+        for (const file of children(join(root, directory))) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const path = join(root, directory, file);
+            try {
+                const header = JSON.parse(readFileSync(path, 'utf8').split('\n', 1)[0]);
+                if (header && typeof header === 'object' && header.type === 'session' && header.id === threadId) {
+                    piSessionPaths.set(key, path);
+                    return path;
+                }
+            }
+            catch { /* unreadable entries are not a match */ }
+        }
+    return null;
+}
+const opencodeStoreRoot = () => process.env.SPEXCODE_OPENCODE_DATA_DIR
+    || join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'opencode');
+function opencodeStoreRevision(root) {
+    try {
+        const database = statSync(join(root, 'opencode.db'));
+        let writeAheadLog = '0:0';
+        try {
+            const stat = statSync(join(root, 'opencode.db-wal'));
+            writeAheadLog = `${stat.size}:${Math.floor(stat.mtimeMs)}`;
+        }
+        catch { /* a checkpointed database has no separate write-ahead log */ }
+        return `${database.size}:${Math.floor(database.mtimeMs)}:${writeAheadLog}`;
+    }
+    catch {
+        return null;
+    }
+}
+// The export is read RAW: `--sanitize` replaces every prose and tool-output part with a `[redacted:…]` token,
+// which made the whole conversation unreadable; the reader hands over the same local bytes the other harnesses'
+// files hold, and nothing here leaves the machine that ran the thread.
+function opencodeExport(threadId) {
+    return execFileSync(process.env.SPEXCODE_OPENCODE_CMD || 'opencode', ['export', threadId], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+}
+const fileRevision = (path) => {
+    try {
+        const stat = statSync(path);
+        return `${stat.size}:${Math.floor(stat.mtimeMs)}`;
+    }
+    catch {
+        return null;
+    }
+};
+// @@@interval-seek - a native file is append-only, so the byte where an interval's first event sits never
+// moves. The open tail re-reads its interval on every change; remembering that offset per (file, from) turns
+// each re-read into "parse the current stretch" instead of "parse the whole thread again".
+const intervalOffsets = new Map();
+// One pass over the bytes from `scan.position` to the end of the file. Every complete line is parsed as JSON
+// and handed to `onLine` with its byte offset; `onLine` returning true stops the scan early (a bounded
+// lookahead), which abandons the rest — only a one-shot read does that.
+function scanLines(harness, fd, scan, onLine) {
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let { position, carry } = scan;
+    let lineStart = position - carry.length;
+    while (true) {
+        const read = readSync(fd, chunk, 0, chunk.length, position);
+        if (read <= 0)
+            break;
+        position += read;
+        const buffer = carry.length ? Buffer.concat([carry, chunk.subarray(0, read)]) : Buffer.from(chunk.subarray(0, read));
+        let cut = 0;
+        for (let index = 0; index < buffer.length; index++) {
+            if (buffer[index] !== 10)
+                continue;
+            const line = buffer.subarray(cut, index).toString('utf8');
+            const lineOffset = lineStart;
+            lineStart += index - cut + 1;
+            cut = index + 1;
+            if (!line.trim())
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch (error) {
+                throw new TranscriptReadError('invalid', `${harness} transcript cannot be parsed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (onLine(value, lineOffset))
+                return { position, carry: Buffer.alloc(0) };
+        }
+        carry = Buffer.from(buffer.subarray(cut));
+    }
+    return { position, carry };
+}
+// The cursor over one interval of one line file. A one-shot `read` is a cursor advanced once and dropped; the
+// open interval's `tail` keeps it, so each advance parses only what the harness appended since the last one.
+class LineFileCursor {
+    harness;
+    path;
+    parse;
+    from;
+    collector;
+    scan = { position: 0, carry: Buffer.alloc(0) };
+    started = false;
+    seekKey;
+    constructor(harness, path, parse, from) {
+        this.harness = harness;
+        this.path = path;
+        this.parse = parse;
+        this.from = from;
+        this.seekKey = `${path}\n${from}`;
+        this.collector = new IntervalCollector({ from, to: from });
+    }
+    restart(size) {
+        const seek = intervalOffsets.get(this.seekKey) ?? 0;
+        const start = seek > 0 && seek < size ? seek : 0;
+        this.collector = new IntervalCollector({ from: this.from, to: this.from });
+        // a seek lands on the interval's first event, so the timestamps before it are known to exist
+        if (start > 0)
+            this.collector.sawTimestamp = true;
+        this.scan = { position: start, carry: Buffer.alloc(0) };
+    }
+    advance(to, lookahead = Number.POSITIVE_INFINITY) {
+        let size = 0;
+        try {
+            size = statSync(this.path).size;
+        }
+        catch (error) {
+            throw new TranscriptReadError('unreadable', `${this.harness} transcript is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (size <= 0)
+            throw new TranscriptReadError('unreadable', `${this.harness} transcript is unreadable: file is empty`);
+        // a source that shrank was rewritten underneath the cursor: forget the position and read the interval afresh
+        if (!this.started || size < this.scan.position) {
+            this.restart(size);
+            this.started = true;
+        }
+        this.collector.extend(to);
+        let fd = null;
+        try {
+            fd = openSync(this.path, 'r');
+            let postRangeLines = 0;
+            this.scan = scanLines(this.harness, fd, this.scan, (value, offset) => {
+                const event = this.parse(value);
+                if (!event)
+                    return false;
+                const inRange = event.at !== null && event.at >= this.from && event.at <= to;
+                if (inRange && !intervalOffsets.has(this.seekKey))
+                    intervalOffsets.set(this.seekKey, offset);
+                const pastRange = this.collector.add(event);
+                return pastRange && ++postRangeLines >= lookahead;
+            });
+        }
+        catch (error) {
+            if (error instanceof TranscriptReadError)
+                throw error;
+            throw new TranscriptReadError('unreadable', `${this.harness} transcript could not be read: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            if (fd !== null)
+                closeSync(fd);
+        }
+        return this.collector.finish(fileRevision(this.path) ?? `${size}`, this.harness);
+    }
+}
+function lineFileReader(harness, locate, parse) {
+    const find = (threadId) => {
+        const path = locate(threadId);
+        if (!path)
+            throw new TranscriptReadError('missing', `${harness} transcript for ${threadId} is unavailable: file was not found`);
+        return path;
+    };
+    return {
+        revision: (threadId) => { const path = locate(threadId); return path ? fileRevision(path) : null; },
+        // after passing `to`, a one-shot read scans a fixed lookahead window for timestamp disorder before stopping
+        read: async (threadId, range) => new LineFileCursor(harness, find(threadId), parse, range.from).advance(range.to, POST_RANGE_LOOKAHEAD_LINES),
+        tail: (threadId, from) => {
+            let cursor = null;
+            return {
+                // the file is located on the first advance, so a tail opened before the thread exists fails as `missing`
+                // there rather than at construction
+                advance: async (to) => (cursor ??= new LineFileCursor(harness, find(threadId), parse, from)).advance(to),
+                close: () => { cursor = null; },
+            };
+        },
+    };
+}
+export const claudeTranscript = lineFileReader('claude', (threadId) => claudeTranscriptPath(threadId), claudeEvent);
+export const codexTranscript = lineFileReader('codex', (threadId) => codexRolloutPath(threadId), codexEvent);
+export const piTranscript = lineFileReader('pi', (threadId) => piSessionPath(threadId), piEvent);
+// OpenCode has no per-thread file: the store's revision is the change token, and one export per
+// revision is parsed and kept, so repeated interval reads of a quiet thread cost nothing new.
+const opencodeExports = new Map();
+export function opencodeTranscriptReader(root = opencodeStoreRoot(), load = opencodeExport) {
+    const reader = {
+        revision: () => opencodeStoreRevision(root),
+        read: async (threadId, range) => {
+            const revision = opencodeStoreRevision(root);
+            if (!revision)
+                throw new TranscriptReadError('missing', `opencode transcript for ${threadId} is unavailable: store was not found`);
+            const key = `${root}:${threadId}`;
+            let cached = opencodeExports.get(key);
+            if (!cached || cached.revision !== revision) {
+                let exported;
+                try {
+                    exported = load(threadId);
+                }
+                catch (error) {
+                    throw new TranscriptReadError('unreadable', `opencode transcript could not be exported: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                let value;
+                try {
+                    value = JSON.parse(exported);
+                }
+                catch (error) {
+                    throw new TranscriptReadError('invalid', `opencode transcript cannot be parsed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                cached = { revision, events: opencodeEvents(value) };
+                opencodeExports.set(key, cached);
+            }
+            const collector = new IntervalCollector(range);
+            for (const event of cached.events)
+                collector.add(event);
+            return collector.finish(revision, 'opencode');
+        },
+    };
+    return {
+        ...reader,
+        // no file grows here: an open interval is re-collected from the cached export, which is one export per revision
+        tail: (threadId, from) => ({ advance: (to) => reader.read(threadId, { from, to }), close: () => { } }),
+    };
+}
+export const opencodeTranscript = opencodeTranscriptReader();
+export function unsupportedTranscript(harness) {
+    const refuse = async () => { throw new TranscriptReadError('unsupported', `${harness} does not support transcript access`); };
+    return {
+        revision: () => null,
+        read: refuse,
+        tail: () => ({ advance: refuse, close: () => { } }),
+    };
+}

package/dist/turns.d.ts

@@ -0,0 +1,42 @@
+export type TranscriptRange = Readonly<{
+    from: number;
+    to: number;
+}>;
+export type TranscriptTool = Readonly<{
+    id: string;
+    name: string;
+    input?: string;
+    output?: string;
+    outputLines: number;
+    outputBytes: number;
+}>;
+export type TranscriptTurn = Readonly<{
+    id: string;
+    at: number;
+    role: 'user' | 'assistant';
+    text?: string;
+    tools?: readonly TranscriptTool[];
+}>;
+export type TranscriptRead = Readonly<{
+    revision: string;
+    from: number;
+    to: number;
+    turns: readonly TranscriptTurn[];
+    truncated: boolean;
+    omittedTurns: number;
+    omittedBytes: number;
+    outOfOrderEvents: number;
+}>;
+export type TranscriptTail = Readonly<{
+    advance(to: number): Promise<TranscriptRead>;
+    close(): void;
+}>;
+export type TranscriptReader = Readonly<{
+    revision(threadId: string): string | null;
+    read(threadId: string, range: TranscriptRange): Promise<TranscriptRead>;
+    tail(threadId: string, from: number): TranscriptTail;
+}>;
+export declare class TranscriptReadError extends Error {
+    readonly reason: 'unsupported' | 'missing' | 'unreadable' | 'invalid';
+    constructor(reason: 'unsupported' | 'missing' | 'unreadable' | 'invalid', message: string);
+}

package/dist/turns.js

@@ -0,0 +1,11 @@
+// THE NORMALIZED TRANSCRIPT. Every harness keeps its conversation in a private shape; this is the one shape
+// every surface reads instead: user and assistant prose, tool calls with their input, and each call's output
+// once the harness recorded it. Nothing here imports Node, so a browser renderer and a Node reader share it.
+export class TranscriptReadError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'TranscriptReadError';
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@spexcode/transcript",
+  "version": "0.7.0-next.0",
+  "type": "module",
+  "description": "Normalized agent transcripts: one parser per harness, a bounded interval reader over a native thread file or an in-memory event stream, and the full/delta frame protocol every transport and renderer share.",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./frames": "./dist/frames.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}