/**
 * Context Management Types
 *
 * Types for managing agent context windows, including token tracking,
 * compaction, summarization, and filtering.
 */
import type { Message } from '../providers/types.js';
/**
 * Context categories for budget allocation
 *
 * Each category has its own budget, preventing one type of content
 * from consuming space meant for another.
 */
export type ContextCategory = 'system' | 'recentMessages' | 'toolResults' | 'history';
/**
 * Budget allocation percentages for each category
 * Must sum to 1.0 (100%)
 */
export interface BudgetAllocation {
    /**
     * System prompt allocation
     * @default 0.05 (5%)
     */
    system: number;
    /**
     * Recent messages (last N turns) allocation
     * @default 0.40 (40%)
     */
    recentMessages: number;
    /**
     * Tool results allocation
     * @default 0.25 (25%)
     */
    toolResults: number;
    /**
     * Older conversation history allocation
     * @default 0.30 (30%)
     */
    history: number;
}
/**
 * Budget information for a single category
 */
export interface CategoryBudgetInfo {
    /**
     * Allocation fraction (0.0 - 1.0)
     */
    allocated: number;
    /**
     * Allocated tokens based on maxContextTokens
     */
    allocatedTokens: number;
    /**
     * Currently used tokens in this category
     */
    used: number;
    /**
     * Remaining tokens available
     */
    remaining: number;
    /**
     * Utilization of this category (0.0 - 1.0)
     */
    utilization: number;
}
/**
 * Result of a pre-flight context check
 *
 * Call canAddContent() before adding content to check if action is needed.
 */
export interface PreflightResult {
    /**
     * Whether the content can be added without issues
     */
    allowed: boolean;
    /**
     * Whether an action is required before adding
     */
    requiresAction: boolean;
    /**
     * Recommended action to take
     */
    action?: 'compact' | 'summarize' | 'reject';
    /**
     * Which category needs action (for compact)
     */
    category?: ContextCategory;
    /**
     * Estimated tokens for the content to add
     */
    estimatedTokens: number;
    /**
     * Tokens remaining in the target category budget
     */
    budgetRemaining: number;
    /**
     * Human-readable recommendation
     */
    recommendation?: string;
}
/**
 * Verbosity levels for graceful degradation
 *
 * Tools should adapt their output based on context pressure.
 */
export type VerbosityLevel = 'full' | 'normal' | 'abbreviated' | 'minimal';
/**
 * Verbosity threshold configuration
 */
export interface VerbosityConfig {
    /**
     * Utilization threshold for 'full' verbosity (below this)
     * @default 0.50 (50%)
     */
    fullThreshold: number;
    /**
     * Utilization threshold for 'normal' verbosity (below this)
     * @default 0.80 (80%)
     */
    normalThreshold: number;
    /**
     * Utilization threshold for 'abbreviated' verbosity (below this)
     * @default 0.95 (95%)
     */
    abbreviatedThreshold: number;
}
/**
 * Context management configuration
 */
export interface ContextConfig {
    /**
     * Maximum tokens for the context window
     * @default 200000 (Claude's limit)
     */
    maxContextTokens: number;
    /**
     * Budget allocation for each category
     * Enables category-specific compaction
     */
    budget: BudgetAllocation;
    /**
     * Verbosity level thresholds
     * Controls graceful degradation
     */
    verbosity: VerbosityConfig;
    /**
     * Filtering configuration
     */
    filtering: FilteringConfig;
    /**
     * Compaction configuration
     */
    compaction: CompactionConfig;
    /**
     * Summarization configuration
     */
    summarization: SummarizationConfig;
}
/**
 * Filtering configuration - applied before adding to context
 */
export interface FilteringConfig {
    /**
     * Maximum tokens for a single tool result
     * Results larger than this will be truncated
     * @default 80000
     */
    maxToolResultTokens: number;
    /**
     * Maximum lines for file content
     * @default 500
     */
    maxFileLines: number;
    /**
     * Maximum lines for error traces
     * @default 50
     */
    maxErrorLines: number;
}
/**
 * Compaction configuration - replaces old content with file references
 */
export interface CompactionConfig {
    /**
     * Trigger compaction every N turns
     * @default 20
     */
    triggerInterval: number;
    /**
     * Trigger compaction when context utilization exceeds this threshold
     * @default 0.5 (50%)
     */
    triggerThreshold: number;
    /**
     * Number of recent turns to preserve (not compact)
     * @default 10
     */
    preserveRecentTurns: number;
    /**
     * Minimum tokens in a message to consider for compaction
     * @default 1000
     */
    minTokensToCompact: number;
}
/**
 * Summarization configuration - compresses entire history
 */
export interface SummarizationConfig {
    /**
     * Emit warning when context utilization exceeds this threshold
     * @default 0.80 (80%)
     */
    warningThreshold: number;
    /**
     * Trigger normal summarization when context utilization exceeds this threshold
     * @default 0.90 (90%)
     */
    triggerThreshold: number;
    /**
     * Trigger emergency summarization (fewer preserved messages)
     * @default 0.95 (95%)
     */
    emergencyThreshold: number;
    /**
     * Number of recent messages to preserve in normal mode
     * @default 6
     */
    preserveRecentMessages: number;
    /**
     * Number of recent messages to preserve in emergency mode
     * @default 4
     */
    emergencyPreserveMessages: number;
    /**
     * Maximum tokens for the summary
     * @default 2000
     */
    summaryMaxTokens: number;
    /**
     * Maximum summarization rounds before throwing error
     * @default 3
     */
    maxRounds: number;
    /**
     * Target utilization after summarization
     * @default 0.70 (70%)
     */
    targetUtilization: number;
}
/**
 * Result of a compaction operation
 */
export interface CompactionResult {
    /**
     * Number of messages before compaction
     */
    messagesBefore: number;
    /**
     * Number of messages after compaction
     */
    messagesAfter: number;
    /**
     * Total tokens before compaction
     */
    tokensBefore: number;
    /**
     * Total tokens after compaction
     */
    tokensAfter: number;
    /**
     * Files created during compaction (for reversibility)
     */
    filesCreated: string[];
}
/**
 * Result of a summarization operation
 */
export interface SummarizationResult {
    /**
     * Tokens in original conversation
     */
    originalTokens: number;
    /**
     * Tokens in summary
     */
    summaryTokens: number;
    /**
     * Number of messages preserved (not summarized)
     */
    messagesPreserved: number;
    /**
     * The generated summary text
     */
    summary: string;
    /**
     * Number of summarization rounds performed
     */
    rounds: number;
    /**
     * Whether emergency mode was used
     */
    emergency: boolean;
}
/**
 * Result of a filtering operation
 */
export interface FilteringResult {
    /**
     * Whether the content was filtered
     */
    filtered: boolean;
    /**
     * Original token count
     */
    originalTokens: number;
    /**
     * Token count after filtering
     */
    filteredTokens: number;
    /**
     * Path to file where full content was saved (if filtered)
     */
    savedToFile?: string;
}
/**
 * Context-related events
 */
export type ContextEvent = {
    type: 'context_warning';
    utilization: number;
    threshold: number;
} | {
    type: 'context_compacted';
    result: CompactionResult;
} | {
    type: 'context_summarized';
    result: SummarizationResult;
} | {
    type: 'content_filtered';
    result: FilteringResult;
};
/**
 * Context event handler
 */
export type ContextEventHandler = (event: ContextEvent) => void;
/**
 * Categorized messages for smart compaction
 */
export interface CategorizedMessages {
    /**
     * System prompt message(s)
     */
    system: Message[];
    /**
     * Recent messages (last N turns, never compacted)
     */
    recentMessages: Message[];
    /**
     * Messages containing tool results
     */
    toolResults: Message[];
    /**
     * Older conversation history
     */
    history: Message[];
    /**
     * Token counts per category
     */
    tokenCounts: Record<ContextCategory, number>;
    /**
     * Original message indices for reconstruction
     */
    originalIndices: Map<Message, number>;
}
/**
 * Options for smart compaction
 */
export interface SmartCompactOptions {
    /**
     * Function to generate LLM summary for history messages
     */
    generateSummary: (messages: Message[]) => Promise<string>;
    /**
     * Function to save content to a file (for tool results)
     */
    saveToFile: (content: string, index: number) => Promise<string>;
    /**
     * Number of recent turns to preserve (not compact)
     * @default from config.compaction.preserveRecentTurns
     */
    preserveRecentTurns?: number;
    /**
     * Target utilization after compaction (0-1)
     * @default from config.summarization.targetUtilization
     */
    targetUtilization?: number;
    /**
     * Whether to use emergency mode (more aggressive)
     * @default auto-detect based on utilization
     */
    emergency?: boolean;
}
/**
 * Result of smart compaction
 */
export interface SmartCompactionResult {
    /**
     * Total tokens before compaction
     */
    tokensBefore: number;
    /**
     * Total tokens after compaction
     */
    tokensAfter: number;
    /**
     * Per-category statistics
     */
    categoryStats: Record<ContextCategory, {
        tokensBefore: number;
        tokensAfter: number;
        action: 'preserved' | 'compacted' | 'summarized';
    }>;
    /**
     * Files created during tool result compaction
     */
    filesCreated: string[];
    /**
     * Generated summary (for history)
     */
    summary?: string;
    /**
     * Number of summarization rounds performed
     */
    summarizationRounds: number;
    /**
     * Whether emergency mode was used
     */
    emergency: boolean;
}
/**
 * Context statistics
 */
export interface ContextStats {
    /**
     * Current token count
     */
    currentTokens: number;
    /**
     * Maximum tokens allowed
     */
    maxTokens: number;
    /**
     * Current utilization (0.0 - 1.0)
     */
    utilization: number;
    /**
     * Number of messages in history
     */
    messageCount: number;
    /**
     * Number of turns (user message + assistant response pairs)
     */
    turnCount: number;
    /**
     * Number of compactions performed
     */
    compactionCount: number;
    /**
     * Number of summarizations performed
     */
    summarizationCount: number;
}