@osolmaz/pi-workflows 0.15.1 → 0.15.3

package/src/extension/session-delivery.ts

@@ -0,0 +1,174 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type ClaimedSessionDelivery = {
+  deliveryId: string;
+  claimExpiresAt: number;
+  isStillDeliverable: () => boolean | Promise<boolean>;
+  findSessionEntryId: (entries: readonly unknown[]) => string | undefined;
+  send: () => void;
+  settle: (sessionEntryId: string) => Promise<void>;
+};
+
+export type ClaimSessionDelivery = () => Promise<ClaimedSessionDelivery | undefined>;
+
+type QueuedSessionDelivery = {
+  delivery: ClaimedSessionDelivery;
+  queuedAt: number;
+  ambiguityReported: boolean;
+};
+
+const SESSION_ENTRY_CONFIRMATION_MS = 10_000;
+
+/**
+ * Delivers at most one host-owned message into a Pi session at a time.
+ *
+ * Pi's public sendMessage API does not return the saved session entry ID. Keep
+ * the claimed delivery in memory until that entry becomes observable. Polling
+ * may reconcile the delivery, but it must never send the same claim again.
+ */
+export class SessionDeliveryCoordinator {
+  private readonly queued = new Map<string, QueuedSessionDelivery>();
+  private claimed: ClaimedSessionDelivery | undefined;
+  private synchronizing = false;
+
+  async synchronize(
+    ctx: Pick<ExtensionContext, "hasPendingMessages" | "isIdle" | "sessionManager" | "ui">,
+    claimers: readonly ClaimSessionDelivery[],
+  ): Promise<void> {
+    if (this.synchronizing) return;
+    this.synchronizing = true;
+    try {
+      if (await this.settleQueued(ctx)) return;
+      if (await this.sendClaimed(ctx)) return;
+      if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
+
+      for (const claim of claimers) {
+        const delivery = await claim();
+        if (delivery === undefined) continue;
+
+        const existingEntryId = delivery.findSessionEntryId(ctx.sessionManager.getBranch());
+        if (existingEntryId !== undefined) {
+          if (delivery.claimExpiresAt <= Date.now()) return;
+          this.rememberQueued(delivery);
+          await this.settleDelivery(ctx, delivery.deliveryId, existingEntryId);
+          return;
+        }
+
+        // Remember the host claim before the final idle check. If Pi starts a
+        // turn while the claim request is in flight, a later poll can use this
+        // exact still-live claim instead of making a conflicting second claim.
+        this.claimed = delivery;
+        await this.sendClaimed(ctx);
+        return;
+      }
+    } finally {
+      this.synchronizing = false;
+    }
+  }
+
+  clear(): void {
+    this.claimed = undefined;
+    this.queued.clear();
+  }
+
+  private async sendClaimed(
+    ctx: Pick<ExtensionContext, "hasPendingMessages" | "isIdle" | "sessionManager" | "ui">,
+  ): Promise<boolean> {
+    const delivery = this.claimed;
+    if (delivery === undefined) return false;
+    if (delivery.claimExpiresAt <= Date.now()) {
+      this.claimed = undefined;
+      return false;
+    }
+
+    const existingEntryId = delivery.findSessionEntryId(ctx.sessionManager.getBranch());
+    if (existingEntryId !== undefined) {
+      this.rememberQueued(delivery);
+      this.claimed = undefined;
+      await this.settleDelivery(ctx, delivery.deliveryId, existingEntryId);
+      return true;
+    }
+    if (!ctx.isIdle() || ctx.hasPendingMessages()) return true;
+    if (!(await delivery.isStillDeliverable())) {
+      this.claimed = undefined;
+      return false;
+    }
+    if (delivery.claimExpiresAt <= Date.now()) {
+      this.claimed = undefined;
+      return false;
+    }
+    if (!ctx.isIdle() || ctx.hasPendingMessages()) return true;
+
+    this.rememberQueued(delivery);
+    this.claimed = undefined;
+    try {
+      delivery.send();
+    } catch (error) {
+      this.queued.delete(delivery.deliveryId);
+      throw error;
+    }
+
+    const insertedEntryId = delivery.findSessionEntryId(ctx.sessionManager.getBranch());
+    if (insertedEntryId !== undefined) {
+      await this.settleDelivery(ctx, delivery.deliveryId, insertedEntryId);
+    }
+    return true;
+  }
+
+  private rememberQueued(delivery: ClaimedSessionDelivery): void {
+    if (this.queued.has(delivery.deliveryId)) return;
+    this.queued.set(delivery.deliveryId, {
+      delivery,
+      queuedAt: Date.now(),
+      ambiguityReported: false,
+    });
+  }
+
+  private async settleQueued(
+    ctx: Pick<ExtensionContext, "hasPendingMessages" | "isIdle" | "sessionManager" | "ui">,
+  ): Promise<boolean> {
+    let hadQueuedDelivery = false;
+    for (const [deliveryId, queued] of this.queued) {
+      hadQueuedDelivery = true;
+      const sessionEntryId = queued.delivery.findSessionEntryId(ctx.sessionManager.getBranch());
+      if (sessionEntryId === undefined) {
+        if (
+          !queued.ambiguityReported &&
+          ctx.isIdle() &&
+          !ctx.hasPendingMessages() &&
+          Date.now() - queued.queuedAt >= SESSION_ENTRY_CONFIRMATION_MS
+        ) {
+          queued.ambiguityReported = true;
+          ctx.ui.notify(
+            `Workflow session delivery ${deliveryId} is ambiguous: Pi did not expose a matching session entry. Do not retry it until you check the session history.`,
+            "warning",
+          );
+        }
+        return true;
+      }
+      await this.settleDelivery(ctx, deliveryId, sessionEntryId);
+    }
+    return hadQueuedDelivery;
+  }
+
+  private async settleDelivery(
+    ctx: Pick<ExtensionContext, "ui">,
+    deliveryId: string,
+    sessionEntryId: string,
+  ): Promise<void> {
+    const queued = this.queued.get(deliveryId);
+    if (queued === undefined) return;
+    try {
+      await queued.delivery.settle(sessionEntryId);
+      this.queued.delete(deliveryId);
+    } catch (error) {
+      if (!queued.ambiguityReported) {
+        queued.ambiguityReported = true;
+        ctx.ui.notify(
+          `Workflow session delivery ${deliveryId} is visible but its durable receipt is ambiguous: ${String(error)}. Do not retry it until recovery checks the session history.`,
+          "warning",
+        );
+      }
+    }
+  }
+}

package/src/extension/session-view.ts

@@ -0,0 +1,131 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SqliteControllerStore } from "../controllers/sqlite.js";
+import { workflowStatePath } from "../state/database.js";
+import { WorkflowRunStore, type LoadedWorkflowRun } from "../workflows/store.js";
+import { buildWidgetView } from "./widget.js";
+
+const WIDGET_KEY = "pi-workflows";
+const WIDGET_SCROLL_STEP = 3;
+
+/** Read-only projection of the host-owned run into the origin Pi session. */
+export class SessionWorkflowView {
+  private loaded: LoadedWorkflowRun | undefined;
+  private scroll: number | null = null;
+  private shownScroll = 0;
+  private maxScroll = 0;
+  private stepCount = 0;
+  private visible = false;
+
+  refresh(ctx: ExtensionContext): void {
+    const loaded = loadSessionRun(ctx.sessionManager.getSessionId());
+    if (loaded === undefined) {
+      this.clear(ctx);
+      return;
+    }
+    if (this.loaded?.runId !== loaded.runId || this.stepCount !== loaded.state.steps.length) {
+      this.scroll = null;
+      this.stepCount = loaded.state.steps.length;
+    }
+    this.loaded = loaded;
+    this.render(ctx);
+  }
+
+  scrollUp(ctx: ExtensionContext): void {
+    this.scrollBy(ctx, -WIDGET_SCROLL_STEP);
+  }
+
+  scrollDown(ctx: ExtensionContext): void {
+    this.scrollBy(ctx, WIDGET_SCROLL_STEP);
+  }
+
+  clear(ctx: ExtensionContext): void {
+    this.loaded = undefined;
+    this.scroll = null;
+    this.shownScroll = 0;
+    this.maxScroll = 0;
+    this.stepCount = 0;
+    if (!this.visible) return;
+    this.visible = false;
+    safelyUpdateUi(ctx, () => {
+      ctx.ui.setWidget(WIDGET_KEY, undefined);
+      ctx.ui.setStatus(WIDGET_KEY, undefined);
+    });
+  }
+
+  private scrollBy(ctx: ExtensionContext, delta: number): void {
+    if (this.loaded === undefined) return;
+    const current = this.scroll ?? this.shownScroll;
+    this.scroll = Math.max(0, Math.min(this.maxScroll, current + delta));
+    this.render(ctx);
+  }
+
+  private render(ctx: ExtensionContext): void {
+    const loaded = this.loaded;
+    if (loaded === undefined) return;
+    const render = (
+      width = Number.POSITIVE_INFINITY,
+      theme?: Parameters<typeof buildWidgetView>[6],
+    ) => {
+      const view = buildWidgetView(
+        loaded.state,
+        loaded.snapshot,
+        new Date(),
+        this.scroll,
+        loaded.state.paused === true,
+        width,
+        theme,
+        undefined,
+      );
+      this.shownScroll = view.scroll;
+      this.maxScroll = view.maxScroll;
+      if (this.scroll !== null) this.scroll = view.scroll;
+      return view.lines;
+    };
+    safelyUpdateUi(ctx, () => {
+      if (ctx.mode === "tui") {
+        ctx.ui.setWidget(WIDGET_KEY, (_tui, theme) => ({
+          render: (width) => render(width, theme),
+          invalidate() {},
+        }));
+      } else {
+        ctx.ui.setWidget(WIDGET_KEY, render());
+      }
+      const label = loaded.state.paused === true ? "paused" : loaded.state.status;
+      ctx.ui.setStatus(WIDGET_KEY, `${loaded.state.workflowName} [${label}]`);
+      this.visible = true;
+    });
+  }
+}
+
+function loadSessionRun(sessionId: string): LoadedWorkflowRun | undefined {
+  try {
+    const queue = new SqliteControllerStore(workflowStatePath(), {
+      readOnly: true,
+      global: true,
+    });
+    let runId: string | undefined;
+    try {
+      runId = queue.findSessionReservation(sessionId)?.runId;
+    } finally {
+      queue.close();
+    }
+    if (runId === undefined) return undefined;
+
+    const runs = new WorkflowRunStore(workflowStatePath(), { readOnly: true });
+    try {
+      return runs.readRun(runId) ?? undefined;
+    } finally {
+      runs.close();
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+function safelyUpdateUi(ctx: ExtensionContext, update: () => void): void {
+  try {
+    if (ctx.hasUI) update();
+  } catch {
+    // A session replacement can make a captured context stale between polls.
+  }
+}

package/src/extension/widget.ts

@@ -86,7 +86,7 @@ export function buildWidgetView(
   // `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;
-  const glyph = paused ? "⏸" : STATUS_GLYPHS[state.status];
+  const glyph = paused ? "⏸" : (STATUS_GLYPHS[state.status] ?? "·");
   const statusText = paused ? "paused" : state.status;
   // Titles, status details, and errors can carry model- or shell-controlled
   // text; never let escape sequences or newlines reach the terminal.
@@ -398,7 +398,7 @@ function elapsedSince(startedAt: string | undefined, now: Date): string | null {
   return formatDuration(Math.max(0, now.getTime() - started));
 }
 
-function statusTone(status: WorkflowRunStatus): ThemeColor {
+function statusTone(status: string): ThemeColor {
   switch (status) {
     case "completed":
       return "success";
@@ -409,6 +409,7 @@ function statusTone(status: WorkflowRunStatus): ThemeColor {
     case "waiting":
       return "warning";
     case "running":
+    default:
       return "accent";
   }
 }

package/src/host/runner.ts

@@ -526,14 +526,37 @@ export class WorkflowHost {
       case "run.pause": {
         const runId = requireRunId(request);
         const active = this.activeRuns.get(runId);
-        if (active === undefined) return { outcome: "rejected", error: "Run is not active" };
-        this.commitActivePause(active);
-        active.control = "pause";
-        afterCommit.push(() => void active.supervisor.stop("cancelled"));
-        return { outcome: "accepted", receipt: { runId, status: "parked", paused: true } };
+        if (active !== undefined) {
+          if (active.control === "pause") {
+            return { outcome: "adopted", receipt: { runId, status: "parked", paused: true } };
+          }
+          if (active.control === "handoff") {
+            const paused = this.queue.pauseParkedWorkflowRun({ runId });
+            return paused
+              ? { outcome: "accepted", receipt: { runId, status: "parked", paused: true } }
+              : { outcome: "rejected", error: "Run handoff is not pausable" };
+          }
+          if (active.control !== undefined) {
+            return { outcome: "rejected", error: `Run is already handling ${active.control}` };
+          }
+          this.commitActivePause(active);
+          active.control = "pause";
+          afterCommit.push(() => void active.supervisor.stop("cancelled"));
+          return { outcome: "accepted", receipt: { runId, status: "parked", paused: true } };
+        }
+        const paused = this.queue.pauseParkedWorkflowRun({ runId });
+        return paused
+          ? { outcome: "accepted", receipt: { runId, status: "parked", paused: true } }
+          : { outcome: "rejected", error: "Run is not pausable" };
       }
       case "run.resume": {
         const runId = requireRunId(request);
+        if (this.queue.resumePausedInteraction({ runId })) {
+          return {
+            outcome: "accepted",
+            receipt: { runId, status: "parked", paused: false, waitingForInteraction: true },
+          };
+        }
         if (this.activeRuns.has(runId) || this.pendingStarts.has(runId)) {
           return { outcome: "adopted", receipt: { runId, active: true } };
         }
@@ -570,20 +593,27 @@ export class WorkflowHost {
       case "interaction.update": {
         const payload = requireRecord(request.payload, "interaction update payload");
         if (payload.claimPresentation === true) {
-          const interaction = this.hostState.claimInteractionPresentation({
-            requestId: requireString(payload.requestId, "requestId"),
-            expectedRevision: requireNonNegativeInteger(
-              request.expectedRevision,
-              "expectedRevision",
-            ),
-            presenterId: request.clientId,
-            leaseMs: PRESENTATION_CLAIM_LEASE_MS,
-          });
-          return {
-            outcome: "accepted",
-            revision: interaction.revision,
-            receipt: interaction as unknown as JsonValue,
-          };
+          try {
+            const interaction = this.hostState.claimInteractionPresentation({
+              requestId: requireString(payload.requestId, "requestId"),
+              expectedRevision: requireNonNegativeInteger(
+                request.expectedRevision,
+                "expectedRevision",
+              ),
+              presenterId: request.clientId,
+              leaseMs: PRESENTATION_CLAIM_LEASE_MS,
+            });
+            return {
+              outcome: "accepted",
+              revision: interaction.revision,
+              receipt: interaction as unknown as JsonValue,
+            };
+          } catch (error) {
+            if (errorMessage(error) === "Interactive request presentation claim conflict") {
+              return { outcome: "conflict", error: errorMessage(error) };
+            }
+            throw error;
+          }
         }
         if (typeof payload.sessionEntryId === "string") {
           const interaction = this.hostState.markInteractionPresented({
@@ -722,17 +752,18 @@ export class WorkflowHost {
     };
   }
 
-  private rememberDeliveryClaim(options: Omit<DeliveryClaim, "expiresAt">): string {
+  private rememberDeliveryClaim(options: Omit<DeliveryClaim, "expiresAt">): {
+    claimId: string;
+    claimExpiresAt: string;
+  } {
     const now = Date.now();
     for (const [claimId, claim] of this.deliveryClaims) {
       if (claim.expiresAt <= now) this.deliveryClaims.delete(claimId);
     }
     const claimId = randomUUID();
-    this.deliveryClaims.set(claimId, {
-      ...options,
-      expiresAt: now + DELIVERY_CLAIM_LEASE_MS,
-    });
-    return claimId;
+    const expiresAt = now + DELIVERY_CLAIM_LEASE_MS;
+    this.deliveryClaims.set(claimId, { ...options, expiresAt });
+    return { claimId, claimExpiresAt: new Date(expiresAt).toISOString() };
   }
 
   private deliveryClaim(
@@ -757,8 +788,39 @@ export class WorkflowHost {
     return claim;
   }
 
+  private validateDelivery(
+    command: HostRequest,
+    payload: Record<string, unknown>,
+    kind: DeliveryClaim["kind"],
+  ): Omit<HostResponse, "schema" | "requestId"> {
+    const resourceId = requireString(payload.resourceId, "resourceId");
+    const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
+    const claimId = requireString(payload.claimId, "claimId");
+    const claim = this.deliveryClaim(claimId, command.clientId, kind, resourceId, targetSessionId);
+    if (claim === undefined) {
+      return { outcome: "accepted", receipt: { claimId, live: false } };
+    }
+    const live =
+      kind === "notification"
+        ? this.queue.isWorkflowNotificationClaimLive({
+            notificationId: resourceId,
+            targetSessionId,
+            claimToken: claim.token,
+          })
+        : this.queue.isWorkflowTurnIntentClaimLive({
+            intentId: resourceId,
+            targetSessionId,
+            claimToken: claim.token,
+          });
+    if (!live) this.deliveryClaims.delete(claimId);
+    return { outcome: "accepted", receipt: { claimId, live } };
+  }
+
   private claimNotification(command: HostRequest): Omit<HostResponse, "schema" | "requestId"> {
     const payload = requireRecord(command.payload, "notification claim payload");
+    if (payload.validateClaim === true) {
+      return this.validateDelivery(command, payload, "notification");
+    }
     const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
     const token = randomUUID();
     const notification = this.queue.claimPendingWorkflowNotifications({
@@ -770,7 +832,7 @@ export class WorkflowHost {
     if (notification === undefined) {
       return { outcome: "accepted", receipt: { notification: null } };
     }
-    const claimId = this.rememberDeliveryClaim({
+    const claim = this.rememberDeliveryClaim({
       clientId: command.clientId,
       token,
       targetSessionId,
@@ -779,7 +841,7 @@ export class WorkflowHost {
     });
     return {
       outcome: "accepted",
-      receipt: { claimId, notification } as unknown as JsonValue,
+      receipt: { ...claim, notification } as unknown as JsonValue,
     };
   }
 
@@ -811,6 +873,9 @@ export class WorkflowHost {
 
   private claimTurn(command: HostRequest): Omit<HostResponse, "schema" | "requestId"> {
     const payload = requireRecord(command.payload, "turn claim payload");
+    if (payload.validateClaim === true) {
+      return this.validateDelivery(command, payload, "turn");
+    }
     const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
     const token = randomUUID();
     const intent = this.queue.claimEligibleWorkflowTurnIntents({
@@ -822,7 +887,7 @@ export class WorkflowHost {
     if (intent === undefined) {
       return { outcome: "accepted", receipt: { turn: null } };
     }
-    const claimId = this.rememberDeliveryClaim({
+    const claim = this.rememberDeliveryClaim({
       clientId: command.clientId,
       token,
       targetSessionId,
@@ -831,7 +896,7 @@ export class WorkflowHost {
     });
     return {
       outcome: "accepted",
-      receipt: { claimId, turn: intent } as unknown as JsonValue,
+      receipt: { ...claim, turn: intent } as unknown as JsonValue,
     };
   }
 
@@ -913,6 +978,9 @@ export class WorkflowHost {
     if (interaction === undefined || interaction.kind !== "decision") {
       return { outcome: "notFound", error: `Decision request not found: ${requestId}` };
     }
+    if (this.queue.isWorkflowRunPaused(interaction.runId)) {
+      return { outcome: "conflict", error: "Workflow run is paused" };
+    }
     const request = interaction.contract as unknown as HumanDecisionRequest;
     const response = payload.response as HumanDecisionResponse;
     const accepted = this.decisions.acceptSync(request, {
@@ -1085,6 +1153,9 @@ export class WorkflowHost {
     if (interaction === undefined || interaction.runId !== runId) {
       return { outcome: "notFound", error: `Interactive request not found: ${requestId}` };
     }
+    if (this.queue.isWorkflowRunPaused(runId)) {
+      return { outcome: "conflict", error: "Workflow run is paused" };
+    }
     const attemptId = requireString(payload.attempt, "attempt");
     const nodeId = requireString(payload.step, "step");
     const storedContract = requireRecord(interaction.contract, "interactive contract");
@@ -1148,6 +1219,9 @@ export class WorkflowHost {
     if (current === undefined || current.runId !== requireRunId(request)) {
       return { outcome: "notFound", error: `Interactive request not found: ${requestId}` };
     }
+    if (this.queue.isWorkflowRunPaused(current.runId)) {
+      return { outcome: "conflict", error: "Workflow run is paused" };
+    }
     const attemptId = requireString(payload.attempt, "attempt");
     const nodeId = requireString(payload.step, "step");
     const storedContract = requireRecord(current.contract, "interactive contract");

package/src/host/state.ts

@@ -65,6 +65,8 @@ export type InteractiveRequestRecord = {
   contract: JsonValue;
   revision: number;
   status: "pending" | "presenting" | "settled" | "cancelled";
+  presenterId: string | null;
+  presentationClaimExpiresAt: string | null;
   presentationSessionEntryId: string | null;
   acceptedSubmissionId: string | null;
   createdAt: string;
@@ -676,7 +678,7 @@ export class HostStateStore {
          WHERE request_id = ? AND revision = ? AND presentation_session_entry_id IS NULL
            AND (
              status = 'pending'
-             OR (status = 'presenting' AND (presenter_id = ? OR presentation_claim_expires_at <= ?))
+             OR (status = 'presenting' AND presentation_claim_expires_at <= ?)
            )`,
       )
       .run(
@@ -685,7 +687,6 @@ export class HostStateStore {
         now,
         options.requestId,
         options.expectedRevision,
-        options.presenterId,
         now,
       );
     if (changed.changes !== 1) throw new Error("Interactive request presentation claim conflict");
@@ -887,7 +888,9 @@ export class HostStateStore {
       .prepare(
         `SELECT request_id AS requestId, run_id AS runId, attempt_id AS attemptId,
                 target_session_id AS targetSessionId, kind, contract_hash AS contractHash,
-                revision, status, presentation_session_entry_id AS presentationSessionEntryId,
+                revision, status, presenter_id AS presenterId,
+                presentation_claim_expires_at AS presentationClaimExpiresAt,
+                presentation_session_entry_id AS presentationSessionEntryId,
                 accepted_submission_id AS acceptedSubmissionId, created_at AS createdAt,
                 updated_at AS updatedAt, settled_at AS settledAt, consumed_at AS consumedAt
          FROM interactive_requests WHERE request_id = ?`,
@@ -903,6 +906,8 @@ export class HostStateStore {
       contract: this.state.readJson(row.contractHash),
       revision: row.revision,
       status: row.status,
+      presenterId: row.presenterId,
+      presentationClaimExpiresAt: iso(row.presentationClaimExpiresAt),
       presentationSessionEntryId: row.presentationSessionEntryId,
       acceptedSubmissionId: row.acceptedSubmissionId,
       createdAt: new Date(row.createdAt).toISOString(),
@@ -998,6 +1003,8 @@ type InteractiveRequestRow = {
   contractHash: Buffer;
   revision: number;
   status: InteractiveRequestRecord["status"];
+  presenterId: string | null;
+  presentationClaimExpiresAt: number | null;
   presentationSessionEntryId: string | null;
   acceptedSubmissionId: string | null;
   createdAt: number;
@@ -1116,6 +1123,8 @@ function isInteractiveRequestRow(value: unknown): value is InteractiveRequestRow
     Buffer.isBuffer(value.contractHash) &&
     typeof value.revision === "number" &&
     ["pending", "presenting", "settled", "cancelled"].includes(value.status as string) &&
+    nullableString(value.presenterId) &&
+    nullableNumber(value.presentationClaimExpiresAt) &&
     nullableString(value.presentationSessionEntryId) &&
     nullableString(value.acceptedSubmissionId) &&
     typeof value.createdAt === "number" &&