@tiens.nguyen/gu-cli 1.0.833 → 1.0.834

package/README.md

@@ -57,6 +57,7 @@ server. After picking, `gu doctor` shows the URL and model that are actually in
 | `/model`, `/agent-model`, `/embed-model` | switch models (see above) |
 | `/context-window [tokens\|auto]` | tell gu how big the coding model's context is (hosted models cannot be probed) |
 | `/doctor` | check every configured model answers, especially the embedder |
+| `/browser` | the gu Chrome extension the agent uses to open, see and click web pages (UI tests): is it connected, and how to install it (Load unpacked from `~/.gonext/browser-extension`); setup and Chrome Web Store publishing: [browser-extension/README.md](browser-extension/README.md) |
 | `/tokens` | break down the last prompt sent to the coding model — how much of it was RAG |
 | `/prices [update]` | price and cache tables, and what the last turn and this session cost |
 | `/rag` | where this folder's RAG knowledge base lives: local, cloud, or both |

package/browser-bridge.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// The browser bridge (task #363, GitHub #144): the gu Chrome extension holds a WebSocket to this
+// process, and the agent's browser tool (a new Python process every turn) sends it commands over
+// HTTP. The bridge outlives a turn so the extension stays connected between them.
+//
+// Local only, and only for the two who should use it:
+//   • it listens on 127.0.0.1 and refuses a Host header that is not 127.0.0.1/localhost
+//     (a web page cannot reach it through DNS rebinding);
+//   • the WebSocket is accepted only from an Origin of chrome-extension:// — a web page cannot
+//     forge that header;
+//   • a command needs the token in ~/.gonext/browser-bridge.json, which only this user can read.
+//
+// No dependency: the WebSocket is the few lines of RFC 6455 a single local client needs.
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_PORT = 4127;
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+export function statePath() {
+  return process.env.GU_BROWSER_STATE || join(homedir(), ".gonext", "browser-bridge.json");
+}
+
+// ── WebSocket frames ────────────────────────────────────────────────────────────────────────
+export function encodeFrame(text, opcode = 1) {
+  const payload = Buffer.from(text);
+  const n = payload.length;
+  const head = n < 126 ? Buffer.alloc(2) : n < 65536 ? Buffer.alloc(4) : Buffer.alloc(10);
+  head[0] = 0x80 | opcode;
+  if (n < 126) head[1] = n;
+  else if (n < 65536) {
+    head[1] = 126;
+    head.writeUInt16BE(n, 2);
+  } else {
+    head[1] = 127;
+    head.writeBigUInt64BE(BigInt(n), 2);
+  }
+  return Buffer.concat([head, payload]);
+}
+
+// Pulls whole frames off the front of buf. Returns { frames: [{fin, opcode, payload}], rest }.
+export function decodeFrames(buf) {
+  const frames = [];
+  let off = 0;
+  while (buf.length - off >= 2) {
+    const b0 = buf[off];
+    const b1 = buf[off + 1];
+    let len = b1 & 0x7f;
+    let p = off + 2;
+    if (len === 126) {
+      if (buf.length < p + 2) break;
+      len = buf.readUInt16BE(p);
+      p += 2;
+    } else if (len === 127) {
+      if (buf.length < p + 8) break;
+      len = Number(buf.readBigUInt64BE(p));
+      p += 8;
+    }
+    const masked = (b1 & 0x80) !== 0;
+    const mask = masked ? buf.subarray(p, p + 4) : null;
+    if (masked) p += 4;
+    if (buf.length < p + len) break;
+    const payload = Buffer.from(buf.subarray(p, p + len));
+    if (mask) for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+    frames.push({ fin: (b0 & 0x80) !== 0, opcode: b0 & 0x0f, payload });
+    off = p + len;
+  }
+  return { frames, rest: buf.subarray(off) };
+}
+
+// ── the bridge ──────────────────────────────────────────────────────────────────────────────
+export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toString("hex"), idleMs = 4 * 3600e3, log = () => {} } = {}) {
+  let ext = null; // { socket, version }
+  let nextId = 1;
+  const pending = new Map(); // id → { resolve, timer }
+  const waiters = new Set(); // resolve() when the extension connects
+  let lastUse = Date.now();
+
+  const hostOk = (h) => /^(127\.0\.0\.1|localhost)(:\d+)?$/i.test(String(h || ""));
+
+  function dropExtension(sock) {
+    if (!ext || ext.socket !== sock) return;
+    ext = null;
+    for (const [id, p] of pending) {
+      clearTimeout(p.timer);
+      p.resolve({ ok: false, error: "the gu Chrome extension disconnected" });
+      pending.delete(id);
+    }
+  }
+
+  function send(cmd, timeoutMs) {
+    return new Promise((resolve) => {
+      if (!ext) return resolve({ ok: false, error: "not connected", notConnected: true });
+      const id = nextId++;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        resolve({ ok: false, error: `the browser did not answer in ${Math.round(timeoutMs / 1000)}s` });
+      }, timeoutMs);
+      pending.set(id, { resolve, timer });
+      ext.socket.write(encodeFrame(JSON.stringify({ ...cmd, id })));
+    });
+  }
+
+  function waitConnected(ms) {
+    if (ext || ms <= 0) return Promise.resolve(Boolean(ext));
+    return new Promise((resolve) => {
+      const done = (v) => {
+        clearTimeout(t);
+        waiters.delete(done);
+        resolve(v);
+      };
+      const t = setTimeout(() => done(Boolean(ext)), ms);
+      waiters.add(done);
+    });
+  }
+
+  const server = createServer(async (req, res) => {
+    const json = (code, body) => {
+      res.writeHead(code, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+    if (!hostOk(req.headers.host) || req.headers.origin) return json(403, { error: "forbidden" });
+    if (req.headers.authorization !== `Bearer ${token}`) return json(401, { error: "bad token" });
+    lastUse = Date.now();
+    const url = new URL(req.url, "http://127.0.0.1");
+    if (req.method === "GET" && url.pathname === "/status") {
+      const waitMs = Math.min(Number(url.searchParams.get("wait_ms")) || 0, 60000);
+      await waitConnected(waitMs);
+      return json(200, { connected: Boolean(ext), version: ext?.version || null, pid: process.pid });
+    }
+    if (req.method === "POST" && url.pathname === "/cmd") {
+      let body = "";
+      for await (const c of req) body += c;
+      let cmd;
+      try {
+        cmd = JSON.parse(body);
+      } catch {
+        return json(400, { error: "bad json" });
+      }
+      const timeoutMs = Math.min(Math.max(Number(cmd.timeout_ms) || 60000, 1000), 120000);
+      delete cmd.timeout_ms;
+      const r = await send(cmd, timeoutMs);
+      return json(r.notConnected ? 503 : 200, r);
+    }
+    json(404, { error: "not found" });
+  });
+
+  server.on("upgrade", (req, socket) => {
+    const origin = String(req.headers.origin || "");
+    const key = req.headers["sec-websocket-key"];
+    if (!hostOk(req.headers.host) || !origin.startsWith("chrome-extension://") || !key || new URL(req.url, "http://x").pathname !== "/extension") {
+      socket.end("HTTP/1.1 403 Forbidden\r\n\r\n");
+      return;
+    }
+    const accept = createHash("sha1").update(key + WS_GUID).digest("base64");
+    socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+    socket.setNoDelay(true);
+    if (ext) ext.socket.destroy(); // the newest extension wins (Chrome restarted it)
+    ext = { socket, version: null, origin };
+    log(`extension connected (${origin})`);
+    let buf = Buffer.alloc(0);
+    let parts = [];
+    socket.on("data", (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      const { frames, rest } = decodeFrames(buf);
+      buf = Buffer.from(rest);
+      for (const f of frames) {
+        if (f.opcode === 8) {
+          socket.end(encodeFrame("", 8));
+          return;
+        }
+        if (f.opcode === 9) {
+          socket.write(encodeFrame(f.payload.toString(), 10));
+          continue;
+        }
+        if (f.opcode === 10) continue;
+        parts.push(f.payload);
+        if (!f.fin) continue;
+        const text = Buffer.concat(parts).toString("utf8");
+        parts = [];
+        let msg;
+        try {
+          msg = JSON.parse(text);
+        } catch {
+          continue;
+        }
+        if (msg.type === "hello") {
+          if (ext?.socket === socket) ext.version = msg.version || "?";
+          for (const w of [...waiters]) w(true);
+        } else if (msg.id !== undefined && pending.has(msg.id)) {
+          const p = pending.get(msg.id);
+          pending.delete(msg.id);
+          clearTimeout(p.timer);
+          p.resolve(msg.ok ? { ok: true, result: msg.result } : { ok: false, error: msg.error || "failed" });
+        }
+      }
+    });
+    socket.on("close", () => dropExtension(socket));
+    socket.on("error", () => dropExtension(socket));
+  });
+
+  const idle = setInterval(() => {
+    if (Date.now() - lastUse > idleMs) {
+      log("idle — exiting");
+      server.close();
+      clearInterval(idle);
+      if (ext) ext.socket.destroy();
+      server.emit("idle-exit");
+    }
+  }, Math.min(idleMs, 60000));
+  idle.unref();
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      resolve({
+        server,
+        port: server.address().port,
+        token,
+        connected: () => Boolean(ext),
+        close: () => {
+          clearInterval(idle);
+          if (ext) ext.socket.destroy();
+          return new Promise((r) => server.close(() => r()));
+        },
+      });
+    });
+  });
+}
+
+// ── run as a program: gu starts it on demand, detached ──────────────────────────────────────
+async function main() {
+  const path = statePath();
+  const port = process.env.GU_BROWSER_PORT !== undefined ? Number(process.env.GU_BROWSER_PORT) : DEFAULT_PORT;
+  const log = (m) => process.stderr.write(`[gu-browser-bridge] ${m}\n`);
+  let b;
+  try {
+    b = await startBridge({ port, log });
+  } catch (e) {
+    log(`cannot listen on 127.0.0.1:${port}: ${e.code || e.message}`);
+    process.exit(3);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify({ port: b.port, token: b.token, pid: process.pid, started: Date.now() / 1000 }), { mode: 0o600 });
+  log(`listening on 127.0.0.1:${b.port}`);
+  const cleanup = () => {
+    try {
+      if (JSON.parse(readFileSync(path, "utf8")).pid === process.pid) unlinkSync(path);
+    } catch {
+      /* gone */
+    }
+  };
+  b.server.on("idle-exit", () => {
+    cleanup();
+    process.exit(0);
+  });
+  for (const sig of ["SIGTERM", "SIGINT"]) process.on(sig, () => {
+    cleanup();
+    process.exit(0);
+  });
+}
+
+const isMain = (() => {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) main();

package/browser-command.mjs

@@ -0,0 +1,116 @@
+// /browser (task #363, GitHub #144): is the gu Chrome extension connected, and how to install it.
+//
+// The extension is loaded from a FIXED folder, ~/.gonext/browser-extension, not from the npm
+// package: an update moves the package and Chrome would lose an unpacked extension loaded there.
+// The files are copied there (again after an update) every time this runs, as the agent does.
+import { spawn } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, openSync, closeSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const EXT_SRC = join(HERE, "browser-extension");
+export const EXT_FILES = ["manifest.json", "background.js", "popup.html", "popup.js", "icons/icon16.png", "icons/icon48.png", "icons/icon128.png"];
+
+const dataDir = () => join(homedir(), ".gonext");
+export const extensionDir = () => process.env.GU_BROWSER_EXT_DIR || join(dataDir(), "browser-extension");
+const statePath = () => process.env.GU_BROWSER_STATE || join(dataDir(), "browser-bridge.json");
+
+export function installExtensionFiles(src = EXT_SRC, dst = extensionDir()) {
+  mkdirSync(join(dst, "icons"), { recursive: true });
+  for (const n of EXT_FILES) {
+    const from = join(src, n);
+    const to = join(dst, n);
+    if (!existsSync(to) || !readFileSync(to).equals(readFileSync(from))) copyFileSync(from, to);
+  }
+  return dst;
+}
+
+function readState() {
+  try {
+    const st = JSON.parse(readFileSync(statePath(), "utf8"));
+    return st.port && st.token ? st : null;
+  } catch {
+    return null;
+  }
+}
+
+async function status(st, waitMs = 0) {
+  const r = await fetch(`http://127.0.0.1:${st.port}/status?wait_ms=${waitMs}`, {
+    headers: { authorization: `Bearer ${st.token}` },
+    signal: AbortSignal.timeout(waitMs + 3000),
+  });
+  return r.json();
+}
+
+// → { running, connected, version }. Starts the bridge when it is not running, so an extension
+// installed a moment from now has something to connect to.
+export async function bridgeStatus({ start = true, waitMs = 1500 } = {}) {
+  let st = readState();
+  try {
+    if (st) return { running: true, ...(await status(st, waitMs)) };
+  } catch {
+    /* stale state file */
+  }
+  if (!start) return { running: false, connected: false };
+  mkdirSync(dataDir(), { recursive: true });
+  const log = openSync(join(dataDir(), "browser-bridge.log"), "a");
+  spawn(process.execPath, [join(HERE, "browser-bridge.mjs")], { detached: true, stdio: ["ignore", log, log] }).unref();
+  closeSync(log);
+  const end = Date.now() + 5000;
+  while (Date.now() < end) {
+    await new Promise((r) => setTimeout(r, 150));
+    st = readState();
+    if (!st) continue;
+    try {
+      return { running: true, ...(await status(st, waitMs)) };
+    } catch {
+      /* not listening yet */
+    }
+  }
+  return { running: false, connected: false };
+}
+
+export function browserReport({ connected, version, running }, folder, platform = process.platform) {
+  if (connected) {
+    return [
+      `✓ The gu Chrome extension is connected (v${version}).`,
+      "The agent can open and use web pages in its own tabs (the \"gu\" tab",
+      "group) to test a UI, click through a flow or fill a form.",
+      "Your other tabs are never touched.",
+    ];
+  }
+  const pick = platform === "darwin"
+    ? ["     In the file dialog press ⌘⇧G, paste the folder (it is on your", "     clipboard) and press Enter."]
+    : ["     In the file dialog type or paste the folder (it starts with a dot,", "     so it is hidden)."];
+  return [
+    running ? "The gu Chrome extension is not connected." : "The gu browser bridge could not start (is node working?).",
+    "The agent uses it to open, see and click web pages like a person.",
+    "To install it:",
+    "  1. Open Chrome and go to chrome://extensions",
+    "  2. Turn on Developer mode (top right)",
+    "  3. Click \"Load unpacked\" and choose this folder:",
+    `       ${folder}`,
+    ...pick,
+    "  4. Type /browser again — it should say connected.",
+    "Already installed? Open Chrome: it reconnects within 30 seconds",
+    "(or click the extension's icon → Connect now).",
+  ];
+}
+
+// macOS: put the folder on the clipboard and open the extensions page, so step 3 is a paste.
+export function helpInstall(folder, platform = process.platform) {
+  if (platform !== "darwin") return false;
+  try {
+    const cp = spawn("pbcopy", [], { stdio: ["pipe", "ignore", "ignore"] });
+    cp.stdin.end(folder);
+    if (existsSync("/Applications/Google Chrome.app")) {
+      spawn("open", ["-a", "Google Chrome", "chrome://extensions"], { stdio: "ignore", detached: true }).unref();
+      return true;
+    }
+  } catch {
+    /* best effort */
+  }
+  return false;
+}

package/browser-extension/README.md

@@ -0,0 +1,111 @@
+# gu browser — Chrome extension
+
+The agent's `browser(...)` tool works through this extension. With it, the agent 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 task is #363 (GitHub #144).
+
+```
+agent turn (python, a new process each turn)
+   │  HTTP + token        ~/.gonext/browser-bridge.json (0600)
+   ▼
+browser-bridge.mjs        127.0.0.1:4127, started on demand, outlives the turn
+   │  WebSocket           only from a chrome-extension:// origin
+   ▼
+this extension            chrome.debugger → real Input.dispatchMouseEvent / insertText / key events
+   │
+   ▼
+gu's own tabs only        the tab group "gu" and the popups those tabs open
+```
+
+## Set up (a user)
+
+1. Install or update gu. The extension ships inside the npm package.
+2. Type `/browser` in the gu terminal. It copies the extension to `~/.gonext/browser-extension`, starts the bridge and shows whether the extension is connected. On a Mac it also opens `chrome://extensions` and puts the folder path on the clipboard.
+3. In Chrome open `chrome://extensions` and turn on **Developer mode** (top right).
+4. Click **Load unpacked** and choose `~/.gonext/browser-extension`.
+   - **Mac:** in the file dialog press ⌘⇧G and paste the path. The folder starts with a dot, so it is hidden.
+   - **Linux / Windows:** type or paste the path.
+5. Type `/browser` again. It should say `✓ The gu Chrome extension is 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:** gu copies the new files into that folder. Click the reload icon on the extension's card in `chrome://extensions`, or restart Chrome.
+- **Chrome closed or asleep:** the extension reconnects within 30 seconds of Chrome starting. The extension's icon has a **Connect now** button, and it shows a purple `on` badge while connected.
+- **When it is not connected:** the agent's tool answers `BROWSER NOT AVAILABLE` with these steps. The prompt tells the model to stop and ask you, not to work around it.
+- **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 from their own extensions page.
+
+Turning it off:
+
+- `GU_BROWSER=0` in the worker's environment removes the tool.
+- Removing the extension in `chrome://extensions` disconnects it.
+
+## 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**, this extension unpacked (15 checks; the click must be trusted) | see below |
+
+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 uses port 4127, so stop any other gu bridge first.
+
+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
+
+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.