@spexcode/transcript 0.7.0-next.0 → 0.7.0-next.2

package/dist/frames.d.ts

@@ -1,4 +1,6 @@
 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;
 }>;

package/dist/frames.js

@@ -1,4 +1,6 @@
 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';

package/dist/parsers.d.ts

@@ -27,7 +27,12 @@ export type ParsedEvent = {
 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 codexAppServerEvent(value: unknown): ParsedEvent | null;
+export declare function codexAppServerStream(): Parse;
 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[];

package/dist/parsers.js

@@ -51,7 +51,7 @@ const compact = (value) => {
     }
 };
 const lineCount = (value) => value ? value.split(/\r?\n/).length : 0;
-// --- the four native shapes --------------------------------------------------------------------------------
+// --- the seven native shapes -------------------------------------------------------------------------------
 export function claudeEvent(value) {
     const entry = object(value);
     const message = object(entry?.message);
@@ -120,6 +120,101 @@ export function codexEvent(value) {
     }
     return null;
 }
+// Codex app-server notifications are a different native stream from rollout lines. Keep this mapping stateless:
+// a caller that needs streamed prose uses codexAppServerStream below, while file and in-memory sources still
+// share the same one-record parser contract.
+export function codexAppServerEvent(value) {
+    const entry = object(value);
+    const params = object(entry?.params);
+    if (!entry || !params || typeof entry.method !== 'string')
+        return null;
+    const item = object(params.item);
+    const method = entry.method;
+    const recognized = method === 'item/agentMessage/delta' || method === 'item/started' || method === 'item/completed';
+    if (!recognized)
+        return null;
+    const eventAt = timestamp(params.emittedAtMs) ?? timestamp(params.startedAtMs) ?? timestamp(params.completedAtMs);
+    if (eventAt === null)
+        return { at: null, turn: null };
+    if (method === 'item/agentMessage/delta') {
+        const id = string(params.itemId);
+        const delta = string(params.delta);
+        return id && delta !== null
+            ? { at: eventAt, turn: { id, at: eventAt, role: 'assistant', text: delta, tools: [] } }
+            : null;
+    }
+    if ((method !== 'item/started' && method !== 'item/completed') || !item)
+        return null;
+    const id = string(item.id);
+    const type = string(item.type);
+    if (!id || !type)
+        return null;
+    if (type === 'userMessage') {
+        const text = blockText(item.content);
+        return text ? { at: eventAt, turn: { id, at: eventAt, role: 'user', text, tools: [] } } : null;
+    }
+    if (type === 'agentMessage') {
+        const text = string(item.text);
+        return { at: eventAt, turn: { id, at: eventAt, role: 'assistant', text: text ?? undefined, tools: [] } };
+    }
+    const toolTypes = new Set(['commandExecution', 'functionCall', 'customToolCall', 'mcpToolCall', 'dynamicToolCall']);
+    if (!toolTypes.has(type))
+        return null;
+    if (method === 'item/started') {
+        const name = type === 'commandExecution' ? 'command'
+            : string(item.name) ?? string(item.tool) ?? (type === 'mcpToolCall' ? 'mcp' : 'tool');
+        const input = item.arguments !== undefined ? item.arguments
+            : item.input !== undefined ? item.input
+                : item.command !== undefined ? item.command
+                    : undefined;
+        return { at: eventAt, turn: { id, at: eventAt, role: 'assistant', tools: [{ id, name, input: input === undefined ? undefined : compact(input), outputLines: 0, outputBytes: 0 }] } };
+    }
+    let output = undefined;
+    if (type === 'commandExecution')
+        output = item.aggregatedOutput;
+    else if (type === 'functionCall' || type === 'customToolCall')
+        output = item.output ?? item.result;
+    else if (type === 'mcpToolCall')
+        output = item.result ?? item.error;
+    else if (type === 'dynamicToolCall')
+        output = item.contentItems ?? item.output ?? item.error;
+    return output === undefined || output === null
+        ? { at: eventAt, turn: null }
+        : { at: eventAt, turn: null, toolOutputs: [{ id, text: compact(output) }] };
+}
+// Agent-message deltas are fragments of one native item. The closure remembers only that item's text and
+// re-emits its native id, allowing IntervalCollector to replace the earlier turn in place.
+export function codexAppServerStream() {
+    const textByItem = new Map();
+    return (value) => {
+        const parsed = codexAppServerEvent(value);
+        if (!parsed)
+            return null;
+        const entry = object(value);
+        const params = object(entry?.params);
+        const item = object(params?.item);
+        if (entry?.method === 'item/agentMessage/delta') {
+            const id = string(params?.itemId);
+            if (!id || !parsed.turn)
+                return parsed;
+            const text = (textByItem.get(id) ?? '') + (parsed.turn.text ?? '');
+            textByItem.set(id, text);
+            return { ...parsed, turn: { ...parsed.turn, text } };
+        }
+        if (item && item.type === 'agentMessage') {
+            const id = string(item.id);
+            if (id) {
+                const text = string(item.text);
+                if (text !== null || !textByItem.has(id))
+                    textByItem.set(id, text ?? '');
+                const turn = parsed.turn;
+                if (turn)
+                    return { ...parsed, turn: { ...turn, text: textByItem.get(id) || undefined } };
+            }
+        }
+        return parsed;
+    };
+}
 const blockText = (content) => typeof content === 'string'
     ? string(content)
     : items(content).map((block) => string(object(block)?.text)).filter(Boolean).join('\n') || null;
@@ -154,6 +249,116 @@ export function piEvent(value) {
     }
     return null;
 }
+export function geminiEvent(value) {
+    const entry = object(value);
+    const message = (entry?.type === 'user' || entry?.type === 'gemini')
+        ? entry
+        : object(items(entry?.messages)[0]) ?? object(items(object(entry?.$set)?.messages)[0]);
+    if (!entry || !message)
+        return null;
+    const eventAt = at(message) ?? at(entry);
+    if (eventAt === null)
+        return { at: null, turn: null };
+    const content = message.content;
+    const blocks = items(content);
+    const outputs = blocks.flatMap((blockValue) => {
+        const block = object(blockValue);
+        const response = object(block?.functionResponse);
+        const id = string(response?.id);
+        return id ? [{ id, text: compact(response?.response ?? '') }] : [];
+    });
+    if (outputs.length)
+        return { at: eventAt, turn: null, toolOutputs: outputs };
+    if (message.type === 'user') {
+        const text = typeof content === 'string' ? string(content) : blocks.map((block) => string(object(block)?.text)).filter(Boolean).join('\n') || null;
+        return text ? { at: eventAt, turn: { id: idOf(message), at: eventAt, role: 'user', text, tools: [] } } : null;
+    }
+    if (message.type === 'gemini') {
+        const turn = { id: idOf(message), at: eventAt, role: 'assistant', tools: [] };
+        if (typeof content === 'string')
+            turn.text = string(content) ?? undefined;
+        for (const callValue of items(message.toolCalls)) {
+            const call = object(callValue);
+            const id = string(call?.id) ?? `tool-${turn.tools.length}`;
+            turn.tools.push({ id, name: string(call?.name) ?? 'tool', input: call?.args === undefined ? undefined : compact(call.args), outputLines: 0, outputBytes: 0 });
+        }
+        if (!turn.text && !turn.tools.length)
+            return null;
+        return { at: eventAt, turn };
+    }
+    return null;
+}
+export function openclawEvent(value) {
+    const entry = object(value);
+    const message = object(entry?.message);
+    if (!entry || entry.type !== 'message' || !message)
+        return null;
+    const eventAt = at(message) ?? at(entry);
+    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 === 'toolResult') {
+        const id = string(message.toolCallId);
+        return id ? { at: eventAt, turn: null, toolOutputs: [{ id, text: blockText(message.content) ?? compact(message.content ?? '') }] } : 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 turn.text || turn.tools.length ? { at: eventAt, turn } : null;
+    }
+    return null;
+}
+export function hermesEvents(value) {
+    const root = object(value);
+    const events = [];
+    for (const messageValue of items(root?.messages)) {
+        const message = object(messageValue);
+        if (!message)
+            continue;
+        const eventAt = at(message);
+        if (eventAt === null) {
+            events.push({ at: null, turn: null });
+            continue;
+        }
+        const role = message.role;
+        if (role === 'user') {
+            const text = string(message.content);
+            if (text)
+                events.push({ at: eventAt, turn: { id: idOf(message), at: eventAt, role: 'user', text, tools: [] } });
+        }
+        else if (role === 'assistant') {
+            const turn = { id: idOf(message), at: eventAt, role: 'assistant', tools: [] };
+            const text = string(message.content);
+            if (text)
+                turn.text = text;
+            for (const callValue of items(message.tool_calls)) {
+                const call = object(callValue);
+                const fn = object(call?.function);
+                const id = string(call?.id) ?? `tool-${turn.tools.length}`;
+                turn.tools.push({ id, name: string(fn?.name) ?? 'tool', input: fn?.arguments === undefined ? undefined : compact(fn.arguments), outputLines: 0, outputBytes: 0 });
+            }
+            if (turn.text || turn.tools.length)
+                events.push({ at: eventAt, turn });
+        }
+        else if (role === 'tool') {
+            const id = string(message.tool_call_id);
+            if (id)
+                events.push({ at: eventAt, turn: null, toolOutputs: [{ id, text: compact(message.content ?? '') }] });
+        }
+    }
+    return events;
+}
 // 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.
@@ -256,14 +461,31 @@ export class IntervalCollector {
                 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++;
+            const existingAt = this.turns.findIndex((candidate) => candidate.id === turn.id);
+            if (existingAt >= 0) {
+                const existing = this.turns[existingAt];
+                const incomingTools = new Map(turn.tools.map((tool) => [tool.id, tool]));
+                const tools = existing.tools.map((tool) => {
+                    const incoming = incomingTools.get(tool.id);
+                    incomingTools.delete(tool.id);
+                    return incoming ? { ...tool, ...incoming, output: incoming.output ?? tool.output } : tool;
+                });
+                tools.push(...incomingTools.values());
+                const replacement = { ...existing, ...turn, text: turn.text ?? existing.text, tools };
+                this.turns[existingAt] = replacement;
+                for (const tool of replacement.tools)
+                    this.byTool.set(tool.id, tool);
+            }
+            else {
+                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;

package/dist/readers.d.ts

@@ -1,10 +1,16 @@
 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 codexRolloutPath(threadId: string, root?: string, archive?: string): string | null;
 export declare function piSessionPath(threadId: string, root?: string): string | null;
+export declare function geminiTranscriptPath(threadId: string, root?: string): string | null;
+export declare function openclawTranscriptPath(threadId: string, root?: string): string | null;
 export declare const claudeTranscript: TranscriptReader;
 export declare const codexTranscript: TranscriptReader;
 export declare const piTranscript: TranscriptReader;
+export declare const geminiTranscript: TranscriptReader;
+export declare const openclawTranscript: TranscriptReader;
 export declare function opencodeTranscriptReader(root?: string, load?: (threadId: string) => string): TranscriptReader;
 export declare const opencodeTranscript: TranscriptReader;
+export declare function hermesTranscriptReader(root?: string, load?: (threadId: string) => string): TranscriptReader;
+export declare const hermesTranscript: TranscriptReader;
 export declare function unsupportedTranscript(harness: string): TranscriptReader;

package/dist/readers.js

@@ -1,9 +1,9 @@
 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 { dirname, join } from 'node:path';
 import { TranscriptReadError } from './turns.js';
-import { IntervalCollector, claudeEvent, codexEvent, opencodeEvents, piEvent } from './parsers.js';
+import { IntervalCollector, claudeEvent, codexEvent, geminiEvent, hermesEvents, openclawEvent, 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
@@ -31,7 +31,10 @@ export function claudeTranscriptPath(threadId, root = projectTranscriptRoot()) {
 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()) {
+// A thread Codex has ARCHIVED (the app-server's thread/archive, which a closed session runs) keeps its
+// rollout, moved out of the dated tree into the flat `archived_sessions/` beside it — a closed session's
+// conversation is still on disk and still readable, so the locator looks there second.
+export function codexRolloutPath(threadId, root = codexSessionsDir(), archive = join(dirname(root), 'archived_sessions')) {
     for (const year of children(root))
         for (const month of children(join(root, year)))
             for (const day of children(join(root, year, month))) {
@@ -40,7 +43,8 @@ export function codexRolloutPath(threadId, root = codexSessionsDir()) {
                 if (file)
                     return join(dir, file);
             }
-    return null;
+    const archived = children(archive).find((name) => name.includes(threadId));
+    return archived ? join(archive, archived) : null;
 }
 const piSessionsRoot = () => join(process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent'), 'sessions');
 const piSessionPaths = new Map();
@@ -72,6 +76,36 @@ export function piSessionPath(threadId, root = piSessionsRoot()) {
         }
     return null;
 }
+const findJsonl = (root, threadId, maxDepth = 5) => {
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return null;
+        for (const name of children(dir)) {
+            const path = join(dir, name);
+            try {
+                if (statSync(path).isFile() && name.endsWith('.jsonl')) {
+                    if (name.includes(threadId))
+                        return path;
+                    const header = JSON.parse(readFileSync(path, 'utf8').split('\n', 1)[0]);
+                    if (header.sessionId === threadId || header.id === threadId)
+                        return path;
+                }
+                else if (statSync(path).isDirectory()) {
+                    const found = walk(path, depth + 1);
+                    if (found)
+                        return found;
+                }
+            }
+            catch { /* skip entries that disappear or are not JSON */ }
+        }
+        return null;
+    };
+    return walk(root, 0);
+};
+const geminiRoot = () => process.env.GEMINI_HOME || process.env.GEMINI_CONFIG_DIR || join(homedir(), '.gemini');
+export function geminiTranscriptPath(threadId, root = geminiRoot()) { return findJsonl(root, threadId); }
+const openclawRoot = () => process.env.OPENCLAW_STATE_DIR || join(homedir(), '.openclaw', 'state');
+export function openclawTranscriptPath(threadId, root = openclawRoot()) { return findJsonl(root, threadId); }
 const opencodeStoreRoot = () => process.env.SPEXCODE_OPENCODE_DATA_DIR
     || join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'opencode');
 function opencodeStoreRevision(root) {
@@ -243,6 +277,8 @@ function lineFileReader(harness, locate, parse) {
 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);
+export const geminiTranscript = lineFileReader('gemini', (threadId) => geminiTranscriptPath(threadId), geminiEvent);
+export const openclawTranscript = lineFileReader('openclaw', (threadId) => openclawTranscriptPath(threadId), openclawEvent);
 // 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();
@@ -286,6 +322,53 @@ export function opencodeTranscriptReader(root = opencodeStoreRoot(), load = open
     };
 }
 export const opencodeTranscript = opencodeTranscriptReader();
+const hermesRoot = () => process.env.HERMES_HOME || join(homedir(), '.hermes', 'profiles', 'default');
+function hermesRevision(root) {
+    try {
+        const stat = statSync(join(root, 'state.db'));
+        return `${stat.size}:${Math.floor(stat.mtimeMs)}`;
+    }
+    catch {
+        return null;
+    }
+}
+function hermesExport(threadId) {
+    return execFileSync(process.env.SPEXCODE_HERMES_CMD || 'hermes', ['sessions', 'export', '--format', 'jsonl', '--session-id', threadId, '--yes'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+const hermesExports = new Map();
+export function hermesTranscriptReader(root = hermesRoot(), load = hermesExport) {
+    const read = async (threadId, range) => {
+        const revision = hermesRevision(root);
+        if (!revision)
+            throw new TranscriptReadError('missing', `hermes transcript for ${threadId} is unavailable: state.db was not found`);
+        const key = `${root}:${threadId}`;
+        let cached = hermesExports.get(key);
+        if (!cached || cached.revision !== revision) {
+            let exported;
+            try {
+                exported = load(threadId);
+            }
+            catch (error) {
+                throw new TranscriptReadError('unreadable', `hermes 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', `hermes transcript cannot be parsed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            cached = { revision, events: hermesEvents(value) };
+            hermesExports.set(key, cached);
+        }
+        const collector = new IntervalCollector(range);
+        for (const event of cached.events)
+            collector.add(event);
+        return collector.finish(revision, 'hermes');
+    };
+    return { revision: () => hermesRevision(root), read, tail: (threadId, from) => ({ advance: (to) => read(threadId, { from, to }), close: () => { } }) };
+}
+export const hermesTranscript = hermesTranscriptReader();
 export function unsupportedTranscript(harness) {
     const refuse = async () => { throw new TranscriptReadError('unsupported', `${harness} does not support transcript access`); };
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/transcript",
-  "version": "0.7.0-next.0",
+  "version": "0.7.0-next.2",
   "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": [