spexcode 0.6.7 → 0.7.0-next.0

package/node_modules/@spexcode/transcript/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/node_modules/@spexcode/transcript/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/node_modules/@spexcode/transcript/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/node_modules/@spexcode/transcript/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/node_modules/@spexcode/transcript/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/node_modules/@spexcode/transcript/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/node_modules/@spexcode/transcript/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/node_modules/@spexcode/transcript/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;