browser

Documentation

Overview

Package browser drives a long-lived Chrome instance via the Chrome DevTools Protocol (chromedp) so the agent can fully interact with web pages as tools — the same dispatch as read_file/bash. It exposes the full browser interaction surface a user has: navigate, click, type, scroll, hover, keyboard, dropdowns, history, tabs, uploads, viewport, screenshots, console logs, and arbitrary JS.

The Session wraps a persistent chromedp context created once (on New) and reused across tool calls — a single Chrome process for the whole agent session, torn down on Close. It tracks multiple tabs (each a child chromedp context) and a rolling console-log buffer captured via CDP Runtime events. The profile is EPHEMERAL (a fresh temp profile per launch): no existing cookies or logins, nothing persisted across sessions. It reuses browserrender.Find to locate the Chrome binary (no new dependency, no Node).

Every operation runs under a bounded, caller-cancellable context derived from the tab's context: the timeout/cancel propagates into the in-flight CDP command (chromedp aborts it) while the tab itself survives for the next op.

Index

• Constants
• type Controller
• type EphemeralController
• type Options
• type RemoteConfig
• type Session
  • func New(opt Options) (*Session, error)
  • func (s *Session) Alive() bool
  • func (s *Session) Back(ctx context.Context) error
  • func (s *Session) ClearConsole()
  • func (s *Session) Click(ctx context.Context, selector string) error
  • func (s *Session) Close()
  • func (s *Session) CloseTab(index int) (newActive int, err error)
  • func (s *Session) Console(level string) []string
  • func (s *Session) Eval(ctx context.Context, js string) (string, error)
  • func (s *Session) Forward(ctx context.Context) error
  • func (s *Session) Hover(ctx context.Context, selector string) error
  • func (s *Session) ListTabs(ctx context.Context) []TabInfo
  • func (s *Session) Navigate(ctx context.Context, url string) error
  • func (s *Session) NewTab(ctx context.Context) (int, error)
  • func (s *Session) PressKey(ctx context.Context, key string) error
  • func (s *Session) Resize(ctx context.Context, width, height int) error
  • func (s *Session) Screenshot(ctx context.Context, fullPage bool) ([]byte, string, error)
  • func (s *Session) Scroll(ctx context.Context, dx, dy int) (string, error)
  • func (s *Session) ScrollTo(ctx context.Context, selector string) error
  • func (s *Session) Select(ctx context.Context, selector, value string) error
  • func (s *Session) SwitchTab(ctx context.Context, index int) (url, title string, err error)
  • func (s *Session) TabCount() int
  • func (s *Session) Text(ctx context.Context) (string, error)
  • func (s *Session) Type(ctx context.Context, selector, text string, appendTo bool) error
  • func (s *Session) Upload(ctx context.Context, selector string, files []string) error
  • func (s *Session) WaitFor(ctx context.Context, selector, state string, timeout time.Duration) error
• type TabInfo

Constants

const ChromeDevToolsMCPPackage = "chrome-devtools-mcp@" + ChromeDevToolsMCPVersion

const ChromeDevToolsMCPVersion = "1.8.0"

Types

type Controller

type Controller interface {
	Close() error
	Navigate(context.Context, string) error
	NewTab(context.Context, string) error
}

Controller is the stable browser boundary shared by ephemeral and brokered backends. Calls remain typed; autonomous agents never receive raw MCP access.

type EphemeralController

type EphemeralController struct{ *Session }

EphemeralController identifies the existing fresh-profile backend used by ordinary sessions. Session remains the concrete implementation while callers migrate behind Controller.

type Options

type Options struct {
	// Headless runs Chrome without a window — required when there is no desktop
	// session (a gateway job under launchd/systemd). Interactive sessions run
	// headed so the user can watch the agent work.
	Headless bool
}

Options configures a Session launch.

type RemoteConfig

type RemoteConfig struct{ SocketPath, AgentID, RunID, Token string }

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is a persistent Chrome instance controlled via CDP, with multi-tab support and a rolling console-log buffer.

func New

func New(opt Options) (*Session, error)

New launches a Chrome instance and returns a persistent Session with one open tab. The Chrome binary is discovered via browserrender.Find (which honors CHROME_PATH) — a clear error is returned when none is available.

func (*Session) Alive

func (s *Session) Alive() bool

Alive reports whether the Chrome process backing this session is still reachable. The runtime calls this on the cached session before each browser tool call so that a Chrome that died (the user quit the window, the OS killed it, a crash) is detected and relaunched — without it, every tool call would drive a dead chromedp context and return "context canceled" forever.

Two independent signals: chromedp's LostConnection channel (closed when the CDP websocket to Chrome drops) and a zero-signal probe of the OS process (ESRCH = the process is gone). Either being dead means the session is dead.

func (*Session) Back

func (s *Session) Back(ctx context.Context) error

Back navigates the current tab to the previous page in browser history.

func (*Session) ClearConsole

func (s *Session) ClearConsole()

ClearConsole empties the console buffer.

func (*Session) Click

func (s *Session) Click(ctx context.Context, selector string) error

Click an element matching a CSS selector.

func (*Session) Close

func (s *Session) Close()

Close tears down the Chrome process and releases all CDP resources. Safe to call multiple times.

func (*Session) CloseTab

func (s *Session) CloseTab(index int) (newActive int, err error)

CloseTab closes the tab at the given 1-based index via CDP (the real Chrome tab closes, not just our handle). Closing the ACTIVE tab deterministically activates the nearest lower index. Tab 1 hosts the session's CDP connection and can't be closed individually; neither can the last remaining tab. Returns the new active tab's 1-based index.

func (*Session) Console

func (s *Session) Console(level string) []string

Console returns the captured console messages, optionally filtered by level. When level is empty, all entries are returned. Each entry is formatted as "[tab N] LEVEL: text". Entries are returned oldest-first.

func (*Session) Eval

func (s *Session) Eval(ctx context.Context, js string) (string, error)

Eval runs JavaScript in the page and returns the result rendered as a string: strings verbatim, numbers/booleans/objects/arrays as JSON, undefined/null as "undefined". Accepts both expressions ("1+1", "document.title") and statements ("var x = 5; x * 2").

func (*Session) Forward

func (s *Session) Forward(ctx context.Context) error

Forward navigates the current tab to the next page in browser history.

func (*Session) Hover

func (s *Session) Hover(ctx context.Context, selector string) error

Hover moves the mouse over an element matching a CSS selector, triggering hover states, dropdown menus, tooltips, etc.

func (*Session) ListTabs

func (s *Session) ListTabs(ctx context.Context) []TabInfo

ListTabs returns the current tabs with LIVE urls and titles.

func (*Session) Navigate

func (s *Session) Navigate(ctx context.Context, url string) error

Navigate loads a URL in the current tab and waits for the body to be ready.

func (*Session) NewTab

func (s *Session) NewTab(ctx context.Context) (int, error)

NewTab opens a new tab (about:blank) and switches focus to it. Returns the tab index (1-based, for the agent's reference).

func (*Session) PressKey

func (s *Session) PressKey(ctx context.Context, key string) error

PressKey sends a key event (e.g. "Enter", "Escape", "Tab", "ArrowDown") to the page. The key is sent to whatever element currently has focus. Use after browser_click or browser_type to submit forms, close modals, navigate dropdowns, etc.

func (*Session) Resize

func (s *Session) Resize(ctx context.Context, width, height int) error

Resize sets the viewport to the given CSS dimensions.

func (*Session) Screenshot

func (s *Session) Screenshot(ctx context.Context, fullPage bool) ([]byte, string, error)

Screenshot captures the current viewport (or the full scrollable page) and returns the image bytes plus their actual mime type. Captures above maxImageBytes are retried as JPEG at decreasing quality so a single screenshot can't flood the model's context.

func (*Session) Scroll

func (s *Session) Scroll(ctx context.Context, dx, dy int) (string, error)

Scroll scrolls the page by the given x and y deltas in CSS pixels and returns the resulting position ("scrolled to X,Y (viewport Hpx, total Tpx)") so the agent knows whether it hit the bottom.

func (*Session) ScrollTo

func (s *Session) ScrollTo(ctx context.Context, selector string) error

ScrollTo scrolls the element matching the selector into view (centered).

func (*Session) Select

func (s *Session) Select(ctx context.Context, selector, value string) error

Select picks an option in a <select> element by value (the option's value attribute). The selector must match a <select> element.

func (*Session) SwitchTab

func (s *Session) SwitchTab(ctx context.Context, index int) (url, title string, err error)

SwitchTab switches focus to the tab at the given 1-based index and returns its LIVE url and title (queried from the page, not cached).

func (*Session) TabCount

func (s *Session) TabCount() int

TabCount returns the number of open tabs.

func (*Session) Text

func (s *Session) Text(ctx context.Context) (string, error)

Text returns the visible text content of the current page (body.innerText).

func (*Session) Type

func (s *Session) Type(ctx context.Context, selector, text string, appendTo bool) error

Type text into an element matching a CSS selector. By default the field is cleared first (what a user means by "type X into the box"); append=true keeps the existing value and appends.

func (*Session) Upload

func (s *Session) Upload(ctx context.Context, selector string, files []string) error

Upload sets the files of a file input matching the selector. Path validation (project-root confinement, symlink resolution) is the CALLER's job — this layer only drives CDP.

func (*Session) WaitFor

func (s *Session) WaitFor(ctx context.Context, selector, state string, timeout time.Duration) error

WaitFor waits until an element matching the selector reaches the given state ("visible", "hidden", or "ready" = attached to the DOM), bounded by timeout (capped at 60s). This is how the agent settles SPA navigation instead of racing it.

type TabInfo

type TabInfo struct {
	Index  int // 1-based
	Active bool
	URL    string
	Title  string
}

TabInfo is a live snapshot of one tab.