@ekkos/cli 0.2.0

package/dist/cache/LocalSessionStore.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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
+ */
+import { Turn, SessionMeta, LocalCacheConfig, SessionListEntry, CacheResult } from './types.js';
+/**
+ * LocalSessionStore - Fast local cache for conversation turns
+ */
+export declare class LocalSessionStore {
+    private config;
+    private sessionsDir;
+    private indexPath;
+    private indexCache;
+    private indexCacheTime;
+    private readonly INDEX_CACHE_TTL;
+    constructor(config?: Partial<LocalCacheConfig>);
+    /**
+     * Ensure cache directories exist
+     */
+    private ensureDirectories;
+    /**
+     * Get the JSONL file path for a session
+     */
+    private getTurnsPath;
+    /**
+     * Get the metadata file path for a session
+     */
+    private getMetaPath;
+    /**
+     * Read the session index (with caching)
+     */
+    private readIndex;
+    /**
+     * Write the session index atomically
+     */
+    private writeIndex;
+    /**
+     * Update a single session in the index
+     */
+    private updateIndexEntry;
+    /**
+     * Read session metadata
+     */
+    getSessionMeta(sessionId: string): SessionMeta | null;
+    /**
+     * Write session metadata atomically
+     */
+    private writeSessionMeta;
+    /**
+     * Append a turn to the session's JSONL file
+     * This is the hot path - must be fast
+     */
+    appendTurn(sessionId: string, sessionName: string, turn: Turn, projectPath?: string): CacheResult<void>;
+    /**
+     * Get the last N turns from a session
+     * Handles crash recovery (partial lines)
+     */
+    getLastTurns(sessionId: string, n?: number): CacheResult<Turn[]>;
+    /**
+     * Get a specific turn by ID
+     */
+    getTurn(sessionId: string, turnId: number): CacheResult<Turn>;
+    /**
+     * Update the assistant response for a pending turn
+     * (Called when Stop hook fires)
+     */
+    updateTurnResponse(sessionId: string, turnId: number, response: string, toolsUsed?: string[], filesReferenced?: string[]): CacheResult<void>;
+    /**
+     * Acknowledge that turns up to acked_turn_id have been flushed to Redis
+     */
+    ack(sessionId: string, ackedTurnId: number): CacheResult<void>;
+    /**
+     * Acknowledge that turns up to ackedTurnId have been flushed to Supabase
+     * This is separate from Redis ACK - both must succeed before pruning
+     */
+    ackSupabase(sessionId: string, ackedTurnId: number): CacheResult<void>;
+    /**
+     * 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: string): CacheResult<number>;
+    /**
+     * List all sessions, sorted by last active (newest first)
+     */
+    listSessions(): SessionListEntry[];
+    /**
+     * Get session ID from session name
+     */
+    getSessionId(sessionName: string): string | null;
+    /**
+     * Get session name from session ID
+     */
+    getSessionName(sessionId: string): string | null;
+    /**
+     * Check if a session exists in local cache
+     */
+    hasSession(sessionIdOrName: string): boolean;
+    /**
+     * Delete a session from local cache
+     */
+    deleteSession(sessionId: string): CacheResult<void>;
+    /**
+     * Evict oldest sessions to stay under max_sessions limit
+     * Only evicts sessions that are fully ACKed to Redis
+     */
+    evictOldSessions(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        session_count: number;
+        total_turns: number;
+        cache_size_bytes: number;
+    };
+    /**
+     * Clear all local cache (use with caution)
+     */
+    clearAll(): void;
+}
+export declare const localCache: LocalSessionStore;