/**
 * 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;
}
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;
    };
    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>;
}

export { DEFAULT_TRACE_ANALYST_BUDGETS as D, type QueryTracesPage as Q, type SearchSpanResult as S, type TraceAnalysisStore as T, type ViewSpansResult as V, type DatasetOverview as a, type SearchTraceResult as b, type SpanMatchRecord as c, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX as d, type TraceAnalystByteBudgets as e, type TraceAnalystFilters as f, type TraceAnalystSpan as g, type TraceAnalystSpanKind as h, type TraceAnalystSpanStatus as i, type TraceAnalystTraceSummary as j, type ViewTraceOversized as k, type ViewTraceResult as l };
