@osolmaz/pi-workflows 0.4.0 → 0.5.1

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";
@@ -65,6 +66,7 @@ export type {
   ComputeNodeDefinition,
   FunctionActionNodeDefinition,
   MaybePromise,
+  NotifyNodeDefinition,
   ShellActionExecution,
   ShellActionNodeDefinition,
   ShellActionResult,
@@ -79,6 +81,9 @@ export type {
   WorkflowNodeOutcome,
   WorkflowNodeResult,
   WorkflowNodeSnapshot,
+  WorkflowNotificationReceipt,
+  WorkflowNotificationRequest,
+  WorkflowNotificationSink,
   WorkflowPresentationContext,
   WorkflowRunManifest,
   WorkflowRunResult,

package/src/workflows/migrate-sources.ts

@@ -25,6 +25,7 @@ export type LegacySourceMigrationQueue = {
   }): 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;
@@ -45,6 +46,12 @@ export async function migrateLegacyWorkflowSources(options: {
   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();

package/src/workflows/schema.ts

@@ -4,6 +4,7 @@ import type {
   CheckpointNodeDefinition,
   ComputeNodeDefinition,
   FunctionActionNodeDefinition,
+  NotifyNodeDefinition,
   ShellActionNodeDefinition,
   WorkflowDefinition,
   WorkflowEdge,
@@ -62,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
@@ -112,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

@@ -1323,6 +1323,9 @@ function snapshotNode(node: WorkflowNodeDefinition): WorkflowNodeSnapshot {
   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

@@ -68,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";
@@ -121,6 +128,7 @@ export type CheckpointNodeDefinition = WorkflowNodeCommon & {
 export type WorkflowNodeDefinition =
   | AgentNodeDefinition
   | ComputeNodeDefinition
+  | NotifyNodeDefinition
   | ActionNodeDefinition
   | CheckpointNodeDefinition;
 
@@ -444,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;
   /**