@within-7/minto 0.3.6 → 0.3.10

package/dist/utils/stats.js

@@ -0,0 +1,417 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { CONFIG_PATHS } from "./configPaths.js";
+import { debug as debugLogger } from "./debugLogger.js";
+const STATS_VERSION = 1;
+const MAX_DAILY_RECORDS = 90;
+const SAVE_DEBOUNCE_MS = 5e3;
+const CURRENT_SESSION_ID = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+class StatsManager {
+  static instance = null;
+  stats;
+  isDirty = false;
+  saveTimeout = null;
+  sessionStartTime = null;
+  constructor() {
+    this.stats = this.loadStats();
+  }
+  /**
+   * Get singleton instance
+   */
+  static getInstance() {
+    if (!StatsManager.instance) {
+      StatsManager.instance = new StatsManager();
+    }
+    return StatsManager.instance;
+  }
+  /**
+   * Load stats from disk or create default
+   */
+  loadStats() {
+    const statsPath = CONFIG_PATHS.activityFile;
+    try {
+      if (existsSync(statsPath)) {
+        const data = readFileSync(statsPath, "utf-8");
+        const parsed = JSON.parse(data);
+        if (parsed.version !== STATS_VERSION) {
+          return this.migrateStats(parsed);
+        }
+        return parsed;
+      }
+    } catch (error) {
+      debugLogger.warn("STATS_LOAD_ERROR", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    return this.createDefaultStats();
+  }
+  /**
+   * Create default empty stats structure
+   */
+  createDefaultStats() {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      version: STATS_VERSION,
+      lastUpdated: now,
+      dailyActivity: [],
+      modelUsage: {},
+      toolUsage: {},
+      lifetime: {
+        totalMessages: 0,
+        totalSessions: 0,
+        totalToolCalls: 0,
+        totalTokens: 0,
+        totalCost: 0,
+        firstUsed: now
+      }
+    };
+  }
+  /**
+   * Migrate older stats versions
+   */
+  migrateStats(oldStats) {
+    debugLogger.info("STATS_MIGRATION", {
+      fromVersion: oldStats.version,
+      toVersion: STATS_VERSION
+    });
+    return this.createDefaultStats();
+  }
+  /**
+   * Get today's date string in YYYY-MM-DD format
+   */
+  getTodayString() {
+    return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  }
+  /**
+   * Get or create today's activity record
+   */
+  getOrCreateTodayActivity() {
+    const today = this.getTodayString();
+    let activity = this.stats.dailyActivity.find((a) => a.date === today);
+    if (!activity) {
+      activity = {
+        date: today,
+        messageCount: 0,
+        sessionCount: 0,
+        toolCallCount: 0,
+        tokensUsed: 0,
+        costEstimate: 0
+      };
+      this.stats.dailyActivity.push(activity);
+      if (this.stats.dailyActivity.length > MAX_DAILY_RECORDS) {
+        this.stats.dailyActivity = this.stats.dailyActivity.sort((a, b) => b.date.localeCompare(a.date)).slice(0, MAX_DAILY_RECORDS);
+      }
+    }
+    return activity;
+  }
+  /**
+   * Schedule a debounced save
+   */
+  scheduleSave() {
+    this.isDirty = true;
+    if (this.saveTimeout) {
+      return;
+    }
+    this.saveTimeout = setTimeout(() => {
+      this.saveStatsSync();
+      this.saveTimeout = null;
+    }, SAVE_DEBOUNCE_MS);
+  }
+  /**
+   * Save stats to disk (synchronous, for debounced writes)
+   */
+  saveStatsSync() {
+    if (!this.isDirty) return;
+    const statsPath = CONFIG_PATHS.activityFile;
+    try {
+      const dir = dirname(statsPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      this.stats.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
+      writeFileSync(statsPath, JSON.stringify(this.stats, null, 2), "utf-8");
+      this.isDirty = false;
+      debugLogger.trace("STATS_SAVED", { path: statsPath });
+    } catch (error) {
+      debugLogger.error("STATS_SAVE_ERROR", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  // ============================================
+  // Public API - Recording Methods
+  // ============================================
+  /**
+   * Record a message (API call)
+   *
+   * Call this after each API call completes.
+   *
+   * @param model - Model name used
+   * @param inputTokens - Number of input tokens
+   * @param outputTokens - Number of output tokens
+   * @param costUSD - Estimated cost in USD (optional)
+   */
+  recordMessage(model, inputTokens, outputTokens, costUSD = 0) {
+    const totalTokens = inputTokens + outputTokens;
+    const today = this.getOrCreateTodayActivity();
+    today.messageCount += 1;
+    today.tokensUsed += totalTokens;
+    today.costEstimate += costUSD;
+    if (!this.stats.modelUsage[model]) {
+      this.stats.modelUsage[model] = {
+        model,
+        calls: 0,
+        tokens: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        costEstimate: 0
+      };
+    }
+    const modelStats = this.stats.modelUsage[model];
+    modelStats.calls += 1;
+    modelStats.tokens += totalTokens;
+    modelStats.inputTokens += inputTokens;
+    modelStats.outputTokens += outputTokens;
+    modelStats.costEstimate += costUSD;
+    this.stats.lifetime.totalMessages += 1;
+    this.stats.lifetime.totalTokens += totalTokens;
+    this.stats.lifetime.totalCost += costUSD;
+    if (this.stats.currentSession) {
+      this.stats.currentSession.messageCount += 1;
+      this.stats.currentSession.model = model;
+    }
+    this.scheduleSave();
+  }
+  /**
+   * Record a tool call
+   *
+   * Call this when a tool execution completes.
+   *
+   * @param toolName - Name of the tool
+   * @param isError - Whether the execution resulted in an error
+   */
+  recordToolCall(toolName, isError = false) {
+    const today = this.getOrCreateTodayActivity();
+    today.toolCallCount += 1;
+    if (!this.stats.toolUsage[toolName]) {
+      this.stats.toolUsage[toolName] = {
+        toolName,
+        calls: 0,
+        successCount: 0,
+        errorCount: 0
+      };
+    }
+    const toolStats = this.stats.toolUsage[toolName];
+    toolStats.calls += 1;
+    if (isError) {
+      toolStats.errorCount += 1;
+    } else {
+      toolStats.successCount += 1;
+    }
+    this.stats.lifetime.totalToolCalls += 1;
+    this.scheduleSave();
+  }
+  /**
+   * Record session start
+   *
+   * Call this when a new REPL session starts.
+   */
+  recordSessionStart() {
+    this.sessionStartTime = Date.now();
+    const today = this.getOrCreateTodayActivity();
+    today.sessionCount += 1;
+    this.stats.lifetime.totalSessions += 1;
+    this.stats.currentSession = {
+      sessionId: CURRENT_SESSION_ID,
+      startTime: this.sessionStartTime,
+      messageCount: 0
+    };
+    this.scheduleSave();
+  }
+  /**
+   * Record session end
+   *
+   * Call this when a REPL session ends.
+   *
+   * @param durationMs - Session duration in milliseconds (optional, auto-calculated if sessionStart was called)
+   */
+  recordSessionEnd(durationMs) {
+    const endTime = Date.now();
+    if (this.stats.currentSession) {
+      this.stats.currentSession.endTime = endTime;
+      this.stats.currentSession.durationMs = durationMs ?? (this.sessionStartTime ? endTime - this.sessionStartTime : 0);
+    }
+    this.sessionStartTime = null;
+    this.isDirty = true;
+    this.saveStatsSync();
+  }
+  // ============================================
+  // Public API - Query Methods
+  // ============================================
+  /**
+   * Get the complete stats data
+   */
+  getStats() {
+    return { ...this.stats };
+  }
+  /**
+   * Save stats (use for manual saves, e.g., before exit)
+   */
+  saveStats(stats) {
+    this.stats = stats;
+    this.isDirty = true;
+    this.saveStatsSync();
+  }
+  /**
+   * Get today's activity statistics
+   */
+  getTodayStats() {
+    const today = this.getTodayString();
+    return this.stats.dailyActivity.find((a) => a.date === today) ?? null;
+  }
+  /**
+   * Get statistics for the last N days
+   *
+   * @param days - Number of days to retrieve
+   */
+  getStatsForDays(days) {
+    const cutoffDate = /* @__PURE__ */ new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - days);
+    const cutoffString = cutoffDate.toISOString().split("T")[0];
+    return this.stats.dailyActivity.filter((a) => a.date >= cutoffString).sort((a, b) => b.date.localeCompare(a.date));
+  }
+  /**
+   * Get model usage statistics
+   */
+  getModelUsageStats() {
+    return Object.values(this.stats.modelUsage).sort(
+      (a, b) => b.calls - a.calls
+    );
+  }
+  /**
+   * Get tool usage statistics
+   */
+  getToolUsageStats() {
+    return Object.values(this.stats.toolUsage).sort((a, b) => b.calls - a.calls);
+  }
+  /**
+   * Get lifetime statistics summary
+   */
+  getLifetimeStats() {
+    return { ...this.stats.lifetime };
+  }
+  /**
+   * Estimate cost for a given model and token count
+   *
+   * Simple cost estimation based on known model pricing.
+   * Returns 0 for unknown models.
+   *
+   * @param model - Model name
+   * @param inputTokens - Number of input tokens
+   * @param outputTokens - Number of output tokens
+   */
+  estimateCost(model, inputTokens, outputTokens) {
+    const pricing = {
+      // Claude models
+      "claude-3-opus": { input: 15, output: 75 },
+      "claude-3-sonnet": { input: 3, output: 15 },
+      "claude-3-haiku": { input: 0.25, output: 1.25 },
+      "claude-sonnet-4": { input: 3, output: 15 },
+      // GPT models
+      "gpt-4": { input: 30, output: 60 },
+      "gpt-4-turbo": { input: 10, output: 30 },
+      "gpt-4o": { input: 5, output: 15 },
+      "gpt-4o-mini": { input: 0.15, output: 0.6 },
+      "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+      // Default for unknown models
+      default: { input: 3, output: 15 }
+    };
+    let modelPricing = pricing.default;
+    for (const [key, price] of Object.entries(pricing)) {
+      if (key !== "default" && model.toLowerCase().includes(key)) {
+        modelPricing = price;
+        break;
+      }
+    }
+    return inputTokens / 1e6 * modelPricing.input + outputTokens / 1e6 * modelPricing.output;
+  }
+  /**
+   * Reset statistics (for testing)
+   */
+  resetForTests() {
+    if (process.env.NODE_ENV !== "test") {
+      throw new Error("resetForTests can only be called in tests");
+    }
+    this.stats = this.createDefaultStats();
+    this.isDirty = false;
+    this.sessionStartTime = null;
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+      this.saveTimeout = null;
+    }
+  }
+  /**
+   * Force immediate save (for graceful shutdown)
+   */
+  forceImmediateSave() {
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+      this.saveTimeout = null;
+    }
+    this.isDirty = true;
+    this.saveStatsSync();
+  }
+}
+const statsManager = StatsManager.getInstance();
+function getStats() {
+  return statsManager.getStats();
+}
+function saveStats(stats) {
+  statsManager.saveStats(stats);
+}
+function recordMessage(model, inputTokens, outputTokens, costUSD) {
+  statsManager.recordMessage(model, inputTokens, outputTokens, costUSD);
+}
+function recordToolCall(toolName, isError) {
+  statsManager.recordToolCall(toolName, isError);
+}
+function recordSessionStart() {
+  statsManager.recordSessionStart();
+}
+function recordSessionEnd(durationMs) {
+  statsManager.recordSessionEnd(durationMs);
+}
+function getTodayStats() {
+  return statsManager.getTodayStats();
+}
+function getStatsForDays(days) {
+  return statsManager.getStatsForDays(days);
+}
+function getModelUsageStats() {
+  return statsManager.getModelUsageStats();
+}
+function getToolUsageStats() {
+  return statsManager.getToolUsageStats();
+}
+function estimateCost(model, inputTokens, outputTokens) {
+  return statsManager.estimateCost(model, inputTokens, outputTokens);
+}
+function forceImmediateSave() {
+  statsManager.forceImmediateSave();
+}
+export {
+  estimateCost,
+  forceImmediateSave,
+  getModelUsageStats,
+  getStats,
+  getStatsForDays,
+  getTodayStats,
+  getToolUsageStats,
+  recordMessage,
+  recordSessionEnd,
+  recordSessionStart,
+  recordToolCall,
+  saveStats,
+  statsManager
+};
+//# sourceMappingURL=stats.js.map

package/dist/utils/stats.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/stats.ts"],
+  "sourcesContent": ["/**\n * Usage Statistics Manager\n *\n * Tracks and persists usage statistics across sessions.\n * Integrates with token tracking, tool execution, and session lifecycle.\n *\n * Data is stored at ~/.minto/stats/activity.json\n *\n * Features:\n * - Daily activity aggregation\n * - Model usage breakdown\n * - Tool call tracking\n * - Session duration tracking\n * - Cost estimation\n *\n * Performance:\n * - Uses in-memory cache with periodic file persistence\n * - Debounced writes to avoid excessive disk I/O\n * - Non-blocking async saves that don't block main flow\n */\n\nimport { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'\nimport { dirname } from 'path'\nimport { CONFIG_PATHS } from './configPaths'\nimport { debug as debugLogger } from './debugLogger'\n\n// ============================================\n// Type Definitions\n// ============================================\n\n/**\n * Daily activity statistics\n */\nexport interface DailyActivity {\n  /** Date in YYYY-MM-DD format */\n  date: string\n  /** Number of messages sent/received */\n  messageCount: number\n  /** Number of sessions started */\n  sessionCount: number\n  /** Number of tool calls executed */\n  toolCallCount: number\n  /** Total tokens used (input + output) */\n  tokensUsed: number\n  /** Estimated cost in USD */\n  costEstimate: number\n}\n\n/**\n * Model-specific usage statistics\n */\nexport interface ModelUsage {\n  /** Model name/identifier */\n  model: string\n  /** Number of API calls to this model */\n  calls: number\n  /** Total tokens used by this model */\n  tokens: number\n  /** Input tokens */\n  inputTokens: number\n  /** Output tokens */\n  outputTokens: number\n  /** Estimated cost for this model */\n  costEstimate: number\n}\n\n/**\n * Tool-specific usage statistics\n */\nexport interface ToolUsage {\n  /** Tool name */\n  toolName: string\n  /** Number of times this tool was called */\n  calls: number\n  /** Number of successful executions */\n  successCount: number\n  /** Number of failed executions */\n  errorCount: number\n}\n\n/**\n * Session information\n */\nexport interface SessionInfo {\n  /** Session ID */\n  sessionId: string\n  /** Start timestamp */\n  startTime: number\n  /** End timestamp (if completed) */\n  endTime?: number\n  /** Duration in milliseconds */\n  durationMs?: number\n  /** Number of messages in this session */\n  messageCount: number\n  /** Model used */\n  model?: string\n}\n\n/**\n * Complete statistics data structure\n */\nexport interface StatsData {\n  /** Schema version for future migrations */\n  version: number\n  /** Last update timestamp */\n  lastUpdated: string\n  /** Daily activity records (last 90 days) */\n  dailyActivity: DailyActivity[]\n  /** Model usage breakdown */\n  modelUsage: Record<string, ModelUsage>\n  /** Tool usage breakdown */\n  toolUsage: Record<string, ToolUsage>\n  /** Current session info */\n  currentSession?: SessionInfo\n  /** Total lifetime statistics */\n  lifetime: {\n    totalMessages: number\n    totalSessions: number\n    totalToolCalls: number\n    totalTokens: number\n    totalCost: number\n    firstUsed: string\n  }\n}\n\n// ============================================\n// Constants\n// ============================================\n\nconst STATS_VERSION = 1\nconst MAX_DAILY_RECORDS = 90 // Keep 90 days of history\nconst SAVE_DEBOUNCE_MS = 5000 // Debounce file writes to 5 seconds\nconst CURRENT_SESSION_ID = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`\n\n// ============================================\n// Stats Manager Implementation\n// ============================================\n\n/**\n * StatsManager - Singleton class for managing usage statistics\n */\nclass StatsManager {\n  private static instance: StatsManager | null = null\n  private stats: StatsData\n  private isDirty: boolean = false\n  private saveTimeout: NodeJS.Timeout | null = null\n  private sessionStartTime: number | null = null\n\n  private constructor() {\n    this.stats = this.loadStats()\n  }\n\n  /**\n   * Get singleton instance\n   */\n  static getInstance(): StatsManager {\n    if (!StatsManager.instance) {\n      StatsManager.instance = new StatsManager()\n    }\n    return StatsManager.instance\n  }\n\n  /**\n   * Load stats from disk or create default\n   */\n  private loadStats(): StatsData {\n    const statsPath = CONFIG_PATHS.activityFile\n\n    try {\n      if (existsSync(statsPath)) {\n        const data = readFileSync(statsPath, 'utf-8')\n        const parsed = JSON.parse(data) as StatsData\n\n        // Validate version and migrate if needed\n        if (parsed.version !== STATS_VERSION) {\n          return this.migrateStats(parsed)\n        }\n\n        return parsed\n      }\n    } catch (error) {\n      debugLogger.warn('STATS_LOAD_ERROR', {\n        error: error instanceof Error ? error.message : String(error),\n      })\n    }\n\n    return this.createDefaultStats()\n  }\n\n  /**\n   * Create default empty stats structure\n   */\n  private createDefaultStats(): StatsData {\n    const now = new Date().toISOString()\n    return {\n      version: STATS_VERSION,\n      lastUpdated: now,\n      dailyActivity: [],\n      modelUsage: {},\n      toolUsage: {},\n      lifetime: {\n        totalMessages: 0,\n        totalSessions: 0,\n        totalToolCalls: 0,\n        totalTokens: 0,\n        totalCost: 0,\n        firstUsed: now,\n      },\n    }\n  }\n\n  /**\n   * Migrate older stats versions\n   */\n  private migrateStats(oldStats: any): StatsData {\n    // For now, just create fresh stats\n    // Future versions can add migration logic here\n    debugLogger.info('STATS_MIGRATION', {\n      fromVersion: oldStats.version,\n      toVersion: STATS_VERSION,\n    })\n    return this.createDefaultStats()\n  }\n\n  /**\n   * Get today's date string in YYYY-MM-DD format\n   */\n  private getTodayString(): string {\n    return new Date().toISOString().split('T')[0]!\n  }\n\n  /**\n   * Get or create today's activity record\n   */\n  private getOrCreateTodayActivity(): DailyActivity {\n    const today = this.getTodayString()\n    let activity = this.stats.dailyActivity.find(a => a.date === today)\n\n    if (!activity) {\n      activity = {\n        date: today,\n        messageCount: 0,\n        sessionCount: 0,\n        toolCallCount: 0,\n        tokensUsed: 0,\n        costEstimate: 0,\n      }\n      this.stats.dailyActivity.push(activity)\n\n      // Prune old records\n      if (this.stats.dailyActivity.length > MAX_DAILY_RECORDS) {\n        this.stats.dailyActivity = this.stats.dailyActivity\n          .sort((a, b) => b.date.localeCompare(a.date))\n          .slice(0, MAX_DAILY_RECORDS)\n      }\n    }\n\n    return activity\n  }\n\n  /**\n   * Schedule a debounced save\n   */\n  private scheduleSave(): void {\n    this.isDirty = true\n\n    if (this.saveTimeout) {\n      return // Already scheduled\n    }\n\n    this.saveTimeout = setTimeout(() => {\n      this.saveStatsSync()\n      this.saveTimeout = null\n    }, SAVE_DEBOUNCE_MS)\n  }\n\n  /**\n   * Save stats to disk (synchronous, for debounced writes)\n   */\n  private saveStatsSync(): void {\n    if (!this.isDirty) return\n\n    const statsPath = CONFIG_PATHS.activityFile\n\n    try {\n      // Ensure directory exists\n      const dir = dirname(statsPath)\n      if (!existsSync(dir)) {\n        mkdirSync(dir, { recursive: true })\n      }\n\n      this.stats.lastUpdated = new Date().toISOString()\n      writeFileSync(statsPath, JSON.stringify(this.stats, null, 2), 'utf-8')\n      this.isDirty = false\n\n      debugLogger.trace('STATS_SAVED', { path: statsPath })\n    } catch (error) {\n      debugLogger.error('STATS_SAVE_ERROR', {\n        error: error instanceof Error ? error.message : String(error),\n      })\n    }\n  }\n\n  // ============================================\n  // Public API - Recording Methods\n  // ============================================\n\n  /**\n   * Record a message (API call)\n   *\n   * Call this after each API call completes.\n   *\n   * @param model - Model name used\n   * @param inputTokens - Number of input tokens\n   * @param outputTokens - Number of output tokens\n   * @param costUSD - Estimated cost in USD (optional)\n   */\n  recordMessage(\n    model: string,\n    inputTokens: number,\n    outputTokens: number,\n    costUSD: number = 0,\n  ): void {\n    const totalTokens = inputTokens + outputTokens\n\n    // Update daily activity\n    const today = this.getOrCreateTodayActivity()\n    today.messageCount += 1\n    today.tokensUsed += totalTokens\n    today.costEstimate += costUSD\n\n    // Update model usage\n    if (!this.stats.modelUsage[model]) {\n      this.stats.modelUsage[model] = {\n        model,\n        calls: 0,\n        tokens: 0,\n        inputTokens: 0,\n        outputTokens: 0,\n        costEstimate: 0,\n      }\n    }\n    const modelStats = this.stats.modelUsage[model]!\n    modelStats.calls += 1\n    modelStats.tokens += totalTokens\n    modelStats.inputTokens += inputTokens\n    modelStats.outputTokens += outputTokens\n    modelStats.costEstimate += costUSD\n\n    // Update lifetime stats\n    this.stats.lifetime.totalMessages += 1\n    this.stats.lifetime.totalTokens += totalTokens\n    this.stats.lifetime.totalCost += costUSD\n\n    // Update current session if active\n    if (this.stats.currentSession) {\n      this.stats.currentSession.messageCount += 1\n      this.stats.currentSession.model = model\n    }\n\n    this.scheduleSave()\n  }\n\n  /**\n   * Record a tool call\n   *\n   * Call this when a tool execution completes.\n   *\n   * @param toolName - Name of the tool\n   * @param isError - Whether the execution resulted in an error\n   */\n  recordToolCall(toolName: string, isError: boolean = false): void {\n    // Update daily activity\n    const today = this.getOrCreateTodayActivity()\n    today.toolCallCount += 1\n\n    // Update tool usage\n    if (!this.stats.toolUsage[toolName]) {\n      this.stats.toolUsage[toolName] = {\n        toolName,\n        calls: 0,\n        successCount: 0,\n        errorCount: 0,\n      }\n    }\n    const toolStats = this.stats.toolUsage[toolName]!\n    toolStats.calls += 1\n    if (isError) {\n      toolStats.errorCount += 1\n    } else {\n      toolStats.successCount += 1\n    }\n\n    // Update lifetime stats\n    this.stats.lifetime.totalToolCalls += 1\n\n    this.scheduleSave()\n  }\n\n  /**\n   * Record session start\n   *\n   * Call this when a new REPL session starts.\n   */\n  recordSessionStart(): void {\n    this.sessionStartTime = Date.now()\n\n    // Update daily activity\n    const today = this.getOrCreateTodayActivity()\n    today.sessionCount += 1\n\n    // Update lifetime stats\n    this.stats.lifetime.totalSessions += 1\n\n    // Set current session\n    this.stats.currentSession = {\n      sessionId: CURRENT_SESSION_ID,\n      startTime: this.sessionStartTime,\n      messageCount: 0,\n    }\n\n    this.scheduleSave()\n  }\n\n  /**\n   * Record session end\n   *\n   * Call this when a REPL session ends.\n   *\n   * @param durationMs - Session duration in milliseconds (optional, auto-calculated if sessionStart was called)\n   */\n  recordSessionEnd(durationMs?: number): void {\n    const endTime = Date.now()\n\n    if (this.stats.currentSession) {\n      this.stats.currentSession.endTime = endTime\n      this.stats.currentSession.durationMs =\n        durationMs ??\n        (this.sessionStartTime ? endTime - this.sessionStartTime : 0)\n    }\n\n    this.sessionStartTime = null\n\n    // Force immediate save on session end\n    this.isDirty = true\n    this.saveStatsSync()\n  }\n\n  // ============================================\n  // Public API - Query Methods\n  // ============================================\n\n  /**\n   * Get the complete stats data\n   */\n  getStats(): StatsData {\n    return { ...this.stats }\n  }\n\n  /**\n   * Save stats (use for manual saves, e.g., before exit)\n   */\n  saveStats(stats: StatsData): void {\n    this.stats = stats\n    this.isDirty = true\n    this.saveStatsSync()\n  }\n\n  /**\n   * Get today's activity statistics\n   */\n  getTodayStats(): DailyActivity | null {\n    const today = this.getTodayString()\n    return this.stats.dailyActivity.find(a => a.date === today) ?? null\n  }\n\n  /**\n   * Get statistics for the last N days\n   *\n   * @param days - Number of days to retrieve\n   */\n  getStatsForDays(days: number): DailyActivity[] {\n    const cutoffDate = new Date()\n    cutoffDate.setDate(cutoffDate.getDate() - days)\n    const cutoffString = cutoffDate.toISOString().split('T')[0]!\n\n    return this.stats.dailyActivity\n      .filter(a => a.date >= cutoffString)\n      .sort((a, b) => b.date.localeCompare(a.date))\n  }\n\n  /**\n   * Get model usage statistics\n   */\n  getModelUsageStats(): ModelUsage[] {\n    return Object.values(this.stats.modelUsage).sort(\n      (a, b) => b.calls - a.calls,\n    )\n  }\n\n  /**\n   * Get tool usage statistics\n   */\n  getToolUsageStats(): ToolUsage[] {\n    return Object.values(this.stats.toolUsage).sort((a, b) => b.calls - a.calls)\n  }\n\n  /**\n   * Get lifetime statistics summary\n   */\n  getLifetimeStats(): StatsData['lifetime'] {\n    return { ...this.stats.lifetime }\n  }\n\n  /**\n   * Estimate cost for a given model and token count\n   *\n   * Simple cost estimation based on known model pricing.\n   * Returns 0 for unknown models.\n   *\n   * @param model - Model name\n   * @param inputTokens - Number of input tokens\n   * @param outputTokens - Number of output tokens\n   */\n  estimateCost(\n    model: string,\n    inputTokens: number,\n    outputTokens: number,\n  ): number {\n    // Default pricing (USD per million tokens)\n    const pricing: Record<string, { input: number; output: number }> = {\n      // Claude models\n      'claude-3-opus': { input: 15, output: 75 },\n      'claude-3-sonnet': { input: 3, output: 15 },\n      'claude-3-haiku': { input: 0.25, output: 1.25 },\n      'claude-sonnet-4': { input: 3, output: 15 },\n      // GPT models\n      'gpt-4': { input: 30, output: 60 },\n      'gpt-4-turbo': { input: 10, output: 30 },\n      'gpt-4o': { input: 5, output: 15 },\n      'gpt-4o-mini': { input: 0.15, output: 0.6 },\n      'gpt-3.5-turbo': { input: 0.5, output: 1.5 },\n      // Default for unknown models\n      default: { input: 3, output: 15 },\n    }\n\n    // Find matching pricing (partial match)\n    let modelPricing = pricing.default!\n    for (const [key, price] of Object.entries(pricing)) {\n      if (key !== 'default' && model.toLowerCase().includes(key)) {\n        modelPricing = price\n        break\n      }\n    }\n\n    return (\n      (inputTokens / 1_000_000) * modelPricing.input +\n      (outputTokens / 1_000_000) * modelPricing.output\n    )\n  }\n\n  /**\n   * Reset statistics (for testing)\n   */\n  resetForTests(): void {\n    if (process.env.NODE_ENV !== 'test') {\n      throw new Error('resetForTests can only be called in tests')\n    }\n    this.stats = this.createDefaultStats()\n    this.isDirty = false\n    this.sessionStartTime = null\n    if (this.saveTimeout) {\n      clearTimeout(this.saveTimeout)\n      this.saveTimeout = null\n    }\n  }\n\n  /**\n   * Force immediate save (for graceful shutdown)\n   */\n  forceImmediateSave(): void {\n    if (this.saveTimeout) {\n      clearTimeout(this.saveTimeout)\n      this.saveTimeout = null\n    }\n    this.isDirty = true\n    this.saveStatsSync()\n  }\n}\n\n// ============================================\n// Exported Singleton and Convenience Functions\n// ============================================\n\nexport const statsManager = StatsManager.getInstance()\n\n/**\n * Get complete statistics data\n */\nexport function getStats(): StatsData {\n  return statsManager.getStats()\n}\n\n/**\n * Save statistics data\n */\nexport function saveStats(stats: StatsData): void {\n  statsManager.saveStats(stats)\n}\n\n/**\n * Record a message (API call)\n */\nexport function recordMessage(\n  model: string,\n  inputTokens: number,\n  outputTokens: number,\n  costUSD?: number,\n): void {\n  statsManager.recordMessage(model, inputTokens, outputTokens, costUSD)\n}\n\n/**\n * Record a tool call\n */\nexport function recordToolCall(toolName: string, isError?: boolean): void {\n  statsManager.recordToolCall(toolName, isError)\n}\n\n/**\n * Record session start\n */\nexport function recordSessionStart(): void {\n  statsManager.recordSessionStart()\n}\n\n/**\n * Record session end\n */\nexport function recordSessionEnd(durationMs?: number): void {\n  statsManager.recordSessionEnd(durationMs)\n}\n\n/**\n * Get today's statistics\n */\nexport function getTodayStats(): DailyActivity | null {\n  return statsManager.getTodayStats()\n}\n\n/**\n * Get statistics for the last N days\n */\nexport function getStatsForDays(days: number): DailyActivity[] {\n  return statsManager.getStatsForDays(days)\n}\n\n/**\n * Get model usage statistics\n */\nexport function getModelUsageStats(): ModelUsage[] {\n  return statsManager.getModelUsageStats()\n}\n\n/**\n * Get tool usage statistics\n */\nexport function getToolUsageStats(): ToolUsage[] {\n  return statsManager.getToolUsageStats()\n}\n\n/**\n * Estimate cost for model and tokens\n */\nexport function estimateCost(\n  model: string,\n  inputTokens: number,\n  outputTokens: number,\n): number {\n  return statsManager.estimateCost(model, inputTokens, outputTokens)\n}\n\n/**\n * Force immediate save (for graceful shutdown)\n */\nexport function forceImmediateSave(): void {\n  statsManager.forceImmediateSave()\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/utils/stringSubstitution.js

@@ -0,0 +1,106 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+const execAsync = promisify(exec);
+const DEFAULT_CONTEXT = {
+  sessionId: "",
+  cwd: process.cwd(),
+  env: {},
+  allowDynamicCommands: false,
+  commandTimeout: 1e4
+};
+async function substituteVariables(content, args, context = {}) {
+  const ctx = { ...DEFAULT_CONTEXT, ...context };
+  let result = content;
+  const argValues = args.trim() ? args.trim().split(/\s+/) : [];
+  result = result.replace(/\$ARGUMENTS(?!\[)/g, args);
+  result = result.replace(/\$ARGUMENTS\[(\d+)\]/g, (_, indexStr) => {
+    const index = parseInt(indexStr, 10);
+    return argValues[index] ?? "";
+  });
+  result = result.replace(/\$(\d+)(?!\d)/g, (_, indexStr) => {
+    const index = parseInt(indexStr, 10);
+    return argValues[index] ?? "";
+  });
+  result = result.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/gi, (_, varName) => {
+    switch (varName.toUpperCase()) {
+      case "CLAUDE_SESSION_ID":
+      case "SESSION_ID":
+        return ctx.sessionId || "";
+      case "CWD":
+      case "PWD":
+        return ctx.cwd;
+      default:
+        return ctx.env[varName] ?? process.env[varName] ?? "";
+    }
+  });
+  if (ctx.allowDynamicCommands) {
+    const commandPattern = /!\`([^`]+)\`/g;
+    const matches = [...result.matchAll(commandPattern)];
+    for (const match of matches) {
+      const command = match[1];
+      try {
+        const { stdout } = await execAsync(command, {
+          timeout: ctx.commandTimeout,
+          cwd: ctx.cwd
+        });
+        result = result.replace(match[0], stdout.trim());
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        result = result.replace(match[0], `(error: ${errorMessage})`);
+      }
+    }
+  } else {
+    result = result.replace(/!\`([^`]+)\`/g, "(dynamic commands disabled)");
+  }
+  return result;
+}
+function hasSubstitutionPatterns(content) {
+  return /\$(?:ARGUMENTS|\d+|\{[A-Z_][A-Z0-9_]*\})|!\`/.test(content);
+}
+function extractSubstitutionPatterns(content) {
+  const patterns = {
+    arguments: [],
+    indexedArgs: [],
+    variables: [],
+    commands: []
+  };
+  if (/\$ARGUMENTS(?!\[)/.test(content)) {
+    patterns.arguments.push("$ARGUMENTS");
+  }
+  const argIndexMatches = content.matchAll(/\$ARGUMENTS\[(\d+)\]/g);
+  for (const match of argIndexMatches) {
+    patterns.indexedArgs.push(parseInt(match[1], 10));
+  }
+  const shortIndexMatches = content.matchAll(/\$(\d+)(?!\d)/g);
+  for (const match of shortIndexMatches) {
+    patterns.indexedArgs.push(parseInt(match[1], 10));
+  }
+  const varMatches = content.matchAll(/\$\{([A-Z_][A-Z0-9_]*)\}/gi);
+  for (const match of varMatches) {
+    patterns.variables.push(match[1]);
+  }
+  const cmdMatches = content.matchAll(/!\`([^`]+)\`/g);
+  for (const match of cmdMatches) {
+    patterns.commands.push(match[1]);
+  }
+  patterns.indexedArgs = [...new Set(patterns.indexedArgs)].sort(
+    (a, b) => a - b
+  );
+  patterns.variables = [...new Set(patterns.variables)];
+  return patterns;
+}
+function validateArguments(args, patterns) {
+  const argValues = args.trim() ? args.trim().split(/\s+/) : [];
+  const maxIndex = Math.max(...patterns.indexedArgs, -1);
+  if (maxIndex >= 0 && argValues.length <= maxIndex) {
+    return `Expected at least ${maxIndex + 1} argument(s), got ${argValues.length}`;
+  }
+  return null;
+}
+export {
+  extractSubstitutionPatterns,
+  hasSubstitutionPatterns,
+  substituteVariables,
+  validateArguments
+};
+//# sourceMappingURL=stringSubstitution.js.map

package/dist/utils/stringSubstitution.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/stringSubstitution.ts"],
+  "sourcesContent": ["/**\n * String Substitution Engine\n *\n * Implements Claude Code skill specification for variable substitution.\n * Supports the following patterns:\n *\n * - $ARGUMENTS       - All arguments as a single string\n * - $ARGUMENTS[N]    - Indexed argument (0-based)\n * - $N               - Shorthand for $ARGUMENTS[N]\n * - ${VARIABLE_NAME} - Environment variable or context variable\n * - !`command`       - Dynamic command execution (with security controls)\n */\n\nimport { exec } from 'child_process'\nimport { promisify } from 'util'\n\nconst execAsync = promisify(exec)\n\n/**\n * Context for string substitution\n */\nexport interface SubstitutionContext {\n  sessionId?: string\n  cwd?: string\n  env?: Record<string, string>\n  /**\n   * Allow dynamic command execution (!`command`)\n   * Default: false (security consideration)\n   */\n  allowDynamicCommands?: boolean\n  /**\n   * Timeout for dynamic command execution in milliseconds\n   * Default: 10000 (10 seconds)\n   */\n  commandTimeout?: number\n}\n\n/**\n * Default substitution context\n */\nconst DEFAULT_CONTEXT: Required<SubstitutionContext> = {\n  sessionId: '',\n  cwd: process.cwd(),\n  env: {},\n  allowDynamicCommands: false,\n  commandTimeout: 10000,\n}\n\n/**\n * Substitute variables in a string\n *\n * @param content - The content to substitute variables in\n * @param args - Arguments string (space-separated)\n * @param context - Substitution context\n * @returns The content with variables substituted\n */\nexport async function substituteVariables(\n  content: string,\n  args: string,\n  context: SubstitutionContext = {},\n): Promise<string> {\n  const ctx = { ...DEFAULT_CONTEXT, ...context }\n  let result = content\n  const argValues = args.trim() ? args.trim().split(/\\s+/) : []\n\n  // 1. $ARGUMENTS - All arguments as a single string\n  // Use negative lookahead to avoid matching $ARGUMENTS[N]\n  result = result.replace(/\\$ARGUMENTS(?!\\[)/g, args)\n\n  // 2. $ARGUMENTS[N] - Indexed argument (0-based)\n  result = result.replace(/\\$ARGUMENTS\\[(\\d+)\\]/g, (_, indexStr) => {\n    const index = parseInt(indexStr, 10)\n    return argValues[index] ?? ''\n  })\n\n  // 3. $N - Shorthand for indexed argument (0-based)\n  // Use negative lookahead to avoid matching multi-digit or $ARGUMENTS\n  result = result.replace(/\\$(\\d+)(?!\\d)/g, (_, indexStr) => {\n    const index = parseInt(indexStr, 10)\n    return argValues[index] ?? ''\n  })\n\n  // 4. ${VARIABLE_NAME} - Context and environment variables\n  result = result.replace(/\\$\\{([A-Z_][A-Z0-9_]*)\\}/gi, (_, varName) => {\n    // Built-in context variables (Claude Code spec)\n    switch (varName.toUpperCase()) {\n      case 'CLAUDE_SESSION_ID':\n      case 'SESSION_ID':\n        return ctx.sessionId || ''\n      case 'CWD':\n      case 'PWD':\n        return ctx.cwd\n      default:\n        // Check custom context env first, then process.env\n        return ctx.env[varName] ?? process.env[varName] ?? ''\n    }\n  })\n\n  // 5. !`command` - Dynamic command execution\n  // Only execute if explicitly allowed (security consideration)\n  if (ctx.allowDynamicCommands) {\n    const commandPattern = /!\\`([^`]+)\\`/g\n    const matches = [...result.matchAll(commandPattern)]\n\n    for (const match of matches) {\n      const command = match[1]\n      try {\n        const { stdout } = await execAsync(command, {\n          timeout: ctx.commandTimeout,\n          cwd: ctx.cwd,\n        })\n        result = result.replace(match[0], stdout.trim())\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : String(error)\n        result = result.replace(match[0], `(error: ${errorMessage})`)\n      }\n    }\n  } else {\n    // Replace !`command` with placeholder when not allowed\n    result = result.replace(/!\\`([^`]+)\\`/g, '(dynamic commands disabled)')\n  }\n\n  return result\n}\n\n/**\n * Check if a string contains substitution patterns\n * Useful for optimization - skip substitution if no patterns present\n */\nexport function hasSubstitutionPatterns(content: string): boolean {\n  return /\\$(?:ARGUMENTS|\\d+|\\{[A-Z_][A-Z0-9_]*\\})|!\\`/.test(content)\n}\n\n/**\n * Extract all substitution patterns from a string\n * Useful for validation and documentation\n */\nexport function extractSubstitutionPatterns(content: string): {\n  arguments: string[]\n  indexedArgs: number[]\n  variables: string[]\n  commands: string[]\n} {\n  const patterns = {\n    arguments: [] as string[],\n    indexedArgs: [] as number[],\n    variables: [] as string[],\n    commands: [] as string[],\n  }\n\n  // $ARGUMENTS\n  if (/\\$ARGUMENTS(?!\\[)/.test(content)) {\n    patterns.arguments.push('$ARGUMENTS')\n  }\n\n  // $ARGUMENTS[N]\n  const argIndexMatches = content.matchAll(/\\$ARGUMENTS\\[(\\d+)\\]/g)\n  for (const match of argIndexMatches) {\n    patterns.indexedArgs.push(parseInt(match[1], 10))\n  }\n\n  // $N\n  const shortIndexMatches = content.matchAll(/\\$(\\d+)(?!\\d)/g)\n  for (const match of shortIndexMatches) {\n    patterns.indexedArgs.push(parseInt(match[1], 10))\n  }\n\n  // ${VARIABLE}\n  const varMatches = content.matchAll(/\\$\\{([A-Z_][A-Z0-9_]*)\\}/gi)\n  for (const match of varMatches) {\n    patterns.variables.push(match[1])\n  }\n\n  // !`command`\n  const cmdMatches = content.matchAll(/!\\`([^`]+)\\`/g)\n  for (const match of cmdMatches) {\n    patterns.commands.push(match[1])\n  }\n\n  // Deduplicate indexed args\n  patterns.indexedArgs = [...new Set(patterns.indexedArgs)].sort(\n    (a, b) => a - b,\n  )\n  patterns.variables = [...new Set(patterns.variables)]\n\n  return patterns\n}\n\n/**\n * Validate arguments against expected patterns\n * Returns error message if validation fails, null if valid\n */\nexport function validateArguments(\n  args: string,\n  patterns: ReturnType<typeof extractSubstitutionPatterns>,\n): string | null {\n  const argValues = args.trim() ? args.trim().split(/\\s+/) : []\n  const maxIndex = Math.max(...patterns.indexedArgs, -1)\n\n  if (maxIndex >= 0 && argValues.length <= maxIndex) {\n    return `Expected at least ${maxIndex + 1} argument(s), got ${argValues.length}`\n  }\n\n  return null\n}\n"],
+  "mappings": "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",
+  "names": []
+}