byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/llm/context/context-manager.js

@@ -0,0 +1,419 @@
+import { NoOpLogger } from '../../../../core/interfaces/cipher/i-logger.js';
+import { getErrorMessage } from '../../../../utils/error-helpers.js';
+import { AsyncMutex } from './async-mutex.js';
+import { MiddleRemovalStrategy, OldestRemovalStrategy } from './compression/index.js';
+import { countMessagesTokens } from './utils.js';
+/**
+ * Context Manager for managing conversation history.
+ *
+ * Responsibilities:
+ * - Store and manage internal message history
+ * - Format messages for specific LLM providers
+ * - Handle message compression (future)
+ * - Count tokens for context management
+ *
+ * Generic type T represents the provider-specific message format
+ * (e.g., GeminiContent for Gemini, MessageParam for Anthropic)
+ */
+export class ContextManager {
+    compressionStrategies;
+    formatter;
+    historyStorage;
+    isInitialized = false;
+    logger;
+    maxInputTokens;
+    messages = [];
+    /**
+     * Mutex for thread-safe operations on messages array.
+     * Used during parallel tool execution to prevent race conditions.
+     */
+    mutex = new AsyncMutex();
+    sessionId;
+    tokenizer;
+    /**
+     * Creates a new context manager
+     *
+     * @param options - Configuration options
+     * @param options.sessionId - Unique session identifier
+     * @param options.formatter - Message formatter for provider-specific format
+     * @param options.tokenizer - Token counter for the model
+     * @param options.maxInputTokens - Maximum input tokens allowed
+     * @param options.historyStorage - Optional history storage for persistence
+     * @param options.compressionStrategies - Optional compression strategies (defaults to MiddleRemoval + OldestRemoval)
+     */
+    constructor(options) {
+        this.sessionId = options.sessionId;
+        this.formatter = options.formatter;
+        this.tokenizer = options.tokenizer;
+        this.maxInputTokens = options.maxInputTokens;
+        this.historyStorage = options.historyStorage;
+        this.logger = options.logger ?? new NoOpLogger();
+        // Initialize compression strategies with defaults
+        this.compressionStrategies = options.compressionStrategies ?? [
+            new MiddleRemovalStrategy({ preserveEnd: 5, preserveStart: 4 }),
+            new OldestRemovalStrategy({ minMessagesToKeep: 4 }),
+        ];
+    }
+    /**
+     * Add an assistant message to the conversation.
+     *
+     * @param content - Message content (text or null if only tool calls)
+     * @param toolCalls - Optional tool calls made by the assistant
+     */
+    async addAssistantMessage(content, toolCalls) {
+        const message = {
+            content,
+            role: 'assistant',
+            toolCalls,
+        };
+        this.messages.push(message);
+        // Auto-save to persistent storage (non-blocking)
+        this.persistHistory().catch((error) => {
+            this.logger.error('Failed to persist history after assistant message', { error, sessionId: this.sessionId });
+        });
+    }
+    /**
+     * Add a system message to the conversation.
+     *
+     * @param content - System message content
+     */
+    async addSystemMessage(content) {
+        const message = {
+            content,
+            role: 'system',
+        };
+        this.messages.push(message);
+        // Auto-save to persistent storage (non-blocking)
+        this.persistHistory().catch((error) => {
+            this.logger.error('Failed to persist history after system message', { error, sessionId: this.sessionId });
+        });
+    }
+    /**
+     * Add a tool result message to the conversation.
+     * Thread-safe: Uses mutex to protect shared state during parallel tool execution.
+     *
+     * @param toolCallId - ID of the tool call this result responds to
+     * @param toolName - Name of the tool that was executed
+     * @param result - Result from tool execution
+     * @param _metadata - Additional metadata (success status, error type, execution metadata)
+     * @param _metadata.success - Whether the tool execution succeeded
+     * @param _metadata.errorType - Classified error type (if failed)
+     * @param _metadata.metadata - Execution metadata (duration, tokens, etc.)
+     * @returns The content that was added
+     */
+    async addToolResult(toolCallId, toolName, result, _metadata) {
+        // Sanitize result - convert to string representation (can be done outside lock)
+        const sanitized = this.sanitizeToolResult(result);
+        const message = {
+            content: sanitized,
+            name: toolName,
+            role: 'tool',
+            toolCallId,
+        };
+        // Use mutex to protect message array modification and persistence
+        await this.mutex.withLock(async () => {
+            this.messages.push(message);
+            // Persist within the lock to ensure ordering consistency
+            try {
+                await this.persistHistory();
+            }
+            catch (error) {
+                this.logger.error('Failed to persist history after tool result', { error, sessionId: this.sessionId });
+            }
+        });
+        return sanitized;
+    }
+    /**
+     * Add a user message to the conversation.
+     *
+     * @param content - User message text
+     * @param _imageData - Optional image data (not yet implemented)
+     * @param _fileData - Optional file data (not yet implemented)
+     */
+    async addUserMessage(content, _imageData, _fileData) {
+        // Simple implementation: just use text content
+        // Image and file support can be added later
+        const message = {
+            content,
+            role: 'user',
+        };
+        this.messages.push(message);
+        // Auto-save to persistent storage (non-blocking)
+        this.persistHistory().catch((error) => {
+            this.logger.error('Failed to persist history after user message', { error, sessionId: this.sessionId });
+        });
+    }
+    /**
+     * Clear all messages from the conversation history.
+     * Also clears persisted history if storage is enabled.
+     */
+    async clearHistory() {
+        this.messages = [];
+        // Clear persisted history if storage enabled
+        if (this.historyStorage) {
+            try {
+                await this.historyStorage.deleteHistory(this.sessionId);
+                // Debug logging removed for cleaner user experience
+            }
+            catch (error) {
+                this.logger.error('Failed to clear persisted history', { error, sessionId: this.sessionId });
+            }
+        }
+    }
+    /**
+     * Get comprehensive messages (all messages, for persistence/debugging).
+     * This includes all messages including invalid ones.
+     *
+     * @returns All messages in the conversation history
+     */
+    getComprehensiveMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Get curated messages (valid messages only, for API calls).
+     * Filters out invalid messages that would waste tokens or confuse the LLM.
+     *
+     * @returns Only valid messages suitable for API calls
+     */
+    getCuratedMessages() {
+        return this.messages.filter((msg) => this.validateMessage(msg).isValid);
+    }
+    /**
+     * Get formatted messages with compression applied.
+     * Uses curated (valid-only) messages for better LLM context quality.
+     *
+     * @param systemPrompt - Optional system prompt (for token accounting)
+     * @returns Formatted messages, system prompt, token count, and filter stats
+     */
+    async getFormattedMessagesWithCompression(systemPrompt) {
+        // Get curated messages (filter invalid ones)
+        const curatedMessages = this.getCuratedMessages();
+        const messagesFiltered = this.messages.length - curatedMessages.length;
+        // Calculate system prompt tokens
+        const systemPromptTokens = systemPrompt ? this.tokenizer.countTokens(systemPrompt) : 0;
+        // Compress curated history if needed
+        const compressedHistory = await this.compressHistoryIfNeeded(systemPromptTokens, curatedMessages);
+        // Format compressed messages
+        const formattedMessages = this.formatter.format(compressedHistory);
+        // Count total tokens (system + history)
+        const historyTokens = countMessagesTokens(compressedHistory, this.tokenizer);
+        const tokensUsed = systemPromptTokens + historyTokens;
+        return {
+            formattedMessages,
+            messagesFiltered,
+            systemPrompt,
+            tokensUsed,
+        };
+    }
+    /**
+     * Get the maximum input tokens allowed.
+     */
+    getMaxInputTokens() {
+        return this.maxInputTokens;
+    }
+    /**
+     * Get all messages in the conversation.
+     */
+    getMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Get the session ID.
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Initialize the context manager by loading persisted history.
+     * Should be called after construction to restore previous conversation.
+     *
+     * @returns True if history was loaded, false otherwise
+     */
+    async initialize() {
+        if (this.isInitialized) {
+            this.logger.warn('ContextManager already initialized', { sessionId: this.sessionId });
+            return false;
+        }
+        if (!this.historyStorage) {
+            this.isInitialized = true;
+            return false;
+        }
+        try {
+            const history = await this.historyStorage.loadHistory(this.sessionId);
+            if (history && history.length > 0) {
+                this.messages = history;
+                this.isInitialized = true;
+                // Debug logging removed for cleaner user experience
+                return true;
+            }
+            this.isInitialized = true;
+            // Debug logging removed for cleaner user experience
+            return false;
+        }
+        catch (error) {
+            this.logger.error('Failed to load history for session', { error, sessionId: this.sessionId });
+            this.isInitialized = true;
+            return false;
+        }
+    }
+    /**
+     * Compress conversation history if needed to fit within token limits.
+     *
+     * This method applies compression strategies sequentially until the history
+     * fits within the available token budget (maxInputTokens - systemPromptTokens).
+     *
+     * @param systemPromptTokens - Tokens used by system prompt (reserved, not compressible)
+     * @param messagesToCompress - Messages to compress (defaults to all messages)
+     * @returns Compressed message history
+     */
+    async compressHistoryIfNeeded(systemPromptTokens, messagesToCompress) {
+        const messages = messagesToCompress ?? this.messages;
+        // Calculate current token usage
+        const currentHistoryTokens = countMessagesTokens(messages, this.tokenizer);
+        const totalTokens = systemPromptTokens + currentHistoryTokens;
+        // No compression needed
+        if (totalTokens <= this.maxInputTokens) {
+            // Debug logging removed for cleaner user experience
+            return messages;
+        }
+        // Debug logging removed for cleaner user experience
+        // Calculate target token budget for history
+        // Reserve space for system prompt
+        const maxHistoryTokens = this.maxInputTokens - systemPromptTokens;
+        // Apply compression strategies sequentially
+        let compressedHistory = messages;
+        for (const strategy of this.compressionStrategies) {
+            // Debug logging removed for cleaner user experience
+            // eslint-disable-next-line no-await-in-loop
+            compressedHistory = await strategy.compress(compressedHistory, maxHistoryTokens, this.tokenizer);
+            // Check if we've met the token limit
+            const compressedTokens = countMessagesTokens(compressedHistory, this.tokenizer);
+            const newTotal = systemPromptTokens + compressedTokens;
+            if (newTotal <= this.maxInputTokens) {
+                // Debug logging removed for cleaner user experience
+                break;
+            }
+        }
+        // Final token count
+        const finalTokens = countMessagesTokens(compressedHistory, this.tokenizer);
+        const finalTotal = systemPromptTokens + finalTokens;
+        if (finalTotal > this.maxInputTokens) {
+            // Keep warning as it's important for users to know
+            this.logger.warn('Unable to compress below token limit', {
+                finalTokens,
+                finalTotal,
+                maxInputTokens: this.maxInputTokens,
+                sessionId: this.sessionId,
+                systemPromptTokens,
+            });
+        }
+        return compressedHistory;
+    }
+    /**
+     * Count tokens in formatted messages.
+     *
+     * @param _formattedMessages - Messages in provider-specific format
+     * @returns Token count
+     */
+    async countTokens(_formattedMessages) {
+        // Use tokenizer to count tokens
+        // This is simplified - actual implementation would convert formatted messages back
+        // For now, estimate based on internal messages
+        const text = this.messages
+            .map((m) => {
+            if (typeof m.content === 'string') {
+                return m.content;
+            }
+            if (Array.isArray(m.content)) {
+                return m.content
+                    .map((part) => {
+                    if (part.type === 'text') {
+                        return part.text;
+                    }
+                    return '';
+                })
+                    .join('');
+            }
+            return '';
+        })
+            .join('\n');
+        return this.tokenizer.countTokens(text);
+    }
+    /**
+     * Check if a system message is noise (empty or whitespace only).
+     *
+     * @param message - Message to check
+     * @returns True if the message is noise
+     */
+    isSystemNoise(message) {
+        const content = typeof message.content === 'string' ? message.content : '';
+        return content.trim().length === 0;
+    }
+    /**
+     * Persist current conversation history to storage.
+     * This is called automatically after each message is added.
+     *
+     * @returns Promise that resolves when history is persisted
+     */
+    async persistHistory() {
+        if (!this.historyStorage) {
+            return;
+        }
+        // Store InternalMessage directly (no conversion needed)
+        await this.historyStorage.saveHistory(this.sessionId, this.messages);
+    }
+    /**
+     * Sanitize tool result for storage.
+     * Handles large outputs, binary data, circular references, etc.
+     *
+     * @param result - Raw tool result
+     * @returns Sanitized string representation
+     */
+    sanitizeToolResult(result) {
+        try {
+            // If already a string, return as-is
+            if (typeof result === 'string') {
+                return result;
+            }
+            // Convert to JSON string
+            const jsonString = JSON.stringify(result, null, 2);
+            // Limit size to prevent extremely large results
+            const MAX_RESULT_LENGTH = 50_000;
+            if (jsonString.length > MAX_RESULT_LENGTH) {
+                return jsonString.slice(0, MAX_RESULT_LENGTH) + '\n... (truncated)';
+            }
+            return jsonString;
+        }
+        catch (error) {
+            // Handle circular references or other serialization errors
+            return `[Tool result serialization failed: ${getErrorMessage(error)}]`;
+        }
+    }
+    /**
+     * Validate a message for API inclusion.
+     * Filters out invalid messages that would waste tokens or confuse the LLM.
+     *
+     * Rules:
+     * 1. Empty content (non-tool messages without content or tool calls)
+     * 2. Tool result without corresponding tool call ID
+     * 3. System messages with only noise (empty or whitespace)
+     *
+     * @param message - Message to validate
+     * @returns Validation result indicating if message is valid for API
+     */
+    validateMessage(message) {
+        // Rule 1: Empty content check (skip for tool messages which always have content)
+        if (message.role !== 'tool' && !message.content && (!message.toolCalls || message.toolCalls.length === 0)) {
+            return { isValid: false, reason: 'empty_content' };
+        }
+        // Rule 2: Tool result without corresponding call ID
+        if (message.role === 'tool' && !message.toolCallId) {
+            return { isValid: false, reason: 'incomplete_tool_call' };
+        }
+        // Rule 3: System messages with only noise (empty or whitespace)
+        if (message.role === 'system' && this.isSystemNoise(message)) {
+            return { isValid: false, reason: 'system_noise' };
+        }
+        return { isValid: true };
+    }
+}

package/dist/infra/cipher/llm/context/index.d.ts

@@ -0,0 +1,2 @@
+export { AsyncMutex } from './async-mutex.js';
+export { ContextManager, type FileData, type FormattedMessagesResult, type ImageData, } from './context-manager.js';

package/dist/infra/cipher/llm/context/index.js

@@ -0,0 +1,2 @@
+export { AsyncMutex } from './async-mutex.js';
+export { ContextManager, } from './context-manager.js';

package/dist/infra/cipher/llm/context/loop-detector.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Loop Detector for Agent Tool Calls
+ *
+ * Detects repetitive tool call patterns to prevent the agent from:
+ * - Making the same tool call with identical arguments multiple times
+ * - Oscillating between two tool calls (A→B→A→B pattern)
+ *
+ * When a loop is detected, the caller should skip tool execution
+ * and inject a warning message to guide the LLM to try a different approach.
+ *
+ * Thread-safe: Uses AsyncMutex to protect shared state during parallel tool execution.
+ */
+/**
+ * Signature of a tool call for comparison.
+ */
+export interface ToolCallSignature {
+    /** Hash of the serialized arguments for fast comparison */
+    argsHash: string;
+    /** Timestamp when the call was recorded */
+    timestamp: number;
+    /** Name of the tool being called */
+    toolName: string;
+}
+/**
+ * Result of loop detection check.
+ */
+export interface LoopDetectionResult {
+    /** Whether a loop pattern was detected */
+    isLoop: boolean;
+    /** Type of loop pattern detected */
+    loopType?: 'exact_repeat' | 'oscillation';
+    /** Number of times the pattern repeated */
+    repeatCount?: number;
+    /** Human-readable suggestion for the LLM */
+    suggestion?: string;
+}
+/**
+ * Configuration for loop detection thresholds.
+ */
+export interface LoopDetectorConfig {
+    /** Same tool+args called N times consecutively = loop (default: 3) */
+    exactRepeatThreshold: number;
+    /** A→B→A→B pattern cycles before detection (default: 2) */
+    oscillationThreshold: number;
+    /** How many recent calls to track (default: 10) */
+    windowSize: number;
+}
+/**
+ * Loop Detector.
+ *
+ * Tracks recent tool calls and detects repetitive patterns.
+ * This helps prevent the agent from wasting tokens and time
+ * on repeated unsuccessful attempts.
+ *
+ * Thread-safe: All mutating operations use AsyncMutex to ensure
+ * safe concurrent access during parallel tool execution.
+ *
+ * @example
+ * ```typescript
+ * const detector = new LoopDetector()
+ *
+ * // Before executing each tool call (async for thread safety)
+ * const result = await detector.recordAndCheck('read_file', { path: '/foo.ts' })
+ * if (result.isLoop) {
+ *   // Skip execution, inject warning to LLM
+ *   console.log(result.suggestion)
+ * } else {
+ *   // Execute tool normally
+ * }
+ * ```
+ */
+export declare class LoopDetector {
+    private readonly config;
+    private readonly mutex;
+    private recentCalls;
+    constructor(config?: Partial<LoopDetectorConfig>);
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): Readonly<LoopDetectorConfig>;
+    /**
+     * Get the number of recorded calls in the window.
+     */
+    getRecentCallCount(): number;
+    /**
+     * Record a tool call and check for loop patterns.
+     * Thread-safe: Uses mutex to protect shared state during parallel execution.
+     *
+     * @param toolName - Name of the tool being called
+     * @param args - Arguments passed to the tool
+     * @returns Detection result indicating if a loop was found
+     */
+    recordAndCheck(toolName: string, args: Record<string, unknown>): Promise<LoopDetectionResult>;
+    /**
+     * Reset the detector state.
+     * Should be called when starting a new conversation or task.
+     * Thread-safe: Uses mutex to protect shared state.
+     */
+    reset(): Promise<void>;
+    /**
+     * Create a signature for a tool call.
+     */
+    private createSignature;
+    /**
+     * Detect exact repeat pattern: same call N times consecutively.
+     */
+    private detectExactRepeat;
+    /**
+     * Detect loop patterns in recent calls.
+     */
+    private detectLoop;
+    /**
+     * Detect oscillation pattern: A→B→A→B.
+     */
+    private detectOscillation;
+    /**
+     * Create a deterministic hash of tool arguments.
+     * Sorts keys to ensure consistent ordering.
+     */
+    private hashArgs;
+    /**
+     * Check if two signatures represent the same tool call.
+     */
+    private signaturesMatch;
+}