browserforce 1.0.9 → 1.0.10

package/README.md

@@ -23,6 +23,20 @@ Works with [OpenClaw](https://github.com/openclaw/openclaw), Claude, or any MCP-
 | Agent support | Any MCP client | OpenClaw only | Any MCP client | Claude only | **Any MCP client** |
 | Playwright API | Partial | No | Full | No | **Full** |
 
+## Your Credentials Stay Yours
+
+Every other approach asks you to hand over something: an API key, an OAuth token, stored passwords, session cookies in a config file. BrowserForce asks for none of it.
+
+**Why?** Because you're already logged in. BrowserForce talks to your running Chrome — it doesn't extract credentials, store cookies, or replay tokens. The browser handles auth exactly as it always has. Your agent inherits your sessions the same way a new Chrome tab does.
+
+What you never need to provide:
+- No passwords
+- No API keys
+- No OAuth tokens
+- No session cookies in env vars or config files
+
+It's a security win *and* a setup win — there are no secrets to rotate, leak, or manage. Your logins live in Chrome. They stay in Chrome.
+
 ## Setup
 
 ### 1. Install
@@ -153,10 +167,76 @@ browserforce snapshot [n]       # Accessibility tree of tab n
 browserforce screenshot [n]     # Screenshot tab n (PNG to stdout)
 browserforce navigate <url>     # Open URL in a new tab
 browserforce -e "<code>"        # Run Playwright JavaScript (one-shot)
+browserforce plugin list        # List installed plugins
+browserforce plugin install <n> # Install a plugin from the registry
+browserforce plugin remove <n>  # Remove an installed plugin
 ```
 
 Each `-e` command is one-shot — state does not persist between calls. For persistent state, use the MCP server.
 
+## Plugins
+
+Plugins add custom helpers directly into the `execute` tool scope. Install once — your agent calls them like built-in functions.
+
+### Install a plugin
+
+```bash
+browserforce plugin install highlight
+```
+
+That's it. Restart MCP (or Claude Desktop) and `highlight()` is available in every `execute` call.
+
+### Official plugins
+
+| Plugin | What it adds | Install |
+|--------|-------------|---------|
+| `highlight` | `highlight(selector, color?)` — outlines matching elements; `clearHighlights()` — removes them | `browserforce plugin install highlight` |
+
+### Use an installed plugin
+
+After installing `highlight`, your agent can call it directly:
+
+```javascript
+// Outline all buttons in blue
+await highlight('button', 'blue');
+
+// Highlight the specific element you're about to click
+await highlight('[data-testid="submit"]', 'red');
+return await screenshotWithAccessibilityLabels();
+```
+
+The helper receives the active page, context, and state automatically — no plumbing needed.
+
+### Manage plugins
+
+```bash
+browserforce plugin list        # See what's installed
+browserforce plugin remove highlight   # Uninstall
+```
+
+Plugins are stored at `~/.browserforce/plugins/`. Each one is a folder with an `index.js`.
+
+### Write your own
+
+```javascript
+// ~/.browserforce/plugins/my-plugin/index.js
+export default {
+  name: 'my-plugin',
+  helpers: {
+    async scrollToBottom(page, ctx, state) {
+      await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+    },
+    async countLinks(page, ctx, state) {
+      return page.evaluate(() => document.querySelectorAll('a').length);
+    },
+  },
+};
+```
+
+Drop it in `~/.browserforce/plugins/my-plugin/`, restart MCP, and call `await scrollToBottom()` or `await countLinks()` from any `execute` call.
+
+Add a `SKILL.md` file alongside `index.js` and its content is automatically appended to the `execute` tool's description — so your agent knows the helpers exist without you having to explain them every time.
+
 ### Any Playwright Script
 
 ```javascript

package/bin.js

@@ -3,6 +3,7 @@
 
 import { parseArgs } from 'node:util';
 import http from 'node:http';
+import { checkForUpdate } from './mcp/src/update-check.js';
 
 const { values, positionals } = parseArgs({
   options: {
@@ -42,6 +43,32 @@ function httpGet(url) {
   });
 }
 
+function httpFetch(method, url, body, authToken) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const payload = body ? JSON.stringify(body) : undefined;
+    const req = http.request({
+      hostname: parsed.hostname, port: parsed.port,
+      path: parsed.pathname, method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}),
+        ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', (d) => (data += d));
+      res.on('end', () => {
+        try { resolve({ status: res.statusCode, body: JSON.parse(data) }); }
+        catch { resolve({ status: res.statusCode, body: data }); }
+      });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
 async function connectBrowser() {
   const { getCdpUrl, ensureRelay } = await import('./mcp/src/exec-engine.js');
   await ensureRelay();
@@ -215,6 +242,86 @@ async function cmdMcp() {
   await import('./mcp/src/index.js');
 }
 
+async function cmdPlugin() {
+  const sub = positionals[1];
+  if (!sub) {
+    console.error('Usage: browserforce plugin <list|install|remove> [name]');
+    process.exit(1);
+  }
+
+  const { getRelayHttpUrl } = await import('./mcp/src/exec-engine.js');
+  let baseUrl;
+  try { baseUrl = getRelayHttpUrl(); } catch { baseUrl = 'http://127.0.0.1:19222'; }
+
+  // Auth token for write endpoints — read from token file
+  const { readFileSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const { homedir } = await import('node:os');
+  const pluginsDir = process.env.BF_PLUGINS_DIR || join(homedir(), '.browserforce', 'plugins');
+  const tokenFile = join(homedir(), '.browserforce', 'auth-token');
+  let authToken = '';
+  try { authToken = readFileSync(tokenFile, 'utf8').trim(); } catch { /* no token file */ }
+
+  if (sub === 'list') {
+    const data = await httpGet(`${baseUrl}/plugins`);
+    if (values.json) {
+      output(data, true);
+    } else {
+      const list = (data && data.plugins) ? data.plugins : [];
+      if (list.length === 0) {
+        console.log('No plugins installed');
+      } else {
+        for (const name of list) console.log(` \u2022 ${name}`);
+      }
+    }
+    return;
+  }
+
+  if (sub === 'install') {
+    const name = positionals[2];
+    if (!name) { console.error('Usage: browserforce plugin install <name>'); process.exit(1); }
+    const { status, body } = await httpFetch('POST', `${baseUrl}/plugins/install`, { name }, authToken);
+    if (status >= 400) {
+      console.error(`Error: ${body.error || JSON.stringify(body)}`);
+      process.exit(1);
+    }
+    output(body, values.json);
+    return;
+  }
+
+  if (sub === 'remove') {
+    const name = positionals[2];
+    if (!name) { console.error('Usage: browserforce plugin remove <name>'); process.exit(1); }
+    const { status, body } = await httpFetch('DELETE', `${baseUrl}/plugins/${encodeURIComponent(name)}`, null, authToken);
+    if (status >= 400) {
+      console.error(`Error: ${body.error || JSON.stringify(body)}`);
+      process.exit(1);
+    }
+    output(body, values.json);
+    return;
+  }
+
+  console.error(`Unknown plugin subcommand: ${sub}`);
+  process.exit(1);
+}
+
+async function cmdUpdate() {
+  const { spawnSync } = await import('node:child_process');
+  console.log('Checking for updates...');
+  const update = await checkForUpdate();
+  if (!update) {
+    console.log('Already up to date.');
+    return;
+  }
+  console.log(`Updating ${update.current} → ${update.latest}...`);
+  const result = spawnSync('npm', ['install', '-g', 'browserforce'], { stdio: 'inherit' });
+  if (result.status !== 0) {
+    console.error('Update failed. Run manually: npm install -g browserforce');
+    process.exit(1);
+  }
+  console.log(`Updated to ${update.latest}.`);
+}
+
 function cmdHelp() {
   console.log(`
   BrowserForce — Give AI agents your real Chrome browser
@@ -227,6 +334,10 @@ function cmdHelp() {
     browserforce screenshot [n]     Screenshot tab n (default: 0)
     browserforce snapshot [n]       Accessibility tree of tab n (default: 0)
     browserforce navigate <url>     Open URL in a new tab
+    browserforce plugin list        List installed plugins
+    browserforce plugin install <n> Install a plugin from the registry
+    browserforce plugin remove <n>  Remove an installed plugin
+    browserforce update             Update to the latest version
     browserforce -e "<code>"        Execute Playwright JavaScript (one-shot)
 
   Options:
@@ -237,6 +348,9 @@ function cmdHelp() {
   Examples:
     browserforce serve
     browserforce tabs
+    browserforce plugin list
+    browserforce plugin install highlight
+    browserforce update
     browserforce -e "return await snapshot()"
     browserforce -e "await page.goto('https://github.com'); return await snapshot()"
     browserforce screenshot 0 > page.png
@@ -252,7 +366,7 @@ function cmdHelp() {
 const commands = {
   serve: cmdServe, mcp: cmdMcp, status: cmdStatus, tabs: cmdTabs,
   screenshot: cmdScreenshot, snapshot: cmdSnapshot, navigate: cmdNavigate,
-  execute: cmdExecute, help: cmdHelp,
+  execute: cmdExecute, plugin: cmdPlugin, update: cmdUpdate, help: cmdHelp,
 };
 
 const handler = commands[command];
@@ -262,9 +376,22 @@ if (!handler) {
   process.exit(1);
 }
 
+// Start update check in background — skipped for long-running or self-update commands
+const updatePromise = (command !== 'serve' && command !== 'mcp' && command !== 'update')
+  ? checkForUpdate()
+  : null;
+
 try {
   await handler();
 } catch (err) {
   console.error(`Error: ${err.message}`);
   process.exit(1);
 }
+
+// Show update notice after command finishes (wait at most 500 ms)
+if (updatePromise) {
+  const update = await Promise.race([updatePromise, new Promise(r => setTimeout(r, 500, null))]);
+  if (update) {
+    process.stderr.write(`\n  Update available: ${update.current} → ${update.latest}\n  Run: npm install -g browserforce\n\n`);
+  }
+}

package/mcp/src/exec-engine.js

@@ -198,6 +198,7 @@ export async function smartWaitForPageLoad(page, timeout, pollInterval = 100, mi
 // computed accessible names. Supports Shadow DOM (open roots).
 
 export async function getAccessibilityTree(page, rootSelector) {
+  if (!page || typeof page.evaluate !== 'function') return null;
   return page.evaluate((sel) => {
     function getRole(el) {
       if (el.nodeType !== 1) return null;
@@ -403,7 +404,7 @@ export class CodeExecutionTimeoutError extends Error {
 
 // buildExecContext takes userState and optional console helpers as params
 // instead of referencing module-level singletons.
-export function buildExecContext(defaultPage, ctx, userState, consoleHelpers = {}) {
+export function buildExecContext(defaultPage, ctx, userState, consoleHelpers = {}, pluginHelpers = {}) {
   const { consoleLogs, setupConsoleCapture } = consoleHelpers;
 
   const activePage = () => {
@@ -443,7 +444,18 @@ export function buildExecContext(defaultPage, ctx, userState, consoleHelpers = {
     if (consoleLogs) consoleLogs.set(activePage(), []);
   };
 
+  // Wrap plugin helpers to auto-inject (page, ctx, state) as first three args
+  const wrappedPluginHelpers = {};
+  for (const [name, fn] of Object.entries(pluginHelpers)) {
+    wrappedPluginHelpers[name] = (...args) => {
+      let pg = null;
+      try { pg = activePage(); } catch { /* no active page */ }
+      return fn(pg, ctx, userState, ...args);
+    };
+  }
+
   return {
+    ...wrappedPluginHelpers,           // plugin helpers spread first — built-ins always win
     page: defaultPage, context: ctx, state: userState,
     snapshot, waitForPageLoad, getLogs, clearLogs,
     fetch, URL, URLSearchParams, Buffer, setTimeout, clearTimeout,

package/mcp/src/index.js

@@ -10,6 +10,8 @@ import {
   getCdpUrl, ensureRelay, CodeExecutionTimeoutError, buildExecContext, runCode, formatResult,
 } from './exec-engine.js';
 import { screenshotWithLabels } from './a11y-labels.js';
+import { loadPlugins, buildPluginHelpers, buildPluginSkillAppendix } from './plugin-loader.js';
+import { checkForUpdate } from './update-check.js';
 
 // ─── Console Log Capture ─────────────────────────────────────────────────────
 
@@ -101,6 +103,17 @@ function getPages() {
 
 let userState = {};
 
+// ─── Plugin State ────────────────────────────────────────────────────────────
+
+let plugins = [];
+let pluginHelpers = {};
+
+// ─── Update State ────────────────────────────────────────────────────────────
+// Checked once at startup; notice injected into first execute response only.
+
+let pendingUpdate = null;    // { current, latest } or null
+let updateNoticeSent = false;
+
 // ─── MCP Server ──────────────────────────────────────────────────────────────
 
 const server = new McpServer({
@@ -291,38 +304,45 @@ state
   Persistent object — survives across execute calls. Cleared on reset.
   Use state.page, state.data, state.anything to preserve working state.`;
 
-server.tool(
-  'execute',
-  EXECUTE_PROMPT,
-  {
-    code: z.string().describe('JavaScript to run — page/context/state/snapshot/waitForPageLoad/getLogs in scope'),
-    timeout: z.number().optional().describe('Max execution time in ms (default: 30000)'),
-  },
-  async ({ code, timeout = 30000 }) => {
-    await ensureBrowser();
-    ensureAllPagesCapture();
-    const ctx = getContext();
-    const pages = ctx.pages();
-    const page = pages[0] || null;
-
-    if (page) setupConsoleCapture(page);
-    const execCtx = buildExecContext(page, ctx, userState, {
-      consoleLogs, setupConsoleCapture,
-    });
-    try {
-      const result = await runCode(code, execCtx, timeout);
-      const formatted = formatResult(result);
-      return { content: [formatted] };
-    } catch (err) {
-      const isTimeout = err instanceof CodeExecutionTimeoutError;
-      const hint = isTimeout ? '' : '\n\n[If connection lost, call reset tool to reconnect]';
-      return {
-        content: [{ type: 'text', text: `Error: ${err.message}${hint}` }],
-        isError: true,
-      };
+function registerExecuteTool(skillAppendix = '') {
+  server.tool(
+    'execute',
+    EXECUTE_PROMPT + skillAppendix,
+    {
+      code: z.string().describe('JavaScript to run — page/context/state/snapshot/waitForPageLoad/getLogs in scope'),
+      timeout: z.number().optional().describe('Max execution time in ms (default: 30000)'),
+    },
+    async ({ code, timeout = 30000 }) => {
+      await ensureBrowser();
+      ensureAllPagesCapture();
+      const ctx = getContext();
+      const pages = ctx.pages();
+      const page = pages[0] || null;
+
+      if (page) setupConsoleCapture(page);
+      const execCtx = buildExecContext(page, ctx, userState, {
+        consoleLogs, setupConsoleCapture,
+      }, pluginHelpers);
+      try {
+        const result = await runCode(code, execCtx, timeout);
+        const formatted = formatResult(result);
+        // Inject update notice into the first text response of the session (once only)
+        if (pendingUpdate && !updateNoticeSent && formatted.type === 'text') {
+          updateNoticeSent = true;
+          formatted.text += `\n\n[BrowserForce update available: ${pendingUpdate.current} → ${pendingUpdate.latest}]\n[Run: browserforce update   or: npm install -g browserforce]`;
+        }
+        return { content: [formatted] };
+      } catch (err) {
+        const isTimeout = err instanceof CodeExecutionTimeoutError;
+        const hint = isTimeout ? '' : '\n\n[If connection lost, call reset tool to reconnect]';
+        return {
+          content: [{ type: 'text', text: `Error: ${err.message}${hint}` }],
+          isError: true,
+        };
+      }
     }
-  }
-);
+  );
+}
 
 server.tool(
   'reset',
@@ -425,9 +445,29 @@ server.tool(
   }
 );
 
+// ─── Plugin Init ─────────────────────────────────────────────────────────────
+
+async function initPlugins() {
+  try {
+    plugins = await loadPlugins();
+    pluginHelpers = buildPluginHelpers(plugins);
+    if (plugins.length > 0) {
+      process.stderr.write(`[bf-mcp] Loaded ${plugins.length} plugin(s): ${plugins.map(p => p.name).join(', ')}\n`);
+    }
+  } catch (err) {
+    process.stderr.write(`[bf-mcp] Plugin load error: ${err.message}\n`);
+  }
+}
+
 // ─── Start Server ────────────────────────────────────────────────────────────
 
 async function main() {
+  await initPlugins();
+  registerExecuteTool(buildPluginSkillAppendix(plugins));
+
+  // Fire update check in background — result stored in pendingUpdate for execute handler
+  checkForUpdate().then(info => { pendingUpdate = info; }).catch(() => {});
+
   try {
     await ensureBrowser();
     process.stderr.write('[bf-mcp] Connected to relay\n');

package/mcp/src/plugin-installer.js

@@ -0,0 +1,71 @@
+import { mkdir, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import https from 'node:https';
+
+const REGISTRY_URL = 'https://raw.githubusercontent.com/ivalsaraj/browserforce/main/plugins/registry.json';
+
+function httpsGetRaw(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'browserforce' } }, (res) => {
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+      }
+      let data = '';
+      res.on('data', d => { data += d; });
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+async function fetchRegistry() {
+  // Test override
+  if (process.env.BF_TEST_REGISTRY) {
+    return JSON.parse(process.env.BF_TEST_REGISTRY);
+  }
+  const raw = await httpsGetRaw(REGISTRY_URL);
+  return JSON.parse(raw);
+}
+
+async function fetchPluginFile(url, testEnvKey) {
+  if (process.env[testEnvKey]) return process.env[testEnvKey];
+  return httpsGetRaw(url);
+}
+
+/**
+ * Install a plugin from the registry into destDir/<name>/.
+ * @param {string} name
+ * @param {string} pluginsDir  — e.g. ~/.browserforce/plugins
+ */
+export async function installPlugin(name, pluginsDir) {
+  const registry = await fetchRegistry();
+  const entry = registry.plugins?.find(p => p.name === name);
+  if (!entry) throw new Error(`Plugin "${name}" not found in registry`);
+
+  if (!entry.url) throw new Error(`Plugin "${name}" registry entry missing required field: url`);
+
+  const js = await fetchPluginFile(entry.url, 'BF_TEST_PLUGIN_JS');
+
+  // SHA-256 integrity check (skip if registry entry omits sha256 — dev/test mode)
+  if (entry.sha256) {
+    const actual = createHash('sha256').update(js).digest('hex');
+    if (actual !== entry.sha256) {
+      throw new Error(`Plugin "${name}" integrity check failed — sha256 mismatch`);
+    }
+  }
+
+  const destDir = join(pluginsDir, name);
+  await mkdir(destDir, { recursive: true });
+
+  // Write atomically: write to .tmp, then rename — prevents partial installs
+  const tmpJs = join(destDir, 'index.js.tmp');
+  await writeFile(tmpJs, js);
+  await rename(tmpJs, join(destDir, 'index.js'));
+
+  if (entry.skill_url) {
+    try {
+      const skill = await fetchPluginFile(entry.skill_url, 'BF_TEST_PLUGIN_SKILL');
+      await writeFile(join(destDir, 'SKILL.md'), skill);
+    } catch { /* SKILL.md optional */ }
+  }
+}

package/mcp/src/plugin-loader.js

@@ -0,0 +1,85 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { homedir } from 'node:os';
+
+export const PLUGINS_DIR = join(homedir(), '.browserforce', 'plugins');
+
+/**
+ * Scan pluginsDir for subfolders with index.js. Loads each as an ESM module.
+ * @param {string} [pluginsDir]
+ * @returns {Promise<Array>}
+ */
+export async function loadPlugins(pluginsDir = PLUGINS_DIR) {
+  const plugins = [];
+
+  let entries;
+  try {
+    entries = await readdir(pluginsDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      // Permission or IO error — log but don't crash
+      process.stderr.write(`[bf-plugins] Cannot read plugins dir: ${err.message}\n`);
+    }
+    return plugins; // missing directory is fine — no plugins installed
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const pluginDir = join(pluginsDir, entry.name);
+    const indexPath = join(pluginDir, 'index.js');
+
+    let mod;
+    try {
+      mod = await import(pathToFileURL(indexPath).href);
+    } catch (err) {
+      process.stderr.write(`[bf-plugins] Failed to load ${entry.name}: ${err.message}\n`);
+      continue;
+    }
+
+    const plugin = mod.default;
+    if (!plugin?.name) {
+      process.stderr.write(`[bf-plugins] Skipping ${entry.name}: export missing 'name' field\n`);
+      continue;
+    }
+
+    let skill = '';
+    try {
+      skill = await readFile(join(pluginDir, 'SKILL.md'), 'utf8');
+    } catch { /* SKILL.md is optional */ }
+
+    plugins.push({ ...plugin, _skill: skill, _dir: pluginDir });
+    process.stderr.write(`[bf-plugins] Loaded plugin: ${plugin.name}\n`);
+  }
+
+  return plugins;
+}
+
+/**
+ * Merge helpers from all plugins into a flat object.
+ * Last plugin wins on name collision (with a warning).
+ */
+export function buildPluginHelpers(plugins) {
+  const helpers = {};
+  for (const plugin of plugins) {
+    if (!plugin.helpers) continue;
+    for (const [name, fn] of Object.entries(plugin.helpers)) {
+      if (helpers[name]) {
+        process.stderr.write(`[bf-plugins] Helper name conflict: "${name}" — ${plugin.name} overwrites previous\n`);
+      }
+      helpers[name] = fn;
+    }
+  }
+  return helpers;
+}
+
+/**
+ * Build the SKILL.md appendix to append to the execute tool prompt.
+ * Only includes plugins that have non-empty SKILL.md content.
+ */
+export function buildPluginSkillAppendix(plugins) {
+  const sections = plugins
+    .filter(p => p._skill && p._skill.trim())
+    .map(p => `\n\n═══ PLUGIN: ${p.name} ═══\n\n${p._skill.trim()}`);
+  return sections.join('');
+}

package/mcp/src/update-check.js

@@ -0,0 +1,65 @@
+import https from 'node:https';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export function semverGt(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+/**
+ * Check npm registry for a newer version of browserforce.
+ * Result is cached for 24 h in ~/.browserforce/update-check.json.
+ * Returns { current, latest } if an update is available, otherwise null.
+ * Never throws — all errors resolve to null.
+ */
+export async function checkForUpdate() {
+  try {
+    // package.json is two levels up from mcp/src/
+    const pkgPath = new URL('../../package.json', import.meta.url).pathname;
+    const current = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+
+    const cacheDir = join(homedir(), '.browserforce');
+    const cacheFile = join(cacheDir, 'update-check.json');
+
+    // Return cached result if still fresh (< 24 h)
+    try {
+      const cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
+      if (Date.now() - cached.checkedAt < 86_400_000) {
+        return semverGt(cached.latest, current) ? { current, latest: cached.latest } : null;
+      }
+    } catch { /* no cache yet, or invalid */ }
+
+    // Fetch latest from npm registry
+    const latest = await new Promise((resolve, reject) => {
+      const req = https.get(
+        'https://registry.npmjs.org/browserforce/latest',
+        { headers: { 'User-Agent': 'browserforce-cli' } },
+        (res) => {
+          if (res.statusCode !== 200) { res.resume(); return reject(new Error(`HTTP ${res.statusCode}`)); }
+          let data = '';
+          res.on('data', d => (data += d));
+          res.on('end', () => { try { resolve(JSON.parse(data).version); } catch { reject(new Error('parse error')); } });
+        },
+      );
+      req.on('error', reject);
+      req.setTimeout(5000, () => { req.destroy(); reject(new Error('timeout')); });
+    });
+
+    // Persist to cache
+    try {
+      mkdirSync(cacheDir, { recursive: true });
+      writeFileSync(cacheFile, JSON.stringify({ checkedAt: Date.now(), latest }));
+    } catch { /* ignore cache write errors */ }
+
+    return semverGt(latest, current) ? { current, latest } : null;
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browserforce",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "type": "module",
   "description": "Give AI agents your real Chrome browser with progressive examples: simple reads, form interactions, multi-tab workflows, and state persistence. Search X and GitHub, extract ProductHunt data, test forms, compare A/B variants, monitor status pages. Works with OpenClaw, Claude, and any MCP agent.",
   "homepage": "https://github.com/ivalsaraj/browserforce",
@@ -46,8 +46,8 @@
     "relay": "lsof -ti tcp:19222 | xargs kill -9 2>/dev/null; sleep 0.3; node relay/src/index.js",
     "relay:dev": "lsof -ti tcp:19222 | xargs kill -9 2>/dev/null; sleep 0.3; node --watch relay/src/index.js",
     "mcp": "node mcp/src/index.js",
-    "test": "node --test relay/test/relay-server.test.js && node --test mcp/test/mcp-tools.test.js && node --test test/cli.test.js",
+    "test": "node --test relay/test/relay-server.test.js && node --test mcp/test/mcp-tools.test.js && node --test mcp/test/plugin-loader.test.js && node --test mcp/test/plugin-installer.test.js && node --test mcp/test/exec-engine-plugins.test.js && node --test mcp/test/mcp-plugin-integration.test.js && node --test test/cli.test.js",
     "test:relay": "node --test relay/test/relay-server.test.js",
-    "test:mcp": "node --test mcp/test/mcp-tools.test.js"
+    "test:mcp": "node --test mcp/test/mcp-tools.test.js && node --test mcp/test/plugin-loader.test.js && node --test mcp/test/plugin-installer.test.js && node --test mcp/test/exec-engine-plugins.test.js && node --test mcp/test/mcp-plugin-integration.test.js"
   }
 }

package/relay/src/index.js

@@ -14,6 +14,7 @@ const PING_INTERVAL_MS = 5000;
 const BF_DIR = path.join(os.homedir(), '.browserforce');
 const TOKEN_FILE = path.join(BF_DIR, 'auth-token');
 const CDP_URL_FILE = path.join(BF_DIR, 'cdp-url');
+const BF_PLUGINS_DIR = path.join(BF_DIR, 'plugins');
 
 // ─── Logging ─────────────────────────────────────────────────────────────────
 
@@ -124,8 +125,9 @@ function syntheticInitResponse(method, target) {
 }
 
 class RelayServer {
-  constructor(port = DEFAULT_PORT) {
+  constructor(port = DEFAULT_PORT, pluginsDir = BF_PLUGINS_DIR) {
     this.port = port;
+    this.pluginsDir = pluginsDir;
     this.authToken = getOrCreateAuthToken();
 
     // Extension connection (single slot)
@@ -158,23 +160,26 @@ class RelayServer {
     this.extWss.on('connection', (ws) => this._onExtConnect(ws));
     this.cdpWss.on('connection', (ws) => this._onCdpConnect(ws));
 
-    server.listen(this.port, '127.0.0.1', () => {
-      const cdpUrl = `ws://127.0.0.1:${this.port}/cdp?token=${this.authToken}`;
-      if (writeCdpUrl) writeCdpUrlFile(cdpUrl);
-      console.log('');
-      console.log('  BrowserForce');
-      console.log('  ────────────────────────────────────────');
-      console.log(`  Status:   http://127.0.0.1:${this.port}/`);
-      console.log(`  CDP:      ${cdpUrl}`);
-      console.log(`  Config:   ${BF_DIR}/`);
-      console.log('  ────────────────────────────────────────');
-      console.log('');
-      console.log('  Waiting for extension to connect...');
-      console.log('');
-    });
-
     this.server = server;
-    return this;
+
+    return new Promise((resolve) => {
+      server.listen(this.port, '127.0.0.1', () => {
+        this.port = server.address().port;
+        const cdpUrl = `ws://127.0.0.1:${this.port}/cdp?token=${this.authToken}`;
+        if (writeCdpUrl) writeCdpUrlFile(cdpUrl);
+        console.log('');
+        console.log('  BrowserForce');
+        console.log('  ────────────────────────────────────────');
+        console.log(`  Status:   http://127.0.0.1:${this.port}/`);
+        console.log(`  CDP:      ${cdpUrl}`);
+        console.log(`  Config:   ${BF_DIR}/`);
+        console.log('  ────────────────────────────────────────');
+        console.log('');
+        console.log('  Waiting for extension to connect...');
+        console.log('');
+        resolve({ port: this.port, authToken: this.authToken });
+      });
+    });
   }
 
   // ─── HTTP ────────────────────────────────────────────────────────────────
@@ -230,10 +235,95 @@ class RelayServer {
       return;
     }
 
+    // ─── Plugin Routes ───────────────────────────────────────────────────────
+
+    if (url.pathname === '/plugins' && req.method === 'GET') {
+      try {
+        const entries = fs.existsSync(this.pluginsDir)
+          ? fs.readdirSync(this.pluginsDir, { withFileTypes: true })
+              .filter(d => d.isDirectory())
+              .map(d => d.name)
+          : [];
+        res.end(JSON.stringify({ plugins: entries }));
+      } catch (err) {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ error: err.message }));
+      }
+      return;
+    }
+
+    if (url.pathname === '/plugins/install' && req.method === 'POST') {
+      if (!this._requireAuth(req, res)) return;
+      let body = '';
+      req.on('data', chunk => { body += chunk; });
+      req.on('end', async () => {
+        try {
+          const { name } = JSON.parse(body);
+          if (!name) {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ error: 'name required' }));
+            return;
+          }
+          const { installPlugin } = require('./plugin-installer.cjs');
+          await installPlugin(name, this.pluginsDir);
+          res.end(JSON.stringify({ ok: true, plugin: name }));
+        } catch (err) {
+          res.statusCode = 422;
+          res.end(JSON.stringify({ error: err.message }));
+        }
+      });
+      return;
+    }
+
+    const deleteMatch = url.pathname.match(/^\/plugins\/([a-z0-9_-]+)$/);
+    if (deleteMatch && req.method === 'DELETE') {
+      if (!this._requireAuth(req, res)) return;
+      const name = deleteMatch[1];
+      try {
+        const pluginPath = path.join(this.pluginsDir, name);
+        if (!fs.existsSync(pluginPath)) {
+          res.statusCode = 404;
+          res.end(JSON.stringify({ error: `Plugin "${name}" not installed` }));
+          return;
+        }
+        fs.rmSync(pluginPath, { recursive: true });
+        res.end(JSON.stringify({ ok: true, plugin: name }));
+      } catch (err) {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ error: err.message }));
+      }
+      return;
+    }
+
     res.statusCode = 404;
     res.end(JSON.stringify({ error: 'Not found' }));
   }
 
+  // ─── Auth Helper ─────────────────────────────────────────────────────────
+
+  _requireAuth(req, res) {
+    // Double gate: Bearer token + Origin restriction.
+    // The relay's /json/version exposes the auth token unauthenticated (required
+    // by Playwright for CDP discovery), so Bearer alone isn't sufficient —
+    // any local browser tab could read the token and call write endpoints.
+    // Restricting Origin to chrome-extension:// closes that vector.
+    const origin = req.headers['origin'] || '';
+    if (origin && !origin.startsWith('chrome-extension://')) {
+      // Origin present but not the extension — reject (CSRF / browser tab attack)
+      res.statusCode = 403;
+      res.end(JSON.stringify({ error: 'Forbidden — invalid origin' }));
+      return false;
+    }
+    const authHeader = req.headers['authorization'] || '';
+    const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null;
+    if (!token || token !== this.authToken) {
+      res.statusCode = 401;
+      res.end(JSON.stringify({ error: 'Unauthorized — Bearer token required' }));
+      return false;
+    }
+    return true;
+  }
+
   // ─── WebSocket Upgrade ───────────────────────────────────────────────────
 
   _handleUpgrade(req, socket, head) {

package/relay/src/plugin-installer.cjs

@@ -0,0 +1,55 @@
+// CJS version of mcp/src/plugin-installer.js — keep in sync
+const { mkdir, writeFile, rename } = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const https = require('node:https');
+
+const REGISTRY_URL = 'https://raw.githubusercontent.com/ivalsaraj/browserforce/main/plugins/registry.json';
+
+function httpsGetRaw(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'browserforce' } }, (res) => {
+      if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+      let data = '';
+      res.on('data', d => { data += d; });
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+async function fetchRegistry() {
+  if (process.env.BF_TEST_REGISTRY) return JSON.parse(process.env.BF_TEST_REGISTRY);
+  const raw = await httpsGetRaw(REGISTRY_URL);
+  return JSON.parse(raw);
+}
+
+async function installPlugin(name, pluginsDir) {
+  const registry = await fetchRegistry();
+  const entry = registry.plugins?.find(p => p.name === name);
+  if (!entry) throw new Error(`Plugin "${name}" not found in registry`);
+
+  if (!entry.url) throw new Error(`Plugin "${name}" registry entry missing required field: url`);
+
+  const js = await httpsGetRaw(entry.url);
+
+  if (entry.sha256) {
+    const actual = crypto.createHash('sha256').update(js).digest('hex');
+    if (actual !== entry.sha256) throw new Error(`Plugin "${name}" integrity check failed`);
+  }
+
+  const destDir = path.join(pluginsDir, name);
+  await mkdir(destDir, { recursive: true });
+
+  const tmpJs = path.join(destDir, 'index.js.tmp');
+  await writeFile(tmpJs, js);
+  await rename(tmpJs, path.join(destDir, 'index.js'));
+
+  if (entry.skill_url) {
+    try {
+      const skill = await httpsGetRaw(entry.skill_url);
+      await writeFile(path.join(destDir, 'SKILL.md'), skill);
+    } catch { /* optional */ }
+  }
+}
+
+module.exports = { installPlugin };