/** 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;
/** The two config keys that govern prompt caching for a request. */
export interface CachePolicyReader {
    get(key: 'cache.enabled'): unknown;
    get(key: 'cache.stableTtl'): unknown;
}
/**
 * The strategy for a request, with `cache.enabled` and `cache.stableTtl` applied.
 *
 * The capability-derived strategy above answers "what CAN this provider cache".
 * This answers "what has the operator asked for", which is a separate question
 * that nothing used to ask: `cache.enabled` was read by nobody, so the only way
 * to stop paying cache writes was to switch provider, and `cache.stableTtl` fed
 * `CacheContext.configuredTtl`, which no caller populated, so the enum's '5m'
 * position produced 1h TTLs like its '1h' one.
 *
 * `enabled: false` returns the no-op strategy: no breakpoints, so no
 * `cache_control` is placed on any block and the request is billed as an
 * uncached one. It deliberately does not merely shorten the TTL, off means off.
 *
 * `config` is optional so a provider constructed without one (a direct
 * construction in a test, an embedder wiring only an API key) keeps the shipped
 * defaults: caching on, at the provider's longest stable TTL.
 */
export declare function resolveCacheStrategy(context: CacheContext, config?: CachePolicyReader | undefined): 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