@tangle-network/traces 0.9.17 → 0.9.18

package/dist/{chunk-I4W6DECY.js → chunk-F2OEMHVZ.js}

@@ -8975,7 +8975,58 @@ function traceCoverageFinding(pipelines, adoption) {
     }
   });
 }
-function deterministicFindings(pipelines, reactions, adoption) {
+function sortedToolErrorSpans(spans) {
+  return spans.filter((item) => item.attributes["openinference.span.kind"] === "TOOL" && item.status.code === "ERROR").sort((left, right) => left.start_time.localeCompare(right.start_time) || left.trace_id.localeCompare(right.trace_id) || left.span_id.localeCompare(right.span_id));
+}
+function toolErrorEvidence(item) {
+  return evidence(
+    "span",
+    spanEvidenceUri(item.trace_id, item.span_id),
+    `${String(item.attributes["tool.name"] ?? item.name)}: ${item.status.message ?? "tool span ended with ERROR"}`.slice(0, 240)
+  );
+}
+function toolErrorFinding(pipelines, spans) {
+  const terminalFailureTraceIds = new Set(
+    spans.filter((item) => item.parent_span_id === null && item.status.code === "ERROR").map((item) => item.trace_id)
+  );
+  const nonTerminalRuns = pipelines.toolUse.filter(
+    (run) => !terminalFailureTraceIds.has(run.runId)
+  );
+  const totalCalls = nonTerminalRuns.reduce((total, run) => total + run.totalCalls, 0);
+  const errorCount = nonTerminalRuns.reduce(
+    (total, run) => total + Object.values(run.byTool).reduce((runTotal, tool) => runTotal + tool.errors, 0),
+    0
+  );
+  if (errorCount === 0) return void 0;
+  const errorSpans = sortedToolErrorSpans(spans).filter((item) => !terminalFailureTraceIds.has(item.trace_id));
+  if (errorSpans.length === 0) return void 0;
+  const affectedRuns = new Set(errorSpans.map((item) => item.trace_id)).size;
+  const errorRate = errorCount / Math.max(1, totalCalls);
+  const citedSpans = errorSpans.slice(0, 3);
+  return makeFinding({
+    analyst_id: "traces-deterministic",
+    area: "tool-use",
+    subject: "non-terminal-tool-errors",
+    claim: `${errorCount}/${totalCalls} tool call(s) ended in errors across ${affectedRuns} run(s) without a terminal failure`,
+    severity: errorRate >= 0.25 ? "high" : "medium",
+    rationale: "Recovered tool errors still consume time and tokens, and repeated failures can hide brittle retry or recovery behavior.",
+    evidence_refs: citedSpans.map(toolErrorEvidence),
+    recommended_action: "Inspect the most frequent failing tool and its cited inputs, then change the retry or recovery policy so a failure produces new state before another call.",
+    validation_plan: "Rerun comparable sessions and require non-terminal tool errors to decrease without increasing terminal failures.",
+    confidence: 1,
+    metadata: {
+      source: "agent-eval.computeToolUseMetrics",
+      errorCount,
+      totalCalls,
+      errorRate,
+      affectedRuns,
+      citedErrorSpans: citedSpans.length,
+      omittedErrorSpans: Math.max(0, errorSpans.length - citedSpans.length)
+    },
+    id_basis: "non-terminal-tool-errors"
+  });
+}
+function deterministicFindings(pipelines, reactions, adoption, spans) {
   const findings = [];
   const coverage = traceCoverageFinding(pipelines, adoption);
   if (coverage) findings.push(coverage);
@@ -8998,10 +9049,16 @@ function deterministicFindings(pipelines, reactions, adoption) {
       metadata: { source: "traces.pipeline.stuckLoopView", loopCount: loops.length }
     }));
   }
+  const toolErrors = toolErrorFinding(pipelines, spans);
+  if (toolErrors) findings.push(toolErrors);
   const failedRuns = pipelines.failureClusters.totalFailures;
   if (failedRuns > 0) {
     const top = pipelines.failureClusters.clusters[0];
     const failureRate = failedRuns / Math.max(1, pipelines.failureClusters.totalRuns);
+    const exampleSpans = top?.exampleRunId ? spans.filter((item) => item.trace_id === top.exampleRunId) : [];
+    const exampleRoot = exampleSpans.find((item) => item.parent_span_id === null && item.status.code === "ERROR");
+    const exampleToolErrors = sortedToolErrorSpans(exampleSpans);
+    const citedToolErrors = exampleToolErrors.slice(0, 3);
     findings.push(makeFinding({
       analyst_id: "traces-deterministic",
       area: "reliability",
@@ -9009,12 +9066,17 @@ function deterministicFindings(pipelines, reactions, adoption) {
       severity: failureRate >= 0.1 ? "high" : "medium",
       rationale: "Execution errors consume time and tokens, and sparse error telemetry can hide whether the agent recovered or repeated the same failure.",
       evidence_refs: [
+        ...exampleRoot ? [evidence(
+          "span",
+          spanEvidenceUri(exampleRoot.trace_id, exampleRoot.span_id),
+          `${exampleRoot.name}: ${exampleRoot.status.message ?? "root span ended with ERROR"}`.slice(0, 240)
+        )] : [],
+        ...citedToolErrors.map(toolErrorEvidence),
         evidence(
           "metric",
           `pipelines.failure_cluster.${top?.failureClass ?? "unknown"}`,
           top ? `${top.runCount} run(s); example: ${top.exampleError ?? "error details not captured"}` : `${failedRuns} failed run(s)`
-        ),
-        ...top?.exampleRunId ? [evidence("span", `trace:${top.exampleRunId}`, top.exampleError)] : []
+        )
       ],
       recommended_action: top?.failureClass === "unknown" ? "Instrument the failing operation name and arguments, then start with the highest-frequency example error and verify the agent changes state before retrying." : "Fix the highest-frequency failure cluster first, then require the agent to inspect the error and change state before retrying.",
       validation_plan: "Rerun a comparable trace window and require failed runs and repeated failures in the top cluster to decrease.",
@@ -9024,7 +9086,9 @@ function deterministicFindings(pipelines, reactions, adoption) {
         failedRuns,
         totalRuns: pipelines.failureClusters.totalRuns,
         topFailureClass: top?.failureClass,
-        exampleRunId: top?.exampleRunId
+        exampleRunId: top?.exampleRunId,
+        citedToolErrorSpans: citedToolErrors.length,
+        omittedToolErrorSpans: Math.max(0, exampleToolErrors.length - citedToolErrors.length)
       }
     }));
   }
@@ -9212,7 +9276,7 @@ async function runTraceInvestigation(opts) {
     analyzeAdoption(opts.spans, { cwds: opts.cwds })
   ]);
   opts.signal?.throwIfAborted();
-  const deterministic = deterministicFindings(pipelines, reactions, adoption);
+  const deterministic = deterministicFindings(pipelines, reactions, adoption, opts.spans);
   const agenticRoute = opts.ai && !opts.agenticRegistry ? planTraceAgenticRoute(pipelines, reactions) : void 0;
   const analysis = await analyzeSpans(opts.spans, {
     ai: opts.ai,

package/dist/cli.js

@@ -43,7 +43,7 @@ import {
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-I4W6DECY.js";
+} from "./chunk-F2OEMHVZ.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";

package/dist/index.js

@@ -130,7 +130,7 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceImprovementArtifacts
-} from "./chunk-I4W6DECY.js";
+} from "./chunk-F2OEMHVZ.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {

package/docs/trace-analysts.md

@@ -175,10 +175,11 @@ It must also avoid inventing issues on clean trajectories.
 | Dataset | Labels used |
 | --- | --- |
 | AgentRx | Failure category, failed step, and root-cause step |
-| CodeTraceBench | Incorrect and unhelpful action steps, including clean trajectories |
+| CodeTraceBench | Incorrect and unhelpful action steps; solved label-empty rows are clean controls |
 
 Use `runAnalystBenchmark` to report recall, precision, F1, root-step accuracy, citation coverage, citation validity, clean-case false positives, repeat agreement, latency, calls, tokens, and known cost.
 Use `compareAnalystRunners` for paired baseline and candidate comparisons.
+Failed label-empty CodeTraceBench rows are unlabeled, not clean controls.
 
 ```ts
 import {

package/package.json

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