@tangle-network/traces 0.4.1 → 0.6.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)
@@ -102,19 +103,56 @@ traces upload   --since 24h                        # upload last day to the Inte
 | `--llm` / `--budget <usd>` | Enable agentic analysts (needs `OPENAI_API_KEY`) / cap their spend |
 | `--interval <s>` / `--window <m>` | `watch`: poll seconds (default 5) / active-session window minutes (default 30) |
 | `--min-loop <n>` | Identical repeated calls before flagging a loop (default 3) |
+| `--no-content` | `upload`: send metadata only — strip all prompt/response text |
 | `--dry-run` / `--yes` | `upload`: preview without sending / skip the confirm prompt |
 
 ## Upload to the Intelligence Platform
 
-`upload` **redacts PII/secrets locally before anything leaves the machine**, dedups against already-uploaded sessions, and tags each with metadata (harness, cwd, git branch, host).
+`upload` **redacts locally before anything leaves the machine**, dedups against already-uploaded sessions, and tags each with metadata (harness, cwd, git branch, host).
 
 ```bash
-traces upload --since 24h --dry-run   # see exactly what would be sent — no network
-traces upload --since 24h             # send it
+traces upload --since 24h --dry-run     # see exactly what would be sent — no network
+traces upload --since 24h --no-content  # send metadata only — drop all prompt/response text
+traces upload --since 24h               # send it
 ```
 
 It needs `TANGLE_INGEST_URL` (or `TANGLE_ORCHESTRATOR_URL`), `TANGLE_INGEST_API_KEY` (or `TANGLE_API_KEY`), and `TANGLE_TENANT_ID`. Without them, `--dry-run` still works fully.
 
+### Redaction scope — read this before uploading prose
+
+Redaction is **best-effort regex** for *structured* secrets and credentials: API keys, GitHub/cloud tokens, JWTs, bearer headers, private-key blocks, `KEY=secret` assignments, and credentials embedded in URLs. It runs over every span attribute, including the captured prompt/response text.
+
+It does **not** catch free-form PII — names, postal addresses, phone numbers in prose — which needs a context-aware model. Three postures, strongest first:
+
+1. **`--no-content`** — upload metadata only (tool calls, tokens, timing, loop signal); no prose leaves the machine.
+2. Run an ML PII scrubber (e.g. [`openai/privacy-filter`](https://github.com/openai/privacy-filter)) on the platform ingest side as defense-in-depth.
+3. Default — regex redaction of structured secrets.
+
+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
+```
+
+**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.
@@ -129,6 +167,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'
@@ -158,6 +197,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-33NBMIH4.js → chunk-6TVW7PL6.js}

@@ -70,6 +70,114 @@ async function analyzeSpans(spans, opts = {}) {
   return { otlpPath, result };
 }
 
+// src/external.ts
+import { spawn } from "child_process";
+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 haloAnalyzer(opts = {}) {
+  const defaultPrompt = opts.defaultPrompt ?? "diagnose";
+  return commandAnalyzer({
+    name: "halo",
+    command: opts.command ?? "halo",
+    args: (otlpPath, prompt) => [otlpPath, "-p", prompt ?? defaultPrompt],
+    timeoutMs: opts.timeoutMs
+  });
+}
+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;
@@ -139,15 +247,38 @@ async function runPipelines(spans, opts = {}) {
   return { stuckLoops, toolUse };
 }
 
+// src/adapters/conversation.ts
+var CONTENT_CAP = 8e3;
+function capText(raw) {
+  const t = raw.trim();
+  if (t.length <= CONTENT_CAP) return t;
+  return `${t.slice(0, CONTENT_CAP)}\u2026 [+${t.length - CONTENT_CAP} chars]`;
+}
+function userPromptSpan(o) {
+  return span({
+    traceId: o.traceId,
+    spanId: o.spanId,
+    parentSpanId: o.parentSpanId,
+    name: "user.prompt",
+    kind: "CHAIN",
+    startTime: o.startTime,
+    service: o.service ?? null,
+    agent: o.agent ?? null,
+    step: o.step,
+    content: o.content
+  });
+}
+
 // src/adapters/amp.ts
 import { readdir, readFile, stat } from "fs/promises";
 import { homedir } from "os";
 import { basename, join } from "path";
 var SERVICE = "amp";
-var CONTENT_CAP = 8e3;
 function textOf(content) {
   if (typeof content === "string") return content.slice(0, CONTENT_CAP);
-  return (Array.isArray(content) ? content : []).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n").trim().slice(0, CONTENT_CAP);
+  return capText(
+    (Array.isArray(content) ? content : []).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n")
+  );
 }
 var AmpAdapter = class {
   harness = "amp";
@@ -201,12 +332,10 @@ var AmpAdapter = class {
         const prompt = textOf(m.content);
         if (prompt) {
           spans.push(
-            span({
+            userPromptSpan({
               traceId,
               spanId: `${llmId}:user`,
               parentSpanId: rootId,
-              name: "user.prompt",
-              kind: "CHAIN",
               startTime: start,
               service: SERVICE,
               agent: SERVICE,
@@ -290,10 +419,11 @@ function inputTokens(u) {
 function asBlocks(content) {
   return Array.isArray(content) ? content : [];
 }
-var CONTENT_CAP2 = 8e3;
 function textOf2(content) {
-  if (typeof content === "string") return content.slice(0, CONTENT_CAP2);
-  return asBlocks(content).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n").trim().slice(0, CONTENT_CAP2);
+  if (typeof content === "string") return capText(content);
+  return capText(
+    asBlocks(content).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n")
+  );
 }
 function stringifyToolResult(content) {
   if (typeof content === "string") return content;
@@ -354,12 +484,10 @@ function parseClaudeStream(events, ctx) {
       const prompt = textOf2(ev.message.content);
       if (prompt) {
         spans.push(
-          span({
+          userPromptSpan({
             traceId: ctx.traceId,
             spanId: `${ctx.idPrefix}${uid}:user`,
             parentSpanId: ctx.rootParent,
-            name: "user.prompt",
-            kind: "CHAIN",
             startTime: ts,
             service: SERVICE2,
             agent: ctx.agent,
@@ -518,9 +646,8 @@ function contentToString(content) {
   }
   return "";
 }
-var CONTENT_CAP3 = 8e3;
 function textOf3(content) {
-  return contentToString(content).trim().slice(0, CONTENT_CAP3);
+  return capText(contentToString(content));
 }
 function outputIsError(output) {
   const s = typeof output === "string" ? output : JSON.stringify(output ?? "");
@@ -673,17 +800,15 @@ var CodexAdapter = class {
         const prompt = textOf3(l.payload.content);
         if (prompt) {
           spans.push(
-            span({
+            userPromptSpan({
               traceId,
               spanId: `msg:${step}:user`,
               parentSpanId: rootId,
-              name: "user.prompt",
-              kind: "CHAIN",
               startTime: ts,
+              content: prompt,
               service: SERVICE3,
               agent: SERVICE3,
-              step,
-              content: prompt
+              step
             })
           );
           step += 1;
@@ -844,9 +969,10 @@ import { readdir as readdir5, readFile as readFile5, stat as stat5 } from "fs/pr
 import { homedir as homedir5 } from "os";
 import { basename as basename4, join as join5 } from "path";
 var SERVICE5 = "factory";
-var CONTENT_CAP4 = 8e3;
 function textOf4(content) {
-  return (content ?? []).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("").trim().slice(0, CONTENT_CAP4);
+  return capText(
+    (content ?? []).filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("")
+  );
 }
 function parseLines4(raw) {
   const out = [];
@@ -938,17 +1064,15 @@ var FactoryAdapter = class {
       if (role === "user") {
         if (text) {
           spans.push(
-            span({
+            userPromptSpan({
               traceId,
               spanId: `user:${l.id ?? step}`,
               parentSpanId: rootId,
-              name: "user.prompt",
-              kind: "CHAIN",
               startTime: ts,
+              content: text,
               service: SERVICE5,
               agent: SERVICE5,
-              step,
-              content: text
+              step
             })
           );
           step += 1;
@@ -1010,9 +1134,8 @@ function tokens(t) {
   if (!t) return null;
   return t.actual ?? t.approx ?? null;
 }
-var CONTENT_CAP5 = 8e3;
 function textOf5(content) {
-  return (content ?? "").trim().slice(0, CONTENT_CAP5);
+  return capText(content ?? "");
 }
 var ForgeAdapter = class {
   harness = "forge";
@@ -1070,17 +1193,15 @@ var ForgeAdapter = class {
         const prompt = textOf5(entry.text.content);
         if (prompt) {
           spans.push(
-            span({
+            userPromptSpan({
               traceId,
               spanId: `user:${step}`,
               parentSpanId: rootId,
-              name: "user.prompt",
-              kind: "CHAIN",
               startTime: ts,
+              content: prompt,
               service: SERVICE6,
               agent: SERVICE6,
-              step,
-              content: prompt
+              step
             })
           );
           step += 1;
@@ -1146,10 +1267,9 @@ function iso(ts, fallback) {
 function toolStatusError(status) {
   return status != null && /error|fail|cancel/i.test(status);
 }
-var CONTENT_CAP6 = 8e3;
 function textOf6(content) {
   const s = typeof content === "string" ? content : JSON.stringify(content ?? "");
-  return s.trim().slice(0, CONTENT_CAP6);
+  return capText(s);
 }
 var GeminiFamilyAdapter = class {
   harness;
@@ -1231,17 +1351,15 @@ var GeminiFamilyAdapter = class {
         const prompt = textOf6(m.content);
         if (prompt) {
           spans.push(
-            span({
+            userPromptSpan({
               traceId,
               spanId: `${llmId}:user`,
               parentSpanId: rootId,
-              name: "user.prompt",
-              kind: "CHAIN",
               startTime: ts,
+              content: prompt,
               service: this.service,
               agent: this.service,
-              step,
-              content: prompt
+              step
             })
           );
           step += 1;
@@ -1304,9 +1422,10 @@ var SERVICE7 = "opencode";
 function isoOf(ms) {
   return new Date(ms ?? 0).toISOString();
 }
-var CONTENT_CAP7 = 8e3;
 function textOf7(parts) {
-  return parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join("\n").trim().slice(0, CONTENT_CAP7);
+  return capText(
+    parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join("\n")
+  );
 }
 var OpencodeAdapter = class {
   harness = "opencode";
@@ -1407,12 +1526,10 @@ var OpencodeAdapter = class {
       step += 1;
       if (msg.role === "user" && turnText) {
         spans.push(
-          span({
+          userPromptSpan({
             traceId,
             spanId: `${llmId}:user`,
             parentSpanId: rootId,
-            name: "user.prompt",
-            kind: "CHAIN",
             startTime: isoOf(msg.time?.created),
             service: SERVICE7,
             agent: SERVICE7,
@@ -1472,10 +1589,11 @@ function isToolBlock(b) {
 function isToolResultBlock(b) {
   return typeof b.type === "string" && /tool[_-]?result|tool[_-]?output/i.test(b.type);
 }
-var CONTENT_CAP8 = 8e3;
 function textOf8(content) {
   if (!content) return "";
-  return content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("").trim().slice(0, CONTENT_CAP8);
+  return capText(
+    content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("")
+  );
 }
 var PiAdapter = class {
   harness = "pi";
@@ -1547,12 +1665,10 @@ var PiAdapter = class {
         const prompt = textOf8(msg.content);
         if (prompt) {
           spans.push(
-            span({
+            userPromptSpan({
               traceId,
               spanId: `${mid}:user`,
               parentSpanId: rootId,
-              name: "user.prompt",
-              kind: "CHAIN",
               startTime: ts,
               service: SERVICE8,
               agent: SERVICE8,
@@ -1718,7 +1834,7 @@ var QwenAdapter = class {
             inputTokens: r.usageMetadata?.promptTokenCount ?? null,
             outputTokens: r.usageMetadata?.candidatesTokenCount ?? null,
             step,
-            content: textOf9(r.message?.parts).slice(0, 8e3) || null
+            content: capText(textOf9(r.message?.parts)) || null
           })
         );
         lastLlm = llmId;
@@ -1746,15 +1862,13 @@ var QwenAdapter = class {
           step += 1;
         }
       } else if (r.type === "user") {
-        const prompt = textOf9(r.message?.parts).slice(0, 8e3);
+        const prompt = capText(textOf9(r.message?.parts));
         if (prompt) {
           spans.push(
-            span({
+            userPromptSpan({
               traceId,
               spanId: `user:${r.uuid ?? step}`,
               parentSpanId: rootId,
-              name: "user.prompt",
-              kind: "CHAIN",
               startTime: ts,
               service: SERVICE9,
               agent: SERVICE9,
@@ -1960,6 +2074,12 @@ var CODING_REDACTION_RULES = [
   {
     id: "assigned-secret",
     pattern: /\b(?:api[_-]?key|secret|token|password|passwd|access[_-]?token|client[_-]?secret)\b\s*[:=]\s*["']?[A-Za-z0-9._\-]{12,}["']?/gi
+  },
+  // Credentials embedded in URLs — common when a prompt pastes a curl/clone line.
+  { id: "url-userinfo", pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@/gi },
+  {
+    id: "url-secret-param",
+    pattern: /[?&](?:access[_-]?token|api[_-]?key|apikey|auth|token|secret|password|sig|signature)=[^&\s"'#)]+/gi
   }
 ];
 var TRACES_REDACTION_RULES = [...DEFAULT_REDACTION_RULES, ...CODING_REDACTION_RULES];
@@ -1976,6 +2096,28 @@ 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";
@@ -2088,8 +2230,20 @@ function toTraceSpanEvents(spans, rootMeta) {
     };
   });
 }
+function stripSpanContent(spans) {
+  return spans.map((s) => {
+    if (s.attributes["content"] == null) return s;
+    const { content: _drop, ...attributes } = s.attributes;
+    return { ...s, attributes };
+  });
+}
 async function executeUpload(plan, opts = {}) {
-  const newItems = plan.items.filter((i) => i.isNew);
+  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();
@@ -2142,10 +2296,18 @@ export {
   serializeSpans,
   writeOtlpFile,
   analyzeSpans,
+  runCommand,
+  commandAnalyzer,
+  haloAnalyzer,
+  runExternalAnalyzers,
+  commandRedactor,
   parseIsoToEpochMs,
   parseSince,
   toRuntimeStore,
   runPipelines,
+  CONTENT_CAP,
+  capText,
+  userPromptSpan,
   AmpAdapter,
   ClaudeAdapter,
   CodexAdapter,
@@ -2168,6 +2330,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-33NBMIH4.js";
+} from "./chunk-6TVW7PL6.js";
 
 // src/cli.ts
 import { stat, writeFile } from "fs/promises";
@@ -105,7 +109,9 @@ function parseArgs(argv) {
     window: 30,
     minLoop: 3,
     dryRun: false,
-    yes: false
+    yes: false,
+    noContent: false,
+    analyzers: []
   };
   for (let i = 1; i < argv.length; i++) {
     const arg = argv[i];
@@ -154,6 +160,20 @@ function parseArgs(argv) {
       case "--dry-run":
         a.dryRun = true;
         break;
+      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;
@@ -193,10 +213,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 });
@@ -253,8 +276,21 @@ async function cmdAnalyze(args) {
 `)
   });
   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 }) : 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})`);
@@ -296,6 +332,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;
@@ -322,7 +360,7 @@ Window: since ${new Date(sinceMs).toISOString()}
     return;
   }
   if (args.dryRun) {
-    const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlp });
+    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;
@@ -335,7 +373,7 @@ Window: since ${new Date(sinceMs).toISOString()}
     }
   }
   const res = await executeUpload(plan, { log: (m) => w(`${m}
-`) });
+`), stripContent: args.noContent, redactor });
   console.log(
     `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped.`
   );
@@ -359,12 +397,16 @@ 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)
   --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';
@@ -436,6 +436,37 @@ declare class ForgeAdapter implements HarnessTraceAdapter {
     parse(ref: SessionRef): Promise<OtlpSpan[]>;
 }
 
+/**
+ * Shared conversation-capture primitives for the harness adapters.
+ *
+ * Every adapter records the human's prompt and the assistant's prose, not just
+ * the execution skeleton (LLM token spans + tool calls). These helpers keep that
+ * capture identical across harnesses: one text cap, one `user.prompt` span shape.
+ */
+
+/** Max chars of conversation text kept per span — enough for prompt/response
+ *  analysis, bounded for storage + redaction cost. */
+declare const CONTENT_CAP = 8000;
+/** Trim and cap a message's text at {@link CONTENT_CAP}. When the text is cut, a
+ *  visible `… [+N chars]` marker is appended so analysts (and readers) know the
+ *  content was truncated rather than silently lost. */
+declare function capText(raw: string): string;
+interface UserPromptInput {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    startTime: string;
+    /** The human's prompt text (extracted by the adapter; cap with capText). */
+    content: string;
+    service?: string | null;
+    agent?: string | null;
+    step?: number;
+}
+/** The canonical `user.prompt` span. Every adapter emits the human's turn the
+ *  same way — a CHAIN span, because a user message is not an LLM call — so
+ *  analysts see one consistent shape regardless of harness. */
+declare function userPromptSpan(o: UserPromptInput): OtlpSpan;
+
 /**
  * Run agent-eval's shipped trace pipelines over normalized harness spans.
  *
@@ -522,6 +553,90 @@ interface AnalyzeResult {
 }
 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;
+/** HALO (github.com/context-labs/halo) over the OTLP artifact: `halo <file> -p <prompt>`.
+ *  Install HALO yourself; this just drives it. */
+declare function haloAnalyzer(opts?: {
+    command?: string;
+    defaultPrompt?: 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`.
  *
@@ -589,9 +704,15 @@ declare function watchSessions(opts: ObserverOptions): Promise<void>;
  * Reuses agent-eval's `redactValue` + `DEFAULT_REDACTION_RULES` (email, IPs,
  * generic secret keys, …) and layers on coding-session-specific rules that the
  * defaults miss — GitHub tokens, cloud keys, JWTs, bearer headers, private-key
- * blocks, and `key=secret` assignments common in shell/tool output. Redaction
- * runs over every span attribute + status message, so what leaves the machine
- * is already scrubbed.
+ * blocks, `key=secret` assignments, and credentials embedded in URLs. Redaction
+ * runs over every span attribute + status message (including captured prompt /
+ * response `content`), so what leaves the machine is already scrubbed.
+ *
+ * Scope, stated honestly: this is **best-effort regex** for *structured* secrets
+ * and credentials. It does NOT catch free-form PII — names, postal addresses,
+ * phone numbers, account numbers in prose — which need a context-aware model.
+ * For that assurance, run an ML PII scrubber (e.g. openai/privacy-filter) on the
+ * ingest side of the platform, or upload metadata-only with `--no-content`.
  */
 
 /** Secrets common in coding-agent traces that the substrate defaults don't cover. */
@@ -605,6 +726,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
@@ -709,9 +838,16 @@ interface ExecuteOptions {
     otlpOut?: string;
     /** Custom sink. Defaults to the hosted Tangle Intelligence client from env. */
     backend?: UploadBackend;
+    /** Metadata-only upload: drop captured prompt/response `content` from every
+     *  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, 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, collectSessions, executeUpload, knownHarnesses, listAdapters, loadState, parseIsoToEpochMs, parseSince, planUpload, redactSpans, resolveAdapter, runPipelines, saveState, scanSessions, selectAdapters, serializeSpans, sessionHash, span, toRuntimeStore, toTraceSpanEvents, uploadKey, 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, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeOtlpFile };

package/dist/index.js

@@ -2,6 +2,7 @@ import {
   ATTR,
   AmpAdapter,
   CODING_REDACTION_RULES,
+  CONTENT_CAP,
   ClaudeAdapter,
   CodexAdapter,
   CopilotAdapter,
@@ -16,7 +17,12 @@ import {
   TRACES_REDACTION_RULES,
   alreadyUploaded,
   analyzeSpans,
+  applyRedactor,
+  capText,
+  commandAnalyzer,
+  commandRedactor,
   executeUpload,
+  haloAnalyzer,
   knownHarnesses,
   listAdapters,
   loadState,
@@ -25,6 +31,8 @@ import {
   planUpload,
   redactSpans,
   resolveAdapter,
+  runCommand,
+  runExternalAnalyzers,
   runPipelines,
   saveState,
   scanSessions,
@@ -35,9 +43,10 @@ import {
   toRuntimeStore,
   toTraceSpanEvents,
   uploadKey,
+  userPromptSpan,
   watchSessions,
   writeOtlpFile
-} from "./chunk-33NBMIH4.js";
+} from "./chunk-6TVW7PL6.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -66,6 +75,7 @@ export {
   AmpAdapter,
   AnalystRegistry,
   CODING_REDACTION_RULES,
+  CONTENT_CAP,
   ClaudeAdapter,
   CodexAdapter,
   CopilotAdapter,
@@ -81,10 +91,15 @@ export {
   TRACES_REDACTION_RULES,
   alreadyUploaded,
   analyzeSpans,
+  applyRedactor,
   buildDefaultAnalystRegistry,
+  capText,
   collectSessions,
+  commandAnalyzer,
+  commandRedactor,
   createHostedClient,
   executeUpload,
+  haloAnalyzer,
   hostedClientFromEnv,
   knownHarnesses,
   listAdapters,
@@ -97,6 +112,8 @@ export {
   redactString,
   redactValue,
   resolveAdapter,
+  runCommand,
+  runExternalAnalyzers,
   runPipelines,
   saveState,
   scanSessions,
@@ -107,6 +124,7 @@ export {
   toRuntimeStore,
   toTraceSpanEvents,
   uploadKey,
+  userPromptSpan,
   watchSessions,
   writeOtlpFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.4.1",
+  "version": "0.6.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",