@agentic-kit/run-log 0.2.0

package/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/pi-entry.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isToolResultMessage = exports.isAssistantMessage = exports.isPiBranchSummaryEntry = exports.isPiCompactionEntry = exports.isPiMessageEntry = exports.isPiSessionHeader = void 0;
+exports.assertPiSessionEntry = assertPiSessionEntry;
+exports.contentText = contentText;
+exports.toolCalls = toolCalls;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isPiSessionHeader = (entry) => entry.type === 'session';
+exports.isPiSessionHeader = isPiSessionHeader;
+const isPiMessageEntry = (entry) => entry.type === 'message' && isRecord(entry.message);
+exports.isPiMessageEntry = isPiMessageEntry;
+const isPiCompactionEntry = (entry) => entry.type === 'compaction';
+exports.isPiCompactionEntry = isPiCompactionEntry;
+const isPiBranchSummaryEntry = (entry) => entry.type === 'branch_summary';
+exports.isPiBranchSummaryEntry = isPiBranchSummaryEntry;
+const isAssistantMessage = (message) => message.role === 'assistant';
+exports.isAssistantMessage = isAssistantMessage;
+const isToolResultMessage = (message) => message.role === 'toolResult';
+exports.isToolResultMessage = isToolResultMessage;
+/**
+ * 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.
+ */
+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. */
+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. */
+function toolCalls(message) {
+    if (!Array.isArray(message.content))
+        return [];
+    return message.content.filter((block) => isRecord(block) && block.type === 'toolCall');
+}

package/projectors/parts.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Renderable projection: run log records → an ordered list of parts a UI draws.
+ *
+ * This is the projection that replaces per-host transcript encodings. A tool
+ * call and its later result collapse into one part, so a renderer never has to
+ * correlate two messages itself, and an unknown entry type becomes an
+ * `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';
+export type ToolStatus = 'requested' | 'completed' | 'failed';
+export interface PartBase {
+    /** Sequence of the record that introduced the part — a stable React key. */
+    seq: number;
+    entryId?: string;
+}
+export interface TextPart extends PartBase {
+    kind: 'text';
+    role: 'user' | 'assistant';
+    text: string;
+    model?: string;
+    provider?: string;
+}
+export interface ThinkingPart extends PartBase {
+    kind: 'thinking';
+    text: string;
+}
+export interface ToolPart extends PartBase {
+    kind: 'tool';
+    toolCallId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    status: ToolStatus;
+    /** Text of the tool result, once one has been logged. */
+    output?: string;
+    details?: unknown;
+    /** Sequence of the record that settled the call. */
+    settledSeq?: number;
+}
+export interface BashPart extends PartBase {
+    kind: 'bash';
+    command: string;
+    output: string;
+    exitCode?: number;
+}
+export interface CustomPart extends PartBase {
+    kind: 'custom';
+    customType: string;
+    text: string;
+    display: boolean;
+    details?: unknown;
+}
+export interface SummaryPart extends PartBase {
+    kind: 'summary';
+    reason: 'compaction' | 'branch';
+    summary: string;
+}
+export interface UnknownPart extends PartBase {
+    kind: 'unknown';
+    entryType: string;
+    entry: PiSessionEntry;
+}
+export type ConversationPart = TextPart | ThinkingPart | ToolPart | BashPart | CustomPart | SummaryPart | UnknownPart;
+export interface Conversation {
+    parts: ConversationPart[];
+    /** From the session header, when the log carries one. */
+    sessionId?: string;
+    cwd?: string;
+}
+/**
+ * Project records into a conversation. Pure and total: the same records always
+ * produce the same parts, whichever host wrote them.
+ */
+export declare function projectParts(records: readonly RunEventRecord[]): Conversation;

package/projectors/parts.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Renderable projection: run log records → an ordered list of parts a UI draws.
+ *
+ * This is the projection that replaces per-host transcript encodings. A tool
+ * call and its later result collapse into one part, so a renderer never has to
+ * correlate two messages itself, and an unknown entry type becomes an
+ * `unknown` part rather than disappearing — a log written by a newer pi still
+ * renders, minus the detail this version understands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectParts = projectParts;
+const pi_entry_1 = require("../pi-entry");
+/**
+ * Project records into a conversation. Pure and total: the same records always
+ * produce the same parts, whichever host wrote them.
+ */
+function projectParts(records) {
+    const parts = [];
+    const toolsByCallId = new Map();
+    let sessionId;
+    let cwd;
+    for (const record of records) {
+        const { entry, seq } = record;
+        if ((0, pi_entry_1.isPiSessionHeader)(entry)) {
+            sessionId = entry.id;
+            if (typeof entry.cwd === 'string')
+                cwd = entry.cwd;
+            continue;
+        }
+        if ((0, pi_entry_1.isPiCompactionEntry)(entry)) {
+            parts.push({ kind: 'summary', reason: 'compaction', summary: entry.summary, seq, entryId: entry.id });
+            continue;
+        }
+        if ((0, pi_entry_1.isPiBranchSummaryEntry)(entry)) {
+            parts.push({ kind: 'summary', reason: 'branch', summary: entry.summary, seq, entryId: entry.id });
+            continue;
+        }
+        if (!(0, pi_entry_1.isPiMessageEntry)(entry)) {
+            parts.push({ kind: 'unknown', entryType: entry.type, entry, seq, entryId: entry.id });
+            continue;
+        }
+        const message = entry.message;
+        const base = { seq, entryId: entry.id };
+        if (message.role === 'user') {
+            parts.push({ kind: 'text', role: 'user', text: (0, pi_entry_1.contentText)(message.content), ...base });
+            continue;
+        }
+        if ((0, pi_entry_1.isAssistantMessage)(message)) {
+            for (const block of Array.isArray(message.content) ? message.content : []) {
+                if (block.type === 'text' && block.text.length > 0) {
+                    parts.push({
+                        kind: 'text',
+                        role: 'assistant',
+                        text: block.text,
+                        ...(message.model ? { model: message.model } : {}),
+                        ...(message.provider ? { provider: message.provider } : {}),
+                        ...base
+                    });
+                }
+                else if (block.type === 'thinking') {
+                    parts.push({ kind: 'thinking', text: block.thinking, ...base });
+                }
+            }
+            for (const call of (0, pi_entry_1.toolCalls)(message)) {
+                const part = {
+                    kind: 'tool',
+                    toolCallId: call.id,
+                    name: call.name,
+                    arguments: call.arguments ?? {},
+                    status: 'requested',
+                    ...base
+                };
+                toolsByCallId.set(call.id, part);
+                parts.push(part);
+            }
+            continue;
+        }
+        if ((0, pi_entry_1.isToolResultMessage)(message)) {
+            const existing = toolsByCallId.get(message.toolCallId);
+            const output = (0, pi_entry_1.contentText)(message.content);
+            const status = message.isError ? 'failed' : 'completed';
+            if (existing) {
+                existing.status = status;
+                existing.output = output;
+                existing.settledSeq = seq;
+                if (message.details !== undefined)
+                    existing.details = message.details;
+            }
+            else {
+                // A result whose call is not in this window (paged read, forked branch).
+                parts.push({
+                    kind: 'tool',
+                    toolCallId: message.toolCallId,
+                    name: message.toolName,
+                    arguments: {},
+                    status,
+                    output,
+                    settledSeq: seq,
+                    ...base
+                });
+            }
+            continue;
+        }
+        if (message.role === 'bashExecution') {
+            parts.push({
+                kind: 'bash',
+                command: message.command,
+                output: message.output,
+                ...(typeof message.exitCode === 'number' ? { exitCode: message.exitCode } : {}),
+                ...base
+            });
+            continue;
+        }
+        if (message.role === 'custom') {
+            parts.push({
+                kind: 'custom',
+                customType: message.customType,
+                text: (0, pi_entry_1.contentText)(message.content),
+                display: message.display !== false,
+                ...(message.details !== undefined ? { details: message.details } : {}),
+                ...base
+            });
+            continue;
+        }
+        parts.push({
+            kind: 'summary',
+            reason: message.role === 'branchSummary' ? 'branch' : 'compaction',
+            summary: message.summary ?? '',
+            ...base
+        });
+    }
+    return {
+        parts,
+        ...(sessionId ? { sessionId } : {}),
+        ...(cwd ? { cwd } : {})
+    };
+}

package/projectors/session.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session projection: run log records → a pi session file.
+ *
+ * This is what makes a run resumable anywhere. The log is the source of truth;
+ * a `.jsonl` session is a derived artifact, so a run that started in the cloud
+ * can be continued locally (and vice versa) by projecting the log back into the
+ * only format pi's `SessionManager` reads.
+ *
+ * Returns a string rather than writing a file: the projection is pure, and the
+ * node-side write lives in `@agentic-kit/run-log/file-store`.
+ */
+import { type PiSessionEntry } from '../pi-entry';
+import { type RunEventRecord } from '../record';
+export interface SessionProjectionOptions {
+    /** Used when the log carries no session header (a run logged headerless). */
+    sessionId?: string;
+    cwd?: string;
+    timestamp?: string;
+}
+export interface SessionProjection {
+    /** The full session file contents, newline-terminated. */
+    jsonl: string;
+    /** Entries in file order, header first. */
+    entries: PiSessionEntry[];
+    piSessionVersion: number;
+}
+/**
+ * Project records into a pi session file. Throws when the records cannot form a
+ * loadable session — an unresumable session must fail at projection time, not
+ * when pi later reads a truncated tree.
+ */
+export declare function projectSession(records: readonly RunEventRecord[], options?: SessionProjectionOptions): SessionProjection;
+/** Parse a pi session file into entries — the inverse, for importing a session. */
+export declare function parseSessionJsonl(jsonl: string): PiSessionEntry[];

package/projectors/session.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Session projection: run log records → a pi session file.
+ *
+ * This is what makes a run resumable anywhere. The log is the source of truth;
+ * a `.jsonl` session is a derived artifact, so a run that started in the cloud
+ * can be continued locally (and vice versa) by projecting the log back into the
+ * only format pi's `SessionManager` reads.
+ *
+ * Returns a string rather than writing a file: the projection is pure, and the
+ * node-side write lives in `@agentic-kit/run-log/file-store`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectSession = projectSession;
+exports.parseSessionJsonl = parseSessionJsonl;
+const pi_entry_1 = require("../pi-entry");
+const record_1 = require("../record");
+/**
+ * Project records into a pi session file. Throws when the records cannot form a
+ * loadable session — an unresumable session must fail at projection time, not
+ * when pi later reads a truncated tree.
+ */
+function projectSession(records, options = {}) {
+    (0, record_1.assertOrdered)(records);
+    const versions = new Set(records.map((record) => record.piSessionVersion));
+    if (versions.size > 1) {
+        throw new Error(`run log mixes pi session versions (${Array.from(versions).sort().join(', ')}); migrate the older entries before projecting a session`);
+    }
+    const piSessionVersion = records[0]?.piSessionVersion ?? record_1.SUPPORTED_PI_SESSION_VERSION;
+    const entries = records.map((record) => record.entry);
+    const headerIndex = entries.findIndex(pi_entry_1.isPiSessionHeader);
+    if (headerIndex > 0) {
+        throw new Error(`run log carries a session header at position ${String(headerIndex)}; a pi session file requires it first`);
+    }
+    const body = headerIndex === 0 ? entries.slice(1) : entries;
+    const header = headerIndex === 0
+        ? entries[0]
+        : {
+            type: 'session',
+            version: piSessionVersion,
+            id: options.sessionId ?? records[0]?.runId ?? 'run-log',
+            timestamp: options.timestamp ?? records[0]?.recordedAt ?? new Date().toISOString(),
+            ...(options.cwd ? { cwd: options.cwd } : {})
+        };
+    const ordered = [header, ...body];
+    return {
+        entries: ordered,
+        piSessionVersion,
+        jsonl: ordered.map((entry) => JSON.stringify(entry)).join('\n') + '\n'
+    };
+}
+/** Parse a pi session file into entries — the inverse, for importing a session. */
+function parseSessionJsonl(jsonl) {
+    const entries = [];
+    const lines = jsonl.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (line.length === 0)
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`pi session line ${String(i + 1)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return entries;
+}

package/projectors/tool-state.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+import type { RunEventRecord } from '../record';
+/** `customType` of an approval request written by the gate extension. */
+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";
+export type ToolCallStatus = 'requested' | 'awaiting-approval' | 'rejected' | 'running' | 'completed' | 'failed';
+export interface ToolCallState {
+    toolCallId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    status: ToolCallStatus;
+    requestedSeq: number;
+    settledSeq?: number;
+    output?: string;
+    approval?: ApprovalState;
+}
+export interface ApprovalState {
+    toolCallId: string;
+    requestedSeq: number;
+    prompt: string;
+    resolvedSeq?: number;
+    decision?: 'approved' | 'rejected';
+    reason?: string;
+    actorId?: string;
+}
+export interface ToolStateProjection {
+    tools: Record<string, ToolCallState>;
+    /** In log order — the oldest unanswered request first. */
+    pendingApprovals: ApprovalState[];
+}
+export declare function projectToolState(records: readonly RunEventRecord[]): ToolStateProjection;
+/** The parts of an approval request an extension needs to write one. */
+export interface ApprovalRequestInput {
+    toolCallId: string;
+    prompt: string;
+}
+export interface ApprovalResolutionInput {
+    toolCallId: string;
+    decision: 'approved' | 'rejected';
+    reason?: string;
+    actorId?: string;
+}
+/** Build the pi `custom` message an approval request is carried in. */
+export declare const approvalRequestMessage: (input: ApprovalRequestInput) => {
+    role: "custom";
+    customType: string;
+    content: string;
+    display: boolean;
+    details: {
+        toolCallId: string;
+    };
+    timestamp: number;
+};
+/** Build the pi `custom` message a human's answer is carried in. */
+export declare const approvalResolutionMessage: (input: ApprovalResolutionInput) => {
+    role: "custom";
+    customType: string;
+    content: string;
+    display: boolean;
+    details: {
+        actorId?: string;
+        reason?: string;
+        toolCallId: string;
+        decision: "rejected" | "approved";
+    };
+    timestamp: number;
+};