@osolmaz/pi-workflows 0.15.3 → 0.16.1

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: "!",
 };
 
 /**
@@ -35,17 +38,28 @@ const STATUS_GLYPHS: Record<WorkflowRunStatus, string> = {
 const PI_MAX_WIDGET_LINES = 10;
 const MAX_NODE_ERROR_CHARS = 120;
 
-export function nodeGlyph(state: WorkflowRunState, nodeId: string): string {
-  if (state.currentNode === nodeId) {
+function displayedRunningNode(
+  state: WorkflowRunState,
+  displayStatus: WorkflowDisplayStatus | undefined,
+): string | undefined {
+  return state.currentNode ?? (displayStatus === "running" ? state.waitingOn : undefined);
+}
+
+export function nodeGlyph(
+  state: WorkflowRunState,
+  nodeId: string,
+  displayStatus?: WorkflowDisplayStatus,
+): string {
+  if (displayedRunningNode(state, displayStatus) === nodeId) {
     return "◐";
   }
+  if (state.waitingOn === nodeId) {
+    return "⏸";
+  }
   const result = state.results[nodeId];
   if (!result) {
     return "·";
   }
-  if (state.waitingOn === nodeId) {
-    return "⏸";
-  }
   return result.outcome === "ok" ? "✓" : "✗";
 }
 
@@ -79,35 +93,43 @@ export function buildWidgetView(
   theme?: WidgetTheme,
   updateHistory?: WorkflowUpdateRecord[],
   actionHint?: string,
+  displayStatus?: WorkflowDisplayStatus,
+  displayReason?: string | null,
+  controls?: readonly string[],
 ): 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 (displayReason) {
+    footer.push(paint(theme, "dim", `  ${sanitizeText(displayReason)}`));
+  }
+  if (controls !== undefined && controls.length > 0) {
+    footer.push(paint(theme, "dim", `  controls: ${controls.join(", ")}`));
+  }
   if (state.error) {
     footer.push(paint(theme, "error", `  error: ${truncate(sanitizeText(state.error), 120)}`));
   }
-  if (state.status === "waiting" && state.waitingOn) {
-    footer.push(
-      paint(theme, "warning", `  waiting on checkpoint: ${sanitizeText(state.waitingOn)}`),
-    );
+  if (status === "waiting" && state.waitingOn) {
+    footer.push(paint(theme, "warning", `  waiting on step: ${sanitizeText(state.waitingOn)}`));
   }
   const hint = actionHint?.trim() ? sanitizeText(actionHint) : undefined;
   const progress = progressLines(state, now, updateHistory).slice(0, 4);
   const baseBudget = PI_MAX_WIDGET_LINES - 1 - footer.length - progress.length;
   const nodes = displayNodeIds(snapshot).map((nodeId) =>
-    compactNodeLine(state, snapshot, nodeId, now, paused, theme),
+    compactNodeLine(state, snapshot, nodeId, now, paused, status, theme),
   );
   const combineHintWithWindow =
     hint !== undefined && nodes.length > 0 && nodes.length + 1 > baseBudget;
@@ -255,15 +277,17 @@ function compactNodeLine(
   nodeId: string,
   now: Date,
   paused: boolean,
+  displayStatus: WorkflowDisplayStatus,
   theme?: WidgetTheme,
 ): string {
   const node = snapshot.nodes[nodeId];
-  const glyph = nodeGlyph(state, nodeId);
+  const runningNode = displayedRunningNode(state, displayStatus);
+  const isCurrent = runningNode === nodeId;
+  const isWaiting = state.waitingOn === nodeId && !isCurrent;
+  const glyph = nodeGlyph(state, nodeId, displayStatus);
   const typeGlyph = node ? nodeTypeGlyph(node.nodeType, node.actionExecution) : "?";
   const name = sanitizeText(nodeId);
-  const segments = nodeRuntimeSegments(state, snapshot, nodeId, now);
-  const isCurrent = state.currentNode === nodeId;
-  const isWaiting = state.waitingOn === nodeId;
+  const segments = nodeRuntimeSegments(state, snapshot, nodeId, now, isCurrent);
 
   if (isCurrent || isWaiting) {
     const tone = paused || isWaiting ? "warning" : "accent";
@@ -296,6 +320,7 @@ function nodeRuntimeSegments(
   snapshot: WorkflowDefinitionSnapshot,
   nodeId: string,
   now: Date,
+  isCurrent: boolean,
 ): string[] {
   const segments: string[] = [];
   const node = snapshot.nodes[nodeId];
@@ -307,11 +332,11 @@ function nodeRuntimeSegments(
     segments.push("assistant response");
   }
   const completedAttempts = state.steps.filter((step) => step.nodeId === nodeId).length;
-  const attempts = completedAttempts + (state.currentNode === nodeId ? 1 : 0);
+  const attempts = completedAttempts + (isCurrent ? 1 : 0);
   if (attempts > 1) {
     segments.push(`↻${attempts}`);
   }
-  if (state.currentNode === nodeId && state.currentSettingsChangeNumber !== undefined) {
+  if (isCurrent && state.currentSettingsChangeNumber !== undefined) {
     segments.push(`settings ${state.currentSettingsChangeNumber}`);
   } else {
     const latest = state.steps.findLast((step) => step.nodeId === nodeId);
@@ -321,8 +346,8 @@ function nodeRuntimeSegments(
   }
 
   const result = state.results[nodeId];
-  if (state.currentNode === nodeId) {
-    if (state.statusDetail) {
+  if (isCurrent) {
+    if (state.currentNode === nodeId && state.statusDetail) {
       segments.push(sanitizeText(state.statusDetail));
     }
     const elapsed = elapsedSince(state.currentNodeStartedAt, now);
@@ -407,7 +432,10 @@ function statusTone(status: string): ThemeColor {
     case "cancelled":
       return "error";
     case "waiting":
+    case "paused":
       return "warning";
+    case "ambiguous":
+      return "error";
     case "running":
     default:
       return "accent";

package/src/extension/workflow-message-coordinator.ts

@@ -0,0 +1,334 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowClient } from "../client/client.js";
+import type { WorkflowSessionView, WorkflowTurnReport } from "../client/view.js";
+import type { JsonValue } from "../state/json.js";
+import type { WorkflowMessage, WorkflowTurnStopReason } from "../state/workflow-messages.js";
+
+const WORKFLOW_MESSAGE_ID_FIELD = "workflowMessageId";
+
+type PendingTurn = {
+  workflowTurnId: string;
+  workflowMessageId: string | null;
+  runId: string | null;
+  startedReported: boolean;
+  end: { stopReason: WorkflowTurnStopReason; responseSessionEntryId: string | null } | null;
+};
+
+/** Adds every host-owned workflow message to one Pi session through one public API path. */
+export class WorkflowMessageCoordinator {
+  private readonly queued = new Set<string>();
+  private readonly closedTurnMessages = new Set<string>();
+  private synchronizing = false;
+  private lastBranchEpoch: string | null = null;
+  private view: WorkflowSessionView | null = null;
+  private turn: PendingTurn | null = null;
+
+  updateView(view: WorkflowSessionView): void {
+    this.view = view;
+    const visibleIds = new Set(view.workflowMessages.map((message) => message.workflowMessageId));
+    for (const messageId of this.closedTurnMessages) {
+      if (!visibleIds.has(messageId)) this.closedTurnMessages.delete(messageId);
+    }
+    for (const message of view.workflowMessages) {
+      if (message.status === "sent" || message.status === "cancelled") {
+        this.queued.delete(message.workflowMessageId);
+      }
+    }
+    if (
+      this.turn !== null &&
+      this.turn.workflowMessageId === null &&
+      view.openWorkflowMessageId !== null
+    ) {
+      const message = messageById(view, view.openWorkflowMessageId);
+      if (message !== undefined && messageStartsTurn(message)) this.bindTurn(message);
+    }
+  }
+
+  branchChanged(): void {
+    this.lastBranchEpoch = null;
+  }
+
+  startTurn(): void {
+    if (this.turn !== null && this.turn.end === null) return;
+    this.turn = {
+      workflowTurnId: `workflow-turn-${randomUUID()}`,
+      workflowMessageId: null,
+      runId: null,
+      startedReported: false,
+      end: null,
+    };
+    const candidate = this.turnCandidate();
+    if (candidate !== undefined) this.bindTurn(candidate);
+  }
+
+  endTurn(stopReason: WorkflowTurnStopReason, responseSessionEntryId: string | null): void {
+    if (this.turn === null) this.startTurn();
+    if (this.turn !== null) this.turn.end = { stopReason, responseSessionEntryId };
+  }
+
+  activeTurnMessage(): WorkflowMessage | undefined {
+    if (this.view === null || this.turn?.workflowMessageId === null || this.turn === null) {
+      return undefined;
+    }
+    return messageById(this.view, this.turn.workflowMessageId);
+  }
+
+  async synchronize(
+    pi: ExtensionAPI,
+    client: WorkflowClient,
+    ctx: Pick<ExtensionContext, "hasPendingMessages" | "isIdle" | "sessionManager">,
+  ): Promise<void> {
+    if (this.synchronizing || this.view === null) return;
+    this.synchronizing = true;
+    try {
+      const view = this.view;
+      if (!view.coordinatorActive || view.coordinatorEpoch === null) return;
+      if (this.turn === null && !ctx.isIdle() && view.openWorkflowTurn !== null) {
+        this.turn = {
+          workflowTurnId: view.openWorkflowTurn.workflowTurnId,
+          workflowMessageId: view.openWorkflowTurn.workflowMessageId,
+          runId: view.openWorkflowTurn.runId,
+          startedReported: false,
+          end: null,
+        };
+      }
+      if (
+        view.branchReportRequired ||
+        this.lastBranchEpoch !== view.coordinatorEpoch ||
+        this.hasUnconfirmedBranchEntry(ctx, view)
+      ) {
+        await this.reportBranch(client, ctx, view);
+      }
+      await this.flushTurn(client, view);
+      const messageId = view.nextWorkflowMessageId;
+      if (messageId === null || this.queued.has(messageId)) return;
+      const message = messageById(view, messageId);
+      if (message === undefined || message.status !== "pending") return;
+      if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
+
+      this.queued.add(messageId);
+      const existingEntry = branchWorkflowEntries(ctx.sessionManager.getBranch()).get(messageId);
+      if (existingEntry !== undefined) {
+        await this.reportBranch(client, ctx, view);
+        return;
+      }
+
+      // There must be no asynchronous boundary between these final checks and
+      // the documented Pi sendMessage call.
+      if (
+        this.view !== view ||
+        !view.coordinatorActive ||
+        view.coordinatorEpoch === null ||
+        view.nextWorkflowMessageId !== messageId ||
+        !ctx.isIdle() ||
+        ctx.hasPendingMessages() ||
+        branchWorkflowEntries(ctx.sessionManager.getBranch()).has(messageId)
+      ) {
+        this.queued.delete(messageId);
+        return;
+      }
+      try {
+        pi.sendMessage(
+          {
+            customType: message.content.customType,
+            content: message.content.content,
+            display: message.content.display,
+            details: message.content.details,
+          },
+          { triggerTurn: message.content.triggerTurn },
+        );
+      } catch (error) {
+        this.queued.delete(messageId);
+        throw error;
+      }
+      await this.reportBranch(client, ctx, view);
+      await this.flushTurn(client, view);
+    } finally {
+      this.synchronizing = false;
+    }
+  }
+
+  clear(): void {
+    this.queued.clear();
+    this.closedTurnMessages.clear();
+    this.view = null;
+    this.turn = null;
+    this.lastBranchEpoch = null;
+    this.synchronizing = false;
+  }
+
+  private turnCandidate(): WorkflowMessage | undefined {
+    const view = this.view;
+    if (view === null) return undefined;
+    if (view.openWorkflowMessageId !== null) {
+      const open = messageById(view, view.openWorkflowMessageId);
+      if (
+        open !== undefined &&
+        !this.closedTurnMessages.has(open.workflowMessageId) &&
+        messageStartsTurn(open)
+      ) {
+        return open;
+      }
+    }
+    for (const messageId of this.queued) {
+      const queued = messageById(view, messageId);
+      if (queued?.status === "pending" && messageStartsTurn(queued)) return queued;
+    }
+    return undefined;
+  }
+
+  private bindTurn(message: WorkflowMessage): void {
+    if (this.turn === null) return;
+    this.turn.workflowMessageId = message.workflowMessageId;
+    this.turn.runId = message.runId;
+  }
+
+  private async flushTurn(client: WorkflowClient, view: WorkflowSessionView): Promise<void> {
+    const pending = this.turn;
+    if (
+      pending === null ||
+      pending.workflowMessageId === null ||
+      pending.runId === null ||
+      view.coordinatorEpoch === null ||
+      this.lastBranchEpoch !== view.coordinatorEpoch
+    ) {
+      return;
+    }
+    const message = messageById(view, pending.workflowMessageId);
+    if (message?.status !== "sent") return;
+    if (!pending.startedReported) {
+      await reportTurn(client, {
+        state: "started",
+        workflowMessageId: pending.workflowMessageId,
+        workflowTurnId: pending.workflowTurnId,
+        runId: pending.runId,
+        targetSessionId: view.sessionId,
+        coordinatorEpoch: view.coordinatorEpoch,
+      });
+      pending.startedReported = true;
+    }
+    if (pending.end === null) return;
+    await reportTurn(client, {
+      state: "ended",
+      workflowMessageId: pending.workflowMessageId,
+      workflowTurnId: pending.workflowTurnId,
+      runId: pending.runId,
+      targetSessionId: view.sessionId,
+      coordinatorEpoch: view.coordinatorEpoch,
+      stopReason: pending.end.stopReason,
+      responseSessionEntryId: pending.end.responseSessionEntryId,
+    });
+    if (message.kind === "terminal" || message.kind === "followUp") {
+      this.closedTurnMessages.add(pending.workflowMessageId);
+    }
+    for (const current of new Set([view, this.view])) {
+      if (current?.openWorkflowTurn?.workflowTurnId === pending.workflowTurnId) {
+        current.openWorkflowTurn = null;
+      }
+      if (
+        current?.openWorkflowMessageId === pending.workflowMessageId &&
+        (message.kind === "terminal" || message.kind === "followUp")
+      ) {
+        current.openWorkflowMessageId = null;
+      }
+    }
+    this.turn = null;
+  }
+
+  private async reportBranch(
+    client: WorkflowClient,
+    ctx: Pick<ExtensionContext, "hasPendingMessages" | "isIdle" | "sessionManager">,
+    view: WorkflowSessionView,
+  ): Promise<void> {
+    if (view.coordinatorEpoch === null) return;
+    const allowed = new Set(view.workflowMessages.map((message) => message.workflowMessageId));
+    const branch = branchWorkflowEntries(ctx.sessionManager.getBranch());
+    const entries = [...branch]
+      .filter(([workflowMessageId]) => allowed.has(workflowMessageId))
+      .map(([workflowMessageId, piSessionEntryId]) => ({ workflowMessageId, piSessionEntryId }));
+    const isIdle = ctx.isIdle();
+    const hasPendingMessages = ctx.hasPendingMessages();
+    const response = await client.request({
+      operation: "workflowMessage.reportBranch",
+      payload: {
+        targetSessionId: view.sessionId,
+        coordinatorEpoch: view.coordinatorEpoch,
+        entries,
+        isIdle,
+        hasPendingMessages,
+      },
+    });
+    if (response.outcome !== "accepted" && response.outcome !== "adopted") {
+      throw new Error(response.error ?? "Workflow host rejected the Pi branch report");
+    }
+    for (const entry of entries) {
+      const message = messageById(view, entry.workflowMessageId);
+      if (message !== undefined) {
+        message.status = "sent";
+        message.piSessionEntryId = entry.piSessionEntryId;
+      }
+      this.queued.delete(entry.workflowMessageId);
+    }
+    this.lastBranchEpoch = view.coordinatorEpoch;
+  }
+
+  private hasUnconfirmedBranchEntry(
+    ctx: Pick<ExtensionContext, "sessionManager">,
+    view: WorkflowSessionView,
+  ): boolean {
+    const branch = branchWorkflowEntries(ctx.sessionManager.getBranch());
+    return view.workflowMessages.some(
+      (message) => message.status !== "sent" && branch.has(message.workflowMessageId),
+    );
+  }
+}
+
+export function branchWorkflowEntries(entries: readonly unknown[]): Map<string, string> {
+  const found = new Map<string, string>();
+  for (const value of entries) {
+    if (!isRecord(value) || typeof value.id !== "string") continue;
+    if (value.type !== "custom_message" && value.role !== "custom") continue;
+    if (!isRecord(value.details)) continue;
+    const workflowMessageId = value.details[WORKFLOW_MESSAGE_ID_FIELD];
+    if (typeof workflowMessageId === "string") found.set(workflowMessageId, value.id);
+  }
+  return found;
+}
+
+export function responseEntryId(entries: readonly unknown[]): string | null {
+  for (const value of [...entries].reverse()) {
+    if (!isRecord(value) || typeof value.id !== "string") continue;
+    if (value.type === "message" && isRecord(value.message) && value.message.role === "assistant") {
+      return value.id;
+    }
+    if (value.role === "assistant") return value.id;
+  }
+  return null;
+}
+
+function messageById(
+  view: WorkflowSessionView,
+  workflowMessageId: string,
+): WorkflowMessage | undefined {
+  return view.workflowMessages.find((message) => message.workflowMessageId === workflowMessageId);
+}
+
+function messageStartsTurn(message: WorkflowMessage): boolean {
+  return message.kind === "step" || message.kind === "terminal" || message.kind === "followUp";
+}
+
+async function reportTurn(client: WorkflowClient, report: WorkflowTurnReport): Promise<void> {
+  const response = await client.request({
+    operation: "workflowTurn.report",
+    runId: report.runId,
+    payload: report as unknown as JsonValue,
+  });
+  if (response.outcome !== "accepted" && response.outcome !== "adopted") {
+    throw new Error(response.error ?? "Workflow host rejected the model-turn report");
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}