@agentic-kit/run-log 0.5.0 → 0.6.0

package/README.md

@@ -106,10 +106,6 @@ Unreadable input fails loudly. A corrupt record, a mixed-version log, or a sessi
 - [`@agentic-kit/metering`](../metering) — the metered gateway and usage reporting
 - [`agentic-server`](../agentic-server) — the metered inference gateway
 
-## License
-
-SEE LICENSE IN LICENSE
-
 ---
 
 ## Education and Tutorials

package/esm/file-store.d.ts

@@ -13,7 +13,7 @@
 import { type SessionProjectionOptions } from './projectors/session';
 import { type RunEventRecord } from './record';
 import { type AppendOptions, type RunLogCursor, type RunLogPage, type RunLogStore } from './store';
-import type { PiSessionEntry } from './transcripts/pi-entry';
+import type { TranscriptEntry } from './transcripts/entry';
 export interface FileRunLogStoreOptions {
     /** Absolute path of the log file. Parent directories are created. */
     path: string;
@@ -22,7 +22,7 @@ export declare class FileRunLogStore implements RunLogStore {
     private readonly path;
     constructor(options: FileRunLogStoreOptions);
     private load;
-    append(runId: string, entries: readonly PiSessionEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
+    append(runId: string, entries: readonly TranscriptEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
     read(runId: string, cursor?: RunLogCursor, limit?: number): Promise<RunLogPage>;
 }
 /**

package/esm/index.d.ts

@@ -9,6 +9,7 @@
 export { constructiveEntryTypes, type EntryTypeDefinition, EntryTypeRegistry, type EntryVisibility } from './entry-types';
 export { follow, type FollowOptions, readAll } from './follow';
 export { type SessionEntrySource, SessionMirror, type SessionMirrorOptions } from './mirror';
+export { type EventGroup, type ProjectionOptions, type SequencedEvent, toEventGroups, toEvents } from './projectors/events';
 export { type BashPart, type Conversation, type ConversationPart, type CustomPart, projectParts, type SummaryPart, type TextPart, type ThinkingPart, type ToolPart, type ToolStatus, type UnknownPart } from './projectors/parts';
 export { parseSessionJsonl, projectSession, type SessionProjection, type SessionProjectionOptions } from './projectors/session';
 export { type ApprovalSpan, type ModelSpan, projectSpans, type Span, type SpanBase, type SpanKind, type SpanProjection, type SpanStatus, type SpanTiming, type ToolSpan } from './projectors/spans';
@@ -16,5 +17,10 @@ export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, type ApprovalRequestIn
 export { modelKey, type ModelUsage, projectUsage, type RunUsage, type UsageTotals } from './projectors/usage';
 export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, type RunEventRecord, wrapEntry, type WrapEntryOptions } from './record';
 export { type AppendOptions, cursorAfter, MemoryRunLogStore, type RunLogAppendStore, type RunLogCursor, type RunLogPage, type RunLogReadStore, type RunLogStore, START } from './store';
+export { assertTranscriptEntry, type TranscriptEntry } from './transcripts/entry';
+export { type BashEvent, type CustomEvent, type ModelResponseEvent, type SessionStartEvent, type SummaryEvent, type TextEvent, type ThinkingEvent, type ToolCallEvent, type ToolResultEvent, type TranscriptEvent, type TranscriptEventBase, type TranscriptUsage, type UnknownEvent } from './transcripts/event';
 export { assertTranscriptFormat, PI_TRANSCRIPT_FORMAT, SUPPORTED_PI_TRANSCRIPT_VERSION, type TranscriptFormat } from './transcripts/format';
 export { assertPiSessionEntry, contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, type PiAssistantMessage, type PiBashExecutionMessage, type PiBranchSummaryEntry, type PiCompactionEntry, type PiContent, type PiCustomMessage, type PiEntryBase, type PiImageContent, type PiMessage, type PiMessageEntry, type PiOtherEntry, type PiSessionEntry, type PiSessionHeader, type PiSummaryMessage, type PiTextContent, type PiThinkingContent, type PiToolCallContent, type PiToolResultMessage, type PiUsage, type PiUsageCost, type PiUserMessage, toolCalls } from './transcripts/pi-entry';
+export { piEntryToEvents, piTranscriptReader } from './transcripts/pi-reader';
+export { passthroughReader, type TranscriptReader, TranscriptReaderRegistry } from './transcripts/reader';
+export { defaultTranscriptReaders, transcriptReaders } from './transcripts/registry';

package/esm/index.js

@@ -9,6 +9,7 @@
 export { constructiveEntryTypes, EntryTypeRegistry } from './entry-types';
 export { follow, readAll } from './follow';
 export { SessionMirror } from './mirror';
+export { toEventGroups, toEvents } from './projectors/events';
 export { projectParts } from './projectors/parts';
 export { parseSessionJsonl, projectSession } from './projectors/session';
 export { projectSpans } from './projectors/spans';
@@ -16,5 +17,9 @@ export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, approvalRequestMessage
 export { modelKey, projectUsage } from './projectors/usage';
 export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, wrapEntry } from './record';
 export { cursorAfter, MemoryRunLogStore, START } from './store';
+export { assertTranscriptEntry } from './transcripts/entry';
 export { assertTranscriptFormat, PI_TRANSCRIPT_FORMAT, SUPPORTED_PI_TRANSCRIPT_VERSION } from './transcripts/format';
 export { assertPiSessionEntry, contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from './transcripts/pi-entry';
+export { piEntryToEvents, piTranscriptReader } from './transcripts/pi-reader';
+export { passthroughReader, TranscriptReaderRegistry } from './transcripts/reader';
+export { defaultTranscriptReaders, transcriptReaders } from './transcripts/registry';

package/esm/mirror.d.ts

@@ -19,8 +19,8 @@
  */
 import type { RunEventRecord } from './record';
 import type { RunLogAppendStore } from './store';
-import type { TranscriptFormat } from './transcripts/format';
-import { type PiSessionEntry } from './transcripts/pi-entry';
+import { type TranscriptEntry } from './transcripts/entry';
+import { type TranscriptFormat } from './transcripts/format';
 /** The slice of a harness session manager the mirror needs. */
 export interface SessionEntrySource {
     getHeader(): unknown;
@@ -30,11 +30,11 @@ export interface SessionMirrorOptions {
     runId: string;
     store: RunLogAppendStore;
     /**
-     * Narrow each entry before it is appended. Defaults to the pi transcript
-     * reader, which is the only entry shape the record currently types; an adapter
-     * for another transcript supplies its own.
+     * Narrow each entry before it is appended. Defaults to the reader registered
+     * for `transcriptFormat`, so an adapter for another transcript gets its own
+     * validation by registering its reader.
      */
-    assertEntry?: (entry: unknown) => PiSessionEntry;
+    assertEntry?: (entry: unknown) => TranscriptEntry;
     /** Transcript format the entries are encoded in, e.g. `pi`. */
     transcriptFormat?: TranscriptFormat;
     /** Transcript format version the entries are produced under. */

package/esm/mirror.js

@@ -17,7 +17,8 @@
  * and the format the entries are validated as, so this is testable without a
  * running agent.
  */
-import { assertPiSessionEntry } from './transcripts/pi-entry';
+import { PI_TRANSCRIPT_FORMAT } from './transcripts/format';
+import { transcriptReaders } from './transcripts/registry';
 export class SessionMirror {
     runId;
     store;
@@ -32,7 +33,9 @@ export class SessionMirror {
     constructor(options) {
         this.runId = options.runId;
         this.store = options.store;
-        this.assertEntry = options.assertEntry ?? assertPiSessionEntry;
+        this.assertEntry =
+            options.assertEntry ??
+                transcriptReaders.require(options.transcriptFormat ?? PI_TRANSCRIPT_FORMAT).assertEntry;
         this.transcriptFormat = options.transcriptFormat;
         this.transcriptVersion = options.transcriptVersion;
     }

package/esm/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/esm/projectors/events.js

@@ -0,0 +1,23 @@
+/**
+ * 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 { transcriptReaders } from '../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.
+ */
+export function toEventGroups(records, options = {}) {
+    const readers = options.readers ?? transcriptReaders;
+    return records.map((record) => ({
+        seq: record.seq,
+        events: readers.require(record.transcriptFormat).toEvents(record.entry)
+    }));
+}
+export function toEvents(records, options = {}) {
+    return toEventGroups(records, options).flatMap(({ seq, events }) => events.map((event) => ({ seq, event })));
+}

package/esm/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/esm/projectors/parts.js

@@ -1,131 +1,114 @@
 /**
  * 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 { contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from '../transcripts/pi-entry';
+import { toEvents } from './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.
  */
-export function projectParts(records) {
+export function projectParts(records, options = {}) {
     const parts = [];
     const toolsByCallId = new Map();
     let sessionId;
     let cwd;
-    for (const record of records) {
-        const { entry, seq } = record;
-        if (isPiSessionHeader(entry)) {
-            sessionId = entry.id;
-            if (typeof entry.cwd === 'string')
-                cwd = entry.cwd;
-            continue;
-        }
-        if (isPiCompactionEntry(entry)) {
-            parts.push({ kind: 'summary', reason: 'compaction', summary: entry.summary, seq, entryId: entry.id });
-            continue;
-        }
-        if (isPiBranchSummaryEntry(entry)) {
-            parts.push({ kind: 'summary', reason: 'branch', summary: entry.summary, seq, entryId: entry.id });
-            continue;
-        }
-        if (!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: contentText(message.content), ...base });
-            continue;
-        }
-        if (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 toolCalls(message)) {
+    for (const { seq, event } of 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 (isToolResultMessage(message)) {
-            const existing = toolsByCallId.get(message.toolCallId);
-            const output = 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: 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/esm/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/esm/projectors/session.js

@@ -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 { assertOrdered } from '../record';
 import { assertTranscriptFormat, PI_TRANSCRIPT_FORMAT, SUPPORTED_PI_TRANSCRIPT_VERSION } from '../transcripts/format';
@@ -25,6 +30,7 @@ export 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 ?? 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(isPiSessionHeader);
     if (headerIndex > 0) {

package/esm/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;