@tiens.nguyen/gu-cli 1.0.834 → 1.0.836

package/browser-extension/background.js

@@ -5,8 +5,12 @@
 // 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.
+// gu only works in ITS OWN tabs: the ones it opened (kept in a tab group named "gu"), the popups
+// those open, and a tab the user shares from the popup ("Let gu use this tab", #150). The user's
+// other tabs are never read, captured or controlled. What each command does is in actions.js,
+// shared with gu's own Chrome window (browser-chrome.mjs).
+
+import { enableDomains, forgetTab, onCdpEvent, runAction } from "./actions.js";
 
 const DEFAULT_PORT = 4127;
 const VERSION = chrome.runtime.getManifest().version;
@@ -15,9 +19,6 @@ 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() {
@@ -41,24 +42,36 @@ async function connect() {
     connecting = false;
   }
   ws = sock;
-  sock.onopen = () => {
-    sock.send(JSON.stringify({ type: "hello", version: VERSION }));
+  sock.onopen = async () => {
+    sock.send(JSON.stringify({ type: "hello", version: VERSION, installType: await installType() }));
     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 = () => {
+  sock.onclose = (ev) => {
     if (ws !== sock) return; // an older socket the bridge replaced
     ws = null;
     clearInterval(pingTimer);
     setBadge(false);
-    setTimeout(connect, 3000);
+    // 4001: another gu extension (the store copy next to a developer one) has the bridge.
+    // Retry slowly instead of every 3 s; the alarm keeps trying too (#148).
+    setTimeout(connect, ev.code === 4001 ? 30000 : 3000);
   };
   sock.onerror = () => {};
 }
 
+// "development" = loaded unpacked (Developer mode); "normal" = from the Chrome Web Store (#146).
+// getSelf needs no "management" permission.
+async function installType() {
+  try {
+    return (await chrome.management.getSelf()).installType;
+  } catch {
+    return "unknown";
+  }
+}
+
 function setBadge(on) {
   chrome.action.setBadgeText({ text: on ? "on" : "" }).catch(() => {});
   chrome.action.setBadgeBackgroundColor({ color: "#6d5bd0" }).catch(() => {});
@@ -75,6 +88,18 @@ chrome.runtime.onMessage.addListener((msg, _sender, reply) => {
   } else if (msg?.type === "reconnect") {
     connect().then(() => reply({ ok: true }));
     return true;
+  } else if (msg?.type === "tabState") {
+    state().then((s) => reply({ shared: s.tabs.includes(msg.tabId) }));
+    return true;
+  } else if (msg?.type === "share") {
+    // "Let gu use this tab" (#150): the user hands gu a tab of their own.
+    addToGroup(msg.tabId)
+      .then(() => saveState({ current: msg.tabId }))
+      .then(() => reply({ ok: true }), (e) => reply({ ok: false, error: String(e?.message || e) }));
+    return true;
+  } else if (msg?.type === "unshare") {
+    unshare(msg.tabId).then(() => reply({ ok: true }));
+    return true;
   }
   return false;
 });
@@ -134,6 +159,16 @@ async function addToGroup(tabId) {
   await saveState({ tabs, group });
 }
 
+// "Stop sharing": the tab leaves the group, gu lets go of it, and never touches it again.
+async function unshare(tabId) {
+  const s = await state();
+  await saveState({ tabs: s.tabs.filter((t) => t !== tabId), current: s.current === tabId ? null : s.current });
+  await chrome.tabs.ungroup(tabId).catch(() => {});
+  if (attached.has(tabId)) await chrome.debugger.detach({ tabId }).catch(() => {});
+  attached.delete(tabId);
+  forgetTab(tabId);
+}
+
 // 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();
@@ -143,240 +178,37 @@ chrome.tabs.onCreated.addListener(async (tab) => {
   }
 });
 
-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.debugger.onEvent.addListener((src, method, params) => onCdpEvent(src.tabId, method, params, cdp));
 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(() => {});
-  }
+  forgetTab(tabId);
 });
 
-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;
+// The host actions.js runs on: chrome.tabs + chrome.debugger, in the user's own Chrome.
+const host = {
+  cdp,
+  async 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`);
+      }
     }
-    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");
+    attached.add(tabId);
+    await enableDomains(cdp, tabId);
+  },
+  async open(url, newTab) {
     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];
+    let tab = newTab ? 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 });
@@ -384,100 +216,46 @@ async function run(cmd) {
     }
     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") {
+    return tab.id;
+  },
+  async 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"`);
+    return (await liveTabs()).map((t) => ({ id: t.id, title: t.title, url: t.url, current: t.id === s.current }));
+  },
+  async switchTo(tabId) {
+    const id = Number(tabId);
+    if (!(await liveTabs()).some((t) => t.id === id)) return false;
     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}"`);
+    return true;
+  },
+  async current() {
+    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]).id;
+  },
+  async info(tabId) {
+    const t = await chrome.tabs.get(tabId).catch(() => null);
+    return t ? { url: t.url, title: t.title, status: t.status } : null;
+  },
+  async activate(tabId) {
+    await chrome.tabs.update(tabId, { active: true });
+  },
+  async close(tabId) {
+    await chrome.tabs.remove(tabId);
+  },
+};
+
+async function run(cmd) {
+  const a = String(cmd.action || "").toLowerCase();
+  if (a === "status") return { version: VERSION, installType: await installType() };
+  if (a === "uninstall_self") {
+    // /browser cleanup (#147): a developer copy removes itself. Never the store copy — that one
+    // the user removes, or keeps.
+    if ((await installType()) !== "development") throw new Error("this is not a developer (unpacked) install — not removed");
+    setTimeout(() => chrome.management.uninstallSelf({ showConfirmDialog: false }).catch(() => {}), 200);
+    return { uninstalling: chrome.runtime.id };
   }
+  return runAction(cmd, host);
 }

package/browser-extension/manifest.json

@@ -1,11 +1,12 @@
 {
   "manifest_version": 3,
   "name": "gu browser",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",
+    "32": "icons/icon32.png",
     "48": "icons/icon48.png",
     "128": "icons/icon128.png"
   },
@@ -28,6 +29,7 @@
     "default_popup": "popup.html",
     "default_icon": {
       "16": "icons/icon16.png",
+      "32": "icons/icon32.png",
       "48": "icons/icon48.png",
       "128": "icons/icon128.png"
     }

package/browser-extension/popup.html

@@ -16,6 +16,10 @@
   <h1>gu browser</h1>
   <div id="status"><span class="dot"></span><span id="label">checking…</span></div>
   <p id="help"></p>
+  <div id="tab" style="margin-top:12px;display:none">
+    <div id="tabLabel" style="color:inherit"></div>
+    <button id="share">Let gu use this tab</button>
+  </div>
   <button id="retry">Connect now</button>
   <script src="popup.js"></script>
 </body>

package/browser-extension/popup.js

@@ -20,3 +20,26 @@ document.getElementById("retry").onclick = () => {
   chrome.runtime.sendMessage({ type: "reconnect" }, () => setTimeout(check, 600));
 };
 check();
+
+// "Let gu use this tab" (#150): hand gu one of your own tabs — it joins the "gu" group and the
+// agent can use it; "Stop sharing" takes it back. Chrome's own pages cannot be shared.
+const tabBox = document.getElementById("tab");
+const tabLabel = document.getElementById("tabLabel");
+const shareBtn = document.getElementById("share");
+
+async function showTab() {
+  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+  if (!tab || !/^(https?|file):/i.test(tab.url || "")) return;
+  const { shared } = await chrome.runtime.sendMessage({ type: "tabState", tabId: tab.id });
+  tabBox.style.display = "block";
+  tabLabel.textContent = shared ? "gu can use this tab." : "This tab is yours — gu cannot see it.";
+  shareBtn.textContent = shared ? "Stop sharing this tab" : "Let gu use this tab";
+  shareBtn.onclick = async () => {
+    shareBtn.disabled = true;
+    const r = await chrome.runtime.sendMessage({ type: shared ? "unshare" : "share", tabId: tab.id });
+    shareBtn.disabled = false;
+    if (r && r.ok === false) tabLabel.textContent = r.error;
+    else showTab();
+  };
+}
+showTab();

package/client-expert-api.mjs

@@ -20,6 +20,7 @@
 import { createRequire } from "node:module";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { spawnSurviving, pidOnPort } from "./platform-tools.mjs";
+import { procCommand, procStart, sameProcess } from "./proc-identity.mjs";
 import { DEFAULT_API_BASE as HOSTED_API_BASE } from "./device-login.mjs";
 import { spawn } from "node:child_process";
 import { writeFile, mkdir, readFile, access } from "node:fs/promises";
@@ -113,6 +114,46 @@ export function localMongoUri({ env = process.env, home = homedir() } = {}) {
 
 const GONEXT_DIR = join(homedir(), ".gonext");
 export const API_PID_FILE = join(GONEXT_DIR, "local-api.pid");
+
+/**
+ * THE PID FILE CARRIES THE PROCESS'S START TIME (#373, GitHub #154): "<pid>\n<start epoch s>\n".
+ * The file outlives the API (a crash, a reboot), and its id may belong to another program by the
+ * time `gu api stop`, restart, upgrade or reset reads it. The start time, read from ps when the
+ * file is written, is what tells them apart. Older files hold only the pid.
+ */
+export async function writeApiPid(pid, { path = API_PID_FILE } = {}) {
+  if (!pid) return;
+  const t = procStart(pid);
+  await writeFile(path, `${pid}\n${Number.isFinite(t) ? t : ""}\n`).catch(() => {});
+}
+
+/** { pid, started } from the pid file; pid null when there is none. */
+export async function readApiPid({ path = API_PID_FILE } = {}) {
+  const [a, b] = String(await readFile(path, "utf8").catch(() => "")).split(/\s+/);
+  const pid = Number(a);
+  const started = b ? Number(b) : NaN;
+  return { pid: Number.isInteger(pid) && pid > 0 ? pid : null, started: Number.isFinite(started) ? started : null };
+}
+
+/**
+ * The pid to stop — only while it is still the local API. With a start time: the same process
+ * started then. An older file without one: the process must look like the API (node … index.js).
+ * { pid } to signal, or { pid: null, why } — never a guess.
+ */
+export async function apiPidToStop({ path = API_PID_FILE, platform = process.platform, startOf = procStart, commandOf = procCommand } = {}) {
+  const { pid, started } = await readApiPid({ path });
+  if (!pid) return { pid: null, why: "no local API pid on record" };
+  if (platform === "win32") return { pid };
+  if (started != null) {
+    const same = sameProcess(pid, started, { before: 2, after: 2, startOf });
+    if (same === "same") return { pid };
+    if (same === "gone") return { pid: null, why: "not running" };
+    if (same === "other") return { pid: null, why: `pid ${pid} is now another program, not the local API — left alone` };
+  }
+  const cmd = commandOf(pid, { platform });
+  if (!cmd) return { pid: null, why: "not running" };
+  return /\bnode\b.*\bindex\.js\b/.test(cmd) ? { pid } : { pid: null, why: `pid ${pid} is now another program, not the local API — left alone` };
+}
 export const API_LOG_FILE = join(GONEXT_DIR, "local-api.log");
 
 /** The API authenticates a worker by sha256 of the key — same function it uses server-side. */
@@ -528,14 +569,14 @@ export async function startLocalApi({
   // serves — which is the better question anyway: what matters is who is answering, not who
   // we spawned. Recorded after the server is up, by the caller's waitForApi.
   const pid = res.pid ?? null;
-  if (pid) await writeFile(API_PID_FILE, String(pid) + "\n").catch(() => {});
+  await writeApiPid(pid);
   return { pid, how: res.how, port };
 }
 
 /** Record whoever is serving the port, so `api stop` has something to stop. */
 export async function recordApiPid(port = LOCAL_API_PORT) {
   const pid = await pidOnPort(port);
-  if (pid) await writeFile(API_PID_FILE, String(pid) + "\n").catch(() => {});
+  await writeApiPid(pid);
   return pid;
 }