@bastani/atomic 0.8.27 → 0.8.28-alpha.2

package/dist/builtin/workflows/src/extension/index.ts

@@ -129,7 +129,7 @@ export const WORKFLOW_TOOL_DESCRIPTION =
   "For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
   "For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
   "quote the exact path without rewriting separators (Windows backslashes are valid), " +
-  "search it with rg/grep, and read small ranges; transcript defaults to at most 5 recent entries and explicit tail/limit overrides that preview.";
+  "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.";
 
 // ---------------------------------------------------------------------------
 // Minimal ExtensionAPI structural types
@@ -644,8 +644,10 @@ function renderTranscriptToolContent(
   if (result.transcriptPath) lines.push(`transcriptPathJson: ${JSON.stringify(result.transcriptPath)}`);
   if (result.entryCount !== undefined) lines.push(`availableEntries: ${result.entryCount}`);
   if (result.entryLimit !== undefined) lines.push(`entryLimit: ${result.entryLimit}`);
+  if (result.lazyReadPrompt) lines.push(`lazyReadPrompt: ${result.lazyReadPrompt}`);
+  if (result.fallbackNote) lines.push(`fallbackNote: ${result.fallbackNote}`);
   if (result.entries.length === 0) {
-    lines.push("entries: none");
+    lines.push(result.inlineMode === "path_only" || result.lazyReadPrompt ? "entries: not inlined" : "entries: none");
     return lines.join("\n");
   }
   lines.push("entries:");
@@ -702,6 +704,10 @@ function renderStagesToolContent(
       lines.push("inputRequest:");
       lines.push(JSON.stringify(stage.inputRequest, null, 2));
     }
+    if (stage.promptFootprint !== undefined) {
+      lines.push("promptFootprint:");
+      lines.push(JSON.stringify(stage.promptFootprint, null, 2));
+    }
   });
   return lines.join("\n");
 }
@@ -800,6 +806,7 @@ type WorkflowStageSummary = {
   awaitingInputSince?: number;
   pendingPrompt?: StageSnapshot["pendingPrompt"];
   inputRequest?: StageSnapshot["inputRequest"];
+  promptFootprint?: StageSnapshot["promptFootprint"];
 };
 
 type WorkflowTranscriptEntry = {
@@ -842,6 +849,9 @@ function summarizeStage(stage: StageSnapshot): WorkflowStageSummary {
     inputRequest: stage.inputRequest === undefined
       ? undefined
       : structuredClone(stage.inputRequest),
+    promptFootprint: stage.promptFootprint === undefined
+      ? undefined
+      : structuredClone(stage.promptFootprint),
   };
 }
 
@@ -854,6 +864,12 @@ type TranscriptEntrySelection = {
   entryLimit?: number;
 };
 
+type WorkflowTranscriptResult = Extract<WorkflowToolResult, { action: "transcript" }>;
+
+function isTranscriptPreviewExplicit(args: WorkflowToolArgs): boolean {
+  return args.tail !== undefined || args.limit !== undefined;
+}
+
 function requestedTranscriptEntryLimit(args: WorkflowToolArgs): number {
   const raw = args.tail ?? args.limit;
   if (raw === undefined) return DEFAULT_TRANSCRIPT_LIMIT;
@@ -891,6 +907,80 @@ function selectTranscriptEntries(
   };
 }
 
+function transcriptLazyReadPrompt(path: string): string {
+  return `Transcript not inlined to protect context. Read it lazily from ${path} with your file read tools (read small ranges; rg/grep for targeted lookups).`;
+}
+
+function transcriptFallbackNote(limit: number): string {
+  return `No transcript file path is available for this stage; falling back to a bounded inline preview of up to ${limit} recent ${limit === 1 ? "entry" : "entries"}.`;
+}
+
+/**
+ * Shape a transcript tool result, keeping the context-safe path-only default
+ * the cheap hot path for the large runs #1314 protects against.
+ *
+ * `buildEntries` is a thunk so the default case (a transcript file path exists
+ * and no explicit `tail`/`limit` was requested) never materializes entry bodies
+ * just to discard them. Only the caller-provided `entryCount` is needed for the
+ * advisory count, which matches what `buildEntries()` would yield. The thunk is
+ * invoked solely for the explicit-preview and no-path fallback branches.
+ */
+function shapeTranscriptResult(input: {
+  runId: string;
+  stageId: string;
+  source: "live" | "snapshot";
+  entryCount: number;
+  buildEntries: () => readonly WorkflowTranscriptEntry[];
+  args: WorkflowToolArgs;
+  sessionId?: string | undefined;
+  sessionFile?: string | undefined;
+  transcriptPath?: string | undefined;
+}): WorkflowTranscriptResult {
+  // `transcriptPath` already falls back to `sessionFile`, so it is the single
+  // resolved path the agent should lazily read.
+  const transcriptPath = input.transcriptPath ?? input.sessionFile;
+  if (transcriptPath !== undefined && !isTranscriptPreviewExplicit(input.args)) {
+    const result: WorkflowTranscriptResult = {
+      action: "transcript",
+      runId: input.runId,
+      stageId: input.stageId,
+      source: input.source,
+      entries: [],
+      // `truncated` here means "more transcript exists on disk than was inlined"
+      // (everything, since the default inlines nothing), not "an explicit limit
+      // clipped results". It only drives the cosmetic "(truncated)" notice
+      // suffix; no consumer re-fetches on it.
+      truncated: input.entryCount > 0,
+      entryCount: input.entryCount,
+      entryLimit: 0,
+      lazyReadPrompt: transcriptLazyReadPrompt(transcriptPath),
+      inlineMode: "path_only",
+    };
+    if (input.sessionId !== undefined) result.sessionId = input.sessionId;
+    if (input.sessionFile !== undefined) result.sessionFile = input.sessionFile;
+    result.transcriptPath = transcriptPath;
+    return result;
+  }
+
+  const limited = selectTranscriptEntries(input.buildEntries(), input.args);
+  const result: WorkflowTranscriptResult = {
+    action: "transcript",
+    runId: input.runId,
+    stageId: input.stageId,
+    source: input.source,
+    entries: limited.entries,
+    truncated: limited.truncated,
+    entryCount: limited.entryCount,
+    entryLimit: limited.entryLimit,
+    inlineMode: transcriptPath === undefined ? "fallback_preview" : "preview",
+  };
+  if (input.sessionId !== undefined) result.sessionId = input.sessionId;
+  if (input.sessionFile !== undefined) result.sessionFile = input.sessionFile;
+  if (transcriptPath !== undefined) result.transcriptPath = transcriptPath;
+  if (transcriptPath === undefined) result.fallbackNote = transcriptFallbackNote(limited.entryLimit ?? DEFAULT_TRANSCRIPT_LIMIT);
+  return result;
+}
+
 function messageText(content: MessageLike["content"]): string | undefined {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return undefined;
@@ -1463,33 +1553,40 @@ export function makeExecuteWorkflowTool(
         if (liveHandle !== undefined) {
           const sessionFile = liveHandle.sessionFile ?? snapshot?.sessionFile;
           const sessionId = liveHandle.sessionId ?? snapshot?.sessionId;
-          const limited = selectTranscriptEntries(
-            liveHandle.messages.map((m) => transcriptEntryFromMessage(m as MessageLike)),
-            args,
-          );
-          return {
-            action: "transcript",
+          return shapeTranscriptResult({
             runId: stageRunId,
             stageId: stage.stageId,
             source: "live",
-            ...limited,
+            entryCount: liveHandle.messages.length,
+            buildEntries: () =>
+              liveHandle.messages.map((m) => transcriptEntryFromMessage(m as MessageLike)),
+            args,
             sessionId,
             sessionFile,
             transcriptPath: sessionFile,
-          };
+          });
         }
-        const fallback = snapshotTranscriptEntries(snapshot, args.includeToolOutput === true);
-        const limited = selectTranscriptEntries(fallback, args);
-        return {
-          action: "transcript",
+        const snapshotSessionFile = snapshot?.sessionFile;
+        const includeSnapshotOutput = args.includeToolOutput === true && (
+          isTranscriptPreviewExplicit(args) || snapshotSessionFile === undefined
+        );
+        // Cheap count matches `snapshotTranscriptEntries(...).length` (one entry
+        // per tool event plus the optional terminal result/error entries)
+        // without building bodies for the path-only default.
+        const snapshotEntryCount = (snapshot?.toolEvents?.length ?? 0)
+          + (snapshot?.result !== undefined ? 1 : 0)
+          + (snapshot?.error !== undefined ? 1 : 0);
+        return shapeTranscriptResult({
           runId: stageRunId,
           stageId: stage.stageId,
           source: "snapshot",
-          ...limited,
+          entryCount: snapshotEntryCount,
+          buildEntries: () => snapshotTranscriptEntries(snapshot, includeSnapshotOutput),
+          args,
           sessionId: snapshot?.sessionId,
-          sessionFile: snapshot?.sessionFile,
-          transcriptPath: snapshot?.sessionFile,
-        };
+          sessionFile: snapshotSessionFile,
+          transcriptPath: snapshotSessionFile,
+        });
       }
 
       case "send": {
@@ -1543,6 +1640,24 @@ export function makeExecuteWorkflowTool(
             ok ? `Answered input request ${brokerPrompt.id}.` : `No matching pending input request ${brokerPrompt.id}.`,
           );
         }
+        const customPrompt = snapshot?.status === "awaiting_input" && snapshot.promptFootprint?.kind === "custom"
+          ? snapshot.promptFootprint
+          : undefined;
+        const targetsCustomPrompt =
+          customPrompt !== undefined &&
+          (args.promptId === undefined || args.promptId === customPrompt.id) &&
+          (requestedDelivery === "answer" ||
+            args.promptId !== undefined ||
+            requestedDelivery === "auto");
+        if (targetsCustomPrompt && customPrompt !== undefined) {
+          return workflowSendResult(
+            stageRunId,
+            stage.stageId,
+            "answer",
+            "noop",
+            `Custom UI prompt ${customPrompt.id} requires the interactive workflow graph; arbitrary ctx.ui.custom<T> results cannot be answered through workflow send.`,
+          );
+        }
         const targetsPrompt =
           requestedDelivery === "answer" ||
           args.promptId !== undefined ||

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";