@ekkos/cli 0.2.18 → 1.0.0

package/dist/commands/usage/session.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionCommand = sessionCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage session [id] [--list] [--instance id] [--json]
+ *
+ * Accepts ekkOS 3-word names (lit-lex-zip) or ccusage project paths.
+ */
+async function sessionCommand(options) {
+    const instanceId = options.instance;
+    if (options.list) {
+        await listSessions(instanceId, options.json);
+        return;
+    }
+    if (!options.sessionId) {
+        await listSessions(instanceId, options.json);
+        return;
+    }
+    try {
+        let usage = null;
+        // Detect ekkOS 3-word session names and resolve via active-sessions.json
+        if ((0, usage_parser_js_1.isEkkosSessionName)(options.sessionId)) {
+            usage = await (0, usage_parser_js_1.getSessionUsageByName)(options.sessionId);
+            if (!usage) {
+                if (options.json) {
+                    console.log(JSON.stringify({ error: `ekkOS session "${options.sessionId}" not found` }));
+                    return;
+                }
+                console.log(chalk_1.default.yellow(`  ekkOS session "${options.sessionId}" not found.`));
+                console.log(chalk_1.default.gray('  Check available sessions with: ekkos usage session -l'));
+                return;
+            }
+        }
+        else {
+            // Fallback to ccusage project-path lookup
+            usage = await (0, usage_parser_js_1.getSessionUsage)(options.sessionId, instanceId);
+        }
+        if (!usage) {
+            if (options.json) {
+                console.log(JSON.stringify({ error: 'Session not found' }));
+                return;
+            }
+            console.log(chalk_1.default.yellow(`  No usage data found for session: ${options.sessionId}`));
+            return;
+        }
+        if (options.json) {
+            console.log(JSON.stringify(usage, null, 2));
+            return;
+        }
+        displaySessionUsage(usage);
+    }
+    catch (err) {
+        console.log(chalk_1.default.red(`  Error: ${err.message}`));
+    }
+}
+/** Display session usage in formatted table */
+function displaySessionUsage(usage) {
+    (0, formatters_js_1.titleBar)(`Session: ${usage.session_name}`, usage.session_id);
+    (0, formatters_js_1.sectionHeader)('Summary');
+    console.log(`  ${chalk_1.default.bold('Session ID:')}      ${usage.session_id}`);
+    console.log(`  ${chalk_1.default.bold('Turn Count:')}      ${chalk_1.default.green(usage.turn_count.toString())}`);
+    console.log(`  ${chalk_1.default.bold('Total Tokens:')}    ${(0, formatters_js_1.formatNumber)(usage.total_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Avg Context:')}     ${(0, formatters_js_1.formatPercentage)(usage.avg_context_percentage)}`);
+    console.log(`  ${chalk_1.default.bold('Max Context:')}     ${(0, formatters_js_1.formatPercentage)(usage.max_context_percentage)}`);
+    console.log(`  ${chalk_1.default.bold('Started:')}         ${(0, formatters_js_1.formatTimestamp)(usage.started_at)}`);
+    console.log(`  ${chalk_1.default.bold('Last Activity:')}   ${(0, formatters_js_1.formatTimestamp)(usage.last_activity)}`);
+    console.log();
+    (0, formatters_js_1.sectionHeader)('Token Breakdown');
+    console.log(`  ${chalk_1.default.bold('Input Tokens:')}       ${(0, formatters_js_1.formatNumber)(usage.total_input_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Output Tokens:')}      ${(0, formatters_js_1.formatNumber)(usage.total_output_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Cache Read:')}         ${(0, formatters_js_1.formatNumber)(usage.total_cache_read_tokens)} ${chalk_1.default.gray('(90% discount)')}`);
+    console.log(`  ${chalk_1.default.bold('Cache Creation:')}     ${(0, formatters_js_1.formatNumber)(usage.total_cache_creation_tokens)} ${chalk_1.default.gray('(25% premium)')}`);
+    console.log();
+    (0, formatters_js_1.sectionHeader)('Cost');
+    console.log(`  ${chalk_1.default.bold('Total Cost:')}  ${chalk_1.default.green((0, formatters_js_1.formatCost)(usage.total_cost))}`);
+    console.log(`  ${chalk_1.default.bold('Models Used:')} ${chalk_1.default.cyan(usage.models_used.join(', '))}`);
+    console.log();
+    // ekkOS pattern metrics
+    if (usage.patterns_retrieved !== undefined) {
+        (0, formatters_js_1.sectionHeader)('ekkOS Pattern Metrics');
+        console.log(`  ${chalk_1.default.bold('Patterns Retrieved:')}  ${chalk_1.default.cyan(usage.patterns_retrieved.toString())}`);
+        console.log(`  ${chalk_1.default.bold('Patterns Applied:')}    ${chalk_1.default.green(usage.patterns_applied?.toString() || '0')}`);
+        console.log(`  ${chalk_1.default.bold('Patterns Learned:')}    ${chalk_1.default.yellow(usage.patterns_learned?.toString() || '0')}`);
+        console.log(`  ${chalk_1.default.bold('Confidence Gain:')}     ${chalk_1.default.magenta(`+${((usage.confidence_gain || 0) * 100).toFixed(1)}%`)}`);
+        console.log();
+    }
+    // Turn-by-turn breakdown
+    if (usage.turns.length > 0) {
+        (0, formatters_js_1.sectionHeader)('Turn-by-Turn Breakdown');
+        console.log(chalk_1.default.gray('  Turn │ Context % │  Input │ Output │ Cache Read │   Total'));
+        console.log(chalk_1.default.gray('─'.repeat(80)));
+        for (const turn of usage.turns) {
+            const turnStr = turn.turn_number.toString().padStart(4);
+            const contextStr = (0, formatters_js_1.formatPercentage)(turn.context_percentage).padStart(10);
+            const inputStr = (0, formatters_js_1.formatNumber)(turn.input_tokens).padStart(7);
+            const outputStr = (0, formatters_js_1.formatNumber)(turn.output_tokens).padStart(7);
+            const cacheStr = (0, formatters_js_1.formatNumber)(turn.cache_read_tokens).padStart(11);
+            const totalStr = (0, formatters_js_1.formatNumber)(turn.total_tokens).padStart(8);
+            const contextColor = (0, formatters_js_1.getContextColor)(turn.context_percentage);
+            console.log(`  ${turnStr} │ ${contextColor(contextStr)} │ ${inputStr} │ ${outputStr} │ ${cacheStr} │ ${totalStr}`);
+        }
+        console.log();
+    }
+    // VM validation
+    if (usage.turn_count >= 5) {
+        const contextValues = usage.turns.map(t => t.context_percentage);
+        const range = Math.max(...contextValues) - Math.min(...contextValues);
+        if (range < 15) {
+            console.log(chalk_1.default.green.bold('  VM Working: Context staying in constant band'));
+        }
+        else {
+            console.log(chalk_1.default.yellow.bold('  VM Warning: Context growing linearly (check proxy eviction)'));
+        }
+        console.log();
+    }
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}
+/** List available sessions - shows ekkOS sessions by default, falls back to ccusage */
+async function listSessions(instanceId, json) {
+    // Try ekkOS sessions first (individual sessions with 3-word names)
+    const ekkosSessions = await (0, usage_parser_js_1.listEkkosSessions)(30);
+    if (ekkosSessions.length > 0) {
+        if (json) {
+            console.log(JSON.stringify(ekkosSessions, null, 2));
+            return;
+        }
+        (0, formatters_js_1.titleBar)('ekkOS Sessions', `${ekkosSessions.length} recent`);
+        // Find max cost for bar rendering
+        const maxCost = Math.max(...ekkosSessions.map(s => s.cost), 0.01);
+        console.log(chalk_1.default.gray('  Session Name        │ Turns │    Cost │   Tokens │ Models                  │ Started'));
+        console.log(chalk_1.default.gray('  ' + '─'.repeat(100)));
+        for (const s of ekkosSessions) {
+            const name = chalk_1.default.bold.cyan(s.name.padEnd(20));
+            const turns = s.turnCount.toString().padStart(5);
+            const cost = chalk_1.default.green((0, formatters_js_1.formatCost)(s.cost).padStart(7));
+            const tokens = (0, formatters_js_1.formatCompact)(s.tokens).padStart(8);
+            const models = chalk_1.default.gray(s.models
+                .filter(m => !m.includes('synthetic'))
+                .map(m => {
+                if (m.includes('opus-4-6'))
+                    return 'opus-4.6';
+                if (m.includes('opus-4-5'))
+                    return 'opus-4.5';
+                if (m.includes('sonnet-4-5'))
+                    return 'sonnet-4.5';
+                if (m.includes('haiku-4-5'))
+                    return 'haiku-4.5';
+                return m;
+            }).join(', ').padEnd(24));
+            const started = chalk_1.default.gray((0, formatters_js_1.formatTimestamp)(s.startedAt));
+            const bar = (0, formatters_js_1.renderBar)(s.cost, maxCost, 8);
+            console.log(`  ${name}│ ${turns} │ ${cost} │ ${tokens} │ ${models}│ ${started} ${bar}`);
+        }
+        console.log();
+        console.log(chalk_1.default.gray('  Use: ekkos usage session <name>  for detailed breakdown'));
+        console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+        console.log();
+        return;
+    }
+    // Fallback to ccusage project-level sessions
+    const sessions = await (0, usage_parser_js_1.getAllSessions)(instanceId);
+    if (sessions.length === 0) {
+        if (json) {
+            console.log(JSON.stringify([]));
+            return;
+        }
+        (0, formatters_js_1.noData)('session');
+        return;
+    }
+    if (json) {
+        console.log(JSON.stringify(sessions, null, 2));
+        return;
+    }
+    (0, formatters_js_1.titleBar)('Sessions', `${sessions.length} found`);
+    const sorted = [...sessions].sort((a, b) => (b.last_activity || '').localeCompare(a.last_activity || ''));
+    for (const session of sorted) {
+        console.log(`  ${chalk_1.default.bold(session.session_id)}`);
+        console.log(`    ${chalk_1.default.gray('Cost:')} ${chalk_1.default.green((0, formatters_js_1.formatCost)(session.total_cost))}` +
+            `  ${chalk_1.default.gray('Tokens:')} ${(0, formatters_js_1.formatCompact)(session.total_tokens)}` +
+            `  ${chalk_1.default.gray('Last:')} ${session.last_activity}` +
+            `  ${chalk_1.default.gray('Models:')} ${chalk_1.default.cyan(session.models_used.join(', '))}`);
+        console.log();
+    }
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/commands/usage/weekly.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ekkos usage weekly [--weeks N] [--json]
+ *
+ * Show weekly usage breakdown
+ */
+export declare function weeklyCommand(options: {
+    weeks?: number;
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/usage/weekly.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.weeklyCommand = weeklyCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage weekly [--weeks N] [--json]
+ *
+ * Show weekly usage breakdown
+ */
+async function weeklyCommand(options) {
+    const weeks = options.weeks || 8;
+    const data = await (0, usage_parser_js_1.getWeeklyUsage)();
+    if (data.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify([]));
+            return;
+        }
+        (0, formatters_js_1.noData)('weekly usage');
+        return;
+    }
+    // Sort by week date descending
+    const sorted = [...data].sort((a, b) => (b.week || '').localeCompare(a.week || ''));
+    const recent = sorted.slice(0, weeks);
+    if (options.json) {
+        console.log(JSON.stringify(recent, null, 2));
+        return;
+    }
+    (0, formatters_js_1.titleBar)('Weekly Usage Report', `Last ${Math.min(weeks, recent.length)} weeks`);
+    const maxCost = Math.max(...recent.map(w => w.totalCost || 0));
+    let totalCost = 0;
+    console.log(chalk_1.default.gray('  Week of'.padEnd(22)) +
+        chalk_1.default.gray('│ ') +
+        chalk_1.default.gray('Cost'.padStart(10)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Input'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Output'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Cache'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Chart'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    for (const week of recent) {
+        const cost = week.totalCost || 0;
+        totalCost += cost;
+        const weekDate = (0, formatters_js_1.formatDate)(week.week || '');
+        const bar = (0, formatters_js_1.renderBar)(cost, maxCost, 14);
+        console.log(`  ${chalk_1.default.white(weekDate.padEnd(20))} │ ${chalk_1.default.green((0, formatters_js_1.formatCost)(cost).padStart(10))} │ ${(0, formatters_js_1.formatCompact)(week.inputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(week.outputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(week.cacheReadTokens || 0).padStart(8)} │ ${bar}`);
+    }
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(chalk_1.default.bold('  TOTAL'.padEnd(22)) +
+        `│ ${chalk_1.default.green.bold((0, formatters_js_1.formatCost)(totalCost).padStart(10))} │`);
+    console.log();
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/commands/usage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ekkos usage [session-id] [--instance instance-id]
+ *
+ * Track Claude Code session token usage and context percentage
+ * Powered by ccusage (https://ccusage.com)
+ */
+export declare function usageCommand(args: string[]): Promise<void>;

package/dist/commands/usage.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usageCommand = usageCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../lib/usage-parser.js");
+/**
+ * ekkos usage [session-id] [--instance instance-id]
+ *
+ * Track Claude Code session token usage and context percentage
+ * Powered by ccusage (https://ccusage.com)
+ */
+async function usageCommand(args) {
+    const sessionIdArg = args[0];
+    const instanceIdFlag = args.indexOf('--instance');
+    const listFlag = args.includes('--list');
+    // Default instance ID (current project)
+    let instanceId = '-Volumes-MacMiniPort-DEV-EKKOS'; // Default to current project
+    if (instanceIdFlag !== -1 && args[instanceIdFlag + 1]) {
+        instanceId = args[instanceIdFlag + 1];
+    }
+    // List available sessions
+    if (listFlag) {
+        await listAvailableSessions(instanceId);
+        return;
+    }
+    // Show usage for specific session
+    if (!sessionIdArg) {
+        console.log(chalk_1.default.red('❌ Session ID required'));
+        console.log(chalk_1.default.gray('\nUsage:'));
+        console.log(chalk_1.default.gray('  ekkos usage <session-id>              Show usage for session'));
+        console.log(chalk_1.default.gray('  ekkos usage --list                    List available sessions'));
+        console.log(chalk_1.default.gray('  ekkos usage <id> --instance <inst>    Use specific instance'));
+        process.exit(1);
+    }
+    try {
+        console.log(chalk_1.default.gray('Fetching usage data from ccusage...'));
+        const usage = await (0, usage_parser_js_1.getSessionUsage)(sessionIdArg, instanceId);
+        if (!usage) {
+            console.log(chalk_1.default.yellow('⚠️  No usage data found for session'));
+            return;
+        }
+        displaySessionUsage(usage);
+    }
+    catch (err) {
+        console.log(chalk_1.default.red(`❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+}
+/**
+ * Display session usage in formatted table
+ */
+function displaySessionUsage(usage) {
+    console.log();
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log(chalk_1.default.bold.cyan(`  Session Usage: ${usage.session_name}`));
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+    // Summary section
+    console.log(chalk_1.default.bold('📊 Summary'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(`  ${chalk_1.default.bold('Session ID:')}      ${usage.session_id}`);
+    console.log(`  ${chalk_1.default.bold('Turn Count:')}     ${chalk_1.default.green(usage.turn_count.toString())}`);
+    console.log(`  ${chalk_1.default.bold('Total Tokens:')}   ${formatNumber(usage.total_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Avg Context:')}    ${formatPercentage(usage.avg_context_percentage)}`);
+    console.log(`  ${chalk_1.default.bold('Max Context:')}    ${formatPercentage(usage.max_context_percentage)}`);
+    console.log(`  ${chalk_1.default.bold('Started:')}        ${formatTimestamp(usage.started_at)}`);
+    console.log(`  ${chalk_1.default.bold('Last Activity:')}  ${formatTimestamp(usage.last_activity)}`);
+    console.log();
+    // Token breakdown
+    console.log(chalk_1.default.bold('🔢 Token Breakdown'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(`  ${chalk_1.default.bold('Input Tokens:')}       ${formatNumber(usage.total_input_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Output Tokens:')}      ${formatNumber(usage.total_output_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Cache Read:')}         ${formatNumber(usage.total_cache_read_tokens)} ${chalk_1.default.gray('(90% discount)')}`);
+    console.log(`  ${chalk_1.default.bold('Cache Creation:')}     ${formatNumber(usage.total_cache_creation_tokens)} ${chalk_1.default.gray('(25% premium)')}`);
+    console.log();
+    // Cost breakdown
+    console.log(chalk_1.default.bold('💰 Cost'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(`  ${chalk_1.default.bold('Total Cost:')}  ${chalk_1.default.green('$' + usage.total_cost.toFixed(2))}`);
+    console.log(`  ${chalk_1.default.bold('Models Used:')} ${chalk_1.default.cyan(usage.models_used.join(', '))}`);
+    console.log();
+    // ekkOS pattern metrics (if available)
+    if (usage.patterns_retrieved !== undefined) {
+        console.log(chalk_1.default.bold('🧠 ekkOS Pattern Metrics'));
+        console.log(chalk_1.default.gray('─'.repeat(80)));
+        console.log(`  ${chalk_1.default.bold('Patterns Retrieved:')}  ${chalk_1.default.cyan(usage.patterns_retrieved.toString())}`);
+        console.log(`  ${chalk_1.default.bold('Patterns Applied:')}    ${chalk_1.default.green(usage.patterns_applied?.toString() || '0')}`);
+        console.log(`  ${chalk_1.default.bold('Patterns Learned:')}    ${chalk_1.default.yellow(usage.patterns_learned?.toString() || '0')}`);
+        console.log(`  ${chalk_1.default.bold('Confidence Gain:')}     ${chalk_1.default.magenta(`+${((usage.confidence_gain || 0) * 100).toFixed(1)}%`)}`);
+        console.log();
+    }
+    // Turn-by-turn breakdown (if available)
+    if (usage.turns.length > 0) {
+        console.log(chalk_1.default.bold('📈 Turn-by-Turn Breakdown'));
+        console.log(chalk_1.default.gray('─'.repeat(80)));
+        console.log(chalk_1.default.gray('  Turn') +
+            chalk_1.default.gray(' │ ') +
+            chalk_1.default.gray('Context %') +
+            chalk_1.default.gray(' │ ') +
+            chalk_1.default.gray('Input') +
+            chalk_1.default.gray(' │ ') +
+            chalk_1.default.gray('Output') +
+            chalk_1.default.gray(' │ ') +
+            chalk_1.default.gray('Cache Read') +
+            chalk_1.default.gray(' │ ') +
+            chalk_1.default.gray('Total'));
+        console.log(chalk_1.default.gray('─'.repeat(80)));
+        for (const turn of usage.turns) {
+            const turnStr = turn.turn_number.toString().padStart(4);
+            const contextStr = formatPercentage(turn.context_percentage).padStart(10);
+            const inputStr = formatNumber(turn.input_tokens).padStart(7);
+            const outputStr = formatNumber(turn.output_tokens).padStart(7);
+            const cacheStr = formatNumber(turn.cache_read_tokens).padStart(11);
+            const totalStr = formatNumber(turn.total_tokens).padStart(8);
+            // Color code context percentage
+            const contextColor = getContextColor(turn.context_percentage);
+            console.log(`  ${turnStr} │ ${contextColor(contextStr)} │ ${inputStr} │ ${outputStr} │ ${cacheStr} │ ${totalStr}`);
+        }
+        console.log();
+    }
+    // VM validation status
+    const isVmWorking = validateVmBehavior(usage);
+    if (isVmWorking) {
+        console.log(chalk_1.default.green.bold('✅ VM Working: Context staying in constant band (good!)'));
+    }
+    else {
+        console.log(chalk_1.default.yellow.bold('⚠️  VM Warning: Context growing linearly (check proxy eviction)'));
+    }
+    console.log();
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}
+/**
+ * List available sessions for an instance
+ */
+async function listAvailableSessions(instanceId) {
+    console.log();
+    console.log(chalk_1.default.bold.cyan('📋 Available Sessions (via ccusage)'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(chalk_1.default.gray('Fetching sessions...'));
+    const sessions = await (0, usage_parser_js_1.getAllSessions)(instanceId);
+    if (sessions.length === 0) {
+        console.log(chalk_1.default.yellow('  No sessions found'));
+        console.log();
+        return;
+    }
+    for (const session of sessions) {
+        console.log(`  ${chalk_1.default.bold(session.session_id)}`);
+        console.log(`    ${chalk_1.default.gray('Turns:')} ${chalk_1.default.green(session.turn_count.toString())}, ${chalk_1.default.gray('Cost:')} ${chalk_1.default.green('$' + session.total_cost.toFixed(2))}, ${chalk_1.default.gray('Context:')} ${formatPercentage(session.avg_context_percentage)}`);
+        console.log(`    ${chalk_1.default.gray('Last:')} ${session.last_activity}, ${chalk_1.default.gray('Models:')} ${chalk_1.default.cyan(session.models_used.join(', '))}`);
+        console.log();
+    }
+}
+/**
+ * Validate VM behavior based on context growth pattern
+ */
+function validateVmBehavior(usage) {
+    if (usage.turn_count < 5) {
+        return true; // Too few turns to judge
+    }
+    // Check if context is staying in a constant band (±10%)
+    const contextValues = usage.turns.map(t => t.context_percentage);
+    const min = Math.min(...contextValues);
+    const max = Math.max(...contextValues);
+    const range = max - min;
+    // If range is small (< 15%), VM is working
+    return range < 15;
+}
+/**
+ * Format numbers with commas
+ */
+function formatNumber(num) {
+    return num.toLocaleString('en-US');
+}
+/**
+ * Format percentage
+ */
+function formatPercentage(pct) {
+    return `${pct.toFixed(1)}%`;
+}
+/**
+ * Format timestamp
+ */
+function formatTimestamp(ts) {
+    try {
+        const date = new Date(ts);
+        return date.toLocaleString('en-US', {
+            month: 'short',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: '2-digit',
+            hour12: true
+        });
+    }
+    catch {
+        return ts;
+    }
+}
+/**
+ * Get color for context percentage
+ */
+function getContextColor(pct) {
+    if (pct < 30)
+        return chalk_1.default.green;
+    if (pct < 50)
+        return chalk_1.default.yellow;
+    if (pct < 70)
+        return chalk_1.default.hex('#FFA500'); // Orange
+    return chalk_1.default.red;
+}

package/dist/cron/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ekkOS Cron Jobs
+ * ================
+ *
+ * Background jobs for ekkOS maintenance and evolution.
+ */
+export { evaluatePromotions, queryPatternStats, writePatchConfig, type PromoterConfig, type PromotionResult, type PromotedPatchConfig, type PromotedPattern, } from './promoter.js';

package/dist/cron/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * ekkOS Cron Jobs
+ * ================
+ *
+ * Background jobs for ekkOS maintenance and evolution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writePatchConfig = exports.queryPatternStats = exports.evaluatePromotions = void 0;
+var promoter_js_1 = require("./promoter.js");
+Object.defineProperty(exports, "evaluatePromotions", { enumerable: true, get: function () { return promoter_js_1.evaluatePromotions; } });
+Object.defineProperty(exports, "queryPatternStats", { enumerable: true, get: function () { return promoter_js_1.queryPatternStats; } });
+Object.defineProperty(exports, "writePatchConfig", { enumerable: true, get: function () { return promoter_js_1.writePatchConfig; } });

package/dist/cron/promoter.d.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * ekkOS PROMETHEUS Pattern Promoter
+ * ==================================
+ *
+ * Daily cron job that evaluates patterns for promotion to constitutional memory.
+ *
+ * Constitutional patterns are injected into the system prompt via @ekkos/patch,
+ * making them "instincts" that don't require retrieval.
+ *
+ * Promotion Criteria (default):
+ * - Success rate ≥ 85%
+ * - Applications ≥ 5
+ * - Skip rate ≤ 10%
+ * - Confidence ≥ 70%
+ * - Used within last 30 days
+ * - Used in ≥ 2 unique sessions
+ *
+ * Usage:
+ *   npx ekkos-promote                  # Run promotion evaluation
+ *   npx ekkos-promote --dry-run        # Preview without applying changes
+ *   npx ekkos-promote --user <uuid>    # Promote for specific user
+ *
+ * Schedule via launchd (macOS) or cron:
+ *   0 6 * * * /path/to/node /path/to/ekkos-promote
+ */
+import { SupabaseClient } from '@supabase/supabase-js';
+import { type PatternStats } from '@ekkos/prometheus';
+interface PromoterConfig {
+    supabaseUrl: string;
+    supabaseKey: string;
+    dryRun: boolean;
+    userId?: string;
+    patchConfigPath: string;
+    verbose: boolean;
+}
+interface PromotionResult {
+    evaluated: number;
+    promoted: number;
+    demoted: number;
+    patterns: Array<{
+        patternId: string;
+        title: string;
+        action: 'promoted' | 'demoted' | 'unchanged';
+        score: number;
+        reason?: string;
+    }>;
+    patchConfig?: PromotedPatchConfig;
+}
+interface PromotedPattern {
+    id: string;
+    title: string;
+    problem: string;
+    solution: string;
+    promotedAt: string;
+    successRate: number;
+    appliedCount: number;
+    tags?: string[];
+}
+interface PromotedPatchConfig {
+    version: string;
+    generatedAt: string;
+    promotedPatterns: PromotedPattern[];
+    totalPatterns: number;
+}
+declare function queryPatternStats(supabase: SupabaseClient, userId?: string): Promise<PatternStats[]>;
+declare function evaluatePromotions(supabase: SupabaseClient, config: PromoterConfig): Promise<PromotionResult>;
+declare function writePatchConfig(config: PromotedPatchConfig, outputPath: string): void;
+export { evaluatePromotions, queryPatternStats, writePatchConfig };
+export type { PromoterConfig, PromotionResult, PromotedPatchConfig, PromotedPattern };