erosolar-cli
Version:
Unified AI agent framework for the command line - Multi-provider support with schema-driven tools, code intelligence, and transparent reasoning
265 lines • 8.92 kB
TypeScript
/**
* ContextManager - Manages conversation context to prevent token limit leaks
*
* Responsibilities:
* - Truncate tool outputs intelligently
* - Prune old conversation history with LLM summarization
* - Track and estimate token usage
* - Keep conversation within budget based on model context windows
* - Proactively shrink context before hitting limits
*/
import type { ConversationMessage } from './types.js';
/**
* Callback for LLM-based summarization of conversation history
* Takes messages to summarize and returns a concise summary string
*/
export type SummarizationCallback = (messages: ConversationMessage[]) => Promise<string>;
/**
* Signals that indicate a good compaction point in the conversation
*/
export interface CompactionSignal {
type: 'task_boundary' | 'topic_shift' | 'milestone' | 'context_saturation' | 'user_pivot' | 'ai_flow_pattern';
confidence: number;
messageIndex: number;
reason: string;
metadata?: Record<string, unknown>;
}
/**
* AI Flow Patterns for intelligent context management
*/
export interface AIFlowPattern {
patternId: string;
description: string;
toolSequence: string[];
contextImpact: number;
compactionOpportunity: boolean;
preservationPriority: number;
}
/**
* Enhanced compaction analysis with AI flow awareness
*/
export interface EnhancedCompactionAnalysis {
shouldCompact: boolean;
signals: CompactionSignal[];
recommendedCompactionPoint: number | null;
urgency: 'none' | 'low' | 'medium' | 'high' | 'critical';
preserveFromIndex: number;
aiFlowPatterns: AIFlowPattern[];
estimatedTokenSavings: number;
riskAssessment: {
informationLossRisk: 'low' | 'medium' | 'high';
continuityRisk: 'low' | 'medium' | 'high';
recoveryDifficulty: 'easy' | 'moderate' | 'hard';
};
}
/**
* Result of intelligent compaction analysis
*/
export interface CompactionAnalysis {
shouldCompact: boolean;
signals: CompactionSignal[];
recommendedCompactionPoint: number | null;
urgency: 'none' | 'low' | 'medium' | 'high' | 'critical';
preserveFromIndex: number;
}
/**
* Summarization prompt template
*/
export declare const SUMMARIZATION_PROMPT = "Create a compact but reliable summary of the earlier conversation.\n\nKeep:\n- Decisions, preferences, and open questions\n- File paths, function/class names, APIs, and error messages with fixes\n- What was completed vs. still pending (tests, TODOs)\n\nFormat:\n## Key Context\n- ...\n## Work Completed\n- ...\n## Open Items\n- ...\n\nConversation:\n{conversation}";
export interface ContextManagerConfig {
maxTokens: number;
targetTokens: number;
warningTokens?: number;
criticalTokens?: number;
maxToolOutputLength: number;
preserveRecentMessages: number;
estimatedCharsPerToken: number;
useLLMSummarization?: boolean;
summarizationCallback?: SummarizationCallback;
model?: string;
enableIntelligentCompaction?: boolean;
compactionThreshold?: number;
minSignalConfidence?: number;
taskBoundaryPatterns?: string[];
topicShiftSensitivity?: number;
enableAIFlowPatternDetection?: boolean;
aiFlowPatterns?: AIFlowPattern[];
}
/**
* Pre-defined AI Flow Patterns for intelligent context management
*/
export declare const DEFAULT_AI_FLOW_PATTERNS: AIFlowPattern[];
export interface TruncationResult {
content: string;
wasTruncated: boolean;
originalLength: number;
truncatedLength: number;
}
export declare class ContextManager {
private config;
constructor(config?: Partial<ContextManagerConfig>);
/**
* Truncate tool output intelligently
*/
truncateToolOutput(output: string, toolName: string): TruncationResult;
/**
* Intelligent truncation based on tool type
*/
private intelligentTruncate;
private truncateFileOutput;
private truncateSearchOutput;
private truncateBashOutput;
private truncateDefault;
/**
* Estimate tokens in a message
*/
estimateTokens(message: ConversationMessage): number;
/**
* Detect context overflow risk from recent tool usage patterns
*/
detectContextOverflowRisk(toolCalls: string[]): boolean;
/**
* Estimate total tokens in conversation
*/
estimateTotalTokens(messages: ConversationMessage[]): number;
/**
* Prune old messages when approaching limit
*
* Synchronously removes old messages to stay within budget.
* If LLM summarization is available and enabled, this method will be async.
*/
pruneMessages(messages: ConversationMessage[]): {
pruned: ConversationMessage[];
removed: number;
};
/**
* Prune messages with LLM-based summarization
*
* This is an async version that uses the LLM to create intelligent summaries
* instead of just removing old messages. Should be called BEFORE generation.
*/
pruneMessagesWithSummary(messages: ConversationMessage[], options?: {
force?: boolean;
}): Promise<{
pruned: ConversationMessage[];
removed: number;
summarized: boolean;
}>;
/**
* Check if we're approaching the limit
*/
isApproachingLimit(messages: ConversationMessage[]): boolean;
/**
* Get warning level for current context usage
* Returns: null (no warning), 'info' (<70%), 'warning' (70-90%), 'danger' (>90%)
*/
getWarningLevel(messages: ConversationMessage[]): 'info' | 'warning' | 'danger' | null;
/**
* Get a human-readable warning message
*/
getWarningMessage(messages: ConversationMessage[]): string | null;
/**
* Get context stats
*/
getStats(messages: ConversationMessage[]): {
totalTokens: number;
percentage: number;
isOverLimit: boolean;
isApproachingLimit: boolean;
};
/**
* Update configuration
*/
updateConfig(config: Partial<ContextManagerConfig>): void;
/**
* Default patterns that indicate task boundaries
*/
private static readonly DEFAULT_TASK_BOUNDARY_PATTERNS;
/**
* Patterns indicating topic/task shifts
*/
private static readonly TOPIC_SHIFT_PATTERNS;
/**
* Patterns indicating user pivots (abandoning current direction)
*/
private static readonly USER_PIVOT_PATTERNS;
/**
* Analyze the conversation to detect intelligent compaction points
*/
analyzeCompactionPoints(messages: ConversationMessage[]): CompactionAnalysis;
/**
* Detect task boundary signals
*/
private detectTaskBoundary;
/**
* Detect topic shift signals
*/
private detectTopicShift;
/**
* Detect user pivot signals (abandoning current direction)
*/
private detectUserPivot;
/**
* Detect context saturation (heavy tool output regions)
*/
private detectContextSaturation;
/**
* Detect milestone signals (significant accomplishments)
*/
private detectMilestone;
/**
* Check if content looks like a task conclusion
*/
private looksLikeConclusion;
/**
* Check if two contents represent different topics (simple heuristic)
*/
private isNewTopic;
/**
* Calculate urgency level based on token percentage
*/
private calculateUrgency;
/**
* Find the best compaction point from signals
*/
private findBestCompactionPoint;
/**
* Find a safe preservation point that doesn't break tool call chains
*/
private findSafePreservePoint;
/**
* Perform intelligent compaction based on analysis
* This method analyzes the conversation and compacts at the optimal point
*/
intelligentCompact(messages: ConversationMessage[]): Promise<{
compacted: ConversationMessage[];
analysis: CompactionAnalysis;
summarized: boolean;
}>;
/**
* Check if intelligent compaction should be triggered
* Call this before generation to proactively manage context
*/
shouldTriggerCompaction(messages: ConversationMessage[]): {
shouldCompact: boolean;
urgency: CompactionAnalysis['urgency'];
reason: string | null;
};
}
/**
* Create a default context manager instance with model-aware limits
*/
export declare function createDefaultContextManager(overrides?: Partial<ContextManagerConfig>, model?: string): ContextManager;
/**
* Format conversation messages into readable text for summarization
*/
export declare function formatMessagesForSummary(messages: ConversationMessage[]): string;
/**
* Create a summarization callback using the given provider
*/
export declare function createSummarizationCallback(provider: {
generate: (messages: ConversationMessage[], tools: unknown[]) => Promise<{
content?: string;
}>;
}): SummarizationCallback;
//# sourceMappingURL=contextManager.d.ts.map