/**
 * One-time "context is approaching auto-compaction" warning.
 *
 * The smart models auto-compact once the session context reaches the absolute
 * cap (default 500k tokens — see `resolveAutoCompactTokenCap` in
 * `../context-window-guard.ts`). This module owns the threshold math for the
 * user-facing heads-up that fires when a session crosses
 * `AUTO_COMPACT_WARNING_SHARE` (85%) of that effective cap, plus the
 * per-session "warned once" state.
 *
 * State is in-memory by design: a gateway restart re-warning once is fine.
 * The flag re-arms two ways:
 *  - explicitly via `resetContextTokenWarning` when a compaction completes
 *  - implicitly (hysteresis) whenever the observed usage drops back below the
 *    warn threshold (manual /compact, /new, session reset...), so a missed
 *    reset can never permanently silence the warning.
 */
export declare const AUTO_COMPACT_WARNING_SHARE = 0.85;
export type ContextWarningUsage = {
    input?: number;
    output?: number;
    cacheRead?: number;
    cacheWrite?: number;
    total?: number;
};
/**
 * Estimate the session's context tokens from a turn's usage — the same
 * arithmetic the runner's diagnostics use (prompt side includes cache
 * reads/writes; `total` wins when the provider reports it).
 */
export declare function estimateContextTokensFromUsage(usage: ContextWarningUsage | undefined | null): number | null;
/** 430_000 -> "430k", 1_000_000 -> "1m", 1_250_000 -> "1.3m", 900 -> "900". */
export declare function formatContextTokens(tokens: number): string;
export type ContextWarningDecision = {
    shouldWarn: boolean;
    usedTokens: number;
    capTokens: number;
    warnAtTokens: number;
    text: string;
};
/**
 * Pure threshold math: warn once `usedTokens` crosses `warnShare` (default
 * 85%) of the effective cap. `capTokens` must already be the effective
 * compaction window, i.e. min(model contextWindow, autoCompactTokens).
 */
export declare function evaluateContextTokenWarning(params: {
    usedTokens: number | null | undefined;
    capTokens: number | null | undefined;
    warnShare?: number;
}): ContextWarningDecision | null;
/**
 * One-shot gate around {@link evaluateContextTokenWarning}: returns the
 * warning line the first time a session crosses the threshold, null after
 * that. Dropping back below the threshold re-arms the warning.
 */
export declare function noteContextTokenWarning(params: {
    sessionKey: string | null | undefined;
    usedTokens: number | null | undefined;
    capTokens: number | null | undefined;
}): string | null;
/** Re-arm the warning for a session (called when a compaction completes). */
export declare function resetContextTokenWarning(sessionKey: string | null | undefined): void;
export declare const __testing: {
    readonly clearAll: () => void;
    readonly size: () => number;
};