import { type CacheRetention, type PreparedContext, type Usage } from "@kenkaiiii/gg-ai";
import { type CacheTouch } from "./cache-expiry.js";
export interface CacheRequestObservation {
    provider: string;
    model: string;
    at: number;
    cacheRetention: CacheRetention;
    /** Request-shaping settings only; digested in memory, never logged. */
    settings: unknown;
    /** Route/account identity, digested in memory. Never pass credentials. */
    route: unknown;
}
type HistoryEdit = "tool_prune" | "compaction";
export interface CacheContextReport {
    stage: "prepared_context";
    request: number;
    changes: string[];
    messageCount: number;
    previousMessageCount: number;
    /** Logical-message prefix, NOT a provider token offset or exact HTTP-body comparison. */
    unchangedMessages: number;
    imagesBefore: number;
    imagesAfter: number;
    imagesDropped: number;
    pruneFreedTokensEstimate: number;
    sincePreviousRequestMs: number | null;
    requestedTtlExceeded: boolean;
    /** Possible signed-thinking prefix mismatch; not a server-confirmed rejection. */
    thinkingPrefixRiskBlocks: number;
    /** Existing Anthropic encoding removes these signed blocks from settled turns. */
    settledThinkingBlocks: number;
    fingerprintMs: number;
}
export interface CacheUsageReport extends CacheContextReport {
    promptTokens: number;
    cacheRead: number;
    cacheWrite: number;
    comparison: "first_request" | "compaction" | "route_changed" | "cache_unreported" | "comparable";
    /** Upper-bound proxy for repeated input not read from cache, not proven avoidable waste. */
    reprocessedPromptTokensEstimate: number | null;
    costStatus: "unavailable";
    ttftMs: number | null;
    providerDurationMs: number;
}
/** One per session. Retains only one completed snapshot and one in-flight snapshot, no payloads.
 * Failed/retried attempts never replace the last successful usage baseline. */
export declare class CacheDiagnostics {
    private completed;
    private pending;
    private edits;
    private freedTokens;
    private requests;
    private reportedCache;
    private lastTouch;
    /** Last successful cache-using request (real turn or prewarm), or null. */
    lastCacheTouch(): CacheTouch | null;
    /** Record a successful cache-using request that bypassed prepare/complete (prewarm). */
    noteCacheTouch(touch: CacheTouch): void;
    reset(): void;
    discardAttempt(): void;
    noteEdit(edit: HistoryEdit, freedTokens?: number): void;
    prepare(context: PreparedContext, input: CacheRequestObservation): CacheContextReport;
    complete(usage: Usage, timing: {
        ttftMs?: number;
        providerDurationMs: number;
    }): CacheUsageReport | undefined;
}
export {};