# ClusterFlow integration guide 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. ## 1. Add the local module Place `cfbrowser/` next to `clusterflow/`. In the ClusterFlow module: ```sh 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. ## 2. Copy the tested registry adapter 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. ```sh 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. ## 3. Own one Manager in the workspace/application lifecycle Create a Manager once for the enabled browser feature, not once per model turn: ```go 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](NATIVE.en.md). 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: ```go 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. ```go 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. ## 4. Register before the run catalog snapshot For the smallest prototype integration, register directly into `combined` inside `agentservice.registryForSettings`, before `combined.Snapshot()`: ```go 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. ## 5. Preserve scope and permissions Use the scope already passed by the Runner: ```go owner := api.Owner{ EnvironmentID: scope.EnvironmentID, ThreadID: scope.ThreadID, RunID: scope.RunID, SSHSessionID: scope.SessionID, } ``` - Do not consult the currently selected Vue SSH tab when executing a background call. - Child Agents have their own RunID even when they inherit ThreadID and SSH SessionID. - Keep the adapter's External risks for sessions, navigation and actions; Full Access continues to use ClusterFlow's existing policy behavior. - Snapshot/read/wait/capture/files are read tools, scoped to already owned resources. - The SDK's Service does not perform ClusterFlow approval prompts itself. Invoke it through the existing Tool Bus/Runner, or enforce equivalent host policy. 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. ## 6. Files, grants and SSH transfer 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. ## 7. UI and message integration 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. ## 8. Lifecycle checklist | 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. ## 9. Integration acceptance 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.