pipeai 0.8.2 → 0.9.0

package/dist/index.js

@@ -18,6 +18,7 @@ function runWithWriter(writer, fn) {
 function getActiveWriter() {
   return writerStorage.getStore();
 }
+var SKIP = /* @__PURE__ */ Symbol("pipeai.foreach.skip");
 function resolveValue(value, ctx, input) {
   if (typeof value === "function") {
     return value(ctx, input);
@@ -257,7 +258,15 @@ var Agent = class {
     const resolved = await this.resolveConfig(ctx, input);
     const options = this.buildCallOptions(resolved, ctx, input);
     try {
-      const onErrorOption = this.config.onError ? { onError: ({ error }) => this.invokeOnError(error, ctx, input) } : {};
+      const onErrorOption = this.config.onError ? {
+        onError: async ({ error }) => {
+          try {
+            await this.invokeOnError(error, ctx, input);
+          } catch (handlerError) {
+            console.error(`Agent "${this.id}": onError handler threw on the stream path:`, handlerError);
+          }
+        }
+      } : {};
       return streamText({
         ...options,
         ...extra,
@@ -355,6 +364,179 @@ var Agent = class {
 import {
   createUIMessageStream
 } from "ai";
+
+// src/steps/step.ts
+var Step = class {
+  /**
+   * Observability event subtype for `type: "step"` nodes (agent / transform =
+   * `"step"`; nested / branch / foreach / repeat / parallel override).
+   * `undefined` on gate / catch / finally nodes, whose `type` IS the event type.
+   */
+  category;
+  /**
+   * The sealed sub-workflow attached to this node, when it has one (`nested`,
+   * and workflow-target `foreach` / `repeat`). Consumed by the recursive
+   * `stepShapeHash` walk and the resume path-walk in `loadState`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  nestedWorkflow;
+  /**
+   * Precedence source tag a kind writes to `state.pendingError` when it
+   * captures a thrown body error. Defaults to `"step"`; kinds with a distinct
+   * error-precedence bucket (e.g. `finally`, `catch`, `gate`) override it.
+   */
+  errorSource = "step";
+  /**
+   * The step's body, invoked by the run loop only after {@link shouldSkip}
+   * returned `false`. Each kind overrides it to do its work and capture errors
+   * onto state. `state.output` is the input on entry and becomes the output on
+   * exit; `state.writer` is present in stream mode. The base implementation is
+   * a no-op so kinds that carry no body of their own need not override it.
+   */
+  async execute(_state) {
+  }
+  /**
+   * Run-policy gate, called by the run loop before {@link execute}: return
+   * `true` when this step should be skipped silently (no hooks, no output
+   * change). The default is the "normal" policy — skip while the flow is
+   * suspended or already in error. Overridden by kinds with inverted policies:
+   * `catch` runs only when there's an error, `finally` always runs.
+   */
+  shouldSkip(state) {
+    return !!state.suspension || !!state.pendingError;
+  }
+  /**
+   * Apply `when` / `otherwise` conditional-skip options. Returns `true` when
+   * the body should be skipped — i.e. `when` returned false. On skip,
+   * `otherwise` (if present) produces the output; without it the input passes
+   * through unchanged. Distinct from {@link shouldSkip}: this is the body-level
+   * `when` / `otherwise` decision a kind applies after the policy gate passes.
+   */
+  async applyConditionalSkip(state, options) {
+    if (!options?.when) return false;
+    const params = { ctx: state.ctx, input: state.output };
+    if (await options.when(params)) return false;
+    if (options.otherwise) {
+      state.output = await options.otherwise(params);
+    }
+    return true;
+  }
+};
+
+// src/steps/transform-step.ts
+var TransformStep = class extends Step {
+  type = "step";
+  id;
+  fn;
+  options;
+  constructor(id, fn, options) {
+    super();
+    this.id = id;
+    this.fn = fn;
+    this.options = options;
+  }
+  async execute(state) {
+    try {
+      if (await this.applyConditionalSkip(state, this.options)) return;
+      state.output = await this.fn({
+        ctx: state.ctx,
+        input: state.output,
+        // Present in stream mode (undefined in generate mode), letting the
+        // inline step emit UIMessageChunk parts onto the workflow's stream.
+        writer: state.writer
+      });
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+};
+
+// src/steps/agent-step.ts
+var AgentStep = class _AgentStep extends Step {
+  type = "step";
+  id;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  agent;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  options;
+  constructor(id, agent, options) {
+    super();
+    this.id = id;
+    this.agent = agent;
+    this.options = options;
+  }
+  async execute(state) {
+    try {
+      if (await this.applyConditionalSkip(state, this.options)) return;
+      await _AgentStep.runAgent(state, this.agent, state.ctx, this.options);
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+  /**
+   * Run an agent against the current state, writing its result to
+   * `state.output`. In stream mode, output extraction awaits the full stream
+   * before returning — streaming benefits the client (incremental output), not
+   * pipeline throughput, since each step still runs sequentially.
+   *
+   * Static (does not touch instance state) so the still-literal foreach /
+   * parallel / branch combinators can share it. `itemIndex` identifies the
+   * execution to `handleStream` inside a multi-execution combinator (numeric
+   * index, record key, or matched case); `undefined` for a plain single
+   * `.step(agent)`.
+   */
+  static async runAgent(state, agent, ctx, options, itemIndex) {
+    const input = state.output;
+    const hasStructuredOutput = agent.hasOutput;
+    const abortSignal = state.abortSignal;
+    const agentCallOpts = abortSignal ? { abortSignal } : void 0;
+    if (state.mode === "stream" && state.writer) {
+      const writer = state.writer;
+      await runWithWriter(writer, async () => {
+        const result = await agent.stream(ctx, state.output, agentCallOpts);
+        if (options?.handleStream) {
+          await options.handleStream({ result, writer, ctx, input, itemIndex });
+        } else {
+          writer.merge(result.toUIMessageStream());
+        }
+        const hookParams = {
+          mode: "stream",
+          result,
+          ctx,
+          input
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        };
+        if (options?.onResult) {
+          await options.onResult(hookParams);
+        }
+        if (options?.mapResult) {
+          state.output = await options.mapResult(hookParams);
+        } else {
+          state.output = await extractOutput(result, hasStructuredOutput, agent.validateOutput);
+        }
+      });
+    } else {
+      const result = await agent.generate(ctx, state.output, agentCallOpts);
+      const hookParams = {
+        mode: "generate",
+        result,
+        ctx,
+        input
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      };
+      if (options?.onResult) {
+        await options.onResult(hookParams);
+      }
+      if (options?.mapResult) {
+        state.output = await options.mapResult(hookParams);
+      } else {
+        state.output = await extractOutput(result, hasStructuredOutput, agent.validateOutput);
+      }
+    }
+  }
+};
+
+// src/errors.ts
 var WorkflowBranchError = class extends Error {
   constructor(branchType, message) {
     super(message);
@@ -370,65 +552,118 @@ var WorkflowLoopError = class extends Error {
     this.name = "WorkflowLoopError";
   }
 };
-var NestedGateUnsupportedError = class extends Error {
-  gateId;
-  workflowId;
-  // Always present; non-gate rejections from concurrent foreach.
-  siblingErrors;
-  // Always present; OTHER suspending items in concurrent foreach.
-  siblingSuspensions;
-  constructor(gateId, workflowId, siblingErrors = [], siblingSuspensions = []) {
-    super(`Gate "${gateId}" hit inside nested workflow "${workflowId ?? "(anonymous)"}". Nested gates are not yet supported.`);
-    this.name = "NestedGateUnsupportedError";
-    this.gateId = gateId;
-    this.workflowId = workflowId;
-    this.siblingErrors = siblingErrors;
-    this.siblingSuspensions = siblingSuspensions;
-  }
-};
 var CHECKPOINT_STEP_ID = "::pipeai::onCheckpoint";
-var CheckpointTimeoutError = class extends Error {
-  timeoutMs;
-  constructor(timeoutMs) {
-    super(`onCheckpoint exceeded ${timeoutMs}ms timeout`);
-    this.name = "CheckpointTimeoutError";
-    this.timeoutMs = timeoutMs;
+var ABORT_STEP_ID = "::pipeai::abort";
+var GATE_RESUME_STEP_ID = "::pipeai::gate:resume";
+
+// src/steps/branch-step.ts
+var PredicateBranchStep = class extends Step {
+  type = "step";
+  category = "branch";
+  id;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  cases;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(id, cases) {
+    super();
+    this.id = id;
+    this.cases = cases;
+  }
+  async execute(state) {
+    try {
+      const ctx = state.ctx;
+      const input = state.output;
+      for (let caseIndex = 0; caseIndex < this.cases.length; caseIndex++) {
+        const branchCase = this.cases[caseIndex];
+        if (branchCase.when) {
+          const match = await branchCase.when({ ctx, input });
+          if (!match) continue;
+        }
+        await AgentStep.runAgent(state, branchCase.agent, ctx, branchCase, caseIndex);
+        return;
+      }
+      let inputRepr;
+      try {
+        inputRepr = JSON.stringify(input);
+        if (inputRepr === void 0) inputRepr = String(input);
+      } catch {
+        inputRepr = `[unserializable ${typeof input}]`;
+      }
+      throw new WorkflowBranchError("predicate", `No branch matched and no default branch (a case without \`when\`) was provided. Input: ${inputRepr}`);
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
   }
 };
-function resolveFreezeSnapshots(state) {
-  return state.runOptions?.freezeSnapshots ? true : false;
-}
-function migrateSnapshot(legacy) {
-  if (legacy.version !== 1) {
-    throw new Error(`migrateSnapshot: expected v1 snapshot, got version ${legacy.version}`);
+var SelectBranchStep = class extends Step {
+  type = "step";
+  category = "branch";
+  id;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  config;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(id, config) {
+    super();
+    this.id = id;
+    this.config = config;
   }
+  async execute(state) {
+    try {
+      const ctx = state.ctx;
+      const input = state.output;
+      const config = this.config;
+      const key = await config.select({ ctx, input });
+      const keyDeclared = Object.prototype.hasOwnProperty.call(config.agents, key);
+      if (keyDeclared && config.agents[key] === void 0) {
+        throw new WorkflowBranchError(
+          "select",
+          `Agent for key "${key}" was declared but the value is undefined. This usually means a conditional spread set the value to undefined. Available keys: ${Object.keys(config.agents).join(", ")}`
+        );
+      }
+      let agent = keyDeclared ? config.agents[key] : void 0;
+      if (!agent) {
+        if (config.onUnknownKey) {
+          config.onUnknownKey({
+            key,
+            availableKeys: Object.keys(config.agents),
+            ctx
+          });
+        }
+        if (config.fallback) {
+          agent = config.fallback;
+        } else {
+          throw new WorkflowBranchError("select", `No agent found for key "${key}" and no fallback provided. Available keys: ${Object.keys(config.agents).join(", ")}`);
+        }
+      }
+      await AgentStep.runAgent(state, agent, ctx, config, key);
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+};
+
+// src/runtime.ts
+function makeAbortError(signal) {
   return {
-    version: 2,
-    kind: "gate",
-    resumeFromIndex: legacy.resumeFromIndex,
-    output: legacy.output,
-    gateId: legacy.gateId,
-    gatePayload: legacy.gatePayload
+    error: signal.reason ?? new Error("Workflow aborted"),
+    stepId: ABORT_STEP_ID,
+    source: "step"
   };
 }
-function getObservabilityType(node) {
-  if (node.type !== "step") return node.type;
-  return node.category ?? "step";
+function prependNestedPath(snapshot, index, state) {
+  const next = { ...snapshot, nestedPath: [index, ...snapshot.nestedPath ?? []] };
+  if (resolveFreezeSnapshots(state)) deepFreeze(next);
+  return next;
 }
-function getNestedWorkflows(node) {
-  switch (node.type) {
-    case "step":
-      return node.nestedWorkflow ? [node.nestedWorkflow] : [];
-    case "gate":
-    case "catch":
-    case "finally":
-      return [];
-  }
+function resolveFreezeSnapshots(state) {
+  return state.runOptions?.freezeSnapshots ? true : false;
 }
 function pendingErrorSourceToStepType(source) {
   switch (source) {
     case "step":
       return "step";
+    case "gate":
+      return "gate";
     case "finally":
       return "finally";
     case "catch":
@@ -439,43 +674,42 @@ function pendingErrorSourceToStepType(source) {
 }
 async function emitCheckpoint(state, opts, resumeFromIndex, stepShapeHash) {
   if (!opts.onCheckpoint) return;
+  const willFreeze = resolveFreezeSnapshots(state);
   const snap = {
     version: 2,
     kind: "checkpoint",
     resumeFromIndex,
-    output: state.output,
+    output: willFreeze ? structuredClone(state.output) : state.output,
     stepShapeHash
   };
-  if (resolveFreezeSnapshots(state)) deepFreeze(snap);
-  const controller = new AbortController();
-  if (opts.checkpointTimeout !== void 0) {
-    const timeoutMs = opts.checkpointTimeout;
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const callPromise = Promise.resolve(opts.onCheckpoint(snap, { signal: controller.signal }));
-      const timeoutPromise = new Promise((_, reject) => {
-        controller.signal.addEventListener(
-          "abort",
-          () => reject(new CheckpointTimeoutError(timeoutMs)),
-          { once: true }
-        );
-      });
-      callPromise.catch(() => {
-      });
-      timeoutPromise.catch(() => {
-      });
-      await Promise.race([callPromise, timeoutPromise]);
-    } finally {
-      clearTimeout(timeoutId);
-    }
-  } else {
-    await opts.onCheckpoint(snap, { signal: controller.signal });
-  }
+  if (willFreeze) deepFreeze(snap);
+  await opts.onCheckpoint(snap, { signal: state.abortSignal });
 }
 var warnedStreamOnErrorOnSuspend = false;
 function pushWarning(state, source, stepId, error) {
   (state.warnings ??= []).push({ source, stepId, error });
 }
+function fireHook(observability, state, name, event) {
+  const hook = observability?.[name];
+  if (!hook) return void 0;
+  return fireHookSlow(state, name, event, hook);
+}
+async function fireHookSlow(state, name, event, hook) {
+  try {
+    await hook(event);
+    return void 0;
+  } catch (e) {
+    if (name !== "onStepError") {
+      const stepId = event.stepId;
+      pushWarning(state, name, stepId, e);
+      console.error(`pipeai: ${name} hook threw for stepId "${stepId}":`, e);
+    }
+    return e;
+  }
+}
+function hasItemHooks(observability) {
+  return !!observability && !!(observability.onItemStart || observability.onItemFinish || observability.onItemError);
+}
 function demotePendingError(state, pe) {
   pushWarning(state, pe.source, pe.stepId, pe.error);
 }
@@ -486,15 +720,466 @@ function maybeWarnStreamOnErrorOnSuspend(result, options) {
     "pipeai: stream() with options.onError suspended at a gate \u2014 onError will NOT be invoked for suspension. Discriminate via the resolved output Promise."
   );
 }
+function makeRuntimeState(ctx, output, mode, opts, writer) {
+  return {
+    ctx,
+    output,
+    mode,
+    ...writer ? { writer } : {},
+    runOptions: opts,
+    abortSignal: opts?.abortSignal
+  };
+}
+
+// src/steps/semaphore.ts
+var Semaphore = class {
+  available;
+  waiters = [];
+  constructor(permits) {
+    this.available = permits;
+  }
+  acquire() {
+    if (this.available > 0) {
+      this.available--;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+  release() {
+    const next = this.waiters.shift();
+    if (next) {
+      next();
+    } else {
+      this.available++;
+    }
+  }
+};
+
+// src/steps/concurrent.ts
+function validateConcurrency(kind, value) {
+  if (value !== void 0 && !(Number.isInteger(value) && value >= 1 || value === Infinity)) {
+    throw new Error(`${kind}: concurrency must be a positive integer or Infinity, got ${value}`);
+  }
+  return value ?? Infinity;
+}
+async function dispatchUnits(params) {
+  const { state, stepId, kind, units, observability, handleStream, onUnitSuccess } = params;
+  const unitStates = new Array(units.length);
+  const wantItemHooks = hasItemHooks(observability);
+  const executeUnit = async (unit, index) => {
+    const inheritStreaming = unit.isWorkflow || handleStream !== void 0;
+    const unitState = {
+      ctx: state.ctx,
+      output: unit.input,
+      mode: inheritStreaming ? state.mode : "generate",
+      writer: inheritStreaming ? state.writer : void 0,
+      abortSignal: state.abortSignal
+    };
+    unitStates[index] = unitState;
+    const unitStart = wantItemHooks ? performance.now() : 0;
+    if (wantItemHooks) {
+      await fireHook(observability, state, "onItemStart", {
+        stepId,
+        type: kind,
+        itemIndex: unit.key,
+        ctx: state.ctx,
+        input: unit.input
+      });
+    }
+    try {
+      if (unit.isWorkflow) {
+        await unit.target.executeAsNested(unitState);
+      } else {
+        await AgentStep.runAgent(
+          unitState,
+          unit.target,
+          state.ctx,
+          handleStream ? { handleStream } : void 0,
+          unit.key
+        );
+      }
+      onUnitSuccess(index, unitState.output);
+      if (wantItemHooks) {
+        await fireHook(observability, state, "onItemFinish", {
+          stepId,
+          type: kind,
+          itemIndex: unit.key,
+          ctx: state.ctx,
+          output: unitState.output,
+          durationMs: performance.now() - unitStart
+        });
+      }
+    } catch (error) {
+      if (wantItemHooks) {
+        await fireHook(observability, state, "onItemError", {
+          stepId,
+          type: kind,
+          itemIndex: unit.key,
+          ctx: state.ctx,
+          error,
+          durationMs: performance.now() - unitStart
+        });
+      }
+      throw error;
+    }
+  };
+  const sem = new Semaphore(params.concurrency);
+  const failures = [];
+  const inflight = /* @__PURE__ */ new Set();
+  for (let i = 0; i < units.length; i++) {
+    if (state.abortSignal?.aborted) break;
+    await sem.acquire();
+    if (state.abortSignal?.aborted) {
+      sem.release();
+      break;
+    }
+    const index = i;
+    const unit = (async () => {
+      try {
+        await executeUnit(units[index], index);
+      } catch (error) {
+        failures.push({ key: units[index].key, index, error });
+      } finally {
+        sem.release();
+      }
+    })();
+    inflight.add(unit);
+    void unit.finally(() => inflight.delete(unit));
+  }
+  await Promise.all(inflight);
+  failures.sort((a, b) => a.index - b.index);
+  return reconcileUnits(state, stepId, failures, units.length, (i) => units[i].key, unitStates, state.abortSignal);
+}
+function reconcileUnits(state, id, failures, count, keyAt, unitStates, signal) {
+  for (let i = 0; i < count; i++) {
+    const us = unitStates[i];
+    if (!us) continue;
+    if (us.suspension) {
+      throw new Error(
+        `internal: gate "${us.suspension.gateId}" suspended inside concurrent unit ${id}[${keyAt(i)}]. Gates are forbidden in foreach / parallel targets \u2014 a cast must have bypassed the build-time guard.`
+      );
+    }
+    if (!us.warnings) continue;
+    for (const w of us.warnings) {
+      pushWarning(state, w.source, `${id}[${keyAt(i)}]:${w.stepId}`, w.error);
+    }
+  }
+  if (signal?.aborted) {
+    for (const f of failures) {
+      pushWarning(state, "foreach-sibling", `${id}[${f.key}]`, f.error);
+    }
+    throw signal.reason ?? new Error("Workflow aborted");
+  }
+  return failures;
+}
+
+// src/steps/foreach-step.ts
+var ForeachStep = class extends Step {
+  type = "step";
+  category = "foreach";
+  nestedWorkflow;
+  id;
+  target;
+  concurrency;
+  onError;
+  handleStream;
+  isWorkflow;
+  observability;
+  constructor(target, options, observability) {
+    super();
+    this.target = target;
+    this.concurrency = validateConcurrency("foreach", options?.concurrency);
+    this.onError = options?.onError;
+    this.handleStream = options?.handleStream;
+    this.observability = observability;
+    this.isWorkflow = target instanceof SealedWorkflow;
+    const defaultId = this.isWorkflow ? target.id ?? "foreach" : `foreach:${target.id}`;
+    this.id = options?.id ?? defaultId;
+    this.nestedWorkflow = this.isWorkflow ? target : void 0;
+  }
+  async execute(state) {
+    try {
+      const items = state.output;
+      if (!Array.isArray(items)) {
+        throw new Error(`foreach "${this.id}": expected array input, got ${typeof items}`);
+      }
+      const results = new Array(items.length);
+      const failures = await dispatchUnits({
+        state,
+        stepId: this.id,
+        kind: "foreach",
+        units: items.map((item, i) => ({ key: i, input: item, target: this.target, isWorkflow: this.isWorkflow })),
+        concurrency: this.concurrency,
+        observability: this.observability,
+        handleStream: this.handleStream,
+        onUnitSuccess: (index, output) => {
+          results[index] = output;
+        }
+      });
+      const skipped = /* @__PURE__ */ new Set();
+      for (const { index, error } of failures) {
+        if (!this.onError) throw error;
+        const recovered = await this.onError({ error, item: items[index], index, ctx: state.ctx });
+        if (recovered === SKIP) {
+          skipped.add(index);
+        } else {
+          results[index] = recovered;
+        }
+      }
+      state.output = skipped.size === 0 ? results : results.filter((_, i) => !skipped.has(i));
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+};
+
+// src/steps/parallel-step.ts
+var ParallelStep = class extends Step {
+  type = "step";
+  category = "parallel";
+  id;
+  entries;
+  isTuple;
+  concurrency;
+  onError;
+  handleStream;
+  observability;
+  constructor(branches, options, observability) {
+    super();
+    this.isTuple = Array.isArray(branches);
+    this.entries = this.isTuple ? branches.map((target, i) => ({ key: i, index: i, target, isWorkflow: target instanceof SealedWorkflow })) : Object.entries(branches).map(([k, t], i) => ({ key: k, index: i, target: t, isWorkflow: t instanceof SealedWorkflow }));
+    this.concurrency = validateConcurrency("parallel", options?.concurrency);
+    this.onError = options?.onError;
+    this.handleStream = options?.handleStream;
+    this.observability = observability;
+    this.id = options?.id ?? (this.isTuple ? "parallel:tuple" : "parallel:record");
+  }
+  async execute(state) {
+    try {
+      const input = state.output;
+      const results = this.isTuple ? new Array(this.entries.length) : {};
+      const failures = await dispatchUnits({
+        state,
+        stepId: this.id,
+        kind: "parallel",
+        units: this.entries.map((e) => ({ key: e.key, input, target: e.target, isWorkflow: e.isWorkflow })),
+        concurrency: this.concurrency,
+        observability: this.observability,
+        handleStream: this.handleStream,
+        onUnitSuccess: (index, output) => {
+          results[this.entries[index].key] = output;
+        }
+      });
+      for (const { key, index, error } of failures) {
+        if (!this.onError) throw error;
+        const recovered = await this.onError({
+          error,
+          key: this.isTuple ? void 0 : key,
+          index: this.isTuple ? index : void 0,
+          ctx: state.ctx
+        });
+        results[key] = recovered === SKIP ? void 0 : recovered;
+      }
+      state.output = results;
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+};
+
+// src/steps/gate-step.ts
+var GateStep = class extends Step {
+  type = "gate";
+  id;
+  errorSource = "gate";
+  /** Read by `loadState` to validate the resumed gate response. */
+  schema;
+  /** Read by `loadState` to merge the response with the suspended output. */
+  merge;
+  payload;
+  condition;
+  constructor(id, options) {
+    super();
+    this.id = id;
+    this.payload = options?.payload;
+    this.schema = options?.schema;
+    this.condition = options?.condition;
+    this.merge = options?.merge;
+  }
+  async execute(state) {
+    try {
+      const params = { ctx: state.ctx, input: state.output };
+      if (this.condition && !await this.condition(params)) return;
+      const snapshot = {
+        version: 2,
+        kind: "gate",
+        resumeFromIndex: state.stepIndex ?? -1,
+        output: state.output,
+        gateId: this.id,
+        gatePayload: this.payload ? await this.payload(params) : state.output
+      };
+      state.suspension = snapshot;
+      if (resolveFreezeSnapshots(state)) deepFreeze(snapshot);
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+};
+
+// src/steps/catch-step.ts
+var CatchStep = class extends Step {
+  type = "catch";
+  id;
+  errorSource = "catch";
+  catchFn;
+  constructor(id, catchFn) {
+    super();
+    this.id = id;
+    this.catchFn = catchFn;
+  }
+  // Runs only on a pending error; skipped on suspension and checkpoint failure.
+  shouldSkip(state) {
+    return !!state.suspension || !state.pendingError || !!state.checkpointFailed;
+  }
+  async execute(state) {
+    const handled = state.pendingError;
+    state.output = await this.catchFn({
+      error: handled.error,
+      ctx: state.ctx,
+      lastOutput: state.output,
+      stepId: handled.stepId
+    });
+    state.pendingError = void 0;
+  }
+};
+
+// src/steps/finally-step.ts
+var FinallyStep = class extends Step {
+  type = "finally";
+  id;
+  errorSource = "finally";
+  fn;
+  constructor(id, fn) {
+    super();
+    this.id = id;
+    this.fn = fn;
+  }
+  // Always runs — cleanup must fire regardless of suspension / error state.
+  shouldSkip(_state) {
+    return false;
+  }
+  async execute(state) {
+    await this.fn({ ctx: state.ctx });
+  }
+};
+
+// src/steps/nested-workflow-step.ts
+var NestedWorkflowStep = class extends Step {
+  type = "step";
+  category = "nested";
+  nestedWorkflow;
+  id;
+  options;
+  constructor(id, workflow, options) {
+    super();
+    this.id = id;
+    this.nestedWorkflow = workflow;
+    this.options = options;
+  }
+  async execute(state) {
+    const descent = state.resumeDescent;
+    if (descent) {
+      state.resumeDescent = void 0;
+      const [childStart, ...rest] = descent.remaining;
+      const myIndex2 = state.stepIndex ?? -1;
+      try {
+        if (rest.length === 0) {
+          state.output = descent.seedOutput;
+        } else {
+          state.resumeDescent = { remaining: rest, seedOutput: descent.seedOutput };
+        }
+        await this.nestedWorkflow.executeAsNested(state, childStart);
+        if (state.suspension) state.suspension = prependNestedPath(state.suspension, myIndex2, state);
+      } catch (error) {
+        state.pendingError = { error, stepId: this.id, source: this.errorSource };
+      }
+      return;
+    }
+    const myIndex = state.stepIndex ?? -1;
+    try {
+      if (await this.applyConditionalSkip(state, this.options)) return;
+      await this.nestedWorkflow.executeAsNested(state);
+      if (state.suspension) state.suspension = prependNestedPath(state.suspension, myIndex, state);
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+};
+
+// src/steps/repeat-step.ts
+var RepeatStep = class extends Step {
+  type = "step";
+  category = "repeat";
+  nestedWorkflow;
+  id;
+  target;
+  predicate;
+  maxIterations;
+  isWorkflow;
+  constructor(id, target, predicate, maxIterations, isWorkflow) {
+    super();
+    this.id = id;
+    this.target = target;
+    this.predicate = predicate;
+    this.maxIterations = maxIterations;
+    this.isWorkflow = isWorkflow;
+    this.nestedWorkflow = isWorkflow ? target : void 0;
+  }
+  async execute(state) {
+    try {
+      const ctx = state.ctx;
+      for (let i = 1; i <= this.maxIterations; i++) {
+        if (state.abortSignal?.aborted) {
+          throw state.abortSignal.reason ?? new Error("Workflow aborted");
+        }
+        if (this.isWorkflow) {
+          await this.target.executeAsNested(state);
+        } else {
+          await AgentStep.runAgent(state, this.target, ctx);
+        }
+        const done = await this.predicate({ output: state.output, ctx, iterations: i });
+        if (done) return;
+      }
+      throw new WorkflowLoopError(this.maxIterations, this.maxIterations);
+    } catch (error) {
+      state.pendingError = { error, stepId: this.id, source: this.errorSource };
+    }
+  }
+};
+
+// src/workflow.ts
+function migrateSnapshot(legacy) {
+  if (legacy.version !== 1) {
+    throw new Error(`migrateSnapshot: expected v1 snapshot, got version ${legacy.version}`);
+  }
+  return {
+    version: 2,
+    kind: "gate",
+    resumeFromIndex: legacy.resumeFromIndex,
+    output: legacy.output,
+    gateId: legacy.gateId,
+    gatePayload: legacy.gatePayload
+  };
+}
 var SealedWorkflow = class _SealedWorkflow {
   id;
   steps;
   observability;
   // Memoized — see ensureDuplicateCheck().
   duplicateCheckPassed = false;
-  // Memoized lazily per terminal instance — build pipelines once at module
-  // load and re-run via generate() to amortize.
-  _cachedExecutableStepCount;
+  // Memoized lazily per terminal instance: the executable / checkpointable step
+  // counts (one walk) and the recursive shape hash (separate — it's expensive).
+  _stepCounts;
   _cachedStepShapeHash;
   constructor(steps, id, observability) {
     this.steps = steps;
@@ -529,21 +1214,26 @@ var SealedWorkflow = class _SealedWorkflow {
     }
     this.duplicateCheckPassed = true;
   }
-  // ── shape-hash + RunOptions validation ────────────────────────
+  // ── step counts + shape-hash (memoized) ────────────────────────────
   /**
-   * Count of executable nodes — i.e. NOT `catch` or `finally`. Drives
-   * checkpoint auto-cadence so adding cleanup steps doesn't surprise users
-   * with extra fires. `branch`/`foreach`/`repeat`/`parallel`/`nested` are all
-   * `type: "step"` internally and count as executable.
+   * Two cadence inputs from a single walk:
+   *   - `executable` — nodes that aren't `catch` / `finally`. A graph-size
+   *     proxy for the catastrophe threshold in {@link validateRunOptions}.
+   *   - `checkpointable` — `type === "step"` nodes only (this includes
+   *     branch / foreach / repeat / parallel / nested). Drives the checkpoint
+   *     auto-cadence denominator: gates suspend/skip and never reach the
+   *     checkpoint block, so counting them would dilute the "~4 checkpoints
+   *     across the run" target.
    */
-  get cachedExecutableStepCount() {
-    if (this._cachedExecutableStepCount !== void 0) return this._cachedExecutableStepCount;
-    let n = 0;
+  get stepCounts() {
+    if (this._stepCounts) return this._stepCounts;
+    let executable = 0;
+    let checkpointable = 0;
     for (const s of this.steps) {
-      if (s.type !== "catch" && s.type !== "finally") n++;
+      if (s.type !== "catch" && s.type !== "finally") executable++;
+      if (s.type === "step") checkpointable++;
     }
-    this._cachedExecutableStepCount = n;
-    return n;
+    return this._stepCounts = { executable, checkpointable };
   }
   /** @internal — used by `computeStepShapeHash` to descend nested workflows. */
   getStepsForShapeHash() {
@@ -551,7 +1241,7 @@ var SealedWorkflow = class _SealedWorkflow {
   }
   get cachedStepShapeHash() {
     if (this._cachedStepShapeHash !== void 0) return this._cachedStepShapeHash;
-    const getNested = (node) => getNestedWorkflows(node);
+    const getNested = (node) => node.nestedWorkflow ? [node.nestedWorkflow] : [];
     this._cachedStepShapeHash = computeStepShapeHash(
       this.steps,
       getNested
@@ -562,24 +1252,29 @@ var SealedWorkflow = class _SealedWorkflow {
    * Validate user-provided RunOptions before a run begins. Throws on
    * outright errors and on the loud-disaster combo (`freezeSnapshots: true
    * + checkpointEvery: 1` on a workflow of 8+ steps). Warns once on the
-   * merely-suspicious combo (`freezeSnapshots: true + cadence <= 2`).
-   * Plan-of-record: catastrophic combo escape via the
-   * `"iAcceptThePerformanceCost"` literal.
+   * merely-suspicious combo (`freezeSnapshots: true + cadence <= 2`), and on
+   * checkpoint-cadence options set without an `onCheckpoint` sink (a no-op
+   * that usually signals a forgotten sink).
    */
   validateRunOptions(opts) {
     if (!opts) return;
-    if (!opts.onCheckpoint) return;
     if (opts.checkpointEvery !== void 0 && opts.checkpointWhen !== void 0) {
       throw new Error("RunOptions: checkpointEvery and checkpointWhen are mutually exclusive");
     }
     if (opts.checkpointEvery !== void 0 && (!Number.isInteger(opts.checkpointEvery) || opts.checkpointEvery < 1)) {
       throw new Error(`RunOptions: checkpointEvery must be a positive integer, got ${opts.checkpointEvery}`);
     }
-    if (opts.checkpointTimeout !== void 0 && (!Number.isFinite(opts.checkpointTimeout) || opts.checkpointTimeout < 1)) {
-      throw new Error(`RunOptions: checkpointTimeout must be a finite positive number (ms), got ${opts.checkpointTimeout}`);
+    if (!opts.onCheckpoint) {
+      if (opts.checkpointEvery !== void 0 || opts.checkpointWhen !== void 0) {
+        warnOnce(
+          "pipeai:checkpoint-without-sink",
+          "pipeai: checkpointEvery/checkpointWhen set without onCheckpoint \u2014 no checkpoints will fire. Did you forget the onCheckpoint sink?"
+        );
+      }
+      return;
     }
-    const length = this.cachedExecutableStepCount;
-    const cadence = opts.checkpointEvery ?? Math.max(1, Math.ceil(length / 4));
+    const length = this.stepCounts.executable;
+    const cadence = opts.checkpointEvery ?? Math.max(1, Math.ceil(this.stepCounts.checkpointable / 4));
     if (opts.freezeSnapshots && opts.freezeSnapshots !== "iAcceptThePerformanceCost" && cadence === 1 && length >= 8) {
       throw new Error(
         `freezeSnapshots+checkpointEvery:1 on a ${length}-step workflow is reliably catastrophic. Set checkpointEvery >= 5, freezeSnapshots: false, or pass "iAcceptThePerformanceCost".`
@@ -593,6 +1288,13 @@ var SealedWorkflow = class _SealedWorkflow {
     }
   }
   // ── Observability helpers ─────────────────────────────────────
+  /** Observability event `type` for a node: a `type: "step"` node reports its
+   *  `category` (agent / transform default to `"step"`); every other node's
+   *  `type` IS the event type. */
+  obsEventType(node) {
+    if (node.type !== "step") return node.type;
+    return node.category ?? "step";
+  }
   /**
    * Fire an observability hook safely. Returns `undefined` synchronously when
    * no hook is registered — avoiding the promise wrapper + microtask that an
@@ -606,48 +1308,80 @@ var SealedWorkflow = class _SealedWorkflow {
    * Returns the hook's thrown error if any; undefined otherwise. Callers
    * `await` the result — `await undefined` is sync, so the no-hook path
    * stays allocation-free.
+   *
+   * Thin delegate to the free `fireHook` (which takes an explicit
+   * observability), kept as a method so the loop's many `this.fireHook` call
+   * sites stay unchanged.
    */
   fireHook(state, name, event) {
-    const hook = this.observability?.[name];
-    if (!hook) return void 0;
-    return this.fireHookSlow(state, name, event, hook);
+    return fireHook(this.observability, state, name, event);
   }
-  async fireHookSlow(state, name, event, hook) {
-    try {
-      await hook(event);
-      return void 0;
-    } catch (e) {
-      if (name !== "onStepError") {
-        const stepId = event.stepId;
-        pushWarning(state, name, stepId, e);
-        console.error(`pipeai: ${name} hook threw for stepId "${stepId}":`, e);
+  /**
+   * Fire `onStepError` for a step-body failure and honor the documented
+   * cause-attachment contract uniformly across every firing path (step, gate,
+   * catch, finally, checkpoint). When the hook itself throws, its error is
+   * attached as `cause` on the ORIGINAL error so the original still reaches the
+   * caller with the failure trail attached. If the original error is frozen /
+   * non-extensible (cause assignment throws) or is not an object, the hook
+   * error is recorded as a warning instead — so an `onStepError` throw is never
+   * silently lost. (The suspension-wins tail fires `onStepError` separately, on
+   * its own demotion path.)
+   */
+  async fireStepErrorAndAttachCause(state, event) {
+    const obsError = await this.fireHook(state, "onStepError", event);
+    if (obsError === void 0) return;
+    const e = event.error;
+    if (typeof e === "object" && e !== null) {
+      try {
+        e.cause = obsError;
+        return;
+      } catch {
       }
-      return e;
     }
+    pushWarning(state, "onStepError", event.stepId, obsError);
   }
   // ── Execution ─────────────────────────────────────────────────
   async generate(ctx, ...args) {
     this.ensureDuplicateCheck();
     const input = args[0];
     const opts = args[1];
-    this.validateRunOptions(opts);
-    const state = {
-      ctx,
-      output: input,
-      mode: "generate",
-      runOptions: opts,
-      abortSignal: opts?.abortSignal
-    };
-    await this.execute(state, 0, opts);
-    return this.buildResult(state);
+    return this.runGenerate(ctx, 0, opts, () => ({ output: input, initialError: null }));
   }
   stream(ctx, ...args) {
     this.ensureDuplicateCheck();
     const input = args[0];
     const options = args[1];
     const opts = args[2];
+    return this.runStream(ctx, 0, opts, options, () => ({ output: input, initialError: null }));
+  }
+  // Helper — converts terminal RuntimeState into a WorkflowResult; freezes
+  // snapshot + warnings if requested via runOptions.
+  buildResult(state) {
+    const warnings = state.warnings ?? [];
+    if (resolveFreezeSnapshots(state)) {
+      deepFreeze(warnings);
+    }
+    if (state.suspension) {
+      return { status: "suspended", snapshot: state.suspension, warnings };
+    }
+    return { status: "complete", output: state.output, warnings };
+  }
+  // ── Shared run drivers (generate / stream) ────────────────────
+  // Every public entry point — base generate/stream plus gate- and
+  // checkpoint-resume — differs only in (a) how it seeds the initial output /
+  // pre-execute error and (b) the start index. Both drivers take a `seed`
+  // thunk for (a) and a `startIndex` for (b); the rest (validation, state
+  // construction, execute, result building, stream plumbing) is identical.
+  async runGenerate(ctx, startIndex, opts, seed) {
+    this.validateRunOptions(opts);
+    const seeded = await seed();
+    const state = makeRuntimeState(ctx, seeded.output, "generate", opts);
+    if (seeded.resumeDescent) state.resumeDescent = seeded.resumeDescent;
+    await this.execute(state, startIndex, opts, seeded.initialError);
+    return this.buildResult(state);
+  }
+  runStream(ctx, startIndex, opts, options, seed) {
     this.validateRunOptions(opts);
-    const abortSignal = opts?.abortSignal;
     let resolveOutput;
     let rejectOutput;
     const outputPromise = new Promise((res, rej) => {
@@ -658,16 +1392,11 @@ var SealedWorkflow = class _SealedWorkflow {
     });
     const stream = createUIMessageStream({
       execute: async ({ writer }) => {
-        const state = {
-          ctx,
-          output: input,
-          mode: "stream",
-          writer,
-          runOptions: opts,
-          abortSignal
-        };
         try {
-          await this.execute(state, 0, opts);
+          const seeded = await seed();
+          const state = makeRuntimeState(ctx, seeded.output, "stream", opts, writer);
+          if (seeded.resumeDescent) state.resumeDescent = seeded.resumeDescent;
+          await this.execute(state, startIndex, opts, seeded.initialError);
           const result = this.buildResult(state);
           maybeWarnStreamOnErrorOnSuspend(result, options);
           resolveOutput(result);
@@ -681,22 +1410,7 @@ var SealedWorkflow = class _SealedWorkflow {
       ...options?.originalMessages ? { originalMessages: options.originalMessages } : {},
       ...options?.generateId ? { generateId: options.generateId } : {}
     });
-    return {
-      stream,
-      output: outputPromise
-    };
-  }
-  // Helper — converts terminal RuntimeState into a WorkflowResult; freezes
-  // snapshot + warnings if requested via runOptions.
-  buildResult(state) {
-    const warnings = state.warnings ?? [];
-    if (state.suspension && resolveFreezeSnapshots(state)) {
-      deepFreeze(warnings);
-    }
-    if (state.suspension) {
-      return { status: "suspended", snapshot: state.suspension, warnings };
-    }
-    return { status: "complete", output: state.output, warnings };
+    return { stream, output: outputPromise };
   }
   // ── Internal: execute pipeline ────────────────────────────────
   async execute(state, startIndex = 0, opts, initialError = null) {
@@ -706,297 +1420,184 @@ var SealedWorkflow = class _SealedWorkflow {
     if (opts !== void 0 && state.runOptions === void 0) {
       state.runOptions = opts;
     }
-    const ckptCadence = opts?.onCheckpoint && opts.checkpointWhen === void 0 ? opts.checkpointEvery ?? Math.max(1, Math.ceil(this.cachedExecutableStepCount / 4)) : 0;
-    let pendingError = initialError;
-    let abortPromoted = false;
-    const makeAbortError = (signal) => ({
-      error: signal.reason ?? new Error("Workflow aborted"),
-      stepId: "abort",
-      source: "step"
-    });
+    const ckptCadence = opts?.onCheckpoint && opts.checkpointWhen === void 0 ? opts.checkpointEvery ?? Math.max(1, Math.ceil(this.stepCounts.checkpointable / 4)) : 0;
+    const ckptCounter = { seen: 0 };
+    state.pendingError = initialError ?? void 0;
+    const abortState = { promoted: false };
     for (let i = startIndex; i < this.steps.length; i++) {
-      if (state.abortSignal?.aborted) {
-        if (!abortPromoted) {
-          abortPromoted = true;
-          state.suspension = void 0;
-          if (pendingError) demotePendingError(state, pendingError);
-          pendingError = makeAbortError(state.abortSignal);
-        } else if (!pendingError) {
-          pendingError = makeAbortError(state.abortSignal);
-        }
-      }
+      this.promoteAbort(state, abortState);
       const node = this.steps[i];
-      if (node.type === "finally") {
-        const stepId2 = node.id;
-        const finStart = performance.now();
-        await this.fireHook(state, "onStepStart", { stepId: stepId2, type: "finally", ctx: state.ctx, input: state.output });
-        try {
-          await node.execute(state);
-          await this.fireHook(state, "onStepFinish", {
-            stepId: stepId2,
-            type: "finally",
-            ctx: state.ctx,
-            output: state.output,
-            durationMs: performance.now() - finStart,
-            suspended: false
-          });
-        } catch (e) {
-          await this.fireHook(state, "onStepError", {
-            stepId: stepId2,
-            type: "finally",
-            ctx: state.ctx,
-            error: e,
-            durationMs: performance.now() - finStart
-          });
-          if (pendingError) demotePendingError(state, pendingError);
-          pendingError = { error: e, stepId: stepId2, source: "finally" };
-        }
-        continue;
-      }
-      if (node.type === "catch") {
-        if (state.suspension || !pendingError || state.checkpointFailed) continue;
-        const stepId2 = node.id;
-        const cStart = performance.now();
-        await this.fireHook(state, "onStepStart", { stepId: stepId2, type: "catch", ctx: state.ctx, input: state.output });
-        try {
-          state.output = await node.catchFn({
-            error: pendingError.error,
-            ctx: state.ctx,
-            lastOutput: state.output,
-            stepId: pendingError.stepId
-          });
-          pendingError = null;
-          await this.fireHook(state, "onStepFinish", {
-            stepId: stepId2,
-            type: "catch",
-            ctx: state.ctx,
-            output: state.output,
-            durationMs: performance.now() - cStart,
-            suspended: false
-          });
-        } catch (e) {
-          await this.fireHook(state, "onStepError", {
-            stepId: stepId2,
-            type: "catch",
-            ctx: state.ctx,
-            error: e,
-            durationMs: performance.now() - cStart
-          });
-          if (pendingError) demotePendingError(state, pendingError);
-          pendingError = { error: e, stepId: stepId2, source: "catch" };
-        }
-        continue;
-      }
-      if (state.suspension || pendingError) continue;
-      if (node.type === "gate") {
-        const stepId2 = node.id;
-        const gStart = performance.now();
-        await this.fireHook(state, "onStepStart", { stepId: stepId2, type: "gate", ctx: state.ctx, input: state.output });
-        try {
-          if (node.condition && !await node.condition(state)) {
-            await this.fireHook(state, "onStepFinish", {
-              stepId: stepId2,
-              type: "gate",
-              ctx: state.ctx,
-              output: state.output,
-              durationMs: performance.now() - gStart,
-              suspended: false
-            });
-            continue;
-          }
-          const snapshot = {
-            version: 2,
-            kind: "gate",
-            resumeFromIndex: i,
-            output: state.output,
-            gateId: node.id,
-            gatePayload: await node.payload(state)
-          };
-          state.suspension = snapshot;
-          if (resolveFreezeSnapshots(state)) deepFreeze(snapshot);
-          await this.fireHook(state, "onStepFinish", {
-            stepId: stepId2,
-            type: "gate",
-            ctx: state.ctx,
-            output: state.output,
-            durationMs: performance.now() - gStart,
-            suspended: true
-          });
-        } catch (e) {
-          pendingError = { error: e, stepId: node.id, source: "step" };
-        }
-        continue;
-      }
-      const obsType = getObservabilityType(node);
+      if (node.shouldSkip(state)) continue;
+      const obsType = this.obsEventType(node);
       const stepId = node.id;
       const sStart = performance.now();
-      const stepInput = state.output;
-      await this.fireHook(state, "onStepStart", { stepId, type: obsType, ctx: state.ctx, input: stepInput });
+      const errBefore = state.pendingError;
+      const suspendedBefore = !!state.suspension;
+      state.stepIndex = i;
+      await this.fireHook(state, "onStepStart", { stepId, type: obsType, ctx: state.ctx, input: state.output });
       try {
         await node.execute(state);
-        await this.fireHook(state, "onStepFinish", {
+      } catch (e) {
+        await this.fireStepErrorAndAttachCause(state, {
           stepId,
           type: obsType,
           ctx: state.ctx,
-          output: state.output,
-          durationMs: performance.now() - sStart,
-          suspended: false
+          error: e,
+          durationMs: performance.now() - sStart
         });
-      } catch (e) {
-        pendingError = { error: e, stepId: node.id, source: "step" };
-        const obsError = await this.fireHook(state, "onStepError", {
+        throw e;
+      }
+      const newError = state.pendingError && state.pendingError !== errBefore ? state.pendingError : null;
+      const isAbort = !!newError && state.abortSignal?.aborted === true && newError.error === state.abortSignal.reason;
+      if (isAbort) {
+      } else if (newError) {
+        await this.fireStepErrorAndAttachCause(state, {
           stepId,
           type: obsType,
           ctx: state.ctx,
-          error: e,
+          error: newError.error,
           durationMs: performance.now() - sStart
         });
-        if (obsError !== void 0 && typeof e === "object" && e !== null) {
-          try {
-            e.cause = obsError;
-          } catch {
-          }
-        }
+      } else {
+        await this.fireHook(state, "onStepFinish", {
+          stepId,
+          type: obsType,
+          ctx: state.ctx,
+          output: state.output,
+          durationMs: performance.now() - sStart,
+          suspended: !suspendedBefore && !!state.suspension
+        });
       }
-      const leaked = state.suspension;
-      if (leaked) {
+      if (node.type === "step" && node.category !== "nested" && state.suspension) {
+        const leaked = state.suspension;
         state.suspension = void 0;
         throw new Error(`internal: suspension bubbled from non-gate step "${node.id}" (gate "${leaked.gateId}").`);
       }
-      if (!pendingError && !state.suspension && opts?.onCheckpoint) {
-        const shouldCheckpoint = opts.checkpointWhen ? opts.checkpointWhen({ stepIndex: i, stepId: node.id, ctx: state.ctx }) : (i + 1) % ckptCadence === 0;
-        if (shouldCheckpoint) {
-          const ckptStart = performance.now();
-          try {
-            await emitCheckpoint(
-              state,
-              opts,
-              i + 1,
-              this.cachedStepShapeHash
-            );
-          } catch (e) {
-            pendingError = { error: e, stepId: CHECKPOINT_STEP_ID, source: "onCheckpoint" };
-            state.checkpointFailed = true;
-            await this.fireHook(state, "onStepError", {
-              stepId: CHECKPOINT_STEP_ID,
-              type: "step",
-              ctx: state.ctx,
-              error: e,
-              durationMs: performance.now() - ckptStart
-            });
-          }
-        }
-      }
+      await this.maybeCheckpoint(state, opts, node, i, ckptCadence, ckptCounter);
+    }
+    await this.settleRun(state, abortState.promoted);
+  }
+  /**
+   * Promote a fired abort signal into `state.pendingError` at an iteration
+   * boundary. First observation discards any in-progress suspension (the caller
+   * asked to stop) and preserves a genuinely-different prior step error as a
+   * warning — but NOT one that is itself the abort reason (a nested workflow /
+   * concurrent unit that already rethrew it), which would surface a phantom
+   * step-failure warning. Subsequent iterations only re-promote if a downstream
+   * catch cleared pendingError — `AbortSignal.aborted` is sticky, so the
+   * workflow must not resume mid-pipeline just because a catch swallowed one
+   * observation.
+   */
+  promoteAbort(state, abortState) {
+    const signal = state.abortSignal;
+    if (!signal?.aborted) return;
+    if (!abortState.promoted) {
+      abortState.promoted = true;
+      state.suspension = void 0;
+      const prior = state.pendingError;
+      if (prior && prior.error !== signal.reason) demotePendingError(state, prior);
+      state.pendingError = makeAbortError(signal);
+    } else if (!state.pendingError) {
+      state.pendingError = makeAbortError(signal);
+    }
+  }
+  /**
+   * Emit a checkpoint after a successful `type:"step"` body. Skipped on
+   * pendingError (no clean state to snapshot), on suspension (gate already
+   * won), and for catch/finally/gate nodes (not checkpointable). Numeric
+   * `checkpointEvery` (default: `max(1, ceil(count/4))`) uses the loop-hoisted
+   * `ckptCadence`; the predicate form runs per step. A `when:false`-skipped
+   * `type:"step"` node returns normally (its body never ran) and still reaches
+   * here — it advances the counter and can itself be a checkpoint boundary,
+   * keeping the cadence denominator (`stepCounts.checkpointable`) consistent
+   * with the runtime counter.
+   */
+  async maybeCheckpoint(state, opts, node, index, ckptCadence, counter) {
+    if (node.type !== "step" || state.pendingError || state.suspension || !opts?.onCheckpoint) return;
+    counter.seen++;
+    const shouldCheckpoint = opts.checkpointWhen ? opts.checkpointWhen({ stepIndex: index, stepId: node.id, ctx: state.ctx }) : counter.seen % ckptCadence === 0;
+    if (!shouldCheckpoint) return;
+    const ckptStart = performance.now();
+    try {
+      await emitCheckpoint(state, opts, index + 1, this.cachedStepShapeHash);
+    } catch (e) {
+      state.pendingError = { error: e, stepId: CHECKPOINT_STEP_ID, source: "onCheckpoint" };
+      state.checkpointFailed = true;
+      await this.fireStepErrorAndAttachCause(state, {
+        stepId: CHECKPOINT_STEP_ID,
+        type: "step",
+        ctx: state.ctx,
+        error: e,
+        durationMs: performance.now() - ckptStart
+      });
+    }
+  }
+  /**
+   * Terminal reconciliation after the loop. Re-promotes a swallowed abort
+   * (recoverability must not depend on catch position), then resolves the
+   * mutually-exclusive precedence tail: checkpointFailed > original-step error
+   * > suspension. (A throwing catch/finally never reaches here — it bubbles
+   * straight out of the loop, so there is no finally-aggregation branch.)
+   */
+  async settleRun(state, abortPromoted) {
+    if (abortPromoted && !state.pendingError && !state.suspension && state.abortSignal?.aborted) {
+      state.pendingError = makeAbortError(state.abortSignal);
     }
-    if (pendingError && !state.suspension) {
+    if (state.pendingError && !state.suspension) {
+      const pe = state.pendingError;
       if (state.checkpointFailed) {
         const warningsArr = state.warnings ?? [];
-        const checkpointError = pendingError.source === "onCheckpoint" ? pendingError.error : warningsArr.find((w) => w.source === "onCheckpoint")?.error;
-        const finallyErrors = warningsArr.filter((w) => w.source === "finally").map((w) => w.error);
-        const all = pendingError.source === "finally" ? [...finallyErrors, pendingError.error] : finallyErrors;
-        if (all.length > 0) {
+        const checkpointError = pe.source === "onCheckpoint" ? pe.error : warningsArr.find((w) => w.source === "onCheckpoint")?.error;
+        const suppressed = warningsArr.filter((w) => w.error !== checkpointError).map((w) => w.error);
+        if (pe.source !== "onCheckpoint" && pe.error !== checkpointError) {
+          suppressed.push(pe.error);
+        }
+        if (suppressed.length > 0) {
           console.warn(
-            `pipeai: ${all.length} .finally() error(s) suppressed by checkpoint-failure precedence:`,
-            all
+            `pipeai: ${suppressed.length} error(s) suppressed by checkpoint-failure precedence:`,
+            suppressed
           );
         }
-        throw checkpointError ?? pendingError.error;
+        throw checkpointError ?? pe.error;
       }
-      const isFinallyPath = pendingError.source === "finally" || (state.warnings?.some((w) => w.source === "finally") ?? false);
-      if (isFinallyPath) {
-        const all = [...(state.warnings ?? []).map((w) => w.error), pendingError.error];
-        throw new AggregateError(all, `Workflow failed with ${all.length} error(s) from .finally() bodies`);
-      }
-      throw pendingError.error;
-    } else if (pendingError && state.suspension) {
-      demotePendingError(state, pendingError);
+      throw pe.error;
+    } else if (state.pendingError && state.suspension) {
+      const pe = state.pendingError;
+      demotePendingError(state, pe);
       try {
         await this.observability?.onStepError?.({
-          stepId: pendingError.stepId,
-          type: pendingErrorSourceToStepType(pendingError.source),
+          stepId: pe.stepId,
+          type: pendingErrorSourceToStepType(pe.source),
           ctx: state.ctx,
-          error: pendingError.error,
+          error: pe.error,
           durationMs: 0
         });
       } catch (obsError) {
-        pushWarning(state, "onStepError", pendingError.stepId, obsError);
+        pushWarning(state, "onStepError", pe.stepId, obsError);
       }
-      pendingError = null;
+      state.pendingError = void 0;
     }
   }
-  // ── Internal: execute a nested workflow within a step/loop ─────
-  // Defined on SealedWorkflow (not Workflow) because TypeScript's protected
-  // access rules only allow calling workflow.execute() from the same class.
-  //
-  // Contract: clears any inner suspension before re-throwing as
-  // NestedGateUnsupportedError. The outer execute() therefore never observes
-  // a leaked `state.suspension` from non-gate nodes (defensive invariant).
-  async executeNestedWorkflow(state, workflow) {
+  /**
+   * Run THIS sealed workflow as a nested step on the caller's run `state`.
+   * Public (internal; not re-exported from index) so `Step` subclasses —
+   * `nested` / `repeat` / `foreach` / `parallel` with `SealedWorkflow` targets
+   * — can run a sub-workflow without reaching the protected `execute`.
+   *
+   * Contract: RunOptions is run-scoped, so the child never inherits the
+   * parent's (`state.warnings` IS propagated — telemetry > config). A gate
+   * inside the child leaves `state.suspension` set so it propagates up (only a
+   * `.step(workflow)` ever does this — concurrent/looped combinators forbid
+   * gated targets at build time).
+   */
+  async executeAsNested(state, startIndex = 0) {
     const savedRunOptions = state.runOptions;
     state.runOptions = void 0;
     try {
-      await workflow.execute(state);
+      await this.execute(state, startIndex);
     } finally {
       state.runOptions = savedRunOptions;
     }
-    if (state.suspension) {
-      const gateId = state.suspension.gateId;
-      state.suspension = void 0;
-      throw new NestedGateUnsupportedError(gateId, workflow.id);
-    }
-  }
-  // ── Internal: execute an agent within a step/branch ───────────
-  // In stream mode, output extraction awaits the full stream before returning.
-  // Streaming benefits the client (incremental output), not pipeline throughput —
-  // each step still runs sequentially.
-  async executeAgent(state, agent, ctx, options) {
-    const input = state.output;
-    const hasStructuredOutput = agent.hasOutput;
-    const abortSignal = state.abortSignal;
-    const agentCallOpts = abortSignal ? { abortSignal } : void 0;
-    if (state.mode === "stream" && state.writer) {
-      const writer = state.writer;
-      await runWithWriter(writer, async () => {
-        const result = await agent.stream(ctx, state.output, agentCallOpts);
-        if (options?.handleStream) {
-          await options.handleStream({ result, writer, ctx, input });
-        } else {
-          writer.merge(result.toUIMessageStream());
-        }
-        const hookParams = {
-          mode: "stream",
-          result,
-          ctx,
-          input
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        };
-        if (options?.onResult) {
-          await options.onResult(hookParams);
-        }
-        if (options?.mapResult) {
-          state.output = await options.mapResult(hookParams);
-        } else {
-          state.output = await extractOutput(result, hasStructuredOutput, agent.validateOutput);
-        }
-      });
-    } else {
-      const result = await agent.generate(ctx, state.output, agentCallOpts);
-      const hookParams = {
-        mode: "generate",
-        result,
-        ctx,
-        input
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      };
-      if (options?.onResult) {
-        await options.onResult(hookParams);
-      }
-      if (options?.mapResult) {
-        state.output = await options.mapResult(hookParams);
-      } else {
-        state.output = await extractOutput(result, hasStructuredOutput, agent.validateOutput);
-      }
-    }
   }
   // ── Gate: load persisted state for resumption ──────────────────
   loadState(gateId, snapshot) {
@@ -1010,6 +1611,31 @@ var SealedWorkflow = class _SealedWorkflow {
       );
     }
     this.ensureDuplicateCheck();
+    const nestedPath = gateLike.nestedPath;
+    if (nestedPath && nestedPath.length > 0) {
+      let steps = this.steps;
+      for (const idx of nestedPath) {
+        const child = steps[idx]?.nestedWorkflow;
+        if (!child) {
+          throw new Error(`loadState: nested gate "${gateId}" path is stale \u2014 step ${idx} is not a nested workflow.`);
+        }
+        steps = child.getStepsForShapeHash();
+      }
+      const innerGate = steps[gateLike.resumeFromIndex];
+      if (!(innerGate instanceof GateStep) || innerGate.id !== gateId) {
+        throw new Error(`loadState: nested gate "${gateId}" not found at the recorded path.`);
+      }
+      const remaining = [...nestedPath.slice(1), gateLike.resumeFromIndex + 1];
+      return new ResumedWorkflow(this.steps, nestedPath[0], {
+        mode: "gate",
+        schema: innerGate.schema,
+        mergeFn: innerGate.merge,
+        priorOutput: gateLike.output,
+        snapshot: gateLike,
+        observability: this.observability,
+        nestedRemaining: remaining
+      });
+    }
     const gateIndex = this.findGateIndex(gateLike);
     const gateNode = this.steps[gateIndex];
     return new ResumedWorkflow(this.steps, gateIndex + 1, {
@@ -1060,25 +1686,19 @@ var SealedWorkflow = class _SealedWorkflow {
       this.ensureDuplicateCheck();
     }
     return new CheckpointResumedWorkflow(this.steps, idx, {
-      mode: "checkpoint",
       priorOutput: ckpt.output,
-      snapshot: ckpt,
       observability: this.observability
     });
   }
   /**
    * Append a `.finally()` body to a sealed workflow, returning another sealed
    * workflow. Allows multi-finally chains (`.finally().finally()`). A throwing
-   * `.finally` body does NOT abort subsequent ones — they all run.
+   * `.finally` body bubbles straight out of the run: it is non-recoverable, does
+   * NOT aggregate with a prior error, and subsequent `.finally()` bodies do not
+   * run. (See {@link FinallyStep} for the full contract.)
    */
   finally(id, fn) {
-    const node = {
-      type: "finally",
-      id,
-      execute: async (state) => {
-        await fn({ ctx: state.ctx });
-      }
-    };
+    const node = new FinallyStep(id, fn);
     return new _SealedWorkflow([...this.steps, node], this.id, this.observability);
   }
   findGateIndex(snapshot) {
@@ -1108,6 +1728,7 @@ var ResumedWorkflow = class extends SealedWorkflow {
   schema;
   mergeFn;
   priorOutput;
+  nestedRemaining;
   /** @internal */
   constructor(steps, startIndex, config) {
     super(steps, void 0, config.observability);
@@ -1115,6 +1736,7 @@ var ResumedWorkflow = class extends SealedWorkflow {
     this.schema = config.schema;
     this.mergeFn = config.mergeFn;
     this.priorOutput = config.priorOutput;
+    this.nestedRemaining = config.nestedRemaining;
   }
   validateResponse(response) {
     if (this.schema) {
@@ -1122,77 +1744,39 @@ var ResumedWorkflow = class extends SealedWorkflow {
     }
     return response;
   }
-  async generate(ctx, ...args) {
-    const rawResponse = args[0];
-    const opts = args[1];
-    let output = this.priorOutput;
-    let initialError = null;
+  /**
+   * Seed the run by validating the gate response and merging it with the
+   * suspended output. Runs schema.parse + mergeFn inside a try so a failure
+   * becomes a pre-execute `initialError` (routed through `.catch()`) rather
+   * than escaping the run synchronously. On error the output falls back to the
+   * prior (pre-gate) output.
+   */
+  async seedFromResponse(rawResponse) {
     try {
       const response = this.validateResponse(rawResponse);
-      output = this.mergeFn ? await this.mergeFn({ priorOutput: this.priorOutput, response }) : response;
+      const merged = this.mergeFn ? await this.mergeFn({ priorOutput: this.priorOutput, response }) : response;
+      if (this.nestedRemaining) {
+        return {
+          output: this.priorOutput,
+          initialError: null,
+          resumeDescent: { remaining: this.nestedRemaining, seedOutput: merged }
+        };
+      }
+      return { output: merged, initialError: null };
     } catch (error) {
-      initialError = { error, stepId: "gate:resume", source: "step" };
-    }
-    const state = {
-      ctx,
-      output,
-      mode: "generate",
-      runOptions: opts,
-      abortSignal: opts?.abortSignal
-    };
-    await this.execute(state, this.startIndex, opts, initialError);
-    return this.buildResult(state);
+      return { output: this.priorOutput, initialError: { error, stepId: GATE_RESUME_STEP_ID, source: "step" } };
+    }
+  }
+  async generate(ctx, ...args) {
+    const rawResponse = args[0];
+    const opts = args[1];
+    return this.runGenerate(ctx, this.startIndex, opts, () => this.seedFromResponse(rawResponse));
   }
   stream(ctx, ...args) {
     const rawResponse = args[0];
     const options = args[1];
     const opts = args[2];
-    const abortSignal = opts?.abortSignal;
-    let resolveOutput;
-    let rejectOutput;
-    const outputPromise = new Promise((res, rej) => {
-      resolveOutput = res;
-      rejectOutput = rej;
-    });
-    outputPromise.catch(() => {
-    });
-    const mergeFn = this.mergeFn;
-    const priorOutput = this.priorOutput;
-    const startIndex = this.startIndex;
-    const stream = createUIMessageStream({
-      execute: async ({ writer }) => {
-        let output = priorOutput;
-        let initialError = null;
-        try {
-          const response = this.validateResponse(rawResponse);
-          output = mergeFn ? await mergeFn({ priorOutput, response }) : response;
-        } catch (error) {
-          initialError = { error, stepId: "gate:resume", source: "step" };
-        }
-        const state = {
-          ctx,
-          output,
-          mode: "stream",
-          writer,
-          runOptions: opts,
-          abortSignal
-        };
-        try {
-          await this.execute(state, startIndex, opts, initialError);
-          const result = this.buildResult(state);
-          maybeWarnStreamOnErrorOnSuspend(result, options);
-          resolveOutput(result);
-        } catch (error) {
-          rejectOutput(error);
-          throw error;
-        }
-      },
-      ...options?.onError ? { onError: options.onError } : {},
-      ...options?.onFinish ? { onFinish: options.onFinish } : {},
-      ...options?.originalMessages ? { originalMessages: options.originalMessages } : {},
-      ...options?.generateId ? { generateId: options.generateId } : {}
-    });
-    return { stream, output: outputPromise };
+    return this.runStream(ctx, this.startIndex, opts, options, () => this.seedFromResponse(rawResponse));
   }
 };
 var CheckpointResumedWorkflow = class extends SealedWorkflow {
@@ -1208,64 +1792,22 @@ var CheckpointResumedWorkflow = class extends SealedWorkflow {
   // Inputs are ignored — state is seeded from the snapshot's `output` field.
   async generate(ctx, ...args) {
     const opts = args[1];
-    this.validateRunOptions(opts);
-    const state = {
-      ctx,
-      output: this.priorOutput,
-      mode: "generate",
-      runOptions: opts
-    };
-    await this.execute(state, this.startIndex, opts);
-    return this.buildResult(state);
+    return this.runGenerate(ctx, this.startIndex, opts, () => ({ output: this.priorOutput, initialError: null }));
   }
   stream(ctx, ...args) {
     const options = args[1];
     const opts = args[2];
-    this.validateRunOptions(opts);
-    let resolveOutput;
-    let rejectOutput;
-    const outputPromise = new Promise((res, rej) => {
-      resolveOutput = res;
-      rejectOutput = rej;
-    });
-    outputPromise.catch(() => {
-    });
-    const priorOutput = this.priorOutput;
-    const startIndex = this.startIndex;
-    const stream = createUIMessageStream({
-      execute: async ({ writer }) => {
-        const state = {
-          ctx,
-          output: priorOutput,
-          mode: "stream",
-          writer,
-          runOptions: opts
-        };
-        try {
-          await this.execute(state, startIndex, opts);
-          const result = this.buildResult(state);
-          maybeWarnStreamOnErrorOnSuspend(result, options);
-          resolveOutput(result);
-        } catch (error) {
-          rejectOutput(error);
-          throw error;
-        }
-      },
-      ...options?.onError ? { onError: options.onError } : {},
-      ...options?.onFinish ? { onFinish: options.onFinish } : {},
-      ...options?.originalMessages ? { originalMessages: options.originalMessages } : {},
-      ...options?.generateId ? { generateId: options.generateId } : {}
-    });
-    return { stream, output: outputPromise };
+    return this.runStream(ctx, this.startIndex, opts, options, () => ({ output: this.priorOutput, initialError: null }));
   }
 };
 var Workflow = class _Workflow extends SealedWorkflow {
   /**
-   * Sentinel value for `foreach`'s `onError` handler. Returning `Workflow.SKIP`
-   * from `onError` omits the failed item's index from the output array,
-   * shortening it relative to the input array.
+   * Sentinel value for `foreach`/`parallel`'s `onError` handler. Returning
+   * `Workflow.SKIP` omits the failed item (foreach: shortens the output array;
+   * parallel: leaves the slot `undefined`). Aliases the leaf-module `SKIP` so
+   * the step subclasses can compare against it without importing this class.
    */
-  static SKIP = /* @__PURE__ */ Symbol("pipeai.foreach.skip");
+  static SKIP = SKIP;
   constructor(steps = [], id, observability) {
     super(steps, id, observability);
   }
@@ -1276,26 +1818,20 @@ var Workflow = class _Workflow extends SealedWorkflow {
     return new _Workflow([]).step(agent, options);
   }
   // Builder helper — append a step and return a re-typed Workflow.
-  // Centralizes the `[...steps, node] as any` + new Workflow + observability/id
-  // forwarding pattern used by every combinator method.
   appendStep(node) {
     return new _Workflow([...this.steps, node], this.id, this.observability);
   }
   // ── step: implementation ──────────────────────────────────────
-  step(target, optionsOrFn) {
+  step(target, optionsOrFn, inlineOptions) {
     if (target instanceof SealedWorkflow) {
       const workflow = target;
-      const node2 = {
-        type: "step",
-        id: workflow.id ?? "nested-workflow",
-        nestedWorkflow: workflow,
-        // Feeds the recursive stepShapeHash walk.
-        category: "nested",
-        // Observability event type.
-        execute: async (state) => {
-          await this.executeNestedWorkflow(state, workflow);
-        }
-      };
+      const options2 = optionsOrFn;
+      const node2 = new NestedWorkflowStep(
+        options2?.id ?? workflow.id ?? "nested-workflow",
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        workflow,
+        options2
+      );
       return this.appendStep(node2);
     }
     if (typeof target === "string") {
@@ -1303,31 +1839,22 @@ var Workflow = class _Workflow extends SealedWorkflow {
         throw new Error(`Workflow step("${target}"): second argument must be a function`);
       }
       const fn = optionsOrFn;
-      const node2 = {
-        type: "step",
-        id: target,
-        execute: async (state) => {
-          state.output = await fn({
-            ctx: state.ctx,
-            input: state.output,
-            // Present in stream mode (undefined in generate mode), letting the
-            // inline step emit UIMessageChunk parts onto the workflow's stream.
-            writer: state.writer
-          });
-        }
-      };
+      const node2 = new TransformStep(
+        target,
+        fn,
+        inlineOptions
+      );
       return this.appendStep(node2);
     }
     const agent = target;
     const options = optionsOrFn;
-    const node = {
-      type: "step",
-      id: options?.id ?? agent.id,
-      execute: async (state) => {
-        const ctx = state.ctx;
-        await this.executeAgent(state, agent, ctx, options);
-      }
-    };
+    const node = new AgentStep(
+      options?.id ?? agent.id,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      agent,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      options
+    );
     return this.appendStep(node);
   }
   // ── gate: human-in-the-loop suspension point ────────────────
@@ -1335,467 +1862,57 @@ var Workflow = class _Workflow extends SealedWorkflow {
     if (this.steps.some((s) => s.type === "gate" && s.id === id)) {
       throw new Error(`Workflow: duplicate gate ID "${id}". Each gate must have a unique identifier.`);
     }
-    const node = {
-      type: "gate",
-      id,
-      schema: options?.schema,
-      condition: options?.condition ? async (state) => options.condition({
-        ctx: state.ctx,
-        input: state.output
-      }) : void 0,
-      merge: options?.merge ? (params) => options.merge(params) : void 0,
-      payload: async (state) => {
-        if (options?.payload) {
-          return options.payload({
-            ctx: state.ctx,
-            input: state.output
-          });
-        }
-        return state.output;
-      }
-    };
+    const node = new GateStep(id, options);
     return this.appendStep(node);
   }
   // ── branch: implementation ────────────────────────────────────
   branch(casesOrConfig, options) {
-    if (Array.isArray(casesOrConfig)) {
-      return this.branchPredicate(casesOrConfig, options?.id);
-    }
-    return this.branchSelect(casesOrConfig, options?.id);
-  }
-  branchPredicate(cases, explicitId) {
-    const node = {
-      type: "step",
-      id: explicitId ?? "branch:predicate",
-      category: "branch",
-      execute: async (state) => {
-        const ctx = state.ctx;
-        const input = state.output;
-        for (const branchCase of cases) {
-          if (branchCase.when) {
-            const match = await branchCase.when({ ctx, input });
-            if (!match) continue;
-          }
-          await this.executeAgent(state, branchCase.agent, ctx, branchCase);
-          return;
-        }
-        let inputRepr;
-        try {
-          inputRepr = JSON.stringify(input);
-          if (inputRepr === void 0) inputRepr = String(input);
-        } catch {
-          inputRepr = `[unserializable ${typeof input}]`;
-        }
-        throw new WorkflowBranchError("predicate", `No branch matched and no default branch (a case without \`when\`) was provided. Input: ${inputRepr}`);
-      }
-    };
-    return this.appendStep(node);
-  }
-  branchSelect(config, explicitId) {
-    const node = {
-      type: "step",
-      id: explicitId ?? "branch:select",
-      category: "branch",
-      execute: async (state) => {
-        const ctx = state.ctx;
-        const input = state.output;
-        const key = await config.select({ ctx, input });
-        const keyDeclared = Object.prototype.hasOwnProperty.call(config.agents, key);
-        if (keyDeclared && config.agents[key] === void 0) {
-          throw new WorkflowBranchError(
-            "select",
-            `Agent for key "${key}" was declared but the value is undefined. This usually means a conditional spread set the value to undefined. Available keys: ${Object.keys(config.agents).join(", ")}`
-          );
-        }
-        let agent = keyDeclared ? config.agents[key] : void 0;
-        if (!agent) {
-          if (config.onUnknownKey) {
-            config.onUnknownKey({
-              key,
-              availableKeys: Object.keys(config.agents),
-              ctx
-            });
-          }
-          if (config.fallback) {
-            agent = config.fallback;
-          } else {
-            throw new WorkflowBranchError("select", `No agent found for key "${key}" and no fallback provided. Available keys: ${Object.keys(config.agents).join(", ")}`);
-          }
-        }
-        await this.executeAgent(state, agent, ctx, config);
-      }
-    };
+    const node = Array.isArray(casesOrConfig) ? new PredicateBranchStep(options?.id ?? "branch:predicate", casesOrConfig) : new SelectBranchStep(options?.id ?? "branch:select", casesOrConfig);
     return this.appendStep(node);
   }
-  // ── foreach: array iteration ─────────────────────────────────
-  /**
-   * Map each item of an array through an agent or sub-workflow.
-   *
-   * @param target Agent or `SealedWorkflow` invoked once per item.
-   * @param options.id Override the default step id (`foreach:<agentId>` or
-   *   the workflow's id). Required when chaining multiple foreach over the same
-   *   target — the construction-time `(type, id)` walk rejects duplicates.
-   * @param options.concurrency Max items in flight at any moment (default 1).
-   *   Backed by a semaphore: as soon as one item completes, the next launches —
-   *   no lockstep batching.
-   * @param options.onError Per-iteration error handler. **Bypassed entirely on
-   *   the suspension path** (when any item hits a nested gate) — see the
-   *   foreach concurrency hazards in the README. Otherwise: return a
-   *   `TNextOutput` value to substitute, return `Workflow.SKIP` to omit, throw
-   *   to abort. Invoked sequentially in index order after all items settle.
-   */
+  // Implementation
   foreach(target, options) {
-    const concurrency = options?.concurrency ?? 1;
-    const onError = options?.onError;
-    const isWorkflow = target instanceof SealedWorkflow;
-    const defaultId = isWorkflow ? target.id ?? "foreach" : `foreach:${target.id}`;
-    const id = options?.id ?? defaultId;
-    const node = {
-      type: "step",
-      id,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      nestedWorkflow: isWorkflow ? target : void 0,
-      category: "foreach",
-      execute: async (state) => {
-        const items = state.output;
-        if (!Array.isArray(items)) {
-          throw new Error(`foreach "${id}": expected array input, got ${typeof items}`);
-        }
-        const ctx = state.ctx;
-        const results = new Array(items.length);
-        const skipped = /* @__PURE__ */ new Set();
-        const itemStates = new Array(items.length);
-        const executeItem = async (item, index) => {
-          const itemState = {
-            ctx: state.ctx,
-            output: item,
-            mode: "generate",
-            abortSignal: state.abortSignal
-          };
-          itemStates[index] = itemState;
-          const itemStart = performance.now();
-          await this.fireHook(state, "onItemStart", {
-            stepId: id,
-            type: "foreach",
-            itemIndex: index,
-            ctx: state.ctx,
-            input: item
-          });
-          try {
-            if (isWorkflow) {
-              await this.executeNestedWorkflow(itemState, target);
-            } else {
-              await this.executeAgent(itemState, target, ctx);
-            }
-            results[index] = itemState.output;
-            await this.fireHook(state, "onItemFinish", {
-              stepId: id,
-              type: "foreach",
-              itemIndex: index,
-              ctx: state.ctx,
-              output: itemState.output,
-              durationMs: performance.now() - itemStart
-            });
-          } catch (error) {
-            await this.fireHook(state, "onItemError", {
-              stepId: id,
-              type: "foreach",
-              itemIndex: index,
-              ctx: state.ctx,
-              error,
-              durationMs: performance.now() - itemStart
-            });
-            throw error;
-          }
-        };
-        const mergeItemWarnings = () => {
-          for (let idx = 0; idx < items.length; idx++) {
-            const its = itemStates[idx];
-            if (!its?.warnings) continue;
-            for (const w of its.warnings) {
-              pushWarning(state, w.source, `${id}[${idx}]:${w.stepId}`, w.error);
-            }
-          }
-        };
-        const handleRejection = async (error, item, index) => {
-          if (!onError) throw error;
-          const recovered = await onError({
-            error,
-            item,
-            index,
-            ctx: state.ctx
-          });
-          if (recovered === _Workflow.SKIP) {
-            skipped.add(index);
-          } else {
-            results[index] = recovered;
-          }
-        };
-        const failures = [];
-        const signal = state.abortSignal;
-        if (concurrency <= 1) {
-          for (let i = 0; i < items.length; i++) {
-            if (signal?.aborted) {
-              failures.push({ index: i, error: signal.reason ?? new Error("Workflow aborted") });
-              continue;
-            }
-            try {
-              await executeItem(items[i], i);
-            } catch (error) {
-              failures.push({ index: i, error });
-            }
-          }
-        } else {
-          let nextIndex = 0;
-          const worker = async () => {
-            while (true) {
-              const i = nextIndex++;
-              if (i >= items.length) return;
-              if (signal?.aborted) {
-                failures.push({ index: i, error: signal.reason ?? new Error("Workflow aborted") });
-                continue;
-              }
-              try {
-                await executeItem(items[i], i);
-              } catch (error) {
-                failures.push({ index: i, error });
-              }
-            }
-          };
-          const workers = Array.from(
-            { length: Math.min(concurrency, items.length) },
-            () => worker()
-          );
-          await Promise.all(workers);
-        }
-        failures.sort((a, b) => a.index - b.index);
-        const gateFailures = [];
-        const nonGateFailures = [];
-        for (const f of failures) {
-          if (f.error instanceof NestedGateUnsupportedError) {
-            gateFailures.push({ index: f.index, error: f.error });
-          } else {
-            nonGateFailures.push(f);
-          }
-        }
-        mergeItemWarnings();
-        if (gateFailures.length > 0) {
-          for (const nr of nonGateFailures) {
-            pushWarning(state, "foreach-sibling", `${id}[${nr.index}]`, nr.error);
-          }
-          const lowest = gateFailures[0];
-          const otherSuspensions = gateFailures.slice(1).map((g) => ({
-            index: g.index,
-            gateId: g.error.gateId
-          }));
-          const siblingErrors = nonGateFailures.map((nr) => nr.error);
-          throw new NestedGateUnsupportedError(
-            lowest.error.gateId,
-            lowest.error.workflowId,
-            siblingErrors,
-            otherSuspensions
-          );
-        }
-        for (const { index, error } of nonGateFailures) {
-          await handleRejection(error, items[index], index);
-        }
-        state.output = skipped.size === 0 ? results : results.filter((_, i) => !skipped.has(i));
-      }
-    };
+    const body = typeof target === "function" ? target(_Workflow.create({ observability: this.observability })) : target;
+    const node = new ForeachStep(body, options, this.observability);
     return this.appendStep(node);
   }
   // Implementation
   parallel(branches, options) {
-    const isTuple = Array.isArray(branches);
-    const entries = isTuple ? branches.map((target, i) => ({ key: i, index: i, target })) : Object.entries(branches).map(([k, t], i) => ({ key: k, index: i, target: t }));
-    const branchCount = entries.length;
-    const requestedConcurrency = options?.concurrency;
-    let effectiveConcurrency;
-    if (requestedConcurrency === void 0) {
-      effectiveConcurrency = Math.min(branchCount, 5);
-    } else {
-      effectiveConcurrency = requestedConcurrency;
-    }
-    if (requestedConcurrency === void 0 && branchCount > 5) {
-      warnOnce(
-        "pipeai:parallel-cap",
-        `pipeai: parallel() with ${branchCount} branches capped at concurrency 5 by default. Pass { concurrency: ${branchCount} } (or Infinity) to opt in, or set { concurrency: N } if you want fewer.`
-      );
-    }
-    const onError = options?.onError;
-    const id = options?.id ?? (isTuple ? "parallel:tuple" : "parallel:record");
-    const node = {
-      type: "step",
-      id,
-      category: "parallel",
-      execute: async (state) => {
-        const ctx = state.ctx;
-        const input = state.output;
-        const results = isTuple ? new Array(branchCount) : {};
-        const branchStates = new Array(branchCount);
-        const executeBranch = async ({ key, index, target }) => {
-          const branchState = { ctx: state.ctx, output: input, mode: "generate" };
-          branchStates[index] = branchState;
-          const branchStart = performance.now();
-          const itemIndex = isTuple ? index : key;
-          await this.fireHook(state, "onItemStart", {
-            stepId: id,
-            type: "parallel",
-            itemIndex,
-            ctx: state.ctx,
-            input
-          });
-          try {
-            if (target instanceof SealedWorkflow) {
-              await this.executeNestedWorkflow(branchState, target);
-            } else {
-              await this.executeAgent(branchState, target, ctx);
-            }
-            results[key] = branchState.output;
-            await this.fireHook(state, "onItemFinish", {
-              stepId: id,
-              type: "parallel",
-              itemIndex,
-              ctx: state.ctx,
-              output: branchState.output,
-              durationMs: performance.now() - branchStart
-            });
-          } catch (error) {
-            await this.fireHook(state, "onItemError", {
-              stepId: id,
-              type: "parallel",
-              itemIndex,
-              ctx: state.ctx,
-              error,
-              durationMs: performance.now() - branchStart
-            });
-            throw error;
-          }
-        };
-        const failures = [];
-        const eff = Number.isFinite(effectiveConcurrency) ? Math.max(1, effectiveConcurrency) : branchCount;
-        if (eff <= 1) {
-          for (const e of entries) {
-            try {
-              await executeBranch(e);
-            } catch (error) {
-              failures.push({ key: e.key, index: e.index, error });
-            }
-          }
-        } else {
-          let nextIndex = 0;
-          const worker = async () => {
-            while (true) {
-              const i = nextIndex++;
-              if (i >= branchCount) return;
-              const e = entries[i];
-              try {
-                await executeBranch(e);
-              } catch (error) {
-                failures.push({ key: e.key, index: e.index, error });
-              }
-            }
-          };
-          const workers = Array.from(
-            { length: Math.min(eff, branchCount) },
-            () => worker()
-          );
-          await Promise.all(workers);
-        }
-        for (let idx = 0; idx < branchCount; idx++) {
-          const bs = branchStates[idx];
-          if (!bs?.warnings) continue;
-          for (const w of bs.warnings) {
-            pushWarning(state, w.source, `${id}[${entries[idx].key}]:${w.stepId}`, w.error);
-          }
-        }
-        const gateFailures = [];
-        const nonGateFailures = [];
-        for (const f of failures) {
-          if (f.error instanceof NestedGateUnsupportedError) gateFailures.push({ key: f.key, index: f.index, error: f.error });
-          else nonGateFailures.push(f);
-        }
-        gateFailures.sort((a, b) => a.index - b.index);
-        nonGateFailures.sort((a, b) => a.index - b.index);
-        if (gateFailures.length > 0) {
-          for (const nr of nonGateFailures) {
-            pushWarning(state, "foreach-sibling", `${id}[${nr.key}]`, nr.error);
-          }
-          const lowest = gateFailures[0];
-          const otherSuspensions = gateFailures.slice(1).map((g) => ({ index: g.index, gateId: g.error.gateId }));
-          const siblingErrors = nonGateFailures.map((nr) => nr.error);
-          throw new NestedGateUnsupportedError(
-            lowest.error.gateId,
-            lowest.error.workflowId,
-            siblingErrors,
-            otherSuspensions
-          );
-        }
-        for (const { key, index, error } of nonGateFailures) {
-          if (!onError) throw error;
-          const recovered = await onError({
-            error,
-            key: isTuple ? void 0 : key,
-            index: isTuple ? index : void 0,
-            ctx: state.ctx
-          });
-          if (recovered === _Workflow.SKIP) {
-            results[key] = void 0;
-          } else {
-            results[key] = recovered;
-          }
-        }
-        state.output = results;
-      }
-    };
+    const node = new ParallelStep(branches, options, this.observability);
     return this.appendStep(node);
   }
   // ── repeat: conditional loop ─────────────────────────────────
   repeat(target, options) {
+    if (options.maxIterations !== void 0 && (!Number.isInteger(options.maxIterations) || options.maxIterations < 1)) {
+      throw new Error(`repeat: maxIterations must be a positive integer, got ${options.maxIterations}`);
+    }
+    if (options.until === void 0 === (options.while === void 0)) {
+      throw new Error("repeat: requires exactly one of `until` or `while`");
+    }
     const maxIterations = options.maxIterations ?? 10;
     const isWorkflow = target instanceof SealedWorkflow;
     const defaultId = isWorkflow ? target.id ?? "repeat" : `repeat:${target.id}`;
     const id = options.id ?? defaultId;
     const predicate = options.until ?? (async (p) => !await options.while(p));
-    const node = {
-      type: "step",
+    const node = new RepeatStep(
       id,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      nestedWorkflow: isWorkflow ? target : void 0,
-      category: "repeat",
-      execute: async (state) => {
-        const ctx = state.ctx;
-        for (let i = 1; i <= maxIterations; i++) {
-          if (state.abortSignal?.aborted) {
-            throw state.abortSignal.reason ?? new Error("Workflow aborted");
-          }
-          if (isWorkflow) {
-            await this.executeNestedWorkflow(state, target);
-          } else {
-            await this.executeAgent(state, target, ctx);
-          }
-          const done = await predicate({
-            output: state.output,
-            ctx,
-            iterations: i
-          });
-          if (done) return;
-        }
-        throw new WorkflowLoopError(maxIterations, maxIterations);
-      }
-    };
+      target,
+      predicate,
+      maxIterations,
+      isWorkflow
+    );
     return this.appendStep(node);
   }
   // ── catch ─────────────────────────────────────────────────────
   catch(id, fn) {
-    if (!this.steps.some((s) => s.type === "step")) {
-      throw new Error(`Workflow: catch("${id}") requires at least one preceding step.`);
+    if (!this.steps.some((s) => s.type === "step" || s.type === "gate")) {
+      throw new Error(`Workflow: catch("${id}") requires at least one preceding step or gate.`);
     }
-    const node = {
-      type: "catch",
+    const node = new CatchStep(
       id,
-      catchFn: fn
-    };
+      fn
+    );
     return this.appendStep(node);
   }
   // `.finally()` is inherited from SealedWorkflow now (it lives there so
@@ -1803,20 +1920,19 @@ var Workflow = class _Workflow extends SealedWorkflow {
 };
 
 // src/index.ts
-var SKIP = Workflow.SKIP;
+var SKIP2 = Workflow.SKIP;
 export {
+  ABORT_STEP_ID,
   Agent,
   CHECKPOINT_STEP_ID,
-  CheckpointTimeoutError,
-  NestedGateUnsupportedError,
-  SKIP,
+  GATE_RESUME_STEP_ID,
+  SKIP2 as SKIP,
   TOOL_PROVIDER_BRAND,
   ToolProvider,
   Workflow,
   WorkflowBranchError,
   WorkflowLoopError,
   defineTool,
-  getActiveWriter,
   isToolProvider,
   migrateSnapshot
 };