@claudetools/tools 0.8.2 → 0.8.4

package/dist/context/example-usage.js

@@ -0,0 +1,128 @@
+// =============================================================================
+// Usage Estimator Example
+// =============================================================================
+//
+// Example demonstrating how to use the context usage estimator in practice.
+//
+// =============================================================================
+import { usageEstimator, estimateTokens, isContextNearLimit, getContextFill, MODEL_CONTEXT_LIMITS, } from './index.js';
+/**
+ * Example: Track a complete conversation flow
+ */
+function exampleConversation() {
+    console.log('=== Context Usage Estimator Example ===\n');
+    // 1. Initial session context injection (SessionStart)
+    const sessionContext = `
+You are Claude Code, an AI assistant. You have access to memory tools...
+[large system prompt and instructions]
+`.repeat(50);
+    const sessionTokens = estimateTokens(sessionContext);
+    usageEstimator.trackInjection(sessionTokens);
+    console.log(`Session context injected: ${sessionTokens} tokens`);
+    // 2. User message
+    const userMessage = 'Help me implement a new feature for user authentication';
+    const userTokens = estimateTokens(userMessage);
+    usageEstimator.trackUserMessage(userTokens);
+    console.log(`User message: ${userTokens} tokens`);
+    // 3. Context injection based on user query
+    const relevantContext = `
+Memory facts about authentication:
+- User authentication uses JWT tokens
+- Tokens expire after 24 hours
+- Refresh tokens are stored in httpOnly cookies
+`.repeat(20);
+    const contextTokens = estimateTokens(relevantContext);
+    usageEstimator.trackInjection(contextTokens);
+    console.log(`Query-based context injected: ${contextTokens} tokens`);
+    // 4. Tool outputs (e.g., codebase search results)
+    const toolOutput = `
+Found 5 authentication-related files:
+- src/auth/jwt.ts
+- src/auth/refresh.ts
+- src/middleware/auth.ts
+`.repeat(10);
+    const toolTokens = estimateTokens(toolOutput);
+    usageEstimator.trackToolOutput(toolTokens);
+    console.log(`Tool output: ${toolTokens} tokens`);
+    // 5. Assistant response
+    const assistantResponse = `
+I'll help you implement user authentication. Based on the existing codebase,
+here's my recommendation:
+
+[detailed implementation plan]
+`.repeat(100);
+    const assistantTokens = estimateTokens(assistantResponse);
+    usageEstimator.trackAssistantMessage(assistantTokens);
+    console.log(`Assistant response: ${assistantTokens} tokens`);
+    // 6. Check status
+    console.log('\n--- Current Status ---');
+    const usage = usageEstimator.getCurrentUsage();
+    console.log(`Total tokens: ${usage.totalEstimated.toLocaleString()}`);
+    console.log(`Context fill: ${getContextFill().toFixed(1)}%`);
+    console.log(`Approaching limit: ${isContextNearLimit() ? 'YES ⚠️' : 'NO ✅'}`);
+    // 7. Print full report
+    console.log('\n');
+    console.log(usageEstimator.getReport(MODEL_CONTEXT_LIMITS.SONNET));
+}
+/**
+ * Example: Simulate approaching context limit
+ */
+function exampleApproachingLimit() {
+    console.log('\n=== Example: Approaching Limit ===\n');
+    // Reset estimator
+    usageEstimator.reset();
+    // Simulate a long conversation with lots of context
+    const limit = MODEL_CONTEXT_LIMITS.SONNET;
+    // Large initial injection
+    usageEstimator.trackInjection(100_000);
+    console.log(`After session start: ${getContextFill().toFixed(1)}% full`);
+    // Multiple exchanges
+    for (let i = 0; i < 10; i++) {
+        usageEstimator.trackExchange(2_000, 8_000);
+    }
+    console.log(`After 10 exchanges: ${getContextFill().toFixed(1)}% full`);
+    // Check if we should start pruning context
+    if (isContextNearLimit(80)) {
+        console.log('\n⚠️  Context is near limit! Time to:');
+        console.log('   - Prune old context');
+        console.log('   - Reduce injection size');
+        console.log('   - Summarise conversation history');
+        const remaining = usageEstimator.getRemainingBudget(limit);
+        console.log(`\nRemaining budget: ${remaining.toLocaleString()} tokens`);
+    }
+    // Show history trend
+    const history = usageEstimator.getHistory();
+    console.log(`\nHistory snapshots: ${history.length}`);
+    console.log('Fill percentage trend:');
+    history.slice(-5).forEach((snapshot, i) => {
+        console.log(`  ${i + 1}. ${snapshot.fillPercentage.toFixed(1)}%`);
+    });
+}
+/**
+ * Example: Token estimation accuracy
+ */
+function exampleTokenEstimation() {
+    console.log('\n=== Example: Token Estimation ===\n');
+    const samples = [
+        'Hello',
+        'Hello, how are you today?',
+        'The quick brown fox jumps over the lazy dog',
+        `function calculateTotal(items) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}`,
+        'a'.repeat(1000),
+    ];
+    console.log('Character count → Estimated tokens:\n');
+    samples.forEach(text => {
+        const tokens = estimateTokens(text);
+        const preview = text.length > 50 ? text.slice(0, 47) + '...' : text;
+        console.log(`  ${text.length} chars → ~${tokens} tokens`);
+        console.log(`    "${preview}"\n`);
+    });
+}
+// Run examples if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    exampleConversation();
+    exampleApproachingLimit();
+    exampleTokenEstimation();
+}

package/dist/context/exchange-summariser.d.ts

@@ -0,0 +1,80 @@
+import type { SessionState } from './importance-scorer.js';
+import type { Exchange } from './session-store.js';
+/**
+ * Session state with exchanges (extends base SessionState)
+ */
+export interface SessionStateWithExchanges extends SessionState {
+    exchanges: Exchange[];
+}
+/**
+ * Result of summarising a batch of exchanges
+ */
+export interface SummarisationResult {
+    summarisedCount: number;
+    summary: string;
+    tokensSaved: number;
+}
+/**
+ * AI environment interface for summarisation (optional)
+ */
+export interface AIEnvironment {
+    AI?: {
+        run: (model: string, options: {
+            messages: Array<{
+                role: string;
+                content: string;
+            }>;
+        }) => Promise<unknown>;
+    };
+    EXTRACTION_MODEL?: string;
+}
+export declare class ExchangeSummariser {
+    private env?;
+    constructor(env?: AIEnvironment);
+    /**
+     * Check if session has exchanges that should be summarised
+     *
+     * @param session - Current session state
+     * @param threshold - Number of unsummarised turns to trigger (default: 10)
+     * @returns True if summarisation should be triggered
+     */
+    shouldSummarise(session: SessionStateWithExchanges, threshold?: number): boolean;
+    /**
+     * Summarise old exchanges in the session
+     *
+     * @param session - Current session state (with exchanges)
+     * @param threshold - Number of unsummarised turns to leave active (default: 10)
+     * @returns Summarisation result with token savings
+     */
+    summariseOldExchanges(session: SessionStateWithExchanges, threshold?: number): Promise<SummarisationResult>;
+    /**
+     * Get the current summary for a session (if exists)
+     *
+     * @param session - Session state
+     * @returns Summary text or null if no summarised exchanges
+     */
+    getSummary(session: SessionStateWithExchanges): string | null;
+    /**
+     * Generate summary for a batch of exchanges
+     *
+     * Uses AI if available, falls back to extractive summarisation
+     */
+    private generateSummary;
+    /**
+     * AI-powered summarisation using Workers AI
+     */
+    private aiSummarise;
+    /**
+     * Extractive summarisation (local, no AI required)
+     *
+     * Strategy: Create a factual summary based on exchange metadata
+     */
+    private extractiveSummarise;
+}
+/**
+ * Create an ExchangeSummariser instance
+ *
+ * @param env - Optional AI environment for AI-powered summarisation
+ * @returns ExchangeSummariser instance
+ */
+export declare function createExchangeSummariser(env?: AIEnvironment): ExchangeSummariser;

package/dist/context/exchange-summariser.js

@@ -0,0 +1,261 @@
+// =============================================================================
+// Exchange Summariser - Automatic Context Management
+// =============================================================================
+// Summarises old exchanges (>10 turns) to reduce token count while preserving
+// decisions, outcomes, and key information.
+//
+// Strategy:
+// - For local/offline: extractive summarisation (key sentences)
+// - With AI available: Workers AI for better quality summaries
+// - Stores summaries in session state
+// - Marks exchanges as summarised to avoid re-processing
+// =============================================================================
+// -----------------------------------------------------------------------------
+// Configuration
+// -----------------------------------------------------------------------------
+const SUMMARISATION_CONFIG = {
+    DEFAULT_THRESHOLD: 10, // Default number of turns before summarisation
+    EXTRACTIVE_SENTENCES: 3, // Number of sentences to extract in local mode
+    MAX_SUMMARY_LENGTH: 500, // Maximum summary length (tokens ~125)
+    TURN_BATCH_SIZE: 10, // Summarise in batches of N turns
+};
+// -----------------------------------------------------------------------------
+// Token Estimation
+// -----------------------------------------------------------------------------
+/**
+ * Estimate token count for text (rough approximation: ~4 chars per token)
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// -----------------------------------------------------------------------------
+// Exchange Summariser
+// -----------------------------------------------------------------------------
+export class ExchangeSummariser {
+    env;
+    constructor(env) {
+        this.env = env;
+    }
+    /**
+     * Check if session has exchanges that should be summarised
+     *
+     * @param session - Current session state
+     * @param threshold - Number of unsummarised turns to trigger (default: 10)
+     * @returns True if summarisation should be triggered
+     */
+    shouldSummarise(session, threshold = SUMMARISATION_CONFIG.DEFAULT_THRESHOLD) {
+        if (!session.exchanges || session.exchanges.length === 0) {
+            return false;
+        }
+        // Count unsummarised exchanges
+        const unsummarised = session.exchanges.filter(ex => !ex.summarised_at);
+        return unsummarised.length >= threshold;
+    }
+    /**
+     * Summarise old exchanges in the session
+     *
+     * @param session - Current session state (with exchanges)
+     * @param threshold - Number of unsummarised turns to leave active (default: 10)
+     * @returns Summarisation result with token savings
+     */
+    async summariseOldExchanges(session, threshold = SUMMARISATION_CONFIG.DEFAULT_THRESHOLD) {
+        if (!session.exchanges || session.exchanges.length === 0) {
+            return {
+                summarisedCount: 0,
+                summary: '',
+                tokensSaved: 0,
+            };
+        }
+        // Get unsummarised exchanges, oldest first
+        const unsummarised = session.exchanges
+            .filter((ex) => !ex.summarised_at)
+            .sort((a, b) => a.turn - b.turn);
+        // Only summarise if we have enough exchanges beyond threshold
+        if (unsummarised.length <= threshold) {
+            return {
+                summarisedCount: 0,
+                summary: '',
+                tokensSaved: 0,
+            };
+        }
+        // Identify exchanges to summarise (leave threshold most recent ones active)
+        const toSummarise = unsummarised.slice(0, -threshold);
+        if (toSummarise.length === 0) {
+            return {
+                summarisedCount: 0,
+                summary: '',
+                tokensSaved: 0,
+            };
+        }
+        // Calculate token savings (approximate)
+        const originalTokens = toSummarise.reduce((sum, ex) => sum + ex.user_tokens + ex.assistant_tokens + ex.tool_tokens, 0);
+        // Generate summary
+        const summary = await this.generateSummary(toSummarise, session.session_id);
+        const summaryTokens = estimateTokens(summary);
+        const tokensSaved = originalTokens - summaryTokens;
+        // Mark exchanges as summarised
+        const now = new Date();
+        toSummarise.forEach((ex) => {
+            ex.summarised_at = now;
+        });
+        console.log(`📝 SUMMARISATION: Turns ${toSummarise[0].turn}-${toSummarise[toSummarise.length - 1].turn} ` +
+            `(${toSummarise.length} exchanges): ${originalTokens} → ${summaryTokens} tokens ` +
+            `(${((tokensSaved / originalTokens) * 100).toFixed(1)}% reduction)`);
+        return {
+            summarisedCount: toSummarise.length,
+            summary,
+            tokensSaved,
+        };
+    }
+    /**
+     * Get the current summary for a session (if exists)
+     *
+     * @param session - Session state
+     * @returns Summary text or null if no summarised exchanges
+     */
+    getSummary(session) {
+        if (!session.exchanges || session.exchanges.length === 0) {
+            return null;
+        }
+        const summarised = session.exchanges.filter((ex) => ex.summarised_at);
+        if (summarised.length === 0) {
+            return null;
+        }
+        // Return a compact summary header
+        const turnRange = `${Math.min(...summarised.map((e) => e.turn))}-${Math.max(...summarised.map((e) => e.turn))}`;
+        return `Turns ${turnRange} summary: ${summarised.length} exchanges summarised`;
+    }
+    // ---------------------------------------------------------------------------
+    // Summary Generation
+    // ---------------------------------------------------------------------------
+    /**
+     * Generate summary for a batch of exchanges
+     *
+     * Uses AI if available, falls back to extractive summarisation
+     */
+    async generateSummary(exchanges, sessionId) {
+        // Try AI-powered summarisation first
+        if (this.env?.AI && this.env?.EXTRACTION_MODEL) {
+            try {
+                return await this.aiSummarise(exchanges);
+            }
+            catch (error) {
+                console.error('AI summarisation failed, falling back to extractive:', error);
+            }
+        }
+        // Fallback: extractive summarisation
+        return this.extractiveSummarise(exchanges);
+    }
+    /**
+     * AI-powered summarisation using Workers AI
+     */
+    async aiSummarise(exchanges) {
+        if (!this.env?.AI || !this.env?.EXTRACTION_MODEL) {
+            throw new Error('AI not available');
+        }
+        // Build simple exchange representation
+        // Note: We don't have the actual message content in Exchange type,
+        // so we focus on metadata
+        const turnSummary = exchanges
+            .map(ex => {
+            const tokens = ex.user_tokens + ex.assistant_tokens + ex.tool_tokens;
+            return `Turn ${ex.turn}: ${tokens} tokens (user: ${ex.user_tokens}, assistant: ${ex.assistant_tokens}, tools: ${ex.tool_tokens})`;
+        })
+            .join('\n');
+        const prompt = `You are a conversation summariser. Summarise these conversation turns concisely.
+
+TURNS:
+"""
+${turnSummary}
+"""
+
+Create a 1-2 sentence summary focusing on:
+- Number of turns and turn range
+- Key activity indicators (high token usage = detailed discussion)
+- Progress indicators (tool usage patterns)
+
+RESPOND WITH TEXT ONLY. NO JSON. NO MARKDOWN. Just the summary.
+
+Example: "Turns 1-10: Investigated authentication bug in src/auth.ts with extensive code review (high token usage). Used grep and read tools to analyse JWT implementation, identified expiry issue."`;
+        const response = await this.env.AI.run(this.env.EXTRACTION_MODEL, { messages: [{ role: 'user', content: prompt }] });
+        // Parse response
+        let summaryText;
+        if (typeof response === 'string') {
+            summaryText = response;
+        }
+        else if (response && typeof response === 'object') {
+            const responseData = response.response;
+            if (responseData) {
+                if (typeof responseData === 'string') {
+                    summaryText = responseData;
+                }
+                else if (typeof responseData === 'object') {
+                    // Try to extract a summary field if it's JSON
+                    summaryText = responseData.summary || JSON.stringify(responseData);
+                }
+                else {
+                    summaryText = 'Summary generation failed';
+                }
+            }
+            else {
+                const possibleText = response.text
+                    || response.content
+                    || 'Summary generation failed';
+                summaryText = typeof possibleText === 'string' ? possibleText : 'Summary generation failed';
+            }
+        }
+        else {
+            summaryText = 'Summary generation failed';
+        }
+        // Truncate if too long
+        if (summaryText.length > SUMMARISATION_CONFIG.MAX_SUMMARY_LENGTH) {
+            summaryText = summaryText.slice(0, SUMMARISATION_CONFIG.MAX_SUMMARY_LENGTH) + '...';
+        }
+        return summaryText.trim();
+    }
+    /**
+     * Extractive summarisation (local, no AI required)
+     *
+     * Strategy: Create a factual summary based on exchange metadata
+     */
+    extractiveSummarise(exchanges) {
+        if (exchanges.length === 0) {
+            return '';
+        }
+        const turnRange = `${exchanges[0].turn}-${exchanges[exchanges.length - 1].turn}`;
+        const totalTokens = exchanges.reduce((sum, ex) => sum + ex.user_tokens + ex.assistant_tokens + ex.tool_tokens, 0);
+        const avgTokens = Math.round(totalTokens / exchanges.length);
+        // Classify activity level
+        let activity = 'discussion';
+        if (avgTokens > 2000) {
+            activity = 'extensive code analysis';
+        }
+        else if (avgTokens > 1000) {
+            activity = 'detailed investigation';
+        }
+        else if (avgTokens > 500) {
+            activity = 'moderate discussion';
+        }
+        else {
+            activity = 'brief exchanges';
+        }
+        // Detect tool usage patterns
+        const toolHeavy = exchanges.filter(ex => ex.tool_tokens > ex.assistant_tokens).length;
+        const toolPattern = toolHeavy > exchanges.length / 2
+            ? ' Heavy tool usage indicates codebase exploration or file operations.'
+            : '';
+        return `Turns ${turnRange} summary: ${exchanges.length} exchanges with ${activity} (avg ${avgTokens} tokens/turn).${toolPattern}`;
+    }
+}
+// -----------------------------------------------------------------------------
+// Factory Functions
+// -----------------------------------------------------------------------------
+/**
+ * Create an ExchangeSummariser instance
+ *
+ * @param env - Optional AI environment for AI-powered summarisation
+ * @returns ExchangeSummariser instance
+ */
+export function createExchangeSummariser(env) {
+    return new ExchangeSummariser(env);
+}

package/dist/context/health-monitor.d.ts

@@ -0,0 +1,97 @@
+import type { SessionState } from './importance-scorer.js';
+/**
+ * Health status of context estimation
+ */
+export interface HealthStatus {
+    estimatedFill: number;
+    calibrationFactor: number;
+    driftWarning: boolean;
+    recommendation: string;
+    metrics: {
+        sessionsMonitored: number;
+        avgDrift: number;
+        lastCalibration: Date | null;
+    };
+}
+/**
+ * Single drift measurement
+ */
+export interface DriftRecord {
+    timestamp: Date;
+    estimated: number;
+    actual: number;
+    drift: number;
+}
+export declare class HealthMonitor {
+    private driftHistory;
+    private calibrationFactor;
+    private lastCalibrationDate;
+    /**
+     * Check health status of session estimation
+     *
+     * @param session - Current session state
+     * @returns Health status with metrics and recommendations
+     */
+    checkHealth(session: SessionState): HealthStatus;
+    /**
+     * 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: SessionState, actualFill: number): void;
+    /**
+     * Get current calibration factor
+     * Multiply estimated tokens by this factor to get calibrated estimate
+     *
+     * @returns Current calibration factor
+     */
+    getCalibrationFactor(): number;
+    /**
+     * Get drift history for analysis
+     *
+     * @returns Array of drift records (newest first)
+     */
+    getDriftHistory(): DriftRecord[];
+    /**
+     * Clear drift history and reset calibration
+     * Useful when estimation algorithm changes
+     */
+    reset(): void;
+    /**
+     * Get estimated fill from session state
+     * This would normally come from the usage estimator
+     */
+    private getEstimatedFill;
+    /**
+     * Record a drift measurement
+     */
+    private recordDrift;
+    /**
+     * Calculate average drift from recent history
+     * Uses exponential weighting (recent samples weighted more)
+     */
+    private calculateAverageDrift;
+    /**
+     * Update calibration factor based on drift history
+     * Uses exponential moving average to smooth adjustments
+     */
+    private updateCalibrationFactor;
+    /**
+     * Generate health recommendation based on drift
+     */
+    private generateRecommendation;
+}
+/**
+ * Create a new health monitor instance
+ */
+export declare function createHealthMonitor(): HealthMonitor;
+/**
+ * Get or create the singleton health monitor instance
+ */
+export declare function getHealthMonitor(): HealthMonitor;
+/**
+ * Reset the singleton instance (for testing)
+ */
+export declare function resetHealthMonitor(): void;

package/dist/context/health-monitor.example.d.ts

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