/** Position where a cache breakpoint should be placed. */
export type BreakpointPosition = 'system_and_tools' | 'conversation_prefix' | 'last_tool_result' | 'dynamic';
/** A single cache breakpoint instruction. */
export interface CacheBreakpoint {
    position: BreakpointPosition;
    ttl: string;
    ttlSeconds: number;
    reason: string;
}
/** Complete cache strategy for a provider request. */
export interface CacheStrategy {
    /** Breakpoints to place (for explicit providers only). Ordered by position in content. */
    breakpoints: CacheBreakpoint[];
    /** Whether prefix stability should be enforced (universal — true for all caching providers). */
    prefixStable: boolean;
    /** Session affinity header to send (for providers like Fireworks). */
    sessionAffinityHeader?: string | undefined;
    /** Keep-alive duration hint for local runtimes (seconds, -1 = indefinite). */
    keepAliveSeconds?: number | undefined;
    /** Re-evaluate strategy after this many turns. */
    refreshAfterTurns: number;
}
/** Context needed to generate a cache strategy. */
export interface CacheContext {
    providerName: string;
    systemPromptTokens: number;
    toolCount: number;
    toolTokens: number;
    conversationTurns: number;
    conversationTokens: number;
    /** Recent cache hit rate (0-1). Undefined if not yet tracked. */
    recentCacheHitRate?: number | undefined;
    /** Whether the user has configured a custom TTL preference. Accepts any TTL label string to accommodate future provider options. */
    configuredTtl?: string | undefined;
}
/** Cache hit rate tracking. */
export interface CacheHitMetrics {
    totalInputTokens: number;
    cacheReadTokens: number;
    cacheWriteTokens: number;
    /** Computed hit rate: cacheReadTokens / (totalInputTokens + cacheReadTokens) */
    hitRate: number;
    /** Number of turns tracked. */
    turns: number;
}
/**
 * Generate the default cache strategy for a provider based on its capabilities.
 */
export declare function getDefaultStrategy(context: CacheContext): CacheStrategy;
/**
 * CacheHitTracker — tracks cache hit rate over a sliding window of turns.
 */
export declare class CacheHitTracker {
    private metrics;
    /**
     * Record usage from a single turn.
     *
     * @param usage.inputTokens - Non-cached input tokens for this turn (tokens NOT served from
     *   cache). On Anthropic, this corresponds to `usage.input_tokens` (exclusive of cached
     *   tokens). Do NOT include cache_read_input_tokens or cache_creation_input_tokens here.
     * @param usage.cacheReadTokens - Tokens served from cache (cache hits).
     * @param usage.cacheWriteTokens - Tokens written to cache this turn (cache creation).
     */
    recordTurn(usage: {
        inputTokens: number;
        cacheReadTokens?: number | undefined;
        cacheWriteTokens?: number | undefined;
    }): void;
    /** Get current metrics. */
    getMetrics(): Readonly<CacheHitMetrics>;
    /** Get current hit rate (0-1). */
    getHitRate(): number;
    /** Reset metrics (e.g., after strategy refresh). */
    reset(): void;
}
//# sourceMappingURL=cache-strategy.d.ts.map