@ooples/token-optimizer-mcp
Version:
Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters
461 lines • 14.2 kB
TypeScript
/**
* CacheWarmup - Intelligent Cache Pre-warming Tool
*
* Token Reduction Target: 87%+
*
* Features:
* - Schedule-based warming (cron-like)
* - Pattern-based warming from historical access
* - Dependency graph resolution
* - Parallel warming with concurrency control
* - Progressive warming (hot keys first)
* - Dry-run simulation mode
* - Rollback on failures
*
* Operations:
* 1. schedule - Schedule cache warming
* 2. immediate - Warm cache immediately
* 3. pattern-based - Warm based on access patterns
* 4. dependency-based - Warm with dependency resolution
* 5. selective - Warm specific keys/categories
* 6. status - Get warming status
*/
import { CacheEngine } from '../../core/cache-engine.js';
import { TokenCounter } from '../../core/token-counter.js';
import { MetricsCollector } from '../../core/metrics.js';
import { EventEmitter } from 'events';
export type WarmupStrategy = 'immediate' | 'progressive' | 'dependency' | 'pattern';
export type WarmupPriority = 'high' | 'normal' | 'low';
export type WarmupStatus = 'idle' | 'warming' | 'paused' | 'completed' | 'failed' | 'cancelled';
export interface CacheWarmupOptions {
operation: 'schedule' | 'immediate' | 'pattern-based' | 'dependency-based' | 'selective' | 'status' | 'cancel' | 'pause' | 'resume' | 'configure';
keys?: string[];
categories?: string[];
pattern?: string;
priority?: WarmupPriority;
strategy?: WarmupStrategy;
dataSource?: WarmupDataSource;
dataFetcher?: (key: string) => Promise<string>;
schedule?: string;
scheduleId?: string;
startTime?: number;
endTime?: number;
dependencies?: DependencyGraph;
resolveDependencies?: boolean;
accessHistory?: AccessHistoryEntry[];
minAccessCount?: number;
timeWindow?: number;
maxConcurrency?: number;
batchSize?: number;
delayBetweenBatches?: number;
hotKeyThreshold?: number;
warmupPercentage?: number;
dryRun?: boolean;
enableRollback?: boolean;
validateBeforeCommit?: boolean;
timeout?: number;
maxRetries?: number;
retryDelay?: number;
reportProgress?: boolean;
progressInterval?: number;
useCache?: boolean;
cacheTTL?: number;
}
export interface WarmupDataSource {
type: 'database' | 'api' | 'file' | 'cache' | 'custom';
connectionString?: string;
endpoint?: string;
filePath?: string;
customFetcher?: (key: string) => Promise<string>;
}
export interface DependencyGraph {
nodes: DependencyNode[];
edges: DependencyEdge[];
}
export interface DependencyNode {
key: string;
priority: number;
category?: string;
estimatedSize?: number;
}
export interface DependencyEdge {
from: string;
to: string;
type: 'required' | 'optional';
}
export interface AccessHistoryEntry {
key: string;
timestamp: number;
accessCount: number;
category?: string;
metadata?: Record<string, unknown>;
}
export interface WarmupSchedule {
id: string;
cronExpression: string;
options: CacheWarmupOptions;
enabled: boolean;
nextRun: number;
lastRun?: number;
status: 'active' | 'paused' | 'completed' | 'failed';
}
export interface WarmupProgress {
status: WarmupStatus;
totalKeys: number;
warmedKeys: number;
failedKeys: number;
skippedKeys: number;
currentKey?: string;
percentComplete: number;
startTime: number;
estimatedCompletion?: number;
elapsedTime: number;
throughput: number;
errors: WarmupError[];
}
export interface WarmupError {
key: string;
error: string;
timestamp: number;
retryCount: number;
}
export interface WarmupResult {
success: boolean;
operation: string;
data: {
progress?: WarmupProgress;
warmedKeys?: string[];
failedKeys?: string[];
skippedKeys?: string[];
schedule?: WarmupSchedule;
schedules?: WarmupSchedule[];
simulation?: SimulationResult;
configuration?: WarmupConfiguration;
};
metadata: {
tokensUsed: number;
tokensSaved: number;
cacheHit: boolean;
executionTime: number;
};
}
export interface SimulationResult {
estimatedKeys: number;
estimatedSize: number;
estimatedTime: number;
estimatedCost: number;
keysByPriority: {
high: number;
normal: number;
low: number;
};
dependencyLayers: number;
warnings: string[];
}
export interface WarmupConfiguration {
maxConcurrency: number;
batchSize: number;
defaultTimeout: number;
maxRetries: number;
enableRollback: boolean;
progressReporting: boolean;
}
/**
* CacheWarmup - Intelligent cache pre-warming with advanced scheduling and dependency resolution
*/
export declare class CacheWarmupTool extends EventEmitter {
private cache;
private tokenCounter;
private metrics;
private config;
private activeJobs;
private jobCounter;
private schedules;
private scheduleTimers;
private accessHistory;
private hotKeys;
private dependencyGraph;
private resolvedOrder;
private stats;
constructor(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector);
/**
* Main entry point for cache warmup operations
*/
run(options: CacheWarmupOptions): Promise<WarmupResult>;
/**
* Immediate cache warmup
*/
private immediateWarmup;
/**
* Schedule cache warmup with cron expression
*/
private scheduleWarmup;
/**
* Pattern-based warmup from access history
*/
private patternBasedWarmup;
/**
* Dependency-based warmup with graph resolution
*/
private dependencyBasedWarmup;
/**
* Selective warmup for specific keys/categories
*/
private selectiveWarmup;
/**
* Get warmup status
*/
private getStatus;
/**
* Cancel warmup job
*/
private cancelWarmup;
/**
* Pause warmup job
*/
private pauseWarmup;
/**
* Resume warmup job
*/
private resumeWarmup;
/**
* Configure warmup settings
*/
private configure;
/**
* Progressive warmup - warm hot keys first
*/
private progressiveWarmup;
/**
* Warmup with dependency resolution
*/
private warmupWithDependencies;
/**
* Warmup by pattern matching
*/
private warmupByPattern;
/**
* Parallel warmup with concurrency control
*/
private parallelWarmup;
/**
* Warm a batch of keys in parallel
*/
private warmBatchParallel;
/**
* Warm a single key
*/
private warmKey;
/**
* Fetch data for a key
*/
private fetchData;
/**
* Simulate warmup
*/
private simulateWarmup;
/**
* Rollback warmup changes
*/
private rollback;
/**
* Resolve dependencies in topological order
*/
private resolveDependencies;
/**
* Calculate dependency depth
*/
private calculateDependencyDepth;
/**
* Identify hot keys from access history
*/
private identifyHotKeys;
/**
* Sort keys by priority (hot keys first)
*/
private sortKeysByPriority;
/**
* Update access history
*/
private updateAccessHistory;
/**
* Update job progress
*/
private updateProgress;
/**
* Parse cron expression
*/
private parseCronExpression;
/**
* Calculate next run time from cron schedule
*/
private calculateNextRun;
/**
* Schedule next run
*/
private scheduleNextRun;
/**
* Execute scheduled warmup
*/
private executeSchedule;
/**
* Cancel schedule
*/
private cancelSchedule;
/**
* Generate unique job ID
*/
private generateJobId;
/**
* Generate unique schedule ID
*/
private generateScheduleId;
/**
* Sleep for specified duration
*/
private sleep;
/**
* Execute promise with timeout
*/
private withTimeout;
/**
* Check if operation is cacheable
*/
private isCacheableOperation;
/**
* Get cache key parameters
*/
private getCacheKeyParams;
/**
* Cleanup and dispose
*/
dispose(): void;
}
export declare function getCacheWarmupTool(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector): CacheWarmupTool;
export declare const CACHE_WARMUP_TOOL_DEFINITION: {
readonly name: "cache_warmup";
readonly description: "Intelligent cache pre-warming with 87%+ token reduction, featuring schedule-based warming, pattern analysis, dependency resolution, and progressive warming strategies";
readonly inputSchema: {
readonly type: "object";
readonly properties: {
readonly operation: {
readonly type: "string";
readonly enum: readonly ["schedule", "immediate", "pattern-based", "dependency-based", "selective", "status", "cancel", "pause", "resume", "configure"];
readonly description: "The warmup operation to perform";
};
readonly keys: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Keys to warm (for immediate/selective operations)";
};
readonly categories: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Categories to warm (for selective operation)";
};
readonly pattern: {
readonly type: "string";
readonly description: "Regex pattern for key matching";
};
readonly priority: {
readonly type: "string";
readonly enum: readonly ["high", "normal", "low"];
readonly description: "Warmup priority (default: normal)";
};
readonly strategy: {
readonly type: "string";
readonly enum: readonly ["immediate", "progressive", "dependency", "pattern"];
readonly description: "Warmup strategy (default: progressive)";
};
readonly schedule: {
readonly type: "string";
readonly description: "Cron expression for scheduled warmup (e.g., '0 * * * *' for hourly)";
};
readonly scheduleId: {
readonly type: "string";
readonly description: "Schedule ID for cancel operation";
};
readonly dependencies: {
readonly type: "object";
readonly description: "Dependency graph for dependency-based warmup";
};
readonly accessHistory: {
readonly type: "array";
readonly description: "Access history for pattern-based warmup";
};
readonly minAccessCount: {
readonly type: "number";
readonly description: "Minimum access count for hot keys (default: 5)";
};
readonly timeWindow: {
readonly type: "number";
readonly description: "Time window for pattern analysis in ms (default: 3600000)";
};
readonly maxConcurrency: {
readonly type: "number";
readonly description: "Max concurrent warmup operations (default: 10)";
};
readonly batchSize: {
readonly type: "number";
readonly description: "Batch size for warmup (default: 50)";
};
readonly delayBetweenBatches: {
readonly type: "number";
readonly description: "Delay between batches in ms";
};
readonly hotKeyThreshold: {
readonly type: "number";
readonly description: "Minimum access count for hot keys";
};
readonly warmupPercentage: {
readonly type: "number";
readonly description: "Percentage of cache to warm (default: 80)";
};
readonly dryRun: {
readonly type: "boolean";
readonly description: "Simulate warmup without executing (default: false)";
};
readonly enableRollback: {
readonly type: "boolean";
readonly description: "Enable rollback on failures (default: true)";
};
readonly timeout: {
readonly type: "number";
readonly description: "Timeout for warmup operations in ms (default: 30000)";
};
readonly maxRetries: {
readonly type: "number";
readonly description: "Maximum retry attempts (default: 3)";
};
readonly retryDelay: {
readonly type: "number";
readonly description: "Delay between retries in ms";
};
readonly reportProgress: {
readonly type: "boolean";
readonly description: "Enable progress reporting (default: true)";
};
readonly progressInterval: {
readonly type: "number";
readonly description: "Progress report interval in ms";
};
readonly useCache: {
readonly type: "boolean";
readonly description: "Enable result caching (default: true)";
readonly default: true;
};
readonly cacheTTL: {
readonly type: "number";
readonly description: "Cache TTL in seconds (default: 300)";
readonly default: 300;
};
};
readonly required: readonly ["operation"];
};
};
export declare function runCacheWarmup(options: CacheWarmupOptions, cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector): Promise<WarmupResult>;
//# sourceMappingURL=cache-warmup.d.ts.map