@agentic-kit/run-log 0.5.0 → 0.6.0

package/transcripts/entry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A harness's own session entry, as the log stores it.
+ *
+ * The log is deliberately not a re-encoding of a harness's transcript — an
+ * entry is kept byte-for-byte so the run stays resumable in the harness that
+ * wrote it. All the wrapper knows structurally is that an entry is an object
+ * with a `type`; what that type *means* is the reader's business, selected by
+ * the record's `transcriptFormat`.
+ */
+export interface TranscriptEntry {
+    /** The format's own entry discriminator, e.g. pi's `message`. */
+    type: string;
+    [key: string]: unknown;
+}
+export declare const isEntryRecord: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Narrow an untrusted value (a JSONB column, an HTTP body) to the structure
+ * every transcript shares. A format's own reader validates the rest.
+ */
+export declare function assertTranscriptEntry(value: unknown): TranscriptEntry;

package/transcripts/entry.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * A harness's own session entry, as the log stores it.
+ *
+ * The log is deliberately not a re-encoding of a harness's transcript — an
+ * entry is kept byte-for-byte so the run stays resumable in the harness that
+ * wrote it. All the wrapper knows structurally is that an entry is an object
+ * with a `type`; what that type *means* is the reader's business, selected by
+ * the record's `transcriptFormat`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEntryRecord = void 0;
+exports.assertTranscriptEntry = assertTranscriptEntry;
+const isEntryRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+exports.isEntryRecord = isEntryRecord;
+/**
+ * Narrow an untrusted value (a JSONB column, an HTTP body) to the structure
+ * every transcript shares. A format's own reader validates the rest.
+ */
+function assertTranscriptEntry(value) {
+    if (!(0, exports.isEntryRecord)(value)) {
+        throw new TypeError(`transcript entry must be an object, received ${typeof value}`);
+    }
+    if (typeof value.type !== 'string' || value.type.length === 0) {
+        throw new TypeError('transcript entry must carry a non-empty string `type`');
+    }
+    return value;
+}

package/transcripts/event.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The neutral vocabulary every projector reads.
+ *
+ * A projector used to know pi's message shapes, which made "render a run" and
+ * "read pi" the same capability. An event is what a transcript entry *means* —
+ * a model answered, a tool was called, a human was asked — so a format is
+ * understood in exactly one place (its `TranscriptReader`) and rendering,
+ * tracing and usage folding stop caring which harness ran.
+ *
+ * Kept close to what the projectors need rather than to any one harness: pi's
+ * `message`/`toolResult`/`custom` entries and DeepSeek Harness's
+ * `assistant/message`, `tool/call`, `tool/result` events both land here without
+ * either format's naming surviving the trip.
+ */
+import type { TranscriptEntry } from './entry';
+/** Tokens and cost as a transcript reports them — all fields optional. */
+export interface TranscriptUsage {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    totalTokens?: number;
+    cost?: {
+        total?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface TranscriptEventBase {
+    /** The entry's id in its own transcript, when the format gives entries ids. */
+    entryId?: string;
+    /** The entry's ISO timestamp, when it carries one. */
+    at?: string;
+}
+/** The transcript's opening entry: which session, and where it ran. */
+export interface SessionStartEvent extends TranscriptEventBase {
+    kind: 'session-start';
+    sessionId?: string;
+    cwd?: string;
+}
+export interface TextEvent extends TranscriptEventBase {
+    kind: 'text';
+    role: 'user' | 'assistant';
+    text: string;
+    model?: string;
+    provider?: string;
+}
+export interface ThinkingEvent extends TranscriptEventBase {
+    kind: 'thinking';
+    text: string;
+}
+/**
+ * A model finished answering. Separate from the text it produced because a
+ * trace and a usage total ask about the *call* — which model, what it cost, why
+ * it stopped — while a renderer asks about the content.
+ */
+export interface ModelResponseEvent extends TranscriptEventBase {
+    kind: 'model-response';
+    model?: string;
+    provider?: string;
+    /** The provider's response id — the join key to a metered inference row. */
+    responseId?: string;
+    stopReason?: string;
+    usage?: TranscriptUsage;
+    errorMessage?: string;
+}
+export interface ToolCallEvent extends TranscriptEventBase {
+    kind: 'tool-call';
+    toolCallId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ToolResultEvent extends TranscriptEventBase {
+    kind: 'tool-result';
+    toolCallId: string;
+    name: string;
+    output: string;
+    failed: boolean;
+    details?: unknown;
+    /** Nested model work the tool itself paid for. */
+    usage?: TranscriptUsage;
+}
+export interface BashEvent extends TranscriptEventBase {
+    kind: 'bash';
+    command: string;
+    output: string;
+    exitCode?: number;
+}
+/**
+ * A platform entry riding in the transcript — an approval request, a gate
+ * decision — discriminated by `customType` and interpreted by the entry-type
+ * registry rather than by a format's reader.
+ */
+export interface CustomEvent extends TranscriptEventBase {
+    kind: 'custom';
+    customType: string;
+    text: string;
+    /** Whether the entry is part of the conversation a human is shown. */
+    display: boolean;
+    details?: unknown;
+}
+export interface SummaryEvent extends TranscriptEventBase {
+    kind: 'summary';
+    reason: 'compaction' | 'branch';
+    summary: string;
+    usage?: TranscriptUsage;
+}
+/**
+ * An entry this reader does not understand. Carried rather than dropped: a log
+ * written by a newer harness still renders, minus the detail this version
+ * knows, and a projector never silently loses a row.
+ */
+export interface UnknownEvent extends TranscriptEventBase {
+    kind: 'unknown';
+    entryType: string;
+    entry: TranscriptEntry;
+}
+export type TranscriptEvent = SessionStartEvent | TextEvent | ThinkingEvent | ModelResponseEvent | ToolCallEvent | ToolResultEvent | BashEvent | CustomEvent | SummaryEvent | UnknownEvent;

package/transcripts/event.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * The neutral vocabulary every projector reads.
+ *
+ * A projector used to know pi's message shapes, which made "render a run" and
+ * "read pi" the same capability. An event is what a transcript entry *means* —
+ * a model answered, a tool was called, a human was asked — so a format is
+ * understood in exactly one place (its `TranscriptReader`) and rendering,
+ * tracing and usage folding stop caring which harness ran.
+ *
+ * Kept close to what the projectors need rather than to any one harness: pi's
+ * `message`/`toolResult`/`custom` entries and DeepSeek Harness's
+ * `assistant/message`, `tool/call`, `tool/result` events both land here without
+ * either format's naming surviving the trip.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/transcripts/pi-entry.d.ts

@@ -16,6 +16,7 @@ export interface PiUsageCost {
     cacheRead?: number;
     cacheWrite?: number;
     total?: number;
+    [key: string]: unknown;
 }
 export interface PiUsage {
     input?: number;

package/transcripts/pi-reader.d.ts

@@ -0,0 +1,16 @@
+/**
+ * pi's transcript reader: pi session entries → neutral events.
+ *
+ * This is the only place in the package that knows pi's message shapes. It stays
+ * here rather than in `@agentic-kit/pi` on purpose — a reader must be
+ * browser-safe, because renderers project logs client-side, while the adapter
+ * package pulls pi's node SDK. The types it reads are structural (see
+ * `./pi-entry`), so nothing here imports pi either.
+ */
+import type { TranscriptEntry } from './entry';
+import type { TranscriptEvent } from './event';
+import type { TranscriptReader } from './reader';
+/** What a single pi entry means, in order. */
+export declare function piEntryToEvents(entry: TranscriptEntry): TranscriptEvent[];
+/** pi's session-file transcript (`@earendil-works/pi-coding-agent`). */
+export declare const piTranscriptReader: TranscriptReader;

package/transcripts/pi-reader.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * pi's transcript reader: pi session entries → neutral events.
+ *
+ * This is the only place in the package that knows pi's message shapes. It stays
+ * here rather than in `@agentic-kit/pi` on purpose — a reader must be
+ * browser-safe, because renderers project logs client-side, while the adapter
+ * package pulls pi's node SDK. The types it reads are structural (see
+ * `./pi-entry`), so nothing here imports pi either.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.piTranscriptReader = void 0;
+exports.piEntryToEvents = piEntryToEvents;
+const format_1 = require("./format");
+const pi_entry_1 = require("./pi-entry");
+/** What a single pi entry means, in order. */
+function piEntryToEvents(entry) {
+    const pi = entry;
+    const base = {
+        ...(typeof pi.id === 'string' ? { entryId: pi.id } : {}),
+        ...(typeof pi.timestamp === 'string' ? { at: pi.timestamp } : {})
+    };
+    if ((0, pi_entry_1.isPiSessionHeader)(pi)) {
+        return [
+            {
+                kind: 'session-start',
+                ...base,
+                ...(typeof pi.id === 'string' ? { sessionId: pi.id } : {}),
+                ...(typeof pi.cwd === 'string' ? { cwd: pi.cwd } : {})
+            }
+        ];
+    }
+    if ((0, pi_entry_1.isPiCompactionEntry)(pi)) {
+        return [
+            { kind: 'summary', reason: 'compaction', summary: pi.summary, ...(pi.usage ? { usage: pi.usage } : {}), ...base }
+        ];
+    }
+    if ((0, pi_entry_1.isPiBranchSummaryEntry)(pi)) {
+        return [
+            { kind: 'summary', reason: 'branch', summary: pi.summary, ...(pi.usage ? { usage: pi.usage } : {}), ...base }
+        ];
+    }
+    if (!(0, pi_entry_1.isPiMessageEntry)(pi)) {
+        return [{ kind: 'unknown', entryType: pi.type, entry, ...base }];
+    }
+    const message = pi.message;
+    if (message.role === 'user') {
+        return [{ kind: 'text', role: 'user', text: (0, pi_entry_1.contentText)(message.content), ...base }];
+    }
+    if ((0, pi_entry_1.isAssistantMessage)(message)) {
+        const events = [
+            {
+                kind: 'model-response',
+                ...(message.model ? { model: message.model } : {}),
+                ...(message.provider ? { provider: message.provider } : {}),
+                ...(typeof message.responseId === 'string' ? { responseId: message.responseId } : {}),
+                ...(message.stopReason ? { stopReason: message.stopReason } : {}),
+                ...(message.usage ? { usage: message.usage } : {}),
+                ...(message.errorMessage ? { errorMessage: message.errorMessage } : {}),
+                ...base
+            }
+        ];
+        for (const block of Array.isArray(message.content) ? message.content : []) {
+            if (block.type === 'text' && block.text.length > 0) {
+                events.push({
+                    kind: 'text',
+                    role: 'assistant',
+                    text: block.text,
+                    ...(message.model ? { model: message.model } : {}),
+                    ...(message.provider ? { provider: message.provider } : {}),
+                    ...base
+                });
+            }
+            else if (block.type === 'thinking') {
+                events.push({ kind: 'thinking', text: block.thinking, ...base });
+            }
+        }
+        for (const call of (0, pi_entry_1.toolCalls)(message)) {
+            events.push({
+                kind: 'tool-call',
+                toolCallId: call.id,
+                name: call.name,
+                arguments: call.arguments ?? {},
+                ...base
+            });
+        }
+        return events;
+    }
+    if ((0, pi_entry_1.isToolResultMessage)(message)) {
+        return [
+            {
+                kind: 'tool-result',
+                toolCallId: message.toolCallId,
+                name: message.toolName,
+                output: (0, pi_entry_1.contentText)(message.content),
+                failed: message.isError === true,
+                ...(message.details === undefined ? {} : { details: message.details }),
+                ...(message.usage ? { usage: message.usage } : {}),
+                ...base
+            }
+        ];
+    }
+    if (message.role === 'bashExecution') {
+        return [
+            {
+                kind: 'bash',
+                command: message.command,
+                output: message.output,
+                ...(typeof message.exitCode === 'number' ? { exitCode: message.exitCode } : {}),
+                ...base
+            }
+        ];
+    }
+    if (message.role === 'custom') {
+        return [
+            {
+                kind: 'custom',
+                customType: message.customType,
+                text: (0, pi_entry_1.contentText)(message.content),
+                display: message.display !== false,
+                ...(message.details === undefined ? {} : { details: message.details }),
+                ...base
+            }
+        ];
+    }
+    return [
+        {
+            kind: 'summary',
+            reason: message.role === 'branchSummary' ? 'branch' : 'compaction',
+            summary: message.summary ?? '',
+            ...base
+        }
+    ];
+}
+/** pi's session-file transcript (`@earendil-works/pi-coding-agent`). */
+exports.piTranscriptReader = {
+    format: format_1.PI_TRANSCRIPT_FORMAT,
+    version: format_1.SUPPORTED_PI_TRANSCRIPT_VERSION,
+    assertEntry: pi_entry_1.assertPiSessionEntry,
+    toEvents: piEntryToEvents
+};

package/transcripts/reader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The transcript reader registry: one place per format that knows how to read
+ * it, looked up by the format a record was written under.
+ *
+ * A reader is registered *by value*, like an entry type, so a second harness
+ * ships its reader with its adapter and neither this package nor a renderer is
+ * released to support it. A record names its format, so a run that changed
+ * harness mid-flight still projects as one ordered log.
+ */
+import { type TranscriptEntry } from './entry';
+import type { TranscriptEvent } from './event';
+import type { TranscriptFormat } from './format';
+export interface TranscriptReader {
+    format: TranscriptFormat;
+    /** The format version this reader projects without migration. */
+    version: number;
+    /** Narrow an untrusted entry of this format. Throws on anything unreadable. */
+    assertEntry: (value: unknown) => TranscriptEntry;
+    /**
+     * What the entry means, in order. One entry may mean several things — a pi
+     * assistant message is a model response plus its text plus its tool calls.
+     */
+    toEvents: (entry: TranscriptEntry) => TranscriptEvent[];
+}
+export declare class TranscriptReaderRegistry {
+    private readonly readers;
+    constructor(readers?: readonly TranscriptReader[]);
+    register(reader: TranscriptReader): this;
+    get(format: TranscriptFormat): TranscriptReader | undefined;
+    has(format: TranscriptFormat): boolean;
+    formats(): TranscriptFormat[];
+    /**
+     * The reader for a format, or a loud failure. A log whose format nothing can
+     * read must not render as an empty conversation — the missing piece is an
+     * unregistered adapter, and saying so is the only useful outcome.
+     */
+    require(format: TranscriptFormat): TranscriptReader;
+}
+/**
+ * A reader for a format whose entries the platform stores but cannot interpret.
+ *
+ * Every entry becomes an `unknown` event, which is enough to keep a log
+ * append-only, ordered and inspectable while its adapter is still being written.
+ */
+export declare function passthroughReader(format: TranscriptFormat, version?: number): TranscriptReader;

package/transcripts/reader.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * The transcript reader registry: one place per format that knows how to read
+ * it, looked up by the format a record was written under.
+ *
+ * A reader is registered *by value*, like an entry type, so a second harness
+ * ships its reader with its adapter and neither this package nor a renderer is
+ * released to support it. A record names its format, so a run that changed
+ * harness mid-flight still projects as one ordered log.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranscriptReaderRegistry = void 0;
+exports.passthroughReader = passthroughReader;
+const entry_1 = require("./entry");
+class TranscriptReaderRegistry {
+    readers = new Map();
+    constructor(readers = []) {
+        for (const reader of readers)
+            this.register(reader);
+    }
+    register(reader) {
+        this.readers.set(reader.format, reader);
+        return this;
+    }
+    get(format) {
+        return this.readers.get(format);
+    }
+    has(format) {
+        return this.readers.has(format);
+    }
+    formats() {
+        return Array.from(this.readers.keys()).sort();
+    }
+    /**
+     * The reader for a format, or a loud failure. A log whose format nothing can
+     * read must not render as an empty conversation — the missing piece is an
+     * unregistered adapter, and saying so is the only useful outcome.
+     */
+    require(format) {
+        const reader = this.readers.get(format);
+        if (!reader) {
+            const known = this.formats();
+            throw new Error(`no transcript reader registered for format "${format}"` +
+                (known.length === 0 ? '' : `; this registry reads ${known.join(', ')}`));
+        }
+        return reader;
+    }
+}
+exports.TranscriptReaderRegistry = TranscriptReaderRegistry;
+/**
+ * A reader for a format whose entries the platform stores but cannot interpret.
+ *
+ * Every entry becomes an `unknown` event, which is enough to keep a log
+ * append-only, ordered and inspectable while its adapter is still being written.
+ */
+function passthroughReader(format, version = 1) {
+    return {
+        format,
+        version,
+        assertEntry: entry_1.assertTranscriptEntry,
+        toEvents: (entry) => [
+            {
+                kind: 'unknown',
+                entryType: entry.type,
+                entry,
+                ...(typeof entry.id === 'string' ? { entryId: entry.id } : {}),
+                ...(typeof entry.timestamp === 'string' ? { at: entry.timestamp } : {})
+            }
+        ]
+    };
+}

package/transcripts/registry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The registry the projectors use when a caller does not pass their own.
+ *
+ * pi is registered because it is the harness the platform ships; a host adding
+ * a second one either registers into its own registry or into this one at
+ * startup. Kept apart from `./reader` so the registry type does not depend on
+ * any format.
+ */
+import { TranscriptReaderRegistry } from './reader';
+/** Readers registered out of the box. */
+export declare const defaultTranscriptReaders: () => TranscriptReaderRegistry;
+/**
+ * The process-wide registry. Mutable on purpose: a host registers its adapter's
+ * reader once at startup and every projector call then reads that format.
+ */
+export declare const transcriptReaders: TranscriptReaderRegistry;

package/transcripts/registry.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * The registry the projectors use when a caller does not pass their own.
+ *
+ * pi is registered because it is the harness the platform ships; a host adding
+ * a second one either registers into its own registry or into this one at
+ * startup. Kept apart from `./reader` so the registry type does not depend on
+ * any format.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transcriptReaders = exports.defaultTranscriptReaders = void 0;
+const pi_reader_1 = require("./pi-reader");
+const reader_1 = require("./reader");
+/** Readers registered out of the box. */
+const defaultTranscriptReaders = () => new reader_1.TranscriptReaderRegistry([pi_reader_1.piTranscriptReader]);
+exports.defaultTranscriptReaders = defaultTranscriptReaders;
+/**
+ * The process-wide registry. Mutable on purpose: a host registers its adapter's
+ * reader once at startup and every projector call then reads that format.
+ */
+exports.transcriptReaders = (0, exports.defaultTranscriptReaders)();