@browserbridge/bbx 1.12.0 → 1.12.2

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.