@bastani/atomic 0.8.13-0 → 0.8.14-0

package/dist/builtin/workflows/src/shared/stage-ui-broker.ts

@@ -0,0 +1,193 @@
+import { randomUUID } from "node:crypto";
+import type { Component, Focusable, TUI } from "@earendil-works/pi-tui";
+import type { Store } from "./store.js";
+import { store as defaultStore } from "./store.js";
+import type { PiCustomOverlayFactory, PiCustomOverlayOptions, PiKeybindings, PiTheme } from "../extension/wiring.js";
+
+export interface StageCustomUiRequest<T = unknown> {
+  readonly id: string;
+  readonly runId: string;
+  readonly stageId: string;
+  readonly factory: PiCustomOverlayFactory<T>;
+  readonly options?: PiCustomOverlayOptions;
+  readonly createdAt: number;
+  resolve(value: T): void;
+  reject(reason: unknown): void;
+}
+
+export interface StageCustomUiHost {
+  showCustomUi(request: StageCustomUiRequest): void;
+  hideCustomUi?(request: StageCustomUiRequest, reason: unknown): void;
+}
+
+function key(runId: string, stageId: string): string {
+  return `${runId}\0${stageId}`;
+}
+
+function nextRequestId(): string {
+  return `stage-ui-${randomUUID()}`;
+}
+
+export class StageUiBroker {
+  private readonly store: Store;
+  private readonly pending = new Map<string, StageCustomUiRequest>();
+  private readonly hosts = new Map<string, StageCustomUiHost>();
+
+  constructor(store: Store = defaultStore) {
+    this.store = store;
+  }
+
+  private hideHost(host: StageCustomUiHost | undefined, request: StageCustomUiRequest, reason: unknown): void {
+    try {
+      host?.hideCustomUi?.(request, reason);
+    } catch {
+      // Host teardown is best-effort; request settlement must still continue.
+    }
+  }
+
+  private showHostOrReject(host: StageCustomUiHost, request: StageCustomUiRequest): void {
+    try {
+      host.showCustomUi(request);
+    } catch (error) {
+      this.reject(request, error);
+    }
+  }
+
+  registerHost(runId: string, stageId: string, host: StageCustomUiHost): () => void {
+    const hostKey = key(runId, stageId);
+    const previousHost = this.hosts.get(hostKey);
+    const request = this.pending.get(hostKey);
+    if (previousHost && previousHost !== host && request) {
+      this.hideHost(
+        previousHost,
+        request,
+        new Error(`pi-workflows: stage ${stageId} custom UI host replaced`),
+      );
+    }
+    this.hosts.set(hostKey, host);
+    const activeRequest = this.pending.get(hostKey);
+    if (activeRequest) this.showHostOrReject(host, activeRequest);
+    return () => {
+      if (this.hosts.get(hostKey) !== host) return;
+      this.hosts.delete(hostKey);
+      const pendingRequest = this.pending.get(hostKey);
+      if (pendingRequest) {
+        this.reject(
+          pendingRequest,
+          new Error(`pi-workflows: stage ${stageId} custom UI host unregistered`),
+        );
+      }
+    };
+  }
+
+  requestCustomUi<T>(
+    runId: string,
+    stageId: string,
+    factory: PiCustomOverlayFactory<T>,
+    options?: PiCustomOverlayOptions,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    if (signal?.aborted) {
+      return Promise.reject(signal.reason ?? new Error("pi-workflows: stage UI request aborted"));
+    }
+    const hostKey = key(runId, stageId);
+    const existing = this.pending.get(hostKey);
+    if (existing) {
+      return Promise.reject(new Error(`pi-workflows: stage ${stageId} already has a pending custom UI request`));
+    }
+
+    let request!: StageCustomUiRequest<T>;
+    const promise = new Promise<T>((resolve, reject) => {
+      request = {
+        id: nextRequestId(),
+        runId,
+        stageId,
+        factory,
+        ...(options !== undefined ? { options } : {}),
+        createdAt: Date.now(),
+        resolve,
+        reject,
+      };
+    });
+
+    const onAbort = (): void => {
+      this.reject(request, signal?.reason ?? new Error("pi-workflows: stage UI request aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    this.pending.set(hostKey, request);
+    this.store.recordStageAwaitingInput(runId, stageId, true, request.createdAt);
+    const host = this.hosts.get(hostKey);
+    if (host) this.showHostOrReject(host, request);
+    // Re-check after listener registration and host display; AbortSignal does
+    // not replay an already-fired abort event for listeners added later.
+    if (signal?.aborted) onAbort();
+
+    return promise.finally(() => {
+      signal?.removeEventListener("abort", onAbort);
+    });
+  }
+
+  resolve<T>(request: StageCustomUiRequest<T>, value: T): void {
+    const hostKey = key(request.runId, request.stageId);
+    if (this.pending.get(hostKey)?.id !== request.id) return;
+    this.pending.delete(hostKey);
+    this.store.recordStageAwaitingInput(request.runId, request.stageId, false);
+    this.hideHost(this.hosts.get(hostKey), request, undefined);
+    request.resolve(value);
+  }
+
+  reject(request: StageCustomUiRequest, reason: unknown): void {
+    const hostKey = key(request.runId, request.stageId);
+    if (this.pending.get(hostKey)?.id !== request.id) return;
+    this.pending.delete(hostKey);
+    this.store.recordStageAwaitingInput(request.runId, request.stageId, false);
+    this.hideHost(this.hosts.get(hostKey), request, reason);
+    request.reject(reason);
+  }
+}
+
+export interface MountedStageCustomUi {
+  readonly request: StageCustomUiRequest;
+  readonly component: Component & { dispose?(): void };
+}
+
+export async function mountStageCustomUi(
+  request: StageCustomUiRequest,
+  tui: TUI,
+  theme: PiTheme,
+  keybindings: PiKeybindings,
+  broker: StageUiBroker,
+  onDone?: () => void,
+): Promise<MountedStageCustomUi> {
+  const rawComponent = await request.factory(
+    tui as unknown as Parameters<StageCustomUiRequest["factory"]>[0],
+    theme,
+    keybindings,
+    (result: unknown) => {
+      broker.resolve(request, result);
+      onDone?.();
+    },
+  );
+  const component: Component & { dispose?(): void } & Partial<Focusable> = {
+    render: (width) => rawComponent.render(width),
+    ...(rawComponent.handleInput !== undefined
+      ? { handleInput: (data: string) => rawComponent.handleInput?.(data) }
+      : {}),
+    invalidate: () => rawComponent.invalidate?.(),
+    ...(rawComponent.dispose !== undefined ? { dispose: () => rawComponent.dispose?.() } : {}),
+  };
+  if ("focused" in rawComponent) {
+    Object.defineProperty(component, "focused", {
+      get: () => (rawComponent as Component & Partial<Focusable>).focused,
+      set: (value: boolean) => {
+        (rawComponent as Component & Partial<Focusable>).focused = value;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+  return { request, component };
+}
+
+export const stageUiBroker = new StageUiBroker();

package/dist/builtin/workflows/src/shared/store-types.ts

@@ -11,7 +11,10 @@ export type StageStatus =
   | "paused"
   | "blocked"
   | "completed"
-  | "failed";
+  | "failed"
+  | "skipped";
+
+export type WorkflowFailureKind = "auth" | "rate_limit" | "provider" | "cancelled" | "unknown";
 
 /**
  * Human-in-the-loop prompt kind. Mirrors the four `WorkflowUIContext` methods.
@@ -66,9 +69,21 @@ export interface StageSnapshot {
   durationMs?: number;
   result?: string;
   error?: string;
+  /** Structured workflow failure category for failed stages. */
+  failureKind?: WorkflowFailureKind;
+  /** Original unsanitized error text when different from `error`. */
+  failureMessage?: string;
+  /** Reason for stages skipped by fail-fast/cascade handling. */
+  skippedReason?: string;
+  /** Source stage id when this stage was replayed during failed-run continuation. */
+  replayedFromStageId?: string;
+  /** True when provider work was skipped by continuation replay. */
+  replayed?: boolean;
   readonly toolEvents: ToolEvent[];
   /** True while an in-stage ask_user_question tool is waiting on the user. */
   awaitingInputSince?: number;
+  /** Pending human-in-the-loop prompt owned by this workflow stage/node. */
+  pendingPrompt?: PendingPrompt;
   blockedByStageId?: string;
   notices?: StageNotice[];
   /**
@@ -125,6 +140,16 @@ export interface RunSnapshot {
   resumedAt?: number;
   result?: Record<string, unknown>;
   error?: string;
+  /** Structured workflow failure category for failed runs. */
+  failureKind?: WorkflowFailureKind;
+  /** Original unsanitized error text when different from `error`. */
+  failureMessage?: string;
+  failedStageId?: string;
+  resumable?: boolean;
+  /** Source failed run when this run is a continuation. */
+  resumedFromRunId?: string;
+  /** Source stage id where continuation resumes real execution. */
+  resumeFromStageId?: string;
   /**
    * Pending human-in-the-loop prompt. Set when a background workflow calls
    * `ctx.ui.input/confirm/select/editor`; cleared when the user responds via

package/dist/builtin/workflows/src/shared/store.ts

@@ -11,6 +11,8 @@ import type {
   StoreSnapshot,
   ToolEvent,
   RunStatus,
+  StageStatus,
+  WorkflowFailureKind,
   WorkflowNotice,
 } from "./store-types.js";
 import { accumulatePausedDurationMs, elapsedRunMs } from "./timing.js";
@@ -18,6 +20,29 @@ import { accumulatePausedDurationMs, elapsedRunMs } from "./timing.js";
 /** Statuses that represent a terminal run state — cannot be overwritten. */
 const TERMINAL_STATUSES: ReadonlySet<RunStatus> = new Set(["completed", "failed", "killed"]);
 
+function isTerminalStageStatus(status: StageStatus): boolean {
+  return status === "completed" || status === "failed" || status === "skipped";
+}
+
+function cannotAwaitInput(status: StageStatus): boolean {
+  return isTerminalStageStatus(status) || status === "paused" || status === "blocked";
+}
+
+function cannotBlock(status: StageStatus): boolean {
+  return isTerminalStageStatus(status) || status === "paused";
+}
+
+function cannotPause(status: StageStatus): boolean {
+  return isTerminalStageStatus(status) || status === "paused" || status === "blocked";
+}
+
+export interface RunEndMetadata {
+  readonly failureKind?: WorkflowFailureKind;
+  readonly failureMessage?: string;
+  readonly failedStageId?: string;
+  readonly resumable?: boolean;
+}
+
 export interface Store {
   runs(): readonly RunSnapshot[];
   notices(): readonly WorkflowNotice[];
@@ -39,6 +64,7 @@ export interface Store {
     status: RunStatus,
     result?: Record<string, unknown>,
     error?: string,
+    metadata?: RunEndMetadata,
   ): boolean;
   /**
    * Remove a run from live workflow history/status. Any pending HIL prompt
@@ -84,6 +110,17 @@ export interface Store {
    * overlay-driven response. Foreground runs never call this.
    */
   awaitPendingPrompt(runId: string, promptId: string): Promise<unknown>;
+  /** Record a pending HIL prompt for a specific workflow stage/node. */
+  recordStagePendingPrompt(runId: string, stageId: string, prompt: PendingPrompt): boolean;
+  /** Resolve a pending HIL prompt on a specific workflow stage/node. */
+  resolveStagePendingPrompt(
+    runId: string,
+    stageId: string,
+    promptId: string,
+    response: unknown,
+  ): boolean;
+  /** Wait for a stage/node-scoped HIL prompt to resolve. */
+  awaitStagePendingPrompt(runId: string, stageId: string, promptId: string): Promise<unknown>;
   /**
    * Record Pi/pi SDK session metadata for a stage after lazy
    * attach. The serializable snapshot tracks this so post-mortem reopen
@@ -186,6 +223,26 @@ export function createStore(): Store {
     return run.stages.find((s) => s.id === stageId);
   }
 
+  function rejectPrompt(promptId: string, reason: string): void {
+    const entry = _resolvers.get(promptId);
+    if (!entry) return;
+    _resolvers.delete(promptId);
+    entry.reject(new Error(reason));
+  }
+
+  function rejectStagePrompt(stage: StageSnapshot, reason: string): void {
+    const prompt = stage.pendingPrompt;
+    if (!prompt) return;
+    stage.pendingPrompt = undefined;
+    rejectPrompt(prompt.id, reason);
+  }
+
+  function rejectAllStagePrompts(run: RunSnapshot, reason: string): void {
+    for (const stage of run.stages) {
+      rejectStagePrompt(stage, reason);
+    }
+  }
+
   return {
     runs(): readonly RunSnapshot[] {
       return _runs;
@@ -274,7 +331,13 @@ export function createStore(): Store {
       existing.durationMs = stage.durationMs;
       existing.result = stage.result;
       existing.error = stage.error;
+      existing.failureKind = stage.failureKind;
+      existing.failureMessage = stage.failureMessage;
+      existing.skippedReason = stage.skippedReason;
+      existing.replayedFromStageId = stage.replayedFromStageId;
+      existing.replayed = stage.replayed;
       delete existing.awaitingInputSince;
+      rejectStagePrompt(existing, `pi-workflows: stage ${stage.id} ended before prompt resolved`);
       _version++;
       notify();
     },
@@ -284,6 +347,7 @@ export function createStore(): Store {
       status: RunStatus,
       result?: Record<string, unknown>,
       error?: string,
+      metadata?: RunEndMetadata,
     ): boolean {
       const run = findRun(runId);
       if (!run) return false;
@@ -306,20 +370,21 @@ export function createStore(): Store {
       if ((status === "failed" || status === "killed") && error !== undefined) {
         run.error = error;
       }
+      if (metadata !== undefined) {
+        if (metadata.failureKind !== undefined) run.failureKind = metadata.failureKind;
+        if (metadata.failureMessage !== undefined) run.failureMessage = metadata.failureMessage;
+        if (metadata.failedStageId !== undefined) run.failedStageId = metadata.failedStageId;
+        if (metadata.resumable !== undefined) run.resumable = metadata.resumable;
+      }
       // Abandon any waiting HIL prompt — workflow body never resumed past
       // it, but the awaiter promise must reject so the executor's catch
       // can finalise the run state cleanly.
       const pending = run.pendingPrompt;
       if (pending) {
         run.pendingPrompt = undefined;
-        const entry = _resolvers.get(pending.id);
-        if (entry) {
-          _resolvers.delete(pending.id);
-          entry.reject(
-            new Error(`pi-workflows: run ${runId} ended before prompt resolved`),
-          );
-        }
+        rejectPrompt(pending.id, `pi-workflows: run ${runId} ended before prompt resolved`);
       }
+      rejectAllStagePrompts(run, `pi-workflows: run ${runId} ended before prompt resolved`);
       _version++;
       notify();
       return true;
@@ -331,14 +396,9 @@ export function createStore(): Store {
       const run = _runs[index]!;
       const pending = run.pendingPrompt;
       if (pending) {
-        const entry = _resolvers.get(pending.id);
-        if (entry) {
-          _resolvers.delete(pending.id);
-          entry.reject(
-            new Error(`pi-workflows: run ${runId} was removed before prompt resolved`),
-          );
-        }
+        rejectPrompt(pending.id, `pi-workflows: run ${runId} was removed before prompt resolved`);
       }
+      rejectAllStagePrompts(run, `pi-workflows: run ${runId} was removed before prompt resolved`);
       _runs.splice(index, 1);
       for (let i = _notices.length - 1; i >= 0; i--) {
         if (_notices[i]?.runId === runId) _notices.splice(i, 1);
@@ -416,6 +476,74 @@ export function createStore(): Store {
       });
     },
 
+    recordStagePendingPrompt(runId: string, stageId: string, prompt: PendingPrompt): boolean {
+      const run = findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      const stage = findStage(run, stageId);
+      if (!stage) return false;
+      if (isTerminalStageStatus(stage.status)) return false;
+      if (stage.pendingPrompt !== undefined) return false;
+      stage.pendingPrompt = { ...prompt };
+      stage.status = "awaiting_input";
+      stage.awaitingInputSince = prompt.createdAt;
+      _version++;
+      notify();
+      return true;
+    },
+
+    resolveStagePendingPrompt(
+      runId: string,
+      stageId: string,
+      promptId: string,
+      response: unknown,
+    ): boolean {
+      const run = findRun(runId);
+      if (!run) return false;
+      const stage = findStage(run, stageId);
+      if (!stage) return false;
+      const pending = stage.pendingPrompt;
+      if (!pending || pending.id !== promptId) return false;
+      stage.pendingPrompt = undefined;
+      if (stage.status === "awaiting_input") {
+        stage.status = "running";
+        delete stage.awaitingInputSince;
+      }
+      _version++;
+      notify();
+      const entry = _resolvers.get(promptId);
+      if (entry) {
+        _resolvers.delete(promptId);
+        entry.resolve(response);
+      }
+      return true;
+    },
+
+    awaitStagePendingPrompt(runId: string, stageId: string, promptId: string): Promise<unknown> {
+      return new Promise<unknown>((resolve, reject) => {
+        const run = findRun(runId);
+        if (!run) {
+          reject(new Error(`pi-workflows: run "${runId}" not found`));
+          return;
+        }
+        const stage = findStage(run, stageId);
+        if (!stage) {
+          reject(new Error(`pi-workflows: stage "${stageId}" not found on run "${runId}"`));
+          return;
+        }
+        const pending = stage.pendingPrompt;
+        if (!pending || pending.id !== promptId) {
+          reject(
+            new Error(
+              `pi-workflows: pending prompt "${promptId}" not registered on stage "${stageId}" in run "${runId}"`,
+            ),
+          );
+          return;
+        }
+        _resolvers.set(promptId, { promptId, resolve, reject });
+      });
+    },
+
     recordStageSession(
       runId: string,
       stageId: string,
@@ -480,7 +608,7 @@ export function createStore(): Store {
       if (TERMINAL_STATUSES.has(run.status)) return false;
       const stage = findStage(run, stageId);
       if (!stage) return false;
-      if (stage.status === "completed" || stage.status === "failed" || stage.status === "paused" || stage.status === "blocked") return false;
+      if (cannotAwaitInput(stage.status)) return false;
 
       if (awaiting) {
         if (stage.status === "awaiting_input") return false;
@@ -502,7 +630,7 @@ export function createStore(): Store {
       if (TERMINAL_STATUSES.has(run.status)) return false;
       const stage = findStage(run, stageId);
       if (!stage) return false;
-      if (stage.status === "completed" || stage.status === "failed" || stage.status === "paused") return false;
+      if (cannotBlock(stage.status)) return false;
       if (stage.status === "blocked") {
         if (stage.blockedByStageId === blockedBy) return false;
         stage.blockedByStageId = blockedBy;
@@ -547,7 +675,7 @@ export function createStore(): Store {
       if (TERMINAL_STATUSES.has(run.status)) return false;
       const stage = findStage(run, stageId);
       if (!stage) return false;
-      if (stage.status === "paused" || stage.status === "blocked" || stage.status === "completed" || stage.status === "failed") return false;
+      if (cannotPause(stage.status)) return false;
       stage.status = "paused";
       stage.pausedAt = pausedAt ?? Date.now();
       stage.resumedAt = undefined;

package/dist/builtin/workflows/src/shared/timing.ts

@@ -1,5 +1,6 @@
 interface StageTimerSnapshot {
   readonly startedAt?: number;
+  readonly endedAt?: number;
   readonly durationMs?: number;
   readonly pausedDurationMs?: number;
   readonly pausedAt?: number;
@@ -7,6 +8,7 @@ interface StageTimerSnapshot {
 
 interface RunTimerSnapshot {
   readonly startedAt: number;
+  readonly endedAt?: number;
   readonly durationMs?: number;
   readonly pausedDurationMs?: number;
   readonly pausedAt?: number;
@@ -39,10 +41,12 @@ export function accumulatePausedDurationMs(
 export function elapsedStageMs(stage: StageTimerSnapshot, now = Date.now()): number | undefined {
   if (stage.durationMs !== undefined) return nonNegative(stage.durationMs);
   if (stage.startedAt === undefined) return undefined;
-  return elapsedFromStart(stage.startedAt, now, stage.pausedDurationMs, stage.pausedAt);
+  const effectiveNow = stage.endedAt ?? now;
+  return elapsedFromStart(stage.startedAt, effectiveNow, stage.pausedDurationMs, stage.pausedAt);
 }
 
 export function elapsedRunMs(run: RunTimerSnapshot, now = Date.now()): number {
   if (run.durationMs !== undefined) return nonNegative(run.durationMs);
-  return elapsedFromStart(run.startedAt, now, run.pausedDurationMs, run.pausedAt);
+  const effectiveNow = run.endedAt ?? now;
+  return elapsedFromStart(run.startedAt, effectiveNow, run.pausedDurationMs, run.pausedAt);
 }