@osolmaz/pi-workflows 0.15.2 → 0.15.3

package/src/extension/index.ts

@@ -14,6 +14,7 @@ import { createRunId, WorkflowRunStore } from "../workflows/store.js";
 import type { AgentStepContract, HumanDecisionResponse } from "../workflows/types.js";
 import { parseControllerArgs, type ParsedControllerArgs } from "./controller-command.js";
 import { SessionDeliveryCoordinator, type ClaimedSessionDelivery } from "./session-delivery.js";
+import { SessionWorkflowView } from "./session-view.js";
 import {
   recoverAssistantStep,
   registerWorkflowAgentStepMessageRenderer,
@@ -133,6 +134,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let presentationTail = Promise.resolve();
   let toolTail = Promise.resolve();
   const sessionDelivery = new SessionDeliveryCoordinator();
+  const sessionView = new SessionWorkflowView();
 
   const presentInOrder = async (ctx: ExtensionContext): Promise<void> => {
     const prior = presentationTail;
@@ -148,6 +150,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         () => claimPendingTurnDelivery(pi, client, ctx),
       ]);
     } finally {
+      sessionView.refresh(ctx);
       release?.();
     }
   };
@@ -268,6 +271,16 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerShortcut("shift+up", {
+    description: "Scroll the workflow widget up",
+    handler: (ctx) => sessionView.scrollUp(ctx),
+  });
+
+  pi.registerShortcut("shift+down", {
+    description: "Scroll the workflow widget down",
+    handler: (ctx) => sessionView.scrollDown(ctx),
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     sessionContext = ctx;
     try {
@@ -282,6 +295,44 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     pollTimer.unref?.();
   });
 
+  pi.on("agent_end", async (event, ctx) => {
+    const interrupted =
+      ctx.signal?.aborted === true ||
+      event.messages.some(
+        (message) =>
+          isRecord(message) && "stopReason" in message && message.stopReason === "aborted",
+      );
+    if (!interrupted) return;
+    const interaction = pendingInteractionForSession(ctx.sessionManager.getSessionId());
+    if (
+      interaction === undefined ||
+      interaction.kind === "decision" ||
+      workflowRunPaused(interaction.runId)
+    ) {
+      return;
+    }
+    const turnHasPrompt = event.messages.some(
+      (message) => interactionRequestId(message) === interaction.requestId,
+    );
+    if (!turnHasPrompt) return;
+    try {
+      const pauseId = `escape-pause-${interaction.runId}-${randomUUID()}`;
+      await requestAccepted(client, {
+        operation: "run.pause",
+        requestId: pauseId,
+        idempotencyKey: pauseId,
+        runId: interaction.runId,
+      });
+      sessionView.refresh(ctx);
+      ctx.ui.notify(
+        `Workflow ${interaction.runId} paused because its model turn was interrupted. Use /workflow resume to continue.`,
+        "info",
+      );
+    } catch (error) {
+      ctx.ui.notify(`Could not pause interrupted workflow: ${errorMessage(error)}`, "warning");
+    }
+  });
+
   pi.on("agent_settled", async (_event, ctx) => {
     try {
       await submitVisibleAssistantResponse(client, ctx);
@@ -291,9 +342,10 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     await presentInOrder(ctx).catch(() => undefined);
   });
 
-  pi.on("session_shutdown", async () => {
+  pi.on("session_shutdown", async (_event, ctx) => {
     sessionContext = null;
     sessionDelivery.clear();
+    sessionView.clear(ctx);
     if (pollTimer !== null) clearInterval(pollTimer);
     pollTimer = null;
   });
@@ -530,8 +582,17 @@ async function claimPendingInteractionDelivery(
     entryIdentifier(entries.find((entry) => interactionRequestId(entry) === interaction.requestId));
   const existingEntryId = findSessionEntryId(ctx.sessionManager.getBranch());
   let presentationRevision = interaction.revision;
+  let claimExpiresAt = Number.POSITIVE_INFINITY;
   if (existingEntryId === undefined) {
-    const claim = await requestAccepted(client, {
+    if (workflowRunPaused(interaction.runId)) return undefined;
+    if (
+      interaction.presentationClaimExpiresAt !== null &&
+      Date.parse(interaction.presentationClaimExpiresAt) > Date.now()
+    ) {
+      return undefined;
+    }
+    await client.ensureRunning();
+    const claim = await client.request({
       operation: "interaction.update",
       requestId: `claim-presentation-${interaction.requestId}-${interaction.revision}-${client.clientId}`,
       idempotencyKey: `claim-presentation-${interaction.requestId}-${interaction.revision}-${client.clientId}`,
@@ -539,13 +600,29 @@ async function claimPendingInteractionDelivery(
       expectedRevision: interaction.revision,
       payload: { requestId: interaction.requestId, claimPresentation: true },
     });
+    if (claim.outcome === "conflict") return undefined;
+    if (claim.outcome !== "accepted" && claim.outcome !== "adopted") {
+      throw new Error(claim.error ?? "Workflow host rejected interaction.update");
+    }
     if (claim.revision === undefined) throw new Error("Presentation claim has no revision");
+    const receipt = isRecord(claim.receipt) ? claim.receipt : undefined;
     presentationRevision = claim.revision;
+    claimExpiresAt = claimExpiry(receipt?.presentationClaimExpiresAt, "presentation claim");
   }
 
   const contract = interactionContract(interaction);
   return {
     deliveryId: `interaction:${interaction.requestId}`,
+    claimExpiresAt,
+    isStillDeliverable: () =>
+      existingEntryId === undefined &&
+      interactionPresentationClaimIsLive({
+        requestId: interaction.requestId,
+        runId: interaction.runId,
+        presenterId: client.clientId,
+        revision: presentationRevision,
+        claimExpiresAt,
+      }),
     findSessionEntryId,
     send: () => {
       if (interaction.kind === "decision") {
@@ -617,9 +694,18 @@ async function claimPendingNotificationDelivery(
   const notification = isRecord(receipt?.notification) ? receipt.notification : undefined;
   if (notification === undefined) return undefined;
   const claimId = requireText(receipt?.claimId, "notification claimId");
+  const claimExpiresAt = claimExpiry(receipt?.claimExpiresAt, "notification claim");
   const notificationId = requireText(notification.notificationId, "notificationId");
   return {
     deliveryId: `notification:${notificationId}`,
+    claimExpiresAt,
+    isStillDeliverable: () =>
+      hostDeliveryClaimIsLive(client, {
+        kind: "notification",
+        resourceId: notificationId,
+        targetSessionId: sessionId,
+        claimId,
+      }),
     findSessionEntryId: (entries) =>
       entryIdentifier(
         entries.find(
@@ -678,12 +764,21 @@ async function claimPendingTurnDelivery(
   const turn = isRecord(receipt?.turn) ? receipt.turn : undefined;
   if (turn === undefined) return undefined;
   const claimId = requireText(receipt?.claimId, "turn claimId");
+  const claimExpiresAt = claimExpiry(receipt?.claimExpiresAt, "turn claim");
   const intentId = requireText(turn.intentId, "turn intentId");
   const runId = requireText(turn.runId, "turn runId");
   const state = terminalRunState(runId);
   if (state === undefined) return undefined;
   return {
     deliveryId: `turn:${intentId}`,
+    claimExpiresAt,
+    isStillDeliverable: () =>
+      hostDeliveryClaimIsLive(client, {
+        kind: "turn",
+        resourceId: intentId,
+        targetSessionId: sessionId,
+        claimId,
+      }),
     findSessionEntryId: (entries) =>
       entryIdentifier(
         entries.find(
@@ -723,7 +818,13 @@ async function submitVisibleAssistantResponse(
   ctx: ExtensionContext,
 ): Promise<void> {
   const interaction = pendingInteractionForSession(ctx.sessionManager.getSessionId());
-  if (interaction === undefined || interaction.kind !== "assistant") return;
+  if (
+    interaction === undefined ||
+    interaction.kind !== "assistant" ||
+    workflowRunPaused(interaction.runId)
+  ) {
+    return;
+  }
   const contract = agentContract(interaction);
   if (contract === undefined) return;
   const submission = recoverAssistantStep(ctx.sessionManager.getBranch(), contract);
@@ -874,6 +975,65 @@ function terminalRunState(runId: string): Record<string, unknown> | undefined {
   }
 }
 
+function workflowRunPaused(runId: string): boolean {
+  return terminalRunState(runId)?.paused === true;
+}
+
+function interactionPresentationClaimIsLive(options: {
+  requestId: string;
+  runId: string;
+  presenterId: string;
+  revision: number;
+  claimExpiresAt: number;
+}): boolean {
+  try {
+    const store = new HostStateStore(workflowStatePath(), { readOnly: true });
+    try {
+      const interaction = store.getInteraction(options.requestId);
+      return (
+        interaction?.runId === options.runId &&
+        interaction.status === "presenting" &&
+        interaction.presenterId === options.presenterId &&
+        interaction.revision === options.revision &&
+        interaction.presentationSessionEntryId === null &&
+        interaction.presentationClaimExpiresAt !== null &&
+        Date.parse(interaction.presentationClaimExpiresAt) === options.claimExpiresAt &&
+        !workflowRunPaused(options.runId)
+      );
+    } finally {
+      store.close();
+    }
+  } catch {
+    return false;
+  }
+}
+
+async function hostDeliveryClaimIsLive(
+  client: WorkflowHostClient,
+  options: {
+    kind: "notification" | "turn";
+    resourceId: string;
+    targetSessionId: string;
+    claimId: string;
+  },
+): Promise<boolean> {
+  try {
+    const validationId = randomUUID();
+    const response = await client.request({
+      operation: options.kind === "notification" ? "notification.claim" : "turn.claim",
+      requestId: `delivery-validate-${options.claimId}-${validationId}`,
+      idempotencyKey: validationId,
+      payload: { ...options, validateClaim: true },
+    });
+    const receipt = isRecord(response.receipt) ? response.receipt : undefined;
+    return (
+      (response.outcome === "accepted" || response.outcome === "adopted") && receipt?.live === true
+    );
+  } catch {
+    return false;
+  }
+}
+
 function presentationMessage(
   turn: Record<string, unknown>,
   state: Record<string, unknown>,
@@ -929,6 +1089,12 @@ function requireText(value: unknown, name: string): string {
   return value;
 }
 
+function claimExpiry(value: unknown, name: string): number {
+  const expiry = Date.parse(requireText(value, `${name} expiry`));
+  if (!Number.isFinite(expiry)) throw new Error(`${name} expiry must be a timestamp`);
+  return expiry;
+}
+
 function activeSessionRun(ctx: ExtensionContext): WorkflowRunQueueRecord | undefined {
   return sessionRun(ctx);
 }
@@ -1023,7 +1189,11 @@ function agentContract(interaction: InteractiveRequestRecord): AgentStepContract
 }
 
 function interactionRequestId(value: unknown): string | undefined {
-  if (!isRecord(value) || value.type !== "custom_message" || !isRecord(value.details)) {
+  if (
+    !isRecord(value) ||
+    (value.type !== "custom_message" && value.role !== "custom") ||
+    !isRecord(value.details)
+  ) {
     return undefined;
   }
   return typeof value.details.requestId === "string" ? value.details.requestId : undefined;

package/src/extension/session-delivery.ts

@@ -2,6 +2,8 @@ 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>;
@@ -26,6 +28,7 @@ const SESSION_ENTRY_CONFIRMATION_MS = 10_000;
  */
 export class SessionDeliveryCoordinator {
   private readonly queued = new Map<string, QueuedSessionDelivery>();
+  private claimed: ClaimedSessionDelivery | undefined;
   private synchronizing = false;
 
   async synchronize(
@@ -36,6 +39,7 @@ export class SessionDeliveryCoordinator {
     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) {
@@ -44,32 +48,17 @@ export class SessionDeliveryCoordinator {
 
         const existingEntryId = delivery.findSessionEntryId(ctx.sessionManager.getBranch());
         if (existingEntryId !== undefined) {
-          await delivery.settle(existingEntryId);
+          if (delivery.claimExpiresAt <= Date.now()) return;
+          this.rememberQueued(delivery);
+          await this.settleDelivery(ctx, delivery.deliveryId, existingEntryId);
           return;
         }
 
-        // The host claim is asynchronous. Pi can start another turn while that
-        // request is in flight, so check again immediately before the
-        // synchronous send. An unused claim expires and is never sent later.
-        if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
-
-        this.queued.set(delivery.deliveryId, {
-          delivery,
-          queuedAt: Date.now(),
-          ambiguityReported: false,
-        });
-        try {
-          delivery.send();
-        } catch (error) {
-          this.queued.delete(delivery.deliveryId);
-          throw error;
-        }
-
-        const insertedEntryId = delivery.findSessionEntryId(ctx.sessionManager.getBranch());
-        if (insertedEntryId !== undefined) {
-          this.queued.delete(delivery.deliveryId);
-          await delivery.settle(insertedEntryId);
-        }
+        // 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 {
@@ -78,9 +67,63 @@ export class SessionDeliveryCoordinator {
   }
 
   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> {
@@ -103,9 +146,29 @@ export class SessionDeliveryCoordinator {
         }
         return true;
       }
-      this.queued.delete(deliveryId);
-      await queued.delivery.settle(sessionEntryId);
+      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";
   }
 }