@tiens.nguyen/gu-cli 1.0.833 → 1.0.835

package/gu-repl.mjs

@@ -139,7 +139,8 @@ import {
 import { completedFlush, splitLiveStream } from "./completed-flush.mjs";
 import { isScaffoldStep, isGroupableStep, stepGroupRows, relativizePaths } from "./step-group.mjs";
 import { clearLogsNoticeText } from "./clear-logs.mjs";
-import { commandLogFile, killShell, logTail, readShells, renderShellDetails, shellPickerLabel, shellState, shellsNotice } from "./shell-details.mjs";
+import { allowIn, allowedIn, bridgeCommand, browserReport, bridgeStatus, extensionDir, findDevInstalls, helpInstall, installExtensionFiles, installSteps, localLeftovers, openExtensionsPage, removeLocalFiles, STORE_URL, stopBridge } from "./browser-command.mjs";
+import { commandLogFile, killShell, logTail, markAnnounced, readShells, recapQuestion, shellsToRecap, statusText as shellStatusText, renderShellDetails, shellPickerLabel, shellState, shellsNotice } from "./shell-details.mjs";
 import { discoverSkills, matchSkillCommand } from "./skills.mjs";
 import { appendNew, archivePathFor, archivedWorkspaceKey, markReset, seedArchive } from "./conversation-archive.mjs";
 import { addAllowRule, listServers as listMcpServers } from "./mcp-config.mjs";
@@ -953,6 +954,7 @@ const COMMANDS = [
   { name: "/open-presets", usage: "/open-presets [name]", desc: "your whole setup now, keys included, read-only in your editor — to copy to another computer; with a name, edit that preset" },
   { name: "/use-presets", usage: "/use-presets [name]", desc: "pick a saved preset and apply it — shows what changes, backs up your setup, asks first" },
   { name: "/doctor", desc: "check every configured model ANSWERS — especially the embedder, which a turn only reaches after several steps" },
+  { name: "/browser", usage: "/browser [allow|forget|install|cleanup]", desc: "the gu Chrome extension the agent uses to open and click web pages (UI tests) — is it connected, and how to install it" },
   { name: "/shells", desc: "long commands the agent left running in the background — status, runtime, command, output; stop one" },
   { name: "/tokens", desc: "break down the last prompt sent to the coding model — how much of it was RAG" },
   { name: "/clear-logs", desc: "show what gu's logs, RAG indexes and old API versions take on disk, then ask what to clear — the logs first" },
@@ -9503,6 +9505,33 @@ function refreshShells() {
   shellEntries = readShells().map((rec) => ({ rec, st: shellState(rec) }));
   const after = shellsNotice(shellEntries, { viewed: shellsViewed, since: SHELLS_SINCE })?.text ?? "";
   if (after !== before) paintBar();
+  wakeForShells();
+}
+
+/**
+ * WHEN A BACKGROUND SHELL FINISHES, THE AGENT HEARS ABOUT IT (#362) — Claude Code tells its model
+ * "background command completed" and it recaps or carries on. A shell that ends DURING a turn is
+ * told on the next step (the agent's step_callback); one that ends after the turn starts a short
+ * recap turn here — only at the empty main prompt (never into a question you are answering or a
+ * line you are typing), only for this folder's shells, and never for one you stopped yourself.
+ * GU_SHELL_RECAP=0 turns it off.
+ */
+let mainPromptWaiting = false;
+const SHELL_DONE_PREFIX = "\u0000shell-done:";
+function wakeForShells() {
+  if (process.env.GU_SHELL_RECAP === "0") return;
+  if (!mainPromptWaiting || following || listPickerActive || approvalActive || (rl?.line ?? "") !== "") return;
+  const due = shellsToRecap(shellEntries, { cwd: process.cwd(), since: SHELLS_SINCE });
+  if (!due.length) return;
+  const ids = due.map((r) => String(r.id));
+  try {
+    if (!markAnnounced(ids)) return; // another terminal got there first
+  } catch {
+    return;
+  }
+  for (const id of ids) shellsViewed.add(id);
+  mainPromptWaiting = false;
+  submitSyntheticLine(SHELL_DONE_PREFIX + ids.join(","));
 }
 
 /** The Shell details block for one shell, printed into the transcript. */
@@ -9534,6 +9563,89 @@ function printShellDetails(rec) {
  * details, then refresh / stop it / close. During a turn it only prints the details — a picker
  * would fight the turn for the keyboard, as showOtherAgents explains.
  */
+// /browser (#363): the extension's connection, else how to install it.
+async function showBrowser() {
+  const st = await bridgeStatus().catch(() => ({ running: false, connected: false }));
+  const lines = browserReport(st, { allowed: allowedIn(resolve(process.cwd())) });
+  console.log("");
+  for (const [i, l] of lines.entries()) console.log(GUTTER + (i === 0 && st.connected ? accent(l) : l.startsWith("⚠") ? yellow(l) : dim(l)));
+  console.log("");
+  paintBar();
+}
+
+// /browser install (#150): the extension, for the agent to use YOUR Chrome. Optional — gu's own
+// window needs nothing. The store page once published; until then the developer way.
+async function browserInstall() {
+  let folder = extensionDir();
+  if (!STORE_URL) {
+    try {
+      folder = installExtensionFiles();
+    } catch (e) {
+      console.log(GUTTER + yellow(`could not copy the extension to ${folder}: ${e.message}`));
+    }
+  }
+  await bridgeStatus().catch(() => null); // running, so a fresh install has something to connect to
+  console.log("");
+  for (const l of installSteps(folder)) console.log(GUTTER + dim(l));
+  if (STORE_URL ? openExtensionsPage() : helpInstall(folder)) console.log(GUTTER + dim(STORE_URL ? "(Opened Chrome.)" : "(Opened chrome://extensions and copied the folder to your clipboard.)"));
+  console.log("");
+  paintBar();
+}
+
+// /browser cleanup (#145, #147): remove the developer (unpacked) install so the Chrome Web Store
+// one can take its place. Chrome lets no other program uninstall an extension, so: the connected
+// developer copy removes itself (chrome.management.uninstallSelf), other profiles get a Remove
+// click from you, and then gu's own files go.
+async function browserCleanup() {
+  if (listPickerActive || approvalActive) return;
+  const out = (l = "") => console.log(l ? GUTTER + l : "");
+  const st = await bridgeStatus({ start: false, waitMs: 0 }).catch(() => ({ connected: false }));
+  const devConnected = st.connected && st.installType === "development";
+  const installs = findDevInstalls();
+  const files = localLeftovers();
+  out();
+  if (!installs.length && !devConnected && !files.length) {
+    out(accent("✓ Nothing of the gu extension's developer install is left."));
+    out();
+    paintBar();
+    return;
+  }
+  out("The gu extension's developer install — what this removes:");
+  for (const f of installs) out(dim(`  • ${f.browser} — ${f.profile}: gu browser, unpacked (${f.id})`));
+  if (devConnected && !installs.some((f) => f.id === st.id)) out(dim(`  • the connected developer copy (${st.id})`));
+  for (const f of files) out(dim(`  • ${f.replace(homedir(), "~")}`));
+  if (st.connected && st.installType === "normal") out(dim("  (The Chrome Web Store copy is connected — it stays.)"));
+  out();
+  const go = await pickFromList(["Clean up", "Cancel"], 0);
+  if (go !== 0) {
+    out(dim("(cancelled)"));
+    out();
+    paintBar();
+    return;
+  }
+  if (devConnected) {
+    const r = await bridgeCommand({ action: "uninstall_self" });
+    out(r.ok ? accent(`✓ Removed from Chrome: the connected developer copy (${st.id}).`) : yellow(`could not remove the connected copy: ${r.error}`));
+    await new Promise((res) => setTimeout(res, 1500)); // Chrome writes its profile a moment later
+  }
+  const left = findDevInstalls().filter((f) => !(devConnected && f.id === st.id));
+  if (left.length) {
+    out("Chrome does not let gu remove an extension in another profile. In each of these,");
+    out("open chrome://extensions, find \"gu browser\" and click Remove:");
+    for (const f of left) out(dim(`  • ${f.browser} — ${f.profile}`));
+    if (openExtensionsPage()) out(dim("(Opened chrome://extensions.)"));
+    await pickFromList(["Done — I removed it", "Skip — leave it in that browser"], 0);
+  }
+  stopBridge();
+  await new Promise((res) => setTimeout(res, 300));
+  const gone = removeLocalFiles();
+  if (gone.length) out(accent(`✓ Deleted ${gone.length} of gu's file(s) in ~/.gonext.`));
+  const still = [...findDevInstalls().filter((f) => !(devConnected && f.id === st.id)).map((f) => `${f.browser} — ${f.profile}`), ...localLeftovers()];
+  out(still.length ? yellow(`Still there: ${still.join(", ")}`) : accent("✓ The developer install is gone. Install the Chrome Web Store copy, then /browser."));
+  out();
+  paintBar();
+}
+
 async function showShells() {
   if (listPickerActive || approvalActive) return;
   const width = Math.max(20, process.stdout.columns || 80);
@@ -10494,6 +10606,9 @@ const S3SETUP_PREFIX = "__S3SETUP__::";
 // "Always" writes an allow rule to ~/.gonext/mcp.json — the agent re-reads that file before every
 // call, so it counts from the next call of this same turn, and for every turn after.
 const MCPTOOL_PREFIX = "__MCPTOOL__::";
+// The agent's first use of the browser in a turn (#150): "<folder>\t<what it is about to do>".
+// "Always" puts the folder on ~/.gonext/browser-allow.json, which the agent reads before asking.
+const BROWSER_PREFIX = "__BROWSER__::";
 async function approvalPrompt(command) {
   // Wipe the live "thinking" status block BEFORE any picker draws, and stop the ticker from
   // redrawing it (the tick early-returns while a picker is active) — otherwise the block
@@ -10551,6 +10666,25 @@ async function approvalPrompt(command) {
     );
     return { allow: idx === 0, dontAsk: false };
   }
+  if (command.startsWith(BROWSER_PREFIX)) {
+    const [folder = "", what = ""] = command.slice(BROWSER_PREFIX.length).split("\t");
+    if (!process.stdin.isTTY) return { allow: false, dontAsk: false };
+    process.stdout.write(
+      "\n" + yellow("🌐 Allow gu to use a web browser?") + dim("  (no answer in ~3 min = No)") + "\n" +
+        dim(`  It wants to: ${what || "open a page"}`) + "\n" +
+        dim("  In your Chrome if the gu extension is there, else in gu's own Chrome window.") + "\n"
+    );
+    const idx = await pickFromList(["Yes, this time", "Yes, always in this folder", "No"], 0, { timeoutMs: 170000, timeoutIndex: 2 });
+    if (idx === 1) {
+      try {
+        allowIn(folder || resolve(process.cwd()), true);
+        process.stdout.write(dim("  (won't ask again here — /browser forget undoes it)\n"));
+      } catch (e) {
+        process.stdout.write(yellow(`  could not save that (${e?.message || e}) — allowed this once\n`));
+      }
+    }
+    return { allow: idx === 0 || idx === 1, dontAsk: false };
+  }
   if (command.startsWith(MCPTOOL_PREFIX)) {
     const [server = "", tool = "", preview = ""] = command.slice(MCPTOOL_PREFIX.length).split("\t");
     if (!process.stdin.isTTY) return { allow: false, dontAsk: false };
@@ -14007,6 +14141,7 @@ async function main() {
     // the turn ends; a queued line carries no Enter keypress, so its re-prompt overwrites
     // in place (\r + refresh) rather than stacking ">> >> >> " on one row.
     let lineRaw;
+    mainPromptWaiting = true; // a finished background shell may start a recap turn now (#362)
     for (;;) {
       lineRaw = await nextLine();
       const echoed = enterEchoed;
@@ -14035,8 +14170,21 @@ async function main() {
       }
     }
     enterEchoed = false;
+    mainPromptWaiting = false;
     footerActive = false; // a line arrived from the queue (no Enter keypress) → disarm
     if (lineRaw === null) break; // stdin closed
+    // A RECAP TURN FOR A FINISHED BACKGROUND SHELL (#362). Nobody typed it, so it is not echoed as
+    // a question under ">>" — one dim line says what started it, then the turn runs as usual.
+    let shellRecap = false;
+    if (lineRaw.startsWith(SHELL_DONE_PREFIX)) {
+      const ids = lineRaw.slice(SHELL_DONE_PREFIX.length).split(",");
+      const entries = readShells().map((rec) => ({ rec, st: shellState(rec) })).filter((e) => ids.includes(String(e.rec.id)));
+      if (!entries.length) continue;
+      shellRecap = true;
+      alignOutputToLineStart();
+      console.log("\n" + GUTTER + dim(`⏺ background ${entries.length === 1 ? "shell" : "shells"} finished — ${entries.map((e) => `${e.rec.id} ${shellStatusText(e.st)}`).join(", ")} · gu asks the agent to recap`));
+      lineRaw = recapQuestion(entries);
+    }
     const line = lineRaw.trim();
     // #302: what was typed for THIS line (before expansion), and whether it was sent from a
     // stopped turn's restored question.
@@ -14051,7 +14199,7 @@ async function main() {
     // carries a NUL and a raw jobId, and echoing it as a question would put both in the
     // scrollback under a ">>" that claims the user wrote them. Its branch prints its own
     // "⇄ following: …" line, which is the readable version of the same event.
-    if (barPinned() && line && !line.startsWith(ATTACH_PREFIX)) {
+    if (barPinned() && line && !line.startsWith(ATTACH_PREFIX) && !shellRecap) {
       inputVisible = false; // the zone goes back to an empty prompt for the turn
       // START THIS LINE AT COLUMN 0, don't assume it is already there.
       //
@@ -14147,6 +14295,26 @@ async function main() {
       await showShells();
       continue;
     }
+    if (line === "/browser") {
+      await showBrowser();
+      continue;
+    }
+    if (line === "/browser cleanup") {
+      await browserCleanup();
+      continue;
+    }
+    if (line === "/browser install") {
+      await browserInstall();
+      continue;
+    }
+    if (line === "/browser allow" || line === "/browser forget") {
+      allowIn(cwd, line === "/browser allow");
+      console.log("\n" + GUTTER + (line === "/browser allow"
+        ? accent("✓ The agent may use the browser in this folder without asking.") + dim(" (/browser forget undoes it)")
+        : accent("✓ The agent asks again before it uses the browser in this folder.")) + "\n");
+      paintBar();
+      continue;
+    }
     if (line === "/model") {
       await chooseModel();
       continue;

package/gu_browser.py

@@ -0,0 +1,335 @@
+"""The agent's browser tool, Python side (task #363, GitHub #144).
+
+The agent runs in a new process every turn, so it never holds the Chrome extension itself: it talks
+to browser-bridge.mjs (a small local Node process that does) over HTTP, starting it when needed.
+This module finds or starts the bridge, sends one command, and turns the answer into the text the
+model reads. No model or smolagents import here — it is tested on its own.
+"""
+
+import base64
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+EXT_SRC = os.path.join(HERE, "browser-extension")
+EXT_FILES = ("manifest.json", "background.js", "actions.js", "popup.html", "popup.js",
+             "icons/icon16.png", "icons/icon48.png", "icons/icon128.png")
+BRIDGE = os.path.join(HERE, "browser-bridge.mjs")
+
+
+def data_dir():
+    return os.path.join(os.path.expanduser("~"), ".gonext")
+
+
+def state_path():
+    return os.environ.get("GU_BROWSER_STATE") or os.path.join(data_dir(), "browser-bridge.json")
+
+
+def seen_path():
+    # Written the first time an extension answers: from then on a missing connection means "Chrome
+    # is asleep or closed", worth a longer wait, not "never installed".
+    return os.path.join(os.path.dirname(state_path()), "browser-extension-seen")
+
+
+def extension_dir():
+    """The folder the user loads into Chrome. A fixed place under ~/.gonext, not the npm package:
+    an update moves the package, and Chrome would lose an unpacked extension loaded from there."""
+    return os.environ.get("GU_BROWSER_EXT_DIR") or os.path.join(data_dir(), "browser-extension")
+
+
+def install_extension_files():
+    """Copy the extension to extension_dir() when it is missing or older. Returns the folder."""
+    dst = extension_dir()
+    try:
+        with open(os.path.join(EXT_SRC, "manifest.json"), encoding="utf-8") as f:
+            want = f.read()
+        try:
+            with open(os.path.join(dst, "manifest.json"), encoding="utf-8") as f:
+                have = f.read()
+        except OSError:
+            have = ""
+        def same(n):
+            try:
+                with open(os.path.join(dst, n), "rb") as a, open(os.path.join(EXT_SRC, n), "rb") as b:
+                    return a.read() == b.read()
+            except OSError:
+                return False
+        if have != want or not all(same(n) for n in EXT_FILES):
+            os.makedirs(os.path.join(dst, "icons"), exist_ok=True)
+            for n in EXT_FILES:
+                shutil.copyfile(os.path.join(EXT_SRC, n), os.path.join(dst, n))
+    except OSError:
+        pass
+    return dst
+
+
+# The Chrome Web Store page of the gu extension, once it is published (#149/#150). Until then the
+# extension is the developer path only — and nobody needs it: gu's own Chrome window works without.
+STORE_URL = os.environ.get("GU_BROWSER_STORE_URL", "")
+
+
+def allow_path():
+    return os.path.join(os.path.dirname(state_path()), "browser-allow.json")
+
+
+def _real(folder):
+    try:
+        return os.path.realpath(folder)
+    except OSError:
+        return folder
+
+
+def allowed_in(folder):
+    """Has the user said "always allow the browser" for this folder (#150)?"""
+    try:
+        with open(allow_path(), encoding="utf-8") as f:
+            return _real(folder) in (json.load(f).get("folders") or [])
+    except (OSError, ValueError):
+        return False
+
+
+def allow_in(folder, allow=True):
+    """Add (or remove) a folder on the "always allow" list. The terminal writes it on "Always"."""
+    try:
+        with open(allow_path(), encoding="utf-8") as f:
+            folders = json.load(f).get("folders") or []
+    except (OSError, ValueError):
+        folders = []
+    f_ = _real(folder)
+    folders = [x for x in folders if x != f_] + ([f_] if allow else [])
+    os.makedirs(os.path.dirname(allow_path()), exist_ok=True)
+    with open(allow_path(), "w", encoding="utf-8") as f:
+        json.dump({"folders": folders}, f, indent=2)
+
+
+def last_seen():
+    """{version, installType} of the extension that last connected, or {} (#146). An older marker
+    holds only the version."""
+    try:
+        with open(seen_path(), encoding="utf-8") as f:
+            raw = f.read().strip()
+        try:
+            return json.loads(raw) if raw.startswith("{") else {"version": raw}
+        except ValueError:
+            return {"version": raw}
+    except OSError:
+        return {}
+
+
+def install_text(reason="not connected"):
+    """What the model is told when the extension is not there: stop and ask the user."""
+    if last_seen().get("installType") == "normal":
+        # The Chrome Web Store copy is installed: never point at the developer folder again (#145).
+        return (f"BROWSER NOT AVAILABLE ({reason}): the gu Chrome extension (Chrome Web Store) is "
+                "installed but not connected — Chrome is probably closed. STOP and ask the user to "
+                "open Chrome (the extension reconnects within 30 seconds, or its icon → Connect now), "
+                "then continue. /browser in the gu terminal shows the status.")
+    # gu's own Chrome window needs no extension (#150), so this is reached only when there is no
+    # Chrome to start at all.
+    return (
+        f"BROWSER NOT AVAILABLE ({reason}). gu opens its own Chrome window when the gu extension is "
+        "not there, and it found no Chrome, Chromium, Edge or Brave on this computer. Do NOT work "
+        "around it with curl or a headless script for a UI check — STOP and tell the user: install "
+        "Google Chrome (or set GU_BROWSER_CHROME to a Chromium-based browser), then ask again."
+        + (f" To use their own Chrome instead, they can add the gu extension: {STORE_URL}" if STORE_URL else ""))
+
+
+def _node():
+    return os.environ.get("GU_NODE") or shutil.which("node") or "node"
+
+
+def _read_state():
+    try:
+        with open(state_path(), encoding="utf-8") as f:
+            st = json.load(f)
+        return st if st.get("port") and st.get("token") else None
+    except (OSError, ValueError):
+        return None
+
+
+def _http(st, method, path, body=None, timeout=10):
+    req = urllib.request.Request(
+        f"http://127.0.0.1:{st['port']}{path}", method=method,
+        data=json.dumps(body).encode() if body is not None else None,
+        headers={"authorization": f"Bearer {st['token']}", "content-type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return json.loads(e.read() or b"{}") | {"_status": e.code}
+        except ValueError:
+            return {"_status": e.code, "error": str(e)}
+
+
+def _start_bridge(log=None):
+    """Start browser-bridge.mjs detached (it outlives this turn) and wait for its state file."""
+    os.makedirs(data_dir(), exist_ok=True)
+    logf = open(os.path.join(data_dir(), "browser-bridge.log"), "ab")
+    kw = {"start_new_session": True} if os.name != "nt" else {
+        "creationflags": getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)}
+    subprocess.Popen([_node(), BRIDGE], stdin=subprocess.DEVNULL, stdout=logf, stderr=logf,
+                     env=dict(os.environ), **kw)
+    logf.close()
+    if log:
+        log("browser: started the bridge")
+    end = time.time() + 6
+    while time.time() < end:
+        st = _read_state()
+        if st:
+            try:
+                _http(st, "GET", "/status", timeout=2)
+                return st
+            except OSError:
+                pass
+        time.sleep(0.15)
+    return None
+
+
+def connect(wait=True, log=None, on_wait=None, own=False):
+    """→ (state, None) when the extension is connected, else (None, reason).
+    own=True (#150): gu's own Chrome window may stand in, so a missing extension is no failure —
+    → (state, None) either way, and the wait for a sleeping extension is shorter."""
+    st = _read_state()
+    started = False
+    try:
+        if not st:
+            raise OSError("no bridge")
+        _http(st, "GET", "/status", timeout=3)
+    except OSError:
+        st = _start_bridge(log)
+        started = True
+        if not st:
+            return None, "the gu browser bridge did not start (is node installed?)"
+    # A Chrome extension's worker sleeps; its alarm wakes it to reconnect within 30 s. Wait that
+    # long only when an extension has connected before — otherwise it is most likely not installed.
+    seen = os.path.exists(seen_path())
+    if own:
+        wait_ms = (8000 if seen else 0) if wait else 0  # then gu's own window
+    else:
+        wait_ms = (35000 if (seen and started) else 8000 if seen else 4000) if wait else 0
+    if wait_ms >= 8000 and on_wait:
+        on_wait()
+    try:
+        s = _http(st, "GET", f"/status?wait_ms={wait_ms}", timeout=wait_ms / 1000 + 5)
+    except OSError as e:
+        return None, f"the gu browser bridge is not answering ({e})"
+    if not s.get("connected"):
+        return (st, None) if own else (None, "extension not connected")
+    mark = {"version": s.get("version"), "installType": s.get("installType")}
+    if last_seen() != mark:
+        try:
+            with open(seen_path(), "w") as f:
+                json.dump(mark, f)
+        except OSError:
+            pass
+    return st, None
+
+
+def command(cmd, log=None, on_wait=None, own=False):
+    """Send one command. → (ok, result_or_error, not_connected).
+    own=True: without the extension, the bridge uses gu's own Chrome window (#150). The result
+    then carries "_backend": "chrome"."""
+    st, why = connect(log=log, on_wait=on_wait, own=own)
+    if not st:
+        return False, why, True
+    if own:
+        cmd = dict(cmd, backend="auto")
+    timeout_s = 75 if cmd.get("action") in ("open", "wait", "js") else 40
+    try:
+        r = _http(st, "POST", "/cmd", body=dict(cmd, timeout_ms=(timeout_s - 5) * 1000), timeout=timeout_s)
+    except OSError as e:
+        return False, f"the browser bridge did not answer ({e})", False
+    if r.get("_status") == 503:
+        return False, "extension not connected", True
+    if r.get("noChrome"):
+        return False, str(r.get("error")), True  # nothing to drive: the install answer applies
+    if not r.get("ok"):
+        return False, str(r.get("error") or "failed"), False
+    res = r.get("result") or {}
+    if isinstance(res, dict) and r.get("backend"):
+        res["_backend"] = r["backend"]
+    return True, res, False
+
+
+# ── what the model reads ────────────────────────────────────────────────────────────────────
+def _head(res):
+    out = f"Page: {res.get('title') or '(no title)'} — {res.get('url') or ''}"
+    for d in res.get("dialogs") or []:
+        out += f"\nA dialog opened and gu accepted it: {d}"
+    errs = res.get("errors") or []
+    if errs:
+        out += "\nNEW console errors:\n" + "\n".join("  " + e for e in errs)
+    return out
+
+
+def format_read(res):
+    els = res.get("elements") or []
+    lines = [_head(res), f"Viewport {res.get('viewport')}, scrolled {res.get('scroll')} px."]
+    if els:
+        lines.append("Interactive elements in view — click/type by [number] (good until the next read):")
+        lines += ["  " + e for e in els]
+    else:
+        lines.append("No interactive elements in view.")
+    if res.get("offscreen"):
+        lines.append(f"(+{res['offscreen']} more off screen — scroll to reach them)")
+    text = (res.get("text") or "").strip()
+    lines.append("Page text:\n" + (text or "(empty)"))
+    return "\n".join(lines)
+
+
+def format_result(action, res):
+    a = action
+    if a == "tabs":
+        tabs = res.get("tabs") or []
+        if not tabs:
+            return "gu has no tab open."
+        return "gu's tabs:\n" + "\n".join(
+            f"  {t['id']}{' (current)' if t.get('current') else ''}: {t.get('title') or ''} — {t.get('url')}" for t in tabs)
+    if a == "read":
+        return format_read(res)
+    if a == "close":
+        return f"Closed tab {res.get('closed')}."
+    out = _head(res)
+    if a in ("click", "double_click", "right_click", "hover"):
+        out = f"{a.replace('_', ' ').capitalize()} at {res.get('at')} on {res.get('hit')}.\n" + out
+    if a == "scroll":
+        out += f"\nScrolled to {res.get('scroll')} px."
+    if a == "js":
+        out += f"\nResult: {res.get('value')}"
+    if a == "console":
+        msgs = res.get("console") or []
+        out += ("\nConsole since the last read:\n" + "\n".join(f"  [{m.get('level')}] {m.get('text')}" for m in msgs)
+                if msgs else "\nConsole: nothing new.")
+    if a in ("open", "click", "double_click", "type", "key", "back", "reload"):
+        out += "\n(read or screenshot to see the page now)"
+    return out
+
+
+def decode_screenshot(res, max_edge=1568):
+    """The screenshot as a PIL image at the page's CSS size, so its pixels ARE click coordinates.
+    → (image, note). Chrome captures in device pixels (2× on a Retina screen)."""
+    from io import BytesIO
+    from PIL import Image
+    im = Image.open(BytesIO(base64.b64decode(res.get("image") or ""))).convert("RGB")
+    w, h = int(res.get("width") or im.width), int(res.get("height") or im.height)
+    if (w, h) != im.size and w > 0 and h > 0:
+        im = im.resize((w, h), Image.LANCZOS)
+    note = f"Screenshot {im.width}×{im.height} — its pixels are the page's x,y for click."
+    if max(im.size) > max_edge:
+        k = max_edge / max(im.size)
+        im = im.resize((max(1, int(im.width * k)), max(1, int(im.height * k))), Image.LANCZOS)
+        note = (f"Screenshot shrunk to {im.width}×{im.height}; the page is {w}×{h} — multiply a point "
+                f"in it by {1 / k:.3f} for click x,y.")
+    return im, note
+
+
+if __name__ == "__main__":  # tiny manual check: python3 gu_browser.py open https://example.com
+    ok, res, _ = command({"action": sys.argv[1], "url": sys.argv[2] if len(sys.argv) > 2 else ""})
+    print(format_result(sys.argv[1], res) if ok else res)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.833",
+  "version": "1.0.835",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -125,6 +125,15 @@
     "skills.mjs",
     "skill-source.mjs",
     "shell-details.mjs",
+    "proc-identity.mjs",
+    "browser-command.mjs",
+    "browser-bridge.mjs",
+    "browser-extension/manifest.json",
+    "browser-extension/background.js",
+    "browser-extension/actions.js",
+    "browser-extension/popup.html",
+    "browser-extension/popup.js",
+    "browser-extension/icons/",
     "step-group.mjs",
     "mcp-config.mjs",
     "mcp-command.mjs",
@@ -136,6 +145,7 @@
     "gu_mcp.py",
     "gu_skills.py",
     "gu_test_digest.py",
+    "gu_browser.py",
     "gu_hooks.py",
     "prompt_scaffold_check.py",
     "gonext_transcribe.py",

package/proc-identity.mjs

@@ -0,0 +1,53 @@
+// IS THIS PID STILL THE PROCESS WE MEANT? (task #373, GitHub #154)
+//
+// gu keeps process ids in files — shells.json, the local API's pid file, the browser bridge's state —
+// and those files outlive their processes. After a reboot or a crash the id is free, and the OS
+// hands it to the next program (VS Code, Chrome); a SIGTERM to the saved id then lands on that.
+// A process's START TIME is what tells two holders of one id apart, so it is what gu records and
+// checks before it signals anything. POSIX only: `ps -o lstart=` reads the same on macOS and procps.
+
+import { spawnSync } from "node:child_process";
+
+const MONTHS = "JanFebMarAprMayJunJulAugSepOctNovDec";
+
+/** When `pid` started (epoch s); null = no such process; NaN = cannot tell (no ps, Windows). */
+export function procStart(pid, { platform = process.platform } = {}) {
+  if (platform === "win32" || !(Number(pid) > 0)) return NaN;
+  const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+    encoding: "utf8",
+    env: { ...process.env, LC_ALL: "C", LANG: "C" },
+    timeout: 5000,
+  });
+  if (r.error) return NaN;
+  const raw = String(r.stdout || "").trim().replace(/\s+/g, " ");
+  if (!raw) return null;
+  // "Wed Oct 14 23:26:17 2026", local time.
+  const m = raw.match(/^\w{3} (\w{3}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/);
+  const mon = m ? MONTHS.indexOf(m[1]) / 3 : -1;
+  if (!m || mon < 0 || !Number.isInteger(mon)) return NaN;
+  return new Date(Number(m[6]), mon, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5])).getTime() / 1000;
+}
+
+/** The command line of `pid` ("" when there is none, or no ps). */
+export function procCommand(pid, { platform = process.platform } = {}) {
+  if (platform === "win32" || !(Number(pid) > 0)) return "";
+  const r = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 5000 });
+  return r.error ? "" : String(r.stdout || "").trim();
+}
+
+/**
+ * Is `pid` the process that was running at `startedAt` (epoch s, as recorded)?
+ *   "same"  — it started then (within `before` s before and `after` s after the record);
+ *   "gone"  — no process has that id;
+ *   "other" — that id belongs to a process started at another time: never signal it;
+ *   "unknown" — nothing to compare (Windows, no ps, nothing recorded).
+ * `before` is the room for a record written a while after its process started (a server that
+ * records itself once it listens); `after` is ps's whole-second rounding.
+ */
+export function sameProcess(pid, startedAt, { before = 5, after = 5, startOf = procStart } = {}) {
+  const t = startOf(pid);
+  if (t === null) return "gone";
+  const rec = Number(startedAt);
+  if (!Number.isFinite(t) || startedAt == null || !Number.isFinite(rec)) return "unknown";
+  return t >= rec - before && t <= rec + after ? "same" : "other";
+}