/**
 * Cache Trace Debugging (OpenClaw-inspired)
 *
 * Logs every stage of prompt construction for debugging
 * cache hit/miss issues and context building.
 *
 * Enable via CACHE_TRACE=true environment variable.
 */
export type TraceStage = 'session_loaded' | 'session_sanitized' | 'history_truncated' | 'system_prompt_built' | 'tools_selected' | 'context_compressed' | 'images_processed' | 'stream_started' | 'stream_completed' | 'post_run' | 'cache_hit' | 'cache_miss' | 'compaction_triggered' | 'compaction_completed';
export interface TraceEntry {
    stage: TraceStage;
    timestamp: number;
    durationMs?: number;
    tokenCount?: number;
    messageCount?: number;
    metadata?: Record<string, unknown>;
}
/**
 * Cache trace debugger.
 * Records timing and token counts at each stage of prompt construction.
 */
export declare class CacheTrace {
    private enabled;
    private entries;
    private stageStartTimes;
    private sessionId;
    constructor(sessionId?: string);
    /**
     * Record a trace entry for a completed stage.
     */
    trace(stage: TraceStage, metadata?: Record<string, unknown> & {
        tokenCount?: number;
        messageCount?: number;
    }): void;
    /**
     * Mark the start of a stage (for duration tracking).
     */
    start(stage: TraceStage): void;
    /**
     * End a stage and record the trace with duration.
     */
    end(stage: TraceStage, metadata?: Record<string, unknown> & {
        tokenCount?: number;
        messageCount?: number;
    }): void;
    /**
     * Get all trace entries.
     */
    getEntries(): TraceEntry[];
    /**
     * Get a summary of the trace.
     */
    getSummary(): string;
    clear(): void;
    isEnabled(): boolean;
}
