# CFBrowser v0.1.1 A runnable, cgo-free Go browser automation prototype for ClusterFlow agents. [简体中文](README.zh-CN.md) · [Usage](docs/USAGE.en.md) · [ClusterFlow integration](docs/INTEGRATION.en.md) · [Design](docs/DESIGN.en.md) · [Validation](docs/VALIDATION.en.md) ## Implemented engines | Engine | What runs | Current boundary | | --- | --- | --- | | CDP | Dedicated Chrome/Chromium/Edge process, controlled with chromedp | DOM snapshots, browser input, text/tables, waits, screenshots, authenticated/blob downloads | | Native | Separate Go worker: Windows WebView2 (COM), macOS WKWebView (purego/objc), Linux WebKitGTK (purego) | Hidden window, isolated script world, open Shadow DOM snapshots, viewport PNG, synthetic actions, text/tables and waits; Windows also has browser-generated input and bounded full-page PNG | Windows/macOS adapters are implemented as **experimental** backends. Windows requires the Evergreen WebView2 Runtime; macOS requires 11+ and a logged-in graphical session. This delivery cross-compiles both adapters; Windows/macOS runtime validation remains pending. See [Native backends](docs/NATIVE.en.md) for exact build/test commands and limits. ## Build and try Requires Go **1.24 or later**. The module name is a local integration identifier and has not been published. Dependencies are vendored; no Node.js, Python or browser-driver service is needed by the SDK. ```sh CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser ./cmd/cfbrowser CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker ./cmd/cfbrowser-worker ./bin/cfbrowser --browser /path/to/chrome doctor ./bin/cfbrowser --browser /path/to/chrome demo ``` `demo` launches a local dynamic fixture, fills a query, clicks Search, waits for the result, extracts a table and captures a screenshot when supported. It needs no external website or LLM key. The local origin is authorized only for this fixture. To export the demo screenshot, add `--export-dir /existing/authorized/folder` before `demo`. For native WebView on macOS or Linux, run in a graphical session (Linux additionally needs GTK3/WebKitGTK 4.1 runtime libraries): ```sh ./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker demo ``` A headless Linux machine needs a display server for this native backend, for example `xvfb-run -a ...`. Hiding a native window does not make GTK independent of a display server. `--no-sandbox` is an explicit CI escape hatch, never a default or a production recommendation. Windows: run `./scripts/test-native.ps1` from PowerShell. macOS: run `sh scripts/test-native.sh`. These scripts build the actual native worker, run ABI tests, execute the native demo and run native-only integration tests without a Chrome/Edge executable. `doctor` reports static capabilities; only `demo` and integration tests verify runtime startup. Native supports open Shadow DOM and viewport screenshots; Windows also supports browser-generated input and bounded full-page capture. Native downloads remain unavailable. ## Direct integration ```go manager, err := cfbrowser.New(cfbrowser.Config{}, &cdp.Driver{}) if err != nil { return err } defer manager.Close() owner := api.Owner{EnvironmentID: "ssh1", ThreadID: "thread1", RunID: "run1"} session, err := manager.CreateSession(ctx, owner) if err != nil { return err } page, err := manager.NewPage(ctx, owner, session.ID) if err != nil { return err } _, err = manager.Navigate(ctx, owner, session.ID, page.PageID, "https://example.org", "goto") ``` See the compilable [basic example](examples/basic/main.go) and [tool boundary example](examples/agent-loop/main.go). ## Tests ```sh go test ./... -coverprofile=test-results/unit.cover go test -race ./... CFBROWSER_INTEGRATION=1 CFBROWSER_EXECUTABLE=/path/to/chrome go test ./integration -v ``` `-race` requires a cgo-enabled **test toolchain**; the distributed application still builds with `CGO_ENABLED=0`. Enable native real-engine tests with `CFBROWSER_NATIVE=1` and `CFBROWSER_WORKER=/absolute/path/to/cfbrowser-worker`. Read the validation document for complete commands and actual results. ## Important runtime boundaries - The host supplies `api.Owner`; models cannot override environment, thread or run identity. - A new snapshot invalidates older refs on that page. DOM replacement or navigation also invalidates refs. - Action success means the input was dispatched; it does not prove a website transaction succeeded. Unknown outcomes are not retried automatically. - `networkPolicy=degraded`: only explicit top-level navigation is validated. Subresources, redirects and page-generated requests require a trusted network or OS egress controls. - Screenshots return file metadata; visual model input is not implemented. Native downloads/uploads, AX snapshots, cross-frame browsing, persistent profiles and proxy configuration are not implemented. - Call `ClosePage`, `CloseSession` and `Manager.Close` from the owning host lifecycle. There is no idle reaper or crash recovery service in this prototype. Browser binaries and native system runtimes are not bundled. See [NOTICE](NOTICE) and dependency licenses in `vendor/`.