# Usage guide Version: 0.1.0 prototype. Read the capability table before selecting an engine. ## 1. Requirements and build Go 1.24+ is required by the secure file-root implementation. Dependencies are vendored. The SDK has no Node.js, Python, Playwright server or ChromeDriver runtime dependency. ```sh mkdir -p bin test-results 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 go test -mod=vendor ./... ``` On PowerShell, set `$env:CGO_ENABLED="0"`, then use `go build -buildvcs=false -mod=vendor -o bin/cfbrowser.exe ./cmd/cfbrowser`. Build `./cmd/cfbrowser-worker` as `bin/cfbrowser-worker.exe` too. Windows uses the installed Evergreen WebView2 Runtime; macOS uses system WKWebView (11+). See [native build and runtime tests](NATIVE.en.md). For CDP, install Chrome/Chromium/Edge separately or point to an already installed executable. Chrome Headless Shell is also usable for headless workloads. Browser downloads are never automatic. For native Linux, install GTK3 and WebKitGTK **4.1** runtime libraries. For example, on a compatible Ubuntu system: `sudo apt install libgtk-3-0t64 libwebkit2gtk-4.1-0`. Package names and available WebKitGTK versions vary by distribution. Rocky 9 has not been runtime-tested. Do not symlink a 4.0 or 6.0 ABI to 4.1. The native backend needs an X11/Wayland graphical environment. A CI machine may use Xvfb. The SDK's `Headed=false` means a hidden native top-level window, not displayless GTK. ## 2. Commands All flags precede the command. ```sh ./bin/cfbrowser --browser /path/to/chrome doctor ./bin/cfbrowser --browser /path/to/chrome demo ./bin/cfbrowser --browser /path/to/chrome --export-dir /existing/folder demo ./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker demo ./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker --diagnostics demo ./bin/cfbrowser --browser /path/to/chrome serve ``` `doctor` reports implemented capabilities and executable discovery. It returns `runtimeVerified=false`: this command does **not** launch a browser or prove that GTK can open a display. `demo` exercises the actual engine against a local fixture. | Flag | Meaning | | --- | --- | | `--engine cdp/native` | Explicit engine; no silent fallback | | `--browser PATH` | Trusted-host Chromium executable | | `--worker PATH` | Trusted-host native worker executable | | `--headed` | Show a window from startup; not an interactive handoff system | | `--allow-origin ORIGIN` | Authorize an exact private origin, including port; repeatable | | `--data-dir DIR` | Base for a private instance directory, removed by Close | | `--export-dir DIR` | Demo-only authorized screenshot export root; must already exist | | `--no-sandbox` | Explicit isolated-CI exception for Chromium or WebKit; off by default | | `--diagnostics` | Forward native engine stderr; it may contain site/runtime details | The demo grants its own ephemeral HTTP origin, so it does not require a general localhost allowance. An existing export file causes a no-overwrite error. ## 3. Manager configuration and ownership ```go manager, err := cfbrowser.New(cfbrowser.Config{ Executable: "/path/to/chrome", MaxSessions: 2, MaxPages: 3, MaxResultBytes: 64 * 1024, MaxDownloadBytes: 100 * 1024 * 1024, Timeout: 30 * time.Second, Policy: policy.URLPolicy{ AllowOrigins: []string{"http://127.0.0.1:18900"}, }, }, &cdp.Driver{}) ``` For native Windows/macOS/Linux, pass `&native.Driver{WorkerPath: "/path/to/cfbrowser-worker"}` instead. `native` is the import alias for `clusterflow.dev/cfbrowser/driver/native`. Native driver options may include a trusted `Diagnostics io.Writer`. Always handle the returned error before using the manager and defer `manager.Close()`. Use a stable `api.Owner` built from the actual host execution scope. Every EnvironmentID, ThreadID and RunID is required. SSHSessionID is optional but participates in equality when supplied. A child Agent must use its own RunID. One session owns one dedicated browser process or native worker. Pages within it share cookies/storage. Different sessions do not. A new run cannot adopt an old session merely by knowing its ID; lease transfer is not implemented. `DataDir` is a temporary-storage **base**, not a persistent profile directory. Closing a session removes its managed downloads. Export important results before closing. Closing the manager removes its entire private instance directory. ## 4. Lifecycle and API ```go owner := api.Owner{EnvironmentID: "ssh1", ThreadID: "thread1", RunID: "run1", SSHSessionID: "connection1"} session, err := manager.CreateSession(ctx, owner) // Check err before using session. page, err := manager.NewPage(ctx, owner, session.ID) // Check err before using page. ``` | Manager method | Purpose | | --- | --- | | `Capabilities(ctx)` | Engine feature implementation status | | `CreateSession(ctx, owner)` | Reserve quota and start a dedicated isolated engine | | `Sessions(owner)` | List only this owner's sessions | | `NewPage(ctx, owner, sessionID)` | Add a managed page | | `Navigate(ctx, owner, sessionID, pageID, url, operation)` | goto/back/forward/reload | | `Snapshot(ctx, owner, sessionID, pageID, request)` | Bounded fresh semantic refs | | `Act(ctx, owner, sessionID, pageID, request)` | Single validated element action | | `Read(ctx, owner, sessionID, pageID, request)` | Bounded text/table extraction | | `Wait(ctx, owner, sessionID, pageID, request)` | Cancellable ready/URL/text/textGone wait | | `Capture(ctx, owner, sessionID, pageID)` | CDP viewport PNG in managed storage | | `Files(ctx, owner, sessionID)` | Import completed CDP downloads and list metadata | | `Export(ctx, owner, sessionID, fileID, authorizedRoot, relativePath)` | No-overwrite export confined to an authorized root | | `ClosePage(ctx, owner, sessionID, pageID)` | Close one page and reclaim page quota | | `CloseSession(owner, sessionID)` | Close the owning engine and clear session storage | | `Close()` | Idempotent manager shutdown | Operations on a page are serialized with a cancellable gate. Operations on different pages may proceed concurrently. Resource quotas count managed pages; arbitrary page-generated popups are outside the prototype page API and are not a complete browser-resource sandbox. ## 5. Observe and act ```go snapshot, err := manager.Snapshot(ctx, owner, sessionID, pageID, api.SnapshotRequest{ Mode: "interactive", MaxBytes: 12 * 1024, MaxElements: 100, }) ``` Modes are `compact` and `interactive`. The result is `kind=dom-semantic`, not a complete accessibility tree. Refs identify actual element objects in an isolated script world, not page-editable attributes. Password and file-input values are excluded. ```go result, err := manager.Act(ctx, owner, sessionID, pageID, api.ActionRequest{ SnapshotID: snapshot.SnapshotID, Ref: "e1", Action: "fill", Value: "La2O3", }) ``` Find the actual ref in the returned elements rather than assuming e1 always means the same field. New snapshots conservatively invalidate all previous refs. DOM replacement, changed element identity/name/link or navigation may also invalidate them. | Action | CDP | Native (all platforms) | | --- | --- | --- | | click | Browser-dispatched mouse input | Synthetic DOM click | | hover | Browser mouse input | Unsupported | | fill | Browser keyboard selection and text insertion | Native value setter plus input/change events | | type | Browser text insertion | Unsupported | | press | Enter, Tab, Escape, ArrowUp/Down, Backspace | Unsupported | | select/check/uncheck/scroll | Bounded DOM operation | Bounded DOM operation | `result.InputKind` distinguishes `browser` from `synthetic`. Even with the CDP backend, select/check/scroll use DOM operations. `effect=dispatched` only confirms dispatch. If a connection disappears during a possible side effect, `BROWSER_ACTION_OUTCOME_UNKNOWN` tells the host to observe before deciding whether another action is appropriate. The SDK never retries actions automatically. ## 6. Reading, waiting and budgets ```go text, err := manager.Read(ctx, owner, sessionID, pageID, api.ReadRequest{Mode: "text", MaxBytes: 24576}) table, err := manager.Read(ctx, owner, sessionID, pageID, api.ReadRequest{Mode: "table", Ref: tableRef, SnapshotID: snapshotID}) err = manager.Wait(ctx, owner, sessionID, pageID, api.WaitRequest{Kind: "text", Value: "Results", TimeoutMS: 5000}) ``` Wait kinds: `ready`, `url` substring, `text`, `textGone`. No `networkidle` assumption is made. Waiting does not call a model. The earliest caller deadline, Manager Timeout and optional wait timeout wins. Snapshot/read budgets refer to final serialized JSON bytes, including escaping. Element scans, label extraction and text scans are bounded. A snapshot scans at most 4,000 DOM elements, returns at most 150 refs and clips names/values. Text/table extraction is intentionally finite; `truncated=true` must be respected. No continuation or diff protocol exists in v0.1. ## 7. Downloads and export CDP downloads use the actual browser network state, preserving cookies, Referer, POST response semantics and blob handling. Poll `Files` with a cancellable host wait until the expected file is available. The method lists only completed imports; an unfinished or canceled download is not reported as a completed file. ```go files, err := manager.Files(ctx, owner, sessionID) // Check err and select an expected file before exporting it. info, err := manager.Export(ctx, owner, sessionID, files[0].ID, authorizedRoot, "paper.cif") ``` The host must resolve `authorizedRoot` from its real local-file grants. It is not a model argument. `os.OpenRoot` confines the destination and rejects escapes through symlinks. Parent directories must exist. Existing files are never overwritten. File metadata contains an opaque ID, sanitized name, MIME, size and SHA-256, never an absolute path. Defaults: 100 MiB per download, 64 managed files per session, 4 MiB per screenshot. Chromium's progress-based cancellation is not a hard disk quota against a hostile server; use OS storage limits where required. Native downloads/screenshots and file uploads are not implemented. ## 8. Agent tools and private pipe protocol Use `agenttools.Catalog()` for eight descriptors and `agenttools.Service{Manager: manager}.Call(ctx, owner, name, arguments)` for execution. Apply the host's approval policy before Call. The library does not replace ClusterFlow's permission system. ```json {"operation":"create"} ``` This is the model argument for `cf_browser_session`. Its response includes `session` and an initial `page`. Then use `cf_browser_navigate`, `cf_browser_snapshot`, `cf_browser_act`, `cf_browser_read`, `cf_browser_wait`, `cf_browser_capture` and `cf_browser_files`. The CLI `serve` command uses a 4-byte big-endian length plus UTF-8 JSON; maximum frame size is 512 KiB. It supports `capabilities`, `tools.list`, `tools.call` and `request.cancel`. Owner identity appears only in the trusted host envelope: ```json {"version":1,"id":1,"method":"tools.call","params":{"owner":{"environmentId":"ssh1","threadId":"t1","runId":"r1"},"name":"cf_browser_session","arguments":{"operation":"list"}}} ``` `deadline` is an optional Unix-millisecond timestamp. Responses echo `id`, carry protocol `version=1` and contain either `result` or a stable `error`. Up to 32 calls may be pending. The native worker has its own trusted internal protocol; do not expose its Evaluate method as a model tool. Run `python3 scripts/pipe_demo.py ./bin/cfbrowser serve` to test framing without starting a browser. Python is only a demonstration client, not an SDK dependency. EOF cancels handlers and closes the manager. Native worker stderr is separate from protocol stdout. ## 9. Boundaries and troubleshooting - `BROWSER_ENGINE_NOT_FOUND`: configure a real executable. WebView2 runtime installation alone is not a full Edge browser installation. - Native startup exits: on Windows check Evergreen WebView2 Runtime installation and architecture; on macOS check 11+, a logged-in GUI session and worker signing/ATS configuration; on Linux check GTK/WebKitGTK 4.1 ABI and display connection. Add `--diagnostics` only while diagnosing locally. - `--browser msedge.exe` selects a full browser for CDP; it is unnecessary for `--engine native`. Windows native embeds WebView2 through COM; it does not launch full Edge with remote debugging. - `BROWSER_STALE_REF`: take a new snapshot and use its refs. - `BROWSER_TARGET_NOT_ACTIONABLE`: the element is hidden, disabled or obscured; observe/wait before another action. - `BROWSER_NETWORK_BLOCKED`: authorize a specific private origin through host configuration if it belongs to the task. - Native type/press/hover, downloads or screenshots: use CDP or handle `BROWSER_CAPABILITY_UNSUPPORTED`. - The caller must close owned sessions during shutdown. No idle TTL, profile adoption, general popup/dialog API, proxy injection, OS Job Object or full crash recovery is included. URL validation checks explicit navigation only. It does not constrain every redirect, subresource, Service Worker, WebSocket or DNS re-resolution. This prototype is suitable for a trusted desktop/network test environment, not as a strict multi-tenant web sandbox. A production egress gateway remains part of the longer-term design.