@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/dist/viewer/session-reducer.js

@@ -0,0 +1,266 @@
+function payloadString(payload, key) {
+    const value = payload[key];
+    return typeof value === "string" ? value : undefined;
+}
+function payloadIndex(payload) {
+    const value = payload.contentIndex;
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function ensureBlock(message, contentIndex, kind) {
+    const existing = message.blocks.get(contentIndex);
+    if (existing) {
+        return existing;
+    }
+    const block = { contentIndex, kind, text: "" };
+    message.blocks.set(contentIndex, block);
+    return block;
+}
+function entryIds(entries) {
+    return new Set(entries.flatMap((record) => {
+        const id = record.entry.id;
+        return typeof id === "string" ? [id] : [];
+    }));
+}
+function foldSessionEvents(entries, events, throughSeq, initial) {
+    const messages = new Map();
+    const messageOrder = [];
+    for (const message of initial?.messages ?? []) {
+        messages.set(message.messageId, {
+            ...message,
+            blocks: new Map(message.blocks.map((block) => [block.contentIndex, { ...block }])),
+        });
+        messageOrder.push(message.messageId);
+    }
+    const tools = new Map();
+    const toolOrder = [];
+    for (const tool of initial?.tools ?? []) {
+        tools.set(tool.toolCallId, { ...tool });
+        toolOrder.push(tool.toolCallId);
+    }
+    const settledEntryIds = [...(initial?.settledEntryIds ?? [])];
+    const knownEntries = entryIds(entries);
+    const diagnostics = [...(initial?.diagnostics ?? [])];
+    let expectedSeq = (initial?.throughSeq ?? 0) + 1;
+    let lastSeq = initial?.throughSeq ?? 0;
+    for (const event of events) {
+        if (event.seq <= lastSeq) {
+            continue;
+        }
+        if (event.seq > throughSeq) {
+            break;
+        }
+        if (event.seq !== expectedSeq) {
+            diagnostics.push(`session event sequence gap at ${expectedSeq}`);
+            expectedSeq = event.seq;
+        }
+        expectedSeq += 1;
+        lastSeq = event.seq;
+        switch (event.type) {
+            case "message_started": {
+                if (!event.messageId) {
+                    diagnostics.push(`message_started ${event.seq} has no messageId`);
+                    break;
+                }
+                if (!messages.has(event.messageId)) {
+                    messages.set(event.messageId, {
+                        messageId: event.messageId,
+                        role: payloadString(event.payload, "role") ?? "unknown",
+                        status: "streaming",
+                        blocks: new Map(),
+                    });
+                    messageOrder.push(event.messageId);
+                }
+                break;
+            }
+            case "assistant_event": {
+                if (!event.messageId) {
+                    diagnostics.push(`assistant_event ${event.seq} has no messageId`);
+                    break;
+                }
+                const message = messages.get(event.messageId);
+                if (!message) {
+                    diagnostics.push(`assistant_event ${event.seq} precedes message_started`);
+                    break;
+                }
+                const assistantType = payloadString(event.payload, "type");
+                const contentIndex = payloadIndex(event.payload);
+                if (contentIndex !== undefined &&
+                    (assistantType === "text_start" ||
+                        assistantType === "thinking_start" ||
+                        assistantType === "toolcall_start")) {
+                    ensureBlock(message, contentIndex, assistantType === "text_start"
+                        ? "text"
+                        : assistantType === "thinking_start"
+                            ? "thinking"
+                            : "toolCall");
+                }
+                else if (contentIndex !== undefined &&
+                    (assistantType === "text_delta" ||
+                        assistantType === "thinking_delta" ||
+                        assistantType === "toolcall_delta")) {
+                    const block = ensureBlock(message, contentIndex, assistantType === "text_delta"
+                        ? "text"
+                        : assistantType === "thinking_delta"
+                            ? "thinking"
+                            : "toolCall");
+                    block.text += payloadString(event.payload, "delta") ?? "";
+                }
+                else if (contentIndex !== undefined &&
+                    (assistantType === "text_end" || assistantType === "thinking_end")) {
+                    const block = ensureBlock(message, contentIndex, assistantType === "text_end" ? "text" : "thinking");
+                    const content = payloadString(event.payload, "content") ?? "";
+                    if (block.text !== content) {
+                        diagnostics.push(`${assistantType} mismatch for ${event.messageId}:${contentIndex}`);
+                        block.text = content;
+                    }
+                }
+                else if (contentIndex !== undefined && assistantType === "toolcall_end") {
+                    const block = ensureBlock(message, contentIndex, "toolCall");
+                    block.value = event.payload.toolCall;
+                }
+                else if (assistantType === "done") {
+                    message.status = "finished";
+                }
+                else if (assistantType === "error") {
+                    message.status = "error";
+                }
+                break;
+            }
+            case "message_finished": {
+                if (!event.messageId) {
+                    diagnostics.push(`message_finished ${event.seq} has no messageId`);
+                    break;
+                }
+                const message = messages.get(event.messageId);
+                if (!message) {
+                    diagnostics.push(`message_finished ${event.seq} precedes message_started`);
+                    break;
+                }
+                const settled = event.payload.settled === true;
+                const entryId = payloadString(event.payload, "entryId");
+                if (settled && entryId) {
+                    message.status = "settled";
+                    message.entryId = entryId;
+                    settledEntryIds.push(entryId);
+                    if (!knownEntries.has(entryId)) {
+                        diagnostics.push(`settled entry ${entryId} is missing`);
+                    }
+                }
+                else {
+                    message.status = "unsettled";
+                }
+                break;
+            }
+            case "tool_execution_started": {
+                if (!event.toolCallId || !event.messageId) {
+                    diagnostics.push(`tool_execution_started ${event.seq} is uncorrelated`);
+                    break;
+                }
+                const tool = {
+                    toolCallId: event.toolCallId,
+                    messageId: event.messageId,
+                    toolName: payloadString(event.payload, "toolName") ?? "tool",
+                    status: "running",
+                    updates: 0,
+                    ...(event.payload.args === undefined ? {} : { args: event.payload.args }),
+                };
+                tools.set(event.toolCallId, tool);
+                toolOrder.push(event.toolCallId);
+                break;
+            }
+            case "tool_execution_updated": {
+                const tool = event.toolCallId ? tools.get(event.toolCallId) : undefined;
+                if (tool) {
+                    tool.updates += 1;
+                }
+                else {
+                    diagnostics.push(`tool_execution_updated ${event.seq} precedes start`);
+                }
+                break;
+            }
+            case "tool_execution_finished": {
+                const tool = event.toolCallId ? tools.get(event.toolCallId) : undefined;
+                if (!tool) {
+                    diagnostics.push(`tool_execution_finished ${event.seq} precedes start`);
+                    break;
+                }
+                tool.status = event.payload.isError === true ? "failed" : "finished";
+                if (event.payload.result !== undefined) {
+                    tool.result = event.payload.result;
+                }
+                break;
+            }
+            case "turn_started":
+            case "turn_finished":
+                break;
+            default:
+                break;
+        }
+    }
+    return {
+        throughSeq: lastSeq,
+        messages: messageOrder.map((messageId) => {
+            const message = messages.get(messageId);
+            return {
+                messageId: message.messageId,
+                role: message.role,
+                status: message.status,
+                ...(message.entryId === undefined ? {} : { entryId: message.entryId }),
+                blocks: [...message.blocks.values()].toSorted((left, right) => left.contentIndex - right.contentIndex),
+            };
+        }),
+        tools: toolOrder.map((toolCallId) => tools.get(toolCallId)),
+        settledEntryIds,
+        diagnostics,
+    };
+}
+/** Fold the durable semantic journal through one sequence position. */
+export function reduceSessionEvents(entries, events, throughSeq = Number.MAX_SAFE_INTEGER) {
+    return foldSessionEvents(entries, events, throughSeq);
+}
+/**
+ * In-memory seek index. Checkpoints are viewer-only cache state and are never
+ * persisted into a run bundle.
+ */
+export class SessionReplayIndex {
+    entries;
+    events;
+    checkpoints = [];
+    timestamps;
+    constructor(entries, events, checkpointInterval = 256) {
+        this.entries = entries;
+        this.events = events;
+        let lastTimestamp = Number.NEGATIVE_INFINITY;
+        this.timestamps = events.map((event) => {
+            const parsed = Date.parse(event.at);
+            lastTimestamp = Math.max(lastTimestamp, Number.isFinite(parsed) ? parsed : lastTimestamp);
+            return { at: lastTimestamp, seq: event.seq };
+        });
+        let state = foldSessionEvents(entries, events, 0);
+        this.checkpoints.push({ seq: 0, state });
+        for (let end = checkpointInterval - 1; end < events.length; end += checkpointInterval) {
+            const seq = events[end]?.seq ?? state.throughSeq;
+            state = foldSessionEvents(entries, events, seq, state);
+            this.checkpoints.push({ seq, state });
+        }
+    }
+    stateAtSeq(throughSeq) {
+        const checkpoint = this.checkpoints.findLast(({ seq }) => seq <= throughSeq);
+        return foldSessionEvents(this.entries, this.events, throughSeq, checkpoint?.state);
+    }
+    seqAtOrBefore(timestampMs) {
+        let low = 0;
+        let high = this.timestamps.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if ((this.timestamps[middle]?.at ?? Number.POSITIVE_INFINITY) <= timestampMs) {
+                low = middle + 1;
+            }
+            else {
+                high = middle;
+            }
+        }
+        return low === 0 ? 0 : (this.timestamps[low - 1]?.seq ?? 0);
+    }
+}
+//# sourceMappingURL=session-reducer.js.map

package/dist/viewer/session-reducer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reducer.js","sourceRoot":"","sources":["../../src/viewer/session-reducer.ts"],"names":[],"mappings":"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"}

package/dist/workflows/artifacts.d.ts

@@ -0,0 +1,40 @@
+import type { ArtifactRef, ArtifactValue } from "./types.js";
+/**
+ * Value externalization for run bundles (see docs/run-bundles.md): string
+ * leaves larger than the threshold are written once, content-addressed, under
+ * `artifacts/` and replaced by `{ "$artifact": ref }`. Because artifacts are
+ * immutable and deduplicated by hash, the same output appearing in `outputs`,
+ * `results`, `steps`, and the trace costs one file plus small references.
+ */
+export declare const ARTIFACT_THRESHOLD_BYTES = 4096;
+export declare const ARTIFACTS_DIR = "artifacts";
+export declare function isArtifactValue(value: unknown): value is ArtifactValue;
+/**
+ * Writes externalized string leaves for one run bundle. Instances serialize
+ * their writes and deduplicate by content hash, so encoding the same large
+ * string in several value positions touches the filesystem once.
+ */
+export declare class ArtifactWriter {
+    private readonly runDir;
+    private readonly written;
+    private chain;
+    private dirCreated;
+    constructor(runDir: string);
+    /** True once any artifact exists for this run. */
+    get hasArtifacts(): boolean;
+    externalize(text: string): Promise<ArtifactValue>;
+}
+/**
+ * Encode a persisted value: externalize large string leaves and escape
+ * single-key `$artifact`/`$escaped` objects so the sentinel stays
+ * unambiguous. Returns the original value when nothing changed.
+ */
+export declare function encodeValue(value: unknown, writer: ArtifactWriter, thresholdBytes?: number): Promise<unknown>;
+/**
+ * Walk a persisted value, replacing every `$artifact` sentinel via `resolve`
+ * and unwrapping `$escaped` objects. `resolve` may return the artifact
+ * contents or a placeholder; it receives the reference untouched.
+ */
+export declare function decodeValueWith(value: unknown, resolve: (ref: ArtifactRef) => unknown): unknown;
+/** Resolve every artifact reference in `value` by reading the bundle files. */
+export declare function resolveArtifacts(value: unknown, runDir: string): Promise<unknown>;

package/dist/workflows/artifacts.js

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Value externalization for run bundles (see docs/run-bundles.md): string
+ * leaves larger than the threshold are written once, content-addressed, under
+ * `artifacts/` and replaced by `{ "$artifact": ref }`. Because artifacts are
+ * immutable and deduplicated by hash, the same output appearing in `outputs`,
+ * `results`, `steps`, and the trace costs one file plus small references.
+ */
+export const ARTIFACT_THRESHOLD_BYTES = 4096;
+export const ARTIFACTS_DIR = "artifacts";
+const ARTIFACT_KEY = "$artifact";
+const ESCAPED_KEY = "$escaped";
+export function isArtifactValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        ARTIFACT_KEY in value);
+}
+function isEscapedValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        ESCAPED_KEY in value);
+}
+/** True for a single-key object that would be misread as a sentinel. */
+function needsEscape(value) {
+    const keys = Object.keys(value);
+    return keys.length === 1 && (keys[0] === ARTIFACT_KEY || keys[0] === ESCAPED_KEY);
+}
+/**
+ * Writes externalized string leaves for one run bundle. Instances serialize
+ * their writes and deduplicate by content hash, so encoding the same large
+ * string in several value positions touches the filesystem once.
+ */
+export class ArtifactWriter {
+    runDir;
+    written = new Set();
+    chain = Promise.resolve();
+    dirCreated = false;
+    constructor(runDir) {
+        this.runDir = runDir;
+    }
+    /** True once any artifact exists for this run. */
+    get hasArtifacts() {
+        return this.written.size > 0;
+    }
+    async externalize(text) {
+        const bytes = Buffer.from(text, "utf8");
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        const relativePath = `${ARTIFACTS_DIR}/sha256-${sha256}.txt`;
+        const task = this.chain.then(async () => {
+            if (this.written.has(sha256)) {
+                return;
+            }
+            if (!this.dirCreated) {
+                await fs.mkdir(path.join(this.runDir, ARTIFACTS_DIR), { recursive: true, mode: 0o700 });
+                this.dirCreated = true;
+            }
+            const filePath = path.join(this.runDir, relativePath);
+            // Content-addressed files are immutable; an existing file is complete
+            // unless a previous crash left a partial write, which the temp-rename
+            // pattern prevents.
+            const tempPath = `${filePath}.${process.pid}.tmp`;
+            await fs.writeFile(tempPath, bytes, { mode: 0o600 });
+            await fs.rename(tempPath, filePath);
+            this.written.add(sha256);
+        });
+        this.chain = task.catch(() => undefined);
+        await task;
+        return {
+            $artifact: {
+                path: relativePath,
+                mediaType: "text/plain",
+                bytes: bytes.byteLength,
+                sha256,
+            },
+        };
+    }
+}
+/**
+ * Encode a persisted value: externalize large string leaves and escape
+ * single-key `$artifact`/`$escaped` objects so the sentinel stays
+ * unambiguous. Returns the original value when nothing changed.
+ */
+export async function encodeValue(value, writer, thresholdBytes = ARTIFACT_THRESHOLD_BYTES) {
+    if (typeof value === "string") {
+        if (Buffer.byteLength(value, "utf8") <= thresholdBytes) {
+            return value;
+        }
+        return await writer.externalize(value);
+    }
+    if (Array.isArray(value)) {
+        const encoded = await Promise.all(value.map((item) => encodeValue(item, writer, thresholdBytes)));
+        return encoded.some((item, index) => item !== value[index]) ? encoded : value;
+    }
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        const entries = await Promise.all(Object.entries(record).map(async ([key, item]) => [key, await encodeValue(item, writer, thresholdBytes)]));
+        const changed = entries.some(([key, item]) => item !== record[key]);
+        const encoded = changed ? Object.fromEntries(entries) : record;
+        return needsEscape(record) ? { [ESCAPED_KEY]: encoded } : encoded;
+    }
+    return value;
+}
+/**
+ * Walk a persisted value, replacing every `$artifact` sentinel via `resolve`
+ * and unwrapping `$escaped` objects. `resolve` may return the artifact
+ * contents or a placeholder; it receives the reference untouched.
+ */
+export function decodeValueWith(value, resolve) {
+    if (isArtifactValue(value)) {
+        return resolve(value.$artifact);
+    }
+    if (isEscapedValue(value)) {
+        // The unwrapped object is user data: process its children but do not
+        // re-test the object itself as a sentinel.
+        return decodeChildren(value.$escaped, resolve);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => decodeValueWith(item, resolve));
+    }
+    if (typeof value === "object" && value !== null) {
+        return decodeChildren(value, resolve);
+    }
+    return value;
+}
+function decodeChildren(record, resolve) {
+    return Object.fromEntries(Object.entries(record).map(([key, item]) => [key, decodeValueWith(item, resolve)]));
+}
+/** Resolve every artifact reference in `value` by reading the bundle files. */
+export async function resolveArtifacts(value, runDir) {
+    const refs = [];
+    decodeValueWith(value, (ref) => {
+        refs.push(ref);
+        return null;
+    });
+    const contents = new Map();
+    for (const ref of refs) {
+        if (contents.has(ref.path)) {
+            continue;
+        }
+        const resolved = path.resolve(runDir, ref.path);
+        // A reference must never escape the bundle directory.
+        if (!resolved.startsWith(path.resolve(runDir) + path.sep)) {
+            throw new Error(`Artifact path escapes the bundle: ${ref.path}`);
+        }
+        contents.set(ref.path, await fs.readFile(resolved, "utf8"));
+    }
+    return decodeValueWith(value, (ref) => contents.get(ref.path) ?? null);
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/workflows/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../src/workflows/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/workflows/engine.d.ts

@@ -11,14 +11,23 @@ export declare class WorkflowEngine {
     private readonly defaultNodeTimeoutMs;
     private readonly maxSteps;
     private readonly onEvent?;
+    private readonly onRunStarted?;
+    private readonly onRunFinishing?;
     private activeAbort;
     private cancelled;
+    private parked;
     private paused;
     private wakePause;
     constructor(options: WorkflowEngineOptions);
     get outputRoot(): string;
     /** Abort the currently running node and mark the run cancelled. */
     cancel(): void;
+    /**
+     * Stop without a terminal event so another runner can claim and resume
+     * the run. The active node aborts; its partial attempt is never recorded,
+     * so resume reruns that node from its last persisted boundary.
+     */
+    park(): void;
     /**
      * Request a pause. The current step finishes normally; the engine then
      * holds before dispatching the next node until `resume` (or `cancel`).
@@ -30,7 +39,36 @@ export declare class WorkflowEngine {
     get pauseRequested(): boolean;
     run(workflow: WorkflowDefinition, input: unknown, options?: {
         workflowPath?: string;
+        workflowHash?: string;
+        runId?: string;
+    }): Promise<WorkflowRunResult>;
+    /**
+     * Resume an interrupted run at the node it stopped on. The caller must
+     * hold the run's queue claim. Completed nodes replay from the recorded
+     * state; only the interrupted node and everything downstream rerun.
+     */
+    resumeRun(workflow: WorkflowDefinition, runId: string, options?: {
+        workflowHash?: string;
+        force?: boolean;
     }): Promise<WorkflowRunResult>;
+    /**
+     * Start a continuation run from a checkpointed parent. The new run gets a
+     * fresh bundle and trace, carries forward the parent's outputs, results,
+     * and step accounting, and continues routing after the checkpoint.
+     */
+    continueRun(workflow: WorkflowDefinition, parentRunId: string, input: unknown, options?: {
+        workflowPath?: string;
+        workflowHash?: string;
+        runId?: string;
+        force?: boolean;
+    }): Promise<WorkflowRunResult>;
+    /**
+     * Find where a resumed run continues. An in-flight node reruns; otherwise
+     * routing continues from the last recorded step. A null nodeId means the
+     * graph was already done when the crash hit.
+     */
+    private resumePointFor;
+    private finishAfterError;
     /**
      * Resolve the run title inside a cancellation and timeout boundary. This
      * runs before any node abort controller exists, so without it a hung async