venombrowser 4.1.1 → 4.1.2

package/bin/venombrowser-cli.js

@@ -37,6 +37,8 @@ Commands:
   setup           Run the interactive setup wizard
   start           Start the bridge daemon
   status          Check daemon & extension connection status
+  stop            Stop the bridge daemon (releases port)
+  restart         Restart the bridge daemon
   connect         Auto-register MCP server with known agents
   uninstall       Remove MCP entries, stop daemon (does NOT npm uninstall)
   agent "<task>"  Run a one-shot browser automation task
@@ -153,6 +155,35 @@ function runChat() {
   child.on('exit', (code) => process.exit(code || 0));
 }
 
+function runStop() {
+  const { BrowserBridge } = require('../src/bridge-client');
+  const bridge = new BrowserBridge({ port: BRIDGE_PORT, session: 'cli', apiKey: process.env.REST_API_KEY });
+  bridge.stopServer()
+    .then(() => console.log('✅ Sent stop signal to bridge daemon. It will shut down gracefully.'))
+    .catch(err => {
+      if (err.message.includes('fetch failed') || err.message.includes('ECONNREFUSED')) {
+        console.log('✅ Daemon is already stopped.');
+      } else {
+        console.error('❌ Failed to stop daemon:', err.message);
+      }
+    });
+}
+
+function runRestart() {
+  console.log('🔄 Restarting VenomBrowser daemon...');
+  const { BrowserBridge } = require('../src/bridge-client');
+  const bridge = new BrowserBridge({ port: BRIDGE_PORT, session: 'cli', apiKey: process.env.REST_API_KEY });
+  bridge.stopServer()
+    .then(() => {
+      console.log('✅ Daemon stopped.');
+      setTimeout(() => runStart(), 1000);
+    })
+    .catch(err => {
+      console.log('✅ Daemon was not running.');
+      runStart();
+    });
+}
+
 // ─── Dispatch ───────────────────────────────────────────────────────────────
 
 const command = process.argv[2];
@@ -167,6 +198,12 @@ switch (command) {
   case 'status':
     runStatus();
     break;
+  case 'stop':
+    runStop();
+    break;
+  case 'restart':
+    runRestart();
+    break;
   case 'connect':
     runConnect();
     break;

package/bin/venombrowser-mcp.js

@@ -136,9 +136,14 @@ async function main() {
   // Step 1: Ensure the bridge daemon is running (Kimi-style auto-start)
   await ensureBridgeRunning();
 
-  // Step 2: Start the MCP server (stdio transport for agent communication)
   const VenomBrowserMcpServer = require('../src/mcp-server');
-  const server = new VenomBrowserMcpServer();
+  const server = new VenomBrowserMcpServer({
+    onBeforeCommand: async (toolName) => {
+      // Don't auto-start if the agent is explicitly trying to stop the server
+      if (toolName === 'stop_server') return;
+      await ensureBridgeRunning();
+    }
+  });
   await server.start();
 }
 

package/bin/venombrowser-setup.js

@@ -1,183 +1,145 @@
 #!/usr/bin/env node
-/**
- * VenomBrowser Setup — Interactive setup wizard
- *
- * Helps users (and agents) configure VenomBrowser by:
- * 1. Creating/updating .env from .env.example
- * 2. Generating a REST_API_KEY if missing
- * 3. Prompting for WS_AUTH_TOKEN (from extension popup)
- * 4. Configuring the LLM provider
- *
- * Usage:
- *   node bin/venombrowser-setup.js
- *   node bin/venombrowser-setup.js --auto          # Non-interactive: generate keys, use defaults
- *   node bin/venombrowser-setup.js --token=<tok>   # Set the WS_AUTH_TOKEN directly
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const readline = require('readline');
-
-const ENV_PATH = path.join(__dirname, '..', '.env');
-const EXAMPLE_PATH = path.join(__dirname, '..', '.env.example');
-
-function generateKey(length = 32) {
-  return crypto.randomBytes(length).toString('hex');
-}
-
-function parseEnv(content) {
-  const vars = {};
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const eqIndex = trimmed.indexOf('=');
-    if (eqIndex === -1) continue;
-    const key = trimmed.slice(0, eqIndex).trim();
-    const val = trimmed.slice(eqIndex + 1).trim();
-    vars[key] = val;
-  }
-  return vars;
-}
-
-function updateEnvFile(updates) {
-  let content;
-  if (fs.existsSync(ENV_PATH)) {
-    content = fs.readFileSync(ENV_PATH, 'utf8');
-  } else if (fs.existsSync(EXAMPLE_PATH)) {
-    content = fs.readFileSync(EXAMPLE_PATH, 'utf8');
-  } else {
-    // Build minimal .env
-    content = Object.entries(updates).map(([k, v]) => `${k}=${v}`).join('\n') + '\n';
-    fs.writeFileSync(ENV_PATH, content);
-    return;
-  }
-
-  for (const [key, value] of Object.entries(updates)) {
-    // Replace existing key= lines, or append
-    const regex = new RegExp(`^${key}=.*$`, 'm');
-    if (regex.test(content)) {
-      content = content.replace(regex, `${key}=${value}`);
-    } else {
-      content += `\n${key}=${value}\n`;
-    }
-  }
-
-  fs.writeFileSync(ENV_PATH, content);
-}
-
-function ask(rl, question) {
-  return new Promise(resolve => rl.question(question, resolve));
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const isAuto = args.includes('--auto');
-  const tokenArg = args.find(a => a.startsWith('--token='));
-  const tokenValue = tokenArg ? tokenArg.split('=').slice(1).join('=') : null;
-
-  console.log('🕷️ VenomBrowser Bridge Setup');
-  console.log('═'.repeat(50));
-
-  // Load existing env
-  let existing = {};
-  if (fs.existsSync(ENV_PATH)) {
-    existing = parseEnv(fs.readFileSync(ENV_PATH, 'utf8'));
-    console.log('📄 Found existing .env file');
-  } else {
-    console.log('📄 No .env file found — will create one');
-  }
-
-  const updates = {};
-
-  // ── REST_API_KEY ─────────────────────────────────────────────────────────
-  if (!existing.REST_API_KEY || existing.REST_API_KEY.includes('pick-any') || existing.REST_API_KEY.includes('your')) {
-    const key = generateKey();
-    updates.REST_API_KEY = key;
-    console.log(`🔑 Generated REST_API_KEY: ${key}`);
-  } else {
-    console.log(`🔑 REST_API_KEY: ${existing.REST_API_KEY.slice(0, 8)}...`);
-  }
-
-  // ── WS_AUTH_TOKEN ────────────────────────────────────────────────────────
-  if (tokenValue) {
-    updates.WS_AUTH_TOKEN = tokenValue;
-    console.log(`🔐 WS_AUTH_TOKEN set from --token flag`);
-  } else if (isAuto) {
-    if (!existing.WS_AUTH_TOKEN || existing.WS_AUTH_TOKEN.includes('paste')) {
-      console.log('⚠️  WS_AUTH_TOKEN not set. After loading the extension, run:');
-      console.log('   node bin/venombrowser-setup.js --token=<paste-token-from-extension-popup>');
-    }
-  } else {
-    // Interactive
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-    if (!existing.WS_AUTH_TOKEN || existing.WS_AUTH_TOKEN.includes('paste')) {
-      console.log();
-      console.log('📋 To get your WS_AUTH_TOKEN:');
-      console.log('   1. Load the extension/ folder in chrome://extensions/');
-      console.log('   2. Click the VenomBrowser Bridge icon in your toolbar');
-      console.log('   3. Click the auth token to copy it');
-      console.log();
-      const token = await ask(rl, '🔐 Paste your Auth Token (or press Enter to skip): ');
-      if (token.trim()) {
-        updates.WS_AUTH_TOKEN = token.trim();
-        console.log('✅ WS_AUTH_TOKEN saved!');
-      } else {
-        console.log('⏭️  Skipped — you can set it later with: node bin/venombrowser-setup.js --token=<token>');
-      }
-    } else {
-      console.log(`🔐 WS_AUTH_TOKEN: ${existing.WS_AUTH_TOKEN.slice(0, 8)}...`);
-    }
-
-    rl.close();
-  }
-
-  // ── Save ──────────────────────────────────────────────────────────────────
-  if (Object.keys(updates).length > 0) {
-    updateEnvFile(updates);
-    console.log();
-    console.log('💾 Configuration saved to server/.env');
-  } else {
-    console.log();
-    console.log('✅ Configuration is already up to date');
-  }
-
-  // ── Final summary ─────────────────────────────────────────────────────────
-  const final = { ...existing, ...updates };
-  console.log();
-  console.log('🚀 Next steps:');
-  if (!final.WS_AUTH_TOKEN || final.WS_AUTH_TOKEN.includes('paste')) {
-    console.log('   1. Set your WS_AUTH_TOKEN (see instructions above)');
-    console.log('   2. Start using your AI agent (the bridge daemon will auto-start)');
-  } else {
-    console.log('   1. Start using your AI agent (the bridge daemon will auto-start)');
-  }
-  console.log('   2. venombrowser chat      — start interactive chat');
-  console.log('   3. venombrowser agent "task" — run a one-shot task');
-  console.log();
-
-  // ── Auto-register with agents ────────────────────────────────────────────
-  try {
-    const { connect } = require('../src/connect');
-    connect();
-  } catch (err) {
-    console.log('ℹ️  Auto-registration skipped:', err.message);
-    // Still print manual instructions as fallback
-    const absPath = path.resolve(__dirname, 'venombrowser-mcp.js').replace(/\\/g, '/');
-    console.log('🔌 To connect Claude Code or other MCP agents, add this to your MCP config:');
-    console.log(JSON.stringify({
-      "venombrowser": {
-        command: "node",
-        args: [absPath],
-        env: {
-          REST_API_KEY: final.REST_API_KEY || updates.REST_API_KEY || 'your-key'
-        }
-      }
-    }, null, 2));
-    console.log();
-  }
-}
-
-main().catch(console.error);
-
+/**
+ * VenomBrowser Setup — Interactive setup wizard
+ *
+ * Helps users (and agents) configure VenomBrowser by:
+ * 1. Creating/updating .env from .env.example
+ * 2. Configuring the LLM provider (optional)
+ *
+ * Usage:
+ *   node bin/venombrowser-setup.js
+ *   node bin/venombrowser-setup.js --auto          # Non-interactive: use defaults
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const ENV_PATH = path.join(__dirname, '..', '.env');
+const EXAMPLE_PATH = path.join(__dirname, '..', '.env.example');
+
+function parseEnv(content) {
+  const vars = {};
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    const val = trimmed.slice(eqIndex + 1).trim();
+    vars[key] = val;
+  }
+  return vars;
+}
+
+function updateEnvFile(updates) {
+  let content;
+  if (fs.existsSync(ENV_PATH)) {
+    content = fs.readFileSync(ENV_PATH, 'utf8');
+  } else if (fs.existsSync(EXAMPLE_PATH)) {
+    content = fs.readFileSync(EXAMPLE_PATH, 'utf8');
+  } else {
+    // Build minimal .env
+    content = Object.entries(updates).map(([k, v]) => `${k}=${v}`).join('\n') + '\n';
+    fs.writeFileSync(ENV_PATH, content);
+    return;
+  }
+
+  for (const [key, value] of Object.entries(updates)) {
+    // Replace existing key= lines, or append
+    const regex = new RegExp(`^${key}=.*$`, 'm');
+    if (regex.test(content)) {
+      content = content.replace(regex, `${key}=${value}`);
+    } else {
+      content += `\n${key}=${value}\n`;
+    }
+  }
+
+  fs.writeFileSync(ENV_PATH, content);
+}
+
+function ask(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+async function main() {
+  console.log('🕷️ VenomBrowser Bridge Setup');
+  console.log('═'.repeat(50));
+
+  // Load existing env
+  let existing = {};
+  if (fs.existsSync(ENV_PATH)) {
+    existing = parseEnv(fs.readFileSync(ENV_PATH, 'utf8'));
+    console.log('📄 Found existing .env file');
+  } else {
+    console.log('📄 No .env file found — will create one');
+  }
+
+  const crypto = require('crypto');
+  const updates = {};
+  
+  // ── Auto-generate security tokens if missing ──────────────────────────────
+  if (!existing.REST_API_KEY) {
+    updates.REST_API_KEY = crypto.randomBytes(32).toString('hex');
+    console.log('🔑 Generated new REST_API_KEY');
+  }
+  if (!existing.WS_AUTH_TOKEN) {
+    updates.WS_AUTH_TOKEN = crypto.randomUUID();
+    console.log('🔑 Generated new WS_AUTH_TOKEN');
+  }
+  
+  const finalWsToken = updates.WS_AUTH_TOKEN || existing.WS_AUTH_TOKEN;
+
+  // ── Inject token into extension ───────────────────────────────────────────
+  const bgPath = path.join(__dirname, '..', '..', 'extension', 'background.js');
+  if (fs.existsSync(bgPath)) {
+    let bgContent = fs.readFileSync(bgPath, 'utf8');
+    // Look for INJECTED_TOKEN = '__WS_AUTH_TOKEN__' or an already injected token
+    bgContent = bgContent.replace(/const INJECTED_TOKEN = '.*?';/, `const INJECTED_TOKEN = '${finalWsToken}';`);
+    fs.writeFileSync(bgPath, bgContent);
+    console.log('💉 Injected WS_AUTH_TOKEN into extension/background.js');
+  }
+
+  // ── Save ──────────────────────────────────────────────────────────────────
+  if (Object.keys(updates).length > 0) {
+    updateEnvFile(updates);
+    console.log();
+    console.log('💾 Configuration saved to server/.env');
+  } else {
+    console.log();
+    console.log('✅ Configuration is already up to date');
+  }
+
+  // ── Final summary ─────────────────────────────────────────────────────────
+  console.log();
+  console.log('🚀 Next steps:');
+  console.log('   1. IMPORTANT: Go to chrome://extensions and click the "Reload" icon on the VenomBrowser extension');
+  console.log('      (This is required to apply the newly generated security token)');
+  console.log('   2. Start using your AI agent (the bridge daemon will auto-start)');
+  console.log('   3. venombrowser chat      — start interactive chat');
+  console.log('   4. venombrowser agent "task" — run a one-shot task');
+  console.log();
+
+  // ── Auto-register with agents ────────────────────────────────────────────
+  try {
+    const { connect } = require('../src/connect');
+    connect();
+  } catch (err) {
+    console.log('ℹ️  Auto-registration skipped:', err.message);
+    // Still print manual instructions as fallback
+    const absPath = path.resolve(__dirname, 'venombrowser-mcp.js').replace(/\\/g, '/');
+    console.log('🔌 To connect Claude Code or other MCP agents, add this to your MCP config:');
+    console.log(JSON.stringify({
+      "venombrowser": {
+        command: "node",
+        args: [absPath],
+        env: {
+          BRIDGE_PORT: "10086"
+        }
+      }
+    }, null, 2));
+    console.log();
+  }
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "venombrowser",
-  "version": "4.1.1",
+  "version": "4.1.2",
   "description": "Agent-agnostic browser automation platform — give any AI agent eyes and hands in your real Chrome browser",
   "author": "TechVenom",
   "main": "src/bridge-server.js",

package/src/bridge-client.js

@@ -18,22 +18,29 @@ class BridgeTimeoutError extends BridgeError {}
 class BridgeCommandError extends BridgeError {}
 
 class BrowserBridge {
-  constructor({ host = '127.0.0.1', port = 10086, session = 'default' } = {}) {
+  constructor({ host = '127.0.0.1', port = 10086, session = 'default', apiKey } = {}) {
+    if (!apiKey) {
+      throw new Error('apiKey is required to connect to the VenomBrowser bridge.');
+    }
     this.baseUrl = `http://${host}:${port}`;
     this.session = session;
     this.http = axios.create({
       baseURL: this.baseUrl,
-      timeout: 60000
+      timeout: 60000,
+      headers: {
+        'x-bridge-key': apiKey
+      }
     });
   }
 
   // ─── Core command method ─────────────────────────────────────────────────
-  async command(action, args = {}, timeout = 30000) {
+  async command(action, args = {}, timeout = 30000, extra = {}) {
     try {
       const response = await this.http.post('/command', {
         action,
         args,
-        session: this.session
+        session: this.session,
+        ...extra
       }, { timeout });
       return response.data;
     } catch (e) {
@@ -73,7 +80,19 @@ class BrowserBridge {
   }
 
   async closeSession() {
-    return this.command('close_session');
+    return this.command('close_session', {}, 30000, { confirm: true });
+  }
+
+  async stopServer() {
+    return this.command('stop_server', {}, 5000, { confirm: true });
+  }
+
+  async restartServer() {
+    return this.command('restart_server', {}, 5000, { confirm: true });
+  }
+
+  async bridgeStatus() {
+    return this.command('status');
   }
 
   // ─── Content interaction (Kimi-style) ────────────────────────────────────
@@ -130,6 +149,47 @@ class BrowserBridge {
     return this.command('scroll', { direction, amount });
   }
 
+  // ─── Phase 1: Cheap Wins ─────────────────────────────────────────────────
+  async scrollTo(selector) {
+    return this.command('scroll_to', { selector });
+  }
+
+  async checkVisibility(selector) {
+    return this.command('check_visibility', { selector });
+  }
+
+  async checkStale(selector) {
+    return this.command('check_stale', { selector });
+  }
+
+  async doubleClick(selector) {
+    return this.command('double_click', { selector });
+  }
+
+  async rightClick(selector) {
+    return this.command('right_click', { selector });
+  }
+
+  async keyboard(key, { modifiers = [] } = {}) {
+    return this.command('keyboard', { key, modifiers });
+  }
+
+  async goBack() {
+    return this.command('go_back');
+  }
+
+  async goForward() {
+    return this.command('go_forward');
+  }
+
+  async manageCookies(cmd, { name, value, domain } = {}) {
+    return this.command('manage_cookies', { cmd, name, value, domain });
+  }
+
+  async manageStorage(cmd, { storageType = 'local', key, value } = {}) {
+    return this.command('manage_storage', { cmd, storage_type: storageType, key, value });
+  }
+
   // ─── Legacy compatibility (maps old names to new) ─────────────────────────
   async extract(selector = null) {
     const r = await this.evaluate(`

package/src/bridge-server.js

@@ -16,13 +16,37 @@ const fs = require('fs');
 const path = require('path');
 const WebSocket = require('ws');
 const { v4: uuidv4 } = require('uuid');
+const crypto = require('crypto');
 
 const PORT = parseInt(process.env.BRIDGE_PORT || '10086', 10);
 const WS_PORT = parseInt(process.env.WS_PORT || String(PORT + 1), 10);
+const WS_AUTH_TOKEN = process.env.WS_AUTH_TOKEN;
+const REST_API_KEY = process.env.REST_API_KEY;
+const CORS_ORIGIN = process.env.CORS_ORIGIN;
+
+if (!WS_AUTH_TOKEN || !REST_API_KEY) {
+  console.error('[Bridge] FATAL: WS_AUTH_TOKEN and REST_API_KEY must be set in the environment.');
+  process.exit(1);
+}
+
 const WS_PING_INTERVAL = 15000;
 const WS_PING_TIMEOUT = 10000;
 const CMD_TIMEOUT = 30000;
+const IDLE_TIMEOUT = 15 * 60 * 1000; // 15 minutes of inactivity shuts down the daemon
 const SCREENSHOT_DIR = path.join(__dirname, '..', '..', 'screenshots');
+const LOG_DIR = path.join(__dirname, '..', 'logs');
+
+if (!fs.existsSync(LOG_DIR)) {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+
+function safeCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const aBuf = Buffer.from(a);
+  const bBuf = Buffer.from(b);
+  if (aBuf.length !== bBuf.length) return false;
+  return crypto.timingSafeEqual(aBuf, bBuf);
+}
 
 class VenomBrowserBridgeServer {
   constructor() {
@@ -37,13 +61,57 @@ class VenomBrowserBridgeServer {
     this.currentTab = null;
     this.pingTimer = null;
     this.lastPong = Date.now();
+    this.idleTimer = null;
+
+    this.lastRestActivity = Date.now();
+    this.EXTENSION_IDLE_TIMEOUT = parseInt(process.env.EXTENSION_IDLE_TIMEOUT || String(120 * 1000), 10);
+    this.DAEMON_IDLE_TIMEOUT = parseInt(process.env.DAEMON_IDLE_TIMEOUT || String(30 * 60 * 1000), 10);
+
+    // Setup uncaught exception handlers
+    process.on('uncaughtException', (err) => {
+      console.error('[Bridge] UNCAUGHT EXCEPTION:', err);
+    });
 
+    process.on('unhandledRejection', (reason, promise) => {
+      console.error('[Bridge] UNHANDLED REJECTION:', reason);
+    });
+  }
+
+  start() {
+    console.log(`\n🚀 Starting VenomBrowser Bridge Server v4.1.0...`);
     this.startHTTP();
     this.startWS();
     this.startPingLoop();
+    this.startIdleMonitor();
+  }
+
+  startIdleMonitor() {
+    setInterval(() => {
+      const now = Date.now();
+      const idleTime = now - this.lastRestActivity;
+
+      // 1. If idle longer than DAEMON_IDLE_TIMEOUT, shut down completely
+      if (idleTime > this.DAEMON_IDLE_TIMEOUT) {
+        console.log(`[Bridge] Daemon idle for > ${this.DAEMON_IDLE_TIMEOUT}ms. Shutting down.`);
+        process.exit(0);
+      }
+
+      // 2. If idle longer than EXTENSION_IDLE_TIMEOUT, disconnect extension
+      if (idleTime > this.EXTENSION_IDLE_TIMEOUT && this.extensionWs && this.extensionWs.readyState === WebSocket.OPEN) {
+        console.log(`[Bridge] No REST activity for > ${this.EXTENSION_IDLE_TIMEOUT}ms. Disconnecting extension.`);
+        this.safeSend(this.extensionWs, { type: 'idle_disconnect' });
+        
+        // Wait a tiny bit for message to send before closing
+        setTimeout(() => {
+          if (this.extensionWs) {
+            this.extensionWs.close(1000, 'Idle Disconnect');
+          }
+        }, 100);
+      }
+    }, 10000); // Check every 10 seconds
   }
 
-  // ─── Safe WebSocket send ─────────────────────────────────────────────────
+  // ─── HTTP Server ─────────────────────────────────────────────────────────
   safeSend(ws, data) {
     try {
       if (ws && ws.readyState === WebSocket.OPEN) {
@@ -59,9 +127,16 @@ class VenomBrowserBridgeServer {
   // ─── HTTP Server ─────────────────────────────────────────────────────────
   startHTTP() {
     this.httpServer = http.createServer((req, res) => {
-      res.setHeader('Access-Control-Allow-Origin', '*');
-      res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
-      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+      // CORS handling
+      if (CORS_ORIGIN && CORS_ORIGIN !== '*') {
+        if (req.headers.origin === CORS_ORIGIN) {
+          res.setHeader('Access-Control-Allow-Origin', CORS_ORIGIN);
+          res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+          res.setHeader('Access-Control-Allow-Headers', 'Content-Type, x-bridge-key');
+        }
+      } else {
+        // No CORS by default. Only allow localhost processes.
+      }
 
       if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
 
@@ -80,6 +155,12 @@ class VenomBrowserBridgeServer {
         });
       }
 
+      // API Key Auth for all other endpoints
+      const apiKey = req.headers['x-bridge-key'];
+      if (!safeCompare(apiKey, REST_API_KEY)) {
+        return send(401, { success: false, error: 'Unauthorized: Invalid x-bridge-key' });
+      }
+
       if (req.method === 'GET' && req.url === '/status') {
         return send(200, {
           success: true,
@@ -139,10 +220,19 @@ class VenomBrowserBridgeServer {
 
     if (!action) throw new Error('action is required');
 
+    const destructiveActions = ['upload', 'close_session', 'stop_server', 'restart_server'];
+    const destructiveArgs = ['delete', 'clear'];
+    if (destructiveActions.includes(action) || (['manage_cookies', 'manage_storage'].includes(action) && destructiveArgs.includes(args.cmd))) {
+      if (request.confirm !== true) {
+        throw new Error(`Confirmation required: The action '${action}' is destructive. You must include "confirm": true in your request to proceed.`);
+      }
+    }
+
     if (!this.sessions.has(session)) {
       this.sessions.set(session, { tabs: new Set(), startTime: Date.now(), commandCount: 0 });
     }
     this.sessions.get(session).commandCount++;
+    this.lastRestActivity = Date.now();
 
     if (action === 'health') return { service: 'venombrowser-bridge' };
 
@@ -156,8 +246,6 @@ class VenomBrowserBridgeServer {
       };
     }
 
-    if (!this.isConnected()) throw new Error('Extension not connected');
-
     return this.executeAction(action, args, session, tabId);
   }
 
@@ -218,6 +306,19 @@ class VenomBrowserBridgeServer {
         return { closed };
       }
 
+      case 'stop_server': {
+        console.log('[Bridge] Received stop_server command from agent/CLI. Shutting down gracefully.');
+        setTimeout(() => this.shutdown(), 100);
+        return { success: true, message: 'Server is shutting down.' };
+      }
+
+      case 'restart_server': {
+        console.log('[Bridge] Received restart_server command. Shutting down for restart...');
+        // The MCP server / agent will auto-spawn a new daemon on next command
+        setTimeout(() => this.shutdown(), 100);
+        return { success: true, message: 'Server is restarting. Next command will auto-spawn a new daemon.' };
+      }
+
       case 'snapshot': {
         const r = await send('SNAPSHOT', {}, tabId || this.currentTab);
         const res = r.result || {};
@@ -245,12 +346,18 @@ class VenomBrowserBridgeServer {
       }
 
       case 'evaluate': {
-        const r = await send('EVALUATE', { code: args.code }, tabId || this.currentTab, 30000);
+        const code = args.code;
+        fs.appendFileSync(path.join(LOG_DIR, 'audit.log'), `[${new Date().toISOString()}] evaluate: ${code}\n`);
+        const r = await send('EVALUATE', { code }, tabId || this.currentTab, 30000);
         return { type: r.result?.type, value: r.result?.result };
       }
 
       case 'cdp': {
-        const r = await send('CDP', { method: args.method, params: args.params }, tabId || this.currentTab, 30000);
+        const { method, params = {} } = args;
+        if (method === 'Runtime.evaluate' || method === 'Runtime.evaluateOnNewDocument') {
+          fs.appendFileSync(path.join(LOG_DIR, 'audit.log'), `[${new Date().toISOString()}] CDP ${method}: ${JSON.stringify(params)}\n`);
+        }
+        const r = await send('CDP', { method, params }, tabId || this.currentTab, 30000);
         return r.result;
       }
 
@@ -294,6 +401,57 @@ class VenomBrowserBridgeServer {
         return r.result;
       }
 
+      // ── Phase 1: Cheap Wins ──
+      case 'scroll_to': {
+        const r = await send('SCROLL_TO', { selector: args.selector }, tabId || this.currentTab);
+        return r.result;
+      }
+
+      case 'check_visibility': {
+        const r = await send('CHECK_VISIBILITY', { selector: args.selector }, tabId || this.currentTab);
+        return r.result;
+      }
+
+      case 'check_stale': {
+        const r = await send('CHECK_STALE', { selector: args.selector }, tabId || this.currentTab);
+        return r.result;
+      }
+
+      case 'double_click': {
+        const r = await send('DOUBLE_CLICK', { selector: args.selector }, tabId || this.currentTab);
+        return { success: true, tag: r.result?.tag, text: r.result?.text };
+      }
+
+      case 'right_click': {
+        const r = await send('RIGHT_CLICK', { selector: args.selector }, tabId || this.currentTab);
+        return { success: true, tag: r.result?.tag, text: r.result?.text };
+      }
+
+      case 'keyboard': {
+        const r = await send('KEYBOARD', { key: args.key, modifiers: args.modifiers || [] }, tabId || this.currentTab);
+        return r.result;
+      }
+
+      case 'go_back': {
+        const r = await send('GO_BACK', {}, tabId || this.currentTab);
+        return r.result;
+      }
+
+      case 'go_forward': {
+        const r = await send('GO_FORWARD', {}, tabId || this.currentTab);
+        return r.result;
+      }
+
+      case 'manage_cookies': {
+        const r = await send('COOKIES', { cmd: args.cmd, name: args.name, value: args.value, domain: args.domain }, tabId || this.currentTab);
+        return r.result;
+      }
+
+      case 'manage_storage': {
+        const r = await send('STORAGE', { cmd: args.cmd, storageType: args.storage_type || args.storageType || 'local', key: args.key, value: args.value }, tabId || this.currentTab);
+        return r.result;
+      }
+
       default:
         throw new Error(`Unknown action: ${action}`);
     }
@@ -301,8 +459,8 @@ class VenomBrowserBridgeServer {
 
   // ─── WebSocket server ────────────────────────────────────────────────────
   startWS() {
-    this.wss = new WebSocket.Server({ port: WS_PORT }, () => {
-      console.log(`[Bridge] WebSocket on ws://localhost:${WS_PORT}`);
+    this.wss = new WebSocket.Server({ host: '127.0.0.1', port: WS_PORT }, () => {
+      console.log(`[Bridge] WebSocket on ws://127.0.0.1:${WS_PORT}`);
     });
 
     this.wss.on('error', (e) => {
@@ -316,6 +474,16 @@ class VenomBrowserBridgeServer {
       const addr = req.socket.remoteAddress || 'unknown';
       console.log(`[Bridge] Extension connected from ${addr}`);
 
+      // Handshake timeout
+      ws.authTimeout = setTimeout(() => {
+        if (!ws.authenticated) {
+          console.log('[Bridge] Extension handshake timed out.');
+          ws.close(4001, 'Auth timeout');
+        }
+      }, 5000);
+
+      ws.authenticated = false;
+
       // Replace previous connection
       if (this.extensionWs && this.extensionWs.readyState === WebSocket.OPEN) {
         console.log('[Bridge] Replacing previous extension');
@@ -364,9 +532,19 @@ class VenomBrowserBridgeServer {
     }
     if (msg.type === 'hello') {
       console.log(`[Bridge] Extension handshake: ${msg.client} v${msg.version}`);
+      if (safeCompare(msg.token, WS_AUTH_TOKEN)) {
+        ws.authenticated = true;
+        clearTimeout(ws.authTimeout);
+        this.safeSend(ws, { type: 'auth_ok' });
+      } else {
+        this.safeSend(ws, { type: 'auth_fail' });
+        setTimeout(() => ws.close(4001, 'Unauthorized'), 100);
+      }
       return;
     }
 
+    if (!ws.authenticated) return; // Drop messages from unauthenticated sockets
+
     // Command response
     if (msg.id && this.pending.has(msg.id)) {
       const entry = this.pending.get(msg.id);
@@ -400,9 +578,14 @@ class VenomBrowserBridgeServer {
   }
 
   // ─── Send command to extension ───────────────────────────────────────────
-  sendToExtension(command, params = {}, tabId = null, timeoutMs = CMD_TIMEOUT) {
-    if (!this.isConnected()) {
-      return Promise.reject(new Error('Extension not connected'));
+  async sendToExtension(command, params = {}, tabId = null, timeoutMs = CMD_TIMEOUT) {
+    if (!this.isConnected() || !this.extensionWs.authenticated) {
+      console.log(`[Bridge] Extension not ready. Waiting for reconnection (max 10s)...`);
+      try {
+        await this.waitForConnection(10000);
+      } catch (err) {
+        throw err;
+      }
     }
 
     const id = uuidv4();
@@ -425,6 +608,25 @@ class VenomBrowserBridgeServer {
     });
   }
 
+  waitForConnection(timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (this.isConnected() && this.extensionWs.authenticated) return resolve();
+      
+      const checkInterval = setInterval(() => {
+        if (this.isConnected() && this.extensionWs.authenticated) {
+          clearInterval(checkInterval);
+          clearTimeout(timeoutTimer);
+          resolve();
+        }
+      }, 500);
+
+      const timeoutTimer = setTimeout(() => {
+        clearInterval(checkInterval);
+        reject(new Error('Timed out waiting for extension to connect'));
+      }, timeoutMs);
+    });
+  }
+
   rejectAll(reason) {
     for (const { reject, timer } of this.pending.values()) {
       clearTimeout(timer);
@@ -466,6 +668,7 @@ process.on('unhandledRejection', (reason) => {
 // ─── Start ────────────────────────────────────────────────────────────────
 console.log('🚀 Starting VenomBrowser Bridge Server v4.1.0...');
 const server = new VenomBrowserBridgeServer();
+server.start();
 console.log(`📡 WebSocket : ws://localhost:${WS_PORT}`);
 console.log(`🌐 HTTP API  : http://127.0.0.1:${PORT}/command`);
 console.log(`📋 Status    : http://127.0.0.1:${PORT}/status`);

package/src/connect.js

@@ -185,9 +185,17 @@ function connect() {
   const registered = [];
 
   for (const { name, path: configPath, format } of configs) {
+    // If the file doesn't exist, create it so we can auto-configure
     if (!fs.existsSync(configPath)) {
-      console.log(`   ⏭️  ${name}: config not found, skipping`);
-      continue;
+      try {
+        const dir = path.dirname(configPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(configPath, '{}', 'utf8');
+        console.log(`   ✨ ${name}: created missing config file`);
+      } catch (err) {
+        console.log(`   ⏭️  ${name}: could not create config (${err.message})`);
+        continue;
+      }
     }
 
     const result = format === 'mcp'

package/src/mcp-server.js

@@ -20,12 +20,15 @@ const { BrowserBridge } = require('./bridge-client');
 const { getMcpToolDefinitions, executeTool } = require('./tools/browser-tools');
 
 class VenomBrowserMcpServer {
-  constructor() {
+  constructor(options = {}) {
+    this.onBeforeCommand = options.onBeforeCommand || null;
     const host = process.env.BRIDGE_HOST || '127.0.0.1';
     const port = parseInt(process.env.BRIDGE_PORT || '10086', 10);
     const session = process.env.BRIDGE_SESSION || 'mcp-session';
 
-    this.bridge = new BrowserBridge({ host, port, session });
+    const apiKey = process.env.REST_API_KEY;
+
+    this.bridge = new BrowserBridge({ host, port, session, apiKey });
 
     this.server = new Server(
       { name: 'venombrowser', version: '4.0.0' },
@@ -45,6 +48,10 @@ class VenomBrowserMcpServer {
       const { name, arguments: args } = request.params;
 
       try {
+        if (this.onBeforeCommand) {
+          await this.onBeforeCommand(name);
+        }
+
         const result = await executeTool(this.bridge, name, args || {});
 
         // Special handling for screenshots — return as MCP image content

package/src/tools/browser-tools.js

@@ -188,8 +188,9 @@ const TOOL_DEFINITIONS = [
       parameters: {
         type: 'object',
         properties: {
-          selector: { type: 'string', description: 'CSS selector of the file input' },
-          files: { type: 'array', items: { type: 'string' }, description: 'File paths to upload' }
+          selector: { type: 'string', description: '@e ref or CSS selector' },
+          files: { type: 'array', items: { type: 'string' }, description: 'Absolute paths to files' },
+          confirm: { type: 'boolean', description: 'Required: set to true to confirm this action' }
         },
         required: ['selector', 'files']
       }
@@ -233,8 +234,188 @@ const TOOL_DEFINITIONS = [
     function: {
       name: 'close_session',
       description: 'Close all tabs in the session.',
+      parameters: {
+        type: 'object',
+        properties: {
+          confirm: { type: 'boolean', description: 'Required: set to true to confirm closing all tabs' }
+        }
+      }
+    }
+  },
+  // ── Phase 1: Cheap Wins ──
+  {
+    type: 'function',
+    function: {
+      name: 'scroll_to',
+      description: 'Scroll an element into view. Use before clicking elements that may be off-screen.',
+      parameters: {
+        type: 'object',
+        properties: {
+          selector: { type: 'string', description: '@e ref or CSS selector of element to scroll to' }
+        },
+        required: ['selector']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'check_visibility',
+      description: 'Check if an element is visible, in viewport, and not obscured by overlays (cookie banners, modals, etc).',
+      parameters: {
+        type: 'object',
+        properties: {
+          selector: { type: 'string', description: '@e ref or CSS selector' }
+        },
+        required: ['selector']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'check_stale',
+      description: 'Check if an @e ref from a previous snapshot is still valid (element still in DOM).',
+      parameters: {
+        type: 'object',
+        properties: {
+          selector: { type: 'string', description: '@e ref (e.g. "@e5")' }
+        },
+        required: ['selector']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'double_click',
+      description: 'Double-click an element. Useful for text selection or opening items.',
+      parameters: {
+        type: 'object',
+        properties: {
+          selector: { type: 'string', description: '@e ref or CSS selector' }
+        },
+        required: ['selector']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'right_click',
+      description: 'Right-click an element to trigger context menu.',
+      parameters: {
+        type: 'object',
+        properties: {
+          selector: { type: 'string', description: '@e ref or CSS selector' }
+        },
+        required: ['selector']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'keyboard',
+      description: 'Press a key or key combination. Uses real hardware-level key events via CDP. Examples: key="Enter", key="a" modifiers=["Control"] for Ctrl+A.',
+      parameters: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'Key name: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Space, F1-F12, or any letter/number.' },
+          modifiers: { type: 'array', items: { type: 'string', enum: ['Control', 'Alt', 'Shift', 'Meta'] }, description: 'Modifier keys to hold. Default none.' }
+        },
+        required: ['key']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'go_back',
+      description: 'Navigate back in browser history (like clicking the back button).',
       parameters: { type: 'object', properties: {} }
     }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'go_forward',
+      description: 'Navigate forward in browser history.',
+      parameters: { type: 'object', properties: {} }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'manage_cookies',
+      description: 'Read, set, or delete cookies for the current page domain.',
+      parameters: {
+        type: 'object',
+        properties: {
+          cmd: { type: 'string', enum: ['get', 'get_all', 'set', 'delete', 'clear'], description: 'Cookie operation' },
+          name: { type: 'string', description: 'Cookie name (required for get/set/delete)' },
+          value: { type: 'string', description: 'Cookie value (for set)' },
+          domain: { type: 'string', description: 'Cookie domain (optional, defaults to current domain)' },
+          confirm: { type: 'boolean', description: 'Required: true if cmd is delete or clear' }
+        },
+        required: ['cmd']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'manage_storage',
+      description: 'Read, set, or delete localStorage/sessionStorage entries for the current page.',
+      parameters: {
+        type: 'object',
+        properties: {
+          cmd: { type: 'string', enum: ['get', 'get_all', 'set', 'delete', 'clear', 'keys'], description: 'Storage operation' },
+          storage_type: { type: 'string', enum: ['local', 'session'], description: 'Which storage to use. Default "local".' },
+          key: { type: 'string', description: 'Storage key (required for get/set/delete)' },
+          value: { type: 'string', description: 'Value to store (for set). Objects will be JSON-stringified.' },
+          confirm: { type: 'boolean', description: 'Required: true if cmd is delete or clear' }
+        },
+        required: ['cmd']
+      }
+    }
+  },
+  // ── Lifecycle Management ──
+  {
+    type: 'function',
+    function: {
+      name: 'bridge_status',
+      description: 'Check the VenomBrowser bridge daemon status: whether the server is running, the extension is connected, uptime, and command count.',
+      parameters: { type: 'object', properties: {} }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'stop_server',
+      description: 'Stop the VenomBrowser bridge daemon completely. This releases the port and disconnects the extension. Use when you are completely done with browser automation and want to free resources.',
+      parameters: {
+        type: 'object',
+        properties: {
+          confirm: { type: 'boolean', description: 'Required: set to true to confirm stopping the server' }
+        },
+        required: ['confirm']
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'restart_server',
+      description: 'Restart the VenomBrowser bridge daemon. Use this to fix connection issues — the daemon will shut down and auto-restart on your next browser command.',
+      parameters: {
+        type: 'object',
+        properties: {
+          confirm: { type: 'boolean', description: 'Required: set to true to confirm restarting the server' }
+        },
+        required: ['confirm']
+      }
+    }
   }
 ];
 
@@ -340,6 +521,88 @@ async function executeTool(bridge, name, args = {}) {
       return { closed: r.closed };
     }
 
+    // ── Phase 1: Cheap Wins ──
+    case 'scroll_to': {
+      const r = await bridge.scrollTo(args.selector);
+      return r;
+    }
+
+    case 'check_visibility': {
+      const r = await bridge.checkVisibility(args.selector);
+      return r;
+    }
+
+    case 'check_stale': {
+      const r = await bridge.checkStale(args.selector);
+      return r;
+    }
+
+    case 'double_click': {
+      const r = await bridge.doubleClick(args.selector);
+      return { success: true, tag: r.tag, text: r.text };
+    }
+
+    case 'right_click': {
+      const r = await bridge.rightClick(args.selector);
+      return { success: true, tag: r.tag, text: r.text };
+    }
+
+    case 'keyboard': {
+      const r = await bridge.keyboard(args.key, { modifiers: args.modifiers });
+      return r;
+    }
+
+    case 'go_back': {
+      const r = await bridge.goBack();
+      return r;
+    }
+
+    case 'go_forward': {
+      const r = await bridge.goForward();
+      return r;
+    }
+
+    case 'manage_cookies': {
+      const r = await bridge.manageCookies(args.cmd, { name: args.name, value: args.value, domain: args.domain });
+      return r;
+    }
+
+    case 'manage_storage': {
+      const r = await bridge.manageStorage(args.cmd, { storageType: args.storage_type, key: args.key, value: args.value });
+      return r;
+    }
+
+    // ── Lifecycle Management ──
+    case 'bridge_status': {
+      const r = await bridge.bridgeStatus();
+      return r;
+    }
+
+    case 'stop_server': {
+      try {
+        const r = await bridge.stopServer();
+        return { success: true, message: r.message || 'Server is shutting down.' };
+      } catch (e) {
+        // Server may close connection before responding — that's expected
+        if (e.message?.includes('ECONNRESET') || e.message?.includes('ECONNREFUSED') || e.message?.includes('socket hang up')) {
+          return { success: true, message: 'Server has shut down.' };
+        }
+        throw e;
+      }
+    }
+
+    case 'restart_server': {
+      try {
+        const r = await bridge.restartServer();
+        return { success: true, message: r.message || 'Server is restarting. Your next browser command will auto-spawn a new daemon.' };
+      } catch (e) {
+        if (e.message?.includes('ECONNRESET') || e.message?.includes('ECONNREFUSED') || e.message?.includes('socket hang up')) {
+          return { success: true, message: 'Server has shut down for restart. Your next browser command will auto-spawn a new daemon.' };
+        }
+        throw e;
+      }
+    }
+
     default:
       throw new Error(`Unknown tool: ${name}`);
   }