agentflow-core 0.1.3 → 0.2.0

package/dist/index.cjs

@@ -33,8 +33,11 @@ __export(index_exports, {
   getStats: () => getStats,
   getSubtree: () => getSubtree,
   getTraceTree: () => getTraceTree,
+  graphToJson: () => graphToJson,
   groupByTraceId: () => groupByTraceId,
+  loadGraph: () => loadGraph,
   runTraced: () => runTraced,
+  startLive: () => startLive,
   stitchTrace: () => stitchTrace
 });
 module.exports = __toCommonJS(index_exports);
@@ -265,6 +268,58 @@ function createGraphBuilder(config) {
   return builder;
 }
 
+// src/loader.ts
+function toNodesMap(raw) {
+  if (raw instanceof Map) return raw;
+  if (Array.isArray(raw)) {
+    return new Map(raw);
+  }
+  if (raw !== null && typeof raw === "object") {
+    return new Map(Object.entries(raw));
+  }
+  return /* @__PURE__ */ new Map();
+}
+function loadGraph(input) {
+  const raw = typeof input === "string" ? JSON.parse(input) : input;
+  const nodes = toNodesMap(raw.nodes);
+  return {
+    id: raw.id ?? "",
+    rootNodeId: raw.rootNodeId ?? raw.rootId ?? "",
+    nodes,
+    edges: raw.edges ?? [],
+    startTime: raw.startTime ?? 0,
+    endTime: raw.endTime ?? null,
+    status: raw.status ?? "completed",
+    trigger: raw.trigger ?? "unknown",
+    agentId: raw.agentId ?? "unknown",
+    events: raw.events ?? [],
+    traceId: raw.traceId,
+    spanId: raw.spanId,
+    parentSpanId: raw.parentSpanId
+  };
+}
+function graphToJson(graph) {
+  const nodesObj = {};
+  for (const [id, node] of graph.nodes) {
+    nodesObj[id] = node;
+  }
+  return {
+    id: graph.id,
+    rootNodeId: graph.rootNodeId,
+    nodes: nodesObj,
+    edges: graph.edges,
+    startTime: graph.startTime,
+    endTime: graph.endTime,
+    status: graph.status,
+    trigger: graph.trigger,
+    agentId: graph.agentId,
+    events: graph.events,
+    traceId: graph.traceId,
+    spanId: graph.spanId,
+    parentSpanId: graph.parentSpanId
+  };
+}
+
 // src/runner.ts
 var import_node_child_process = require("child_process");
 var import_node_fs = require("fs");
@@ -300,27 +355,6 @@ function deriveAgentId(command) {
 function fileTimestamp() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-").replace(/\.\d+Z$/, "");
 }
-function graphToJson(graph) {
-  const nodesObj = {};
-  for (const [id, node] of graph.nodes) {
-    nodesObj[id] = node;
-  }
-  return {
-    id: graph.id,
-    rootNodeId: graph.rootNodeId,
-    nodes: nodesObj,
-    edges: graph.edges,
-    startTime: graph.startTime,
-    endTime: graph.endTime,
-    status: graph.status,
-    trigger: graph.trigger,
-    agentId: graph.agentId,
-    events: graph.events,
-    traceId: graph.traceId,
-    spanId: graph.spanId,
-    parentSpanId: graph.parentSpanId
-  };
-}
 async function runTraced(config) {
   const {
     command,
@@ -437,69 +471,9 @@ async function runTraced(config) {
   };
 }
 
-// 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/live.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
 
 // src/graph-query.ts
 function getNode(graph, nodeId) {
@@ -639,6 +613,348 @@ function getStats(graph) {
     hungCount
   };
 }
+
+// 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/live.ts
+var C = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[90m",
+  under: "\x1B[4m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  white: "\x1B[37m"
+};
+function parseArgs(argv) {
+  const config = {
+    tracesDir: "./traces",
+    refreshMs: 3e3
+  };
+  const args = argv.slice(0);
+  if (args[0] === "live") args.shift();
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      printUsage();
+      process.exit(0);
+    } else if (arg === "--refresh" || arg === "-r") {
+      i++;
+      const val = parseInt(args[i] ?? "", 10);
+      if (!isNaN(val) && val > 0) config.refreshMs = val * 1e3;
+      i++;
+    } else if (arg === "--traces-dir" || arg === "-t") {
+      i++;
+      config.tracesDir = args[i] ?? config.tracesDir;
+      i++;
+    } else if (!arg.startsWith("-")) {
+      config.tracesDir = arg;
+      i++;
+    } else {
+      i++;
+    }
+  }
+  config.tracesDir = (0, import_node_path2.resolve)(config.tracesDir);
+  return config;
+}
+function printUsage() {
+  console.log(`
+AgentFlow Live Monitor \u2014 real-time terminal dashboard for agent systems.
+
+Usage:
+  agentflow live [traces-dir] [options]
+
+Arguments:
+  traces-dir              Path to the traces directory (default: ./traces)
+
+Options:
+  -r, --refresh <secs>    Refresh interval in seconds (default: 3)
+  -t, --traces-dir <path> Explicit traces directory path
+  -h, --help              Show this help message
+
+Examples:
+  agentflow live
+  agentflow live ./my-traces --refresh 5
+  agentflow live /var/log/agentflow/traces -r 10
+`.trim());
+}
+function listTraceFiles(tracesDir) {
+  try {
+    return (0, import_node_fs2.readdirSync)(tracesDir).filter((f) => f.endsWith(".json")).map((f) => {
+      const fp = (0, import_node_path2.join)(tracesDir, f);
+      const stat = (0, import_node_fs2.statSync)(fp);
+      return { filename: f, path: fp, mtime: stat.mtime.getTime() };
+    }).sort((a, b) => b.mtime - a.mtime);
+  } catch {
+    return [];
+  }
+}
+function safeLoadTrace(fp) {
+  try {
+    return loadGraph((0, import_node_fs2.readFileSync)(fp, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function analyze(trace) {
+  try {
+    const stats = getStats(trace);
+    const fails = getFailures(trace);
+    const hung = getHungNodes(trace);
+    return {
+      agentId: trace.agentId,
+      trigger: trace.trigger,
+      traceId: trace.traceId,
+      spanId: trace.spanId,
+      parentSpanId: trace.parentSpanId,
+      nodes: stats.totalNodes,
+      success: fails.length === 0 && hung.length === 0,
+      failures: fails.length,
+      hung: hung.length
+    };
+  } catch {
+    return null;
+  }
+}
+function getDistributedDepth(dt, spanId) {
+  if (!spanId) return 0;
+  const graph = dt.graphs.get(spanId);
+  if (!graph || !graph.parentSpanId) return 0;
+  return 1 + getDistributedDepth(dt, graph.parentSpanId);
+}
+var prevFileCount = 0;
+var newExecCount = 0;
+var sessionStart = Date.now();
+function render(config) {
+  const files = listTraceFiles(config.tracesDir);
+  if (files.length > prevFileCount && prevFileCount > 0) {
+    newExecCount += files.length - prevFileCount;
+  }
+  prevFileCount = files.length;
+  const allTraces = [];
+  const agents = {};
+  for (const f of files.slice(0, 200)) {
+    const trace = safeLoadTrace(f.path);
+    if (!trace) continue;
+    allTraces.push(trace);
+    const a = analyze(trace);
+    if (!a) continue;
+    if (!agents[a.agentId]) {
+      agents[a.agentId] = { name: a.agentId, total: 0, ok: 0, fail: 0, lastTs: 0 };
+    }
+    const ag = agents[a.agentId];
+    ag.total++;
+    a.success ? ag.ok++ : ag.fail++;
+    if (f.mtime > ag.lastTs) ag.lastTs = f.mtime;
+  }
+  const agentList = Object.values(agents).sort((a, b) => b.total - a.total);
+  const totExec = agentList.reduce((s, a) => s + a.total, 0);
+  const totFail = agentList.reduce((s, a) => s + a.fail, 0);
+  const sysRate = totExec > 0 ? ((totExec - totFail) / totExec * 100).toFixed(1) : "100.0";
+  const recent = [];
+  for (const f of files.slice(0, 15)) {
+    const trace = safeLoadTrace(f.path);
+    if (!trace) continue;
+    const a = analyze(trace);
+    if (a) recent.push({ ...a, ts: f.mtime });
+  }
+  const now = Date.now();
+  const buckets = new Array(12).fill(0);
+  const failBuckets = new Array(12).fill(0);
+  for (const f of files) {
+    const age = now - f.mtime;
+    if (age > 36e5) continue;
+    const idx = 11 - Math.floor(age / 3e5);
+    if (idx >= 0 && idx < 12) {
+      const trace = safeLoadTrace(f.path);
+      if (!trace) continue;
+      const a = analyze(trace);
+      if (!a) continue;
+      buckets[idx]++;
+      if (!a.success) failBuckets[idx]++;
+    }
+  }
+  const maxBucket = Math.max(...buckets, 1);
+  const sparkChars = " \u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+  const spark = buckets.map((v, i) => {
+    const level = Math.round(v / maxBucket * 8);
+    return (failBuckets[i] > 0 ? C.red : C.green) + sparkChars[level] + C.reset;
+  }).join("");
+  const traceGroups = groupByTraceId(allTraces);
+  const distributedTraces = [];
+  for (const [_traceId, graphs] of traceGroups) {
+    if (graphs.length > 1) {
+      try {
+        distributedTraces.push(stitchTrace(graphs));
+      } catch {
+      }
+    }
+  }
+  distributedTraces.sort((a, b) => b.startTime - a.startTime);
+  const upSec = Math.floor((Date.now() - sessionStart) / 1e3);
+  const upMin = Math.floor(upSec / 60);
+  const upStr = upMin > 0 ? `${upMin}m ${upSec % 60}s` : `${upSec}s`;
+  const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+  process.stdout.write("\x1B[2J\x1B[H");
+  console.log(`${C.bold}${C.cyan}\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557${C.reset}`);
+  console.log(`${C.bold}${C.cyan}\u2551${C.reset}  ${C.bold}${C.white}AGENTFLOW LIVE${C.reset}                               ${C.green}\u25CF LIVE${C.reset}  ${C.dim}${time}${C.reset}  ${C.bold}${C.cyan}\u2551${C.reset}`);
+  const metaLine = `Refresh: ${config.refreshMs / 1e3}s \xB7 Up: ${upStr}`;
+  const pad1 = Math.max(0, 64 - metaLine.length);
+  console.log(`${C.bold}${C.cyan}\u2551${C.reset}  ${C.dim}${metaLine}${C.reset}${" ".repeat(pad1)}${C.bold}${C.cyan}\u2551${C.reset}`);
+  console.log(`${C.bold}${C.cyan}\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D${C.reset}`);
+  const sc = totFail === 0 ? C.green : C.yellow;
+  console.log("");
+  console.log(`  ${C.bold}Agents${C.reset} ${sc}${agentList.length}${C.reset}    ${C.bold}Executions${C.reset} ${sc}${totExec}${C.reset}    ${C.bold}Success${C.reset} ${sc}${sysRate}%${C.reset}    ${C.bold}Traces${C.reset} ${sc}${files.length}${C.reset}    ${C.bold}New${C.reset} ${C.yellow}+${newExecCount}${C.reset}    ${C.bold}Distributed${C.reset} ${C.magenta}${distributedTraces.length}${C.reset}`);
+  console.log("");
+  console.log(`  ${C.bold}Activity (1h)${C.reset}  ${spark}  ${C.dim}\u2190 now${C.reset}`);
+  console.log("");
+  console.log(`  ${C.bold}${C.under}Agent                          Runs   OK  Fail  Rate     Last Active${C.reset}`);
+  for (const ag of agentList) {
+    const rate = (ag.ok / ag.total * 100).toFixed(0);
+    const lastTime = new Date(ag.lastTs).toLocaleTimeString();
+    const isRecent = Date.now() - ag.lastTs < 3e5;
+    let status;
+    if (ag.fail > 0) status = `${C.red}\u25CF${C.reset}`;
+    else if (isRecent) status = `${C.green}\u25CF${C.reset}`;
+    else status = `${C.dim}\u25CB${C.reset}`;
+    const name = ag.name.padEnd(28);
+    const runs = String(ag.total).padStart(5);
+    const ok = String(ag.ok).padStart(5);
+    const fail = ag.fail > 0 ? `${C.red}${String(ag.fail).padStart(4)}${C.reset}` : String(ag.fail).padStart(4);
+    const rateStr = (rate + "%").padStart(5);
+    const activeStr = isRecent ? `${C.green}${lastTime}${C.reset}` : `${C.dim}${lastTime}${C.reset}`;
+    console.log(`  ${status} ${name}${runs}${ok}${fail}  ${rateStr}     ${activeStr}`);
+  }
+  if (distributedTraces.length > 0) {
+    console.log("");
+    console.log(`  ${C.bold}${C.under}Distributed Traces (multi-agent workflows)${C.reset}`);
+    for (const dt of distributedTraces.slice(0, 5)) {
+      const traceTime = new Date(dt.startTime).toLocaleTimeString();
+      const statusIcon = dt.status === "completed" ? `${C.green}\u2713${C.reset}` : dt.status === "failed" ? `${C.red}\u2717${C.reset}` : `${C.yellow}\u23F3${C.reset}`;
+      const dur = dt.endTime ? `${dt.endTime - dt.startTime}ms` : "running";
+      const tid = dt.traceId.slice(0, 8);
+      console.log(`  ${statusIcon}  ${C.magenta}trace:${tid}${C.reset}  ${C.dim}${traceTime}${C.reset}  ${C.dim}${dur}${C.reset}  ${C.dim}(${dt.graphs.size} agents)${C.reset}`);
+      const tree = getTraceTree(dt);
+      for (let i = 0; i < tree.length; i++) {
+        const g = tree[i];
+        const depth = getDistributedDepth(dt, g.spanId);
+        const indent = "     " + "\u2502  ".repeat(Math.max(0, depth - 1));
+        const isLast = i === tree.length - 1 || getDistributedDepth(dt, tree[i + 1]?.spanId) <= depth;
+        const connector = depth === 0 ? "  " : isLast ? "\u2514\u2500 " : "\u251C\u2500 ";
+        const gStatus = g.status === "completed" ? `${C.green}\u2713${C.reset}` : g.status === "failed" ? `${C.red}\u2717${C.reset}` : `${C.yellow}\u23F3${C.reset}`;
+        const gDur = g.endTime ? `${g.endTime - g.startTime}ms` : "running";
+        console.log(`${indent}${connector}${gStatus} ${C.bold}${g.agentId}${C.reset} ${C.dim}[${g.trigger}] ${gDur}${C.reset}`);
+      }
+    }
+  }
+  console.log("");
+  console.log(`  ${C.bold}${C.under}Recent Executions${C.reset}`);
+  for (const ex of recent.slice(0, 8)) {
+    const icon = ex.success ? `${C.green}\u2713${C.reset}` : `${C.red}\u2717${C.reset}`;
+    const t = new Date(ex.ts).toLocaleTimeString();
+    const agent = ex.agentId.padEnd(28);
+    const age = Math.floor((Date.now() - ex.ts) / 1e3);
+    const ageStr = age < 60 ? age + "s ago" : Math.floor(age / 60) + "m ago";
+    const traceTag = ex.traceId ? ` ${C.magenta}\u29EB${C.reset}` : "";
+    console.log(`  ${icon}  ${agent} ${C.dim}${t}  ${ageStr.padStart(8)}  ${ex.nodes} nodes${C.reset}${traceTag}`);
+  }
+  if (files.length === 0) {
+    console.log(`  ${C.dim}No trace files found. Waiting for traces in:${C.reset}`);
+    console.log(`  ${C.dim}${config.tracesDir}${C.reset}`);
+  }
+  console.log("");
+  console.log(`  ${C.dim}Watching: ${config.tracesDir}${C.reset}`);
+  console.log(`  ${C.dim}Press Ctrl+C to exit${C.reset}`);
+}
+function startLive(argv) {
+  const config = parseArgs(argv);
+  if (!(0, import_node_fs2.existsSync)(config.tracesDir)) {
+    console.error(`Traces directory does not exist: ${config.tracesDir}`);
+    console.error("Create it or specify a different path: agentflow live <traces-dir>");
+    process.exit(1);
+  }
+  render(config);
+  let debounce = null;
+  try {
+    (0, import_node_fs2.watch)(config.tracesDir, () => {
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(() => render(config), 500);
+    });
+  } catch {
+  }
+  setInterval(() => render(config), config.refreshMs);
+  process.on("SIGINT", () => {
+    console.log("\n" + C.dim + "Monitor stopped." + C.reset);
+    process.exit(0);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createGraphBuilder,
@@ -654,7 +970,10 @@ function getStats(graph) {
   getStats,
   getSubtree,
   getTraceTree,
+  graphToJson,
   groupByTraceId,
+  loadGraph,
   runTraced,
+  startLive,
   stitchTrace
 });

package/dist/index.d.cts

@@ -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 };