@spexcode/transcript 0.7.0-next.13 → 0.7.0-next.15

package/dist/parsers.d.ts

@@ -45,6 +45,7 @@ export declare class IntervalCollector {
     private readonly evicted;
     private readonly synthesized;
     sawTimestamp: boolean;
+    sawRecord: boolean;
     omittedTurns: number;
     omittedBytes: number;
     outOfOrderEvents: number;

package/dist/parsers.js

@@ -54,6 +54,28 @@ const compact = (value) => {
 // (Claude's tool_result content, Codex's input_text output blocks, MCP results everywhere) means the text of
 // those blocks, with their line breaks; encoding the block list itself as JSON would show the reader escaped
 // newlines inside a JSON shell. A block that is not text — an image, a reference — is named, not dumped.
+// @@@ a block that is not text is NAMED, with what the producer said about it - the output contract is text,
+// so a picture cannot be carried in it; the honest substitute is a placeholder that says what was there. A
+// bare `[image]` answers none of the questions a person actually has, and both facts worth having are already
+// in the record: the media type when the producer states it (Claude's `source.media_type`, the `data:<mime>;`
+// prefix of Codex's `image_url`) and the size, which base64 always yields. Neither is guessed — an image with
+// no stated type is named `[image 1.2 MB]`, not sniffed from its bytes.
+const KB = 1024;
+const humanBytes = (bytes) => bytes >= KB * KB ? `${(bytes / (KB * KB)).toFixed(1)} MB`
+    : bytes >= KB ? `${Math.round(bytes / KB)} KB` : `${bytes} B`;
+const base64Bytes = (data) => {
+    const body = data.replace(/=+$/, '');
+    return Math.floor((body.length * 3) / 4);
+};
+const blockLabel = (block, type) => {
+    const source = object(block.source);
+    const url = string(block.image_url) ?? string(block.url) ?? string(source?.url);
+    const dataUrl = url && url.startsWith('data:') ? /^data:([^;,]*)[;,]/.exec(url) : null;
+    const mime = string(source?.media_type) ?? string(block.mimeType) ?? string(block.mime_type) ?? (dataUrl ? dataUrl[1] : null);
+    const encoded = string(source?.data) ?? (url && url.startsWith('data:') ? url.slice(url.indexOf(',') + 1) : null);
+    const size = encoded ? ` ${humanBytes(base64Bytes(encoded))}` : '';
+    return `[${mime || type}${size}]`;
+};
 const resultText = (value) => {
     if (typeof value === 'string')
         return value;
@@ -67,10 +89,8 @@ const resultText = (value) => {
         if (text !== null)
             return text;
         const type = string(block.type);
-        if (type === 'image')
-            return '[image]';
         if (type)
-            return `[${type}]`;
+            return blockLabel(block, type);
         return compact(blockValue);
     }).join('\n');
 };
@@ -133,7 +153,14 @@ export function claudeEvent(value) {
             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: [] };
+        // ONE API MESSAGE IS ONE TURN, however many lines Claude wrote it as. It writes one CONTENT BLOCK per
+        // line — prose on one, each tool call on its own — and every line of the same message repeats that
+        // message's `id` while carrying its own `uuid`. Keying on the line made one message up to six turns:
+        // measured over twelve recent threads, 5,077 assistant lines carry only 2,396 distinct message ids, so a
+        // turn count read off the lines is more than twice the truth. Keying on the message id lets the collector
+        // fold the fragments back together with the rule it already has for a re-emitted turn — text kept, calls
+        // merged by their own ids — so nothing here has to accumulate.
+        const turn = { id: idOf(message) ?? idOf(entry), at: eventAt, role: 'assistant', tools: [] };
         for (const blockValue of items(message.content)) {
             const block = object(blockValue);
             if (block?.type === 'text')
@@ -517,6 +544,7 @@ export class IntervalCollector {
     evicted = new Set();
     synthesized = new Map(); // `<role>@<at>` → how many turns already wore it
     sawTimestamp = false;
+    sawRecord = false; // a record this harness's parser RECOGNIZED arrived, with or without a clock
     omittedTurns = 0;
     omittedBytes = 0;
     outOfOrderEvents = 0;
@@ -528,6 +556,7 @@ export class IntervalCollector {
         this.range.to = to; }
     // returns true once the source has moved past `to` (the caller may then bound its lookahead)
     add(event) {
+        this.sawRecord = true;
         const eventAt = event.at;
         if (eventAt === null)
             return this.pastRange;
@@ -600,7 +629,13 @@ export class IntervalCollector {
         return this.pastRange;
     }
     finish(revision, harness) {
-        if (!this.sawTimestamp)
+        // THE CLOCK GATE IS ABOUT THE HARNESS, NOT THE MOMENT. It catches a source whose conversational records
+        // carry no usable time, which makes interval reads impossible. It must NOT catch a thread that has simply
+        // not spoken yet: every Claude transcript opens with clockless bookkeeping (`mode`, `permission-mode`,
+        // `file-history-snapshot`) before its first message — 40 of 40 real threads on this box — and those lines
+        // are not records this parser recognizes at all, so failing on them put an error frame on the page for the
+        // first moments of EVERY new session, which is exactly when someone is watching.
+        if (this.sawRecord && !this.sawTimestamp)
             throw new TranscriptReadError('invalid', `${harness} transcript has no reliable timestamps; interval reads are unavailable`);
         return {
             revision,

package/dist/readers.js

@@ -205,8 +205,13 @@ class LineFileCursor {
         catch (error) {
             throw new TranscriptReadError('unreadable', `${this.harness} transcript is unreadable: ${error instanceof Error ? error.message : String(error)}`);
         }
+        // AN EMPTY FILE IS A THREAD THAT HAS NOT SPOKEN YET, not a broken one. The harness creates the transcript
+        // before it writes the first record, so the moments right after a session starts — exactly when a person is
+        // watching — read as zero bytes. Failing there put an error on the page for a conversation that simply had
+        // not begun. Zero bytes is unambiguous in a way a garbled file is not: there is nothing to misread, so this
+        // is the one place the no-timestamp gate is skipped rather than tripped.
         if (size <= 0)
-            throw new TranscriptReadError('unreadable', `${this.harness} transcript is unreadable: file is empty`);
+            return { revision: fileRevision(this.path) ?? '0', from: this.from, to, turns: [], truncated: false, omittedTurns: 0, omittedBytes: 0, outOfOrderEvents: 0 };
         // 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);
@@ -216,8 +221,9 @@ class LineFileCursor {
         let fd = null;
         try {
             fd = openSync(this.path, 'r');
-            let postRangeLines = 0;
+            let postRangeLines = 0, parsedLines = 0, unparsableLines = 0;
             this.scan = scanLines(fd, this.scan, (value, offset) => {
+                parsedLines++;
                 const event = this.parse(value);
                 if (!event)
                     return false;
@@ -226,7 +232,11 @@ class LineFileCursor {
                     intervalOffsets.set(this.seekKey, offset);
                 const pastRange = this.collector.add(event);
                 return pastRange && ++postRangeLines >= lookahead;
-            }, (bytes) => { this.collector.omittedBytes += bytes; });
+            }, (bytes) => { unparsableLines++; this.collector.omittedBytes += bytes; });
+            // a file in which NOTHING is JSON is not this thread's transcript at all — that is the loud case, and it
+            // stays loud; a file whose lines parse but say nothing conversational yet is simply not started
+            if (!parsedLines && unparsableLines > 0)
+                throw new TranscriptReadError('invalid', `${this.harness} transcript cannot be parsed: no line is JSON`);
         }
         catch (error) {
             if (error instanceof TranscriptReadError)

package/package.json

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