@tangle-network/agent-eval 0.27.2 → 0.29.0

package/dist/traces.js

@@ -1,17 +1,29 @@
 import {
   DEFAULT_REDACTION_RULES,
+  DEFAULT_TRACE_ANALYST_BUDGETS,
   FileSystemTraceStore,
   InMemoryTraceStore,
   OTEL_AGENT_EVAL_SCOPE,
+  OtlpFileTraceStore,
   REDACTION_VERSION,
   ReplayCache,
   ReplayCacheMissError,
+  SpanNotFoundError,
+  TRACE_ANALYST_ACTOR_DESCRIPTION,
+  TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,
+  TRACE_ANALYST_SUBAGENT_DESCRIPTION,
+  TRACE_ANALYST_TRUNCATION_MARKER_PREFIX,
+  TraceFileMissingError,
+  TraceNotFoundError,
+  analyzeTraces,
+  buildTraceAnalystTools,
   createReplayFetch,
   exportRunAsOtlp,
   iterateRawCalls,
   redactString,
-  redactValue
-} from "./chunk-4U4BKCXK.js";
+  redactValue,
+  traceAnalystFunctionGroup
+} from "./chunk-UW4NOOZI.js";
 import {
   aggregateLlm,
   argHash,
@@ -48,992 +60,9 @@ import {
   llmSpanFromProvider
 } from "./chunk-TVVP3ZZQ.js";
 import "./chunk-VSMTAMNK.js";
-import {
-  NotFoundError
-} from "./chunk-NG236HPC.js";
+import "./chunk-NG236HPC.js";
 import "./chunk-PZ5AY32C.js";
 
-// src/trace-analyst/analyst.ts
-import { AxJSRuntime, agent } from "@ax-llm/ax";
-
-// src/trace-analyst/prompts.ts
-var TRACE_ANALYST_ACTOR_DESCRIPTION = `You answer questions about an OTLP-shaped JSONL trace dataset using the trace tools provided in the \`traces\` namespace.
-
-DISCOVERY \u2192 NARROW \u2192 DEEP-READ protocol \u2014 follow exactly:
-
-1. ALWAYS call \`traces.getDatasetOverview({})\` FIRST without a regex_pattern. The result tells you total_traces, raw_jsonl_bytes, services, agents, models, and sample_trace_ids (real ids \u2014 never fabricate one).
-
-2. Use raw_jsonl_bytes to gauge how expensive raw scans will be. \`filters.regex_pattern\` is the one scan-heavy filter on getDatasetOverview / queryTraces / countTraces \u2014 narrow with indexed fields (has_errors, model_names, service_names, agent_names, time bounds) BEFORE adding a regex on a large dataset.
-
-3. To list more traces than the sample, call \`traces.queryTraces({ filters?, limit, offset? })\`. Each summary carries raw_jsonl_bytes \u2014 use it to choose between viewTrace and searchTrace BEFORE calling either.
-
-4. Per-trace inspection:
-   - SMALL trace (raw_jsonl_bytes well under 150_000): call \`traces.viewTrace({ trace_id })\`. Returns all spans. Per-attribute payloads are head-capped at ~4KB; large \`input.value\` / \`output.value\` / \`llm.input_messages\` will show a \`[trace-analyst truncated: N bytes]\` marker.
-   - LARGE trace (raw_jsonl_bytes near or above 150_000, or you saw an \`oversized\` response): use \`traces.searchTrace({ trace_id, regex_pattern })\` to get bounded SpanMatchRecords (span metadata + matched text + surrounding context). Then call \`traces.viewSpans({ trace_id, span_ids: [...] })\` for surgical reads (~16KB cap, 4\xD7 higher than discovery), or \`traces.searchSpan({ trace_id, span_id, regex_pattern })\` for one large span. Stays bounded regardless of trace size.
-   - Useful regex patterns: \`STATUS_CODE_ERROR\` (failures), tool names like \`grep\` or \`view_trace\`, error strings like \`MaxTurnsExceeded\`, model names, attribute keys.
-
-5. ONLY call viewTrace / viewSpans / searchTrace / searchSpan with trace/span ids you have already seen in sample_trace_ids, a queryTraces page, or a previous search result. Never invent ids.
-
-5a. **Result-shape contract** \u2014 searchTrace and searchSpan return \`{ trace_id, hits, total_matches, has_more }\`. Iterate \`result.hits\` (NOT result.matches). Each hit has \`{ span_id, span_name, span_kind, attribute_path, matched_text, context_before, context_after, match_offset }\`. viewTrace returns \`{ trace_id, spans }\` (or \`oversized\`). viewSpans returns \`{ trace_id, spans, missing_span_ids, truncated_attribute_count }\`. Never assume a field name \u2014 log the result shape first if unsure.
-
-6. If viewTrace returns an \`oversized\` summary instead of \`spans\`, DO NOT retry the same call. Read the summary's top_span_names, span_count, span_response_bytes_max, error_span_count to plan a follow-up: switch to searchTrace (or searchSpan for one large span), then viewSpans on a smaller, surgical span_ids set.
-
-7. If searchTrace or searchSpan returns has_more=true, REFINE the regex to be more specific rather than blindly raising max_matches.
-
-8. If a tool errors (invalid regex, range error), STOP and reconsider \u2014 don't retry with a guessed id or argument. Use the discovery tools above to recover.
-
-9. If a ~4KB-truncated payload from viewTrace / searchTrace matters for your answer, first try viewSpans on that span id (~16KB cap). If a 16KB-truncated payload from viewSpans still matters, narrow further with searchSpan against a more specific regex rather than asking for the full payload again.
-
-10. If maxDepth > 0 and the question splits into independent semantic branches, delegate well-defined subtasks to subagents using \`await llmQuery(...)\`. Pass narrow context and a focused query. Examples:
-
-    const reviews = await llmQuery([
-      { query: 'Drill into trace abc123 \u2014 what tool calls preceded the failure?', context: { trace_id: 'abc123' } },
-      { query: 'Drill into trace def456 \u2014 same failure mode?', context: { trace_id: 'def456' } },
-    ]);
-
-OBSERVABILITY rules:
-- Each non-final actor turn must emit at least one \`console.log(...)\` for evidence. Up to 3 logs per turn is fine when correlating multiple data sources (e.g. one log for findings list, one for source-file content, one for derived analysis).
-- Do NOT combine \`console.log\` with \`final(...)\` or \`askClarification(...)\` in the same turn \u2014 finish gathering data first, then call final on its own turn.
-- Reuse runtime variables across turns; don't recompute.
-- When done, call \`await final(answer)\` with the fully-formed report. The responder rewrites the answer into output fields; if you only pass a vague summary string the responder has nothing concrete to format.
-
-CRITICAL \u2014 \`final()\` payload contract for evidence-grounded analysis tasks:
-- Pass a STRUCTURED object as the second arg with the actual data the responder needs to format the answer. Do NOT pass abstract instructions; pass evidence.
-- Example for per-item verdict tasks:
-  \`\`\`js
-  await final("Format the per-item verdict report from the evidence below.", {
-    findings: [
-      { id: 'sub-1-finding-1', claim: '...', verdict: 'TRUE-POSITIVE', evidence: 'lines 42-45 of contracts/X.sol show ...' },
-      ...all items
-    ],
-    systemic_summary: '3 sentences I wrote based on the evidence above'
-  });
-  \`\`\`
-- Calling \`final("answer", {})\` with no evidence is a failure mode \u2014 the responder will hallucinate or echo back the field names. Always include the gathered data.
-- Premature final after a single viewSpans call is INSUFFICIENT for per-finding analysis tasks. Read the requested attributes (e.g. \`spans[i].attributes['redteam.finding.title']\`), and for each one perform the requested cross-reference (e.g. read the source SPAN's \`attributes['source.content']\`).
-
-OUTPUT contract \u2014 your final answer must include:
-- A clear prose conclusion answering the user's question.
-- Trace ids and span ids cited as evidence for each claim.
-- Failure modes named in the user's domain language, with frequency and concrete examples.
-
-Do NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.`;
-var TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-actor-v5-2026-05-06";
-var TRACE_ANALYST_SUBAGENT_DESCRIPTION = `You are a trace-analyst subagent. Your parent has delegated a focused trace-inspection question. Use the same DISCOVERY \u2192 NARROW \u2192 DEEP-READ protocol but stay tightly scoped: do exactly what was asked, return a concise compact answer, do NOT spawn further subagents unless the parent's question is genuinely multi-branch.
-
-Cite trace ids and span ids for every claim. Do NOT invent ids.`;
-
-// src/trace-analyst/store-otlp.ts
-import { readFile, stat } from "fs/promises";
-
-// src/trace-analyst/store.ts
-function compileSearchRegex(pattern) {
-  let source = pattern;
-  let flags = "m";
-  if (source.startsWith("(?i)")) {
-    source = source.slice(4);
-    flags += "i";
-  }
-  return new RegExp(source, flags);
-}
-function truncateForBudget(value, byteCap) {
-  const original = Buffer.byteLength(value, "utf8");
-  if (original <= byteCap) return value;
-  const ratio = byteCap / original;
-  let cut = Math.max(0, Math.floor(value.length * ratio));
-  while (cut > 0 && Buffer.byteLength(value.slice(0, cut), "utf8") > byteCap) {
-    cut -= 1;
-  }
-  return `${value.slice(0, cut)}
-[trace-analyst truncated: original ${original} bytes]`;
-}
-
-// src/trace-analyst/types.ts
-var DEFAULT_TRACE_ANALYST_BUDGETS = {
-  perCallByteCeiling: 15e4,
-  perAttributeViewBudget: 4096,
-  perAttributeSpanBudget: 16384,
-  perMatchTextBudget: 1024
-};
-var TRACE_ANALYST_TRUNCATION_MARKER_PREFIX = "[trace-analyst truncated:";
-
-// src/trace-analyst/store-otlp.ts
-var OtlpFileTraceStore = class {
-  path;
-  perAttributeViewBudget;
-  perAttributeSpanBudget;
-  perCallByteCeiling;
-  perMatchTextBudget;
-  indexPromise;
-  /** Cached UTF-8 buffer of the file. We pin it once because every
-   *  read needs slice access and re-reading on each call balloons the
-   *  syscall count. */
-  bufferPromise;
-  constructor(opts) {
-    this.path = opts.path;
-    this.perAttributeViewBudget = opts.perAttributeViewBudget ?? DEFAULT_TRACE_ANALYST_BUDGETS.perAttributeViewBudget;
-    this.perAttributeSpanBudget = opts.perAttributeSpanBudget ?? DEFAULT_TRACE_ANALYST_BUDGETS.perAttributeSpanBudget;
-    this.perCallByteCeiling = opts.perCallByteCeiling ?? DEFAULT_TRACE_ANALYST_BUDGETS.perCallByteCeiling;
-    this.perMatchTextBudget = opts.perMatchTextBudget ?? DEFAULT_TRACE_ANALYST_BUDGETS.perMatchTextBudget;
-  }
-  // ─── Public API ────────────────────────────────────────────────────
-  async getOverview(filters) {
-    const idx = await this.index();
-    const matched = await this.matchedTraces(idx, filters);
-    const services = /* @__PURE__ */ new Set();
-    const agents = /* @__PURE__ */ new Set();
-    const models = /* @__PURE__ */ new Set();
-    const tools = /* @__PURE__ */ new Set();
-    let rawBytes = 0;
-    let earliest = null;
-    let latest = null;
-    let errorTraceCount = 0;
-    let errorSpanCount = 0;
-    for (const t of matched) {
-      if (t.service_name) services.add(t.service_name);
-      if (t.agent_name) agents.add(t.agent_name);
-      for (const m of t.models) models.add(m);
-      for (const tn of t.tools) tools.add(tn);
-      rawBytes += t.raw_jsonl_bytes;
-      if (!earliest || t.start_time < earliest) earliest = t.start_time;
-      if (!latest || t.end_time > latest) latest = t.end_time;
-      if (t.has_errors) {
-        errorTraceCount += 1;
-        for (const s of t.spans) if (s.status === "ERROR") errorSpanCount += 1;
-      }
-    }
-    const sample_trace_ids = matched.slice(0, 20).map((t) => t.trace_id);
-    return {
-      total_traces: matched.length,
-      raw_jsonl_bytes: rawBytes,
-      services: [...services].sort(),
-      agents: [...agents].sort(),
-      models: [...models].sort(),
-      tool_names: [...tools].sort(),
-      sample_trace_ids,
-      errors: { trace_count: errorTraceCount, span_count: errorSpanCount },
-      time_range: earliest && latest ? { earliest, latest } : null
-    };
-  }
-  async queryTraces(opts) {
-    if (!Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > 200) {
-      throw new RangeError(`queryTraces.limit must be 1..200, got ${opts.limit}`);
-    }
-    const offset = opts.offset ?? 0;
-    if (!Number.isInteger(offset) || offset < 0) {
-      throw new RangeError(`queryTraces.offset must be >=0, got ${offset}`);
-    }
-    const idx = await this.index();
-    const matched = await this.matchedTraces(idx, opts.filters);
-    const slice = matched.slice(offset, offset + opts.limit);
-    return {
-      traces: slice.map((t) => this.toSummary(t)),
-      total: matched.length,
-      has_more: offset + slice.length < matched.length
-    };
-  }
-  async countTraces(filters) {
-    const idx = await this.index();
-    const matched = await this.matchedTraces(idx, filters);
-    return matched.length;
-  }
-  async viewTrace(opts) {
-    const idx = await this.index();
-    const trace = idx.byTrace.get(opts.trace_id);
-    if (!trace) {
-      throw new TraceNotFoundError(opts.trace_id);
-    }
-    const cap = opts.per_attribute_byte_cap ?? this.perAttributeViewBudget;
-    const buf = await this.buffer();
-    const spans = [];
-    let runningBytes = 0;
-    let span_response_bytes_max = 0;
-    for (const s of trace.spans) {
-      const projected = await this.projectSpan(buf, trace.trace_id, s, cap);
-      const bytes = Buffer.byteLength(JSON.stringify(projected), "utf8");
-      span_response_bytes_max = Math.max(span_response_bytes_max, bytes);
-      runningBytes += bytes;
-      if (runningBytes > this.perCallByteCeiling) {
-        return {
-          trace_id: trace.trace_id,
-          oversized: this.buildOversizedSummary(trace, span_response_bytes_max)
-        };
-      }
-      spans.push(projected);
-    }
-    return { trace_id: trace.trace_id, spans };
-  }
-  async viewSpans(opts) {
-    const idx = await this.index();
-    const trace = idx.byTrace.get(opts.trace_id);
-    if (!trace) throw new TraceNotFoundError(opts.trace_id);
-    if (opts.span_ids.length === 0) {
-      return {
-        trace_id: trace.trace_id,
-        spans: [],
-        missing_span_ids: [],
-        truncated_attribute_count: 0
-      };
-    }
-    if (opts.span_ids.length > 100) {
-      throw new RangeError(`viewSpans.span_ids cap is 100, got ${opts.span_ids.length}`);
-    }
-    const cap = opts.per_attribute_byte_cap ?? this.perAttributeSpanBudget;
-    const wantSet = new Set(opts.span_ids);
-    const found = trace.spans.filter((s) => wantSet.has(s.span_id));
-    const missing = opts.span_ids.filter((id) => !found.some((f2) => f2.span_id === id));
-    const buf = await this.buffer();
-    const spans = [];
-    let truncated = 0;
-    let runningBytes = 0;
-    for (const s of found) {
-      const before = truncationCounter(this);
-      const projected = await this.projectSpan(buf, trace.trace_id, s, cap);
-      truncated += before.delta();
-      const bytes = Buffer.byteLength(JSON.stringify(projected), "utf8");
-      runningBytes += bytes;
-      if (runningBytes > this.perCallByteCeiling) {
-        break;
-      }
-      spans.push(projected);
-    }
-    return {
-      trace_id: trace.trace_id,
-      spans,
-      missing_span_ids: missing,
-      truncated_attribute_count: truncated
-    };
-  }
-  async searchTrace(opts) {
-    const max_matches = opts.max_matches ?? 50;
-    if (!Number.isInteger(max_matches) || max_matches < 1 || max_matches > 500) {
-      throw new RangeError(`searchTrace.max_matches must be 1..500, got ${max_matches}`);
-    }
-    const idx = await this.index();
-    const trace = idx.byTrace.get(opts.trace_id);
-    if (!trace) throw new TraceNotFoundError(opts.trace_id);
-    const re = compileSearchRegex(opts.regex_pattern);
-    const buf = await this.buffer();
-    const hits = [];
-    let total = 0;
-    let capped = false;
-    for (const s of trace.spans) {
-      const remaining = max_matches - hits.length;
-      const localHits = await this.scanSpanForMatches(
-        buf,
-        trace.trace_id,
-        s,
-        re,
-        this.perMatchTextBudget,
-        remaining
-      );
-      total += localHits.total;
-      for (const h of localHits.records) {
-        if (hits.length >= max_matches) break;
-        hits.push(h);
-      }
-      if (hits.length >= max_matches) {
-        capped = true;
-        total = Math.max(total, hits.length + 1);
-        break;
-      }
-    }
-    return {
-      trace_id: trace.trace_id,
-      hits,
-      total_matches: total,
-      has_more: capped || total > hits.length
-    };
-  }
-  async searchSpan(opts) {
-    const max_matches = opts.max_matches ?? 50;
-    if (!Number.isInteger(max_matches) || max_matches < 1 || max_matches > 500) {
-      throw new RangeError(`searchSpan.max_matches must be 1..500, got ${max_matches}`);
-    }
-    const idx = await this.index();
-    const trace = idx.byTrace.get(opts.trace_id);
-    if (!trace) throw new TraceNotFoundError(opts.trace_id);
-    const span = trace.spans.find((s) => s.span_id === opts.span_id);
-    if (!span) {
-      throw new SpanNotFoundError(opts.trace_id, opts.span_id);
-    }
-    const re = compileSearchRegex(opts.regex_pattern);
-    const buf = await this.buffer();
-    const localHits = await this.scanSpanForMatches(
-      buf,
-      trace.trace_id,
-      span,
-      re,
-      this.perMatchTextBudget,
-      max_matches
-    );
-    return {
-      trace_id: trace.trace_id,
-      span_id: span.span_id,
-      hits: localHits.records,
-      total_matches: localHits.total,
-      has_more: localHits.total > localHits.records.length
-    };
-  }
-  // ─── Index building ────────────────────────────────────────────────
-  /** Force the index to materialise. Useful to amortise startup cost
-   *  before the first agent call. */
-  async ensureIndexed() {
-    await this.index();
-  }
-  async buffer() {
-    if (!this.bufferPromise) {
-      this.bufferPromise = readFile(this.path);
-    }
-    return this.bufferPromise;
-  }
-  async index() {
-    if (!this.indexPromise) {
-      this.indexPromise = this.buildIndex();
-    }
-    return this.indexPromise;
-  }
-  async buildIndex() {
-    let buf;
-    try {
-      buf = await this.buffer();
-    } catch (err) {
-      const stats = await stat(this.path).catch(() => null);
-      if (!stats) {
-        throw new TraceFileMissingError(this.path);
-      }
-      throw err;
-    }
-    const byTrace = /* @__PURE__ */ new Map();
-    let cursor = 0;
-    while (cursor < buf.length) {
-      const newlineIndex = buf.indexOf(10, cursor);
-      const lineEnd = newlineIndex === -1 ? buf.length : newlineIndex;
-      const lineLength = lineEnd - cursor;
-      if (lineLength === 0) {
-        cursor = lineEnd + 1;
-        continue;
-      }
-      const lineSlice = buf.subarray(cursor, lineEnd).toString("utf8");
-      const lineOffset = cursor;
-      cursor = lineEnd + 1;
-      let parsed;
-      try {
-        parsed = JSON.parse(lineSlice);
-      } catch {
-        continue;
-      }
-      if (!parsed || typeof parsed !== "object") continue;
-      const span = readOtlpSpan(parsed);
-      if (!span) continue;
-      let entry = byTrace.get(span.trace_id);
-      if (!entry) {
-        entry = {
-          trace_id: span.trace_id,
-          service_name: span.service_name,
-          agent_name: span.agent_name,
-          span_count: 0,
-          has_errors: false,
-          start_time: span.start_time,
-          end_time: span.end_time,
-          duration_ms: 0,
-          raw_jsonl_bytes: 0,
-          models: /* @__PURE__ */ new Set(),
-          tools: /* @__PURE__ */ new Set(),
-          spans: []
-        };
-        byTrace.set(span.trace_id, entry);
-      } else {
-        if (!entry.service_name && span.service_name) entry.service_name = span.service_name;
-        if (!entry.agent_name && span.agent_name) entry.agent_name = span.agent_name;
-      }
-      const indexEntry = {
-        span_id: span.span_id,
-        parent_span_id: span.parent_span_id,
-        name: span.name,
-        kind: span.kind,
-        start_time: span.start_time,
-        end_time: span.end_time,
-        duration_ms: span.duration_ms,
-        status: span.status,
-        status_message: span.status_message,
-        service_name: span.service_name,
-        agent_name: span.agent_name,
-        model_name: span.model_name,
-        tool_name: span.tool_name,
-        line_byte_offset: lineOffset,
-        line_byte_length: lineLength
-      };
-      entry.spans.push(indexEntry);
-      entry.span_count += 1;
-      entry.raw_jsonl_bytes += lineLength + 1;
-      if (span.status === "ERROR") entry.has_errors = true;
-      if (span.start_time < entry.start_time) entry.start_time = span.start_time;
-      if (span.end_time > entry.end_time) entry.end_time = span.end_time;
-      if (span.model_name) entry.models.add(span.model_name);
-      if (span.tool_name) entry.tools.add(span.tool_name);
-    }
-    let totalRawBytes = 0;
-    for (const t of byTrace.values()) {
-      totalRawBytes += t.raw_jsonl_bytes;
-      t.spans.sort(
-        (a, b) => a.start_time.localeCompare(b.start_time) || a.line_byte_offset - b.line_byte_offset
-      );
-      t.duration_ms = Math.max(0, new Date(t.end_time).getTime() - new Date(t.start_time).getTime());
-    }
-    const sortedTraceIds = [...byTrace.keys()].sort();
-    return { byTrace, totalRawBytes, sortedTraceIds };
-  }
-  // ─── Filter pipeline ───────────────────────────────────────────────
-  async matchedTraces(idx, filters) {
-    const traces = idx.sortedTraceIds.map((id) => idx.byTrace.get(id)).filter(isPresent);
-    if (!filters) return traces;
-    const indexedFiltered = traces.filter((t) => {
-      if (filters.has_errors !== void 0 && t.has_errors !== filters.has_errors) return false;
-      if (filters.service_names && filters.service_names.length > 0) {
-        if (!t.service_name || !filters.service_names.includes(t.service_name)) return false;
-      }
-      if (filters.agent_names && filters.agent_names.length > 0) {
-        if (!t.agent_name || !filters.agent_names.includes(t.agent_name)) return false;
-      }
-      if (filters.model_names && filters.model_names.length > 0) {
-        if (![...t.models].some((m) => filters.model_names.includes(m))) return false;
-      }
-      if (filters.tool_names && filters.tool_names.length > 0) {
-        if (![...t.tools].some((tn) => filters.tool_names.includes(tn))) return false;
-      }
-      if (filters.start_time_after && t.start_time < filters.start_time_after) return false;
-      if (filters.start_time_before && t.start_time > filters.start_time_before) return false;
-      return true;
-    });
-    if (!filters.regex_pattern) return indexedFiltered;
-    const re = compileSearchRegex(filters.regex_pattern);
-    const buf = await this.buffer();
-    const out = [];
-    for (const t of indexedFiltered) {
-      let matched = false;
-      for (const s of t.spans) {
-        const slice = buf.subarray(s.line_byte_offset, s.line_byte_offset + s.line_byte_length);
-        if (re.test(slice.toString("utf8"))) {
-          matched = true;
-          break;
-        }
-      }
-      if (matched) out.push(t);
-    }
-    return out;
-  }
-  toSummary(t) {
-    return {
-      trace_id: t.trace_id,
-      service_name: t.service_name,
-      agent_name: t.agent_name,
-      span_count: t.span_count,
-      has_errors: t.has_errors,
-      start_time: t.start_time,
-      end_time: t.end_time,
-      duration_ms: t.duration_ms,
-      raw_jsonl_bytes: t.raw_jsonl_bytes,
-      models: [...t.models].sort(),
-      tools: [...t.tools].sort()
-    };
-  }
-  // ─── Span projection (lazy attribute reads) ────────────────────────
-  async projectSpan(buf, trace_id, s, perAttrCap) {
-    const slice = buf.subarray(s.line_byte_offset, s.line_byte_offset + s.line_byte_length).toString("utf8");
-    let raw = {};
-    try {
-      const parsed = JSON.parse(slice);
-      if (parsed && typeof parsed === "object") raw = parsed;
-    } catch {
-    }
-    const attrs = extractAttributes(raw);
-    const projected = {};
-    for (const [k, v] of Object.entries(attrs)) {
-      if (typeof v === "string") {
-        const trunc = truncateForBudget(v, perAttrCap);
-        if (trunc !== v) trackTruncation(this);
-        projected[k] = trunc;
-      } else if (Array.isArray(v) || v && typeof v === "object") {
-        const json = JSON.stringify(v);
-        const trunc = truncateForBudget(json, perAttrCap);
-        if (trunc !== json) {
-          trackTruncation(this);
-          projected[k] = trunc;
-        } else {
-          projected[k] = v;
-        }
-      } else {
-        projected[k] = v;
-      }
-    }
-    return {
-      trace_id,
-      span_id: s.span_id,
-      parent_span_id: s.parent_span_id,
-      name: s.name,
-      kind: s.kind,
-      start_time: s.start_time,
-      end_time: s.end_time,
-      duration_ms: s.duration_ms,
-      status: s.status,
-      status_message: s.status_message,
-      service_name: s.service_name,
-      agent_name: s.agent_name,
-      model_name: s.model_name,
-      tool_name: s.tool_name,
-      attributes: projected
-    };
-  }
-  buildOversizedSummary(t, span_response_bytes_max) {
-    const counts = /* @__PURE__ */ new Map();
-    let errorCount = 0;
-    for (const s of t.spans) {
-      counts.set(s.name, (counts.get(s.name) ?? 0) + 1);
-      if (s.status === "ERROR") errorCount += 1;
-    }
-    const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 20);
-    return {
-      span_count: t.span_count,
-      top_span_names: top,
-      span_response_bytes_max,
-      error_span_count: errorCount
-    };
-  }
-  async scanSpanForMatches(buf, trace_id, s, re, textBudget, recordCap) {
-    const slice = buf.subarray(s.line_byte_offset, s.line_byte_offset + s.line_byte_length).toString("utf8");
-    const records = [];
-    const globalRe = new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`);
-    let total = 0;
-    let hasMore = false;
-    let m;
-    while ((m = globalRe.exec(slice)) !== null) {
-      total += 1;
-      if (m.index === globalRe.lastIndex) globalRe.lastIndex += 1;
-      if (records.length >= recordCap) {
-        hasMore = true;
-        break;
-      }
-      const before = slice.slice(Math.max(0, m.index - textBudget / 2), m.index);
-      const after = slice.slice(
-        m.index + m[0].length,
-        m.index + m[0].length + Math.floor(textBudget / 2)
-      );
-      records.push({
-        trace_id,
-        span_id: s.span_id,
-        span_name: s.name,
-        span_kind: s.kind,
-        attribute_path: bestAttributePathForOffset(slice, m.index) ?? "span.raw",
-        matched_text: truncateForBudget(m[0], textBudget),
-        context_before: truncateForBudget(before, textBudget),
-        context_after: truncateForBudget(after, textBudget),
-        match_offset: m.index
-      });
-    }
-    return { records, total, hasMore };
-  }
-};
-var TraceFileMissingError = class extends NotFoundError {
-  constructor(path) {
-    super(`trace file not found: ${path}`);
-  }
-};
-var TraceNotFoundError = class extends NotFoundError {
-  trace_id;
-  constructor(trace_id) {
-    super(`trace not found: ${trace_id}`);
-    this.trace_id = trace_id;
-  }
-};
-var SpanNotFoundError = class extends NotFoundError {
-  trace_id;
-  span_id;
-  constructor(trace_id, span_id) {
-    super(`span ${span_id} not found in trace ${trace_id}`);
-    this.trace_id = trace_id;
-    this.span_id = span_id;
-  }
-};
-function readOtlpSpan(raw) {
-  const trace_id = stringField(raw, "trace_id") ?? stringField(raw, "traceId");
-  const span_id = stringField(raw, "span_id") ?? stringField(raw, "spanId");
-  if (!trace_id || !span_id) return null;
-  const parent_id = stringField(raw, "parent_span_id") ?? stringField(raw, "parentSpanId") ?? null;
-  const name = stringField(raw, "name") ?? "unknown";
-  const start_time = stringField(raw, "start_time") ?? stringField(raw, "startTime") ?? "";
-  const end_time = stringField(raw, "end_time") ?? stringField(raw, "endTime") ?? start_time;
-  const status = readStatus(raw);
-  const attrs = extractAttributes(raw);
-  const service_name = asString(attrs["service.name"]) ?? asString(attrs["resource.attributes.service.name"]) ?? null;
-  const agent_name = asString(attrs["agent.name"]) ?? asString(attrs["inference.agent.name"]) ?? null;
-  const model_name = asString(attrs["llm.model_name"]) ?? asString(attrs["inference.llm.model_name"]) ?? null;
-  const tool_name = asString(attrs["tool.name"]) ?? asString(attrs["inference.tool.name"]) ?? null;
-  const kind = inferKind(attrs);
-  let duration_ms = 0;
-  if (start_time && end_time) {
-    const a = Date.parse(start_time);
-    const b = Date.parse(end_time);
-    if (!Number.isNaN(a) && !Number.isNaN(b)) duration_ms = Math.max(0, b - a);
-  }
-  return {
-    trace_id,
-    span_id,
-    parent_span_id: parent_id && parent_id.length > 0 ? parent_id : null,
-    name,
-    kind,
-    start_time,
-    end_time,
-    duration_ms,
-    status: status.code,
-    status_message: status.message,
-    service_name,
-    agent_name,
-    model_name,
-    tool_name
-  };
-}
-function readStatus(raw) {
-  const status = raw.status;
-  if (status && typeof status === "object" && !Array.isArray(status)) {
-    const codeRaw = status.code;
-    const code = codeRaw === "STATUS_CODE_OK" || codeRaw === "OK" ? "OK" : codeRaw === "STATUS_CODE_ERROR" || codeRaw === "ERROR" ? "ERROR" : "UNSET";
-    const messageRaw = status.message;
-    const message = typeof messageRaw === "string" && messageRaw.length > 0 ? messageRaw : void 0;
-    return { code, message };
-  }
-  return { code: "UNSET", message: void 0 };
-}
-function inferKind(attrs) {
-  const opik = asString(attrs["openinference.span.kind"]) ?? asString(attrs["inference.observation_kind"]);
-  if (opik) {
-    const upper = opik.toUpperCase();
-    if (upper === "AGENT" || upper === "LLM" || upper === "TOOL" || upper === "CHAIN" || upper === "GUARDRAIL" || upper === "SPAN") {
-      return upper;
-    }
-  }
-  return "UNKNOWN";
-}
-function extractAttributes(raw) {
-  const out = {};
-  const resource = raw.resource;
-  if (resource && typeof resource === "object" && !Array.isArray(resource)) {
-    const ra = resource.attributes;
-    if (ra && typeof ra === "object" && !Array.isArray(ra)) {
-      for (const [k, v] of Object.entries(ra)) {
-        out[k] = v;
-      }
-    }
-  }
-  const spanAttrs = raw.attributes;
-  if (spanAttrs && typeof spanAttrs === "object" && !Array.isArray(spanAttrs)) {
-    for (const [k, v] of Object.entries(spanAttrs)) {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-function stringField(raw, key) {
-  const v = raw[key];
-  return typeof v === "string" ? v : void 0;
-}
-function asString(v) {
-  return typeof v === "string" && v.length > 0 ? v : null;
-}
-function isPresent(v) {
-  return v !== void 0;
-}
-var truncationCounters = /* @__PURE__ */ new WeakMap();
-function trackTruncation(store) {
-  let c = truncationCounters.get(store);
-  if (!c) {
-    c = { value: 0 };
-    truncationCounters.set(store, c);
-  }
-  c.value += 1;
-}
-function truncationCounter(store) {
-  const before = truncationCounters.get(store)?.value ?? 0;
-  return {
-    delta() {
-      const after = truncationCounters.get(store)?.value ?? 0;
-      return after - before;
-    }
-  };
-}
-function bestAttributePathForOffset(slice, offset) {
-  let i = offset;
-  while (i > 0 && slice[i] !== '"') i -= 1;
-  if (i <= 0) return null;
-  let j = i - 1;
-  while (j > 0 && slice[j] !== ":") j -= 1;
-  if (j <= 0) return null;
-  let k = j - 1;
-  while (k > 0 && slice[k] !== '"') k -= 1;
-  let l = k - 1;
-  while (l > 0 && slice[l] !== '"') l -= 1;
-  if (l <= 0) return null;
-  return slice.slice(l + 1, k);
-}
-
-// src/trace-analyst/tools.ts
-import { f, fn } from "@ax-llm/ax";
-var NAMESPACE = "traces";
-var filtersField = f.json("Filter set. ALL fields are AND-composed. Leave empty to scan everything.").optional();
-function buildTraceAnalystTools(opts) {
-  const { store } = opts;
-  const getDatasetOverview = fn("getDatasetOverview").description(
-    "Dataset rollup: total traces, raw_jsonl_bytes, services, agents, models, tools, and sample_trace_ids (real ids passable to view/search). Always call this FIRST without a regex_pattern."
-  ).namespace(NAMESPACE).arg("filters", filtersField).returns(f.json("DatasetOverview")).handler(async ({ filters }) => store.getOverview(parseFilters(filters))).build();
-  const queryTraces = fn("queryTraces").description(
-    "Paginated trace summaries. Each summary carries raw_jsonl_bytes \u2014 use it to size traces BEFORE calling viewTrace. Narrow with indexed filters before adding regex_pattern."
-  ).namespace(NAMESPACE).arg("filters", filtersField).arg("limit", f.number("Page size, 1..200")).arg("offset", f.number("Page offset; default 0").optional()).returns(f.json("QueryTracesPage")).handler(
-    async ({ filters, limit, offset }) => store.queryTraces({
-      filters: parseFilters(filters),
-      limit: assertPageLimit(limit),
-      offset: assertOffset(offset)
-    })
-  ).build();
-  const countTraces = fn("countTraces").description(
-    "Count traces matching `filters`. Use as a cheap pre-flight before opting into a regex_pattern scan."
-  ).namespace(NAMESPACE).arg("filters", filtersField).returns(f.number("count")).handler(async ({ filters }) => store.countTraces(parseFilters(filters))).build();
-  const viewTrace = fn("viewTrace").description(
-    "Return ALL spans for a single trace, with each attribute capped at ~4KB. If the response would exceed the per-call ceiling the result carries `oversized` instead of `spans` \u2014 DO NOT retry with the same trace_id; switch to searchTrace / viewSpans."
-  ).namespace(NAMESPACE).arg("trace_id", f.string("Real trace id from a prior overview/query")).returns(f.json("ViewTraceResult")).handler(
-    async ({ trace_id }) => store.viewTrace({ trace_id: assertString(trace_id, "trace_id") })
-  ).build();
-  const viewSpans = fn("viewSpans").description(
-    "Surgical read of specific spans within a trace, with each attribute capped at ~16KB (4\xD7 the discovery cap). Use after searchTrace narrows to specific span_ids."
-  ).namespace(NAMESPACE).arg("trace_id", f.string("Real trace id")).arg("span_ids", f.string("Span ids to fetch").array()).returns(f.json("ViewSpansResult")).handler(
-    async ({ trace_id, span_ids }) => store.viewSpans({
-      trace_id: assertString(trace_id, "trace_id"),
-      span_ids: assertStringArray(span_ids, "span_ids")
-    })
-  ).build();
-  const searchTrace = fn("searchTrace").description(
-    "Regex search across all spans of one trace. Returns `{trace_id, hits: SpanMatchRecord[], total_matches, has_more}`. **Iterate `result.hits`, NOT `result.matches`** \u2014 the field is `hits`. Each hit has `{span_id, span_name, span_kind, attribute_path, matched_text, context_before, context_after, match_offset}`. Bounded regardless of trace size by max_matches (1..500, default 50). If has_more=true, REFINE the regex rather than blindly raising max_matches."
-  ).namespace(NAMESPACE).arg("trace_id", f.string("Real trace id")).arg("regex_pattern", f.string("JS-compatible regex, multiline")).arg("max_matches", f.number("Max records returned, 1..500; default 50").optional()).returns(f.json("SearchTraceResult")).handler(
-    async ({ trace_id, regex_pattern, max_matches }) => store.searchTrace({
-      trace_id: assertString(trace_id, "trace_id"),
-      regex_pattern: assertRegex(regex_pattern),
-      max_matches: assertMaxMatches(max_matches)
-    })
-  ).build();
-  const searchSpan = fn("searchSpan").description(
-    "Regex search inside a single span. Use when viewSpans returned a 16KB-truncated payload and you need to narrow further. Returns `{trace_id, span_id, hits: SpanMatchRecord[], total_matches, has_more}` \u2014 iterate `result.hits`, NOT `result.matches`."
-  ).namespace(NAMESPACE).arg("trace_id", f.string("Real trace id")).arg("span_id", f.string("Real span id within trace")).arg("regex_pattern", f.string("JS-compatible regex, multiline")).arg("max_matches", f.number("Max records, 1..500; default 50").optional()).returns(f.json("SearchSpanResult")).handler(
-    async ({ trace_id, span_id, regex_pattern, max_matches }) => store.searchSpan({
-      trace_id: assertString(trace_id, "trace_id"),
-      span_id: assertString(span_id, "span_id"),
-      regex_pattern: assertRegex(regex_pattern),
-      max_matches: assertMaxMatches(max_matches)
-    })
-  ).build();
-  return [
-    getDatasetOverview,
-    queryTraces,
-    countTraces,
-    viewTrace,
-    viewSpans,
-    searchTrace,
-    searchSpan
-  ];
-}
-function traceAnalystFunctionGroup(opts) {
-  return {
-    namespace: NAMESPACE,
-    title: "Trace Analysis",
-    selectionCriteria: "Use for any inspection of OTLP-shaped trace data.",
-    description: "Discovery \u2192 narrow \u2192 deep-read tools over a JSONL trace dataset. Always call getDatasetOverview first.",
-    functions: buildTraceAnalystTools(opts)
-  };
-}
-function parseFilters(input) {
-  if (input == null) return void 0;
-  if (typeof input !== "object" || Array.isArray(input)) {
-    throw new TypeError(`filters must be an object, got ${typeof input}`);
-  }
-  const f2 = input;
-  const out = {};
-  if (typeof f2.has_errors === "boolean") out.has_errors = f2.has_errors;
-  out.service_names = stringArrayOrUndefined(f2.service_names, "service_names");
-  out.agent_names = stringArrayOrUndefined(f2.agent_names, "agent_names");
-  out.model_names = stringArrayOrUndefined(f2.model_names, "model_names");
-  out.tool_names = stringArrayOrUndefined(f2.tool_names, "tool_names");
-  if (typeof f2.start_time_after === "string") out.start_time_after = f2.start_time_after;
-  if (typeof f2.start_time_before === "string") out.start_time_before = f2.start_time_before;
-  if (typeof f2.regex_pattern === "string") {
-    if (f2.regex_pattern.length === 0) {
-      throw new TypeError("filters.regex_pattern cannot be empty");
-    }
-    out.regex_pattern = f2.regex_pattern;
-  }
-  return out;
-}
-function stringArrayOrUndefined(v, label) {
-  if (v === void 0 || v === null) return void 0;
-  if (!Array.isArray(v)) throw new TypeError(`${label} must be an array of strings`);
-  if (v.some((x) => typeof x !== "string")) {
-    throw new TypeError(`${label} entries must be strings`);
-  }
-  return v;
-}
-function assertPageLimit(limit) {
-  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 200) {
-    throw new RangeError(`limit must be an integer 1..200`);
-  }
-  return limit;
-}
-function assertOffset(offset) {
-  if (offset === void 0) return void 0;
-  if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0) {
-    throw new RangeError(`offset must be a non-negative integer`);
-  }
-  return offset;
-}
-function assertRegex(pattern) {
-  if (typeof pattern !== "string" || pattern.length === 0) {
-    throw new TypeError(`regex_pattern must be a non-empty string`);
-  }
-  new RegExp(pattern, "m");
-  return pattern;
-}
-function assertMaxMatches(n) {
-  if (n === void 0) return void 0;
-  if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 500) {
-    throw new RangeError(`max_matches must be an integer 1..500`);
-  }
-  return n;
-}
-function assertString(v, label) {
-  if (typeof v !== "string" || v.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string`);
-  }
-  return v;
-}
-function assertStringArray(v, label) {
-  if (!Array.isArray(v)) throw new TypeError(`${label} must be an array of strings`);
-  if (v.some((x) => typeof x !== "string")) {
-    throw new TypeError(`${label} entries must be strings`);
-  }
-  return v;
-}
-
-// src/trace-analyst/analyst.ts
-async function analyzeTraces(input, options) {
-  if (!input.question || typeof input.question !== "string") {
-    throw new TypeError("analyzeTraces: input.question must be a non-empty string");
-  }
-  const store = typeof options.source === "string" ? new OtlpFileTraceStore({ path: options.source }) : options.source;
-  if (store instanceof OtlpFileTraceStore) {
-    await store.ensureIndexed();
-  }
-  const tools = buildTraceAnalystTools({ store });
-  const turns = [];
-  let progressFs;
-  if (options.progressLogPath) {
-    const { createWriteStream } = await import("fs");
-    const { mkdir } = await import("fs/promises");
-    const { dirname } = await import("path");
-    await mkdir(dirname(options.progressLogPath), { recursive: true });
-    progressFs = createWriteStream(options.progressLogPath, { flags: "a" });
-  }
-  const actorTurnCallback = async (turn) => {
-    const snap = {
-      turn: turn.turn,
-      isError: turn.isError,
-      code: turn.code,
-      output: turn.output,
-      thought: turn.thought
-    };
-    turns.push(snap);
-    if (progressFs) {
-      try {
-        progressFs.write(`${JSON.stringify({ ...snap, ts: Date.now() })}
-`);
-      } catch {
-      }
-    }
-    if (options.onTurn) await options.onTurn(snap);
-  };
-  const maxDepth = options.maxDepth ?? 1;
-  const maxTurns = options.maxTurns ?? 12;
-  const maxParallelSubagents = options.maxParallelSubagents ?? 2;
-  const maxRuntimeChars = options.maxRuntimeChars ?? 6e3;
-  const analyst = agent(
-    "question:string -> answer:string, findings:string[]",
-    {
-      agentIdentity: {
-        name: "TraceAnalyst",
-        description: "Analyzes OTLP-shaped JSONL traces using bounded discovery tools to identify systemic failure modes."
-      },
-      contextFields: ["question"],
-      runtime: new AxJSRuntime({
-        permissions: [],
-        blockDynamicImport: true,
-        allowedModules: [],
-        freezeIntrinsics: true,
-        blockShadowRealm: true,
-        // RLM stdout mode relies on runtime bindings persisting across turns.
-        preventGlobalThisExtensions: false
-      }),
-      mode: maxDepth > 0 ? "advanced" : "simple",
-      recursionOptions: maxDepth > 0 ? { maxDepth } : void 0,
-      maxTurns,
-      maxRuntimeChars,
-      maxBatchedLlmQueryConcurrency: maxParallelSubagents,
-      promptLevel: "detailed",
-      // Trace analysis depends on exact prior tool results and runtime variables.
-      contextPolicy: { preset: "full", budget: "balanced" },
-      functions: { local: tools },
-      actorOptions: {
-        description: options.actorDescription ?? TRACE_ANALYST_ACTOR_DESCRIPTION,
-        ...options.model ? { model: options.model } : {},
-        // Keep actor messages tool-call/content shaped across reasoning models.
-        showThoughts: false,
-        thinkingTokenBudget: "none"
-      },
-      responderOptions: {
-        ...options.model ? { model: options.model } : {},
-        description: options.subagentDescription ?? TRACE_ANALYST_SUBAGENT_DESCRIPTION,
-        showThoughts: false
-      },
-      actorTurnCallback,
-      bubbleErrors: [TraceFileMissingError]
-    }
-  );
-  let result;
-  try {
-    result = await analyst.forward(options.ai, { question: input.question });
-  } finally {
-    if (progressFs) {
-      await new Promise((resolve) => progressFs.end(() => resolve()));
-    }
-  }
-  return {
-    answer: typeof result.answer === "string" ? result.answer : String(result.answer ?? ""),
-    findings: Array.isArray(result.findings) ? result.findings.filter((s) => typeof s === "string") : [],
-    turns,
-    turnCount: turns.length,
-    usage: normalizeRoleArrays(analyst.getUsage()),
-    chatLog: normalizeRoleArrays(analyst.getChatLog()),
-    actorPromptVersion: TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION
-  };
-}
-function normalizeRoleArrays(value) {
-  const record = value && typeof value === "object" ? value : {};
-  return {
-    actor: normalizeRecordArray(record.actor),
-    responder: normalizeRecordArray(record.responder)
-  };
-}
-function normalizeRecordArray(value) {
-  if (!Array.isArray(value)) return [];
-  return value.map(
-    (item) => item && typeof item === "object" ? { ...item } : { value: item }
-  );
-}
-
 // src/trace-analyst/hook.ts
 var DEFAULT_QUESTION = "Summarise what happened in this run. Surface any failure modes, surprising findings, or evidence that the run's verdict is wrong.";
 function traceAnalystOnRunComplete(opts) {