@bastani/atomic 0.9.11-alpha.8 → 0.9.11

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

@@ -4,30 +4,29 @@
  */
 
 import type {
-  AgentSession,
-  AgentSessionEvent,
-  VerbatimCompactionResult,
-  CreateAgentSessionOptions,
-  ModelCycleResult,
-  PromptOptions,
-  SessionManager,
-  SettingsManager,
-  ToolDefinition,
+	AgentSession,
+	AgentSessionEvent,
+	CreateAgentSessionOptions,
+	ModelCycleResult,
+	PromptOptions,
+	SessionManager,
+	SettingsManager,
+	ToolDefinition,
+	VerbatimCompactionResult,
 } from "@bastani/atomic";
 import type { TSchema } from "typebox";
 import type * as AuthoringContract from "./authoring-contract.js";
+import type { ToolNodeSnapshot } from "./store-types.js";
 
-export type { TSchema };
-
-export type { AgentSessionEvent, VerbatimCompactionResult, ModelCycleResult, PromptOptions };
+export type { AgentSessionEvent, ModelCycleResult, PromptOptions, TSchema, VerbatimCompactionResult };
 
 export type StageUserMessageContent = Parameters<AgentSession["sendUserMessage"]>[0];
 
 export type StageUserMessageDelivery = "steer" | "followUp";
 
 export interface StageSendUserMessageOptions {
-  /** Delivery mode to use when the stage session is already streaming. Defaults to followUp. */
-  readonly deliverAs?: StageUserMessageDelivery;
+	/** Delivery mode to use when the stage session is already streaming. Defaults to followUp. */
+	readonly deliverAs?: StageUserMessageDelivery;
 }
 
 export type WorkflowModelValue = NonNullable<CreateAgentSessionOptions["model"]> | string;
@@ -37,13 +36,14 @@ export type WorkflowModelFallbackFields = AuthoringContract.WorkflowModelFallbac
 export type WorkflowThinkingLevel = AuthoringContract.WorkflowThinkingLevel;
 
 export interface WorkflowModelInfo extends Omit<AuthoringContract.WorkflowModelInfo, "model"> {
-  readonly model?: NonNullable<CreateAgentSessionOptions["model"]>;
+	readonly model?: NonNullable<CreateAgentSessionOptions["model"]>;
 }
 
-export interface WorkflowModelCatalogPort extends Omit<AuthoringContract.WorkflowModelCatalogPort, "listModels" | "currentModel"> {
-  listModels(): Promise<readonly WorkflowModelInfo[]>;
-  /** Current user-selected model used as the implicit final fallback. */
-  readonly currentModel?: WorkflowModelValue;
+export interface WorkflowModelCatalogPort
+	extends Omit<AuthoringContract.WorkflowModelCatalogPort, "listModels" | "currentModel"> {
+	listModels(): Promise<readonly WorkflowModelInfo[]>;
+	/** Current user-selected model used as the implicit final fallback. */
+	readonly currentModel?: WorkflowModelValue;
 }
 
 // ---------------------------------------------------------------------------
@@ -57,7 +57,8 @@ export type WorkflowInputValues = AuthoringContract.WorkflowInputValues;
 export type WorkflowOutputValues = AuthoringContract.WorkflowOutputValues;
 export type WorkflowRunOutput = AuthoringContract.WorkflowRunOutput;
 export type WorkflowExitStatus = AuthoringContract.WorkflowExitStatus;
-export type WorkflowExitOptions<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowExitOptions<TOutputs>;
+export type WorkflowExitOptions<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> =
+	AuthoringContract.WorkflowExitOptions<TOutputs>;
 
 // ---------------------------------------------------------------------------
 // Workflow input / output schemas
@@ -85,17 +86,17 @@ export type WorkflowExecutionMode = AuthoringContract.WorkflowExecutionMode;
 export type WorkflowExecutionPolicy = AuthoringContract.WorkflowExecutionPolicy;
 
 export const INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy = Object.freeze({
-  mode: "interactive",
-  allowHumanInput: true,
-  awaitTerminalRun: false,
-  allowInputPicker: true,
+	mode: "interactive",
+	allowHumanInput: true,
+	awaitTerminalRun: false,
+	allowInputPicker: true,
 });
 
 export const NON_INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy = Object.freeze({
-  mode: "non_interactive",
-  allowHumanInput: false,
-  awaitTerminalRun: true,
-  allowInputPicker: false,
+	mode: "non_interactive",
+	allowHumanInput: false,
+	awaitTerminalRun: true,
+	allowInputPicker: false,
 });
 
 // ---------------------------------------------------------------------------
@@ -103,27 +104,34 @@ export const NON_INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy = Object.f
 // ---------------------------------------------------------------------------
 
 export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = WorkflowInputValues> {
-  /** Inputs forwarded to the child workflow, typed against its input contract. */
-  readonly inputs?: TInputs;
-  /** Parent boundary stage display name. Defaults to workflow:<workflow-name>. */
-  readonly stageName?: string;
+	/** Inputs forwarded to the child workflow, typed against its input contract. */
+	readonly inputs?: TInputs;
+	/** Parent boundary stage display name. Defaults to workflow:<workflow-name>. */
+	readonly stageName?: string;
 }
 
 type WorkflowRequiredKeys<T extends object> = {
-  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+	[K in keyof T]-?: Record<never, never> extends Pick<T, K> ? never : K;
 }[keyof T];
 
-export type WorkflowRunChildOptionsArgument<TInputs extends WorkflowInputValues = WorkflowInputValues> = [WorkflowRequiredKeys<TInputs>] extends [never]
-  ? WorkflowRunChildOptions<TInputs>
-  : WorkflowRunChildOptions<TInputs> & { readonly inputs: TInputs };
-
-export type WorkflowRunChildArgs<TInputs extends WorkflowInputValues = WorkflowInputValues> = [WorkflowRequiredKeys<TInputs>] extends [never]
-  ? readonly [options?: WorkflowRunChildOptionsArgument<NoInfer<TInputs>>]
-  : readonly [options: WorkflowRunChildOptionsArgument<NoInfer<TInputs>>];
-
-export type WorkflowCompletedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowCompletedChildResult<TOutputs>;
-export type WorkflowExitedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowExitedChildResult<TOutputs>;
-export type WorkflowChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowChildResult<TOutputs>;
+export type WorkflowRunChildOptionsArgument<TInputs extends WorkflowInputValues = WorkflowInputValues> = [
+	WorkflowRequiredKeys<TInputs>,
+] extends [never]
+	? WorkflowRunChildOptions<TInputs>
+	: WorkflowRunChildOptions<TInputs> & { readonly inputs: TInputs };
+
+export type WorkflowRunChildArgs<TInputs extends WorkflowInputValues = WorkflowInputValues> = [
+	WorkflowRequiredKeys<TInputs>,
+] extends [never]
+	? readonly [options?: WorkflowRunChildOptionsArgument<NoInfer<TInputs>>]
+	: readonly [options: WorkflowRunChildOptionsArgument<NoInfer<TInputs>>];
+
+export type WorkflowCompletedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> =
+	AuthoringContract.WorkflowCompletedChildResult<TOutputs>;
+export type WorkflowExitedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> =
+	AuthoringContract.WorkflowExitedChildResult<TOutputs>;
+export type WorkflowChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> =
+	AuthoringContract.WorkflowChildResult<TOutputs>;
 
 // ---------------------------------------------------------------------------
 // HIL (human-in-the-loop) primitives available inside run functions
@@ -165,8 +173,8 @@ export interface WorkflowUIAdapter extends AuthoringContract.WorkflowUIAdapter {
 type Mutable<T> = { -readonly [K in keyof T]: T[K] };
 
 export interface StageMcpOptions extends AuthoringContract.StageMcpOptions {
-  allow?: string[];
-  deny?: string[];
+	allow?: string[];
+	deny?: string[];
 }
 
 /**
@@ -175,28 +183,28 @@ export interface StageMcpOptions extends AuthoringContract.StageMcpOptions {
  * workflow-owned options such as `mcp` and `gitWorktreeDir` are stripped before SDK session creation.
  */
 export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined>
-  extends Omit<CreateAgentSessionOptions, "model" | keyof AuthoringContract.StageOptions>,
-    Omit<Mutable<AuthoringContract.StageOptions<TSchemaDef>>, "sessionManager" | "settingsManager"> {
-  /** Optional structured final-answer schema. When set, the stage receives a schema-specific final-answer tool. */
-  schema?: TSchemaDef;
-  /** Model id or pi SDK model object used as the primary stage model. */
-  model?: WorkflowModelValue;
-  /** Per-stage MCP server gating. No-op when no WorkflowMcpPort is configured. */
-  mcp?: StageMcpOptions;
-  customTools?: ToolDefinition[];
-  scopedModels?: CreateAgentSessionOptions["scopedModels"];
-  sessionManager?: SessionManager;
-  settingsManager?: SettingsManager;
-  /** Internal durable resume hook: reopen this exact Atomic/Pi session file instead of forking. */
-  resumeFromSessionFile?: string;
-  /** Internal durable replay key used to map a live LM session to durable resume state. */
-  durableReplayKey?: string;
-  /** Internal durable timing baseline accumulated before a process-boundary resume. */
-  durableAccumulatedDurationMs?: number;
-  /** Internal durable source identity reused when an active stage session is reopened. */
-  durableStageId?: string;
-  /** Internal durable source parents reused with `durableStageId`. */
-  durableParentIds?: readonly string[];
+	extends Omit<CreateAgentSessionOptions, "model" | keyof AuthoringContract.StageOptions>,
+		Omit<Mutable<AuthoringContract.StageOptions<TSchemaDef>>, "sessionManager" | "settingsManager"> {
+	/** Optional structured final-answer schema. When set, the stage receives a schema-specific final-answer tool. */
+	schema?: TSchemaDef;
+	/** Model id or pi SDK model object used as the primary stage model. */
+	model?: WorkflowModelValue;
+	/** Per-stage MCP server gating. No-op when no WorkflowMcpPort is configured. */
+	mcp?: StageMcpOptions;
+	customTools?: ToolDefinition[];
+	scopedModels?: CreateAgentSessionOptions["scopedModels"];
+	sessionManager?: SessionManager;
+	settingsManager?: SettingsManager;
+	/** Internal durable resume hook: reopen this exact Atomic/Pi session file instead of forking. */
+	resumeFromSessionFile?: string;
+	/** Internal durable replay key used to map a live LM session to durable resume state. */
+	durableReplayKey?: string;
+	/** Internal durable timing baseline accumulated before a process-boundary resume. */
+	durableAccumulatedDurationMs?: number;
+	/** Internal durable source identity reused when an active stage session is reopened. */
+	durableStageId?: string;
+	/** Internal durable source parents reused with `durableStageId`. */
+	durableParentIds?: readonly string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -208,27 +216,27 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
  * Not exposed to workflow authors — StageContext public API is unchanged.
  */
 export interface StageExecutionMeta {
-  /** Run ID of the containing workflow execution. */
-  runId: string;
-  /** Runtime-owned home group shared by this top-level workflow invocation. */
-  workflowIntercomGroup?: string;
-  /** Stage ID of the current stage. */
-  stageId: string;
-  /** Human-readable stage name. */
-  stageName: string;
-  /** Stage options after workflow-owned direct-mode rewriting. */
-  stageOptions?: StageOptions;
-  /** AbortSignal propagated from the executor's own AbortController. */
-  signal?: AbortSignal;
-  /** Runtime execution mode for policy-aware child sessions. */
-  executionMode?: WorkflowExecutionMode;
-  /** Internal stage-generation context reused across model-fallback sessions. */
-  orchestrationContext?: CreateAgentSessionOptions["orchestrationContext"];
+	/** Run ID of the containing workflow execution. */
+	runId: string;
+	/** Runtime-owned home group shared by this top-level workflow invocation. */
+	workflowIntercomGroup?: string;
+	/** Stage ID of the current stage. */
+	stageId: string;
+	/** Human-readable stage name. */
+	stageName: string;
+	/** Stage options after workflow-owned direct-mode rewriting. */
+	stageOptions?: StageOptions;
+	/** AbortSignal propagated from the executor's own AbortController. */
+	signal?: AbortSignal;
+	/** Runtime execution mode for policy-aware child sessions. */
+	executionMode?: WorkflowExecutionMode;
+	/** Internal stage-generation context reused across model-fallback sessions. */
+	orchestrationContext?: CreateAgentSessionOptions["orchestrationContext"];
 }
 
 export interface CompleteStageOpts extends WorkflowModelFallbackFields {
-  model?: WorkflowModelValue;
-  maxTokens?: number;
+	model?: WorkflowModelValue;
+	maxTokens?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -240,10 +248,10 @@ export interface CompleteStageOpts extends WorkflowModelFallbackFields {
  * Implemented by the pi runtime or a test stub; no hard dep on integrations/mcp.
  */
 export interface WorkflowMcpPort {
-  /** Restrict MCP server access for the given stage. Null = unrestricted. */
-  setScope(stageId: string, allow: string[] | null, deny: string[] | null): void;
-  /** Restore unrestricted MCP access after the stage settles. */
-  clearScope(stageId: string): void;
+	/** Restrict MCP server access for the given stage. Null = unrestricted. */
+	setScope(stageId: string, allow: string[] | null, deny: string[] | null): void;
+	/** Restore unrestricted MCP access after the stage settles. */
+	clearScope(stageId: string): void;
 }
 
 /**
@@ -251,9 +259,9 @@ export interface WorkflowMcpPort {
  * Mirrors PersistenceAPI from shared/persistence-session-entries — no hard import.
  */
 export interface WorkflowPersistencePort {
-  appendEntry(type: string, payload: Record<string, unknown>): string | undefined;
-  setLabel?(entryId: string, label: string): void;
-  appendCustomMessageEntry?(content: string, meta?: Record<string, unknown>): string | undefined;
+	appendEntry(type: string, payload: Record<string, unknown>): string | undefined;
+	setLabel?(entryId: string, label: string): void;
+	appendCustomMessageEntry?(content: string, meta?: Record<string, unknown>): string | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -268,7 +276,8 @@ export interface WorkflowPersistencePort {
 export type WorkflowTaskContext = AuthoringContract.WorkflowTaskContext;
 export type WorkflowTaskContextInput = AuthoringContract.WorkflowTaskContextInput;
 export type WorkflowTaskResult = AuthoringContract.WorkflowTaskResult;
-export type WorkflowStageResult<TSchemaDef extends TSchema | undefined = undefined> = AuthoringContract.WorkflowStageResult<TSchemaDef>;
+export type WorkflowStageResult<TSchemaDef extends TSchema | undefined = undefined> =
+	AuthoringContract.WorkflowStageResult<TSchemaDef>;
 
 /**
  * Higher-level task API: create a tracked stage, optionally inject prior task
@@ -276,11 +285,21 @@ export type WorkflowStageResult<TSchemaDef extends TSchema | undefined = undefin
  *
  * `{previous}` means prior step output.
  */
-export interface WorkflowTaskOptions extends StageOptions, Omit<Mutable<AuthoringContract.WorkflowTaskOptions>, keyof AuthoringContract.StageOptions> {}
-export interface WorkflowTaskStep extends WorkflowTaskOptions, Omit<Mutable<AuthoringContract.WorkflowTaskStep>, keyof AuthoringContract.WorkflowTaskOptions> {}
-export interface WorkflowSharedTaskDefaults extends StageOptions, Omit<Mutable<AuthoringContract.WorkflowSharedTaskDefaults>, keyof AuthoringContract.StageOptions> {}
-export interface WorkflowChainOptions extends WorkflowSharedTaskDefaults, Omit<Mutable<AuthoringContract.WorkflowChainOptions>, keyof AuthoringContract.WorkflowSharedTaskDefaults> {}
-export interface WorkflowParallelOptions extends WorkflowSharedTaskDefaults, Omit<Mutable<AuthoringContract.WorkflowParallelOptions>, keyof AuthoringContract.WorkflowSharedTaskDefaults> {}
+export interface WorkflowTaskOptions
+	extends StageOptions,
+		Omit<Mutable<AuthoringContract.WorkflowTaskOptions>, keyof AuthoringContract.StageOptions> {}
+export interface WorkflowTaskStep
+	extends WorkflowTaskOptions,
+		Omit<Mutable<AuthoringContract.WorkflowTaskStep>, keyof AuthoringContract.WorkflowTaskOptions> {}
+export interface WorkflowSharedTaskDefaults
+	extends StageOptions,
+		Omit<Mutable<AuthoringContract.WorkflowSharedTaskDefaults>, keyof AuthoringContract.StageOptions> {}
+export interface WorkflowChainOptions
+	extends WorkflowSharedTaskDefaults,
+		Omit<Mutable<AuthoringContract.WorkflowChainOptions>, keyof AuthoringContract.WorkflowSharedTaskDefaults> {}
+export interface WorkflowParallelOptions
+	extends WorkflowSharedTaskDefaults,
+		Omit<Mutable<AuthoringContract.WorkflowParallelOptions>, keyof AuthoringContract.WorkflowSharedTaskDefaults> {}
 
 export type WorkflowOutputMode = AuthoringContract.WorkflowOutputMode;
 export type WorkflowMaxOutput = AuthoringContract.WorkflowMaxOutput;
@@ -309,58 +328,58 @@ export type WorkflowTaskSessionOptions = StageOptions & WorkflowTaskSessionField
  * executor owns disposal and wraps prompt() with stage lifecycle tracking.
  */
 export interface StageContext<TSchemaDef extends TSchema | undefined = undefined> {
-  /** Human-readable name for this stage (used in TUI + persistence). */
-  readonly name: string;
-
-  /** Send a prompt and wait for completion. */
-  prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
-  complete(text: string, options?: CompleteStageOpts): Promise<string>;
-
-  /**
-   * Send a user-authored follow-on message to this stage session.
-   *
-   * When the session is idle this starts a new user turn immediately. When the
-   * session is streaming, the message is queued as a follow-up by default, or
-   * as steering when `deliverAs: "steer"` is provided.
-   */
-  sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
-
-  /** Queue messages during streaming. */
-  steer(text: string): Promise<void>;
-  followUp(text: string): Promise<void>;
-
-  /** Subscribe to events (returns unsubscribe function). */
-  subscribe(listener: (event: AgentSessionEvent) => void): () => void;
-
-  /** Session info. */
-  readonly sessionFile: string | undefined;
-  readonly sessionId: string;
-
-  /** Model control. */
-  setModel(model: Parameters<AgentSession["setModel"]>[0]): Promise<void>;
-  setThinkingLevel(level: Parameters<AgentSession["setThinkingLevel"]>[0]): void;
-  cycleModel(): Promise<ModelCycleResult | undefined>;
-  cycleThinkingLevel(): ReturnType<AgentSession["cycleThinkingLevel"]>;
-
-  /** State access. */
-  readonly agent: AgentSession["agent"];
-  readonly model: AgentSession["model"];
-  readonly thinkingLevel: AgentSession["thinkingLevel"];
-  readonly messages: AgentSession["messages"];
-  readonly isStreaming: AgentSession["isStreaming"];
-
-  /** In-place tree navigation within the current session file. */
-  navigateTree(
-    targetId: string,
-    options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
-  ): Promise<{ editorText?: string; cancelled: boolean }>;
-
-  /** Compaction. */
-  compact(): Promise<VerbatimCompactionResult>;
-  abortCompaction(): void;
-
-  /** Abort current operation. */
-  abort(): Promise<void>;
+	/** Human-readable name for this stage (used in TUI + persistence). */
+	readonly name: string;
+
+	/** Send a prompt and wait for completion. */
+	prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
+	complete(text: string, options?: CompleteStageOpts): Promise<string>;
+
+	/**
+	 * Send a user-authored follow-on message to this stage session.
+	 *
+	 * When the session is idle this starts a new user turn immediately. When the
+	 * session is streaming, the message is queued as a follow-up by default, or
+	 * as steering when `deliverAs: "steer"` is provided.
+	 */
+	sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
+
+	/** Queue messages during streaming. */
+	steer(text: string): Promise<void>;
+	followUp(text: string): Promise<void>;
+
+	/** Subscribe to events (returns unsubscribe function). */
+	subscribe(listener: (event: AgentSessionEvent) => void): () => void;
+
+	/** Session info. */
+	readonly sessionFile: string | undefined;
+	readonly sessionId: string;
+
+	/** Model control. */
+	setModel(model: Parameters<AgentSession["setModel"]>[0]): Promise<void>;
+	setThinkingLevel(level: Parameters<AgentSession["setThinkingLevel"]>[0]): void;
+	cycleModel(): Promise<ModelCycleResult | undefined>;
+	cycleThinkingLevel(): ReturnType<AgentSession["cycleThinkingLevel"]>;
+
+	/** State access. */
+	readonly agent: AgentSession["agent"];
+	readonly model: AgentSession["model"];
+	readonly thinkingLevel: AgentSession["thinkingLevel"];
+	readonly messages: AgentSession["messages"];
+	readonly isStreaming: AgentSession["isStreaming"];
+
+	/** In-place tree navigation within the current session file. */
+	navigateTree(
+		targetId: string,
+		options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
+	): Promise<{ editorText?: string; cancelled: boolean }>;
+
+	/** Compaction. */
+	compact(): Promise<VerbatimCompactionResult>;
+	abortCompaction(): void;
+
+	/** Abort current operation. */
+	abort(): Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -368,71 +387,96 @@ export interface StageContext<TSchemaDef extends TSchema | undefined = undefined
 // ---------------------------------------------------------------------------
 
 export interface WorkflowRunContext<
-  TInputs extends WorkflowInputValues = WorkflowInputValues,
-  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+	TInputs extends WorkflowInputValues = WorkflowInputValues,
+	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
 > {
-  /** Typed inputs provided by the caller, validated against the input schema. */
-  readonly inputs: TInputs;
-  /** Invocation working directory for workflow-owned artifacts. Defaults to the host process cwd when omitted. */
-  readonly cwd?: string;
-  /** Intentionally end this workflow run from any call depth. */
-  exit(options?: WorkflowExitOptions<TOutputs>): never;
-  /**
-   * Create and register a named stage synchronously. Stage work starts when
-   * a stage method such as prompt() or complete() is awaited; the executor
-   * infers the DAG automatically from those method calls.
-   *
-   * @param name   Human-readable stage name (used in TUI + persistence).
-   * @param options Optional per-stage configuration (mcp allow/deny, etc.).
-   */
-  stage<TSchemaDef extends TSchema>(name: string, options: StageOptions<TSchemaDef> & { schema: TSchemaDef }): StageContext<TSchemaDef>;
-  stage(name: string, options?: StageOptions): StageContext;
-  /**
-   * Safe high-level task primitive. Equivalent to creating a named stage and
-   * calling prompt(), with built-in context handoff support.
-   */
-  task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
-  /** Run tasks in sequence. Missing step tasks: first gets `{task}`, later steps get `{previous}`. */
-  chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
-  /** Run tasks in parallel. Missing step tasks use the first available task as a fallback. */
-  parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
-  /** Execute a reusable child workflow by compiled workflow definition. */
-  workflow<
-    TChildInputs extends WorkflowInputValues,
-    TChildOutputs extends WorkflowOutputValues,
-    TChildRunInputs extends WorkflowInputValues = TChildInputs,
-  >(
-    definition: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
-    ...args: WorkflowRunChildArgs<TChildRunInputs>
-  ): Promise<WorkflowChildResult<TChildOutputs>>;
-  /** HIL primitives for user interaction during a run. */
-  readonly ui: WorkflowUIContext;
-  /**
-   * Durable cached tool execution. Runs arbitrary TypeScript code and caches
-   * the result so completed side effects are not repeated on resume.
-   * Only `ctx.*` blocks produce durable checkpoints.
-   *
-   * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
-   */
-  tool: WorkflowToolPrimitive;
-  /**
-   * Model catalog port for the invoking session, when the host provides one.
-   * `models.currentModel` is the user-selected session model; leading a stage's
-   * model chain with it (bare, without a reasoning suffix) runs the stage at
-   * the session's model and default thinking level.
-   */
-  readonly models?: WorkflowModelCatalogPort;
+	/** Typed inputs provided by the caller, validated against the input schema. */
+	readonly inputs: TInputs;
+	/** Stable owning workflow-run id for durable run-scoped artifacts. */
+	readonly runId?: string;
+	/** Invocation working directory for workflow-owned artifacts. Defaults to the host process cwd when omitted. */
+	readonly cwd?: string;
+	/** Intentionally end this workflow run from any call depth. */
+	exit(options?: WorkflowExitOptions<TOutputs>): never;
+	/**
+	 * Create and register a named stage synchronously. Stage work starts when
+	 * a stage method such as prompt() or complete() is awaited; the executor
+	 * infers the DAG automatically from those method calls.
+	 *
+	 * @param name   Human-readable stage name (used in TUI + persistence).
+	 * @param options Optional per-stage configuration (mcp allow/deny, etc.).
+	 */
+	stage<TSchemaDef extends TSchema>(
+		name: string,
+		options: StageOptions<TSchemaDef> & { schema: TSchemaDef },
+	): StageContext<TSchemaDef>;
+	stage(name: string, options?: StageOptions): StageContext;
+	/**
+	 * Safe high-level task primitive. Equivalent to creating a named stage and
+	 * calling prompt(), with built-in context handoff support.
+	 */
+	task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
+	/** Run tasks in sequence. Missing step tasks: first gets `{task}`, later steps get `{previous}`. */
+	chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
+	/** Run tasks in parallel. Missing step tasks use the first available task as a fallback. */
+	parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
+	/** Execute a reusable child workflow by compiled workflow definition. */
+	workflow<
+		TChildInputs extends WorkflowInputValues,
+		TChildOutputs extends WorkflowOutputValues,
+		TChildRunInputs extends WorkflowInputValues = TChildInputs,
+	>(
+		definition: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
+		...args: WorkflowRunChildArgs<TChildRunInputs>
+	): Promise<WorkflowChildResult<TChildOutputs>>;
+	/** HIL primitives for user interaction during a run. */
+	readonly ui: WorkflowUIContext;
+	/**
+	 * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+	 * the result so completed side effects are not repeated on resume.
+	 * Only `ctx.*` blocks produce durable checkpoints.
+	 *
+	 * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+	 */
+	tool: WorkflowToolPrimitive;
+	/**
+	 * Model catalog port for the invoking session, when the host provides one.
+	 * `models.currentModel` is the user-selected session model; leading a stage's
+	 * model chain with it (bare, without a reasoning suffix) runs the stage at
+	 * the session's model and default thinking level.
+	 */
+	readonly models?: WorkflowModelCatalogPort;
 }
 
+export type WorkflowToolContext = AuthoringContract.WorkflowToolContext;
 export type WorkflowToolError = AuthoringContract.WorkflowToolError;
 export type WorkflowToolFailure = AuthoringContract.WorkflowToolFailure;
 export type WorkflowToolOptions = AuthoringContract.WorkflowToolOptions;
-export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> = AuthoringContract.WorkflowToolOutcome<TValue>;
+export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> =
+	AuthoringContract.WorkflowToolOutcome<TValue>;
 export type WorkflowToolPrimitive = AuthoringContract.WorkflowToolPrimitive;
 export type WorkflowToolReturnOptions = AuthoringContract.WorkflowToolReturnOptions;
-export type WorkflowToolSuccess<TValue extends WorkflowSerializableValue> = AuthoringContract.WorkflowToolSuccess<TValue>;
+export type WorkflowToolSuccess<TValue extends WorkflowSerializableValue> =
+	AuthoringContract.WorkflowToolSuccess<TValue>;
 export type WorkflowToolThrowOptions = AuthoringContract.WorkflowToolThrowOptions;
 
+/**
+ * Stable identity of one `ctx.tool` graph node.
+ *
+ * The local `tool:<argsHash>` id is unique only inside its own run: two nested
+ * child runs executing the same call produce the same local id, so control
+ * results carry the owning run alongside it.
+ */
+export interface WorkflowToolNodeIdentity {
+	readonly runId: string;
+	readonly nodeId: string;
+}
+
+/** A tool node cancelled by a control action, with its owning run identity. */
+export interface WorkflowCancelledToolNode extends WorkflowToolNodeIdentity {
+	readonly node: ToolNodeSnapshot;
+}
+
 // ---------------------------------------------------------------------------
 // WorkflowRuntimeConfig — resolved runtime tunables injected at composition root
 // ---------------------------------------------------------------------------
@@ -453,8 +497,8 @@ export type WorkflowRuntimeConfig = AuthoringContract.WorkflowRuntimeConfig;
 // ---------------------------------------------------------------------------
 
 export type WorkflowRunFn<
-  TInputs extends WorkflowInputValues = WorkflowInputValues,
-  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+	TInputs extends WorkflowInputValues = WorkflowInputValues,
+	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
 > = (ctx: WorkflowRunContext<TInputs, TOutputs>) => ReturnType<AuthoringContract.WorkflowRunFn<TInputs, TOutputs>>;
 
 // ---------------------------------------------------------------------------
@@ -467,9 +511,10 @@ declare const workflowDefinitionBrand: unique symbol;
 export type WorkflowDefinitionBrand = { readonly [workflowDefinitionBrand]: true };
 
 export interface WorkflowDefinition<
-  TInputs extends WorkflowInputValues = WorkflowInputValues,
-  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
-  TRunInputs extends WorkflowInputValues = TInputs,
-> extends Omit<AuthoringContract.WorkflowDefinition<TInputs, TOutputs, TRunInputs, WorkflowDefinitionBrand>, "run">, WorkflowDefinitionBrand {
-  readonly run: WorkflowRunFn<TInputs, TOutputs>;
+	TInputs extends WorkflowInputValues = WorkflowInputValues,
+	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+	TRunInputs extends WorkflowInputValues = TInputs,
+> extends Omit<AuthoringContract.WorkflowDefinition<TInputs, TOutputs, TRunInputs, WorkflowDefinitionBrand>, "run">,
+		WorkflowDefinitionBrand {
+	readonly run: WorkflowRunFn<TInputs, TOutputs>;
 }