@tangle-network/traces 0.23.1 → 1.0.0

package/dist/analyst-model-call-JVUOYZ5V.js

@@ -0,0 +1,20 @@
+import {
+  ANALYST_MAX_OUTPUT_TOKENS,
+  UnservableModelError,
+  analysisEngineFromEnv,
+  bridgeVersion,
+  createAnalystModelOwner,
+  missingAskRequirements
+} from "./chunk-GLUDGUGJ.js";
+import {
+  DEFAULT_ANALYST_MODEL
+} from "./chunk-O52XK7OB.js";
+export {
+  ANALYST_MAX_OUTPUT_TOKENS,
+  DEFAULT_ANALYST_MODEL,
+  UnservableModelError,
+  analysisEngineFromEnv,
+  bridgeVersion,
+  createAnalystModelOwner,
+  missingAskRequirements
+};

package/dist/ask-XLS3VANY.js

@@ -0,0 +1,39 @@
+import {
+  createTraceQuestionCorpus,
+  engineCallReservationFloorUsd,
+  isBridgeMismatchError,
+  loadTraceQuestionsFile,
+  normalizeTraceQuestions,
+  renderTraceQuestionInstructions,
+  renderTraceQuestionPrompt,
+  renderTraceQuestionsReport,
+  runTraceQuestions,
+  traceCitationsInText,
+  writeTraceQuestionsArtifacts
+} from "./chunk-NH7HCDLB.js";
+import "./chunk-PYH3PL3N.js";
+import {
+  DEFAULT_ASK_CONCURRENCY,
+  MAX_TRACE_QUESTION_CHARS
+} from "./chunk-O52XK7OB.js";
+import "./chunk-3I4PJ5Q7.js";
+import "./chunk-UVE5ANVV.js";
+import "./chunk-3T62R7ON.js";
+import "./chunk-TR6O4S4T.js";
+import "./chunk-NZ5Y7UEL.js";
+import "./chunk-DU534HAX.js";
+export {
+  DEFAULT_ASK_CONCURRENCY,
+  MAX_TRACE_QUESTION_CHARS,
+  createTraceQuestionCorpus,
+  engineCallReservationFloorUsd,
+  isBridgeMismatchError,
+  loadTraceQuestionsFile,
+  normalizeTraceQuestions,
+  renderTraceQuestionInstructions,
+  renderTraceQuestionPrompt,
+  renderTraceQuestionsReport,
+  runTraceQuestions,
+  traceCitationsInText,
+  writeTraceQuestionsArtifacts
+};

package/dist/check-YF6ZHPGG.js

@@ -0,0 +1,322 @@
+import {
+  formatVerdict
+} from "./chunk-4VKPN432.js";
+import {
+  redactSpans
+} from "./chunk-RZL5GAWH.js";
+import {
+  parseIsoToEpochMs,
+  toolArgumentsFromAttributes
+} from "./chunk-DU534HAX.js";
+
+// src/check.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import {
+  compileTraceContractSpec,
+  evaluateTraceContract,
+  explainTraceContract,
+  lintTraceContractSpec
+} from "@tangle-network/agent-eval";
+var CONFORMANCE = "conformance";
+var CHECK_EXIT = Object.freeze({
+  pass: 0,
+  fail: 1,
+  /** A rule or verdict could not run, the contract is malformed, or the trace is unreadable or ambiguous. */
+  couldNotDecide: 2
+});
+var AmbiguousTraceInputError = class extends Error {
+  name = "AmbiguousTraceInputError";
+};
+var ContractFileError = class extends Error {
+  name = "ContractFileError";
+};
+async function loadContract(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    throw new ContractFileError(`cannot read contract ${path}: ${errorText(error)}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    throw new ContractFileError(`contract ${path} is not JSON: ${errorText(error)}`);
+  }
+  try {
+    const findings = lintTraceContractSpec(json);
+    const errors = findings.filter((f) => f.level === "error");
+    if (errors.length > 0) {
+      throw new ContractFileError(
+        `contract ${path} contradicts itself:
+${errors.map((f) => `  ${f.path}: ${f.message} [${f.code}]`).join("\n")}`
+      );
+    }
+    return {
+      path,
+      contract: compileTraceContractSpec(json),
+      warnings: findings.map((f) => `${f.path}: ${f.message} [${f.code}]`)
+    };
+  } catch (error) {
+    if (error instanceof ContractFileError) throw error;
+    throw new ContractFileError(`contract ${path}: ${errorText(error)}`);
+  }
+}
+function contractSpansFromOtlp(spans) {
+  return spans.map((span) => {
+    const startedAt = epochMs(span.start_time);
+    const endedAt = epochMs(span.end_time);
+    const args = toolArgumentsFromAttributes(span.attributes);
+    const truncated = span.attributes["traces.input.truncated"] === true;
+    return {
+      spanId: span.span_id,
+      parentSpanId: span.parent_span_id,
+      name: span.name,
+      ...startedAt === void 0 ? {} : { startedAt },
+      ...endedAt === void 0 ? {} : { endedAt },
+      ...span.status.code === "ERROR" ? { status: "error" } : span.status.code === "OK" ? { status: "ok" } : {},
+      // A truncated argument capture is not the call's arguments.
+      ...args.argsCaptured && !truncated ? { args: args.args } : { argsCaptured: false },
+      attributes: span.attributes
+    };
+  });
+}
+function epochMs(value) {
+  try {
+    return parseIsoToEpochMs(value);
+  } catch {
+    return void 0;
+  }
+}
+function groupByTrace(spans) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    const list = groups.get(span.trace_id) ?? [];
+    list.push(span);
+    groups.set(span.trace_id, list);
+  }
+  return [...groups].map(([traceId, list]) => ({ traceId, spans: list }));
+}
+async function runCheck(contract, spans, opts = {}) {
+  const traces = [];
+  for (const group of groupByTrace(spans)) {
+    const verdict = evaluateTraceContract(contract, contractSpansFromOtlp(group.spans));
+    const check = { traceId: group.traceId, spanCount: group.spans.length, verdict };
+    if (verdict.status !== "pass" && opts.evidenceRoot !== void 0) {
+      check.evidenceDir = await writeEvidence(opts.evidenceRoot, contract, group.traceId, group.spans, verdict);
+    }
+    traces.push(check);
+  }
+  const status = traces.some((t) => t.verdict.status === "error") ? "error" : traces.every((t) => t.verdict.status === "pass") ? "pass" : "fail";
+  const exitCode = status === "pass" ? CHECK_EXIT.pass : status === "fail" ? CHECK_EXIT.fail : CHECK_EXIT.couldNotDecide;
+  return { contract: contract.name, status, exitCode, traces };
+}
+async function writeEvidence(root, contract, traceId, spans, verdict) {
+  const dir = join(root, `${safeName(contract.name)}-${safeName(traceId).slice(0, 40)}`);
+  await mkdir(dir, { recursive: true });
+  const cited = new Set(verdict.violations.map((v) => v.spanId).filter((id) => id !== void 0));
+  const redacted = redactSpans(spans.filter((s) => cited.has(s.span_id)));
+  await writeFile(join(dir, "verdict.json"), `${JSON.stringify({ traceId, verdict }, null, 2)}
+`);
+  await writeFile(join(dir, "contract.json"), `${JSON.stringify(contract, null, 2)}
+`);
+  await writeFile(join(dir, "explain.txt"), `${explainTraceContract(contract)}
+`);
+  await writeFile(join(dir, "cited-spans.jsonl"), redacted.spans.map((s) => JSON.stringify(s)).join("\n") + (redacted.spans.length ? "\n" : ""));
+  return dir;
+}
+function safeName(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+function ruleLines(verdict) {
+  const branchPassed = /* @__PURE__ */ new Map();
+  for (const e of verdict.ruleExecutions) {
+    if (e.alternative === void 0) continue;
+    branchPassed.set(e.alternative, (branchPassed.get(e.alternative) ?? true) && e.status === "pass");
+  }
+  const anyBranchPassed = [...branchPassed.values()].some(Boolean);
+  return verdict.ruleExecutions.map((e) => {
+    const rule = e.alternative ? `${e.alternative}/${e.rule}` : e.rule;
+    const status = e.alternative && anyBranchPassed && !branchPassed.get(e.alternative) ? "skipped" : e.status;
+    return {
+      rule,
+      status,
+      ...e.error === void 0 ? {} : { error: e.error },
+      details: verdict.violations.filter((x) => x.rule === rule).map((x) => x.detail)
+    };
+  });
+}
+function renderCheckText(report) {
+  const lines = [];
+  for (const t of report.traces) {
+    const v = t.verdict;
+    lines.push(`${v.status.toUpperCase()}  contract ${report.contract}  trace ${t.traceId}  (${t.spanCount} spans, ${v.notes})`);
+    for (const r of ruleLines(v)) {
+      lines.push(`  ${r.status.padEnd(7)} ${r.rule}${r.error ? `  ${r.error}` : ""}`);
+      if (r.status === "fail") for (const detail of r.details.slice(0, 5)) lines.push(`          ${detail}`);
+    }
+    if (t.evidenceDir) lines.push(`  evidence \u2192 ${t.evidenceDir}`);
+  }
+  return lines.join("\n");
+}
+function contractSuites(report) {
+  return report.traces.map((t) => {
+    const rules = ruleLines(t.verdict);
+    const count = (status) => rules.filter((r) => r.status === status).length;
+    const cases = rules.map((r) => {
+      const open = `    <testcase classname="${xml(report.contract)}" name="${xml(r.rule)}">`;
+      if (r.status === "pass") return `${open}</testcase>`;
+      if (r.status === "skipped") return `${open}
+      <skipped message="another alternative passed"/>
+    </testcase>`;
+      if (r.status === "error") {
+        return `${open}
+      <error message="${xml(r.error ?? "rule could not be evaluated")}"/>
+    </testcase>`;
+      }
+      return `${open}
+      <failure message="${xml(r.details[0] ?? "rule failed")}">${xml(r.details.join("\n"))}</failure>
+    </testcase>`;
+    });
+    return [
+      `  <testsuite name="${xml(`${report.contract} @ ${t.traceId}`)}" tests="${rules.length}" failures="${count("fail")}" errors="${count("error")}" skipped="${count("skipped")}">`,
+      ...cases,
+      "  </testsuite>"
+    ].join("\n");
+  });
+}
+function renderGithubAnnotations(report) {
+  const lines = [];
+  for (const t of report.traces) {
+    for (const r of ruleLines(t.verdict)) {
+      if (r.status === "pass" || r.status === "skipped") continue;
+      const detail = r.status === "error" ? `could not be evaluated: ${r.error ?? "unknown"}` : r.details.join("\n");
+      lines.push(`::error title=${ghProperty(`${report.contract}: ${r.rule}`)}::${ghData(`trace ${t.traceId}: ${detail}`)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function contractGate(report) {
+  return { gate: "contract", status: report.status === "error" ? "unknown" : report.status, report };
+}
+function conformanceGate(subject, validation, text) {
+  return { gate: "conformance", status: validation.ok ? "pass" : "fail", subject, validation, text };
+}
+function shareSafeGate(verdict) {
+  const status = verdict.status === "UNSAFE" ? "fail" : verdict.status === "UNKNOWN" ? "unknown" : "pass";
+  return { gate: "share-safe", status, verdict };
+}
+function combineGates(gates) {
+  const status = gates.some((gate) => gate.status === "fail") ? "fail" : gates.some((gate) => gate.status === "unknown") ? "unknown" : "pass";
+  const exitCode = status === "pass" ? CHECK_EXIT.pass : status === "fail" ? CHECK_EXIT.fail : CHECK_EXIT.couldNotDecide;
+  return { status, exitCode, gates };
+}
+async function writeGateEvidence(root, verdict) {
+  for (const gate of verdict.gates) {
+    if (gate.status === "pass" || gate.gate === "contract") continue;
+    await mkdir(root, { recursive: true });
+    if (gate.gate === "conformance") await writeFile(join(root, "conformance.md"), `${gate.text}
+`);
+    else await writeFile(join(root, "share-safe.json"), `${JSON.stringify(gate.verdict, null, 2)}
+`);
+  }
+}
+var CONFORMANCE_EXPLAINED = [
+  "conformance: whether the input can be read as a trace at all, and which analyses its spans can support.",
+  "  fail  not one entry could be read as a span (an empty export, or every line unreadable)",
+  "  pass  spans were read; each capability a field they lack costs is listed with what it empties"
+].join("\n");
+function renderVerdictText(verdict) {
+  return verdict.gates.map((gate) => {
+    if (gate.gate === "contract") return renderCheckText(gate.report);
+    if (gate.gate === "conformance") return gate.text;
+    return formatVerdict(gate.verdict);
+  }).join("\n\n");
+}
+function renderVerdictJUnit(verdict) {
+  const suites = verdict.gates.flatMap((gate) => {
+    if (gate.gate === "contract") return contractSuites(gate.report);
+    if (gate.gate === "conformance") {
+      const readable = gate.validation.ok ? '    <testcase classname="conformance" name="readable"></testcase>' : `    <testcase classname="conformance" name="readable">
+      <failure message="not one entry could be read as a span"/>
+    </testcase>`;
+      const capabilities = gate.validation.capabilities.map((capability) => capability.available ? `    <testcase classname="conformance" name="${xml(capability.name)}"></testcase>` : `    <testcase classname="conformance" name="${xml(capability.name)}">
+      <skipped message="${xml(capability.reason ?? "unavailable")}"/>
+    </testcase>`);
+      const unavailable = gate.validation.capabilities.filter((capability) => !capability.available).length;
+      return [[
+        `  <testsuite name="${xml(`conformance @ ${gate.subject}`)}" tests="${capabilities.length + 1}" failures="${gate.validation.ok ? 0 : 1}" errors="0" skipped="${unavailable}">`,
+        readable,
+        ...capabilities,
+        "  </testsuite>"
+      ].join("\n")];
+    }
+    const result = gate.verdict;
+    const findings = result.findings.map((finding) => `${finding.severity} ${finding.category}/${finding.detector} x${finding.count} at ${finding.paths.join(", ")}`);
+    const body = gate.status === "fail" ? `
+      <failure message="${xml(`${result.status}: ${findings[0] ?? ""}`)}">${xml(findings.join("\n"))}</failure>
+    ` : gate.status === "unknown" ? `
+      <error message="${xml(`UNKNOWN: ${result.unreadable[0] ?? "part of the input could not be read"}`)}">${xml(result.unreadable.join("\n"))}</error>
+    ` : findings.length > 0 ? `
+      <system-out>${xml(findings.join("\n"))}</system-out>
+    ` : "";
+    return [[
+      `  <testsuite name="${xml(`share-safe @ ${result.target}`)}" tests="1" failures="${gate.status === "fail" ? 1 : 0}" errors="${gate.status === "unknown" ? 1 : 0}" skipped="0">`,
+      `    <testcase classname="share-safe" name="${xml(result.target)}">${body}</testcase>`,
+      "  </testsuite>"
+    ].join("\n")];
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="traces check">
+${suites.join("\n")}
+</testsuites>
+`;
+}
+function renderVerdictGithub(verdict) {
+  const lines = [];
+  for (const gate of verdict.gates) {
+    if (gate.gate === "contract") {
+      const annotations = renderGithubAnnotations(gate.report);
+      if (annotations) lines.push(annotations);
+    } else if (gate.gate === "conformance") {
+      if (!gate.validation.ok) lines.push(`::error title=${ghProperty("conformance")}::${ghData(`${gate.subject}: not one entry could be read as a span`)}`);
+    } else {
+      const result = gate.verdict;
+      for (const finding of result.findings) {
+        const kind = finding.severity === "error" ? "error" : "warning";
+        lines.push(`::${kind} title=${ghProperty(`share-safe: ${finding.category}/${finding.detector}`)}::${ghData(`${result.target}: x${finding.count} at ${finding.paths.join(", ")}`)}`);
+      }
+      for (const entry of result.unreadable) lines.push(`::error title=${ghProperty("share-safe: unreadable")}::${ghData(entry)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function xml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, "");
+}
+function ghData(value) {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function ghProperty(value) {
+  return ghData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  AmbiguousTraceInputError,
+  CHECK_EXIT,
+  CONFORMANCE,
+  CONFORMANCE_EXPLAINED,
+  combineGates,
+  conformanceGate,
+  contractGate,
+  loadContract,
+  renderVerdictGithub,
+  renderVerdictJUnit,
+  renderVerdictText,
+  runCheck,
+  shareSafeGate,
+  writeGateEvidence
+};

package/dist/chunk-3I4PJ5Q7.js

@@ -0,0 +1,25 @@
+import {
+  iterSerializedSpans
+} from "./chunk-NZ5Y7UEL.js";
+
+// src/analysis-store.ts
+import { otlpTextToTraceAnalysisStore } from "@tangle-network/agent-eval/traces";
+var DETERMINISTIC_PER_CALL_CEILING = 512 * 1024 * 1024;
+function openAgenticTraceStore(spans) {
+  return otlpTextToTraceAnalysisStore(spans instanceof Uint8Array ? spans : exportBytes(spans));
+}
+function openDeterministicTraceStore(spans) {
+  const bytes = spans instanceof Uint8Array ? spans : exportBytes(spans);
+  return otlpTextToTraceAnalysisStore(bytes, { perCallByteCeiling: DETERMINISTIC_PER_CALL_CEILING });
+}
+function exportBytes(spans) {
+  const lines = [];
+  for (const line of iterSerializedSpans(spans)) lines.push(Buffer.from(line, "utf8"));
+  return Buffer.concat(lines);
+}
+
+export {
+  openAgenticTraceStore,
+  openDeterministicTraceStore,
+  exportBytes
+};