@compass-ai/nova 1.0.72 → 1.0.74

package/dist/services/conversation-compactor.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Conversation compaction service using Claude to intelligently summarize
+ * conversation history while preserving key decisions and context.
+ *
+ * This module provides functionality to reduce token usage by compacting
+ * long conversation histories into concise summaries that retain essential
+ * information for continued development assistance.
+ */
+import { ConversationMessage } from '../types/session.js';
+import { Message } from '../types/anthropic.js';
+import { TokenUsage } from '../types/token.js';
+/**
+ * Result of a compaction operation
+ */
+export interface CompactionResult {
+    /** The generated summary */
+    summary: string;
+    /** Number of messages that were compacted */
+    messagesCompacted: number;
+    /** Token count before compaction */
+    tokensBefore: number;
+    /** Token count after compaction (summary tokens) */
+    tokensAfter: number;
+    /** Tokens saved by compaction */
+    tokensSaved: number;
+    /** Percentage of tokens saved */
+    savingsPercent: number;
+    /** Timestamp of compaction */
+    timestamp: string;
+    /** Token usage for the compaction API call */
+    apiUsage: TokenUsage;
+}
+/**
+ * Options for conversation compaction
+ */
+export interface CompactionOptions {
+    /** Maximum tokens for the summary (default: 2000) */
+    maxSummaryTokens?: number;
+    /** Minimum messages required before compaction (default: 10) */
+    minMessagesForCompaction?: number;
+    /** Whether to preserve the last N messages uncompacted (default: 2) */
+    preserveRecentMessages?: number;
+    /** Custom system prompt for compaction */
+    customPrompt?: string;
+    /** Whether to include code snippets in summary (default: true) */
+    includeCodeSnippets?: boolean;
+    /** Whether to include file paths mentioned (default: true) */
+    includeFilePaths?: boolean;
+}
+declare const COMPACTION_SYSTEM_PROMPT = "You are a conversation summarizer for a development assistant called Compass. Your task is to create a concise but comprehensive summary of the conversation history that preserves all essential context for continued development work.\n\nYour summary MUST include:\n1. **Key Decisions Made**: Any architectural, design, or implementation decisions\n2. **Code Changes**: Files created, modified, or deleted with brief descriptions\n3. **Current State**: What has been accomplished and what remains to be done\n4. **Important Context**: Technical constraints, user preferences, or requirements mentioned\n5. **Pending Tasks**: Any incomplete work or next steps discussed\n6. **Active Plan & Task IDs**: If there is an active plan being executed, preserve the plan ID, task IDs, and their statuses VERBATIM. These are critical references to on-disk state that cannot be reconstructed from summaries alone. Look for patterns like \"plan ID:\", \"planId:\", \"task-\", or \"[ACTIVE PLAN CONTEXT\" blocks and preserve them exactly.\n\nFormat your summary as structured markdown with clear sections. Be concise but don't omit critical information that would be needed to continue the conversation effectively.\n\nIf code snippets are essential for context (e.g., specific implementations, configurations, or patterns), include them in fenced code blocks.\n\nDo NOT include:\n- Pleasantries or conversational filler\n- Redundant information\n- Detailed explanations that can be inferred from code\n- Historical context that's no longer relevant";
+/**
+ * ConversationCompactor class provides intelligent conversation summarization
+ * using Claude to reduce token usage while preserving essential context.
+ */
+declare class ConversationCompactor {
+    private client;
+    private autoCompactThreshold;
+    constructor(autoCompactThreshold?: number);
+    /**
+     * Initializes the compactor with an Anthropic client
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Compacts a conversation history into a summary
+     *
+     * @param messages - Array of conversation messages to compact
+     * @param options - Compaction options
+     * @returns CompactionResult with the summary and statistics
+     */
+    compact(messages: ConversationMessage[], options?: CompactionOptions): Promise<CompactionResult>;
+    /**
+     * Compacts the current session's conversation history
+     *
+     * @param options - Compaction options
+     * @returns CompactionResult with the summary and statistics
+     */
+    compactCurrentSession(options?: CompactionOptions): Promise<CompactionResult>;
+    /**
+     * Checks if the current session should be auto-compacted based on token usage
+     *
+     * @returns True if auto-compaction is recommended
+     */
+    shouldAutoCompact(): Promise<boolean>;
+    /**
+     * Performs auto-compaction if the threshold is exceeded
+     *
+     * @param options - Compaction options
+     * @returns CompactionResult if compaction was performed, null otherwise
+     */
+    autoCompactIfNeeded(options?: CompactionOptions): Promise<CompactionResult | null>;
+    /**
+     * Sets the auto-compact threshold
+     *
+     * @param threshold - Token count threshold for auto-compaction
+     */
+    setAutoCompactThreshold(threshold: number): void;
+    /**
+     * Gets the current auto-compact threshold
+     *
+     * @returns The current threshold value
+     */
+    getAutoCompactThreshold(): number;
+    /**
+     * Estimates the token savings from compacting the given messages
+     *
+     * @param messages - Messages to estimate compaction for
+     * @returns Estimated token savings
+     */
+    estimateSavings(messages: ConversationMessage[]): {
+        currentTokens: number;
+        estimatedAfter: number;
+        estimatedSavings: number;
+        estimatedSavingsPercent: number;
+    };
+    /**
+     * Formats a compacted summary for display
+     *
+     * @param result - The compaction result
+     * @returns Formatted string for display
+     */
+    formatCompactionSummary(result: CompactionResult): string;
+    /**
+     * Builds the prompt for compaction
+     */
+    private buildCompactionPrompt;
+    /**
+     * Calculates the total token count for an array of messages
+     */
+    private calculateMessageTokens;
+    /**
+     * Extracts key information from messages for quick reference
+     */
+    extractKeyInfo(messages: ConversationMessage[]): {
+        filesModified: string[];
+        decisionsCount: number;
+        codeBlocksCount: number;
+    };
+    /**
+     * Compacts an array of API messages (Message[] format used in agentic loops).
+     * This handles the complex content blocks from Anthropic API format.
+     *
+     * @param messages - Array of API messages to compact
+     * @param preserveRecentCount - Number of recent messages to preserve uncompacted (default: 4)
+     * @param maxSummaryTokens - Maximum tokens for the summary (default: 3000)
+     * @returns Object with the summary and the reconstructed messages array
+     */
+    compactApiMessages(messages: Message[], preserveRecentCount?: number, maxSummaryTokens?: number, systemPrompt?: string): Promise<{
+        summary: string;
+        compactedMessages: Message[];
+        tokensBefore: number;
+        tokensAfter: number;
+        messagesCompacted: number;
+    }>;
+    /**
+     * Compacts API messages specifically for plan approval transitions.
+     * Uses a plan-focused summarization prompt that preserves architectural decisions
+     * and file paths while discarding raw exploration data (file contents, grep results).
+     *
+     * @param messages - Array of API messages to compact
+     * @param preserveRecentCount - Number of recent messages to preserve (default: 3)
+     * @param maxSummaryTokens - Maximum tokens for the summary (default: 3000)
+     * @returns Object with the summary and the reconstructed messages array
+     */
+    compactForPlanApproval(messages: Message[], preserveRecentCount?: number, maxSummaryTokens?: number): Promise<{
+        summary: string;
+        compactedMessages: Message[];
+        tokensBefore: number;
+        tokensAfter: number;
+        messagesCompacted: number;
+    }>;
+    /**
+     * Estimates token count for API Message[] array
+     */
+    private estimateApiMessageTokens;
+    /**
+     * Estimates tokens for a single content block
+     */
+    private estimateContentBlockTokens;
+    /**
+     * Formats API messages into a text representation for compaction.
+     * Empty tool results (no matches, no files found) are stripped from the
+     * per-message output and replaced with a single terse summary line at the
+     * top, saving significant tokens when the LLM performed many exploratory
+     * searches that returned nothing.
+     */
+    private formatApiMessagesForCompaction;
+    /**
+     * Scans messages for tool_result blocks that indicate empty/no-match results
+     * and returns the set of their corresponding tool_use IDs.
+     */
+    private collectEmptyToolResultIds;
+    /**
+     * Extracts the text content from a tool_result block.
+     */
+    private extractToolResultText;
+    /**
+     * Determines if a tool result's text content indicates an empty/no-match result.
+     * Matches common patterns from search_code, find_files, and list_files tools.
+     */
+    private isEmptyToolResult;
+    /**
+     * Formats a content block to text representation
+     */
+    private formatContentBlock;
+}
+/**
+ * Gets the singleton ConversationCompactor instance.
+ * Creates the instance on first call.
+ *
+ * @param autoCompactThreshold - Optional threshold for auto-compaction
+ * @returns Promise resolving to the ConversationCompactor instance
+ */
+export declare function getConversationCompactor(autoCompactThreshold?: number): Promise<ConversationCompactor>;
+/**
+ * Creates a new ConversationCompactor instance with custom configuration.
+ * Use this when you need a separate instance from the singleton.
+ *
+ * @param autoCompactThreshold - Optional threshold for auto-compaction
+ * @returns A new ConversationCompactor instance
+ */
+export declare function createConversationCompactor(autoCompactThreshold?: number): ConversationCompactor;
+export { ConversationCompactor, COMPACTION_SYSTEM_PROMPT };
+//# sourceMappingURL=conversation-compactor.d.ts.map

package/dist/services/conversation-compactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-compactor.d.ts","sourceRoot":"","sources":["../../src/services/conversation-compactor.ts"],"names":[],"mappings":"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"}