pipeai 0.8.2 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Tool, ToolExecutionOptions, UIMessageStreamWriter, FlexibleSchema, streamText, generateText, Output, LanguageModel, ModelMessage, ToolChoice, ToolSet, StopCondition, OnStepFinishEvent, OnFinishEvent, GenerateTextResult as GenerateTextResult$1, StreamTextResult as StreamTextResult$1, UIMessage, UIMessageStreamOnFinishCallback, IdGenerator } from 'ai';
+import { Tool, ToolExecutionOptions, UIMessageStreamWriter, FlexibleSchema, streamText, generateText, Output, LanguageModel, ModelMessage, ToolChoice, ToolSet, StopCondition, OnStepFinishEvent, OnFinishEvent, GenerateTextResult as GenerateTextResult$1, StreamTextResult as StreamTextResult$1, UIMessage, UIMessageStreamOnFinishCallback, IdGenerator, InferUIMessageChunk } from 'ai';
 import { ZodType } from 'zod';
 
 declare const TOOL_PROVIDER_BRAND: unique symbol;
@@ -26,36 +26,6 @@ declare class ToolProvider<TContext, TInput = unknown, TOutput = unknown> implem
 declare function defineTool<TContext>(): <TInput, TOutput>(config: ToolProviderConfig<TContext, TInput, TOutput>) => ToolProvider<TContext, TInput, TOutput>;
 declare function isToolProvider<TContext>(obj: unknown): obj is IToolProvider<TContext>;
 
-/**
- * Returns the active `UIMessageStreamWriter` if the current async context is
- * running inside a streaming workflow, or `undefined` otherwise.
- *
- * Use from inside a custom `IToolProvider`'s returned `Tool.execute` callback
- * to forward incremental output to the workflow's UI message stream:
- *
- * ```ts
- * import { getActiveWriter, type IToolProvider, TOOL_PROVIDER_BRAND } from "pipeai";
- *
- * const myProvider: IToolProvider<MyCtx> = {
- *   [TOOL_PROVIDER_BRAND]: true,
- *   createTool(ctx) {
- *     return tool({
- *       execute: async (input) => {
- *         const writer = getActiveWriter();
- *         // ...stream incremental progress to writer if present...
- *         return result;
- *       },
- *     });
- *   },
- * };
- * ```
- *
- * **Important timing note:** call this from *inside* the `Tool.execute`
- * callback, not from inside `createTool` itself. `createTool` runs during
- * agent setup (before the workflow has set the writer); `Tool.execute` runs
- * during tool invocation (when the writer is live).
- */
-declare function getActiveWriter(): UIMessageStreamWriter | undefined;
 type MaybePromise<T> = T | Promise<T>;
 /**
  * A value that can be static or derived from context and input.
@@ -178,28 +148,7 @@ declare class Agent<TContext, TInput = void, TOutput = void> {
     private resolveTools;
 }
 
-declare class WorkflowBranchError extends Error {
-    readonly branchType: "predicate" | "select";
-    constructor(branchType: "predicate" | "select", message: string);
-}
-declare class WorkflowLoopError extends Error {
-    readonly iterations: number;
-    readonly maxIterations: number;
-    constructor(iterations: number, maxIterations: number);
-}
-declare class NestedGateUnsupportedError extends Error {
-    readonly gateId: string;
-    readonly workflowId: string | undefined;
-    readonly siblingErrors: readonly unknown[];
-    readonly siblingSuspensions: readonly {
-        index: number;
-        gateId: string;
-    }[];
-    constructor(gateId: string, workflowId: string | undefined, siblingErrors?: readonly unknown[], siblingSuspensions?: readonly {
-        index: number;
-        gateId: string;
-    }[]);
-}
+type SkipSentinel = typeof Workflow.SKIP;
 /**
  * v2 gate snapshot. The `kind` discriminant differentiates it from
  * checkpoint snapshots. The legacy v1 form is still accepted by `loadState`.
@@ -211,6 +160,15 @@ interface GateSnapshot {
     readonly output: unknown;
     readonly gateId: string;
     readonly gatePayload: unknown;
+    /**
+     * Path of nested-workflow step indices from the ROOT workflow down to the
+     * workflow that owns the gate, outermost-first. Absent/empty for a top-level
+     * gate. Each `.step(workflow)` the suspension bubbles through prepends its own
+     * step index, so {@link SealedWorkflow.loadState} can descend back to the
+     * gate on resume. (`resumeFromIndex` is the gate's index within that
+     * innermost workflow; `gateId` is the innermost gate's id.)
+     */
+    readonly nestedPath?: readonly number[];
 }
 /**
  * v2 checkpoint snapshot. Carries a step-shape hash; resume verifies the
@@ -239,7 +197,7 @@ interface LegacyGateSnapshotV1 {
 }
 type WorkflowSnapshot = GateSnapshot | CheckpointSnapshot | LegacyGateSnapshotV1;
 interface WorkflowWarning {
-    readonly source: "step" | "finally" | "catch" | "onCheckpoint" | "onStepStart" | "onStepFinish" | "onStepError" | "foreach-sibling";
+    readonly source: "step" | "gate" | "finally" | "catch" | "onCheckpoint" | "onStepStart" | "onStepFinish" | "onStepError" | "onItemStart" | "onItemFinish" | "onItemError" | "foreach-sibling";
     readonly stepId: string;
     readonly error: unknown;
 }
@@ -255,6 +213,9 @@ type WorkflowStepType = "step" | "nested" | "gate" | "catch" | "finally" | "bran
  *   - step-like / gate (cond-true → suspends): onStepStart always; onStepFinish
  *     when body returns (suspended: true for gate, false otherwise); onStepError
  *     on body throw.
+ *   - step-like (`when` → false → skip): onStepStart, onStepFinish({ suspended:
+ *     false }) with the passthrough/`otherwise` value as `output`. A skipped
+ *     step's body never runs, but it is still bracketed by start/finish.
  *   - gate (cond false → skip): onStepStart, onStepFinish({ suspended: false }).
  *   - catch: onStepStart only when pendingError set; onStepFinish when catchFn
  *     returns; onStepError when catchFn throws.
@@ -267,17 +228,17 @@ type WorkflowStepType = "step" | "nested" | "gate" | "catch" | "finally" | "bran
  * Skip-checked nodes (`state.suspension || pendingError` already set on entry)
  * emit nothing — `.finally()` is the exception.
  */
-interface WorkflowObservability {
+interface WorkflowObservability<TContext = unknown> {
     onStepStart?: (event: {
         stepId: string;
         type: WorkflowStepType;
-        ctx: unknown;
+        ctx: TContext;
         input: unknown;
     }) => MaybePromise<void>;
     onStepFinish?: (event: {
         stepId: string;
         type: WorkflowStepType;
-        ctx: unknown;
+        ctx: TContext;
         output: unknown;
         durationMs: number;
         suspended: boolean;
@@ -285,7 +246,7 @@ interface WorkflowObservability {
     onStepError?: (event: {
         stepId: string;
         type: WorkflowStepType;
-        ctx: unknown;
+        ctx: TContext;
         error: unknown;
         durationMs: number;
     }) => MaybePromise<void>;
@@ -293,14 +254,14 @@ interface WorkflowObservability {
         stepId: string;
         type: "foreach" | "parallel";
         itemIndex: number | string;
-        ctx: unknown;
+        ctx: TContext;
         input: unknown;
     }) => MaybePromise<void>;
     onItemFinish?: (event: {
         stepId: string;
         type: "foreach" | "parallel";
         itemIndex: number | string;
-        ctx: unknown;
+        ctx: TContext;
         output: unknown;
         durationMs: number;
     }) => MaybePromise<void>;
@@ -308,7 +269,7 @@ interface WorkflowObservability {
         stepId: string;
         type: "foreach" | "parallel";
         itemIndex: number | string;
-        ctx: unknown;
+        ctx: TContext;
         error: unknown;
         durationMs: number;
     }) => MaybePromise<void>;
@@ -317,12 +278,15 @@ interface RunOptions {
     /**
      * Step-level checkpoint sink. Called after each successful step body when
      * `checkpointEvery` cadence or `checkpointWhen` predicate fires. Receives a
-     * v2 `CheckpointSnapshot` and an `AbortSignal` that aborts on
-     * `checkpointTimeout` expiration. Throwing here propagates to the caller
+     * v2 `CheckpointSnapshot` and the run's `abortSignal` (or `undefined` when
+     * the run wasn't given one), so a cancelled run can tear down an in-flight
+     * write if the callback honors it. Throwing here propagates to the caller
      * as an error — workflow `.catch()` is bypassed for checkpoint failures.
+     * There is no framework-imposed timeout; bound the write yourself by racing
+     * the passed `signal` against your own timer if you need one.
      */
     readonly onCheckpoint?: (snapshot: CheckpointSnapshot, opts: {
-        signal: AbortSignal;
+        signal: AbortSignal | undefined;
     }) => MaybePromise<void>;
     /**
      * Fire `onCheckpoint` every N executable steps. Mutually exclusive with
@@ -349,42 +313,20 @@ interface RunOptions {
     /**
      * Cooperative cancellation signal. Checked at every step boundary inside
      * `execute()` and forwarded to agent calls in `executeAgent`, foreach
-     * workers, and nested workflows. When the signal aborts, the workflow
-     * tears down to `signal.reason` via the same pending-error path as any
-     * other step failure, so `.catch()` handlers still get a chance to
-     * observe (or recover from) the abort. `.finally()` bodies still run
-     * on the abort path. Unlike `freezeSnapshots`, this option DOES
-     * propagate into nested workflows, foreach items, and repeat loops —
-     * cancellation should be transitive.
+     * workers, parallel branches, nested workflows, and the `onCheckpoint`
+     * callback's `signal` (so a cancelled run can tear down an in-flight
+     * checkpoint write, if the callback honors it). When the signal aborts,
+     * the workflow tears down to `signal.reason` via the same pending-error path
+     * as any other step failure, so `.catch()` handlers still get a chance to
+     * observe the abort (e.g. for logging/cleanup) — but an abort is sticky and
+     * non-recoverable: even a terminal `.catch()` that returns a value cannot
+     * make the run complete; it still rejects with `signal.reason`. `.finally()`
+     * bodies still run on the abort path. Unlike `freezeSnapshots`, this option DOES
+     * propagate into nested workflows, foreach items, parallel branches, and
+     * repeat loops — cancellation should be transitive.
      */
     readonly abortSignal?: AbortSignal;
-    /**
-     * Maximum ms `onCheckpoint` is allowed to run before its AbortSignal fires.
-     * On timeout, a `CheckpointTimeoutError` is raised on the run (catch is
-     * bypassed; original error reaches the caller). Default: no timeout.
-     */
-    readonly checkpointTimeout?: number;
 }
-/**
- * Synthetic step id reported when `onCheckpoint` itself throws. Reserved
- * via the construction-time `(type, id)` walk — user step ids may not
- * contain the `::pipeai::` namespace.
- */
-declare const CHECKPOINT_STEP_ID: "::pipeai::onCheckpoint";
-/**
- * Thrown internally when `onCheckpoint` exceeds `RunOptions.checkpointTimeout`.
- * Surfaces to the caller as the rejection error.
- */
-declare class CheckpointTimeoutError extends Error {
-    readonly timeoutMs: number;
-    constructor(timeoutMs: number);
-}
-/**
- * Convert a legacy v1 gate snapshot to a v2 gate snapshot. Long-lived
- * storage (Redis-without-TTL, S3, Postgres) should re-serialize via this
- * helper before v0.8.0+ drops v1 acceptance.
- */
-declare function migrateSnapshot(legacy: LegacyGateSnapshotV1): GateSnapshot;
 /**
  * Discriminated union describing one agent invocation's result.
  *
@@ -438,20 +380,70 @@ interface AgentStepHooks<TContext, TOutput, TNextOutput> {
      * Has no generate-mode analog because in generate mode there is no stream
      * to merge. If both `handleStream` and `mapResult`/`onResult` are
      * configured, `handleStream` runs first.
+     *
+     * `itemIndex` identifies the execution when this hook runs inside a
+     * multi-execution combinator: the numeric index for `foreach` and tuple
+     * `parallel`, the key for record `parallel`, and the matched key / case
+     * index for `branch`. It is `undefined` for a plain single `.step(agent)`.
      */
     handleStream?: (params: {
         result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
         writer: UIMessageStreamWriter;
         ctx: Readonly<TContext>;
         input: TOutput;
+        itemIndex?: number | string;
     }) => MaybePromise<void>;
 }
-type StepOptions<TContext, TOutput, TNextOutput> = AgentStepHooks<TContext, TOutput, TNextOutput> & {
+/**
+ * Predicate gating whether a step runs. Receives the step's input. When it
+ * returns false the step is skipped — its body (agent / fn / sub-workflow) is
+ * never invoked.
+ */
+type StepWhen<TContext, TOutput> = (params: {
+    ctx: Readonly<TContext>;
+    input: TOutput;
+}) => MaybePromise<boolean>;
+/**
+ * Produces the step's output when `when` returns false. With it, a skipped
+ * step's output is `otherwise(...)` (typed `TNextOutput`, so the step's output
+ * type stays `TNextOutput`). Without it, a skipped step passes its input
+ * through unchanged (output type widens to `TOutput | TNextOutput`).
+ */
+type StepOtherwise<TContext, TOutput, TNextOutput> = (params: {
+    ctx: Readonly<TContext>;
+    input: TOutput;
+}) => MaybePromise<TNextOutput>;
+/** Conditional-skip options shared by all `step` forms. */
+interface ConditionalStepOptions<TContext, TOutput, TNextOutput> {
+    /** Run the step only when this returns true. Omit to always run. */
+    when?: StepWhen<TContext, TOutput>;
+    /**
+     * Skip value when `when` is false. Omit for passthrough (input unchanged).
+     * Has no effect without `when` — a lone `otherwise` is never invoked.
+     */
+    otherwise?: StepOtherwise<TContext, TOutput, TNextOutput>;
+}
+type StepOptions<TContext, TOutput, TNextOutput> = AgentStepHooks<TContext, TOutput, TNextOutput> & ConditionalStepOptions<TContext, TOutput, TNextOutput> & {
     /** Override the default step id (`agent.id`). Required when reusing the same
      *  agent across multiple steps in one workflow — the construction-time
      *  `(type, id)` walk rejects duplicates. */
     id?: string;
 };
+/** Options for the inline `step(id, fn, options?)` form — conditional skip only. */
+type InlineStepOptions<TContext, TOutput, TNextOutput> = ConditionalStepOptions<TContext, TOutput, TNextOutput>;
+/** Options for the nested `step(workflow, options?)` form — conditional skip + id override. */
+type NestedStepOptions<TContext, TOutput, TNextOutput> = ConditionalStepOptions<TContext, TOutput, TNextOutput> & {
+    id?: string;
+};
+/**
+ * A step that supplies `when` without `otherwise` may skip to passthrough, so
+ * its output widens to `TOutput | TNextOutput`. Supplying `otherwise` (which
+ * returns `TNextOutput`) — or omitting `when` — keeps the output `TNextOutput`.
+ */
+type SkipPassthrough<TContext, TOutput, TNextOutput> = ConditionalStepOptions<TContext, TOutput, TNextOutput> & {
+    when: StepWhen<TContext, TOutput>;
+    otherwise?: undefined;
+};
 interface BranchCase<TContext, TOutput, TNextOutput> extends AgentStepHooks<TContext, TOutput, TNextOutput> {
     when?: (params: {
         ctx: Readonly<TContext>;
@@ -487,8 +479,8 @@ type WorkflowResult<TOutput> = {
     readonly snapshot: GateSnapshot;
     readonly warnings: readonly WorkflowWarning[];
 };
-interface WorkflowStreamResult<TOutput> {
-    stream: ReadableStream;
+interface WorkflowStreamResult<TOutput, UI_MESSAGE extends UIMessage = UIMessage> {
+    stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>;
     output: Promise<WorkflowResult<TOutput>>;
 }
 /**
@@ -541,6 +533,14 @@ type LoopPredicate<TContext, TOutput> = (params: {
     ctx: Readonly<TContext>;
     iterations: number;
 }) => MaybePromise<boolean>;
+/**
+ * Loop control for `repeat`. Exactly one of `until` / `while` — never both.
+ *
+ * Both forms are **do-while**: the body always runs at least once, then the
+ * predicate is checked. This is intentional — the predicate receives the
+ * body's `output`, which doesn't exist until the body has run — but it means
+ * `while: () => false` still executes the body once (it is not a pre-check).
+ */
 type RepeatOptions<TContext, TOutput> = {
     until: LoopPredicate<TContext, TOutput>;
     while?: never;
@@ -551,6 +551,60 @@ type RepeatOptions<TContext, TOutput> = {
     maxIterations?: number;
 };
 type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
+/**
+ * Options for `Workflow.foreach` — shared by the agent / sub-workflow target
+ * form and the per-item path-builder callback form.
+ */
+interface ForeachOptions<TContext, TOutput, TNextOutput> {
+    /** Override the default step id (`foreach:<agentId>` or the body workflow's id). */
+    id?: string;
+    /**
+     * 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.
+     */
+    concurrency?: number;
+    /**
+     * Per-iteration error handler. Return a `TNextOutput` to substitute, return
+     * `Workflow.SKIP` to omit the item, or throw to abort. Invoked sequentially in
+     * index order after all items settle. **Bypassed on the abort path.**
+     */
+    onError?: (params: {
+        error: unknown;
+        item: ElementOf<TOutput>;
+        index: number;
+        ctx: Readonly<TContext>;
+    }) => MaybePromise<TNextOutput | SkipSentinel>;
+    /**
+     * **Stream-mode + agent-target only.** When the workflow is run via
+     * `.stream(...)`, each item's agent runs in stream mode and this hook decides
+     * how its stream surfaces to the writer (`itemIndex` = the item index). Not
+     * invoked for sub-workflow bodies (which stream transitively) nor in generate
+     * mode.
+     */
+    handleStream?: (params: {
+        result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
+        writer: UIMessageStreamWriter;
+        ctx: Readonly<TContext>;
+        input: ElementOf<TOutput>;
+        itemIndex: number;
+    }) => MaybePromise<void>;
+}
+/**
+ * Brand that makes a *gated* workflow unassignable where gates are forbidden —
+ * `foreach` / `parallel` / `repeat` targets. A nested gate can't suspend one
+ * branch of a concurrent fan-out or one iteration of a loop, so it's rejected
+ * at build time. Since `.step(workflow)` folds child gates into `TGates`, this
+ * catches gates at ANY nesting depth, not just direct ones.
+ */
+type GatesForbidden = {
+    readonly __agent_workflow_error__: "a workflow with gate(s) cannot be a foreach / parallel / repeat target";
+};
+/** `unknown` when `TG` has no gate keys (no-op intersection), else the {@link GatesForbidden} brand. */
+type NoGates<TG extends Record<string, unknown>> = [keyof TG] extends [never] ? unknown : GatesForbidden;
+/** A `parallel` branch with its gates checked: gated workflows resolve to the {@link GatesForbidden} brand. */
+type GatelessBranch<T> = T extends SealedWorkflow<any, any, any, infer G> ? ([keyof G] extends [never] ? T : GatesForbidden) : T;
 /** A target for a `parallel()` branch — agent or sealed workflow. */
 type ParallelTarget<TContext, TInput> = Agent<TContext, TInput, any> | SealedWorkflow<TContext, TInput, any>;
 /** Extract the output type of a single parallel branch target. */
@@ -563,25 +617,40 @@ type ParallelOutputRecord<T extends Record<string, unknown>> = {
 type ParallelOutputTuple<T extends ReadonlyArray<unknown>> = {
     [K in keyof T]: BranchOutput<T[K]>;
 };
-interface ParallelOptions<TContext> {
+/**
+ * Record output when `onError` is supplied: any branch may be `SKIP`ped,
+ * leaving its slot `undefined`, so every value is widened to `| undefined`.
+ */
+type ParallelOutputRecordPartial<T extends Record<string, unknown>> = {
+    [K in keyof T]: BranchOutput<T[K]> | undefined;
+};
+/** Tuple counterpart of `ParallelOutputRecordPartial` — each slot `| undefined`. */
+type ParallelOutputTuplePartial<T extends ReadonlyArray<unknown>> = {
+    [K in keyof T]: BranchOutput<T[K]> | undefined;
+};
+interface ParallelOptions<TContext, TOutput = unknown> {
     /** Override the default step id. Default: `parallel:record` or `parallel:tuple`. */
     id?: string;
     /**
-     * Max branches in flight at any moment. Default: `min(branches.length, 5)`.
-     * Pass `Infinity` (or `branches.length`) for full fan-out on >5-branch calls
-     * — the default caps at 5 to protect against rate limits and emits a
-     * one-time warn when the cap kicks in.
+     * Max branches in flight at any moment. **Default: unbounded** (`Infinity` —
+     * all branches run concurrently, clamped only by branch count). Pass an
+     * integer to throttle against provider rate limits.
      */
     concurrency?: number;
     /**
      * Per-branch error handler. On the no-suspension path, called once per
      * rejected branch in index order after all settle. Return a value to
-     * substitute, return `Workflow.SKIP` to leave the slot undefined (record
-     * form only — tuple SKIP would shift indices), or rethrow to abort the
-     * parallel.
+     * substitute, return `Workflow.SKIP` to leave the slot `undefined`, or
+     * rethrow to abort the parallel. A throw (or rethrow) aborts immediately:
+     * rejected branches at indices AFTER the throwing one are neither recovered
+     * nor surfaced as warnings. SKIP works in both the record and tuple
+     * forms (the slot stays `undefined` in place — it does not shift indices);
+     * supplying `onError` widens the output values to `BranchOutput | undefined`
+     * to reflect that a slot may be skipped.
      *
      * **Bypassed entirely on the suspension path** (any branch hit a nested
-     * gate). See README's "Suspension under `parallel()`" section.
+     * gate) and on the cancellation path (the run was aborted). See README's
+     * "Suspension under `parallel()`" section.
      */
     onError?: (params: {
         error: unknown;
@@ -590,43 +659,27 @@ interface ParallelOptions<TContext> {
         /** Branch index in the tuple form; `undefined` in the record form. */
         index?: number;
         ctx: Readonly<TContext>;
-    }) => unknown | typeof Workflow.SKIP | Promise<unknown | typeof Workflow.SKIP>;
+    }) => unknown | SkipSentinel | Promise<unknown | SkipSentinel>;
+    /**
+     * **Stream-mode + agent-branch only.** When the workflow is run via
+     * `.stream(...)`, each agent branch runs in stream mode and this hook decides
+     * how its stream surfaces to the writer (`itemIndex` = the record key or the
+     * tuple index). Without it, agent branches run in generate mode (no
+     * auto-merge). Not invoked for `SealedWorkflow` branches (which stream
+     * transitively via their own steps) nor in generate mode.
+     */
+    handleStream?: (params: {
+        result: StreamTextResult<ToolSet, any>;
+        writer: UIMessageStreamWriter;
+        ctx: Readonly<TContext>;
+        input: TOutput;
+        itemIndex: number | string;
+    }) => MaybePromise<void>;
 }
 interface SchemaWithParse<T = unknown> {
     parse(data: unknown): T;
 }
-type StepCategory = "step" | "nested" | "branch" | "foreach" | "repeat" | "parallel";
-type StepNode = {
-    readonly type: "step";
-    readonly id: string;
-    readonly execute: (state: RuntimeState) => MaybePromise<void>;
-    readonly nestedWorkflow?: SealedWorkflow<any, any, any, any>;
-    /** Disambiguates observability events. Default `"step"`. */
-    readonly category?: StepCategory;
-} | {
-    readonly type: "catch";
-    readonly id: string;
-    readonly catchFn: (params: {
-        error: unknown;
-        ctx: unknown;
-        lastOutput: unknown;
-        stepId: string;
-    }) => MaybePromise<unknown>;
-} | {
-    readonly type: "finally";
-    readonly id: string;
-    readonly execute: (state: RuntimeState) => MaybePromise<void>;
-} | {
-    readonly type: "gate";
-    readonly id: string;
-    readonly payload: (state: RuntimeState) => MaybePromise<unknown>;
-    readonly schema?: SchemaWithParse;
-    readonly condition?: (state: RuntimeState) => MaybePromise<boolean>;
-    readonly merge?: (params: {
-        priorOutput: unknown;
-        response: unknown;
-    }) => MaybePromise<unknown>;
-};
+
 interface RuntimeState {
     ctx: unknown;
     output: unknown;
@@ -635,22 +688,158 @@ interface RuntimeState {
     suspension?: GateSnapshot;
     warnings?: WorkflowWarning[];
     checkpointFailed?: boolean;
+    pendingError?: PendingError;
     runOptions?: RunOptions;
     abortSignal?: AbortSignal;
+    stepIndex?: number;
+    resumeDescent?: ResumeDescent;
 }
+/**
+ * Drives resume re-entry for a gate that suspended inside nested workflows.
+ * `remaining` is the list of child start-indices to descend through, one per
+ * nesting level, ending with the innermost gate's `resumeFromIndex + 1`. When a
+ * `NestedWorkflowStep` consumes the LAST entry it first seeds `state.output`
+ * with `seedOutput` (the merged gate response) before running the innermost
+ * child from that index.
+ */
+type ResumeDescent = {
+    readonly remaining: readonly number[];
+    readonly seedOutput: unknown;
+};
 type PendingError = {
     error: unknown;
     stepId: string;
-    source: "step" | "finally" | "catch" | "onCheckpoint";
+    source: "step" | "gate" | "finally" | "catch" | "onCheckpoint";
+};
+
+/**
+ * Disambiguates observability events for `type: "step"` nodes. Keeps a single
+ * `type: "step"` node kind rather than splitting branch/foreach/repeat/
+ * parallel/nested into their own run-loop variants.
+ */
+type StepCategory = "step" | "nested" | "branch" | "foreach" | "repeat" | "parallel";
+/**
+ * Base class for a single workflow step node. The run loop in `workflow.ts`
+ * consumes `ReadonlyArray<Step>` directly — every combinator on `Workflow`
+ * constructs one of the subclasses in this directory.
+ *
+ * ## Execution model (the "fat step")
+ *
+ * The run loop does two things: ask {@link shouldSkip} whether the node runs
+ * at all (skipped nodes fire no observability hooks), then call
+ * {@link execute}. Everything else is the step's own business — a kind's
+ * `execute` runs its work (applying the body-level `when` / `otherwise`
+ * decision via {@link applyConditionalSkip}) and captures any thrown error
+ * onto `state.pendingError`, exactly the way it writes its result to
+ * `state.output`. Errors accumulate on the state; they do not escape.
+ *
+ * The base {@link execute} is a no-op so kinds with no body of their own need
+ * not override it. {@link errorSource} tags which precedence bucket a captured
+ * error lands in.
+ */
+declare abstract class Step {
+    /** Run-loop dispatch discriminant. */
+    abstract readonly type: "step" | "gate" | "catch" | "finally";
+    /** Identifier, unique per `type`; surfaced in observability and snapshots. */
+    abstract readonly id: string;
+    /**
+     * 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.
+     */
+    readonly category?: StepCategory;
+    /**
+     * 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`.
+     */
+    readonly nestedWorkflow?: SealedWorkflow<any, any, any, any>;
+    /**
+     * 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.
+     */
+    protected readonly errorSource: PendingError["source"];
+    /**
+     * 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.
+     */
+    execute(_state: RuntimeState): Promise<void>;
+    /**
+     * 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: RuntimeState): boolean;
+    /**
+     * 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.
+     */
+    protected applyConditionalSkip(state: RuntimeState, options: ConditionalStepOptions<unknown, unknown, unknown> | undefined): Promise<boolean>;
+}
+
+declare class WorkflowBranchError extends Error {
+    readonly branchType: "predicate" | "select";
+    constructor(branchType: "predicate" | "select", message: string);
+}
+declare class WorkflowLoopError extends Error {
+    readonly iterations: number;
+    readonly maxIterations: number;
+    constructor(iterations: number, maxIterations: number);
+}
+/**
+ * Synthetic step id reported when `onCheckpoint` itself throws. Reserved
+ * via the construction-time `(type, id)` walk — user step ids may not
+ * contain the `::pipeai::` namespace.
+ */
+declare const CHECKPOINT_STEP_ID: "::pipeai::onCheckpoint";
+/**
+ * Synthetic step id carried by the pending-error a cancellation promotes
+ * (surfaced to `.catch()` / observability). Lives in the reserved
+ * `::pipeai::` namespace so it can't be confused with a user step literally
+ * named "abort".
+ */
+declare const ABORT_STEP_ID: "::pipeai::abort";
+/**
+ * Synthetic step id used when a gate-resume's response validation / merge
+ * throws before the pipeline re-enters `execute()`. Reserved-namespaced for
+ * the same reason as {@link ABORT_STEP_ID}.
+ */
+declare const GATE_RESUME_STEP_ID: "::pipeai::gate:resume";
+
+/**
+ * Convert a legacy v1 gate snapshot to a v2 gate snapshot. Long-lived
+ * storage (Redis-without-TTL, S3, Postgres) should re-serialize via this
+ * helper before v0.8.0+ drops v1 acceptance.
+ */
+declare function migrateSnapshot(legacy: LegacyGateSnapshotV1): GateSnapshot;
+/**
+ * Seed for a run: the initial pipeline `output` plus an optional pre-execute
+ * `initialError`. The resume entry points compute these differently (gate
+ * schema-parse + merge vs. plain snapshot output), but every entry point then
+ * funnels through the same `runGenerate` / `runStream` machinery.
+ */
+type StateSeed = {
+    output: unknown;
+    initialError: PendingError | null;
+    resumeDescent?: ResumeDescent;
 };
 declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates extends Record<string, unknown> = {}> {
     readonly id?: string;
-    protected readonly steps: ReadonlyArray<StepNode>;
+    protected readonly steps: ReadonlyArray<Step>;
     protected readonly observability?: WorkflowObservability;
     private duplicateCheckPassed;
-    private _cachedExecutableStepCount?;
+    private _stepCounts?;
     private _cachedStepShapeHash?;
-    protected constructor(steps: ReadonlyArray<StepNode>, id?: string, observability?: WorkflowObservability);
+    protected constructor(steps: ReadonlyArray<Step>, id?: string, observability?: WorkflowObservability);
     /**
      * Walk the step list once per terminal instance. Rejects:
      *   - Duplicate `(type, id)` pairs.
@@ -659,24 +848,35 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
      */
     private ensureDuplicateCheck;
     /**
-     * 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.
      */
-    protected get cachedExecutableStepCount(): number;
+    protected get stepCounts(): {
+        executable: number;
+        checkpointable: number;
+    };
     /** @internal — used by `computeStepShapeHash` to descend nested workflows. */
-    getStepsForShapeHash(): ReadonlyArray<StepNode>;
+    getStepsForShapeHash(): ReadonlyArray<Step>;
     protected get cachedStepShapeHash(): string;
     /**
      * 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).
      */
     protected validateRunOptions(opts: RunOptions | undefined): void;
+    /** 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. */
+    private obsEventType;
     /**
      * Fire an observability hook safely. Returns `undefined` synchronously when
      * no hook is registered — avoiding the promise wrapper + microtask that an
@@ -690,15 +890,81 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
      * 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.
      */
     protected fireHook<K extends keyof WorkflowObservability, E extends Parameters<NonNullable<WorkflowObservability[K]>>[0]>(state: RuntimeState, name: K, event: E): MaybePromise<unknown>;
-    private fireHookSlow;
+    /**
+     * 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.)
+     */
+    protected fireStepErrorAndAttachCause(state: RuntimeState, event: {
+        stepId: string;
+        type: WorkflowStepType;
+        ctx: unknown;
+        error: unknown;
+        durationMs: number;
+    }): Promise<void>;
     generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput, opts?: RunOptions] : [input: TInput, opts?: RunOptions]): Promise<WorkflowResult<TOutput>>;
-    stream<UI_MESSAGE extends UIMessage = UIMessage>(ctx: TContext, ...args: TInput extends void ? [input?: TInput, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions] : [input: TInput, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions]): WorkflowStreamResult<TOutput>;
+    stream<UI_MESSAGE extends UIMessage = UIMessage>(ctx: TContext, ...args: TInput extends void ? [input?: TInput, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions] : [input: TInput, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions]): WorkflowStreamResult<TOutput, UI_MESSAGE>;
     protected buildResult(state: RuntimeState): WorkflowResult<TOutput>;
+    protected runGenerate(ctx: unknown, startIndex: number, opts: RunOptions | undefined, seed: () => MaybePromise<StateSeed>): Promise<WorkflowResult<TOutput>>;
+    protected runStream<UI_MESSAGE extends UIMessage = UIMessage>(ctx: unknown, startIndex: number, opts: RunOptions | undefined, options: WorkflowStreamOptions<UI_MESSAGE> | undefined, seed: () => MaybePromise<StateSeed>): WorkflowStreamResult<TOutput, UI_MESSAGE>;
     protected execute(state: RuntimeState, startIndex?: number, opts?: RunOptions, initialError?: PendingError | null): Promise<void>;
-    protected executeNestedWorkflow(state: RuntimeState, workflow: SealedWorkflow<TContext, unknown, unknown, any>): Promise<void>;
-    protected executeAgent<TAgentInput, TNextOutput>(state: RuntimeState, agent: Agent<TContext, any, TNextOutput>, ctx: TContext, options?: AgentStepHooks<TContext, any, TNextOutput>): Promise<void>;
+    /**
+     * 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.
+     */
+    private promoteAbort;
+    /**
+     * 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.
+     */
+    private maybeCheckpoint;
+    /**
+     * 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.)
+     */
+    private settleRun;
+    /**
+     * 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).
+     */
+    executeAsNested(state: RuntimeState, startIndex?: number): Promise<void>;
     loadState<K extends string & keyof TGates>(gateId: K, snapshot: WorkflowSnapshot): ResumedWorkflow<TContext, TGates[K], TOutput>;
     /**
      * Resume from a checkpoint snapshot. Validates the step-shape hash unless
@@ -719,7 +985,9 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
     /**
      * 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: string, fn: (params: {
         ctx: Readonly<TContext>;
@@ -727,7 +995,7 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
     private findGateIndex;
 }
 interface ResumedWorkflowConfig {
-    readonly mode: "gate" | "checkpoint";
+    readonly mode: "gate";
     readonly schema?: SchemaWithParse<unknown>;
     readonly mergeFn?: (params: {
         priorOutput: unknown;
@@ -736,48 +1004,76 @@ interface ResumedWorkflowConfig {
     readonly priorOutput?: unknown;
     readonly snapshot?: WorkflowSnapshot;
     readonly observability?: WorkflowObservability;
+    /**
+     * Set only for a NESTED gate resume: the descent (child start-indices per
+     * level, innermost-last) the merged gate response rides down to the suspended
+     * child. When present, `startIndex` is the ROOT's nested-step index and the
+     * seed sets `state.resumeDescent` instead of the root `output`.
+     */
+    readonly nestedRemaining?: readonly number[];
 }
 declare class ResumedWorkflow<TContext, TResponse = unknown, TOutput = void> extends SealedWorkflow<TContext, TResponse, TOutput> {
     private readonly startIndex;
     private readonly schema?;
     private readonly mergeFn?;
     private readonly priorOutput;
+    private readonly nestedRemaining?;
     /** @internal */
-    constructor(steps: ReadonlyArray<StepNode>, startIndex: number, config: ResumedWorkflowConfig);
+    constructor(steps: ReadonlyArray<Step>, startIndex: number, config: ResumedWorkflowConfig);
     private validateResponse;
+    /**
+     * 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.
+     */
+    private seedFromResponse;
     generate(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse, opts?: RunOptions] : [response: TResponse, opts?: RunOptions]): Promise<WorkflowResult<TOutput>>;
-    stream<UI_MESSAGE extends UIMessage = UIMessage>(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions] : [response: TResponse, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions]): WorkflowStreamResult<TOutput>;
+    stream<UI_MESSAGE extends UIMessage = UIMessage>(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions] : [response: TResponse, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions]): WorkflowStreamResult<TOutput, UI_MESSAGE>;
 }
 declare class CheckpointResumedWorkflow<TContext, TOutput = void> extends SealedWorkflow<TContext, void, TOutput> {
     private readonly startIndex;
     private readonly priorOutput;
     /** @internal */
-    constructor(steps: ReadonlyArray<StepNode>, startIndex: number, config: ResumedWorkflowConfig);
+    constructor(steps: ReadonlyArray<Step>, startIndex: number, config: {
+        priorOutput?: unknown;
+        observability?: WorkflowObservability;
+    });
     generate(ctx: TContext, ...args: [input?: void, opts?: RunOptions]): Promise<WorkflowResult<TOutput>>;
-    stream<UI_MESSAGE extends UIMessage = UIMessage>(ctx: TContext, ...args: [input?: void, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions]): WorkflowStreamResult<TOutput>;
+    stream<UI_MESSAGE extends UIMessage = UIMessage>(ctx: TContext, ...args: [input?: void, options?: WorkflowStreamOptions<UI_MESSAGE>, opts?: RunOptions]): WorkflowStreamResult<TOutput, UI_MESSAGE>;
 }
 declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends Record<string, unknown> = {}> extends SealedWorkflow<TContext, TInput, TOutput, TGates> {
     /**
-     * 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 readonly SKIP: unique symbol;
+    static readonly SKIP: symbol;
     private constructor();
     static create<TContext, TInput = void>(options?: {
         id?: string;
-        observability?: WorkflowObservability;
+        observability?: WorkflowObservability<TContext>;
     }): Workflow<TContext, TInput, TInput>;
+    static from<TContext, TInput, TOutput>(agent: Agent<TContext, TInput, TOutput>, options: StepOptions<TContext, TInput, TOutput> & SkipPassthrough<TContext, TInput, TOutput>): Workflow<TContext, TInput, TInput | TOutput>;
     static from<TContext, TInput, TOutput>(agent: Agent<TContext, TInput, TOutput>, options?: StepOptions<TContext, TInput, TOutput>): Workflow<TContext, TInput, TOutput>;
     private appendStep;
+    step<TNextOutput>(agent: Agent<TContext, TOutput, TNextOutput>, options: StepOptions<TContext, TOutput, TNextOutput> & SkipPassthrough<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TOutput | TNextOutput, TGates>;
     step<TNextOutput>(agent: Agent<TContext, TOutput, TNextOutput>, options?: StepOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
-    step<TNextOutput>(workflow: SealedWorkflow<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
+    step<TNextOutput, TChildGates extends Record<string, unknown> = {}>(workflow: SealedWorkflow<TContext, TOutput, TNextOutput, TChildGates>, options: NestedStepOptions<TContext, TOutput, TNextOutput> & SkipPassthrough<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TOutput | TNextOutput, TGates & TChildGates>;
+    step<TNextOutput, TChildGates extends Record<string, unknown> = {}>(workflow: SealedWorkflow<TContext, TOutput, TNextOutput, TChildGates>, options?: NestedStepOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates & TChildGates>;
     step<TNextOutput>(id: string, fn: (params: {
         ctx: Readonly<TContext>;
         input: TOutput;
         writer?: UIMessageStreamWriter;
-    }) => MaybePromise<TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
-    gate<TResponse = TOutput, Id extends string = string>(id: Id & (Id extends keyof TGates ? never : Id), options?: {
+    }) => MaybePromise<TNextOutput>, options: InlineStepOptions<TContext, TOutput, TNextOutput> & SkipPassthrough<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TOutput | TNextOutput, TGates>;
+    step<TNextOutput>(id: string, fn: (params: {
+        ctx: Readonly<TContext>;
+        input: TOutput;
+        writer?: UIMessageStreamWriter;
+    }) => MaybePromise<TNextOutput>, options?: InlineStepOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
+    gate<TResponse = TOutput, TMerged = TResponse, Id extends string = string>(id: Id & (Id extends keyof TGates ? never : Id), options?: {
         payload?: (params: {
             ctx: Readonly<TContext>;
             input: TOutput;
@@ -790,16 +1086,14 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
         merge?: (params: {
             priorOutput: TOutput;
             response: TResponse;
-        }) => MaybePromise<TResponse>;
-    }): Workflow<TContext, TInput, TResponse, TGates & Record<Id, TResponse>>;
+        }) => MaybePromise<TMerged>;
+    }): Workflow<TContext, TInput, TMerged, TGates & Record<Id, TResponse>>;
     branch<TNextOutput>(cases: BranchCase<TContext, TOutput, TNextOutput>[], options?: {
         id?: string;
     }): Workflow<TContext, TInput, TNextOutput, TGates>;
     branch<TKeys extends string, TNextOutput>(config: BranchSelect<TContext, TOutput, TKeys, TNextOutput>, options?: {
         id?: string;
     }): Workflow<TContext, TInput, TNextOutput, TGates>;
-    private branchPredicate;
-    private branchSelect;
     /**
      * Map each item of an array through an agent or sub-workflow.
      *
@@ -807,30 +1101,45 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
      * @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<TNextOutput>(target: Agent<TContext, ElementOf<TOutput>, TNextOutput> | SealedWorkflow<TContext, ElementOf<TOutput>, TNextOutput>, options?: {
-        id?: string;
-        concurrency?: number;
-        onError?: (params: {
-            error: unknown;
-            item: ElementOf<TOutput>;
-            index: number;
-            ctx: Readonly<TContext>;
-        }) => MaybePromise<TNextOutput | typeof Workflow.SKIP>;
-    }): Workflow<TContext, TInput, TNextOutput[], TGates>;
+    foreach<TNextOutput, TG extends Record<string, unknown> = {}>(target: Agent<TContext, ElementOf<TOutput>, TNextOutput> | (SealedWorkflow<TContext, ElementOf<TOutput>, TNextOutput, TG> & NoGates<TG>), options?: ForeachOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput[], TGates>;
+    foreach<TNextOutput, TG extends Record<string, unknown> = {}>(build: (path: Workflow<TContext, ElementOf<TOutput>, ElementOf<TOutput>>) => (SealedWorkflow<TContext, ElementOf<TOutput>, TNextOutput, TG> & NoGates<TG>), options?: ForeachOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput[], TGates>;
+    /** Record-form + `onError`. Values are `BranchOutput | undefined` (SKIP-able). */
+    parallel<TBranches extends Record<string, ParallelTarget<TContext, TOutput>>>(branches: TBranches & {
+        [K in keyof TBranches]: GatelessBranch<TBranches[K]>;
+    }, options: ParallelOptions<TContext, TOutput> & {
+        onError: NonNullable<ParallelOptions<TContext, TOutput>["onError"]>;
+    }): Workflow<TContext, TInput, ParallelOutputRecordPartial<TBranches>, TGates>;
     /** Record-form overload. Returns `{ [K]: BranchOutput<T[K]> }`. */
-    parallel<TBranches extends Record<string, ParallelTarget<TContext, TOutput>>>(branches: TBranches, options?: ParallelOptions<TContext>): Workflow<TContext, TInput, ParallelOutputRecord<TBranches>, TGates>;
+    parallel<TBranches extends Record<string, ParallelTarget<TContext, TOutput>>>(branches: TBranches & {
+        [K in keyof TBranches]: GatelessBranch<TBranches[K]>;
+    }, options?: ParallelOptions<TContext, TOutput>): Workflow<TContext, TInput, ParallelOutputRecord<TBranches>, TGates>;
+    /** Tuple-form + `onError`. Each slot is `BranchOutput | undefined` (SKIP-able). */
+    parallel<TBranches extends ReadonlyArray<ParallelTarget<TContext, TOutput>>>(branches: TBranches & {
+        [K in keyof TBranches]: GatelessBranch<TBranches[K]>;
+    }, options: ParallelOptions<TContext, TOutput> & {
+        onError: NonNullable<ParallelOptions<TContext, TOutput>["onError"]>;
+    }): Workflow<TContext, TInput, ParallelOutputTuplePartial<TBranches>, TGates>;
     /** Tuple-form overload. Returns `[O1, O2, ...]`. Use `as const`. */
-    parallel<TBranches extends ReadonlyArray<ParallelTarget<TContext, TOutput>>>(branches: TBranches, options?: ParallelOptions<TContext>): Workflow<TContext, TInput, ParallelOutputTuple<TBranches>, TGates>;
-    repeat(target: Agent<TContext, TOutput, TOutput> | SealedWorkflow<TContext, TOutput, TOutput>, options: RepeatOptions<TContext, TOutput> & {
+    parallel<TBranches extends ReadonlyArray<ParallelTarget<TContext, TOutput>>>(branches: TBranches & {
+        [K in keyof TBranches]: GatelessBranch<TBranches[K]>;
+    }, options?: ParallelOptions<TContext, TOutput>): Workflow<TContext, TInput, ParallelOutputTuple<TBranches>, TGates>;
+    repeat<TG extends Record<string, unknown> = {}>(target: Agent<TContext, TOutput, TOutput> | (SealedWorkflow<TContext, TOutput, TOutput, TG> & NoGates<TG>), options: RepeatOptions<TContext, TOutput> & {
         id?: string;
     }): Workflow<TContext, TInput, TOutput, TGates>;
     catch(id: string, fn: (params: {
@@ -843,4 +1152,4 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
 
 declare const SKIP: symbol;
 
-export { Agent, type AgentConfig, type AgentResultParams, type AgentStepHooks, type AsToolMapOutput, type BranchCase, type BranchSelect, CHECKPOINT_STEP_ID, CheckpointResumedWorkflow, type CheckpointSnapshot, CheckpointTimeoutError, type GateSnapshot, type GenerateTextResult, type IToolProvider, type LegacyGateSnapshotV1, type MaybePromise, NestedGateUnsupportedError, type OutputType, type ParallelOptions, type ParallelOutputRecord, type ParallelOutputTuple, type ParallelTarget, type RepeatOptions, type Resolvable, ResumedWorkflow, type RunOptions, SKIP, SealedWorkflow, type StepOptions, type StreamTextResult, TOOL_PROVIDER_BRAND, type ToolExecuteOptions, ToolProvider, type ToolProviderConfig, Workflow, WorkflowBranchError, WorkflowLoopError, type WorkflowObservability, type WorkflowResult, type WorkflowSnapshot, type WorkflowStepType, type WorkflowStreamOptions, type WorkflowStreamResult, type WorkflowWarning, defineTool, getActiveWriter, isToolProvider, migrateSnapshot };
+export { ABORT_STEP_ID, Agent, type AgentConfig, type AgentResultParams, type AgentStepHooks, type AsToolMapOutput, type BranchCase, type BranchSelect, CHECKPOINT_STEP_ID, CheckpointResumedWorkflow, type CheckpointSnapshot, type ForeachOptions, GATE_RESUME_STEP_ID, type GateSnapshot, type GenerateTextResult, type IToolProvider, type LegacyGateSnapshotV1, type MaybePromise, type OutputType, type ParallelOptions, type ParallelOutputRecord, type ParallelOutputTuple, type ParallelTarget, type RepeatOptions, type Resolvable, ResumedWorkflow, type RunOptions, SKIP, SealedWorkflow, type StepOptions, type StreamTextResult, TOOL_PROVIDER_BRAND, type ToolExecuteOptions, ToolProvider, type ToolProviderConfig, Workflow, WorkflowBranchError, WorkflowLoopError, type WorkflowObservability, type WorkflowResult, type WorkflowSnapshot, type WorkflowStepType, type WorkflowStreamOptions, type WorkflowStreamResult, type WorkflowWarning, defineTool, isToolProvider, migrateSnapshot };