@tangle-network/agent-eval 0.95.0 → 0.96.0

package/dist/traces.d.ts

@@ -1,4 +1,976 @@
-export * from './replay';
-export * from './trace';
-export * from './trace-analyst';
-//# sourceMappingURL=traces.d.ts.map
+import { N as NotFoundError, R as ReplayError } from './errors-CzMUYo7b.js';
+import { P as ProviderRedactor, R as RawProviderSink, d as RawProviderEvent } from './raw-provider-sink-C46HDghv.js';
+export { F as FileSystemRawProviderSink, a as FileSystemRawProviderSinkOptions, I as InMemoryRawProviderSink, b as InMemoryRawProviderSinkOptions, N as NoopRawProviderSink, c as RawProviderDirection, e as RawProviderSinkFilter, f as defaultProviderRedactor, p as providerFromBaseUrl } from './raw-provider-sink-C46HDghv.js';
+import { a as RunCompleteHookContext, R as RunCompleteHook } from './emitter-C2rqGH_l.js';
+export { S as SpanHandle, T as TraceEmitter, b as TraceEmitterOptions, l as llmSpanFromProvider } from './emitter-C2rqGH_l.js';
+export { b as RunIntegrityError, R as RunIntegrityExpectations, c as RunIntegrityIssue, d as RunIntegrityIssueCode, a as RunIntegrityReport, e as assertRunCaptured, t as throwIfRunIncomplete } from './integrity-D2t12mMw.js';
+import { T as TraceStore } from './store-BcFXE6LG.js';
+export { E as EventFilter, F as FileSystemTraceStore, a as FileSystemTraceStoreOptions, I as InMemoryTraceStore, R as RunFilter, S as SpanFilter } from './store-BcFXE6LG.js';
+export { a as aggregateLlm, b as argHash, g as groupBy, j as judgeSpans, l as llmSpans, r as runFailureClass, c as runsForScenario, t as toolSpans } from './query-B7GGjRox.js';
+export { D as DEFAULT_REDACTION_RULES, b as REDACTION_VERSION, a as RedactionReport, R as RedactionRule, r as redactString, c as redactValue } from './redact-B40YG2M_.js';
+import { R as Run } from './schema-m0gsnbt3.js';
+export { A as Artifact, B as BudgetLedgerEntry, h as BudgetSpec, E as EventKind, i as FAILURE_CLASSES, F as FailureClass, G as GenericSpan, J as JudgeSpan, L as LlmSpan, M as Message, d as RetrievalSpan, g as RunLayer, b as RunOutcome, f as RunStatus, e as SandboxSpan, S as Span, j as SpanBase, c as SpanKind, k as SpanStatus, l as TRACE_SCHEMA_VERSION, T as ToolSpan, a as TraceEvent, m as isJudgeSpan, n as isLlmSpan, o as isRetrievalSpan, p as isSandboxSpan, q as isToolSpan } from './schema-m0gsnbt3.js';
+import { A as AnalyzeTracesOptions, b as AnalyzeTracesResult } from './analyst-C8HHvfJp.js';
+export { a as AnalyzeTracesInput, c as AnalyzeTracesTurnSnapshot, d as analyzeTraces } from './analyst-C8HHvfJp.js';
+import { h as TraceAnalystSpanKind, i as TraceAnalystSpanStatus, T as TraceAnalysisStore, g as TraceAnalystFilters, b as DatasetOverview, Q as QueryTracesPage, l as ViewTraceResult, V as ViewSpansResult, c as SearchTraceResult, S as SearchSpanResult } from './store-C1YxJDEK.js';
+export { D as DEFAULT_TRACE_ANALYST_BUDGETS, E as ErrorCluster, d as SpanMatchRecord, e as TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, f as TraceAnalystByteBudgets, a as TraceAnalystSpan, j as TraceAnalystTraceSummary, k as ViewTraceOversized } from './store-C1YxJDEK.js';
+import { a as RunSplitTag, b as RunTokenUsage, R as RunRecord } from './run-record-CP2ObebC.js';
+import { AxFunction } from '@ax-llm/ax';
+import '@tangle-network/agent-interface';
+
+/** Canonical OpenInference-over-OTLP attribute vocabulary used at the trace boundary. */
+declare const OPENINFERENCE_SPAN_KIND = "openinference.span.kind";
+declare const LLM_MODEL_NAME = "llm.model_name";
+declare const LLM_INPUT_TOKENS = "llm.token_count.prompt";
+declare const LLM_OUTPUT_TOKENS = "llm.token_count.completion";
+declare const LLM_CACHED_TOKENS = "llm.token_count.prompt_cache_hit";
+declare const LLM_COST_USD = "llm.cost_usd";
+declare const TOOL_NAME = "tool.name";
+declare const SPAN_KIND_ATTR_KEYS: readonly ["openinference.span.kind", "inference.observation_kind"];
+declare const LLM_MODEL_ATTR_KEYS: readonly ["llm.model_name", "inference.llm.model_name", "llm.model", "gen_ai.request.model", "gen_ai.response.model"];
+declare const LLM_INPUT_TOKEN_ATTR_KEYS: readonly ["llm.token_count.prompt", "inference.llm.input_tokens", "llm.input_tokens", "gen_ai.usage.input_tokens", "gen_ai.usage.prompt_tokens"];
+declare const LLM_OUTPUT_TOKEN_ATTR_KEYS: readonly ["llm.token_count.completion", "inference.llm.output_tokens", "llm.output_tokens", "gen_ai.usage.output_tokens", "gen_ai.usage.completion_tokens"];
+declare const LLM_CACHED_TOKEN_ATTR_KEYS: readonly ["llm.token_count.prompt_cache_hit", "inference.llm.cached_tokens", "llm.cached_tokens", "gen_ai.usage.cached_tokens"];
+declare const LLM_COST_ATTR_KEYS: readonly ["llm.cost_usd", "inference.llm.cost.total", "llm.cost.total", "gen_ai.usage.cost"];
+declare const TOOL_NAME_ATTR_KEYS: readonly ["tool.name", "inference.tool.name"];
+declare function traceSpanKindToOpenInferenceKind(kind: string): string;
+
+/**
+ * Trace-analyst auto-execution hook.
+ *
+ * Wires `analyzeTraces` into a `TraceEmitter`'s `onRunComplete` so a
+ * direct matrix run produces an analysis artifact without an out-of-band
+ * step. Designed for the case where the consumer reports "the analyst
+ * never ran" — the cause is almost always orchestration, not the analyst.
+ *
+ * Usage:
+ *
+ *   const emitter = new TraceEmitter(store, {
+ *     onRunComplete: [traceAnalystOnRunComplete({ analyze: opts, save })],
+ *   })
+ *
+ * Hooks are best-effort by default — they never crash the underlying run.
+ * The caller decides whether to gate the run on the analysis result via
+ * the `gateOn` callback.
+ */
+
+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;
+
+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;
+
+/**
+ * OpenTelemetry JSON export — maps TraceSchema v1 to OTLP/JSON so
+ * traces render natively in Jaeger / Honeycomb / Langfuse / Grafana.
+ *
+ * Wire format only. We do NOT depend on the @opentelemetry SDK — that
+ * would drag in polyfills incompatible with Workers/Edge. Consumers
+ * push the JSON to their collector of choice via HTTP.
+ *
+ * Reference: OTLP 1.3.2 (ResourceSpans / ScopeSpans / Span).
+ */
+
+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>;
+
+/**
+ * `flattenOtlpExportToNdjson` — flatten an `OtlpExport` (the shape
+ * `exportRunAsOtlp` produces) into the per-line JSON the analyst's
+ * `OtlpFileTraceStore` index reads. Replaces three per-consumer OTLP
+ * flatteners with one canonical projection.
+ *
+ * Pure function, no I/O — the caller does `.map(JSON.stringify).join('\n')`
+ * and writes the file (consumers want control over rotation + naming).
+ */
+
+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) mirrors legacy 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[];
+
+/**
+ * Canonical OTLP-flat-line readers shared by every consumer of the
+ * OTLP-JSONL wire shape (one OTLP span per line; the form
+ * `flattenOtlpExportToNdjson` produces and the form AppWorld / HALO
+ * emit via their OpenInference OTLP exporter).
+ *
+ * `OtlpFileTraceStore` indexes spans with these; `otlpToRunRecords`
+ * aggregates spans into `RunRecord`s with the same readers. One parser,
+ * one vocabulary — a divergence between the analyst's view of a trace and
+ * the RunRecord projected from it is a class of bug this consolidation
+ * removes by construction.
+ *
+ * Vocabulary. The readers understand BOTH dialects that appear in the
+ * wild:
+ *   - the substrate's own `llm.*` / `tool.*` / `span.kind` attributes
+ *     (`flattenSpanAttributes` in `trace/otel.ts`), and
+ *   - the OpenInference / inference-export attributes AppWorld / HALO
+ *     emit (`openinference.span.kind`, `inference.observation_kind`,
+ *     `inference.llm.input_tokens`, `llm.token_count.prompt`, …).
+ *
+ * Pure, no I/O.
+ */
+
+/**
+ * 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;
+/** Read a numeric attribute, tolerating numeric strings; `null` if absent/NaN. */
+declare function asNumber(v: unknown): number | null;
+/** First finite numeric value across a list of candidate attribute keys. */
+declare function firstNumberAttr(attrs: Record<string, unknown>, keys: readonly string[]): number | 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;
+
+/**
+ * `otlpToRunRecords` — fold an OTLP traces.jsonl (one OTLP span per line;
+ * the form AppWorld / HALO emit via their OpenInference OTLP exporter, the
+ * same shape `flattenOtlpExportToNdjson` produces) into validated
+ * `RunRecord[]` — one record per `trace_id` (one trace == one task).
+ *
+ * This is the offline ingestion primitive the AppWorld proposer bench and the
+ * hosted Intelligence product both stand on: traces in, paper-grade rows
+ * out, ready for `compareProposers` / `analyzeRuns` / the promotion gate.
+ *
+ * Aggregation per trace:
+ *   - tokenUsage: sum LLM-span `input` / `output` (+ `cached` when present)
+ *     across every LLM span in the trace.
+ *   - costUsd: sum per-span LLM cost when present; else priced via
+ *     `opts.priceUsdPerToken` from the aggregated tokens; else 0 with a
+ *     loud `raw.cost_unpriced = 1` marker so a missing price is visible, not
+ *     a silent zero folded into a gate.
+ *   - failureMode: the first `STATUS_CODE_ERROR` span's normalized status
+ *     message (carries the real failure signature, not a generic class).
+ *   - model: the dominant LLM model in the trace (snapshot-padded to satisfy
+ *     `validateRunRecord` when the trace's model is a bare alias).
+ *   - outcome score: `opts.scoreForTrace` (AppWorld `world.evaluate()` →
+ *     TGC/SGC) when supplied; else 1 when the trace had no error span, 0
+ *     when it did — a defensible default the caller can override.
+ *   - prompt / completion: carried into `raw` as token-count signals and,
+ *     when the first/last LLM span exposes `input.value` / `output.value`,
+ *     the verbatim text is preserved on the optional `promptText` /
+ *     `completionText` of the returned `OtlpTraceRunRecord`.
+ *
+ * Fail-loud: an OTLP file with zero valid spans throws. A trace with no
+ * spans is impossible (a trace exists only because a span referenced it).
+ * `validateRunRecord` runs on every row — a malformed projection throws
+ * rather than silently producing a half-record.
+ */
+
+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 `compareProposers` 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: 0` AND `raw.cost_unpriced = 1` — the zero is flagged,
+     * never silent.
+     */
+    priceUsdPerToken?: number;
+    /**
+     * Score for a trace's outcome (AppWorld `world.evaluate()` → TGC/SGC, or
+     * any [0,1] task-success signal). Keyed by `trace_id`; falls through to
+     * the error-derived default (1 = no error span, 0 = had one) when the map
+     * has no entry or the function returns undefined.
+     */
+    scoreForTrace?: (traceId: string, span: TraceAggregate) => number | undefined;
+    /**
+     * Per-record judge metadata when an external judge produced the score.
+     * Keyed by `trace_id`.
+     */
+    judgeMetadataForTrace?: (traceId: 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;
+    spanCount: number;
+    llmSpanCount: number;
+    toolSpanCount: number;
+    agentSpanCount: number;
+    errorSpanCount: number;
+    tokenUsage: RunTokenUsage;
+    /** First error span's normalized status message, if any. */
+    firstErrorMessage?: string;
+    model: string;
+    startTime: string;
+    endTime: string;
+    wallMs: number;
+}
+/**
+ * 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[];
+/** As {@link otlpToRunRecords} but returns the prompt/completion text too. */
+declare function otlpToTraceRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
+
+/** 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 \u2192 NARROW \u2192 DEEP-READ protocol \u2014 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 \u2014 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 \u2014 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 \u2014 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\u00D7 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** \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.\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 \u2014 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 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:\n\n    const reviews = await llmQuery([\n      { query: 'Drill into trace abc123 \u2014 what tool calls preceded the failure?', context: { trace_id: 'abc123' } },\n      { query: 'Drill into trace def456 \u2014 same failure mode?', context: { trace_id: 'def456' } },\n    ]);\n\nOBSERVABILITY rules:\n- 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).\n- 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.\n- Reuse runtime variables across turns; don't recompute.\n- 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.\n\nCRITICAL \u2014 `final()` payload contract for evidence-grounded analysis tasks:\n- 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.\n- Example for per-item verdict tasks:\n  ```js\n  await final(\"Format the per-item verdict report from the evidence below.\", {\n    findings: [\n      { id: 'sub-1-finding-1', claim: '...', verdict: 'TRUE-POSITIVE', evidence: 'lines 42-45 of contracts/X.sol show ...' },\n      ...all items\n    ],\n    systemic_summary: '3 sentences I wrote based on the evidence above'\n  });\n  ```\n- 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.\n- 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']`).\n\nOUTPUT contract \u2014 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\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-v5-2026-05-06";
+/** Subagent prompt for focused trace-inspection subtasks. */
+declare const 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.\n\nCite trace ids and span ids for every claim. Do NOT invent ids.";
+
+/**
+ * `OtlpFileTraceStore` — read-only OTLP-JSONL trace store for the
+ * trace-analyst.
+ *
+ * Wire shape. Each line of the input file is one OTLP-shaped span. The
+ * store understands flattened OTLP JSONL plus the OpenInference vocab.
+ * We project upstream's full
+ * span shape down to `TraceAnalystSpan` lazily — full materialisation
+ * only happens for the spans the agent actually requests.
+ *
+ * Indexing. On first read the store builds an in-memory index keyed
+ * by `trace_id` carrying:
+ *   - byte offsets + lengths for each span line (for surgical reads
+ *     without re-parsing the whole file)
+ *   - a `TraceAnalystTraceSummary` rollup
+ *   - sets of services / agents / models / tools / has_errors
+ *   - byte size of the trace's JSONL slab
+ *
+ * Memory bound. The index keeps span metadata only — names, kinds,
+ * offsets, status. Attribute payloads stay on disk until requested.
+ * For a 50MB JSONL with 50k spans, the index is ~5MB.
+ *
+ * Concurrency. The store builds the index once on first read and
+ * caches it. Subsequent reads reuse the index. The file is opened on
+ * each read; we never hold a long-lived FD.
+ */
+
+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);
+}
+
+/**
+ * Trace-analyst tool surface — six namespaced AxFunctions the analyst
+ * agent calls from generated JS code via `traces.<name>(...)`.
+ *
+ * Discovery → narrow → deep-read protocol. Tool names + ordering
+ * support RLM discovery:
+ *
+ *   1. `getDatasetOverview` (cheap)  — first call, sizes the dataset
+ *   2. `queryTraces`                 — paginated summaries with `raw_jsonl_bytes`
+ *   3. `countTraces`                 — cheap pre-flight before regex
+ *   4. `viewTrace`                   — full span list, oversized → summary
+ *   5. `viewSpans`                   — surgical 16KB-cap reads
+ *   6. `searchTrace` / `searchSpan`  — bounded regex hits
+ *
+ * Failure mode. Tool handlers throw on bad input (invalid trace ids,
+ * out-of-range pagination, malformed regex). Ax converts thrown errors
+ * into actor-visible `[ERROR]` strings so the analyst can adjust on
+ * the next turn instead of looping.
+ */
+
+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[];
+};
+
+/**
+ * Token-usage extraction from chat-completions responses and SSE streams.
+ *
+ * `captureFetchToRawSink` records the raw provider triple but deliberately does
+ * not interpret token usage — cost is a per-consumer axis. Three consumers each
+ * re-implement the same `usage` parser on top of the captured response (the
+ * OpenAI `prompt_tokens`/`completion_tokens` shape, the Anthropic
+ * `input_tokens`/`output_tokens` shape, and the camelCase variants), plus an
+ * SSE accumulator that sums the per-chunk `usage` deltas. This is the one
+ * canonical version.
+ *
+ * Both functions return `null` (not a silent `{ input: 0, output: 0 }`) when no
+ * usage is present, so a caller can tell "no usage reported" from "zero tokens".
+ */
+interface ExtractedUsage {
+    input: number;
+    output: number;
+    /** Cached prompt tokens, when the provider reports them. */
+    cached?: number;
+}
+/**
+ * Pull `{ input, output, cached? }` from a parsed chat-completions response
+ * body. Accepts a top-level `usage` object (the common case) or a body that IS
+ * the usage object. Returns null when neither an input nor an output count is
+ * present — callers must inspect for null rather than treat it as zero cost.
+ */
+declare function extractUsage(body: unknown): ExtractedUsage | null;
+/**
+ * Sum token usage across an SSE response body. Each `data:` line is parsed and
+ * fed to `extractUsage`; the per-chunk counts are accumulated. The `[DONE]`
+ * sentinel and non-JSON lines are skipped. Returns null when no chunk carried
+ * usage — distinguishing a usage-less stream from a genuine zero.
+ *
+ * Providers report SSE usage in two ways: a single terminal chunk with the full
+ * totals, or incremental per-chunk deltas. Summing is correct for the delta
+ * case and harmless for the terminal case (one non-null chunk ⇒ the total).
+ */
+declare function extractUsageFromSse(text: string): ExtractedUsage | null;
+/**
+ * Extract usage from an HTTP `Response` without consuming the caller's body:
+ * clones, reads the text, and tries the JSON parser first, then the SSE
+ * accumulator. Best-effort — returns null on any read/parse miss so a usage tee
+ * never takes down the underlying call.
+ */
+declare function extractUsageFromResponse(response: Response): Promise<ExtractedUsage | null>;
+
+/**
+ * `captureFetchToRawSink` — wrap a `fetch` so every request / response / error
+ * against a provider is recorded into a `RawProviderSink` as the canonical
+ * `RawProviderEvent` triple. The one substrate copy of the fetch-capture
+ * pattern four consumers hand-roll (legal ships two copies).
+ *
+ * The returned value is a plain `typeof fetch` — pass it as the `fetchImpl` to
+ * any OpenAI-compatible backend factory. Capture is best-effort by default: a
+ * sink write that throws does NOT take down the underlying LLM call (set
+ * `failClosed` to change that). Uses the existing `defaultProviderRedactor` +
+ * `providerFromBaseUrl` — no new redaction policy.
+ */
+
+interface CaptureFetchContext {
+    /** Logical run id stamped on every captured event. Required — without it
+     *  the raw events can't be paired with their parent `Run`. */
+    runId: string;
+    /** Optional logical span id (enables span-level sink filtering). */
+    spanId?: string;
+    /** Resolved base URL (normalised, no trailing slash). Used for the event's
+     *  `baseUrl` and for endpoint-path extraction. */
+    baseUrl: string;
+    /** Model id the caller intends to invoke. Stamped on every event. */
+    model: string;
+    /** Provider override. When omitted, `providerFromBaseUrl(baseUrl)`. */
+    provider?: string;
+}
+interface CaptureFetchOptions {
+    /** Override the capture-time redactor. Default `defaultProviderRedactor`. */
+    redactor?: ProviderRedactor;
+    /** Cap on captured response-body bytes; beyond it the body is truncated and
+     *  `body_truncated` is added to `redactedFields`. Default 2 MiB. */
+    responseBodyByteCap?: number;
+    /** When true, a sink-write failure propagates to the caller. Default false
+     *  — capture is best-effort so a sink failure never kills the LLM call. */
+    failClosed?: boolean;
+    /**
+     * Invoked with the token usage parsed off each successful response (JSON or
+     * SSE), keyed by the captured context. Lets a caller fold usage → cost without
+     * re-cloning the response themselves. Not called when the response carries no
+     * usage. Best-effort: a throw here is swallowed (it never kills the LLM call)
+     * unless `failClosed` is set.
+     */
+    onUsage?: (usage: ExtractedUsage, ctx: CaptureFetchContext) => void;
+}
+declare function captureFetchToRawSink(fetch: typeof globalThis.fetch, sink: RawProviderSink, ctx: CaptureFetchContext, opts?: CaptureFetchOptions): typeof globalThis.fetch;
+
+/**
+ * OTEL span exporter — streams spans to an OTLP/HTTP collector.
+ *
+ * Reads OTEL_EXPORTER_OTLP_ENDPOINT + OTEL_EXPORTER_OTLP_HEADERS from env
+ * when no explicit config is given. Batches spans and flushes periodically
+ * or when the batch fills. No @opentelemetry SDK dependency — minimal
+ * OTLP/JSON serializer (~120 LOC) using the existing otel.ts helpers.
+ */
+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;
+    costUsd?: number;
+    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;
+
+/**
+ * OTEL bridge — connects TraceEmitter span lifecycle to the OtelExporter.
+ *
+ * When an OtelExporter is active, every span that closes through the
+ * TraceEmitter is also pushed to the exporter for real-time streaming to
+ * the user's OTEL collector.
+ *
+ * The bridge is opt-in: attach via `otelRunCompleteHook(exporter)` as a
+ * RunCompleteHook, or wrap the store with `createOtelTracingStore` for
+ * real-time per-span export.
+ */
+
+/**
+ * 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;
+
+/**
+ * Convert agent-eval's internal trace shape (`FileSystemTraceStore` → `Run`,
+ * `Span`, `TraceEvent`) into the OTLP-flat JSONL the trace analyst
+ * (`analyzeTraces` + `OtlpFileTraceStore`) reads.
+ *
+ * Eval harnesses shard a `FileSystemTraceStore` per cell (persona / variant)
+ * under a run directory. The analyst consumes a single OTLP-NDJSON file keyed
+ * on `trace_id` + `span_id` with `start_time`/`end_time` in ISO-8601 and
+ * resource + `attributes` rolled up per-span. This module walks every shard,
+ * projects each `Span` (plus events pinned to it) into the flat OTLP shape,
+ * and emits one NDJSON file.
+ *
+ * Generic OTLP/OpenInference fields are always emitted (`service.name`,
+ * `agent.name`, `run.id`/`run.status`, `openinference.span.kind`,
+ * `llm.model_name`, …). Domain attributes (`legal.*`, `tax.*`, …) are injected
+ * per-run via {@link TraceStoreToOtlpOptions.resourceAttributes} /
+ * {@link TraceStoreToOtlpOptions.runAttributes} so consumers don't re-roll the
+ * walker.
+ */
+
+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;
+
+/**
+ * Replay-from-raw-events — turn every captured campaign run into a
+ * re-runnable artifact.
+ *
+ * `RawProviderSink` captures every provider HTTP envelope; `runEvalCampaign`
+ * makes that capture the default. Together they make every past run a
+ * complete fingerprint of what happened on the wire — enough to replay
+ * the run without burning new LLM cost.
+ *
+ * Three use cases this primitive enables:
+ *
+ *   1. **Post-hoc judging** — apply a new judge / rubric / scoring callback
+ *      to last week's runs without re-calling any LLM. The cost of trying
+ *      a new rubric drops from "another full sweep" to a CPU-bound replay.
+ *   2. **Determinism audits** — replay the same campaign and verify the
+ *      raw responses match byte-for-byte. Any drift is a non-determinism
+ *      bug (in the harness, the prompt builder, the sandbox, …).
+ *   3. **Free judge calibration** — run two judges on identical responses
+ *      and measure inter-judge agreement without doubling LLM spend.
+ *
+ * The interface is deliberately fetch-shaped. Inject `createReplayFetch`
+ * into `LlmClientOptions.fetch` and every `callLlm` transparently reads
+ * from the cache instead of calling the network. No new code path through
+ * the LLM client is needed; the cache hit is invisible to the runner.
+ */
+
+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>;
+
+export { AnalyzeTracesOptions, AnalyzeTracesResult, type CaptureFetchContext, type CaptureFetchOptions, DatasetOverview, type ExportableSpan, type ExtractedUsage, type FlattenOtlpOptions, LLM_CACHED_TOKENS, LLM_CACHED_TOKEN_ATTR_KEYS, LLM_COST_ATTR_KEYS, LLM_COST_USD, LLM_INPUT_TOKENS, LLM_INPUT_TOKEN_ATTR_KEYS, LLM_MODEL_ATTR_KEYS, LLM_MODEL_NAME, LLM_OUTPUT_TOKENS, LLM_OUTPUT_TOKEN_ATTR_KEYS, OPENINFERENCE_SPAN_KIND, OTEL_AGENT_EVAL_SCOPE, type OtelExportConfig, type OtelExporter, type OtlpExport, OtlpFileTraceStore, type OtlpFileTraceStoreOptions, type OtlpFlatLine, type OtlpResourceSpans, type OtlpSpan, type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, type ProjectedOtlpSpan, ProviderRedactor, QueryTracesPage, RawProviderEvent, RawProviderSink, ReplayCache, type ReplayCacheEntry, ReplayCacheMissError, type ReplayCacheStats, type ReplayFetchOptions, Run, RunCompleteHook, RunCompleteHookContext, SPAN_KIND_ATTR_KEYS, SearchSpanResult, SearchTraceResult, SpanNotFoundError, TOOL_NAME, TOOL_NAME_ATTR_KEYS, TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_SUBAGENT_DESCRIPTION, type TraceAggregate, TraceAnalysisStore, TraceAnalystFilters, type TraceAnalystHookOptions, TraceAnalystSpanKind, TraceAnalystSpanStatus, TraceFileMissingError, type TraceInsightContext, type TraceInsightFinding, type TraceInsightPanelRole, type TraceInsightPromptInput, type TraceInsightQualityGate, type TraceInsightQuestion, type TraceInsightReadiness, type TraceInsightSuite, type TraceInsightTask, TraceNotFoundError, TraceStore, type TraceStoreSource, type TraceStoreToOtlpOptions, type TracesToOtlpResult, ViewSpansResult, ViewTraceResult, asNumber, asString, buildTraceAnalystTools, buildTraceInsightContext, buildTraceInsightPrompt, captureFetchToRawSink, convertTraceStoresToOtlp, createOtelExporter, createOtelTracingStore, createReplayFetch, defaultTraceInsightPanel, describeTraceInsightScope, domainEvidencePattern, exportRunAsOtlp, extractOtlpAttributes, extractUsage, extractUsageFromResponse, extractUsageFromSse, firstNumberAttr, firstStringAttr, flattenOtlpExportToNdjson, inferDomainKeywords, inferOtlpKind, iterateRawCalls, otelRunCompleteHook, otlpToRunRecords, otlpToTraceRunRecords, planTraceInsightQuestions, projectOtlpFlatLine, readOtlpStatus, scoreTraceInsightReadiness, stringField, tokenizeDomainWords, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };