@davidorex/pi-workflows 0.2.0 → 0.3.0

package/src/step-agent.test.ts

@@ -1,327 +0,0 @@
-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 nunjucks from "nunjucks";
-import { executeAgentStep } from "./step-agent.ts";
-import type { AgentStepOptions } from "./step-agent.ts";
-import { zeroUsage } from "./step-shared.ts";
-import { dispatch } from "./dispatch.ts";
-import type { StepSpec, StepResult, ExecutionState, AgentSpec } from "./types.ts";
-import { mockCtx } from "./test-helpers.ts";
-
-/**
- * Mock dispatch factory: returns a controlled StepResult.
- * Optionally captures call arguments for assertion.
- */
-function mockDispatch(
-  result: Partial<StepResult> = {},
-  capture?: { calls: any[] },
-): typeof dispatch {
-  return async (step, agent, prompt, opts) => {
-    if (capture) capture.calls.push({ step, agent, prompt, opts });
-    return {
-      step: opts.stepName,
-      agent: step.agent ?? "mock",
-      status: "completed",
-      usage: zeroUsage(),
-      durationMs: 100,
-      textOutput: "mock output",
-      ...result,
-    } as StepResult;
-  };
-}
-
-function makeTmpRunDir(t: any): string {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-agent-"));
-  fs.mkdirSync(path.join(tmpDir, "outputs"), { recursive: true });
-  fs.mkdirSync(path.join(tmpDir, "sessions"), { recursive: true });
-  t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-  return tmpDir;
-}
-
-function makeOptions(tmpDir: string, overrides?: Partial<AgentStepOptions>): AgentStepOptions {
-  return {
-    ctx: mockCtx(tmpDir),
-    loadAgent: () => ({ name: "default" }),
-    runDir: tmpDir,
-    specFilePath: path.join(tmpDir, "spec.yaml"),
-    widgetState: {
-      spec: { name: "test", description: "", steps: {}, source: "project" as const, filePath: "" },
-      state: { input: {}, steps: {}, status: "running" },
-      startTime: Date.now(),
-    },
-    dispatchFn: mockDispatch(),
-    ...overrides,
-  };
-}
-
-describe("executeAgentStep", () => {
-  // Happy path
-  it("dispatches to dispatchFn and returns its result", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "test-agent" };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir));
-    assert.strictEqual(result.status, "completed");
-    assert.strictEqual(result.agent, "test-agent");
-  });
-
-  it("resolves input expressions before dispatch", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "test-agent", input: { data: "${{ input.value }}" } };
-    const state: ExecutionState = { input: { value: "resolved" }, steps: {}, status: "running" };
-    const capture = { calls: [] as any[] };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir, {
-      dispatchFn: mockDispatch({}, capture),
-    }));
-    assert.strictEqual(result.status, "completed");
-    // The prompt should contain the resolved input
-    assert.ok(capture.calls.length > 0);
-    const prompt = capture.calls[0].prompt;
-    assert.ok(prompt.includes("resolved"), `Expected prompt to contain "resolved", got: ${prompt}`);
-  });
-
-  it("loads agent via loadAgent callback", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "my-special-agent" };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-    let loadedAgentName = "";
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir, {
-      loadAgent: (name: string) => {
-        loadedAgentName = name;
-        return { name };
-      },
-    }));
-    assert.strictEqual(loadedAgentName, "my-special-agent");
-    assert.strictEqual(result.status, "completed");
-  });
-
-  it("compiles agent spec through templateEnv when provided", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    // stepSpec.input maps role from state.input so resolvedInput carries it to compileAgentSpec
-    const stepSpec: StepSpec = { agent: "test-agent", input: { role: "${{ input.role }}" } };
-    const state: ExecutionState = { input: { role: "analyzer" }, steps: {}, status: "running" };
-    const env = new nunjucks.Environment(undefined, { autoescape: false, throwOnUndefined: false });
-    const capture = { calls: [] as any[] };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir, {
-      loadAgent: () => ({ name: "test", systemPrompt: "You are a {{ role }}" }),
-      templateEnv: env,
-      dispatchFn: mockDispatch({}, capture),
-    }));
-    assert.strictEqual(result.status, "completed");
-    // The compiled agent should have the rendered systemPrompt
-    assert.ok(capture.calls.length > 0);
-    const passedAgent = capture.calls[0].agent;
-    assert.strictEqual(passedAgent.systemPrompt, "You are a analyzer");
-  });
-
-  it("passes signal to dispatchFn", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "test-agent" };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-    const controller = new AbortController();
-    const capture = { calls: [] as any[] };
-
-    await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir, {
-      signal: controller.signal,
-      dispatchFn: mockDispatch({}, capture),
-    }));
-    assert.ok(capture.calls.length > 0);
-    assert.strictEqual(capture.calls[0].opts.signal, controller.signal);
-  });
-
-  it("passes timeout to dispatchFn when stepSpec.timeout is set", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "test-agent", timeout: { seconds: 30 } };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-    const capture = { calls: [] as any[] };
-
-    await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir, {
-      dispatchFn: mockDispatch({}, capture),
-    }));
-    assert.ok(capture.calls.length > 0);
-    assert.strictEqual(capture.calls[0].opts.timeoutMs, 30000);
-  });
-
-  // Expression resolution failure
-  it("returns failed result when input expression resolution throws", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "test-agent", input: { bad: "${{ steps.missing.output }}" } };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir));
-    assert.strictEqual(result.status, "failed");
-    assert.ok(result.error);
-    assert.ok(result.error!.includes("missing"));
-    assert.strictEqual(result.durationMs, 0);
-    assert.deepStrictEqual(result.usage, zeroUsage());
-  });
-
-  // Output validation (schema-bound output)
-  it("validates output file against schema when output.schema is set and file exists", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-
-    // Create schema file
-    const schemaDir = path.join(tmpDir, "schemas");
-    fs.mkdirSync(schemaDir, { recursive: true });
-    fs.writeFileSync(path.join(schemaDir, "output.json"), JSON.stringify({
-      type: "object",
-      required: ["summary"],
-      properties: { summary: { type: "string" } },
-    }));
-
-    // Create outputs file simulating what the subprocess would write
-    fs.writeFileSync(
-      path.join(tmpDir, "outputs", "step1.json"),
-      JSON.stringify({ summary: "all good" }),
-    );
-
-    const stepSpec: StepSpec = {
-      agent: "test-agent",
-      output: { schema: path.join(schemaDir, "output.json") },
-    };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir));
-    assert.strictEqual(result.status, "completed");
-    assert.deepStrictEqual(result.output, { summary: "all good" });
-  });
-
-  it("falls back to textOutput parsing when output file does not exist", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-
-    const schemaDir = path.join(tmpDir, "schemas");
-    fs.mkdirSync(schemaDir, { recursive: true });
-    fs.writeFileSync(path.join(schemaDir, "output.json"), JSON.stringify({
-      type: "object",
-      required: ["summary"],
-      properties: { summary: { type: "string" } },
-    }));
-
-    const stepSpec: StepSpec = {
-      agent: "test-agent",
-      output: { schema: path.join(schemaDir, "output.json") },
-    };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir, {
-      dispatchFn: mockDispatch({ textOutput: JSON.stringify({ summary: "from text" }) }),
-    }));
-    assert.strictEqual(result.status, "completed");
-    assert.deepStrictEqual(result.output, { summary: "from text" });
-  });
-
-  it("fails when schema validation rejects output", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-
-    const schemaDir = path.join(tmpDir, "schemas");
-    fs.mkdirSync(schemaDir, { recursive: true });
-    fs.writeFileSync(path.join(schemaDir, "output.json"), JSON.stringify({
-      type: "object",
-      required: ["summary"],
-      properties: { summary: { type: "string" } },
-    }));
-
-    // Write invalid output (missing required field "summary")
-    fs.writeFileSync(
-      path.join(tmpDir, "outputs", "step1.json"),
-      JSON.stringify({ other: "nope" }),
-    );
-
-    const stepSpec: StepSpec = {
-      agent: "test-agent",
-      output: { schema: path.join(schemaDir, "output.json") },
-    };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir));
-    assert.strictEqual(result.status, "failed");
-    assert.ok(result.error);
-    assert.ok(result.error!.toLowerCase().includes("validat") || result.error!.includes("required"));
-  });
-
-  it("fails when no valid JSON output is available for schema-bound step", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-
-    const schemaDir = path.join(tmpDir, "schemas");
-    fs.mkdirSync(schemaDir, { recursive: true });
-    fs.writeFileSync(path.join(schemaDir, "output.json"), JSON.stringify({
-      type: "object",
-      properties: { summary: { type: "string" } },
-    }));
-
-    const stepSpec: StepSpec = {
-      agent: "test-agent",
-      output: { schema: path.join(schemaDir, "output.json") },
-    };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir, {
-      dispatchFn: mockDispatch({ textOutput: "not valid JSON at all" }),
-    }));
-    assert.strictEqual(result.status, "failed");
-    assert.ok(result.error);
-    assert.ok(result.error!.includes("no valid JSON output"));
-  });
-
-  // Output persistence (non-schema path)
-  it("persists output via persistStepOutput when no schema", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "test-agent" };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir));
-    // persistStepOutput should have been called — outputPath set
-    assert.ok(result.outputPath);
-  });
-
-  it("resolves output.path expressions for persistence", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const customPath = path.join(tmpDir, "resolved-output.json");
-    const stepSpec: StepSpec = {
-      agent: "test-agent",
-      output: { path: customPath },
-    };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir));
-    assert.strictEqual(result.outputPath, customPath);
-  });
-
-  // Edge cases
-  it("handles undefined stepSpec.input (defaults to {})", async (t) => {
-    const tmpDir = makeTmpRunDir(t);
-    const stepSpec: StepSpec = { agent: "test-agent" };
-    const state: ExecutionState = { input: {}, steps: {}, status: "running" };
-
-    const result = await executeAgentStep("step1", stepSpec, state, makeOptions(tmpDir));
-    assert.strictEqual(result.status, "completed");
-  });
-
-  it("uses real dispatch when dispatchFn not provided (structural check)", async (t) => {
-    // This test verifies the fallback code path exists structurally
-    // without actually spawning a subprocess (which requires pi on PATH).
-    // We verify by checking that the function signature accepts options without dispatchFn.
-    const tmpDir = makeTmpRunDir(t);
-    const options: AgentStepOptions = {
-      ctx: mockCtx(tmpDir),
-      loadAgent: () => ({ name: "default" }),
-      runDir: tmpDir,
-      specFilePath: path.join(tmpDir, "spec.yaml"),
-      widgetState: {
-        spec: { name: "test", description: "", steps: {}, source: "project" as const, filePath: "" },
-        state: { input: {}, steps: {}, status: "running" },
-        startTime: Date.now(),
-      },
-      // dispatchFn intentionally omitted — defaults to real dispatch
-    };
-    // Just verify the options type is valid without actually calling
-    assert.ok(options.dispatchFn === undefined);
-  });
-});

package/src/step-agent.ts

@@ -1,178 +0,0 @@
-/**
- * Agent step executor — dispatches an LLM subprocess and validates output.
- */
-import fs from "node:fs";
-import path from "node:path";
-import type { StepSpec, AgentSpec, StepResult, ExecutionState, ExpressionScope } from "./types.ts";
-import type { ProgressWidgetState } from "./tui.ts";
-import { resolveExpressions } from "./expression.ts";
-import { dispatch } from "./dispatch.ts";
-import { validateFromFile } from "@davidorex/pi-project/src/schema-validator.ts";
-import { persistStepOutput } from "./output.ts";
-import { zeroUsage, resolveSchemaPath, buildPrompt, compileAgentSpec } from "./step-shared.ts";
-import type nunjucks from "nunjucks";
-
-/** Retry context passed from the executor on retry attempts. */
-export interface RetryContext {
-  attempt: number;
-  priorErrors: string[];
-  steeringMessage?: string;
-}
-
-export interface AgentStepOptions {
-  ctx: any;
-  signal?: AbortSignal;
-  loadAgent: (name: string) => AgentSpec;
-  runDir: string;
-  specFilePath: string;
-  widgetState: ProgressWidgetState;
-  templateEnv?: nunjucks.Environment;
-  dispatchFn?: typeof dispatch;   // injectable for testing; defaults to real dispatch
-  modelConfig?: import("./dispatch.ts").ModelConfig;
-  retryContext?: RetryContext;    // set on retry attempts (attempt > 1)
-  onStepActivity?: (activity: { tool: string; preview: string; timestamp: number }) => void;
-}
-
-/**
- * Execute an agent step: resolve input, render templates, dispatch subprocess,
- * validate output, persist result.
- *
- * Returns the StepResult.
- */
-export async function executeAgentStep(
-  stepName: string,
-  stepSpec: StepSpec,
-  state: ExecutionState,
-  options: AgentStepOptions,
-): Promise<StepResult> {
-  const { ctx, signal, loadAgent, runDir, specFilePath, templateEnv } = options;
-  const scope: ExpressionScope = { input: state.input, steps: state.steps };
-
-  // Expose forEach bindings (as name + forEach metadata) if present on the state
-  const stateAny = state as Record<string, unknown>;
-  if (stateAny.forEach !== undefined) {
-    scope.forEach = stateAny.forEach;
-  }
-  for (const key of Object.keys(stateAny)) {
-    if (key !== "input" && key !== "steps" && key !== "status" && key !== "loop" &&
-        key !== "workflowName" && key !== "specVersion" && key !== "startedAt" &&
-        key !== "updatedAt" && key !== "forEach") {
-      scope[key] = stateAny[key];
-    }
-  }
-
-  // Resolve input expressions
-  let resolvedInput: unknown;
-  try {
-    resolvedInput = resolveExpressions(stepSpec.input ?? {}, scope);
-  } catch (err) {
-    return {
-      step: stepName,
-      agent: stepSpec.agent,
-      status: "failed",
-      usage: zeroUsage(),
-      durationMs: 0,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-
-  // Load and optionally render agent template
-  let agentSpec: AgentSpec;
-  try {
-    agentSpec = loadAgent(stepSpec.agent);
-  } catch (err) {
-    return {
-      step: stepName,
-      agent: stepSpec.agent,
-      status: "failed",
-      usage: zeroUsage(),
-      durationMs: 0,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-  // Inject output schema into template context if available
-  if (stepSpec.output?.schema && typeof resolvedInput === "object" && resolvedInput !== null) {
-    const schemaPath = resolveSchemaPath(stepSpec.output.schema, options.specFilePath);
-    try {
-      const schemaContent = fs.readFileSync(schemaPath, "utf8");
-      (resolvedInput as Record<string, unknown>).output_schema = schemaContent;
-    } catch { /* schema file not found — template can still render without it */ }
-  }
-  agentSpec = compileAgentSpec(agentSpec, resolvedInput, templateEnv);
-
-  let prompt = buildPrompt(stepSpec, agentSpec, resolvedInput, runDir, stepName);
-
-  // Inject retry context if this is a retry attempt
-  if (options.retryContext) {
-    const rc = options.retryContext;
-    const retryParts: string[] = [];
-    retryParts.push(`## Retry Context (attempt ${rc.attempt})\n`);
-    retryParts.push("Your previous attempt failed. The filesystem has been rolled back to its pre-attempt state.\n");
-    retryParts.push("### Prior Errors");
-    for (let i = 0; i < rc.priorErrors.length; i++) {
-      retryParts.push(`${i + 1}. ${rc.priorErrors[i]}`);
-    }
-    retryParts.push("");
-    if (rc.steeringMessage) {
-      retryParts.push("### Steering");
-      retryParts.push(rc.steeringMessage);
-      retryParts.push("");
-    }
-    retryParts.push("---\n");
-    prompt = retryParts.join("\n") + prompt;
-  }
-
-  const dispatchFn = options.dispatchFn ?? dispatch;
-  const result = await dispatchFn(stepSpec, agentSpec, prompt, {
-    cwd: ctx.cwd,
-    sessionLogDir: path.join(runDir, "sessions"),
-    stepName,
-    signal,
-    timeoutMs: stepSpec.timeout ? stepSpec.timeout.seconds * 1000 : undefined,
-    onEvent: (event) => {
-      if (event.type === "tool_execution_start" && event.toolName && options.onStepActivity) {
-        options.onStepActivity({
-          tool: event.toolName,
-          preview: event.toolArgs || "",
-          timestamp: Date.now(),
-        });
-      }
-    },
-    modelConfig: options.modelConfig,
-  });
-
-  // Resolve output path from spec (may contain ${{ }} expressions)
-  const resolvedOutputPath = stepSpec.output?.path
-    ? String(resolveExpressions(stepSpec.output.path, scope))
-    : undefined;
-
-  // Validate output against schema (if defined)
-  if (stepSpec.output?.schema && result.status === "completed") {
-    const schemaPath = resolveSchemaPath(stepSpec.output.schema, specFilePath);
-    try {
-      const outputFilePath = path.join(runDir, "outputs", `${stepName}.json`);
-      if (fs.existsSync(outputFilePath)) {
-        const rawOutput = JSON.parse(fs.readFileSync(outputFilePath, "utf-8"));
-        validateFromFile(schemaPath, rawOutput, `step output for '${stepName}'`);
-        result.output = rawOutput;
-      } else {
-        try {
-          const parsed = JSON.parse(result.textOutput || "");
-          validateFromFile(schemaPath, parsed, `step output for '${stepName}'`);
-          result.output = parsed;
-          result.outputPath = persistStepOutput(runDir, stepName, parsed, undefined, resolvedOutputPath);
-        } catch {
-          result.status = "failed";
-          result.error = `Step '${stepName}' has output schema but no valid JSON output was produced`;
-        }
-      }
-    } catch (err) {
-      result.status = "failed";
-      result.error = err instanceof Error ? err.message : String(err);
-    }
-  } else {
-    result.outputPath = persistStepOutput(runDir, stepName, result.output, result.textOutput, resolvedOutputPath);
-  }
-
-  return result;
-}