@agentic-kit/run-log 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+# @agentic-kit/run-log
+
+The append-only **run log**: one ordered record of what an agent run did, wherever it ran.
+
+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)
+```
+
+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.
+
+```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
+}
+```
+
+## Install
+
+```sh
+npm install @agentic-kit/run-log
+```
+
+## Writing
+
+Writing is an `append` against a store. Appends are **idempotent by pi entry id**, so a writer that restarts and replays its tail does not duplicate history.
+
+```ts
+import { MemoryRunLogStore } from '@agentic-kit/run-log';
+
+const store = new MemoryRunLogStore();
+await store.append('run-1', [entry]);        // → the records actually written
+await store.append('run-1', [entry]);        // → [] — already present
+```
+
+Two stores ship here: `MemoryRunLogStore` (the reference implementation, and the test double) and `FileRunLogStore` from the node-only entry point:
+
+```ts
+import { FileRunLogStore, writeSessionFile } from '@agentic-kit/run-log/file-store';
+```
+
+The main entry is **browser-safe** — renderers import the projectors, so nothing in it may reach for a node builtin. Anything touching the filesystem lives behind `/file-store` (the same split, for the same reason, as `12factor-env/dotenv`).
+
+The durable store is Postgres, in `constructive-db`: `append` becomes an insert, `read` a keyset scan. Neither is in this package, because the interface is the contract.
+
+## Reading
+
+Every surface is the same reader: hold a cursor, ask for what came after it. That is what makes a local run and a cloud run indistinguishable to a UI.
+
+```ts
+import { follow, projectParts, readAll } from '@agentic-kit/run-log';
+
+const records = await readAll(store, 'run-1');
+
+for await (const batch of follow(store, 'run-1', { waitForChange })) {
+  render(projectParts(batch).parts);
+}
+```
+
+`waitForChange` (Postgres `LISTEN/NOTIFY`, IPC, a websocket) is an *optimisation*: it races the poll delay, and without one `follow` degrades to polling. No new transport is required for a run to stream.
+
+## Projections
+
+| Projection | Answers |
+| --- | --- |
+| `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) |
+| `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*.
+
+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-server`](../agentic-server) — the metered inference gateway
+
+## License
+
+SEE LICENSE IN LICENSE
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/file-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@agentic-kit/run-log/file-store` — the node-only JSONL store.
+ *
+ * A separate entry point because the package's main entry is imported by
+ * browsers, Electron renderers and Next client components; a `node:fs` import
+ * there breaks those bundles. Same split, same reason, as `12factor-env/dotenv`.
+ *
+ * The file holds one wrapped record per line, so a run is recoverable with
+ * `tail -f` and a partially-written last line is detectable rather than silently
+ * 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';
+export interface FileRunLogStoreOptions {
+    /** Absolute path of the log file. Parent directories are created. */
+    path: string;
+}
+export declare class FileRunLogStore implements RunLogStore {
+    private readonly path;
+    constructor(options: FileRunLogStoreOptions);
+    private load;
+    append(runId: string, entries: readonly PiSessionEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
+    read(runId: string, cursor?: RunLogCursor, limit?: number): Promise<RunLogPage>;
+}
+/**
+ * Write the run's pi session file so `SessionManager.open` can resume it. This
+ * is the cloud→local (and local→local restart) resume path: project, write,
+ * hand the path to pi.
+ */
+export declare function writeSessionFile(path: string, records: readonly RunEventRecord[], options?: SessionProjectionOptions): string;

package/esm/file-store.js

@@ -0,0 +1,85 @@
+/**
+ * `@agentic-kit/run-log/file-store` — the node-only JSONL store.
+ *
+ * A separate entry point because the package's main entry is imported by
+ * browsers, Electron renderers and Next client components; a `node:fs` import
+ * there breaks those bundles. Same split, same reason, as `12factor-env/dotenv`.
+ *
+ * The file holds one wrapped record per line, so a run is recoverable with
+ * `tail -f` and a partially-written last line is detectable rather than silently
+ * 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 { 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 { cursorAfter, START } from './store';
+export class FileRunLogStore {
+    path;
+    constructor(options) {
+        this.path = options.path;
+    }
+    load() {
+        if (!existsSync(this.path))
+            return [];
+        const contents = readFileSync(this.path, 'utf8');
+        const records = [];
+        const lines = contents.split('\n');
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i].trim();
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch (error) {
+                throw new Error(`run log ${this.path} line ${String(i + 1)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            records.push(assertRunEventRecord(parsed));
+        }
+        return records;
+    }
+    async append(runId, entries, options = {}) {
+        const existing = this.load().filter((record) => record.runId === runId);
+        const seen = new Set(existing.map((record) => idempotencyKey(runId, record.entry)));
+        const written = [];
+        for (const entry of entries) {
+            const key = idempotencyKey(runId, entry);
+            if (seen.has(key))
+                continue;
+            written.push(wrapEntry({
+                runId,
+                seq: existing.length + written.length + 1,
+                entry,
+                ...(options.recordedAt ? { recordedAt: options.recordedAt } : {}),
+                piSessionVersion: options.piSessionVersion ?? SUPPORTED_PI_SESSION_VERSION
+            }));
+            seen.add(key);
+        }
+        if (written.length === 0)
+            return written;
+        mkdirSync(dirname(this.path), { recursive: true });
+        if (!existsSync(this.path))
+            writeFileSync(this.path, '', { mode: 0o600 });
+        appendFileSync(this.path, written.map((record) => JSON.stringify(record)).join('\n') + '\n');
+        return written;
+    }
+    async read(runId, cursor = START, limit) {
+        const after = this.load().filter((record) => record.runId === runId && record.seq > cursor.afterSeq);
+        const records = typeof limit === 'number' ? after.slice(0, limit) : after;
+        return { records, cursor: cursorAfter(records, cursor) };
+    }
+}
+/**
+ * Write the run's pi session file so `SessionManager.open` can resume it. This
+ * is the cloud→local (and local→local restart) resume path: project, write,
+ * hand the path to pi.
+ */
+export function writeSessionFile(path, records, options = {}) {
+    const projection = projectSession(records, options);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, projection.jsonl, { mode: 0o600 });
+    return path;
+}

package/esm/follow.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Following a run log.
+ *
+ * Every surface — a desktop chat pane, a web execution view, a CLI tail, the
+ * resume path — is the same reader: hold a cursor, ask for what came after it.
+ * That is what makes local and cloud runs indistinguishable to a UI, so this is
+ * the only reader loop in the system.
+ *
+ * A push wakeup (LISTEN/NOTIFY, IPC, websocket) is an optimisation, not a
+ * requirement: `waitForChange` short-circuits the delay when it resolves, and
+ * without one the loop degrades to polling at `pollIntervalMs`.
+ */
+import type { RunEventRecord } from './record';
+import { type RunLogCursor, type RunLogReadStore } from './store';
+export interface FollowOptions {
+    cursor?: RunLogCursor;
+    /** Polling delay when no wakeup arrives. */
+    pollIntervalMs?: number;
+    /** Records per read. */
+    limit?: number;
+    /** Resolves when the run may have new records; races the poll delay. */
+    waitForChange?: (signal?: AbortSignal) => Promise<void>;
+    /** Stop following once this returns true for the batch just yielded. */
+    isTerminal?: (records: readonly RunEventRecord[]) => boolean;
+    signal?: AbortSignal;
+    /** Injectable for tests; defaults to `setTimeout`. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Yield every batch of new records until the run reaches a terminal state or
+ * the caller aborts. Batches are yielded as read, so a caller can project
+ * incrementally rather than re-projecting the whole run per frame.
+ */
+export declare function follow(store: RunLogReadStore, runId: string, options?: FollowOptions): AsyncGenerator<RunEventRecord[], void, void>;
+/** Read a run to its current end in one pass. */
+export declare function readAll(store: RunLogReadStore, runId: string, cursor?: RunLogCursor, pageLimit?: number): Promise<RunEventRecord[]>;

package/esm/follow.js

@@ -0,0 +1,65 @@
+/**
+ * Following a run log.
+ *
+ * Every surface — a desktop chat pane, a web execution view, a CLI tail, the
+ * resume path — is the same reader: hold a cursor, ask for what came after it.
+ * That is what makes local and cloud runs indistinguishable to a UI, so this is
+ * the only reader loop in the system.
+ *
+ * A push wakeup (LISTEN/NOTIFY, IPC, websocket) is an optimisation, not a
+ * requirement: `waitForChange` short-circuits the delay when it resolves, and
+ * without one the loop degrades to polling at `pollIntervalMs`.
+ */
+import { cursorAfter, START } from './store';
+const defaultSleep = (ms, signal) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        resolve();
+    }, { once: true });
+});
+/**
+ * Yield every batch of new records until the run reaches a terminal state or
+ * the caller aborts. Batches are yielded as read, so a caller can project
+ * incrementally rather than re-projecting the whole run per frame.
+ */
+export async function* follow(store, runId, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 500;
+    const sleep = options.sleep ?? defaultSleep;
+    let cursor = options.cursor ?? START;
+    while (!options.signal?.aborted) {
+        const page = await store.read(runId, cursor, options.limit);
+        if (page.records.length > 0) {
+            cursor = cursorAfter(page.records, cursor);
+            yield page.records;
+            if (options.isTerminal?.(page.records))
+                return;
+            // Drain before waiting: a burst of tool output should not be paced by the
+            // poll interval.
+            continue;
+        }
+        if (options.waitForChange) {
+            await Promise.race([
+                options.waitForChange(options.signal),
+                sleep(pollIntervalMs, options.signal)
+            ]);
+        }
+        else {
+            await sleep(pollIntervalMs, options.signal);
+        }
+    }
+}
+/** Read a run to its current end in one pass. */
+export async function readAll(store, runId, cursor = START, pageLimit = 500) {
+    const records = [];
+    let position = cursor;
+    for (;;) {
+        const page = await store.read(runId, position, pageLimit);
+        if (page.records.length === 0)
+            return records;
+        records.push(...page.records);
+        position = cursorAfter(page.records, position);
+        if (page.records.length < pageLimit)
+            return records;
+    }
+}

package/esm/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@agentic-kit/run-log` — the append-only run log: one ordered record of what
+ * an agent run did, wherever it ran.
+ *
+ * Browser-safe on purpose: renderers import the projectors, so nothing here may
+ * reach for a node builtin. The filesystem store lives behind
+ * `@agentic-kit/run-log/file-store`.
+ */
+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 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 { 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 { type AppendOptions, cursorAfter, MemoryRunLogStore, type RunLogAppendStore, type RunLogCursor, type RunLogPage, type RunLogReadStore, type RunLogStore, START } from './store';

package/esm/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@agentic-kit/run-log` — the append-only run log: one ordered record of what
+ * an agent run did, wherever it ran.
+ *
+ * Browser-safe on purpose: renderers import the projectors, so nothing here may
+ * reach for a node builtin. The filesystem store lives behind
+ * `@agentic-kit/run-log/file-store`.
+ */
+export { follow, readAll } from './follow';
+export { assertPiSessionEntry, contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from './pi-entry';
+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 { modelKey, projectUsage } from './projectors/usage';
+export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, SUPPORTED_PI_SESSION_VERSION, wrapEntry } from './record';
+export { cursorAfter, MemoryRunLogStore, START } from './store';

package/esm/pi-entry.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The structural subset of pi's session entries this package reads.
+ *
+ * Deliberately structural, not imported from pi: a run log stores pi entries
+ * *verbatim*, so the types here describe what the projectors read rather than
+ * re-declaring pi's format. Every interface keeps an index signature so an
+ * entry produced by a newer pi still parses, and unknown `type` values are
+ * carried through untouched instead of being dropped.
+ *
+ * Reference: `@earendil-works/pi-coding-agent` `docs/session-format.md`
+ * (session file version 3).
+ */
+export interface PiUsageCost {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    total?: number;
+}
+export interface PiUsage {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    totalTokens?: number;
+    cost?: PiUsageCost;
+    [key: string]: unknown;
+}
+export interface PiTextContent {
+    type: 'text';
+    text: string;
+}
+export interface PiThinkingContent {
+    type: 'thinking';
+    thinking: string;
+}
+export interface PiImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+export interface PiToolCallContent {
+    type: 'toolCall';
+    id: string;
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+export type PiContent = PiTextContent | PiThinkingContent | PiImageContent | PiToolCallContent;
+export interface PiUserMessage {
+    role: 'user';
+    content: string | PiContent[];
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface PiAssistantMessage {
+    role: 'assistant';
+    content: PiContent[];
+    api?: string;
+    provider?: string;
+    model?: string;
+    usage?: PiUsage;
+    stopReason?: 'stop' | 'length' | 'toolUse' | 'error' | 'aborted';
+    errorMessage?: string;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface PiToolResultMessage {
+    role: 'toolResult';
+    toolCallId: string;
+    toolName: string;
+    content: PiContent[];
+    details?: unknown;
+    usage?: PiUsage;
+    isError?: boolean;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface PiBashExecutionMessage {
+    role: 'bashExecution';
+    command: string;
+    output: string;
+    exitCode?: number;
+    cancelled?: boolean;
+    truncated?: boolean;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface PiCustomMessage {
+    role: 'custom';
+    customType: string;
+    content: string | PiContent[];
+    display?: boolean;
+    details?: unknown;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface PiSummaryMessage {
+    role: 'branchSummary' | 'compactionSummary';
+    summary: string;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export type PiMessage = PiUserMessage | PiAssistantMessage | PiToolResultMessage | PiBashExecutionMessage | PiCustomMessage | PiSummaryMessage;
+export interface PiSessionHeader {
+    type: 'session';
+    version: number;
+    id: string;
+    timestamp: string;
+    cwd?: string;
+    parentSession?: string;
+    [key: string]: unknown;
+}
+export interface PiEntryBase {
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export interface PiMessageEntry extends PiEntryBase {
+    type: 'message';
+    message: PiMessage;
+    [key: string]: unknown;
+}
+export interface PiCompactionEntry extends PiEntryBase {
+    type: 'compaction';
+    summary: string;
+    tokensBefore?: number;
+    usage?: PiUsage;
+    [key: string]: unknown;
+}
+export interface PiBranchSummaryEntry extends PiEntryBase {
+    type: 'branch_summary';
+    summary: string;
+    fromId: string;
+    usage?: PiUsage;
+    [key: string]: unknown;
+}
+export interface PiOtherEntry extends PiEntryBase {
+    type: string;
+    [key: string]: unknown;
+}
+export type PiSessionEntry = PiSessionHeader | PiMessageEntry | PiCompactionEntry | PiBranchSummaryEntry | PiOtherEntry;
+export declare const isPiSessionHeader: (entry: PiSessionEntry) => entry is PiSessionHeader;
+export declare const isPiMessageEntry: (entry: PiSessionEntry) => entry is PiMessageEntry;
+export declare const isPiCompactionEntry: (entry: PiSessionEntry) => entry is PiCompactionEntry;
+export declare const isPiBranchSummaryEntry: (entry: PiSessionEntry) => entry is PiBranchSummaryEntry;
+export declare const isAssistantMessage: (message: PiMessage) => message is PiAssistantMessage;
+export declare const isToolResultMessage: (message: PiMessage) => message is PiToolResultMessage;
+/**
+ * Narrow an untrusted value (a database JSONB column, an HTTP body) to a pi
+ * entry. Throws rather than returning null: a log row that cannot be read is a
+ * corrupted log, never an empty one.
+ */
+export declare function assertPiSessionEntry(value: unknown): PiSessionEntry;
+/** The text of a message's content, whether it is a string or a block array. */
+export declare function contentText(content: string | PiContent[] | undefined): string;
+/** Tool calls requested by an assistant message, in order. */
+export declare function toolCalls(message: PiAssistantMessage): PiToolCallContent[];

package/esm/pi-entry.js

@@ -0,0 +1,61 @@
+/**
+ * The structural subset of pi's session entries this package reads.
+ *
+ * Deliberately structural, not imported from pi: a run log stores pi entries
+ * *verbatim*, so the types here describe what the projectors read rather than
+ * re-declaring pi's format. Every interface keeps an index signature so an
+ * entry produced by a newer pi still parses, and unknown `type` values are
+ * carried through untouched instead of being dropped.
+ *
+ * Reference: `@earendil-works/pi-coding-agent` `docs/session-format.md`
+ * (session file version 3).
+ */
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const isPiSessionHeader = (entry) => entry.type === 'session';
+export const isPiMessageEntry = (entry) => entry.type === 'message' && isRecord(entry.message);
+export const isPiCompactionEntry = (entry) => entry.type === 'compaction';
+export const isPiBranchSummaryEntry = (entry) => entry.type === 'branch_summary';
+export const isAssistantMessage = (message) => message.role === 'assistant';
+export const isToolResultMessage = (message) => message.role === 'toolResult';
+/**
+ * Narrow an untrusted value (a database JSONB column, an HTTP body) to a pi
+ * entry. Throws rather than returning null: a log row that cannot be read is a
+ * corrupted log, never an empty one.
+ */
+export function assertPiSessionEntry(value) {
+    if (!isRecord(value)) {
+        throw new TypeError(`pi session entry must be an object, received ${typeof value}`);
+    }
+    if (typeof value.type !== 'string' || value.type.length === 0) {
+        throw new TypeError('pi session entry must carry a non-empty string `type`');
+    }
+    if (value.type !== 'session') {
+        if (typeof value.id !== 'string' || value.id.length === 0) {
+            throw new TypeError(`pi ${value.type} entry must carry a non-empty string \`id\``);
+        }
+        if (typeof value.timestamp !== 'string') {
+            throw new TypeError(`pi ${value.type} entry must carry an ISO string \`timestamp\``);
+        }
+        if (!('parentId' in value)) {
+            throw new TypeError(`pi ${value.type} entry must carry \`parentId\` (null for the first entry)`);
+        }
+    }
+    return value;
+}
+/** The text of a message's content, whether it is a string or a block array. */
+export function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((block) => isRecord(block) && block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+}
+/** Tool calls requested by an assistant message, in order. */
+export function toolCalls(message) {
+    if (!Array.isArray(message.content))
+        return [];
+    return message.content.filter((block) => isRecord(block) && block.type === 'toolCall');
+}