@bastani/atomic 0.8.21 → 0.8.22-0

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

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { Component, Focusable, TUI } from "@earendil-works/pi-tui";
-import type { Store } from "./store.js";
+import type { StagePromptAnswerSource, Store } from "./store.js";
 import { store as defaultStore } from "./store.js";
 import type { StageInputRequest } from "./store-types.js";
 import type { StageInputAnswer, StagePromptAdapter } from "./stage-prompt.js";
@@ -22,6 +22,22 @@ export interface StageCustomUiHost {
   hideCustomUi?(request: StageCustomUiRequest, reason: unknown): void;
 }
 
+export interface StagePromptResolvedEvent {
+  readonly runId: string;
+  readonly stageId: string;
+  readonly prompt: StageInputRequest;
+  readonly answer: unknown;
+  readonly answeredAt: number;
+  readonly answerSource?: StagePromptAnswerSource;
+}
+
+export interface AnswerStagePromptOptions {
+  /** Identifies who answered the prompt so notification code can avoid echoing workflow-tool answers. */
+  readonly answerSource?: StagePromptAnswerSource;
+}
+
+export type StagePromptResolvedListener = (event: StagePromptResolvedEvent) => void;
+
 function key(runId: string, stageId: string): string {
   return `${runId}\0${stageId}`;
 }
@@ -39,6 +55,8 @@ export class StageUiBroker {
   // custom-UI prompt can be answered programmatically (e.g. via `workflow
   // send`) without a TUI host rendering the interactive component.
   private readonly adapters = new Map<string, StagePromptAdapter>();
+  private readonly resolvedPromptIds = new Map<string, string>();
+  private readonly resolvedListeners = new Set<StagePromptResolvedListener>();
 
   constructor(store: Store = defaultStore) {
     this.store = store;
@@ -52,7 +70,13 @@ export class StageUiBroker {
    * after the matching `requestCustomUi`; the (runId, stageId) key joins them.
    */
   provideStagePrompt(runId: string, stageId: string, adapter: StagePromptAdapter): void {
-    this.adapters.set(key(runId, stageId), adapter);
+    const hostKey = key(runId, stageId);
+    this.adapters.set(hostKey, adapter);
+    // A newly provided adapter represents a fresh prompt instance, even when
+    // the caller reuses the same prompt id (readiness gates historically did).
+    // Clear the resolved marker unconditionally so a raced answer for this new
+    // request cannot be mistaken for a duplicate answer to the prior instance.
+    this.resolvedPromptIds.delete(hostKey);
     this.store.recordStageInputRequest(runId, stageId, adapter.prompt);
   }
 
@@ -63,6 +87,23 @@ export class StageUiBroker {
     }
   }
 
+  /**
+   * Settle and hide any brokered prompt that belongs to a stage whose workflow
+   * lifecycle has ended. Detaching a host intentionally does not cancel human
+   * input, but terminal stage/run cleanup must not leave stale HIL UI mounted.
+   */
+  cancelStagePrompt(runId: string, stageId: string, reason: unknown): void {
+    const hostKey = key(runId, stageId);
+    const request = this.pending.get(hostKey);
+    if (request) {
+      this.reject(request, reason);
+      return;
+    }
+    if (this.adapters.delete(hostKey)) {
+      this.store.clearStageInputRequest(runId, stageId);
+    }
+  }
+
   /**
    * Return the structured descriptor for a stage's brokered prompt when BOTH a
    * headless-answer adapter and a live pending request exist for it — i.e. when
@@ -80,15 +121,41 @@ export class StageUiBroker {
    * `ctx.ui.custom` promise with the adapter-built result. Returns `false` when
    * there is no adapter+request pair for the stage.
    */
-  answerStagePrompt(runId: string, stageId: string, answer: StageInputAnswer): boolean {
+  answerStagePrompt(
+    runId: string,
+    stageId: string,
+    answer: StageInputAnswer,
+    options: AnswerStagePromptOptions = {},
+  ): boolean {
     const hostKey = key(runId, stageId);
     const adapter = this.adapters.get(hostKey);
     const request = this.pending.get(hostKey);
     if (!adapter || !request) return false;
-    this.resolve(request, adapter.buildResult(answer));
+    this.resolve(request, adapter.buildResult(answer), options);
     return true;
   }
 
+  wasStagePromptResolved(runId: string, stageId: string, promptId: string): boolean {
+    return this.resolvedPromptIds.get(key(runId, stageId)) === promptId;
+  }
+
+  onStagePromptResolved(listener: StagePromptResolvedListener): () => void {
+    this.resolvedListeners.add(listener);
+    return () => {
+      this.resolvedListeners.delete(listener);
+    };
+  }
+
+  private notifyStagePromptAnswered(event: StagePromptResolvedEvent): void {
+    for (const listener of this.resolvedListeners) {
+      try {
+        listener(event);
+      } catch {
+        // Listener failures must not prevent the prompt from resolving.
+      }
+    }
+  }
+
   private hideHost(host: StageCustomUiHost | undefined, request: StageCustomUiRequest, reason: unknown): void {
     try {
       host?.hideCustomUi?.(request, reason);
@@ -113,7 +180,7 @@ export class StageUiBroker {
       this.hideHost(
         previousHost,
         request,
-        new Error(`pi-workflows: stage ${stageId} custom UI host replaced`),
+        new Error(`atomic-workflows: stage ${stageId} custom UI host replaced`),
       );
     }
     this.hosts.set(hostKey, host);
@@ -139,12 +206,12 @@ export class StageUiBroker {
     signal?: AbortSignal,
   ): Promise<T> {
     if (signal?.aborted) {
-      return Promise.reject(signal.reason ?? new Error("pi-workflows: stage UI request aborted"));
+      return Promise.reject(signal.reason ?? new Error("atomic-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`));
+      return Promise.reject(new Error(`atomic-workflows: stage ${stageId} already has a pending custom UI request`));
     }
 
     let request!: StageCustomUiRequest<T>;
@@ -162,7 +229,7 @@ export class StageUiBroker {
     });
 
     const onAbort = (): void => {
-      this.reject(request, signal?.reason ?? new Error("pi-workflows: stage UI request aborted"));
+      this.reject(request, signal?.reason ?? new Error("atomic-workflows: stage UI request aborted"));
     };
     signal?.addEventListener("abort", onAbort, { once: true });
 
@@ -179,14 +246,26 @@ export class StageUiBroker {
     });
   }
 
-  resolve<T>(request: StageCustomUiRequest<T>, value: T): void {
+  resolve<T>(request: StageCustomUiRequest<T>, value: T, options: AnswerStagePromptOptions = {}): void {
     const hostKey = key(request.runId, request.stageId);
     if (this.pending.get(hostKey)?.id !== request.id) return;
+    const prompt = this.adapters.get(hostKey)?.prompt;
     this.pending.delete(hostKey);
     this.adapters.delete(hostKey);
+    if (prompt !== undefined) this.resolvedPromptIds.set(hostKey, prompt.id);
     this.store.clearStageInputRequest(request.runId, request.stageId);
     this.store.recordStageAwaitingInput(request.runId, request.stageId, false);
     this.hideHost(this.hosts.get(hostKey), request, undefined);
+    if (prompt !== undefined) {
+      this.notifyStagePromptAnswered({
+        runId: request.runId,
+        stageId: request.stageId,
+        prompt,
+        answer: value,
+        answeredAt: Date.now(),
+        ...(options.answerSource !== undefined ? { answerSource: options.answerSource } : {}),
+      });
+    }
     request.resolve(value);
   }
 
@@ -195,6 +274,7 @@ export class StageUiBroker {
     if (this.pending.get(hostKey)?.id !== request.id) return;
     this.pending.delete(hostKey);
     this.adapters.delete(hostKey);
+    this.resolvedPromptIds.delete(hostKey);
     this.store.clearStageInputRequest(request.runId, request.stageId);
     this.store.recordStageAwaitingInput(request.runId, request.stageId, false);
     this.hideHost(this.hosts.get(hostKey), request, reason);
@@ -214,12 +294,14 @@ export async function mountStageCustomUi(
   keybindings: PiKeybindings,
   broker: StageUiBroker,
   onDone?: () => void,
+  canResolve?: () => boolean,
 ): Promise<MountedStageCustomUi> {
   const rawComponent = await request.factory(
     tui as unknown as Parameters<StageCustomUiRequest["factory"]>[0],
     theme,
     keybindings,
     (result: unknown) => {
+      if (canResolve?.() === false) return;
       broker.resolve(request, result);
       onDone?.();
     },

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

@@ -3,6 +3,8 @@
  * cross-ref: spec §5.5
  */
 
+import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+
 export type RunStatus = "pending" | "running" | "paused" | "completed" | "failed" | "killed";
 export type StageStatus =
   | "pending"
@@ -94,6 +96,20 @@ export interface StageNotice {
   readonly meta?: string;
 }
 
+export interface WorkflowChildRunRef {
+  readonly alias: string;
+  readonly workflow: string;
+  readonly runId: string;
+}
+
+export interface WorkflowChildReplaySnapshot {
+  readonly alias: string;
+  readonly workflow: string;
+  readonly runId: string;
+  readonly status: "completed";
+  readonly outputs: WorkflowOutputValues;
+}
+
 export interface StageSnapshot {
   readonly id: string;
   readonly name: string;
@@ -125,6 +141,10 @@ export interface StageSnapshot {
   replayedFromStageId?: string;
   /** True when provider work was skipped by continuation replay. */
   replayed?: boolean;
+  /** Live child workflow run metadata used to expand nested workflow graphs while the child is running. */
+  workflowChildRun?: WorkflowChildRunRef;
+  /** Snapshot-safe child workflow result metadata for continuation replay of import boundaries. */
+  workflowChild?: WorkflowChildReplaySnapshot;
   readonly toolEvents: ToolEvent[];
   /** True while an in-stage ask_user_question tool is waiting on the user. */
   awaitingInputSince?: number;
@@ -155,8 +175,10 @@ export interface StageSnapshot {
    */
   sessionId?: string;
   sessionFile?: string;
-  /** Effective model selected for this stage after fallback resolution. */
+  /** Effective model id selected for this stage after fallback resolution. */
   model?: string;
+  /** True when Codex fast mode applied to this workflow stage. */
+  fastMode?: boolean;
   /** Ordered model ids attempted by fallback orchestration. */
   attemptedModels?: readonly string[];
   /** Per-model fallback attempt outcomes. */
@@ -180,7 +202,7 @@ export interface StageSnapshot {
 export interface RunSnapshot {
   readonly id: string;
   readonly name: string;
-  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly inputs: Readonly<WorkflowInputValues>;
   status: RunStatus;
   readonly stages: StageSnapshot[];
   startedAt: number;
@@ -192,7 +214,7 @@ export interface RunSnapshot {
   pausedAt?: number;
   /** Timestamp recorded on the most recent resume from a paused state. */
   resumedAt?: number;
-  result?: Record<string, unknown>;
+  result?: WorkflowOutputValues;
   error?: string;
   /** Structured workflow failure category for failed runs. */
   failureKind?: WorkflowFailureKind;
@@ -200,6 +222,12 @@ export interface RunSnapshot {
   failureMessage?: string;
   failedStageId?: string;
   resumable?: boolean;
+  /** Parent workflow run when this snapshot is an internal child workflow run. Hidden from top-level status lists. */
+  parentRunId?: string;
+  /** Parent workflow boundary stage that launched this internal child workflow run. */
+  parentStageId?: string;
+  /** Top-level workflow run that owns this nested run tree. */
+  rootRunId?: string;
   /** Source failed run when this run is a continuation. */
   resumedFromRunId?: string;
   /** Source stage id where continuation resumes real execution. */

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

@@ -3,6 +3,7 @@
  * cross-ref: spec §5.5
  */
 
+import type { WorkflowOutputValues } from "./types.js";
 import type {
   PendingPrompt,
   PromptKind,
@@ -16,8 +17,10 @@ import type {
   StageStatus,
   WorkflowFailureKind,
   WorkflowNotice,
+  WorkflowChildRunRef,
 } from "./store-types.js";
 import { accumulatePausedDurationMs, elapsedRunMs } from "./timing.js";
+import { isTopLevelWorkflowRun } from "./run-visibility.js";
 
 /** Statuses that represent a terminal run state — cannot be overwritten. */
 const TERMINAL_STATUSES: ReadonlySet<RunStatus> = new Set(["completed", "failed", "killed"]);
@@ -45,6 +48,8 @@ export interface RunEndMetadata {
   readonly resumable?: boolean;
 }
 
+export type StagePromptAnswerSource = "workflow_ui" | "workflow_tool";
+
 export interface PromptAnswerRecord {
   readonly runId: string;
   readonly stageId: string;
@@ -52,6 +57,7 @@ export interface PromptAnswerRecord {
   readonly kind: PromptKind;
   readonly value: unknown;
   readonly answeredAt: number;
+  readonly answerSource?: StagePromptAnswerSource;
 }
 
 export interface ResolveStagePendingPromptOptions {
@@ -60,6 +66,8 @@ export interface ResolveStagePendingPromptOptions {
    * continuation replay. Abort/default resolutions should set this to false.
    */
   readonly recordAnswer?: boolean;
+  /** Identifies who answered the prompt so notification code can avoid echoing workflow-tool answers. */
+  readonly answerSource?: StagePromptAnswerSource;
 }
 
 export interface Store {
@@ -68,6 +76,8 @@ export interface Store {
   activeRunId(): string | null;
   recordRunStart(run: RunSnapshot): void;
   recordStageStart(runId: string, stage: StageSnapshot): void;
+  /** Link a workflow boundary stage to its live child run before that child completes. */
+  recordStageWorkflowChildRun(runId: string, stageId: string, ref: WorkflowChildRunRef): boolean;
   recordToolStart(runId: string, stageId: string, evt: ToolEvent): void;
   recordToolEnd(runId: string, stageId: string, evt: ToolEvent): void;
   recordStageEnd(runId: string, stage: StageSnapshot): void;
@@ -81,7 +91,7 @@ export interface Store {
   recordRunEnd(
     runId: string,
     status: RunStatus,
-    result?: Record<string, unknown>,
+    result?: WorkflowOutputValues,
     error?: string,
     metadata?: RunEndMetadata,
   ): boolean;
@@ -298,7 +308,19 @@ export function createStore(): Store {
     },
 
     activeRunId(): string | null {
-      // Most recently started run that hasn't ended
+      // Most recently started top-level run that hasn't ended. Nested
+      // workflow runs stay in the store for live control/expanded graph
+      // rendering, but should not steal the active top-level workflow slot.
+      for (let i = _runs.length - 1; i >= 0; i--) {
+        const run = _runs[i];
+        if (run && isTopLevelWorkflowRun(run) && run.endedAt === undefined) {
+          return run.id;
+        }
+      }
+      // Fallback for the degraded "orphaned-nested-only" state: a child run is in
+      // flight but no top-level run is. This normally cannot happen (a parent
+      // stays in flight while awaiting `ctx.workflow(...)`), so callers that rely
+      // on a top-level id should treat a returned nested id as best-effort.
       for (let i = _runs.length - 1; i >= 0; i--) {
         const run = _runs[i];
         if (run && run.endedAt === undefined) {
@@ -325,6 +347,24 @@ export function createStore(): Store {
       notify();
     },
 
+    recordStageWorkflowChildRun(runId: string, stageId: string, ref: WorkflowChildRunRef): boolean {
+      const run = findRun(runId);
+      if (!run) return false;
+      const stage = findStage(run, stageId);
+      if (!stage) return false;
+      if (
+        stage.workflowChildRun?.runId === ref.runId &&
+        stage.workflowChildRun.alias === ref.alias &&
+        stage.workflowChildRun.workflow === ref.workflow
+      ) {
+        return false;
+      }
+      stage.workflowChildRun = { ...ref };
+      _version++;
+      notify();
+      return true;
+    },
+
     recordToolStart(runId: string, stageId: string, evt: ToolEvent): void {
       const run = findRun(runId);
       if (!run) return;
@@ -383,9 +423,11 @@ export function createStore(): Store {
       if (stage.promptAnswerState !== undefined) existing.promptAnswerState = stage.promptAnswerState;
       if (stage.replayedFromStageId !== undefined) existing.replayedFromStageId = stage.replayedFromStageId;
       if (stage.replayed !== undefined) existing.replayed = stage.replayed;
+      if (stage.workflowChildRun !== undefined) existing.workflowChildRun = { ...stage.workflowChildRun };
+      if (stage.workflowChild !== undefined) existing.workflowChild = structuredClone(stage.workflowChild);
       delete existing.awaitingInputSince;
       delete existing.inputRequest;
-      rejectStagePrompt(existing, `pi-workflows: stage ${stage.id} ended before prompt resolved`);
+      rejectStagePrompt(existing, `atomic-workflows: stage ${stage.id} ended before prompt resolved`);
       _version++;
       notify();
     },
@@ -393,7 +435,7 @@ export function createStore(): Store {
     recordRunEnd(
       runId: string,
       status: RunStatus,
-      result?: Record<string, unknown>,
+      result?: WorkflowOutputValues,
       error?: string,
       metadata?: RunEndMetadata,
     ): boolean {
@@ -430,9 +472,9 @@ export function createStore(): Store {
       const pending = run.pendingPrompt;
       if (pending) {
         run.pendingPrompt = undefined;
-        rejectPrompt(pending.id, `pi-workflows: run ${runId} ended before prompt resolved`);
+        rejectPrompt(pending.id, `atomic-workflows: run ${runId} ended before prompt resolved`);
       }
-      rejectAllStagePrompts(run, `pi-workflows: run ${runId} ended before prompt resolved`);
+      rejectAllStagePrompts(run, `atomic-workflows: run ${runId} ended before prompt resolved`);
       _version++;
       notify();
       return true;
@@ -444,9 +486,9 @@ export function createStore(): Store {
       const run = _runs[index]!;
       const pending = run.pendingPrompt;
       if (pending) {
-        rejectPrompt(pending.id, `pi-workflows: run ${runId} was removed before prompt resolved`);
+        rejectPrompt(pending.id, `atomic-workflows: run ${runId} was removed before prompt resolved`);
       }
-      rejectAllStagePrompts(run, `pi-workflows: run ${runId} was removed before prompt resolved`);
+      rejectAllStagePrompts(run, `atomic-workflows: run ${runId} was removed before prompt resolved`);
       for (const stage of run.stages) {
         _stagePromptAnswers.delete(stagePromptAnswerKey(runId, stage.id));
       }
@@ -511,14 +553,14 @@ export function createStore(): Store {
       return new Promise<unknown>((resolve, reject) => {
         const run = findRun(runId);
         if (!run) {
-          reject(new Error(`pi-workflows: run "${runId}" not found`));
+          reject(new Error(`atomic-workflows: run "${runId}" not found`));
           return;
         }
         const pending = run.pendingPrompt;
         if (!pending || pending.id !== promptId) {
           reject(
             new Error(
-              `pi-workflows: pending prompt "${promptId}" not registered on run "${runId}"`,
+              `atomic-workflows: pending prompt "${promptId}" not registered on run "${runId}"`,
             ),
           );
           return;
@@ -565,6 +607,7 @@ export function createStore(): Store {
           kind: pending.kind,
           value: response,
           answeredAt: Date.now(),
+          ...(options.answerSource !== undefined ? { answerSource: options.answerSource } : {}),
         });
         stage.promptAnswerState = "available";
       } else {
@@ -590,19 +633,19 @@ export function createStore(): Store {
       return new Promise<unknown>((resolve, reject) => {
         const run = findRun(runId);
         if (!run) {
-          reject(new Error(`pi-workflows: run "${runId}" not found`));
+          reject(new Error(`atomic-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}"`));
+          reject(new Error(`atomic-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}"`,
+              `atomic-workflows: pending prompt "${promptId}" not registered on stage "${stageId}" in run "${runId}"`,
             ),
           );
           return;
@@ -700,6 +743,7 @@ export function createStore(): Store {
         stage.status = "awaiting_input";
         stage.awaitingInputSince = ts ?? Date.now();
       } else {
+        if (stage.pendingPrompt !== undefined) return false;
         if (stage.status !== "awaiting_input") return false;
         stage.status = "running";
         delete stage.awaitingInputSince;
@@ -859,7 +903,7 @@ export function createStore(): Store {
       // instead of leaking. The error message is intentionally generic — the
       // caller already issued a session boundary, exact cause isn't needed.
       for (const entry of _resolvers.values()) {
-        entry.reject(new Error("pi-workflows: store cleared"));
+        entry.reject(new Error("atomic-workflows: store cleared"));
       }
       _resolvers.clear();
       _stagePromptAnswers.clear();