spexcode 0.6.8 → 0.7.0-next.1

package/node_modules/@spexcode/spec-core/templates/spexcode.json

@@ -1,9 +1,8 @@
 {
   "lint": {
-    "governedRoots": ["."]
-  },
-  "dashboard": {
-    "showHeadlessLaunchers": false
+    "governedRoots": [
+      "."
+    ]
   },
   "uploads": {
     "maxBytes": 2147483648,
@@ -19,15 +18,39 @@
   },
   "sessions": {
     "launchers": {
-      "claude": { "harness": "claude", "cmd": "claude" },
-      "claude-headless": { "harness": "claude-headless", "cmd": "claude" },
-      "codex": { "harness": "codex", "cmd": "codex" },
-      "codex-headless": { "harness": "codex-headless", "cmd": "codex --yolo" },
-      "opencode": { "harness": "opencode", "cmd": "opencode" },
-      "opencode-headless": { "harness": "opencode-headless", "cmd": "opencode --auto" },
-      "pi": { "harness": "pi", "cmd": "pi" },
-      "pi-headless": { "harness": "pi-headless", "cmd": "pi" }
+      "claude-headless": {
+        "harness": "claude-headless",
+        "cmd": "claude"
+      },
+      "claude": {
+        "harness": "claude",
+        "cmd": "claude"
+      },
+      "codex-headless": {
+        "harness": "codex-headless",
+        "cmd": "codex --yolo"
+      },
+      "codex": {
+        "harness": "codex",
+        "cmd": "codex"
+      },
+      "opencode-headless": {
+        "harness": "opencode-headless",
+        "cmd": "opencode --auto"
+      },
+      "opencode": {
+        "harness": "opencode",
+        "cmd": "opencode"
+      },
+      "pi-headless": {
+        "harness": "pi-headless",
+        "cmd": "pi"
+      },
+      "pi": {
+        "harness": "pi",
+        "cmd": "pi"
+      }
     },
-    "defaultLauncher": "claude"
+    "defaultLauncher": "claude-headless"
   }
 }

package/node_modules/@spexcode/spec-eval/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-eval",
-  "version": "0.6.8",
+  "version": "0.7.0-next.1",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -26,7 +26,7 @@
     "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/spec-core": "0.6.8"
+    "@spexcode/spec-core": "0.7.0-next.1"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

package/node_modules/@spexcode/spec-forge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-forge",
-  "version": "0.6.8",
+  "version": "0.7.0-next.1",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -22,7 +22,7 @@
     "test": "tsx --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/spec-core": "0.6.8"
+    "@spexcode/spec-core": "0.7.0-next.1"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

package/node_modules/@spexcode/transcript/dist/frames.d.ts

@@ -0,0 +1,46 @@
+import { type TranscriptRead, type TranscriptReader, type TranscriptTool, type TranscriptTurn } from './turns.js';
+export { TranscriptReadError } from './turns.js';
+export type { TranscriptRange, TranscriptRead, TranscriptReader, TranscriptTail, TranscriptTool, 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/node_modules/@spexcode/transcript/dist/frames.js

@@ -0,0 +1,87 @@
+import { TranscriptReadError } from './turns.js';
+// the browser-safe entry is complete on its own: the normalized shape travels with the frames that carry it
+export { 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,50 @@
+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 geminiEvent(value: unknown): ParsedEvent | null;
+export declare function openclawEvent(value: unknown): ParsedEvent | null;
+export declare function hermesEvents(value: unknown): ParsedEvent[];
+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;
+}