@tangle-network/traces 0.23.1 → 1.0.1

package/dist/live-XXL7VZWB.js

@@ -0,0 +1,14 @@
+import {
+  streamSessions,
+  watchSource
+} from "./chunk-GNRXKQEQ.js";
+import "./chunk-REO2JQJY.js";
+import "./chunk-WF7PTDCZ.js";
+import "./chunk-7USMM4MA.js";
+import "./chunk-UQSAGXPH.js";
+import "./chunk-CQ6UYZG6.js";
+import "./chunk-DU534HAX.js";
+export {
+  streamSessions,
+  watchSource
+};

package/dist/mcp-EYIDKBEK.js

@@ -0,0 +1,85 @@
+import {
+  exportBytes,
+  openAgenticTraceStore
+} from "./chunk-2XXABIRL.js";
+import {
+  tracesVersion
+} from "./chunk-CQ6UYZG6.js";
+import {
+  assessSpans,
+  redactSpans
+} from "./chunk-RZL5GAWH.js";
+import "./chunk-DU534HAX.js";
+
+// src/mcp.ts
+import {
+  buildTraceAnalysisToolDescriptors,
+  combineVerdicts,
+  redact,
+  shareAllowed,
+  UNTRUSTED_TRACE_TEXT
+} from "@tangle-network/agent-eval/traces";
+import { createStdioToolServer } from "@tangle-network/agent-runtime/mcp";
+var MCP_RESULT_BYTE_CAP = 512 * 1024;
+function createServedSpans() {
+  const chunks = [];
+  const verdicts = [];
+  return {
+    add(spans) {
+      if (spans.length === 0) return;
+      const { spans: redacted } = redactSpans(spans);
+      verdicts.push(assessSpans(redacted));
+      chunks.push(exportBytes(redacted));
+    },
+    finish() {
+      return { bytes: Buffer.concat(chunks), verdict: combineVerdicts("default", verdicts) };
+    }
+  };
+}
+function traceMcpTools(options) {
+  const served = options.served ?? (() => {
+    const builder = createServedSpans();
+    builder.add(options.spans ?? []);
+    return builder.finish();
+  })();
+  const { verdict } = served;
+  if (!shareAllowed(verdict)) {
+    const findings = verdict.findings.map((f) => `${f.category}/${f.detector} (${f.count})`).join(", ");
+    throw new Error(
+      `mcp: refusing to serve \u2014 redacted spans are still ${verdict.status}` + (findings ? `: ${findings}` : "") + (verdict.unreadable.length > 0 ? `; unreadable: ${verdict.unreadable.join("; ")}` : "")
+    );
+  }
+  const store = openAgenticTraceStore(served.bytes);
+  const descriptors = buildTraceAnalysisToolDescriptors({ store }).filter((d) => d.name !== "readSpanSource");
+  return descriptors.map((descriptor) => ({
+    name: descriptor.name,
+    description: descriptor.description,
+    inputSchema: descriptor.parameters,
+    annotations: {
+      readOnlyHint: descriptor.readOnly,
+      idempotentHint: descriptor.idempotent,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    handler: async (args) => {
+      const { value } = redact(await descriptor.handler(args));
+      const result = { untrusted: UNTRUSTED_TRACE_TEXT, result: value };
+      const bytes = Buffer.byteLength(JSON.stringify(result));
+      if (bytes > MCP_RESULT_BYTE_CAP) {
+        throw new RangeError(
+          `${descriptor.name}: result is ${bytes} bytes, above the ${MCP_RESULT_BYTE_CAP}-byte cap; narrow the request`
+        );
+      }
+      return result;
+    }
+  }));
+}
+async function serveTraceMcp(options) {
+  const tools = traceMcpTools(options);
+  const server = createStdioToolServer({ serverName: "traces", serverVersion: tracesVersion(), tools });
+  await server.serve();
+}
+export {
+  createServedSpans,
+  serveTraceMcp
+};

package/dist/report-E3G2T5TJ.js

@@ -0,0 +1,338 @@
+import {
+  describeSessionRelationship,
+  minutesText,
+  renderFirstFailure,
+  sheetText,
+  topCounts,
+  utcMinute
+} from "./chunk-WF7PTDCZ.js";
+import "./chunk-7USMM4MA.js";
+import {
+  ACTOR_ATTR,
+  ATTR,
+  isInheritedSpan,
+  sessionIdFromAttributes
+} from "./chunk-UQSAGXPH.js";
+import "./chunk-CQ6UYZG6.js";
+import "./chunk-DU534HAX.js";
+
+// src/report.ts
+var CORRUPTION_RECEIPT_DISPLAY_LIMIT = 100;
+function sessionReportSource(ref, spans, sessionIdOverride) {
+  const root = spans.find((item) => item.parent_span_id === null) ?? spans[0];
+  const inScope = spans.filter((item) => !isInheritedSpan(item.attributes));
+  const prompt = inScope.find(
+    (item) => item.name === "user.prompt" && item.attributes[ACTOR_ATTR] === "human"
+  ) ?? inScope.find((item) => item.name === "user.prompt") ?? inScope.find(
+    (item) => item.attributes["span.type"] === "interaction" && typeof item.attributes.content === "string"
+  );
+  const content = typeof prompt?.attributes.content === "string" ? prompt.attributes.content : "";
+  const firstLine = content.split(/\r?\n/, 1)[0].trim();
+  const subject = firstLine.length > 240 ? `${firstLine.slice(0, 240)}\u2026 [+${firstLine.length - 240} chars]` : firstLine;
+  const role = root?.attributes["traces.session.role"];
+  const parentSessionId = root?.attributes["traces.parent_session_id"];
+  const relationship = describeSessionRelationship(ref, spans);
+  const corruptionDigest = root?.attributes[ATTR.CORRUPTION_DIGEST];
+  const sessionId = [
+    sessionIdOverride,
+    root ? sessionIdFromAttributes(root.attributes) : void 0,
+    root?.trace_id,
+    ref.sessionId
+  ].find((value) => typeof value === "string" && value.length > 0);
+  return {
+    sessionId,
+    path: ref.path,
+    subject,
+    role: role === "operator" || role === "child" ? role : "unknown",
+    ...typeof parentSessionId === "string" ? { parentSessionId } : {},
+    childSessionIds: relationship.childSessionIds,
+    ...relationship.depth !== void 0 ? { depth: relationship.depth } : {},
+    ...relationship.agentNickname ? { agentNickname: relationship.agentNickname } : {},
+    ...relationship.agentRole ? { agentRole: relationship.agentRole } : {},
+    ...relationship.agentPath ? { agentPath: relationship.agentPath } : {},
+    ...relationship.taskScope ? { taskScope: relationship.taskScope } : {},
+    ...relationship.turnId ? { turnId: relationship.turnId } : {},
+    integrity: ref.integrity?.status ?? "complete",
+    ...ref.integrity ? {
+      corruptionCount: ref.integrity.corruptions.length,
+      ...typeof corruptionDigest === "string" ? { corruptionDigest } : {},
+      corruptions: ref.integrity.corruptions.slice(0, CORRUPTION_RECEIPT_DISPLAY_LIMIT)
+    } : {}
+  };
+}
+var ANALYZE_TEXT_LINES = 40;
+var TABLE_SESSIONS = 15;
+var SEVERITY_LABEL = {
+  critical: "CRIT",
+  high: "HIGH",
+  medium: "MED",
+  low: "LOW",
+  info: "INFO"
+};
+function plural(count, noun, many = `${noun}s`) {
+  return `${count} ${count === 1 ? noun : many}`;
+}
+var short = (id) => id.slice(0, 8);
+function elapsedText(ms) {
+  const minutes = ms / 6e4;
+  if (minutes < 60) return minutesText(minutes);
+  const whole = Math.round(minutes);
+  return `${Math.floor(whole / 60)}h ${whole % 60}m`;
+}
+function costText(facts) {
+  return facts.cost.usd === null ? `cost unknown: ${sheetText(facts.cost.unavailable ?? "no reason recorded", 60)}` : `$${facts.cost.usd.toFixed(facts.cost.usd < 1 ? 4 : 2)} ${facts.cost.label}`;
+}
+function windowText(first, last) {
+  if (first === null || last === null) return null;
+  const [from, to] = [utcMinute(first), utcMinute(last)];
+  const elapsed = Date.parse(last) - Date.parse(first);
+  return `${from}\u2192${from.slice(0, 5) === to.slice(0, 5) ? to.slice(6) : to} UTC${Number.isFinite(elapsed) && elapsed > 0 ? `, ${elapsedText(elapsed)}` : ""}`;
+}
+function placeOf(facts) {
+  const repo = facts.repo.value;
+  return repo ? `${repo.repository.split("/").at(-1)}${repo.branch ? ` (${repo.branch})` : ""}` : facts.cwd.value?.split("/").filter(Boolean).at(-1);
+}
+function header(facts) {
+  const parts = [`${short(facts.sessionId ?? facts.traceId)} ${facts.harness ?? "unknown harness"}`];
+  const place = placeOf(facts);
+  if (place) parts.push(place);
+  const window = windowText(facts.firstRecordAt.value, facts.lastRecordAt.value);
+  if (window) parts.push(window);
+  if (facts.measurements.activeMinutes.value !== null) parts.push(`active ${minutesText(facts.measurements.activeMinutes.value)}`);
+  if (facts.parentSessionId) parts.push(`child of ${short(facts.parentSessionId)}`);
+  parts.push(costText(facts));
+  return parts.join(" \xB7 ");
+}
+function askedLine(facts) {
+  const turns = facts.humanTurns.value;
+  if (turns === null) return null;
+  const [first, ...rest] = turns;
+  if (!first) return null;
+  return `asked "${sheetText(first.text, 110)}"${rest.length > 0 ? ` (+${plural(rest.length, "more human turn")})` : ""}`;
+}
+function firstFailureLine(facts) {
+  const failure = facts.firstFailure;
+  return failure.status === "found" || failure.status === "ambiguous" ? `first failure ${renderFirstFailure(failure)}` : null;
+}
+function commandLines(facts) {
+  const waste = facts.measurements.waste;
+  const lines = [];
+  const streaks = [...waste.failingStreaks.value ?? []].sort((a, b) => b.minutes - a.minutes || b.runs - a.runs);
+  if (streaks.length > 0) {
+    const shown = streaks.slice(0, 2).map((streak) => {
+      const command = streak.command === null ? `a ${streak.tool} command` : `\`${sheetText(streak.command, 60)}\``;
+      return `${command} ${streak.runs}\xD7 in a row (${minutesText(streak.minutes)}, ${utcMinute(streak.at).slice(6)}, span ${streak.spanIds[0]})`;
+    });
+    lines.push(`failing commands ${streaks.length}: ${shown.join(" \xB7 ")}${streaks.length > 2 ? ` \xB7 +${streaks.length - 2} more` : ""}`);
+  }
+  const repeated = waste.repeatedCommands.value;
+  const rollbacks = waste.rollbacks.value ?? 0;
+  const rework = [];
+  if (repeated && repeated.commands > 0) rework.push(`${plural(repeated.commands, "command")} rerun, ${plural(repeated.extraRuns, "extra run")}`);
+  if (rollbacks > 0) rework.push(`${plural(rollbacks, "revert or reset --hard", "reverts or resets --hard")}`);
+  if (rework.length > 0) lines.push(`repeated ${rework.join(" \xB7 ")}`);
+  return lines;
+}
+function toolErrorLine(errors) {
+  if (!errors || errors.errors === 0) return null;
+  const clusters = errors.clusters.slice(0, 3).map((cluster) => `${cluster.tool} \xD7${cluster.count} "${sheetText(cluster.error, 50)}" (span ${cluster.spanIds[0]})`);
+  return `tool errors ${errors.errors}/${errors.calls}: ${clusters.join(" \xB7 ")}`;
+}
+function stallLine(facts) {
+  const stalls = facts.measurements.waste.stalls.value ?? [];
+  if (stalls.length === 0) return null;
+  const total = stalls.reduce((sum2, stall) => sum2 + stall.minutes, 0);
+  const shown = [...stalls].sort((a, b) => b.minutes - a.minutes).slice(0, 2).map((stall) => `${utcMinute(stall.at).slice(6)} ${stall.kind} ${minutesText(stall.minutes)} (span ${stall.spanId})`);
+  return `stalls ${stalls.length} \u2265 10 min, ${minutesText(total)}: ${shown.join(" \xB7 ")}${stalls.length > 2 ? ` \xB7 +${stalls.length - 2} more` : ""}`;
+}
+function signalQuote(turn) {
+  const when = utcMinute(turn.at).slice(6);
+  if (turn.signals.includes("interrupt")) return `  ${when} after an interrupt: "${sheetText(turn.text, 90)}"`;
+  if (turn.signals.includes("rejected-tool")) return `  ${when} after a rejected tool call: "${sheetText(turn.text, 90)}"`;
+  return `  ${when} "${sheetText(turn.text, 60)}" after the claim "${sheetText(turn.answered ?? "", 60)}"`;
+}
+function interruptLines(facts) {
+  const turns = facts.humanTurns.value ?? [];
+  const with_ = (signal) => turns.filter((turn) => turn.signals.includes(signal));
+  const interrupts = with_("interrupt");
+  const rejected = with_("rejected-tool");
+  const afterClaim = with_("after-claim");
+  if (interrupts.length + rejected.length + afterClaim.length === 0) return [];
+  const quoted = [.../* @__PURE__ */ new Set([...interrupts, ...rejected, ...afterClaim])].slice(0, 3);
+  return [
+    `Interrupts and rejections: ${plural(interrupts.length, "turn")} after an interrupt \xB7 ${plural(rejected.length, "turn")} after a rejected tool call \xB7 ${plural(afterClaim.length, "turn")} right after a completion claim`,
+    ...quoted.map(signalQuote)
+  ];
+}
+function prList(entries, keep = 6) {
+  const ids = entries.map((entry) => entry.identifier === null ? "unnumbered" : /^\d+$/u.test(entry.identifier) ? `#${entry.identifier}` : sheetText(entry.identifier, 30));
+  return `${entries.length}${ids.length > 0 ? ` (${ids.slice(0, keep).join(" ")}${ids.length > keep ? ` +${ids.length - keep}` : ""})` : ""}`;
+}
+function prLine(facts) {
+  const prs = facts.pullRequests.value;
+  if (prs === null || prs.created.length + prs.merged.length === 0) return null;
+  const files = facts.changedFiles.value === null ? "" : ` \xB7 changed ${plural(facts.changedFiles.value.length, "file")}`;
+  return `PRs opened ${prList(prs.created)} \xB7 merged ${prList(prs.merged)}${files}`;
+}
+function citedSpans(finding) {
+  const fromUris = finding.evidence_refs.flatMap((ref) => {
+    const match = /\/span\/([^/]+)$/u.exec(ref.uri);
+    return match ? [decodeURIComponent(match[1])] : [];
+  });
+  if (fromUris.length > 0) return [...new Set(fromUris)];
+  return finding.evidence_refs.flatMap((ref) => {
+    if (!ref.excerpt?.startsWith("{")) return [];
+    try {
+      const parsed = JSON.parse(ref.excerpt);
+      return [parsed.first_span_id, parsed.last_span_id].filter((id) => typeof id === "string");
+    } catch {
+      return [];
+    }
+  });
+}
+function findingLine(finding, sessions) {
+  const spans = citedSpans(finding);
+  const session = sessions > 1 && typeof finding.metadata?.sessionId === "string" ? `${short(finding.metadata.sessionId)} ` : "";
+  const cite = spans.length > 0 ? ` (span${spans.length > 1 ? "s" : ""} ${spans.slice(0, 2).join(", ")}${spans.length > 2 ? ", \u2026" : ""})` : "";
+  return `  ${SEVERITY_LABEL[finding.severity].padEnd(4)} ${session}${finding.subject ?? finding.area}: ${sheetText(finding.claim, 110)}${cite}`;
+}
+function closingLines(result, used) {
+  const findings = result.packet.findings;
+  const lines = [];
+  if (findings.length > 0) {
+    const counts = ["critical", "high", "medium", "low", "info"].map((severity) => [SEVERITY_LABEL[severity], findings.filter((finding) => finding.severity === severity).length]).filter(([, count]) => count > 0).map(([label, count]) => `${label} ${count}`);
+    lines.push(`findings ${findings.length} (${counts.join(", ")})`);
+    const room = ANALYZE_TEXT_LINES - used - lines.length - 1 - (result.cannotAnswer.length > 0 ? 1 : 0);
+    const shown = findings.length > room ? Math.max(0, room - 1) : findings.length;
+    for (const finding of findings.slice(0, shown)) lines.push(findingLine(finding, result.facts.sessions.length));
+    if (shown < findings.length) lines.push(`  \u2026 ${findings.length - shown} more: --format json | jq .packet.findings`);
+  } else {
+    lines.push("findings none");
+  }
+  if (result.cannotAnswer.length > 0) {
+    lines.push(`cannot answer ${plural(result.cannotAnswer.length, "question")}: --format json | jq .cannotAnswer, or report.md under --out DIR`);
+  }
+  return lines;
+}
+function singleSession(result, facts) {
+  const sessionId = facts.sessionId ?? facts.traceId;
+  return [
+    header(facts),
+    askedLine(facts),
+    firstFailureLine(facts),
+    ...commandLines(facts),
+    toolErrorLine(result.measures.toolErrors.find((entry) => entry.sessionId === sessionId)),
+    stallLine(facts),
+    ...interruptLines(facts),
+    prLine(facts)
+  ].filter((line) => line !== null);
+}
+function sum(values) {
+  return values.reduce((total, value) => total + (value ?? 0), 0);
+}
+function fleetHeader(result) {
+  const sessions = result.facts.sessions;
+  const byHarness = {};
+  for (const facts of sessions) byHarness[facts.harness ?? "unknown"] = (byHarness[facts.harness ?? "unknown"] ?? 0) + 1;
+  const firsts = sessions.map((facts) => facts.firstRecordAt.value).filter((value) => value !== null).sort();
+  const lasts = sessions.map((facts) => facts.lastRecordAt.value).filter((value) => value !== null).sort();
+  const unpriced = sessions.filter((facts) => facts.cost.usd === null).length;
+  const priced = sum(sessions.map((facts) => facts.cost.usd));
+  const cost = unpriced === sessions.length ? "cost unknown" : `$${priced.toFixed(2)} list price (Router rates)${unpriced > 0 ? `, ${unpriced} unpriced` : ""}`;
+  const wasteKnown = sessions.filter((facts) => facts.measurements.waste.minutes !== null);
+  const waste = wasteKnown.length === 0 ? "waste unknown" : `waste ${(sum(wasteKnown.map((facts) => facts.measurements.waste.minutes)) / 60).toFixed(1)} h${wasteKnown.length < sessions.length ? ` (${sessions.length - wasteKnown.length} unknown)` : ""}`;
+  const interrupts = sum(sessions.map((facts) => (facts.humanTurns.value ?? []).filter((turn) => turn.signals.includes("interrupt")).length));
+  const window = windowText(firsts[0] ?? null, lasts.at(-1) ?? null);
+  const lines = [[
+    `${plural(sessions.length, "session")} (${topCounts(byHarness, 4)})`,
+    ...window ? [window] : [],
+    cost,
+    waste,
+    `${plural(interrupts, "interrupt")}`
+  ].join(" \xB7 ")];
+  const unread = result.facts.selection?.unreadSessions ?? [];
+  if (unread.length > 0) lines.push(`unreadable ${unread.length}: ${unread.slice(0, 2).map((entry) => `${short(entry.sessionId ?? entry.traceId ?? entry.source ?? "?")} ${sheetText(entry.reason, 50)}`).join(" \xB7 ")}`);
+  return lines;
+}
+var kTokens = (tokens) => tokens < 1e3 ? String(tokens) : `${Math.round(tokens / 1e3)}k`;
+var seconds = (ms) => `${(ms / 1e3).toFixed(1)} s`;
+function operatingLine(result) {
+  const { modelCalls, guardRefusals, limitStops } = result.measures.operating;
+  if (modelCalls.calls === 0 && guardRefusals.toolCalls === 0) return void 0;
+  const parts = [];
+  const { mean, p50 } = modelCalls.contextTokens;
+  if (mean !== null) parts.push(`context/call mean ${kTokens(mean)}${p50 === void 0 ? "" : ` p50 ${kTokens(p50)}`}`);
+  const bands = modelCalls.latencyByContext;
+  if (bands.length > 0) {
+    const ends = bands.length === 1 ? [bands[0]] : [bands[0], bands.at(-1)];
+    parts.push(`reply p50 ${ends.map((band) => `${seconds(band.p50Ms)} at ${band.band}`).join(", ")}`);
+  }
+  if (guardRefusals.perThousandCalls !== null) {
+    const top = guardRefusals.byGuard[0];
+    parts.push(`guard refusals ${guardRefusals.perThousandCalls}/1k calls${top ? ` (${top.guard} ${top.refusals})` : ""}`);
+  }
+  parts.push(`limit stops ${limitStops.sessions} (${limitStops.terminalFailuresAtLimit}/${limitStops.terminalFailures} terminal failures)`);
+  return parts.join(" \xB7 ");
+}
+function cell(text, width) {
+  return text.length > width ? `${text.slice(0, width - 1)}\u2026` : text.padEnd(width);
+}
+function sessionTable(result) {
+  const sessions = [...result.facts.sessions].sort((a, b) => (b.measurements.waste.minutes ?? -1) - (a.measurements.waste.minutes ?? -1));
+  const rows = sessions.slice(0, TABLE_SESSIONS).map((facts) => {
+    const waste = facts.measurements.waste;
+    const turns = facts.humanTurns.value ?? [];
+    const prs = facts.pullRequests.value;
+    const signals = turns.filter((turn) => turn.signals.length > 0).length;
+    return [
+      cell(short(facts.sessionId ?? facts.traceId), 8),
+      cell(facts.harness ?? "?", 11),
+      cell(placeOf(facts) ?? "?", 22),
+      cell(facts.measurements.activeMinutes.value === null ? "?" : minutesText(facts.measurements.activeMinutes.value), 7),
+      cell(facts.cost.usd === null ? "?" : `$${facts.cost.usd.toFixed(2)}`, 8),
+      cell(waste.minutes === null ? "?" : minutesText(waste.minutes), 7),
+      cell(String((waste.failingStreaks.value ?? []).length), 7),
+      cell(String((waste.stalls.value ?? []).length), 6),
+      cell(String(signals), 7),
+      cell(prs === null ? "?" : `${prs.created.length}/${prs.merged.length}`, 5),
+      sheetText(turns[0]?.text ?? "", 40)
+    ].join(" ").trimEnd();
+  });
+  const head = ["session ", "harness    ", "repo                  ", "active ", "cost    ", "waste  ", "streaks", "stalls", "signals", "PRs  ", "asked"].join(" ");
+  return [head, ...rows, ...sessions.length > TABLE_SESSIONS ? [`\u2026 ${sessions.length - TABLE_SESSIONS} more sessions: --format json | jq .facts.sessions`] : []];
+}
+function renderAnalysis(result) {
+  const sessions = result.facts.sessions;
+  const operating = sessions.length === 1 ? void 0 : operatingLine(result);
+  const body = sessions.length === 1 ? singleSession(result, sessions[0]) : [...fleetHeader(result), ...sessionTable(result), ...operating ? [operating] : []];
+  const lines = [...body, ...closingLines(result, body.length)];
+  return `${lines.slice(0, ANALYZE_TEXT_LINES).join("\n")}
+`;
+}
+function cannotAnswerLine(entry) {
+  return `- **${entry.analysis}**${entry.sessionId ? ` (session \`${entry.sessionId}\`)` : ""}: ${entry.reason}`;
+}
+function renderAnalysisReport(result) {
+  return [
+    "# traces analyze",
+    "",
+    "```text",
+    renderAnalysis(result).trimEnd(),
+    "```",
+    "",
+    "## Findings",
+    ...result.packet.report.split("\n").filter((line) => !/^#{1,2} /u.test(line)),
+    "",
+    `## What these traces cannot answer (${result.cannotAnswer.length})`,
+    "",
+    ...result.cannotAnswer.length > 0 ? result.cannotAnswer.map(cannotAnswerLine) : ["Nothing: every analysis had what it reads."],
+    ""
+  ].join("\n");
+}
+export {
+  ANALYZE_TEXT_LINES,
+  elapsedText,
+  renderAnalysis,
+  renderAnalysisReport,
+  sessionReportSource
+};