mcp-agent-foundry 1.3.1 → 2.0.0

package/dist/router/context-manager.js

@@ -1,3 +1,760 @@
-export {};
-// TODO: Implement
+/**
+ * Context Manager
+ *
+ * Manages context window tracking, auto-compaction, and truncation
+ * for multi-provider agent orchestration. Tracks token usage across
+ * different providers and models with varying context limits.
+ *
+ * Key features:
+ * - Per-provider/model context limit tracking
+ * - Automatic compaction when approaching limits
+ * - Smart truncation that preserves important content
+ * - Context visualization for debugging
+ * - Event emission for monitoring
+ */
+// ============================================================================
+// Default Model Limits
+// ============================================================================
+/**
+ * Default context limits for known models.
+ * Values are in tokens.
+ */
+const DEFAULT_MODEL_LIMITS = {
+    // OpenAI
+    'gpt-4o': 128000,
+    'gpt-4o-mini': 128000,
+    'gpt-4-turbo': 128000,
+    'gpt-4-turbo-preview': 128000,
+    'gpt-4': 8192,
+    'gpt-3.5-turbo': 16385,
+    'o1': 128000,
+    'o1-mini': 128000,
+    'o1-preview': 128000,
+    'o3-mini': 128000,
+    // Anthropic
+    'claude-3-opus': 200000,
+    'claude-3-opus-20240229': 200000,
+    'claude-3-sonnet': 200000,
+    'claude-3-sonnet-20240229': 200000,
+    'claude-3-haiku': 200000,
+    'claude-3-haiku-20240307': 200000,
+    'claude-3-5-sonnet': 200000,
+    'claude-3-5-sonnet-20240620': 200000,
+    'claude-3-5-sonnet-20241022': 200000,
+    'claude-sonnet-4': 200000,
+    'claude-sonnet-4-20250514': 200000,
+    'claude-opus-4': 200000,
+    'claude-opus-4-20250514': 200000,
+    'claude-opus-4-5-20251101': 200000,
+    // Google
+    'gemini-2.0-flash': 1000000,
+    'gemini-2.0-flash-exp': 1000000,
+    'gemini-1.5-pro': 1000000,
+    'gemini-1.5-pro-latest': 1000000,
+    'gemini-1.5-flash': 1000000,
+    'gemini-1.5-flash-latest': 1000000,
+    'gemini-pro': 32768,
+    // DeepSeek
+    'deepseek-chat': 128000,
+    'deepseek-coder': 128000,
+    'deepseek-reasoner': 128000,
+    // Groq
+    'llama-3.3-70b-versatile': 32768,
+    'llama-3.1-70b-versatile': 32768,
+    'llama-3.1-8b-instant': 8192,
+    'mixtral-8x7b-32768': 32768,
+    'gemma2-9b-it': 8192,
+    // Perplexity
+    'llama-3.1-sonar-large-128k-online': 127072,
+    'llama-3.1-sonar-small-128k-online': 127072,
+    'llama-3.1-sonar-huge-128k-online': 127072,
+    // Together/Fireworks (common models)
+    'meta-llama/Llama-3.1-70B-Instruct': 131072,
+    'meta-llama/Llama-3.1-8B-Instruct': 131072,
+    'mistralai/Mixtral-8x7B-Instruct-v0.1': 32768,
+    // Ollama (local models - conservative defaults)
+    'llama3': 8192,
+    'llama3:70b': 8192,
+    'codellama': 16384,
+    'mistral': 8192,
+    'mixtral': 32768,
+};
+/**
+ * Characters per token ratio by provider.
+ * Used for token estimation when exact counting isn't available.
+ */
+const CHARS_PER_TOKEN = {
+    anthropic: 3.5,
+    openai: 4.0,
+    google: 4.0,
+    deepseek: 4.0,
+    groq: 4.0,
+    perplexity: 4.0,
+    together: 4.0,
+    fireworks: 4.0,
+    ollama: 4.0,
+    default: 4.0,
+};
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_CONFIG = {
+    defaultContextLimit: 128000,
+    autoCompactThreshold: 0.9,
+    blockingThreshold: 0.98,
+    maxToolResultTokens: 4096,
+    maxMessageTokens: 16384,
+    modelLimits: {},
+};
+// ============================================================================
+// Context Manager Class
+// ============================================================================
+/**
+ * Manages context window tracking and optimization for multi-provider
+ * agent orchestration.
+ *
+ * @example
+ * ```typescript
+ * const contextManager = new ContextManager({ autoCompactThreshold: 0.85 }, logger);
+ *
+ * // Check context state before making a request
+ * const state = contextManager.getState('openai', 'gpt-4o', messages);
+ * if (state.isBlocked) {
+ *   // Context too full, need to compact
+ *   messages = contextManager.compact(messages);
+ * }
+ *
+ * // Get detailed breakdown for debugging
+ * const breakdown = contextManager.getBreakdown(messages);
+ * console.log(contextManager.visualize(state, breakdown));
+ * ```
+ */
+export class ContextManager {
+    config;
+    logger;
+    listeners = new Set();
+    /**
+     * Create a new ContextManager instance.
+     *
+     * @param config - Partial configuration (merged with defaults)
+     * @param logger - Logger instance for observability
+     */
+    constructor(config, logger) {
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            modelLimits: {
+                ...DEFAULT_MODEL_LIMITS,
+                ...config.modelLimits,
+            },
+        };
+        this.logger = logger;
+        this.logger.debug('ContextManager initialized', {
+            autoCompactThreshold: this.config.autoCompactThreshold,
+            blockingThreshold: this.config.blockingThreshold,
+            defaultContextLimit: this.config.defaultContextLimit,
+        });
+    }
+    // ==========================================================================
+    // Public Methods - State Management
+    // ==========================================================================
+    /**
+     * Get the current context state for a provider/model combination.
+     *
+     * @param provider - Provider name (e.g., 'openai', 'anthropic')
+     * @param model - Model name (e.g., 'gpt-4o', 'claude-3-opus')
+     * @param messages - Current conversation messages
+     * @returns Current context state with usage metrics
+     */
+    getState(provider, model, messages) {
+        const maxTokens = this.getModelLimit(provider, model);
+        const usedTokens = this.estimateMessagesTokens(messages, provider);
+        const usedPercentage = (usedTokens / maxTokens) * 100;
+        const remainingPercentage = 100 - usedPercentage;
+        const remainingTokens = Math.max(0, maxTokens - usedTokens);
+        const isNearLimit = usedPercentage >= this.config.autoCompactThreshold * 100;
+        const isBlocked = usedPercentage >= this.config.blockingThreshold * 100;
+        const state = {
+            provider,
+            model,
+            usedTokens,
+            maxTokens,
+            usedPercentage: Math.round(usedPercentage * 100) / 100,
+            remainingPercentage: Math.round(remainingPercentage * 100) / 100,
+            remainingTokens,
+            isNearLimit,
+            isBlocked,
+        };
+        // Emit events based on state
+        if (isBlocked) {
+            this.emit({ type: 'context_blocked', state });
+        }
+        else if (isNearLimit) {
+            this.emit({
+                type: 'context_warning',
+                state,
+                message: `Context usage at ${usedPercentage.toFixed(1)}%, approaching limit`,
+            });
+        }
+        return state;
+    }
+    /**
+     * Check if the context should be auto-compacted.
+     *
+     * @param state - Current context state
+     * @returns True if compaction should be triggered
+     */
+    shouldCompact(state) {
+        return state.usedPercentage >= this.config.autoCompactThreshold * 100;
+    }
+    /**
+     * Check if the context is blocked (too full for new messages).
+     *
+     * @param state - Current context state
+     * @returns True if context is blocked
+     */
+    isBlocked(state) {
+        return state.isBlocked;
+    }
+    // ==========================================================================
+    // Public Methods - Token Estimation
+    // ==========================================================================
+    /**
+     * Estimate the number of tokens in a string.
+     *
+     * Uses a simple character-based approximation. For more accurate counting,
+     * consider integrating tiktoken or a provider-specific tokenizer.
+     *
+     * @param text - Text to estimate tokens for
+     * @param provider - Provider name for provider-specific ratios
+     * @returns Estimated token count
+     */
+    estimateTokens(text, provider = 'default') {
+        if (!text)
+            return 0;
+        const charsPerToken = CHARS_PER_TOKEN[provider] ?? CHARS_PER_TOKEN['default'] ?? 4.0;
+        return Math.ceil(text.length / charsPerToken);
+    }
+    /**
+     * Estimate tokens for a content block.
+     *
+     * @param block - Content block to analyze
+     * @param provider - Provider name for estimation
+     * @returns Estimated token count
+     */
+    estimateContentBlockTokens(block, provider = 'default') {
+        let tokens = 0;
+        const blockType = block.type;
+        switch (blockType) {
+            case 'text':
+                tokens = this.estimateTokens(block.text ?? '', provider);
+                break;
+            case 'tool_use': {
+                // Tool name + input JSON
+                // Use type assertion to access name property
+                const name = 'name' in block ? block.name : undefined;
+                tokens = this.estimateTokens(name ?? '', provider);
+                if (block.input) {
+                    tokens += this.estimateTokens(JSON.stringify(block.input), provider);
+                }
+                break;
+            }
+            case 'tool_result':
+                tokens = this.estimateTokens(block.content ?? '', provider);
+                break;
+            case 'image':
+                // Images are typically 85 tokens for low detail, up to 1445 for high detail
+                // Use a conservative estimate
+                tokens = 500;
+                break;
+            default:
+                // Unknown block type, estimate based on any text-like content
+                if ('text' in block && typeof block.text === 'string') {
+                    tokens = this.estimateTokens(block.text, provider);
+                }
+        }
+        return tokens;
+    }
+    /**
+     * Estimate tokens for a message.
+     *
+     * @param message - Message to analyze
+     * @param provider - Provider name for estimation
+     * @returns Estimated token count
+     */
+    estimateMessageTokens(message, provider = 'default') {
+        // Role token overhead (approximately 4 tokens for role markers)
+        let tokens = 4;
+        if (typeof message.content === 'string') {
+            tokens += this.estimateTokens(message.content, provider);
+        }
+        else if (Array.isArray(message.content)) {
+            for (const block of message.content) {
+                tokens += this.estimateContentBlockTokens(block, provider);
+            }
+        }
+        return tokens;
+    }
+    /**
+     * Estimate total tokens for an array of messages.
+     *
+     * @param messages - Messages to analyze
+     * @param provider - Provider name for estimation
+     * @returns Total estimated token count
+     */
+    estimateMessagesTokens(messages, provider = 'default') {
+        let total = 0;
+        for (const message of messages) {
+            total += this.estimateMessageTokens(message, provider);
+        }
+        // Add overhead for message structure (approximately 3 tokens per message boundary)
+        total += messages.length * 3;
+        return total;
+    }
+    // ==========================================================================
+    // Public Methods - Model Limits
+    // ==========================================================================
+    /**
+     * Get the context limit for a specific model.
+     *
+     * Looks up the model in the configured limits, falling back to
+     * DEFAULT_MODEL_LIMITS, then to the default context limit.
+     *
+     * @param provider - Provider name
+     * @param model - Model name
+     * @returns Context limit in tokens
+     */
+    getModelLimit(provider, model) {
+        // Check configured limits first
+        if (this.config.modelLimits[model]) {
+            return this.config.modelLimits[model];
+        }
+        // Check default limits
+        if (DEFAULT_MODEL_LIMITS[model]) {
+            return DEFAULT_MODEL_LIMITS[model];
+        }
+        // Try to match by prefix (e.g., 'gpt-4o-2024-05-13' matches 'gpt-4o')
+        for (const [knownModel, limit] of Object.entries(DEFAULT_MODEL_LIMITS)) {
+            if (model.startsWith(knownModel) || knownModel.startsWith(model)) {
+                return limit;
+            }
+        }
+        // Provider-specific defaults
+        const providerDefaults = {
+            anthropic: 200000,
+            google: 1000000,
+            openai: 128000,
+            deepseek: 128000,
+            groq: 32768,
+            perplexity: 127072,
+            together: 32768,
+            fireworks: 32768,
+            ollama: 8192,
+        };
+        if (providerDefaults[provider]) {
+            this.logger.debug('Using provider default limit', {
+                provider,
+                model,
+                limit: providerDefaults[provider],
+            });
+            return providerDefaults[provider];
+        }
+        // Fall back to configured default
+        this.logger.warn('Unknown model, using default context limit', {
+            provider,
+            model,
+            limit: this.config.defaultContextLimit,
+        });
+        return this.config.defaultContextLimit;
+    }
+    // ==========================================================================
+    // Public Methods - Truncation
+    // ==========================================================================
+    /**
+     * Truncate content to fit within a token limit.
+     *
+     * @param content - Content to truncate
+     * @param maxTokens - Maximum tokens allowed
+     * @param options - Truncation options
+     * @returns Truncated content
+     */
+    truncate(content, maxTokens, options) {
+        const result = this.truncateWithResult(content, maxTokens, options);
+        return result.content;
+    }
+    /**
+     * Truncate content with detailed result information.
+     *
+     * @param content - Content to truncate
+     * @param maxTokens - Maximum tokens allowed
+     * @param options - Truncation options
+     * @returns Truncation result with metadata
+     */
+    truncateWithResult(content, maxTokens, options) {
+        const opts = {
+            maxTokens,
+            position: options?.position ?? 'end',
+            suffix: options?.suffix ?? '... [truncated]',
+            prefix: options?.prefix ?? '',
+            preserveCodeBlocks: options?.preserveCodeBlocks ?? true,
+        };
+        const originalTokens = this.estimateTokens(content);
+        if (originalTokens <= maxTokens) {
+            return {
+                content,
+                originalTokens,
+                truncatedTokens: originalTokens,
+                wasTruncated: false,
+            };
+        }
+        // Calculate how many characters we can keep
+        const charsPerToken = CHARS_PER_TOKEN['default'] ?? 4.0;
+        const suffixTokens = this.estimateTokens(opts.suffix ?? '');
+        const prefixTokens = this.estimateTokens(opts.prefix ?? '');
+        const availableTokens = maxTokens - suffixTokens - prefixTokens;
+        const maxChars = Math.floor(availableTokens * charsPerToken);
+        let truncated;
+        switch (opts.position) {
+            case 'start':
+                truncated = opts.prefix + content.slice(-maxChars) + (opts.suffix ?? '');
+                break;
+            case 'middle': {
+                const halfChars = Math.floor(maxChars / 2);
+                const start = content.slice(0, halfChars);
+                const end = content.slice(-halfChars);
+                truncated = start + (opts.suffix ?? '') + end;
+                break;
+            }
+            case 'end':
+            default:
+                truncated = (opts.prefix ?? '') + content.slice(0, maxChars) + (opts.suffix ?? '');
+                break;
+        }
+        const truncatedTokens = this.estimateTokens(truncated);
+        this.emit({
+            type: 'truncation_applied',
+            originalTokens,
+            truncatedTokens,
+        });
+        return {
+            content: truncated,
+            originalTokens,
+            truncatedTokens,
+            wasTruncated: true,
+        };
+    }
+    // ==========================================================================
+    // Public Methods - Compaction
+    // ==========================================================================
+    /**
+     * Compact messages to reduce context usage.
+     *
+     * Strategy:
+     * 1. Truncate long tool results
+     * 2. Truncate long individual messages
+     * 3. Summarize/drop older messages if still over limit
+     *
+     * @param messages - Messages to compact
+     * @param targetReduction - Target reduction percentage (0-1, default 0.3)
+     * @returns Compacted messages array
+     */
+    compact(messages, targetReduction = 0.3) {
+        const originalTokens = this.estimateMessagesTokens(messages);
+        const targetTokens = originalTokens * (1 - targetReduction);
+        this.logger.info('Starting context compaction', {
+            originalTokens,
+            targetTokens,
+            messageCount: messages.length,
+        });
+        let compactedMessages = [...messages];
+        let currentTokens = originalTokens;
+        let strategy = 'truncate';
+        // Step 1: Truncate long tool results
+        compactedMessages = this.truncateToolResults(compactedMessages);
+        currentTokens = this.estimateMessagesTokens(compactedMessages);
+        if (currentTokens <= targetTokens) {
+            this.emitCompactionResult(originalTokens, currentTokens, messages.length, compactedMessages.length, strategy);
+            return compactedMessages;
+        }
+        // Step 2: Truncate long messages
+        compactedMessages = this.truncateLongMessages(compactedMessages);
+        currentTokens = this.estimateMessagesTokens(compactedMessages);
+        if (currentTokens <= targetTokens) {
+            this.emitCompactionResult(originalTokens, currentTokens, messages.length, compactedMessages.length, strategy);
+            return compactedMessages;
+        }
+        // Step 3: Drop older messages (keep first message as context, and recent messages)
+        strategy = 'hybrid';
+        const keepRecent = Math.max(4, Math.ceil(messages.length * 0.3));
+        const firstMessage = compactedMessages[0];
+        const recentMessages = compactedMessages.slice(-keepRecent);
+        if (firstMessage && compactedMessages.length > keepRecent + 1) {
+            // Keep first message (usually system context) and recent messages
+            compactedMessages = [firstMessage, ...recentMessages];
+            // Add a summary marker
+            const summaryMessage = {
+                role: 'assistant',
+                content: '[Previous conversation context has been summarized to reduce length]',
+            };
+            compactedMessages.splice(1, 0, summaryMessage);
+        }
+        currentTokens = this.estimateMessagesTokens(compactedMessages);
+        this.emitCompactionResult(originalTokens, currentTokens, messages.length, compactedMessages.length, strategy);
+        return compactedMessages;
+    }
+    // ==========================================================================
+    // Public Methods - Breakdown & Visualization
+    // ==========================================================================
+    /**
+     * Get a detailed breakdown of context usage by category.
+     *
+     * @param messages - Messages to analyze
+     * @param provider - Provider name for estimation
+     * @returns Context breakdown by category
+     */
+    getBreakdown(messages, provider = 'default') {
+        const breakdown = {
+            systemPrompt: 0,
+            messages: 0,
+            toolResults: 0,
+            images: 0,
+            total: 0,
+        };
+        for (const message of messages) {
+            const isSystemPrompt = this.isSystemPromptMessage(message);
+            if (typeof message.content === 'string') {
+                const tokens = this.estimateTokens(message.content, provider);
+                if (isSystemPrompt) {
+                    breakdown.systemPrompt += tokens;
+                }
+                else {
+                    breakdown.messages += tokens;
+                }
+            }
+            else if (Array.isArray(message.content)) {
+                for (const block of message.content) {
+                    const tokens = this.estimateContentBlockTokens(block, provider);
+                    if (block.type === 'tool_result') {
+                        breakdown.toolResults += tokens;
+                    }
+                    else if (block.type === 'image') {
+                        breakdown.images += tokens;
+                    }
+                    else if (isSystemPrompt) {
+                        breakdown.systemPrompt += tokens;
+                    }
+                    else {
+                        breakdown.messages += tokens;
+                    }
+                }
+            }
+        }
+        breakdown.total = breakdown.systemPrompt + breakdown.messages + breakdown.toolResults + breakdown.images;
+        return breakdown;
+    }
+    /**
+     * Generate a human-readable visualization of context usage.
+     *
+     * @param state - Current context state
+     * @param breakdown - Context breakdown by category
+     * @returns Formatted visualization string
+     */
+    visualize(state, breakdown) {
+        const lines = [
+            '='.repeat(60),
+            'CONTEXT USAGE REPORT',
+            '='.repeat(60),
+            '',
+            `Provider: ${state.provider}`,
+            `Model: ${state.model}`,
+            '',
+            '--- Token Usage ---',
+            `Used: ${state.usedTokens.toLocaleString()} / ${state.maxTokens.toLocaleString()} (${state.usedPercentage.toFixed(1)}%)`,
+            `Remaining: ${state.remainingTokens.toLocaleString()} (${state.remainingPercentage.toFixed(1)}%)`,
+            '',
+            '--- Usage Breakdown ---',
+            `System Prompt: ${breakdown.systemPrompt.toLocaleString()} tokens (${this.formatPercentage(breakdown.systemPrompt, breakdown.total)})`,
+            `Messages: ${breakdown.messages.toLocaleString()} tokens (${this.formatPercentage(breakdown.messages, breakdown.total)})`,
+            `Tool Results: ${breakdown.toolResults.toLocaleString()} tokens (${this.formatPercentage(breakdown.toolResults, breakdown.total)})`,
+            `Images: ${breakdown.images.toLocaleString()} tokens (${this.formatPercentage(breakdown.images, breakdown.total)})`,
+            `Total: ${breakdown.total.toLocaleString()} tokens`,
+            '',
+            '--- Status ---',
+            `Near Limit: ${state.isNearLimit ? 'YES (consider compacting)' : 'No'}`,
+            `Blocked: ${state.isBlocked ? 'YES (compaction required)' : 'No'}`,
+            '',
+            this.generateUsageBar(state.usedPercentage),
+            '='.repeat(60),
+        ];
+        return lines.join('\n');
+    }
+    // ==========================================================================
+    // Public Methods - Event Handling
+    // ==========================================================================
+    /**
+     * Add an event listener for context events.
+     *
+     * @param listener - Event listener function
+     */
+    addEventListener(listener) {
+        this.listeners.add(listener);
+    }
+    /**
+     * Remove an event listener.
+     *
+     * @param listener - Event listener to remove
+     */
+    removeEventListener(listener) {
+        this.listeners.delete(listener);
+    }
+    // ==========================================================================
+    // Private Methods
+    // ==========================================================================
+    /**
+     * Emit a context event to all listeners.
+     */
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.logger.error('Error in context event listener', { error });
+            }
+        }
+    }
+    /**
+     * Truncate tool results that exceed the configured limit.
+     */
+    truncateToolResults(messages) {
+        return messages.map((message) => {
+            if (typeof message.content === 'string') {
+                return message;
+            }
+            const truncatedContent = message.content.map((block) => {
+                if (block.type === 'tool_result' && block.content) {
+                    const tokens = this.estimateTokens(block.content);
+                    if (tokens > this.config.maxToolResultTokens) {
+                        return {
+                            ...block,
+                            content: this.truncate(block.content, this.config.maxToolResultTokens),
+                        };
+                    }
+                }
+                return block;
+            });
+            return { ...message, content: truncatedContent };
+        });
+    }
+    /**
+     * Truncate individual messages that exceed the configured limit.
+     */
+    truncateLongMessages(messages) {
+        return messages.map((message) => {
+            if (typeof message.content === 'string') {
+                const tokens = this.estimateTokens(message.content);
+                if (tokens > this.config.maxMessageTokens) {
+                    return {
+                        ...message,
+                        content: this.truncate(message.content, this.config.maxMessageTokens),
+                    };
+                }
+                return message;
+            }
+            // For content blocks, truncate text blocks that are too long
+            const truncatedContent = message.content.map((block) => {
+                if (block.type === 'text' && block.text) {
+                    const tokens = this.estimateTokens(block.text);
+                    if (tokens > this.config.maxMessageTokens) {
+                        return {
+                            ...block,
+                            text: this.truncate(block.text, this.config.maxMessageTokens),
+                        };
+                    }
+                }
+                return block;
+            });
+            return { ...message, content: truncatedContent };
+        });
+    }
+    /**
+     * Check if a message is a system prompt.
+     */
+    isSystemPromptMessage(message) {
+        // Check for explicit metadata
+        if ('metadata' in message && message.metadata?.isSystemPrompt) {
+            return true;
+        }
+        // Check for system role
+        if (message.role === 'system') {
+            return true;
+        }
+        // Check for <system> tags in content
+        if (typeof message.content === 'string') {
+            return message.content.includes('<system>') || message.content.includes('</system>');
+        }
+        return false;
+    }
+    /**
+     * Emit a compaction result event.
+     */
+    emitCompactionResult(originalTokens, compactedTokens, originalCount, compactedCount, strategy) {
+        const result = {
+            originalTokens,
+            compactedTokens,
+            tokensSaved: originalTokens - compactedTokens,
+            reductionPercentage: ((originalTokens - compactedTokens) / originalTokens) * 100,
+            originalMessageCount: originalCount,
+            compactedMessageCount: compactedCount,
+            strategy,
+        };
+        this.logger.info('Context compaction completed', {
+            tokensSaved: result.tokensSaved,
+            reductionPercentage: result.reductionPercentage.toFixed(1),
+            strategy,
+        });
+        this.emit({ type: 'compact_completed', result });
+    }
+    /**
+     * Format a percentage for display.
+     */
+    formatPercentage(value, total) {
+        if (total === 0)
+            return '0.0%';
+        return ((value / total) * 100).toFixed(1) + '%';
+    }
+    /**
+     * Generate a visual progress bar for context usage.
+     */
+    generateUsageBar(percentage) {
+        const width = 50;
+        const filled = Math.round((percentage / 100) * width);
+        const empty = width - filled;
+        let bar;
+        if (percentage >= 98) {
+            bar = '!'.repeat(filled) + '-'.repeat(empty);
+        }
+        else if (percentage >= 90) {
+            bar = '#'.repeat(filled) + '-'.repeat(empty);
+        }
+        else {
+            bar = '='.repeat(filled) + '-'.repeat(empty);
+        }
+        return `[${bar}] ${percentage.toFixed(1)}%`;
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a ContextManager instance.
+ *
+ * @param config - Partial configuration (merged with defaults)
+ * @param logger - Logger instance
+ * @returns Configured ContextManager instance
+ */
+export function createContextManager(config, logger) {
+    return new ContextManager(config, logger);
+}
 //# sourceMappingURL=context-manager.js.map