@osolmaz/pi-workflows 0.1.0

package/dist/viewer/tui.js

@@ -0,0 +1,140 @@
+import { listRunBundles, readRunBundle } from "../workflows/store.js";
+import { maxDetailScroll, renderRunDetailLines, renderRunListLines, } from "./render.js";
+import { watchRunsDir } from "./watch.js";
+const ALT_SCREEN_ON = "\u001b[?1049h\u001b[?25l";
+const ALT_SCREEN_OFF = "\u001b[?25h\u001b[?1049l";
+const CLEAR = "\u001b[2J\u001b[H";
+function viewportSize() {
+    return {
+        width: process.stdout.columns ?? 80,
+        height: process.stdout.rows ?? 24,
+    };
+}
+/**
+ * Interactive live viewer. Watches the runs directory and re-renders as run
+ * bundles change on disk. Returns when the user quits.
+ */
+export async function runViewer(options) {
+    let mode = { view: "list" };
+    let bundles = [];
+    let selectedIndex = 0;
+    let detailScroll = 0;
+    /** Replay position; null follows the latest step live. */
+    let selectedStep = null;
+    let detailStepCount = 0;
+    if (options.runId) {
+        bundles = await listRunBundles(options.runsDir);
+        const match = bundles.find((bundle) => bundle.state.runId === options.runId);
+        if (!match) {
+            throw new Error(`Run not found: ${options.runId}`);
+        }
+        mode = { view: "detail", runDir: match.runDir };
+    }
+    const draw = async () => {
+        bundles = await listRunBundles(options.runsDir);
+        selectedIndex = Math.min(selectedIndex, Math.max(0, bundles.length - 1));
+        const size = viewportSize();
+        const lines = mode.view === "list"
+            ? renderRunListLines(bundles, selectedIndex, size)
+            : await renderDetail(mode.runDir, size);
+        process.stdout.write(CLEAR + lines.join("\n"));
+    };
+    const renderDetail = async (runDir, size) => {
+        const bundle = await readRunBundle(runDir);
+        if (!bundle) {
+            return ["Run bundle disappeared. Press q to go back."];
+        }
+        detailStepCount = bundle.state.steps.length;
+        if (selectedStep !== null && selectedStep >= detailStepCount - 1) {
+            // Scrubbed to (or past) the end: snap back to following live updates.
+            selectedStep = null;
+        }
+        detailScroll = Math.min(detailScroll, maxDetailScroll(bundle, size, selectedStep));
+        return renderRunDetailLines(bundle, size, new Date(), detailScroll, selectedStep);
+    };
+    process.stdout.write(ALT_SCREEN_ON);
+    const stopWatching = watchRunsDir(options.runsDir, () => {
+        void draw();
+    });
+    const ticker = setInterval(() => {
+        void draw();
+    }, options.tickMs ?? 1_000);
+    const rawModeSupported = process.stdin.isTTY === true;
+    if (rawModeSupported) {
+        process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    try {
+        await new Promise((resolve) => {
+            const onKey = (data) => {
+                const key = data.toString("utf8");
+                if (key === "q" || key === "\u0003" || key === "\u001b") {
+                    if (mode.view === "detail" && key === "q") {
+                        mode = { view: "list" };
+                        void draw();
+                        return;
+                    }
+                    resolve();
+                    return;
+                }
+                handleNavigationKey(key);
+            };
+            const handleNavigationKey = (key) => {
+                if (mode.view !== "list") {
+                    if (key === "r") {
+                        void draw();
+                    }
+                    else if (key === "\u001b[A" || key === "k") {
+                        detailScroll = Math.max(0, detailScroll - 1);
+                        void draw();
+                    }
+                    else if (key === "\u001b[B" || key === "j") {
+                        // Clamped against the content height in renderDetail.
+                        detailScroll += 1;
+                        void draw();
+                    }
+                    else if (key === "\u001b[D" || key === "h") {
+                        const current = selectedStep ?? detailStepCount - 1;
+                        selectedStep = Math.max(0, current - 1);
+                        void draw();
+                    }
+                    else if (key === "\u001b[C" || key === "l") {
+                        // renderDetail snaps back to live once this reaches the end.
+                        selectedStep = selectedStep === null ? null : selectedStep + 1;
+                        void draw();
+                    }
+                    return;
+                }
+                if (key === "\u001b[A" || key === "k") {
+                    selectedIndex = Math.max(0, selectedIndex - 1);
+                    void draw();
+                }
+                else if (key === "\u001b[B" || key === "j") {
+                    selectedIndex = Math.min(Math.max(0, bundles.length - 1), selectedIndex + 1);
+                    void draw();
+                }
+                else if (key === "\r" || key === "\n") {
+                    const selected = bundles[selectedIndex];
+                    if (selected) {
+                        mode = { view: "detail", runDir: selected.runDir };
+                        detailScroll = 0;
+                        selectedStep = null;
+                        void draw();
+                    }
+                }
+            };
+            process.stdin.on("data", onKey);
+            void draw();
+        });
+    }
+    finally {
+        clearInterval(ticker);
+        stopWatching();
+        if (rawModeSupported) {
+            process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+        process.stdout.write(ALT_SCREEN_OFF);
+    }
+}
+//# sourceMappingURL=tui.js.map

package/dist/viewer/tui.js.map

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

package/dist/viewer/watch.d.ts

@@ -0,0 +1,9 @@
+export type Unsubscribe = () => void;
+/**
+ * Watch a directory tree for changes with a polling fallback. `onChange` is
+ * debounced so bursts of writes trigger one refresh.
+ */
+export declare function watchRunsDir(dir: string, onChange: () => void, options?: {
+    pollMs?: number;
+    debounceMs?: number;
+}): Unsubscribe;

package/dist/viewer/watch.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+/**
+ * Watch a directory tree for changes with a polling fallback. `onChange` is
+ * debounced so bursts of writes trigger one refresh.
+ */
+export function watchRunsDir(dir, onChange, options = {}) {
+    const pollMs = options.pollMs ?? 1_000;
+    const debounceMs = options.debounceMs ?? 80;
+    let debounceTimer = null;
+    let closed = false;
+    const fire = () => {
+        if (closed) {
+            return;
+        }
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            onChange();
+        }, debounceMs);
+    };
+    let watcher = null;
+    try {
+        watcher = fs.watch(dir, { recursive: true }, fire);
+        watcher.on("error", () => {
+            watcher?.close();
+            watcher = null;
+        });
+    }
+    catch {
+        watcher = null;
+    }
+    // Polling fallback covers platforms without recursive fs.watch and missed events.
+    const poller = setInterval(fire, pollMs);
+    poller.unref?.();
+    return () => {
+        closed = true;
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        clearInterval(poller);
+        watcher?.close();
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/viewer/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/viewer/watch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAIzB;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAW,EACX,QAAoB,EACpB,OAAO,GAA6C,EAAE;IAEtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;IAC5C,IAAI,aAAa,GAA0B,IAAI,CAAC;IAChD,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,IAAI,MAAM,EAAE,CAAC;YACX,OAAO;QACT,CAAC;QACD,IAAI,aAAa,EAAE,CAAC;YAClB,YAAY,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;QACD,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,aAAa,GAAG,IAAI,CAAC;YACrB,QAAQ,EAAE,CAAC;QACb,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC;IAEF,IAAI,OAAO,GAAwB,IAAI,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;QACnD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACvB,OAAO,EAAE,KAAK,EAAE,CAAC;YACjB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,kFAAkF;IAClF,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;IAEjB,OAAO,GAAG,EAAE;QACV,MAAM,GAAG,IAAI,CAAC;QACd,IAAI,aAAa,EAAE,CAAC;YAClB,YAAY,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;QACD,aAAa,CAAC,MAAM,CAAC,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC"}

package/dist/workflows/decision.d.ts

@@ -0,0 +1,25 @@
+import type { AgentNodeDefinition, WorkflowEdge, WorkflowNodeContext } from "./types.js";
+type DecisionAgentOptions = Omit<AgentNodeDefinition, "nodeType" | "prompt" | "expectedOutput" | "validate">;
+export type DecisionDefinition<TChoice extends string> = DecisionAgentOptions & {
+    question: string | ((context: WorkflowNodeContext) => string | Promise<string>);
+    choices: readonly TChoice[];
+    field?: string;
+};
+/**
+ * Build an `agent` node that asks the model to pick one of `choices` and
+ * submit a JSON object whose chosen field is validated. Pair with
+ * `decisionEdge` (or any `switch` edge keyed on `$.<field>`) to route on the
+ * result.
+ */
+export declare function decision<TChoice extends string>(definition: DecisionDefinition<TChoice>): AgentNodeDefinition;
+/**
+ * Build the matching `switch` edge for a `decision` node. Typing `cases` as
+ * `Record<TChoice, string>` makes a missing case a compile error.
+ */
+export declare function decisionEdge<TChoice extends string>(args: {
+    from: string;
+    choices: readonly TChoice[];
+    field?: string;
+    cases: Record<TChoice, string>;
+}): WorkflowEdge;
+export {};

package/dist/workflows/decision.js

@@ -0,0 +1,96 @@
+import { agent } from "./definition.js";
+import { extractJsonValue } from "./json.js";
+const DEFAULT_FIELD = "route";
+const SIMPLE_FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Build an `agent` node that asks the model to pick one of `choices` and
+ * submit a JSON object whose chosen field is validated. Pair with
+ * `decisionEdge` (or any `switch` edge keyed on `$.<field>`) to route on the
+ * result.
+ */
+export function decision(definition) {
+    const { question, choices, field: fieldOverride, ...agentOptions } = definition;
+    const field = normalizeField(fieldOverride);
+    assertValidChoices(choices);
+    const allowed = new Set(choices);
+    const allowedLabels = choices.map((choice) => JSON.stringify(choice)).join(" | ");
+    return agent({
+        ...agentOptions,
+        async prompt(context) {
+            const text = typeof question === "function" ? await question(context) : question;
+            return [
+                text,
+                "",
+                `Answer by picking exactly one of: ${allowedLabels}.`,
+                `Include a short "reason" alongside your choice.`,
+            ].join("\n");
+        },
+        expectedOutput: `{ ${JSON.stringify(field)}: ${allowedLabels}, "reason": "short justification" }`,
+        validate(output) {
+            const raw = normalizeDecisionOutput(output);
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                throw new Error(`Decision output must be a JSON object, got ${describeValue(raw)}`);
+            }
+            const value = raw[field];
+            if (typeof value !== "string" || !allowed.has(value)) {
+                throw new Error(`Decision returned invalid ${field}=${JSON.stringify(value)}; expected one of ${allowedLabels}`);
+            }
+            return raw;
+        },
+    });
+}
+/**
+ * Build the matching `switch` edge for a `decision` node. Typing `cases` as
+ * `Record<TChoice, string>` makes a missing case a compile error.
+ */
+export function decisionEdge(args) {
+    const field = normalizeField(args.field);
+    assertValidChoices(args.choices);
+    for (const choice of args.choices) {
+        if (!Object.hasOwn(args.cases, choice)) {
+            throw new Error(`Decision edge is missing case for choice ${JSON.stringify(choice)}`);
+        }
+    }
+    return {
+        from: args.from,
+        switch: {
+            on: `$.${field}`,
+            cases: args.cases,
+        },
+    };
+}
+function normalizeDecisionOutput(output) {
+    if (typeof output === "string") {
+        return extractJsonValue(output);
+    }
+    return output;
+}
+function describeValue(value) {
+    if (value === null) {
+        return "null";
+    }
+    return Array.isArray(value) ? "array" : typeof value;
+}
+function assertValidChoices(choices) {
+    if (choices.length === 0) {
+        throw new Error("Decision choices must include at least one value");
+    }
+    const seen = new Set();
+    for (const choice of choices) {
+        if (typeof choice !== "string" || choice.length === 0) {
+            throw new Error("Decision choices must be non-empty strings");
+        }
+        if (seen.has(choice)) {
+            throw new Error(`Decision choices must be unique; duplicate ${JSON.stringify(choice)}`);
+        }
+        seen.add(choice);
+    }
+}
+function normalizeField(fieldOverride) {
+    const field = fieldOverride ?? DEFAULT_FIELD;
+    if (!SIMPLE_FIELD_PATTERN.test(field)) {
+        throw new Error(`Decision field must be a simple JSON key matching ${SIMPLE_FIELD_PATTERN.source}`);
+    }
+    return field;
+}
+//# sourceMappingURL=decision.js.map

package/dist/workflows/decision.js.map

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

package/dist/workflows/definition.d.ts

@@ -0,0 +1,9 @@
+import type { AgentNodeDefinition, CheckpointNodeDefinition, ComputeNodeDefinition, FunctionActionNodeDefinition, ShellActionNodeDefinition, WorkflowDefinition } from "./types.js";
+export declare function defineWorkflow<TWorkflow extends WorkflowDefinition>(definition: TWorkflow): TWorkflow;
+export declare function isWorkflowDefinition(value: unknown): value is WorkflowDefinition;
+export declare function agent(definition: Omit<AgentNodeDefinition, "nodeType">): AgentNodeDefinition;
+export declare function compute(definition: Omit<ComputeNodeDefinition, "nodeType">): ComputeNodeDefinition;
+export declare function action(definition: Omit<FunctionActionNodeDefinition, "nodeType">): FunctionActionNodeDefinition;
+export declare function action(definition: Omit<ShellActionNodeDefinition, "nodeType">): ShellActionNodeDefinition;
+export declare function shell(definition: Omit<ShellActionNodeDefinition, "nodeType">): ShellActionNodeDefinition;
+export declare function checkpoint(definition?: Omit<CheckpointNodeDefinition, "nodeType">): CheckpointNodeDefinition;

package/dist/workflows/definition.js

@@ -0,0 +1,61 @@
+import { assertValidAgentNode, assertValidActionNode, assertValidCheckpointNode, assertValidComputeNode, assertValidShellActionNode, assertValidWorkflowDefinitionShape, } from "./schema.js";
+const WORKFLOW_DEFINITION_BRAND = Symbol.for("pi-workflows.definition");
+export function defineWorkflow(definition) {
+    assertValidWorkflowDefinitionShape(definition);
+    if (isWorkflowDefinition(definition)) {
+        return definition;
+    }
+    Object.defineProperty(definition, WORKFLOW_DEFINITION_BRAND, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return definition;
+}
+export function isWorkflowDefinition(value) {
+    return (value != null &&
+        typeof value === "object" &&
+        value[WORKFLOW_DEFINITION_BRAND] === true);
+}
+export function agent(definition) {
+    const node = {
+        nodeType: "agent",
+        ...definition,
+    };
+    assertValidAgentNode(node);
+    return node;
+}
+export function compute(definition) {
+    const node = {
+        nodeType: "compute",
+        ...definition,
+    };
+    assertValidComputeNode(node);
+    return node;
+}
+export function action(definition) {
+    const node = {
+        nodeType: "action",
+        ...definition,
+    };
+    assertValidActionNode(node);
+    return node;
+}
+export function shell(definition) {
+    const node = {
+        nodeType: "action",
+        ...definition,
+    };
+    assertValidShellActionNode(node);
+    return node;
+}
+export function checkpoint(definition = {}) {
+    const node = {
+        nodeType: "checkpoint",
+        ...definition,
+    };
+    assertValidCheckpointNode(node);
+    return node;
+}
+//# sourceMappingURL=definition.js.map

package/dist/workflows/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/workflows/definition.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,kCAAkC,GACnC,MAAM,aAAa,CAAC;AAWrB,MAAM,yBAAyB,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAExE,MAAM,UAAU,cAAc,CAC5B,UAAqB;IAErB,kCAAkC,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,yBAAyB,EAAE;QAC3D,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IACH,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,CACL,KAAK,IAAI,IAAI;QACb,OAAO,KAAK,KAAK,QAAQ;QACxB,KAAsC,CAAC,yBAAyB,CAAC,KAAK,IAAI,CAC5E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,UAAiD;IACrE,MAAM,IAAI,GAAwB;QAChC,QAAQ,EAAE,OAAO;QACjB,GAAG,UAAU;KACd,CAAC;IACF,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,OAAO,CACrB,UAAmD;IAEnD,MAAM,IAAI,GAA0B;QAClC,QAAQ,EAAE,SAAS;QACnB,GAAG,UAAU;KACd,CAAC;IACF,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC;AACd,CAAC;AAQD,MAAM,UAAU,MAAM,CACpB,UAE+C;IAE/C,MAAM,IAAI,GAAyB;QACjC,QAAQ,EAAE,QAAQ;QAClB,GAAG,UAAU;KACd,CAAC;IACF,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,KAAK,CACnB,UAAuD;IAEvD,MAAM,IAAI,GAA8B;QACtC,QAAQ,EAAE,QAAQ;QAClB,GAAG,UAAU;KACd,CAAC;IACF,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,UAAU,GAA+C,EAAE;IAE3D,MAAM,IAAI,GAA6B;QACrC,QAAQ,EAAE,YAAY;QACtB,GAAG,UAAU;KACd,CAAC;IACF,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/workflows/engine.d.ts

@@ -0,0 +1,65 @@
+import type { WorkflowDefinition, WorkflowEngineOptions, WorkflowRunResult } from "./types.js";
+/**
+ * Executes a workflow graph step by step. Agent steps are delegated to the
+ * configured executor; compute/action/checkpoint nodes run inline. Every
+ * state transition is persisted to the run bundle before the engine moves on,
+ * so a live viewer can follow along by watching the bundle directory.
+ */
+export declare class WorkflowEngine {
+    private readonly executor;
+    private readonly store;
+    private readonly defaultNodeTimeoutMs;
+    private readonly maxSteps;
+    private readonly onEvent?;
+    private activeAbort;
+    private cancelled;
+    private paused;
+    private wakePause;
+    constructor(options: WorkflowEngineOptions);
+    get outputRoot(): string;
+    /** Abort the currently running node and mark the run cancelled. */
+    cancel(): void;
+    /**
+     * Request a pause. The current step finishes normally; the engine then
+     * holds before dispatching the next node until `resume` (or `cancel`).
+     */
+    pause(): void;
+    /** Release a pause requested with `pause`. */
+    resume(): void;
+    /** True when a pause has been requested or the run is already held. */
+    get pauseRequested(): boolean;
+    run(workflow: WorkflowDefinition, input: unknown, options?: {
+        workflowPath?: string;
+    }): Promise<WorkflowRunResult>;
+    /**
+     * Resolve the run title inside a cancellation and timeout boundary. This
+     * runs before any node abort controller exists, so without it a hung async
+     * `title` callback would leave the session permanently occupied.
+     */
+    private resolveTitleBounded;
+    private createRunState;
+    private executeGraph;
+    /**
+     * Hold the run at the step boundary while a pause is in effect. Pausing
+     * never interrupts a node mid-flight; it only delays the next dispatch.
+     */
+    private holdWhilePaused;
+    private routeAfterFailure;
+    private recordAttempt;
+    private executeNode;
+    private outcomeForError;
+    private createNodeResult;
+    private runNodeWithTimeout;
+    private dispatchNode;
+    private createNodeContext;
+    private runAgentNode;
+    private acceptSubmission;
+    private runActionNode;
+    private persist;
+    private finishRun;
+}
+/**
+ * The step contract appended to every agent-node prompt. This is the
+ * documented standard for how the model completes a workflow step.
+ */
+export declare function appendStepContract(prompt: string, workflowName: string, nodeId: string, attemptId: string, expectedOutput: string | undefined): string;