@browserbridge/bbx 1.7.2 → 1.7.4

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

@@ -76,7 +76,10 @@ export function isRetrySafeBridgeMethod(method, params) {
 
 /**
  * @typedef {{
- *   content: Array<{ type: 'text', text: string }>,
+ *   content: [
+ *     { type: 'text', text: string },
+ *     ...Array<{ type: 'image', data: string, mimeType: string }>
+ *   ],
  *   structuredContent: Record<string, unknown>,
  *   isError?: boolean
  * }} ToolResult
@@ -86,11 +89,20 @@ export function isRetrySafeBridgeMethod(method, params) {
  * @param {string} summary
  * @param {Record<string, unknown>} [structuredContent={}]
  * @param {boolean} [isError=false]
+ * @param {Array<{ type: 'image', data: string, mimeType: string }>} [additionalContent=[]]
  * @returns {ToolResult}
  */
-export function createToolResult(summary, structuredContent = {}, isError = false) {
+export function createToolResult(
+  summary,
+  structuredContent = {},
+  isError = false,
+  additionalContent = []
+) {
   const toolResult = {
-    content: [{ type: /** @type {'text'} */ ('text'), text: summary }],
+    content: /** @type {ToolResult['content']} */ ([
+      { type: 'text', text: summary },
+      ...additionalContent,
+    ]),
     structuredContent,
     ...(isError ? { isError: true } : {}),
   };
@@ -122,77 +134,22 @@ export function summarizeToolResponse(response, method) {
  */
 export function summarizeToolError(error) {
   const message = error instanceof Error ? error.message : String(error);
+  const record =
+    error && typeof error === 'object' ? /** @type {Record<string, unknown>} */ (error) : {};
+  const code = typeof record.code === 'string' ? record.code : 'INTERNAL_ERROR';
+  const recovery = getErrorRecovery(code);
   return createToolResult(
-    `ERROR: ${message}`,
+    `${code}: ${message}${recovery?.hint ? ` ${recovery.hint}` : ''}`,
     {
       ok: false,
       evidence: null,
+      error: { code, message },
+      recovery,
     },
     true
   );
 }
 
-/**
- * @param {ToolResult} result
- * @returns {boolean}
- */
-function shouldTryRemoteFallback(result) {
-  if (!result.isError && result.structuredContent.ok !== false) {
-    return false;
-  }
-  const text = result.content[0]?.text ?? '';
-  return /\b(ACCESS_DENIED|DAEMON_OFFLINE|EXTENSION_DISCONNECTED|NATIVE_HOST_UNAVAILABLE|CONNECTION_LOST)\b|\b(ENOENT|ECONNREFUSED|ETIMEDOUT)\b|ERROR: connect\b/u.test(
-    text
-  );
-}
-
-/**
- * @param {ToolResult} result
- * @param {string} destinationId
- * @returns {ToolResult}
- */
-function annotateAutoDestination(result, destinationId) {
-  return {
-    ...result,
-    structuredContent: {
-      ...result.structuredContent,
-      destinationId,
-      autoSelectedDestinationId: destinationId,
-    },
-  };
-}
-
-/**
- * @param {(client: import('../../agent-client/src/client.js').BridgeClient) => Promise<ToolResult>} callback
- * @param {ToolResult} localResult
- * @returns {Promise<ToolResult>}
- */
-async function tryRemoteFallback(callback, localResult) {
-  const remotes = (await listBridgeDestinations()).filter((destination) => !destination.local);
-  if (remotes.length === 0) {
-    return localResult;
-  }
-
-  let lastFallbackResult = localResult;
-  for (const remote of remotes) {
-    const client = await createBridgeClientForDestination(remote.id);
-    try {
-      await client.connect();
-      const result = annotateAutoDestination(await callback(client), remote.id);
-      lastFallbackResult = result;
-      if (!shouldTryRemoteFallback(result)) {
-        return result;
-      }
-    } catch (error) {
-      lastFallbackResult = annotateAutoDestination(summarizeToolError(error), remote.id);
-    } finally {
-      await client.close();
-    }
-  }
-
-  return lastFallbackResult;
-}
-
 /**
  * @param {(client: import('../../agent-client/src/client.js').BridgeClient) => Promise<ToolResult>} callback
  * @param {{ destinationId?: string | null }} [options]
@@ -201,8 +158,7 @@ async function tryRemoteFallback(callback, localResult) {
 export async function withToolClient(callback, options = {}) {
   try {
     if (!options.destinationId) {
-      const result = await withBridgeClient(callback);
-      return shouldTryRemoteFallback(result) ? await tryRemoteFallback(callback, result) : result;
+      return await withBridgeClient(callback);
     }
     const client = await createBridgeClientForDestination(options.destinationId);
     await client.connect();
@@ -367,7 +323,10 @@ export function applyHtmlBudgetPreset(args) {
  */
 export async function requestBridgeWithRetry(client, method, params, options) {
   const response = await requestBridge(client, method, params, options);
-  const recovery = !response.ok && response.error ? getErrorRecovery(response.error.code) : null;
+  const recovery =
+    !response.ok && response.error
+      ? (response.error.recovery ?? getErrorRecovery(response.error.code))
+      : null;
   if (!response.ok && recovery?.retry && isRetrySafeBridgeMethod(method, params)) {
     const delay = recovery.retryAfterMs ?? 1000;
     process.stderr.write(

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

@@ -54,6 +54,8 @@ export {
 } from './handlers-capture.js';
 
 export {
+  MAX_BATCH_CALLS,
+  MAX_BATCH_CONCURRENCY,
   PAGE_ACTIONS,
   handlePageTool,
   handleBatchTool,

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

@@ -27,6 +27,7 @@ import {
   handleStylesLayoutTool,
   handleTabsTool,
   handleInvestigateTool,
+  MAX_BATCH_CALLS,
 } from './handlers.js';
 import {
   BUDGET_PRESETS,
@@ -40,7 +41,7 @@ import {
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
-import { MCP_SERVER_INSTRUCTIONS } from './guidance.js';
+import { MCP_SERVER_INSTRUCTIONS, registerBridgeMcpGuidance } 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 =
@@ -105,6 +106,8 @@ export function createBridgeMcpServer() {
     }
   );
 
+  registerBridgeMcpGuidance(server);
+
   server.registerTool(
     'browser_status',
     {
@@ -172,14 +175,19 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Tabs',
       description:
-        'List, create, or close browser tabs. Prefer "list" to work in existing tabs; only use "create" when the user explicitly requests a new page.',
+        'List, create, close, or activate browser tabs. Prefer "list" to work in existing tabs; only use "create" when the user explicitly requests a new page.',
       inputSchema: {
         action: z
-          .enum(['list', 'create', 'close'])
-          .describe('"list" (preferred), "create" (only when needed), or "close"'),
+          .enum(['list', 'create', 'close', 'activate'])
+          .describe('"list" (preferred), "create" (only when needed), "close", or "activate"'),
         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)'),
+        tabId: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Tab ID (required for close/activate)'),
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
       },
     },
@@ -191,7 +199,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser DOM',
       description:
-        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed — use query/find first.',
+        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed - use query/find first.',
       inputSchema: {
         action: z
           .enum([
@@ -267,7 +275,9 @@ export function createBridgeMcpServer() {
         state: z
           .enum(['attached', 'detached', 'visible', 'hidden'])
           .optional()
-          .describe('Expected element state (for wait action)'),
+          .describe(
+            'Expected element state (for wait action); hidden also matches complete absence'
+          ),
         timeoutMs: z
           .number()
           .int()
@@ -331,7 +341,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Page State',
       description:
-        'Read page-level data: state (URL/title), evaluate (JS), console, storage, text, network, or performance. For element-level reads, use browser_dom. evaluate and performance are debugger-backed — prefer lighter reads first.',
+        'Read page-level data: state (URL/title), evaluate (JS), console, storage, text, network, or performance. For element-level reads, use browser_dom. evaluate and performance are debugger-backed - prefer lighter reads first.',
       inputSchema: {
         action: z
           .enum([
@@ -367,9 +377,11 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Return actual value vs JSON (default: true)'),
         level: z
-          .string()
+          .enum(['all', 'debug', 'log', 'info', 'warn', 'error', 'exception', 'rejection'])
           .optional()
-          .describe('Minimum console level: log, warn, error (default: all)'),
+          .describe(
+            'Minimum console severity (default: all); exception/rejection select that exact stream'
+          ),
         clear: z.boolean().optional().describe('Clear buffer after reading (default: false)'),
         limit: z
           .number()
@@ -402,7 +414,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Navigation',
       description:
-        'Navigate to a URL, reload, go back/forward, scroll, or resize the viewport. resize is debugger-backed — use only for exact viewport overrides.',
+        'Navigate to a URL, reload, go back/forward, scroll, or resize the viewport. resize is debugger-backed - use only for exact viewport overrides.',
       inputSchema: {
         action: z
           .enum(['navigate', 'reload', 'go_back', 'go_forward', 'scroll', 'resize'])
@@ -453,6 +465,7 @@ export function createBridgeMcpServer() {
             'click',
             'focus',
             'type',
+            'fill',
             'press_key',
             'cdp_press_key',
             'set_checked',
@@ -485,6 +498,11 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Click count (1=single, 2=double)'),
         text: z.string().max(100000).optional().describe('Text to type (for type action)'),
+        value: z.string().max(100000).optional().describe('Value to set (for fill action)'),
+        mode: z
+          .enum(['auto', 'setter', 'keystrokes'])
+          .optional()
+          .describe('Fill strategy (default: auto)'),
         clear: z.boolean().optional().describe('Clear field before typing (default: false)'),
         submit: z.boolean().optional().describe('Press Enter after typing (default: false)'),
         key: z
@@ -591,7 +609,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Capture',
       description:
-        'Capture screenshots or CDP snapshots. Debugger-backed and token-expensive — use only when structured reads (browser_dom, browser_styles_layout) are insufficient. Prefer element, then tight region; full_page only for document-level context.',
+        'Capture screenshots or CDP snapshots. Debugger-backed and token-expensive - use only when structured reads (browser_dom, browser_styles_layout) are insufficient. Prefer element, then tight region; full_page only for document-level context.',
       inputSchema: {
         action: z
           .enum([
@@ -642,7 +660,13 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Batch',
       description:
-        'Execute multiple bridge calls in parallel to reduce round-trips. Combine independent reads (e.g., styles + text + console) in one call. Preserves call order in the response.',
+        'Execute independent read-only bridge calls in parallel to reduce round-trips. Mutations and destructive reads are rejected; run them sequentially with specialized tools or browser_call. Preserves call order in the response.',
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
       inputSchema: {
         calls: z
           .array(
@@ -661,6 +685,7 @@ export function createBridgeMcpServer() {
             })
           )
           .min(1)
+          .max(MAX_BATCH_CALLS)
           .describe('Calls to execute in parallel'),
       },
     },

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

@@ -249,11 +249,20 @@ export async function stopBridgeDaemon(options = {}) {
     resolvedTransport.type === 'socket' ? resolvedTransport.socketPath : '';
 
   const pidFromFile = await readPidFn(pidPath);
-  let previousPid = pidFromFile;
-  let previouslyRunning = previousPid !== null;
-
-  if (previousPid === null && (await safePingDaemon(resolvedTransport, pingDaemonFn))) {
-    previousPid = await findPidByTransportFn(resolvedTransport);
+  const reachable = await safePingDaemon(resolvedTransport, pingDaemonFn);
+  const endpointOwnerPid =
+    pidFromFile !== null || reachable ? await findPidByTransportFn(resolvedTransport) : null;
+  /** @type {number | null} */
+  let previousPid = null;
+  let previouslyRunning = false;
+
+  if (endpointOwnerPid !== null) {
+    previousPid = endpointOwnerPid;
+    previouslyRunning = true;
+  } else if (reachable) {
+    // TCP endpoints do not expose an owner pid. In that case daemon
+    // reachability is the evidence supporting the recorded pid.
+    previousPid = pidFromFile;
     previouslyRunning = true;
   }
 
@@ -275,9 +284,8 @@ export async function stopBridgeDaemon(options = {}) {
       sleepFn,
     });
     if (!stopped) {
-      // The pid file can be stale (e.g. a root-owned leftover from a sudo
-      // install that the daemon could not overwrite) while a daemon with a
-      // different pid owns the socket. Target the socket owner before giving up.
+      // Endpoint ownership may become discoverable after a recorded daemon pid
+      // fails to stop. Only target the verified owner before giving up.
       const socketOwnerPid = await findPidByTransportFn(resolvedTransport);
       if (socketOwnerPid !== null && socketOwnerPid !== previousPid) {
         try {