agentflow-core 0.1.3 → 0.2.0

package/dist/cli.cjs

@@ -235,6 +235,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
 function globToRegex(pattern) {
   const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
@@ -267,27 +319,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,
@@ -404,8 +435,442 @@ async function runTraced(config) {
   };
 }
 
-// src/cli.ts
+// src/live.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+
+// src/graph-query.ts
+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 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
+  };
+}
+
+// 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);
+  });
+}
+
+// src/cli.ts
+function printHelp() {
+  console.log(`
+AgentFlow CLI \u2014 execution tracing and live monitoring for AI agent systems.
+
+Usage:
+  agentflow <command> [options]
+
+Commands:
+  run   [options] -- <cmd>     Wrap a command with automatic execution tracing
+  live  [traces-dir] [options] Real-time terminal monitor for trace files
+
+Run \`agentflow <command> --help\` for command-specific options.
+
+Examples:
+  agentflow run --traces-dir ./traces -- python -m myagent process
+  agentflow live ./traces
+  agentflow live ./traces --refresh 5
+`.trim());
+}
+function parseRunArgs(argv) {
   const result = {
     tracesDir: "./traces",
     watchDirs: [],
@@ -463,9 +928,9 @@ function parseArgs(argv) {
   result.command = commandArgs;
   return result;
 }
-function printUsage() {
+function printRunUsage() {
   console.log(`
-AgentFlow CLI \u2014 Wrap any command with automatic execution tracing.
+AgentFlow Run \u2014 wrap any command with automatic execution tracing.
 
 Usage:
   agentflow run [options] -- <command>
@@ -479,21 +944,20 @@ Options:
   --help                  Show this help message
 
 Examples:
-  agentflow run -- python -m alfred process
-  agentflow run --watch-dir /home/trader/.alfred/data -- python -m alfred process
-  agentflow run --traces-dir ./my-traces --agent-id alfred -- node worker.js
+  agentflow run -- python -m myagent process
+  agentflow run --watch-dir ./data -- python worker.py
+  agentflow run --traces-dir ./my-traces --agent-id recon -- node agent.js
 `.trim());
 }
-async function main() {
-  const argv = process.argv.slice(2);
-  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-    printUsage();
+async function runCommand(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printRunUsage();
     process.exit(0);
   }
-  const parsed = parseArgs(argv);
+  const parsed = parseRunArgs(argv);
   if (parsed.command.length === 0) {
     console.error("Error: No command specified. Use -- to separate agentflow flags from the command.");
-    console.error("Example: agentflow run -- python -m alfred process");
+    console.error("Example: agentflow run -- python -m myagent process");
     process.exit(1);
   }
   const commandStr = parsed.command.join(" ");
@@ -539,4 +1003,28 @@ async function main() {
     process.exit(1);
   }
 }
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] !== "run" && argv[0] !== "live" && (argv.includes("--help") || argv.includes("-h"))) {
+    printHelp();
+    process.exit(0);
+  }
+  const subcommand = argv[0];
+  switch (subcommand) {
+    case "run":
+      await runCommand(argv);
+      break;
+    case "live":
+      startLive(argv);
+      break;
+    default:
+      if (!subcommand?.startsWith("-")) {
+        startLive(["live", ...argv]);
+      } else {
+        printHelp();
+        process.exit(1);
+      }
+      break;
+  }
+}
 main();

package/dist/cli.js

@@ -1,11 +1,31 @@
 #!/usr/bin/env node
 import {
-  runTraced
-} from "./chunk-DGLK6IBP.js";
+  runTraced,
+  startLive
+} from "./chunk-TRKBUPIN.js";
 
 // src/cli.ts
 import { basename } from "path";
-function parseArgs(argv) {
+function printHelp() {
+  console.log(`
+AgentFlow CLI \u2014 execution tracing and live monitoring for AI agent systems.
+
+Usage:
+  agentflow <command> [options]
+
+Commands:
+  run   [options] -- <cmd>     Wrap a command with automatic execution tracing
+  live  [traces-dir] [options] Real-time terminal monitor for trace files
+
+Run \`agentflow <command> --help\` for command-specific options.
+
+Examples:
+  agentflow run --traces-dir ./traces -- python -m myagent process
+  agentflow live ./traces
+  agentflow live ./traces --refresh 5
+`.trim());
+}
+function parseRunArgs(argv) {
   const result = {
     tracesDir: "./traces",
     watchDirs: [],
@@ -63,9 +83,9 @@ function parseArgs(argv) {
   result.command = commandArgs;
   return result;
 }
-function printUsage() {
+function printRunUsage() {
   console.log(`
-AgentFlow CLI \u2014 Wrap any command with automatic execution tracing.
+AgentFlow Run \u2014 wrap any command with automatic execution tracing.
 
 Usage:
   agentflow run [options] -- <command>
@@ -79,21 +99,20 @@ Options:
   --help                  Show this help message
 
 Examples:
-  agentflow run -- python -m alfred process
-  agentflow run --watch-dir /home/trader/.alfred/data -- python -m alfred process
-  agentflow run --traces-dir ./my-traces --agent-id alfred -- node worker.js
+  agentflow run -- python -m myagent process
+  agentflow run --watch-dir ./data -- python worker.py
+  agentflow run --traces-dir ./my-traces --agent-id recon -- node agent.js
 `.trim());
 }
-async function main() {
-  const argv = process.argv.slice(2);
-  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-    printUsage();
+async function runCommand(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printRunUsage();
     process.exit(0);
   }
-  const parsed = parseArgs(argv);
+  const parsed = parseRunArgs(argv);
   if (parsed.command.length === 0) {
     console.error("Error: No command specified. Use -- to separate agentflow flags from the command.");
-    console.error("Example: agentflow run -- python -m alfred process");
+    console.error("Example: agentflow run -- python -m myagent process");
     process.exit(1);
   }
   const commandStr = parsed.command.join(" ");
@@ -139,4 +158,28 @@ async function main() {
     process.exit(1);
   }
 }
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] !== "run" && argv[0] !== "live" && (argv.includes("--help") || argv.includes("-h"))) {
+    printHelp();
+    process.exit(0);
+  }
+  const subcommand = argv[0];
+  switch (subcommand) {
+    case "run":
+      await runCommand(argv);
+      break;
+    case "live":
+      startLive(argv);
+      break;
+    default:
+      if (!subcommand?.startsWith("-")) {
+        startLive(["live", ...argv]);
+      } else {
+        printHelp();
+        process.exit(1);
+      }
+      break;
+  }
+}
 main();