@osolmaz/pi-workflows 0.3.0 → 0.5.0

package/src/workflows/migrate-sources.ts

@@ -0,0 +1,174 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { BuiltinWorkflowCatalog } from "./catalog.js";
+import { WorkflowRunStore, listRunBundles } from "./store.js";
+import type { WorkflowRunState, WorkflowSource } from "./types.js";
+
+export type LegacySourceMigrationQueue = {
+  repairCanonicalWorkflowSourceRun(options: {
+    runId: string;
+    workflowName: string;
+    workflowSourceRef: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+  }): "unchanged" | "claimed" | false;
+  claimLegacyWorkflowSourceRun(options: {
+    runId: string;
+    workflowName: string;
+    oldWorkflowPath: string;
+    workflowSourceRef: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+  }): boolean;
+  parkWorkflowRun(options: { runId: string; claimToken: string }): boolean;
+  getWorkflowRun(runId: string): { status: "claimed" | "parked" | "done" } | undefined;
+  setWorkflowRunOriginSession?(runId: string, originSessionId: string): boolean;
+};
+
+const MIGRATION_LEASE_MS = 30_000;
+
+export type LegacySourceMigrationResult = {
+  migratedRunIds: string[];
+  blocked: { runId: string; reason: string }[];
+};
+
+/** One bounded migration for nonterminal runs created before canonical sources. */
+export async function migrateLegacyWorkflowSources(options: {
+  catalog: BuiltinWorkflowCatalog;
+  store?: WorkflowRunStore;
+  queue?: LegacySourceMigrationQueue;
+}): Promise<LegacySourceMigrationResult> {
+  const store = options.store ?? new WorkflowRunStore();
+  const result: LegacySourceMigrationResult = { migratedRunIds: [], blocked: [] };
+  for (const bundle of await listRunBundles(store.outputRoot)) {
+    const state = bundle.state;
+    if (state.status !== "running" && state.status !== "waiting") continue;
+    if (
+      options.queue?.setWorkflowRunOriginSession !== undefined &&
+      bundle.sessionBinding !== null
+    ) {
+      options.queue.setWorkflowRunOriginSession(state.runId, bundle.sessionBinding.piSessionId);
+    }
+    if (state.workflowSource !== undefined) {
+      if (options.queue === undefined) continue;
+      const claimToken = randomUUID();
+      const repaired = options.queue.repairCanonicalWorkflowSourceRun({
+        runId: state.runId,
+        workflowName: state.workflowName,
+        workflowSourceRef: sourceRef(state.workflowSource),
+        runnerId: `source-migration-${process.pid}`,
+        claimToken,
+        leaseMs: MIGRATION_LEASE_MS,
+      });
+      if (repaired === false) {
+        // Another runner can own a canonical run during startup. Its source is
+        // already safe; the normal queue lease will make it claimable later.
+      } else if (
+        repaired === "claimed" &&
+        !options.queue.parkWorkflowRun({ runId: state.runId, claimToken })
+      ) {
+        result.blocked.push({
+          runId: state.runId,
+          reason: "canonical queue repair could not release its claim",
+        });
+      }
+      continue;
+    }
+    if (state.workflowPath === undefined || state.workflowHash === undefined) {
+      result.blocked.push({ runId: state.runId, reason: "legacy workflow identity is incomplete" });
+      continue;
+    }
+    const legacyPath = {
+      workflowName: state.workflowName,
+      workflowPath: state.workflowPath,
+    };
+    const pathEntry = options.catalog.legacyPathEntry(legacyPath);
+    let workflowSource: WorkflowSource;
+    let workflowSourceRef: string;
+    if (pathEntry === undefined) {
+      workflowSource = {
+        kind: "file",
+        path: path.resolve(state.workflowPath),
+        hash: state.workflowHash,
+      };
+      workflowSourceRef = workflowSource.path;
+    } else {
+      const legacy = options.catalog.matchLegacy({
+        ...legacyPath,
+        workflowHash: state.workflowHash,
+      });
+      if (legacy === undefined) {
+        const reason = `legacy built-in ${pathEntry.id} has an unknown source revision`;
+        result.blocked.push({ runId: state.runId, reason });
+        continue;
+      }
+      workflowSource = {
+        kind: "builtin",
+        id: legacy.entry.id,
+        revision: legacy.revision,
+      };
+      workflowSourceRef = legacy.entry.ref;
+    }
+    const claimToken = randomUUID();
+    const queueIsDone = options.queue?.getWorkflowRun(state.runId)?.status === "done";
+    if (
+      options.queue !== undefined &&
+      !queueIsDone &&
+      !options.queue.claimLegacyWorkflowSourceRun({
+        runId: state.runId,
+        workflowName: state.workflowName,
+        oldWorkflowPath: state.workflowPath,
+        workflowSourceRef,
+        runnerId: `source-migration-${process.pid}`,
+        claimToken,
+        leaseMs: MIGRATION_LEASE_MS,
+      })
+    ) {
+      result.blocked.push({
+        runId: state.runId,
+        reason: "matching queue row is active or unavailable",
+      });
+      continue;
+    }
+    const migrated: WorkflowRunState = {
+      ...state,
+      workflowSource,
+    };
+    delete migrated.workflowPath;
+    delete migrated.workflowHash;
+    const migratedManifest = {
+      ...bundle.manifest,
+      workflowSource: migrated.workflowSource,
+    };
+    delete (migratedManifest as typeof migratedManifest & { workflowPath?: string }).workflowPath;
+    // State is the migration commit point. Queue and manifest updates are
+    // idempotent, so a crash before this write can safely retry.
+    await writeJsonAtomic(path.join(bundle.runDir, "manifest.json"), migratedManifest);
+    await writeJsonAtomic(path.join(bundle.runDir, "state.json"), migrated);
+    if (
+      options.queue !== undefined &&
+      !queueIsDone &&
+      !options.queue.parkWorkflowRun({ runId: state.runId, claimToken })
+    ) {
+      result.blocked.push({
+        runId: state.runId,
+        reason: "migration completed but its queue claim could not be released",
+      });
+    }
+    result.migratedRunIds.push(state.runId);
+  }
+  return result;
+}
+
+function sourceRef(source: WorkflowSource): string {
+  return source.kind === "builtin" ? `builtin:${source.id}` : source.path;
+}
+
+async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
+  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.source-migration.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await fs.rename(tempPath, filePath);
+}

package/src/workflows/schema.ts

@@ -4,6 +4,7 @@ import type {
   CheckpointNodeDefinition,
   ComputeNodeDefinition,
   FunctionActionNodeDefinition,
+  NotifyNodeDefinition,
   ShellActionNodeDefinition,
   WorkflowDefinition,
   WorkflowEdge,
@@ -34,9 +35,10 @@ function assertOptionalFunction(value: unknown, description: string): void {
 function assertCommonNodeFields(node: WorkflowNodeDefinition, nodeId: string): void {
   if (
     node.timeoutMs !== undefined &&
+    typeof node.timeoutMs !== "function" &&
     (typeof node.timeoutMs !== "number" || !Number.isFinite(node.timeoutMs) || node.timeoutMs <= 0)
   ) {
-    fail(`node ${nodeId} timeoutMs must be a finite positive number`);
+    fail(`node ${nodeId} timeoutMs must be a finite positive number or function`);
   }
   if (node.statusDetail !== undefined && typeof node.statusDetail !== "string") {
     fail(`node ${nodeId} statusDetail must be a string`);
@@ -61,6 +63,16 @@ export function assertValidComputeNode(node: ComputeNodeDefinition, nodeId = "co
   assertCommonNodeFields(node, nodeId);
 }
 
+export function assertValidNotifyNode(node: NotifyNodeDefinition, nodeId = "notify"): void {
+  if (typeof node.message !== "function") {
+    fail(`node ${nodeId} requires a message function`);
+  }
+  if (node.kind !== undefined && node.kind !== "progress" && node.kind !== "final") {
+    fail(`node ${nodeId} kind must be progress or final`);
+  }
+  assertCommonNodeFields(node, nodeId);
+}
+
 export function assertValidActionNode(node: ActionNodeDefinition, nodeId = "action"): void {
   // Dispatch discriminates with `"exec" in node`, so validation must use the
   // same property semantics: a present-but-invalid `exec` is an error even
@@ -111,6 +123,9 @@ function assertValidNode(node: WorkflowNodeDefinition, nodeId: string): void {
     case "compute":
       assertValidComputeNode(node, nodeId);
       return;
+    case "notify":
+      assertValidNotifyNode(node, nodeId);
+      return;
     case "action":
       assertValidActionNode(node, nodeId);
       return;

package/src/workflows/store.ts

@@ -1284,7 +1284,7 @@ function createManifest(
     runId: state.runId,
     workflowName: state.workflowName,
     ...(state.runTitle !== undefined ? { runTitle: state.runTitle } : {}),
-    ...(state.workflowPath !== undefined ? { workflowPath: state.workflowPath } : {}),
+    ...(state.workflowSource !== undefined ? { workflowSource: state.workflowSource } : {}),
     startedAt: state.startedAt,
     ...(state.finishedAt !== undefined ? { finishedAt: state.finishedAt } : {}),
     status: state.status,
@@ -1317,12 +1317,15 @@ export function createDefinitionSnapshot(workflow: WorkflowDefinition): Workflow
 function snapshotNode(node: WorkflowNodeDefinition): WorkflowNodeSnapshot {
   const common: WorkflowNodeSnapshot = {
     nodeType: node.nodeType,
-    ...(node.timeoutMs !== undefined ? { timeoutMs: node.timeoutMs } : {}),
+    ...(typeof node.timeoutMs === "number" ? { timeoutMs: node.timeoutMs } : {}),
     ...(node.statusDetail !== undefined ? { statusDetail: node.statusDetail } : {}),
   };
   if (node.nodeType === "agent" && node.expectedOutput !== undefined) {
     common.expectedOutput = node.expectedOutput;
   }
+  if (node.nodeType === "notify") {
+    common.summary = node.kind ?? "progress";
+  }
   if (node.nodeType === "checkpoint" && node.summary !== undefined) {
     common.summary = node.summary;
   }

package/src/workflows/types.ts

@@ -20,8 +20,11 @@ export type WorkflowNodeContext<TInput = unknown> = {
 };
 
 export type WorkflowNodeCommon = {
-  /** Per-node timeout. Falls back to the engine default (15 minutes). */
-  timeoutMs?: number;
+  /**
+   * Per-node timeout or a callback that derives it from the run context.
+   * Falls back to the engine default (15 minutes).
+   */
+  timeoutMs?: number | ((context: WorkflowNodeContext) => MaybePromise<number>);
   /** Short human-readable label shown in the viewer while the node runs. */
   statusDetail?: string;
 };
@@ -65,6 +68,13 @@ export type ComputeNodeDefinition = WorkflowNodeCommon & {
   run: (context: WorkflowNodeContext) => MaybePromise<unknown>;
 };
 
+/** A durable user-facing message addressed by the runtime to the run's origin session. */
+export type NotifyNodeDefinition = WorkflowNodeCommon & {
+  nodeType: "notify";
+  message: (context: WorkflowNodeContext) => MaybePromise<string>;
+  kind?: "progress" | "final";
+};
+
 /** A deterministic runtime-owned step implemented as a local function. */
 export type FunctionActionNodeDefinition = WorkflowNodeCommon & {
   nodeType: "action";
@@ -118,6 +128,7 @@ export type CheckpointNodeDefinition = WorkflowNodeCommon & {
 export type WorkflowNodeDefinition =
   | AgentNodeDefinition
   | ComputeNodeDefinition
+  | NotifyNodeDefinition
   | ActionNodeDefinition
   | CheckpointNodeDefinition;
 
@@ -230,6 +241,10 @@ export type WorkflowRunStatus =
   | "timed_out"
   | "cancelled";
 
+export type WorkflowSource =
+  | { kind: "builtin"; id: string; revision: string }
+  | { kind: "file"; path: string; hash: string };
+
 export type WorkflowRunState = {
   schema: "pi-workflows.run-state.v1";
   /**
@@ -249,8 +264,10 @@ export type WorkflowRunState = {
    */
   carriedStepCount?: number;
   runTitle?: string;
+  /** Stable built-in identity or immutable file source used by this run. */
+  workflowSource?: WorkflowSource;
+  /** Legacy fields accepted only by the bounded built-in migration. */
   workflowPath?: string;
-  /** SHA-256 of the workflow source at run start; resume refuses mismatches. */
   workflowHash?: string;
   startedAt: string;
   finishedAt?: string;
@@ -377,7 +394,7 @@ export type WorkflowRunManifest = {
   runId: string;
   workflowName: string;
   runTitle?: string;
-  workflowPath?: string;
+  workflowSource?: WorkflowSource;
   startedAt: string;
   finishedAt?: string;
   status: WorkflowRunStatus;
@@ -435,8 +452,30 @@ export interface AgentStepExecutor {
   runAgentStep(request: AgentStepRequest, signal: AbortSignal): Promise<AgentStepSubmission>;
 }
 
+export type WorkflowNotificationRequest = {
+  runId: string;
+  workflowName: string;
+  nodeId: string;
+  attemptId: string;
+  /** Stable one-based occurrence of this notify node within the run. */
+  notificationIndex: number;
+  kind: "progress" | "final";
+  content: string;
+};
+
+export type WorkflowNotificationReceipt = {
+  notificationId: string;
+  targetSessionId: string;
+};
+
+export interface WorkflowNotificationSink {
+  notify(request: WorkflowNotificationRequest): MaybePromise<WorkflowNotificationReceipt>;
+}
+
 export type WorkflowEngineOptions = {
   executor: AgentStepExecutor;
+  /** Durable destination for notify nodes. Required when a workflow uses one. */
+  notificationSink?: WorkflowNotificationSink;
   /** Root directory for run bundles. Defaults to `~/.pi/agent/workflows/runs`. */
   outputRoot?: string;
   /**