@tangle-network/agent-eval 0.129.0 → 0.130.0

package/dist/replay-OoidtG1E.d.ts

@@ -0,0 +1,749 @@
+import { o as NotFoundError, s as ReplayError } from "./errors-CEk209JS.js";
+import { a as RunRecord, l as RunTerminalOutcome, s as RunSplitTag, u as RunTokenUsage } from "./run-record-CnZu_gjl.js";
+import { S as ToolSpan, f as Run } from "./schema-BtVldJ3T.js";
+import { c as RawProviderEvent, l as RawProviderSink } from "./raw-provider-sink-BU29Sh8h.js";
+import { s as TraceStore } from "./store-CT9YIIve.js";
+import { n as RunCompleteHookContext, t as RunCompleteHook } from "./emitter-DGQGoLyj.js";
+import { a as QueryTracesPage, d as TraceAnalystFilters, g as ViewSpansResult, m as TraceAnalystSpanStatus, o as SearchSpanResult, p as TraceAnalystSpanKind, r as DatasetOverview, s as SearchTraceResult, t as TraceAnalysisStore, v as ViewTraceResult } from "./store-CxJry_cs.js";
+import { n as AnalyzeTracesOptions, r as AnalyzeTracesResult } from "./analyst-BkTS3C58.js";
+import { AxFunction } from "@ax-llm/ax";
+//#region src/trace/otel.d.ts
+declare const OTEL_AGENT_EVAL_SCOPE: {
+  name: string;
+  version: string;
+};
+interface OtlpSpan {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  kind: number;
+  startTimeUnixNano: string;
+  endTimeUnixNano: string;
+  attributes: Array<{
+    key: string;
+    value: {
+      stringValue?: string;
+      intValue?: string;
+      doubleValue?: number;
+      boolValue?: boolean;
+    };
+  }>;
+  events?: Array<{
+    timeUnixNano: string;
+    name: string;
+    attributes?: OtlpSpan['attributes'];
+  }>;
+  status?: {
+    code: number;
+    message?: string;
+  };
+}
+interface OtlpResourceSpans {
+  resource: {
+    attributes: OtlpSpan['attributes'];
+  };
+  scopeSpans: Array<{
+    scope: typeof OTEL_AGENT_EVAL_SCOPE;
+    spans: OtlpSpan[];
+  }>;
+}
+interface OtlpExport {
+  resourceSpans: OtlpResourceSpans[];
+}
+/** Export a single run's spans + events in OTLP/JSON. */
+declare function exportRunAsOtlp(store: TraceStore, runId: string, resourceAttrs?: Record<string, string | number | boolean>): Promise<OtlpExport>;
+//#endregion
+//#region src/trace/otlp-attributes.d.ts
+type ToolSpanOtlpInput = Pick<ToolSpan, 'toolName' | 'args' | 'argsCaptured' | 'result' | 'latencyMs'>;
+type OtlpSpanRole = 'AGENT' | 'CHAIN' | 'EVALUATOR' | 'GUARDRAIL' | 'LLM' | 'SPAN' | 'TOOL' | 'UNKNOWN';
+interface OtlpSpanRoleInput {
+  name: string;
+  attributes: Record<string, unknown>;
+  kind?: string | null;
+}
+/**
+ * Classify a span once for both measurement and error accounting.
+ * An explicit OpenInference kind wins; untyped spans use the same tool and
+ * model signals in online and offline intake.
+ */
+declare function classifyOtlpSpanRole(input: OtlpSpanRoleInput): OtlpSpanRole;
+declare function isOtlpModelCall(input: OtlpSpanRoleInput): boolean;
+declare function applyToolSpanOtlpAttributes(attributes: Record<string, unknown>, span: ToolSpanOtlpInput): void;
+declare function traceSpanKindToOpenInferenceKind(kind: string): string;
+//#endregion
+//#region src/trace/otel-export.d.ts
+interface OtelExportConfig {
+  /** OTLP endpoint. Reads OTEL_EXPORTER_OTLP_ENDPOINT env by default. */
+  endpoint?: string;
+  /** OTLP headers. Reads OTEL_EXPORTER_OTLP_HEADERS env by default. */
+  headers?: Record<string, string>;
+  /** Batch size before flush. Default 64. */
+  batchSize?: number;
+  /** Flush interval ms. Default 5000. */
+  flushIntervalMs?: number;
+  /** Resource attributes stamped on every export. */
+  resourceAttributes?: Record<string, string | number | boolean>;
+  /** Service name. Default 'agent-eval'. */
+  serviceName?: string;
+}
+interface OtelExporter {
+  /** Called by the TraceEmitter on every span close. */
+  exportSpan(span: ExportableSpan): void;
+  /** Force flush pending spans. */
+  flush(): Promise<void>;
+  /** Shutdown cleanly — flushes remaining spans and stops the timer. */
+  shutdown(): Promise<void>;
+}
+interface ExportableSpan {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  kind: string;
+  startedAt: number;
+  endedAt?: number;
+  status?: string;
+  error?: string;
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cachedTokens?: number;
+  cacheWriteTokens?: number;
+  costUsd?: number;
+  tool?: ToolSpanOtlpInput;
+  attributes?: Record<string, unknown>;
+}
+/**
+ * Create an OTEL exporter. Returns undefined when no endpoint is configured
+ * (neither via config nor env) — callers should check before attaching.
+ */
+declare function createOtelExporter(config?: OtelExportConfig): OtelExporter | undefined;
+//#endregion
+//#region src/trace/otel-bridge.d.ts
+/**
+ * Create a RunCompleteHook that exports all spans from the completed run
+ * to the OTEL exporter, then flushes.
+ */
+declare function otelRunCompleteHook(exporter: OtelExporter): RunCompleteHook;
+/**
+ * Create an auto-exporting TraceStore wrapper that intercepts updateSpan
+ * calls. When a span gets an endedAt, it's exported immediately. This
+ * gives real-time streaming instead of batch-at-end.
+ *
+ * This is the preferred integration path: wrap the store before
+ * constructing the TraceEmitter.
+ */
+declare function createOtelTracingStore(inner: TraceStore, exporter: OtelExporter, traceId: string): TraceStore;
+//#endregion
+//#region src/trace/redact.d.ts
+/**
+ * Redaction — remove PII / secrets from trace payloads before persist.
+ *
+ * Pre-persistence rules mean raw traces in storage are already scrubbed.
+ * Unredacted variants (for debugging / post-mortems) live in a separate
+ * storage layer with stricter access controls; this module only covers
+ * the default scrub-then-persist path.
+ *
+ * Rules compose: pass an array of `RedactionRule`, each is applied in
+ * order. Strings that match get replaced with a tagged sentinel so the
+ * eval framework can count how many redactions happened per run
+ * (surfaced via `redaction_applied` events).
+ */
+interface RedactionRule {
+  id: string;
+  pattern: RegExp;
+  /** Replacement — e.g. '[PII:email]'. Defaults to `[redacted:{id}]`. */
+  replacement?: string;
+}
+interface RedactionReport {
+  redactionCount: number;
+  byRule: Record<string, number>;
+}
+/** OWASP / common-sense defaults — extend per-domain. */
+declare const DEFAULT_REDACTION_RULES: RedactionRule[];
+declare const REDACTION_VERSION = "1.0.0";
+/**
+ * Redact a single string. Returns the new string and a per-rule count of
+ * how many substitutions fired.
+ */
+declare function redactString(input: string, rules?: RedactionRule[]): {
+  output: string;
+  report: RedactionReport;
+};
+/**
+ * Walk a JSON-ish value applying `redactString` to every string leaf.
+ * Arrays and plain objects are recursed; other types pass through
+ * untouched. Circular references throw — traces should be tree-shaped.
+ */
+declare function redactValue(value: unknown, rules?: RedactionRule[], report?: RedactionReport): {
+  value: unknown;
+  report: RedactionReport;
+};
+//#endregion
+//#region src/trace/store-to-otlp.d.ts
+interface TracesToOtlpResult {
+  /** Total spans emitted across every cell. */
+  spanCount: number;
+  /** Total run-anchor spans (one per Run) appended for analyst visibility. */
+  runCount: number;
+  /** Cells whose shards parsed cleanly. */
+  cellCount: number;
+  /** Cells that errored mid-conversion — surfaced so a partial conversion
+   *  isn't silently masked. */
+  cellErrorCount: number;
+}
+/**
+ * A trace source the analyst should ingest. Two layouts are supported:
+ *
+ *   - `celled` (default): the root holds one cell subdirectory per
+ *     persona/variant, each a `FileSystemTraceStore` (`runs.ndjson`,
+ *     `spans.ndjson`, `events.ndjson`).
+ *   - `flat`: the root is itself a single `FileSystemTraceStore` (e.g. a
+ *     production-ingestion sidecar that appends one ndjson set directly under
+ *     the chosen directory).
+ */
+interface TraceStoreSource {
+  /** Absolute path to the trace store root. */
+  root: string;
+  /** Layout — `celled` (default) or `flat`. */
+  layout?: 'celled' | 'flat';
+  /** OTLP `service.name` for this source. Overrides the options default. */
+  serviceName?: string;
+}
+/** Domain hooks. The walker is generic; consumers inject the namespaced
+ *  attributes that ride along on every run + span for analyst discovery. */
+interface TraceStoreToOtlpOptions {
+  /** Default OTLP `service.name` when a source doesn't set its own.
+   *  Default `agent-eval`. */
+  serviceName?: string;
+  /** Extra resource attributes per run, e.g.
+   *  `(run) => ({ 'legal.persona_id': run.tags?.personaId ?? '' })`. */
+  resourceAttributes?: (run: Run) => Record<string, unknown>;
+  /** Extra attributes on the per-run anchor span, e.g. domain outcome fields. */
+  runAttributes?: (run: Run) => Record<string, unknown>;
+}
+/**
+ * Read every per-cell shard under each source root and write a flat OTLP-JSONL
+ * view of the corpus to `outPath`. Each cell directory is a
+ * `FileSystemTraceStore` — NDJSON append-only with size-based rotation;
+ * `updateRun`/`updateSpan` append `{ id, ...patch, _update: true }` rows
+ * rather than rewriting, so readers must merge those patches in (done here).
+ *
+ * A `string` source is treated as a celled root.
+ */
+declare function convertTraceStoresToOtlp(source: string | TraceStoreSource | readonly TraceStoreSource[], outPath: string, opts?: TraceStoreToOtlpOptions): TracesToOtlpResult;
+//#endregion
+//#region src/trace-analyst/hook.d.ts
+interface TraceAnalystHookOptions {
+  /**
+   * Options forwarded to `analyzeTraces`. The hook supplies the question
+   * if you don't pass one — defaulting to a launch-grade prompt that asks
+   * for failure modes, surprising findings, and a recommendation.
+   */
+  analyze: Omit<AnalyzeTracesOptions, 'source'> & {
+    source?: AnalyzeTracesOptions['source'];
+  };
+  /**
+   * Override the question. The default is intentionally generic:
+   * "Summarise what happened in this run, surface any failure modes,
+   *  surprising findings, or evidence the verdict is wrong."
+   */
+  question?: string;
+  /**
+   * Persist the result. The hook calls this with the analysis output and
+   * the run context. Common implementations write to a TraceAnalysisStore
+   * or append to a per-run JSONL.
+   */
+  save?: (result: AnalyzeTracesResult, ctx: RunCompleteHookContext) => Promise<void>;
+  /**
+   * Predicate gating execution per run. Default: every completed run.
+   * Use to skip aborted runs, debug runs, or runs without LLM activity.
+   */
+  shouldRun?: (ctx: RunCompleteHookContext) => boolean;
+  /**
+   * Optional gate: if set and returns false, the hook records the failure
+   * as a log event on the run instead of staying quiet. The caller can
+   * then trigger downstream alerts off `analyst_gate_failed` log events.
+   */
+  gateOn?: (result: AnalyzeTracesResult, ctx: RunCompleteHookContext) => boolean;
+}
+declare function traceAnalystOnRunComplete(opts: TraceAnalystHookOptions): RunCompleteHook;
+//#endregion
+//#region src/trace-analyst/insights.d.ts
+interface TraceInsightTask {
+  id: string;
+  name: string;
+  prompt?: string;
+  difficulty?: string;
+  tags?: string[];
+  outcome?: string;
+  score?: number;
+  gaps?: string[];
+}
+interface TraceInsightSuite {
+  name: string;
+  collectionId?: string;
+  tasks: TraceInsightTask[];
+}
+interface TraceInsightFinding {
+  kind: string;
+  severity?: string;
+  taskIds: string[];
+  evidence?: string;
+  proposedFixClass?: string;
+}
+interface TraceInsightQuestion {
+  id: string;
+  question: string;
+  why: string;
+}
+interface TraceInsightPanelRole {
+  id: string;
+  name: string;
+  responsibility: string;
+}
+interface TraceInsightPromptInput {
+  suite: TraceInsightSuite;
+  findings?: TraceInsightFinding[];
+  agent?: Record<string, unknown>;
+  totals?: Record<string, unknown>;
+  maxRepresentativeTraces?: number;
+}
+interface TraceInsightContext {
+  suite: TraceInsightSuite;
+  scope: string;
+  keywords: string[];
+  questions: TraceInsightQuestion[];
+  panel: TraceInsightPanelRole[];
+  findings: TraceInsightFinding[];
+  agent: Record<string, unknown> | null;
+  totals: Record<string, unknown> | null;
+}
+interface TraceInsightQualityGate {
+  id: string;
+  label: string;
+  passed: boolean;
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  detail: string;
+}
+interface TraceInsightReadiness {
+  score: number;
+  grade: 'external-ready' | 'internal-review' | 'raw-analysis';
+  gates: TraceInsightQualityGate[];
+}
+declare function tokenizeDomainWords(value: string): string[];
+declare function inferDomainKeywords(suite: TraceInsightSuite): string[];
+declare function domainEvidencePattern(keywords: string[]): RegExp;
+declare function describeTraceInsightScope(suite: TraceInsightSuite): string;
+declare function planTraceInsightQuestions(input: TraceInsightPromptInput): TraceInsightQuestion[];
+declare function buildTraceInsightContext(input: TraceInsightPromptInput): TraceInsightContext;
+declare function scoreTraceInsightReadiness(context: TraceInsightContext): TraceInsightReadiness;
+declare function defaultTraceInsightPanel(): TraceInsightPanelRole[];
+declare function buildTraceInsightPrompt(input: TraceInsightPromptInput): string;
+//#endregion
+//#region src/trace-analyst/otlp-flatten.d.ts
+interface OtlpFlatLine {
+  trace_id: string;
+  span_id: string;
+  parent_span_id: string | null;
+  name: string;
+  kind: string;
+  start_time: string;
+  end_time: string;
+  status: {
+    code: 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR' | 'STATUS_CODE_UNSET';
+    message?: string;
+  };
+  resource: {
+    attributes: Record<string, string | number | boolean>;
+  };
+  attributes: Record<string, string | number | boolean>;
+  events?: Array<{
+    name: string;
+    timeUnixNano?: string;
+    attributes?: Record<string, unknown>;
+  }>;
+}
+interface FlattenOtlpOptions {
+  /** `'openinference'` (default) maps source per-span attributes into the
+   *  canonical OpenInference vocabulary the analyst readers consume. `'none'`
+   *  passes attributes through untouched. */
+  attributeVocabulary?: 'openinference' | 'none';
+  /** Override the numeric-kind → otlp-string mapping. */
+  kindMap?: Partial<Record<number, string>>;
+}
+declare function flattenOtlpExportToNdjson(otlpExport: OtlpExport, opts?: FlattenOtlpOptions): OtlpFlatLine[];
+//#endregion
+//#region src/trace-analyst/otlp-span.d.ts
+/**
+ * The structural fields a flat OTLP-JSONL line projects to. `attributes`
+ * is the merged resource+span attribute map (span overrides resource);
+ * the named fields are the pivots every reader of a trace needs without
+ * paying the full attribute materialisation.
+ */
+interface ProjectedOtlpSpan {
+  trace_id: string;
+  span_id: string;
+  parent_span_id: string | null;
+  name: string;
+  kind: TraceAnalystSpanKind;
+  start_time: string;
+  end_time: string;
+  duration_ms: number;
+  status: TraceAnalystSpanStatus;
+  status_message: string | undefined;
+  service_name: string | null;
+  agent_name: string | null;
+  model_name: string | null;
+  tool_name: string | null;
+  /** Merged resource + span attributes, span winning on overlap. */
+  attributes: Record<string, unknown>;
+}
+/**
+ * Project one parsed OTLP-JSONL object to `ProjectedOtlpSpan`, or `null`
+ * when the line is missing the mandatory `trace_id` + `span_id`.
+ */
+declare function projectOtlpFlatLine(raw: Record<string, unknown>): ProjectedOtlpSpan | null;
+declare function readOtlpStatus(raw: Record<string, unknown>): {
+  code: TraceAnalystSpanStatus;
+  message: string | undefined;
+};
+declare function inferOtlpKind(attrs: Record<string, unknown>): TraceAnalystSpanKind;
+/**
+ * Flatten OTLP `attributes` + `resource.attributes` into a single
+ * dotted-key map. Span attributes override resource attributes when keys
+ * overlap. Nested objects/arrays are preserved as-is.
+ */
+declare function extractOtlpAttributes(raw: Record<string, unknown>): Record<string, unknown>;
+declare function stringField(raw: Record<string, unknown>, key: string): string | undefined;
+declare function asString(v: unknown): string | null;
+/** First non-empty string value across a list of candidate attribute keys. */
+declare function firstStringAttr(attrs: Record<string, unknown>, keys: readonly string[]): string | null;
+//#endregion
+//#region src/trace-analyst/otlp-to-run-records.d.ts
+interface OtlpToRunRecordsOptions {
+  /** Logical experiment grouping for every produced record. */
+  experimentId: string;
+  /** Candidate (variant) id — the surface these traces exercised. The
+   *  bench passes the proposer label here so `compareOptimizationMethods` can pair rows. */
+  candidateId: string;
+  /** Split assignment for every produced record. Default `'holdout'` —
+   *  ingested traces are evidence, not the optimizer's training pool. */
+  splitTag?: RunSplitTag;
+  /** Git SHA the traces were produced from. Default `'unknown'`. */
+  commitSha?: string;
+  /** sha256 of the effective prompt surface. Default `'unknown'`. */
+  promptHash?: string;
+  /** sha256 of the effective config. Default `'unknown'`. */
+  configHash?: string;
+  /** RNG seed recorded on every row. Default 0. */
+  seed?: number;
+  /**
+   * Fallback model snapshot when the trace exposes no LLM model attribute
+   * OR exposes a bare alias `validateRunRecord` would reject. The trace's
+   * own model wins when it already carries a snapshot. Default
+   * `'unknown@otlp'` (opaque-snapshot form the validator accepts).
+   */
+  fallbackModel?: string;
+  /**
+   * USD per total token (input+output) used to price a trace when no
+   * per-span cost attribute is present. When unset, an unpriced trace
+   * records `costUsd: null` and `raw.cost_unpriced = 1`.
+   */
+  priceUsdPerToken?: number;
+  /**
+   * Map each OTLP `trace_id` to the logical run it belongs to. Use this when a
+   * provider emits several traces for one task attempt. All mapped traces are
+   * aggregated into one record; duplicate span ids remain isolated by their
+   * source trace. The callback must return a non-empty id for every trace.
+   *
+   * When omitted, every `trace_id` remains an independent run.
+   */
+  logicalRunIdForTrace?: (traceId: string) => string;
+  /**
+   * Score for a produced run's outcome (AppWorld `world.evaluate()` →
+   * TGC/SGC, or
+   * any [0,1] task-success signal). Keyed by the logical run id when
+   * `logicalRunIdForTrace` is supplied, otherwise by `trace_id`. When the map
+   * has no entry or the function returns undefined, the record remains
+   * unlabeled.
+   */
+  scoreForTrace?: (runId: string, span: TraceAggregate) => number | undefined;
+  /**
+   * Per-record judge metadata when an external judge produced the score.
+   * Keyed by the logical run id when supplied, otherwise by `trace_id`.
+   */
+  judgeMetadataForTrace?: (runId: string) => RunRecord['judgeMetadata'] | undefined;
+}
+/** A `RunRecord` plus the verbatim prompt/completion text when the trace's
+ *  LLM spans exposed it. The text is NOT on the validated `RunRecord`
+ *  (`outcome.raw` is numeric-only) but consumers ingesting full traces want
+ *  it — so it rides alongside. */
+interface OtlpTraceRunRecord {
+  record: RunRecord;
+  /** Verbatim first-LLM-span `input.value`, when present. */
+  promptText?: string;
+  /** Verbatim last-LLM-span `output.value`, when present. */
+  completionText?: string;
+}
+/** Per-trace rollup the score callback can inspect. */
+interface TraceAggregate {
+  traceId: string;
+  /** Number of source OTLP traces folded into this run. */
+  sourceTraceCount: number;
+  /** Source OTLP trace ids folded into this run, sorted for deterministic audit output. */
+  sourceTraceIds: readonly string[];
+  spanCount: number;
+  llmSpanCount: number;
+  toolSpanCount: number;
+  agentSpanCount: number;
+  errorSpanCount: number;
+  executionErrorCount: number;
+  processErrorCount: number;
+  guardrailErrorCount: number;
+  judgeErrorCount: number;
+  propagatedErrorCount: number;
+  unclassifiedErrorCount: number;
+  tokenUsage: RunTokenUsage;
+  /** First error span's normalized status message, if any. */
+  firstErrorMessage?: string;
+  model: string;
+  startTime: string;
+  endTime: string;
+  wallMs: number;
+  /** Root-span terminal result. Child span errors do not change this value. */
+  terminalOutcome: RunTerminalOutcome;
+}
+/**
+ * Parse + aggregate an OTLP traces.jsonl string into validated
+ * `RunRecord[]` (one per trace). Use {@link otlpToTraceRunRecords} when you
+ * also want the verbatim prompt/completion text alongside each record.
+ */
+declare function otlpToRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): RunRecord[];
+/**
+ * Aggregate already-parsed OTLP flat rows without serializing them back to
+ * JSONL. This is the in-memory counterpart to {@link otlpToRunRecords}; both
+ * paths share projection, reconciliation, validation, and ordering.
+ */
+declare function otlpRowsToRunRecords(rows: Iterable<object>, opts: OtlpToRunRecordsOptions): RunRecord[];
+/** As {@link otlpToRunRecords} but returns the prompt/completion text too. */
+declare function otlpToTraceRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
+/** Parsed-row counterpart to {@link otlpToTraceRunRecords}. */
+declare function otlpRowsToTraceRunRecords(rows: Iterable<object>, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
+//#endregion
+//#region src/trace-analyst/prompts.d.ts
+/** Ax RLM prompt for bounded trace discovery and evidence-backed analysis. */
+declare const TRACE_ANALYST_ACTOR_DESCRIPTION = "You answer questions about an OTLP-shaped JSONL trace dataset using the trace tools provided in the `traces` namespace.\n\nDISCOVERY → NARROW → DEEP-READ protocol — follow exactly:\n\n1. 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 — never fabricate one).\n\n2. 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 — narrow with indexed fields (has_errors, model_names, service_names, agent_names, time bounds) BEFORE adding a regex on a large dataset.\n\n3. To list more traces than the sample, call `traces.queryTraces({ filters?, limit, offset? })`. Each summary carries raw_jsonl_bytes — use it to choose between viewTrace and searchTrace BEFORE calling either.\n\n4. Per-trace inspection:\n   - 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.\n   - 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× higher than discovery), or `traces.searchSpan({ trace_id, span_id, regex_pattern })` for one large span. Stays bounded regardless of trace size.\n   - Useful regex patterns: `STATUS_CODE_ERROR` (failures), tool names like `grep` or `view_trace`, error strings like `MaxTurnsExceeded`, model names, attribute keys.\n\n5. 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.\n\n5a. **Result-shape contract** — 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 — log the result shape first if unsure.\n\n6. 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.\n\n7. If searchTrace or searchSpan returns has_more=true, REFINE the regex to be more specific rather than blindly raising max_matches.\n\n8. If a tool errors (invalid regex, range error), STOP and reconsider — don't retry with a guessed id or argument. Use the discovery tools above to recover.\n\n9. 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.\n\n10. If the question splits into independent reasoning branches, use bounded `llmQuery(...)` calls over evidence you already loaded. Subqueries cannot inspect the trace store, so pass the exact trace excerpts they need. Example:\n\n    const reviews = await llmQuery([\n      { query: 'Classify the failure mechanism in this excerpt.', context: traceAbcExcerpt },\n      { query: 'Classify the failure mechanism in this excerpt.', context: traceDefExcerpt },\n    ]);\n\nOBSERVABILITY rules:\n- Each discovery turn must emit at least one concise `console.log(...)` showing what evidence was learned.\n- Finish gathering evidence before submitting the analysis.\n- Reuse runtime variables across turns; don't recompute.\n\nOUTPUT contract — your final answer must include:\n- A clear prose conclusion answering the user's question.\n- Trace ids and span ids cited as evidence for each claim.\n- Failure modes named in the user's domain language, with frequency and concrete examples.\n- A concise findings array containing only claims supported by inspected evidence.\n\nDo NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.";
+declare const TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-actor-v6-2026-07-14";
+//#endregion
+//#region src/trace-analyst/store-otlp.d.ts
+interface OtlpFileTraceStoreOptions {
+  /** Path to the OTLP-JSONL file. */
+  path: string;
+  /** Override the discovery (`viewTrace`) per-attribute byte cap. */
+  perAttributeViewBudget?: number;
+  /** Override the surgical (`viewSpans`) per-attribute byte cap. */
+  perAttributeSpanBudget?: number;
+  /** Override the per-call ceiling that triggers oversized summaries. */
+  perCallByteCeiling?: number;
+  /** Override the per-match text budget. */
+  perMatchTextBudget?: number;
+  /**
+   * Hard ceiling on the trace file size in bytes. The store reads the
+   * whole file into one Buffer and indexes it in memory, so an
+   * unbounded file OOMs the process. Above this size the store fails
+   * loud with `TraceFileTooLargeError` instead of degrading silently.
+   * Default 256 MiB.
+   */
+  maxFileBytes?: number;
+}
+declare class OtlpFileTraceStore implements TraceAnalysisStore {
+  private readonly path;
+  private readonly perAttributeViewBudget;
+  private readonly perAttributeSpanBudget;
+  private readonly perCallByteCeiling;
+  private readonly perMatchTextBudget;
+  private readonly maxFileBytes;
+  private 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. */
+  private bufferPromise?;
+  constructor(opts: OtlpFileTraceStoreOptions);
+  getOverview(filters?: TraceAnalystFilters): Promise<DatasetOverview>;
+  queryTraces(opts: {
+    filters?: TraceAnalystFilters;
+    limit: number;
+    offset?: number;
+  }): Promise<QueryTracesPage>;
+  countTraces(filters?: TraceAnalystFilters): Promise<number>;
+  viewTrace(opts: {
+    trace_id: string;
+    per_attribute_byte_cap?: number;
+  }): Promise<ViewTraceResult>;
+  viewSpans(opts: {
+    trace_id: string;
+    span_ids: readonly string[];
+    per_attribute_byte_cap?: number;
+  }): Promise<ViewSpansResult>;
+  searchTrace(opts: {
+    trace_id: string;
+    regex_pattern: string;
+    max_matches?: number;
+  }): Promise<SearchTraceResult>;
+  searchSpan(opts: {
+    trace_id: string;
+    span_id: string;
+    regex_pattern: string;
+    max_matches?: number;
+  }): Promise<SearchSpanResult>;
+  /** Force the index to materialise. Useful to amortise startup cost
+   *  before the first agent call. */
+  ensureIndexed(): Promise<void>;
+  private buffer;
+  /** Stat-then-read so an oversized file fails loud BEFORE we allocate a
+   *  multi-hundred-MB Buffer and OOM the process. A missing file surfaces
+   *  as TraceFileMissingError; any other stat/read error propagates. */
+  private readGuarded;
+  private index;
+  private buildIndex;
+  private matchedTraces;
+  private toSummary;
+  private projectSpan;
+  private buildOversizedSummary;
+  private scanSpanForMatches;
+}
+declare class TraceFileMissingError extends NotFoundError {
+  constructor(path: string);
+}
+declare class TraceNotFoundError extends NotFoundError {
+  readonly trace_id: string;
+  constructor(trace_id: string);
+}
+declare class SpanNotFoundError extends NotFoundError {
+  readonly trace_id: string;
+  readonly span_id: string;
+  constructor(trace_id: string, span_id: string);
+}
+//#endregion
+//#region src/trace-analyst/tools.d.ts
+interface BuildTraceAnalystToolsOpts {
+  store: TraceAnalysisStore;
+  /** Override the default sample-trace-id slot count (20). Mostly for tests. */
+  sampleTraceLimit?: number;
+}
+/**
+ * Build the trace-analyst function set. Pass the result into
+ * `agent(...).functions.local`.
+ */
+declare function buildTraceAnalystTools(opts: BuildTraceAnalystToolsOpts): AxFunction[];
+/**
+ * Convenience: same shape as `buildTraceAnalystTools` but returns the
+ * grouped form expected when registering trace tools alongside other
+ * agent function modules. */
+declare function traceAnalystFunctionGroup(opts: BuildTraceAnalystToolsOpts): {
+  namespace: string;
+  title: string;
+  selectionCriteria: string;
+  description: string;
+  functions: AxFunction[];
+};
+//#endregion
+//#region src/replay.d.ts
+declare class ReplayCacheMissError extends ReplayError {
+  readonly url: string;
+  readonly requestKey: string;
+  constructor(url: string, requestKey: string, message?: string);
+}
+interface ReplayCacheEntry {
+  request: RawProviderEvent;
+  response: RawProviderEvent;
+}
+interface ReplayCacheStats {
+  total: number;
+  byProvider: Record<string, number>;
+  byModel: Record<string, number>;
+  /** Spans for which we have a request but no response (run aborted mid-call). */
+  orphanRequests: number;
+}
+/**
+ * In-memory deterministic cache of (request → response) keyed on a stable
+ * hash of the request body. Built from a `RawProviderSink` containing
+ * paired `request` and `response` events from a previous run.
+ *
+ * The cache is the source of truth for replay; `createReplayFetch` is a
+ * thin wrapper that reads from it.
+ */
+declare class ReplayCache {
+  private byKey;
+  private orphans;
+  private byProvider;
+  private byModel;
+  /**
+   * Build a cache from a sink's events. The sink must implement `list()`.
+   * Filter by `runId` / `spanId` to scope to a specific replay.
+   */
+  static fromSink(sink: RawProviderSink, filter?: {
+    runId?: string;
+    spanId?: string;
+  }): Promise<ReplayCache>;
+  /** Build a cache from an in-memory event list. */
+  static fromEvents(events: RawProviderEvent[]): Promise<ReplayCache>;
+  /** Number of cacheable (request, response) pairs in the cache. */
+  size(): number;
+  stats(): ReplayCacheStats;
+  /** Iterate every cached `(request, response)` pair in insertion order. */
+  entries(): IterableIterator<ReplayCacheEntry>;
+  /**
+   * Look up a cached response by hashing the (model, messages, temperature,
+   * maxTokens, response_format) shape. Returns `undefined` on miss; the
+   * caller decides whether to throw, fall back to the network, or skip.
+   */
+  lookup(requestBody: unknown): Promise<ReplayCacheEntry | undefined>;
+}
+interface ReplayFetchOptions {
+  /**
+   * Behaviour on cache miss. Default `'throw'`. `'fallback'` calls the
+   * `fallbackFetch` (typically `globalThis.fetch`) so a partial replay can
+   * still complete; `'fail-closed'` returns a synthetic 599 response so the
+   * call site sees a non-retriable failure.
+   */
+  onMiss?: 'throw' | 'fallback' | 'fail-closed';
+  fallbackFetch?: typeof fetch;
+  /** Optional callback fired once per replayed call (for telemetry / counters). */
+  onHit?: (info: {
+    url: string;
+    provider: string;
+    model: string;
+  }) => void;
+  /** Optional callback fired on cache miss before the `onMiss` policy applies. */
+  onMissNotify?: (info: {
+    url: string;
+    requestBody: unknown;
+  }) => void;
+}
+/**
+ * Build a `fetch`-shaped function that serves cached responses out of a
+ * `ReplayCache` for any URL ending in `/chat/completions`. Pass through
+ * `LlmClientOptions.fetch` and `callLlm` becomes free.
+ *
+ * Non-`/chat/completions` URLs are passed straight to the fallback fetch
+ * (default: `globalThis.fetch`). This matters because non-LLM HTTP work
+ * (judge HTTP servers, sandbox callbacks) sometimes flows through the same
+ * `fetch` and shouldn't be intercepted.
+ */
+declare function createReplayFetch(cache: ReplayCache, opts?: ReplayFetchOptions): typeof fetch;
+/**
+ * Convenience iterator over `(request, response)` pairs in a sink — for
+ * post-hoc scoring that doesn't need a `fetch` shim. The judge or scorer
+ * runs purely in-process over cached LLM outputs.
+ */
+declare function iterateRawCalls(sink: RawProviderSink, filter?: {
+  runId?: string;
+  spanId?: string;
+}): AsyncGenerator<ReplayCacheEntry>;
+//#endregion
+export { TraceAnalystHookOptions as $, readOtlpStatus as A, TraceInsightQuestion as B, otlpToTraceRunRecords as C, traceSpanKindToOpenInferenceKind as Ct, firstStringAttr as D, OtlpSpan as Dt, extractOtlpAttributes as E, OtlpResourceSpans as Et, TraceInsightContext as F, buildTraceInsightPrompt as G, TraceInsightSuite as H, TraceInsightFinding as I, domainEvidencePattern as J, defaultTraceInsightPanel as K, TraceInsightPanelRole as L, FlattenOtlpOptions as M, OtlpFlatLine as N, inferOtlpKind as O, exportRunAsOtlp as Ot, flattenOtlpExportToNdjson as P, tokenizeDomainWords as Q, TraceInsightPromptInput as R, otlpToRunRecords as S, isOtlpModelCall as St, asString as T, OtlpExport as Tt, TraceInsightTask as U, TraceInsightReadiness as V, buildTraceInsightContext as W, planTraceInsightQuestions as X, inferDomainKeywords as Y, scoreTraceInsightReadiness as Z, OtlpToRunRecordsOptions as _, OtlpSpanRole as _t, ReplayFetchOptions as a, DEFAULT_REDACTION_RULES as at, otlpRowsToRunRecords as b, applyToolSpanOtlpAttributes as bt, buildTraceAnalystTools as c, RedactionRule as ct, OtlpFileTraceStoreOptions as d, createOtelTracingStore as dt, traceAnalystOnRunComplete as et, SpanNotFoundError as f, otelRunCompleteHook as ft, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION as g, createOtelExporter as gt, TRACE_ANALYST_ACTOR_DESCRIPTION as h, OtelExporter as ht, ReplayCacheStats as i, convertTraceStoresToOtlp as it, stringField as j, projectOtlpFlatLine as k, traceAnalystFunctionGroup as l, redactString as lt, TraceNotFoundError as m, OtelExportConfig as mt, ReplayCacheEntry as n, TraceStoreToOtlpOptions as nt, createReplayFetch as o, REDACTION_VERSION as ot, TraceFileMissingError as p, ExportableSpan as pt, describeTraceInsightScope as q, ReplayCacheMissError as r, TracesToOtlpResult as rt, iterateRawCalls as s, RedactionReport as st, ReplayCache as t, TraceStoreSource as tt, OtlpFileTraceStore as u, redactValue as ut, OtlpTraceRunRecord as v, OtlpSpanRoleInput as vt, ProjectedOtlpSpan as w, OTEL_AGENT_EVAL_SCOPE as wt, otlpRowsToTraceRunRecords as x, classifyOtlpSpanRole as xt, TraceAggregate as y, ToolSpanOtlpInput as yt, TraceInsightQualityGate as z };
+//# sourceMappingURL=replay-OoidtG1E.d.ts.map