@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/src/workflows/index.ts

@@ -4,11 +4,56 @@ export {
   checkpoint,
   compute,
   defineWorkflow,
+  defineWorkflowRegistry,
+  includeWorkflow,
+  includedResult,
   isWorkflowDefinition,
   notify,
   shell,
 } from "./definition.js";
 export { decision, decisionEdge, type DecisionDefinition } from "./decision.js";
+export {
+  MAX_PRESENTATION_BLOCKS,
+  MAX_PRESENTATION_CODE_UNITS,
+  MAX_PRESENTATION_ITEMS,
+  MAX_PRESENTATION_STRING_CODE_UNITS,
+  MAX_PRESENTATION_TRANSPORT_PARTS,
+  decisionDocumentSegments,
+  decisionPresentationDigest,
+  decisionPresentationFingerprint,
+  digestCanonical,
+  humanDecisionChannelRequest,
+  legacyDecisionPresentation,
+  normalizeDecisionPresentation,
+  validateHumanDecisionRequestIntegrity,
+  type DecisionDocumentSegment,
+} from "./decision-presentation.js";
+export {
+  HumanDecisionStore,
+  canonicalJson,
+  choice,
+  createHumanDecisionAttemptId,
+  createHumanDecisionRequest,
+  defineHumanChoices,
+  digest,
+  humanDecision,
+  humanDecisionEdge,
+  humanDecisionStateRoot,
+  textInput,
+  validateHumanDecisionResponse,
+  validateHumanDecisionSubmission,
+  type HumanDecisionAcceptance,
+  type HumanDecisionChoiceDefinition,
+  type HumanDecisionDefinition,
+  type HumanDecisionResponseFor,
+} from "./human-decision.js";
+export {
+  compileWorkflowDefinition,
+  compositionMetadata,
+  isCompiledWorkflow,
+  type CompileWorkflowOptions,
+  type WorkflowCompositionMetadata,
+} from "./composition.js";
 export { WorkflowEngine, appendStepContract } from "./engine.js";
 export { CancelledError, TimeoutError } from "./errors.js";
 export {
@@ -76,6 +121,9 @@ export {
   type ReadRunBundleOptions,
 } from "./store.js";
 export type {
+  AcceptedHumanDecision,
+  AcceptedHumanDecisionV1,
+  AcceptedHumanDecisionV2,
   AgentNodeDefinition,
   AgentStepContract,
   AgentStepExecutor,
@@ -89,16 +137,57 @@ export type {
   ConversationRange,
   ComputeNodeDefinition,
   FunctionActionNodeDefinition,
+  DecisionPresentation,
+  DecisionPresentationBlock,
+  DecisionPresentationBullets,
+  DecisionPresentationFields,
+  DecisionPresentationParagraph,
+  DecisionPresentationPreformatted,
+  DecisionPresentationSection,
+  HumanDecisionAnswerSource,
+  HumanDecisionAudience,
+  HumanDecisionCancellationRecord,
+  HumanDecisionChannelRequest,
+  HumanDecisionChoice,
+  HumanDecisionChoiceMap,
+  HumanDecisionContinuationRecord,
+  HumanDecisionDeliveryRecord,
+  HumanDecisionDeliveryRecordV1,
+  HumanDecisionDeliveryRecordV2,
+  HumanDecisionNodeContract,
+  HumanDecisionPrompt,
+  HumanDecisionReceipt,
+  HumanDecisionReceiptV1,
+  HumanDecisionReceiptV2,
+  HumanDecisionRequest,
+  HumanDecisionRequestV1,
+  HumanDecisionRequestV2,
+  HumanDecisionResponse,
+  HumanDecisionSettlementRecord,
+  HumanDecisionSubmission,
+  HumanDecisionTextInput,
+  LegacyHumanDecisionPrompt,
   MaybePromise,
   NotifyNodeDefinition,
+  PresentedHumanDecisionPrompt,
   ShellActionExecution,
   ShellActionNodeDefinition,
   ShellActionResult,
   WorkflowActionContext,
   WorkflowActionReceipt,
+  WorkflowCompositionSnapshot,
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
   WorkflowEdge,
+  WorkflowExitDefinition,
+  WorkflowExitMap,
+  WorkflowExitOutputs,
+  WorkflowIncludeDefinition,
+  WorkflowIncludedResult,
+  WorkflowInputOf,
+  WorkflowMountedSource,
+  WorkflowMountSnapshot,
+  WorkflowValueParser,
   WorkflowEngineOptions,
   WorkflowNodeCommon,
   WorkflowNodeContext,

package/src/workflows/loader.ts

@@ -5,9 +5,19 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
 import type { BuiltinWorkflowCatalog } from "./catalog.js";
-import { isWorkflowDefinition } from "./definition.js";
+import {
+  compileWorkflowDefinition,
+  compositionMetadata,
+  type WorkflowCompositionSourceMap,
+} from "./composition.js";
+import { defineWorkflow, isWorkflowDefinition } from "./definition.js";
 import { WorkflowSourceChangedError } from "./errors.js";
-import type { WorkflowDefinition, WorkflowSource } from "./types.js";
+import type {
+  WorkflowDefinition,
+  WorkflowIncludeDefinition,
+  WorkflowMountedSource,
+  WorkflowSource,
+} from "./types.js";
 
 const WORKFLOW_FILE_SUFFIXES = [".workflow.ts", ".workflow.js", ".workflow.mts", ".workflow.mjs"];
 
@@ -25,9 +35,12 @@ export type WorkflowSearchPaths = {
 export type ResolvedWorkflow = {
   definition: WorkflowDefinition;
   source: WorkflowSource;
+  sources: WorkflowMountedSource[];
   sourceKind: DiscoveredWorkflow["source"];
 };
 
+type SingleResolvedWorkflow = Omit<ResolvedWorkflow, "sources">;
+
 /** Directories scanned for user workflow files, in precedence order. */
 export function workflowSearchDirs(
   options: WorkflowSearchPaths,
@@ -59,6 +72,12 @@ export function workflowFileStem(filePath: string): string {
 // Alias package imports to this process's workflow API. User files can reload,
 // but their node constructors and validators remain from one engine version.
 const SELF_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
+const BUILTINS_ENTRY = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "builtins",
+  "index",
+);
 
 /** Load a user workflow module from disk. */
 export async function loadWorkflowFile(filePath: string): Promise<WorkflowDefinition> {
@@ -66,7 +85,11 @@ export async function loadWorkflowFile(filePath: string): Promise<WorkflowDefini
   const jiti = createJiti(pathToFileURL(absolutePath).href, {
     interopDefault: true,
     moduleCache: false,
-    alias: { "@osolmaz/pi-workflows": SELF_ENTRY },
+    alias: {
+      "@osolmaz/pi-workflows/builtins": BUILTINS_ENTRY,
+      "@osolmaz/pi-workflows": SELF_ENTRY,
+      "pi-workflows": SELF_ENTRY,
+    },
   });
   const loaded = (await jiti.import(absolutePath, { default: true })) as unknown;
   if (!isWorkflowDefinition(loaded)) {
@@ -111,12 +134,42 @@ async function listWorkflowFiles(dir: string): Promise<string[]> {
     .sort();
 }
 
-/** Resolve a workflow name, stable built-in ref, or direct user file path. */
+/** Resolve a workflow and every nested include before returning it. */
 export async function resolveWorkflowRef(
   ref: string,
   options: WorkflowSearchPaths,
   catalog?: BuiltinWorkflowCatalog,
 ): Promise<ResolvedWorkflow> {
+  const root = await resolveSingleWorkflowRef(ref, options, catalog, options.cwd);
+  const sourceMap: WorkflowCompositionSourceMap = new Map([[root.definition, root.source]]);
+  const activeSources: string[] = [];
+  const definition = await resolveIncludes(
+    root.definition,
+    sourceBaseDir(root.source),
+    options,
+    catalog,
+    sourceMap,
+    activeSources,
+    sourceKey(root.source),
+  );
+  const compiled = compileWorkflowDefinition(definition, {
+    rootSource: root.source,
+    sourceMap,
+  });
+  return {
+    definition: compiled,
+    source: root.source,
+    sources: compositionMetadata(compiled)?.sources ?? [],
+    sourceKind: root.sourceKind,
+  };
+}
+
+async function resolveSingleWorkflowRef(
+  ref: string,
+  options: WorkflowSearchPaths,
+  catalog: BuiltinWorkflowCatalog | undefined,
+  relativeBase: string,
+): Promise<SingleResolvedWorkflow> {
   if (ref.startsWith("builtin:")) {
     const id = ref.slice("builtin:".length);
     const builtin = catalog?.get(id);
@@ -128,7 +181,7 @@ export async function resolveWorkflowRef(
     };
   }
   if (looksLikePath(ref)) {
-    const absolutePath = path.resolve(options.cwd, ref);
+    const absolutePath = path.resolve(relativeBase, ref);
     await fs.access(absolutePath);
     return {
       definition: await loadWorkflowFile(absolutePath),
@@ -142,30 +195,145 @@ export async function resolveWorkflowRef(
     const available = discovered.map((workflow) => workflow.name).join(", ") || "(none)";
     throw new Error(`Unknown workflow ${JSON.stringify(ref)}. Available workflows: ${available}`);
   }
-  if (match.source === "builtin") return await resolveWorkflowRef(match.ref, options, catalog);
-  const absolutePath = path.resolve(match.ref);
-  return {
-    definition: await loadWorkflowFile(absolutePath),
-    source: { kind: "file", path: absolutePath, hash: await hashWorkflowSource(absolutePath) },
-    sourceKind: match.source,
-  };
+  const resolved = await resolveSingleWorkflowRef(match.ref, options, catalog, options.cwd);
+  return { ...resolved, sourceKind: match.source };
+}
+
+async function resolveIncludes(
+  workflow: WorkflowDefinition,
+  baseDir: string | undefined,
+  options: WorkflowSearchPaths,
+  catalog: BuiltinWorkflowCatalog | undefined,
+  sourceMap: WorkflowCompositionSourceMap,
+  activeSources: string[],
+  currentSourceKey: string,
+): Promise<WorkflowDefinition> {
+  const cycleAt = activeSources.indexOf(currentSourceKey);
+  if (cycleAt >= 0) {
+    throw new Error(
+      `Workflow include source cycle: ${[...activeSources.slice(cycleAt), currentSourceKey].join(" -> ")}`,
+    );
+  }
+  activeSources.push(currentSourceKey);
+  const resolvedIncludes: Record<string, WorkflowIncludeDefinition> = {};
+  for (const [mountName, include] of Object.entries(workflow.includes ?? {})) {
+    let child: WorkflowDefinition;
+    let childSource: WorkflowSource | undefined;
+    let childBaseDir = baseDir;
+    if (typeof include.workflow === "string") {
+      if (
+        baseDir === undefined &&
+        looksLikePath(include.workflow) &&
+        !path.isAbsolute(include.workflow)
+      ) {
+        throw new Error(
+          `Built-in workflow ${workflow.name} cannot resolve relative include ${include.workflow}`,
+        );
+      }
+      const resolved = await resolveSingleWorkflowRef(
+        include.workflow,
+        options,
+        catalog,
+        baseDir ?? options.cwd,
+      );
+      child = resolved.definition;
+      childSource = resolved.source;
+      childBaseDir = sourceBaseDir(resolved.source);
+    } else {
+      child = include.workflow;
+      childSource = await sourceForDirectDefinition(child, catalog);
+      childBaseDir = childSource ? sourceBaseDir(childSource) : baseDir;
+    }
+    if (childSource !== undefined) sourceMap.set(child, childSource);
+    assertContractCompatible(include, child, mountName);
+    const childKey = childSource ? sourceKey(childSource) : `memory:${child.name}`;
+    const resolvedChild = await resolveIncludes(
+      child,
+      childBaseDir,
+      options,
+      catalog,
+      sourceMap,
+      activeSources,
+      childKey,
+    );
+    if (childSource !== undefined) sourceMap.set(resolvedChild, childSource);
+    resolvedIncludes[mountName] = { ...include, workflow: resolvedChild };
+  }
+  activeSources.pop();
+  if (Object.keys(resolvedIncludes).length === 0) return workflow;
+  const resolved = defineWorkflow({ ...workflow, includes: resolvedIncludes });
+  const ownSource = sourceMap.get(workflow);
+  if (ownSource !== undefined) sourceMap.set(resolved, ownSource);
+  return resolved;
 }
 
-/** Resolve an already persisted canonical source. */
+async function sourceForDirectDefinition(
+  workflow: WorkflowDefinition,
+  catalog?: BuiltinWorkflowCatalog,
+): Promise<WorkflowSource | undefined> {
+  const builtin = catalog?.sourceForDefinition(workflow);
+  if (builtin !== undefined) return builtin;
+  if (workflow.source === undefined) return undefined;
+  let filePath: string;
+  try {
+    filePath = fileURLToPath(workflow.source);
+  } catch {
+    throw new Error(`Workflow ${workflow.name} source must be a file URL: ${workflow.source}`);
+  }
+  return { kind: "file", path: filePath, hash: await hashWorkflowSource(filePath) };
+}
+
+function assertContractCompatible(
+  include: WorkflowIncludeDefinition,
+  child: WorkflowDefinition,
+  mountName: string,
+): void {
+  if (include.contract === undefined) return;
+  if (
+    include.contract.contractId !== undefined &&
+    child.contractId !== include.contract.contractId
+  ) {
+    throw new Error(
+      `Workflow include ${mountName} contract mismatch: expected ${include.contract.contractId}; got ${child.contractId ?? "none"}`,
+    );
+  }
+  const expected = Object.keys(include.contract.exits ?? {}).sort();
+  const actual = Object.keys(child.exits ?? {}).sort();
+  if (JSON.stringify(expected) !== JSON.stringify(actual)) {
+    throw new Error(
+      `Workflow include ${mountName} exit contract mismatch: expected ${expected.join(", ") || "none"}; got ${actual.join(", ") || "none"}`,
+    );
+  }
+  if ((include.contract.input === undefined) !== (child.input === undefined)) {
+    throw new Error(`Workflow include ${mountName} input contract mismatch`);
+  }
+}
+
+function sourceBaseDir(source: WorkflowSource): string | undefined {
+  return source.kind === "file" ? path.dirname(source.path) : undefined;
+}
+
+function sourceKey(source: WorkflowSource): string {
+  return source.kind === "file"
+    ? `file:${source.path}:${source.hash}`
+    : `builtin:${source.id}:${source.revision}`;
+}
+
+/** Resolve an already persisted canonical source and its includes. */
 export async function resolveWorkflowSource(
   source: WorkflowSource,
   catalog?: BuiltinWorkflowCatalog,
   runId = source.kind === "builtin" ? `builtin:${source.id}` : source.path,
+  options: WorkflowSearchPaths = { cwd: process.cwd() },
 ): Promise<WorkflowDefinition> {
   if (source.kind === "builtin") {
     if (catalog === undefined) throw new Error(`No built-in workflow catalog for ${source.id}`);
-    return catalog.resolve(source, runId);
+    catalog.resolve(source, runId);
+    return (await resolveWorkflowRef(`builtin:${source.id}`, options, catalog)).definition;
   }
   const actualHash = await hashWorkflowSource(source.path);
-  if (actualHash !== source.hash) {
-    throw new WorkflowSourceChangedError(runId);
-  }
-  return await loadWorkflowFile(source.path);
+  if (actualHash !== source.hash) throw new WorkflowSourceChangedError(runId);
+  return (await resolveWorkflowRef(source.path, options, catalog)).definition;
 }
 
 function looksLikePath(ref: string): boolean {

package/src/workflows/schema.ts

@@ -134,6 +134,23 @@ export function assertValidCheckpointNode(
     fail(`node ${nodeId} summary must be a string`);
   }
   assertOptionalFunction(node.run, `node ${nodeId} run`);
+  if (node.humanDecision !== undefined) {
+    assertRecord(node.humanDecision, `node ${nodeId} humanDecision`);
+    if (
+      (typeof node.humanDecision.audience !== "string" ||
+        node.humanDecision.audience.length === 0) &&
+      typeof node.humanDecision.audience !== "function"
+    ) {
+      fail(`node ${nodeId} humanDecision audience must be a non-empty string or function`);
+    }
+    assertRecord(node.humanDecision.choices, `node ${nodeId} humanDecision choices`);
+    if (Object.keys(node.humanDecision.choices).length === 0) {
+      fail(`node ${nodeId} humanDecision choices must not be empty`);
+    }
+    if (typeof node.humanDecision.request !== "function") {
+      fail(`node ${nodeId} humanDecision request must be a function`);
+    }
+  }
   assertCommonNodeFields(node, nodeId);
 }
 
@@ -199,7 +216,10 @@ function assertValidEdgeShape(edge: WorkflowEdge, index: number): void {
  */
 const RESERVED_WORKFLOW_NAMES = new Set(["answer", "cancel", "list", "pause", "resume", "status"]);
 
-export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinition): void {
+export function assertValidWorkflowDefinitionShape(
+  definition: WorkflowDefinition,
+  options: { compiled?: boolean } = {},
+): void {
   assertRecord(definition, "workflow");
   if (typeof definition.name !== "string" || definition.name.length === 0) {
     fail("workflow requires a name");
@@ -207,6 +227,17 @@ export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinitio
   if (RESERVED_WORKFLOW_NAMES.has(definition.name)) {
     fail(`workflow name ${JSON.stringify(definition.name)} is reserved for /workflow subcommands`);
   }
+  if (definition.source !== undefined && typeof definition.source !== "string") {
+    fail("workflow source must be a string");
+  }
+  if (
+    definition.contractId !== undefined &&
+    (typeof definition.contractId !== "string" ||
+      !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(definition.contractId))
+  ) {
+    fail("workflow contractId must be a stable identifier");
+  }
+  assertOptionalFunction(definition.input, "workflow input");
   if (
     definition.title !== undefined &&
     typeof definition.title !== "string" &&
@@ -237,7 +268,14 @@ export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinitio
     fail("workflow requires at least one node");
   }
   for (const [nodeId, node] of Object.entries(definition.nodes)) {
-    if (!NODE_ID_PATTERN.test(nodeId)) {
+    const segments = nodeId.split("/");
+    if (
+      segments.some(
+        (segment) =>
+          !NODE_ID_PATTERN.test(segment) || (!options.compiled && segment.startsWith("__piw_")),
+      ) ||
+      (!options.compiled && segments.length !== 1)
+    ) {
       fail(`node id ${JSON.stringify(nodeId)} must match ${NODE_ID_PATTERN.source}`);
     }
     // Ids like __proto__ or toString would collide with Object prototype
@@ -248,6 +286,45 @@ export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinitio
     assertRecord(node, `node ${nodeId}`);
     assertValidNode(node, nodeId);
   }
+  if (definition.includes !== undefined) {
+    assertRecord(definition.includes, "workflow includes");
+    for (const [mountName, include] of Object.entries(definition.includes)) {
+      if (!NODE_ID_PATTERN.test(mountName) || mountName.startsWith("__piw_")) {
+        fail(`include name ${JSON.stringify(mountName)} must match ${NODE_ID_PATTERN.source}`);
+      }
+      if (Object.hasOwn(definition.nodes, mountName)) {
+        fail(`include name ${JSON.stringify(mountName)} collides with a node id`);
+      }
+      assertRecord(include, `include ${mountName}`);
+      if (
+        typeof include.workflow !== "string" &&
+        (include.workflow === null || typeof include.workflow !== "object")
+      ) {
+        fail(`include ${mountName} requires a workflow definition or reference`);
+      }
+      assertOptionalFunction(include.input, `include ${mountName} input`);
+      if (
+        include.contract !== undefined &&
+        (include.contract === null || typeof include.contract !== "object")
+      ) {
+        fail(`include ${mountName} contract must be a workflow definition`);
+      }
+    }
+  }
+  if (definition.exits !== undefined) {
+    assertRecord(definition.exits, "workflow exits");
+    if (Object.keys(definition.exits).length === 0) fail("workflow exits must not be empty");
+    for (const [exitName, exit] of Object.entries(definition.exits)) {
+      if (!NODE_ID_PATTERN.test(exitName) || exitName.startsWith("__piw_")) {
+        fail(`exit name ${JSON.stringify(exitName)} must match ${NODE_ID_PATTERN.source}`);
+      }
+      assertRecord(exit, `exit ${exitName}`);
+      if (typeof exit.from !== "string" || exit.from.length === 0) {
+        fail(`exit ${exitName} requires from`);
+      }
+      assertOptionalFunction(exit.validate, `exit ${exitName} validate`);
+    }
+  }
   if (!Array.isArray(definition.edges)) {
     fail("workflow edges must be an array");
   }

package/src/workflows/store.ts

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { ArtifactWriter, encodeValue } from "./artifacts.js";
+import { compositionMetadata } from "./composition.js";
 import type {
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
@@ -1350,6 +1351,8 @@ function createManifest(
     workflowName: state.workflowName,
     ...(state.runTitle !== undefined ? { runTitle: state.runTitle } : {}),
     ...(state.workflowSource !== undefined ? { workflowSource: state.workflowSource } : {}),
+    ...(state.workflowSources !== undefined ? { workflowSources: state.workflowSources } : {}),
+    ...(state.definitionDigest !== undefined ? { definitionDigest: state.definitionDigest } : {}),
     startedAt: state.startedAt,
     ...(state.finishedAt !== undefined ? { finishedAt: state.finishedAt } : {}),
     status: state.status,
@@ -1368,20 +1371,52 @@ function createManifest(
 }
 
 export function createDefinitionSnapshot(workflow: WorkflowDefinition): WorkflowDefinitionSnapshot {
+  const composition = compositionMetadata(workflow)?.snapshot;
   return {
     schema: DEFINITION_SNAPSHOT_SCHEMA,
     name: workflow.name,
+    ...(workflow.contractId !== undefined ? { contractId: workflow.contractId } : {}),
     startAt: workflow.startAt,
     nodes: Object.fromEntries(
-      Object.entries(workflow.nodes).map(([nodeId, node]) => [nodeId, snapshotNode(node)]),
+      Object.entries(workflow.nodes).map(([nodeId, node]) => [
+        nodeId,
+        snapshotNode(workflow, nodeId, node),
+      ]),
     ),
     edges: structuredClone(workflow.edges),
+    ...(composition !== undefined ? { composition: structuredClone(composition) } : {}),
   };
 }
 
-function snapshotNode(node: WorkflowNodeDefinition): WorkflowNodeSnapshot {
+function snapshotNode(
+  workflow: WorkflowDefinition,
+  nodeId: string,
+  node: WorkflowNodeDefinition,
+): WorkflowNodeSnapshot {
+  const composition = compositionMetadata(workflow);
+  const entry = composition?.entries[nodeId];
+  const exit = composition?.exits[nodeId];
+  const scope = Object.values(composition?.scopes ?? {})
+    .filter((candidate) => candidate.path !== "" && nodeId.startsWith(`${candidate.path}/`))
+    .sort((a, b) => b.path.length - a.path.length)[0];
+  const mountPath = entry?.mountPath ?? exit?.mountPath ?? scope?.path;
+  const localNodeId =
+    entry !== undefined
+      ? entry.mountName
+      : exit !== undefined
+        ? exit.exitName
+        : scope !== undefined
+          ? nodeId.slice(scope.path.length + 1)
+          : undefined;
   const common: WorkflowNodeSnapshot = {
     nodeType: node.nodeType,
+    ...(mountPath !== undefined ? { mountPath: mountPath.split("/") } : {}),
+    ...(localNodeId !== undefined ? { localNodeId } : {}),
+    ...(entry !== undefined
+      ? { includeTransition: "entry" as const }
+      : exit !== undefined
+        ? { includeTransition: "exit" as const }
+        : {}),
     ...(typeof node.timeoutMs === "number" ? { timeoutMs: node.timeoutMs } : {}),
     ...(node.statusDetail !== undefined ? { statusDetail: node.statusDetail } : {}),
   };
@@ -1394,6 +1429,14 @@ function snapshotNode(node: WorkflowNodeDefinition): WorkflowNodeSnapshot {
   if (node.nodeType === "checkpoint" && node.summary !== undefined) {
     common.summary = node.summary;
   }
+  if (node.nodeType === "checkpoint" && node.humanDecision !== undefined) {
+    common.humanDecision = {
+      audience:
+        typeof node.humanDecision.audience === "string" ? node.humanDecision.audience : "<dynamic>",
+      ...(typeof node.humanDecision.audience === "function" ? { dynamicAudience: true } : {}),
+      choices: structuredClone(node.humanDecision.choices),
+    };
+  }
   if (node.nodeType === "action") {
     common.actionExecution = "exec" in node ? "shell" : "function";
   }