@tangle-network/traces 0.8.0 → 0.8.11

package/dist/cli.js

@@ -1,23 +1,39 @@
 #!/usr/bin/env node
 import {
+  analyzeAdoption,
+  analyzeReactions,
   analyzeSpans,
+  buildPolicyEvidenceRecord,
+  buildSessionIndexFromRows,
   commandAnalyzer,
   commandRedactor,
   executeUpload,
+  exportTraceEvidenceFile,
   haloAnalyzer,
+  inspectSessionIndex,
   knownHarnesses,
+  parseSession,
   parseSince,
   planUpload,
+  readSessionIndexFile,
+  renderInspectionReport,
   resolveAdapter,
   runExternalAnalyzers,
   runPipelines,
   selectAdapters,
+  serializePolicyEvidence,
+  serializeSessionIndex,
+  serializeSpans,
   watchSessions,
-  writeOtlpFile
-} from "./chunk-BUD6I3ZJ.js";
+  writeInspectionReportFile,
+  writeOtlpFile,
+  writePolicyEvidenceFile,
+  writeSessionIndexFile,
+  writeTraceEvidenceExportFile
+} from "./chunk-PRRWLKSI.js";
 
 // src/cli.ts
-import { stat, writeFile } from "fs/promises";
+import { readFile, stat, writeFile } from "fs/promises";
 
 // src/report.ts
 var SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
@@ -95,11 +111,93 @@ function renderPipelines(pr) {
   lines.push("");
   return lines.join("\n");
 }
+var REACTION_BADGE = {
+  correction: "correction",
+  frustration: "frustration",
+  jargon: "jargon-complaint",
+  structure: "structure-complaint",
+  praise: "praise"
+};
+function ratioStr(r) {
+  if (r === null) return "n/a (no reaction signals)";
+  if (!Number.isFinite(r)) return "\u221E (corrective with zero praise)";
+  return `${r.toFixed(2)}:1`;
+}
+function oneLine(s, n) {
+  const t = s.replace(/\s+/g, " ").trim();
+  return t.length > n ? `${t.slice(0, n)}\u2026` : t;
+}
+function renderReactions(rr) {
+  const lines = ["## user reactions (deterministic, human turns only)", ""];
+  const total = Object.values(rr.signals).reduce((a, b) => a + b, 0);
+  if (rr.humanReactionTurns === 0) {
+    lines.push("- No human turns followed an assistant turn (nothing to classify).");
+    lines.push("");
+    return lines.join("\n");
+  }
+  lines.push(
+    `- **Reaction turns:** ${rr.humanReactionTurns} human turn(s) followed an assistant turn; ${total} carried a reaction signal.`
+  );
+  lines.push(`- **Corrective-to-positive ratio:** ${ratioStr(rr.correctiveToPositiveRatio)}`);
+  lines.push("");
+  lines.push("| Signal | Count |");
+  lines.push("|---|---|");
+  for (const [k, v] of Object.entries(rr.signals)) {
+    if (v > 0) lines.push(`| ${REACTION_BADGE[k] ?? k} | ${v} |`);
+  }
+  lines.push("");
+  if (rr.triggerPairs.length > 0) {
+    lines.push("### top trigger pairs (assistant prose \u2192 human reaction)");
+    lines.push("");
+    for (const p of rr.triggerPairs) {
+      lines.push(`- **[${p.reactions.map((r) => REACTION_BADGE[r] ?? r).join(", ")}]**`);
+      lines.push(`  - assistant: \`${oneLine(p.assistant, 180)}\``);
+      lines.push(`  - human: \`${oneLine(p.human, 180)}\``);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderAdoption(ar) {
+  const lines = ["## skill & subagent adoption (deterministic)", ""];
+  lines.push(
+    `- **Skill penetration:** ${(ar.skillPenetration * 100).toFixed(0)}% (${ar.sessionsWithSkill}/${ar.sessionCount} session(s) invoked a skill explicitly)`
+  );
+  lines.push(
+    `- **Explicit skill invocations:** ${ar.totalSkillInvocations} (Skill tool spans)  \xB7  **Loop-dispatched runs:** ${ar.totalLoopDispatchedRuns} (from ${ar.skillRunFilesRead} \`.evolve/skill-runs.jsonl\` file(s))`
+  );
+  lines.push(
+    `- **Subagent spawns:** ${ar.totalSubagentSpawns} across ${ar.sessionsWithSubagent} session(s)`
+  );
+  lines.push("");
+  const skillRows = Object.entries(ar.skillInvocations).sort((a, b) => b[1] - a[1]);
+  const loopRows = Object.entries(ar.loopDispatchedRuns).sort((a, b) => b[1] - a[1]);
+  if (skillRows.length > 0 || loopRows.length > 0) {
+    lines.push("| Skill | Explicit invocations | Loop-dispatched runs |");
+    lines.push("|---|---|---|");
+    const names = [.../* @__PURE__ */ new Set([...skillRows.map((r) => r[0]), ...loopRows.map((r) => r[0])])].sort(
+      (a, b) => (ar.skillInvocations[b] ?? 0) + (ar.loopDispatchedRuns[b] ?? 0) - (ar.skillInvocations[a] ?? 0) - (ar.loopDispatchedRuns[a] ?? 0)
+    );
+    for (const n of names) {
+      lines.push(`| \`${n}\` | ${ar.skillInvocations[n] ?? 0} | ${ar.loopDispatchedRuns[n] ?? 0} |`);
+    }
+    lines.push("");
+  }
+  const agentRows = Object.entries(ar.subagentSpawns).sort((a, b) => b[1] - a[1]);
+  if (agentRows.length > 0) {
+    lines.push("| Subagent | Spawns |");
+    lines.push("|---|---|");
+    for (const [n, c] of agentRows) lines.push(`| \`${n}\` | ${c} |`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 
 // src/cli.ts
 function parseArgs(argv) {
   const a = {
-    command: argv[0] ?? "help",
+    command: argv[0] === "--help" || argv[0] === "-h" ? "help" : argv[0] ?? "help",
+    help: argv[0] === "--help" || argv[0] === "-h",
     harness: "claude-code",
     harnessExplicit: false,
     all: false,
@@ -111,7 +209,8 @@ function parseArgs(argv) {
     dryRun: false,
     yes: false,
     noContent: false,
-    analyzers: []
+    analyzers: [],
+    attrs: []
   };
   for (let i = 1; i < argv.length; i++) {
     const arg = argv[i];
@@ -151,6 +250,14 @@ function parseArgs(argv) {
       case "--model":
         a.model = next();
         break;
+      case "--metadata":
+        a.metadata = next();
+        break;
+      case "--attr": {
+        const v = next();
+        if (v) a.attrs.push(v);
+        break;
+      }
       case "--interval":
         a.interval = Number(next());
         break;
@@ -177,12 +284,21 @@ function parseArgs(argv) {
       case "--redactor":
         a.redactorCmd = next();
         break;
+      case "--format":
+        a.format = next();
+        break;
+      case "--help":
+      case "-h":
+        a.help = true;
+        break;
       case "--yes":
       case "-y":
         a.yes = true;
         break;
       default:
         if (arg?.startsWith("--")) throw new Error(`unknown flag: ${arg}`);
+        if (arg && !a.input) a.input = arg;
+        else if (arg) throw new Error(`unexpected positional argument: ${arg}`);
     }
   }
   return a;
@@ -243,23 +359,28 @@ async function collectSpans(args) {
       harness: adapter.harness,
       sessionId: args.session,
       path: args.session,
-      cwd: null,
+      // --session is an explicit file; honor --cwd so adoption can find the
+      // project's .evolve/skill-runs.jsonl (locate() infers cwd in the scan path).
+      cwd: args.cwd ?? null,
       mtimeMs: st.mtimeMs
     };
-    return { spans: await adapter.parse(ref), harness: adapter.harness, sessionCount: 1 };
+    const spans2 = await parseSession(adapter, ref);
+    return { spans: spans2, harness: adapter.harness, sessionCount: 1, cwds: ref.cwd ? [ref.cwd] : [] };
   }
   const groups = await discover({ ...args, last: args.last || 1 });
   const spans = [];
   let sessionCount = 0;
   const harnesses = [];
+  const cwds = [];
   for (const { adapter, refs } of groups) {
     if (refs.length > 0) harnesses.push(adapter.harness);
     for (const ref of refs) {
-      spans.push(...await adapter.parse(ref));
+      spans.push(...await parseSession(adapter, ref));
+      if (ref.cwd) cwds.push(ref.cwd);
       sessionCount += 1;
     }
   }
-  return { spans, harness: harnesses.join("+") || args.harness, sessionCount };
+  return { spans, harness: harnesses.join("+") || args.harness, sessionCount, cwds };
 }
 async function cmdConvert(args) {
   const { spans } = await collectSpans(args);
@@ -267,8 +388,125 @@ async function cmdConvert(args) {
   const path = await writeOtlpFile(spans, args.otlp);
   console.log(`wrote ${spans.length} spans \u2192 ${path}`);
 }
+async function collectSessionRows(args) {
+  if (args.session) {
+    const adapter = resolveAdapter(args.harness);
+    if (!adapter) throw new Error(`unknown harness "${args.harness}"`);
+    const st = await stat(args.session);
+    const ref = {
+      harness: adapter.harness,
+      sessionId: args.session,
+      path: args.session,
+      cwd: args.cwd ?? null,
+      mtimeMs: st.mtimeMs
+    };
+    return [{ ref, spans: await parseSession(adapter, ref) }];
+  }
+  const groups = await discover({ ...args, last: args.last || 20 });
+  const rows = [];
+  for (const { adapter, refs } of groups) {
+    for (const ref of refs) rows.push({ ref, spans: await parseSession(adapter, ref) });
+  }
+  return rows;
+}
+async function cmdEvidence(args) {
+  const rows = (await collectSessionRows(args)).filter((row) => row.spans.length > 0);
+  if (rows.length === 0) throw new Error("no spans found for the given selection");
+  const otlpPath = args.otlp ? await writeOtlpFile(rows.flatMap((row) => row.spans), args.otlp) : void 0;
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const records = await Promise.all(rows.map(
+    (row) => buildPolicyEvidenceRecord(row.ref, row.spans, {
+      generatedAt,
+      minLoopOccurrences: args.minLoop,
+      maxLoopExamples: 25,
+      otlpPath
+    })
+  ));
+  if (args.out) {
+    const path = await writePolicyEvidenceFile(records, args.out);
+    console.log(`policy evidence \u2192 ${path}  (${records.length} session rows${otlpPath ? `, OTLP: ${otlpPath}` : ""})`);
+  } else {
+    process.stdout.write(serializePolicyEvidence(records));
+  }
+}
+async function cmdIndex(args) {
+  const rows = (await collectSessionRows(args)).filter((row) => row.spans.length > 0);
+  if (rows.length === 0) throw new Error("no spans found for the given selection");
+  const index = await buildSessionIndexFromRows(rows, {
+    minLoopOccurrences: args.minLoop,
+    selection: {
+      command: "index",
+      harness: args.harnessExplicit ? args.harness : void 0,
+      all: args.all || void 0,
+      last: args.last || void 0,
+      session: args.session,
+      cwd: args.cwd,
+      since: args.since
+    }
+  });
+  if (args.out) {
+    const path = await writeSessionIndexFile(index, args.out);
+    console.log(`session index \u2192 ${path}  (${index.totals.sessions} session rows)`);
+  } else {
+    process.stdout.write(serializeSessionIndex(index));
+  }
+}
+async function cmdInspect(args) {
+  if (!args.input) throw new Error("inspect needs an index file; run `traces index --out session-index.json` first");
+  const index = await readSessionIndexFile(args.input);
+  const report = inspectSessionIndex(index);
+  if (args.out) {
+    const path = await writeInspectionReportFile(report, args.out);
+    console.log(`inspection report \u2192 ${path}  (${report.totals.findings} finding(s), high ${report.totals.high})`);
+  } else {
+    process.stdout.write(renderInspectionReport(report));
+  }
+}
+async function cmdExport(args) {
+  if (!args.input) throw new Error("export needs an input file; run `traces export --help` for examples");
+  const format = args.format ?? "auto";
+  if (format !== "auto" && format !== "policy-evidence" && format !== "sandbox-events" && format !== "openinference") {
+    throw new Error("--format must be auto, policy-evidence, sandbox-events, or openinference");
+  }
+  const attributes = await loadExportAttributes(args);
+  const outPath = args.out ?? args.otlp;
+  if (outPath) {
+    const result2 = await writeTraceEvidenceExportFile(args.input, outPath, { format, attributes });
+    console.log(
+      `exported ${result2.spans.length} OpenInference span(s) from ${result2.format} \u2192 ${result2.path} (${result2.redactionCount} redaction${result2.redactionCount === 1 ? "" : "s"})`
+    );
+    return;
+  }
+  const result = await exportTraceEvidenceFile(args.input, { format, attributes });
+  process.stdout.write(serializeSpans(result.spans));
+}
+function parseAttributeValue(raw) {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(raw)) {
+    const number = Number(raw);
+    if (Number.isFinite(number)) return number;
+  }
+  return raw;
+}
+async function loadExportAttributes(args) {
+  const attributes = {};
+  if (args.metadata) {
+    const parsed = JSON.parse(await readFile(args.metadata, "utf8"));
+    if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("--metadata must point to a JSON object");
+    }
+    Object.assign(attributes, parsed);
+  }
+  for (const attr of args.attrs) {
+    const eq = attr.indexOf("=");
+    if (eq <= 0) throw new Error(`--attr must be key=value, got ${attr}`);
+    attributes[attr.slice(0, eq)] = parseAttributeValue(attr.slice(eq + 1));
+  }
+  return attributes;
+}
 async function cmdAnalyze(args) {
-  const { spans, harness, sessionCount } = await collectSpans(args);
+  const { spans, harness, sessionCount, cwds } = await collectSpans(args);
   if (spans.length === 0) throw new Error("no spans found for the given selection");
   const ai = args.llm ? await buildAxService() : void 0;
   const { otlpPath, result } = await analyzeSpans(spans, {
@@ -280,8 +518,12 @@ async function cmdAnalyze(args) {
 `)
   });
   const pipelines = await runPipelines(spans, { minLoopOccurrences: args.minLoop });
+  const reactions = analyzeReactions(spans);
+  const adoption = await analyzeAdoption(spans, { cwds });
   let report = `${renderReport(result, { harness, sessionCount, spanCount: spans.length, otlpPath })}
-${renderPipelines(pipelines)}`;
+${renderPipelines(pipelines)}
+${renderReactions(reactions)}
+${renderAdoption(adoption)}`;
   if (args.analyzers.length > 0 && otlpPath) {
     const engines = args.analyzers.map(
       (spec) => spec === "halo" ? haloAnalyzer({ defaultPrompt: args.analyzerPrompt, model: args.model }) : commandAnalyzer({ name: spec, command: spec, args: (p, prompt) => prompt ? [p, prompt] : [p] })
@@ -382,6 +624,32 @@ Window: since ${new Date(sinceMs).toISOString()}
     `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped.`
   );
 }
+function usageExport() {
+  console.log(`traces export \u2014 convert trace evidence files to OpenInference JSONL
+
+Usage:
+  traces export <input.jsonl|input.json> --out <spans.jsonl> [--format auto]
+  traces export <input.json> --attr task.id=abc --attr arm=baseline --out spans.jsonl
+  traces export <input.json> --metadata run-metadata.json --out spans.jsonl
+  traces export <input.jsonl|input.json> > spans.jsonl
+
+Input formats:
+  policy-evidence  Compact JSONL rows from \`traces evidence --out policy-evidence.jsonl\`
+  sandbox-events   Sandbox/OpenCode event arrays with start/raw/result/done/error events
+  openinference    Existing OpenInference JSONL; rewrites through traces redaction
+  auto             Detect the format from the file contents (default)
+
+Examples:
+  traces evidence --all --since 24h --out policy-evidence.jsonl
+  traces export policy-evidence.jsonl --out spans.openinference.jsonl
+  traces export sandbox-events.json --format sandbox-events --out spans.openinference.jsonl
+  traces export sandbox-events.json --attr task.id=aec-001 --attr outcome.score=1 --out spans.openinference.jsonl
+  halo spans.openinference.jsonl --prompt "Analyze this trace slice" --max-turns 1
+
+Safety:
+  export runs the same local regex redaction used by upload before writing spans.
+  --metadata must be a JSON object; --attr key=value is repeatable and overrides matching metadata keys.`);
+}
 function usage() {
   console.log(`traces \u2014 analyze, observe & upload coding-agent sessions
 
@@ -389,6 +657,10 @@ Commands:
   list      List discovered sessions
   analyze   Run analyst suite + loop/waste pipelines, write a markdown report
   convert   Emit OTLP-JSONL only (HALO: use analyze --analyzer halo)
+  index     Emit a reusable session index JSON for later investigation
+  inspect   Read a session index and print ranked improvement findings
+  export    Convert evidence/events files to OpenInference JSONL for HALO
+  evidence  Emit compact session-evidence JSONL for downstream policy miners
   watch     Online observer: tail active sessions, notify on stuck loops (read-only)
   upload    Redact + upload sessions in a time window to the Tangle Intelligence Platform
 
@@ -400,7 +672,10 @@ Options:
   --cwd <dir>      Filter sessions by working directory
   --since <t>      upload: window \u2014 30m / 2h / 7d or an ISO date (default 24h); analyze: ISO cutoff
   --out <path>     Write report to a file
-  --otlp <path>    OTLP artifact path (also the dry-run upload preview path)
+  --otlp <path>    OTLP artifact path (also evidence provenance / dry-run upload preview)
+  --format <kind>  export: auto | policy-evidence | sandbox-events | openinference
+  --metadata <json> export: attach JSON object fields as span attributes
+  --attr <k=v>     export: attach one span attribute (repeatable)
   --llm            Enable agentic RLM analysts (needs OPENAI_API_KEY / OPENAI_BASE_URL)
   --model <id>     --llm model id (e.g. a router model like glm-5.2); default is agent-eval's
   --budget <usd>   USD cap for agentic analysts
@@ -413,12 +688,22 @@ Options:
   --no-content     upload: strip prompt/response text \u2014 send metadata only
   --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the regex pass
   --yes, -y        upload: skip the confirmation prompt
+  --help, -h       Show help (use \`traces export --help\` for export examples)
 
 Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID`);
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    if (args.command === "export" || args.command === "help" && args.input === "export") usageExport();
+    else usage();
+    return;
+  }
   switch (args.command) {
+    case "help":
+      if (args.input === "export") usageExport();
+      else usage();
+      break;
     case "list":
       await cmdList(args);
       break;
@@ -428,6 +713,18 @@ async function main() {
     case "convert":
       await cmdConvert(args);
       break;
+    case "index":
+      await cmdIndex(args);
+      break;
+    case "inspect":
+      await cmdInspect(args);
+      break;
+    case "export":
+      await cmdExport(args);
+      break;
+    case "evidence":
+      await cmdEvidence(args);
+      break;
     case "watch":
       await cmdWatch(args);
       break;