@browserbridge/bbx 1.11.3 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -56,6 +56,8 @@
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "fixture:browser": "node tests/fixtures/browser-reliability/server.mjs",
+    "fixture:interaction": "node tests/fixtures/agent-interaction/server.mjs",
+    "bench:interaction": "node tests/fixtures/agent-interaction/bench.mjs",
     "test:runtime": "node --import tsx --test packages/*/test/*.test.ts packages/integration-tests/*.test.ts tests/fixtures/*/*.test.ts",
     "test": "c8 node --import tsx --test packages/*/test/*.test.ts packages/integration-tests/*.test.ts tests/fixtures/*/*.test.ts",
     "coverage": "c8 report --reporter=text --reporter=text-summary",
@@ -73,25 +75,29 @@
     "install-manifest": "node packages/native-host/bin/install-manifest.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.3.1",
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
-    "@types/chrome": "^0.3.0",
-    "@types/node": "^26.6.1",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@types/chrome": "^0.3.4",
+    "@types/node": "^26.6.4",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "c8": "^12.0.0",
     "har-schema": "^2.0.0",
-    "oxfmt": "^0.68.0",
-    "oxlint": "^1.83.0",
-    "tsx": "^4.23.13",
+    "oxfmt": "^0.72.0",
+    "oxlint": "^1.87.0",
+    "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=20"
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true,
+    "fsevents@2.3.3": true
   }
 }

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

@@ -139,6 +139,18 @@ async function writeSocketLine(socket, line, signal) {
   }
 }
 
+/**
+ * Agent session that keeps tab routing sticky across separate CLI processes.
+ * Set `BBX_SESSION` to give one agent its own working tab; unset callers share
+ * the extension's default session.
+ *
+ * @returns {string | null}
+ */
+export function getDefaultAgentSession() {
+  const value = process.env.BBX_SESSION?.trim();
+  return value ? value : null;
+}
+
 export class BridgeClient extends EventEmitter {
   /**
    * @param {BridgeClientOptions} [options={}]
@@ -156,6 +168,7 @@ export class BridgeClient extends EventEmitter {
     exitProcessOnNpmUpdate = false,
     updateCompatibleNpmPackageFn = updateCompatibleNpmPackage,
     authToken = undefined,
+    agentSession = getDefaultAgentSession(),
   } = {}) {
     super();
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
@@ -171,6 +184,7 @@ export class BridgeClient extends EventEmitter {
     this.exitProcessOnNpmUpdate = exitProcessOnNpmUpdate;
     this.updateCompatibleNpmPackageFn = updateCompatibleNpmPackageFn;
     this.authToken = authToken;
+    this.agentSession = agentSession;
     this.socket = null;
     this.connected = false;
     this.protocolCompatibility = null;
@@ -488,7 +502,10 @@ export class BridgeClient extends EventEmitter {
       method,
       params,
       tabId,
-      meta,
+      meta:
+        this.agentSession && meta.agent_session === undefined
+          ? { ...meta, agent_session: this.agentSession }
+          : meta,
     });
 
     if (method === 'page.extract_content') {

package/packages/agent-client/src/types.ts

@@ -124,6 +124,8 @@ export interface BridgeClientOptions {
     supportedVersions: readonly string[];
   }) => Promise<NpmUpdateResult>;
   authToken?: string | null;
+  /** Stable agent session id used for sticky working-tab routing. */
+  agentSession?: string | null;
 }
 
 export interface ShortcutCommand {

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

@@ -326,10 +326,17 @@ export const INPUT_ACTION_METHODS = {
  *
  * @param {unknown} elementRef
  * @param {unknown} selector
+ * @param {unknown} [locator]
  * @returns {import('../../protocol/src/types.js').InputTarget | null}
  */
-function createInputTarget(elementRef, selector) {
+function createInputTarget(elementRef, selector, locator) {
   if (typeof elementRef === 'string' && elementRef) return { elementRef };
+  if (locator && typeof locator === 'object' && Object.keys(locator).length) {
+    return {
+      ...(typeof selector === 'string' && selector ? { selector } : {}),
+      .../** @type {Record<string, unknown>} */ (locator),
+    };
+  }
   if (typeof selector === 'string' && selector) return { selector };
   return null;
 }
@@ -337,18 +344,20 @@ function createInputTarget(elementRef, selector) {
 /**
  * Avoid changing legacy handler payloads when new options are omitted.
  *
- * @param {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean }} args
- * @returns {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean }}
+ * @param {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean, timeoutMs?: number, observe?: boolean | { settleMs?: number } }} args
+ * @returns {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean, timeoutMs?: number, observe?: boolean | { settleMs?: number } }}
  */
 function createInputOptions(args) {
   return {
     ...(args.executionMode ? { executionMode: args.executionMode } : {}),
     ...(typeof args.recoverStale === 'boolean' ? { recoverStale: args.recoverStale } : {}),
+    ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+    ...(args.observe !== undefined ? { observe: args.observe } : {}),
   };
 }
 
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, value?: string, mode?: 'auto' | 'setter' | 'keystrokes', executionMode?: 'dom' | 'cdp', recoverStale?: boolean, clear?: boolean, submit?: boolean, key?: string, code?: string, modifiers?: string[], checked?: boolean, values?: string[], labels?: string[], indexes?: number[], duration?: number, sourceElementRef?: string, sourceSelector?: string, destinationElementRef?: string, destinationSelector?: string, offsetX?: number, offsetY?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, holdMs?: number, text?: string, value?: string, mode?: 'auto' | 'setter' | 'keystrokes', executionMode?: 'dom' | 'cdp', recoverStale?: boolean, clear?: boolean, submit?: boolean, key?: string, code?: string, modifiers?: string[], checked?: boolean, values?: string[], labels?: string[], indexes?: number[], duration?: number, sourceElementRef?: string, sourceSelector?: string, destinationElementRef?: string, destinationSelector?: string, offsetX?: number, offsetY?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep', locator?: Record<string, unknown>, timeoutMs?: number, observe?: boolean | { settleMs?: number } }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleInputTool(args) {
@@ -374,9 +383,9 @@ export async function handleInputTool(args) {
     async (client) => {
       const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
       const elementTarget = () => {
-        const target = createInputTarget(args.elementRef, args.selector);
+        const target = createInputTarget(args.elementRef, args.selector, args.locator);
         if (!target) {
-          throw new BridgeError('INVALID_REQUEST', 'Provide either elementRef or selector.');
+          throw new BridgeError('INVALID_REQUEST', 'Provide elementRef, selector, or locator.');
         }
         return target;
       };
@@ -391,6 +400,7 @@ export async function handleInputTool(args) {
               button: args.button,
               clickCount: args.clickCount,
               modifiers: args.modifiers,
+              ...(typeof args.holdMs === 'number' ? { holdMs: args.holdMs } : {}),
               ...createInputOptions(args),
             },
             {
@@ -456,7 +466,8 @@ export async function handleInputTool(args) {
           return summarizeToolResponse(response, 'input.fill');
         }
         case 'press_key': {
-          const target = args.elementRef || args.selector ? elementTarget() : undefined;
+          const target =
+            args.elementRef || args.selector || args.locator ? elementTarget() : undefined;
           const response = await requestBridgeWithRetry(
             client,
             'input.press_key',
@@ -464,6 +475,7 @@ export async function handleInputTool(args) {
               target,
               key: args.key,
               modifiers: args.modifiers,
+              ...(typeof args.holdMs === 'number' ? { holdMs: args.holdMs } : {}),
               ...createInputOptions(args),
             },
             {

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

@@ -87,6 +87,7 @@ export const DOM_ACTIONS = {
       exact: a.exact,
       selector: a.selector,
       maxResults: a.maxResults,
+      ...(a.includeHidden !== undefined ? { includeHidden: a.includeHidden } : {}),
     }),
   },
   find_role: {
@@ -95,8 +96,10 @@ export const DOM_ACTIONS = {
     params: (a) => ({
       role: a.role,
       name: a.name,
+      ...(a.exact !== undefined ? { exact: a.exact } : {}),
       selector: a.selector,
       maxResults: a.maxResults,
+      ...(a.includeHidden !== undefined ? { includeHidden: a.includeHidden } : {}),
     }),
   },
   html: {
@@ -117,12 +120,14 @@ export const DOM_ACTIONS = {
       maxDepth: a.maxDepth,
       compact: a.compact,
       interactiveOnly: a.interactiveOnly,
+      ...(a.source !== undefined ? { source: a.source } : {}),
+      ...(a.format !== undefined ? { format: a.format } : {}),
     }),
   },
 };
 
 /**
- * @param {{ action: string, baselineId?: string, maxChanges?: number, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, compact?: boolean, interactiveOnly?: boolean, textBudget?: number, includeBbox?: boolean, attributeAllowlist?: string[], attributes?: string[], text?: string, exact?: boolean, maxResults?: number, role?: string, name?: string, state?: string, timeoutMs?: number, outer?: boolean, maxLength?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, baselineId?: string, maxChanges?: number, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, compact?: boolean, interactiveOnly?: boolean, source?: 'cdp' | 'dom', format?: 'tree' | 'outline', includeHidden?: boolean, textBudget?: number, includeBbox?: boolean, attributeAllowlist?: string[], attributes?: string[], text?: string, exact?: boolean, maxResults?: number, role?: string, name?: string, state?: string, timeoutMs?: number, outer?: boolean, maxLength?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleDomTool(args) {

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

@@ -47,6 +47,8 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-clie
 
 export const REQUEST_SOURCE = 'mcp';
 const MCP_CLIENT_ID = `mcp_${randomUUID()}`;
+// One MCP server process serves one agent conversation, so it owns one working tab.
+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();
 
@@ -346,6 +348,7 @@ export async function withMcpRequestClient(callback, options = {}) {
   const client = await createBridgeClientForDestination(options.destinationId, {
     checkProtocolOnConnect: false,
     clientId: MCP_CLIENT_ID,
+    agentSession: MCP_AGENT_SESSION,
   });
   let completed = false;
   try {

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

@@ -284,7 +284,7 @@ export function createBridgeMcpServer(options = {}) {
     {
       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 and depth-limited - use query/find first.',
+        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For a page overview to act on, use accessibility_tree with source "dom": a compact outline (`- role "name" [ref]`) whose refs work directly as input targets, with no debugger. find_text/find_role search shadow DOM, use real accessible names (labels, aria-*), and skip hidden matches. For full-page text, use browser_page action "text".',
       inputSchema: z.object({
         action: z
           .enum([
@@ -350,6 +350,16 @@ export function createBridgeMcpServer(options = {}) {
           .describe(
             'Return semantically interactive AX nodes; actionable state is reported separately'
           ),
+        source: z
+          .enum(['dom', 'cdp'])
+          .optional()
+          .describe(
+            'accessibility_tree source: dom = actionable outline with refs, no debugger (recommended); cdp = Chrome AX tree (default)'
+          ),
+        format: z
+          .enum(['outline', 'tree'])
+          .optional()
+          .describe('accessibility_tree format (outline is default for source dom)'),
         textBudget: z
           .number()
           .int()
@@ -381,6 +391,10 @@ export function createBridgeMcpServer(options = {}) {
           .describe('Maximum search results (default: 10)'),
         role: z.string().optional().describe('ARIA role to search for (for find_role action)'),
         name: z.string().optional().describe('Accessible name to match with role'),
+        includeHidden: z
+          .boolean()
+          .optional()
+          .describe('Include hidden matches in find_text/find_role (default: false; counted)'),
         state: z
           .enum(['attached', 'detached', 'visible', 'hidden'])
           .optional()
@@ -658,7 +672,7 @@ export function createBridgeMcpServer(options = {}) {
     {
       title: 'Browser Input',
       description:
-        'Dispatch browser input. Targeted click, focus, type, fill, press_key, set_checked, select_option, hover, and drag actions perform actionability checks and report resolution/execution metadata. cdp_press_key and scroll_into_view use separate contracts. Reuse elementRef values and verify application state after mutations.',
+        'Dispatch browser input. Target by elementRef, selector, or a semantic locator ({role,name} / text / label / placeholder / testId) in one call. Targeted actions auto-wait for the element to become actionable (timeoutMs) and click/press_key/set_checked/select_option/submits return observed effects (URL change, dialogs, alerts, focus, DOM churn, target state), so a follow-up read is usually unnecessary. cdp_press_key and scroll_into_view use separate contracts.',
       inputSchema: z.object({
         action: z
           .enum([
@@ -707,7 +721,7 @@ export function createBridgeMcpServer(options = {}) {
           .enum(['dom', 'cdp'])
           .optional()
           .describe(
-            'Input execution path (default: dom; CDP supports click, hover, drag, type, fill)'
+            'Input execution path (default: dom; CDP supports click, hover, drag, type, fill, press_key). Use cdp when the page needs trusted input, e.g. to start audio or media.'
           ),
         recoverStale: z
           .boolean()
@@ -729,6 +743,15 @@ export function createBridgeMcpServer(options = {}) {
           .array(z.enum(['Alt', 'Control', 'Meta', 'Shift']))
           .optional()
           .describe('Modifier keys'),
+        holdMs: z
+          .number()
+          .int()
+          .min(0)
+          .max(10000)
+          .optional()
+          .describe(
+            'Keep the mouse button or key pressed this long (click, press_key; default: 0)'
+          ),
         checked: z.boolean().optional().describe('Checked state (for set_checked action)'),
         values: z.array(z.string()).optional().describe('Option values to select'),
         labels: z
@@ -760,6 +783,39 @@ export function createBridgeMcpServer(options = {}) {
           .describe('Drag destination selector (alternative to destinationElementRef)'),
         offsetX: z.number().optional().describe('Drag drop offset X (default: 0)'),
         offsetY: z.number().optional().describe('Drag drop offset Y (default: 0)'),
+        locator: z
+          .object({
+            role: z.string().max(500).optional().describe('ARIA role, e.g. button, textbox, link'),
+            name: z.string().max(500).optional().describe('Accessible name (labels, aria-*, text)'),
+            text: z.string().max(500).optional().describe('Visible text of the element'),
+            label: z.string().max(500).optional().describe('Form control label text'),
+            placeholder: z.string().max(500).optional(),
+            testId: z.string().max(500).optional().describe('data-testid / data-test / data-qa'),
+            exact: z.boolean().optional().describe('Exact instead of substring match'),
+            nth: z.number().int().min(0).max(49).optional().describe('Pick the nth visible match'),
+          })
+          .optional()
+          .describe(
+            'Find the target semantically in the same call (instead of elementRef/selector); selector narrows candidates'
+          ),
+        timeoutMs: z
+          .number()
+          .int()
+          .min(0)
+          .max(15000)
+          .optional()
+          .describe(
+            'Wait for the target to appear and become actionable (default: 2500; 0 = no wait)'
+          ),
+        observe: z
+          .union([
+            z.boolean(),
+            z.object({ settleMs: z.number().int().min(0).max(5000).optional() }),
+          ])
+          .optional()
+          .describe(
+            'Report effects (URL, dialogs, alerts, focus, DOM churn, target state) after the action; default on for click, press_key, set_checked, select_option, and submits'
+          ),
       }),
     },
     handleInputTool

package/packages/protocol/src/defaults.js

@@ -45,6 +45,22 @@ export const MAX_BATCH_CALLS = 20;
 
 /** Maximum read-only batch calls executing concurrently. */
 export const MAX_BATCH_CONCURRENCY = 5;
+
+/** Maximum press-and-hold time for one pointer, key, or touch action (ms). */
+export const MAX_INPUT_HOLD_MS = 10_000;
+
+/** Default contact time for an input.touch gesture without explicit holdMs (ms). */
+export const DEFAULT_TOUCH_HOLD_MS = 50;
+
+/** Maximum simultaneous touch points in one input.touch gesture. */
+export const MAX_TOUCH_POINTS = 10;
+
+/** Maximum steps accepted by one input.perform sequence. */
+export const MAX_PERFORM_STEPS = 200;
+
+/** Default and maximum total budget for one input.perform sequence (ms). */
+export const DEFAULT_PERFORM_TIMEOUT_MS = 30_000;
+export const MAX_PERFORM_TIMEOUT_MS = 120_000;
 export const MAX_INTERCEPT_RULES_PER_TAB = 32;
 export const MAX_INTERCEPT_URL_PATTERN_LENGTH = 2_048;
 export const MAX_INTERCEPT_BODY_BYTES = 262_144;