@anvia/core 1.0.3 → 1.0.7

package/dist/pipeline/index.d.ts

@@ -1,5 +1,5 @@
-import { g as AgentInteractionOutcome, f as AgentInput, o as AgentRunSettings } from '../types-BUEZMBhO.js';
-import { A as Agent } from '../agent-DYfzP-n5.js';
+import { g as AgentInteractionOutcome, X as AgentTraceOptions, J as AgentObserverTraceInfo, H as AgentObserverErrorPolicy, W as AgentTraceInfo, f as AgentInput, o as AgentRunSettings } from '../types-DL7wX6hJ.js';
+import { A as Agent } from '../agent-B-3jCRmI.js';
 import { J as JsonObject, c as CompletionModel } from '../types-DgvozfPc.js';
 import { ExtractOptions } from '../extractor/index.js';
 import { z } from 'zod';
@@ -7,7 +7,7 @@ import '../agent/interactions/index.js';
 import '../retry-CjvSlKGW.js';
 import '../types-DhkodEft.js';
 import '../type-utils-CtHVDRn_.js';
-import '../types-CSYt7-It.js';
+import '../types-DmzRCbU5.js';
 import '../tool-BpqpoRSE.js';
 import '../middleware-kcF8AusP.js';
 import '../zod-schema-C7F4clpm.js';
@@ -22,6 +22,15 @@ declare class PipelineAgentSuspensionError extends Error {
     readonly result: AgentInteractionOutcome;
     constructor(result: AgentInteractionOutcome);
 }
+type PipelineObserverFailure = {
+    readonly observer: string;
+    readonly error: unknown;
+};
+declare class PipelineObserverDispatchError extends AggregateError {
+    readonly phase: string;
+    readonly failures: readonly PipelineObserverFailure[];
+    constructor(phase: string, failures: readonly PipelineObserverFailure[]);
+}
 
 type PipelineMetadata = {
     id?: string | undefined;
@@ -35,6 +44,7 @@ type PipelineOptions<Input, Parsed = Input> = {
     name?: string | undefined;
     description?: string | undefined;
     metadata?: JsonObject | undefined;
+    observability?: PipelineObservabilityOptions | undefined;
 };
 type PipelineStageMetadata = {
     id: string;
@@ -93,10 +103,69 @@ type PipelineRunEvent = (PipelineRunEventBase & {
 type PipelineRunObserver = {
     onEvent(event: PipelineRunEvent): void | Promise<void>;
 };
+type PipelineTraceOptions = Omit<AgentTraceOptions, "promptRef">;
+type PipelineTraceInfo = AgentTraceInfo;
+type PipelineObserverTraceInfo = AgentObserverTraceInfo;
+type PipelineObserverErrorPolicy = AgentObserverErrorPolicy;
+type PipelineRunStartArgs = {
+    readonly runId: string;
+    readonly pipelineId: string;
+    readonly pipelineName?: string | undefined;
+    readonly pipelineDescription?: string | undefined;
+    readonly pipelineMetadata?: JsonObject | undefined;
+    readonly runMetadata?: JsonObject | undefined;
+    readonly trace?: PipelineTraceOptions | undefined;
+    readonly input: unknown;
+};
+type PipelineRunEndArgs = {
+    readonly runId: string;
+    readonly pipelineId: string;
+    readonly output: unknown;
+    readonly durationMs: number;
+};
+type PipelineRunErrorArgs = {
+    readonly runId: string;
+    readonly pipelineId: string;
+    readonly status: "failed" | "cancelled";
+    readonly error: unknown;
+    readonly durationMs: number;
+};
+type PipelineStageStartArgs = Readonly<PipelineRunEventBase> & {
+    readonly input: unknown;
+};
+type PipelineStageEndArgs = Readonly<PipelineRunEventBase> & {
+    readonly output: unknown;
+    readonly durationMs: number;
+};
+type PipelineStageErrorArgs = Readonly<PipelineRunEventBase> & {
+    readonly error: unknown;
+    readonly durationMs: number;
+};
+interface PipelineStageObservation {
+    readonly trace?: PipelineObserverTraceInfo | undefined;
+    end(args: PipelineStageEndArgs): void | Promise<void>;
+    error?(args: PipelineStageErrorArgs): void | Promise<void>;
+}
+interface PipelineRunObservation {
+    readonly trace?: PipelineObserverTraceInfo | undefined;
+    startStage?(args: PipelineStageStartArgs): PipelineStageObservation | undefined | Promise<PipelineStageObservation | undefined>;
+    end(args: PipelineRunEndArgs): void | Promise<void>;
+    error?(args: PipelineRunErrorArgs): void | Promise<void>;
+}
+interface PipelineObserver {
+    startRun(args: PipelineRunStartArgs): PipelineRunObservation | undefined | Promise<PipelineRunObservation | undefined>;
+}
+type PipelineObserverMap = Readonly<Record<string, PipelineObserver>>;
+type PipelineObservabilityOptions<Observers extends PipelineObserverMap = PipelineObserverMap> = {
+    readonly observers: Observers;
+    readonly primaryTrace?: Extract<keyof Observers, string> | undefined;
+    readonly errorPolicy?: PipelineObserverErrorPolicy | undefined;
+};
 type PipelineRunOptions<Input> = {
     input: Input;
     runId?: string | undefined;
     metadata?: JsonObject | undefined;
+    trace?: PipelineTraceOptions | undefined;
     abortSignal?: AbortSignal | undefined;
     observer?: PipelineRunObserver | undefined;
     failOnObserverError?: boolean | undefined;
@@ -104,11 +173,13 @@ type PipelineRunOptions<Input> = {
 type PipelineRunResult<Output> = {
     runId: string;
     output: Awaited<Output>;
+    trace?: PipelineTraceInfo | undefined;
 };
 type PipelineBatchOptions<Input> = {
     inputs: Iterable<Input>;
     concurrency: number;
     metadata?: JsonObject | undefined;
+    trace?: PipelineTraceOptions | undefined;
     abortSignal?: AbortSignal | undefined;
     observer?: PipelineRunObserver | undefined;
     failOnObserverError?: boolean | undefined;
@@ -117,6 +188,7 @@ type PipelineBatchItem<Output> = {
     status: "completed";
     runId: string;
     output: Awaited<Output>;
+    trace?: PipelineTraceInfo | undefined;
 } | {
     status: "failed";
     runId: string;
@@ -152,6 +224,7 @@ declare class Pipeline<Input, Output = Input> {
     readonly name: string | undefined;
     readonly description: string | undefined;
     readonly metadata: JsonObject | undefined;
+    readonly observability: PipelineOptions<Input>["observability"];
     private readonly executor;
     private readonly state;
     constructor(options: PipelineOptions<Input, Output>);
@@ -167,4 +240,4 @@ declare class Pipeline<Input, Output = Input> {
     private execute;
 }
 
-export { type ParallelOutput, Pipeline, type PipelineAgentOptions, PipelineAgentSuspensionError, type PipelineBatchItem, type PipelineBatchOptions, type PipelineComposeOptions, type PipelineExtractOptions, type PipelineGraph, type PipelineGraphEdge, type PipelineGraphNode, type PipelineMetadata, type PipelineNodePath, type PipelineOptions, type PipelineParallelOptions, type PipelineRunEvent, type PipelineRunObserver, type PipelineRunOptions, type PipelineRunResult, type PipelineStageContext, type PipelineStageKind, type PipelineStageMetadata, type PipelineStepOptions };
+export { type ParallelOutput, Pipeline, type PipelineAgentOptions, PipelineAgentSuspensionError, type PipelineBatchItem, type PipelineBatchOptions, type PipelineComposeOptions, type PipelineExtractOptions, type PipelineGraph, type PipelineGraphEdge, type PipelineGraphNode, type PipelineMetadata, type PipelineNodePath, type PipelineObservabilityOptions, type PipelineObserver, PipelineObserverDispatchError, type PipelineObserverErrorPolicy, type PipelineObserverFailure, type PipelineObserverMap, type PipelineObserverTraceInfo, type PipelineOptions, type PipelineParallelOptions, type PipelineRunEndArgs, type PipelineRunErrorArgs, type PipelineRunEvent, type PipelineRunObservation, type PipelineRunObserver, type PipelineRunOptions, type PipelineRunResult, type PipelineRunStartArgs, type PipelineStageContext, type PipelineStageEndArgs, type PipelineStageErrorArgs, type PipelineStageKind, type PipelineStageMetadata, type PipelineStageObservation, type PipelineStageStartArgs, type PipelineStepOptions, type PipelineTraceInfo, type PipelineTraceOptions };

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