/**
 * TraceCollector — extracts structured trace data from provider responses.
 *
 * Parses tool calls, token usage, and timing data from Promptfoo result
 * objects and normalizes them into the canonical `EvalTrace` shape.
 *
 * Works via inline extraction — parsing provider response metadata
 * directly, without requiring additional infrastructure.
 *
 * @see docs/design-docs/architecture-overhaul/observability-telemetry.md
 * @see packages/core/src/types/trace.ts — EvalTrace types
 */
import type { EvalMode, EvalTrace, ToolCallCategory, ToolCallSource } from "../../../_vendor/ailf-core/index.d.ts";
/** Raw provider response shape (subset of Promptfoo's result object) */
export interface ProviderResponse {
    /** Raw text output */
    output?: string;
    /** Token usage (varies by provider) */
    tokenUsage?: {
        completion?: number;
        prompt?: number;
        total?: number;
        cached?: number;
    };
    /** Provider-specific metadata (e.g., Claude's toolCalls) */
    metadata?: {
        toolCalls?: RawToolCall[];
        /**
         * Per-turn LLM-call latency in milliseconds, in turn order (D0088).
         * Recorded by the loops we own (`Date.now()` around the model fetch);
         * drives the `llm-turn` timeline spans below.
         */
        llmTimings?: number[];
        [key: string]: unknown;
    };
    /** Response latency in milliseconds */
    latencyMs?: number;
    /**
     * Real execution-time bounds measured by the mode adapter around the observed
     * run (W-trace-real-timestamps). ISO 8601. When present, `collectTrace` uses
     * them for `EvalTrace.startedAt`/`completedAt` verbatim instead of
     * reconstructing the window from `latencyMs` at emission time — the literacy
     * adapter forwards the agent-observer session's `startedAt`/`endedAt` here.
     * Modes with no source anchor (MCP, agent-harness) omit both and let the
     * collector reconstruct the window.
     */
    startedAt?: string;
    completedAt?: string;
}
/** Raw tool call from a provider (pre-normalization) */
export interface RawToolCall {
    name?: string;
    input?: Record<string, unknown>;
    output?: unknown;
    error?: string;
    durationMs?: number;
    /**
     * 0-based model round (turn) this call was issued in (D0088). Set by the
     * MCP adapter from the loop's `ToolCallEntry.turnIndex`; lets `buildSpans`
     * place this call's `tool-call` span after the matching `llm-turn` span in
     * execution order. Absent for modes that don't time per turn.
     */
    turnIndex?: number;
    /**
     * Per-call provenance override (D0088). When set, it wins over the
     * collector's uniform `toolCallSource`, letting a single trace carry
     * mixed provenance — literacy interleaves the model's `tool_use` blocks
     * (`loop-transcript`) with the HTTP observer log (`http-observer`) in one
     * `toolCalls` array. Calls without it fall back to the uniform default.
     */
    source?: ToolCallSource;
    /** Alternative field names used by some providers */
    function?: {
        name?: string;
        arguments?: string;
    };
    type?: string;
}
/** Options for trace collection */
export interface TraceCollectorOptions {
    /** Run ID to associate with this trace */
    runId: string;
    /** Evaluation mode that produced this trace (D0088). */
    mode: EvalMode;
    /** Task ID that produced this test case */
    taskId: string;
    /** Test case index within the task */
    testCaseIndex: number;
    /** Model under evaluation */
    modelId: string;
    /** Custom tool → category mappings */
    toolCategories?: Record<string, ToolCallCategory>;
    /**
     * Provenance stamped on every extracted tool call (D0088). Defaults to
     * `"provider-metadata"` — the shape `collectTrace` reads
     * (`metadata.toolCalls`). A mode adapter that reads a transcript or HTTP
     * log overrides this.
     */
    toolCallSource?: ToolCallSource;
    /** Maximum output size per tool call (bytes) */
    maxOutputBytes?: number;
}
/**
 * Collect a trace from a single provider response.
 *
 * Extracts tool calls, token usage, timing, and builds the
 * chronological event log.
 */
export declare function collectTrace(response: ProviderResponse, options: TraceCollectorOptions): EvalTrace;
/**
 * Merge multiple per-turn traces into a single test case trace.
 *
 * Each turn produces its own trace. This function combines them into
 * a parent trace with per-turn spans.
 */
export declare function mergeTraces(turns: EvalTrace[], parentOptions: TraceCollectorOptions): EvalTrace;
