@jshookmcp/jshook 0.2.5 → 0.2.7

package/dist/src/utils/TokenBudgetManager.js

@@ -1,331 +0,0 @@
-import { logger } from './logger.js';
-import { TOKEN_BUDGET_MAX_TOKENS } from '../constants.js';
-export class TokenBudgetManager {
-    static instance;
-    MAX_TOKENS = TOKEN_BUDGET_MAX_TOKENS;
-    WARNING_THRESHOLDS = [0.8, 0.9, 0.95];
-    BYTES_PER_TOKEN = 4;
-    AUTO_CLEANUP_THRESHOLD = 0.9;
-    HISTORY_RETENTION = 5 * 60 * 1000;
-    currentUsage = 0;
-    toolCallHistory = [];
-    warnings = new Set();
-    sessionStartTime = Date.now();
-    trackingEnabled = true;
-    MAX_ESTIMATION_DEPTH = 4;
-    MAX_ESTIMATION_ARRAY_ITEMS = 50;
-    MAX_ESTIMATION_OBJECT_KEYS = 50;
-    MAX_ESTIMATION_STRING_LENGTH = 2000;
-    MAX_ESTIMATION_BYTES = 256 * 1024;
-    externalCleanupFn = null;
-    constructor() {
-        logger.info('TokenBudgetManager initialized');
-    }
-    static getInstance() {
-        if (!this.instance) {
-            this.instance = new TokenBudgetManager();
-        }
-        return this.instance;
-    }
-    setExternalCleanup(fn) {
-        this.externalCleanupFn = fn;
-    }
-    recordToolCall(toolName, request, response) {
-        if (!this.trackingEnabled) {
-            return;
-        }
-        try {
-            const requestSize = this.calculateSize(request);
-            const responseSize = this.calculateSize(response);
-            const totalSize = requestSize + responseSize;
-            const estimatedTokens = this.estimateTokens(totalSize);
-            this.currentUsage += estimatedTokens;
-            const record = {
-                toolName,
-                timestamp: Date.now(),
-                requestSize,
-                responseSize,
-                estimatedTokens,
-                cumulativeTokens: this.currentUsage,
-            };
-            this.toolCallHistory.push(record);
-            logger.debug(`Token usage: ${this.currentUsage}/${this.MAX_TOKENS} (${this.getUsagePercentage()}%) | ` +
-                `Tool: ${toolName} | Size: ${(totalSize / 1024).toFixed(1)}KB | Tokens: ${estimatedTokens}`);
-            this.checkWarnings();
-            if (this.shouldAutoCleanup()) {
-                this.autoCleanup();
-            }
-        }
-        catch (error) {
-            logger.error('Failed to record tool call:', error);
-        }
-    }
-    isRecord(value) {
-        return value !== null && typeof value === 'object';
-    }
-    hasDetailedSummarySize(value) {
-        if (!this.isRecord(value) || !('detailId' in value)) {
-            return false;
-        }
-        const summary = value.summary;
-        if (!this.isRecord(summary)) {
-            return false;
-        }
-        const { size } = summary;
-        return typeof size === 'number' && Number.isFinite(size) && size > 0;
-    }
-    tryEstimateMcpEnvelope(data) {
-        if (!this.isRecord(data))
-            return null;
-        const content = data['content'];
-        if (!Array.isArray(content) || content.length === 0)
-            return null;
-        const first = content[0];
-        if (!this.isRecord(first))
-            return null;
-        if (first['type'] !== 'text' || typeof first['text'] !== 'string')
-            return null;
-        const text = first['text'];
-        const truncated = text.length > this.MAX_ESTIMATION_STRING_LENGTH
-            ? `${text.slice(0, this.MAX_ESTIMATION_STRING_LENGTH)}...[truncated:${text.length}]`
-            : text;
-        const overhead = 42 + (data['isError'] === true ? 14 : 0);
-        const textBytes = Buffer.byteLength(truncated, 'utf8');
-        return Math.min(overhead + textBytes, this.MAX_ESTIMATION_BYTES);
-    }
-    calculateSize(data) {
-        try {
-            if (this.hasDetailedSummarySize(data)) {
-                return Math.min(data.summary.size, this.MAX_ESTIMATION_BYTES);
-            }
-            const mcpSize = this.tryEstimateMcpEnvelope(data);
-            if (mcpSize !== null)
-                return mcpSize;
-            const normalized = this.normalizeForSizeEstimate(data, 0, new WeakSet());
-            const serialized = JSON.stringify(normalized);
-            if (!serialized) {
-                return 0;
-            }
-            return Math.min(Buffer.byteLength(serialized, 'utf8'), this.MAX_ESTIMATION_BYTES);
-        }
-        catch (error) {
-            logger.warn('Failed to calculate data size:', error);
-            return 0;
-        }
-    }
-    normalizeForSizeEstimate(value, depth, seen) {
-        if (value === null || value === undefined) {
-            return value;
-        }
-        const valueType = typeof value;
-        if (valueType === 'boolean' || valueType === 'number') {
-            return value;
-        }
-        if (valueType === 'string') {
-            const stringValue = value;
-            return stringValue.length > this.MAX_ESTIMATION_STRING_LENGTH
-                ? `${stringValue.slice(0, this.MAX_ESTIMATION_STRING_LENGTH)}...[truncated:${stringValue.length}]`
-                : stringValue;
-        }
-        if (valueType === 'bigint') {
-            return value.toString();
-        }
-        if (valueType === 'symbol') {
-            return value.toString();
-        }
-        if (valueType === 'function') {
-            return '[Function]';
-        }
-        if (value instanceof Error) {
-            return {
-                name: value.name,
-                message: value.message,
-                stack: value.stack?.slice(0, this.MAX_ESTIMATION_STRING_LENGTH),
-            };
-        }
-        if (Buffer.isBuffer(value)) {
-            return `[Buffer:${value.byteLength}]`;
-        }
-        if (depth >= this.MAX_ESTIMATION_DEPTH) {
-            if (Array.isArray(value)) {
-                return `[Array:${value.length}]`;
-            }
-            return '[Object]';
-        }
-        if (Array.isArray(value)) {
-            const limited = value
-                .slice(0, this.MAX_ESTIMATION_ARRAY_ITEMS)
-                .map((item) => this.normalizeForSizeEstimate(item, depth + 1, seen));
-            if (value.length > this.MAX_ESTIMATION_ARRAY_ITEMS) {
-                limited.push(`[truncated:${value.length - this.MAX_ESTIMATION_ARRAY_ITEMS}]`);
-            }
-            return limited;
-        }
-        if (valueType === 'object') {
-            if (!this.isRecord(value)) {
-                return '[Object]';
-            }
-            if (seen.has(value)) {
-                return '[Circular]';
-            }
-            seen.add(value);
-            const entries = Object.entries(value);
-            const limitedEntries = entries.slice(0, this.MAX_ESTIMATION_OBJECT_KEYS);
-            const out = {};
-            for (const [key, nestedValue] of limitedEntries) {
-                out[key] = this.normalizeForSizeEstimate(nestedValue, depth + 1, seen);
-            }
-            if (entries.length > this.MAX_ESTIMATION_OBJECT_KEYS) {
-                out.__truncatedKeys = entries.length - this.MAX_ESTIMATION_OBJECT_KEYS;
-            }
-            return out;
-        }
-        return String(value);
-    }
-    estimateTokens(bytes) {
-        return Math.ceil(bytes / this.BYTES_PER_TOKEN);
-    }
-    getUsagePercentage() {
-        return Math.round((this.currentUsage / this.MAX_TOKENS) * 100);
-    }
-    checkWarnings() {
-        const ratio = this.currentUsage / this.MAX_TOKENS;
-        for (const threshold of this.WARNING_THRESHOLDS) {
-            if (ratio >= threshold && !this.warnings.has(threshold)) {
-                this.emitWarning(threshold);
-                this.warnings.add(threshold);
-            }
-        }
-    }
-    emitWarning(threshold) {
-        const percentage = Math.round(threshold * 100);
-        const remaining = this.MAX_TOKENS - this.currentUsage;
-        logger.warn(`Token Budget Warning: ${percentage}% used! ` +
-            `(${this.currentUsage}/${this.MAX_TOKENS}, ${remaining} tokens remaining)`);
-        if (threshold >= 0.95) {
-            logger.warn('CRITICAL: Consider clearing caches or starting a new session.');
-        }
-        else if (threshold >= 0.9) {
-            logger.warn('HIGH: Auto-cleanup will trigger soon. Consider using summary modes.');
-        }
-        else if (threshold >= 0.8) {
-            logger.warn('MODERATE: Monitor usage. Use get_token_budget_stats for details.');
-        }
-    }
-    shouldAutoCleanup() {
-        const ratio = this.currentUsage / this.MAX_TOKENS;
-        return ratio >= this.AUTO_CLEANUP_THRESHOLD;
-    }
-    autoCleanup() {
-        logger.info('Auto-cleanup triggered at 90% usage.');
-        const beforeUsage = this.currentUsage;
-        if (this.externalCleanupFn) {
-            try {
-                this.externalCleanupFn();
-                logger.info('External cleanup callback invoked');
-            }
-            catch (e) {
-                logger.warn('External cleanup callback failed:', e);
-            }
-        }
-        const cutoff = Date.now() - this.HISTORY_RETENTION;
-        const beforeCount = this.toolCallHistory.length;
-        this.toolCallHistory = this.toolCallHistory.filter((call) => call.timestamp > cutoff);
-        const removedCount = beforeCount - this.toolCallHistory.length;
-        logger.info(`Removed ${removedCount} old tool call records`);
-        this.recalculateUsage();
-        const afterUsage = this.currentUsage;
-        const freed = beforeUsage - afterUsage;
-        const freedPercentage = Math.round((freed / this.MAX_TOKENS) * 100);
-        logger.info(`Cleanup complete. Freed ${freed} tokens (${freedPercentage}%). ` +
-            `Usage: ${afterUsage}/${this.MAX_TOKENS} (${this.getUsagePercentage()}%)`);
-        const newRatio = afterUsage / this.MAX_TOKENS;
-        this.warnings = new Set(Array.from(this.warnings).filter((threshold) => newRatio >= threshold));
-    }
-    recalculateUsage() {
-        this.currentUsage = this.toolCallHistory.reduce((sum, call) => sum + call.estimatedTokens, 0);
-    }
-    getStats() {
-        const toolUsage = new Map();
-        for (const call of this.toolCallHistory) {
-            const current = toolUsage.get(call.toolName) || 0;
-            toolUsage.set(call.toolName, current + call.estimatedTokens);
-        }
-        const topTools = Array.from(toolUsage.entries())
-            .map(([tool, tokens]) => ({
-            tool,
-            tokens,
-            percentage: Math.round((tokens / this.currentUsage) * 100),
-        }))
-            .toSorted((a, b) => b.tokens - a.tokens)
-            .slice(0, 10);
-        const suggestions = this.generateSuggestions(topTools);
-        const recentCalls = this.toolCallHistory.slice(-20);
-        return {
-            currentUsage: this.currentUsage,
-            maxTokens: this.MAX_TOKENS,
-            usagePercentage: this.getUsagePercentage(),
-            toolCallCount: this.toolCallHistory.length,
-            topTools,
-            warnings: Array.from(this.warnings).map((t) => Math.round(t * 100)),
-            recentCalls,
-            suggestions,
-            sessionStartTime: this.sessionStartTime,
-        };
-    }
-    generateSuggestions(topTools) {
-        const suggestions = [];
-        const ratio = this.currentUsage / this.MAX_TOKENS;
-        if (ratio >= 0.95) {
-            suggestions.push(' CRITICAL: Clear all caches immediately or start a new session');
-        }
-        else if (ratio >= 0.9) {
-            suggestions.push('HIGH: Auto-cleanup triggered. Consider manual cleanup for better control');
-        }
-        else if (ratio >= 0.8) {
-            suggestions.push('MODERATE: Monitor usage closely. Use summary modes for large data');
-        }
-        for (const { tool, percentage } of topTools) {
-            if (percentage > 30) {
-                if (tool.includes('collect_code')) {
-                    suggestions.push(` ${tool} uses ${percentage}% tokens. Try smartMode="summary" or "priority"`);
-                }
-                else if (tool.includes('get_script_source')) {
-                    suggestions.push(` ${tool} uses ${percentage}% tokens. Try preview=true first`);
-                }
-                else if (tool.includes('network_get_requests')) {
-                    suggestions.push(` ${tool} uses ${percentage}% tokens. Reduce limit or use filters`);
-                }
-                else if (tool.includes('page_evaluate')) {
-                    suggestions.push(` ${tool} uses ${percentage}% tokens. Query specific properties instead of full objects`);
-                }
-            }
-        }
-        if (suggestions.length === 0) {
-            suggestions.push(' Token usage is healthy. Continue monitoring.');
-        }
-        return suggestions;
-    }
-    manualCleanup() {
-        logger.info('Manual cleanup requested.');
-        this.autoCleanup();
-    }
-    setTrackingEnabled(enabled) {
-        if (this.trackingEnabled === enabled) {
-            return;
-        }
-        this.trackingEnabled = enabled;
-        logger.warn(`Token budget tracking ${enabled ? 'enabled' : 'disabled'}`);
-    }
-    isTrackingEnabled() {
-        return this.trackingEnabled;
-    }
-    reset() {
-        logger.info('Resetting token budget...');
-        this.currentUsage = 0;
-        this.toolCallHistory = [];
-        this.warnings.clear();
-        this.sessionStartTime = Date.now();
-        logger.info('Token budget reset complete');
-    }
-}

package/dist/src/utils/UnifiedCacheManager.d.ts

@@ -1,54 +0,0 @@
-export interface CacheInstance {
-    name: string;
-    getStats(): CacheStats | Promise<CacheStats>;
-    cleanup?(): Promise<void> | void;
-    clear?(): Promise<void> | void;
-}
-export interface CacheStats {
-    entries: number;
-    size: number;
-    hits?: number;
-    misses?: number;
-    hitRate?: number;
-    ttl?: number;
-    maxSize?: number;
-}
-export interface GlobalCacheStats {
-    totalEntries: number;
-    totalSize: number;
-    totalSizeMB: string;
-    hitRate: number;
-    caches: Array<{
-        name: string;
-        entries: number;
-        size: number;
-        sizeMB: string;
-        hitRate?: number;
-        ttl?: number;
-    }>;
-    recommendations: string[];
-}
-export declare class UnifiedCacheManager {
-    protected static instance: UnifiedCacheManager;
-    private readonly GLOBAL_MAX_SIZE;
-    private readonly LOW_HIT_RATE_THRESHOLD;
-    private caches;
-    constructor();
-    static getInstance(): UnifiedCacheManager;
-    registerCache(cache: CacheInstance): void;
-    unregisterCache(name: string): void;
-    getGlobalStats(): Promise<GlobalCacheStats>;
-    smartCleanup(targetSize?: number): Promise<{
-        before: number;
-        after: number;
-        freed: number;
-        freedPercentage: number;
-    }>;
-    private cleanupExpired;
-    private cleanupLowHitRate;
-    private cleanupLargeItems;
-    private calculateCleanupResult;
-    clearAll(): Promise<void>;
-    preheat(urls: string[]): Promise<void>;
-    private generateRecommendations;
-}

package/dist/src/utils/UnifiedCacheManager.js

@@ -1,205 +0,0 @@
-import { logger } from './logger.js';
-import { CACHE_GLOBAL_MAX_SIZE_BYTES, CACHE_LOW_HIT_RATE_THRESHOLD } from '../constants.js';
-export class UnifiedCacheManager {
-    static instance;
-    GLOBAL_MAX_SIZE = CACHE_GLOBAL_MAX_SIZE_BYTES;
-    LOW_HIT_RATE_THRESHOLD = CACHE_LOW_HIT_RATE_THRESHOLD;
-    caches = new Map();
-    constructor() {
-        logger.info('UnifiedCacheManager initialized');
-    }
-    static getInstance() {
-        if (!this.instance) {
-            this.instance = new UnifiedCacheManager();
-        }
-        return this.instance;
-    }
-    registerCache(cache) {
-        this.caches.set(cache.name, cache);
-        logger.info(`Registered cache: ${cache.name}`);
-    }
-    unregisterCache(name) {
-        this.caches.delete(name);
-        logger.info(`Unregistered cache: ${name}`);
-    }
-    async getGlobalStats() {
-        let totalEntries = 0;
-        let totalSize = 0;
-        let totalHits = 0;
-        let totalMisses = 0;
-        const cacheStats = [];
-        for (const [name, cache] of this.caches) {
-            try {
-                const stats = await cache.getStats();
-                totalEntries += stats.entries;
-                totalSize += stats.size;
-                totalHits += stats.hits || 0;
-                totalMisses += stats.misses || 0;
-                cacheStats.push({
-                    name,
-                    entries: stats.entries,
-                    size: stats.size,
-                    sizeMB: (stats.size / 1024 / 1024).toFixed(2),
-                    hitRate: stats.hitRate,
-                    ttl: stats.ttl,
-                });
-            }
-            catch (error) {
-                logger.error(`Failed to get stats for cache ${name}:`, error);
-            }
-        }
-        const hitRate = totalHits + totalMisses > 0 ? totalHits / (totalHits + totalMisses) : 0;
-        const recommendations = this.generateRecommendations(totalSize, hitRate, cacheStats);
-        return {
-            totalEntries,
-            totalSize,
-            totalSizeMB: (totalSize / 1024 / 1024).toFixed(2),
-            hitRate,
-            caches: cacheStats,
-            recommendations,
-        };
-    }
-    async smartCleanup(targetSize) {
-        const target = targetSize || this.GLOBAL_MAX_SIZE * 0.7;
-        const beforeStats = await this.getGlobalStats();
-        const beforeSize = beforeStats.totalSize;
-        if (beforeSize <= target) {
-            logger.info('No cleanup needed');
-            return {
-                before: beforeSize,
-                after: beforeSize,
-                freed: 0,
-                freedPercentage: 0,
-            };
-        }
-        logger.info(`Smart cleanup: current ${beforeStats.totalSizeMB}MB, ` +
-            `target ${(target / 1024 / 1024).toFixed(2)}MB`);
-        await this.cleanupExpired();
-        let currentStats = await this.getGlobalStats();
-        if (currentStats.totalSize <= target) {
-            return this.calculateCleanupResult(beforeSize, currentStats.totalSize);
-        }
-        await this.cleanupLowHitRate();
-        currentStats = await this.getGlobalStats();
-        if (currentStats.totalSize <= target) {
-            return this.calculateCleanupResult(beforeSize, currentStats.totalSize);
-        }
-        await this.cleanupLargeItems();
-        const afterStats = await this.getGlobalStats();
-        return this.calculateCleanupResult(beforeSize, afterStats.totalSize);
-    }
-    async cleanupExpired() {
-        logger.info('Cleaning up expired data...');
-        for (const [name, cache] of this.caches) {
-            if (cache.cleanup) {
-                try {
-                    await cache.cleanup();
-                    logger.debug(`Cleaned up expired data in ${name}`);
-                }
-                catch (error) {
-                    logger.error(`Failed to cleanup ${name}:`, error);
-                }
-            }
-        }
-    }
-    async cleanupLowHitRate() {
-        logger.info('Cleaning up low hit rate caches...');
-        const stats = await this.getGlobalStats();
-        const avgHitRate = stats.hitRate;
-        for (const cacheStats of stats.caches) {
-            if (cacheStats.hitRate !== undefined &&
-                cacheStats.hitRate < avgHitRate * this.LOW_HIT_RATE_THRESHOLD) {
-                const cache = this.caches.get(cacheStats.name);
-                if (cache?.clear) {
-                    try {
-                        await cache.clear();
-                        logger.info(`Cleared low hit rate cache: ${cacheStats.name} (${(cacheStats.hitRate * 100).toFixed(1)}%)`);
-                    }
-                    catch (error) {
-                        logger.error(`Failed to clear ${cacheStats.name}:`, error);
-                    }
-                }
-            }
-        }
-    }
-    async cleanupLargeItems() {
-        logger.info('Cleaning up large caches...');
-        const stats = await this.getGlobalStats();
-        const sortedCaches = stats.caches.toSorted((a, b) => b.size - a.size);
-        for (const cacheStats of sortedCaches.slice(0, 2)) {
-            const cache = this.caches.get(cacheStats.name);
-            if (cache?.clear) {
-                try {
-                    await cache.clear();
-                    logger.info(`Cleared large cache: ${cacheStats.name} (${cacheStats.sizeMB}MB)`);
-                }
-                catch (error) {
-                    logger.error(`Failed to clear ${cacheStats.name}:`, error);
-                }
-            }
-        }
-    }
-    calculateCleanupResult(before, after) {
-        const freed = before - after;
-        const freedPercentage = Math.round((freed / this.GLOBAL_MAX_SIZE) * 100);
-        logger.info(`Cleanup complete! Freed ${(freed / 1024 / 1024).toFixed(2)}MB (${freedPercentage}%). ` +
-            `Usage: ${(after / 1024 / 1024).toFixed(2)}MB/${(this.GLOBAL_MAX_SIZE / 1024 / 1024).toFixed(0)}MB`);
-        return {
-            before,
-            after,
-            freed,
-            freedPercentage,
-        };
-    }
-    async clearAll() {
-        logger.info('Clearing all caches...');
-        for (const [name, cache] of this.caches) {
-            if (cache.clear) {
-                try {
-                    await cache.clear();
-                    logger.info(`Cleared cache: ${name}`);
-                }
-                catch (error) {
-                    logger.error(`Failed to clear ${name}:`, error);
-                }
-            }
-        }
-        logger.success('All caches cleared');
-    }
-    async preheat(urls) {
-        logger.info(`Preheating cache for ${urls.length} URLs...`);
-        logger.info('Cache preheat completed');
-    }
-    generateRecommendations(totalSize, hitRate, cacheStats) {
-        const recommendations = [];
-        const sizeRatio = totalSize / this.GLOBAL_MAX_SIZE;
-        if (sizeRatio >= 0.9) {
-            recommendations.push(' CRITICAL: Cache size at 90%. Run smart_cache_cleanup immediately!');
-        }
-        else if (sizeRatio >= 0.7) {
-            recommendations.push('WARNING: Cache size at 70%. Consider cleanup soon.');
-        }
-        else if (sizeRatio >= 0.5) {
-            recommendations.push('INFO: Cache size at 50%. Monitor usage.');
-        }
-        if (hitRate < 0.3) {
-            recommendations.push(' Low cache hit rate (<30%). Consider adjusting TTL or cache strategy.');
-        }
-        else if (hitRate > 0.7) {
-            recommendations.push(' Good cache hit rate (>70%). Cache is working well.');
-        }
-        for (const cache of cacheStats) {
-            const cacheRatio = cache.size / totalSize;
-            if (cacheRatio > 0.5) {
-                recommendations.push(` ${cache.name} uses ${Math.round(cacheRatio * 100)}% of total cache. Consider cleanup.`);
-            }
-            if (cache.hitRate !== undefined && cache.hitRate < 0.2) {
-                recommendations.push(` ${cache.name} has low hit rate (${(cache.hitRate * 100).toFixed(1)}%). Consider disabling or adjusting.`);
-            }
-        }
-        if (recommendations.length === 0) {
-            recommendations.push(' Cache health is good. No action needed.');
-        }
-        return recommendations;
-    }
-}

package/dist/src/utils/WorkerPool.d.ts

@@ -1,38 +0,0 @@
-import { type ResourceLimits } from 'node:worker_threads';
-export interface WorkerPoolOptions {
-    name?: string;
-    workerScript: string;
-    minWorkers?: number;
-    maxWorkers?: number;
-    idleTimeoutMs?: number;
-    resourceLimits?: ResourceLimits;
-}
-export declare class WorkerPool<TPayload extends Record<string, unknown>, TResult> {
-    private readonly name;
-    private readonly workerScript;
-    private readonly minWorkers;
-    private readonly maxWorkers;
-    private readonly idleTimeoutMs;
-    private readonly resourceLimits?;
-    private readonly workers;
-    private readonly queuedJobs;
-    private readonly activeJobs;
-    private nextWorkerId;
-    private nextJobId;
-    private closed;
-    constructor(options: WorkerPoolOptions);
-    submit(payload: TPayload, timeoutMs?: number): Promise<TResult>;
-    close(): Promise<void>;
-    private ensureMinWorkers;
-    private pumpQueue;
-    private findIdleWorker;
-    private spawnWorker;
-    private dispatchJob;
-    private handleWorkerMessage;
-    private handleWorkerFailure;
-    private handleWorkerExit;
-    private handleJobTimeout;
-    private armIdleTimer;
-    private terminateWorker;
-    private toError;
-}