@tangle-network/traces 0.10.2 → 0.11.0

package/dist/cli.js

@@ -12,11 +12,13 @@ import {
   describeSessionRelationship,
   executeUpload,
   exportTraceEvidenceFile,
+  fileRunContextSupervisorRunReader,
   haloAnalyzer,
   hodoscopeAnalyzer,
   importCodeTraceBench,
   indexSessionIdsByTrace,
   inspectSessionIndex,
+  isFileRunContextDir,
   knownHarnesses,
   loadTracesConfig,
   locateSessions,
@@ -27,6 +29,7 @@ import {
   readSessionIndexFile,
   renderInspectionReport,
   resolveAdapter,
+  resolveRunWatchTarget,
   runTraceImprovement,
   runTraceInvestigation,
   saveReport,
@@ -39,18 +42,19 @@ import {
   streamSessions,
   totalAgenticFailureMessage,
   traceStreamEventsFromSpans,
+  watchRunTarget,
   watchSessions,
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-LC66I5TE.js";
+} from "./chunk-JCI5YXNT.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
-import { readFile, stat } from "fs/promises";
-import { basename, resolve } from "path";
+import { readdir, readFile, stat } from "fs/promises";
+import { basename, join, resolve } from "path";
 import {
   analyzeSupervisorRun,
   findSupervisorRunDirs,
@@ -81,6 +85,7 @@ function parseArgs(argv) {
     maxWorkflowSessions: 100,
     llm: false,
     interval: 5,
+    intervalExplicit: false,
     window: 30,
     minLoop: 3,
     dryRun: false,
@@ -88,6 +93,7 @@ function parseArgs(argv) {
     noContent: false,
     analyzers: [],
     replay: false,
+    once: false,
     noSpans: false,
     noFindings: false,
     attrs: [],
@@ -174,6 +180,7 @@ function parseArgs(argv) {
       }
       case "--interval":
         a.interval = Number(next());
+        a.intervalExplicit = true;
         break;
       case "--window":
         a.window = Number(next());
@@ -188,7 +195,12 @@ function parseArgs(argv) {
         a.noContent = true;
         break;
       case "--replay":
+        a.replay = true;
+        break;
+      // `stream --once` has always meant "one pass"; `watch --once` means the
+      // same thing over a run directory, so one flag drives both.
       case "--once":
+        a.once = true;
         a.replay = true;
         break;
       case "--no-spans":
@@ -668,9 +680,23 @@ async function cmdAnalyze(args) {
   assertAgenticAnalystsRan(args, result.agenticPerAnalyst);
 }
 async function cmdAnalyzeSupervisorRun(runDir, args) {
-  const nested = await findSupervisorRunDirs(runDir);
+  const runContextDirs = await findFileRunContextDirs(runDir);
+  const nested = runContextDirs.length > 0 ? [] : await findSupervisorRunDirs(runDir);
   let markdown;
-  if (nested.length > 0) {
+  if (runContextDirs.length > 1) {
+    markdown = renderSupervisorRollupMarkdown(
+      rollupSupervisorRuns(
+        await Promise.all(
+          runContextDirs.map((dir) => analyzeSupervisorRun(fileRunContextSupervisorRunReader(dir)))
+        )
+      ),
+      `Supervisor rollup \u2014 ${runDir}`
+    );
+  } else if (runContextDirs.length === 1) {
+    markdown = renderSupervisorRunMarkdown(
+      await analyzeSupervisorRun(fileRunContextSupervisorRunReader(runContextDirs[0]))
+    );
+  } else if (nested.length > 0) {
     markdown = renderSupervisorRollupMarkdown(
       rollupSupervisorRuns(await Promise.all(nested.map((dir) => analyzeSupervisorRun(dir)))),
       `Supervisor rollup \u2014 ${runDir}`
@@ -679,20 +705,30 @@ async function cmdAnalyzeSupervisorRun(runDir, args) {
     const report = await analyzeSupervisorRun(runDir);
     if (isUnavailable(report.orchestration.workersSpawned)) {
       throw new Error(
-        `no supervisor run found at ${runDir} \u2014 expected <runDir>/ws/.agent/supervisor/<id> (or the pre-rename <runDir>/ws/.loops/supervisor/<id>), or a parent directory containing such runs`
+        `no supervisor run found at ${runDir} \u2014 expected <runDir>/spawn-journal.jsonl (agent-runtime createFileRunContext), <runDir>/ws/.agent/supervisor/<id> (or the pre-rename <runDir>/ws/.loops/supervisor/<id>), or a parent directory containing such runs`
       );
     }
     markdown = renderSupervisorRunMarkdown(report);
   }
+  const runs = Math.max(runContextDirs.length, nested.length, 1);
   if (args.out) {
     await saveReport(args.out, markdown);
-    console.log(
-      `supervisor report \u2192 ${args.out}  (${nested.length > 0 ? `${nested.length} runs` : "1 run"})`
-    );
+    console.log(`supervisor report \u2192 ${args.out}  (${runs === 1 ? "1 run" : `${runs} runs`})`);
   } else {
     console.log(markdown);
   }
 }
+async function findFileRunContextDirs(dir) {
+  if (await isFileRunContextDir(dir)) return [dir];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const found = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = join(dir, entry.name);
+    if (await isFileRunContextDir(child)) found.push(child);
+  }
+  return found.sort();
+}
 async function collectImportedSpans(args) {
   if (!args.input) throw new Error("input file missing");
   const attributes = await loadExportAttributes(args);
@@ -911,6 +947,8 @@ async function cmdStream(args) {
   });
 }
 async function cmdWatch(args) {
+  const target = args.supervisorRunDir ?? args.input;
+  if (target !== void 0) return cmdWatchRunTarget(target, args);
   const all = args.all || !args.harnessExplicit && !args.cwd;
   const controller = new AbortController();
   process.once("SIGINT", () => controller.abort());
@@ -939,6 +977,26 @@ async function cmdWatch(args) {
     }
   });
 }
+async function cmdWatchRunTarget(dir, args) {
+  const target = await resolveRunWatchTarget(resolve(dir));
+  const controller = new AbortController();
+  if (!args.once) {
+    process.once("SIGINT", () => controller.abort());
+    process.stderr.write(
+      `traces watch: tailing ${target.requested} every ${args.interval}s; read-only, ${target.runDir === null ? "span source only \u2014 Ctrl-C to stop" : "stops when result.json lands. Ctrl-C to stop"}.
+`
+    );
+  }
+  const snapshot = await watchRunTarget(target, {
+    once: args.once,
+    // A tree view wants a tighter poll than the session observer's 5s default:
+    // a blocking question is worth surfacing the moment it lands.
+    intervalMs: args.intervalExplicit ? Math.max(250, args.interval * 1e3) : 2e3,
+    signal: controller.signal
+  });
+  const result = snapshot.journal?.result ?? null;
+  if (result !== null && result.errorMessage !== null) process.exitCode = 1;
+}
 async function cmdUpload(args) {
   const sinceMs = args.since ? parseSince(args.since) : Date.now() - 24 * 60 * 60 * 1e3;
   const all = args.all || !args.harnessExplicit;
@@ -1057,6 +1115,7 @@ Commands:
   evidence  Emit compact session-evidence JSONL for downstream policy miners
   stream    Emit JSONL trace stream events for live visualizers or replay
   watch     Online observer: tail active sessions, notify on loops + semantic findings
+            (watch <target> tails ONE run tree instead: a run directory or a span file)
   upload    Redact + upload sessions in a time window to the Tangle Intelligence Platform
 
 Options:
@@ -1074,6 +1133,8 @@ Options:
                    analyze: report a SUPERVISION TREE instead of harness sessions \u2014
                    steers, spawn waves, concurrency, idle wall, cost by role,
                    accepted vs rejected. Rolls up when the dir holds many runs.
+                   watch: same directory, live. Reads the loops layout, the
+                   agent-runtime createFileRunContext journal, and OTLP span files.
   --since <t>      upload: window, 30m / 2h / 7d or an ISO date (default 24h); analyze: ISO cutoff
   --out <path>     Write report to a file
   --dir <path>     improve: write artifacts to this directory
@@ -1083,6 +1144,7 @@ Options:
   --attr <k=v>     analyze/export file: attach one span attribute (repeatable)
   --mode <kind>    stream: visualizer | findings | agent (default visualizer)
   --replay, --once stream: scan once and exit (default for positional input / --session)
+  --once           watch <target>: print ONE snapshot and exit, for scripts and agents
   --no-spans       stream: omit per-span pulse events
   --no-findings    stream: omit semantic live-finding events
   --llm            Enable agentic RLM analysts. Runs on the Tangle router by
@@ -1096,7 +1158,7 @@ Options:
   --budget <usd>   USD cap for agentic analysts
   --analyzer <id>  analyze: also run halo, hodoscope, or an installed command (repeatable)
   --analyzer-prompt <p>  analyze: prompt passed to external analyzers (default: diagnose)
-  --interval <s>   watch/stream: poll interval seconds (default 5)
+  --interval <s>   watch/stream: poll interval seconds (sessions 5, run tree 2)
   --window <m>     watch/stream: only sessions active in the last N minutes (default 30)
   --min-loop <n>   Min identical repeated calls to flag a loop (default 3)
   --dry-run        upload: redact + dedup + preview, write OTLP, but do NOT send
@@ -1106,6 +1168,13 @@ Options:
   --version, -v    Print the installed traces version
   --help, -h       Show help (use \`traces export --help\` or \`traces import-codetracebench --help\`)
 
+Watch a run tree (any depth; driver spend and child spend stay separate,
+and a cost the harness never priced reads "unknown", never $0):
+  traces watch runs/my-run                 live tree: status, budget, driver vs child spend
+  traces watch runs/my-run --once          one snapshot, then exit
+  traces watch traces.otlp.jsonl           OTLP spans only \u2014 works for ANY emitter
+  traces analyze --supervisor-run-dir runs/my-run   the full tree report
+
 Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID`);
 }
 async function main() {