@agentic-kit/run-log 0.2.0 → 0.4.0

package/projectors/spans.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectSpans = projectSpans;
+const pi_entry_1 = require("../transcripts/pi-entry");
+const tool_state_1 = require("./tool-state");
+const ms = (from, to) => {
+    const start = Date.parse(from);
+    const end = Date.parse(to);
+    if (Number.isNaN(start) || Number.isNaN(end))
+        return undefined;
+    return end - start;
+};
+const close = (span, seq, at) => {
+    span.endSeq = seq;
+    span.endedAt = at;
+    const duration = ms(span.startedAt, at);
+    if (duration !== undefined)
+        span.durationMs = duration;
+};
+const detailsOf = (value) => typeof value === 'object' && value !== null ? value : {};
+/**
+ * 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.
+ */
+function projectSpans(records) {
+    const spans = [];
+    const tools = new Map();
+    const approvals = new Map();
+    /**
+     * The end of the previous entry, which is the earliest the next model call
+     * can have begun — pi logs a response, never a request.
+     */
+    let previousAt;
+    for (const { entry, seq } of records) {
+        const at = typeof entry.timestamp === 'string' ? entry.timestamp : undefined;
+        if (at === undefined)
+            continue;
+        const previous = previousAt;
+        previousAt = at;
+        if (!(0, pi_entry_1.isPiMessageEntry)(entry))
+            continue;
+        const message = entry.message;
+        if ((0, pi_entry_1.isAssistantMessage)(message)) {
+            const span = {
+                id: `model:${entry.id}`,
+                kind: 'model',
+                name: message.model ?? 'model',
+                // The turn began no earlier than the previous entry was written; with no
+                // previous entry the interval is unknown and the span is a point.
+                startedAt: previous ?? at,
+                startSeq: seq,
+                endSeq: seq,
+                endedAt: at,
+                timing: 'bounded',
+                status: message.stopReason === 'error' ? 'error' : 'ok',
+                ...(message.model ? { model: message.model } : {}),
+                ...(message.provider ? { provider: message.provider } : {}),
+                ...(typeof message.responseId === 'string' ? { responseId: message.responseId } : {}),
+                ...(message.stopReason ? { stopReason: message.stopReason } : {}),
+                ...(message.usage ? { usage: message.usage } : {}),
+                ...(message.errorMessage ? { errorMessage: message.errorMessage } : {})
+            };
+            const duration = ms(span.startedAt, at);
+            if (duration !== undefined)
+                span.durationMs = duration;
+            spans.push(span);
+            for (const call of (0, pi_entry_1.toolCalls)(message)) {
+                const tool = {
+                    id: `tool:${call.id}`,
+                    kind: 'tool',
+                    name: call.name,
+                    parentId: span.id,
+                    toolCallId: call.id,
+                    arguments: call.arguments ?? {},
+                    startedAt: at,
+                    startSeq: seq,
+                    // A call and its result are two writes; anything between them —
+                    // approval, queueing — is inside the interval.
+                    timing: 'bounded',
+                    status: 'open'
+                };
+                tools.set(call.id, tool);
+                spans.push(tool);
+            }
+            continue;
+        }
+        if ((0, pi_entry_1.isToolResultMessage)(message)) {
+            const tool = tools.get(message.toolCallId);
+            if (!tool)
+                continue;
+            close(tool, seq, at);
+            tool.status = message.isError ? 'error' : 'ok';
+            tool.output = (0, pi_entry_1.contentText)(message.content);
+            if (message.details !== undefined)
+                tool.details = message.details;
+            const approval = approvals.get(message.toolCallId);
+            if (approval?.durationMs !== undefined)
+                tool.approvalWaitMs = approval.durationMs;
+            continue;
+        }
+        if (message.role !== 'custom')
+            continue;
+        const info = detailsOf(message.details);
+        const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : undefined;
+        if (toolCallId === undefined)
+            continue;
+        if (message.customType === tool_state_1.APPROVAL_REQUEST_TYPE) {
+            const tool = tools.get(toolCallId);
+            const approval = {
+                id: `approval:${toolCallId}`,
+                kind: 'approval',
+                name: tool?.name ?? 'approval',
+                ...(tool ? { parentId: tool.id } : {}),
+                toolCallId,
+                prompt: (0, pi_entry_1.contentText)(message.content),
+                startedAt: at,
+                startSeq: seq,
+                // Request and answer are exactly the interval a human held the run.
+                timing: 'measured',
+                status: 'open'
+            };
+            approvals.set(toolCallId, approval);
+            spans.push(approval);
+            continue;
+        }
+        if (message.customType === tool_state_1.APPROVAL_RESOLUTION_TYPE) {
+            const approval = approvals.get(toolCallId);
+            if (!approval)
+                continue;
+            close(approval, seq, at);
+            const approved = info.decision === 'approved';
+            approval.decision = approved ? 'approved' : 'rejected';
+            approval.status = approved ? 'ok' : 'denied';
+            if (typeof info.actorId === 'string')
+                approval.actorId = info.actorId;
+            const tool = tools.get(toolCallId);
+            if (tool && approval.durationMs !== undefined)
+                tool.approvalWaitMs = approval.durationMs;
+            continue;
+        }
+        if (message.customType === tool_state_1.GATE_DECISION_TYPE) {
+            // Throws on a malformed decision — see the note on this function.
+            const decision = (0, tool_state_1.assertGateDecisionDetails)(message.details, seq);
+            const tool = tools.get(decision.toolCallId);
+            if (!tool)
+                continue;
+            tool.gateDecision = decision.decision;
+            if (decision.reason !== undefined)
+                tool.gateReason = decision.reason;
+            // A denied call is never executed, so this write is the only thing that
+            // will ever close its span.
+            if (decision.decision === 'deny' && tool.status === 'open') {
+                close(tool, seq, at);
+                tool.status = 'denied';
+            }
+        }
+    }
+    return { spans };
+}

package/projectors/tool-state.d.ts

@@ -13,6 +13,14 @@ import type { RunEventRecord } from '../record';
 export declare const APPROVAL_REQUEST_TYPE = "constructive.approval.request";
 /** `customType` of the human's answer to a request. */
 export declare const APPROVAL_RESOLUTION_TYPE = "constructive.approval.resolution";
+/**
+ * `customType` of a settled gate decision.
+ *
+ * Unlike an approval, this is written for *every* decision including the ones
+ * no human saw: a policy rule that denies a tool call is otherwise invisible in
+ * the log, leaving "which tool calls did the gate block" unanswerable.
+ */
+export declare const GATE_DECISION_TYPE = "constructive.gate.decision";
 export type ToolCallStatus = 'requested' | 'awaiting-approval' | 'rejected' | 'running' | 'completed' | 'failed';
 export interface ToolCallState {
     toolCallId: string;
@@ -33,12 +41,37 @@ export interface ApprovalState {
     reason?: string;
     actorId?: string;
 }
+/** A settled gate decision as it is carried in the log. */
+export interface GateDecisionDetails {
+    toolCallId: string;
+    toolName: string;
+    /** What the policy said: `allow`, `deny` or `ask`. */
+    verdict: string;
+    /** How the call was finally settled — `ask` resolves to one of these. */
+    decision: 'allow' | 'deny';
+    reason?: string;
+    actorId?: string;
+    decidedAt?: string;
+}
+export interface GateDecisionState extends GateDecisionDetails {
+    seq: number;
+}
 export interface ToolStateProjection {
     tools: Record<string, ToolCallState>;
+    /** Settled gate decisions in log order, keyed by tool call id. */
+    gateDecisions: Record<string, GateDecisionState>;
     /** In log order — the oldest unanswered request first. */
     pendingApprovals: ApprovalState[];
 }
 export declare function projectToolState(records: readonly RunEventRecord[]): ToolStateProjection;
+/** Narrow the `details` of a `constructive.gate.decision` entry. */
+export declare function assertGateDecisionDetails(value: unknown, seq?: number): GateDecisionDetails;
+/** Narrow the `details` of a `constructive.approval.request` entry. */
+export declare function assertApprovalRequestDetails(value: unknown, seq?: number): {
+    toolCallId: string;
+};
+/** Narrow the `details` of a `constructive.approval.resolution` entry. */
+export declare function assertApprovalResolutionDetails(value: unknown, seq?: number): ApprovalResolutionInput;
 /** The parts of an approval request an extension needs to write one. */
 export interface ApprovalRequestInput {
     toolCallId: string;
@@ -61,6 +94,23 @@ export declare const approvalRequestMessage: (input: ApprovalRequestInput) => {
     };
     timestamp: number;
 };
+/** Build the pi `custom` message a settled gate decision is carried in. */
+export declare const gateDecisionMessage: (input: GateDecisionDetails) => {
+    role: "custom";
+    customType: string;
+    content: string;
+    display: boolean;
+    details: {
+        decidedAt?: string;
+        actorId?: string;
+        reason?: string;
+        toolCallId: string;
+        toolName: string;
+        verdict: string;
+        decision: "allow" | "deny";
+    };
+    timestamp: number;
+};
 /** Build the pi `custom` message a human's answer is carried in. */
 export declare const approvalResolutionMessage: (input: ApprovalResolutionInput) => {
     role: "custom";

package/projectors/tool-state.js

@@ -10,17 +10,31 @@
  * same — the cloud already treats the conversation as the approval UI.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.approvalResolutionMessage = exports.approvalRequestMessage = exports.APPROVAL_RESOLUTION_TYPE = exports.APPROVAL_REQUEST_TYPE = void 0;
+exports.approvalResolutionMessage = exports.gateDecisionMessage = exports.approvalRequestMessage = exports.GATE_DECISION_TYPE = exports.APPROVAL_RESOLUTION_TYPE = exports.APPROVAL_REQUEST_TYPE = void 0;
 exports.projectToolState = projectToolState;
-const pi_entry_1 = require("../pi-entry");
+exports.assertGateDecisionDetails = assertGateDecisionDetails;
+exports.assertApprovalRequestDetails = assertApprovalRequestDetails;
+exports.assertApprovalResolutionDetails = assertApprovalResolutionDetails;
+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. */
 exports.APPROVAL_RESOLUTION_TYPE = 'constructive.approval.resolution';
+/**
+ * `customType` of a settled gate decision.
+ *
+ * Unlike an approval, this is written for *every* decision including the ones
+ * no human saw: a policy rule that denies a tool call is otherwise invisible in
+ * the log, leaving "which tool calls did the gate block" unanswerable.
+ */
+exports.GATE_DECISION_TYPE = 'constructive.gate.decision';
+/** Where a bad entry is, when the caller is projecting a log rather than validating one value. */
+const at = (seq) => (seq === undefined ? '' : ` at seq ${String(seq)}`);
 const details = (value) => typeof value === 'object' && value !== null ? value : {};
 function projectToolState(records) {
     const tools = {};
     const approvals = new Map();
+    const gateDecisions = {};
     for (const { entry, seq } of records) {
         if (!(0, pi_entry_1.isPiMessageEntry)(entry))
             continue;
@@ -60,11 +74,7 @@ function projectToolState(records) {
         if (message.role !== 'custom')
             continue;
         if (message.customType === exports.APPROVAL_REQUEST_TYPE) {
-            const info = details(message.details);
-            const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
-            if (!toolCallId) {
-                throw new Error(`approval request at seq ${String(seq)} carries no toolCallId; the run log cannot attribute it`);
-            }
+            const { toolCallId } = assertApprovalRequestDetails(message.details, seq);
             const approval = {
                 toolCallId,
                 requestedSeq: seq,
@@ -77,19 +87,16 @@ function projectToolState(records) {
             continue;
         }
         if (message.customType === exports.APPROVAL_RESOLUTION_TYPE) {
-            const info = details(message.details);
-            const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
-            if (!toolCallId) {
-                throw new Error(`approval resolution at seq ${String(seq)} carries no toolCallId; the run log cannot attribute it`);
-            }
+            const info = assertApprovalResolutionDetails(message.details, seq);
+            const toolCallId = info.toolCallId;
             const approved = info.decision === 'approved';
             const existing = approvals.get(toolCallId);
             const approval = {
                 ...(existing ?? { toolCallId, requestedSeq: seq, prompt: '' }),
                 resolvedSeq: seq,
-                decision: approved ? 'approved' : 'rejected',
-                ...(typeof info.reason === 'string' ? { reason: info.reason } : {}),
-                ...(typeof info.actorId === 'string' ? { actorId: info.actorId } : {})
+                decision: info.decision,
+                ...(info.reason === undefined ? {} : { reason: info.reason }),
+                ...(info.actorId === undefined ? {} : { actorId: info.actorId })
             };
             approvals.set(toolCallId, approval);
             const state = tools[toolCallId];
@@ -99,12 +106,72 @@ function projectToolState(records) {
             else if (state) {
                 tools[toolCallId] = { ...state, approval };
             }
+            continue;
+        }
+        if (message.customType === exports.GATE_DECISION_TYPE) {
+            const decision = assertGateDecisionDetails(message.details, seq);
+            gateDecisions[decision.toolCallId] = { ...decision, seq };
+            const state = tools[decision.toolCallId];
+            // A blocked call never produces a tool result, so the gate's `deny` is the
+            // only thing that will ever settle it.
+            if (state && decision.decision === 'deny' && state.settledSeq === undefined) {
+                tools[decision.toolCallId] = {
+                    ...state,
+                    status: 'rejected',
+                    settledSeq: seq,
+                    ...(decision.reason === undefined ? {} : { output: decision.reason })
+                };
+            }
         }
     }
     const pendingApprovals = Array.from(approvals.values())
         .filter((approval) => approval.resolvedSeq === undefined)
         .sort((a, b) => a.requestedSeq - b.requestedSeq);
-    return { tools, pendingApprovals };
+    return { tools, gateDecisions, pendingApprovals };
+}
+/** Narrow the `details` of a `constructive.gate.decision` entry. */
+function assertGateDecisionDetails(value, seq) {
+    const info = details(value);
+    const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
+    if (!toolCallId) {
+        throw new TypeError(`gate decision${at(seq)} carries no toolCallId; the run log cannot attribute it`);
+    }
+    if (info.decision !== 'allow' && info.decision !== 'deny') {
+        throw new TypeError(`gate decision${at(seq)} must settle to "allow" or "deny"`);
+    }
+    return {
+        toolCallId,
+        toolName: typeof info.toolName === 'string' ? info.toolName : '',
+        verdict: typeof info.verdict === 'string' ? info.verdict : info.decision,
+        decision: info.decision,
+        ...(typeof info.reason === 'string' ? { reason: info.reason } : {}),
+        ...(typeof info.actorId === 'string' ? { actorId: info.actorId } : {}),
+        ...(typeof info.decidedAt === 'string' ? { decidedAt: info.decidedAt } : {})
+    };
+}
+/** Narrow the `details` of a `constructive.approval.request` entry. */
+function assertApprovalRequestDetails(value, seq) {
+    const info = details(value);
+    if (typeof info.toolCallId !== 'string' || info.toolCallId.length === 0) {
+        throw new TypeError(`approval request${at(seq)} carries no toolCallId; the run log cannot attribute it`);
+    }
+    return { toolCallId: info.toolCallId };
+}
+/** Narrow the `details` of a `constructive.approval.resolution` entry. */
+function assertApprovalResolutionDetails(value, seq) {
+    const info = details(value);
+    if (typeof info.toolCallId !== 'string' || info.toolCallId.length === 0) {
+        throw new TypeError(`approval resolution${at(seq)} carries no toolCallId; the run log cannot attribute it`);
+    }
+    if (info.decision !== 'approved' && info.decision !== 'rejected') {
+        throw new TypeError(`approval resolution${at(seq)} must decide "approved" or "rejected"`);
+    }
+    return {
+        toolCallId: info.toolCallId,
+        decision: info.decision,
+        ...(typeof info.reason === 'string' ? { reason: info.reason } : {}),
+        ...(typeof info.actorId === 'string' ? { actorId: info.actorId } : {})
+    };
 }
 /** Build the pi `custom` message an approval request is carried in. */
 const approvalRequestMessage = (input) => ({
@@ -116,6 +183,26 @@ const approvalRequestMessage = (input) => ({
     timestamp: Date.now()
 });
 exports.approvalRequestMessage = approvalRequestMessage;
+/** Build the pi `custom` message a settled gate decision is carried in. */
+const gateDecisionMessage = (input) => ({
+    role: 'custom',
+    customType: exports.GATE_DECISION_TYPE,
+    content: `gate ${input.decision}: ${input.toolName}${input.reason ? ` — ${input.reason}` : ''}`,
+    // The model already learned of a denial through the blocked call's error; a
+    // second telling would only spend context.
+    display: false,
+    details: {
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        verdict: input.verdict,
+        decision: input.decision,
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.actorId ? { actorId: input.actorId } : {}),
+        ...(input.decidedAt ? { decidedAt: input.decidedAt } : {})
+    },
+    timestamp: Date.now()
+});
+exports.gateDecisionMessage = gateDecisionMessage;
 /** Build the pi `custom` message a human's answer is carried in. */
 const approvalResolutionMessage = (input) => ({
     role: 'custom',

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;