Rename the flags to browser-*, and take browser config as one JSON object

[rgarcia]

First slice of 5c: the user-facing vocabulary. Nothing here is a rename of internals — that's the next slice — but flags and commands are what people type, so they're worth getting right before the sweep.

Flags name the domain, not the acronym

--cua-tools → --browser-tools, --cua-coordinates → --browser-coordinates, and the commands become /browser and /browser-tools. Someone selecting browser tools shouldn't have to learn what CUA stood for.

Four browser flags become one JSON object

Before, one flag per field of Kernel's browser-create call:

--cua-profile-id --cua-profile-save-changes --cua-proxy-id --cua-browser-timeout

That surface grows every time the SDK does. Now:

pi -p --browser-tools browser \
  --browser-options '{"stealth":true,"profile":{"id":"p1","save_changes":true},"proxy_id":"px1"}' \
  "open example.com"

--browser-options is forwarded verbatim, so a field the SDK adds tomorrow needs no change here — a test pins that by passing an invented field through.

The only default is timeout_seconds: 600, since the failure it prevents is a browser vanishing mid-task.

One behavior change worth flagging: stealth: true used to be hardcoded and unconditional — the earlier hands-on QA pass got stealth seven times without ever asking for it. It's now opt-in via the JSON. That's the right default for a library (don't silently pick a mode for the caller), but it does mean an existing invocation that relied on implicit stealth has to say so.

--browser-session still attaches an existing browser and is rejected in combination with --browser-options, since attaching and configuring-a-new-one are contradictory.

Verification

typecheck 0, cua-ai 99, cua-agent 283, cua-pi-extension 33 — two new tests cover the JSON parsing, including the failure modes that would otherwise silently do nothing (invalid JSON, a JSON array, and the attach/configure conflict).

Still ahead in 5c

The big mechanical slice: collapse cua-ai + cua-agent + cua-pi-extension into one @onkernel/loop with core/ and pi/ subpaths and a pi.extensions entry, rename Cua* → Loop* (domain concepts to ComputerUse*), move tool identities to the kloop. prefix, and drop the pi-ai / pi-agent-core re-exports so consumers import pi from pi.

---

Note

Medium Risk
Breaking CLI renames and stealth becoming opt-in can change real browser sessions for existing invocations; JSON passthrough is flexible but misconfiguration now fails at parse time rather than via typed flags.

Overview
User-facing CLI and commands now use browser naming instead of CUA: --browser-tools, --browser-coordinates, /browser, and /browser-tools replace the old cua-* equivalents. Status lines, stderr warnings, and error text follow the same vocabulary.

Browser provisioning config is collapsed into --browser-session (attach) plus --browser-options, a JSON object passed through to Kernel’s browsers.create. The removed flags (--cua-profile-id, save-changes, proxy, timeout) are expressible in that JSON. --browser-session cannot be combined with --browser-options.

Behavior changes: owned browsers default to timeout_seconds: 600 (was 300 via flag). stealth is no longer forced on create—callers must set it in JSON if they want it. Create payloads are built as default timeout plus spread of parsed JSON.

Docs, changelog, and tests are updated for the new flags and for parseBrowserOptions validation (invalid JSON, non-object, attach+configure conflict).

^{Reviewed by Cursor Bugbot for commit aadf8ce. Bugbot is set up for automated code reviews on this repo. Configure here.}