@tangle-network/traces 0.5.0 → 0.7.0

package/README.md

@@ -18,6 +18,7 @@ It reads the transcripts your harness leaves on disk, reconstructs the run as sp
 - [Supported harnesses](#supported-harnesses)
 - [CLI reference](#cli-reference)
 - [Upload to the Intelligence Platform](#upload-to-the-intelligence-platform)
+- [External engines (bring your own)](#external-engines-bring-your-own)
 - [Library (SDK)](#library-sdk)
 - [Examples](#examples)
 - [Develop](#develop)
@@ -42,7 +43,7 @@ That's the command in the demo above. The **deterministic pass** — stuck loops
 
 Add `--llm` for the **agentic analysts** (failure-mode / knowledge-gap / knowledge-poisoning / improvement); they call OpenAI and respect `--budget <usd>`.
 
-Every run also writes an **OTLP-JSONL artifact** that feeds [HALO](https://github.com/context-labs/halo) (`halo spans.jsonl -p "diagnose"`) — analysis is never locked to one engine.
+Every run also writes an **OTLP-JSONL artifact**, and you can run external engines like [HALO](https://github.com/context-labs/halo) over it with `--analyzer halo` (traces converts our spans to the canonical OpenInference shape HALO needs) — see [External engines](#external-engines-bring-your-own). Analysis is never locked to one engine.
 
 ## What it finds
 
@@ -129,6 +130,31 @@ It does **not** catch free-form PII — names, postal addresses, phone numbers i
 
 Always `--dry-run` first to see exactly what would be sent.
 
+## External engines (bring your own)
+
+`traces` hosts analysis engines and PII scrubbers it does **not** bundle — you install the tool, `traces` drives it over a thin command adapter. Same pattern for any future engine or model.
+
+**Analyzers** run over the emitted OTLP artifact as peers to the built-in analysts:
+
+```bash
+traces analyze --last 1 --analyzer halo                         # run HALO too
+traces analyze --last 1 --analyzer halo --analyzer-prompt "find token waste"
+traces analyze --last 1 --analyzer halo --analyzer my-engine    # repeatable
+```
+
+HALO needs canonical OpenInference, so `--analyzer halo` converts our spans automatically (`toCanonicalOpenInference`). HALO runs its *own* LLM (OpenAI client — set `OPENAI_BASE_URL` / `OPENAI_API_KEY`, or use HALO's provider); `--model` is forwarded to it. traces supplies the trace and drives the CLI; it doesn't pay for or configure HALO's model.
+
+**Redactors** scrub prompt/response prose with an external PII model (catching names/addresses the regex pass can't), running *after* the built-in redaction:
+
+```bash
+# the command reads a JSON array of strings on stdin, writes the scrubbed array on stdout
+traces upload --since 24h --dry-run --redactor "my-pii-scrubber"
+```
+
+In the SDK these are the `ExternalAnalyzer` and `Redactor` interfaces (`haloAnalyzer`, `commandAnalyzer`, `commandRedactor`, `applyRedactor`, `runExternalAnalyzers`). See [`examples/external-engines.ts`](./examples/external-engines.ts).
+
+> For the built-in agentic analysts (`--llm`), set `OPENAI_API_KEY` — or point at any OpenAI-compatible gateway with `OPENAI_BASE_URL` (e.g. an internal router) to use a non-OpenAI key.
+
 ## Library (SDK)
 
 The CLI is a thin consumer of these exports.
@@ -143,6 +169,7 @@ The CLI is a thin consumer of these exports.
 | `planUpload` / `executeUpload` | `(…, { backend? }) → …` | redact + dedup + send to any sink |
 | `selectAdapters` / `listAdapters` / `resolveAdapter` | adapter selection + the harness registry |
 | `HarnessTraceAdapter` | interface (`locate` + `parse`) | implement to add a harness |
+| `ExternalAnalyzer` / `Redactor` | `haloAnalyzer` / `commandAnalyzer` / `commandRedactor` | drive engines/models you install (not bundled) |
 
 ```ts
 import { watchSessions, analyzeSpans, AnalystRegistry, makeFinding } from '@tangle-network/traces'
@@ -172,6 +199,7 @@ Runnable, in [`examples/`](./examples):
 | [`custom-analyst.ts`](./examples/custom-analyst.ts) | register and run your own analyst |
 | [`custom-backend.ts`](./examples/custom-backend.ts) | redact + dedup + upload to your own sink |
 | [`register-harness.ts`](./examples/register-harness.ts) | add a new harness by implementing `HarnessTraceAdapter` |
+| [`external-engines.ts`](./examples/external-engines.ts) | drive HALO + an external PII scrubber you install yourself |
 
 ## Develop
 

package/dist/{chunk-HF2KGEBW.js → chunk-Q56AP2EY.js}

@@ -31,11 +31,11 @@ function serializeSpans(spans) {
 `;
 }
 async function writeOtlpFile(spans, outPath) {
-  const { mkdtemp, writeFile: writeFile2 } = await import("fs/promises");
+  const { mkdtemp, writeFile: writeFile3 } = await import("fs/promises");
   const { tmpdir } = await import("os");
   const { join: join13 } = await import("path");
   const path = outPath ?? join13(await mkdtemp(join13(tmpdir(), "traces-")), "spans.otlp.jsonl");
-  await writeFile2(path, serializeSpans(spans), "utf8");
+  await writeFile3(path, serializeSpans(spans), "utf8");
   return path;
 }
 
@@ -70,6 +70,151 @@ async function analyzeSpans(spans, opts = {}) {
   return { otlpPath, result };
 }
 
+// src/external.ts
+import { spawn } from "child_process";
+import { readFile, writeFile } from "fs/promises";
+function runCommand(command, args = [], opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const maxBuffer = opts.maxBuffer ?? 32 * 1024 * 1024;
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(command, [...args], { signal: opts.signal });
+    } catch (err2) {
+      reject(err2 instanceof Error ? err2 : new Error(String(err2)));
+      return;
+    }
+    let out = "";
+    let err = "";
+    let killed = false;
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill("SIGKILL");
+      reject(new Error(`${command}: timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const cap = (add, buf) => {
+      const next = buf + add;
+      if (next.length > maxBuffer) {
+        killed = true;
+        child.kill("SIGKILL");
+        clearTimeout(timer);
+        reject(new Error(`${command}: output exceeded ${maxBuffer} bytes`));
+      }
+      return next;
+    };
+    child.stdout?.on("data", (d) => {
+      out = cap(String(d), out);
+    });
+    child.stderr?.on("data", (d) => {
+      err = cap(String(d), err);
+    });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      if (!killed) reject(e);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (!killed) resolve({ stdout: out, stderr: err, code });
+    });
+    if (opts.input !== void 0) {
+      child.stdin?.on("error", () => {
+      });
+      child.stdin?.end(opts.input);
+    }
+  });
+}
+function commandAnalyzer(spec) {
+  return {
+    name: spec.name,
+    async analyze(otlpPath, opts = {}) {
+      try {
+        const res = await runCommand(spec.command, spec.args(otlpPath, opts.prompt), {
+          signal: opts.signal,
+          timeoutMs: spec.timeoutMs
+        });
+        if (res.code !== 0) {
+          return { analyzer: spec.name, ok: false, output: res.stdout, error: res.stderr.trim() || `exit ${res.code}` };
+        }
+        return { analyzer: spec.name, ok: true, output: res.stdout.trim(), findings: spec.parse?.(res.stdout) };
+      } catch (e) {
+        return { analyzer: spec.name, ok: false, output: "", error: e instanceof Error ? e.message : String(e) };
+      }
+    }
+  };
+}
+function toCanonicalOpenInference(otlpJsonl, opts = {}) {
+  return otlpJsonl.split("\n").filter((l) => l.trim()).map((line) => {
+    const s = JSON.parse(line);
+    const a = s.attributes ?? {};
+    const resourceAttrs = { "service.name": a["service.name"] ?? opts.service ?? "traces" };
+    if (a["agent.name"]) resourceAttrs["agent.name"] = a["agent.name"];
+    return JSON.stringify({
+      trace_id: s.trace_id,
+      span_id: s.span_id,
+      parent_span_id: s.parent_span_id ?? "",
+      trace_state: "",
+      name: s.name,
+      kind: a["openinference.span.kind"] ?? "CHAIN",
+      start_time: s.start_time,
+      end_time: s.end_time,
+      status: { code: s.status?.code ?? "OK", message: s.status?.message ?? "" },
+      resource: { attributes: resourceAttrs },
+      scope: { name: opts.scopeName ?? "tangle-traces", version: "" },
+      attributes: a
+    });
+  }).join("\n");
+}
+function haloAnalyzer(opts = {}) {
+  const command = opts.command ?? "halo";
+  const defaultPrompt = opts.defaultPrompt ?? "diagnose";
+  return {
+    name: "halo",
+    async analyze(otlpPath, o = {}) {
+      try {
+        const canonical = toCanonicalOpenInference(await readFile(otlpPath, "utf8"));
+        const canonPath = `${otlpPath}.halo.jsonl`;
+        await writeFile(canonPath, canonical);
+        const args = [canonPath, "-p", o.prompt ?? defaultPrompt];
+        if (opts.model) args.push("-m", opts.model);
+        const res = await runCommand(command, args, { signal: o.signal, timeoutMs: opts.timeoutMs });
+        if (res.code !== 0) {
+          return { analyzer: "halo", ok: false, output: res.stdout, error: res.stderr.trim() || `exit ${res.code}` };
+        }
+        return { analyzer: "halo", ok: true, output: res.stdout.trim() };
+      } catch (e) {
+        return { analyzer: "halo", ok: false, output: "", error: e instanceof Error ? e.message : String(e) };
+      }
+    }
+  };
+}
+function runExternalAnalyzers(otlpPath, analyzers, opts = {}) {
+  return Promise.all(analyzers.map((a) => a.analyze(otlpPath, opts)));
+}
+function commandRedactor(spec) {
+  const name = spec.name ?? spec.command;
+  return {
+    name,
+    async redactText(texts) {
+      if (texts.length === 0) return [];
+      const res = await runCommand(spec.command, spec.args ?? [], {
+        input: JSON.stringify(texts),
+        timeoutMs: spec.timeoutMs
+      });
+      if (res.code !== 0) throw new Error(`redactor ${name}: exit ${res.code}: ${res.stderr.trim()}`);
+      let parsed;
+      try {
+        parsed = JSON.parse(res.stdout);
+      } catch {
+        throw new Error(`redactor ${name}: stdout was not JSON`);
+      }
+      if (!Array.isArray(parsed) || parsed.length !== texts.length) {
+        throw new Error(`redactor ${name}: expected a JSON array of ${texts.length} strings`);
+      }
+      return parsed.map(String);
+    }
+  };
+}
+
 // src/time.ts
 function parseIsoToEpochMs(ts) {
   if (!ts) return 0;
@@ -162,7 +307,7 @@ function userPromptSpan(o) {
 }
 
 // src/adapters/amp.ts
-import { readdir, readFile, stat } from "fs/promises";
+import { readdir, readFile as readFile2, stat } from "fs/promises";
 import { homedir } from "os";
 import { basename, join } from "path";
 var SERVICE = "amp";
@@ -204,7 +349,7 @@ var AmpAdapter = class {
   async parse(ref) {
     let thread;
     try {
-      thread = JSON.parse(await readFile(ref.path, "utf8"));
+      thread = JSON.parse(await readFile2(ref.path, "utf8"));
     } catch {
       return [];
     }
@@ -288,7 +433,7 @@ var AmpAdapter = class {
 };
 
 // src/adapters/claude.ts
-import { readdir as readdir2, readFile as readFile2, stat as stat2 } from "fs/promises";
+import { readdir as readdir2, readFile as readFile3, stat as stat2 } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { basename as basename2, join as join2 } from "path";
 var SERVICE2 = "claude-code";
@@ -449,7 +594,7 @@ var ClaudeAdapter = class {
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
   }
   async parse(ref) {
-    const raw = await readFile2(ref.path, "utf8");
+    const raw = await readFile3(ref.path, "utf8");
     const events = parseLines(raw);
     const traceId = events.find((e) => e.sessionId)?.sessionId ?? ref.sessionId;
     const rootId = `root:${traceId}`;
@@ -492,13 +637,13 @@ var ClaudeAdapter = class {
       const hash = basename2(f, ".jsonl");
       let meta = {};
       try {
-        meta = JSON.parse(await readFile2(join2(subDir, `${hash}.meta.json`), "utf8"));
+        meta = JSON.parse(await readFile3(join2(subDir, `${hash}.meta.json`), "utf8"));
       } catch {
       }
       const parent = meta.toolUseId && main.toolSpanByUseId.get(meta.toolUseId)?.span_id || `root:${traceId}`;
       let raw;
       try {
-        raw = await readFile2(join2(subDir, f), "utf8");
+        raw = await readFile3(join2(subDir, f), "utf8");
       } catch {
         continue;
       }
@@ -516,7 +661,7 @@ var ClaudeAdapter = class {
 };
 
 // src/adapters/codex.ts
-import { readdir as readdir3, readFile as readFile3, stat as stat3 } from "fs/promises";
+import { readdir as readdir3, readFile as readFile4, stat as stat3 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import { basename as basename3, join as join3 } from "path";
 var SERVICE3 = "codex";
@@ -600,7 +745,7 @@ var CodexAdapter = class {
         continue;
       }
       if (opts.sinceMs && st.mtimeMs < opts.sinceMs) continue;
-      const head = (await readFile3(path, "utf8").catch(() => "")).split("\n", 1)[0] ?? "";
+      const head = (await readFile4(path, "utf8").catch(() => "")).split("\n", 1)[0] ?? "";
       let cwd = null;
       let id = basename3(path).replace(/^rollout-[\dT-]+-/, "").replace(/\.jsonl$/, "");
       try {
@@ -615,7 +760,7 @@ var CodexAdapter = class {
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
   }
   async parse(ref) {
-    const lines = parseLines2(await readFile3(ref.path, "utf8"));
+    const lines = parseLines2(await readFile4(ref.path, "utf8"));
     const meta = lines.find((l) => l.type === "session_meta");
     const traceId = meta?.payload?.id ?? ref.sessionId;
     const model = lines.find((l) => l.type === "turn_context")?.payload?.model ?? null;
@@ -731,7 +876,7 @@ var CodexAdapter = class {
 };
 
 // src/adapters/copilot.ts
-import { readdir as readdir4, readFile as readFile4, stat as stat4 } from "fs/promises";
+import { readdir as readdir4, readFile as readFile5, stat as stat4 } from "fs/promises";
 import { homedir as homedir4 } from "os";
 import { join as join4 } from "path";
 var SERVICE4 = "github-copilot";
@@ -776,7 +921,7 @@ var CopilotAdapter = class {
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
   }
   async parse(ref) {
-    const events = parseLines3(await readFile4(ref.path, "utf8"));
+    const events = parseLines3(await readFile5(ref.path, "utf8"));
     const traceId = ref.sessionId;
     const rootId = `root:${traceId}`;
     const spans = [
@@ -857,7 +1002,7 @@ var CopilotAdapter = class {
 };
 
 // src/adapters/factory.ts
-import { readdir as readdir5, readFile as readFile5, stat as stat5 } from "fs/promises";
+import { readdir as readdir5, readFile as readFile6, stat as stat5 } from "fs/promises";
 import { homedir as homedir5 } from "os";
 import { basename as basename4, join as join5 } from "path";
 var SERVICE5 = "factory";
@@ -918,13 +1063,13 @@ var FactoryAdapter = class {
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
   }
   async parse(ref) {
-    const lines = parseLines4(await readFile5(ref.path, "utf8"));
+    const lines = parseLines4(await readFile6(ref.path, "utf8"));
     const start = lines.find((l) => l.type === "session_start");
     const traceId = start?.id ?? ref.sessionId;
     const rootId = `root:${traceId}`;
     let settings = {};
     try {
-      settings = JSON.parse(await readFile5(ref.path.replace(/\.jsonl$/, ".settings.json"), "utf8"));
+      settings = JSON.parse(await readFile6(ref.path.replace(/\.jsonl$/, ".settings.json"), "utf8"));
     } catch {
     }
     const spans = [
@@ -1018,7 +1163,7 @@ var FactoryAdapter = class {
 };
 
 // src/adapters/forge.ts
-import { readdir as readdir6, readFile as readFile6, stat as stat6 } from "fs/promises";
+import { readdir as readdir6, readFile as readFile7, stat as stat6 } from "fs/promises";
 import { homedir as homedir6 } from "os";
 import { basename as basename5, join as join6 } from "path";
 var SERVICE6 = "forge";
@@ -1064,7 +1209,7 @@ var ForgeAdapter = class {
   async parse(ref) {
     let dump;
     try {
-      dump = JSON.parse(await readFile6(ref.path, "utf8"));
+      dump = JSON.parse(await readFile7(ref.path, "utf8"));
     } catch {
       return [];
     }
@@ -1148,7 +1293,7 @@ var ForgeAdapter = class {
 };
 
 // src/adapters/gemini.ts
-import { readdir as readdir7, readFile as readFile7, stat as stat7 } from "fs/promises";
+import { readdir as readdir7, readFile as readFile8, stat as stat7 } from "fs/promises";
 import { homedir as homedir7 } from "os";
 import { join as join7 } from "path";
 function iso(ts, fallback) {
@@ -1213,7 +1358,7 @@ var GeminiFamilyAdapter = class {
   async parse(ref) {
     let session;
     try {
-      session = JSON.parse(await readFile7(ref.path, "utf8"));
+      session = JSON.parse(await readFile8(ref.path, "utf8"));
     } catch {
       return [];
     }
@@ -1307,7 +1452,7 @@ var GeminiAdapter = class extends GeminiFamilyAdapter {
 };
 
 // src/adapters/opencode.ts
-import { readdir as readdir8, readFile as readFile8, stat as stat8 } from "fs/promises";
+import { readdir as readdir8, readFile as readFile9, stat as stat8 } from "fs/promises";
 import { homedir as homedir8 } from "os";
 import { join as join8 } from "path";
 var SERVICE7 = "opencode";
@@ -1362,7 +1507,7 @@ var OpencodeAdapter = class {
     const messages = [];
     for (const f of msgFiles) {
       try {
-        messages.push({ msg: JSON.parse(await readFile8(join8(ref.path, f), "utf8")), file: f });
+        messages.push({ msg: JSON.parse(await readFile9(join8(ref.path, f), "utf8")), file: f });
       } catch {
       }
     }
@@ -1390,7 +1535,7 @@ var OpencodeAdapter = class {
         const partFiles = (await readdir8(pdir)).filter((f) => f.endsWith(".json"));
         for (const pf of partFiles) {
           try {
-            parts.push(JSON.parse(await readFile8(join8(pdir, pf), "utf8")));
+            parts.push(JSON.parse(await readFile9(join8(pdir, pf), "utf8")));
           } catch {
           }
         }
@@ -1460,7 +1605,7 @@ var OpencodeAdapter = class {
 };
 
 // src/adapters/pi.ts
-import { readdir as readdir9, readFile as readFile9, stat as stat9 } from "fs/promises";
+import { readdir as readdir9, readFile as readFile10, stat as stat9 } from "fs/promises";
 import { homedir as homedir9 } from "os";
 import { basename as basename6, join as join9 } from "path";
 var SERVICE8 = "pi";
@@ -1528,7 +1673,7 @@ var PiAdapter = class {
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
   }
   async parse(ref) {
-    const lines = parseLines5(await readFile9(ref.path, "utf8"));
+    const lines = parseLines5(await readFile10(ref.path, "utf8"));
     const sessionLine = lines.find((l) => l.type === "session");
     const traceId = sessionLine?.id ?? ref.sessionId;
     const rootId = `root:${traceId}`;
@@ -1629,7 +1774,7 @@ var PiAdapter = class {
 };
 
 // src/adapters/qwen.ts
-import { readdir as readdir10, readFile as readFile10, stat as stat10 } from "fs/promises";
+import { readdir as readdir10, readFile as readFile11, stat as stat10 } from "fs/promises";
 import { homedir as homedir10 } from "os";
 import { basename as basename7, join as join10 } from "path";
 var SERVICE9 = "qwen";
@@ -1688,7 +1833,7 @@ var QwenAdapter = class {
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
   }
   async parse(ref) {
-    const records = parseLines6(await readFile10(ref.path, "utf8"));
+    const records = parseLines6(await readFile11(ref.path, "utf8"));
     const traceId = records.find((r) => r.sessionId)?.sessionId ?? ref.sessionId;
     const rootId = `root:${traceId}`;
     const spans = [
@@ -1988,10 +2133,32 @@ function redactSpans(spans, rules = TRACES_REDACTION_RULES) {
   });
   return { spans: out, report };
 }
+async function applyRedactor(spans, redactor) {
+  const idx = [];
+  const texts = [];
+  spans.forEach((s, i) => {
+    const c = s.attributes["content"];
+    if (typeof c === "string" && c.length > 0) {
+      idx.push(i);
+      texts.push(c);
+    }
+  });
+  const out = spans.map((s) => ({ ...s, attributes: { ...s.attributes } }));
+  if (texts.length === 0) return { spans: out, changed: 0 };
+  const scrubbed = await redactor.redactText(texts);
+  let changed = 0;
+  idx.forEach((spanI, k) => {
+    if (scrubbed[k] !== texts[k]) {
+      out[spanI].attributes["content"] = scrubbed[k];
+      changed += 1;
+    }
+  });
+  return { spans: out, changed };
+}
 
 // src/upload-state.ts
 import { createHash } from "crypto";
-import { mkdir, readFile as readFile11, writeFile } from "fs/promises";
+import { mkdir, readFile as readFile12, writeFile as writeFile2 } from "fs/promises";
 import { homedir as homedir11 } from "os";
 import { dirname, join as join11 } from "path";
 function stateFile() {
@@ -2011,7 +2178,7 @@ function sessionHash(spans) {
 }
 async function loadState() {
   try {
-    return JSON.parse(await readFile11(stateFile(), "utf8"));
+    return JSON.parse(await readFile12(stateFile(), "utf8"));
   } catch {
     return {};
   }
@@ -2019,7 +2186,7 @@ async function loadState() {
 async function saveState(state) {
   const f = stateFile();
   await mkdir(dirname(f), { recursive: true });
-  await writeFile(f, `${JSON.stringify(state, null, 2)}
+  await writeFile2(f, `${JSON.stringify(state, null, 2)}
 `, "utf8");
 }
 function alreadyUploaded(state, harness, sessionId, hash) {
@@ -2027,7 +2194,7 @@ function alreadyUploaded(state, harness, sessionId, hash) {
 }
 
 // src/upload.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 import { createRequire } from "module";
 import { hostname } from "os";
 import { basename as basename8, join as join12 } from "path";
@@ -2054,7 +2221,7 @@ async function planUpload(opts = {}) {
 async function gitBranch(cwd) {
   if (!cwd) return void 0;
   try {
-    const head = await readFile12(join12(cwd, ".git", "HEAD"), "utf8");
+    const head = await readFile13(join12(cwd, ".git", "HEAD"), "utf8");
     const m = head.match(/^ref:\s*refs\/heads\/(.+)$/m);
     return m?.[1]?.trim();
   } catch {
@@ -2108,7 +2275,12 @@ function stripSpanContent(spans) {
   });
 }
 async function executeUpload(plan, opts = {}) {
-  const newItems = plan.items.filter((i) => i.isNew).map((i) => opts.stripContent ? { ...i, spans: stripSpanContent(i.spans) } : i);
+  let newItems = plan.items.filter((i) => i.isNew);
+  if (opts.redactor && !opts.stripContent) {
+    const r = opts.redactor;
+    newItems = await Promise.all(newItems.map(async (i) => ({ ...i, spans: (await applyRedactor(i.spans, r)).spans })));
+  }
+  if (opts.stripContent) newItems = newItems.map((i) => ({ ...i, spans: stripSpanContent(i.spans) }));
   const skipped = plan.items.length - newItems.length;
   const redactionCount = newItems.reduce((n, i) => n + i.redaction.redactionCount, 0);
   const uploadedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -2161,6 +2333,12 @@ export {
   serializeSpans,
   writeOtlpFile,
   analyzeSpans,
+  runCommand,
+  commandAnalyzer,
+  toCanonicalOpenInference,
+  haloAnalyzer,
+  runExternalAnalyzers,
+  commandRedactor,
   parseIsoToEpochMs,
   parseSince,
   toRuntimeStore,
@@ -2190,6 +2368,7 @@ export {
   CODING_REDACTION_RULES,
   TRACES_REDACTION_RULES,
   redactSpans,
+  applyRedactor,
   uploadKey,
   sessionHash,
   loadState,

package/dist/cli.js

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
 import {
   analyzeSpans,
+  commandAnalyzer,
+  commandRedactor,
   executeUpload,
+  haloAnalyzer,
   knownHarnesses,
   parseSince,
   planUpload,
   resolveAdapter,
+  runExternalAnalyzers,
   runPipelines,
   selectAdapters,
   watchSessions,
   writeOtlpFile
-} from "./chunk-HF2KGEBW.js";
+} from "./chunk-Q56AP2EY.js";
 
 // src/cli.ts
 import { stat, writeFile } from "fs/promises";
@@ -68,7 +72,7 @@ function renderReport(result, meta) {
     }
   }
   lines.push("---");
-  lines.push(`OTLP artifact: \`${meta.otlpPath}\` \u2014 also runnable with \`halo ${meta.otlpPath} -p "diagnose"\`.`);
+  lines.push(`OTLP artifact: \`${meta.otlpPath}\` \u2014 run external engines with \`traces analyze --analyzer halo\`.`);
   lines.push("");
   return lines.join("\n");
 }
@@ -106,7 +110,8 @@ function parseArgs(argv) {
     minLoop: 3,
     dryRun: false,
     yes: false,
-    noContent: false
+    noContent: false,
+    analyzers: []
   };
   for (let i = 1; i < argv.length; i++) {
     const arg = argv[i];
@@ -143,6 +148,9 @@ function parseArgs(argv) {
       case "--budget":
         a.budget = Number(next());
         break;
+      case "--model":
+        a.model = next();
+        break;
       case "--interval":
         a.interval = Number(next());
         break;
@@ -158,6 +166,17 @@ function parseArgs(argv) {
       case "--no-content":
         a.noContent = true;
         break;
+      case "--analyzer": {
+        const v = next();
+        if (v) a.analyzers.push(v);
+        break;
+      }
+      case "--analyzer-prompt":
+        a.analyzerPrompt = next();
+        break;
+      case "--redactor":
+        a.redactorCmd = next();
+        break;
       case "--yes":
       case "-y":
         a.yes = true;
@@ -197,10 +216,13 @@ async function discover(args) {
 async function buildAxService() {
   const apiKey = process.env.OPENAI_API_KEY;
   if (!apiKey) {
-    throw new Error("--llm needs OPENAI_API_KEY for the agentic analyst kinds (deterministic analysis needs no key)");
+    throw new Error(
+      "--llm needs OPENAI_API_KEY \u2014 an OpenAI key, or a router/gateway key with OPENAI_BASE_URL set to an OpenAI-compatible endpoint (e.g. the Tangle router). Deterministic analysis needs no key."
+    );
   }
+  const apiURL = process.env.OPENAI_BASE_URL || void 0;
   const { AxAI } = await import("@ax-llm/ax");
-  return new AxAI({ name: "openai", apiKey });
+  return new AxAI({ name: "openai", apiKey, ...apiURL ? { apiURL } : {} });
 }
 async function cmdList(args) {
   const groups = await discover({ ...args, last: args.last || 20 });
@@ -251,14 +273,28 @@ async function cmdAnalyze(args) {
   const ai = args.llm ? await buildAxService() : void 0;
   const { otlpPath, result } = await analyzeSpans(spans, {
     ai,
+    model: args.model,
     budgetUsd: args.budget,
     otlpOutPath: args.otlp,
     log: (msg) => process.stderr.write(`${msg}
 `)
   });
   const pipelines = await runPipelines(spans, { minLoopOccurrences: args.minLoop });
-  const report = `${renderReport(result, { harness, sessionCount, spanCount: spans.length, otlpPath })}
+  let report = `${renderReport(result, { harness, sessionCount, spanCount: spans.length, otlpPath })}
 ${renderPipelines(pipelines)}`;
+  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] })
+    );
+    const results = await runExternalAnalyzers(otlpPath, engines, { prompt: args.analyzerPrompt });
+    for (const r of results) {
+      report += `
+
+## ${r.analyzer} (external analyzer)
+
+${r.ok ? r.output || "(no output)" : `failed: ${r.error}`}`;
+    }
+  }
   if (args.out) {
     await writeFile(args.out, report, "utf8");
     console.log(`report \u2192 ${args.out}  (${result.findings.length} findings, ${pipelines.stuckLoops.findings.length} loops, OTLP: ${otlpPath})`);
@@ -300,6 +336,8 @@ async function cmdUpload(args) {
     cwd: args.cwd,
     sinceMs
   });
+  const redactorParts = args.redactorCmd?.split(/\s+/).filter(Boolean) ?? [];
+  const redactor = redactorParts[0] ? commandRedactor({ command: redactorParts[0], args: redactorParts.slice(1) }) : void 0;
   const newItems = plan.items.filter((i) => i.isNew);
   const byRule = {};
   let totalRedactions = 0;
@@ -326,7 +364,7 @@ Window: since ${new Date(sinceMs).toISOString()}
     return;
   }
   if (args.dryRun) {
-    const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlp, stripContent: args.noContent });
+    const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlp, stripContent: args.noContent, redactor });
     console.log(`dry run \u2014 ${newItems.length} session(s), ${totalRedactions} redaction(s). Redacted OTLP \u2192 ${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;
@@ -339,7 +377,7 @@ Window: since ${new Date(sinceMs).toISOString()}
     }
   }
   const res = await executeUpload(plan, { log: (m) => w(`${m}
-`), stripContent: args.noContent });
+`), stripContent: args.noContent, redactor });
   console.log(
     `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped.`
   );
@@ -350,7 +388,7 @@ function usage() {
 Commands:
   list      List discovered sessions
   analyze   Run analyst suite + loop/waste pipelines, write a markdown report
-  convert   Emit OTLP-JSONL only (also feeds HALO)
+  convert   Emit OTLP-JSONL only (HALO: use analyze --analyzer halo)
   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
 
@@ -363,13 +401,17 @@ Options:
   --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)
-  --llm            Enable agentic RLM analysts (needs OPENAI_API_KEY)
+  --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
+  --analyzer <cmd> analyze: also run an external engine over the OTLP (repeatable; "halo" or any command)
+  --analyzer-prompt <p>  analyze: prompt passed to external analyzers (default: diagnose)
   --interval <s>   watch: poll interval seconds (default 5)
   --window <m>     watch: 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
   --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
 
 Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID`);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ToolUseMetrics, InMemoryTraceStore } from '@tangle-network/agent-eval';
 import { StuckLoopReport } from '@tangle-network/agent-eval/pipelines';
 import { AxAIService } from '@ax-llm/ax';
-import { AnalystRegistry, buildDefaultAnalystRegistry } from '@tangle-network/agent-eval/analyst';
+import { AnalystRegistry, buildDefaultAnalystRegistry, AnalystFinding } from '@tangle-network/agent-eval/analyst';
 export { Analyst, AnalystContext, AnalystFinding, AnalystRegistry, buildDefaultAnalystRegistry, makeFinding } from '@tangle-network/agent-eval/analyst';
 import { RedactionRule, RedactionReport } from '@tangle-network/agent-eval/traces';
 export { DEFAULT_REDACTION_RULES, RedactionReport, RedactionRule, redactString, redactValue } from '@tangle-network/agent-eval/traces';
@@ -14,8 +14,10 @@ export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-n
  * Every harness adapter projects its native session log onto `OtlpSpan[]`
  * and we serialize one span per JSONL line. This is the exact wire shape
  * `@tangle-network/agent-eval`'s `OtlpFileTraceStore` indexes
- * (`projectOtlpFlatLine` + `extractOtlpAttributes`) AND the OpenInference
- * OTLP form HALO consumes — so one emitted file feeds both engines.
+ * (`projectOtlpFlatLine` + `extractOtlpAttributes`). It is a flat subset, NOT
+ * canonical OpenInference (kind lives in attributes; no resource/scope; root
+ * parent is null) — external OpenInference engines like HALO need the canonical
+ * form, which `external.ts` `toCanonicalOpenInference` produces.
  *
  * Attribute vocabulary the downstream analysts key off:
  *   - `openinference.span.kind`  → span kind (AGENT | LLM | TOOL | CHAIN)
@@ -524,8 +526,10 @@ declare function toRuntimeStore(spans: readonly OtlpSpan[]): Promise<RuntimeTrac
  * LLM, model-agnostic). Supply `ai` to add the agentic RLM kinds
  * (failure-mode / knowledge-gap / knowledge-poisoning / improvement).
  *
- * The written OTLP file is the canonical artifact — the same file feeds HALO
- * (`halo <file> -p "diagnose"`), so analysis is never locked to one engine.
+ * The written OTLP file is the artifact our pipeline reads. External engines can
+ * analyze it too: HALO needs canonical OpenInference, so `--analyzer halo`
+ * converts it first (see external.ts `toCanonicalOpenInference`) — analysis is
+ * never locked to one engine.
  */
 
 interface AnalyzeOptions {
@@ -547,12 +551,109 @@ interface AnalyzeOptions {
     log?: (msg: string, fields?: Record<string, unknown>) => void;
 }
 interface AnalyzeResult {
-    /** Path to the OTLP-JSONL artifact (feeds HALO too). */
+    /** Path to the OTLP-JSONL artifact (convert to canonical for HALO). */
     otlpPath: string;
     result: Awaited<ReturnType<ReturnType<typeof buildDefaultAnalystRegistry>['run']>>;
 }
 declare function analyzeSpans(spans: readonly OtlpSpan[], opts?: AnalyzeOptions): Promise<AnalyzeResult>;
 
+/**
+ * External-tool adapters: run analysis engines and PII scrubbers that `traces`
+ * does NOT bundle. Each is a thin command adapter over a shared subprocess
+ * runner — install the tool yourself (HALO, openai/privacy-filter, anything),
+ * point an adapter at it, and it composes with the built-in pipeline.
+ *
+ *   - ExternalAnalyzer — run an engine over the emitted OTLP-JSONL artifact and
+ *     fold its output into the report (HALO and friends).
+ *   - Redactor — scrub free-form prompt/response text via an external model that
+ *     catches what the regex pass can't (names, addresses).
+ */
+
+interface RunResult {
+    stdout: string;
+    stderr: string;
+    code: number | null;
+}
+/** Spawn `command args`, optionally write `input` to stdin, and collect output.
+ *  Rejects on spawn error, timeout, or output exceeding `maxBuffer`. */
+declare function runCommand(command: string, args?: readonly string[], opts?: {
+    input?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxBuffer?: number;
+}): Promise<RunResult>;
+interface ExternalAnalysisResult {
+    analyzer: string;
+    ok: boolean;
+    /** Raw text the engine produced (markdown/JSON/plain — engine-specific). */
+    output: string;
+    /** Structured findings, when the engine emits parseable JSON. */
+    findings?: AnalystFinding[];
+    error?: string;
+}
+/** An analysis engine that runs over the emitted OTLP-JSONL artifact — a peer to
+ *  the built-in analysts, so you get many analyzers beyond our own. */
+interface ExternalAnalyzer {
+    name: string;
+    analyze(otlpPath: string, opts?: {
+        prompt?: string;
+        signal?: AbortSignal;
+    }): Promise<ExternalAnalysisResult>;
+}
+/** Wrap any CLI that reads the OTLP file and prints analysis to stdout. `args`
+ *  builds the argv from the artifact path + optional prompt. Non-zero exit →
+ *  `ok:false` with stderr in `error` (fail-soft: one engine never breaks a run). */
+declare function commandAnalyzer(spec: {
+    name: string;
+    command: string;
+    args: (otlpPath: string, prompt?: string) => string[];
+    /** Parse stdout into structured findings; omit to keep raw output only. */
+    parse?: (stdout: string) => AnalystFinding[] | undefined;
+    timeoutMs?: number;
+}): ExternalAnalyzer;
+/** Convert our OTLP-JSONL (the flat shape our pipeline reads) into the canonical
+ *  OpenInference span schema HALO's `SpanRecord` requires: top-level `kind`,
+ *  `resource`, `scope`, and a string (never null) `parent_span_id`. Our own
+ *  writer keeps the simpler shape for the agent-eval reader; this is the bridge
+ *  to OpenInference consumers. Input + output are JSONL strings (one span/line). */
+declare function toCanonicalOpenInference(otlpJsonl: string, opts?: {
+    service?: string;
+    scopeName?: string;
+}): string;
+/** HALO (github.com/context-labs/halo) over the OTLP artifact. HALO requires
+ *  canonical OpenInference, so this converts our OTLP to a `<path>.halo.jsonl`
+ *  first, then runs `halo <file> -p <prompt> [-m <model>]`. Install HALO yourself
+ *  and configure its LLM provider (it uses the OpenAI client — `OPENAI_BASE_URL`
+ *  / `OPENAI_API_KEY`); this just drives it. */
+declare function haloAnalyzer(opts?: {
+    command?: string;
+    defaultPrompt?: string;
+    model?: string;
+    timeoutMs?: number;
+}): ExternalAnalyzer;
+/** Run external analyzers over one OTLP artifact, concurrently. Never throws —
+ *  a failing engine returns `ok:false`. */
+declare function runExternalAnalyzers(otlpPath: string, analyzers: readonly ExternalAnalyzer[], opts?: {
+    prompt?: string;
+    signal?: AbortSignal;
+}): Promise<ExternalAnalysisResult[]>;
+/** An external PII/secret scrubber for free-form text — catches what regex
+ *  can't (names, addresses). Use to harden upload beyond the built-in rules. */
+interface Redactor {
+    name: string;
+    /** Scrub a batch of texts; returns one scrubbed string per input, in order. */
+    redactText(texts: readonly string[]): Promise<string[]>;
+}
+/** Wrap any CLI that speaks the redaction protocol: read a JSON array of strings
+ *  on stdin, write a same-length JSON array of scrubbed strings on stdout.
+ *  (A 3-line wrapper adapts tools like `opf`/openai-privacy-filter.) */
+declare function commandRedactor(spec: {
+    name?: string;
+    command: string;
+    args?: string[];
+    timeoutMs?: number;
+}): Redactor;
+
 /**
  * Live trace observer — the reusable, event-driven core behind `traces watch`.
  *
@@ -642,6 +743,14 @@ interface SpanRedaction {
 /** Redact every span's attributes + status message. Returns scrubbed spans and
  *  an aggregate report (count + per-rule breakdown) over the whole set. */
 declare function redactSpans(spans: readonly OtlpSpan[], rules?: RedactionRule[]): SpanRedaction;
+/** Defense-in-depth: run an external {@link Redactor} (e.g. an ML PII model) over
+ *  every span's captured `content` (prompt/response prose), catching free-form
+ *  PII the regex pass misses. Compose AFTER `redactSpans`. Returns scrubbed spans
+ *  and the number of `content` fields the model changed. */
+declare function applyRedactor(spans: readonly OtlpSpan[], redactor: Redactor): Promise<{
+    spans: OtlpSpan[];
+    changed: number;
+}>;
 
 /**
  * Batch collection seam — `collectSessions` returns redacted spans per session
@@ -750,9 +859,12 @@ interface ExecuteOptions {
      *  span before it leaves the machine (still keeps tool calls, tokens, timing,
      *  loop signal). The strongest privacy posture when prose can't leave. */
     stripContent?: boolean;
+    /** External PII scrubber applied to `content` AFTER the regex pass — catches
+     *  free-form PII (names, addresses) the rules miss. Ignored if stripContent. */
+    redactor?: Redactor;
     log?: (msg: string) => void;
 }
 /** Send the NEW items (or, on dryRun, write the redacted OTLP that would send). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ATTR, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, CODING_REDACTION_RULES, CONTENT_CAP, ClaudeAdapter, CodexAdapter, type CollectOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, QwenAdapter, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, alreadyUploaded, analyzeSpans, capText, collectSessions, executeUpload, knownHarnesses, listAdapters, loadState, parseIsoToEpochMs, parseSince, planUpload, redactSpans, resolveAdapter, runPipelines, saveState, scanSessions, selectAdapters, serializeSpans, sessionHash, span, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeOtlpFile };
+export { ATTR, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, CODING_REDACTION_RULES, CONTENT_CAP, ClaudeAdapter, CodexAdapter, type CollectOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, QwenAdapter, type Redactor, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, alreadyUploaded, analyzeSpans, applyRedactor, capText, collectSessions, commandAnalyzer, commandRedactor, executeUpload, haloAnalyzer, knownHarnesses, listAdapters, loadState, parseIsoToEpochMs, parseSince, planUpload, redactSpans, resolveAdapter, runCommand, runExternalAnalyzers, runPipelines, saveState, scanSessions, selectAdapters, serializeSpans, sessionHash, span, toCanonicalOpenInference, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeOtlpFile };

package/dist/index.js

@@ -17,8 +17,12 @@ import {
   TRACES_REDACTION_RULES,
   alreadyUploaded,
   analyzeSpans,
+  applyRedactor,
   capText,
+  commandAnalyzer,
+  commandRedactor,
   executeUpload,
+  haloAnalyzer,
   knownHarnesses,
   listAdapters,
   loadState,
@@ -27,6 +31,8 @@ import {
   planUpload,
   redactSpans,
   resolveAdapter,
+  runCommand,
+  runExternalAnalyzers,
   runPipelines,
   saveState,
   scanSessions,
@@ -34,13 +40,14 @@ import {
   serializeSpans,
   sessionHash,
   span,
+  toCanonicalOpenInference,
   toRuntimeStore,
   toTraceSpanEvents,
   uploadKey,
   userPromptSpan,
   watchSessions,
   writeOtlpFile
-} from "./chunk-HF2KGEBW.js";
+} from "./chunk-Q56AP2EY.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -85,11 +92,15 @@ export {
   TRACES_REDACTION_RULES,
   alreadyUploaded,
   analyzeSpans,
+  applyRedactor,
   buildDefaultAnalystRegistry,
   capText,
   collectSessions,
+  commandAnalyzer,
+  commandRedactor,
   createHostedClient,
   executeUpload,
+  haloAnalyzer,
   hostedClientFromEnv,
   knownHarnesses,
   listAdapters,
@@ -102,6 +113,8 @@ export {
   redactString,
   redactValue,
   resolveAdapter,
+  runCommand,
+  runExternalAnalyzers,
   runPipelines,
   saveState,
   scanSessions,
@@ -109,6 +122,7 @@ export {
   serializeSpans,
   sessionHash,
   span,
+  toCanonicalOpenInference,
   toRuntimeStore,
   toTraceSpanEvents,
   uploadKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",