@vybestack/llxprt-code-agents 0.10.0-nightly.260613.1adad3b34

package/dist/src/compression/CompressionHandler.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GenerateContentConfig } from '@google/genai';
+import type { HistoryService } from '@vybestack/llxprt-code-core/services/history/HistoryService.js';
+import type { IContent } from '@vybestack/llxprt-code-core/services/history/IContent.js';
+import type { AgentRuntimeContext } from '@vybestack/llxprt-code-core/runtime/AgentRuntimeContext.js';
+import type { RuntimeProvider as IProvider } from '@vybestack/llxprt-code-core/runtime/contracts/RuntimeProvider.js';
+import type { CompressionContext, CompressionProviderResult } from '@vybestack/llxprt-code-core/core/compression/types.js';
+import { PerformCompressionResult } from '@vybestack/llxprt-code-core/core/turn.js';
+/**
+ * CompressionHandler orchestrates all compression logic for ChatSession.
+ * Manages compression state, retry/fallback logic, and density optimization.
+ *
+ * @plan PLAN-20260220-DECOMPOSE.P03
+ * @requirement Module 3 specification
+ */
+export declare class CompressionHandler {
+    private readonly runtimeContext;
+    private readonly historyService;
+    private readonly generationConfig;
+    private readonly providerResolver;
+    private readonly hookTrigger;
+    static readonly TOKEN_SAFETY_MARGIN = 1000;
+    static readonly DEFAULT_COMPLETION_BUDGET = 65536;
+    static readonly COMPRESSION_COOLDOWN_MS = 60000;
+    static readonly COMPRESSION_FAILURE_THRESHOLD = 3;
+    static readonly INEFFECTIVE_COMPRESSION_REDUCTION_THRESHOLD = 0.05;
+    static readonly RECENT_COMPRESSION_WINDOW_MS = 60000;
+    private compressionPromise;
+    private compressionFailureCount;
+    private lastCompressionFailureTime;
+    private lastSuccessfulCompressionTime;
+    densityDirty: boolean;
+    _suppressDensityDirty: boolean;
+    private activeTodosProvider?;
+    lastPromptTokenCount: number | null;
+    private logger;
+    constructor(runtimeContext: AgentRuntimeContext, historyService: HistoryService, generationConfig: GenerateContentConfig, providerResolver: (compressionProfileName: string | undefined) => CompressionProviderResult | Promise<CompressionProviderResult>, hookTrigger: (context: CompressionContext) => Promise<void>);
+    /**
+     * Calculate effective token count based on reasoning settings.
+     * Accounts for whether reasoning will be included in API calls.
+     *
+     * @plan PLAN-20251202-THINKING.P15
+     * @requirement REQ-THINK-005.1, REQ-THINK-005.2
+     */
+    getEffectiveTokenCount(): number;
+    /**
+     * Run density optimization if the active strategy supports it and new content exists.
+     * Called before threshold check in ensureCompressionBeforeSend and enforceContextWindow.
+     *
+     * @plan PLAN-20260211-HIGHDENSITY.P20
+     * @requirement REQ-HD-002.1-002.9
+     */
+    ensureDensityOptimized(): Promise<void>;
+    /**
+     * Check if compression is needed based on token count.
+     * Includes system prompt in both actual API count and estimated count paths.
+     *
+     * @plan PLAN-20251028-STATELESS6.P10
+     * @requirement REQ-STAT6-002.2
+     */
+    shouldCompress(pendingTokens?: number): boolean;
+    /**
+     * Ensure compression runs before sending a message if needed.
+     * Waits for ongoing compression and triggers new compression if threshold reached.
+     *
+     * @plan PLAN-20260220-DECOMPOSE.P03
+     */
+    ensureCompressionBeforeSend(prompt_id: string, pendingTokens: number, source: 'send' | 'stream', trigger?: 'manual' | 'auto'): Promise<void>;
+    /**
+     * Enforce hard context window limits with compression and density optimization.
+     * Throws if limits cannot be satisfied even after compression.
+     *
+     * @plan PLAN-20260220-DECOMPOSE.P03
+     */
+    /**
+     * Compute the baseline prompt token count for hard-limit projection.
+     * Prefer API-observed prompt tokens when available (includes cache read/write).
+     */
+    private getProjectedPromptBaseline;
+    /**
+     * Compute the projected token count for a pending request.
+     */
+    private computeProjectedTokens;
+    /**
+     * Compute context-window limits and completion budget for enforcement.
+     */
+    private computeContextLimits;
+    enforceContextWindow(pendingTokens: number, promptId: string, provider?: IProvider): Promise<void>;
+    /**
+     * Force truncation fallback when primary compression was ineffective.
+     * Returns the recomputed projected token count after fallback attempt.
+     */
+    private forceTruncationIfIneffective;
+    /**
+     * Build a diagnostic error for context window overflow after all reduction attempts.
+     */
+    private buildContextOverflowError;
+    /**
+     * Perform compression with retry, fallback, and cooldown logic.
+     *
+     * @plan PLAN-20260218-COMPRESSION-RETRY.P01
+     * @requirement REQ-CS-006.1, REQ-CS-002.9, REQ-CR-003-005
+     */
+    performCompression(prompt_id: string, options?: {
+        bypassCooldown?: boolean;
+        trigger?: 'manual' | 'auto';
+    }): Promise<PerformCompressionResult>;
+    /**
+     * Check if compression is in cooldown after repeated failures.
+     *
+     * @plan PLAN-20260218-COMPRESSION-RETRY.P01
+     * @requirement REQ-CR-005
+     */
+    isCompressionInCooldown(): boolean;
+    /**
+     * Returns true if compression completed successfully within the recent window.
+     * Used to distinguish ALREADY_COMPRESSED from NOOP in the /compress command.
+     */
+    wasRecentlyCompressed(): boolean;
+    /**
+     * Execute compression with retry for transient errors and fallback to truncation.
+     *
+     * @plan PLAN-20260218-COMPRESSION-RETRY.P01
+     * @requirement REQ-CR-003-005
+     */
+    private runCompressionWithRetryAndFallback;
+    /**
+     * Attempt fallback compression using TopDownTruncationStrategy.
+     *
+     * @plan PLAN-20260218-COMPRESSION-RETRY.P01
+     * @requirement REQ-CR-004-005
+     */
+    private performFallbackCompression;
+    /**
+     * Build CompressionContext for compression strategies.
+     *
+     * @plan PLAN-20260211-COMPRESSION.P14
+     * @requirement REQ-CS-001.6
+     */
+    buildCompressionContext(promptId: string): Promise<CompressionContext>;
+    /**
+     * Mark density optimization as dirty (new content added).
+     * Respects _suppressDensityDirty flag during compression rebuilds.
+     *
+     * @plan PLAN-20260211-HIGHDENSITY.P20
+     * @requirement REQ-HD-002.6
+     */
+    markDensityDirty(): void;
+    /**
+     * Set the active todos provider callback.
+     *
+     * @plan PLAN-20260220-DECOMPOSE.P03
+     */
+    setActiveTodosProvider(provider: () => Promise<string | undefined>): void;
+    /**
+     * Get the last prompt token count from API.
+     *
+     * @plan PLAN-20260220-DECOMPOSE.P03
+     */
+    getLastPromptTokenCount(): number;
+    /**
+     * Set the last prompt token count from API response.
+     *
+     * @plan PLAN-20260220-DECOMPOSE.P03
+     */
+    setLastPromptTokenCount(count: number): void;
+    /**
+     * Estimate token count for pending content.
+     * Delegates to compressionBudgeting helper.
+     *
+     * @plan PLAN-20260220-DECOMPOSE.P03
+     */
+    estimatePendingTokens(contents: IContent[]): Promise<number>;
+}