@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.2

package/dist/builtin/workflows/src/authoring.d.ts

@@ -1,76 +1,24 @@
-import type { TAny, TArray, TArrayOptions, TBigInt, TBoolean, TEnum, TEnumValue, TInteger, TIntersect, TIntersectOptions, TLiteral, TLiteralValue, TNever, TNull, TNumber, TNumberOptions, TOmit, TObject, TObjectOptions, TPartial, TPick, TRecordAction, TRequired, TSchema, TSchemaOptions, TString, TStringOptions, TTuple, TTupleOptions, TUndefined, TUnion, TUnknown, TVoid, Type as TypeboxType, TKeysToIndexer } from "typebox";
-type PreserveOptions<T extends TSchema, O extends TSchemaOptions> = T & O;
-type TypeScriptEnumLike = Record<string, string | number>;
-type TypeScriptEnumValues<T extends TypeScriptEnumLike> = Extract<T[keyof T], TEnumValue>[];
-export declare const Type: Omit<typeof TypeboxType, "Any" | "Array" | "BigInt" | "Boolean" | "Enum" | "Integer" | "Intersect" | "Literal" | "Never" | "Null" | "Number" | "Omit" | "Partial" | "Pick" | "Object" | "Record" | "Required" | "String" | "Tuple" | "Undefined" | "Union" | "Unknown" | "Void"> & {
-    Any<const O extends TSchemaOptions>(options: O): PreserveOptions<TAny, O>;
-    Any(): TAny;
-    Array<Type extends TSchema, const O extends TArrayOptions>(items: Type, options: O): PreserveOptions<TArray<Type>, O>;
-    Array<Type extends TSchema>(items: Type): TArray<Type>;
-    BigInt<const O extends TSchemaOptions>(options: O): PreserveOptions<TBigInt, O>;
-    BigInt(): TBigInt;
-    Boolean<const O extends TSchemaOptions>(options: O): PreserveOptions<TBoolean, O>;
-    Boolean(): TBoolean;
-    Enum<Values extends TEnumValue[], const O extends TSchemaOptions>(values: readonly [...Values], options: O): PreserveOptions<TEnum<Values>, O>;
-    Enum<Values extends TEnumValue[]>(values: readonly [...Values]): TEnum<Values>;
-    Enum<Enum extends TypeScriptEnumLike, const O extends TSchemaOptions>(value: Enum, options: O): PreserveOptions<TEnum<TypeScriptEnumValues<Enum>>, O>;
-    Enum<Enum extends TypeScriptEnumLike>(value: Enum): TEnum<TypeScriptEnumValues<Enum>>;
-    Integer<const O extends TNumberOptions>(options: O): PreserveOptions<TInteger, O>;
-    Integer(): TInteger;
-    Intersect<Types extends TSchema[], const O extends TIntersectOptions>(types: [...Types], options: O): PreserveOptions<TIntersect<Types>, O>;
-    Intersect<Types extends TSchema[]>(types: [...Types]): TIntersect<Types>;
-    Literal<const Value extends TLiteralValue, const O extends TSchemaOptions>(value: Value, options: O): PreserveOptions<TLiteral<Value>, O>;
-    Literal<const Value extends TLiteralValue>(value: Value): TLiteral<Value>;
-    Never<const O extends TSchemaOptions>(options: O): PreserveOptions<TNever, O>;
-    Never(): TNever;
-    Null<const O extends TSchemaOptions>(options: O): PreserveOptions<TNull, O>;
-    Null(): TNull;
-    Number<const O extends TNumberOptions>(options: O): PreserveOptions<TNumber, O>;
-    Number(): TNumber;
-    Omit<Type extends TSchema, Indexer extends PropertyKey[], const O extends TSchemaOptions>(type: Type, indexer: readonly [...Indexer], options: O): PreserveOptions<TOmit<Type, TKeysToIndexer<Indexer>>, O>;
-    Omit<Type extends TSchema, Indexer extends PropertyKey[]>(type: Type, indexer: readonly [...Indexer]): TOmit<Type, TKeysToIndexer<Indexer>>;
-    Omit<Type extends TSchema, Indexer extends TSchema, const O extends TSchemaOptions>(type: Type, indexer: Indexer, options: O): PreserveOptions<TOmit<Type, Indexer>, O>;
-    Omit<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer): TOmit<Type, Indexer>;
-    Partial<Type extends TSchema, const O extends TSchemaOptions>(type: Type, options: O): PreserveOptions<TPartial<Type>, O>;
-    Partial<Type extends TSchema>(type: Type): TPartial<Type>;
-    Pick<Type extends TSchema, Indexer extends PropertyKey[], const O extends TSchemaOptions>(type: Type, indexer: readonly [...Indexer], options: O): PreserveOptions<TPick<Type, TKeysToIndexer<Indexer>>, O>;
-    Pick<Type extends TSchema, Indexer extends PropertyKey[]>(type: Type, indexer: readonly [...Indexer]): TPick<Type, TKeysToIndexer<Indexer>>;
-    Pick<Type extends TSchema, Indexer extends TSchema, const O extends TSchemaOptions>(type: Type, indexer: Indexer, options: O): PreserveOptions<TPick<Type, Indexer>, O>;
-    Pick<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer): TPick<Type, Indexer>;
-    Object<Properties extends Record<PropertyKey, TSchema>, const O extends TObjectOptions>(properties: Properties, options: O): PreserveOptions<TObject<Properties>, O>;
-    Object<Properties extends Record<PropertyKey, TSchema>>(properties: Properties): TObject<Properties>;
-    Record<Key extends TSchema, Value extends TSchema, const O extends TObjectOptions>(key: Key, value: Value, options: O): PreserveOptions<TRecordAction<Key, Value>, O>;
-    Record<Key extends TSchema, Value extends TSchema>(key: Key, value: Value): TRecordAction<Key, Value>;
-    Required<Type extends TSchema, const O extends TSchemaOptions>(type: Type, options: O): PreserveOptions<TRequired<Type>, O>;
-    Required<Type extends TSchema>(type: Type): TRequired<Type>;
-    String<const O extends TStringOptions>(options: O): PreserveOptions<TString, O>;
-    String(): TString;
-    Tuple<Types extends TSchema[], const O extends TTupleOptions>(types: [...Types], options: O): PreserveOptions<TTuple<Types>, O>;
-    Tuple<Types extends TSchema[]>(types: [...Types]): TTuple<Types>;
-    Undefined<const O extends TSchemaOptions>(options: O): PreserveOptions<TUndefined, O>;
-    Undefined(): TUndefined;
-    Union<Types extends TSchema[], const O extends TSchemaOptions>(anyOf: [...Types], options: O): PreserveOptions<TUnion<Types>, O>;
-    Union<Types extends TSchema[]>(anyOf: [...Types]): TUnion<Types>;
-    Unknown<const O extends TSchemaOptions>(options: O): PreserveOptions<TUnknown, O>;
-    Unknown(): TUnknown;
-    Void<const O extends TSchemaOptions>(options: O): PreserveOptions<TVoid, O>;
-    Void(): TVoid;
-};
+import type { TSchema } from "typebox";
 export type { Static, TSchema } from "typebox";
-export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildOptions, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
+export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
 import type * as AuthoringContract from "./shared/authoring-contract.js";
-import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowDetails, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionPolicy, WorkflowInputValues, WorkflowOutputValues, WorkflowSerializableObject, WorkflowChainStep } from "./shared/authoring-contract.js";
+import type { AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./shared/workflow-authoring-types.js";
+export type { WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas, } from "./shared/workflow-authoring-types.js";
+import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowDetails, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionPolicy, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowSerializableObject, WorkflowChainStep } from "./shared/authoring-contract.js";
 declare const workflowDefinitionBrand: unique symbol;
 type WorkflowDefinitionBrand = {
     readonly [workflowDefinitionBrand]: true;
 };
 export interface WorkflowDefinition<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs, TDefinitionBrand extends object = WorkflowDefinitionBrand> extends WorkflowContractDefinition<TInputs, TOutputs, TRunInputs, TDefinitionBrand>, WorkflowDefinitionBrand {
 }
+export type AuthoredWorkflowDefinition<TInputs extends WorkflowInputSchemaMap, TOutputs extends WorkflowOutputSchemaMap> = WorkflowDefinition<WorkflowInputsFromSchemas<TInputs>, WorkflowOutputsFromSchemas<TOutputs>, WorkflowProvidedInputsFromSchemas<TInputs>> & {
+    readonly outputs: Readonly<TOutputs>;
+};
 export type WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowRunContext<TInputs, WorkflowDefinitionBrand, TOutputs>;
 export type WorkflowRunFn<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowRunFn<TInputs, TOutputs, WorkflowDefinitionBrand>;
+type WorkflowRunInputArgument<TInputs extends WorkflowInputValues> = [keyof TInputs] extends [never] ? Readonly<Record<string, never>> : TInputs;
+export type AuthoredWorkflowSpec<TInputs extends WorkflowInputSchemaMap = {}, TOutputs extends WorkflowOutputSchemaMap = WorkflowOutputSchemaMap, TActualOutputs extends WorkflowOutputsFromSchemas<TOutputs> = WorkflowOutputsFromSchemas<TOutputs>> = SharedAuthoredWorkflowSpec<TInputs, TOutputs, TActualOutputs, WorkflowRunContext<WorkflowInputsFromSchemas<TInputs>, WorkflowOutputsFromSchemas<TOutputs>>>;
 export type AnyWorkflowDefinition = WorkflowDefinition<WorkflowInputValues, WorkflowOutputValues, WorkflowInputValues>;
-export type WorkflowBuilder<TInputs extends WorkflowInputValues = {}, TOutputs extends WorkflowOutputValues = {}, TRunInputs extends WorkflowInputValues = TInputs> = AuthoringContract.WorkflowBuilder<TInputs, TOutputs, TRunInputs, WorkflowDefinitionBrand, WorkflowDefinition<TInputs, TOutputs, TRunInputs>>;
-export type CompletedWorkflowBuilder<TInputs extends WorkflowInputValues = {}, TOutputs extends WorkflowOutputValues = {}, TRunInputs extends WorkflowInputValues = TInputs> = AuthoringContract.CompletedWorkflowBuilder<TInputs, TOutputs, TRunInputs, WorkflowDefinitionBrand, WorkflowDefinition<TInputs, TOutputs, TRunInputs>>;
 export type RunContinuationOpts = AuthoringContract.RunContinuationOpts;
 export type WorkflowParentRunLink = AuthoringContract.WorkflowParentRunLink;
 export type RunOpts = Omit<AuthoringContract.RunOpts, "registry"> & {
@@ -78,7 +26,7 @@ export type RunOpts = Omit<AuthoringContract.RunOpts, "registry"> & {
 };
 export declare const INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy;
 export declare const NON_INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy;
-export declare function run<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs>(definition: WorkflowDefinition<TInputs, TOutputs, TRunInputs>, inputs: Readonly<NoInfer<TRunInputs>>, opts?: RunOpts): Promise<RunResult<TOutputs>>;
+export declare function run<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs>(definition: WorkflowDefinition<TInputs, TOutputs, TRunInputs>, inputs: Readonly<NoInfer<WorkflowRunInputArgument<TRunInputs>>>, opts?: RunOpts): Promise<RunResult<TOutputs>>;
 export declare function runTask(task: WorkflowDirectTaskItem, runOptions?: RunOpts): Promise<WorkflowDetails>;
 export declare function runTask(task: WorkflowDirectTaskItem, options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
 export declare function runParallel(tasks: readonly WorkflowDirectTaskItem[], options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
@@ -86,7 +34,7 @@ export declare function runChain(steps: readonly WorkflowChainStep[], options?:
 export declare function resolveInputs<TInputs extends WorkflowInputValues>(schema: Readonly<Record<keyof TInputs & string, TSchema>>, provided: Partial<TInputs>): ResolvedInputs<TInputs>;
 export declare function setupGitWorktree(options: GitWorktreeSetupOptions): GitWorktreeSetupResult;
 export interface WorkflowRegistry {
-    register<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues>(definition: WorkflowDefinition<TInputs, TOutputs>): WorkflowRegistry;
+    register<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs>(definition: WorkflowDefinition<TInputs, TOutputs, TRunInputs>): WorkflowRegistry;
     merge(other: WorkflowRegistry): WorkflowRegistry;
     get(name: string): AnyWorkflowDefinition | undefined;
     has(name: string): boolean;
@@ -96,10 +44,10 @@ export interface WorkflowRegistry {
 }
 /**
  * @deprecated Removed imperative workflow API. This runtime value only throws
- * a migration error; author workflows with defineWorkflow(...).compile().
+ * a migration error; author workflows with workflow({...}).
  */
 export declare const runWorkflow: never;
-export declare function defineWorkflow(name: string): WorkflowBuilder;
+export declare function workflow<const TInputs extends WorkflowInputSchemaMap = {}, const TOutputs extends WorkflowOutputSchemaMap = WorkflowOutputSchemaMap, TActualOutputs extends WorkflowOutputsFromSchemas<TOutputs> = WorkflowOutputsFromSchemas<TOutputs>>(spec: AuthoredWorkflowSpec<TInputs, TOutputs, TActualOutputs>): AuthoredWorkflowDefinition<TInputs, TOutputs>;
 export declare function createRegistry<TDefinitions extends readonly AnyWorkflowDefinition[] = readonly AnyWorkflowDefinition[]>(initial?: TDefinitions): WorkflowRegistry;
 export declare function normalizeWorkflowName(name: string): string;
 export declare function workflowNamesEqual(a: string, b: string): boolean;

package/dist/builtin/workflows/src/engine/graph-inference.ts

@@ -0,0 +1,100 @@
+/**
+ * GraphFrontierTracker — infers DAG parents from JavaScript execution order.
+ *
+ * Algorithm:
+ * - Maintain `frontier: Set<string>` — settled stage IDs not yet consumed as parents
+ * - At onSpawn(stageId): snapshot current frontier as parents, store in stageParents
+ * - At onSettle(stageId): remove stage's parents from frontier, add stageId to frontier
+ * - getParents(stageId): return recorded parents
+ */
+
+export interface StageNode {
+  readonly id: string;
+  readonly name: string;
+  readonly parentIds: readonly string[];
+}
+
+export class GraphFrontierTracker {
+  private frontier: Set<string> = new Set();
+  private stageParents: Map<string, string[]> = new Map();
+  private nodes: Map<string, StageNode> = new Map();
+
+  /**
+   * Call when ctx.stage(name) is invoked.
+   * Returns the inferred parent IDs (snapshot of current frontier).
+   */
+  onSpawn(stageId: string, stageName: string): string[] {
+    const parents = Array.from(this.frontier);
+    this.stageParents.set(stageId, parents);
+
+    this.nodes.set(stageId, {
+      id: stageId,
+      name: stageName,
+      parentIds: Object.freeze(parents),
+    });
+
+    return parents;
+  }
+
+  /**
+   * Snapshot the current frontier without registering or mutating a stage.
+   *
+   * Use this when an already-spawned stage needs its parents refreshed before
+   * it starts; `onSpawn` must only be called for the initial `ctx.stage()`
+   * invocation that creates the graph node.
+   */
+  currentParents(): string[] {
+    return Array.from(this.frontier);
+  }
+
+  /**
+   * Replace the recorded parents for a stage before it settles.
+   *
+   * Continuation replay uses source-run topology as authoritative: a replayed
+   * stage may spawn with provisional parents inferred from the continuation's
+   * current frontier, then install the translated source parents before the
+   * stage is recorded or settled.
+   */
+  replaceParents(stageId: string, parentIds: readonly string[]): void {
+    const parents = Array.from(parentIds);
+    this.stageParents.set(stageId, parents);
+    const node = this.nodes.get(stageId);
+    if (node !== undefined) {
+      this.nodes.set(stageId, {
+        ...node,
+        parentIds: Object.freeze(parents),
+      });
+    }
+  }
+
+  /**
+   * Call when the stage's Promise settles.
+   * Removes the stage's parents from the frontier and adds stageId to frontier.
+   */
+  onSettle(stageId: string): void {
+    const parents = this.stageParents.get(stageId) ?? [];
+    // Remove parents from frontier (they are now consumed)
+    for (const parentId of parents) {
+      this.frontier.delete(parentId);
+    }
+    // Add this stage to the frontier
+    this.frontier.add(stageId);
+  }
+
+  /** Get all recorded nodes as an array. */
+  getNodes(): StageNode[] {
+    return Array.from(this.nodes.values());
+  }
+
+  /** Get parent IDs for a stage. */
+  getParents(stageId: string): string[] {
+    return this.stageParents.get(stageId) ?? [];
+  }
+
+  /** Reset to initial state. */
+  reset(): void {
+    this.frontier.clear();
+    this.stageParents.clear();
+    this.nodes.clear();
+  }
+}

package/dist/builtin/workflows/src/engine/options.ts

@@ -0,0 +1,40 @@
+import type { RunOpts } from "../runs/foreground/executor-types.js";
+
+export type EngineStageRuntimeOptions = Pick<
+  RunOpts,
+  | "continuation"
+  | "models"
+  | "executionMode"
+  | "defaultSessionDir"
+  | "persistence"
+  | "onStageStart"
+  | "onStageEnd"
+  | "confirmStageReadiness"
+  | "usePromptNodesForUi"
+>;
+
+export type EngineWorkflowBoundaryOptions = Pick<
+  RunOpts,
+  "persistence" | "onStageStart" | "onStageEnd"
+>;
+
+export type EngineChildRunOptions = Pick<
+  RunOpts,
+  | "adapters"
+  | "ui"
+  | "executionMode"
+  | "defaultSessionDir"
+  | "usePromptNodesForUi"
+  | "confirmStageReadiness"
+  | "store"
+  | "persistence"
+  | "mcp"
+  | "cancellation"
+  | "overlay"
+  | "config"
+  | "models"
+  | "registry"
+  | "stageControlRegistry"
+  | "onStageStart"
+  | "onStageEnd"
+>;

package/dist/builtin/workflows/src/engine/primitives/chain.ts

@@ -0,0 +1,29 @@
+import type { WorkflowChainOptions, WorkflowTaskResult, WorkflowTaskStep } from "../../shared/types.js";
+import type { EngineRuntime } from "../runtime.js";
+import type { WorkflowTaskPrimitive } from "./task.js";
+import {
+  chainStepPrompt,
+  replaceTaskPlaceholder,
+  taskOptionsFromStep,
+  taskPrevious,
+  taskWithSharedDefaults,
+} from "../../runs/foreground/executor-task-prompts.js";
+
+export function createChainPrimitive(input: {
+  readonly runtime: EngineRuntime;
+  readonly task: WorkflowTaskPrimitive;
+}): (steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions) => Promise<WorkflowTaskResult[]> {
+  return async (steps: readonly WorkflowTaskStep[], options: WorkflowChainOptions = {}): Promise<WorkflowTaskResult[]> => {
+    input.runtime.exit.throwIfWorkflowExitSelected();
+    const results: WorkflowTaskResult[] = [];
+    for (let index = 0; index < steps.length; index += 1) {
+      input.runtime.exit.throwIfWorkflowExitSelected();
+      const step = steps[index]!;
+      const explicitPrevious = taskPrevious(step);
+      const previous = explicitPrevious ?? (index > 0 ? results[index - 1] : undefined);
+      const prompt = replaceTaskPlaceholder(chainStepPrompt(step, index), options.task ?? "");
+      results.push(await input.task(step.name, taskWithSharedDefaults(taskOptionsFromStep(step, prompt, previous), options)));
+    }
+    return results;
+  };
+}

package/dist/builtin/workflows/src/engine/primitives/exit.ts

@@ -0,0 +1,2 @@
+export { createWorkflowExitManager } from "../../runs/foreground/executor-exit-manager.js";
+export type { WorkflowExitManager } from "../../runs/foreground/executor-exit-manager.js";

package/dist/builtin/workflows/src/engine/primitives/parallel.ts

@@ -0,0 +1,47 @@
+import type { WorkflowParallelOptions, WorkflowTaskResult, WorkflowTaskStep } from "../../shared/types.js";
+import type { EngineRuntime } from "../runtime.js";
+import type { WorkflowTaskPrimitive } from "./task.js";
+import type { ParallelFailFastScope, ParallelFailFastStage } from "../../runs/foreground/executor-types.js";
+import { findWorkflowExitSignal } from "../../runs/foreground/executor-abort.js";
+import { mapParallelSteps } from "../../runs/foreground/executor-direct-helpers.js";
+import {
+  parallelFallbackTask,
+  replaceTaskPlaceholder,
+  taskOptionsFromStep,
+  taskPrevious,
+  taskWithSharedDefaults,
+} from "../../runs/foreground/executor-task-prompts.js";
+
+export function createParallelPrimitive(input: {
+  readonly runtime: EngineRuntime;
+  readonly task: WorkflowTaskPrimitive;
+}): (steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions) => Promise<WorkflowTaskResult[]> {
+  return async (steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions = {}): Promise<WorkflowTaskResult[]> => {
+    input.runtime.exit.throwIfWorkflowExitSelected();
+    const fallback = parallelFallbackTask(steps, options);
+    const failFastEnabled = options.failFast !== false;
+    const parallelScope: ParallelFailFastScope = {
+      failed: false,
+      activeStages: new Map<string, ParallelFailFastStage>(),
+      parentIds: Object.freeze(input.runtime.tracker.currentParents()),
+    };
+    return mapParallelSteps(steps, options.concurrency, options.failFast, async (step) => {
+      input.runtime.exit.throwIfWorkflowExitSelected();
+      const prompt = replaceTaskPlaceholder(step.prompt ?? step.task ?? fallback, options.task ?? fallback);
+      return await input.task(
+        step.name,
+        taskWithSharedDefaults(taskOptionsFromStep(step, prompt, taskPrevious(step)), options),
+        parallelScope,
+      );
+    }, (error) => {
+      if (!failFastEnabled) return;
+      parallelScope.failed = true;
+      parallelScope.firstFailure = error;
+      for (const stage of parallelScope.activeStages.values()) stage.skip();
+    }, {
+      beforeDequeue: input.runtime.exit.throwIfWorkflowExitSelected,
+      beforeMap: input.runtime.exit.throwIfWorkflowExitSelected,
+      isControlSignal: (error) => findWorkflowExitSignal(error, input.runtime.exit.exitScope) !== undefined,
+    });
+  };
+}

package/dist/builtin/workflows/src/engine/primitives/task.ts

@@ -0,0 +1,108 @@
+import type { WorkflowChainOptions, WorkflowParallelOptions, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep } from "../../shared/types.js";
+import type { ParallelFailFastScope } from "../../runs/foreground/executor-types.js";
+import type { EngineRuntime } from "../runtime.js";
+import {
+  applyTaskContext,
+  structuredTaskOutputText,
+  taskPrevious,
+  taskPrompt,
+  taskPromptOptions,
+  taskReadInstruction,
+  taskStageOptions,
+  truncateTaskOutput,
+} from "../../runs/foreground/executor-task-prompts.js";
+import {
+  cleanupPreparedWorktrees,
+  collectWorktreeDiffs,
+  prepareDirectWorktrees,
+  stageOptionsWithGitWorktree,
+  stageOptionsWithInputDefaults,
+} from "../../runs/foreground/executor-direct-helpers.js";
+import { createChainPrimitive } from "./chain.js";
+import { createParallelPrimitive } from "./parallel.js";
+
+export type WorkflowTaskPrimitive = (
+  name: string,
+  options: WorkflowTaskOptions,
+  stageFailFastScope?: ParallelFailFastScope,
+) => Promise<WorkflowTaskResult>;
+
+export interface WorkflowTaskRunners {
+  task: WorkflowTaskPrimitive;
+  chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
+  parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
+}
+
+function createTaskPrimitive(runtime: EngineRuntime): WorkflowTaskPrimitive {
+  return async (name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope): Promise<WorkflowTaskResult> => {
+    runtime.exit.throwIfWorkflowExitSelected();
+    const runTaskOnce = async (taskOptions: WorkflowTaskOptions): Promise<WorkflowTaskResult> => {
+      runtime.exit.throwIfWorkflowExitSelected();
+      const resolvedTaskOptions = stageOptionsWithGitWorktree(
+        stageOptionsWithInputDefaults(taskOptions, runtime.inputRuntimeDefaults),
+        runtime.workflowInvocationCwd,
+      ) ?? taskOptions;
+      const stageOptions = taskStageOptions(resolvedTaskOptions);
+      const stageHandle = runtime.spawnStage(name, {
+        kind: "agent",
+        ...(stageOptions !== undefined ? { options: stageOptions } : {}),
+        ...(stageFailFastScope !== undefined ? { failFastScope: stageFailFastScope } : {}),
+      });
+      const stage = stageHandle.context;
+      const rawOutput = await stage.prompt(
+        applyTaskContext(`${taskReadInstruction(resolvedTaskOptions)}${taskPrompt(resolvedTaskOptions)}`, taskPrevious(resolvedTaskOptions)),
+        taskPromptOptions(resolvedTaskOptions),
+      );
+      const structured = typeof rawOutput === "string" ? undefined : rawOutput;
+      const text = truncateTaskOutput(structuredTaskOutputText(rawOutput), resolvedTaskOptions.maxOutput);
+      const sessionId = (() => {
+        try {
+          return stage.sessionId;
+        } catch {
+          return undefined;
+        }
+      })();
+      const stageMeta = stage.__modelFallbackMeta();
+      return {
+        name,
+        stageName: name,
+        text,
+        ...(structured !== undefined ? { structured } : {}),
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(stage.sessionFile !== undefined ? { sessionFile: stage.sessionFile } : {}),
+        ...(stageMeta.model !== undefined ? { model: stageMeta.model } : {}),
+        ...(stageMeta.fastMode === true ? { fastMode: stageMeta.fastMode } : {}),
+        ...(stageMeta.attemptedModels !== undefined ? { attemptedModels: stageMeta.attemptedModels } : {}),
+        ...(stageMeta.modelAttempts !== undefined ? { modelAttempts: stageMeta.modelAttempts } : {}),
+        ...(stageMeta.warnings !== undefined ? { warnings: stageMeta.warnings } : {}),
+      };
+    };
+
+    if (options.worktree !== true) return runTaskOnce(options);
+    const prepared = prepareDirectWorktrees(
+      [{ ...options, name }],
+      { ...options, worktree: true },
+      `${runtime.runId}-${name}-${crypto.randomUUID()}`,
+      name,
+    );
+    const preparedTask = prepared.tasks[0]!;
+    try {
+      const result = await runTaskOnce(preparedTask);
+      const worktreeDiffs = collectWorktreeDiffs(prepared, options.artifacts !== false);
+      return worktreeDiffs.artifacts.length === 0
+        ? result
+        : { ...result, artifacts: [...(result.artifacts ?? []), ...worktreeDiffs.artifacts] };
+    } finally {
+      cleanupPreparedWorktrees(prepared);
+    }
+  };
+}
+
+export function createWorkflowTaskRunners(input: { readonly runtime: EngineRuntime }): WorkflowTaskRunners {
+  const task = createTaskPrimitive(input.runtime);
+  return {
+    task,
+    chain: createChainPrimitive({ runtime: input.runtime, task }),
+    parallel: createParallelPrimitive({ runtime: input.runtime, task }),
+  };
+}

package/dist/builtin/workflows/src/engine/primitives/ui.ts

@@ -0,0 +1,41 @@
+import type {
+  WorkflowCustomUiFactory,
+  WorkflowCustomUiOptions,
+  WorkflowUIContext,
+} from "../../shared/types.js";
+import type { RunOpts } from "../../runs/foreground/executor-types.js";
+import { makeHeadlessUnavailableUIContext, normalizeUIContext } from "../../runs/foreground/executor-hil.js";
+
+export function buildExitGatedUiContext(input: {
+  readonly opts: RunOpts;
+  readonly baseFromPromptNodes: () => WorkflowUIContext;
+  readonly throwIfWorkflowExitSelected: () => void;
+}): WorkflowUIContext {
+  const base = input.opts.usePromptNodesForUi === true
+    ? input.baseFromPromptNodes()
+    : input.opts.executionMode === "non_interactive" && input.opts.ui === undefined
+      ? makeHeadlessUnavailableUIContext()
+      : normalizeUIContext(input.opts.ui);
+  return {
+    async input(promptText: string): Promise<string> {
+      input.throwIfWorkflowExitSelected();
+      return await base.input(promptText);
+    },
+    async confirm(message: string): Promise<boolean> {
+      input.throwIfWorkflowExitSelected();
+      return await base.confirm(message);
+    },
+    async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
+      input.throwIfWorkflowExitSelected();
+      return await base.select(message, options);
+    },
+    async editor(initial?: string): Promise<string> {
+      input.throwIfWorkflowExitSelected();
+      return await base.editor(initial);
+    },
+    async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
+      input.throwIfWorkflowExitSelected();
+      return await base.custom(factory, options);
+    },
+  };
+}