import type { AgentMessage } from '@earendil-works/pi-agent-core';
import { type CompactionPreparation, type CompactionSettings } from '@earendil-works/pi-agent-core';
/** Late-compaction defaults for ~1M-class windows (clamped on smaller windows). */
export declare const DEFAULT_COMPACT_RESERVE_TOKENS = 48000;
export declare const DEFAULT_COMPACT_KEEP_RECENT_TOKENS = 32000;
export declare const DEFAULT_CLEAR_KEEP_TOOL_USES = 8;
/** Soft ceiling for the auto clear-trigger (15% of window, bounded below). */
export declare const DEFAULT_CLEAR_TRIGGER_CAP = 150000;
export declare const DEFAULT_CLEAR_TRIGGER_FLOOR = 50000;
/**
 * Lookahead pad: assume one more hop may grow context by this many tokens
 * (assistant prose + follow-up tools). Mid-turn clear/compact fire earlier by
 * this amount. 0 disables foresight (hard line only).
 */
export declare const DEFAULT_LOOKAHEAD_TOKENS = 24000;
/** Placeholder prefix so we never double-clear the same result. */
export declare const CLEARED_TOOL_RESULT_PREFIX = "[cleared tool_result:";
/** Stable activity label for web chat "compacting" status steps (i18n maps this). */
export declare const COMPACTION_ACTIVITY_LABEL = "Compacting context";
/** Default tools whose results must survive clearing (state / memory / UX). */
export declare const DEFAULT_CLEAR_EXCLUDE_TOOLS: readonly ["memory", "memory_save", "memory_query", "save_memo", "search_memos", "update_memo", "delete_memo", "long_task", "complete_goal", "ask_user", "push_message"];
export interface ToolClearingSettings {
    enabled: boolean;
    /** Estimated context tokens above which clearing runs. */
    triggerTokens: number;
    /** Keep this many most-recent toolResult messages intact. */
    keepToolUses: number;
    /** Skip clearing when fewer than this many chars would be freed. */
    clearAtLeastChars: number;
    /** Tool-name patterns (case-insensitive; matched as exact / suffix / __name). */
    excludeTools: string[];
}
export interface ContextBudgetSettings {
    clearing: ToolClearingSettings;
    compaction: CompactionSettings;
    /**
     * Extra tokens assumed for the *next* model hop when deciding mid-turn
     * emergency clear / compact. Softens the late-compaction line without
     * changing pre-turn shouldCompact.
     */
    lookaheadTokens: number;
    /** Replaces pi's default summarization framing when non-empty. */
    compactInstructions: string | undefined;
}
export interface ClearToolResultsResult {
    messages: AgentMessage[];
    clearedCount: number;
    charsFreed: number;
    applied: boolean;
}
/**
 * Compaction master switch. Prefer `AGIM_CTX_COMPACT`; legacy
 * `AGIM_NATIVE_COMPACTION=off` still disables.
 */
export declare function isContextCompactionEnabled(): boolean;
/** Clamp a target so small windows cannot reserve/keep more than a safe share. */
export declare function clampToWindowShare(target: number, window: number, maxShare: number, floor: number): number;
/**
 * Session-scoped compression-rate preset (压缩率).
 * Global default is always `auto` (window-scaled env defaults).
 *   - full (满压): wait until near full window before L2 compact
 *   - balanced (均衡): mid reserve
 *   - frequent (频繁): compact earlier / more often
 */
export type CompactRate = 'auto' | 'full' | 'balanced' | 'frequent';
export declare const COMPACT_RATE_IDS: readonly CompactRate[];
/** Reserve as a share of the model window (before clamp). Keep SPA mirror in sync. */
export declare const COMPACT_RATE_RESERVE_SHARE: Record<Exclude<CompactRate, 'auto'>, number>;
export declare const COMPACT_RATE_KEEP_SHARE: Record<Exclude<CompactRate, 'auto'>, number>;
/** Extra headroom when judging whether a rate is safe vs current used tokens. */
export declare const COMPACT_RATE_USED_SAFETY = 1.1;
export declare function normalizeCompactRate(raw: string | undefined | null): CompactRate;
export declare function reserveTokensForCompactRate(contextWindow: number, rate: CompactRate, autoReserve: number): number;
export declare function keepRecentTokensForCompactRate(contextWindow: number, rate: CompactRate, autoKeep: number): number;
/** Hard line for a compact-rate choice (uses auto reserve when rate=auto). */
export declare function hardLineForCompactRate(contextWindow: number, rate: CompactRate, autoReserve: number): number;
/**
 * True when choosing `rate` would keep the hard line at/above current used
 * (with safety margin). Approximate SPA estimates should pass used*margin.
 */
export declare function isCompactRateSafe(contextWindow: number, usedTokens: number, rate: CompactRate, autoReserve: number, safety?: number): boolean;
/** Resolve budget knobs from env (+ optional session compact-rate overlay). */
export declare function resolveContextBudgetSettings(contextWindow?: number, compactRate?: CompactRate | string | null): ContextBudgetSettings;
/** Hard late-compaction line: window − reserve. */
export declare function hardBudgetLine(contextWindow: number, reserveTokens: number): number;
/**
 * Soft line used for mid-turn foresight: hard line minus lookahead pad.
 * When lookahead is 0, soft === hard.
 */
export declare function softBudgetLine(contextWindow: number, reserveTokens: number, lookaheadTokens: number): number;
/** Projected tokens for the next hop = current estimate + lookahead pad. */
export declare function projectNextHopTokens(currentTokens: number, lookaheadTokens: number): number;
/** Agim-tuned compaction brief (cookbook: custom instructions fully replace the default). */
export declare const DEFAULT_AGIM_COMPACT_INSTRUCTIONS: string;
export declare function isExcludedToolName(toolName: string, excludeTools: readonly string[]): boolean;
/** Estimate tokens for a message list (pi heuristic). */
export declare function estimateMessagesTokens(messages: AgentMessage[]): number;
/**
 * Clear old toolResult payloads, keeping the most recent `keepToolUses`.
 * Returns the original array reference when nothing changes.
 */
export declare function clearToolResultsInMessages(messages: AgentMessage[], settings: ToolClearingSettings): ClearToolResultsResult;
/** Apply clearing to compaction preparation message lists (summarizer input). */
export declare function applyClearingToPreparation(preparation: CompactionPreparation, settings: ToolClearingSettings): CompactionPreparation;
/**
 * Mid-turn budget guard (late-compaction companion).
 *
 * Pre-turn L2 compact only runs once per user message. If tools inflate the
 * window during the turn past `contextWindow - reserveTokens`, we cannot
 * always afford a second summarization round-trip — but we *can* urgently
 * strip re-fetchable tool payloads so the next model call still fits.
 *
 * Returns `{ messages, emergency }` where `emergency` is true when the
 * aggressive path ran. No UI — logs only (operator preference).
 */
export declare function applyContextBudgetToMessages(messages: AgentMessage[], budget: ContextBudgetSettings, contextWindow: number): {
    messages: AgentMessage[];
    emergency: boolean;
    cleared: ClearToolResultsResult;
};
//# sourceMappingURL=context-budget.d.ts.map