@tangle-network/agent-eval 0.120.1 → 0.120.2

package/dist/traces.d.ts

@@ -1,2343 +0,0 @@
-import { AxAIService, AxAgentActorTurnCallbackArgs, AxFunction } from '@ax-llm/ax';
-
-/**
- * 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;
-    });
-}
-
-/**
- * RawProviderSink — first-class persistence for the actual HTTP-level
- * request/response bodies of every LLM provider call.
- *
- * Why this is a separate sink from the structured `LlmSpan`:
- *
- *   - `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.
- *
- * 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.
- *
- * 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.
- */
-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;
-    /**
-     * 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`.
-     */
-    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 RawProviderSinkFilter {
-    runId?: string;
-    spanId?: string;
-    direction?: RawProviderDirection;
-    attemptIndex?: number;
-}
-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>;
-}
-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;
-}
-declare class InMemoryRawProviderSink implements RawProviderSink {
-    private events;
-    private redactor;
-    constructor(opts?: InMemoryRawProviderSinkOptions);
-    record(event: RawProviderEvent): Promise<void>;
-    list(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
-    size(): number;
-}
-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 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;
-}
-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[]>;
-}
-/**
- * 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;
-
-/**
- * Replay-from-raw-events — turn every captured campaign run into a
- * re-runnable artifact.
- *
- * `RawProviderSink` captures every provider HTTP envelope; `runEvalCampaign`
- * makes that capture the default. Together they make every past run a
- * complete fingerprint of what happened on the wire — enough to replay
- * the run without burning new LLM cost.
- *
- * Three use cases this primitive enables:
- *
- *   1. **Post-hoc judging** — apply a new judge / rubric / scoring callback
- *      to last week's runs without re-calling any LLM. The cost of trying
- *      a new rubric drops from "another full sweep" to a CPU-bound replay.
- *   2. **Determinism audits** — replay the same campaign and verify the
- *      raw responses match byte-for-byte. Any drift is a non-determinism
- *      bug (in the harness, the prompt builder, the sandbox, …).
- *   3. **Free judge calibration** — run two judges on identical responses
- *      and measure inter-judge agreement without doubling LLM spend.
- *
- * The interface is deliberately fetch-shaped. Inject `createReplayFetch`
- * into `LlmClientOptions.fetch` and every `callLlm` transparently reads
- * from the cache instead of calling the network. No new code path through
- * the LLM client is needed; the cache hit is invisible to the runner.
- */
-
-declare class ReplayCacheMissError extends ReplayError {
-    readonly url: string;
-    readonly requestKey: string;
-    constructor(url: string, requestKey: string, message?: string);
-}
-interface ReplayCacheEntry {
-    request: RawProviderEvent;
-    response: RawProviderEvent;
-}
-interface ReplayCacheStats {
-    total: number;
-    byProvider: Record<string, number>;
-    byModel: Record<string, number>;
-    /** Spans for which we have a request but no response (run aborted mid-call). */
-    orphanRequests: number;
-}
-/**
- * In-memory deterministic cache of (request → response) keyed on a stable
- * hash of the request body. Built from a `RawProviderSink` containing
- * paired `request` and `response` events from a previous run.
- *
- * The cache is the source of truth for replay; `createReplayFetch` is a
- * thin wrapper that reads from it.
- */
-declare class ReplayCache {
-    private byKey;
-    private orphans;
-    private byProvider;
-    private byModel;
-    /**
-     * Build a cache from a sink's events. The sink must implement `list()`.
-     * Filter by `runId` / `spanId` to scope to a specific replay.
-     */
-    static fromSink(sink: RawProviderSink, filter?: {
-        runId?: string;
-        spanId?: string;
-    }): Promise<ReplayCache>;
-    /** Build a cache from an in-memory event list. */
-    static fromEvents(events: RawProviderEvent[]): Promise<ReplayCache>;
-    /** Number of cacheable (request, response) pairs in the cache. */
-    size(): number;
-    stats(): ReplayCacheStats;
-    /** Iterate every cached `(request, response)` pair in insertion order. */
-    entries(): IterableIterator<ReplayCacheEntry>;
-    /**
-     * Look up a cached response by hashing the (model, messages, temperature,
-     * maxTokens, response_format) shape. Returns `undefined` on miss; the
-     * caller decides whether to throw, fall back to the network, or skip.
-     */
-    lookup(requestBody: unknown): Promise<ReplayCacheEntry | undefined>;
-}
-interface ReplayFetchOptions {
-    /**
-     * Behaviour on cache miss. Default `'throw'`. `'fallback'` calls the
-     * `fallbackFetch` (typically `globalThis.fetch`) so a partial replay can
-     * still complete; `'fail-closed'` returns a synthetic 599 response so the
-     * call site sees a non-retriable failure.
-     */
-    onMiss?: 'throw' | 'fallback' | 'fail-closed';
-    fallbackFetch?: typeof fetch;
-    /** Optional callback fired once per replayed call (for telemetry / counters). */
-    onHit?: (info: {
-        url: string;
-        provider: string;
-        model: string;
-    }) => void;
-    /** Optional callback fired on cache miss before the `onMiss` policy applies. */
-    onMissNotify?: (info: {
-        url: string;
-        requestBody: unknown;
-    }) => void;
-}
-/**
- * Build a `fetch`-shaped function that serves cached responses out of a
- * `ReplayCache` for any URL ending in `/chat/completions`. Pass through
- * `LlmClientOptions.fetch` and `callLlm` becomes free.
- *
- * Non-`/chat/completions` URLs are passed straight to the fallback fetch
- * (default: `globalThis.fetch`). This matters because non-LLM HTTP work
- * (judge HTTP servers, sandbox callbacks) sometimes flows through the same
- * `fetch` and shouldn't be intercepted.
- */
-declare function createReplayFetch(cache: ReplayCache, opts?: ReplayFetchOptions): typeof fetch;
-/**
- * Convenience iterator over `(request, response)` pairs in a sink — for
- * post-hoc scoring that doesn't need a `fetch` shim. The judge or scorer
- * runs purely in-process over cached LLM outputs.
- */
-declare function iterateRawCalls(sink: RawProviderSink, filter?: {
-    runId?: string;
-    spanId?: string;
-}): AsyncGenerator<ReplayCacheEntry>;
-
-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.
- *
- * Every score, every failure class, every pipeline in the framework is
- * a view over this data. Shape it once, live with it.
- *
- * 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;
-}
-/**
- * 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).
- */
-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;
-    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;
-
-/**
- * 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`.
- */
-
-/** 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;
-}
-/**
- * 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.
- */
-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;
-}
-/**
- * Per-judge / per-dimension breakdown for runs scored by an ensemble of
- * judges over a multi-dimensional rubric.
- *
- * 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.
- *
- * `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 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 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;
-    /** Stable identifier for the candidate (variant) being run. The
-     *  promotion gate compares two `candidateId`s on matched items. */
-    candidateId: 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;
-    /** 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;
-    /** 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;
-    /**
-     * 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`.
-     */
-    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;
-}
-
-/**
- * Provider response and SSE usage extraction.
- *
- * Missing usage returns `null`; reported zeroes and cache-only activity remain
- * distinguishable from absent telemetry.
- */
-
-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?, 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 only when none of those categories is present.
- */
-declare function extractUsage(body: unknown): ExtractedUsage | null;
-/**
- * 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, 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, sseOptions?: ExtractUsageFromSseOptions): Promise<ExtractedUsage | null>;
-
-/**
- * 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 {
-    /** Logical run id stamped on every captured event. Required — without it
-     *  the raw events can't be paired with their parent `Run`. */
-    runId: string;
-    /** Optional logical span id (enables span-level sink filtering). */
-    spanId?: string;
-    /** Resolved base URL (normalised, no trailing slash). Used for the event's
-     *  `baseUrl` and for endpoint-path extraction. */
-    baseUrl: string;
-    /** Model id the caller intends to invoke. Stamped on every event. */
-    model: string;
-    /** Provider override. When omitted, `providerFromBaseUrl(baseUrl)`. */
-    provider?: string;
-}
-interface CaptureFetchOptions {
-    /** Override the capture-time redactor. Default `defaultProviderRedactor`. */
-    redactor?: ProviderRedactor;
-    /** Cap on captured response-body bytes; beyond it the body is truncated and
-     *  `body_truncated` is added to `redactedFields`. Default 2 MiB. */
-    responseBodyByteCap?: number;
-    /** When true, a sink-write failure propagates to the caller. Default false
-     *  — capture is best-effort so a sink failure never kills the LLM call. */
-    failClosed?: boolean;
-    /**
-     * Invoked with the token usage parsed off each successful response (JSON or
-     * SSE), keyed by the captured context. Lets a caller fold usage → cost without
-     * re-cloning the response themselves. Not called when the response carries no
-     * usage. Best-effort: a throw here is swallowed (it never kills the LLM call)
-     * unless `failClosed` is set.
-     */
-    onUsage?: (usage: ExtractedUsage, ctx: CaptureFetchContext) => void;
-    /** 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[]>;
-}
-
-/**
- * TraceEmitter — hierarchical span builder that auto-parents using an
- * internal stack. One emitter per Run; emitters do NOT share state.
- *
- * 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 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";
-/** Exact prompt context after summing mutually exclusive input/cache categories. */
-declare const LLM_CONTEXT_TOKENS = "tangle.llm.context_tokens";
-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", ...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"];
-/** Read a numeric attribute, tolerating numeric strings; `null` if absent or invalid. */
-declare function asNumber(value: unknown): number | null;
-/** First finite numeric value across a list of candidate attribute keys. */
-declare function firstNumberAttr(attributes: Record<string, unknown>, keys: readonly string[]): number | null;
-/** Sum producer-supplied, mutually exclusive prompt-token categories. */
-declare function contextInputTokens(usage: {
-    inputTokens?: number | null;
-    cachedTokens?: number | null;
-    cacheWriteTokens?: number | null;
-}): number | undefined;
-interface LlmSpanOtlpInput {
-    model?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    reasoningTokens?: number;
-    cachedTokens?: number;
-    cacheWriteTokens?: number;
-    costUsd?: number;
-    finishReason?: string;
-}
-/** Write the canonical LLM attributes shared by trace producers. */
-declare function applyLlmSpanOtlpAttributes(attributes: Record<string, unknown>, span: LlmSpanOtlpInput): void;
-
-/** Canonical OpenInference-over-OTLP attribute vocabulary used at the trace boundary. */
-
-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. */
-    headers?: Record<string, string>;
-    /** Batch size before flush. Default 64. */
-    batchSize?: number;
-    /** Flush interval ms. Default 5000. */
-    flushIntervalMs?: number;
-    /** Resource attributes stamped on every export. */
-    resourceAttributes?: Record<string, string | number | boolean>;
-    /** Service name. Default 'agent-eval'. */
-    serviceName?: string;
-}
-interface OtelExporter {
-    /** Called by the TraceEmitter on every span close. */
-    exportSpan(span: ExportableSpan): void;
-    /** Force flush pending spans. */
-    flush(): Promise<void>;
-    /** Shutdown cleanly — flushes remaining spans and stops the timer. */
-    shutdown(): Promise<void>;
-}
-interface ExportableSpan {
-    traceId: string;
-    spanId: string;
-    parentSpanId?: string;
-    name: string;
-    kind: string;
-    startedAt: number;
-    endedAt?: number;
-    status?: string;
-    error?: string;
-    model?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    reasoningTokens?: number;
-    cachedTokens?: number;
-    cacheWriteTokens?: number;
-    costUsd?: number;
-    tool?: ToolSpanOtlpInput;
-    attributes?: Record<string, unknown>;
-}
-/**
- * Create an OTEL exporter. Returns undefined when no endpoint is configured
- * (neither via config nor env) — callers should check before attaching.
- */
-declare function createOtelExporter(config?: OtelExportConfig): OtelExporter | undefined;
-
-/**
- * OTEL bridge — connects TraceEmitter span lifecycle to the OtelExporter.
- *
- * When an OtelExporter is active, every span that closes through the
- * TraceEmitter is also pushed to the exporter for real-time streaming to
- * the user's OTEL collector.
- *
- * The bridge is opt-in: attach via `otelRunCompleteHook(exporter)` as a
- * RunCompleteHook, or wrap the store with `createOtelTracingStore` for
- * real-time per-span export.
- */
-
-/**
- * Create a RunCompleteHook that exports all spans from the completed run
- * to the OTEL exporter, then flushes.
- */
-declare function otelRunCompleteHook(exporter: OtelExporter): RunCompleteHook;
-/**
- * Create an auto-exporting TraceStore wrapper that intercepts updateSpan
- * calls. When a span gets an endedAt, it's exported immediately. This
- * gives real-time streaming instead of batch-at-end.
- *
- * This is the preferred integration path: wrap the store before
- * constructing the TraceEmitter.
- */
-declare function createOtelTracingStore(inner: TraceStore, exporter: OtelExporter, traceId: string): TraceStore;
-
-/**
- * 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.
- *
- * Pre-persistence rules mean raw traces in storage are already scrubbed.
- * Unredacted variants (for debugging / post-mortems) live in a separate
- * storage layer with stricter access controls; this module only covers
- * the default scrub-then-persist path.
- *
- * Rules compose: pass an array of `RedactionRule`, each is applied in
- * order. Strings that match get replaced with a tagged sentinel so the
- * eval framework can count how many redactions happened per run
- * (surfaced via `redaction_applied` events).
- */
-interface RedactionRule {
-    id: string;
-    pattern: RegExp;
-    /** Replacement — e.g. '[PII:email]'. Defaults to `[redacted:{id}]`. */
-    replacement?: string;
-}
-interface RedactionReport {
-    redactionCount: number;
-    byRule: Record<string, number>;
-}
-/** OWASP / common-sense defaults — extend per-domain. */
-declare const DEFAULT_REDACTION_RULES: RedactionRule[];
-declare const REDACTION_VERSION = "1.0.0";
-/**
- * Redact a single string. Returns the new string and a per-rule count of
- * how many substitutions fired.
- */
-declare function redactString(input: string, rules?: RedactionRule[]): {
-    output: string;
-    report: RedactionReport;
-};
-/**
- * Walk a JSON-ish value applying `redactString` to every string leaf.
- * Arrays and plain objects are recursed; other types pass through
- * untouched. Circular references throw — traces should be tree-shaped.
- */
-declare function redactValue(value: unknown, rules?: RedactionRule[], report?: RedactionReport): {
-    value: unknown;
-    report: RedactionReport;
-};
-
-/**
- * Convert agent-eval's internal trace shape (`FileSystemTraceStore` → `Run`,
- * `Span`, `TraceEvent`) into the OTLP-flat JSONL the trace analyst
- * (`analyzeTraces` + `OtlpFileTraceStore`) reads.
- *
- * Eval harnesses shard a `FileSystemTraceStore` per cell (persona / variant)
- * under a run directory. The analyst consumes a single OTLP-NDJSON file keyed
- * on `trace_id` + `span_id` with `start_time`/`end_time` in ISO-8601 and
- * resource + `attributes` rolled up per-span. This module walks every shard,
- * projects each `Span` (plus events pinned to it) into the flat OTLP shape,
- * and emits one NDJSON file.
- *
- * Generic OTLP/OpenInference fields are always emitted (`service.name`,
- * `agent.name`, `run.id`/`run.status`, `openinference.span.kind`,
- * `llm.model_name`, …). Domain attributes (`legal.*`, `tax.*`, …) are injected
- * per-run via {@link TraceStoreToOtlpOptions.resourceAttributes} /
- * {@link TraceStoreToOtlpOptions.runAttributes} so consumers don't re-roll the
- * walker.
- */
-
-interface TracesToOtlpResult {
-    /** Total spans emitted across every cell. */
-    spanCount: number;
-    /** Total run-anchor spans (one per Run) appended for analyst visibility. */
-    runCount: number;
-    /** Cells whose shards parsed cleanly. */
-    cellCount: number;
-    /** Cells that errored mid-conversion — surfaced so a partial conversion
-     *  isn't silently masked. */
-    cellErrorCount: number;
-}
-/**
- * A trace source the analyst should ingest. Two layouts are supported:
- *
- *   - `celled` (default): the root holds one cell subdirectory per
- *     persona/variant, each a `FileSystemTraceStore` (`runs.ndjson`,
- *     `spans.ndjson`, `events.ndjson`).
- *   - `flat`: the root is itself a single `FileSystemTraceStore` (e.g. a
- *     production-ingestion sidecar that appends one ndjson set directly under
- *     the chosen directory).
- */
-interface TraceStoreSource {
-    /** Absolute path to the trace store root. */
-    root: string;
-    /** Layout — `celled` (default) or `flat`. */
-    layout?: 'celled' | 'flat';
-    /** OTLP `service.name` for this source. Overrides the options default. */
-    serviceName?: string;
-}
-/** Domain hooks. The walker is generic; consumers inject the namespaced
- *  attributes that ride along on every run + span for analyst discovery. */
-interface TraceStoreToOtlpOptions {
-    /** Default OTLP `service.name` when a source doesn't set its own.
-     *  Default `agent-eval`. */
-    serviceName?: string;
-    /** Extra resource attributes per run, e.g.
-     *  `(run) => ({ 'legal.persona_id': run.tags?.personaId ?? '' })`. */
-    resourceAttributes?: (run: Run) => Record<string, unknown>;
-    /** Extra attributes on the per-run anchor span, e.g. domain outcome fields. */
-    runAttributes?: (run: Run) => Record<string, unknown>;
-}
-/**
- * Read every per-cell shard under each source root and write a flat OTLP-JSONL
- * view of the corpus to `outPath`. Each cell directory is a
- * `FileSystemTraceStore` — NDJSON append-only with size-based rotation;
- * `updateRun`/`updateSpan` append `{ id, ...patch, _update: true }` rows
- * rather than rewriting, so readers must merge those patches in (done here).
- *
- * A `string` source is treated as a celled root.
- */
-declare function convertTraceStoresToOtlp(source: string | TraceStoreSource | readonly TraceStoreSource[], outPath: string, opts?: TraceStoreToOtlpOptions): TracesToOtlpResult;
-
-/**
- * Shared types for the trace-analyst module.
- *
- * 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.
- *
- * 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:
- *
- *   - `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.
- *
- * 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.
- */
-
-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 AnalyzeTracesInput {
-    /** The user-facing question. Domain framing belongs here, not in the
-     *  actor description. */
-    question: string;
-}
-interface AnalyzeTracesResult {
-    /** The actor's submitted prose answer. */
-    answer: string;
-    /** Bulleted findings from the actor's structured completion. */
-    findings: string[];
-    /** Per-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 {
-    stage: AxAgentActorTurnCallbackArgs['stage'];
-    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 `executorOptions.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 the actor. */
-    model?: string;
-    /** Maximum model subqueries. 0 disables model fan-out. Default 4. */
-    maxSubqueries?: number;
-    /** Maximum actor turns. Default 12. */
-    maxTurns?: number;
-    /** Maximum parallel model subqueries. Default 2. */
-    maxParallelSubqueries?: number;
-    /** Cancels in-flight model and tool work. */
-    signal?: AbortSignal;
-    /** Override the actor description. */
-    actorDescription?: 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 for diagnosis and recovery. */
-    progressLogPath?: string;
-}
-/**
- * Run the trace analyst.
- *
- * 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 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;
-/** 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` by default, or per caller-defined
- * logical run when one task is fragmented across multiple OTLP traces.
- *
- * 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;
-    /**
-     * 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;
-    /**
-     * Map each OTLP `trace_id` to the logical run it belongs to. Use this when a
-     * provider emits several traces for one task attempt. All mapped traces are
-     * aggregated into one record; duplicate span ids remain isolated by their
-     * source trace. The callback must return a non-empty id for every trace.
-     *
-     * When omitted, every `trace_id` remains an independent run.
-     */
-    logicalRunIdForTrace?: (traceId: string) => string;
-    /**
-     * Score for a produced run's outcome (AppWorld `world.evaluate()` →
-     * TGC/SGC, or
-     * any [0,1] task-success signal). Keyed by the logical run id when
-     * `logicalRunIdForTrace` is supplied, otherwise by `trace_id`; 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?: (runId: string, span: TraceAggregate) => number | undefined;
-    /**
-     * Per-record judge metadata when an external judge produced the score.
-     * Keyed by the logical run id when supplied, otherwise by `trace_id`.
-     */
-    judgeMetadataForTrace?: (runId: string) => RunRecord['judgeMetadata'] | undefined;
-}
-/** A `RunRecord` plus the verbatim prompt/completion text when the trace's
- *  LLM spans exposed it. The text is NOT on the validated `RunRecord`
- *  (`outcome.raw` is numeric-only) but consumers ingesting full traces want
- *  it — so it rides alongside. */
-interface OtlpTraceRunRecord {
-    record: RunRecord;
-    /** Verbatim first-LLM-span `input.value`, when present. */
-    promptText?: string;
-    /** Verbatim last-LLM-span `output.value`, when present. */
-    completionText?: string;
-}
-/** Per-trace rollup the score callback can inspect. */
-interface TraceAggregate {
-    traceId: string;
-    /** Number of source OTLP traces folded into this run. */
-    sourceTraceCount: number;
-    /** Source OTLP trace ids folded into this run, sorted for deterministic audit output. */
-    sourceTraceIds: readonly string[];
-    spanCount: number;
-    llmSpanCount: number;
-    toolSpanCount: number;
-    agentSpanCount: number;
-    errorSpanCount: number;
-    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[];
-/**
- * Aggregate already-parsed OTLP flat rows without serializing them back to
- * JSONL. This is the in-memory counterpart to {@link otlpToRunRecords}; both
- * paths share projection, reconciliation, validation, and ordering.
- */
-declare function otlpRowsToRunRecords(rows: Iterable<object>, opts: OtlpToRunRecordsOptions): RunRecord[];
-/** As {@link otlpToRunRecords} but returns the prompt/completion text too. */
-declare function otlpToTraceRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
-/** Parsed-row counterpart to {@link otlpToTraceRunRecords}. */
-declare function otlpRowsToTraceRunRecords(rows: Iterable<object>, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
-
-/** 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 the question splits into independent reasoning branches, use bounded `llmQuery(...)` calls over evidence you already loaded. Subqueries cannot inspect the trace store, so pass the exact trace excerpts they need. Example:\n\n    const reviews = await llmQuery([\n      { query: 'Classify the failure mechanism in this excerpt.', context: traceAbcExcerpt },\n      { query: 'Classify the failure mechanism in this excerpt.', context: traceDefExcerpt },\n    ]);\n\nOBSERVABILITY rules:\n- Each discovery turn must emit at least one concise `console.log(...)` showing what evidence was learned.\n- Finish gathering evidence before submitting the analysis.\n- Reuse runtime variables across turns; don't recompute.\n\nOUTPUT contract \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- A concise findings array containing only claims supported by inspected evidence.\n\nDo NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.";
-declare const TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-actor-v6-2026-07-14";
-
-/**
- * `OtlpFileTraceStore` — read-only OTLP-JSONL trace store for the
- * trace-analyst.
- *
- * Wire shape. Each line of the input file is one OTLP-shaped span. The
- * store understands flattened OTLP JSONL plus the OpenInference vocab.
- * We project upstream's full
- * span shape down to `TraceAnalystSpan` lazily — full materialisation
- * only happens for the spans the agent actually requests.
- *
- * Indexing. On first read the store builds an in-memory index keyed
- * by `trace_id` carrying:
- *   - byte offsets + lengths for each span line (for surgical reads
- *     without re-parsing the whole file)
- *   - a `TraceAnalystTraceSummary` rollup
- *   - sets of services / agents / models / tools / has_errors
- *   - byte size of the trace's JSONL slab
- *
- * Memory bound. The index keeps span metadata only — names, kinds,
- * offsets, status. Attribute payloads stay on disk until requested.
- * For a 50MB JSONL with 50k spans, the index is ~5MB.
- *
- * Concurrency. The store builds the index once on first read and
- * caches it. Subsequent reads reuse the index. The file is opened on
- * each read; we never hold a long-lived FD.
- */
-
-interface OtlpFileTraceStoreOptions {
-    /** Path to the OTLP-JSONL file. */
-    path: string;
-    /** Override the discovery (`viewTrace`) per-attribute byte cap. */
-    perAttributeViewBudget?: number;
-    /** Override the surgical (`viewSpans`) per-attribute byte cap. */
-    perAttributeSpanBudget?: number;
-    /** Override the per-call ceiling that triggers oversized summaries. */
-    perCallByteCeiling?: number;
-    /** Override the per-match text budget. */
-    perMatchTextBudget?: number;
-    /**
-     * Hard ceiling on the trace file size in bytes. The store reads the
-     * whole file into one Buffer and indexes it in memory, so an
-     * unbounded file OOMs the process. Above this size the store fails
-     * loud with `TraceFileTooLargeError` instead of degrading silently.
-     * Default 256 MiB.
-     */
-    maxFileBytes?: number;
-}
-declare class OtlpFileTraceStore implements TraceAnalysisStore {
-    private readonly path;
-    private readonly perAttributeViewBudget;
-    private readonly perAttributeSpanBudget;
-    private readonly perCallByteCeiling;
-    private readonly perMatchTextBudget;
-    private readonly maxFileBytes;
-    private indexPromise?;
-    /** Cached UTF-8 buffer of the file. We pin it once because every
-     *  read needs slice access and re-reading on each call balloons the
-     *  syscall count. */
-    private bufferPromise?;
-    constructor(opts: OtlpFileTraceStoreOptions);
-    getOverview(filters?: TraceAnalystFilters): Promise<DatasetOverview>;
-    queryTraces(opts: {
-        filters?: TraceAnalystFilters;
-        limit: number;
-        offset?: number;
-    }): Promise<QueryTracesPage>;
-    countTraces(filters?: TraceAnalystFilters): Promise<number>;
-    viewTrace(opts: {
-        trace_id: string;
-        per_attribute_byte_cap?: number;
-    }): Promise<ViewTraceResult>;
-    viewSpans(opts: {
-        trace_id: string;
-        span_ids: readonly string[];
-        per_attribute_byte_cap?: number;
-    }): Promise<ViewSpansResult>;
-    searchTrace(opts: {
-        trace_id: string;
-        regex_pattern: string;
-        max_matches?: number;
-    }): Promise<SearchTraceResult>;
-    searchSpan(opts: {
-        trace_id: string;
-        span_id: string;
-        regex_pattern: string;
-        max_matches?: number;
-    }): Promise<SearchSpanResult>;
-    /** Force the index to materialise. Useful to amortise startup cost
-     *  before the first agent call. */
-    ensureIndexed(): Promise<void>;
-    private buffer;
-    /** Stat-then-read so an oversized file fails loud BEFORE we allocate a
-     *  multi-hundred-MB Buffer and OOM the process. A missing file surfaces
-     *  as TraceFileMissingError; any other stat/read error propagates. */
-    private readGuarded;
-    private index;
-    private buildIndex;
-    private matchedTraces;
-    private toSummary;
-    private projectSpan;
-    private buildOversizedSummary;
-    private scanSpanForMatches;
-}
-declare class TraceFileMissingError extends NotFoundError {
-    constructor(path: string);
-}
-declare class TraceNotFoundError extends NotFoundError {
-    readonly trace_id: string;
-    constructor(trace_id: string);
-}
-declare class SpanNotFoundError extends NotFoundError {
-    readonly trace_id: string;
-    readonly span_id: string;
-    constructor(trace_id: string, span_id: string);
-}
-
-/**
- * Trace-analyst tool surface — six namespaced AxFunctions the analyst
- * agent calls from generated JS code via `traces.<name>(...)`.
- *
- * Discovery → narrow → deep-read protocol. Tool names + ordering
- * support RLM discovery:
- *
- *   1. `getDatasetOverview` (cheap)  — first call, sizes the dataset
- *   2. `queryTraces`                 — paginated summaries with `raw_jsonl_bytes`
- *   3. `countTraces`                 — cheap pre-flight before regex
- *   4. `viewTrace`                   — full span list, oversized → summary
- *   5. `viewSpans`                   — surgical 16KB-cap reads
- *   6. `searchTrace` / `searchSpan`  — bounded regex hits
- *
- * Failure mode. Tool handlers throw on bad input (invalid trace ids,
- * out-of-range pagination, malformed regex). Ax converts thrown errors
- * into actor-visible `[ERROR]` strings so the analyst can adjust on
- * the next turn instead of looping.
- */
-
-interface BuildTraceAnalystToolsOpts {
-    store: TraceAnalysisStore;
-    /** Override the default sample-trace-id slot count (20). Mostly for tests. */
-    sampleTraceLimit?: number;
-}
-/**
- * Build the trace-analyst function set. Pass the result into
- * `agent(...).functions.local`.
- */
-declare function buildTraceAnalystTools(opts: BuildTraceAnalystToolsOpts): AxFunction[];
-/**
- * Convenience: same shape as `buildTraceAnalystTools` but returns the
- * grouped form expected when registering trace tools alongside other
- * agent function modules. */
-declare function traceAnalystFunctionGroup(opts: BuildTraceAnalystToolsOpts): {
-    namespace: string;
-    title: string;
-    selectionCriteria: string;
-    description: string;
-    functions: AxFunction[];
-};
-
-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_CONTEXT_TOKENS, 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 LlmSpanOtlpInput, 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_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, applyLlmSpanOtlpAttributes, applyToolSpanOtlpAttributes, argHash, asNumber, asString, assertRunCaptured, buildTraceAnalystTools, buildTraceInsightContext, buildTraceInsightPrompt, captureFetchToRawSink, contextInputTokens, 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, otlpRowsToRunRecords, otlpRowsToTraceRunRecords, otlpToRunRecords, otlpToTraceRunRecords, planTraceInsightQuestions, projectOtlpFlatLine, providerFromBaseUrl, readOtlpStatus, redactString, redactValue, runFailureClass, runsForScenario, scoreTraceInsightReadiness, stringField, throwIfRunIncomplete, tokenizeDomainWords, toolSpans, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };