@tangle-network/traces 0.23.1 → 1.0.1

package/dist/chunk-VFOLC4OX.js

@@ -0,0 +1,407 @@
+import {
+  detectEvidenceFormat,
+  exportTraceEvidenceFile
+} from "./chunk-CG5QHQO4.js";
+import {
+  isCodexExecRecord,
+  listAdapters,
+  parseSession,
+  readsStoreRoots,
+  resolveAdapter
+} from "./chunk-7USMM4MA.js";
+import {
+  isOtlpJsonFile,
+  isStandardOtlpRow,
+  readJsonl,
+  readOtlpInput
+} from "./chunk-CQ6UYZG6.js";
+
+// src/refs.ts
+import { readFile, stat } from "fs/promises";
+import { homedir } from "os";
+import { join, resolve, sep } from "path";
+import { CODEX_HOME_RULE, STORES, codexHomes, isCodexHome } from "@tangle-network/harness-sessions";
+import { ATTR } from "@tangle-network/agent-trace-contract";
+var MIN_REF_CHARS = 8;
+var RefError = class extends Error {
+  code;
+  candidates;
+  constructor(message, code, candidates = []) {
+    super(message);
+    this.name = "RefError";
+    this.code = code;
+    this.candidates = candidates;
+  }
+};
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function statOf(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return null;
+    throw error;
+  }
+}
+async function isDirectory(path) {
+  return (await statOf(path))?.isDirectory() ?? false;
+}
+async function isFile(path) {
+  return (await statOf(path))?.isFile() ?? false;
+}
+function ownHome() {
+  return process.env.HOME || homedir();
+}
+var HEAD_ROWS = 20;
+var MAX_WHOLE_JSON_BYTES = 256 * 1024 * 1024;
+var CODEX_ROLLOUT_TYPES = /* @__PURE__ */ new Set(["session_meta", "response_item", "event_msg", "turn_context"]);
+var STORE_PATHS = [
+  { harness: "claude-code", root: STORES["claude-code.projects-jsonl"].root },
+  { harness: "pi", root: STORES["pi.session-jsonl"].root },
+  { harness: "kimi", root: STORES["kimi.session-dir"].root },
+  { harness: "factory", root: STORES["factory.session-jsonl"].root }
+];
+function harnessOfStorePath(path) {
+  const absolute = resolve(path);
+  for (const { harness, root } of STORE_PATHS) {
+    if (absolute.includes(`${sep}${root.split("/").join(sep)}${sep}`)) return harness;
+  }
+  const segments = absolute.split(sep);
+  for (let i = 1; i < segments.length - 1; i += 1) {
+    if (!CODEX_HOME_RULE.sessionDirs.includes(segments[i + 1])) continue;
+    if (isCodexHome(segments.slice(0, i + 1).join(sep))) return "codex";
+  }
+  return void 0;
+}
+async function headRows(path) {
+  const rows = [];
+  let unparsed = 0;
+  for await (const row of readJsonl(path, { mode: "recover", onCorruption: () => {
+    unparsed += 1;
+  } })) {
+    rows.push(row);
+    if (rows.length >= HEAD_ROWS) return rows;
+    if (unparsed > HEAD_ROWS && rows.length === 0) break;
+  }
+  if (rows.length > 0 && unparsed === 0) {
+    const only = rows.length === 1 ? rows[0] : void 0;
+    if (Array.isArray(only)) return only;
+    if (isObject(only) && Array.isArray(only.events)) return only.events;
+    return rows;
+  }
+  const info = await stat(path);
+  if (info.size > MAX_WHOLE_JSON_BYTES) return rows;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return rows;
+  }
+  if (Array.isArray(parsed)) return parsed;
+  if (isObject(parsed) && Array.isArray(parsed.events)) return parsed.events;
+  return [parsed];
+}
+function isClaudeRecord(row) {
+  return isObject(row) && (typeof row.sessionId === "string" || typeof row.session_id === "string") && typeof row.type === "string" && ("message" in row || "uuid" in row || "subtype" in row);
+}
+async function sniffTraceFile(path) {
+  const stored = harnessOfStorePath(path);
+  if (stored) return { kind: "session", harness: stored };
+  if (await isOtlpJsonFile(path)) return { kind: "spans", reader: "otlp" };
+  const rows = await headRows(path);
+  if (rows.some(isCodexExecRecord)) return { kind: "session", harness: "codex-exec" };
+  if (rows.length > 0 && rows.every((row) => isObject(row) && typeof row.trace_id === "string" && typeof row.span_id === "string")) {
+    return { kind: "spans", reader: "otlp" };
+  }
+  if (rows.length > 0 && rows.every(isStandardOtlpRow)) return { kind: "spans", reader: "otlp" };
+  if (!rows.some((row) => isObject(row) && typeof row.span_id === "string")) {
+    if (rows.some(isClaudeRecord)) return { kind: "session", harness: "claude-code" };
+    if (rows.some((row) => isObject(row) && CODEX_ROLLOUT_TYPES.has(String(row.type)) && isObject(row.payload))) {
+      return { kind: "session", harness: "codex" };
+    }
+    const first = rows[0];
+    if (isObject(first) && first.type === "session" && typeof first.id === "string") return { kind: "session", harness: "pi" };
+    if (rows.some((row) => isObject(row) && row.type === "session_start")) return { kind: "session", harness: "factory" };
+  }
+  const evidence = detectEvidenceFormat(rows);
+  if (evidence === "sandbox-events") {
+    for await (const row of readJsonl(path, { mode: "recover", onCorruption: () => {
+    } })) {
+      if (isCodexExecRecord(row)) return { kind: "session", harness: "codex-exec" };
+    }
+  }
+  if (evidence) return { kind: "spans", reader: evidence };
+  return { kind: "spans", reader: "otlp" };
+}
+function adapterFor(harness) {
+  const adapter = resolveAdapter(harness);
+  if (!adapter) {
+    throw new RefError(`unknown harness "${harness}"; known: ${listAdapters().map((a) => a.harness).join(", ")}`, "usage");
+  }
+  return adapter;
+}
+async function fileRef(path, ref, selector, options) {
+  if (options.format) return { kind: "spans", ref, path, reader: options.format, ...selector ? { selector } : {} };
+  const sniffed = options.harness ? { kind: "session", harness: options.harness } : await sniffTraceFile(path);
+  if (sniffed.kind === "spans") return { kind: "spans", ref, path, reader: sniffed.reader, ...selector ? { selector } : {} };
+  if (selector) throw new RefError(`${ref}: a #selector picks a run from a span file; ${path} is a ${sniffed.harness} session`, "usage");
+  const adapter = adapterFor(sniffed.harness);
+  const info = await stat(path);
+  return {
+    kind: "session",
+    ref,
+    adapter,
+    session: { harness: adapter.harness, sessionId: ref, path, cwd: null, mtimeMs: info.mtimeMs }
+  };
+}
+var HOME_STORES = [
+  STORES["claude-code.projects-jsonl"].root,
+  STORES["opencode.sqlite"].root,
+  STORES["pi.session-jsonl"].root,
+  STORES["kimi.session-dir"].root,
+  STORES["factory.session-jsonl"].root
+];
+async function isStoreRoot(dir) {
+  for (const root of HOME_STORES) if (await isDirectory(join(dir, root))) return true;
+  for (const home of await codexHomes(dir)) {
+    for (const sessions of CODEX_HOME_RULE.sessionDirs) if (await isDirectory(join(home, sessions))) return true;
+  }
+  return false;
+}
+var BUNDLE_SPAN_FILES = ["spans.otlp.jsonl", join("derived", "trace.otlp.jsonl")];
+async function directoryRef(path, ref) {
+  if (await isFile(join(path, "manifest.json"))) {
+    for (const file of BUNDLE_SPAN_FILES) {
+      if (await isFile(join(path, file))) return { kind: "spans", ref, path: join(path, file), reader: "otlp" };
+    }
+    throw new RefError(`${ref} has a manifest.json but no spans.otlp.jsonl; it is not a traces bundle`, "unreadable");
+  }
+  const { findSupervisorRunDirs, isRuntimeSupervisorRunDir } = await import("@tangle-network/agent-eval/supervisor-run");
+  if (await isRuntimeSupervisorRunDir(path)) return { kind: "run-dir", ref, path };
+  if (await isStoreRoot(path)) return { kind: "store-root", ref, path: resolve(path) };
+  if ((await findSupervisorRunDirs(path)).length > 0) return { kind: "run-dir", ref, path };
+  return { kind: "spans", ref, path, reader: "otlp" };
+}
+function looksLikePath(ref) {
+  return ref.includes("/") || ref.startsWith(".") || ref.startsWith("~") || /\.(?:jsonl|ndjson|json|db)$/iu.test(ref);
+}
+function candidate({ adapter, session }) {
+  return { harness: adapter.harness, sessionId: session.sessionId, path: session.path };
+}
+var COMPLETE_ID_CHARS = 20;
+async function lookupSession(query, options, storeRoot) {
+  const short = query.length < MIN_REF_CHARS;
+  const home = storeRoot ?? ownHome();
+  const selected = options.harness ? [adapterFor(options.harness)] : listAdapters();
+  const adapters = storeRoot === void 0 ? selected : selected.filter(readsStoreRoots);
+  const failures = /* @__PURE__ */ new Map();
+  const listed = /* @__PURE__ */ new Map();
+  const sessionsOf = (adapter, exact) => {
+    if (readsStoreRoots(adapter) && exact) return adapter.locateIn(home, { nativeSessionId: query });
+    let all = listed.get(adapter);
+    if (!all) {
+      all = readsStoreRoots(adapter) ? adapter.locateIn(home) : adapter.locate();
+      listed.set(adapter, all);
+    }
+    return all;
+  };
+  const search = async (exact) => {
+    const found2 = /* @__PURE__ */ new Map();
+    for (const adapter of adapters) {
+      let sessions;
+      try {
+        sessions = await sessionsOf(adapter, exact);
+      } catch (error) {
+        failures.set(adapter.harness, errorText(error));
+        continue;
+      }
+      for (const session of sessions) {
+        const id = session.sessionId;
+        if (id === query || !exact && (id.startsWith(query) || id.endsWith(query))) {
+          found2.set(`${adapter.harness}\0${session.path}\0${id}`, { adapter, session });
+        }
+      }
+    }
+    return [...found2.values()].sort((a, b) => b.session.mtimeMs - a.session.mtimeMs);
+  };
+  let found = query.length >= COMPLETE_ID_CHARS || short ? await search(true) : [];
+  if (found.length === 0 && short) {
+    throw new RefError(
+      `"${query}" is not a file, a directory or a session id, and a session id prefix or suffix needs at least ${MIN_REF_CHARS} characters`,
+      "usage"
+    );
+  }
+  if (found.length === 0) {
+    const matched = await search(false);
+    const exact = matched.filter(({ session }) => session.sessionId === query);
+    found = exact.length > 0 ? exact : matched;
+  }
+  if (found.length === 1) return { kind: "session", ref: query, adapter: found[0].adapter, session: found[0].session };
+  const where = storeRoot === void 0 ? "" : ` under ${storeRoot}`;
+  if (found.length === 0) {
+    const unread = failures.size > 0 ? `; could not read ${[...failures].map(([harness, reason]) => `${harness}: ${reason}`).join("; ")}` : "";
+    throw new RefError(
+      `no session id is, starts with or ends with "${query}"${where} (${adapters.map((a) => a.harness).join(", ")})${unread}; \`traces list\` shows ids`,
+      "unreadable"
+    );
+  }
+  const shown = found.slice(0, 5).map((item) => `${item.adapter.harness} ${item.session.sessionId}`);
+  const more = found.length > shown.length ? ` and ${found.length - shown.length} more` : "";
+  throw new RefError(
+    `"${query}" matches ${found.length} sessions${where} (${shown.join(", ")}${more}); pass more of the id`,
+    "ambiguous",
+    found.map(candidate)
+  );
+}
+function shortestRefs(ids) {
+  const unique = [...new Set(ids)];
+  const reverse = (text) => [...text].reverse().join("");
+  const forward = [...unique].sort();
+  const backward = unique.map(reverse).sort();
+  const starting = (sorted, prefix) => {
+    let low = 0;
+    let high = sorted.length;
+    while (low < high) {
+      const mid = low + high >> 1;
+      if (sorted[mid] < prefix) low = mid + 1;
+      else high = mid;
+    }
+    const found = [];
+    for (let i = low; i < sorted.length && found.length < 2 && sorted[i].startsWith(prefix); i += 1) found.push(sorted[i]);
+    return found;
+  };
+  const alone = (id, form) => {
+    const matches = /* @__PURE__ */ new Set([...starting(forward, form), ...starting(backward, reverse(form)).map(reverse)]);
+    return matches.size === 1 && matches.has(id);
+  };
+  const shortest = /* @__PURE__ */ new Map();
+  for (const id of unique) {
+    let best = id;
+    for (let length = MIN_REF_CHARS; length < id.length; length += 1) {
+      const prefix = id.slice(0, length);
+      const suffix = id.slice(-length);
+      if (alone(id, prefix)) {
+        best = prefix;
+        break;
+      }
+      if (alone(id, suffix)) {
+        best = suffix;
+        break;
+      }
+    }
+    shortest.set(id, best);
+  }
+  return shortest;
+}
+async function splitSelector(ref) {
+  const hash = ref.lastIndexOf("#");
+  if (hash <= 0 || hash === ref.length - 1 || await statOf(ref) !== null) return { path: ref };
+  const path = ref.slice(0, hash);
+  return await statOf(path) === null ? { path: ref } : { path, selector: ref.slice(hash + 1) };
+}
+async function pathRef(ref, options) {
+  const { path, selector } = await splitSelector(ref);
+  const info = await statOf(path);
+  if (info === null) {
+    if (looksLikePath(ref)) throw new RefError(`no such file or directory: ${ref}`, "unreadable");
+    return void 0;
+  }
+  if (info.isDirectory()) {
+    if (selector) throw new RefError(`${ref}: a #selector picks a run from a span file, not a directory`, "usage");
+    return directoryRef(path, ref);
+  }
+  if (!info.isFile()) throw new RefError(`${ref} is neither a file nor a directory`, "unreadable");
+  return fileRef(path, ref, selector, options);
+}
+async function resolveRefs(refs, options = {}) {
+  const byPath = await Promise.all(refs.map((ref) => pathRef(ref, options)));
+  const roots = byPath.filter((ref) => ref?.kind === "store-root");
+  if (roots.length > 1) {
+    throw new RefError(`name one store root per command, not ${roots.length}: ${roots.map((root) => root.ref).join(", ")}`, "usage");
+  }
+  const resolved = [];
+  for (const [index, ref] of refs.entries()) {
+    resolved.push(byPath[index] ?? await lookupSession(ref, options, roots[0]?.path));
+  }
+  return resolved;
+}
+function branchSpans(spans, branch) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const span of spans) byId.set(span.span_id, span);
+  const children = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    if (!span.parent_span_id) continue;
+    const list = children.get(span.parent_span_id);
+    if (list) list.push(span);
+    else children.set(span.parent_span_id, [span]);
+  }
+  const matched = spans.filter(
+    (span) => span.attributes[ATTR.branchId] === branch || span.attributes[ATTR.branchArm] === branch
+  );
+  const matchedIds = new Set(matched.map((span) => span.span_id));
+  const hasMatchedAncestor = (span) => {
+    let current = span;
+    while (current.parent_span_id) {
+      const parent = byId.get(current.parent_span_id);
+      if (!parent) return false;
+      if (matchedIds.has(parent.span_id)) return true;
+      current = parent;
+    }
+    return false;
+  };
+  const roots = matched.filter((span) => !hasMatchedAncestor(span));
+  if (roots.length > 1) {
+    const named = roots.map((span) => `${span.span_id} (${ATTR.branchId}=${JSON.stringify(span.attributes[ATTR.branchId] ?? null)})`).join(", ");
+    throw new Error(
+      `"${branch}" matches ${roots.length} separate subtrees, not one arm: ${named} \u2014 sibling arms can share a branch id; select by span id, or narrow the input to one arm first`
+    );
+  }
+  const selected = /* @__PURE__ */ new Set();
+  const stack = [...matched];
+  while (stack.length > 0) {
+    const span = stack.pop();
+    if (selected.has(span)) continue;
+    selected.add(span);
+    stack.push(...children.get(span.span_id) ?? []);
+  }
+  return spans.filter((span) => selected.has(span));
+}
+function selectSpans(spans, selector, path) {
+  if (selector.startsWith("branch=")) {
+    const branch = selector.slice("branch=".length);
+    const picked2 = branchSpans(spans, branch);
+    if (picked2.length === 0) throw new RefError(`${path} holds no span with ${ATTR.branchId} or ${ATTR.branchArm} "${branch}"`, "unreadable");
+    return picked2;
+  }
+  const picked = spans.filter((span) => span.trace_id === selector);
+  if (picked.length === 0) throw new RefError(`${path} holds no run with trace id ${selector}`, "unreadable");
+  return picked;
+}
+async function readRefSpans(ref, options = {}) {
+  const resolved = (await resolveRefs([ref], options))[0];
+  switch (resolved.kind) {
+    case "session":
+      return parseSession(resolved.adapter, resolved.session);
+    case "run-dir":
+      return [...(await readOtlpInput(resolved.path)).spans];
+    case "store-root":
+      throw new RefError(`${ref} is a store root, which holds many sessions; name one session in it`, "usage");
+    case "spans": {
+      const spans = resolved.reader === "otlp" ? [...(await readOtlpInput(resolved.path)).spans] : (await exportTraceEvidenceFile(resolved.path, { format: resolved.reader })).spans;
+      return resolved.selector ? selectSpans(spans, resolved.selector, resolved.path) : spans;
+    }
+  }
+}
+
+export {
+  RefError,
+  shortestRefs,
+  resolveRefs,
+  selectSpans,
+  readRefSpans
+};