@bastani/atomic 0.8.27-alpha.1 → 0.8.28-alpha.1

package/dist/builtin/workflows/src/extension/render-result.ts

@@ -110,11 +110,13 @@ type StageListItem = {
   awaitingInputSince?: number;
   pendingPrompt?: PendingPrompt;
   inputRequest?: StageInputRequest;
+  promptFootprint?: PendingPrompt;
 };
 type StageListResult = { action: "stages"; runId: string; filter: string; stages: StageListItem[]; error?: string };
 type StageDetailItem = StageSnapshot & { transcriptPath?: string };
 type StageDetailResult = { action: "stage"; runId: string; stage?: StageDetailItem; error?: string };
 type TranscriptEntry = { role: string; text?: string; toolName?: string; output?: string; timestamp?: number };
+type TranscriptInlineMode = "path_only" | "preview" | "fallback_preview";
 type TranscriptResult = {
   action: "transcript";
   runId: string;
@@ -127,6 +129,9 @@ type TranscriptResult = {
   sessionId?: string;
   sessionFile?: string;
   transcriptPath?: string;
+  lazyReadPrompt?: string;
+  fallbackNote?: string;
+  inlineMode?: TranscriptInlineMode;
 };
 type SendResult = { action: "send"; runId: string; stageId: string; delivery: string; status: "ok" | "noop"; message: string };
 type PauseResult = { action: "pause"; runId: string; status: string; message: string };
@@ -213,7 +218,7 @@ function renderNotice(
 const TRANSCRIPT_NOTICE_ENTRY_LIMIT = 5;
 const TRANSCRIPT_NOTICE_CHAR_LIMIT = 240;
 
-function transcriptNoticeText(entries: readonly TranscriptEntry[]): string {
+function transcriptEntriesNoticeText(entries: readonly TranscriptEntry[]): string {
   if (entries.length === 0) return "no transcript entries";
   const shown = entries.slice(0, TRANSCRIPT_NOTICE_ENTRY_LIMIT);
   const text = shown
@@ -225,6 +230,21 @@ function transcriptNoticeText(entries: readonly TranscriptEntry[]): string {
   return fitLine(`${text}${entrySuffix}`, TRANSCRIPT_NOTICE_CHAR_LIMIT);
 }
 
+function transcriptNoticeText(result: TranscriptResult): string {
+  if ((result.inlineMode === "path_only" || result.lazyReadPrompt !== undefined) && result.entries.length === 0) {
+    const path = result.transcriptPath ?? result.sessionFile ?? "transcript file";
+    const count = result.entryCount === undefined
+      ? ""
+      : ` (${result.entryCount} ${result.entryCount === 1 ? "entry" : "entries"})`;
+    return fitLine(`not inlined; read ${path}${count}`, TRANSCRIPT_NOTICE_CHAR_LIMIT);
+  }
+  const entriesText = transcriptEntriesNoticeText(result.entries);
+  if (result.inlineMode === "fallback_preview" || result.fallbackNote !== undefined) {
+    return fitLine(`no session file; preview: ${entriesText}`, TRANSCRIPT_NOTICE_CHAR_LIMIT);
+  }
+  return entriesText;
+}
+
 export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts): string {
   const partial = opts?.isPartial === true;
   const themed = opts?.plain !== true;
@@ -350,7 +370,7 @@ export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts
 
     case "transcript": {
       const r = result as TranscriptResult;
-      const text = transcriptNoticeText(r.entries);
+      const text = transcriptNoticeText(r);
       const suffix = r.truncated ? " (truncated)" : "";
       return renderNotice("WORKFLOW TRANSCRIPT", `${r.runId}/${r.stageId.slice(0, 12)} ${r.source}: ${text}${suffix}`, opts, themed);
     }

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -114,7 +114,7 @@ export const WorkflowParametersSchema = Type.Object({
     Type.Literal("resume"),
     Type.Literal("reload"),
   ], {
-    description: "Workflow action: run/list/get/inputs/status, inspect stage metadata, send messages or prompt answers, pause/resume/interrupt/kill runs, or reload workflow resources. For transcript inspection, prefer status/stages/stage first to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript defaults to at most 5 recent entries and explicit tail/limit overrides that preview.",
+    description: "Workflow action: run/list/get/inputs/status, inspect stage metadata, send messages or prompt answers, pause/resume/interrupt/kill runs, or reload workflow resources. For transcript inspection, prefer status/stages/stage first to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
   })),
   runId: Type.Optional(Type.String({
     description: "Run identifier or unique prefix for status/stages/stage/transcript/send/pause/resume/interrupt/kill. Use '--all' or all:true for supported bulk run-control actions.",
@@ -146,14 +146,14 @@ export const WorkflowParametersSchema = Type.Object({
   })),
   limit: Type.Optional(Type.Integer({
     minimum: 0,
-    description: "Transcript-only: explicitly inline at most this many recent entries. Omit both limit and tail to use the default 5-entry preview plus metadata/path; prefer rg/grep on the exact quoted sessionFile/transcriptPath for targeted lookup without rewriting platform path separators.",
+    description: "Transcript-only: explicitly inline at most this many recent entries. Omit both limit and tail to use the path-only default when sessionFile/transcriptPath exists; prefer rg/grep on the exact quoted sessionFile/transcriptPath for targeted lookup without rewriting platform path separators.",
   })),
   tail: Type.Optional(Type.Integer({
     minimum: 0,
     description: "Transcript-only: explicitly inline the last N entries; overrides limit. Use for quick recent-context checks after status/stages/stage expose the transcript path.",
   })),
   includeToolOutput: Type.Optional(Type.Boolean({
-    description: "Transcript-only: include captured tool output entries when building transcript results from stage snapshots; prefer rg/grep on the exact quoted sessionFile/transcriptPath for large outputs. Live session transcripts may not expose tool output.",
+    description: "Transcript-only: include captured tool output entries when building inlined snapshot previews; this does not bypass the path-only default. Prefer rg/grep on the exact quoted sessionFile/transcriptPath for large outputs. Live session transcripts may not expose tool output.",
   })),
   text: Type.Optional(Type.String({
     description: "Text to send to a stage for prompt answers, steering, follow-ups, or resume messages.",

package/dist/builtin/workflows/src/runs/foreground/executor.ts

@@ -14,6 +14,8 @@ import type {
   WorkflowRunContext,
   WorkflowUIContext,
   WorkflowUIAdapter,
+  WorkflowCustomUiFactory,
+  WorkflowCustomUiOptions,
   WorkflowInputSchema,
   StageContext,
   StageOptions,
@@ -56,7 +58,7 @@ import type {
   WorkflowFailureRecoverability,
   WorkflowFailureDisposition,
   PendingPrompt,
-  PromptKind,
+  CustomPromptIdentitySource,
   WorkflowChildReplaySnapshot,
   WorkflowChildRunRef,
 } from "../../shared/store-types.js";
@@ -108,7 +110,7 @@ export interface RunContinuationOpts {
   readonly resumeFromStageId: string;
 }
 
-export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "store" | "cancellation" | "overlay" | "registry" | "stageControlRegistry" | "continuation" | "onRunStart" | "onStageStart" | "onStageEnd" | "onRunEnd"> {
+export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "store" | "cancellation" | "overlay" | "registry" | "stageControlRegistry" | "continuation" | "onRunStart" | "onStageStart" | "onStageEnd" | "onRunEnd" | "ui"> {
   adapters?: StageAdapters;
   /** Invocation working directory exposed to workflow definitions as ctx.cwd. */
   cwd?: string;
@@ -271,14 +273,28 @@ function resolveInputRuntimeDefaults(
 // HIL unavailable fallback — rejects with precise per-primitive error
 // ---------------------------------------------------------------------------
 
-interface PromptDescriptor {
-  readonly kind: PromptKind;
+type PrimitivePromptDescriptor =
+  | { readonly kind: "input"; readonly message: string; readonly initial?: string }
+  | { readonly kind: "confirm"; readonly message: string }
+  | { readonly kind: "select"; readonly message: string; readonly choices: readonly string[] }
+  | { readonly kind: "editor"; readonly message: string; readonly initial?: string };
+
+interface CustomPromptDescriptor<T> {
+  readonly kind: "custom";
   readonly message: string;
-  readonly choices?: readonly string[];
-  readonly initial?: string;
+  readonly factory: WorkflowCustomUiFactory<T>;
+  readonly options?: WorkflowCustomUiOptions;
+  readonly customIdentityHash: string;
+  readonly customIdentitySource: CustomPromptIdentitySource;
 }
 
-function fallbackForPromptDescriptor(descriptor: PromptDescriptor): unknown {
+type PromptDescriptor<T = unknown> = PrimitivePromptDescriptor | CustomPromptDescriptor<T>;
+
+function isCustomPromptDescriptor<T>(descriptor: PromptDescriptor<T>): descriptor is CustomPromptDescriptor<T> {
+  return descriptor.kind === "custom";
+}
+
+function fallbackForPromptDescriptor(descriptor: PrimitivePromptDescriptor): unknown {
   switch (descriptor.kind) {
     case "input":
     case "editor":
@@ -286,7 +302,7 @@ function fallbackForPromptDescriptor(descriptor: PromptDescriptor): unknown {
     case "confirm":
       return false;
     case "select":
-      return descriptor.choices?.[0] ?? "";
+      return descriptor.choices[0] ?? "";
   }
 }
 
@@ -295,8 +311,12 @@ function makePrompt(descriptor: PromptDescriptor): PendingPrompt {
     id: `hil-${crypto.randomUUID()}`,
     kind: descriptor.kind,
     message: descriptor.message,
-    ...(descriptor.choices !== undefined ? { choices: descriptor.choices } : {}),
-    ...(descriptor.initial !== undefined ? { initial: descriptor.initial } : {}),
+    ...(!isCustomPromptDescriptor(descriptor) && descriptor.kind === "select" ? { choices: descriptor.choices } : {}),
+    ...(!isCustomPromptDescriptor(descriptor) && (descriptor.kind === "input" || descriptor.kind === "editor") && descriptor.initial !== undefined ? { initial: descriptor.initial } : {}),
+    ...(isCustomPromptDescriptor(descriptor) ? {
+      customIdentityHash: descriptor.customIdentityHash,
+      customIdentitySource: descriptor.customIdentitySource,
+    } : {}),
     createdAt: Date.now(),
   };
 }
@@ -307,13 +327,19 @@ function stableHash(value: unknown): string {
 }
 
 function promptDescriptorHash(descriptor: PromptDescriptor): string {
+  if (isCustomPromptDescriptor(descriptor)) {
+    return stableHash({
+      kind: "custom",
+      customIdentityHash: descriptor.customIdentityHash,
+    });
+  }
   return stableHash({
     kind: descriptor.kind,
     message: descriptor.message,
-    choices: descriptor.choices ?? [],
+    choices: descriptor.kind === "select" ? descriptor.choices : [],
     // Include input/editor initial text because it is visible prompt context;
     // changing it should not replay a stale answer from the same callsite.
-    initial: descriptor.initial ?? null,
+    initial: descriptor.kind === "input" || descriptor.kind === "editor" ? descriptor.initial ?? null : null,
   });
 }
 
@@ -334,6 +360,80 @@ function hilAbortError(signal: AbortSignal): Error {
     : new Error("atomic-workflows: HIL aborted");
 }
 
+function resolveCustomPromptIdentity<T>(
+  factory: WorkflowCustomUiFactory<T>,
+  options: WorkflowCustomUiOptions | undefined,
+): Pick<CustomPromptDescriptor<T>, "customIdentityHash" | "customIdentitySource"> {
+  const replayIdentity = options?.replayIdentity?.trim();
+  if (replayIdentity !== undefined && replayIdentity.length > 0) {
+    return {
+      customIdentityHash: stableHash({ source: "caller", value: replayIdentity }),
+      customIdentitySource: "caller",
+    };
+  }
+  if (factory.name.trim().length > 0) {
+    return {
+      customIdentityHash: stableHash({ source: "factory", value: factory.name }),
+      customIdentitySource: "factory",
+    };
+  }
+  try {
+    const source = Function.prototype.toString.call(factory);
+    if (source.trim().length > 0) {
+      return {
+        customIdentityHash: stableHash({ source: "factory", value: source }),
+        customIdentitySource: "factory",
+      };
+    }
+  } catch {
+    // Fall through to callsite-only identity below.
+  }
+  return {
+    customIdentityHash: stableHash({ source: "callsite" }),
+    customIdentitySource: "callsite",
+  };
+}
+
+function customPromptDescriptor<T>(
+  factory: WorkflowCustomUiFactory<T>,
+  options: WorkflowCustomUiOptions | undefined,
+): CustomPromptDescriptor<T> {
+  const label = options?.label?.trim();
+  return {
+    kind: "custom",
+    message: label && label.length > 0 ? label : "Custom TUI prompt",
+    factory,
+    ...(options !== undefined ? { options } : {}),
+    ...resolveCustomPromptIdentity(factory, options),
+  };
+}
+
+interface MergedHilSignal {
+  readonly signal: AbortSignal;
+  readonly dispose: () => void;
+}
+
+function mergeHilSignals(primary: AbortSignal, secondary: AbortSignal | undefined): MergedHilSignal {
+  if (secondary === undefined) return { signal: primary, dispose: () => undefined };
+  const controller = new AbortController();
+  const abortFrom = (source: AbortSignal): void => {
+    if (!controller.signal.aborted) controller.abort(source.reason);
+  };
+  const onPrimaryAbort = (): void => abortFrom(primary);
+  const onSecondaryAbort = (): void => abortFrom(secondary);
+  primary.addEventListener("abort", onPrimaryAbort, { once: true });
+  secondary.addEventListener("abort", onSecondaryAbort, { once: true });
+  if (primary.aborted) abortFrom(primary);
+  else if (secondary.aborted) abortFrom(secondary);
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      primary.removeEventListener("abort", onPrimaryAbort);
+      secondary.removeEventListener("abort", onSecondaryAbort);
+    },
+  };
+}
+
 function makeUnavailableUIContext(): WorkflowUIContext {
   const msg = (primitive: string): string =>
     `atomic-workflows: HIL ctx.ui.${primitive} is unavailable because Atomic runtime did not provide a UI adapter`;
@@ -342,6 +442,31 @@ function makeUnavailableUIContext(): WorkflowUIContext {
     confirm: () => Promise.reject(new Error(msg("confirm"))),
     select: () => Promise.reject(new Error(msg("select"))),
     editor: () => Promise.reject(new Error(msg("editor"))),
+    custom: () => Promise.reject(new Error(msg("custom"))),
+  };
+}
+
+function normalizeUIContext(adapter: WorkflowUIAdapter | undefined): WorkflowUIContext {
+  const unavailable = makeUnavailableUIContext();
+  if (adapter === undefined) return unavailable;
+  return {
+    input(prompt) {
+      return adapter.input.call(adapter, prompt);
+    },
+    confirm(message) {
+      return adapter.confirm.call(adapter, message);
+    },
+    select<T extends string>(message: string, options: readonly T[]): Promise<T> {
+      return adapter.select.call(adapter, message, options) as Promise<T>;
+    },
+    editor(initial) {
+      return adapter.editor.call(adapter, initial);
+    },
+    custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
+      return adapter.custom !== undefined
+        ? adapter.custom.call(adapter, factory, options) as Promise<T>
+        : unavailable.custom(factory, options);
+    },
   };
 }
 
@@ -1400,8 +1525,19 @@ export async function runChain(
   return workflowDetailsFromRun("chain", runResult, results, options, validationWarnings);
 }
 
-function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+export function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
   if (signal.aborted) {
+    // Callers invoke `raceAbort(call(), signal)`, so `call()` is evaluated —
+    // and the underlying work (e.g. a stage prompt) is already in flight —
+    // before this function observes an already-aborted signal. Attach a no-op
+    // rejection handler so that in-flight promise can never surface as an
+    // unhandled rejection. Without this, killing a workflow mid-prompt orphans
+    // the prompt promise; its eventual rejection (commonly
+    // "No API key found for ...") escapes every workflow error boundary and is
+    // raised as a process-level uncaught exception that crashes the whole CLI.
+    // The run is being aborted, so the orphaned settlement is intentionally
+    // discarded here.
+    void promise.catch(() => {});
     return Promise.reject(signal.reason ?? new DOMException("workflow killed", "AbortError"));
   }
   return new Promise<T>((resolve, reject) => {
@@ -2640,11 +2776,16 @@ export async function run<TInputs extends WorkflowInputValues>(
     };
   };
 
-  const buildPromptNodeUiAdapter = (): WorkflowUIAdapter => {
-    const ask = async (descriptor: PromptDescriptor): Promise<unknown> => {
+  const buildPromptNodeUiAdapter = (): WorkflowUIContext => {
+    const ask = async <T>(descriptor: PromptDescriptor<T>): Promise<unknown> => {
+      const isCustom = isCustomPromptDescriptor(descriptor);
       if (ownController.signal.aborted) {
+        if (isCustom) throw hilAbortError(ownController.signal);
         return fallbackForPromptDescriptor(descriptor);
       }
+      if (isCustom && descriptor.options?.signal?.aborted) {
+        throw hilAbortError(descriptor.options.signal);
+      }
 
       const prompt = makePrompt(descriptor);
       const stageId = crypto.randomUUID();
@@ -2741,6 +2882,55 @@ export async function run<TInputs extends WorkflowInputValues>(
         finalizePromptStage("completed");
         return replayAnswer.value;
       }
+
+      if (isCustom) {
+        if (descriptor.options?.overlay === true) {
+          const error = new Error("atomic-workflows: ctx.ui.custom overlay mode is unavailable in the workflow graph viewer");
+          applyFailureToStage(stageSnapshot, classifyExecutorFailure(error));
+          finalizePromptStage("failed");
+          throw error;
+        }
+
+        const mergedSignal = mergeHilSignals(ownController.signal, descriptor.options?.signal);
+        try {
+          if (mergedSignal.signal.aborted) throw hilAbortError(mergedSignal.signal);
+          const accepted = activeStore.recordStageAwaitingInput(runId, stageId, true, prompt.createdAt);
+          if (!accepted) {
+            const error = new Error("atomic-workflows: ctx.ui.custom prompt node is unavailable");
+            stageSnapshot.skippedReason = "prompt-unavailable";
+            finalizePromptStage("skipped");
+            throw error;
+          }
+          const response = await stageUiBroker.requestCustomUi(
+            runId,
+            stageId,
+            descriptor.factory as unknown as Parameters<typeof stageUiBroker.requestCustomUi>[2],
+            descriptor.options as Parameters<typeof stageUiBroker.requestCustomUi>[3],
+            mergedSignal.signal,
+          );
+          activeStore.recordStagePromptAnswer(runId, stageId, prompt, response, {
+            answerSource: "workflow_ui",
+          });
+          finalizePromptStage("completed");
+          return response;
+        } catch (err) {
+          activeStore.recordStageAwaitingInput(runId, stageId, false);
+          stageUiBroker.cancelStagePrompt(runId, stageId, err);
+          if (mergedSignal.signal.aborted) {
+            stageSnapshot.skippedReason = ownController.signal.aborted ? "run-aborted" : "prompt-aborted";
+            finalizePromptStage("skipped");
+            throw hilAbortError(mergedSignal.signal);
+          }
+          if (!finalized) {
+            applyFailureToStage(stageSnapshot, classifyExecutorFailure(err));
+            finalizePromptStage("failed");
+          }
+          throw err;
+        } finally {
+          mergedSignal.dispose();
+        }
+      }
+
       const accepted = activeStore.recordStagePendingPrompt(runId, stageId, prompt);
       if (!accepted) {
         stageSnapshot.skippedReason = "prompt-unavailable";
@@ -2818,6 +3008,10 @@ export async function run<TInputs extends WorkflowInputValues>(
         });
         return typeof response === "string" ? response : initial ?? "";
       },
+      async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
+        const response = await ask(customPromptDescriptor(factory, options));
+        return response as T;
+      },
     };
   };
 
@@ -2827,7 +3021,7 @@ export async function run<TInputs extends WorkflowInputValues>(
     get cwd() { return resolveWorkflowCwd(); },
     // Prompt nodes and caller-provided UI adapters are mutually exclusive;
     // executor-owned prompt nodes intentionally take precedence when enabled.
-    ui: opts.usePromptNodesForUi === true ? buildPromptNodeUiAdapter() : opts.ui ?? makeUnavailableUIContext(),
+    ui: opts.usePromptNodesForUi === true ? buildPromptNodeUiAdapter() : normalizeUIContext(opts.ui),
 
     stage(name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope) {
       options = stageOptionsWithGitWorktree(stageOptionsWithInputDefaults(options, inputRuntimeDefaults), workflowInvocationCwd);

package/dist/builtin/workflows/src/sdk-surface.ts

@@ -37,7 +37,7 @@ export type { StageNode } from "./runs/shared/graph-inference.js";
 export { setupGitWorktree } from "./runs/shared/worktree.js";
 export type { GitWorktreeSetupOptions, GitWorktreeSetupResult } from "./runs/shared/worktree.js";
 export { createStore, store } from "./shared/store.js";
-export type { RunStatus, StageStatus, ToolEvent, StageSnapshot, RunSnapshot, StoreSnapshot, WorkflowNotice, NoticeLevel, WorkflowOverlayAdapter, PromptKind, PendingPrompt } from "./shared/store-types.js";
+export type { RunStatus, StageStatus, ToolEvent, StageSnapshot, RunSnapshot, StoreSnapshot, WorkflowNotice, NoticeLevel, WorkflowOverlayAdapter, PromptKind, CustomPromptIdentitySource, PendingPrompt } from "./shared/store-types.js";
 
 // Phase D — cancellation registry
 export { createCancellationRegistry, cancellationRegistry } from "./runs/background/cancellation-registry.js";

package/dist/builtin/workflows/src/shared/authoring-contract.d.ts

@@ -1,10 +1,13 @@
 /**
- * Dependency-light workflow authoring contract shared by the runtime type graph
- * and the standalone package typing surface.
+ * Workflow authoring contract shared by the runtime type graph and the
+ * standalone package typing surface.
  *
- * This module intentionally imports only TypeBox types. Do not import
- * @bastani/atomic, executor internals, stores, or runtime graph modules here.
+ * This module intentionally avoids executor internals, stores, or runtime graph
+ * modules here. Public custom-TUI types are type-only imports from the same
+ * extension-compatible surfaces used by Atomic extension UI.
  */
+import type { KeybindingsManager, Theme } from "@bastani/atomic";
+import type { Component, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
 import type { Static, TOptional, TSchema } from "typebox";
 export type { Static, TSchema };
 export type WorkflowSerializablePrimitive = string | number | boolean | null;
@@ -335,13 +338,47 @@ export interface WorkflowChildResult<TOutputs extends WorkflowOutputValues = Wor
     readonly status: "completed";
     readonly outputs: TOutputs;
 }
+export type WorkflowCustomUiComponent = Component & {
+    dispose?(): void;
+};
+export type WorkflowCustomUiTui = TUI;
+export type WorkflowCustomUiTheme = Theme;
+export type WorkflowCustomUiKeybindings = KeybindingsManager;
+export type WorkflowCustomUiOverlayOptions = OverlayOptions;
+export type WorkflowCustomUiOverlayHandle = OverlayHandle;
+export type WorkflowCustomUiFactory<T> = (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (value: T) => void) => WorkflowCustomUiComponent | Promise<WorkflowCustomUiComponent>;
+export interface WorkflowCustomUiOptions {
+    /** Render as a nested overlay. Workflow graph hosts may reject this when unsupported. */
+    readonly overlay?: boolean;
+    /** AbortSignal to programmatically dismiss the custom UI. */
+    readonly signal?: AbortSignal;
+    /** Overlay positioning/sizing options. Can be static or a function for dynamic updates. */
+    readonly overlayOptions?: OverlayOptions | (() => OverlayOptions);
+    /** Called with the real overlay handle after an overlay is shown. */
+    readonly onHandle?: (handle: OverlayHandle) => void;
+    /**
+     * Workflow-only replay identity. Recommended whenever widget state or
+     * semantics can change without the callsite changing. Do not include secrets;
+     * the runtime stores only a hash.
+     */
+    readonly replayIdentity?: string;
+    /** Safe display-only label for graph/status surfaces. Defaults to "Custom TUI prompt". Not part of replay identity. */
+    readonly label?: string;
+}
 export interface WorkflowUIContext {
     input(prompt: string): Promise<string>;
     confirm(message: string): Promise<boolean>;
     select<T extends string>(message: string, options: readonly T[]): Promise<T>;
     editor(initial?: string): Promise<string>;
+    custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T>;
+}
+export interface WorkflowUIAdapter {
+    input(prompt: string): Promise<string>;
+    confirm(message: string): Promise<boolean>;
+    select<T extends string>(message: string, options: readonly T[]): Promise<T>;
+    editor(initial?: string): Promise<string>;
+    custom?<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T>;
 }
-export type WorkflowUIAdapter = WorkflowUIContext;
 export interface WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues, TDefinitionBrand extends object = {}> {
     readonly inputs: Readonly<TInputs>;
     readonly cwd?: string;

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

@@ -32,10 +32,12 @@ export type WorkflowFailureCode =
   | "unknown";
 
 /**
- * Human-in-the-loop prompt kind. Mirrors the four `WorkflowUIContext` methods.
+ * Human-in-the-loop prompt kind. Mirrors the `WorkflowUIContext` methods.
  * cross-ref: src/shared/types.ts WorkflowUIContext
  */
-export type PromptKind = "input" | "confirm" | "select" | "editor";
+export type PromptKind = "input" | "confirm" | "select" | "editor" | "custom";
+
+export type CustomPromptIdentitySource = "caller" | "factory" | "callsite";
 
 /**
  * A pending HIL prompt awaiting user response. Surfaced through the graph
@@ -53,6 +55,10 @@ export interface PendingPrompt {
   readonly choices?: readonly string[];
   /** Initial value for `kind: "input"` and `kind: "editor"`. */
   readonly initial?: string;
+  /** Hash of caller-supplied or derived replay identity for `kind: "custom"`. */
+  readonly customIdentityHash?: string;
+  /** Explains how a custom prompt replay identity was derived without storing the raw identity. */
+  readonly customIdentitySource?: CustomPromptIdentitySource;
   /** Issue timestamp (ms since epoch). */
   readonly createdAt: number;
 }

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

@@ -119,6 +119,11 @@ export interface ResolveStagePendingPromptOptions {
   readonly answerSource?: StagePromptAnswerSource;
 }
 
+export interface RecordStagePromptAnswerOptions {
+  /** Identifies who answered the prompt so notification code can avoid echoing workflow-tool answers. */
+  readonly answerSource?: StagePromptAnswerSource;
+}
+
 export interface Store {
   runs(): readonly RunSnapshot[];
   notices(): readonly WorkflowNotice[];
@@ -206,6 +211,19 @@ export interface Store {
   ): boolean;
   /** Wait for a stage/node-scoped HIL prompt to resolve. */
   awaitStagePendingPrompt(runId: string, stageId: string, promptId: string): Promise<unknown>;
+  /**
+   * Record a live-only prompt answer for prompt-node UIs that do not use
+   * `stage.pendingPrompt` (notably arbitrary `ctx.ui.custom<T>` widgets).
+   * The raw value stays in the private answer ledger and is never serialized
+   * into snapshots or persistence.
+   */
+  recordStagePromptAnswer(
+    runId: string,
+    stageId: string,
+    prompt: PendingPrompt,
+    response: unknown,
+    options?: RecordStagePromptAnswerOptions,
+  ): boolean;
   /**
    * Record a live-only draft for an active stage-local input/editor prompt.
    * Draft text may contain secrets and must never be copied into snapshots,
@@ -774,6 +792,39 @@ export function createStore(): Store {
       });
     },
 
+    recordStagePromptAnswer(
+      runId: string,
+      stageId: string,
+      prompt: PendingPrompt,
+      response: unknown,
+      options: RecordStagePromptAnswerOptions = {},
+    ): 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;
+      _stagePromptAnswers.set(stagePromptAnswerKey(runId, stageId), {
+        runId,
+        stageId,
+        promptId: prompt.id,
+        kind: prompt.kind,
+        value: response,
+        answeredAt: Date.now(),
+        ...(options.answerSource !== undefined ? { answerSource: options.answerSource } : {}),
+      });
+      if (stage.promptFootprint === undefined) stage.promptFootprint = { ...prompt };
+      stage.promptAnswerState = "available";
+      if (stage.status === "awaiting_input") {
+        stage.status = "running";
+        delete stage.awaitingInputSince;
+      }
+      _version++;
+      notify();
+      return true;
+    },
+
     recordStagePromptDraft(runId: string, stageId: string, promptId: string, text: string): boolean {
       if (stageHasActiveTextPrompt(runId, stageId, promptId) === undefined) return false;
       _stagePromptDrafts.set(stagePromptDraftKey(runId, stageId, promptId), text);

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

@@ -116,14 +116,24 @@ export interface WorkflowChildResult<TOutputs extends WorkflowOutputValues = Wor
  * Each primitive suspends the current stage until the user responds.
  * Mirrors pi ctx.ui.input / confirm / select / editor methods.
  */
-export type WorkflowUIContext = AuthoringContract.WorkflowUIContext;
+export type WorkflowCustomUiComponent = AuthoringContract.WorkflowCustomUiComponent;
+export type WorkflowCustomUiTui = AuthoringContract.WorkflowCustomUiTui;
+export type WorkflowCustomUiTheme = AuthoringContract.WorkflowCustomUiTheme;
+export type WorkflowCustomUiKeybindings = AuthoringContract.WorkflowCustomUiKeybindings;
+export type WorkflowCustomUiOverlayOptions = AuthoringContract.WorkflowCustomUiOverlayOptions;
+export type WorkflowCustomUiOverlayHandle = AuthoringContract.WorkflowCustomUiOverlayHandle;
+export type WorkflowCustomUiFactory<T> = AuthoringContract.WorkflowCustomUiFactory<T>;
+export type WorkflowCustomUiOptions = AuthoringContract.WorkflowCustomUiOptions;
+
+export interface WorkflowUIContext extends AuthoringContract.WorkflowUIContext {}
 
 /**
  * Adapter supplied by the pi runtime (or test harness) to back the HIL
- * primitives.  Must implement the same surface as WorkflowUIContext so that
- * the executor can delegate directly.
+ * primitives.  The custom-widget method is optional for compatibility with
+ * existing primitive-only adapters; the executor normalizes a missing custom
+ * method to the same unavailable-UI rejection used in headless mode.
  */
-export type WorkflowUIAdapter = AuthoringContract.WorkflowUIAdapter;
+export interface WorkflowUIAdapter extends AuthoringContract.WorkflowUIAdapter {}
 
 // ---------------------------------------------------------------------------
 // StageOptions — per-stage configuration + pi SDK session options

package/dist/builtin/workflows/src/tui/graph-view.ts

@@ -357,7 +357,10 @@ export class GraphView implements Component {
       ? expandWorkflowGraph(this.currentSnapshot, run.id)
       : { stages: [], targets: new Map() };
     const stages = [...this.expandedGraph.stages];
-    const hasStagePrompt = stages.some((stage) => stage.pendingPrompt !== undefined);
+    const hasStagePrompt = stages.some((stage) =>
+      stage.pendingPrompt !== undefined ||
+      (stage.status === "awaiting_input" && stage.promptFootprint?.kind === "custom")
+    );
     if (!hasStagePrompt) return stages;
     return stages.filter((stage) => {
       // Prompt-node injection can leave unstarted author stages in the store