@codebolt/agent 5.0.6 → 5.0.8

package/dist/processor-pieces/postToolCallProcessors/conversationCompactorModifier.d.ts

@@ -1,18 +1,215 @@
 /**
  * Conversation Compactor Modifier
  * Post-Tool Call processor for compacting conversation history to reduce context size
+ *
+ * Inspired by gemini-cli's ChatCompressionService approach:
+ * - Truncates large tool outputs
+ * - Summarizes old conversation history using LLM
+ * - Preserves recent context for continuity
  */
 import { BasePostToolCallProcessor } from '../base/basePostToolCallProcessor';
 import { PostToolCallProcessorInput, PostToolCallProcessorOutput } from '@codebolt/types/agent';
+import { MessageObject } from '@codebolt/types/sdk';
+/**
+ * Compression Status Enum - tracks the result of compression attempts
+ */
+export declare enum CompressionStatus {
+    /** Compression was successful */
+    COMPRESSED = "COMPRESSED",
+    /** Compression not needed - under threshold */
+    NOOP = "NOOP",
+    /** Compression failed - summary larger than original */
+    FAILED_INFLATED_TOKEN_COUNT = "FAILED_INFLATED_TOKEN_COUNT",
+    /** Compression failed - token counting error */
+    FAILED_TOKEN_COUNT_ERROR = "FAILED_TOKEN_COUNT_ERROR",
+    /** Compression failed - LLM summarization error */
+    FAILED_SUMMARIZATION_ERROR = "FAILED_SUMMARIZATION_ERROR",
+    /** Tool output truncation was applied (without full compression) */
+    TOOL_OUTPUT_TRUNCATED = "TOOL_OUTPUT_TRUNCATED"
+}
+/**
+ * Compression metadata - tracks compression state and statistics
+ */
+export interface CompressionMetadata {
+    /** Status of the compression attempt */
+    status: CompressionStatus;
+    /** Original token count before compression */
+    originalTokenCount: number;
+    /** Token count after compression */
+    newTokenCount: number;
+    /** Number of messages that were compressed/removed */
+    messagesCompressed: number;
+    /** Number of messages preserved */
+    messagesPreserved: number;
+    /** Whether tool outputs were truncated */
+    toolOutputsTruncated: boolean;
+    /** Number of failed compression attempts in this session */
+    failedAttempts: number;
+    /** Timestamp of compression */
+    timestamp: string;
+    /** Compression strategy used */
+    strategy: 'simple' | 'smart' | 'summarize';
+}
+/**
+ * Configuration options for ConversationCompactorModifier
+ * Based on gemini-cli thresholds with codebolt adaptations
+ */
 export interface ConversationCompactorOptions {
-    maxMessages?: number;
-    preserveSystemMessages?: boolean;
-    preserveLastUserMessages?: number;
-    preserveLastToolResults?: number;
+    /**
+     * Token threshold as fraction of model limit (0.0 - 1.0)
+     * Compression triggers when tokens exceed this fraction of the limit
+     * @default 0.5 (compress at 50% of limit, same as gemini-cli)
+     */
+    compressionTokenThreshold?: number;
+    /**
+     * Fraction of recent history to preserve after compression (0.0 - 1.0)
+     * @default 0.3 (keep last 30% of history, same as gemini-cli)
+     */
+    preserveThreshold?: number;
+    /**
+     * Maximum token budget for tool response content
+     * Older tool outputs exceeding this budget will be truncated
+     * @default 50000 (same as gemini-cli COMPRESSION_FUNCTION_RESPONSE_TOKEN_BUDGET)
+     */
+    toolResponseTokenBudget?: number;
+    /**
+     * Maximum lines to keep when truncating tool outputs
+     * @default 30 (same as gemini-cli COMPRESSION_TRUNCATE_LINES)
+     */
+    truncateLines?: number;
+    /**
+     * Compression strategy
+     * - 'simple': Just truncate old messages
+     * - 'smart': Truncate tool outputs + remove old messages intelligently
+     * - 'summarize': Use LLM to generate state_snapshot summary
+     * @default 'smart'
+     */
     compactStrategy?: 'simple' | 'smart' | 'summarize';
+    /**
+     * Whether to preserve system messages during compression
+     * @default true
+     */
+    preserveSystemMessages?: boolean;
+    /**
+     * Minimum number of user messages to always preserve
+     * @default 3
+     */
+    minPreservedUserMessages?: number;
+    /**
+     * Whether to enable LLM verification pass for summarization
+     * Adds a second LLM call to verify summary accuracy
+     * @default false (for performance)
+     */
+    enableVerificationPass?: boolean;
+    /**
+     * Model token limit (auto-detected if not specified)
+     * @default 128000
+     */
+    modelTokenLimit?: number;
+    /**
+     * LLM role for summarization calls
+     * @default 'summarizer'
+     */
+    llmRole?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    enableLogging?: boolean;
 }
 export declare class ConversationCompactorModifier extends BasePostToolCallProcessor {
-    private options;
+    private readonly options;
+    private failedCompressionAttempts;
+    private hasFailedCompression;
     constructor(options?: ConversationCompactorOptions);
+    /**
+     * Estimates token count for a string
+     * Uses the ~4 characters per token approximation
+     */
+    private estimateTokens;
+    /**
+     * Counts tokens for an array of messages
+     */
+    private countMessageTokens;
+    /**
+     * Gets content length from a message (handles string and array content)
+     */
+    private getMessageContentLength;
+    /**
+     * Extracts text content from a message
+     */
+    private getMessageContent;
+    /**
+     * Checks if a message is a function/tool response
+     */
+    private isToolResponseMessage;
+    /**
+     * Truncates content to a specified number of lines
+     * Keeps first half and last half of allowed lines for context
+     */
+    private truncateToLines;
+    /**
+     * Truncates large tool output messages to reduce token count
+     * Iterates backwards (prioritizing recent messages) following gemini-cli approach
+     */
+    private truncateLargeToolOutputs;
+    /**
+     * Adjusts split index to the start of the next turn (user message)
+     * Ensures we don't split in the middle of a conversation turn
+     */
+    private adjustToTurnBoundary;
+    /**
+     * Maps filtered array index back to original messages array
+     */
+    private mapToOriginalIndex;
+    /**
+     * Finds the index to split history for compression
+     * Returns the index after which messages should be preserved
+     */
+    private findCompressionSplitIndex;
+    /**
+     * Generates the compression prompt with state_snapshot XML format
+     * Based on gemini-cli's approach
+     */
+    private getCompressionPrompt;
+    /**
+     * Generates a state snapshot summary using LLM
+     */
+    private generateStateSummary;
+    /**
+     * Optional verification pass - asks LLM to verify and correct the summary
+     */
+    private verifySummary;
+    /**
+     * Simple compression strategy - just removes old messages
+     */
+    private compressSimple;
+    /**
+     * Smart compression strategy - truncates tool outputs + intelligent message removal
+     */
+    private compressSmart;
+    /**
+     * Summarize compression strategy - uses LLM to create state snapshot
+     */
+    private compressSummarize;
     modify(input: PostToolCallProcessorInput): Promise<PostToolCallProcessorOutput>;
+    /**
+     * Resets the compression state (useful for new conversations)
+     */
+    resetCompressionState(): void;
+    /**
+     * Gets the current compression statistics
+     */
+    getCompressionStats(): {
+        failedAttempts: number;
+        hasFailedCompression: boolean;
+        options: Required<ConversationCompactorOptions>;
+    };
+    /**
+     * Forces compression regardless of threshold (for testing or manual trigger)
+     */
+    forceCompress(messages: MessageObject[]): Promise<{
+        messages: MessageObject[];
+        metadata: Partial<CompressionMetadata>;
+    }>;
 }