@bastani/atomic 0.8.13-0 → 0.8.14-0

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

@@ -5,10 +5,25 @@
 
 import { truncateToWidth } from "../tui/text-helpers.js";
 
+/** Renderer-only subset of the canonical WorkflowToolArgs from index.ts. */
 export interface WorkflowToolArgs {
   workflow?: string;
   inputs?: Record<string, unknown>;
-  action?: "run" | "list" | "get" | "status" | "interrupt" | "kill" | "resume" | "inputs";
+  action?:
+    | "run"
+    | "list"
+    | "get"
+    | "status"
+    | "stages"
+    | "stage"
+    | "transcript"
+    | "send"
+    | "pause"
+    | "interrupt"
+    | "kill"
+    | "resume"
+    | "reload"
+    | "inputs";
   runId?: string;
   task?: { name?: string; prompt?: string; task?: string } | string;
   tasks?: readonly unknown[];
@@ -62,6 +77,24 @@ export function renderCall(args: WorkflowToolArgs, opts: RenderCallOpts = {}): s
     case "run":
       line = name === undefined ? "workflow: run" : `workflow: run ${quoted(name)}`;
       break;
+    case "stages":
+      line = name === undefined ? "workflow: list stages" : `workflow: list stages for ${quoted(name)}`;
+      break;
+    case "stage":
+      line = name === undefined ? "workflow: inspect stage" : `workflow: inspect stage in ${quoted(name)}`;
+      break;
+    case "transcript":
+      line = name === undefined ? "workflow: read stage transcript" : `workflow: read stage transcript in ${quoted(name)}`;
+      break;
+    case "send":
+      line = name === undefined ? "workflow: send to stage" : `workflow: send to stage in ${quoted(name)}`;
+      break;
+    case "pause":
+      line = name === undefined ? "workflow: pause run" : `workflow: pause run ${quoted(name)}`;
+      break;
+    case "reload":
+      line = "workflow: reload runtime";
+      break;
     case "interrupt":
       line = name === undefined
         ? "workflow: interrupt run"

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

@@ -1,9 +1,9 @@
 /**
  * Render the workflow tool result for chat / LLM-tool surfaces.
  *
- * Rich background-workflow surfaces (status list, per-run detail) delegate
- * to the canonical Catppuccin renderers in `src/tui/`. Compact one-liners
- * (list/run/interrupt/resume) stay inline here.
+ * Workflow surfaces delegate to the canonical rounded renderers in `src/tui/`.
+ * Compact status/error/control responses are wrapped in the same rounded
+ * notice panel vocabulary so tool output stays visually consistent.
  *
  * cross-ref:
  *  - src/tui/status-list.ts  band-header status list
@@ -11,7 +11,7 @@
  *  - pi-subagents src/extension/index.ts renderResult slot
  */
 
-import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
+import type { PendingPrompt, RunSnapshot, StageSnapshot, StageStatus } from "../shared/store-types.js";
 import type { WorkflowDetails } from "../shared/types.js";
 import type { RunDetail } from "../runs/background/status.js";
 import { renderInputsSchema } from "../shared/render-inputs-schema.js";
@@ -20,6 +20,7 @@ import { renderRunDetail } from "../tui/run-detail.js";
 import { renderWorkflowList } from "../tui/workflow-list.js";
 import { deriveGraphTheme } from "../tui/graph-theme.js";
 import { renderDispatchConfirm } from "../tui/dispatch-confirm.js";
+import { renderRoundedBox } from "../tui/chat-surface.js";
 import { truncateToWidth } from "../tui/text-helpers.js";
 
 // ---------------------------------------------------------------------------
@@ -97,6 +98,32 @@ type RunResult = {
    */
   message?: string;
 };
+type StageListItem = {
+  id: string;
+  name: string;
+  status: StageStatus;
+  sessionId?: string;
+  sessionFile?: string;
+  error?: string;
+  awaitingInputSince?: number;
+  pendingPrompt?: PendingPrompt;
+};
+type StageListResult = { action: "stages"; runId: string; filter: string; stages: StageListItem[]; error?: string };
+type StageDetailResult = { action: "stage"; runId: string; stage?: StageSnapshot; error?: string };
+type TranscriptEntry = { role: string; text?: string; toolName?: string; output?: string; timestamp?: number };
+type TranscriptResult = {
+  action: "transcript";
+  runId: string;
+  stageId: string;
+  source: "live" | "snapshot" | "error";
+  entries: TranscriptEntry[];
+  truncated: boolean;
+  sessionId?: string;
+  sessionFile?: string;
+};
+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 };
+type ReloadResult = { action: "reload"; status: "ok" | "noop"; message: string };
 type InterruptResult = { action: "interrupt"; runId: string; status: string; message: string };
 type KillResult = { action: "kill"; runId: string; status: string; message: string };
 type ResumeResult = { action: "resume"; runId: string; status: string; message: string };
@@ -108,6 +135,12 @@ export type WorkflowToolResult =
   | InputsResult
   | GetResult
   | RunResult
+  | StageListResult
+  | StageDetailResult
+  | TranscriptResult
+  | SendResult
+  | PauseResult
+  | ReloadResult
   | InterruptResult
   | KillResult
   | ResumeResult;
@@ -144,6 +177,38 @@ function fitLine(line: string, width?: number): string {
   return truncateToWidth(line, width, "…");
 }
 
+function renderNotice(
+  title: string,
+  message: string,
+  opts: RenderResultOpts | undefined,
+  themed: boolean,
+): string {
+  const theme = themed ? deriveGraphTheme({}) : undefined;
+  const width = opts?.width;
+  const contentWidth = width && width > 0 ? Math.max(1, width - 4) : undefined;
+  return renderRoundedBox({
+    title,
+    bodyLines: [` ${fitLine(message, contentWidth)} `],
+    theme,
+    width,
+  });
+}
+
+const TRANSCRIPT_NOTICE_ENTRY_LIMIT = 5;
+const TRANSCRIPT_NOTICE_CHAR_LIMIT = 240;
+
+function transcriptNoticeText(entries: readonly TranscriptEntry[]): string {
+  if (entries.length === 0) return "no transcript entries";
+  const shown = entries.slice(0, TRANSCRIPT_NOTICE_ENTRY_LIMIT);
+  const text = shown
+    .map((entry) => `${entry.role}: ${entry.text ?? entry.output ?? entry.toolName ?? "(no body)"}`)
+    .join(" | ");
+  const entrySuffix = entries.length > shown.length
+    ? ` … (+${entries.length - shown.length} more)`
+    : "";
+  return fitLine(`${text}${entrySuffix}`, TRANSCRIPT_NOTICE_CHAR_LIMIT);
+}
+
 export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts): string {
   const partial = opts?.isPartial === true;
   const themed = opts?.plain !== true;
@@ -168,7 +233,7 @@ export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts
     case "statusDetail": {
       if ("error" in result) {
         const r = result as Extract<StatusDetailResult, { error: string }>;
-        return fitLine(`workflow status id=${r.runId}: ${r.error}`, opts?.width);
+        return renderNotice("WORKFLOW STATUS", `id=${r.runId}: ${r.error}`, opts, themed);
       }
       const r = result as Extract<StatusDetailResult, { detail: RunDetail }>;
       return renderRunDetail(r.detail, {
@@ -187,34 +252,36 @@ export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts
 
     case "get": {
       const r = result as GetResult;
-      if (r.error) return fitLine(`workflow get (${r.workflow}): ${r.error}`, opts?.width);
+      if (r.error) return renderNotice("WORKFLOW GET", `${r.workflow}: ${r.error}`, opts, themed);
       const output = r.details?.output;
       const description = typeof output?.["description"] === "string" ? ` — ${output["description"]}` : "";
-      return fitLine(
-        `workflow get (${r.workflow}): ${r.details?.status ?? "completed"}${description}`,
-        opts?.width,
+      return renderNotice(
+        "WORKFLOW GET",
+        `${r.workflow}: ${r.details?.status ?? "completed"}${description}`,
+        opts,
+        themed,
       );
     }
 
     case "run": {
       const r = result as RunResult;
-      if (partial) return fitLine(`workflow run ${r.runId}: ${r.status} (in progress…)`, opts?.width);
+      if (partial) return renderNotice("WORKFLOW RUN", `${r.runId}: ${r.status} (in progress…)`, opts, themed);
       if (r.status === "failed" && !r.runId) {
         // Not-found path — render the error verbatim, no fake runId banner.
         const label = r.name ? ` (${r.name})` : "";
-        return fitLine(`workflow run${label}: ${r.error ?? "workflow not found"}`, opts?.width);
+        return renderNotice("WORKFLOW RUN", `${label || "workflow"}: ${r.error ?? "workflow not found"}`, opts, themed);
       }
       if (r.error) {
         const label = r.name ? ` (${r.name})` : "";
-        return fitLine(`workflow run ${r.runId}${label}: ${r.status} — ${r.error}`, opts?.width);
+        return renderNotice("WORKFLOW RUN", `${r.runId}${label}: ${r.status} — ${r.error}`, opts, themed);
       }
       if (r.details) {
         const label = r.name ? ` (${r.name})` : "";
-        return fitLine(`workflow run ${r.runId}${label}: ${r.details.mode} ${r.details.status}`, opts?.width);
+        return renderNotice("WORKFLOW RUN", `${r.runId}${label}: ${r.details.mode} ${r.details.status}`, opts, themed);
       }
       if (r.status === "completed" || r.status === "killed") {
         const label = r.name ? ` (${r.name})` : "";
-        return fitLine(`workflow run ${r.runId}${label}: ${r.status}`, opts?.width);
+        return renderNotice("WORKFLOW RUN", `${r.runId}${label}: ${r.status}`, opts, themed);
       }
       // Background dispatch — reuse the same confirmation card rendered by
       // `/workflow <name> ...` when we have the workflow name and run id.
@@ -228,31 +295,69 @@ export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts
         });
       }
       const label = r.name ? ` (${r.name})` : "";
-      return fitLine(
-        `workflow run ${r.runId}${label}: started in background — ${r.message ?? r.status}`,
-        opts?.width,
+      return renderNotice(
+        "WORKFLOW RUN",
+        `${r.runId}${label}: started in background — ${r.message ?? r.status}`,
+        opts,
+        themed,
       );
     }
 
+    case "stages": {
+      const r = result as StageListResult;
+      if (r.error) return renderNotice("WORKFLOW STAGES", `${r.runId || "(none)"}: ${r.error}`, opts, themed);
+      const counts = r.stages.map((s) => `${s.name} (${s.id.slice(0, 12)}): ${s.status}`).join("; ");
+      return renderNotice("WORKFLOW STAGES", `${r.runId}: ${r.filter} — ${counts || "no stages"}`, opts, themed);
+    }
+
+    case "stage": {
+      const r = result as StageDetailResult;
+      if (r.error || !r.stage) return renderNotice("WORKFLOW STAGE", `${r.runId}: ${r.error ?? "stage not found"}`, opts, themed);
+      const extra = r.stage.error ? ` — ${r.stage.error}` : r.stage.result ? ` — ${r.stage.result}` : "";
+      return renderNotice("WORKFLOW STAGE", `${r.runId}: ${r.stage.name} (${r.stage.id.slice(0, 12)}) ${r.stage.status}${extra}`, opts, themed);
+    }
+
+    case "transcript": {
+      const r = result as TranscriptResult;
+      const text = transcriptNoticeText(r.entries);
+      const suffix = r.truncated ? " (truncated)" : "";
+      return renderNotice("WORKFLOW TRANSCRIPT", `${r.runId}/${r.stageId.slice(0, 12)} ${r.source}: ${text}${suffix}`, opts, themed);
+    }
+
+    case "send": {
+      const r = result as SendResult;
+      return renderNotice("WORKFLOW SEND", `${r.runId}/${r.stageId.slice(0, 12)} ${r.delivery}: ${r.message}`, opts, themed);
+    }
+
+    case "pause": {
+      const r = result as PauseResult;
+      return renderNotice("WORKFLOW PAUSE", `${r.runId}: ${r.message}`, opts, themed);
+    }
+
+    case "reload": {
+      const r = result as ReloadResult;
+      return renderNotice("WORKFLOW RELOAD", r.message, opts, themed);
+    }
+
     case "interrupt": {
       const r = result as InterruptResult;
-      return fitLine(`workflow interrupt ${r.runId}: ${r.message}`, opts?.width);
+      return renderNotice("WORKFLOW INTERRUPT", `${r.runId}: ${r.message}`, opts, themed);
     }
 
     case "kill": {
       const r = result as KillResult;
-      return fitLine(`workflow kill ${r.runId}: ${r.message}`, opts?.width);
+      return renderNotice("WORKFLOW KILL", `${r.runId}: ${r.message}`, opts, themed);
     }
 
     case "resume": {
       const r = result as ResumeResult;
-      return fitLine(`workflow resume ${r.runId}: ${r.message}`, opts?.width);
+      return renderNotice("WORKFLOW RESUME", `${r.runId}: ${r.message}`, opts, themed);
     }
 
     default: {
       // Runtime guard — handles values coerced from external sources.
       const fallback = result as { action: string; message?: string };
-      return fitLine(`workflow: ${fallback.message ?? JSON.stringify(result)}`, opts?.width);
+      return renderNotice("WORKFLOW", fallback.message ?? JSON.stringify(result), opts, themed);
     }
   }
 }

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

@@ -24,8 +24,9 @@ import type {
   WorkflowModelCatalogPort,
 } from "../shared/types.js";
 import type { StageAdapters } from "../runs/foreground/stage-runner.js";
-import { runChain, runParallel, runTask, type RunOpts } from "../runs/foreground/executor.js";
+import { resolveInputs, runChain, runParallel, runTask, type RunOpts } from "../runs/foreground/executor.js";
 import type { Store } from "../shared/store.js";
+import type { RunSnapshot } from "../shared/store-types.js";
 import type { CancellationRegistry } from "../runs/background/cancellation-registry.js";
 import { store as defaultStore } from "../shared/store.js";
 import { dispatch } from "./dispatcher.js";
@@ -39,6 +40,8 @@ import {
   type WorkflowResultIntercomPort,
 } from "../intercom/result-intercom.js";
 import { validateWorkflowModels } from "../runs/shared/model-fallback.js";
+import { runDetached } from "../runs/background/runner.js";
+import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
 
 // ---------------------------------------------------------------------------
 // Options
@@ -81,6 +84,10 @@ export interface ExtensionRuntimeOpts {
 // Public interface
 // ---------------------------------------------------------------------------
 
+export type ResumeFailedRunResult =
+  | { ok: true; runId: string; sourceRunId: string; resumeFromStageId: string; message: string }
+  | { ok: false; reason: "run_not_found" | "not_resumable" | "workflow_not_found" | "insufficient_state"; message: string };
+
 export interface ExtensionRuntime {
   /**
    * Live registry — read-only reference.
@@ -96,6 +103,9 @@ export interface ExtensionRuntime {
 
   /** Execute direct single/parallel/chain workflow tool modes. */
   runDirect(args: WorkflowToolArgs): Promise<WorkflowDetails>;
+
+  /** Start a linked continuation for a failed resumable named workflow run. */
+  resumeFailedRun(sourceRunId: string, stageId?: string): ResumeFailedRunResult;
 }
 
 // ---------------------------------------------------------------------------
@@ -312,6 +322,82 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     throw new Error("WorkflowRuntime.runDirect: no direct execution mode supplied");
   }
 
+  function matchesResumeStageIdentifier(stage: RunSnapshot["stages"][number], identifier: string): boolean {
+    return stage.id === identifier || stage.name === identifier || stage.id.startsWith(identifier);
+  }
+
+  function stageLabel(stage: RunSnapshot["stages"][number]): string {
+    return `${stage.name} (${stage.id.slice(0, 12)})`;
+  }
+
+  function resolveUniqueResumeStage(source: RunSnapshot, identifier: string): { ok: true; stage: RunSnapshot["stages"][number] } | { ok: false; message: string } {
+    const exactId = source.stages.find((stage) => stage.id === identifier);
+    if (exactId !== undefined) return { ok: true, stage: exactId };
+
+    const exactNames = source.stages.filter((stage) => stage.name === identifier);
+    if (exactNames.length === 1) return { ok: true, stage: exactNames[0]! };
+    if (exactNames.length > 1) {
+      return { ok: false, message: `insufficient_state: ambiguous stage identifier "${identifier}" matches: ${exactNames.map(stageLabel).join(", ")}` };
+    }
+
+    const matches = source.stages.filter((stage) => matchesResumeStageIdentifier(stage, identifier));
+    if (matches.length === 0) return { ok: false, message: `insufficient_state: stage not found in source run ${source.id}: ${identifier}` };
+    if (matches.length > 1) {
+      return { ok: false, message: `insufficient_state: ambiguous stage identifier "${identifier}" matches: ${matches.map(stageLabel).join(", ")}` };
+    }
+    return { ok: true, stage: matches[0]! };
+  }
+
+  function resolveResumeStage(source: RunSnapshot, stageId?: string): { ok: true; stageId: string } | { ok: false; message: string } {
+    if (stageId !== undefined) {
+      const resolved = resolveUniqueResumeStage(source, stageId);
+      if (!resolved.ok) return { ok: false, message: resolved.message };
+      const stage = resolved.stage;
+      if (stage.status !== "failed") return { ok: false, message: `insufficient_state: stage ${stage.name} is ${stage.status}, not failed` };
+      return { ok: true, stageId: stage.id };
+    }
+    const failedStageId = source.failedStageId ?? source.stages.find((stage) => stage.status === "failed")?.id;
+    if (failedStageId === undefined) {
+      return { ok: false, message: `insufficient_state: failed run ${source.id} does not identify a failed stage` };
+    }
+    return { ok: true, stageId: failedStageId };
+  }
+
+  function resumeFailedRun(sourceRunId: string, stageId?: string): ResumeFailedRunResult {
+    const source = activeStore.runs().find((run) => run.id === sourceRunId);
+    if (source === undefined) {
+      return { ok: false, reason: "run_not_found", message: `run not found: ${sourceRunId}` };
+    }
+    if (source.status !== "failed" || source.endedAt === undefined || source.resumable === false) {
+      return { ok: false, reason: "not_resumable", message: `run ${sourceRunId} is not a failed resumable workflow run` };
+    }
+    const def = registry.get(source.name);
+    if (def === undefined) {
+      return { ok: false, reason: "workflow_not_found", message: `workflow_not_found: ${source.name}` };
+    }
+    const resolvedStage = resolveResumeStage(source, stageId);
+    if (!resolvedStage.ok) {
+      return { ok: false, reason: "insufficient_state", message: resolvedStage.message };
+    }
+    const sourceInputs = { ...source.inputs };
+    try {
+      resolveInputs(def.inputs, sourceInputs);
+    } catch (err) {
+      return { ok: false, reason: "insufficient_state", message: `insufficient_state: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const accepted = runDetached(def, sourceInputs, {
+      ...runOptions({ workflow: def.name, inputs: sourceInputs }),
+      continuation: { source, resumeFromStageId: resolvedStage.stageId },
+    });
+    return {
+      ok: true,
+      runId: accepted.runId,
+      sourceRunId: source.id,
+      resumeFromStageId: resolvedStage.stageId,
+      message: `Resuming failed workflow "${def.name}" from run ${source.id.slice(0, 8)} at stage ${resolvedStage.stageId.slice(0, 8)} (new run ${accepted.runId}).`,
+    };
+  }
+
   async function runDirectAsync(args: WorkflowToolArgs): Promise<WorkflowDetails> {
     const runId = crypto.randomUUID();
     const mode = directMode(args);
@@ -330,7 +416,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
         runId,
         status: "failed",
         progress: { completed: 0, total: directProgressTotal(args) },
-        error: error instanceof Error ? error.message : String(error),
+        error: classifyWorkflowFailure(error).userMessage,
       }, delivery, parentSession);
     }
     const background = runDirectForeground(args, runId);
@@ -345,7 +431,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
           runId,
           status: "failed",
           progress: { completed: 0, total: directProgressTotal(args) },
-          error: error instanceof Error ? error.message : String(error),
+          error: classifyWorkflowFailure(error).userMessage,
         }, delivery, parentSession);
         emitDirectIntercom(details, delivery, parentSession);
       },
@@ -382,5 +468,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
         return summarized;
       });
     },
+
+    resumeFailedRun,
   };
 }

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

@@ -21,10 +21,12 @@
  *            pi docs/sdk.md createAgentSession
  */
 
+import { basename } from "node:path";
 import type { CreateAgentSessionOptions } from "@bastani/atomic";
 import type { ChatMessageRenderOptions } from "@bastani/atomic";
 import type { StageAdapters, StageSessionRuntime } from "../runs/foreground/stage-runner.js";
 import type { StageExecutionMeta, StageOptions } from "../shared/types.js";
+import { stageUiBroker, type StageUiBroker } from "../shared/stage-ui-broker.js";
 
 // ---------------------------------------------------------------------------
 // Minimal pi surface
@@ -61,6 +63,8 @@ export interface RuntimeWiringSurface {
 export interface RuntimeAdapterBuildOptions {
   /** Test seam for SDK session creation. */
   createAgentSession?: (options?: CreateAgentSessionOptions) => Promise<{ session: StageSessionRuntime }>;
+  /** Broker that routes stage-local custom UI into attached workflow nodes. */
+  stageUiBroker?: StageUiBroker;
 }
 
 type BindableStageSession = StageSessionRuntime & {
@@ -149,7 +153,7 @@ export async function prepareAtomicStageSessionOptions(
     cwd,
     agentDir,
     settingsManager,
-    builtinPackagePaths: sdk.getBuiltinPackagePaths?.() ?? [],
+    builtinPackagePaths: stageBuiltinPackagePaths(sdk.getBuiltinPackagePaths?.() ?? []),
   });
   await resourceLoader.reload();
 
@@ -162,6 +166,15 @@ export async function prepareAtomicStageSessionOptions(
   };
 }
 
+function stageBuiltinPackagePaths(paths: readonly string[]): string[] {
+  // Workflow stages are child AgentSessions owned by the workflow extension.
+  // Loading the workflows extension again inside that child session replays its
+  // `session_start` lifecycle and clears/kills the parent workflow store. Keep
+  // the other builtin packages (subagents, mcp, web-access, intercom), but do
+  // not recursively install workflows into workflow stage sessions.
+  return paths.filter((path) => basename(path) !== "workflows");
+}
+
 async function createPiSdkAgentSession(
   options?: CreateAgentSessionOptions,
 ): Promise<{ session: StageSessionRuntime }> {
@@ -224,7 +237,11 @@ function stripWorkflowOnlyOptions(options: (StageOptions | CreateAgentSessionOpt
   return sessionOptions as CreateAgentSessionOptions;
 }
 
-function makeStageExtensionUiContext(ui: PiUISurface) {
+function makeStageExtensionUiContext(
+  ui: PiUISurface,
+  meta: StageExecutionMeta | undefined,
+  broker: StageUiBroker,
+) {
   return {
     select: ui.select ?? (async () => undefined),
     confirm: ui.confirm ?? (async () => false),
@@ -240,14 +257,22 @@ function makeStageExtensionUiContext(ui: PiUISurface) {
     setFooter: ui.setFooter ?? (() => undefined),
     setHeader: ui.setHeader ?? (() => undefined),
     setTitle: ui.setTitle ?? (() => undefined),
-    custom: ui.custom
-      ? async <T = undefined>(factory: PiCustomOverlayFactory<T>, options?: PiCustomOverlayOptions): Promise<T> => {
-        const result = await ui.custom!(factory as PiCustomOverlayFactory, options ?? { overlay: true });
+    custom: async <T = undefined>(factory: PiCustomOverlayFactory<T>, options?: PiCustomOverlayOptions): Promise<T> => {
+      if (meta !== undefined) {
+        return broker.requestCustomUi(
+          meta.runId,
+          meta.stageId,
+          factory,
+          options,
+          meta.signal,
+        );
+      }
+      if (ui.custom) {
+        const result = await ui.custom(factory as PiCustomOverlayFactory, options ?? { overlay: true });
         return result as T;
       }
-      : async () => {
-        throw new Error("pi-workflows: ask_user_question UI is unavailable");
-      },
+      throw new Error("pi-workflows: ask_user_question UI is unavailable");
+    },
     pasteToEditor: ui.pasteToEditor ?? (() => undefined),
     setEditorText: ui.setEditorText ?? (() => undefined),
     getEditorText: ui.getEditorText ?? (() => ""),
@@ -289,9 +314,10 @@ export function buildRuntimeAdapters(
     options.createAgentSession ??
     pi.createAgentSession ??
     (isTestContext() ? createTestAgentSession : createPiSdkAgentSession);
+  const broker = options.stageUiBroker ?? stageUiBroker;
   const adapters: StageAdapters = {
     agentSession: {
-      async create(stageOptions: CreateAgentSessionOptions & Pick<StageOptions, "mcp" | "fallbackModels">, _meta?: StageExecutionMeta): Promise<StageSessionRuntime> {
+      async create(stageOptions: CreateAgentSessionOptions & Pick<StageOptions, "mcp" | "fallbackModels">, meta?: StageExecutionMeta): Promise<StageSessionRuntime> {
         // Atomic's SDK handles extension / skills / prompt-template /
         // slash-command discovery via the SettingsManager / ResourceLoader.
         // The production default deliberately uses normal DefaultResourceLoader
@@ -302,9 +328,9 @@ export function buildRuntimeAdapters(
         const sessionOptions: CreateAgentSessionOptions = stripWorkflowOnlyOptions(stageOptions) ?? {};
         const result = await createSession(sessionOptions);
         const bindable = result.session as BindableStageSession;
-        if (typeof pi.ui?.custom === "function" && typeof bindable.bindExtensions === "function") {
+        if ((pi.ui !== undefined || meta !== undefined) && typeof bindable.bindExtensions === "function") {
           await bindable.bindExtensions({
-            uiContext: makeStageExtensionUiContext(pi.ui),
+            uiContext: makeStageExtensionUiContext(pi.ui ?? {}, meta, broker),
           });
         }
         return result.session;
@@ -568,7 +594,7 @@ export interface PiUISurface {
   setTheme?: (theme: string | unknown) => { success: boolean; error?: string };
   getToolsExpanded?: () => boolean;
   setToolsExpanded?: (expanded: boolean) => void;
-  getChatRenderSettings?: () => Partial<Omit<ChatMessageRenderOptions, "ui" | "cwd" | "markdownTheme">> | undefined;
+  getChatRenderSettings?: () => Partial<Omit<ChatMessageRenderOptions, "ui" | "cwd">> | undefined;
 }
 
 /**

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

@@ -99,21 +99,78 @@ export const WorkflowParametersSchema = Type.Object({
     Type.Literal("get"),
     Type.Literal("inputs"),
     Type.Literal("status"),
+    Type.Literal("stages"),
+    Type.Literal("stage"),
+    Type.Literal("transcript"),
+    Type.Literal("send"),
+    Type.Literal("pause"),
     Type.Literal("interrupt"),
     Type.Literal("kill"),
     Type.Literal("resume"),
-  ])),
+    Type.Literal("reload"),
+  ], {
+    description: "Workflow action: run/list/get/inputs/status, inspect stages/transcripts, send messages or prompt answers, pause/resume/interrupt/kill runs, or reload workflow resources.",
+  })),
   runId: Type.Optional(Type.String({
-    description: "Run identifier or unique prefix for status/interrupt/kill/resume. Use '--all' for interrupt/kill all.",
+    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.",
   })),
   all: Type.Optional(Type.Boolean({
-    description: "Apply supported run-control actions (interrupt/kill) to all in-flight runs.",
+    description: "Apply supported run-control actions (pause/interrupt/kill) to all in-flight runs instead of one run; cannot be combined with stageId.",
   })),
   stageId: Type.Optional(Type.String({
-    description: "Stage id, unique prefix, or stage name for stage-scoped resume.",
+    description: "Stage id, unique prefix, or stage name for stage-scoped inspection, transcript, send, pause, or resume.",
   })),
   message: Type.Optional(Type.String({
-    description: "Optional message forwarded when resuming paused work.",
+    description: "Message payload for send/follow-up/prompt/steer/resume, or optional text forwarded when resuming paused work.",
+  })),
+  statusFilter: Type.Optional(Type.Union([
+    Type.Literal("pending"),
+    Type.Literal("running"),
+    Type.Literal("awaiting_input"),
+    Type.Literal("paused"),
+    Type.Literal("blocked"),
+    Type.Literal("completed"),
+    Type.Literal("failed"),
+    Type.Literal("skipped"),
+    Type.Literal("all"),
+  ], {
+    description: "Filter stages by status for the stages action; use 'all' to include every stage.",
+  })),
+  format: Type.Optional(Type.Union([Type.Literal("text"), Type.Literal("json")], {
+    description: "Agent-visible output format for data-bearing inspection actions.",
+  })),
+  limit: Type.Optional(Type.Integer({
+    minimum: 0,
+    description: "Transcript-only: maximum number of most recent transcript entries to return; applied before tool output is serialized.",
+  })),
+  tail: Type.Optional(Type.Integer({
+    minimum: 0,
+    description: "Transcript-only: return only the last N transcript entries; overrides limit when both are provided.",
+  })),
+  includeToolOutput: Type.Optional(Type.Boolean({
+    description: "Transcript-only: include captured tool output entries when building results from stage snapshots; 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.",
+  })),
+  response: Type.Optional(Type.Unknown({
+    description: "Structured response payload for answering a pending stage prompt.",
+  })),
+  delivery: Type.Optional(Type.Union([
+    Type.Literal("auto"),
+    Type.Literal("answer"),
+    Type.Literal("prompt"),
+    Type.Literal("steer"),
+    Type.Literal("followUp"),
+    Type.Literal("resume"),
+  ], {
+    description: "Delivery mode for the send action: auto answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.",
+  })),
+  promptId: Type.Optional(Type.String({
+    description: "Pending prompt identifier to answer when using the send action.",
+  })),
+  reason: Type.Optional(Type.String({
+    description: "Human-readable reason for the reload action, echoed in the reload result.",
   })),
   task: Type.Optional(Type.Union([
     DirectTaskSchema,