@bastani/atomic 0.9.11-alpha.8 → 0.9.11-alpha.9

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

@@ -4,33 +4,33 @@ import type { KeybindingsManager, Theme } from "@bastani/atomic";
 import type { Component, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
 import type { TSchema } from "typebox";
 import type {
-  RunStatus,
-  StageAdapters,
-  StageContext,
-  StageOptions,
-  WorkflowAction,
-  WorkflowArtifact,
-  WorkflowChainOptions,
-  WorkflowContextMode,
-  WorkflowDetailsMode,
-  WorkflowChildResult,
-  WorkflowDetailsStatus,
-  WorkflowExecutionMode,
-  WorkflowExitOptions,
-  WorkflowInputSchemaMap,
-  WorkflowInputValues,
-  WorkflowMcpPort,
-  WorkflowModelCatalogPort,
-  WorkflowOutputSchemaMap,
-  WorkflowOutputValues,
-  WorkflowParallelOptions,
-  WorkflowPersistencePort,
-  WorkflowRunChildArgs,
-  WorkflowSerializableObject,
-  WorkflowSerializableValue,
-  WorkflowTaskOptions,
-  WorkflowTaskResult,
-  WorkflowTaskStep,
+	RunStatus,
+	StageAdapters,
+	StageContext,
+	StageOptions,
+	WorkflowAction,
+	WorkflowArtifact,
+	WorkflowChainOptions,
+	WorkflowChildResult,
+	WorkflowContextMode,
+	WorkflowDetailsMode,
+	WorkflowDetailsStatus,
+	WorkflowExecutionMode,
+	WorkflowExitOptions,
+	WorkflowInputSchemaMap,
+	WorkflowInputValues,
+	WorkflowMcpPort,
+	WorkflowModelCatalogPort,
+	WorkflowOutputSchemaMap,
+	WorkflowOutputValues,
+	WorkflowParallelOptions,
+	WorkflowPersistencePort,
+	WorkflowRunChildArgs,
+	WorkflowSerializableObject,
+	WorkflowSerializableValue,
+	WorkflowTaskOptions,
+	WorkflowTaskResult,
+	WorkflowTaskStep,
 } from "./authoring-contract-stage.js";
 
 export type WorkflowCustomUiComponent = Component & { dispose?(): void };
@@ -41,342 +41,368 @@ export type WorkflowCustomUiOverlayOptions = OverlayOptions;
 export type WorkflowCustomUiOverlayHandle = OverlayHandle;
 
 export type WorkflowCustomUiFactory<T> = (
-  tui: TUI,
-  theme: Theme,
-  keybindings: KeybindingsManager,
-  done: (value: T) => void,
+	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;
+	/** 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>;
+	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>;
+	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 WorkflowRunContext<
-  TInputs extends WorkflowInputValues = WorkflowInputValues,
-  TDefinitionBrand extends object = {},
-  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+	TInputs extends WorkflowInputValues = WorkflowInputValues,
+	TDefinitionBrand extends object = Record<never, never>,
+	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
 > {
-  readonly inputs: Readonly<TInputs>;
-  readonly cwd?: string;
-  exit(options?: WorkflowExitOptions<TOutputs>): never;
-  stage<TSchemaDef extends TSchema>(name: string, options: StageOptions<TSchemaDef> & { readonly schema: TSchemaDef }): StageContext<TSchemaDef>;
-  stage(name: string, options?: StageOptions): StageContext;
-  task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
-  chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
-  parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
-  workflow<
-    TChildInputs extends WorkflowInputValues,
-    TChildOutputs extends WorkflowOutputValues,
-    TChildRunInputs extends WorkflowInputValues = TChildInputs,
-  >(
-    definition: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs> & TDefinitionBrand,
-    ...args: WorkflowRunChildArgs<TChildRunInputs>
-  ): Promise<WorkflowChildResult<TChildOutputs>>;
-  readonly ui: WorkflowUIContext;
-  /**
-   * Durable cached tool execution. Runs arbitrary TypeScript code and caches
-   * the result durably so completed side effects are not repeated on resume.
-   * Only `ctx.*` blocks (tool, ui, stage, task, chain, parallel, workflow)
-   * produce durable checkpoints.
-   *
-   * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
-   */
-  tool: WorkflowToolPrimitive;
+	readonly inputs: Readonly<TInputs>;
+	readonly cwd?: string;
+	exit(options?: WorkflowExitOptions<TOutputs>): never;
+	stage<TSchemaDef extends TSchema>(
+		name: string,
+		options: StageOptions<TSchemaDef> & { readonly schema: TSchemaDef },
+	): StageContext<TSchemaDef>;
+	stage(name: string, options?: StageOptions): StageContext;
+	task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
+	chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
+	parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
+	workflow<
+		TChildInputs extends WorkflowInputValues,
+		TChildOutputs extends WorkflowOutputValues,
+		TChildRunInputs extends WorkflowInputValues = TChildInputs,
+	>(
+		definition: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs> & TDefinitionBrand,
+		...args: WorkflowRunChildArgs<TChildRunInputs>
+	): Promise<WorkflowChildResult<TChildOutputs>>;
+	readonly ui: WorkflowUIContext;
+	/**
+	 * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+	 * the result durably so completed side effects are not repeated on resume.
+	 * Only `ctx.*` blocks (tool, ui, stage, task, chain, parallel, workflow)
+	 * produce durable checkpoints.
+	 *
+	 * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+	 */
+	tool: WorkflowToolPrimitive;
 }
 
 /** Serializable process details copied from an exhausted `ctx.tool` callback error. */
 export interface WorkflowToolError extends WorkflowSerializableObject {
-  readonly name: string;
-  readonly message: string;
-  readonly exitCode?: number;
-  readonly stdout?: string;
-  readonly stderr?: string;
+	readonly name: string;
+	readonly message: string;
+	readonly exitCode?: number;
+	readonly stdout?: string;
+	readonly stderr?: string;
 }
 
 export interface WorkflowToolSuccess<TValue extends WorkflowSerializableValue> extends WorkflowSerializableObject {
-  readonly ok: true;
-  readonly value: TValue;
-  readonly attempts: number;
-  readonly cached: boolean;
+	readonly ok: true;
+	readonly value: TValue;
+	readonly attempts: number;
+	readonly cached: boolean;
 }
 
 export interface WorkflowToolFailure extends WorkflowSerializableObject {
-  readonly ok: false;
-  readonly error: WorkflowToolError;
-  readonly attempts: number;
-  readonly cached: boolean;
+	readonly ok: false;
+	readonly error: WorkflowToolError;
+	readonly attempts: number;
+	readonly cached: boolean;
 }
 
 /** Typed result returned when `failureMode: "return"` is selected. */
 export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> =
-  | WorkflowToolSuccess<TValue>
-  | WorkflowToolFailure;
+	| WorkflowToolSuccess<TValue>
+	| WorkflowToolFailure;
 
 /** Options for `ctx.tool`. Throwing after exhausted retries remains the default. */
 export interface WorkflowToolOptions {
-  readonly failureMode?: "throw" | "return";
-  readonly retriesAllowed?: boolean;
-  readonly maxAttempts?: number;
-  readonly intervalMs?: number;
-  readonly backoffRate?: number;
+	readonly failureMode?: "throw" | "return";
+	readonly retriesAllowed?: boolean;
+	readonly maxAttempts?: number;
+	readonly intervalMs?: number;
+	readonly backoffRate?: number;
 }
 
 export type WorkflowToolReturnOptions = WorkflowToolOptions & { readonly failureMode: "return" };
 export type WorkflowToolThrowOptions = WorkflowToolOptions & { readonly failureMode?: "throw" };
 
+/**
+ * Cancellation handle handed to every `ctx.tool` callback.
+ *
+ * The signal aborts when the run is cancelled, when the run is gracefully quit,
+ * or when this single tool node is aborted through `/workflow quit|interrupt`
+ * with the node's id or name. Callbacks that forward it to `fetch`, a child
+ * process, or a network client unblock promptly; callbacks that ignore it are
+ * abandoned after a bounded wait.
+ */
+export interface WorkflowToolContext {
+	readonly signal: AbortSignal;
+}
+
 /** `ctx.tool` runs an async function and durably caches its serializable result. */
 export interface WorkflowToolPrimitive {
-  <TValue extends WorkflowSerializableValue>(
-    name: string,
-    args: Readonly<Record<string, WorkflowSerializableValue>>,
-    fn: () => Promise<TValue>,
-    options: WorkflowToolReturnOptions,
-  ): Promise<WorkflowToolOutcome<TValue>>;
-  <TValue extends WorkflowSerializableValue>(
-    name: string,
-    args: Readonly<Record<string, WorkflowSerializableValue>>,
-    fn: () => Promise<TValue>,
-    options?: WorkflowToolThrowOptions,
-  ): Promise<TValue>;
-  <TValue extends WorkflowSerializableValue>(
-    name: string,
-    args: Readonly<Record<string, WorkflowSerializableValue>>,
-    fn: () => Promise<TValue>,
-    options?: WorkflowToolOptions,
-  ): Promise<TValue | WorkflowToolOutcome<TValue>>;
+	<TValue extends WorkflowSerializableValue>(
+		name: string,
+		args: Readonly<Record<string, WorkflowSerializableValue>>,
+		fn: (toolCtx: WorkflowToolContext) => Promise<TValue>,
+		options: WorkflowToolReturnOptions,
+	): Promise<WorkflowToolOutcome<TValue>>;
+	<TValue extends WorkflowSerializableValue>(
+		name: string,
+		args: Readonly<Record<string, WorkflowSerializableValue>>,
+		fn: (toolCtx: WorkflowToolContext) => Promise<TValue>,
+		options?: WorkflowToolThrowOptions,
+	): Promise<TValue>;
+	<TValue extends WorkflowSerializableValue>(
+		name: string,
+		args: Readonly<Record<string, WorkflowSerializableValue>>,
+		fn: (toolCtx: WorkflowToolContext) => Promise<TValue>,
+		options?: WorkflowToolOptions,
+	): Promise<TValue | WorkflowToolOutcome<TValue>>;
 }
 
 export type WorkflowRunFn<
-  TInputs extends WorkflowInputValues = WorkflowInputValues,
-  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
-  TDefinitionBrand extends object = {},
+	TInputs extends WorkflowInputValues = WorkflowInputValues,
+	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+	TDefinitionBrand extends object = Record<never, never>,
 > = (ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>) => Promise<TOutputs> | TOutputs;
 
 export interface WorkflowRuntimeConfig {
-  readonly maxDepth: number;
-  readonly defaultConcurrency: number;
-  readonly persistRuns: boolean;
-  readonly statusFile: boolean;
-  readonly statusFilePath?: string;
-  readonly resumeInFlight: "ask" | "auto" | "never";
-  readonly worktree?: {
-    readonly symlinkDirectories: readonly string[];
-  };
+	readonly maxDepth: number;
+	readonly defaultConcurrency: number;
+	readonly persistRuns: boolean;
+	readonly statusFile: boolean;
+	readonly statusFilePath?: string;
+	readonly resumeInFlight: "ask" | "auto" | "never";
+	readonly worktree?: {
+		readonly symlinkDirectories: readonly string[];
+	};
 }
 
 export interface WorkflowWorktreeInputBinding {
-  readonly gitWorktreeDir: string;
-  readonly baseBranch?: string;
+	readonly gitWorktreeDir: string;
+	readonly baseBranch?: string;
 }
 
 export interface WorkflowInputBindings {
-  readonly worktree?: WorkflowWorktreeInputBinding;
+	readonly worktree?: WorkflowWorktreeInputBinding;
 }
 
 export interface WorkflowDefinition<
-  TInputs extends WorkflowInputValues = WorkflowInputValues,
-  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
-  TRunInputs extends WorkflowInputValues = TInputs,
-  TDefinitionBrand extends object = {},
+	TInputs extends WorkflowInputValues = WorkflowInputValues,
+	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+	TRunInputs extends WorkflowInputValues = TInputs,
+	TDefinitionBrand extends object = Record<never, never>,
 > {
-  readonly __piWorkflow: true;
-  readonly __runInputs?: TRunInputs;
-  readonly name: string;
-  readonly normalizedName: string;
-  readonly description: string;
-  readonly autoAttach?: true;
-  readonly inputs: WorkflowInputSchemaMap;
-  readonly outputs?: WorkflowOutputSchemaMap;
-  readonly inputBindings?: WorkflowInputBindings;
-  run(ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>): Promise<TOutputs> | TOutputs;
+	readonly __piWorkflow: true;
+	readonly __runInputs?: TRunInputs;
+	readonly name: string;
+	readonly normalizedName: string;
+	readonly description: string;
+	readonly autoAttach?: true;
+	readonly inputs: WorkflowInputSchemaMap;
+	readonly outputs?: WorkflowOutputSchemaMap;
+	readonly inputBindings?: WorkflowInputBindings;
+	run(ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>): Promise<TOutputs> | TOutputs;
 }
 
 export type NoExtraOutputs<TDeclared extends WorkflowOutputValues, TActual extends TDeclared> = TActual &
-  Record<Exclude<keyof TActual, keyof TDeclared>, never>;
+	Record<Exclude<keyof TActual, keyof TDeclared>, never>;
 
 export interface WorkflowOverlayAdapter extends WorkflowSerializableObject {}
 export interface RunSnapshot extends WorkflowSerializableObject {}
 export interface ActiveRunEntry {
-  readonly controller: AbortController;
-  readonly children: readonly AbortController[];
+	readonly controller: AbortController;
+	readonly children: readonly AbortController[];
 }
 
 export interface CancellationRegistry {
-  register(runId: string, controller: AbortController): void;
-  registerChild(runId: string, controller: AbortController): void;
-  abort(runId: string, reason?: unknown): boolean;
-  abortAll(reason?: unknown): number;
-  unregister(runId: string): void;
-  isAborted(runId: string): boolean;
+	register(runId: string, controller: AbortController): void;
+	registerChild(runId: string, controller: AbortController): void;
+	abort(runId: string, reason?: unknown): boolean;
+	abortAll(reason?: unknown): number;
+	unregister(runId: string): void;
+	isAborted(runId: string): boolean;
 }
 
 export interface RunContinuationOpts {
-  readonly source: RunSnapshot;
-  readonly resumeFromStageId: string;
+	readonly source: RunSnapshot;
+	readonly resumeFromStageId: string;
 }
 
 export interface WorkflowParentRunLink {
-  readonly runId: string;
-  readonly stageId: string;
-  readonly rootRunId: string;
+	readonly runId: string;
+	readonly stageId: string;
+	readonly rootRunId: string;
 }
 
 export interface RunOpts {
-  readonly adapters?: StageAdapters;
-  readonly cwd?: string;
-  readonly ui?: WorkflowUIAdapter;
-  readonly executionMode?: WorkflowExecutionMode;
-  readonly usePromptNodesForUi?: boolean;
-  readonly confirmStageReadiness?: (request: {
-    readonly runId: string;
-    readonly stageId: string;
-    readonly stageName: string;
-    readonly signal: AbortSignal;
-  }) => Promise<boolean>;
-  readonly store?: object;
-  readonly persistence?: WorkflowPersistencePort;
-  readonly mcp?: WorkflowMcpPort;
-  readonly cancellation?: CancellationRegistry;
-  readonly overlay?: WorkflowOverlayAdapter;
-  readonly signal?: AbortSignal;
-  readonly deferWorkflowStart?: boolean;
-  readonly config?: WorkflowRuntimeConfig;
-  readonly models?: WorkflowModelCatalogPort;
-  readonly registry?: object;
-  readonly depth?: number;
-  readonly stageControlRegistry?: object;
-  readonly runId?: string;
-  readonly continuation?: RunContinuationOpts;
-  readonly parentRun?: WorkflowParentRunLink;
-  readonly onRunStart?: (snapshot: RunSnapshot) => void;
-  readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
-  readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
-  readonly onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
+	readonly adapters?: StageAdapters;
+	readonly cwd?: string;
+	readonly ui?: WorkflowUIAdapter;
+	readonly executionMode?: WorkflowExecutionMode;
+	readonly usePromptNodesForUi?: boolean;
+	readonly confirmStageReadiness?: (request: {
+		readonly runId: string;
+		readonly stageId: string;
+		readonly stageName: string;
+		readonly signal: AbortSignal;
+	}) => Promise<boolean>;
+	readonly store?: object;
+	readonly persistence?: WorkflowPersistencePort;
+	readonly mcp?: WorkflowMcpPort;
+	readonly cancellation?: CancellationRegistry;
+	readonly overlay?: WorkflowOverlayAdapter;
+	readonly signal?: AbortSignal;
+	readonly deferWorkflowStart?: boolean;
+	readonly config?: WorkflowRuntimeConfig;
+	readonly models?: WorkflowModelCatalogPort;
+	readonly registry?: object;
+	readonly depth?: number;
+	readonly stageControlRegistry?: object;
+	readonly toolControlRegistry?: object;
+	readonly toolAdmissionBoundary?: object;
+	readonly runId?: string;
+	readonly continuation?: RunContinuationOpts;
+	readonly parentRun?: WorkflowParentRunLink;
+	readonly onRunStart?: (snapshot: RunSnapshot) => void;
+	readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
+	readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
+	readonly onRunEnd?: (
+		runId: string,
+		status: RunStatus,
+		result?: WorkflowOutputValues,
+		error?: string,
+		exitReason?: string,
+	) => void;
 }
 
 export interface WorkflowProgressSummary extends WorkflowSerializableObject {
-  readonly completed?: number;
-  readonly total?: number;
+	readonly completed?: number;
+	readonly total?: number;
 }
 
 export interface WorkflowControlEvent extends WorkflowSerializableObject {
-  readonly type?: "notify" | "needs_attention" | "interrupted" | "resumed";
-  readonly message?: string;
+	readonly type?: "notify" | "needs_attention" | "interrupted" | "resumed";
+	readonly message?: string;
 }
 
 export interface WorkflowIntercomSummary extends WorkflowSerializableObject {
-  readonly enabled?: boolean;
-  readonly delivery?: "off" | "notify" | "result" | "control-and-result";
-  readonly parentSession?: string;
+	readonly enabled?: boolean;
+	readonly delivery?: "off" | "notify" | "result" | "control-and-result";
+	readonly parentSession?: string;
 }
 
 export interface WorkflowDetails extends WorkflowSerializableObject {
-  readonly mode: WorkflowDetailsMode;
-  readonly action?: WorkflowAction;
-  readonly runId?: string;
-  readonly status: WorkflowDetailsStatus;
-  readonly context?: WorkflowContextMode;
-  readonly results?: readonly WorkflowTaskResult[];
-  readonly output?: WorkflowOutputValues;
-  readonly progress?: WorkflowProgressSummary;
-  readonly artifacts?: readonly WorkflowArtifact[];
-  readonly controlEvents?: readonly WorkflowControlEvent[];
-  readonly intercom?: WorkflowIntercomSummary;
-  readonly warnings?: readonly string[];
-  /** Actionable user guidance for accepted background execution. */
-  readonly message?: string;
-  readonly error?: string;
-  /** True when the run reached its terminal status through ctx.exit(). */
-  readonly exited?: boolean;
-  readonly exitReason?: string;
+	readonly mode: WorkflowDetailsMode;
+	readonly action?: WorkflowAction;
+	readonly runId?: string;
+	readonly status: WorkflowDetailsStatus;
+	readonly context?: WorkflowContextMode;
+	readonly results?: readonly WorkflowTaskResult[];
+	readonly output?: WorkflowOutputValues;
+	readonly progress?: WorkflowProgressSummary;
+	readonly artifacts?: readonly WorkflowArtifact[];
+	readonly controlEvents?: readonly WorkflowControlEvent[];
+	readonly intercom?: WorkflowIntercomSummary;
+	readonly warnings?: readonly string[];
+	/** Actionable user guidance for accepted background execution. */
+	readonly message?: string;
+	readonly error?: string;
+	/** True when the run reached its terminal status through ctx.exit(). */
+	readonly exited?: boolean;
+	readonly exitReason?: string;
 }
 
 export type StageStatus = RunStatus | "skipped" | "awaiting_input" | "blocked";
 
 export interface StageSnapshot extends WorkflowSerializableObject {
-  readonly id: string;
-  readonly name: string;
-  readonly status: StageStatus;
-  readonly result?: WorkflowSerializableValue;
-  readonly error?: string;
+	readonly id: string;
+	readonly name: string;
+	readonly status: StageStatus;
+	readonly result?: WorkflowSerializableValue;
+	readonly error?: string;
 }
 
 export interface ToolNodeSnapshot extends WorkflowSerializableObject {
-  readonly kind: "tool";
-  /** Stable durable node identity. */
-  readonly id: string;
-  readonly name: string;
-  readonly argsHash: string;
-  readonly ordinal: number;
-  readonly parentIds: readonly string[];
-  readonly status: "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
-  readonly topologyState?: "unavailable";
-  readonly replayed?: boolean;
-  readonly executionOrder?: number;
-  readonly startedAt?: number;
-  readonly endedAt?: number;
-  readonly resultSummary?: string;
-  readonly error?: string;
-  readonly attachable: false;
+	readonly kind: "tool";
+	/** Stable durable node identity. */
+	readonly id: string;
+	readonly name: string;
+	readonly argsHash: string;
+	readonly ordinal: number;
+	readonly parentIds: readonly string[];
+	readonly status: "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
+	readonly topologyState?: "unavailable";
+	readonly replayed?: boolean;
+	readonly executionOrder?: number;
+	readonly startedAt?: number;
+	readonly endedAt?: number;
+	readonly resultSummary?: string;
+	readonly error?: string;
+	readonly attachable: false;
 }
 
-export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
-  readonly runId: string;
-  readonly status: RunStatus;
-  readonly result?: Partial<TOutputs>;
-  readonly error?: string;
-  /** Tool node whose rejection supplied the selected terminal failure. */
-  readonly failedToolNodeId?: string;
-  /** True when the run reached its terminal status through ctx.exit(). */
-  readonly exited?: boolean;
-  readonly exitReason?: string;
-  readonly stages: readonly StageSnapshot[];
-  /** Always populated by the runtime; optional for legacy structural literals. */
-  readonly toolNodes?: readonly ToolNodeSnapshot[];
+export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues>
+	extends WorkflowSerializableObject {
+	readonly runId: string;
+	readonly status: RunStatus;
+	readonly result?: Partial<TOutputs>;
+	readonly error?: string;
+	/** Tool node whose rejection supplied the selected terminal failure. */
+	readonly failedToolNodeId?: string;
+	/** True when the run reached its terminal status through ctx.exit(). */
+	readonly exited?: boolean;
+	readonly exitReason?: string;
+	readonly stages: readonly StageSnapshot[];
+	/** Always populated by the runtime; optional for legacy structural literals. */
+	readonly toolNodes?: readonly ToolNodeSnapshot[];
 }
 
-export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> & WorkflowSerializableObject;
+export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> &
+	WorkflowSerializableObject;
 
 export interface GitWorktreeSetupOptions extends WorkflowSerializableObject {
-  readonly gitWorktreeDir: string;
-  readonly baseBranch?: string;
-  readonly cwd: string;
+	readonly gitWorktreeDir: string;
+	readonly baseBranch?: string;
+	readonly cwd: string;
 }
 
 export interface GitWorktreeSetupResult extends WorkflowSerializableObject {
-  readonly worktreeRoot: string;
-  readonly cwd: string;
-  readonly repositoryRoot: string;
-  readonly created: boolean;
+	readonly worktreeRoot: string;
+	readonly cwd: string;
+	readonly repositoryRoot: string;
+	readonly created: boolean;
 }