pipeai 0.8.4 → 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;
@@ -479,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>>;
 }
 /**
@@ -551,6 +551,46 @@ 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
@@ -640,6 +680,112 @@ interface SchemaWithParse<T = unknown> {
     parse(data: unknown): T;
 }
 
+interface RuntimeState {
+    ctx: unknown;
+    output: unknown;
+    mode: "generate" | "stream";
+    writer?: UIMessageStreamWriter;
+    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" | "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);
@@ -668,69 +814,13 @@ declare const ABORT_STEP_ID: "::pipeai::abort";
  * 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;
-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 execute: (state: RuntimeState) => MaybePromise<void>;
-} | {
-    readonly type: "finally";
-    readonly id: string;
-    readonly execute: (state: RuntimeState) => MaybePromise<void>;
-} | {
-    readonly type: "gate";
-    readonly id: string;
-    readonly execute: (state: RuntimeState) => MaybePromise<void>;
-    readonly schema?: SchemaWithParse;
-    readonly merge?: (params: {
-        priorOutput: unknown;
-        response: unknown;
-    }) => MaybePromise<unknown>;
-};
-interface RuntimeState {
-    ctx: unknown;
-    output: unknown;
-    mode: "generate" | "stream";
-    writer?: UIMessageStreamWriter;
-    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" | "gate" | "finally" | "catch" | "onCheckpoint";
-};
 /**
  * Seed for a run: the initial pipeline `output` plus an optional pre-execute
  * `initialError`. The resume entry points compute these differently (gate
@@ -744,13 +834,12 @@ type StateSeed = {
 };
 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 _cachedCheckpointableStepCount?;
+    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.
@@ -759,34 +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;
-    /**
-     * 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.
-     */
-    protected get cachedCheckpointableStepCount(): 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
@@ -800,9 +890,12 @@ 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>;
-    protected hasItemHooks(): boolean;
     /**
      * Fire `onStepError` for a step-body failure and honor the documented
      * cause-attachment contract uniformly across every firing path (step, gate,
@@ -822,11 +915,43 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
         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>;
+    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>;
+    /**
+     * 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 —
@@ -870,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;
@@ -894,7 +1019,7 @@ declare class ResumedWorkflow<TContext, TResponse = unknown, TOutput = void> ext
     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
@@ -905,23 +1030,27 @@ declare class ResumedWorkflow<TContext, TResponse = unknown, TOutput = void> ext
      */
     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;
@@ -944,7 +1073,7 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
         input: TOutput;
         writer?: UIMessageStreamWriter;
     }) => MaybePromise<TNextOutput>, options?: InlineStepOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
-    gate<TResponse = TOutput, Id extends string = string>(id: Id & (Id extends keyof TGates ? never : Id), options?: {
+    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;
@@ -957,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.
      *
@@ -990,32 +1117,8 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
      *   failures at indices AFTER the throwing one are neither recovered nor
      *   surfaced as warnings.
      */
-    foreach<TNextOutput, TG extends Record<string, unknown> = {}>(target: Agent<TContext, ElementOf<TOutput>, TNextOutput> | (SealedWorkflow<TContext, ElementOf<TOutput>, TNextOutput, TG> & NoGates<TG>), options?: {
-        id?: string;
-        concurrency?: number;
-        onError?: (params: {
-            error: unknown;
-            item: ElementOf<TOutput>;
-            index: number;
-            ctx: Readonly<TContext>;
-        }) => MaybePromise<TNextOutput | typeof Workflow.SKIP>;
-        /**
-         * **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). Without it, agent items run in generate mode (no auto-merge —
-         * unlike a single `.step(agent)`, foreach never auto-merges N streams).
-         * Not invoked for `SealedWorkflow` targets (which stream transitively via
-         * their own steps) nor in generate mode.
-         */
-        handleStream?: (params: {
-            result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
-            writer: UIMessageStreamWriter;
-            ctx: Readonly<TContext>;
-            input: ElementOf<TOutput>;
-            itemIndex: number;
-        }) => MaybePromise<void>;
-    }): 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]>;
@@ -1049,4 +1152,4 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
 
 declare const SKIP: symbol;
 
-export { ABORT_STEP_ID, Agent, type AgentConfig, type AgentResultParams, type AgentStepHooks, type AsToolMapOutput, type BranchCase, type BranchSelect, CHECKPOINT_STEP_ID, CheckpointResumedWorkflow, type CheckpointSnapshot, 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 };
+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 };