@claudetools/tools 0.8.2 → 0.8.4

package/dist/context/health-monitor.example.js

@@ -0,0 +1,164 @@
+// =============================================================================
+// Health Monitor Usage Example
+// =============================================================================
+// Demonstrates how to use the health monitor to track and calibrate
+// context estimation accuracy.
+// =============================================================================
+import { getHealthMonitor } from './index.js';
+// =============================================================================
+// Example 1: Basic Health Check
+// =============================================================================
+function exampleBasicHealthCheck() {
+    console.log('\n=== Example 1: Basic Health Check ===\n');
+    const monitor = getHealthMonitor();
+    const session = {
+        session_id: 'example-session-1',
+        started_at: new Date(),
+        injected_facts: [],
+    };
+    const health = monitor.checkHealth(session);
+    console.log('Health Status:');
+    console.log(`  Estimated Fill: ${(health.estimatedFill * 100).toFixed(1)}%`);
+    console.log(`  Calibration Factor: ${health.calibrationFactor.toFixed(3)}`);
+    console.log(`  Drift Warning: ${health.driftWarning}`);
+    console.log(`  Recommendation: ${health.recommendation}`);
+    console.log('\nMetrics:');
+    console.log(`  Sessions Monitored: ${health.metrics.sessionsMonitored}`);
+    console.log(`  Average Drift: ${(health.metrics.avgDrift * 100).toFixed(1)}%`);
+    console.log(`  Last Calibration: ${health.metrics.lastCalibration || 'Never'}`);
+}
+// =============================================================================
+// Example 2: Calibration with Actual Usage
+// =============================================================================
+function exampleCalibration() {
+    console.log('\n=== Example 2: Calibration with Actual Usage ===\n');
+    const monitor = getHealthMonitor();
+    const session = {
+        session_id: 'example-session-2',
+        started_at: new Date(),
+        injected_facts: [],
+    };
+    // Simulate receiving actual usage data from /context command
+    console.log('Calibrating with actual usage data...\n');
+    // Session 1: Actual usage 60%, estimated 50%
+    monitor.calibrate(session, 0.6);
+    console.log('Session 1: Actual 60%, Estimated 50%');
+    // Session 2: Actual usage 65%, estimated 50%
+    monitor.calibrate(session, 0.65);
+    console.log('Session 2: Actual 65%, Estimated 50%');
+    // Session 3: Actual usage 70%, estimated 50%
+    monitor.calibrate(session, 0.7);
+    console.log('Session 3: Actual 70%, Estimated 50%');
+    // Check health after calibration
+    const health = monitor.checkHealth(session);
+    console.log('\nHealth after calibration:');
+    console.log(`  Calibration Factor: ${health.calibrationFactor.toFixed(3)}`);
+    console.log(`  Drift Warning: ${health.driftWarning}`);
+    console.log(`  Average Drift: ${(health.metrics.avgDrift * 100).toFixed(1)}%`);
+    console.log(`  Recommendation: ${health.recommendation}`);
+}
+// =============================================================================
+// Example 3: Drift History Analysis
+// =============================================================================
+function exampleDriftHistory() {
+    console.log('\n=== Example 3: Drift History Analysis ===\n');
+    const monitor = getHealthMonitor();
+    const session = {
+        session_id: 'example-session-3',
+        started_at: new Date(),
+        injected_facts: [],
+    };
+    // Add some calibration samples
+    const samples = [0.55, 0.58, 0.62, 0.65, 0.70];
+    samples.forEach((actual, index) => {
+        monitor.calibrate(session, actual);
+        console.log(`Sample ${index + 1}: Actual ${(actual * 100).toFixed(0)}%`);
+    });
+    // Get drift history
+    console.log('\nDrift History (newest first):');
+    const history = monitor.getDriftHistory();
+    history.slice(0, 5).forEach((record, index) => {
+        console.log(`  ${index + 1}. ${record.timestamp.toISOString()}: ` +
+            `Est: ${(record.estimated * 100).toFixed(1)}%, ` +
+            `Actual: ${(record.actual * 100).toFixed(1)}%, ` +
+            `Drift: ${record.drift > 0 ? '+' : ''}${(record.drift * 100).toFixed(1)}%`);
+    });
+}
+// =============================================================================
+// Example 4: Integration with Context Management
+// =============================================================================
+function exampleIntegration() {
+    console.log('\n=== Example 4: Integration Pattern ===\n');
+    const monitor = getHealthMonitor();
+    // Simulated context management flow
+    const session = {
+        session_id: 'example-session-4',
+        started_at: new Date(),
+        injected_facts: [],
+    };
+    console.log('Context Management Flow:\n');
+    // 1. Check health before injection
+    console.log('1. Check health status');
+    const healthBefore = monitor.checkHealth(session);
+    console.log(`   Current calibration factor: ${healthBefore.calibrationFactor.toFixed(3)}`);
+    // 2. Use calibrated estimates for injection decisions
+    console.log('\n2. Use calibrated estimates');
+    const baseEstimate = 0.5;
+    const calibratedEstimate = baseEstimate * healthBefore.calibrationFactor;
+    console.log(`   Base estimate: ${(baseEstimate * 100).toFixed(1)}%`);
+    console.log(`   Calibrated estimate: ${(calibratedEstimate * 100).toFixed(1)}%`);
+    // 3. After session, calibrate with actual usage
+    console.log('\n3. Calibrate with actual usage');
+    const actualUsage = 0.65;
+    monitor.calibrate(session, actualUsage);
+    console.log(`   Actual usage: ${(actualUsage * 100).toFixed(1)}%`);
+    // 4. Check updated health
+    console.log('\n4. Check updated health');
+    const healthAfter = monitor.checkHealth(session);
+    console.log(`   New calibration factor: ${healthAfter.calibrationFactor.toFixed(3)}`);
+    console.log(`   Drift warning: ${healthAfter.driftWarning}`);
+    if (healthAfter.driftWarning) {
+        console.log(`   ⚠️  ${healthAfter.recommendation}`);
+    }
+}
+// =============================================================================
+// Example 5: Handling Drift Warnings
+// =============================================================================
+function exampleDriftWarnings() {
+    console.log('\n=== Example 5: Handling Drift Warnings ===\n');
+    const monitor = getHealthMonitor();
+    monitor.reset(); // Start fresh
+    const session = {
+        session_id: 'example-session-5',
+        started_at: new Date(),
+        injected_facts: [],
+    };
+    console.log('Simulating consistent underestimation:\n');
+    // Simulate consistent underestimation (actual >> estimated)
+    for (let i = 0; i < 5; i++) {
+        const actual = 0.75 + i * 0.02; // Gradually increasing
+        monitor.calibrate(session, actual);
+        console.log(`Calibration ${i + 1}: Actual ${(actual * 100).toFixed(1)}%`);
+    }
+    const health = monitor.checkHealth(session);
+    console.log('\nHealth Check Result:');
+    console.log(`  ⚠️  Drift Warning: ${health.driftWarning}`);
+    console.log(`  📊 Average Drift: ${(health.metrics.avgDrift * 100).toFixed(1)}%`);
+    console.log(`  🔧 Calibration Factor: ${health.calibrationFactor.toFixed(3)}`);
+    console.log(`\n💡 ${health.recommendation}`);
+    console.log('\nNext steps:');
+    console.log('  - Future estimates will be multiplied by calibration factor');
+    console.log('  - Monitor drift over time to ensure accuracy improves');
+    console.log('  - Consider more aggressive eviction if needed');
+}
+// =============================================================================
+// Run All Examples
+// =============================================================================
+if (import.meta.url === `file://${process.argv[1]}`) {
+    exampleBasicHealthCheck();
+    exampleCalibration();
+    exampleDriftHistory();
+    exampleIntegration();
+    exampleDriftWarnings();
+    console.log('\n=== Examples Complete ===\n');
+}

package/dist/context/health-monitor.js

@@ -0,0 +1,210 @@
+// =============================================================================
+// Health Monitor - Context estimation accuracy tracking
+// =============================================================================
+// Monitors drift between estimated and actual token usage to calibrate
+// estimates and warn when accuracy degrades.
+//
+// Calibration Logic:
+// - Records drift when actual fill data is available
+// - Adjusts future estimates by calibration factor
+// - Warns if drift exceeds 10%
+// =============================================================================
+// -----------------------------------------------------------------------------
+// Configuration
+// -----------------------------------------------------------------------------
+const HEALTH_CONFIG = {
+    /** Maximum number of drift records to store in memory */
+    MAX_DRIFT_HISTORY: 100,
+    /** Drift threshold for warnings (10%) */
+    DRIFT_WARNING_THRESHOLD: 0.1,
+    /** Number of samples needed before adjusting calibration */
+    MIN_SAMPLES_FOR_CALIBRATION: 3,
+    /** Weight of new samples in moving average (0-1) */
+    CALIBRATION_SMOOTHING: 0.3,
+};
+// -----------------------------------------------------------------------------
+// Health Monitor Implementation
+// -----------------------------------------------------------------------------
+export class HealthMonitor {
+    driftHistory = [];
+    calibrationFactor = 1.0;
+    lastCalibrationDate = null;
+    /**
+     * Check health status of session estimation
+     *
+     * @param session - Current session state
+     * @returns Health status with metrics and recommendations
+     */
+    checkHealth(session) {
+        const estimatedFill = this.getEstimatedFill(session);
+        const avgDrift = this.calculateAverageDrift();
+        const driftWarning = Math.abs(avgDrift) > HEALTH_CONFIG.DRIFT_WARNING_THRESHOLD;
+        return {
+            estimatedFill,
+            calibrationFactor: this.calibrationFactor,
+            driftWarning,
+            recommendation: this.generateRecommendation(avgDrift, driftWarning),
+            metrics: {
+                sessionsMonitored: this.driftHistory.length,
+                avgDrift,
+                lastCalibration: this.lastCalibrationDate,
+            },
+        };
+    }
+    /**
+     * Calibrate estimates using actual fill measurement
+     * Records drift and adjusts calibration factor if needed
+     *
+     * @param session - Current session state
+     * @param actualFill - Actual token usage (0.0 to 1.0)
+     */
+    calibrate(session, actualFill) {
+        const estimatedFill = this.getEstimatedFill(session);
+        const drift = actualFill - estimatedFill;
+        const driftPercent = drift / actualFill;
+        // Record drift
+        this.recordDrift(estimatedFill, actualFill, drift);
+        // Update calibration if we have enough samples
+        if (this.driftHistory.length >= HEALTH_CONFIG.MIN_SAMPLES_FOR_CALIBRATION) {
+            this.updateCalibrationFactor();
+        }
+    }
+    /**
+     * Get current calibration factor
+     * Multiply estimated tokens by this factor to get calibrated estimate
+     *
+     * @returns Current calibration factor
+     */
+    getCalibrationFactor() {
+        return this.calibrationFactor;
+    }
+    /**
+     * Get drift history for analysis
+     *
+     * @returns Array of drift records (newest first)
+     */
+    getDriftHistory() {
+        return [...this.driftHistory].reverse();
+    }
+    /**
+     * Clear drift history and reset calibration
+     * Useful when estimation algorithm changes
+     */
+    reset() {
+        this.driftHistory = [];
+        this.calibrationFactor = 1.0;
+        this.lastCalibrationDate = null;
+    }
+    // ---------------------------------------------------------------------------
+    // Private Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Get estimated fill from session state
+     * This would normally come from the usage estimator
+     */
+    getEstimatedFill(session) {
+        // In practice, this would call usageEstimator.getContextFill(session)
+        // For now, return a placeholder that accounts for calibration
+        return 0.5 * this.calibrationFactor; // Placeholder
+    }
+    /**
+     * Record a drift measurement
+     */
+    recordDrift(estimated, actual, drift) {
+        const record = {
+            timestamp: new Date(),
+            estimated,
+            actual,
+            drift,
+        };
+        this.driftHistory.push(record);
+        // Trim history if it exceeds max size
+        if (this.driftHistory.length > HEALTH_CONFIG.MAX_DRIFT_HISTORY) {
+            this.driftHistory.shift(); // Remove oldest
+        }
+    }
+    /**
+     * Calculate average drift from recent history
+     * Uses exponential weighting (recent samples weighted more)
+     */
+    calculateAverageDrift() {
+        if (this.driftHistory.length === 0) {
+            return 0;
+        }
+        // Use last 10 samples for average
+        const recentSamples = this.driftHistory.slice(-10);
+        let weightedSum = 0;
+        let totalWeight = 0;
+        recentSamples.forEach((record, index) => {
+            // Exponential weight: newer samples weighted more heavily
+            const weight = Math.exp(index / recentSamples.length);
+            const driftPercent = record.drift / record.actual;
+            weightedSum += driftPercent * weight;
+            totalWeight += weight;
+        });
+        return weightedSum / totalWeight;
+    }
+    /**
+     * Update calibration factor based on drift history
+     * Uses exponential moving average to smooth adjustments
+     */
+    updateCalibrationFactor() {
+        const avgDrift = this.calculateAverageDrift();
+        // Calculate new factor: if we're consistently underestimating (positive drift),
+        // increase the factor; if overestimating, decrease it
+        const targetFactor = 1 / (1 - avgDrift);
+        // Smooth the adjustment using exponential moving average
+        this.calibrationFactor =
+            this.calibrationFactor * (1 - HEALTH_CONFIG.CALIBRATION_SMOOTHING) +
+                targetFactor * HEALTH_CONFIG.CALIBRATION_SMOOTHING;
+        this.lastCalibrationDate = new Date();
+    }
+    /**
+     * Generate health recommendation based on drift
+     */
+    generateRecommendation(avgDrift, driftWarning) {
+        if (!driftWarning) {
+            return 'Estimation accuracy is good. No action needed.';
+        }
+        const driftPercent = Math.abs(avgDrift * 100).toFixed(1);
+        if (avgDrift > 0) {
+            // Underestimating (actual usage higher than estimated)
+            return `Warning: Estimates are ${driftPercent}% too low. Context window may fill faster than expected. Consider more aggressive eviction.`;
+        }
+        else {
+            // Overestimating (actual usage lower than estimated)
+            return `Warning: Estimates are ${driftPercent}% too high. Context window has more capacity than estimated. Can inject more facts safely.`;
+        }
+    }
+}
+// -----------------------------------------------------------------------------
+// Factory
+// -----------------------------------------------------------------------------
+/**
+ * Create a new health monitor instance
+ */
+export function createHealthMonitor() {
+    return new HealthMonitor();
+}
+// -----------------------------------------------------------------------------
+// Singleton Instance
+// -----------------------------------------------------------------------------
+let monitorInstance = null;
+/**
+ * Get or create the singleton health monitor instance
+ */
+export function getHealthMonitor() {
+    if (!monitorInstance) {
+        monitorInstance = new HealthMonitor();
+    }
+    return monitorInstance;
+}
+/**
+ * Reset the singleton instance (for testing)
+ */
+export function resetHealthMonitor() {
+    if (monitorInstance) {
+        monitorInstance.reset();
+    }
+    monitorInstance = null;
+}

package/dist/context/importance-scorer.d.ts

@@ -0,0 +1,94 @@
+import type { ScoredFact } from '@claudetools/shared';
+/**
+ * Fact that has been injected into the session context
+ * Tracks injection time and reference patterns for decay calculation
+ */
+export interface InjectedFact extends ScoredFact {
+    injected_at: Date;
+    last_referenced?: Date;
+}
+/**
+ * Session state tracking for importance scoring
+ * Contains session metadata needed for recency calculations
+ */
+export interface SessionState {
+    session_id: string;
+    started_at: Date;
+    injected_facts: InjectedFact[];
+}
+/**
+ * Importance level from fact metadata
+ */
+export type ImportanceLevel = 'critical' | 'high' | 'normal';
+/**
+ * Scored fact with computed importance
+ */
+export interface ScoredImportance {
+    fact: InjectedFact;
+    score: number;
+    breakdown: {
+        base: number;
+        timeDecay: number;
+        referenceBoost: number;
+        recencyBoost: number;
+    };
+}
+export declare class ImportanceScorer {
+    /**
+     * Calculate dynamic importance score for a single fact
+     *
+     * @param fact - The injected fact to score
+     * @param session - Current session state
+     * @returns Importance score between 0.0 and 1.0
+     */
+    calculateImportance(fact: InjectedFact, session: SessionState): number;
+    /**
+     * Calculate importance with component breakdown for debugging
+     *
+     * @param fact - The injected fact to score
+     * @param session - Current session state
+     * @returns Scored fact with breakdown
+     */
+    calculateWithBreakdown(fact: InjectedFact, session: SessionState): ScoredImportance;
+    /**
+     * Score all facts in a session
+     *
+     * @param session - Session state with injected facts
+     * @returns Array of scored facts sorted by score (descending)
+     */
+    scoreAllFacts(session: SessionState): ScoredImportance[];
+    /**
+     * Get facts that should be evicted (lowest importance scores)
+     *
+     * @param session - Session state
+     * @param count - Number of facts to evict
+     * @returns Facts to evict (lowest scores first)
+     */
+    getEvictionCandidates(session: SessionState, count: number): InjectedFact[];
+    /**
+     * Get facts above a minimum importance threshold
+     *
+     * @param session - Session state
+     * @param minScore - Minimum score threshold (0.0 to 1.0)
+     * @returns Facts above threshold
+     */
+    getFactsAboveThreshold(session: SessionState, minScore: number): InjectedFact[];
+    /**
+     * Extract importance level from fact metadata
+     */
+    private extractImportanceLevel;
+    /**
+     * Calculate reference boost
+     * Recently-referenced facts get a boost to stay in context longer
+     */
+    private calculateReferenceBoost;
+    /**
+     * Calculate recency boost
+     * Newer injections in the session get a boost
+     */
+    private calculateRecencyBoost;
+}
+/**
+ * Create a new importance scorer instance
+ */
+export declare function createImportanceScorer(): ImportanceScorer;

package/dist/context/importance-scorer.example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/context/importance-scorer.example.js

@@ -0,0 +1,140 @@
+// =============================================================================
+// Importance Scorer - Example Usage
+// =============================================================================
+// Demonstrates the importance decay algorithm for automatic context management
+// =============================================================================
+import { createImportanceScorer } from './importance-scorer.js';
+// -----------------------------------------------------------------------------
+// Example Session Setup
+// -----------------------------------------------------------------------------
+// Create a session that started 1 hour ago
+const sessionStartTime = new Date(Date.now() - 60 * 60 * 1000);
+// Create facts with different importance levels and injection times
+const facts = [
+    // Critical fact injected 5 minutes ago
+    {
+        edge_id: 'fact1',
+        source_entity_id: 'component_a',
+        target_entity_id: 'pattern_x',
+        relation_type: 'USES',
+        fact: 'ComponentA uses PatternX for state management',
+        created_at: new Date().toISOString(),
+        metadata: {
+            critical: true,
+            category: 'architecture',
+        },
+        injected_at: new Date(Date.now() - 5 * 60 * 1000), // 5 minutes ago
+    },
+    // High importance fact injected 15 minutes ago (still within half-life)
+    {
+        edge_id: 'fact2',
+        source_entity_id: 'bug_123',
+        target_entity_id: 'fix_abc',
+        relation_type: 'HAD_BUG',
+        fact: 'Bug 123 was fixed by implementing retry logic',
+        created_at: new Date().toISOString(),
+        metadata: {
+            important: true,
+            category: 'decision',
+        },
+        injected_at: new Date(Date.now() - 15 * 60 * 1000), // 15 minutes ago
+    },
+    // Normal fact injected 45 minutes ago (past half-life, should decay)
+    {
+        edge_id: 'fact3',
+        source_entity_id: 'user',
+        target_entity_id: 'preference',
+        relation_type: 'PREFERS',
+        fact: 'User prefers TypeScript over JavaScript',
+        created_at: new Date().toISOString(),
+        metadata: {
+            category: 'preference',
+        },
+        injected_at: new Date(Date.now() - 45 * 60 * 1000), // 45 minutes ago
+    },
+    // High importance fact injected 20 minutes ago, referenced 2 minutes ago
+    {
+        edge_id: 'fact4',
+        source_entity_id: 'module_y',
+        target_entity_id: 'dependency_z',
+        relation_type: 'DEPENDS_ON',
+        fact: 'ModuleY depends on DependencyZ for authentication',
+        created_at: new Date().toISOString(),
+        metadata: {
+            important: true,
+            category: 'pattern',
+        },
+        injected_at: new Date(Date.now() - 20 * 60 * 1000), // 20 minutes ago
+        last_referenced: new Date(Date.now() - 2 * 60 * 1000), // Referenced 2 minutes ago
+    },
+];
+const session = {
+    session_id: 'example_session',
+    started_at: sessionStartTime,
+    injected_facts: facts,
+};
+// -----------------------------------------------------------------------------
+// Score and Display Results
+// -----------------------------------------------------------------------------
+const scorer = createImportanceScorer();
+console.log('='.repeat(80));
+console.log('Importance Scorer - Example Execution');
+console.log('='.repeat(80));
+console.log();
+// Score all facts
+const scored = scorer.scoreAllFacts(session);
+console.log('Scored Facts (highest to lowest importance):');
+console.log('-'.repeat(80));
+scored.forEach((result, index) => {
+    console.log(`${index + 1}. ${result.fact.fact}`);
+    console.log(`   Score: ${result.score.toFixed(3)}`);
+    console.log(`   Breakdown:`);
+    console.log(`     - Base Importance: ${result.breakdown.base.toFixed(3)}`);
+    console.log(`     - Time Decay: ${result.breakdown.timeDecay.toFixed(3)}`);
+    console.log(`     - Reference Boost: ${result.breakdown.referenceBoost.toFixed(3)}`);
+    console.log(`     - Recency Boost: ${result.breakdown.recencyBoost.toFixed(3)}`);
+    console.log(`   Injected: ${Math.round((Date.now() - result.fact.injected_at.getTime()) / 60000)} minutes ago`);
+    if (result.fact.last_referenced) {
+        console.log(`   Last Referenced: ${Math.round((Date.now() - result.fact.last_referenced.getTime()) / 60000)} minutes ago`);
+    }
+    console.log();
+});
+// -----------------------------------------------------------------------------
+// Eviction Example
+// -----------------------------------------------------------------------------
+console.log('='.repeat(80));
+console.log('Eviction Candidates (lowest 2 scores):');
+console.log('-'.repeat(80));
+const evictionCandidates = scorer.getEvictionCandidates(session, 2);
+evictionCandidates.forEach((fact, index) => {
+    console.log(`${index + 1}. ${fact.fact}`);
+});
+console.log();
+// -----------------------------------------------------------------------------
+// Threshold Example
+// -----------------------------------------------------------------------------
+console.log('='.repeat(80));
+console.log('Facts Above Threshold (min score: 0.5):');
+console.log('-'.repeat(80));
+const aboveThreshold = scorer.getFactsAboveThreshold(session, 0.5);
+aboveThreshold.forEach((fact, index) => {
+    console.log(`${index + 1}. ${fact.fact}`);
+});
+console.log();
+// -----------------------------------------------------------------------------
+// Algorithm Verification
+// -----------------------------------------------------------------------------
+console.log('='.repeat(80));
+console.log('Algorithm Verification:');
+console.log('-'.repeat(80));
+console.log('✓ Base importance levels: critical (1.0), high (0.7), normal (0.4)');
+console.log('✓ Time decay: Exponential with 30-minute half-life');
+console.log('✓ Reference boost: Recent references keep facts longer');
+console.log('✓ Recency boost: Newer injections weighted higher');
+console.log('✓ Score range: All scores between 0.0 and 1.0');
+console.log();
+console.log('Expected behavior:');
+console.log('  - Critical architecture fact should score highest (recently injected)');
+console.log('  - Recently referenced fact should get boost despite age');
+console.log('  - Old normal fact should score lowest (past half-life, no boost)');
+console.log('='.repeat(80));