@ekkos/cli 0.3.3 → 1.0.1

package/README.md

@@ -0,0 +1,57 @@
+# @ekkos/cli
+
+Persistent cognitive memory for AI coding assistants. ekkOS gives Claude Code, Cursor, and Windsurf long-term memory — patterns, decisions, and operational intelligence that compound across every interaction.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @ekkos/cli
+
+# Authenticate and configure your IDE
+ekkos init
+
+# Launch Claude Code with memory
+ekkos run
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ekkos init` | Authenticate and configure your IDE (Claude Code, Cursor, Windsurf) |
+| `ekkos run` | Launch Claude Code with ekkOS memory connected |
+| `ekkos run --dashboard` | Launch with live metrics dashboard (tmux split) |
+| `ekkos status` | Check connection and memory health |
+| `ekkos dashboard` | Open the live session dashboard |
+| `ekkos export` | Export your patterns and memory as JSON |
+| `ekkos --help` | Show all commands |
+
+## What It Does
+
+- **Remembers what works** — Patterns from successful solutions are recalled automatically
+- **Learns from mistakes** — Anti-patterns prevent repeating the same errors
+- **Crosses sessions** — Knowledge persists across conversations, projects, and tools
+- **Gets smarter over time** — Success rates compound as patterns are verified
+
+## How It Works
+
+ekkOS installs hooks into your AI coding assistant that:
+
+1. **Before each prompt** — Searches 11 memory layers for relevant patterns
+2. **After each response** — Captures new solutions as reusable patterns
+3. **Between sessions** — Preserves context through eviction and rehydration
+
+## Requirements
+
+- Node.js >= 18
+- An ekkOS account ([platform.ekkos.dev](https://platform.ekkos.dev/signup))
+- One of: Claude Code, Cursor, Windsurf, or VS Code
+
+## Documentation
+
+[docs.ekkos.dev](https://docs.ekkos.dev)
+
+## License
+
+Proprietary — see [ekkos.dev/terms](https://ekkos.dev/terms)

package/dist/agent/daemon.d.ts

@@ -18,9 +18,16 @@ export declare class AgentDaemon {
     private ws;
     private reconnectAttempt;
     private heartbeatTimer;
+    private pongTimer;
+    private pongReceived;
     private ptyRunner;
     private currentSessionId;
+    private currentSessionCwd;
+    private sessionStartedAt;
+    private ptyRestartAttempts;
+    private readonly QUICK_EXIT_MS;
     private running;
+    private logPath;
     private outputBuffer;
     private currentSessionName;
     private isAutoClearInProgress;
@@ -63,6 +70,14 @@ export declare class AgentDaemon {
      * Handle resize from browser
      */
     private handleResize;
+    /**
+     * Handle directory listing request from relay for project browsing UI.
+     */
+    private handleListDirectories;
+    private resolveBrowsePath;
+    private getParentPath;
+    private getWindowsRootEntries;
+    private resolveSessionCwd;
     /**
      * Handle PTY exit
      */
@@ -83,10 +98,22 @@ export declare class AgentDaemon {
      * Sleep helper
      */
     private sleep;
+    /**
+     * Start or restart PTY for the current session.
+     */
+    private startSessionPty;
     /**
      * Handle WebSocket close
+     *
+     * CRITICAL: Do NOT kill the PTY here. The PTY must survive WebSocket
+     * disconnects so users can reconnect to their existing session.
+     * The PTY is only killed on explicit session_end or daemon stop.
      */
     private handleClose;
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    private scheduleReconnect;
     /**
      * Handle WebSocket error
      */

package/dist/agent/daemon.js

@@ -51,8 +51,10 @@ const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const pty_runner_1 = require("./pty-runner");
+const log_rotate_1 = require("../utils/log-rotate");
 const RELAY_URL = process.env.RELAY_WS_URL || 'wss://ekkos-relay-production.up.railway.app';
-const HEARTBEAT_INTERVAL = 30000; // 30 seconds
+const HEARTBEAT_INTERVAL = 10000; // 10 seconds - must be well under Railway's 20-30s idle timeout
+const PONG_TIMEOUT = 15000; // If no pong received in 15s, consider connection dead
 const RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 16000, 32000, 60000]; // Exponential backoff
 // Auto-continue: Context wall detection pattern
 const CONTEXT_WALL_REGEX = /context limit reached.*\/(compact|clear)\b.*to continue/i;
@@ -65,8 +67,13 @@ class AgentDaemon {
         this.ws = null;
         this.reconnectAttempt = 0;
         this.heartbeatTimer = null;
+        this.pongTimer = null;
+        this.pongReceived = true;
         this.ptyRunner = null;
         this.currentSessionId = null;
+        this.sessionStartedAt = 0;
+        this.ptyRestartAttempts = 0;
+        this.QUICK_EXIT_MS = 15000;
         this.running = false;
         // Auto-continue state
         this.outputBuffer = '';
@@ -75,6 +82,7 @@ class AgentDaemon {
         this.lastContextWallTime = 0;
         this.CONTEXT_WALL_COOLDOWN = 30000; // 30 seconds between auto-clears
         this.config = config;
+        this.logPath = path.join(os.homedir(), '.ekkos', 'agent.log');
     }
     /**
      * Start the daemon
@@ -94,6 +102,11 @@ class AgentDaemon {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
+        // Stop pong timer
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
         // Close PTY
         if (this.ptyRunner) {
             this.ptyRunner.kill();
@@ -121,6 +134,7 @@ class AgentDaemon {
         });
         this.ws.on('open', () => this.handleOpen());
         this.ws.on('message', (data) => this.handleMessage(data));
+        this.ws.on('pong', () => { this.pongReceived = true; });
         this.ws.on('close', (code, reason) => this.handleClose(code, reason.toString()));
         this.ws.on('error', (err) => this.handleError(err));
     }
@@ -130,8 +144,29 @@ class AgentDaemon {
     handleOpen() {
         this.log('Connected to relay server');
         this.reconnectAttempt = 0;
-        // Start heartbeat
+        this.pongReceived = true;
+        // If we have a surviving PTY session, tell relay we're ready to reattach
+        if (this.ptyRunner && this.currentSessionId) {
+            this.log(`Re-advertising surviving session ${this.currentSessionId}`);
+            this.sendMessage({
+                type: 'session_alive',
+                sessionId: this.currentSessionId,
+            });
+        }
+        // Start heartbeat with dual ping: protocol-level + app-level
         this.heartbeatTimer = setInterval(() => {
+            if (!this.pongReceived) {
+                // Previous ping never got a pong - connection is dead
+                this.log('No pong received, connection dead - forcing reconnect');
+                this.ws?.terminate(); // terminate, not close - skip graceful shutdown
+                return;
+            }
+            this.pongReceived = false;
+            // Protocol-level ping (handled by ws library)
+            if (this.ws && this.ws.readyState === ws_1.default.OPEN) {
+                this.ws.ping();
+            }
+            // App-level heartbeat (for relay server to track device presence)
             this.sendMessage({ type: 'heartbeat' });
         }, HEARTBEAT_INTERVAL);
     }
@@ -166,6 +201,9 @@ class AgentDaemon {
             case 'error':
                 this.log('Server error:', message.error);
                 break;
+            case 'list_dirs':
+                void this.handleListDirectories(message.requestId, message.path);
+                break;
         }
     }
     /**
@@ -173,27 +211,31 @@ class AgentDaemon {
      */
     handleSessionStart(sessionId, cwd) {
         this.log(`Session start request: ${sessionId}${cwd ? ` (cwd: ${cwd})` : ''}`);
-        // Kill existing session if any
+        // If reconnecting to the SAME session, reuse existing PTY
+        if (this.ptyRunner && this.currentSessionId === sessionId) {
+            this.log(`Reattaching to existing PTY for session ${sessionId}`);
+            this.sendMessage({ type: 'ready', sessionId });
+            return;
+        }
+        // Different session - kill old PTY if any
         if (this.ptyRunner) {
+            this.log(`Killing old PTY for session ${this.currentSessionId}`);
             this.ptyRunner.kill();
             this.ptyRunner = null;
         }
         this.currentSessionId = sessionId;
+        const resolved = this.resolveSessionCwd(cwd);
+        this.currentSessionCwd = resolved.cwd;
+        this.ptyRestartAttempts = 0;
         // Reset auto-continue state
         this.outputBuffer = '';
         this.currentSessionName = null;
         this.isAutoClearInProgress = false;
         this.lastContextWallTime = 0;
-        // Start PTY with ekkos run (skip -d flag to avoid double init)
-        this.ptyRunner = new pty_runner_1.PTYRunner({
-            command: 'ekkos',
-            args: ['run', '-b'], // -b for bypass permissions (skip -d to avoid double spawn)
-            onData: (data) => this.sendOutput(data),
-            onExit: (code) => this.handlePTYExit(code),
-            cwd: cwd || process.env.HOME, // Use specified cwd or fall back to home
-            verbose: this.config.verbose,
-        });
-        this.ptyRunner.start();
+        this.startSessionPty(resolved.cwd);
+        if (resolved.warning) {
+            this.sendOutput(`\r\n[ekkOS] ${resolved.warning}\r\n`);
+        }
         // Notify server that PTY is ready
         this.sendMessage({
             type: 'ready',
@@ -208,11 +250,13 @@ class AgentDaemon {
             return; // Not our session
         }
         this.log('Session ended');
+        this.currentSessionId = null;
+        this.currentSessionCwd = undefined;
+        this.ptyRestartAttempts = 0;
         if (this.ptyRunner) {
             this.ptyRunner.kill();
             this.ptyRunner = null;
         }
-        this.currentSessionId = null;
     }
     /**
      * Handle input from browser
@@ -230,17 +274,162 @@ class AgentDaemon {
             this.ptyRunner.resize(cols, rows);
         }
     }
+    /**
+     * Handle directory listing request from relay for project browsing UI.
+     */
+    async handleListDirectories(requestId, requestedPath) {
+        if (!requestId)
+            return;
+        try {
+            const resolvedPath = this.resolveBrowsePath(requestedPath);
+            if (resolvedPath === '__WINDOWS_ROOT__') {
+                this.sendMessage({
+                    type: 'list_dirs_result',
+                    requestId,
+                    path: '/',
+                    parentPath: null,
+                    entries: this.getWindowsRootEntries(),
+                });
+                return;
+            }
+            const dirents = await fs.promises.readdir(resolvedPath, { withFileTypes: true });
+            const entries = dirents
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => ({
+                name: entry.name,
+                path: path.join(resolvedPath, entry.name),
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .slice(0, 300);
+            this.sendMessage({
+                type: 'list_dirs_result',
+                requestId,
+                path: resolvedPath,
+                parentPath: this.getParentPath(resolvedPath),
+                entries,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to read directory';
+            this.sendMessage({
+                type: 'list_dirs_result',
+                requestId,
+                error: message,
+            });
+        }
+    }
+    resolveBrowsePath(requestedPath) {
+        const homePath = os.homedir();
+        const raw = requestedPath?.trim() ?? '';
+        if (process.platform === 'win32' && (raw === '' || raw === '/' || raw === '\\')) {
+            return '__WINDOWS_ROOT__';
+        }
+        if (!raw) {
+            return homePath;
+        }
+        if (raw === '~') {
+            return homePath;
+        }
+        if (raw.startsWith('~/') || raw.startsWith('~\\')) {
+            return path.resolve(path.join(homePath, raw.slice(2)));
+        }
+        return path.resolve(raw);
+    }
+    getParentPath(currentPath) {
+        if (process.platform === 'win32' && /^[A-Za-z]:\\?$/.test(currentPath)) {
+            return null;
+        }
+        const parsed = path.parse(currentPath);
+        if (currentPath === parsed.root) {
+            return null;
+        }
+        const parent = path.dirname(currentPath);
+        return parent === currentPath ? null : parent;
+    }
+    getWindowsRootEntries() {
+        const entries = [];
+        for (let code = 65; code <= 90; code++) {
+            const drive = String.fromCharCode(code);
+            const drivePath = `${drive}:\\`;
+            if (fs.existsSync(drivePath)) {
+                entries.push({
+                    name: `${drive}:`,
+                    path: drivePath,
+                });
+            }
+        }
+        return entries;
+    }
+    resolveSessionCwd(cwd) {
+        const homePath = os.homedir();
+        const raw = cwd?.trim();
+        if (!raw) {
+            return { cwd: homePath };
+        }
+        let expanded = raw;
+        if (raw === '~') {
+            expanded = homePath;
+        }
+        else if (raw.startsWith('~/') || raw.startsWith('~\\')) {
+            expanded = path.join(homePath, raw.slice(2));
+        }
+        const resolvedPath = path.resolve(expanded);
+        try {
+            const stat = fs.statSync(resolvedPath);
+            if (stat.isDirectory()) {
+                return { cwd: resolvedPath };
+            }
+            return {
+                cwd: homePath,
+                warning: `Requested path is not a directory: ${raw}. Falling back to ${homePath}.`,
+            };
+        }
+        catch {
+            return {
+                cwd: homePath,
+                warning: `Requested path not found: ${raw}. Falling back to ${homePath}.`,
+            };
+        }
+    }
     /**
      * Handle PTY exit
      */
     handlePTYExit(code) {
         this.log(`PTY exited with code ${code}`);
+        const elapsed = Date.now() - this.sessionStartedAt;
+        const hasActiveSession = this.running && this.currentSessionId !== null;
+        const quickExit = elapsed < this.QUICK_EXIT_MS;
+        if (hasActiveSession && code !== 0) {
+            this.ptyRestartAttempts = quickExit ? this.ptyRestartAttempts + 1 : 1;
+            const attempt = this.ptyRestartAttempts;
+            const sessionId = this.currentSessionId;
+            const restartDelay = quickExit
+                ? Math.min(600 * attempt, 5000)
+                : 1000;
+            const reason = quickExit ? 'crashed' : 'exited unexpectedly';
+            this.log(`PTY ${reason} (${elapsed}ms, code ${code}). Restarting in ${restartDelay}ms (attempt ${attempt})...`);
+            this.ptyRunner = null;
+            this.sendOutput(`\r\n[ekkOS] Terminal ${reason} (code ${code}). Restarting in ${Math.max(1, Math.ceil(restartDelay / 1000))}s...\r\n`);
+            setTimeout(() => {
+                if (!this.running || !sessionId || this.currentSessionId !== sessionId || this.ptyRunner) {
+                    return;
+                }
+                this.startSessionPty(this.currentSessionCwd);
+                this.sendMessage({
+                    type: 'ready',
+                    sessionId,
+                });
+            }, restartDelay);
+            return;
+        }
         this.sendMessage({
             type: 'session_end',
             sessionId: this.currentSessionId || undefined,
         });
         this.ptyRunner = null;
         this.currentSessionId = null;
+        this.currentSessionCwd = undefined;
+        this.ptyRestartAttempts = 0;
     }
     /**
      * Send PTY output to server (with auto-continue detection)
@@ -318,8 +507,39 @@ class AgentDaemon {
     sleep(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
+    /**
+     * Start or restart PTY for the current session.
+     */
+    startSessionPty(cwd) {
+        this.sessionStartedAt = Date.now();
+        // Run through the same Node runtime as the daemon to avoid PATH/shebang drift
+        // (e.g. Homebrew node upgrades breaking dylib links).
+        const fallbackEntrypoint = path.resolve(__dirname, '..', 'index.js');
+        const argvEntrypoint = process.argv[1];
+        const cliEntrypoint = argvEntrypoint && !argvEntrypoint.includes('/node_modules/.bin/')
+            ? argvEntrypoint
+            : fallbackEntrypoint;
+        // Start PTY with `node <cli> run -b` (skip -d to avoid double spawn).
+        this.ptyRunner = new pty_runner_1.PTYRunner({
+            command: process.execPath,
+            args: [cliEntrypoint, 'run', '-b'],
+            onData: (data) => this.sendOutput(data),
+            onExit: (code) => this.handlePTYExit(code),
+            cwd: cwd || process.env.HOME, // Use specified cwd or fall back to home
+            env: {
+                EKKOS_REMOTE_SESSION: '1',
+                EKKOS_NO_SPLASH: '1',
+            },
+            verbose: this.config.verbose,
+        });
+        this.ptyRunner.start();
+    }
     /**
      * Handle WebSocket close
+     *
+     * CRITICAL: Do NOT kill the PTY here. The PTY must survive WebSocket
+     * disconnects so users can reconnect to their existing session.
+     * The PTY is only killed on explicit session_end or daemon stop.
      */
     handleClose(code, reason) {
         this.log(`Disconnected: ${code} ${reason}`);
@@ -328,20 +548,29 @@ class AgentDaemon {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
-        // Kill PTY if running
-        if (this.ptyRunner) {
-            this.ptyRunner.kill();
-            this.ptyRunner = null;
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+        // PTY stays alive - user can reconnect to existing session
+        // Only log if there's an active session being preserved
+        if (this.ptyRunner && this.currentSessionId) {
+            this.log(`Preserving PTY session ${this.currentSessionId} across disconnect`);
         }
-        this.currentSessionId = null;
         // Reconnect if still running
         if (this.running) {
-            const delay = RECONNECT_DELAYS[Math.min(this.reconnectAttempt, RECONNECT_DELAYS.length - 1)];
-            this.reconnectAttempt++;
-            this.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempt})...`);
-            setTimeout(() => this.connect(), delay);
+            this.scheduleReconnect();
         }
     }
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    scheduleReconnect() {
+        const delay = RECONNECT_DELAYS[Math.min(this.reconnectAttempt, RECONNECT_DELAYS.length - 1)];
+        this.reconnectAttempt++;
+        this.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempt})...`);
+        setTimeout(() => this.connect(), delay);
+    }
     /**
      * Handle WebSocket error
      */
@@ -365,13 +594,9 @@ class AgentDaemon {
         if (this.config.verbose) {
             console.log(message);
         }
-        // Also log to file
+        // Log to file with rotation
         try {
-            const logDir = path.join(os.homedir(), '.ekkos');
-            if (!fs.existsSync(logDir)) {
-                fs.mkdirSync(logDir, { recursive: true });
-            }
-            fs.appendFileSync(path.join(logDir, 'agent.log'), message + '\n');
+            (0, log_rotate_1.appendLog)(this.logPath, message);
         }
         catch {
             // Ignore log errors

package/dist/agent/health-check.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Health check for ekkOS agent daemon
+ *
+ * Verifies:
+ * - Service is installed and loaded
+ * - Process is running
+ * - Recent activity in logs
+ * - Network connectivity to relay server
+ */
+interface HealthStatus {
+    ok: boolean;
+    service: {
+        installed: boolean;
+        loaded: boolean;
+        running: boolean;
+        pid?: number;
+    };
+    logs: {
+        lastActivity?: Date;
+        recentErrors: string[];
+    };
+    relay: {
+        reachable: boolean;
+        lastError?: string;
+    };
+}
+/**
+ * Check agent daemon health
+ */
+export declare function checkDaemonHealth(): Promise<HealthStatus>;
+/**
+ * Format health status for console output
+ */
+export declare function formatHealthStatus(status: HealthStatus): string;
+export {};