@browserbridge/bbx 1.7.8 → 1.9.0

package/packages/agent-client/src/config.js

@@ -0,0 +1,195 @@
+// @ts-check
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getBridgeDir, getBridgeTransport } from '../../native-host/src/config.js';
+import { atomicWriteFile } from './atomic-write.js';
+
+/** @typedef {import('./types.js').AutoUpdatePolicy} AutoUpdatePolicy */
+/** @typedef {import('./types.js').BridgeClientOptions} BridgeClientOptions */
+/** @typedef {import('./types.js').BrowserBridgeConfig} BrowserBridgeConfig */
+
+export const AUTO_UPDATE_ENV = 'BBX_AUTO_UPDATE';
+export const CONFIG_FILENAME = 'config.json';
+const AUTO_UPDATE_POLICIES = new Set(['off', 'compatible']);
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getBridgeConfigPath(env = process.env) {
+  return path.join(getBridgeDir(env), CONFIG_FILENAME);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {AutoUpdatePolicy}
+ */
+export function parseAutoUpdatePolicy(value) {
+  if (typeof value !== 'string' || !AUTO_UPDATE_POLICIES.has(value)) {
+    throw new Error('Auto-update policy must be "off" or "compatible".');
+  }
+  return /** @type {AutoUpdatePolicy} */ (value);
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {Promise<BrowserBridgeConfig>}
+ */
+export async function readBridgeConfig(env = process.env) {
+  const configPath = getBridgeConfigPath(env);
+  let raw;
+  try {
+    raw = await fs.promises.readFile(configPath, 'utf8');
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return { autoUpdate: 'off' };
+    }
+    throw error;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Cannot read ${configPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Cannot read ${configPath}: expected a JSON object.`);
+  }
+
+  const config = /** @type {Record<string, unknown>} */ (parsed);
+  return {
+    ...config,
+    autoUpdate: config.autoUpdate === undefined ? 'off' : parseAutoUpdatePolicy(config.autoUpdate),
+  };
+}
+
+/**
+ * @param {AutoUpdatePolicy} policy
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {Promise<string>}
+ */
+export async function setAutoUpdatePolicy(policy, env = process.env) {
+  const normalized = parseAutoUpdatePolicy(policy);
+  const configPath = getBridgeConfigPath(env);
+  const config = await readBridgeConfig(env);
+  await atomicWriteFile(
+    configPath,
+    `${JSON.stringify({ ...config, autoUpdate: normalized }, null, 2)}\n`,
+    { encoding: 'utf8', mode: 0o600 }
+  );
+  return configPath;
+}
+
+/**
+ * Environment configuration overrides the persisted preference for unattended
+ * and containerized clients.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {Promise<AutoUpdatePolicy>}
+ */
+export async function getAutoUpdatePolicy(env = process.env) {
+  if (env[AUTO_UPDATE_ENV] !== undefined) {
+    return parseAutoUpdatePolicy(env[AUTO_UPDATE_ENV]);
+  }
+  return (await readBridgeConfig(env)).autoUpdate;
+}
+
+/**
+ * @param {BridgeClientOptions} [options={}]
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @param {string[]} [argv=process.argv]
+ * @returns {Promise<BridgeClientOptions>}
+ */
+export async function applyConfiguredAutoUpdate(
+  options = {},
+  env = process.env,
+  argv = process.argv
+) {
+  if (options.updateNpmOnCompatibleVersion !== undefined) {
+    return options;
+  }
+  if (env[AUTO_UPDATE_ENV] === undefined && !isBrowserBridgeProcess(argv)) {
+    return options;
+  }
+  if (env.npm_command === 'exec' || (await getAutoUpdatePolicy(env)) !== 'compatible') {
+    return options;
+  }
+  const transport = options.socketPath ? null : (options.transport ?? getBridgeTransport(env));
+  if (transport?.type === 'tcp' && !isLoopbackHost(transport.host)) {
+    return options;
+  }
+  return {
+    ...options,
+    checkProtocolOnConnect: true,
+    updateNpmOnCompatibleVersion: true,
+    exitProcessOnNpmUpdate: isMcpProcess(argv),
+  };
+}
+
+/**
+ * @param {string} host
+ * @returns {boolean}
+ */
+function isLoopbackHost(host) {
+  const normalized = host
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/gu, '');
+  if (normalized === 'localhost' || normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') {
+    return true;
+  }
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(normalized);
+  return Boolean(
+    match && match.slice(1).every((part) => Number(part) <= 255) && match[1] === '127'
+  );
+}
+
+/**
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isMcpProcess(argv = process.argv) {
+  const entry = (argv[1] || '').replaceAll('\\', '/');
+  const entryName = entry.slice(entry.lastIndexOf('/') + 1).toLowerCase();
+  return (
+    (argv[2] === 'mcp' && argv[3] === 'serve') ||
+    (entry.includes('/mcp-server/') && entry.endsWith('/bin.js')) ||
+    entryName === 'bbx-mcp' ||
+    entryName === 'bbx-mcp.cmd'
+  );
+}
+
+/**
+ * Persisted CLI preferences apply to the shipped executables, not arbitrary
+ * programmatic BridgeClient consumers that happen to share the same user home.
+ *
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isBrowserBridgeProcess(argv = process.argv) {
+  if (isMcpProcess(argv)) return true;
+  const entry = (argv[1] || '').replaceAll('\\', '/');
+  const entryName = entry.slice(entry.lastIndexOf('/') + 1).toLowerCase();
+  return (
+    (entry.includes('/agent-client/') && entry.endsWith('/cli.js')) ||
+    entryName === 'bbx' ||
+    entryName === 'bbx.cmd'
+  );
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingFileError(error) {
+  return Boolean(
+    error &&
+    typeof error === 'object' &&
+    /** @type {{ code?: unknown }} */ (error).code === 'ENOENT'
+  );
+}

package/packages/agent-client/src/content-extract.js

@@ -0,0 +1,198 @@
+// @ts-check
+
+import { Readability } from '@mozilla/readability';
+import { parseHTML } from 'linkedom';
+
+/** @typedef {import('../../protocol/src/types.js').ExtractContentResult} ExtractContentResult */
+/** @typedef {import('../../protocol/src/types.js').NormalizedExtractContentParams} ExtractContentParams */
+
+const METADATA_LIMITS = Object.freeze({ title: 300, byline: 200, excerpt: 500, siteName: 200 });
+const EXCLUDED_SELECTOR =
+  'script,style,noscript,template,input,textarea,select,option,button,[hidden],[aria-hidden="true"]';
+
+/** @param {string | null | undefined} value @param {number} limit @returns {string | undefined} */
+function boundedText(value, limit) {
+  const normalized = String(value ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return normalized ? normalized.slice(0, limit) : undefined;
+}
+
+/** @param {ParentNode} root @returns {void} */
+function sanitize(root) {
+  for (const element of root.querySelectorAll(EXCLUDED_SELECTOR)) element.remove();
+  for (const element of root.querySelectorAll('[style]')) {
+    const style = element.getAttribute('style')?.toLowerCase() ?? '';
+    if (/display\s*:\s*none|visibility\s*:\s*hidden/.test(style)) element.remove();
+  }
+}
+
+/** @param {Element} element @returns {number} */
+function meaningfulLength(element) {
+  return (element.textContent ?? '').replace(/\s+/g, ' ').trim().length;
+}
+
+/** @param {ParentNode} root @returns {Element | null} */
+function largestSemanticRoot(root) {
+  let best = null;
+  let bestLength = 0;
+  const candidates = [];
+  if (
+    'matches' in root &&
+    typeof (/** @type {{ matches?: unknown }} */ (root).matches) === 'function' &&
+    /** @type {Element} */ (root).matches('article,main,[role="main"]')
+  ) {
+    candidates.push(/** @type {Element} */ (root));
+  }
+  candidates.push(...root.querySelectorAll('article,main,[role="main"]'));
+  for (const candidate of candidates) {
+    const length = meaningfulLength(candidate);
+    if (length > bestLength) {
+      best = candidate;
+      bestLength = length;
+    }
+  }
+  return best;
+}
+
+/** @param {Node} node @returns {string} */
+function markdownForNode(node) {
+  if (node.nodeType === 3) return (node.textContent ?? '').replace(/\s+/g, ' ');
+  if (node.nodeType !== 1) return '';
+  const element = /** @type {Element} */ (node);
+  const tag = element.tagName.toLowerCase();
+  const children = () => Array.from(element.childNodes, markdownForNode).join('');
+  if (/^h[1-6]$/.test(tag)) return `\n${'#'.repeat(Number(tag[1]))} ${children().trim()}\n\n`;
+  if (['p', 'div', 'section', 'article', 'main'].includes(tag)) {
+    return `\n${children().trim()}\n\n`;
+  }
+  if (tag === 'br') return '\n';
+  if (tag === 'hr') return '\n---\n';
+  if (tag === 'strong' || tag === 'b') return `**${children().trim()}**`;
+  if (tag === 'em' || tag === 'i') return `*${children().trim()}*`;
+  if (tag === 'code' && element.parentElement?.tagName.toLowerCase() !== 'pre') {
+    return `\`${(element.textContent ?? '').replace(/`/g, '\\`')}\``;
+  }
+  if (tag === 'pre') return `\n\`\`\`\n${element.textContent ?? ''}\n\`\`\`\n\n`;
+  if (tag === 'blockquote') {
+    return `\n${children()
+      .trim()
+      .split('\n')
+      .map((line) => `> ${line}`)
+      .join('\n')}\n\n`;
+  }
+  if (tag === 'li') {
+    const marker =
+      element.parentElement?.tagName.toLowerCase() === 'ol'
+        ? `${Array.from(element.parentElement.children).indexOf(element) + 1}.`
+        : '-';
+    return `\n${marker} ${children().trim()}`;
+  }
+  if (tag === 'ul' || tag === 'ol') return `${children()}\n\n`;
+  if (tag === 'a') {
+    const label = children().trim();
+    const href = element.getAttribute('href')?.trim();
+    return href && !/^(?:javascript|data):/i.test(href) ? `[${label}](${href})` : label;
+  }
+  return children();
+}
+
+/** @param {Element} root @param {'text' | 'markdown'} format @returns {string} */
+function formatRoot(root, format) {
+  if (format === 'markdown') {
+    return markdownForNode(root)
+      .replace(/[ \t]+\n/g, '\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim();
+  }
+  return (root.textContent ?? '')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/** @param {string} content @param {number} budget @param {'text' | 'markdown'} format */
+function truncateContent(content, budget, format) {
+  if (content.length <= budget) return { content, truncated: false, omitted: 0 };
+  const boundary = Math.max(content.lastIndexOf('\n\n', budget), content.lastIndexOf(' ', budget));
+  const end = boundary >= Math.floor(budget * 0.7) ? boundary : budget;
+  let value = content.slice(0, end).trimEnd();
+  if (format === 'markdown' && (value.match(/```/g)?.length ?? 0) % 2 === 1) {
+    value = `${value.slice(0, Math.max(0, budget - 4)).trimEnd()}\n\`\`\``;
+  }
+  return { content: value, truncated: true, omitted: content.length - value.length };
+}
+
+/**
+ * Convert one bounded browser HTML snapshot into semantic content in Node.
+ * Raw HTML is consumed here and never included in the returned result.
+ *
+ * @param {string} html
+ * @param {ExtractContentParams} params
+ * @param {{ title?: string, settlement?: ExtractContentResult['settlement'] }} [context]
+ * @returns {ExtractContentResult}
+ */
+export function extractContentFromHtml(html, params, context = {}) {
+  const escapedTitle = String(context.title ?? '').replace(/[&<>]/g, (character) => {
+    if (character === '&') return '&amp;';
+    if (character === '<') return '&lt;';
+    return '&gt;';
+  });
+  const { document } = parseHTML(
+    `<!doctype html><html><head><title>${escapedTitle}</title></head><body>${html}</body></html>`
+  );
+  sanitize(document);
+  const semanticRoot = largestSemanticRoot(document.body);
+  const semanticLength = semanticRoot ? meaningfulLength(semanticRoot) : 0;
+  let readability = null;
+  try {
+    readability = new Readability(/** @type {Document} */ (document.cloneNode(true))).parse();
+  } catch {
+    readability = null;
+  }
+
+  /** @type {Element} */
+  let resultRoot;
+  /** @type {import('../../protocol/src/types.js').ExtractContentSource} */
+  let source;
+  if (readability && (readability.length ?? 0) >= Math.max(200, Math.floor(semanticLength * 0.2))) {
+    const template = document.createElement('template');
+    template.innerHTML = readability.content ?? '';
+    sanitize(template.content);
+    const wrapper = document.createElement('article');
+    wrapper.append(template.content.cloneNode(true));
+    resultRoot = wrapper;
+    source = 'readability';
+  } else if (semanticRoot && semanticLength > 0) {
+    resultRoot = semanticRoot;
+    source = 'semantic-root';
+  } else {
+    resultRoot = document.body;
+    source = 'body';
+  }
+
+  const formatted = formatRoot(resultRoot, params.format);
+  const bounded = truncateContent(formatted, params.textBudget, params.format);
+  const metadata = params.includeMetadata
+    ? {
+        title: boundedText(readability?.title ?? context.title, METADATA_LIMITS.title),
+        byline: boundedText(readability?.byline, METADATA_LIMITS.byline),
+        excerpt: boundedText(readability?.excerpt, METADATA_LIMITS.excerpt),
+        siteName: boundedText(readability?.siteName, METADATA_LIMITS.siteName),
+      }
+    : {};
+  return {
+    format: params.format,
+    content: bounded.content,
+    ...metadata,
+    source,
+    root: {
+      tag: resultRoot.tagName.toLowerCase(),
+      ...(params.selector ? { selector: params.selector } : {}),
+    },
+    length: formatted.length,
+    truncated: bounded.truncated,
+    omitted: bounded.omitted,
+    ...(context.settlement ? { settlement: context.settlement } : {}),
+  };
+}

package/packages/agent-client/src/npm-self-update.js

@@ -0,0 +1,305 @@
+// @ts-check
+
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = '@browserbridge/bbx';
+const PACKAGE_ROOT = path.dirname(fileURLToPath(new URL('../../../package.json', import.meta.url)));
+const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+const DEFAULT_LOCK_TIMEOUT_MS = 120_000;
+const UPDATE_LOCK_PORT_START = 49_152;
+const UPDATE_LOCK_PORT_COUNT = 16_384;
+const UPDATE_LOCK_PORT_ATTEMPTS = 32;
+
+/** @typedef {import('./types.js').NpmUpdateResult} NpmUpdateResult */
+
+export class NpmPackageUpdatedError extends Error {
+  /**
+   * @param {string} version
+   */
+  constructor(version) {
+    super(`Browser Bridge updated to ${version}; restarting to load the new version.`);
+    this.name = 'NpmPackageUpdatedError';
+    this.code = 'BBX_NPM_UPDATED';
+    this.version = version;
+  }
+}
+
+/**
+ * @param {string} value
+ * @returns {[number, number, number] | null}
+ */
+export function parseStableVersion(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.exec(value);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+/**
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+export function comparePackageVersions(left, right) {
+  const leftParts = parseStableVersion(left);
+  const rightParts = parseStableVersion(right);
+  if (!leftParts || !rightParts) {
+    throw new Error(`Cannot compare invalid stable versions "${left}" and "${right}".`);
+  }
+  for (let index = 0; index < leftParts.length; index += 1) {
+    const delta = leftParts[index] - rightParts[index];
+    if (delta !== 0) return delta > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * @param {string} version
+ * @returns {string | null}
+ */
+export function derivePackageProtocolVersion(version) {
+  const parsed = parseStableVersion(version);
+  return parsed ? `${parsed[0]}.${parsed[1]}` : null;
+}
+
+/**
+ * @param {unknown[]} versions
+ * @param {readonly string[]} supportedProtocols
+ * @param {string} currentVersion
+ * @returns {string | null}
+ */
+export function selectCompatibleNpmVersion(versions, supportedProtocols, currentVersion) {
+  if (!parseStableVersion(currentVersion)) return null;
+  const supported = new Set(supportedProtocols.filter((version) => /^\d+\.\d+$/u.test(version)));
+  let selected = null;
+  for (const value of versions) {
+    if (typeof value !== 'string' || !parseStableVersion(value)) continue;
+    const protocolVersion = derivePackageProtocolVersion(value);
+    if (!protocolVersion || !supported.has(protocolVersion)) continue;
+    if (comparePackageVersions(value, currentVersion) <= 0) continue;
+    if (selected === null || comparePackageVersions(value, selected) > 0) selected = value;
+  }
+  return selected;
+}
+
+/**
+ * @param {string} packageRoot
+ * @returns {Promise<string | null>}
+ */
+async function readPackageVersion(packageRoot) {
+  try {
+    const parsed = JSON.parse(
+      await fs.promises.readFile(path.join(packageRoot, 'package.json'), 'utf8')
+    );
+    return parsed && typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string[]} args
+ * @param {{ env?: NodeJS.ProcessEnv, timeoutMs?: number }} [options={}]
+ * @returns {Promise<string>}
+ */
+export async function runNpmCommand(args, options = {}) {
+  const env = options.env ?? process.env;
+  const npmExecPath = env.npm_execpath;
+  const useNode = Boolean(npmExecPath && /\.(?:c?js|mjs)$/u.test(npmExecPath));
+  const command = useNode
+    ? process.execPath
+    : npmExecPath || (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+  const commandArgs = useNode && npmExecPath ? [npmExecPath, ...args] : args;
+
+  return new Promise((resolve, reject) => {
+    execFile(
+      command,
+      commandArgs,
+      {
+        env,
+        encoding: 'utf8',
+        timeout: options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
+        maxBuffer: 4 * 1024 * 1024,
+        windowsHide: true,
+      },
+      (error, stdout, stderr) => {
+        if (!error) {
+          resolve(stdout);
+          return;
+        }
+        const detail = stderr.trim();
+        reject(
+          new Error(
+            `npm ${args.join(' ')} failed${detail ? `: ${detail.slice(0, 1000)}` : `: ${error.message}`}`
+          )
+        );
+      }
+    );
+  });
+}
+
+/**
+ * Bind an exclusive loopback port derived from the global npm package path.
+ * The OS releases the lock if the updater crashes, avoiding persistent stale
+ * lock files while preserving cross-process serialization.
+ *
+ * @param {string} lockKey
+ * @param {number} [offset=0]
+ * @returns {number}
+ */
+export function getNpmUpdateLockPort(lockKey, offset = 0) {
+  const digest = createHash('sha256').update(lockKey).digest();
+  return (
+    UPDATE_LOCK_PORT_START +
+    ((digest.readUInt32BE(0) + Math.max(0, Math.trunc(offset))) % UPDATE_LOCK_PORT_COUNT)
+  );
+}
+
+/**
+ * @param {number} port
+ * @returns {Promise<string | null>}
+ */
+async function readNpmUpdateLockIdentity(port) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    let settled = false;
+    let value = '';
+    /** @param {string | null} result */
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setEncoding('utf8');
+    socket.setTimeout(250, () => finish(null));
+    socket.on('data', (chunk) => {
+      value += chunk;
+      if (value.length > 256 || value.includes('\n')) finish(value.trim());
+    });
+    socket.on('end', () => finish(value.trim() || null));
+    socket.on('error', () => finish(null));
+  });
+}
+
+/**
+ * @param {string} lockKey
+ * @param {number} [timeoutMs=DEFAULT_LOCK_TIMEOUT_MS]
+ * @returns {Promise<() => Promise<void>>}
+ */
+export async function acquireNpmUpdateLock(lockKey, timeoutMs = DEFAULT_LOCK_TIMEOUT_MS) {
+  const startedAt = Date.now();
+  const identity = `bbx-npm-update:${createHash('sha256').update(lockKey).digest('hex')}`;
+  while (true) {
+    let activeUpdaterFound = false;
+    for (let offset = 0; offset < UPDATE_LOCK_PORT_ATTEMPTS; offset += 1) {
+      const port = getNpmUpdateLockPort(lockKey, offset);
+      const server = net.createServer((socket) => socket.end(`${identity}\n`));
+      const acquired = await new Promise((resolve, reject) => {
+        server.once('error', (error) => {
+          if (/** @type {NodeJS.ErrnoException} */ (error).code === 'EADDRINUSE') {
+            resolve(false);
+            return;
+          }
+          reject(error);
+        });
+        server.listen({ host: '127.0.0.1', port, exclusive: true }, () => resolve(true));
+      });
+      if (acquired) {
+        return async () => {
+          await new Promise((resolve) => server.close(resolve));
+        };
+      }
+      if ((await readNpmUpdateLockIdentity(port)) === identity) {
+        activeUpdaterFound = true;
+        break;
+      }
+    }
+    if (Date.now() - startedAt >= timeoutMs) {
+      throw new Error(
+        activeUpdaterFound
+          ? 'Timed out waiting for another Browser Bridge npm update to finish.'
+          : 'Could not reserve a local Browser Bridge npm update lock.'
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+}
+
+/**
+ * @param {{
+ *   extensionVersion: string,
+ *   supportedVersions: readonly string[],
+ *   env?: NodeJS.ProcessEnv,
+ *   packageRoot?: string,
+ *   lockPath?: string,
+ *   runNpmFn?: typeof runNpmCommand,
+ * }} options
+ * @returns {Promise<NpmUpdateResult>}
+ */
+export async function updateCompatibleNpmPackage(options) {
+  const env = options.env ?? process.env;
+  const packageRoot = options.packageRoot ?? PACKAGE_ROOT;
+  const runNpmFn = options.runNpmFn ?? runNpmCommand;
+  const extensionProtocol = derivePackageProtocolVersion(options.extensionVersion);
+  if (!extensionProtocol || !options.supportedVersions.includes(extensionProtocol)) {
+    return { updated: false, reason: 'invalid_extension_version' };
+  }
+
+  const globalRoot = (await runNpmFn(['root', '--global'], { env })).trim();
+  const expectedRoot = path.join(globalRoot, '@browserbridge', 'bbx');
+  const [realPackageRoot, realExpectedRoot, expectedStat] = await Promise.all([
+    fs.promises.realpath(packageRoot).catch(() => ''),
+    fs.promises.realpath(expectedRoot).catch(() => ''),
+    fs.promises.lstat(expectedRoot).catch(() => null),
+  ]);
+  if (!realPackageRoot || realPackageRoot !== realExpectedRoot || expectedStat?.isSymbolicLink()) {
+    return { updated: false, reason: 'not_global_install' };
+  }
+
+  const lockKey = options.lockPath ?? realExpectedRoot;
+  const releaseLock = await acquireNpmUpdateLock(lockKey);
+  try {
+    const currentVersion = await readPackageVersion(packageRoot);
+    if (!currentVersion || !parseStableVersion(currentVersion)) {
+      return { updated: false, reason: 'invalid_installed_version' };
+    }
+    if (comparePackageVersions(options.extensionVersion, currentVersion) <= 0) {
+      return { updated: false, reason: 'extension_not_newer', previousVersion: currentVersion };
+    }
+
+    const versionsRaw = await runNpmFn(['view', PACKAGE_NAME, 'versions', '--json'], { env });
+    const parsedVersions = JSON.parse(versionsRaw);
+    const versions = Array.isArray(parsedVersions) ? parsedVersions : [parsedVersions];
+    const targetVersion = selectCompatibleNpmVersion(
+      versions,
+      options.supportedVersions,
+      currentVersion
+    );
+    if (!targetVersion) {
+      return { updated: false, reason: 'no_compatible_update', previousVersion: currentVersion };
+    }
+
+    await runNpmFn(
+      ['install', '--global', '--no-audit', '--no-fund', '--', `${PACKAGE_NAME}@${targetVersion}`],
+      { env }
+    );
+    const installedVersion = await readPackageVersion(packageRoot);
+    if (installedVersion !== targetVersion) {
+      throw new Error(
+        `npm reported success, but Browser Bridge ${targetVersion} was not installed at ${packageRoot}.`
+      );
+    }
+    return {
+      updated: true,
+      reason: 'updated',
+      previousVersion: currentVersion,
+      version: targetVersion,
+    };
+  } finally {
+    await releaseLock();
+  }
+}