@bastani/atomic 0.9.0-alpha.1 → 0.9.0-alpha.3

package/dist/builtin/workflows/src/runs/foreground/executor-run.ts

@@ -1,359 +1 @@
-import type { RunSnapshot } from "../../shared/store-types.js";
-import type {
-  WorkflowDefinition,
-  WorkflowInputValues,
-  WorkflowCustomUiFactory,
-  WorkflowCustomUiOptions,
-  WorkflowRunContext,
-  WorkflowUIContext,
-} 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 "../shared/graph-inference.js";
-import { createRunLimiter } from "../shared/concurrency.js";
-import { stageControlRegistry as defaultStageControlRegistry } from "./stage-control-registry.js";
-import type { RunOpts, RunResult } from "./executor-types.js";
-import { unknownErrorMessage, findWorkflowExitSignal, parentWorkflowExitAbortReason } from "./executor-abort.js";
-import { createWorkflowExitManager } from "./executor-exit-manager.js";
-import { resolveAndValidateInputs, resolveInputConcurrency, resolveInputRuntimeDefaults } from "./executor-inputs.js";
-import { workflowCwdWithInputWorktree } from "./executor-direct-helpers.js";
-import { createStageScheduler } from "./executor-scheduler.js";
-import { createRunFinalizers } from "./executor-run-finalizers.js";
-import { createWorkflowBoundaryFactory } from "./executor-child-boundary.js";
-import { createWorkflowStageFactory } from "./executor-stage-factory.js";
-import { createWorkflowTaskRunners } from "./executor-task-context.js";
-import { createChildWorkflowRunner } from "./executor-child-workflow.js";
-import { createContinuationReplayIndex } from "./executor-continuation.js";
-import { buildPromptNodeUiAdapter } from "./executor-prompt-nodes.js";
-import { makeHeadlessUnavailableUIContext, normalizeUIContext } from "./executor-hil.js";
-import {
-  appendRunEndWhenRecorded,
-  assertWorkflowCreatedStage,
-  finalizeKilled,
-  finalizeKilledByFailure,
-  recordActiveBlockedFailure,
-  reconcileTerminalRunResult,
-  selectRunFailureDisposition,
-} from "./executor-lifecycle.js";
-import { assertWorkflowRunOutputs, normalizeWorkflowRunOutput } from "./executor-outputs.js";
-import { isWorkflowDefinition, workflowDefinitionRequirementMessage } from "./executor-child-helpers.js";
-
-function nextEventLoopTurn(): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, 0));
-}
-
-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);
-    },
-  };
-}
-
-export async function run<TInputs extends WorkflowInputValues>(
-  def: WorkflowDefinition<TInputs>,
-  inputs: Readonly<Record<string, unknown>>,
-  opts: RunOpts = {},
-): Promise<RunResult> {
-  if (!isWorkflowDefinition(def)) throw new Error(workflowDefinitionRequirementMessage("run(definition, inputs)", def));
-
-  const activeStore = opts.store ?? defaultStore;
-  const adapters = opts.adapters ?? {};
-  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 startWorkflowBoundaryStage = createWorkflowBoundaryFactory({
-    runId,
-    runSnapshot,
-    activeStore,
-    opts,
-    tracker,
-    replayIndex,
-    registerWorkflowExitCleanup: exit.registerWorkflowExitCleanup,
-    workflowExitSkippedReason: exit.workflowExitSkippedReason,
-    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 stage = createWorkflowStageFactory({
-    runId,
-    activeStore,
-    opts,
-    adapters,
-    signal: ownController.signal,
-    tracker,
-    scheduler,
-    replayIndex,
-    limiter,
-    inputRuntimeDefaults,
-    workflowInvocationCwd,
-    stageRegistry,
-    exit,
-    classifyExecutorFailure,
-  });
-  const taskRunners = createWorkflowTaskRunners({
-    runId,
-    exit,
-    tracker,
-    inputRuntimeDefaults,
-    workflowInvocationCwd,
-    stage,
-  });
-  const workflow = createChildWorkflowRunner({
-    runId,
-    depth,
-    opts,
-    exit,
-    ownController,
-    resolveWorkflowCwd,
-    nextWorkflowBoundaryReplayKey,
-    startWorkflowBoundaryStage,
-    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,
-    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);
-  }
-}
+export { run } from "../../engine/run.js";

package/dist/builtin/workflows/src/runs/foreground/executor-scheduler.ts

@@ -1,6 +1,6 @@
 import type { RunSnapshot, StageSnapshot } from "../../shared/store-types.js";
 import type { Store } from "../../shared/store.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
 import type { StageControlRegistry } from "./stage-control-registry.js";
 
 interface ReleaseBarrier {

package/dist/builtin/workflows/src/runs/foreground/executor-stage-call.ts

@@ -112,10 +112,7 @@ export function createTrackedStageCaller(input: {
     runtime.activeStore.recordStageStart(runtime.runId, runtime.stageSnapshot);
     runtime.appendStageStartOnce();
 
-    const mcpAllow = input.options?.mcp?.allow ?? null;
-    const mcpDeny = input.options?.mcp?.deny ?? null;
-    const hasMcpScope = mcpAllow !== null || mcpDeny !== null;
-    if (runtime.opts.mcp && hasMcpScope) runtime.opts.mcp.setScope(runtime.stageId, mcpAllow, mcpDeny);
+    runtime.mcpScope.apply();
 
     try {
       const abortSession = (): void => {
@@ -183,7 +180,7 @@ export function createTrackedStageCaller(input: {
       }
       throw err;
     } finally {
-      if (runtime.opts.mcp && hasMcpScope) runtime.opts.mcp.clearScope(runtime.stageId);
+      runtime.mcpScope.clear();
       runtime.captureStageSessionMeta();
       runtime.finalizeStageSnapshot();
       if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {

package/dist/builtin/workflows/src/runs/foreground/executor-stage-factory.ts

@@ -7,10 +7,11 @@ import { appendStageEnd, appendStageStart } from "../../shared/persistence-sessi
 import { elapsedStageMs } from "../../shared/timing.js";
 import type { WorkflowFailure } from "../../shared/workflow-failures.js";
 import type { ConcurrencyLimiter } from "../shared/concurrency.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
+import type { EngineStageRuntimeOptions } from "../../engine/options.js";
 import { createStageContext as createInnerStageContext, type InternalStageContext, type StageAdapters } from "./stage-runner.js";
 import type { StageControlRegistry } from "./stage-control-registry.js";
-import type { RunOpts, ParallelFailFastScope } from "./executor-types.js";
+import type { ParallelFailFastScope } from "./executor-types.js";
 import type { WorkflowExitManager } from "./executor-exit-manager.js";
 import type { ContinuationReplayIndex } from "./executor-continuation.js";
 import { sameStringSet } from "./executor-continuation.js";
@@ -19,7 +20,7 @@ import { isTerminalStage } from "./executor-scheduler.js";
 import { stageReplayFields } from "./executor-lifecycle.js";
 import { askUserQuestionToolEvent, toolResultHasChatAnswer } from "./executor-hil.js";
 import { createReplayStageContext } from "./executor-stage-replay.js";
-import type { LiveStageMutableState, LiveStageRuntime, StageContextWithMeta } from "./executor-stage-types.js";
+import type { LiveStageMutableState, LiveStageRuntime, StageContextWithMeta, StageMcpScope } from "./executor-stage-types.js";
 import { createStageControlHandle } from "./executor-stage-control.js";
 import { createTrackedStageCaller } from "./executor-stage-call.js";
 import { createStageContext } from "./executor-stage-context.js";
@@ -28,7 +29,7 @@ import { stageOptionsWithGitWorktree, stageOptionsWithInputDefaults } from "./ex
 export function createWorkflowStageFactory(input: {
   readonly runId: string;
   readonly activeStore: Store;
-  readonly opts: RunOpts;
+  readonly opts: EngineStageRuntimeOptions;
   readonly adapters: StageAdapters;
   readonly signal: AbortSignal;
   readonly tracker: GraphFrontierTracker;
@@ -40,6 +41,7 @@ export function createWorkflowStageFactory(input: {
   readonly stageRegistry: StageControlRegistry;
   readonly exit: WorkflowExitManager;
   readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
+  readonly createMcpScope: (stageId: string, options: StageOptions | undefined) => StageMcpScope;
 }): (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope) => StageContextWithMeta {
   return (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope): StageContextWithMeta => {
     input.exit.throwIfWorkflowExitSelected();
@@ -287,6 +289,7 @@ export function createWorkflowStageFactory(input: {
       signal: input.signal,
       exit: input.exit,
       classifyExecutorFailure: input.classifyExecutorFailure,
+      mcpScope: input.createMcpScope(stageId, options),
       ...(stageFailFastScope !== undefined ? { stageFailFastScope } : {}),
       state,
       unregisterStageHandle: () => {},
@@ -317,6 +320,11 @@ export function createWorkflowStageFactory(input: {
     const blockedBy = input.scheduler.blockingAncestorFor(stageSnapshot);
     if (blockedBy !== undefined) input.scheduler.blockStageUntilCascadeRelease(stageSnapshot, blockedBy);
 
+    // Parallel fail-fast and workflow-exit cleanup can both target a live stage.
+    // The first terminal path owns the snapshot: finalization unregisters
+    // workflow-exit cleanup and removes the stage from the fail-fast active set.
+    // Later paths must not overwrite the terminal skippedReason; they only abort
+    // and release idempotent live handles.
     const skipForParallelFailFast = (): void => {
       if (isTerminalStage(stageSnapshot)) return;
       markSkippedForParallelFailFast();

package/dist/builtin/workflows/src/runs/foreground/executor-stage-replay.ts

@@ -2,9 +2,10 @@ import type { StageSnapshot } from "../../shared/store-types.js";
 import type { Store } from "../../shared/store.js";
 import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
 import { elapsedStageMs } from "../../shared/timing.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
+import type { EngineStageRuntimeOptions } from "../../engine/options.js";
 import type { InternalStageContext } from "./stage-runner.js";
-import type { RunOpts, WorkflowExitCleanup } from "./executor-types.js";
+import type { WorkflowExitCleanup } from "./executor-types.js";
 import { stageReplayFields } from "./executor-lifecycle.js";
 
 export function createReplayStageContext(input: {
@@ -14,7 +15,7 @@ export function createReplayStageContext(input: {
   readonly stageSnapshot: StageSnapshot;
   readonly replaySource: StageSnapshot;
   readonly activeStore: Store;
-  readonly opts: RunOpts;
+  readonly opts: EngineStageRuntimeOptions;
   readonly tracker: GraphFrontierTracker;
   readonly registerWorkflowExitCleanup: (stageId: string, cleanup: WorkflowExitCleanup) => () => void;
   readonly workflowExitSkippedReason: (reason?: string) => string;

package/dist/builtin/workflows/src/runs/foreground/executor-stage-types.ts

@@ -3,10 +3,16 @@ import type { Store } from "../../shared/store.js";
 import type { StageContext } from "../../shared/types.js";
 import type { InternalStageContext } from "./stage-runner.js";
 import type { StageControlRegistry } from "./stage-control-registry.js";
-import type { RunOpts, ParallelFailFastScope } from "./executor-types.js";
+import type { ParallelFailFastScope } from "./executor-types.js";
 import type { StageScheduler } from "./executor-scheduler.js";
 import type { WorkflowExitManager } from "./executor-exit-manager.js";
 import type { WorkflowFailure } from "../../shared/workflow-failures.js";
+import type { EngineStageRuntimeOptions } from "../../engine/options.js";
+
+export interface StageMcpScope {
+  apply(): void;
+  clear(): void;
+}
 
 export interface LiveStageMutableState {
   activeAskUserQuestionAnonymousCalls: number;
@@ -27,12 +33,13 @@ export interface LiveStageRuntime {
   readonly stageSnapshot: StageSnapshot;
   readonly innerCtx: InternalStageContext;
   readonly activeStore: Store;
-  readonly opts: RunOpts;
+  readonly opts: EngineStageRuntimeOptions;
   readonly stageRegistry: StageControlRegistry;
   readonly scheduler: StageScheduler;
   readonly signal: AbortSignal;
   readonly exit: WorkflowExitManager;
   readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
+  readonly mcpScope: StageMcpScope;
   readonly stageFailFastScope?: ParallelFailFastScope;
   readonly state: LiveStageMutableState;
   unregisterStageHandle: () => void;

package/dist/builtin/workflows/src/runs/foreground/executor-task-context.ts

@@ -1,132 +1,2 @@
-import type { StageContext, StageOptions, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep, WorkflowChainOptions, WorkflowParallelOptions } from "../../shared/types.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
-import type { WorkflowExitManager } from "./executor-exit-manager.js";
-import type { ParallelFailFastScope, ParallelFailFastStage } from "./executor-types.js";
-import { findWorkflowExitSignal } from "./executor-abort.js";
-import {
-  applyTaskContext,
-  chainStepPrompt,
-  parallelFallbackTask,
-  replaceTaskPlaceholder,
-  structuredTaskOutputText,
-  taskOptionsFromStep,
-  taskPrevious,
-  taskPrompt,
-  taskPromptOptions,
-  taskReadInstruction,
-  taskStageOptions,
-  taskWithSharedDefaults,
-  truncateTaskOutput,
-} from "./executor-task-prompts.js";
-import { cleanupPreparedWorktrees, collectWorktreeDiffs, mapParallelSteps, prepareDirectWorktrees, stageOptionsWithGitWorktree, stageOptionsWithInputDefaults } from "./executor-direct-helpers.js";
-import type { InternalStageContext } from "./stage-runner.js";
-
-export interface WorkflowTaskRunners {
-  task(name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope): Promise<WorkflowTaskResult>;
-  chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
-  parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
-}
-
-export function createWorkflowTaskRunners(input: {
-  readonly runId: string;
-  readonly exit: WorkflowExitManager;
-  readonly tracker: GraphFrontierTracker;
-  readonly inputRuntimeDefaults: Partial<StageOptions>;
-  readonly workflowInvocationCwd: string;
-  readonly stage: (name: string, options?: StageOptions, scope?: ParallelFailFastScope) => StageContext;
-}): WorkflowTaskRunners {
-  const task = async (name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope): Promise<WorkflowTaskResult> => {
-    input.exit.throwIfWorkflowExitSelected();
-    const runTaskOnce = async (taskOptions: WorkflowTaskOptions): Promise<WorkflowTaskResult> => {
-      input.exit.throwIfWorkflowExitSelected();
-      const resolvedTaskOptions = stageOptionsWithGitWorktree(stageOptionsWithInputDefaults(taskOptions, input.inputRuntimeDefaults), input.workflowInvocationCwd) ?? taskOptions;
-      const stage = input.stage(name, taskStageOptions(resolvedTaskOptions), stageFailFastScope);
-      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 as InternalStageContext).__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 },
-      `${input.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);
-    }
-  };
-
-  const chain = async (steps: readonly WorkflowTaskStep[], options: WorkflowChainOptions = {}): Promise<WorkflowTaskResult[]> => {
-    input.exit.throwIfWorkflowExitSelected();
-    const results: WorkflowTaskResult[] = [];
-    for (let index = 0; index < steps.length; index += 1) {
-      input.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 task(step.name, taskWithSharedDefaults(taskOptionsFromStep(step, prompt, previous), options)));
-    }
-    return results;
-  };
-
-  const parallel = async (steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions = {}): Promise<WorkflowTaskResult[]> => {
-    input.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.tracker.currentParents()),
-    };
-    return mapParallelSteps(steps, options.concurrency, options.failFast, async (step) => {
-      input.exit.throwIfWorkflowExitSelected();
-      const prompt = replaceTaskPlaceholder(step.prompt ?? step.task ?? fallback, options.task ?? fallback);
-      return await 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.exit.throwIfWorkflowExitSelected,
-      beforeMap: input.exit.throwIfWorkflowExitSelected,
-      isControlSignal: (error) => findWorkflowExitSignal(error, input.exit.exitScope) !== undefined,
-    });
-  };
-
-  return { task, chain, parallel };
-}
+export { createWorkflowTaskRunners } from "../../engine/primitives/task.js";
+export type { WorkflowTaskRunners } from "../../engine/primitives/task.js";

package/dist/builtin/workflows/src/runs/foreground/executor-types.ts

@@ -82,10 +82,10 @@ export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "s
   onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
 }
 
-export interface RunResult {
+export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> {
   readonly runId: string;
   readonly status: RunStatus;
-  readonly result?: WorkflowOutputValues;
+  readonly result?: Partial<TOutputs>;
   readonly error?: string;
   /** True when the run reached its terminal status through ctx.exit(). */
   readonly exited?: boolean;