/**
 * Response Cache: cache local determinístico de respostas de modelo.
 *
 * Distinto do prompt caching do provider (`llm/prompt-cache.ts`), que barateia
 * o PREFIXO de uma chamada que ainda acontece. Aqui a chamada não acontece: a
 * mesma (provider, modelo, system, mensagens, teto de saída, temperatura)
 * devolve a resposta gravada, custo zero e latência de disco.
 *
 * Por que é seguro: a chave inclui TODAS as entradas que alteram a saída.
 * Temperatura acima de 0 continua sendo cacheada de propósito (o objetivo é
 * reexecutar um run idêntico sem repagar), mas o cache é OPT-IN justamente
 * porque essa é uma escolha do usuário, não um default silencioso.
 *
 * Invalidação: TTL por entrada e versão de esquema na chave. Um artefato
 * gravado por uma versão anterior do formato nunca é lido pela nova.
 */
export interface CacheKeyInput {
    provider: string;
    model: string;
    system?: string;
    messages: Array<{
        role: string;
        content: string;
    }>;
    maxTokens?: number;
    temperature?: number;
    /**
     * Política de tools do executor de processo, quando houver. Entra na chave
     * porque muda o que a resposta pôde ver: a mesma pergunta respondida com
     * leitura do repositório é outra resposta, e servir uma pela outra seria um
     * hit que mente sobre a evidência que produziu o artefato.
     */
    toolPolicy?: string;
}
export interface CachedResponse {
    text: string;
    tokens: number;
    model: string;
    provider: string;
    /** Momento em que a resposta original foi gravada. */
    storedAt: string;
    /** Tokens que a chamada original consumiu: é o que se economiza no hit. */
    originalTokens: number;
}
export interface ResponseCacheOptions {
    baseDir: string;
    enabled?: boolean;
    ttlMs?: number;
    maxEntries?: number;
}
export declare function cacheKey(input: CacheKeyInput): string;
export declare class ResponseCache {
    private readonly dir;
    readonly enabled: boolean;
    private readonly ttlMs;
    private readonly maxEntries;
    private hits;
    private misses;
    constructor(opts: ResponseCacheOptions);
    get stats(): {
        hits: number;
        misses: number;
    };
    private fileFor;
    /** Resposta gravada e ainda válida, ou null. Cache desligado sempre devolve null. */
    get(input: CacheKeyInput): CachedResponse | null;
    /** Grava a resposta. No-op com cache desligado ou resposta vazia. */
    set(input: CacheKeyInput, response: {
        text: string;
        tokens: number;
        model: string;
        provider: string;
    }): void;
    /** Mantém o cache dentro do teto removendo as entradas mais antigas. */
    private evict;
    /**
     * Registra o miss no Budget Controller quando o cache está ligado. Com cache
     * desligado não existe "miss": a chamada sempre aconteceria, então contar
     * inflaria artificialmente a taxa de erro do cache.
     */
    recordMissIfEnabled(budget?: {
        recordCacheMiss(): void;
    }): void;
    /** Apaga o cache inteiro. Devolve quantas entradas foram removidas. */
    clear(): number;
    /**
     * Ligado por `IZANAGI_CACHE=1` (ou `--cache` na CLI, que seta a env).
     * Default desligado: cachear resposta de modelo é uma decisão do usuário.
     */
    static enabledFromEnv(): boolean;
}
//# sourceMappingURL=response-cache.d.ts.map