@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/src/workflows/engine.ts

@@ -1,6 +1,11 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { resolveArtifacts } from "./artifacts.js";
+import {
+  compileWorkflowDefinition,
+  compositionMetadata,
+  isCompiledWorkflow,
+} from "./composition.js";
 import {
   CancelledError,
   errorMessage,
@@ -12,10 +17,22 @@ import {
   WorkflowSourceChangedError,
 } from "./errors.js";
 import { resolveNext, resolveNextForOutcome, validateWorkflowDefinition } from "./graph.js";
+import {
+  HumanDecisionStore,
+  createHumanDecisionRequest,
+  validateHumanDecisionResponse,
+} from "./human-decision.js";
 import { extractJsonValue } from "./json.js";
 import { runShellAction, shellResultFromError } from "./shell.js";
-import { RUN_STATE_SCHEMA, WorkflowRunStore, createRunId, readRunBundle } from "./store.js";
+import {
+  RUN_STATE_SCHEMA,
+  WorkflowRunStore,
+  createDefinitionSnapshot,
+  createRunId,
+  readRunBundle,
+} from "./store.js";
 import type {
+  AcceptedHumanDecision,
   AgentNodeDefinition,
   AgentStepExecutor,
   ActionNodeDefinition,
@@ -32,6 +49,7 @@ import type {
   WorkflowNodeOutcome,
   WorkflowNodeResult,
   WorkflowNotificationSink,
+  HumanDecisionRequest,
   WorkflowRunResult,
   WorkflowRunState,
   WorkflowSource,
@@ -215,10 +233,12 @@ export class WorkflowEngine {
     input: unknown,
     options: { workflowSource?: WorkflowSource; runId?: string } = {},
   ): Promise<WorkflowRunResult> {
+    workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
     validateWorkflowDefinition(workflow);
     // Fail before any bundle exists so bad input cannot leave a partial run
     // on disk or silently change shape when state.json round-trips.
-    const normalizedInput = input === undefined ? null : input;
+    const suppliedInput = input === undefined ? null : input;
+    const normalizedInput = workflow.input ? await workflow.input(suppliedInput) : suppliedInput;
     assertJsonSerializable(normalizedInput, "Workflow run input");
     if (options.runId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(options.runId)) {
       throw new Error(`Invalid workflow run id: ${JSON.stringify(options.runId)}`);
@@ -270,6 +290,7 @@ export class WorkflowEngine {
     runId: string,
     options: { workflowSource?: WorkflowSource; force?: boolean } = {},
   ): Promise<WorkflowRunResult> {
+    workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
     validateWorkflowDefinition(workflow);
     // Reset before any await: a park or cancel landing during preparation
     // must survive, or a host drain would hang while the run executes.
@@ -279,7 +300,7 @@ export class WorkflowEngine {
     const bundle = await this.store.prepareRunResume(runId);
     const { runDir } = bundle;
     const state = bundle.state;
-    const sourceMismatch = workflowSourceMismatch(state, options.workflowSource);
+    const sourceMismatch = workflowIdentityMismatch(state, workflow, options.workflowSource);
     if (sourceMismatch && options.force !== true) {
       throw new WorkflowSourceChangedError(runId);
     }
@@ -330,7 +351,7 @@ export class WorkflowEngine {
         state,
         runDir,
         point.nodeId,
-        state.steps.length,
+        countExecutableSteps(workflow, state.steps),
         point.lastOutput,
       );
     } catch (error) {
@@ -352,8 +373,14 @@ export class WorkflowEngine {
     workflow: WorkflowDefinition,
     parentRunId: string,
     input: unknown,
-    options: { workflowSource?: WorkflowSource; runId?: string; force?: boolean } = {},
+    options: {
+      workflowSource?: WorkflowSource;
+      runId?: string;
+      force?: boolean;
+      humanDecision?: AcceptedHumanDecision;
+    } = {},
   ): Promise<WorkflowRunResult> {
+    workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
     validateWorkflowDefinition(workflow);
     this.cancelled = false;
     this.paused = false;
@@ -367,12 +394,44 @@ export class WorkflowEngine {
         `Cannot continue workflow run ${parentRunId} with status ${parent.state.status}`,
       );
     }
-    const sourceMismatch = workflowSourceMismatch(parent.state, options.workflowSource);
+    const sourceMismatch = workflowIdentityMismatch(parent.state, workflow, options.workflowSource);
     if (sourceMismatch && options.force !== true) {
       throw new WorkflowSourceChangedError(parentRunId);
     }
 
-    const normalizedInput = input === undefined ? null : input;
+    const waitingNodeId = parent.state.waitingOn;
+    const waitingNode = workflow.nodes[waitingNodeId];
+    const humanContract =
+      waitingNode?.nodeType === "checkpoint" ? waitingNode.humanDecision : undefined;
+    let acceptedResponse: unknown;
+    let acceptedNodeId: string | undefined;
+    let normalizedInput: unknown;
+    if (humanContract !== undefined) {
+      if (options.humanDecision === undefined) {
+        throw new Error(`Checkpoint ${waitingNodeId} requires an accepted verified human decision`);
+      }
+      const request = parent.state.finalOutput as HumanDecisionRequest;
+      if (
+        (request?.schema !== "pi-workflows.human-decision-request.v1" &&
+          request?.schema !== "pi-workflows.human-decision-request.v2") ||
+        request.decisionId !== options.humanDecision.decisionId ||
+        request.requestDigest !== options.humanDecision.requestDigest
+      ) {
+        throw new Error("Accepted human decision does not match the waiting request");
+      }
+      const durableDecision = await new HumanDecisionStore(this.store.outputRoot).readAccepted(
+        request.decisionId,
+      );
+      if (durableDecision === null || !isDeepStrictEqual(durableDecision, options.humanDecision)) {
+        throw new Error("Accepted human decision does not match the durable decision record");
+      }
+      acceptedResponse = validateHumanDecisionResponse(request, durableDecision.response);
+      acceptedNodeId = request.nodeId;
+      normalizedInput = await resolveArtifacts(parent.state.input, parent.runDir);
+    } else {
+      const suppliedInput = input === undefined ? null : input;
+      normalizedInput = workflow.input ? await workflow.input(suppliedInput) : suppliedInput;
+    }
     assertJsonSerializable(normalizedInput, "Workflow run input");
     if (options.runId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(options.runId)) {
       throw new Error(`Invalid workflow run id: ${JSON.stringify(options.runId)}`);
@@ -399,6 +458,39 @@ export class WorkflowEngine {
       parent.state.steps,
       parent.runDir,
     )) as WorkflowRunState["steps"];
+    if (humanContract !== undefined && options.humanDecision !== undefined) {
+      const receipt = {
+        decisionId: options.humanDecision.decisionId,
+        requestDigest: options.humanDecision.requestDigest,
+        nodeId: acceptedNodeId ?? waitingNodeId,
+        response: options.humanDecision.response,
+        acceptedAt: options.humanDecision.acceptedAt,
+        answerDigest: options.humanDecision.answerDigest,
+      };
+      state.humanDecision =
+        options.humanDecision.schema === "pi-workflows.human-decision-accepted.v2"
+          ? {
+              schema: "pi-workflows.human-decision-receipt.v2",
+              ...receipt,
+              subjectDigest: options.humanDecision.subjectDigest,
+              presentationDigest: options.humanDecision.presentationDigest,
+              revision: options.humanDecision.revision,
+            }
+          : { schema: "pi-workflows.human-decision-receipt.v1", ...receipt };
+      state.outputs[waitingNodeId] = acceptedResponse;
+      const priorResult = state.results[waitingNodeId];
+      if (priorResult === undefined) {
+        throw new Error(`Waiting human decision result is missing for ${waitingNodeId}`);
+      }
+      state.results[waitingNodeId] = { ...priorResult, output: acceptedResponse };
+      const stepIndex = state.steps.findLastIndex((step) => step.nodeId === waitingNodeId);
+      if (stepIndex < 0)
+        throw new Error(`Waiting human decision step is missing for ${waitingNodeId}`);
+      const priorStep = state.steps[stepIndex];
+      if (priorStep === undefined)
+        throw new Error("Waiting human decision step became unavailable");
+      state.steps[stepIndex] = { ...priorStep, output: acceptedResponse };
+    }
     state.carriedStepCount = state.steps.length;
 
     const runDir = await this.store.initializeRunBundle(workflow, state);
@@ -428,7 +520,7 @@ export class WorkflowEngine {
         state,
         runDir,
         point.nodeId,
-        state.steps.length,
+        countExecutableSteps(workflow, state.steps),
         point.lastOutput,
       );
     } catch (error) {
@@ -546,6 +638,7 @@ export class WorkflowEngine {
     runId: string | undefined,
   ): Promise<WorkflowRunState> {
     const now = new Date().toISOString();
+    const composition = compositionMetadata(workflow);
     return {
       schema: RUN_STATE_SCHEMA,
       traceSeq: 0,
@@ -553,6 +646,10 @@ export class WorkflowEngine {
       workflowName: workflow.name,
       ...(await this.resolveTitleBounded(workflow, input)),
       ...(workflowSource !== undefined ? { workflowSource } : {}),
+      ...(composition?.sources.length ? { workflowSources: composition.sources } : {}),
+      ...(composition?.snapshot.mounts.length
+        ? { definitionDigest: definitionDigest(workflow) }
+        : {}),
       startedAt: now,
       updatedAt: now,
       status: "running",
@@ -573,17 +670,24 @@ export class WorkflowEngine {
     initialLastOutput?: unknown,
   ): Promise<void> {
     const maxSteps = workflow.maxSteps ?? this.maxSteps;
+    const composition = compositionMetadata(workflow);
     let currentNodeId: string | null = startNodeId;
     let executedSteps = executedStepsBase;
     let lastOutput: unknown = initialLastOutput;
 
     while (currentNodeId !== null) {
       await this.holdWhilePaused(state, runDir);
-      executedSteps += 1;
-      if (executedSteps > maxSteps) {
-        throw new Error(
-          `Workflow exceeded maxSteps=${maxSteps}; aborting to avoid an unbounded loop`,
-        );
+      const isTransition =
+        composition?.entries[currentNodeId] !== undefined ||
+        composition?.exits[currentNodeId] !== undefined;
+      if (!isTransition) {
+        executedSteps += 1;
+        if (executedSteps > maxSteps) {
+          throw new Error(
+            `Workflow exceeded maxSteps=${maxSteps}; aborting to avoid an unbounded loop`,
+          );
+        }
+        assertInvocationStepLimit(composition, currentNodeId, state.steps);
       }
 
       const node = workflow.nodes[currentNodeId];
@@ -597,7 +701,7 @@ export class WorkflowEngine {
         // as in-flight, and resume reruns it with a fresh attempt.
         throw new RunParkedError();
       }
-      this.recordAttempt(state, attempt);
+      this.recordAttempt(workflow, state, attempt);
       // The terminal node event carries the output, receipt, and conversation
       // linkage so the trace alone is sufficient to reconstruct the run.
       await this.persist(runDir, state, {
@@ -622,6 +726,35 @@ export class WorkflowEngine {
         continue;
       }
 
+      const entered = composition?.entries[attempt.result.nodeId];
+      if (entered !== undefined) {
+        const value = attempt.result.output as { invocation?: number } | undefined;
+        await this.persist(runDir, state, {
+          scope: "run",
+          type: "include_entered",
+          payload: {
+            mountPath: entered.mountPath.split("/"),
+            workflowName: entered.workflowName,
+            invocation: value?.invocation ?? 1,
+          },
+        });
+      }
+      const exited = composition?.exits[attempt.result.nodeId];
+      if (exited !== undefined) {
+        const entrySteps = state.steps.filter((step) => step.nodeId === exited.mountPath);
+        await this.persist(runDir, state, {
+          scope: "run",
+          type: "include_exited",
+          payload: {
+            mountPath: exited.mountPath.split("/"),
+            workflowName: composition?.scopes[exited.mountPath]?.workflowName ?? exited.mountName,
+            invocation: entrySteps.length,
+            exit: exited.exitName,
+            output: attempt.result.output ?? null,
+          },
+        });
+      }
+
       lastOutput = attempt.result.output;
       if (node.nodeType === "checkpoint") {
         await this.finishRun(runDir, state, "waiting", {
@@ -678,13 +811,13 @@ export class WorkflowEngine {
     state: WorkflowRunState,
     attempt: NodeAttempt,
   ): string | null {
+    if (attempt.result.outcome === "cancelled" || this.cancelled) {
+      throw new CancelledError();
+    }
     const next = resolveNextForOutcome(workflow.edges, attempt.result.nodeId, attempt.result);
     if (next !== null) {
       return next;
     }
-    if (attempt.result.outcome === "cancelled" || this.cancelled) {
-      throw new CancelledError();
-    }
     if (attempt.result.outcome === "timed_out") {
       state.status = "timed_out";
     }
@@ -693,7 +826,11 @@ export class WorkflowEngine {
       : new Error(attempt.result.error ?? `Workflow node failed: ${attempt.result.nodeId}`);
   }
 
-  private recordAttempt(state: WorkflowRunState, attempt: NodeAttempt): void {
+  private recordAttempt(
+    workflow: WorkflowDefinition,
+    state: WorkflowRunState,
+    attempt: NodeAttempt,
+  ): void {
     state.results[attempt.result.nodeId] = attempt.result;
     if (attempt.result.outcome === "ok") {
       state.outputs[attempt.result.nodeId] = attempt.result.output;
@@ -702,6 +839,11 @@ export class WorkflowEngine {
       // must not survive next to a non-ok latest result.
       delete state.outputs[attempt.result.nodeId];
     }
+    const exit = compositionMetadata(workflow)?.exits[attempt.result.nodeId];
+    if (exit !== undefined && attempt.result.outcome === "ok") {
+      state.outputs[exit.mountPath] = attempt.result.output;
+      state.results[exit.mountPath] = { ...attempt.result, nodeId: exit.mountPath };
+    }
     const step: WorkflowStepRecord = {
       attemptId: attempt.result.attemptId,
       nodeId: attempt.result.nodeId,
@@ -977,7 +1119,12 @@ export class WorkflowEngine {
       case "action":
         return await this.runActionNode(node, context, nodeId, attemptId, signal, meta);
       case "checkpoint":
-        return await runCheckpointNode(node, context);
+        return await runCheckpointNode(node, context, {
+          store: this.store,
+          workflowName: workflow.name,
+          nodeId,
+          attemptId,
+        });
     }
   }
 
@@ -1154,7 +1301,30 @@ export class WorkflowEngine {
 async function runCheckpointNode(
   node: CheckpointNodeDefinition,
   context: WorkflowNodeContext,
+  execution: {
+    store: WorkflowRunStore;
+    workflowName: string;
+    nodeId: string;
+    attemptId: string;
+  },
 ): Promise<NodeExecution> {
+  if (node.humanDecision !== undefined) {
+    const prompt = await node.humanDecision.request(context);
+    const audience =
+      typeof node.humanDecision.audience === "function"
+        ? await node.humanDecision.audience(context)
+        : node.humanDecision.audience;
+    const request = createHumanDecisionRequest({
+      runId: context.state.runId,
+      workflowName: execution.workflowName,
+      nodeId: execution.nodeId,
+      attemptId: execution.attemptId,
+      contract: { audience, choices: node.humanDecision.choices },
+      prompt,
+    });
+    await new HumanDecisionStore(execution.store.outputRoot).createRequest(request);
+    return { output: request, promptText: null };
+  }
   const output = node.run ? await node.run(context) : { summary: node.summary ?? "checkpoint" };
   return { output, promptText: null };
 }
@@ -1234,6 +1404,54 @@ function abortRejection(signal: AbortSignal): Promise<never> {
   });
 }
 
+function countExecutableSteps(workflow: WorkflowDefinition, steps: WorkflowStepRecord[]): number {
+  const metadata = compositionMetadata(workflow);
+  if (metadata === undefined) return steps.length;
+  return steps.filter(
+    (step) =>
+      metadata.entries[step.nodeId] === undefined && metadata.exits[step.nodeId] === undefined,
+  ).length;
+}
+
+function assertInvocationStepLimit(
+  metadata: ReturnType<typeof compositionMetadata>,
+  nodeId: string,
+  steps: WorkflowStepRecord[],
+): void {
+  if (metadata === undefined) return;
+  const scopes = Object.values(metadata.scopes)
+    .filter(
+      (candidate) =>
+        candidate.path !== "" &&
+        candidate.maxSteps !== undefined &&
+        nodeId.startsWith(`${candidate.path}/`),
+    )
+    .sort((a, b) => a.path.length - b.path.length);
+  for (const scope of scopes) {
+    let entryIndex = -1;
+    for (let index = steps.length - 1; index >= 0; index -= 1) {
+      if (steps[index]?.nodeId === scope.path) {
+        entryIndex = index;
+        break;
+      }
+    }
+    if (entryIndex < 0) throw new Error(`Workflow include entry is missing: ${scope.path}`);
+    const attempts = steps
+      .slice(entryIndex + 1)
+      .filter(
+        (step) =>
+          step.nodeId.startsWith(`${scope.path}/`) &&
+          metadata.entries[step.nodeId] === undefined &&
+          metadata.exits[step.nodeId] === undefined,
+      ).length;
+    if (attempts >= (scope.maxSteps as number)) {
+      throw new Error(
+        `Included workflow ${scope.workflowName} at ${scope.path} exceeded maxSteps=${scope.maxSteps}`,
+      );
+    }
+  }
+}
+
 /**
  * Outputs are persisted to the run bundle, so they must be JSON-serializable.
  * Failing here turns a bad callback return value into a normal node failure
@@ -1255,6 +1473,25 @@ function workflowSourceMismatch(
   );
 }
 
+function workflowIdentityMismatch(
+  state: WorkflowRunState,
+  workflow: WorkflowDefinition,
+  source: WorkflowSource | undefined,
+): boolean {
+  if (workflowSourceMismatch(state, source)) return true;
+  const metadata = compositionMetadata(workflow);
+  const currentSources = metadata?.sources ?? [];
+  if (!isDeepStrictEqual(state.workflowSources ?? [], currentSources)) return true;
+  const currentDigest = metadata?.snapshot.mounts.length ? definitionDigest(workflow) : undefined;
+  return state.definitionDigest !== currentDigest;
+}
+
+function definitionDigest(workflow: WorkflowDefinition): string {
+  return `sha256:${createHash("sha256")
+    .update(JSON.stringify(createDefinitionSnapshot(workflow)))
+    .digest("hex")}`;
+}
+
 function assertJsonSerializable(value: unknown, what: string): void {
   let encoded: string | undefined;
   try {

package/src/workflows/graph.ts

@@ -1,3 +1,4 @@
+import { compileWorkflowDefinition, isCompiledWorkflow } from "./composition.js";
 import { assertValidWorkflowDefinitionShape } from "./schema.js";
 import type { WorkflowDefinition, WorkflowEdge, WorkflowNodeResult } from "./types.js";
 
@@ -6,17 +7,18 @@ import type { WorkflowDefinition, WorkflowEdge, WorkflowNodeResult } from "./typ
  * at most one outgoing edge per node.
  */
 export function validateWorkflowDefinition(workflow: WorkflowDefinition): void {
-  assertValidWorkflowDefinitionShape(workflow);
-  if (!Object.hasOwn(workflow.nodes, workflow.startAt)) {
-    throw new Error(`Workflow start node is missing: ${workflow.startAt}`);
+  const executable = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
+  assertValidWorkflowDefinitionShape(executable, { compiled: true });
+  if (!Object.hasOwn(executable.nodes, executable.startAt)) {
+    throw new Error(`Workflow start node is missing: ${executable.startAt}`);
   }
 
   const outgoingEdges = new Set<string>();
-  for (const edge of workflow.edges) {
-    validateWorkflowEdge(workflow, edge, outgoingEdges);
+  for (const edge of executable.edges) {
+    validateWorkflowEdge(executable, edge, outgoingEdges);
   }
 
-  assertAllNodesReachable(workflow);
+  assertAllNodesReachable(executable);
 }
 
 /** Reject nodes that no path from `startAt` can ever reach. */