@agentic-kit/run-log 0.2.0 → 0.3.0

package/README.md

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

package/entry-types.d.ts

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

package/entry-types.js

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

package/esm/entry-types.d.ts

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

package/esm/entry-types.js

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

package/esm/index.d.ts

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

package/esm/index.js

@@ -6,11 +6,13 @@
  * reach for a node builtin. The filesystem store lives behind
  * `@agentic-kit/run-log/file-store`.
  */
+export { constructiveEntryTypes, EntryTypeRegistry } from './entry-types';
 export { follow, readAll } from './follow';
 export { assertPiSessionEntry, contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from './pi-entry';
 export { projectParts } from './projectors/parts';
 export { parseSessionJsonl, projectSession } from './projectors/session';
-export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, approvalRequestMessage, approvalResolutionMessage, projectToolState } from './projectors/tool-state';
+export { projectSpans } from './projectors/spans';
+export { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, approvalRequestMessage, approvalResolutionMessage, assertApprovalRequestDetails, assertApprovalResolutionDetails, assertGateDecisionDetails, GATE_DECISION_TYPE, gateDecisionMessage, projectToolState } from './projectors/tool-state';
 export { modelKey, projectUsage } from './projectors/usage';
 export { assertOrdered, assertRunEventRecord, idempotencyKey, RUN_LOG_WRAPPER_VERSION, SUPPORTED_PI_SESSION_VERSION, wrapEntry } from './record';
 export { cursorAfter, MemoryRunLogStore, START } from './store';

package/esm/projectors/spans.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Span projection: run log records → timed intervals with parents.
+ *
+ * The log answers *what* happened and the parts projection answers *in what
+ * order*, but a trace view asks "how long did this take, and inside what" —
+ * questions pi's entries only answer in pairs. Every entry is timestamped, so a
+ * tool call and its result, or an approval request and its answer, bracket an
+ * interval; nothing new has to be stored to know it.
+ *
+ * Two honesty rules shape the output. A duration derived from a *pair of writes*
+ * is a bound, not a measurement — the gap between a tool call and its result
+ * includes the wait for a human — so every span says which it is via `timing`,
+ * and a tool span carries its approval wait separately so a renderer can show
+ * "blocked on you" apart from "running". And an interval that never closed stays
+ * `open` with no duration rather than being closed at the last record: a run
+ * still in flight must not look like one that finished.
+ */
+import { type PiUsage } from '../pi-entry';
+import type { RunEventRecord } from '../record';
+export type SpanKind = 'model' | 'tool' | 'approval';
+export type SpanStatus = 'open' | 'ok' | 'error' | 'denied';
+/**
+ * Whether the duration is the interval that was measured, or a bound that
+ * includes whatever else sat between the two writes.
+ */
+export type SpanTiming = 'measured' | 'bounded';
+export interface SpanBase {
+    /** Stable within a run — a renderer's key and a parent reference. */
+    id: string;
+    kind: SpanKind;
+    /** Row title: the tool name, the model, or the awaited tool. */
+    name: string;
+    parentId?: string;
+    startSeq: number;
+    /** Absent while the span is still open. */
+    endSeq?: number;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    timing: SpanTiming;
+    status: SpanStatus;
+}
+export interface ModelSpan extends SpanBase {
+    kind: 'model';
+    model?: string;
+    provider?: string;
+    /** pi's provider response id — the join key to a metered inference row. */
+    responseId?: string;
+    stopReason?: string;
+    usage?: PiUsage;
+    errorMessage?: string;
+}
+export interface ToolSpan extends SpanBase {
+    kind: 'tool';
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+    output?: string;
+    details?: unknown;
+    /** Of the total duration, how much was spent waiting on a human. */
+    approvalWaitMs?: number;
+    /** Set when the gate settled the call instead of an execution. */
+    gateDecision?: 'allow' | 'deny';
+    gateReason?: string;
+}
+export interface ApprovalSpan extends SpanBase {
+    kind: 'approval';
+    toolCallId: string;
+    prompt: string;
+    decision?: 'approved' | 'rejected';
+    actorId?: string;
+}
+export type Span = ModelSpan | ToolSpan | ApprovalSpan;
+export interface SpanProjection {
+    /** In start order — the order a timeline draws them. */
+    spans: Span[];
+}
+/**
+ * Project records into spans. Pure, and like the other projectors it ignores what
+ * it does not recognise — a log written by a newer pi still traces. A *registered*
+ * type that is malformed is another matter and throws: a gate decision naming no
+ * tool call is a writer bug, and a trace that quietly omitted a refusal would be
+ * worse than one that fails.
+ */
+export declare function projectSpans(records: readonly RunEventRecord[]): SpanProjection;

package/esm/projectors/spans.js

@@ -0,0 +1,176 @@
+/**
+ * Span projection: run log records → timed intervals with parents.
+ *
+ * The log answers *what* happened and the parts projection answers *in what
+ * order*, but a trace view asks "how long did this take, and inside what" —
+ * questions pi's entries only answer in pairs. Every entry is timestamped, so a
+ * tool call and its result, or an approval request and its answer, bracket an
+ * interval; nothing new has to be stored to know it.
+ *
+ * Two honesty rules shape the output. A duration derived from a *pair of writes*
+ * is a bound, not a measurement — the gap between a tool call and its result
+ * includes the wait for a human — so every span says which it is via `timing`,
+ * and a tool span carries its approval wait separately so a renderer can show
+ * "blocked on you" apart from "running". And an interval that never closed stays
+ * `open` with no duration rather than being closed at the last record: a run
+ * still in flight must not look like one that finished.
+ */
+import { contentText, isAssistantMessage, isPiMessageEntry, isToolResultMessage, toolCalls } from '../pi-entry';
+import { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, assertGateDecisionDetails, GATE_DECISION_TYPE } from './tool-state';
+const ms = (from, to) => {
+    const start = Date.parse(from);
+    const end = Date.parse(to);
+    if (Number.isNaN(start) || Number.isNaN(end))
+        return undefined;
+    return end - start;
+};
+const close = (span, seq, at) => {
+    span.endSeq = seq;
+    span.endedAt = at;
+    const duration = ms(span.startedAt, at);
+    if (duration !== undefined)
+        span.durationMs = duration;
+};
+const detailsOf = (value) => typeof value === 'object' && value !== null ? value : {};
+/**
+ * Project records into spans. Pure, and like the other projectors it ignores what
+ * it does not recognise — a log written by a newer pi still traces. A *registered*
+ * type that is malformed is another matter and throws: a gate decision naming no
+ * tool call is a writer bug, and a trace that quietly omitted a refusal would be
+ * worse than one that fails.
+ */
+export function projectSpans(records) {
+    const spans = [];
+    const tools = new Map();
+    const approvals = new Map();
+    /**
+     * The end of the previous entry, which is the earliest the next model call
+     * can have begun — pi logs a response, never a request.
+     */
+    let previousAt;
+    for (const { entry, seq } of records) {
+        const at = typeof entry.timestamp === 'string' ? entry.timestamp : undefined;
+        if (at === undefined)
+            continue;
+        const previous = previousAt;
+        previousAt = at;
+        if (!isPiMessageEntry(entry))
+            continue;
+        const message = entry.message;
+        if (isAssistantMessage(message)) {
+            const span = {
+                id: `model:${entry.id}`,
+                kind: 'model',
+                name: message.model ?? 'model',
+                // The turn began no earlier than the previous entry was written; with no
+                // previous entry the interval is unknown and the span is a point.
+                startedAt: previous ?? at,
+                startSeq: seq,
+                endSeq: seq,
+                endedAt: at,
+                timing: 'bounded',
+                status: message.stopReason === 'error' ? 'error' : 'ok',
+                ...(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 } : {})
+            };
+            const duration = ms(span.startedAt, at);
+            if (duration !== undefined)
+                span.durationMs = duration;
+            spans.push(span);
+            for (const call of toolCalls(message)) {
+                const tool = {
+                    id: `tool:${call.id}`,
+                    kind: 'tool',
+                    name: call.name,
+                    parentId: span.id,
+                    toolCallId: call.id,
+                    arguments: call.arguments ?? {},
+                    startedAt: at,
+                    startSeq: seq,
+                    // A call and its result are two writes; anything between them —
+                    // approval, queueing — is inside the interval.
+                    timing: 'bounded',
+                    status: 'open'
+                };
+                tools.set(call.id, tool);
+                spans.push(tool);
+            }
+            continue;
+        }
+        if (isToolResultMessage(message)) {
+            const tool = tools.get(message.toolCallId);
+            if (!tool)
+                continue;
+            close(tool, seq, at);
+            tool.status = message.isError ? 'error' : 'ok';
+            tool.output = contentText(message.content);
+            if (message.details !== undefined)
+                tool.details = message.details;
+            const approval = approvals.get(message.toolCallId);
+            if (approval?.durationMs !== undefined)
+                tool.approvalWaitMs = approval.durationMs;
+            continue;
+        }
+        if (message.role !== 'custom')
+            continue;
+        const info = detailsOf(message.details);
+        const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : undefined;
+        if (toolCallId === undefined)
+            continue;
+        if (message.customType === APPROVAL_REQUEST_TYPE) {
+            const tool = tools.get(toolCallId);
+            const approval = {
+                id: `approval:${toolCallId}`,
+                kind: 'approval',
+                name: tool?.name ?? 'approval',
+                ...(tool ? { parentId: tool.id } : {}),
+                toolCallId,
+                prompt: contentText(message.content),
+                startedAt: at,
+                startSeq: seq,
+                // Request and answer are exactly the interval a human held the run.
+                timing: 'measured',
+                status: 'open'
+            };
+            approvals.set(toolCallId, approval);
+            spans.push(approval);
+            continue;
+        }
+        if (message.customType === APPROVAL_RESOLUTION_TYPE) {
+            const approval = approvals.get(toolCallId);
+            if (!approval)
+                continue;
+            close(approval, seq, at);
+            const approved = info.decision === 'approved';
+            approval.decision = approved ? 'approved' : 'rejected';
+            approval.status = approved ? 'ok' : 'denied';
+            if (typeof info.actorId === 'string')
+                approval.actorId = info.actorId;
+            const tool = tools.get(toolCallId);
+            if (tool && approval.durationMs !== undefined)
+                tool.approvalWaitMs = approval.durationMs;
+            continue;
+        }
+        if (message.customType === GATE_DECISION_TYPE) {
+            // Throws on a malformed decision — see the note on this function.
+            const decision = assertGateDecisionDetails(message.details, seq);
+            const tool = tools.get(decision.toolCallId);
+            if (!tool)
+                continue;
+            tool.gateDecision = decision.decision;
+            if (decision.reason !== undefined)
+                tool.gateReason = decision.reason;
+            // A denied call is never executed, so this write is the only thing that
+            // will ever close its span.
+            if (decision.decision === 'deny' && tool.status === 'open') {
+                close(tool, seq, at);
+                tool.status = 'denied';
+            }
+        }
+    }
+    return { spans };
+}