@osolmaz/pi-workflows 0.4.0 → 0.5.0

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";
@@ -46,6 +42,7 @@ import { WorkflowToolParameters, type WorkflowToolInput } from "./workflow-tool.
 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;
@@ -217,11 +214,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,111 +232,56 @@ 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.
+      // Delivery retries on the next poll. It never affects workflow execution.
     }
   };
 
-  // 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;
-    }
-    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) => {
     if (runSyncTimer !== null) {
       return;
@@ -746,6 +685,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 +738,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 +938,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 +1250,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 +1271,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 ||

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":

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