Skip to content

Agent Zero AI framework

Use stable Host Browser selections

Alessandrob960af866374
diff --git a/plugins/_browser/AGENTS.md b/plugins/_browser/AGENTS.md
index 688cec007..ce97ff7da 100644
--- a/plugins/_browser/AGENTS.md
+++ b/plugins/_browser/AGENTS.md
@@ -39,7 +39,7 @@
- Keep narrow WebUI Browser controls usable by grouping navigation with Annotate/settings above a full-width address bar.
- For Bring Your Own Browser with an existing host profile, `host_browser_selection` may target automatic CLI selection, a browser family/id, an HTTP CDP discovery address, or a full DevTools WebSocket endpoint and must be forwarded to the connector runtime as `browser_selection`.
- Browser Settings must refresh connected A0 CLI host-browser inventory while the settings view is open so newly authorized endpoints appear without saving or reopening.
-- Browser Settings keeps the Host browser dropdown focused on automatic selection, advertised debug endpoints, and a validated Custom endpoint field instead of listing every installed local profile. Preserve endpoint path/query case and let A0 CLI resolve discovery addresses on the host.
+- Browser Settings keeps the Host browser dropdown focused on automatic selection, stable IDs for advertised debug endpoints, and a validated Custom endpoint field instead of listing every installed local profile. An exact legacy endpoint advertised by a connected A0 CLI migrates to that browser's stable ID in both settings and runtime operations; unmatched custom endpoints remain exact and fail closed. Preserve endpoint path/query case and let A0 CLI resolve discovery addresses on the host.
- Browser URL-intent handling must only claim web URL schemes and leave custom Agent Zero schemes to their owning surfaces.
- Prefer DOM/CDP browser actions with refs, selectors, frame-chain refs, and screenshots over viewport coordinate input. Coordinates remain a visual fallback.
- Do not hardcode user-specific browser paths or secrets.
diff --git a/plugins/_browser/helpers/connector_runtime.py b/plugins/_browser/helpers/connector_runtime.py
index d5f05cb71..c28c8a68c 100644
--- a/plugins/_browser/helpers/connector_runtime.py
+++ b/plugins/_browser/helpers/connector_runtime.py
@@ -105,6 +105,22 @@ _REMOTE_DEBUGGING_ERROR_TOKENS = (
)
+def _stable_host_browser_selection(selection: Any, metadata: Any) -> str:
+ selected = str(selection or "").strip()
+ if not selected or not isinstance(metadata, dict):
+ return selected
+ candidates = list(metadata.get("available_browsers") or [])
+ candidates.append(metadata)
+ for candidate in candidates:
+ if not isinstance(candidate, dict):
+ continue
+ endpoint = str(candidate.get("cdp_endpoint") or "").strip()
+ browser_id = str(candidate.get("id") or candidate.get("browser_id") or "").strip()
+ if endpoint == selected and browser_id:
+ return browser_id
+ return selected
+
+
class ConnectorBrowserRuntime:
def __init__(self, context_id: str, agent: Any):
self.context_id = str(context_id or "").strip()
@@ -279,6 +295,7 @@ class ConnectorBrowserRuntime:
if not sid:
statuses = host_browser_metadata_for_context(self.context_id)
raise RuntimeError(self._host_browser_unavailable_message(statuses))
+ payload["browser_selection"] = self._host_browser_selection(sid)
if self._needs_prepare(sid, payload):
await self._send_browser_op(
@@ -290,7 +307,7 @@ class ConnectorBrowserRuntime:
"context_id": self.context_id,
"action": "ensure",
"profile_mode": self._host_browser_profile_mode(),
- "browser_selection": self._host_browser_selection(),
+ "browser_selection": self._host_browser_selection(sid),
},
),
)
@@ -303,9 +320,19 @@ class ConnectorBrowserRuntime:
mode = str(config.get(HOST_BROWSER_PROFILE_MODE_KEY) or "existing").strip().lower()
return "agent" if mode == "agent" else "existing"
- def _host_browser_selection(self) -> str:
+ def _host_browser_selection(self, sid: str = "") -> str:
config = get_browser_config(self.agent)
- return str(config.get(HOST_BROWSER_SELECTION_KEY) or "").strip()
+ selection = str(config.get(HOST_BROWSER_SELECTION_KEY) or "").strip()
+ if sid:
+ return _stable_host_browser_selection(
+ selection,
+ host_browser_metadata_for_sid(sid),
+ )
+ for metadata in host_browser_metadata_for_context(self.context_id):
+ stable = _stable_host_browser_selection(selection, metadata)
+ if stable != selection:
+ return stable
+ return selection
def _with_content_helper(self, sid: str, payload: dict[str, Any]) -> dict[str, Any]:
return self._with_browser_helpers(sid, payload)
diff --git a/plugins/_browser/webui/browser-config-store.js b/plugins/_browser/webui/browser-config-store.js
index b41f210aa..8220f9e33 100644
--- a/plugins/_browser/webui/browser-config-store.js
+++ b/plugins/_browser/webui/browser-config-store.js
@@ -105,6 +105,24 @@ function isCustomHostBrowserEndpoint(value) {
return Boolean(normalizeCustomHostBrowserEndpoint(value));
}
+function stableHostBrowserSelection(value, status) {
+ const selection = normalizeHostBrowserSelection(value);
+ if (!selection) return "";
+ const connectors = Array.isArray(status?.connectors) ? status.connectors : [];
+ for (const connector of connectors) {
+ const candidates = [
+ ...(Array.isArray(connector?.available_browsers) ? connector.available_browsers : []),
+ connector,
+ ];
+ for (const candidate of candidates) {
+ const endpoint = normalizeCustomHostBrowserEndpoint(candidate?.cdp_endpoint);
+ const browserId = normalizeHostBrowserSelection(candidate?.id || candidate?.browser_id);
+ if (endpoint && endpoint === selection && browserId) return browserId;
+ }
+ }
+ return selection;
+}
+
function normalizeBoolean(value, fallback = true) {
if (value === undefined || value === null || value === "") return fallback;
if (typeof value === "boolean") return value;
@@ -255,14 +273,20 @@ export const store = createStore("browserConfig", {
? connector.available_browsers
: [];
for (const browser of advertised) {
- const value = normalizeCustomHostBrowserEndpoint(browser?.cdp_endpoint || browser?.id);
+ const endpoint = normalizeCustomHostBrowserEndpoint(browser?.cdp_endpoint);
+ const value = endpoint
+ ? normalizeHostBrowserSelection(browser?.id) || endpoint
+ : "";
if (!value || seen.has(value)) continue;
seen.add(value);
const label = browser?.label || hostBrowserFamilyLabel(browser?.family || value);
const status = browser?.status ? ` - ${hostBrowserStatusLabel(browser.status)}` : "";
options.push({ value, label: `${label}${status}` });
}
- const fallbackValue = normalizeCustomHostBrowserEndpoint(connector?.cdp_endpoint || connector?.browser_id);
+ const fallbackEndpoint = normalizeCustomHostBrowserEndpoint(connector?.cdp_endpoint);
+ const fallbackValue = fallbackEndpoint
+ ? normalizeHostBrowserSelection(connector?.browser_id) || fallbackEndpoint
+ : "";
if (fallbackValue && !seen.has(fallbackValue)) {
seen.add(fallbackValue);
const label = connector?.browser_label || hostBrowserFamilyLabel(connector?.browser_family || fallbackValue);
@@ -338,6 +362,18 @@ export const store = createStore("browserConfig", {
try {
const response = await callJsonApi(BROWSER_STATUS_API, {});
this.hostBrowserStatus = response?.host_browser || { connectors: [] };
+ const safeConfig = ensureConfig(this.config);
+ if (safeConfig) {
+ const stable = stableHostBrowserSelection(
+ safeConfig.host_browser_selection,
+ this.hostBrowserStatus,
+ );
+ if (stable !== safeConfig.host_browser_selection) {
+ safeConfig.host_browser_selection = stable;
+ this.hostBrowserCustomEndpoint = "";
+ this.hostBrowserCustomMode = false;
+ }
+ }
} catch (_error) {
this.hostBrowserStatus = { connectors: [] };
} finally {
diff --git a/tests/test_browser_agent_regressions.py b/tests/test_browser_agent_regressions.py
index 9198aff38..c63ccae3a 100644
--- a/tests/test_browser_agent_regressions.py
+++ b/tests/test_browser_agent_regressions.py
@@ -2,6 +2,7 @@ import asyncio
import concurrent.futures
import json
import re
+import subprocess
import sys
import threading
import zipfile
@@ -277,6 +278,56 @@ def test_browser_config_normalizes_host_browser_selection():
)
+def test_browser_config_store_migrates_advertised_endpoint_to_stable_id():
+ path = PROJECT_ROOT / "plugins" / "_browser" / "webui" / "browser-config-store.js"
+ source = path.read_text(encoding="utf-8")
+ source = re.sub(r"^import .*;\n", "", source, flags=re.M)
+ source = source.replace("export const store = createStore", "const store = createStore")
+ endpoint = "ws://localhost:9222/devtools/browser/old-guid"
+ browser_status = {
+ "connectors": [
+ {
+ "browser_id": "chrome-cdp",
+ "cdp_endpoint": endpoint,
+ "available_browsers": [
+ {
+ "id": "chrome-cdp",
+ "family": "chrome-cdp",
+ "label": "Chrome (allowed)",
+ "cdp_endpoint": endpoint,
+ },
+ {
+ "id": "chrome:default",
+ "family": "chrome",
+ "label": "Chrome profile",
+ "cdp_endpoint": "",
+ },
+ ],
+ }
+ ]
+ }
+ script = (
+ "const browserStatus = "
+ + json.dumps(browser_status)
+ + ";\n"
+ + "const createStore = (_name, value) => value;\n"
+ + "const callJsonApi = async () => ({ host_browser: browserStatus });\n"
+ + "const showConfirmDialog = async () => false;\n"
+ + source
+ + f"\nstore.config = ensureConfig({{ host_browser_selection: {json.dumps(endpoint)} }});\n"
+ + "await store.loadHostBrowserStatus();\n"
+ + "if (store.config.host_browser_selection !== 'chrome-cdp') throw new Error('legacy endpoint was not migrated');\n"
+ + "const values = store.hostBrowserOptions().map((option) => option.value);\n"
+ + "if (!values.includes('chrome-cdp')) throw new Error('stable browser id is missing');\n"
+ + f"if (values.includes({json.dumps(endpoint)})) throw new Error('volatile endpoint was advertised');\n"
+ + "if (values.includes('chrome:default')) throw new Error('local profiles leaked into the dropdown');\n"
+ + "const custom = 'ws://localhost:9333/devtools/browser/custom';\n"
+ + "if (stableHostBrowserSelection(custom, browserStatus) !== custom) throw new Error('custom endpoint changed');\n"
+ )
+
+ subprocess.run(["node", "--input-type=module", "-e", script], check=True, text=True)
+
+
def test_browser_config_normalizes_max_open_tabs():
assert normalize_browser_config({"max_open_tabs": "12"})["max_open_tabs"] == 12
assert normalize_browser_config({"max_open_tabs": "0"})["max_open_tabs"] == 1
diff --git a/tests/test_host_browser_connector.py b/tests/test_host_browser_connector.py
index d7e17bf98..1dc2696a0 100644
--- a/tests/test_host_browser_connector.py
+++ b/tests/test_host_browser_connector.py
@@ -17,6 +17,7 @@ from plugins._browser.helpers import connector_runtime as connector_runtime_modu
from plugins._browser.helpers.connector_runtime import (
ConnectorBrowserRuntime,
_agent_uses_local_chat_model,
+ _stable_host_browser_selection,
)
@@ -69,6 +70,50 @@ def test_host_browser_metadata_selection_is_context_scoped():
ws_runtime.unregister_sid(sid)
+def test_connector_runtime_uses_stable_id_for_advertised_legacy_endpoint(monkeypatch):
+ sid = "sid-host-browser-stable"
+ context_id = "ctx-host-browser-stable"
+ endpoint = "ws://localhost:9222/devtools/browser/old-guid"
+ metadata = {
+ "supported": True,
+ "enabled": True,
+ "status": "ready",
+ "browser_family": "chrome-cdp",
+ "browser_id": "chrome-cdp",
+ "cdp_endpoint": endpoint,
+ "available_browsers": [
+ {
+ "id": "chrome-cdp",
+ "family": "chrome-cdp",
+ "label": "Chrome (allowed)",
+ "cdp_endpoint": endpoint,
+ }
+ ],
+ "features": ["ensure", "open"],
+ }
+ monkeypatch.setattr(
+ connector_runtime_module,
+ "get_browser_config",
+ lambda agent=None: {
+ "host_browser_profile_mode": "existing",
+ "host_browser_selection": endpoint,
+ },
+ )
+ ws_runtime.register_sid(sid)
+ ws_runtime.subscribe_sid_to_context(sid, context_id)
+ try:
+ ws_runtime.store_sid_host_browser_metadata(sid, metadata)
+ runtime = ConnectorBrowserRuntime(context_id, _agent(context_id))
+
+ assert runtime._payload_for_call("open", "example.com")["browser_selection"] == "chrome-cdp"
+ assert _stable_host_browser_selection(
+ "ws://localhost:9333/devtools/browser/custom",
+ metadata,
+ ) == "ws://localhost:9333/devtools/browser/custom"
+ finally:
+ ws_runtime.unregister_sid(sid)
+
+
def test_host_browser_candidate_selection_allows_disabled_supported_cli():
sid = "sid-host-browser-disabled"
context_id = "ctx-host-browser-disabled"