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

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);
+      },
+    };
+  }
+}

package/dist/builtin/workflows/src/extension/workflow-module-loader.ts

@@ -7,8 +7,9 @@
  */
 
 import { createJiti } from "jiti/static";
+import * as typeboxModule from "typebox";
 import * as workflowsSdkSurface from "../sdk-surface.js";
-import { isBrandedWorkflowDefinition } from "../workflows/define-workflow.js";
+import { isBrandedWorkflowDefinition } from "../authoring/workflow.js";
 import deepResearchCodebase from "../../builtin/deep-research-codebase.js";
 import goal from "../../builtin/goal.js";
 import openClaudeDesign from "../../builtin/open-claude-design.js";
@@ -16,6 +17,7 @@ import ralph from "../../builtin/ralph.js";
 
 const WORKFLOWS_MODULE_SPECIFIER = "@bastani/workflows";
 const WORKFLOWS_BUILTIN_MODULE_SPECIFIER = `${WORKFLOWS_MODULE_SPECIFIER}/builtin`;
+const TYPEBOX_MODULE_SPECIFIER = "typebox";
 // Keep this in sync with index.ts through sdk-surface.ts.
 const WORKFLOWS_SDK_MODULE: Record<string, unknown> = {
   ...workflowsSdkSurface,
@@ -26,9 +28,13 @@ const WORKFLOWS_BUILTIN_MODULE: Record<string, unknown> = {
   openClaudeDesign,
   ralph,
 };
+const TYPEBOX_MODULE: Record<string, unknown> = {
+  ...typeboxModule,
+};
 const WORKFLOWS_VIRTUAL_MODULES: Record<string, unknown> = {
   [WORKFLOWS_MODULE_SPECIFIER]: WORKFLOWS_SDK_MODULE,
   [WORKFLOWS_BUILTIN_MODULE_SPECIFIER]: WORKFLOWS_BUILTIN_MODULE,
+  [TYPEBOX_MODULE_SPECIFIER]: TYPEBOX_MODULE,
   [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/deep-research-codebase`]: { default: deepResearchCodebase },
   [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/goal`]: { default: goal },
   [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/open-claude-design`]: { default: openClaudeDesign },
@@ -95,10 +101,10 @@ export function validateWorkflowDefinitionShape(value: unknown): string | null {
   const d = value as Record<string, unknown>;
 
   if (d["__piWorkflow"] !== true) {
-    return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from defineWorkflow(...).compile()";
+    return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from workflow({...})";
   }
   if (!isBrandedWorkflowDefinition(value)) {
-    return "workflow definition is not produced by defineWorkflow(...).compile(); hand-rolled __piWorkflow objects are not supported";
+    return "workflow definition is not produced by workflow({...}); hand-rolled __piWorkflow objects are not supported";
   }
   if (typeof d["name"] !== "string" || (d["name"] as string).trim().length === 0) {
     return "name must be a non-empty string";

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -43,23 +43,6 @@ const JsonSchemaObject = Type.Unsafe<Record<string, unknown>>({
   description: "Plain JSON Schema used as final-answer tool arguments for this workflow item.",
 });
 
-const BashCommandRuleSchema = Type.Union([
-  Type.String(),
-  Type.Object({ prefix: Type.String() }, { additionalProperties: false }),
-  Type.Object({ glob: Type.String() }, { additionalProperties: false }),
-  Type.Object({
-    regex: Type.String(),
-    flags: Type.Optional(Type.String()),
-  }, { additionalProperties: false }),
-]);
-
-const BashCommandPolicySchema = Type.Object({
-  default: Type.Optional(Type.Union([Type.Literal("allow"), Type.Literal("deny")])),
-  allow: Type.Optional(Type.Array(BashCommandRuleSchema)),
-  deny: Type.Optional(Type.Array(BashCommandRuleSchema)),
-  match: Type.Optional(Type.Union([Type.Literal("whole"), Type.Literal("segments")])),
-}, { additionalProperties: false });
-
 const StageSessionOptionProperties = {
   schema: Type.Optional(JsonSchemaObject),
   cwd: Type.Optional(Type.String()),
@@ -76,7 +59,6 @@ const StageSessionOptionProperties = {
   })),
   tools: Type.Optional(Type.Array(Type.String())),
   customTools: Type.Optional(Type.Array(SdkSessionOptionArrayElementSchema("customTools"))),
-  bashPolicy: Type.Optional(BashCommandPolicySchema),
   resourceLoader: Type.Optional(SdkSessionOptionSchema("resourceLoader")),
   sessionManager: Type.Optional(SdkSessionOptionSchema("sessionManager")),
   settingsManager: Type.Optional(SdkSessionOptionSchema("settingsManager")),

package/dist/builtin/workflows/src/index.ts

@@ -6,5 +6,3 @@
 // Add new non-cyclic public runtime exports to sdk-surface.ts so the Bun
 // virtual SDK used by workflow discovery stays in lockstep with this entry.
 export * from "./sdk-surface.js";
-
-// Note: `Type` / `Static` / `TSchema` are re-exported via ./sdk-surface.js.

package/dist/builtin/workflows/src/runs/background/runner.ts

@@ -14,7 +14,7 @@
  * cross-ref: spec detached-runner
  */
 
-import type { WorkflowDefinition, WorkflowExecutionMode, WorkflowInputValues } from "../../shared/types.js";
+import type { WorkflowDefinition, WorkflowExecutionMode, WorkflowInputValues, WorkflowOutputValues } from "../../shared/types.js";
 import type { RunOpts, RunResult } from "../foreground/executor.js";
 import type { CancellationRegistry } from "./cancellation-registry.js";
 import type { JobTracker } from "./job-tracker.js";
@@ -85,8 +85,11 @@ export function buildDetachedAccepted(
  * the store remains source of truth for run status. Cancellation is wired
  * through the provided (or default) CancellationRegistry.
  */
-export function runDetached<TInputs extends WorkflowInputValues>(
-  def: WorkflowDefinition<TInputs>,
+export function runDetached<
+  TInputs extends WorkflowInputValues,
+  TRunInputs extends WorkflowInputValues = TInputs,
+>(
+  def: WorkflowDefinition<TInputs, WorkflowOutputValues, TRunInputs>,
   inputs: Readonly<Record<string, unknown>>,
   opts: DetachedRunOpts = {},
 ): DetachedAccepted {

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

@@ -4,12 +4,12 @@ import type { WorkflowChildResult } from "../../shared/types.js";
 import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
 import { elapsedStageMs } from "../../shared/timing.js";
 import type { WorkflowFailure } from "../../shared/workflow-failures.js";
-import type { RunOpts } from "./executor-types.js";
+import type { EngineWorkflowBoundaryOptions } from "../../engine/options.js";
 import type { ContinuationReplayIndex } from "./executor-continuation.js";
 import { sameStringSet } from "./executor-continuation.js";
 import { applyFailureToStage, stageReplayFields } from "./executor-lifecycle.js";
 import { cloneWorkflowChildReplaySnapshot, cloneWorkflowChildValue } from "./executor-child-helpers.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
 import type { WorkflowExitCleanup } from "./executor-types.js";
 import { makeParentWorkflowExitAbortReason } from "./executor-abort.js";
 
@@ -71,7 +71,7 @@ export function createWorkflowBoundaryFactory(input: {
   readonly runId: string;
   readonly runSnapshot: RunSnapshot;
   readonly activeStore: Store;
-  readonly opts: RunOpts;
+  readonly opts: EngineWorkflowBoundaryOptions;
   readonly tracker: GraphFrontierTracker;
   readonly replayIndex: ContinuationReplayIndex;
   readonly registerWorkflowExitCleanup: (stageId: string, cleanup: WorkflowExitCleanup) => () => void;

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

@@ -1,4 +1,4 @@
-import { isBrandedWorkflowDefinition } from "../../workflows/define-workflow.js";
+import { isBrandedWorkflowDefinition } from "../../authoring/workflow.js";
 import type {
   WorkflowChildResult,
   WorkflowDefinition,
@@ -16,7 +16,7 @@ function workflowChildSerializationMessage(err: unknown): string {
 }
 
 export function isWorkflowDefinition(value: unknown): value is WorkflowDefinition {
-  if (!isBrandedWorkflowDefinition(value)) return false;
+  if (value === null || typeof value !== "object" || !isBrandedWorkflowDefinition(value)) return false;
   const record = value as Partial<WorkflowDefinition>;
   return record.__piWorkflow === true &&
     typeof record.name === "string" && record.name.trim().length > 0 &&
@@ -27,9 +27,9 @@ export function isWorkflowDefinition(value: unknown): value is WorkflowDefinitio
 
 export function workflowDefinitionRequirementMessage(callSite: string, value: unknown): string {
   if (value !== null && typeof value === "object" && (value as { __piWorkflow?: unknown }).__piWorkflow === true) {
-    return `atomic-workflows: ${callSite} requires a compiled workflow definition produced by defineWorkflow(...).compile(); hand-rolled __piWorkflow objects are not supported`;
+    return `atomic-workflows: ${callSite} requires a workflow definition produced by workflow({...}); hand-rolled __piWorkflow objects are not supported`;
   }
-  return `atomic-workflows: ${callSite} requires a compiled workflow definition`;
+  return `atomic-workflows: ${callSite} requires a workflow definition`;
 }
 
 export function cloneWorkflowChildReplaySnapshot(snapshot: WorkflowChildReplaySnapshot): WorkflowChildReplaySnapshot {