@anvia/core 1.0.3 → 1.0.4

package/dist/pipeline/index.js

@@ -1,3 +1,6 @@
+import {
+  observerSnapshot
+} from "../chunk-KSKST3KP.js";
 import {
   AgentRunBlockedError
 } from "../chunk-AHLKV6KP.js";
@@ -26,6 +29,19 @@ var PipelineAgentSuspensionError = class extends Error {
   }
   result;
 };
+var PipelineObserverDispatchError = class extends AggregateError {
+  phase;
+  failures;
+  constructor(phase, failures) {
+    super(
+      failures.map((failure) => failure.error),
+      `Pipeline observer ${phase} failed for ${failures.map((failure) => failure.observer).join(", ")}.`
+    );
+    this.name = "PipelineObserverDispatchError";
+    this.phase = phase;
+    this.failures = Object.freeze([...failures]);
+  }
+};
 
 // src/pipeline/pipeline.ts
 import { z } from "zod";
@@ -201,48 +217,214 @@ function pathEquals(left, right) {
   return left.length === right.length && left.every((segment, index) => segment === right[index]);
 }
 
+// src/pipeline/observability.ts
+function resolvePrimaryTrace(observers, primaryTrace) {
+  if (primaryTrace === void 0) return void 0;
+  const primary = observers.find((entry) => entry.name === primaryTrace);
+  return primary?.observer.trace === void 0 ? void 0 : Object.freeze({ observer: primary.name, ...primary.observer.trace });
+}
+function snapshotPipelineObservability(observability) {
+  if (observability === void 0) return void 0;
+  const observers = {};
+  for (const [name, observer] of Object.entries(observability.observers)) {
+    if (name.trim().length === 0) {
+      throw new TypeError("Pipeline observer names must not be empty.");
+    }
+    if (typeof observer !== "object" || observer === null || typeof observer.startRun !== "function") {
+      throw new TypeError(`Pipeline observer "${name}" must implement startRun().`);
+    }
+    observers[name] = observer;
+  }
+  if (observability.primaryTrace !== void 0 && !(observability.primaryTrace in observers)) {
+    throw new TypeError(
+      `Pipeline primaryTrace "${observability.primaryTrace}" must name a configured observer.`
+    );
+  }
+  const errorPolicy = observability.errorPolicy ?? "ignore";
+  if (errorPolicy !== "ignore" && errorPolicy !== "throw") {
+    throw new TypeError('Pipeline observability.errorPolicy must be "ignore" or "throw".');
+  }
+  const snapshot = {
+    observers: Object.freeze(observers),
+    errorPolicy,
+    ...observability.primaryTrace === void 0 ? {} : { primaryTrace: observability.primaryTrace }
+  };
+  return Object.freeze(snapshot);
+}
+async function startPipelineRunObservers(observers, args, options) {
+  const runObservers = [];
+  const failures = [];
+  for (const [name, observer] of Object.entries(observers)) {
+    try {
+      const runObserver = await observer.startRun(observerSnapshot(args));
+      if (runObserver !== void 0) {
+        runObservers.push({ name, observer: runObserver, terminal: false });
+      }
+    } catch (error) {
+      failures.push({ observer: name, error });
+    }
+  }
+  if (options.errorPolicy === "throw" && failures.length > 0) {
+    const startupError = new PipelineObserverDispatchError("startRun", failures);
+    const cleanupFailures = await terminateObservers(
+      runObservers,
+      (observer) => observer.error?.(
+        observerSnapshot({
+          runId: args.runId,
+          pipelineId: args.pipelineId,
+          status: "failed",
+          error: startupError,
+          durationMs: 0
+        })
+      )
+    );
+    throw new PipelineObserverDispatchError("startRun", [...failures, ...cleanupFailures]);
+  }
+  return new ActivePipelineRunObservers(runObservers, options);
+}
+var ActivePipelineRunObservers = class {
+  constructor(observers, options) {
+    this.observers = observers;
+    this.options = options;
+    this.trace = resolvePrimaryTrace(observers, options.primaryTrace);
+  }
+  observers;
+  options;
+  trace;
+  async startStage(args) {
+    const stageObservers = [];
+    const failures = [];
+    for (const entry of this.observers) {
+      if (entry.observer.startStage === void 0) continue;
+      try {
+        const observer = await entry.observer.startStage(observerSnapshot(args));
+        if (observer !== void 0) {
+          stageObservers.push({ name: entry.name, observer, terminal: false });
+        }
+      } catch (error) {
+        failures.push({ observer: entry.name, error });
+      }
+    }
+    if (this.options.errorPolicy === "throw" && failures.length > 0) {
+      const startupError = new PipelineObserverDispatchError("startStage", failures);
+      const cleanupFailures = await terminateObservers(
+        stageObservers,
+        (observer) => observer.error?.(observerSnapshot({ ...args, error: startupError, durationMs: 0 }))
+      );
+      throw new PipelineObserverDispatchError("startStage", [...failures, ...cleanupFailures]);
+    }
+    return new ActivePipelineStageObservers(stageObservers, this.options);
+  }
+  async end(args) {
+    await dispatchTerminalObservers(
+      this.observers,
+      "end",
+      (observer) => observer.end(observerSnapshot(args)),
+      this.options.errorPolicy
+    );
+  }
+  async error(args) {
+    await dispatchTerminalObservers(
+      this.observers,
+      "error",
+      (observer) => observer.error?.(observerSnapshot(args)),
+      "ignore"
+    );
+  }
+};
+var ActivePipelineStageObservers = class {
+  constructor(observers, options) {
+    this.observers = observers;
+    this.options = options;
+    this.trace = resolvePrimaryTrace(observers, options.primaryTrace);
+  }
+  observers;
+  options;
+  trace;
+  async end(args) {
+    await dispatchTerminalObservers(
+      this.observers,
+      "stage.end",
+      (observer) => observer.end(observerSnapshot(args)),
+      this.options.errorPolicy
+    );
+  }
+  async error(args) {
+    await dispatchTerminalObservers(
+      this.observers,
+      "stage.error",
+      (observer) => observer.error?.(observerSnapshot(args)),
+      "ignore"
+    );
+  }
+};
+async function dispatchTerminalObservers(observers, phase, dispatch, errorPolicy) {
+  const failures = await terminateObservers(observers, dispatch);
+  if (errorPolicy === "throw" && failures.length > 0) {
+    throw new PipelineObserverDispatchError(phase, failures);
+  }
+}
+async function terminateObservers(observers, dispatch) {
+  const failures = [];
+  for (const entry of observers) {
+    if (entry.terminal) continue;
+    entry.terminal = true;
+    try {
+      await dispatch(entry.observer);
+    } catch (error) {
+      failures.push({ observer: entry.name, error });
+    }
+  }
+  return failures;
+}
+
 // src/pipeline/runtime.ts
-async function runNode(context, node, path, fn) {
+async function runNode(context, node, path, input, fn) {
   throwIfAborted(context.abortSignal);
   const eventNode = scopedNode(node, path);
   const startedAt = Date.now();
-  await emitEvent(context, {
-    type: "stage_started",
+  const eventBase = {
     runId: context.runId,
     pipelineId: context.pipelineId,
     path: [...path],
     node: eventNode
-  });
+  };
+  const observers = await context.observability.startStage({ ...eventBase, input });
   try {
-    const output = await fn();
+    await emitEvent(context, { type: "stage_started", ...eventBase });
+  } catch (error) {
+    await observers.error({ ...eventBase, error, durationMs: Date.now() - startedAt });
+    throw error;
+  }
+  try {
+    const output = await fn(observers.trace);
     throwIfAborted(context.abortSignal);
+    const durationMs = Date.now() - startedAt;
     await emitEvent(context, {
       type: "stage_completed",
-      runId: context.runId,
-      pipelineId: context.pipelineId,
-      path: [...path],
-      node: eventNode,
-      durationMs: Date.now() - startedAt
+      ...eventBase,
+      durationMs
     });
+    await observers.end({ ...eventBase, output, durationMs });
     return output;
   } catch (error) {
+    const durationMs = Date.now() - startedAt;
     const failureEvent = {
       type: "stage_failed",
-      runId: context.runId,
-      pipelineId: context.pipelineId,
-      path: [...path],
-      node: eventNode,
-      durationMs: Date.now() - startedAt,
+      ...eventBase,
+      durationMs,
       error
     };
     try {
       await emitEvent(context, failureEvent);
     } catch (observerError) {
+      await observers.error({ ...eventBase, error, durationMs });
       throw new AggregateError(
         [error, observerError],
         `Pipeline stage "${node.id}" and its observer both failed.`
       );
     }
+    await observers.error({ ...eventBase, error, durationMs });
     throw error;
   }
 }
@@ -297,12 +479,14 @@ var Pipeline = class {
   name;
   description;
   metadata;
+  observability;
   executor;
   state;
   constructor(options) {
     if (isInternalPipelineOptions(options)) {
       this.executor = options[internalPipelineOptions].executor;
       this.state = options[internalPipelineOptions].state;
+      this.observability = options[internalPipelineOptions].observability;
     } else {
       const id = normalizePipelineId(options.id);
       if (!isZodSchema(options.inputSchema)) {
@@ -319,6 +503,7 @@ var Pipeline = class {
         description: options.description,
         metadata: options.metadata
       });
+      this.observability = snapshotPipelineObservability(options.observability);
     }
     const graph = this.state.graph;
     this.id = graph.id;
@@ -335,6 +520,7 @@ var Pipeline = class {
         context,
         next.node,
         path,
+        value,
         () => options.run(stageContext(value, context))
       );
     });
@@ -353,6 +539,7 @@ var Pipeline = class {
         context,
         boundary.node,
         path,
+        value,
         () => options.pipeline.execute(value, context, path)
       );
     });
@@ -379,7 +566,7 @@ var Pipeline = class {
     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 () => {
+      return runNode(context, parallel.node, parallelPath, value, async () => {
         const controller = new AbortController();
         const combined = combineAbortSignals(context.abortSignal, controller.signal);
         const branchContext = childContext(context, combined.signal);
@@ -392,6 +579,7 @@ var Pipeline = class {
               branchContext,
               node,
               path,
+              value,
               () => branch.execute(value, branchContext, path)
             );
             return [key, output];
@@ -427,10 +615,15 @@ var Pipeline = class {
     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 () => {
+      return runNode(context, next.node, path, value, async (stageTrace) => {
         const request = await options.request(stageContext(value, context));
         const response = await options.agent.generate({
           ...request,
+          trace: withPipelineParentTrace(
+            request.trace,
+            stageTrace,
+            options.agent.observability?.primaryTrace
+          ),
           abortSignal: context.abortSignal
         });
         if (response.type === "interaction") {
@@ -448,7 +641,7 @@ var Pipeline = class {
     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 () => {
+      return runNode(context, next.node, path, value, async () => {
         const text = await options.text(stageContext(value, context));
         const result = await extract({
           model: options.model,
@@ -467,18 +660,54 @@ var Pipeline = class {
   }
   async run(options) {
     const runId = normalizeRunId(options.runId ?? globalThis.crypto.randomUUID());
+    const startedAt = Date.now();
+    const observability = await startPipelineRunObservers(
+      this.observability?.observers ?? {},
+      {
+        runId,
+        pipelineId: this.id,
+        pipelineName: this.name,
+        pipelineDescription: this.description,
+        pipelineMetadata: this.metadata,
+        runMetadata: options.metadata,
+        trace: options.trace,
+        input: options.input
+      },
+      {
+        primaryTrace: this.observability?.primaryTrace,
+        errorPolicy: this.observability?.errorPolicy ?? "ignore"
+      }
+    );
     const context = {
       runId,
       pipelineId: this.id,
       runMetadata: options.metadata,
       abortSignal: options.abortSignal,
       observer: options.observer,
-      failOnObserverError: options.failOnObserverError === true
+      failOnObserverError: options.failOnObserverError === true,
+      observability
     };
-    throwIfAborted(context.abortSignal);
-    const output = await this.execute(options.input, context, []);
-    throwIfAborted(context.abortSignal);
-    return { runId, output };
+    try {
+      throwIfAborted(context.abortSignal);
+      const output = await this.execute(options.input, context, []);
+      throwIfAborted(context.abortSignal);
+      await observability.end({
+        runId,
+        pipelineId: this.id,
+        output,
+        durationMs: Date.now() - startedAt
+      });
+      return observability.trace === void 0 ? { runId, output } : { runId, output, trace: observability.trace };
+    } catch (error) {
+      await observability.error({
+        runId,
+        pipelineId: this.id,
+        status: context.abortSignal?.aborted === true ? "cancelled" : "failed",
+        error,
+        durationMs: Date.now() - startedAt
+      });
+      throw error;
+    }
   }
   async runBatch(options) {
     throwIfAborted(options.abortSignal);
@@ -489,6 +718,7 @@ var Pipeline = class {
           input,
           runId,
           metadata: options.metadata,
+          trace: options.trace,
           abortSignal: options.abortSignal,
           observer: options.observer,
           failOnObserverError: options.failOnObserverError
@@ -506,19 +736,29 @@ var Pipeline = class {
     return cloneGraph(withOutputNode(this.state));
   }
   derive(executor, state) {
-    return createDerivedPipeline(executor, state);
+    return createDerivedPipeline(executor, state, this.observability);
   }
   async execute(input, context, pathPrefix) {
     throwIfAborted(context.abortSignal);
     return await this.executor(input, context, pathPrefix);
   }
 };
-function createDerivedPipeline(executor, state) {
+function createDerivedPipeline(executor, state, observability) {
   const options = {
-    [internalPipelineOptions]: { executor, state }
+    [internalPipelineOptions]: { executor, state, observability }
   };
   return new Pipeline(options);
 }
+function withPipelineParentTrace(trace, parent, agentPrimaryTrace) {
+  if (parent?.traceId === void 0) return trace;
+  if (parent.observer !== agentPrimaryTrace) return trace;
+  if (trace?.traceId !== void 0 && trace.traceId !== parent.traceId) return trace;
+  return {
+    ...trace,
+    traceId: parent.traceId,
+    ...trace?.parentObservationId !== void 0 || parent.observationId === void 0 ? {} : { parentObservationId: parent.observationId }
+  };
+}
 function isInternalPipelineOptions(options) {
   return internalPipelineOptions in options;
 }
@@ -567,6 +807,7 @@ function normalizeParallelBranches(branches) {
 }
 export {
   Pipeline,
-  PipelineAgentSuspensionError
+  PipelineAgentSuspensionError,
+  PipelineObserverDispatchError
 };
 //# sourceMappingURL=index.js.map