@osolmaz/pi-workflows 0.3.0 → 0.5.0

package/src/host/runner.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { builtinWorkflowCatalog } from "../builtins/catalog.js";
 import {
   ControllerManager,
   loadDiscoveredControllers,
@@ -17,8 +18,9 @@ import {
   isClaimLostError,
   WorkflowSourceChangedError,
 } from "../workflows/errors.js";
-import { hashWorkflowSource, loadWorkflowFile, resolveWorkflowRef } from "../workflows/loader.js";
-import { WorkflowRunStore } from "../workflows/store.js";
+import { resolveWorkflowRef, resolveWorkflowSource } from "../workflows/loader.js";
+import { migrateLegacyWorkflowSources } from "../workflows/migrate-sources.js";
+import { WorkflowRunStore, readRunBundle } from "../workflows/store.js";
 import type { WorkflowDefinition } from "../workflows/types.js";
 import { HostProcessRegistry } from "./processes.js";
 import { RpcStepExecutor } from "./rpc-executor.js";
@@ -59,6 +61,7 @@ export class WorkflowHost {
   private manager: ControllerManager | null = null;
   private pollTimer: ReturnType<typeof setInterval> | null = null;
   private readonly activeRuns = new Map<string, Promise<void>>();
+  private readonly migrationBlockedRuns = new Set<string>();
   private readonly schedulerExecutors = new Map<WorkflowEngine, RpcStepExecutor>();
   /** Runs whose resume refused (edited source); skipped until a host restart. */
   private readonly skippedRuns = new Set<string>();
@@ -94,14 +97,27 @@ export class WorkflowHost {
       this.log(`reaped ${reaped.length} orphaned headless session(s): ${reaped.join(", ")}`);
     }
 
+    const migration = await migrateLegacyWorkflowSources({
+      catalog: builtinWorkflowCatalog,
+      store: this.childRunStore,
+      queue: this.store,
+    });
+    for (const blocked of migration.blocked) {
+      this.migrationBlockedRuns.add(blocked.runId);
+      this.log(`run ${blocked.runId} parked: ${blocked.reason}`);
+    }
+
     const definitions = await loadDiscoveredControllers({ cwd: this.options.cwd });
     if (definitions.length > 0) {
       const scheduler = new WorkflowEngineScheduler({
         store: this.childRunStore,
         resolveWorkflow: async (name) => {
-          const resolved = await resolveWorkflowRef(name, { cwd: this.options.cwd });
-          const workflow = await loadWorkflowFile(resolved.path);
-          return { workflow };
+          const resolved = await resolveWorkflowRef(
+            name,
+            { cwd: this.options.cwd },
+            builtinWorkflowCatalog,
+          );
+          return { workflow: resolved.definition, workflowSource: resolved.source };
         },
         createEngine: () => {
           const executor = new RpcStepExecutor({
@@ -176,7 +192,7 @@ export class WorkflowHost {
         runnerId: this.runnerId,
         claimToken: randomUUID(),
         leaseMs: RUN_CLAIM_LEASE_MS,
-        excludeRunIds: [...this.skippedRuns],
+        excludeRunIds: [...this.skippedRuns, ...this.migrationBlockedRuns],
       });
     } catch (error) {
       // Store contention or corruption must not kill the host's loop.
@@ -195,13 +211,36 @@ export class WorkflowHost {
   private async runClaimed(record: WorkflowRunQueueRecord): Promise<void> {
     const claimToken = record.claimToken as string;
     const runId = record.runId;
-    this.log(`resuming ${record.workflowRef} run ${runId}`);
+    this.log(`resuming ${record.workflowName} run ${runId}`);
     let workflow: WorkflowDefinition;
-    let workflowHash: string;
+    let workflowSource: import("../workflows/types.js").WorkflowSource;
     try {
-      workflow = await loadWorkflowFile(record.workflowPath);
-      workflowHash = await hashWorkflowSource(record.workflowPath);
+      const bundle = await readRunBundle(this.childRunStore.runDirFor(runId));
+      if (bundle?.state.workflowSource === undefined) {
+        throw new Error(`Workflow run ${runId} has no canonical workflow source`);
+      }
+      workflow = await resolveWorkflowSource(
+        bundle.state.workflowSource,
+        builtinWorkflowCatalog,
+        runId,
+      );
+      workflowSource = bundle.state.workflowSource;
     } catch (error) {
+      if (error instanceof WorkflowSourceChangedError) {
+        try {
+          this.store.parkWorkflowRun({ runId, claimToken });
+        } catch {
+          // Best-effort.
+        }
+        this.skippedRuns.add(runId);
+        this.recordEvent(runId, record.workflowName, "parked", {
+          reason: "workflow source changed",
+        });
+        this.log(
+          `run ${runId} skipped: workflow source changed; install the matching package revision, then restart the host`,
+        );
+        return;
+      }
       await this.failUnresumable(record, claimToken, errorMessage(error));
       return;
     }
@@ -230,7 +269,26 @@ export class WorkflowHost {
       ...(this.options.piArgs !== undefined ? { piArgs: this.options.piArgs } : {}),
       ...(this.options.env !== undefined ? { env: this.options.env } : {}),
     });
-    const engine = new WorkflowEngine({ executor, store: fencedStore });
+    const engine = new WorkflowEngine({
+      executor,
+      store: fencedStore,
+      notificationSink: {
+        notify: (request) => {
+          fence();
+          if (record.originSessionId === null) {
+            throw new Error(`Workflow run ${request.runId} has no origin session`);
+          }
+          const notification = store.enqueueWorkflowNotification({
+            ...request,
+            targetSessionId: record.originSessionId,
+          });
+          return {
+            notificationId: notification.notificationId,
+            targetSessionId: notification.targetSessionId,
+          };
+        },
+      },
+    });
     const parkEngine = () => engine.park();
     this.parkedEngines.push(parkEngine);
 
@@ -245,23 +303,23 @@ export class WorkflowHost {
     }, RUN_CLAIM_RENEW_MS);
     renewTimer.unref?.();
 
-    this.recordEvent(runId, record.workflowRef, "resumed", { runnerId: this.runnerId });
+    this.recordEvent(runId, record.workflowName, "resumed", { runnerId: this.runnerId });
     try {
-      const result = await engine.resumeRun(workflow, runId, { workflowHash });
+      const result = await engine.resumeRun(workflow, runId, { workflowSource });
       clearInterval(renewTimer);
       if (result.state.status === "running") {
         // Parked again mid-drain: leave it claimable for the next runner.
         this.store.parkWorkflowRun({ runId, claimToken });
-        this.recordEvent(runId, record.workflowRef, "parked", {});
-        this.log(`parked ${record.workflowRef} run ${runId}`);
+        this.recordEvent(runId, record.workflowName, "parked", {});
+        this.log(`parked ${record.workflowName} run ${runId}`);
         return;
       }
       this.store.completeWorkflowRun({ runId, claimToken });
-      this.recordEvent(runId, record.workflowRef, result.state.status, {
+      this.recordEvent(runId, record.workflowName, result.state.status, {
         ...(result.state.error !== undefined ? { error: result.state.error } : {}),
         ...(result.state.waitingOn !== undefined ? { waitingOn: result.state.waitingOn } : {}),
       });
-      this.log(`${record.workflowRef} run ${runId} ${result.state.status}`);
+      this.log(`${record.workflowName} run ${runId} ${result.state.status}`);
     } catch (error) {
       clearInterval(renewTimer);
       if (isClaimLostError(error)) {
@@ -277,7 +335,7 @@ export class WorkflowHost {
           // Best-effort.
         }
         this.skippedRuns.add(runId);
-        this.recordEvent(runId, record.workflowRef, "parked", {
+        this.recordEvent(runId, record.workflowName, "parked", {
           reason: "workflow source changed",
         });
         this.log(
@@ -327,9 +385,9 @@ export class WorkflowHost {
     // no-op (the bundle was already waiting or completed), so the feed
     // stays truthful for sessions syncing from it.
     if (actualStatus !== undefined && actualStatus !== "failed") {
-      this.recordEvent(record.runId, record.workflowRef, actualStatus, {});
+      this.recordEvent(record.runId, record.workflowName, actualStatus, {});
     } else {
-      this.recordEvent(record.runId, record.workflowRef, "failed", { error: message });
+      this.recordEvent(record.runId, record.workflowName, "failed", { error: message });
     }
     this.log(`run ${record.runId} cannot resume: ${message}`);
   }

package/src/render/graph-render.ts

@@ -79,6 +79,7 @@ const CARD_DYNAMIC_RESERVE = "↻ 100  ◷ 9999d 23h 59m 59s";
 const NODE_TYPE_GLYPHS: Record<string, string> = {
   agent: "●",
   compute: "ƒ",
+  notify: "✉",
   action: "⚙",
   checkpoint: "◆",
 };
@@ -87,6 +88,8 @@ function nodeTypeStyle(nodeType: string): CanvasStyle {
   switch (nodeType) {
     case "agent":
     case "compute":
+    case "notify":
+      return nodeType === "notify" ? "action" : nodeType;
     case "action":
     case "checkpoint":
       return nodeType;

package/src/workflows/catalog.ts

@@ -0,0 +1,135 @@
+import { isWorkflowDefinition } from "./definition.js";
+import { WorkflowSourceChangedError } from "./errors.js";
+import type { WorkflowDefinition, WorkflowSource } from "./types.js";
+
+const BUILTIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const REVISION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+export type LegacyBuiltinSource = {
+  workflowHash: string;
+  revision: string;
+  pathSuffixes: readonly string[];
+};
+
+export type BuiltinWorkflowRegistration = {
+  id: string;
+  revision: string;
+  definition: WorkflowDefinition;
+  legacySources?: LegacyBuiltinSource[];
+};
+
+export type BuiltinWorkflowEntry = Readonly<{
+  id: string;
+  ref: string;
+  revision: string;
+  definition: WorkflowDefinition;
+  legacySources: readonly LegacyBuiltinSource[];
+}>;
+
+export type LegacyBuiltinMatch = {
+  entry: BuiltinWorkflowEntry;
+  revision: string;
+};
+
+/** Process-local catalog of package-provided workflow definitions. */
+export class BuiltinWorkflowCatalog {
+  private readonly byId = new Map<string, BuiltinWorkflowEntry>();
+  private readonly byName = new Map<string, BuiltinWorkflowEntry>();
+
+  constructor(registrations: BuiltinWorkflowRegistration[]) {
+    for (const registration of registrations) {
+      if (!BUILTIN_ID_PATTERN.test(registration.id)) {
+        throw new Error(`Invalid built-in workflow id: ${JSON.stringify(registration.id)}`);
+      }
+      if (!REVISION_PATTERN.test(registration.revision)) {
+        throw new Error(
+          `Invalid built-in workflow revision: ${JSON.stringify(registration.revision)}`,
+        );
+      }
+      if (!isWorkflowDefinition(registration.definition)) {
+        throw new Error(`Built-in workflow ${registration.id} is not defined with defineWorkflow`);
+      }
+      if (this.byId.has(registration.id)) {
+        throw new Error(`Duplicate built-in workflow id: ${registration.id}`);
+      }
+      if (this.byName.has(registration.definition.name)) {
+        throw new Error(`Duplicate built-in workflow name: ${registration.definition.name}`);
+      }
+      const entry: BuiltinWorkflowEntry = Object.freeze({
+        id: registration.id,
+        ref: `builtin:${registration.id}`,
+        revision: registration.revision,
+        definition: registration.definition,
+        legacySources: Object.freeze(
+          (registration.legacySources ?? []).map((legacy) =>
+            Object.freeze({ ...legacy, pathSuffixes: Object.freeze([...legacy.pathSuffixes]) }),
+          ),
+        ),
+      });
+      this.byId.set(entry.id, entry);
+      this.byName.set(entry.definition.name, entry);
+    }
+  }
+
+  list(): BuiltinWorkflowEntry[] {
+    return [...this.byId.values()];
+  }
+
+  get(id: string): BuiltinWorkflowEntry | undefined {
+    return this.byId.get(id);
+  }
+
+  getByName(name: string): BuiltinWorkflowEntry | undefined {
+    return this.byName.get(name);
+  }
+
+  resolve(
+    source: WorkflowSource,
+    runId = `builtin:${source.kind === "builtin" ? source.id : "unknown"}`,
+  ): WorkflowDefinition {
+    if (source.kind !== "builtin") {
+      throw new Error("A file workflow source cannot be resolved by the built-in catalog");
+    }
+    const entry = this.byId.get(source.id);
+    if (entry === undefined) {
+      throw new Error(`Unknown built-in workflow: ${source.id}`);
+    }
+    if (entry.revision !== source.revision) {
+      throw new WorkflowSourceChangedError(runId);
+    }
+    return entry.definition;
+  }
+
+  matchLegacy(options: {
+    workflowName: string;
+    workflowPath: string;
+    workflowHash: string;
+  }): LegacyBuiltinMatch | undefined {
+    const entry = this.legacyPathEntry(options);
+    if (entry === undefined) return undefined;
+    const workflowPath = options.workflowPath.replaceAll("\\", "/");
+    const legacy = entry.legacySources.find(
+      (candidate) =>
+        candidate.workflowHash === options.workflowHash &&
+        candidate.pathSuffixes.some((suffix) =>
+          workflowPath.endsWith(suffix.replaceAll("\\", "/")),
+        ),
+    );
+    return legacy === undefined ? undefined : { entry, revision: legacy.revision };
+  }
+
+  /** Identify a registered old built-in path without accepting its revision. */
+  legacyPathEntry(options: {
+    workflowName: string;
+    workflowPath: string;
+  }): BuiltinWorkflowEntry | undefined {
+    const entry = this.byName.get(options.workflowName);
+    if (entry === undefined) return undefined;
+    const workflowPath = options.workflowPath.replaceAll("\\", "/");
+    return entry.legacySources.some((legacy) =>
+      legacy.pathSuffixes.some((suffix) => workflowPath.endsWith(suffix.replaceAll("\\", "/"))),
+    )
+      ? entry
+      : undefined;
+  }
+}

package/src/workflows/definition.ts

@@ -3,6 +3,7 @@ import {
   assertValidActionNode,
   assertValidCheckpointNode,
   assertValidComputeNode,
+  assertValidNotifyNode,
   assertValidShellActionNode,
   assertValidWorkflowDefinitionShape,
 } from "./schema.js";
@@ -12,6 +13,7 @@ import type {
   CheckpointNodeDefinition,
   ComputeNodeDefinition,
   FunctionActionNodeDefinition,
+  NotifyNodeDefinition,
   ShellActionNodeDefinition,
   WorkflowDefinition,
 } from "./types.js";
@@ -62,6 +64,15 @@ export function compute(
   return node;
 }
 
+export function notify(definition: Omit<NotifyNodeDefinition, "nodeType">): NotifyNodeDefinition {
+  const node: NotifyNodeDefinition = {
+    nodeType: "notify",
+    ...definition,
+  };
+  assertValidNotifyNode(node);
+  return node;
+}
+
 export function action(
   definition: Omit<FunctionActionNodeDefinition, "nodeType">,
 ): FunctionActionNodeDefinition;