import type { Usage } from "@gajae-code/ai/core";
export interface CacheEconomicsPricing {
    input: number;
    cacheRead: number;
    cacheWrite: number;
}
export interface CacheEconomicsModelCost extends CacheEconomicsPricing {
    output: number;
}
export type CacheEconomicsBasis = {
    kind: "persisted-aggregate";
    costBreakdown: Usage["cost"];
} | {
    kind: "current-model-estimate";
    pricing: CacheEconomicsPricing;
};
export interface CacheEconomicsUsage {
    input: number;
    output?: number;
    cacheRead: number;
    cacheWrite: number;
    total?: number;
    cost?: {
        input?: number;
        output?: number;
        cacheRead?: number;
        cacheWrite?: number;
        total?: number;
    };
}
export interface CacheMissCostSummary {
    inputTokens: number;
    cacheReadTokens: number;
    cacheWriteTokens: number;
    inputCostUsd: number;
    cacheReadCostUsd: number;
    cacheWriteCostUsd: number;
    cacheHitRate: number | undefined;
    missPremiumUsd: number | undefined;
}
/**
 * How a detected cache-miss pattern is attributed, per issue #2020.
 *
 * - `actionable`: usage evidence points to a user-controllable cause and GJC
 *   has a concrete remediation.
 * - `diagnostic-only`: a miss pattern is observed but the cause is not
 *   determinable from usage alone; describe what is unknown, assert no cause.
 * - `provider-side-suspected`: the provider returned no cache activity, so the
 *   miss cannot be attributed to the user's prompt; not user-actionable.
 */
export type CacheMissAttribution = "actionable" | "diagnostic-only" | "provider-side-suspected";
export interface CacheBehaviorWarning {
    code: "expensive_cache_miss" | "cache_write_spike" | "provider_side_cache_miss";
    attribution: CacheMissAttribution;
    reason: string;
    /** Concrete remediation — present only when `attribution` is `actionable`. */
    nextStep?: string;
    /** What GJC cannot determine — present for non-actionable attributions. */
    unknown?: string;
    costUsd: number;
}
export interface CacheWarningBuildState {
    warningsEmitted: number;
}
export declare function computeCacheMissCostSummary(usage: CacheEconomicsUsage | undefined, basis: CacheEconomicsBasis): CacheMissCostSummary | undefined;
export declare function formatCacheMissSummaryLines(summary: CacheMissCostSummary): string[];
export declare function buildCacheBehaviorWarning(usage: Usage | undefined, model: {
    cost: CacheEconomicsModelCost;
} | undefined | null): CacheBehaviorWarning | undefined;
/**
 * Render a cache warning as a single transcript line. Actionable attributions
 * carry a concrete next step; non-actionable ones state what is unknown and,
 * for provider-side patterns, that the miss is not user-actionable — never
 * asserting a cause or blaming the provider (#2020).
 */
export declare function formatCacheWarningLine(warning: CacheBehaviorWarning): string;
export declare function buildCacheEconomicsWarning(usage: Usage | undefined, model: {
    cost: CacheEconomicsModelCost;
} | undefined | null, state: CacheWarningBuildState): string | undefined;