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, 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. It reuses browserrender.Find to locate the Chrome binary (no new dependency, no Node).
Index ¶
- type Session
- 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) 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() []string
- 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) Screenshot(ctx context.Context, fullPage bool) ([]byte, error)
- func (s *Session) Scroll(ctx context.Context, dx, dy int) 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(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) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 ¶
New launches a Chrome instance with a visible window (headed) and returns a persistent Session with one open tab. You can watch Chrome work as the agent navigates, clicks, and types. The Chrome binary is discovered via browserrender.Find — a clear error is returned when none is available.
func (*Session) Alive ¶
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) ClearConsole ¶
func (s *Session) ClearConsole()
ClearConsole empties the console buffer.
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 ¶
CloseTab closes the tab at the given 1-based index. If closing the active tab, focus moves to the previous tab (or the first one). Closing the last tab is not allowed (the browser needs at least one tab).
func (*Session) Console ¶
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) Hover ¶
Hover moves the mouse over an element matching a CSS selector, triggering hover states, dropdown menus, tooltips, etc.
func (*Session) Navigate ¶
Navigate loads a URL in the current tab and waits for the body to be ready.
func (*Session) NewTab ¶
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 ¶
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) Screenshot ¶
Screenshot captures the current viewport as a PNG. When fullPage is true it captures the entire scrollable page instead (can be very large — token cost).
func (*Session) Scroll ¶
Scroll scrolls the page by the given x and y deltas in CSS pixels. Positive y scrolls down; positive x scrolls right. Use (0, 500) to scroll down half a viewport, or a large y to reach the bottom.
func (*Session) Select ¶
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 ¶
SwitchTab switches focus to the tab at the given 1-based index. Returns the tab's current URL and title.
Source Files