agentflow-core 0.8.0 → 0.8.1

package/README.md

@@ -0,0 +1,99 @@
+# agentflow-core
+
+**v0.8.0** — Monitor any AI agent system. Auto-detects failures, sends alerts, audits OS processes. Zero config, zero dependencies.
+
+Works with any agent framework: OpenAI, Anthropic, LangChain, CrewAI, AutoGen, or hand-rolled agents.
+
+## Installation
+
+```bash
+npm install agentflow-core
+```
+
+Requires Node.js >= 20.
+
+## Quick start
+
+### Step 1 — Build an execution graph
+
+Wrap your agent's work with `createGraphBuilder`. Each logical unit of work is a node; the graph captures the full execution tree.
+
+```ts
+import { createGraphBuilder, getStats } from 'agentflow-core';
+
+const builder = createGraphBuilder({ agentId: 'my-agent' });
+
+const rootId = builder.startNode({ type: 'agent', name: 'main' });
+  const toolId = builder.startNode({ type: 'tool', name: 'fetch', parentId: rootId });
+  builder.endNode(toolId);
+builder.endNode(rootId);
+
+const graph = builder.build();
+console.log(getStats(graph));
+// { totalNodes: 2, failedNodes: 0, duration: 42, status: 'completed' }
+```
+
+### Step 2 — Mine patterns across runs
+
+Accumulate graphs over time and use process mining to find variants, bottlenecks, and conformance drift.
+
+```ts
+import { discoverProcess, findVariants, getBottlenecks, checkConformance } from 'agentflow-core';
+
+const model = discoverProcess(graphs);          // build a process model from observed runs
+const variants = findVariants(graphs);          // group runs by their execution path
+const bottlenecks = getBottlenecks(graphs);     // rank nodes by cumulative wait time
+const report = checkConformance(graph, model);  // score a new run against the baseline
+```
+
+### Step 3 — Add guards
+
+Guards detect runaway loops, spawn explosions, and policy violations at runtime. Wrap your builder with `withGuards` to activate them.
+
+```ts
+import { createGraphBuilder, withGuards, createSomaPolicySource } from 'agentflow-core';
+
+const raw = createGraphBuilder({ agentId: 'my-agent' });
+const guarded = withGuards(raw, {
+  maxDepth: 8,
+  maxReasoningSteps: 20,
+  onViolation: 'warn',        // 'warn' | 'error' | 'abort'
+  policySource: myPolicySource, // optional: adaptive thresholds from Soma
+});
+```
+
+## API highlights
+
+| Export | Kind | Description |
+|---|---|---|
+| `createGraphBuilder` | factory | Build and mutate an execution graph during a run |
+| `withGuards` | wrapper | Add runtime guard checks to any GraphBuilder |
+| `checkGuards` | fn | Pure guard check on a graph snapshot |
+| `getStats` | fn | Summary stats: node counts, status, duration |
+| `getCriticalPath` | fn | Longest path through the graph by duration |
+| `getFailures` | fn | All failed nodes with error metadata |
+| `getHungNodes` | fn | Nodes that are running beyond their timeout |
+| `discoverProcess` | fn | Build a process model from a run corpus |
+| `findVariants` | fn | Group runs by execution path signature |
+| `getBottlenecks` | fn | Rank nodes by cumulative elapsed time |
+| `checkConformance` | fn | Score a run against a reference process model |
+| `createInsightEngine` | factory | Tier-2 LLM analysis: anomaly, failure, and fix prompts |
+| `createTraceStore` | factory | Persist and load graphs from disk |
+| `createEventEmitter` | factory | Emit structured events during execution |
+| `createJsonEventWriter` | factory | Write events to newline-delimited JSON |
+| `createSomaEventWriter` | factory | Write events to a Soma inbox for ingestion |
+| `createKnowledgeStore` | factory | Lightweight in-process key/value knowledge store |
+| `createPolicySource` | factory | Static policy source for guard thresholds |
+| `stitchTrace` | fn | Reconstruct a distributed trace from span events |
+| `startLive` | fn | Live terminal monitor for a running agent |
+| `startWatch` | fn | Headless watcher with alerting via notify channels |
+| `auditProcesses` | fn | Audit OS processes, PIDs, and systemd units |
+| `runTraced` | fn | Run a shell command with full execution tracing |
+| `toAsciiTree` | fn | Render a graph as an ASCII tree |
+| `toTimeline` | fn | Render a graph as a text timeline |
+
+Full type definitions are bundled. All functions are pure unless noted as factory.
+
+## Docs
+
+[https://github.com/ClemenceChee/AgentFlow#readme](https://github.com/ClemenceChee/AgentFlow#readme)

package/dist/{chunk-DY7YHFIB.js → chunk-BYWLDTZK.js}

@@ -25,7 +25,8 @@ function loadGraph(input) {
     events: raw.events ?? [],
     traceId: raw.traceId,
     spanId: raw.spanId,
-    parentSpanId: raw.parentSpanId
+    parentSpanId: raw.parentSpanId,
+    metadata: raw.metadata ?? {}
   };
 }
 function graphToJson(graph) {

package/dist/{chunk-6X5HU5LB.js → chunk-NVFWBTAZ.js}

@@ -1,7 +1,7 @@
 import {
   graphToJson,
   loadGraph
-} from "./chunk-DY7YHFIB.js";
+} from "./chunk-BYWLDTZK.js";
 
 // src/graph-query.ts
 function getNode(graph, nodeId) {
@@ -207,7 +207,7 @@ function getTraceTree(trace) {
 }
 
 // src/process-audit.ts
-import { execSync } from "child_process";
+import { execFileSync, execSync } from "child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { basename, join } from "path";
 function isPidAlive(pid) {
@@ -264,8 +264,15 @@ function auditSystemd(config) {
   if (config.systemdUnit === null || config.systemdUnit === void 0) return null;
   const unit = config.systemdUnit;
   try {
-    const raw = execSync(
-      `systemctl --user show ${unit} --property=ActiveState,SubState,MainPID,NRestarts,Result --no-pager 2>/dev/null`,
+    const raw = execFileSync(
+      "systemctl",
+      [
+        "--user",
+        "show",
+        unit,
+        "--property=ActiveState,SubState,MainPID,NRestarts,Result",
+        "--no-pager"
+      ],
       { encoding: "utf8", timeout: 5e3 }
     );
     const props = {};
@@ -356,9 +363,11 @@ function getOsProcesses(processName) {
   }
 }
 function discoverProcessConfig(dirs) {
-  let pidFile;
-  let workersFile;
-  let processName = "";
+  const configs = discoverAllProcessConfigs(dirs);
+  return configs.length > 0 ? configs[0] ?? null : null;
+}
+function discoverAllProcessConfigs(dirs) {
+  const configs = /* @__PURE__ */ new Map();
   for (const dir of dirs) {
     if (!existsSync(dir)) continue;
     let entries;
@@ -374,35 +383,63 @@ function discoverProcessConfig(dirs) {
       } catch {
         continue;
       }
-      if (f.endsWith(".pid") && !pidFile) {
-        pidFile = fp;
-        if (!processName) {
-          processName = basename(f, ".pid");
+      if (f.endsWith(".pid")) {
+        const name = basename(f, ".pid");
+        if (!configs.has(name)) {
+          configs.set(name, { processName: name });
         }
+        const cfg = configs.get(name) ?? { processName: name };
+        if (!cfg.pidFile) cfg.pidFile = fp;
       }
-      if ((f === "workers.json" || f.endsWith("-workers.json")) && !workersFile) {
-        workersFile = fp;
-        if (!processName && f !== "workers.json") {
-          processName = basename(f, "-workers.json");
+      if (f === "workers.json" || f.endsWith("-workers.json")) {
+        const name = f === "workers.json" ? "" : basename(f, "-workers.json");
+        if (name && !configs.has(name)) {
+          configs.set(name, { processName: name });
+        }
+        if (name) {
+          const cfg = configs.get(name) ?? { processName: name };
+          if (!cfg.workersFile) cfg.workersFile = fp;
         }
       }
     }
   }
-  if (!processName && !pidFile && !workersFile) return null;
-  if (!processName) processName = "agent";
-  let systemdUnit;
   try {
-    const unitName = `${processName}.service`;
-    const result = execSync(
-      `systemctl --user show ${unitName} --property=LoadState --no-pager 2>/dev/null`,
-      { encoding: "utf8", timeout: 3e3 }
+    const raw = execSync(
+      "systemctl --user list-units --type=service --all --no-legend --no-pager 2>/dev/null",
+      { encoding: "utf8", timeout: 5e3 }
     );
-    if (result.includes("LoadState=loaded")) {
-      systemdUnit = unitName;
+    for (const line of raw.trim().split("\n")) {
+      if (!line.trim()) continue;
+      const parts = line.trim().split(/\s+/);
+      const unitName = parts[0] ?? "";
+      const loadState = parts[1] ?? "";
+      if (!unitName.endsWith(".service") || loadState !== "loaded") continue;
+      const name = unitName.replace(".service", "");
+      if (/^(dbus|gpg-agent|dirmngr|keyboxd|snapd\.|pk-|launchpadlib-)/.test(name)) continue;
+      if (!configs.has(name)) {
+        configs.set(name, { processName: name });
+      }
+      const cfg = configs.get(name) ?? { processName: name };
+      cfg.systemdUnit = unitName;
     }
   } catch {
   }
-  return { processName, pidFile, workersFile, systemdUnit };
+  for (const cfg of configs.values()) {
+    if (cfg.systemdUnit !== void 0) continue;
+    try {
+      const unitName = `${cfg.processName}.service`;
+      const result = execFileSync(
+        "systemctl",
+        ["--user", "show", unitName, "--property=LoadState", "--no-pager"],
+        { encoding: "utf8", timeout: 3e3 }
+      );
+      if (result.includes("LoadState=loaded")) {
+        cfg.systemdUnit = unitName;
+      }
+    } catch {
+    }
+  }
+  return [...configs.values()];
 }
 function auditProcesses(config) {
   const pidFile = auditPidFile(config);
@@ -566,7 +603,7 @@ function parseArgs(argv) {
   if (args[0] === "live") args.shift();
   let i = 0;
   while (i < args.length) {
-    const arg = args[i];
+    const arg = args[i] ?? "";
     if (arg === "--help" || arg === "-h") {
       printUsage();
       process.exit(0);
@@ -873,7 +910,7 @@ function processJsonlFile(file) {
     if (!content) return [];
     const lines = content.split("\n");
     const lineCount = lines.length;
-    const lastObj = JSON.parse(lines[lines.length - 1]);
+    const lastObj = JSON.parse(lines[lines.length - 1] ?? "{}");
     const name = lastObj.jobId ?? lastObj.agentId ?? lastObj.name ?? lastObj.id ?? nameFromFile(file.filename);
     if (lastObj.action !== void 0 || lastObj.jobId !== void 0) {
       const status2 = findStatus(lastObj);
@@ -969,7 +1006,7 @@ function processJsonlFile(file) {
     }
     const parts = [];
     if (model) {
-      const shortModel = model.includes("/") ? model.split("/").pop() : model;
+      const shortModel = model.includes("/") ? model.split("/").pop() ?? model : model;
       parts.push(shortModel.slice(0, 20));
     }
     if (toolCalls.length > 0) {
@@ -1134,15 +1171,15 @@ function render(config) {
     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]++;
+      buckets[idx] = (buckets[idx] ?? 0) + 1;
+      if (r.status === "error") failBuckets[idx] = (failBuckets[idx] ?? 0) + 1;
     }
   }
   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;
+    return ((failBuckets[i] ?? 0) > 0 ? C.red : C.green) + sparkChars[level] + C.reset;
   }).join("");
   let auditResult = null;
   if (now - lastAuditTime > 1e4) {
@@ -1393,7 +1430,7 @@ function render(config) {
     for (const d of config.dirs) writeLine(L, `  ${C.dim}  ${d}${C.reset}`);
   }
   writeLine(L, "");
-  const dirLabel = config.dirs.length === 1 ? config.dirs[0] : `${config.dirs.length} directories`;
+  const dirLabel = config.dirs.length === 1 ? config.dirs[0] ?? "" : `${config.dirs.length} directories`;
   writeLine(L, `  ${C.dim}Watching: ${dirLabel}${C.reset}`);
   writeLine(L, `  ${C.dim}Press Ctrl+C to exit${C.reset}`);
   flushLines(L);
@@ -2207,7 +2244,7 @@ function parseDuration(input) {
     const n = parseInt(input, 10);
     return Number.isNaN(n) ? 0 : n * 1e3;
   }
-  const value = parseFloat(match[1]);
+  const value = parseFloat(match[1] ?? "0");
   switch (match[2]?.toLowerCase()) {
     case "s":
       return value * 1e3;
@@ -2251,12 +2288,12 @@ function estimateInterval(history) {
   const sorted = [...history].sort((a, b) => a - b);
   const deltas = [];
   for (let i = 1; i < sorted.length; i++) {
-    const d = sorted[i] - sorted[i - 1];
+    const d = (sorted[i] ?? 0) - (sorted[i - 1] ?? 0);
     if (d > 0) deltas.push(d);
   }
   if (deltas.length === 0) return 0;
   deltas.sort((a, b) => a - b);
-  return deltas[Math.floor(deltas.length / 2)];
+  return deltas[Math.floor(deltas.length / 2)] ?? 0;
 }
 function detectTransitions(previous, currentRecords, config, now) {
   const alerts = [];
@@ -2413,7 +2450,7 @@ function parseWatchArgs(argv) {
   if (args[0] === "watch") args.shift();
   let i = 0;
   while (i < args.length) {
-    const arg = args[i];
+    const arg = args[i] ?? "";
     if (arg === "--help" || arg === "-h") {
       printWatchUsage();
       process.exit(0);
@@ -2482,7 +2519,7 @@ function parseWatchArgs(argv) {
   }
   notifyChannels.unshift({ type: "stdout" });
   if (!stateFilePath) {
-    stateFilePath = join5(dirs[0], ".agentflow-watch-state.json");
+    stateFilePath = join5(dirs[0] ?? ".", ".agentflow-watch-state.json");
   }
   return {
     dirs,
@@ -2643,6 +2680,7 @@ export {
   stitchTrace,
   getTraceTree,
   discoverProcessConfig,
+  discoverAllProcessConfigs,
   auditProcesses,
   formatAuditReport,
   startLive,

package/dist/cli.cjs

@@ -62,7 +62,8 @@ function loadGraph(input) {
     events: raw.events ?? [],
     traceId: raw.traceId,
     spanId: raw.spanId,
-    parentSpanId: raw.parentSpanId
+    parentSpanId: raw.parentSpanId,
+    metadata: raw.metadata ?? {}
   };
 }
 function graphToJson(graph) {
@@ -303,8 +304,15 @@ function auditSystemd(config) {
   if (config.systemdUnit === null || config.systemdUnit === void 0) return null;
   const unit = config.systemdUnit;
   try {
-    const raw = (0, import_node_child_process.execSync)(
-      `systemctl --user show ${unit} --property=ActiveState,SubState,MainPID,NRestarts,Result --no-pager 2>/dev/null`,
+    const raw = (0, import_node_child_process.execFileSync)(
+      "systemctl",
+      [
+        "--user",
+        "show",
+        unit,
+        "--property=ActiveState,SubState,MainPID,NRestarts,Result",
+        "--no-pager"
+      ],
       { encoding: "utf8", timeout: 5e3 }
     );
     const props = {};
@@ -395,9 +403,11 @@ function getOsProcesses(processName) {
   }
 }
 function discoverProcessConfig(dirs) {
-  let pidFile;
-  let workersFile;
-  let processName = "";
+  const configs = discoverAllProcessConfigs(dirs);
+  return configs.length > 0 ? configs[0] ?? null : null;
+}
+function discoverAllProcessConfigs(dirs) {
+  const configs = /* @__PURE__ */ new Map();
   for (const dir of dirs) {
     if (!(0, import_node_fs.existsSync)(dir)) continue;
     let entries;
@@ -413,35 +423,63 @@ function discoverProcessConfig(dirs) {
       } catch {
         continue;
       }
-      if (f.endsWith(".pid") && !pidFile) {
-        pidFile = fp;
-        if (!processName) {
-          processName = (0, import_node_path.basename)(f, ".pid");
+      if (f.endsWith(".pid")) {
+        const name = (0, import_node_path.basename)(f, ".pid");
+        if (!configs.has(name)) {
+          configs.set(name, { processName: name });
         }
+        const cfg = configs.get(name) ?? { processName: name };
+        if (!cfg.pidFile) cfg.pidFile = fp;
       }
-      if ((f === "workers.json" || f.endsWith("-workers.json")) && !workersFile) {
-        workersFile = fp;
-        if (!processName && f !== "workers.json") {
-          processName = (0, import_node_path.basename)(f, "-workers.json");
+      if (f === "workers.json" || f.endsWith("-workers.json")) {
+        const name = f === "workers.json" ? "" : (0, import_node_path.basename)(f, "-workers.json");
+        if (name && !configs.has(name)) {
+          configs.set(name, { processName: name });
+        }
+        if (name) {
+          const cfg = configs.get(name) ?? { processName: name };
+          if (!cfg.workersFile) cfg.workersFile = fp;
         }
       }
     }
   }
-  if (!processName && !pidFile && !workersFile) return null;
-  if (!processName) processName = "agent";
-  let systemdUnit;
   try {
-    const unitName = `${processName}.service`;
-    const result = (0, import_node_child_process.execSync)(
-      `systemctl --user show ${unitName} --property=LoadState --no-pager 2>/dev/null`,
-      { encoding: "utf8", timeout: 3e3 }
+    const raw = (0, import_node_child_process.execSync)(
+      "systemctl --user list-units --type=service --all --no-legend --no-pager 2>/dev/null",
+      { encoding: "utf8", timeout: 5e3 }
     );
-    if (result.includes("LoadState=loaded")) {
-      systemdUnit = unitName;
+    for (const line of raw.trim().split("\n")) {
+      if (!line.trim()) continue;
+      const parts = line.trim().split(/\s+/);
+      const unitName = parts[0] ?? "";
+      const loadState = parts[1] ?? "";
+      if (!unitName.endsWith(".service") || loadState !== "loaded") continue;
+      const name = unitName.replace(".service", "");
+      if (/^(dbus|gpg-agent|dirmngr|keyboxd|snapd\.|pk-|launchpadlib-)/.test(name)) continue;
+      if (!configs.has(name)) {
+        configs.set(name, { processName: name });
+      }
+      const cfg = configs.get(name) ?? { processName: name };
+      cfg.systemdUnit = unitName;
     }
   } catch {
   }
-  return { processName, pidFile, workersFile, systemdUnit };
+  for (const cfg of configs.values()) {
+    if (cfg.systemdUnit !== void 0) continue;
+    try {
+      const unitName = `${cfg.processName}.service`;
+      const result = (0, import_node_child_process.execFileSync)(
+        "systemctl",
+        ["--user", "show", unitName, "--property=LoadState", "--no-pager"],
+        { encoding: "utf8", timeout: 3e3 }
+      );
+      if (result.includes("LoadState=loaded")) {
+        cfg.systemdUnit = unitName;
+      }
+    } catch {
+    }
+  }
+  return [...configs.values()];
 }
 function auditProcesses(config) {
   const pidFile = auditPidFile(config);
@@ -603,7 +641,7 @@ function parseArgs(argv) {
   if (args[0] === "live") args.shift();
   let i = 0;
   while (i < args.length) {
-    const arg = args[i];
+    const arg = args[i] ?? "";
     if (arg === "--help" || arg === "-h") {
       printUsage();
       process.exit(0);
@@ -910,7 +948,7 @@ function processJsonlFile(file) {
     if (!content) return [];
     const lines = content.split("\n");
     const lineCount = lines.length;
-    const lastObj = JSON.parse(lines[lines.length - 1]);
+    const lastObj = JSON.parse(lines[lines.length - 1] ?? "{}");
     const name = lastObj.jobId ?? lastObj.agentId ?? lastObj.name ?? lastObj.id ?? nameFromFile(file.filename);
     if (lastObj.action !== void 0 || lastObj.jobId !== void 0) {
       const status2 = findStatus(lastObj);
@@ -1006,7 +1044,7 @@ function processJsonlFile(file) {
     }
     const parts = [];
     if (model) {
-      const shortModel = model.includes("/") ? model.split("/").pop() : model;
+      const shortModel = model.includes("/") ? model.split("/").pop() ?? model : model;
       parts.push(shortModel.slice(0, 20));
     }
     if (toolCalls.length > 0) {
@@ -1171,15 +1209,15 @@ function render(config) {
     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]++;
+      buckets[idx] = (buckets[idx] ?? 0) + 1;
+      if (r.status === "error") failBuckets[idx] = (failBuckets[idx] ?? 0) + 1;
     }
   }
   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;
+    return ((failBuckets[i] ?? 0) > 0 ? C.red : C.green) + sparkChars[level] + C.reset;
   }).join("");
   let auditResult = null;
   if (now - lastAuditTime > 1e4) {
@@ -1430,7 +1468,7 @@ function render(config) {
     for (const d of config.dirs) writeLine(L, `  ${C.dim}  ${d}${C.reset}`);
   }
   writeLine(L, "");
-  const dirLabel = config.dirs.length === 1 ? config.dirs[0] : `${config.dirs.length} directories`;
+  const dirLabel = config.dirs.length === 1 ? config.dirs[0] ?? "" : `${config.dirs.length} directories`;
   writeLine(L, `  ${C.dim}Watching: ${dirLabel}${C.reset}`);
   writeLine(L, `  ${C.dim}Press Ctrl+C to exit${C.reset}`);
   flushLines(L);
@@ -2440,7 +2478,7 @@ function parseDuration(input) {
     const n = parseInt(input, 10);
     return Number.isNaN(n) ? 0 : n * 1e3;
   }
-  const value = parseFloat(match[1]);
+  const value = parseFloat(match[1] ?? "0");
   switch (match[2]?.toLowerCase()) {
     case "s":
       return value * 1e3;
@@ -2484,12 +2522,12 @@ function estimateInterval(history) {
   const sorted = [...history].sort((a, b) => a - b);
   const deltas = [];
   for (let i = 1; i < sorted.length; i++) {
-    const d = sorted[i] - sorted[i - 1];
+    const d = (sorted[i] ?? 0) - (sorted[i - 1] ?? 0);
     if (d > 0) deltas.push(d);
   }
   if (deltas.length === 0) return 0;
   deltas.sort((a, b) => a - b);
-  return deltas[Math.floor(deltas.length / 2)];
+  return deltas[Math.floor(deltas.length / 2)] ?? 0;
 }
 function detectTransitions(previous, currentRecords, config, now) {
   const alerts = [];
@@ -2646,7 +2684,7 @@ function parseWatchArgs(argv) {
   if (args[0] === "watch") args.shift();
   let i = 0;
   while (i < args.length) {
-    const arg = args[i];
+    const arg = args[i] ?? "";
     if (arg === "--help" || arg === "-h") {
       printWatchUsage();
       process.exit(0);
@@ -2715,7 +2753,7 @@ function parseWatchArgs(argv) {
   }
   notifyChannels.unshift({ type: "stdout" });
   if (!stateFilePath) {
-    stateFilePath = (0, import_node_path6.join)(dirs[0], ".agentflow-watch-state.json");
+    stateFilePath = (0, import_node_path6.join)(dirs[0] ?? ".", ".agentflow-watch-state.json");
   }
   return {
     dirs,
@@ -3036,7 +3074,7 @@ function parseAuditArgs(argv) {
   if (args[0] === "audit") args.shift();
   let i = 0;
   while (i < args.length) {
-    const arg = args[i];
+    const arg = args[i] ?? "";
     if (arg === "--help" || arg === "-h") {
       printAuditUsage();
       process.exit(0);
@@ -3126,7 +3164,7 @@ function runAudit(argv) {
 async function main() {
   const argv = process.argv.slice(2);
   const knownCommands = ["run", "live", "watch", "trace", "audit"];
-  if (argv.length === 0 || !knownCommands.includes(argv[0]) && (argv.includes("--help") || argv.includes("-h"))) {
+  if (argv.length === 0 || !knownCommands.includes(argv[0] ?? "") && (argv.includes("--help") || argv.includes("-h"))) {
     printHelp();
     process.exit(0);
   }

package/dist/cli.js

@@ -9,8 +9,8 @@ import {
   startWatch,
   toAsciiTree,
   toTimeline
-} from "./chunk-6X5HU5LB.js";
-import "./chunk-DY7YHFIB.js";
+} from "./chunk-NVFWBTAZ.js";
+import "./chunk-BYWLDTZK.js";
 
 // src/cli.ts
 import { basename, resolve as resolve2 } from "path";
@@ -95,7 +95,7 @@ async function traceShow(argv) {
     const { join } = await import("path");
     const fname = graphId.endsWith(".json") ? graphId : `${graphId}.json`;
     try {
-      const { loadGraph } = await import("./loader-LYRR6LMM.js");
+      const { loadGraph } = await import("./loader-JMFEFI3Q.js");
       const content = await readFile(join(dir, fname), "utf-8");
       graph = loadGraph(content);
     } catch {
@@ -124,7 +124,7 @@ async function traceTimeline(argv) {
     const { join } = await import("path");
     const fname = graphId.endsWith(".json") ? graphId : `${graphId}.json`;
     try {
-      const { loadGraph } = await import("./loader-LYRR6LMM.js");
+      const { loadGraph } = await import("./loader-JMFEFI3Q.js");
       const content = await readFile(join(dir, fname), "utf-8");
       graph = loadGraph(content);
     } catch {
@@ -381,7 +381,7 @@ function parseAuditArgs(argv) {
   if (args[0] === "audit") args.shift();
   let i = 0;
   while (i < args.length) {
-    const arg = args[i];
+    const arg = args[i] ?? "";
     if (arg === "--help" || arg === "-h") {
       printAuditUsage();
       process.exit(0);
@@ -471,7 +471,7 @@ function runAudit(argv) {
 async function main() {
   const argv = process.argv.slice(2);
   const knownCommands = ["run", "live", "watch", "trace", "audit"];
-  if (argv.length === 0 || !knownCommands.includes(argv[0]) && (argv.includes("--help") || argv.includes("-h"))) {
+  if (argv.length === 0 || !knownCommands.includes(argv[0] ?? "") && (argv.includes("--help") || argv.includes("-h"))) {
     printHelp();
     process.exit(0);
   }