pipeai 0.8.4 → 0.9.0

package/dist/index.cjs

@@ -24,7 +24,7 @@ __export(index_exports, {
   Agent: () => Agent,
   CHECKPOINT_STEP_ID: () => CHECKPOINT_STEP_ID,
   GATE_RESUME_STEP_ID: () => GATE_RESUME_STEP_ID,
-  SKIP: () => SKIP,
+  SKIP: () => SKIP2,
   TOOL_PROVIDER_BRAND: () => TOOL_PROVIDER_BRAND,
   ToolProvider: () => ToolProvider,
   Workflow: () => Workflow,
@@ -52,6 +52,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);
@@ -291,7 +292,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 (0, import_ai2.streamText)({
         ...options,
         ...extra,
@@ -390,12 +399,19 @@ var import_ai3 = require("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.
+  /**
+   * 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
@@ -403,19 +419,20 @@ var Step = class {
    */
   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.
+   * 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: 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.
+   * 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;
@@ -451,7 +468,6 @@ var TransformStep = class extends Step {
     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({
@@ -482,7 +498,6 @@ var AgentStep = class _AgentStep extends Step {
     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);
@@ -553,6 +568,26 @@ var AgentStep = class _AgentStep extends Step {
   }
 };
 
+// src/errors.ts
+var WorkflowBranchError = class extends Error {
+  constructor(branchType, message) {
+    super(message);
+    this.branchType = branchType;
+    this.name = "WorkflowBranchError";
+  }
+};
+var WorkflowLoopError = class extends Error {
+  constructor(iterations, maxIterations) {
+    super(`Loop exceeded maximum iterations (${maxIterations})`);
+    this.iterations = iterations;
+    this.maxIterations = maxIterations;
+    this.name = "WorkflowLoopError";
+  }
+};
+var CHECKPOINT_STEP_ID = "::pipeai::onCheckpoint";
+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";
@@ -567,7 +602,6 @@ var PredicateBranchStep = class extends Step {
     this.cases = cases;
   }
   async execute(state) {
-    if (this.shouldSkip(state)) return;
     try {
       const ctx = state.ctx;
       const input = state.output;
@@ -606,7 +640,6 @@ var SelectBranchStep = class extends Step {
     this.config = config;
   }
   async execute(state) {
-    if (this.shouldSkip(state)) return;
     try {
       const ctx = state.ctx;
       const input = state.output;
@@ -641,6 +674,95 @@ var SelectBranchStep = class extends Step {
   }
 };
 
+// src/runtime.ts
+function makeAbortError(signal) {
+  return {
+    error: signal.reason ?? new Error("Workflow aborted"),
+    stepId: ABORT_STEP_ID,
+    source: "step"
+  };
+}
+function prependNestedPath(snapshot, index, state) {
+  const next = { ...snapshot, nestedPath: [index, ...snapshot.nestedPath ?? []] };
+  if (resolveFreezeSnapshots(state)) deepFreeze(next);
+  return next;
+}
+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/steps/semaphore.ts
 var Semaphore = class {
   available;
@@ -663,17 +785,103 @@ var Semaphore = class {
       this.available++;
     }
   }
-  async run(fn) {
-    await this.acquire();
-    try {
-      return await fn();
-    } finally {
-      this.release();
-    }
-  }
 };
 
 // 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];
@@ -701,128 +909,50 @@ function reconcileUnits(state, id, failures, count, keyAt, unitStates, signal) {
 var ForeachStep = class extends Step {
   type = "step";
   category = "foreach";
-  id;
   nestedWorkflow;
+  id;
   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.concurrency = validateConcurrency("foreach", options?.concurrency);
     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 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 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) {
+      });
+      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 === Workflow.SKIP) {
+        if (recovered === SKIP) {
           skipped.add(index);
         } else {
           results[index] = recovered;
@@ -842,7 +972,6 @@ var ParallelStep = class extends Step {
   id;
   entries;
   isTuple;
-  branchCount;
   concurrency;
   onError;
   handleStream;
@@ -850,112 +979,30 @@ var ParallelStep = class extends Step {
   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.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) {
-    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 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;
         }
-        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) {
+      });
+      for (const { key, index, error } of failures) {
         if (!this.onError) throw error;
         const recovered = await this.onError({
           error,
@@ -963,11 +1010,7 @@ var ParallelStep = class extends Step {
           index: this.isTuple ? index : void 0,
           ctx: state.ctx
         });
-        if (recovered === Workflow.SKIP) {
-          results[key] = void 0;
-        } else {
-          results[key] = recovered;
-        }
+        results[key] = recovered === SKIP ? void 0 : recovered;
       }
       state.output = results;
     } catch (error) {
@@ -987,25 +1030,25 @@ var GateStep = class extends Step {
   merge;
   payload;
   condition;
-  constructor(id, payload, schema, condition, merge) {
+  constructor(id, options) {
     super();
     this.id = id;
-    this.payload = payload;
-    this.schema = schema;
-    this.condition = condition;
-    this.merge = merge;
+    this.payload = options?.payload;
+    this.schema = options?.schema;
+    this.condition = options?.condition;
+    this.merge = options?.merge;
   }
   async execute(state) {
-    if (this.shouldSkip(state)) return;
     try {
-      if (this.condition && !await this.condition(state)) return;
+      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: await this.payload(state)
+        gatePayload: this.payload ? await this.payload(params) : state.output
       };
       state.suspension = snapshot;
       if (resolveFreezeSnapshots(state)) deepFreeze(snapshot);
@@ -1031,7 +1074,6 @@ var CatchStep = class extends Step {
     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,
@@ -1059,7 +1101,6 @@ var FinallyStep = class extends Step {
     return false;
   }
   async execute(state) {
-    if (this.shouldSkip(state)) return;
     await this.fn({ ctx: state.ctx });
   }
 };
@@ -1068,8 +1109,8 @@ var FinallyStep = class extends Step {
 var NestedWorkflowStep = class extends Step {
   type = "step";
   category = "nested";
-  id;
   nestedWorkflow;
+  id;
   options;
   constructor(id, workflow, options) {
     super();
@@ -1096,7 +1137,6 @@ var NestedWorkflowStep = class extends Step {
       }
       return;
     }
-    if (this.shouldSkip(state)) return;
     const myIndex = state.stepIndex ?? -1;
     try {
       if (await this.applyConditionalSkip(state, this.options)) return;
@@ -1112,8 +1152,8 @@ var NestedWorkflowStep = class extends Step {
 var RepeatStep = class extends Step {
   type = "step";
   category = "repeat";
-  id;
   nestedWorkflow;
+  id;
   target;
   predicate;
   maxIterations;
@@ -1128,7 +1168,6 @@ var RepeatStep = class extends Step {
     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++) {
@@ -1150,107 +1189,7 @@ var RepeatStep = class extends Step {
   }
 };
 
-// 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);
-    this.branchType = branchType;
-    this.name = "WorkflowBranchError";
-  }
-};
-var WorkflowLoopError = class extends Error {
-  constructor(iterations, maxIterations) {
-    super(`Loop exceeded maximum iterations (${maxIterations})`);
-    this.iterations = iterations;
-    this.maxIterations = maxIterations;
-    this.name = "WorkflowLoopError";
-  }
-};
-var CHECKPOINT_STEP_ID = "::pipeai::onCheckpoint";
-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) {
     throw new Error(`migrateSnapshot: expected v1 snapshot, got version ${legacy.version}`);
@@ -1264,30 +1203,15 @@ function migrateSnapshot(legacy) {
     gatePayload: legacy.gatePayload
   };
 }
-function getObservabilityType(node) {
-  if (node.type !== "step") return node.type;
-  return node.category ?? "step";
-}
-function getNestedWorkflows(node) {
-  switch (node.type) {
-    case "step":
-      return node.nestedWorkflow ? [node.nestedWorkflow] : [];
-    case "gate":
-    case "catch":
-    case "finally":
-      return [];
-  }
-}
 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;
-  _cachedCheckpointableStepCount;
+  // 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;
@@ -1322,39 +1246,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;
-  }
-  /**
-   * 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;
+    return this._stepCounts = { executable, checkpointable };
   }
   /** @internal — used by `computeStepShapeHash` to descend nested workflows. */
   getStepsForShapeHash() {
@@ -1362,7 +1273,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
@@ -1373,21 +1284,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}`);
     }
-    const length = this.cachedExecutableStepCount;
-    const cadence = opts.checkpointEvery ?? Math.max(1, Math.ceil(this.cachedCheckpointableStepCount / 4));
+    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.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".`
@@ -1401,6 +1320,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
@@ -1414,17 +1340,14 @@ 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.
    */
-  // 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) {
     return fireHook(this.observability, state, name, event);
   }
-  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,
@@ -1529,30 +1452,15 @@ 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.cachedCheckpointableStepCount / 4)) : 0;
-    let executableStepsSeen = 0;
+    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;
-    let abortPromoted = false;
-    const makeAbortError = (signal) => ({
-      error: signal.reason ?? new Error("Workflow aborted"),
-      stepId: ABORT_STEP_ID,
-      source: "step"
-    });
+    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 (state.pendingError) demotePendingError(state, state.pendingError);
-          state.pendingError = makeAbortError(state.abortSignal);
-        } else if (!state.pendingError) {
-          state.pendingError = makeAbortError(state.abortSignal);
-        }
-      }
+      this.promoteAbort(state, abortState);
       const node = this.steps[i];
-      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);
+      if (node.shouldSkip(state)) continue;
+      const obsType = this.obsEventType(node);
       const stepId = node.id;
       const sStart = performance.now();
       const errBefore = state.pendingError;
@@ -1572,7 +1480,9 @@ var SealedWorkflow = class _SealedWorkflow {
         throw e;
       }
       const newError = state.pendingError && state.pendingError !== errBefore ? state.pendingError : null;
-      if (newError) {
+      const isAbort = !!newError && state.abortSignal?.aborted === true && newError.error === state.abortSignal.reason;
+      if (isAbort) {
+      } else if (newError) {
         await this.fireStepErrorAndAttachCause(state, {
           stepId,
           type: obsType,
@@ -1595,32 +1505,73 @@ var SealedWorkflow = class _SealedWorkflow {
         state.suspension = void 0;
         throw new Error(`internal: suspension bubbled from non-gate step "${node.id}" (gate "${leaked.gateId}").`);
       }
-      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 {
-            await emitCheckpoint(
-              state,
-              opts,
-              i + 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
-            });
-          }
-        }
-      }
+      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);
     }
@@ -1696,15 +1647,14 @@ var SealedWorkflow = class _SealedWorkflow {
     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;
+        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?.type !== "gate" || innerGate.id !== gateId) {
+      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];
@@ -1768,9 +1718,7 @@ var SealedWorkflow = class _SealedWorkflow {
       this.ensureDuplicateCheck();
     }
     return new CheckpointResumedWorkflow(this.steps, idx, {
-      mode: "checkpoint",
       priorOutput: ckpt.output,
-      snapshot: ckpt,
       observability: this.observability
     });
   }
@@ -1886,11 +1834,12 @@ var CheckpointResumedWorkflow = class extends SealedWorkflow {
 };
 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);
   }
@@ -1901,8 +1850,6 @@ 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);
   }
@@ -1947,67 +1894,18 @@ 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 = new GateStep(
-      id,
-      async (state) => {
-        if (options?.payload) {
-          return options.payload({
-            ctx: state.ctx,
-            input: state.output
-          });
-        }
-        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
-    );
+    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 = new PredicateBranchStep(explicitId ?? "branch:predicate", cases);
-    return this.appendStep(node);
-  }
-  branchSelect(config, explicitId) {
-    const node = new SelectBranchStep(explicitId ?? "branch:select", 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:
-   *   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) **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.
-   */
+  // Implementation
   foreach(target, options) {
-    const node = new ForeachStep(target, options, this.observability);
+    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
@@ -2054,7 +1952,7 @@ var Workflow = class _Workflow extends SealedWorkflow {
 };
 
 // src/index.ts
-var SKIP = Workflow.SKIP;
+var SKIP2 = Workflow.SKIP;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ABORT_STEP_ID,