@agentic-kit/run-log 0.3.0 → 0.5.0

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

@@ -8,11 +8,13 @@
  */
 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 { 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,23 +8,15 @@
  * `@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.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.toolCalls = exports.isToolResultMessage = exports.isPiSessionHeader = exports.isPiMessageEntry = exports.isPiCompactionEntry = exports.isPiBranchSummaryEntry = exports.isAssistantMessage = exports.contentText = exports.assertPiSessionEntry = exports.readAll = exports.follow = exports.EntryTypeRegistry = exports.constructiveEntryTypes = 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");
@@ -51,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.3.0",
+  "version": "0.5.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": "6880388c8cd5fb21745decff8bd23c3a430338b3"
+  "gitHead": "b5b6b9f05276b7e9cbd3d1f4acd31dd315c353ea"
 }

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

@@ -15,8 +15,8 @@
  * `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 PiUsage } from '../pi-entry';
 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';
 /**

package/projectors/spans.js

@@ -18,7 +18,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectSpans = projectSpans;
-const pi_entry_1 = require("../pi-entry");
+const pi_entry_1 = require("../transcripts/pi-entry");
 const tool_state_1 = require("./tool-state");
 const ms = (from, to) => {
     const start = Date.parse(from);

package/projectors/tool-state.js

@@ -15,7 +15,7 @@ exports.projectToolState = projectToolState;
 exports.assertGateDecisionDetails = assertGateDecisionDetails;
 exports.assertApprovalRequestDetails = assertApprovalRequestDetails;
 exports.assertApprovalResolutionDetails = assertApprovalResolutionDetails;
-const pi_entry_1 = require("../pi-entry");
+const pi_entry_1 = require("../transcripts/pi-entry");
 /** `customType` of an approval request written by the gate extension. */
 exports.APPROVAL_REQUEST_TYPE = 'constructive.approval.request';
 /** `customType` of the human's answer to a request. */

package/projectors/usage.d.ts

@@ -9,7 +9,7 @@
  *
  * This projection describes what a run *observed*. It is reconciliation input,
  * never the billing authority — a gateway-observed record is (see
- * `@agentic-kit/pi-ext-metered-model`).
+ * `@agentic-kit/metering`).
  */
 import type { RunEventRecord } from '../record';
 export interface UsageTotals {

package/projectors/usage.js

@@ -10,12 +10,12 @@
  *
  * This projection describes what a run *observed*. It is reconciliation input,
  * never the billing authority — a gateway-observed record is (see
- * `@agentic-kit/pi-ext-metered-model`).
+ * `@agentic-kit/metering`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.modelKey = void 0;
 exports.projectUsage = projectUsage;
-const pi_entry_1 = require("../pi-entry");
+const pi_entry_1 = require("../transcripts/pi-entry");
 const empty = () => ({
     input: 0,
     output: 0,

package/record.d.ts

@@ -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 { type PiSessionEntry } from './pi-entry';
-/** Version of the wrapper itself — bumped only if these four fields change. */
+import { type TranscriptFormat } from './transcripts/format';
+import { type PiSessionEntry } from './transcripts/pi-entry';
+/** Version of the wrapper itself — bumped only if these fields change. */
 export declare const RUN_LOG_WRAPPER_VERSION = 1;
-/** The pi session format version this package projects without migration. */
-export declare const SUPPORTED_PI_SESSION_VERSION = 3;
 export interface RunEventRecord {
     /** The run this entry belongs to. */
     runId: string;
@@ -19,9 +19,11 @@ export interface RunEventRecord {
     seq: number;
     /** When the platform durably recorded the entry (ISO 8601). */
     recordedAt: string;
-    /** pi's session format version at write time. */
-    piSessionVersion: number;
-    /** The pi session entry, byte-for-byte as pi produced it. */
+    /** The transcript the entry is encoded in, e.g. `pi`. */
+    transcriptFormat: TranscriptFormat;
+    /** That transcript's format version at write time. */
+    transcriptVersion: number;
+    /** The harness's session entry, byte-for-byte as it was produced. */
     entry: PiSessionEntry;
 }
 export interface WrapEntryOptions {
@@ -29,7 +31,8 @@ export interface WrapEntryOptions {
     seq: number;
     entry: PiSessionEntry;
     recordedAt?: string;
-    piSessionVersion?: number;
+    transcriptFormat?: TranscriptFormat;
+    transcriptVersion?: number;
 }
 export declare function wrapEntry(options: WrapEntryOptions): RunEventRecord;
 /**

package/record.js

@@ -1,24 +1,24 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_PI_SESSION_VERSION = exports.RUN_LOG_WRAPPER_VERSION = void 0;
+exports.RUN_LOG_WRAPPER_VERSION = void 0;
 exports.wrapEntry = wrapEntry;
 exports.assertRunEventRecord = assertRunEventRecord;
 exports.idempotencyKey = idempotencyKey;
 exports.assertOrdered = assertOrdered;
-const pi_entry_1 = require("./pi-entry");
-/** Version of the wrapper itself — bumped only if these four fields change. */
+const format_1 = require("./transcripts/format");
+const pi_entry_1 = require("./transcripts/pi-entry");
+/** Version of the wrapper itself — bumped only if these fields change. */
 exports.RUN_LOG_WRAPPER_VERSION = 1;
-/** The pi session format version this package projects without migration. */
-exports.SUPPORTED_PI_SESSION_VERSION = 3;
 function wrapEntry(options) {
     if (!options.runId)
         throw new TypeError('a run log record needs a runId');
@@ -29,7 +29,8 @@ function wrapEntry(options) {
         runId: options.runId,
         seq: options.seq,
         recordedAt: options.recordedAt ?? new Date().toISOString(),
-        piSessionVersion: options.piSessionVersion ?? exports.SUPPORTED_PI_SESSION_VERSION,
+        transcriptFormat: options.transcriptFormat ?? format_1.PI_TRANSCRIPT_FORMAT,
+        transcriptVersion: options.transcriptVersion ?? format_1.SUPPORTED_PI_TRANSCRIPT_VERSION,
         entry: (0, pi_entry_1.assertPiSessionEntry)(options.entry)
     };
 }
@@ -52,14 +53,18 @@ 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: (0, pi_entry_1.assertPiSessionEntry)(record.entry)
     };
 }

package/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/store.js

@@ -29,7 +29,8 @@ class MemoryRunLogStore {
                 seq: records.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 })
             });
             written.push(record);
             seen.add(key);

package/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/transcripts/format.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PI_TRANSCRIPT_VERSION = exports.PI_TRANSCRIPT_FORMAT = void 0;
+exports.assertTranscriptFormat = assertTranscriptFormat;
+/** pi's session-file entries (`@earendil-works/pi-coding-agent`). */
+exports.PI_TRANSCRIPT_FORMAT = 'pi';
+/** The pi session format version this package projects without migration. */
+exports.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.
+ */
+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`);
+}