@anvia/core 0.26.0 → 1.0.0-rc.10

package/dist/pipeline/index.js

@@ -1,387 +1,572 @@
+import {
+  AgentRunBlockedError
+} from "../chunk-X4LK4ODN.js";
 import {
   mapWithConcurrency
-} from "../chunk-OIMLU4SF.js";
+} from "../chunk-3RM57ZT2.js";
+import {
+  extract
+} from "../chunk-LTXABCOO.js";
+import "../chunk-D4PACGPA.js";
+import "../chunk-7PHMK7W4.js";
+import "../chunk-7JLAIN6E.js";
+import "../chunk-QGX73TSQ.js";
+import "../chunk-3XQGVDU5.js";
+import {
+  abortError,
+  throwIfAborted
+} from "../chunk-3RWESPUG.js";
+
+// src/pipeline/errors.ts
+var PipelineAgentSuspensionError = class extends Error {
+  constructor(result) {
+    super("Pipeline agent stage suspended for human interaction.");
+    this.result = result;
+    this.name = "PipelineAgentSuspensionError";
+  }
+  result;
+};
 
-// src/pipeline/builder.ts
+// src/pipeline/pipeline.ts
 import { z } from "zod";
 
 // src/pipeline/graph.ts
-function initialBuilderState(metadata) {
-  return {
-    graph: initialGraph(metadata),
-    terminalNodeId: "input",
-    terminalNodeIds: ["input"],
-    nextNodeIndex: 1,
-    nextEdgeIndex: 1
-  };
-}
-function initialGraph(metadata) {
-  const id = normalizeId(metadata.id ?? "pipeline");
+var INPUT_ID = "$input";
+var OUTPUT_ID = "$output";
+var RESERVED_STAGE_IDS = /* @__PURE__ */ new Set([INPUT_ID, OUTPUT_ID]);
+function initialPipelineState(options) {
+  const input = graphNode(INPUT_ID, [INPUT_ID], "input", "Input");
   const graph = {
-    id,
-    nodes: [{ id: "input", kind: "input", label: "Input" }],
+    id: options.id,
+    nodes: [input],
     edges: []
   };
-  if (metadata.name !== void 0) {
-    graph.name = metadata.name;
-  }
-  if (metadata.description !== void 0) {
-    graph.description = metadata.description;
-  }
-  if (metadata.metadata !== void 0) {
-    graph.metadata = metadata.metadata;
-  }
-  return graph;
-}
-function appendNode(state, kind, label, options = {}) {
-  const node = graphNode(kind, label, state.nextNodeIndex, {
-    ...options,
-    existingIds: new Set(state.graph.nodes.map((item) => item.id))
-  });
+  if (options.name !== void 0) graph.name = options.name;
+  if (options.description !== void 0) graph.description = options.description;
+  if (options.metadata !== void 0) graph.metadata = options.metadata;
   return {
-    node,
-    state: appendGraphNode(state, node, activeTerminalNodeIds(state), [node.id])
+    graph,
+    terminalPaths: [input.path],
+    stageIds: /* @__PURE__ */ new Set(),
+    nextEdgeIndex: 1
   };
 }
-function appendChildNode(state, parentId, kind, label, options = {}) {
-  const node = graphNode(kind, label, state.nextNodeIndex, {
-    ...options,
-    existingIds: new Set(state.graph.nodes.map((item) => item.id))
+function appendStageNode(state, kind, stage, options = {}) {
+  const id = validateStageId(stage.id);
+  if (state.stageIds.has(id)) {
+    throw new TypeError(`Pipeline stage id "${id}" is already registered.`);
+  }
+  const node = graphNode(id, [id], kind, stage.name ?? options.defaultLabel ?? id, {
+    description: stage.description,
+    metadata: stage.metadata,
+    agentId: options.agentId,
+    agentName: options.agentName,
+    pipelineId: options.pipelineId
   });
   return {
     node,
-    state: appendGraphNode(state, node, [parentId], activeTerminalNodeIds(state))
+    state: appendNode(state, node, state.terminalPaths, [node.path], id)
   };
 }
-function activeTerminalNodeIds(state) {
-  return state.terminalNodeIds.length > 0 ? state.terminalNodeIds : [state.terminalNodeId];
+function appendComposedGraph(state, boundary, child) {
+  return appendChildGraph(state, boundary.path, child);
 }
-function withTerminalNodes(state, terminalNodeIds) {
-  return {
-    ...state,
-    terminalNodeId: terminalNodeIds.at(-1) ?? state.terminalNodeId,
-    terminalNodeIds
-  };
+function appendParallelBranch(state, parallel, branchKey, child) {
+  const id = validateStageId(branchKey);
+  const path = [...parallel.path, id];
+  const node = graphNode(id, path, "branch", id, { branchKey: id, pipelineId: child.id });
+  const withBranch = appendNode(state, node, [parallel.path], state.terminalPaths);
+  const withChild = appendChildGraph(withBranch, node.path, child);
+  return { state: withChild, node, terminalPaths: withChild.terminalPaths };
+}
+function withTerminalPaths(state, terminalPaths) {
+  return { ...state, terminalPaths };
 }
 function withOutputNode(state) {
   const graph = cloneGraph(state.graph);
-  if (graph.nodes.some((node) => node.id === "output")) {
+  const outputPath = [OUTPUT_ID];
+  if (graph.nodes.some((node) => pathEquals(node.path, outputPath))) {
     return graph;
   }
-  graph.nodes.push({ id: "output", kind: "output", label: "Output" });
+  graph.nodes.push(graphNode(OUTPUT_ID, outputPath, "output", "Output"));
   graph.edges.push(
-    ...activeTerminalNodeIds(state).map((sourceId, index) => ({
+    ...state.terminalPaths.map((source, index) => ({
       id: `edge_${state.nextEdgeIndex + index}`,
-      source: sourceId,
-      target: "output"
+      source: [...source],
+      target: outputPath
     }))
   );
   return graph;
 }
-function nextStageLabel(state, prefix) {
-  return `${prefix} ${state.nextNodeIndex}`;
-}
 function cloneGraph(graph) {
   return {
     ...graph,
-    nodes: graph.nodes.map((node) => ({ ...node })),
-    edges: graph.edges.map((edge) => ({ ...edge }))
+    nodes: graph.nodes.map((node) => ({ ...node, path: [...node.path] })),
+    edges: graph.edges.map((edge) => ({
+      ...edge,
+      source: [...edge.source],
+      target: [...edge.target]
+    }))
   };
 }
-function appendGraphNode(state, node, sourceIds, terminalNodeIds) {
-  const edges = sourceIds.map((sourceId, index) => ({
+function scopedNode(node, path) {
+  return { ...node, path: [...path] };
+}
+function appendChildGraph(state, parentPath, child) {
+  const childNodes = child.nodes.filter((node) => !isBoundaryPath(node.path)).map((node) => scopedNode(node, [...parentPath, ...node.path]));
+  const childEdges = [];
+  const terminalPaths = [];
+  let nextEdgeIndex = state.nextEdgeIndex;
+  for (const edge of child.edges) {
+    const sourceIsInput = isInputPath(edge.source);
+    const targetIsOutput = isOutputPath(edge.target);
+    const source = sourceIsInput ? [...parentPath] : [...parentPath, ...edge.source];
+    if (targetIsOutput) {
+      terminalPaths.push(source);
+      continue;
+    }
+    const target = [...parentPath, ...edge.target];
+    let childEdge = {
+      id: `edge_${nextEdgeIndex}`,
+      source,
+      target
+    };
+    if (edge.label !== void 0) childEdge = { ...childEdge, label: edge.label };
+    childEdges.push(childEdge);
+    nextEdgeIndex += 1;
+  }
+  return {
+    ...state,
+    graph: {
+      ...state.graph,
+      nodes: [...state.graph.nodes, ...childNodes],
+      edges: [...state.graph.edges, ...childEdges]
+    },
+    terminalPaths: terminalPaths.length === 0 ? [[...parentPath]] : terminalPaths,
+    nextEdgeIndex
+  };
+}
+function appendNode(state, node, sourcePaths, terminalPaths, stageId) {
+  const edges = sourcePaths.map((source, index) => ({
     id: `edge_${state.nextEdgeIndex + index}`,
-    source: sourceId,
-    target: node.id
+    source: [...source],
+    target: [...node.path]
   }));
-  const terminalNodeId = terminalNodeIds.at(-1) ?? state.terminalNodeId;
+  const stageIds = new Set(state.stageIds);
+  if (stageId !== void 0) stageIds.add(stageId);
   return {
     graph: {
       ...state.graph,
       nodes: [...state.graph.nodes, node],
       edges: [...state.graph.edges, ...edges]
     },
-    terminalNodeId,
-    terminalNodeIds,
-    nextNodeIndex: state.nextNodeIndex + 1,
+    terminalPaths,
+    stageIds,
     nextEdgeIndex: state.nextEdgeIndex + edges.length
   };
 }
-function graphNode(kind, label, index, options = {}) {
-  const id = uniqueGraphNodeId(
-    normalizeId(options.preferredId ?? `${kind}_${index}`),
-    options.existingIds ?? /* @__PURE__ */ new Set()
-  );
-  const node = {
-    id,
-    kind,
-    label
-  };
-  if (options.description !== void 0) {
-    node.description = options.description;
-  }
-  if (options.metadata !== void 0) {
-    node.metadata = options.metadata;
-  }
-  if (options.agentId !== void 0) {
-    node.agentId = options.agentId;
-  }
-  if (options.agentName !== void 0) {
-    node.agentName = options.agentName;
+function graphNode(id, path, kind, label, options = {}) {
+  const node = { id, path: [...path], kind, label };
+  if (options.description !== void 0) node.description = options.description;
+  if (options.metadata !== void 0) node.metadata = options.metadata;
+  if (options.agentId !== void 0) node.agentId = options.agentId;
+  if (options.agentName !== void 0) node.agentName = options.agentName;
+  if (options.pipelineId !== void 0) node.pipelineId = options.pipelineId;
+  if (options.branchKey !== void 0) node.branchKey = options.branchKey;
+  return node;
+}
+function validateStageId(value) {
+  if (typeof value !== "string") {
+    throw new TypeError("Pipeline stage id must be a string.");
   }
-  if (options.pipelineId !== void 0) {
-    node.pipelineId = options.pipelineId;
+  const id = value.trim();
+  if (id.length === 0) {
+    throw new TypeError("Pipeline stage id must be a non-empty string.");
   }
-  if (options.branchKey !== void 0) {
-    node.branchKey = options.branchKey;
+  if (RESERVED_STAGE_IDS.has(id)) {
+    throw new TypeError(`Pipeline stage id "${id}" is reserved.`);
   }
-  return node;
+  return id;
 }
-function normalizeId(value) {
-  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
-  return normalized.length === 0 ? "pipeline" : normalized;
+function isBoundaryPath(path) {
+  return isInputPath(path) || isOutputPath(path);
 }
-function uniqueGraphNodeId(baseId, existingIds) {
-  let id = baseId;
-  let suffix = 2;
-  while (existingIds.has(id)) {
-    id = `${baseId}_${suffix}`;
-    suffix += 1;
-  }
-  return id;
+function isInputPath(path) {
+  return path.length === 1 && path[0] === INPUT_ID;
+}
+function isOutputPath(path) {
+  return path.length === 1 && path[0] === OUTPUT_ID;
+}
+function pathEquals(left, right) {
+  return left.length === right.length && left.every((segment, index) => segment === right[index]);
 }
-
-// src/pipeline/pipeline.ts
-var Pipeline = class {
-  constructor(executor, pipelineGraph = initialGraph({})) {
-    this.executor = executor;
-    this.pipelineGraph = pipelineGraph;
-    this.id = pipelineGraph.id;
-    this.name = pipelineGraph.name;
-    this.description = pipelineGraph.description;
-    this.metadata = pipelineGraph.metadata;
-  }
-  executor;
-  pipelineGraph;
-  id;
-  name;
-  description;
-  metadata;
-  /** Run one input through the built pipeline and return the final stage output. */
-  async run(input, options = {}) {
-    return await this.executor(input, { observer: options.observer });
-  }
-  /** Run many inputs through the same pipeline with bounded concurrency. */
-  async batch(inputs, options) {
-    return mapWithConcurrency([...inputs], options.concurrency, (input) => this.run(input));
-  }
-  graph() {
-    return cloneGraph(this.pipelineGraph);
-  }
-};
 
 // src/pipeline/runtime.ts
-async function runNode(context, node, fn) {
+async function runNode(context, node, path, fn) {
+  throwIfAborted(context.abortSignal);
+  const eventNode = scopedNode(node, path);
   const startedAt = Date.now();
-  await context.observer?.onEvent({ type: "stage_started", node });
+  await emitEvent(context, {
+    type: "stage_started",
+    runId: context.runId,
+    pipelineId: context.pipelineId,
+    path: [...path],
+    node: eventNode
+  });
   try {
     const output = await fn();
-    await context.observer?.onEvent({
+    throwIfAborted(context.abortSignal);
+    await emitEvent(context, {
       type: "stage_completed",
-      node,
+      runId: context.runId,
+      pipelineId: context.pipelineId,
+      path: [...path],
+      node: eventNode,
       durationMs: Date.now() - startedAt
     });
     return output;
   } catch (error) {
-    await context.observer?.onEvent({
+    const failureEvent = {
       type: "stage_failed",
-      node,
+      runId: context.runId,
+      pipelineId: context.pipelineId,
+      path: [...path],
+      node: eventNode,
       durationMs: Date.now() - startedAt,
       error
-    });
+    };
+    try {
+      await emitEvent(context, failureEvent);
+    } catch (observerError) {
+      throw new AggregateError(
+        [error, observerError],
+        `Pipeline stage "${node.id}" and its observer both failed.`
+      );
+    }
     throw error;
   }
 }
+function stageContext(input, context) {
+  return {
+    input,
+    runId: context.runId,
+    pipelineId: context.pipelineId,
+    runMetadata: context.runMetadata,
+    abortSignal: context.abortSignal
+  };
+}
+function childContext(context, abortSignal) {
+  return { ...context, abortSignal };
+}
+function combineAbortSignals(parent, local) {
+  const controller = new AbortController();
+  const abortFromParent = () => controller.abort(parent?.reason);
+  const abortFromLocal = () => controller.abort(local.reason);
+  if (parent?.aborted === true) {
+    controller.abort(parent.reason);
+  } else if (local.aborted) {
+    controller.abort(local.reason);
+  } else {
+    parent?.addEventListener("abort", abortFromParent, { once: true });
+    local.addEventListener("abort", abortFromLocal, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    dispose() {
+      parent?.removeEventListener("abort", abortFromParent);
+      local.removeEventListener("abort", abortFromLocal);
+    }
+  };
+}
+function pipelineAbortError(signal) {
+  return abortError(signal?.reason);
+}
+async function emitEvent(context, event) {
+  if (context.observer === void 0) return;
+  try {
+    await context.observer.onEvent(event);
+  } catch (error) {
+    if (context.failOnObserverError) throw error;
+  }
+}
 
-// src/pipeline/builder.ts
-var PipelineBuilder = class _PipelineBuilder {
+// src/pipeline/pipeline.ts
+var internalPipelineOptions = /* @__PURE__ */ Symbol("internal-pipeline-options");
+var Pipeline = class {
+  id;
+  name;
+  description;
+  metadata;
   executor;
   state;
-  constructor(metadataOrExecutor, stateOrMetadata) {
-    if (stateOrMetadata !== void 0 && isBuilderState(stateOrMetadata)) {
-      this.executor = metadataOrExecutor;
-      this.state = stateOrMetadata;
-      return;
-    }
-    if (typeof metadataOrExecutor === "function") {
-      const executor = metadataOrExecutor;
-      this.executor = ((input) => executor(input));
-      this.state = initialBuilderState({});
-      return;
-    }
-    if (isZodSchema(metadataOrExecutor)) {
-      const schema = metadataOrExecutor;
-      const metadata = stateOrMetadata !== void 0 && isPipelineMetadata(stateOrMetadata) ? stateOrMetadata : {};
-      this.executor = ((input) => schema.parse(input));
-      this.state = initialBuilderState(metadata);
-      return;
+  constructor(options) {
+    if (isInternalPipelineOptions(options)) {
+      this.executor = options[internalPipelineOptions].executor;
+      this.state = options[internalPipelineOptions].state;
+    } else {
+      const id = normalizePipelineId(options.id);
+      if (!isZodSchema(options.inputSchema)) {
+        throw new TypeError("Pipeline inputSchema must be a Zod schema.");
+      }
+      const inputSchema = options.inputSchema;
+      this.executor = (async (input, context) => {
+        throwIfAborted(context.abortSignal);
+        return inputSchema.parseAsync(input);
+      });
+      this.state = initialPipelineState({
+        id,
+        name: options.name,
+        description: options.description,
+        metadata: options.metadata
+      });
     }
-    this.executor = identity;
-    this.state = initialBuilderState(metadataOrExecutor ?? {});
+    const graph = this.state.graph;
+    this.id = graph.id;
+    this.name = graph.name;
+    this.description = graph.description;
+    this.metadata = graph.metadata;
   }
-  /** Add a synchronous or asynchronous transform stage. */
-  step(fn, metadata) {
-    const next = appendNode(
-      this.state,
-      "step",
-      metadata?.name ?? nextStageLabel(this.state, "Step"),
-      {
-        description: metadata?.description,
-        metadata: metadata?.metadata,
-        preferredId: metadata?.id
-      }
-    );
-    return new _PipelineBuilder(
-      async (input, context) => {
-        const value = await this.runStep(input, context);
-        const result = await runNode(context, next.node, () => fn(value));
-        return result;
-      },
-      next.state
-    );
+  step(options) {
+    const next = appendStageNode(this.state, "step", options);
+    const executor = (async (input, context, pathPrefix) => {
+      const value = await this.execute(input, context, pathPrefix);
+      const path = [...pathPrefix, next.node.id];
+      return await runNode(
+        context,
+        next.node,
+        path,
+        () => options.run(stageContext(value, context))
+      );
+    });
+    return this.derive(executor, next.state);
   }
-  /** Compose another pipeline operation after the current stage. */
-  use(op, metadata) {
-    const nested = op instanceof Pipeline ? op : void 0;
-    const next = appendNode(
-      this.state,
-      nested === void 0 ? "step" : "pipeline",
-      metadata?.name ?? nested?.name ?? nested?.id ?? nextStageLabel(this.state, nested === void 0 ? "Operation" : "Pipeline"),
-      {
-        description: metadata?.description ?? nested?.description,
-        metadata: metadata?.metadata ?? nested?.metadata,
-        preferredId: metadata?.id,
-        pipelineId: nested?.id
-      }
-    );
-    return new _PipelineBuilder(
-      async (input, context) => {
-        const value = await this.runStep(input, context);
-        const result = await runNode(context, next.node, () => op.run(value));
-        return result;
-      },
-      next.state
-    );
+  compose(options) {
+    const boundary = appendStageNode(this.state, "pipeline", options, {
+      defaultLabel: options.pipeline.name ?? options.pipeline.id,
+      pipelineId: options.pipeline.id
+    });
+    const state = appendComposedGraph(boundary.state, boundary.node, options.pipeline.graph());
+    const executor = (async (input, context, pathPrefix) => {
+      const value = await this.execute(input, context, pathPrefix);
+      const path = [...pathPrefix, boundary.node.id];
+      return await runNode(
+        context,
+        boundary.node,
+        path,
+        () => options.pipeline.execute(value, context, path)
+      );
+    });
+    return this.derive(executor, state);
   }
-  /** Run named branch operations concurrently from the current value. */
-  parallel(branches, metadata) {
-    const parallel = appendNode(
-      this.state,
-      "parallel",
-      metadata?.name ?? `${Object.keys(branches).length} parallel branches`,
-      {
-        description: metadata?.description,
-        metadata: metadata?.metadata,
-        preferredId: metadata?.id
-      }
-    );
+  parallel(options) {
+    const branchEntries = normalizeParallelBranches(options.branches);
+    if (branchEntries.length === 0) {
+      throw new TypeError("Pipeline parallel branches must not be empty.");
+    }
+    const parallel = appendStageNode(this.state, "parallel", options, {
+      defaultLabel: `${branchEntries.length} parallel branches`
+    });
     let nextState = parallel.state;
-    const branchNodes = {};
-    for (const key of Object.keys(branches)) {
-      const branch = appendChildNode(nextState, parallel.node.id, "branch", key, {
-        branchKey: key
-      });
-      nextState = branch.state;
-      branchNodes[key] = branch.node;
+    const branchNodes = /* @__PURE__ */ new Map();
+    const terminalPaths = [];
+    for (const [key, branch] of branchEntries) {
+      const appended = appendParallelBranch(nextState, parallel.node, key, branch.graph());
+      nextState = appended.state;
+      branchNodes.set(key, appended.node);
+      terminalPaths.push(...appended.terminalPaths);
     }
-    nextState = withTerminalNodes(
-      nextState,
-      Object.values(branchNodes).map((node) => node.id)
-    );
-    return new _PipelineBuilder(async (input, context) => {
-      const value = await this.runStep(input, context);
-      const entries = await runNode(
-        context,
-        parallel.node,
-        () => Promise.all(
-          Object.entries(branches).map(async ([key, op]) => {
-            const node = branchNodes[key];
-            const output = await runNode(context, node, () => op.run(value));
+    nextState = withTerminalPaths(nextState, terminalPaths);
+    return this.derive(async (input, context, pathPrefix) => {
+      const value = await this.execute(input, context, pathPrefix);
+      const parallelPath = [...pathPrefix, parallel.node.id];
+      return runNode(context, parallel.node, parallelPath, async () => {
+        const controller = new AbortController();
+        const combined = combineAbortSignals(context.abortSignal, controller.signal);
+        const branchContext = childContext(context, combined.signal);
+        let firstError;
+        const promises = branchEntries.map(async ([key, branch]) => {
+          const node = branchNodes.get(key);
+          const path = [...parallelPath, node.id];
+          try {
+            const output = await runNode(
+              branchContext,
+              node,
+              path,
+              () => branch.execute(value, branchContext, path)
+            );
             return [key, output];
-          })
-        )
-      );
-      return Object.fromEntries(entries);
+          } catch (error) {
+            if (firstError === void 0) firstError = error;
+            if (!controller.signal.aborted) controller.abort(error);
+            throw error;
+          }
+        });
+        const settled = await Promise.allSettled(promises);
+        combined.dispose();
+        if (context.abortSignal?.aborted === true) {
+          throw pipelineAbortError(context.abortSignal);
+        }
+        if (firstError !== void 0) throw firstError;
+        return Object.fromEntries(
+          settled.map(
+            (result) => result.value
+          )
+        );
+      });
     }, nextState);
   }
-  /** Send the current value to an agent as text and continue with the agent output. */
-  prompt(agent, metadata) {
-    const next = appendNode(this.state, "agent", metadata?.name ?? agent.name ?? agent.id, {
-      description: metadata?.description ?? agent.description,
-      metadata: metadata?.metadata,
-      preferredId: metadata?.id,
-      agentId: agent.id,
-      agentName: agent.name
+  agent(options) {
+    if (options.suspension !== "reject") {
+      throw new TypeError('Pipeline Agent stages require suspension: "reject".');
+    }
+    const next = appendStageNode(this.state, "agent", options, {
+      defaultLabel: options.agent.name ?? options.agent.id,
+      agentId: options.agent.id,
+      agentName: options.agent.name
     });
-    return new _PipelineBuilder(async (input, context) => {
-      const value = await this.runStep(input, context);
-      return runNode(context, next.node, async () => {
-        const response = await agent.prompt(String(value)).send();
+    return this.derive(async (input, context, pathPrefix) => {
+      const value = await this.execute(input, context, pathPrefix);
+      const path = [...pathPrefix, next.node.id];
+      return runNode(context, next.node, path, async () => {
+        const request = await options.request(stageContext(value, context));
+        const response = await options.agent.generate({
+          ...request,
+          abortSignal: context.abortSignal
+        });
+        if (response.status === "suspended") {
+          throw new PipelineAgentSuspensionError(response);
+        }
+        if (response.status === "blocked") {
+          throw new AgentRunBlockedError(response);
+        }
         return response.output;
       });
     }, next.state);
   }
-  /** Send the current value to an extractor as text and continue with typed schema data. */
-  extract(extractor, metadata) {
-    const next = appendNode(
-      this.state,
-      "extractor",
-      metadata?.name ?? nextStageLabel(this.state, "Extractor"),
-      {
-        description: metadata?.description,
-        metadata: metadata?.metadata,
-        preferredId: metadata?.id
-      }
-    );
-    return new _PipelineBuilder(async (input, context) => {
-      const value = await this.runStep(input, context);
-      return runNode(context, next.node, () => extractor.extract(String(value)));
+  extract(options) {
+    const next = appendStageNode(this.state, "extractor", options);
+    return this.derive(async (input, context, pathPrefix) => {
+      const value = await this.execute(input, context, pathPrefix);
+      const path = [...pathPrefix, next.node.id];
+      return runNode(context, next.node, path, async () => {
+        const text = await options.text(stageContext(value, context));
+        const result = await extract({
+          model: options.model,
+          text,
+          outputSchema: options.outputSchema,
+          instructions: options.instructions,
+          retries: options.retries,
+          temperature: options.temperature,
+          maxTokens: options.maxTokens,
+          providerOptions: options.providerOptions,
+          abortSignal: context.abortSignal
+        });
+        return result.output;
+      });
     }, next.state);
   }
-  /** Finish the builder and return a runnable pipeline. */
-  build() {
-    const graph = withOutputNode(this.state);
-    return new Pipeline(
-      (input, context) => this.runStep(input, context),
-      graph
-    );
+  async run(options) {
+    const runId = normalizeRunId(options.runId ?? globalThis.crypto.randomUUID());
+    const context = {
+      runId,
+      pipelineId: this.id,
+      runMetadata: options.metadata,
+      abortSignal: options.abortSignal,
+      observer: options.observer,
+      failOnObserverError: options.failOnObserverError === true
+    };
+    throwIfAborted(context.abortSignal);
+    const output = await this.execute(options.input, context, []);
+    throwIfAborted(context.abortSignal);
+    return { runId, output };
   }
-  async runStep(input, context) {
-    return await this.executor(input, context);
+  async runBatch(options) {
+    throwIfAborted(options.abortSignal);
+    return mapWithConcurrency([...options.inputs], options.concurrency, async (input) => {
+      const runId = globalThis.crypto.randomUUID();
+      try {
+        const result = await this.run({
+          input,
+          runId,
+          metadata: options.metadata,
+          abortSignal: options.abortSignal,
+          observer: options.observer,
+          failOnObserverError: options.failOnObserverError
+        });
+        return { status: "completed", ...result };
+      } catch (error) {
+        if (options.abortSignal?.aborted === true) {
+          throw pipelineAbortError(options.abortSignal);
+        }
+        return { status: "failed", runId, error };
+      }
+    });
+  }
+  graph() {
+    return cloneGraph(withOutputNode(this.state));
+  }
+  derive(executor, state) {
+    return createDerivedPipeline(executor, state);
+  }
+  async execute(input, context, pathPrefix) {
+    throwIfAborted(context.abortSignal);
+    return await this.executor(input, context, pathPrefix);
   }
 };
-function identity(input) {
-  return input;
+function createDerivedPipeline(executor, state) {
+  const options = {
+    [internalPipelineOptions]: { executor, state }
+  };
+  return new Pipeline(options);
+}
+function isInternalPipelineOptions(options) {
+  return internalPipelineOptions in options;
 }
 function isZodSchema(value) {
   return value instanceof z.ZodType;
 }
-function isBuilderState(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false;
+function normalizePipelineId(id) {
+  if (typeof id !== "string") {
+    throw new TypeError("Pipeline id must be a string.");
   }
-  const candidate = value;
-  return "graph" in candidate && "terminalNodeId" in candidate && "terminalNodeIds" in candidate && "nextNodeIndex" in candidate && "nextEdgeIndex" in candidate;
+  const normalized = id.trim();
+  if (normalized.length === 0) {
+    throw new TypeError("Pipeline id must be a non-empty string.");
+  }
+  return normalized;
+}
+function normalizeRunId(runId) {
+  if (typeof runId !== "string") {
+    throw new TypeError("Pipeline runId must be a string.");
+  }
+  const normalized = runId.trim();
+  if (normalized.length === 0) {
+    throw new TypeError("Pipeline runId must be a non-empty string.");
+  }
+  return normalized;
 }
-function isPipelineMetadata(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false;
+function normalizeParallelBranches(branches) {
+  const entries = [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(branches)) {
+    const pipeline = branches[key];
+    const id = key.trim();
+    if (id.length === 0) {
+      throw new TypeError("Pipeline parallel branch id must be a non-empty string.");
+    }
+    if (ids.has(id)) {
+      throw new TypeError(`Pipeline parallel branch id "${id}" is already registered.`);
+    }
+    ids.add(id);
+    if (id !== key) {
+      throw new TypeError("Pipeline parallel branch ids must not contain surrounding whitespace.");
+    }
+    entries.push([id, pipeline]);
   }
-  const candidate = value;
-  return "id" in candidate || "name" in candidate || "description" in candidate || "metadata" in candidate;
+  return entries;
 }
 export {
   Pipeline,
-  PipelineBuilder
+  PipelineAgentSuspensionError
 };
 //# sourceMappingURL=index.js.map