@tangle-network/traces 0.15.4 → 0.15.5

package/dist/cli.js

@@ -8,6 +8,7 @@ import {
   appendAll,
   assembleSessionBundle,
   assertOutsideSourceBundle,
+  assessSpans,
   buildPolicyEvidenceRecord,
   buildSessionFactsReport,
   buildSessionIndexFromRows,
@@ -17,11 +18,13 @@ import {
   collectSessionSelection,
   commandAnalyzer,
   commandRedactor,
+  diffRuns,
   executeUpload,
   exportTraceEvidenceFile,
   externalFailureMessage,
   fileRunContextSupervisorRunReader,
   findingRejectionDetail,
+  formatVerdict,
   haloAnalyzer,
   hodoscopeAnalyzer,
   importCodeTraceBench,
@@ -34,6 +37,7 @@ import {
   locateSessions,
   mergeTracesConfig,
   normalizeTraceQuestions,
+  openAgenticTraceStore,
   parseSession,
   parseSince,
   planUpload,
@@ -41,7 +45,9 @@ import {
   projectSessionBundle,
   readOtlpInput,
   readSessionIndexFile,
+  redactSpans,
   renderInspectionReport,
+  renderRunDiff,
   renderSessionFacts,
   renderValidation,
   resolveAdapter,
@@ -59,18 +65,22 @@ import {
   streamSessions,
   totalAgenticFailureMessage,
   traceStreamEventsFromSpans,
+  tracesVersion,
   validationExitCode,
+  verdictExitCode,
   verifyFindingsInSandbox,
+  verifySafe,
   verifySessionBundle,
   watchRunTarget,
   watchSessions,
+  writeAnalysisTraceFile,
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceQuestionsArtifacts
-} from "./chunk-SKOW5V5U.js";
+} from "./chunk-RERVIGLH.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
@@ -89,11 +99,60 @@ import {
   renderSupervisorRunMarkdown,
   rollupSupervisorRuns
 } from "@tangle-network/agent-eval/supervisor-run";
-function packageVersion() {
-  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-  if (typeof pkg.version !== "string" || !pkg.version) throw new Error("package.json is missing version");
-  return pkg.version;
+
+// src/mcp.ts
+import { rm } from "fs/promises";
+import { dirname } from "path";
+import { buildTraceAnalysisToolDescriptors, redact, shareAllowed, UNTRUSTED_TRACE_TEXT } from "@tangle-network/agent-eval/traces";
+import { createStdioToolServer } from "@tangle-network/agent-runtime/mcp";
+var MCP_RESULT_BYTE_CAP = 512 * 1024;
+async function traceMcpTools(options) {
+  const { spans } = redactSpans(options.spans);
+  const verdict = assessSpans(spans);
+  if (!shareAllowed(verdict)) {
+    const findings = verdict.findings.map((f) => `${f.category}/${f.detector} (${f.count})`).join(", ");
+    throw new Error(
+      `mcp: refusing to serve \u2014 redacted spans are still ${verdict.status}` + (findings ? `: ${findings}` : "") + (verdict.unreadable.length > 0 ? `; unreadable: ${verdict.unreadable.join("; ")}` : "")
+    );
+  }
+  const file = await writeAnalysisTraceFile(spans);
+  const store = await openAgenticTraceStore(file);
+  const descriptors = buildTraceAnalysisToolDescriptors({ store }).filter((d) => d.name !== "readSpanSource");
+  const tools = descriptors.map((descriptor) => ({
+    name: descriptor.name,
+    description: descriptor.description,
+    inputSchema: descriptor.parameters,
+    annotations: {
+      readOnlyHint: descriptor.readOnly,
+      idempotentHint: descriptor.idempotent,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    handler: async (args) => {
+      const { value } = redact(await descriptor.handler(args));
+      const result = { untrusted: UNTRUSTED_TRACE_TEXT, result: value };
+      const bytes = Buffer.byteLength(JSON.stringify(result));
+      if (bytes > MCP_RESULT_BYTE_CAP) {
+        throw new RangeError(
+          `${descriptor.name}: result is ${bytes} bytes, above the ${MCP_RESULT_BYTE_CAP}-byte cap; narrow the request`
+        );
+      }
+      return result;
+    }
+  }));
+  return { tools, otlpPath: file.otlpPath };
 }
+async function serveTraceMcp(options) {
+  const { tools, otlpPath } = await traceMcpTools(options);
+  const server = createStdioToolServer({ serverName: "traces", serverVersion: tracesVersion(), tools });
+  try {
+    await server.serve();
+  } finally {
+    await rm(dirname(otlpPath), { recursive: true, force: true });
+  }
+}
+
+// src/cli.ts
 function parseArgs(argv) {
   const a = {
     command: argv[0] === "--help" || argv[0] === "-h" ? "help" : argv[0] ?? "help",
@@ -296,22 +355,14 @@ function parseArgs(argv) {
   }
   return a;
 }
-var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set(["analyze", "facts", "investigate", "improve", "ask", "stream", "validate"]);
-function migrateWritingOtlpFlag(args) {
-  if (args.otlp === void 0 || OTLP_INPUT_COMMANDS.has(args.command)) return args;
-  if (args.otlpOut !== void 0) {
+var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set(["analyze", "facts", "investigate", "improve", "ask", "stream", "validate", "mcp"]);
+function validateOtlpSelection(args) {
+  if (args.otlp === void 0) return args;
+  if (!OTLP_INPUT_COMMANDS.has(args.command)) {
     throw new Error(
-      `${args.command} was given both --otlp and --otlp-out. --otlp is the deprecated spelling of --otlp-out on writing commands; pass only --otlp-out.`
+      `${args.command} does not read --otlp. --otlp reads OTLP-JSONL on ${[...OTLP_INPUT_COMMANDS].join(", ")}; use --otlp-out <path> to write the artifact.`
     );
   }
-  console.error(
-    `warning: --otlp is deprecated on \`${args.command}\` and will be removed in 0.12. --otlp now READS OTLP-JSONL; use --otlp-out <path> to write the artifact. Treating it as --otlp-out for this run.`
-  );
-  return { ...args, otlpOut: args.otlp, otlp: void 0 };
-}
-function validateOtlpSelection(raw) {
-  const args = migrateWritingOtlpFlag(raw);
-  if (args.otlp === void 0) return args;
   if (args.input) throw new Error("--otlp cannot be combined with an input file");
   if (args.session) throw new Error("--otlp reads a file and cannot be combined with --session");
   if (args.supervisorRunDir) throw new Error("--otlp cannot be combined with --supervisor-run-dir");
@@ -686,6 +737,73 @@ async function cmdBundle(args) {
     `session bundle (${manifest.view} view) \u2192 ${result.directory}  (${manifest.files.length} file(s), ${manifest.ledgerSlices.length} ledger slice(s), ${manifest.absent.length} recorded absent)`
   );
 }
+async function cmdMcp(args) {
+  if (args.help) {
+    process.stdout.write(`traces mcp \u2014 read-only MCP server over stdio for the selected traces
+
+Usage:
+  traces mcp --otlp <file|dir>                  any OTLP-JSONL
+  traces mcp --harness claude-code --last 5     recent harness sessions (any selection flag)
+
+Register with a client, for example:
+  claude mcp add traces -- traces mcp --otlp ./spans.otlp.jsonl
+
+Every tool is read-only and idempotent and says so in its MCP annotations.
+Spans (including causal links) and results are redacted, the server refuses
+to start if the redacted spans are still UNSAFE or UNKNOWN, each result
+carries an untrusted-text notice, and a result above 512 KiB is refused
+rather than truncated. readSpanSource is not served: windowed reads of
+original source bytes cannot be redacted.
+`);
+    return;
+  }
+  const selected = validateOtlpSelection(validateWorkflowSelection(applyCurrentSessionSelection(args)));
+  const collected = await collectSpans(selected);
+  if (collected.spans.length === 0) throw new Error("mcp: no spans found for the given selection");
+  warnIncompleteWorkflow(collected.workflow);
+  process.stderr.write(`traces mcp: serving ${collected.spans.length} span(s) over stdio
+`);
+  await serveTraceMcp({ spans: collected.spans });
+}
+async function cmdDiff(argv) {
+  const inputs = [];
+  const kinds = [];
+  let format = "text";
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      process.stdout.write(`traces diff \u2014 where two runs of one task first diverge
+
+Usage:
+  traces diff <a> <b> [--kind TOOL]... [--format text|json]
+
+Each side is an OTLP file or directory, any file convert reads, file#<trace id>,
+or file#branch=<id> for one arm (agent.branch.id or agent.branch.arm, and every
+span below it \u2014 refused if the label names more than one subtree). Steps pair
+by span id, then position with the same name and kind, then name and kind
+anywhere. Exit 0 when the runs agree on outcome, 1 when they diverge, 2 when a
+side cannot be read, 3 when the steps line up with no divergence but neither
+side carries a definitive OK/ERROR status or a TOOL step \u2014 there is no
+recorded outcome to call agreement on.
+`);
+      return;
+    }
+    if (arg === "--format") format = argv[++i] ?? "";
+    else if (arg === "--kind") kinds.push(argv[++i] ?? "");
+    else if (arg.startsWith("--")) throw new Error(`diff: unknown flag ${arg}`);
+    else inputs.push(arg);
+  }
+  if (inputs.length !== 2) {
+    throw new Error("diff needs two runs: traces diff <a> <b> (a file, a directory, file#<trace id> or file#branch=<id>)");
+  }
+  if (format !== "json" && format !== "text") throw new Error(`diff: --format must be json or text, got "${format}"`);
+  if (kinds.some((kind) => !kind)) throw new Error("diff: --kind needs a span kind, e.g. --kind TOOL");
+  const report = await diffRuns(inputs[0], inputs[1], { kinds });
+  process.stdout.write(format === "json" ? `${JSON.stringify(report, null, 2)}
+` : renderRunDiff(report));
+  if (report.diff.firstDivergence) process.exitCode = 1;
+  else if (report.caveat) process.exitCode = 3;
+}
 async function cmdBundleVerify(argv) {
   let dir;
   let format = "text";
@@ -1296,11 +1414,11 @@ async function cmdUpload(args) {
   const redactorParts = args.redactorCmd?.split(/\s+/).filter(Boolean) ?? [];
   const redactor = redactorParts[0] ? commandRedactor({ command: redactorParts[0], args: redactorParts.slice(1) }) : void 0;
   const candidates = plan.items;
-  const byRule = {};
+  const byDetector = {};
   let totalRedactions = 0;
   for (const i of candidates) {
     totalRedactions += i.redaction.redactionCount;
-    for (const [r, n] of Object.entries(i.redaction.byRule)) byRule[r] = (byRule[r] ?? 0) + n;
+    for (const [r, n] of Object.entries(i.redaction.byDetector)) byDetector[r] = (byDetector[r] ?? 0) + n;
   }
   const w = (s) => process.stderr.write(s);
   w(`
@@ -1308,7 +1426,7 @@ Window: since ${new Date(sinceMs).toISOString()}
 `);
   w(`Sessions found: ${plan.items.length}  \xB7  final privacy-mode dedup runs before upload
 `);
-  w(`PII/secrets redacted: ${totalRedactions}${Object.keys(byRule).length ? ` (${Object.entries(byRule).map(([r, n]) => `${r}:${n}`).join(", ")})` : ""}
+  w(`PII/secrets redacted: ${totalRedactions}${Object.keys(byDetector).length ? ` (${Object.entries(byDetector).map(([r, n]) => `${r}:${n}`).join(", ")})` : ""}
 `);
   for (const i of candidates.slice(0, 25)) {
     w(`  + [${i.ref.harness}] ${i.ref.sessionId.slice(0, 8)}  ${i.spans.length} spans  ${i.redaction.redactionCount} redacted  ${i.ref.cwd ?? ""}
@@ -1322,7 +1440,8 @@ Window: since ${new Date(sinceMs).toISOString()}
   }
   if (args.dryRun) {
     const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlpOut, stripContent: args.noContent, redactor });
-    console.log(`dry run: ${candidates.length - res2.skippedSessions} session(s), ${totalRedactions} redaction(s). Redacted OTLP -> ${res2.otlpPath}`);
+    reportRefused(res2.refused);
+    console.log(`dry run: ${candidates.length - res2.skippedSessions - res2.refused.length} session(s), ${totalRedactions} redaction(s). Redacted OTLP -> ${res2.otlpPath}`);
     console.log("No upload performed. Set TANGLE_INGEST_URL / TANGLE_INGEST_API_KEY / TANGLE_TENANT_ID and drop --dry-run to send.");
     return;
   }
@@ -1335,10 +1454,79 @@ Window: since ${new Date(sinceMs).toISOString()}
   }
   const res = await executeUpload(plan, { log: (m) => w(`${m}
 `), stripContent: args.noContent, redactor });
+  reportRefused(res.refused);
   console.log(
-    `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped.`
+    `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped; ${res.refused.length} refused.`
   );
 }
+function reportRefused(refused) {
+  for (const { harness, sessionId, verdict } of refused) {
+    process.stderr.write(`  REFUSED [${harness}] ${sessionId.slice(0, 8)}: ${verdict.status}
+`);
+    for (const finding of verdict.findings.filter((f) => f.severity === "error")) {
+      process.stderr.write(`    ${finding.category}/${finding.detector} x${finding.count} at ${finding.paths.join(", ")}
+`);
+    }
+    for (const entry of verdict.unreadable) process.stderr.write(`    unread ${entry}
+`);
+  }
+  if (refused.length > 0) {
+    process.stderr.write(`${refused.length} session(s) refused by the share-safety check and kept on this machine.
+`);
+    process.exitCode = 1;
+  }
+}
+async function cmdVerifySafe(argv) {
+  let target;
+  let format = "text";
+  let profile = "share";
+  const knownSecrets = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--format") format = argv[++i] ?? "";
+    else if (arg === "--profile") profile = argv[++i] ?? "";
+    else if (arg === "--known-secret-env") {
+      const name = argv[++i] ?? "";
+      const value = process.env[name];
+      if (!value) throw new Error(`verify-safe: environment variable ${name || "(missing name)"} is not set`);
+      knownSecrets.push(value);
+    } else if (arg === "--help" || arg === "-h") {
+      usageVerifySafe();
+      return;
+    } else if (arg.startsWith("--")) throw new Error(`verify-safe: unknown flag ${arg}`);
+    else if (target === void 0) target = arg;
+    else throw new Error(`verify-safe: unexpected argument ${arg}`);
+  }
+  if (!target) throw new Error("verify-safe needs a file or directory: traces verify-safe <file|dir>");
+  if (format !== "json" && format !== "text") throw new Error(`verify-safe: --format must be json or text, got "${format}"`);
+  if (profile !== "default" && profile !== "share" && profile !== "strict") {
+    throw new Error(`verify-safe: --profile must be default, share or strict, got "${profile}"`);
+  }
+  const result = await verifySafe(target, { profile, knownSecrets });
+  process.stdout.write(format === "json" ? `${JSON.stringify(result, null, 2)}
+` : `${formatVerdict(result)}
+`);
+  process.exitCode = verdictExitCode(result);
+}
+function usageVerifySafe() {
+  console.log(`traces verify-safe <file|dir> [--profile default|share|strict] [--known-secret-env NAME]... [--format text|json]
+
+Check whether files are safe to share, without changing them. A directory is read
+recursively. .json files are parsed whole, .jsonl and .ndjson line by line, and
+any other file is scanned as text.
+
+  SAFE                 nothing found                                   exit 0
+  SAFE_WITH_WARNINGS   only warnings (raw content, identifiers, media) exit 0
+  UNSAFE               a credential, or personal data under share/strict exit 1
+  UNKNOWN              a file, line or byte range could not be read      exit 2
+
+--profile           default | share (default) | strict; see agent-eval docs/redaction.md
+--known-secret-env  name of an environment variable holding a secret to look for in
+                    any encoding (repeatable); the value is never printed
+--format            text (default) | json
+
+Findings name the file, line and JSON Pointer, never the matched value.`);
+}
 function usageExport() {
   console.log(`traces export: convert trace evidence files to OpenInference JSONL
 
@@ -1365,7 +1553,7 @@ Examples:
   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.
+  export runs the same local redaction (agent-eval's redaction core) used by upload before writing spans.
   --metadata must be a JSON object; --attr key=value is repeatable and overrides matching metadata keys.`);
 }
 function usageImportCodeTraceBench() {
@@ -1447,7 +1635,8 @@ Commands:
   facts     Print the deterministic session-facts sheet for the selected
             sessions: tool calls excluding synthesized spans, subagent spawns
             with task names, human turns in order, the final message per task,
-            changed paths, first/last record times, and the harness token total.
+            changed paths, first/last record times, the harness token total, and
+            the first failure by agent-eval's fixed precedence (or none).
             No model call, no budget, $0. Every fact names the span ids it came
             from; a fact the spans cannot support is null with its reason.
             --format json (default) or text (exit 1 when a session cannot be read)
@@ -1458,6 +1647,17 @@ Commands:
             ledger sliced to the session window, git log, and a sha256 manifest
             (needs --session <id|path> and --out <new-dir>). This is the FULL
             view: it holds the session's own words, for a reader who cites them
+  mcp       Serve the selected traces to an MCP client over stdio: 7 read-only,
+            idempotent trace tools; spans and results redacted, results capped
+            and marked untrusted (traces mcp --help)
+  diff <a> <b>
+            Pair two runs' steps (by span id, then position with the same name
+            and kind, then name and kind anywhere) and mark the first divergence:
+            changed, replaced, only-in-a, only-in-b or reordered. Each side is an
+            OTLP file or directory, any file convert reads, file#<trace id>, or
+            file#branch=<id> for one arm (agent.branch.id or agent.branch.arm).
+            --kind TOOL (repeatable) keeps only steps of that span kind.
+            Exit 0 agree, 1 diverge, 2 unreadable (--format text|json)
   bundle verify <bundle-dir>
             Check a bundle against its manifest: every listed file present with
             its recorded size and SHA-256, no unlisted or non-regular file beside
@@ -1487,7 +1687,11 @@ Commands:
   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
+  upload    Redact + upload sessions in a time window to the Tangle Intelligence Platform;
+            a session whose final events are UNSAFE or UNKNOWN is refused (exit 1)
+  verify-safe <file|dir>
+            Say whether files are safe to share: SAFE, SAFE_WITH_WARNINGS, UNSAFE
+            (exit 1) or UNKNOWN (exit 2). Read-only (--help for flags)
 
 Options:
   --harness <id>   Harness or alias (default: claude-code). Known: ${knownHarnesses().join(", ")}
@@ -1513,9 +1717,8 @@ Options:
                    A directory reads the OTLP files under it \u2014 only the otlp/
                    subdirectory when the producer made one \u2014 and names the JSONL
                    that is not OTLP instead of reading it as broken spans.
-                   Supported by: validate, analyze, investigate, improve, ask, stream.
-                   On a WRITING command it is the deprecated spelling of
-                   --otlp-out; it still works, with a warning, until 0.12.
+                   Supported by: validate, analyze, facts, investigate, improve, ask,
+                   stream, mcp. Writing commands take --otlp-out.
   --source-bundle <dir>  Analyze a retained full bundle; explicitly grant source-field reads.
                    Available for analyze, investigate, improve, and ask.
   --otlp-out <path>  WRITE the OTLP-JSONL artifact here (also evidence
@@ -1567,7 +1770,7 @@ Options:
   --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
   --no-content     upload: strip prompt/response text; send metadata only
-  --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the regex pass
+  --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the redaction core
   --yes, -y        upload: skip the confirmation prompt
   --version, -v    Print the installed traces version
   --help, -h       Show help (use \`traces validate --help\`, \`traces export --help\`,
@@ -1585,7 +1788,7 @@ Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KE
 async function main() {
   const rawArgs = process.argv.slice(2);
   if (rawArgs[0] === "--version" || rawArgs[0] === "-v" || rawArgs[0] === "version") {
-    console.log(`traces ${packageVersion()}`);
+    console.log(`traces ${tracesVersion()}`);
     return;
   }
   if (rawArgs[0] === "replay-verify") {
@@ -1600,10 +1803,28 @@ async function main() {
     await cmdVerifyFindings(rawArgs.slice(1));
     return;
   }
+  if (rawArgs[0] === "mcp") {
+    await cmdMcp(parseArgs(rawArgs));
+    return;
+  }
+  if (rawArgs[0] === "diff") {
+    try {
+      await cmdDiff(rawArgs.slice(1));
+    } catch (err) {
+      process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exitCode = 2;
+    }
+    return;
+  }
   if (rawArgs[0] === "bundle" && rawArgs[1] === "verify") {
     await cmdBundleVerify(rawArgs.slice(2));
     return;
   }
+  if (rawArgs[0] === "verify-safe") {
+    await cmdVerifySafe(rawArgs.slice(1));
+    return;
+  }
   const parsedArgs = parseArgs(rawArgs);
   if (parsedArgs.help) {
     if (parsedArgs.command === "import-codetracebench" || parsedArgs.command === "help" && parsedArgs.input === "import-codetracebench") usageImportCodeTraceBench();