@multiplier-labs/stepflow 0.3.3 → 0.3.4

package/src/core/orchestrator/plan-resolution.ts

@@ -0,0 +1,140 @@
+/**
+ * Plan resolution — turns ExecuteOptions into the runtime artefacts
+ * the orchestrator needs to start running steps.
+ *
+ * Today the engine has no separate planner module: the "plan" is just the
+ * declarative WorkflowDefinition combined with the optional resume
+ * checkpoint and the supplied input/metadata. This module is the seam
+ * where, in the future, recipe/plan resolution and input validation can
+ * grow without bloating execute-workflow.ts.
+ *
+ * Responsibilities:
+ *   1. Build the WorkflowContext from the run options + checkpoint, with a
+ *      `context.emit` helper that routes through safeEmitEvent.
+ *   2. Set up the workflow-level timeout: returns a handle the caller
+ *      clears in both the success and failure paths, and a getter for
+ *      the WorkflowTimeoutError that fired (so the catch block can
+ *      surface it instead of the abort-derived error).
+ *   3. Compute the initial set of completed-step keys (used by the loop
+ *      to skip steps already done in a previous run).
+ */
+import type {
+  WorkflowDefinition,
+  WorkflowContext,
+  Logger,
+  SpawnChildOptions,
+} from '../types';
+import type { EventTransport } from '../../events/types';
+import { WorkflowTimeoutError } from '../../utils/errors';
+import { createScopedLogger } from '../../utils/logger';
+import { safeEmitEvent } from './persistence';
+
+/**
+ * Inputs needed to resolve a workflow plan + build its execution context.
+ */
+export interface BuildContextOptions {
+  runId: string;
+  definition: WorkflowDefinition;
+  input: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+  events: EventTransport;
+  logger: Logger;
+  abortController: AbortController;
+  spawnChild: (options: SpawnChildOptions) => Promise<string>;
+  /** Existing checkpoint results to preload into context.results. */
+  checkpointResults?: Record<string, unknown>;
+}
+
+/**
+ * Build the WorkflowContext that will be threaded through every step
+ * handler. On resume, preload `context.results` from the checkpoint.
+ */
+export function buildContext(options: BuildContextOptions): WorkflowContext {
+  const {
+    runId,
+    definition,
+    input,
+    metadata,
+    events,
+    logger,
+    abortController,
+    spawnChild,
+    checkpointResults,
+  } = options;
+
+  return {
+    runId,
+    stepId: '', // set per-step by the step-runner before each handler call
+    kind: definition.kind,
+    input,
+    results: checkpointResults ? { ...checkpointResults } : {},
+    metadata,
+    logger: createScopedLogger(logger, runId),
+    signal: abortController.signal,
+    spawnChild,
+    emit: (eventType: string, payload?: unknown) => {
+      safeEmitEvent(events, logger, {
+        runId,
+        kind: definition.kind,
+        eventType,
+        timestamp: new Date(),
+        payload,
+      });
+    },
+  };
+}
+
+/**
+ * Handle returned by setupWorkflowTimeout. The orchestrator must call
+ * `clear()` on both success and failure paths to release the timer, and
+ * may read `getTimeoutError()` in the catch path: if non-null, the abort
+ * was triggered by our timeout (not user cancellation), and the caller
+ * should surface that error instead of the generic abort-derived one.
+ */
+export interface WorkflowTimeoutHandle {
+  clear: () => void;
+  getTimeoutError: () => WorkflowTimeoutError | undefined;
+}
+
+/**
+ * Arm a workflow-level timeout if the definition specifies one.
+ *
+ * On fire: constructs a WorkflowTimeoutError (recoverable via
+ * `getTimeoutError`) and aborts the controller, which causes any
+ * in-flight step handler racing the abort signal to reject.
+ *
+ * If the definition has no timeout, returns no-op handles.
+ */
+export function setupWorkflowTimeout(
+  runId: string,
+  definition: WorkflowDefinition,
+  abortController: AbortController
+): WorkflowTimeoutHandle {
+  if (!definition.timeout) {
+    return {
+      clear: () => {},
+      getTimeoutError: () => undefined,
+    };
+  }
+
+  let timeoutError: WorkflowTimeoutError | undefined;
+  const timeoutId = setTimeout(() => {
+    timeoutError = new WorkflowTimeoutError(runId, definition.timeout!);
+    abortController.abort();
+  }, definition.timeout);
+
+  return {
+    clear: () => clearTimeout(timeoutId),
+    getTimeoutError: () => timeoutError,
+  };
+}
+
+/**
+ * Initial list of step keys to consider already complete — empty for a
+ * fresh run, the checkpoint's set for a resume.
+ */
+export function initialCompletedSteps(
+  checkpoint?: { completedStepKeys: Set<string> }
+): string[] {
+  return checkpoint ? Array.from(checkpoint.completedStepKeys) : [];
+}

package/src/core/orchestrator/state-transitions.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure state-transition decisions for the orchestrator.
+ *
+ * Every function in here is deterministic and side-effect-free: given
+ * the current shape of an event, error, or step config they return what
+ * the next state should be. The orchestrator and step-runner read these
+ * decisions and apply them via persistence helpers.
+ *
+ * State-transition rules captured here:
+ *
+ *   Run terminal status:
+ *     - WorkflowTimeoutError       → status='failed',   eventType='run.timeout'
+ *     - WorkflowCanceledError      → status='canceled', eventType='run.canceled'
+ *     - any other error            → status='failed',   eventType='run.failed'
+ *
+ *   Step error policy resolution (precedence):
+ *     - step.onError                        > definition.defaultOnError > 'fail'
+ *     - step.maxRetries                     > 3
+ *     - step.retryDelay (ms)                > 1000
+ *     - step.retryBackoff (multiplier)      > 2
+ *
+ *   Step retry decision (after a non-cancellation failure):
+ *     - onError === 'skip'                            → 'skip'
+ *     - onError === 'retry' && attempt <= maxRetries  → 'retry'
+ *     - otherwise (incl. retries exhausted, 'fail')   → 'fail'
+ */
+import type { WorkflowDefinition, WorkflowStep } from '../types';
+import { WorkflowCanceledError, WorkflowTimeoutError } from '../../utils/errors';
+
+/**
+ * Storage-level statuses the orchestrator may persist for a non-success run.
+ */
+export type RunFinalStatus = 'failed' | 'canceled';
+
+/**
+ * Event types emitted on a non-success run completion.
+ */
+export type RunFinalEventType = 'run.timeout' | 'run.canceled' | 'run.failed';
+
+/**
+ * Result of mapping an error to a terminal run state.
+ */
+export interface RunFinalDecision {
+  status: RunFinalStatus;
+  eventType: RunFinalEventType;
+}
+
+/**
+ * Map a thrown workflow error to the final run status + event type.
+ * Note: a workflow timeout is persisted as `failed` for storage compatibility,
+ * but the emitted event distinguishes it via `run.timeout`.
+ */
+export function decideRunFinalState(error: unknown): RunFinalDecision {
+  if (error instanceof WorkflowTimeoutError) {
+    return { status: 'failed', eventType: 'run.timeout' };
+  }
+  if (error instanceof WorkflowCanceledError) {
+    return { status: 'canceled', eventType: 'run.canceled' };
+  }
+  return { status: 'failed', eventType: 'run.failed' };
+}
+
+/**
+ * Step-level error policy resolved from a step + workflow definition.
+ */
+export interface StepErrorPolicy {
+  onError: 'fail' | 'skip' | 'retry';
+  maxRetries: number;
+  retryDelay: number;
+  retryBackoff: number;
+}
+
+/**
+ * Resolve the effective error policy for a step.
+ * Step-level config overrides workflow defaults; workflow defaults override
+ * the engine defaults (`fail` / 3 / 1000ms / 2x).
+ */
+export function resolveStepErrorPolicy<TInput>(
+  step: WorkflowStep<TInput>,
+  definition: WorkflowDefinition<TInput>
+): StepErrorPolicy {
+  return {
+    onError: step.onError ?? definition.defaultOnError ?? 'fail',
+    maxRetries: step.maxRetries ?? 3,
+    retryDelay: step.retryDelay ?? 1000,
+    retryBackoff: step.retryBackoff ?? 2,
+  };
+}
+
+/**
+ * Decision returned after a step attempt fails.
+ *
+ *  - 'skip'  : swallow the error and treat the step as a no-op (returns undefined)
+ *  - 'retry' : back off and try again
+ *  - 'fail'  : escalate (StepError) and abort the workflow
+ */
+export type StepFailureAction = 'skip' | 'retry' | 'fail';
+
+/**
+ * Decide what to do after a step attempt has failed (and was not canceled).
+ */
+export function decideStepFailureAction(
+  policy: StepErrorPolicy,
+  attempt: number
+): StepFailureAction {
+  if (policy.onError === 'skip') return 'skip';
+  if (policy.onError === 'retry' && attempt <= policy.maxRetries) return 'retry';
+  return 'fail';
+}

package/src/core/orchestrator/step-runner.ts

@@ -0,0 +1,427 @@
+/**
+ * Step runner — executes a single workflow step with hooks, retries,
+ * cancellation, and timeout handling.
+ *
+ * The shape of the previous monolithic `executeStep` was a `while (true)`
+ * loop containing a `try`/`catch` with multiple nested `if` branches per
+ * error path (cancel, hook, skip, retry, fail). This file flattens that:
+ *
+ *   - Each error path is its own intent-named helper
+ *     (handleSkipAction, handleRetryAction, runOnStepErrorHook, etc.)
+ *   - The main loop nesting is at most 3 levels (while → try → switch)
+ *
+ * State-transition rules covered here (see also state-transitions.ts):
+ *
+ *   pre-attempt:
+ *     - abort signal already raised → throw WorkflowCanceledError
+ *
+ *   per-attempt:
+ *     - handler resolves            → markStepSucceeded, emit step.completed, return
+ *     - handler rejects + canceled  → markStepFailed(canceled), emit step.failed, rethrow
+ *     - handler rejects + policy=skip   → emit step.skipped, return undefined
+ *     - handler rejects + policy=retry  → emit step.retry, sleep, continue
+ *     - handler rejects + policy=fail   → throw StepError
+ */
+import type {
+  WorkflowDefinition,
+  WorkflowStep,
+  WorkflowContext,
+  Logger,
+} from '../types';
+import type { StorageAdapter, WorkflowRunStepRecord } from '../../storage/types';
+import type { EventTransport } from '../../events/types';
+import {
+  StepError,
+  StepTimeoutError,
+  WorkflowCanceledError,
+} from '../../utils/errors';
+import { sleep, calculateRetryDelay } from '../../utils/retry';
+import {
+  createStepRecord,
+  markStepSucceeded,
+  markStepFailed,
+  markStepCanceled,
+  safeEmitEvent,
+} from './persistence';
+import {
+  resolveStepErrorPolicy,
+  decideStepFailureAction,
+  type StepErrorPolicy,
+} from './state-transitions';
+
+/**
+ * Inputs to `executeStep` beyond the step + context themselves.
+ */
+export interface StepExecutionOptions<TInput = Record<string, unknown>> {
+  definition: WorkflowDefinition<TInput>;
+  storage: StorageAdapter;
+  events: EventTransport;
+  logger: Logger;
+  abortController: AbortController;
+}
+
+/**
+ * Execute a single workflow step with error handling and retries.
+ *
+ * Returns the step's result on success, or `undefined` if the resolved
+ * error policy is `skip` and the step failed. Throws on cancellation,
+ * timeout, or `fail` policy.
+ */
+export async function executeStep<TInput>(
+  step: WorkflowStep<TInput>,
+  context: WorkflowContext<TInput>,
+  options: StepExecutionOptions<TInput>
+): Promise<unknown> {
+  const { definition, storage, events, logger, abortController } = options;
+  const policy = resolveStepErrorPolicy(step, definition);
+
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    throwIfCanceled(abortController, context.runId);
+
+    const stepRecord = await beginStepAttempt(
+      storage,
+      events,
+      logger,
+      context,
+      step,
+      attempt
+    );
+
+    if (definition.hooks?.beforeStep) {
+      await definition.hooks.beforeStep(context, step);
+    }
+
+    try {
+      const result = await runStepHandler(step, context, abortController);
+      await completeStepAttempt(
+        storage,
+        events,
+        logger,
+        stepRecord,
+        context,
+        step,
+        result,
+        definition
+      );
+      return result;
+    } catch (error) {
+      const lastError = toError(error);
+      const isCanceled =
+        error instanceof WorkflowCanceledError || abortController.signal.aborted;
+
+      await markStepFailed(storage, stepRecord.id, error, isCanceled);
+
+      if (isCanceled) {
+        emitStepFailedEvent(events, logger, context, step, lastError, attempt);
+        throw error;
+      }
+
+      await runOnStepErrorHook(definition, context, step, lastError, logger);
+      emitStepFailedEvent(events, logger, context, step, lastError, attempt);
+
+      const action = decideStepFailureAction(policy, attempt);
+
+      if (action === 'skip') {
+        handleSkipAction(events, logger, context, step, lastError);
+        return undefined;
+      }
+
+      if (action === 'retry') {
+        await handleRetryAction(
+          storage,
+          events,
+          logger,
+          abortController,
+          context,
+          step,
+          attempt,
+          policy,
+          lastError,
+          stepRecord.id
+        );
+        continue;
+      }
+
+      // action === 'fail' — explicit fail strategy or retries exhausted
+      throw new StepError(step.key, lastError.message, attempt, lastError);
+    }
+  }
+}
+
+/**
+ * Throw a WorkflowCanceledError if the abort signal has already been raised.
+ * Called at the top of each attempt so we don't even create a step record
+ * after cancellation.
+ */
+function throwIfCanceled(abortController: AbortController, runId: string): void {
+  if (abortController.signal.aborted) {
+    throw new WorkflowCanceledError(runId);
+  }
+}
+
+/**
+ * Persist a fresh step record for this attempt, set it as the current step
+ * id on the context (so handlers can attach granular telemetry), and emit
+ * `step.started`.
+ */
+async function beginStepAttempt<TInput>(
+  storage: StorageAdapter,
+  events: EventTransport,
+  logger: Logger,
+  context: WorkflowContext<TInput>,
+  step: WorkflowStep<TInput>,
+  attempt: number
+): Promise<WorkflowRunStepRecord> {
+  const stepRecord = await createStepRecord(
+    storage,
+    context.runId,
+    step.key,
+    step.name,
+    attempt
+  );
+  context.stepId = stepRecord.id;
+  safeEmitEvent(events, logger, {
+    runId: context.runId,
+    kind: context.kind,
+    eventType: 'step.started',
+    stepKey: step.key,
+    timestamp: new Date(),
+    payload: { attempt },
+  });
+  return stepRecord;
+}
+
+/**
+ * Invoke the step handler. If the step has its own timeout, race against it
+ * AND the abort signal; otherwise just race against the abort signal so a
+ * workflow-level timeout/cancellation still interrupts the step.
+ */
+async function runStepHandler<TInput>(
+  step: WorkflowStep<TInput>,
+  context: WorkflowContext<TInput>,
+  abortController: AbortController
+): Promise<unknown> {
+  if (step.timeout) {
+    return executeWithTimeout(
+      () => step.handler(context),
+      step.timeout,
+      abortController.signal,
+      step.key
+    );
+  }
+  return raceWithAbort(step.handler(context), abortController.signal);
+}
+
+/**
+ * Mark the step as succeeded, run the afterStep hook (if any), and emit
+ * `step.completed`.
+ */
+async function completeStepAttempt<TInput>(
+  storage: StorageAdapter,
+  events: EventTransport,
+  logger: Logger,
+  stepRecord: WorkflowRunStepRecord,
+  context: WorkflowContext<TInput>,
+  step: WorkflowStep<TInput>,
+  result: unknown,
+  definition: WorkflowDefinition<TInput>
+): Promise<void> {
+  await markStepSucceeded(storage, stepRecord.id, result);
+  if (definition.hooks?.afterStep) {
+    await definition.hooks.afterStep(context, step, result);
+  }
+  safeEmitEvent(events, logger, {
+    runId: context.runId,
+    kind: context.kind,
+    eventType: 'step.completed',
+    stepKey: step.key,
+    timestamp: new Date(),
+    payload: { result },
+  });
+}
+
+/**
+ * Coerce an unknown thrown value into a real Error, preserving message
+ * text for non-Error throws.
+ */
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Run the user's onStepError hook (if defined). Hook failures are logged
+ * but never propagated — they must not mask the original step error.
+ */
+async function runOnStepErrorHook<TInput>(
+  definition: WorkflowDefinition<TInput>,
+  context: WorkflowContext<TInput>,
+  step: WorkflowStep<TInput>,
+  lastError: Error,
+  logger: Logger
+): Promise<void> {
+  if (!definition.hooks?.onStepError) return;
+  try {
+    await definition.hooks.onStepError(context, step, lastError);
+  } catch (hookError) {
+    logger.error('onStepError hook failed for run ' + context.runId + ':', hookError);
+  }
+}
+
+/**
+ * Emit a `step.failed` event with the canonical payload.
+ */
+function emitStepFailedEvent<TInput>(
+  events: EventTransport,
+  logger: Logger,
+  context: WorkflowContext<TInput>,
+  step: WorkflowStep<TInput>,
+  lastError: Error,
+  attempt: number
+): void {
+  safeEmitEvent(events, logger, {
+    runId: context.runId,
+    kind: context.kind,
+    eventType: 'step.failed',
+    stepKey: step.key,
+    timestamp: new Date(),
+    payload: { error: lastError.message, attempt },
+  });
+}
+
+/**
+ * Apply the `skip` failure action: warn, emit `step.skipped`, then the
+ * caller returns `undefined` from the step.
+ */
+function handleSkipAction<TInput>(
+  events: EventTransport,
+  logger: Logger,
+  context: WorkflowContext<TInput>,
+  step: WorkflowStep<TInput>,
+  lastError: Error
+): void {
+  logger.warn(`Step "${step.key}" failed, skipping (strategy: skip)`);
+  safeEmitEvent(events, logger, {
+    runId: context.runId,
+    kind: context.kind,
+    eventType: 'step.skipped',
+    stepKey: step.key,
+    timestamp: new Date(),
+    payload: { reason: 'error', error: lastError.message },
+  });
+}
+
+/**
+ * Apply the `retry` failure action: emit `step.retry`, sleep with backoff,
+ * and let the loop fall through to the next attempt. If the sleep itself
+ * is interrupted by cancellation, mark the step record canceled before
+ * rethrowing.
+ */
+async function handleRetryAction<TInput>(
+  storage: StorageAdapter,
+  events: EventTransport,
+  logger: Logger,
+  abortController: AbortController,
+  context: WorkflowContext<TInput>,
+  step: WorkflowStep<TInput>,
+  attempt: number,
+  policy: StepErrorPolicy,
+  lastError: Error,
+  stepRecordId: string
+): Promise<void> {
+  const delay = calculateRetryDelay(attempt, policy.retryDelay, policy.retryBackoff);
+  logger.warn(
+    `Step "${step.key}" failed, retrying in ${delay}ms (attempt ${attempt}/${policy.maxRetries})`
+  );
+  safeEmitEvent(events, logger, {
+    runId: context.runId,
+    kind: context.kind,
+    eventType: 'step.retry',
+    stepKey: step.key,
+    timestamp: new Date(),
+    payload: { attempt, maxRetries: policy.maxRetries, delay, error: lastError.message },
+  });
+
+  try {
+    await sleep(delay, abortController.signal);
+  } catch (sleepError) {
+    if (sleepError instanceof WorkflowCanceledError) {
+      await markStepCanceled(storage, stepRecordId);
+    }
+    throw sleepError;
+  }
+}
+
+/**
+ * Execute a function with a timeout.
+ *
+ * Uses Promise.race to resolve as soon as either the function completes, the
+ * timeout fires, or the abort signal triggers. The `finally` block is critical:
+ * without it, the losing promise's timer/listener would remain active, leaking
+ * memory — especially problematic in long-running engines processing many steps.
+ */
+export async function executeWithTimeout<T>(
+  fn: () => Promise<T>,
+  timeoutMs: number,
+  signal: AbortSignal,
+  stepKey: string
+): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+
+  try {
+    return await Promise.race([
+      fn(),
+      new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new StepTimeoutError(stepKey, timeoutMs));
+        }, timeoutMs);
+
+        onAbort = () => {
+          clearTimeout(timeoutId);
+          reject(new WorkflowCanceledError('run'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+      }),
+    ]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+/**
+ * Race a promise against an abort signal.
+ *
+ * Steps without their own timeout still need to respect workflow-level timeouts
+ * and cancellation. This wraps the step handler in a Promise.race so that an
+ * abort signal (from workflow timeout or user cancellation) can interrupt it.
+ *
+ * The `finally` cleanup removes the abort listener to prevent accumulating
+ * listeners on the signal across many steps — without it, each step would
+ * leave a dangling listener even after completing successfully.
+ */
+export async function raceWithAbort<T>(
+  promise: Promise<T>,
+  signal: AbortSignal
+): Promise<T> {
+  if (signal.aborted) {
+    throw new WorkflowCanceledError('run');
+  }
+
+  let onAbort: (() => void) | undefined;
+
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        onAbort = () => reject(new WorkflowCanceledError('run'));
+        signal.addEventListener('abort', onAbort, { once: true });
+      }),
+    ]);
+  } finally {
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+  }
+}