@ekkos/cli 0.2.9 → 0.2.11

package/dist/cache/capture.js

@@ -1,25 +1,33 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * ekkOS Fast Capture & Restore - CLI for local cache operations
+ * ekkOS Fast Capture & Restore - CLI for local cache operations (Instance-Aware)
  *
- * Capture Commands:
+ * Per ekkOS Onboarding Spec v1.2 FINAL + ADDENDUM:
+ * - All Tier 0 cache paths MUST be: ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.jsonl
+ * - All persisted records MUST include: instanceId, sessionId, sessionName
+ *
+ * Capture Commands (NEW format with instanceId):
+ *   capture user <instance_id> <session_id> <session_name> <turn_id> <query> [project_path]
+ *   capture response <instance_id> <session_id> <turn_id> <response> [tools] [files]
+ *
+ * Capture Commands (LEGACY format - backward compatible, uses default instanceId):
  *   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]
+ *   capture restore [session_name] [--json|--markdown|--n=N] [--instance=ID]
  *
- * 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
+ * ACK & Sync Commands:
+ *   capture ack <session_id> <turn_id> [--instance=ID]
+ *   capture sync [session_id] [--instance=ID]
+ *   capture prune <session_id> [--instance=ID]
+ *   capture cleanup [--instance=ID]
  *
  * Query Commands:
- *   capture list                           - List all cached sessions
- *   capture get <session_id> [n]           - Get last N turns
- *   capture stats                          - Cache statistics
+ *   capture list [--instance=ID|--all]
+ *   capture get <session_id> [n] [--instance=ID]
+ *   capture stats [--instance=ID]
  *
  * This is a lightweight script designed for hook integration.
  * Writes to local JSONL cache with minimal latency.
@@ -63,7 +71,7 @@ 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();
+const paths_js_1 = require("../utils/paths.js");
 // 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');
@@ -82,75 +90,236 @@ function loadAuthToken() {
     }
     return '';
 }
+/**
+ * Parse --instance=ID flag from args
+ */
+function parseInstanceFlag(args) {
+    let instanceId = process.env.EKKOS_INSTANCE_ID || paths_js_1.DEFAULT_INSTANCE_ID;
+    const cleanArgs = [];
+    for (const arg of args) {
+        if (arg.startsWith('--instance=')) {
+            instanceId = arg.slice('--instance='.length);
+        }
+        else {
+            cleanArgs.push(arg);
+        }
+    }
+    return { instanceId: (0, paths_js_1.normalizeInstanceId)(instanceId), cleanArgs };
+}
+/**
+ * Detect if args match the NEW format (with instanceId as first positional arg)
+ *
+ * NEW user format: <instance_id> <session_id> <session_name> <turn_id> <query> [project_path]
+ * OLD user format: <session_id> <session_name> <turn_id> <query> [project_path]
+ *
+ * Detection heuristic:
+ * - If arg[3] is a number (turn_id), it's NEW format
+ * - If arg[2] is a number (turn_id), it's OLD format
+ */
+function isNewUserFormat(args) {
+    // NEW format has at least 5 args: instanceId, sessionId, sessionName, turnId, query
+    if (args.length < 5)
+        return false;
+    // In NEW format, arg[3] should be turn_id (a number)
+    // In OLD format, arg[2] should be turn_id (a number)
+    const arg3 = args[3];
+    const arg2 = args[2];
+    // If arg[3] is numeric but arg[2] is not, it's NEW format
+    if (/^\d+$/.test(arg3) && !/^\d+$/.test(arg2)) {
+        return true;
+    }
+    // If arg[2] is numeric, it's OLD format
+    if (/^\d+$/.test(arg2)) {
+        return false;
+    }
+    // Default to NEW format if ambiguous and we have enough args
+    return args.length >= 5;
+}
+/**
+ * Similar detection for response command
+ *
+ * NEW response format: <instance_id> <session_id> <turn_id> <response> [tools] [files]
+ * OLD response format: <session_id> <turn_id> <response> [tools] [files]
+ */
+function isNewResponseFormat(args) {
+    // NEW format has at least 4 args: instanceId, sessionId, turnId, response
+    if (args.length < 4)
+        return false;
+    // In NEW format, arg[2] should be turn_id (a number)
+    // In OLD format, arg[1] should be turn_id (a number)
+    const arg2 = args[2];
+    const arg1 = args[1];
+    // If arg[2] is numeric but arg[1] is not, it's NEW format
+    if (/^\d+$/.test(arg2) && !/^\d+$/.test(arg1)) {
+        return true;
+    }
+    // If arg[1] is numeric, it's OLD format
+    if (/^\d+$/.test(arg1)) {
+        return false;
+    }
+    // Default to NEW format if ambiguous
+    return args.length >= 4;
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
     if (!command) {
-        console.error('Usage: capture <user|response> ...');
+        console.error('ekkOS Capture CLI - Instance-Aware Local Cache');
+        console.error('');
+        console.error('Usage: ekkos-capture <command> [args...]');
+        console.error('');
+        console.error('Commands:');
+        console.error('  user      Capture user query (start of turn)');
+        console.error('  response  Capture assistant response (end of turn)');
+        console.error('  restore   Restore session context');
+        console.error('  ack       Acknowledge turn synced to Redis');
+        console.error('  sync      Sync unACKed turns to Redis');
+        console.error('  prune     Remove safely ACKed turns');
+        console.error('  cleanup   Prune all + evict old sessions');
+        console.error('  list      List cached sessions');
+        console.error('  get       Get turns from a session');
+        console.error('  stats     Show cache statistics');
+        console.error('');
+        console.error('Global options:');
+        console.error('  --instance=ID  Override instance ID (default: $EKKOS_INSTANCE_ID or "default")');
         process.exit(1);
     }
     try {
+        // Parse global --instance flag
+        const { instanceId, cleanArgs } = parseInstanceFlag(args.slice(1));
+        const store = (0, LocalSessionStore_js_1.createLocalSessionStore)(instanceId);
         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 }));
+                // Detect format and parse accordingly
+                if (isNewUserFormat(cleanArgs)) {
+                    // NEW format: <instance_id> <session_id> <session_name> <turn_id> <query> [project_path]
+                    const [instId, sessionId, sessionName, turnIdStr, query, projectPath] = cleanArgs;
+                    if (!instId || !sessionId || !sessionName || !turnIdStr || !query) {
+                        console.error('Usage (new): capture user <instance_id> <session_id> <session_name> <turn_id> <query> [project_path]');
+                        console.error('Usage (old): capture user <session_id> <session_name> <turn_id> <query> [project_path]');
+                        process.exit(1);
+                    }
+                    // Use the provided instanceId
+                    store.setInstanceId(instId);
+                    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: [],
+                        instance_id: instId,
+                        session_id: sessionId,
+                        session_name: sessionName,
+                    };
+                    const result = store.appendTurn(sessionId, sessionName, turn, projectPath);
+                    if (result.success) {
+                        console.log(JSON.stringify({ success: true, instance_id: instId, latency_ms: result.latency_ms }));
+                    }
+                    else {
+                        console.error(JSON.stringify({ success: false, error: result.error }));
+                        process.exit(1);
+                    }
                 }
                 else {
-                    console.error(JSON.stringify({ success: false, error: result.error }));
-                    process.exit(1);
+                    // OLD format: <session_id> <session_name> <turn_id> <query> [project_path]
+                    const [sessionId, sessionName, turnIdStr, query, projectPath] = cleanArgs;
+                    if (!sessionId || !sessionName || !turnIdStr || !query) {
+                        console.error('Usage (new): capture user <instance_id> <session_id> <session_name> <turn_id> <query> [project_path]');
+                        console.error('Usage (old): 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: [],
+                        instance_id: instanceId, // Use parsed/default instanceId
+                        session_id: sessionId,
+                        session_name: sessionName,
+                    };
+                    const result = store.appendTurn(sessionId, sessionName, turn, projectPath);
+                    if (result.success) {
+                        console.log(JSON.stringify({ success: true, instance_id: instanceId, 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 }));
+                // Detect format and parse accordingly
+                if (isNewResponseFormat(cleanArgs)) {
+                    // NEW format: <instance_id> <session_id> <turn_id> <response> [tools_json] [files_json]
+                    const [instId, sessionId, turnIdStr, response, toolsJson, filesJson] = cleanArgs;
+                    if (!instId || !sessionId || !turnIdStr || !response) {
+                        console.error('Usage (new): capture response <instance_id> <session_id> <turn_id> <response> [tools_json] [files_json]');
+                        console.error('Usage (old): capture response <session_id> <turn_id> <response> [tools_json] [files_json]');
+                        process.exit(1);
+                    }
+                    // Use the provided instanceId
+                    store.setInstanceId(instId);
+                    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, instance_id: instId, latency_ms: result.latency_ms }));
+                    }
+                    else {
+                        console.error(JSON.stringify({ success: false, error: result.error }));
+                        process.exit(1);
+                    }
                 }
                 else {
-                    console.error(JSON.stringify({ success: false, error: result.error }));
-                    process.exit(1);
+                    // OLD format: <session_id> <turn_id> <response> [tools_json] [files_json]
+                    const [sessionId, turnIdStr, response, toolsJson, filesJson] = cleanArgs;
+                    if (!sessionId || !turnIdStr || !response) {
+                        console.error('Usage (new): capture response <instance_id> <session_id> <turn_id> <response> [tools_json] [files_json]');
+                        console.error('Usage (old): 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, instance_id: instanceId, 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));
+                // Check for --all flag
+                const showAll = cleanArgs.includes('--all');
+                if (showAll) {
+                    const sessions = store.listAllSessions();
+                    console.log(JSON.stringify(sessions, null, 2));
+                }
+                else {
+                    const sessions = store.listSessions();
+                    console.log(JSON.stringify(sessions, null, 2));
+                }
                 break;
             }
             case 'get': {
-                // capture get <session_id> [n]
-                const [, sessionId, nStr] = args;
+                const sessionId = cleanArgs[0];
+                const nStr = cleanArgs[1];
                 if (!sessionId) {
-                    console.error('Usage: capture get <session_id> [n]');
+                    console.error('Usage: capture get <session_id> [n] [--instance=ID]');
                     process.exit(1);
                 }
-                const n = nStr ? parseInt(nStr, 10) : 10;
+                const n = nStr && /^\d+$/.test(nStr) ? parseInt(nStr, 10) : 10;
                 const result = store.getLastTurns(sessionId, n);
                 if (result.success) {
                     console.log(JSON.stringify(result.data, null, 2));
@@ -167,13 +336,12 @@ async function main() {
                 break;
             }
             case 'restore': {
-                // capture restore [session_name] [--json|--markdown|--n=N]
-                const orchestrator = new RestoreOrchestrator_js_1.RestoreOrchestrator();
+                const orchestrator = new RestoreOrchestrator_js_1.RestoreOrchestrator(instanceId);
                 let sessionName;
                 let outputFormat = 'json';
                 let lastN = 10;
-                for (let i = 1; i < args.length; i++) {
-                    const arg = args[i];
+                for (let i = 0; i < cleanArgs.length; i++) {
+                    const arg = cleanArgs[i];
                     if (arg === '--json') {
                         outputFormat = 'json';
                     }
@@ -189,6 +357,7 @@ async function main() {
                 }
                 const result = await orchestrator.restore({
                     session_name: sessionName,
+                    instance_id: instanceId,
                     last_n: lastN,
                 });
                 if (result.success && result.data) {
@@ -199,6 +368,7 @@ async function main() {
                         console.log(JSON.stringify({
                             success: true,
                             source: result.data.source,
+                            instance_id: instanceId,
                             latency_ms: result.latency_ms,
                             session_name: result.data.session_name,
                             session_id: result.data.session_id,
@@ -211,6 +381,7 @@ async function main() {
                     console.error(JSON.stringify({
                         success: false,
                         error: result.error,
+                        instance_id: instanceId,
                         latency_ms: result.latency_ms,
                     }));
                     process.exit(1);
@@ -218,17 +389,16 @@ async function main() {
                 break;
             }
             case 'ack': {
-                // capture ack <session_id> <turn_id>
-                // Update ACK cursor after successful Redis flush
-                const [, sessionId, turnIdStr] = args;
+                const sessionId = cleanArgs[0];
+                const turnIdStr = cleanArgs[1];
                 if (!sessionId || !turnIdStr) {
-                    console.error('Usage: capture ack <session_id> <turn_id>');
+                    console.error('Usage: capture ack <session_id> <turn_id> [--instance=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 }));
+                    console.log(JSON.stringify({ success: true, acked_turn_id: turnId, instance_id: instanceId, latency_ms: result.latency_ms }));
                 }
                 else {
                     console.error(JSON.stringify({ success: false, error: result.error }));
@@ -237,11 +407,9 @@ async function main() {
                 break;
             }
             case 'prune': {
-                // capture prune <session_id>
-                // Remove turns safely below ACK threshold
-                const [, sessionId] = args;
+                const sessionId = cleanArgs[0];
                 if (!sessionId) {
-                    console.error('Usage: capture prune <session_id>');
+                    console.error('Usage: capture prune <session_id> [--instance=ID]');
                     process.exit(1);
                 }
                 const meta = store.getSessionMeta(sessionId);
@@ -255,6 +423,7 @@ async function main() {
                         success: true,
                         pruned_turns: result.data,
                         acked_turn_id: meta.acked_turn_id,
+                        instance_id: instanceId,
                         latency_ms: result.latency_ms,
                     }));
                 }
@@ -265,9 +434,7 @@ async function main() {
                 break;
             }
             case 'sync': {
-                // capture sync [session_id]
-                // Sync unACKed turns to Redis, update ACK on success
-                const [, sessionIdArg] = args;
+                const sessionIdArg = cleanArgs[0];
                 const authToken = loadAuthToken();
                 if (!authToken) {
                     console.error(JSON.stringify({ success: false, error: 'No auth token configured' }));
@@ -297,6 +464,7 @@ async function main() {
                         try {
                             const payload = {
                                 session_name: meta.session_name || session.session_name,
+                                instance_id: instanceId,
                                 turn_number: turn.turn_id,
                                 user_query: turn.user_query,
                                 agent_response: turn.assistant_response,
@@ -334,14 +502,12 @@ async function main() {
                     turns_synced: totalSynced,
                     turns_failed: totalFailed,
                     sessions_processed: sessions.length,
+                    instance_id: instanceId,
                 }));
                 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 sessionIdArg = cleanArgs[0];
                 const authToken = loadAuthToken();
                 if (!authToken) {
                     console.error(JSON.stringify({ success: false, error: 'No auth token configured' }));
@@ -380,6 +546,7 @@ async function main() {
                                 session_id: session.session_id,
                                 metadata: {
                                     source: 'claude-code',
+                                    instance_id: instanceId,
                                     turn_number: turn.turn_id,
                                     session_name: meta.session_name,
                                     tools_used: turn.tools_used || [],
@@ -422,12 +589,11 @@ async function main() {
                     turns_failed: totalFailed,
                     turns_skipped: totalSkipped,
                     sessions_processed: sessions.length,
+                    instance_id: instanceId,
                 }));
                 break;
             }
             case 'cleanup': {
-                // capture cleanup
-                // Evict old sessions and prune all sessions
                 const sessions = store.listSessions();
                 let totalPruned = 0;
                 // Prune all sessions
@@ -444,6 +610,7 @@ async function main() {
                     turns_pruned: totalPruned,
                     sessions_evicted: evicted,
                     remaining_sessions: store.listSessions().length,
+                    instance_id: instanceId,
                 }));
                 break;
             }

package/dist/cache/types.d.ts

@@ -8,6 +8,9 @@
  */
 /**
  * A single conversation turn (user + assistant pair)
+ *
+ * Per ekkOS Onboarding Spec v1.2 ADDENDUM:
+ * All persisted records MUST include: instanceId, sessionId, sessionName
  */
 export interface Turn {
     turn_id: number;
@@ -19,6 +22,9 @@ export interface Turn {
     diffs?: string[];
     token_estimate?: number;
     is_complete?: boolean;
+    instance_id?: string;
+    session_id?: string;
+    session_name?: string;
 }
 /**
  * Known placeholder strings that indicate incomplete/invalid responses
@@ -37,17 +43,22 @@ export interface SessionIndex {
 }
 export interface SessionIndexEntry {
     session_id: string;
+    instance_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
+ * Per-session metadata stored in {instanceId}/{session_id}.meta.json
+ *
+ * Per ekkOS Onboarding Spec v1.2 ADDENDUM:
+ * All persisted records MUST include: instanceId, sessionId, sessionName
  */
 export interface SessionMeta {
     session_id: string;
     session_name: string;
+    instance_id?: string;
     acked_turn_id: number;
     supabase_acked_turn_id?: number;
     last_flush_ts: string;
@@ -68,6 +79,7 @@ export interface OpenLoop {
 export interface RestorePayload {
     session_id: string;
     session_name: string;
+    instance_id?: string;
     source: 'local' | 'redis' | 'supabase' | 'stream';
     restored_turns: Turn[];
     latest: {
@@ -118,6 +130,7 @@ export interface Pattern {
 export interface RestoreOptions {
     session_name?: string;
     session_id?: string;
+    instance_id?: string;
     last_n?: number;
     include_directives?: boolean;
     include_patterns?: boolean;

package/dist/commands/agent.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ekkos agent - Agent management commands for remote terminal
+ *
+ * Subcommands:
+ * - daemon: Run the agent daemon (used by service)
+ * - start: Start the agent service
+ * - stop: Stop the agent service
+ * - restart: Restart the agent service
+ * - status: Check agent status
+ * - uninstall: Remove agent service
+ */
+export interface AgentOptions {
+    verbose?: boolean;
+}
+/**
+ * Run the agent daemon (foreground)
+ */
+export declare function agentDaemon(options?: AgentOptions): Promise<void>;
+/**
+ * Start the agent service
+ */
+export declare function agentStart(options?: AgentOptions): Promise<void>;
+/**
+ * Stop the agent service
+ */
+export declare function agentStop(options?: AgentOptions): Promise<void>;
+/**
+ * Restart the agent service
+ */
+export declare function agentRestart(options?: AgentOptions): Promise<void>;
+/**
+ * Check agent status
+ */
+export declare function agentStatus(options?: AgentOptions): Promise<void>;
+/**
+ * Uninstall the agent service
+ */
+export declare function agentUninstall(options?: AgentOptions): Promise<void>;
+/**
+ * Show agent logs
+ */
+export declare function agentLogs(options?: {
+    follow?: boolean;
+}): Promise<void>;