@osolmaz/pi-workflows 0.2.0 → 0.4.0

package/dist/host/rpc-bridge.js

@@ -0,0 +1,39 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+export const RPC_SUBMISSION_PREFIX = "PI_WORKFLOWS_STEP_SUBMISSION ";
+/**
+ * Loaded into headless `pi --mode rpc` children spawned by the standalone
+ * host. The child has no workflow engine, so this bridge only registers the
+ * `workflow` tool and reports every submission to the host over stderr; the
+ * host validates against the engine and re-prompts on rejection.
+ */
+export default function piWorkflowsRpcBridge(pi) {
+    pi.registerTool({
+        name: "workflow",
+        label: "Workflow",
+        description: [
+            "Submit the output for the pending workflow step with action submit.",
+            "Only call this tool when a workflow step contract in the conversation asks you to.",
+            "Pass the exact step id from the contract and your result as the output.",
+        ].join(" "),
+        parameters: Type.Object({
+            action: StringEnum(["submit"]),
+            step: Type.String({ description: "Step id from the workflow step contract" }),
+            attempt: Type.String({ description: "Attempt id from the workflow step contract" }),
+            output: Type.Unknown({ description: "Step output matching the expected shape" }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            process.stderr.write(`${RPC_SUBMISSION_PREFIX}${JSON.stringify(params)}\n`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Submission recorded. Continue only when the workflow sends the next step.",
+                    },
+                ],
+                details: {},
+            };
+        },
+    });
+}
+//# sourceMappingURL=rpc-bridge.js.map

package/dist/host/rpc-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-bridge.js","sourceRoot":"","sources":["../../src/host/rpc-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,MAAM,CAAC,MAAM,qBAAqB,GAAG,+BAA+B,CAAC;AAErE;;;;;GAKG;AACH,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAAC,EAAgB;IAC3D,EAAE,CAAC,YAAY,CAAC;QACd,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,UAAU;QACjB,WAAW,EAAE;YACX,qEAAqE;YACrE,oFAAoF;YACpF,yEAAyE;SAC1E,CAAC,IAAI,CAAC,GAAG,CAAC;QACX,UAAU,EAAE,IAAI,CAAC,MAAM,CACrB;YACE,MAAM,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAU,CAAC;YACvC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,yCAAyC,EAAE,CAAC;YAC7E,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,4CAA4C,EAAE,CAAC;YACnF,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,yCAAyC,EAAE,CAAC;SACjF,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAChC;QACD,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM;YAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,qBAAqB,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5E,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,2EAA2E;qBAClF;iBACF;gBACD,OAAO,EAAE,EAAE;aACZ,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/host/rpc-executor.d.ts

@@ -0,0 +1,38 @@
+import type { AgentStepExecutor, AgentStepRequest, AgentStepSubmission } from "../workflows/types.js";
+import type { HostProcessRegistry } from "./processes.js";
+export type RpcStepExecutorOptions = {
+    cwd: string;
+    registry: HostProcessRegistry;
+    /** Absolute path to the pi binary; defaults to the installed `pi`. */
+    piBin?: string;
+    /** Extra environment for the child; the host's environment is inherited. */
+    env?: Record<string, string>;
+    /** Extra pi arguments, for example a model override. */
+    piArgs?: string[];
+};
+/**
+ * Runs agent steps in a headless `pi --mode rpc` child. One child serves one
+ * workflow run. The rpc-bridge extension inside the child registers the
+ * `workflow` tool and reports submissions over stderr; this executor
+ * validates them through `request.accept` and re-prompts on rejection, so
+ * the model sees the same tool contract as an in-session run.
+ */
+export declare class RpcStepExecutor implements AgentStepExecutor {
+    private readonly options;
+    private child;
+    private childExited;
+    private stderrBuffer;
+    private submissions;
+    private submissionWaiters;
+    private stdoutBuffer;
+    constructor(options: RpcStepExecutorOptions);
+    runAgentStep(request: AgentStepRequest, signal: AbortSignal): Promise<AgentStepSubmission>;
+    /** Stop the child's whole process group, then unregister it. */
+    close(): Promise<void>;
+    private currentExit;
+    private ensureStarted;
+    private promptForSubmission;
+    private takeMatchingSubmission;
+    private sendAbortQuietly;
+    private wakeSubmissionWaiters;
+}

package/dist/host/rpc-executor.js

@@ -0,0 +1,254 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { RPC_SUBMISSION_PREFIX } from "./rpc-bridge.js";
+// Production resolves the compiled .js; tests and dev checkouts load the .ts
+// source, which pi compiles itself when loading extensions.
+const BRIDGE_PATH = ["./rpc-bridge.js", "./rpc-bridge.ts"]
+    .map((candidate) => fileURLToPath(new URL(candidate, import.meta.url)))
+    .find((candidate) => fs.existsSync(candidate));
+const ABORT_GRACE_MS = 3_000;
+/**
+ * Runs agent steps in a headless `pi --mode rpc` child. One child serves one
+ * workflow run. The rpc-bridge extension inside the child registers the
+ * `workflow` tool and reports submissions over stderr; this executor
+ * validates them through `request.accept` and re-prompts on rejection, so
+ * the model sees the same tool contract as an in-session run.
+ */
+export class RpcStepExecutor {
+    options;
+    child = null;
+    childExited = null;
+    stderrBuffer = "";
+    submissions = [];
+    submissionWaiters = [];
+    stdoutBuffer = "";
+    constructor(options) {
+        this.options = options;
+    }
+    async runAgentStep(request, signal) {
+        this.ensureStarted();
+        let prompt = request.prompt;
+        for (;;) {
+            throwIfAborted(signal);
+            const submission = await this.promptForSubmission(prompt, request, signal);
+            const accepted = await request.accept(submission.output);
+            if (accepted.ok) {
+                return { output: accepted.value };
+            }
+            prompt = [
+                `The workflow rejected your submission for step ${JSON.stringify(request.contract.nodeId)}:`,
+                accepted.error,
+                "",
+                "Call the `workflow` tool again with a corrected output.",
+            ].join("\n");
+        }
+    }
+    /** Stop the child's whole process group, then unregister it. */
+    async close() {
+        const child = this.child;
+        this.child = null;
+        if (child === null) {
+            return;
+        }
+        const pid = child.pid;
+        if (this.childExited === null) {
+            try {
+                child.stdin?.end();
+            }
+            catch {
+                // The pipe may already be closed.
+            }
+            // The child spawns in its own group; tool calls can leave
+            // grandchildren that leader-only signals would orphan forever.
+            if (pid !== undefined) {
+                killGroup(pid, "SIGTERM");
+            }
+            else {
+                child.kill("SIGTERM");
+            }
+            const exited = await waitForExit(child, ABORT_GRACE_MS);
+            if (!exited) {
+                if (pid !== undefined) {
+                    killGroup(pid, "SIGKILL");
+                }
+                else {
+                    child.kill("SIGKILL");
+                }
+            }
+        }
+        if (pid !== undefined) {
+            this.options.registry.unregister(pid);
+        }
+    }
+    currentExit() {
+        return this.childExited;
+    }
+    ensureStarted() {
+        if (this.child !== null) {
+            const exited = this.currentExit();
+            if (exited !== null) {
+                throw new Error(`Headless pi session exited (code ${exited.code}, signal ${exited.signal})`);
+            }
+            return;
+        }
+        if (BRIDGE_PATH === undefined) {
+            throw new Error("The pi-workflows rpc-bridge extension is missing from this installation");
+        }
+        const piBin = this.options.piBin ?? "pi";
+        const child = spawn(piBin, [
+            "--mode",
+            "rpc",
+            "--no-session",
+            // Isolation is required: an installed pi-workflows extension would
+            // otherwise load beside the bridge, register a competing workflow
+            // tool, and start its own resume and controller workers.
+            "--no-extensions",
+            "-e",
+            BRIDGE_PATH,
+            ...(this.options.piArgs ?? []),
+        ], {
+            cwd: this.options.cwd,
+            env: { ...process.env, ...this.options.env },
+            stdio: ["pipe", "pipe", "pipe"],
+            // Own process group: the host kills groups, never individual PIDs,
+            // so a killed host cannot leave an orphaned agent working.
+            detached: true,
+        });
+        this.child = child;
+        if (child.pid !== undefined) {
+            this.options.registry.register(child.pid);
+        }
+        child.on("exit", (code, signal) => {
+            this.childExited = { code, signal };
+            if (child.pid !== undefined) {
+                this.options.registry.unregister(child.pid);
+            }
+            this.wakeSubmissionWaiters();
+        });
+        // A failed spawn (missing binary, EACCES) emits error instead of exit;
+        // without a listener it would crash the host as an uncaught exception.
+        child.on("error", (error) => {
+            this.childExited = { code: null, signal: error.message };
+            this.wakeSubmissionWaiters();
+        });
+        child.stdin?.on("error", () => {
+            // Writes racing child exit surface asynchronously as EPIPE; the step
+            // fails through the exit path instead of an uncaught stream error.
+        });
+        child.stderr?.on("data", (chunk) => {
+            this.stderrBuffer += chunk.toString("utf8");
+            const lines = this.stderrBuffer.split("\n");
+            this.stderrBuffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (!line.startsWith(RPC_SUBMISSION_PREFIX)) {
+                    continue;
+                }
+                try {
+                    const parsed = JSON.parse(line.slice(RPC_SUBMISSION_PREFIX.length));
+                    if (parsed.action === "submit" &&
+                        typeof parsed.step === "string" &&
+                        typeof parsed.attempt === "string") {
+                        this.submissions.push(parsed);
+                    }
+                }
+                catch {
+                    // A malformed marker line is ignored; the step times out instead.
+                }
+            }
+            this.wakeSubmissionWaiters();
+        });
+        // stdout carries the RPC event stream. The submission channel is stderr,
+        // so stdout is only drained to keep the pipe from blocking.
+        child.stdout?.on("data", (chunk) => {
+            this.stdoutBuffer = (this.stdoutBuffer + chunk.toString("utf8")).slice(-64 * 1024);
+        });
+    }
+    async promptForSubmission(prompt, request, signal) {
+        const child = this.child;
+        if (child === null || this.childExited !== null) {
+            throw new Error("Headless pi session is not running");
+        }
+        const matching = this.takeMatchingSubmission(request);
+        if (matching !== undefined) {
+            return matching;
+        }
+        child.stdin?.write(`${JSON.stringify({ type: "prompt", message: prompt })}\n`);
+        for (;;) {
+            throwIfAborted(signal);
+            const exited = this.currentExit();
+            if (exited !== null) {
+                throw new Error(`Headless pi session exited mid-step (code ${exited.code})`);
+            }
+            const found = this.takeMatchingSubmission(request);
+            if (found !== undefined) {
+                return found;
+            }
+            await new Promise((resolve, reject) => {
+                const waiter = () => {
+                    signal.removeEventListener("abort", onAbort);
+                    resolve();
+                };
+                const onAbort = () => {
+                    this.sendAbortQuietly();
+                    reject(signal.reason ?? new Error("Workflow step aborted"));
+                };
+                this.submissionWaiters.push(waiter);
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+        }
+    }
+    takeMatchingSubmission(request) {
+        const index = this.submissions.findIndex((candidate) => candidate.step === request.contract.nodeId &&
+            candidate.attempt === request.contract.attemptId);
+        return index === -1 ? undefined : this.submissions.splice(index, 1)[0];
+    }
+    sendAbortQuietly() {
+        try {
+            this.child?.stdin?.write(`${JSON.stringify({ type: "abort" })}\n`);
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    wakeSubmissionWaiters() {
+        const waiters = this.submissionWaiters;
+        this.submissionWaiters = [];
+        for (const waiter of waiters) {
+            waiter();
+        }
+    }
+}
+function killGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+        return;
+    }
+    catch {
+        // Group signals are unsupported here; the leader still needs it.
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // Already gone.
+    }
+}
+function throwIfAborted(signal) {
+    if (signal.aborted) {
+        throw signal.reason ?? new Error("Workflow step aborted");
+    }
+}
+async function waitForExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return true;
+    }
+    return await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), timeoutMs);
+        child.once("exit", () => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}
+//# sourceMappingURL=rpc-executor.js.map

package/dist/host/rpc-executor.js.map

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

package/dist/host/runner.d.ts

@@ -0,0 +1,50 @@
+import { HostProcessRegistry } from "./processes.js";
+export type WorkflowHostOptions = {
+    cwd: string;
+    runnerId?: string;
+    /** Explicit store path; defaults to the project-scoped controller store. */
+    storeFile?: string;
+    /** Explicit run-bundle root; defaults to the shared runs directory. */
+    runsDir?: string;
+    registry?: HostProcessRegistry;
+    piArgs?: string[];
+    /** Extra environment for headless children (for example a test provider). */
+    env?: Record<string, string>;
+    /** Poll interval for the claim loop; tests use a faster cadence. */
+    claimPollMs?: number;
+    onLog?: (message: string) => void;
+};
+/**
+ * The always-on runner: claims parked workflow runs and reconciles durable
+ * controllers without a Pi session. Conversation nodes execute in headless
+ * `pi --mode rpc` children. Everything the host does is recoverable: claims
+ * expire, bundles fence stale writers, and child processes are reaped by
+ * the next host.
+ */
+export declare class WorkflowHost {
+    private readonly options;
+    private readonly runnerId;
+    private readonly registry;
+    private readonly store;
+    private readonly childRunStore;
+    private manager;
+    private pollTimer;
+    private readonly activeRuns;
+    private readonly migrationBlockedRuns;
+    private readonly schedulerExecutors;
+    /** Runs whose resume refused (edited source); skipped until a host restart. */
+    private readonly skippedRuns;
+    private stopping;
+    private readonly stateDir;
+    constructor(options: WorkflowHostOptions);
+    private log;
+    /** Take the advisory lock, reap orphans, and start claiming. */
+    start(): Promise<void>;
+    /** Drain: stop claiming, park in-flight runs, stop controllers, kill children. */
+    stop(): Promise<void>;
+    private readonly parkedEngines;
+    private claimOnce;
+    private runClaimed;
+    private failUnresumable;
+    private recordEvent;
+}