@tangle-network/agent-eval 0.117.1 → 0.118.0

package/dist/traces.d.ts

@@ -1,678 +1,786 @@
-import { N as NotFoundError, R as ReplayError } from './errors-oeQrLqXC.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-CjD7vUwv.js';
-export { S as SpanHandle, T as TraceEmitter, b as TraceEmitterOptions, l as llmSpanFromProvider } from './emitter-CjD7vUwv.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-DqlBiLyK.js';
-import { T as TraceStore } from './store-DGqD0Pyo.js';
-export { E as EventFilter, F as FileSystemTraceStore, a as FileSystemTraceStoreOptions, I as InMemoryTraceStore, R as RunFilter, S as SpanFilter } from './store-DGqD0Pyo.js';
-import { T as ToolSpan, R as Run } from './schema-B3Q3l9Z_.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, c as RetrievalSpan, g as RunLayer, a as RunOutcome, f as RunStatus, d as SandboxSpan, S as Span, j as SpanBase, b as SpanKind, k as SpanStatus, l as TRACE_SCHEMA_VERSION, e as TraceEvent, m as isJudgeSpan, n as isLlmSpan, o as isRetrievalSpan, p as isSandboxSpan, q as isToolSpan } from './schema-B3Q3l9Z_.js';
-export { a as aggregateLlm, b as argHash, g as groupBy, h as hasCapturedToolArgs, j as judgeSpans, l as llmSpans, r as runFailureClass, c as runsForScenario, t as toolSpans } from './query-CF7PG61p.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, c as RunTokenUsage, R as RunRecord } from './run-record-BDH49H2E.js';
-import { AxFunction } from '@ax-llm/ax';
-import '@tangle-network/agent-interface';
+import { AxAIService, AxFunction } from '@ax-llm/ax';
 
-/** 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 TOOL_ARGS_CAPTURED = "tool.args_captured";
-declare const TOOL_LATENCY_MS = "tool.latency_ms";
-declare const INPUT_VALUE = "input.value";
-declare const OUTPUT_VALUE = "output.value";
-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"];
-type ToolSpanOtlpInput = Pick<ToolSpan, 'toolName' | 'args' | 'argsCaptured' | 'result' | 'latencyMs'>;
-declare function applyToolSpanOtlpAttributes(attributes: Record<string, unknown>, span: ToolSpanOtlpInput): void;
-declare function traceSpanKindToOpenInferenceKind(kind: string): string;
+/**
+ * Error taxonomy for `@tangle-network/agent-eval`.
+ *
+ * Every error this package throws as part of its *public contract* extends
+ * `AgentEvalError`. Consumers can pattern-match by `instanceof <Subclass>` or
+ * by the stable string `code` carried on the base class.
+ *
+ * The codes are stable across minor versions; new codes can be added, but
+ * existing codes never change meaning. New subclasses are non-breaking.
+ *
+ * Internal invariant guards (`throw new Error('this should never happen')`)
+ * remain plain `Error`s on purpose — they're programmer-mistake assertions,
+ * not consumer-catchable contract failures.
+ */
+type AgentEvalErrorCode = 'validation' | 'not_found' | 'config' | 'capture_integrity' | 'judge' | 'verification' | 'replay' | 'backend_integrity' | 'profile_matrix';
+/**
+ * Base class for every contract error this package throws — carries the stable
+ * string `code` taxonomy so consumers can `instanceof`-match or switch on `code`.
+ */
+declare class AgentEvalError extends Error {
+    /** Stable string code. Survives minification; safe to switch on. */
+    readonly code: AgentEvalErrorCode;
+    constructor(code: AgentEvalErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A named resource (run, span, rubric, scenario, dataset row, route) does not exist. */
+declare class NotFoundError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A run is missing the artifacts a launch-grade check requires:
+ * raw HTTP capture absent, no LLM spans, route assertion failed, run-end
+ * assertion tripped. Block ship on this; do not catch and move on.
+ */
+declare class CaptureIntegrityError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Replay cache cannot satisfy a request: miss with no fallback, sink lacks list(), unsupported URL. */
+declare class ReplayError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 
 /**
- * Trace-analyst auto-execution hook.
+ * RawProviderSink — first-class persistence for the actual HTTP-level
+ * request/response bodies of every LLM provider call.
  *
- * 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.
+ * Why this is a separate sink from the structured `LlmSpan`:
  *
- * Usage:
+ *   - `LlmSpan` records the *intent* — model name, messages, output text,
+ *     usage. It's what dashboards read; it's NOT enough for forensics.
+ *   - When a downstream consumer reports "the verifier used the wrong route"
+ *     or "tokens look right but reasoning was missing," the only way to
+ *     answer is the raw HTTP body. Span fields can lie (a proxy can echo
+ *     a different `model` value than what actually answered); the raw
+ *     response is ground truth.
  *
- *   const emitter = new TraceEmitter(store, {
- *     onRunComplete: [traceAnalystOnRunComplete({ analyze: opts, save })],
- *   })
+ * Default behaviour: opt-in. Pass `rawSink` to `LlmClientOptions` (or the
+ * matrix runner / BuilderSession sets it up automatically) and every
+ * request, response, and error is recorded — including retries, with the
+ * attempt index attached so a flaky call's full event chain is recoverable.
  *
- * 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.
+ * Redaction is enforced at sink time. The default redactor strips
+ * `Authorization`, `X-Api-Key`, `X-Auth-Token`, `Cookie` headers and any
+ * payload field whose key matches `apiKey | api_key | bearer | password |
+ * secret | token` (case-insensitive). Override via the sink constructor or
+ * the per-call `redactor`. The `redactedFields` array on the persisted
+ * event lets a reviewer see what was stripped without exposing the values.
  */
-
-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;
+type RawProviderDirection = 'request' | 'response' | 'error';
+interface RawProviderEvent {
+    /** Stable id. Generated by the sink if omitted. */
+    eventId: string;
+    /** Trace context populated by `LlmClient` when the call is wrapped in a span. */
+    runId?: string;
+    spanId?: string;
     /**
-     * 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.
+     * Logical provider name. Free-form so callers can use whatever id matches
+     * their topology (`'openai'`, `'anthropic'`, `'tangle-router'`, …). When
+     * omitted, derived from `baseUrl` in `LlmClientOptions`.
      */
-    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[];
+    provider: string;
+    model: string;
+    /** Endpoint path, e.g. `'/v1/chat/completions'`. */
+    endpoint: string;
+    /** Base URL used for the call (already-normalised — no trailing slash). */
+    baseUrl: string;
+    /** 0-indexed retry attempt. The first attempt is 0; a retried call gets 1, 2, … */
+    attemptIndex: number;
+    direction: RawProviderDirection;
+    /** Unix ms. */
+    timestamp: number;
+    /** Wall-clock duration of the call leg. Set on `response` and `error` events; null on `request`. */
+    durationMs?: number;
+    statusCode?: number;
+    requestHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    responseHeaders?: Record<string, string>;
+    responseBody?: unknown;
+    /** Set on `direction: 'error'` events. */
+    errorMessage?: string;
+    /** Field paths the redactor stripped from this event ('header:Authorization', 'body.apiKey', …). */
+    redactedFields: string[];
 }
-interface TraceInsightFinding {
-    kind: string;
-    severity?: string;
-    taskIds: string[];
-    evidence?: string;
-    proposedFixClass?: string;
+interface RawProviderSinkFilter {
+    runId?: string;
+    spanId?: string;
+    direction?: RawProviderDirection;
+    attemptIndex?: number;
 }
-interface TraceInsightQuestion {
-    id: string;
-    question: string;
-    why: string;
+interface RawProviderSink {
+    record(event: RawProviderEvent): Promise<void>;
+    /** Optional listing — implementations that durably persist (file, db) should support this. */
+    list?(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
+    /** Optional teardown for backed implementations. */
+    close?(): Promise<void>;
 }
-interface TraceInsightPanelRole {
-    id: string;
-    name: string;
-    responsibility: string;
+type ProviderRedactor = (event: RawProviderEvent) => RawProviderEvent;
+/**
+ * Default redactor — strips well-known auth headers and any body field whose
+ * key matches the credential pattern. Records every redacted path on
+ * `event.redactedFields` so a downstream reviewer can see what was removed.
+ */
+declare function defaultProviderRedactor(event: RawProviderEvent): RawProviderEvent;
+interface InMemoryRawProviderSinkOptions {
+    redactor?: ProviderRedactor;
 }
-interface TraceInsightPromptInput {
-    suite: TraceInsightSuite;
-    findings?: TraceInsightFinding[];
-    agent?: Record<string, unknown>;
-    totals?: Record<string, unknown>;
-    maxRepresentativeTraces?: number;
+declare class InMemoryRawProviderSink implements RawProviderSink {
+    private events;
+    private redactor;
+    constructor(opts?: InMemoryRawProviderSinkOptions);
+    record(event: RawProviderEvent): Promise<void>;
+    list(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
+    size(): 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;
+declare class NoopRawProviderSink implements RawProviderSink {
+    record(): Promise<void>;
+    /**
+     * Returns an empty array. Implemented so `assertRunCaptured` does not
+     * trip the `no_raw_sink` issue when a caller explicitly opts out of
+     * capture by passing this sink — opt-out is a deliberate choice, not a
+     * misconfiguration.
+     */
+    list(): Promise<RawProviderEvent[]>;
 }
-interface TraceInsightQualityGate {
-    id: string;
-    label: string;
-    passed: boolean;
-    severity: 'critical' | 'high' | 'medium' | 'low';
-    detail: string;
+interface FileSystemRawProviderSinkOptions {
+    /** Directory the NDJSON file is written into. Created if missing. */
+    dir: string;
+    /** File name; default `'raw-provider-events.ndjson'`. */
+    fileName?: string;
+    /** Bytes after which the writer rolls over to a new file (default 32 MiB). */
+    rollAtBytes?: number;
+    redactor?: ProviderRedactor;
 }
-interface TraceInsightReadiness {
-    score: number;
-    grade: 'external-ready' | 'internal-review' | 'raw-analysis';
-    gates: TraceInsightQualityGate[];
+declare class FileSystemRawProviderSink implements RawProviderSink {
+    private dir;
+    private fileName;
+    private rollAtBytes;
+    private redactor;
+    private bytesWritten;
+    private rollIndex;
+    private initPromise;
+    constructor(opts: FileSystemRawProviderSinkOptions);
+    private ensureInit;
+    private currentPath;
+    record(event: RawProviderEvent): Promise<void>;
+    list(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
 }
-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;
+/**
+ * Best-effort provider id from a base URL. Falls back to the URL host when
+ * none of the well-known patterns match.
+ */
+declare function providerFromBaseUrl(baseUrl: string): string;
 
 /**
- * OpenTelemetry JSON export — maps TraceSchema v1 to OTLP/JSON so
- * traces render natively in Jaeger / Honeycomb / Langfuse / Grafana.
+ * Replay-from-raw-events — turn every captured campaign run into a
+ * re-runnable artifact.
  *
- * 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.
+ * `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.
  *
- * Reference: OTLP 1.3.2 (ResourceSpans / ScopeSpans / Span).
+ * 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 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;
-    };
+declare class ReplayCacheMissError extends ReplayError {
+    readonly url: string;
+    readonly requestKey: string;
+    constructor(url: string, requestKey: string, message?: string);
 }
-interface OtlpResourceSpans {
-    resource: {
-        attributes: OtlpSpan['attributes'];
-    };
-    scopeSpans: Array<{
-        scope: typeof OTEL_AGENT_EVAL_SCOPE;
-        spans: OtlpSpan[];
-    }>;
+interface ReplayCacheEntry {
+    request: RawProviderEvent;
+    response: RawProviderEvent;
 }
-interface OtlpExport {
-    resourceSpans: OtlpResourceSpans[];
+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;
 }
-/** 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.
+ * 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.
  *
- * Pure function, no I/O — the caller does `.map(JSON.stringify).join('\n')`
- * and writes the file (consumers want control over rotation + naming).
+ * The cache is the source of truth for replay; `createReplayFetch` is a
+ * thin wrapper that reads from it.
  */
-
-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>;
-    }>;
+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 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>>;
+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;
 }
-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).
+ * 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.
  *
- * `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.
+ * 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>;
+
+type AgentProfileCellSchemaVersion = 'agent-profile-cell/v1';
+type AgentProfileDimensionValue = string | number | boolean | null;
+interface AgentProfileSource {
+    /** Runtime/profile contract being fingerprinted, e.g. `agent-interface-profile`. */
+    kind: string;
+    /** sha256 over the canonical source profile object. */
+    hash: string;
+}
+interface AgentProfileHarness {
+    id: string;
+    version?: string;
+    hash?: string;
+}
+interface AgentProfileCell {
+    schemaVersion: AgentProfileCellSchemaVersion;
+    cellId: string;
+    profileId: string;
+    sourceProfile: AgentProfileSource;
+    harness?: AgentProfileHarness;
+    model?: string;
+    promptHash?: string;
+    dimensions?: Record<string, AgentProfileDimensionValue>;
+}
+
+/**
+ * TraceSchema v1 — the canonical data model for agent-eval.
  *
- * 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`, …).
+ * Every score, every failure class, every pipeline in the framework is
+ * a view over this data. Shape it once, live with it.
  *
- * Pure, no I/O.
+ * Wire-compatible with OpenTelemetry span semantics (see trace/otel.ts)
+ * but extended with agent-specific span kinds (llm, tool, retrieval,
+ * judge, sandbox) and first-class BudgetLedger / Artifact / JudgeVerdict
+ * entities that OTEL leaves as free-form attributes.
  */
-
+declare const TRACE_SCHEMA_VERSION = "1.0.0";
+type RunStatus = 'running' | 'completed' | 'failed' | 'aborted';
+interface BudgetSpec {
+    tokens?: number;
+    wallMs?: number;
+    calls?: number;
+    usd?: number;
+}
+interface RunOutcome$1 {
+    score?: number;
+    pass?: boolean;
+    failureClass?: FailureClass;
+    notes?: string;
+}
 /**
- * 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.
+ * Layer — optional classification in a nested build workflow.
+ * `builder`: the meta-agent editing a project (e.g. agent-builder Forge chat).
+ * `app-build`: sandbox harness that compiled + tested the generated scaffold.
+ * `app-runtime`: a run of the generated agent against a domain scenario.
+ * `meta`: any meta-eval (judge replay, correlation analysis).
  */
-interface ProjectedOtlpSpan {
-    trace_id: string;
-    span_id: string;
-    parent_span_id: string | null;
+type RunLayer = 'builder' | 'app-build' | 'app-runtime' | 'meta' | 'custom';
+interface Run {
+    runId: string;
+    /**
+     * Stable identifier of the scenario being executed.
+     *
+     * Always populated on the persisted Run — but `TraceEmitter.startRun` accepts
+     * input WITHOUT this field, substituting a sensible default
+     * (`run.layer ?? run.tags?.['kind'] ?? 'runtime'`) when the caller has no
+     * curated scenario to anchor to (runtime / operator / meta-eval runs). This
+     * keeps the persisted shape unambiguous for downstream filters + aggregations
+     * while removing the boilerplate of inventing placeholder ids at the call site.
+     */
+    scenarioId: string;
+    variantId?: string;
+    datasetVersion?: string;
+    /** Git SHA of agent code at run time. */
+    codeSha?: string;
+    /** Hash of the prompt template + any system prompt. */
+    promptSha?: string;
+    /** Model id + date + system-prompt hash, concatenated. */
+    modelFingerprint?: string;
+    seed?: number;
+    /** Arbitrary environment markers (shell, docker version, tz). */
+    envFingerprint?: Record<string, string>;
+    /** Version of the redaction rules applied to this run. */
+    redactionVersion?: string;
+    /** Parent run in a nested build workflow. A builder run's children are
+     *  app-build runs; those children are app-runtime runs. */
+    parentRunId?: string;
+    /** Stable project identifier — groups runs across chats + sessions. */
+    projectId?: string;
+    /** Chat/conversation identifier within a project. */
+    chatId?: string;
+    /** Layer classification — hint for aggregation; not enforced. */
+    layer?: RunLayer;
+    startedAt: number;
+    endedAt?: number;
+    status: RunStatus;
+    outcome?: RunOutcome$1;
+    budget?: BudgetSpec;
+    /** Free-form labels for downstream grouping. */
+    tags?: Record<string, string>;
+}
+type SpanKind = 'agent' | 'llm' | 'tool' | 'retrieval' | 'judge' | 'sandbox' | 'custom';
+type SpanStatus = 'ok' | 'error';
+interface SpanBase {
+    spanId: string;
+    parentSpanId?: string;
+    runId: string;
+    kind: SpanKind;
     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>;
+    startedAt: number;
+    endedAt?: number;
+    status?: SpanStatus;
+    error?: string;
+    /** Anything not covered by typed fields. Kept deliberately free-form. */
+    attributes?: Record<string, unknown>;
+}
+interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    tokens?: number;
+    /** Multi-modal content descriptors; blobs themselves live in Artifacts. */
+    images?: Array<{
+        artifactId?: string;
+        url?: string;
+        mime?: string;
+    }>;
+}
+interface LlmSpan extends SpanBase {
+    kind: 'llm';
+    model: string;
+    messages: Message[];
+    output?: string;
+    inputTokens?: number;
+    /** All generated tokens, including the reasoning subset when present. */
+    outputTokens?: number;
+    cachedTokens?: number;
+    cacheWriteTokens?: number;
+    /** Reasoning-token subset of `outputTokens`. */
+    reasoningTokens?: number;
+    costUsd?: number;
+    finishReason?: string;
+}
+interface ToolSpan extends SpanBase {
+    kind: 'tool';
+    toolName: string;
+    args: unknown;
+    /** False when the source observed the call but did not capture its arguments. */
+    argsCaptured?: boolean;
+    result?: unknown;
+    latencyMs?: number;
 }
+interface RetrievalSpan extends SpanBase {
+    kind: 'retrieval';
+    query: string;
+    hits: Array<{
+        docId: string;
+        score: number;
+        content?: string;
+    }>;
+}
+interface JudgeSpan extends SpanBase {
+    kind: 'judge';
+    judgeId: string;
+    /** Span this judgment applies to. */
+    targetSpanId: string;
+    dimension: string;
+    /** Numeric score (free-range; interpretation up to the judge). */
+    score: number;
+    rationale?: string;
+    evidence?: string;
+}
+interface SandboxSpan extends SpanBase {
+    kind: 'sandbox';
+    image?: string;
+    command?: string;
+    exitCode?: number;
+    testsTotal?: number;
+    testsPassed?: number;
+    stdoutHash?: string;
+    stderrHash?: string;
+    /** Duration in ms; the harness fills this explicitly (endedAt - startedAt may miss setup). */
+    wallMs?: number;
+}
+interface GenericSpan extends SpanBase {
+    kind: 'agent' | 'custom';
+}
+type Span = LlmSpan | ToolSpan | RetrievalSpan | JudgeSpan | SandboxSpan | GenericSpan;
+type EventKind = 'log' | 'error' | 'budget_decrement' | 'budget_breach' | 'state_mutation' | 'policy_violation' | 'redaction_applied' | 'custom';
+interface TraceEvent {
+    eventId: string;
+    runId: string;
+    spanId?: string;
+    kind: EventKind;
+    timestamp: number;
+    payload: Record<string, unknown>;
+}
+interface BudgetLedgerEntry {
+    runId: string;
+    dimension: keyof BudgetSpec;
+    limit: number;
+    consumed: number;
+    remaining: number;
+    timestamp: number;
+    breached: boolean;
+    /** Span that triggered this entry, if any. */
+    spanId?: string;
+}
+interface Artifact {
+    artifactId: string;
+    runId: string;
+    spanId?: string;
+    contentType: string;
+    sizeBytes: number;
+    /** sha256 in hex. */
+    hash: string;
+    /** External storage URL (R2, S3, filesystem path). */
+    storageUrl?: string;
+    /** Inline content for small blobs — keep under ~64KB. */
+    inlineContent?: string;
+}
+type FailureClass = 'success' | 'reasoning_error' | 'tool_selection_error' | 'tool_argument_error' | 'tool_recovery_failure' | 'hallucination' | 'instruction_following' | 'safety_refusal_miss' | 'policy_violation' | 'budget_exceeded' | 'format_drift' | 'permission_escalation' | 'pii_leak' | 'cost_overrun' | 'timeout' | 'sandbox_failure' | 'missing_user_data' | 'missing_domain_data' | 'missing_codebase_context' | 'missing_runtime_context' | 'missing_credentials' | 'missing_integration_connection' | 'missing_integration_scope' | 'integration_approval_required' | 'integration_auth_expired' | 'integration_provider_failure' | 'bad_integration_manifest' | 'unsafe_integration_write_denied' | 'stale_external_data' | 'bad_retrieval' | 'insufficient_evidence' | 'contradictory_evidence' | 'ambiguous_user_intent' | 'knowledge_readiness_blocked' | 'unknown';
+declare const FAILURE_CLASSES: readonly FailureClass[];
+declare function isLlmSpan(s: Span): s is LlmSpan;
+declare function isToolSpan(s: Span): s is ToolSpan;
+declare function isRetrievalSpan(s: Span): s is RetrievalSpan;
+declare function isJudgeSpan(s: Span): s is JudgeSpan;
+declare function isSandboxSpan(s: Span): s is SandboxSpan;
+
 /**
- * Project one parsed OTLP-JSONL object to `ProjectedOtlpSpan`, or `null`
- * when the line is missing the mandatory `trace_id` + `span_id`.
+ * Paper-grade RunRecord schema + runtime validator.
+ *
+ * Every run that participates in a promotion gate, paper table, or
+ * researcher loop SHOULD be recorded as a `RunRecord`. The mandatory
+ * fields are exactly those the paper "Two Loops, Three Roles" requires
+ * for reproducibility: who/what/when/cost/seed/hash, plus the search vs
+ * holdout split tag and either a `searchScore` or a `holdoutScore`.
+ *
+ * This is intentionally NOT a replacement for the rich `Run` /
+ * `ProposeReviewReport` / `ScenarioResult` types already in the
+ * package. Those are runtime structures with full provenance. A
+ * `RunRecord` is the analysis-time projection — the JSON-friendly
+ * row you'd put in a parquet file or paste into a notebook.
+ *
+ * Validate at the boundary:
+ *
+ *   const rec = validateRunRecord(rawJson)         // throws on missing
+ *   const ok  = isRunRecord(rawJson)               // boolean check
+ *   const rec = parseRunRecordSafe(rawJson)        // { ok, value | error }
+ *
+ * The validator runs in pure TS — zod is intentionally NOT a
+ * dependency. Round-trip tested in `tests/run-record.test.ts`.
  */
-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;
+
+/** Search/dev/holdout split tag. 'search' is the paper-grade alias for the
+ *  combined train+test pool that the optimizer is allowed to read. */
+type RunSplitTag = 'search' | 'dev' | 'holdout';
+interface RunTokenUsage {
+    input: number;
+    /** All generated tokens charged as output, including reasoning tokens. */
+    output: number;
+    /** Reasoning-token subset of `output`, when the provider reports it. */
+    reasoning?: number;
+    /** Prompt tokens served from a provider cache. */
+    cached?: number;
+    /** Prompt tokens written into a provider cache. */
+    cacheWrite?: number;
+}
 /**
- * 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.
+ * How a run's USD amount was obtained.
+ *
+ * `costUsd` remains mandatory for wire compatibility. New producers should
+ * always populate this discriminated union so a missing bill is never
+ * mistaken for an observed zero-dollar run. For `uncaptured`, `costUsd` uses
+ * the legacy `0` sentinel while this field carries the truthful null.
  */
-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;
-
+type RunCostProvenance = {
+    kind: 'observed';
+    usd: number;
+} | {
+    kind: 'estimated';
+    usd: number;
+} | {
+    kind: 'uncaptured';
+    usd: null;
+};
+interface RunJudgeMetadata {
+    model: string;
+    promptVersion: string;
+    /** [0,1] confidence the judge declared. Constant judge confidence
+     *  across many runs is a fallback signal (see `canary.ts`). */
+    confidence: number;
+    /** True if the judge degraded to a fallback path (rules-only,
+     *  prior-call cache, etc.). The canary uses this to alert. */
+    fallback: boolean;
+}
 /**
- * `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).
+ * Per-judge / per-dimension breakdown for runs scored by an ensemble of
+ * judges over a multi-dimensional rubric.
  *
- * 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.
+ * The collapsed `outcome.searchScore` / `holdoutScore` carries the
+ * composite the gate uses. The full breakdown belongs here so consumers
+ * can answer "which judge disagreed?", "which dimension dragged the
+ * composite down?", and "did half the panel fail?" without re-running.
  *
- * 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`.
+ * `perJudge[judgeId][dim]` is the canonical source; `perDimMean` and
+ * `composite` are convenience projections — derivable but precomputed so
+ * downstream IRR primitives (`interRaterReliability`,
+ * `corpusInterRaterAgreement`) and reporters don't pay the same
+ * aggregation twice.
  *
- * 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.
+ * Fail-loud discipline: judges that errored out land in `failedJudges`
+ * by id. A missing key in `perJudge` is ambiguous (silent zero vs not
+ * run); the explicit list makes a partial-failure recorded as such.
  */
-
-interface OtlpToRunRecordsOptions {
-    /** Logical experiment grouping for every produced record. */
+interface JudgeScoresRecord {
+    /** Per-judge per-dimension scores. `{ "kimi-k2.6": { helpfulness: 0.8, clarity: 0.7 }, ... }`. */
+    perJudge: Record<string, Record<string, number>>;
+    /** Per-dim mean across judges. Convenience — derivable from `perJudge`. */
+    perDimMean: Record<string, number>;
+    /** Composite mean across all dims and judges. Mirrors the score
+     *  the gate sees on `outcome.searchScore` / `holdoutScore`. */
+    composite: number;
+    /** Judges that errored or returned an unparseable verdict. Recorded
+     *  by id (e.g. `['glm-5.1']`) so a partial-failure case is explicit,
+     *  not inferred from missing keys in `perJudge`. */
+    failedJudges?: string[];
+    /** Free-form notes the judges emitted (joined across judges or
+     *  first-judge only — consumer's choice). */
+    notes?: string;
+}
+interface RunOutcome {
+    /** Score on the search/optimization split. Optional because a
+     *  holdout-only evaluation only fills `holdoutScore`. */
+    searchScore?: number;
+    /** Score on the held-out split. Optional because a search-only run
+     *  only fills `searchScore`. At least one must be present. */
+    holdoutScore?: number;
+    /** Bag of any other metric the run produced — judge dimensions,
+     *  pass/fail counters, latency stats, etc. Numeric only — keeps
+     *  reporters honest. */
+    raw: Record<string, number>;
+    /** Per-judge / per-dim breakdown. Consumers writing ensemble
+     *  judgements populate this; substrate primitives like
+     *  `interRaterReliability` and `corpusInterRaterAgreement` accept
+     *  these records as input. Optional — single-judge or scalar-only
+     *  runs leave it unset. */
+    judgeScores?: JudgeScoresRecord;
+    /** Authenticity / realness verdict — did the run build the REAL thing on the
+     *  intended infra, or fake it (see `./authenticity`)? Optional: only domains
+     *  with an authenticity config populate it. Carried in the corpus so the
+     *  flywheel / off-policy learning can optimize for real completion, not gamed
+     *  pass-rate. `score` is 0-1; `gated` is the anti-Goodhart flag — a gated run
+     *  must not count as a real success regardless of `score`. */
+    realness?: {
+        score: number;
+        gated: boolean;
+        reason?: string;
+    };
+}
+/**
+ * Mandatory paper-grade fields for a single evaluation run. Optional
+ * fields are extension points; mandatory fields throw if missing.
+ *
+ * Hash discipline:
+ *   - `promptHash` is the sha256 of the EFFECTIVE prompt sent to the
+ *     model (after any steering bundle merge).
+ *   - `configHash` is the sha256 of the effective run config (model,
+ *     temperature, tools, judges, splits). The pair (promptHash,
+ *     configHash) uniquely identifies an experiment cell.
+ *
+ * Model snapshot discipline:
+ *   - `model` MUST encode a snapshot version. Bare aliases like
+ *     `claude-sonnet-4` or `gpt-4o` are banned — they remap silently.
+ *     Use `claude-sonnet-4-6@2025-04-15` or `gpt-4o-2024-11-20`.
+ */
+interface RunRecord {
+    /** UUID for the run. */
+    runId: string;
+    /** Logical experiment grouping (a treatment vs a baseline within
+     *  the same sweep should share `experimentId`). */
     experimentId: string;
-    /** Candidate (variant) id — the surface these traces exercised. The
-     *  bench passes the proposer label here so `compareProposers` can pair rows. */
+    /** Stable identifier for the candidate (variant) being run. The
+     *  promotion gate compares two `candidateId`s on matched items. */
     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;
+    /** RNG seed for the run. Always recorded — silent re-seeding is
+     *  the most common cause of non-reproducible numbers. */
+    seed: number;
+    /** Model identifier WITH snapshot version. */
     model: string;
-    startTime: string;
-    endTime: string;
+    /** sha256 of the effective prompt (post-steering). */
+    promptHash: string;
+    /** sha256 of the effective config. */
+    configHash: string;
+    /** Git SHA the harness was run from. */
+    commitSha: string;
+    /** End-to-end wall-clock duration in milliseconds. */
     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;
+    /** Time spent queued before execution started, if known. */
+    queueMs?: number;
+    /** Total USD cost. Mandatory — runs without a cost number are
+     *  unbounded by definition and must not be admitted into the gate.
+     *  `0` is retained as the compatibility sentinel for an uncaptured amount;
+     *  inspect `costProvenance` before treating it as observed. */
+    costUsd: number;
+    /** Observed, model-priced estimate, or genuinely uncaptured USD amount.
+     *  Optional only so existing serialized RunRecords remain valid. */
+    costProvenance?: RunCostProvenance;
+    /** Token usage breakdown. */
+    tokenUsage: RunTokenUsage;
+    /** Judge-side metadata, if a judge was used. */
+    judgeMetadata?: RunJudgeMetadata;
+    /** Per-split scores + raw bag. */
+    outcome: RunOutcome;
+    /** Canonical, cross-agent failure class drawn from the shared
+     *  `FAILURE_CLASSES` taxonomy. This is the aggregation key that makes
+     *  "which failure dominates across the whole fleet" answerable in ONE
+     *  vocabulary — every agent classifies against the same enum. Producers
+     *  set it via the substrate classifier; leave unset only when the failure
+     *  genuinely can't be classified. */
+    failureClass?: FailureClass;
+    /** Free-form domain-specific failure detail, scoped UNDER `failureClass`
+     *  (e.g. failureClass='tool_recovery_failure', failureMode='forge_build_unsatisfied').
+     *  The within-agent drill-down; `failureClass` is the cross-agent key. */
+    failureMode?: string;
+    /** Which split this run was drawn from. */
+    splitTag: RunSplitTag;
     /**
-     * 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.
+     * Stable scenario identifier the run was scored against. Optional for
+     * backwards compatibility, but **strongly recommended**: every primitive
+     * that pairs runs by scenario (preferences, paired stats, BT tournament)
+     * keys on this. The campaign artifact populates it canonically; legacy
+     * runs without it fall back to inference from `outcome.raw.scenario_id`
+     * or `experimentId`.
      */
-    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);
+    scenarioId?: string;
+    /**
+     * Canonical identity for the agent profile cell that produced this row:
+     * profile artifact hash plus optional harness/model/prompt/reporting
+     * dimensions. Use `agentProfile.cellId` to group persona sweeps and
+     * longitudinal reports by the complete source profile, not by a loose
+     * candidate label or opaque config hash.
+     */
+    agentProfile?: AgentProfileCell;
 }
 
 /**
- * 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
+ * Provider response and SSE usage extraction.
  *
- * 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`.
+ * Missing usage returns `null`; reported zeroes and cache-only activity remain
+ * distinguishable from absent telemetry.
  */
-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;
+type ExtractedUsage = RunTokenUsage;
+type SseUsageMode = 'cumulative' | 'delta';
+interface ExtractUsageFromSseOptions {
+    /** Provider usage events are cumulative snapshots unless explicitly marked as deltas. */
+    mode?: SseUsageMode;
 }
 /**
- * Pull `{ input, output, cached? }` from a parsed chat-completions response
+ * Pull `{ input, output, cached?, cacheWrite? }` from a parsed 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.
+ * the usage object. Returns null only when none of those categories is present.
  */
 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).
+ * Extract token usage from a complete SSE response body using the shared SSE
+ * frame parser. Cumulative snapshots are the fail-safe default because summing
+ * them inflates billing; callers with explicit delta events opt into `mode: 'delta'`.
  */
-declare function extractUsageFromSse(text: string): ExtractedUsage | null;
+declare function extractUsageFromSse(text: string, options?: ExtractUsageFromSseOptions): 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>;
+declare function extractUsageFromResponse(response: Response, sseOptions?: ExtractUsageFromSseOptions): 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.
+ * Wrap a provider `fetch` and record request, response, and error events.
+ *
+ * The returned value is a plain `typeof fetch`. Capture is best-effort by
+ * default; set `failClosed` when telemetry loss must stop the provider call.
  */
 
 interface CaptureFetchContext {
@@ -706,19 +814,419 @@ interface CaptureFetchOptions {
      * unless `failClosed` is set.
      */
     onUsage?: (usage: ExtractedUsage, ctx: CaptureFetchContext) => void;
+    /** How repeated SSE usage events should be reconciled. Default `cumulative`. */
+    sseUsageMode?: SseUsageMode;
 }
 declare function captureFetchToRawSink(fetch: typeof globalThis.fetch, sink: RawProviderSink, ctx: CaptureFetchContext, opts?: CaptureFetchOptions): typeof globalThis.fetch;
 
+interface RunFilter {
+    scenarioId?: string;
+    variantId?: string;
+    status?: RunStatus;
+    since?: number;
+    until?: number;
+    tag?: {
+        key: string;
+        value: string;
+    };
+    parentRunId?: string;
+    projectId?: string;
+    chatId?: string;
+    layer?: RunLayer;
+}
+interface SpanFilter {
+    runId?: string;
+    parentSpanId?: string;
+    kind?: SpanKind;
+    name?: string;
+    toolName?: string;
+    judgeId?: string;
+    since?: number;
+    until?: number;
+}
+interface EventFilter {
+    runId?: string;
+    spanId?: string;
+    kind?: EventKind;
+    since?: number;
+    until?: number;
+}
+interface TraceStore {
+    appendRun(run: Run): Promise<void>;
+    updateRun(runId: string, patch: Partial<Run>): Promise<void>;
+    appendSpan(span: Span): Promise<void>;
+    updateSpan(spanId: string, patch: Partial<Span>): Promise<void>;
+    appendEvent(event: TraceEvent): Promise<void>;
+    appendArtifact(artifact: Artifact): Promise<void>;
+    appendBudgetEntry(entry: BudgetLedgerEntry): Promise<void>;
+    getRun(runId: string): Promise<Run | undefined>;
+    listRuns(filter?: RunFilter): Promise<Run[]>;
+    spans(filter?: SpanFilter): Promise<Span[]>;
+    events(filter?: EventFilter): Promise<TraceEvent[]>;
+    budget(runId: string): Promise<BudgetLedgerEntry[]>;
+    artifacts(runId: string): Promise<Artifact[]>;
+}
+declare class InMemoryTraceStore implements TraceStore {
+    private runs;
+    private allSpans;
+    private allEvents;
+    private allArtifacts;
+    private allBudget;
+    appendRun(run: Run): Promise<void>;
+    updateRun(runId: string, patch: Partial<Run>): Promise<void>;
+    appendSpan(span: Span): Promise<void>;
+    updateSpan(spanId: string, patch: Partial<Span>): Promise<void>;
+    appendEvent(event: TraceEvent): Promise<void>;
+    appendArtifact(artifact: Artifact): Promise<void>;
+    appendBudgetEntry(entry: BudgetLedgerEntry): Promise<void>;
+    getRun(runId: string): Promise<Run | undefined>;
+    listRuns(filter?: RunFilter): Promise<Run[]>;
+    spans(filter?: SpanFilter): Promise<Span[]>;
+    events(filter?: EventFilter): Promise<TraceEvent[]>;
+    budget(runId: string): Promise<BudgetLedgerEntry[]>;
+    artifacts(runId: string): Promise<Artifact[]>;
+}
+interface FileSystemTraceStoreOptions {
+    dir: string;
+    /** Roll over NDJSON files when they exceed this size in bytes. Default 32 MB. */
+    maxBytes?: number;
+}
+declare class FileSystemTraceStore implements TraceStore {
+    private dir;
+    private maxBytes;
+    /** Lazy in-memory index for queries — populated on first read. */
+    private index?;
+    /** Memoized index build — concurrent first reads share one build, and an
+     *  append racing an in-flight load awaits this so its row isn't lost. */
+    private indexPromise?;
+    /** Strictly-increasing rollover stamp. Date.now() alone collides when two
+     *  rollovers land in the same millisecond, overwriting a rolled file. */
+    private lastRolloverStamp;
+    /**
+     * Per-file append serialization. stat → conditional-rename → appendFile is a
+     * read-modify-write on the active file; without a lock two concurrent appends
+     * to the same `name` can both pass the size check (exceeding maxBytes) or one
+     * can append to a file the other just renamed away. Each entry chains the
+     * next append behind the prior one for that file.
+     */
+    private appendLocks;
+    constructor(options: FileSystemTraceStoreOptions);
+    private ensureDir;
+    private append;
+    private appendLocked;
+    private insertInto;
+    private load;
+    private buildIndex;
+    appendRun(run: Run): Promise<void>;
+    updateRun(runId: string, patch: Partial<Run>): Promise<void>;
+    appendSpan(span: Span): Promise<void>;
+    updateSpan(spanId: string, patch: Partial<Span>): Promise<void>;
+    appendEvent(event: TraceEvent): Promise<void>;
+    appendArtifact(artifact: Artifact): Promise<void>;
+    appendBudgetEntry(entry: BudgetLedgerEntry): Promise<void>;
+    getRun(runId: string): Promise<Run | undefined>;
+    listRuns(filter?: RunFilter): Promise<Run[]>;
+    spans(filter?: SpanFilter): Promise<Span[]>;
+    events(filter?: EventFilter): Promise<TraceEvent[]>;
+    budget(runId: string): Promise<BudgetLedgerEntry[]>;
+    artifacts(runId: string): Promise<Artifact[]>;
+}
+
 /**
- * OTEL span exporter — streams spans to an OTLP/HTTP collector.
+ * TraceEmitter — hierarchical span builder that auto-parents using an
+ * internal stack. One emitter per Run; emitters do NOT share state.
  *
- * 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.
+ * Convenience methods (`llm`, `tool`, `retrieval`, `judge`, `sandbox`)
+ * return a `SpanHandle` with `.end()` / `.fail()` so callers don't
+ * have to thread spanIds manually. For async workflows that can't use
+ * the stack (e.g. fan-out parallel calls), pass `parentSpanId`
+ * explicitly.
  */
 
-interface OtelExportConfig {
+interface SpanHandle<S extends Span = Span> {
+    span: S;
+    end(patch?: Partial<S>): Promise<void>;
+    fail(error: string | Error, patch?: Partial<S>): Promise<void>;
+}
+interface RunCompleteHookContext {
+    runId: string;
+    emitter: TraceEmitter;
+    store: TraceStore;
+    /** Outcome the caller passed to `endRun` (undefined for `abortRun`). */
+    outcome?: RunOutcome$1;
+    /** Final run status. */
+    status: 'completed' | 'failed' | 'aborted';
+}
+type RunCompleteHook = (ctx: RunCompleteHookContext) => Promise<void> | void;
+interface TraceEmitterOptions {
+    runId?: string;
+    /** Inject a clock for deterministic tests. */
+    now?: () => number;
+    /** Inject an id generator for deterministic tests. */
+    id?: () => string;
+    /**
+     * Hooks fired after `endRun` / `abortRun` writes the final run state.
+     * Designed for trace-analyst auto-execution, integrity assertions, and
+     * outbound notifications. Hooks run sequentially in the order supplied.
+     *
+     * By default a hook that throws is swallowed and logged as a `note` event
+     * on the run — auto-orchestration must not crash the underlying flow.
+     * Set `hookErrors: 'throw'` to propagate.
+     */
+    onRunComplete?: RunCompleteHook[];
+    /** `'swallow'` (default) | `'throw'`. */
+    hookErrors?: 'swallow' | 'throw';
+}
+declare class TraceEmitter {
+    private store;
+    private stack;
+    private _runId;
+    private now;
+    private id;
+    private hooks;
+    private hookErrors;
+    constructor(store: TraceStore, options?: TraceEmitterOptions);
+    get runId(): string;
+    get traceStore(): TraceStore;
+    /** Append a hook after construction (e.g. attach the trace analyst). */
+    addRunCompleteHook(hook: RunCompleteHook): void;
+    /**
+     * Begin a Run.
+     *
+     * `scenarioId` is required on the persisted Run shape — every Run downstream
+     * gets a non-empty scenarioId so filters and aggregations stay simple — but
+     * the INPUT here accepts it as optional. When omitted, startRun substitutes
+     * a sensible default (`run.layer ?? run.tags?.['kind'] ?? 'runtime'`) so
+     * runtime / operator / meta-eval runs that have no curated-scenario corpus
+     * to anchor to don't have to invent placeholder strings at the call site.
+     */
+    startRun(run: Omit<Run, 'runId' | 'scenarioId' | 'startedAt' | 'status'> & {
+        scenarioId?: string;
+    }): Promise<Run>;
+    endRun(outcome?: RunOutcome$1): Promise<void>;
+    abortRun(reason: string): Promise<void>;
+    private runHooks;
+    span<S extends Span = Span>(init: {
+        kind: SpanKind;
+        name: string;
+        parentSpanId?: string;
+        attributes?: Record<string, unknown>;
+    } & Partial<Omit<S, 'spanId' | 'runId' | 'startedAt' | 'kind' | 'name'>>): Promise<SpanHandle<S>>;
+    private handle;
+    private pop;
+    llm(init: Omit<LlmSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<LlmSpan>>;
+    tool(init: Omit<ToolSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<ToolSpan>>;
+    retrieval(init: Omit<RetrievalSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<RetrievalSpan>>;
+    recordJudge(verdict: Omit<JudgeSpan, 'spanId' | 'runId' | 'kind' | 'startedAt' | 'endedAt'>): Promise<JudgeSpan>;
+    sandbox(init: Omit<SandboxSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>): Promise<SpanHandle<SandboxSpan>>;
+    emit(event: {
+        kind: EventKind;
+        spanId?: string;
+        payload?: Record<string, unknown>;
+    }): Promise<TraceEvent>;
+    recordBudget(entry: Omit<BudgetLedgerEntry, 'runId' | 'timestamp'> & {
+        timestamp?: number;
+    }): Promise<BudgetLedgerEntry>;
+    recordArtifact(artifact: Omit<Artifact, 'artifactId' | 'runId'>): Promise<Artifact>;
+    /**
+     * Runs `fn` inside a span; auto-ends on success, auto-fails on throw.
+     * Returns the fn's return value. Use this for the 95% case.
+     */
+    within<T>(init: Parameters<TraceEmitter['span']>[0], fn: (handle: SpanHandle) => Promise<T>): Promise<T>;
+}
+/** Helper to build an LLM span handle args object from a provider-shaped response. */
+declare function llmSpanFromProvider(args: {
+    name?: string;
+    model: string;
+    messages: Message[];
+    output: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cachedTokens?: number;
+        cacheWriteTokens?: number;
+        reasoningTokens?: number;
+    };
+    costUsd?: number;
+    finishReason?: string;
+}): Omit<LlmSpan, 'spanId' | 'runId' | 'kind' | 'startedAt'>;
+
+/**
+ * Run-completion integrity check — at end of run, verify the expected event
+ * types were actually captured. The point is the launch-review failure mode:
+ * a run *appears* successful but the raw provider events were never written,
+ * so a downstream reviewer can't reconstruct what happened.
+ *
+ * Pattern:
+ *
+ *   const report = await assertRunCaptured(store, runId, {
+ *     llmSpansMin: 1,
+ *     judgeSpansMin: 1,
+ *     rawSink: providerSink,                  // must have ≥ 1 event for this run
+ *     requireRawCoverageOfLlmSpans: true,     // every llm span has matching raw events
+ *   })
+ *   if (!report.ok) throwIfRunIncomplete(report)  // or mark run failed and continue
+ *
+ * The function is read-only on the store and returns a structured report;
+ * the caller chooses the failure mode (throw, mark run failed, log warning).
+ * `throwIfRunIncomplete` is the convenient strict mode.
+ */
+
+interface RunIntegrityExpectations {
+    /** Minimum LLM span count. Default 0 (no requirement). */
+    llmSpansMin?: number;
+    /** Minimum judge span count. Default 0. */
+    judgeSpansMin?: number;
+    /** Minimum tool span count. Default 0. */
+    toolSpansMin?: number;
+    /**
+     * Raw provider sink to consult for capture verification. When present,
+     * the check requires at least one raw event for the run.
+     */
+    rawSink?: RawProviderSink;
+    /** Minimum raw provider event count. Default 0; ignored when `rawSink` absent. */
+    rawProviderEventsMin?: number;
+    /**
+     * Every LLM span must have at least one matching raw `request` event
+     * (matched by spanId). Catches the common bug where the structured span
+     * was emitted but the raw HTTP capture was wired to a different sink.
+     */
+    requireRawCoverageOfLlmSpans?: boolean;
+    /** Run outcome must be set (not null/undefined). Default false. */
+    requireOutcome?: boolean;
+}
+type RunIntegrityIssueCode = 'no_run' | 'missing_llm_spans' | 'missing_judge_spans' | 'missing_tool_spans' | 'missing_raw_events' | 'no_raw_sink' | 'orphan_llm_span' | 'missing_outcome';
+interface RunIntegrityIssue {
+    code: RunIntegrityIssueCode;
+    message: string;
+    detail?: Record<string, unknown>;
+}
+interface RunIntegrityReport {
+    ok: boolean;
+    runId: string;
+    llmSpanCount: number;
+    judgeSpanCount: number;
+    toolSpanCount: number;
+    rawProviderEventCount: number;
+    /**
+     * Coverage of LLM spans by raw provider events keyed on spanId.
+     * `total` is the number of LLM spans; `covered` is the count with at
+     * least one matching `request` raw event.
+     */
+    rawSpanCoverage: {
+        covered: number;
+        total: number;
+    };
+    issues: RunIntegrityIssue[];
+}
+declare class RunIntegrityError extends CaptureIntegrityError {
+    readonly report: RunIntegrityReport;
+    constructor(report: RunIntegrityReport);
+}
+declare function assertRunCaptured(store: TraceStore, runId: string, expectations?: RunIntegrityExpectations): Promise<RunIntegrityReport>;
+/** Strict mode: throws `RunIntegrityError` when the report isn't ok. */
+declare function throwIfRunIncomplete(report: RunIntegrityReport): void;
+
+/**
+ * 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>;
+
+/** Canonical OpenInference-over-OTLP attribute names used at trace boundaries. */
+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_REASONING_TOKENS = "llm.token_count.reasoning";
+declare const LLM_CACHED_TOKENS = "llm.token_count.prompt_cache_hit";
+declare const LLM_CACHE_WRITE_TOKENS = "llm.token_count.prompt_cache_write";
+declare const LLM_COST_USD = "llm.cost_usd";
+declare const TOOL_NAME = "tool.name";
+declare const TOOL_ARGS_CAPTURED = "tool.args_captured";
+declare const TOOL_LATENCY_MS = "tool.latency_ms";
+declare const INPUT_VALUE = "input.value";
+declare const OUTPUT_VALUE = "output.value";
+
+/** Canonical OpenInference-over-OTLP attribute vocabulary used at the trace boundary. */
+
+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", ...string[], "tangle.model"];
+declare const LLM_INPUT_TOKEN_ATTR_KEYS: readonly ["llm.token_count.prompt", "inference.llm.input_tokens", "llm.input_tokens", ...string[], "tangle.tokens.in", "tokens.in"];
+declare const LLM_OUTPUT_TOKEN_ATTR_KEYS: readonly ["llm.token_count.completion", "inference.llm.output_tokens", "llm.output_tokens", ...string[], "tangle.tokens.out", "tokens.out"];
+/** Reasoning-token subset of output, when a producer exposes it separately. */
+declare const LLM_REASONING_TOKEN_ATTR_KEYS: readonly ["llm.token_count.reasoning", "inference.llm.reasoning_tokens", "llm.reasoning_tokens", "gen_ai.usage.reasoning_tokens", "gen_ai.usage.reasoning_output_tokens", "reasoning_tokens", "reasoning_output_tokens", "tangle.tokens.reasoning", "gen_ai.usage.output_tokens_details.reasoning_tokens", "gen_ai.usage.completion_tokens_details.reasoning_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", "gen_ai.usage.prompt_tokens_details.cached_tokens", "gen_ai.usage.input_tokens_details.cached_tokens", "gen_ai.usage.cache_read_tokens", "gen_ai.usage.cache_read_input_tokens", "cache_read_tokens", "cache_read_input_tokens", "input_cache_read", "tangle.tokens.cached"];
+declare const LLM_CACHE_WRITE_TOKEN_ATTR_KEYS: readonly ["llm.token_count.prompt_cache_write", "inference.llm.cache_write_tokens", "llm.cache_write_tokens", "gen_ai.usage.cache_creation_tokens", "gen_ai.usage.cache_creation_input_tokens", "cache_creation_tokens", "cache_creation_input_tokens", "input_cache_creation", "tangle.tokens.cache_write"];
+declare const LLM_COST_ATTR_KEYS: readonly ["llm.cost_usd", "inference.llm.cost.total", "llm.cost.total", "gen_ai.usage.cost", "gen_ai.usage.cost_usd", "tangle.cost.usd", "cost.usd", "cost"];
+/** Explicit run-total cost keys safe to preserve on an untyped span. */
+declare const RUN_COST_ATTR_KEYS: readonly ["tangle.cost.usd", "cost.usd"];
+declare const TOOL_NAME_ATTR_KEYS: readonly ["tool.name", "inference.tool.name"];
+type ToolSpanOtlpInput = Pick<ToolSpan, 'toolName' | 'args' | 'argsCaptured' | 'result' | 'latencyMs'>;
+declare function applyToolSpanOtlpAttributes(attributes: Record<string, unknown>, span: ToolSpanOtlpInput): void;
+declare function traceSpanKindToOpenInferenceKind(kind: string): string;
+
+/**
+ * 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. */
@@ -753,6 +1261,9 @@ interface ExportableSpan {
     model?: string;
     inputTokens?: number;
     outputTokens?: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+    cacheWriteTokens?: number;
     costUsd?: number;
     tool?: ToolSpanOtlpInput;
     attributes?: Record<string, unknown>;
@@ -790,6 +1301,38 @@ declare function otelRunCompleteHook(exporter: OtelExporter): RunCompleteHook;
  */
 declare function createOtelTracingStore(inner: TraceStore, exporter: OtelExporter, traceId: string): TraceStore;
 
+/**
+ * Typed query helpers over TraceStore.
+ *
+ * Not a full SQL engine — a minimal, composable set of operators that
+ * cover the canned-pipeline use cases. For ad-hoc analytics, persist to
+ * NDJSON and point DuckDB at it; the schema is stable so external SQL
+ * tooling works out of the box.
+ */
+
+declare function runsForScenario(store: TraceStore, scenarioId: string): Promise<Run[]>;
+declare function llmSpans(store: TraceStore, runId?: string): Promise<LlmSpan[]>;
+declare function toolSpans(store: TraceStore, runId?: string, toolName?: string): Promise<ToolSpan[]>;
+/** Query judge-kind spans from the trace store, optionally scoped to a single run. */
+declare function judgeSpans(store: TraceStore, runId?: string): Promise<JudgeSpan[]>;
+/** Group spans by any key selector. */
+declare function groupBy<T, K extends string | number>(items: T[], key: (t: T) => K): Map<K, T[]>;
+/** Hash tool arguments to an orderless-key-stable string for de-duplication. */
+declare function argHash(args: unknown): string;
+/** Whether argument-based comparisons are valid for this tool call. */
+declare function hasCapturedToolArgs(span: ToolSpan): boolean;
+/** Sum an LLM-span array into aggregate token + cost. */
+declare function aggregateLlm(spans: LlmSpan[]): {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+};
+/** Pick the outcome's failure class when present, else derive 'success' from run status. */
+declare function runFailureClass(run: Run): FailureClass;
+
 /**
  * Redaction — remove PII / secrets from trace payloads before persist.
  *
@@ -907,122 +1450,852 @@ interface TraceStoreToOtlpOptions {
 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.
+ * Shared types for the trace-analyst module.
  *
- * `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.
+ * Wire format. The store interface speaks `OtlpSpanLike` rows — one JSONL
+ * line per span, OTLP-shaped. We do NOT depend on a specific tracing
+ * vendor at the type level. Adapter
+ * layers map upstream shapes onto this interface.
  *
- * Three use cases this primitive enables:
+ * Design constraint. Every read operation that can return arbitrary
+ * payload must carry a byte budget so the agent's tool result stays
+ * bounded regardless of input trace size. Oversized responses
+ * substitute a deterministic summary instead of bytes — see
+ * `ViewTraceOversized`.
+ */
+/** OTLP span kind (subset we actually use). */
+type TraceAnalystSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'GUARDRAIL' | 'SPAN' | 'UNKNOWN';
+type TraceAnalystSpanStatus = 'OK' | 'ERROR' | 'UNSET';
+/** Subset of OTLP span fields the analyst exposes to the agent. The
+ *  store's job is to project upstream's full span shape down to this
+ *  view — the analyst never sees vendor extensions directly. */
+interface TraceAnalystSpan {
+    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;
+    service_name: string | null;
+    agent_name: string | null;
+    model_name: string | null;
+    tool_name: string | null;
+    /** Raw JSON-serialisable attribute map. May contain large strings;
+     *  callers must respect the per-attribute byte cap. */
+    attributes: Record<string, unknown>;
+}
+interface TraceAnalystTraceSummary {
+    trace_id: string;
+    service_name: string | null;
+    agent_name: string | null;
+    span_count: number;
+    has_errors: boolean;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    raw_jsonl_bytes: number;
+    models: string[];
+    tools: string[];
+}
+interface TraceAnalystFilters {
+    /** Restrict to traces that contain at least one error span. */
+    has_errors?: boolean;
+    /** Match if any span's `service.name` is in this list. */
+    service_names?: string[];
+    /** Match if any span's `agent.name` is in this list. */
+    agent_names?: string[];
+    /** Match if any LLM span's `llm.model_name` is in this list. */
+    model_names?: string[];
+    /** Match if any tool span's `tool.name` is in this list. */
+    tool_names?: string[];
+    /** ISO-8601 lower bound on the trace's earliest start time. */
+    start_time_after?: string;
+    /** ISO-8601 upper bound on the trace's earliest start time. */
+    start_time_before?: string;
+    /** Single regex applied to raw JSONL bytes for the trace. Opt-in;
+     *  expensive on large datasets. Use the indexed filters above first. */
+    regex_pattern?: string;
+}
+/** One distinct error signature across the dataset — the deterministic unit of
+ *  failure coverage. Signatures normalize volatile tokens (digits, hex/uuids,
+ *  paths, durations) out of the span `status_message` so semantically identical
+ *  failures collapse into one cluster. An analyst that accounts for every
+ *  cluster has, by construction, covered every distinct failure mode. */
+interface ErrorCluster {
+    /** Normalized status_message — the cluster key. */
+    signature: string;
+    /** A verbatim, un-normalized exemplar message (for exact-string citation). */
+    status_message_sample: string;
+    /** The span name that most often carries this signature, if any. */
+    span_name: string | null;
+    /** The tool that most often carries this signature, if any. */
+    tool_name: string | null;
+    trace_count: number;
+    span_count: number;
+    /** trace_count / total error traces in the matched set (0..1). */
+    prevalence: number;
+    /** Real trace ids carrying this signature (capped), passable to view/search. */
+    exemplar_trace_ids: string[];
+    /** Real span ids carrying this signature (capped). */
+    exemplar_span_ids: string[];
+}
+interface DatasetOverview {
+    total_traces: number;
+    raw_jsonl_bytes: number;
+    services: string[];
+    agents: string[];
+    models: string[];
+    tool_names: string[];
+    /** Up to 20 real trace ids the agent may pass to view/search tools. */
+    sample_trace_ids: string[];
+    errors: {
+        trace_count: number;
+        span_count: number;
+    };
+    /** The COMPLETE deterministic error-signature population, sorted by
+     *  trace_count desc. This is the failure-coverage checklist: an analysis is
+     *  complete only when every cluster here is accounted for. Empty when the
+     *  matched set has no error spans. */
+    error_clusters: ErrorCluster[];
+    time_range: {
+        earliest: string;
+        latest: string;
+    } | null;
+}
+interface QueryTracesPage {
+    traces: TraceAnalystTraceSummary[];
+    total: number;
+    has_more: boolean;
+}
+/** Full-trace view. When the response would exceed the per-call byte
+ *  budget, `oversized` is populated INSTEAD of `spans` so the agent
+ *  knows to switch to `searchTrace` / `viewSpans`. */
+interface ViewTraceResult {
+    trace_id: string;
+    spans?: TraceAnalystSpan[];
+    oversized?: ViewTraceOversized;
+}
+interface ViewTraceOversized {
+    span_count: number;
+    /** Names with their counts, sorted desc. Capped at 20 entries. */
+    top_span_names: Array<[string, number]>;
+    /** Largest single span body (bytes after attribute-cap projection). */
+    span_response_bytes_max: number;
+    error_span_count: number;
+}
+interface ViewSpansResult {
+    trace_id: string;
+    spans: TraceAnalystSpan[];
+    /** Number of requested span ids that were not found in the trace. */
+    missing_span_ids: string[];
+    /** Number of attribute fields truncated to fit the per-attribute cap. */
+    truncated_attribute_count: number;
+}
+interface SpanMatchRecord {
+    trace_id: string;
+    span_id: string;
+    span_name: string;
+    span_kind: TraceAnalystSpanKind;
+    /** JSON pointer-style path to the matched value, e.g.
+     *  `attributes."llm.input_messages"[2].content`. */
+    attribute_path: string;
+    matched_text: string;
+    context_before: string;
+    context_after: string;
+    match_offset: number;
+}
+interface SearchTraceResult {
+    trace_id: string;
+    hits: SpanMatchRecord[];
+    total_matches: number;
+    has_more: boolean;
+}
+interface SearchSpanResult {
+    trace_id: string;
+    span_id: string;
+    hits: SpanMatchRecord[];
+    total_matches: number;
+    has_more: boolean;
+}
+/** Tunable byte budgets for bounded RLM tool output. */
+interface TraceAnalystByteBudgets {
+    /** Max bytes any single tool response may emit. Hard ceiling enforced
+     *  by the store; oversized → summary. Default 150_000. */
+    perCallByteCeiling: number;
+    /** Per-attribute string truncation cap on `viewTrace` (discovery scan).
+     *  Default 4096. */
+    perAttributeViewBudget: number;
+    /** Per-attribute string truncation cap on `viewSpans` (surgical reads).
+     *  Default 16384. */
+    perAttributeSpanBudget: number;
+    /** Per-attribute cap on a single match record's `matched_text` and
+     *  context window. Default 1024. */
+    perMatchTextBudget: number;
+}
+declare const DEFAULT_TRACE_ANALYST_BUDGETS: TraceAnalystByteBudgets;
+/** Marker substituted in place of truncated string payloads. Callers
+ *  parsing tool output can detect it deterministically. */
+declare const TRACE_ANALYST_TRUNCATION_MARKER_PREFIX = "[trace-analyst truncated:";
+
+/**
+ * `TraceAnalysisStore` — read-side interface the trace-analyst calls
+ * through. Six operations, all bounded:
  *
- *   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.
+ *   - `getOverview(filters?)` — dataset rollup + sample trace ids.
+ *   - `queryTraces(filters?, limit, offset)` — paginated summaries.
+ *   - `countTraces(filters?)` — cheap count without materialisation.
+ *   - `viewTrace(trace_id, perAttrCap)` — full span list, oversized → summary.
+ *   - `viewSpans(trace_id, span_ids, perAttrCap)` — surgical span fetch.
+ *   - `searchTrace(trace_id, regex, max_matches)` — bounded regex hits.
+ *   - `searchSpan(trace_id, span_id, regex, max_matches)` — single-span search.
  *
- * 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.
+ * Multiple implementations ship in the core (`OtlpFileTraceStore`).
+ * Downstream callers can supply their own — e.g. a DuckDB-backed
+ * adapter or an in-memory adapter for tests — by implementing this
+ * interface.
+ *
+ * Filters compose with AND semantics. Empty/undefined fields impose
+ * no constraint. `regex_pattern` is the only opt-in raw-bytes scan —
+ * implementations may skip it via `count`/`overview` when not set.
  */
 
-declare class ReplayCacheMissError extends ReplayError {
-    readonly url: string;
-    readonly requestKey: string;
-    constructor(url: string, requestKey: string, message?: string);
+interface TraceAnalysisStore {
+    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;
+        /** Override per-attribute byte cap. Defaults to discovery budget. */
+        per_attribute_byte_cap?: number;
+    }): Promise<ViewTraceResult>;
+    viewSpans(opts: {
+        trace_id: string;
+        span_ids: readonly string[];
+        /** Override per-attribute byte cap. Defaults to surgical budget. */
+        per_attribute_byte_cap?: number;
+    }): Promise<ViewSpansResult>;
+    searchTrace(opts: {
+        trace_id: string;
+        regex_pattern: string;
+        /** Hard cap on matches returned. Default 50. */
+        max_matches?: number;
+    }): Promise<SearchTraceResult>;
+    searchSpan(opts: {
+        trace_id: string;
+        span_id: string;
+        regex_pattern: string;
+        max_matches?: number;
+    }): Promise<SearchSpanResult>;
 }
-interface ReplayCacheEntry {
-    request: RawProviderEvent;
-    response: RawProviderEvent;
+
+interface AnalyzeTracesInput {
+    /** The user-facing question. Domain framing belongs here, not in the
+     *  actor description. */
+    question: string;
 }
-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;
+interface AnalyzeTracesResult {
+    /** The responder's prose answer. */
+    answer: string;
+    /** Bulleted findings extracted from the responder's structured output. */
+    findings: string[];
+    /** Per-actor-turn snapshots captured via `actorTurnCallback`. */
+    turns: AnalyzeTracesTurnSnapshot[];
+    /** Total turns the actor took. */
+    turnCount: number;
+    /** Token usage by role. */
+    usage: TraceAnalystUsage;
+    /** Full system + assistant + tool message log by role. */
+    chatLog: TraceAnalystChatLog;
+    /** Prompt version that produced this run. */
+    actorPromptVersion: string;
+}
+interface TraceAnalystUsage {
+    actor: TraceAnalystUsageEntry[];
+    responder: TraceAnalystUsageEntry[];
+}
+interface TraceAnalystUsageEntry {
+    [key: string]: unknown;
+}
+interface TraceAnalystChatLog {
+    actor: TraceAnalystChatMessage[];
+    responder: TraceAnalystChatMessage[];
+}
+interface TraceAnalystChatMessage {
+    [key: string]: unknown;
+}
+interface AnalyzeTracesTurnSnapshot {
+    turn: number;
+    isError: boolean;
+    /** The JS code the actor produced for this turn. */
+    code: string;
+    /** The formatted action-log entry the actor sees on the next turn. */
+    output: string;
+    /** Provider thought (when `actorOptions.showThoughts` is true and the
+     *  provider returns it). */
+    thought?: string;
+}
+interface AnalyzeTracesOptions {
+    /** Trace data source. Pass either an OTLP-JSONL path or a custom store. */
+    source: string | TraceAnalysisStore;
+    /** Caller-provided AxAIService. */
+    ai: AxAIService;
+    /** Model id forwarded to actor + responder. */
+    model?: string;
+    /** Recursion depth. 0 = no sub-agent dispatch. Default 1. */
+    maxDepth?: number;
+    /** Maximum actor turns. Default 12. */
+    maxTurns?: number;
+    /** Maximum parallel sub-agent calls in batched llmQuery. Default 2. */
+    maxParallelSubagents?: number;
+    /** Override the actor description. */
+    actorDescription?: string;
+    /** Override the subagent description. */
+    subagentDescription?: string;
+    /** Per-turn observability hook. */
+    onTurn?: (turn: AnalyzeTracesTurnSnapshot) => void | Promise<void>;
+    /** Override max runtime characters per turn. Default 6000. */
+    maxRuntimeChars?: number;
+    /** When set, every turn's snapshot is appended to this JSONL file
+     *  immediately. If the analyst crashes mid-loop (provider 503,
+     *  network error, validator reject) the partial reasoning is still
+     *  on disk. Replay the file with the responder afterward to recover
+     *  evidence. */
+    progressLogPath?: string;
 }
 /**
- * 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.
+ * Run the trace analyst.
  *
- * The cache is the source of truth for replay; `createReplayFetch` is a
- * thin wrapper that reads from it.
+ * Throws:
+ *   - `TraceFileMissingError` if `source` is a path and doesn't exist.
+ *   - `AxAgentClarificationError` if the analyst asks for clarification.
+ *   - Provider errors (auth, rate limits) propagate from the AI service.
  */
-declare class ReplayCache {
-    private byKey;
-    private orphans;
-    private byProvider;
-    private byModel;
+declare function analyzeTraces(input: AnalyzeTracesInput, options: AnalyzeTracesOptions): Promise<AnalyzeTracesResult>;
+
+/**
+ * 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;
+
+/**
+ * `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: reconcile input, output, cache-read, and cache-write across
+ *     nested model-call wrappers without double-counting parent aggregates.
+ *   - costUsd: reconcile complete observed model-call 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;
     /**
-     * Build a cache from a sink's events. The sink must implement `list()`.
-     * Filter by `runId` / `spanId` to scope to a specific replay.
+     * 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.
      */
-    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>;
+    priceUsdPerToken?: number;
     /**
-     * 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.
+     * 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.
      */
-    lookup(requestBody: unknown): Promise<ReplayCacheEntry | 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;
 }
-interface ReplayFetchOptions {
+/** 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;
     /**
-     * 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.
+     * 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.
      */
-    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;
+    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);
+}
+
 /**
- * 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.
+ * Trace-analyst tool surface — six namespaced AxFunctions the analyst
+ * agent calls from generated JS code via `traces.<name>(...)`.
  *
- * 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.
+ * 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.
  */
-declare function createReplayFetch(cache: ReplayCache, opts?: ReplayFetchOptions): typeof fetch;
+
+interface BuildTraceAnalystToolsOpts {
+    store: TraceAnalysisStore;
+    /** Override the default sample-trace-id slot count (20). Mostly for tests. */
+    sampleTraceLimit?: number;
+}
 /**
- * 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.
+ * Build the trace-analyst function set. Pass the result into
+ * `agent(...).functions.local`.
  */
-declare function iterateRawCalls(sink: RawProviderSink, filter?: {
-    runId?: string;
-    spanId?: string;
-}): AsyncGenerator<ReplayCacheEntry>;
+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[];
+};
 
-export { AnalyzeTracesOptions, AnalyzeTracesResult, type CaptureFetchContext, type CaptureFetchOptions, DEFAULT_REDACTION_RULES, DatasetOverview, type ExportableSpan, type ExtractedUsage, type FlattenOtlpOptions, INPUT_VALUE, 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, OUTPUT_VALUE, type OtelExportConfig, type OtelExporter, type OtlpExport, OtlpFileTraceStore, type OtlpFileTraceStoreOptions, type OtlpFlatLine, type OtlpResourceSpans, type OtlpSpan, type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, type ProjectedOtlpSpan, ProviderRedactor, QueryTracesPage, REDACTION_VERSION, RawProviderEvent, RawProviderSink, type RedactionReport, type RedactionRule, ReplayCache, type ReplayCacheEntry, ReplayCacheMissError, type ReplayCacheStats, type ReplayFetchOptions, Run, RunCompleteHook, RunCompleteHookContext, SPAN_KIND_ATTR_KEYS, SearchSpanResult, SearchTraceResult, SpanNotFoundError, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS, TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_SUBAGENT_DESCRIPTION, ToolSpan, type ToolSpanOtlpInput, 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, applyToolSpanOtlpAttributes, 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, redactString, redactValue, scoreTraceInsightReadiness, stringField, tokenizeDomainWords, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };
+export { type AnalyzeTracesInput, type AnalyzeTracesOptions, type AnalyzeTracesResult, type AnalyzeTracesTurnSnapshot, type Artifact, type BudgetLedgerEntry, type BudgetSpec, type CaptureFetchContext, type CaptureFetchOptions, DEFAULT_REDACTION_RULES, DEFAULT_TRACE_ANALYST_BUDGETS, type DatasetOverview, type ErrorCluster, type EventFilter, type EventKind, type ExportableSpan, type ExtractUsageFromSseOptions, type ExtractedUsage, FAILURE_CLASSES, type FailureClass, FileSystemRawProviderSink, type FileSystemRawProviderSinkOptions, FileSystemTraceStore, type FileSystemTraceStoreOptions, type FlattenOtlpOptions, type GenericSpan, INPUT_VALUE, InMemoryRawProviderSink, type InMemoryRawProviderSinkOptions, InMemoryTraceStore, type JudgeSpan, LLM_CACHED_TOKENS, LLM_CACHED_TOKEN_ATTR_KEYS, LLM_CACHE_WRITE_TOKENS, LLM_CACHE_WRITE_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, LLM_REASONING_TOKENS, LLM_REASONING_TOKEN_ATTR_KEYS, type LlmSpan, type Message, NoopRawProviderSink, OPENINFERENCE_SPAN_KIND, OTEL_AGENT_EVAL_SCOPE, OUTPUT_VALUE, type OtelExportConfig, type OtelExporter, type OtlpExport, OtlpFileTraceStore, type OtlpFileTraceStoreOptions, type OtlpFlatLine, type OtlpResourceSpans, type OtlpSpan, type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, type ProjectedOtlpSpan, type ProviderRedactor, type QueryTracesPage, REDACTION_VERSION, RUN_COST_ATTR_KEYS, type RawProviderDirection, type RawProviderEvent, type RawProviderSink, type RawProviderSinkFilter, type RedactionReport, type RedactionRule, ReplayCache, type ReplayCacheEntry, ReplayCacheMissError, type ReplayCacheStats, type ReplayFetchOptions, type RetrievalSpan, type Run, type RunCompleteHook, type RunCompleteHookContext, type RunFilter, RunIntegrityError, type RunIntegrityExpectations, type RunIntegrityIssue, type RunIntegrityIssueCode, type RunIntegrityReport, type RunLayer, type RunOutcome$1 as RunOutcome, type RunStatus, SPAN_KIND_ATTR_KEYS, type SandboxSpan, type SearchSpanResult, type SearchTraceResult, type Span, type SpanBase, type SpanFilter, type SpanHandle, type SpanKind, type SpanMatchRecord, SpanNotFoundError, type SpanStatus, type SseUsageMode, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS, TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_SUBAGENT_DESCRIPTION, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, TRACE_SCHEMA_VERSION, type ToolSpan, type ToolSpanOtlpInput, type TraceAggregate, type TraceAnalysisStore, type TraceAnalystByteBudgets, type TraceAnalystFilters, type TraceAnalystHookOptions, type TraceAnalystSpan, type TraceAnalystSpanKind, type TraceAnalystSpanStatus, type TraceAnalystTraceSummary, TraceEmitter, type TraceEmitterOptions, type TraceEvent, TraceFileMissingError, type TraceInsightContext, type TraceInsightFinding, type TraceInsightPanelRole, type TraceInsightPromptInput, type TraceInsightQualityGate, type TraceInsightQuestion, type TraceInsightReadiness, type TraceInsightSuite, type TraceInsightTask, TraceNotFoundError, type TraceStore, type TraceStoreSource, type TraceStoreToOtlpOptions, type TracesToOtlpResult, type ViewSpansResult, type ViewTraceOversized, type ViewTraceResult, aggregateLlm, analyzeTraces, applyToolSpanOtlpAttributes, argHash, asNumber, asString, assertRunCaptured, buildTraceAnalystTools, buildTraceInsightContext, buildTraceInsightPrompt, captureFetchToRawSink, convertTraceStoresToOtlp, createOtelExporter, createOtelTracingStore, createReplayFetch, defaultProviderRedactor, defaultTraceInsightPanel, describeTraceInsightScope, domainEvidencePattern, exportRunAsOtlp, extractOtlpAttributes, extractUsage, extractUsageFromResponse, extractUsageFromSse, firstNumberAttr, firstStringAttr, flattenOtlpExportToNdjson, groupBy, hasCapturedToolArgs, inferDomainKeywords, inferOtlpKind, isJudgeSpan, isLlmSpan, isRetrievalSpan, isSandboxSpan, isToolSpan, iterateRawCalls, judgeSpans, llmSpanFromProvider, llmSpans, otelRunCompleteHook, otlpToRunRecords, otlpToTraceRunRecords, planTraceInsightQuestions, projectOtlpFlatLine, providerFromBaseUrl, readOtlpStatus, redactString, redactValue, runFailureClass, runsForScenario, scoreTraceInsightReadiness, stringField, throwIfRunIncomplete, tokenizeDomainWords, toolSpans, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };