@ekkos/cli 0.2.0

package/dist/cache/LocalSessionStore.js

@@ -0,0 +1,688 @@
+"use strict";
+/**
+ * ekkOS Fast /continue - Local Session Store
+ *
+ * Tier 0 of the 3-tier restore chain.
+ * Provides ultra-low latency (<20ms) turn storage using append-only JSONL files.
+ *
+ * Features:
+ * - Atomic writes (write to .tmp, rename)
+ * - Crash recovery (handle partial JSONL lines)
+ * - ACK-based safe pruning
+ * - Multi-session support with LRU eviction
+ */
+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 });
+exports.localCache = exports.LocalSessionStore = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// Default configuration
+const DEFAULT_CONFIG = {
+    cache_dir: path.join(os.homedir(), '.ekkos', 'cache'),
+    max_sessions: 20,
+    max_turns_per_session: 100,
+    safety_margin: 5,
+    flush_interval_ms: 5000,
+};
+/**
+ * LocalSessionStore - Fast local cache for conversation turns
+ */
+class LocalSessionStore {
+    constructor(config = {}) {
+        this.indexCache = null;
+        this.indexCacheTime = 0;
+        this.INDEX_CACHE_TTL = 1000; // 1 second
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.sessionsDir = path.join(this.config.cache_dir, 'sessions');
+        this.indexPath = path.join(this.sessionsDir, 'index.json');
+        this.ensureDirectories();
+    }
+    /**
+     * Ensure cache directories exist
+     */
+    ensureDirectories() {
+        try {
+            fs.mkdirSync(this.sessionsDir, { recursive: true });
+        }
+        catch (err) {
+            // Directory might already exist
+        }
+    }
+    /**
+     * Get the JSONL file path for a session
+     */
+    getTurnsPath(sessionId) {
+        return path.join(this.sessionsDir, `${sessionId}.jsonl`);
+    }
+    /**
+     * Get the metadata file path for a session
+     */
+    getMetaPath(sessionId) {
+        return path.join(this.sessionsDir, `${sessionId}.meta.json`);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INDEX OPERATIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Read the session index (with caching)
+     */
+    readIndex() {
+        const now = Date.now();
+        if (this.indexCache && now - this.indexCacheTime < this.INDEX_CACHE_TTL) {
+            return this.indexCache;
+        }
+        try {
+            if (fs.existsSync(this.indexPath)) {
+                const content = fs.readFileSync(this.indexPath, 'utf-8');
+                this.indexCache = JSON.parse(content);
+                this.indexCacheTime = now;
+                return this.indexCache;
+            }
+        }
+        catch (err) {
+            // Corrupted index, start fresh
+            console.error('[LocalSessionStore] Index read error, resetting:', err);
+        }
+        this.indexCache = {};
+        this.indexCacheTime = now;
+        return this.indexCache;
+    }
+    /**
+     * Write the session index atomically
+     */
+    writeIndex(index) {
+        const tmpPath = `${this.indexPath}.tmp`;
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(index, null, 2), 'utf-8');
+            fs.renameSync(tmpPath, this.indexPath);
+            this.indexCache = index;
+            this.indexCacheTime = Date.now();
+        }
+        catch (err) {
+            // Clean up temp file on error
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw err;
+        }
+    }
+    /**
+     * Update a single session in the index
+     */
+    updateIndexEntry(sessionName, entry) {
+        const index = this.readIndex();
+        index[sessionName] = entry;
+        this.writeIndex(index);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SESSION METADATA
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Read session metadata
+     */
+    getSessionMeta(sessionId) {
+        const metaPath = this.getMetaPath(sessionId);
+        try {
+            if (fs.existsSync(metaPath)) {
+                const content = fs.readFileSync(metaPath, 'utf-8');
+                return JSON.parse(content);
+            }
+        }
+        catch (err) {
+            console.error('[LocalSessionStore] Meta read error:', err);
+        }
+        return null;
+    }
+    /**
+     * Write session metadata atomically
+     */
+    writeSessionMeta(meta) {
+        const metaPath = this.getMetaPath(meta.session_id);
+        const tmpPath = `${metaPath}.tmp`;
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(meta, null, 2), 'utf-8');
+            fs.renameSync(tmpPath, metaPath);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw err;
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TURN OPERATIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Append a turn to the session's JSONL file
+     * This is the hot path - must be fast
+     */
+    appendTurn(sessionId, sessionName, turn, projectPath) {
+        const startTime = Date.now();
+        const turnsPath = this.getTurnsPath(sessionId);
+        try {
+            // Append turn as JSONL line (atomic append on most filesystems)
+            const line = JSON.stringify(turn) + '\n';
+            fs.appendFileSync(turnsPath, line, 'utf-8');
+            // Update metadata
+            let meta = this.getSessionMeta(sessionId);
+            if (!meta) {
+                meta = {
+                    session_id: sessionId,
+                    session_name: sessionName,
+                    acked_turn_id: 0,
+                    last_flush_ts: new Date().toISOString(),
+                    turn_count: 0,
+                    project_path: projectPath,
+                    created_at: new Date().toISOString(),
+                };
+            }
+            meta.turn_count = turn.turn_id;
+            meta.last_flush_ts = new Date().toISOString();
+            if (projectPath)
+                meta.project_path = projectPath;
+            this.writeSessionMeta(meta);
+            // Update index
+            this.updateIndexEntry(sessionName, {
+                session_id: sessionId,
+                last_active_ts: new Date().toISOString(),
+                last_turn_id: turn.turn_id,
+                acked_turn_id: meta.acked_turn_id,
+                project_path: projectPath,
+            });
+            return {
+                success: true,
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Get the last N turns from a session
+     * Handles crash recovery (partial lines)
+     */
+    getLastTurns(sessionId, n = 10) {
+        const startTime = Date.now();
+        const turnsPath = this.getTurnsPath(sessionId);
+        try {
+            if (!fs.existsSync(turnsPath)) {
+                return {
+                    success: false,
+                    error: 'Session not found in local cache',
+                    source: 'local',
+                    latency_ms: Date.now() - startTime,
+                };
+            }
+            const content = fs.readFileSync(turnsPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            const turns = [];
+            // Parse lines, handling potential corruption
+            for (const line of lines) {
+                try {
+                    const turn = JSON.parse(line);
+                    turns.push(turn);
+                }
+                catch {
+                    // Skip corrupted lines (crash recovery)
+                    console.error('[LocalSessionStore] Skipping corrupted line');
+                }
+            }
+            // Return last N turns, oldest first
+            const lastN = turns.slice(-n);
+            return {
+                success: true,
+                data: lastN,
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Get a specific turn by ID
+     */
+    getTurn(sessionId, turnId) {
+        const result = this.getLastTurns(sessionId, 1000); // Get all
+        if (!result.success || !result.data) {
+            return { success: false, error: result.error, source: 'local' };
+        }
+        const turn = result.data.find((t) => t.turn_id === turnId);
+        if (!turn) {
+            return { success: false, error: `Turn ${turnId} not found`, source: 'local' };
+        }
+        return { success: true, data: turn, source: 'local' };
+    }
+    /**
+     * Update the assistant response for a pending turn
+     * (Called when Stop hook fires)
+     */
+    updateTurnResponse(sessionId, turnId, response, toolsUsed, filesReferenced) {
+        const startTime = Date.now();
+        const turnsPath = this.getTurnsPath(sessionId);
+        try {
+            if (!fs.existsSync(turnsPath)) {
+                return {
+                    success: false,
+                    error: 'Session not found',
+                    source: 'local',
+                    latency_ms: Date.now() - startTime,
+                };
+            }
+            const content = fs.readFileSync(turnsPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            const turns = [];
+            for (const line of lines) {
+                try {
+                    turns.push(JSON.parse(line));
+                }
+                catch {
+                    // Skip corrupted lines
+                }
+            }
+            // Find and update the turn
+            const turnIndex = turns.findIndex((t) => t.turn_id === turnId);
+            if (turnIndex === -1) {
+                return {
+                    success: false,
+                    error: `Turn ${turnId} not found`,
+                    source: 'local',
+                    latency_ms: Date.now() - startTime,
+                };
+            }
+            turns[turnIndex].assistant_response = response;
+            if (toolsUsed)
+                turns[turnIndex].tools_used = toolsUsed;
+            if (filesReferenced)
+                turns[turnIndex].files_referenced = filesReferenced;
+            // Rewrite the file atomically
+            const newContent = turns.map((t) => JSON.stringify(t)).join('\n') + '\n';
+            const tmpPath = `${turnsPath}.tmp`;
+            fs.writeFileSync(tmpPath, newContent, 'utf-8');
+            fs.renameSync(tmpPath, turnsPath);
+            return {
+                success: true,
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ACK & PRUNING
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Acknowledge that turns up to acked_turn_id have been flushed to Redis
+     */
+    ack(sessionId, ackedTurnId) {
+        const startTime = Date.now();
+        try {
+            const meta = this.getSessionMeta(sessionId);
+            if (!meta) {
+                return {
+                    success: false,
+                    error: 'Session metadata not found',
+                    source: 'local',
+                    latency_ms: Date.now() - startTime,
+                };
+            }
+            // Only update if new ACK is higher (prevent regression)
+            if (ackedTurnId > meta.acked_turn_id) {
+                meta.acked_turn_id = ackedTurnId;
+                meta.last_flush_ts = new Date().toISOString();
+                this.writeSessionMeta(meta);
+                // Update index too
+                const index = this.readIndex();
+                const sessionName = Object.keys(index).find((name) => index[name].session_id === sessionId);
+                if (sessionName) {
+                    index[sessionName].acked_turn_id = ackedTurnId;
+                    this.writeIndex(index);
+                }
+            }
+            return {
+                success: true,
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Acknowledge that turns up to ackedTurnId have been flushed to Supabase
+     * This is separate from Redis ACK - both must succeed before pruning
+     */
+    ackSupabase(sessionId, ackedTurnId) {
+        const startTime = Date.now();
+        try {
+            const meta = this.getSessionMeta(sessionId);
+            if (!meta) {
+                return {
+                    success: false,
+                    error: 'Session metadata not found',
+                    source: 'local',
+                    latency_ms: Date.now() - startTime,
+                };
+            }
+            // Only update if new ACK is higher (prevent regression)
+            const currentSupabaseAck = meta.supabase_acked_turn_id || 0;
+            if (ackedTurnId > currentSupabaseAck) {
+                meta.supabase_acked_turn_id = ackedTurnId;
+                meta.last_flush_ts = new Date().toISOString();
+                this.writeSessionMeta(meta);
+            }
+            return {
+                success: true,
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Prune turns that are safely ACKed to BOTH Redis AND Supabase
+     * Only removes turns where turn_id <= min(redis_ack, supabase_ack) - safety_margin
+     * This ensures data is persisted in both tiers before local pruning
+     */
+    prune(sessionId) {
+        const startTime = Date.now();
+        const turnsPath = this.getTurnsPath(sessionId);
+        try {
+            const meta = this.getSessionMeta(sessionId);
+            if (!meta) {
+                return {
+                    success: false,
+                    error: 'Session metadata not found',
+                    source: 'local',
+                    latency_ms: Date.now() - startTime,
+                };
+            }
+            // Require BOTH Redis AND Supabase ACKs before pruning
+            // This prevents data loss when Supabase capture fails
+            const redisAck = meta.acked_turn_id || 0;
+            const supabaseAck = meta.supabase_acked_turn_id || 0;
+            const minAck = Math.min(redisAck, supabaseAck);
+            const pruneThreshold = minAck - this.config.safety_margin;
+            if (pruneThreshold <= 0) {
+                return {
+                    success: true,
+                    data: 0,
+                    source: 'local',
+                    latency_ms: Date.now() - startTime,
+                };
+            }
+            if (!fs.existsSync(turnsPath)) {
+                return { success: true, data: 0, source: 'local' };
+            }
+            const content = fs.readFileSync(turnsPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            const turns = [];
+            let prunedCount = 0;
+            for (const line of lines) {
+                try {
+                    const turn = JSON.parse(line);
+                    if (turn.turn_id > pruneThreshold) {
+                        turns.push(turn);
+                    }
+                    else {
+                        prunedCount++;
+                    }
+                }
+                catch {
+                    // Skip corrupted lines
+                }
+            }
+            // Rewrite with remaining turns
+            if (prunedCount > 0) {
+                const newContent = turns.map((t) => JSON.stringify(t)).join('\n') + '\n';
+                const tmpPath = `${turnsPath}.tmp`;
+                fs.writeFileSync(tmpPath, newContent, 'utf-8');
+                fs.renameSync(tmpPath, turnsPath);
+            }
+            return {
+                success: true,
+                data: prunedCount,
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SESSION MANAGEMENT
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * List all sessions, sorted by last active (newest first)
+     */
+    listSessions() {
+        const index = this.readIndex();
+        const entries = [];
+        for (const [sessionName, entry] of Object.entries(index)) {
+            const meta = this.getSessionMeta(entry.session_id);
+            entries.push({
+                session_name: sessionName,
+                session_id: entry.session_id,
+                last_active_ts: entry.last_active_ts,
+                turn_count: meta?.turn_count || entry.last_turn_id,
+                project_path: entry.project_path,
+                is_current: false, // Caller determines this
+            });
+        }
+        // Sort by last active (newest first)
+        entries.sort((a, b) => new Date(b.last_active_ts).getTime() - new Date(a.last_active_ts).getTime());
+        return entries;
+    }
+    /**
+     * Get session ID from session name
+     */
+    getSessionId(sessionName) {
+        const index = this.readIndex();
+        return index[sessionName]?.session_id || null;
+    }
+    /**
+     * Get session name from session ID
+     */
+    getSessionName(sessionId) {
+        const index = this.readIndex();
+        for (const [name, entry] of Object.entries(index)) {
+            if (entry.session_id === sessionId) {
+                return name;
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if a session exists in local cache
+     */
+    hasSession(sessionIdOrName) {
+        const index = this.readIndex();
+        // Check by name
+        if (index[sessionIdOrName])
+            return true;
+        // Check by ID
+        for (const entry of Object.values(index)) {
+            if (entry.session_id === sessionIdOrName)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Delete a session from local cache
+     */
+    deleteSession(sessionId) {
+        const startTime = Date.now();
+        try {
+            // Remove files
+            const turnsPath = this.getTurnsPath(sessionId);
+            const metaPath = this.getMetaPath(sessionId);
+            if (fs.existsSync(turnsPath))
+                fs.unlinkSync(turnsPath);
+            if (fs.existsSync(metaPath))
+                fs.unlinkSync(metaPath);
+            // Remove from index
+            const index = this.readIndex();
+            const sessionName = Object.keys(index).find((name) => index[name].session_id === sessionId);
+            if (sessionName) {
+                delete index[sessionName];
+                this.writeIndex(index);
+            }
+            return {
+                success: true,
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                source: 'local',
+                latency_ms: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Evict oldest sessions to stay under max_sessions limit
+     * Only evicts sessions that are fully ACKed to Redis
+     */
+    evictOldSessions() {
+        const sessions = this.listSessions();
+        if (sessions.length <= this.config.max_sessions) {
+            return 0;
+        }
+        let evictedCount = 0;
+        const toEvict = sessions.length - this.config.max_sessions;
+        // Start from oldest (end of sorted array)
+        for (let i = sessions.length - 1; i >= 0 && evictedCount < toEvict; i--) {
+            const session = sessions[i];
+            const meta = this.getSessionMeta(session.session_id);
+            // Only evict if fully ACKed
+            if (meta && meta.acked_turn_id >= meta.turn_count) {
+                this.deleteSession(session.session_id);
+                evictedCount++;
+            }
+        }
+        return evictedCount;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // UTILITIES
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const sessions = this.listSessions();
+        let totalTurns = 0;
+        let cacheSize = 0;
+        for (const session of sessions) {
+            totalTurns += session.turn_count;
+            const turnsPath = this.getTurnsPath(session.session_id);
+            try {
+                const stats = fs.statSync(turnsPath);
+                cacheSize += stats.size;
+            }
+            catch {
+                // File might not exist
+            }
+        }
+        return {
+            session_count: sessions.length,
+            total_turns: totalTurns,
+            cache_size_bytes: cacheSize,
+        };
+    }
+    /**
+     * Clear all local cache (use with caution)
+     */
+    clearAll() {
+        const sessions = this.listSessions();
+        for (const session of sessions) {
+            this.deleteSession(session.session_id);
+        }
+        this.indexCache = {};
+        this.writeIndex({});
+    }
+}
+exports.LocalSessionStore = LocalSessionStore;
+// Export singleton instance
+exports.localCache = new LocalSessionStore();