/**
 * EvalTrace — Observability types for evaluation execution.
 *
 * Captures the full request/response lifecycle for a single test case,
 * including tool calls, URLs visited, search terms, token usage, and
 * a chronological event log for replay and debugging.
 *
 * Canonical field names:
 * - `operation` on TraceSpan (not `name` — storage adapts on serialization)
 *
 * Design decision: Start with simple per-result traces (flat span list
 * per EvalResult). No depth limits for agent harness spans. OTel
 * integration deferred.
 *
 * @see docs/design-docs/architecture-overhaul/observability-telemetry.md (canonical)
 * @see docs/design-docs/architecture-overhaul/domain-model.md (Trace entity)
 */
/**
 * Normalized tool call category for cross-model comparison.
 *
 * Raw tool names from providers are noisy and inconsistent (`WebSearch`
 * vs `web_search` vs `Browser.search`). AILF normalizes every tool call
 * into one of six categories.
 */
export type ToolCallCategory = "search" | "read" | "write" | "execute" | "navigate" | "communicate";
/** A single tool call made during evaluation execution */
export interface ToolCallRecord {
    /** Tool name as reported by the provider (e.g., "WebSearch", "Bash") */
    name: string;
    /** Serialized input arguments */
    input: Record<string, unknown>;
    /** Serialized output (truncated to maxOutputBytes) */
    output: unknown;
    /** Wall-clock duration of the tool call in milliseconds */
    durationMs: number;
    /** Error message if the tool call failed */
    error?: string;
    /** Classification category */
    category: ToolCallCategory;
}
/** A single span in the trace — one logical operation */
export interface TraceSpan {
    /** Unique identifier for this span */
    spanId: string;
    /** Parent span ID (null for root spans) */
    parentSpanId: string | null;
    /** Operation name (canonical field — storage may use `name`) */
    operation: string;
    /** Start time relative to trace start, in milliseconds */
    startMs: number;
    /** End time relative to trace start, in milliseconds */
    endMs: number;
    /** Arbitrary key-value attributes for this span */
    attributes: Record<string, unknown>;
}
/** Timestamped event in the trace log */
export interface TraceEvent {
    /** ISO 8601 timestamp */
    timestamp: string;
    /** Event type */
    type: "tool_call_start" | "tool_call_end" | "llm_request" | "llm_response" | "error" | "checkpoint" | "custom";
    /** Event-specific payload */
    data: Record<string, unknown>;
}
/** Token usage breakdown for a single evaluation step */
export interface TraceTokenUsage {
    /** Tokens in the prompt/input */
    promptTokens: number;
    /** Tokens in the completion/output */
    completionTokens: number;
    /** Total tokens (prompt + completion) */
    totalTokens: number;
    /** Tokens consumed by tool call inputs/outputs */
    toolTokens?: number;
}
/**
 * The complete trace for a single test case execution.
 *
 * Captures everything that happened during one task × one provider
 * evaluation: tool calls, URLs visited, search terms, token usage,
 * cost, and a chronological event log.
 */
export interface EvalTrace {
    /** Unique identifier for this trace */
    traceId: string;
    /** Parent run this trace belongs to */
    runId: string;
    /** Task definition that produced this test case */
    taskId: string;
    /** Test case index within the task */
    testCaseIndex: number;
    /** Model under evaluation */
    modelId: string;
    /** Hierarchical spans for structured tracing */
    spans: TraceSpan[];
    /** Ordered list of tool calls made during execution */
    toolCalls: ToolCallRecord[];
    /** URLs fetched via WebFetch, WebSearch, or browser navigation */
    urlsVisited: string[];
    /** Search queries issued to WebSearch or semantic search */
    searchTerms: string[];
    /** Files read during execution (sandbox paths) */
    filesRead: string[];
    /** Files created or modified during execution */
    filesWritten: string[];
    /** Aggregate token usage across all LLM calls in this trace */
    tokensUsed: TraceTokenUsage;
    /** Estimated cost in USD */
    costEstimate: number;
    /** Total wall-clock execution time in milliseconds */
    durationMs: number;
    /** Chronological event log for replay / debugging */
    events: TraceEvent[];
    /** ISO 8601 start timestamp */
    startedAt: string;
    /** ISO 8601 end timestamp */
    completedAt: string;
}
