byterover-cli 1.6.0 → 1.7.1

package/dist/agent/infra/llm/context/compression/reactive-overflow.js

@@ -0,0 +1,272 @@
+/**
+ * Reactive Overflow compression strategy.
+ *
+ * This strategy uses an LLM to generate intelligent summaries of older messages
+ * when the context window overflows. Unlike simple truncation strategies, it
+ * preserves the semantic meaning of the conversation.
+ *
+ * Algorithm:
+ * 1. Check if overflow (currentTokens > maxHistoryTokens)
+ * 2. Select oldest non-system messages to summarize
+ * 3. Generate LLM summary of selected messages
+ * 4. Return: systemMessages + summaryMessage + remainingMessages
+ * 5. Summary message has metadata.isSummary = true
+ *
+ * Key design principles:
+ * - Uses same model as conversation (per user configuration)
+ * - Summary message marks compaction boundary
+ * - filterCompacted() excludes old messages at read-time
+ * - Full history preserved in storage for audit
+ *
+ */
+import { isTextPart } from '../../../../core/interfaces/message-type-guards.js';
+/**
+ * Default configuration values.
+ */
+const DEFAULTS = {
+    minMessagesToSummarize: 10,
+    preserveLastNTurns: 2,
+    summaryTargetTokens: 2000,
+};
+/**
+ * Reactive Overflow compression strategy.
+ *
+ * Uses an LLM to generate intelligent summaries when context overflows.
+ */
+export class ReactiveOverflowStrategy {
+    llmProvider;
+    minMessagesToSummarize;
+    model;
+    preserveLastNTurns;
+    summaryTargetTokens;
+    constructor(options) {
+        this.llmProvider = options.llmProvider;
+        this.model = options.model;
+        this.summaryTargetTokens = options.summaryTargetTokens ?? DEFAULTS.summaryTargetTokens;
+        this.minMessagesToSummarize = options.minMessagesToSummarize ?? DEFAULTS.minMessagesToSummarize;
+        this.preserveLastNTurns = options.preserveLastNTurns ?? DEFAULTS.preserveLastNTurns;
+    }
+    async compress(history, maxHistoryTokens, tokenizer) {
+        // Calculate current token count
+        const currentTokens = this.countHistoryTokens(history, tokenizer);
+        // Check if compression is needed
+        if (currentTokens <= maxHistoryTokens) {
+            return history;
+        }
+        // Separate system messages from non-system messages
+        const systemMessages = history.filter((m) => m.role === 'system');
+        const nonSystemMessages = history.filter((m) => m.role !== 'system');
+        // Check if we have enough messages to summarize
+        if (nonSystemMessages.length < this.minMessagesToSummarize) {
+            // Not enough messages, can't use this strategy
+            return history;
+        }
+        // Calculate how many messages to keep (preserve last N turns)
+        const turnBoundaries = this.findTurnBoundaries(nonSystemMessages);
+        const turnsToPreserve = Math.min(this.preserveLastNTurns, turnBoundaries.length);
+        const preserveFromIndex = turnsToPreserve > 0
+            ? turnBoundaries[turnBoundaries.length - turnsToPreserve]
+            : nonSystemMessages.length;
+        // Split messages into "to summarize" and "to keep"
+        const messagesToSummarize = nonSystemMessages.slice(0, preserveFromIndex);
+        const messagesToKeep = nonSystemMessages.slice(preserveFromIndex);
+        // Need enough messages to summarize
+        if (messagesToSummarize.length < this.minMessagesToSummarize) {
+            return history;
+        }
+        // Generate summary using LLM
+        const summaryContent = await this.generateSummary(messagesToSummarize);
+        // Create summary message with metadata
+        const summaryMessage = {
+            content: `[Conversation Summary]\n${summaryContent}`,
+            metadata: {
+                compactedAt: Date.now(),
+                isSummary: true,
+                summarizedMessageCount: messagesToSummarize.length,
+            },
+            role: 'system',
+        };
+        // Return: system messages + summary + kept messages
+        return [...systemMessages, summaryMessage, ...messagesToKeep];
+    }
+    getName() {
+        return 'ReactiveOverflow';
+    }
+    /**
+     * Count tokens in message history.
+     */
+    countHistoryTokens(history, tokenizer) {
+        let total = 0;
+        for (const message of history) {
+            total += this.countMessageTokens(message, tokenizer);
+        }
+        return total;
+    }
+    /**
+     * Count tokens in a single message.
+     */
+    countMessageTokens(message, tokenizer) {
+        // Role overhead (approximately 4 tokens)
+        let tokens = 4;
+        if (typeof message.content === 'string') {
+            tokens += tokenizer.countTokens(message.content);
+        }
+        else if (Array.isArray(message.content)) {
+            for (const part of message.content) {
+                tokens += isTextPart(part) ? tokenizer.countTokens(part.text) : 100;
+            }
+        }
+        // Tool calls overhead
+        if (message.toolCalls) {
+            for (const call of message.toolCalls) {
+                tokens += tokenizer.countTokens(call.function.name);
+                tokens += tokenizer.countTokens(call.function.arguments);
+            }
+        }
+        return tokens;
+    }
+    /**
+     * Extract text content from a message.
+     */
+    extractTextContent(message) {
+        if (typeof message.content === 'string') {
+            return message.content;
+        }
+        if (Array.isArray(message.content)) {
+            return message.content
+                .filter((p) => isTextPart(p))
+                .map((p) => p.text)
+                .join('\n');
+        }
+        return '';
+    }
+    /**
+     * Find turn boundaries in message history.
+     *
+     * A turn boundary is the index where a user message starts.
+     * Returns indices of all user messages.
+     */
+    findTurnBoundaries(messages) {
+        const boundaries = [];
+        for (const [index, message] of messages.entries()) {
+            if (message.role === 'user') {
+                boundaries.push(index);
+            }
+        }
+        return boundaries;
+    }
+    /**
+     * Format messages for the summary prompt.
+     */
+    formatMessagesForSummary(messages) {
+        const lines = [];
+        for (const message of messages) {
+            const role = this.formatRole(message.role);
+            const content = this.extractTextContent(message);
+            // Truncate very long messages
+            const truncatedContent = content.length > 2000
+                ? `${content.slice(0, 2000)}... [truncated]`
+                : content;
+            if (truncatedContent) {
+                lines.push(`${role}: ${truncatedContent}`);
+            }
+            // Include tool call information
+            if (message.toolCalls && message.toolCalls.length > 0) {
+                const toolNames = message.toolCalls.map((tc) => tc.function.name).join(', ');
+                lines.push(`[Used tools: ${toolNames}]`);
+            }
+        }
+        return lines.join('\n\n');
+    }
+    /**
+     * Format role for display.
+     */
+    formatRole(role) {
+        switch (role) {
+            case 'assistant': {
+                return 'Assistant';
+            }
+            case 'system': {
+                return 'System';
+            }
+            case 'tool': {
+                return 'Tool Result';
+            }
+            case 'user': {
+                return 'User';
+            }
+            default: {
+                return role.charAt(0).toUpperCase() + role.slice(1);
+            }
+        }
+    }
+    /**
+     * Generate a fallback summary without LLM.
+     */
+    generateFallbackSummary(messages) {
+        const userMessages = messages.filter((m) => m.role === 'user');
+        const assistantMessages = messages.filter((m) => m.role === 'assistant');
+        const toolMessages = messages.filter((m) => m.role === 'tool');
+        const lines = [
+            `Summarized ${messages.length} messages:`,
+            `- ${userMessages.length} user messages`,
+            `- ${assistantMessages.length} assistant responses`,
+            `- ${toolMessages.length} tool results`,
+        ];
+        // Extract key topics from user messages
+        const topics = new Set();
+        for (const msg of userMessages.slice(0, 5)) {
+            const content = this.extractTextContent(msg);
+            const words = content.split(/\s+/).slice(0, 10).join(' ');
+            if (words) {
+                topics.add(words);
+            }
+        }
+        if (topics.size > 0) {
+            const topicLines = ['', 'Key topics discussed:'];
+            for (const topic of topics) {
+                topicLines.push(`- ${topic}...`);
+            }
+            lines.push(...topicLines);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Generate a summary of messages using the LLM.
+     */
+    async generateSummary(messages) {
+        const conversationText = this.formatMessagesForSummary(messages);
+        const prompt = `You are a conversation summarizer. Summarize the following conversation concisely, preserving:
+- Key decisions made
+- Important actions taken
+- Critical context for continuing the conversation
+- Any unresolved questions or tasks
+
+Keep the summary focused and actionable. Do not include unnecessary details.
+
+Conversation:
+${conversationText}
+
+Summary:`;
+        try {
+            const summary = await this.llmProvider.generate({
+                maxTokens: this.summaryTargetTokens,
+                prompt,
+                ...(this.model && { model: this.model }),
+                temperature: 0.3, // Lower temperature for more consistent summaries
+            });
+            return summary.trim() || 'Unable to generate summary.';
+        }
+        catch {
+            // Fallback if LLM fails
+            const fallbackSummary = this.generateFallbackSummary(messages);
+            return fallbackSummary;
+        }
+    }
+}
+/**
+ * Create a ReactiveOverflowStrategy instance.
+ */
+export function createReactiveOverflowStrategy(options) {
+    return new ReactiveOverflowStrategy(options);
+}

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

@@ -0,0 +1,36 @@
+import type { ITokenizer } from '../../../../core/interfaces/i-tokenizer.js';
+import type { InternalMessage } from '../../../../core/interfaces/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/agent/infra/llm/context/context-manager.d.ts

@@ -0,0 +1,332 @@
+import type { IHistoryStorage } from '../../../core/interfaces/i-history-storage.js';
+import type { ILogger } from '../../../core/interfaces/i-logger.js';
+import type { IMessageFormatter } from '../../../core/interfaces/i-message-formatter.js';
+import type { ITokenizer } from '../../../core/interfaces/i-tokenizer.js';
+import type { AttachmentPart, InternalMessage, ToolPart, ToolState } from '../../../core/interfaces/message-types.js';
+import type { ICompressionStrategy } from './compression/types.js';
+/**
+ * Configuration for persistence retry behavior.
+ */
+export interface PersistenceRetryConfig {
+    /** Base delay between retries in milliseconds (default: 100) */
+    baseDelayMs?: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    multiplier?: number;
+}
+/**
+ * Event emitted when persistence fails after all retries.
+ */
+export interface PersistenceFailedEvent {
+    /** Number of attempts made */
+    attempts: number;
+    /** The error that caused the failure */
+    error: Error;
+    /** Session ID */
+    sessionId: string;
+}
+/**
+ * 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;
+    /** Callback invoked when persistence fails after all retries */
+    onPersistenceFailed?: (event: PersistenceFailedEvent) => void;
+    /** Configuration for persistence retry behavior */
+    persistenceRetry?: PersistenceRetryConfig;
+    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;
+    /** Callback for persistence failure events */
+    private readonly onPersistenceFailed?;
+    /** Retry configuration for persistence operations */
+    private readonly persistenceRetry;
+    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)
+     * @param options.persistenceRetry - Optional retry configuration for persistence
+     * @param options.onPersistenceFailed - Optional callback for persistence failure events
+     */
+    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 pending tool call to the current assistant message.
+     * Creates a ToolPart in pending state and adds it to the last assistant message's content.
+     *
+     * @param callId - Unique identifier for this tool call
+     * @param toolName - Name of the tool being called
+     * @param input - Parsed input arguments
+     */
+    addToolCallPending(callId: string, toolName: string, input: Record<string, unknown>): 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;
+    }, attachments?: AttachmentPart[]): 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>;
+    /**
+     * Compress messages by removing oldest messages until total tokens fit within the budget.
+     * This directly modifies the internal messages array by slicing from the beginning.
+     *
+     * @param maxTokens - Maximum token budget allowed
+     * @param messageTokens - Array of token counts corresponding to each message
+     */
+    compressMessage(maxTokens: number, messageTokens: number[]): void;
+    /**
+     * Flush any pending history writes to storage.
+     * Provides explicit durability guarantee - ensures all messages
+     * are persisted before the promise resolves.
+     *
+     * Call at turn boundaries, before session cleanup, or when
+     * explicit persistence confirmation is needed.
+     *
+     * @returns Promise that resolves when history is persisted
+     * @throws Error if persistence fails after all retries
+     */
+    flush(): 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;
+    /**
+     * Get a tool part by its call ID.
+     *
+     * @param callId - ID of the tool call to find
+     * @returns The tool part if found, undefined otherwise
+     */
+    getToolPart(callId: string): ToolPart | undefined;
+    /**
+     * 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>;
+    /**
+     * Update a tool call's state.
+     * Used for transitioning through pending → running → completed/error.
+     *
+     * @param callId - ID of the tool call to update
+     * @param stateUpdate - New state
+     */
+    updateToolCallState(callId: string, stateUpdate: ToolState): void;
+    /**
+     * Add a ToolPart to a message at the given index.
+     */
+    private addToolPartToMessage;
+    /**
+     * 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;
+    /**
+     * Find the index of the last assistant message.
+     *
+     * @returns Index of last assistant message, or -1 if not found
+     */
+    private findLastAssistantMessageIndex;
+    /**
+     * 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 with retry logic.
+     * This is called automatically after each message is added.
+     *
+     * Uses exponential backoff for retries:
+     * - Attempt 1: immediate
+     * - Attempt 2: baseDelayMs * multiplier^0 = 100ms
+     * - Attempt 3: baseDelayMs * multiplier^1 = 200ms
+     *
+     * If all retries fail, invokes onPersistenceFailed callback if configured.
+     *
+     * @returns Promise that resolves when history is persisted (or all retries exhausted)
+     */
+    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;
+    /**
+     * Sleep for the specified duration.
+     * @param ms - Duration in milliseconds
+     */
+    private sleep;
+    /**
+     * 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;
+}