agentflow-core 0.1.4 → 0.2.1

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   groupByTraceId: () => groupByTraceId,
   loadGraph: () => loadGraph,
   runTraced: () => runTraced,
+  startLive: () => startLive,
   stitchTrace: () => stitchTrace
 });
 module.exports = __toCommonJS(index_exports);
@@ -470,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) {
@@ -672,6 +613,520 @@ 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: ".", refreshMs: 3e3, recursive: false };
+  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 v = parseInt(args[i] ?? "", 10);
+      if (!isNaN(v) && v > 0) config.refreshMs = v * 1e3;
+      i++;
+    } else if (arg === "--recursive" || arg === "-R") {
+      config.recursive = true;
+      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.
+
+Auto-detects agent traces, state files, job schedulers, and session logs
+from any JSON/JSONL files in the watched directory.
+
+Usage:
+  agentflow live [directory] [options]
+
+Arguments:
+  directory               Directory to watch (default: current directory)
+
+Options:
+  -r, --refresh <secs>    Refresh interval in seconds (default: 3)
+  -R, --recursive         Scan subdirectories (1 level deep)
+  -h, --help              Show this help message
+
+Examples:
+  agentflow live ./data
+  agentflow live ./traces --refresh 5
+  agentflow live /var/lib/myagent -R
+`.trim());
+}
+function scanFiles(dir, recursive) {
+  const results = [];
+  function scanDir(d) {
+    try {
+      for (const f of (0, import_node_fs2.readdirSync)(d)) {
+        if (f.startsWith(".")) continue;
+        const fp = (0, import_node_path2.join)(d, f);
+        let stat;
+        try {
+          stat = (0, import_node_fs2.statSync)(fp);
+        } catch {
+          continue;
+        }
+        if (stat.isDirectory() && recursive && d === dir) {
+          scanDir(fp);
+          continue;
+        }
+        if (!stat.isFile()) continue;
+        if (f.endsWith(".json")) {
+          results.push({ filename: f, path: fp, mtime: stat.mtime.getTime(), ext: ".json" });
+        } else if (f.endsWith(".jsonl")) {
+          results.push({ filename: f, path: fp, mtime: stat.mtime.getTime(), ext: ".jsonl" });
+        }
+      }
+    } catch {
+    }
+  }
+  scanDir(dir);
+  results.sort((a, b) => b.mtime - a.mtime);
+  return results;
+}
+function safeReadJson(fp) {
+  try {
+    return JSON.parse((0, import_node_fs2.readFileSync)(fp, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function nameFromFile(filename) {
+  return (0, import_node_path2.basename)(filename).replace(/\.(json|jsonl)$/, "").replace(/-state$/, "");
+}
+function normalizeStatus(val) {
+  if (typeof val !== "string") return "unknown";
+  const s = val.toLowerCase();
+  if (["ok", "success", "completed", "done", "passed", "healthy", "good"].includes(s)) return "ok";
+  if (["error", "failed", "failure", "crashed", "unhealthy", "bad", "timeout"].includes(s)) return "error";
+  if (["running", "active", "in_progress", "started", "pending", "processing"].includes(s)) return "running";
+  return "unknown";
+}
+function findStatus(obj) {
+  for (const key of ["status", "state", "lastRunStatus", "lastStatus", "health", "result"]) {
+    if (key in obj) {
+      const val = obj[key];
+      if (typeof val === "string") return normalizeStatus(val);
+      if (typeof val === "object" && val !== null && "status" in val) {
+        return normalizeStatus(val.status);
+      }
+    }
+  }
+  return "unknown";
+}
+function findTimestamp(obj) {
+  for (const key of ["ts", "timestamp", "lastRunAtMs", "last_run", "lastExecution", "updated_at", "started_at", "endTime", "startTime"]) {
+    const val = obj[key];
+    if (typeof val === "number") return val > 1e12 ? val : val * 1e3;
+    if (typeof val === "string") {
+      const d = Date.parse(val);
+      if (!isNaN(d)) return d;
+    }
+  }
+  return 0;
+}
+function extractDetail(obj) {
+  const parts = [];
+  for (const key of ["summary", "message", "description", "lastError", "error", "name", "jobId", "id"]) {
+    const val = obj[key];
+    if (typeof val === "string" && val.length > 0 && val.length < 200) {
+      parts.push(val.slice(0, 80));
+      break;
+    }
+  }
+  for (const key of ["totalExecutions", "runs", "count", "processed", "consecutiveErrors"]) {
+    const val = obj[key];
+    if (typeof val === "number") {
+      parts.push(`${key}: ${val}`);
+      break;
+    }
+  }
+  return parts.join(" | ") || "";
+}
+function tryLoadTrace(fp, raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const obj = raw;
+  if (!("nodes" in obj)) return null;
+  if (!("agentId" in obj) && !("rootNodeId" in obj) && !("rootId" in obj)) return null;
+  try {
+    return loadGraph(obj);
+  } catch {
+    return null;
+  }
+}
+function processJsonFile(file) {
+  const raw = safeReadJson(file.path);
+  if (raw === null) return [];
+  const records = [];
+  const trace = tryLoadTrace(file.path, raw);
+  if (trace) {
+    try {
+      const fails = getFailures(trace);
+      const hung = getHungNodes(trace);
+      const stats = getStats(trace);
+      records.push({
+        id: trace.agentId,
+        source: "trace",
+        status: fails.length === 0 && hung.length === 0 ? "ok" : "error",
+        lastActive: file.mtime,
+        detail: `${stats.totalNodes} nodes [${trace.trigger}]`,
+        file: file.filename,
+        traceData: trace
+      });
+    } catch {
+    }
+    return records;
+  }
+  if (typeof raw !== "object") return records;
+  const arr = Array.isArray(raw) ? raw : Array.isArray(raw.jobs) ? raw.jobs : Array.isArray(raw.tasks) ? raw.tasks : Array.isArray(raw.items) ? raw.items : null;
+  if (arr && arr.length > 0 && typeof arr[0] === "object" && arr[0] !== null) {
+    for (const item of arr.slice(0, 50)) {
+      const name = item.name ?? item.id ?? item.jobId ?? item.agentId;
+      if (!name) continue;
+      const state = typeof item.state === "object" && item.state !== null ? item.state : item;
+      const status2 = findStatus(state);
+      const ts2 = findTimestamp(state) || file.mtime;
+      const detail2 = extractDetail(state);
+      records.push({ id: String(name), source: "jobs", status: status2, lastActive: ts2, detail: detail2, file: file.filename });
+    }
+    return records;
+  }
+  const obj = raw;
+  for (const containerKey of ["tools", "workers", "services", "agents", "daemons"]) {
+    const container = obj[containerKey];
+    if (typeof container === "object" && container !== null && !Array.isArray(container)) {
+      for (const [name, info] of Object.entries(container)) {
+        if (typeof info !== "object" || info === null) continue;
+        const w = info;
+        const status2 = findStatus(w);
+        const ts2 = findTimestamp(w) || findTimestamp(obj) || file.mtime;
+        const pid = w.pid;
+        const detail2 = pid ? `pid: ${pid}` : extractDetail(w);
+        records.push({ id: name, source: "workers", status: status2, lastActive: ts2, detail: detail2, file: file.filename });
+      }
+      return records;
+    }
+  }
+  const status = findStatus(obj);
+  const ts = findTimestamp(obj) || file.mtime;
+  const detail = extractDetail(obj);
+  records.push({ id: nameFromFile(file.filename), source: "state", status, lastActive: ts, detail, file: file.filename });
+  return records;
+}
+function processJsonlFile(file) {
+  try {
+    const content = (0, import_node_fs2.readFileSync)(file.path, "utf8").trim();
+    if (!content) return [];
+    const lines = content.split("\n");
+    const lastLine = lines[lines.length - 1];
+    const obj = JSON.parse(lastLine);
+    const name = obj.jobId ?? obj.agentId ?? obj.name ?? obj.id ?? nameFromFile(file.filename);
+    const status = findStatus(obj);
+    const ts = findTimestamp(obj) || file.mtime;
+    const action = obj.action;
+    const detail = action ? `${action} (${lines.length} entries)` : `${lines.length} entries`;
+    return [{ id: String(name), source: "session", status, lastActive: ts, detail, file: file.filename }];
+  } catch {
+    return [];
+  }
+}
+var prevFileCount = 0;
+var newExecCount = 0;
+var sessionStart = Date.now();
+function render(config) {
+  const files = scanFiles(config.tracesDir, config.recursive);
+  if (files.length > prevFileCount && prevFileCount > 0) {
+    newExecCount += files.length - prevFileCount;
+  }
+  prevFileCount = files.length;
+  const allRecords = [];
+  const allTraces = [];
+  for (const f of files.slice(0, 300)) {
+    const records = f.ext === ".jsonl" ? processJsonlFile(f) : processJsonFile(f);
+    for (const r of records) {
+      allRecords.push(r);
+      if (r.traceData) allTraces.push(r.traceData);
+    }
+  }
+  const agents = {};
+  for (const r of allRecords) {
+    if (!agents[r.id]) {
+      agents[r.id] = { name: r.id, total: 0, ok: 0, fail: 0, running: 0, lastTs: 0, source: r.source, detail: "" };
+    }
+    const ag = agents[r.id];
+    ag.total++;
+    if (r.status === "ok") ag.ok++;
+    else if (r.status === "error") ag.fail++;
+    else if (r.status === "running") ag.running++;
+    if (r.lastActive > ag.lastTs) {
+      ag.lastTs = r.lastActive;
+      ag.detail = r.detail;
+      ag.source = r.source;
+    }
+  }
+  const agentList = Object.values(agents).sort((a, b) => b.lastTs - a.lastTs);
+  const totExec = agentList.reduce((s, a) => s + a.total, 0);
+  const totFail = agentList.reduce((s, a) => s + a.fail, 0);
+  const totRunning = agentList.reduce((s, a) => s + a.running, 0);
+  const sysRate = totExec > 0 ? ((totExec - totFail) / totExec * 100).toFixed(1) : "100.0";
+  const now = Date.now();
+  const buckets = new Array(12).fill(0);
+  const failBuckets = new Array(12).fill(0);
+  for (const r of allRecords) {
+    const age = now - r.lastActive;
+    if (age > 36e5 || age < 0) continue;
+    const idx = 11 - Math.floor(age / 3e5);
+    if (idx >= 0 && idx < 12) {
+      buckets[idx]++;
+      if (r.status === "error") 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 distributedTraces = [];
+  if (allTraces.length > 1) {
+    const traceGroups = groupByTraceId(allTraces);
+    for (const [_tid, 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();
+  const sourceTag = (s) => {
+    switch (s) {
+      case "trace":
+        return `${C.cyan}trace${C.reset}`;
+      case "jobs":
+        return `${C.blue}job${C.reset}`;
+      case "workers":
+        return `${C.magenta}worker${C.reset}`;
+      case "session":
+        return `${C.yellow}session${C.reset}`;
+      case "state":
+        return `${C.dim}state${C.reset}`;
+    }
+  };
+  process.stdout.write("\x1B[2J\x1B[H");
+  console.log(`${C.bold}${C.cyan}\u2554${"\u2550".repeat(70)}\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} \xB7 Files: ${files.length}`;
+  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".repeat(70)}\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}Records${C.reset} ${sc}${totExec}${C.reset}    ${C.bold}Success${C.reset} ${sc}${sysRate}%${C.reset}    ${C.bold}Running${C.reset} ${C.green}${totRunning}${C.reset}    ${C.bold}Errors${C.reset} ${totFail > 0 ? C.red : C.dim}${totFail}${C.reset}    ${C.bold}New${C.reset} ${C.yellow}+${newExecCount}${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                     Type     Status   Last Active  Detail${C.reset}`);
+  for (const ag of agentList.slice(0, 30)) {
+    const lastTime = ag.lastTs > 0 ? new Date(ag.lastTs).toLocaleTimeString() : "n/a";
+    const isRecent = Date.now() - ag.lastTs < 3e5;
+    let statusIcon;
+    let statusText;
+    if (ag.fail > 0 && ag.ok === 0 && ag.running === 0) {
+      statusIcon = `${C.red}\u25CF${C.reset}`;
+      statusText = `${C.red}error${C.reset}`;
+    } else if (ag.running > 0) {
+      statusIcon = `${C.green}\u25CF${C.reset}`;
+      statusText = `${C.green}running${C.reset}`;
+    } else if (ag.fail > 0) {
+      statusIcon = `${C.yellow}\u25CF${C.reset}`;
+      statusText = `${C.yellow}${ag.ok}ok/${ag.fail}err${C.reset}`;
+    } else if (ag.ok > 0) {
+      statusIcon = isRecent ? `${C.green}\u25CF${C.reset}` : `${C.dim}\u25CB${C.reset}`;
+      statusText = ag.total > 1 ? `${C.green}${ag.ok}/${ag.total}${C.reset}` : `${C.green}ok${C.reset}`;
+    } else {
+      statusIcon = `${C.dim}\u25CB${C.reset}`;
+      statusText = `${C.dim}idle${C.reset}`;
+    }
+    const name = ag.name.length > 23 ? ag.name.slice(0, 22) + "\u2026" : ag.name.padEnd(23);
+    const src = sourceTag(ag.source).padEnd(16);
+    const active = isRecent ? `${C.green}${lastTime}${C.reset}` : `${C.dim}${lastTime}${C.reset}`;
+    const detail = ag.detail.length > 30 ? ag.detail.slice(0, 29) + "\u2026" : ag.detail;
+    console.log(`  ${statusIcon} ${name}  ${src}  ${statusText.padEnd(18)}  ${active.padEnd(20)}  ${C.dim}${detail}${C.reset}`);
+  }
+  if (distributedTraces.length > 0) {
+    console.log("");
+    console.log(`  ${C.bold}${C.under}Distributed Traces${C.reset}`);
+    for (const dt of distributedTraces.slice(0, 3)) {
+      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}  ${dur}  (${dt.graphs.size} agents)${C.reset}`);
+      const tree = getTraceTree(dt);
+      for (let i = 0; i < Math.min(tree.length, 6); i++) {
+        const g = tree[i];
+        const depth = getDistDepth(dt, g.spanId);
+        const indent = "     " + "\u2502  ".repeat(Math.max(0, depth - 1));
+        const isLast = i === tree.length - 1 || getDistDepth(dt, tree[i + 1]?.spanId) <= depth;
+        const conn = depth === 0 ? "  " : isLast ? "\u2514\u2500 " : "\u251C\u2500 ";
+        const gs = g.status === "completed" ? `${C.green}\u2713${C.reset}` : g.status === "failed" ? `${C.red}\u2717${C.reset}` : `${C.yellow}\u23F3${C.reset}`;
+        const gd = g.endTime ? `${g.endTime - g.startTime}ms` : "running";
+        console.log(`${indent}${conn}${gs} ${C.bold}${g.agentId}${C.reset} ${C.dim}[${g.trigger}] ${gd}${C.reset}`);
+      }
+    }
+  }
+  const recentRecords = allRecords.filter((r) => r.lastActive > 0).sort((a, b) => b.lastActive - a.lastActive).slice(0, 8);
+  if (recentRecords.length > 0) {
+    console.log("");
+    console.log(`  ${C.bold}${C.under}Recent Activity${C.reset}`);
+    for (const r of recentRecords) {
+      const icon = r.status === "ok" ? `${C.green}\u2713${C.reset}` : r.status === "error" ? `${C.red}\u2717${C.reset}` : r.status === "running" ? `${C.green}\u25B6${C.reset}` : `${C.dim}\u25CB${C.reset}`;
+      const t = new Date(r.lastActive).toLocaleTimeString();
+      const agent = r.id.length > 26 ? r.id.slice(0, 25) + "\u2026" : r.id.padEnd(26);
+      const age = Math.floor((Date.now() - r.lastActive) / 1e3);
+      const ageStr = age < 60 ? age + "s ago" : age < 3600 ? Math.floor(age / 60) + "m ago" : Math.floor(age / 3600) + "h ago";
+      const detail = r.detail.length > 25 ? r.detail.slice(0, 24) + "\u2026" : r.detail;
+      console.log(`  ${icon}  ${agent} ${C.dim}${t}  ${ageStr.padStart(8)}${C.reset}  ${C.dim}${detail}${C.reset}`);
+    }
+  }
+  if (files.length === 0) {
+    console.log("");
+    console.log(`  ${C.dim}No JSON/JSONL files found. Waiting for data 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 getDistDepth(dt, spanId) {
+  if (!spanId) return 0;
+  const g = dt.graphs.get(spanId);
+  if (!g || !g.parentSpanId) return 0;
+  return 1 + getDistDepth(dt, g.parentSpanId);
+}
+function startLive(argv) {
+  const config = parseArgs(argv);
+  if (!(0, import_node_fs2.existsSync)(config.tracesDir)) {
+    console.error(`Directory does not exist: ${config.tracesDir}`);
+    console.error("Specify a directory containing JSON/JSONL files: agentflow live <dir>");
+    process.exit(1);
+  }
+  render(config);
+  let debounce = null;
+  try {
+    (0, import_node_fs2.watch)(config.tracesDir, { recursive: config.recursive }, () => {
+      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,
@@ -691,5 +1146,6 @@ function getStats(graph) {
   groupByTraceId,
   loadGraph,
   runTraced,
+  startLive,
   stitchTrace
 });

package/dist/index.d.cts

@@ -377,6 +377,24 @@ interface RunResult {
  */
 declare function runTraced(config: RunConfig): Promise<RunResult>;
 
+/**
+ * AgentFlow Live Monitor — real-time terminal dashboard for any agent system.
+ *
+ * Auto-detects and displays data from any JSON/JSONL files in the watched
+ * directory. Works with agentflow traces, generic state files, job
+ * schedulers, session logs — no configuration needed.
+ *
+ * File detection:
+ *   .json with `nodes` + `agentId`          → AgentFlow trace (full analysis)
+ *   .json with array of objects with `state` → Job/task list (per-item status)
+ *   .json with `status`/`pid`/`tools`        → Process/worker state
+ *   .json with any other structure            → Generic state (mtime-based)
+ *   .jsonl                                    → Session log (last entry status)
+ *
+ * @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[];
@@ -497,4 +515,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, graphToJson, groupByTraceId, loadGraph, 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.d.ts

@@ -377,6 +377,24 @@ interface RunResult {
  */
 declare function runTraced(config: RunConfig): Promise<RunResult>;
 
+/**
+ * AgentFlow Live Monitor — real-time terminal dashboard for any agent system.
+ *
+ * Auto-detects and displays data from any JSON/JSONL files in the watched
+ * directory. Works with agentflow traces, generic state files, job
+ * schedulers, session logs — no configuration needed.
+ *
+ * File detection:
+ *   .json with `nodes` + `agentId`          → AgentFlow trace (full analysis)
+ *   .json with array of objects with `state` → Job/task list (per-item status)
+ *   .json with `status`/`pid`/`tools`        → Process/worker state
+ *   .json with any other structure            → Generic state (mtime-based)
+ *   .jsonl                                    → Session log (last entry status)
+ *
+ * @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[];
@@ -497,4 +515,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, graphToJson, groupByTraceId, loadGraph, 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 };