@browserbridge/bbx 1.12.1 → 1.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "private": false,
   "keywords": [
     "agent-tools",

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

@@ -6,7 +6,8 @@ import { methodNeedsTab, parseIntArg, parseJsonObject } from './cli-helpers.js';
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('../../protocol/src/defaults.js').BudgetPresetName} BudgetPresetName */
 
-const CALL_USAGE = 'Usage: call [--tab <tabId>] [--preset quick|normal|deep] <method> [paramsJson]';
+const CALL_USAGE =
+  'Usage: call [--extension <connectionId>] [--browser <name>] [--profile <label>] [--tab <tabId>] [--preset quick|normal|deep] <method> [paramsJson]';
 
 /**
  * Read all of stdin as UTF-8 text. Resolves once stdin closes.
@@ -149,10 +150,27 @@ export function extractPresetFlag(args) {
 
 /**
  * @param {string[]} args
- * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}
+ * @returns {Promise<import('../../protocol/src/types.js').BrowserTarget & { tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}
  */
 export async function parseCallCommand(args) {
-  const presetParsed = extractPresetFlag(args);
+  const remaining = [...args];
+  /** @type {import('../../protocol/src/types.js').BrowserTarget} */
+  const target = {};
+  /** @type {Array<[string, keyof import('../../protocol/src/types.js').BrowserTarget]>} */
+  const selectors = [
+    ['--extension', 'extensionId'],
+    ['--browser', 'targetBrowser'],
+    ['--profile', 'targetProfile'],
+  ];
+  for (const [flag, field] of selectors) {
+    const index = remaining.indexOf(flag);
+    if (index === -1) continue;
+    const value = remaining[index + 1];
+    if (!value?.trim() || value.startsWith('--')) throw new Error(`${flag} requires a value.`);
+    target[field] = value;
+    remaining.splice(index, 2);
+  }
+  const presetParsed = extractPresetFlag(remaining);
   const parsed = extractTabFlag(presetParsed.rest);
   const [first, second, ...extra] = parsed.rest;
   if (!first) {
@@ -173,6 +191,7 @@ export async function parseCallCommand(args) {
       rawParams = await readStdin();
     }
     return {
+      ...target,
       method,
       tabId: methodNeedsTab(method) ? parsed.tabId : null,
       params: applyMethodBudgetPreset(method, parseJsonObject(rawParams), presetParsed.preset),

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

@@ -33,7 +33,7 @@ import { requestBridge } from './runtime.js';
  */
 
 /**
- * @typedef {{ method: BridgeMethod, params: Record<string, unknown>, tabId: number | null }} PreparedBatchCall
+ * @typedef {import('../../protocol/src/types.js').BrowserTarget & { method: BridgeMethod, params: Record<string, unknown>, tabId: number | null }} PreparedBatchCall
  */
 
 /**
@@ -107,10 +107,11 @@ export async function runBatchCalls(client, input, source, options = {}) {
   const validPrepared = /** @type {Array<{ value: PreparedBatchCall }>} */ (prepared);
   if (!client.connected) await client.connect();
   return mapWithConcurrency(validPrepared, MAX_BATCH_CONCURRENCY, async (item) => {
-    const { method, params, tabId } = item.value;
+    const { method, params, tabId, ...target } = item.value;
     const startTime = Date.now();
     try {
       const response = await requestBridge(client, method, params, {
+        ...target,
         tabId,
         source,
       });
@@ -150,6 +151,16 @@ function prepareBatchCall(call, preset) {
     };
   }
   const method = /** @type {BridgeMethod} */ (batchCall.method);
+  /** @type {import('../../protocol/src/types.js').BrowserTarget} */
+  const target = {};
+  for (const field of /** @type {const} */ (['extensionId', 'targetBrowser', 'targetProfile'])) {
+    const value = batchCall[field];
+    if (value === undefined) continue;
+    if (typeof value !== 'string' || !value.trim()) {
+      return { error: invalidBatchItem(method, `${field} must be a non-empty string.`) };
+    }
+    target[field] = value;
+  }
   if (method === 'sensitive.read') {
     return {
       error: invalidBatchItem(
@@ -182,7 +193,7 @@ function prepareBatchCall(call, preset) {
     batchCall.tabId > 0
       ? batchCall.tabId
       : null;
-  return { value: { method, params: mergedParams, tabId } };
+  return { value: { ...target, method, params: mergedParams, tabId } };
 }
 
 /**

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

@@ -393,8 +393,9 @@ async function main() {
     }
 
     if (command === 'call') {
-      const { tabId, method, params } = await parseCallCommand(rest);
+      const { tabId, method, params, ...target } = await parseCallCommand(rest);
       const response = await requestBridge(client, method, params, {
+        ...target,
         tabId,
         source: REQUEST_SOURCE,
       });
@@ -413,8 +414,9 @@ async function main() {
     }
 
     if (command.includes('.') && METHODS.includes(/** @type {BridgeMethod} */ (command))) {
-      const { tabId, method, params } = await parseCallCommand([command, ...rest]);
+      const { tabId, method, params, ...target } = await parseCallCommand([command, ...rest]);
       const response = await requestBridge(client, method, params, {
+        ...target,
         tabId,
         source: REQUEST_SOURCE,
       });

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

@@ -294,7 +294,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Generic RPC',
     lines: [
-      'bbx call [--tab <tabId>] [--preset quick|normal|deep] <method> [paramsJson|-]  Call any bridge method (- reads JSON from stdin)',
+      'bbx call [--extension <connectionId>] [--browser <name>] [--profile <label>] [--tab <tabId>] [--preset quick|normal|deep] <method> [paramsJson|-]  Call any bridge method (- reads JSON from stdin)',
       'bbx <method> [--tab <tabId>] [paramsJson|-]                        Direct alias for exact bridge methods such as page.get_state',
       "bbx batch [--preset quick|normal|deep] '[{method,params,tabId?},...]'  Up to 20 parallel read-only calls",
       '--preset fills budget gaps (maxNodes, maxDepth, textBudget, limit) from the shared quick|normal|deep presets; explicit params always win.',

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

@@ -107,7 +107,7 @@ export async function ensureClientConnected(client) {
  * @param {BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} [params={}]
- * @param {{ tabId?: number | null, source?: BridgeRequestSource, mcpEra?: import('./types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
+ * @param {import('../../protocol/src/types.js').BrowserTarget & { tabId?: number | null, source?: BridgeRequestSource, mcpEra?: import('./types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridge(client, method, params = {}, options = {}) {
@@ -128,12 +128,17 @@ export async function requestBridge(client, method, params = {}, options = {}) {
     method,
     params,
     tabId: methodNeedsTab(method) ? (options.tabId ?? null) : null,
-    meta: withRequestMeta(
-      options.source,
-      options.mcpEra,
-      options.tokenBudget,
-      options.automaticRetry
-    ),
+    meta: {
+      ...withRequestMeta(
+        options.source,
+        options.mcpEra,
+        options.tokenBudget,
+        options.automaticRetry
+      ),
+      ...(options.extensionId !== undefined ? { target_extension: options.extensionId } : {}),
+      ...(options.targetBrowser !== undefined ? { target_browser: options.targetBrowser } : {}),
+      ...(options.targetProfile !== undefined ? { target_profile: options.targetProfile } : {}),
+    },
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
   });
 }

package/packages/mcp-server/src/guidance.js

@@ -7,7 +7,8 @@
  */
 const SHARED_INSTRUCTIONS = Object.freeze([
   'Prefer Browser Bridge MCP tools over shelling out to bbx. Use bbx only for explicit CLI setup, doctor, logs, or raw debugging requests.',
-  'Start with browser_call method health.ping. If window access is disabled, call browser_call method access.request once, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once.',
+  'Start with browser_call method health.ping. Its access status describes only the routed profile, not every window. Use connectedExtensions or unscoped tabs.list to discover profiles and existing tabs. Reuse the selected extensionId, destinationId when remote, and tabId on every follow-up call, including each browser_batch item. tabId alone does not select a profile. Never disable unrelated windows to fix routing. If a connection disappears, rediscover it instead of switching profiles or using guessed IDs.',
+  "If the selected profile has window access disabled, call browser_call method access.request once with its extensionId, ask the user to click Enable in that profile's Browser Bridge popup or side panel, then retry once with the same target. Restricted pages and ambiguous_browser_target are routing problems, not evidence that every window needs enabling.",
   'Use structured reads first through browser_call: page.get_state, dom.query, page.get_text, page.extract_content, styles.get_computed, or layout.get_box_model. Prefer semantic extraction for articles and documentation. Use browser_batch only for parallel reads; run mutations sequentially and keep limits tight before widening.',
   'Reuse elementRef values returned by DOM reads. Use attribute allowlists for focused DOM reads.',
   'Escalate to screenshot.capture_element, screenshot.capture_region, dom.get_accessibility_tree, page.evaluate, viewport.resize, or CDP only when structured reads cannot answer the question.',

package/packages/mcp-server/src/handlers-navigation.js

@@ -5,6 +5,7 @@ import {
   createToolResult,
   getBridgeDestinations,
   getToolTokenBudget,
+  hasMcpBrowserTarget,
   requestBridgeWithRetry,
   summarizeToolError,
   withMcpRequestClient,
@@ -19,7 +20,7 @@ import {
  */
 export async function handleTabsTool(args) {
   if (args.action === 'list') {
-    if (typeof args.destinationId === 'string') {
+    if (typeof args.destinationId === 'string' || hasMcpBrowserTarget()) {
       return callBridgeTool('tabs.list', {}, { destinationId: args.destinationId });
     }
     const destinations = await getBridgeDestinations();
@@ -51,10 +52,14 @@ export async function handleTabsTool(args) {
               tabs: [],
             };
           }
-          const result = /** @type {{ tabs?: Array<Record<string, unknown>> }} */ (response.result);
+          const result =
+            /** @type {{ tabs?: Array<Record<string, unknown>>, profiles?: unknown[], partial?: boolean }} */ (
+              response.result
+            );
           return {
             destinationId: destination.id,
-            ok: true,
+            ok: result.partial !== true,
+            ...(result.profiles ? { profiles: result.profiles } : {}),
             tabs: (result.tabs ?? []).map((tab) => ({ destinationId: destination.id, ...tab })),
           };
         } catch (error) {
@@ -78,7 +83,7 @@ export async function handleTabsTool(args) {
         tabs,
         destinations: results,
       },
-      failures.length === results.length
+      failures.length === results.length && tabs.length === 0
     );
   }
   if (args.action === 'create') {

package/packages/mcp-server/src/handlers-page.js

@@ -347,7 +347,7 @@ export async function handleSensitiveReadTool(args) {
 }
 
 /**
- * @param {{ calls?: Array<{ method?: string, params?: Record<string, unknown>, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }> }} args
+ * @param {{ calls?: Array<import('../../protocol/src/types.js').BrowserTarget & { method?: string, params?: Record<string, unknown>, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }> }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleBatchTool(args) {
@@ -393,6 +393,9 @@ export async function handleBatchTool(args) {
       response = await withMcpRequestClient(
         (client) =>
           requestBridgeWithRetry(client, method, params, {
+            ...(call.extensionId ? { extensionId: call.extensionId } : {}),
+            ...(call.targetBrowser ? { targetBrowser: call.targetBrowser } : {}),
+            ...(call.targetProfile ? { targetProfile: call.targetProfile } : {}),
             tabId,
             source: REQUEST_SOURCE,
             tokenBudget,
@@ -405,15 +408,25 @@ export async function handleBatchTool(args) {
     if (callError || !response) {
       return {
         destinationId,
+        ...(call.extensionId ? { extensionId: call.extensionId } : {}),
         ...summarizeThrownBatchError(method, tabId, callError, Date.now() - startTime),
       };
     }
+    const discovery = method === 'tabs.list' ? summarizeToolResponse(response, method) : null;
     return {
       destinationId,
+      ...(call.extensionId ? { extensionId: call.extensionId } : {}),
       ...summarizeBatchResponseItem(
         { method, tabId, response, durationMs: Date.now() - startTime },
         { compact: true }
       ),
+      ...(discovery
+        ? {
+            summary: discovery.content[0].text,
+            evidence: discovery.structuredContent.evidence,
+            ...(discovery.structuredContent.outputTruncated ? { outputTruncated: true } : {}),
+          }
+        : {}),
     };
   });
 

package/packages/mcp-server/src/handlers-utils.js

@@ -5,6 +5,8 @@ import { randomUUID } from 'node:crypto';
 
 import {
   BridgeError,
+  createSuccess,
+  createFailure,
   bridgeMethodNeedsTab,
   DEFAULT_CONSOLE_LIMIT,
   DEFAULT_LOG_TAIL_LIMIT,
@@ -51,6 +53,33 @@ const MCP_CLIENT_ID = `mcp_${randomUUID()}`;
 const MCP_AGENT_SESSION = process.env.BBX_SESSION?.trim() || MCP_CLIENT_ID;
 /** @type {AsyncLocalStorage<{ era: import('../../protocol/src/types.js').McpProtocolEra, signal?: AbortSignal }>} */
 const MCP_REQUEST_ERA = new AsyncLocalStorage();
+/** @type {AsyncLocalStorage<import('../../protocol/src/types.js').BrowserTarget>} */
+const MCP_REQUEST_TARGET = new AsyncLocalStorage();
+
+/**
+ * Scope routing to one tool invocation, including selector resolution and retries.
+ * @template T
+ * @param {unknown} args
+ * @param {() => T} callback
+ * @returns {T}
+ */
+export function runWithMcpRequestTarget(args, callback) {
+  const record =
+    args && typeof args === 'object' ? /** @type {Record<string, unknown>} */ (args) : {};
+  const target = {
+    ...(MCP_REQUEST_TARGET.getStore() ?? {}),
+    ...(typeof record.extensionId === 'string' ? { extensionId: record.extensionId } : {}),
+    ...(typeof record.targetBrowser === 'string' ? { targetBrowser: record.targetBrowser } : {}),
+    ...(typeof record.targetProfile === 'string' ? { targetProfile: record.targetProfile } : {}),
+  };
+  return MCP_REQUEST_TARGET.run(target, callback);
+}
+
+/** @returns {boolean} */
+export function hasMcpBrowserTarget() {
+  const target = MCP_REQUEST_TARGET.getStore();
+  return Boolean(target?.extensionId || target?.targetBrowser || target?.targetProfile);
+}
 
 /**
  * @template T
@@ -275,6 +304,16 @@ export function summarizeToolResponse(response, method, params = {}) {
   const summary = annotateBridgeSummary(summarizeBridgeResponse(response, method), response);
   const summaryRecord = /** @type {Record<string, unknown>} */ (summary);
   if (response.ok) {
+    if (
+      method === 'tabs.list' &&
+      response.result &&
+      typeof response.result === 'object' &&
+      'partial' in response.result &&
+      response.result.partial === true
+    ) {
+      summary.summary +=
+        ' Some browser profiles could not be listed; inspect evidence.profiles before assuming a tab is absent.';
+    }
     const evidence = getRequestAwareEvidence(response.result, method, params, summary.evidence);
     summary.evidence = evidence.value;
     if (evidence.metadata) summaryRecord.evidenceMeta = evidence.metadata;
@@ -505,6 +544,35 @@ function getRequestAwareEvidence(rawResult, method, params, fallback) {
     rawResult && typeof rawResult === 'object' && !Array.isArray(rawResult)
       ? /** @type {Record<string, unknown>} */ (rawResult)
       : {};
+  if (method === 'tabs.list' && Array.isArray(result.tabs)) {
+    const tabs = /** @type {unknown[]} */ (result.tabs)
+      .filter((tab) => tab && typeof tab === 'object' && !Array.isArray(tab))
+      .map((tab) => /** @type {Record<string, unknown>} */ (tab))
+      .sort(
+        (left, right) =>
+          Number(right.working === true || right.active === true) -
+          Number(left.working === true || left.active === true)
+      )
+      .map((tab) => ({
+        ...(typeof tab.extensionId === 'string' ? { extensionId: tab.extensionId } : {}),
+        tabId: tab.tabId,
+        windowId: tab.windowId,
+        active: tab.active,
+        ...(tab.working === true ? { working: true } : {}),
+        ...(tab.browserName !== undefined ? { browserName: tab.browserName } : {}),
+        ...(tab.profileLabel !== undefined ? { profileLabel: tab.profileLabel } : {}),
+        title: typeof tab.title === 'string' ? tab.title.slice(0, 200) : tab.title,
+        origin: tab.origin,
+        ...(typeof tab.url === 'string'
+          ? { url: tab.url.slice(0, 512), ...(tab.url.length > 512 ? { urlTruncated: true } : {}) }
+          : {}),
+      }));
+    const metadata = Object.fromEntries(Object.entries(result).filter(([key]) => key !== 'tabs'));
+    return boundToolValue(
+      { tabCount: tabs.length, ...metadata, tabs },
+      { maxEntries: 2000, maxCharacters: 30_000, maxStringLength: 1000 }
+    );
+  }
   if (method === 'page.extract_content' && typeof result.content === 'string') {
     const requested = positiveInteger(params.textBudget) ?? DEFAULT_PAGE_TEXT_BUDGET;
     const maxCharacters = Math.min(requested, 16_000);
@@ -757,14 +825,24 @@ export async function waitForClientReconnect(client, timeoutMs = RECONNECT_WAIT_
  * @param {import('../../agent-client/src/client.js').BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} params
- * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, mcpEra?: import('../../protocol/src/types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} options
+ * @param {import('../../protocol/src/types.js').BrowserTarget & { tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, mcpEra?: import('../../protocol/src/types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt', skipProfileDiscovery?: boolean }} options
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridgeWithRetry(client, method, params, options) {
   const requestOptions = {
+    ...(MCP_REQUEST_TARGET.getStore() ?? {}),
     ...options,
     mcpEra: options.mcpEra ?? MCP_REQUEST_ERA.getStore()?.era,
   };
+  if (
+    method === 'tabs.list' &&
+    !options.skipProfileDiscovery &&
+    !requestOptions.extensionId &&
+    !requestOptions.targetBrowser &&
+    !requestOptions.targetProfile
+  ) {
+    return listBrowserProfileTabs(client, params, requestOptions);
+  }
   /** @param {typeof requestOptions} attemptOptions */
   const attempt = (attemptOptions) =>
     awaitMcpOperation(async () => {
@@ -811,6 +889,102 @@ export async function requestBridgeWithRetry(client, method, params, options) {
   return response;
 }
 
+/**
+ * Discover only enabled profiles. Reading tabs never chooses a working tab.
+ * @param {import('../../agent-client/src/client.js').BridgeClient} client
+ * @param {Record<string, unknown>} params
+ * @param {Parameters<typeof requestBridgeWithRetry>[3]} options
+ * @returns {Promise<BridgeResponse>}
+ */
+async function listBrowserProfileTabs(client, params, options) {
+  const health = await requestBridgeWithRetry(client, 'health.ping', {}, options);
+  if (!health.ok) return health;
+  const result =
+    health.result && typeof health.result === 'object'
+      ? /** @type {Record<string, unknown>} */ (health.result)
+      : {};
+  const profiles = Array.isArray(result.connectedExtensions)
+    ? /** @type {unknown[]} */ (result.connectedExtensions)
+        .filter((value) => value && typeof value === 'object' && !Array.isArray(value))
+        .map((value) => /** @type {Record<string, unknown>} */ (value))
+        .filter((value) => typeof value.extensionId === 'string' && value.accessEnabled === true)
+        .map((value) => /** @type {Record<string, unknown> & { extensionId: string }} */ (value))
+    : [];
+  // Older daemons and a disabled single profile keep the usual access response.
+  if (
+    profiles.length === 0 &&
+    (!Array.isArray(result.connectedExtensions) || result.connectedExtensions.length <= 1)
+  ) {
+    return requestBridgeWithRetry(client, 'tabs.list', params, {
+      ...options,
+      skipProfileDiscovery: true,
+    });
+  }
+  if (profiles.length === 0) {
+    return createFailure(
+      health.id,
+      'ACCESS_DENIED',
+      'No connected profile has an enabled window. Select an extensionId from connectedExtensions and request access only for that profile.',
+      {
+        reason: 'no_enabled_browser_profiles',
+        connectedExtensions: result.connectedExtensions,
+      },
+      { method: 'tabs.list' }
+    );
+  }
+  const results = [];
+  for (const profile of profiles) {
+    /** @type {BridgeResponse} */
+    let response;
+    try {
+      response = await requestBridgeWithRetry(client, 'tabs.list', params, {
+        ...options,
+        extensionId: profile.extensionId,
+      });
+    } catch (error) {
+      throwIfMcpRequestCancelled();
+      response = createFailure(
+        health.id,
+        error instanceof BridgeError ? error.code : 'INTERNAL_ERROR',
+        error instanceof Error ? error.message : String(error),
+        null,
+        { method: 'tabs.list' }
+      );
+    }
+    const listed =
+      response.ok && response.result && typeof response.result === 'object'
+        ? /** @type {Record<string, unknown>} */ (response.result)
+        : {};
+    results.push({
+      extensionId: profile.extensionId,
+      browserName: profile.browserName ?? null,
+      profileLabel: profile.profileLabel ?? null,
+      ok: response.ok,
+      ...(response.ok ? {} : { error: response.error }),
+      tabs: Array.isArray(listed.tabs)
+        ? /** @type {unknown[]} */ (listed.tabs)
+            .filter((tab) => tab && typeof tab === 'object' && !Array.isArray(tab))
+            .map((tab) => ({
+              .../** @type {Record<string, unknown>} */ (tab),
+              extensionId: profile.extensionId,
+              browserName: profile.browserName ?? null,
+              profileLabel: profile.profileLabel ?? null,
+            }))
+        : [],
+    });
+  }
+  return createSuccess(
+    health.id,
+    {
+      tabs: results.flatMap((profile) => profile.tabs),
+      profiles: results.map(({ tabs, ...profile }) => ({ ...profile, tabCount: tabs.length })),
+      connectedExtensions: result.connectedExtensions,
+      partial: results.some((profile) => !profile.ok),
+    },
+    { method: 'tabs.list' }
+  );
+}
+
 /**
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} [params={}]

package/packages/mcp-server/src/handlers.js

@@ -16,6 +16,7 @@ import {
   summarizeToolResponse,
   withToolClient,
   REQUEST_SOURCE,
+  hasMcpBrowserTarget,
 } from './handlers-utils.js';
 
 export {
@@ -81,6 +82,9 @@ const HOME_DIR = os.homedir();
  */
 export async function handleStatusTool(args = {}) {
   try {
+    if (hasMcpBrowserTarget()) {
+      return callBridgeTool('health.ping', {}, { destinationId: args.destinationId });
+    }
     const requestedDestinationId =
       typeof args.destinationId === 'string' ? args.destinationId : null;
     if (requestedDestinationId && requestedDestinationId !== 'local') {
@@ -172,7 +176,7 @@ async function callRemoteHealth(destinationId) {
  */
 export async function handleSkillTool(args = {}) {
   try {
-    if (typeof args.destinationId === 'string') {
+    if (typeof args.destinationId === 'string' || hasMcpBrowserTarget()) {
       return callBridgeTool('skill.get_runtime_context', {}, { destinationId: args.destinationId });
     }
     const ctx = createRuntimeContext();

package/packages/mcp-server/src/server.js

@@ -54,13 +54,44 @@ import {
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { getMcpServerInstructions } from './guidance.js';
 import { isToolEnabledForEra, LOADABLE_TOOLSET_TOOLS } from './toolset.js';
+import { runWithMcpRequestTarget } from './handlers-utils.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
-  'Target a specific tab instead of the active tab in the enabled window.';
+  'Tab ID within the selected browser profile. With multiple profiles, also pass extensionId from tabs.list or health.ping.';
 export const DESTINATION_ID_DESCRIPTION =
   'Optional Browser Bridge destination ID from browser_status/browser_tabs; omit for local.';
 
+const BROWSER_TARGET_SCHEMA = {
+  extensionId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .optional()
+    .describe(
+      'Exact browser connection ID from health.ping connectedExtensions or tabs.list. Reuse with tabId on every call; IDs are scoped to destinationId and change on reconnect.'
+    ),
+  targetBrowser: z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .optional()
+    .describe(
+      'Browser name from health.ping connectedExtensions. Prefer extensionId when names are ambiguous.'
+    ),
+  targetProfile: z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .optional()
+    .describe(
+      'Profile label from health.ping connectedExtensions. Prefer extensionId when labels are missing or duplicated.'
+    ),
+};
+
 const MCP_SERVER_VERSION = loadPackageVersion();
 
 /**
@@ -173,9 +204,24 @@ export function createBridgeMcpServer(options = {}) {
   const registerTool = (name, config, handler) => {
     const wrappedHandler = /** @type {typeof handler} */ (
       (args, context) =>
-        runWithMcpRequestEra(era, () => handler(args, context), context.mcpReq.signal)
+        runWithMcpRequestEra(
+          era,
+          () => runWithMcpRequestTarget(args, () => handler(args, context)),
+          context.mcpReq.signal
+        )
     );
-    const registration = server.registerTool(name, config, wrappedHandler);
+    const routedConfig =
+      name === 'browser_setup' || name === 'browser_toolset'
+        ? config
+        : {
+            ...config,
+            // Added optional routing fields are consumed by the wrapper; handlers keep
+            // their original, SDK-checked argument contracts.
+            inputSchema: /** @type {InputSchema} */ (
+              /** @type {unknown} */ (config.inputSchema.extend(BROWSER_TARGET_SCHEMA))
+            ),
+          };
+    const registration = server.registerTool(name, routedConfig, wrappedHandler);
     registrations.set(name, registration);
     if (!isToolEnabledForEra(name, era)) {
       registration.disable();
@@ -257,7 +303,7 @@ export function createBridgeMcpServer(options = {}) {
     {
       title: 'Browser Tabs',
       description:
-        'List, create, close, or activate browser tabs. List without destinationId aggregates configured destinations; other actions default to local. Only create a page when the user explicitly requests it.',
+        "List, create, close, or activate browser tabs. Unscoped list discovers tabs across enabled browser profiles and configured destinations. Reuse each tab's extensionId, destinationId, and tabId for subsequent calls. Other actions default to local. Only create a page when the user explicitly requests it.",
       inputSchema: z.object({
         action: z
           .enum(['list', 'create', 'close', 'activate'])
@@ -1051,6 +1097,7 @@ export function createBridgeMcpServer(options = {}) {
                 .describe('Method params for this call'),
               tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
               destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+              ...BROWSER_TARGET_SCHEMA,
               budgetPreset: z
                 .enum(['quick', 'normal', 'deep'])
                 .optional()

package/packages/native-host/src/daemon.js

@@ -1282,7 +1282,9 @@ export class BridgeDaemon {
       typeof request.meta?.target_browser === 'string' ? request.meta.target_browser : null;
     const targetProfile =
       typeof request.meta?.target_profile === 'string' ? request.meta.target_profile : null;
-    const hasExplicitTarget = Boolean(targetBrowser || targetProfile);
+    const targetExtension =
+      typeof request.meta?.target_extension === 'string' ? request.meta.target_extension : null;
+    const hasExplicitTarget = Boolean(targetBrowser || targetProfile || targetExtension);
 
     const ownerPendingCount = this.pendingRequestsByOwnerSocket.get(socket)?.size ?? 0;
     if (
@@ -1311,13 +1313,42 @@ export class BridgeDaemon {
       request.method === 'dom.baseline.describe' ||
       request.method === 'dom.baseline.release';
     const baselineOwner = usesBaselineOwner ? this.domBaselines.get(baselineId ?? '') : null;
+    const candidates = [...this.extensionSockets.entries()].filter(
+      ([id, extension]) =>
+        (!targetExtension || id === targetExtension) &&
+        (!targetBrowser || extension.__browserName === targetBrowser) &&
+        (!targetProfile || extension.__profileLabel === targetProfile)
+    );
+    if (
+      !usesBaselineOwner &&
+      candidates.length > 1 &&
+      request.method !== 'health.ping' &&
+      request.method !== 'skill.get_runtime_context'
+    ) {
+      await writeJsonLine(socket, {
+        type: 'agent.response',
+        response: createFailure(
+          request.id,
+          ERROR_CODES.TAB_MISMATCH,
+          'Multiple browser profiles match this call. Select a connection with extensionId in MCP or meta.target_extension in raw requests, then list its tabs. A tabId alone does not select a profile. Do not disable other windows.',
+          {
+            reason: 'ambiguous_browser_target',
+            connectedExtensions: this.getConnectedExtensionsSnapshot(),
+          },
+          { method: request.method }
+        ),
+      });
+      this.recordDaemonRequestOutcome(request, false);
+      return;
+    }
     const target = usesBaselineOwner
       ? baselineOwner &&
+        (!targetExtension || this.extensionSockets.get(targetExtension) === baselineOwner) &&
         (!targetBrowser || baselineOwner.__browserName === targetBrowser) &&
         (!targetProfile || baselineOwner.__profileLabel === targetProfile)
         ? baselineOwner
         : null
-      : this.selectExtensionTarget(targetBrowser, targetProfile);
+      : this.selectExtensionTarget(targetBrowser, targetProfile, targetExtension);
 
     if (!target) {
       if (usesBaselineOwner) {
@@ -1339,9 +1370,12 @@ export class BridgeDaemon {
         request.id,
         ERROR_CODES.EXTENSION_DISCONNECTED,
         hasExplicitTarget
-          ? `No connected extension matches target_browser="${targetBrowser ?? '*'}" target_profile="${targetProfile ?? '*'}".`
+          ? `No connected extension matches target_browser="${targetBrowser ?? '*'}" target_profile="${targetProfile ?? '*'}" target_extension="${targetExtension ?? '*'}".`
           : 'The Chrome extension is not connected to the local bridge daemon.',
-        null,
+        {
+          reason: hasExplicitTarget ? 'browser_target_disconnected' : 'extension_disconnected',
+          connectedExtensions: this.getConnectedExtensionsSnapshot(),
+        },
         { method: request.method }
       );
       await writeJsonLine(socket, { type: 'agent.response', response });
@@ -1418,11 +1452,13 @@ export class BridgeDaemon {
    *
    * @param {string | null} targetBrowser
    * @param {string | null} targetProfile
+   * @param {string | null} [targetExtension]
    * @returns {ClientSocket | null}
    */
-  selectExtensionTarget(targetBrowser, targetProfile) {
-    const candidates = Array.from(this.extensionSockets.entries()).filter(([, extSocket]) => {
+  selectExtensionTarget(targetBrowser, targetProfile, targetExtension = null) {
+    const candidates = Array.from(this.extensionSockets.entries()).filter(([id, extSocket]) => {
       return (
+        (!targetExtension || id === targetExtension) &&
         (!targetBrowser || extSocket.__browserName === targetBrowser) &&
         (!targetProfile || extSocket.__profileLabel === targetProfile)
       );

package/packages/protocol/src/protocol.js

@@ -296,7 +296,7 @@ export function createSuccess(id, result, meta = {}) {
  * @returns {BridgeFailureResponse}
  */
 export function createFailure(id, code, message, details = null, meta = {}) {
-  const recovery = getErrorRecovery(code);
+  const recovery = getRoutingRecovery(code, details) ?? getErrorRecovery(code);
   const effectiveRecovery =
     recovery && meta.method === 'sensitive.read'
       ? {
@@ -322,6 +322,35 @@ export function createFailure(id, code, message, details = null, meta = {}) {
   };
 }
 
+/**
+ * Routing errors need selection guidance, not closed-tab or global enable hints.
+ * @param {import('./types.js').ErrorCode} code
+ * @param {unknown} details
+ * @returns {import('./types.js').BridgeRecovery | null}
+ */
+function getRoutingRecovery(code, details) {
+  const reason =
+    details && typeof details === 'object' && 'reason' in details ? details.reason : null;
+  if (
+    (code === ERROR_CODES.TAB_MISMATCH && reason === 'ambiguous_browser_target') ||
+    (code === ERROR_CODES.EXTENSION_DISCONNECTED && reason === 'browser_target_disconnected')
+  ) {
+    return {
+      retry: false,
+      alternativeMethod: 'health.ping',
+      hint: 'Discover connectedExtensions with health.ping or list enabled profiles with MCP tabs.list. Select extensionId and tabId for the intended page. Do not disable unrelated windows or fall back to another profile.',
+    };
+  }
+  if (code === ERROR_CODES.ACCESS_DENIED && reason === 'no_enabled_browser_profiles') {
+    return {
+      retry: false,
+      alternativeMethod: 'health.ping',
+      hint: "Choose the intended extensionId from connectedExtensions before requesting access. Ask the user to enable only that profile's window.",
+    };
+  }
+  return null;
+}
+
 /**
  * @param {unknown} request
  * @returns {BridgeRequest}
@@ -409,6 +438,7 @@ export function validateBridgeRequest(request) {
     params: normalizeRequestParams(method, params),
     meta: {
       ...meta,
+      ...normalizeBrowserTargetMeta(meta),
       protocol_version:
         typeof meta.protocol_version === 'string' ? meta.protocol_version : getProtocolVersion(),
       token_budget: typeof meta.token_budget === 'number' ? meta.token_budget : null,
@@ -424,6 +454,37 @@ export function validateBridgeRequest(request) {
   };
 }
 
+/**
+ * Never turn a malformed explicit selector into implicit routing.
+ * @param {Record<string, unknown>} meta
+ * @returns {Pick<BridgeMeta, 'target_extension' | 'target_browser' | 'target_profile'>}
+ */
+function normalizeBrowserTargetMeta(meta) {
+  /** @type {Pick<BridgeMeta, 'target_extension' | 'target_browser' | 'target_profile'>} */
+  const target = {};
+  for (const field of /** @type {const} */ ([
+    'target_extension',
+    'target_browser',
+    'target_profile',
+  ])) {
+    const value = meta[field];
+    if (value === undefined) continue;
+    if (
+      typeof value !== 'string' ||
+      !value.trim() ||
+      value.length > 256 ||
+      hasAsciiControlCharacters(value)
+    ) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `meta.${field} must be a non-empty string of at most 256 characters without control characters.`
+      );
+    }
+    target[field] = value.trim();
+  }
+  return target;
+}
+
 /** @param {string} value @returns {boolean} */
 function hasAsciiControlCharacters(value) {
   for (let index = 0; index < value.length; index += 1) {

package/packages/protocol/src/types.ts

@@ -144,7 +144,17 @@ export type BridgeMethod =
 
 export type CostClass = 'cheap' | 'moderate' | 'heavy' | 'extreme';
 
+/** Browser connection selectors, independent of the machine destination and tab. */
+export interface BrowserTarget {
+  extensionId?: string;
+  targetBrowser?: string;
+  targetProfile?: string;
+}
+
 export interface BridgeMeta {
+  target_extension?: string;
+  target_browser?: string;
+  target_profile?: string;
   protocol_version?: string;
   token_budget?: number | null;
   transport_bytes?: number;

package/skills/browser-bridge/SKILL.md

@@ -121,6 +121,26 @@ In MCP mode, pass `destinationId` on any browser tool call instead; `browser_sta
 
 Browser Bridge access is window-scoped. The user turns it on once for the current browser window in the popup or side panel.
 
+### Multiple windows and profiles
+
+Do not disable other windows or profiles to make routing work. `health.ping` returns `connectedExtensions`; its `access` status describes only the profile that answered. A restricted active tab there does not mean the requested page in another profile is unavailable.
+
+In MCP, an unscoped `tabs.list` discovers tabs across enabled profiles. Choose the requested page by URL/title, then pass its `extensionId` and `tabId` on every call, including each batch item. Include `destinationId` for a remote machine. `tabId` and element refs are profile-local, so neither identifies a browser profile by itself. `targetBrowser` and `targetProfile` also work when their names uniquely identify a connection; prefer `extensionId` when labels are absent or duplicated.
+
+Use the daemon connection's `extensionId`, not `browserExtensionId`, which identifies the installed Chrome extension and may be shared across profiles.
+
+```json
+{ "method": "page.get_state", "extensionId": "<connection ID from discovery>", "tabId": 123 }
+```
+
+CLI calls accept the same connection selector:
+
+```bash
+bbx call --extension '<connection ID from health.ping>' --tab 123 page.get_state '{}'
+```
+
+When multiple connections match, calls fail with `TAB_MISMATCH` and `reason: ambiguous_browser_target` before reading or changing any page. Choose a connection from the error's `connectedExtensions`, list its tabs, and retry with the exact target. Connection IDs change on reconnect; rediscover a missing connection rather than falling back to another profile. Ask the user to enable access only for the selected profile if it is disabled.
+
 To request access, call `access.request` (via `bbx access-request`, `browser_access` MCP tool, or `bbx call access.request`). This surfaces an Enable cue in the extension popup/side panel for the focused window.
 
 Do not call `access.request` repeatedly while the same window is still pending. If access is already requested, tell the user to enable that window and wait for them to confirm readiness.
@@ -154,7 +174,7 @@ After access is enabled:
 | `INPUT_FOCUS_CHANGED`     | No       | Inspect focus handlers; do not replay native text automatically                           |
 | `DIALOG_NOT_OPEN`         | No       | Trigger or inspect the dialog again                                                       |
 | `DIALOG_ACTION_CONFLICT`  | No       | Inspect current dialog state; never auto-repeat accept/dismiss                            |
-| `TAB_MISMATCH`            | No       | Tab closed or not found (`working_tab_closed`: your working tab is gone) - pass `tabId` or use `tabs.list` |
+| `TAB_MISMATCH`            | No       | For `ambiguous_browser_target`, select `extensionId` and list its tabs. For a closed working tab, select a new `tabId`. Never disable unrelated windows. |
 | `TIMEOUT`                 | Once     | Retry once; if still failing, simplify (smaller `maxNodes`, narrower selector)            |
 | `CONTENT_SCRIPT_UNAVAILABLE` | No     | Switch to a normal http(s) page in the enabled window                                    |
 | `EXTENSION_DISCONNECTED`  | After 3s | Check Chrome is running; `bbx status` to verify, then retry                               |

package/skills/browser-bridge/references/capabilities.md

@@ -9,15 +9,15 @@ Browser Bridge does not use capability-scoped sessions anymore.
 ## Access Model
 
 1. The user turns Browser Bridge on for one browser window.
-2. Default routing follows the active tab in that enabled window.
-3. Use `tabId` only when you intentionally need a different tab in the same enabled window.
+2. With one connected profile, the first page call binds the session to its active tab. Later calls keep using that working tab even when browser focus changes.
+3. Use `tabId` to choose a different working tab in the selected profile's enabled window.
 4. Turning Browser Bridge off removes access immediately.
 
 Once a window is enabled, the bridge can use all standard methods in that window, including debugger-backed methods when needed.
 
 ## Routing Defaults
 
-Prefer default routing:
+Default routing is safe when only one browser profile is connected:
 
 ```bash
 bbx status
@@ -25,7 +25,7 @@ bbx page-text
 bbx dom-query main
 ```
 
-If the user switches to another tab in the enabled window, Browser Bridge follows that tab automatically.
+If the user switches to another tab, Browser Bridge keeps using the session's working tab.
 
 Use explicit `tabId` only for non-active tabs or deliberate side-by-side comparisons:
 
@@ -35,7 +35,9 @@ bbx call --tab 123 page.get_text
 bbx call --tab 456 dom.query '{"selector":"main"}'
 ```
 
-In MCP tools, pass `tabId` for explicit targeting.
+With multiple profiles, first use `health.ping` to read `connectedExtensions` or an unscoped MCP `tabs.list` to find the requested page across enabled profiles. Pass the selected `extensionId` and `tabId` on every MCP call, plus `destinationId` for a remote machine. Profile-local tab IDs and element refs are not globally unique. For CLI, use `bbx call --extension <connectionId> --tab <tabId> <method> '{...}'`. Browser/profile names are also available through MCP `targetBrowser`/`targetProfile` or CLI `--browser`/`--profile` when they uniquely identify a connection.
+
+Ambiguous calls fail before reaching a page with `TAB_MISMATCH`, `reason: ambiguous_browser_target`, and connection choices. Never disable unrelated windows to route a call. Connection IDs change on reconnect, so rediscover a missing target rather than silently switching profiles.
 
 ## Access Failures
 
@@ -44,4 +46,4 @@ If a call fails with `ACCESS_DENIED`, `TAB_MISMATCH`, or another routing error:
 1. Confirm the user enabled Browser Bridge for the correct browser window.
 2. Confirm the target page is a normal web page, not a Chrome-restricted page.
 3. If using explicit `tabId`, confirm that tab is inside the enabled window.
-4. Fall back to default routing when you do not need a specific tab.
+4. For `ambiguous_browser_target`, choose a connection and list its tabs. Do not fall back to an unrelated active profile.