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

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

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

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

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

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

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

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

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

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

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

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";