@agentic-kit/run-log 0.2.0

package/projectors/tool-state.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * Tool and approval projection: run log records → the state a UI needs to know
+ * what is running and what is waiting on a human.
+ *
+ * Approvals ride in the log as pi `custom` messages rather than a side channel,
+ * because "the run is blocked on you" is part of the run's history: a surface
+ * that reconnects hours later must be able to see a pending request without
+ * having been present when it was raised, and both placements then behave the
+ * 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.projectToolState = projectToolState;
+const pi_entry_1 = require("../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';
+const details = (value) => typeof value === 'object' && value !== null ? value : {};
+function projectToolState(records) {
+    const tools = {};
+    const approvals = new Map();
+    for (const { entry, seq } of records) {
+        if (!(0, pi_entry_1.isPiMessageEntry)(entry))
+            continue;
+        const message = entry.message;
+        if ((0, pi_entry_1.isAssistantMessage)(message)) {
+            for (const call of (0, pi_entry_1.toolCalls)(message)) {
+                tools[call.id] = {
+                    toolCallId: call.id,
+                    name: call.name,
+                    arguments: call.arguments ?? {},
+                    status: 'requested',
+                    requestedSeq: seq
+                };
+            }
+            continue;
+        }
+        if ((0, pi_entry_1.isToolResultMessage)(message)) {
+            const state = tools[message.toolCallId];
+            const settled = {
+                status: message.isError ? 'failed' : 'completed',
+                settledSeq: seq,
+                output: (0, pi_entry_1.contentText)(message.content)
+            };
+            tools[message.toolCallId] = state
+                ? { ...state, ...settled }
+                : {
+                    toolCallId: message.toolCallId,
+                    name: message.toolName,
+                    arguments: {},
+                    requestedSeq: seq,
+                    status: settled.status,
+                    settledSeq: seq,
+                    output: settled.output
+                };
+            continue;
+        }
+        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 approval = {
+                toolCallId,
+                requestedSeq: seq,
+                prompt: (0, pi_entry_1.contentText)(message.content)
+            };
+            approvals.set(toolCallId, approval);
+            const state = tools[toolCallId];
+            if (state)
+                tools[toolCallId] = { ...state, status: 'awaiting-approval', approval };
+            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 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 } : {})
+            };
+            approvals.set(toolCallId, approval);
+            const state = tools[toolCallId];
+            if (state && state.status === 'awaiting-approval') {
+                tools[toolCallId] = { ...state, status: approved ? 'running' : 'rejected', approval };
+            }
+            else if (state) {
+                tools[toolCallId] = { ...state, approval };
+            }
+        }
+    }
+    const pendingApprovals = Array.from(approvals.values())
+        .filter((approval) => approval.resolvedSeq === undefined)
+        .sort((a, b) => a.requestedSeq - b.requestedSeq);
+    return { tools, pendingApprovals };
+}
+/** Build the pi `custom` message an approval request is carried in. */
+const approvalRequestMessage = (input) => ({
+    role: 'custom',
+    customType: exports.APPROVAL_REQUEST_TYPE,
+    content: input.prompt,
+    display: true,
+    details: { toolCallId: input.toolCallId },
+    timestamp: Date.now()
+});
+exports.approvalRequestMessage = approvalRequestMessage;
+/** Build the pi `custom` message a human's answer is carried in. */
+const approvalResolutionMessage = (input) => ({
+    role: 'custom',
+    customType: exports.APPROVAL_RESOLUTION_TYPE,
+    content: input.reason ?? input.decision,
+    display: true,
+    details: {
+        toolCallId: input.toolCallId,
+        decision: input.decision,
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.actorId ? { actorId: input.actorId } : {})
+    },
+    timestamp: Date.now()
+});
+exports.approvalResolutionMessage = approvalResolutionMessage;

package/projectors/usage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Usage projection: run log records → token and cost totals.
+ *
+ * Every usage-bearing pi entry counts, not just assistant messages: a tool that
+ * performed nested LLM work reports `usage` on its result, and compaction and
+ * branch summaries are model calls the run paid for. Missing any of those makes
+ * a run look cheaper than it was, which is exactly the kind of drift metering
+ * exists to prevent.
+ *
+ * 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`).
+ */
+import type { RunEventRecord } from '../record';
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: number;
+    /** Number of usage-bearing entries folded into these totals. */
+    calls: number;
+}
+export interface ModelUsage extends UsageTotals {
+    provider: string;
+    model: string;
+}
+export interface RunUsage extends UsageTotals {
+    /** Per provider+model breakdown, keyed `provider/model`. */
+    byModel: Record<string, ModelUsage>;
+}
+export declare const modelKey: (provider: string, model: string) => string;
+/** Fold every usage-bearing entry in the records into run totals. */
+export declare function projectUsage(records: readonly RunEventRecord[]): RunUsage;

package/projectors/usage.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Usage projection: run log records → token and cost totals.
+ *
+ * Every usage-bearing pi entry counts, not just assistant messages: a tool that
+ * performed nested LLM work reports `usage` on its result, and compaction and
+ * branch summaries are model calls the run paid for. Missing any of those makes
+ * a run look cheaper than it was, which is exactly the kind of drift metering
+ * exists to prevent.
+ *
+ * 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`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelKey = void 0;
+exports.projectUsage = projectUsage;
+const pi_entry_1 = require("../pi-entry");
+const empty = () => ({
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: 0,
+    calls: 0
+});
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+function fold(target, usage) {
+    const input = num(usage.input);
+    const output = num(usage.output);
+    const cacheRead = num(usage.cacheRead);
+    const cacheWrite = num(usage.cacheWrite);
+    target.input += input;
+    target.output += output;
+    target.cacheRead += cacheRead;
+    target.cacheWrite += cacheWrite;
+    // Providers that omit a total still have one: the parts they did report.
+    target.totalTokens += usage.totalTokens === undefined
+        ? input + output + cacheRead + cacheWrite
+        : num(usage.totalTokens);
+    target.cost += num(usage.cost?.total);
+    target.calls += 1;
+}
+const modelKey = (provider, model) => `${provider}/${model}`;
+exports.modelKey = modelKey;
+/** Fold every usage-bearing entry in the records into run totals. */
+function projectUsage(records) {
+    const totals = { ...empty(), byModel: {} };
+    const add = (usage, provider = 'unknown', model = 'unknown') => {
+        if (!usage)
+            return;
+        fold(totals, usage);
+        const key = (0, exports.modelKey)(provider, model);
+        const bucket = totals.byModel[key] ?? { ...empty(), provider, model };
+        fold(bucket, usage);
+        totals.byModel[key] = bucket;
+    };
+    let lastProvider = 'unknown';
+    let lastModel = 'unknown';
+    for (const { entry } of records) {
+        if ((0, pi_entry_1.isPiMessageEntry)(entry)) {
+            const message = entry.message;
+            if ((0, pi_entry_1.isAssistantMessage)(message)) {
+                lastProvider = message.provider ?? lastProvider;
+                lastModel = message.model ?? lastModel;
+                add(message.usage, message.provider ?? 'unknown', message.model ?? 'unknown');
+            }
+            else if ((0, pi_entry_1.isToolResultMessage)(message)) {
+                // Nested model work inside a tool: attributed to the run's current model,
+                // which is the model that requested the tool.
+                add(message.usage, lastProvider, lastModel);
+            }
+            continue;
+        }
+        if ((0, pi_entry_1.isPiCompactionEntry)(entry) || (0, pi_entry_1.isPiBranchSummaryEntry)(entry)) {
+            add(entry.usage, lastProvider, lastModel);
+        }
+    }
+    return totals;
+}

package/record.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The run log record: four platform-owned fields around a verbatim pi 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.
+ */
+import { type PiSessionEntry } from './pi-entry';
+/** Version of the wrapper itself — bumped only if these four 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;
+    /** 1-based position within the run. Gapless and strictly increasing. */
+    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. */
+    entry: PiSessionEntry;
+}
+export interface WrapEntryOptions {
+    runId: string;
+    seq: number;
+    entry: PiSessionEntry;
+    recordedAt?: string;
+    piSessionVersion?: number;
+}
+export declare function wrapEntry(options: WrapEntryOptions): RunEventRecord;
+/**
+ * Narrow an untrusted record (database row, HTTP body). Throws on anything
+ * unreadable — a log that cannot be parsed must fail loudly, never silently
+ * render as an empty conversation.
+ */
+export declare function assertRunEventRecord(value: unknown): RunEventRecord;
+/**
+ * The de-duplication key for an append. pi entry ids are unique within a
+ * session, so a retried append (a Job restart re-emitting its tail, a
+ * reconnecting writer) is recognised rather than duplicated.
+ */
+export declare function idempotencyKey(runId: string, entry: PiSessionEntry): string;
+/** Records must be contiguous and in order before anything projects them. */
+export declare function assertOrdered(records: readonly RunEventRecord[]): void;

package/record.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * The run log record: four platform-owned fields around a verbatim pi 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PI_SESSION_VERSION = 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. */
+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');
+    if (!Number.isInteger(options.seq) || options.seq < 1) {
+        throw new TypeError(`run log seq must be a positive integer, received ${String(options.seq)}`);
+    }
+    return {
+        runId: options.runId,
+        seq: options.seq,
+        recordedAt: options.recordedAt ?? new Date().toISOString(),
+        piSessionVersion: options.piSessionVersion ?? exports.SUPPORTED_PI_SESSION_VERSION,
+        entry: (0, pi_entry_1.assertPiSessionEntry)(options.entry)
+    };
+}
+/**
+ * Narrow an untrusted record (database row, HTTP body). Throws on anything
+ * unreadable — a log that cannot be parsed must fail loudly, never silently
+ * render as an empty conversation.
+ */
+function assertRunEventRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError(`run log record must be an object, received ${typeof value}`);
+    }
+    const record = value;
+    if (typeof record.runId !== 'string' || record.runId.length === 0) {
+        throw new TypeError('run log record must carry a non-empty runId');
+    }
+    if (!Number.isInteger(record.seq) || record.seq < 1) {
+        throw new TypeError(`run log record ${record.runId} has an invalid seq: ${String(record.seq)}`);
+    }
+    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`);
+    }
+    return {
+        runId: record.runId,
+        seq: record.seq,
+        recordedAt: record.recordedAt,
+        piSessionVersion: record.piSessionVersion,
+        entry: (0, pi_entry_1.assertPiSessionEntry)(record.entry)
+    };
+}
+/**
+ * The de-duplication key for an append. pi entry ids are unique within a
+ * session, so a retried append (a Job restart re-emitting its tail, a
+ * reconnecting writer) is recognised rather than duplicated.
+ */
+function idempotencyKey(runId, entry) {
+    const id = typeof entry.id === 'string' ? entry.id : null;
+    if (id)
+        return `${runId}:${entry.type}:${id}`;
+    // Session headers carry no tree id; there is exactly one per session file.
+    return `${runId}:${entry.type}:${String(entry.id ?? 'header')}`;
+}
+/** Records must be contiguous and in order before anything projects them. */
+function assertOrdered(records) {
+    for (let i = 1; i < records.length; i += 1) {
+        const previous = records[i - 1];
+        const current = records[i];
+        if (current.runId !== previous.runId) {
+            throw new Error(`run log records mix runs: ${previous.runId} then ${current.runId} at index ${String(i)}`);
+        }
+        if (current.seq <= previous.seq) {
+            throw new Error(`run log records out of order in ${current.runId}: seq ${String(previous.seq)} followed by ${String(current.seq)}`);
+        }
+    }
+}

package/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The storage contract. A run log is append-only and read by cursor, so the
+ * interfaces are deliberately two: a writer (the agent host) and a reader
+ * (every UI surface, the resume path, the usage rollup). Concrete stores live
+ * 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';
+/** Read position: `afterSeq` is exclusive, so `0` means "from the start". */
+export interface RunLogCursor {
+    afterSeq: number;
+}
+export declare const START: RunLogCursor;
+export declare const cursorAfter: (records: readonly RunEventRecord[], from?: RunLogCursor) => RunLogCursor;
+export interface RunLogPage {
+    records: RunEventRecord[];
+    cursor: RunLogCursor;
+}
+export interface AppendOptions {
+    /** pi session format version the entries were produced under. */
+    piSessionVersion?: number;
+    recordedAt?: string;
+}
+export interface RunLogAppendStore {
+    /**
+     * Append entries to a run, returning the records actually written. Entries
+     * already present (matched by pi entry id) are skipped, which makes an append
+     * safe to retry.
+     */
+    append(runId: string, entries: readonly PiSessionEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
+}
+export interface RunLogReadStore {
+    read(runId: string, cursor?: RunLogCursor, limit?: number): Promise<RunLogPage>;
+}
+export type RunLogStore = RunLogAppendStore & RunLogReadStore;
+/** In-memory store: the reference implementation and the test double. */
+export declare class MemoryRunLogStore implements RunLogStore {
+    private readonly runs;
+    private readonly seen;
+    append(runId: string, entries: readonly PiSessionEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
+    read(runId: string, cursor?: RunLogCursor, limit?: number): Promise<RunLogPage>;
+    /** Test/debug helper: every record of a run, ignoring cursors. */
+    snapshot(runId: string): RunEventRecord[];
+    runIds(): string[];
+}

package/store.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * The storage contract. A run log is append-only and read by cursor, so the
+ * interfaces are deliberately two: a writer (the agent host) and a reader
+ * (every UI surface, the resume path, the usage rollup). Concrete stores live
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRunLogStore = exports.cursorAfter = exports.START = void 0;
+const record_1 = require("./record");
+exports.START = { afterSeq: 0 };
+const cursorAfter = (records, from = exports.START) => records.length === 0 ? from : { afterSeq: records[records.length - 1].seq };
+exports.cursorAfter = cursorAfter;
+/** In-memory store: the reference implementation and the test double. */
+class MemoryRunLogStore {
+    runs = new Map();
+    seen = new Map();
+    async append(runId, entries, options = {}) {
+        const records = this.runs.get(runId) ?? [];
+        const seen = this.seen.get(runId) ?? new Set();
+        const written = [];
+        for (const entry of entries) {
+            const key = (0, record_1.idempotencyKey)(runId, entry);
+            if (seen.has(key))
+                continue;
+            const record = (0, record_1.wrapEntry)({
+                runId,
+                seq: records.length + written.length + 1,
+                entry,
+                ...(options.recordedAt ? { recordedAt: options.recordedAt } : {}),
+                piSessionVersion: options.piSessionVersion ?? record_1.SUPPORTED_PI_SESSION_VERSION
+            });
+            written.push(record);
+            seen.add(key);
+        }
+        this.runs.set(runId, records.concat(written));
+        this.seen.set(runId, seen);
+        return written;
+    }
+    async read(runId, cursor = exports.START, limit) {
+        const all = this.runs.get(runId) ?? [];
+        const after = all.filter((record) => record.seq > cursor.afterSeq);
+        const records = typeof limit === 'number' ? after.slice(0, limit) : after;
+        (0, record_1.assertOrdered)(records);
+        return { records, cursor: (0, exports.cursorAfter)(records, cursor) };
+    }
+    /** Test/debug helper: every record of a run, ignoring cursors. */
+    snapshot(runId) {
+        return (this.runs.get(runId) ?? []).slice();
+    }
+    runIds() {
+        return Array.from(this.runs.keys());
+    }
+}
+exports.MemoryRunLogStore = MemoryRunLogStore;