@tangle-network/traces 0.11.5 → 0.12.0

package/dist/index.js

@@ -25,6 +25,7 @@ import {
   JsonSourceError,
   JsonlParseError,
   OpencodeAdapter,
+  POLICY_EVIDENCE_NOTE,
   PartialUploadError,
   PiAdapter,
   QwenAdapter,
@@ -47,6 +48,7 @@ import {
   analyzeSpans,
   analyzeSteeringChain,
   applyRedactor,
+  assembleSessionBundle,
   assertSandboxReachable,
   buildFixPrompt,
   buildPolicyEvidenceRecord,
@@ -57,6 +59,8 @@ import {
   buildTraceFindingPacket,
   capText,
   chatTrajectoryToSpans,
+  classifyEvidenceOnlyPath,
+  classifyFailureFollowUps,
   classifyLiveActions,
   classifyReaction,
   classifyVerdict,
@@ -77,12 +81,15 @@ import {
   countScriptCommands,
   countSkillRunsJsonl,
   cwdMatchesSelection,
+  cwdMatchesSelectionResolved,
   defaultTraceLiveAnalysts,
   deriveFailureSignature,
   derivedImageTag,
   describeSessionRelationship,
   dockerImagePreparer,
   enumerateReplayableCases,
+  environmentAttributes,
+  environmentFromSpanAttributes,
   equivalentGitCwds,
   executeUpload,
   exportTraceEvidenceFile,
@@ -90,6 +97,8 @@ import {
   exportTraceEvidenceText,
   extractFixCommand,
   fileRunContextSupervisorRunReader,
+  findContextRoot,
+  findSessionTextLeaks,
   findSpanSourceFiles,
   findingReplayStep,
   findingTrajectoryId,
@@ -97,7 +106,9 @@ import {
   generateFixCommand,
   goldIncorrectSteps,
   haloAnalyzer,
+  hashSessionBundleFiles,
   hodoscopeAnalyzer,
+  httpJsonTransport,
   importCodeTraceBench,
   incompleteInputsNote,
   indexSessionIdsByTrace,
@@ -112,6 +123,7 @@ import {
   isSubmitAction,
   knownHarnesses,
   listAdapters,
+  listSessionBundleFiles,
   loadState,
   loadTracesConfig,
   locateSessions,
@@ -134,6 +146,8 @@ import {
   parseVerifyFindingsArgs,
   planTraceAgenticRoute,
   planUpload,
+  primeAnalyzer,
+  projectSessionBundle,
   readCoordinationLog,
   readFileRunContext,
   readFindingsFile,
@@ -144,6 +158,7 @@ import {
   readRunContextJournal,
   readRunContextSnapshot,
   readRunWatchSnapshot,
+  readSessionBundleManifest,
   readSessionIndexFile,
   readSpanRunSnapshot,
   recordSessionCorruption,
@@ -192,9 +207,11 @@ import {
   sessionHash,
   sessionIdFromAttributes,
   sessionIntegrityAttributes,
+  sessionTextSignatures,
   skippedAnalyses,
   span,
   spanRunTotals,
+  stampEnvironmentAttrs,
   stampRepoAttrs,
   stampSessionIdentity,
   stampSessionIntegrity,
@@ -228,12 +245,13 @@ import {
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
+  writeSessionBundleManifest,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceImprovementArtifacts,
   zaiChatCaller,
   zeroPricedCost
-} from "./chunk-VTYOCFGF.js";
+} from "./chunk-CV22VGCK.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -286,6 +304,7 @@ export {
   JsonSourceError,
   JsonlParseError,
   OpencodeAdapter,
+  POLICY_EVIDENCE_NOTE,
   PartialUploadError,
   PiAdapter,
   QwenAdapter,
@@ -308,6 +327,7 @@ export {
   analyzeSpans,
   analyzeSteeringChain,
   applyRedactor,
+  assembleSessionBundle,
   assertSandboxReachable,
   buildDefaultAnalystRegistry,
   buildFixPrompt,
@@ -319,6 +339,8 @@ export {
   buildTraceFindingPacket,
   capText,
   chatTrajectoryToSpans,
+  classifyEvidenceOnlyPath,
+  classifyFailureFollowUps,
   classifyLiveActions,
   classifyReaction,
   classifyVerdict,
@@ -341,12 +363,15 @@ export {
   countSkillRunsJsonl,
   createHostedClient,
   cwdMatchesSelection,
+  cwdMatchesSelectionResolved,
   defaultTraceLiveAnalysts,
   deriveFailureSignature,
   derivedImageTag,
   describeSessionRelationship,
   dockerImagePreparer,
   enumerateReplayableCases,
+  environmentAttributes,
+  environmentFromSpanAttributes,
   equivalentGitCwds,
   executeUpload,
   exportTraceEvidenceFile,
@@ -354,6 +379,8 @@ export {
   exportTraceEvidenceText,
   extractFixCommand,
   fileRunContextSupervisorRunReader,
+  findContextRoot,
+  findSessionTextLeaks,
   findSpanSourceFiles,
   findingReplayStep,
   findingTrajectoryId,
@@ -361,8 +388,10 @@ export {
   generateFixCommand,
   goldIncorrectSteps,
   haloAnalyzer,
+  hashSessionBundleFiles,
   hodoscopeAnalyzer,
   hostedClientFromEnv,
+  httpJsonTransport,
   importCodeTraceBench,
   incompleteInputsNote,
   indexSessionIdsByTrace,
@@ -377,6 +406,7 @@ export {
   isSubmitAction,
   knownHarnesses,
   listAdapters,
+  listSessionBundleFiles,
   loadState,
   loadTracesConfig,
   locateSessions,
@@ -400,6 +430,8 @@ export {
   parseVerifyFindingsArgs,
   planTraceAgenticRoute,
   planUpload,
+  primeAnalyzer,
+  projectSessionBundle,
   readCoordinationLog,
   readFileRunContext,
   readFindingsFile,
@@ -410,6 +442,7 @@ export {
   readRunContextJournal,
   readRunContextSnapshot,
   readRunWatchSnapshot,
+  readSessionBundleManifest,
   readSessionIndexFile,
   readSpanRunSnapshot,
   recordSessionCorruption,
@@ -460,9 +493,11 @@ export {
   sessionHash,
   sessionIdFromAttributes,
   sessionIntegrityAttributes,
+  sessionTextSignatures,
   skippedAnalyses,
   span,
   spanRunTotals,
+  stampEnvironmentAttrs,
   stampRepoAttrs,
   stampSessionIdentity,
   stampSessionIntegrity,
@@ -496,6 +531,7 @@ export {
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
+  writeSessionBundleManifest,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceImprovementArtifacts,

package/docs/trace-analysts.md

@@ -68,9 +68,12 @@ traces analyze --all --last 20 --analyzer hodoscope
 
 # Run any installed command that accepts an OpenInference file path.
 traces analyze --last 1 --analyzer my-trace-tool
+
+# One-shot prime-RLM analysis through a local OpenAI-compatible bridge.
+traces analyze --last 1 --analyzer prime --analyzer-prompt "find unsupported completion claims"
 ```
 
-`--model` is forwarded to the built-in model-assisted analysts, HALO, and Hodoscope.
+`--model` is forwarded to the built-in model-assisted analysts, HALO, Hodoscope, and prime.
 HALO and Hodoscope use their own provider clients and credentials.
 The Hodoscope adapter pins version `0.2.4` and uses Python 3.11 through `uvx`.
 
@@ -87,6 +90,41 @@ Raw JSON is still a `report`.
 Only an adapter that validates the full finding shape may return `findings`.
 Hodoscope always returns `discovery`, and each candidate has `status: 'needs_review'` plus its source trace and span.
 
+### Prime engine
+
+`--analyzer prime` runs a one-shot analyst over the emitted OTLP artifact through an OpenAI-compatible bridge, such as cli-bridge's prime backend.
+Unlike the `--llm` analysts, which drill into the trace with paged tools, prime has no REPL and no trace tools: the full span projection is inlined into a single prompt as JSON.
+Oversized projections are re-rendered with a per-attribute character cap; if the projection still exceeds the inline budget the engine fails loud instead of silently dropping spans.
+
+Prerequisites:
+
+- A running bridge that accepts `POST /v1/chat/completions` and routes the configured model to the prime backend.
+- No key handling here: the bridge owns provider credentials.
+
+Configuration (flags first, then environment, then defaults):
+
+| Setting | Source | Default |
+| --- | --- | --- |
+| Bridge root URL | `TRACES_PRIME_BRIDGE_URL` | `http://localhost:4181` |
+| Model | `--model`, then `TRACES_PRIME_MODEL` | `prime/zai/glm-5.2` |
+| Per-call deadline | `TRACES_PRIME_TIMEOUT_MS` | `1200000` (20 min) |
+| Question | `--analyzer-prompt` | a general diagnosis question |
+
+```bash
+traces analyze --last 1 --analyzer prime
+TRACES_PRIME_BRIDGE_URL=http://localhost:4181 traces analyze --last 1 --analyzer prime --analyzer-prompt "find unsupported completion claims"
+```
+
+Output expectations:
+
+- The reply contract is one fenced JSON block of short strings citing span ids verbatim; a structurally malformed reply gets exactly one bounded repair turn that carries the malformed reply and the contract, never the trajectory.
+- A still-malformed reply after repair is a failed result (`ok: false`) with the raw reply preserved for inspection; one failed engine never discards the other results.
+- Valid rows become full `findings` with `trace://` span evidence, validated against the artifact like every other findings-kind engine; rows citing unknown or ambiguous span ids are rejected with a recorded reason.
+- Zero findings from a well-formed reply is an honest null, not a failure.
+- Bridge-reported token usage and call counts are recorded in the result output; cost stays uncaptured because this adapter has no pricing table.
+
+The scored prime-vs-dspy comparison — same trajectories, same scoring — lives in `@tangle-network/agent-eval`'s analyst benchmark (`runAnalystBenchmark`); this engine is the capture-side entry point, not the scoreboard.
+
 ## Write one analyst
 
 An analyst receives a paged trace store and returns typed findings.

package/examples/external-engines.ts

@@ -10,6 +10,7 @@ import {
   commandRedactor,
   haloAnalyzer,
   hodoscopeAnalyzer,
+  primeAnalyzer,
   writeOtlpFile,
 } from '@tangle-network/traces'
 
@@ -41,7 +42,19 @@ console.log(
     : `hodoscope unavailable: ${discovery.error}`,
 )
 
-// 3) External REDACTOR: scrub prose with your own PII model before upload. The
+// 3) PRIME ENGINE: one-shot RLM through an OpenAI-compatible bridge (run
+//    cli-bridge's prime backend locally, or set TRACES_PRIME_BRIDGE_URL).
+//    The full span projection travels inline; findings come back with
+//    validated trace:// span evidence.
+const prime = primeAnalyzer({ defaultPrompt: 'find unsupported completion claims' })
+const primeResult = await prime.analyze(otlp)
+console.log(
+  primeResult.ok
+    ? `${primeResult.findings?.length ?? 0} prime finding(s)\n${primeResult.output}`
+    : `prime bridge unavailable: ${primeResult.error}`,
+)
+
+// 4) External REDACTOR: scrub prose with your own PII model before upload. The
 //    command reads a JSON array of strings on stdin and writes the scrubbed array
 //    on stdout (a 3-line wrapper adapts openai/privacy-filter's `opf`).
 const redactor = commandRedactor({ command: 'my-pii-scrubber' })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.11.5",
+  "version": "0.12.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",
@@ -44,13 +44,14 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13.0"
   },
   "dependencies": {
-    "@tangle-network/agent-eval": "0.143.0",
-    "@tangle-network/agent-runtime": "0.126.0",
+    "@tangle-network/agent-eval": "0.145.22",
+    "@tangle-network/agent-interface": "1.0.0",
+    "@tangle-network/agent-runtime": "0.137.0",
     "@tangle-network/agent-trace-contract": "^1.0.2",
-    "@tangle-network/sandbox": "0.17.2"
+    "@tangle-network/sandbox": "0.27.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/build-trace-analyst/SKILL.md

@@ -48,6 +48,19 @@ Use `runAnalystBenchmark` with `registryBenchmarkRunner` from `@tangle-network/a
 Use AgentRx or CodeTraceBench labels when they match the finding.
 Compare the candidate with a no-findings baseline and relevant maintained or external analysts on identical cases and limits.
 
+Two shipped engines are available as comparison arms.
+`--analyzer prime` inlines the whole span projection into one prompt and needs no REPL.
+`--analyzer halo` and `--analyzer hodoscope` drill into the trace with paged tools.
+Compare an inline arm with a paged arm to separate the prompt from the navigation.
+
+```bash
+traces analyze --last 1 --analyzer prime
+```
+
+Assert the served model, not the requested id.
+A gateway can answer one id with another model, so a panel can report families it never ran.
+Use `assertServedModel` and `assertCrossFamilyServed` from `@tangle-network/agent-eval` before you trust a per-model or cross-family number.
+
 Use at least 20 independent cases before comparative statistics.
 Retain every case row and report exact-step recall, precision, F1, root-step accuracy when labeled, citation coverage and validity, clean-case false positives, repeat agreement, failures, latency, calls, all token fields, and known or missing cost.
 

package/skills/inspect-agent-traces/SKILL.md

@@ -22,10 +22,9 @@ traces analyze --otlp results/sessions --out .traces/all.md   # a directory of e
 Use `--harness` only for coding agents whose on-disk format we do not control.
 Those adapters are the legacy edge, not the way to integrate a system you own.
 
-A directory is a run directory: it holds the span export beside raw event, stream and
-SDK logs that are also `*.jsonl`. Only the OTLP files are read, and the rest are listed
-with what they actually hold. An `otlp/` subdirectory, when the producer made one, is
-read on its own.
+A run directory holds the span export beside raw event, stream and SDK logs that are
+also `*.jsonl`. Only the OTLP files are read; the rest are listed with what they hold.
+An `otlp/` subdirectory, when present, is read on its own.
 
 Any section headed `inputs incomplete`, or carrying an `Inputs incomplete` line above
 its table, is computed from a field the trace does not carry everywhere. Report those
@@ -73,6 +72,33 @@ traces improve --harness codex --current --latest-turn --workflow \
 `improve` writes findings, evidence, a report, and spans.
 It does not edit an agent, repository, memory store, or knowledge base.
 
+Write one session's durable evidence directory for a later reader:
+
+```bash
+traces bundle --harness claude-code --session <id-or-path> --out .traces/bundle
+```
+
+`bundle` copies the transcript, the derived report and spans, the `.evolve` ledger rows inside the session window, and a `manifest.json` with a SHA-256 per file.
+It spends no model call.
+A missing transcript stops the assembly.
+An absent optional input is recorded in `manifest.absent` with the probed path.
+
+## Pick the view for the reader
+
+That bundle is the FULL view (`manifest.view: "full"`), and it holds the whole session transcript.
+Never give it to a writer that must not see an earlier conclusion: the transcript holds the text of every file the session wrote, so a check for the earlier report FILE passes while its CONTENT is still readable.
+
+Project the writer's copy instead:
+
+```bash
+traces bundle-view .traces/bundle --view evidence-only --out .traces/writer
+```
+
+That view carries `derived/session-index.json`, `derived/evidence.jsonl`, and the structured `ledger/` records.
+It excludes the transcripts, the report, the spans, and every prose ledger file by name, with rules and hashes in `manifest.excluded`.
+Before writing, it compares each carried file against each excluded file for shared 8-word runs of prose, and drops any file that repeats one.
+`manifest.view` names which copy you hold.
+
 ## Report
 
 - State the source (`--otlp <path>` or the harness), selected task boundary, session and span counts, and integrity warnings.