/**
 * `traces` fixture — read-only access to the OTel traces emitted by the
 * agent during this run. Pre-loaded by the runner before the test body
 * starts; sync access from inside the body.
 *
 * Three construction modes (the runner picks one):
 *   - `buildTracesAccessor(spans)` — real spans available, real numbers.
 *   - `emptyTracesAccessor()` — agent opted out (`useTraces=false`).
 *     Every accessor returns 0/[] so user matchers don't blow up.
 *   - `unavailableTracesAccessor(reason)` — agent opted in (`useTraces=true`)
 *     but spans were not fetchable (no runId, fetch failed, or polling
 *     timed out). Every accessor *throws* so silent false-passes like
 *     `expect(traces.totalTokens).to.be.lessThan(10_000)` against an
 *     empty fixture become loud failures (see issue #230).
 *
 * Built on top of `services/traces/index.ts:fetchTracesByRunIds` —
 * the runner is responsible for invoking that and constructing the
 * accessor.
 */
import type { Span } from '../../types/index.js';
export interface TracesAccessor {
    /** Sum of all `gen_ai.usage.prompt_tokens + completion_tokens` across LLM spans. */
    totalTokens: number;
    /** Sum of all `gen_ai.usage.cost_usd` (or derived) across LLM spans. */
    totalCost: number;
    /** Tool invocation summary derived from spans. */
    toolCalls: ReadonlyArray<{
        name: string;
        durationMs: number;
    }>;
    /** Duration of the first span matching the given name, or 0 when not found. */
    spanDuration(name: string): number;
    /** All spans (read-only). */
    spans: ReadonlyArray<Span>;
}
/**
 * Empty accessor — silent zeros. Used when the agent opted out of traces
 * (`useTraces: false`). Reading any accessor returns `0` / `[]` so user
 * matchers in opt-out scenarios don't throw.
 */
export declare function emptyTracesAccessor(): TracesAccessor;
/**
 * Loud-failure accessor — every read throws. Used when the agent opted
 * in to traces (`useTraces: true`) but spans were not retrievable. This
 * turns the silent false-pass described in issue #230 into an actionable
 * error, e.g.:
 *
 *   Error: traces fixture unavailable: no spans found for runId=…
 *
 * Construction never throws — only attribute / method access does.
 */
export declare function unavailableTracesAccessor(reason: string): TracesAccessor;
/** Build a TracesAccessor from a flat list of spans. */
export declare function buildTracesAccessor(spans: Span[]): TracesAccessor;
//# sourceMappingURL=traces.d.ts.map