@tiens.nguyen/gu-cli 1.0.833 → 1.0.835

package/browser-extension/README.md

@@ -0,0 +1,151 @@
+# gu browser — the agent's browser
+
+The agent's `browser(...)` tool opens a web page, sees it, and clicks and types with a real mouse and keyboard, to test a UI flow or click through an app. It follows the same idea as Claude in Chrome. The tasks are #363 (GitHub #144) and #369 (GitHub #150).
+
+**Nothing has to be installed.** The first time a turn uses the browser, gu asks you. After you allow it, the agent works in one of two places:
+
+- **Your own Chrome**, through this extension, if the extension is installed. The agent works in its own tabs (the "gu" tab group) and in any tab you share, and it has your logins.
+- **gu's own Chrome window**, if the extension is not installed. The bridge starts a Chrome of its own: a visible window on a separate profile (`~/.gonext/browser-profile`), started with its DevTools port open. It is not signed in to your accounts; sign in there once if a test needs it, and the profile keeps it.
+
+```
+agent turn (python, a new process each turn) — asks you first (#150)
+   │  HTTP + token        ~/.gonext/browser-bridge.json (0600)
+   ▼
+browser-bridge.mjs        127.0.0.1:4127, started on demand, outlives the turn
+   │                      the extension when it is connected, else gu's own window
+   ├─ WebSocket (only a chrome-extension:// origin) → this extension → chrome.debugger
+   └─ DevTools WebSocket → gu's own Chrome window (browser-chrome.mjs)
+        both run the same actions.js: real Input.dispatchMouseEvent / insertText / key events
+```
+
+## Use it (a user)
+
+- **Ask gu to check a page.** The first browser call of a turn shows:
+
+  ```
+  🌐 Allow gu to use a web browser?
+    It wants to: open http://localhost:5173
+    In your Chrome if the gu extension is there, else in gu's own Chrome window.
+     ▸ Yes, this time
+       Yes, always in this folder
+       No
+  ```
+
+  "Always" adds the folder to `~/.gonext/browser-allow.json`. A "No" holds for the rest of the turn, and the model carries on without the browser.
+- **`/browser`** shows where the agent works and whether it asks in this folder.
+- **`/browser allow` / `/browser forget`** stop or restart the question for this folder.
+- **Share a tab** (extension only): click the gu icon on a tab, then **Let gu use this tab**. The tab joins the "gu" group and the agent can use it. **Stop sharing this tab** takes it back.
+- **Turning it off:** `GU_BROWSER=0` in the worker's environment removes the tool.
+
+### The extension, to use your own Chrome (optional)
+
+Chrome lets no program turn on Developer mode or load an unpacked extension, which is why the default is gu's own window.
+
+- **Once the extension is on the Chrome Web Store:** `/browser install` opens its page; click **Add to Chrome**. No toggle is involved. Set `GU_BROWSER_STORE_URL`, then put the link in `STORE_URL` once it is published.
+- **Until then, the developer way** (`/browser install` shows it and copies the folder): turn on **Developer mode** in `chrome://extensions`, click **Load unpacked**, and choose `~/.gonext/browser-extension` (on a Mac, ⌘⇧G and paste). `/browser` should then say connected.
+
+Some notes:
+
+- **Why a fixed folder:** the extension is loaded from `~/.gonext/browser-extension`, not from the npm package, because an update moves the package and Chrome would lose an extension loaded from there. After a gu update, click reload on the extension's card.
+- **Chrome closed or asleep:** the extension reconnects within 30 seconds of Chrome starting, or immediately with its icon's **Connect now** button. It shows a purple `on` badge while connected. Meanwhile the agent uses gu's own window.
+- **The "debugging this browser" bar:** Chrome shows "gu browser started debugging this browser" while the agent works. That is the `chrome.debugger` permission, which is what makes a click a real, trusted click.
+- **Other Chromium browsers** (Edge, Brave, Arc, Chromium) load it the same way. gu's own window uses the first of Chrome, Chromium, Edge or Brave it finds; set `GU_BROWSER_CHROME` to choose.
+
+## Switch from the developer install to the store one
+
+Run this before installing the Chrome Web Store copy (#145):
+
+```
+/browser cleanup
+```
+
+1. **It lists what it found:**
+   - every Chrome, Chrome Beta/Canary, Chromium, Edge and Brave profile with "gu browser" loaded unpacked. It reads each profile's `Preferences` and `Secure Preferences` and never writes them;
+   - the connected copy;
+   - gu's files in `~/.gonext`: `browser-extension/`, `browser-bridge.json`, `browser-extension-seen`, `browser-bridge.log`.
+2. **On "Clean up", the connected developer copy removes itself** with `chrome.management.uninstallSelf`, which needs no extra permission. A store copy is never removed this way.
+3. **Copies in other profiles need your click.** Chrome signs its profile settings, so no other program can uninstall an extension. gu opens `chrome://extensions` (on a Mac) and waits while you click Remove on "gu browser" in each one.
+4. **Then it stops the bridge, deletes gu's files, scans again,** and says either `✓ The developer install is gone` or what is still there.
+
+Once the store copy is installed, `/browser` shows `(… Chrome Web Store)` and does not copy the developer folder back. The agent's not-connected answer then says "open Chrome", not "Load unpacked".
+
+If both copies stay installed, the bridge keeps the one that connected first and turns the other away with close code 4001, and the refused copy retries every 30 s instead of every 3 s. `/browser` warns `⚠ A second gu extension … — /browser cleanup removes the developer copy`.
+
+## Develop
+
+| What | How |
+| --- | --- |
+| Bridge (frames, origin/host/token checks) | `node --test tests/browser-bridge.test.mjs` |
+| `/browser` text and file copy | `node --test tests/browser-command.test.mjs` |
+| Python client and agent turns, with a stand-in extension | `python3 -m unittest tests.test_browser` |
+| **Real Chrome**, two copies of this extension unpacked (20 checks: the click must be trusted; one copy refused; the developer copy removes itself) | see below |
+| **Real Chrome, gu's own window** (no extension; 16 checks) | the same script with `--own` |
+
+The real-Chrome check needs **Chrome for Testing** or Chromium. Branded Chrome has ignored `--load-extension` since version 137.
+
+```sh
+curl -sSfLO https://storage.googleapis.com/chrome-for-testing-public/<version>/mac-arm64/chrome-mac-arm64.zip
+ditto -x -k chrome-mac-arm64.zip cft/        # not npx @puppeteer/browsers: it left the app without Frameworks
+pkill -f "Google Chrome for Testing"         # a leftover one on the same profile swallows the launch
+GU_E2E_CHROME="cft/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing" \
+  python3 scripts/browser-e2e.py
+```
+
+The check runs on a free port, with copies of the extension pointed at that port, so a gu running on 4127 with your own Chrome is left alone.
+
+To work on the extension in your own Chrome:
+
+1. Load `tools/gonext-local-worker/browser-extension` itself with **Load unpacked**.
+2. After an edit, click reload on its card.
+3. Its service worker console is under **Inspect views: service worker**.
+
+`connect()` must set its `connecting` flag before its first `await`. Chrome fires it several times at startup, and two sockets made every command hang.
+
+Which files make the extension is listed in two places, and both must change together:
+
+- `EXT_FILES` in `gu_browser.py` and in `browser-command.mjs`: what gets copied and packed.
+- `files` in `package.json`: what ships in the npm package.
+
+## Publish to the Chrome Web Store
+
+**The quick way (steps 1–2):** in the deploy app (`electric-app-deploy`), choose patch / minor / major next to **Build Chrome extension** and press it. The button:
+- raises the version in `manifest.json`;
+- checks that the scripts parse, that every file the manifest names is there, and that the bridge and `/browser` tests pass;
+- writes `release/chrome-extension/gu-browser-<version>.zip` (git-ignored) and its `.sha256` at the repo root.
+
+If any step fails, the old version is put back. The panel has **Show zip in Finder** and **Open store dashboard**. Nothing is uploaded or committed: upload the zip, then commit `manifest.json`.
+
+Publishing is optional; Load unpacked works without it. Once published, a user installs with one click, and Chrome updates the extension by itself.
+
+1. **Bump the version.** Raise `"version"` in `manifest.json`. The store refuses a version it has seen.
+2. **Build the zip.**
+
+   ```sh
+   python3 scripts/pack-browser-extension.py      # → dist/gu-browser-<version>.zip (dist/ is git-ignored)
+   ```
+
+   It packs exactly `EXT_FILES`, with `manifest.json` at the zip's root, and checks the icons exist.
+3. **Developer account** (once). Register at <https://chrome.google.com/webstore/devconsole>; there is a one-time US$5 fee. Verify the contact email.
+4. **New item.** Choose **Add new item**, upload the zip, then fill in the listing:
+   - **Description:** what it does and that it needs the gu CLI. Copy from the top of this file.
+   - **Category:** Developer Tools.
+   - **Images:** the 128×128 icon (`icons/icon128.png`) and at least one 1280×800 screenshot. A page in the "gu" tab group with the `on` badge works.
+   - **Visibility:** **Unlisted** for gu users only (installed from the link that `/browser` can print), or **Public**.
+5. **Privacy tab.** The review needs all of the following:
+   - **Single purpose:** "Lets the gu coding agent on this computer open, read and operate web pages in its own tab group, for testing web UIs."
+   - **Permission justifications:**
+     - `debugger`: send real mouse and keyboard input, take screenshots, and read console errors in gu's own tabs.
+     - `tabs`, `tabGroups`: open gu's tabs and keep them in the "gu" group.
+     - `alarms`: reconnect to the local gu bridge after Chrome puts the worker to sleep.
+     - `storage`: remember which tabs are gu's.
+     - Host permission `<all_urls>`: the agent may be asked to test any site, including localhost.
+   - **Remote code:** "No". Everything runs from the packaged files.
+   - **Data use:** website content is read only on the user's machine and sent only to the gu bridge on 127.0.0.1. Nothing is sold or transferred, and nothing is used for advertising.
+   - **Privacy policy URL:** required, because the extension handles website content. Host a short page that states the above.
+6. **Submit for review.** `debugger` and `<all_urls>` trigger an in-depth review, which can take days to a few weeks. Answer any questions in the developer console.
+7. **After approval:**
+   - The store build has a fixed extension ID. The bridge accepts any `chrome-extension://` origin, so nothing in gu changes for it.
+   - Put the store link in `/browser` (`browserReport` in `browser-command.mjs`) as the first option, and keep Load unpacked as the fallback.
+   - **Each later release:** bump the version, run `pack-browser-extension.py`, then **Package → Upload new package → Submit**.
+
+Microsoft Edge Add-ons (<https://partner.microsoft.com/dashboard/microsoftedge>) takes the same zip, with a similar listing and review.

package/browser-extension/actions.js

@@ -0,0 +1,319 @@
+// What every browser command DOES (task #363/#369, GitHub #144/#150), shared by the two ways gu
+// reaches Chrome:
+//   • the gu Chrome extension (background.js) — chrome.debugger in the user's own Chrome;
+//   • gu's own Chrome window (browser-chrome.mjs, in the bridge) — the DevTools protocol over a
+//     WebSocket, no extension, nothing to install.
+// Both speak the same DevTools protocol, so one implementation serves both. A "host" supplies the
+// tabs and the protocol:
+//   host.cdp(tabId, method, params) → result        host.attach(tabId)
+//   host.open(url, newTab) → tabId                   host.current() → tabId (throws when none)
+//   host.tabs() → [{id, title, url, current}]        host.switchTo(tabId) → boolean
+//   host.info(tabId) → {url, title, status} | null   host.activate(tabId)
+//   host.close(tabId)
+// No chrome.* and no Node API in here: it runs in an extension service worker and in Node.
+
+const consoleBuf = new Map(); // tabId → [{level, text}] since the last "console" read
+const dialogs = new Map(); // tabId → [text] of alerts/confirms gu accepted
+const freshErrors = new Map(); // tabId → errors not yet reported after a command
+
+export function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export function forgetTab(tabId) {
+  consoleBuf.delete(tabId);
+  freshErrors.delete(tabId);
+  dialogs.delete(tabId);
+}
+
+function pushConsole(tabId, level, text) {
+  const buf = consoleBuf.get(tabId) || [];
+  buf.push({ level, text: String(text).slice(0, 500) });
+  if (buf.length > 100) buf.splice(0, buf.length - 100);
+  consoleBuf.set(tabId, buf);
+  if (level === "error") freshErrors.set(tabId, [...(freshErrors.get(tabId) || []), String(text).slice(0, 300)].slice(-5));
+}
+
+/** Every DevTools event of a tab goes through here (both hosts call it). */
+export function onCdpEvent(tabId, method, params, cdp) {
+  if (method === "Runtime.consoleAPICalled") {
+    const text = (params.args || []).map((a) => (a.value !== undefined ? String(a.value) : a.description || a.type)).join(" ");
+    pushConsole(tabId, params.type === "warning" ? "warn" : params.type, text);
+  } else if (method === "Runtime.exceptionThrown") {
+    const d = params.exceptionDetails || {};
+    pushConsole(tabId, "error", `Uncaught ${d.exception?.description || d.text || "exception"}`);
+  } else if (method === "Log.entryAdded") {
+    const e = params.entry || {};
+    if (e.level === "error" || e.level === "warning") pushConsole(tabId, e.level === "warning" ? "warn" : "error", `${e.text}${e.url ? ` (${e.url})` : ""}`);
+  } else if (method === "Page.javascriptDialogOpening") {
+    // An alert/confirm would freeze the page and every later command; accept it and report it.
+    const list = dialogs.get(tabId) || [];
+    list.push(`${params.type}: ${params.message}`);
+    dialogs.set(tabId, list);
+    cdp(tabId, "Page.handleJavaScriptDialog", { accept: true, promptText: params.defaultPrompt || "" }).catch(() => {});
+  }
+}
+
+/** The domains a freshly attached tab needs, for the events above. */
+export async function enableDomains(cdp, tabId) {
+  await cdp(tabId, "Runtime.enable");
+  await cdp(tabId, "Page.enable");
+  await cdp(tabId, "Log.enable").catch(() => {});
+}
+
+async function evaluate(host, tabId, expression) {
+  const r = await host.cdp(tabId, "Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true, userGesture: true });
+  if (r.exceptionDetails) {
+    const d = r.exceptionDetails;
+    throw new Error(`page script error: ${d.exception?.description || d.text}`);
+  }
+  return r.result?.value;
+}
+
+export async function waitLoaded(host, tabId, ms = 20000) {
+  const end = Date.now() + ms;
+  await sleep(150);
+  while (Date.now() < end) {
+    const t = await host.info(tabId);
+    if (!t) throw new Error("the tab was closed");
+    if (t.status === "complete") return t;
+    await sleep(150);
+  }
+  return host.info(tabId);
+}
+
+// ── reading the page ────────────────────────────────────────────────────────────────────────
+// Runs IN the page. Numbers the visible interactive elements (data-gu-ref) so the agent can say
+// "click 7"; the numbers are good until the next read.
+function readPage(opts) {
+  const sel = 'a[href],button,input:not([type=hidden]),select,textarea,summary,[role=button],[role=link],[role=checkbox],[role=radio],[role=tab],[role=menuitem],[role=option],[role=switch],[role=combobox],[role=textbox],[contenteditable=""],[contenteditable=true],[onclick],[tabindex]:not([tabindex="-1"])';
+  const vw = innerWidth;
+  const vh = innerHeight;
+  for (const e of document.querySelectorAll("[data-gu-ref]")) e.removeAttribute("data-gu-ref");
+  const clean = (s) => String(s || "").replace(/\s+/g, " ").trim();
+  const lines = [];
+  let n = 0;
+  let below = 0;
+  for (const el of document.querySelectorAll(sel)) {
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) continue;
+    const cs = getComputedStyle(el);
+    if (cs.visibility === "hidden" || cs.display === "none" || Number(cs.opacity) === 0) continue;
+    if (!(r.bottom > 0 && r.right > 0 && r.top < vh && r.left < vw)) {
+      below++;
+      continue;
+    }
+    if (lines.length >= (opts.max || 150)) {
+      below++;
+      continue;
+    }
+    const ref = ++n;
+    el.setAttribute("data-gu-ref", String(ref));
+    const tag = el.tagName.toLowerCase();
+    const type = tag === "input" ? (el.getAttribute("type") || "text").toLowerCase() : "";
+    const role = el.getAttribute("role") || (tag === "a" ? "link" : tag === "input" ? (["checkbox", "radio", "submit", "button"].includes(type) ? type : `textbox(${type})`) : tag);
+    const label = el.labels && el.labels[0] ? el.labels[0].innerText : "";
+    const name = clean(el.getAttribute("aria-label") || label || (tag === "input" || tag === "textarea" || tag === "select" ? "" : el.innerText) || el.getAttribute("placeholder") || el.getAttribute("title") || el.getAttribute("alt") || el.getAttribute("name") || "").slice(0, 80);
+    const bits = [];
+    if ((tag === "input" && !["checkbox", "radio", "submit", "button"].includes(type)) || tag === "textarea") bits.push(`value=${JSON.stringify(String(el.value).slice(0, 60))}`);
+    if (tag === "select") bits.push(`selected=${JSON.stringify(clean(el.options[el.selectedIndex]?.text))}`);
+    if (type === "checkbox" || type === "radio") bits.push(el.checked ? "checked" : "unchecked");
+    if (el.disabled || el.getAttribute("aria-disabled") === "true") bits.push("disabled");
+    if (tag === "a") bits.push(`→ ${clean(el.getAttribute("href")).slice(0, 60)}`);
+    if (el === document.activeElement) bits.push("focused");
+    lines.push(`[${ref}] ${role} ${JSON.stringify(name)}${bits.length ? ` ${bits.join(" ")}` : ""} @${Math.round(r.left + r.width / 2)},${Math.round(r.top + r.height / 2)}`);
+  }
+  const de = document.documentElement;
+  return {
+    url: location.href,
+    title: document.title,
+    viewport: `${vw}x${vh}`,
+    scroll: `${Math.round(scrollY)} of ${Math.max(0, de.scrollHeight - vh)}`,
+    elements: lines,
+    offscreen: below,
+    text: String((document.body && document.body.innerText) || "").replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim().slice(0, opts.maxText || 6000),
+  };
+}
+
+async function refPoint(host, tabId, ref) {
+  const p = await evaluate(host, tabId, `(() => {
+    const el = document.querySelector('[data-gu-ref="${Number(ref)}"]');
+    if (!el) return null;
+    el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+    const r = el.getBoundingClientRect();
+    return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+  })()`);
+  if (!p) throw new Error(`no element [${ref}] on the page now — read the page again for fresh numbers`);
+  return p;
+}
+
+// What is really under the point — an overlay or a cookie banner takes the click, not the button.
+async function hitAt(host, tabId, x, y) {
+  return evaluate(host, tabId, `(() => {
+    const el = document.elementFromPoint(${x}, ${y});
+    if (!el) return "nothing";
+    const t = (el.innerText || el.value || el.getAttribute("aria-label") || "").replace(/\\s+/g, " ").trim().slice(0, 50);
+    return el.tagName.toLowerCase() + (el.id ? "#" + el.id : "") + (t ? ' "' + t + '"' : "");
+  })()`);
+}
+
+const hasRef = (cmd) => cmd.ref !== undefined && cmd.ref !== null && cmd.ref !== "";
+
+async function point(host, tabId, cmd) {
+  if (hasRef(cmd)) return refPoint(host, tabId, cmd.ref);
+  if (Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) return { x: cmd.x, y: cmd.y };
+  throw new Error("say where: ref (a number from read) or x and y");
+}
+
+async function mouse(host, tabId, x, y, button = "left", clicks = 1) {
+  await host.cdp(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+  for (let i = 1; i <= clicks; i++) {
+    await host.cdp(tabId, "Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, clickCount: i });
+    await host.cdp(tabId, "Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, clickCount: i });
+  }
+}
+
+// ── keys ────────────────────────────────────────────────────────────────────────────────────
+const KEYS = {
+  enter: ["Enter", "Enter", 13, "\r"], tab: ["Tab", "Tab", 9], escape: ["Escape", "Escape", 27], esc: ["Escape", "Escape", 27],
+  backspace: ["Backspace", "Backspace", 8], delete: ["Delete", "Delete", 46], space: [" ", "Space", 32, " "],
+  arrowup: ["ArrowUp", "ArrowUp", 38], arrowdown: ["ArrowDown", "ArrowDown", 40], arrowleft: ["ArrowLeft", "ArrowLeft", 37],
+  arrowright: ["ArrowRight", "ArrowRight", 39], up: ["ArrowUp", "ArrowUp", 38], down: ["ArrowDown", "ArrowDown", 40],
+  left: ["ArrowLeft", "ArrowLeft", 37], right: ["ArrowRight", "ArrowRight", 39], home: ["Home", "Home", 36], end: ["End", "End", 35],
+  pageup: ["PageUp", "PageUp", 33], pagedown: ["PageDown", "PageDown", 34],
+};
+const MODS = { alt: 1, option: 1, ctrl: 2, control: 2, meta: 4, cmd: 4, command: 4, shift: 8 };
+
+async function pressKey(host, tabId, combo) {
+  const parts = String(combo).split("+").map((s) => s.trim()).filter(Boolean);
+  let mods = 0;
+  for (const p of parts.slice(0, -1)) mods |= MODS[p.toLowerCase()] || 0;
+  const k = parts[parts.length - 1] || "";
+  // Select-all and friends are editor COMMANDS in Chrome: a bare ctrl+a does not select on a Mac.
+  const cmdName = (mods & 6) && /^[acvxz]$/i.test(k) ? { a: "selectAll", c: "copy", v: "paste", x: "cut", z: "undo" }[k.toLowerCase()] : null;
+  let key, code, keyCode, text;
+  if (KEYS[k.toLowerCase()]) [key, code, keyCode, text] = KEYS[k.toLowerCase()];
+  else if (k.length === 1) {
+    key = mods & 8 ? k.toUpperCase() : k;
+    code = /[a-z]/i.test(k) ? `Key${k.toUpperCase()}` : /\d/.test(k) ? `Digit${k}` : "";
+    keyCode = k.toUpperCase().charCodeAt(0);
+    text = key;
+  } else throw new Error(`unknown key "${k}" — use Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, Space or one character, with ctrl+ / shift+ / alt+ / meta+`);
+  if (mods & 7) text = undefined; // a shortcut types nothing
+  const base = { key, code, windowsVirtualKeyCode: keyCode, modifiers: mods };
+  await host.cdp(tabId, "Input.dispatchKeyEvent", { ...base, type: text ? "keyDown" : "rawKeyDown", text, ...(cmdName ? { commands: [cmdName] } : {}) });
+  await host.cdp(tabId, "Input.dispatchKeyEvent", { ...base, type: "keyUp" });
+}
+
+// ── the commands ────────────────────────────────────────────────────────────────────────────
+async function settle(host, tabId) {
+  await sleep(350);
+  const t = await host.info(tabId);
+  if (t && t.status === "loading") await waitLoaded(host, tabId, 15000);
+}
+
+async function after(host, tabId, extra = {}) {
+  const t = await host.info(tabId);
+  const errs = freshErrors.get(tabId) || [];
+  const dl = dialogs.get(tabId) || [];
+  freshErrors.delete(tabId);
+  dialogs.delete(tabId);
+  return { tab: tabId, url: t?.url || "", title: t?.title || "", errors: errs, dialogs: dl, ...extra };
+}
+
+export async function runAction(cmd, host) {
+  const a = String(cmd.action || "").toLowerCase();
+  if (a === "open") {
+    const url = String(cmd.url || "");
+    if (!/^(https?|file):\/\//i.test(url) && !/^about:blank$/i.test(url)) throw new Error("open needs a full http(s):// or file:// url");
+    const id = await host.open(url, Boolean(cmd.new_tab));
+    await host.attach(id);
+    await waitLoaded(host, id);
+    return after(host, id);
+  }
+  if (a === "tabs") return { tabs: await host.tabs() };
+  if (a === "switch") {
+    const id = cmd.tab;
+    if (!(await host.switchTo(id))) throw new Error(`tab ${cmd.tab} is not one of gu's tabs — see action "tabs"`);
+    return after(host, id);
+  }
+  const id = await host.current();
+  if (a === "close") {
+    await host.close(id);
+    forgetTab(id);
+    return { closed: id };
+  }
+  await host.attach(id);
+  switch (a) {
+    case "read":
+      return { ...(await evaluate(host, id, `(${readPage})(${JSON.stringify({ maxText: cmd.max_text || 6000 })})`)), ...(await after(host, id)) };
+    case "screenshot": {
+      await host.activate(id); // a background tab is not painted
+      const m = await host.cdp(id, "Page.getLayoutMetrics");
+      const vp = m.cssVisualViewport || m.visualViewport || {};
+      const shot = await host.cdp(id, "Page.captureScreenshot", { format: "jpeg", quality: 80 });
+      return { ...(await after(host, id)), image: shot.data, mime: "image/jpeg", width: Math.round(vp.clientWidth), height: Math.round(vp.clientHeight) };
+    }
+    case "click":
+    case "double_click":
+    case "right_click":
+    case "hover": {
+      const p = await point(host, id, cmd);
+      const hit = await hitAt(host, id, p.x, p.y);
+      if (a === "hover") await host.cdp(id, "Input.dispatchMouseEvent", { type: "mouseMoved", x: p.x, y: p.y });
+      else await mouse(host, id, p.x, p.y, a === "right_click" ? "right" : "left", a === "double_click" ? 2 : 1);
+      await settle(host, id);
+      return after(host, id, { at: `${Math.round(p.x)},${Math.round(p.y)}`, hit });
+    }
+    case "type": {
+      if (hasRef(cmd)) {
+        const p = await refPoint(host, id, cmd.ref);
+        await mouse(host, id, p.x, p.y);
+        if (cmd.clear) await pressKey(host, id, "ctrl+a");
+      }
+      await host.cdp(id, "Input.insertText", { text: String(cmd.text ?? "") });
+      if (cmd.submit) await pressKey(host, id, "Enter");
+      await settle(host, id);
+      return after(host, id);
+    }
+    case "key":
+      for (const k of String(cmd.text || "").split(/\s+/).filter(Boolean)) await pressKey(host, id, k);
+      await settle(host, id);
+      return after(host, id);
+    case "scroll": {
+      const m = await host.cdp(id, "Page.getLayoutMetrics");
+      const vp = m.cssVisualViewport || {};
+      const x = Number.isFinite(cmd.x) ? cmd.x : vp.clientWidth / 2;
+      const y = Number.isFinite(cmd.y) ? cmd.y : vp.clientHeight / 2;
+      const amount = Number(cmd.amount) || Math.round((vp.clientHeight || 800) * 0.8);
+      const dir = String(cmd.direction || "down").toLowerCase();
+      const dx = dir === "left" ? -amount : dir === "right" ? amount : 0;
+      const dy = dir === "up" ? -amount : dir === "down" ? amount : 0;
+      await host.cdp(id, "Input.dispatchMouseEvent", { type: "mouseWheel", x, y, deltaX: dx, deltaY: dy });
+      await sleep(300);
+      return after(host, id, { scroll: await evaluate(host, id, "Math.round(scrollY) + ' of ' + Math.max(0, document.documentElement.scrollHeight - innerHeight)") });
+    }
+    case "back":
+      await evaluate(host, id, "history.back()");
+      await settle(host, id);
+      return after(host, id);
+    case "reload":
+      await host.cdp(id, "Page.reload", { ignoreCache: true });
+      await settle(host, id);
+      return after(host, id);
+    case "wait":
+      await sleep(Math.max(0, Math.min(Number(cmd.seconds) || 1, 30)) * 1000);
+      return after(host, id);
+    case "js": {
+      const value = await evaluate(host, id, String(cmd.text || ""));
+      return after(host, id, { value: value === undefined ? "undefined" : JSON.stringify(value)?.slice(0, 8000) });
+    }
+    case "console": {
+      const all = consoleBuf.get(id) || [];
+      consoleBuf.set(id, []);
+      return after(host, id, { console: all });
+    }
+    default:
+      throw new Error(`unknown action "${cmd.action}"`);
+  }
+}