Documentation
¶
Overview ¶
Package browser implements the opt-in browser tool family (issue #94): a chromedp-driven headless Chromium whose traffic is forced through the agent's EgressProxy, exposed to the LLM as token-optimized tools that exchange indexed page digests instead of raw HTML.
Index ¶
- Variables
- func HeadlessFromEnv() bool
- func RegisterTools(reg *coretools.Registry, m *Manager) error
- func ResolveBinary() (string, error)
- type Config
- type Manager
- func (m *Manager) Click(index int, gen int64, maxEls int) (pageSnapshot, error)
- func (m *Manager) Extract(mode, selector string) (content string, url string, err error)
- func (m *Manager) Fill(index int, text string, gen int64, submit bool, allowSensitive bool, ...) (pageSnapshot, error)
- func (m *Manager) Navigate(url string, waitMS int, maxEls int) (pageSnapshot, error)
- func (m *Manager) Screenshot(fullPage bool) ([]byte, error)
- func (m *Manager) Snapshot(maxEls int, scrollToIndex int, scrollPages float64) (pageSnapshot, error)
- func (m *Manager) Stop()
Constants ¶
This section is empty.
Variables ¶
var ErrStale = errors.New("stale element index: the page changed since the last snapshot")
ErrStale is returned when an interaction references a generation older than the current page state (the page navigated or was re-snapshotted since the LLM last saw it). Tools catch it and return a fresh digest so the model recovers in one turn.
var ToolNames = []string{
"browser_navigate",
"browser_state",
"browser_click",
"browser_fill",
"browser_extract",
"browser_screenshot",
}
ToolNames lists the browser tool family in registration order. Useful for tests and for denied_tools documentation.
Functions ¶
func HeadlessFromEnv ¶
func HeadlessFromEnv() bool
HeadlessFromEnv reports whether the browser should run headless. Defaults to true; FORGE_BROWSER_HEADLESS=false or 0 opts into headful mode for local debugging.
func RegisterTools ¶
RegisterTools registers the browser tool family against a live Manager. Fail-closed: a manager without a proxy must never have been constructed (NewManager enforces it), but re-assert here since this is the last gate before the LLM can drive the browser.
func ResolveBinary ¶
ResolveBinary locates a Chromium-compatible browser binary. FORGE_BROWSER_BIN takes precedence and must point at an existing file; otherwise candidates are probed via exec.LookPath (absolute candidates via os.Stat).
Types ¶
type Config ¶
type Config struct {
// BinaryPath is the resolved absolute path to a Chromium-compatible binary.
BinaryPath string
// Headless launches with --headless=new when true.
Headless bool
// ProxyURL is the EgressProxy address (http://127.0.0.1:<port>). Required:
// the manager refuses to launch an unproxied browser.
ProxyURL string
// WorkDir is the agent working directory; the throwaway browser profile
// and screenshot fallback directory live under it.
WorkDir string
// AllowSensitiveFill permits browser_fill on password/payment fields.
AllowSensitiveFill bool
ActionTimeout time.Duration
}
Config holds everything the Manager needs to launch and drive Chromium.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns at most one Chromium process per agent, launched lazily on the first tool call and stopped by the runner on shutdown. All tool executions are serialized: the LLM drives a single logical tab.
func NewManager ¶
NewManager validates cfg and returns an unlaunched Manager.
func (*Manager) Click ¶
Click resolves index to fresh viewport coordinates and dispatches a trusted CDP mouse click, then returns the post-action snapshot.
func (*Manager) Extract ¶
Extract returns the page content in the requested mode ("text", "links", "html") plus the current URL. Pagination happens in the tool layer.
func (*Manager) Fill ¶
func (m *Manager) Fill(index int, text string, gen int64, submit bool, allowSensitive bool, maxEls int) (pageSnapshot, error)
Fill types text into the element at index: focus via trusted click, select existing content, replace it with CDP Input.insertText (fires native input events, so React/Vue controlled inputs see the change), then dispatch change. Select elements pick the matching option instead. Protected fields (password/payment autocomplete) are refused unless allowSensitive.
func (*Manager) Screenshot ¶
Screenshot captures the viewport (or full page) as PNG bytes.
Source Files