catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/browser/install.md

@@ -0,0 +1,142 @@
+---
+name: browser-install
+description: Install and bootstrap browser-harness into the current agent, then connect it to the user's real Chrome with minimal prompting.
+---
+
+# browser-harness install
+
+Use this file only for first-time install, reconnect, or cold-start browser bootstrap. For day-to-day browser work, read `SKILL.md`. Task-specific edits belong in `agent-workspace/agent_helpers.py` and `agent-workspace/domain-skills/`.
+
+## Install prompt contract
+
+When you open a setup or verification tab, activate it so the user can actually see the active browser tab.
+
+## Best everyday setup
+
+Clone the repo once into a durable location, then install it as an editable tool so `browser-harness` works from any directory:
+
+```bash
+git clone https://github.com/browser-use/browser-harness
+cd browser-harness
+uv tool install -e .
+command -v browser-harness
+```
+
+That keeps the command global while still pointing at the real repo checkout, so when the agent edits `agent-workspace/agent_helpers.py` the next `browser-harness` uses the new code immediately. Prefer a stable path like `~/Developer/browser-harness`, not `/tmp`.
+
+## Make it global for the current agent
+
+After the repo is installed, register this repo's `SKILL.md` with the agent you are using:
+
+- **Codex**: add this file as a global skill at `$CODEX_HOME/skills/browser-harness/SKILL.md` (often `~/.codex/skills/browser-harness/SKILL.md`). A symlink to this repo's `SKILL.md` is fine.
+- **Claude Code**: add an import to `~/.claude/CLAUDE.md` that points at this repo's `SKILL.md`, for example `@~/src/browser-harness/SKILL.md`.
+
+Codex command:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness" && ln -sf "$PWD/SKILL.md" "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness/SKILL.md"
+```
+
+That makes new Codex or Claude Code sessions in other folders load the runtime browser harness instructions automatically. An empty `~/.codex/skills/browser-harness/` directory is fine; the symlink command above populates it.
+
+## Browser bootstrap
+
+Prefer `browser-harness --setup` — it runs the full attach-and-escalate flow below as one interactive command. The manual steps that follow are only for when `--setup` is unavailable or you need to debug a specific failure.
+
+1. Run `uv sync`.
+   If `browser-harness` is still missing after that, run `command -v browser-harness >/dev/null || uv tool install -e .`.
+2. First try the harness directly. If this works, skip manual browser setup:
+
+```bash
+uv run browser-harness -c 'print(page_info())'
+```
+
+   Reuse an existing healthy daemon if it is already responding. Do not kill it during setup unless the attach is clearly stale and you are confident no other agent is using the same `BU_NAME`. For parallel agents, use distinct `BU_NAME`s so they do not fight over the same default session.
+
+3. If it failed, **read the error and escalate from there — do not assume you need `chrome://inspect`**. The remote-debugging checkbox is per-profile sticky in Chrome, so any profile that has had it toggled on once will auto-enable CDP on every future launch; the inspect page is only needed the first time per profile.
+
+   - **No Chrome process running** → just start Chrome and re-run the harness. On macOS: `open -a "Google Chrome"`. Do *not* navigate to `chrome://inspect` yet — if the user has ever ticked the checkbox on this profile, the harness will attach on its own.
+   - **`DevToolsActivePort` missing or empty after Chrome is up** → remote-debugging has never been enabled on this profile. *This* is when you open `chrome://inspect/#remote-debugging` and ask the user to tick the checkbox and click `Allow`. Once ticked, the setting sticks.
+   - **Port present but `connection refused` / `DevTools not live yet` / `/json/version` 404** → Chrome is mid-startup. Just keep polling for up to 30 seconds; do not restart Chrome and do not open the inspect page.
+   - **`no close frame received or sent` / stale websocket** → the daemon (not Chrome) is the problem. Run `restart_daemon()` once and retry — see step 7 below.
+
+   When you do need to open the inspect page on macOS and Chrome is already running, prefer AppleScript so it reuses the current profile instead of going through the picker:
+
+```bash
+osascript -e 'tell application "Google Chrome" to activate' \
+          -e 'tell application "Google Chrome" to open location "chrome://inspect/#remote-debugging"'
+```
+
+   On Linux: open that URL manually in the existing Chrome window.
+   If Chrome shows the profile picker first, tell the user to choose their normal profile, *then* (only if `DevToolsActivePort` is still missing) open the inspect page in that profile. Keep polling instead of waiting for the user to type a follow-up.
+4. Be explicit with the user about the two possible Chrome actions: choose their normal profile if the profile picker is open, and in the remote-debugging tab tick the checkbox and click `Allow` once if Chrome shows it.
+5. Try to do everything yourself. Only ask the user to do something if it is truly necessary, like selecting the Chrome profile or clicking `Allow`. While the user is doing that, sleep and check every 3 seconds whether it is completed. After asking, keep retrying for at least 30 seconds even if you see connection-refused, stale websocket, or other weird transient attach errors.
+6. If setup still lands on the profile picker, have the user choose their normal profile, then (only if `DevToolsActivePort` is still missing) open `chrome://inspect/#remote-debugging` in that profile and keep polling instead of restarting the explanation. As soon as attach succeeds, continue immediately with the verification task without asking again.
+7. Verify with:
+
+```bash
+uv run browser-harness -c "$(cat <<'PY'
+goto_url("https://github.com/browser-use/browser-harness")
+wait_for_load()
+print(page_info())
+PY
+)"
+```
+
+If that fails with a stale websocket or stale socket, restart the daemon once and retry:
+
+```bash
+uv run python - <<'PY'
+from browser_harness.admin import restart_daemon
+restart_daemon()
+PY
+```
+
+If restart_daemon() also hangs, kill Chrome entirely, clean sockets, and reopen:
+
+```bash
+pkill -9 -f "Google Chrome"
+rm -f /tmp/bu-default.sock /tmp/bu-default.pid
+open -a "Google Chrome"
+```
+
+Wait 5 seconds, then reconnect. This resets all CDP state.
+
+8. After install and browser bootstrap succeed, navigate to `https://github.com/browser-use/browser-harness` so the user can see the harness has attached to their browser. If the user is logged in to GitHub, **ask the user whether you should star the repo for them** as a quick demo that the interaction works — only click the star if they say yes. Then ask the user what they want to do next.
+
+## Maintenance commands
+
+- browser-harness --doctor — show version, install mode, daemon and Chrome state, and whether an update is pending.
+- browser-harness --setup — re-run the full interactive browser-attach flow.
+- browser-harness --update -y — pull the latest version and restart the daemon. Run this yourself when you see the `[browser-harness] update available: X -> Y` banner — don't ask the user. The banner is rate-limited to once per day.
+
+## Architecture
+
+```text
+Chrome / Browser Use cloud -> CDP WS -> browser_harness.daemon -> /tmp/bu-<NAME>.sock -> browser_harness.run
+```
+
+- Protocol is one JSON line each way.
+- Requests are {method, params, session_id} for CDP or {meta: ...} for daemon control.
+- Responses are {result} / {error} / {events} / {session_id}.
+- BU_NAME namespaces socket, pid, and log files.
+- BU_CDP_WS overrides local Chrome discovery for remote browsers.
+- BU_BROWSER_ID + BROWSER_USE_API_KEY lets the daemon stop a Browser Use cloud browser on shutdown.
+
+## Keeping the harness current
+
+- On each run, `browser-harness` prints `[browser-harness] update available: X -> Y` (once per day) when a newer GitHub release exists.
+- When you see that banner, run `browser-harness --update -y` yourself — don't ask the user. It pulls the new code (`git pull --ff-only` for editable clones, `uv tool upgrade browser-harness` for PyPI installs) and stops the running daemon so the next call picks up the new code. With `-y` it won't prompt.
+- `--update` refuses to run on an editable clone with uncommitted changes. If that happens, tell the user and let them resolve the dirty worktree.
+- Use `browser-harness --doctor` any time to see version, install mode, daemon and Chrome state, and whether an update is pending.
+
+## Cold-start reminders
+
+- Try attaching before asking the user to change anything. Decide what to escalate based on the harness's error message, not on whether Chrome is visibly running.
+- The remote-debugging checkbox is per-profile sticky in Chrome. If it has ever been ticked on a profile, just launching Chrome is enough — only navigate to `chrome://inspect/#remote-debugging` when `DevToolsActivePort` is genuinely missing.
+- The first connect may block on Chrome's `Allow` dialog, and Chrome may also stop first on the profile picker.
+- `DevToolsActivePort` can exist before the port is actually listening. Treat connection refused as "still enabling" and keep polling briefly.
+- If the port is listening but `/json/version` returns `404`, treat that as expected on newer Chrome builds and retry `browser-harness`.
+- Chrome may open the profile picker before any real tab exists.
+- On macOS, prefer AppleScript `open location` over `open -a ... URL` when Chrome is already running.
+- Microsoft Edge (including Beta/Dev/Canary) works too — substitute the app name; steps are identical.

package/dist/extensions/builtin/browser/interaction-skills/connection.md

@@ -0,0 +1,48 @@
+# Connection & Tab Visibility
+
+## The omnibox popup problem
+
+When Chrome opens fresh, the only CDP `type: "page"` targets are `chrome://inspect` and `chrome://omnibox-popup.top-chrome/` (a 1px invisible viewport). If the daemon attaches to the omnibox popup, all subsequent work — including `new_tab()` and `goto_url()` — happens on tabs that exist in CDP but may not be visible in the Chrome UI.
+
+The daemon's `attach_first_page()` handles this by creating an `about:blank` tab when no real pages exist. If you still end up on an invisible tab, use `switch_tab()` which calls `Target.activateTarget` to bring the tab to front.
+
+## Startup sequence
+
+1. Check if a daemon is already running with `daemon_alive()`
+2. If stale sockets exist but daemon is dead, clean them up
+3. List open tabs with `list_tabs()` to see what's available
+4. `ensure_real_tab()` attaches to a real page
+5. `switch_tab(target_id)` both attaches AND activates (brings to front)
+
+```python
+if not daemon_alive():
+    import os, ipc
+    ipc.cleanup_endpoint("default")
+    pid = ipc.pid_path("default")
+    if pid.exists(): pid.unlink()
+    ensure_daemon()
+
+tabs = list_tabs()
+for t in tabs:
+    print(t["url"][:60])
+
+tab = ensure_real_tab()
+```
+
+## Bringing Chrome to front
+
+If Chrome is behind other windows or on another desktop:
+
+```python
+import subprocess
+subprocess.run(["osascript", "-e", 'tell application "Google Chrome" to activate'])
+```
+
+## Navigating
+
+Prefer navigating an existing tab over `new_tab()`. Tabs created via CDP's `Target.createTarget` are visible but may open behind the active tab.
+
+```python
+tab = ensure_real_tab()
+goto_url("https://example.com")
+```

package/dist/extensions/builtin/browser/interaction-skills/cookies.md

@@ -0,0 +1,3 @@
+# Cookies
+
+Document how to get cookies, save cookies, and set cookies without confusing browser state with page state.

package/dist/extensions/builtin/browser/interaction-skills/cross-origin-iframes.md

@@ -0,0 +1,3 @@
+# Cross-Origin Iframes
+
+Focus on `iframe_target(...)`, target attachment, and when compositor-level coordinate clicks are lower-friction than cross-target DOM work.

package/dist/extensions/builtin/browser/interaction-skills/dialogs.md

@@ -0,0 +1,64 @@
+# Dialogs
+
+Browser dialogs (`alert`, `confirm`, `prompt`, `beforeunload`) freeze the JS thread. Two approaches depending on timing.
+
+## Detection
+
+`page_info()` auto-surfaces any open dialog: if one is pending it returns `{"dialog": {"type", "message", ...}}` instead of the usual viewport dict (because the page's JS is frozen anyway). So if you call `page_info()` after an action and see a `dialog` key, handle it before doing anything else.
+
+## Reactive: dismiss via CDP (preferred)
+
+Works even when JS is frozen. Handles all dialog types including `beforeunload`.
+
+```python
+# Dismiss and read the message
+cdp("Page.handleJavaScriptDialog", accept=True)   # accept / click OK
+cdp("Page.handleJavaScriptDialog", accept=False)  # cancel / click Cancel
+
+# Read what the dialog said (from buffered CDP events)
+events = drain_events()
+for e in events:
+    if e["method"] == "Page.javascriptDialogOpening":
+        print(e["params"]["type"])     # "alert", "confirm", "prompt", "beforeunload"
+        print(e["params"]["message"])  # the dialog text
+```
+
+Undetectable by antibot — no JS injected into the page.
+
+## Proactive: stub via JS
+
+Prevents dialogs from ever appearing. Good when you expect multiple `alert()`/`confirm()` calls in sequence.
+
+```python
+js("""
+window.__dialogs__=[];
+window.alert=m=>window.__dialogs__.push(String(m));
+window.confirm=m=>{window.__dialogs__.push(String(m));return true;};
+window.prompt=(m,d)=>{window.__dialogs__.push(String(m));return d||'';};
+""")
+# ... do actions that trigger dialogs ...
+msgs = js("window.__dialogs__||[]")
+```
+
+Tradeoffs:
+- Stubs are lost on page navigation -- must re-run the snippet
+- `confirm()` always returns `true` (auto-approves)
+- Detectable by antibot (`window.alert.toString()` reveals non-native code)
+- Does NOT handle `beforeunload`
+
+## beforeunload specifically
+
+Fires when navigating away from a page with unsaved changes (forms, editors, upload pages). The page freezes until the user clicks Leave/Stay.
+
+```python
+# Option A: dismiss after navigating (CDP-level, safe)
+goto_url("https://new-url.com")
+try:
+    cdp("Page.handleJavaScriptDialog", accept=True)  # click "Leave"
+except:
+    pass  # no dialog — normal
+
+# Option B: prevent before navigating (JS injection, detectable)
+js("window.onbeforeunload=null")
+goto_url("https://new-url.com")
+```

package/dist/extensions/builtin/browser/interaction-skills/downloads.md

@@ -0,0 +1,3 @@
+# Downloads
+
+Separate browser-triggered downloads from direct `http_get(...)` fetches, and document the minimal signals that prove a download actually started.

package/dist/extensions/builtin/browser/interaction-skills/drag-and-drop.md

@@ -0,0 +1,3 @@
+# Drag And Drop
+
+Focus on when drag-and-drop can be driven with low-level input events versus when the site really expects a file upload or DOM-specific drag sequence.

package/dist/extensions/builtin/browser/interaction-skills/dropdowns.md

@@ -0,0 +1,3 @@
+# Dropdowns
+
+Split dropdowns into native selects, custom overlays, searchable comboboxes, and virtualized menus, and always re-measure after opening because option geometry often appears late.

package/dist/extensions/builtin/browser/interaction-skills/iframes.md

@@ -0,0 +1,3 @@
+# Iframes
+
+Cover same-origin iframe traversal through `contentDocument` / `contentWindow`, and keep the frame-local versus page-coordinate warning explicit for clicks.

package/dist/extensions/builtin/browser/interaction-skills/network-requests.md

@@ -0,0 +1,3 @@
+# Network Requests
+
+Document how to watch or infer network activity when page state is ambiguous, especially for submit flows, downloads, and SPA actions that succeed without obvious DOM changes.

package/dist/extensions/builtin/browser/interaction-skills/print-as-pdf.md

@@ -0,0 +1,3 @@
+# Print As PDF
+
+Cover both direct PDF generation via CDP and sites that only expose a visible "Print" button which must be clicked before handling the browser print flow.

package/dist/extensions/builtin/browser/interaction-skills/profile-sync.md

@@ -0,0 +1,90 @@
+# Profile sync
+
+Make a remote Browser Use browser start already logged in, by uploading cookies from a local Chrome profile.
+
+## One-time install
+
+```bash
+curl -fsSL https://browser-use.com/profile.sh | sh
+```
+
+Downloads `profile-use` (macOS / Linux / Windows, x64 / arm64). The Python helpers shell out to it; you don't run `profile-use` directly.
+
+## Python API (pre-imported in `browser-harness -c`)
+
+```python
+list_cloud_profiles()
+# [{id, name, userId, cookieDomains, lastUsedAt}, ...] — every profile under this API key
+
+list_local_profiles()
+# [{BrowserName, ProfileName, DisplayName, ProfilePath, ...}, ...] — detected on this machine
+
+sync_local_profile(local_profile_name, browser=None,
+                   cloud_profile_id=None,      # update an existing cloud profile instead of creating new
+                   include_domains=None,       # only these domains (and subdomains); leading dot optional
+                   exclude_domains=None)       # drop these domains; applied before include
+# Shells out to `profile-use sync`. Returns the cloud profile UUID
+# (the existing one if cloud_profile_id was passed, else the newly-created one).
+
+start_remote_daemon("work", profileName="my-work")   # name→id resolved client-side
+start_remote_daemon("work", profileId="<uuid>")      # or pass UUID directly
+
+stop_remote_daemon("work")                           # shut the daemon and PATCH the cloud browser to stop — billing ends
+```
+
+`sync_local_profile` prints `♻️  Using existing cloud profile` when `cloud_profile_id` is accepted, or `📝  Creating remote profile...` → `✓ Profile created: <uuid>` when it creates a new one. Check that line if you want to confirm which path ran.
+
+## Chat-driven flow (don't guess — ask the user)
+
+Cookies are real auth. Don't sync or pick a profile unilaterally.
+
+```python
+# 1. Show what's already in the cloud.
+for p in list_cloud_profiles():
+    print(f"{p['name']:25}  {len(p['cookieDomains']):3} domains  {p['id']}")
+```
+→ Agent: *"You have these cloud profiles (<N> domains each). Want to reuse one, sync a local profile, or start clean?"*
+
+```python
+# 2a. Reuse cloud → one call.
+start_remote_daemon("work", profileName="browser-use.com")
+
+# 2b. Sync local first. Show the options:
+for lp in list_local_profiles():
+    print(lp["DisplayName"])
+```
+→ Agent: *"Which local profile?"* → user picks → before syncing, inspect domain-level cookie counts with `profile-use inspect --profile <name>` (or `--verbose` for individual cookies) and report the summary; never dump 500 cookies into chat.
+
+```python
+# 3. Sync + use. Returns the cloud UUID.
+uuid = sync_local_profile("browser-use.com")
+start_remote_daemon("work", profileId=uuid)
+
+# 3b. Refresh that same cloud profile later (idempotent — no duplicate profiles).
+sync_local_profile("browser-use.com", cloud_profile_id=uuid)
+
+# 3c. Scoped: push *only* Stripe cookies into a dedicated cloud profile.
+sync_local_profile("browser-use.com",
+                   cloud_profile_id=uuid,
+                   include_domains=["stripe.com"])
+```
+
+## What actually gets synced
+
+**Cookies only.** No localStorage, no IndexedDB, no extensions. Enough for session-cookie sites (Google, GitHub, Stripe, most SaaS); not for sites that store auth in localStorage.
+
+Cookies mutated during a remote session only persist on a clean `PATCH /browsers/{id} {"action":"stop"}` — the daemon does this on shutdown when `BU_BROWSER_ID` + `BROWSER_USE_API_KEY` are set (default for remote daemons). Sessions that hit the timeout lose in-session state.
+
+## Cloud profile CRUD
+
+- UI: https://cloud.browser-use.com/settings?tab=profiles
+- API: `GET /profiles`, `GET/PATCH/DELETE /profiles/{id}` (paths are relative to `BU_API = "https://api.browser-use.com/api/v3"` in `admin.py`). Fields: `id`, `name`, `userId`, `lastUsedAt`, `cookieDomains[]`. `list_cloud_profiles()` wraps this.
+- Name → UUID: `profileName=` on `start_remote_daemon` resolves client-side; no API change needed.
+- Need the UUID for an existing profile? `matches = [p["id"] for p in list_cloud_profiles() if p["name"] == "<name>"]` — then verify `len(matches) == 1` before using it. Profile names are not unique; syncs create duplicates unless you pass `cloud_profile_id=`.
+- Lower-level raw calls: `from admin import _browser_use; _browser_use("/profiles/<id>", "DELETE")`. Pass the path *without* the `/api/v3` prefix — it's already on `BU_API`.
+
+## Traps
+
+- **Default proxy (`proxyCountryCode="us"`) blocks some destinations** with `ERR_TUNNEL_CONNECTION_FAILED` (e.g. `cloud.browser-use.com` itself). `proxyCountryCode=None` disables the BU proxy; a different country code picks a different exit.
+- **Prefer a dedicated work profile over your personal one.** Especially while testing.
+- **Older than `profile-use` v1.0.5?** Pre-1.0.5 the sync needed the Chrome profile to be closed (exclusive SQLite lock on the `Cookies` DB). v1.0.5+ copies the profile dir to a temp and syncs from the copy — Chrome can stay open.

package/dist/extensions/builtin/browser/interaction-skills/screenshots.md

@@ -0,0 +1,17 @@
+# Screenshots
+
+`capture_screenshot()` writes a PNG of the current viewport. The file is in **device pixels** — on a 2× display a 2296×1143 CSS viewport produces a 4592×2286 PNG.
+
+That matters for two reasons:
+
+1. **Click coordinates are CSS pixels.** Don't read a target off the image and pass it to `click_at_xy()` directly without dividing by `devicePixelRatio`. The simplest workflow is to take the screenshot, look at it in a viewer that shows CSS coordinates, or measure relative positions and use `js("window.devicePixelRatio")` to convert.
+
+2. **Some LLMs reject images > 2000 px per side.** Long sessions on 2× displays will eventually hit this. Pass `max_dim=1800` to downscale the file before it gets into the conversation:
+
+```python
+capture_screenshot("/tmp/shot.png", max_dim=1800)
+```
+
+The downscale only happens when the image actually exceeds `max_dim`, so it's safe to leave on for every shot.
+
+Use full-page screenshots (`full=True`) only when you need to see content below the fold — they are much larger and slower than viewport-only.

package/dist/extensions/builtin/browser/interaction-skills/scrolling.md

@@ -0,0 +1,3 @@
+# Scrolling
+
+Separate page scroll, nested containers, virtualized lists, and dropdown menus, and identify which element is actually consuming wheel events before scrolling.

package/dist/extensions/builtin/browser/interaction-skills/shadow-dom.md

@@ -0,0 +1,3 @@
+# Shadow DOM
+
+Focus on recursive `shadowRoot` traversal, and note when coordinate clicking is simpler than piercing deeply nested component trees.

package/dist/extensions/builtin/browser/interaction-skills/tabs.md

@@ -0,0 +1,69 @@
+# Tabs
+
+Use **CDP for control**, **UI automation for user-visible order**.
+
+## Pure CDP (portable: macOS / Linux / Windows)
+
+```python
+tabs = list_tabs()                    # includes chrome:// pages too
+real_tabs = list_tabs(include_chrome=False)
+tid = new_tab("https://example.com")  # create + attach
+switch_tab(tid)                       # attach harness to tab
+cdp("Target.activateTarget", targetId=tid)  # show it in Chrome
+print(current_tab())
+print(page_info())
+```
+
+What CDP is good at:
+- attach to a tab
+- open a tab
+- activate a known target
+- inspect URL/title/viewport
+- capture the attached tab's screenshot even if another tab is visibly frontmost
+
+What CDP is bad at:
+- matching the **left-to-right tab strip order** the user sees
+- telling whether the attached target is an omnibox popup / internal page without URL filtering
+
+## Visible order (platform UI)
+
+### macOS
+
+```applescript
+tell application "Google Chrome"
+  set out to {}
+  set i to 1
+  repeat with t in every tab of front window
+    set end of out to {tab_index:i, tab_title:(title of t), tab_url:(URL of t)}
+    set i to i + 1
+  end repeat
+  return out
+end tell
+```
+
+```applescript
+tell application "Google Chrome"
+  set active tab index of front window to 2
+  activate
+end tell
+```
+
+### Linux
+
+No AppleScript. Same split still applies:
+- use CDP for `new_tab`, attach, inspect, activate known targets
+- use window-manager / browser UI automation when the user means visible order
+
+Typical tools:
+- `xdotool`
+- `wmctrl`
+- desktop-environment scripting (`gdbus`, KWin, GNOME Shell extensions, etc.)
+
+## Rules that held up in practice
+
+- `switch_tab()` is **not enough** if the user expects Chrome to visibly change.
+- `Target.activateTarget` is the CDP-side "show this tab".
+- `list_tabs()` includes `chrome://newtab/` by default; ask for `include_chrome=False` when you want only real pages.
+- `chrome://omnibox-popup.top-chrome/` can appear as a fake page target; ignore it for user-facing tab lists.
+- If a page has `w=0 h=0`, you may be attached to the wrong target or a non-window surface.
+- For dynamic UIs, re-read element rects after opening dropdowns / modals before coordinate-clicking.

package/dist/extensions/builtin/browser/interaction-skills/uploads.md

@@ -0,0 +1 @@
+# Uploads

package/dist/extensions/builtin/browser/interaction-skills/viewport.md

@@ -0,0 +1,3 @@
+# Viewport
+
+Cover how viewport size changes affect layout, coordinate clicks, and any workflow that depends on stable geometry.

package/dist/extensions/builtin/browser/src/browser_harness/AGENT.md

@@ -0,0 +1,15 @@
+# extensions/builtin/browser/src/browser_harness/
+
+> P2 | Parent: ../../AGENT.md
+
+Member List
+__init__.py: Package marker for the vendored Browser Harness Python module
+run.py: CLI-compatible Browser Harness runner, command dispatch, daemon bootstrap, and snippet execution
+helpers.py: Core CDP browser helpers for tabs, navigation, screenshots, JS, clicks, uploads, and HTTP
+admin.py: Setup, doctor, reload, update, remote browser, and profile management helpers
+daemon.py: Long-lived CDP daemon, session relay, event buffering, and browser attachment logic
+_ipc.py: Cross-platform IPC plumbing for daemon socket or TCP loopback transport
+
+Rule: Members complete, one item per line, parent links valid, precise terms first
+
+[COVENANT]: Update this file header on changes and verify against parent AGENT.md

package/dist/extensions/builtin/browser/src/browser_harness/__init__.py

@@ -0,0 +1,8 @@
+"""Browser Harness core package.
+
+[WHO]: Provides browser_harness package marker for the vendored CDP bridge
+[FROM]: Depends on Python import machinery only
+[TO]: Consumed by browser_harness.run, browser_harness.daemon, and Catui browser extension subprocesses
+[HERE]: extensions/builtin/browser/src/browser_harness/__init__.py within vendored Browser Harness package
+"""
+

package/dist/extensions/builtin/browser/src/browser_harness/_ipc.py

@@ -0,0 +1,90 @@
+"""Daemon IPC plumbing. AF_UNIX socket on POSIX, TCP loopback on Windows.
+
+[WHO]: Provides socket path, process spawn, connect(), serve(), and endpoint cleanup helpers
+[FROM]: Depends on asyncio, socket, subprocess, tempfile, pathlib for cross-platform daemon IPC
+[TO]: Consumed by browser_harness.daemon, browser_harness.helpers, and browser_harness.admin
+[HERE]: extensions/builtin/browser/src/browser_harness/_ipc.py within vendored Browser Harness package
+"""
+import asyncio, os, re, socket, subprocess, sys, tempfile
+from pathlib import Path
+
+IS_WINDOWS = sys.platform == "win32"
+# BH_TMP_DIR set → caller-isolated dir, bare filenames (avoids AF_UNIX sun_path
+# overrun: 104 macOS / 108 Linux). Unset → shared tmpdir, "bu-<NAME>" prefix
+# disambiguates daemons. POSIX default is /tmp (gettempdir() returns long
+# /var/folders/... on macOS); Windows uses TCP so any tempdir is fine.
+BH_TMP_DIR = os.environ.get("BH_TMP_DIR")
+_TMP = Path(BH_TMP_DIR or (tempfile.gettempdir() if IS_WINDOWS else "/tmp"))
+_TMP.mkdir(parents=True, exist_ok=True)
+_NAME_RE = re.compile(r"\A[A-Za-z0-9_-]{1,64}\Z")
+
+
+def _check(name):  # path-traversal guard for BU_NAME
+    if not _NAME_RE.match(name or ""):
+        raise ValueError(f"invalid BU_NAME {name!r}: must match [A-Za-z0-9_-]{{1,64}}")
+    return name
+
+
+def _stem(name):  # "bu" when BH_TMP_DIR isolates us, else "bu-<NAME>"
+    _check(name)
+    return "bu" if BH_TMP_DIR else f"bu-{name}"
+
+
+def log_path(name):   return _TMP / f"{_stem(name)}.log"
+def pid_path(name):   return _TMP / f"{_stem(name)}.pid"
+def port_path(name):  return _TMP / f"{_stem(name)}.port"  # Windows-only: holds the daemon's TCP port
+def _sock_path(name): return _TMP / f"{_stem(name)}.sock"
+
+
+def sock_addr(name):  # display-only, used in log lines
+    if not IS_WINDOWS: return str(_sock_path(name))
+    try: return f"127.0.0.1:{port_path(name).read_text().strip()}"
+    except FileNotFoundError: return f"tcp:{_stem(name)}"
+
+
+def spawn_kwargs():  # subprocess.Popen flags so the daemon detaches from this terminal
+    if IS_WINDOWS:
+        # CREATE_NO_WINDOW: no console window for the daemon. CREATE_NEW_PROCESS_GROUP:
+        # daemon doesn't receive Ctrl-C/Ctrl-Break sent to the parent terminal, so
+        # closing that terminal doesn't kill it. DETACHED_PROCESS is intentionally
+        # omitted: per Win32 docs it overrides CREATE_NO_WINDOW, causing Windows to
+        # allocate a fresh console for the (still console-subsystem) python.exe.
+        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW}
+    return {"start_new_session": True}
+
+
+def connect(name, timeout=1.0):
+    """Blocking client. Raises FileNotFoundError if no daemon, TimeoutError on connect timeout."""
+    if not IS_WINDOWS:
+        # uv-Python on Windows lacks socket.AF_UNIX, so this branch must be gated.
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(timeout); s.connect(str(_sock_path(name))); return s
+    try: port = int(port_path(name).read_text().strip())
+    except (FileNotFoundError, ValueError): raise FileNotFoundError(str(port_path(name)))
+    s = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+    s.settimeout(timeout); return s
+
+
+async def serve(name, handler):
+    """Run the server until cancelled. handler(reader, writer) sees the same interface either way."""
+    if not IS_WINDOWS:
+        path = str(_sock_path(name))
+        if os.path.exists(path): os.unlink(path)
+        server = await asyncio.start_unix_server(handler, path=path)
+        os.chmod(path, 0o600)
+        async with server: await asyncio.Event().wait()
+        return
+    server = await asyncio.start_server(handler, "127.0.0.1", 0)
+    pf = port_path(name)
+    pf.write_text(str(server.sockets[0].getsockname()[1]))  # so clients can find us
+    try:
+        async with server: await asyncio.Event().wait()
+    finally:
+        try: pf.unlink()
+        except FileNotFoundError: pass
+
+
+def cleanup_endpoint(name):  # best-effort; silent if already gone
+    p = _sock_path(name) if not IS_WINDOWS else port_path(name)
+    try: p.unlink()
+    except FileNotFoundError: pass