Browser Automation

Text-first browser automation through Playwright CLI or Chrome DevTools MCP, with explicit backend capability boundaries.

src/browser/ provides a unified BrowserBackend for browser tools. BrowserManager selects between two current backends by profile: managed browsers use PlaywrightCliBackend, while existing Chrome sessions use ChromeMcpBackend. Browser automation is exposed through built-in browser_* tools; it is not a Panel Canvas or Browser inspector API.

Unified Backend Contract

BrowserBackend covers opening, closing, listing, and navigating tabs; clicking, typing, filling, hovering, scrolling, screenshots, snapshots, JavaScript evaluation, and select controls using snapshot references; and optional history navigation, text waits, console output, network logs, PDF, dialogs, drag-and-drop, uploads, resizing, emulation, cookies, and storage state.

Snapshots are structured, model-facing page views using ActionTarget::Ref for interactive elements. The two backends do not promise identical action sets; the trait defaults unsupported actions to Unsupported, so callers must follow the selected backend's actual capabilities.

Playwright CLI Backend

PlaywrightCliBackend drives a managed browser through playwright-cli:

It can launch managed Chromium/Chrome sessions with headless or headed configuration.
Navigation, screenshots, DOM/ARIA snapshots, and text interaction use the CLI session.
Clicks can use snapshot references, while some typing operations can target the current focus.
Cookie management and saving/restoring cookies plus localStorage storage state are provided by this backend.
Browser state is isolated by profile and session key.

Chrome DevTools MCP Backend

ChromeMcpBackend operates an existing Chrome session through Chrome DevTools MCP:

Page IDs are numeric tab identifiers, and the target page is selected before actions.
Each profile has a serialization lock spanning page selection and the action call, preventing interleaved operations on different tabs.
Element actions use refs returned by browser_snapshot; coordinate clicking is unsupported.
Existing pages, tab switching, console and network output, screenshots, and DevTools interactions are supported where the MCP driver provides them.
Navigation targets pass through the browser SSRF guard, which also prepares a host-resolver pin for Chrome.

Playwright CLI coordinate or storage-state behavior must not be assumed for the Chrome MCP backend, and element locations must not be guessed instead of using snapshot refs.

Text-First Snapshots

Page content is represented primarily as text plus actionable elements rather than injecting the full HTML into context. A typical flow is to open or navigate a tab, call browser_snapshot, use the returned refs for actions, and take a screenshot or another snapshot when needed. Exact tool names come from the browser_* entries in BUILTIN_TOOL_DEFINITIONS and runtime registration.

Network Policy

Both backends check navigation targets with BrowserSsrfGuard. Private addresses, localhost, and other sensitive targets are blocked by default; Chrome MCP additionally stages a host-resolver pin. This is the browser egress boundary, distinct from MCP server SSRF/allowlists and messaging-channel permissions.

Profiles and Concurrency

ProfileManager separates managed sessions from existing Chrome profiles. Chrome MCP holds a profile lock across page selection and the action, preserving state consistency within a profile. The tool scheduler's ConcurrencyClaim still governs cross-tool batch parallelism; a tool name that looks read-only is not by itself proof that browser actions can run concurrently.

Panel Boundary

The Panel's Canvas / Browser inspector seams were withdrawn in 26.7.25. They had no consumers and are not a current browser-tool surface. Current browser documentation covers only BrowserBackend, browser tools, page snapshots, network policy, and profile management.

Code Location

src/browser/backend.rs — unified backend trait
src/browser/manager.rs — profile-to-backend routing
src/browser/playwright_cli_backend.rs — playwright-cli backend
src/browser/chrome_mcp_backend.rs — Chrome DevTools MCP backend
src/browser/playwright_cli.rs — CLI driver
src/browser/chrome_mcp.rs — Chrome MCP driver
src/browser/network_policy.rs — browser SSRF guard
src/browser/profile.rs, src/browser/tab_registry.rs — profile and tab state
src/builtin_tools/browser_tools/ — agent-facing browser_* tools