@agentic-kit/run-log 0.5.0 → 0.7.0

package/projectors/events.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The step every projector shares: records → neutral events, in log order.
+ *
+ * Each record names its own transcript format, so this is also where a mixed
+ * log stops being a special case: the reader is chosen per record, and a run
+ * that changed harness projects as one conversation.
+ */
+import type { RunEventRecord } from '../record';
+import type { TranscriptEvent } from '../transcripts/event';
+import type { TranscriptReaderRegistry } from '../transcripts/reader';
+export interface ProjectionOptions {
+    /** Readers to interpret the records with. Defaults to the process registry. */
+    readers?: TranscriptReaderRegistry;
+}
+/** What one record meant, tagged with its position in the run. */
+export interface EventGroup {
+    seq: number;
+    events: TranscriptEvent[];
+}
+/** One event, tagged with the position of the record it came from. */
+export interface SequencedEvent {
+    seq: number;
+    event: TranscriptEvent;
+}
+/**
+ * Read every record with the reader its format names. Grouped by record because
+ * a span asks when the *previous entry* was written, which the flattened stream
+ * can no longer tell you.
+ */
+export declare function toEventGroups(records: readonly RunEventRecord[], options?: ProjectionOptions): EventGroup[];
+export declare function toEvents(records: readonly RunEventRecord[], options?: ProjectionOptions): SequencedEvent[];

package/projectors/events.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * The step every projector shares: records → neutral events, in log order.
+ *
+ * Each record names its own transcript format, so this is also where a mixed
+ * log stops being a special case: the reader is chosen per record, and a run
+ * that changed harness projects as one conversation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEventGroups = toEventGroups;
+exports.toEvents = toEvents;
+const registry_1 = require("../transcripts/registry");
+/**
+ * Read every record with the reader its format names. Grouped by record because
+ * a span asks when the *previous entry* was written, which the flattened stream
+ * can no longer tell you.
+ */
+function toEventGroups(records, options = {}) {
+    const readers = options.readers ?? registry_1.transcriptReaders;
+    return records.map((record) => ({
+        seq: record.seq,
+        events: readers.require(record.transcriptFormat).toEvents(record.entry)
+    }));
+}
+function toEvents(records, options = {}) {
+    return toEventGroups(records, options).flatMap(({ seq, events }) => events.map((event) => ({ seq, event })));
+}

package/projectors/parts.d.ts

@@ -1,14 +1,17 @@
 /**
  * Renderable projection: run log records → an ordered list of parts a UI draws.
  *
- * This is the projection that replaces per-host transcript encodings. A tool
- * call and its later result collapse into one part, so a renderer never has to
- * correlate two messages itself, and an unknown entry type becomes an
- * `unknown` part rather than disappearing — a log written by a newer pi still
- * renders, minus the detail this version understands.
+ * This is the projection that replaces per-host transcript encodings. It reads
+ * neutral transcript events rather than any harness's entries, so a renderer
+ * draws a run without knowing which harness produced it. A tool call and its
+ * later result collapse into one part, so a renderer never has to correlate two
+ * messages itself, and an entry the format's reader does not understand becomes
+ * an `unknown` part rather than disappearing — a log written by a newer harness
+ * still renders, minus the detail this version understands.
  */
 import type { RunEventRecord } from '../record';
-import { type PiSessionEntry } from '../transcripts/pi-entry';
+import type { TranscriptEntry } from '../transcripts/entry';
+import { type ProjectionOptions } from './events';
 export type ToolStatus = 'requested' | 'completed' | 'failed';
 export interface PartBase {
     /** Sequence of the record that introduced the part — a stable React key. */
@@ -59,17 +62,17 @@ export interface SummaryPart extends PartBase {
 export interface UnknownPart extends PartBase {
     kind: 'unknown';
     entryType: string;
-    entry: PiSessionEntry;
+    entry: TranscriptEntry;
 }
 export type ConversationPart = TextPart | ThinkingPart | ToolPart | BashPart | CustomPart | SummaryPart | UnknownPart;
 export interface Conversation {
     parts: ConversationPart[];
-    /** From the session header, when the log carries one. */
+    /** From the transcript's opening entry, when the log carries one. */
     sessionId?: string;
     cwd?: string;
 }
 /**
  * Project records into a conversation. Pure and total: the same records always
- * produce the same parts, whichever host wrote them.
+ * produce the same parts, whichever harness wrote them.
  */
-export declare function projectParts(records: readonly RunEventRecord[]): Conversation;
+export declare function projectParts(records: readonly RunEventRecord[], options?: ProjectionOptions): Conversation;

package/projectors/parts.js

@@ -2,133 +2,116 @@
 /**
  * Renderable projection: run log records → an ordered list of parts a UI draws.
  *
- * This is the projection that replaces per-host transcript encodings. A tool
- * call and its later result collapse into one part, so a renderer never has to
- * correlate two messages itself, and an unknown entry type becomes an
- * `unknown` part rather than disappearing — a log written by a newer pi still
- * renders, minus the detail this version understands.
+ * This is the projection that replaces per-host transcript encodings. It reads
+ * neutral transcript events rather than any harness's entries, so a renderer
+ * draws a run without knowing which harness produced it. A tool call and its
+ * later result collapse into one part, so a renderer never has to correlate two
+ * messages itself, and an entry the format's reader does not understand becomes
+ * an `unknown` part rather than disappearing — a log written by a newer harness
+ * still renders, minus the detail this version understands.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectParts = projectParts;
-const pi_entry_1 = require("../transcripts/pi-entry");
+const events_1 = require("./events");
 /**
  * Project records into a conversation. Pure and total: the same records always
- * produce the same parts, whichever host wrote them.
+ * produce the same parts, whichever harness wrote them.
  */
-function projectParts(records) {
+function projectParts(records, options = {}) {
     const parts = [];
     const toolsByCallId = new Map();
     let sessionId;
     let cwd;
-    for (const record of records) {
-        const { entry, seq } = record;
-        if ((0, pi_entry_1.isPiSessionHeader)(entry)) {
-            sessionId = entry.id;
-            if (typeof entry.cwd === 'string')
-                cwd = entry.cwd;
-            continue;
-        }
-        if ((0, pi_entry_1.isPiCompactionEntry)(entry)) {
-            parts.push({ kind: 'summary', reason: 'compaction', summary: entry.summary, seq, entryId: entry.id });
-            continue;
-        }
-        if ((0, pi_entry_1.isPiBranchSummaryEntry)(entry)) {
-            parts.push({ kind: 'summary', reason: 'branch', summary: entry.summary, seq, entryId: entry.id });
-            continue;
-        }
-        if (!(0, pi_entry_1.isPiMessageEntry)(entry)) {
-            parts.push({ kind: 'unknown', entryType: entry.type, entry, seq, entryId: entry.id });
-            continue;
-        }
-        const message = entry.message;
-        const base = { seq, entryId: entry.id };
-        if (message.role === 'user') {
-            parts.push({ kind: 'text', role: 'user', text: (0, pi_entry_1.contentText)(message.content), ...base });
-            continue;
-        }
-        if ((0, pi_entry_1.isAssistantMessage)(message)) {
-            for (const block of Array.isArray(message.content) ? message.content : []) {
-                if (block.type === 'text' && block.text.length > 0) {
-                    parts.push({
-                        kind: 'text',
-                        role: 'assistant',
-                        text: block.text,
-                        ...(message.model ? { model: message.model } : {}),
-                        ...(message.provider ? { provider: message.provider } : {}),
-                        ...base
-                    });
-                }
-                else if (block.type === 'thinking') {
-                    parts.push({ kind: 'thinking', text: block.thinking, ...base });
-                }
-            }
-            for (const call of (0, pi_entry_1.toolCalls)(message)) {
+    for (const { seq, event } of (0, events_1.toEvents)(records, options)) {
+        const base = { seq, ...(event.entryId === undefined ? {} : { entryId: event.entryId }) };
+        switch (event.kind) {
+            case 'session-start':
+                if (event.sessionId !== undefined)
+                    sessionId = event.sessionId;
+                if (event.cwd !== undefined)
+                    cwd = event.cwd;
+                break;
+            // A model call is a trace and metering concern; its content arrives as the
+            // text and tool-call events that follow it.
+            case 'model-response':
+                break;
+            case 'text':
+                parts.push({
+                    kind: 'text',
+                    role: event.role,
+                    text: event.text,
+                    ...(event.model ? { model: event.model } : {}),
+                    ...(event.provider ? { provider: event.provider } : {}),
+                    ...base
+                });
+                break;
+            case 'thinking':
+                parts.push({ kind: 'thinking', text: event.text, ...base });
+                break;
+            case 'tool-call': {
                 const part = {
                     kind: 'tool',
-                    toolCallId: call.id,
-                    name: call.name,
-                    arguments: call.arguments ?? {},
+                    toolCallId: event.toolCallId,
+                    name: event.name,
+                    arguments: event.arguments,
                     status: 'requested',
                     ...base
                 };
-                toolsByCallId.set(call.id, part);
+                toolsByCallId.set(event.toolCallId, part);
                 parts.push(part);
+                break;
             }
-            continue;
-        }
-        if ((0, pi_entry_1.isToolResultMessage)(message)) {
-            const existing = toolsByCallId.get(message.toolCallId);
-            const output = (0, pi_entry_1.contentText)(message.content);
-            const status = message.isError ? 'failed' : 'completed';
-            if (existing) {
-                existing.status = status;
-                existing.output = output;
-                existing.settledSeq = seq;
-                if (message.details !== undefined)
-                    existing.details = message.details;
+            case 'tool-result': {
+                const existing = toolsByCallId.get(event.toolCallId);
+                const status = event.failed ? 'failed' : 'completed';
+                if (existing) {
+                    existing.status = status;
+                    existing.output = event.output;
+                    existing.settledSeq = seq;
+                    if (event.details !== undefined)
+                        existing.details = event.details;
+                }
+                else {
+                    // A result whose call is not in this window (paged read, forked branch).
+                    parts.push({
+                        kind: 'tool',
+                        toolCallId: event.toolCallId,
+                        name: event.name,
+                        arguments: {},
+                        status,
+                        output: event.output,
+                        settledSeq: seq,
+                        ...base
+                    });
+                }
+                break;
             }
-            else {
-                // A result whose call is not in this window (paged read, forked branch).
+            case 'bash':
                 parts.push({
-                    kind: 'tool',
-                    toolCallId: message.toolCallId,
-                    name: message.toolName,
-                    arguments: {},
-                    status,
-                    output,
-                    settledSeq: seq,
+                    kind: 'bash',
+                    command: event.command,
+                    output: event.output,
+                    ...(event.exitCode === undefined ? {} : { exitCode: event.exitCode }),
                     ...base
                 });
-            }
-            continue;
-        }
-        if (message.role === 'bashExecution') {
-            parts.push({
-                kind: 'bash',
-                command: message.command,
-                output: message.output,
-                ...(typeof message.exitCode === 'number' ? { exitCode: message.exitCode } : {}),
-                ...base
-            });
-            continue;
-        }
-        if (message.role === 'custom') {
-            parts.push({
-                kind: 'custom',
-                customType: message.customType,
-                text: (0, pi_entry_1.contentText)(message.content),
-                display: message.display !== false,
-                ...(message.details !== undefined ? { details: message.details } : {}),
-                ...base
-            });
-            continue;
+                break;
+            case 'custom':
+                parts.push({
+                    kind: 'custom',
+                    customType: event.customType,
+                    text: event.text,
+                    display: event.display,
+                    ...(event.details === undefined ? {} : { details: event.details }),
+                    ...base
+                });
+                break;
+            case 'summary':
+                parts.push({ kind: 'summary', reason: event.reason, summary: event.summary, ...base });
+                break;
+            case 'unknown':
+                parts.push({ kind: 'unknown', entryType: event.entryType, entry: event.entry, ...base });
+                break;
         }
-        parts.push({
-            kind: 'summary',
-            reason: message.role === 'branchSummary' ? 'branch' : 'compaction',
-            summary: message.summary ?? '',
-            ...base
-        });
     }
     return {
         parts,

package/projectors/session.d.ts

@@ -8,6 +8,11 @@
  *
  * Returns a string rather than writing a file: the projection is pure, and the
  * node-side write lives in `@agentic-kit/run-log/file-store`.
+ *
+ * Unlike the other projectors this one is deliberately *not* neutral:
+ * re-emitting a transcript in its native encoding is per-format work, so a
+ * second harness ships its own session projection beside its reader rather than
+ * reusing this. The neutral half of "read a log" is `../transcripts/event`.
  */
 import { type RunEventRecord } from '../record';
 import { type PiSessionEntry } from '../transcripts/pi-entry';

package/projectors/session.js

@@ -9,6 +9,11 @@
  *
  * Returns a string rather than writing a file: the projection is pure, and the
  * node-side write lives in `@agentic-kit/run-log/file-store`.
+ *
+ * Unlike the other projectors this one is deliberately *not* neutral:
+ * re-emitting a transcript in its native encoding is per-format work, so a
+ * second harness ships its own session projection beside its reader rather than
+ * reusing this. The neutral half of "read a log" is `../transcripts/event`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectSession = projectSession;
@@ -29,6 +34,7 @@ function projectSession(records, options = {}) {
         throw new Error(`run log mixes pi session versions (${Array.from(versions).sort().join(', ')}); migrate the older entries before projecting a session`);
     }
     const transcriptVersion = records[0]?.transcriptVersion ?? format_1.SUPPORTED_PI_TRANSCRIPT_VERSION;
+    // Safe: every record was just asserted to carry the pi transcript format.
     const entries = records.map((record) => record.entry);
     const headerIndex = entries.findIndex(pi_entry_1.isPiSessionHeader);
     if (headerIndex > 0) {

package/projectors/spans.d.ts

@@ -3,7 +3,7 @@
  *
  * The log answers *what* happened and the parts projection answers *in what
  * order*, but a trace view asks "how long did this take, and inside what" —
- * questions pi's entries only answer in pairs. Every entry is timestamped, so a
+ * questions a transcript only answers in pairs. Every entry is timestamped, so a
  * tool call and its result, or an approval request and its answer, bracket an
  * interval; nothing new has to be stored to know it.
  *
@@ -16,7 +16,8 @@
  * still in flight must not look like one that finished.
  */
 import type { RunEventRecord } from '../record';
-import { type PiUsage } from '../transcripts/pi-entry';
+import type { TranscriptUsage } from '../transcripts/event';
+import { type ProjectionOptions } from './events';
 export type SpanKind = 'model' | 'tool' | 'approval';
 export type SpanStatus = 'open' | 'ok' | 'error' | 'denied';
 /**
@@ -44,10 +45,10 @@ export interface ModelSpan extends SpanBase {
     kind: 'model';
     model?: string;
     provider?: string;
-    /** pi's provider response id — the join key to a metered inference row. */
+    /** The provider's response id — the join key to a metered inference row. */
     responseId?: string;
     stopReason?: string;
-    usage?: PiUsage;
+    usage?: TranscriptUsage;
     errorMessage?: string;
 }
 export interface ToolSpan extends SpanBase {
@@ -76,9 +77,9 @@ export interface SpanProjection {
 }
 /**
  * Project records into spans. Pure, and like the other projectors it ignores what
- * it does not recognise — a log written by a newer pi still traces. A *registered*
- * type that is malformed is another matter and throws: a gate decision naming no
- * tool call is a writer bug, and a trace that quietly omitted a refusal would be
- * worse than one that fails.
+ * it does not recognise — a log written by a newer harness still traces. A
+ * *registered* type that is malformed is another matter and throws: a gate
+ * decision naming no tool call is a writer bug, and a trace that quietly omitted
+ * a refusal would be worse than one that fails.
  */
-export declare function projectSpans(records: readonly RunEventRecord[]): SpanProjection;
+export declare function projectSpans(records: readonly RunEventRecord[], options?: ProjectionOptions): SpanProjection;