agentflow-core 0.1.1 → 0.1.2

package/dist/index.cjs

@@ -31,11 +31,15 @@ __export(index_exports, {
   getNode: () => getNode,
   getParent: () => getParent,
   getStats: () => getStats,
-  getSubtree: () => getSubtree
+  getSubtree: () => getSubtree,
+  getTraceTree: () => getTraceTree,
+  groupByTraceId: () => groupByTraceId,
+  stitchTrace: () => stitchTrace
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/graph-builder.ts
+var import_crypto = require("crypto");
 function deepFreeze(obj) {
   if (obj === null || typeof obj !== "object") return obj;
   if (obj instanceof Map) {
@@ -66,6 +70,9 @@ function createGraphBuilder(config) {
   const generateId = config?.idGenerator ?? createCounterIdGenerator();
   const agentId = config?.agentId ?? "unknown";
   const trigger = config?.trigger ?? "manual";
+  const spanId = (0, import_crypto.randomUUID)();
+  const traceId = config?.traceId ?? (typeof process !== "undefined" ? process.env?.AGENTFLOW_TRACE_ID : void 0) ?? (0, import_crypto.randomUUID)();
+  const parentSpanId = config?.parentSpanId ?? (typeof process !== "undefined" ? process.env?.AGENTFLOW_PARENT_SPAN_ID : void 0) ?? null;
   const graphId = generateId();
   const startTime = Date.now();
   const nodes = /* @__PURE__ */ new Map();
@@ -136,7 +143,10 @@ function createGraphBuilder(config) {
       status: graphStatus,
       trigger,
       agentId,
-      events: [...events]
+      events: [...events],
+      traceId,
+      spanId,
+      parentSpanId
     };
     return deepFreeze(graph);
   }
@@ -144,6 +154,9 @@ function createGraphBuilder(config) {
     get graphId() {
       return graphId;
     },
+    get traceContext() {
+      return { traceId, spanId };
+    },
     startNode(opts) {
       assertNotBuilt();
       const id = generateId();
@@ -251,6 +264,70 @@ function createGraphBuilder(config) {
   return builder;
 }
 
+// src/graph-stitch.ts
+function groupByTraceId(graphs) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const g of graphs) {
+    if (!g.traceId) continue;
+    const arr = groups.get(g.traceId) ?? [];
+    arr.push(g);
+    groups.set(g.traceId, arr);
+  }
+  return groups;
+}
+function stitchTrace(graphs) {
+  if (graphs.length === 0) throw new Error("No graphs to stitch");
+  const traceId = graphs[0].traceId ?? "";
+  const graphsBySpan = /* @__PURE__ */ new Map();
+  const childMap = /* @__PURE__ */ new Map();
+  let rootGraph = null;
+  for (const g of graphs) {
+    if (g.spanId) graphsBySpan.set(g.spanId, g);
+    if (!g.parentSpanId) {
+      if (!rootGraph || g.startTime < rootGraph.startTime) rootGraph = g;
+    }
+    if (g.parentSpanId) {
+      const siblings = childMap.get(g.parentSpanId) ?? [];
+      if (g.spanId) siblings.push(g.spanId);
+      childMap.set(g.parentSpanId, siblings);
+    }
+  }
+  if (!rootGraph) rootGraph = graphs[0];
+  let status = "completed";
+  let endTime = 0;
+  let startTime = Infinity;
+  for (const g of graphs) {
+    startTime = Math.min(startTime, g.startTime);
+    if (g.status === "failed") status = "failed";
+    else if (g.status === "running" && status !== "failed") status = "running";
+    if (g.endTime === null) endTime = null;
+    else if (endTime !== null) endTime = Math.max(endTime, g.endTime);
+  }
+  const frozenChildMap = /* @__PURE__ */ new Map();
+  for (const [k, v] of childMap) frozenChildMap.set(k, Object.freeze([...v]));
+  return Object.freeze({
+    traceId,
+    graphs: graphsBySpan,
+    rootGraph,
+    childMap: frozenChildMap,
+    startTime,
+    endTime,
+    status
+  });
+}
+function getTraceTree(trace) {
+  const result = [];
+  function walk(spanId) {
+    const graph = trace.graphs.get(spanId);
+    if (graph) result.push(graph);
+    const children = trace.childMap.get(spanId) ?? [];
+    for (const childSpan of children) walk(childSpan);
+  }
+  if (trace.rootGraph.spanId) walk(trace.rootGraph.spanId);
+  else result.push(trace.rootGraph);
+  return result;
+}
+
 // src/graph-query.ts
 function getNode(graph, nodeId) {
   return graph.nodes.get(nodeId);
@@ -402,5 +479,8 @@ function getStats(graph) {
   getNode,
   getParent,
   getStats,
-  getSubtree
+  getSubtree,
+  getTraceTree,
+  groupByTraceId,
+  stitchTrace
 });

package/dist/index.d.cts

@@ -65,6 +65,12 @@ interface ExecutionGraph {
     readonly agentId: string;
     /** Full ordered event log for auditability. */
     readonly events: readonly TraceEvent[];
+    /** Distributed trace ID linking graphs across services. */
+    readonly traceId?: string;
+    /** Unique span ID for this graph within the trace. */
+    readonly spanId?: string;
+    /** Parent span ID, or null if this is the root span. */
+    readonly parentSpanId?: string | null;
 }
 /**
  * Configuration for AgentFlow.
@@ -100,6 +106,10 @@ interface AgentFlowConfig {
     readonly logger?: (message: string) => void;
     /** Error callback for internal failures. */
     readonly onError?: (error: unknown) => void;
+    /** Distributed trace ID to join an existing trace. */
+    readonly traceId?: string;
+    /** Parent span ID for linking to an upstream graph. */
+    readonly parentSpanId?: string;
 }
 /**
  * Output adapter interface. Writers receive the completed execution graph
@@ -161,6 +171,11 @@ interface StartNodeOptions {
 interface GraphBuilder {
     /** The graph's ID, available before `build()`. */
     readonly graphId: string;
+    /** Trace context for propagating distributed trace information. */
+    readonly traceContext: {
+        traceId: string;
+        spanId: string;
+    };
     /** Start a new execution node. Returns the generated node ID. */
     startNode(opts: StartNodeOptions): string;
     /** End a node. Status defaults to `'completed'`. */
@@ -204,6 +219,16 @@ interface GraphStats {
     readonly failureCount: number;
     readonly hungCount: number;
 }
+/** A stitched distributed trace spanning multiple execution graphs. */
+interface DistributedTrace {
+    readonly traceId: string;
+    readonly graphs: ReadonlyMap<string, ExecutionGraph>;
+    readonly rootGraph: ExecutionGraph;
+    readonly childMap: ReadonlyMap<string, readonly string[]>;
+    readonly startTime: number;
+    readonly endTime: number | null;
+    readonly status: GraphStatus;
+}
 /** @internal Mutable version of ExecutionNode used during graph construction. */
 interface MutableExecutionNode {
     id: string;
@@ -251,6 +276,10 @@ interface MutableExecutionNode {
  */
 declare function createGraphBuilder(config?: AgentFlowConfig): GraphBuilder;
 
+declare function groupByTraceId(graphs: ExecutionGraph[]): Map<string, ExecutionGraph[]>;
+declare function stitchTrace(graphs: ExecutionGraph[]): DistributedTrace;
+declare function getTraceTree(trace: DistributedTrace): ExecutionGraph[];
+
 /**
  * Pure query functions for interrogating a built `ExecutionGraph`.
  * Every function takes a frozen graph and returns derived data without mutation.
@@ -367,4 +396,4 @@ declare function getDepth(graph: ExecutionGraph): number;
  */
 declare function getStats(graph: ExecutionGraph): GraphStats;
 
-export { type Adapter, type AgentFlowConfig, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree };
+export { type Adapter, type AgentFlowConfig, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, groupByTraceId, stitchTrace };

package/dist/index.d.ts

@@ -65,6 +65,12 @@ interface ExecutionGraph {
     readonly agentId: string;
     /** Full ordered event log for auditability. */
     readonly events: readonly TraceEvent[];
+    /** Distributed trace ID linking graphs across services. */
+    readonly traceId?: string;
+    /** Unique span ID for this graph within the trace. */
+    readonly spanId?: string;
+    /** Parent span ID, or null if this is the root span. */
+    readonly parentSpanId?: string | null;
 }
 /**
  * Configuration for AgentFlow.
@@ -100,6 +106,10 @@ interface AgentFlowConfig {
     readonly logger?: (message: string) => void;
     /** Error callback for internal failures. */
     readonly onError?: (error: unknown) => void;
+    /** Distributed trace ID to join an existing trace. */
+    readonly traceId?: string;
+    /** Parent span ID for linking to an upstream graph. */
+    readonly parentSpanId?: string;
 }
 /**
  * Output adapter interface. Writers receive the completed execution graph
@@ -161,6 +171,11 @@ interface StartNodeOptions {
 interface GraphBuilder {
     /** The graph's ID, available before `build()`. */
     readonly graphId: string;
+    /** Trace context for propagating distributed trace information. */
+    readonly traceContext: {
+        traceId: string;
+        spanId: string;
+    };
     /** Start a new execution node. Returns the generated node ID. */
     startNode(opts: StartNodeOptions): string;
     /** End a node. Status defaults to `'completed'`. */
@@ -204,6 +219,16 @@ interface GraphStats {
     readonly failureCount: number;
     readonly hungCount: number;
 }
+/** A stitched distributed trace spanning multiple execution graphs. */
+interface DistributedTrace {
+    readonly traceId: string;
+    readonly graphs: ReadonlyMap<string, ExecutionGraph>;
+    readonly rootGraph: ExecutionGraph;
+    readonly childMap: ReadonlyMap<string, readonly string[]>;
+    readonly startTime: number;
+    readonly endTime: number | null;
+    readonly status: GraphStatus;
+}
 /** @internal Mutable version of ExecutionNode used during graph construction. */
 interface MutableExecutionNode {
     id: string;
@@ -251,6 +276,10 @@ interface MutableExecutionNode {
  */
 declare function createGraphBuilder(config?: AgentFlowConfig): GraphBuilder;
 
+declare function groupByTraceId(graphs: ExecutionGraph[]): Map<string, ExecutionGraph[]>;
+declare function stitchTrace(graphs: ExecutionGraph[]): DistributedTrace;
+declare function getTraceTree(trace: DistributedTrace): ExecutionGraph[];
+
 /**
  * Pure query functions for interrogating a built `ExecutionGraph`.
  * Every function takes a frozen graph and returns derived data without mutation.
@@ -367,4 +396,4 @@ declare function getDepth(graph: ExecutionGraph): number;
  */
 declare function getStats(graph: ExecutionGraph): GraphStats;
 
-export { type Adapter, type AgentFlowConfig, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree };
+export { type Adapter, type AgentFlowConfig, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, groupByTraceId, stitchTrace };

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/graph-builder.ts
+import { randomUUID } from "crypto";
 function deepFreeze(obj) {
   if (obj === null || typeof obj !== "object") return obj;
   if (obj instanceof Map) {
@@ -29,6 +30,9 @@ function createGraphBuilder(config) {
   const generateId = config?.idGenerator ?? createCounterIdGenerator();
   const agentId = config?.agentId ?? "unknown";
   const trigger = config?.trigger ?? "manual";
+  const spanId = randomUUID();
+  const traceId = config?.traceId ?? (typeof process !== "undefined" ? process.env?.AGENTFLOW_TRACE_ID : void 0) ?? randomUUID();
+  const parentSpanId = config?.parentSpanId ?? (typeof process !== "undefined" ? process.env?.AGENTFLOW_PARENT_SPAN_ID : void 0) ?? null;
   const graphId = generateId();
   const startTime = Date.now();
   const nodes = /* @__PURE__ */ new Map();
@@ -99,7 +103,10 @@ function createGraphBuilder(config) {
       status: graphStatus,
       trigger,
       agentId,
-      events: [...events]
+      events: [...events],
+      traceId,
+      spanId,
+      parentSpanId
     };
     return deepFreeze(graph);
   }
@@ -107,6 +114,9 @@ function createGraphBuilder(config) {
     get graphId() {
       return graphId;
     },
+    get traceContext() {
+      return { traceId, spanId };
+    },
     startNode(opts) {
       assertNotBuilt();
       const id = generateId();
@@ -214,6 +224,70 @@ function createGraphBuilder(config) {
   return builder;
 }
 
+// src/graph-stitch.ts
+function groupByTraceId(graphs) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const g of graphs) {
+    if (!g.traceId) continue;
+    const arr = groups.get(g.traceId) ?? [];
+    arr.push(g);
+    groups.set(g.traceId, arr);
+  }
+  return groups;
+}
+function stitchTrace(graphs) {
+  if (graphs.length === 0) throw new Error("No graphs to stitch");
+  const traceId = graphs[0].traceId ?? "";
+  const graphsBySpan = /* @__PURE__ */ new Map();
+  const childMap = /* @__PURE__ */ new Map();
+  let rootGraph = null;
+  for (const g of graphs) {
+    if (g.spanId) graphsBySpan.set(g.spanId, g);
+    if (!g.parentSpanId) {
+      if (!rootGraph || g.startTime < rootGraph.startTime) rootGraph = g;
+    }
+    if (g.parentSpanId) {
+      const siblings = childMap.get(g.parentSpanId) ?? [];
+      if (g.spanId) siblings.push(g.spanId);
+      childMap.set(g.parentSpanId, siblings);
+    }
+  }
+  if (!rootGraph) rootGraph = graphs[0];
+  let status = "completed";
+  let endTime = 0;
+  let startTime = Infinity;
+  for (const g of graphs) {
+    startTime = Math.min(startTime, g.startTime);
+    if (g.status === "failed") status = "failed";
+    else if (g.status === "running" && status !== "failed") status = "running";
+    if (g.endTime === null) endTime = null;
+    else if (endTime !== null) endTime = Math.max(endTime, g.endTime);
+  }
+  const frozenChildMap = /* @__PURE__ */ new Map();
+  for (const [k, v] of childMap) frozenChildMap.set(k, Object.freeze([...v]));
+  return Object.freeze({
+    traceId,
+    graphs: graphsBySpan,
+    rootGraph,
+    childMap: frozenChildMap,
+    startTime,
+    endTime,
+    status
+  });
+}
+function getTraceTree(trace) {
+  const result = [];
+  function walk(spanId) {
+    const graph = trace.graphs.get(spanId);
+    if (graph) result.push(graph);
+    const children = trace.childMap.get(spanId) ?? [];
+    for (const childSpan of children) walk(childSpan);
+  }
+  if (trace.rootGraph.spanId) walk(trace.rootGraph.spanId);
+  else result.push(trace.rootGraph);
+  return result;
+}
+
 // src/graph-query.ts
 function getNode(graph, nodeId) {
   return graph.nodes.get(nodeId);
@@ -364,5 +438,8 @@ export {
   getNode,
   getParent,
   getStats,
-  getSubtree
+  getSubtree,
+  getTraceTree,
+  groupByTraceId,
+  stitchTrace
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentflow-core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Universal execution tracing for AI agent systems",
   "type": "module",
   "main": "./dist/index.cjs",