USAGE.en.md 13 KB

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.

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.

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.

./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

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

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

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.

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

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.

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.

{"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:

{"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.