@jshookmcp/jshook 0.2.6 → 0.2.8

package/dist/src/utils/RingBuffer.js

@@ -1,74 +0,0 @@
-export class RingBuffer {
-    capacity;
-    buf;
-    head = 0;
-    tail = 0;
-    count = 0;
-    constructor(capacity) {
-        this.capacity = capacity;
-        this.buf = Array.from({ length: capacity });
-    }
-    get length() {
-        return this.count;
-    }
-    push(item) {
-        if (this.count === this.buf.length) {
-            if (this.buf.length < this.capacity) {
-                this.grow();
-            }
-            else {
-                this.buf[this.tail] = item;
-                this.tail = (this.tail + 1) % this.buf.length;
-                this.head = (this.head + 1) % this.buf.length;
-                return;
-            }
-        }
-        this.buf[this.tail] = item;
-        this.tail = (this.tail + 1) % this.buf.length;
-        this.count++;
-    }
-    shift() {
-        if (this.count === 0)
-            return undefined;
-        const item = this.buf[this.head];
-        this.buf[this.head] = undefined;
-        this.head = (this.head + 1) % this.buf.length;
-        this.count--;
-        return item;
-    }
-    clear() {
-        this.buf = Array.from({ length: Math.min(64, this.capacity) });
-        this.head = 0;
-        this.tail = 0;
-        this.count = 0;
-    }
-    *[Symbol.iterator]() {
-        for (let i = 0; i < this.count; i++) {
-            yield this.buf[(this.head + i) % this.buf.length];
-        }
-    }
-    toArray() {
-        const result = Array.from({ length: this.count });
-        for (let i = 0; i < this.count; i++) {
-            result[i] = this.buf[(this.head + i) % this.buf.length];
-        }
-        return result;
-    }
-    map(fn) {
-        const result = Array.from({ length: this.count });
-        for (let i = 0; i < this.count; i++) {
-            result[i] = fn(this.buf[(this.head + i) % this.buf.length], i);
-        }
-        return result;
-    }
-    grow() {
-        const newSize = Math.min(this.buf.length * 2, this.capacity);
-        const newBuf = Array.from({ length: newSize });
-        for (let i = 0; i < this.count; i++) {
-            newBuf[i] = this.buf[(this.head + i) % this.buf.length];
-        }
-        this.buf = newBuf;
-        this.head = 0;
-        this.tail = this.count;
-    }
-}

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

@@ -1,66 +0,0 @@
-export interface ToolCallRecord {
-    toolName: string;
-    timestamp: number;
-    requestSize: number;
-    responseSize: number;
-    estimatedTokens: number;
-    cumulativeTokens: number;
-}
-export interface TokenBudgetStats {
-    currentUsage: number;
-    maxTokens: number;
-    usagePercentage: number;
-    toolCallCount: number;
-    topTools: Array<{
-        tool: string;
-        tokens: number;
-        percentage: number;
-    }>;
-    warnings: number[];
-    recentCalls: ToolCallRecord[];
-    suggestions: string[];
-}
-export type ExternalCleanupFn = () => void;
-export declare class TokenBudgetManager {
-    private static instance;
-    private readonly MAX_TOKENS;
-    private readonly WARNING_THRESHOLDS;
-    private readonly BYTES_PER_TOKEN;
-    private readonly AUTO_CLEANUP_THRESHOLD;
-    private readonly HISTORY_RETENTION;
-    private currentUsage;
-    private toolCallHistory;
-    private warnings;
-    private sessionStartTime;
-    private trackingEnabled;
-    private readonly MAX_ESTIMATION_DEPTH;
-    private readonly MAX_ESTIMATION_ARRAY_ITEMS;
-    private readonly MAX_ESTIMATION_OBJECT_KEYS;
-    private readonly MAX_ESTIMATION_STRING_LENGTH;
-    private readonly MAX_ESTIMATION_BYTES;
-    private externalCleanupFn;
-    constructor();
-    static getInstance(): TokenBudgetManager;
-    setExternalCleanup(fn: ExternalCleanupFn): void;
-    recordToolCall(toolName: string, request: unknown, response: unknown): void;
-    private isRecord;
-    private hasDetailedSummarySize;
-    private tryEstimateMcpEnvelope;
-    private calculateSize;
-    private normalizeForSizeEstimate;
-    private estimateTokens;
-    getUsagePercentage(): number;
-    private checkWarnings;
-    private emitWarning;
-    private shouldAutoCleanup;
-    private autoCleanup;
-    private recalculateUsage;
-    getStats(): TokenBudgetStats & {
-        sessionStartTime: number;
-    };
-    private generateSuggestions;
-    manualCleanup(): void;
-    setTrackingEnabled(enabled: boolean): void;
-    isTrackingEnabled(): boolean;
-    reset(): void;
-}

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;
-}