/**
 * Neutral context-usage metrics for deciding when a session needs compaction.
 */
import type { Api, Usage } from "@bastani/pi-ai/compat";
import type { AgentMessage } from "@earendil-works/pi-agent-core";
import type { SessionEntry, SessionProjection } from "../session-manager.ts";
export interface CompactionSettings {
    enabled: boolean;
    reserveTokens: number;
    /** Fraction of compactable context to keep. 0.3 is aggressive, 0.7 is light. */
    compression_ratio: number;
    /** Number of recent context-eligible messages to preserve in standard mode. */
    preserve_recent: number;
    /** Focus query for relevance-based pruning; auto-detected when omitted in settings/options. */
    query?: string;
}
export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
/**
 * Calculate active context-window tokens from provider usage.
 *
 * Prefer normalized component fields over `totalTokens`: some providers expose
 * `totalTokens` as a billing/cumulative total, while the footer needs an active
 * context estimate. Some Anthropic-compatible endpoints mirror cached input in
 * both `input` and `cacheRead`/`cacheWrite`; only Anthropic Messages usage uses
 * the near-equal-bucket guard because OpenAI APIs expose disjoint normalized
 * components that must always be summed.
 */
export declare function calculateContextTokens(usage: Usage, api?: Api): number;
/**
 * Find the last non-aborted assistant message usage from session entries.
 */
export declare function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined;
export interface ContextUsageEstimate {
    tokens: number;
    usageTokens: number;
    trailingTokens: number;
    lastUsageIndex: number | null;
}
/**
 * Estimate context tokens from messages, using the last assistant usage when available.
 * If there are messages after the last usage, estimate their tokens with estimateTokens.
 */
export declare function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate;
/** Estimate projected context without trusting usage captured before a later edit or compaction. */
export declare function estimateProjectedContextTokens(projection: SessionProjection, branchEntries: SessionEntry[]): ContextUsageEstimate;
/**
 * Check if compaction should trigger based on context usage.
 */
export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
/**
 * Shared image-token estimation used by every compaction/context-accounting path.
 *
 * Providers fold image tokens into their reported prompt/input usage, so usage-based
 * accounting already captures actual image cost. For heuristic paths (trailing
 * messages without usage, transcript content-block estimates) a single conservative
 * fixed estimate keeps both the context-window threshold check and the transcript
 * planner consistent.
 */
export declare const ESTIMATED_IMAGE_CHARS = 4800;
export declare const ESTIMATED_IMAGE_TOKENS: number;
/** Estimate one raw content block after the caller applies provider visibility. */
export declare function estimateContentBlockTokens(block: unknown, visible?: boolean): number;
/**
 * Count image content blocks in a message content array (text or block array).
 *
 * Exported as the canonical image-counting contract so tests can verify the
 * heuristic independently of the transcript-based estimation used in production.
 */
export declare function countImageContentBlocks(content: string | Array<{
    type: string;
}>): number;
/**
 * Estimate the token cost of only the image content blocks in a message content array.
 *
 * Exported as the canonical image-token-estimation contract so tests can verify
 * the heuristic independently of the transcript-based estimation used in production.
 */
export declare function estimateImageContentTokens(content: string | Array<{
    type: string;
}>): number;
/**
 * Estimate token count for a message using chars/4 heuristic.
 * This is conservative (overestimates tokens).
 */
export declare function estimateTokens(message: AgentMessage): number;
//# sourceMappingURL=compaction.d.ts.map