@tiens.nguyen/gu-cli 1.0.833 → 1.0.834

package/browser-extension/background.js

@@ -0,0 +1,483 @@
+// gu browser — the Chrome side of the agent's browser tool (task #363, GitHub #144).
+//
+// The extension connects to gu's local bridge (browser-bridge.mjs, ws://127.0.0.1:4127) and runs
+// the commands the agent sends. Input goes through chrome.debugger (the DevTools protocol), so a
+// click is a real mouse press and release at a point, and typing is real key input, the way a
+// person would do it, not el.click().
+//
+// gu only works in ITS OWN tabs: the ones it opened (kept in a tab group named "gu") and the
+// popups those open. The user's other tabs are never read, captured or controlled.
+
+const DEFAULT_PORT = 4127;
+const VERSION = chrome.runtime.getManifest().version;
+
+let ws = null;
+let connecting = false; // set before the first await: startup fires connect() several times at once
+let pingTimer = null;
+const attached = new Set();
+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
+
+// ── connection ──────────────────────────────────────────────────────────────────────────────
+async function bridgePort() {
+  try {
+    const { port } = await chrome.storage.local.get("port");
+    return Number(port) || DEFAULT_PORT;
+  } catch {
+    return DEFAULT_PORT;
+  }
+}
+
+async function connect() {
+  if (connecting || (ws && (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN))) return;
+  connecting = true;
+  let sock;
+  try {
+    sock = new WebSocket(`ws://127.0.0.1:${await bridgePort()}/extension`);
+  } catch {
+    return;
+  } finally {
+    connecting = false;
+  }
+  ws = sock;
+  sock.onopen = () => {
+    sock.send(JSON.stringify({ type: "hello", version: VERSION }));
+    setBadge(true);
+    clearInterval(pingTimer);
+    // An open socket that carries a message at least every 30 s keeps the service worker awake.
+    pingTimer = setInterval(() => sock.readyState === WebSocket.OPEN && sock.send('{"type":"ping"}'), 20000);
+  };
+  sock.onmessage = (ev) => onCommand(sock, ev.data);
+  sock.onclose = () => {
+    if (ws !== sock) return; // an older socket the bridge replaced
+    ws = null;
+    clearInterval(pingTimer);
+    setBadge(false);
+    setTimeout(connect, 3000);
+  };
+  sock.onerror = () => {};
+}
+
+function setBadge(on) {
+  chrome.action.setBadgeText({ text: on ? "on" : "" }).catch(() => {});
+  chrome.action.setBadgeBackgroundColor({ color: "#6d5bd0" }).catch(() => {});
+}
+
+// The service worker sleeps when nothing happens; the alarm wakes it to retry the bridge.
+chrome.alarms.create("gu-connect", { periodInMinutes: 0.5 });
+chrome.alarms.onAlarm.addListener(() => connect());
+chrome.runtime.onStartup.addListener(() => connect());
+chrome.runtime.onInstalled.addListener(() => connect());
+chrome.runtime.onMessage.addListener((msg, _sender, reply) => {
+  if (msg?.type === "status") {
+    reply({ connected: Boolean(ws && ws.readyState === WebSocket.OPEN), version: VERSION });
+  } else if (msg?.type === "reconnect") {
+    connect().then(() => reply({ ok: true }));
+    return true;
+  }
+  return false;
+});
+connect();
+
+async function onCommand(sock, data) {
+  let msg;
+  try {
+    msg = JSON.parse(data);
+  } catch {
+    return;
+  }
+  if (!msg || msg.id === undefined) return;
+  let reply;
+  try {
+    reply = { id: msg.id, ok: true, result: await run(msg) };
+  } catch (e) {
+    reply = { id: msg.id, ok: false, error: String(e?.message || e) };
+  }
+  if (sock.readyState === WebSocket.OPEN) sock.send(JSON.stringify(reply));
+}
+
+// ── gu's tabs ───────────────────────────────────────────────────────────────────────────────
+async function state() {
+  const s = await chrome.storage.session.get(["tabs", "current", "group"]);
+  return { tabs: s.tabs || [], current: s.current ?? null, group: s.group ?? null };
+}
+
+async function saveState(patch) {
+  await chrome.storage.session.set(patch);
+}
+
+async function liveTabs() {
+  const s = await state();
+  const live = [];
+  for (const id of s.tabs) {
+    try {
+      live.push(await chrome.tabs.get(id));
+    } catch {
+      /* closed */
+    }
+  }
+  if (live.length !== s.tabs.length) await saveState({ tabs: live.map((t) => t.id) });
+  return live;
+}
+
+async function addToGroup(tabId) {
+  const s = await state();
+  let group = s.group;
+  try {
+    group = await chrome.tabs.group(group != null ? { tabIds: [tabId], groupId: group } : { tabIds: [tabId] });
+  } catch {
+    group = await chrome.tabs.group({ tabIds: [tabId] }); // the old group was closed
+  }
+  await chrome.tabGroups.update(group, { title: "gu", color: "purple" }).catch(() => {});
+  const tabs = s.tabs.includes(tabId) ? s.tabs : [...s.tabs, tabId];
+  await saveState({ tabs, group });
+}
+
+// A page gu opened that opens another (target=_blank, window.open) — that one is gu's too.
+chrome.tabs.onCreated.addListener(async (tab) => {
+  const s = await state();
+  if (tab.openerTabId != null && s.tabs.includes(tab.openerTabId)) {
+    await addToGroup(tab.id).catch(() => {});
+    await saveState({ current: tab.id });
+  }
+});
+
+async function currentTab() {
+  const tabs = await liveTabs();
+  if (!tabs.length) throw new Error('gu has no tab open yet — use action "open" with a url first');
+  const s = await state();
+  return tabs.find((t) => t.id === s.current) || tabs[tabs.length - 1];
+}
+
+async function waitLoaded(tabId, ms = 20000) {
+  const end = Date.now() + ms;
+  await sleep(150);
+  while (Date.now() < end) {
+    const t = await chrome.tabs.get(tabId).catch(() => null);
+    if (!t) throw new Error("the tab was closed");
+    if (t.status === "complete") return t;
+    await sleep(150);
+  }
+  return chrome.tabs.get(tabId);
+}
+
+// ── DevTools protocol ───────────────────────────────────────────────────────────────────────
+async function attach(tabId) {
+  if (attached.has(tabId)) return;
+  try {
+    await chrome.debugger.attach({ tabId }, "1.3");
+  } catch (e) {
+    if (!/already attached/i.test(String(e?.message))) {
+      throw new Error(`cannot control this tab (${e?.message || e}) — Chrome pages (chrome://, the Web Store) cannot be automated`);
+    }
+  }
+  attached.add(tabId);
+  await cdp(tabId, "Runtime.enable");
+  await cdp(tabId, "Page.enable");
+  await cdp(tabId, "Log.enable").catch(() => {});
+}
+
+function cdp(tabId, method, params = {}) {
+  return chrome.debugger.sendCommand({ tabId }, method, params);
+}
+
+chrome.debugger.onDetach.addListener((src) => attached.delete(src.tabId));
+chrome.tabs.onRemoved.addListener((tabId) => {
+  attached.delete(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));
+}
+
+chrome.debugger.onEvent.addListener((src, method, params) => {
+  const tabId = src.tabId;
+  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(() => {});
+  }
+});
+
+async function evaluate(tabId, expression) {
+  const r = await 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;
+}
+
+// ── 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(tabId, ref) {
+  const p = await evaluate(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(tabId, x, y) {
+  return evaluate(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 + '"' : "");
+  })()`);
+}
+
+async function point(tabId, cmd) {
+  if (cmd.ref !== undefined && cmd.ref !== null && cmd.ref !== "") return refPoint(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(tabId, x, y, button = "left", clicks = 1) {
+  await cdp(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+  for (let i = 1; i <= clicks; i++) {
+    await cdp(tabId, "Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, clickCount: i });
+    await 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(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 cdp(tabId, "Input.dispatchKeyEvent", { ...base, type: text ? "keyDown" : "rawKeyDown", text, ...(cmdName ? { commands: [cmdName] } : {}) });
+  await cdp(tabId, "Input.dispatchKeyEvent", { ...base, type: "keyUp" });
+}
+
+// ── the commands ────────────────────────────────────────────────────────────────────────────
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function settle(tabId) {
+  await sleep(350);
+  const t = await chrome.tabs.get(tabId).catch(() => null);
+  if (t && t.status === "loading") await waitLoaded(tabId, 15000);
+}
+
+async function after(tabId, extra = {}) {
+  const t = await chrome.tabs.get(tabId).catch(() => null);
+  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 };
+}
+
+async function run(cmd) {
+  const a = String(cmd.action || "").toLowerCase();
+  if (a === "status") return { version: VERSION };
+  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 tabs = await liveTabs();
+    const s = await state();
+    let tab = cmd.new_tab ? null : tabs.find((t) => t.id === s.current) || tabs[tabs.length - 1];
+    if (tab) tab = await chrome.tabs.update(tab.id, { url, active: true });
+    else {
+      tab = await chrome.tabs.create({ url, active: true });
+      await addToGroup(tab.id);
+    }
+    await saveState({ current: tab.id });
+    await chrome.windows.update(tab.windowId, { focused: true }).catch(() => {});
+    await attach(tab.id);
+    await waitLoaded(tab.id);
+    return after(tab.id);
+  }
+  if (a === "tabs") {
+    const s = await state();
+    return { tabs: (await liveTabs()).map((t) => ({ id: t.id, title: t.title, url: t.url, current: t.id === s.current })) };
+  }
+  if (a === "switch") {
+    const id = Number(cmd.tab);
+    const tab = (await liveTabs()).find((t) => t.id === id);
+    if (!tab) throw new Error(`tab ${cmd.tab} is not one of gu's tabs — see action "tabs"`);
+    await chrome.tabs.update(id, { active: true });
+    await saveState({ current: id });
+    return after(id);
+  }
+  const tab = await currentTab();
+  const id = tab.id;
+  if (a === "close") {
+    await chrome.tabs.remove(id);
+    return { closed: id };
+  }
+  await attach(id);
+  switch (a) {
+    case "read":
+      return { ...(await evaluate(id, `(${readPage})(${JSON.stringify({ maxText: cmd.max_text || 6000 })})`)), ...(await after(id)) };
+    case "screenshot": {
+      // Make it the visible tab: a background tab is not painted.
+      await chrome.tabs.update(id, { active: true });
+      const m = await cdp(id, "Page.getLayoutMetrics");
+      const vp = m.cssVisualViewport || m.visualViewport || {};
+      const shot = await cdp(id, "Page.captureScreenshot", { format: "jpeg", quality: 80 });
+      return { ...(await after(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(id, cmd);
+      const hit = await hitAt(id, p.x, p.y);
+      if (a === "hover") await cdp(id, "Input.dispatchMouseEvent", { type: "mouseMoved", x: p.x, y: p.y });
+      else await mouse(id, p.x, p.y, a === "right_click" ? "right" : "left", a === "double_click" ? 2 : 1);
+      await settle(id);
+      return after(id, { at: `${Math.round(p.x)},${Math.round(p.y)}`, hit });
+    }
+    case "type": {
+      if (cmd.ref !== undefined && cmd.ref !== null && cmd.ref !== "") {
+        const p = await refPoint(id, cmd.ref);
+        await mouse(id, p.x, p.y);
+        if (cmd.clear) await pressKey(id, "ctrl+a");
+      }
+      await cdp(id, "Input.insertText", { text: String(cmd.text ?? "") });
+      if (cmd.submit) await pressKey(id, "Enter");
+      await settle(id);
+      return after(id);
+    }
+    case "key":
+      for (const k of String(cmd.text || "").split(/\s+/).filter(Boolean)) await pressKey(id, k);
+      await settle(id);
+      return after(id);
+    case "scroll": {
+      const m = await 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 cdp(id, "Input.dispatchMouseEvent", { type: "mouseWheel", x, y, deltaX: dx, deltaY: dy });
+      await sleep(300);
+      return after(id, { scroll: await evaluate(id, "Math.round(scrollY) + ' of ' + Math.max(0, document.documentElement.scrollHeight - innerHeight)") });
+    }
+    case "back":
+      await evaluate(id, "history.back()");
+      await settle(id);
+      return after(id);
+    case "reload":
+      await cdp(id, "Page.reload", { ignoreCache: true });
+      await settle(id);
+      return after(id);
+    case "wait":
+      await sleep(Math.max(0, Math.min(Number(cmd.seconds) || 1, 30)) * 1000);
+      return after(id);
+    case "js": {
+      const value = await evaluate(id, String(cmd.text || ""));
+      return after(id, { value: value === undefined ? "undefined" : JSON.stringify(value)?.slice(0, 8000) });
+    }
+    case "console": {
+      const all = consoleBuf.get(id) || [];
+      consoleBuf.set(id, []);
+      return after(id, { console: all });
+    }
+    default:
+      throw new Error(`unknown action "${cmd.action}"`);
+  }
+}

package/browser-extension/manifest.json

@@ -0,0 +1,35 @@
+{
+  "manifest_version": 3,
+  "name": "gu browser",
+  "version": "1.0.0",
+  "description": "Lets the gu coding agent open, see and operate web pages in its own tabs (tab group \"gu\") with a real mouse and keyboard.",
+  "minimum_chrome_version": "116",
+  "icons": {
+    "16": "icons/icon16.png",
+    "48": "icons/icon48.png",
+    "128": "icons/icon128.png"
+  },
+  "permissions": [
+    "debugger",
+    "tabs",
+    "tabGroups",
+    "alarms",
+    "storage"
+  ],
+  "host_permissions": [
+    "<all_urls>"
+  ],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+  "action": {
+    "default_title": "gu browser",
+    "default_popup": "popup.html",
+    "default_icon": {
+      "16": "icons/icon16.png",
+      "48": "icons/icon48.png",
+      "128": "icons/icon128.png"
+    }
+  }
+}

package/browser-extension/popup.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  body { font: 13px -apple-system, system-ui, sans-serif; margin: 0; padding: 14px 16px; width: 260px; color: #1d1b26; background: #fff; }
+  h1 { font-size: 14px; margin: 0 0 8px; }
+  .dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: #b9b6c4; margin-right: 6px; }
+  .on .dot { background: #2f9e62; }
+  p { margin: 8px 0 0; color: #5d5a6b; line-height: 1.4; }
+  button { margin-top: 10px; font: inherit; padding: 4px 10px; }
+  @media (prefers-color-scheme: dark) { body { background: #1d1b26; color: #eceaf3; } p { color: #a9a6b8; } }
+</style>
+</head>
+<body>
+  <h1>gu browser</h1>
+  <div id="status"><span class="dot"></span><span id="label">checking…</span></div>
+  <p id="help"></p>
+  <button id="retry">Connect now</button>
+  <script src="popup.js"></script>
+</body>
+</html>

package/browser-extension/popup.js

@@ -0,0 +1,22 @@
+// Shows whether the extension is connected to gu's local bridge, and retries on request.
+const label = document.getElementById("label");
+const help = document.getElementById("help");
+
+function show(s) {
+  const on = Boolean(s && s.connected);
+  document.getElementById("status").className = on ? "on" : "";
+  label.textContent = on ? `connected to gu (v${s.version})` : "not connected";
+  help.textContent = on
+    ? "gu's agent can open and use pages in the \"gu\" tab group. Your other tabs are never touched."
+    : "gu connects when its agent needs the browser. In the gu terminal, /browser shows the status.";
+}
+
+function check() {
+  chrome.runtime.sendMessage({ type: "status" }, show);
+}
+
+document.getElementById("retry").onclick = () => {
+  label.textContent = "connecting…";
+  chrome.runtime.sendMessage({ type: "reconnect" }, () => setTimeout(check, 600));
+};
+check();