@claudetools/tools 0.8.2 → 0.8.4

package/dist/context/usage-estimator.d.ts

@@ -0,0 +1,131 @@
+export interface TokenUsage {
+    injectedTokens: number;
+    toolOutputTokens: number;
+    userTokens: number;
+    assistantTokens: number;
+    totalEstimated: number;
+}
+export interface UsageSnapshot {
+    timestamp: string;
+    usage: TokenUsage;
+    fillPercentage: number;
+    modelLimit: number;
+}
+/**
+ * Model context limits (in tokens)
+ */
+export declare const MODEL_CONTEXT_LIMITS: {
+    readonly SONNET: 200000;
+    readonly OPUS: 200000;
+    readonly HAIKU: 200000;
+};
+/**
+ * Default model limit to use
+ */
+export declare const DEFAULT_MODEL_LIMIT: 200000;
+export declare class UsageEstimator {
+    private usage;
+    private history;
+    private maxHistorySize;
+    constructor(maxHistorySize?: number);
+    /**
+     * Estimate tokens from text using character count approximation
+     * @param text - Text to estimate tokens for
+     * @returns Estimated token count
+     */
+    estimateTokens(text: string): number;
+    /**
+     * Track context injection (SessionStart, UserPromptSubmit)
+     * @param tokens - Number of tokens injected
+     */
+    trackInjection(tokens: number): void;
+    /**
+     * Track tool output tokens
+     * @param tokens - Number of tokens in tool output
+     */
+    trackToolOutput(tokens: number): void;
+    /**
+     * Track a conversation exchange (user + assistant)
+     * @param userTokens - Tokens in user message
+     * @param assistantTokens - Tokens in assistant response
+     */
+    trackExchange(userTokens: number, assistantTokens: number): void;
+    /**
+     * Track user message tokens
+     * @param tokens - Number of tokens in user message
+     */
+    trackUserMessage(tokens: number): void;
+    /**
+     * Track assistant response tokens
+     * @param tokens - Number of tokens in assistant response
+     */
+    trackAssistantMessage(tokens: number): void;
+    /**
+     * Get estimated context fill percentage
+     * @param modelLimit - Model context limit (defaults to Sonnet/Opus 200k)
+     * @returns Fill percentage (0-100)
+     */
+    getEstimatedFill(modelLimit?: number): number;
+    /**
+     * Get current usage statistics
+     * @returns Current token usage breakdown
+     */
+    getCurrentUsage(): TokenUsage;
+    /**
+     * Get usage history snapshots
+     * @returns Array of historical usage snapshots
+     */
+    getHistory(): UsageSnapshot[];
+    /**
+     * Check if context is approaching limit
+     * @param threshold - Percentage threshold (default 80%)
+     * @param modelLimit - Model context limit
+     * @returns true if fill exceeds threshold
+     */
+    isApproachingLimit(threshold?: number, modelLimit?: number): boolean;
+    /**
+     * Get remaining token budget
+     * @param modelLimit - Model context limit
+     * @returns Number of tokens remaining
+     */
+    getRemainingBudget(modelLimit?: number): number;
+    /**
+     * Reset all usage tracking
+     */
+    reset(): void;
+    /**
+     * Get a formatted usage report
+     * @param modelLimit - Model context limit
+     * @returns Human-readable usage report
+     */
+    getReport(modelLimit?: number): string;
+    /**
+     * Update total estimated tokens
+     */
+    private updateTotal;
+    /**
+     * Take a snapshot of current usage
+     */
+    private snapshot;
+    /**
+     * Get status emoji based on fill percentage
+     */
+    private getStatusEmoji;
+    /**
+     * Get status text based on fill percentage
+     */
+    private getStatusText;
+}
+export declare const usageEstimator: UsageEstimator;
+/**
+ * Helper: Estimate tokens from text (convenience function)
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Helper: Check if context is approaching limit
+ */
+export declare function isContextNearLimit(threshold?: number): boolean;
+/**
+ * Helper: Get current fill percentage
+ */
+export declare function getContextFill(): number;

package/dist/context/usage-estimator.js

@@ -0,0 +1,260 @@
+// =============================================================================
+// Context Usage Estimator
+// =============================================================================
+//
+// Track token usage per injection, maintain running totals, and estimate
+// context fill percentage for automatic context management.
+//
+// Token estimation uses ~4 chars = 1 token approximation (conservative).
+// Model context limits: Sonnet/Opus = 200k, Haiku = 200k
+//
+// =============================================================================
+/**
+ * Model context limits (in tokens)
+ */
+export const MODEL_CONTEXT_LIMITS = {
+    SONNET: 200_000,
+    OPUS: 200_000,
+    HAIKU: 200_000,
+};
+/**
+ * Default model limit to use
+ */
+export const DEFAULT_MODEL_LIMIT = MODEL_CONTEXT_LIMITS.SONNET;
+/**
+ * Conservative token estimation: ~4 characters = 1 token
+ * This tends to overestimate slightly, which is safer for context management.
+ */
+const CHARS_PER_TOKEN = 4;
+export class UsageEstimator {
+    usage;
+    history;
+    maxHistorySize;
+    constructor(maxHistorySize = 100) {
+        this.usage = {
+            injectedTokens: 0,
+            toolOutputTokens: 0,
+            userTokens: 0,
+            assistantTokens: 0,
+            totalEstimated: 0,
+        };
+        this.history = [];
+        this.maxHistorySize = maxHistorySize;
+    }
+    /**
+     * Estimate tokens from text using character count approximation
+     * @param text - Text to estimate tokens for
+     * @returns Estimated token count
+     */
+    estimateTokens(text) {
+        if (!text || text.length === 0) {
+            return 0;
+        }
+        return Math.ceil(text.length / CHARS_PER_TOKEN);
+    }
+    /**
+     * Track context injection (SessionStart, UserPromptSubmit)
+     * @param tokens - Number of tokens injected
+     */
+    trackInjection(tokens) {
+        this.usage.injectedTokens += tokens;
+        this.updateTotal();
+        this.snapshot();
+    }
+    /**
+     * Track tool output tokens
+     * @param tokens - Number of tokens in tool output
+     */
+    trackToolOutput(tokens) {
+        this.usage.toolOutputTokens += tokens;
+        this.updateTotal();
+        this.snapshot();
+    }
+    /**
+     * Track a conversation exchange (user + assistant)
+     * @param userTokens - Tokens in user message
+     * @param assistantTokens - Tokens in assistant response
+     */
+    trackExchange(userTokens, assistantTokens) {
+        this.usage.userTokens += userTokens;
+        this.usage.assistantTokens += assistantTokens;
+        this.updateTotal();
+        this.snapshot();
+    }
+    /**
+     * Track user message tokens
+     * @param tokens - Number of tokens in user message
+     */
+    trackUserMessage(tokens) {
+        this.usage.userTokens += tokens;
+        this.updateTotal();
+        this.snapshot();
+    }
+    /**
+     * Track assistant response tokens
+     * @param tokens - Number of tokens in assistant response
+     */
+    trackAssistantMessage(tokens) {
+        this.usage.assistantTokens += tokens;
+        this.updateTotal();
+        this.snapshot();
+    }
+    /**
+     * Get estimated context fill percentage
+     * @param modelLimit - Model context limit (defaults to Sonnet/Opus 200k)
+     * @returns Fill percentage (0-100)
+     */
+    getEstimatedFill(modelLimit = DEFAULT_MODEL_LIMIT) {
+        if (modelLimit <= 0) {
+            return 0;
+        }
+        const fillPercentage = (this.usage.totalEstimated / modelLimit) * 100;
+        return Math.min(100, Math.max(0, fillPercentage));
+    }
+    /**
+     * Get current usage statistics
+     * @returns Current token usage breakdown
+     */
+    getCurrentUsage() {
+        return { ...this.usage };
+    }
+    /**
+     * Get usage history snapshots
+     * @returns Array of historical usage snapshots
+     */
+    getHistory() {
+        return [...this.history];
+    }
+    /**
+     * Check if context is approaching limit
+     * @param threshold - Percentage threshold (default 80%)
+     * @param modelLimit - Model context limit
+     * @returns true if fill exceeds threshold
+     */
+    isApproachingLimit(threshold = 80, modelLimit = DEFAULT_MODEL_LIMIT) {
+        return this.getEstimatedFill(modelLimit) >= threshold;
+    }
+    /**
+     * Get remaining token budget
+     * @param modelLimit - Model context limit
+     * @returns Number of tokens remaining
+     */
+    getRemainingBudget(modelLimit = DEFAULT_MODEL_LIMIT) {
+        return Math.max(0, modelLimit - this.usage.totalEstimated);
+    }
+    /**
+     * Reset all usage tracking
+     */
+    reset() {
+        this.usage = {
+            injectedTokens: 0,
+            toolOutputTokens: 0,
+            userTokens: 0,
+            assistantTokens: 0,
+            totalEstimated: 0,
+        };
+        this.history = [];
+    }
+    /**
+     * Get a formatted usage report
+     * @param modelLimit - Model context limit
+     * @returns Human-readable usage report
+     */
+    getReport(modelLimit = DEFAULT_MODEL_LIMIT) {
+        const fill = this.getEstimatedFill(modelLimit);
+        const remaining = this.getRemainingBudget(modelLimit);
+        const lines = [
+            'Context Usage Report',
+            '='.repeat(50),
+            '',
+            'Token Breakdown:',
+            `  Injected Context: ${this.usage.injectedTokens.toLocaleString()} tokens`,
+            `  Tool Outputs:     ${this.usage.toolOutputTokens.toLocaleString()} tokens`,
+            `  User Messages:    ${this.usage.userTokens.toLocaleString()} tokens`,
+            `  Assistant:        ${this.usage.assistantTokens.toLocaleString()} tokens`,
+            `  Total Estimated:  ${this.usage.totalEstimated.toLocaleString()} tokens`,
+            '',
+            'Context Window:',
+            `  Model Limit:      ${modelLimit.toLocaleString()} tokens`,
+            `  Used:             ${this.usage.totalEstimated.toLocaleString()} tokens (${fill.toFixed(1)}%)`,
+            `  Remaining:        ${remaining.toLocaleString()} tokens`,
+            '',
+            `Status: ${this.getStatusEmoji(fill)} ${this.getStatusText(fill)}`,
+            '='.repeat(50),
+        ];
+        return lines.join('\n');
+    }
+    // ---------------------------------------------------------------------------
+    // Private Methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Update total estimated tokens
+     */
+    updateTotal() {
+        this.usage.totalEstimated =
+            this.usage.injectedTokens +
+                this.usage.toolOutputTokens +
+                this.usage.userTokens +
+                this.usage.assistantTokens;
+    }
+    /**
+     * Take a snapshot of current usage
+     */
+    snapshot() {
+        const snapshot = {
+            timestamp: new Date().toISOString(),
+            usage: { ...this.usage },
+            fillPercentage: this.getEstimatedFill(),
+            modelLimit: DEFAULT_MODEL_LIMIT,
+        };
+        this.history.push(snapshot);
+        // Trim history if it exceeds max size
+        if (this.history.length > this.maxHistorySize) {
+            this.history = this.history.slice(-this.maxHistorySize);
+        }
+    }
+    /**
+     * Get status emoji based on fill percentage
+     */
+    getStatusEmoji(fill) {
+        if (fill >= 90)
+            return '🔴';
+        if (fill >= 80)
+            return '🟡';
+        if (fill >= 50)
+            return '🟢';
+        return '✅';
+    }
+    /**
+     * Get status text based on fill percentage
+     */
+    getStatusText(fill) {
+        if (fill >= 90)
+            return 'Critical - Context nearly full';
+        if (fill >= 80)
+            return 'Warning - Approaching limit';
+        if (fill >= 50)
+            return 'Good - Moderate usage';
+        return 'Excellent - Plenty of space';
+    }
+}
+// Export singleton instance for convenience
+export const usageEstimator = new UsageEstimator();
+/**
+ * Helper: Estimate tokens from text (convenience function)
+ */
+export function estimateTokens(text) {
+    return usageEstimator.estimateTokens(text);
+}
+/**
+ * Helper: Check if context is approaching limit
+ */
+export function isContextNearLimit(threshold = 80) {
+    return usageEstimator.isApproachingLimit(threshold);
+}
+/**
+ * Helper: Get current fill percentage
+ */
+export function getContextFill() {
+    return usageEstimator.getEstimatedFill();
+}

package/dist/context/usage-estimator.test.d.ts

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

package/dist/context/usage-estimator.test.js

@@ -0,0 +1,208 @@
+// =============================================================================
+// Context Usage Estimator Tests
+// =============================================================================
+import { UsageEstimator, MODEL_CONTEXT_LIMITS } from './usage-estimator.js';
+describe('UsageEstimator', () => {
+    let estimator;
+    beforeEach(() => {
+        estimator = new UsageEstimator();
+    });
+    describe('estimateTokens', () => {
+        it('should estimate tokens using ~4 chars = 1 token', () => {
+            // Empty string
+            expect(estimator.estimateTokens('')).toBe(0);
+            // 4 characters = 1 token
+            expect(estimator.estimateTokens('test')).toBe(1);
+            // 8 characters = 2 tokens
+            expect(estimator.estimateTokens('test123!')).toBe(2);
+            // 100 characters = 25 tokens
+            const text100 = 'a'.repeat(100);
+            expect(estimator.estimateTokens(text100)).toBe(25);
+            // 1000 characters = 250 tokens
+            const text1000 = 'a'.repeat(1000);
+            expect(estimator.estimateTokens(text1000)).toBe(250);
+        });
+        it('should round up partial tokens', () => {
+            // 5 characters = 2 tokens (rounded up from 1.25)
+            expect(estimator.estimateTokens('hello')).toBe(2);
+            // 7 characters = 2 tokens (rounded up from 1.75)
+            expect(estimator.estimateTokens('testing')).toBe(2);
+        });
+    });
+    describe('trackInjection', () => {
+        it('should track injected context tokens', () => {
+            estimator.trackInjection(100);
+            expect(estimator.getCurrentUsage().injectedTokens).toBe(100);
+            expect(estimator.getCurrentUsage().totalEstimated).toBe(100);
+            estimator.trackInjection(50);
+            expect(estimator.getCurrentUsage().injectedTokens).toBe(150);
+            expect(estimator.getCurrentUsage().totalEstimated).toBe(150);
+        });
+    });
+    describe('trackToolOutput', () => {
+        it('should track tool output tokens', () => {
+            estimator.trackToolOutput(200);
+            expect(estimator.getCurrentUsage().toolOutputTokens).toBe(200);
+            expect(estimator.getCurrentUsage().totalEstimated).toBe(200);
+            estimator.trackToolOutput(100);
+            expect(estimator.getCurrentUsage().toolOutputTokens).toBe(300);
+            expect(estimator.getCurrentUsage().totalEstimated).toBe(300);
+        });
+    });
+    describe('trackExchange', () => {
+        it('should track user and assistant tokens', () => {
+            estimator.trackExchange(50, 150);
+            const usage = estimator.getCurrentUsage();
+            expect(usage.userTokens).toBe(50);
+            expect(usage.assistantTokens).toBe(150);
+            expect(usage.totalEstimated).toBe(200);
+        });
+        it('should accumulate multiple exchanges', () => {
+            estimator.trackExchange(50, 150);
+            estimator.trackExchange(30, 100);
+            const usage = estimator.getCurrentUsage();
+            expect(usage.userTokens).toBe(80);
+            expect(usage.assistantTokens).toBe(250);
+            expect(usage.totalEstimated).toBe(330);
+        });
+    });
+    describe('getEstimatedFill', () => {
+        it('should calculate fill percentage correctly', () => {
+            const limit = MODEL_CONTEXT_LIMITS.SONNET; // 200k
+            // 0 tokens = 0%
+            expect(estimator.getEstimatedFill(limit)).toBe(0);
+            // 100k tokens = 50%
+            estimator.trackInjection(100_000);
+            expect(estimator.getEstimatedFill(limit)).toBe(50);
+            // 200k tokens = 100%
+            estimator.trackToolOutput(100_000);
+            expect(estimator.getEstimatedFill(limit)).toBe(100);
+        });
+        it('should cap at 100% for over-limit usage', () => {
+            const limit = MODEL_CONTEXT_LIMITS.SONNET;
+            // 250k tokens (exceeds 200k limit)
+            estimator.trackInjection(250_000);
+            expect(estimator.getEstimatedFill(limit)).toBe(100);
+        });
+        it('should handle custom model limits', () => {
+            const customLimit = 100_000;
+            estimator.trackInjection(50_000);
+            expect(estimator.getEstimatedFill(customLimit)).toBe(50);
+            estimator.trackToolOutput(30_000);
+            expect(estimator.getEstimatedFill(customLimit)).toBe(80);
+        });
+    });
+    describe('isApproachingLimit', () => {
+        it('should detect when approaching limit', () => {
+            const limit = MODEL_CONTEXT_LIMITS.SONNET;
+            // Under threshold (80%)
+            estimator.trackInjection(150_000); // 75%
+            expect(estimator.isApproachingLimit(80, limit)).toBe(false);
+            // At threshold
+            estimator.trackToolOutput(10_000); // 80%
+            expect(estimator.isApproachingLimit(80, limit)).toBe(true);
+            // Over threshold
+            estimator.trackUserMessage(20_000); // 90%
+            expect(estimator.isApproachingLimit(80, limit)).toBe(true);
+        });
+        it('should support custom thresholds', () => {
+            const limit = MODEL_CONTEXT_LIMITS.SONNET;
+            estimator.trackInjection(100_000); // 50%
+            expect(estimator.isApproachingLimit(40, limit)).toBe(true);
+            expect(estimator.isApproachingLimit(60, limit)).toBe(false);
+        });
+    });
+    describe('getRemainingBudget', () => {
+        it('should calculate remaining token budget', () => {
+            const limit = MODEL_CONTEXT_LIMITS.SONNET;
+            // Full budget available
+            expect(estimator.getRemainingBudget(limit)).toBe(200_000);
+            // 50k used, 150k remaining
+            estimator.trackInjection(50_000);
+            expect(estimator.getRemainingBudget(limit)).toBe(150_000);
+            // 200k used, 0 remaining
+            estimator.trackToolOutput(150_000);
+            expect(estimator.getRemainingBudget(limit)).toBe(0);
+        });
+        it('should not return negative budget', () => {
+            const limit = MODEL_CONTEXT_LIMITS.SONNET;
+            // Exceed limit
+            estimator.trackInjection(250_000);
+            expect(estimator.getRemainingBudget(limit)).toBe(0);
+        });
+    });
+    describe('reset', () => {
+        it('should reset all usage tracking', () => {
+            estimator.trackInjection(100);
+            estimator.trackToolOutput(200);
+            estimator.trackExchange(50, 150);
+            expect(estimator.getCurrentUsage().totalEstimated).toBe(500);
+            estimator.reset();
+            const usage = estimator.getCurrentUsage();
+            expect(usage.injectedTokens).toBe(0);
+            expect(usage.toolOutputTokens).toBe(0);
+            expect(usage.userTokens).toBe(0);
+            expect(usage.assistantTokens).toBe(0);
+            expect(usage.totalEstimated).toBe(0);
+            expect(estimator.getHistory()).toHaveLength(0);
+        });
+    });
+    describe('history tracking', () => {
+        it('should maintain usage history', () => {
+            estimator.trackInjection(100);
+            estimator.trackToolOutput(200);
+            estimator.trackExchange(50, 150);
+            const history = estimator.getHistory();
+            expect(history.length).toBeGreaterThan(0);
+            // Each snapshot should have required fields
+            history.forEach(snapshot => {
+                expect(snapshot).toHaveProperty('timestamp');
+                expect(snapshot).toHaveProperty('usage');
+                expect(snapshot).toHaveProperty('fillPercentage');
+                expect(snapshot).toHaveProperty('modelLimit');
+            });
+        });
+        it('should limit history size', () => {
+            const smallEstimator = new UsageEstimator(5);
+            // Add more snapshots than max size
+            for (let i = 0; i < 10; i++) {
+                smallEstimator.trackInjection(10);
+            }
+            const history = smallEstimator.getHistory();
+            expect(history.length).toBeLessThanOrEqual(5);
+        });
+    });
+    describe('integration scenario', () => {
+        it('should track realistic conversation flow', () => {
+            const limit = MODEL_CONTEXT_LIMITS.SONNET;
+            // Initial context injection (SessionStart)
+            const sessionContext = 'System instructions and context...'.repeat(100);
+            estimator.trackInjection(estimator.estimateTokens(sessionContext));
+            // User message with context injection
+            const userMessage = 'Help me debug this code...'.repeat(50);
+            estimator.trackUserMessage(estimator.estimateTokens(userMessage));
+            const contextInjection = 'Relevant memory facts...'.repeat(200);
+            estimator.trackInjection(estimator.estimateTokens(contextInjection));
+            // Tool calls and outputs
+            estimator.trackToolOutput(estimator.estimateTokens('Tool output...'.repeat(100)));
+            // Assistant response
+            const assistantResponse = 'Here is the solution...'.repeat(300);
+            estimator.trackAssistantMessage(estimator.estimateTokens(assistantResponse));
+            // Verify tracking
+            const usage = estimator.getCurrentUsage();
+            expect(usage.totalEstimated).toBeGreaterThan(0);
+            expect(usage.injectedTokens).toBeGreaterThan(0);
+            expect(usage.toolOutputTokens).toBeGreaterThan(0);
+            expect(usage.userTokens).toBeGreaterThan(0);
+            expect(usage.assistantTokens).toBeGreaterThan(0);
+            // Should not be near limit yet
+            expect(estimator.isApproachingLimit(80, limit)).toBe(false);
+            // Fill percentage should be reasonable
+            const fill = estimator.getEstimatedFill(limit);
+            expect(fill).toBeGreaterThan(0);
+            expect(fill).toBeLessThan(20); // Should be well under 20%
+            // Should have remaining budget
+            expect(estimator.getRemainingBudget(limit)).toBeGreaterThan(150_000);
+        });
+    });
+});

package/dist/context-cli.d.ts

@@ -0,0 +1,16 @@
+/**
+ * claudetools context status - Show current session context usage
+ */
+export declare function contextStatus(args: string[]): Promise<void>;
+/**
+ * claudetools context evict - Manually trigger eviction cycle
+ */
+export declare function contextEvict(args: string[]): Promise<void>;
+/**
+ * claudetools context summarise - Summarise and compress exchanges
+ */
+export declare function contextSummarise(args: string[]): Promise<void>;
+/**
+ * claudetools context reset - Clear session state
+ */
+export declare function contextReset(args: string[]): Promise<void>;