@quintinshaw/pi-dynamic-workflows 1.0.0

package/dist/run-persistence.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Workflow run state persistence for pause/resume support.
+ */
+export type RunStatus = "pending" | "running" | "paused" | "completed" | "failed" | "aborted";
+export interface PersistedAgentState {
+    id: number;
+    label: string;
+    phase?: string;
+    prompt: string;
+    status: "queued" | "running" | "done" | "error" | "skipped";
+    result?: unknown;
+    error?: string;
+    startedAt?: string;
+    endedAt?: string;
+}
+export interface PersistedRunState {
+    runId: string;
+    workflowName: string;
+    script: string;
+    args?: unknown;
+    status: RunStatus;
+    phases: string[];
+    currentPhase?: string;
+    agents: PersistedAgentState[];
+    logs: string[];
+    result?: unknown;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+}
+export interface RunPersistence {
+    /** Save current run state. */
+    save(state: PersistedRunState): void;
+    /** Load a persisted run by ID. */
+    load(runId: string): PersistedRunState | null;
+    /** List all persisted runs. */
+    list(): PersistedRunState[];
+    /** Delete a persisted run. */
+    delete(runId: string): boolean;
+    /** Get runs directory path. */
+    getRunsDir(): string;
+}
+export declare function createRunPersistence(cwd: string): RunPersistence;
+/**
+ * Generate a unique run ID.
+ */
+export declare function generateRunId(): string;

package/dist/run-persistence.js

@@ -0,0 +1,78 @@
+/**
+ * Workflow run state persistence for pause/resume support.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { WORKFLOW_RUNS_DIR } from "./config.js";
+export function createRunPersistence(cwd) {
+    const runsDir = join(cwd, WORKFLOW_RUNS_DIR);
+    const ensureDir = () => {
+        if (!existsSync(runsDir)) {
+            mkdirSync(runsDir, { recursive: true });
+        }
+    };
+    const runPath = (runId) => join(runsDir, `${runId}.json`);
+    return {
+        save(state) {
+            ensureDir();
+            state.updatedAt = new Date().toISOString();
+            writeFileSync(runPath(state.runId), JSON.stringify(state, null, 2));
+        },
+        load(runId) {
+            try {
+                const path = runPath(runId);
+                if (!existsSync(path))
+                    return null;
+                return JSON.parse(readFileSync(path, "utf-8"));
+            }
+            catch {
+                return null;
+            }
+        },
+        list() {
+            ensureDir();
+            try {
+                const files = readdirSync(runsDir).filter((f) => f.endsWith(".json"));
+                const runs = [];
+                for (const file of files) {
+                    try {
+                        const state = JSON.parse(readFileSync(join(runsDir, file), "utf-8"));
+                        runs.push(state);
+                    }
+                    catch {
+                        // Skip corrupted files
+                    }
+                }
+                return runs.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+            }
+            catch {
+                return [];
+            }
+        },
+        delete(runId) {
+            try {
+                const path = runPath(runId);
+                if (existsSync(path)) {
+                    const { unlinkSync } = require("node:fs");
+                    unlinkSync(path);
+                    return true;
+                }
+                return false;
+            }
+            catch {
+                return false;
+            }
+        },
+        getRunsDir() {
+            return runsDir;
+        },
+    };
+}
+/**
+ * Generate a unique run ID.
+ */
+export function generateRunId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 8);
+    return `${timestamp}-${random}`;
+}

package/dist/structured-output.d.ts

@@ -0,0 +1,19 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+export interface StructuredOutputCapture<T = unknown> {
+    value: T | undefined;
+    called: boolean;
+}
+export interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {
+    schema: TSchemaDef;
+    capture: StructuredOutputCapture<Static<TSchemaDef>>;
+    name?: string;
+}
+/**
+ * Create a terminating tool that captures validated params as the subagent result.
+ *
+ * Pi validates `params` against `schema` before execute() is called. Returning
+ * `terminate: true` lets the subagent finish on this tool call without paying for
+ * an extra assistant follow-up turn.
+ */
+export declare function createStructuredOutputTool<TSchemaDef extends TSchema>({ schema, capture, name, }: StructuredOutputToolOptions<TSchemaDef>): ToolDefinition<TSchemaDef, Static<TSchemaDef>>;

package/dist/structured-output.js

@@ -0,0 +1,30 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+/**
+ * Create a terminating tool that captures validated params as the subagent result.
+ *
+ * Pi validates `params` against `schema` before execute() is called. Returning
+ * `terminate: true` lets the subagent finish on this tool call without paying for
+ * an extra assistant follow-up turn.
+ */
+export function createStructuredOutputTool({ schema, capture, name = "structured_output", }) {
+    return defineTool({
+        name,
+        label: "Structured Output",
+        description: "Return the final machine-readable result for this subagent task.",
+        promptSnippet: "Return final machine-readable output",
+        promptGuidelines: [
+            `${name} is the final answer channel for this task; call ${name} exactly once when done.`,
+            `Do not write a prose final answer after calling ${name}.`,
+        ],
+        parameters: schema,
+        async execute(_toolCallId, params) {
+            capture.value = params;
+            capture.called = true;
+            return {
+                content: [{ type: "text", text: "Structured output received." }],
+                details: params,
+                terminate: true,
+            };
+        },
+    });
+}

package/dist/workflow-manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Workflow manager for background execution, pause/resume, and run management.
+ */
+import { EventEmitter } from "node:events";
+import type { WorkflowSnapshot } from "./display.js";
+import { WorkflowError } from "./errors.js";
+import { type PersistedRunState, type RunPersistence, type RunStatus } from "./run-persistence.js";
+import { type WorkflowRunResult } from "./workflow.js";
+export interface ManagedRun {
+    runId: string;
+    status: RunStatus;
+    snapshot: WorkflowSnapshot;
+    result?: WorkflowRunResult;
+    error?: WorkflowError;
+    controller: AbortController;
+    startedAt: Date;
+}
+export interface WorkflowManagerOptions {
+    cwd?: string;
+    concurrency?: number;
+}
+export declare class WorkflowManager extends EventEmitter {
+    private runs;
+    private persistence;
+    private cwd;
+    private concurrency;
+    constructor(options?: WorkflowManagerOptions);
+    /**
+     * Start a workflow in the background.
+     * Returns immediately with a run ID; the workflow executes asynchronously.
+     */
+    startInBackground(script: string, args?: unknown): {
+        runId: string;
+        promise: Promise<WorkflowRunResult>;
+    };
+    /**
+     * Execute a workflow synchronously (blocking).
+     */
+    runSync(script: string, args?: unknown): Promise<WorkflowRunResult>;
+    private executeRun;
+    private persistRun;
+    /**
+     * Pause a running workflow.
+     */
+    pause(runId: string): boolean;
+    /**
+     * Resume a paused workflow.
+     */
+    resume(runId: string): Promise<boolean>;
+    /**
+     * Stop a running workflow.
+     */
+    stop(runId: string): boolean;
+    /**
+     * Get status of a specific run.
+     */
+    getRun(runId: string): ManagedRun | undefined;
+    /**
+     * List all runs (active + persisted).
+     */
+    listRuns(): PersistedRunState[];
+    /**
+     * Get snapshot of a run.
+     */
+    getSnapshot(runId: string): WorkflowSnapshot | null;
+    /**
+     * Delete a persisted run.
+     */
+    deleteRun(runId: string): boolean;
+    /**
+     * Get the persistence layer (for saving workflows).
+     */
+    getPersistence(): RunPersistence;
+}

package/dist/workflow-manager.js

@@ -0,0 +1,241 @@
+/**
+ * Workflow manager for background execution, pause/resume, and run management.
+ */
+import { EventEmitter } from "node:events";
+import { WorkflowError, WorkflowErrorCode } from "./errors.js";
+import { createRunPersistence, generateRunId, } from "./run-persistence.js";
+import { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export class WorkflowManager extends EventEmitter {
+    runs = new Map();
+    persistence;
+    cwd;
+    concurrency;
+    constructor(options = {}) {
+        super();
+        this.cwd = options.cwd ?? process.cwd();
+        this.concurrency = options.concurrency ?? 8;
+        this.persistence = createRunPersistence(this.cwd);
+    }
+    /**
+     * Start a workflow in the background.
+     * Returns immediately with a run ID; the workflow executes asynchronously.
+     */
+    startInBackground(script, args) {
+        const runId = generateRunId();
+        const controller = new AbortController();
+        const parsed = parseWorkflowScript(script);
+        const managed = {
+            runId,
+            status: "running",
+            snapshot: {
+                name: parsed.meta.name,
+                description: parsed.meta.description,
+                phases: parsed.meta.phases?.map((p) => p.title) ?? [],
+                logs: [],
+                agents: [],
+                agentCount: 0,
+                runningCount: 0,
+                doneCount: 0,
+                errorCount: 0,
+            },
+            controller,
+            startedAt: new Date(),
+        };
+        this.runs.set(runId, managed);
+        // Persist initial state
+        this.persistence.save({
+            runId,
+            workflowName: parsed.meta.name,
+            script,
+            args,
+            status: "running",
+            phases: managed.snapshot.phases,
+            agents: [],
+            logs: [],
+            startedAt: managed.startedAt.toISOString(),
+            updatedAt: managed.startedAt.toISOString(),
+        });
+        // Run workflow asynchronously
+        const promise = this.executeRun(managed, script, args);
+        return { runId, promise };
+    }
+    /**
+     * Execute a workflow synchronously (blocking).
+     */
+    async runSync(script, args) {
+        const runId = generateRunId();
+        const controller = new AbortController();
+        const parsed = parseWorkflowScript(script);
+        const managed = {
+            runId,
+            status: "running",
+            snapshot: {
+                name: parsed.meta.name,
+                description: parsed.meta.description,
+                phases: parsed.meta.phases?.map((p) => p.title) ?? [],
+                logs: [],
+                agents: [],
+                agentCount: 0,
+                runningCount: 0,
+                doneCount: 0,
+                errorCount: 0,
+            },
+            controller,
+            startedAt: new Date(),
+        };
+        this.runs.set(runId, managed);
+        return this.executeRun(managed, script, args);
+    }
+    async executeRun(managed, script, args) {
+        try {
+            const result = await runWorkflow(script, {
+                cwd: this.cwd,
+                args,
+                signal: managed.controller.signal,
+                concurrency: this.concurrency,
+                onLog: (message) => {
+                    managed.snapshot.logs.push(message);
+                    this.emit("log", { runId: managed.runId, message });
+                },
+                onPhase: (title) => {
+                    managed.snapshot.currentPhase = title;
+                    if (!managed.snapshot.phases.includes(title)) {
+                        managed.snapshot.phases.push(title);
+                    }
+                    this.emit("phase", { runId: managed.runId, title });
+                },
+                onAgentStart: (event) => {
+                    managed.snapshot.agents.push({
+                        id: managed.snapshot.agents.length + 1,
+                        label: event.label,
+                        phase: event.phase,
+                        prompt: event.prompt,
+                        status: "running",
+                    });
+                    this.emit("agentStart", { runId: managed.runId, ...event });
+                },
+                onAgentEnd: (event) => {
+                    const agent = [...managed.snapshot.agents]
+                        .reverse()
+                        .find((a) => a.label === event.label && a.status === "running");
+                    if (agent) {
+                        agent.status = event.result === null ? "error" : "done";
+                    }
+                    this.emit("agentEnd", { runId: managed.runId, ...event });
+                },
+            });
+            managed.status = "completed";
+            managed.result = result;
+            this.emit("complete", { runId: managed.runId, result });
+            // Persist final state
+            this.persistRun(managed);
+            return result;
+        }
+        catch (error) {
+            const workflowError = error instanceof WorkflowError
+                ? error
+                : new WorkflowError(error instanceof Error ? error.message : String(error), WorkflowErrorCode.WORKFLOW_ABORTED, { recoverable: true });
+            if (managed.controller.signal.aborted) {
+                managed.status = "aborted";
+            }
+            else {
+                managed.status = "failed";
+            }
+            managed.error = workflowError;
+            this.emit("error", { runId: managed.runId, error: workflowError });
+            // Persist final state
+            this.persistRun(managed);
+            throw workflowError;
+        }
+    }
+    persistRun(managed) {
+        this.persistence.save({
+            runId: managed.runId,
+            workflowName: managed.snapshot.name,
+            script: "", // Don't persist script for security
+            status: managed.status,
+            phases: managed.snapshot.phases,
+            currentPhase: managed.snapshot.currentPhase,
+            agents: managed.snapshot.agents.map((a) => ({
+                ...a,
+                startedAt: managed.startedAt.toISOString(),
+                endedAt: new Date().toISOString(),
+            })),
+            logs: managed.snapshot.logs,
+            result: managed.result?.result,
+            startedAt: managed.startedAt.toISOString(),
+            updatedAt: new Date().toISOString(),
+            completedAt: managed.status === "completed" ? new Date().toISOString() : undefined,
+            durationMs: managed.result?.durationMs,
+        });
+    }
+    /**
+     * Pause a running workflow.
+     */
+    pause(runId) {
+        const managed = this.runs.get(runId);
+        if (managed?.status !== "running")
+            return false;
+        managed.controller.abort();
+        managed.status = "paused";
+        this.emit("paused", { runId });
+        this.persistRun(managed);
+        return true;
+    }
+    /**
+     * Resume a paused workflow.
+     */
+    async resume(runId) {
+        const persisted = this.persistence.load(runId);
+        if (persisted?.status !== "paused")
+            return false;
+        // For now, resume creates a fresh run with completed agents' results cached
+        // Full resume would require re-executing the script with cached results
+        this.emit("resumed", { runId });
+        return true;
+    }
+    /**
+     * Stop a running workflow.
+     */
+    stop(runId) {
+        const managed = this.runs.get(runId);
+        if (!managed || (managed.status !== "running" && managed.status !== "paused"))
+            return false;
+        managed.controller.abort();
+        managed.status = "aborted";
+        this.emit("stopped", { runId });
+        this.persistRun(managed);
+        return true;
+    }
+    /**
+     * Get status of a specific run.
+     */
+    getRun(runId) {
+        return this.runs.get(runId);
+    }
+    /**
+     * List all runs (active + persisted).
+     */
+    listRuns() {
+        return this.persistence.list();
+    }
+    /**
+     * Get snapshot of a run.
+     */
+    getSnapshot(runId) {
+        return this.runs.get(runId)?.snapshot ?? null;
+    }
+    /**
+     * Delete a persisted run.
+     */
+    deleteRun(runId) {
+        this.runs.delete(runId);
+        return this.persistence.delete(runId);
+    }
+    /**
+     * Get the persistence layer (for saving workflows).
+     */
+    getPersistence() {
+        return this.persistence;
+    }
+}

package/dist/workflow-saved.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Save and load reusable workflow commands.
+ */
+export interface SavedWorkflow {
+    /** Command name (filename without extension). */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** The workflow script. */
+    script: string;
+    /** Optional parameter schema for parameterized workflows. */
+    parameters?: Record<string, {
+        type: string;
+        description?: string;
+        required?: boolean;
+        default?: unknown;
+    }>;
+    /** Where this workflow is saved. */
+    location: "project" | "user";
+    /** Full file path. */
+    path: string;
+    /** When it was saved. */
+    savedAt: string;
+}
+export interface WorkflowStorage {
+    /** Save a workflow. */
+    save(workflow: Omit<SavedWorkflow, "path" | "savedAt">, location?: "project" | "user"): SavedWorkflow;
+    /** Load a workflow by name. */
+    load(name: string): SavedWorkflow | null;
+    /** List all saved workflows. */
+    list(): SavedWorkflow[];
+    /** Delete a saved workflow. */
+    delete(name: string, location?: "project" | "user"): boolean;
+}
+export declare function createWorkflowStorage(cwd: string): WorkflowStorage;

package/dist/workflow-saved.js

@@ -0,0 +1,91 @@
+/**
+ * Save and load reusable workflow commands.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { USER_WORKFLOW_SAVED_DIR, WORKFLOW_SAVED_DIR } from "./config.js";
+export function createWorkflowStorage(cwd) {
+    const projectDir = join(cwd, WORKFLOW_SAVED_DIR);
+    const userDir = USER_WORKFLOW_SAVED_DIR.replace("~", process.env.HOME ?? "");
+    const ensureDir = (dir) => {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    };
+    const workflowPath = (name, location) => {
+        const dir = location === "project" ? projectDir : userDir;
+        return join(dir, `${name}.json`);
+    };
+    const loadFromFile = (path, location) => {
+        try {
+            if (!existsSync(path))
+                return null;
+            const data = JSON.parse(readFileSync(path, "utf-8"));
+            return {
+                ...data,
+                location,
+                path,
+            };
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        save(workflow, location = "project") {
+            const dir = location === "project" ? projectDir : userDir;
+            ensureDir(dir);
+            const path = workflowPath(workflow.name, location);
+            const saved = {
+                ...workflow,
+                location,
+                path,
+                savedAt: new Date().toISOString(),
+            };
+            writeFileSync(path, JSON.stringify(saved, null, 2));
+            return saved;
+        },
+        load(name) {
+            // Project takes precedence over user
+            const projectPath = workflowPath(name, "project");
+            const project = loadFromFile(projectPath, "project");
+            if (project)
+                return project;
+            const userPath = workflowPath(name, "user");
+            return loadFromFile(userPath, "user");
+        },
+        list() {
+            const workflows = [];
+            // Load project workflows
+            if (existsSync(projectDir)) {
+                for (const file of readdirSync(projectDir).filter((f) => f.endsWith(".json"))) {
+                    const wf = loadFromFile(join(projectDir, file), "project");
+                    if (wf)
+                        workflows.push(wf);
+                }
+            }
+            // Load user workflows
+            if (existsSync(userDir)) {
+                for (const file of readdirSync(userDir).filter((f) => f.endsWith(".json"))) {
+                    const wf = loadFromFile(join(userDir, file), "user");
+                    if (wf)
+                        workflows.push(wf);
+                }
+            }
+            return workflows.sort((a, b) => a.name.localeCompare(b.name));
+        },
+        delete(name, location) {
+            const locations = location ? [location] : ["project", "user"];
+            let deleted = false;
+            for (const loc of locations) {
+                const path = workflowPath(name, loc);
+                if (existsSync(path)) {
+                    const { unlinkSync } = require("node:fs");
+                    unlinkSync(path);
+                    deleted = true;
+                }
+            }
+            return deleted;
+        },
+    };
+}

package/dist/workflow-tool.d.ts

@@ -0,0 +1,22 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+declare const workflowToolSchema: Type.TObject<{
+    script: Type.TString;
+    args: Type.TOptional<Type.TAny>;
+    background: Type.TOptional<Type.TBoolean>;
+    maxAgents: Type.TOptional<Type.TNumber>;
+    agentTimeoutMs: Type.TOptional<Type.TNumber>;
+}>;
+export type WorkflowToolInput = {
+    script: string;
+    args?: unknown;
+    background?: boolean;
+    maxAgents?: number;
+    agentTimeoutMs?: number;
+};
+export interface WorkflowToolOptions {
+    cwd?: string;
+    concurrency?: number;
+}
+export declare function createWorkflowTool(options?: WorkflowToolOptions): ToolDefinition<typeof workflowToolSchema, any>;
+export {};