@generativereality/browser-automation 0.4.5 → 0.4.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +34 -6
- package/dist/index.js +646 -49
- package/package.json +3 -3
- package/scripts/check-one-port.sh +70 -0
- package/scripts/launch-chrome.sh +122 -7
- package/skills/browser/SKILL.md +115 -6
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
4
|
-
"description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP
|
|
3
|
+
"version": "0.4.7",
|
|
4
|
+
"description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP \u2014 many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"browser-automation": "dist/index.js"
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"dev": "bun run ./src/index.ts",
|
|
17
17
|
"build": "tsdown",
|
|
18
18
|
"typecheck": "tsc --noEmit",
|
|
19
|
-
"check": "npm run typecheck && npm run build",
|
|
19
|
+
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build",
|
|
20
20
|
"release": "bumpp && npm publish",
|
|
21
21
|
"sync-plugin": "bash scripts/sync-plugin.sh",
|
|
22
22
|
"prepack": "npm run build"
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
#
|
|
3
|
+
# One place decides the CDP port. This fails the build if a second one appears.
|
|
4
|
+
#
|
|
5
|
+
# The formula (base + uid offset) has now been copied out of `cdpPort()` twice:
|
|
6
|
+
# into the launch script within an hour of being written, and into a downstream
|
|
7
|
+
# app the same day. Both copies carried a comment promising to keep them in
|
|
8
|
+
# step, which is the tell rather than the plan — and the second time, the
|
|
9
|
+
# comment outlived the fix that removed the duplication and sat there inviting a
|
|
10
|
+
# third copy in good faith.
|
|
11
|
+
#
|
|
12
|
+
# A comment cannot enforce this. A grep can, and it costs nothing: there is no
|
|
13
|
+
# test runner in this package and this needs none.
|
|
14
|
+
#
|
|
15
|
+
# What is allowed to name the number:
|
|
16
|
+
# - src/core/cdp.ts the definition
|
|
17
|
+
# - src/commands/doctor.ts a historical note about the bug, in a comment
|
|
18
|
+
# Everything else asks: `browser-automation port`, or `--port` from the CLI.
|
|
19
|
+
set -euo pipefail
|
|
20
|
+
|
|
21
|
+
cd "$(dirname "${BASH_SOURCE[0]}")/.."
|
|
22
|
+
|
|
23
|
+
fail=0
|
|
24
|
+
|
|
25
|
+
# The base port, anywhere it could be executed.
|
|
26
|
+
while IFS= read -r hit; do
|
|
27
|
+
echo "✗ $hit" >&2
|
|
28
|
+
fail=1
|
|
29
|
+
done < <(
|
|
30
|
+
grep -rn --include='*.ts' --include='*.sh' -- '9223' src scripts 2>/dev/null \
|
|
31
|
+
| grep -v '^src/core/cdp.ts:' \
|
|
32
|
+
| grep -v '^src/commands/doctor.ts:.*\*' \
|
|
33
|
+
| grep -v '^scripts/check-one-port.sh:' \
|
|
34
|
+
| grep -vE '^[^:]+:[0-9]+:[[:space:]]*(//|#)' || true
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
# Shell ARITHMETIC on the uid — the shape a re-derivation takes when somebody
|
|
38
|
+
# does not want to shell out to node.
|
|
39
|
+
#
|
|
40
|
+
# Deliberately narrow: `$(( … ))` or `expr`, not "a line mentioning id -u".
|
|
41
|
+
# The first version matched `pgrep -u "$(id -u)" -f -- "--remote-debugging-port=…"`
|
|
42
|
+
# — the ownership probe, which uses the port it was GIVEN — and a checker whose
|
|
43
|
+
# first run cries wolf is how the one real finding gets skimmed past.
|
|
44
|
+
while IFS= read -r hit; do
|
|
45
|
+
echo "✗ $hit" >&2
|
|
46
|
+
fail=1
|
|
47
|
+
done < <(
|
|
48
|
+
grep -rnE --include='*.sh' '\$\(\([^)]*id -u|expr[^|]*id -u' scripts 2>/dev/null \
|
|
49
|
+
| grep -v '^scripts/check-one-port.sh:' || true
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
if [ "$fail" -ne 0 ]; then
|
|
53
|
+
cat >&2 <<'MSG'
|
|
54
|
+
|
|
55
|
+
The CDP port is decided in exactly one place: cdpPort() in src/core/cdp.ts.
|
|
56
|
+
Ask for it instead of recomputing it:
|
|
57
|
+
|
|
58
|
+
TypeScript import { cdpPort } from '../core/cdp.js'
|
|
59
|
+
shell browser-automation port
|
|
60
|
+
a subprocess pass --port, as `launch` does
|
|
61
|
+
|
|
62
|
+
Why this is enforced rather than requested: 127.0.0.1 is machine-wide and the
|
|
63
|
+
DevTools protocol has no authentication, so two answers to "which port" means
|
|
64
|
+
one account silently driving another account's browser — which on a real task
|
|
65
|
+
is somebody's signed-in bank session. Found 2026-08-08; not a hypothetical.
|
|
66
|
+
MSG
|
|
67
|
+
exit 1
|
|
68
|
+
fi
|
|
69
|
+
|
|
70
|
+
echo "✓ one place decides the port"
|
package/scripts/launch-chrome.sh
CHANGED
|
@@ -2,25 +2,89 @@
|
|
|
2
2
|
# Launch the canonical long-running headed Chrome that the browser-automation CLI drives via per-target CDP.
|
|
3
3
|
#
|
|
4
4
|
# Usage:
|
|
5
|
-
# ./scripts/launch-chrome.sh
|
|
6
|
-
# ./scripts/launch-chrome.sh --status
|
|
5
|
+
# ./scripts/launch-chrome.sh # launch if not already running
|
|
6
|
+
# ./scripts/launch-chrome.sh --status # exit 0 if a CDP browser is listening, else 1
|
|
7
|
+
# ./scripts/launch-chrome.sh --port 9224 # explicit port (the CLI always passes this)
|
|
8
|
+
# ./scripts/launch-chrome.sh --restart # quit a running Chrome first, then launch
|
|
9
|
+
#
|
|
10
|
+
# Why --restart exists:
|
|
11
|
+
# A browser process can permanently lose the ability to launch renderers (see
|
|
12
|
+
# src/core/renderer-health.ts for the mechanism). Every existing tab keeps
|
|
13
|
+
# working, so the browser looks fine, but no new tab or cross-origin
|
|
14
|
+
# navigation ever will again. Restarting is the ONLY recovery — and plain
|
|
15
|
+
# `launch` cannot do it, because it is idempotent by design and correctly
|
|
16
|
+
# reports "already running". Without an explicit flag the only way out was to
|
|
17
|
+
# go and kill Chrome by hand, which is how a diagnosis ends up unactionable.
|
|
7
18
|
#
|
|
8
19
|
# Why this script exists:
|
|
9
20
|
# The `browser-automation` skill prefers to drive a real, persistent Chrome
|
|
10
21
|
# profile (so logins survive reboots) over a Playwright-managed one. The
|
|
11
|
-
# convention is: one Chrome listening on --remote-debugging-port
|
|
12
|
-
# a dedicated user-data-dir. The browser-automation CLI then drives it over
|
|
13
|
-
# to start
|
|
22
|
+
# convention is: one Chrome per user listening on --remote-debugging-port with
|
|
23
|
+
# a dedicated user-data-dir. The browser-automation CLI then drives it over
|
|
24
|
+
# per-target CDP. This script is the single source of truth for how to start
|
|
25
|
+
# that Chrome.
|
|
26
|
+
#
|
|
27
|
+
# ONE CHROME PER USER, NOT PER MACHINE:
|
|
28
|
+
# 127.0.0.1 is machine-wide and CDP has no authentication, so a single
|
|
29
|
+
# hardcoded port means the first macOS account to launch owns it and every
|
|
30
|
+
# other account's automation silently drives that account's browser. The port
|
|
31
|
+
# is therefore derived from the uid, by `cdpPort()` in src/core/cdp.ts — the
|
|
32
|
+
# one place that decides it. This script is told, or asks.
|
|
14
33
|
set -euo pipefail
|
|
15
34
|
|
|
16
|
-
|
|
35
|
+
# --- port ------------------------------------------------------------------
|
|
36
|
+
# **Asked for, never recomputed.** `cdpPort()` in src/core/cdp.ts is the only
|
|
37
|
+
# place the port is decided; the CLI passes it here with --port, and a person
|
|
38
|
+
# running this script by hand gets the same number by asking the CLI that ships
|
|
39
|
+
# beside it. A second copy of the formula is a second answer waiting to happen.
|
|
40
|
+
ask_cli_for_port() {
|
|
41
|
+
local dist="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/dist/index.js"
|
|
42
|
+
if [ -f "$dist" ] && command -v node >/dev/null 2>&1; then
|
|
43
|
+
node "$dist" port 2>/dev/null && return 0
|
|
44
|
+
fi
|
|
45
|
+
command -v browser-automation >/dev/null 2>&1 && browser-automation port 2>/dev/null
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
PORT=""
|
|
49
|
+
RESTART=0
|
|
50
|
+
ARGS=()
|
|
51
|
+
while [ $# -gt 0 ]; do
|
|
52
|
+
case "$1" in
|
|
53
|
+
--port) PORT="${2:-}"; shift 2 ;;
|
|
54
|
+
--restart) RESTART=1; shift ;;
|
|
55
|
+
*) ARGS+=("$1"); shift ;;
|
|
56
|
+
esac
|
|
57
|
+
done
|
|
58
|
+
set -- "${ARGS[@]+"${ARGS[@]}"}"
|
|
59
|
+
PORT="${PORT:-$(ask_cli_for_port || true)}"
|
|
60
|
+
if [ -z "${PORT}" ]; then
|
|
61
|
+
echo "Error: could not work out which port to use — pass --port, or set" >&2
|
|
62
|
+
echo " BROWSER_AUTOMATION_PORT. (This script asks the CLI beside it;" >&2
|
|
63
|
+
echo " see cdpPort() in src/core/cdp.ts, the only place it is decided.)" >&2
|
|
64
|
+
exit 1
|
|
65
|
+
fi
|
|
66
|
+
|
|
17
67
|
PROFILE="${BROWSER_AUTOMATION_PROFILE:-$HOME/Library/Application Support/Google/Chrome/browser-automation}"
|
|
18
|
-
|
|
68
|
+
# Under the caller's OWN temp dir: /tmp is shared and sticky, so with a
|
|
69
|
+
# machine-global name the second user cannot write the first user's log.
|
|
70
|
+
LOG="${BROWSER_AUTOMATION_LOG:-${TMPDIR:-/tmp}/chrome-${PORT}.log}"
|
|
19
71
|
|
|
20
72
|
is_up() {
|
|
21
73
|
curl -fs -o /dev/null "http://localhost:${PORT}/json/version"
|
|
22
74
|
}
|
|
23
75
|
|
|
76
|
+
# Is the browser answering on this port OURS?
|
|
77
|
+
#
|
|
78
|
+
# Note the question is "is it mine", not "whose is it". `lsof` tells a
|
|
79
|
+
# non-root user NOTHING about another user's socket — it prints an empty
|
|
80
|
+
# result and exits 0, which reads exactly like a free port. Measured
|
|
81
|
+
# 2026-08-08: as the second account, `lsof -iTCP:9223 -sTCP:LISTEN` returned
|
|
82
|
+
# nothing while the first account's Chrome was plainly listening. You can
|
|
83
|
+
# always see your OWN processes, so ask that instead.
|
|
84
|
+
port_is_ours() {
|
|
85
|
+
pgrep -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" >/dev/null 2>&1
|
|
86
|
+
}
|
|
87
|
+
|
|
24
88
|
if [ "${1:-}" = "--status" ]; then
|
|
25
89
|
if is_up; then
|
|
26
90
|
echo "Chrome CDP on :${PORT} is up"
|
|
@@ -30,9 +94,50 @@ if [ "${1:-}" = "--status" ]; then
|
|
|
30
94
|
exit 1
|
|
31
95
|
fi
|
|
32
96
|
|
|
97
|
+
# Something is answering on our port and it is not ours. Refuse loudly rather
|
|
98
|
+
# than drive it: "already running" here used to mean "another macOS account's
|
|
99
|
+
# browser, and you will never be told".
|
|
100
|
+
if is_up && ! port_is_ours; then
|
|
101
|
+
echo "Error: something else on this Mac is already serving CDP on port ${PORT}," >&2
|
|
102
|
+
echo " and it is not a Chrome this account started. Driving it would act in" >&2
|
|
103
|
+
echo " ANOTHER user's browser — quit Chrome in that account, or set" >&2
|
|
104
|
+
echo " BROWSER_AUTOMATION_PORT to a free port for this one." >&2
|
|
105
|
+
exit 1
|
|
106
|
+
fi
|
|
107
|
+
|
|
108
|
+
# Restart: quit the Chrome we own, wait for the port to go quiet, fall through
|
|
109
|
+
# to the normal launch. Deliberately SIGTERM, not SIGKILL — Chrome flushes its
|
|
110
|
+
# profile (cookies, extension state, session) on a clean quit, and that profile
|
|
111
|
+
# is the whole reason this browser is long-lived. Only escalate if it will not
|
|
112
|
+
# go, and say so when it happens.
|
|
113
|
+
if [ "$RESTART" = "1" ] && is_up; then
|
|
114
|
+
if ! port_is_ours; then
|
|
115
|
+
echo "Error: refusing to restart a Chrome this account did not start." >&2
|
|
116
|
+
exit 1
|
|
117
|
+
fi
|
|
118
|
+
TABS="$(curl -fs "http://localhost:${PORT}/json/list" 2>/dev/null | grep -c '"type": "page"' || true)"
|
|
119
|
+
echo "Restarting Chrome on :${PORT} — closing ${TABS:-?} open tab(s)."
|
|
120
|
+
pkill -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" 2>/dev/null || true
|
|
121
|
+
for _ in $(seq 1 40); do
|
|
122
|
+
is_up || break
|
|
123
|
+
sleep 0.25
|
|
124
|
+
done
|
|
125
|
+
if is_up; then
|
|
126
|
+
echo "Chrome did not quit on SIGTERM after 10s; sending SIGKILL." >&2
|
|
127
|
+
pkill -9 -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" 2>/dev/null || true
|
|
128
|
+
sleep 2
|
|
129
|
+
fi
|
|
130
|
+
# Chrome unregisters its bootstrap names and releases the port on the way out;
|
|
131
|
+
# relaunching before that finishes produces a second browser that cannot serve
|
|
132
|
+
# CDP. A short settle beats a confusing race.
|
|
133
|
+
sleep 1
|
|
134
|
+
fi
|
|
135
|
+
|
|
33
136
|
if is_up; then
|
|
34
137
|
echo "Already running on :${PORT} — nothing to do."
|
|
35
138
|
echo "Drive it with: browser-automation goto -s <session> <url>"
|
|
139
|
+
echo "(To force a fresh browser process — the only fix for a Chrome that can no"
|
|
140
|
+
echo " longer launch renderers — use: browser-automation launch --restart)"
|
|
36
141
|
exit 0
|
|
37
142
|
fi
|
|
38
143
|
|
|
@@ -57,6 +162,16 @@ fi
|
|
|
57
162
|
|
|
58
163
|
mkdir -p "$(dirname "$PROFILE")"
|
|
59
164
|
|
|
165
|
+
# Keep one generation of the previous log. Chrome's stdout is the only place
|
|
166
|
+
# the reason for a renderer failure is ever written, and truncating it on
|
|
167
|
+
# relaunch destroys the evidence at exactly the moment somebody restarted
|
|
168
|
+
# BECAUSE of that failure. (Done during this fix, to this author's own
|
|
169
|
+
# evidence.) One generation, not a rotation scheme: the interesting log is
|
|
170
|
+
# always the one from the browser that just misbehaved.
|
|
171
|
+
if [ -s "$LOG" ]; then
|
|
172
|
+
mv -f "$LOG" "${LOG}.prev" 2>/dev/null || true
|
|
173
|
+
fi
|
|
174
|
+
|
|
60
175
|
nohup "$CHROME" \
|
|
61
176
|
--remote-debugging-port="$PORT" \
|
|
62
177
|
--user-data-dir="$PROFILE" \
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -14,7 +14,8 @@ file under `~/.browser-automation/sessions/`.
|
|
|
14
14
|
|
|
15
15
|
## The model — read this first
|
|
16
16
|
|
|
17
|
-
- **One shared headed Chrome** on
|
|
17
|
+
- **One shared headed Chrome per USER** on a uid-derived
|
|
18
|
+
`--remote-debugging-port` (`9223` for the first account on the machine) with a
|
|
18
19
|
persistent profile (`browser-automation`). Cookies, logins, and **browser
|
|
19
20
|
extensions (password managers, etc.) all persist** across runs and across
|
|
20
21
|
Claude Code restarts. The user can watch and complete interactive auth in the
|
|
@@ -55,7 +56,7 @@ file under `~/.browser-automation/sessions/`.
|
|
|
55
56
|
|
|
56
57
|
```bash
|
|
57
58
|
npm install -g @generativereality/browser-automation
|
|
58
|
-
browser-automation launch # start
|
|
59
|
+
browser-automation launch # start this user's Chrome (idempotent)
|
|
59
60
|
browser-automation doctor # verify Node, Chrome, targets, sessions
|
|
60
61
|
```
|
|
61
62
|
|
|
@@ -71,7 +72,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
71
72
|
| Need | Command |
|
|
72
73
|
|---|---|
|
|
73
74
|
| Start/refresh the Chrome | `browser-automation launch` |
|
|
74
|
-
| Diagnose setup | `browser-automation doctor` |
|
|
75
|
+
| Diagnose setup (incl. renderer capacity) | `browser-automation doctor` |
|
|
75
76
|
| List sessions + every open tab (id, title, url) | `browser-automation list` |
|
|
76
77
|
| Open a background tab | `browser-automation new -s work [url]` |
|
|
77
78
|
| Navigate (session tab created if needed) | `browser-automation goto -s work https://example.com` |
|
|
@@ -85,8 +86,11 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
85
86
|
| Download a file / CSV export | `browser-automation download -m bank --click e42` (or `--url <href>`) |
|
|
86
87
|
| Set files on a known `<input type=file>` | `browser-automation setfiles -m app e7 ~/Desktop/clip.mp4` |
|
|
87
88
|
| Upload via a button that opens a file chooser | `browser-automation upload -m app --click e9 ~/Desktop/clip.mp4` |
|
|
89
|
+
| Drop file(s) onto a drag-and-drop zone | `browser-automation drop -m app e7 ~/Desktop/clip.mp4` (add `--js` for a synthetic drop) |
|
|
88
90
|
| Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
|
|
89
91
|
| Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
|
|
92
|
+
| Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
|
|
93
|
+
| Restart Chrome (only fix for the renderer wedge — closes ALL tabs) | `browser-automation launch --restart` |
|
|
90
94
|
| Forget a session (tab stays open) | `browser-automation close -s work` |
|
|
91
95
|
| Forget **and** close the browser tab | `browser-automation close -s work --tab` |
|
|
92
96
|
|
|
@@ -186,7 +190,7 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
186
190
|
whose JS handler builds a client-side **blob** and clicks it via a *nested*
|
|
187
191
|
synthetic click won't fire (Chrome activation quirk) — for those, grab the
|
|
188
192
|
underlying export URL/endpoint and use `--url`, or the site's API.
|
|
189
|
-
- **File upload.**
|
|
193
|
+
- **File upload.** Three paths. The first two mirror Playwright. For a static, snapshot-able
|
|
190
194
|
`<input type=file>`, use `setfiles <ref> <path…>` — it resolves the ref and
|
|
191
195
|
calls `DOM.setFileInputFiles` (a file input's `.files` is read-only to page JS,
|
|
192
196
|
so a value-setter/`eval` can't populate it; CDP can, and fires trusted
|
|
@@ -207,11 +211,113 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
207
211
|
successful run **adds another attachment** — retrying a "did it work?" upload a
|
|
208
212
|
few times silently produces duplicates (this cost us a dozen copies on a live ASC
|
|
209
213
|
reply). Upload once, verify, and only re-run if verification shows nothing staged.
|
|
214
|
+
The **third path is drag-and-drop**, for zones with NO `<input type=file>` at
|
|
215
|
+
all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
|
|
216
|
+
tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
|
|
217
|
+
use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
|
|
218
|
+
(`Input.dispatchDragEvent`) carrying the real files from disk: it force-fronts
|
|
219
|
+
the tab (bringToFront + focus emulation + active lifecycle — so the tab reports
|
|
220
|
+
focused+visible even when the Chrome window isn't the frontmost OS window),
|
|
221
|
+
waits for the zone to be actionable, then dragEnter→dragOver→drop. The
|
|
222
|
+
force-front matters: drop-zone uploaders commonly do their work only inside a
|
|
223
|
+
**user activation**, and CDP input grants no activation on a tab the renderer
|
|
224
|
+
considers `hidden` — which it is whenever the window is occluded (the usual
|
|
225
|
+
case while you work in the terminal). vocalremover.org is the canonical example:
|
|
226
|
+
the file reaches its `change`/`drop` handler either way, but it only uploads +
|
|
227
|
+
separates once activation is present. `--js` instead dispatches a synthetic
|
|
228
|
+
(isTrusted=false) `DataTransfer` drop **without** force-fronting/stealing focus,
|
|
229
|
+
for zones that accept synthetic events. The `<ref>` can be any snapshot element
|
|
230
|
+
sitting over the drop region (a heading/button inside the zone) — the drop
|
|
231
|
+
bubbles to the zone/document handler, so it works even when the drop div itself
|
|
232
|
+
isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
|
|
233
|
+
confirm processing started, then grab the result (often a download endpoint you
|
|
234
|
+
can pull with `download --url`).
|
|
235
|
+
- **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
|
|
236
|
+
A browser process can permanently lose the ability to launch **renderer processes** while
|
|
237
|
+
looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
|
|
238
|
+
until you open a tab or navigate somewhere new, and then the errors read as the remote site's
|
|
239
|
+
doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
|
|
240
|
+
|
|
241
|
+
How it shows up:
|
|
242
|
+
- `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
|
|
243
|
+
`example.com`**.
|
|
244
|
+
- **Cross-origin** navigation of an existing, working tab → `navigate failed: net::ERR_ABORTED`.
|
|
245
|
+
Site isolation puts a new origin in a new renderer — the exact thing Chrome can no longer do.
|
|
246
|
+
- **Same-origin** navigation on that same tab keeps working perfectly (Skyscanner → Skyscanner
|
|
247
|
+
with new query params was fine throughout). That asymmetry is what makes it masquerade as
|
|
248
|
+
"only site X blocks us": the tab you were already using still behaves.
|
|
249
|
+
- A target created at the browser level (`PUT /json/new?<url>`) appears in `/json/list` with the
|
|
250
|
+
right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
|
|
251
|
+
`Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
|
|
252
|
+
|
|
253
|
+
**The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
|
|
254
|
+
keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
|
|
255
|
+
restart):
|
|
256
|
+
```
|
|
257
|
+
ERROR:base/apple/mach_port_rendezvous_mac.cc:256]
|
|
258
|
+
bootstrap_look_up com.google.Chrome.MachPortRendezvousServer.<pid>: (ipc/send) invalid destination port
|
|
259
|
+
ERROR:base/memory/shared_memory_switch.cc:261]
|
|
260
|
+
No rendezvous client, terminating process (parent died?)
|
|
261
|
+
```
|
|
262
|
+
A Chrome child process gets its shared-memory handles by looking up a Mach bootstrap service the
|
|
263
|
+
browser registers **once, at startup**, named `com.google.Chrome.MachPortRendezvousServer.<browser-pid>`.
|
|
264
|
+
That registration had vanished from the user's launchd namespace — confirmed absent via
|
|
265
|
+
`launchctl print gui/$UID | grep MachPortRendezvousServer.<pid>`, while two healthy Chromes on the
|
|
266
|
+
same machine were both listed. From then on **every renderer Chrome launches kills itself within
|
|
267
|
+
milliseconds**, which is why none ever appears in `ps` and why the browser only reports
|
|
268
|
+
`Render process gone.` **What made the name vanish is not established.** Two things
|
|
269
|
+
correlated and neither is proven: the binary on disk had moved to 151.0.7922.170 while the live
|
|
270
|
+
browser was still running .138, and `GoogleUpdater` was FATAL-ing on its own `bootstrap_check_in`
|
|
271
|
+
with error 141. But the first renderer failure (18:53) *preceded* the first updater FATAL (19:42)
|
|
272
|
+
by ~50 minutes, so the update churn is at best a fellow symptom of a sick launchd bootstrap
|
|
273
|
+
namespace, not the cause. Treat the trigger as unknown; the diagnosis and the recovery do not
|
|
274
|
+
depend on it.
|
|
275
|
+
|
|
276
|
+
**It is NOT about how many tabs are open.** That was the first theory and it is wrong: a freshly
|
|
277
|
+
launched Chrome on the same machine was driven to **421 page targets / 435 live renderer
|
|
278
|
+
processes, every one responsive**, and a 256-fd `ulimit` made no difference either (205 renderers,
|
|
279
|
+
all fine). The broken browser had 66 tabs. The count was a coincidence — so do not treat a big
|
|
280
|
+
tab count as evidence of this, and do not expect closing tabs to fix it.
|
|
281
|
+
|
|
282
|
+
**Diagnose it:**
|
|
283
|
+
```bash
|
|
284
|
+
browser-automation doctor # measures renderer capacity, not just reachability
|
|
285
|
+
```
|
|
286
|
+
`doctor` now creates a throwaway tab, makes its renderer evaluate `1+1`, and closes it — the one
|
|
287
|
+
round-trip that separates a wedged browser from a slow network or a hostile site. On failure it
|
|
288
|
+
names the root cause (including the missing bootstrap service and the pid) and points at Chrome's
|
|
289
|
+
log. On a healthy browser it reports e.g. `✓ Renderer capacity: a new tab got a live renderer in
|
|
290
|
+
73ms`. `goto` and `new` run the same probe automatically **on the error path only**, so a bare
|
|
291
|
+
`Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
|
|
292
|
+
site's bot-protection docs.
|
|
293
|
+
|
|
294
|
+
**Recovery — only a Chrome restart clears it.** The bootstrap name is registered at startup and
|
|
295
|
+
never re-registered, so nothing short of a new browser process helps. Closing tabs does not, and
|
|
296
|
+
plain `launch` will not either (idempotent by design — it sees a live browser and exits happy):
|
|
297
|
+
```bash
|
|
298
|
+
browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
|
|
299
|
+
```
|
|
300
|
+
It reports how many tabs it is about to close. **Those tabs belong to every parallel Claude Code
|
|
301
|
+
session sharing this Chrome — ask Fred first, never restart unilaterally.**
|
|
302
|
+
|
|
303
|
+
**Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
|
|
304
|
+
(they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
|
|
305
|
+
closes tabs whose renderer does not answer. Use `--dry` first. It is genuinely useful, but it is
|
|
306
|
+
**not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
|
|
307
|
+
— tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
|
|
308
|
+
nobody wants it.
|
|
309
|
+
|
|
310
|
+
**The false lead to resist:** a bare `curl` to a suspicious site may genuinely return a bot wall
|
|
311
|
+
(vikingline.fi serves an Imperva "Pardon Our Interruption" page, HTTP 200), which feels like
|
|
312
|
+
confirmation. It confirms nothing about the browser path — the persistent, cookie-bearing profile
|
|
313
|
+
is a completely different client. Check the browser first: if `doctor` says renderer capacity is
|
|
314
|
+
fine and a boring cross-origin URL loads, *then* start suspecting the site.
|
|
315
|
+
|
|
210
316
|
- **Page still loading.** `goto` waits for the load event, but SPAs render after.
|
|
211
317
|
If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
|
|
212
318
|
once a known element should be present.
|
|
213
319
|
- **`launch` is macOS/Linux only** (resolves the Chrome binary per-OS). On other
|
|
214
|
-
setups, start Chrome manually with `--remote-debugging-port
|
|
320
|
+
setups, start Chrome manually with `--remote-debugging-port=<doctor's port>
|
|
215
321
|
--user-data-dir="<profile>"`.
|
|
216
322
|
|
|
217
323
|
## Network insights — find the API behind a page
|
|
@@ -275,7 +381,10 @@ working around it forever**:
|
|
|
275
381
|
|
|
276
382
|
## Troubleshooting
|
|
277
383
|
|
|
278
|
-
- **`No CDP browser on http://localhost
|
|
384
|
+
- **`No CDP browser on http://localhost:<port>`** → `browser-automation launch`.
|
|
385
|
+
If it says the port is held by ANOTHER user, that is not your Chrome and
|
|
386
|
+
driving it would act in their session — quit Chrome in that account, or set
|
|
387
|
+
`BROWSER_AUTOMATION_PORT`.
|
|
279
388
|
- **`command not found: browser-automation`** → `npm install -g @generativereality/browser-automation`.
|
|
280
389
|
- **Chrome was restarted** → nothing to do; the next `goto` recreates the
|
|
281
390
|
session's tab automatically (sessions self-heal; `list` shows `stale`).
|