Browser — Overview (tools/browser/)

Fail-closed browser session ownership: BrowserManager owns lifecycle and metadata, BrowserBackend is the only engine seam, models.py is the shared vocabulary. With the stock config (browser.enabled: false, backend: none) every path fails closed — nothing launches, nothing pretends a browser exists.

Package map

Architecture

agent ──► tools/mcp_tools/browser.py ──► BrowserManager ──► BrowserBackend ──► Chromium
  (@require_allowlist        (transitions +          (engine adapter,
   target lock)               ownership guards)       never policy)

• The manager MAY validate transitions, allocate ids, hold metadata, track ownership by run id, and drive the async funnel. It MUST NOT launch browsers, open sockets, visit URLs, or run JS — every capability delegates to the injected backend (manager.py:15-25).
• The backend never touches the allowlist; the MCP layer calling the funnel is target-locked and sandboxed (interfaces.py:46-51).
• Stock builds have no backend injected, so available() is never true and every action raises BrowserBackendUnavailable.

manager.py — BrowserManager

def __init__(self, config: dict[str, Any] | None = None, *, backend: BrowserBackend | None = None) -> None

op names a BrowserBackend coroutine (navigate, observe, execute_action, capture_screenshot, get_network_events, get_storage, get_page_state). Per-session asyncio.Lock serializes ops; _sync_last_url best-effort mirrors the live URL onto the record.

interfaces.py — BrowserBackend

class BrowserBackend(ABC):
    backend_id: str = ""
    display_name: str = ""
    capabilities: tuple[str, ...] = ()

    def is_configured(self, config: dict[str, Any] | None) -> bool: ...
    def health(self, config: dict[str, Any] | None) -> dict[str, Any]: ...
    async def start_session(self, *, target, run_id="", session_id="", headless=True, metadata=None) -> BrowserSession: ...
    async def stop_session(self, session_id: str) -> BrowserResult: ...
    async def navigate(self, session_id: str, url: str, *, timeout_seconds=None) -> BrowserResult: ...
    async def observe(self, session_id: str, *, include_forms=True, include_endpoints=True) -> BrowserObservation: ...
    async def execute_action(self, session_id: str, action: BrowserAction) -> BrowserResult: ...
    async def capture_screenshot(self, session_id: str, *, artifact_path="") -> BrowserArtifact: ...
    async def get_network_events(self, session_id: str, *, limit=100, after_id="") -> list[BrowserNetworkEvent]: ...
    async def get_storage(self, session_id: str, *, origin="") -> BrowserStorageSnapshot: ...
    async def get_page_state(self, session_id: str) -> BrowserPageState: ...
    async def close(self, session_id: str) -> BrowserResult: ...

All operations are @abstractmethod (no executable defaults); only metadata probes (is_configured/health) have bodies. Methods return models.* types only — no Playwright/Selenium/CDP object may leak across the seam.

models.py — vocabulary

Serialization is deterministic (hand-rolled field-order dicts) and tolerant on read (unknown enums → safe defaults).

capabilities.py — declared ≠ available

10 stable browser.* names (navigate, dom.inspect, javascript.execute, network.observe, network.replay, storage.read, form.inspect, form.submit, screenshot, endpoint.discover), each with description + read_only planner hint.

available = browser.enabled AND backend != "none"
            AND backend in BACKEND_REGISTRY
            AND (BACKEND_REGISTRY[backend].is_configured(...) OR sandbox worker configured)

errors.py — failure taxonomy

BrowserBackendError (base, .code) → BrowserBackendUnavailable (tool_unavailable), BrowserBackendNotImplemented, BrowserTransitionError (invalid_transition), BrowserSessionNotFound (session_not_found), BrowserTimeout (timeout), BrowserNavigationFailed (navigation_failed), BrowserCrashed (transport_error, marks session FAILED), BrowserScopeBlocked (scope_blocked), BrowserScriptError (script_error). browser_error_from_exception(exc) maps any exception to (failure_class_value, message) for result blocks.

Lifecycle

PENDING → STARTING → READY ⇄ ACTIVE
               ↓         ↓      ↓
            FAILED    SUSPENDED STOPPING → CLOSED / FAILED

start_session_async drives PENDING → STARTING → READY; run_op wraps each op in READY/SUSPENDED → ACTIVE → READY; close_session_async ends in CLOSED (or FAILED when the backend crashed). reap_idle closes sessions idle beyond session_timeout_seconds on every start.

MCP surface (tools/mcp_tools/browser.py)

Registered only when browser.enabled + backend: playwright + browser_runtime_available(config) (all three, else the module registers nothing).

Config keys (browser: block)

Example

manager = BrowserManager(config, backend=playwright_backend)
session = await manager.start_session_async(target_ip="10.0.0.50", run_id="run-1")
result = await manager.run_op(session.session_id, "navigate", url="http://10.0.0.50/")
obs = await manager.run_op(session.session_id, "observe")
await manager.close_session_async(session.session_id)

Tests (selected)

Related documentation

• Browser agent design
• Configuration overview
• Kernel overview
• MCP tools
• Safety model

Source map

• tools/browser/manager.py
• tools/browser/interfaces.py
• tools/browser/models.py
• tools/browser/capabilities.py
• tools/browser/errors.py
• tools/mcp_tools/browser.py
• docs/browser-agent-design.md