pipeai 0.8.2 → 0.8.4

package/dist/index.js

@@ -355,6 +355,847 @@ var Agent = class {
 import {
   createUIMessageStream
 } from "ai";
+
+// src/steps/step.ts
+var Step = class {
+  // Note: `type: "step"` subclasses (agent / transform / nested / branch /
+  // foreach / repeat / parallel) also carry a `readonly category` that the run
+  // loop reads (`getObservabilityType`) to type observability events. It is not
+  // declared on this base — the `StepNode` union in `workflow.ts` redeclares the
+  // node shape, so `category` is part of that structural contract rather than
+  // this class. Subclasses add it directly.
+  /**
+   * 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 — the only method the run loop invokes. Each kind overrides
+   * it to do its work, run its own skip checks, 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: return `true` when this step should be skipped silently
+   * (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) {
+    if (this.shouldSkip(state)) return;
+    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) {
+    if (this.shouldSkip(state)) return;
+    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/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) {
+    if (this.shouldSkip(state)) return;
+    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 };
+    }
+  }
+};
+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) {
+    if (this.shouldSkip(state)) return;
+    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/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++;
+    }
+  }
+  async run(fn) {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+};
+
+// src/steps/concurrent.ts
+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";
+  id;
+  nestedWorkflow;
+  target;
+  concurrency;
+  onError;
+  handleStream;
+  isWorkflow;
+  inheritStreaming;
+  observability;
+  constructor(target, options, observability) {
+    super();
+    if (options?.concurrency !== void 0 && !(Number.isInteger(options.concurrency) && options.concurrency >= 1 || options.concurrency === Infinity)) {
+      throw new Error(`foreach: concurrency must be a positive integer or Infinity, got ${options.concurrency}`);
+    }
+    this.target = target;
+    this.concurrency = options?.concurrency ?? Infinity;
+    this.onError = options?.onError;
+    this.handleStream = options?.handleStream;
+    this.observability = observability;
+    this.isWorkflow = target instanceof SealedWorkflow;
+    this.inheritStreaming = this.isWorkflow || this.handleStream !== void 0;
+    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) {
+    if (this.shouldSkip(state)) return;
+    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 skipped = /* @__PURE__ */ new Set();
+      const itemStates = new Array(items.length);
+      const wantItemHooks = hasItemHooks(this.observability);
+      const executeItem = async (item, index) => {
+        const itemState = {
+          ctx: state.ctx,
+          output: item,
+          mode: this.inheritStreaming ? state.mode : "generate",
+          writer: this.inheritStreaming ? state.writer : void 0,
+          abortSignal: state.abortSignal
+        };
+        itemStates[index] = itemState;
+        const itemStart = wantItemHooks ? performance.now() : 0;
+        if (wantItemHooks) {
+          await fireHook(this.observability, state, "onItemStart", {
+            stepId: this.id,
+            type: "foreach",
+            itemIndex: index,
+            ctx: state.ctx,
+            input: item
+          });
+        }
+        try {
+          if (this.isWorkflow) {
+            await this.target.executeAsNested(itemState);
+          } else {
+            await AgentStep.runAgent(
+              itemState,
+              this.target,
+              state.ctx,
+              this.handleStream ? { handleStream: this.handleStream } : void 0,
+              index
+            );
+          }
+          results[index] = itemState.output;
+          if (wantItemHooks) {
+            await fireHook(this.observability, state, "onItemFinish", {
+              stepId: this.id,
+              type: "foreach",
+              itemIndex: index,
+              ctx: state.ctx,
+              output: itemState.output,
+              durationMs: performance.now() - itemStart
+            });
+          }
+        } catch (error) {
+          if (wantItemHooks) {
+            await fireHook(this.observability, state, "onItemError", {
+              stepId: this.id,
+              type: "foreach",
+              itemIndex: index,
+              ctx: state.ctx,
+              error,
+              durationMs: performance.now() - itemStart
+            });
+          }
+          throw error;
+        }
+      };
+      const sem = new Semaphore(this.concurrency);
+      const failures = [];
+      const inflight = /* @__PURE__ */ new Set();
+      for (let i = 0; i < items.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 executeItem(items[index], index);
+          } catch (error) {
+            failures.push({ key: index, 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);
+      const nonGateFailures = reconcileUnits(state, this.id, failures, items.length, (i) => i, itemStates, state.abortSignal);
+      for (const { index, error } of nonGateFailures) {
+        if (!this.onError) throw error;
+        const recovered = await this.onError({ error, item: items[index], index, ctx: state.ctx });
+        if (recovered === Workflow.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;
+  branchCount;
+  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 })) : Object.entries(branches).map(([k, t], i) => ({ key: k, index: i, target: t }));
+    this.branchCount = this.entries.length;
+    const requestedConcurrency = options?.concurrency;
+    if (requestedConcurrency !== void 0 && !(Number.isInteger(requestedConcurrency) && requestedConcurrency >= 1 || requestedConcurrency === Infinity)) {
+      throw new Error(`parallel: concurrency must be a positive integer or Infinity, got ${requestedConcurrency}`);
+    }
+    this.concurrency = requestedConcurrency ?? Infinity;
+    this.onError = options?.onError;
+    this.handleStream = options?.handleStream;
+    this.observability = observability;
+    this.id = options?.id ?? (this.isTuple ? "parallel:tuple" : "parallel:record");
+  }
+  async execute(state) {
+    if (this.shouldSkip(state)) return;
+    try {
+      const input = state.output;
+      const results = this.isTuple ? new Array(this.branchCount) : {};
+      const branchStates = new Array(this.branchCount);
+      const wantItemHooks = hasItemHooks(this.observability);
+      const executeBranch = async ({ key, index, target }) => {
+        const isWorkflowBranch = target instanceof SealedWorkflow;
+        const inheritStreaming = isWorkflowBranch || this.handleStream !== void 0;
+        const branchState = {
+          ctx: state.ctx,
+          output: input,
+          mode: inheritStreaming ? state.mode : "generate",
+          writer: inheritStreaming ? state.writer : void 0,
+          abortSignal: state.abortSignal
+        };
+        branchStates[index] = branchState;
+        const branchStart = wantItemHooks ? performance.now() : 0;
+        const itemIndex = this.isTuple ? index : key;
+        if (wantItemHooks) {
+          await fireHook(this.observability, state, "onItemStart", {
+            stepId: this.id,
+            type: "parallel",
+            itemIndex,
+            ctx: state.ctx,
+            input
+          });
+        }
+        try {
+          if (isWorkflowBranch) {
+            await target.executeAsNested(branchState);
+          } else {
+            await AgentStep.runAgent(
+              branchState,
+              target,
+              state.ctx,
+              this.handleStream ? { handleStream: this.handleStream } : void 0,
+              itemIndex
+            );
+          }
+          results[key] = branchState.output;
+          if (wantItemHooks) {
+            await fireHook(this.observability, state, "onItemFinish", {
+              stepId: this.id,
+              type: "parallel",
+              itemIndex,
+              ctx: state.ctx,
+              output: branchState.output,
+              durationMs: performance.now() - branchStart
+            });
+          }
+        } catch (error) {
+          if (wantItemHooks) {
+            await fireHook(this.observability, state, "onItemError", {
+              stepId: this.id,
+              type: "parallel",
+              itemIndex,
+              ctx: state.ctx,
+              error,
+              durationMs: performance.now() - branchStart
+            });
+          }
+          throw error;
+        }
+      };
+      const keyAt = (i) => this.entries[i].key;
+      const sem = new Semaphore(this.concurrency);
+      const failures = [];
+      const inflight = /* @__PURE__ */ new Set();
+      for (let i = 0; i < this.branchCount; i++) {
+        if (state.abortSignal?.aborted) break;
+        await sem.acquire();
+        if (state.abortSignal?.aborted) {
+          sem.release();
+          break;
+        }
+        const index = i;
+        const unit = (async () => {
+          try {
+            await executeBranch(this.entries[index]);
+          } catch (error) {
+            failures.push({ key: keyAt(index), 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);
+      const nonGateFailures = reconcileUnits(state, this.id, failures, this.branchCount, keyAt, branchStates, state.abortSignal);
+      for (const { key, index, error } of nonGateFailures) {
+        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
+        });
+        if (recovered === Workflow.SKIP) {
+          results[key] = void 0;
+        } else {
+          results[key] = 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, payload, schema, condition, merge) {
+    super();
+    this.id = id;
+    this.payload = payload;
+    this.schema = schema;
+    this.condition = condition;
+    this.merge = merge;
+  }
+  async execute(state) {
+    if (this.shouldSkip(state)) return;
+    try {
+      if (this.condition && !await this.condition(state)) return;
+      const snapshot = {
+        version: 2,
+        kind: "gate",
+        resumeFromIndex: state.stepIndex ?? -1,
+        output: state.output,
+        gateId: this.id,
+        gatePayload: await this.payload(state)
+      };
+      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) {
+    if (this.shouldSkip(state)) return;
+    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) {
+    if (this.shouldSkip(state)) return;
+    await this.fn({ ctx: state.ctx });
+  }
+};
+
+// src/steps/nested-workflow-step.ts
+var NestedWorkflowStep = class extends Step {
+  type = "step";
+  category = "nested";
+  id;
+  nestedWorkflow;
+  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;
+    }
+    if (this.shouldSkip(state)) 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";
+  id;
+  nestedWorkflow;
+  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) {
+    if (this.shouldSkip(state)) return;
+    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/runtime.ts
+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":
+      return "catch";
+    case "onCheckpoint":
+      return "step";
+  }
+}
+async function emitCheckpoint(state, opts, resumeFromIndex, stepShapeHash) {
+  if (!opts.onCheckpoint) return;
+  const willFreeze = resolveFreezeSnapshots(state);
+  const snap = {
+    version: 2,
+    kind: "checkpoint",
+    resumeFromIndex,
+    output: willFreeze ? structuredClone(state.output) : state.output,
+    stepShapeHash
+  };
+  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);
+}
+function maybeWarnStreamOnErrorOnSuspend(result, options) {
+  if (result.status !== "suspended" || !options?.onError || warnedStreamOnErrorOnSuspend) return;
+  warnedStreamOnErrorOnSuspend = true;
+  console.warn(
+    "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/workflow.ts
 var WorkflowBranchError = class extends Error {
   constructor(branchType, message) {
     super(message);
@@ -370,33 +1211,13 @@ 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;
-  }
-};
-function resolveFreezeSnapshots(state) {
-  return state.runOptions?.freezeSnapshots ? true : false;
+var ABORT_STEP_ID = "::pipeai::abort";
+var GATE_RESUME_STEP_ID = "::pipeai::gate:resume";
+function prependNestedPath(snapshot, index, state) {
+  const next = { ...snapshot, nestedPath: [index, ...snapshot.nestedPath ?? []] };
+  if (resolveFreezeSnapshots(state)) deepFreeze(next);
+  return next;
 }
 function migrateSnapshot(legacy) {
   if (legacy.version !== 1) {
@@ -425,67 +1246,6 @@ function getNestedWorkflows(node) {
       return [];
   }
 }
-function pendingErrorSourceToStepType(source) {
-  switch (source) {
-    case "step":
-      return "step";
-    case "finally":
-      return "finally";
-    case "catch":
-      return "catch";
-    case "onCheckpoint":
-      return "step";
-  }
-}
-async function emitCheckpoint(state, opts, resumeFromIndex, stepShapeHash) {
-  if (!opts.onCheckpoint) return;
-  const snap = {
-    version: 2,
-    kind: "checkpoint",
-    resumeFromIndex,
-    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 });
-  }
-}
-var warnedStreamOnErrorOnSuspend = false;
-function pushWarning(state, source, stepId, error) {
-  (state.warnings ??= []).push({ source, stepId, error });
-}
-function demotePendingError(state, pe) {
-  pushWarning(state, pe.source, pe.stepId, pe.error);
-}
-function maybeWarnStreamOnErrorOnSuspend(result, options) {
-  if (result.status !== "suspended" || !options?.onError || warnedStreamOnErrorOnSuspend) return;
-  warnedStreamOnErrorOnSuspend = true;
-  console.warn(
-    "pipeai: stream() with options.onError suspended at a gate \u2014 onError will NOT be invoked for suspension. Discriminate via the resolved output Promise."
-  );
-}
 var SealedWorkflow = class _SealedWorkflow {
   id;
   steps;
@@ -495,6 +1255,7 @@ var SealedWorkflow = class _SealedWorkflow {
   // Memoized lazily per terminal instance — build pipelines once at module
   // load and re-run via generate() to amortize.
   _cachedExecutableStepCount;
+  _cachedCheckpointableStepCount;
   _cachedStepShapeHash;
   constructor(steps, id, observability) {
     this.steps = steps;
@@ -545,6 +1306,24 @@ var SealedWorkflow = class _SealedWorkflow {
     this._cachedExecutableStepCount = n;
     return n;
   }
+  /**
+   * Count of *checkpointable* nodes — `type === "step"` only (this includes
+   * `branch`/`foreach`/`repeat`/`parallel`/`nested`, all internally `step`).
+   * Drives the checkpoint auto-cadence denominator. Distinct from
+   * {@link cachedExecutableStepCount}, which also counts `gate` nodes: gates
+   * suspend/skip and never reach the checkpoint block, so the runtime
+   * `executableStepsSeen` counter never advances on them. Counting gates in
+   * the denominator would dilute the "~4 checkpoints across the run" target.
+   */
+  get cachedCheckpointableStepCount() {
+    if (this._cachedCheckpointableStepCount !== void 0) return this._cachedCheckpointableStepCount;
+    let n = 0;
+    for (const s of this.steps) {
+      if (s.type === "step") n++;
+    }
+    this._cachedCheckpointableStepCount = n;
+    return n;
+  }
   /** @internal — used by `computeStepShapeHash` to descend nested workflows. */
   getStepsForShapeHash() {
     return this.steps;
@@ -575,11 +1354,8 @@ var SealedWorkflow = class _SealedWorkflow {
     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}`);
-    }
     const length = this.cachedExecutableStepCount;
-    const cadence = opts.checkpointEvery ?? Math.max(1, Math.ceil(length / 4));
+    const cadence = opts.checkpointEvery ?? Math.max(1, Math.ceil(this.cachedCheckpointableStepCount / 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".`
@@ -607,47 +1383,82 @@ var SealedWorkflow = class _SealedWorkflow {
    * `await` the result — `await undefined` is sync, so the no-hook path
    * stays allocation-free.
    */
+  // Thin delegates to the free `fireHook` / `hasItemHooks` (which take an
+  // explicit observability). Kept as methods so the loop's many `this.fireHook`
+  // call sites stay unchanged; bare `fireHook` / `hasItemHooks` below resolve to
+  // the module-level functions, not these members.
   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);
+  hasItemHooks() {
+    return hasItemHooks(this.observability);
+  }
+  /**
+   * 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 +1469,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 +1487,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,12 +1497,13 @@ 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;
+    const ckptCadence = opts?.onCheckpoint && opts.checkpointWhen === void 0 ? opts.checkpointEvery ?? Math.max(1, Math.ceil(this.cachedCheckpointableStepCount / 4)) : 0;
+    let executableStepsSeen = 0;
+    state.pendingError = initialError ?? void 0;
     let abortPromoted = false;
     const makeAbortError = (signal) => ({
       error: signal.reason ?? new Error("Workflow aborted"),
-      stepId: "abort",
+      stepId: ABORT_STEP_ID,
       source: "step"
     });
     for (let i = startIndex; i < this.steps.length; i++) {
@@ -719,152 +1511,61 @@ var SealedWorkflow = class _SealedWorkflow {
         if (!abortPromoted) {
           abortPromoted = true;
           state.suspension = void 0;
-          if (pendingError) demotePendingError(state, pendingError);
-          pendingError = makeAbortError(state.abortSignal);
-        } else if (!pendingError) {
-          pendingError = makeAbortError(state.abortSignal);
+          if (state.pendingError) demotePendingError(state, state.pendingError);
+          state.pendingError = makeAbortError(state.abortSignal);
+        } else if (!state.pendingError) {
+          state.pendingError = makeAbortError(state.abortSignal);
         }
       }
       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 skip = node.type === "finally" ? false : node.type === "catch" ? !!state.suspension || !state.pendingError || !!state.checkpointFailed : !!state.suspension || !!state.pendingError;
+      if (skip) continue;
       const obsType = getObservabilityType(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;
+      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 (node.type === "step" && !state.pendingError && !state.suspension && opts?.onCheckpoint) {
+        executableStepsSeen++;
+        const shouldCheckpoint = opts.checkpointWhen ? opts.checkpointWhen({ stepIndex: i, stepId: node.id, ctx: state.ctx }) : executableStepsSeen % ckptCadence === 0;
         if (shouldCheckpoint) {
           const ckptStart = performance.now();
           try {
@@ -875,127 +1576,76 @@ var SealedWorkflow = class _SealedWorkflow {
               this.cachedStepShapeHash
             );
           } catch (e) {
-            pendingError = { error: e, stepId: CHECKPOINT_STEP_ID, source: "onCheckpoint" };
+            state.pendingError = { error: e, stepId: CHECKPOINT_STEP_ID, source: "onCheckpoint" };
             state.checkpointFailed = true;
-            await this.fireHook(state, "onStepError", {
+            await this.fireStepErrorAndAttachCause(state, {
               stepId: CHECKPOINT_STEP_ID,
               type: "step",
               ctx: state.ctx,
               error: e,
               durationMs: performance.now() - ckptStart
             });
-          }
-        }
-      }
-    }
-    if (pendingError && !state.suspension) {
-      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) {
-          console.warn(
-            `pipeai: ${all.length} .finally() error(s) suppressed by checkpoint-failure precedence:`,
-            all
-          );
-        }
-        throw checkpointError ?? pendingError.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);
-      try {
-        await this.observability?.onStepError?.({
-          stepId: pendingError.stepId,
-          type: pendingErrorSourceToStepType(pendingError.source),
-          ctx: state.ctx,
-          error: pendingError.error,
-          durationMs: 0
-        });
-      } catch (obsError) {
-        pushWarning(state, "onStepError", pendingError.stepId, obsError);
-      }
-      pendingError = null;
-    }
-  }
-  // ── 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) {
-    const savedRunOptions = state.runOptions;
-    state.runOptions = void 0;
-    try {
-      await workflow.execute(state);
-    } 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);
+    }
+    if (abortPromoted && !state.pendingError && !state.suspension && state.abortSignal?.aborted) {
+      state.pendingError = makeAbortError(state.abortSignal);
+    }
+    if (state.pendingError && !state.suspension) {
+      const pe = state.pendingError;
+      if (state.checkpointFailed) {
+        const warningsArr = state.warnings ?? [];
+        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: ${suppressed.length} error(s) suppressed by checkpoint-failure precedence:`,
+            suppressed
+          );
+        }
+        throw checkpointError ?? pe.error;
+      }
+      throw pe.error;
+    } else if (state.pendingError && state.suspension) {
+      const pe = state.pendingError;
+      demotePendingError(state, pe);
+      try {
+        await this.observability?.onStepError?.({
+          stepId: pe.stepId,
+          type: pendingErrorSourceToStepType(pe.source),
+          ctx: state.ctx,
+          error: pe.error,
+          durationMs: 0
+        });
+      } catch (obsError) {
+        pushWarning(state, "onStepError", pe.stepId, obsError);
       }
+      state.pendingError = void 0;
+    }
+  }
+  /**
+   * 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 this.execute(state, startIndex);
+    } finally {
+      state.runOptions = savedRunOptions;
     }
   }
   // ── Gate: load persisted state for resumption ──────────────────
@@ -1010,6 +1660,32 @@ 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 node = steps[idx];
+        const child = node?.type === "step" ? node.nestedWorkflow : void 0;
+        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?.type !== "gate" || 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, {
@@ -1069,16 +1745,12 @@ var SealedWorkflow = class _SealedWorkflow {
   /**
    * 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 +1780,7 @@ var ResumedWorkflow = class extends SealedWorkflow {
   schema;
   mergeFn;
   priorOutput;
+  nestedRemaining;
   /** @internal */
   constructor(steps, startIndex, config) {
     super(steps, void 0, config.observability);
@@ -1115,6 +1788,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 +1796,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,55 +1844,12 @@ 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 {
@@ -1282,20 +1875,16 @@ var Workflow = class _Workflow extends SealedWorkflow {
     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 +1892,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,16 +1915,9 @@ 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",
+    const node = new GateStep(
       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) => {
+      async (state) => {
         if (options?.payload) {
           return options.payload({
             ctx: state.ctx,
@@ -1352,8 +1925,14 @@ var Workflow = class _Workflow extends SealedWorkflow {
           });
         }
         return state.output;
-      }
-    };
+      },
+      options?.schema,
+      options?.condition ? async (state) => options.condition({
+        ctx: state.ctx,
+        input: state.output
+      }) : void 0,
+      options?.merge ? (params) => options.merge(params) : void 0
+    );
     return this.appendStep(node);
   }
   // ── branch: implementation ────────────────────────────────────
@@ -1364,67 +1943,11 @@ var Workflow = class _Workflow extends SealedWorkflow {
     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}`);
-      }
-    };
+    const node = new PredicateBranchStep(explicitId ?? "branch:predicate", cases);
     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 = new SelectBranchStep(explicitId ?? "branch:select", config);
     return this.appendStep(node);
   }
   // ── foreach: array iteration ─────────────────────────────────
@@ -1435,367 +1958,63 @@ var Workflow = class _Workflow extends SealedWorkflow {
    * @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 —
+   * @param options.concurrency Max items in flight at any moment. **Default:
+   *   unbounded** (`Infinity` — every item runs concurrently, clamped only by
+   *   item count). Pass an integer to throttle against provider rate limits.
+   *   Backed by a worker pool: 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
+   *   the suspension path** (when any item hits a nested gate) **and on the
+   *   cancellation path** (the run was aborted — pre-abort failures become
+   *   `foreach-sibling` warnings and the abort reason rethrows) — 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.
+   *   A throw (or rethrow) from `onError` aborts the foreach immediately:
+   *   failures at indices AFTER the throwing one are neither recovered nor
+   *   surfaced as warnings.
    */
   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 node = new ForeachStep(target, 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
@@ -1805,10 +2024,10 @@ var Workflow = class _Workflow extends SealedWorkflow {
 // src/index.ts
 var SKIP = Workflow.SKIP;
 export {
+  ABORT_STEP_ID,
   Agent,
   CHECKPOINT_STEP_ID,
-  CheckpointTimeoutError,
-  NestedGateUnsupportedError,
+  GATE_RESUME_STEP_ID,
   SKIP,
   TOOL_PROVIDER_BRAND,
   ToolProvider,
@@ -1816,7 +2035,6 @@ export {
   WorkflowBranchError,
   WorkflowLoopError,
   defineTool,
-  getActiveWriter,
   isToolProvider,
   migrateSnapshot
 };