knoxis-helper 1.0.0

package/lib/knoxis-local-agent.js

@@ -0,0 +1,1137 @@
+#!/usr/bin/env node
+
+/**
+ * Knoxis Local Agent - Zero Dependencies Version
+ *
+ * Runs on the user's local machine to handle terminal operations
+ * when the backend is deployed in Azure.
+ *
+ * Usage:
+ *   node knoxis-local-agent.js
+ *   curl -L https://github.com/USER/REPO/releases/latest/download/knoxis-helper.js | node - pair
+ *
+ * The web frontend connects to this agent at http://localhost:3456
+ * to request terminal operations on the user's local machine.
+ *
+ * ZERO EXTERNAL DEPENDENCIES - uses only Node.js built-in modules
+ */
+
+const http = require('http');
+const https = require('https');
+const { exec, spawn, spawnSync } = require('child_process');
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const url = require('url');
+
+const DEFAULT_PORT = parseInt(process.env.KNOXIS_AGENT_PORT || '3456', 10);
+const CERT_DIR = process.env.KNOXIS_CERT_DIR || path.join(os.homedir(), '.knoxis', 'certs');
+const CERT_FILE = process.env.KNOXIS_CERT_FILE || path.join(CERT_DIR, 'localhost.pem');
+const KEY_FILE = process.env.KNOXIS_CERT_KEY || path.join(CERT_DIR, 'localhost-key.pem');
+
+// Trusted origins for CORS (deployed frontends)
+const TRUSTED_ORIGINS = [
+  'https://qig.ai',
+  'https://www.qig.ai',
+  'https://app.qig.ai',
+  'http://localhost:3000',
+  'http://localhost:5173',
+  'http://127.0.0.1:3000',
+  'http://127.0.0.1:5173'
+];
+const ALLOWED_ORIGINS = (process.env.KNOXIS_ALLOWED_ORIGINS || '')
+  .split(',')
+  .map(origin => origin.trim())
+  .filter(Boolean);
+// Merge custom origins with trusted ones
+const ALL_ALLOWED_ORIGINS = [...new Set([...TRUSTED_ORIGINS, ...ALLOWED_ORIGINS])];
+
+const serverMeta = { secure: false, port: DEFAULT_PORT };
+
+/**
+ * Generate self-signed certificate for HTTPS using OpenSSL (pre-installed on macOS/Linux)
+ */
+function generateSelfSignedCert() {
+  console.log('🔐 Generating self-signed certificate...');
+
+  if (!fs.existsSync(CERT_DIR)) {
+    fs.mkdirSync(CERT_DIR, { recursive: true });
+  }
+
+  const keyPath = path.join(CERT_DIR, 'localhost-key.pem');
+  const certPath = path.join(CERT_DIR, 'localhost.pem');
+
+  // Generate key + cert in one command
+  const result = spawnSync('openssl', [
+    'req', '-x509', '-newkey', 'rsa:2048',
+    '-keyout', keyPath,
+    '-out', certPath,
+    '-days', '365',
+    '-nodes',
+    '-subj', '/CN=localhost',
+    '-addext', 'subjectAltName=DNS:localhost,IP:127.0.0.1'
+  ], { stdio: 'pipe' });
+
+  if (result.status === 0) {
+    console.log('✅ Certificate generated');
+    return true;
+  }
+
+  console.warn('⚠️  OpenSSL failed - running in HTTP mode');
+  return false;
+}
+
+/**
+ * Get CORS headers for the given request origin
+ */
+function getCorsHeaders(requestOrigin) {
+  const headers = {
+    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS, PATCH',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
+    'Access-Control-Max-Age': '86400'
+  };
+
+  // Check if origin is allowed
+  if (requestOrigin) {
+    const isAllowed = ALL_ALLOWED_ORIGINS.some(allowed => {
+      if (allowed === '*') return true;
+      return requestOrigin === allowed || requestOrigin.endsWith(allowed.replace('https://', '.'));
+    });
+
+    if (isAllowed) {
+      // Use specific origin (required when credentials are used)
+      headers['Access-Control-Allow-Origin'] = requestOrigin;
+      headers['Access-Control-Allow-Credentials'] = 'true';
+    } else {
+      // For unknown origins, allow without credentials
+      headers['Access-Control-Allow-Origin'] = '*';
+    }
+  } else {
+    headers['Access-Control-Allow-Origin'] = '*';
+  }
+
+  return headers;
+}
+
+function escapeForDoubleQuotedShellArg(value) {
+  return String(value || '')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$')
+    .replace(/`/g, '\\`')
+    .replace(/!/g, '\\!');
+}
+
+const DEFAULT_HEADLESS_TIMEOUT_MS = parseInt(process.env.KNOXIS_HEADLESS_TIMEOUT_MS || '1200000', 10); // 20 min
+const DEFAULT_HEADLESS_MAX_OUTPUT_CHARS = parseInt(process.env.KNOXIS_HEADLESS_MAX_OUTPUT_CHARS || '50000', 10);
+
+function buildShellCommand(command) {
+  if (os.platform() === 'win32') {
+    return { cmd: 'cmd.exe', args: ['/c', command] };
+  }
+  return { cmd: 'bash', args: ['-lc', command] };
+}
+
+function commandExists(cmd) {
+  const detector = os.platform() === 'win32' ? 'where' : 'which';
+  const result = spawnSync(detector, [cmd], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function safeBasename(value) {
+  return String(value || '').replace(/[^a-zA-Z0-9._-]+/g, '_').slice(0, 80) || 'session';
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function runHeadlessProcess({ workspace, command, prompt, sessionLabel }) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    const workspaceDir = workspace || process.cwd();
+
+    const logDir = path.join(workspaceDir, '.knoxis', 'headless');
+    ensureDir(logDir);
+    const logFile = path.join(logDir, `${Date.now()}-${safeBasename(sessionLabel)}.log`);
+    const logStream = fs.createWriteStream(logFile, { encoding: 'utf8' });
+
+    const trimmedCommand = String(command || '').trim();
+    const hasPrompt = typeof prompt === 'string' && prompt.trim().length > 0;
+    const lowerCommand = trimmedCommand.toLowerCase();
+    const looksLikePairProgram = lowerCommand.includes('knoxis-pair-program');
+
+    let proc;
+    let stdout = '';
+    let stderr = '';
+    let truncated = false;
+    let timedOut = false;
+
+    const capture = (chunk, isStdErr) => {
+      const text = chunk.toString();
+      logStream.write(text);
+      if (isStdErr) {
+        stderr += text;
+        return;
+      }
+      if (stdout.length < DEFAULT_HEADLESS_MAX_OUTPUT_CHARS) {
+        stdout += text;
+      } else {
+        truncated = true;
+      }
+    };
+
+    const finish = (exitCode) => {
+      try { logStream.end(); } catch (e) {}
+      resolve({
+        success: exitCode === 0 && !timedOut,
+        exitCode,
+        timedOut,
+        truncated,
+        durationMs: Date.now() - startedAt,
+        workspace: workspaceDir,
+        logFile,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+      });
+    };
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      try { proc.kill('SIGKILL'); } catch (e) {}
+    }, DEFAULT_HEADLESS_TIMEOUT_MS);
+
+    const spawnShell = (shellCommand) => {
+      const spec = buildShellCommand(shellCommand);
+      proc = spawn(spec.cmd, spec.args, { cwd: workspaceDir, env: process.env });
+      proc.stdout.on('data', chunk => capture(chunk, false));
+      proc.stderr.on('data', chunk => capture(chunk, true));
+      proc.on('close', code => {
+        clearTimeout(timeout);
+        finish(code == null ? 1 : code);
+      });
+    };
+
+    if (!looksLikePairProgram && hasPrompt && (!trimmedCommand || lowerCommand.startsWith('claude'))) {
+      if (!commandExists('claude')) {
+        clearTimeout(timeout);
+        finish(127);
+        return;
+      }
+
+      proc = spawn('claude', ['--dangerously-skip-permissions'], { cwd: workspaceDir, env: process.env, stdio: ['pipe', 'pipe', 'pipe'] });
+      proc.stdout.on('data', chunk => capture(chunk, false));
+      proc.stderr.on('data', chunk => capture(chunk, true));
+      proc.on('close', code => {
+        clearTimeout(timeout);
+        finish(code == null ? 1 : code);
+      });
+
+      proc.stdin.write(prompt);
+      proc.stdin.end();
+      return;
+    }
+
+    if (trimmedCommand) {
+      spawnShell(trimmedCommand);
+      return;
+    }
+
+    // Fallback: no command, no prompt
+    clearTimeout(timeout);
+    finish(1);
+  });
+}
+
+// ===== WORKSPACE MANAGEMENT (self-contained) =====
+const KNOXIS_DIR = path.join(os.homedir(), '.knoxis');
+const WORKSPACES_FILE = path.join(KNOXIS_DIR, 'workspaces.json');
+const RECENT_FILE = path.join(KNOXIS_DIR, 'recent.json');
+
+function ensureKnoxisDir() {
+  if (!fs.existsSync(KNOXIS_DIR)) {
+    fs.mkdirSync(KNOXIS_DIR, { recursive: true });
+  }
+}
+
+function loadWorkspaces() {
+  ensureKnoxisDir();
+  try {
+    if (fs.existsSync(WORKSPACES_FILE)) {
+      return JSON.parse(fs.readFileSync(WORKSPACES_FILE, 'utf8'));
+    }
+  } catch (e) {
+    console.warn('⚠️ Failed to load workspaces:', e.message);
+  }
+  return {};
+}
+
+function saveWorkspaces(workspaces) {
+  ensureKnoxisDir();
+  fs.writeFileSync(WORKSPACES_FILE, JSON.stringify(workspaces, null, 2));
+}
+
+function resolveWorkspacePath(nameOrPath) {
+  // Direct path
+  if (fs.existsSync(nameOrPath)) {
+    return path.resolve(nameOrPath);
+  }
+
+  // Try workspace registry
+  const workspaces = loadWorkspaces();
+  if (workspaces[nameOrPath]) {
+    return workspaces[nameOrPath];
+  }
+
+  // Fuzzy match
+  const lower = nameOrPath.toLowerCase();
+  for (const [name, wsPath] of Object.entries(workspaces)) {
+    if (name.toLowerCase().includes(lower)) {
+      return wsPath;
+    }
+  }
+
+  return null;
+}
+
+function discoverProjects() {
+  const discovered = {};
+  const searchDirs = [
+    path.join(os.homedir(), 'Projects'),
+    path.join(os.homedir(), 'IdeaProjects'),
+    path.join(os.homedir(), 'Developer'),
+    path.join(os.homedir(), 'Code'),
+    path.join(os.homedir(), 'dev'),
+    path.join(os.homedir(), 'src'),
+    path.join(os.homedir(), 'work'),
+  ];
+
+  for (const searchDir of searchDirs) {
+    if (fs.existsSync(searchDir)) {
+      try {
+        const entries = fs.readdirSync(searchDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            const projectPath = path.join(searchDir, entry.name);
+            // Check if it looks like a project
+            const hasGit = fs.existsSync(path.join(projectPath, '.git'));
+            const hasPackage = fs.existsSync(path.join(projectPath, 'package.json'));
+            const hasPom = fs.existsSync(path.join(projectPath, 'pom.xml'));
+            const hasSrc = fs.existsSync(path.join(projectPath, 'src'));
+
+            if (hasGit || hasPackage || hasPom || hasSrc) {
+              discovered[entry.name] = projectPath;
+            }
+          }
+        }
+      } catch (e) {
+        // Skip inaccessible directories
+      }
+    }
+  }
+
+  return discovered;
+}
+
+// ===== FILE FINDER (self-contained) =====
+function findFilesRecursive(dir, patterns, results = [], maxDepth = 5, currentDepth = 0) {
+  if (currentDepth > maxDepth || results.length >= 20) return results;
+
+  const skipDirs = ['node_modules', '.git', 'target', 'build', 'dist', '__pycache__', 'venv', '.idea'];
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (results.length >= 20) break;
+
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!skipDirs.includes(entry.name) && !entry.name.startsWith('.')) {
+          findFilesRecursive(fullPath, patterns, results, maxDepth, currentDepth + 1);
+        }
+      } else if (entry.isFile()) {
+        const nameLower = entry.name.toLowerCase();
+        const matches = patterns.some(p => nameLower.includes(p.toLowerCase()));
+        if (matches) {
+          results.push(fullPath);
+        }
+      }
+    }
+  } catch (e) {
+    // Skip inaccessible directories
+  }
+
+  return results;
+}
+
+function extractSearchPatterns(query) {
+  const patterns = [];
+  const lower = query.toLowerCase();
+
+  // Map common terms to file patterns
+  const termMappings = {
+    'controller': ['Controller', 'controller'],
+    'service': ['Service', 'service'],
+    'model': ['Model', 'Entity', 'model', 'entity'],
+    'repo': ['Repository', 'Repo', 'repository'],
+    'config': ['Config', 'config', '.yml', '.yaml', '.properties'],
+    'test': ['Test', 'Spec', 'test', 'spec'],
+    'component': ['Component', 'component', '.tsx', '.jsx'],
+    'hook': ['use', 'Hook'],
+    'api': ['Api', 'Endpoint', 'Route', 'api'],
+    'voice': ['Voice', 'voice', 'Audio', 'audio'],
+    'intent': ['Intent', 'intent'],
+  };
+
+  for (const [term, mappings] of Object.entries(termMappings)) {
+    if (lower.includes(term)) {
+      patterns.push(...mappings);
+    }
+  }
+
+  // Add individual words from query
+  const words = query.split(/\s+/).filter(w => w.length >= 3);
+  patterns.push(...words);
+
+  return [...new Set(patterns)];
+}
+
+// Helper to parse JSON body
+function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', chunk => { body += chunk.toString(); });
+    req.on('end', () => {
+      try {
+        resolve(body ? JSON.parse(body) : {});
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+// Helper to send JSON response
+function sendJSON(res, statusCode, data, requestOrigin) {
+  const corsHeaders = getCorsHeaders(requestOrigin);
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json',
+    ...corsHeaders
+  });
+  res.end(JSON.stringify(data));
+}
+
+// Request handler
+async function handleRequest(req, res) {
+  const parsedUrl = url.parse(req.url, true);
+  const pathname = parsedUrl.pathname;
+  const method = req.method;
+  const requestOrigin = req.headers.origin || req.headers.referer?.replace(/\/$/, '') || '';
+
+  // Handle CORS preflight
+  if (method === 'OPTIONS') {
+    const corsHeaders = getCorsHeaders(requestOrigin);
+    res.writeHead(204, corsHeaders);
+    return res.end();
+  }
+
+  // Health check
+  if (pathname === '/health' && method === 'GET') {
+    return sendJSON(res, 200, {
+      status: 'healthy',
+      platform: os.platform(),
+      agent: 'knoxis-local-agent',
+      version: '2.1.0-https',
+      secure: serverMeta.secure,
+      port: serverMeta.port,
+      dependencies: 'none',
+      allowedOrigins: ALL_ALLOWED_ORIGINS
+    }, requestOrigin);
+  }
+
+  // Execute terminal command
+  if (pathname === '/terminal/execute' && method === 'POST') {
+    try {
+      const body = await parseBody(req);
+      const { workspaceDirectory, workingDirectory, command, prompt, headless, sessionId } = body;
+      const workspace = workspaceDirectory || workingDirectory;
+
+      console.log('📂 Workspace:', workspace);
+      console.log('📝 Command:', command);
+      if (prompt) console.log('💬 Prompt length:', prompt.length);
+      if (headless) console.log('🫥 Headless:', true);
+
+      const platform = os.platform();
+
+      if (headless) {
+        const result = await runHeadlessProcess({
+          workspace,
+          command,
+          prompt,
+          sessionLabel: sessionId || 'pair'
+        });
+        return sendJSON(res, result.success ? 200 : 500, result, requestOrigin);
+      }
+
+      if (platform === 'darwin') {
+        await openMacTerminal(workspace, command);
+        return sendJSON(res, 200, { success: true, message: 'Terminal opened on macOS', platform: 'darwin' }, requestOrigin);
+      }
+      if (platform === 'win32') {
+        await openWindowsTerminal(workspace, command);
+        return sendJSON(res, 200, { success: true, message: 'Terminal opened on Windows', platform: 'win32' }, requestOrigin);
+      }
+
+      await openLinuxTerminal(workspace, command);
+      return sendJSON(res, 200, { success: true, message: 'Terminal opened on Linux', platform: 'linux' }, requestOrigin);
+
+    } catch (error) {
+      console.error('❌ Failed to open terminal:', error);
+      return sendJSON(res, 500, { success: false, error: error.message }, requestOrigin);
+    }
+  }
+
+  // Directory check
+  if (pathname === '/directory/check' && method === 'GET') {
+    const dirPath = parsedUrl.query.path;
+
+    if (!dirPath) {
+      return sendJSON(res, 400, { success: false, error: 'Path parameter required' }, requestOrigin);
+    }
+
+    try {
+      const exists = fs.existsSync(dirPath);
+      const stats = exists ? fs.statSync(dirPath) : null;
+
+      return sendJSON(res, 200, {
+        success: true,
+        exists,
+        isDirectory: stats ? stats.isDirectory() : false,
+        path: dirPath
+      }, requestOrigin);
+    } catch (error) {
+      return sendJSON(res, 200, { success: false, exists: false, error: error.message }, requestOrigin);
+    }
+  }
+
+  // ===== WORKSPACE MANAGEMENT ENDPOINTS =====
+
+  // List all workspaces
+  if (pathname === '/workspace/list' && method === 'GET') {
+    const workspaces = loadWorkspaces();
+    const list = Object.entries(workspaces).map(([name, wsPath]) => ({
+      name,
+      path: wsPath,
+      exists: fs.existsSync(wsPath)
+    }));
+    return sendJSON(res, 200, { success: true, workspaces: list }, requestOrigin);
+  }
+
+  // Get workspace by name (with fuzzy matching)
+  if (pathname === '/workspace/get' && method === 'GET') {
+    const name = parsedUrl.query.name;
+    if (!name) {
+      return sendJSON(res, 400, { success: false, error: 'Name parameter required' }, requestOrigin);
+    }
+
+    const wsPath = resolveWorkspacePath(name);
+    if (wsPath) {
+      return sendJSON(res, 200, { success: true, name, path: wsPath }, requestOrigin);
+    }
+    return sendJSON(res, 404, { success: false, error: `Workspace not found: ${name}` }, requestOrigin);
+  }
+
+  // Save workspace
+  if (pathname === '/workspace/save' && method === 'POST') {
+    try {
+      const body = await parseBody(req);
+      const { name, path: wsPath } = body;
+
+      if (!name) {
+        return sendJSON(res, 400, { success: false, error: 'Name required' }, requestOrigin);
+      }
+
+      const pathToSave = wsPath || process.cwd();
+      const resolved = path.resolve(pathToSave);
+
+      if (!fs.existsSync(resolved)) {
+        return sendJSON(res, 400, { success: false, error: `Path does not exist: ${resolved}` }, requestOrigin);
+      }
+
+      const workspaces = loadWorkspaces();
+      workspaces[name] = resolved;
+      saveWorkspaces(workspaces);
+
+      return sendJSON(res, 200, { success: true, name, path: resolved }, requestOrigin);
+    } catch (error) {
+      return sendJSON(res, 500, { success: false, error: error.message }, requestOrigin);
+    }
+  }
+
+  // Remove workspace
+  if (pathname === '/workspace/remove' && method === 'DELETE') {
+    const name = parsedUrl.query.name;
+    if (!name) {
+      return sendJSON(res, 400, { success: false, error: 'Name parameter required' }, requestOrigin);
+    }
+
+    const workspaces = loadWorkspaces();
+    if (workspaces[name]) {
+      delete workspaces[name];
+      saveWorkspaces(workspaces);
+      return sendJSON(res, 200, { success: true, message: `Removed workspace: ${name}` }, requestOrigin);
+    }
+    return sendJSON(res, 404, { success: false, error: `Workspace not found: ${name}` }, requestOrigin);
+  }
+
+  // Discover projects automatically
+  if (pathname === '/workspace/discover' && method === 'POST') {
+    const discovered = discoverProjects();
+    const workspaces = loadWorkspaces();
+    let added = 0;
+
+    for (const [name, wsPath] of Object.entries(discovered)) {
+      if (!workspaces[name]) {
+        workspaces[name] = wsPath;
+        added++;
+      }
+    }
+
+    saveWorkspaces(workspaces);
+
+    return sendJSON(res, 200, {
+      success: true,
+      discovered: Object.keys(discovered).length,
+      added,
+      workspaces: Object.entries(workspaces).map(([name, wsPath]) => ({ name, path: wsPath }))
+    }, requestOrigin);
+  }
+
+  // ===== FILE FINDER ENDPOINTS =====
+
+  // Find files in workspace
+  if (pathname === '/files/find' && method === 'GET') {
+    const query = parsedUrl.query.query || parsedUrl.query.q;
+    const workspace = parsedUrl.query.workspace || parsedUrl.query.w;
+    const maxResults = parseInt(parsedUrl.query.max || '10');
+
+    if (!query) {
+      return sendJSON(res, 400, { success: false, error: 'Query parameter required' }, requestOrigin);
+    }
+
+    let searchDir = process.cwd();
+    if (workspace) {
+      const wsPath = resolveWorkspacePath(workspace);
+      if (wsPath) {
+        searchDir = wsPath;
+      } else {
+        return sendJSON(res, 404, { success: false, error: `Workspace not found: ${workspace}` }, requestOrigin);
+      }
+    }
+
+    const patterns = extractSearchPatterns(query);
+    const results = findFilesRecursive(searchDir, patterns, [], 6, 0);
+
+    const files = results.slice(0, maxResults).map(fullPath => ({
+      path: fullPath.replace(searchDir + '/', ''),
+      fullPath,
+      name: path.basename(fullPath)
+    }));
+
+    return sendJSON(res, 200, {
+      success: true,
+      query,
+      workspace: workspace || null,
+      searchDir,
+      patterns,
+      files
+    }, requestOrigin);
+  }
+
+  // ===== PAIR PROGRAMMING ENDPOINTS =====
+
+  // Start pair programming session (opens terminal)
+  if (pathname === '/pair/start' && method === 'POST') {
+    try {
+      const body = await parseBody(req);
+      const { workspace, task, file, provider, headless, sessionId } = body;
+
+      if (!task) {
+        return sendJSON(res, 400, { success: false, error: 'Task description required' }, requestOrigin);
+      }
+
+      let workspaceDir = process.cwd();
+      if (workspace) {
+        const wsPath = resolveWorkspacePath(workspace);
+        if (wsPath) {
+          workspaceDir = wsPath;
+        } else {
+          return sendJSON(res, 404, { success: false, error: `Workspace not found: ${workspace}` }, requestOrigin);
+        }
+      }
+
+      // Build the prompt for Claude
+      let prompt = task;
+      if (file) {
+        prompt = `Working on file: ${file}\n\nTask: ${task}`;
+      }
+
+      // Build command - use claude with auto-approve
+      const command = `claude --dangerously-skip-permissions "${escapeForDoubleQuotedShellArg(prompt)}"`;
+
+      if (headless) {
+        const result = await runHeadlessProcess({
+          workspace: workspaceDir,
+          command: provider && String(provider).toLowerCase() === 'codex' ? 'codex' : 'claude',
+          prompt,
+          sessionLabel: sessionId || 'pair'
+        });
+        return sendJSON(res, result.success ? 200 : 500, result, requestOrigin);
+      }
+
+      const platform = os.platform();
+      if (platform === 'darwin') {
+        await openMacTerminal(workspaceDir, command);
+      } else if (platform === 'win32') {
+        await openWindowsTerminal(workspaceDir, command);
+      } else {
+        await openLinuxTerminal(workspaceDir, command);
+      }
+
+      return sendJSON(res, 200, {
+        success: true,
+        message: 'Pair programming session started',
+        workspace: workspaceDir,
+        task,
+        file: file || null
+      }, requestOrigin);
+    } catch (error) {
+      return sendJSON(res, 500, { success: false, error: error.message }, requestOrigin);
+    }
+  }
+
+  // 404
+  sendJSON(res, 404, { error: 'Not found' }, requestOrigin);
+}
+
+/**
+ * Open terminal on macOS
+ */
+function openMacTerminal(workspaceDir, command) {
+  return new Promise((resolve, reject) => {
+    if (!fs.existsSync(workspaceDir)) {
+      fs.mkdirSync(workspaceDir, { recursive: true });
+    }
+
+    const escapedDir = workspaceDir.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    let finalCommand = command;
+
+    if (command.includes('claude') && !command.includes('--dangerously-skip-permissions')) {
+      finalCommand = command.replace(/^claude\s+/, 'claude --dangerously-skip-permissions ');
+    }
+
+    const escapedCommand = finalCommand.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+
+    const appleScript = `
+tell application "Terminal"
+    activate
+    set newTab to do script "cd \\"${escapedDir}\\""
+    delay 0.5
+    do script "${escapedCommand}" in newTab
+end tell
+    `.trim();
+
+    const tempScript = `/tmp/knoxis-terminal-${Date.now()}.scpt`;
+    fs.writeFileSync(tempScript, appleScript);
+
+    exec(`osascript "${tempScript}"`, (error) => {
+      try { fs.unlinkSync(tempScript); } catch (e) {}
+
+      if (error) {
+        console.error('❌ AppleScript error:', error);
+        reject(error);
+      } else {
+        console.log('✅ Terminal opened on macOS');
+        resolve();
+      }
+    });
+  });
+}
+
+/**
+ * Open terminal on Windows
+ */
+function openWindowsTerminal(workspaceDir, command) {
+  return new Promise((resolve, reject) => {
+    if (!fs.existsSync(workspaceDir)) {
+      fs.mkdirSync(workspaceDir, { recursive: true });
+    }
+
+    const fullCommand = `start cmd /K "cd /d "${workspaceDir}" && ${command}"`;
+
+    exec(fullCommand, (error) => {
+      if (error) {
+        console.error('❌ Windows terminal error:', error);
+        reject(error);
+      } else {
+        console.log('✅ Terminal opened on Windows');
+        resolve();
+      }
+    });
+  });
+}
+
+/**
+ * Open terminal on Linux
+ */
+function openLinuxTerminal(workspaceDir, command) {
+  return new Promise((resolve, reject) => {
+    if (!fs.existsSync(workspaceDir)) {
+      fs.mkdirSync(workspaceDir, { recursive: true });
+    }
+
+    const fullCommand = `gnome-terminal --working-directory="${workspaceDir}" -- bash -c "${command}; exec bash"`;
+
+    exec(fullCommand, (error) => {
+      if (error) {
+        const xtermCommand = `xterm -e "cd '${workspaceDir}' && ${command}; bash"`;
+        exec(xtermCommand, (error2) => {
+          if (error2) {
+            console.error('❌ Linux terminal error:', error2);
+            reject(error2);
+          } else {
+            console.log('✅ Terminal opened on Linux (xterm)');
+            resolve();
+          }
+        });
+      } else {
+        console.log('✅ Terminal opened on Linux (gnome-terminal)');
+        resolve();
+      }
+    });
+  });
+}
+
+function createServer() {
+  // Try to load existing certs
+  try {
+    if (fs.existsSync(KEY_FILE) && fs.existsSync(CERT_FILE)) {
+      const key = fs.readFileSync(KEY_FILE);
+      const cert = fs.readFileSync(CERT_FILE);
+      serverMeta.secure = true;
+      return https.createServer({ key, cert }, handleRequest);
+    }
+  } catch (err) {
+    console.warn('⚠️  Failed to load TLS certificates:', err.message);
+  }
+
+  // No certs exist - try to generate them
+  if (!fs.existsSync(CERT_FILE) || !fs.existsSync(KEY_FILE)) {
+    const generated = generateSelfSignedCert();
+    if (generated && fs.existsSync(KEY_FILE) && fs.existsSync(CERT_FILE)) {
+      try {
+        const key = fs.readFileSync(KEY_FILE);
+        const cert = fs.readFileSync(CERT_FILE);
+        serverMeta.secure = true;
+        return https.createServer({ key, cert }, handleRequest);
+      } catch (err) {
+        console.warn('⚠️  Failed to load generated certificates:', err.message);
+      }
+    }
+  }
+
+  // Fallback to HTTP (will cause mixed content issues from HTTPS frontends)
+  serverMeta.secure = false;
+  console.warn('');
+  console.warn('⚠️  RUNNING IN HTTP MODE - This will cause 405/CORS errors from HTTPS frontends!');
+  console.warn('');
+  return http.createServer(handleRequest);
+}
+
+function ensureLaunchAgentIfNeeded() {
+  if (process.platform !== 'darwin') return;
+  if (process.env.KNOXIS_SKIP_LAUNCH_AGENT === '1') return;
+
+  try {
+    const agentsDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    if (!fs.existsSync(agentsDir)) {
+      fs.mkdirSync(agentsDir, { recursive: true });
+    }
+
+    const plistPath = path.join(agentsDir, 'com.knoxis.helper.plist');
+    const programArgs = [process.execPath, __filename];
+
+    const logDir = path.join(os.homedir(), 'Library', 'Logs');
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    const stdoutPath = path.join(logDir, 'KnoxisHelper.log');
+
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>com.knoxis.helper</string>
+    <key>ProgramArguments</key>
+    <array>
+      ${programArgs.map(arg => `<string>${arg}</string>`).join('\n      ')}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${stdoutPath}</string>
+    <key>StandardErrorPath</key>
+    <string>${stdoutPath}</string>
+  </dict>
+</plist>`;
+
+    let needsWrite = true;
+    if (fs.existsSync(plistPath)) {
+      const current = fs.readFileSync(plistPath, 'utf8');
+      if (current === plist) needsWrite = false;
+    }
+
+    if (needsWrite) {
+      fs.writeFileSync(plistPath, plist, 'utf8');
+      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');
+      } else {
+        console.warn('⚠️  Unable to automatically load launch agent. Run:');
+        console.warn(`   launchctl load -w ${plistPath}`);
+      }
+    }
+
+  } catch (err) {
+    console.warn('⚠️  Unable to configure auto-start for Knoxis helper:', err.message);
+  }
+}
+
+// ===== WEBSOCKET RELAY CLIENT =====
+// Connects to the deployed backend's WebSocket to receive pair programming commands
+// without needing the frontend to relay. Backend pushes commands directly.
+
+const BACKEND_WS_URL = process.env.KNOXIS_BACKEND_WS_URL || null;
+const RELAY_USER_ID = process.env.KNOXIS_USER_ID || null;
+const RELAY_RECONNECT_INTERVAL_MS = parseInt(process.env.KNOXIS_RECONNECT_MS || '10000', 10);
+
+let relaySocket = null;
+let relayReconnectTimer = null;
+
+function connectRelayWebSocket() {
+  if (!BACKEND_WS_URL || !RELAY_USER_ID) {
+    return; // Not configured - skip relay
+  }
+
+  const wsUrl = `${BACKEND_WS_URL}/ws/knoxis-terminal?userId=${encodeURIComponent(RELAY_USER_ID)}`;
+  console.log(`🔌 Connecting relay to: ${wsUrl}`);
+
+  // Use Node.js built-in WebSocket (Node 22+) or ws module
+  let WebSocketImpl;
+  try {
+    WebSocketImpl = globalThis.WebSocket || require('ws');
+  } catch (e) {
+    // For older Node versions without built-in WebSocket, try dynamic import or skip
+    try {
+      WebSocketImpl = require('ws');
+    } catch (e2) {
+      console.warn('⚠️  WebSocket relay requires Node 22+ or the "ws" package. Relay disabled.');
+      console.warn('   Install with: npm install ws');
+      return;
+    }
+  }
+
+  try {
+    relaySocket = new WebSocketImpl(wsUrl);
+  } catch (e) {
+    console.warn('⚠️  Failed to create WebSocket connection:', e.message);
+    scheduleRelayReconnect();
+    return;
+  }
+
+  relaySocket.onopen = () => {
+    console.log('✅ Relay WebSocket connected to backend');
+    if (relayReconnectTimer) {
+      clearTimeout(relayReconnectTimer);
+      relayReconnectTimer = null;
+    }
+  };
+
+  relaySocket.onmessage = async (event) => {
+    try {
+      const data = typeof event.data === 'string' ? event.data : event.data.toString();
+      const msg = JSON.parse(data);
+
+      if (msg.type === 'execute_command') {
+        console.log(`📥 Relay command received: ${msg.requestId}`);
+        console.log(`   📂 Dir: ${msg.workingDir}`);
+        console.log(`   📝 Cmd: ${(msg.command || '').substring(0, 100)}...`);
+
+        const workspace = msg.workingDir || process.cwd();
+        const command = msg.command || '';
+
+        let result;
+        try {
+          if (msg.headless) {
+            result = await runHeadlessProcess({
+              workspace,
+              command,
+              prompt: msg.prompt,
+              sessionLabel: msg.requestId || 'relay'
+            });
+          } else {
+            const platform = os.platform();
+            if (platform === 'darwin') {
+              await openMacTerminal(workspace, command);
+            } else if (platform === 'win32') {
+              await openWindowsTerminal(workspace, command);
+            } else {
+              await openLinuxTerminal(workspace, command);
+            }
+            result = { success: true, message: 'Terminal opened via relay' };
+          }
+        } catch (err) {
+          result = { success: false, error: err.message };
+        }
+
+        // Send result back to backend
+        const response = JSON.stringify({
+          type: 'command_result',
+          requestId: msg.requestId,
+          ...result,
+          timestamp: Date.now()
+        });
+
+        if (relaySocket && relaySocket.readyState === 1) { // OPEN
+          relaySocket.send(response);
+          console.log(`📤 Relay result sent for: ${msg.requestId} (success: ${result.success})`);
+        }
+      } else if (msg.type === 'connected') {
+        console.log(`🤝 Backend acknowledged: ${msg.message}`);
+      }
+    } catch (e) {
+      console.error('❌ Relay message handling error:', e.message);
+    }
+  };
+
+  relaySocket.onclose = (event) => {
+    console.log(`🔌 Relay WebSocket closed (code: ${event.code || 'unknown'})`);
+    relaySocket = null;
+    scheduleRelayReconnect();
+  };
+
+  relaySocket.onerror = (err) => {
+    console.error('❌ Relay WebSocket error:', err.message || 'connection failed');
+    // onclose will fire after this, triggering reconnect
+  };
+}
+
+function scheduleRelayReconnect() {
+  if (relayReconnectTimer) return;
+  if (!BACKEND_WS_URL || !RELAY_USER_ID) return;
+
+  console.log(`⏳ Relay reconnecting in ${RELAY_RECONNECT_INTERVAL_MS / 1000}s...`);
+  relayReconnectTimer = setTimeout(() => {
+    relayReconnectTimer = null;
+    connectRelayWebSocket();
+  }, RELAY_RECONNECT_INTERVAL_MS);
+}
+
+// Send heartbeat to keep relay alive
+function startRelayHeartbeat() {
+  if (!BACKEND_WS_URL || !RELAY_USER_ID) return;
+
+  setInterval(() => {
+    if (relaySocket && relaySocket.readyState === 1) {
+      try {
+        relaySocket.send(JSON.stringify({ type: 'heartbeat', timestamp: Date.now() }));
+      } catch (e) {
+        // Will reconnect on close
+      }
+    }
+  }, 30000); // Every 30 seconds
+}
+
+// Graceful shutdown
+function shutdown() {
+  console.log('\n👋 Shutting down Knoxis Local Agent...');
+  if (relaySocket) {
+    try { relaySocket.close(); } catch (e) {}
+  }
+  process.exit(0);
+}
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+
+// Start the server
+ensureLaunchAgentIfNeeded();
+const server = createServer();
+
+// Start WebSocket relay if configured
+connectRelayWebSocket();
+startRelayHeartbeat();
+
+server.listen(serverMeta.port, () => {
+  const scheme = serverMeta.secure ? 'https' : 'http';
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════════╗');
+  console.log('║       🚀 KNOXIS LOCAL AGENT v2.1.0 (HTTPS + CORS Fix)        ║');
+  console.log('╚══════════════════════════════════════════════════════════════╝');
+  console.log('');
+  console.log(`🔒 Mode: ${serverMeta.secure ? 'HTTPS (Secure)' : 'HTTP (Insecure - see warning below)'}`);
+  console.log(`🌐 Listening: ${scheme}://localhost:${serverMeta.port}`);
+  console.log(`📦 Dependencies: NONE (pure Node.js)`);
+  console.log('');
+  console.log('🔐 Allowed Origins (CORS):');
+  ALL_ALLOWED_ORIGINS.forEach(origin => console.log(`   ✓ ${origin}`));
+  console.log('');
+  console.log('📁 Workspace Management:');
+  console.log('   GET  /workspace/list          - List saved workspaces');
+  console.log('   GET  /workspace/get?name=X    - Get workspace path (fuzzy match)');
+  console.log('   POST /workspace/save          - Save workspace {name, path}');
+  console.log('   POST /workspace/discover      - Auto-discover projects');
+  console.log('');
+  console.log('🔍 File Finder:');
+  console.log('   GET  /files/find?q=X&w=Y      - Find files by query in workspace');
+  console.log('');
+  console.log('🤝 Pair Programming:');
+  console.log('   POST /pair/start              - Start session {workspace, task, file}');
+  console.log('');
+  if (BACKEND_WS_URL && RELAY_USER_ID) {
+    console.log('🔌 WebSocket Relay:');
+    console.log(`   Backend: ${BACKEND_WS_URL}`);
+    console.log(`   User ID: ${RELAY_USER_ID}`);
+    console.log('   Status: Connecting...');
+    console.log('');
+  } else {
+    console.log('📡 WebSocket Relay: Not configured');
+    console.log('   Set KNOXIS_BACKEND_WS_URL and KNOXIS_USER_ID to enable');
+    console.log(`   Example: KNOXIS_BACKEND_WS_URL=wss://your-backend.azurecontainerapps.io KNOXIS_USER_ID=your-uuid node ${path.basename(__filename)}`);
+    console.log('');
+  }
+
+  if (!serverMeta.secure) {
+    console.warn('╔══════════════════════════════════════════════════════════════╗');
+    console.warn('║  ⚠️  WARNING: Running in HTTP mode (no TLS certificates)     ║');
+    console.warn('║  Browsers will block requests from HTTPS sites (like qig.ai) ║');
+    console.warn('╚══════════════════════════════════════════════════════════════╝');
+    console.warn('');
+    console.warn('To fix this, either:');
+    console.warn(`  1. Install OpenSSL and restart (auto-generates certs)`);
+    console.warn(`  2. Manually place certs in: ${CERT_DIR}`);
+    console.warn('');
+  } else {
+    console.log('✅ HTTPS enabled - ready for secure connections from deployed frontends');
+    console.log('');
+  }
+});