Adom Bridge

@@ -189,11 +189,11 @@ adom-bridge <command> '<json-args>' ```bash adom-bridge-cli ping adom-bridge-cli status-adom-bridge-cli browser_open_window '{"sessionId":"dart2","url":"https://example.com"}'-adom-bridge-cli browser_eval '{"sessionId":"dart2","expr":"document.title"}'-adom-bridge-cli browser_screenshot '{"sessionId":"dart2"}'-adom-bridge-cli browser_list_windows-adom-bridge-cli browser_close_window '{"sessionId":"dart2"}'+adom-bridge-cli pup_open_window '{"sessionId":"dart2","url":"https://example.com"}'+adom-bridge-cli pup_eval '{"sessionId":"dart2","expr":"document.title"}'+adom-bridge-cli pup_screenshot '{"sessionId":"dart2"}'+adom-bridge-cli pup_list_windows+adom-bridge-cli pup_close_window '{"sessionId":"dart2"}' adom-bridge-cli notify_user '{"title":"Hello","body":"From Docker"}' adom-bridge-cli shell_execute '{"command":"echo hello"}' adom-bridge-cli pull_file '{"filePaths":["C:\\Users\\john\\Downloads\\image.png"],"saveTo":"/tmp"}'@@ -303,7 +303,7 @@ curl -X POST http://127.0.0.1:47200/command \ # → identical JSON to `adom-bridge-cli server_add '{...}'`, including the _hint ``` -**What's safe to send directly:** essentially everything sync (`server_*`, `bridge_list`, `hd_status`, `hd_build_status`, `desktop_list_windows`, `desktop_screenshot_*`, `kicad_*`, `fusion_*`, `browser_screenshot`, `notify_user`, ...) plus async-dispatching verbs that return a job id in <500 ms (`bridge_install`, `hd_build`, `desktop_install_kicad`, ...).+**What's safe to send directly:** essentially everything sync (`server_*`, `bridge_list`, `hd_status`, `hd_build_status`, `desktop_list_windows`, `desktop_screenshot_*`, `kicad_*`, `fusion_*`, `pup_screenshot`, `notify_user`, ...) plus async-dispatching verbs that return a job id in <500 ms (`bridge_install`, `hd_build`, `desktop_install_kicad`, ...).  **What requires the CLI fallback:** verbs returning a structured `errorCode:"cli_required"` from this endpoint — currently `pull_file`, `send_files`, `shell_execute`. These use binary streaming or multi-minute approval polling that doesn't fit a single synchronous HTTP request. `GET /status` returns the full list at runtime so callers can branch defensively. @@ -1135,9 +1135,9 @@ adom-bridge-cli pull_file '{"path": "C:/tmp/mfg/cpl.csv"}'     - `adom-bridge-cli desktop_open_url '{"url":"https://docs.example.com","browser":"edge"}'` -- force native Edge   - Returns `{ok, browser, url, exePath?}`. Allowed schemes: http, https, mailto, ftp, ftps. Other schemes refused. -#### `desktop_open_url` vs `browser_open_window` — two completely different browsers+#### `desktop_open_url` vs `pup_open_window` — two completely different browsers -| | `desktop_open_url` | `browser_open_window` |+| | `desktop_open_url` | `pup_open_window` | |---|---|---| | **What browser** | Native OS browser the user uses daily — Microsoft Edge / Google Chrome / Mozilla Firefox / Brave (whichever they've set as Windows default, or the one you name explicitly) | Puppeteer-controlled **Chrome for Testing** — a separate Chromium build that pup launches | | **Profile / data** | The user's real profile: saved logins, history, bookmarks, extensions, autofill | Isolated profile under `plugins/puppeteer/profiles/<sessionId>/` — empty, no saved logins |@@ -1145,17 +1145,17 @@ adom-bridge-cli pull_file '{"path": "C:/tmp/mfg/cpl.csv"}' | **Use when** | A login is required (claude.ai, GitHub, internal tools, banking) — the human's existing session must be reused | Automation, scraping, screenshot capture, video recording, headful UI testing | | **Can Claude control it after launch?** | No — once handed off, Claude can't see or drive it | Yes — every `browser_*` verb (screenshot, eval, navigate, record, etc.) | -**Decision rule:** human-in-the-loop login flow → `desktop_open_url`. AI-driven automation → `browser_open_window` (defaults to Chrome for Testing). AI-driven automation that **must** be the user's real, signed-in profile (GCP Console with org/projects, internal SSO behind a managed-Chrome policy, anything Context-Aware Access blocks for non-enrolled browsers) → `browser_open_window` with the new `nativeBrowser` + `nativeProfile` args (v1.0.5+, see below).+**Decision rule:** human-in-the-loop login flow → `desktop_open_url`. AI-driven automation → `pup_open_window` (defaults to Chrome for Testing). AI-driven automation that **must** be the user's real, signed-in profile (GCP Console with org/projects, internal SSO behind a managed-Chrome policy, anything Context-Aware Access blocks for non-enrolled browsers) → `pup_open_window` with the new `nativeBrowser` + `nativeProfile` args (v1.0.5+, see below). -#### When pup means "the user's real Chrome/Edge" — `browser_open_window` native mode (v1.0.6+, smart flow v1.0.11)+#### When pup means "the user's real Chrome/Edge" — `pup_open_window` native mode (v1.0.6+, smart flow v1.0.11) -Default `browser_open_window` (no native args) launches Chrome for Testing — same as day one. **Never auto-switch a plain pup request to native.** "Open this URL in pup", "screenshot this", "click that button" all stay on CfT.+Default `pup_open_window` (no native args) launches Chrome for Testing — same as day one. **Never auto-switch a plain pup request to native.** "Open this URL in pup", "screenshot this", "click that button" all stay on CfT.  Native mode drives the user's **REAL browser** — their actual signed-in profile, with live cookies, org policies, and device enrollment intact (NOT a clone — v1.0.6 replaced the old clone approach). Opt-in via TWO additive args from `desktop_list_browsers`:  ```bash adom-bridge-cli desktop_list_browsers     # installed browsers + profiles (+ the signed-in account per profile)-adom-bridge-cli browser_open_window '{+adom-bridge-cli pup_open_window '{   "sessionId":"gcp",   "nativeBrowser":"chrome",            # chrome / edge / brave   "nativeProfile":"Default",           # profile id: Default / Profile 1 / Profile 2@@ -1178,7 +1178,7 @@ adom-bridge-cli browser_open_window '{ - **`native_relaunch_required`** — the browser is open without the port, so driving it means closing + reopening it (with `--restore-last-session`, so all tabs/windows come back). **Ask the user's permission**, then re-call with `"nativeRelaunch":true`. The response's `alternatives` lists other installed browsers you could offer instead. - **`native_cdp_blocked`** — the debug port won't open, almost always an **enterprise policy** (`RemoteDebuggingAllowed` disabled via Google Workspace / Chrome cloud management — affects **Chrome browser-wide, every profile**). `diagnosis` says whether it's a confirmed local-registry policy or a likely cloud-managed one. AD will **not** close that browser again. `alternatives` names other installed browsers — **Edge usually escapes Google management**, so it often drives natively when Chrome can't. Offer the user the alternative, or fall back to generic CfT. -**Always available — generic CfT.** `browser_open_window` with NO `nativeBrowser`/`nativeProfile` drives a clean Chrome-for-Testing instance: no user session, no managed policy, fully controllable. If a task needs the user's logged-in session there, have them sign in once. This is the universal fallback whenever native is blocked.+**Always available — generic CfT.** `pup_open_window` with NO `nativeBrowser`/`nativeProfile` drives a clean Chrome-for-Testing instance: no user session, no managed policy, fully controllable. If a task needs the user's logged-in session there, have them sign in once. This is the universal fallback whenever native is blocked.  **Power-user shortcut:** if the user launches their browser at startup with `--remote-debugging-port=<N>`, AD reconnects every session with no prompt at all (a productized opt-in "keep native browsers debug-ready at boot" is on the roadmap, default OFF for security). @@ -1204,7 +1204,7 @@ adom-bridge-cli browser_open_window '{  #### ⚠️ Common footgun — `localhost` / `file://` URLs from Docker AIs -If you're running this CLI from a remote Docker container (galliaApril, dartv4, etc.), `browser_open_window` / `browser_open_tab` / `browser_navigate` will load the URL inside the USER's local pup — NOT inside your container. So a URL like `http://localhost:8080/foo.html` resolves to the user's machine, not your container's service.+If you're running this CLI from a remote Docker container (galliaApril, dartv4, etc.), `pup_open_window` / `pup_open_tab` / `pup_navigate` will load the URL inside the USER's local pup — NOT inside your container. So a URL like `http://localhost:8080/foo.html` resolves to the user's machine, not your container's service.  **v1.7.10+ detects this.** When you pass a URL whose host is `localhost`, `127.0.0.1`, `0.0.0.0`, `::1`, or scheme is `file://`, the response includes a `_hint` field explaining the issue and suggesting the public-slug URL pattern (`https://<user>-<repo>-<suffix>.adom.cloud/proxy/<port>/<path>`). **The call still proceeds** — rare legitimate cases exist where the user actually does have something running on their localhost. @@ -1219,7 +1219,7 @@ python3 -m http.server 8786 --bind 0.0.0.0 & #    Slug looks like: <username>-<container>-<random-id>  # 3. Open the public URL — NOT localhost:-adom-bridge-cli browser_open_window '{+adom-bridge-cli pup_open_window '{   "sessionId":"demo",   "url":"https://<your-container-slug>.adom.cloud/proxy/8786/foo.html" }'@@ -1338,7 +1338,7 @@ Two ways to use it:  **Keyboard chords:** `desktop_press_key` accepts a chord as one string `["ctrl+w"]` OR separate tokens `["ctrl","w"]` — both mean Ctrl held + W. A *sequence* of distinct chords uses `+` per element: `["ctrl+l","enter"]`. The reply echoes `chords` showing how AD interpreted your `keys`. -- `desktop_flash_window` (v1.8.152+) -- Flash an **arbitrary** window's taskbar button orange (Win32 `FlashWindowEx`) as an "attention / ongoing activity" cue. Resolve the HWND with `desktop_list_windows` first. Args: `hwnd` (int) OR `titleContains` (string); `mode` (`"until_focused"` default — flashes until the user clicks the window; or `"count"`); `count` (int, `mode:"count"` only, default 3); `stop` (bool — clear an active flash). Returns `{ok, hwnd, title, mode}`. **Lightweight by design** (direct FlashWindowEx, no process spawn) so a bridge can call it after every verb. Distinct from the puppeteer bridge's `browser_alert_window`, which only flashes pup's OWN tracked windows — this flashes any window on the host. For progress + overlay-icon status, use `desktop_taskbar`.+- `desktop_flash_window` (v1.8.152+) -- Flash an **arbitrary** window's taskbar button orange (Win32 `FlashWindowEx`) as an "attention / ongoing activity" cue. Resolve the HWND with `desktop_list_windows` first. Args: `hwnd` (int) OR `titleContains` (string); `mode` (`"until_focused"` default — flashes until the user clicks the window; or `"count"`); `count` (int, `mode:"count"` only, default 3); `stop` (bool — clear an active flash). Returns `{ok, hwnd, title, mode}`. **Lightweight by design** (direct FlashWindowEx, no process spawn) so a bridge can call it after every verb. Distinct from the puppeteer bridge's `pup_alert_window`, which only flashes pup's OWN tracked windows — this flashes any window on the host. For progress + overlay-icon status, use `desktop_taskbar`.   - Example: `adom-bridge-cli desktop_flash_window '{"hwnd":133560}'` then `adom-bridge-cli desktop_flash_window '{"hwnd":133560,"stop":true}'` to clear. - `desktop_taskbar` (v1.8.152+) -- Paint **glanceable status** on any window's taskbar button via `ITaskbarList3` (progress bar + overlay icon) + `FlashWindowEx`, so a bridge can show what the AI is doing on the **real app window it drives** (e.g. native-browser putting an "Adom is driving" badge + task progress on the Chrome/Edge button). Works on windows owned by **other processes**. Persistent COM (init once, reuse) — safe to tick progress frequently; no process spawn. Resolve the HWND via `desktop_list_windows`. Args (all channels optional; provide ≥1):   - `hwnd` (int) OR `titleContains` (string)@@ -1365,7 +1365,7 @@ Two ways to use it:     # the pin opens a managed window instead of an orphan app.     adom-bridge-cli desktop_register_app_identity '{"appId":"Adom.Pup","displayName":"Adom Pup",       "iconPath":"C:/.../adom-pup.ico",-      "args":"browser_open_window {\"sessionId\":\"pinned\",\"owner\":\"pinned-launch\"}"}'+      "args":"pup_open_window {\"sessionId\":\"pinned\",\"owner\":\"pinned-launch\"}"}'      # Per window, e.g. at park time. cacheKey survives page-title churn.     adom-bridge-cli desktop_set_window_identity '{"cacheKey":"<sessionId>",@@ -1471,14 +1471,14 @@ The pup bridge is **cloud-owned** and ships its OWN full skill (its wiki page / Most-used verbs:  ```bash-adom-bridge-cli browser_open_window '{"sessionId": "s1", "profile": "p1", "url": "https://example.com"}'-adom-bridge-cli browser_navigate '{"sessionId": "s1", "url": "https://example.com/page2"}'-adom-bridge-cli browser_screenshot '{"sessionId": "s1"}'-adom-bridge-cli browser_eval '{"sessionId": "s1", "expression": "document.title"}'-adom-bridge-cli browser_fetch_url '{"url": "https://example.com/data.json"}'+adom-bridge-cli pup_open_window '{"sessionId": "s1", "profile": "p1", "url": "https://example.com"}'+adom-bridge-cli pup_navigate '{"sessionId": "s1", "url": "https://example.com/page2"}'+adom-bridge-cli pup_screenshot '{"sessionId": "s1"}'+adom-bridge-cli pup_eval '{"sessionId": "s1", "expression": "document.title"}'+adom-bridge-cli pup_fetch_url '{"url": "https://example.com/data.json"}' ``` -`browser_readiness` is the read-only probe (never spawns or downloads). Full details: the bridge's own skill via `sync_skills`.+`pup_readiness` is the read-only probe (never spawns or downloads). Full details: the bridge's own skill via `sync_skills`.  ### Screen recording — AD's desktop recorder (tab recording is pup's) @@ -1493,7 +1493,7 @@ adom-bridge-cli desktop_record_list '{}' adom-bridge-cli desktop_recorder_close '{}' ``` -`desktop_record_start` without `confirmDesktopNotTabRecording: true` refuses with `errorCode: desktop_record_needs_confirmation` — that guard exists because recording a BROWSER TAB is the pup bridge's separate feature (`browser_record_start` etc., see pup's own skill).+`desktop_record_start` without `confirmDesktopNotTabRecording: true` refuses with `errorCode: desktop_record_needs_confirmation` — that guard exists because recording a BROWSER TAB is the pup bridge's separate feature (`pup_record_start` etc., see pup's own skill).  ### Filesystem primitives — `desktop_list_files` / `desktop_watch_files` / `desktop_pull_glob` (v1.5.0+) @@ -1547,7 +1547,7 @@ Composes `desktop_list_files` (or `desktop_watch_files` if `wait:true`) with the  ```bash BEFORE=$(date +%s)-# … trigger the download click via browser_input_dispatch …+# … trigger the download click via pup_input_dispatch … adom-bridge-cli desktop_pull_glob "{   \"path\": \"%USERPROFILE%\\\\Downloads\",   \"glob\": \"ul_*.zip\",