browser

Documentation

Overview

Package browser gives the agent a real browser via the Chrome DevTools Protocol (chromedp): it attaches to the user's running Chrome/Chromium/ Brave when a DevTools port is open, otherwise launches a managed instance — visible by default, so the user can watch the agent work. When the machine has no Chromium-family browser at all, one is provisioned on the spot (see install.go): `factor init` does it up front, and a session that finds none does it rather than reporting the suite unavailable. Build with -tags nobrowser to strip the whole suite from the binary.

Index

• Constants
• func Available() bool
• func EngineBinary(home string) string
• func EngineDir(home string) string
• func EnsureEngine(ctx context.Context, home string, progress Progress) (string, bool, error)
• func EnsureFastEngine(ctx context.Context, home string, progress Progress) (string, bool, error)
• func FastEngineBinary(home string) string
• func FastEngineSupported() (bool, string)
• func FindBrowserBinary(configured string) (string, error)
• func NewTools(cfg config.BrowserConfig, workspace string, guard *tools.PathGuard) ([]tools.Tool, func())
• func Verify(ctx context.Context, cfg config.BrowserConfig) error
• type Progress
• type Session
  • func NewSession(cfg config.BrowserConfig, workspace string, guard *tools.PathGuard) *Session
  • func (s *Session) Close()

Constants

const (

	// InstallTimeout bounds one provisioning attempt. The tarball is ~125MB
	// and the machines that need it most are the ones on slow links.
	InstallTimeout = 20 * time.Minute
)

Functions

func Available

func Available() bool

Available reports whether this build carries the browser suite at all.

func EngineBinary

func EngineBinary(home string) string

EngineBinary is the provisioned browser's executable.

func EngineDir

func EngineDir(home string) string

EngineDir is where a provisioned browser lives.

func EnsureEngine

func EnsureEngine(ctx context.Context, home string, progress Progress) (string, bool, error)

EnsureEngine returns a Chromium-family binary the browser suite can drive, downloading Helium when the machine has none. The bool reports whether this call installed it. Callers holding a configured browser.command should resolve that with FindBrowserBinary first — this function only knows about the machine, not the config.

func EnsureFastEngine

func EnsureFastEngine(ctx context.Context, home string, progress Progress) (string, bool, error)

EnsureFastEngine installs Lightpanda: a browser written from scratch for automation, with a CDP server and no renderer at all. It reads pages for a fraction of Chromium's memory, which is worth a second engine on a small box — but only reads them, so it supplements the real browser instead of replacing it. Its builds need glibc 2.34, which older distributions do not have; the version check below is what turns that into a clear answer.

func FastEngineBinary

func FastEngineBinary(home string) string

FastEngineBinary is the provisioned lightweight engine.

func FastEngineSupported

func FastEngineSupported() (bool, string)

FastEngineSupported reports whether this machine can run the lightweight engine, and why not when it cannot.

func FindBrowserBinary

func FindBrowserBinary(configured string) (string, error)

FindBrowserBinary locates a Chromium-family binary: first on PATH, then in the fixed locations PATH never covers — where macOS and Windows keep their browsers, and where Factor installs the one it provisions itself.

func NewTools

func NewTools(cfg config.BrowserConfig, workspace string, guard *tools.PathGuard) ([]tools.Tool, func())

NewTools returns the browser tool suite sharing one session.

func Verify

func Verify(ctx context.Context, cfg config.BrowserConfig) error

Verify launches the configured browser and drives one round-trip through it, so `factor init` can report a browser that actually works rather than one that merely exists on disk. Every other wizard step checks itself the same way.

Types

type Progress

type Progress func(format string, args ...any)

Progress reports provisioning steps to whoever is watching (the wizard prints them; the gateway logs them).

type Session

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

Session lazily owns one browser connection shared by all browser tools.

The connection and the tabs on it are deliberately separate lifetimes. browserCtx is a bare connection that never owns a tab, so releasing it closes nothing; every tab hangs off it as its own context. That split is what lets the agent move between the user's tabs at all: chromedp closes a tab when its context is cancelled, so a session that kept one tab context and re-made it on every switch would close the user's tabs as it went.

func NewSession

func NewSession(cfg config.BrowserConfig, workspace string, guard *tools.PathGuard) *Session

func (*Session) Close

func (s *Session) Close()

Close shuts the managed browser down.