@agentic-kit/run-log 0.2.0 → 0.4.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
 }
 ```
 
@@ -77,17 +78,32 @@ for await (const batch of follow(store, 'run-1', { waitForChange })) {
 | --- | --- |
 | `projectParts` | the renderable transcript — a tool call and its later result collapse into one part, so no renderer correlates messages itself |
 | `projectUsage` | tokens and cost, per `provider/model` and per run, including nested tool usage and compaction calls |
-| `projectToolState` | what is running, and what is waiting on a human (approvals ride in the log as pi `custom` messages, so a surface that reconnects hours later still sees a pending request) |
+| `projectToolState` | what is running, what is waiting on a human, and how the gate settled each call (approvals and gate decisions ride in the log as pi `custom` messages, so a surface that reconnects hours later still sees a pending request) |
+| `projectSpans` | how long each step took, and inside what — tool spans (call → result), model spans, approval spans (request → answer) with parents, for a timeline |
 | `projectSession` | a pi session file — the resume path, cloud → local included |
 
-All four are pure and total: the same records always produce the same output, whichever host wrote them, which is the property the tests assert as *placement invariance*.
+All of them are pure and total: the same records always produce the same output, whichever host wrote them, which is the property the tests assert as *placement invariance*.
+
+A span 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 (`timing: 'bounded' | 'measured'`) and a tool span carries its approval wait separately. An interval that never closed stays `open` with no duration, because a run still in flight must not look like one that finished.
+
+## Entry types
+
+New event kinds are namespaced pi `custom` messages, not new tables: the log stores entries verbatim, so a type is only a `customType` string plus a validator. `constructiveEntryTypes()` is the registry of the ones this platform writes — approval requests and answers, and `constructive.gate.decision` — each pairing a details type with a runtime assertion, a label, and a visibility:
+
+| Visibility | Meaning |
+| --- | --- |
+| `surface` | part of the conversation the model sees — an approval question and its answer |
+| `log-only` | audit and trace data, never fed back to the model — a gate decision, which the model already learned of through the blocked call's error |
+
+An unregistered type is `log-only`: a trace view showing an unknown row is right, a prompt built from one is not.
 
 Unreadable input fails loudly. A corrupt record, a mixed-version log, or a session whose header is not first throws rather than degrading into an empty transcript — a run that silently renders as blank is worse than one that reports it cannot be read. An *unknown* entry type is different: it is carried through as an `unknown` part, so a log written by a newer pi still renders.
 
 ## 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/entry-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The entry-type registry: the one place that says what a `custom` entry in a
+ * run log means.
+ *
+ * pi's session format is extensible through `custom` messages, and Constructive
+ * uses that seam rather than new tables — an approval, a gate decision, a future
+ * command are all entries in the same append-only log, so a new kind of event
+ * costs a registration here and no schema change at all.
+ *
+ * Two things are registered per type. A `details` guard, because the payload
+ * arrives from a database column or an HTTP body and a projector must not read
+ * it untyped. And a *visibility*: whether the entry is part of what the model
+ * sees (`surface`) or a record only humans and tooling read (`log-only`). pi
+ * decides what to replay from the entries it wrote itself, so the flag does not
+ * steer the agent loop; it tells a renderer which rows belong to the
+ * conversation and which belong to the trace, and it documents intent for the
+ * writer.
+ */
+/**
+ * Whether an entry contributes to the conversation the model sees.
+ *
+ * - `surface`: the entry is (or becomes) part of the model's context — an
+ *   approval prompt the agent must react to, for instance.
+ * - `log-only`: durable, replayable, projected into traces and audits, but
+ *   never part of what the model reads. A gate decision is the archetype: the
+ *   model already learned of a denial through the blocked tool call's error.
+ */
+export type EntryVisibility = 'surface' | 'log-only';
+/** What the registry knows about one `customType`. */
+export interface EntryTypeDefinition<TDetails = unknown> {
+    /** The namespaced discriminator, e.g. `constructive.gate.decision`. */
+    customType: string;
+    visibility: EntryVisibility;
+    /** Short human label — a renderer's fallback row title. */
+    label: string;
+    /**
+     * Narrow the entry's `details`. Throws rather than returning null: a payload
+     * that cannot be read is a corrupted entry, never an empty one.
+     */
+    assertDetails: (value: unknown) => TDetails;
+}
+/**
+ * A registry of `custom` entry types.
+ *
+ * Registration is by value rather than by module side effect so a host can hold
+ * its own registry (a test, a downstream package adding its own vocabulary)
+ * without mutating everyone else's.
+ */
+export declare class EntryTypeRegistry {
+    private readonly types;
+    constructor(definitions?: readonly EntryTypeDefinition<never>[]);
+    /** Register a type. Re-registering the same `customType` is a programming error. */
+    register<TDetails>(definition: EntryTypeDefinition<TDetails>): this;
+    /** The definition for a `customType`, or undefined when nothing claims it. */
+    get(customType: string): EntryTypeDefinition<unknown> | undefined;
+    has(customType: string): boolean;
+    /** Every registered type, in registration order. */
+    list(): readonly EntryTypeDefinition<unknown>[];
+    /**
+     * The visibility of a `customType`. An unregistered type is `log-only`: a
+     * renderer showing an unknown row in the trace is right, and one feeding it
+     * to a model would not be.
+     */
+    visibilityOf(customType: string): EntryVisibility;
+}
+/**
+ * The types Constructive itself writes.
+ *
+ * A host that adds its own vocabulary registers onto a copy
+ * (`constructiveEntryTypes()`) rather than mutating a shared singleton, so one
+ * package's registration cannot surprise another's projector.
+ */
+export declare const constructiveEntryTypes: () => EntryTypeRegistry;

package/entry-types.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * The entry-type registry: the one place that says what a `custom` entry in a
+ * run log means.
+ *
+ * pi's session format is extensible through `custom` messages, and Constructive
+ * uses that seam rather than new tables — an approval, a gate decision, a future
+ * command are all entries in the same append-only log, so a new kind of event
+ * costs a registration here and no schema change at all.
+ *
+ * Two things are registered per type. A `details` guard, because the payload
+ * arrives from a database column or an HTTP body and a projector must not read
+ * it untyped. And a *visibility*: whether the entry is part of what the model
+ * sees (`surface`) or a record only humans and tooling read (`log-only`). pi
+ * decides what to replay from the entries it wrote itself, so the flag does not
+ * steer the agent loop; it tells a renderer which rows belong to the
+ * conversation and which belong to the trace, and it documents intent for the
+ * writer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructiveEntryTypes = exports.EntryTypeRegistry = void 0;
+const tool_state_1 = require("./projectors/tool-state");
+/**
+ * A registry of `custom` entry types.
+ *
+ * Registration is by value rather than by module side effect so a host can hold
+ * its own registry (a test, a downstream package adding its own vocabulary)
+ * without mutating everyone else's.
+ */
+class EntryTypeRegistry {
+    types = new Map();
+    constructor(definitions = []) {
+        for (const definition of definitions)
+            this.register(definition);
+    }
+    /** Register a type. Re-registering the same `customType` is a programming error. */
+    register(definition) {
+        if (this.types.has(definition.customType)) {
+            throw new Error(`entry type ${definition.customType} is already registered`);
+        }
+        this.types.set(definition.customType, definition);
+        return this;
+    }
+    /** The definition for a `customType`, or undefined when nothing claims it. */
+    get(customType) {
+        return this.types.get(customType);
+    }
+    has(customType) {
+        return this.types.has(customType);
+    }
+    /** Every registered type, in registration order. */
+    list() {
+        return Array.from(this.types.values());
+    }
+    /**
+     * The visibility of a `customType`. An unregistered type is `log-only`: a
+     * renderer showing an unknown row in the trace is right, and one feeding it
+     * to a model would not be.
+     */
+    visibilityOf(customType) {
+        return this.types.get(customType)?.visibility ?? 'log-only';
+    }
+}
+exports.EntryTypeRegistry = EntryTypeRegistry;
+/**
+ * The types Constructive itself writes.
+ *
+ * A host that adds its own vocabulary registers onto a copy
+ * (`constructiveEntryTypes()`) rather than mutating a shared singleton, so one
+ * package's registration cannot surprise another's projector.
+ */
+const constructiveEntryTypes = () => new EntryTypeRegistry()
+    .register({
+    customType: tool_state_1.APPROVAL_REQUEST_TYPE,
+    // The agent is blocked on this one, and a reconnecting surface must be
+    // able to see it — it belongs to the conversation.
+    visibility: 'surface',
+    label: 'Approval requested',
+    assertDetails: tool_state_1.assertApprovalRequestDetails
+})
+    .register({
+    customType: tool_state_1.APPROVAL_RESOLUTION_TYPE,
+    visibility: 'surface',
+    label: 'Approval answered',
+    assertDetails: tool_state_1.assertApprovalResolutionDetails
+})
+    .register({
+    customType: tool_state_1.GATE_DECISION_TYPE,
+    visibility: 'log-only',
+    label: 'Gate decision',
+    assertDetails: (value) => (0, tool_state_1.assertGateDecisionDetails)(value)
+});
+exports.constructiveEntryTypes = constructiveEntryTypes;

package/esm/entry-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The entry-type registry: the one place that says what a `custom` entry in a
+ * run log means.
+ *
+ * pi's session format is extensible through `custom` messages, and Constructive
+ * uses that seam rather than new tables — an approval, a gate decision, a future
+ * command are all entries in the same append-only log, so a new kind of event
+ * costs a registration here and no schema change at all.
+ *
+ * Two things are registered per type. A `details` guard, because the payload
+ * arrives from a database column or an HTTP body and a projector must not read
+ * it untyped. And a *visibility*: whether the entry is part of what the model
+ * sees (`surface`) or a record only humans and tooling read (`log-only`). pi
+ * decides what to replay from the entries it wrote itself, so the flag does not
+ * steer the agent loop; it tells a renderer which rows belong to the
+ * conversation and which belong to the trace, and it documents intent for the
+ * writer.
+ */
+/**
+ * Whether an entry contributes to the conversation the model sees.
+ *
+ * - `surface`: the entry is (or becomes) part of the model's context — an
+ *   approval prompt the agent must react to, for instance.
+ * - `log-only`: durable, replayable, projected into traces and audits, but
+ *   never part of what the model reads. A gate decision is the archetype: the
+ *   model already learned of a denial through the blocked tool call's error.
+ */
+export type EntryVisibility = 'surface' | 'log-only';
+/** What the registry knows about one `customType`. */
+export interface EntryTypeDefinition<TDetails = unknown> {
+    /** The namespaced discriminator, e.g. `constructive.gate.decision`. */
+    customType: string;
+    visibility: EntryVisibility;
+    /** Short human label — a renderer's fallback row title. */
+    label: string;
+    /**
+     * Narrow the entry's `details`. Throws rather than returning null: a payload
+     * that cannot be read is a corrupted entry, never an empty one.
+     */
+    assertDetails: (value: unknown) => TDetails;
+}
+/**
+ * A registry of `custom` entry types.
+ *
+ * Registration is by value rather than by module side effect so a host can hold
+ * its own registry (a test, a downstream package adding its own vocabulary)
+ * without mutating everyone else's.
+ */
+export declare class EntryTypeRegistry {
+    private readonly types;
+    constructor(definitions?: readonly EntryTypeDefinition<never>[]);
+    /** Register a type. Re-registering the same `customType` is a programming error. */
+    register<TDetails>(definition: EntryTypeDefinition<TDetails>): this;
+    /** The definition for a `customType`, or undefined when nothing claims it. */
+    get(customType: string): EntryTypeDefinition<unknown> | undefined;
+    has(customType: string): boolean;
+    /** Every registered type, in registration order. */
+    list(): readonly EntryTypeDefinition<unknown>[];
+    /**
+     * The visibility of a `customType`. An unregistered type is `log-only`: a
+     * renderer showing an unknown row in the trace is right, and one feeding it
+     * to a model would not be.
+     */
+    visibilityOf(customType: string): EntryVisibility;
+}
+/**
+ * The types Constructive itself writes.
+ *
+ * A host that adds its own vocabulary registers onto a copy
+ * (`constructiveEntryTypes()`) rather than mutating a shared singleton, so one
+ * package's registration cannot surprise another's projector.
+ */
+export declare const constructiveEntryTypes: () => EntryTypeRegistry;

package/esm/entry-types.js

@@ -0,0 +1,88 @@
+/**
+ * The entry-type registry: the one place that says what a `custom` entry in a
+ * run log means.
+ *
+ * pi's session format is extensible through `custom` messages, and Constructive
+ * uses that seam rather than new tables — an approval, a gate decision, a future
+ * command are all entries in the same append-only log, so a new kind of event
+ * costs a registration here and no schema change at all.
+ *
+ * Two things are registered per type. A `details` guard, because the payload
+ * arrives from a database column or an HTTP body and a projector must not read
+ * it untyped. And a *visibility*: whether the entry is part of what the model
+ * sees (`surface`) or a record only humans and tooling read (`log-only`). pi
+ * decides what to replay from the entries it wrote itself, so the flag does not
+ * steer the agent loop; it tells a renderer which rows belong to the
+ * conversation and which belong to the trace, and it documents intent for the
+ * writer.
+ */
+import { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, assertApprovalRequestDetails, assertApprovalResolutionDetails, assertGateDecisionDetails, GATE_DECISION_TYPE } from './projectors/tool-state';
+/**
+ * A registry of `custom` entry types.
+ *
+ * Registration is by value rather than by module side effect so a host can hold
+ * its own registry (a test, a downstream package adding its own vocabulary)
+ * without mutating everyone else's.
+ */
+export class EntryTypeRegistry {
+    types = new Map();
+    constructor(definitions = []) {
+        for (const definition of definitions)
+            this.register(definition);
+    }
+    /** Register a type. Re-registering the same `customType` is a programming error. */
+    register(definition) {
+        if (this.types.has(definition.customType)) {
+            throw new Error(`entry type ${definition.customType} is already registered`);
+        }
+        this.types.set(definition.customType, definition);
+        return this;
+    }
+    /** The definition for a `customType`, or undefined when nothing claims it. */
+    get(customType) {
+        return this.types.get(customType);
+    }
+    has(customType) {
+        return this.types.has(customType);
+    }
+    /** Every registered type, in registration order. */
+    list() {
+        return Array.from(this.types.values());
+    }
+    /**
+     * The visibility of a `customType`. An unregistered type is `log-only`: a
+     * renderer showing an unknown row in the trace is right, and one feeding it
+     * to a model would not be.
+     */
+    visibilityOf(customType) {
+        return this.types.get(customType)?.visibility ?? 'log-only';
+    }
+}
+/**
+ * The types Constructive itself writes.
+ *
+ * A host that adds its own vocabulary registers onto a copy
+ * (`constructiveEntryTypes()`) rather than mutating a shared singleton, so one
+ * package's registration cannot surprise another's projector.
+ */
+export const constructiveEntryTypes = () => new EntryTypeRegistry()
+    .register({
+    customType: APPROVAL_REQUEST_TYPE,
+    // The agent is blocked on this one, and a reconnecting surface must be
+    // able to see it — it belongs to the conversation.
+    visibility: 'surface',
+    label: 'Approval requested',
+    assertDetails: assertApprovalRequestDetails
+})
+    .register({
+    customType: APPROVAL_RESOLUTION_TYPE,
+    visibility: 'surface',
+    label: 'Approval answered',
+    assertDetails: assertApprovalResolutionDetails
+})
+    .register({
+    customType: GATE_DECISION_TYPE,
+    visibility: 'log-only',
+    label: 'Gate decision',
+    assertDetails: (value) => assertGateDecisionDetails(value)
+});

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

@@ -6,11 +6,15 @@
  * reach for a node builtin. The filesystem store lives behind
  * `@agentic-kit/run-log/file-store`.
  */
+export { constructiveEntryTypes, type EntryTypeDefinition, EntryTypeRegistry, type EntryVisibility } from './entry-types';
 export { follow, type FollowOptions, readAll } from './follow';
-export { assertPiSessionEntry, contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, type PiAssistantMessage, type PiBashExecutionMessage, type PiBranchSummaryEntry, type PiCompactionEntry, type PiContent, type PiCustomMessage, type PiEntryBase, type PiImageContent, type PiMessage, type PiMessageEntry, type PiOtherEntry, type PiSessionEntry, type PiSessionHeader, type PiSummaryMessage, type PiTextContent, type PiThinkingContent, type PiToolCallContent, type PiToolResultMessage, type PiUsage, type PiUsageCost, type PiUserMessage, toolCalls } from './pi-entry';
+export { type SessionEntrySource, SessionMirror, type SessionMirrorOptions } from './mirror';
 export { type BashPart, type Conversation, type ConversationPart, type CustomPart, projectParts, type SummaryPart, type TextPart, type ThinkingPart, type ToolPart, type ToolStatus, type UnknownPart } from './projectors/parts';
 export { parseSessionJsonl, projectSession, type SessionProjection, type SessionProjectionOptions } from './projectors/session';
-export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, type ApprovalRequestInput, approvalRequestMessage, type ApprovalResolutionInput, approvalResolutionMessage, type ApprovalState, projectToolState, type ToolCallState, type ToolCallStatus, type ToolStateProjection } from './projectors/tool-state';
+export { type ApprovalSpan, type ModelSpan, projectSpans, type Span, type SpanBase, type SpanKind, type SpanProjection, type SpanStatus, type SpanTiming, type ToolSpan } from './projectors/spans';
+export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, type ApprovalRequestInput, approvalRequestMessage, type ApprovalResolutionInput, approvalResolutionMessage, type ApprovalState, assertApprovalRequestDetails, assertApprovalResolutionDetails, assertGateDecisionDetails, GATE_DECISION_TYPE, type GateDecisionDetails, gateDecisionMessage, type GateDecisionState, projectToolState, type ToolCallState, type ToolCallStatus, type ToolStateProjection } from './projectors/tool-state';
 export { modelKey, type ModelUsage, projectUsage, type RunUsage, type UsageTotals } from './projectors/usage';
-export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, type RunEventRecord, SUPPORTED_PI_SESSION_VERSION, wrapEntry, type WrapEntryOptions } from './record';
+export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, type RunEventRecord, wrapEntry, type WrapEntryOptions } from './record';
 export { type AppendOptions, cursorAfter, MemoryRunLogStore, type RunLogAppendStore, type RunLogCursor, type RunLogPage, type RunLogReadStore, type RunLogStore, START } from './store';
+export { assertTranscriptFormat, PI_TRANSCRIPT_FORMAT, SUPPORTED_PI_TRANSCRIPT_VERSION, type TranscriptFormat } from './transcripts/format';
+export { assertPiSessionEntry, contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, type PiAssistantMessage, type PiBashExecutionMessage, type PiBranchSummaryEntry, type PiCompactionEntry, type PiContent, type PiCustomMessage, type PiEntryBase, type PiImageContent, type PiMessage, type PiMessageEntry, type PiOtherEntry, type PiSessionEntry, type PiSessionHeader, type PiSummaryMessage, type PiTextContent, type PiThinkingContent, type PiToolCallContent, type PiToolResultMessage, type PiUsage, type PiUsageCost, type PiUserMessage, toolCalls } from './transcripts/pi-entry';

package/esm/index.js

@@ -6,11 +6,15 @@
  * reach for a node builtin. The filesystem store lives behind
  * `@agentic-kit/run-log/file-store`.
  */
+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 { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, approvalRequestMessage, approvalResolutionMessage, projectToolState } from './projectors/tool-state';
+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.