@ekkos/cli 0.2.0

package/dist/cache/capture.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * ekkOS Fast Capture & Restore - CLI for local cache operations
+ *
+ * Capture Commands:
+ *   capture user <session_id> <session_name> <turn_id> <query> [project_path]
+ *   capture response <session_id> <turn_id> <response> [tools] [files]
+ *
+ * Restore Commands:
+ *   capture restore [session_name] [--json|--markdown|--n=N]
+ *
+ * ACK & Sync Commands (Phase 5):
+ *   capture ack <session_id> <turn_id>     - Update ACK cursor after Redis success
+ *   capture sync [session_id]              - Sync unACKed turns to Redis
+ *   capture prune <session_id>             - Remove safely ACKed turns
+ *   capture cleanup                        - Prune all + evict old sessions
+ *
+ * Query Commands:
+ *   capture list                           - List all cached sessions
+ *   capture get <session_id> [n]           - Get last N turns
+ *   capture stats                          - Cache statistics
+ *
+ * This is a lightweight script designed for hook integration.
+ * Writes to local JSONL cache with minimal latency.
+ */
+export {};

package/dist/cache/capture.js

@@ -0,0 +1,461 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * ekkOS Fast Capture & Restore - CLI for local cache operations
+ *
+ * Capture Commands:
+ *   capture user <session_id> <session_name> <turn_id> <query> [project_path]
+ *   capture response <session_id> <turn_id> <response> [tools] [files]
+ *
+ * Restore Commands:
+ *   capture restore [session_name] [--json|--markdown|--n=N]
+ *
+ * ACK & Sync Commands (Phase 5):
+ *   capture ack <session_id> <turn_id>     - Update ACK cursor after Redis success
+ *   capture sync [session_id]              - Sync unACKed turns to Redis
+ *   capture prune <session_id>             - Remove safely ACKed turns
+ *   capture cleanup                        - Prune all + evict old sessions
+ *
+ * Query Commands:
+ *   capture list                           - List all cached sessions
+ *   capture get <session_id> [n]           - Get last N turns
+ *   capture stats                          - Cache statistics
+ *
+ * This is a lightweight script designed for hook integration.
+ * Writes to local JSONL cache with minimal latency.
+ */
+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 });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const LocalSessionStore_js_1 = require("./LocalSessionStore.js");
+const RestoreOrchestrator_js_1 = require("../restore/RestoreOrchestrator.js");
+const store = new LocalSessionStore_js_1.LocalSessionStore();
+// API configuration
+const MEMORY_API_URL = process.env.EKKOS_API_URL || 'https://api.ekkos.dev';
+const CONFIG_PATH = path.join(os.homedir(), '.ekkos', 'config.json');
+/**
+ * Load auth token from config
+ */
+function loadAuthToken() {
+    try {
+        if (fs.existsSync(CONFIG_PATH)) {
+            const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+            return config.hookApiKey || config.apiKey || '';
+        }
+    }
+    catch {
+        // Ignore config errors
+    }
+    return '';
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command) {
+        console.error('Usage: capture <user|response> ...');
+        process.exit(1);
+    }
+    try {
+        switch (command) {
+            case 'user': {
+                // capture user <session_id> <session_name> <turn_id> <query> [project_path]
+                const [, sessionId, sessionName, turnIdStr, query, projectPath] = args;
+                if (!sessionId || !sessionName || !turnIdStr || !query) {
+                    console.error('Usage: capture user <session_id> <session_name> <turn_id> <query> [project_path]');
+                    process.exit(1);
+                }
+                const turnId = parseInt(turnIdStr, 10);
+                const turn = {
+                    turn_id: turnId,
+                    ts: new Date().toISOString(),
+                    user_query: query,
+                    assistant_response: '', // Will be filled by response capture
+                    tools_used: [],
+                    files_referenced: [],
+                };
+                const result = store.appendTurn(sessionId, sessionName, turn, projectPath);
+                if (result.success) {
+                    console.log(JSON.stringify({ success: true, latency_ms: result.latency_ms }));
+                }
+                else {
+                    console.error(JSON.stringify({ success: false, error: result.error }));
+                    process.exit(1);
+                }
+                break;
+            }
+            case 'response': {
+                // capture response <session_id> <turn_id> <response> [tools_json] [files_json]
+                const [, sessionId, turnIdStr, response, toolsJson, filesJson] = args;
+                if (!sessionId || !turnIdStr || !response) {
+                    console.error('Usage: capture response <session_id> <turn_id> <response> [tools_json] [files_json]');
+                    process.exit(1);
+                }
+                const turnId = parseInt(turnIdStr, 10);
+                const tools = toolsJson ? JSON.parse(toolsJson) : [];
+                const files = filesJson ? JSON.parse(filesJson) : [];
+                const result = store.updateTurnResponse(sessionId, turnId, response, tools, files);
+                if (result.success) {
+                    console.log(JSON.stringify({ success: true, latency_ms: result.latency_ms }));
+                }
+                else {
+                    console.error(JSON.stringify({ success: false, error: result.error }));
+                    process.exit(1);
+                }
+                break;
+            }
+            case 'list': {
+                // capture list
+                const sessions = store.listSessions();
+                console.log(JSON.stringify(sessions, null, 2));
+                break;
+            }
+            case 'get': {
+                // capture get <session_id> [n]
+                const [, sessionId, nStr] = args;
+                if (!sessionId) {
+                    console.error('Usage: capture get <session_id> [n]');
+                    process.exit(1);
+                }
+                const n = nStr ? parseInt(nStr, 10) : 10;
+                const result = store.getLastTurns(sessionId, n);
+                if (result.success) {
+                    console.log(JSON.stringify(result.data, null, 2));
+                }
+                else {
+                    console.error(JSON.stringify({ error: result.error }));
+                    process.exit(1);
+                }
+                break;
+            }
+            case 'stats': {
+                const stats = store.getStats();
+                console.log(JSON.stringify(stats, null, 2));
+                break;
+            }
+            case 'restore': {
+                // capture restore [session_name] [--json|--markdown|--n=N]
+                const orchestrator = new RestoreOrchestrator_js_1.RestoreOrchestrator();
+                let sessionName;
+                let outputFormat = 'json';
+                let lastN = 10;
+                for (let i = 1; i < args.length; i++) {
+                    const arg = args[i];
+                    if (arg === '--json') {
+                        outputFormat = 'json';
+                    }
+                    else if (arg === '--markdown' || arg === '--md') {
+                        outputFormat = 'markdown';
+                    }
+                    else if (arg.startsWith('--n=')) {
+                        lastN = parseInt(arg.slice(4), 10) || 10;
+                    }
+                    else if (!arg.startsWith('-')) {
+                        sessionName = arg;
+                    }
+                }
+                const result = await orchestrator.restore({
+                    session_name: sessionName,
+                    last_n: lastN,
+                });
+                if (result.success && result.data) {
+                    if (outputFormat === 'markdown') {
+                        console.log(orchestrator.formatAsSystemReminder(result.data));
+                    }
+                    else {
+                        console.log(JSON.stringify({
+                            success: true,
+                            source: result.data.source,
+                            latency_ms: result.latency_ms,
+                            session_name: result.data.session_name,
+                            session_id: result.data.session_id,
+                            turns_restored: result.data.restored_turns.length,
+                            token_estimate: result.data.metadata.token_estimate,
+                        }, null, 2));
+                    }
+                }
+                else {
+                    console.error(JSON.stringify({
+                        success: false,
+                        error: result.error,
+                        latency_ms: result.latency_ms,
+                    }));
+                    process.exit(1);
+                }
+                break;
+            }
+            case 'ack': {
+                // capture ack <session_id> <turn_id>
+                // Update ACK cursor after successful Redis flush
+                const [, sessionId, turnIdStr] = args;
+                if (!sessionId || !turnIdStr) {
+                    console.error('Usage: capture ack <session_id> <turn_id>');
+                    process.exit(1);
+                }
+                const turnId = parseInt(turnIdStr, 10);
+                const result = store.ack(sessionId, turnId);
+                if (result.success) {
+                    console.log(JSON.stringify({ success: true, acked_turn_id: turnId, latency_ms: result.latency_ms }));
+                }
+                else {
+                    console.error(JSON.stringify({ success: false, error: result.error }));
+                    process.exit(1);
+                }
+                break;
+            }
+            case 'prune': {
+                // capture prune <session_id>
+                // Remove turns safely below ACK threshold
+                const [, sessionId] = args;
+                if (!sessionId) {
+                    console.error('Usage: capture prune <session_id>');
+                    process.exit(1);
+                }
+                const meta = store.getSessionMeta(sessionId);
+                if (!meta) {
+                    console.error(JSON.stringify({ success: false, error: 'Session not found' }));
+                    process.exit(1);
+                }
+                const result = store.prune(sessionId);
+                if (result.success) {
+                    console.log(JSON.stringify({
+                        success: true,
+                        pruned_turns: result.data,
+                        acked_turn_id: meta.acked_turn_id,
+                        latency_ms: result.latency_ms,
+                    }));
+                }
+                else {
+                    console.error(JSON.stringify({ success: false, error: result.error }));
+                    process.exit(1);
+                }
+                break;
+            }
+            case 'sync': {
+                // capture sync [session_id]
+                // Sync unACKed turns to Redis, update ACK on success
+                const [, sessionIdArg] = args;
+                const authToken = loadAuthToken();
+                if (!authToken) {
+                    console.error(JSON.stringify({ success: false, error: 'No auth token configured' }));
+                    process.exit(1);
+                }
+                // Get sessions to sync
+                const sessions = sessionIdArg
+                    ? [{ session_id: sessionIdArg, session_name: store.getSessionName(sessionIdArg) || 'unknown' }]
+                    : store.listSessions();
+                let totalSynced = 0;
+                let totalFailed = 0;
+                for (const session of sessions) {
+                    const meta = store.getSessionMeta(session.session_id);
+                    if (!meta)
+                        continue;
+                    // Get unACKed turns (turns after acked_turn_id)
+                    const turnsResult = store.getLastTurns(session.session_id, 100);
+                    if (!turnsResult.success || !turnsResult.data)
+                        continue;
+                    const unackedTurns = turnsResult.data.filter((t) => t.turn_id > meta.acked_turn_id && t.assistant_response // Only complete turns
+                    );
+                    if (unackedTurns.length === 0)
+                        continue;
+                    // Sync each turn to Redis
+                    let maxSyncedTurn = meta.acked_turn_id;
+                    for (const turn of unackedTurns) {
+                        try {
+                            const payload = {
+                                session_name: meta.session_name || session.session_name,
+                                turn_number: turn.turn_id,
+                                user_query: turn.user_query,
+                                agent_response: turn.assistant_response,
+                                tools_used: turn.tools_used || [],
+                                files_referenced: turn.files_referenced || [],
+                            };
+                            const response = await fetch(`${MEMORY_API_URL}/api/v1/working/turn`, {
+                                method: 'POST',
+                                headers: {
+                                    Authorization: `Bearer ${authToken}`,
+                                    'Content-Type': 'application/json',
+                                },
+                                body: JSON.stringify(payload),
+                                signal: AbortSignal.timeout(5000),
+                            });
+                            if (response.ok) {
+                                maxSyncedTurn = Math.max(maxSyncedTurn, turn.turn_id);
+                                totalSynced++;
+                            }
+                            else {
+                                totalFailed++;
+                            }
+                        }
+                        catch {
+                            totalFailed++;
+                        }
+                    }
+                    // Update ACK cursor if any turns synced
+                    if (maxSyncedTurn > meta.acked_turn_id) {
+                        store.ack(session.session_id, maxSyncedTurn);
+                    }
+                }
+                console.log(JSON.stringify({
+                    success: true,
+                    turns_synced: totalSynced,
+                    turns_failed: totalFailed,
+                    sessions_processed: sessions.length,
+                }));
+                break;
+            }
+            case 'sync-supabase': {
+                // capture sync-supabase [session_id]
+                // Sync ALL local cache turns to Supabase (episodic memory)
+                // This backfills any missing turns that failed during capture
+                const [, sessionIdArg] = args;
+                const authToken = loadAuthToken();
+                if (!authToken) {
+                    console.error(JSON.stringify({ success: false, error: 'No auth token configured' }));
+                    process.exit(1);
+                }
+                // Get sessions to sync
+                const sessions = sessionIdArg
+                    ? [{ session_id: sessionIdArg, session_name: store.getSessionName(sessionIdArg) || 'unknown' }]
+                    : store.listSessions();
+                let totalSynced = 0;
+                let totalFailed = 0;
+                let totalSkipped = 0;
+                for (const session of sessions) {
+                    const meta = store.getSessionMeta(session.session_id);
+                    if (!meta)
+                        continue;
+                    // Get ALL turns from local cache
+                    const turnsResult = store.getLastTurns(session.session_id, 1000);
+                    if (!turnsResult.success || !turnsResult.data)
+                        continue;
+                    // Filter to turns not yet ACKed for Supabase
+                    const supabaseAck = meta.supabase_acked_turn_id || 0;
+                    const unackedTurns = turnsResult.data.filter((t) => t.turn_id > supabaseAck && t.assistant_response // Only complete turns
+                    );
+                    if (unackedTurns.length === 0) {
+                        totalSkipped += turnsResult.data.length;
+                        continue;
+                    }
+                    console.error(`[sync-supabase] Syncing ${unackedTurns.length} turns for ${meta.session_name}...`);
+                    let maxSyncedTurn = supabaseAck;
+                    for (const turn of unackedTurns) {
+                        try {
+                            const payload = {
+                                user_query: turn.user_query,
+                                assistant_response: turn.assistant_response,
+                                session_id: session.session_id,
+                                metadata: {
+                                    source: 'claude-code',
+                                    turn_number: turn.turn_id,
+                                    session_name: meta.session_name,
+                                    tools_used: turn.tools_used || [],
+                                    files_referenced: turn.files_referenced || [],
+                                    backfill: true,
+                                },
+                            };
+                            const response = await fetch(`${MEMORY_API_URL}/api/v1/memory/capture`, {
+                                method: 'POST',
+                                headers: {
+                                    Authorization: `Bearer ${authToken}`,
+                                    'Content-Type': 'application/json',
+                                },
+                                body: JSON.stringify(payload),
+                                signal: AbortSignal.timeout(10000),
+                            });
+                            if (response.ok) {
+                                maxSyncedTurn = Math.max(maxSyncedTurn, turn.turn_id);
+                                totalSynced++;
+                            }
+                            else {
+                                const errorText = await response.text();
+                                console.error(`[sync-supabase] Failed turn ${turn.turn_id}: ${response.status} - ${errorText}`);
+                                totalFailed++;
+                            }
+                        }
+                        catch (err) {
+                            console.error(`[sync-supabase] Error syncing turn ${turn.turn_id}:`, err);
+                            totalFailed++;
+                        }
+                    }
+                    // Update Supabase ACK cursor if any turns synced
+                    if (maxSyncedTurn > supabaseAck) {
+                        store.ackSupabase(session.session_id, maxSyncedTurn);
+                    }
+                }
+                console.log(JSON.stringify({
+                    success: true,
+                    turns_synced: totalSynced,
+                    turns_failed: totalFailed,
+                    turns_skipped: totalSkipped,
+                    sessions_processed: sessions.length,
+                }));
+                break;
+            }
+            case 'cleanup': {
+                // capture cleanup
+                // Evict old sessions and prune all sessions
+                const sessions = store.listSessions();
+                let totalPruned = 0;
+                // Prune all sessions
+                for (const session of sessions) {
+                    const result = store.prune(session.session_id);
+                    if (result.success && result.data) {
+                        totalPruned += result.data;
+                    }
+                }
+                // Evict old sessions if over limit
+                const evicted = store.evictOldSessions();
+                console.log(JSON.stringify({
+                    success: true,
+                    turns_pruned: totalPruned,
+                    sessions_evicted: evicted,
+                    remaining_sessions: store.listSessions().length,
+                }));
+                break;
+            }
+            default:
+                console.error(`Unknown command: ${command}`);
+                console.error('Commands: user, response, list, get, stats, restore, ack, prune, sync, sync-supabase, cleanup');
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(JSON.stringify({ success: false, error: String(err) }));
+        process.exit(1);
+    }
+}
+main();

package/dist/cache/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ekkOS Fast /continue - Local Cache Module
+ *
+ * Tier 0 of the 3-tier restore chain for near-zero context loss.
+ */
+export * from './types.js';
+export * from './LocalSessionStore.js';

package/dist/cache/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * ekkOS Fast /continue - Local Cache Module
+ *
+ * Tier 0 of the 3-tier restore chain for near-zero context loss.
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./LocalSessionStore.js"), exports);

package/dist/cache/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * ekkOS Fast /continue - Local Cache Types
+ *
+ * Defines the data structures for the 3-tier restore chain:
+ * Tier 0: Local JSONL cache (~20ms)
+ * Tier 1: Redis hot cache (~150ms)
+ * Tier 2: Supabase cold store (~500ms)
+ */
+/**
+ * A single conversation turn (user + assistant pair)
+ */
+export interface Turn {
+    turn_id: number;
+    ts: string;
+    user_query: string;
+    assistant_response: string;
+    tools_used: string[];
+    files_referenced: string[];
+    diffs?: string[];
+    token_estimate?: number;
+    is_complete?: boolean;
+}
+/**
+ * Known placeholder strings that indicate incomplete/invalid responses
+ * These should NOT be treated as valid assistant_response content
+ */
+export declare const INVALID_RESPONSE_PATTERNS: string[];
+/**
+ * Check if an assistant_response is valid (complete, not a placeholder)
+ */
+export declare function isValidAssistantResponse(response: string | undefined | null): boolean;
+/**
+ * Session metadata stored in index.json
+ */
+export interface SessionIndex {
+    [session_name: string]: SessionIndexEntry;
+}
+export interface SessionIndexEntry {
+    session_id: string;
+    last_active_ts: string;
+    last_turn_id: number;
+    acked_turn_id: number;
+    project_path?: string;
+}
+/**
+ * Per-session metadata stored in {session_id}.meta.json
+ */
+export interface SessionMeta {
+    session_id: string;
+    session_name: string;
+    acked_turn_id: number;
+    supabase_acked_turn_id?: number;
+    last_flush_ts: string;
+    turn_count: number;
+    project_path?: string;
+    created_at: string;
+}
+/**
+ * Restore payload returned by RestoreOrchestrator
+ */
+export interface RestorePayload {
+    session_id: string;
+    session_name: string;
+    source: 'local' | 'redis' | 'supabase';
+    restored_turns: Turn[];
+    latest: {
+        user_query: string;
+        assistant_response: string;
+    };
+    pending_turn?: {
+        turn_id: number;
+        user_query: string;
+        ts: string;
+    };
+    directives: Directive[];
+    patterns: Pattern[];
+    metadata: {
+        acked_turn_id: number;
+        last_flush_ts: string;
+        token_estimate: number;
+        complete_turn_count: number;
+        has_pending: boolean;
+    };
+}
+/**
+ * User directive (MUST/NEVER/PREFER/AVOID)
+ */
+export interface Directive {
+    id: string;
+    type: 'MUST' | 'NEVER' | 'PREFER' | 'AVOID';
+    rule: string;
+    reason?: string;
+    priority: number;
+}
+/**
+ * Pattern from ekkOS memory
+ */
+export interface Pattern {
+    id: string;
+    title: string;
+    problem: string;
+    solution: string;
+    success_rate: number;
+    applied_count: number;
+}
+/**
+ * Options for restore operation
+ */
+export interface RestoreOptions {
+    session_name?: string;
+    session_id?: string;
+    last_n?: number;
+    include_directives?: boolean;
+    include_patterns?: boolean;
+    max_tokens?: number;
+}
+/**
+ * Result of a cache operation
+ */
+export interface CacheResult<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    source?: 'local' | 'redis' | 'supabase';
+    latency_ms?: number;
+}
+/**
+ * Local cache configuration
+ */
+export interface LocalCacheConfig {
+    cache_dir: string;
+    max_sessions: number;
+    max_turns_per_session: number;
+    safety_margin: number;
+    flush_interval_ms: number;
+}
+/**
+ * Session list entry (for /continue sessions)
+ */
+export interface SessionListEntry {
+    session_name: string;
+    session_id: string;
+    last_active_ts: string;
+    turn_count: number;
+    project_path?: string;
+    is_current: boolean;
+}