@evan_zhong/browser-attach 0.16.0 → 0.17.2

package/src/hub.mjs

@@ -3,6 +3,8 @@ import http from 'node:http';
 import { randomUUID, timingSafeEqual } from 'node:crypto';
 import { WebSocketServer, WebSocket } from 'ws';
 import { VERSION } from './config.mjs';
+import { syncExtension } from './setup.mjs';
+import { compareVersions } from '../extension/version.js';
 
 const MAX_MESSAGE = 24 * 1024 * 1024;
 const OPERATIONS = new Set(['release_tab', 'activate_tab', 'close_tab', 'snapshot', 'read_text', 'type', 'hover', 'drag', 'wait', 'select_option', 'click', 'fill', 'press_key', 'batch', 'scroll', 'navigate', 'screenshot', 'handle_dialog', 'upload_file', 'evaluate', 'logs']);
@@ -12,6 +14,8 @@ const send = (ws, data) => { if (ws.readyState === WebSocket.OPEN) ws.send(JSON.
 
 export async function startHub(config, { port = config.port, operationTimeout = HUB_OPERATION_TIMEOUT_MS } = {}) {
   const browsers = new Map(), clients = new Set(), claims = new Map(), tabClaims = new Map(), queues = new Map();
+  const cleanups = new Set();
+  let state = 'starting', upgradeError;
   const authorized = token => typeof token === 'string' && Buffer.byteLength(token) === Buffer.byteLength(config.token)
     && timingSafeEqual(Buffer.from(token), Buffer.from(config.token));
   const bearer = request => authorized(request.headers.authorization?.replace(/^Bearer /, ''));
@@ -28,13 +32,13 @@ export async function startHub(config, { port = config.port, operationTimeout =
     result.then(done, done);
     return result;
   }
-  function requestBrowser(browser, owner, command, args) {
+  function requestBrowser(browser, owner, command, args, timeout = operationTimeout) {
     return new Promise((resolve, reject) => {
       const id = randomUUID();
       const timer = setTimeout(() => {
         browser.pending.delete(id);
         reject(new OperationTimeout('Browser operation timed out; outcome may be unknown. Connection will release its tabs. List and claim again.'));
-      }, operationTimeout);
+      }, timeout);
       browser.pending.set(id, { resolve: value => { clearTimeout(timer); resolve(value); }, reject: error => { clearTimeout(timer); reject(error); } });
       if (browser.ws.readyState !== WebSocket.OPEN) {
         clearTimeout(timer); browser.pending.delete(id); reject(new Error('Browser disconnected')); return;
@@ -44,12 +48,13 @@ export async function startHub(config, { port = config.port, operationTimeout =
   }
   async function execute(owner, observed, method, args) {
     if (method === 'list_browsers') return {
-      browsers: [...browsers.values()].map(browser => ({ browser_id: browser.id, ...browser.info, capabilities: CAPABILITIES })),
+      browsers: [...browsers.values()].filter(browser => browser.ready).map(browser => ({ browser_id: browser.id, ...browser.info, capabilities: CAPABILITIES })),
+      upgrades: [...browsers.values()].filter(browser => !browser.ready).map(browser => ({ instance_id: browser.info.instance_id, version: browser.info.extension_version, error: browser.upgradeError })),
       hint: 'Load the paired extension in each Chrome/Edge profile if empty.',
     };
     if (method === 'list_tabs' || method === 'claim_tab' || method === 'open_tab' || method === 'fetch') {
       const browser = browsers.get(args.browser_id);
-      if (!browser) throw new Error('Browser is not connected; call browser_discover kind=browsers again');
+      if (!browser?.ready) throw new Error('Browser is not connected; call browser_discover kind=browsers again');
       if (method === 'open_tab' || method === 'fetch') return await requestBrowser(browser, owner, method, args);
       if (method === 'list_tabs') {
         const result = await requestBrowser(browser, owner, method, {});
@@ -93,10 +98,36 @@ export async function startHub(config, { port = config.port, operationTimeout =
   }
 
   let closing;
-  const server = http.createServer((request, response) => {
+  const server = http.createServer(async (request, response) => {
     if (request.headers.origin || !bearer(request)) { response.writeHead(403).end(); return; }
     response.setHeader('Content-Type', 'application/json');
-    if (request.url === '/health' && request.method === 'GET') response.end(JSON.stringify({ service: 'browser-attach', version: VERSION, browsers: browsers.size }));
+    if (request.url === '/health' && request.method === 'GET') response.end(JSON.stringify({ service: 'browser-attach', version: VERSION, state,
+      browsers: [...browsers.values()].filter(browser => browser.ready).length, clients: clients.size, upgrade_error: upgradeError,
+      extensions: [...browsers.values()].map(browser => ({ instance_id: browser.info.instance_id, version: browser.info.extension_version, ready: browser.ready, error: browser.upgradeError })) }));
+    else if (request.url === '/upgrade' && request.method === 'POST') {
+      try {
+        const target = request.headers['x-browser-attach-version'];
+        if (compareVersions(target, VERSION) <= 0) { response.writeHead(409).end(JSON.stringify({ error: 'Upgrade target must be newer than this Hub' })); return; }
+        if (state !== 'ready' || clients.size || cleanups.size || [...browsers.values()].some(browser => browser.pending.size)) {
+          response.writeHead(409).end(JSON.stringify({ error: 'Hub is in use; close other MCP connections and retry the upgrade' })); return;
+        }
+        state = 'upgrading';
+        upgradeError = undefined;
+        const connected = [...browsers.values()];
+        const outcomes = await Promise.allSettled(connected.map(async browser => {
+          const result = await requestBrowser(browser, null, 'prepare_upgrade', {}, 8000);
+          if (result.errors?.length || result.prepared !== true) throw new Error(result.errors?.join('; ') || 'Extension did not confirm cleanup');
+        }));
+        const failed = outcomes.find(item => item.status === 'rejected');
+        if (failed) {
+          await Promise.allSettled(connected.map(browser => requestBrowser(browser, null, 'resume', {}, 1000)));
+          upgradeError = `Extension cleanup failed: ${failed.reason.message}`;
+          state = 'ready'; throw new Error(upgradeError);
+        }
+        response.end(JSON.stringify({ stopping: true, extensions: connected.map(browser => browser.info.instance_id) }));
+        setImmediate(() => close());
+      } catch (error) { response.writeHead(409).end(JSON.stringify({ error: error.message })); }
+    }
     else if (request.url === '/shutdown' && request.method === 'POST') {
       response.end('{"stopping":true}'); setImmediate(() => close());
     } else response.writeHead(404).end();
@@ -105,8 +136,9 @@ export async function startHub(config, { port = config.port, operationTimeout =
   server.on('upgrade', (request, socket, head) => {
     const extension = request.url === '/extension';
     const valid = extension ? request.headers.origin === `chrome-extension://${config.extension_id}`
-      : request.url === '/client' && !request.headers.origin && bearer(request);
+      : request.url === '/client' && !request.headers.origin && bearer(request) && request.headers['x-browser-attach-version'] === VERSION;
     if (!valid) { socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return; }
+    if (state !== 'ready') { socket.end('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n'); return; }
     wss.handleUpgrade(request, socket, head, ws => {
       ws.on('pong', () => { ws.isAlive = true; });
       if (extension) connectExtension(ws); else connectClient(ws);
@@ -120,18 +152,23 @@ export async function startHub(config, { port = config.port, operationTimeout =
       try {
         const data = JSON.parse(raw.toString());
         if (!browser) {
+          if (state !== 'ready') { ws.close(1013, 'Hub is preparing an upgrade'); return; }
           const info = data.browser;
-          if (data.type !== 'hello' || !authorized(data.token) || !info || info.extension_version !== VERSION || !['chrome', 'edge'].includes(info.family) ||
+          if (data.type !== 'hello' || !authorized(data.token) || !info || !['chrome', 'edge'].includes(info.family) ||
               !['instance_id', 'run_id', 'profile_name'].every(key => typeof info[key] === 'string' && info[key].length >= 1 && info[key].length <= 128))
             throw new Error('Invalid pairing or browser identity');
           const id = `${info.instance_id}:${info.run_id}`;
           if (browsers.has(id)) throw new Error('Browser instance is already connected');
-          browser = { id, ws, info, pending: new Map() };
+          const comparison = compareVersions(info.extension_version, VERSION);
+          if (comparison > 0) throw new Error('Extension is newer than this Hub');
+          browser = { id, ws, info, ready: comparison === 0, pending: new Map() };
           browsers.set(id, browser); clearTimeout(helloTimer);
-          send(ws, { type: 'connected', browser_id: id }); return;
+          if (browser.ready) send(ws, { type: 'connected', browser_id: id });
+          else requestBrowser(browser, null, 'reload_extension', { version: VERSION }).catch(error => { browser.upgradeError = error.message; });
+          return;
         }
         if (data.type === 'ping') send(ws, { type: 'pong' });
-        else if (data.type === 'detached') forget(tabClaims.get(keyFor(browser.id, data.tab_id)));
+        else if (browser.ready && data.type === 'detached') forget(tabClaims.get(keyFor(browser.id, data.tab_id)));
         else if (browser.pending.has(data.id)) {
           const pending = browser.pending.get(data.id); browser.pending.delete(data.id);
           if ('error' in data) pending.reject(new Error(String(data.error))); else pending.resolve(data.result || {});
@@ -168,10 +205,13 @@ export async function startHub(config, { port = config.port, operationTimeout =
     });
     ws.on('close', () => {
       disconnected = true; clients.delete(ws);
-      chain.finally(async () => {
-        await Promise.allSettled([...browsers.values()].map(browser => requestBrowser(browser, owner, 'release_owner', {})));
-        for (const [handle, claim] of claims) if (claim.owner === owner) forget(handle);
-      });
+      const cleanup = chain.then(async () => {
+        await Promise.allSettled([...browsers.values()].filter(browser => browser.ready).map(async browser => {
+          const result = await requestBrowser(browser, owner, 'release_owner', {});
+          if (!result.errors?.length) for (const [handle, claim] of claims) if (claim.owner === owner && claim.browser_id === browser.id) forget(handle);
+        }));
+      }).finally(() => cleanups.delete(cleanup));
+      cleanups.add(cleanup);
     });
   }
   const heartbeat = setInterval(() => {
@@ -183,6 +223,7 @@ export async function startHub(config, { port = config.port, operationTimeout =
   async function close() {
     if (closing) return closing;
     closing = (async () => {
+      state = 'stopping';
       clearInterval(heartbeat);
       for (const ws of wss.clients) ws.close(1001, 'Hub stopped');
       const timer = setTimeout(() => { for (const ws of wss.clients) ws.terminate(); }, 1000);
@@ -191,7 +232,11 @@ export async function startHub(config, { port = config.port, operationTimeout =
     })();
     return closing;
   }
-  try { await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); }); }
-  catch (error) { clearInterval(heartbeat); wss.close(); throw error; }
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+    config.port = server.address().port;
+    if (config.extension_dir) await syncExtension(config);
+    state = 'ready';
+  } catch (error) { await close(); throw error; }
   return { server, close, port: server.address().port, claims, browsers };
 }

package/src/mcp.mjs

@@ -147,7 +147,7 @@ export function createMcp(client) {
   }, null, args => { dragOptions(args); return args; });
   tool('wait', 'Wait without scrolling or input. actionable requires a stable, visible, enabled, unobscured target in the viewport; network_idle uses observed page requests. Timeout includes the last observed state.', {
     ...handle, ...dialogPolicy, timeout_ms: integerRange('timeout_ms', 100, 30000).default(5000), ...selector, ...frameScope, nth: target.nth,
-    condition: z.enum(['attached', 'visible', 'actionable', 'text', 'url', 'network_idle']), expected: z.string().max(2000).optional().describe('For text: textContent substring; for url: main-frame URL substring. Text may use previous instead.'), previous: z.string().max(100000).optional().describe('Text only: wait for full textContent to differ; alternative to expected.'), idle_ms: integerRange('idle_ms', 100, 10000).default(500),
+    condition: z.enum(['attached', 'visible', 'actionable', 'text', 'url', 'network_idle']), expected: z.string().max(2000).optional().describe('For text: rendered innerText substring; for url: main-frame URL substring. Text may use previous instead.'), previous: z.string().max(100000).optional().describe('Text only: wait for full rendered innerText to differ; alternative to expected.'), idle_ms: integerRange('idle_ms', 100, 10000).default(500),
   }, null, args => { waitOptions(args); return args; });
   tool('select_option', 'Set one HTML select option without native UI, using synthetic input/change (events_trusted=false). Verifies retained selection only.', {
     ...handle, ...inputTimeout, ...target, value: z.string().optional().describe('Choose exactly one of value, label or zero-based index; value/label match exactly.'), label: z.string().optional(), index: integerRange('index', 0, Number.MAX_SAFE_INTEGER).optional(),
@@ -194,6 +194,7 @@ export function createMcp(client) {
 
 export async function runMcp(configPath) {
   const client = new AttachClient(await ensureHub(configPath));
+  await client.connect();
   const server = createMcp(client);
   const transport = new StdioServerTransport();
   transport.onclose = () => client.close();

package/src/setup.mjs

@@ -1,9 +1,10 @@
 import { randomBytes, createHash } from 'node:crypto';
-import { cp, mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
-import { join, resolve, dirname } from 'node:path';
+import { cp, copyFile, mkdir, mkdtemp, readFile, writeFile, chmod, rename, rm, rmdir, readdir, stat } from 'node:fs/promises';
+import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { execFileSync } from 'node:child_process';
-import { ROOT, DEFAULT_CONFIG, loadConfig, writeJson } from './config.mjs';
+import { ROOT, DEFAULT_CONFIG, VERSION, loadConfig, writeJson } from './config.mjs';
+import { compareVersions } from '../extension/version.js';
 
 export const mcpSettings = (configPath = DEFAULT_CONFIG) => ({ command: process.execPath,
   args: [join(ROOT, 'bin/browser-attach.mjs'), 'mcp', '--config', resolve(configPath)],
@@ -19,33 +20,103 @@ async function privateDirectory(path) {
   } else await chmod(path, 0o700);
 }
 
-export async function setup({ configPath = DEFAULT_CONFIG, extensionDir, port = 47831 } = {}) {
+export async function setup({ configPath = DEFAULT_CONFIG, extensionDir, port } = {}) {
   configPath = resolve(configPath);
-  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('port must be 1024..65535');
   await privateDirectory(dirname(configPath));
-  extensionDir = resolve(extensionDir || join(dirname(configPath), 'extension'));
-  if (extensionDir !== resolve(ROOT, 'extension')) {
-    await cp(join(ROOT, 'extension'), extensionDir, { recursive: true, filter: source => !source.endsWith('config.generated.js') });
-  }
-  await privateDirectory(extensionDir);
-  const manifestPath = join(extensionDir, 'manifest.json');
-  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const manifest = JSON.parse(await readFile(join(ROOT, 'extension/manifest.json'), 'utf8'));
   const extensionId = [...createHash('sha256').update(Buffer.from(manifest.key, 'base64')).digest('hex').slice(0, 32)]
     .map(char => String.fromCharCode(97 + parseInt(char, 16))).join('');
   let config;
   try { config = await loadConfig(configPath); }
   catch (error) { if (error.cause?.code !== 'ENOENT') throw error; }
+  port ??= config?.port ?? 47831;
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('port must be 1024..65535');
+  extensionDir = resolve(extensionDir || config?.extension_dir || join(dirname(configPath), 'extension'));
+  const configRelative = relative(extensionDir, configPath);
+  if (dirname(extensionDir) === extensionDir || (!isAbsolute(configRelative) && configRelative !== '..' && !configRelative.startsWith('..' + sep)))
+    throw new Error('Choose a dedicated extension directory outside the pairing file');
   config ||= { port, token: randomBytes(48).toString('base64url'), extension_id: extensionId };
   if (config.port !== port || config.extension_id !== extensionId) throw new Error('Pairing differs from requested port/extension. Stop the hub and remove the pairing config before a fresh setup.');
+  if (config.extension_dir && resolve(config.extension_dir) !== extensionDir) throw new Error('Use the paired extension directory, or a separate pairing config for a different directory.');
   config.extension_dir = extensionDir;
-  manifest.content_security_policy = { extension_pages: `script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:${port}` };
-  await writeJson(manifestPath, manifest);
-  await writeFile(join(extensionDir, 'config.generated.js'), '// Machine-local pairing secret. Never publish.\nexport const CONNECTION = ' +
-    JSON.stringify({ url: `ws://127.0.0.1:${port}/extension`, token: config.token }) + ';\n', { mode: 0o600 });
   await writeJson(configPath, config);
   return { config, configPath, extensionDir };
 }
 
+// Only the Hub holding the listening port may replace the stable copy.
+export async function syncExtension(config) {
+  const source = resolve(ROOT, 'extension'), destination = resolve(config.extension_dir);
+  const manifest = JSON.parse(await readFile(join(source, 'manifest.json'), 'utf8'));
+  const backup = destination + '.previous';
+  async function installed(directory) {
+    try {
+      const value = JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8'));
+      if (value.key !== manifest.key) throw new Error(`Unrecognized extension directory: ${directory}`);
+      return value;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      try { if ((await readdir(directory)).length) throw new Error(`Unrecognized extension directory: ${directory}`); }
+      catch (missing) { if (missing.code !== 'ENOENT') throw missing; }
+      return null;
+    }
+  }
+  async function files(directory) {
+    const entries = await readdir(directory, { recursive: true });
+    const kinds = await Promise.all(entries.map(path => stat(join(directory, path))));
+    return entries.filter((_, index) => kinds[index].isFile());
+  }
+  async function install(directory) {
+    await privateDirectory(destination);
+    const incoming = await files(directory), existing = await files(destination);
+    // Keep the loaded directory itself stable and commit its manifest last.
+    for (const path of incoming.filter(path => path !== 'manifest.json')) {
+      const target = join(destination, path);
+      await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+      await copyFile(join(directory, path), target + '.updating');
+      await rename(target + '.updating', target);
+    }
+    for (const path of existing) if (!incoming.includes(path)) await rm(join(destination, path));
+    await writeJson(join(destination, 'manifest.json'), JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8')));
+  }
+  let current = await installed(destination);
+  if (current && compareVersions(current.version, VERSION) > 0) throw new Error('Refusing to downgrade the installed extension');
+  const previous = destination === source ? null : await installed(backup);
+  if (previous) {
+    await install(backup);
+    current = previous;
+    await rm(backup, { recursive: true });
+  }
+  await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+  const stage = destination === source ? source : await mkdtemp(destination + '.staging-');
+  try {
+    if (stage !== source) await cp(source, stage, { recursive: true, filter: path => !path.endsWith('config.generated.js') });
+    await privateDirectory(stage);
+    manifest.content_security_policy = { extension_pages: `script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:${config.port}` };
+    await writeJson(join(stage, 'manifest.json'), manifest);
+    await writeFile(join(stage, 'config.generated.js'), '// Machine-local pairing secret. Never publish.\nexport const CONNECTION = ' +
+      JSON.stringify({ url: `ws://127.0.0.1:${config.port}/extension`, token: config.token }) + ';\n', { mode: 0o600 });
+    if (stage !== source) {
+      if (current) {
+        await privateDirectory(stage + '.previous');
+        await cp(destination, stage + '.previous', { recursive: true });
+        await rename(stage + '.previous', backup);
+      } else {
+        try { await rmdir(destination); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+        await rename(stage, destination);
+        return;
+      }
+      try { await install(stage); }
+      catch (error) { if (current) await install(backup); throw error; }
+      if (current) await rm(backup, { recursive: true });
+    }
+  } finally {
+    if (stage !== source) {
+      await rm(stage, { recursive: true, force: true });
+      await rm(stage + '.previous', { recursive: true, force: true });
+    }
+  }
+}
+
 export async function configureNosis(directory = join(homedir(), '.nosis'), { configPath = DEFAULT_CONFIG } = {}) {
   const path = join(directory, 'agent_config.json');
   const data = JSON.parse((await readFile(path, 'utf8')).replace(/^\uFEFF/, ''));