@quintinshaw/pi-dynamic-workflows 1.0.0

package/src/structured-output.ts

@@ -0,0 +1,47 @@
+import { defineTool, 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 function createStructuredOutputTool<TSchemaDef extends TSchema>({
+  schema,
+  capture,
+  name = "structured_output",
+}: StructuredOutputToolOptions<TSchemaDef>): ToolDefinition<TSchemaDef, Static<TSchemaDef>> {
+  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/src/workflow-manager.ts

@@ -0,0 +1,294 @@
+/**
+ * Workflow manager for background execution, pause/resume, and run management.
+ */
+
+import { EventEmitter } from "node:events";
+import type { WorkflowSnapshot } from "./display.js";
+import { WorkflowError, WorkflowErrorCode } from "./errors.js";
+import {
+  createRunPersistence,
+  generateRunId,
+  type PersistedRunState,
+  type RunPersistence,
+  type RunStatus,
+} from "./run-persistence.js";
+import { parseWorkflowScript, runWorkflow, 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 class WorkflowManager extends EventEmitter {
+  private runs = new Map<string, ManagedRun>();
+  private persistence: RunPersistence;
+  private cwd: string;
+  private concurrency: number;
+
+  constructor(options: WorkflowManagerOptions = {}) {
+    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: string, args?: unknown): { runId: string; promise: Promise<WorkflowRunResult> } {
+    const runId = generateRunId();
+    const controller = new AbortController();
+    const parsed = parseWorkflowScript(script);
+
+    const managed: ManagedRun = {
+      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: string, args?: unknown): Promise<WorkflowRunResult> {
+    const runId = generateRunId();
+    const controller = new AbortController();
+    const parsed = parseWorkflowScript(script);
+
+    const managed: ManagedRun = {
+      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);
+  }
+
+  private async executeRun(managed: ManagedRun, script: string, args?: unknown): Promise<WorkflowRunResult> {
+    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;
+    }
+  }
+
+  private persistRun(managed: ManagedRun) {
+    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: string): boolean {
+    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: string): Promise<boolean> {
+    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: string): boolean {
+    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: string): ManagedRun | undefined {
+    return this.runs.get(runId);
+  }
+
+  /**
+   * List all runs (active + persisted).
+   */
+  listRuns(): PersistedRunState[] {
+    return this.persistence.list();
+  }
+
+  /**
+   * Get snapshot of a run.
+   */
+  getSnapshot(runId: string): WorkflowSnapshot | null {
+    return this.runs.get(runId)?.snapshot ?? null;
+  }
+
+  /**
+   * Delete a persisted run.
+   */
+  deleteRun(runId: string): boolean {
+    this.runs.delete(runId);
+    return this.persistence.delete(runId);
+  }
+
+  /**
+   * Get the persistence layer (for saving workflows).
+   */
+  getPersistence(): RunPersistence {
+    return this.persistence;
+  }
+}

package/src/workflow-saved.ts

@@ -0,0 +1,131 @@
+/**
+ * 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 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 function createWorkflowStorage(cwd: string): WorkflowStorage {
+  const projectDir = join(cwd, WORKFLOW_SAVED_DIR);
+  const userDir = USER_WORKFLOW_SAVED_DIR.replace("~", process.env.HOME ?? "");
+
+  const ensureDir = (dir: string) => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  };
+
+  const workflowPath = (name: string, location: "project" | "user") => {
+    const dir = location === "project" ? projectDir : userDir;
+    return join(dir, `${name}.json`);
+  };
+
+  const loadFromFile = (path: string, location: "project" | "user"): SavedWorkflow | null => {
+    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: SavedWorkflow = {
+        ...workflow,
+        location,
+        path,
+        savedAt: new Date().toISOString(),
+      };
+
+      writeFileSync(path, JSON.stringify(saved, null, 2));
+      return saved;
+    },
+
+    load(name: string): SavedWorkflow | null {
+      // 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(): SavedWorkflow[] {
+      const workflows: SavedWorkflow[] = [];
+
+      // 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: string, location?: "project" | "user"): boolean {
+      const locations = location ? [location] : (["project", "user"] as const);
+      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;
+    },
+  };
+}