@davidorex/pi-workflows 0.2.0 → 0.3.0

package/src/checkpoint.ts

@@ -1,140 +0,0 @@
-/**
- * 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";
-import { WORKFLOWS_DIR } from "./workflows-dir.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 .workflows/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, WORKFLOWS_DIR, "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

@@ -1,143 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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");
-}

package/src/dag.test.ts

@@ -1,350 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert";
-import { extractDependencies, buildExecutionPlan, isSequential } from "./dag.ts";
-import type { StepSpec } from "./types.ts";
-import { makeSpec as makeSpecFull } from "./test-helpers.ts";
-
-/**
- * Helper: build a minimal WorkflowSpec from a steps object.
- */
-function makeSpec(steps: Record<string, StepSpec>) {
-  return makeSpecFull({ steps });
-}
-
-describe("extractDependencies", () => {
-  it("returns empty deps for steps with no expressions", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: { agent: "bar" },
-    });
-    const deps = extractDependencies(spec);
-    assert.strictEqual(deps.get("a")!.size, 0);
-    assert.strictEqual(deps.get("b")!.size, 0);
-  });
-
-  it("extracts deps from input expressions", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        agent: "bar",
-        input: {
-          context: "${{ steps.a.textOutput }}",
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.strictEqual(deps.get("a")!.size, 0);
-    assert.ok(deps.get("b")!.has("a"));
-  });
-
-  it("extracts deps from when condition", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        agent: "bar",
-        when: "${{ steps.a.output.shouldRun }}",
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.ok(deps.get("b")!.has("a"));
-  });
-
-  it("extracts deps from bare when condition (no ${{ }})", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        agent: "bar",
-        when: "steps.a.output.shouldRun",
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.ok(deps.get("b")!.has("a"));
-  });
-
-  it("extracts deps from gate check", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        gate: { check: "${{ steps.a.output.reproCommand }}" },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.ok(deps.get("b")!.has("a"));
-  });
-
-  it("extracts deps from transform mapping", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: { agent: "bar" },
-      c: {
-        transform: {
-          mapping: {
-            fromA: "${{ steps.a.textOutput }}",
-            fromB: "${{ steps.b.output.data }}",
-          },
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.ok(deps.get("c")!.has("a"));
-    assert.ok(deps.get("c")!.has("b"));
-  });
-
-  it("extracts multiple deps from a single expression string", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: { agent: "bar" },
-      c: {
-        agent: "baz",
-        input: {
-          combined: "${{ steps.a.textOutput }}\n\n${{ steps.b.textOutput }}",
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.ok(deps.get("c")!.has("a"));
-    assert.ok(deps.get("c")!.has("b"));
-  });
-
-  it("extracts deps from nested input objects", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        agent: "bar",
-        input: {
-          nested: {
-            deep: {
-              value: "${{ steps.a.output.x }}",
-            },
-          },
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.ok(deps.get("b")!.has("a"));
-  });
-
-  it("extracts deps from input arrays", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        agent: "bar",
-        input: {
-          items: ["${{ steps.a.output.x }}", "static"],
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.ok(deps.get("b")!.has("a"));
-  });
-
-  it("ignores input-only references (no step deps)", () => {
-    const spec = makeSpec({
-      a: {
-        agent: "foo",
-        input: {
-          path: "${{ input.path }}",
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.strictEqual(deps.get("a")!.size, 0);
-  });
-
-  it("ignores self-references", () => {
-    const spec = makeSpec({
-      a: {
-        agent: "foo",
-        input: {
-          self: "${{ steps.a.output }}",
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.strictEqual(deps.get("a")!.size, 0);
-  });
-
-  it("ignores references to non-existent steps", () => {
-    const spec = makeSpec({
-      a: {
-        agent: "foo",
-        input: {
-          bad: "${{ steps.nonexistent.output }}",
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    assert.strictEqual(deps.get("a")!.size, 0);
-  });
-
-  it("does not descend into loop sub-steps", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        loop: {
-          maxAttempts: 3,
-          steps: {
-            inner: {
-              agent: "bar",
-              input: { ctx: "${{ steps.a.textOutput }}" },
-            },
-          },
-        },
-      },
-    });
-    const deps = extractDependencies(spec);
-    // The loop step itself should depend on 'a' via its sub-step's expression,
-    // BUT per the design: we do NOT descend into loop sub-steps for top-level DAG.
-    // The loop step's own `input` or `when` would declare its real deps.
-    assert.strictEqual(deps.get("b")!.size, 0);
-  });
-});
-
-describe("buildExecutionPlan", () => {
-  it("fully sequential: linear chain", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: {
-        agent: "bar",
-        input: { ctx: "${{ steps.a.textOutput }}" },
-      },
-      c: {
-        agent: "baz",
-        input: { ctx: "${{ steps.b.output }}" },
-      },
-    });
-    const plan = buildExecutionPlan(spec);
-    assert.strictEqual(plan.length, 3);
-    assert.deepStrictEqual(plan[0].steps, ["a"]);
-    assert.deepStrictEqual(plan[1].steps, ["b"]);
-    assert.deepStrictEqual(plan[2].steps, ["c"]);
-    assert.ok(isSequential(plan));
-  });
-
-  it("fully parallel: no dependencies", () => {
-    const spec = makeSpec({
-      a: { agent: "foo", input: { x: "${{ input.path }}" } },
-      b: { agent: "bar", input: { x: "${{ input.path }}" } },
-      c: { agent: "baz", input: { x: "${{ input.path }}" } },
-    });
-    const plan = buildExecutionPlan(spec);
-    assert.strictEqual(plan.length, 1);
-    assert.strictEqual(plan[0].steps.length, 3);
-    assert.ok(plan[0].steps.includes("a"));
-    assert.ok(plan[0].steps.includes("b"));
-    assert.ok(plan[0].steps.includes("c"));
-    assert.ok(!isSequential(plan));
-  });
-
-  it("fan-out then merge: diamond pattern", () => {
-    const spec = makeSpec({
-      source: { agent: "foo" },
-      analyzerA: {
-        agent: "bar",
-        input: { ctx: "${{ steps.source.textOutput }}" },
-      },
-      analyzerB: {
-        agent: "baz",
-        input: { ctx: "${{ steps.source.textOutput }}" },
-      },
-      merge: {
-        transform: {
-          mapping: {
-            a: "${{ steps.analyzerA.output }}",
-            b: "${{ steps.analyzerB.output }}",
-          },
-        },
-      },
-    });
-    const plan = buildExecutionPlan(spec);
-    assert.strictEqual(plan.length, 3);
-    assert.deepStrictEqual(plan[0].steps, ["source"]);
-    assert.strictEqual(plan[1].steps.length, 2);
-    assert.ok(plan[1].steps.includes("analyzerA"));
-    assert.ok(plan[1].steps.includes("analyzerB"));
-    assert.deepStrictEqual(plan[2].steps, ["merge"]);
-  });
-
-  it("mixed: some parallel, some sequential", () => {
-    const spec = makeSpec({
-      a: { agent: "foo" },
-      b: { agent: "bar" },
-      c: {
-        agent: "baz",
-        input: { ctx: "${{ steps.a.textOutput }}" },
-      },
-      d: {
-        transform: {
-          mapping: {
-            b: "${{ steps.b.output }}",
-            c: "${{ steps.c.output }}",
-          },
-        },
-      },
-    });
-    const plan = buildExecutionPlan(spec);
-    assert.strictEqual(plan.length, 3);
-    // Layer 0: a, b (both independent)
-    assert.strictEqual(plan[0].steps.length, 2);
-    assert.ok(plan[0].steps.includes("a"));
-    assert.ok(plan[0].steps.includes("b"));
-    // Layer 1: c (depends on a)
-    assert.deepStrictEqual(plan[1].steps, ["c"]);
-    // Layer 2: d (depends on b and c)
-    assert.deepStrictEqual(plan[2].steps, ["d"]);
-  });
-
-  it("detects cycle", () => {
-    const spec = makeSpec({
-      a: {
-        agent: "foo",
-        input: { ctx: "${{ steps.b.output }}" },
-      },
-      b: {
-        agent: "bar",
-        input: { ctx: "${{ steps.a.output }}" },
-      },
-    });
-    assert.throws(
-      () => buildExecutionPlan(spec),
-      (err: Error) => err.message.includes("cycle"),
-    );
-  });
-
-  it("single step", () => {
-    const spec = makeSpec({
-      only: { agent: "foo" },
-    });
-    const plan = buildExecutionPlan(spec);
-    assert.strictEqual(plan.length, 1);
-    assert.deepStrictEqual(plan[0].steps, ["only"]);
-    assert.ok(isSequential(plan));
-  });
-
-  it("preserves YAML order within layers", () => {
-    // Steps with no deps should appear in their YAML declaration order
-    const spec = makeSpec({
-      z: { agent: "foo" },
-      a: { agent: "bar" },
-      m: { agent: "baz" },
-    });
-    const plan = buildExecutionPlan(spec);
-    assert.strictEqual(plan.length, 1);
-    // Should preserve insertion order: z, a, m
-    assert.deepStrictEqual(plan[0].steps, ["z", "a", "m"]);
-  });
-
-  it("step with when referencing another step", () => {
-    const spec = makeSpec({
-      check: { gate: { check: "echo ok" } },
-      conditional: {
-        agent: "foo",
-        when: "${{ steps.check.output.passed }}",
-      },
-    });
-    const plan = buildExecutionPlan(spec);
-    assert.strictEqual(plan.length, 2);
-    assert.deepStrictEqual(plan[0].steps, ["check"]);
-    assert.deepStrictEqual(plan[1].steps, ["conditional"]);
-  });
-});