@ekkos/cli 0.2.18 → 0.3.3

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 };