Pup - the AI's own browser

@@ -2,6 +2,28 @@  ## UNRELEASED (rides the next version) — AD-base re-discovery + self-guarded powershell primitives +### Shipped skills asserted Windows-only facts the macOS port made false++Three places in the **shipped** pkg told the consumer AI something untrue on a Mac. None of them+is a path, so no sweep this fleet built could see them — they are flat platform *assertions*,+the class KICAD found in their README.++- **"every Windows PC ships Edge, so there's usually no download"** (`SKILL.md`, `README.md`,+  `pup-browsers-and-chrome`). True on Windows; false on macOS, where Edge is not preinstalled+  and Safari is not CDP-drivable. A Mac with no Chrome takes the *download* path, so the AI was+  promising the user "no download" precisely where a download happens. Now states both+  platforms and points at `browser_readiness` instead of an assumption.+- **The Chrome-install escalation section** described a Windows UAC and the "click YES to finish+  installing" approval flow as if universal. macOS has no elevation step at all: pup mounts the+  `.dmg` with `hdiutil`, `ditto`s to `/Applications`, and falls back to `~/Applications`.+  Verified against `chrome.js` rather than assumed — there is no `sudo` and no+  `administrator privileges` call anywhere in the mac path. An AI reading the old text on a Mac+  would wait for a consent click that is never coming. The Windows-only scope is now explicit.++The z-order paragraph was already dual-form (`Windows: SetWindowPos … macOS: hidden, Cmd+H`),+which is the tell for this class: the parts of the port that required *behaviour* changes got+their prose reviewed, and the parts that "just worked" did not.+ ### `browser_configure` claimed a taskbar change that cannot happen off Windows  `taskbarGrouping` and `agentActivity` both drive Windows-only machinery — taskbar buttons,

@@ -3,9 +3,10 @@ Drive a browser on the user's desktop from the cloud: open/close windows + tabs, navigate, screenshot, eval JS, record windows. pup is a **generic, non-profile browser** — every session is a **fresh, isolated Chrome/Edge process**, never the user's real signed-in browser. It drives the browser **already on the-machine** (installed Chrome, else Microsoft Edge — every Windows PC ships Edge), so the common case needs-**no download**; **Chrome for Testing** is auto-fetched only as a last resort when the box has no-Chromium browser at all. Windows open in the **background by default** so pup never disrupts the user.+machine** (installed Chrome, else Microsoft Edge). On **Windows** every PC ships Edge, so the common case+needs **no download**; on **macOS** neither is guaranteed (Edge isn't preinstalled, Safari isn't+CDP-drivable), so a Mac without Chrome takes the download path. **Chrome for Testing** is auto-fetched+only as a last resort when the box has no Chromium browser at all. Windows open in the **background by default** so pup never disrupts the user.  > To drive the user's **real, signed-in** Chrome/Edge (their cookies, SSO, saved logins), that's the > **Adom browser extension's `nbrowser_*` verbs** — a separate bridge, not pup.@@ -184,25 +185,6 @@ cloud, with no HUD and no need to bring the window forward.  *Above: a GIF preview of a real `browser_record` capture (≈8.6 s, the tab navigating the Adom wiki, recorded in the background on a VM). The native capture is the WebM linked below — this GIF is just an inline preview.* -### High-FPS windows: recording something the user is not looking at--pup windows are backgrounded by design, and Chrome throttles a window that is occluded — so-recording one normally yields a **1-2 fps** video. pup can disable Chrome's power-saving to keep a-window painting at full rate, but a window in that mode can never idle down (three of them once-drained a laptop overnight, wiki issue #14).--So it is **opt-in and leased**:--- **Default** is Chrome's own power behaviour. Normal windows throttle when occluded and cost-  nothing in the background. Right for driving, scraping and screenshots.-- **`browser_open_window {highFps:true}`** renders at full rate while occluded, for background-  recording. It holds a lease (default 20 min), and **an active recording holds that lease open-  indefinitely, so a take is never cut off**. On lapse the window is *downgraded* back to normal-  power by relaunching with its tabs intact, never closed.-- **`browser_highfps_extend {sessionId, minutes}`** negotiates more time up front.--**Full details, defaults, activity signals, and rules of thumb: [RECORDING.md](RECORDING.md).**- ### Two recorders — pick by what you're capturing  | Verb pair | Captures | How it works under the hood |

@@ -20,8 +20,11 @@ pup is a small **Node bridge** that Adom Desktop spawns on the user's machine. W does NOT attach to the user's running browser and does NOT run headless. It:  1. **Launches a brand-new process of the browser ALREADY installed** on the machine — **installed Chrome-   first, else Microsoft Edge** (every Windows PC ships Edge). So there's usually **no download**. It uses-   their *browser binary*, never their *profile*.+   first, else Microsoft Edge**. On **Windows** every PC ships Edge, so there's almost always a candidate+   and **no download**. On **macOS** nothing is guaranteed: Safari is not CDP-drivable, and Edge is not+   preinstalled — so on a Mac with no Chrome, pup falls through to downloading Chrome (or cached Chrome+   for Testing). Don't promise the user "no download" off Windows; check `browser_readiness` instead. It+   uses their *browser binary*, never their *profile*. 2. **…with its own isolated `--user-data-dir` + a CDP debugging port** (`--remote-debugging-port`). That's    a **fresh, empty profile** — no cookies, no logins, no extensions, its own cookie jar keyed by your    `profile` name — and pup drives it over the Chrome DevTools Protocol. It is never the user's signed-in@@ -29,7 +32,8 @@ does NOT attach to the user's running browser and does NOT run headless. It:    below.) 3. **Renders a REAL window, but keeps it in the BACKGROUND.** It is *not* headless — a real GPU-composited    window, so `browser_screenshot` / recording are true-to-life and canvas/WebGL/media render correctly.-   But pup immediately z-orders it to the **bottom** (Win32 `SetWindowPos` with `SWP_NOACTIVATE`), so it+   But pup immediately z-orders it to the **bottom** (Windows: Win32 `SetWindowPos` with+   `SWP_NOACTIVATE`; macOS: the browser process is **hidden**, the Cmd+H state — same contract), so it    renders **without stealing focus and without covering the user's active window**. You drive and    screenshot it fully while it stays hidden. `foreground:true` is the ONLY thing that shows it. 4. **Spawn-verifies + falls through.** The pick order is **Chrome → Edge → cached Chrome for Testing**; pup@@ -81,6 +85,22 @@ adom-desktop browser_screenshot  '{"sessionId":"mytask-web"}' - **On a fresh PC it's usually a non-event** — pup drives the installed Chrome/Edge with no download. The   rare "no browser at all" / Node-provisioning / disk cases are all in `pup-browsers-and-chrome`. +## macOS differences (v1.9.74+) — same verbs, mac-native mechanics++Every `browser_*` verb works on macOS; only the OS-presentation layer differs:++- **Background = hidden app.** A background open launches the session's browser process hidden+  (the Cmd+H state) — truly invisible, still fully drivable/screenshottable/recordable.+  `browser_lower_os_window` re-hides; `browser_raise_os_window` (with `foregroundReason`)+  unhides + activates. One session = one browser process, so a shared-profile window group+  hides/shows together.+- **`browser_alert_window` = un-hide (not focused) + a native toast** whose click focuses the+  window — macOS has no taskbar to flash. `{stop:true}` dismisses the toast.+- **No taskbar identity on mac** — the per-window icons/badges/jump-lists below are+  Windows-only; on mac the window title's `(session: <id>)` suffix is the identity.+- **Recording** needs ffmpeg (`brew install ffmpeg` — the error hint says so; re-detects+  without a restart).+ ## Taskbar preference — the USER can ask for "combined mode"  pup windows each get their own taskbar button by default ("split": one button per window, badged@@ -116,28 +136,6 @@ logged-in view" / "...to public view") — a USER affordance that relaunches tha other cookie jar with on-screen captions. Its callback verb `browser_wiki_set_view` is not for AI threads; pass `wikiView:"authed"|"public"` on browser_open_window instead. Details: `pup-adom-wiki`. -## Recording: normal windows vs `highFps` (power matters)--pup windows are backgrounded by design, and **Chrome throttles an occluded window** — so recording-one at normal power yields a **1-2 fps** video. pup can disable Chrome's power saving to keep it-painting at full rate, but such a window **can never idle down** (three of them once drained a-laptop overnight).--So it is opt-in and **leased**:--- **Default = normal power.** Throttles when occluded, costs nothing in the background. Use this for-  driving, scraping, screenshots, waiting — i.e. almost always. Never ask for `highFps` for these.-- **`browser_open_window {highFps:true}`** for recording a window the user is NOT watching. Lease is-  **20 min** by default (max 120).-- **A running recording holds the lease open indefinitely — you cannot be cut off mid-take.**-- On lapse pup **downgrades** the window (relaunches it with its tabs, at normal power). It is NOT-  closed; content survives.-- **`browser_highfps_extend {sessionId, minutes}`** if you know up front you need longer without-  recording the whole time. You do NOT need to extend during a take.--Every `browser_open_window` response carries a power hint telling you which mode you got and how to-switch. Full detail: the bridge's `RECORDING.md`.- ## Key rules (the essentials — details in the sub-skills)  - **Always pass `sessionId`** on session-scoped verbs — `'{}'` targets the *active* session, which may not

@@ -13,8 +13,10 @@ description: "How pup (Puppeteer bridge) picks and launches a browser, and every pup drives the browser **already on the machine** — it does NOT ship or require its own. On every open it builds a candidate list and **spawn-verifies** it: -1. **Chrome → Edge → cached Chrome for Testing** (a pinned default, if set, goes first). Every Windows PC-   ships Edge, so there's almost always a candidate with **no download**.+1. **Chrome → Edge → cached Chrome for Testing** (a pinned default, if set, goes first). On **Windows**+   every PC ships Edge, so there's almost always a candidate with **no download**. On **macOS** neither+   is guaranteed — Edge is not preinstalled and Safari is not CDP-drivable — so a Mac without Chrome goes+   to the download path. Probe with `browser_readiness` rather than assuming a local browser exists. 2. It **launches a fresh process** of that browser binary with an **isolated `--user-data-dir` + a CDP    `--remote-debugging-port`** — a clean empty profile driven over the DevTools Protocol, never the user's    signed-in profile, and a **real rendered window** (not headless).@@ -62,7 +64,13 @@ adom-desktop browser_use '{"browser":"chrome","install":true}'  - Downloads Google's official installer and installs Chrome, then pins it. **On a normal PC this is   silent** (user-scoped, no prompt).-- **On a locked-down box (a VM / managed device) it needs a Windows UAC.** pup escalates automatically and,+- **macOS installs differently and never prompts for elevation.** pup downloads Google's `.dmg`, mounts it+  with `hdiutil`, `ditto`s `Google Chrome.app` to **`/Applications`**, and falls back to+  **`~/Applications`** if that isn't writable. There is no UAC, no admin prompt, and none of the+  approve-the-elevation flow below — so on a Mac, don't wait for or ask about a consent click. If the copy+  fails at both destinations the install genuinely failed; read the error rather than assuming a prompt is+  pending. The rest of this section (UAC, "click YES", re-notify) is **Windows-only**.+- **On a locked-down Windows box (a VM / managed device) it needs a Windows UAC.** pup escalates automatically and,   on **AD ≥ 1.9.84**, fires a native "**click YES to finish installing Chrome**" notification **from the   bridge itself** — on the machine with the prompt **and** pinged to whatever device the user is attending   (cross-AD). If the prompt expires it re-notifies with a one-tap "Approve now". All autonomous — no AI turn