@osolmaz/pi-workflows 0.1.0 → 0.3.0

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,49 @@
+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 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;
+}

package/dist/host/runner.js

@@ -0,0 +1,350 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ControllerManager, loadDiscoveredControllers, projectControllerStorePath, SqliteControllerStore, WorkflowEngineScheduler, } from "../controllers/index.js";
+import { WorkflowEngine } from "../workflows/engine.js";
+import { ClaimLostError, errorMessage, isClaimLostError, WorkflowSourceChangedError, } from "../workflows/errors.js";
+import { hashWorkflowSource, loadWorkflowFile, resolveWorkflowRef } from "../workflows/loader.js";
+import { WorkflowRunStore } from "../workflows/store.js";
+import { HostProcessRegistry } from "./processes.js";
+import { RpcStepExecutor } from "./rpc-executor.js";
+const CLAIM_POLL_MS = 2_000;
+const RUN_CLAIM_LEASE_MS = 30_000;
+const RUN_CLAIM_RENEW_MS = 10_000;
+/**
+ * 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 class WorkflowHost {
+    options;
+    runnerId;
+    registry;
+    store;
+    childRunStore;
+    manager = null;
+    pollTimer = null;
+    activeRuns = new Map();
+    schedulerExecutors = new Map();
+    /** Runs whose resume refused (edited source); skipped until a host restart. */
+    skippedRuns = new Set();
+    stopping = false;
+    stateDir;
+    constructor(options) {
+        this.options = options;
+        this.runnerId = options.runnerId ?? `host-${randomUUID().slice(0, 8)}`;
+        this.store = new SqliteControllerStore(options.storeFile ?? projectControllerStorePath(options.cwd));
+        this.stateDir = path.dirname(this.store.filePath);
+        this.registry = options.registry ?? new HostProcessRegistry(this.stateDir);
+        this.childRunStore = new WorkflowRunStore(options.runsDir ?? process.env.PI_WORKFLOWS_RUNS_DIR ?? undefined);
+    }
+    log(message) {
+        this.options.onLog?.(message);
+    }
+    /** Take the advisory lock, reap orphans, and start claiming. */
+    async start() {
+        // The lock comes first: a second host must refuse before touching the
+        // children registry, or it would kill the live host's child processes
+        // as supposed orphans.
+        acquireHostLock(this.stateDir, this.runnerId, this.options.cwd);
+        const reaped = this.registry.reapOrphans();
+        if (reaped.length > 0) {
+            this.log(`reaped ${reaped.length} orphaned headless session(s): ${reaped.join(", ")}`);
+        }
+        const definitions = await loadDiscoveredControllers({ cwd: this.options.cwd });
+        if (definitions.length > 0) {
+            const scheduler = new WorkflowEngineScheduler({
+                store: this.childRunStore,
+                resolveWorkflow: async (name) => {
+                    const resolved = await resolveWorkflowRef(name, { cwd: this.options.cwd });
+                    const workflow = await loadWorkflowFile(resolved.path);
+                    return { workflow };
+                },
+                createEngine: () => {
+                    const executor = new RpcStepExecutor({
+                        cwd: this.options.cwd,
+                        registry: this.registry,
+                        ...(this.options.piArgs !== undefined ? { piArgs: this.options.piArgs } : {}),
+                        ...(this.options.env !== undefined ? { env: this.options.env } : {}),
+                    });
+                    const engine = new WorkflowEngine({ executor, store: this.childRunStore });
+                    this.schedulerExecutors.set(engine, executor);
+                    return engine;
+                },
+                disposeEngine: async (engine) => {
+                    const executor = this.schedulerExecutors.get(engine);
+                    if (executor !== undefined) {
+                        this.schedulerExecutors.delete(engine);
+                        await executor.close();
+                    }
+                },
+            });
+            this.manager = new ControllerManager({
+                store: this.store,
+                controllers: definitions,
+                workflowScheduler: scheduler,
+            });
+            this.manager.start();
+            this.log(`controller workers started for ${definitions.length} controller(s)`);
+        }
+        this.pollTimer = setInterval(() => {
+            this.claimOnce();
+        }, this.options.claimPollMs ?? CLAIM_POLL_MS);
+        this.pollTimer.unref?.();
+        this.claimOnce();
+        this.log(`host ${this.runnerId} watching ${this.options.cwd}`);
+    }
+    /** Drain: stop claiming, park in-flight runs, stop controllers, kill children. */
+    async stop() {
+        if (this.stopping) {
+            return;
+        }
+        this.stopping = true;
+        if (this.pollTimer !== null) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        const pending = [...this.activeRuns.values()];
+        for (const run of this.parkedEngines.splice(0)) {
+            run();
+        }
+        await Promise.allSettled(pending);
+        await this.manager?.stop().catch(() => undefined);
+        for (const executor of this.schedulerExecutors.values()) {
+            await executor.close().catch(() => undefined);
+        }
+        this.schedulerExecutors.clear();
+        this.registry.killAll();
+        releaseHostLock(this.stateDir, this.runnerId);
+        this.store.close();
+    }
+    parkedEngines = [];
+    claimOnce() {
+        if (this.stopping || this.activeRuns.size > 0) {
+            return;
+        }
+        let claimed;
+        try {
+            claimed = this.store.claimNextWorkflowRun({
+                runnerId: this.runnerId,
+                claimToken: randomUUID(),
+                leaseMs: RUN_CLAIM_LEASE_MS,
+                excludeRunIds: [...this.skippedRuns],
+            });
+        }
+        catch (error) {
+            // Store contention or corruption must not kill the host's loop.
+            this.log(`claim failed, retrying shortly: ${errorMessage(error)}`);
+            return;
+        }
+        if (claimed === undefined) {
+            return;
+        }
+        const task = this.runClaimed(claimed).finally(() => {
+            this.activeRuns.delete(claimed.runId);
+        });
+        this.activeRuns.set(claimed.runId, task);
+    }
+    async runClaimed(record) {
+        const claimToken = record.claimToken;
+        const runId = record.runId;
+        this.log(`resuming ${record.workflowRef} run ${runId}`);
+        let workflow;
+        let workflowHash;
+        try {
+            workflow = await loadWorkflowFile(record.workflowPath);
+            workflowHash = await hashWorkflowSource(record.workflowPath);
+        }
+        catch (error) {
+            await this.failUnresumable(record, claimToken, errorMessage(error));
+            return;
+        }
+        if (this.stopping) {
+            // The drain started during setup: park before anything executes.
+            try {
+                this.store.parkWorkflowRun({ runId, claimToken });
+            }
+            catch {
+                // Best-effort.
+            }
+            return;
+        }
+        const store = this.store;
+        const fence = () => {
+            if (!store.verifyWorkflowRunClaim({ runId, claimToken })) {
+                throw new ClaimLostError(runId);
+            }
+        };
+        const fencedStore = new WorkflowRunStore(this.childRunStore.outputRoot, {
+            fenceProvider: () => fence,
+        });
+        const executor = new RpcStepExecutor({
+            cwd: this.options.cwd,
+            registry: this.registry,
+            ...(this.options.piArgs !== undefined ? { piArgs: this.options.piArgs } : {}),
+            ...(this.options.env !== undefined ? { env: this.options.env } : {}),
+        });
+        const engine = new WorkflowEngine({ executor, store: fencedStore });
+        const parkEngine = () => engine.park();
+        this.parkedEngines.push(parkEngine);
+        const renewTimer = setInterval(() => {
+            try {
+                if (!store.renewWorkflowRunClaim({ runId, claimToken, leaseMs: RUN_CLAIM_LEASE_MS })) {
+                    engine.cancel();
+                }
+            }
+            catch {
+                // Transient store errors leave fencing to decide ownership.
+            }
+        }, RUN_CLAIM_RENEW_MS);
+        renewTimer.unref?.();
+        this.recordEvent(runId, record.workflowRef, "resumed", { runnerId: this.runnerId });
+        try {
+            const result = await engine.resumeRun(workflow, runId, { workflowHash });
+            clearInterval(renewTimer);
+            if (result.state.status === "running") {
+                // Parked again mid-drain: leave it claimable for the next runner.
+                this.store.parkWorkflowRun({ runId, claimToken });
+                this.recordEvent(runId, record.workflowRef, "parked", {});
+                this.log(`parked ${record.workflowRef} run ${runId}`);
+                return;
+            }
+            this.store.completeWorkflowRun({ runId, claimToken });
+            this.recordEvent(runId, record.workflowRef, result.state.status, {
+                ...(result.state.error !== undefined ? { error: result.state.error } : {}),
+                ...(result.state.waitingOn !== undefined ? { waitingOn: result.state.waitingOn } : {}),
+            });
+            this.log(`${record.workflowRef} run ${runId} ${result.state.status}`);
+        }
+        catch (error) {
+            clearInterval(renewTimer);
+            if (isClaimLostError(error)) {
+                this.log(`run ${runId} continues under another runner`);
+                return;
+            }
+            if (error instanceof WorkflowSourceChangedError) {
+                // Edited source is a refusal, not a failure: keep the run claimable
+                // for a later fix, and stop spinning on it for this host's lifetime.
+                try {
+                    this.store.parkWorkflowRun({ runId, claimToken });
+                }
+                catch {
+                    // Best-effort.
+                }
+                this.skippedRuns.add(runId);
+                this.recordEvent(runId, record.workflowRef, "parked", {
+                    reason: "workflow source changed",
+                });
+                this.log(`run ${runId} skipped: workflow source changed; revert or force-resume it, then restart the host`);
+                return;
+            }
+            await this.failUnresumable(record, claimToken, errorMessage(error));
+        }
+        finally {
+            const index = this.parkedEngines.indexOf(parkEngine);
+            if (index !== -1) {
+                this.parkedEngines.splice(index, 1);
+            }
+            await executor.close().catch(() => undefined);
+        }
+    }
+    async failUnresumable(record, claimToken, message) {
+        let actualStatus;
+        let heldClaim = false;
+        try {
+            // The interruption write obeys the same fencing rule as every other
+            // bundle write: without a live claim, the current owner decides.
+            heldClaim = this.store.verifyWorkflowRunClaim({ runId: record.runId, claimToken });
+            if (heldClaim) {
+                const bundle = await this.childRunStore.markRunInterrupted(record.runId, message);
+                actualStatus = bundle?.state.status;
+            }
+        }
+        catch {
+            // The bundle may be unreadable; the queue row still needs closure.
+        }
+        try {
+            this.store.completeWorkflowRun({ runId: record.runId, claimToken });
+        }
+        catch {
+            // Best-effort.
+        }
+        if (!heldClaim) {
+            // Another runner owns the run; its owner reports from here.
+            this.log(`run ${record.runId} continues under another runner`);
+            return;
+        }
+        // Report the bundle's real terminal state when the interruption was a
+        // no-op (the bundle was already waiting or completed), so the feed
+        // stays truthful for sessions syncing from it.
+        if (actualStatus !== undefined && actualStatus !== "failed") {
+            this.recordEvent(record.runId, record.workflowRef, actualStatus, {});
+        }
+        else {
+            this.recordEvent(record.runId, record.workflowRef, "failed", { error: message });
+        }
+        this.log(`run ${record.runId} cannot resume: ${message}`);
+    }
+    recordEvent(runId, workflowRef, type, payload) {
+        try {
+            this.store.recordRunEvent({ runId, workflowRef, type, payload, runnerId: this.runnerId });
+        }
+        catch {
+            // The event feed is best-effort.
+        }
+    }
+}
+function hostLockPath(stateDir) {
+    return path.join(stateDir, "host.lock");
+}
+/**
+ * The advisory lock guards host-versus-host only: the embedded runner in a
+ * Pi session does not take it. A second host refuses to start while the
+ * recorded PID is alive.
+ */
+function acquireHostLock(stateDir, runnerId, cwd) {
+    const lockPath = hostLockPath(stateDir);
+    const existing = readLock(lockPath);
+    if (existing !== null && existing.runnerId !== runnerId && isAlive(existing.pid)) {
+        throw new Error(`Another workflow host (pid ${existing.pid}, ${existing.runnerId}) is already running for ${cwd}`);
+    }
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(lockPath, `${JSON.stringify({ pid: process.pid, runnerId, startedAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600 });
+}
+function releaseHostLock(stateDir, runnerId) {
+    const lockPath = hostLockPath(stateDir);
+    const existing = readLock(lockPath);
+    if (existing?.runnerId !== runnerId) {
+        return;
+    }
+    try {
+        fs.rmSync(lockPath);
+    }
+    catch {
+        // Already gone.
+    }
+}
+function readLock(lockPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (typeof parsed.pid !== "number" || typeof parsed.runnerId !== "string") {
+            return null;
+        }
+        return { pid: parsed.pid, runnerId: parsed.runnerId };
+    }
+    catch {
+        return null;
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=runner.js.map