@claudetools/tools 0.8.2 → 0.8.4

package/dist/cli.js

@@ -11,6 +11,7 @@ import { runSetup, runUninstall, runInit, runCleanup } from './setup.js';
 import { startServer } from './index.js';
 import { startWatcher, stopWatcher, watcherStatus } from './watcher.js';
 import { generateCodebaseMap, generateCodebaseMapLocal } from './helpers/codebase-mapper.js';
+import { contextStatus, contextEvict, contextSummarise, contextReset, } from './context-cli.js';
 // Get version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -56,6 +57,10 @@ Commands:
   watch --status   Check watcher status
   map              Generate codebase map for current project
   map --local      Generate map locally without uploading
+  context status   Show current session context usage
+  context evict    Manually trigger eviction cycle
+  context summarise Summarise and compress exchanges
+  context reset    Clear session state
 
 Running without options starts the MCP server.
 
@@ -165,6 +170,42 @@ else if (positionals[0] === 'map') {
         process.exit(1);
     });
 }
+else if (positionals[0] === 'context') {
+    // Handle context command
+    const subcommand = positionals[1];
+    const contextArgs = process.argv.slice(4); // Get args after subcommand
+    switch (subcommand) {
+        case 'status':
+            contextStatus(contextArgs).catch((error) => {
+                console.error('Context status failed:', error);
+                process.exit(1);
+            });
+            break;
+        case 'evict':
+            contextEvict(contextArgs).catch((error) => {
+                console.error('Context evict failed:', error);
+                process.exit(1);
+            });
+            break;
+        case 'summarise':
+        case 'summarize': // Support both spellings
+            contextSummarise(contextArgs).catch((error) => {
+                console.error('Context summarise failed:', error);
+                process.exit(1);
+            });
+            break;
+        case 'reset':
+            contextReset(contextArgs).catch((error) => {
+                console.error('Context reset failed:', error);
+                process.exit(1);
+            });
+            break;
+        default:
+            console.error(`Unknown context subcommand: ${subcommand}`);
+            console.error('Available subcommands: status, evict, summarise, reset');
+            process.exit(1);
+    }
+}
 else {
     // Start MCP server
     startServer();

package/dist/context/deduplication.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Deduplication Tracker for Context Injection
+ *
+ * Tracks which facts have been injected into context and when,
+ * preventing redundant re-injection unless facts are stale.
+ *
+ * @module context/deduplication
+ */
+export interface DeduplicationTracker {
+    /**
+     * Record that a fact was injected at a specific turn
+     */
+    recordInjection(factId: string, turn: number): void;
+    /**
+     * Determine if a fact should be injected
+     * @param factId - The fact ID to check
+     * @param currentTurn - Current conversation turn number
+     * @param freshnessThreshold - Number of turns before fact is considered stale (default: 10)
+     * @returns true if fact should be injected, false if it's already fresh in context
+     */
+    shouldInject(factId: string, currentTurn: number, freshnessThreshold?: number): boolean;
+    /**
+     * Get all currently tracked facts and their injection turns
+     */
+    getInjectedFacts(): Map<string, number>;
+    /**
+     * Clear all tracked facts
+     */
+    clear(): void;
+    /**
+     * Get statistics about tracked facts
+     */
+    getStats(currentTurn: number): {
+        totalTracked: number;
+        fresh: number;
+        stale: number;
+        averageAge: number;
+    };
+    /**
+     * Remove facts older than a certain age to prevent unbounded growth
+     */
+    pruneOldFacts(currentTurn: number, maxAge?: number): number;
+}
+/**
+ * In-memory deduplication tracker implementation
+ */
+export declare class InMemoryDeduplicationTracker implements DeduplicationTracker {
+    private injectedFacts;
+    private defaultFreshnessThreshold;
+    constructor(defaultFreshnessThreshold?: number);
+    recordInjection(factId: string, turn: number): void;
+    shouldInject(factId: string, currentTurn: number, freshnessThreshold?: number): boolean;
+    getInjectedFacts(): Map<string, number>;
+    clear(): void;
+    /**
+     * Get statistics about tracked facts
+     */
+    getStats(currentTurn: number): {
+        totalTracked: number;
+        fresh: number;
+        stale: number;
+        averageAge: number;
+    };
+    /**
+     * Remove facts older than a certain age to prevent unbounded growth
+     */
+    pruneOldFacts(currentTurn: number, maxAge?: number): number;
+}
+/**
+ * Create a new deduplication tracker
+ */
+export declare function createDeduplicationTracker(freshnessThreshold?: number): DeduplicationTracker;

package/dist/context/deduplication.js

@@ -0,0 +1,77 @@
+/**
+ * Deduplication Tracker for Context Injection
+ *
+ * Tracks which facts have been injected into context and when,
+ * preventing redundant re-injection unless facts are stale.
+ *
+ * @module context/deduplication
+ */
+/**
+ * In-memory deduplication tracker implementation
+ */
+export class InMemoryDeduplicationTracker {
+    injectedFacts;
+    defaultFreshnessThreshold;
+    constructor(defaultFreshnessThreshold = 10) {
+        this.injectedFacts = new Map();
+        this.defaultFreshnessThreshold = defaultFreshnessThreshold;
+    }
+    recordInjection(factId, turn) {
+        this.injectedFacts.set(factId, turn);
+    }
+    shouldInject(factId, currentTurn, freshnessThreshold = this.defaultFreshnessThreshold) {
+        const lastInjectedTurn = this.injectedFacts.get(factId);
+        // Never injected before - should inject
+        if (lastInjectedTurn === undefined) {
+            return true;
+        }
+        // Calculate how many turns ago it was injected
+        const turnsSinceInjection = currentTurn - lastInjectedTurn;
+        // Should inject if it's been more than threshold turns
+        return turnsSinceInjection > freshnessThreshold;
+    }
+    getInjectedFacts() {
+        return new Map(this.injectedFacts);
+    }
+    clear() {
+        this.injectedFacts.clear();
+    }
+    /**
+     * Get statistics about tracked facts
+     */
+    getStats(currentTurn) {
+        const facts = Array.from(this.injectedFacts.values());
+        const fresh = facts.filter(turn => currentTurn - turn <= this.defaultFreshnessThreshold);
+        const stale = facts.filter(turn => currentTurn - turn > this.defaultFreshnessThreshold);
+        const totalAge = facts.reduce((sum, turn) => sum + (currentTurn - turn), 0);
+        return {
+            totalTracked: facts.length,
+            fresh: fresh.length,
+            stale: stale.length,
+            averageAge: facts.length > 0 ? totalAge / facts.length : 0,
+        };
+    }
+    /**
+     * Remove facts older than a certain age to prevent unbounded growth
+     */
+    pruneOldFacts(currentTurn, maxAge = 100) {
+        let pruned = 0;
+        const toDelete = [];
+        this.injectedFacts.forEach((turn, factId) => {
+            if (currentTurn - turn > maxAge) {
+                toDelete.push(factId);
+            }
+        });
+        toDelete.forEach(factId => {
+            this.injectedFacts.delete(factId);
+            pruned++;
+        });
+        return pruned;
+    }
+}
+/**
+ * Create a new deduplication tracker
+ */
+export function createDeduplicationTracker(freshnessThreshold = 10) {
+    return new InMemoryDeduplicationTracker(freshnessThreshold);
+}

package/dist/context/deduplication.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tests for DeduplicationTracker
+ *
+ * These tests demonstrate the usage and verify the logic.
+ */
+export declare function runTests(): void;

package/dist/context/deduplication.test.js

@@ -0,0 +1,84 @@
+/**
+ * Tests for DeduplicationTracker
+ *
+ * These tests demonstrate the usage and verify the logic.
+ */
+import { createDeduplicationTracker } from './deduplication.js';
+// Example usage demonstration
+function demonstrateUsage() {
+    const tracker = createDeduplicationTracker(10); // 10-turn freshness threshold
+    console.log('\n=== Deduplication Tracker Demo ===\n');
+    // Scenario 1: First injection
+    console.log('Turn 1: Check if fact_123 should be injected');
+    console.log('Result:', tracker.shouldInject('fact_123', 1)); // true - never injected
+    tracker.recordInjection('fact_123', 1);
+    // Scenario 2: Recent injection (within threshold)
+    console.log('\nTurn 5: Check if fact_123 should be injected again');
+    console.log('Result:', tracker.shouldInject('fact_123', 5)); // false - only 4 turns ago
+    console.log('Turns since injection:', 5 - 1);
+    // Scenario 3: Stale injection (beyond threshold)
+    console.log('\nTurn 15: Check if fact_123 should be injected again');
+    console.log('Result:', tracker.shouldInject('fact_123', 15)); // true - 14 turns ago (> 10)
+    console.log('Turns since injection:', 15 - 1);
+    // Scenario 4: Multiple facts
+    tracker.recordInjection('fact_456', 10);
+    tracker.recordInjection('fact_789', 12);
+    console.log('\nTurn 20: Check multiple facts');
+    console.log('fact_123 (injected turn 1):', tracker.shouldInject('fact_123', 20)); // true - 19 turns
+    console.log('fact_456 (injected turn 10):', tracker.shouldInject('fact_456', 20)); // true - 10 turns
+    console.log('fact_789 (injected turn 12):', tracker.shouldInject('fact_789', 20)); // false - 8 turns
+    // Scenario 5: Statistics
+    console.log('\nStatistics at turn 20:');
+    console.log(JSON.stringify(tracker.getStats(20), null, 2));
+    // Scenario 6: Pruning old facts
+    console.log('\nPruning facts older than 50 turns at turn 100:');
+    tracker.recordInjection('old_fact', 30);
+    const pruned = tracker.pruneOldFacts(100, 50);
+    console.log('Pruned:', pruned, 'facts');
+    console.log('Remaining facts:', tracker.getInjectedFacts().size);
+}
+// Run tests if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    demonstrateUsage();
+}
+// Simple assertion-based tests
+export function runTests() {
+    const tracker = createDeduplicationTracker(10);
+    // Test 1: Never injected should return true
+    if (!tracker.shouldInject('test_fact', 1)) {
+        throw new Error('Test 1 failed: Never injected fact should inject');
+    }
+    // Test 2: Recent injection should return false
+    tracker.recordInjection('test_fact', 1);
+    if (tracker.shouldInject('test_fact', 5)) {
+        throw new Error('Test 2 failed: Recent fact should not inject');
+    }
+    // Test 3: Stale injection should return true
+    if (!tracker.shouldInject('test_fact', 15)) {
+        throw new Error('Test 3 failed: Stale fact should inject');
+    }
+    // Test 4: Custom threshold
+    if (!tracker.shouldInject('test_fact', 6, 5)) {
+        throw new Error('Test 4 failed: Custom threshold should allow injection');
+    }
+    // Test 5: Clear should reset state
+    tracker.clear();
+    if (tracker.getInjectedFacts().size !== 0) {
+        throw new Error('Test 5 failed: Clear should remove all facts');
+    }
+    // Test 6: Statistics
+    tracker.recordInjection('fact1', 1);
+    tracker.recordInjection('fact2', 8);
+    tracker.recordInjection('fact3', 15);
+    const stats = tracker.getStats(20);
+    if (stats.totalTracked !== 3) {
+        throw new Error('Test 6 failed: Should track 3 facts');
+    }
+    if (stats.fresh !== 1) {
+        throw new Error('Test 6 failed: Should have 1 fresh fact');
+    }
+    if (stats.stale !== 2) {
+        throw new Error('Test 6 failed: Should have 2 stale facts');
+    }
+    console.log('✅ All tests passed!');
+}

package/dist/context/emergency-eviction.d.ts

@@ -0,0 +1,73 @@
+import type { PersistedSessionState } from './session-store.js';
+/**
+ * Result of emergency eviction operation
+ */
+export interface EmergencyResult {
+    wasEmergency: boolean;
+    actionsToken: string[];
+    evictedCount: number;
+    summarisedExchanges: number;
+    compressedCritical: number;
+    newEstimatedFill: number;
+    userWarning: string;
+}
+/**
+ * Emergency eviction configuration
+ */
+export interface EmergencyConfig {
+    emergencyThreshold: number;
+    targetFill: number;
+    criticalCompressionThreshold: number;
+}
+export declare class EmergencyEviction {
+    private config;
+    private scorer;
+    constructor(config?: Partial<EmergencyConfig>);
+    /**
+     * Check if session is in emergency state
+     */
+    isEmergency(session: PersistedSessionState): boolean;
+    /**
+     * Run emergency eviction protocol
+     *
+     * Steps:
+     * 1. Summarise recent exchanges
+     * 2. Evict normal importance facts
+     * 3. If still critical, compress high importance facts
+     * 4. If still critical, compress critical facts (last resort)
+     *
+     * @param session - Current session state
+     * @returns Emergency result with actions taken
+     */
+    runEmergencyEviction(session: PersistedSessionState): Promise<EmergencyResult>;
+    /**
+     * Get facts by importance level
+     */
+    private getFactsByImportance;
+    /**
+     * Get count of unsummarised exchanges
+     */
+    private getUnsummarisedExchangeCount;
+    /**
+     * Estimate tokens for a set of exchanges
+     */
+    private estimateExchangeTokens;
+    /**
+     * Estimate tokens for a set of facts
+     * More realistic estimate: ~500 tokens per fact average
+     * (includes context, entities, relationships, metadata)
+     */
+    private estimateFactTokens;
+    /**
+     * Recalculate fill percentage after token change
+     */
+    private recalculateFill;
+    /**
+     * Generate user-facing warning message
+     */
+    private generateUserWarning;
+}
+/**
+ * Create emergency eviction instance with optional config
+ */
+export declare function createEmergencyEviction(config?: Partial<EmergencyConfig>): EmergencyEviction;

package/dist/context/emergency-eviction.example.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Example: Monitor session context and trigger emergency eviction
+ */
+declare function monitorSessionContext(sessionId: string): Promise<void>;
+/**
+ * Example: Custom emergency configuration for aggressive cleanup
+ */
+declare function aggressiveEmergencyCleanup(sessionId: string): Promise<void>;
+/**
+ * Example: Integration with post-tool-use hook
+ */
+declare function postToolUseEmergencyCheck(sessionId: string): Promise<void>;
+export { monitorSessionContext, aggressiveEmergencyCleanup, postToolUseEmergencyCheck };

package/dist/context/emergency-eviction.example.js

@@ -0,0 +1,94 @@
+// =============================================================================
+// Emergency Eviction - Usage Example
+// =============================================================================
+import { createEmergencyEviction, getSessionStore, } from './index.js';
+/**
+ * Example: Monitor session context and trigger emergency eviction
+ */
+async function monitorSessionContext(sessionId) {
+    const sessionStore = getSessionStore();
+    const eviction = createEmergencyEviction({
+        emergencyThreshold: 0.70, // Trigger at 70% fill
+        targetFill: 0.50, // Aim for 50% after eviction
+        criticalCompressionThreshold: 0.65, // Compress critical if still > 65%
+    });
+    // Get current session state
+    const session = await sessionStore.getSession(sessionId);
+    if (!session) {
+        console.log('Session not found');
+        return;
+    }
+    console.log(`Session fill: ${(session.estimated_fill * 100).toFixed(1)}%`);
+    // Check if emergency eviction is needed
+    if (eviction.isEmergency(session)) {
+        console.log('🚨 EMERGENCY: Context at critical level, running eviction...');
+        const result = await eviction.runEmergencyEviction(session);
+        console.log('\nEmergency Eviction Results:');
+        console.log('─────────────────────────────────────');
+        console.log(`Actions taken: ${result.actionsToken.length}`);
+        result.actionsToken.forEach((action) => console.log(`  • ${action}`));
+        console.log(`\nEvicted facts: ${result.evictedCount}`);
+        console.log(`Summarised exchanges: ${result.summarisedExchanges}`);
+        console.log(`Compressed critical facts: ${result.compressedCritical}`);
+        console.log(`\nFill: ${(session.estimated_fill * 100).toFixed(1)}% → ${(result.newEstimatedFill * 100).toFixed(1)}%`);
+        console.log(`\n⚠️  ${result.userWarning}`);
+        // Update session with new fill estimate
+        await sessionStore.updateSession(sessionId, {
+            estimated_fill: result.newEstimatedFill,
+        });
+    }
+    else {
+        console.log('✓ Context within safe limits');
+    }
+}
+/**
+ * Example: Custom emergency configuration for aggressive cleanup
+ */
+async function aggressiveEmergencyCleanup(sessionId) {
+    const sessionStore = getSessionStore();
+    const eviction = createEmergencyEviction({
+        emergencyThreshold: 0.60, // Trigger earlier at 60%
+        targetFill: 0.30, // Aim for very low fill (30%)
+        criticalCompressionThreshold: 0.50, // More aggressive critical compression
+    });
+    const session = await sessionStore.getSession(sessionId);
+    if (!session)
+        return;
+    if (eviction.isEmergency(session)) {
+        const result = await eviction.runEmergencyEviction(session);
+        console.log('🔥 Aggressive cleanup completed:');
+        console.log(`  Evicted: ${result.evictedCount} facts`);
+        console.log(`  Compressed: ${result.compressedCritical} critical facts`);
+        console.log(`  New fill: ${(result.newEstimatedFill * 100).toFixed(1)}%`);
+        await sessionStore.updateSession(sessionId, {
+            estimated_fill: result.newEstimatedFill,
+        });
+    }
+}
+/**
+ * Example: Integration with post-tool-use hook
+ */
+async function postToolUseEmergencyCheck(sessionId) {
+    const sessionStore = getSessionStore();
+    const eviction = createEmergencyEviction();
+    const session = await sessionStore.getSession(sessionId);
+    if (!session)
+        return;
+    // Check after every tool use
+    if (eviction.isEmergency(session)) {
+        console.log('Emergency eviction triggered by tool use');
+        const result = await eviction.runEmergencyEviction(session);
+        // Log to user
+        if (result.compressedCritical > 0) {
+            console.error('⚠️  CRITICAL: Context pressure forced compression of important facts');
+        }
+        else if (result.evictedCount > 0) {
+            console.warn(`Context cleanup: Evicted ${result.evictedCount} facts`);
+        }
+        await sessionStore.updateSession(sessionId, {
+            estimated_fill: result.newEstimatedFill,
+        });
+    }
+}
+// Export examples
+export { monitorSessionContext, aggressiveEmergencyCleanup, postToolUseEmergencyCheck };