@tiens.nguyen/gu-cli 1.0.832 → 1.0.834

package/gonext_agent_chat.py

@@ -8024,7 +8024,9 @@ def _run_command_prompt_line(shell, windows=None):
             "interactive input() CLI fails with EOFError. A server or GUI app is left RUNNING — "
             "stop_server closes it. " + _BG_LINE)
     return (
-        "    run_command IS A SHELL (bash): pipes, redirects, `;`, `||`, `$( )`, globs and heredocs "
+        "    run_command IS A SHELL (bash), and it KEEPS its folder and exported variables from one "
+        "call to the next in this turn (`cd sub`, then `npm test` runs in sub; an explicit workdir "
+        "wins). Pipes, redirects, `;`, `||`, `$( )`, globs and heredocs "
         "work, so put a whole sequence in ONE call — dependent steps with &&, independent ones with "
         "`;` (e.g. `cd app && npm test 2>&1 | tail -40`); a multi-line command goes in a "
         "triple-quoted string.\n"
@@ -8037,12 +8039,43 @@ def _run_command_prompt_line(shell, windows=None):
         "    GITHUB: use `gh`. Multi-line text goes as a heredoc on stdin — "
         "`gh issue comment 12 --body-file - <<'EOF'` … `EOF` (same for gh issue create / gh pr "
         "create) — never write a body file first, and do not run `gh auth status` first.\n"
+        # #362: how Claude Code checks work — scripts as heredocs, the one function not the app,
+        # cheapest check first, and never a pipe between a test run and the decision it feeds.
+        "    CHECKS: a Python/Node script goes as a heredoc — `python3 - <<'EOF'` … `EOF` (node: "
+        "`node --input-type=module - <<'EOF'`) — never `python3 -c` built from joined strings. To "
+        "check one function, load its module and call it with real input instead of running the "
+        "app. Order: syntax check → the ONE test → the suite once. Test output arrives with a TEST "
+        "SUMMARY of each failure first, so never pipe it into tail/grep (a pipe hides the exit code).\n"
         "    Read and search FILES with read_file_lines / grep_repo, not cat/grep/sed. `sudo`/`su` "
         "are blocked; piping into sh/python and writing or deleting outside the project ask the "
         "user first; an interactive input() CLI fails with EOFError. A server or GUI app is left "
         "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 "
@@ -8156,9 +8189,28 @@ def _test_commands_line(root: str) -> str:
     cmds = _project_test_commands(root) if root else []
     if not cmds:
         return ""
-    return ("  TEST COMMANDS, from this project's own manifests — use these, never guess a runner "
+    line = ("  TEST COMMANDS, from this project's own manifests — use these, never guess a runner "
             "(a missing pytest fails silently behind a pipe): "
             + "; ".join(f"{d} → {c}" for d, c in cmds) + "\n")
+    try:
+        import gu_test_digest as _td
+        forms = _td.one_test_forms(c for _, c in cmds)
+    except Exception:  # noqa: BLE001
+        forms = []
+    if forms:
+        # #362: check a fix with ONE test (seconds), run the suite once at the end.
+        line += ("  ONE TEST while fixing (the suite once at the end): " + " · ".join(forms) + "\n")
+    return line
+
+
+def _test_digest(output: str, cwd: str = "") -> str:
+    """gu_test_digest.digest, or "" if the module is missing — a summary must never fail a command."""
+    try:
+        import gu_test_digest as _td
+        return _td.digest(output or "", cwd or "")
+    except Exception as e:  # noqa: BLE001
+        _log(f"test digest skip: {e}")
+        return ""
 
 
 # bash's words for a line whose quotes do not pair up.
@@ -9051,10 +9103,10 @@ def _ws_cap_servers(max_live: int = 3) -> list:
 # running" link and the Shell details view (shell-details.mjs).
 #
 # THE EXIT CODE OUTLIVES THE AGENT. The agent is one process per turn; a build that ends after the
-# turn has no parent left to wait() on it. So a shell line runs as `"$0" -c "$1"; rc=$?; echo $rc
-# > "$2"; exit $rc` — the command text untouched, its exit code written to `exit_file` AND passed
-# on (without the `exit $rc` every failure read as EXITED 0). The argv-only path (Windows)
-# has no such wrapper and says "exit code unknown" instead of guessing.
+# turn has no parent left to wait() on it. So a shell line runs as `eval "$1"` under an EXIT trap
+# that writes its exit code to `exit_file` AND exits with it (without that every failure read as
+# EXITED 0) — see _run_state_wrapper, which also keeps the folder and exports for the next call.
+# The argv-only path has no such wrapper and says "exit code unknown" instead of guessing.
 _SHELLS_KEEP = 20            # newest records kept, running or not
 _SHELLS_KEEP_DONE_S = 86400  # a finished shell is listed for a day
 
@@ -9127,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:
@@ -9143,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):
@@ -9270,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":
@@ -9283,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."""
@@ -9301,6 +9401,77 @@ def _shells_context_line(shells: list, now=None) -> str:
             + ". Read one with shell_output(<id>); stop one with stop_server(<id>).\n")
 
 
+# THE SHELL KEEPS ITS FOLDER AND EXPORTS BETWEEN CALLS (#362), the way Claude Code's Bash tool does.
+# Every run_command was a fresh bash, so `cd tools/x` or `source .venv/bin/activate` lasted one call
+# and every line started `cd … &&`. Not a long-lived pty (a hung one would wedge the turn): each
+# line runs in the outer shell via `eval`, and an EXIT trap — which also fires on `exit 3` — saves
+# `export -p` and `pwd` to this turn's state file; the next call sources it and starts in that
+# folder. One turn only: the file is removed when the agent exits. An explicit workdir wins.
+_RUN_STATE = {"path": ""}
+# Builtins that change the shell itself. As argv they run nothing (`export` is no program; macOS's
+# /usr/bin/cd exits 0 having changed nothing) — with a shell, a line using one goes to bash.
+_SHELL_STATE_BUILTINS = {"cd", "export", "source", ".", "set", "unset", "alias", "unalias", "pushd",
+                         "popd", "umask", "shopt", "declare", "typeset", "readonly", "trap", "ulimit",
+                         "hash", "eval"}
+_RUN_STATE_SKIP = r"^declare -x (PWD|OLDPWD|SHLVL|_)="
+
+
+def _run_state_path() -> str:
+    import atexit
+    import time as _t
+    if not _RUN_STATE["path"]:
+        d = os.path.join(os.path.expanduser("~"), ".gonext", "run-state")
+        os.makedirs(d, exist_ok=True)
+        # A background shell that ends after its turn rewrites its file; sweep day-old ones.
+        try:
+            for n in os.listdir(d):
+                fp = os.path.join(d, n)
+                if _t.time() - os.path.getmtime(fp) > 86400:
+                    os.remove(fp)
+        except OSError:
+            pass
+        _RUN_STATE["path"] = os.path.join(d, f"{os.getpid()}.sh")
+
+        def _clean(base=_RUN_STATE["path"]):
+            for ext in ("", ".cwd", ".tmp"):
+                try:
+                    os.remove(base + ext)
+                except OSError:
+                    pass
+        atexit.register(_clean)
+    return _RUN_STATE["path"]
+
+
+def _run_state_cwd() -> str:
+    """The folder the last shell line ended in, this turn — or ""."""
+    p = _RUN_STATE["path"]
+    if not p:
+        return ""
+    try:
+        with open(p + ".cwd", encoding="utf-8") as fh:
+            return fh.read().strip()
+    except OSError:
+        return ""
+
+
+def _run_state_set_cwd(cwd: str) -> None:
+    """Record the folder an && chain ended in — the chain runs its `cd` itself, not in bash."""
+    try:
+        with open(_run_state_path() + ".cwd", "w", encoding="utf-8") as fh:
+            fh.write(cwd)
+    except OSError:
+        pass
+
+
+def _run_state_wrapper() -> str:
+    """The outer script: $1 the line, $2 the exit file, $3 the state file."""
+    return ('[ -f "$3" ] && . "$3" >/dev/null 2>&1; '
+            "trap '__gu_rc=$?; echo $__gu_rc > \"$2\"; "
+            f"export -p | grep -vE \"{_RUN_STATE_SKIP}\" > \"$3.tmp\" 2>/dev/null && mv -f \"$3.tmp\" \"$3\"; "
+            "pwd > \"$3.cwd\"; exit $__gu_rc' EXIT; "
+            'eval "$1"')
+
+
 def _ws_scrubbed_env() -> dict:
     """Minimal child env for run_command. The worker process env holds secrets
     (GONEXT_WORKER_KEY etc. via worker.env) — a repo's test script must NEVER see
@@ -10626,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 = ""
@@ -10693,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 "
@@ -11772,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
@@ -14684,6 +14885,14 @@ def run_agent_chat(cfg):
                             if os.path.isdir(os.path.join(_active, _stripped)):
                                 _wd_in = _stripped
                 wd = _rag_read_allowed(_wd_in or _default_ws_root())
+                _wd_before = wd
+                if not _wd_in and _run_shell_bin():
+                    _kept = _run_state_cwd()
+                    if _kept and os.path.isdir(_kept):
+                        try:
+                            wd = _rag_read_allowed(_kept)
+                        except Exception:  # noqa: BLE001 — left the allowed folders: start over
+                            wd = _wd_before
                 w = _ws_for_path(wd)
                 if w is None or not w.get("allowRun"):
                     # Contextual nudge (task #102): the #1 reason the model shells out here is
@@ -14707,7 +14916,12 @@ def run_agent_chat(cfg):
                            + (_HEREDOC_HINT if "quote" in str(_scan["error"]) else ""))
                     _last_obs["text"] = msg
                     return msg
-                _use_shell = bool(_scan) and _shell_needed(_scan)
+                # Once this turn has shell state (a cd, an activated venv), every line goes through
+                # the shell so it starts from that state — not only lines with shell syntax.
+                _words = [c["argv"][0] for c in _shell_commands(_scan["tokens"]) if c["argv"]] if _scan else []
+                _builtin = sorted({w for w in _words if w in _SHELL_STATE_BUILTINS})
+                _use_shell = bool(_scan) and (_shell_needed(_scan) or bool(_builtin) or bool(
+                    _RUN_STATE["path"] and os.path.exists(_RUN_STATE["path"])))
                 _bg_err = _shell_background_error(_scan) if _use_shell else None
                 if _bg_err:
                     _last_obs["text"] = _bg_err
@@ -14720,7 +14934,10 @@ def run_agent_chat(cfg):
                 # AN `&&` CHAIN IS ONE STEP (task #274): each part runs through THIS function —
                 # allowlist, risk gate, approval, server detection, all of it — in order, and
                 # the first failure stops the rest. `cd DIR` sets the folder for what follows.
-                _chain = _and_chain_parts(command)
+                # A chain runs each part as a program; `export`/`source` in it would run nothing,
+                # so with a shell such a line goes to bash whole. (`cd` the chain does itself.)
+                _chain = None if (_use_shell and [b for b in _builtin if b != "cd"]) \
+                    else _and_chain_parts(command)
                 if _chain:
                     _chain_start = _t.time()
                     _cur_wd = wd
@@ -14764,6 +14981,10 @@ def run_agent_chat(cfg):
                                 + (": " + " && ".join(_rest) if _rest else "")
                                 if _stopped else f"CHAIN DONE — all {len(_chain)} parts ran")
                     result = _summary + "\n" + "\n".join(_outs)
+                    if _shell_bin and _cur_wd != wd:
+                        _run_state_set_cwd(_cur_wd)  # the next call starts where the chain ended
+                        result += (f"\n(the shell is now in {_cur_wd} — the next run_command "
+                                   "without a workdir starts there)")
                     _last_obs["text"] = result
                     return result
                 # REFUSE SHELL SYNTAX BEFORE SPAWNING (task #204). Without this, `cd X && Y`
@@ -14884,12 +15105,13 @@ def run_agent_chat(cfg):
                 if _use_shell:
                     _cmd_text, _attrib_note = _with_attribution_text(
                         command, _scan, _attribution_settings(wd))
-                    # The exit code is written to a file so it outlives this turn's process —
-                    # the line itself runs untouched as $1 (see BACKGROUND SHELLS).
+                    # The exit code is written to a file so it outlives this turn's process, and
+                    # the folder + exports are kept for the next call — the line itself runs
+                    # untouched as $1 (see BACKGROUND SHELLS, _run_state_wrapper).
                     # Git Bash reads C:/x, not C:\x, inside the line it runs.
                     _fs = (lambda x: x.replace("\\", "/")) if _IS_WINDOWS else (lambda x: x)
-                    argv = [_shell_bin, "-c", '"$0" -c "$1"; rc=$?; echo $rc > "$2"; exit $rc',
-                            _fs(_shell_bin), _cmd_text, _fs(exit_path)]
+                    argv = [_shell_bin, "-c", _run_state_wrapper(),
+                            _fs(_shell_bin), _cmd_text, _fs(exit_path), _fs(_run_state_path())]
                 else:
                     argv, _attrib_note = _with_attribution(argv, _attribution_settings(wd))
                 if _attrib_note:
@@ -14939,7 +15161,11 @@ def run_agent_chat(cfg):
                 while True:
                     rc = proc.poll()
                     if rc is not None:
-                        out = _ws_distill_output(_read_log())
+                        _raw = _read_log()
+                        out = _ws_distill_output(_raw)
+                        # The result FIRST (#362): counts and each failure with file:line, read
+                        # from the WHOLE output — the observation below is capped, this is not.
+                        _digest = _test_digest(_raw, wd)
                         # Task #90 Phase 1 — truthful perception: never claim success the
                         # tool didn't observe. exit 0 is a FACT about the process, not
                         # proof of the GOAL (e.g. `npm start` exits 0 when its port is
@@ -14962,7 +15188,7 @@ def run_agent_chat(cfg):
                         # what `cd X && Y` used to do — and the model read the silence as a
                         # clean pass. An absence cannot be reasoned about; a stated fact can.
                         result = (
-                            f"{status}\n{out}" if out.strip()
+                            f"{status}\n" + (f"{_digest}\n\n" if _digest else "") + out if out.strip()
                             else f"{status}\nNO OUTPUT: the command printed nothing on stdout or "
                                  "stderr. If you expected output, it probably did not do what "
                                  "you intended — check the command before repeating it."
@@ -14982,6 +15208,11 @@ def run_agent_chat(cfg):
                                    f"Command failed behind a pipe → {_trim_words(_hidden)}"})
                         if rc != 0 and _use_shell and _SHELL_QUOTE_ERR_RE.search(out or ""):
                             result += _HEREDOC_HINT
+                        # Say where the shell now is, so a next `cd sub` is not done twice (#362).
+                        _now = _run_state_cwd() if _use_shell else ""
+                        if _now and os.path.realpath(_now) != os.path.realpath(wd):
+                            result += (f"\n(the shell is now in {_now} — the next run_command "
+                                       "without a workdir starts there)")
                         if rc != 0 and _WS_PERM_ERR_RE.search(out or ""):
                             _f = _ws_access_facts()
                             result = f"{result}\n\n{_ws_access_report(_f, _ws_paths_in(command))}"
@@ -15197,6 +15428,14 @@ def run_agent_chat(cfg):
                 if st["state"] == "exited":
                     head += ("\nexit 0 alone does NOT prove the intended effect happened — check "
                              "the output and VERIFY.")
+                if st["state"] != "running":
+                    try:
+                        with open(sh.get("log") or "", encoding="utf-8", errors="replace") as fh:
+                            _dg = _test_digest(fh.read(), str(sh.get("workdir") or ""))
+                    except OSError:
+                        _dg = ""
+                    if _dg:
+                        head += "\n" + _dg
                 tail_note = ""
                 if not new.strip() and int(sh.get("read_offset") or 0) == 0:
                     lf = _shell_log_file(str(sh.get("command") or ""), str(sh.get("workdir") or ""))
@@ -15339,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
@@ -15359,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).