@tangle-network/traces 0.6.0 → 0.8.0

package/README.md

@@ -43,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 a **canonical OpenInference JSONL artifact**, so you can run external engines like [HALO](https://github.com/context-labs/halo) over it directly with `--analyzer halo` — see [External engines](#external-engines-bring-your-own). Analysis is never locked to one engine.
 
 ## What it finds
 
@@ -142,6 +142,8 @@ traces analyze --last 1 --analyzer halo --analyzer-prompt "find token waste"
 traces analyze --last 1 --analyzer halo --analyzer my-engine    # repeatable
 ```
 
+Our OTLP artifact is **canonical OpenInference** (top-level `kind`, `resource`, `scope`), so HALO reads it directly — no conversion. 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

package/dist/{chunk-6TVW7PL6.js → chunk-BUD6I3ZJ.js}

@@ -25,17 +25,36 @@ function span(input) {
     attributes
   };
 }
+function toOpenInferenceSpan(s) {
+  const a = s.attributes;
+  const resourceAttrs = {};
+  if (a["service.name"] != null) resourceAttrs["service.name"] = a["service.name"];
+  if (a["agent.name"] != null) resourceAttrs["agent.name"] = a["agent.name"];
+  return {
+    trace_id: s.trace_id,
+    span_id: s.span_id,
+    parent_span_id: s.parent_span_id ?? "",
+    name: s.name,
+    kind: typeof a["openinference.span.kind"] === "string" ? a["openinference.span.kind"] : "CHAIN",
+    start_time: s.start_time,
+    end_time: s.end_time,
+    status: { code: s.status.code, message: s.status.message ?? "" },
+    resource: { attributes: resourceAttrs },
+    scope: { name: "tangle-traces", version: "" },
+    attributes: a
+  };
+}
 function serializeSpans(spans) {
   if (spans.length === 0) return "";
-  return `${spans.map((s) => JSON.stringify(s)).join("\n")}
+  return `${spans.map((s) => JSON.stringify(toOpenInferenceSpan(s))).join("\n")}
 `;
 }
 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;
 }
 
@@ -72,6 +91,7 @@ async function analyzeSpans(spans, opts = {}) {
 
 // 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;
@@ -141,14 +161,50 @@ function commandAnalyzer(spec) {
     }
   };
 }
+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 commandAnalyzer({
+  return {
     name: "halo",
-    command: opts.command ?? "halo",
-    args: (otlpPath, prompt) => [otlpPath, "-p", prompt ?? defaultPrompt],
-    timeoutMs: opts.timeoutMs
-  });
+    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)));
@@ -270,7 +326,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";
@@ -312,7 +368,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 [];
     }
@@ -396,7 +452,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";
@@ -557,7 +613,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}`;
@@ -600,13 +656,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;
       }
@@ -624,7 +680,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";
@@ -708,7 +764,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 {
@@ -723,7 +779,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;
@@ -839,7 +895,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";
@@ -884,7 +940,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 = [
@@ -965,7 +1021,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";
@@ -1026,13 +1082,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 = [
@@ -1126,7 +1182,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";
@@ -1172,7 +1228,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 [];
     }
@@ -1256,7 +1312,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) {
@@ -1321,7 +1377,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 [];
     }
@@ -1415,7 +1471,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";
@@ -1470,7 +1526,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 {
       }
     }
@@ -1498,7 +1554,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 {
           }
         }
@@ -1568,7 +1624,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";
@@ -1636,7 +1692,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}`;
@@ -1737,7 +1793,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";
@@ -1796,7 +1852,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 = [
@@ -2121,7 +2177,7 @@ async function applyRedactor(spans, redactor) {
 
 // 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() {
@@ -2141,7 +2197,7 @@ function sessionHash(spans) {
 }
 async function loadState() {
   try {
-    return JSON.parse(await readFile11(stateFile(), "utf8"));
+    return JSON.parse(await readFile12(stateFile(), "utf8"));
   } catch {
     return {};
   }
@@ -2149,7 +2205,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) {
@@ -2157,7 +2213,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";
@@ -2184,7 +2240,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 {
@@ -2293,11 +2349,13 @@ async function executeUpload(plan, opts = {}) {
 
 export {
   span,
+  toOpenInferenceSpan,
   serializeSpans,
   writeOtlpFile,
   analyzeSpans,
   runCommand,
   commandAnalyzer,
+  toCanonicalOpenInference,
   haloAnalyzer,
   runExternalAnalyzers,
   commandRedactor,

package/dist/cli.js

@@ -14,7 +14,7 @@ import {
   selectAdapters,
   watchSessions,
   writeOtlpFile
-} from "./chunk-6TVW7PL6.js";
+} from "./chunk-BUD6I3ZJ.js";
 
 // src/cli.ts
 import { stat, writeFile } from "fs/promises";
@@ -72,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");
 }
@@ -148,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;
@@ -270,6 +273,7 @@ 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}
@@ -280,7 +284,7 @@ async function cmdAnalyze(args) {
 ${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] })
+      (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) {
@@ -384,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
 
@@ -398,6 +402,7 @@ Options:
   --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 / 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)

package/dist/index.d.ts

@@ -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)
@@ -71,7 +73,15 @@ interface SpanInput {
  * so the behavioral analyst's "no LLM data" case stays honest.
  */
 declare function span(input: SpanInput): OtlpSpan;
-/** Serialize spans to OTLP-JSONL (one span per line, trailing newline). */
+/** Project an in-memory span to a COMPLETE OpenInference span: the standard shape
+ *  OTel/OpenInference consumers (and HALO) expect — top-level `kind`, `resource`,
+ *  `scope`, and a string `parent_span_id` ("" at the root) — while keeping the
+ *  attribute vocabulary (incl. `openinference.span.kind`) our own analysts read.
+ *  One artifact feeds our pipeline, HALO, and any OpenInference tool. */
+declare function toOpenInferenceSpan(s: OtlpSpan): Record<string, unknown>;
+/** Serialize spans to OpenInference JSONL (one complete span per line). This is a
+ *  standard OpenInference representation: it feeds our analysts, HALO, and other
+ *  OpenInference tools directly — no per-tool conversion. */
 declare function serializeSpans(spans: readonly OtlpSpan[]): string;
 /** Write spans to an OTLP-JSONL file (a temp file when no path is given). */
 declare function writeOtlpFile(spans: readonly OtlpSpan[], outPath?: string): Promise<string>;
@@ -524,8 +534,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,7 +559,7 @@ 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']>>;
 }
@@ -607,11 +619,24 @@ declare function commandAnalyzer(spec: {
     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. */
+/** 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 —
@@ -850,4 +875,4 @@ interface ExecuteOptions {
 /** 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, 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 };
+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, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeOtlpFile };

package/dist/index.js

@@ -40,13 +40,15 @@ import {
   serializeSpans,
   sessionHash,
   span,
+  toCanonicalOpenInference,
+  toOpenInferenceSpan,
   toRuntimeStore,
   toTraceSpanEvents,
   uploadKey,
   userPromptSpan,
   watchSessions,
   writeOtlpFile
-} from "./chunk-6TVW7PL6.js";
+} from "./chunk-BUD6I3ZJ.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -121,6 +123,8 @@ export {
   serializeSpans,
   sessionHash,
   span,
+  toCanonicalOpenInference,
+  toOpenInferenceSpan,
   toRuntimeStore,
   toTraceSpanEvents,
   uploadKey,

package/package.json

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