/**
 * Cache Control Utilities for Claude Models
 *
 * This module provides utilities for adding cache_control markers to Claude models
 * to optimize token usage and reduce costs. Cache control is only applied to Claude
 * models and preserves backward compatibility with existing message formats.
 */
import type { ChatCompletionMessageParam, ChatCompletionContentPart, ChatCompletionContentPartText, CompletionUsage } from "openai/resources";
import type { ModelCapabilities } from "../types/config.js";
/**
 * Cache control directive for Claude models
 */
export interface CacheControl {
    type: "ephemeral";
}
/**
 * Extended text content part with cache control support
 */
export interface ClaudeChatCompletionContentPartText extends ChatCompletionContentPartText {
    type: "text";
    text: string;
    cache_control?: CacheControl;
}
/**
 * Extended prompt_tokens_details with cache_creation_input_tokens
 * Some models (e.g. Gemini, DeepSeek) return this field inside prompt_tokens_details
 */
export interface ExtendedPromptTokensDetails extends CompletionUsage.PromptTokensDetails {
    cache_creation_input_tokens?: number;
}
/**
 * Enhanced usage metrics including cache information
 * Supports both Claude-specific top-level fields and OpenAI-standard prompt_tokens_details
 */
export interface ClaudeUsage extends CompletionUsage {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
    cache_read_input_tokens?: number;
    cache_creation_input_tokens?: number;
    cache_creation?: {
        ephemeral_5m_input_tokens: number;
        ephemeral_1h_input_tokens: number;
    };
    prompt_tokens_details?: ExtendedPromptTokensDetails;
}
/**
 * Validates cache control structure
 * @param control - Object to validate
 * @returns True if valid cache control object
 */
export declare function isValidCacheControl(control: unknown): control is CacheControl;
/**
 * Adds cache control markers to message content
 * @param content - Original content (string or structured)
 * @param shouldCache - Whether to add cache control
 * @returns Structured content with cache control markers
 */
export declare function addCacheControlToContent(content: string | ChatCompletionContentPart[], shouldCache: boolean): ClaudeChatCompletionContentPartText[];
/**
 * Counts the total number of content blocks across all messages.
 * Each element in a message's content array counts as one block.
 * String content counts as one block. Null/undefined content counts as zero
 * (e.g. assistant messages with only tool_calls).
 * @param messages - Array of chat messages
 * @returns Total content block count
 */
export declare function countContentBlocks(messages: ChatCompletionMessageParam[]): number;
/**
 * Transforms messages for explicit cache control.
 *
 * Cache breakpoints (following Claude Code's "last message marker" strategy):
 * 1. System message — always marked (stable prefix)
 * 2. Last message — the last user/assistant message with content is marked.
 *    The API scans backward from this marker within 20 blocks. Since each
 *    turn adds ~2 blocks (< 20), the previous request's marker position
 *    always falls within the scan window, ensuring cache hits.
 *
 * Tools are marked separately via addCacheControlToLastTool (called by aiService).
 *
 * @param messages - Original OpenAI message array
 * @param capabilities - Declarative model capabilities for cache detection
 * @returns Messages with cache control markers applied
 */
export declare function transformMessagesForExplicitCache(messages: ChatCompletionMessageParam[], capabilities?: ModelCapabilities): ChatCompletionMessageParam[];
/**
 * Extends standard usage with cache metrics
 * Extracts cache tokens from both Claude-specific top-level fields and
 * OpenAI-standard prompt_tokens_details (used by Gemini, DeepSeek, etc.)
 * @param standardUsage - OpenAI usage response
 * @param cacheMetrics - Additional cache metrics from the API response
 * @returns Extended usage with cache information
 */
export declare function extendUsageWithCacheMetrics(standardUsage: CompletionUsage, cacheMetrics?: Partial<ClaudeUsage>): ClaudeUsage;
/**
 * Validates Claude usage structure
 * @param usage - Usage object to validate
 * @returns True if usage structure is valid
 */
export declare function isValidClaudeUsage(usage: unknown): usage is ClaudeUsage;