pipeai 0.8.2 → 0.8.4

package/dist/index.d.ts

@@ -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>;
@@ -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,20 @@ type RepeatOptions<TContext, TOutput> = {
     maxIterations?: number;
 };
 type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
+/**
+ * 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 +577,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,11 +619,61 @@ 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;
 }
+
+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;
 type StepCategory = "step" | "nested" | "branch" | "foreach" | "repeat" | "parallel";
 type StepNode = {
     readonly type: "step";
@@ -606,12 +685,7 @@ type StepNode = {
 } | {
     readonly type: "catch";
     readonly id: string;
-    readonly catchFn: (params: {
-        error: unknown;
-        ctx: unknown;
-        lastOutput: unknown;
-        stepId: string;
-    }) => MaybePromise<unknown>;
+    readonly execute: (state: RuntimeState) => MaybePromise<void>;
 } | {
     readonly type: "finally";
     readonly id: string;
@@ -619,9 +693,8 @@ type StepNode = {
 } | {
     readonly type: "gate";
     readonly id: string;
-    readonly payload: (state: RuntimeState) => MaybePromise<unknown>;
+    readonly execute: (state: RuntimeState) => MaybePromise<void>;
     readonly schema?: SchemaWithParse;
-    readonly condition?: (state: RuntimeState) => MaybePromise<boolean>;
     readonly merge?: (params: {
         priorOutput: unknown;
         response: unknown;
@@ -635,13 +708,39 @@ 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";
+};
+/**
+ * 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;
@@ -649,6 +748,7 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
     protected readonly observability?: WorkflowObservability;
     private duplicateCheckPassed;
     private _cachedExecutableStepCount?;
+    private _cachedCheckpointableStepCount?;
     private _cachedStepShapeHash?;
     protected constructor(steps: ReadonlyArray<StepNode>, id?: string, observability?: WorkflowObservability);
     /**
@@ -665,6 +765,16 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
      * `type: "step"` internally and count as executable.
      */
     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;
     /** @internal — used by `computeStepShapeHash` to descend nested workflows. */
     getStepsForShapeHash(): ReadonlyArray<StepNode>;
     protected get cachedStepShapeHash(): string;
@@ -692,13 +802,44 @@ declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates ext
      * stays allocation-free.
      */
     protected fireHook<K extends keyof WorkflowObservability, E extends Parameters<NonNullable<WorkflowObservability[K]>>[0]>(state: RuntimeState, name: K, event: E): MaybePromise<unknown>;
-    private fireHookSlow;
+    protected hasItemHooks(): boolean;
+    /**
+     * 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>;
     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 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>;
+    /**
+     * 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 +860,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>;
@@ -736,15 +879,31 @@ 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);
     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>;
 }
@@ -766,17 +925,25 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
     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>, 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>): Workflow<TContext, TInput, TNextOutput, TGates>;
+    }) => 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?: {
         payload?: (params: {
             ctx: Readonly<TContext>;
@@ -807,16 +974,23 @@ 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?: {
+    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: {
@@ -825,12 +999,44 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
             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>;
+    /** 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 +1049,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, 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 };