@osolmaz/pi-workflows 0.3.0 → 0.5.0

package/src/controllers/sqlite.ts

@@ -93,6 +93,7 @@ type WorkflowRunQueueRow = {
   claim_token: string | null;
   claim_expires_at: number | null;
   affinity_runner_id: string | null;
+  origin_session_id: string | null;
   parent_run_id: string | null;
   created_at: string;
   updated_at: string;
@@ -101,19 +102,52 @@ type WorkflowRunQueueRow = {
 /** A user-started workflow run tracked by the durable run queue. */
 export type WorkflowRunQueueRecord = {
   runId: string;
-  workflowRef: string;
-  workflowPath: string;
+  /** Human-readable workflow name used in status and event output. */
+  workflowName: string;
+  /** Canonical source reference used to reopen the run. */
+  workflowSourceRef: string;
   input: unknown;
   status: "claimed" | "parked" | "done";
   runnerId: string | null;
   claimToken: string | null;
   claimExpiresAt: string | null;
   affinityRunnerId: string | null;
+  /** Pi session that owns delivery and interactive execution, or null for detached runs. */
+  originSessionId: string | null;
   parentRunId: string | null;
   createdAt: string;
   updatedAt: string;
 };
 
+type WorkflowNotificationRow = {
+  notification_id: string;
+  run_id: string;
+  node_id: string;
+  attempt_id: string;
+  notification_index: number;
+  target_session_id: string;
+  kind: "progress" | "final";
+  content: string;
+  created_at: string;
+  delivery_claim_token: string | null;
+  delivery_claim_expires_at: number | null;
+  delivered_at: string | null;
+};
+
+export type WorkflowNotificationRecord = {
+  notificationId: string;
+  runId: string;
+  nodeId: string;
+  attemptId: string;
+  notificationIndex: number;
+  targetSessionId: string;
+  kind: "progress" | "final";
+  content: string;
+  createdAt: string;
+  deliveryClaimExpiresAt: string | null;
+  deliveredAt: string | null;
+};
+
 type RunEventRow = {
   seq: number;
   recorded_at: string;
@@ -772,6 +806,13 @@ export class SqliteControllerStore implements ControllerStore {
         .prepare("INSERT OR IGNORE INTO schema_info (singleton, schema_id) VALUES (1, ?)")
         .run(CONTROLLER_STORE_SCHEMA);
       this.database.exec(SCHEMA_SQL);
+      const queueColumns = this.database.pragma("table_info(workflow_run_queue)") as {
+        name: string;
+      }[];
+      if (!queueColumns.some((column) => column.name === "origin_session_id")) {
+        this.database.exec("ALTER TABLE workflow_run_queue ADD COLUMN origin_session_id TEXT");
+      }
+      this.database.exec("DROP TABLE IF EXISTS session_watermarks");
     });
   }
 
@@ -866,22 +907,26 @@ export class SqliteControllerStore implements ControllerStore {
    */
   enqueueWorkflowRun(options: {
     runId: string;
-    workflowRef: string;
-    workflowPath: string;
+    workflowName: string;
+    workflowSourceRef: string;
     input: unknown;
     runnerId: string;
     claimToken: string;
     leaseMs: number;
     affinityRunnerId?: string;
+    originSessionId?: string;
     parentRunId?: string;
     now?: string;
   }): WorkflowRunQueueRecord {
     validateRunId(options.runId);
-    validateKey(options.workflowRef, "workflow ref");
-    validateKey(options.workflowPath, "workflow path");
+    validateKey(options.workflowName, "workflow name");
+    validateKey(options.workflowSourceRef, "workflow source ref");
     validateKey(options.runnerId, "runner id");
     validateKey(options.claimToken, "claim token");
     validateDuration(options.leaseMs, "leaseMs");
+    if (options.originSessionId !== undefined) {
+      validateKey(options.originSessionId, "origin session id");
+    }
     const inputJson = canonicalJson(options.input ?? null, "workflow run input");
     validateJsonSize(inputJson, "Workflow run input", MAX_RESOURCE_VALUE_BYTES);
     const now = validTimestamp(options.now);
@@ -891,18 +936,19 @@ export class SqliteControllerStore implements ControllerStore {
         `INSERT INTO workflow_run_queue (
           run_id, workflow_ref, workflow_path, input_json, status,
           runner_id, claim_token, claim_expires_at, affinity_runner_id,
-          parent_run_id, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, 'claimed', ?, ?, ?, ?, ?, ?, ?)`,
+          origin_session_id, parent_run_id, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, 'claimed', ?, ?, ?, ?, ?, ?, ?, ?)`,
       )
       .run(
         options.runId,
-        options.workflowRef,
-        options.workflowPath,
+        options.workflowName,
+        options.workflowSourceRef,
         inputJson,
         options.runnerId,
         options.claimToken,
         expiresAt,
         options.affinityRunnerId ?? options.runnerId,
+        options.originSessionId ?? null,
         options.parentRunId ?? null,
         now,
         now,
@@ -943,11 +989,14 @@ export class SqliteControllerStore implements ControllerStore {
     claimToken: string;
     leaseMs: number;
     excludeRunIds?: string[];
+    /** Interactive sessions provide their id; detached hosts omit it. */
+    sessionId?: string;
     now?: string;
   }): WorkflowRunQueueRecord | undefined {
     validateKey(options.runnerId, "runner id");
     validateKey(options.claimToken, "claim token");
     validateDuration(options.leaseMs, "leaseMs");
+    if (options.sessionId !== undefined) validateKey(options.sessionId, "session id");
     const now = validTimestamp(options.now);
     const nowMs = epoch(now);
     const expiresAt = nowMs + options.leaseMs;
@@ -957,6 +1006,10 @@ export class SqliteControllerStore implements ControllerStore {
     }
     const exclusion =
       excluded.length === 0 ? "" : `AND run_id NOT IN (${excluded.map(() => "?").join(", ")})`;
+    const sessionFilter =
+      options.sessionId === undefined
+        ? ""
+        : "AND (origin_session_id IS NULL OR origin_session_id = ?)";
     const claimable = `(
       status = 'parked'
       OR (status = 'claimed' AND claim_expires_at IS NOT NULL AND claim_expires_at <= ?)
@@ -965,13 +1018,18 @@ export class SqliteControllerStore implements ControllerStore {
       const candidate = this.database
         .prepare(
           `SELECT run_id FROM workflow_run_queue
-           WHERE ${claimable} ${exclusion}
+           WHERE ${claimable} ${exclusion} ${sessionFilter}
            ORDER BY
              CASE WHEN affinity_runner_id = ? THEN 0 ELSE 1 END,
              created_at ASC
            LIMIT 1`,
         )
-        .get(nowMs, ...excluded, options.runnerId) as { run_id: string } | undefined;
+        .get(
+          nowMs,
+          ...excluded,
+          ...(options.sessionId === undefined ? [] : [options.sessionId]),
+          options.runnerId,
+        ) as { run_id: string } | undefined;
       if (candidate === undefined) {
         return undefined;
       }
@@ -1068,6 +1126,122 @@ export class SqliteControllerStore implements ControllerStore {
     return result.changes === 1;
   }
 
+  /** Repair a canonical bundle's queue source and claim it only when needed. */
+  repairCanonicalWorkflowSourceRun(options: {
+    runId: string;
+    workflowName: string;
+    workflowSourceRef: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+    now?: string;
+  }): "unchanged" | "claimed" | false {
+    validateRunId(options.runId);
+    validateKey(options.workflowName, "workflow name");
+    validateKey(options.workflowSourceRef, "workflow source ref");
+    validateKey(options.runnerId, "runner id");
+    validateKey(options.claimToken, "claim token");
+    validateDuration(options.leaseMs, "leaseMs");
+    const now = validTimestamp(options.now);
+    const nowMs = epoch(now);
+    const expiresAt = nowMs + options.leaseMs;
+    return this.transaction(() => {
+      const row = this.database
+        .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
+        .get(options.runId) as WorkflowRunQueueRow | undefined;
+      if (row === undefined || row.status === "done") return false;
+      if (row.workflow_path === options.workflowSourceRef && row.status === "parked") {
+        return "unchanged";
+      }
+      const claimable =
+        row.status === "parked" ||
+        (row.status === "claimed" &&
+          row.claim_token === options.claimToken &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at > nowMs) ||
+        (row.status === "claimed" &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at <= nowMs);
+      if (!claimable) return false;
+      const result = this.database
+        .prepare(
+          `UPDATE workflow_run_queue
+           SET workflow_ref = ?, workflow_path = ?, status = 'claimed', runner_id = ?,
+               claim_token = ?, claim_expires_at = ?, updated_at = ?
+           WHERE run_id = ? AND status != 'done'`,
+        )
+        .run(
+          options.workflowName,
+          options.workflowSourceRef,
+          options.runnerId,
+          options.claimToken,
+          expiresAt,
+          now,
+          options.runId,
+        );
+      return result.changes === 1 ? "claimed" : false;
+    });
+  }
+
+  /** Claim and rewrite one proved legacy workflow source queue row atomically. */
+  claimLegacyWorkflowSourceRun(options: {
+    runId: string;
+    workflowName: string;
+    oldWorkflowPath: string;
+    workflowSourceRef: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+    now?: string;
+  }): boolean {
+    validateRunId(options.runId);
+    validateKey(options.workflowName, "workflow name");
+    validateKey(options.oldWorkflowPath, "legacy workflow path");
+    validateKey(options.workflowSourceRef, "workflow source ref");
+    validateKey(options.runnerId, "runner id");
+    validateKey(options.claimToken, "claim token");
+    validateDuration(options.leaseMs, "leaseMs");
+    const now = validTimestamp(options.now);
+    const nowMs = epoch(now);
+    const expiresAt = nowMs + options.leaseMs;
+    return this.transaction(() => {
+      const row = this.database
+        .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
+        .get(options.runId) as WorkflowRunQueueRow | undefined;
+      if (row === undefined || row.status === "done") return false;
+      const sourceMatches =
+        row.workflow_path === options.oldWorkflowPath ||
+        row.workflow_path === options.workflowSourceRef;
+      const claimable =
+        row.status === "parked" ||
+        (row.status === "claimed" &&
+          row.claim_token === options.claimToken &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at > nowMs) ||
+        (row.status === "claimed" &&
+          row.claim_expires_at !== null &&
+          row.claim_expires_at <= nowMs);
+      if (!sourceMatches || !claimable) return false;
+      const result = this.database
+        .prepare(
+          `UPDATE workflow_run_queue
+           SET workflow_ref = ?, workflow_path = ?, status = 'claimed', runner_id = ?,
+               claim_token = ?, claim_expires_at = ?, updated_at = ?
+           WHERE run_id = ? AND status != 'done'`,
+        )
+        .run(
+          options.workflowName,
+          options.workflowSourceRef,
+          options.runnerId,
+          options.claimToken,
+          expiresAt,
+          now,
+          options.runId,
+        );
+      return result.changes === 1;
+    });
+  }
+
   /** Append a run lifecycle transition to the event feed. */
   recordRunEvent(options: {
     runId: string;
@@ -1117,37 +1291,141 @@ export class SqliteControllerStore implements ControllerStore {
     }));
   }
 
-  /** The highest run event seq in the feed; 0 when empty. */
-  latestRunEventSeq(): number {
-    const row = this.database.prepare("SELECT MAX(seq) AS latest FROM run_events").get() as {
-      latest: number | null;
-    };
-    return row.latest ?? 0;
-  }
-
-  /** The last run event this session was told about; 0 before any sync. */
-  getSessionWatermark(sessionId: string): number {
-    validateKey(sessionId, "session id");
+  enqueueWorkflowNotification(options: {
+    runId: string;
+    nodeId: string;
+    attemptId: string;
+    notificationIndex: number;
+    targetSessionId: string;
+    kind: "progress" | "final";
+    content: string;
+    notificationId?: string;
+    now?: string;
+  }): WorkflowNotificationRecord {
+    validateRunId(options.runId);
+    validateKey(options.nodeId, "workflow node id");
+    validateKey(options.attemptId, "workflow attempt id");
+    if (!Number.isSafeInteger(options.notificationIndex) || options.notificationIndex <= 0) {
+      throw new Error("Workflow notification index must be a positive safe integer");
+    }
+    validateKey(options.targetSessionId, "target session id");
+    if (options.content.trim().length === 0 || options.content.length > MAX_EVENT_BYTES) {
+      throw new Error(`Workflow notification content must be 1-${MAX_EVENT_BYTES} characters`);
+    }
+    const notificationId = options.notificationId ?? randomUUID();
+    validateKey(notificationId, "notification id");
+    this.database
+      .prepare(
+        `INSERT INTO workflow_notifications (
+          notification_id, run_id, node_id, attempt_id, notification_index,
+          target_session_id, kind, content, created_at, delivered_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+        ON CONFLICT(run_id, node_id, notification_index) DO NOTHING`,
+      )
+      .run(
+        notificationId,
+        options.runId,
+        options.nodeId,
+        options.attemptId,
+        options.notificationIndex,
+        options.targetSessionId,
+        options.kind,
+        options.content.trim(),
+        validTimestamp(options.now),
+      );
     const row = this.database
-      .prepare("SELECT last_event_seq FROM session_watermarks WHERE session_id = ?")
-      .get(sessionId) as { last_event_seq: number } | undefined;
-    return row?.last_event_seq ?? 0;
+      .prepare(
+        "SELECT * FROM workflow_notifications WHERE run_id = ? AND node_id = ? AND notification_index = ?",
+      )
+      .get(options.runId, options.nodeId, options.notificationIndex) as WorkflowNotificationRow;
+    return workflowNotificationFromRow(row);
   }
 
-  setSessionWatermark(sessionId: string, seq: number, now?: string): void {
-    validateKey(sessionId, "session id");
-    if (!Number.isSafeInteger(seq) || seq < 0) {
-      throw new Error(`Invalid run event watermark: ${seq}`);
+  claimPendingWorkflowNotifications(options: {
+    targetSessionId: string;
+    claimToken: string;
+    leaseMs: number;
+    limit?: number;
+    now?: string;
+  }): WorkflowNotificationRecord[] {
+    validateKey(options.targetSessionId, "target session id");
+    validateKey(options.claimToken, "notification claim token");
+    validateDuration(options.leaseMs, "notification leaseMs");
+    const limit = options.limit ?? 20;
+    if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+      throw new Error("Workflow notification limit must be an integer from 1 through 100");
     }
-    this.database
+    const now = validTimestamp(options.now);
+    const nowMs = epoch(now);
+    return this.transaction(() => {
+      const ids = this.database
+        .prepare(
+          `SELECT notification_id FROM workflow_notifications
+           WHERE target_session_id = ? AND delivered_at IS NULL
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)
+           ORDER BY created_at, notification_id LIMIT ?`,
+        )
+        .all(options.targetSessionId, nowMs, limit) as { notification_id: string }[];
+      if (ids.length === 0) return [];
+      const placeholders = ids.map(() => "?").join(", ");
+      this.database
+        .prepare(
+          `UPDATE workflow_notifications
+           SET delivery_claim_token = ?, delivery_claim_expires_at = ?
+           WHERE notification_id IN (${placeholders}) AND delivered_at IS NULL
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)`,
+        )
+        .run(
+          options.claimToken,
+          nowMs + options.leaseMs,
+          ...ids.map((row) => row.notification_id),
+          nowMs,
+        );
+      const rows = this.database
+        .prepare(
+          `SELECT * FROM workflow_notifications WHERE delivery_claim_token = ?
+           ORDER BY created_at, notification_id`,
+        )
+        .all(options.claimToken) as WorkflowNotificationRow[];
+      return rows.map(workflowNotificationFromRow);
+    });
+  }
+
+  markWorkflowNotificationDelivered(options: {
+    notificationId: string;
+    targetSessionId: string;
+    claimToken: string;
+    now?: string;
+  }): boolean {
+    validateKey(options.notificationId, "notification id");
+    validateKey(options.targetSessionId, "target session id");
+    validateKey(options.claimToken, "notification claim token");
+    const result = this.database
       .prepare(
-        `INSERT INTO session_watermarks (session_id, last_event_seq, updated_at)
-         VALUES (?, ?, ?)
-         ON CONFLICT(session_id) DO UPDATE SET
-           last_event_seq = MAX(session_watermarks.last_event_seq, excluded.last_event_seq),
-           updated_at = excluded.updated_at`,
+        `UPDATE workflow_notifications
+         SET delivered_at = ?, delivery_claim_token = NULL, delivery_claim_expires_at = NULL
+         WHERE notification_id = ? AND target_session_id = ?
+           AND delivery_claim_token = ? AND delivered_at IS NULL`,
       )
-      .run(sessionId, seq, validTimestamp(now));
+      .run(
+        validTimestamp(options.now),
+        options.notificationId,
+        options.targetSessionId,
+        options.claimToken,
+      );
+    return result.changes === 1;
+  }
+
+  setWorkflowRunOriginSession(runId: string, originSessionId: string): boolean {
+    validateRunId(runId);
+    validateKey(originSessionId, "origin session id");
+    const result = this.database
+      .prepare(
+        `UPDATE workflow_run_queue SET origin_session_id = ?
+         WHERE run_id = ? AND origin_session_id IS NULL`,
+      )
+      .run(originSessionId, runId);
+    return result.changes === 1;
   }
 
   private requireWorkflowRun(runId: string): WorkflowRunQueueRecord {
@@ -1211,6 +1489,7 @@ const SCHEMA_SQL = `
     claim_token TEXT,
     claim_expires_at INTEGER,
     affinity_runner_id TEXT,
+    origin_session_id TEXT,
     parent_run_id TEXT,
     created_at TEXT NOT NULL,
     updated_at TEXT NOT NULL
@@ -1233,11 +1512,24 @@ const SCHEMA_SQL = `
   );
   CREATE INDEX IF NOT EXISTS run_events_run ON run_events(run_id);
 
-  CREATE TABLE IF NOT EXISTS session_watermarks (
-    session_id TEXT PRIMARY KEY,
-    last_event_seq INTEGER NOT NULL CHECK (last_event_seq >= 0),
-    updated_at TEXT NOT NULL
+  CREATE TABLE IF NOT EXISTS workflow_notifications (
+    notification_id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    node_id TEXT NOT NULL,
+    attempt_id TEXT NOT NULL,
+    notification_index INTEGER NOT NULL CHECK (notification_index > 0),
+    target_session_id TEXT NOT NULL,
+    kind TEXT NOT NULL CHECK (kind IN ('progress', 'final')),
+    content TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    delivery_claim_token TEXT,
+    delivery_claim_expires_at INTEGER,
+    delivered_at TEXT,
+    UNIQUE (run_id, node_id, notification_index)
   );
+  CREATE INDEX IF NOT EXISTS workflow_notifications_pending
+    ON workflow_notifications(target_session_id, delivery_claim_expires_at, created_at)
+    WHERE delivered_at IS NULL;
 
   CREATE TABLE IF NOT EXISTS effects (
     effect_key TEXT NOT NULL,
@@ -1329,17 +1621,35 @@ function workflowFromRow(row: WorkflowRow): ChildWorkflowRecord {
   };
 }
 
+function workflowNotificationFromRow(row: WorkflowNotificationRow): WorkflowNotificationRecord {
+  return {
+    notificationId: row.notification_id,
+    runId: row.run_id,
+    nodeId: row.node_id,
+    attemptId: row.attempt_id,
+    notificationIndex: row.notification_index,
+    targetSessionId: row.target_session_id,
+    kind: row.kind,
+    content: row.content,
+    createdAt: row.created_at,
+    deliveryClaimExpiresAt:
+      row.delivery_claim_expires_at === null ? null : iso(row.delivery_claim_expires_at),
+    deliveredAt: row.delivered_at,
+  };
+}
+
 function workflowRunFromRow(row: WorkflowRunQueueRow): WorkflowRunQueueRecord {
   return {
     runId: row.run_id,
-    workflowRef: row.workflow_ref,
-    workflowPath: row.workflow_path,
+    workflowName: row.workflow_ref,
+    workflowSourceRef: row.workflow_path,
     input: parseStoredJson(row.input_json, "workflow run input"),
     status: row.status,
     runnerId: row.runner_id,
     claimToken: row.claim_token,
     claimExpiresAt: row.claim_expires_at === null ? null : iso(row.claim_expires_at),
     affinityRunnerId: row.affinity_runner_id,
+    originSessionId: row.origin_session_id,
     parentRunId: row.parent_run_id,
     createdAt: row.created_at,
     updatedAt: row.updated_at,

package/src/controllers/workflow-engine-scheduler.ts

@@ -4,6 +4,7 @@ import type {
   WorkflowDefinition,
   WorkflowRunResult,
   WorkflowRunStatus,
+  WorkflowSource,
 } from "../workflows/types.js";
 import type {
   ControllerWorkflowScheduler,
@@ -13,7 +14,7 @@ import type {
 
 export type ResolvedChildWorkflow = {
   workflow: WorkflowDefinition;
-  workflowPath?: string;
+  workflowSource?: WorkflowSource;
 };
 
 export type WorkflowEngineSchedulerOptions = {
@@ -77,7 +78,9 @@ export class WorkflowEngineScheduler implements ControllerWorkflowScheduler {
     const promise = engine
       .run(resolved.workflow, request.input, {
         runId,
-        ...(resolved.workflowPath !== undefined ? { workflowPath: resolved.workflowPath } : {}),
+        ...(resolved.workflowSource !== undefined
+          ? { workflowSource: resolved.workflowSource }
+          : {}),
       })
       .then((result) => {
         callCompletion(onComplete, resultFromRun(result));

package/src/extension/executor.ts

@@ -33,6 +33,8 @@ export type ConversationStepExecutorOptions = {
   maxNudges?: number;
   /** Conversation linkage hooks, wired to the session recorder. */
   conversation?: ConversationHooks;
+  /** Called when the engine aborts a pending agent step. */
+  onAbort?: (contract: AgentStepRequest["contract"], reason: unknown) => void;
 };
 
 type PendingStep = {
@@ -61,6 +63,7 @@ export class ConversationStepExecutor implements AgentStepExecutor {
   private readonly sendPrompt: (delivery: PromptDelivery) => void;
   private readonly maxNudges: number;
   private readonly conversation: ConversationHooks | undefined;
+  private readonly onAbort: ConversationStepExecutorOptions["onAbort"];
   private pending: PendingStep | null = null;
   private streaming = false;
   private heldByUser = false;
@@ -69,6 +72,7 @@ export class ConversationStepExecutor implements AgentStepExecutor {
     this.sendPrompt = options.sendPrompt;
     this.maxNudges = options.maxNudges ?? DEFAULT_MAX_NUDGES;
     this.conversation = options.conversation;
+    this.onAbort = options.onAbort;
   }
 
   /** Track agent streaming state (wire to agent_start / agent_settled). */
@@ -121,8 +125,15 @@ export class ConversationStepExecutor implements AgentStepExecutor {
     return await new Promise<AgentStepSubmission>((resolve, reject) => {
       const onAbort = () => {
         const reason: unknown = signal.reason ?? new Error("Workflow step aborted");
+        if (this.pending?.request !== request) {
+          return;
+        }
         this.clearPending();
-        reject(reason);
+        try {
+          this.onAbort?.(request.contract, reason);
+        } finally {
+          reject(reason);
+        }
       };
       signal.addEventListener("abort", onAbort, { once: true });
       let markCleared!: () => void;