pipeai 0.2.1 → 0.8.0

package/dist/index.d.ts

@@ -24,7 +24,38 @@ declare class ToolProvider<TContext, TInput = unknown, TOutput = unknown> implem
     createTool(context: Readonly<TContext>): Tool;
 }
 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.
@@ -39,6 +70,16 @@ type OutputType<T = any> = ReturnType<typeof Output.object<T>>;
 type AgentToolSet<TContext> = Record<string, Tool | IToolProvider<TContext>>;
 type GenerateTextResult<TOOLS extends ToolSet = ToolSet, OUTPUT extends OutputType = OutputType> = GenerateTextResult$1<TOOLS, OUTPUT>;
 type StreamTextResult<TOOLS extends ToolSet = ToolSet, OUTPUT extends OutputType = OutputType> = StreamTextResult$1<TOOLS, OUTPUT>;
+/**
+ * The result passed to `asTool` / `asToolProvider`'s `mapOutput`.
+ *
+ * The same agent may be invoked as a tool from a generate-mode parent
+ * (returns `GenerateTextResult`, sync `.text`/`.output`) or from a
+ * stream-mode parent (returns `StreamTextResult`, async `.text`/`.output`).
+ * The callsite cannot statically tell which mode it is in, so `mapOutput`
+ * receives the union and must `await` the relevant fields to support both.
+ */
+type AsToolMapOutput<TOutput> = (result: GenerateTextResult<ToolSet, OutputType<TOutput>> | StreamTextResult<ToolSet, OutputType<TOutput>>) => MaybePromise<TOutput>;
 type StreamTextOptions = Parameters<typeof streamText>[0];
 type GenerateTextOptions = Parameters<typeof generateText>[0];
 type ManagedKeys = 'model' | 'system' | 'prompt' | 'messages' | 'tools' | 'activeTools' | 'toolChoice' | 'stopWhen' | 'output' | 'onFinish' | 'onStepFinish' | 'onError';
@@ -48,6 +89,13 @@ interface AgentConfig<TContext, TInput = void, TOutput = void> extends AIPassthr
     description?: string;
     input?: ZodType<TInput>;
     output?: OutputType<TOutput>;
+    /**
+     * Zod schema used to validate `output` after the AI SDK returns. Distinct
+     * from `tool.outputSchema` (AI SDK's tool-execution output schema): this
+     * runs **after** the SDK has parsed structured output, as a runtime guard
+     * against parse drift. If omitted, the parsed output is trusted as-is.
+     */
+    validateOutput?: ZodType<TOutput>;
     model: Resolvable<TContext, TInput, LanguageModel>;
     system?: Resolvable<TContext, TInput, string>;
     prompt?: Resolvable<TContext, TInput, string>;
@@ -55,7 +103,17 @@ interface AgentConfig<TContext, TInput = void, TOutput = void> extends AIPassthr
     tools?: Resolvable<TContext, TInput, AgentToolSet<TContext>>;
     activeTools?: Resolvable<TContext, TInput, string[]>;
     toolChoice?: Resolvable<TContext, TInput, ToolChoice<ToolSet>>;
-    stopWhen?: Resolvable<TContext, TInput, StopCondition<ToolSet> | Array<StopCondition<ToolSet>>>;
+    /**
+     * Stop condition(s) for the tool loop. Pass either a single AI-SDK
+     * `StopCondition` (which is itself a function) or an array of them.
+     *
+     * **Not a `Resolvable`.** A `StopCondition` and a `(ctx, input) => StopCondition`
+     * resolver are both functions and cannot be safely distinguished at
+     * runtime, so this field intentionally does NOT accept the resolver
+     * form. If you need per-call dynamic stop conditions, build the agent
+     * inside your handler instead of using a static instance.
+     */
+    stopWhen?: StopCondition<ToolSet> | Array<StopCondition<ToolSet>>;
     onStepFinish?: (params: {
         result: OnStepFinishEvent;
         ctx: Readonly<TContext>;
@@ -79,6 +137,14 @@ declare class Agent<TContext, TInput = void, TOutput = void> {
     readonly id: string;
     readonly description: string;
     readonly hasOutput: boolean;
+    /**
+     * Zod schema used to validate the agent's structured `output` after the AI
+     * SDK returns. Distinct from `tool.outputSchema` (which validates tool
+     * execution output). Exposed (readonly) so external runners — notably the
+     * workflow runtime — can pass it through to `extractOutput` without
+     * re-plumbing it.
+     */
+    readonly validateOutput: ZodType<TOutput> | undefined;
     private readonly config;
     private readonly _hasDynamicConfig;
     private readonly _resolvedStaticTools;
@@ -86,15 +152,26 @@ declare class Agent<TContext, TInput = void, TOutput = void> {
     private readonly _onStepFinish;
     private readonly _onFinish;
     constructor(config: AgentConfig<TContext, TInput, TOutput>);
-    generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<GenerateTextResult<ToolSet, OutputType<TOutput>>>;
-    stream(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<StreamTextResult<ToolSet, OutputType<TOutput>>>;
+    generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput, options?: {
+        abortSignal?: AbortSignal;
+    }] : [input: TInput, options?: {
+        abortSignal?: AbortSignal;
+    }]): Promise<GenerateTextResult<ToolSet, OutputType<TOutput>>>;
+    stream(ctx: TContext, ...args: TInput extends void ? [input?: TInput, options?: {
+        abortSignal?: AbortSignal;
+    }] : [input: TInput, options?: {
+        abortSignal?: AbortSignal;
+    }]): Promise<StreamTextResult<ToolSet, OutputType<TOutput>>>;
     asTool(ctx: TContext, options?: {
-        mapOutput?: (result: GenerateTextResult<ToolSet, OutputType<TOutput>>) => MaybePromise<TOutput>;
+        mapOutput?: AsToolMapOutput<TOutput>;
     }): Tool;
     asToolProvider(options?: {
-        mapOutput?: (result: GenerateTextResult<ToolSet, OutputType<TOutput>>) => MaybePromise<TOutput>;
+        mapOutput?: AsToolMapOutput<TOutput>;
     }): IToolProvider<TContext>;
     private createToolInstance;
+    private invokeOnError;
+    private generateWithOptions;
+    private streamWithOptions;
     private buildCallOptions;
     private resolveConfig;
     private resolveConfigAsync;
@@ -110,45 +187,270 @@ declare class WorkflowLoopError extends Error {
     readonly maxIterations: number;
     constructor(iterations: number, maxIterations: number);
 }
-interface WorkflowSnapshot {
+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;
+    }[]);
+}
+/**
+ * v2 gate snapshot. The `kind` discriminant differentiates it from
+ * checkpoint snapshots. The legacy v1 form is still accepted by `loadState`.
+ */
+interface GateSnapshot {
+    readonly version: 2;
+    readonly kind: "gate";
+    readonly resumeFromIndex: number;
+    readonly output: unknown;
+    readonly gateId: string;
+    readonly gatePayload: unknown;
+}
+/**
+ * v2 checkpoint snapshot. Carries a step-shape hash; resume verifies the
+ * workflow definition hasn't drifted before continuing.
+ */
+interface CheckpointSnapshot {
+    readonly version: 2;
+    readonly kind: "checkpoint";
+    readonly resumeFromIndex: number;
+    readonly output: unknown;
+    readonly stepShapeHash: string;
+}
+/**
+ * Legacy v0.4.0 gate-only snapshot. Accepted by `loadState` for one release
+ * via the shim path. `kind?: undefined` makes runtime narrowing on
+ * `kind === undefined` reachable — JSON round-trips strip the property.
+ * Migrate via `migrateSnapshot()` before v0.8.0+.
+ */
+interface LegacyGateSnapshotV1 {
     readonly version: 1;
+    readonly kind?: undefined;
     readonly resumeFromIndex: number;
     readonly output: unknown;
     readonly gateId: string;
     readonly gatePayload: unknown;
 }
-declare class WorkflowSuspended extends Error {
-    readonly snapshot: WorkflowSnapshot;
-    constructor(snapshot: WorkflowSnapshot);
+type WorkflowSnapshot = GateSnapshot | CheckpointSnapshot | LegacyGateSnapshotV1;
+interface WorkflowWarning {
+    readonly source: "step" | "finally" | "catch" | "onCheckpoint" | "onStepStart" | "onStepFinish" | "onStepError" | "foreach-sibling";
+    readonly stepId: string;
+    readonly error: unknown;
 }
-interface AgentStepHooks<TContext, TOutput, TNextOutput> {
-    mapGenerateResult?: (params: {
-        result: GenerateTextResult<ToolSet, OutputType<TNextOutput>>;
-        ctx: Readonly<TContext>;
-        input: TOutput;
-    }) => MaybePromise<TNextOutput>;
-    mapStreamResult?: (params: {
-        result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
-        ctx: Readonly<TContext>;
-        input: TOutput;
-    }) => MaybePromise<TNextOutput>;
-    onGenerateResult?: (params: {
-        result: GenerateTextResult<ToolSet, OutputType<TNextOutput>>;
-        ctx: Readonly<TContext>;
-        input: TOutput;
+type WorkflowStepType = "step" | "nested" | "gate" | "catch" | "finally" | "branch" | "foreach" | "repeat" | "parallel";
+/**
+ * Workflow observability hooks. All optional. Errors thrown inside hooks
+ * are captured into `result.warnings` with a matching `source` tag, except
+ * `onStepError`, which causes the run to throw the ORIGINAL step error with
+ * `error.cause = obsError` (preserving `instanceof` on the original).
+ *
+ * Per-node firing rules (where "step-like" = step / nested / branch /
+ * foreach / parallel / repeat):
+ *   - step-like / gate (cond-true → suspends): onStepStart always; onStepFinish
+ *     when body returns (suspended: true for gate, false otherwise); onStepError
+ *     on body throw.
+ *   - gate (cond false → skip): onStepStart, onStepFinish({ suspended: false }).
+ *   - catch: onStepStart only when pendingError set; onStepFinish when catchFn
+ *     returns; onStepError when catchFn throws.
+ *   - finally: onStepStart always (runs even after suspension); onStepFinish
+ *     always; onStepError when body throws.
+ *   - foreach / parallel: emit ALSO per-item events (onItemStart/Finish/Error).
+ *   - repeat: emit ONLY combinator-level events (no per-iteration events —
+ *     iteration count is data-dependent and per-item would be misleading).
+ *
+ * Skip-checked nodes (`state.suspension || pendingError` already set on entry)
+ * emit nothing — `.finally()` is the exception.
+ */
+interface WorkflowObservability {
+    onStepStart?: (event: {
+        stepId: string;
+        type: WorkflowStepType;
+        ctx: unknown;
+        input: unknown;
     }) => MaybePromise<void>;
-    onStreamResult?: (params: {
-        result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
-        ctx: Readonly<TContext>;
-        input: TOutput;
+    onStepFinish?: (event: {
+        stepId: string;
+        type: WorkflowStepType;
+        ctx: unknown;
+        output: unknown;
+        durationMs: number;
+        suspended: boolean;
+    }) => MaybePromise<void>;
+    onStepError?: (event: {
+        stepId: string;
+        type: WorkflowStepType;
+        ctx: unknown;
+        error: unknown;
+        durationMs: number;
+    }) => MaybePromise<void>;
+    onItemStart?: (event: {
+        stepId: string;
+        type: "foreach" | "parallel";
+        itemIndex: number | string;
+        ctx: unknown;
+        input: unknown;
+    }) => MaybePromise<void>;
+    onItemFinish?: (event: {
+        stepId: string;
+        type: "foreach" | "parallel";
+        itemIndex: number | string;
+        ctx: unknown;
+        output: unknown;
+        durationMs: number;
+    }) => MaybePromise<void>;
+    onItemError?: (event: {
+        stepId: string;
+        type: "foreach" | "parallel";
+        itemIndex: number | string;
+        ctx: unknown;
+        error: unknown;
+        durationMs: number;
+    }) => MaybePromise<void>;
+}
+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
+     * as an error — workflow `.catch()` is bypassed for checkpoint failures.
+     */
+    readonly onCheckpoint?: (snapshot: CheckpointSnapshot, opts: {
+        signal: AbortSignal;
     }) => MaybePromise<void>;
+    /**
+     * Fire `onCheckpoint` every N executable steps. Mutually exclusive with
+     * `checkpointWhen`. Default: `max(1, ceil(executableCount / 4))` —
+     * 4 checkpoints across the run, with a floor of every step on tiny pipelines.
+     */
+    readonly checkpointEvery?: number;
+    /**
+     * Predicate variant — fire `onCheckpoint` exactly when this returns true.
+     * Mutually exclusive with `checkpointEvery`.
+     */
+    readonly checkpointWhen?: (params: {
+        stepIndex: number;
+        stepId: string;
+        ctx: unknown;
+    }) => boolean;
+    /**
+     * When truthy, deeply freeze the gate / checkpoint snapshot and the
+     * `result.warnings` array. Default false. Pass `"iAcceptThePerformanceCost"`
+     * to bypass `validateRunOptions`' catastrophic-combo guard
+     * (freezeSnapshots: true + checkpointEvery: 1 + steps.length >= 8).
+     */
+    readonly freezeSnapshots?: boolean | "iAcceptThePerformanceCost";
+    /**
+     * 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.
+     */
+    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.
+ *
+ * - `mode: "generate"` — `result` is a `GenerateTextResult`; `.text`, `.output`,
+ *   `.usage` etc. are synchronous (already-resolved).
+ * - `mode: "stream"` — `result` is a `StreamTextResult`; the same fields are
+ *   `Promise`s that you must `await` before reading.
+ *
+ * The shared field set (`ctx`, `input`) is identical across both modes;
+ * narrowing on `mode` is only necessary when you need to touch a
+ * mode-specific shape.
+ */
+type AgentResultParams<TContext, TOutput, TNextOutput> = {
+    readonly mode: "generate";
+    readonly result: GenerateTextResult<ToolSet, OutputType<TNextOutput>>;
+    readonly ctx: Readonly<TContext>;
+    readonly input: TOutput;
+} | {
+    readonly mode: "stream";
+    readonly result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
+    readonly ctx: Readonly<TContext>;
+    readonly input: TOutput;
+};
+interface AgentStepHooks<TContext, TOutput, TNextOutput> {
+    /**
+     * Transform the agent's result into the next step's input. Fires once per
+     * step regardless of generate-vs-stream mode; discriminate on `mode` if you
+     * need a mode-specific field. Returning the agent's `result.text` works
+     * for both modes (string vs Promise<string>) because `MaybePromise` accepts
+     * either.
+     *
+     * If omitted, the workflow's default extraction is used:
+     *   - With `agent.output` declared → `extractOutput(result, agent.validateOutput)`
+     *   - Without `agent.output` → `result.text` (awaited if stream)
+     */
+    mapResult?: (params: AgentResultParams<TContext, TOutput, TNextOutput>) => MaybePromise<TNextOutput>;
+    /**
+     * Observe the agent's result without changing the step's downstream value.
+     * Fires once per step regardless of mode. Use for logging, telemetry,
+     * usage accounting, side-effects that should not affect pipeline data
+     * flow.
+     */
+    onResult?: (params: AgentResultParams<TContext, TOutput, TNextOutput>) => MaybePromise<void>;
+    /**
+     * **Stream-mode only.** Override the workflow's default
+     * `writer.merge(result.toUIMessageStream())` call so YOU control how the
+     * agent's stream reaches the outer workflow's UI message stream. Useful
+     * for buffering, transforming, fan-out to multiple writers, or injecting
+     * custom UI messages around the agent's output.
+     *
+     * 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.
+     */
     handleStream?: (params: {
         result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
         writer: UIMessageStreamWriter;
         ctx: Readonly<TContext>;
     }) => MaybePromise<void>;
 }
-type StepOptions<TContext, TOutput, TNextOutput> = AgentStepHooks<TContext, TOutput, TNextOutput>;
+type StepOptions<TContext, TOutput, TNextOutput> = AgentStepHooks<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;
+};
 interface BranchCase<TContext, TOutput, TNextOutput> extends AgentStepHooks<TContext, TOutput, TNextOutput> {
     when?: (params: {
         ctx: Readonly<TContext>;
@@ -161,15 +463,32 @@ interface BranchSelect<TContext, TOutput, TKeys extends string, TNextOutput> ext
         ctx: Readonly<TContext>;
         input: TOutput;
     }) => MaybePromise<TKeys>;
-    agents: Record<TKeys, Agent<TContext, any, TNextOutput>>;
-    fallback?: Agent<TContext, any, TNextOutput>;
-}
-interface WorkflowResult<TOutput> {
-    output: TOutput;
+    agents: Record<TKeys, Agent<TContext, TOutput, TNextOutput>>;
+    fallback?: Agent<TContext, TOutput, TNextOutput>;
+    /**
+     * Diagnostic hook invoked when `select` returns a key that has no matching
+     * entry in `agents`. Fires BEFORE `fallback` is applied or
+     * `WorkflowBranchError` is thrown, regardless of whether a `fallback` is
+     * configured. Useful for logging typos / unexpected classifier output.
+     */
+    onUnknownKey?: (params: {
+        key: string;
+        availableKeys: TKeys[];
+        ctx: Readonly<TContext>;
+    }) => void;
 }
+type WorkflowResult<TOutput> = {
+    readonly status: "complete";
+    readonly output: TOutput;
+    readonly warnings: readonly WorkflowWarning[];
+} | {
+    readonly status: "suspended";
+    readonly snapshot: GateSnapshot;
+    readonly warnings: readonly WorkflowWarning[];
+};
 interface WorkflowStreamResult<TOutput> {
     stream: ReadableStream;
-    output: Promise<TOutput>;
+    output: Promise<WorkflowResult<TOutput>>;
 }
 interface WorkflowStreamOptions {
     onError?: (error: unknown) => string;
@@ -190,13 +509,58 @@ type RepeatOptions<TContext, TOutput> = {
     maxIterations?: number;
 };
 type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
+/** 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. */
+type BranchOutput<T> = T extends Agent<any, any, infer O> ? O : T extends SealedWorkflow<any, any, infer O> ? O : never;
+/** Output shape for the record form: `{ [K]: BranchOutput<T[K]> }`. */
+type ParallelOutputRecord<T extends Record<string, unknown>> = {
+    [K in keyof T]: BranchOutput<T[K]>;
+};
+/** Output shape for the tuple form: `[O1, O2, ...]`. */
+type ParallelOutputTuple<T extends ReadonlyArray<unknown>> = {
+    [K in keyof T]: BranchOutput<T[K]>;
+};
+interface ParallelOptions<TContext> {
+    /** 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.
+     */
+    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.
+     *
+     * **Bypassed entirely on the suspension path** (any branch hit a nested
+     * gate). See README's "Suspension under `parallel()`" section.
+     */
+    onError?: (params: {
+        error: unknown;
+        /** Branch key in the record form; `undefined` in the tuple form. */
+        key?: string;
+        /** 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>;
+}
 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;
@@ -226,39 +590,144 @@ interface RuntimeState {
     output: unknown;
     mode: "generate" | "stream";
     writer?: UIMessageStreamWriter;
+    suspension?: GateSnapshot;
+    warnings?: WorkflowWarning[];
+    checkpointFailed?: boolean;
+    runOptions?: RunOptions;
+    abortSignal?: AbortSignal;
 }
+type PendingError = {
+    error: unknown;
+    stepId: string;
+    source: "step" | "finally" | "catch" | "onCheckpoint";
+};
 declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates extends Record<string, unknown> = {}> {
     readonly id?: string;
     protected readonly steps: ReadonlyArray<StepNode>;
-    protected constructor(steps: ReadonlyArray<StepNode>, id?: string);
-    generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<WorkflowResult<TOutput>>;
-    stream(ctx: TContext, ...args: TInput extends void ? [input?: TInput, options?: WorkflowStreamOptions] : [input: TInput, options?: WorkflowStreamOptions]): WorkflowStreamResult<TOutput>;
-    protected execute(state: RuntimeState, startIndex?: number): Promise<void>;
+    protected readonly observability?: WorkflowObservability;
+    private duplicateCheckPassed;
+    private _cachedExecutableStepCount?;
+    private _cachedStepShapeHash?;
+    protected constructor(steps: ReadonlyArray<StepNode>, id?: string, observability?: WorkflowObservability);
+    /**
+     * Walk the step list once per terminal instance. Rejects:
+     *   - Duplicate `(type, id)` pairs.
+     *   - User step ids containing the reserved `::pipeai::` namespace
+     *     (CHECKPOINT_STEP_ID lives there).
+     */
+    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.
+     */
+    protected get cachedExecutableStepCount(): number;
+    /** @internal — used by `computeStepShapeHash` to descend nested workflows. */
+    getStepsForShapeHash(): ReadonlyArray<StepNode>;
+    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.
+     */
+    protected validateRunOptions(opts: RunOptions | undefined): void;
+    /**
+     * Fire an observability hook safely. Returns `undefined` synchronously when
+     * no hook is registered — avoiding the promise wrapper + microtask that an
+     * async function would unconditionally allocate on every step boundary.
+     *
+     * On hook throw:
+     *   - non-`onStepError` hooks: warning pushed + console.error.
+     *   - `onStepError`: throw is propagated as a return value; the run loop
+     *     attaches it as `cause` on the original step error.
+     *
+     * 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.
+     */
+    protected fireHook<K extends keyof WorkflowObservability, E extends Parameters<NonNullable<WorkflowObservability[K]>>[0]>(state: RuntimeState, name: K, event: E): MaybePromise<unknown>;
+    private fireHookSlow;
+    generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput, opts?: RunOptions] : [input: TInput, opts?: RunOptions]): Promise<WorkflowResult<TOutput>>;
+    stream(ctx: TContext, ...args: TInput extends void ? [input?: TInput, options?: WorkflowStreamOptions, opts?: RunOptions] : [input: TInput, options?: WorkflowStreamOptions, opts?: RunOptions]): WorkflowStreamResult<TOutput>;
+    protected buildResult(state: RuntimeState): WorkflowResult<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>;
     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
+     * `{ skipShapeCheck: true }` is passed. Throws on:
+     *   - gate snapshots (use `loadState` instead)
+     *   - missing/corrupted `stepShapeHash`
+     *   - shape mismatch (unless skipped)
+     *   - out-of-bounds `resumeFromIndex`
+     *   - 0-step workflow (structural invariant)
+     *
+     * Returns a `CheckpointResumedWorkflow` whose `generate(ctx, opts?)` takes
+     * NO response arg — the state is seeded from the snapshot's output. The
+     * matching gate-resume path (`loadState`) keeps the `response` arg.
+     */
+    resumeFrom(snapshot: WorkflowSnapshot, options?: {
+        skipShapeCheck?: boolean;
+    }): CheckpointResumedWorkflow<TContext, TOutput>;
+    /**
+     * 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(id: string, fn: (params: {
+        ctx: Readonly<TContext>;
+    }) => MaybePromise<void>): SealedWorkflow<TContext, TInput, TOutput, TGates>;
     private findGateIndex;
 }
+interface ResumedWorkflowConfig {
+    readonly mode: "gate" | "checkpoint";
+    readonly schema?: SchemaWithParse<unknown>;
+    readonly mergeFn?: (params: {
+        priorOutput: unknown;
+        response: unknown;
+    }) => MaybePromise<unknown>;
+    readonly priorOutput?: unknown;
+    readonly snapshot?: WorkflowSnapshot;
+    readonly observability?: WorkflowObservability;
+}
 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;
     /** @internal */
-    constructor(steps: ReadonlyArray<StepNode>, startIndex: number, schema?: SchemaWithParse<TResponse>, mergeFn?: (params: {
-        priorOutput: unknown;
-        response: unknown;
-    }) => MaybePromise<unknown>, priorOutput?: unknown);
+    constructor(steps: ReadonlyArray<StepNode>, startIndex: number, config: ResumedWorkflowConfig);
     private validateResponse;
-    generate(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse] : [response: TResponse]): Promise<WorkflowResult<TOutput>>;
-    stream(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse, options?: WorkflowStreamOptions] : [response: TResponse, options?: WorkflowStreamOptions]): WorkflowStreamResult<TOutput>;
+    generate(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse, opts?: RunOptions] : [response: TResponse, opts?: RunOptions]): Promise<WorkflowResult<TOutput>>;
+    stream(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse, options?: WorkflowStreamOptions, opts?: RunOptions] : [response: TResponse, options?: WorkflowStreamOptions, opts?: RunOptions]): WorkflowStreamResult<TOutput>;
+}
+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);
+    generate(ctx: TContext, ...args: [input?: void, opts?: RunOptions]): Promise<WorkflowResult<TOutput>>;
+    stream(ctx: TContext, ...args: [input?: void, options?: WorkflowStreamOptions, opts?: RunOptions]): WorkflowStreamResult<TOutput>;
 }
 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.
+     */
+    static readonly SKIP: unique symbol;
     private constructor();
     static create<TContext, TInput = void>(options?: {
         id?: string;
+        observability?: WorkflowObservability;
     }): Workflow<TContext, TInput, TInput>;
     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>): Workflow<TContext, TInput, TNextOutput, TGates>;
     step<TNextOutput>(workflow: SealedWorkflow<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
     step<TNextOutput>(id: string, fn: (params: {
@@ -280,23 +749,55 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
             response: TResponse;
         }) => MaybePromise<TResponse>;
     }): Workflow<TContext, TInput, TResponse, TGates & Record<Id, TResponse>>;
-    branch<TNextOutput>(cases: BranchCase<TContext, TOutput, TNextOutput>[]): Workflow<TContext, TInput, TNextOutput, TGates>;
-    branch<TKeys extends string, TNextOutput>(config: BranchSelect<TContext, TOutput, TKeys, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
+    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.
+     *
+     * @param target Agent or `SealedWorkflow` invoked once per item.
+     * @param options.id Override the default step id (`foreach:<agentId>` or
+     *   the workflow's id). Required when chaining multiple foreach over the same
+     *   target — the construction-time `(type, id)` walk rejects duplicates.
+     * @param options.concurrency Max items in flight at any moment (default 1).
+     *   Backed by a semaphore: 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
+     *   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.
+     */
     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>;
-    repeat(target: Agent<TContext, TOutput, TOutput> | SealedWorkflow<TContext, TOutput, TOutput>, options: RepeatOptions<TContext, TOutput>): Workflow<TContext, TInput, TOutput, 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>;
+    /** 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> & {
+        id?: string;
+    }): Workflow<TContext, TInput, TOutput, TGates>;
     catch(id: string, fn: (params: {
         error: unknown;
         ctx: Readonly<TContext>;
         lastOutput: TOutput;
         stepId: string;
     }) => MaybePromise<TOutput>): Workflow<TContext, TInput, TOutput, TGates>;
-    finally(id: string, fn: (params: {
-        ctx: Readonly<TContext>;
-    }) => MaybePromise<void>): SealedWorkflow<TContext, TInput, TOutput, TGates>;
 }
 
-export { Agent, type AgentConfig, type AgentStepHooks, type BranchCase, type BranchSelect, type GenerateTextResult, type IToolProvider, type MaybePromise, type OutputType, type RepeatOptions, type Resolvable, ResumedWorkflow, SealedWorkflow, type StepOptions, type StreamTextResult, type ToolExecuteOptions, type ToolProviderConfig, Workflow, WorkflowBranchError, WorkflowLoopError, type WorkflowResult, type WorkflowSnapshot, type WorkflowStreamOptions, type WorkflowStreamResult, WorkflowSuspended, defineTool };
+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 };