pi-loop-graph-sdk 0.2.0

package/dist/replay/model.d.ts

@@ -0,0 +1,81 @@
+import type { ReplayDocument } from "./finalizer.js";
+import type { ReplayEventEnvelope } from "./events.js";
+export interface ReplayInvocationModel {
+    readonly id: string;
+    readonly parentId?: string;
+    readonly graphId?: string;
+    readonly graphVersion?: string;
+    readonly boundary?: string;
+    readonly events: readonly ReplayEventEnvelope[];
+    readonly children: readonly ReplayInvocationModel[];
+}
+export interface ExtractedContextBlock {
+    readonly text: string;
+}
+export interface ExtractedContextSnapshot {
+    readonly agentRunId: string;
+    readonly nodeVisitId: string;
+    readonly timestamp: string;
+    readonly blocks: readonly ExtractedContextBlock[];
+}
+export interface ExtractedToolCall {
+    readonly toolCallId: string;
+    readonly sequence: number;
+    readonly toolName: string;
+    readonly args?: unknown;
+    readonly result?: unknown;
+    readonly isError?: boolean;
+    readonly timestamp: string;
+}
+export interface ExtractedTurn {
+    readonly turnIndex: number;
+    readonly startedSequence: number;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly usage?: {
+        readonly inputTokens?: number;
+        readonly outputTokens?: number;
+    };
+    readonly durationMs?: number;
+    readonly assistantTexts: readonly string[];
+    readonly toolCalls: readonly ExtractedToolCall[];
+}
+export interface ExtractedCompletionAttempt {
+    readonly timestamp: string;
+    readonly schemaFingerprint?: string;
+    readonly outcome: "accepted" | "rejected" | "failed";
+    readonly reason?: string;
+    readonly validatorStage?: string;
+    readonly durationMs?: number;
+    readonly validationStages: readonly string[];
+}
+export interface ExtractedAgentRun {
+    readonly agentRunId: string;
+    readonly nodeVisitId: string;
+    readonly stageId: string;
+    readonly graphInvocationId: string;
+    readonly contextSnapshot?: ExtractedContextSnapshot;
+    readonly turns: readonly ExtractedTurn[];
+    readonly completions: readonly ExtractedCompletionAttempt[];
+}
+export interface ExtractedNodeVisit {
+    readonly nodeVisitId: string;
+    readonly stageId: string;
+    readonly enteredAt: string;
+    readonly exitedAt?: string;
+    readonly agentRuns: readonly ExtractedAgentRun[];
+}
+export interface ReplayModel {
+    readonly schemaVersion: 1;
+    readonly rootRunId: string;
+    readonly mode: ReplayDocument["mode"];
+    readonly createdAt: string;
+    readonly recording: ReplayDocument["recording"];
+    readonly result: ReplayDocument["result"];
+    readonly totalCost?: number;
+    readonly summary: Readonly<Record<string, number>>;
+    readonly invocations: readonly ReplayInvocationModel[];
+    readonly unscopedEvents: readonly ReplayEventEnvelope[];
+    readonly nodes: readonly ExtractedNodeVisit[];
+    readonly contextSnapshots: readonly ExtractedContextSnapshot[];
+}

package/dist/replay/model.js

@@ -0,0 +1 @@
+export {};

package/dist/replay/parser.d.ts

@@ -0,0 +1,3 @@
+import type { ReplayDocument } from "./finalizer.js";
+import type { ReplayModel } from "./model.js";
+export declare function parseReplay(input: string | ReplayDocument): ReplayModel;

package/dist/replay/parser.js

@@ -0,0 +1,332 @@
+export function parseReplay(input) {
+    const document = typeof input === "string" ? JSON.parse(input) : input;
+    if (!document || document.schemaVersion !== 1 || !Array.isArray(document.events))
+        throw new TypeError("Unsupported replay document");
+    // ── Bucket events by graphInvocationId ──
+    const buckets = new Map();
+    const unscoped = [];
+    const summary = {};
+    for (const envelope of document.events) {
+        summary[envelope.event.domain] = (summary[envelope.event.domain] ?? 0) + 1;
+        if (!envelope.graphInvocationId) {
+            unscoped.push(envelope);
+            continue;
+        }
+        const bucket = buckets.get(envelope.graphInvocationId) ?? { events: [] };
+        bucket.events.push(envelope);
+        if (envelope.event.type === "graph_entered" && isObject(envelope.event.data)) {
+            bucket.parentId = stringValue(envelope.event.data.parentGraphInvocationId);
+            bucket.graphId = stringValue(envelope.event.data.graphId);
+            bucket.graphVersion = stringValue(envelope.event.data.graphVersion);
+            bucket.boundary = stringValue(envelope.event.data.boundary);
+        }
+        buckets.set(envelope.graphInvocationId, bucket);
+    }
+    // ── Build invocation tree ──
+    const build = (id, stack = new Set()) => {
+        if (stack.has(id))
+            throw new TypeError("Replay invocation cycle");
+        const bucket = buckets.get(id);
+        const next = new Set(stack);
+        next.add(id);
+        const children = [...buckets].filter(([, v]) => v.parentId === id).map(([child]) => build(child, next));
+        return Object.freeze({ id, ...bucket, events: Object.freeze(bucket.events), children: Object.freeze(children) });
+    };
+    for (const id of buckets.keys())
+        build(id);
+    const roots = [...buckets].filter(([, v]) => !v.parentId || !buckets.has(v.parentId)).map(([id]) => build(id));
+    if (buckets.size > 0 && roots.length === 0)
+        throw new TypeError("Replay invocation cycle");
+    // ── Structured extraction ──
+    const allEvents = document.events;
+    // Collect context snapshots
+    const contextSnapshots = [];
+    for (const ev of allEvents) {
+        if (ev.event.type !== "context_snapshot_projected")
+            continue;
+        const data = isObject(ev.event.data) ? ev.event.data : null;
+        if (!data)
+            continue;
+        const message = data;
+        const blocks = [];
+        const content = message.content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                if (isObject(block) && block.type === "text" && typeof block.text === "string") {
+                    blocks.push(Object.freeze({ text: block.text }));
+                }
+            }
+        }
+        if (blocks.length > 0) {
+            contextSnapshots.push(Object.freeze({
+                agentRunId: stringValue(ev.agentRunId) ?? "",
+                nodeVisitId: stringValue(ev.nodeVisitId) ?? "",
+                timestamp: ev.timestamp,
+                blocks: Object.freeze(blocks),
+            }));
+        }
+    }
+    // Collect node visits
+    const nodeVisits = new Map();
+    for (const ev of allEvents) {
+        if (ev.event.type !== "node_entered")
+            continue;
+        const nvId = stringValue(ev.nodeVisitId);
+        if (!nvId)
+            continue;
+        if (!nodeVisits.has(nvId)) {
+            const data = isObject(ev.event.data) ? ev.event.data : null;
+            nodeVisits.set(nvId, {
+                nodeVisitId: nvId,
+                stageId: stringValue(data?.stageId) ?? "",
+                enteredAt: ev.timestamp,
+                agentRuns: [],
+            });
+        }
+    }
+    for (const ev of allEvents) {
+        if (ev.event.type !== "node_exited")
+            continue;
+        const nvId = stringValue(ev.nodeVisitId);
+        if (!nvId)
+            continue;
+        const nv = nodeVisits.get(nvId);
+        if (nv)
+            nodeVisits.set(nvId, { ...nv, exitedAt: ev.timestamp });
+    }
+    // Collect agent runs
+    const agentRuns = new Map();
+    for (const ev of allEvents) {
+        if (ev.event.type !== "agent_started")
+            continue;
+        const arId = stringValue(ev.agentRunId);
+        if (!arId)
+            continue;
+        const data = isObject(ev.event.data) ? ev.event.data : null;
+        const nvId = stringValue(ev.nodeVisitId) ?? "";
+        if (!agentRuns.has(arId)) {
+            // Determine stageId from enclosing node
+            const nv = nodeVisits.get(nvId);
+            agentRuns.set(arId, {
+                agentRunId: arId,
+                nodeVisitId: nvId,
+                stageId: nv?.stageId ?? "",
+                graphInvocationId: stringValue(ev.graphInvocationId) ?? "",
+                turns: [],
+                completions: [],
+            });
+        }
+    }
+    // Attach context snapshots to agent runs
+    for (const cs of contextSnapshots) {
+        const ar = agentRuns.get(cs.agentRunId);
+        if (ar)
+            agentRuns.set(ar.agentRunId, { ...ar, contextSnapshot: cs });
+    }
+    // Collect turns
+    const turns = new Map(); // keyed by agentRunId
+    let currentArId = null;
+    let currentTurnIdx = -1;
+    for (const ev of allEvents) {
+        if (ev.event.type === "agent_started") {
+            currentArId = stringValue(ev.agentRunId) ?? null;
+            currentTurnIdx = -1;
+            continue;
+        }
+        if (ev.event.type === "model_turn_started") {
+            const data = isObject(ev.event.data) ? ev.event.data : null;
+            currentTurnIdx = typeof data?.turn === "number" ? data.turn : currentTurnIdx + 1;
+            if (!currentArId)
+                continue;
+            const list = turns.get(currentArId) ?? [];
+            list.push({
+                turnIndex: currentTurnIdx,
+                startedSequence: ev.sequence,
+                assistantTexts: [],
+                toolCalls: [],
+            });
+            turns.set(currentArId, list);
+            continue;
+        }
+        if (ev.event.type === "model_turn_finished") {
+            const data = isObject(ev.event.data) ? ev.event.data : null;
+            if (!currentArId)
+                continue;
+            const list = turns.get(currentArId) ?? [];
+            const last = list[list.length - 1];
+            if (!last)
+                continue;
+            const message = data?.message;
+            if (isObject(message)) {
+                const provider = stringValue(data.provider);
+                const model = stringValue(data.model);
+                const usage = isObject(data.usage)
+                    ? Object.freeze({ inputTokens: numberValue(data.usage.inputTokens), outputTokens: numberValue(data.usage.outputTokens) })
+                    : undefined;
+                const durationMs = typeof data.durationMs === "number" ? data.durationMs : undefined;
+                const texts = [];
+                const content = message.content;
+                if (Array.isArray(content)) {
+                    for (const block of content) {
+                        if (isObject(block) && block.type === "text" && typeof block.text === "string") {
+                            texts.push(block.text);
+                        }
+                    }
+                }
+                list[list.length - 1] = Object.freeze({
+                    ...last,
+                    provider, model, usage, durationMs,
+                    assistantTexts: Object.freeze(texts),
+                });
+                turns.set(currentArId, list);
+            }
+        }
+    }
+    // Collect tool calls (link by toolCallId)
+    const toolCallsById = new Map();
+    const toolCallsByArId = new Map();
+    for (const ev of allEvents) {
+        if (ev.event.type === "tool_execution_started" || ev.event.type === "tool_execution_finished") {
+            const tcId = stringValue(ev.toolCallId);
+            const arId = stringValue(ev.agentRunId);
+            const data = isObject(ev.event.data) ? ev.event.data : null;
+            if (!tcId)
+                continue;
+            const existing = toolCallsById.get(tcId);
+            if (ev.event.type === "tool_execution_started") {
+                const tc = {
+                    toolCallId: tcId,
+                    sequence: ev.sequence,
+                    toolName: stringValue(data?.toolName) ?? "unknown",
+                    args: data?.args,
+                    timestamp: ev.timestamp,
+                };
+                toolCallsById.set(tcId, tc);
+                if (arId) {
+                    const list = toolCallsByArId.get(arId) ?? [];
+                    list.push(tc);
+                    toolCallsByArId.set(arId, list);
+                }
+            }
+            else if (existing) {
+                const updated = Object.freeze({
+                    ...existing,
+                    result: data?.result,
+                    isError: data?.isError === true,
+                });
+                toolCallsById.set(tcId, updated);
+                if (arId) {
+                    const list = toolCallsByArId.get(arId) ?? [];
+                    const idx = list.findIndex(t => t.toolCallId === tcId);
+                    if (idx >= 0)
+                        list[idx] = updated;
+                }
+            }
+        }
+    }
+    // Attach each tool call to the turn that was active when it started.
+    for (const [arId, arTurns] of turns) {
+        const tcList = toolCallsByArId.get(arId) ?? [];
+        if (tcList.length > 0 && arTurns.length > 0) {
+            const byTurn = arTurns.map((turn, index) => {
+                const nextStart = arTurns[index + 1]?.startedSequence ?? Number.POSITIVE_INFINITY;
+                const calls = tcList.filter((call) => call.sequence >= turn.startedSequence && call.sequence < nextStart);
+                return calls.length > 0 ? Object.freeze({ ...turn, toolCalls: Object.freeze(calls) }) : turn;
+            });
+            turns.set(arId, byTurn);
+            continue;
+        }
+    }
+    // Collect completion attempts
+    const completionsByArId = new Map();
+    const activeCompletionByArId = new Map();
+    const completionStagesByArId = new Map();
+    for (const ev of allEvents) {
+        const arId = stringValue(ev.agentRunId);
+        if (!arId)
+            continue;
+        if (ev.event.type === "completion.submitted") {
+            const data = isObject(ev.event.data) ? ev.event.data : null;
+            const attempts = completionsByArId.get(arId) ?? [];
+            attempts.push({
+                timestamp: ev.timestamp,
+                schemaFingerprint: stringValue(data?.schemaFingerprint),
+                outcome: "accepted", // default, will be updated
+                validationStages: [],
+            });
+            completionsByArId.set(arId, attempts);
+            activeCompletionByArId.set(arId, attempts.length - 1);
+            completionStagesByArId.set(arId, []);
+        }
+        if (ev.event.type === "completion.validation_started") {
+            const data = isObject(ev.event.data) ? ev.event.data : null;
+            const stage = stringValue(data?.validatorStage);
+            if (stage) {
+                const stages = completionStagesByArId.get(arId) ?? [];
+                stages.push(stage);
+                completionStagesByArId.set(arId, stages);
+            }
+        }
+        if (ev.event.type === "completion.accepted" || ev.event.type === "completion.rejected" || ev.event.type === "completion.failed") {
+            const data = isObject(ev.event.data) ? ev.event.data : null;
+            const outcome = ev.event.type === "completion.accepted" ? "accepted"
+                : ev.event.type === "completion.failed" ? "failed" : "rejected";
+            const attempts = completionsByArId.get(arId) ?? [];
+            const activeIndex = activeCompletionByArId.get(arId);
+            const stages = [...(completionStagesByArId.get(arId) ?? [])];
+            const index = activeIndex ?? attempts.length;
+            const existing = attempts[index];
+            attempts[index] = Object.freeze({
+                ...(existing ?? { timestamp: ev.timestamp, validationStages: Object.freeze(stages) }),
+                outcome,
+                reason: stringValue(data?.reason),
+                validatorStage: stringValue(data?.validatorStage),
+                durationMs: typeof data?.durationMs === "number" ? data.durationMs : undefined,
+                validationStages: Object.freeze(stages),
+            });
+            completionsByArId.set(arId, attempts);
+            activeCompletionByArId.delete(arId);
+            completionStagesByArId.delete(arId);
+        }
+    }
+    // Attach turns and completions to agent runs
+    for (const [arId, ar] of agentRuns) {
+        const arTurns = Object.freeze(turns.get(arId)?.map(t => Object.freeze(t)) ?? []);
+        const completions = Object.freeze(completionsByArId.get(arId) ?? []);
+        agentRuns.set(arId, Object.freeze({ ...ar, turns: arTurns, completions }));
+    }
+    // Attach agent runs to node visits
+    for (const [, ar] of agentRuns) {
+        const nv = nodeVisits.get(ar.nodeVisitId);
+        if (nv) {
+            nodeVisits.set(ar.nodeVisitId, Object.freeze({
+                ...nv,
+                agentRuns: Object.freeze([...nv.agentRuns, ar]),
+            }));
+        }
+    }
+    const nodes = Object.freeze([...nodeVisits.values()].map(nv => Object.freeze({ ...nv, agentRuns: Object.freeze(nv.agentRuns) })));
+    return Object.freeze({
+        schemaVersion: 1,
+        rootRunId: document.rootRunId,
+        mode: document.mode,
+        createdAt: document.createdAt,
+        recording: document.recording,
+        result: document.result,
+        ...(document.totalCost === undefined ? {} : { totalCost: document.totalCost }),
+        summary: Object.freeze(summary),
+        invocations: Object.freeze(roots),
+        unscopedEvents: Object.freeze(unscoped),
+        nodes,
+        contextSnapshots: Object.freeze(contextSnapshots),
+    });
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" ? value : undefined;
+}

package/dist/replay/recorder.d.ts

@@ -0,0 +1,30 @@
+import type { GraphRunResult, ReplayReference } from "../core/result.js";
+import type { JsonValue } from "../core/json.js";
+import type { RuntimeEventBus } from "../runtime/event-bus.js";
+import { type PricingResolver, type RecordingMode, type ReplayEvent, type ReplayEventScope } from "./events.js";
+import type { RunStore } from "./store.js";
+export interface RecorderOptions {
+    readonly mode: Exclude<RecordingMode, "off">;
+    readonly store: RunStore;
+    readonly artifactThresholdBytes?: number;
+    readonly pricingResolver?: PricingResolver;
+    readonly now?: () => Date;
+}
+export declare class Recorder {
+    private readonly options;
+    private sequence;
+    private queue;
+    private readonly issues;
+    private rootRunId;
+    private unsubscribe?;
+    constructor(options: RecorderOptions);
+    attach(eventBus: RuntimeEventBus): void;
+    record(event: ReplayEvent, scope: ReplayEventScope): void;
+    finalize<T>(result: GraphRunResult<T>): Promise<{
+        readonly replay: ReplayReference;
+        readonly documentWritten: boolean;
+    }>;
+    private recordRuntimeEvent;
+    private persist;
+}
+export declare function toRecordedJson(value: unknown, mode: RecordingMode): JsonValue;

package/dist/replay/recorder.js

@@ -0,0 +1,195 @@
+import { finalizeJournal } from "./finalizer.js";
+import { REPLAY_SCHEMA_VERSION } from "./events.js";
+export class Recorder {
+    options;
+    sequence = 0;
+    queue = Promise.resolve();
+    issues = [];
+    rootRunId;
+    unsubscribe;
+    constructor(options) {
+        this.options = options;
+    }
+    attach(eventBus) {
+        this.unsubscribe?.();
+        this.unsubscribe = eventBus.subscribe((event) => this.recordRuntimeEvent(event));
+    }
+    record(event, scope) {
+        this.rootRunId ??= scope.rootRunId;
+        const envelope = Object.freeze({
+            schemaVersion: REPLAY_SCHEMA_VERSION,
+            sequence: ++this.sequence,
+            timestamp: (this.options.now?.() ?? new Date()).toISOString(),
+            ...scope,
+            event: Object.freeze({
+                ...event,
+                ...(event.data === undefined ? {} : { data: toRecordedJson(event.data, this.options.mode) }),
+            }),
+        });
+        this.queue = this.queue.then(() => this.persist(envelope)).catch((error) => {
+            this.issues.push(errorMessage(error));
+        });
+    }
+    async finalize(result) {
+        if (this.rootRunId) {
+            this.record({ domain: "recording", type: "recording_finalizing" }, { rootRunId: this.rootRunId });
+        }
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        await this.queue;
+        const runId = this.rootRunId ?? result.rootRunId;
+        try {
+            const recordedResult = toRecordedJson(result, this.options.mode);
+            const serializedResult = JSON.stringify(recordedResult);
+            const threshold = this.options.artifactThresholdBytes ?? 64 * 1024;
+            const persistedResult = Buffer.byteLength(serializedResult, "utf8") > threshold
+                ? await this.options.store.writeArtifact(runId, "final-result.json", serializedResult)
+                : recordedResult;
+            const document = await finalizeJournal({
+                store: this.options.store,
+                runId,
+                mode: this.options.mode,
+                result: persistedResult,
+                pricingResolver: this.options.pricingResolver,
+                initialIssues: this.issues,
+            });
+            const status = document.recording.status;
+            const replay = Object.freeze({
+                mode: this.options.mode,
+                status,
+                location: this.options.store.location(runId),
+                issues: document.recording.issues,
+            });
+            const replayResult = isArtifactReference(persistedResult)
+                ? persistedResult
+                : { ...recordedResult, replay };
+            await this.options.store.writeReplay(runId, `${JSON.stringify({ ...document, result: replayResult }, null, 2)}\n`);
+            return {
+                replay,
+                documentWritten: true,
+            };
+        }
+        catch (error) {
+            const issues = Object.freeze([...this.issues, errorMessage(error)]);
+            return {
+                replay: Object.freeze({
+                    mode: this.options.mode,
+                    status: "failed",
+                    location: this.options.store.location(runId),
+                    issues,
+                }),
+                documentWritten: false,
+            };
+        }
+    }
+    recordRuntimeEvent(event) {
+        const { rootRunId, graphInvocationId, nodeVisitId, agentRunId, ...data } = event;
+        this.record({ domain: runtimeDomain(event.type), type: event.type, data: toRecordedJson(data, this.options.mode) }, {
+            rootRunId,
+            graphInvocationId,
+            nodeVisitId,
+            agentRunId,
+        });
+        if (event.type === "root_started" && this.options.mode === "forensic") {
+            this.record({
+                domain: "recording",
+                type: "forensic_recording_warning",
+                data: { message: "Forensic recording may contain unredacted sensitive data and hidden reasoning." },
+            }, { rootRunId });
+        }
+    }
+    async persist(envelope) {
+        const threshold = this.options.artifactThresholdBytes ?? 64 * 1024;
+        const serializedData = envelope.event.data === undefined ? undefined : JSON.stringify(envelope.event.data);
+        let persisted = envelope;
+        if (serializedData && Buffer.byteLength(serializedData, "utf8") > threshold) {
+            const artifactId = `${String(envelope.sequence).padStart(8, "0")}-${safeType(envelope.event.type)}.json`;
+            const artifact = await this.options.store.writeArtifact(envelope.rootRunId, artifactId, serializedData);
+            persisted = Object.freeze({ ...envelope, event: Object.freeze({ ...envelope.event, data: artifact }) });
+        }
+        await this.options.store.appendJournal(envelope.rootRunId, JSON.stringify(persisted));
+    }
+}
+export function toRecordedJson(value, mode) {
+    return sanitize(value, mode, new WeakSet());
+}
+function sanitize(value, mode, ancestors, key = "") {
+    if (mode !== "forensic" && sensitiveKey(key))
+        return "[REDACTED]";
+    if (mode !== "forensic" && key === "thinking")
+        return "[REDACTED]";
+    if (mode === "events" && verboseKey(key))
+        return "[OMITTED]";
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return mode === "forensic" ? value : redactString(value);
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === "bigint" || typeof value === "symbol" || typeof value === "function" || value === undefined)
+        return String(value);
+    if (ancestors.has(value))
+        return "[CIRCULAR]";
+    if (mode !== "forensic" && isThinkingBlock(value)) {
+        return { type: "thinking", thinking: "[REDACTED]" };
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((entry) => sanitize(entry, mode, ancestors));
+        const output = {};
+        for (const [childKey, child] of Object.entries(value)) {
+            if (mode !== "forensic" && (childKey === "reasoning" || childKey === "thinking"))
+                continue;
+            output[childKey] = sanitize(child, mode, ancestors, childKey);
+        }
+        return output;
+    }
+    catch {
+        return String(value);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function isThinkingBlock(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        && value.type === "thinking";
+}
+function sensitiveKey(key) {
+    return /^(authorization|api[-_]?key|token|password|secret|cookie|set-cookie)$/i.test(key);
+}
+function verboseKey(key) {
+    return /^(content|input|output|result|payload|reasoning|toolResults)$/i.test(key);
+}
+function redactString(value) {
+    return value
+        .replace(/(Bearer\s+)[A-Za-z0-9._~+\/-]+=*/gi, "$1[REDACTED]")
+        .replace(/\bsk-[A-Za-z0-9_-]{10,}\b/g, "[REDACTED]");
+}
+function runtimeDomain(type) {
+    if (type.startsWith("root_") || type === "host_baseline_selected")
+        return "root";
+    if (type.startsWith("graph_"))
+        return "graph";
+    if (type.startsWith("node_"))
+        return "node";
+    if (type.startsWith("agent_"))
+        return "agent";
+    if (type.startsWith("context_"))
+        return "context";
+    if (type.startsWith("mechanism_") || type === "runtime_warning")
+        return "mechanism";
+    if (type.startsWith("transition_"))
+        return "transition";
+    return "recording";
+}
+function safeType(type) {
+    return type.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isArtifactReference(value) {
+    return value !== null && typeof value === "object" && "artifactId" in value && "sha256" in value;
+}

package/dist/replay/store.d.ts

@@ -0,0 +1,41 @@
+import type { ReplayArtifactRef } from "./events.js";
+export interface JournalStore {
+    appendJournal(runId: string, line: string): Promise<void>;
+    readJournal(runId: string): Promise<string>;
+}
+export interface ArtifactStore {
+    writeArtifact(runId: string, artifactId: string, content: string, mediaType?: string): Promise<ReplayArtifactRef>;
+    readArtifact(runId: string, artifactId: string): Promise<string>;
+}
+export interface CheckpointStore {
+    writeCheckpoint(runId: string, checkpointId: string, content: string): Promise<void>;
+    readCheckpoint(runId: string, checkpointId: string): Promise<string>;
+    listCheckpoints?(runId: string): Promise<readonly string[]>;
+    pruneCheckpoints?(runId: string, keep: readonly string[]): Promise<void>;
+    deleteCheckpoint?(runId: string, checkpointId: string): Promise<void>;
+}
+export interface RunStore extends JournalStore, ArtifactStore, CheckpointStore {
+    writeReplay(runId: string, content: string): Promise<void>;
+    readReplay(runId: string): Promise<string>;
+    location(runId: string): string | undefined;
+}
+export interface FileRunStoreOptions {
+    readonly rootDir?: string;
+}
+export declare class FileRunStore implements RunStore {
+    readonly rootDir: string;
+    constructor(options?: FileRunStoreOptions | string);
+    location(runId: string): string;
+    appendJournal(runId: string, line: string): Promise<void>;
+    readJournal(runId: string): Promise<string>;
+    writeArtifact(runId: string, artifactId: string, content: string, mediaType?: string): Promise<ReplayArtifactRef>;
+    readArtifact(runId: string, artifactId: string): Promise<string>;
+    writeCheckpoint(runId: string, checkpointId: string, content: string): Promise<void>;
+    readCheckpoint(runId: string, checkpointId: string): Promise<string>;
+    listCheckpoints(runId: string): Promise<readonly string[]>;
+    pruneCheckpoints(runId: string, keep: readonly string[]): Promise<void>;
+    deleteCheckpoint(runId: string, checkpointId: string): Promise<void>;
+    writeReplay(runId: string, content: string): Promise<void>;
+    readReplay(runId: string): Promise<string>;
+    private runDir;
+}