@agentic-kit/run-log 0.2.0 → 0.4.0

package/esm/record.js

@@ -1,17 +1,17 @@
 /**
- * The run log record: four platform-owned fields around a verbatim pi entry.
+ * The run log record: five platform-owned fields around a verbatim harness entry.
  *
- * The wrapper exists to give an entry identity (which run) and order (which
- * position) across hosts — nothing else. It deliberately does not re-encode pi's
- * semantics, because pi already versions and migrates its own session format;
- * `piSessionVersion` records which version an entry was written under so a
- * reader can hand old entries to pi's migrations instead of guessing.
+ * The wrapper exists to give an entry identity (which run), order (which
+ * position) and readability (which transcript) across hosts — nothing else. It
+ * deliberately does not re-encode a harness's semantics, because a harness
+ * already versions and migrates its own session format; `transcriptFormat` says
+ * which reader can parse the entry, and `transcriptVersion` says which version
+ * that reader must migrate from.
  */
-import { assertPiSessionEntry } from './pi-entry';
-/** Version of the wrapper itself — bumped only if these four fields change. */
+import { PI_TRANSCRIPT_FORMAT, SUPPORTED_PI_TRANSCRIPT_VERSION } from './transcripts/format';
+import { assertPiSessionEntry } from './transcripts/pi-entry';
+/** Version of the wrapper itself — bumped only if these fields change. */
 export const RUN_LOG_WRAPPER_VERSION = 1;
-/** The pi session format version this package projects without migration. */
-export const SUPPORTED_PI_SESSION_VERSION = 3;
 export function wrapEntry(options) {
     if (!options.runId)
         throw new TypeError('a run log record needs a runId');
@@ -22,7 +22,8 @@ export function wrapEntry(options) {
         runId: options.runId,
         seq: options.seq,
         recordedAt: options.recordedAt ?? new Date().toISOString(),
-        piSessionVersion: options.piSessionVersion ?? SUPPORTED_PI_SESSION_VERSION,
+        transcriptFormat: options.transcriptFormat ?? PI_TRANSCRIPT_FORMAT,
+        transcriptVersion: options.transcriptVersion ?? SUPPORTED_PI_TRANSCRIPT_VERSION,
         entry: assertPiSessionEntry(options.entry)
     };
 }
@@ -45,14 +46,18 @@ export function assertRunEventRecord(value) {
     if (typeof record.recordedAt !== 'string') {
         throw new TypeError(`run log record ${record.runId}#${String(record.seq)} must carry recordedAt`);
     }
-    if (!Number.isInteger(record.piSessionVersion)) {
-        throw new TypeError(`run log record ${record.runId}#${String(record.seq)} must carry an integer piSessionVersion`);
+    if (typeof record.transcriptFormat !== 'string' || record.transcriptFormat.length === 0) {
+        throw new TypeError(`run log record ${record.runId}#${String(record.seq)} must carry a non-empty transcriptFormat`);
+    }
+    if (!Number.isInteger(record.transcriptVersion)) {
+        throw new TypeError(`run log record ${record.runId}#${String(record.seq)} must carry an integer transcriptVersion`);
     }
     return {
         runId: record.runId,
         seq: record.seq,
         recordedAt: record.recordedAt,
-        piSessionVersion: record.piSessionVersion,
+        transcriptFormat: record.transcriptFormat,
+        transcriptVersion: record.transcriptVersion,
         entry: assertPiSessionEntry(record.entry)
     };
 }

package/esm/store.d.ts

@@ -5,8 +5,9 @@
  * with their storage — Postgres in constructive-db, JSONL in `./file-store`,
  * memory here for tests and for a run that has not been persisted yet.
  */
-import type { PiSessionEntry } from './pi-entry';
 import { type RunEventRecord } from './record';
+import type { TranscriptFormat } from './transcripts/format';
+import type { PiSessionEntry } from './transcripts/pi-entry';
 /** Read position: `afterSeq` is exclusive, so `0` means "from the start". */
 export interface RunLogCursor {
     afterSeq: number;
@@ -18,8 +19,10 @@ export interface RunLogPage {
     cursor: RunLogCursor;
 }
 export interface AppendOptions {
-    /** pi session format version the entries were produced under. */
-    piSessionVersion?: number;
+    /** Transcript the entries are encoded in. Defaults to pi's. */
+    transcriptFormat?: TranscriptFormat;
+    /** That transcript's format version the entries were produced under. */
+    transcriptVersion?: number;
     recordedAt?: string;
 }
 export interface RunLogAppendStore {

package/esm/store.js

@@ -5,7 +5,7 @@
  * with their storage — Postgres in constructive-db, JSONL in `./file-store`,
  * memory here for tests and for a run that has not been persisted yet.
  */
-import { assertOrdered, idempotencyKey, SUPPORTED_PI_SESSION_VERSION, wrapEntry } from './record';
+import { assertOrdered, idempotencyKey, wrapEntry } from './record';
 export const START = { afterSeq: 0 };
 export const cursorAfter = (records, from = START) => records.length === 0 ? from : { afterSeq: records[records.length - 1].seq };
 /** In-memory store: the reference implementation and the test double. */
@@ -25,7 +25,8 @@ export class MemoryRunLogStore {
                 seq: records.length + written.length + 1,
                 entry,
                 ...(options.recordedAt ? { recordedAt: options.recordedAt } : {}),
-                piSessionVersion: options.piSessionVersion ?? SUPPORTED_PI_SESSION_VERSION
+                ...(options.transcriptFormat === undefined ? {} : { transcriptFormat: options.transcriptFormat }),
+                ...(options.transcriptVersion === undefined ? {} : { transcriptVersion: options.transcriptVersion })
             });
             written.push(record);
             seen.add(key);

package/esm/transcripts/format.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which transcript a record's entry is encoded in.
+ *
+ * The log stores a harness's own entries verbatim, so a reader cannot know how
+ * to project a record without being told what it is looking at. The format is
+ * therefore carried *per record*, not per run: a run resumed under a different
+ * harness, or migrated between them, stays one ordered log.
+ *
+ * Deliberately a string rather than a closed union — a format is a value that
+ * ships with an adapter, so adding one must not require a release of this
+ * package. Known formats are declared as constants here.
+ */
+export type TranscriptFormat = string;
+/** pi's session-file entries (`@earendil-works/pi-coding-agent`). */
+export declare const PI_TRANSCRIPT_FORMAT = "pi";
+/** The pi session format version this package projects without migration. */
+export declare const SUPPORTED_PI_TRANSCRIPT_VERSION = 3;
+/**
+ * Narrow a record's format before projecting it. A projector reads one format;
+ * handing it another must fail loudly rather than render an empty conversation
+ * out of entries it did not understand.
+ */
+export declare function assertTranscriptFormat(records: readonly {
+    transcriptFormat: TranscriptFormat;
+}[], expected: TranscriptFormat): void;

package/esm/transcripts/format.js

@@ -0,0 +1,29 @@
+/**
+ * Which transcript a record's entry is encoded in.
+ *
+ * The log stores a harness's own entries verbatim, so a reader cannot know how
+ * to project a record without being told what it is looking at. The format is
+ * therefore carried *per record*, not per run: a run resumed under a different
+ * harness, or migrated between them, stays one ordered log.
+ *
+ * Deliberately a string rather than a closed union — a format is a value that
+ * ships with an adapter, so adding one must not require a release of this
+ * package. Known formats are declared as constants here.
+ */
+/** pi's session-file entries (`@earendil-works/pi-coding-agent`). */
+export const PI_TRANSCRIPT_FORMAT = 'pi';
+/** The pi session format version this package projects without migration. */
+export const SUPPORTED_PI_TRANSCRIPT_VERSION = 3;
+/**
+ * Narrow a record's format before projecting it. A projector reads one format;
+ * handing it another must fail loudly rather than render an empty conversation
+ * out of entries it did not understand.
+ */
+export function assertTranscriptFormat(records, expected) {
+    const formats = new Set(records.map((record) => record.transcriptFormat));
+    formats.delete(expected);
+    if (formats.size === 0)
+        return;
+    throw new Error(`run log carries transcript format(s) ${Array.from(formats).sort().join(', ')}; ` +
+        `this projector reads "${expected}" entries only`);
+}

package/file-store.d.ts

@@ -10,10 +10,10 @@
  * dropped. This is the store a local run uses before (or without) a database,
  * and the one tests use when they want the log to survive a process restart.
  */
-import type { PiSessionEntry } from './pi-entry';
 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';
 export interface FileRunLogStoreOptions {
     /** Absolute path of the log file. Parent directories are created. */
     path: string;

package/file-store.js

@@ -58,7 +58,8 @@ class FileRunLogStore {
                 seq: existing.length + written.length + 1,
                 entry,
                 ...(options.recordedAt ? { recordedAt: options.recordedAt } : {}),
-                piSessionVersion: options.piSessionVersion ?? record_1.SUPPORTED_PI_SESSION_VERSION
+                ...(options.transcriptFormat === undefined ? {} : { transcriptFormat: options.transcriptFormat }),
+                ...(options.transcriptVersion === undefined ? {} : { transcriptVersion: options.transcriptVersion })
             }));
             seen.add(key);
         }

package/index.d.ts

@@ -6,11 +6,15 @@
  * reach for a node builtin. The filesystem store lives behind
  * `@agentic-kit/run-log/file-store`.
  */
+export { constructiveEntryTypes, type EntryTypeDefinition, EntryTypeRegistry, type EntryVisibility } from './entry-types';
 export { follow, type FollowOptions, readAll } from './follow';
-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 './pi-entry';
+export { type SessionEntrySource, SessionMirror, type SessionMirrorOptions } from './mirror';
 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 { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, type ApprovalRequestInput, approvalRequestMessage, type ApprovalResolutionInput, approvalResolutionMessage, type ApprovalState, projectToolState, type ToolCallState, type ToolCallStatus, type ToolStateProjection } from './projectors/tool-state';
+export { type ApprovalSpan, type ModelSpan, projectSpans, type Span, type SpanBase, type SpanKind, type SpanProjection, type SpanStatus, type SpanTiming, type ToolSpan } from './projectors/spans';
+export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, type ApprovalRequestInput, approvalRequestMessage, type ApprovalResolutionInput, approvalResolutionMessage, type ApprovalState, assertApprovalRequestDetails, assertApprovalResolutionDetails, assertGateDecisionDetails, GATE_DECISION_TYPE, type GateDecisionDetails, gateDecisionMessage, type GateDecisionState, projectToolState, type ToolCallState, type ToolCallStatus, type ToolStateProjection } from './projectors/tool-state';
 export { modelKey, type ModelUsage, projectUsage, type RunUsage, type UsageTotals } from './projectors/usage';
-export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, type RunEventRecord, SUPPORTED_PI_SESSION_VERSION, wrapEntry, type WrapEntryOptions } from './record';
+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 { 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';

package/index.js

@@ -8,30 +8,32 @@
  * `@agentic-kit/run-log/file-store`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.START = exports.MemoryRunLogStore = exports.cursorAfter = exports.wrapEntry = exports.SUPPORTED_PI_SESSION_VERSION = exports.RUN_LOG_WRAPPER_VERSION = exports.idempotencyKey = exports.assertRunEventRecord = exports.assertOrdered = exports.projectUsage = exports.modelKey = exports.projectToolState = exports.approvalResolutionMessage = exports.approvalRequestMessage = exports.APPROVAL_RESOLUTION_TYPE = exports.APPROVAL_REQUEST_TYPE = exports.projectSession = exports.parseSessionJsonl = exports.projectParts = exports.toolCalls = exports.isToolResultMessage = exports.isPiSessionHeader = exports.isPiMessageEntry = exports.isPiCompactionEntry = exports.isPiBranchSummaryEntry = exports.isAssistantMessage = exports.contentText = exports.assertPiSessionEntry = exports.readAll = exports.follow = void 0;
+exports.toolCalls = exports.isToolResultMessage = exports.isPiSessionHeader = exports.isPiMessageEntry = exports.isPiCompactionEntry = exports.isPiBranchSummaryEntry = exports.isAssistantMessage = exports.contentText = exports.assertPiSessionEntry = exports.SUPPORTED_PI_TRANSCRIPT_VERSION = exports.PI_TRANSCRIPT_FORMAT = exports.assertTranscriptFormat = exports.START = exports.MemoryRunLogStore = exports.cursorAfter = exports.wrapEntry = exports.RUN_LOG_WRAPPER_VERSION = exports.idempotencyKey = exports.assertRunEventRecord = exports.assertOrdered = exports.projectUsage = exports.modelKey = exports.projectToolState = exports.gateDecisionMessage = exports.GATE_DECISION_TYPE = exports.assertGateDecisionDetails = exports.assertApprovalResolutionDetails = exports.assertApprovalRequestDetails = exports.approvalResolutionMessage = exports.approvalRequestMessage = exports.APPROVAL_RESOLUTION_TYPE = exports.APPROVAL_REQUEST_TYPE = exports.projectSpans = exports.projectSession = exports.parseSessionJsonl = exports.projectParts = exports.SessionMirror = exports.readAll = exports.follow = exports.EntryTypeRegistry = exports.constructiveEntryTypes = void 0;
+var entry_types_1 = require("./entry-types");
+Object.defineProperty(exports, "constructiveEntryTypes", { enumerable: true, get: function () { return entry_types_1.constructiveEntryTypes; } });
+Object.defineProperty(exports, "EntryTypeRegistry", { enumerable: true, get: function () { return entry_types_1.EntryTypeRegistry; } });
 var follow_1 = require("./follow");
 Object.defineProperty(exports, "follow", { enumerable: true, get: function () { return follow_1.follow; } });
 Object.defineProperty(exports, "readAll", { enumerable: true, get: function () { return follow_1.readAll; } });
-var pi_entry_1 = require("./pi-entry");
-Object.defineProperty(exports, "assertPiSessionEntry", { enumerable: true, get: function () { return pi_entry_1.assertPiSessionEntry; } });
-Object.defineProperty(exports, "contentText", { enumerable: true, get: function () { return pi_entry_1.contentText; } });
-Object.defineProperty(exports, "isAssistantMessage", { enumerable: true, get: function () { return pi_entry_1.isAssistantMessage; } });
-Object.defineProperty(exports, "isPiBranchSummaryEntry", { enumerable: true, get: function () { return pi_entry_1.isPiBranchSummaryEntry; } });
-Object.defineProperty(exports, "isPiCompactionEntry", { enumerable: true, get: function () { return pi_entry_1.isPiCompactionEntry; } });
-Object.defineProperty(exports, "isPiMessageEntry", { enumerable: true, get: function () { return pi_entry_1.isPiMessageEntry; } });
-Object.defineProperty(exports, "isPiSessionHeader", { enumerable: true, get: function () { return pi_entry_1.isPiSessionHeader; } });
-Object.defineProperty(exports, "isToolResultMessage", { enumerable: true, get: function () { return pi_entry_1.isToolResultMessage; } });
-Object.defineProperty(exports, "toolCalls", { enumerable: true, get: function () { return pi_entry_1.toolCalls; } });
+var mirror_1 = require("./mirror");
+Object.defineProperty(exports, "SessionMirror", { enumerable: true, get: function () { return mirror_1.SessionMirror; } });
 var parts_1 = require("./projectors/parts");
 Object.defineProperty(exports, "projectParts", { enumerable: true, get: function () { return parts_1.projectParts; } });
 var session_1 = require("./projectors/session");
 Object.defineProperty(exports, "parseSessionJsonl", { enumerable: true, get: function () { return session_1.parseSessionJsonl; } });
 Object.defineProperty(exports, "projectSession", { enumerable: true, get: function () { return session_1.projectSession; } });
+var spans_1 = require("./projectors/spans");
+Object.defineProperty(exports, "projectSpans", { enumerable: true, get: function () { return spans_1.projectSpans; } });
 var tool_state_1 = require("./projectors/tool-state");
 Object.defineProperty(exports, "APPROVAL_REQUEST_TYPE", { enumerable: true, get: function () { return tool_state_1.APPROVAL_REQUEST_TYPE; } });
 Object.defineProperty(exports, "APPROVAL_RESOLUTION_TYPE", { enumerable: true, get: function () { return tool_state_1.APPROVAL_RESOLUTION_TYPE; } });
 Object.defineProperty(exports, "approvalRequestMessage", { enumerable: true, get: function () { return tool_state_1.approvalRequestMessage; } });
 Object.defineProperty(exports, "approvalResolutionMessage", { enumerable: true, get: function () { return tool_state_1.approvalResolutionMessage; } });
+Object.defineProperty(exports, "assertApprovalRequestDetails", { enumerable: true, get: function () { return tool_state_1.assertApprovalRequestDetails; } });
+Object.defineProperty(exports, "assertApprovalResolutionDetails", { enumerable: true, get: function () { return tool_state_1.assertApprovalResolutionDetails; } });
+Object.defineProperty(exports, "assertGateDecisionDetails", { enumerable: true, get: function () { return tool_state_1.assertGateDecisionDetails; } });
+Object.defineProperty(exports, "GATE_DECISION_TYPE", { enumerable: true, get: function () { return tool_state_1.GATE_DECISION_TYPE; } });
+Object.defineProperty(exports, "gateDecisionMessage", { enumerable: true, get: function () { return tool_state_1.gateDecisionMessage; } });
 Object.defineProperty(exports, "projectToolState", { enumerable: true, get: function () { return tool_state_1.projectToolState; } });
 var usage_1 = require("./projectors/usage");
 Object.defineProperty(exports, "modelKey", { enumerable: true, get: function () { return usage_1.modelKey; } });
@@ -41,9 +43,22 @@ Object.defineProperty(exports, "assertOrdered", { enumerable: true, get: functio
 Object.defineProperty(exports, "assertRunEventRecord", { enumerable: true, get: function () { return record_1.assertRunEventRecord; } });
 Object.defineProperty(exports, "idempotencyKey", { enumerable: true, get: function () { return record_1.idempotencyKey; } });
 Object.defineProperty(exports, "RUN_LOG_WRAPPER_VERSION", { enumerable: true, get: function () { return record_1.RUN_LOG_WRAPPER_VERSION; } });
-Object.defineProperty(exports, "SUPPORTED_PI_SESSION_VERSION", { enumerable: true, get: function () { return record_1.SUPPORTED_PI_SESSION_VERSION; } });
 Object.defineProperty(exports, "wrapEntry", { enumerable: true, get: function () { return record_1.wrapEntry; } });
 var store_1 = require("./store");
 Object.defineProperty(exports, "cursorAfter", { enumerable: true, get: function () { return store_1.cursorAfter; } });
 Object.defineProperty(exports, "MemoryRunLogStore", { enumerable: true, get: function () { return store_1.MemoryRunLogStore; } });
 Object.defineProperty(exports, "START", { enumerable: true, get: function () { return store_1.START; } });
+var format_1 = require("./transcripts/format");
+Object.defineProperty(exports, "assertTranscriptFormat", { enumerable: true, get: function () { return format_1.assertTranscriptFormat; } });
+Object.defineProperty(exports, "PI_TRANSCRIPT_FORMAT", { enumerable: true, get: function () { return format_1.PI_TRANSCRIPT_FORMAT; } });
+Object.defineProperty(exports, "SUPPORTED_PI_TRANSCRIPT_VERSION", { enumerable: true, get: function () { return format_1.SUPPORTED_PI_TRANSCRIPT_VERSION; } });
+var pi_entry_1 = require("./transcripts/pi-entry");
+Object.defineProperty(exports, "assertPiSessionEntry", { enumerable: true, get: function () { return pi_entry_1.assertPiSessionEntry; } });
+Object.defineProperty(exports, "contentText", { enumerable: true, get: function () { return pi_entry_1.contentText; } });
+Object.defineProperty(exports, "isAssistantMessage", { enumerable: true, get: function () { return pi_entry_1.isAssistantMessage; } });
+Object.defineProperty(exports, "isPiBranchSummaryEntry", { enumerable: true, get: function () { return pi_entry_1.isPiBranchSummaryEntry; } });
+Object.defineProperty(exports, "isPiCompactionEntry", { enumerable: true, get: function () { return pi_entry_1.isPiCompactionEntry; } });
+Object.defineProperty(exports, "isPiMessageEntry", { enumerable: true, get: function () { return pi_entry_1.isPiMessageEntry; } });
+Object.defineProperty(exports, "isPiSessionHeader", { enumerable: true, get: function () { return pi_entry_1.isPiSessionHeader; } });
+Object.defineProperty(exports, "isToolResultMessage", { enumerable: true, get: function () { return pi_entry_1.isToolResultMessage; } });
+Object.defineProperty(exports, "toolCalls", { enumerable: true, get: function () { return pi_entry_1.toolCalls; } });

package/mirror.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Mirroring a harness's session into the run log.
+ *
+ * The harness owns the session: it appends entries to its own append-only
+ * transcript. Harnesses generally expose no "entry appended" event to subscribe
+ * to, so the mirror drains instead — after anything that could have appended, it
+ * takes the entries it has not seen yet and appends them to the run log
+ * verbatim. Index-based draining is sound precisely because the transcript is
+ * append-only: entries are never rewritten or removed, only branched from.
+ *
+ * A switch/fork/new-session replaces the entry list under the same source, so the
+ * read position is keyed to the session header's id and resets when that id
+ * changes; entries carried into the new session are absorbed by the store's
+ * idempotency (entry ids).
+ *
+ * Harness-neutral: the adapter owns only the subscription that calls `drain()`
+ * and the format the entries are validated as, so this is testable without a
+ * running agent.
+ */
+import type { RunEventRecord } from './record';
+import type { RunLogAppendStore } from './store';
+import type { TranscriptFormat } from './transcripts/format';
+import { type PiSessionEntry } from './transcripts/pi-entry';
+/** The slice of a harness session manager the mirror needs. */
+export interface SessionEntrySource {
+    getHeader(): unknown;
+    getEntries(): readonly unknown[];
+}
+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.
+     */
+    assertEntry?: (entry: unknown) => PiSessionEntry;
+    /** Transcript format the entries are encoded in, e.g. `pi`. */
+    transcriptFormat?: TranscriptFormat;
+    /** Transcript format version the entries are produced under. */
+    transcriptVersion?: number;
+}
+export declare class SessionMirror {
+    private readonly runId;
+    private readonly store;
+    private readonly assertEntry;
+    private readonly transcriptFormat;
+    private readonly transcriptVersion;
+    private source;
+    private sessionId;
+    private consumed;
+    private headerMirrored;
+    private tail;
+    constructor(options: SessionMirrorOptions);
+    /** Point the mirror at a session source. Safe to call on every event. */
+    bind(source: SessionEntrySource): void;
+    /**
+     * Append everything the mirror has not seen yet. Drains are serialized, so
+     * concurrent callers cannot interleave batches and break run-log ordering.
+     */
+    drain(): Promise<RunEventRecord[]>;
+    private flushOnce;
+}

package/mirror.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Mirroring a harness's session into the run log.
+ *
+ * The harness owns the session: it appends entries to its own append-only
+ * transcript. Harnesses generally expose no "entry appended" event to subscribe
+ * to, so the mirror drains instead — after anything that could have appended, it
+ * takes the entries it has not seen yet and appends them to the run log
+ * verbatim. Index-based draining is sound precisely because the transcript is
+ * append-only: entries are never rewritten or removed, only branched from.
+ *
+ * A switch/fork/new-session replaces the entry list under the same source, so the
+ * read position is keyed to the session header's id and resets when that id
+ * changes; entries carried into the new session are absorbed by the store's
+ * idempotency (entry ids).
+ *
+ * Harness-neutral: the adapter owns only the subscription that calls `drain()`
+ * and the format the entries are validated as, so this is testable without a
+ * running agent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionMirror = void 0;
+const pi_entry_1 = require("./transcripts/pi-entry");
+class SessionMirror {
+    runId;
+    store;
+    assertEntry;
+    transcriptFormat;
+    transcriptVersion;
+    source = null;
+    sessionId = null;
+    consumed = 0;
+    headerMirrored = false;
+    tail = Promise.resolve();
+    constructor(options) {
+        this.runId = options.runId;
+        this.store = options.store;
+        this.assertEntry = options.assertEntry ?? pi_entry_1.assertPiSessionEntry;
+        this.transcriptFormat = options.transcriptFormat;
+        this.transcriptVersion = options.transcriptVersion;
+    }
+    /** Point the mirror at a session source. Safe to call on every event. */
+    bind(source) {
+        this.source = source;
+    }
+    /**
+     * Append everything the mirror has not seen yet. Drains are serialized, so
+     * concurrent callers cannot interleave batches and break run-log ordering.
+     */
+    drain() {
+        const run = this.tail.then(() => this.flushOnce());
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async flushOnce() {
+        const source = this.source;
+        if (!source)
+            return [];
+        const header = source.getHeader();
+        const sessionId = headerSessionId(header);
+        if (sessionId !== null && sessionId !== this.sessionId) {
+            this.sessionId = sessionId;
+            this.consumed = 0;
+            this.headerMirrored = false;
+        }
+        const batch = [];
+        if (!this.headerMirrored && header !== null && header !== undefined)
+            batch.push(this.assertEntry(header));
+        const entries = source.getEntries();
+        const upto = entries.length;
+        for (let i = this.consumed; i < upto; i += 1)
+            batch.push(this.assertEntry(entries[i]));
+        if (batch.length === 0)
+            return [];
+        const written = await this.store.append(this.runId, batch, {
+            ...(this.transcriptFormat === undefined ? {} : { transcriptFormat: this.transcriptFormat }),
+            ...(this.transcriptVersion === undefined ? {} : { transcriptVersion: this.transcriptVersion })
+        });
+        // Advance only after a successful append: a failed drain is retried whole.
+        this.headerMirrored = true;
+        this.consumed = upto;
+        return written;
+    }
+}
+exports.SessionMirror = SessionMirror;
+function headerSessionId(header) {
+    if (typeof header !== 'object' || header === null)
+        return null;
+    const id = header.id;
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-kit/run-log",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "The append-only agent run log — pi session entries stored verbatim under a run/seq wrapper, with projections for transcript, usage, tool state and resumable sessions",
   "main": "index.js",
@@ -35,5 +35,5 @@
     "run-log",
     "constructive"
   ],
-  "gitHead": "d4bf3a37545daad7246505a96ae8a4b87f44d53c"
+  "gitHead": "44a670631c98f7174db0e4c25dc30a3c81fd4437"
 }

package/projectors/parts.d.ts

@@ -7,8 +7,8 @@
  * `unknown` part rather than disappearing — a log written by a newer pi still
  * renders, minus the detail this version understands.
  */
-import { type PiSessionEntry } from '../pi-entry';
 import type { RunEventRecord } from '../record';
+import { type PiSessionEntry } from '../transcripts/pi-entry';
 export type ToolStatus = 'requested' | 'completed' | 'failed';
 export interface PartBase {
     /** Sequence of the record that introduced the part — a stable React key. */

package/projectors/parts.js

@@ -10,7 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectParts = projectParts;
-const pi_entry_1 = require("../pi-entry");
+const pi_entry_1 = require("../transcripts/pi-entry");
 /**
  * Project records into a conversation. Pure and total: the same records always
  * produce the same parts, whichever host wrote them.

package/projectors/session.d.ts

@@ -9,8 +9,8 @@
  * 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`.
  */
-import { type PiSessionEntry } from '../pi-entry';
 import { type RunEventRecord } from '../record';
+import { type PiSessionEntry } from '../transcripts/pi-entry';
 export interface SessionProjectionOptions {
     /** Used when the log carries no session header (a run logged headerless). */
     sessionId?: string;
@@ -22,7 +22,7 @@ export interface SessionProjection {
     jsonl: string;
     /** Entries in file order, header first. */
     entries: PiSessionEntry[];
-    piSessionVersion: number;
+    transcriptVersion: number;
 }
 /**
  * Project records into a pi session file. Throws when the records cannot form a

package/projectors/session.js

@@ -13,8 +13,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectSession = projectSession;
 exports.parseSessionJsonl = parseSessionJsonl;
-const pi_entry_1 = require("../pi-entry");
 const record_1 = require("../record");
+const format_1 = require("../transcripts/format");
+const pi_entry_1 = require("../transcripts/pi-entry");
 /**
  * Project records into a pi session file. Throws when the records cannot form a
  * loadable session — an unresumable session must fail at projection time, not
@@ -22,11 +23,12 @@ const record_1 = require("../record");
  */
 function projectSession(records, options = {}) {
     (0, record_1.assertOrdered)(records);
-    const versions = new Set(records.map((record) => record.piSessionVersion));
+    (0, format_1.assertTranscriptFormat)(records, format_1.PI_TRANSCRIPT_FORMAT);
+    const versions = new Set(records.map((record) => record.transcriptVersion));
     if (versions.size > 1) {
         throw new Error(`run log mixes pi session versions (${Array.from(versions).sort().join(', ')}); migrate the older entries before projecting a session`);
     }
-    const piSessionVersion = records[0]?.piSessionVersion ?? record_1.SUPPORTED_PI_SESSION_VERSION;
+    const transcriptVersion = records[0]?.transcriptVersion ?? format_1.SUPPORTED_PI_TRANSCRIPT_VERSION;
     const entries = records.map((record) => record.entry);
     const headerIndex = entries.findIndex(pi_entry_1.isPiSessionHeader);
     if (headerIndex > 0) {
@@ -37,7 +39,7 @@ function projectSession(records, options = {}) {
         ? entries[0]
         : {
             type: 'session',
-            version: piSessionVersion,
+            version: transcriptVersion,
             id: options.sessionId ?? records[0]?.runId ?? 'run-log',
             timestamp: options.timestamp ?? records[0]?.recordedAt ?? new Date().toISOString(),
             ...(options.cwd ? { cwd: options.cwd } : {})
@@ -45,7 +47,7 @@ function projectSession(records, options = {}) {
     const ordered = [header, ...body];
     return {
         entries: ordered,
-        piSessionVersion,
+        transcriptVersion,
         jsonl: ordered.map((entry) => JSON.stringify(entry)).join('\n') + '\n'
     };
 }

package/projectors/spans.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Span projection: run log records → timed intervals with parents.
+ *
+ * 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
+ * tool call and its result, or an approval request and its answer, bracket an
+ * interval; nothing new has to be stored to know it.
+ *
+ * Two honesty rules shape the output. A duration derived from a *pair of writes*
+ * is a bound, not a measurement — the gap between a tool call and its result
+ * includes the wait for a human — so every span says which it is via `timing`,
+ * and a tool span carries its approval wait separately so a renderer can show
+ * "blocked on you" apart from "running". And an interval that never closed stays
+ * `open` with no duration rather than being closed at the last record: a run
+ * still in flight must not look like one that finished.
+ */
+import type { RunEventRecord } from '../record';
+import { type PiUsage } from '../transcripts/pi-entry';
+export type SpanKind = 'model' | 'tool' | 'approval';
+export type SpanStatus = 'open' | 'ok' | 'error' | 'denied';
+/**
+ * Whether the duration is the interval that was measured, or a bound that
+ * includes whatever else sat between the two writes.
+ */
+export type SpanTiming = 'measured' | 'bounded';
+export interface SpanBase {
+    /** Stable within a run — a renderer's key and a parent reference. */
+    id: string;
+    kind: SpanKind;
+    /** Row title: the tool name, the model, or the awaited tool. */
+    name: string;
+    parentId?: string;
+    startSeq: number;
+    /** Absent while the span is still open. */
+    endSeq?: number;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    timing: SpanTiming;
+    status: SpanStatus;
+}
+export interface ModelSpan extends SpanBase {
+    kind: 'model';
+    model?: string;
+    provider?: string;
+    /** pi's provider response id — the join key to a metered inference row. */
+    responseId?: string;
+    stopReason?: string;
+    usage?: PiUsage;
+    errorMessage?: string;
+}
+export interface ToolSpan extends SpanBase {
+    kind: 'tool';
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+    output?: string;
+    details?: unknown;
+    /** Of the total duration, how much was spent waiting on a human. */
+    approvalWaitMs?: number;
+    /** Set when the gate settled the call instead of an execution. */
+    gateDecision?: 'allow' | 'deny';
+    gateReason?: string;
+}
+export interface ApprovalSpan extends SpanBase {
+    kind: 'approval';
+    toolCallId: string;
+    prompt: string;
+    decision?: 'approved' | 'rejected';
+    actorId?: string;
+}
+export type Span = ModelSpan | ToolSpan | ApprovalSpan;
+export interface SpanProjection {
+    /** In start order — the order a timeline draws them. */
+    spans: Span[];
+}
+/**
+ * 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.
+ */
+export declare function projectSpans(records: readonly RunEventRecord[]): SpanProjection;