@osolmaz/pi-workflows 0.15.2 → 0.16.0

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,154 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowSessionView } from "../client/view.js";
+import type { WorkflowDefinitionSnapshot, WorkflowRunState } from "../workflows/types.js";
+import { buildWidgetView } from "./widget.js";
+
+const WIDGET_KEY = "pi-workflows";
+const WIDGET_SCROLL_STEP = 3;
+
+/** Client-backed projection of the host-owned run into the origin Pi session. */
+export class SessionWorkflowView {
+  private session: WorkflowSessionView | null = null;
+  private scroll: number | null = null;
+  private shownScroll = 0;
+  private maxScroll = 0;
+  private stepCount = 0;
+  private visible = false;
+  private actionHint: string | undefined;
+
+  update(session: WorkflowSessionView, ctx: ExtensionContext): void {
+    const run = session.run;
+    if (
+      run === null ||
+      !isWorkflowRunState(run.state) ||
+      !isWorkflowDefinitionSnapshot(run.workflow)
+    ) {
+      this.session = session;
+      this.clearWidget(ctx);
+      return;
+    }
+    const previousRun = this.session?.run;
+    if (previousRun?.runId !== run.runId || this.stepCount !== run.state.steps.length) {
+      this.scroll = null;
+      this.stepCount = run.state.steps.length;
+    }
+    this.session = session;
+    this.render(ctx);
+  }
+
+  setActionHint(hint: string | undefined, ctx: ExtensionContext): void {
+    this.actionHint = hint;
+    if (this.session?.run !== null) this.render(ctx);
+  }
+
+  refresh(ctx: ExtensionContext): void {
+    if (this.session?.run === null || this.session === null) {
+      this.clearWidget(ctx);
+      return;
+    }
+    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.session = null;
+    this.scroll = null;
+    this.shownScroll = 0;
+    this.maxScroll = 0;
+    this.stepCount = 0;
+    this.clearWidget(ctx);
+  }
+
+  private scrollBy(ctx: ExtensionContext, delta: number): void {
+    if (this.session?.run === null || this.session === null) return;
+    const current = this.scroll ?? this.shownScroll;
+    this.scroll = Math.max(0, Math.min(this.maxScroll, current + delta));
+    this.render(ctx);
+  }
+
+  private clearWidget(ctx: ExtensionContext): void {
+    if (!this.visible) return;
+    this.visible = false;
+    safelyUpdateUi(ctx, () => {
+      ctx.ui.setWidget(WIDGET_KEY, undefined);
+      ctx.ui.setStatus(WIDGET_KEY, undefined);
+    });
+  }
+
+  private render(ctx: ExtensionContext): void {
+    const run = this.session?.run;
+    if (run === null || run === undefined) return;
+    if (!isWorkflowRunState(run.state) || !isWorkflowDefinitionSnapshot(run.workflow)) return;
+    const state = run.state;
+    const snapshot = run.workflow;
+    const render = (
+      width = Number.POSITIVE_INFINITY,
+      theme?: Parameters<typeof buildWidgetView>[6],
+    ) => {
+      const view = buildWidgetView(
+        state,
+        snapshot,
+        new Date(),
+        this.scroll,
+        run.display.status === "paused",
+        width,
+        theme,
+        undefined,
+        this.actionHint,
+        run.display.status,
+      );
+      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());
+      }
+      ctx.ui.setStatus(WIDGET_KEY, `${state.workflowName} [${run.display.status}]`);
+      this.visible = true;
+    });
+  }
+}
+
+function isWorkflowRunState(value: unknown): value is WorkflowRunState {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    (value as { schema?: unknown }).schema === "pi-workflows.run-state.v1" &&
+    typeof (value as { workflowName?: unknown }).workflowName === "string" &&
+    Array.isArray((value as { steps?: unknown }).steps)
+  );
+}
+
+function isWorkflowDefinitionSnapshot(value: unknown): value is WorkflowDefinitionSnapshot {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    (value as { schema?: unknown }).schema === "pi-workflows.definition-snapshot.v1" &&
+    typeof (value as { nodes?: unknown }).nodes === "object"
+  );
+}
+
+function safelyUpdateUi(ctx: ExtensionContext, update: () => void): void {
+  try {
+    if (ctx.hasUI) update();
+  } catch {
+    // A session replacement can make a captured context stale between updates.
+  }
+}

package/src/extension/widget.ts

@@ -1,5 +1,6 @@
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { WorkflowDisplayStatus } from "../client/view.js";
 import { formatDuration } from "../render/format.js";
 import { nodeTypeGlyph } from "../render/node-type.js";
 import {
@@ -14,17 +15,19 @@ import { sanitizeText } from "../workflows/text.js";
 import type {
   WorkflowDefinitionSnapshot,
   WorkflowRunState,
-  WorkflowRunStatus,
   WorkflowUpdateRecord,
 } from "../workflows/types.js";
 
-const STATUS_GLYPHS: Record<WorkflowRunStatus, string> = {
+const STATUS_GLYPHS: Record<WorkflowDisplayStatus, string> = {
+  queued: "…",
   running: "◐",
-  waiting: "⏸",
+  waiting: "○",
+  paused: "⏸",
   completed: "✓",
   failed: "✗",
   timed_out: "✗",
   cancelled: "✗",
+  ambiguous: "!",
 };
 
 /**
@@ -79,26 +82,28 @@ export function buildWidgetView(
   theme?: WidgetTheme,
   updateHistory?: WorkflowUpdateRecord[],
   actionHint?: string,
+  displayStatus?: WorkflowDisplayStatus,
 ): WidgetView {
   const availableWidth = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : width;
   if (availableWidth === 0) return { lines: [], 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;
-  const glyph = paused ? "⏸" : STATUS_GLYPHS[state.status];
-  const statusText = paused ? "paused" : state.status;
+  const status = displayStatus ?? (held || state.paused === true ? "paused" : state.status);
+  const paused = status === "paused";
+  const glyph = STATUS_GLYPHS[status];
+  const statusText = status;
   // Titles, status details, and errors can carry model- or shell-controlled
   // text; never let escape sequences or newlines reach the terminal.
   const title = state.runTitle ? ` — ${sanitizeText(state.runTitle)}` : "";
-  const headerTone = statusTone(paused ? "waiting" : state.status);
+  const headerTone = statusTone(status);
   const header = `${paint(theme, headerTone, glyph)} workflow ${sanitizeText(state.workflowName)}${title} ${paint(theme, headerTone, `[${statusText}]`)}`;
 
   const footer: string[] = [];
   if (state.error) {
     footer.push(paint(theme, "error", `  error: ${truncate(sanitizeText(state.error), 120)}`));
   }
-  if (state.status === "waiting" && state.waitingOn) {
+  if (status === "waiting" && state.waitingOn) {
     footer.push(
       paint(theme, "warning", `  waiting on checkpoint: ${sanitizeText(state.waitingOn)}`),
     );
@@ -398,7 +403,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";
@@ -407,8 +412,12 @@ function statusTone(status: WorkflowRunStatus): ThemeColor {
     case "cancelled":
       return "error";
     case "waiting":
+    case "paused":
       return "warning";
+    case "ambiguous":
+      return "error";
     case "running":
+    default:
       return "accent";
   }
 }

package/src/host/child-worker-supervisor.ts

@@ -1,8 +1,8 @@
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { once } from "node:events";
+import { NdjsonFrameDecoder } from "../client/protocol.js";
 import { errorMessage } from "../workflows/errors.js";
 import { HostProcessRegistry, type ProcessIdentity } from "./processes.js";
-import { NdjsonFrameDecoder } from "./protocol.js";
 import type { WorkerOutcome } from "./state.js";
 
 const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;

package/src/host/resolver-entry.ts

@@ -3,6 +3,12 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { builtinWorkflowCatalog } from "../builtins/catalog.js";
+import { MAX_PROTOCOL_MESSAGE_BYTES } from "../client/protocol.js";
+import type {
+  ResolvedControllerInitialization,
+  ResolvedSettingsChange,
+  ResolvedWorkflowLaunch,
+} from "../client/resolver.js";
 import { discoverControllers, loadControllerFile } from "../controllers/loader.js";
 import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
 import { compositionMetadata } from "../workflows/composition.js";
@@ -12,32 +18,11 @@ import { resolveWorkflowRef } from "../workflows/loader.js";
 import { applyWorkflowSettingsPatch } from "../workflows/settings.js";
 import { createDefinitionSnapshot } from "../workflows/store.js";
 import type { WorkflowDefinition, WorkflowSource } from "../workflows/types.js";
-import { MAX_PROTOCOL_MESSAGE_BYTES } from "./protocol.js";
-
-export type ResolvedWorkflowLaunch = {
-  schema: "pi-workflows.resolved-launch.v1";
-  workflowName: string;
-  workflowSourceRef: string;
-  workflowSource: JsonValue;
-  definitionDigest: string;
-  definitionSnapshot: JsonValue;
-};
-
-export type ResolvedControllerInitialization = {
-  schema: "pi-workflows.resolved-controller-initialization.v1";
-  controllerName: string;
-  controllerPath: string;
-  sourceHash: string;
-  initialStatus: JsonValue;
-};
-
-export type ResolvedSettingsChange = {
-  schema: "pi-workflows.resolved-settings-change.v1";
-  definitionDigest: string;
-  patch: JsonValue;
-  settings: JsonValue;
-  paths: JsonValue;
-};
+export type {
+  ResolvedControllerInitialization,
+  ResolvedSettingsChange,
+  ResolvedWorkflowLaunch,
+} from "../client/resolver.js";
 
 type ResolverRequest = {
   schema: "pi-workflows.resolve-request.v1";