@browserbridge/bbx 1.14.0 → 1.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -77,12 +77,12 @@
   "dependencies": {
     "@modelcontextprotocol/server": "^2.3.1",
     "@mozilla/readability": "^0.6.0",
-    "linkedom": "^0.18.13",
+    "linkedom": "^0.18.14",
     "zod": "^4.6.7"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.3.1",
-    "@types/chrome": "^0.3.5",
+    "@types/chrome": "^0.3.6",
     "@types/node": "^26.6.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

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

@@ -52,7 +52,7 @@ export function printCallResponse(response, method) {
 }
 
 /**
- * @returns {void}
+ * @returns {Promise<void>}
  */
 export function printUsage() {
   const blocks = ['Usage: bbx [--remote <name>] <command> [args]'];
@@ -60,5 +60,11 @@ export function printUsage() {
     blocks.push('', `${section.title}:`);
     blocks.push(...section.lines.map((line) => `  ${line}`));
   }
-  process.stdout.write(`${blocks.join('\n')}\n`);
+  // Wait for piped output to flush before the CLI exits.
+  return new Promise((resolve, reject) => {
+    process.stdout.write(`${blocks.join('\n')}\n`, (error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
 }

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

@@ -101,7 +101,7 @@ const remoteDestinationId =
     : (remoteFlag.remoteId ?? process.env[REMOTE_ENV] ?? null);
 
 if (!command || ['help', '--help', '-h'].includes(command)) {
-  printUsage();
+  await printUsage();
   process.exit(0);
 }
 
@@ -794,7 +794,7 @@ async function main() {
     }
 
     process.stderr.write(`Unknown command: ${command}\n`);
-    printUsage();
+    await printUsage();
     process.exitCode = 1;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

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

@@ -8,6 +8,7 @@
 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. 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.',
+  "Keep working in the target tab when the user switches to their own tab. Reads, input, navigation, and screenshots can run in background tabs; a different active_tab_id is informational. You may switch to tabs you opened for this task without asking while the currently active tab is also one you are using for this task. Check tabs.list active state before switching; track opened tabs from your own tabs.create results. working:true identifies routing, not ownership or foreground focus. Otherwise, activate only at the user's request or with their permission. If background work fails because a tab needs to be active, explain why and ask whether activation is allowed. Apply this rule to tabs.activate, tabs.create with active:true, and equivalent focus APIs.",
   "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 independent parallel reads; run mutations in order, preferably inside one input.perform for a known flow. Keep limits tight before widening.',
   'Reuse elementRef values returned by DOM reads. Use attribute allowlists for focused DOM reads.',

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

@@ -323,13 +323,18 @@ export function createBridgeMcpServer(options = {}) {
     {
       title: 'Browser Tabs',
       description:
-        "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.",
+        "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. New tabs open in the background. You may activate tabs you opened for this task while the active tab is also in use for this task. Otherwise, activate only at the user's request or with their permission. Targeting tabId does not require activation.",
       inputSchema: z.object({
         action: z
           .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)'),
+        active: z
+          .boolean()
+          .optional()
+          .describe(
+            'Focus the new tab when the active tab is in use for this task, or with user permission (default: false)'
+          ),
         limit: z
           .number()
           .int()

package/packages/native-host/src/auth-token.js

@@ -235,6 +235,18 @@ async function ensureStoredBridgeAuthToken(tokenPath, options) {
         owner = await readFile(lockPath, 'utf8');
       } catch (error) {
         if (isMissingFileError(error)) continue;
+        // Windows can report EPERM while a competing owner deletes the lock.
+        // Retry within the same bounded acquisition loop, then recheck the winner.
+        if (
+          process.platform === 'win32' &&
+          error &&
+          typeof error === 'object' &&
+          'code' in error &&
+          error.code === 'EPERM'
+        ) {
+          await new Promise((resolve) => setTimeout(resolve, 10));
+          continue;
+        }
         throw error;
       }
       const match = /^(\d+):([0-9a-f-]{36})\n$/u.exec(owner);

package/packages/protocol/src/protocol.js

@@ -1841,7 +1841,7 @@ export function normalizeTabCreateParams(params = {}) {
   }
   return {
     url,
-    active: params.active !== false,
+    active: params.active === true,
   };
 }
 

package/packages/protocol/src/registry.js

@@ -148,9 +148,11 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'protocol.describe':
     'Describe bridge method parameters and metadata by method or registry group.',
   'tabs.list': 'List tabs in the enabled window.',
-  'tabs.create': 'Create a new tab in the enabled window.',
+  'tabs.create':
+    "Create a background tab in the enabled window. Set active:true when the current active tab is in use for this task, or at the user's request or with their permission.",
   'tabs.close': 'Close a tab in the enabled window.',
-  'tabs.activate': 'Bring a tab to the foreground in the enabled window.',
+  'tabs.activate':
+    "Bring a tab forward at the user's request or with their permission, or switch to a tab you opened for this task while the active tab is also in use for this task. Check active state first; if background work needs activation outside this case, ask. Targeting tabId does not require activation.",
   'skill.get_runtime_context': 'Return runtime method groups, budgets, and limits.',
   'setup.get_status': 'Return MCP and skill setup status.',
   'setup.install': 'Install or uninstall MCP or skill integration targets.',

package/skills/browser-bridge/SKILL.md

@@ -32,7 +32,7 @@ bbx tabs                    # list available tabs (prefer this)
 bbx logs                    # recent bridge request log
 bbx tab-create [url]        # open a new tab (avoid unless necessary)
 bbx tab-close <tabId>       # close a tab
-bbx tab-activate <tabId>    # bring a tab to the foreground
+bbx tab-activate <tabId>    # bring forward under the tab focus rules below
 bbx skill                   # live runtime presets + limits
 bbx protocol describe [method|group] # local method params or compact group index
 ```
@@ -176,13 +176,21 @@ After the Enable cue appears:
 After access is enabled:
 
 1. Your first tab-bound call binds your session to the active tab: that becomes your **working tab**.
-2. The working tab is sticky. If the user switches to another tab (to read mail, say), your calls keep running in your working tab; they never navigate or type into the tab the user is looking at.
+2. The working tab is sticky. If the user switches to their own tab, keep running in your working tab without taking focus back. Reads, input, navigation, and screenshots can run in background tabs. A different `active_tab_id` is informational, not an error to fix.
 3. Responses report `meta.tab_id`; when the user's active tab differs, the summary says so (`Ran in working tab 12; the user's active tab is 34`). If the user asks you to work in "this tab", pass that `tabId` once; the explicit tab becomes your new working tab. `tabs.create` and `tabs.activate` also move your working tab.
 4. If your working tab was closed, calls fail with `TAB_MISMATCH` (`reason: working_tab_closed`) instead of silently using another tab; pick a tab with `tabId` or `tabs.list` (which marks `working: true`).
 5. The binding expires after 15 idle minutes.
 6. Do not stop at a generic "no access" message before making a real Browser Bridge call, because the first denied call is what triggers the UI cue.
 7. CLI agents running separate `bbx` processes share one working tab unless each sets `BBX_SESSION=<name>`; MCP sessions are separated automatically.
 
+### Tab focus
+
+You may switch to tabs you opened for the current task without asking while the currently active tab is also one you are using for that task. Check `tabs.list` active state before switching. Track tabs you opened from your own `tabs.create` results; `working:true` identifies the routed tab, not ownership or foreground focus.
+
+If the user has switched to their own tab, continue in the background. Activate only at their request or with their permission. If something cannot work while the target tab is inactive, explain why and ask whether you may activate it. A timeout alone does not establish that activation is needed. Permission for one activation does not allow repeatedly taking focus back after the user switches away.
+
+These rules apply to `tabs.activate`, `active:true` on creation, and equivalent focus APIs. New tabs open in the background by default.
+
 ## Error Recovery
 
 | Error                     | Retry?   | Recovery                                                                                  |

package/skills/browser-bridge/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Browser Bridge'
   short_description: 'Token-efficient Chrome tab inspection, interaction, and patching via local bridge'
-  default_prompt: 'Use the browser-bridge skill for Chrome tab inspection, interaction, and patching. Start with `bbx status` to confirm connectivity; if the daemon is offline, run `bbx restart`. If ACCESS_DENIED, ask the user to click Enable in the extension popup/side panel, then retry. Default routing follows the active tab; use `--tab` only for a different tab. Prefer structured reads (`dom.query`, `styles.get_computed`) over screenshots. Batch independent reads with `bbx batch`. Use `bbx skill` for runtime presets.'
+  default_prompt: 'Use the browser-bridge skill for Chrome tab inspection, interaction, and patching. Start with `bbx status` to confirm connectivity; if the daemon is offline, run `bbx restart`. If ACCESS_DENIED, ask the user to click Enable in the extension popup/side panel, then retry. The first page call binds to a working tab; keep using it when the user switches tabs. Use `--tab` to target another tab without activating it. Check active state before switching: you may activate tabs you opened for this task while the active tab is also in use for this task. Otherwise, get user permission before taking focus, including when background work requires activation. Prefer structured reads (`dom.query`, `styles.get_computed`) over screenshots. Batch independent reads with `bbx batch`. Use `bbx skill` for runtime presets.'

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

@@ -88,12 +88,16 @@ Uses CDP device emulation - the page re-renders at the new size immediately.
 
 Always start with `tabs.list` to find an appropriate existing tab before considering `tabs.create`.
 
+Reads, input, navigation, and screenshots can target background tabs by `tabId`. New tabs open in the background by default. You may switch to tabs you opened for this task without asking while the active tab is also one you are using for this task. Check `tabs.list` active state before switching, and track opened tabs from your own `tabs.create` results. `working:true` identifies routing, not ownership or foreground focus.
+
+If the user switches to their own tab, continue in the background. Activate only at their request or with their permission. If an operation cannot work while the tab is inactive, explain why and ask whether activation is allowed. A timeout or a different `active_tab_id` alone does not justify activation. Permission for one activation does not allow repeatedly taking focus back after the user switches away. Apply these rules to `tabs.activate`, `active:true`, and equivalent focus APIs.
+
 ```bash
 bbx tabs                                 # list available tabs (start here)
 bbx tab-create https://example.com       # open new tab (avoid unless necessary)
 bbx tab-create                           # open blank tab (avoid unless necessary)
 bbx tab-close 12345                      # close tab by ID
-bbx tab-activate 12345                   # bring a tab to the foreground
+bbx tab-activate 12345                   # bring forward under the tab focus rules above
 bbx call tabs.create '{"url":"https://example.com","active":false}'
 ```
 
@@ -126,7 +130,7 @@ The default `source: "cdp"` returns Chrome's AX tree through the debugger. Use i
 Access is window-scoped. Your first call binds your session to the active tab in the enabled window, which becomes your working tab, and later calls stay there even when the user switches tabs. Responses include `meta.tab_id`; when the user is looking at a different tab, the summary names both. `tabs.list` marks your tab with `working: true`. Passing `tabId`, `tabs.create`, or `tabs.activate` moves your working tab. A closed working tab fails with `TAB_MISMATCH` (`working_tab_closed`) rather than switching to whatever tab is active.
 
 ```bash
-# Default routing follows the active tab in the enabled window:
+# The first page call binds to the active tab; later calls keep that working tab:
 bbx tabs
 bbx page-text
 

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

@@ -5,7 +5,7 @@ Prefer non-debugger methods first. `chrome.debugger`-backed methods (marked **CD
 ## Access Model
 
 1. The user turns Browser Bridge on for one browser window.
-2. Default routing follows the active tab in that enabled window.
+2. The first page call binds to the active tab in that enabled window. Later calls keep the working tab when the user switches tabs. You may activate tabs you opened for this task while the active tab is also in use for this task; check active state first. Otherwise, target background tabs without activating them unless the user requests or permits activation. If background work requires activation, explain why and ask.
 3. Use `tabId` only when you intentionally need a different tab in the same enabled window.
 4. Turning Browser Bridge off removes access immediately.
 
@@ -126,7 +126,7 @@ stopped.
 ```bash
 bbx status | doctor | restart | logs | tabs | skill # no routed tab needed
 bbx protocol describe [method|group]             # local signature or compact group index
-bbx call <method> '{"key":"val"}'           # generic RPC (routes to active tab in enabled window)
+bbx call <method> '{"key":"val"}'           # generic RPC (routes to the session's working tab)
 bbx call --tab 123 <method> '{...}'         # explicit tab target inside enabled window
 bbx batch '[{"method":"...","params":{}}]'  # parallel calls
 ```