agentflow-core 0.3.3 → 0.4.0

package/dist/cli.js

@@ -1,14 +1,211 @@
 #!/usr/bin/env node
 import {
+  createTraceStore,
   runTraced,
   startLive,
-  startWatch
-} from "./chunk-M5CGDXAO.js";
+  startWatch,
+  toAsciiTree,
+  toTimeline
+} from "./chunk-DHCTDCDI.js";
+import "./chunk-DY7YHFIB.js";
 
 // src/cli.ts
 import { basename } from "path";
+
+// src/trace-cli.ts
+import { resolve } from "path";
+function getTracesDir(argv) {
+  const idx = argv.indexOf("--traces-dir");
+  if (idx !== -1 && argv[idx + 1]) {
+    return resolve(argv[idx + 1]);
+  }
+  return resolve("./traces");
+}
+function getFlag(argv, name) {
+  const idx = argv.indexOf(name);
+  if (idx !== -1 && argv[idx + 1]) {
+    return argv[idx + 1];
+  }
+  return void 0;
+}
+function printTraceHelp() {
+  console.log(
+    `
+AgentFlow Trace \u2014 inspect saved execution traces.
+
+Usage:
+  agentflow trace <command> [options]
+
+Commands:
+  list [--status <status>] [--limit <n>]    List saved traces
+  show <graph-id>                           Show trace as ASCII tree
+  timeline <graph-id>                       Show trace as timeline waterfall
+  stuck                                     Show all stuck/hung/timeout spans
+  loops [--threshold <n>]                   Detect reasoning loops
+
+Options:
+  --traces-dir <path>   Directory containing trace files (default: ./traces)
+
+Examples:
+  agentflow trace list --status failed --limit 10
+  agentflow trace show abc-123
+  agentflow trace timeline abc-123
+  agentflow trace stuck
+  agentflow trace loops --threshold 10
+`.trim()
+  );
+}
+async function traceList(argv) {
+  const dir = getTracesDir(argv);
+  const store = createTraceStore(dir);
+  const status = getFlag(argv, "--status");
+  const limitStr = getFlag(argv, "--limit");
+  const limit = limitStr ? Number.parseInt(limitStr, 10) : void 0;
+  const graphs = await store.list({ status, limit });
+  if (graphs.length === 0) {
+    console.log("No traces found.");
+    return;
+  }
+  console.log(`Found ${graphs.length} trace(s) in ${dir}:
+`);
+  for (const g of graphs) {
+    const duration = g.endTime ? `${((g.endTime - g.startTime) / 1e3).toFixed(1)}s` : "running";
+    const date = new Date(g.startTime).toISOString().replace("T", " ").replace(/\.\d+Z$/, "");
+    const icon = g.status === "completed" ? "\u2713" : g.status === "failed" ? "\u2717" : "\u231B";
+    console.log(
+      `  ${icon} ${g.id}  ${g.status.padEnd(10)} ${duration.padEnd(8)} ${date}  ${g.agentId}`
+    );
+  }
+}
+async function traceShow(argv) {
+  const dir = getTracesDir(argv);
+  const store = createTraceStore(dir);
+  const showIdx = argv.indexOf("show");
+  const graphId = showIdx !== -1 ? argv[showIdx + 1] : void 0;
+  if (!graphId || graphId.startsWith("--")) {
+    console.error("Usage: agentflow trace show <graph-id>");
+    process.exit(1);
+  }
+  let graph = await store.get(graphId);
+  if (!graph) {
+    const { readFile } = await import("fs/promises");
+    const { join } = await import("path");
+    const fname = graphId.endsWith(".json") ? graphId : `${graphId}.json`;
+    try {
+      const { loadGraph } = await import("./loader-LYRR6LMM.js");
+      const content = await readFile(join(dir, fname), "utf-8");
+      graph = loadGraph(content);
+    } catch {
+    }
+  }
+  if (!graph) {
+    console.error(`Trace "${graphId}" not found in ${dir}`);
+    process.exit(1);
+  }
+  console.log(`Trace: ${graph.id} (${graph.status})
+`);
+  console.log(toAsciiTree(graph));
+}
+async function traceTimeline(argv) {
+  const dir = getTracesDir(argv);
+  const store = createTraceStore(dir);
+  const timelineIdx = argv.indexOf("timeline");
+  const graphId = timelineIdx !== -1 ? argv[timelineIdx + 1] : void 0;
+  if (!graphId || graphId.startsWith("--")) {
+    console.error("Usage: agentflow trace timeline <graph-id>");
+    process.exit(1);
+  }
+  let graph = await store.get(graphId);
+  if (!graph) {
+    const { readFile } = await import("fs/promises");
+    const { join } = await import("path");
+    const fname = graphId.endsWith(".json") ? graphId : `${graphId}.json`;
+    try {
+      const { loadGraph } = await import("./loader-LYRR6LMM.js");
+      const content = await readFile(join(dir, fname), "utf-8");
+      graph = loadGraph(content);
+    } catch {
+    }
+  }
+  if (!graph) {
+    console.error(`Trace "${graphId}" not found in ${dir}`);
+    process.exit(1);
+  }
+  console.log(`Trace: ${graph.id} (${graph.status})
+`);
+  console.log(toTimeline(graph));
+}
+async function traceStuck(argv) {
+  const dir = getTracesDir(argv);
+  const store = createTraceStore(dir);
+  const stuck = await store.getStuckSpans();
+  if (stuck.length === 0) {
+    console.log("No stuck spans found.");
+    return;
+  }
+  console.log(`Found ${stuck.length} stuck span(s):
+`);
+  for (const node of stuck) {
+    const elapsed = Date.now() - node.startTime;
+    const icon = node.status === "timeout" ? "\u231B" : node.status === "hung" ? "\u231B" : "\u231B";
+    console.log(
+      `  ${icon} ${node.id}  ${node.type.padEnd(10)} ${node.name.padEnd(20)} ${node.status.padEnd(8)} ${(elapsed / 1e3).toFixed(0)}s`
+    );
+  }
+}
+async function traceLoops(argv) {
+  const dir = getTracesDir(argv);
+  const store = createTraceStore(dir);
+  const thresholdStr = getFlag(argv, "--threshold");
+  const threshold = thresholdStr ? Number.parseInt(thresholdStr, 10) : void 0;
+  const loops = await store.getReasoningLoops(threshold);
+  if (loops.length === 0) {
+    console.log("No reasoning loops detected.");
+    return;
+  }
+  console.log(`Found reasoning loops in ${loops.length} trace(s):
+`);
+  for (const { graphId, nodes } of loops) {
+    console.log(`  Graph: ${graphId}`);
+    for (const node of nodes) {
+      console.log(`    - ${node.id} (${node.type}: ${node.name})`);
+    }
+    console.log("");
+  }
+}
+async function handleTrace(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printTraceHelp();
+    return;
+  }
+  const traceIdx = argv.indexOf("trace");
+  const subcommand = traceIdx !== -1 ? argv[traceIdx + 1] : void 0;
+  switch (subcommand) {
+    case "list":
+      await traceList(argv);
+      break;
+    case "show":
+      await traceShow(argv);
+      break;
+    case "timeline":
+      await traceTimeline(argv);
+      break;
+    case "stuck":
+      await traceStuck(argv);
+      break;
+    case "loops":
+      await traceLoops(argv);
+      break;
+    default:
+      printTraceHelp();
+      break;
+  }
+}
+
+// src/cli.ts
 function printHelp() {
-  console.log(`
+  console.log(
+    `
 AgentFlow CLI \u2014 execution tracing and live monitoring for AI agent systems.
 
 Usage:
@@ -18,6 +215,7 @@ Commands:
   run    [options] -- <cmd>       Wrap a command with automatic execution tracing
   live   [dir...] [options]      Real-time terminal monitor (auto-detects any JSON/JSONL)
   watch  [dir...] [options]      Headless alert system \u2014 detects failures, sends notifications
+  trace  <command> [options]     Inspect saved execution traces (list, show, timeline, stuck, loops)
 
 Run \`agentflow <command> --help\` for command-specific options.
 
@@ -27,7 +225,8 @@ Examples:
   agentflow live ./traces ./cron ./workers -R
   agentflow watch ./data --alert-on error --notify telegram
   agentflow watch ./data ./cron --alert-on stale:15m --notify webhook:https://...
-`.trim());
+`.trim()
+  );
 }
 function parseRunArgs(argv) {
   const result = {
@@ -88,7 +287,8 @@ function parseRunArgs(argv) {
   return result;
 }
 function printRunUsage() {
-  console.log(`
+  console.log(
+    `
 AgentFlow Run \u2014 wrap any command with automatic execution tracing.
 
 Usage:
@@ -106,7 +306,8 @@ Examples:
   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());
+`.trim()
+  );
 }
 async function runCommand(argv) {
   if (argv.includes("--help") || argv.includes("-h")) {
@@ -115,7 +316,9 @@ async function runCommand(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(
+      "Error: No command specified. Use -- to separate agentflow flags from the command."
+    );
     console.error("Example: agentflow run -- python -m myagent process");
     process.exit(1);
   }
@@ -139,7 +342,9 @@ async function runCommand(argv) {
   try {
     const result = await runTraced(config);
     console.log("");
-    console.log(`\u2705 Command completed (exit code ${result.exitCode}, ${result.duration.toFixed(1)}s)`);
+    console.log(
+      `\u2705 Command completed (exit code ${result.exitCode}, ${result.duration.toFixed(1)}s)`
+    );
     if (result.tracePaths.length > 0) {
       console.log("\u{1F4DD} Traces saved:");
       const orchPath = result.tracePaths[0];
@@ -164,7 +369,7 @@ async function runCommand(argv) {
 }
 async function main() {
   const argv = process.argv.slice(2);
-  const knownCommands = ["run", "live", "watch"];
+  const knownCommands = ["run", "live", "watch", "trace"];
   if (argv.length === 0 || !knownCommands.includes(argv[0]) && (argv.includes("--help") || argv.includes("-h"))) {
     printHelp();
     process.exit(0);
@@ -180,6 +385,9 @@ async function main() {
     case "watch":
       startWatch(argv);
       break;
+    case "trace":
+      await handleTrace(argv);
+      break;
     default:
       if (!subcommand?.startsWith("-")) {
         startLive(["live", ...argv]);