/**
 * Privacy-safe session / window stats over RoutingTelemetry (SP-207 / #118).
 *
 * Aggregates only numeric and categorical telemetry fields — never prompt,
 * message, or tool-argument bodies.
 */
import type { ModelProfile, PriceCatalog, RoutingTelemetry, Tier } from '../../domain/types/index.js';
export type RoleCostBucket = 'primary' | 'planning_delegate' | 'other';
export type DeploymentClass = 'local' | 'cloud' | 'unknown';
export interface RoleBucketStats {
    readonly count: number;
    readonly total_cost_usd: number;
}
export interface RoleCostBreakdown {
    readonly primary: RoleBucketStats;
    readonly planning_delegate: RoleBucketStats;
    readonly other: RoleBucketStats;
}
/**
 * Compact JSON snapshot for automation / MCP (llm-use `stats_snapshot` analog).
 * Optional `frontier_savings_usd` is omitted when prices are unavailable (fail closed).
 */
export interface SessionStatsSnapshot {
    readonly entry_count: number;
    readonly total_cost_usd: number;
    readonly mean_cost_usd: number | null;
    readonly total_latency_ms: number;
    readonly mean_latency_ms: number | null;
    /** Share of entries with planning_delegate_path === 'delegate' (0–1), null if empty. */
    readonly planning_delegate_share: number | null;
    /** Share of entries with non-delegate path (direct / none / null). */
    readonly direct_share: number | null;
    /** Share classified as local (zero-tier) when distinguishable; null if none classified. */
    readonly local_share: number | null;
    /** Share classified as cloud when distinguishable; null if none classified. */
    readonly cloud_share: number | null;
    readonly role_cost: RoleCostBreakdown;
    /**
     * Estimated USD saved vs always-frontier baseline.
     * Formula: sum over entries with token counts of
     *   max(0, tokens/1e6 * frontier_cost_per_1m - estimated_cost_usd).
     * Omitted when frontier price inputs are missing (fail closed).
     */
    readonly frontier_savings_usd?: number;
}
export interface AggregateSessionStatsOptions {
    /**
     * USD per 1M tokens for the always-frontier baseline.
     * When absent / non-finite / ≤0, `frontier_savings_usd` is omitted.
     */
    readonly frontier_cost_per_1m?: number;
    /** Optional model_id → tier map (e.g. from fleet) for local vs cloud. */
    readonly tier_by_model_id?: ReadonlyMap<string, Tier>;
}
/** Mutually exclusive role for cost bucketing. */
export declare function classifyRoleCostBucket(entry: RoutingTelemetry): RoleCostBucket;
export declare function classifyDeployment(entry: RoutingTelemetry, tierByModelId?: ReadonlyMap<string, Tier>): DeploymentClass;
/**
 * Resolve always-frontier cost/1M from fleet + optional catalog.
 * Returns undefined when no positive frontier price is available (fail closed).
 */
export declare function resolveFrontierCostPer1M(fleet?: readonly ModelProfile[], catalog?: PriceCatalog | null): number | undefined;
/**
 * Pure aggregate over routing telemetry for operator stats.
 * Does not read or emit prompt/message/tool bodies.
 */
export declare function aggregateSessionStats(entries: readonly RoutingTelemetry[], options?: AggregateSessionStatsOptions): SessionStatsSnapshot;
/**
 * Optional vs-always-frontier savings. Returns undefined when price input is
 * missing or non-positive (fail closed) or when no entry has token counts.
 */
export declare function estimateFrontierSavingsUsd(entries: readonly RoutingTelemetry[], frontierCostPer1M: number | undefined): number | undefined;
/** Convenience: aggregate with fleet/catalog-derived tier map + frontier price. */
export declare function aggregateSessionStatsFromFleet(entries: readonly RoutingTelemetry[], fleet?: readonly ModelProfile[], catalog?: PriceCatalog | null): SessionStatsSnapshot;
/** Keys that must never appear on a stats snapshot (privacy). */
export declare const SESSION_STATS_FORBIDDEN_KEYS: readonly ["prompt", "prompt_text", "messages", "content", "tool_calls", "tool_args", "pepper"];
export declare function assertSessionStatsPrivacySafe(snapshot: SessionStatsSnapshot): void;
//# sourceMappingURL=session-stats.d.ts.map