@browserbridge/bbx 1.6.0 → 1.6.2

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

@@ -5,6 +5,7 @@ import {
   DEFAULT_NETWORK_LIMIT,
   METHOD_SET,
 } from '../../protocol/src/index.js';
+import { createBridgeClientForDestination } from '../../agent-client/src/remotes.js';
 import {
   annotateBridgeSummary,
   applyLimitBudgetPreset,
@@ -65,7 +66,7 @@ export const PAGE_ACTIONS = {
 };
 
 /**
- * @param {{ action: string, expression?: string, awaitPromise?: boolean, timeoutMs?: number, returnByValue?: boolean, level?: string, clear?: boolean, limit?: number, type?: string, keys?: string[], textBudget?: number, urlPattern?: string, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, expression?: string, awaitPromise?: boolean, timeoutMs?: number, returnByValue?: boolean, level?: string, clear?: boolean, limit?: number, type?: string, keys?: string[], textBudget?: number, urlPattern?: string, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handlePageTool(args) {
@@ -96,11 +97,12 @@ export async function handlePageTool(args) {
   return callBridgeTool(entry.method, entry.params(normalizedArgs), {
     tabId: typeof normalizedArgs.tabId === 'number' ? normalizedArgs.tabId : null,
     tokenBudget: getToolTokenBudget(normalizedArgs),
+    destinationId: normalizedArgs.destinationId ?? null,
   });
 }
 
 /**
- * @param {{ calls?: Array<{ method?: string, params?: Record<string, unknown>, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }> }} args
+ * @param {{ calls?: Array<{ method?: string, params?: Record<string, unknown>, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }> }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleBatchTool(args) {
@@ -149,20 +151,30 @@ export async function handleBatchTool(args) {
             : null
           : null;
         const tokenBudget = getToolTokenBudget(call);
+        const destinationId = typeof call.destinationId === 'string' ? call.destinationId : null;
 
         const startTime = Date.now();
+        const callClient = destinationId
+          ? await createBridgeClientForDestination(destinationId)
+          : client;
         try {
-          const response = await requestBridgeWithRetry(client, method, call.params || {}, {
+          if (destinationId) {
+            await callClient.connect();
+          }
+          const response = await requestBridgeWithRetry(callClient, method, call.params || {}, {
             tabId,
             source: REQUEST_SOURCE,
             tokenBudget,
           });
-          return summarizeBatchResponseItem({
-            method,
-            tabId,
-            response,
-            durationMs: Date.now() - startTime,
-          });
+          return {
+            destinationId,
+            ...summarizeBatchResponseItem({
+              method,
+              tabId,
+              response,
+              durationMs: Date.now() - startTime,
+            }),
+          };
         } catch (error) {
           return summarizeBatchErrorItem({
             method,
@@ -170,6 +182,10 @@ export async function handleBatchTool(args) {
             error,
             durationMs: Date.now() - startTime,
           });
+        } finally {
+          if (destinationId) {
+            await callClient.close();
+          }
         }
       })
     );
@@ -191,7 +207,7 @@ export async function handleBatchTool(args) {
 }
 
 /**
- * @param {{ method: string, params?: Record<string, unknown>, tabId?: number }} args
+ * @param {{ method: string, params?: Record<string, unknown>, tabId?: number, destinationId?: string }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleRawCallTool(args) {
@@ -199,34 +215,37 @@ export async function handleRawCallTool(args) {
     return summarizeToolError(`Unknown bridge method "${args.method}".`);
   }
 
-  return withToolClient(async (client) => {
-    const response = await requestBridgeWithRetry(
-      client,
-      /** @type {BridgeMethod} */ (args.method),
-      args.params || {},
-      {
-        tabId: typeof args.tabId === 'number' ? args.tabId : null,
-        source: REQUEST_SOURCE,
-      }
-    );
-
-    if (!response.ok) {
-      return createToolResult(
-        response.error.message,
+  return withToolClient(
+    async (client) => {
+      const response = await requestBridgeWithRetry(
+        client,
+        /** @type {BridgeMethod} */ (args.method),
+        args.params || {},
         {
-          ok: false,
-          error: response.error,
-          response,
-        },
-        true
+          tabId: typeof args.tabId === 'number' ? args.tabId : null,
+          source: REQUEST_SOURCE,
+        }
       );
-    }
 
-    return createToolResult(`Called ${args.method}.`, {
-      ok: true,
-      response: response.result,
-    });
-  });
+      if (!response.ok) {
+        return createToolResult(
+          response.error.message,
+          {
+            ok: false,
+            error: response.error,
+            response,
+          },
+          true
+        );
+      }
+
+      return createToolResult(`Called ${args.method}.`, {
+        ok: true,
+        response: response.result,
+      });
+    },
+    { destinationId: args.destinationId ?? null }
+  );
 }
 
 /**
@@ -290,7 +309,7 @@ const INVESTIGATE_SCOPES = {
 };
 
 /**
- * @param {{ objective: string, scope?: 'quick' | 'normal' | 'deep', tabId?: number, selector?: string }} args
+ * @param {{ objective: string, scope?: 'quick' | 'normal' | 'deep', tabId?: number, destinationId?: string, selector?: string }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleInvestigateTool(args) {
@@ -305,62 +324,65 @@ export async function handleInvestigateTool(args) {
     return summarizeToolError(`Unsupported investigation scope "${scopeName}".`);
   }
 
-  return withToolClient(async (client) => {
-    const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
+  return withToolClient(
+    async (client) => {
+      const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
 
-    /** @type {Array<{ method: string, ok: boolean, summary: string, evidence: unknown, durationMs: number }>} */
-    const stepResults = [];
+      /** @type {Array<{ method: string, ok: boolean, summary: string, evidence: unknown, durationMs: number }>} */
+      const stepResults = [];
 
-    for (const step of scope.steps) {
-      const startTime = Date.now();
-      try {
-        const response = await requestBridgeWithRetry(client, step.method, step.params(args), {
-          tabId: requestedTabId,
-          source: REQUEST_SOURCE,
-          tokenBudget: null,
-        });
-        const bridgeSummary = annotateBridgeSummary(
-          summarizeBridgeResponse(response, step.method),
-          response
-        );
-        stepResults.push({
-          method: step.method,
-          ok: bridgeSummary.ok,
-          summary: bridgeSummary.summary,
-          evidence: bridgeSummary.evidence,
-          durationMs: Date.now() - startTime,
-        });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        stepResults.push({
-          method: step.method,
-          ok: false,
-          summary: `ERROR: ${message}`,
-          evidence: null,
-          durationMs: Date.now() - startTime,
-        });
+      for (const step of scope.steps) {
+        const startTime = Date.now();
+        try {
+          const response = await requestBridgeWithRetry(client, step.method, step.params(args), {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: null,
+          });
+          const bridgeSummary = annotateBridgeSummary(
+            summarizeBridgeResponse(response, step.method),
+            response
+          );
+          stepResults.push({
+            method: step.method,
+            ok: bridgeSummary.ok,
+            summary: bridgeSummary.summary,
+            evidence: bridgeSummary.evidence,
+            durationMs: Date.now() - startTime,
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          stepResults.push({
+            method: step.method,
+            ok: false,
+            summary: `ERROR: ${message}`,
+            evidence: null,
+            durationMs: Date.now() - startTime,
+          });
+        }
       }
-    }
 
-    const failedSteps = stepResults.filter((s) => !s.ok);
-    const allOk = failedSteps.length === 0;
-    const totalDuration = stepResults.reduce((sum, s) => sum + s.durationMs, 0);
+      const failedSteps = stepResults.filter((s) => !s.ok);
+      const allOk = failedSteps.length === 0;
+      const totalDuration = stepResults.reduce((sum, s) => sum + s.durationMs, 0);
 
-    const summaryText = allOk
-      ? `Investigation complete (${scope.label}, ${stepResults.length} steps, ${totalDuration}ms). Objective: ${objective}`
-      : `Investigation partial (${scope.label}, ${stepResults.length} steps, ${failedSteps.length} failed, ${totalDuration}ms). Objective: ${objective}`;
+      const summaryText = allOk
+        ? `Investigation complete (${scope.label}, ${stepResults.length} steps, ${totalDuration}ms). Objective: ${objective}`
+        : `Investigation partial (${scope.label}, ${stepResults.length} steps, ${failedSteps.length} failed, ${totalDuration}ms). Objective: ${objective}`;
 
-    return createToolResult(
-      summaryText,
-      {
-        ok: allOk,
-        objective,
-        scope: scopeName,
-        heuristicFallback: true,
-        steps: stepResults,
-        failedSteps,
-      },
-      !allOk
-    );
-  });
+      return createToolResult(
+        summaryText,
+        {
+          ok: allOk,
+          objective,
+          scope: scopeName,
+          heuristicFallback: true,
+          steps: stepResults,
+          failedSteps,
+        },
+        !allOk
+      );
+    },
+    { destinationId: args.destinationId ?? null }
+  );
 }

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

@@ -17,6 +17,10 @@ import {
   resolveRef,
   withBridgeClient,
 } from '../../agent-client/src/runtime.js';
+import {
+  createBridgeClientForDestination,
+  listBridgeDestinations,
+} from '../../agent-client/src/remotes.js';
 import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-client/src/subagent.js';
 
 /** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
@@ -130,11 +134,21 @@ export function summarizeToolError(error) {
 
 /**
  * @param {(client: import('../../agent-client/src/client.js').BridgeClient) => Promise<ToolResult>} callback
+ * @param {{ destinationId?: string | null }} [options]
  * @returns {Promise<ToolResult>}
  */
-export async function withToolClient(callback) {
+export async function withToolClient(callback, options = {}) {
   try {
-    return await withBridgeClient(callback);
+    if (!options.destinationId) {
+      return await withBridgeClient(callback);
+    }
+    const client = await createBridgeClientForDestination(options.destinationId);
+    await client.connect();
+    try {
+      return await callback(client);
+    } finally {
+      await client.close();
+    }
   } catch (error) {
     return summarizeToolError(error);
   }
@@ -306,18 +320,28 @@ export async function requestBridgeWithRetry(client, method, params, options) {
 /**
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} [params={}]
- * @param {{ tabId?: number | null, summaryMethod?: string, tokenBudget?: number | null }} [options]
+ * @param {{ tabId?: number | null, summaryMethod?: string, tokenBudget?: number | null, destinationId?: string | null }} [options]
  * @returns {Promise<ToolResult>}
  */
 export async function callBridgeTool(method, params = {}, options = {}) {
-  return withToolClient(async (client) => {
-    const response = await requestBridgeWithRetry(client, method, params, {
-      tabId: options.tabId ?? null,
-      source: REQUEST_SOURCE,
-      tokenBudget: options.tokenBudget ?? null,
-    });
-    return summarizeToolResponse(response, options.summaryMethod || method);
-  });
+  return withToolClient(
+    async (client) => {
+      const response = await requestBridgeWithRetry(client, method, params, {
+        tabId: options.tabId ?? null,
+        source: REQUEST_SOURCE,
+        tokenBudget: options.tokenBudget ?? null,
+      });
+      return summarizeToolResponse(response, options.summaryMethod || method);
+    },
+    { destinationId: options.destinationId ?? null }
+  );
+}
+
+/**
+ * @returns {Promise<Array<{ id: string, local: boolean, host: string | null, port: number | null }>>}
+ */
+export async function getBridgeDestinations() {
+  return listBridgeDestinations();
 }
 
 /**
@@ -333,22 +357,25 @@ export async function callBridgeTool(method, params = {}, options = {}) {
 export async function dispatchToolAction(actions, args, toolName) {
   const entry = actions[args.action];
   if (!entry) return summarizeToolError(`Unsupported ${toolName} action "${args.action}".`);
-  return withToolClient(async (client) => {
-    const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
-    const ref = entry.ref
-      ? await resolveToolRef(
-          client,
-          /** @type {{ elementRef?: string, selector?: string }} */ (args),
-          requestedTabId
-        )
-      : undefined;
-    const response = await requestBridgeWithRetry(client, entry.method, entry.params(args, ref), {
-      tabId: requestedTabId,
-      source: REQUEST_SOURCE,
-      tokenBudget: getToolTokenBudget(/** @type {{ budgetPreset?: unknown }} */ (args)),
-    });
-    return summarizeToolResponse(response, entry.method);
-  });
+  return withToolClient(
+    async (client) => {
+      const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
+      const ref = entry.ref
+        ? await resolveToolRef(
+            client,
+            /** @type {{ elementRef?: string, selector?: string }} */ (args),
+            requestedTabId
+          )
+        : undefined;
+      const response = await requestBridgeWithRetry(client, entry.method, entry.params(args, ref), {
+        tabId: requestedTabId,
+        source: REQUEST_SOURCE,
+        tokenBudget: getToolTokenBudget(/** @type {{ budgetPreset?: unknown }} */ (args)),
+      });
+      return summarizeToolResponse(response, entry.method);
+    },
+    { destinationId: typeof args.destinationId === 'string' ? args.destinationId : null }
+  );
 }
 
 export {
@@ -357,6 +384,7 @@ export {
   requestBridge,
   resolveRef,
   withBridgeClient,
+  listBridgeDestinations,
   annotateBridgeSummary,
   summarizeBridgeResponse,
   summarizeBatchErrorItem,

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

@@ -8,6 +8,7 @@ import {
   createToolResult,
   getDoctorReport,
   getToolTokenBudget,
+  getBridgeDestinations,
   applyLimitBudgetPreset,
   summarizeToolError,
   summarizeToolResponse,
@@ -71,6 +72,22 @@ const HOME_DIR = os.homedir();
 export async function handleStatusTool() {
   try {
     const report = await getDoctorReport();
+    const destinations = await Promise.all(
+      (await getBridgeDestinations()).map(async (destination) => {
+        if (destination.local) {
+          return {
+            ...destination,
+            reachable: report.daemonReachable,
+            extensionConnected: report.extensionConnected,
+            accessEnabled: report.accessEnabled,
+            routeReady: report.routeReady,
+            routeTabId: report.routeTabId,
+          };
+        }
+        const result = await callRemoteHealth(destination.id);
+        return { ...destination, ...result };
+      })
+    );
     const summary =
       report.issues.length === 0
         ? 'Browser Bridge is ready.'
@@ -78,12 +95,25 @@ export async function handleStatusTool() {
     return createToolResult(summary, {
       ok: report.issues.length === 0,
       evidence: report,
+      destinations,
     });
   } catch (error) {
     return summarizeToolError(error);
   }
 }
 
+/**
+ * @param {string} destinationId
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function callRemoteHealth(destinationId) {
+  const result = await callBridgeTool('health.ping', {}, { destinationId });
+  return {
+    reachable: result.structuredContent.ok === true,
+    health: result.structuredContent,
+  };
+}
+
 /**
  * @returns {Promise<ToolResult>}
  */
@@ -138,21 +168,33 @@ export async function handleLogTool(args) {
 }
 
 /**
+ * @param {{ destinationId?: string }} [args]
  * @returns {Promise<ToolResult>}
  */
-export async function handleHealthTool() {
-  return withToolClient(async (client) => {
-    const response = await client.request({
-      method: 'health.ping',
-      meta: { source: REQUEST_SOURCE },
-    });
-    return summarizeToolResponse(response, 'health.ping');
-  });
+export async function handleHealthTool(args = {}) {
+  const destinationId = typeof args.destinationId === 'string' ? args.destinationId : null;
+  return withToolClient(
+    async (client) => {
+      const response = await client.request({
+        method: 'health.ping',
+        meta: { source: REQUEST_SOURCE },
+      });
+      return summarizeToolResponse(response, 'health.ping');
+    },
+    { destinationId }
+  );
 }
 
 /**
+ * @param {{ destinationId?: string }} [args]
  * @returns {Promise<ToolResult>}
  */
-export async function handleAccessTool() {
-  return callBridgeTool('access.request');
+export async function handleAccessTool(args = {}) {
+  return callBridgeTool(
+    'access.request',
+    {},
+    {
+      destinationId: typeof args.destinationId === 'string' ? args.destinationId : null,
+    }
+  );
 }

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

@@ -40,11 +40,13 @@ import {
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
-import { MCP_SERVER_INSTRUCTIONS, registerBridgeMcpGuidance } from './guidance.js';
+import { MCP_SERVER_INSTRUCTIONS } from './guidance.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.';
+export const DESTINATION_ID_DESCRIPTION =
+  'Optional Browser Bridge destination ID from browser_status/browser_tabs; omit for local.';
 
 const MCP_SERVER_VERSION = loadPackageVersion();
 
@@ -109,7 +111,9 @@ export function createBridgeMcpServer() {
       title: 'Browser Bridge Status',
       description:
         'Check bridge readiness: daemon connectivity, extension state, and window access. Call first to confirm the bridge is usable. If access is not enabled, ask the user to click Enable in the extension popup or side panel, then retry.',
-      inputSchema: {},
+      inputSchema: {
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+      },
     },
     handleStatusTool
   );
@@ -155,7 +159,9 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Health',
       description: 'Ping the bridge to verify daemon and extension connectivity.',
-      inputSchema: {},
+      inputSchema: {
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+      },
     },
     handleHealthTool
   );
@@ -173,6 +179,7 @@ export function createBridgeMcpServer() {
         url: z.string().optional().describe('URL for create action'),
         active: z.boolean().optional().describe('Focus the new tab (default: true)'),
         tabId: z.number().int().positive().optional().describe('Tab ID (required for close)'),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
       },
     },
     handleTabsTool
@@ -199,6 +206,7 @@ export function createBridgeMcpServer() {
           ])
           .describe('DOM operation to perform'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -291,6 +299,7 @@ export function createBridgeMcpServer() {
           .enum(['computed', 'matched_rules', 'box_model', 'hit_test'])
           .describe('Style/layout operation to perform'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -336,6 +345,7 @@ export function createBridgeMcpServer() {
           ])
           .describe('Page operation to perform'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -397,6 +407,7 @@ export function createBridgeMcpServer() {
           .enum(['navigate', 'reload', 'go_back', 'go_forward', 'scroll', 'resize'])
           .describe('Navigation operation to perform'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -451,6 +462,7 @@ export function createBridgeMcpServer() {
           ])
           .describe('Input operation to perform'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -533,6 +545,7 @@ export function createBridgeMcpServer() {
           .enum(['apply_styles', 'apply_dom', 'list', 'rollback', 'commit_baseline'])
           .describe('Patch operation to perform'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -593,6 +606,7 @@ export function createBridgeMcpServer() {
             'element (preferred), region (tight crop), full_page (document-level only), or cdp_* for low-level data'
           ),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -638,6 +652,7 @@ export function createBridgeMcpServer() {
                 .optional()
                 .describe('Method params for this call'),
               tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+              destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
               budgetPreset: z
                 .enum(['quick', 'normal', 'deep'])
                 .optional()
@@ -664,6 +679,7 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Method parameters as object'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
       },
     },
     handleRawCallTool
@@ -675,7 +691,9 @@ export function createBridgeMcpServer() {
       title: 'Browser Bridge Runtime Context',
       description:
         'Return runtime context: budget presets, method groups, and active limits. Call to discover defaults before inspecting a page.',
-      inputSchema: {},
+      inputSchema: {
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+      },
     },
     handleSkillTool
   );
@@ -726,6 +744,7 @@ export function createBridgeMcpServer() {
               '"deep" (state + DOM + text + console + network).'
           ),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         selector: z
           .string()
           .optional()
@@ -735,8 +754,6 @@ export function createBridgeMcpServer() {
     handleInvestigateTool
   );
 
-  registerBridgeMcpGuidance(server);
-
   return server;
 }