@browserbridge/bbx 1.2.0 → 1.4.0

package/README.md

@@ -99,17 +99,20 @@ Managed installs support OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Open
 
 ## Why Browser Bridge
 
-Most adjacent tools optimize for different goals. [Playwright](https://playwright.dev/) and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. [Claude in Chrome](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) is great for integrated Claude workflows, but is vendor-specific. Generic MCP browser servers offer broad control without the developer-focused depth.
+Most adjacent tools optimize for different goals. [Playwright](https://playwright.dev/) and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. [Claude in Chrome](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) is great for integrated Claude workflows, and the [Codex extension](https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg) is a great option if you use Codex, but both are vendor-specific. Generic MCP browser servers offer broad control without the developer-focused depth.
 
 Browser Bridge is optimized for the opposite starting point: **inspect the state that already exists** in a real tab - logged-in sessions, feature flags, seeded storage, SPA state - use structured reads to understand it, test a patch in place, then fix the source. It's open-source, agent-agnostic, and scoped to explicit tab sessions rather than ambient browser control.
 
 ## Setup
 
-1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie)
+1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie) in Chrome or another Chromium-based browser
 2. `npm install -g @browserbridge/bbx` - installs the CLI and native host
-3. In the extension side panel, install MCP or CLI (skill) for your agent of choice
-4. Enable Browser Bridge for the Chrome window you want to inspect/control with the AI agent
-5. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the `browser-bridge` / `$bbx` skill in CLI mode
+3. Run `bbx install`, or target a specific browser with `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`
+4. In the extension side panel, install MCP or CLI (skill) for your agent of choice
+5. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
+6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)
+
+MCP mode is self-contained: the server exposes tools, startup instructions, and prompt templates, so a separate CLI skill is not required for MCP guidance.
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -61,7 +61,7 @@
     "postinstall": "node packages/native-host/bin/postinstall.js",
     "package:extension": "node scripts/package-extension.mjs",
     "check:extension-zip": "node scripts/check-extension-zip.mjs",
-    "release:check": "npm run lint && npm run typecheck && npm test && npm run coverage:check && npm run package:extension && npm pack --dry-run",
+    "release:check": "npm run lint && npm run typecheck && npm test && npm run coverage:check && npm run package:extension && npm run check:extension-zip && npm pack --dry-run",
     "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run coverage:check",
     "status": "node packages/agent-client/src/cli.js status",
     "daemon": "node packages/native-host/bin/bridge-daemon.js",

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

@@ -50,8 +50,8 @@ import { getDoctorReport, requestBridge, resolveRef } from './runtime.js';
 import { collectSetupStatus } from './setup-status.js';
 import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
 
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-/** @typedef {{ image: string, rect: Record<string, unknown> }} ScreenshotResult */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').ScreenshotResult} ScreenshotResult */
 
 const REQUEST_SOURCE = 'cli';
 const TEST_TIMEOUT_ENV = 'BBX_CLIENT_REQUEST_TIMEOUT_MS';
@@ -128,19 +128,25 @@ if (command === 'install-skill') {
   const positional = rest.filter((a) => !a.startsWith('--'));
 
   if (positional.length === 0) {
-    // Parse scope flags without going through parseInstallAgentArgs.
-    let isGlobal = true;
-    if (rest.includes('--local')) isGlobal = false;
-    if (rest.includes('--global')) isGlobal = true;
+    let scopeOptions;
+    try {
+      scopeOptions = parseInstallAgentArgs(rest);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exit(1);
+    }
+
+    const isGlobal = scopeOptions.global !== false;
+    const projectPath = isGlobal ? os.homedir() : scopeOptions.projectPath;
 
     const setupStatus = await collectSetupStatus({
       global: isGlobal,
       cwd: process.cwd(),
-      projectPath: isGlobal ? os.homedir() : process.cwd(),
+      projectPath,
       ...getSetupStatusTestOverrides(),
     });
-    /** @type {import('./install.js').SupportedTarget[]} */
-    const detected = /** @type {import('./install.js').SupportedTarget[]} */ (
+    /** @type {import('./types.js').SupportedTarget[]} */
+    const detected = /** @type {import('./types.js').SupportedTarget[]} */ (
       setupStatus.skillTargets.filter((entry) => entry.detected).map((entry) => entry.key)
     );
     const installedManagedTargets = new Set(
@@ -149,7 +155,7 @@ if (command === 'install-skill') {
         .map((entry) => entry.key)
     );
     const installedManagedTargetList =
-      /** @type {import('./install.js').SupportedTarget[]} */ ([...installedManagedTargets]);
+      /** @type {import('./types.js').SupportedTarget[]} */ ([...installedManagedTargets]);
 
     // Aliases like 'openai' and 'google' map to canonical targets and stay omitted.
     const items = SUPPORTED_TARGETS.map((t) => ({
@@ -167,19 +173,18 @@ if (command === 'install-skill') {
       items
     );
 
-    /** @type {import('./install.js').SupportedTarget[]} */
+    /** @type {import('./types.js').SupportedTarget[]} */
     let targets;
     if (selected === null) {
       // Non-TTY: prefer managed installs, then detected targets (always includes 'agents').
       targets = installedManagedTargets.size > 0 ? installedManagedTargetList : detected;
     } else {
-      targets = /** @type {import('./install.js').SupportedTarget[]} */ (selected);
+      targets = /** @type {import('./types.js').SupportedTarget[]} */ (selected);
     }
 
-    const projectPath = isGlobal ? os.homedir() : process.cwd();
     if (selected !== null) {
       const deselectedTargets =
-        /** @type {import('./install.js').SupportedTarget[]} */ (
+        /** @type {import('./types.js').SupportedTarget[]} */ (
           installedManagedTargetList.filter((target) => !targets.includes(target))
         );
       const removableTargets = await findInstalledManagedTargets({
@@ -226,22 +231,34 @@ if (command === 'install-skill') {
 }
 
 if (command === 'install-mcp') {
-  const argsLeft = [...rest];
   let isGlobal = true;
+  /** @type {string[]} */
+  const positionals = [];
 
-  const localIdx = argsLeft.indexOf('--local');
-  if (localIdx !== -1) {
-    isGlobal = false;
-    argsLeft.splice(localIdx, 1);
+  for (const arg of rest) {
+    if (arg === '--local') {
+      isGlobal = false;
+      continue;
+    }
+    if (arg === '--global') {
+      isGlobal = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      process.stderr.write(`Unknown install-mcp option "${arg}".\n`);
+      process.exit(1);
+    }
+    positionals.push(arg);
   }
-  const globalIdx = argsLeft.indexOf('--global');
-  if (globalIdx !== -1) {
-    argsLeft.splice(globalIdx, 1);
+
+  if (positionals.length > 1) {
+    process.stderr.write(`Unexpected extra argument "${positionals[1]}".\n`);
+    process.exit(1);
   }
 
-  const clientArg = argsLeft[0];
+  const clientArg = positionals[0];
 
-  /** @type {import('./mcp-config.js').McpClientName[]} */
+  /** @type {import('./types.js').McpClientName[]} */
   let clients;
 
   if (!clientArg) {
@@ -252,14 +269,14 @@ if (command === 'install-mcp') {
       projectPath: process.cwd(),
       ...getSetupStatusTestOverrides(),
     });
-    const detected = /** @type {import('./mcp-config.js').McpClientName[]} */ (
+    const detected = /** @type {import('./types.js').McpClientName[]} */ (
       setupStatus.mcpClients.filter((entry) => entry.detected).map((entry) => entry.key)
     );
     const configuredClients = new Set(
       setupStatus.mcpClients.filter((entry) => entry.configured).map((entry) => entry.key)
     );
     const configuredClientList =
-      /** @type {import('./mcp-config.js').McpClientName[]} */ ([...configuredClients]);
+      /** @type {import('./types.js').McpClientName[]} */ ([...configuredClients]);
     const items = MCP_CLIENT_NAMES.map((c) => ({
       value: c,
       label: `${c.padEnd(10)}  ${MCP_CLIENT_LABELS[c]}`,
@@ -284,12 +301,12 @@ if (command === 'install-mcp') {
             ? detected
             : [...MCP_CLIENT_NAMES];
     } else {
-      clients = /** @type {import('./mcp-config.js').McpClientName[]} */ (selected);
+      clients = /** @type {import('./types.js').McpClientName[]} */ (selected);
     }
 
     if (selected !== null) {
       const deselectedClients =
-        /** @type {import('./mcp-config.js').McpClientName[]} */ (
+        /** @type {import('./types.js').McpClientName[]} */ (
           configuredClientList.filter((clientName) => !clients.includes(clientName))
         );
       const removableClients = await findConfiguredMcpClients({
@@ -470,15 +487,20 @@ async function main() {
     }
 
     if (command === 'batch') {
-      await ensureClientConnection();
       const input = rest[0];
       if (!input) {
         throw new Error('Usage: batch \'[{"method":"...","params":{...}}, ...]\'');
       }
-      const calls = JSON.parse(input);
+      let calls;
+      try {
+        calls = JSON.parse(input);
+      } catch {
+        throw new Error('Invalid JSON syntax. Expected a JSON array of bridge calls.');
+      }
       if (!Array.isArray(calls)) {
         throw new Error('Batch input must be a JSON array.');
       }
+      await ensureClientConnection();
       const results = await Promise.all(
         calls.map(async (call) => {
           if (!call || typeof call !== 'object' || typeof call.method !== 'string') {
@@ -847,10 +869,13 @@ async function uninstallBrowserBridge() {
  */
 async function parseCallCommand(args) {
   const parsed = extractTabFlag(args);
-  const [first, second] = parsed.rest;
+  const [first, second, ...extra] = parsed.rest;
   if (!first) {
     throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
   }
+  if (extra.length > 0) {
+    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  }
 
   if (first.includes('.')) {
     const method = /** @type {BridgeMethod} */ (first);

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

@@ -15,53 +15,16 @@ import {
   getBridgeTransport,
   getSocketPath,
 } from '../../native-host/src/config.js';
+import { normalizeBridgeAuthToken, readBridgeAuthToken } from '../../native-host/src/auth-token.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 
-/** @typedef {import('../../native-host/src/config.js').BridgeTransport} BridgeTransport */
-
-/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
-/** @typedef {import('../../protocol/src/types.js').BridgeMeta} BridgeMeta */
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-/**
- * @typedef {{
- *   extensionConnected?: boolean,
- *   supported_versions?: string[],
- *   daemon_supported_versions?: string[],
- *   deprecated_since?: string,
- *   migration_hint?: string
- * }} ProtocolHealthResult
- */
-
-/**
- * @typedef {{
- *   type: 'registered',
- *   role: 'agent' | 'extension',
- *   clientId?: string
- * } | {
- *   type: 'agent.response',
- *   response: BridgeResponse
- * }} ClientMessage
- */
-
-/**
- * @typedef {{
- *   resolve: (value: any) => void,
- *   reject: (error: Error) => void,
- *   timeoutId: NodeJS.Timeout
- * }} PendingRequest
- */
-
-/**
- * @typedef {{
- *   transport?: BridgeTransport,
- *   socketPath?: string,
- *   clientId?: string,
- *   defaultTimeoutMs?: number,
- *   autoReconnect?: boolean,
- *   restartDaemonOnVersionMismatch?: boolean,
- *   restartDaemonFn?: typeof restartBridgeDaemon,
- * }} BridgeClientOptions
- */
+/** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').BridgeResponse} BridgeResponse */
+/** @typedef {import('./types.js').BridgeClientOptions} BridgeClientOptions */
+/** @typedef {import('./types.js').ClientMessage} ClientMessage */
+/** @typedef {import('./types.js').PendingRequest} PendingRequest */
+/** @typedef {import('./types.js').ProtocolHealthResult} ProtocolHealthResult */
 
 /**
  * @param {string} left
@@ -94,6 +57,22 @@ function createTimeoutError(method, timeoutMs) {
   return error;
 }
 
+/**
+ * @param {net.Socket} socket
+ * @param {string} line
+ * @returns {Promise<void>}
+ */
+async function writeSocketLine(socket, line) {
+  if (!socket.write(line)) {
+    await Promise.race([
+      once(socket, 'drain'),
+      once(socket, 'close').then(() => {
+        throw new Error('Bridge socket closed while writing.');
+      }),
+    ]);
+  }
+}
+
 export class BridgeClient extends EventEmitter {
   /**
    * @param {BridgeClientOptions} [options={}]
@@ -106,6 +85,7 @@ export class BridgeClient extends EventEmitter {
     autoReconnect = false,
     restartDaemonOnVersionMismatch = true,
     restartDaemonFn = restartBridgeDaemon,
+    authToken = undefined,
   } = {}) {
     super();
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
@@ -116,6 +96,7 @@ export class BridgeClient extends EventEmitter {
     this.autoReconnect = autoReconnect;
     this.restartDaemonOnVersionMismatch = restartDaemonOnVersionMismatch;
     this.restartDaemonFn = restartDaemonFn;
+    this.authToken = authToken;
     this.socket = null;
     this.connected = false;
     this.protocolCompatibility = null;
@@ -149,6 +130,18 @@ export class BridgeClient extends EventEmitter {
       throw error;
     }
 
+    const registrationPromise = new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.waiting.delete('registered');
+        reject(createTimeoutError('register', this.defaultTimeoutMs));
+      }, this.defaultTimeoutMs);
+      this.waiting.set('registered', {
+        resolve,
+        reject,
+        timeoutId,
+      });
+    });
+
     parseJsonLines(socket, (raw) => {
       const message = /** @type {ClientMessage} */ (raw);
       if (message.type === 'registered') {
@@ -162,6 +155,16 @@ export class BridgeClient extends EventEmitter {
         return;
       }
 
+      if (message.type === 'registration_failed') {
+        const pending = this.waiting.get('registered');
+        if (pending) {
+          this.waiting.delete('registered');
+          clearTimeout(pending.timeoutId);
+          pending.reject(new Error(message.error?.message || 'Bridge daemon registration failed.'));
+        }
+        return;
+      }
+
       if (message.type === 'agent.response') {
         const pending = this.waiting.get(message.response.id);
         if (pending) {
@@ -186,20 +189,31 @@ export class BridgeClient extends EventEmitter {
       // 'close' fires after 'error'; reconnect is triggered there.
     });
 
-    this.socket.write(
-      `${JSON.stringify({ type: 'register', role: 'agent', clientId: this.clientId })}\n`
-    );
-    await new Promise((resolve, reject) => {
-      const timeoutId = setTimeout(() => {
+    const authToken =
+      this.authToken === undefined
+        ? this.transport.type === 'tcp'
+          ? await readBridgeAuthToken()
+          : null
+        : normalizeBridgeAuthToken(this.authToken);
+    try {
+      await writeSocketLine(
+        socket,
+        `${JSON.stringify({
+          type: 'register',
+          role: 'agent',
+          clientId: this.clientId,
+          ...(authToken ? { authToken } : {}),
+        })}\n`
+      );
+    } catch (error) {
+      const pending = this.waiting.get('registered');
+      if (pending) {
+        clearTimeout(pending.timeoutId);
         this.waiting.delete('registered');
-        reject(createTimeoutError('register', this.defaultTimeoutMs));
-      }, this.defaultTimeoutMs);
-      this.waiting.set('registered', {
-        resolve,
-        reject,
-        timeoutId,
-      });
-    });
+      }
+      throw error;
+    }
+    await registrationPromise;
 
     this.protocolCompatibility = null;
     this.protocolWarning = null;
@@ -282,13 +296,15 @@ export class BridgeClient extends EventEmitter {
       });
     });
 
-    if (!this.socket.write(`${JSON.stringify({ type: 'agent.request', request })}\n`)) {
-      await Promise.race([
-        once(this.socket, 'drain'),
-        once(this.socket, 'close').then(() => {
-          throw new Error('Bridge socket closed while writing.');
-        }),
-      ]);
+    try {
+      await writeSocketLine(this.socket, `${JSON.stringify({ type: 'agent.request', request })}\n`);
+    } catch (error) {
+      const pending = this.waiting.get(request.id);
+      if (pending) {
+        clearTimeout(pending.timeoutId);
+        this.waiting.delete(request.id);
+      }
+      throw error;
     }
     const response = /** @type {BridgeResponse} */ (await responsePromise);
     return this.attachProtocolWarning(response);

package/packages/agent-client/src/command-registry.js

@@ -3,18 +3,8 @@
 import { BRIDGE_METHOD_REGISTRY, BRIDGE_METHODS } from '../../protocol/src/index.js';
 import { parseCommaList, parseIntArg, parsePropertyAssignments } from './cli-helpers.js';
 
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-
-/**
- * @typedef {{
- *   method: BridgeMethod,
- *   resolve?: boolean,
- *   printMethod?: string,
- *   usage: string,
- *   description: string,
- *   build: (r: string[], ref?: string) => Record<string, unknown>
- * }} ShortcutCommand
- */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').ShortcutCommand} ShortcutCommand */
 
 /**
  * @param {BridgeMethod} method
@@ -247,11 +237,10 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Setup',
     lines: [
-      'bbx install [--browser chrome|edge|brave|chromium] [extension-id]  Install native messaging manifest',
+      'bbx install [extension-id] [--browser chrome|edge|brave|chromium|arc] [--all]  Install native messaging manifest',
       'bbx uninstall                                                      Remove native host manifests, Browser Bridge runtime files, and managed MCP/skill installs',
-      'bbx install [--all] [--browser <name>] [extension-id]              Install native host manifest (--all for all supported browsers)',
       'bbx install-skill [targets|all] [--global] [--project <path>]      Install/update the managed Browser Bridge CLI skill',
-      'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf',
+      'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf|agents',
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Diagnose install, daemon, extension, and access readiness',
       'bbx restart                                                        Restart the local Browser Bridge daemon',

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

@@ -4,9 +4,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-/** @typedef {import('./mcp-config.js').McpClientName} McpClientName */
-/** @typedef {import('./install.js').SupportedTarget} SupportedTarget */
-/** @typedef {() => boolean | Promise<boolean>} Detector */
+/** @typedef {import('./types.js').McpClientName} McpClientName */
+/** @typedef {import('./types.js').SupportedTarget} SupportedTarget */
+/** @typedef {import('./types.js').Detector} Detector */
 
 const home = os.homedir();
 const platform = process.platform;

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

@@ -41,9 +41,7 @@ const copilotBrowserBridgeNote = [
   '',
 ].join('\n');
 
-/**
- * @typedef {'codex' | 'claude' | 'cursor' | 'copilot' | 'opencode' | 'antigravity' | 'windsurf' | 'agents'} SupportedTarget
- */
+/** @typedef {import('./types.js').SupportedTarget} SupportedTarget */
 
 /** @type {SupportedTarget[]} */
 export const SUPPORTED_TARGETS = [...supportedTargets];
@@ -68,9 +66,7 @@ export function isSupportedTarget(value) {
   return supportedTargets.includes(/** @type {SupportedTarget} */ (value));
 }
 
-/**
- * @typedef {{targets: SupportedTarget[], projectPath: string, global: boolean}} InstallAgentOptions
- */
+/** @typedef {import('./types.js').InstallAgentOptions} InstallAgentOptions */
 
 /**
  * @param {string[]} args
@@ -202,7 +198,7 @@ async function rollbackInstalledSkillDirs(attempted) {
 /**
  * Write MCP config for the given clients.
  *
- * @param {import('./mcp-config.js').McpClientName[]} clients
+ * @param {import('./types.js').McpClientName[]} clients
  * @param {{
  *   global: boolean,
  *   projectPath: string,

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

@@ -5,9 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-/**
- * @typedef {'codex' | 'claude' | 'cursor' | 'copilot' | 'opencode' | 'antigravity' | 'windsurf' | 'agents'} McpClientName
- */
+/** @typedef {import('./types.js').McpClientName} McpClientName */
 
 /** @type {McpClientName[]} */
 export const MCP_CLIENT_NAMES = [
@@ -525,8 +523,13 @@ async function installJsonMcpConfig(clientName, configPath, stdout) {
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
       existing = parsed;
     }
-  } catch {
-    // File missing or unparseable - start fresh.
+  } catch (error) {
+    if (!isMissingFileError(error)) {
+      throw new Error(
+        `Cannot update ${configPath}: existing MCP config is not valid JSON. Fix or remove it first.`
+      );
+    }
+    // File missing - start fresh.
   }
 
   const shape = getMcpConfigShape(clientName);
@@ -663,3 +666,15 @@ export function parseInstalledMcpConfig(clientName, raw) {
     return { configured: false };
   }
 }
+
+/**
+ * @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/runtime.js

@@ -12,39 +12,14 @@ import { resolveDefaultExtensionId } from '../../native-host/src/install-manifes
 import { methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
 
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-/** @typedef {import('../../protocol/src/types.js').BridgeMeta} BridgeMeta */
-/** @typedef {import('../../protocol/src/types.js').BridgeRequestSource} BridgeRequestSource */
-/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
+/** @typedef {import('./types.js').BridgeRequestSource} BridgeRequestSource */
+/** @typedef {import('./types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('../../native-host/src/config.js').SupportedBrowser} SupportedBrowser */
-
-/**
- * @typedef {{
- *   browser: string,
- *   manifestPath: string,
- *   installed: boolean
- * }} BrowserManifestStatus
- */
-
-/**
- * @typedef {{
- *   manifestInstalled: boolean,
- *   manifestPath: string,
- *   allowedOrigins: string[],
- *   defaultExtensionId: string | null,
- *   defaultExtensionIdSource: string,
- *   daemonReachable: boolean,
- *   extensionConnected: boolean,
- *   accessEnabled: boolean,
- *   enabledWindowId: number | null,
- *   routeTabId: number | null,
- *   routeReady: boolean,
- *   routeReason: string,
- *   issues: string[],
- *   nextSteps: string[],
- *   browserManifests: BrowserManifestStatus[]
- * }} DoctorReport
- */
+/** @typedef {import('./types.js').BrowserManifestStatus} BrowserManifestStatus */
+/** @typedef {import('./types.js').DoctorReport} DoctorReport */
+/** @typedef {import('./types.js').DoctorReportOptions} DoctorReportOptions */
 
 /**
  * @param {BridgeClient} client
@@ -178,15 +153,6 @@ export async function checkBrowserManifests() {
   );
 }
 
-/**
- * @typedef {{
- *   loadManifest?: () => Promise<{allowed_origins?: string[]} | null>,
- *   manifestPath?: string,
- *   defaultExtensionIdInfo?: { extensionId: string | null, source: string },
- *   bridgeClientRunner?: <T>(callback: (client: BridgeClient) => Promise<T>) => Promise<T>
- * }} DoctorReportOptions
- */
-
 /**
  * @param {DoctorReportOptions} [options={}]
  * @returns {Promise<DoctorReport>}

package/packages/agent-client/src/setup-status.js

@@ -21,8 +21,8 @@ import {
   SUPPORTED_TARGETS,
 } from './install.js';
 
-/** @typedef {import('./mcp-config.js').McpClientName} McpClientName */
-/** @typedef {import('./install.js').SupportedTarget} SupportedTarget */
+/** @typedef {import('./types.js').McpClientName} McpClientName */
+/** @typedef {import('./types.js').SupportedTarget} SupportedTarget */
 /** @typedef {import('../../protocol/src/types.js').SetupStatus} SetupStatus */
 /** @typedef {import('../../protocol/src/types.js').McpClientStatus} McpClientStatus */
 /** @typedef {import('../../protocol/src/types.js').SkillTargetStatus} SkillTargetStatus */
@@ -52,17 +52,7 @@ const SKILL_TARGET_LABELS = {
   agents: 'Generic agents',
 };
 
-/**
- * @typedef {{
- *   global?: boolean,
- *   cwd?: string,
- *   projectPath?: string,
- *   mcpDetectors?: Record<string, () => boolean | Promise<boolean>>,
- *   skillDetectors?: Record<string, () => boolean | Promise<boolean>>,
- *   access?: (targetPath: string) => Promise<void>,
- *   readFile?: (targetPath: string, encoding: BufferEncoding) => Promise<string>
- * }} SetupStatusOptions
- */
+/** @typedef {import('./types.js').SetupStatusOptions} SetupStatusOptions */
 
 /**
  * Return Browser Bridge MCP and skill installation status for supported clients.