knoxis-helper 1.1.0 → 1.2.1

package/bin/knoxis-helper.js

@@ -3,20 +3,35 @@
 /**
  * Knoxis Helper - First-time setup + local agent launcher
  *
+ * On first run (typically via npx), this copies the agent files to a stable
+ * local path (~/.knoxis/agent/) so that:
+ *   1. Subsequent runs don't need network (works behind VPN)
+ *   2. The macOS LaunchAgent always points to a path that exists
+ *   3. Coworkers get the same reliable experience
+ *
  * Usage:
- *   npx knoxis-helper                     # Interactive setup (first time)
- *   npx knoxis-helper --backend wss://...  # Connect to specific backend
- *   npx knoxis-helper --status             # Check connection status
+ *   npx knoxis-helper                     # First-time: setup + install locally
+ *   npx knoxis-helper --backend wss://... # Connect to specific backend
+ *   npx knoxis-helper --status            # Check connection status
+ *   npx knoxis-helper --check             # Diagnose connectivity issues
+ *   npx knoxis-helper --update            # Force re-copy of agent files
+ *   npx knoxis-helper --uninstall         # Remove LaunchAgent + local files
  */
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const https = require('https');
+const http = require('http');
 const readline = require('readline');
+const { spawnSync } = require('child_process');
 
 const CONFIG_DIR = path.join(os.homedir(), '.knoxis');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
-const DEFAULT_BACKEND = 'wss://voice-backend.qig.ai';
+const AGENT_DIR = path.join(CONFIG_DIR, 'agent');
+const STABLE_AGENT_PATH = path.join(AGENT_DIR, 'knoxis-local-agent.js');
+const PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', 'com.knoxis.helper.plist');
+const DEFAULT_BACKEND = 'wss://voice-app-v2.graymushroom-5a5599fe.centralus.azurecontainerapps.io';
 
 function loadConfig() {
   try {
@@ -40,6 +55,9 @@ function parseArgs() {
     const arg = process.argv[i];
     if (arg === '--status') { args.status = true; continue; }
     if (arg === '--reset') { args.reset = true; continue; }
+    if (arg === '--check') { args.check = true; continue; }
+    if (arg === '--update') { args.update = true; continue; }
+    if (arg === '--uninstall') { args.uninstall = true; continue; }
     if (arg.startsWith('--')) {
       const key = arg.slice(2);
       const next = process.argv[i + 1];
@@ -58,6 +76,118 @@ function ask(rl, question) {
   return new Promise(resolve => rl.question(question, resolve));
 }
 
+/**
+ * Copy agent files to ~/.knoxis/agent/ so they persist across npx cache clears,
+ * VPN changes, and reboots. Returns the stable path.
+ */
+function installAgentLocally(force) {
+  const sourceAgent = path.join(__dirname, '..', 'lib', 'knoxis-local-agent.js');
+  const sourcePairProgram = path.join(__dirname, '..', 'lib', 'knoxis-pair-program.js');
+  const sourcePackage = path.join(__dirname, '..', 'package.json');
+
+  if (!fs.existsSync(sourceAgent)) {
+    return null; // Source not available (shouldn't happen)
+  }
+
+  // Check if already installed and up to date
+  if (!force && fs.existsSync(STABLE_AGENT_PATH)) {
+    try {
+      const installedPkg = path.join(AGENT_DIR, 'package.json');
+      if (fs.existsSync(installedPkg) && fs.existsSync(sourcePackage)) {
+        const installed = JSON.parse(fs.readFileSync(installedPkg, 'utf8'));
+        const source = JSON.parse(fs.readFileSync(sourcePackage, 'utf8'));
+        if (installed.version === source.version) {
+          return STABLE_AGENT_PATH; // Already up to date
+        }
+      }
+    } catch (e) {
+      // Fall through to install
+    }
+  }
+
+  // Copy files to stable location
+  if (!fs.existsSync(AGENT_DIR)) {
+    fs.mkdirSync(AGENT_DIR, { recursive: true });
+  }
+
+  fs.copyFileSync(sourceAgent, STABLE_AGENT_PATH);
+  console.log('  Installed: knoxis-local-agent.js');
+
+  if (fs.existsSync(sourcePairProgram)) {
+    fs.copyFileSync(sourcePairProgram, path.join(AGENT_DIR, 'knoxis-pair-program.js'));
+    console.log('  Installed: knoxis-pair-program.js');
+  }
+
+  if (fs.existsSync(sourcePackage)) {
+    fs.copyFileSync(sourcePackage, path.join(AGENT_DIR, 'package.json'));
+  }
+
+  return STABLE_AGENT_PATH;
+}
+
+/**
+ * Check if the backend is reachable (helps diagnose VPN issues)
+ */
+function checkConnectivity(backendUrl) {
+  return new Promise((resolve) => {
+    // Convert wss:// to https:// for health check
+    let healthUrl = backendUrl
+      .replace('wss://', 'https://')
+      .replace('ws://', 'http://');
+    // Strip path and add /health (using the local agent's health, not backend)
+    // Actually check the backend WebSocket endpoint reachability
+    if (!healthUrl.endsWith('/')) healthUrl += '/';
+
+    const client = healthUrl.startsWith('https') ? https : http;
+    const req = client.get(healthUrl, { rejectUnauthorized: false, timeout: 5000 }, (res) => {
+      resolve({ reachable: true, statusCode: res.statusCode });
+    });
+    req.on('error', (err) => {
+      resolve({ reachable: false, error: err.code || err.message });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ reachable: false, error: 'TIMEOUT' });
+    });
+  });
+}
+
+/**
+ * Check if the local agent is already running
+ */
+function checkLocalAgent(port) {
+  return new Promise((resolve) => {
+    const req = https.get(`https://localhost:${port || 3456}/health`, { rejectUnauthorized: false, timeout: 3000 }, (res) => {
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => {
+        try {
+          resolve({ running: true, ...JSON.parse(data) });
+        } catch (e) {
+          resolve({ running: true, raw: data });
+        }
+      });
+    });
+    req.on('error', () => {
+      // Try HTTP fallback
+      const req2 = http.get(`http://localhost:${port || 3456}/health`, { timeout: 3000 }, (res) => {
+        let data = '';
+        res.on('data', chunk => { data += chunk; });
+        res.on('end', () => {
+          try {
+            resolve({ running: true, ...JSON.parse(data) });
+          } catch (e) {
+            resolve({ running: true, raw: data });
+          }
+        });
+      });
+      req2.on('error', () => resolve({ running: false }));
+      req2.on('timeout', () => { req2.destroy(); resolve({ running: false }); });
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ running: false }); });
+  });
+}
+
 async function firstTimeSetup(args) {
   const config = loadConfig();
 
@@ -119,9 +249,37 @@ async function firstTimeSetup(args) {
   return config;
 }
 
+function uninstall() {
+  console.log('');
+  console.log('  Knoxis Helper - Uninstall');
+  console.log('  =========================');
+
+  // Unload and remove LaunchAgent
+  if (process.platform === 'darwin' && fs.existsSync(PLIST_PATH)) {
+    spawnSync('launchctl', ['unload', PLIST_PATH]);
+    fs.unlinkSync(PLIST_PATH);
+    console.log('  Removed LaunchAgent');
+  }
+
+  // Remove agent files
+  if (fs.existsSync(AGENT_DIR)) {
+    fs.rmSync(AGENT_DIR, { recursive: true, force: true });
+    console.log('  Removed ~/.knoxis/agent/');
+  }
+
+  console.log('  Config preserved at ~/.knoxis/config.json (use --reset to clear)');
+  console.log('');
+}
+
 async function main() {
   const args = parseArgs();
 
+  // Uninstall
+  if (args.uninstall) {
+    uninstall();
+    process.exit(0);
+  }
+
   // Reset
   if (args.reset) {
     try { fs.unlinkSync(CONFIG_FILE); } catch (e) {}
@@ -136,9 +294,83 @@ async function main() {
       console.log('Not configured. Run: npx knoxis-helper');
     } else {
       console.log('Configured:');
-      console.log(`  Backend: ${config.backendWsUrl}`);
-      console.log(`  User:    ${config.userId}`);
+      console.log(`  Backend:   ${config.backendWsUrl}`);
+      console.log(`  User:      ${config.userId}`);
+      console.log(`  Installed: ${fs.existsSync(STABLE_AGENT_PATH) ? STABLE_AGENT_PATH : 'NOT INSTALLED (run npx knoxis-helper --update)'}`);
+
+      const local = await checkLocalAgent();
+      console.log(`  Running:   ${local.running ? 'YES (v' + (local.version || '?') + ', ' + (local.secure ? 'HTTPS' : 'HTTP') + ')' : 'NO'}`);
+    }
+    process.exit(0);
+  }
+
+  // Connectivity check
+  if (args.check) {
+    const config = loadConfig();
+    console.log('');
+    console.log('  Knoxis Helper - Connectivity Check');
+    console.log('  ==================================');
+    console.log('');
+
+    // Check local agent
+    const local = await checkLocalAgent();
+    if (local.running) {
+      console.log(`  Local agent:  RUNNING (v${local.version || '?'}, ${local.secure ? 'HTTPS' : 'HTTP'})`);
+    } else {
+      console.log('  Local agent:  NOT RUNNING');
+    }
+
+    // Check stable install
+    console.log(`  Installed at: ${fs.existsSync(STABLE_AGENT_PATH) ? STABLE_AGENT_PATH : 'NOT INSTALLED'}`);
+
+    // Check LaunchAgent
+    if (process.platform === 'darwin') {
+      console.log(`  LaunchAgent:  ${fs.existsSync(PLIST_PATH) ? 'CONFIGURED' : 'NOT CONFIGURED'}`);
     }
+
+    // Check backend reachability
+    if (config.backendWsUrl) {
+      console.log(`  Backend URL:  ${config.backendWsUrl}`);
+      const result = await checkConnectivity(config.backendWsUrl);
+      if (result.reachable) {
+        console.log(`  Backend:      REACHABLE (HTTP ${result.statusCode})`);
+      } else {
+        console.log(`  Backend:      UNREACHABLE (${result.error})`);
+        console.log('');
+        if (result.error === 'TIMEOUT' || result.error === 'ECONNREFUSED') {
+          console.log('  This is likely a VPN issue. The backend is not reachable from this network.');
+          console.log('  The local agent will still work for direct API calls (localhost:3456).');
+          console.log('  WebSocket relay to backend will reconnect automatically when VPN allows it.');
+        } else {
+          console.log(`  Network error: ${result.error}`);
+          console.log('  Check your VPN settings or try: curl -k https://voice-app-v2.graymushroom-5a5599fe.centralus.azurecontainerapps.io/');
+        }
+      }
+    } else {
+      console.log('  Backend:      NOT CONFIGURED');
+    }
+
+    // Check npm registry (the actual cause of "reinstall" prompts)
+    console.log('');
+    console.log('  Checking npm registry access...');
+    const npmResult = await checkConnectivity('https://registry.npmjs.org/knoxis-helper');
+    if (npmResult.reachable) {
+      console.log('  npm registry: REACHABLE');
+    } else {
+      console.log(`  npm registry: UNREACHABLE (${npmResult.error})`);
+      console.log('');
+      console.log('  This is why npx keeps prompting to reinstall!');
+      console.log('  When npm registry is unreachable (VPN), npx can\'t verify its cache.');
+      console.log('  Fix: The local install at ~/.knoxis/agent/ bypasses this entirely.');
+      if (!fs.existsSync(STABLE_AGENT_PATH)) {
+        console.log('  Run: npx knoxis-helper  (while OFF VPN to do initial install)');
+      } else {
+        console.log('  Your local install is fine. Run directly with:');
+        console.log(`    node ${STABLE_AGENT_PATH}`);
+      }
+    }
+
+    console.log('');
     process.exit(0);
   }
 
@@ -155,13 +387,24 @@ async function main() {
     console.log('');
   }
 
+  // Install agent files to stable path (~/.knoxis/agent/)
+  // This is the key fix: npx cache paths are ephemeral, this path is permanent
+  const stableAgent = installAgentLocally(!!args.update);
+  if (stableAgent) {
+    console.log(`  Agent installed at: ${stableAgent}`);
+    console.log('  (This path survives VPN changes, npx cache clears, and reboots)');
+    console.log('');
+  }
+
   // Set environment variables for the local agent
   process.env.KNOXIS_BACKEND_WS_URL = config.backendWsUrl;
   process.env.KNOXIS_USER_ID = config.userId;
+  // Tell the agent to use the stable path for its LaunchAgent plist
+  process.env.KNOXIS_STABLE_AGENT_PATH = STABLE_AGENT_PATH;
 
-  // Launch the local agent
-  // Try to find it in common locations
+  // Determine which agent to load: prefer stable install, fall back to package location
   const agentLocations = [
+    STABLE_AGENT_PATH,
     path.join(__dirname, '..', 'lib', 'knoxis-local-agent.js'),
     path.join(__dirname, '..', '..', 'knoxis-local-agent.js'),
     path.join(process.cwd(), 'scripts', 'knoxis-local-agent.js'),

package/lib/knoxis-local-agent.js

@@ -446,7 +446,7 @@ async function handleRequest(req, res) {
       status: 'healthy',
       platform: os.platform(),
       agent: 'knoxis-local-agent',
-      version: '2.1.0-https',
+      version: '2.2.0-stable',
       secure: serverMeta.secure,
       port: serverMeta.port,
       dependencies: 'none',
@@ -864,7 +864,13 @@ function ensureLaunchAgentIfNeeded() {
     }
 
     const plistPath = path.join(agentsDir, 'com.knoxis.helper.plist');
-    const programArgs = [process.execPath, __filename];
+
+    // Use the stable path (~/.knoxis/agent/) if available, NOT the ephemeral npx cache path.
+    // This is critical: npx cache paths change on every download, breaking the LaunchAgent.
+    const stableAgentPath = process.env.KNOXIS_STABLE_AGENT_PATH
+      || path.join(os.homedir(), '.knoxis', 'agent', 'knoxis-local-agent.js');
+    const agentScript = fs.existsSync(stableAgentPath) ? stableAgentPath : __filename;
+    const programArgs = [process.execPath, agentScript];
 
     const logDir = path.join(os.homedir(), 'Library', 'Logs');
     if (!fs.existsSync(logDir)) {
@@ -904,7 +910,7 @@ function ensureLaunchAgentIfNeeded() {
       spawnSync('launchctl', ['unload', plistPath]);
       const load = spawnSync('launchctl', ['load', '-w', plistPath]);
       if (load.status === 0) {
-        console.log('🛠️  Installed launch agent to auto-start Knoxis helper');
+        console.log(`🛠️  Installed launch agent (pointing to ${agentScript})`);
       } else {
         console.warn('⚠️  Unable to automatically load launch agent. Run:');
         console.warn(`   launchctl load -w ${plistPath}`);
@@ -934,10 +940,12 @@ function loadConfigFallback() {
 const _config = loadConfigFallback();
 const BACKEND_WS_URL = process.env.KNOXIS_BACKEND_WS_URL || _config.backendWsUrl || null;
 const RELAY_USER_ID = process.env.KNOXIS_USER_ID || _config.userId || null;
-const RELAY_RECONNECT_INTERVAL_MS = parseInt(process.env.KNOXIS_RECONNECT_MS || '10000', 10);
+const RELAY_RECONNECT_BASE_MS = parseInt(process.env.KNOXIS_RECONNECT_MS || '2000', 10);
+const RELAY_RECONNECT_MAX_MS = 60000; // Cap at 60s
 
 let relaySocket = null;
 let relayReconnectTimer = null;
+let relayReconnectAttempts = 0;
 
 function connectRelayWebSocket() {
   if (!BACKEND_WS_URL || !RELAY_USER_ID) {
@@ -972,6 +980,7 @@ function connectRelayWebSocket() {
 
   relaySocket.onopen = () => {
     console.log('✅ Relay WebSocket connected to backend');
+    relayReconnectAttempts = 0; // Reset backoff on successful connection
     if (relayReconnectTimer) {
       clearTimeout(relayReconnectTimer);
       relayReconnectTimer = null;
@@ -1036,9 +1045,16 @@ function connectRelayWebSocket() {
   };
 
   relaySocket.onclose = (event) => {
-    console.log(`🔌 Relay WebSocket closed (code: ${event.code || 'unknown'})`);
+    const code = event.code || 'unknown';
+    console.log(`🔌 Relay WebSocket closed (code: ${code})`);
     relaySocket = null;
-    scheduleRelayReconnect();
+    // Abnormal closure (1006) or going away (1001) — reconnect immediately
+    if (code === 1006 || code === 1001) {
+      console.log('⚡ Unexpected close — reconnecting immediately...');
+      setTimeout(() => connectRelayWebSocket(), 500);
+    } else {
+      scheduleRelayReconnect();
+    }
   };
 
   relaySocket.onerror = (err) => {
@@ -1051,11 +1067,24 @@ function scheduleRelayReconnect() {
   if (relayReconnectTimer) return;
   if (!BACKEND_WS_URL || !RELAY_USER_ID) return;
 
-  console.log(`⏳ Relay reconnecting in ${RELAY_RECONNECT_INTERVAL_MS / 1000}s...`);
+  // Exponential backoff: 2s, 4s, 8s, 16s, 32s, 60s (capped)
+  // This prevents log spam when VPN blocks the backend
+  relayReconnectAttempts++;
+  const delay = Math.min(RELAY_RECONNECT_BASE_MS * Math.pow(2, relayReconnectAttempts - 1), RELAY_RECONNECT_MAX_MS);
+  const delaySec = (delay / 1000).toFixed(0);
+
+  if (relayReconnectAttempts <= 3) {
+    console.log(`⏳ Relay reconnecting in ${delaySec}s... (attempt ${relayReconnectAttempts})`);
+  } else if (relayReconnectAttempts === 4) {
+    console.log(`⏳ Relay reconnecting in ${delaySec}s... (backend may be unreachable — VPN?)`);
+    console.log('   Local agent (localhost:3456) still works. Relay will keep retrying quietly.');
+  }
+  // After attempt 4, reconnect silently to avoid log noise
+
   relayReconnectTimer = setTimeout(() => {
     relayReconnectTimer = null;
     connectRelayWebSocket();
-  }, RELAY_RECONNECT_INTERVAL_MS);
+  }, delay);
 }
 
 // Send heartbeat to keep relay alive

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "knoxis-helper",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"
   },
-  "keywords": ["knoxis", "pair-programming", "claude", "qig"],
+  "keywords": [
+    "knoxis",
+    "pair-programming",
+    "claude",
+    "qig"
+  ],
   "license": "MIT",
   "engines": {
     "node": ">=18"