@osolmaz/pi-workflows 0.4.0 → 0.5.1

package/src/extension/index.ts

@@ -2,11 +2,7 @@ import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { builtinWorkflowCatalog } from "../builtins/catalog.js";
-import {
-  projectControllerStorePath,
-  type RunEventRecord,
-  SqliteControllerStore,
-} from "../controllers/index.js";
+import { projectControllerStorePath, SqliteControllerStore } from "../controllers/index.js";
 import type { JsonObject } from "../controllers/types.js";
 import type { WorkflowSchedulerResult } from "../controllers/workflows.js";
 import { WorkflowEngine } from "../workflows/engine.js";
@@ -40,12 +36,13 @@ import {
 } from "./controller-host.js";
 import { ConversationStepExecutor } from "./executor.js";
 import { SessionRecorder } from "./recorder.js";
-import { buildWidgetView } from "./widget.js";
+import { buildWidgetView, type WidgetLayout, type WidgetScrollState } from "./widget.js";
 import { WorkflowToolParameters, type WorkflowToolInput } from "./workflow-tool.js";
 
 const RUN_CLAIM_LEASE_MS = 30_000;
 const RUN_CLAIM_RENEW_MS = 10_000;
 const RUN_SYNC_POLL_MS = 3_000;
+const NOTIFICATION_DELIVERY_LEASE_MS = 30_000;
 const WIDGET_KEY = "pi-workflows";
 const PRESENTATION_MESSAGE_TYPE = "pi-workflows-presentation";
 const FINAL_WIDGET_TTL_MS = 60_000;
@@ -207,6 +204,14 @@ type WidgetSource = {
   snapshot: WorkflowDefinitionSnapshot;
 };
 
+type WorkflowWidgetComponent = {
+  render: (width: number) => string[];
+  invalidate: () => void;
+};
+
+type WorkflowWidgetFactory = () => WorkflowWidgetComponent;
+type WorkflowWidgetContent = string[] | WorkflowWidgetFactory;
+
 export default function piWorkflows(pi: ExtensionAPI) {
   // One runner identity per session; it names this session in run claims.
   const runnerId = randomUUID();
@@ -217,11 +222,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
     return runQueueStore;
   };
 
-  // Session sync: a per-session watermark over the run event feed keeps this
-  // session's context current with runs other runners drove.
-  // The sync watermark is project-scoped: a reopened session catches up
-  // where the last one stopped, and two open sessions share one pointer.
-  const SYNC_WATERMARK_KEY = "project";
+  // Session-addressed delivery: each session polls only its durable outbox.
+  // Run events remain an audit feed and never enter a conversation.
   let syncArmed = false;
   let runSyncTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -238,109 +240,54 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
   };
 
-  const describeRunEvent = (event: RunEventRecord): string => {
-    const label = `${event.workflowRef} run ${event.runId}`;
-    switch (event.type) {
-      case "waiting": {
-        const waitingOn =
-          typeof event.payload.waitingOn === "string" ? event.payload.waitingOn : "a checkpoint";
-        return `${label} waits at checkpoint ${waitingOn} — answer with /workflow answer`;
+  const deliveredNotificationIds = (ctx: ExtensionContext): Set<string> => {
+    const ids = new Set<string>();
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "custom_message" || entry.customType !== "pi-workflows-notification") {
+        continue;
       }
-      case "parked":
-        return `${label} was parked and will resume when a runner is available`;
-      case "failed": {
-        const detail = typeof event.payload.error === "string" ? `: ${event.payload.error}` : "";
-        return `${label} failed${detail}`;
+      const details = entry.details;
+      if (details !== null && typeof details === "object" && !Array.isArray(details)) {
+        const notificationId = (details as { notificationId?: unknown }).notificationId;
+        if (typeof notificationId === "string") ids.add(notificationId);
       }
-      default:
-        return `${label} ${event.type}`;
     }
+    return ids;
   };
 
-  const runSyncPass = async (ctx: ExtensionContext): Promise<void> => {
-    if (runQueueStore === null || !syncArmed) {
-      return;
-    }
+  const runSyncPass = (ctx: ExtensionContext): void => {
+    if (runQueueStore === null || !syncArmed) return;
     try {
-      const watermark = runQueueStore.getSessionWatermark(SYNC_WATERMARK_KEY);
-      if (watermark === 0) {
-        // First sync ever for this project: never replay the feed (stale
-        // "waits at checkpoint" lines included). Fast-forward, then catch
-        // up from current state instead — what is parked, resuming, or
-        // waiting for an answer right now.
-        const latest = runQueueStore.latestRunEventSeq();
-        if (latest > 0) {
-          runQueueStore.setSessionWatermark(SYNC_WATERMARK_KEY, latest);
+      const sessionId = ctx.sessionManager.getSessionId();
+      const alreadyDelivered = deliveredNotificationIds(ctx);
+      const claimToken = randomUUID();
+      for (const notification of runQueueStore.claimPendingWorkflowNotifications({
+        targetSessionId: sessionId,
+        claimToken,
+        leaseMs: NOTIFICATION_DELIVERY_LEASE_MS,
+      })) {
+        if (!alreadyDelivered.has(notification.notificationId)) {
+          pi.sendMessage({
+            customType: "pi-workflows-notification",
+            content: notification.content,
+            display: true,
+            details: {
+              notificationId: notification.notificationId,
+              runId: notification.runId,
+              kind: notification.kind,
+            },
+          });
+          alreadyDelivered.add(notification.notificationId);
         }
-        await sendStateSnapshot(ctx);
-        return;
-      }
-      const events = runQueueStore.listRunEventsAfter(watermark, { limit: 20 });
-      if (events.length === 0) {
-        return;
-      }
-      // Persist the watermark first. A crash after this point skips the
-      // message, but snapshots recompute from the store, so no information
-      // stays lost; a duplicated state line is the worst outcome.
-      runQueueStore.setSessionWatermark(SYNC_WATERMARK_KEY, events[events.length - 1]?.seq ?? 0);
-      const noteworthy = events.filter(
-        (event) =>
-          event.runnerId !== runnerId &&
-          ["completed", "failed", "timed_out", "cancelled", "waiting", "parked"].includes(
-            event.type,
-          ),
-      );
-      if (noteworthy.length === 0) {
-        return;
+        runQueueStore.markWorkflowNotificationDelivered({
+          notificationId: notification.notificationId,
+          targetSessionId: sessionId,
+          claimToken,
+        });
       }
-      const content = `Workflow run update:\n${noteworthy.map(describeRunEvent).join("\n")}`;
-      pi.sendMessage(
-        { customType: "pi-workflows-run-sync", content, display: false },
-        { deliverAs: "steer", triggerTurn: false },
-      );
-      notify(ctx, noteworthy.map(describeRunEvent).join("; "));
     } catch {
-      // Sync is observational.
-    }
-  };
-
-  // The first-use catch-up: a snapshot of runs that need attention now.
-  const sendStateSnapshot = async (ctx: ExtensionContext) => {
-    if (runQueueStore === null) {
-      return;
-    }
-    const lines: string[] = [];
-    const rows = runQueueStore.listWorkflowRuns();
-    for (const row of rows) {
-      if (row.status === "parked") {
-        lines.push(`${row.workflowName} run ${row.runId} is parked and will resume`);
-      }
-    }
-    const known = new Set(rows.map((row) => row.runId));
-    const continued = new Set(
-      rows.map((row) => row.parentRunId).filter((parent): parent is string => parent !== null),
-    );
-    const bundles = await listRunBundles(new WorkflowRunStore().outputRoot);
-    for (const bundle of bundles) {
-      if (
-        bundle.state.status === "waiting" &&
-        known.has(bundle.state.runId) &&
-        !continued.has(bundle.state.runId)
-      ) {
-        lines.push(
-          `${bundle.state.workflowName} run ${bundle.state.runId} waits at checkpoint ${bundle.state.waitingOn ?? "?"} — answer with /workflow answer`,
-        );
-      }
-    }
-    if (lines.length === 0) {
-      return;
+      // Delivery retries on the next poll. It never affects workflow execution.
     }
-    const content = `Workflow runs needing attention:\n${lines.join("\n")}`;
-    pi.sendMessage(
-      { customType: "pi-workflows-run-sync", content, display: false },
-      { deliverAs: "steer", triggerTurn: false },
-    );
-    notify(ctx, lines.join("; "));
   };
 
   const startRunSync = (ctx: ExtensionContext) => {
@@ -368,9 +315,10 @@ export default function piWorkflows(pi: ExtensionAPI) {
   // Manual widget scroll: null follows the active node; a number is the
   // first visible graph row, set by shift+↑/↓ and reset on step advance.
   let widgetSource: WidgetSource | null = null;
-  let widgetScroll: number | null = null;
+  let widgetScroll: WidgetScrollState = { graph: null, compact: null };
   let widgetShownScroll = 0;
   let widgetMaxScroll = 0;
+  let widgetLayout: WidgetLayout | null = null;
   let widgetStepCount = 0;
   let sessionClosed = false;
   let runGeneration = 0;
@@ -392,10 +340,14 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
   };
 
-  const setWidget = (ctx: ExtensionContext, lines: string[] | undefined) => {
+  const setWidget = (ctx: ExtensionContext, content: WorkflowWidgetContent | undefined) => {
     try {
       if (ctx.hasUI) {
-        ctx.ui.setWidget(WIDGET_KEY, lines);
+        if (typeof content === "function") {
+          ctx.ui.setWidget(WIDGET_KEY, content);
+        } else {
+          ctx.ui.setWidget(WIDGET_KEY, content);
+        }
       }
     } catch {
       // Stale ctx; the widget no longer exists.
@@ -426,20 +378,30 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (!widgetSource) {
       return;
     }
-    const held = runHeld();
-    const view = buildWidgetView(
-      widgetSource.state,
-      widgetSource.snapshot,
-      new Date(),
-      widgetScroll,
-      held,
-    );
-    widgetShownScroll = view.scroll;
-    widgetMaxScroll = view.maxScroll;
-    if (widgetScroll !== null) {
-      widgetScroll = view.scroll;
+    const render = (width = Number.POSITIVE_INFINITY): string[] => {
+      if (!widgetSource) return [];
+      const view = buildWidgetView(
+        widgetSource.state,
+        widgetSource.snapshot,
+        new Date(),
+        widgetScroll,
+        runHeld(),
+        width,
+      );
+      widgetLayout = view.layout;
+      widgetShownScroll = view.scroll;
+      widgetMaxScroll = view.maxScroll;
+      if (widgetScroll[view.layout] !== null) {
+        widgetScroll[view.layout] = view.scroll;
+      }
+      return view.lines;
+    };
+    if (ctx.mode === "tui") {
+      setWidget(ctx, () => ({ render, invalidate() {} }));
+    } else {
+      // RPC transports string widgets but cannot serialize TUI component factories.
+      setWidget(ctx, render());
     }
-    setWidget(ctx, view.lines);
     setStatus(ctx, footerStatus(widgetSource.state));
   };
 
@@ -451,7 +413,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (state.steps.length !== widgetStepCount) {
       widgetStepCount = state.steps.length;
       // The workflow moved on; resume following the active node.
-      widgetScroll = null;
+      widgetScroll = { graph: null, compact: null };
     }
     widgetSource = { state, snapshot };
     renderWidget(ctx);
@@ -459,7 +421,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
 
   const clearWidget = (ctx: ExtensionContext) => {
     widgetSource = null;
-    widgetScroll = null;
+    widgetScroll = { graph: null, compact: null };
+    widgetLayout = null;
     setWidget(ctx, undefined);
     setStatus(ctx, undefined);
   };
@@ -468,7 +431,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (!widgetSource || widgetMaxScroll === 0) {
       return;
     }
-    widgetScroll = Math.max(0, Math.min(widgetShownScroll + delta, widgetMaxScroll));
+    if (widgetLayout === null) return;
+    widgetScroll[widgetLayout] = Math.max(0, Math.min(widgetShownScroll + delta, widgetMaxScroll));
     renderWidget(ctx);
   };
 
@@ -746,6 +710,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
           runnerId,
           claimToken: token,
           leaseMs: RUN_CLAIM_LEASE_MS,
+          originSessionId: ctx.sessionManager.getSessionId(),
           ...(options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {}),
         });
         claimToken = token;
@@ -798,6 +763,24 @@ export default function piWorkflows(pi: ExtensionAPI) {
     const engine = new WorkflowEngine({
       executor,
       store,
+      notificationSink: {
+        notify: (request) => {
+          fence?.();
+          if (queueStore === null) throw new Error("Workflow notifications require a queued run");
+          const record = queueStore.getWorkflowRun(request.runId);
+          if (record?.originSessionId === null || record?.originSessionId === undefined) {
+            throw new Error(`Workflow run ${request.runId} has no origin session`);
+          }
+          const notification = queueStore.enqueueWorkflowNotification({
+            ...request,
+            targetSessionId: record.originSessionId,
+          });
+          return {
+            notificationId: notification.notificationId,
+            targetSessionId: notification.targetSessionId,
+          };
+        },
+      },
       // Awaited by the engine after run_started is persisted, so the session
       // binding and its trace event always precede node and terminal events.
       onRunStarted: async (runDir, state) => {
@@ -980,6 +963,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       claimToken,
       leaseMs: RUN_CLAIM_LEASE_MS,
       excludeRunIds: [...migrationBlockedRuns],
+      sessionId: ctx.sessionManager.getSessionId(),
     });
     if (claimed === undefined) {
       return;
@@ -1291,7 +1275,12 @@ export default function piWorkflows(pi: ExtensionAPI) {
     let parentRunId = requestedRunId ?? lastWaitingRunId;
     if (parentRunId === null) {
       const rows = ensureRunQueueStore(ctx.cwd).listWorkflowRuns();
-      const known = new Set(rows.map((row) => row.runId));
+      const sessionId = ctx.sessionManager.getSessionId();
+      const known = new Set(
+        rows
+          .filter((row) => row.originSessionId === null || row.originSessionId === sessionId)
+          .map((row) => row.runId),
+      );
       const continued = new Set(
         rows.map((row) => row.parentRunId).filter((parent): parent is string => parent !== null),
       );
@@ -1307,6 +1296,14 @@ export default function piWorkflows(pi: ExtensionAPI) {
     if (parentRunId === null) {
       throw new Error("No workflow is waiting for an answer.");
     }
+    const queueRecord = ensureRunQueueStore(ctx.cwd).getWorkflowRun(parentRunId);
+    if (
+      queueRecord?.originSessionId !== null &&
+      queueRecord?.originSessionId !== undefined &&
+      queueRecord.originSessionId !== ctx.sessionManager.getSessionId()
+    ) {
+      throw new Error(`Workflow run ${parentRunId} belongs to another Pi session.`);
+    }
     const parent = await readRunBundle(new WorkflowRunStore().runDirFor(parentRunId));
     if (
       parent === null ||
@@ -1816,7 +1813,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
     clearWidgetTimer();
     stopWidgetTicker();
     widgetSource = null;
-    widgetScroll = null;
+    widgetScroll = { graph: null, compact: null };
+    widgetLayout = null;
   });
 }
 

package/src/extension/widget.ts

@@ -1,3 +1,4 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { ansi, stripAnsi } from "../render/ansi.js";
 import { renderGraphLines } from "../render/graph-render.js";
 import { sanitizeText } from "../workflows/text.js";
@@ -42,9 +43,14 @@ export function displayNodeIds(snapshot: WorkflowDefinitionSnapshot): string[] {
   return Object.keys(snapshot.nodes);
 }
 
+export type WidgetLayout = "graph" | "compact";
+
+export type WidgetScrollState = Record<WidgetLayout, number | null>;
+
 export type WidgetView = {
   lines: string[];
-  /** The clamped first visible graph row; feed back in to scroll relatively. */
+  layout: WidgetLayout;
+  /** The clamped first visible row for the selected layout. */
   scroll: number;
   /** Largest useful scroll value; 0 when the whole graph fits. */
   maxScroll: number;
@@ -61,9 +67,13 @@ export function buildWidgetView(
   state: WorkflowRunState,
   snapshot: WorkflowDefinitionSnapshot,
   now: Date = new Date(),
-  scroll: number | null = null,
+  scroll: WidgetScrollState = { graph: null, compact: null },
   held = false,
+  width = Number.POSITIVE_INFINITY,
 ): WidgetView {
+  const availableWidth = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : width;
+  if (availableWidth === 0) return { lines: [], layout: "compact", scroll: 0, maxScroll: 0 };
+
   // `held` covers pauses the state cannot see yet: an escape-interrupted
   // step or a pause requested while the current node is still finishing.
   const paused = held || state.paused === true;
@@ -79,28 +89,94 @@ export function buildWidgetView(
     footer.push(`  error: ${truncate(sanitizeText(state.error), 120)}`);
   }
   if (state.status === "waiting" && state.waitingOn) {
-    footer.push(`  waiting on checkpoint: ${state.waitingOn}`);
+    footer.push(`  waiting on checkpoint: ${sanitizeText(state.waitingOn)}`);
   }
 
   const budget = PI_MAX_WIDGET_LINES - 1 - footer.length;
   const graph = renderGraphLines({ state, snapshot }, state.steps.length - 1, now, {
     nodeStyle: "box",
   });
-  if (graph.length === 0) {
+  if (graph.length > 0) {
+    const graphScroll = scroll.graph;
+    const windowed = windowLines(
+      graph,
+      budget,
+      graphScroll ?? focusLine(graph, state),
+      graphScroll !== null,
+    );
+    const graphLines = windowed.lines.map((line) => `  ${line}`);
+    if (graphLines.every((line) => visibleWidth(line) <= availableWidth)) {
+      return {
+        lines: fitLines([header, ...graphLines, ...footer], availableWidth),
+        layout: "graph",
+        scroll: windowed.scroll,
+        maxScroll: windowed.maxScroll,
+      };
+    }
+  }
+
+  return compactWidgetView(state, snapshot, header, footer, budget, availableWidth, scroll.compact);
+}
+
+function compactWidgetView(
+  state: WorkflowRunState,
+  snapshot: WorkflowDefinitionSnapshot,
+  header: string,
+  footer: string[],
+  budget: number,
+  width: number,
+  scroll: number | null,
+): WidgetView {
+  const nodes = displayNodeIds(snapshot).map((nodeId) => compactNodeLine(state, snapshot, nodeId));
+  if (nodes.length === 0) {
     return {
-      lines: [header, `  ${compactNodeStrip(state, snapshot)}`, ...footer],
+      lines: fitLines([header, ...footer], width),
+      layout: "compact",
       scroll: 0,
       maxScroll: 0,
     };
   }
-  const windowed = windowLines(graph, budget, scroll ?? focusLine(graph, state), scroll !== null);
+  const anchor = scroll ?? compactFocusIndex(state, snapshot);
+  const windowed = windowLines(nodes, budget, anchor, scroll !== null);
+  const indentation = width >= 3 ? "  " : "";
   return {
-    lines: [header, ...windowed.lines.map((line) => `  ${line}`), ...footer],
+    lines: fitLines(
+      [header, ...windowed.lines.map((line) => `${indentation}${line}`), ...footer],
+      width,
+    ),
+    layout: "compact",
     scroll: windowed.scroll,
     maxScroll: windowed.maxScroll,
   };
 }
 
+function compactFocusIndex(state: WorkflowRunState, snapshot: WorkflowDefinitionSnapshot): number {
+  const nodeIds = displayNodeIds(snapshot);
+  const focused = state.currentNode ?? state.waitingOn;
+  if (focused === undefined) return Math.max(0, nodeIds.length - 1);
+  const index = nodeIds.indexOf(focused);
+  return index === -1 ? Math.max(0, nodeIds.length - 1) : index;
+}
+
+function compactNodeLine(
+  state: WorkflowRunState,
+  snapshot: WorkflowDefinitionSnapshot,
+  nodeId: string,
+): string {
+  const node = snapshot.nodes[nodeId];
+  const type = node?.nodeType === undefined ? "" : ` · ${node.nodeType}`;
+  const detail =
+    state.currentNode === nodeId && state.statusDetail
+      ? ` · ${sanitizeText(state.statusDetail)}`
+      : "";
+  return `${nodeGlyph(state, nodeId)} ${sanitizeText(nodeId)}${type}${detail}`;
+}
+
+function fitLines(lines: string[], width: number): string[] {
+  if (!Number.isFinite(width)) return lines;
+  return lines.map((line) => truncateToWidth(line, width, width > 1 ? "…" : ""));
+}
+
 /** Back-compatible line view following the active node. */
 export function buildWidgetLines(
   state: WorkflowRunState,
@@ -167,19 +243,6 @@ function clampStart(anchor: number, inner: number, total: number, anchorIsStart:
   return Math.max(0, Math.min(start, total - inner));
 }
 
-function compactNodeStrip(state: WorkflowRunState, snapshot: WorkflowDefinitionSnapshot): string {
-  return displayNodeIds(snapshot)
-    .map((nodeId) => {
-      const marker = nodeGlyph(state, nodeId);
-      const detail =
-        state.currentNode === nodeId && state.statusDetail
-          ? ` (${sanitizeText(state.statusDetail)})`
-          : "";
-      return `${marker} ${nodeId}${detail}`;
-    })
-    .join("  ");
-}
-
 function truncate(text: string, maxLength: number): string {
   return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
 }

package/src/host/runner.ts

@@ -269,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);
 

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/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;

package/src/workflows/engine.ts

@@ -30,6 +30,7 @@ import type {
   WorkflowNodeDefinition,
   WorkflowNodeOutcome,
   WorkflowNodeResult,
+  WorkflowNotificationSink,
   WorkflowRunResult,
   WorkflowRunState,
   WorkflowSource,
@@ -74,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;
@@ -88,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;
@@ -868,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":