@tiens.nguyen/gu-cli 1.0.833 → 1.0.834

package/gonext_agent_chat.py

@@ -8052,6 +8052,30 @@ def _run_command_prompt_line(shell, windows=None):
         "RUNNING — stop_server closes it. " + _BG_LINE)
 
 
+# THE BROWSER (task #363, GitHub #144): a real Chrome the agent drives through the gu extension.
+# Offered only where commands may run (the terminal's own folders, never the web app's scratch one)
+# and node can start the bridge. GU_BROWSER=0 turns it off.
+def _browser_on() -> bool:
+    if os.environ.get("GU_BROWSER", "1").strip() == "0":
+        return False
+    if not any(w.get("allowRun") for w in _WS_ROOTS):
+        return False
+    import shutil as _sh
+    return bool(os.environ.get("GU_NODE") or _sh.which("node"))
+
+
+_BROWSER_LINE = (
+    "    UI CHECKS — THE BROWSER: to see, test or operate a web page (does the page render, does "
+    "the button work, does the form submit, what does the user see), use browser(...): a REAL "
+    "Chrome with a real mouse and keyboard. Loop: browser(\"open\", url=…) → browser(\"read\") "
+    "(text + numbered elements) or browser(\"screenshot\") → browser(\"click\", ref=n) / "
+    "browser(\"type\", ref=n, text=…) → read again to check the result; browser(\"console\") shows "
+    "page errors. A local app needs its server running first (run_command background=True). "
+    "Never report a UI as working without looking at it. If browser answers BROWSER NOT "
+    "AVAILABLE, stop and ask the user to install the gu Chrome extension (steps are in the "
+    "answer).\n")
+
+
 # Background shells (task #360). Never `&` (refused) — background=True is the way to say it.
 _BG_LINE = ("A LONG job (build, deploy, big test run) → run_command(…, background=True), then "
             "shell_output(<id>, wait_seconds=…) to wait for it; a command still running at its "
@@ -9155,7 +9179,8 @@ def _shell_state(s: dict, alive=None, now=None) -> dict:
         state = "ended"
     else:
         state = "exited" if code == 0 else "failed"
-    return {"state": state, "code": code, "runtime": max(0.0, ended - started), "ended": ended}
+    return {"state": state, "code": code, "runtime": max(0.0, ended - started), "ended": ended,
+            "by": s.get("killed_by") or ""}
 
 
 def _fmt_runtime(seconds: float) -> str:
@@ -9171,7 +9196,11 @@ def _shell_status_text(st: dict) -> str:
         return "running"
     if st["state"] in ("exited", "failed"):
         return f"exited {st['code']}"
-    return "killed" if st["state"] == "killed" else "ended (exit code unknown)"
+    # WHO STOPPED IT (#362/#143). A bare "killed" read as a crash — "shell got status killed why?"
+    # — when the agent had stopped its own search on purpose. Every stop says who did it.
+    if st["state"] == "killed":
+        return f"killed — stopped by {st['by']}" if st.get("by") else "killed"
+    return "ended (exit code unknown)"
 
 
 def _shell_find(shells: list, key: str):
@@ -9298,7 +9327,7 @@ def _file_tail(path: str, max_chars: int = 4000) -> str:
         return ""
 
 
-def _shell_kill(s: dict) -> None:
+def _shell_kill(s: dict, by: str = "the agent (stop_server)") -> None:
     """Stop a shell's whole process group and mark it killed (unless it already finished)."""
     import time as _t
     if _shell_state(s)["state"] != "running":
@@ -9311,9 +9340,52 @@ def _shell_kill(s: dict) -> None:
     except (OSError, ValueError):
         pass
     s["killed"] = True
+    s["killed_by"] = by
     s["ended"] = _t.time()
 
 
+# A SHELL THAT FINISHES IS NEWS (#362), the way Claude Code tells its model "background command X
+# completed". During a turn the note rides on the next observation (append-only — no cache
+# break); after the turn the terminal starts a short recap turn (gu-repl.mjs, wakeForShells).
+# `announced` stops both from telling twice; `seen` means the agent already read the final state.
+def _shells_in_scope(shells: list, roots=None) -> list:
+    """The shells started inside these folders (default: the registered workspaces) — shells.json
+    is one file for every project, and another project's build is not this turn's news."""
+    paths = [os.path.realpath(r["path"]) for r in (_WS_ROOTS if roots is None else roots)
+             if isinstance(r, dict) and r.get("path")]
+    out = []
+    for s in shells:
+        wd = os.path.realpath(str(s.get("workdir") or ""))
+        if any(wd == p or wd.startswith(p.rstrip(os.sep) + os.sep) for p in paths):
+            out.append(s)
+    return out
+
+
+def _shells_finished_note(shells: list, now=None) -> str:
+    """Notes for shells that finished and were neither read nor announced; marks them announced
+    in `shells` (the caller saves). "" when there is nothing new."""
+    notes = []
+    for s in shells:
+        if s.get("seen") or s.get("announced"):
+            continue
+        st = _shell_state(s, now=now)
+        if st["state"] == "running":
+            continue
+        s["announced"] = True
+        note = (f"[background shell {s.get('id')} finished: {_shell_status_text(st)} after "
+                f"{_fmt_runtime(st['runtime'])} — '{_clip(str(s.get('command')), 120)}'. "
+                f"shell_output('{s.get('id')}') has its output.]")
+        try:
+            with open(s.get("log") or "", encoding="utf-8", errors="replace") as fh:
+                dg = _test_digest(fh.read(), str(s.get("workdir") or ""))
+            if dg:
+                note += "\n" + dg
+        except OSError:
+            pass
+        notes.append(note)
+    return "\n\n".join(notes)
+
+
 def _shells_context_line(shells: list, now=None) -> str:
     """The turn's line about shells: what is still running, and what finished since the model
     last looked — a build that ended between turns is news the model has not seen."""
@@ -10725,7 +10797,7 @@ def run_agent_chat(cfg):
         except Exception as _e:  # noqa: BLE001
             _log(f"server context skip: {_e}")
         try:
-            _ws_servers_line += _shells_context_line(_shells_load())
+            _ws_servers_line += _shells_context_line(_shells_in_scope(_shells_load()))
         except Exception as _e:  # noqa: BLE001
             _log(f"shell context skip: {_e}")
     _ws_tests_line = ""
@@ -10792,7 +10864,8 @@ def run_agent_chat(cfg):
         "and reads do not pile up here and are not re-sent on every later step. Then read only "
         "the exact ranges you will edit. Use grep_repo/read_file_lines directly when you already "
         "know the file or the exact string.\n"
-        + _run_command_prompt_line(bool(_run_shell_bin())) +
+        + _run_command_prompt_line(bool(_run_shell_bin()))
+        + (_BROWSER_LINE if _browser_on() else "") +
         "    DEPLOY: prefer deploy_web(local_dir, host, user, remote_path, domain) over "
         "hand-written scp/ssh/rsync (it rsyncs over your SSH key and finishes nginx when it "
         "can, else writes deploy.sh and returns the exact commands). KEY auth ONLY "
@@ -11871,9 +11944,38 @@ def run_agent_chat(cfg):
             saved += _trim_tool_call_args(_st, 120)
         return saved
 
+    _browser_shot = {"img": None}  # the browser tool's newest screenshot, for this step (#363)
+
     def step_callback(step_log):
         step_num = getattr(step_log, "step_number", "?")
 
+        # A browser screenshot taken in this step goes to the model as an image with the step's
+        # observation (#363). Only the newest two stay in memory: every image is re-sent on every
+        # later step, and an old view of a page that has since changed only misleads.
+        try:
+            if _browser_shot.get("img") is not None:
+                step_log.observations_images = [_browser_shot["img"]]
+                _browser_shot["img"] = None
+                _with = [s for s in (getattr(getattr(_agent_ref.get("a"), "memory", None), "steps", None) or [])
+                         if getattr(s, "observations_images", None) and s is not step_log]
+                for _old in _with[:-1]:
+                    _old.observations_images = None
+        except Exception as e:  # noqa: BLE001
+            _log(f"browser screenshot attach skip: {e}")
+
+        # A background shell that finished during this step is told to the model now (#362).
+        try:
+            _obs_now = getattr(step_log, "observations", None)
+            if isinstance(_obs_now, str):
+                _shs = _shells_load()
+                _fin = _shells_finished_note(_shells_in_scope(_shs))
+                if _fin:
+                    step_log.observations = _obs_now + "\n\n" + _fin
+                    _shells_save(_shs)
+                    _log(f"step {step_num}: told the model a background shell finished")
+        except Exception as e:  # noqa: BLE001
+            _log(f"shell-finished note skip: {e}")
+
         # Task #74: an executor-timeout error means whatever the step's tool call
         # achieved was NEVER reported to the model (a create_pdf may have finished —
         # or may still be finishing — in the background). Flag it so a repeat
@@ -15476,6 +15578,85 @@ def run_agent_chat(cfg):
                 _last_obs["text"] = msg
                 return msg
 
+        @tool
+        def browser(action: str, url: str = "", ref: int = 0, x: int = -1, y: int = -1,
+                    text: str = "", clear: bool = False, submit: bool = False,
+                    direction: str = "", amount: int = 0, seconds: int = 0, tab: int = 0,
+                    new_tab: bool = False) -> str:
+            """Use a REAL Chrome browser (through the gu Chrome extension) like a person does — open a page, see it, click with the mouse, type with the keyboard — to test a UI flow, check a page renders, fill a form or click through an app. Loop: open → read (or screenshot) → click / type → read again to check what happened. Only gu's own tabs are used. If the answer starts BROWSER NOT AVAILABLE, stop and ask the user to install the extension (the answer has the steps).
+
+            Args:
+                action: one of: open (url) · read (page text + visible interactive elements numbered [n] with x,y) · screenshot (an image of the page; pixels = click x,y) · click / double_click / right_click / hover (ref, or x and y) · type (text into the focused field; with ref it clicks that field first) · key (text: "Enter", "Tab", "Escape", "ctrl+a", "shift+Tab"… several separated by spaces) · scroll (direction, amount) · back · reload · wait (seconds) · js (text = a JavaScript expression run in the page; returns its value) · console (the page's console messages since the last call) · tabs · switch (tab) · close
+                url: for open — a full http(s):// or file:// url (localhost:3000 is taken as http://localhost:3000)
+                ref: an element's [n] from the last read, for click/hover/type
+                x: page x coordinate for click/hover (from read's @x,y or the screenshot), when no ref
+                y: page y coordinate, with x
+                text: what to type (type), the key(s) to press (key), or the JavaScript expression (js)
+                clear: type only — replace the field's current value instead of adding to it
+                submit: type only — press Enter after typing
+                direction: scroll only — down (default), up, left or right
+                amount: scroll only — pixels (default most of a screen)
+                seconds: wait only — 1 to 30
+                tab: switch only — a tab id from tabs
+                new_tab: open only — open in a new tab instead of the current gu tab
+            """
+            import gu_browser as _gb
+            a = (action or "").strip().lower().replace(" ", "_").replace("-", "_")
+            try:
+                cmd = {"action": a}
+                if url:
+                    u = url.strip()
+                    if re.match(r"^(localhost|127\.0\.0\.1|0\.0\.0\.0)(:\d+)?(/|$)", u):
+                        u = "http://" + u
+                    elif u.startswith("/") and os.path.exists(u):
+                        u = "file://" + u
+                    cmd["url"] = u
+                if ref:
+                    cmd["ref"] = int(ref)
+                if x is not None and y is not None and int(x) >= 0 and int(y) >= 0:
+                    cmd["x"], cmd["y"] = float(x), float(y)
+                if text:
+                    cmd["text"] = str(text)
+                for k, v in (("clear", clear), ("submit", submit), ("new_tab", new_tab)):
+                    if v:
+                        cmd[k] = True
+                if direction:
+                    cmd["direction"] = direction
+                if amount:
+                    cmd["amount"] = int(amount)
+                if seconds:
+                    cmd["seconds"] = int(seconds)
+                if tab:
+                    cmd["tab"] = int(tab)
+                shot_ok = a == "screenshot" and (
+                    _is_anthropic_url(coding_base_url) or _coder_takes_images(coding_base_url, coding_model_id))
+                if a == "screenshot" and not shot_ok:
+                    cmd["action"] = "read"  # this model is not sent images: it gets the page as text
+                what = cmd.get("url") or (f"[{ref}]" if ref else f"{int(x)},{int(y)}" if "x" in cmd else
+                                          _clip(str(text), 50) if text else "")
+                _emit({"type": "step", "text": f"Browser {a}" + (f" → {what}" if what else "")})
+                ok, res, not_connected = _gb.command(
+                    cmd, log=_log,
+                    on_wait=lambda: _emit({"type": "step", "text": "Waiting for the gu Chrome extension to connect…"}))
+                if not_connected:
+                    _emit({"type": "step", "text": "⚠ The gu Chrome extension is not connected — /browser shows how to install it"})
+                    msg = _gb.install_text(str(res))
+                elif not ok:
+                    msg = f"Error: browser {a} failed: {res}"
+                elif a == "screenshot" and shot_ok:
+                    im, note = _gb.decode_screenshot(res, _IMAGE_MAX_EDGE)
+                    _browser_shot["img"] = im
+                    msg = _gb.format_result("screenshot", res) + "\n" + note + " The image is attached to this observation."
+                elif a == "screenshot":
+                    msg = ("(This coding model is not sent images, so here is the page as text.)\n"
+                           + _gb.format_result("read", res))
+                else:
+                    msg = _gb.format_result(a, res)
+            except Exception as ex:  # noqa: BLE001
+                msg = f"Error: browser {a} failed: {type(ex).__name__}: {ex}"
+            _last_obs["text"] = msg
+            return msg
+
         agent_tools = [http_request, web_search, fetch_url, calculate,
                        get_current_datetime, create_pdf, create_download]
         # Only register the PDF reader / email / RAG tools when available — the model
@@ -15496,6 +15677,8 @@ def run_agent_chat(cfg):
             agent_tools += [symbol_context, grep_repo, read_file_lines, edit_lines, edit_file,
                             create_file, create_folder, run_command, stop_server,
                             shell_output, deploy_web]
+            if _browser_on():
+                agent_tools.append(browser)
             # Workspace RAG (task #133): semantic search over the PROJECT itself, not just a
             # ZIP-at-URL. Needs both a workspace to index and a working embedder, so it's
             # registered only when RAG is actually available — the model never sees a tool it

package/gu-cli.mjs

@@ -74,6 +74,9 @@ function skillsAndMcpForJob(cwd) {
 }
 
 const WORKER_DIR = dirname(fileURLToPath(import.meta.url));
+// The agent's browser tool starts browser-bridge.mjs with THIS node (#363): a launchd/systemd worker
+// often has no node on PATH.
+process.env.GU_NODE ||= process.execPath;
 
 // Running worker version, read from the package's own package.json (single source of
 // truth) so the startup banner shows exactly which build a box is running (task #105).

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 { browserReport, bridgeStatus, extensionDir, helpInstall, installExtensionFiles } 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", 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,23 @@ 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() {
+  let folder = extensionDir();
+  try {
+    folder = installExtensionFiles();
+  } catch (e) {
+    console.log(GUTTER + yellow(`could not copy the extension to ${folder}: ${e.message}`));
+  }
+  const st = await bridgeStatus().catch(() => ({ running: false, connected: false }));
+  const lines = browserReport(st, folder);
+  console.log("");
+  for (const [i, l] of lines.entries()) console.log(GUTTER + (i === 0 ? (st.connected ? accent(l) : l) : dim(l)));
+  if (!st.connected && st.running && helpInstall(folder)) console.log(GUTTER + dim("(Opened chrome://extensions and copied the folder to your clipboard.)"));
+  console.log("");
+  paintBar();
+}
+
 async function showShells() {
   if (listPickerActive || approvalActive) return;
   const width = Math.max(20, process.stdout.columns || 80);
@@ -14007,6 +14053,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 +14082,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 +14111,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 +14207,10 @@ async function main() {
       await showShells();
       continue;
     }
+    if (line === "/browser") {
+      await showBrowser();
+      continue;
+    }
     if (line === "/model") {
       await chooseModel();
       continue;

package/gu_browser.py

@@ -0,0 +1,263 @@
+"""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", "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
+
+
+def install_text(reason="not connected"):
+    """What the model is told when the extension is not there: stop and ask the user."""
+    folder = install_extension_files()
+    return (
+        f"BROWSER NOT AVAILABLE ({reason}): the gu Chrome extension is not installed, or Chrome is "
+        "not running. Do NOT try to work around it with curl or a headless script for a UI check — "
+        "STOP and ask the user to install it, then continue when they say it is done. Tell them:\n"
+        "  1. Open Chrome and go to chrome://extensions\n"
+        "  2. Turn on Developer mode (top right)\n"
+        f"  3. Click \"Load unpacked\" and choose the folder {folder}\n"
+        "  4. (Or type /browser in the gu terminal for these steps and the connection status.)\n"
+        "gu only uses its own tabs (a tab group named \"gu\"); the user's other tabs are never touched.")
+
+
+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):
+    """→ (state, None) when the extension is connected, else (None, reason)."""
+    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())
+    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 None, "extension not connected"
+    if not seen:
+        try:
+            with open(seen_path(), "w") as f:
+                f.write(str(s.get("version") or ""))
+        except OSError:
+            pass
+    return st, None
+
+
+def command(cmd, log=None, on_wait=None):
+    """Send one command. → (ok, result_or_error, not_connected)."""
+    st, why = connect(log=log, on_wait=on_wait)
+    if not st:
+        return False, why, True
+    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 not r.get("ok"):
+        return False, str(r.get("error") or "failed"), False
+    return True, r.get("result") or {}, 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)