byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/llm/context/async-mutex.js

@@ -0,0 +1,92 @@
+/**
+ * AsyncMutex - Simple asynchronous mutex for thread safety in parallel execution.
+ *
+ * Provides mutual exclusion for async operations, ensuring that only one
+ * operation can execute the critical section at a time. Uses a FIFO queue
+ * to ensure fairness among waiting operations.
+ *
+ * @example
+ * ```typescript
+ * const mutex = new AsyncMutex()
+ *
+ * // Option 1: Manual acquire/release
+ * await mutex.acquire()
+ * try {
+ *   // Critical section
+ * } finally {
+ *   mutex.release()
+ * }
+ *
+ * // Option 2: Using withLock (recommended)
+ * await mutex.withLock(async () => {
+ *   // Critical section - automatically released
+ * })
+ * ```
+ */
+export class AsyncMutex {
+    locked = false;
+    queue = [];
+    /**
+     * Acquire the mutex lock.
+     * If the mutex is already locked, the caller will wait in a FIFO queue.
+     *
+     * @returns Promise that resolves when the lock is acquired
+     */
+    async acquire() {
+        if (!this.locked) {
+            this.locked = true;
+            return;
+        }
+        return new Promise((resolve) => {
+            this.queue.push(resolve);
+        });
+    }
+    /**
+     * Get the number of operations waiting for the lock.
+     */
+    getQueueLength() {
+        return this.queue.length;
+    }
+    /**
+     * Check if the mutex is currently locked.
+     */
+    isLocked() {
+        return this.locked;
+    }
+    /**
+     * Release the mutex lock.
+     * If there are waiting operations, the next one in the queue will be granted the lock.
+     *
+     * @throws Error if the mutex is not currently locked
+     */
+    release() {
+        if (!this.locked) {
+            throw new Error('AsyncMutex: Cannot release a mutex that is not locked');
+        }
+        const next = this.queue.shift();
+        if (next) {
+            // Pass lock to next waiter (mutex stays locked)
+            next();
+        }
+        else {
+            // No waiters, unlock
+            this.locked = false;
+        }
+    }
+    /**
+     * Execute a function with the mutex lock held.
+     * The lock is automatically released when the function completes or throws.
+     *
+     * @param fn - Async function to execute with the lock held
+     * @returns The result of the function
+     */
+    async withLock(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Context compression strategies module
+ */
+export { MiddleRemovalStrategy } from './middle-removal.js';
+export { OldestRemovalStrategy } from './oldest-removal.js';
+export type { CompressionStrategyOptions, ICompressionStrategy } from './types.js';

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

@@ -0,0 +1,5 @@
+/**
+ * Context compression strategies module
+ */
+export { MiddleRemovalStrategy } from './middle-removal.js';
+export { OldestRemovalStrategy } from './oldest-removal.js';

package/dist/infra/cipher/llm/context/compression/middle-removal.d.ts

@@ -0,0 +1,40 @@
+import type { ITokenizer } from '../../../../../core/interfaces/cipher/i-tokenizer.js';
+import type { InternalMessage } from '../../../../../core/interfaces/cipher/message-types.js';
+import type { ICompressionStrategy } from './types.js';
+/**
+ * Configuration options for MiddleRemovalStrategy
+ */
+export interface MiddleRemovalOptions {
+    /** Number of messages to preserve at the end (default: 5) */
+    preserveEnd?: number;
+    /** Number of messages to preserve at the start (default: 4) */
+    preserveStart?: number;
+}
+/**
+ * Middle Removal compression strategy.
+ *
+ * Preserves messages at the beginning (early context/setup) and end (recent conversation),
+ * removing messages from the middle section when compression is needed.
+ *
+ * This strategy is ideal for maintaining both:
+ * - Historical context (system instructions, initial setup)
+ * - Recent conversation flow (latest user/assistant exchanges)
+ *
+ * Algorithm:
+ * 1. Check if compression is needed
+ * 2. Identify the "middle" section (between preserved start and end)
+ * 3. Remove oldest messages from middle until token limit is met
+ * 4. Return compressed history with start and end intact
+ *
+ * Example with preserveStart=2, preserveEnd=2:
+ * Messages: [1, 2, 3, 4, 5, 6, 7, 8]
+ * Preserved: [1, 2] + [...] + [7, 8]
+ * Removable: [3, 4, 5, 6] (removed oldest-first if needed)
+ */
+export declare class MiddleRemovalStrategy implements ICompressionStrategy {
+    private readonly preserveEnd;
+    private readonly preserveStart;
+    constructor(options?: MiddleRemovalOptions);
+    compress(history: InternalMessage[], maxHistoryTokens: number, tokenizer: ITokenizer): Promise<InternalMessage[]>;
+    getName(): string;
+}

package/dist/infra/cipher/llm/context/compression/middle-removal.js

@@ -0,0 +1,76 @@
+import { countMessagesTokens } from '../utils.js';
+/**
+ * Middle Removal compression strategy.
+ *
+ * Preserves messages at the beginning (early context/setup) and end (recent conversation),
+ * removing messages from the middle section when compression is needed.
+ *
+ * This strategy is ideal for maintaining both:
+ * - Historical context (system instructions, initial setup)
+ * - Recent conversation flow (latest user/assistant exchanges)
+ *
+ * Algorithm:
+ * 1. Check if compression is needed
+ * 2. Identify the "middle" section (between preserved start and end)
+ * 3. Remove oldest messages from middle until token limit is met
+ * 4. Return compressed history with start and end intact
+ *
+ * Example with preserveStart=2, preserveEnd=2:
+ * Messages: [1, 2, 3, 4, 5, 6, 7, 8]
+ * Preserved: [1, 2] + [...] + [7, 8]
+ * Removable: [3, 4, 5, 6] (removed oldest-first if needed)
+ */
+export class MiddleRemovalStrategy {
+    preserveEnd;
+    preserveStart;
+    constructor(options = {}) {
+        this.preserveEnd = options.preserveEnd ?? 5;
+        this.preserveStart = options.preserveStart ?? 4;
+        // Debug logging removed for cleaner user experience
+    }
+    async compress(history, maxHistoryTokens, tokenizer) {
+        // Calculate initial token count
+        const initialTokenCount = countMessagesTokens(history, tokenizer);
+        // No compression needed - return unchanged
+        if (initialTokenCount <= maxHistoryTokens) {
+            // Debug logging removed for cleaner user experience
+            return history;
+        }
+        const totalMessages = history.length;
+        const removableIndices = [];
+        // Identify middle section that can be removed
+        // We need at least (preserveStart + preserveEnd) messages to apply this strategy
+        if (totalMessages > this.preserveStart + this.preserveEnd) {
+            for (let i = this.preserveStart; i < totalMessages - this.preserveEnd; i++) {
+                removableIndices.push(i);
+            }
+        }
+        else {
+            // Not enough messages to apply strategy
+            console.warn(`MiddleRemovalStrategy: Cannot apply - only ${totalMessages} messages (need at least ${this.preserveStart + this.preserveEnd})`);
+            return history;
+        }
+        // Remove oldest messages from middle section until token limit is met
+        const removedIndices = new Set();
+        let currentTokenCount = initialTokenCount;
+        while (currentTokenCount > maxHistoryTokens && removableIndices.length > 0) {
+            // Remove oldest message from middle (shift from start of removableIndices)
+            const indexToRemove = removableIndices.shift();
+            if (indexToRemove === undefined) {
+                // This should never happen since we check length > 0, but be safe
+                break;
+            }
+            removedIndices.add(indexToRemove);
+            // Recalculate tokens with current removals
+            const remaining = history.filter((_, i) => !removedIndices.has(i));
+            currentTokenCount = countMessagesTokens(remaining, tokenizer);
+        }
+        // Build final compressed history
+        const compressed = history.filter((_, i) => !removedIndices.has(i));
+        // Debug logging removed for cleaner user experience
+        return compressed;
+    }
+    getName() {
+        return 'MiddleRemoval';
+    }
+}

package/dist/infra/cipher/llm/context/compression/oldest-removal.d.ts

@@ -0,0 +1,38 @@
+import type { ITokenizer } from '../../../../../core/interfaces/cipher/i-tokenizer.js';
+import type { InternalMessage } from '../../../../../core/interfaces/cipher/message-types.js';
+import type { ICompressionStrategy } from './types.js';
+/**
+ * Configuration options for OldestRemovalStrategy
+ */
+export interface OldestRemovalOptions {
+    /** Minimum number of recent messages to keep (default: 4) */
+    minMessagesToKeep?: number;
+}
+/**
+ * Oldest Removal compression strategy.
+ *
+ * Simple FIFO (First-In-First-Out) strategy that removes the oldest messages first,
+ * preserving only recent conversation history.
+ *
+ * This strategy is ideal as a fallback after more sophisticated strategies have been
+ * applied. It ensures the most recent context is always preserved while older messages
+ * are removed to meet token limits.
+ *
+ * Algorithm:
+ * 1. Check if compression is needed
+ * 2. Remove oldest message (from start of array)
+ * 3. Recalculate token count
+ * 4. Repeat until token limit is met or minimum messages reached
+ * 5. Warn if still over limit (cannot compress further)
+ *
+ * Example with minMessagesToKeep=3:
+ * Messages: [1, 2, 3, 4, 5, 6, 7, 8]
+ * Remove: 1, then 2, then 3, then 4, then 5 (oldest-first)
+ * Result: [6, 7, 8] (stops at minimum 3 messages)
+ */
+export declare class OldestRemovalStrategy implements ICompressionStrategy {
+    private readonly minMessagesToKeep;
+    constructor(options?: OldestRemovalOptions);
+    compress(history: InternalMessage[], maxHistoryTokens: number, tokenizer: ITokenizer): Promise<InternalMessage[]>;
+    getName(): string;
+}

package/dist/infra/cipher/llm/context/compression/oldest-removal.js

@@ -0,0 +1,53 @@
+import { countMessagesTokens } from '../utils.js';
+/**
+ * Oldest Removal compression strategy.
+ *
+ * Simple FIFO (First-In-First-Out) strategy that removes the oldest messages first,
+ * preserving only recent conversation history.
+ *
+ * This strategy is ideal as a fallback after more sophisticated strategies have been
+ * applied. It ensures the most recent context is always preserved while older messages
+ * are removed to meet token limits.
+ *
+ * Algorithm:
+ * 1. Check if compression is needed
+ * 2. Remove oldest message (from start of array)
+ * 3. Recalculate token count
+ * 4. Repeat until token limit is met or minimum messages reached
+ * 5. Warn if still over limit (cannot compress further)
+ *
+ * Example with minMessagesToKeep=3:
+ * Messages: [1, 2, 3, 4, 5, 6, 7, 8]
+ * Remove: 1, then 2, then 3, then 4, then 5 (oldest-first)
+ * Result: [6, 7, 8] (stops at minimum 3 messages)
+ */
+export class OldestRemovalStrategy {
+    minMessagesToKeep;
+    constructor(options = {}) {
+        this.minMessagesToKeep = options.minMessagesToKeep ?? 4;
+        // Debug logging removed for cleaner user experience
+    }
+    async compress(history, maxHistoryTokens, tokenizer) {
+        // Work with a copy to avoid mutating input
+        const currentHistory = [...history];
+        let currentTokenCount = countMessagesTokens(currentHistory, tokenizer);
+        // Remove oldest messages until token limit met or minimum reached
+        while (currentHistory.length > this.minMessagesToKeep &&
+            currentTokenCount > maxHistoryTokens) {
+            // Remove oldest message (from start)
+            currentHistory.shift();
+            // Recalculate token count
+            currentTokenCount = countMessagesTokens(currentHistory, tokenizer);
+        }
+        // Warn if still over limit after reaching minimum
+        if (currentTokenCount > maxHistoryTokens) {
+            // Keep warning as it's important
+            console.warn(`OldestRemovalStrategy: Cannot compress further - at minimum ${this.minMessagesToKeep} messages (${currentTokenCount} tokens > ${maxHistoryTokens} limit)`);
+        }
+        // Debug logging removed for cleaner user experience
+        return currentHistory;
+    }
+    getName() {
+        return 'OldestRemoval';
+    }
+}

package/dist/infra/cipher/llm/context/compression/types.d.ts

@@ -0,0 +1,36 @@
+import type { ITokenizer } from '../../../../../core/interfaces/cipher/i-tokenizer.js';
+import type { InternalMessage } from '../../../../../core/interfaces/cipher/message-types.js';
+/**
+ * Configuration options for compression strategies
+ */
+export interface CompressionStrategyOptions {
+    [key: string]: unknown;
+}
+/**
+ * Interface for context compression strategies.
+ * Strategies remove messages from history to fit within token limits.
+ *
+ * Compression strategies are applied sequentially by the ContextManager
+ * until the token limit is satisfied. Each strategy can implement different
+ * algorithms for deciding which messages to remove.
+ *
+ * Common strategies:
+ * - MiddleRemoval: Preserves early context and recent messages, removes from middle
+ * - OldestRemoval: Simple FIFO, keeps only recent messages
+ */
+export interface ICompressionStrategy {
+    /**
+     * Compress message history to fit within token limit
+     *
+     * @param history - Full message history to compress
+     * @param maxHistoryTokens - Maximum tokens allowed for history (excluding system prompt)
+     * @param tokenizer - Tokenizer for counting tokens
+     * @returns Compressed message history
+     */
+    compress(history: InternalMessage[], maxHistoryTokens: number, tokenizer: ITokenizer): Promise<InternalMessage[]>;
+    /**
+     * Human-readable name of the strategy
+     * Used for logging and debugging
+     */
+    getName(): string;
+}

package/dist/infra/cipher/llm/context/compression/types.js

@@ -0,0 +1 @@
+export {};

package/dist/infra/cipher/llm/context/context-manager.d.ts

@@ -0,0 +1,234 @@
+import type { IHistoryStorage } from '../../../../core/interfaces/cipher/i-history-storage.js';
+import type { ILogger } from '../../../../core/interfaces/cipher/i-logger.js';
+import type { IMessageFormatter } from '../../../../core/interfaces/cipher/i-message-formatter.js';
+import type { ITokenizer } from '../../../../core/interfaces/cipher/i-tokenizer.js';
+import type { InternalMessage } from '../../../../core/interfaces/cipher/message-types.js';
+import type { ICompressionStrategy } from './compression/types.js';
+/**
+ * Image data for messages
+ */
+export interface ImageData {
+    data: ArrayBuffer | Buffer | string | Uint8Array | URL;
+    mimeType?: string;
+}
+/**
+ * File data for messages
+ */
+export interface FileData {
+    data: ArrayBuffer | Buffer | string | Uint8Array | URL;
+    filename?: string;
+    mimeType: string;
+}
+/**
+ * Result of message formatting with compression
+ */
+export interface FormattedMessagesResult<T> {
+    formattedMessages: T[];
+    /** Number of messages filtered out as invalid */
+    messagesFiltered: number;
+    systemPrompt?: string;
+    tokensUsed: number;
+}
+/**
+ * Reason why a message was considered invalid for API inclusion.
+ */
+export type MessageInvalidReason = 'empty_content' | 'incomplete_tool_call' | 'system_noise';
+/**
+ * Result of message validation check.
+ */
+export interface MessageValidation {
+    /** Whether the message is valid for API inclusion */
+    isValid: boolean;
+    /** Reason if invalid */
+    reason?: MessageInvalidReason;
+}
+/**
+ * Configuration options for ContextManager
+ */
+export interface ContextManagerOptions<T> {
+    compressionStrategies?: ICompressionStrategy[];
+    formatter: IMessageFormatter<T>;
+    historyStorage?: IHistoryStorage;
+    logger?: ILogger;
+    maxInputTokens: number;
+    sessionId: string;
+    tokenizer: ITokenizer;
+}
+/**
+ * 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 declare class ContextManager<T> {
+    private readonly compressionStrategies;
+    private readonly formatter;
+    private readonly historyStorage?;
+    private isInitialized;
+    private readonly logger;
+    private readonly maxInputTokens;
+    private messages;
+    /**
+     * Mutex for thread-safe operations on messages array.
+     * Used during parallel tool execution to prevent race conditions.
+     */
+    private readonly mutex;
+    private readonly sessionId;
+    private readonly 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: ContextManagerOptions<T>);
+    /**
+     * 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
+     */
+    addAssistantMessage(content: null | string, toolCalls?: InternalMessage['toolCalls']): Promise<void>;
+    /**
+     * Add a system message to the conversation.
+     *
+     * @param content - System message content
+     */
+    addSystemMessage(content: string): Promise<void>;
+    /**
+     * 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
+     */
+    addToolResult(toolCallId: string, toolName: string, result: unknown, _metadata: {
+        errorType?: string;
+        metadata?: Record<string, unknown>;
+        success: boolean;
+    }): Promise<string>;
+    /**
+     * 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)
+     */
+    addUserMessage(content: string, _imageData?: ImageData, _fileData?: FileData): Promise<void>;
+    /**
+     * Clear all messages from the conversation history.
+     * Also clears persisted history if storage is enabled.
+     */
+    clearHistory(): Promise<void>;
+    /**
+     * Get comprehensive messages (all messages, for persistence/debugging).
+     * This includes all messages including invalid ones.
+     *
+     * @returns All messages in the conversation history
+     */
+    getComprehensiveMessages(): InternalMessage[];
+    /**
+     * 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(): InternalMessage[];
+    /**
+     * 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
+     */
+    getFormattedMessagesWithCompression(systemPrompt?: string): Promise<FormattedMessagesResult<T>>;
+    /**
+     * Get the maximum input tokens allowed.
+     */
+    getMaxInputTokens(): number;
+    /**
+     * Get all messages in the conversation.
+     */
+    getMessages(): InternalMessage[];
+    /**
+     * Get the session ID.
+     */
+    getSessionId(): string;
+    /**
+     * 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
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * 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
+     */
+    private compressHistoryIfNeeded;
+    /**
+     * Count tokens in formatted messages.
+     *
+     * @param _formattedMessages - Messages in provider-specific format
+     * @returns Token count
+     */
+    private countTokens;
+    /**
+     * Check if a system message is noise (empty or whitespace only).
+     *
+     * @param message - Message to check
+     * @returns True if the message is noise
+     */
+    private isSystemNoise;
+    /**
+     * Persist current conversation history to storage.
+     * This is called automatically after each message is added.
+     *
+     * @returns Promise that resolves when history is persisted
+     */
+    private persistHistory;
+    /**
+     * Sanitize tool result for storage.
+     * Handles large outputs, binary data, circular references, etc.
+     *
+     * @param result - Raw tool result
+     * @returns Sanitized string representation
+     */
+    private sanitizeToolResult;
+    /**
+     * 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
+     */
+    private validateMessage;
+}