@agentic-kit/run-log 0.3.0 → 0.5.0

package/README.md

@@ -9,21 +9,22 @@ The append-only **run log**: one ordered record of what an agent run did, wherev
 A coding agent run has to be observable from a desktop app, a web UI and a CLI; it has to be resumable after a crash, a restart, or a move from the cloud to a laptop; and it has to be meterable. Those are usually four subsystems. Here they are four *projections* of one log:
 
 ```
-pi session entries ──► run log (append-only) ──┬──► transcript parts   (what a UI draws)
-                                               ├──► usage totals       (what a run cost)
-                                               ├──► tool + approval    (what is blocked)
-                                               └──► pi session file    (how it resumes)
+harness entries ──► run log (append-only) ──┬──► transcript parts   (what a UI draws)
+                                            ├──► usage totals       (what a run cost)
+                                            ├──► tool + approval    (what is blocked)
+                                            └──► pi session file    (how it resumes)
 ```
 
-The log stores **pi entries verbatim** under four platform-owned fields. pi already versions and migrates its own session format, so re-encoding it into a second semantic event model would mean maintaining a translation layer that silently loses whatever pi adds next.
+The log stores a harness's **entries verbatim** under five platform-owned fields. A harness already versions and migrates its own session format, so re-encoding it into a second semantic event model would mean maintaining a translation layer that silently loses whatever it adds next. `transcriptFormat` is what makes that safe with more than one harness: it travels with the record, so a reader picks its projector by format and only then migrates by version.
 
 ```ts
 {
   runId,             // which run
   seq,               // 1-based, gapless, strictly increasing
   recordedAt,        // when the platform durably recorded it
-  piSessionVersion,  // pi's session format version at write time
-  entry              // the pi entry, byte-for-byte
+  transcriptFormat,  // which transcript the entry is encoded in, e.g. `pi`
+  transcriptVersion, // that transcript's format version at write time
+  entry              // the harness's entry, byte-for-byte
 }
 ```
 
@@ -100,8 +101,9 @@ Unreadable input fails loudly. A corrupt record, a mixed-version log, or a sessi
 
 ## Related
 
-- [`@agentic-kit/pi`](../pi) — Constructive's typed db tools as a pi extension
-- [`@agentic-kit/harness`](../harness) — host-neutral gates and policy
+- [`@agentic-kit/pi`](../pi) — the pi adapter: typed db tools, and the lane that mirrors pi's session entries into this log
+- [`@agentic-kit/harness`](../harness) — host-neutral gates, policy, and the harness adapter contract
+- [`@agentic-kit/metering`](../metering) — the metered gateway and usage reporting
 - [`agentic-server`](../agentic-server) — the metered inference gateway
 
 ## License

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

@@ -13,7 +13,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { projectSession } from './projectors/session';
-import { assertRunEventRecord, idempotencyKey, SUPPORTED_PI_SESSION_VERSION, wrapEntry } from './record';
+import { assertRunEventRecord, idempotencyKey, wrapEntry } from './record';
 import { cursorAfter, START } from './store';
 export class FileRunLogStore {
     path;
@@ -54,7 +54,8 @@ export class FileRunLogStore {
                 seq: existing.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 })
             }));
             seen.add(key);
         }

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

@@ -8,11 +8,13 @@
  */
 export { constructiveEntryTypes, EntryTypeRegistry } from './entry-types';
 export { follow, readAll } from './follow';
-export { assertPiSessionEntry, contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from './pi-entry';
+export { SessionMirror } from './mirror';
 export { projectParts } from './projectors/parts';
 export { parseSessionJsonl, projectSession } from './projectors/session';
 export { projectSpans } from './projectors/spans';
 export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, approvalRequestMessage, approvalResolutionMessage, assertApprovalRequestDetails, assertApprovalResolutionDetails, assertGateDecisionDetails, GATE_DECISION_TYPE, gateDecisionMessage, projectToolState } from './projectors/tool-state';
 export { modelKey, projectUsage } from './projectors/usage';
-export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, SUPPORTED_PI_SESSION_VERSION, wrapEntry } from './record';
+export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, wrapEntry } from './record';
 export { cursorAfter, MemoryRunLogStore, START } from './store';
+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';

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

@@ -0,0 +1,87 @@
+/**
+ * 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 { assertPiSessionEntry } from './transcripts/pi-entry';
+export 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 ?? 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;
+    }
+}
+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/esm/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/esm/projectors/parts.js

@@ -7,7 +7,7 @@
  * `unknown` part rather than disappearing — a log written by a newer pi still
  * renders, minus the detail this version understands.
  */
-import { contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from '../pi-entry';
+import { contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from '../transcripts/pi-entry';
 /**
  * Project records into a conversation. Pure and total: the same records always
  * produce the same parts, whichever host wrote them.

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

@@ -9,8 +9,9 @@
  * 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 { isPiSessionHeader } from '../pi-entry';
-import { assertOrdered, SUPPORTED_PI_SESSION_VERSION } from '../record';
+import { assertOrdered } from '../record';
+import { assertTranscriptFormat, PI_TRANSCRIPT_FORMAT, SUPPORTED_PI_TRANSCRIPT_VERSION } from '../transcripts/format';
+import { isPiSessionHeader } from '../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
@@ -18,11 +19,12 @@ import { assertOrdered, SUPPORTED_PI_SESSION_VERSION } from '../record';
  */
 export function projectSession(records, options = {}) {
     assertOrdered(records);
-    const versions = new Set(records.map((record) => record.piSessionVersion));
+    assertTranscriptFormat(records, 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 ?? SUPPORTED_PI_SESSION_VERSION;
+    const transcriptVersion = records[0]?.transcriptVersion ?? SUPPORTED_PI_TRANSCRIPT_VERSION;
     const entries = records.map((record) => record.entry);
     const headerIndex = entries.findIndex(isPiSessionHeader);
     if (headerIndex > 0) {
@@ -33,7 +35,7 @@ export 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 } : {})
@@ -41,7 +43,7 @@ export function projectSession(records, options = {}) {
     const ordered = [header, ...body];
     return {
         entries: ordered,
-        piSessionVersion,
+        transcriptVersion,
         jsonl: ordered.map((entry) => JSON.stringify(entry)).join('\n') + '\n'
     };
 }

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

@@ -15,7 +15,7 @@
  * `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 { contentText, isAssistantMessage, isPiMessageEntry, isToolResultMessage, toolCalls } from '../pi-entry';
+import { contentText, isAssistantMessage, isPiMessageEntry, isToolResultMessage, toolCalls } from '../transcripts/pi-entry';
 import { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, assertGateDecisionDetails, GATE_DECISION_TYPE } from './tool-state';
 const ms = (from, to) => {
     const start = Date.parse(from);

package/esm/projectors/tool-state.js

@@ -8,7 +8,7 @@
  * having been present when it was raised, and both placements then behave the
  * same — the cloud already treats the conversation as the approval UI.
  */
-import { contentText, isAssistantMessage, isPiMessageEntry, isToolResultMessage, toolCalls } from '../pi-entry';
+import { contentText, isAssistantMessage, isPiMessageEntry, isToolResultMessage, toolCalls } from '../transcripts/pi-entry';
 /** `customType` of an approval request written by the gate extension. */
 export const APPROVAL_REQUEST_TYPE = 'constructive.approval.request';
 /** `customType` of the human's answer to a request. */

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

@@ -9,9 +9,9 @@
  *
  * 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 { isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isToolResultMessage } from '../pi-entry';
+import { isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isToolResultMessage } from '../transcripts/pi-entry';
 const empty = () => ({
     input: 0,
     output: 0,

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