@tangle-network/traces 0.23.1 → 1.0.1

package/dist/chunk-GLUDGUGJ.js

@@ -0,0 +1,232 @@
+import {
+  DEFAULT_QUESTION_TIMEOUT_MS
+} from "./chunk-O52XK7OB.js";
+
+// src/analyst-model-call.ts
+import { accessSync, constants, readFileSync } from "fs";
+import { delimiter, join } from "path";
+import {
+  canonicalAgentProfileDigest,
+  canonicalCandidateDigest
+} from "@tangle-network/agent-interface";
+import { profileOptimizerModelCall } from "@tangle-network/agent-runtime/kernel";
+import { createDspyRlmTraceEngine } from "@tangle-network/agent-eval/analyst";
+var TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
+var BRIDGE_MODULE = "agent_eval_rpc.dspy_rlm_bridge";
+var ANALYST_MAX_OUTPUT_TOKENS = 16384;
+function bridgeVersion() {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const version = pkg.dependencies?.["@tangle-network/agent-eval"];
+  if (typeof version !== "string" || !version) {
+    throw new Error("package.json is missing the @tangle-network/agent-eval dependency");
+  }
+  return version;
+}
+function bridgeRunner(env) {
+  if (env.TRACES_PYTHON) return { command: env.TRACES_PYTHON };
+  return { command: "uvx", args: ["--from", `agent-eval-rpc[dspy]==${bridgeVersion()}`, "python", "-m", BRIDGE_MODULE] };
+}
+function runnable(command, path) {
+  const candidates = command.includes("/") ? [command] : (path ?? "").split(delimiter).filter(Boolean).map((dir) => join(dir, command));
+  return candidates.some((candidate) => {
+    try {
+      accessSync(candidate, constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+function missingAskRequirements(env = process.env) {
+  const missing = [];
+  if (!env.TANGLE_API_KEY && !env.OPENAI_API_KEY) {
+    missing.push(
+      "a model key: set TANGLE_API_KEY for the Tangle router, or OPENAI_API_KEY (OPENAI_BASE_URL names any other OpenAI-compatible endpoint)"
+    );
+  }
+  const bridge = env.TRACES_PYTHON ? runnable(env.TRACES_PYTHON, env.PATH) : runnable("uvx", env.PATH);
+  if (!bridge) {
+    missing.push(
+      env.TRACES_PYTHON ? `the Python bridge: TRACES_PYTHON=${env.TRACES_PYTHON} is not an executable` : `the Python bridge: install uv (https://docs.astral.sh/uv/), or set TRACES_PYTHON to a Python with agent-eval-rpc[dspy]==${bridgeVersion()}`
+    );
+  }
+  return missing;
+}
+var UnservableModelError = class extends Error {
+  failure;
+  constructor(failure) {
+    super(failure.message);
+    this.name = "UnservableModelError";
+    this.failure = failure;
+  }
+};
+var TRANSIENT_STATUSES = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504, 520, 522, 524]);
+var UNSERVABLE_MODEL = /model_not_allowed|model_not_found|provider_pricing_unavailable|not in this key's allow-list|unknown model/iu;
+function endpointWords(body) {
+  const message = /"message":"((?:[^"\\]|\\.)*)/u.exec(body)?.[1];
+  return (message ?? body).replace(/\\"/gu, '"').slice(0, 240);
+}
+function classifyModelFailure(error, model) {
+  const served = /reported model ("[^"]*") but AgentProfile requires ("[^"]*")/u.exec(error);
+  if (served) {
+    return {
+      kind: "permanent",
+      failure: {
+        code: "model",
+        message: `the endpoint served ${served[1]} for --model ${served[2]}, and ask refuses an answer from a model it did not ask for; pass the provider-qualified model id (for example zai/glm-5.3)`
+      }
+    };
+  }
+  const refused = /\brouter (\d{3}): (.*)$/su.exec(error);
+  if (!refused) {
+    return /router network failure|router request timeout|ECONNRESET|ETIMEDOUT|socket hang up|fetch failed/u.test(error) ? { kind: "transient", reason: "the endpoint could not be reached" } : { kind: "other" };
+  }
+  const status = Number(refused[1]);
+  const words = endpointWords(refused[2]);
+  if (status === 401 || status === 402 || status === 403) {
+    return {
+      kind: "permanent",
+      failure: { code: "auth", message: `the model endpoint refused the key (${status}: ${words}). Check TANGLE_API_KEY, or OPENAI_API_KEY and OPENAI_BASE_URL` }
+    };
+  }
+  if (UNSERVABLE_MODEL.test(refused[2])) {
+    return {
+      kind: "permanent",
+      failure: { code: "model", message: `the model endpoint cannot serve --model ${model} (${status}: ${words})` }
+    };
+  }
+  return TRANSIENT_STATUSES.has(status) ? { kind: "transient", reason: `${status}: ${words}` } : { kind: "other" };
+}
+var MODEL_CALL_ATTEMPTS = 10;
+var FIRST_RETRY_DELAY_MS = 2e3;
+var MAX_RETRY_DELAY_MS = 6e4;
+function retryDelayMs(attempt) {
+  const delay = Math.min(MAX_RETRY_DELAY_MS, FIRST_RETRY_DELAY_MS * 2 ** (attempt - 1));
+  return Math.round(delay * (0.75 + Math.random() * 0.5));
+}
+function pause(ms, signal) {
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const done = (slept) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", aborted);
+      resolve(slept);
+    };
+    const aborted = () => done(false);
+    const timer = setTimeout(() => done(true), ms);
+    signal?.addEventListener("abort", aborted, { once: true });
+  });
+}
+function retryingModelCall(call, opts) {
+  return async (request) => {
+    for (let attempt = 1; ; attempt += 1) {
+      const result = await call(request);
+      if (result.succeeded) return result;
+      const failure = classifyModelFailure(result.error, opts.model);
+      if (failure.kind === "permanent") {
+        opts.onPermanentFailure?.(failure.failure);
+        return result;
+      }
+      if (failure.kind === "other" || attempt >= MODEL_CALL_ATTEMPTS) return result;
+      const delay = retryDelayMs(attempt);
+      opts.log?.(
+        `[analyst] WARN model call failed (${failure.reason}); attempt ${attempt + 1} of ${MODEL_CALL_ATTEMPTS} in ${(delay / 1e3).toFixed(1)} s`
+      );
+      if (!await pause(delay, request.signal)) return result;
+    }
+  };
+}
+function createAnalystModelOwner(opts) {
+  const profile = {
+    name: "traces-analyst",
+    harness: "cli-base",
+    model: {
+      provider: opts.provider,
+      default: opts.model,
+      reasoningEffort: "none",
+      maxVisibleOutputTokens: ANALYST_MAX_OUTPUT_TOKENS,
+      metadata: {
+        // Stream every analyst call. The Tangle Router bounds a buffered request by a deadline that
+        // ends when response headers are sent, and a thinking model's long recursive step outlives
+        // it (`request_deadline_exceeded`). A streamed response sends headers at the first byte.
+        stream: true,
+        // One attempt per call: `retryingModelCall` decides what to retry from the endpoint's
+        // status and code, because Runtime's retry reads the status alone.
+        retry: { maxAttempts: 1 }
+      }
+    }
+  };
+  return {
+    call: profileOptimizerModelCall({
+      profile,
+      context: "traces analyst",
+      executor: {
+        backend: "router",
+        routerBaseUrl: opts.baseUrl,
+        routerKey: opts.apiKey
+      }
+    }),
+    callRef: canonicalCandidateDigest({
+      profile: canonicalAgentProfileDigest(profile),
+      endpoint: opts.baseUrl
+    }),
+    profile
+  };
+}
+function analysisEngineFromEnv(opts) {
+  const env = opts.env ?? process.env;
+  const tangleKey = env.TANGLE_API_KEY;
+  const openAiKey = env.OPENAI_API_KEY;
+  const apiKey = tangleKey || openAiKey;
+  if (!apiKey) {
+    throw new Error(
+      "model-backed analysis needs a model key: TANGLE_API_KEY for the Tangle router (the default endpoint), or OPENAI_API_KEY for OpenAI. Set OPENAI_BASE_URL to target any other OpenAI-compatible gateway. Deterministic analysis needs no key."
+    );
+  }
+  const baseUrl = env.OPENAI_BASE_URL || (tangleKey ? TANGLE_ROUTER_BASE_URL : "https://api.openai.com/v1");
+  const owner = createAnalystModelOwner({
+    apiKey,
+    baseUrl,
+    model: opts.model,
+    provider: baseUrl === TANGLE_ROUTER_BASE_URL ? "tangle-router" : baseUrl.startsWith("https://api.openai.com/") ? "openai" : "openai-compatible"
+  });
+  const log = opts.log;
+  try {
+    return createDspyRlmTraceEngine({
+      call: retryingModelCall(owner.call, {
+        model: opts.model,
+        ...log ? { log } : {},
+        ...opts.onPermanentFailure ? { onPermanentFailure: opts.onPermanentFailure } : {}
+      }),
+      callRef: owner.callRef,
+      recordExecution: (observation) => {
+        log?.(
+          `[analyst] model call ${observation.sequence} ${observation.succeeded ? "ok" : "FAIL"} ${observation.model}`,
+          observation.succeeded ? void 0 : { error: observation.error }
+        );
+      },
+      model: opts.model,
+      maxOutputTokens: ANALYST_MAX_OUTPUT_TOKENS,
+      // The engine's own default ceiling is $1 per investigation, a proxy-side
+      // ceiling separate from any shared ledger; the caller's allocation wins.
+      ...opts.maxCostUsd !== void 0 && Number.isFinite(opts.maxCostUsd) && opts.maxCostUsd > 0 ? { maxCostUsd: opts.maxCostUsd } : {},
+      timeoutMs: opts.timeoutMs ?? DEFAULT_QUESTION_TIMEOUT_MS,
+      runner: bridgeRunner(env)
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/no pricing is configured/u.test(message)) {
+      throw new UnservableModelError({ code: "model", message: `ask cannot price --model ${opts.model}, so it cannot bound the spend: ${message}` });
+    }
+    throw error;
+  }
+}
+
+export {
+  ANALYST_MAX_OUTPUT_TOKENS,
+  bridgeVersion,
+  missingAskRequirements,
+  UnservableModelError,
+  createAnalystModelOwner,
+  analysisEngineFromEnv
+};

package/dist/chunk-GNRXKQEQ.js

@@ -0,0 +1,120 @@
+import {
+  orderSpans,
+  ruleContext,
+  runRules
+} from "./chunk-REO2JQJY.js";
+import {
+  parseSession,
+  scanSessions
+} from "./chunk-7USMM4MA.js";
+import {
+  sessionIdFromAttributes
+} from "./chunk-UQSAGXPH.js";
+
+// src/live.ts
+var sleep = (ms, signal) => new Promise((resolve) => {
+  if (signal?.aborted) {
+    resolve();
+    return;
+  }
+  const onAbort = () => {
+    clearTimeout(t);
+    resolve();
+  };
+  const t = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function watchSource(source, opts) {
+  const intervalMs = Math.max(250, opts.intervalMs ?? 5e3);
+  const seenSessions = /* @__PURE__ */ new Set();
+  const spanCounts = /* @__PURE__ */ new Map();
+  const seenFindings = /* @__PURE__ */ new Set();
+  while (!opts.signal?.aborted) {
+    let sessions = 0;
+    let newSpans = 0;
+    let findings = 0;
+    const unread = [];
+    for await (const { session, spans } of source(unread)) {
+      const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const ordered = orderSpans(spans);
+      const key = `${session.harness}:${session.sessionId}`;
+      sessions += 1;
+      newSpans += Math.max(0, ordered.length - (spanCounts.get(key) ?? 0));
+      spanCounts.set(key, ordered.length);
+      if (!seenSessions.has(key)) {
+        seenSessions.add(key);
+        await opts.onEvent({
+          schemaVersion: 1,
+          kind: "traces.stream.session",
+          event: "session",
+          generatedAt,
+          session,
+          spanCount: ordered.length,
+          startedAt: ordered[0]?.start_time ?? null,
+          endedAt: ordered.at(-1)?.end_time ?? null
+        });
+      }
+      for (const finding of runRules(ruleContext(ordered, { session, generatedAt }), { extraAnalysts: opts.extraAnalysts })) {
+        if (seenFindings.has(finding.id)) continue;
+        seenFindings.add(finding.id);
+        findings += 1;
+        await opts.onEvent({ schemaVersion: 1, kind: "traces.stream.finding", event: "finding", generatedAt, finding });
+      }
+    }
+    await opts.onEvent({
+      schemaVersion: 1,
+      kind: "traces.stream.tick",
+      event: "tick",
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sessions,
+      newSpans,
+      findings,
+      unreadSessions: unread
+    });
+    if (opts.once || opts.signal?.aborted) break;
+    await sleep(intervalMs, opts.signal);
+  }
+}
+function sessionSource(opts) {
+  return async function* (unread) {
+    const skip = (error, ref) => {
+      unread.push({ sessionId: ref?.sessionId ?? null, source: ref?.path ?? "a session store", reason: errorText(error) });
+      opts.onError?.(error, ref);
+    };
+    const named = opts.sessions;
+    if (named) {
+      for (const { adapter, ref } of named) {
+        if (opts.signal?.aborted) return;
+        let spans;
+        try {
+          spans = await parseSession(adapter, ref, { corruptionMode: opts.corruptionMode, signal: opts.signal });
+        } catch (error) {
+          skip(error, ref);
+          continue;
+        }
+        const root = spans.find((span) => span.parent_span_id === null) ?? spans[0];
+        const sessionId = (root && sessionIdFromAttributes(root.attributes)) ?? ref.sessionId;
+        yield { session: { harness: adapter.harness, sessionId, cwd: ref.cwd, path: ref.path }, spans };
+      }
+      return;
+    }
+    const scanned = scanSessions({ ...opts, sinceMs: opts.sinceMs ?? Date.now() - (opts.windowMs ?? 30 * 6e4), onError: skip });
+    for await (const { adapter, ref, spans } of scanned) {
+      yield { session: { harness: adapter.harness, sessionId: ref.sessionId, cwd: ref.cwd, path: ref.path }, spans };
+    }
+  };
+}
+async function streamSessions(opts) {
+  await watchSource(sessionSource(opts), opts);
+}
+
+export {
+  watchSource,
+  streamSessions
+};

package/dist/chunk-K2KH2HHD.js

@@ -0,0 +1,228 @@
+import {
+  readRefSpans
+} from "./chunk-VFOLC4OX.js";
+import {
+  commandTextFromInput,
+  isSynthesizedSpan
+} from "./chunk-WF7PTDCZ.js";
+import {
+  ATTR,
+  SESSION_CWD_ATTR
+} from "./chunk-UQSAGXPH.js";
+import {
+  canonicalJson
+} from "./chunk-DU534HAX.js";
+
+// src/diff.ts
+import { createHash } from "crypto";
+import { epochMillis } from "@tangle-network/agent-eval/diagnosis";
+import { diffSteps, diffStepsFromSpans } from "@tangle-network/agent-eval/pipelines";
+import { OPENINFERENCE_SPAN_KIND, TOOL_NAME } from "@tangle-network/agent-eval/trace-attributes";
+var TEXT_LIMIT = 300;
+var WORKDIR_KEYS = ["workdir", "cwd"];
+var FILE_KEYS = ["file_path", "filePath", "notebook_path"];
+var RECORDED_CWD_KEYS = [SESSION_CWD_ATTR, ATTR.ENVIRONMENT_CWD];
+var PATCH_HEADER = /\*\*\* (Add|Update|Delete|Move to) File: ([^\n"\\]+)/g;
+var WORKTREE_PARENT = /^(.*?\/(?:_wt|\.worktrees|worktrees)\/[^/]+)\/./;
+var TEMP_DIR = /(?<![\w.~-])(?:\/private)?(?:\/tmp|\/var\/tmp|\/var\/folders\/[^/\s]+\/[^/\s]+\/T)\/[^/\s'"`;|&<>(){}]+/g;
+var HEX_RUN = /(?<![0-9A-Za-z])(?:[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}|[0-9A-F]{8}(?:-[0-9A-F]{4}){3}-[0-9A-F]{12}|[0-9a-f]{7,}|[0-9A-F]{7,})(?![0-9A-Za-z])/g;
+function hexId(run) {
+  return run.includes("-") || /[0-9]/.test(run) && /[a-f]/i.test(run) ? "<hex>" : run;
+}
+function stringOf(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return null;
+}
+function jsonObject(text) {
+  if (!text.trimStart().startsWith("{")) return void 0;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function patchedFiles(text) {
+  if (!text.includes("*** Begin Patch")) return null;
+  const headers = [...text.matchAll(PATCH_HEADER)].map((match) => `${match[1]} File: ${match[2].trim()}`);
+  return headers.length > 0 ? headers.join("; ") : null;
+}
+function callArgument(span) {
+  const raw = span.attributes["input.value"];
+  if (raw === void 0 || raw === null || raw === "") return { argument: null, workdir: null };
+  const text = typeof raw === "string" ? raw : canonicalJson(raw);
+  const input = jsonObject(text);
+  const workdir = input ? stringOf(input, WORKDIR_KEYS) : null;
+  const command = commandTextFromInput(text);
+  if (command !== void 0) return { argument: command, workdir };
+  if (!input) return { argument: patchedFiles(text) ?? text, workdir: null };
+  const file = stringOf(input, FILE_KEYS);
+  if (file) return { argument: file, workdir };
+  const patch = Object.values(input).find((value) => typeof value === "string" && value.includes("*** Begin Patch"));
+  const patched = patch === void 0 ? null : patchedFiles(patch);
+  if (patched) return { argument: patched, workdir };
+  const rest = Object.fromEntries(Object.entries(input).filter(([key]) => !WORKDIR_KEYS.includes(key)));
+  return { argument: canonicalJson(rest), workdir };
+}
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizer(cwds) {
+  const places = /* @__PURE__ */ new Map();
+  const add = (path, placeholder) => {
+    if (path.length < 2 || places.has(path)) return;
+    places.set(path, placeholder);
+    places.set(path.replace(/[^A-Za-z0-9]/g, "-"), placeholder);
+  };
+  for (const cwd of cwds) add(cwd, "<cwd>");
+  for (const cwd of cwds) {
+    const worktree = WORKTREE_PARENT.exec(cwd)?.[1];
+    if (worktree) add(worktree, "<worktree>");
+  }
+  const ordered = [...places.keys()].sort((x, y) => y.length - x.length);
+  const place = ordered.length === 0 ? null : new RegExp(`(?<![\\w.~-])(?:${ordered.map(escapeRegExp).join("|")})(?![\\w.@%+=,~-])`, "g");
+  return (text) => {
+    const placed = place ? text.replace(place, (match) => places.get(match)) : text;
+    return placed.replace(TEMP_DIR, "<tmp>").replace(HEX_RUN, hexId);
+  };
+}
+function isToolCall(span) {
+  return span.attributes[OPENINFERENCE_SPAN_KIND] === "TOOL" && !isSynthesizedSpan(span);
+}
+function toolName(span) {
+  const name = span.attributes[TOOL_NAME];
+  return typeof name === "string" && name.length > 0 ? name : span.name.replace(/^tool\./, "");
+}
+function oneLine(text, limit) {
+  const line = text.replace(/\s+/g, " ").trim();
+  return line.length > limit ? `${line.slice(0, limit)}\u2026` : line;
+}
+function containmentOrder(spans) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const span of spans) if (!byId.has(span.span_id)) byId.set(span.span_id, span);
+  const shapes = [...byId.values()].map((span) => ({
+    traceId: span.trace_id,
+    spanId: span.span_id,
+    parentSpanId: span.parent_span_id,
+    name: span.name,
+    kind: String(span.attributes[OPENINFERENCE_SPAN_KIND] ?? "UNKNOWN"),
+    startMs: epochMillis(span.start_time),
+    endMs: epochMillis(span.end_time),
+    status: span.status.code,
+    statusMessage: null,
+    toolName: null,
+    model: null,
+    inputDigest: null,
+    attributes: {}
+  }));
+  return diffStepsFromSpans(shapes).map((step) => byId.get(step.id));
+}
+async function readRunSide(ref) {
+  const spans = await readRefSpans(ref);
+  const traces = [...new Set(spans.map((span) => span.trace_id))];
+  if (traces.length !== 1) {
+    throw new Error(traces.length === 0 ? `${ref} holds no spans` : `${ref} holds ${traces.length} runs; pick one with ${ref}#<trace id>: ${traces.slice(0, 10).join(", ")}`);
+  }
+  const calls = containmentOrder(spans).filter(isToolCall).map((span) => ({ span, ...callArgument(span) }));
+  const cwds = /* @__PURE__ */ new Set();
+  const add = (value) => {
+    if (typeof value === "string" && value.startsWith("/")) cwds.add(value.replace(/\/+$/, ""));
+  };
+  for (const span of spans) for (const key of RECORDED_CWD_KEYS) add(span.attributes[key]);
+  if (cwds.size === 0) for (const span of spans) add(span.attributes[ATTR.CWD]);
+  for (const call of calls) add(call.workdir);
+  const normalize = normalizer([...cwds]);
+  const steps = calls.map(({ span, argument }) => {
+    const normalized = argument === null ? null : normalize(argument);
+    return {
+      id: span.span_id,
+      name: toolName(span),
+      kind: "TOOL",
+      fields: {
+        status: span.status.code,
+        args: normalized === null ? null : createHash("sha256").update(normalized).digest("hex").slice(0, 16)
+      },
+      text: normalized === null ? null : oneLine(normalized, TEXT_LIMIT)
+    };
+  });
+  return { ref, traceId: traces[0], spans: spans.length, cwds: [...cwds].sort(), steps };
+}
+function agreementCaveat(a, b) {
+  if (a.length === 0 && b.length === 0) return "neither run made a tool call";
+  const decided = (steps) => steps.some((step) => step.fields.status === "OK" || step.fields.status === "ERROR");
+  if (!decided(a) && !decided(b)) return "no tool call on either side records an OK or ERROR status (all UNSET)";
+  return void 0;
+}
+async function diffRuns(a, b) {
+  const [left, right] = await Promise.all([readRunSide(a), readRunSide(b)]);
+  const keyed = (side) => left.traceId === right.traceId ? [...side.steps] : side.steps.map((step) => ({ ...step, id: `${side.traceId}\0${step.id}` }));
+  const diff = diffSteps(keyed(left), keyed(right));
+  const caveat = diff.firstDivergence ? void 0 : agreementCaveat(left.steps, right.steps);
+  return { kind: "traces.run_diff", a: left, b: right, diff, ...caveat ? { caveat } : {} };
+}
+var SHOWN = 120;
+function shown(text, other) {
+  if (text === null) return "(input not recorded)";
+  if (other === null || other === text || text.length <= SHOWN) return oneLine(text, SHOWN);
+  let at = 0;
+  while (at < text.length && text[at] === other[at]) at += 1;
+  if (at < SHOWN - 20) return oneLine(text, SHOWN);
+  const start = at - 40;
+  return `\u2026${oneLine(text.slice(start), SHOWN)}`;
+}
+function stepLine(side, step, other, count) {
+  if (!step) return `  ${side}  (no more tool calls: it made ${count})`;
+  const status = step.fields.status === "OK" ? "" : ` [${String(step.fields.status)}]`;
+  return `  ${side}  ${step.name}${status}  ${shown(step.text, other?.text ?? null)}`;
+}
+function why(first) {
+  switch (first.kind) {
+    case "changed":
+      return first.differences.map((d) => d.field === "args" ? "argument" : d.field).join(", ");
+    case "replaced":
+      return "tool";
+    case "only-in-a":
+      return "a call only A makes";
+    case "only-in-b":
+      return "a call only B makes";
+    case "reordered":
+      return "order: each call is made elsewhere in the other run";
+  }
+}
+function sideLine(label, side) {
+  const cwd = side.cwds.length === 0 ? "" : ` \xB7 cwd ${side.cwds[0]}${side.cwds.length > 1 ? ` (+${side.cwds.length - 1})` : ""}`;
+  return `${label}  ${side.ref}  ${side.steps.length} tool call${side.steps.length === 1 ? "" : "s"}${cwd}`;
+}
+function renderRunDiff(report) {
+  const { a, b, diff } = report;
+  const lines = [sideLine("A", a), sideLine("B", b)];
+  const first = diff.firstDivergence;
+  if (!first) {
+    lines.push(report.caveat ? `no difference in the steps, but no agreement on outcome either: ${report.caveat}` : `no difference: all ${a.steps.length} tool calls agree on tool, status and argument`);
+    return `${lines.join("\n")}
+`;
+  }
+  const stepA = first.a === null ? void 0 : a.steps[first.a];
+  const stepB = first.b === null ? void 0 : b.steps[first.b];
+  const agreed = first.index === 0 ? "no step before it" : first.index === 1 ? "step 1 agrees" : `steps 1-${first.index} agree`;
+  lines.push(
+    `first difference at step ${first.index + 1} (${why(first)}); ${agreed}:`,
+    stepLine("A", stepA, stepB, a.steps.length),
+    stepLine("B", stepB, stepA, b.steps.length)
+  );
+  if (stepA && stepB && stepA.text === stepB.text && stepA.fields.args !== stepB.fields.args) {
+    lines.push(`  (the arguments differ after their first ${TEXT_LIMIT} characters)`);
+  }
+  const changed = diff.pairs.filter((pair) => pair.differences.length > 0).length;
+  lines.push(`overall: ${diff.pairs.length} paired (${changed} differ), ${diff.onlyInA.length} only in A, ${diff.onlyInB.length} only in B`);
+  return `${lines.join("\n")}
+`;
+}
+
+export {
+  diffRuns,
+  renderRunDiff
+};