pipeai 0.3.0 → 0.8.0

package/dist/index.cjs

@@ -21,11 +21,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Agent: () => Agent,
+  CHECKPOINT_STEP_ID: () => CHECKPOINT_STEP_ID,
+  CheckpointTimeoutError: () => CheckpointTimeoutError,
+  NestedGateUnsupportedError: () => NestedGateUnsupportedError,
+  SKIP: () => SKIP,
+  TOOL_PROVIDER_BRAND: () => TOOL_PROVIDER_BRAND,
+  ToolProvider: () => ToolProvider,
   Workflow: () => Workflow,
   WorkflowBranchError: () => WorkflowBranchError,
   WorkflowLoopError: () => WorkflowLoopError,
-  WorkflowSuspended: () => WorkflowSuspended,
-  defineTool: () => defineTool
+  defineTool: () => defineTool,
+  getActiveWriter: () => getActiveWriter,
+  isToolProvider: () => isToolProvider,
+  migrateSnapshot: () => migrateSnapshot
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -37,6 +45,7 @@ var import_ai = require("ai");
 
 // src/utils.ts
 var import_node_async_hooks = require("async_hooks");
+var import_node_crypto = require("crypto");
 var writerStorage = new import_node_async_hooks.AsyncLocalStorage();
 function runWithWriter(writer, fn) {
   return writerStorage.run(writer, fn);
@@ -50,35 +59,58 @@ function resolveValue(value, ctx, input) {
   }
   return value;
 }
-var Semaphore = class {
-  available;
-  waiters = [];
-  constructor(permits) {
-    if (!Number.isInteger(permits) || permits < 1) {
-      throw new Error(`Semaphore: permits must be a positive integer, got ${permits}`);
-    }
-    this.available = permits;
-  }
-  async acquire() {
-    if (this.available > 0) {
-      this.available--;
-      return;
-    }
-    await new Promise((resolve) => this.waiters.push(resolve));
-  }
-  release() {
-    const next = this.waiters.shift();
-    if (next) next();
-    else this.available++;
-  }
-};
-async function extractOutput(result, hasStructuredOutput) {
+async function extractOutput(result, hasStructuredOutput, schema) {
   if (hasStructuredOutput) {
     const output = await result.output;
-    if (output !== void 0) return output;
+    if (output === void 0) {
+      throw new Error(
+        "Agent: structured output was declared but the model returned none. This usually means the model produced text that did not match the declared schema, or the underlying SDK did not parse the structured output."
+      );
+    }
+    if (schema) {
+      return schema.parse(output);
+    }
+    return output;
   }
   return await result.text;
 }
+function deepFreeze(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value !== "object" || seen.has(value)) return value;
+  if (Object.isFrozen(value)) return value;
+  seen.add(value);
+  Object.freeze(value);
+  for (const key of Reflect.ownKeys(value)) {
+    deepFreeze(value[key], seen);
+  }
+  return value;
+}
+function computeStepShapeHash(steps, getNested) {
+  return (0, import_node_crypto.createHash)("sha256").update(canonicalDescriptor(steps, getNested, /* @__PURE__ */ new WeakSet())).digest("hex");
+}
+function canonicalDescriptor(steps, getNested, path) {
+  return JSON.stringify(steps.map((s, i) => {
+    const triple = [i, s.type, s.id];
+    for (const inner of getNested(s)) {
+      if (path.has(inner)) {
+        triple.push(`<cycle:${inner.id ?? "anon"}>`);
+        continue;
+      }
+      path.add(inner);
+      try {
+        triple.push(canonicalDescriptor(inner.getStepsForShapeHash(), getNested, path));
+      } finally {
+        path.delete(inner);
+      }
+    }
+    return triple;
+  }));
+}
+var warnedOnceKeys = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+  if (warnedOnceKeys.has(key)) return;
+  warnedOnceKeys.add(key);
+  console.warn(message ?? key);
+}
 
 // src/tool-provider.ts
 var TOOL_PROVIDER_BRAND = /* @__PURE__ */ Symbol.for("agent-workflow.ToolProvider");
@@ -109,10 +141,17 @@ var Agent = class {
   id;
   description;
   hasOutput;
+  /**
+   * 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.
+   */
+  validateOutput;
   config;
   _hasDynamicConfig;
   _resolvedStaticTools = null;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   _passthrough;
   _onStepFinish;
   _onFinish;
@@ -120,6 +159,7 @@ var Agent = class {
     this.id = config.id;
     this.description = config.description ?? "";
     this.hasOutput = config.output !== void 0;
+    this.validateOutput = config.validateOutput;
     this.config = config;
     this._hasDynamicConfig = [
       config.model,
@@ -128,8 +168,7 @@ var Agent = class {
       config.messages,
       config.tools,
       config.activeTools,
-      config.toolChoice,
-      config.stopWhen
+      config.toolChoice
     ].some((v) => typeof v === "function");
     if (!this._hasDynamicConfig) {
       const rawTools = config.tools ?? {};
@@ -143,6 +182,7 @@ var Agent = class {
       description: _desc,
       input: _inputSchema,
       output: _output,
+      validateOutput: _validateOutput,
       model: _m,
       system: _s,
       prompt: _p,
@@ -162,25 +202,13 @@ var Agent = class {
   }
   async generate(ctx, ...args) {
     const input = args[0];
-    const resolved = await this.resolveConfig(ctx, input);
-    const options = this.buildCallOptions(resolved, ctx, input);
-    try {
-      return await (0, import_ai2.generateText)(options);
-    } catch (error) {
-      if (this.config.onError) {
-        await this.config.onError({ error, ctx, input, writer: getActiveWriter() });
-      }
-      throw error;
-    }
+    const callOptions = args[1];
+    return this.generateWithOptions(ctx, input, callOptions ?? {});
   }
   async stream(ctx, ...args) {
     const input = args[0];
-    const resolved = await this.resolveConfig(ctx, input);
-    const options = this.buildCallOptions(resolved, ctx, input);
-    return (0, import_ai2.streamText)({
-      ...options,
-      onError: this.config.onError ? ({ error }) => this.config.onError({ error, ctx, input, writer: getActiveWriter() }) : void 0
-    });
+    const callOptions = args[1];
+    return this.streamWithOptions(ctx, input, callOptions ?? {});
   }
   asTool(ctx, options) {
     return this.createToolInstance(ctx, options);
@@ -201,24 +229,86 @@ var Agent = class {
     return (0, import_ai2.tool)({
       description: this.description,
       inputSchema: this.config.input,
-      execute: async (toolInput) => {
+      // The AI SDK passes a `ToolExecutionOptions` argument that carries
+      // `abortSignal`, `toolCallId`, `messages`, etc. Forward `abortSignal` so
+      // a parent agent's abort cancels in-flight sub-agent calls instead of
+      // leaving them running and producing detached output.
+      execute: async (toolInput, execOptions) => {
+        const abortSignal = execOptions?.abortSignal;
         const writer = getActiveWriter();
         if (writer) {
-          const result2 = await this.stream(ctx, toolInput);
+          const result2 = await this.streamWithOptions(ctx, toolInput, { abortSignal });
           writer.merge(result2.toUIMessageStream());
-          if (options?.mapOutput) return options.mapOutput(result2);
-          return extractOutput(result2, this.hasOutput);
+          if (options?.mapOutput) {
+            await result2.text;
+            return options.mapOutput(result2);
+          }
+          return extractOutput(result2, this.hasOutput, this.validateOutput);
         }
-        const result = await this.generate(ctx, toolInput);
+        const result = await this.generateWithOptions(ctx, toolInput, { abortSignal });
         if (options?.mapOutput) return options.mapOutput(result);
-        return extractOutput(result, this.hasOutput);
+        return extractOutput(result, this.hasOutput, this.validateOutput);
       }
       // TS cannot simplify the SDK's `NeverOptional<TOutput, ...>` conditional in a
       // generic context, so we cast through `unknown` instead of `any`.
     });
   }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  // ── Internal: shared call helpers ─────────────────────────────
+  // `generate()` / `stream()` and the `asTool()` wrapper all funnel through
+  // these so the abortSignal-forwarding and onError-wrapping logic stays in
+  // one place. `extra` carries per-call overrides (currently `abortSignal`).
+  // If the user-supplied onError callback itself throws, attach the original
+  // model error as `.cause` on the new error and rethrow the wrapper. Without
+  // this, the original error is silently shadowed.
+  async invokeOnError(error, ctx, input) {
+    if (!this.config.onError) return;
+    try {
+      await this.config.onError({ error, ctx, input, writer: getActiveWriter() });
+    } catch (handlerError) {
+      if (handlerError instanceof Error) {
+        if (handlerError.cause === void 0) {
+          handlerError.cause = error;
+        }
+        throw handlerError;
+      }
+      const wrapped = new Error(
+        `Agent "${this.id}": onError handler threw a non-Error value (${typeof handlerError}): ${String(handlerError)}`
+      );
+      wrapped.cause = error;
+      throw wrapped;
+    }
+  }
+  async generateWithOptions(ctx, input, extra) {
+    const resolved = await this.resolveConfig(ctx, input);
+    const options = this.buildCallOptions(resolved, ctx, input);
+    try {
+      return await (0, import_ai2.generateText)({ ...options, ...extra });
+    } catch (error) {
+      await this.invokeOnError(error, ctx, input);
+      throw error;
+    }
+  }
+  async streamWithOptions(ctx, input, extra) {
+    const resolved = await this.resolveConfig(ctx, input);
+    const options = this.buildCallOptions(resolved, ctx, input);
+    try {
+      const onErrorOption = this.config.onError ? { onError: ({ error }) => this.invokeOnError(error, ctx, input) } : {};
+      return (0, import_ai2.streamText)({
+        ...options,
+        ...extra,
+        ...onErrorOption
+      });
+    } catch (error) {
+      await this.invokeOnError(error, ctx, input);
+      throw error;
+    }
+  }
   buildCallOptions(resolved, ctx, input) {
+    if (resolved.messages === void 0 && resolved.prompt === void 0) {
+      throw new Error(
+        `Agent "${this.id}": neither \`prompt\` nor \`messages\` was provided. Configure one of them, or supply a Resolvable that returns one based on input.`
+      );
+    }
     return {
       ...this._passthrough,
       model: resolved.model,
@@ -226,11 +316,16 @@ var Agent = class {
       activeTools: resolved.activeTools,
       toolChoice: resolved.toolChoice,
       stopWhen: resolved.stopWhen,
-      ...resolved.messages ? { messages: resolved.messages } : { prompt: resolved.prompt ?? "" },
-      ...resolved.system ? { system: resolved.system } : {},
+      ...resolved.messages !== void 0 ? { messages: resolved.messages } : { prompt: resolved.prompt },
+      // Use `!== undefined` rather than truthy so an intentional empty
+      // `system: ""` survives instead of being silently dropped.
+      ...resolved.system !== void 0 ? { system: resolved.system } : {},
       ...this.config.output ? { output: this.config.output } : {},
-      onStepFinish: this._onStepFinish ? (event) => this._onStepFinish({ result: event, ctx, input, writer: getActiveWriter() }) : void 0,
-      onFinish: this._onFinish ? (event) => this._onFinish({ result: event, ctx, input, writer: getActiveWriter() }) : void 0
+      // Only attach the callback when the user supplied one. Passing
+      // `undefined` explicitly can suppress default SDK rethrow behavior in
+      // some versions.
+      ...this._onStepFinish ? { onStepFinish: (event) => this._onStepFinish({ result: event, ctx, input, writer: getActiveWriter() }) } : {},
+      ...this._onFinish ? { onFinish: (event) => this._onFinish({ result: event, ctx, input, writer: getActiveWriter() }) } : {}
     };
   }
   resolveConfig(ctx, input) {
@@ -252,18 +347,27 @@ var Agent = class {
     return this.resolveConfigAsync(ctx, input);
   }
   async resolveConfigAsync(ctx, input) {
-    const [model, prompt, system, messages, rawTools, activeTools, toolChoice, stopWhen] = await Promise.all([
+    const [model, prompt, system, messages, rawTools, activeTools, toolChoice] = await Promise.all([
       resolveValue(this.config.model, ctx, input),
       resolveValue(this.config.prompt, ctx, input),
       resolveValue(this.config.system, ctx, input),
       resolveValue(this.config.messages, ctx, input),
       resolveValue(this.config.tools, ctx, input),
       resolveValue(this.config.activeTools, ctx, input),
-      resolveValue(this.config.toolChoice, ctx, input),
-      resolveValue(this.config.stopWhen, ctx, input)
+      resolveValue(this.config.toolChoice, ctx, input)
     ]);
     const tools = this.resolveTools(rawTools ?? {}, ctx);
-    return { model, prompt, system, messages, tools, activeTools, toolChoice, stopWhen };
+    return {
+      model,
+      prompt,
+      system,
+      messages,
+      tools,
+      activeTools,
+      toolChoice,
+      // `stopWhen` is always static — see field declaration for why.
+      stopWhen: this.config.stopWhen
+    };
   }
   resolveTools(tools, ctx) {
     const entries = Object.entries(tools);
@@ -299,37 +403,284 @@ var WorkflowLoopError = class extends Error {
     this.name = "WorkflowLoopError";
   }
 };
-var WorkflowSuspended = class extends Error {
-  snapshot;
-  constructor(snapshot) {
-    super(`Workflow suspended at gate "${snapshot.gateId}"`);
-    this.name = "WorkflowSuspended";
-    this.snapshot = snapshot;
+var NestedGateUnsupportedError = class extends Error {
+  gateId;
+  workflowId;
+  // Always present; non-gate rejections from concurrent foreach.
+  siblingErrors;
+  // Always present; OTHER suspending items in concurrent foreach.
+  siblingSuspensions;
+  constructor(gateId, workflowId, siblingErrors = [], siblingSuspensions = []) {
+    super(`Gate "${gateId}" hit inside nested workflow "${workflowId ?? "(anonymous)"}". Nested gates are not yet supported.`);
+    this.name = "NestedGateUnsupportedError";
+    this.gateId = gateId;
+    this.workflowId = workflowId;
+    this.siblingErrors = siblingErrors;
+    this.siblingSuspensions = siblingSuspensions;
   }
 };
-var SealedWorkflow = class {
+var CHECKPOINT_STEP_ID = "::pipeai::onCheckpoint";
+var CheckpointTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`onCheckpoint exceeded ${timeoutMs}ms timeout`);
+    this.name = "CheckpointTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+function resolveFreezeSnapshots(state) {
+  return state.runOptions?.freezeSnapshots ? true : false;
+}
+function migrateSnapshot(legacy) {
+  if (legacy.version !== 1) {
+    throw new Error(`migrateSnapshot: expected v1 snapshot, got version ${legacy.version}`);
+  }
+  return {
+    version: 2,
+    kind: "gate",
+    resumeFromIndex: legacy.resumeFromIndex,
+    output: legacy.output,
+    gateId: legacy.gateId,
+    gatePayload: legacy.gatePayload
+  };
+}
+function getObservabilityType(node) {
+  if (node.type !== "step") return node.type;
+  return node.category ?? "step";
+}
+function getNestedWorkflows(node) {
+  switch (node.type) {
+    case "step":
+      return node.nestedWorkflow ? [node.nestedWorkflow] : [];
+    case "gate":
+    case "catch":
+    case "finally":
+      return [];
+  }
+}
+function pendingErrorSourceToStepType(source) {
+  switch (source) {
+    case "step":
+      return "step";
+    case "finally":
+      return "finally";
+    case "catch":
+      return "catch";
+    case "onCheckpoint":
+      return "step";
+  }
+}
+async function emitCheckpoint(state, opts, resumeFromIndex, stepShapeHash) {
+  if (!opts.onCheckpoint) return;
+  const snap = {
+    version: 2,
+    kind: "checkpoint",
+    resumeFromIndex,
+    output: state.output,
+    stepShapeHash
+  };
+  if (resolveFreezeSnapshots(state)) deepFreeze(snap);
+  const controller = new AbortController();
+  if (opts.checkpointTimeout !== void 0) {
+    const timeoutMs = opts.checkpointTimeout;
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const callPromise = Promise.resolve(opts.onCheckpoint(snap, { signal: controller.signal }));
+      const timeoutPromise = new Promise((_, reject) => {
+        controller.signal.addEventListener(
+          "abort",
+          () => reject(new CheckpointTimeoutError(timeoutMs)),
+          { once: true }
+        );
+      });
+      callPromise.catch(() => {
+      });
+      timeoutPromise.catch(() => {
+      });
+      await Promise.race([callPromise, timeoutPromise]);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  } else {
+    await opts.onCheckpoint(snap, { signal: controller.signal });
+  }
+}
+var warnedStreamOnErrorOnSuspend = false;
+function pushWarning(state, source, stepId, error) {
+  (state.warnings ??= []).push({ source, stepId, error });
+}
+function demotePendingError(state, pe) {
+  pushWarning(state, pe.source, pe.stepId, pe.error);
+}
+function maybeWarnStreamOnErrorOnSuspend(result, options) {
+  if (result.status !== "suspended" || !options?.onError || warnedStreamOnErrorOnSuspend) return;
+  warnedStreamOnErrorOnSuspend = true;
+  console.warn(
+    "pipeai: stream() with options.onError suspended at a gate \u2014 onError will NOT be invoked for suspension. Discriminate via the resolved output Promise."
+  );
+}
+var SealedWorkflow = class _SealedWorkflow {
   id;
   steps;
-  constructor(steps, id) {
+  observability;
+  // Memoized — see ensureDuplicateCheck().
+  duplicateCheckPassed = false;
+  // Memoized lazily per terminal instance — build pipelines once at module
+  // load and re-run via generate() to amortize.
+  _cachedExecutableStepCount;
+  _cachedStepShapeHash;
+  constructor(steps, id, observability) {
     this.steps = steps;
     this.id = id;
+    this.observability = observability;
+  }
+  // ── Construction-time validation (memoized per terminal instance) ────
+  /**
+   * 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).
+   */
+  ensureDuplicateCheck() {
+    if (this.duplicateCheckPassed) return;
+    const seen = /* @__PURE__ */ new Map();
+    for (let i = 0; i < this.steps.length; i++) {
+      const node = this.steps[i];
+      if (node.id.includes("::pipeai::")) {
+        throw new Error(
+          `Workflow: step id "${node.id}" uses the reserved "::pipeai::" namespace at index ${i}.`
+        );
+      }
+      const key = `${node.type}:${node.id}`;
+      const prior = seen.get(key);
+      if (prior !== void 0) {
+        throw new Error(
+          `Workflow: duplicate (${node.type}, "${node.id}") at indices ${prior} and ${i}. Pass an explicit \`{ id }\` (e.g. for back-to-back \`branch(...)\` or \`foreach(agentX).foreach(agentX)\`) to disambiguate.`
+        );
+      }
+      seen.set(key, i);
+    }
+    this.duplicateCheckPassed = true;
+  }
+  // ── shape-hash + RunOptions validation ────────────────────────
+  /**
+   * 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.
+   */
+  get cachedExecutableStepCount() {
+    if (this._cachedExecutableStepCount !== void 0) return this._cachedExecutableStepCount;
+    let n = 0;
+    for (const s of this.steps) {
+      if (s.type !== "catch" && s.type !== "finally") n++;
+    }
+    this._cachedExecutableStepCount = n;
+    return n;
+  }
+  /** @internal — used by `computeStepShapeHash` to descend nested workflows. */
+  getStepsForShapeHash() {
+    return this.steps;
+  }
+  get cachedStepShapeHash() {
+    if (this._cachedStepShapeHash !== void 0) return this._cachedStepShapeHash;
+    const getNested = (node) => getNestedWorkflows(node);
+    this._cachedStepShapeHash = computeStepShapeHash(
+      this.steps,
+      getNested
+    );
+    return this._cachedStepShapeHash;
+  }
+  /**
+   * 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.
+   */
+  validateRunOptions(opts) {
+    if (!opts) return;
+    if (!opts.onCheckpoint) return;
+    if (opts.checkpointEvery !== void 0 && opts.checkpointWhen !== void 0) {
+      throw new Error("RunOptions: checkpointEvery and checkpointWhen are mutually exclusive");
+    }
+    if (opts.checkpointEvery !== void 0 && (!Number.isInteger(opts.checkpointEvery) || opts.checkpointEvery < 1)) {
+      throw new Error(`RunOptions: checkpointEvery must be a positive integer, got ${opts.checkpointEvery}`);
+    }
+    if (opts.checkpointTimeout !== void 0 && (!Number.isFinite(opts.checkpointTimeout) || opts.checkpointTimeout < 1)) {
+      throw new Error(`RunOptions: checkpointTimeout must be a finite positive number (ms), got ${opts.checkpointTimeout}`);
+    }
+    const length = this.cachedExecutableStepCount;
+    const cadence = opts.checkpointEvery ?? Math.max(1, Math.ceil(length / 4));
+    if (opts.freezeSnapshots && opts.freezeSnapshots !== "iAcceptThePerformanceCost" && cadence === 1 && length >= 8) {
+      throw new Error(
+        `freezeSnapshots+checkpointEvery:1 on a ${length}-step workflow is reliably catastrophic. Set checkpointEvery >= 5, freezeSnapshots: false, or pass "iAcceptThePerformanceCost".`
+      );
+    }
+    if (opts.freezeSnapshots && cadence <= 2) {
+      warnOnce(
+        "pipeai:freezeSnapshots-low-cadence",
+        "pipeai: freezeSnapshots+checkpointEvery<=2 compounds graph-walk cost."
+      );
+    }
+  }
+  // ── Observability helpers ─────────────────────────────────────
+  /**
+   * 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.
+   */
+  fireHook(state, name, event) {
+    const hook = this.observability?.[name];
+    if (!hook) return void 0;
+    return this.fireHookSlow(state, name, event, hook);
+  }
+  async fireHookSlow(state, name, event, hook) {
+    try {
+      await hook(event);
+      return void 0;
+    } catch (e) {
+      if (name !== "onStepError") {
+        const stepId = event.stepId;
+        pushWarning(state, name, stepId, e);
+        console.error(`pipeai: ${name} hook threw for stepId "${stepId}":`, e);
+      }
+      return e;
+    }
   }
   // ── Execution ─────────────────────────────────────────────────
   async generate(ctx, ...args) {
+    this.ensureDuplicateCheck();
     const input = args[0];
+    const opts = args[1];
+    this.validateRunOptions(opts);
     const state = {
       ctx,
       output: input,
-      mode: "generate"
-    };
-    await this.execute(state);
-    return {
-      output: state.output
+      mode: "generate",
+      runOptions: opts,
+      abortSignal: opts?.abortSignal
     };
+    await this.execute(state, 0, opts);
+    return this.buildResult(state);
   }
   stream(ctx, ...args) {
+    this.ensureDuplicateCheck();
     const input = args[0];
     const options = args[1];
+    const opts = args[2];
+    this.validateRunOptions(opts);
+    const abortSignal = opts?.abortSignal;
     let resolveOutput;
     let rejectOutput;
     const outputPromise = new Promise((res, rej) => {
@@ -344,11 +695,15 @@ var SealedWorkflow = class {
           ctx,
           output: input,
           mode: "stream",
-          writer
+          writer,
+          runOptions: opts,
+          abortSignal
         };
         try {
-          await this.execute(state);
-          resolveOutput(state.output);
+          await this.execute(state, 0, opts);
+          const result = this.buildResult(state);
+          maybeWarnStreamOnErrorOnSuspend(result, options);
+          resolveOutput(result);
         } catch (error) {
           rejectOutput(error);
           throw error;
@@ -362,20 +717,78 @@ var SealedWorkflow = class {
       output: outputPromise
     };
   }
+  // Helper — converts terminal RuntimeState into a WorkflowResult; freezes
+  // snapshot + warnings if requested via runOptions.
+  buildResult(state) {
+    const warnings = state.warnings ?? [];
+    if (state.suspension && resolveFreezeSnapshots(state)) {
+      deepFreeze(warnings);
+    }
+    if (state.suspension) {
+      return { status: "suspended", snapshot: state.suspension, warnings };
+    }
+    return { status: "complete", output: state.output, warnings };
+  }
   // ── Internal: execute pipeline ────────────────────────────────
-  async execute(state, startIndex = 0) {
+  async execute(state, startIndex = 0, opts, initialError = null) {
     if (this.steps.length === 0) {
       throw new Error("Workflow has no steps. Add at least one step before calling generate() or stream().");
     }
-    let pendingError = null;
+    if (opts !== void 0 && state.runOptions === void 0) {
+      state.runOptions = opts;
+    }
+    const ckptCadence = opts?.onCheckpoint && opts.checkpointWhen === void 0 ? opts.checkpointEvery ?? Math.max(1, Math.ceil(this.cachedExecutableStepCount / 4)) : 0;
+    let pendingError = initialError;
+    let abortPromoted = false;
+    const makeAbortError = (signal) => ({
+      error: signal.reason ?? new Error("Workflow aborted"),
+      stepId: "abort",
+      source: "step"
+    });
     for (let i = startIndex; i < this.steps.length; i++) {
+      if (state.abortSignal?.aborted) {
+        if (!abortPromoted) {
+          abortPromoted = true;
+          state.suspension = void 0;
+          if (pendingError) demotePendingError(state, pendingError);
+          pendingError = makeAbortError(state.abortSignal);
+        } else if (!pendingError) {
+          pendingError = makeAbortError(state.abortSignal);
+        }
+      }
       const node = this.steps[i];
       if (node.type === "finally") {
-        await node.execute(state);
+        const stepId2 = node.id;
+        const finStart = performance.now();
+        await this.fireHook(state, "onStepStart", { stepId: stepId2, type: "finally", ctx: state.ctx, input: state.output });
+        try {
+          await node.execute(state);
+          await this.fireHook(state, "onStepFinish", {
+            stepId: stepId2,
+            type: "finally",
+            ctx: state.ctx,
+            output: state.output,
+            durationMs: performance.now() - finStart,
+            suspended: false
+          });
+        } catch (e) {
+          await this.fireHook(state, "onStepError", {
+            stepId: stepId2,
+            type: "finally",
+            ctx: state.ctx,
+            error: e,
+            durationMs: performance.now() - finStart
+          });
+          if (pendingError) demotePendingError(state, pendingError);
+          pendingError = { error: e, stepId: stepId2, source: "finally" };
+        }
         continue;
       }
       if (node.type === "catch") {
-        if (!pendingError) continue;
+        if (state.suspension || !pendingError || state.checkpointFailed) continue;
+        const stepId2 = node.id;
+        const cStart = performance.now();
+        await this.fireHook(state, "onStepStart", { stepId: stepId2, type: "catch", ctx: state.ctx, input: state.output });
         try {
           state.output = await node.catchFn({
             error: pendingError.error,
@@ -384,49 +797,183 @@ var SealedWorkflow = class {
             stepId: pendingError.stepId
           });
           pendingError = null;
-        } catch (catchError) {
-          pendingError = { error: catchError, stepId: node.id };
+          await this.fireHook(state, "onStepFinish", {
+            stepId: stepId2,
+            type: "catch",
+            ctx: state.ctx,
+            output: state.output,
+            durationMs: performance.now() - cStart,
+            suspended: false
+          });
+        } catch (e) {
+          await this.fireHook(state, "onStepError", {
+            stepId: stepId2,
+            type: "catch",
+            ctx: state.ctx,
+            error: e,
+            durationMs: performance.now() - cStart
+          });
+          if (pendingError) demotePendingError(state, pendingError);
+          pendingError = { error: e, stepId: stepId2, source: "catch" };
         }
         continue;
       }
+      if (state.suspension || pendingError) continue;
       if (node.type === "gate") {
-        if (pendingError) continue;
-        if (node.condition) {
-          const shouldSuspend = await node.condition(state);
-          if (!shouldSuspend) continue;
-        }
-        const gatePayload = await node.payload(state);
-        throw new WorkflowSuspended({
-          version: 1,
-          resumeFromIndex: i,
+        const stepId2 = node.id;
+        const gStart = performance.now();
+        await this.fireHook(state, "onStepStart", { stepId: stepId2, type: "gate", ctx: state.ctx, input: state.output });
+        try {
+          if (node.condition && !await node.condition(state)) {
+            await this.fireHook(state, "onStepFinish", {
+              stepId: stepId2,
+              type: "gate",
+              ctx: state.ctx,
+              output: state.output,
+              durationMs: performance.now() - gStart,
+              suspended: false
+            });
+            continue;
+          }
+          const snapshot = {
+            version: 2,
+            kind: "gate",
+            resumeFromIndex: i,
+            output: state.output,
+            gateId: node.id,
+            gatePayload: await node.payload(state)
+          };
+          state.suspension = snapshot;
+          if (resolveFreezeSnapshots(state)) deepFreeze(snapshot);
+          await this.fireHook(state, "onStepFinish", {
+            stepId: stepId2,
+            type: "gate",
+            ctx: state.ctx,
+            output: state.output,
+            durationMs: performance.now() - gStart,
+            suspended: true
+          });
+        } catch (e) {
+          pendingError = { error: e, stepId: node.id, source: "step" };
+        }
+        continue;
+      }
+      const obsType = getObservabilityType(node);
+      const stepId = node.id;
+      const sStart = performance.now();
+      const stepInput = state.output;
+      await this.fireHook(state, "onStepStart", { stepId, type: obsType, ctx: state.ctx, input: stepInput });
+      try {
+        await node.execute(state);
+        await this.fireHook(state, "onStepFinish", {
+          stepId,
+          type: obsType,
+          ctx: state.ctx,
           output: state.output,
-          gateId: node.id,
-          gatePayload
+          durationMs: performance.now() - sStart,
+          suspended: false
+        });
+      } catch (e) {
+        pendingError = { error: e, stepId: node.id, source: "step" };
+        const obsError = await this.fireHook(state, "onStepError", {
+          stepId,
+          type: obsType,
+          ctx: state.ctx,
+          error: e,
+          durationMs: performance.now() - sStart
         });
+        if (obsError !== void 0 && typeof e === "object" && e !== null) {
+          try {
+            e.cause = obsError;
+          } catch {
+          }
+        }
+      }
+      const leaked = state.suspension;
+      if (leaked) {
+        state.suspension = void 0;
+        throw new Error(`internal: suspension bubbled from non-gate step "${node.id}" (gate "${leaked.gateId}").`);
+      }
+      if (!pendingError && !state.suspension && opts?.onCheckpoint) {
+        const shouldCheckpoint = opts.checkpointWhen ? opts.checkpointWhen({ stepIndex: i, stepId: node.id, ctx: state.ctx }) : (i + 1) % ckptCadence === 0;
+        if (shouldCheckpoint) {
+          const ckptStart = performance.now();
+          try {
+            await emitCheckpoint(
+              state,
+              opts,
+              i + 1,
+              this.cachedStepShapeHash
+            );
+          } catch (e) {
+            pendingError = { error: e, stepId: CHECKPOINT_STEP_ID, source: "onCheckpoint" };
+            state.checkpointFailed = true;
+            await this.fireHook(state, "onStepError", {
+              stepId: CHECKPOINT_STEP_ID,
+              type: "step",
+              ctx: state.ctx,
+              error: e,
+              durationMs: performance.now() - ckptStart
+            });
+          }
+        }
+      }
+    }
+    if (pendingError && !state.suspension) {
+      if (state.checkpointFailed) {
+        const warningsArr = state.warnings ?? [];
+        const checkpointError = pendingError.source === "onCheckpoint" ? pendingError.error : warningsArr.find((w) => w.source === "onCheckpoint")?.error;
+        const finallyErrors = warningsArr.filter((w) => w.source === "finally").map((w) => w.error);
+        const all = pendingError.source === "finally" ? [...finallyErrors, pendingError.error] : finallyErrors;
+        if (all.length > 0) {
+          console.warn(
+            `pipeai: ${all.length} .finally() error(s) suppressed by checkpoint-failure precedence:`,
+            all
+          );
+        }
+        throw checkpointError ?? pendingError.error;
+      }
+      const isFinallyPath = pendingError.source === "finally" || (state.warnings?.some((w) => w.source === "finally") ?? false);
+      if (isFinallyPath) {
+        const all = [...(state.warnings ?? []).map((w) => w.error), pendingError.error];
+        throw new AggregateError(all, `Workflow failed with ${all.length} error(s) from .finally() bodies`);
       }
-      if (pendingError) continue;
+      throw pendingError.error;
+    } else if (pendingError && state.suspension) {
+      demotePendingError(state, pendingError);
       try {
-        await node.execute(state);
-      } catch (error) {
-        if (error instanceof WorkflowSuspended) throw error;
-        pendingError = { error, stepId: node.id };
+        await this.observability?.onStepError?.({
+          stepId: pendingError.stepId,
+          type: pendingErrorSourceToStepType(pendingError.source),
+          ctx: state.ctx,
+          error: pendingError.error,
+          durationMs: 0
+        });
+      } catch (obsError) {
+        pushWarning(state, "onStepError", pendingError.stepId, obsError);
       }
+      pendingError = null;
     }
-    if (pendingError) throw pendingError.error;
   }
   // ── Internal: execute a nested workflow within a step/loop ─────
   // Defined on SealedWorkflow (not Workflow) because TypeScript's protected
   // access rules only allow calling workflow.execute() from the same class.
+  //
+  // Contract: clears any inner suspension before re-throwing as
+  // NestedGateUnsupportedError. The outer execute() therefore never observes
+  // a leaked `state.suspension` from non-gate nodes (defensive invariant).
   async executeNestedWorkflow(state, workflow) {
+    const savedRunOptions = state.runOptions;
+    state.runOptions = void 0;
     try {
       await workflow.execute(state);
-    } catch (error) {
-      if (error instanceof WorkflowSuspended) {
-        throw new Error(
-          `Gates inside nested workflows are not yet supported. Gate "${error.snapshot.gateId}" was hit inside nested workflow "${workflow.id ?? "(anonymous)"}". Consider using a conditional gate with \`condition\` to skip when criteria are met, or restructure the workflow to use gates at the top level only.`
-        );
-      }
-      throw error;
+    } finally {
+      state.runOptions = savedRunOptions;
+    }
+    if (state.suspension) {
+      const gateId = state.suspension.gateId;
+      state.suspension = void 0;
+      throw new NestedGateUnsupportedError(gateId, workflow.id);
     }
   }
   // ── Internal: execute an agent within a step/branch ───────────
@@ -436,59 +983,141 @@ var SealedWorkflow = class {
   async executeAgent(state, agent, ctx, options) {
     const input = state.output;
     const hasStructuredOutput = agent.hasOutput;
+    const abortSignal = state.abortSignal;
+    const agentCallOpts = abortSignal ? { abortSignal } : void 0;
     if (state.mode === "stream" && state.writer) {
       const writer = state.writer;
       await runWithWriter(writer, async () => {
-        const result = await agent.stream(ctx, state.output);
+        const result = await agent.stream(ctx, state.output, agentCallOpts);
         if (options?.handleStream) {
           await options.handleStream({ result, writer, ctx });
         } else {
           writer.merge(result.toUIMessageStream());
         }
-        if (options?.onStreamResult) {
-          await options.onStreamResult({ result, ctx, input });
+        const hookParams = {
+          mode: "stream",
+          result,
+          ctx,
+          input
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        };
+        if (options?.onResult) {
+          await options.onResult(hookParams);
         }
-        if (options?.mapStreamResult) {
-          state.output = await options.mapStreamResult({ result, ctx, input });
+        if (options?.mapResult) {
+          state.output = await options.mapResult(hookParams);
         } else {
-          state.output = await extractOutput(result, hasStructuredOutput);
+          state.output = await extractOutput(result, hasStructuredOutput, agent.validateOutput);
         }
       });
     } else {
-      const result = await agent.generate(ctx, state.output);
-      if (options?.onGenerateResult) {
-        await options.onGenerateResult({ result, ctx, input });
+      const result = await agent.generate(ctx, state.output, agentCallOpts);
+      const hookParams = {
+        mode: "generate",
+        result,
+        ctx,
+        input
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      };
+      if (options?.onResult) {
+        await options.onResult(hookParams);
       }
-      if (options?.mapGenerateResult) {
-        state.output = await options.mapGenerateResult({ result, ctx, input });
+      if (options?.mapResult) {
+        state.output = await options.mapResult(hookParams);
       } else {
-        state.output = await extractOutput(result, hasStructuredOutput);
+        state.output = await extractOutput(result, hasStructuredOutput, agent.validateOutput);
       }
     }
   }
   // ── Gate: load persisted state for resumption ──────────────────
   loadState(gateId, snapshot) {
-    if (snapshot.gateId !== gateId) {
+    if (snapshot.version === 2 && snapshot.kind === "checkpoint") {
+      throw new Error(`loadState: received a checkpoint snapshot. Use resumeFrom() for checkpoint resume; loadState() is for gates.`);
+    }
+    const gateLike = snapshot;
+    if (gateLike.gateId !== gateId) {
       throw new Error(
-        `loadState: gate ID mismatch \u2014 expected "${gateId}" but snapshot has "${snapshot.gateId}".`
+        `loadState: gate ID mismatch \u2014 expected "${gateId}" but snapshot has "${gateLike.gateId}".`
       );
     }
-    const gateIndex = this.findGateIndex(snapshot);
+    this.ensureDuplicateCheck();
+    const gateIndex = this.findGateIndex(gateLike);
     const gateNode = this.steps[gateIndex];
-    return new ResumedWorkflow(
-      this.steps,
-      gateIndex + 1,
-      gateNode.schema,
-      gateNode.merge,
-      snapshot.output
-    );
+    return new ResumedWorkflow(this.steps, gateIndex + 1, {
+      mode: "gate",
+      schema: gateNode.schema,
+      mergeFn: gateNode.merge,
+      priorOutput: gateLike.output,
+      snapshot: gateLike,
+      observability: this.observability
+    });
+  }
+  // ── Checkpoint resume ──────────────────────────────────────────
+  /**
+   * 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, options) {
+    const isGate = snapshot.version === 2 && snapshot.kind === "gate" || snapshot.version === 1 && snapshot.gateId !== void 0;
+    if (isGate) {
+      throw new Error(`resumeFrom: received a gate snapshot. Use loadState() for gate resume; resumeFrom() is for checkpoints.`);
+    }
+    if (this.steps.length === 0) {
+      throw new Error("resumeFrom: workflow has no steps; snapshot is structurally invalid.");
+    }
+    const ckpt = snapshot;
+    const idx = ckpt.resumeFromIndex;
+    if (!Number.isInteger(idx) || idx < 0 || idx > this.steps.length) {
+      throw new Error(`resumeFrom: resumeFromIndex (${idx}) out of bounds for ${this.steps.length}-step workflow.`);
+    }
+    if (!options?.skipShapeCheck) {
+      if (!ckpt.stepShapeHash) {
+        throw new Error("resumeFrom: snapshot missing stepShapeHash; corrupted or hand-crafted.");
+      }
+      this.ensureDuplicateCheck();
+      if (this.cachedStepShapeHash !== ckpt.stepShapeHash) {
+        throw new Error("resumeFrom: workflow shape mismatch; cannot safely resume. Pass { skipShapeCheck: true } to override.");
+      }
+    } else {
+      this.ensureDuplicateCheck();
+    }
+    return new CheckpointResumedWorkflow(this.steps, idx, {
+      mode: "checkpoint",
+      priorOutput: ckpt.output,
+      snapshot: ckpt,
+      observability: this.observability
+    });
+  }
+  /**
+   * 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, fn) {
+    const node = {
+      type: "finally",
+      id,
+      execute: async (state) => {
+        await fn({ ctx: state.ctx });
+      }
+    };
+    return new _SealedWorkflow([...this.steps, node], this.id, this.observability);
   }
   findGateIndex(snapshot) {
-    if (snapshot.version !== 1) {
+    if (snapshot.version !== 1 && snapshot.version !== 2) {
       throw new Error(`Unsupported snapshot version: ${snapshot.version}`);
     }
     const hint = snapshot.resumeFromIndex;
-    if (hint >= 0 && hint < this.steps.length) {
+    if (Number.isInteger(hint) && hint >= 0 && hint < this.steps.length) {
       const node = this.steps[hint];
       if (node.type === "gate" && node.id === snapshot.gateId) {
         return hint;
@@ -511,12 +1140,12 @@ var ResumedWorkflow = class extends SealedWorkflow {
   mergeFn;
   priorOutput;
   /** @internal */
-  constructor(steps, startIndex, schema, mergeFn, priorOutput) {
-    super(steps);
+  constructor(steps, startIndex, config) {
+    super(steps, void 0, config.observability);
     this.startIndex = startIndex;
-    this.schema = schema;
-    this.mergeFn = mergeFn;
-    this.priorOutput = priorOutput;
+    this.schema = config.schema;
+    this.mergeFn = config.mergeFn;
+    this.priorOutput = config.priorOutput;
   }
   validateResponse(response) {
     if (this.schema) {
@@ -525,15 +1154,31 @@ var ResumedWorkflow = class extends SealedWorkflow {
     return response;
   }
   async generate(ctx, ...args) {
-    const response = this.validateResponse(args[0]);
-    const output = this.mergeFn ? await this.mergeFn({ priorOutput: this.priorOutput, response }) : response;
-    const state = { ctx, output, mode: "generate" };
-    await this.execute(state, this.startIndex);
-    return { output: state.output };
+    const rawResponse = args[0];
+    const opts = args[1];
+    let output = this.priorOutput;
+    let initialError = null;
+    try {
+      const response = this.validateResponse(rawResponse);
+      output = this.mergeFn ? await this.mergeFn({ priorOutput: this.priorOutput, response }) : response;
+    } catch (error) {
+      initialError = { error, stepId: "gate:resume", source: "step" };
+    }
+    const state = {
+      ctx,
+      output,
+      mode: "generate",
+      runOptions: opts,
+      abortSignal: opts?.abortSignal
+    };
+    await this.execute(state, this.startIndex, opts, initialError);
+    return this.buildResult(state);
   }
   stream(ctx, ...args) {
-    const response = this.validateResponse(args[0]);
+    const rawResponse = args[0];
     const options = args[1];
+    const opts = args[2];
+    const abortSignal = opts?.abortSignal;
     let resolveOutput;
     let rejectOutput;
     const outputPromise = new Promise((res, rej) => {
@@ -544,18 +1189,92 @@ var ResumedWorkflow = class extends SealedWorkflow {
     });
     const mergeFn = this.mergeFn;
     const priorOutput = this.priorOutput;
+    const startIndex = this.startIndex;
     const stream = (0, import_ai3.createUIMessageStream)({
       execute: async ({ writer }) => {
-        const output = mergeFn ? await mergeFn({ priorOutput, response }) : response;
+        let output = priorOutput;
+        let initialError = null;
+        try {
+          const response = this.validateResponse(rawResponse);
+          output = mergeFn ? await mergeFn({ priorOutput, response }) : response;
+        } catch (error) {
+          initialError = { error, stepId: "gate:resume", source: "step" };
+        }
         const state = {
           ctx,
           output,
           mode: "stream",
-          writer
+          writer,
+          runOptions: opts,
+          abortSignal
+        };
+        try {
+          await this.execute(state, startIndex, opts, initialError);
+          const result = this.buildResult(state);
+          maybeWarnStreamOnErrorOnSuspend(result, options);
+          resolveOutput(result);
+        } catch (error) {
+          rejectOutput(error);
+          throw error;
+        }
+      },
+      ...options?.onError ? { onError: options.onError } : {},
+      ...options?.onFinish ? { onFinish: options.onFinish } : {}
+    });
+    return { stream, output: outputPromise };
+  }
+};
+var CheckpointResumedWorkflow = class extends SealedWorkflow {
+  startIndex;
+  priorOutput;
+  /** @internal */
+  constructor(steps, startIndex, config) {
+    super(steps, void 0, config.observability);
+    this.startIndex = startIndex;
+    this.priorOutput = config.priorOutput;
+  }
+  // Override with widened arg list compatible with parent's `[input?, opts?]`.
+  // Inputs are ignored — state is seeded from the snapshot's `output` field.
+  async generate(ctx, ...args) {
+    const opts = args[1];
+    this.validateRunOptions(opts);
+    const state = {
+      ctx,
+      output: this.priorOutput,
+      mode: "generate",
+      runOptions: opts
+    };
+    await this.execute(state, this.startIndex, opts);
+    return this.buildResult(state);
+  }
+  stream(ctx, ...args) {
+    const options = args[1];
+    const opts = args[2];
+    this.validateRunOptions(opts);
+    let resolveOutput;
+    let rejectOutput;
+    const outputPromise = new Promise((res, rej) => {
+      resolveOutput = res;
+      rejectOutput = rej;
+    });
+    outputPromise.catch(() => {
+    });
+    const priorOutput = this.priorOutput;
+    const startIndex = this.startIndex;
+    const stream = (0, import_ai3.createUIMessageStream)({
+      execute: async ({ writer }) => {
+        const state = {
+          ctx,
+          output: priorOutput,
+          mode: "stream",
+          writer,
+          runOptions: opts
         };
         try {
-          await this.execute(state, this.startIndex);
-          resolveOutput(state.output);
+          await this.execute(state, startIndex, opts);
+          const result = this.buildResult(state);
+          maybeWarnStreamOnErrorOnSuspend(result, options);
+          resolveOutput(result);
         } catch (error) {
           rejectOutput(error);
           throw error;
@@ -574,15 +1293,21 @@ var Workflow = class _Workflow extends SealedWorkflow {
    * shortening it relative to the input array.
    */
   static SKIP = /* @__PURE__ */ Symbol("pipeai.foreach.skip");
-  constructor(steps = [], id) {
-    super(steps, id);
+  constructor(steps = [], id, observability) {
+    super(steps, id, observability);
   }
   static create(options) {
-    return new _Workflow([], options?.id);
+    return new _Workflow([], options?.id, options?.observability);
   }
   static from(agent, options) {
     return new _Workflow([]).step(agent, options);
   }
+  // Builder helper — append a step and return a re-typed Workflow.
+  // Centralizes the `[...steps, node] as any` + new Workflow + observability/id
+  // forwarding pattern used by every combinator method.
+  appendStep(node) {
+    return new _Workflow([...this.steps, node], this.id, this.observability);
+  }
   // ── step: implementation ──────────────────────────────────────
   step(target, optionsOrFn) {
     if (target instanceof SealedWorkflow) {
@@ -590,11 +1315,15 @@ var Workflow = class _Workflow extends SealedWorkflow {
       const node2 = {
         type: "step",
         id: workflow.id ?? "nested-workflow",
+        nestedWorkflow: workflow,
+        // Feeds the recursive stepShapeHash walk.
+        category: "nested",
+        // Observability event type.
         execute: async (state) => {
           await this.executeNestedWorkflow(state, workflow);
         }
       };
-      return new _Workflow([...this.steps, node2], this.id);
+      return this.appendStep(node2);
     }
     if (typeof target === "string") {
       if (typeof optionsOrFn !== "function") {
@@ -611,19 +1340,19 @@ var Workflow = class _Workflow extends SealedWorkflow {
           });
         }
       };
-      return new _Workflow([...this.steps, node2], this.id);
+      return this.appendStep(node2);
     }
     const agent = target;
     const options = optionsOrFn;
     const node = {
       type: "step",
-      id: agent.id,
+      id: options?.id ?? agent.id,
       execute: async (state) => {
         const ctx = state.ctx;
         await this.executeAgent(state, agent, ctx, options);
       }
     };
-    return new _Workflow([...this.steps, node], this.id);
+    return this.appendStep(node);
   }
   // ── gate: human-in-the-loop suspension point ────────────────
   gate(id, options) {
@@ -649,19 +1378,20 @@ var Workflow = class _Workflow extends SealedWorkflow {
         return state.output;
       }
     };
-    return new _Workflow([...this.steps, node], this.id);
+    return this.appendStep(node);
   }
   // ── branch: implementation ────────────────────────────────────
-  branch(casesOrConfig) {
+  branch(casesOrConfig, options) {
     if (Array.isArray(casesOrConfig)) {
-      return this.branchPredicate(casesOrConfig);
+      return this.branchPredicate(casesOrConfig, options?.id);
     }
-    return this.branchSelect(casesOrConfig);
+    return this.branchSelect(casesOrConfig, options?.id);
   }
-  branchPredicate(cases) {
+  branchPredicate(cases, explicitId) {
     const node = {
       type: "step",
-      id: "branch:predicate",
+      id: explicitId ?? "branch:predicate",
+      category: "branch",
       execute: async (state) => {
         const ctx = state.ctx;
         const input = state.output;
@@ -673,21 +1403,43 @@ var Workflow = class _Workflow extends SealedWorkflow {
           await this.executeAgent(state, branchCase.agent, ctx, branchCase);
           return;
         }
-        throw new WorkflowBranchError("predicate", `No branch matched and no default branch (a case without \`when\`) was provided. Input: ${JSON.stringify(input)}`);
+        let inputRepr;
+        try {
+          inputRepr = JSON.stringify(input);
+          if (inputRepr === void 0) inputRepr = String(input);
+        } catch {
+          inputRepr = `[unserializable ${typeof input}]`;
+        }
+        throw new WorkflowBranchError("predicate", `No branch matched and no default branch (a case without \`when\`) was provided. Input: ${inputRepr}`);
       }
     };
-    return new _Workflow([...this.steps, node], this.id);
+    return this.appendStep(node);
   }
-  branchSelect(config) {
+  branchSelect(config, explicitId) {
     const node = {
       type: "step",
-      id: "branch:select",
+      id: explicitId ?? "branch:select",
+      category: "branch",
       execute: async (state) => {
         const ctx = state.ctx;
         const input = state.output;
         const key = await config.select({ ctx, input });
-        let agent = config.agents[key];
+        const keyDeclared = Object.prototype.hasOwnProperty.call(config.agents, key);
+        if (keyDeclared && config.agents[key] === void 0) {
+          throw new WorkflowBranchError(
+            "select",
+            `Agent for key "${key}" was declared but the value is undefined. This usually means a conditional spread set the value to undefined. Available keys: ${Object.keys(config.agents).join(", ")}`
+          );
+        }
+        let agent = keyDeclared ? config.agents[key] : void 0;
         if (!agent) {
+          if (config.onUnknownKey) {
+            config.onUnknownKey({
+              key,
+              availableKeys: Object.keys(config.agents),
+              ctx
+            });
+          }
           if (config.fallback) {
             agent = config.fallback;
           } else {
@@ -697,32 +1449,37 @@ var Workflow = class _Workflow extends SealedWorkflow {
         await this.executeAgent(state, agent, ctx, config);
       }
     };
-    return new _Workflow([...this.steps, node], this.id);
+    return this.appendStep(node);
   }
   // ── foreach: array iteration ─────────────────────────────────
   /**
    * Map each item of an array through an agent or sub-workflow.
    *
    * @param target Agent or `SealedWorkflow` invoked once per item.
+   * @param options.id Override the default step id (`foreach:<agentId>` or
+   *   the workflow's id). Required when chaining multiple foreach over the same
+   *   target — the construction-time `(type, id)` walk rejects duplicates.
    * @param options.concurrency Max items in flight at any moment (default 1).
    *   Backed by a semaphore: as soon as one item completes, the next launches —
    *   no lockstep batching.
-   * @param options.onError Per-iteration error handler. When provided, a single
-   *   item's failure no longer aborts the foreach. Return a `TNextOutput` value
-   *   to substitute for the failed item, return `Workflow.SKIP` to omit the
-   *   index (shortening the output array), or throw / return a rejected promise
-   *   to abort the foreach step (the thrown error is caught by any downstream
-   *   `.catch()`). When omitted, the existing fail-fast behavior is preserved.
-   *   `onError` is invoked sequentially in index order after all items settle.
+   * @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(target, options) {
     const concurrency = options?.concurrency ?? 1;
     const onError = options?.onError;
     const isWorkflow = target instanceof SealedWorkflow;
-    const id = isWorkflow ? target.id ?? "foreach" : `foreach:${target.id}`;
+    const defaultId = isWorkflow ? target.id ?? "foreach" : `foreach:${target.id}`;
+    const id = options?.id ?? defaultId;
     const node = {
       type: "step",
       id,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      nestedWorkflow: isWorkflow ? target : void 0,
+      category: "foreach",
       execute: async (state) => {
         const items = state.output;
         if (!Array.isArray(items)) {
@@ -731,14 +1488,58 @@ var Workflow = class _Workflow extends SealedWorkflow {
         const ctx = state.ctx;
         const results = new Array(items.length);
         const skipped = /* @__PURE__ */ new Set();
+        const itemStates = new Array(items.length);
         const executeItem = async (item, index) => {
-          const itemState = { ctx: state.ctx, output: item, mode: "generate" };
-          if (isWorkflow) {
-            await this.executeNestedWorkflow(itemState, target);
-          } else {
-            await this.executeAgent(itemState, target, ctx);
+          const itemState = {
+            ctx: state.ctx,
+            output: item,
+            mode: "generate",
+            abortSignal: state.abortSignal
+          };
+          itemStates[index] = itemState;
+          const itemStart = performance.now();
+          await this.fireHook(state, "onItemStart", {
+            stepId: id,
+            type: "foreach",
+            itemIndex: index,
+            ctx: state.ctx,
+            input: item
+          });
+          try {
+            if (isWorkflow) {
+              await this.executeNestedWorkflow(itemState, target);
+            } else {
+              await this.executeAgent(itemState, target, ctx);
+            }
+            results[index] = itemState.output;
+            await this.fireHook(state, "onItemFinish", {
+              stepId: id,
+              type: "foreach",
+              itemIndex: index,
+              ctx: state.ctx,
+              output: itemState.output,
+              durationMs: performance.now() - itemStart
+            });
+          } catch (error) {
+            await this.fireHook(state, "onItemError", {
+              stepId: id,
+              type: "foreach",
+              itemIndex: index,
+              ctx: state.ctx,
+              error,
+              durationMs: performance.now() - itemStart
+            });
+            throw error;
+          }
+        };
+        const mergeItemWarnings = () => {
+          for (let idx = 0; idx < items.length; idx++) {
+            const its = itemStates[idx];
+            if (!its?.warnings) continue;
+            for (const w of its.warnings) {
+              pushWarning(state, w.source, `${id}[${idx}]:${w.stepId}`, w.error);
+            }
           }
-          results[index] = itemState.output;
         };
         const handleRejection = async (error, item, index) => {
           if (!onError) throw error;
@@ -754,49 +1555,244 @@ var Workflow = class _Workflow extends SealedWorkflow {
             results[index] = recovered;
           }
         };
+        const failures = [];
+        const signal = state.abortSignal;
         if (concurrency <= 1) {
           for (let i = 0; i < items.length; i++) {
+            if (signal?.aborted) {
+              failures.push({ index: i, error: signal.reason ?? new Error("Workflow aborted") });
+              continue;
+            }
             try {
               await executeItem(items[i], i);
             } catch (error) {
-              await handleRejection(error, items[i], i);
+              failures.push({ index: i, error });
             }
           }
         } else {
-          const sem = new Semaphore(concurrency);
-          const failures = [];
-          await Promise.all(items.map(async (item, i) => {
-            await sem.acquire();
+          let nextIndex = 0;
+          const worker = async () => {
+            while (true) {
+              const i = nextIndex++;
+              if (i >= items.length) return;
+              if (signal?.aborted) {
+                failures.push({ index: i, error: signal.reason ?? new Error("Workflow aborted") });
+                continue;
+              }
+              try {
+                await executeItem(items[i], i);
+              } catch (error) {
+                failures.push({ index: i, error });
+              }
+            }
+          };
+          const workers = Array.from(
+            { length: Math.min(concurrency, items.length) },
+            () => worker()
+          );
+          await Promise.all(workers);
+        }
+        failures.sort((a, b) => a.index - b.index);
+        const gateFailures = [];
+        const nonGateFailures = [];
+        for (const f of failures) {
+          if (f.error instanceof NestedGateUnsupportedError) {
+            gateFailures.push({ index: f.index, error: f.error });
+          } else {
+            nonGateFailures.push(f);
+          }
+        }
+        mergeItemWarnings();
+        if (gateFailures.length > 0) {
+          for (const nr of nonGateFailures) {
+            pushWarning(state, "foreach-sibling", `${id}[${nr.index}]`, nr.error);
+          }
+          const lowest = gateFailures[0];
+          const otherSuspensions = gateFailures.slice(1).map((g) => ({
+            index: g.index,
+            gateId: g.error.gateId
+          }));
+          const siblingErrors = nonGateFailures.map((nr) => nr.error);
+          throw new NestedGateUnsupportedError(
+            lowest.error.gateId,
+            lowest.error.workflowId,
+            siblingErrors,
+            otherSuspensions
+          );
+        }
+        for (const { index, error } of nonGateFailures) {
+          await handleRejection(error, items[index], index);
+        }
+        state.output = skipped.size === 0 ? results : results.filter((_, i) => !skipped.has(i));
+      }
+    };
+    return this.appendStep(node);
+  }
+  // Implementation
+  parallel(branches, options) {
+    const isTuple = Array.isArray(branches);
+    const entries = isTuple ? branches.map((target, i) => ({ key: i, index: i, target })) : Object.entries(branches).map(([k, t], i) => ({ key: k, index: i, target: t }));
+    const branchCount = entries.length;
+    const requestedConcurrency = options?.concurrency;
+    let effectiveConcurrency;
+    if (requestedConcurrency === void 0) {
+      effectiveConcurrency = Math.min(branchCount, 5);
+    } else {
+      effectiveConcurrency = requestedConcurrency;
+    }
+    if (requestedConcurrency === void 0 && branchCount > 5) {
+      warnOnce(
+        "pipeai:parallel-cap",
+        `pipeai: parallel() with ${branchCount} branches capped at concurrency 5 by default. Pass { concurrency: ${branchCount} } (or Infinity) to opt in, or set { concurrency: N } if you want fewer.`
+      );
+    }
+    const onError = options?.onError;
+    const id = options?.id ?? (isTuple ? "parallel:tuple" : "parallel:record");
+    const node = {
+      type: "step",
+      id,
+      category: "parallel",
+      execute: async (state) => {
+        const ctx = state.ctx;
+        const input = state.output;
+        const results = isTuple ? new Array(branchCount) : {};
+        const branchStates = new Array(branchCount);
+        const executeBranch = async ({ key, index, target }) => {
+          const branchState = { ctx: state.ctx, output: input, mode: "generate" };
+          branchStates[index] = branchState;
+          const branchStart = performance.now();
+          const itemIndex = isTuple ? index : key;
+          await this.fireHook(state, "onItemStart", {
+            stepId: id,
+            type: "parallel",
+            itemIndex,
+            ctx: state.ctx,
+            input
+          });
+          try {
+            if (target instanceof SealedWorkflow) {
+              await this.executeNestedWorkflow(branchState, target);
+            } else {
+              await this.executeAgent(branchState, target, ctx);
+            }
+            results[key] = branchState.output;
+            await this.fireHook(state, "onItemFinish", {
+              stepId: id,
+              type: "parallel",
+              itemIndex,
+              ctx: state.ctx,
+              output: branchState.output,
+              durationMs: performance.now() - branchStart
+            });
+          } catch (error) {
+            await this.fireHook(state, "onItemError", {
+              stepId: id,
+              type: "parallel",
+              itemIndex,
+              ctx: state.ctx,
+              error,
+              durationMs: performance.now() - branchStart
+            });
+            throw error;
+          }
+        };
+        const failures = [];
+        const eff = Number.isFinite(effectiveConcurrency) ? Math.max(1, effectiveConcurrency) : branchCount;
+        if (eff <= 1) {
+          for (const e of entries) {
             try {
-              await executeItem(item, i);
+              await executeBranch(e);
             } catch (error) {
-              failures.push({ index: i, error });
-            } finally {
-              sem.release();
+              failures.push({ key: e.key, index: e.index, error });
             }
-          }));
-          failures.sort((a, b) => a.index - b.index);
-          for (const { index, error } of failures) {
-            await handleRejection(error, items[index], index);
           }
+        } else {
+          let nextIndex = 0;
+          const worker = async () => {
+            while (true) {
+              const i = nextIndex++;
+              if (i >= branchCount) return;
+              const e = entries[i];
+              try {
+                await executeBranch(e);
+              } catch (error) {
+                failures.push({ key: e.key, index: e.index, error });
+              }
+            }
+          };
+          const workers = Array.from(
+            { length: Math.min(eff, branchCount) },
+            () => worker()
+          );
+          await Promise.all(workers);
         }
-        state.output = skipped.size === 0 ? results : results.filter((_, i) => !skipped.has(i));
+        for (let idx = 0; idx < branchCount; idx++) {
+          const bs = branchStates[idx];
+          if (!bs?.warnings) continue;
+          for (const w of bs.warnings) {
+            pushWarning(state, w.source, `${id}[${entries[idx].key}]:${w.stepId}`, w.error);
+          }
+        }
+        const gateFailures = [];
+        const nonGateFailures = [];
+        for (const f of failures) {
+          if (f.error instanceof NestedGateUnsupportedError) gateFailures.push({ key: f.key, index: f.index, error: f.error });
+          else nonGateFailures.push(f);
+        }
+        gateFailures.sort((a, b) => a.index - b.index);
+        nonGateFailures.sort((a, b) => a.index - b.index);
+        if (gateFailures.length > 0) {
+          for (const nr of nonGateFailures) {
+            pushWarning(state, "foreach-sibling", `${id}[${nr.key}]`, nr.error);
+          }
+          const lowest = gateFailures[0];
+          const otherSuspensions = gateFailures.slice(1).map((g) => ({ index: g.index, gateId: g.error.gateId }));
+          const siblingErrors = nonGateFailures.map((nr) => nr.error);
+          throw new NestedGateUnsupportedError(
+            lowest.error.gateId,
+            lowest.error.workflowId,
+            siblingErrors,
+            otherSuspensions
+          );
+        }
+        for (const { key, index, error } of nonGateFailures) {
+          if (!onError) throw error;
+          const recovered = await onError({
+            error,
+            key: isTuple ? void 0 : key,
+            index: isTuple ? index : void 0,
+            ctx: state.ctx
+          });
+          if (recovered === _Workflow.SKIP) {
+            results[key] = void 0;
+          } else {
+            results[key] = recovered;
+          }
+        }
+        state.output = results;
       }
     };
-    return new _Workflow([...this.steps, node], this.id);
+    return this.appendStep(node);
   }
   // ── repeat: conditional loop ─────────────────────────────────
   repeat(target, options) {
     const maxIterations = options.maxIterations ?? 10;
     const isWorkflow = target instanceof SealedWorkflow;
-    const id = isWorkflow ? target.id ?? "repeat" : `repeat:${target.id}`;
+    const defaultId = isWorkflow ? target.id ?? "repeat" : `repeat:${target.id}`;
+    const id = options.id ?? defaultId;
     const predicate = options.until ?? (async (p) => !await options.while(p));
     const node = {
       type: "step",
       id,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      nestedWorkflow: isWorkflow ? target : void 0,
+      category: "repeat",
       execute: async (state) => {
         const ctx = state.ctx;
         for (let i = 1; i <= maxIterations; i++) {
+          if (state.abortSignal?.aborted) {
+            throw state.abortSignal.reason ?? new Error("Workflow aborted");
+          }
           if (isWorkflow) {
             await this.executeNestedWorkflow(state, target);
           } else {
@@ -812,7 +1808,7 @@ var Workflow = class _Workflow extends SealedWorkflow {
         throw new WorkflowLoopError(maxIterations, maxIterations);
       }
     };
-    return new _Workflow([...this.steps, node], this.id);
+    return this.appendStep(node);
   }
   // ── catch ─────────────────────────────────────────────────────
   catch(id, fn) {
@@ -824,27 +1820,29 @@ var Workflow = class _Workflow extends SealedWorkflow {
       id,
       catchFn: fn
     };
-    return new _Workflow([...this.steps, node], this.id);
-  }
-  // ── finally (terminal — returns sealed workflow) ──────────────
-  finally(id, fn) {
-    const node = {
-      type: "finally",
-      id,
-      execute: async (state) => {
-        await fn({ ctx: state.ctx });
-      }
-    };
-    return new SealedWorkflow([...this.steps, node], this.id);
+    return this.appendStep(node);
   }
+  // `.finally()` is inherited from SealedWorkflow now (it lives there so
+  // multi-finally chains are possible — `.finally().finally()`).
 };
+
+// src/index.ts
+var SKIP = Workflow.SKIP;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Agent,
+  CHECKPOINT_STEP_ID,
+  CheckpointTimeoutError,
+  NestedGateUnsupportedError,
+  SKIP,
+  TOOL_PROVIDER_BRAND,
+  ToolProvider,
   Workflow,
   WorkflowBranchError,
   WorkflowLoopError,
-  WorkflowSuspended,
-  defineTool
+  defineTool,
+  getActiveWriter,
+  isToolProvider,
+  migrateSnapshot
 });
 //# sourceMappingURL=index.cjs.map