/**
 * Cache-benchmark model types.
 *
 * This is an offline, deterministic simulator of OpenAI-style automatic prompt
 * caching. It answers one question cheaply and reproducibly: what happens to
 * cacheRead / cacheWrite / input tokens (and therefore cost) when a compaction
 * or truncation strategy rewrites or drops part of the conversation?
 */
/** Per-1M-token pricing used to turn token counters into an estimated cost. */
export interface CachePricing {
    /** $/1M uncached prompt (input) tokens. */
    input: number;
    /** $/1M completion (output) tokens. */
    output: number;
    /** $/1M cached prompt tokens. */
    cacheRead: number;
}
export declare const DEFAULT_CACHE_PRICING: CachePricing;
/** A single synthetic entry appended to (or injected into) the prompt. */
export interface PromptEntry {
    /** Stable id for this entry; summaries use negative ids. */
    id: number;
    /** Deterministic text serialized into the request. */
    text: string;
    /** Estimated token count for this entry. */
    tokens: number;
    /** Distinguishes real turns from injected compaction summaries. */
    kind: "turn" | "summary";
}
/** Mutable per-strategy state carried across turns. */
export interface StrategyState {
    /** Ordered prompt entries currently in the active prefix (oldest first). */
    entries: PromptEntry[];
}
/** Accounting for the context a cut destroyed (feeds quality/duration metrics). */
export interface LostContext {
    /** Raw prompt tokens removed from the live prefix by this cut. */
    droppedTokens: number;
    /** Tokens of the replacement summary (0 for hard truncation). */
    summaryTokens: number;
}
/** Result of one strategy step. */
export interface StrategyStep {
    /** Ordered entries to send this turn (oldest first). */
    entries: PromptEntry[];
    /** True when this turn dropped or summarized part of the history (a cache breakpoint). */
    cut: boolean;
    /** Present when this turn dropped part of the history. */
    lost?: LostContext;
}
export interface CacheStrategy {
    name: string;
    init(): StrategyState;
    step(state: StrategyState, turn: number, entry: PromptEntry): StrategyStep;
}
/** Configuration for the prefix-cache simulator. */
export interface PrefixCacheConfig {
    sessionId?: string;
    /** OpenAI only caches prefixes of at least this many tokens. */
    minCacheTokens: number;
    /** "none" disables cache accounting entirely (no reads/writes). */
    cacheRetention?: "none" | "short" | "long";
}
/** One turn of prefix-cache accounting. */
export interface PrefixCacheTurnResult {
    /** Total prompt tokens sent (cached + uncached). */
    promptTokens: number;
    /** Prompt tokens served from cache. */
    cacheReadTokens: number;
    /** Prompt tokens not served from cache (== cacheWriteTokens in spectral usage semantics). */
    inputTokens: number;
    /** Prompt tokens written to cache this turn (the uncached prompt). */
    cacheWriteTokens: number;
    /** Completion tokens billed this turn. */
    outputTokens: number;
    /** Raw longest-common-prefix token count before the minimum-cache threshold. */
    commonPrefixTokens: number;
    /** Whether any prompt tokens were served from cache this turn. */
    cacheHit: boolean;
}
/** Aggregate result for one strategy over a full scenario. */
export interface BenchmarkResult {
    name: string;
    turns: number;
    cutCount: number;
    totalPromptTokens: number;
    totalInputTokens: number;
    totalOutputTokens: number;
    totalCacheReadTokens: number;
    totalCacheWriteTokens: number;
    /** cacheRead / prompt tokens, in [0, 1]. */
    cacheHitRate: number;
    avgPromptTokens: number;
    maxPromptTokens: number;
    finalPromptTokens: number;
    /** Raw context tokens dropped by cuts (oldest-first history removed). */
    totalDroppedTokens: number;
    /** Replacement summary tokens injected by cuts. */
    totalSummaryTokens: number;
    /**
     * Fraction of dropped context NOT carried forward by a summary, in [0, 1].
     * 0 == nothing lost, 1 == hard truncation destroyed everything.
     */
    contextLossRate: number;
    /** Extra uncached input tokens from forced re-reads of hard-lost context. */
    totalReReadTokens: number;
    /** First-order duration proxy: how many extra turns those re-reads add. */
    reReadTurns: number;
    /** Dollar cost of the re-read recovery tokens. */
    reReadCost: number;
    totalCost: number;
    costPerTurn: number;
    /** Percent cost delta vs the keep-all baseline (0 == same cost). */
    costVsKeepAllPct: number;
}
/** Scenario configuration for a benchmark run. */
export interface BenchmarkConfig {
    turns: number;
    systemPromptTokens: number;
    toolsTokens: number;
    /** Prompt tokens appended per turn. Number or per-turn factory. */
    turnPromptTokens: number | ((turn: number) => number);
    /** Completion tokens billed per turn. Number or per-turn factory. */
    turnOutputTokens: number | ((turn: number) => number);
    pricing?: Partial<CachePricing>;
    /** OpenAI only caches prefixes of at least this many tokens. */
    minCacheTokens?: number;
    sessionId?: string;
    /**
     * When a cut hard-loses context (dropped without a summary), the agent must
     * re-read it. This is the fraction of hard-lost tokens re-injected as new
     * uncached input. 0 disables recovery modeling (default); 1 means the agent
     * fully re-reads everything it destroyed.
     */
    reReadFraction?: number;
}
//# sourceMappingURL=types.d.ts.map