witbitz-code 1.7.4__tar.gz → 1.8.0__tar.gz

{witbitz_code-1.7.4/src/witbitz_code.egg-info → witbitz_code-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: witbitz-code
-Version: 1.7.4
+Version: 1.8.0
 Summary: Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay.
 Author: Witbitz
 License-Expression: MIT

{witbitz_code-1.7.4 → witbitz_code-1.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "witbitz-code"
-version = "1.7.4"
+version = "1.8.0"
 description = "Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay."
 readme = "README.md"
 requires-python = ">=3.10"

{witbitz_code-1.7.4 → witbitz_code-1.8.0}/src/witbitz_code/__init__.py

@@ -4,4 +4,4 @@ The Python implementation of tools/witbitz-code.mjs (docs/opencode-relay.md phas
 vectors and cross-implementation tests.
 """
 
-__version__ = "1.7.4"
+__version__ = "1.8.0"

witbitz_code-1.8.0/src/witbitz_code/browse.py

@@ -0,0 +1,145 @@
+"""The agent's browser on this computer — the twin of tools/browse-local-serve.mjs (2026-10-19; the owner: "I want to add the
+browsing with agent capability in local code too" → "Both stages. Default.").
+
+ON by default; `serve --no-browser` or WB_BROWSE_DISABLE=1 turns it off (and removes the agent's browser tools). The browser
+programs are JavaScript (the cloud computer's own: browse-local, the agent's CLI, the publisher), so they run with this
+computer's `node` — as the media tools do; without node the agent works without a browser. Each pairing gets a viewer key
+derived from its secret (relay.browse_key = codeRelay.js deriveBrowseKey), so the app can Watch and Take over.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import shutil
+import socket
+import subprocess
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+from . import plugins
+from .relay import browse_key
+
+BROWSE_DIR = "witbitz-browse"
+PLUGIN_REL = "plugins/witbitz-browser.js"
+FILES = {  # installed path (under OpenCode's config folder) → the packaged file (tools/browse-embed.mjs writes them)
+    f"{BROWSE_DIR}/browse-local.mjs": "witbitz-browse-local.mjs",
+    f"{BROWSE_DIR}/browse-cdp.mjs": "witbitz-browse-cdp.mjs",
+    f"{BROWSE_DIR}/browse-publisher.mjs": "witbitz-browse-publisher.mjs",
+    PLUGIN_REL: "witbitz-browser.js",
+}
+
+
+def disabled(args: list[str], env: dict | None = None) -> bool:
+    env = os.environ if env is None else env
+    return "--no-browser" in args or bool(re.fullmatch(r"(?i)1|true|yes", str(env.get("WB_BROWSE_DISABLE", ""))))
+
+
+def install(config_dir: Path | None = None) -> dict[str, Path]:
+    """The browser files into OpenCode's config folder (an identical file is left alone); → their paths by file name."""
+    root = Path(config_dir) if config_dir else plugins.opencode_config_dir()
+    out = {}
+    for rel, name in FILES.items():
+        target = root / rel
+        text = plugins.packaged(name)
+        try:
+            same = target.read_text(encoding="utf-8") == text
+        except (OSError, UnicodeDecodeError):
+            same = False
+        if not same:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(text, encoding="utf-8", newline="")
+        out[Path(rel).name] = target
+    return out
+
+
+def remove(config_dir: Path | None = None) -> None:
+    """Turned off: the agent's browser tools go, so OpenCode never offers a tool that can only fail."""
+    root = Path(config_dir) if config_dir else plugins.opencode_config_dir()
+    try:
+        (root / PLUGIN_REL).unlink()
+    except FileNotFoundError:
+        pass
+
+
+def node_major(node: str) -> int:
+    try:
+        v = subprocess.run([node, "--version"], capture_output=True, text=True, timeout=10).stdout.strip()
+        return int(v.lstrip("v").split(".")[0])
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return 0
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class LocalBrowser:
+    def __init__(self, proc: asyncio.subprocess.Process, ctl: int, env: dict, http: httpx.AsyncClient) -> None:
+        self.proc, self.ctl, self.env, self._http = proc, ctl, env, http
+        self.last: dict | None = None
+        self._task: asyncio.Task | None = None
+
+    def probe(self) -> dict | None:
+        """The browser's last /status — synchronous: the connector's hello must never wait on it."""
+        return self.last
+
+    async def _poll(self) -> None:
+        try:
+            r = await self._http.get(f"http://127.0.0.1:{self.ctl}/status", timeout=1.5)
+            self.last = r.json() if r.status_code == 200 else None
+        except (httpx.HTTPError, ValueError):
+            self.last = None
+
+    async def _every(self) -> None:
+        while True:
+            await asyncio.sleep(2)
+            await self._poll()
+
+    async def stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+        if self.proc.returncode is None:
+            try:
+                self.proc.terminate()
+                await asyncio.wait_for(self.proc.wait(), 5)
+            except (ProcessLookupError, asyncio.TimeoutError):
+                try:
+                    self.proc.kill()
+                except ProcessLookupError:
+                    pass
+        await self._http.aclose()
+
+
+async def start(pairings: list[dict], *, config_dir: Path | None = None, log: Callable[[str], Any] = print,
+                node: str | None = None) -> LocalBrowser | None:
+    """Start it; → a LocalBrowser (env for OpenCode, probe for the hello), or None when this computer has no node."""
+    node = node or shutil.which("node")
+    if not node:
+        log("witbitz-code: no node on this computer — the agent works without a browser (install Node.js 22+ to add one)")
+        return None
+    paths = await asyncio.to_thread(install, config_dir)
+    watchable = node_major(node) >= 22  # the publisher needs a global WebSocket
+    keys = [browse_key(p["secret"]) for p in pairings if p.get("secret")] if watchable else []
+    ctl, gate = _free_port(), _free_port()
+    env = {**os.environ, "WB_BROWSE_CTL_PORT": str(ctl), "WB_BROWSE_GATE_PORT": str(gate), "WB_BROWSE_KEYS": ",".join(keys),
+           "WB_BROWSE_PUBLISHER": str(paths["browse-publisher.mjs"]), "WB_BROWSE_PARENT": str(os.getpid())}
+    proc = await asyncio.create_subprocess_exec(node, str(paths["browse-local.mjs"]), env=env, stdin=asyncio.subprocess.DEVNULL,
+                                                stdout=asyncio.subprocess.DEVNULL)
+    b = LocalBrowser(proc, ctl, {"WB_BROWSE_NODE": node, "WB_BROWSE_CDP_CLI": str(paths["browse-cdp.mjs"]),
+                                 "WB_BROWSE_CTL": f"http://127.0.0.1:{ctl}", "WB_BROWSE_CDP": f"http://127.0.0.1:{gate}"},
+                     httpx.AsyncClient())
+    for _ in range(20):  # its control port answers within a moment
+        await b._poll()
+        if b.last is not None:
+            break
+        await asyncio.sleep(0.25)
+    b._task = asyncio.ensure_future(b._every())
+    log("witbitz-code: the agent's browser is ready on this computer"
+        + (" — watch it from the Code section" if watchable else " (node is older than 22: the app cannot watch it)") + "; off: serve --no-browser")
+    return b

{witbitz_code-1.7.4 → witbitz_code-1.8.0}/src/witbitz_code/cli.py

@@ -26,7 +26,7 @@ import httpx
 from . import __version__
 from . import pair as pair_cmd
 from . import pairings as pp
-from . import codekeys, codetools, confidential, keys, models, plugins, policy, ports, toolsetup, uninstall as uninstall_mod, winagent, winbg, winconsole, wizard, wslstart
+from . import browse as browse_mod, codekeys, codetools, confidential, keys, models, plugins, policy, ports, toolsetup, uninstall as uninstall_mod, winagent, winbg, winconsole, wizard, wslstart
 from ._js import to_number, truthy
 from .connector import pairings_for_port, start_connector
 from .payers import SessionPayers
@@ -41,7 +41,7 @@ HELP = f"""witbitz-code {__version__} — reach OpenCode on this computer from t
                                start when I log in (Windows and WSL); it serves while it runs. --background (Windows):
                                no window — the page's Quit stops it
   pair [--name <name>]         show a QR code; scan it in Spaces (Settings → Privacy & security → Add a device)
-  serve [--port <n>] [--no-opencode]
+  serve [--port <n>] [--no-opencode] [--no-browser]
                                start OpenCode on 127.0.0.1 with your account's keys, and the connector
   status                       list this computer's pairings and their coding keys
   rotate [--account <email>]   replace the pairing secret(s) without a scan, then restart serve
@@ -217,6 +217,7 @@ async def serve(args: list[str], *, stop: Any = None, live_out: dict | None = No
     stop = stop or _Stop()
     child = None
     proxy = None
+    browser = None
     live: dict = {"connector": None}
     keys_http = httpx.AsyncClient(timeout=30)
     try:
@@ -245,6 +246,17 @@ async def serve(args: list[str], *, stop: Any = None, live_out: dict | None = No
             _err(f"witbitz-code: OpenCode is already running on 127.0.0.1:{port}, started some other way — it cannot use your account's keys.")
             _err("              Close it, then run witbitz-code serve again (it starts OpenCode itself).")
             return 1
+        # THE AGENT'S BROWSER (browse.py): ON unless --no-browser / WB_BROWSE_DISABLE=1 — started BEFORE OpenCode, whose
+        # plugin reads where it is; watched from the Code section like a cloud computer's.
+        if browse_mod.disabled(args):
+            browse_mod.remove()
+        else:
+            try:
+                browser = await browse_mod.start(pairings, log=_err)
+            except OSError as e:
+                _err(f"witbitz-code: the agent's browser could not start ({e}) — the agent works without it")
+            if browser:
+                tools_env = {**tools_env, **browser.env}
         if "--no-opencode" not in args:
             exe = wizard.find_opencode()
             if not exe:
@@ -262,7 +274,8 @@ async def serve(args: list[str], *, stop: Any = None, live_out: dict | None = No
         if child is not None:
             _err("witbitz-code: model calls are paid by each account's own coding keys; confidential models are enforced (min_privacy + verified receipts)")
         # Auto mode's reviewer asks the policy of the model proxy directly (auto_runner.REVIEW_MODELS), billed like the session.
-        connector = await start_connector(pairings, payers=payers, model_url=f"http://127.0.0.1:{proxy.port}/v1" if proxy else "")
+        connector = await start_connector(pairings, payers=payers, model_url=f"http://127.0.0.1:{proxy.port}/v1" if proxy else "",
+                                          browse_probe=browser.probe if browser else None)
         live["status"] = asyncio.ensure_future(_check_keys_every(live_keys, keys_http))
         live["connector"] = connector
         if live_out is not None:
@@ -281,6 +294,8 @@ async def serve(args: list[str], *, stop: Any = None, live_out: dict | None = No
     finally:
         if child is not None:
             await _stop_opencode(child)
+        if browser is not None:
+            await browser.stop()
         if proxy is not None:
             await proxy.close()
         await keys_http.aclose()

{witbitz_code-1.7.4 → witbitz_code-1.8.0}/src/witbitz_code/codetools.py

@@ -39,7 +39,7 @@ Tools you may expect from other setups, and what stands in for them here — do
 - todoread → todowrite returns the whole list on every write.
 - multiedit / patch → edit, one file at a time, or apply_patch where your model is offered it.
 - websearch → web_search (witbitz-media): confidential, answered by a search agent inside a hardware enclave; then webfetch a source for its full text.
-- browser → browser_open / browser_navigate / browser_snapshot / browser_click / browser_type / browser_key / browser_scroll / browser_back / browser_screenshot, when this computer offers them; act from a snapshot's numbered refs, not from a screenshot.
+- browser → browser_open / browser_navigate / browser_snapshot / browser_click / browser_type / browser_key / browser_scroll / browser_back / browser_screenshot / browser_close, when this computer offers them; close it when you are done; act from a snapshot's numbered refs, not from a screenshot.
 - lsp is here when the config enables a language server for the file type (Python: pyright); otherwise run the project's own typecheck or lint.
 """
 

{witbitz_code-1.7.4 → witbitz_code-1.8.0}/src/witbitz_code/connector.py

@@ -160,8 +160,12 @@ class PairingServer:
                  attach_root: Path | None = None, attach_max_file_bytes: int = MAX_FILE_BYTES,
                  asks_reconcile_ms: float = ASKS_RECONCILE_MS, notes_root: str | None = None,
                  notes_plugin_path: Path | None = None, payers: SessionPayers | None = None,
-                 model_url: str = "", remind_times: dict | None = None) -> None:
+                 model_url: str = "", remind_times: dict | None = None,
+                 browse_probe: Callable[[], dict | None] | None = None) -> None:
         self.pairing = pairing
+        # THE AGENT'S BROWSER ON THIS COMPUTER (browse.py): its /status rides the hello; a change is announced within 2 s
+        self._browse_probe = browse_probe
+        self._browse_said = ""  # the last browse report the page was told, as JSON
         self._security: seccheck.SecurityCheck | None = None  # read on the first ask (seccheck.py)
         # WHO PAYS (payers.py): this pairing's account owns the turns it starts; the proxy bills each call to its owner.
         self._payers = payers
@@ -227,6 +231,8 @@ class PairingServer:
         self._spawn(self._every(SWEEP_EVERY_S, self._sweep))
         self._spawn(self._every(self._remind_rt.get("every_s") or REMIND_EVERY_S, lambda: self._spawn(self._remind_tick())))
         self._spawn(self._every(HELLO_EVERY_S, lambda: self.hello() if self.peer.peers >= 2 else None))
+        if self._browse_probe:
+            self._spawn(self._every(2, self._browse_changed))
         self._spawn(self._watch_asks())
         self._spawn(self._every(self._asks_reconcile_s, lambda: self._spawn(self._reconcile_asks()) if self._asks_live else None))
         self.auto.start()
@@ -290,12 +296,27 @@ class PairingServer:
         except Exception as e:
             self._log(f"witbitz-code: {self.name} · {e}")
 
+    def _browse_report(self) -> dict | None:
+        try:
+            r = self._browse_probe() if self._browse_probe else None
+        except Exception:  # noqa: BLE001 — a probe that throws reports nothing
+            r = None
+        return r if isinstance(r, dict) else None
+
+    def _browse_changed(self) -> None:
+        now = json.dumps(self._browse_report(), sort_keys=True)
+        if now != self._browse_said and self.peer.peers >= 2:
+            self.hello()
+
     def hello(self) -> asyncio.Future | None:
         if not self.nonce:
             return None  # no hello before this socket has its nonce
+        browse = self._browse_report()
+        self._browse_said = json.dumps(browse, sort_keys=True)
         # caps: what this connector can do beyond the requests — a page shows the Auto switch only when `auto` is here.
         return self.peer.send({"t": "hello", "ver": VERSION, "name": self.name, "computerId": self.pairing.get("computerId") or "",
-                               "k": self.nonce, "ts": int(time.time() * 1000), "caps": ["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind"], "auto": self.auto.sessions()})
+                               "k": self.nonce, "ts": int(time.time() * 1000), "caps": ["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind"], "auto": self.auto.sessions(),
+                               **({"browse": browse} if browse else {})})
 
     def _auth(self) -> dict:
         pw = self.pairing.get("password") or read_env_password(Path(self.pairing["envFile"]) if self.pairing.get("envFile") else None)
@@ -941,7 +962,8 @@ async def start_connector(pairings: list[dict], *, flush_ms: float = 120, log: C
                           attach_root: Path | None = None, attach_max_file_bytes: int = MAX_FILE_BYTES,
                           asks_reconcile_ms: float = ASKS_RECONCILE_MS, notes_root: str | None = None,
                           notes_plugin_path: Path | None = None, payers: SessionPayers | None = None,
-                          model_url: str = "", remind_times: dict | None = None) -> Connector:
+                          model_url: str = "", remind_times: dict | None = None,
+                          browse_probe: Callable[[], dict | None] | None = None) -> Connector:
     """Serve the given pairings until stop()/aclose(). Options exist for tests: flush_ms, log, client, connect,
     request_timeout_ms, max_senders, max_response_bytes, auto_dir, auto_poll_ms."""
     client = client or local_client()
@@ -956,7 +978,8 @@ async def start_connector(pairings: list[dict], *, flush_ms: float = 120, log: C
         s = PairingServer(p, client=client, flush_ms=flush_ms, log=log, connect=connect, request_timeout_ms=request_timeout_ms,
                           max_senders=max_senders, max_response_bytes=max_response_bytes, auto_dir=auto_dir, auto_poll_ms=auto_poll_ms,
                           attach_root=attach_root, attach_max_file_bytes=attach_max_file_bytes, asks_reconcile_ms=asks_reconcile_ms,
-                          notes_root=notes_root, notes_plugin_path=notes_plugin_path, payers=payers, model_url=model_url, remind_times=remind_times)
+                          notes_root=notes_root, notes_plugin_path=notes_plugin_path, payers=payers, model_url=model_url, remind_times=remind_times,
+                          browse_probe=browse_probe)
         await s.start()
         servers.append(s)
     return Connector(servers, client, payers)

{witbitz_code-1.7.4 → witbitz_code-1.8.0}/src/witbitz_code/devicelink.py

@@ -116,6 +116,9 @@ def read_link_payload(p: Any) -> dict | None:
             anchor = {"method": a["method"], "email": a["email"]}
             if isinstance(token, str) and token:
                 anchor["token"] = token
+            kp = a.get("kp")
+            if isinstance(kp, dict) and truthy(kp.get("priv")) and truthy(kp.get("pub")):
+                anchor["kp"] = {"priv": kp["priv"], "pub": kp["pub"]}
             if truthy(a.get("exp")):
                 anchor["exp"] = a["exp"]
     rel = p.get("rel")
@@ -128,6 +131,7 @@ def read_link_payload(p: Any) -> dict | None:
         if isinstance(rel, dict) and isinstance(rel.get("token"), str) and rel["token"] else None,
         "idx": _ptr(p.get("idx")),
         "pipes": _ptr(p.get("pipes")),
+        "msgs": _ptr(p.get("msgs")),  # the message room (deviceLink.js since b27a27d0)
         "anchor": anchor,
     }
 

witbitz_code-1.8.0/src/witbitz_code/opencode_plugins/witbitz-browse-cdp.mjs

@@ -0,0 +1,248 @@
+// browse-cdp.mjs — what the AGENT does to its browser, over CDP (docs/cloud-computer.md § 12).
+//
+//   node browse-cdp.mjs <op> ['{"json":"args"}']   → one JSON object on stdout
+//
+// It talks to the CDP GATE (browse.go), never to Chromium directly, so the enclave can close the agent's session
+// the moment the owner takes the controls — and a tool that runs during a take-over fails plainly rather than
+// quietly reading a screen someone is typing a password into.
+//
+// ★ ACCESSIBILITY, NOT PIXELS. `snapshot` returns the page's accessibility tree as numbered refs, and `click`
+// takes one of those refs. The agent never needs a screenshot to act, which keeps its context small and its
+// actions deterministic — and it means the model is working from what a screen reader would say, not from what a
+// vision model guesses a JPEG shows. A screenshot is available, for a human to look at, not for the agent to aim by.
+//
+// No dependency: Node's own fetch and WebSocket. There is no npm in the enclave and no network to reach one.
+const CTL = process.env.WB_BROWSE_CTL || 'http://127.0.0.1:9224'
+const GATE = process.env.WB_BROWSE_CDP || 'http://127.0.0.1:9223'
+const out = (o) => { process.stdout.write(JSON.stringify(o) + '\n'); process.exit(o.error ? 1 : 0) }
+
+class CDP {
+  constructor (ws) { this.ws = ws; this.id = 0; this.pending = new Map() }
+  static async attach () {
+    let targets
+    try {
+      // ★ The gate answers /json with an OBJECT when it has no browser to ask ({ error }) or when the browser did not
+      //   answer it — a model read "targets.find is not a function" for that (the owner's agent, 2026-10-06). Three quick
+      //   tries cover a browser that is still coming up; an object after that is the gate's own sentence.
+      for (let i = 0; ; i++) {
+        targets = await (await fetch(GATE + '/json')).json()
+        if (Array.isArray(targets)) break
+        if (i >= 2) throw new Error((targets && targets.error) || 'the browser gate answered without a target list')
+        await new Promise((r) => setTimeout(r, 300))
+      }
+    } catch (e) {
+      // ★★ SAY WHICH ONE. This used to answer "it may be closed, or the owner has the controls" — two causes,
+      //    neither checked, and on 2026-09-21 BOTH were false: no browser had ever been started. The agent
+      //    faithfully passed that on, and the owner went hunting in the viewer for a take-over that did not exist
+      //    ("Try opening example.com" → "it may have been closed or taken over on your side").
+      //    The control surface knows exactly which case this is and is already reachable from here, so ask it.
+      //    An absent capability and a withheld one must never read the same — the third time that lesson has been
+      //    paid for in this subsystem (the plugin that loaded zero tools, the row that was silent when not running).
+      let st = null
+      try { st = await (await fetch(CTL + '/status')).json() } catch { /* the control surface is gone too */ }
+      if (st && !st.offered) throw new Error('this cloud computer has no browser — it was created without one')
+      if (st && st.takeover) throw new Error('the owner has the controls — the agent cannot drive this browser until they give them back')
+      if (st && !st.running) throw new Error('no browser is open yet — call browser_open first, then navigate')
+      throw new Error('the browser is not reachable, and its control surface did not answer either: ' + String(e).slice(0, 80))
+    }
+    const t = targets.find((x) => x.type === 'page') || targets[0]
+    if (!t) throw new Error('the browser has no page open')
+    const ws = new WebSocket(t.webSocketDebuggerUrl)
+    await new Promise((res, rej) => {
+      const timer = setTimeout(() => rej(new Error('CDP did not answer')), 10000)
+      ws.onopen = () => { clearTimeout(timer); res() }
+      ws.onerror = () => { clearTimeout(timer); rej(new Error('the CDP gate refused the connection — the owner may have the controls')) }
+    })
+    const c = new CDP(ws)
+    ws.onmessage = (ev) => {
+      const m = JSON.parse(ev.data)
+      if (m.id && c.pending.has(m.id)) { c.pending.get(m.id)(m); c.pending.delete(m.id) }
+    }
+    return c
+  }
+  send (method, params = {}) {
+    return new Promise((res, rej) => {
+      const i = ++this.id
+      const timer = setTimeout(() => rej(new Error(method + ' timed out')), 30000)
+      this.pending.set(i, (m) => { clearTimeout(timer); m.error ? rej(new Error(method + ': ' + m.error.message)) : res(m.result) })
+      this.ws.send(JSON.stringify({ id: i, method, params }))
+    })
+  }
+  close () { try { this.ws.close() } catch { /* already gone */ } }
+}
+
+// The roles worth showing a model: everything it can act on, plus the text that tells it where it is. A full AX
+// tree of a real page is thousands of nodes and most of them are scaffolding.
+const USEFUL = new Set(['button', 'link', 'textbox', 'searchbox', 'combobox', 'checkbox', 'radio', 'menuitem',
+  'tab', 'switch', 'slider', 'option', 'heading', 'StaticText', 'image', 'listitem', 'alert', 'dialog'])
+
+async function snapshot (c, limit = 120) {
+  await c.send('Accessibility.enable')
+  const { nodes } = await c.send('Accessibility.getFullAXTree', { depth: -1 })
+  const lines = []
+  const refs = {}
+  let n = 0
+  for (const node of nodes) {
+    if (node.ignored) continue
+    const role = node.role?.value
+    const name = (node.name?.value || '').replace(/\s+/g, ' ').trim()
+    if (!role || !USEFUL.has(role)) continue
+    if (!name && role !== 'textbox' && role !== 'searchbox') continue
+    n++
+    if (n > limit) break
+    const ref = String(n)
+    refs[ref] = node.backendDOMNodeId
+    const value = node.properties?.find((p) => p.name === 'value')?.value?.value
+    lines.push(`[${ref}] ${role}${name ? ' "' + name.slice(0, 120) + '"' : ''}${value ? ' = "' + String(value).slice(0, 60) + '"' : ''}`)
+  }
+  return { lines, refs, truncated: n > limit }
+}
+
+// The refs are only meaningful next to the snapshot that made them, so they travel with it rather than living in
+// a cache that a page navigation would quietly invalidate.
+const REFS_FILE = (process.env.TMPDIR || '/tmp') + '/wb-browse-refs.json'
+const { writeFileSync, readFileSync } = await import('node:fs')
+
+// ★ A MISSING refs file is the SAME situation as a stale ref: the agent has not taken a snapshot yet. Letting
+// readFileSync throw turned that into "ENOENT: no such file or directory", which tells a model nothing it can act
+// on — its own test caught this.
+function loadRefs () {
+  try { return JSON.parse(readFileSync(REFS_FILE, 'utf8')) } catch { return {} }
+}
+
+// ★ ENTER CARRIES ITS CHARACTER. A keyDown without `text` is a key with no keypress: Chromium moves no form on it, so
+//   Enter in a search box never submitted (the owner's agent, 2026-10-07; measured: no submit as shipped, a submit with
+//   "\r"). keyDown with the text is what a real keyboard sends.
+async function pressEnter (c) {
+  await c.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, text: '\r', unmodifiedText: '\r' })
+  await c.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 })
+}
+
+async function boxOf (c, backendNodeId) {
+  let model
+  try { ({ model } = await c.send('DOM.getBoxModel', { backendNodeId })) } catch (e) { throw new Error('that ref is stale — the page changed since the snapshot that made it (' + String(e.message || e).slice(0, 80) + '); take a snapshot first') }
+  const q = model.content
+  return { x: (q[0] + q[2] + q[4] + q[6]) / 4, y: (q[1] + q[3] + q[5] + q[7]) / 4 }
+}
+
+const op = process.argv[2]
+let args = {}
+try { args = process.argv[3] ? JSON.parse(process.argv[3]) : {} } catch { out({ error: 'arguments must be JSON' }) }
+
+try {
+  if (op === 'open') {
+    const r = await fetch(CTL + '/open', { method: 'POST' })
+    const j = await r.json()
+    out(j.error ? { error: j.error } : { ok: true, ...j })
+  }
+  if (op === 'status') out(await (await fetch(CTL + '/status')).json())
+  // CLOSE: the browser and everything in it — its tabs, its logins — are gone; the next open starts a fresh one. Refused
+  // while the owner holds the controls (browse.go closeCaller): the agent does not pull the screen from a person.
+  if (op === 'close') {
+    const r = await fetch(CTL + '/close', { method: 'POST' })
+    const j = await r.json().catch(() => ({}))
+    out(j.error ? { error: j.error } : { ok: true, closed: true })
+  }
+  // CLEAR (the owner, 2026-10-19: "a tool that can clear browsing history and cookies"): a close IS a clear — it wipes the
+  // whole profile, history, cookies, cache and every site's storage (browse.go stopBrowseLocked / forgetBrowser) — and a
+  // fresh browser opens after it, so the agent can go on. ⛑ /close answers before it tears down, so this waits until the
+  // browser reports it is gone before opening again. Refused, like close, while the owner holds the controls.
+  if (op === 'clear') {
+    const r = await fetch(CTL + '/close', { method: 'POST' })
+    const j = await r.json().catch(() => ({}))
+    if (j.error) out({ error: j.error })
+    for (let i = 0; i < 40; i++) {
+      await new Promise((res) => setTimeout(res, 250))
+      const st = await (await fetch(CTL + '/status')).json().catch(() => null)
+      if (st && !st.running) break
+    }
+    const r2 = await fetch(CTL + '/open', { method: 'POST' })
+    const j2 = await r2.json().catch(() => ({}))
+    out(j2.error ? { error: 'cleared, but the browser did not open again: ' + j2.error } : { ok: true, cleared: true })
+  }
+
+  // ★ NAVIGATE OPENS THE BROWSER when none is open (the owner's agent, 2026-10-07: "it needed browser_open before
+  //   navigation"). Only a browser this computer OFFERS and that is not in the owner's hands: a computer made without one
+  //   and a take-over still answer with their own sentences (attach, below).
+  let opened = false
+  if (op === 'navigate' && args.url) {
+    let st = null
+    try { st = await (await fetch(CTL + '/status')).json() } catch { /* attach says what is wrong */ }
+    if (st && st.offered && !st.running && !st.takeover) {
+      const j = await (await fetch(CTL + '/open', { method: 'POST' })).json().catch((e) => ({ error: String(e) }))
+      if (j.error) out({ error: 'could not open the browser to navigate: ' + String(j.error).slice(0, 200) })
+      opened = true
+    }
+  }
+
+  const c = await CDP.attach()
+  await c.send('Page.enable')
+  await c.send('DOM.enable')
+
+  if (op === 'navigate') {
+    if (!args.url) out({ error: 'navigate needs a url' })
+    await c.send('Page.navigate', { url: args.url })
+    await new Promise((r) => setTimeout(r, args.waitMs ?? 1200))
+  } else if (op === 'click') {
+    const id = loadRefs()[String(args.ref)]
+    if (!id) out({ error: 'no such ref — take a snapshot first, refs belong to the snapshot that made them' })
+    const { x, y } = await boxOf(c, id)
+    for (const type of ['mousePressed', 'mouseReleased']) {
+      await c.send('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 })
+    }
+    await new Promise((r) => setTimeout(r, args.waitMs ?? 600))
+  } else if (op === 'type') {
+    if (args.ref != null) {
+      const id = loadRefs()[String(args.ref)]
+      if (!id) out({ error: 'no such ref — take a snapshot first, refs belong to the snapshot that made them' })
+      const { x, y } = await boxOf(c, id)
+      for (const type of ['mousePressed', 'mouseReleased']) {
+        await c.send('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 })
+      }
+    }
+    await c.send('Input.insertText', { text: String(args.text ?? '') })
+    if (args.enter) {
+      await pressEnter(c)
+      await new Promise((r) => setTimeout(r, args.waitMs ?? 1000))
+    }
+  } else if (op === 'key') {
+    const key = String(args.key || 'Enter')
+    const codes = { Enter: 13, Tab: 9, Escape: 27, Backspace: 8, ArrowUp: 38, ArrowDown: 40, ArrowLeft: 37, ArrowRight: 39 }
+    if (key === 'Enter') await pressEnter(c)
+    else {
+      for (const type of ['keyDown', 'keyUp']) {
+        await c.send('Input.dispatchKeyEvent', { type, key, code: key, windowsVirtualKeyCode: codes[key] ?? 0 })
+      }
+    }
+    await new Promise((r) => setTimeout(r, 400))
+  } else if (op === 'back') {
+    const h = await c.send('Page.getNavigationHistory')
+    const prev = h.entries[h.currentIndex - 1]
+    if (!prev) out({ error: 'nothing to go back to' })
+    await c.send('Page.navigateToHistoryEntry', { entryId: prev.id })
+    await new Promise((r) => setTimeout(r, 900))
+  } else if (op === 'scroll') {
+    await c.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: 200, y: 400, deltaX: 0, deltaY: Number(args.dy ?? 400) })
+    await new Promise((r) => setTimeout(r, 400))
+  } else if (op === 'screenshot') {
+    const { data } = await c.send('Page.captureScreenshot', { format: 'jpeg', quality: 70 })
+    const path = args.path || ((process.env.TMPDIR || '/tmp') + '/wb-browse-' + Date.now() + '.jpg')
+    writeFileSync(path, Buffer.from(data, 'base64'))
+    const { lines } = await snapshot(c, 0).catch(() => ({ lines: [] }))
+    c.close()
+    out({ ok: true, path, note: 'a picture for a person to look at; act from a snapshot, not from this' })
+  } else if (op !== 'snapshot') {
+    out({ error: 'unknown op: ' + op })
+  }
+
+  // every op ends by saying where the browser now is, so the agent never has to ask separately
+  const snap = await snapshot(c, args.limit ?? 120)
+  writeFileSync(REFS_FILE, JSON.stringify(snap.refs))
+  const { root } = await c.send('DOM.getDocument', { depth: 0 })
+  const title = await c.send('Runtime.evaluate', { expression: 'document.title', returnByValue: true })
+    .then((r) => r.result?.value || '').catch(() => '')
+  c.close()
+  out({ ok: true, ...(opened ? { opened: true } : {}), url: root.documentURL, title, elements: snap.lines, truncated: snap.truncated })
+} catch (e) {
+  out({ error: String(e && e.message ? e.message : e).slice(0, 300) })
+}