byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/llm/context/compression/enhanced-compaction.js

@@ -0,0 +1,175 @@
+/**
+ * Enhanced Compaction Strategy
+ *
+ * Extends the ReactiveOverflowStrategy with additional features from OpenCode:
+ * - Creates CompactionPart to track compaction metadata
+ * - Preserves last 2 conversation turns (configurable)
+ * - Only compacts if saving > 20K tokens (configurable)
+ * - Emits compaction events for observability
+ *
+ * This is a wrapper that adds these features on top of the existing
+ * ReactiveOverflowStrategy for backward compatibility.
+ */
+import { ReactiveOverflowStrategy } from './reactive-overflow.js';
+/**
+ * Default configuration values.
+ */
+const ENHANCED_DEFAULTS = {
+    minTokenSavings: 20_000,
+    preserveTurns: 2,
+};
+/**
+ * Enhanced Compaction Strategy.
+ *
+ * Wraps ReactiveOverflowStrategy with additional OpenCode-style features:
+ * - Token savings threshold
+ * - CompactionPart creation
+ * - Event emission
+ *
+ * @example
+ * ```typescript
+ * const strategy = new EnhancedCompactionStrategy({
+ *   llmProvider: myLlmProvider,
+ *   eventBus: sessionEventBus,
+ *   minTokenSavings: 20000,
+ *   preserveTurns: 2,
+ * })
+ *
+ * const compactedHistory = await strategy.compress(history, maxTokens, tokenizer)
+ * ```
+ */
+export class EnhancedCompactionStrategy {
+    baseStrategy;
+    eventBus;
+    /** Track the last compaction result for observability */
+    lastCompactionResult;
+    minTokenSavings;
+    preserveTurns;
+    constructor(options) {
+        // Create base strategy with configured preserve turns
+        this.baseStrategy = new ReactiveOverflowStrategy({
+            ...options,
+            preserveLastNTurns: options.preserveTurns ?? ENHANCED_DEFAULTS.preserveTurns,
+        });
+        this.eventBus = options.eventBus;
+        this.minTokenSavings = options.minTokenSavings ?? ENHANCED_DEFAULTS.minTokenSavings;
+        this.preserveTurns = options.preserveTurns ?? ENHANCED_DEFAULTS.preserveTurns;
+    }
+    /**
+     * Compress history with enhanced features.
+     */
+    async compress(history, maxHistoryTokens, tokenizer) {
+        // Calculate tokens before compression
+        const tokensBefore = this.countTokens(history, tokenizer);
+        // Check if compression is needed at all
+        if (tokensBefore <= maxHistoryTokens) {
+            return history;
+        }
+        // Apply base compression strategy
+        const compressedHistory = await this.baseStrategy.compress(history, maxHistoryTokens, tokenizer);
+        // Calculate tokens after compression
+        const tokensAfter = this.countTokens(compressedHistory, tokenizer);
+        const tokensSaved = tokensBefore - tokensAfter;
+        // Check minimum savings threshold
+        if (tokensSaved < this.minTokenSavings) {
+            // Not enough savings, return original (let other strategies handle it)
+            return history;
+        }
+        // Find compacted message IDs (messages that were removed or summarized)
+        const compactedMessageIds = this.findCompactedMessageIds(history, compressedHistory);
+        // Create compaction result for tracking
+        this.lastCompactionResult = {
+            compactedAt: Date.now(),
+            compactedMessageIds,
+            messageCountAfter: compressedHistory.length,
+            messageCountBefore: history.length,
+            tokensAfter,
+            tokensBefore,
+            tokensSaved,
+        };
+        // Emit compaction event if event bus provided
+        if (this.eventBus) {
+            this.eventBus.emit('llmservice:contextCompressed', {
+                compressedTokens: tokensAfter,
+                originalTokens: tokensBefore,
+                strategy: 'summary',
+            });
+        }
+        return compressedHistory;
+    }
+    /**
+     * Create a CompactionPart for the given compaction result.
+     * Can be used to insert into message parts for tracking.
+     */
+    createCompactionPart(summary) {
+        if (!this.lastCompactionResult) {
+            return undefined;
+        }
+        return {
+            compactedMessageIds: this.lastCompactionResult.compactedMessageIds,
+            id: `compaction-${Date.now()}`,
+            summary,
+            timestamp: this.lastCompactionResult.compactedAt,
+            tokensSaved: this.lastCompactionResult.tokensSaved,
+            type: 'compaction',
+        };
+    }
+    /**
+     * Get the last compaction result for observability.
+     */
+    getLastCompactionResult() {
+        return this.lastCompactionResult;
+    }
+    getName() {
+        return 'EnhancedCompaction';
+    }
+    /**
+     * Count total tokens in history.
+     */
+    countTokens(history, tokenizer) {
+        let total = 0;
+        for (const message of history) {
+            // Role overhead
+            total += 4;
+            if (typeof message.content === 'string') {
+                total += tokenizer.countTokens(message.content);
+            }
+            else if (Array.isArray(message.content)) {
+                for (const part of message.content) {
+                    total +=
+                        part.type === 'text' || part.type === 'reasoning'
+                            ? tokenizer.countTokens(part.text)
+                            : 100; // Estimate for non-text parts
+                }
+            }
+            // Tool calls overhead
+            if (message.toolCalls) {
+                for (const call of message.toolCalls) {
+                    total += tokenizer.countTokens(call.function.name);
+                    total += tokenizer.countTokens(call.function.arguments);
+                }
+            }
+        }
+        return total;
+    }
+    /**
+     * Find message IDs that were compacted (removed or summarized).
+     * Since messages don't have IDs, we use indices as pseudo-IDs.
+     */
+    findCompactedMessageIds(original, compressed) {
+        const compactedIds = [];
+        const compressedCount = compressed.filter((m) => !m.metadata?.isSummary).length;
+        // Messages from index 0 to (original.length - compressedCount) were compacted
+        const compactedCount = original.length - compressedCount;
+        for (let i = 0; i < compactedCount; i++) {
+            compactedIds.push(`msg-${i}`);
+        }
+        return compactedIds;
+    }
+}
+/**
+ * Create an EnhancedCompactionStrategy instance.
+ */
+export function createEnhancedCompactionStrategy(options) {
+    return new EnhancedCompactionStrategy(options);
+}

package/dist/infra/cipher/llm/context/compression/filter-compacted.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Filter compacted messages utility.
+ *
+ * This module provides read-time filtering of message history based on
+ * compression metadata. When a summary message exists (with metadata.isSummary === true),
+ * messages before it are filtered out since they've been summarized.
+ *
+ * Key design principles:
+ * - Full history preserved in storage (audit trail)
+ * - Filtering happens at read-time, not storage-time
+ * - Summary message marks the boundary
+ *
+ * Based on dexto's filterCompacted() pattern.
+ */
+import type { InternalMessage } from '../../../../../core/interfaces/cipher/message-types.js';
+/**
+ * Filter history to exclude messages before the most recent summary.
+ *
+ * When a summary message exists (metadata.isSummary === true), this function
+ * returns only the summary message and everything after it. This implements
+ * read-time compression where old messages are logically hidden but physically
+ * preserved in storage.
+ *
+ * @param history - Full message history to filter
+ * @returns Filtered history with old messages excluded
+ *
+ * @example
+ * ```typescript
+ * // Before filtering: [msg1, msg2, msg3, summaryMsg, msg4, msg5]
+ * // After filtering:  [summaryMsg, msg4, msg5]
+ *
+ * const filtered = filterCompacted(history);
+ * ```
+ */
+export declare function filterCompacted(history: readonly InternalMessage[]): InternalMessage[];
+/**
+ * Check if history contains a summary message.
+ *
+ * Useful for determining if filtering would have any effect.
+ *
+ * @param history - Message history to check
+ * @returns true if history contains a summary message
+ */
+export declare function hasSummaryMessage(history: readonly InternalMessage[]): boolean;
+/**
+ * Find the summary message in history.
+ *
+ * @param history - Message history to search
+ * @returns The summary message or undefined if not found
+ */
+export declare function findSummaryMessage(history: readonly InternalMessage[]): InternalMessage | undefined;
+/**
+ * Get the count of messages that would be filtered out.
+ *
+ * @param history - Message history to analyze
+ * @returns Number of messages before the summary that would be filtered
+ */
+export declare function getFilteredMessageCount(history: readonly InternalMessage[]): number;
+/**
+ * Get summary statistics about compression state.
+ *
+ * @param history - Message history to analyze
+ * @returns Statistics about the compression state
+ */
+export declare function getCompressionStats(history: readonly InternalMessage[]): {
+    /** When compression occurred (from summary metadata) */
+    compactedAt?: number;
+    /** Whether history has been compressed */
+    hasCompression: boolean;
+    /** Number of messages hidden by compression */
+    hiddenMessageCount: number;
+    /** Number of messages that were summarized (from summary metadata) */
+    summarizedMessageCount: number;
+    /** Number of messages currently visible (after filtering) */
+    visibleMessageCount: number;
+};
+/**
+ * Check if a message is a summary message.
+ *
+ * @param message - Message to check
+ * @returns true if the message is a summary
+ */
+export declare function isSummaryMessage(message: InternalMessage): boolean;

package/dist/infra/cipher/llm/context/compression/filter-compacted.js

@@ -0,0 +1,150 @@
+/**
+ * Filter compacted messages utility.
+ *
+ * This module provides read-time filtering of message history based on
+ * compression metadata. When a summary message exists (with metadata.isSummary === true),
+ * messages before it are filtered out since they've been summarized.
+ *
+ * Key design principles:
+ * - Full history preserved in storage (audit trail)
+ * - Filtering happens at read-time, not storage-time
+ * - Summary message marks the boundary
+ *
+ * Based on dexto's filterCompacted() pattern.
+ */
+/**
+ * Filter history to exclude messages before the most recent summary.
+ *
+ * When a summary message exists (metadata.isSummary === true), this function
+ * returns only the summary message and everything after it. This implements
+ * read-time compression where old messages are logically hidden but physically
+ * preserved in storage.
+ *
+ * @param history - Full message history to filter
+ * @returns Filtered history with old messages excluded
+ *
+ * @example
+ * ```typescript
+ * // Before filtering: [msg1, msg2, msg3, summaryMsg, msg4, msg5]
+ * // After filtering:  [summaryMsg, msg4, msg5]
+ *
+ * const filtered = filterCompacted(history);
+ * ```
+ */
+export function filterCompacted(history) {
+    if (!history || history.length === 0) {
+        return [];
+    }
+    // Find the most recent summary message (search backwards for efficiency)
+    let summaryIndex = -1;
+    for (let i = history.length - 1; i >= 0; i--) {
+        const msg = history[i];
+        if (msg?.metadata?.isSummary === true) {
+            summaryIndex = i;
+            break;
+        }
+    }
+    // If no summary found, return full history
+    if (summaryIndex === -1) {
+        return [...history];
+    }
+    // Return summary + everything after it
+    return history.slice(summaryIndex);
+}
+/**
+ * Check if history contains a summary message.
+ *
+ * Useful for determining if filtering would have any effect.
+ *
+ * @param history - Message history to check
+ * @returns true if history contains a summary message
+ */
+export function hasSummaryMessage(history) {
+    if (!history || history.length === 0)
+        return false;
+    return history.some((msg) => msg?.metadata?.isSummary === true);
+}
+/**
+ * Find the summary message in history.
+ *
+ * @param history - Message history to search
+ * @returns The summary message or undefined if not found
+ */
+export function findSummaryMessage(history) {
+    if (!history || history.length === 0)
+        return undefined;
+    // Search backwards to find the most recent summary
+    for (let i = history.length - 1; i >= 0; i--) {
+        const msg = history[i];
+        if (msg?.metadata?.isSummary === true) {
+            return msg;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get the count of messages that would be filtered out.
+ *
+ * @param history - Message history to analyze
+ * @returns Number of messages before the summary that would be filtered
+ */
+export function getFilteredMessageCount(history) {
+    if (!history || history.length === 0)
+        return 0;
+    // Find summary index
+    let summaryIndex = -1;
+    for (let i = history.length - 1; i >= 0; i--) {
+        if (history[i]?.metadata?.isSummary === true) {
+            summaryIndex = i;
+            break;
+        }
+    }
+    // No summary = nothing filtered
+    if (summaryIndex === -1)
+        return 0;
+    // Count messages before the summary
+    return summaryIndex;
+}
+/**
+ * Get summary statistics about compression state.
+ *
+ * @param history - Message history to analyze
+ * @returns Statistics about the compression state
+ */
+export function getCompressionStats(history) {
+    if (!history || history.length === 0) {
+        return {
+            hasCompression: false,
+            hiddenMessageCount: 0,
+            summarizedMessageCount: 0,
+            visibleMessageCount: 0,
+        };
+    }
+    const summaryMessage = findSummaryMessage(history);
+    if (!summaryMessage) {
+        return {
+            hasCompression: false,
+            hiddenMessageCount: 0,
+            summarizedMessageCount: 0,
+            visibleMessageCount: history.length,
+        };
+    }
+    const filtered = filterCompacted(history);
+    const hiddenCount = history.length - filtered.length;
+    return {
+        compactedAt: summaryMessage.metadata?.compactedAt,
+        hasCompression: true,
+        hiddenMessageCount: hiddenCount,
+        summarizedMessageCount: summaryMessage.metadata?.summarizedMessageCount || hiddenCount,
+        visibleMessageCount: filtered.length,
+    };
+}
+/**
+ * Check if a message is a summary message.
+ *
+ * @param message - Message to check
+ * @returns true if the message is a summary
+ */
+export function isSummaryMessage(message) {
+    return message?.metadata?.isSummary === true;
+}

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

@@ -1,6 +1,11 @@
 /**
  * Context compression strategies module
  */
+export { createEnhancedCompactionStrategy, EnhancedCompactionStrategy } from './enhanced-compaction.js';
+export type { CompactionResult, EnhancedCompactionOptions } from './enhanced-compaction.js';
+export { filterCompacted, findSummaryMessage, getCompressionStats, getFilteredMessageCount, hasSummaryMessage, isSummaryMessage, } from './filter-compacted.js';
 export { MiddleRemovalStrategy } from './middle-removal.js';
 export { OldestRemovalStrategy } from './oldest-removal.js';
+export { createReactiveOverflowStrategy, ReactiveOverflowStrategy } from './reactive-overflow.js';
+export type { ReactiveOverflowOptions } from './reactive-overflow.js';
 export type { CompressionStrategyOptions, ICompressionStrategy } from './types.js';

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

@@ -1,5 +1,11 @@
 /**
  * Context compression strategies module
  */
+// Compression strategies (alphabetical order)
+export { createEnhancedCompactionStrategy, EnhancedCompactionStrategy } from './enhanced-compaction.js';
+// Filter utilities
+export { filterCompacted, findSummaryMessage, getCompressionStats, getFilteredMessageCount, hasSummaryMessage, isSummaryMessage, } from './filter-compacted.js';
+// More compression strategies
 export { MiddleRemovalStrategy } from './middle-removal.js';
 export { OldestRemovalStrategy } from './oldest-removal.js';
+export { createReactiveOverflowStrategy, ReactiveOverflowStrategy } from './reactive-overflow.js';

package/dist/infra/cipher/llm/context/compression/reactive-overflow.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 type { ILlmProvider } from '../../../../../core/interfaces/cipher/i-llm-provider.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 './types.js';
+/**
+ * Options for the ReactiveOverflowStrategy.
+ */
+export interface ReactiveOverflowOptions {
+    /** LLM provider for generating summaries */
+    llmProvider: ILlmProvider;
+    /**
+     * Minimum messages to consider for summarization.
+     * If fewer messages are available, compression is skipped.
+     * Default: 10
+     */
+    minMessagesToSummarize?: number;
+    /**
+     * Model to use for summarization.
+     * Default: uses same model as conversation (passed via generate params)
+     */
+    model?: string;
+    /**
+     * Number of recent turns to always preserve (not summarize).
+     * Default: 2
+     */
+    preserveLastNTurns?: number;
+    /**
+     * Target token count for the summary.
+     * Default: 2000
+     */
+    summaryTargetTokens?: number;
+}
+/**
+ * Reactive Overflow compression strategy.
+ *
+ * Uses an LLM to generate intelligent summaries when context overflows.
+ */
+export declare class ReactiveOverflowStrategy implements ICompressionStrategy {
+    private readonly llmProvider;
+    private readonly minMessagesToSummarize;
+    private readonly model?;
+    private readonly preserveLastNTurns;
+    private readonly summaryTargetTokens;
+    constructor(options: ReactiveOverflowOptions);
+    compress(history: InternalMessage[], maxHistoryTokens: number, tokenizer: ITokenizer): Promise<InternalMessage[]>;
+    getName(): string;
+    /**
+     * Count tokens in message history.
+     */
+    private countHistoryTokens;
+    /**
+     * Count tokens in a single message.
+     */
+    private countMessageTokens;
+    /**
+     * Extract text content from a message.
+     */
+    private extractTextContent;
+    /**
+     * Find turn boundaries in message history.
+     *
+     * A turn boundary is the index where a user message starts.
+     * Returns indices of all user messages.
+     */
+    private findTurnBoundaries;
+    /**
+     * Format messages for the summary prompt.
+     */
+    private formatMessagesForSummary;
+    /**
+     * Format role for display.
+     */
+    private formatRole;
+    /**
+     * Generate a fallback summary without LLM.
+     */
+    private generateFallbackSummary;
+    /**
+     * Generate a summary of messages using the LLM.
+     */
+    private generateSummary;
+}
+/**
+ * Create a ReactiveOverflowStrategy instance.
+ */
+export declare function createReactiveOverflowStrategy(options: ReactiveOverflowOptions): ReactiveOverflowStrategy;