@statforge/claudestat 1.1.1 → 1.2.2

package/dist/mcp-server.js

@@ -0,0 +1,442 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+"use strict";
+/**
+ * mcp-server.ts — MCP (Model Context Protocol) server for claudestat
+ *
+ * Exposes Claude Code usage metrics as tools that Claude can query.
+ * Zero extra dependencies — stdio JSON-RPC 2.0, readline only.
+ * Works without the daemon — reads SQLite + JSONL directly.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+process.on('warning', (w) => {
+    if (w.name === 'ExperimentalWarning' && w.message.includes('SQLite'))
+        return;
+    process.stderr.write(`${w.name}: ${w.message}\n`);
+});
+const readline = __importStar(require("readline"));
+const db_1 = require("./db");
+const quota_tracker_1 = require("./quota-tracker");
+const insights_1 = require("./insights");
+const config_1 = require("./config");
+const SERVER_NAME = 'claudestat';
+const SERVER_VERSION = '1.2.2';
+const PROTOCOL_VERSION = '2025-03-26';
+const TOOLS = [
+    {
+        name: 'get_quota_status',
+        description: 'Get current Claude Code quota status: 5h cycle usage %, plan type, weekly hours per model, and burn rate (tokens/min)',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: 'get_current_session',
+        description: 'Get details about the most recent Claude Code session: cost, tokens, efficiency score, and loops detected',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: 'get_session_stats',
+        description: 'Get aggregated session statistics for the last N days: session count, total cost, total tokens, loops, and average efficiency',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Number of days to look back (1–90, default 7)'
+                }
+            },
+            required: []
+        }
+    },
+    {
+        name: 'get_top_tools',
+        description: 'Get the top 10 most used tools by cost, call count, or duration in the last N days',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Days to look back (default 30)'
+                },
+                sort_by: {
+                    type: 'string',
+                    description: 'Sort by: cost, count, or duration (default cost)'
+                }
+            },
+            required: []
+        }
+    },
+    {
+        name: 'get_usage_insights',
+        description: 'Get unique usage insights not available in /usage: cost per project, cache savings, output/input ratio, efficiency trend, and peak hours',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Days to look back (default 7)'
+                }
+            },
+            required: []
+        }
+    },
+    {
+        name: 'get_model_breakdown',
+        description: 'Get cost and session count broken down by Claude model (Sonnet, Haiku, Opus) for the last N days',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Days to look back (default 7)'
+                }
+            },
+            required: []
+        }
+    },
+    {
+        name: 'get_weekly_insight',
+        description: 'Get the weekly usage summary with an actionable tip (same as claudestat weekly command)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Days to look back (default 7)'
+                }
+            },
+            required: []
+        }
+    }
+];
+function fmtDollar(n) {
+    if (n === 0)
+        return '$0.00';
+    if (n < 0.01)
+        return '< $0.01';
+    return `$${n.toFixed(2)}`;
+}
+function fmtTok(n) {
+    if (n >= 1000000)
+        return `${(n / 1000000).toFixed(1)}M`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}K`;
+    return n.toString();
+}
+function toolGetQuotaStatus() {
+    const q = (0, quota_tracker_1.computeQuota)();
+    const resetMin = Math.ceil(q.cycleResetMs / 60000);
+    const resetLabel = resetMin >= 60
+        ? `${Math.floor(resetMin / 60)}h ${resetMin % 60}m`
+        : `${resetMin}m`;
+    const weeklyTotalHours = q.weeklyHoursSonnet + q.weeklyHoursOpus;
+    const weeklyLimitTotal = q.weeklyLimitSonnet + q.weeklyLimitOpus;
+    const planLabel = q.planSource === 'inferred'
+        ? `${q.detectedPlan.toUpperCase()} plan (unverified — checking API...)`
+        : `${q.detectedPlan.toUpperCase()} plan`;
+    const parts = [
+        `Quota status — ${planLabel}`,
+        ``,
+        `5h cycle:    ${q.cyclePct}%  ·  ${q.cyclePrompts > q.cycleLimit ? `${q.cyclePrompts}/${q.cycleLimit} prompts (OVER LIMIT)` : `${q.cyclePrompts}/${q.cycleLimit} prompts`}  ·  resets in ${resetLabel}`,
+        `Weekly:      ${weeklyTotalHours}h / ${weeklyLimitTotal}h (${q.weeklyPctAll}%)`,
+    ];
+    if (q.weeklyLimitOpus > 0) {
+        parts.push(`   ├─ Sonnet  ${q.weeklyHoursSonnet}h / ${q.weeklyLimitSonnet}h`);
+        parts.push(`   └─ Opus    ${q.weeklyHoursOpus}h / ${q.weeklyLimitOpus}h`);
+    }
+    if (q.burnRateTokensPerMin > 0) {
+        parts.push(`Burn rate:   ${q.burnRateTokensPerMin.toLocaleString()} tokens/min`);
+    }
+    // Active alerts — only shown when thresholds are crossed
+    const cfg = (0, config_1.readConfig)();
+    if (cfg.alertsEnabled) {
+        const alerts = [];
+        const cycleLevel = (0, config_1.getWarnLevel)(q.cyclePct, cfg.warnThresholds);
+        const weeklyLevel = (0, config_1.getWarnLevel)(q.weeklyPctAll, cfg.weeklyWarnThresholds);
+        if (cycleLevel === 'red')
+            alerts.push(`🔴 5h cycle at ${q.cyclePct}% — critical, limit imminent`);
+        else if (cycleLevel)
+            alerts.push(`⚠️  5h cycle at ${q.cyclePct}% — approaching limit`);
+        if (weeklyLevel === 'red')
+            alerts.push(`🔴 Weekly at ${q.weeklyPctAll}% — critical`);
+        else if (weeklyLevel)
+            alerts.push(`⚠️  Weekly at ${q.weeklyPctAll}% — approaching weekly limit`);
+        if (q.cyclePrompts > q.cycleLimit) {
+            alerts.push(`⚠️  Prompt count (${q.cyclePrompts}) exceeds plan limit (${q.cycleLimit}) — plan may be mis-detected`);
+        }
+        const reminderMins = cfg.resetReminderMins ?? 10;
+        if (reminderMins > 0 && resetMin <= reminderMins && resetMin > 0) {
+            alerts.push(`⏰  Cycle resets in ${resetMin}m — good time to wrap up or start fresh`);
+        }
+        if (alerts.length > 0) {
+            parts.push(``);
+            parts.push(`─── ACTIVE ALERTS ───────────────────────`);
+            parts.push(...alerts);
+        }
+    }
+    return parts.join('\n');
+}
+function toolGetCurrentSession() {
+    const session = db_1.dbOps.getLatestSession();
+    if (!session)
+        return 'No sessions recorded yet.';
+    const cost = fmtDollar(session.total_cost_usd ?? 0);
+    const inp = fmtTok(session.total_input_tokens ?? 0);
+    const out = fmtTok(session.total_output_tokens ?? 0);
+    const cache = fmtTok(session.total_cache_read ?? 0);
+    const eff = session.efficiency_score ?? 100;
+    const loops = session.loops_detected ?? 0;
+    const started = new Date(session.started_at).toISOString();
+    const project = session.project_path ?? 'No project';
+    const model = session.dominant_model ?? 'unknown';
+    return [
+        `Latest session: ${session.id.slice(0, 8)}...`,
+        ``,
+        `Project:    ${project}`,
+        `Model:      ${model}`,
+        `Started:    ${started}`,
+        `Cost:       ${cost}`,
+        `Tokens:     ${inp} in + ${out} out  (${cache} cache read)`,
+        `Efficiency: ${eff}/100`,
+        `Loops:      ${loops}`,
+    ].join('\n');
+}
+function toolGetSessionStats(days) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 7)));
+    const insight = db_1.dbOps.getWeeklyInsight(d);
+    if (!insight || insight.total_sessions === 0)
+        return `No sessions in the last ${d} days.`;
+    const totalTok = insight.input_tokens + insight.output_tokens;
+    return [
+        `Session stats — last ${d} days`,
+        ``,
+        `Sessions:     ${insight.total_sessions}`,
+        `Cost:         ${fmtDollar(insight.total_cost)}`,
+        `Tokens:       ${fmtTok(totalTok)} (${fmtTok(insight.input_tokens)} in + ${fmtTok(insight.output_tokens)} out)`,
+        `Cache read:   ${fmtTok(insight.cache_read)}`,
+        `Loops:        ${insight.total_loops}`,
+        `Efficiency:   ${Math.round(insight.avg_efficiency)}/100 avg`,
+    ].join('\n');
+}
+function toolGetTopTools(days, sortBy) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 30)));
+    const sort = (sortBy === 'count' || sortBy === 'duration') ? sortBy : 'cost';
+    const tools = db_1.dbOps.getTopTools(d, sort, 10);
+    if (tools.length === 0)
+        return `No tool usage data in the last ${d} days.`;
+    const lines = [
+        `Top tools — last ${d} days (sorted by ${sort})`,
+        '',
+    ];
+    for (let i = 0; i < tools.length; i++) {
+        const t = tools[i];
+        const idx = `${i + 1}.`.padEnd(4);
+        const name = t.tool_name.padEnd(14);
+        const cnt = `${t.count} calls`.padEnd(14);
+        const dur = t.total_duration_ms > 0
+            ? `${(t.total_duration_ms / 1000).toFixed(1)}s`.padEnd(10)
+            : '—'.padEnd(10);
+        const cost = fmtDollar(t.total_cost_usd);
+        lines.push(`  ${idx}${name}${cnt}${dur}${cost}`);
+    }
+    return lines.join('\n');
+}
+function toolGetUsageInsights(days) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 7)));
+    const i = (0, insights_1.getUsageInsights)(d);
+    if (i.total_sessions === 0)
+        return `No data for the last ${d} days.`;
+    const bar = (pct, width = 20) => '█'.repeat(Math.round(pct / 100 * width)) + '░'.repeat(width - Math.round(pct / 100 * width));
+    const lines = [];
+    lines.push(`💡 Usage insights — last ${d} days`);
+    lines.push('━'.repeat(44));
+    lines.push(``);
+    lines.push(`  💰  ${fmtDollar(i.avg_cost_per_session)}/session  ·  ${i.total_sessions} sessions  ·  ${fmtDollar(i.total_cost)} total`);
+    if (i.project_costs.length > 0) {
+        lines.push(``);
+        lines.push(`  🗂  Top projects`);
+        const topTotal = i.project_costs.reduce((s, p) => s + p.total_cost, 0);
+        for (const p of i.project_costs.slice(0, 4)) {
+            const pct = topTotal > 0 ? Math.round(p.total_cost / topTotal * 100) : 0;
+            const name = (p.project.split('/').pop() ?? p.project).slice(0, 14).padEnd(14);
+            lines.push(`     ${name}  ${bar(pct)}  ${fmtDollar(p.total_cost)}  ${pct}%`);
+        }
+    }
+    lines.push(``);
+    lines.push(`  ⚡  Cache ~${fmtDollar(i.cache_savings_usd)} saved  ·  ${i.cache_hit_pct}% hit rate`);
+    lines.push(``);
+    lines.push(`  📊  ${i.output_input_ratio}× output/input  ·  ${i.ratio_label}`);
+    lines.push(``);
+    const effTrend = i.efficiency_delta !== -999
+        ? `  ${i.efficiency_delta > 0 ? `↑ +${i.efficiency_delta}` : i.efficiency_delta < 0 ? `↓ ${i.efficiency_delta}` : '→ same'} vs prev period`
+        : '';
+    lines.push(`  📈  Efficiency  ${i.avg_efficiency}/100${effTrend}  ·  ${i.total_loops} loops`);
+    if (i.hour_ranges.length > 0) {
+        lines.push(``);
+        lines.push(`  ⏰  Activity by time of day`);
+        const maxCount = Math.max(...i.hour_ranges.map(r => r.count));
+        for (let j = 0; j < i.hour_ranges.length; j++) {
+            const r = i.hour_ranges[j];
+            const pct = maxCount > 0 ? Math.round(r.count / maxCount * 100) : 0;
+            lines.push(`     ${r.emoji}  ${r.from}–${r.to}  ${bar(pct)}  ${r.count} sessions`);
+            if (j < i.hour_ranges.length - 1)
+                lines.push('');
+        }
+    }
+    lines.push(``);
+    lines.push('━'.repeat(44));
+    return lines.join('\n');
+}
+function toolGetModelBreakdown(days) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 7)));
+    const models = db_1.dbOps.getModelBreakdown(d);
+    if (models.length === 0)
+        return `No model data in the last ${d} days.`;
+    const totalCost = models.reduce((s, m) => s + m.total_cost, 0);
+    const lines = [
+        `Model breakdown — last ${d} days`,
+        '',
+    ];
+    for (const m of models) {
+        const pct = totalCost > 0 ? Math.round(m.total_cost / totalCost * 100) : 0;
+        const rawName = (m.model ?? 'unknown').replace(/^<|>$/g, '');
+        const name = rawName.padEnd(30);
+        const cost = fmtDollar(m.total_cost).padEnd(10);
+        lines.push(`  ${name}${cost}${pct}%   ${m.session_count} sessions`);
+    }
+    return lines.join('\n');
+}
+function toolGetWeeklyInsight(days) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 7)));
+    const data = (0, insights_1.getWeeklyInsightData)(d);
+    if (data.total_sessions === 0)
+        return `No usage data for the last ${d} days.`;
+    const fmtDate = (ts) => {
+        const dt = new Date(ts);
+        return dt.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+    };
+    return [
+        `Weekly insight (${fmtDate(data.week_start)} – ${fmtDate(data.week_end)})`,
+        `──────────────────────────────────────────────`,
+        `Sessions: ${data.total_sessions}  ·  Cost: ${fmtDollar(data.total_cost)}  ·  Loops: ${data.total_loops}`,
+        `Top tool: ${data.top_tool} (${data.top_tool_cost_pct}% of cost)  ·  Efficiency: ${data.avg_efficiency}/100`,
+        `Tokens: ${fmtTok(data.input_tokens)} in + ${fmtTok(data.output_tokens)} out  ·  Cache hit: ${data.cache_hit_pct}%`,
+        `Tip: ${(0, insights_1.generateTip)(data)}`,
+    ].join('\n');
+}
+async function handleToolCall(name, args) {
+    const sortBy = typeof args.sort_by === 'string' ? args.sort_by : 'cost';
+    switch (name) {
+        case 'get_quota_status':
+            await (0, quota_tracker_1.refreshFromApi)();
+            return toolGetQuotaStatus();
+        case 'get_current_session': return toolGetCurrentSession();
+        case 'get_session_stats': return toolGetSessionStats(typeof args.days === 'number' ? args.days : 7);
+        case 'get_top_tools': return toolGetTopTools(typeof args.days === 'number' ? args.days : 30, sortBy);
+        case 'get_usage_insights': return toolGetUsageInsights(typeof args.days === 'number' ? args.days : 7);
+        case 'get_model_breakdown': return toolGetModelBreakdown(typeof args.days === 'number' ? args.days : 7);
+        case 'get_weekly_insight': return toolGetWeeklyInsight(typeof args.days === 'number' ? args.days : 7);
+        default: return `Unknown tool: ${name}`;
+    }
+}
+async function handleRequest(msg) {
+    const { id, method, params } = msg;
+    if (id === undefined)
+        return null;
+    try {
+        switch (method) {
+            case 'initialize':
+                return {
+                    jsonrpc: '2.0', id,
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        capabilities: { tools: {} },
+                        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION }
+                    }
+                };
+            case 'tools/list':
+                return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+            case 'tools/call': {
+                const toolName = params?.name;
+                const toolArgs = (params?.arguments ?? {});
+                const text = await handleToolCall(toolName, toolArgs);
+                return {
+                    jsonrpc: '2.0', id,
+                    result: { content: [{ type: 'text', text }], isError: false }
+                };
+            }
+            default:
+                return {
+                    jsonrpc: '2.0', id,
+                    error: { code: -32601, message: `Method not found: ${method}` }
+                };
+        }
+    }
+    catch (e) {
+        return {
+            jsonrpc: '2.0', id,
+            result: { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+        };
+    }
+}
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    try {
+        const msg = JSON.parse(trimmed);
+        handleRequest(msg).then(response => {
+            if (response)
+                process.stdout.write(JSON.stringify(response) + '\n');
+        }).catch((e) => {
+            process.stderr.write(`[claudestat-mcp] Handler error: ${e.message}\n`);
+        });
+    }
+    catch (e) {
+        process.stderr.write(`[claudestat-mcp] Parse error: ${e.message}\n`);
+    }
+});
+process.on('SIGTERM', () => process.exit(0));
+process.on('SIGINT', () => process.exit(0));
+// API quota is refreshed on-demand per get_quota_status call (disk cache throttles to 1 call/5min)
+process.stderr.write(`[claudestat-mcp] Server ready (stdio, protocol ${PROTOCOL_VERSION})\n`);

package/dist/notifier.js

@@ -8,15 +8,33 @@ const child_process_1 = require("child_process");
 const os_1 = __importDefault(require("os"));
 function sendDesktopNotification(title, body) {
     try {
-        if (os_1.default.platform() === 'darwin') {
-            const escaped = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-            (0, child_process_1.execSync)(`osascript -e 'display notification "${escaped}" with title "${title}"'`, { stdio: 'ignore' });
+        const platform = os_1.default.platform();
+        if (platform === 'darwin') {
+            const t = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            const b = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            (0, child_process_1.execSync)(`osascript -e 'display notification "${b}" with title "${t}"'`, { stdio: 'ignore', timeout: 5000 });
         }
-        else if (os_1.default.platform() === 'linux') {
-            (0, child_process_1.execSync)(`notify-send "${title}" "${body}"`, { stdio: 'ignore' });
+        else if (platform === 'linux') {
+            (0, child_process_1.execSync)(`notify-send "${title}" "${body}"`, { stdio: 'ignore', timeout: 5000 });
+        }
+        else if (platform === 'win32') {
+            // UTF-16LE base64-encoded PowerShell to handle any special characters safely
+            const script = [
+                `Add-Type -AssemblyName System.Windows.Forms`,
+                `$n = New-Object System.Windows.Forms.NotifyIcon`,
+                `$n.Icon = [System.Drawing.SystemIcons]::Information`,
+                `$n.BalloonTipIcon = [System.Windows.Forms.ToolTipIcon]::Info`,
+                `$n.BalloonTipTitle = '${title.replace(/'/g, "''")}'`,
+                `$n.BalloonTipText  = '${body.replace(/'/g, "''")}'`,
+                `$n.Visible = $true`,
+                `$n.ShowBalloonTip(5000)`,
+                `Start-Sleep -Milliseconds 200`,
+            ].join('; ');
+            const encoded = Buffer.from(script, 'utf16le').toString('base64');
+            (0, child_process_1.execSync)(`powershell -NoProfile -NonInteractive -EncodedCommand ${encoded}`, { stdio: 'ignore', timeout: 8000 });
         }
     }
     catch {
-        // notification not available — already logged to console
+        // notification unavailable — silent fallback
     }
 }

package/dist/pattern-analyzer.d.ts

@@ -12,6 +12,7 @@
  *   - High cache ratio → positive: great cost efficiency
  *   - High avg cost    → consider Haiku for simpler tasks
  *   - Low efficiency   → linked to loops
+ *   - Write vs Edit    → suggest Edit for incremental changes
  */
 export type InsightLevel = 'tip' | 'warning' | 'positive';
 export interface PatternInsight {

package/dist/pattern-analyzer.js

@@ -13,6 +13,7 @@
  *   - High cache ratio → positive: great cost efficiency
  *   - High avg cost    → consider Haiku for simpler tasks
  *   - Low efficiency   → linked to loops
+ *   - Write vs Edit    → suggest Edit for incremental changes
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.analyzePatterns = analyzePatterns;
@@ -52,6 +53,18 @@ function analyzePatterns(toolCounts, stats) {
             metric: `${bashPct}% Bash (${bashCount}) vs ${readGrep} Read+Grep+Glob`,
         });
     }
+    // ── Heavy Write vs Edit ────────────────────────────────────────────────────
+    const writeCount = get('Write');
+    const editCount = get('Edit');
+    const writePct = Math.round(writeCount / totalTools * 100);
+    if (writeCount > editCount * 3 && writeCount >= 10) {
+        insights.push({
+            level: 'tip',
+            title: 'Heavy Write vs Edit usage',
+            description: 'More than 3× Write calls vs Edit calls. Editing existing files is cheaper in tokens than writing from scratch. Consider using Edit for incremental changes instead of rewriting entire files.',
+            metric: `${writePct}% Write (${writeCount} writes vs ${editCount} edits)`,
+        });
+    }
     // ── High loop rate ────────────────────────────────────────────────────────
     if (stats.avg_loops >= 1.5) {
         insights.push({

package/dist/quota-tracker.d.ts

@@ -32,11 +32,18 @@ export interface QuotaData {
     weeklyTokensHaiku: number;
     weeklyLimitSonnet: number;
     weeklyLimitOpus: number;
+    weeklyPctAll: number;
     burnRateTokensPerMin: number;
     detectedPlan: ClaudePlan;
     planSource: 'config' | 'keychain' | 'inferred';
     computedAt: number;
 }
+/**
+ * Llama a la API de Anthropic para obtener los % de quota exactos que muestra claude.ai.
+ * Actualiza apiCache si la llamada tiene éxito; de lo contrario, no hace nada (silent fallback).
+ * Debe llamarse periódicamente desde el daemon y al inicio del MCP server.
+ */
+export declare function refreshFromApi(): Promise<void>;
 /**
  * Calcula y retorna QuotaData.
  * Usa caché de 30s para no re-leer todos los JSONL en cada request del dashboard.