@tangle-network/traces 0.23.1 → 1.0.1

package/dist/run-watch-RAOOAXOF.js

@@ -0,0 +1,649 @@
+import {
+  exportTraceEvidenceFile
+} from "./chunk-CG5QHQO4.js";
+import {
+  isSynthesizedSpan
+} from "./chunk-UQSAGXPH.js";
+import "./chunk-CQ6UYZG6.js";
+import "./chunk-RZL5GAWH.js";
+import "./chunk-DU534HAX.js";
+import {
+  ZERO_ROLL,
+  addSpend,
+  isFileRunContextDir,
+  mergeRolls,
+  readRunContextSnapshot
+} from "./chunk-M3W6TZHQ.js";
+
+// src/run-watch.ts
+import { stat } from "fs/promises";
+
+// src/run-view-format.ts
+var RULE = "\u2500".repeat(76);
+function int(n) {
+  return n.toLocaleString("en-US");
+}
+function ms(value) {
+  if (value === null) return "\u2014";
+  if (value < 1e3) return `${value}ms`;
+  if (value < 6e4) return `${(value / 1e3).toFixed(1)}s`;
+  const minutes = Math.floor(value / 6e4);
+  return `${minutes}m${String(Math.round(value % 6e4 / 1e3)).padStart(2, "0")}s`;
+}
+function usd(roll) {
+  if (roll.usdKnownRecords === 0) {
+    return roll.usdUnknownRecords === 0 ? "no spend recorded" : `cost unknown (${roll.usdUnknownRecords} unpriced)`;
+  }
+  const priced = zeroPricedCost(roll) ? `$${roll.usd.toFixed(4)} (zero across ${roll.usdKnownRecords} priced)` : `$${roll.usd.toFixed(4)}`;
+  return roll.usdUnknownRecords === 0 ? priced : `${priced} + ${roll.usdUnknownRecords} unpriced`;
+}
+function zeroPricedCost(roll) {
+  return roll.usdKnownRecords > 0 && roll.usd === 0 && roll.tokensIn + roll.tokensOut > 0;
+}
+function tokens(roll) {
+  return `in ${int(roll.tokensIn)} \xB7 out ${int(roll.tokensOut)}`;
+}
+var STATUS_MARK = {
+  pending: "\xB7",
+  acquiring: "\u25D0",
+  running: "\u25B6",
+  done: "\u2713",
+  failed: "\u2717",
+  cancelled: "\u2298"
+};
+function connectors(depth, lastAtDepth) {
+  if (depth === 0) return { head: "\u25CF ", detail: "    " };
+  let stem = "";
+  for (let level = 1; level < depth; level++) stem += lastAtDepth[level] ? "   " : "\u2502  ";
+  const isLast = lastAtDepth[depth] ?? true;
+  return { head: `${stem}${isLast ? "\u2514\u2500 " : "\u251C\u2500 "}`, detail: `${stem}${isLast ? "   " : "\u2502  "}    ` };
+}
+function forEachTreeNode(nodes, parentKey, selfKey, visit) {
+  const lastChildOf = /* @__PURE__ */ new Map();
+  for (const node of nodes) lastChildOf.set(parentKey(node), selfKey(node));
+  const lastAtDepth = [];
+  for (const node of nodes) {
+    lastAtDepth[node.depth] = lastChildOf.get(parentKey(node)) === selfKey(node);
+    lastAtDepth.length = node.depth + 1;
+    visit(node, lastAtDepth);
+  }
+}
+function wrap(text, indent) {
+  const width = Math.max(40, (process.stdout.columns ?? 100) - indent - 2);
+  const pad = " ".repeat(indent);
+  const out = [];
+  for (const paragraph of text.split("\n")) {
+    let line = "";
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      if (line.length > 0 && line.length + 1 + word.length > width) {
+        out.push(pad + line);
+        line = word;
+      } else line = line.length === 0 ? word : `${line} ${word}`;
+    }
+    out.push(pad + line);
+  }
+  return out;
+}
+
+// src/run-span-tree.ts
+import { readdir } from "fs/promises";
+import { join } from "path";
+import {
+  firstNumberAttr,
+  LLM_COST_ATTR_KEYS,
+  LLM_INPUT_TOKEN_ATTR_KEYS,
+  LLM_OUTPUT_TOKEN_ATTR_KEYS,
+  SPAN_KIND_ATTR_KEYS
+} from "@tangle-network/agent-eval/trace-attributes";
+var AGENT_NAME_ATTR_KEYS = ["agent.name", "inference.agent_name", "gen_ai.agent.name"];
+var SERVICE_NAME_ATTR_KEYS = ["service.name", "tangle.runtime"];
+var AGENT_OPERATIONS = /* @__PURE__ */ new Set(["invoke_agent", "invoke_workflow"]);
+var OPERATION_ATTR_KEY = "gen_ai.operation.name";
+function firstStringAttr(attributes, keys) {
+  for (const key of keys) {
+    const value = attributes[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return null;
+}
+var EMPTY_SPAN_RUN_SNAPSHOT = {
+  present: false,
+  nodes: [],
+  maxDepth: 0,
+  traceIds: [],
+  spanCount: 0,
+  startMs: null,
+  endMs: null,
+  llmSpansWithoutTokens: 0,
+  llmSpansWithoutCost: 0,
+  orphanSpans: 0,
+  readError: null
+};
+function spanKind(span) {
+  return firstStringAttr(span.attributes, SPAN_KIND_ATTR_KEYS);
+}
+function isNodeBoundary(span, enclosingNodeId, enclosingAgent) {
+  if (span.parent_span_id === null || enclosingNodeId === null) return true;
+  if (spanKind(span) === "AGENT") return true;
+  if (AGENT_OPERATIONS.has(String(span.attributes[OPERATION_ATTR_KEY] ?? ""))) return true;
+  const agent = firstStringAttr(span.attributes, AGENT_NAME_ATTR_KEYS);
+  return agent !== null && enclosingAgent !== null && agent !== enclosingAgent;
+}
+function spanSpend(span) {
+  const cost = firstNumberAttr(span.attributes, LLM_COST_ATTR_KEYS);
+  return {
+    iterations: 0,
+    tokens: {
+      input: firstNumberAttr(span.attributes, LLM_INPUT_TOKEN_ATTR_KEYS) ?? 0,
+      output: firstNumberAttr(span.attributes, LLM_OUTPUT_TOKEN_ATTR_KEYS) ?? 0
+    },
+    usd: cost ?? 0,
+    ...cost === null ? { usdKnown: false } : {},
+    ms: 0
+  };
+}
+function epoch(value) {
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function buildSpanRunTree(spans, source) {
+  if (spans.length === 0) return { ...EMPTY_SPAN_RUN_SNAPSHOT, source };
+  const byId = /* @__PURE__ */ new Map();
+  for (const span of spans) byId.set(spanKey(span), span);
+  const childrenOf = /* @__PURE__ */ new Map();
+  let orphanSpans = 0;
+  for (const span of spans) {
+    const parentKey = span.parent_span_id === null ? null : byId.has(`${span.trace_id}\0${span.parent_span_id}`) ? `${span.trace_id}\0${span.parent_span_id}` : null;
+    if (span.parent_span_id !== null && parentKey === null) orphanSpans += 1;
+    const bucket = childrenOf.get(parentKey);
+    if (bucket) bucket.push(span);
+    else childrenOf.set(parentKey, [span]);
+  }
+  for (const bucket of childrenOf.values()) {
+    bucket.sort((a, b) => epoch(a.start_time) - epoch(b.start_time) || a.span_id.localeCompare(b.span_id));
+  }
+  const building = /* @__PURE__ */ new Map();
+  const order = [];
+  let llmSpansWithoutTokens = 0;
+  let llmSpansWithoutCost = 0;
+  const walk = (span, enclosingNodeId, enclosingAgent, depth) => {
+    const key = spanKey(span);
+    const agent = firstStringAttr(span.attributes, AGENT_NAME_ATTR_KEYS) ?? enclosingAgent;
+    let nodeId = enclosingNodeId;
+    let nodeAgent = enclosingAgent;
+    let childDepth = depth;
+    if (isNodeBoundary(span, enclosingNodeId, enclosingAgent)) {
+      const node = {
+        span,
+        parentNodeId: enclosingNodeId,
+        depth,
+        agent,
+        driver: ZERO_ROLL,
+        toolCalls: 0,
+        startMs: epoch(span.start_time),
+        endMs: epoch(span.end_time),
+        errors: [],
+        childNodeIds: []
+      };
+      building.set(key, node);
+      order.push(key);
+      if (enclosingNodeId !== null) building.get(enclosingNodeId)?.childNodeIds.push(key);
+      nodeId = key;
+      nodeAgent = agent;
+      childDepth = depth + 1;
+    }
+    const host = nodeId === null ? void 0 : building.get(nodeId);
+    if (host !== void 0) {
+      const kind = spanKind(span);
+      if (kind === "LLM") {
+        host.driver = addSpend(host.driver, spanSpend(span));
+        if (firstNumberAttr(span.attributes, LLM_INPUT_TOKEN_ATTR_KEYS) === null && firstNumberAttr(span.attributes, LLM_OUTPUT_TOKEN_ATTR_KEYS) === null) {
+          llmSpansWithoutTokens += 1;
+        }
+        if (firstNumberAttr(span.attributes, LLM_COST_ATTR_KEYS) === null) llmSpansWithoutCost += 1;
+      } else if (kind === "TOOL" && !isSynthesizedSpan(span.attributes)) {
+        host.toolCalls += 1;
+      }
+      host.startMs = Math.min(host.startMs, epoch(span.start_time));
+      host.endMs = Math.max(host.endMs, epoch(span.end_time));
+      if (span.status.code === "ERROR") {
+        host.errors.push(`${span.name}: ${span.status.message ?? "ERROR"}`);
+      }
+    }
+    for (const child of childrenOf.get(key) ?? []) walk(child, nodeId, nodeAgent, childDepth);
+  };
+  for (const root of childrenOf.get(null) ?? []) walk(root, null, null, 0);
+  const subtotal = /* @__PURE__ */ new Map();
+  const subtotalOf = (key) => {
+    const cached = subtotal.get(key);
+    if (cached !== void 0) return cached;
+    const node = building.get(key);
+    if (node === void 0) return ZERO_ROLL;
+    subtotal.set(key, ZERO_ROLL);
+    let total = node.driver;
+    for (const child of node.childNodeIds) total = mergeRolls(total, subtotalOf(child));
+    subtotal.set(key, total);
+    return total;
+  };
+  const nodes = order.map((key) => {
+    const node = building.get(key);
+    let children = ZERO_ROLL;
+    for (const child of node.childNodeIds) children = mergeRolls(children, subtotalOf(child));
+    return {
+      traceId: node.span.trace_id,
+      spanId: node.span.span_id,
+      parentNodeId: node.parentNodeId === null ? null : building.get(node.parentNodeId).span.span_id,
+      label: node.agent ?? node.span.name,
+      depth: node.depth,
+      role: node.childNodeIds.length > 0 ? "driver" : "leaf",
+      status: node.errors.length > 0 || node.span.status.code === "ERROR" ? "failed" : node.span.status.code === "UNSET" ? "running" : "done",
+      runtime: firstStringAttr(node.span.attributes, SERVICE_NAME_ATTR_KEYS),
+      driver: node.driver,
+      children,
+      toolCalls: node.toolCalls,
+      startMs: node.startMs,
+      endMs: node.endMs,
+      wallMs: Math.max(0, node.endMs - node.startMs),
+      errors: node.errors
+    };
+  });
+  return {
+    source,
+    present: true,
+    nodes,
+    maxDepth: nodes.reduce((max, n) => Math.max(max, n.depth), 0),
+    traceIds: [...new Set(spans.map((s) => s.trace_id))],
+    spanCount: spans.length,
+    startMs: nodes.reduce((min, n) => min === null ? n.startMs : Math.min(min, n.startMs), null),
+    endMs: nodes.reduce((max, n) => max === null ? n.endMs : Math.max(max, n.endMs), null),
+    llmSpansWithoutTokens,
+    llmSpansWithoutCost,
+    orphanSpans,
+    readError: null
+  };
+}
+function spanKey(span) {
+  return `${span.trace_id}\0${span.span_id}`;
+}
+async function readSpanRunSnapshot(path) {
+  try {
+    const exported = await exportTraceEvidenceFile(path);
+    return buildSpanRunTree(exported.spans, path);
+  } catch (error) {
+    return {
+      ...EMPTY_SPAN_RUN_SNAPSHOT,
+      source: path,
+      readError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function spanRunTotals(snapshot) {
+  let driver = ZERO_ROLL;
+  let leaves = ZERO_ROLL;
+  for (const node of snapshot.nodes) {
+    if (node.role === "driver") driver = mergeRolls(driver, node.driver);
+    else leaves = mergeRolls(leaves, node.driver);
+  }
+  return { driver, leaves };
+}
+function renderSpanRunSnapshot(snapshot) {
+  const lines = [];
+  lines.push(`spans ${snapshot.source}`);
+  if (snapshot.readError !== null) {
+    lines.push(`  unreadable: ${snapshot.readError}`);
+    return lines.join("\n");
+  }
+  if (!snapshot.present || snapshot.nodes.length === 0) {
+    lines.push("  no spans yet \u2014 the emitter has written nothing this view can place");
+    return lines.join("\n");
+  }
+  const totals = spanRunTotals(snapshot);
+  lines.push(
+    `  ${snapshot.nodes.length} node(s) \xB7 depth ${snapshot.maxDepth} \xB7 ${int(snapshot.spanCount)} span(s) \xB7 ${snapshot.traceIds.length} trace(s) \xB7 elapsed ${ms(snapshot.endMs === null || snapshot.startMs === null ? null : snapshot.endMs - snapshot.startMs)}`
+  );
+  const delegating = snapshot.nodes.some((node) => node.role === "driver");
+  lines.push(`  driver inference  ${tokens(totals.driver)} \xB7 ${usd(totals.driver)}`);
+  lines.push(`  leaf inference    ${tokens(totals.leaves)} \xB7 ${usd(totals.leaves)}`);
+  if (!delegating) {
+    lines.push("  (no delegation in these spans: every turn belongs to one agent, so the driver half is empty)");
+  }
+  lines.push("");
+  forEachTreeNode(
+    snapshot.nodes,
+    (n) => n.parentNodeId,
+    (n) => n.spanId,
+    (node, lastAtDepth) => {
+      const { head: prefix, detail } = connectors(node.depth, lastAtDepth);
+      const mark = node.status === "failed" ? "\u2717" : node.status === "running" ? "\u25B6" : "\u2713";
+      lines.push(
+        [
+          `${prefix}${mark} ${node.label}`,
+          `[${node.status}]`,
+          node.role,
+          node.runtime ?? "no-runtime",
+          "budget not in spans",
+          `wall ${ms(node.wallMs)}`
+        ].join("  ")
+      );
+      lines.push(
+        `${detail}driver    ${node.driver.records} turn(s) \xB7 ${tokens(node.driver)} \xB7 ${usd(node.driver)} \xB7 ${node.toolCalls} tool call(s)`
+      );
+      if (node.role === "driver") {
+        lines.push(
+          `${detail}children  ${node.children.records} turn(s) \xB7 ${tokens(node.children)} \xB7 ${usd(node.children)}`
+        );
+      }
+      for (const error of node.errors.slice(0, 3)) lines.push(`${detail}error ${error}`);
+    }
+  );
+  const problems = [];
+  if (snapshot.llmSpansWithoutCost > 0) {
+    problems.push(
+      `${snapshot.llmSpansWithoutCost} of the LLM span(s) carry no cost attribute \u2014 that spend is UNKNOWN, not $0 (this emitter writes tokens without a price)`
+    );
+  }
+  if (snapshot.llmSpansWithoutTokens > 0) {
+    problems.push(`${snapshot.llmSpansWithoutTokens} LLM span(s) carry no token count`);
+  }
+  if (snapshot.orphanSpans > 0) {
+    problems.push(
+      `${snapshot.orphanSpans} span(s) name a parent_span_id absent from this file \u2014 re-rooted, not dropped`
+    );
+  }
+  problems.push(
+    "spans carry no authored budget in either the OpenInference or the GenAI vocabulary; point this at a run directory with a spawn journal to see ceilings and settlement"
+  );
+  lines.push("");
+  for (const problem of problems) lines.push(`  ! ${problem}`);
+  return lines.join("\n");
+}
+var SPAN_FILE_PATTERN = /\.(?:otlp|spans|traces|openinference)\.(?:jsonl|ndjson)$|^traces?\.jsonl$|^spans\.jsonl$/i;
+async function findSpanSourceFiles(dir) {
+  const found = [];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const child = join(dir, entry.name);
+    if (entry.isFile()) {
+      if (SPAN_FILE_PATTERN.test(entry.name)) found.push(child);
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+    const nested = await readdir(child, { withFileTypes: true }).catch(() => []);
+    for (const inner of nested) {
+      if (inner.isFile() && SPAN_FILE_PATTERN.test(inner.name)) found.push(join(child, inner.name));
+    }
+  }
+  return found.sort();
+}
+
+// src/supervisor-run-watch.ts
+import { readdir as readdir2 } from "fs/promises";
+import { join as join2 } from "path";
+function budget(node) {
+  const parts = [`${int(node.budget.maxIterations)}it`, `${int(node.budget.maxTokens)}tok`];
+  if (node.budget.maxUsd !== void 0) parts.push(`$${node.budget.maxUsd.toFixed(2)}`);
+  if (node.budget.deadlineMs !== void 0) parts.push(ms(node.budget.deadlineMs));
+  return parts.join("/");
+}
+function budgetUse(node, spent) {
+  const parts = [];
+  if (node.budget.maxIterations > 0 && spent.iterations > 0) {
+    parts.push(`${Math.round(spent.iterations / node.budget.maxIterations * 100)}% it`);
+  }
+  const used = spent.tokensIn + spent.tokensOut;
+  if (node.budget.maxTokens > 0 && used > 0) {
+    parts.push(`${Math.round(used / node.budget.maxTokens * 100)}% tok`);
+  }
+  return parts.length === 0 ? "" : ` \xB7 ${parts.join(", ")} of budget`;
+}
+function renderNode(node, lastAtDepth, lines) {
+  const mark = STATUS_MARK[node.status] ?? "?";
+  const { head: prefix, detail } = connectors(node.depth, lastAtDepth);
+  const head = [
+    `${prefix}${mark} ${node.label}`,
+    `[${node.status}]`,
+    node.role,
+    node.runtime ?? "no-runtime",
+    `budget ${budget(node)}`
+  ];
+  if (node.wallMs !== null) head.push(`wall ${ms(node.wallMs)}`);
+  lines.push(head.join("  "));
+  if (node.driver.records > 0 || node.role === "supervisor") {
+    lines.push(
+      `${detail}driver    ${node.driver.records} turn(s) \xB7 ${tokens(node.driver)} \xB7 ${usd(node.driver)}` + budgetUse(node, node.driver)
+    );
+  }
+  if (node.children.records > 0 || node.role === "supervisor") {
+    lines.push(
+      `${detail}children  ${node.children.records} settled \xB7 ${tokens(node.children)} \xB7 ${usd(node.children)}`
+    );
+  }
+  if (node.settled.records > 0) {
+    lines.push(
+      `${detail}settled   ${node.settled.iterations}it \xB7 ${tokens(node.settled)} \xB7 ${usd(node.settled)}` + budgetUse(node, node.settled)
+    );
+  }
+  if (node.cancelReason !== null) lines.push(`${detail}cancelled: ${node.cancelReason}`);
+  if (node.outRef !== null) lines.push(`${detail}out ${node.outRef}`);
+}
+function renderQuestion(q, lines) {
+  const mark = q.blocking ? "BLOCKING" : q.urgency ?? "question";
+  lines.push(`  \u26A0 ${mark} from ${q.from ?? "unknown"}${q.status === null ? "" : ` [${q.status}]`}`);
+  for (const line of wrap(q.question, 4)) lines.push(line);
+  if (q.reason !== null) for (const line of wrap(`why: ${q.reason}`, 4)) lines.push(line);
+}
+function renderRunContextSnapshot(snapshot) {
+  const lines = [];
+  if (!snapshot.present) {
+    lines.push(`run ${snapshot.runDir}`);
+    lines.push("  no spawn-journal.jsonl yet \u2014 the run has not begun writing");
+    return lines.join("\n");
+  }
+  const totals = runTotals(snapshot);
+  lines.push(`run ${snapshot.runId ?? snapshot.runDir}`);
+  lines.push(
+    `  ${snapshot.nodes.length} node(s) \xB7 depth ${snapshot.maxDepth} \xB7 elapsed ${ms(elapsed(snapshot))}${snapshot.terminal ? "" : " \xB7 live"}`
+  );
+  lines.push(`  driver total    ${tokens(totals.driver)} \xB7 ${usd(totals.driver)}`);
+  lines.push(`  worker total    ${tokens(totals.workers)} \xB7 ${usd(totals.workers)}`);
+  lines.push("");
+  if (snapshot.nodes.length === 0) lines.push("  (no node spawned yet)");
+  forEachTreeNode(
+    snapshot.nodes,
+    (n) => n.parent,
+    (n) => n.id,
+    (node, lastAtDepth) => renderNode(node, lastAtDepth, lines)
+  );
+  if (snapshot.questions.length > 0) {
+    lines.push("");
+    for (const q of snapshot.questions) renderQuestion(q, lines);
+  }
+  if (snapshot.steers.length > 0) {
+    lines.push("");
+    for (const steer of snapshot.steers) {
+      lines.push(`  \u2192 steer ${steer.messageId ?? "(no id)"} to ${steer.toWorker ?? "(no target)"}`);
+      for (const line of wrap(steer.instruction, 4)) lines.push(line);
+    }
+  }
+  const problems = [];
+  if (snapshot.invalidJournalRows > 0) problems.push(`${snapshot.invalidJournalRows} unreadable journal row(s)`);
+  if (snapshot.retiredWaitRows > 0) {
+    problems.push(`${snapshot.retiredWaitRows} wait-state journal row(s) from an older Runtime left out of the tree`);
+  }
+  if (snapshot.invalidCoordinationRows > 0) {
+    problems.push(`${snapshot.invalidCoordinationRows} unreadable coordination row(s)`);
+  }
+  if (snapshot.treeError !== null) problems.push(snapshot.treeError);
+  if (snapshot.partialTail) problems.push("an artifact ends mid-line \u2014 the writer is still appending");
+  if (zeroPricedCost(totals.driver) || zeroPricedCost(totals.workers)) {
+    problems.push(
+      "spend recorded $0 with tokens spent: usdKnown was never set false, so this reads as FREE rather than unmetered. A harness-billed brain (a CLI on a subscription) looks exactly like this."
+    );
+  }
+  const unsettled = snapshot.nodes.filter(
+    (node) => node.status !== "done" && node.status !== "failed" && node.status !== "cancelled"
+  );
+  if (snapshot.terminal && unsettled.length > 0) {
+    problems.push(
+      `${unsettled.length} node(s) have no journaled settlement (${unsettled.map((n) => n.label).join(", ")}) \u2014 a driver reports its outcome through result.json, not the spawn journal`
+    );
+  }
+  if (problems.length > 0) {
+    lines.push("");
+    for (const problem of problems) lines.push(`  ! ${problem}`);
+  }
+  if (snapshot.result !== null) {
+    lines.push("");
+    lines.push(
+      `RESULT ${snapshot.result.kind ?? "unknown-kind"}${snapshot.result.reason === null ? "" : ` \xB7 ${snapshot.result.reason}`}`
+    );
+    if (snapshot.result.errorMessage !== null) {
+      lines.push(`  driver error (${snapshot.result.errorName ?? "Error"}):`);
+      for (const line of wrap(snapshot.result.errorMessage, 4)) lines.push(line);
+    }
+  }
+  return lines.join("\n");
+}
+function runTotals(snapshot) {
+  let driver = ZERO_ROLL;
+  let workers = ZERO_ROLL;
+  for (const node of snapshot.nodes) {
+    driver = mergeRolls(driver, node.driver);
+    if (node.role === "worker") workers = mergeRolls(workers, node.settled);
+  }
+  return { driver, workers };
+}
+function elapsed(snapshot) {
+  if (snapshot.begunAt === null) return null;
+  const end = snapshot.terminal ? snapshot.lastEventAt ?? Date.now() : Date.now();
+  return Math.max(0, end - snapshot.begunAt);
+}
+async function resolveRunContextDir(dir) {
+  if (await isFileRunContextDir(dir)) return dir;
+  const entries = await readdir2(dir, { withFileTypes: true }).catch(() => null);
+  if (entries === null) throw new Error(`cannot read ${dir}`);
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = join2(dir, entry.name);
+    if (await isFileRunContextDir(child)) candidates.push(child);
+  }
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length === 0) {
+    throw new Error(
+      `no spawn-journal.jsonl in ${dir} or any immediate subdirectory \u2014 point at a directory written by agent-runtime createFileRunContext()`
+    );
+  }
+  throw new Error(
+    `${candidates.length} run directories under ${dir}; name one:
+  ${candidates.join("\n  ")}`
+  );
+}
+
+// src/run-watch.ts
+async function resolveRunWatchTarget(target) {
+  const info = await stat(target).catch(() => null);
+  if (info === null) throw new Error(`cannot read ${target}`);
+  if (info.isFile()) return { runDir: null, spanFiles: [target], requested: target };
+  const spanFiles = await findSpanSourceFiles(target);
+  if (await isFileRunContextDir(target)) return { runDir: target, spanFiles, requested: target };
+  const nested = await resolveRunContextDir(target).catch(() => null);
+  if (nested !== null) {
+    const nestedSpans = await findSpanSourceFiles(nested);
+    return {
+      runDir: nested,
+      spanFiles: [.../* @__PURE__ */ new Set([...spanFiles, ...nestedSpans])].sort(),
+      requested: target
+    };
+  }
+  if (spanFiles.length > 0) return { runDir: null, spanFiles, requested: target };
+  throw new Error(
+    `nothing to watch in ${target} \u2014 found neither spawn-journal.jsonl (agent-runtime createFileRunContext, at this level or one below) nor an OTLP span file (*.otlp.jsonl / *.spans.jsonl / *.traces.jsonl / *.openinference.jsonl)`
+  );
+}
+async function readRunWatchSnapshot(target) {
+  const journal = target.runDir === null ? null : await readRunContextSnapshot(target.runDir);
+  const spans = await Promise.all(target.spanFiles.map((file) => readSpanRunSnapshot(file)));
+  return {
+    target,
+    journal,
+    spans,
+    // A span file alone never declares itself finished — an emitter can always
+    // append one more span — so only the journal's `result.json` ends a watch.
+    terminal: journal !== null && journal.terminal
+  };
+}
+function sourceHeader(snapshot) {
+  const lines = ["sources"];
+  if (snapshot.journal !== null) {
+    lines.push(
+      `  journal  ${snapshot.target.runDir}/spawn-journal.jsonl  \u2192 authored budget, settled spend, settlement status (authoritative)`
+    );
+  }
+  for (const span of snapshot.spans) {
+    lines.push(
+      `  spans    ${span.source}  \u2192 tree shape and per-turn detail${span.readError === null ? "" : " (unreadable)"}`
+    );
+  }
+  if (snapshot.journal === null) {
+    lines.push("  (no spawn journal here: budget and settlement are UNAVAILABLE, not zero)");
+  }
+  if (snapshot.spans.length === 0) {
+    lines.push("  (no OTLP span file here: per-turn shape is UNAVAILABLE, not empty)");
+  }
+  return lines;
+}
+function renderRunWatchSnapshot(snapshot) {
+  const blocks = [sourceHeader(snapshot).join("\n")];
+  if (snapshot.journal !== null) blocks.push(renderRunContextSnapshot(snapshot.journal));
+  for (const span of snapshot.spans) blocks.push(renderSpanRunSnapshot(span));
+  return blocks.join("\n\n");
+}
+async function watchRunTarget(target, opts = {}) {
+  const write = opts.write ?? ((text) => process.stdout.write(text));
+  const intervalMs = opts.intervalMs ?? 2e3;
+  let previous = "";
+  for (; ; ) {
+    const snapshot = await readRunWatchSnapshot(target);
+    const rendered = renderRunWatchSnapshot(snapshot);
+    if (opts.once) {
+      write(`${rendered}
+`);
+      return snapshot;
+    }
+    if (rendered !== previous) {
+      write(`
+${RULE}
+${(/* @__PURE__ */ new Date()).toISOString()}
+${rendered}
+`);
+      previous = rendered;
+    }
+    if (snapshot.terminal && opts.follow !== true) return snapshot;
+    if (aborted(opts.signal)) return snapshot;
+    await sleep(intervalMs, opts.signal);
+    if (aborted(opts.signal)) return await readRunWatchSnapshot(target);
+  }
+}
+function aborted(signal) {
+  return signal !== void 0 && signal.aborted;
+}
+function sleep(msDelay, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, msDelay);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+export {
+  readRunWatchSnapshot,
+  renderRunWatchSnapshot,
+  resolveRunWatchTarget,
+  watchRunTarget
+};

package/dist/supervisor-report-RMPLLBGZ.js

@@ -0,0 +1,29 @@
+// src/supervisor-report.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+async function writeSupervisorReport(runDir, out) {
+  const { analyzeSupervisorRun, findSupervisorRunDirs, isRuntimeSupervisorRunDir, renderSupervisorRollupMarkdown, renderSupervisorRunMarkdown, rollupSupervisorRuns } = await import("@tangle-network/agent-eval/supervisor-run");
+  const { fileRunContextSupervisorRunReader } = await import("./supervisor-run-context-WO6VOTGV.js");
+  const single = await isRuntimeSupervisorRunDir(runDir);
+  const runDirs = single ? [runDir] : await findSupervisorRunDirs(runDir);
+  if (runDirs.length === 0) {
+    throw new Error(
+      `no supervisor run found at ${runDir} \u2014 expected a Runtime run containing spawn-journal.jsonl, observer.jsonl, or failure.json, or a parent directory containing such runs`
+    );
+  }
+  const reports = await Promise.all(
+    runDirs.map((dir) => analyzeSupervisorRun(fileRunContextSupervisorRunReader(dir)))
+  );
+  const markdown = single ? renderSupervisorRunMarkdown(reports[0]) : renderSupervisorRollupMarkdown(rollupSupervisorRuns(reports), `Supervisor rollup \u2014 ${runDir}`);
+  if (out) {
+    const path = resolve(out, "report.md");
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, markdown, "utf8");
+    console.log(`supervisor report \u2192 ${path}  (${runDirs.length === 1 ? "1 run" : `${runDirs.length} runs`})`);
+  } else {
+    console.log(markdown);
+  }
+}
+export {
+  writeSupervisorReport
+};