@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/token-tracker.js

@@ -0,0 +1,751 @@
+/**
+ * Token usage tracking service for recording API call metrics, calculating costs,
+ * aggregating session totals, and exporting usage data.
+ *
+ * This module provides comprehensive token tracking functionality for the Compass CLI,
+ * enabling users to monitor their API usage, estimate costs, and receive warnings
+ * when approaching usage thresholds.
+ */
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { getGlobalCompassDir } from '../utils/path.js';
+import { safeReadJson, safeWriteJson, ensureDir } from '../utils/file-system.js';
+import { formatTimestamp } from '../utils/format.js';
+import { logger } from '../utils/logger.js';
+import { getModelConfig } from '../constants/models.js';
+import { TOKEN_WARNING_THRESHOLD } from '../constants/defaults.js';
+import { ROLLING_WINDOW_HOURS, resolvePlanLimits } from '../constants/token-limits.js';
+import { createTokenLimitStore, sumAllUsage, getModelTokens } from './token-limit-store.js';
+/**
+ * File name for storing token usage data
+ */
+const TOKEN_USAGE_FILE = 'token-usage.json';
+/**
+ * Default empty token usage data structure
+ */
+const DEFAULT_TOKEN_USAGE_DATA = {
+    version: '1.0',
+    sessions: [],
+    currentSessionId: null,
+    lastUpdated: '',
+};
+/**
+ * TokenTracker class provides comprehensive token usage tracking for API calls.
+ *
+ * Features:
+ * - Session-based tracking with automatic aggregation
+ * - Cost estimation based on model pricing
+ * - Warning system for usage thresholds
+ * - Persistent storage with automatic save/load
+ * - Detailed metrics and statistics
+ * - Export functionality for usage data
+ */
+class TokenTracker {
+    data;
+    currentSession = null;
+    warningThreshold;
+    costWarningThreshold;
+    initialized = false;
+    dirty = false;
+    tokenWarningEmitted = false;
+    costWarningEmitted = false;
+    constructor() {
+        this.data = { ...DEFAULT_TOKEN_USAGE_DATA };
+        this.warningThreshold = TOKEN_WARNING_THRESHOLD;
+        this.costWarningThreshold = 10.0; // $10 default cost warning
+    }
+    /**
+     * Initializes the token tracker by loading persisted data.
+     * Must be called before using other methods.
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        await this.load();
+        this.initialized = true;
+        logger.debug('Token tracker initialized');
+    }
+    /**
+     * Starts a new tracking session.
+     * If a session ID is provided, it will be used; otherwise, a new UUID is generated.
+     *
+     * @param sessionId - Optional session ID to use
+     * @returns The session ID of the new session
+     */
+    startSession(sessionId) {
+        const id = sessionId || uuidv4();
+        // Check if session already exists
+        const existingSession = this.data.sessions.find((s) => s.sessionId === id);
+        if (existingSession) {
+            this.currentSession = existingSession;
+            this.data.currentSessionId = id;
+            logger.debug(`Resumed existing token tracking session: ${id}`);
+            return id;
+        }
+        // Create new session — reset warning flags
+        this.tokenWarningEmitted = false;
+        this.costWarningEmitted = false;
+        this.currentSession = {
+            sessionId: id,
+            startTime: formatTimestamp(),
+            calls: [],
+            totals: this.createEmptyTokenUsage(),
+            estimatedCost: this.createEmptyCostEstimate(),
+        };
+        this.data.sessions.push(this.currentSession);
+        this.data.currentSessionId = id;
+        this.dirty = true;
+        logger.debug(`Token tracking session started: ${id}`);
+        return id;
+    }
+    /**
+     * Records token usage for an API call.
+     * Automatically starts a session if none is active.
+     *
+     * @param model - The model ID used for the API call
+     * @param usage - Token usage statistics from the API response
+     * @param purpose - Optional description of the API call purpose
+     */
+    async recordUsage(model, usage, purpose) {
+        // Ensure we have an active session
+        if (!this.currentSession) {
+            this.startSession();
+        }
+        // Calculate cost for this call
+        const cost = this.calculateCost(usage, model);
+        // Create the API call record
+        const callUsage = {
+            id: uuidv4(),
+            timestamp: formatTimestamp(),
+            model,
+            usage: { ...usage },
+            cost,
+            purpose,
+        };
+        // Add to current session
+        this.currentSession.calls.push(callUsage);
+        // Update session totals
+        this.updateSessionTotals();
+        // Check for warnings (debug-level, emitted once per threshold)
+        const warnings = this.checkWarnings();
+        for (const warning of warnings) {
+            logger.debug(warning.message);
+        }
+        // Mark as dirty and save
+        this.dirty = true;
+        await this.save();
+        logger.debug(`Recorded usage: ${usage.inputTokens} in, ${usage.outputTokens} out, ${cost.totalCost.toFixed(4)} USD`);
+    }
+    /**
+     * Gets the current session's token usage.
+     *
+     * @returns The current session usage or null if no session is active
+     */
+    getCurrentSessionUsage() {
+        return this.currentSession;
+    }
+    /**
+     * Gets usage metrics for the current session.
+     *
+     * @returns Token metrics for the current session or null if no session/calls
+     */
+    getSessionMetrics() {
+        if (!this.currentSession || this.currentSession.calls.length === 0) {
+            return null;
+        }
+        const calls = this.currentSession.calls;
+        const inputTokens = calls.map((c) => c.usage.inputTokens);
+        const outputTokens = calls.map((c) => c.usage.outputTokens);
+        return {
+            averageInputTokens: this.calculateAverage(inputTokens),
+            averageOutputTokens: this.calculateAverage(outputTokens),
+            peakInputTokens: Math.max(...inputTokens),
+            peakOutputTokens: Math.max(...outputTokens),
+            totalCalls: calls.length,
+            totalTokens: this.currentSession.totals.totalTokens,
+            totalCost: this.currentSession.estimatedCost.totalCost,
+        };
+    }
+    /**
+     * Gets all-time usage statistics across all sessions.
+     *
+     * @returns Aggregated token metrics across all sessions
+     */
+    getAllTimeStats() {
+        const allCalls = this.data.sessions.flatMap((s) => s.calls);
+        if (allCalls.length === 0) {
+            return {
+                averageInputTokens: 0,
+                averageOutputTokens: 0,
+                peakInputTokens: 0,
+                peakOutputTokens: 0,
+                totalCalls: 0,
+                totalTokens: 0,
+                totalCost: 0,
+            };
+        }
+        const inputTokens = allCalls.map((c) => c.usage.inputTokens);
+        const outputTokens = allCalls.map((c) => c.usage.outputTokens);
+        const totalTokens = this.data.sessions.reduce((sum, s) => sum + s.totals.totalTokens, 0);
+        const totalCost = this.data.sessions.reduce((sum, s) => sum + s.estimatedCost.totalCost, 0);
+        return {
+            averageInputTokens: this.calculateAverage(inputTokens),
+            averageOutputTokens: this.calculateAverage(outputTokens),
+            peakInputTokens: Math.max(...inputTokens),
+            peakOutputTokens: Math.max(...outputTokens),
+            totalCalls: allCalls.length,
+            totalTokens,
+            totalCost,
+        };
+    }
+    /**
+     * Gets usage statistics for a specific time period.
+     *
+     * @param startDate - Start of the period
+     * @param endDate - End of the period (defaults to now)
+     * @returns Token metrics for the specified period
+     */
+    getStatsByPeriod(startDate, endDate = new Date()) {
+        const startTime = startDate.getTime();
+        const endTime = endDate.getTime();
+        const filteredCalls = this.data.sessions.flatMap((s) => s.calls.filter((c) => {
+            const callTime = new Date(c.timestamp).getTime();
+            return callTime >= startTime && callTime <= endTime;
+        }));
+        if (filteredCalls.length === 0) {
+            return {
+                averageInputTokens: 0,
+                averageOutputTokens: 0,
+                peakInputTokens: 0,
+                peakOutputTokens: 0,
+                totalCalls: 0,
+                totalTokens: 0,
+                totalCost: 0,
+            };
+        }
+        const inputTokens = filteredCalls.map((c) => c.usage.inputTokens);
+        const outputTokens = filteredCalls.map((c) => c.usage.outputTokens);
+        const totalTokens = filteredCalls.reduce((sum, c) => sum + c.usage.totalTokens, 0);
+        const totalCost = filteredCalls.reduce((sum, c) => sum + c.cost.totalCost, 0);
+        return {
+            averageInputTokens: this.calculateAverage(inputTokens),
+            averageOutputTokens: this.calculateAverage(outputTokens),
+            peakInputTokens: Math.max(...inputTokens),
+            peakOutputTokens: Math.max(...outputTokens),
+            totalCalls: filteredCalls.length,
+            totalTokens,
+            totalCost,
+        };
+    }
+    /**
+     * Gets usage statistics grouped by model.
+     *
+     * @returns Map of model ID to token metrics
+     */
+    getStatsByModel() {
+        const modelStats = new Map();
+        // Group calls by model
+        for (const session of this.data.sessions) {
+            for (const call of session.calls) {
+                const existing = modelStats.get(call.model) || [];
+                existing.push(call);
+                modelStats.set(call.model, existing);
+            }
+        }
+        // Calculate metrics for each model
+        const result = new Map();
+        for (const [model, calls] of modelStats) {
+            if (calls.length === 0)
+                continue;
+            const inputTokens = calls.map((c) => c.usage.inputTokens);
+            const outputTokens = calls.map((c) => c.usage.outputTokens);
+            const totalTokens = calls.reduce((sum, c) => sum + c.usage.totalTokens, 0);
+            const totalCost = calls.reduce((sum, c) => sum + c.cost.totalCost, 0);
+            result.set(model, {
+                averageInputTokens: this.calculateAverage(inputTokens),
+                averageOutputTokens: this.calculateAverage(outputTokens),
+                peakInputTokens: Math.max(...inputTokens),
+                peakOutputTokens: Math.max(...outputTokens),
+                totalCalls: calls.length,
+                totalTokens,
+                totalCost,
+            });
+        }
+        return result;
+    }
+    /**
+     * Ends the current session and marks it as complete.
+     */
+    async endSession() {
+        if (this.currentSession) {
+            this.currentSession.endTime = formatTimestamp();
+            this.dirty = true;
+            await this.save();
+            logger.debug(`Token tracking session ended: ${this.currentSession.sessionId}`);
+            this.currentSession = null;
+            this.data.currentSessionId = null;
+        }
+    }
+    /**
+     * Exports all usage data for backup or analysis.
+     *
+     * @returns Complete token usage data structure
+     */
+    async exportUsage() {
+        return {
+            ...this.data,
+            lastUpdated: formatTimestamp(),
+        };
+    }
+    /**
+     * Exports usage data for a specific session.
+     *
+     * @param sessionId - The session ID to export
+     * @returns Session usage data or null if not found
+     */
+    getSessionById(sessionId) {
+        return this.data.sessions.find((s) => s.sessionId === sessionId) || null;
+    }
+    /**
+     * Gets all sessions, optionally filtered by date range.
+     *
+     * @param startDate - Optional start date filter
+     * @param endDate - Optional end date filter
+     * @returns Array of session usage data
+     */
+    getSessions(startDate, endDate) {
+        let sessions = [...this.data.sessions];
+        if (startDate) {
+            const startTime = startDate.getTime();
+            sessions = sessions.filter((s) => new Date(s.startTime).getTime() >= startTime);
+        }
+        if (endDate) {
+            const endTime = endDate.getTime();
+            sessions = sessions.filter((s) => new Date(s.startTime).getTime() <= endTime);
+        }
+        return sessions;
+    }
+    /**
+     * Sets the warning threshold for token usage.
+     *
+     * @param tokens - Token count threshold for warnings
+     */
+    setWarningThreshold(tokens) {
+        this.warningThreshold = tokens;
+        this.tokenWarningEmitted = false;
+        logger.debug(`Token warning threshold set to ${tokens}`);
+    }
+    /**
+     * Gets the current warning threshold.
+     *
+     * @returns The current token warning threshold
+     */
+    getWarningThreshold() {
+        return this.warningThreshold;
+    }
+    /**
+     * Sets the cost warning threshold.
+     *
+     * @param cost - Cost threshold in USD for warnings
+     */
+    setCostWarningThreshold(cost) {
+        this.costWarningThreshold = cost;
+        this.costWarningEmitted = false;
+        logger.debug(`Cost warning threshold set to $${cost}`);
+    }
+    /**
+     * Gets the current cost warning threshold.
+     *
+     * @returns The current cost warning threshold in USD
+     */
+    getCostWarningThreshold() {
+        return this.costWarningThreshold;
+    }
+    /**
+     * Checks for any warning conditions and returns applicable warnings.
+     *
+     * @returns Array of token warnings
+     */
+    checkWarnings() {
+        const warnings = [];
+        if (!this.currentSession) {
+            return warnings;
+        }
+        const totalTokens = this.currentSession.totals.totalTokens;
+        const totalCost = this.currentSession.estimatedCost.totalCost;
+        // Check token threshold (only emit once per threshold crossing)
+        if (totalTokens >= this.warningThreshold && !this.tokenWarningEmitted) {
+            this.tokenWarningEmitted = true;
+            warnings.push({
+                type: 'exceeded_threshold',
+                message: `Token usage (${totalTokens.toLocaleString()}) has exceeded the warning threshold (${this.warningThreshold.toLocaleString()})`,
+                currentValue: totalTokens,
+                threshold: this.warningThreshold,
+                severity: 'warning',
+            });
+        }
+        else if (totalTokens >= this.warningThreshold * 0.8 && !this.tokenWarningEmitted) {
+            warnings.push({
+                type: 'approaching_limit',
+                message: `Token usage (${totalTokens.toLocaleString()}) is approaching the warning threshold (${this.warningThreshold.toLocaleString()})`,
+                currentValue: totalTokens,
+                threshold: this.warningThreshold,
+                severity: 'info',
+            });
+        }
+        // Check cost threshold (only emit once per threshold crossing)
+        if (totalCost >= this.costWarningThreshold && !this.costWarningEmitted) {
+            this.costWarningEmitted = true;
+            warnings.push({
+                type: 'high_cost',
+                message: `Session cost ($${totalCost.toFixed(2)}) has exceeded the warning threshold ($${this.costWarningThreshold.toFixed(2)})`,
+                currentValue: totalCost,
+                threshold: this.costWarningThreshold,
+                severity: 'warning',
+            });
+        }
+        else if (totalCost >= this.costWarningThreshold * 0.8 && !this.costWarningEmitted) {
+            warnings.push({
+                type: 'high_cost',
+                message: `Session cost ($${totalCost.toFixed(2)}) is approaching the warning threshold ($${this.costWarningThreshold.toFixed(2)})`,
+                currentValue: totalCost,
+                threshold: this.costWarningThreshold,
+                severity: 'info',
+            });
+        }
+        return warnings;
+    }
+    // ===========================================================================
+    // Unified rolling window limit system
+    // ===========================================================================
+    /** Lazily-initialized reference to the unified token limit store. */
+    _limitStore = null;
+    /**
+     * Sets the TokenLimitStore instance used for rolling window tracking.
+     * Must be called before using any limit-related methods.
+     */
+    setLimitStore(store) {
+        this._limitStore = store;
+    }
+    /** Returns the limit store, throwing if not yet wired up. */
+    getLimitStore() {
+        if (!this._limitStore) {
+            throw new Error('[TokenTracker] TokenLimitStore not set — call setLimitStore() first.');
+        }
+        return this._limitStore;
+    }
+    /**
+     * Resolves the applicable token limits for a model under a given plan.
+     *
+     * @param modelId - The model ID to resolve limits for
+     * @param planStatus - The user's current plan status
+     * @param planType - The subscription tier (only used when planStatus === 'active')
+     * @returns General and model-specific limits
+     */
+    resolveLimit(modelId, planStatus, planType) {
+        const planLimits = resolvePlanLimits(planStatus, planType);
+        const modelLimit = planLimits.perModelLimits[modelId] ?? planLimits.defaultPerModelLimit;
+        return {
+            generalLimit: planLimits.generalLimit,
+            modelLimit,
+        };
+    }
+    /**
+     * Checks whether an API call for a given model is allowed under the
+     * token limits for the current 6-hour window.
+     *
+     * Loads the state (which resets if the window expired), reads flat
+     * counters, and compares against both the general (aggregate) limit
+     * and the per-model limit.
+     *
+     * @param modelId - The model ID to check
+     * @param planStatus - The user's current plan status
+     * @param planType - The subscription tier (only used when planStatus === 'active')
+     * @returns Check result with allowed status and remaining tokens
+     */
+    async checkLimit(modelId, planStatus, planType) {
+        const store = this.getLimitStore();
+        const state = await store.loadState(); // loads + resets if window expired
+        const { generalLimit, modelLimit } = this.resolveLimit(modelId, planStatus, planType);
+        const generalUsed = sumAllUsage(state);
+        const modelUsed = getModelTokens(state, modelId);
+        const generalRemaining = Math.max(0, generalLimit - generalUsed);
+        const modelRemaining = Math.max(0, modelLimit - modelUsed);
+        // Check model limit first (more specific)
+        if (modelUsed >= modelLimit) {
+            return {
+                allowed: false,
+                generalRemaining,
+                modelRemaining: 0,
+                reason: `Token limit exceeded for model "${modelId}". Used ${modelUsed.toLocaleString()} / ${modelLimit.toLocaleString()} tokens in the last ${ROLLING_WINDOW_HOURS}h.`,
+            };
+        }
+        // Check general limit
+        if (generalUsed >= generalLimit) {
+            return {
+                allowed: false,
+                generalRemaining: 0,
+                modelRemaining,
+                reason: `Aggregate token limit exceeded. Used ${generalUsed.toLocaleString()} / ${generalLimit.toLocaleString()} tokens in the last ${ROLLING_WINDOW_HOURS}h.`,
+            };
+        }
+        return {
+            allowed: true,
+            generalRemaining,
+            modelRemaining,
+        };
+    }
+    /**
+     * Records token usage against the rolling window limit store.
+     * This is separate from the session analytics `recordUsage` method.
+     *
+     * @param modelId - The model that consumed tokens
+     * @param tokens - Number of tokens consumed
+     */
+    async recordLimitUsage(modelId, tokens) {
+        try {
+            const store = this.getLimitStore();
+            await store.recordUsage(modelId, tokens);
+        }
+        catch (err) {
+            logger.warn(`[TokenTracker] Failed to record limit usage for ${modelId}: ${String(err)}`);
+        }
+    }
+    /**
+     * Gets the total tokens used for a specific model within the rolling window.
+     *
+     * @param modelId - The model to check
+     * @returns Number of tokens used in the current window
+     */
+    async getUsageForModel(modelId) {
+        const store = this.getLimitStore();
+        return store.getModelUsage(modelId);
+    }
+    /**
+     * Gets the remaining tokens for a model under the current plan.
+     *
+     * @param modelId - The model to check
+     * @param planStatus - The user's current plan status
+     * @param planType - The subscription tier (only used when planStatus === 'active')
+     * @returns Remaining tokens for the model
+     */
+    async getRemainingTokens(modelId, planStatus, planType) {
+        const { modelLimit } = this.resolveLimit(modelId, planStatus, planType);
+        const used = await this.getUsageForModel(modelId);
+        return Math.max(0, modelLimit - used);
+    }
+    /**
+     * Clears all usage data. Use with caution.
+     */
+    async clearAllData() {
+        this.data = { ...DEFAULT_TOKEN_USAGE_DATA };
+        this.currentSession = null;
+        this.dirty = true;
+        await this.save();
+        logger.info('All token usage data cleared');
+    }
+    /**
+     * Clears usage data older than the specified number of days.
+     *
+     * @param days - Number of days to retain
+     * @returns Number of sessions removed
+     */
+    async clearOldData(days) {
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - days);
+        const cutoffTime = cutoffDate.getTime();
+        const originalCount = this.data.sessions.length;
+        this.data.sessions = this.data.sessions.filter((session) => {
+            const sessionTime = new Date(session.startTime).getTime();
+            return sessionTime >= cutoffTime;
+        });
+        const removedCount = originalCount - this.data.sessions.length;
+        if (removedCount > 0) {
+            this.dirty = true;
+            await this.save();
+            logger.info(`Cleared ${removedCount} sessions older than ${days} days`);
+        }
+        return removedCount;
+    }
+    /**
+     * Calculates cost for token usage based on model pricing.
+     *
+     * @param usage - Token usage statistics
+     * @param model - Model ID for pricing lookup
+     * @returns Cost estimate breakdown
+     */
+    calculateCost(usage, model) {
+        const modelConfig = getModelConfig(model);
+        if (!modelConfig) {
+            logger.debug(`Unknown model for cost calculation: ${model}`);
+            return this.createEmptyCostEstimate();
+        }
+        const inputCost = (usage.inputTokens / 1_000_000) * modelConfig.pricing.inputPricePerMillion;
+        const outputCost = (usage.outputTokens / 1_000_000) * modelConfig.pricing.outputPricePerMillion;
+        return {
+            inputCost,
+            outputCost,
+            totalCost: inputCost + outputCost,
+            currency: 'USD',
+        };
+    }
+    /**
+     * Updates the current session's totals based on all calls.
+     */
+    updateSessionTotals() {
+        if (!this.currentSession) {
+            return;
+        }
+        const totals = this.createEmptyTokenUsage();
+        const cost = this.createEmptyCostEstimate();
+        for (const call of this.currentSession.calls) {
+            totals.inputTokens += call.usage.inputTokens;
+            totals.outputTokens += call.usage.outputTokens;
+            totals.totalTokens += call.usage.totalTokens;
+            // Handle cache tokens if present
+            if (call.usage.cacheCreationInputTokens) {
+                totals.cacheCreationInputTokens =
+                    (totals.cacheCreationInputTokens || 0) +
+                        call.usage.cacheCreationInputTokens;
+            }
+            if (call.usage.cacheReadInputTokens) {
+                totals.cacheReadInputTokens =
+                    (totals.cacheReadInputTokens || 0) + call.usage.cacheReadInputTokens;
+            }
+            cost.inputCost += call.cost.inputCost;
+            cost.outputCost += call.cost.outputCost;
+            cost.totalCost += call.cost.totalCost;
+        }
+        this.currentSession.totals = totals;
+        this.currentSession.estimatedCost = cost;
+    }
+    /**
+     * Calculates the average of an array of numbers.
+     *
+     * @param numbers - Array of numbers to average
+     * @returns The average, rounded to nearest integer
+     */
+    calculateAverage(numbers) {
+        if (numbers.length === 0) {
+            return 0;
+        }
+        const sum = numbers.reduce((a, b) => a + b, 0);
+        return Math.round(sum / numbers.length);
+    }
+    /**
+     * Creates an empty token usage object.
+     *
+     * @returns Empty TokenUsage object
+     */
+    createEmptyTokenUsage() {
+        return {
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+        };
+    }
+    /**
+     * Creates an empty cost estimate object.
+     *
+     * @returns Empty CostEstimate object
+     */
+    createEmptyCostEstimate() {
+        return {
+            inputCost: 0,
+            outputCost: 0,
+            totalCost: 0,
+            currency: 'USD',
+        };
+    }
+    /**
+     * Gets the file path for token usage data storage.
+     *
+     * @returns Full path to the token usage file
+     */
+    getFilePath() {
+        return path.join(getGlobalCompassDir(), TOKEN_USAGE_FILE);
+    }
+    /**
+     * Loads token usage data from disk.
+     */
+    async load() {
+        try {
+            // Ensure the directory exists
+            await ensureDir(getGlobalCompassDir());
+            const filePath = this.getFilePath();
+            const data = await safeReadJson(filePath);
+            if (data) {
+                this.data = {
+                    ...DEFAULT_TOKEN_USAGE_DATA,
+                    ...data,
+                };
+                // Restore current session if exists
+                if (data.currentSessionId) {
+                    this.currentSession =
+                        data.sessions.find((s) => s.sessionId === data.currentSessionId) ||
+                            null;
+                }
+                logger.debug(`Loaded token usage data: ${this.data.sessions.length} sessions`);
+            }
+        }
+        catch (error) {
+            logger.debug('Failed to load token usage data, starting fresh', error);
+            this.data = { ...DEFAULT_TOKEN_USAGE_DATA };
+        }
+    }
+    /**
+     * Saves token usage data to disk.
+     */
+    async save() {
+        if (!this.dirty) {
+            return;
+        }
+        try {
+            // Ensure the directory exists
+            await ensureDir(getGlobalCompassDir());
+            const filePath = this.getFilePath();
+            this.data.lastUpdated = formatTimestamp();
+            await safeWriteJson(filePath, this.data);
+            this.dirty = false;
+            logger.debug('Token usage data saved');
+        }
+        catch (error) {
+            logger.error('Failed to save token usage data', error);
+        }
+    }
+    /**
+     * Forces a save of the current data, regardless of dirty state.
+     */
+    async forceSave() {
+        this.dirty = true;
+        await this.save();
+    }
+}
+// Singleton instance
+let tokenTrackerInstance = null;
+/**
+ * Gets the singleton TokenTracker instance.
+ * Creates and initializes the instance on first call.
+ *
+ * @returns Promise resolving to the TokenTracker instance
+ */
+export async function getTokenTracker() {
+    if (!tokenTrackerInstance) {
+        tokenTrackerInstance = new TokenTracker();
+        tokenTrackerInstance.setLimitStore(createTokenLimitStore());
+        await tokenTrackerInstance.initialize();
+    }
+    return tokenTrackerInstance;
+}
+/**
+ * Creates a new TokenTracker instance with custom configuration.
+ * Use this when you need a separate instance from the singleton.
+ *
+ * @returns A new TokenTracker instance (not initialized)
+ */
+export function createTokenTracker() {
+    return new TokenTracker();
+}
+export { TokenTracker };
+//# sourceMappingURL=token-tracker.js.map