agentflow-core 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -276,6 +276,58 @@ interface MutableExecutionNode {
  */
 declare function createGraphBuilder(config?: AgentFlowConfig): GraphBuilder;
 
+/**
+ * Load and deserialize execution graphs from JSON.
+ *
+ * Handles all serialization formats produced by the runner, graph-builder,
+ * and third-party tools:
+ *   - `nodes` as a plain object `{ "node_001": { ... } }`  (runner.ts output)
+ *   - `nodes` as an array of `[id, node]` pairs              (Map JSON serialization)
+ *   - `nodes` already a Map                                   (in-memory passthrough)
+ *
+ * @module
+ */
+
+/**
+ * Deserialize a JSON object (or JSON string) into a valid `ExecutionGraph`.
+ *
+ * Use this whenever you read a trace file from disk or receive one over the
+ * network.  It normalizes `nodes` into a proper `Map` regardless of the
+ * serialization format.
+ *
+ * @param input - A parsed JSON object, or a JSON string to be parsed.
+ * @returns A valid `ExecutionGraph` ready for use with query functions.
+ * @throws {Error} If the input cannot be parsed or is missing required fields.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'fs';
+ * import { loadGraph, getStats } from 'agentflow-core';
+ *
+ * const graph = loadGraph(readFileSync('trace.json', 'utf8'));
+ * console.log(getStats(graph));
+ * ```
+ */
+declare function loadGraph(input: string | Record<string, unknown>): ExecutionGraph;
+/**
+ * Serialize an `ExecutionGraph` to a plain JSON-safe object.
+ *
+ * The inverse of `loadGraph`.  `nodes` is written as a plain object keyed by
+ * node ID, which is the most readable format for trace files on disk.
+ *
+ * @param graph - The execution graph to serialize.
+ * @returns A plain object safe to pass to `JSON.stringify`.
+ *
+ * @example
+ * ```ts
+ * import { writeFileSync } from 'fs';
+ * import { graphToJson } from 'agentflow-core';
+ *
+ * writeFileSync('trace.json', JSON.stringify(graphToJson(graph), null, 2));
+ * ```
+ */
+declare function graphToJson(graph: ExecutionGraph): Record<string, unknown>;
+
 /**
  * CLI runner that wraps any command with automatic AgentFlow tracing.
  *
@@ -325,6 +377,25 @@ interface RunResult {
  */
 declare function runTraced(config: RunConfig): Promise<RunResult>;
 
+/**
+ * AgentFlow Live Monitor — real-time terminal dashboard for any agent system.
+ *
+ * Usage:
+ *   agentflow live [traces-dir] [options]
+ *   agentflow live ./traces --refresh 5
+ *
+ * Features:
+ *   - Auto-discovers agents from trace files
+ *   - Sparkline activity graph (1 hour)
+ *   - Per-agent success/failure table
+ *   - Distributed trace tree view
+ *   - Recent execution feed
+ *   - fs.watch auto-refresh on new traces
+ *
+ * @module
+ */
+declare function startLive(argv: string[]): void;
+
 declare function groupByTraceId(graphs: ExecutionGraph[]): Map<string, ExecutionGraph[]>;
 declare function stitchTrace(graphs: ExecutionGraph[]): DistributedTrace;
 declare function getTraceTree(trace: DistributedTrace): ExecutionGraph[];
@@ -445,4 +516,4 @@ declare function getDepth(graph: ExecutionGraph): number;
  */
 declare function getStats(graph: ExecutionGraph): GraphStats;
 
-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 RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, groupByTraceId, runTraced, stitchTrace };
+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 RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, stitchTrace };

package/dist/index.js

@@ -1,210 +1,24 @@
 import {
   createGraphBuilder,
-  runTraced
-} from "./chunk-DGLK6IBP.js";
-
-// 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);
-}
-function getChildren(graph, nodeId) {
-  const node = graph.nodes.get(nodeId);
-  if (!node) return [];
-  const result = [];
-  for (const childId of node.children) {
-    const child = graph.nodes.get(childId);
-    if (child) result.push(child);
-  }
-  return result;
-}
-function getParent(graph, nodeId) {
-  const node = graph.nodes.get(nodeId);
-  if (!node || node.parentId === null) return void 0;
-  return graph.nodes.get(node.parentId);
-}
-function getFailures(graph) {
-  const failureStatuses = /* @__PURE__ */ new Set(["failed", "hung", "timeout"]);
-  return [...graph.nodes.values()].filter((node) => failureStatuses.has(node.status));
-}
-function getHungNodes(graph) {
-  return [...graph.nodes.values()].filter(
-    (node) => node.status === "running" && node.endTime === null
-  );
-}
-function getCriticalPath(graph) {
-  const root = graph.nodes.get(graph.rootNodeId);
-  if (!root) return [];
-  function nodeDuration(node) {
-    const end = node.endTime ?? Date.now();
-    return end - node.startTime;
-  }
-  function dfs(node) {
-    if (node.children.length === 0) {
-      return { duration: nodeDuration(node), path: [node] };
-    }
-    let bestChild = { duration: -1, path: [] };
-    for (const childId of node.children) {
-      const child = graph.nodes.get(childId);
-      if (!child) continue;
-      const result = dfs(child);
-      if (result.duration > bestChild.duration) {
-        bestChild = result;
-      }
-    }
-    return {
-      duration: nodeDuration(node) + bestChild.duration,
-      path: [node, ...bestChild.path]
-    };
-  }
-  return dfs(root).path;
-}
-function findWaitingOn(graph, nodeId) {
-  const results = [];
-  for (const edge of graph.edges) {
-    if (edge.from === nodeId && edge.type === "waited_on") {
-      const node = graph.nodes.get(edge.to);
-      if (node) results.push(node);
-    }
-  }
-  return results;
-}
-function getSubtree(graph, nodeId) {
-  const startNode = graph.nodes.get(nodeId);
-  if (!startNode) return [];
-  const result = [];
-  const queue = [...startNode.children];
-  while (queue.length > 0) {
-    const currentId = queue.shift();
-    if (currentId === void 0) break;
-    const current = graph.nodes.get(currentId);
-    if (!current) continue;
-    result.push(current);
-    queue.push(...current.children);
-  }
-  return result;
-}
-function getDuration(graph) {
-  const end = graph.endTime ?? Date.now();
-  return end - graph.startTime;
-}
-function getDepth(graph) {
-  const root = graph.nodes.get(graph.rootNodeId);
-  if (!root) return -1;
-  function dfs(node, depth) {
-    if (node.children.length === 0) return depth;
-    let maxDepth = depth;
-    for (const childId of node.children) {
-      const child = graph.nodes.get(childId);
-      if (!child) continue;
-      const childDepth = dfs(child, depth + 1);
-      if (childDepth > maxDepth) maxDepth = childDepth;
-    }
-    return maxDepth;
-  }
-  return dfs(root, 0);
-}
-function getStats(graph) {
-  const byStatus = {
-    running: 0,
-    completed: 0,
-    failed: 0,
-    hung: 0,
-    timeout: 0
-  };
-  const byType = {
-    agent: 0,
-    tool: 0,
-    subagent: 0,
-    wait: 0,
-    decision: 0,
-    custom: 0
-  };
-  let failureCount = 0;
-  let hungCount = 0;
-  for (const node of graph.nodes.values()) {
-    byStatus[node.status]++;
-    byType[node.type]++;
-    if (node.status === "failed" || node.status === "timeout" || node.status === "hung") {
-      failureCount++;
-    }
-    if (node.status === "running" && node.endTime === null) {
-      hungCount++;
-    }
-  }
-  return {
-    totalNodes: graph.nodes.size,
-    byStatus,
-    byType,
-    depth: getDepth(graph),
-    duration: getDuration(graph),
-    failureCount,
-    hungCount
-  };
-}
+  findWaitingOn,
+  getChildren,
+  getCriticalPath,
+  getDepth,
+  getDuration,
+  getFailures,
+  getHungNodes,
+  getNode,
+  getParent,
+  getStats,
+  getSubtree,
+  getTraceTree,
+  graphToJson,
+  groupByTraceId,
+  loadGraph,
+  runTraced,
+  startLive,
+  stitchTrace
+} from "./chunk-TRKBUPIN.js";
 export {
   createGraphBuilder,
   findWaitingOn,
@@ -219,7 +33,10 @@ export {
   getStats,
   getSubtree,
   getTraceTree,
+  graphToJson,
   groupByTraceId,
+  loadGraph,
   runTraced,
+  startLive,
   stitchTrace
 };

package/package.json

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