@osolmaz/pi-workflows 0.3.0 → 0.5.0

package/src/workflows/engine.ts

@@ -30,8 +30,10 @@ import type {
   WorkflowNodeDefinition,
   WorkflowNodeOutcome,
   WorkflowNodeResult,
+  WorkflowNotificationSink,
   WorkflowRunResult,
   WorkflowRunState,
+  WorkflowSource,
   WorkflowStepRecord,
   WorkflowTraceEventDraft,
 } from "./types.js";
@@ -39,6 +41,7 @@ import type {
 const DEFAULT_NODE_TIMEOUT_MS = 15 * 60_000;
 const DEFAULT_MAX_STEPS = 100;
 const TITLE_TIMEOUT_MS = 30_000;
+const TIMEOUT_RESOLUTION_TIMEOUT_MS = 30_000;
 // Covers the shell SIGTERM → SIGKILL escalation (1s) plus stdio close.
 const ABORT_CLEANUP_GRACE_MS = 2_000;
 
@@ -72,6 +75,7 @@ type NodeAttempt = {
  */
 export class WorkflowEngine {
   private readonly executor: AgentStepExecutor;
+  private readonly notificationSink: WorkflowNotificationSink | undefined;
   private readonly store: WorkflowRunStore;
   private readonly defaultNodeTimeoutMs: number;
   private readonly maxSteps: number;
@@ -86,6 +90,7 @@ export class WorkflowEngine {
 
   constructor(options: WorkflowEngineOptions) {
     this.executor = options.executor;
+    this.notificationSink = options.notificationSink;
     this.store = options.store ?? new WorkflowRunStore(options.outputRoot);
     this.defaultNodeTimeoutMs = options.defaultNodeTimeoutMs ?? DEFAULT_NODE_TIMEOUT_MS;
     this.maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
@@ -140,7 +145,7 @@ export class WorkflowEngine {
   async run(
     workflow: WorkflowDefinition,
     input: unknown,
-    options: { workflowPath?: string; workflowHash?: string; runId?: string } = {},
+    options: { workflowSource?: WorkflowSource; runId?: string } = {},
   ): Promise<WorkflowRunResult> {
     validateWorkflowDefinition(workflow);
     // Fail before any bundle exists so bad input cannot leave a partial run
@@ -157,8 +162,7 @@ export class WorkflowEngine {
     const state = await this.createRunState(
       workflow,
       normalizedInput,
-      options.workflowPath,
-      options.workflowHash,
+      options.workflowSource,
       options.runId,
     );
     const runDir = await this.store.initializeRunBundle(workflow, state);
@@ -196,7 +200,7 @@ export class WorkflowEngine {
   async resumeRun(
     workflow: WorkflowDefinition,
     runId: string,
-    options: { workflowHash?: string; force?: boolean } = {},
+    options: { workflowSource?: WorkflowSource; force?: boolean } = {},
   ): Promise<WorkflowRunResult> {
     validateWorkflowDefinition(workflow);
     // Reset before any await: a park or cancel landing during preparation
@@ -207,11 +211,8 @@ export class WorkflowEngine {
     const bundle = await this.store.prepareRunResume(runId);
     const { runDir } = bundle;
     const state = bundle.state;
-    const hashMismatch =
-      state.workflowHash !== undefined &&
-      options.workflowHash !== undefined &&
-      state.workflowHash !== options.workflowHash;
-    if (hashMismatch && options.force !== true) {
+    const sourceMismatch = workflowSourceMismatch(state, options.workflowSource);
+    if (sourceMismatch && options.force !== true) {
       throw new WorkflowSourceChangedError(runId);
     }
 
@@ -230,7 +231,7 @@ export class WorkflowEngine {
       payload: {
         ...(point.nodeId !== null ? { resumeAt: point.nodeId } : {}),
         replayedSteps: state.steps.length,
-        ...(hashMismatch ? { workflowHashMismatch: true, forced: true } : {}),
+        ...(sourceMismatch ? { workflowSourceMismatch: true, forced: true } : {}),
       },
     });
     await this.onRunStarted?.(runDir, state);
@@ -283,7 +284,7 @@ export class WorkflowEngine {
     workflow: WorkflowDefinition,
     parentRunId: string,
     input: unknown,
-    options: { workflowPath?: string; workflowHash?: string; runId?: string; force?: boolean } = {},
+    options: { workflowSource?: WorkflowSource; runId?: string; force?: boolean } = {},
   ): Promise<WorkflowRunResult> {
     validateWorkflowDefinition(workflow);
     this.cancelled = false;
@@ -298,11 +299,8 @@ export class WorkflowEngine {
         `Cannot continue workflow run ${parentRunId} with status ${parent.state.status}`,
       );
     }
-    const hashMismatch =
-      parent.state.workflowHash !== undefined &&
-      options.workflowHash !== undefined &&
-      parent.state.workflowHash !== options.workflowHash;
-    if (hashMismatch && options.force !== true) {
+    const sourceMismatch = workflowSourceMismatch(parent.state, options.workflowSource);
+    if (sourceMismatch && options.force !== true) {
       throw new WorkflowSourceChangedError(parentRunId);
     }
 
@@ -315,8 +313,7 @@ export class WorkflowEngine {
     const state = await this.createRunState(
       workflow,
       normalizedInput,
-      options.workflowPath,
-      options.workflowHash,
+      options.workflowSource,
       options.runId,
     );
     state.parentRunId = parentRunId;
@@ -477,8 +474,7 @@ export class WorkflowEngine {
   private async createRunState(
     workflow: WorkflowDefinition,
     input: unknown,
-    workflowPath: string | undefined,
-    workflowHash: string | undefined,
+    workflowSource: WorkflowSource | undefined,
     runId: string | undefined,
   ): Promise<WorkflowRunState> {
     const now = new Date().toISOString();
@@ -488,8 +484,7 @@ export class WorkflowEngine {
       runId: runId ?? createRunId(workflow.name),
       workflowName: workflow.name,
       ...(await this.resolveTitleBounded(workflow, input)),
-      ...(workflowPath !== undefined ? { workflowPath } : {}),
-      ...(workflowHash !== undefined ? { workflowHash } : {}),
+      ...(workflowSource !== undefined ? { workflowSource } : {}),
       startedAt: now,
       updatedAt: now,
       status: "running",
@@ -758,36 +753,43 @@ export class WorkflowEngine {
     node: WorkflowNodeDefinition,
     meta: NodeExecutionMeta,
   ): Promise<NodeExecution> {
-    const timeoutMs = node.timeoutMs ?? this.defaultNodeTimeoutMs;
     const abort = new AbortController();
+    const context = this.createNodeContext(state, abort.signal);
+    let timer: NodeJS.Timeout | undefined;
+    let dispatchSettled: Promise<void> | undefined;
     this.activeAbort = abort;
-    if (this.parked) {
-      // A park that landed during the node_started persist must not let the
-      // node dispatch: its discarded side effects would rerun on resume.
-      throw new RunParkedError();
-    }
-    if (this.cancelled) {
-      throw new CancelledError();
-    }
-
-    const timer = setTimeout(() => {
-      abort.abort(new TimeoutError(timeoutMs));
-    }, timeoutMs);
-    const dispatched = this.dispatchNode(
-      workflow,
-      state,
-      runDir,
-      nodeId,
-      attemptId,
-      node,
-      abort.signal,
-      meta,
-    );
-    const dispatchSettled = dispatched.then(
-      () => undefined,
-      () => undefined,
-    );
     try {
+      if (this.parked) {
+        // A park that landed during the node_started persist must not let the
+        // node dispatch: its discarded side effects would rerun on resume.
+        throw new RunParkedError();
+      }
+      if (this.cancelled) {
+        throw new CancelledError();
+      }
+
+      const timeoutMs = await this.resolveNodeTimeout(node, context, abort);
+      if (abort.signal.aborted) {
+        throw abortError(abort.signal);
+      }
+      timer = setTimeout(() => {
+        abort.abort(new TimeoutError(timeoutMs));
+      }, timeoutMs);
+      const dispatched = this.dispatchNode(
+        workflow,
+        state,
+        runDir,
+        nodeId,
+        attemptId,
+        node,
+        context,
+        abort.signal,
+        meta,
+      );
+      dispatchSettled = dispatched.then(
+        () => undefined,
+        () => undefined,
+      );
       // Race the dispatch against the abort signal so timeouts and cancel
       // take effect even for node callbacks that never observe the signal.
       const execution = await Promise.race([dispatched, abortRejection(abort.signal)]);
@@ -799,7 +801,7 @@ export class WorkflowEngine {
       assertJsonSerializable(execution.output, `Node ${nodeId} output`);
       return execution;
     } catch (error) {
-      if (node.nodeType === "action" && "exec" in node) {
+      if (node.nodeType === "action" && "exec" in node && dispatchSettled !== undefined) {
         // Give the killed shell command a short grace period to close so its
         // action receipt lands in `meta` before the failed attempt persists.
         await Promise.race([
@@ -809,9 +811,37 @@ export class WorkflowEngine {
       }
       const reason: unknown = abort.signal.aborted ? abort.signal.reason : undefined;
       throw reason instanceof TimeoutError || reason instanceof CancelledError ? reason : error;
+    } finally {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      if (this.activeAbort === abort) {
+        this.activeAbort = null;
+      }
+    }
+  }
+
+  private async resolveNodeTimeout(
+    node: WorkflowNodeDefinition,
+    context: WorkflowNodeContext,
+    abort: AbortController,
+  ): Promise<number> {
+    const configured = node.timeoutMs;
+    if (typeof configured !== "function") {
+      return assertValidTimeout(configured ?? this.defaultNodeTimeoutMs);
+    }
+    const timer = setTimeout(
+      () => abort.abort(new TimeoutError(TIMEOUT_RESOLUTION_TIMEOUT_MS)),
+      TIMEOUT_RESOLUTION_TIMEOUT_MS,
+    );
+    try {
+      const resolved = await Promise.race([
+        Promise.resolve(configured(context)),
+        abortRejection(abort.signal),
+      ]);
+      return assertValidTimeout(resolved);
     } finally {
       clearTimeout(timer);
-      this.activeAbort = null;
     }
   }
 
@@ -822,10 +852,10 @@ export class WorkflowEngine {
     nodeId: string,
     attemptId: string,
     node: WorkflowNodeDefinition,
+    context: WorkflowNodeContext,
     signal: AbortSignal,
     meta: NodeExecutionMeta,
   ): Promise<NodeExecution> {
-    const context = this.createNodeContext(state, signal);
     switch (node.nodeType) {
       case "agent":
         return await this.runAgentNode(
@@ -841,6 +871,29 @@ export class WorkflowEngine {
         );
       case "compute":
         return { output: await node.run(context), promptText: null };
+      case "notify": {
+        if (this.notificationSink === undefined) {
+          throw new Error(`Workflow node ${nodeId} requires a notification sink`);
+        }
+        const content = await node.message(context);
+        if (typeof content !== "string" || content.trim().length === 0) {
+          throw new Error(`Workflow node ${nodeId} notification must be a non-empty string`);
+        }
+        const notificationIndex =
+          state.steps.filter(
+            (step) => step.nodeId === nodeId && step.nodeType === "notify" && step.outcome === "ok",
+          ).length + 1;
+        const receipt = await this.notificationSink.notify({
+          runId: state.runId,
+          workflowName: workflow.name,
+          nodeId,
+          attemptId,
+          notificationIndex,
+          kind: node.kind ?? "progress",
+          content: content.trim(),
+        });
+        return { output: receipt, promptText: null };
+      }
       case "action":
         return await this.runActionNode(node, context, signal, meta);
       case "checkpoint":
@@ -1044,7 +1097,13 @@ async function runShellActionNode(
   return { output, promptText: null, action: shellReceipt(result) };
 }
 
-/** Rejects with the abort reason once the signal fires; never resolves. */
+function assertValidTimeout(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error("Node timeoutMs must resolve to a finite positive number");
+  }
+  return value;
+}
+
 /** The error carried by an aborted signal, normalized to an Error. */
 function abortError(signal: AbortSignal): Error {
   const reason: unknown = signal.reason ?? new CancelledError();
@@ -1069,6 +1128,22 @@ function abortRejection(signal: AbortSignal): Promise<never> {
  * Failing here turns a bad callback return value into a normal node failure
  * instead of corrupting the run state.
  */
+function workflowSourceMismatch(
+  state: WorkflowRunState,
+  source: WorkflowSource | undefined,
+): boolean {
+  if (source === undefined) return false;
+  if (state.workflowSource !== undefined) {
+    return !isDeepStrictEqual(state.workflowSource, source);
+  }
+  // Bounded compatibility check for pre-catalog file runs. Startup normally
+  // converts these records with migrateLegacyWorkflowSources first.
+  return (
+    state.workflowHash !== undefined &&
+    (source.kind !== "file" || state.workflowHash !== source.hash)
+  );
+}
+
 function assertJsonSerializable(value: unknown, what: string): void {
   let encoded: string | undefined;
   try {

package/src/workflows/index.ts

@@ -5,6 +5,7 @@ export {
   compute,
   defineWorkflow,
   isWorkflowDefinition,
+  notify,
   shell,
 } from "./definition.js";
 export { decision, decisionEdge, type DecisionDefinition } from "./decision.js";
@@ -21,6 +22,7 @@ export {
   discoverWorkflows,
   loadWorkflowFile,
   resolveWorkflowRef,
+  resolveWorkflowSource,
   workflowFileStem,
   workflowSearchDirs,
   type DiscoveredWorkflow,
@@ -64,6 +66,7 @@ export type {
   ComputeNodeDefinition,
   FunctionActionNodeDefinition,
   MaybePromise,
+  NotifyNodeDefinition,
   ShellActionExecution,
   ShellActionNodeDefinition,
   ShellActionResult,
@@ -78,11 +81,15 @@ export type {
   WorkflowNodeOutcome,
   WorkflowNodeResult,
   WorkflowNodeSnapshot,
+  WorkflowNotificationReceipt,
+  WorkflowNotificationRequest,
+  WorkflowNotificationSink,
   WorkflowPresentationContext,
   WorkflowRunManifest,
   WorkflowRunResult,
   WorkflowRunState,
   WorkflowRunStatus,
+  WorkflowSource,
   WorkflowSessionBinding,
   WorkflowSessionEntryRecord,
   WorkflowStepRecord,

package/src/workflows/loader.ts

@@ -4,14 +4,16 @@ import os from "node:os";
 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 type { WorkflowDefinition } from "./types.js";
+import { WorkflowSourceChangedError } from "./errors.js";
+import type { WorkflowDefinition, WorkflowSource } from "./types.js";
 
 const WORKFLOW_FILE_SUFFIXES = [".workflow.ts", ".workflow.js", ".workflow.mts", ".workflow.mjs"];
 
 export type DiscoveredWorkflow = {
   name: string;
-  path: string;
+  ref: string;
   source: "project" | "global" | "builtin" | "path";
 };
 
@@ -20,23 +22,27 @@ export type WorkflowSearchPaths = {
   homeDir?: string;
 };
 
-/** Directories scanned for workflow files, in precedence order. */
+export type ResolvedWorkflow = {
+  definition: WorkflowDefinition;
+  source: WorkflowSource;
+  sourceKind: DiscoveredWorkflow["source"];
+};
+
+/** Directories scanned for user workflow files, in precedence order. */
 export function workflowSearchDirs(
   options: WorkflowSearchPaths,
-): { dir: string; source: "project" | "global" | "builtin" }[] {
+): { dir: string; source: "project" | "global" }[] {
   const homeDir = options.homeDir ?? os.homedir();
-  const builtinDir = fileURLToPath(new URL("../builtins/", import.meta.url));
   return [
     { dir: path.join(options.cwd, ".pi", "workflows"), source: "project" },
     { dir: path.join(homeDir, ".pi", "agent", "workflows"), source: "global" },
-    { dir: builtinDir, source: "builtin" },
   ];
 }
 
-/** SHA-256 of a workflow source file, recorded in run state for resume pinning. */
+/** SHA-256 of a user workflow source file. */
 export async function hashWorkflowSource(filePath: string): Promise<string> {
   return createHash("sha256")
-    .update(await fs.readFile(filePath))
+    .update(await fs.readFile(path.resolve(filePath)))
     .digest("hex");
 }
 
@@ -50,12 +56,11 @@ export function workflowFileStem(filePath: string): string {
   return suffix ? base.slice(0, -suffix.length) : base;
 }
 
-// Alias the package name to this module's own entry so workflow files can
-// `import { agent } from "@osolmaz/pi-workflows"` whether the engine runs from src
-// (tests, tsx) or from the built dist inside the installed package.
+// 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");
 
-/** Load a workflow module from disk. The default export must be `defineWorkflow(...)`. */
+/** Load a user workflow module from disk. */
 export async function loadWorkflowFile(filePath: string): Promise<WorkflowDefinition> {
   const absolutePath = path.resolve(filePath);
   const jiti = createJiti(pathToFileURL(absolutePath).href, {
@@ -70,22 +75,26 @@ export async function loadWorkflowFile(filePath: string): Promise<WorkflowDefini
   return loaded;
 }
 
-/** Discover named workflows in the project and global workflow directories. */
+/** Discover user workflows first, then unshadowed catalog built-ins. */
 export async function discoverWorkflows(
   options: WorkflowSearchPaths,
+  catalog?: BuiltinWorkflowCatalog,
 ): Promise<DiscoveredWorkflow[]> {
   const discovered: DiscoveredWorkflow[] = [];
   const seenNames = new Set<string>();
   for (const { dir, source } of workflowSearchDirs(options)) {
     for (const filePath of await listWorkflowFiles(dir)) {
       const name = workflowFileStem(filePath);
-      if (seenNames.has(name)) {
-        continue;
-      }
+      if (seenNames.has(name)) continue;
       seenNames.add(name);
-      discovered.push({ name, path: filePath, source });
+      discovered.push({ name, ref: filePath, source });
     }
   }
+  for (const builtin of catalog?.list() ?? []) {
+    if (seenNames.has(builtin.definition.name)) continue;
+    seenNames.add(builtin.definition.name);
+    discovered.push({ name: builtin.definition.name, ref: builtin.ref, source: "builtin" });
+  }
   return discovered;
 }
 
@@ -102,26 +111,61 @@ async function listWorkflowFiles(dir: string): Promise<string[]> {
     .sort();
 }
 
-/**
- * Resolve a `/workflow` argument to a workflow file. Accepts a discovered
- * workflow name or a direct path to a `*.workflow.ts` file.
- */
+/** Resolve a workflow name, stable built-in ref, or direct user file path. */
 export async function resolveWorkflowRef(
   ref: string,
   options: WorkflowSearchPaths,
-): Promise<{ path: string; source: DiscoveredWorkflow["source"] }> {
+  catalog?: BuiltinWorkflowCatalog,
+): Promise<ResolvedWorkflow> {
+  if (ref.startsWith("builtin:")) {
+    const id = ref.slice("builtin:".length);
+    const builtin = catalog?.get(id);
+    if (builtin === undefined) throw new Error(`Unknown built-in workflow ${JSON.stringify(ref)}`);
+    return {
+      definition: builtin.definition,
+      source: { kind: "builtin", id: builtin.id, revision: builtin.revision },
+      sourceKind: "builtin",
+    };
+  }
   if (looksLikePath(ref)) {
     const absolutePath = path.resolve(options.cwd, ref);
     await fs.access(absolutePath);
-    return { path: absolutePath, source: "path" };
+    return {
+      definition: await loadWorkflowFile(absolutePath),
+      source: { kind: "file", path: absolutePath, hash: await hashWorkflowSource(absolutePath) },
+      sourceKind: "path",
+    };
   }
-  const discovered = await discoverWorkflows(options);
+  const discovered = await discoverWorkflows(options, catalog);
   const match = discovered.find((workflow) => workflow.name === ref);
-  if (!match) {
+  if (match === undefined) {
     const available = discovered.map((workflow) => workflow.name).join(", ") || "(none)";
     throw new Error(`Unknown workflow ${JSON.stringify(ref)}. Available workflows: ${available}`);
   }
-  return { path: match.path, source: match.source };
+  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,
+  };
+}
+
+/** Resolve an already persisted canonical source. */
+export async function resolveWorkflowSource(
+  source: WorkflowSource,
+  catalog?: BuiltinWorkflowCatalog,
+  runId = source.kind === "builtin" ? `builtin:${source.id}` : source.path,
+): 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);
+  }
+  const actualHash = await hashWorkflowSource(source.path);
+  if (actualHash !== source.hash) {
+    throw new WorkflowSourceChangedError(runId);
+  }
+  return await loadWorkflowFile(source.path);
 }
 
 function looksLikePath(ref: string): boolean {