@davidorex/pi-workflows 0.1.0

package/src/checkpoint.test.ts

@@ -0,0 +1,237 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { findIncompleteRun, validateResumeCompatibility, computeResumePoint, formatIncompleteRun } from "./checkpoint.ts";
+import { writeState } from "./state.ts";
+import type { ExecutionState } from "./types.ts";
+import { makeSpec } from "./test-helpers.ts";
+
+describe("findIncompleteRun", () => {
+  it("returns null when no runs directory exists", () => {
+    const result = findIncompleteRun("/nonexistent", "test-workflow");
+    assert.strictEqual(result, null);
+  });
+
+  it("returns null when all runs are completed", (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
+    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+    const runDir = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs", "test-20260314-120000-abcd");
+    fs.mkdirSync(runDir, { recursive: true });
+    writeState(runDir, { input: {}, steps: {}, status: "completed" });
+
+    const result = findIncompleteRun(tmpDir, "test");
+    assert.strictEqual(result, null);
+  });
+
+  it("finds a run with status 'running' (interrupted)", (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
+    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+    const runDir = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs", "test-20260314-120000-abcd");
+    fs.mkdirSync(runDir, { recursive: true });
+
+    const state: ExecutionState = {
+      input: { path: "/src" },
+      steps: {
+        explore: {
+          step: "explore", agent: "explorer", status: "completed",
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 1 },
+          durationMs: 1000, textOutput: "found stuff",
+        },
+      },
+      status: "running",
+    };
+    writeState(runDir, state);
+
+    const result = findIncompleteRun(tmpDir, "test");
+    assert.ok(result);
+    assert.strictEqual(result.runId, "test-20260314-120000-abcd");
+    assert.deepStrictEqual(result.completedSteps, ["explore"]);
+    assert.strictEqual(result.failedStep, undefined);
+  });
+
+  it("finds a run with status 'failed'", (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
+    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+    const runDir = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs", "test-20260314-120000-abcd");
+    fs.mkdirSync(runDir, { recursive: true });
+
+    const state: ExecutionState = {
+      input: {},
+      steps: {
+        step1: {
+          step: "step1", agent: "a", status: "completed",
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+          durationMs: 0,
+        },
+        step2: {
+          step: "step2", agent: "b", status: "failed",
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+          durationMs: 0, error: "timeout",
+        },
+      },
+      status: "failed",
+    };
+    writeState(runDir, state);
+
+    const result = findIncompleteRun(tmpDir, "test");
+    assert.ok(result);
+    assert.deepStrictEqual(result.completedSteps, ["step1"]);
+    assert.strictEqual(result.failedStep, "step2");
+  });
+
+  it("returns most recent incomplete run", (t) => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
+    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+    const runsBase = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs");
+
+    // Older run (completed)
+    const oldDir = path.join(runsBase, "test-20260314-100000-aaaa");
+    fs.mkdirSync(oldDir, { recursive: true });
+    writeState(oldDir, { input: {}, steps: {}, status: "completed" });
+
+    // Newer run (failed)
+    const newDir = path.join(runsBase, "test-20260314-120000-bbbb");
+    fs.mkdirSync(newDir, { recursive: true });
+    writeState(newDir, { input: {}, steps: {}, status: "failed" });
+
+    const result = findIncompleteRun(tmpDir, "test");
+    assert.ok(result);
+    assert.strictEqual(result.runId, "test-20260314-120000-bbbb");
+  });
+});
+
+describe("validateResumeCompatibility", () => {
+  it("returns null when compatible", () => {
+    const state: ExecutionState = {
+      input: {},
+      steps: {
+        step1: {
+          step: "step1", agent: "a", status: "completed",
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+          durationMs: 0,
+        },
+      },
+      status: "failed",
+      specVersion: "1",
+    };
+    const spec = makeSpec({ version: "1", steps: { step1: { agent: "a" }, step2: { agent: "b" } } });
+    assert.strictEqual(validateResumeCompatibility(state, spec), null);
+  });
+
+  it("rejects version mismatch", () => {
+    const state: ExecutionState = {
+      input: {},
+      steps: {},
+      status: "failed",
+      specVersion: "1",
+    };
+    const spec = makeSpec({ version: "2", steps: { step1: { agent: "a" } } });
+    const msg = validateResumeCompatibility(state, spec);
+    assert.ok(msg?.includes("version"));
+  });
+
+  it("rejects when completed step no longer exists in spec", () => {
+    const state: ExecutionState = {
+      input: {},
+      steps: {
+        removed_step: {
+          step: "removed_step", agent: "a", status: "completed",
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+          durationMs: 0,
+        },
+      },
+      status: "failed",
+    };
+    const spec = makeSpec({ steps: { different_step: { agent: "a" } } });
+    const msg = validateResumeCompatibility(state, spec);
+    assert.ok(msg?.includes("removed_step"));
+  });
+});
+
+describe("computeResumePoint", () => {
+  it("returns first layer with pending steps", () => {
+    const plan = [
+      { steps: ["a"] },
+      { steps: ["b", "c"] },
+      { steps: ["d"] },
+    ];
+    const completed = new Set(["a"]);
+    const result = computeResumePoint(plan, completed);
+    assert.ok(result);
+    assert.strictEqual(result.resumeLayerIndex, 1);
+    assert.deepStrictEqual(result.pendingStepsInLayer, ["b", "c"]);
+  });
+
+  it("returns only pending steps in a partially completed layer", () => {
+    const plan = [
+      { steps: ["a"] },
+      { steps: ["b", "c", "d"] },
+      { steps: ["e"] },
+    ];
+    const completed = new Set(["a", "b", "d"]);
+    const result = computeResumePoint(plan, completed);
+    assert.ok(result);
+    assert.strictEqual(result.resumeLayerIndex, 1);
+    assert.deepStrictEqual(result.pendingStepsInLayer, ["c"]);
+  });
+
+  it("returns null when all steps are completed", () => {
+    const plan = [
+      { steps: ["a"] },
+      { steps: ["b"] },
+    ];
+    const completed = new Set(["a", "b"]);
+    const result = computeResumePoint(plan, completed);
+    assert.strictEqual(result, null);
+  });
+
+  it("handles first layer being the resume point", () => {
+    const plan = [
+      { steps: ["a", "b"] },
+      { steps: ["c"] },
+    ];
+    const completed = new Set<string>();
+    const result = computeResumePoint(plan, completed);
+    assert.ok(result);
+    assert.strictEqual(result.resumeLayerIndex, 0);
+    assert.deepStrictEqual(result.pendingStepsInLayer, ["a", "b"]);
+  });
+});
+
+describe("formatIncompleteRun", () => {
+  it("formats an interrupted run", () => {
+    const run = {
+      runId: "test-20260314-120000-abcd",
+      runDir: "/tmp/runs/test-20260314-120000-abcd",
+      state: { input: {}, steps: {}, status: "running" as const },
+      completedSteps: ["explore", "analyze"],
+      updatedAt: "2026-03-14T12:00:00.000Z",
+    };
+    const spec = makeSpec({ steps: { explore: { agent: "a" }, analyze: { agent: "b" }, synthesize: { agent: "c" } } });
+    const msg = formatIncompleteRun(run, spec);
+    assert.ok(msg.includes("interrupted"));
+    assert.ok(msg.includes("2/3"));
+  });
+
+  it("formats a failed run with step name", () => {
+    const run = {
+      runId: "test-20260314-120000-abcd",
+      runDir: "/tmp/runs/test-20260314-120000-abcd",
+      state: { input: {}, steps: {}, status: "failed" as const },
+      completedSteps: ["explore"],
+      failedStep: "analyze",
+      updatedAt: "2026-03-14T12:00:00.000Z",
+    };
+    const spec = makeSpec({ steps: { explore: { agent: "a" }, analyze: { agent: "b" }, synthesize: { agent: "c" } } });
+    const msg = formatIncompleteRun(run, spec);
+    assert.ok(msg.includes("failed"));
+    assert.ok(msg.includes("analyze"));
+    assert.ok(msg.includes("1/3"));
+  });
+});

package/src/checkpoint.ts

@@ -0,0 +1,139 @@
+/**
+ * Checkpoint and resume logic for workflow runs.
+ *
+ * Finds incomplete runs, validates they match the current spec,
+ * and provides state needed to resume execution.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import type { ExecutionState, WorkflowSpec } from "./types.ts";
+import { readState } from "./state.ts";
+
+export interface IncompleteRun {
+  runId: string;
+  runDir: string;
+  state: ExecutionState;
+  completedSteps: string[];       // step names with status completed or skipped
+  failedStep?: string;            // name of the step that failed (if any)
+  updatedAt?: string;             // last update timestamp
+}
+
+/**
+ * Find the most recent incomplete run for a workflow.
+ *
+ * Scans .pi/workflow-runs/<name>/runs/ for state.json files
+ * with status "running" or "failed". Returns the most recent one
+ * (by directory name, which encodes timestamp).
+ *
+ * Returns null if no incomplete runs exist.
+ */
+export function findIncompleteRun(cwd: string, workflowName: string): IncompleteRun | null {
+  const runsDir = path.join(cwd, ".pi", "workflow-runs", workflowName, "runs");
+  if (!fs.existsSync(runsDir)) return null;
+
+  const entries = fs.readdirSync(runsDir)
+    .filter(e => {
+      const stat = fs.statSync(path.join(runsDir, e));
+      return stat.isDirectory();
+    })
+    .sort()          // lexicographic — timestamp-based IDs sort chronologically
+    .reverse();      // most recent first
+
+  for (const runId of entries) {
+    const runDir = path.join(runsDir, runId);
+    const state = readState(runDir);
+    if (!state) continue;
+
+    if (state.status === "running" || state.status === "failed" || state.status === "paused") {
+      const completedSteps = Object.entries(state.steps)
+        .filter(([, r]) => r.status === "completed" || r.status === "skipped")
+        .map(([name]) => name);
+
+      const failedStep = Object.entries(state.steps)
+        .find(([, r]) => r.status === "failed")
+        ?.[0];
+
+      return {
+        runId,
+        runDir,
+        state,
+        completedSteps,
+        failedStep,
+        updatedAt: state.updatedAt,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate that a saved state is compatible with the current workflow spec.
+ *
+ * Checks:
+ * 1. Spec version matches (if both specify one)
+ * 2. All completed steps still exist in the spec
+ *
+ * Returns null if compatible, or a string describing the incompatibility.
+ */
+export function validateResumeCompatibility(
+  state: ExecutionState,
+  spec: WorkflowSpec,
+): string | null {
+  // Check version match
+  if (state.specVersion && spec.version && state.specVersion !== spec.version) {
+    return `Spec version changed: run has '${state.specVersion}', current is '${spec.version}'`;
+  }
+
+  // Check all completed steps still exist in spec
+  const specStepNames = new Set(Object.keys(spec.steps));
+  for (const stepName of Object.keys(state.steps)) {
+    if (!specStepNames.has(stepName)) {
+      return `Step '${stepName}' was completed in the saved run but no longer exists in the workflow spec`;
+    }
+  }
+
+  return null; // compatible
+}
+
+/**
+ * Determine which steps need to run when resuming.
+ *
+ * Given the execution plan (layers of step names) and the set of
+ * already-completed steps, returns the layer index to resume from
+ * and which steps within that layer still need to run.
+ *
+ * For a partially-complete parallel layer (some steps done, some not),
+ * returns only the incomplete steps from that layer.
+ */
+export function computeResumePoint(
+  plan: Array<{ steps: string[] }>,
+  completedSteps: Set<string>,
+): { resumeLayerIndex: number; pendingStepsInLayer: string[] } | null {
+  for (let i = 0; i < plan.length; i++) {
+    const layer = plan[i];
+    const pending = layer.steps.filter(s => !completedSteps.has(s));
+
+    if (pending.length > 0) {
+      return { resumeLayerIndex: i, pendingStepsInLayer: pending };
+    }
+  }
+
+  // All steps completed — nothing to resume
+  return null;
+}
+
+/**
+ * Format a human-readable summary of an incomplete run for display.
+ */
+export function formatIncompleteRun(run: IncompleteRun, spec: WorkflowSpec): string {
+  const totalSteps = Object.keys(spec.steps).length;
+  const completed = run.completedSteps.length;
+  const status = run.state.status === "paused" ? "paused"
+    : run.state.status === "running" ? "interrupted"
+    : "failed";
+  const failedInfo = run.failedStep ? ` at step '${run.failedStep}'` : "";
+  const timeInfo = run.updatedAt ? ` (last updated: ${run.updatedAt})` : "";
+
+  return `Found ${status} run${failedInfo}: ${completed}/${totalSteps} steps completed${timeInfo}. Run ID: ${run.runId}`;
+}

package/src/completion.test.ts

@@ -0,0 +1,143 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { resolveCompletion } from "./completion.ts";
+import type { CompletionSpec, WorkflowResult, StepResult, StepUsage } from "./types.ts";
+
+const usage: StepUsage = { input: 1000, output: 500, cacheRead: 0, cacheWrite: 0, cost: 0.03, turns: 2 };
+
+const stepResult: StepResult = {
+  step: "summarize",
+  agent: "summarizer",
+  status: "completed",
+  output: { headline: "Found 3 issues" },
+  textOutput: "The codebase has 3 critical issues.",
+  usage,
+  durationMs: 45000,
+};
+
+const result: WorkflowResult = {
+  workflow: "explore-summarize",
+  runId: "explore-summarize-20260313-120000-abcd",
+  status: "completed",
+  steps: { summarize: stepResult },
+  output: { headline: "Found 3 issues" },
+  totalUsage: { input: 2000, output: 1000, cacheRead: 0, cacheWrite: 0, cost: 0.05, turns: 4 },
+  totalDurationMs: 92000,
+  runDir: "/tmp/runs/explore-summarize-20260313-120000-abcd",
+};
+
+const input = { path: "/src", question: "What are the main components?" };
+
+describe("resolveCompletion", () => {
+  describe("template form", () => {
+    it("resolves expressions in template", () => {
+      const spec: CompletionSpec = {
+        template: "## Results\n\n${{ steps.summarize.textOutput }}\n\nDone in ${{ totalDurationMs | duration }}.",
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.ok(content.includes("## Results"));
+      assert.ok(content.includes("The codebase has 3 critical issues."));
+      assert.ok(content.includes("Done in 1m32s."));
+    });
+
+    it("resolves input and workflow metadata in template", () => {
+      const spec: CompletionSpec = {
+        template: "Explored ${{ input.path }} for workflow '${{ workflow }}'. Status: ${{ status }}.",
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.strictEqual(content, "Explored /src for workflow 'explore-summarize'. Status: completed.");
+    });
+
+    it("applies currency filter in template", () => {
+      const spec: CompletionSpec = {
+        template: "Cost: ${{ totalUsage.cost | currency }}",
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.strictEqual(content, "Cost: $0.05");
+    });
+
+    it("includes runDir in template", () => {
+      const spec: CompletionSpec = {
+        template: "Logs at: ${{ runDir }}/sessions/",
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.strictEqual(content, "Logs at: /tmp/runs/explore-summarize-20260313-120000-abcd/sessions/");
+    });
+
+    it("renders undefined as empty in template", () => {
+      const spec: CompletionSpec = {
+        template: "Answer: ${{ input.nonexistent }}",
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.strictEqual(content, "Answer: ");
+    });
+  });
+
+  describe("message form", () => {
+    it("resolves message with no include", () => {
+      const spec: CompletionSpec = {
+        message: "Present the findings to the user. The workflow '${{ workflow }}' is done.",
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.ok(content.includes("Present the findings to the user."));
+      assert.ok(content.includes("'explore-summarize' is done."));
+    });
+
+    it("resolves message with include paths", () => {
+      const spec: CompletionSpec = {
+        message: "Show the user these results.",
+        include: ["steps.summarize.textOutput", "totalUsage"],
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.ok(content.includes("Show the user these results."));
+      assert.ok(content.includes("steps.summarize.textOutput"));
+      assert.ok(content.includes("The codebase has 3 critical issues."));
+      assert.ok(content.includes("totalUsage"));
+      assert.ok(content.includes('"cost"'));
+    });
+
+    it("formats included objects as JSON blocks", () => {
+      const spec: CompletionSpec = {
+        message: "Review:",
+        include: ["steps.summarize.output"],
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.ok(content.includes("```json"));
+      assert.ok(content.includes('"headline"'));
+    });
+
+    it("formats included primitives as plain text", () => {
+      const spec: CompletionSpec = {
+        message: "Data:",
+        include: ["steps.summarize.textOutput"],
+      };
+      const content = resolveCompletion(spec, result, input);
+      assert.ok(content.includes("The codebase has 3 critical issues."));
+      // Primitive values should NOT be in JSON blocks
+      assert.ok(!content.includes("```json\nThe codebase"));
+    });
+  });
+
+  describe("error handling", () => {
+    it("throws on invalid expression in template", () => {
+      const spec: CompletionSpec = {
+        template: "Bad: ${{ steps.nonexistent.output }}",
+      };
+      assert.throws(
+        () => resolveCompletion(spec, result, input),
+        (err: unknown) => err instanceof Error && err.message.includes("nonexistent"),
+      );
+    });
+
+    it("throws on invalid include path", () => {
+      const spec: CompletionSpec = {
+        message: "ok",
+        include: ["steps.nonexistent.output"],
+      };
+      assert.throws(
+        () => resolveCompletion(spec, result, input),
+        (err: unknown) => err instanceof Error && err.message.includes("nonexistent"),
+      );
+    });
+  });
+});

package/src/completion.ts

@@ -0,0 +1,68 @@
+import type { CompletionSpec, CompletionScope, WorkflowResult } from "./types.ts";
+import { resolveExpression, resolveExpressions } from "./expression.ts";
+
+/**
+ * Resolve a completion spec into the final message string injected into
+ * the main LLM conversation after workflow execution.
+ *
+ * Two forms:
+ * - Template: the template string is resolved with ${{ }} expressions
+ *   and returned as the full content.
+ * - Message + include: the message is resolved, then each include path
+ *   is resolved and appended as structured data.
+ *
+ * @param spec - the CompletionSpec from the workflow YAML
+ * @param result - the completed WorkflowResult
+ * @param executionInput - the original workflow input
+ * @returns the resolved message string
+ */
+export function resolveCompletion(
+  spec: CompletionSpec,
+  result: WorkflowResult,
+  executionInput: unknown,
+): string {
+  const scope: CompletionScope = {
+    input: executionInput,
+    steps: result.steps,
+    totalUsage: result.totalUsage,
+    totalDurationMs: result.totalDurationMs,
+    runDir: result.runDir,
+    runId: result.runId,
+    workflow: result.workflow,
+    status: result.status,
+    output: result.output,
+  };
+
+  if (spec.template) {
+    const resolved = resolveExpressions(spec.template, scope);
+    return String(resolved ?? "");
+  }
+
+  // Message form
+  const parts: string[] = [];
+
+  if (spec.message) {
+    const resolvedMessage = resolveExpressions(spec.message, scope);
+    parts.push(String(resolvedMessage ?? ""));
+  }
+
+  if (spec.include && spec.include.length > 0) {
+    const included: Record<string, unknown> = {};
+    for (const path of spec.include) {
+      const value = resolveExpression(path, scope);
+      included[path] = value;
+    }
+
+    parts.push("");
+    parts.push("---");
+    for (const [path, value] of Object.entries(included)) {
+      if (value !== null && typeof value === "object") {
+        parts.push(`\n### ${path}\n\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``);
+      } else {
+        parts.push(`\n### ${path}\n${String(value ?? "")}`);
+      }
+    }
+  }
+
+  return parts.join("\n");
+}