agentic-qe 3.8.14 → 3.9.0

package/dist/cli/lazy-registry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Lazy Command Registry
+ *
+ * Registers lightweight Commander stubs (name + description) for --help,
+ * but defers loading the full command factory/handler until the user actually
+ * runs the command. This avoids loading all command modules at startup.
+ */
+import { Command } from 'commander';
+export interface LazyCommandDef {
+    name: string;
+    description: string;
+    aliases?: string[];
+    factory: () => Promise<Command>;
+}
+/**
+ * Register a lazy command that returns a Command object.
+ * Used for command factories (createTestCommand, etc.)
+ */
+export declare function registerLazyCommand(program: Command, def: LazyCommandDef): void;
+/**
+ * Register a lazy handler that implements ICommandHandler.register().
+ * Used for handlers registered via the CommandRegistry pattern.
+ */
+export declare function registerLazyHandler(program: Command, name: string, description: string, factory: () => Promise<{
+    register(program: Command, context: any): void;
+}>, context: any, aliases?: string[]): void;
+//# sourceMappingURL=lazy-registry.d.ts.map

package/dist/cli/lazy-registry.js

@@ -0,0 +1,70 @@
+/**
+ * Lazy Command Registry
+ *
+ * Registers lightweight Commander stubs (name + description) for --help,
+ * but defers loading the full command factory/handler until the user actually
+ * runs the command. This avoids loading all command modules at startup.
+ */
+/**
+ * Replace a stub command with the real one and re-parse.
+ * Shared logic between registerLazyCommand and registerLazyHandler.
+ */
+function createLazyStub(program, name, description, aliases) {
+    const stub = program.command(name).description(description);
+    if (aliases) {
+        for (const a of aliases) {
+            stub.alias(a);
+        }
+    }
+    // Disable built-in help on the stub so --help triggers the action
+    // instead of displaying the stub's minimal help.
+    stub.helpOption(false);
+    stub.allowUnknownOption(true);
+    stub.allowExcessArguments(true);
+    return stub;
+}
+function removeStub(program, stub) {
+    const cmds = program.commands;
+    const idx = cmds.indexOf(stub);
+    if (idx >= 0)
+        cmds.splice(idx, 1);
+}
+/**
+ * Register a lazy command that returns a Command object.
+ * Used for command factories (createTestCommand, etc.)
+ */
+export function registerLazyCommand(program, def) {
+    const stub = createLazyStub(program, def.name, def.description, def.aliases);
+    stub.action(async () => {
+        try {
+            const realCmd = await def.factory();
+            removeStub(program, stub);
+            program.addCommand(realCmd);
+            await program.parseAsync(process.argv);
+        }
+        catch (error) {
+            console.error(`Failed to load command '${def.name}':`, error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    });
+}
+/**
+ * Register a lazy handler that implements ICommandHandler.register().
+ * Used for handlers registered via the CommandRegistry pattern.
+ */
+export function registerLazyHandler(program, name, description, factory, context, aliases) {
+    const stub = createLazyStub(program, name, description, aliases);
+    stub.action(async () => {
+        try {
+            const handler = await factory();
+            removeStub(program, stub);
+            handler.register(program, context);
+            await program.parseAsync(process.argv);
+        }
+        catch (error) {
+            console.error(`Failed to load command '${name}':`, error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=lazy-registry.js.map

package/dist/context/compaction/context-budget.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Agentic QE v3 - Context Budget Tracker (IMP-08)
+ *
+ * Tracks estimated token usage across a session and transitions through
+ * 5 operational states based on remaining budget. Emits events on state
+ * transitions so the CompactionPipeline can auto-trigger appropriate tiers.
+ *
+ * States (by remaining tokens):
+ *   Normal      > 25_000   -- No action needed
+ *   Warning     <= 25_000  -- Advisory only
+ *   Pressure    <= 18_000  -- Tier 1 (microcompact) runs proactively
+ *   AutoCompact <= 13_000  -- Tier 2/3 auto-triggered
+ *   Blocking    <= 3_000   -- Tier 4 reactive, blocks new tool calls
+ */
+import { EventEmitter } from 'events';
+export type BudgetState = 'normal' | 'warning' | 'pressure' | 'auto-compact' | 'blocking';
+export interface BudgetTransition {
+    from: BudgetState;
+    to: BudgetState;
+    remainingTokens: number;
+    totalBudget: number;
+    timestamp: number;
+}
+export interface BudgetSnapshot {
+    state: BudgetState;
+    usedTokens: number;
+    remainingTokens: number;
+    totalBudget: number;
+    utilizationPercent: number;
+}
+export interface ContextBudgetOptions {
+    /** Total context window budget in tokens (default: 100_000) */
+    totalBudget?: number;
+    /** Threshold for Warning state (default: 25_000 remaining) */
+    warningThreshold?: number;
+    /** Threshold for Pressure state (default: 18_000 remaining) */
+    pressureThreshold?: number;
+    /** Threshold for AutoCompact state (default: 13_000 remaining) */
+    autoCompactThreshold?: number;
+    /** Threshold for Blocking state (default: 3_000 remaining) */
+    blockingThreshold?: number;
+}
+export declare class ContextBudgetTracker extends EventEmitter {
+    private readonly totalBudget;
+    private readonly warningThreshold;
+    private readonly pressureThreshold;
+    private readonly autoCompactThreshold;
+    private readonly blockingThreshold;
+    private usedTokens;
+    private currentState;
+    constructor(options?: ContextBudgetOptions);
+    /** Add tokens to the usage counter and re-evaluate state. */
+    addTokens(count: number): void;
+    /** Remove tokens (e.g., after compaction freed space). */
+    releaseTokens(count: number): void;
+    /** Set the absolute token count (e.g., after a full recount). */
+    setUsedTokens(count: number): void;
+    /** Current state. */
+    getState(): BudgetState;
+    /** Full snapshot of the budget. */
+    getSnapshot(): BudgetSnapshot;
+    /** Whether the budget is in a state that should block new tool calls. */
+    isBlocking(): boolean;
+    /** Whether compaction should auto-trigger. */
+    shouldAutoCompact(): boolean;
+    /** Whether proactive microcompact should run. */
+    shouldProactiveCompact(): boolean;
+    private evaluate;
+    private computeState;
+}
+//# sourceMappingURL=context-budget.d.ts.map

package/dist/context/compaction/context-budget.js

@@ -0,0 +1,120 @@
+/**
+ * Agentic QE v3 - Context Budget Tracker (IMP-08)
+ *
+ * Tracks estimated token usage across a session and transitions through
+ * 5 operational states based on remaining budget. Emits events on state
+ * transitions so the CompactionPipeline can auto-trigger appropriate tiers.
+ *
+ * States (by remaining tokens):
+ *   Normal      > 25_000   -- No action needed
+ *   Warning     <= 25_000  -- Advisory only
+ *   Pressure    <= 18_000  -- Tier 1 (microcompact) runs proactively
+ *   AutoCompact <= 13_000  -- Tier 2/3 auto-triggered
+ *   Blocking    <= 3_000   -- Tier 4 reactive, blocks new tool calls
+ */
+import { EventEmitter } from 'events';
+// ============================================================================
+// Defaults
+// ============================================================================
+const DEFAULT_TOTAL_BUDGET = 100_000;
+const DEFAULT_WARNING_THRESHOLD = 25_000;
+const DEFAULT_PRESSURE_THRESHOLD = 18_000;
+const DEFAULT_AUTO_COMPACT_THRESHOLD = 13_000;
+const DEFAULT_BLOCKING_THRESHOLD = 3_000;
+// ============================================================================
+// ContextBudgetTracker
+// ============================================================================
+export class ContextBudgetTracker extends EventEmitter {
+    totalBudget;
+    warningThreshold;
+    pressureThreshold;
+    autoCompactThreshold;
+    blockingThreshold;
+    usedTokens = 0;
+    currentState = 'normal';
+    constructor(options = {}) {
+        super();
+        this.totalBudget = options.totalBudget ?? DEFAULT_TOTAL_BUDGET;
+        this.warningThreshold = options.warningThreshold ?? DEFAULT_WARNING_THRESHOLD;
+        this.pressureThreshold = options.pressureThreshold ?? DEFAULT_PRESSURE_THRESHOLD;
+        this.autoCompactThreshold = options.autoCompactThreshold ?? DEFAULT_AUTO_COMPACT_THRESHOLD;
+        this.blockingThreshold = options.blockingThreshold ?? DEFAULT_BLOCKING_THRESHOLD;
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /** Add tokens to the usage counter and re-evaluate state. */
+    addTokens(count) {
+        this.usedTokens += count;
+        this.evaluate();
+    }
+    /** Remove tokens (e.g., after compaction freed space). */
+    releaseTokens(count) {
+        this.usedTokens = Math.max(0, this.usedTokens - count);
+        this.evaluate();
+    }
+    /** Set the absolute token count (e.g., after a full recount). */
+    setUsedTokens(count) {
+        this.usedTokens = Math.max(0, count);
+        this.evaluate();
+    }
+    /** Current state. */
+    getState() {
+        return this.currentState;
+    }
+    /** Full snapshot of the budget. */
+    getSnapshot() {
+        const remaining = Math.max(0, this.totalBudget - this.usedTokens);
+        return {
+            state: this.currentState,
+            usedTokens: this.usedTokens,
+            remainingTokens: remaining,
+            totalBudget: this.totalBudget,
+            utilizationPercent: Math.round((this.usedTokens / this.totalBudget) * 100),
+        };
+    }
+    /** Whether the budget is in a state that should block new tool calls. */
+    isBlocking() {
+        return this.currentState === 'blocking';
+    }
+    /** Whether compaction should auto-trigger. */
+    shouldAutoCompact() {
+        return this.currentState === 'auto-compact' || this.currentState === 'blocking';
+    }
+    /** Whether proactive microcompact should run. */
+    shouldProactiveCompact() {
+        return this.currentState === 'pressure'
+            || this.currentState === 'auto-compact'
+            || this.currentState === 'blocking';
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    evaluate() {
+        const remaining = Math.max(0, this.totalBudget - this.usedTokens);
+        const newState = this.computeState(remaining);
+        if (newState !== this.currentState) {
+            const transition = {
+                from: this.currentState,
+                to: newState,
+                remainingTokens: remaining,
+                totalBudget: this.totalBudget,
+                timestamp: Date.now(),
+            };
+            this.currentState = newState;
+            this.emit('transition', transition);
+        }
+    }
+    computeState(remaining) {
+        if (remaining <= this.blockingThreshold)
+            return 'blocking';
+        if (remaining <= this.autoCompactThreshold)
+            return 'auto-compact';
+        if (remaining <= this.pressureThreshold)
+            return 'pressure';
+        if (remaining <= this.warningThreshold)
+            return 'warning';
+        return 'normal';
+    }
+}
+//# sourceMappingURL=context-budget.js.map

package/dist/context/compaction/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Agentic QE v3 - Compaction Pipeline Orchestrator (IMP-08)
+ *
+ * Orchestrates the 4-tier context compaction stack:
+ *   Tier 1: Microcompact (IMP-01) — age/pressure eviction, zero API
+ *   Tier 2: QE Session Summary — structured local summary, zero API
+ *   Tier 3: LLM Compact — 9-section summary, one API call
+ *   Tier 4: Reactive — aggressive message peeling on 413/overflow
+ *
+ * The pipeline auto-triggers based on ContextBudgetTracker state transitions
+ * and can also be invoked manually. Registers as middleware on the IMP-00
+ * middleware chain (priority 200, after microcompact at 100).
+ */
+import type { ToolMiddleware } from '../../mcp/middleware/middleware-chain';
+import { ContextBudgetTracker, type BudgetSnapshot } from './context-budget';
+import { type Tier1Result } from './tier1-microcompact';
+import { type ConversationMessage, type Tier2Result } from './tier2-session-summary';
+import { type Tier3Result, type LLMCompactCaller } from './tier3-llm-compact';
+import { type Tier4Result } from './tier4-reactive';
+import { MicrocompactEngine } from '../../mcp/middleware/microcompact';
+export { ContextBudgetTracker, type BudgetTransition, type BudgetSnapshot, type BudgetState } from './context-budget';
+export type { ContextBudgetOptions } from './context-budget';
+export { Tier1Microcompact, type Tier1Result } from './tier1-microcompact';
+export { Tier2SessionSummary, type ConversationMessage, type Tier2Result, type SessionSummaryOptions } from './tier2-session-summary';
+export { Tier3LLMCompact, type Tier3Result, type LLMCompactCaller, type Tier3Options } from './tier3-llm-compact';
+export { Tier4Reactive, type Tier4Result, type Tier4Options } from './tier4-reactive';
+export interface CompactionPipelineOptions {
+    /** Total context budget in tokens (default: 100_000) */
+    totalBudget?: number;
+    /** LLM caller for Tier 3 (optional — falls back to extractive) */
+    llmCaller?: LLMCompactCaller;
+    /** Max files to restore after compaction (default: 5) */
+    maxFileRestorations?: number;
+    /** Token budget for file restorations (default: 50_000) */
+    fileRestorationBudget?: number;
+    /** Shared MicrocompactEngine from IMP-01 middleware (Tier 1 reuses it) */
+    sharedMicrocompactEngine?: MicrocompactEngine;
+}
+export type CompactionTierResult = Tier1Result | Tier2Result | Tier3Result | Tier4Result;
+export interface CompactionRunResult {
+    tiersExecuted: number[];
+    totalTokensSaved: number;
+    tierResults: CompactionTierResult[];
+    budgetAfter: BudgetSnapshot;
+}
+export declare class CompactionPipeline {
+    private readonly budget;
+    private readonly tier1;
+    private readonly tier2;
+    private readonly tier3;
+    private readonly tier4;
+    private readonly maxFileRestorations;
+    private readonly fileRestorationBudget;
+    /** Conversation history tracked for Tier 2-4 compaction */
+    private conversationHistory;
+    /** Recently accessed file paths for post-compact restoration */
+    private recentFiles;
+    /** Whether a compaction is currently in progress (prevents re-entrancy) */
+    private compacting;
+    constructor(options?: CompactionPipelineOptions);
+    /** Record a conversation message for tracking. */
+    addMessage(message: ConversationMessage): void;
+    /** Record a recently accessed file path. */
+    recordFileAccess(filePath: string): void;
+    /** Get the list of files that should be restored after compaction. */
+    getFilesForRestoration(): string[];
+    /** Get the current budget snapshot. */
+    getBudgetSnapshot(): BudgetSnapshot;
+    /** Get the budget tracker for direct access. */
+    getBudgetTracker(): ContextBudgetTracker;
+    /**
+     * Manually run compaction up to the specified tier.
+     * Returns results from all tiers that executed.
+     */
+    runCompaction(maxTier?: 1 | 2 | 3 | 4): Promise<CompactionRunResult>;
+    /**
+     * Handle a 413 error or context overflow.
+     * Triggers Tier 4 reactive compaction immediately.
+     */
+    handleOverflow(trigger?: 'status_413' | 'context_overflow'): Promise<Tier4Result>;
+    /** Get compaction statistics for the session_cache_stats tool. */
+    getStats(): {
+        conversationMessages: number;
+        budget: BudgetSnapshot;
+        recentFiles: string[];
+        isCompacting: boolean;
+    };
+    /**
+     * Create a ToolMiddleware that plugs this pipeline into the IMP-00 chain.
+     * Priority 200 — runs after microcompact (100) in post-hooks.
+     * Disabled via AQE_COMPACTION_DISABLED=true.
+     */
+    createMiddleware(): ToolMiddleware;
+    private handleBudgetTransition;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/context/compaction/index.js

@@ -0,0 +1,259 @@
+/**
+ * Agentic QE v3 - Compaction Pipeline Orchestrator (IMP-08)
+ *
+ * Orchestrates the 4-tier context compaction stack:
+ *   Tier 1: Microcompact (IMP-01) — age/pressure eviction, zero API
+ *   Tier 2: QE Session Summary — structured local summary, zero API
+ *   Tier 3: LLM Compact — 9-section summary, one API call
+ *   Tier 4: Reactive — aggressive message peeling on 413/overflow
+ *
+ * The pipeline auto-triggers based on ContextBudgetTracker state transitions
+ * and can also be invoked manually. Registers as middleware on the IMP-00
+ * middleware chain (priority 200, after microcompact at 100).
+ */
+import { ContextBudgetTracker } from './context-budget';
+import { Tier1Microcompact } from './tier1-microcompact';
+import { Tier2SessionSummary } from './tier2-session-summary';
+import { Tier3LLMCompact } from './tier3-llm-compact';
+import { Tier4Reactive } from './tier4-reactive';
+import { estimateTokensPadded } from '../../mcp/middleware/microcompact';
+// ============================================================================
+// Re-exports
+// ============================================================================
+export { ContextBudgetTracker } from './context-budget';
+export { Tier1Microcompact } from './tier1-microcompact';
+export { Tier2SessionSummary } from './tier2-session-summary';
+export { Tier3LLMCompact } from './tier3-llm-compact';
+export { Tier4Reactive } from './tier4-reactive';
+// ============================================================================
+// CompactionPipeline
+// ============================================================================
+export class CompactionPipeline {
+    budget;
+    tier1;
+    tier2;
+    tier3;
+    tier4;
+    maxFileRestorations;
+    fileRestorationBudget;
+    /** Conversation history tracked for Tier 2-4 compaction */
+    conversationHistory = [];
+    /** Recently accessed file paths for post-compact restoration */
+    recentFiles = [];
+    /** Whether a compaction is currently in progress (prevents re-entrancy) */
+    compacting = false;
+    constructor(options = {}) {
+        this.budget = new ContextBudgetTracker({
+            totalBudget: options.totalBudget,
+        });
+        this.tier1 = options.sharedMicrocompactEngine
+            ? Tier1Microcompact.fromEngine(options.sharedMicrocompactEngine)
+            : new Tier1Microcompact();
+        this.tier2 = new Tier2SessionSummary();
+        this.tier3 = new Tier3LLMCompact({ llmCall: options.llmCaller });
+        this.tier4 = new Tier4Reactive();
+        this.maxFileRestorations = options.maxFileRestorations ?? 5;
+        this.fileRestorationBudget = options.fileRestorationBudget ?? 50_000;
+        // Auto-trigger compaction on budget state transitions
+        this.budget.on('transition', (transition) => {
+            this.handleBudgetTransition(transition);
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /** Record a conversation message for tracking. */
+    addMessage(message) {
+        this.conversationHistory.push(message);
+        const tokens = message.estimatedTokens ?? estimateTokensPadded(message.content);
+        this.budget.addTokens(tokens);
+    }
+    /** Record a recently accessed file path. */
+    recordFileAccess(filePath) {
+        // Deduplicate, keep most recent at the end
+        this.recentFiles = this.recentFiles.filter(f => f !== filePath);
+        this.recentFiles.push(filePath);
+        // Trim to max
+        if (this.recentFiles.length > this.maxFileRestorations * 2) {
+            this.recentFiles = this.recentFiles.slice(-this.maxFileRestorations * 2);
+        }
+    }
+    /** Get the list of files that should be restored after compaction. */
+    getFilesForRestoration() {
+        return this.recentFiles.slice(-this.maxFileRestorations);
+    }
+    /** Get the current budget snapshot. */
+    getBudgetSnapshot() {
+        return this.budget.getSnapshot();
+    }
+    /** Get the budget tracker for direct access. */
+    getBudgetTracker() {
+        return this.budget;
+    }
+    /**
+     * Manually run compaction up to the specified tier.
+     * Returns results from all tiers that executed.
+     */
+    async runCompaction(maxTier = 4) {
+        if (this.compacting) {
+            return {
+                tiersExecuted: [],
+                totalTokensSaved: 0,
+                tierResults: [],
+                budgetAfter: this.budget.getSnapshot(),
+            };
+        }
+        this.compacting = true;
+        const tierResults = [];
+        let totalTokensSaved = 0;
+        const tiersExecuted = [];
+        try {
+            // Tier 1: Always run microcompact
+            const t1 = this.tier1.compact();
+            tierResults.push(t1);
+            tiersExecuted.push(1);
+            totalTokensSaved += t1.tokensSaved;
+            if (maxTier >= 2 && this.conversationHistory.length > 0) {
+                // Tier 2: Session summary
+                const t2 = this.tier2.compact(this.conversationHistory);
+                tierResults.push(t2);
+                tiersExecuted.push(2);
+                totalTokensSaved += t2.tokensSaved;
+                // Replace conversation history with preserved messages
+                if (t2.removedMessageCount > 0) {
+                    this.conversationHistory = [...t2.preservedMessages];
+                    this.budget.releaseTokens(t2.tokensSaved);
+                }
+            }
+            if (maxTier >= 3 && this.budget.shouldAutoCompact()) {
+                // Tier 3: LLM compact
+                const t3 = await this.tier3.compact(this.conversationHistory);
+                tierResults.push(t3);
+                tiersExecuted.push(3);
+                totalTokensSaved += t3.tokensSaved;
+                if (t3.tokensSaved > 0) {
+                    // Replace history with summary-as-message
+                    this.conversationHistory = [{
+                            role: 'assistant',
+                            content: t3.summary,
+                            timestamp: Date.now(),
+                            estimatedTokens: t3.summaryTokens,
+                        }];
+                    this.budget.releaseTokens(t3.tokensSaved);
+                }
+            }
+            if (maxTier >= 4 && this.budget.isBlocking()) {
+                // Tier 4: Reactive — last resort
+                const t4 = this.tier4.compact(this.conversationHistory, 'context_overflow');
+                tierResults.push(t4);
+                tiersExecuted.push(4);
+                totalTokensSaved += t4.tokensSaved;
+                if (t4.droppedCount > 0) {
+                    this.conversationHistory = [...t4.survivingMessages];
+                    this.budget.releaseTokens(t4.tokensSaved);
+                }
+            }
+        }
+        finally {
+            this.compacting = false;
+        }
+        return {
+            tiersExecuted,
+            totalTokensSaved,
+            tierResults,
+            budgetAfter: this.budget.getSnapshot(),
+        };
+    }
+    /**
+     * Handle a 413 error or context overflow.
+     * Triggers Tier 4 reactive compaction immediately.
+     */
+    async handleOverflow(trigger = 'status_413') {
+        const result = this.tier4.compact(this.conversationHistory, trigger);
+        if (result.droppedCount > 0) {
+            this.conversationHistory = [...result.survivingMessages];
+            this.budget.releaseTokens(result.tokensSaved);
+        }
+        return result;
+    }
+    /** Get compaction statistics for the session_cache_stats tool. */
+    getStats() {
+        return {
+            conversationMessages: this.conversationHistory.length,
+            budget: this.budget.getSnapshot(),
+            recentFiles: this.getFilesForRestoration(),
+            isCompacting: this.compacting,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Middleware Factory
+    // --------------------------------------------------------------------------
+    /**
+     * Create a ToolMiddleware that plugs this pipeline into the IMP-00 chain.
+     * Priority 200 — runs after microcompact (100) in post-hooks.
+     * Disabled via AQE_COMPACTION_DISABLED=true.
+     */
+    createMiddleware() {
+        const compactionDisabled = process.env.AQE_COMPACTION_DISABLED === 'true';
+        return {
+            name: 'compaction-pipeline',
+            priority: 200,
+            postToolResult: async (context, result) => {
+                if (compactionDisabled)
+                    return result;
+                // Estimate tokens from FULL content for accurate budget tracking,
+                // but store truncated content for conversation history (summarization).
+                const fullParamsStr = JSON.stringify(context.params);
+                const fullResultStr = typeof result === 'string' ? result : JSON.stringify(result);
+                const toolUseId = `${context.toolName}-${context.timestamp}`;
+                // Track the tool call
+                this.addMessage({
+                    role: 'tool_use',
+                    content: fullParamsStr.slice(0, 500),
+                    toolName: context.toolName,
+                    timestamp: context.timestamp,
+                    toolUseId,
+                    // Use full content for token estimation
+                    estimatedTokens: estimateTokensPadded(fullParamsStr),
+                });
+                // Track the result
+                this.addMessage({
+                    role: 'tool_result',
+                    content: fullResultStr.slice(0, 1000),
+                    toolName: context.toolName,
+                    timestamp: Date.now(),
+                    toolUseId,
+                    estimatedTokens: estimateTokensPadded(fullResultStr),
+                });
+                // Track file accesses from tool params
+                const params = context.params;
+                if (typeof params.file_path === 'string') {
+                    this.recordFileAccess(params.file_path);
+                }
+                if (typeof params.path === 'string') {
+                    this.recordFileAccess(params.path);
+                }
+                return result;
+            },
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    handleBudgetTransition(transition) {
+        // Auto-trigger compaction based on state
+        if (transition.to === 'pressure') {
+            // Tier 1 only — proactive microcompact
+            void this.runCompaction(1);
+        }
+        else if (transition.to === 'auto-compact') {
+            // Tiers 1-3
+            void this.runCompaction(3);
+        }
+        else if (transition.to === 'blocking') {
+            // All tiers including reactive
+            void this.runCompaction(4);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/context/compaction/llm-caller-adapter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Agentic QE v3 - LLM Caller Adapter for Tier 3 Compaction (IMP-08)
+ *
+ * Lightweight adapter that creates an LLMCompactCaller from an Anthropic
+ * API key. Uses Haiku-class model for cost efficiency. Falls back
+ * gracefully when no API key is available.
+ */
+import type { LLMCompactCaller } from './tier3-llm-compact';
+/**
+ * Create an LLMCompactCaller if an Anthropic API key is available.
+ * Returns undefined if no key is found (Tier 3 will use extractive fallback).
+ */
+export declare function createLLMCompactCaller(): LLMCompactCaller | undefined;
+//# sourceMappingURL=llm-caller-adapter.d.ts.map