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

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

@@ -0,0 +1,159 @@
+import type {
+  WorkflowChildResult,
+  WorkflowDefinition,
+  WorkflowInputValues,
+  WorkflowOutputValues,
+  WorkflowRunChildArgs,
+  WorkflowRunChildOptions,
+} from "../../shared/types.js";
+import type { WorkflowChildRunRef } from "../../shared/store-types.js";
+import type { ResolvedInputs, RunOpts, RunResult } from "../../runs/foreground/executor-types.js";
+import type { EngineRuntime } from "../runtime.js";
+import { findWorkflowExitSignal, isWorkflowExitStatus, makeParentWorkflowExitAbortReason } from "../../runs/foreground/executor-abort.js";
+import { selectWorkflowOutputs } from "../../runs/foreground/executor-outputs.js";
+import { resolveAndValidateInputs } from "../../runs/foreground/executor-inputs.js";
+import {
+  isWorkflowDefinition,
+  workflowChildReplaySnapshot,
+  workflowDefinitionRequirementMessage,
+} from "../../runs/foreground/executor-child-helpers.js";
+
+export function createChildWorkflowRunner(input: {
+  readonly runtime: EngineRuntime;
+  readonly resolveWorkflowCwd: () => string;
+  readonly nextWorkflowBoundaryReplayKey: (name: string) => string;
+  readonly runWorkflow: <
+    TInputs extends WorkflowInputValues,
+    TRunInputs extends WorkflowInputValues = TInputs,
+  >(
+    def: WorkflowDefinition<TInputs, WorkflowOutputValues, TRunInputs>,
+    inputs: ResolvedInputs,
+    opts?: RunOpts,
+  ) => Promise<RunResult>;
+}): <
+  TChildInputs extends WorkflowInputValues,
+  TChildOutputs extends WorkflowOutputValues,
+  TChildRunInputs extends WorkflowInputValues = TChildInputs,
+>(
+  child: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
+  ...args: WorkflowRunChildArgs<TChildRunInputs>
+) => Promise<WorkflowChildResult<TChildOutputs>> {
+  return async <
+    TChildInputs extends WorkflowInputValues,
+    TChildOutputs extends WorkflowOutputValues,
+    TChildRunInputs extends WorkflowInputValues = TChildInputs,
+  >(
+    child: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
+    ...args: WorkflowRunChildArgs<TChildRunInputs>
+  ): Promise<WorkflowChildResult<TChildOutputs>> => {
+    const options: WorkflowRunChildOptions<TChildRunInputs> = args[0] ?? {};
+    const { runtime } = input;
+    runtime.exit.throwIfWorkflowExitSelected();
+    if (!isWorkflowDefinition(child)) throw new Error(workflowDefinitionRequirementMessage("ctx.workflow(definition)", child));
+    const childName = child.normalizedName;
+    const boundaryName = options.stageName ?? `workflow:${childName}`;
+    const boundaryReplayKey = input.nextWorkflowBoundaryReplayKey(boundaryName);
+    const boundary = runtime.spawnStage(boundaryName, { kind: "workflow-boundary", replayKey: boundaryReplayKey }).boundary;
+    let childRunId: string | undefined;
+    let detachParentAbort: (() => void) | undefined;
+    try {
+      if (boundary.replayedChild !== undefined) {
+        await Promise.resolve();
+        runtime.exit.throwIfWorkflowExitSelected();
+        boundary.finalizeReplay();
+        return boundary.replayedChild as WorkflowChildResult<TChildOutputs>;
+      }
+
+      const childInputs = resolveAndValidateInputs(child.inputs, options.inputs ?? {}, `child workflow "${childName}" (${child.name})`);
+      runtime.exit.throwIfWorkflowExitSelected();
+
+      childRunId = crypto.randomUUID();
+      const childController = new AbortController();
+      const childRef: WorkflowChildRunRef = { alias: childName, workflow: child.normalizedName, runId: childRunId };
+      boundary.linkChildRun(childRef, childController);
+
+      const abortChildFromParent = (): void => {
+        const parentExit = findWorkflowExitSignal(runtime.signal.reason, runtime.exit.exitScope);
+        childController.abort(parentExit !== undefined ? makeParentWorkflowExitAbortReason(parentExit.reason) : runtime.signal.reason);
+      };
+      if (runtime.signal.aborted) abortChildFromParent();
+      else {
+        runtime.signal.addEventListener("abort", abortChildFromParent, { once: true });
+        detachParentAbort = () => runtime.signal.removeEventListener("abort", abortChildFromParent);
+      }
+      runtime.exit.throwIfWorkflowExitSelected();
+      runtime.childRunOptions.cancellation?.register(childRunId, childController);
+      runtime.exit.throwIfWorkflowExitSelected();
+
+      // Ordering is intentional: linkChildRun happens before launch so parent
+      // cleanup can abort the child; observeChildRun happens immediately after
+      // promise creation, with no await in between, so cleanup can await teardown.
+      const childRunPromise = input.runWorkflow(child, childInputs, {
+        ...runtime.childRunOptions,
+        runId: childRunId,
+        cwd: input.resolveWorkflowCwd(),
+        depth: runtime.depth + 1,
+        parentRun: {
+          runId: runtime.runId,
+          stageId: boundary.id,
+          rootRunId: runtime.parentRootRunId ?? runtime.runId,
+        },
+        signal: childController.signal,
+        deferWorkflowStart: false,
+      });
+      boundary.observeChildRun(childRunPromise);
+      const childRun = await childRunPromise;
+      runtime.exit.throwIfWorkflowExitSelected();
+
+      if (!isWorkflowExitStatus(childRun.status)) {
+        const failedChildStage = childRun.stages.find((stage) => stage.failureKind !== undefined);
+        throw new Error(
+          `atomic-workflows: child workflow "${childName}" (${child.name}) failed with status ${childRun.status}${childRun.error !== undefined ? `: ${childRun.error}` : ""}`,
+          {
+            cause: {
+              ...(failedChildStage?.failureKind !== undefined ? { code: failedChildStage.failureKind } : {}),
+              ...(failedChildStage?.failureMessage !== undefined ? { message: failedChildStage.failureMessage } : {}),
+            },
+          },
+        );
+      }
+
+      const outputs = selectWorkflowOutputs(child, childRun.result);
+      const childExited = childRun.exited === true || childRun.status !== "completed";
+      const childResult: WorkflowChildResult<TChildOutputs> = childExited
+        ? {
+            workflow: child.normalizedName,
+            runId: childRun.runId,
+            status: childRun.status,
+            exited: true,
+            outputs: outputs as Partial<TChildOutputs>,
+            ...(childRun.exitReason !== undefined ? { exitReason: childRun.exitReason } : {}),
+          }
+        : {
+            workflow: child.normalizedName,
+            runId: childRun.runId,
+            status: "completed",
+            exited: false,
+            outputs: outputs as TChildOutputs,
+          };
+      const workflowChild = workflowChildReplaySnapshot(childName, childResult);
+      const outputKeys = Object.keys(outputs);
+      boundary.complete(
+        `Workflow "${child.name}" ${childRun.status} (runId: ${childRun.runId}; outputs: ${outputKeys.length > 0 ? outputKeys.join(", ") : "(none)"})`,
+        workflowChild,
+      );
+      return childResult;
+    } catch (err) {
+      const exit = findWorkflowExitSignal(err, runtime.exit.exitScope) ?? findWorkflowExitSignal(runtime.signal.reason, runtime.exit.exitScope);
+      if (exit !== undefined) {
+        await boundary.skipForWorkflowExit(exit.reason);
+        throw exit;
+      }
+      boundary.fail(err);
+      throw err;
+    } finally {
+      detachParentAbort?.();
+      if (childRunId !== undefined) runtime.childRunOptions.cancellation?.unregister(childRunId);
+    }
+  };
+}

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

@@ -0,0 +1,8 @@
+export {
+  createContinuationReplayIndex,
+  sameStringSet,
+} from "../runs/foreground/executor-continuation.js";
+export type {
+  ContinuationReplayDecision,
+  ContinuationReplayIndex,
+} from "../runs/foreground/executor-continuation.js";

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

@@ -0,0 +1,356 @@
+import type { RunSnapshot } from "../shared/store-types.js";
+import type {
+  WorkflowDefinition,
+  WorkflowInputValues,
+  WorkflowOutputValues,
+  WorkflowRunContext,
+} from "../shared/types.js";
+import type { WorkflowFailure } from "../shared/workflow-failures.js";
+import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
+import { store as defaultStore } from "../shared/store.js";
+import { appendRunStart } from "../shared/persistence-session-entries.js";
+import { GraphFrontierTracker } from "./graph-inference.js";
+import { EngineRuntime } from "./runtime.js";
+import type { EngineChildRunOptions, EngineStageRuntimeOptions, EngineWorkflowBoundaryOptions } from "./options.js";
+import { createContinuationReplayIndex } from "./replay.js";
+import { buildExitGatedUiContext } from "./primitives/ui.js";
+import { createWorkflowExitManager } from "./primitives/exit.js";
+import { createWorkflowTaskRunners } from "./primitives/task.js";
+import { createChildWorkflowRunner } from "./primitives/workflow.js";
+import { createRunLimiter } from "../runs/shared/concurrency.js";
+import { stageControlRegistry as defaultStageControlRegistry } from "../runs/foreground/stage-control-registry.js";
+import type { RunOpts, RunResult } from "../runs/foreground/executor-types.js";
+import { unknownErrorMessage, findWorkflowExitSignal, parentWorkflowExitAbortReason } from "../runs/foreground/executor-abort.js";
+import { resolveAndValidateInputs, resolveInputConcurrency, resolveInputRuntimeDefaults } from "../runs/foreground/executor-inputs.js";
+import { workflowCwdWithInputWorktree } from "../runs/foreground/executor-direct-helpers.js";
+import { createStageScheduler } from "../runs/foreground/executor-scheduler.js";
+import { createRunFinalizers } from "../runs/foreground/executor-run-finalizers.js";
+import { buildPromptNodeUiAdapter } from "../runs/foreground/executor-prompt-nodes.js";
+import {
+  appendRunEndWhenRecorded,
+  assertWorkflowCreatedStage,
+  finalizeKilled,
+  finalizeKilledByFailure,
+  recordActiveBlockedFailure,
+  reconcileTerminalRunResult,
+  selectRunFailureDisposition,
+} from "../runs/foreground/executor-lifecycle.js";
+import { assertWorkflowRunOutputs, normalizeWorkflowRunOutput } from "../runs/foreground/executor-outputs.js";
+import { isWorkflowDefinition, workflowDefinitionRequirementMessage } from "../runs/foreground/executor-child-helpers.js";
+
+function nextEventLoopTurn(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+type WorkflowRunInputArgument = Parameters<typeof resolveAndValidateInputs>[1];
+
+export function run<
+  TInputs extends WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues,
+  TRunInputs extends WorkflowInputValues = TInputs,
+>(
+  def: WorkflowDefinition<TInputs, TOutputs, TRunInputs>,
+  inputs: WorkflowRunInputArgument,
+  opts?: RunOpts,
+): Promise<RunResult<TOutputs>>;
+export async function run<
+  TInputs extends WorkflowInputValues,
+  TRunInputs extends WorkflowInputValues = TInputs,
+>(
+  def: WorkflowDefinition<TInputs, WorkflowOutputValues, TRunInputs>,
+  inputs: WorkflowRunInputArgument,
+  opts: RunOpts = {},
+): Promise<RunResult> {
+  if (!isWorkflowDefinition(def)) throw new Error(workflowDefinitionRequirementMessage("run(definition, inputs)", def));
+
+  const activeStore = opts.store ?? defaultStore;
+  const adapters = opts.adapters ?? {};
+  // Prompt-node UI is the graph-mode transport and intentionally takes precedence
+  // over an injected RunOpts.ui adapter; warn because that adapter will be ignored.
+  if (opts.usePromptNodesForUi === true && opts.ui !== undefined) {
+    console.warn("atomic-workflows: usePromptNodesForUi ignores the provided RunOpts.ui adapter");
+  }
+
+  const depth = opts.depth ?? 0;
+  const maxDepth = opts.config?.maxDepth ?? 4;
+  if (depth >= maxDepth) {
+    return {
+      runId: opts.runId ?? crypto.randomUUID(),
+      status: "failed",
+      error: `atomic-workflows: maxDepth exceeded (max ${maxDepth})`,
+      stages: [],
+    };
+  }
+
+  const resolvedInputs = resolveAndValidateInputs(def.inputs, inputs, `workflow "${def.name}"`);
+  const runId = opts.runId ?? crypto.randomUUID();
+  const exitScope = Symbol(`workflow-exit:${runId}`);
+  const ownController = new AbortController();
+  const callerSignal = opts.signal;
+  if (callerSignal) {
+    if (callerSignal.aborted) ownController.abort(callerSignal.reason);
+    else callerSignal.addEventListener("abort", () => { ownController.abort(callerSignal.reason); }, { once: true });
+  }
+  const exit = createWorkflowExitManager({ runId, exitScope, controller: ownController });
+
+  const runSnapshot: RunSnapshot = {
+    id: runId,
+    name: def.name,
+    inputs: Object.freeze(resolvedInputs),
+    status: "running" as const,
+    stages: [],
+    startedAt: Date.now(),
+    ...(opts.parentRun !== undefined ? {
+      parentRunId: opts.parentRun.runId,
+      parentStageId: opts.parentRun.stageId,
+      rootRunId: opts.parentRun.rootRunId,
+    } : {}),
+    ...(opts.continuation !== undefined ? {
+      resumedFromRunId: opts.continuation.source.id,
+      resumeFromStageId: opts.continuation.resumeFromStageId,
+    } : {}),
+  };
+
+  const classifiedFailures = new Map<unknown, WorkflowFailure>();
+  const classifyExecutorFailure = (error: unknown): WorkflowFailure => {
+    const cached = classifiedFailures.get(error);
+    if (cached !== undefined) return cached;
+    let classified: WorkflowFailure;
+    try {
+      classified = classifyWorkflowFailure(error);
+    } catch {
+      classified = classifyWorkflowFailure(new Error(unknownErrorMessage(error)));
+    }
+    classifiedFailures.set(error, classified);
+    return classified;
+  };
+
+  activeStore.recordRunStart(runSnapshot);
+  if (!opts.signal) opts.cancellation?.register(runId, ownController);
+  opts.onRunStart?.(runSnapshot);
+  if (opts.persistence) {
+    appendRunStart(opts.persistence, {
+      runId,
+      name: def.name,
+      inputs: resolvedInputs,
+      ...(runSnapshot.parentRunId !== undefined ? { parentRunId: runSnapshot.parentRunId } : {}),
+      ...(runSnapshot.parentStageId !== undefined ? { parentStageId: runSnapshot.parentStageId } : {}),
+      ...(runSnapshot.rootRunId !== undefined ? { rootRunId: runSnapshot.rootRunId } : {}),
+      ...(runSnapshot.resumedFromRunId !== undefined ? { resumedFromRunId: runSnapshot.resumedFromRunId } : {}),
+      ...(runSnapshot.resumeFromStageId !== undefined ? { resumeFromStageId: runSnapshot.resumeFromStageId } : {}),
+      ts: runSnapshot.startedAt,
+    });
+  }
+
+  const tracker = new GraphFrontierTracker();
+  const inputConcurrency = resolveInputConcurrency(def.inputs, resolvedInputs);
+  const inputRuntimeDefaults = resolveInputRuntimeDefaults(def, resolvedInputs);
+  const workflowInvocationCwd = opts.cwd ?? process.cwd();
+  let workflowCwd: string | undefined;
+  const resolveWorkflowCwd = (): string => {
+    workflowCwd ??= workflowCwdWithInputWorktree(inputRuntimeDefaults, workflowInvocationCwd);
+    return workflowCwd;
+  };
+  const limiter = createRunLimiter(inputConcurrency ?? opts.config?.defaultConcurrency);
+  const stageRegistry = opts.stageControlRegistry ?? defaultStageControlRegistry;
+  const replayIndex = createContinuationReplayIndex(opts.continuation);
+  const scheduler = createStageScheduler({
+    runId,
+    runSnapshot,
+    activeStore,
+    tracker,
+    stageRegistry: () => stageRegistry,
+  });
+  ownController.signal.addEventListener(
+    "abort",
+    () => scheduler.rejectReleaseBarriers(ownController.signal.reason ?? new Error("atomic-workflows: run aborted")),
+    { once: true },
+  );
+
+  const finalizers = createRunFinalizers({
+    def,
+    runId,
+    runSnapshot,
+    activeStore,
+    opts,
+    classifyExecutorFailure,
+    drainWorkflowExitCleanups: exit.drainWorkflowExitCleanups,
+  });
+  const stageOptions: EngineStageRuntimeOptions = {
+    continuation: opts.continuation,
+    models: opts.models,
+    executionMode: opts.executionMode,
+    defaultSessionDir: opts.defaultSessionDir,
+    persistence: opts.persistence,
+    onStageStart: opts.onStageStart,
+    onStageEnd: opts.onStageEnd,
+    confirmStageReadiness: opts.confirmStageReadiness,
+    usePromptNodesForUi: opts.usePromptNodesForUi,
+  };
+  const workflowBoundaryOptions: EngineWorkflowBoundaryOptions = {
+    persistence: opts.persistence,
+    onStageStart: opts.onStageStart,
+    onStageEnd: opts.onStageEnd,
+  };
+  const childRunOptions: EngineChildRunOptions = {
+    adapters: opts.adapters,
+    ui: opts.ui,
+    executionMode: opts.executionMode,
+    defaultSessionDir: opts.defaultSessionDir,
+    usePromptNodesForUi: opts.usePromptNodesForUi,
+    confirmStageReadiness: opts.confirmStageReadiness,
+    store: opts.store,
+    persistence: opts.persistence,
+    mcp: opts.mcp,
+    cancellation: opts.cancellation,
+    overlay: opts.overlay,
+    config: opts.config,
+    models: opts.models,
+    registry: opts.registry,
+    stageControlRegistry: opts.stageControlRegistry,
+    onStageStart: opts.onStageStart,
+    onStageEnd: opts.onStageEnd,
+  };
+  const runtime = new EngineRuntime({
+    runId,
+    depth,
+    runSnapshot,
+    activeStore,
+    stageOptions,
+    workflowBoundaryOptions,
+    childRunOptions,
+    parentRootRunId: opts.parentRun?.rootRunId,
+    adapters,
+    signal: ownController.signal,
+    tracker,
+    scheduler,
+    replayIndex,
+    limiter,
+    inputRuntimeDefaults,
+    workflowInvocationCwd,
+    stageRegistry,
+    exit,
+    classifyExecutorFailure,
+  });
+  const workflowBoundaryReplayCounts = new Map<string, number>();
+  const nextWorkflowBoundaryReplayKey = (name: string): string => {
+    const next = (workflowBoundaryReplayCounts.get(name) ?? 0) + 1;
+    workflowBoundaryReplayCounts.set(name, next);
+    return `workflow:${name}:${next}`;
+  };
+  const taskRunners = createWorkflowTaskRunners({ runtime });
+  const workflow = createChildWorkflowRunner({
+    runtime,
+    resolveWorkflowCwd,
+    nextWorkflowBoundaryReplayKey,
+    runWorkflow: run,
+  });
+
+  const ctx: WorkflowRunContext<TInputs> = {
+    inputs: resolvedInputs as TInputs,
+    get cwd() { return resolveWorkflowCwd(); },
+    exit: exit.exit,
+    ui: buildExitGatedUiContext({
+      opts,
+      throwIfWorkflowExitSelected: exit.throwIfWorkflowExitSelected,
+      baseFromPromptNodes: () => buildPromptNodeUiAdapter({
+        runId,
+        activeStore,
+        opts,
+        tracker,
+        replayIndex,
+        signal: ownController.signal,
+        throwIfWorkflowExitSelected: exit.throwIfWorkflowExitSelected,
+        registerWorkflowExitCleanup: exit.registerWorkflowExitCleanup,
+        workflowExitSkippedReason: exit.workflowExitSkippedReason,
+        preserveWorkflowExitSkippedReason: exit.preserveWorkflowExitSkippedReason,
+        classifyExecutorFailure,
+      }),
+    }),
+    stage: runtime.stage,
+    task: taskRunners.task,
+    chain: taskRunners.chain,
+    parallel: taskRunners.parallel,
+    workflow,
+  };
+
+  try {
+    if (opts.deferWorkflowStart === true) {
+      await nextEventLoopTurn();
+      if (ownController.signal.aborted) {
+        const selectedExit = findWorkflowExitSignal(ownController.signal.reason, exitScope);
+        if (selectedExit !== undefined) return await finalizers.finalizeWorkflowExit(selectedExit);
+        const parentExit = parentWorkflowExitAbortReason(ownController.signal.reason);
+        if (parentExit !== undefined) return await finalizers.finalizeParentWorkflowExitCancellation(parentExit);
+        return finalizeKilled(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd);
+      }
+    }
+
+    const rawResult = await def.run(ctx);
+    if (ownController.signal.aborted) {
+      const selectedExit = findWorkflowExitSignal(ownController.signal.reason, exitScope);
+      if (selectedExit !== undefined) return await finalizers.finalizeWorkflowExit(selectedExit);
+      const parentExit = parentWorkflowExitAbortReason(ownController.signal.reason);
+      if (parentExit !== undefined) return await finalizers.finalizeParentWorkflowExitCancellation(parentExit);
+      return finalizeKilled(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd);
+    }
+
+    const result = normalizeWorkflowRunOutput(def.name, rawResult);
+    assertWorkflowRunOutputs(def.name, result, def.outputs);
+    assertWorkflowCreatedStage(runSnapshot);
+    const recorded = activeStore.recordRunEnd(runId, "completed", result);
+    appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: "completed", result, ts: Date.now() });
+    return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "completed", result }, opts.onRunEnd);
+  } catch (err) {
+    const selectedExit = findWorkflowExitSignal(err, exitScope) ?? findWorkflowExitSignal(ownController.signal.reason, exitScope);
+    if (selectedExit !== undefined) return await finalizers.finalizeWorkflowExit(selectedExit);
+
+    if (ownController.signal.aborted) {
+      const parentExit = parentWorkflowExitAbortReason(ownController.signal.reason);
+      if (parentExit !== undefined) return await finalizers.finalizeParentWorkflowExitCancellation(parentExit);
+      return finalizeKilled(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd);
+    }
+
+    const failure = classifyExecutorFailure(err);
+    const metadata = selectRunFailureDisposition({
+      outerFailure: failure,
+      thrownError: err,
+      stages: runSnapshot.stages,
+      classifyFailure: classifyExecutorFailure,
+    });
+
+    if (metadata.failureDisposition === "terminal_killed") {
+      for (const failedStageId of metadata.failedStageIds) scheduler.blockKnownNonTerminalDescendants(failedStageId);
+      return finalizeKilledByFailure(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd, { ...metadata, resumable: false });
+    }
+
+    if (metadata.failureDisposition === "active_blocked" && metadata.failedStageId !== undefined && metadata.failureRecoverability === "recoverable") {
+      for (const failedStageId of metadata.failedStageIds) scheduler.blockKnownNonTerminalDescendants(failedStageId);
+      return recordActiveBlockedFailure(runId, runSnapshot, activeStore, opts.persistence, {
+        ...metadata,
+        failureRecoverability: "recoverable",
+        failedStageId: metadata.failedStageId,
+        resumable: true,
+      });
+    }
+
+    const recorded = activeStore.recordRunEnd(runId, "failed", undefined, metadata.errorMessage, metadata);
+    appendRunEndWhenRecorded(opts.persistence, recorded, {
+      runId,
+      status: "failed",
+      error: metadata.errorMessage,
+      failureKind: metadata.failureKind,
+      ...(metadata.failureCode !== undefined ? { failureCode: metadata.failureCode } : {}),
+      ...(metadata.failureRecoverability !== undefined ? { failureRecoverability: metadata.failureRecoverability } : {}),
+      ...(metadata.failureDisposition !== undefined ? { failureDisposition: metadata.failureDisposition } : {}),
+      failureMessage: metadata.failureMessage,
+      ...(metadata.failedStageId !== undefined ? { failedStageId: metadata.failedStageId } : {}),
+      resumable: metadata.resumable,
+      ...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
+      ts: Date.now(),
+    });
+    return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "failed", error: metadata.errorMessage }, opts.onRunEnd);
+  } finally {
+    opts.cancellation?.unregister(runId);
+  }
+}

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

@@ -0,0 +1,160 @@
+import type { RunSnapshot } from "../shared/store-types.js";
+import type { Store } from "../shared/store.js";
+import type { StageOptions } from "../shared/types.js";
+import type { ConcurrencyLimiter } from "../runs/shared/concurrency.js";
+import type { ParallelFailFastScope } from "../runs/foreground/executor-types.js";
+import type { WorkflowExitManager } from "../runs/foreground/executor-exit-manager.js";
+import type { ContinuationReplayIndex } from "../runs/foreground/executor-continuation.js";
+import type { StageScheduler } from "../runs/foreground/executor-scheduler.js";
+import type { StageControlRegistry } from "../runs/foreground/stage-control-registry.js";
+import type { StageAdapters } from "../runs/foreground/stage-runner.js";
+import type { LiveStageRuntime, StageMcpScope, StageContextWithMeta } from "../runs/foreground/executor-stage-types.js";
+import { createWorkflowStageFactory } from "../runs/foreground/executor-stage-factory.js";
+import { createWorkflowBoundaryFactory, type WorkflowBoundaryStage } from "../runs/foreground/executor-child-boundary.js";
+import type { GraphFrontierTracker } from "./graph-inference.js";
+import type { EngineChildRunOptions, EngineStageRuntimeOptions, EngineWorkflowBoundaryOptions } from "./options.js";
+
+export interface EngineRuntimeInput {
+  readonly runId: string;
+  readonly depth: number;
+  readonly runSnapshot: RunSnapshot;
+  readonly activeStore: Store;
+  readonly stageOptions: EngineStageRuntimeOptions;
+  readonly workflowBoundaryOptions: EngineWorkflowBoundaryOptions;
+  readonly childRunOptions: EngineChildRunOptions;
+  readonly parentRootRunId?: string;
+  readonly adapters: StageAdapters;
+  readonly signal: AbortSignal;
+  readonly tracker: GraphFrontierTracker;
+  readonly scheduler: StageScheduler;
+  readonly replayIndex: ContinuationReplayIndex;
+  readonly limiter: ConcurrencyLimiter;
+  readonly inputRuntimeDefaults: Partial<StageOptions>;
+  readonly workflowInvocationCwd: string;
+  readonly stageRegistry: StageControlRegistry;
+  readonly exit: WorkflowExitManager;
+  readonly classifyExecutorFailure: LiveStageRuntime["classifyExecutorFailure"];
+}
+
+export interface EngineSpawnAgentStageOptions {
+  readonly kind?: "agent";
+  readonly options?: StageOptions;
+  readonly failFastScope?: ParallelFailFastScope;
+}
+
+export interface EngineSpawnWorkflowBoundaryOptions {
+  readonly kind: "workflow-boundary";
+  readonly replayKey: string;
+}
+
+export type EngineSpawnStageOptions = EngineSpawnAgentStageOptions | EngineSpawnWorkflowBoundaryOptions;
+
+export interface EngineAgentStageHandle {
+  readonly kind: "agent";
+  readonly context: StageContextWithMeta;
+}
+
+export interface EngineWorkflowBoundaryHandle {
+  readonly kind: "workflow-boundary";
+  readonly boundary: WorkflowBoundaryStage;
+}
+
+export type StageHandle = EngineAgentStageHandle | EngineWorkflowBoundaryHandle;
+
+export class EngineRuntime {
+  readonly runId: string;
+  readonly depth: number;
+  readonly activeStore: Store;
+  readonly childRunOptions: EngineChildRunOptions;
+  readonly parentRootRunId?: string;
+  readonly adapters: StageAdapters;
+  readonly signal: AbortSignal;
+  readonly tracker: GraphFrontierTracker;
+  readonly exit: WorkflowExitManager;
+  readonly inputRuntimeDefaults: Partial<StageOptions>;
+  readonly workflowInvocationCwd: string;
+
+  private readonly spawnAgentStage: (
+    name: string,
+    options?: StageOptions,
+    stageFailFastScope?: ParallelFailFastScope,
+  ) => StageContextWithMeta;
+  private readonly spawnWorkflowBoundary: (name: string, replayKey: string) => WorkflowBoundaryStage;
+
+  constructor(input: EngineRuntimeInput) {
+    this.runId = input.runId;
+    this.depth = input.depth;
+    this.activeStore = input.activeStore;
+    this.childRunOptions = input.childRunOptions;
+    this.parentRootRunId = input.parentRootRunId;
+    this.adapters = input.adapters;
+    this.signal = input.signal;
+    this.tracker = input.tracker;
+    this.exit = input.exit;
+    this.inputRuntimeDefaults = input.inputRuntimeDefaults;
+    this.workflowInvocationCwd = input.workflowInvocationCwd;
+
+    // The runtime only wires host-injected ports; stage sessions are still
+    // created lazily by the stage runner through input.adapters.agentSession.
+    this.spawnAgentStage = createWorkflowStageFactory({
+      runId: input.runId,
+      activeStore: input.activeStore,
+      opts: input.stageOptions,
+      adapters: input.adapters,
+      signal: input.signal,
+      tracker: input.tracker,
+      scheduler: input.scheduler,
+      replayIndex: input.replayIndex,
+      limiter: input.limiter,
+      inputRuntimeDefaults: input.inputRuntimeDefaults,
+      workflowInvocationCwd: input.workflowInvocationCwd,
+      stageRegistry: input.stageRegistry,
+      exit: input.exit,
+      classifyExecutorFailure: input.classifyExecutorFailure,
+      createMcpScope: (stageId, options) => this.createMcpScope(stageId, options),
+    });
+    this.spawnWorkflowBoundary = createWorkflowBoundaryFactory({
+      runId: input.runId,
+      runSnapshot: input.runSnapshot,
+      activeStore: input.activeStore,
+      opts: input.workflowBoundaryOptions,
+      tracker: input.tracker,
+      replayIndex: input.replayIndex,
+      registerWorkflowExitCleanup: input.exit.registerWorkflowExitCleanup,
+      workflowExitSkippedReason: input.exit.workflowExitSkippedReason,
+      classifyExecutorFailure: input.classifyExecutorFailure,
+    });
+  }
+
+  spawnStage(name: string, opts: EngineSpawnWorkflowBoundaryOptions): EngineWorkflowBoundaryHandle;
+  spawnStage(name: string, opts?: EngineSpawnAgentStageOptions): EngineAgentStageHandle;
+  spawnStage(name: string, opts: EngineSpawnStageOptions = {}): StageHandle {
+    if (opts.kind === "workflow-boundary") {
+      return { kind: "workflow-boundary", boundary: this.spawnWorkflowBoundary(name, opts.replayKey) };
+    }
+    return { kind: "agent", context: this.spawnAgentStage(name, opts.options, opts.failFastScope) };
+  }
+
+  readonly stage = (name: string, options?: StageOptions, failFastScope?: ParallelFailFastScope): StageContextWithMeta => {
+    const handle = this.spawnStage(name, {
+      kind: "agent",
+      ...(options !== undefined ? { options } : {}),
+      ...(failFastScope !== undefined ? { failFastScope } : {}),
+    });
+    return handle.context;
+  };
+
+  private createMcpScope(stageId: string, options: StageOptions | undefined): StageMcpScope {
+    const allow = options?.mcp?.allow ?? null;
+    const deny = options?.mcp?.deny ?? null;
+    const hasScope = allow !== null || deny !== null;
+    return {
+      apply: () => {
+        if (this.childRunOptions.mcp && hasScope) this.childRunOptions.mcp.setScope(stageId, allow, deny);
+      },
+      clear: () => {
+        if (this.childRunOptions.mcp && hasScope) this.childRunOptions.mcp.clearScope(stageId);
+      },
+    };
+  }
+}