This package is a standalone prototype. It does not modify the uploaded ClusterFlow application or add UI settings automatically. The included Tool Bus adapter was compiled and tested in a separate copy of ClusterFlow-202611051139.zip, using Go 1.25.0.
Place cfbrowser/ next to clusterflow/. In the ClusterFlow module:
go mod edit -require=clusterflow.dev/cfbrowser@v0.0.0
go mod edit -replace=clusterflow.dev/cfbrowser=../cfbrowser
go mod tidy
This path is not a public published module. Replace it with the real repository/tag if you publish the SDK later. When the main application uses vendor mode, regenerate its vendor directory; a dependency's own vendor directory is not inherited by the host.
Go 1.24+ is enough for the SDK; retain the host application's Go 1.25 baseline. The prototype pins chromedp/cdproto and purego rather than following moving branches.
Copy:
| Source in this archive | Destination inside ClusterFlow |
|---|---|
examples/clusterflow/register_browser.go.example |
internal/clusterflowtools/browser_prototype.go |
examples/clusterflow/register_browser_test.go.example |
internal/clusterflowtools/browser_prototype_test.go |
The .example extension prevents the SDK module from importing another project's internal packages. After copying, the code lives inside ClusterFlow and obeys Go's internal-package rules.
CGO_ENABLED=0 go test ./internal/clusterflowtools -run TestPrototypeBrowserRegistry -count=1
The adapter registers eight builtin.browser.* entries. It maps SDK risks to existing Tool Bus risks, keeps a 32 KiB argument cap, and derives Owner from ExecutionScope. The model cannot set environment/thread/run identity through tool arguments.
The adapter uses model tool names as temporary display titles. Add localized titles through frontend/src/utils/aiAgentToolLabels.ts and the existing locale files when building the app UI.
Create a Manager once for the enabled browser feature, not once per model turn:
manager, err := cfbrowser.New(cfbrowser.Config{
Executable: configuredBrowserPath,
Timeout: time.Duration(toolTimeoutSeconds) * time.Second,
MaxResultBytes: maxToolResultBytes,
}, &cdp.Driver{})
if err != nil {
return err
}
browserTools := &agenttools.Service{Manager: manager}
Use the native driver on Windows/macOS/Linux by passing its worker path. The new Windows/macOS implementations are experimental until their native test scripts pass on your target machines; see native deployment. Keep worker discovery, browser paths, grant roots and proxy/network policy in trusted host configuration; none are model arguments.
Store the service in the workspace-owned dependency graph. Expose it from AgentAccess through a narrow method such as:
func (a *AgentAccess) AgentBrowserTools() *agenttools.Service {
return a.workspace.browserTools
}
This requires adding the workspace field and initializing it in the host's real startup path. Return nil when the feature is disabled. Wire manager.Close() into workspace shutdown before its configuration dependencies disappear. The SDK is cgo-free; Wails' overall platform build requirements remain unchanged.
For native mode, keep the worker separate from the Wails frontend WebView. Build and ship it for the host OS/architecture; use an absolute executable path resolved from application resources, not the working directory. On Windows use cfbrowser-worker.exe; on macOS use CFBrowserWorker.app/Contents/MacOS/cfbrowser-worker if bundled. The Manager creates one worker per session, each with isolated data. Sign the worker as part of the application release; macOS signing/notarization must be verified with the real distribution. No changes to the eight Agent tools or Owner mapping are needed.
manager, err := cfbrowser.New(cfbrowser.Config{
Timeout: 30 * time.Second,
}, &native.Driver{WorkerPath: absoluteWorkerPath})
Import native "clusterflow.dev/cfbrowser/driver/native". This configuration omits a browser executable; system WebView runtimes are resolved by the worker. Never give the model direct access to the worker Evaluate RPC.
For the smallest prototype integration, register directly into combined inside agentservice.registryForSettings, before combined.Snapshot():
if settings.BuiltinToolsEnabled {
if provider, ok := s.backend.(interface {
AgentBrowserTools() *agenttools.Service
}); ok && provider.AgentBrowserTools() != nil {
if err := clusterflowtools.RegisterPrototypeBrowserTools(combined, provider.AgentBrowserTools()); err != nil {
return nil, err
}
}
}
Add the agenttools import. This route preserves the existing BuildRegistry backend contract and registers against the actual AgentAccess value, so it does not depend on optional methods being promoted through agentRegistryBackend.
If you instead add browser registration inside clusterflowtools.BuildRegistry, explicitly forward the optional method through agentRegistryBackend; embedding its existing Backend interface does not automatically promote extra methods of the concrete value. Do not register the same eight tools through both paths.
Run catalogs remain snapshots: changing settings should affect future runs. Session ownership and context cancellation are still checked at execution time.
Use the scope already passed by the Runner:
owner := api.Owner{
EnvironmentID: scope.EnvironmentID,
ThreadID: scope.ThreadID,
RunID: scope.RunID,
SSHSessionID: scope.SessionID,
}
Do not advertise RuntimeBehaviorPassiveWait as integrated with follow-up prompt wakeups until you have connected and tested that Runner behavior. SDK Wait is cancellable, but that alone does not implement the application's complete pause/steering contract.
The eight base tools return file IDs only. Export is intentionally a trusted-host SDK method rather than a model tool accepting arbitrary paths.
To expose export in ClusterFlow, add a separate tool with fileId, localGrantId and a relative path. Resolve the actual grant using the existing localfiles service, retain its identity/revocation semantics, and pass a trusted authorized root to Manager.Export. Tie cancellation to grant revocation. A one-time path check is not a substitute for the host's real grant lifecycle.
After authorized export, use the existing cf_file_transfer_start tool with that local grant/path and the current SSH scope. Do not invent a grant ID for the SDK's private download directory.
For binary downloads, reuse the browser-produced file; do not fetch the link again without its cookies or POST context. Native download/upload is not part of v0.1.
Start with the existing AgentToolCallCard and settings components. A small browser toggle, engine selection, executable/worker paths and capability status are enough for a prototype. Keep implementation details out of normal user flows.
The uploaded Agent Message currently carries text. Tool JSON with a screenshot file ID is not an image observation. Visual model input requires content-parts, provider serialization, attachment persistence and usage/context handling; do not send base64 as text and call that vision support.
For SSH tunnels, add only the exact host/port the user configured. The current URL policy checks explicit navigation only. It is not the production egress gateway described in the long-term design. Proxy profiles from the existing Go HTTP client cannot be silently reused by Chromium/WebKit; proxy support is currently unsupported.
| Host event | Integration behavior |
|---|---|
| Switch SSH tab/Thread display | Do not change resource Owner or cancel the background run |
| Cancel Run | Cancel its operation context, then explicitly close its sessions when appropriate |
| Run completes | Export retained files and close sessions; there is no automatic idle reaper |
| Delete Thread/environment | Close all owned sessions from the host lifecycle |
| Application shutdown | Stop new calls, cancel outstanding contexts, call Manager.Close |
| Crash/IPC loss | Discard stale refs; do not automatically replay a possible side effect |
If you need crash-time cleanup guarantees or per-profile leases, implement the planned OS process supervision and lease policy before treating the prototype as a production service.
First run the SDK demo and integration tests. Then run the included registry test in the actual application source, followed by two SSH environments with separate Agent runs. Verify that refs, cookies, files and tool cards do not cross scope. Exercise stop/pause and shutdown with the actual Runner. This delivery verifies the registry seam, not the Wails UI or the complete application lifecycle.