@generativereality/browser-automation 0.4.12 → 0.4.14
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 +2 -1
- package/dist/index.js +422 -125
- package/package.json +1 -1
- package/scripts/launch-chrome.sh +125 -19
- package/skills/browser/SKILL.md +99 -10
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.14",
|
|
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 — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
package/scripts/launch-chrome.sh
CHANGED
|
@@ -55,12 +55,18 @@ ask_cli_for_port() {
|
|
|
55
55
|
}
|
|
56
56
|
|
|
57
57
|
PORT=""
|
|
58
|
+
PROFILE=""
|
|
58
59
|
RESTART=0
|
|
60
|
+
STOP_ONLY=0
|
|
59
61
|
ARGS=()
|
|
60
62
|
while [ $# -gt 0 ]; do
|
|
61
63
|
case "$1" in
|
|
62
64
|
--port) PORT="${2:-}"; shift 2 ;;
|
|
65
|
+
--profile) PROFILE="${2:-}"; shift 2 ;;
|
|
63
66
|
--restart) RESTART=1; shift ;;
|
|
67
|
+
# Quit our Chrome and stop there. `launch --restart` uses it so the profile
|
|
68
|
+
# can be moved while nothing has it open, before the relaunch.
|
|
69
|
+
--stop) RESTART=1; STOP_ONLY=1; shift ;;
|
|
64
70
|
*) ARGS+=("$1"); shift ;;
|
|
65
71
|
esac
|
|
66
72
|
done
|
|
@@ -73,7 +79,23 @@ if [ -z "${PORT}" ]; then
|
|
|
73
79
|
exit 1
|
|
74
80
|
fi
|
|
75
81
|
|
|
76
|
-
|
|
82
|
+
# **Asked for, never hardcoded** — same reason as the port. `resolveProfile()`
|
|
83
|
+
# in src/core/profile.ts decides it (and knows about the move out of Chrome's
|
|
84
|
+
# own folder); the CLI passes it with --profile, and a person running this by
|
|
85
|
+
# hand gets the same answer from `browser-automation profile`.
|
|
86
|
+
ask_cli_for_profile() {
|
|
87
|
+
local dist="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/dist/index.js"
|
|
88
|
+
if [ -f "$dist" ] && command -v node >/dev/null 2>&1; then
|
|
89
|
+
node "$dist" profile 2>/dev/null && return 0
|
|
90
|
+
fi
|
|
91
|
+
command -v browser-automation >/dev/null 2>&1 && browser-automation profile 2>/dev/null
|
|
92
|
+
}
|
|
93
|
+
PROFILE="${PROFILE:-$(ask_cli_for_profile || true)}"
|
|
94
|
+
if [ -z "${PROFILE}" ]; then
|
|
95
|
+
echo "Error: could not work out which profile to use — pass --profile, or set" >&2
|
|
96
|
+
echo " BROWSER_AUTOMATION_PROFILE." >&2
|
|
97
|
+
exit 1
|
|
98
|
+
fi
|
|
77
99
|
# Under the caller's OWN temp dir: /tmp is shared and sticky, so with a
|
|
78
100
|
# machine-global name the second user cannot write the first user's log.
|
|
79
101
|
LOG="${BROWSER_AUTOMATION_LOG:-${TMPDIR:-/tmp}/chrome-${PORT}.log}"
|
|
@@ -119,22 +141,60 @@ fi
|
|
|
119
141
|
# profile (cookies, extension state, session) on a clean quit, and that profile
|
|
120
142
|
# is the whole reason this browser is long-lived. Only escalate if it will not
|
|
121
143
|
# go, and say so when it happens.
|
|
122
|
-
if [ "$RESTART" = "1" ] &&
|
|
144
|
+
if [ "$RESTART" = "1" ] && port_is_ours; then
|
|
123
145
|
if ! port_is_ours; then
|
|
124
146
|
echo "Error: refusing to restart a Chrome this account did not start." >&2
|
|
125
147
|
exit 1
|
|
126
148
|
fi
|
|
127
|
-
|
|
128
|
-
|
|
149
|
+
if is_up; then
|
|
150
|
+
TABS="$(curl -fs "http://localhost:${PORT}/json/list" 2>/dev/null | grep -c '"type": "page"' || true)"
|
|
151
|
+
echo "Restarting Chrome on :${PORT} — closing ${TABS:-?} open tab(s)."
|
|
152
|
+
fi
|
|
129
153
|
pkill -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" 2>/dev/null || true
|
|
154
|
+
# **Wait for Chrome to let go of the PROFILE, not for the port to close.**
|
|
155
|
+
#
|
|
156
|
+
# Chrome shuts its DevTools listener and helpers early in shutdown, so a
|
|
157
|
+
# closed port says nothing. Waiting on it relaunched on top of a Chrome still
|
|
158
|
+
# holding the profile: two browsers with one profile open, the corruption
|
|
159
|
+
# Chrome's SingletonLock exists to prevent.
|
|
160
|
+
#
|
|
161
|
+
# Nor can we wait for the process to exit. Measured 2026-09-23 on macOS 27 /
|
|
162
|
+
# Chrome 153: after SIGTERM or CDP Browser.close the browser process NEVER
|
|
163
|
+
# exits — still asleep after a minute, every restart, however launched. It has
|
|
164
|
+
# done the part that matters, though: SingletonLock is gone, i.e. the profile
|
|
165
|
+
# is flushed and released, and what is left is a Mac app with no windows.
|
|
166
|
+
# Ending that is harmless. Ending a Chrome that still holds the lock is not.
|
|
167
|
+
profile_released() {
|
|
168
|
+
# Only if we can actually SEE the profile. A host macOS has refused
|
|
169
|
+
# Chrome's folder cannot, and "no lock visible" would then read as
|
|
170
|
+
# "released" and kill a Chrome mid-flush.
|
|
171
|
+
ls "$PROFILE" >/dev/null 2>&1 || return 1
|
|
172
|
+
[ ! -L "$PROFILE/SingletonLock" ] && [ ! -e "$PROFILE/SingletonLock" ]
|
|
173
|
+
}
|
|
130
174
|
for _ in $(seq 1 40); do
|
|
131
|
-
|
|
175
|
+
port_is_ours || break
|
|
176
|
+
profile_released && break
|
|
132
177
|
sleep 0.25
|
|
133
178
|
done
|
|
134
|
-
if
|
|
135
|
-
|
|
179
|
+
if port_is_ours; then
|
|
180
|
+
if profile_released; then
|
|
181
|
+
echo "Chrome released its profile but left its process running (normal on macOS); ending it."
|
|
182
|
+
elif ! ls "$PROFILE" >/dev/null 2>&1; then
|
|
183
|
+
# Not evidence of a hung Chrome — we simply cannot look. It has had 10s
|
|
184
|
+
# since being asked to quit, which is ample for a release we cannot see.
|
|
185
|
+
echo "Cannot see ${PROFILE} from this app (macOS keeps Chrome's folder from it), so cannot confirm it was released; ending Chrome after 10s." >&2
|
|
186
|
+
else
|
|
187
|
+
echo "Chrome still held its profile after 10s; sending SIGKILL." >&2
|
|
188
|
+
fi
|
|
136
189
|
pkill -9 -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" 2>/dev/null || true
|
|
137
|
-
|
|
190
|
+
for _ in $(seq 1 20); do
|
|
191
|
+
port_is_ours || break
|
|
192
|
+
sleep 0.25
|
|
193
|
+
done
|
|
194
|
+
fi
|
|
195
|
+
if port_is_ours; then
|
|
196
|
+
echo "Error: Chrome on :${PORT} would not exit, even on SIGKILL. Not relaunching on top of it." >&2
|
|
197
|
+
exit 1
|
|
138
198
|
fi
|
|
139
199
|
# Chrome unregisters its bootstrap names and releases the port on the way out;
|
|
140
200
|
# relaunching before that finishes produces a second browser that cannot serve
|
|
@@ -142,6 +202,11 @@ if [ "$RESTART" = "1" ] && is_up; then
|
|
|
142
202
|
sleep 1
|
|
143
203
|
fi
|
|
144
204
|
|
|
205
|
+
if [ "$STOP_ONLY" = "1" ]; then
|
|
206
|
+
port_is_ours && { echo "Error: Chrome on :${PORT} is still running." >&2; exit 1; }
|
|
207
|
+
exit 0
|
|
208
|
+
fi
|
|
209
|
+
|
|
145
210
|
# A held port is the ONLY thing this branch establishes. It is emphatically not
|
|
146
211
|
# a health check: a Chrome that can no longer give a new tab a renderer keeps
|
|
147
212
|
# serving this port, answering /json/version and listing targets, while every
|
|
@@ -193,23 +258,64 @@ if [ -s "$LOG" ]; then
|
|
|
193
258
|
mv -f "$LOG" "${LOG}.prev" 2>/dev/null || true
|
|
194
259
|
fi
|
|
195
260
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
261
|
+
# On macOS, launch the .app through open(1), never by exec'ing the binary inside
|
|
262
|
+
# it. macOS protects an application's own data directory under
|
|
263
|
+
# ~/Library/Application Support, and the default profile lives under
|
|
264
|
+
# .../Google/Chrome. A process started from a terminal is refused there — for
|
|
265
|
+
# reads as well as writes — so a directly exec'd Chrome cannot even create its
|
|
266
|
+
# own SingletonLock and aborts with "Failed to create a ProcessSingleton for
|
|
267
|
+
# your profile directory". The message names the lock, so it reads as a stale
|
|
268
|
+
# lock from a crashed Chrome; it is not. Measured 2026-09-18 on Darwin 27.0.0
|
|
269
|
+
# with Chrome 153: the profile dir was mode 0700, owned by the user, carried no
|
|
270
|
+
# BSD flags and held no Singleton* files, while ~/Library/Application Support
|
|
271
|
+
# and .../Google both accepted writes from the same shell. LaunchServices gives
|
|
272
|
+
# Chrome its own identity, and the same binary, profile and flags then start.
|
|
273
|
+
#
|
|
274
|
+
# -n: a new instance even when the user's everyday Chrome is running.
|
|
275
|
+
# -g: do not bring it to the front. Chrome's stdout/stderr still reach $LOG via
|
|
276
|
+
# --stdout/--stderr (a healthy start writes "DevTools listening on ws://…").
|
|
277
|
+
app_bundle_of() {
|
|
278
|
+
case "$1" in
|
|
279
|
+
*.app/Contents/MacOS/*) printf '%s.app\n' "${1%%.app/Contents/MacOS/*}" ;;
|
|
280
|
+
*) return 1 ;;
|
|
281
|
+
esac
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
CHROME_FLAGS=(
|
|
285
|
+
--remote-debugging-port="$PORT"
|
|
286
|
+
--user-data-dir="$PROFILE"
|
|
287
|
+
--no-first-run
|
|
288
|
+
--no-default-browser-check
|
|
289
|
+
'about:blank'
|
|
290
|
+
)
|
|
291
|
+
if [ "$(uname -s)" = "Darwin" ] && APP="$(app_bundle_of "$CHROME")"; then
|
|
292
|
+
open -n -g -a "$APP" --stdout "$LOG" --stderr "$LOG" --args "${CHROME_FLAGS[@]}"
|
|
293
|
+
else
|
|
294
|
+
nohup "$CHROME" "${CHROME_FLAGS[@]}" >"$LOG" 2>&1 &
|
|
295
|
+
disown
|
|
296
|
+
fi
|
|
203
297
|
|
|
204
|
-
# Wait
|
|
205
|
-
|
|
298
|
+
# Wait for CDP so the caller can attach immediately. A cold start against a
|
|
299
|
+
# long-lived profile (extensions, logins, restored session) measured 10.6s and
|
|
300
|
+
# 16.4s through open(1), so a 5s window reported failure over a browser that
|
|
301
|
+
# was still coming up. The elapsed time is printed so a window that is too
|
|
302
|
+
# short again is visible rather than guessed at.
|
|
303
|
+
START="$(date +%s)"
|
|
304
|
+
for _ in $(seq 1 240); do
|
|
206
305
|
if is_up; then
|
|
207
|
-
echo "Chrome launched on :${PORT} (profile: ${PROFILE}, log: ${LOG})"
|
|
306
|
+
echo "Chrome launched on :${PORT} in $(( $(date +%s) - START ))s (profile: ${PROFILE}, log: ${LOG})"
|
|
208
307
|
echo "Drive it with: browser-automation goto -s <session> <url>"
|
|
209
308
|
exit 0
|
|
210
309
|
fi
|
|
211
310
|
sleep 0.25
|
|
212
311
|
done
|
|
213
312
|
|
|
214
|
-
echo "Error: Chrome did not
|
|
313
|
+
echo "Error: Chrome did not serve CDP on :${PORT} within 60s. Last lines of ${LOG}:" >&2
|
|
314
|
+
tail -n 8 "$LOG" 2>/dev/null | sed 's/^/ /' >&2
|
|
315
|
+
if grep -qE 'Failed to create a ProcessSingleton|SingletonLock: Operation not permitted' "$LOG" 2>/dev/null; then
|
|
316
|
+
echo "" >&2
|
|
317
|
+
echo "macOS refused this Chrome its own profile directory — not a stale lock." >&2
|
|
318
|
+
echo "Chrome was exec'd directly rather than launched through open(1); see the" >&2
|
|
319
|
+
echo "comment above app_bundle_of in this script." >&2
|
|
320
|
+
fi
|
|
215
321
|
exit 1
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -36,9 +36,16 @@ file under `~/.browser-automation/sessions/`.
|
|
|
36
36
|
Bind a name to an already-open tab with `bind -s name -m <substr>`. Parallel
|
|
37
37
|
Claude Code sessions stay isolated by *convention* — each drives its own tab
|
|
38
38
|
(its own `-s` name or `-m` match) — but any tab is reachable on demand.
|
|
39
|
-
- **No focus stealing.** New tabs are created in the
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
- **No focus stealing — unless you ask for it.** New tabs are created in the
|
|
40
|
+
background, and nothing fronts a tab as a side effect of ordinary driving:
|
|
41
|
+
`goto`, `read`, `snapshot`, `fill`, `eval`, `screenshot` all leave your
|
|
42
|
+
frontmost app alone. Three things deliberately do more, and only these:
|
|
43
|
+
`focus` (emulates focus/visibility in the renderer — still **no window
|
|
44
|
+
moves**), `click --trusted` and `drop` (force-front the tab, because CDP input
|
|
45
|
+
grants no user activation to a renderer that considers itself hidden), and
|
|
46
|
+
`focus --raise`, which calls `Target.activateTarget` and **genuinely takes the
|
|
47
|
+
operator's screen**. `--raise` is the only one that does; reach for plain
|
|
48
|
+
`focus` unless a person needs to see the tab.
|
|
42
49
|
- **Self-healing.** If the tab was closed (or Chrome restarted and reissued
|
|
43
50
|
targetIds), the next `goto` just opens a fresh background tab for that session.
|
|
44
51
|
- **Refs live in the DOM.** `snapshot` stamps `data-ba-ref="e7"` onto each
|
|
@@ -78,6 +85,34 @@ one of those; run `doctor`, which is the same probe.** Override the profile path
|
|
|
78
85
|
with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
|
|
79
86
|
`BROWSER_AUTOMATION_CDP=http://localhost:PORT` if needed.
|
|
80
87
|
|
|
88
|
+
**The profile lives in `~/.browser-automation/chrome-profile`** (`browser-automation
|
|
89
|
+
profile` prints it). Older CLIs kept it inside Chrome's own folder,
|
|
90
|
+
`~/Library/Application Support/Google/Chrome/browser-automation`, and `launch` moves
|
|
91
|
+
it out the first time it can — logins included; the move is a single rename and
|
|
92
|
+
Chrome's cookie key lives in the Keychain, not in the path. To move it on demand:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
browser-automation profile --migrate # refuses, changing nothing, if a Chrome has it open
|
|
96
|
+
browser-automation launch --restart # quits Chrome first, then moves it and relaunches
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Why it moved: macOS decides access to Chrome's folder per HOST app.** A session
|
|
100
|
+
started from a terminal that was once allowed reaches it; one started by an app
|
|
101
|
+
that was not — Clerk.AI, denied in 2026-08 and silently refused ever since — gets
|
|
102
|
+
`EPERM`, and Chrome dies with
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
Failed to create …/browser-automation/SingletonLock: Operation not permitted (1)
|
|
106
|
+
Failed to create a ProcessSingleton for your profile directory. … Aborting now
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**That is not a stale lock**, and there is no lock file to delete. It is also why
|
|
110
|
+
the same command works from your terminal and fails from an app. ⛔ **Do not work
|
|
111
|
+
around it with a scratch `--user-data-dir` or `BROWSER_AUTOMATION_PROFILE` pointed
|
|
112
|
+
at an empty folder**: Chrome starts, and the person is signed out of every site in
|
|
113
|
+
the real profile. Run `browser-automation profile --migrate` once from a terminal
|
|
114
|
+
that can reach the old folder; every host reaches the new one.
|
|
115
|
+
|
|
81
116
|
## Commands
|
|
82
117
|
|
|
83
118
|
Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, else
|
|
@@ -87,6 +122,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
87
122
|
|---|---|
|
|
88
123
|
| Start the Chrome + verify it can make renderers | `browser-automation launch` |
|
|
89
124
|
| Diagnose setup (incl. renderer capacity) | `browser-automation doctor` |
|
|
125
|
+
| Where the Chrome profile lives / move it out of Chrome's folder | `browser-automation profile` / `profile --migrate` |
|
|
90
126
|
| List sessions + every open tab (id, title, url) | `browser-automation list` |
|
|
91
127
|
| Open a background tab | `browser-automation new -s work [url]` |
|
|
92
128
|
| Navigate (session tab created if needed) | `browser-automation goto -s work https://example.com` |
|
|
@@ -103,6 +139,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
103
139
|
| Drop file(s) onto a drag-and-drop zone | `browser-automation drop -m app e7 ~/Desktop/clip.mp4` (add `--js` for a synthetic drop) |
|
|
104
140
|
| Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
|
|
105
141
|
| Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
|
|
142
|
+
| Make a hidden tab render (charts, video, polling) | `browser-automation focus -s work` (add `--raise` to really front it) |
|
|
106
143
|
| Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
|
|
107
144
|
| Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
|
|
108
145
|
| Forget a session (tab stays open) | `browser-automation close -s work` |
|
|
@@ -172,6 +209,22 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
172
209
|
no `name`** (Viking Line's booking selectors — the visible fields are display
|
|
173
210
|
shells; the real state lives in the framework, so `fill` and DOM value-setting
|
|
174
211
|
do nothing at all).
|
|
212
|
+
- **There is NO way to send real keystrokes, and `fill --native` is not one.** `--native` uses CDP
|
|
213
|
+
`Input.insertText`, which fires `beforeinput`/`input` but **never `keydown`**. A combobox that
|
|
214
|
+
filters its list on keystrokes therefore stays empty: the value lands in the DOM and no options
|
|
215
|
+
ever render. npm’s "Select packages and scopes" picker is the canonical case (2026-08-22) — the
|
|
216
|
+
field showed `generativereality` and the list stayed blank through `fill`, `fill --native`, and a
|
|
217
|
+
React native-setter `eval`. There is no `press` or `type` command to escalate to.
|
|
218
|
+
⇒ Drop to raw CDP on the tab’s `webSocketDebuggerUrl` and dispatch `Input.dispatchKeyEvent`
|
|
219
|
+
per character. Two traps, both hit:
|
|
220
|
+
**(1) `keyDown` carrying `text` already inserts the character** — sending a `char` event as well
|
|
221
|
+
types everything twice (`ggeenneerraattiivvee…`), which reads as a flaky page rather than a double
|
|
222
|
+
dispatch. Send `keyDown` + `keyUp` only.
|
|
223
|
+
**(2) Clear with real Backspaces, not select-all+Delete.** A value written by a JS setter is
|
|
224
|
+
invisible to the component’s own state, so the framework keeps the old string and you end up
|
|
225
|
+
appending to it. Backspacing drives the same path a person would.
|
|
226
|
+
Also: the dropdown must actually be **open** first — typing into a collapsed picker’s hidden input
|
|
227
|
+
does nothing, and looks identical to the events not landing.
|
|
175
228
|
**Do NOT hand-roll a raw-CDP trusted click.** Burned 2026-08-22: wrote a
|
|
176
229
|
bespoke `Input.dispatchMouseEvent` helper for exactly this, and it clicked
|
|
177
230
|
stale coordinates (the panel had animated in) — `--trusted` already solves that
|
|
@@ -421,9 +474,15 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
421
474
|
process helps; closing tabs does not, and plain `launch` will not either (idempotent by
|
|
422
475
|
design — it sees a live browser and exits happy):
|
|
423
476
|
```bash
|
|
424
|
-
browser-automation launch --restart #
|
|
477
|
+
browser-automation launch --restart # quit (CDP, then SIGTERM), wait for the profile, relaunch
|
|
425
478
|
```
|
|
426
|
-
It reports how many tabs it is about to close.
|
|
479
|
+
It reports how many tabs it is about to close. `Chrome released its profile but left its
|
|
480
|
+
process running (normal on macOS); ending it.` is the **expected** line, not a fault: on
|
|
481
|
+
macOS 27 / Chrome 153 the browser process never exits on its own after quitting, but it
|
|
482
|
+
does flush and release the profile first, and that release is what the restart waits for.
|
|
483
|
+
(Older CLIs waited only for the port to close and relaunched on top of the still-running
|
|
484
|
+
Chrome — two browsers on one profile. If you see `Chrome did not exit on SIGTERM`, or no
|
|
485
|
+
such line and then odd profile errors, you are on one of those.) **Those tabs belong to every parallel
|
|
427
486
|
Claude Code session sharing this Chrome — ask Fred first, never restart unilaterally.**
|
|
428
487
|
|
|
429
488
|
**Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
|
|
@@ -458,10 +517,20 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
458
517
|
stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
|
|
459
518
|
backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
|
|
460
519
|
painted text — so never read `hidden` alone as a diagnosis.
|
|
461
|
-
**Fix:**
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
520
|
+
**Fix:** make the tab report itself visible.
|
|
521
|
+
```bash
|
|
522
|
+
browser-automation focus -s x # quiet: no window moves, you keep your frontmost app
|
|
523
|
+
```
|
|
524
|
+
`focus` emulates focus + visibility in the renderer, then **reads back what it actually
|
|
525
|
+
achieved** rather than reporting that it sent the command — so a partial result says which half
|
|
526
|
+
is missing instead of printing a tick over it. The page paints immediately. Add `--raise` only
|
|
527
|
+
when a *person* needs to see the tab: that genuinely fronts it and **takes the operator's
|
|
528
|
+
screen**, which is exactly what you normally want to avoid.
|
|
529
|
+
Same root cause as the WebAuthn note above, different symptom: that one refuses, this one
|
|
530
|
+
silently never renders.
|
|
531
|
+
*(Older CLIs had no `focus`; the workaround was a `click --trusted` on a harmless wrapper `div`,
|
|
532
|
+
which fronted the tab as a side effect of needing trusted input. Prefer `focus` — it says what it
|
|
533
|
+
achieved, and it does not click anything.)*
|
|
465
534
|
|
|
466
535
|
**Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
|
|
467
536
|
isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
|
|
@@ -473,7 +542,7 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
473
542
|
| `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
|
|
474
543
|
| scope | that one tab | **every** new tab / cross-origin nav |
|
|
475
544
|
| `doctor` | `✓ Renderer capacity` | names the wedge + pid |
|
|
476
|
-
| fix | `
|
|
545
|
+
| fix | `focus` on the tab | `launch --restart` (**ask first**) |
|
|
477
546
|
|
|
478
547
|
`eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
|
|
479
548
|
painting case. If it times out, stop poking the page and run `doctor`.
|
|
@@ -549,6 +618,26 @@ working around it forever**:
|
|
|
549
618
|
If it says the port is held by ANOTHER user, that is not your Chrome and
|
|
550
619
|
driving it would act in their session — quit Chrome in that account, or set
|
|
551
620
|
`BROWSER_AUTOMATION_PORT`.
|
|
621
|
+
- **`SingletonLock: Operation not permitted` / "Failed to create a ProcessSingleton"**
|
|
622
|
+
→ macOS refused the app this session runs under access to **Chrome's** folder,
|
|
623
|
+
where old CLIs kept the profile (see Setup). Not a stale lock; do not delete
|
|
624
|
+
anything. Upgrade the CLI (`npm install -g @generativereality/browser-automation@latest`)
|
|
625
|
+
and `launch` again: current versions start Chrome through `open(1)`, under
|
|
626
|
+
Chrome's own identity, so it opens its folder whatever app you run under, and
|
|
627
|
+
they move the profile to `~/.browser-automation/` when they can.
|
|
628
|
+
|
|
629
|
+
**What to tell the person — and what NOT to.** ⛔ **Do not ask them to grant
|
|
630
|
+
Full Disk Access** (to the app, to the terminal, to anything). It does work, and
|
|
631
|
+
it hands that app every file on the Mac to fix a problem that needs none of it:
|
|
632
|
+
an agent in Mind My Money said exactly that on 2026-09 — *"let Mind My Money
|
|
633
|
+
reach that folder. Full Disk Access does it, but it also opens far more than
|
|
634
|
+
Chrome"* — when the real fix was a CLI upgrade. Also do not suggest a fresh
|
|
635
|
+
profile or `BROWSER_AUTOMATION_PROFILE` pointed at an empty folder: that signs
|
|
636
|
+
them out of every bank and portal. If `launch` still reports `Profile not moved`
|
|
637
|
+
after upgrading, the browser works anyway (the old folder is still used); the
|
|
638
|
+
one-time move needs a host macOS allows into Chrome's folder, so the ask is small
|
|
639
|
+
and exact: *open Terminal and run `browser-automation profile --migrate`; if macOS
|
|
640
|
+
asks whether Terminal may access data from other apps, allow it.*
|
|
552
641
|
- **`command not found: browser-automation`** → `npm install -g @generativereality/browser-automation`.
|
|
553
642
|
- **Chrome was restarted** → nothing to do; the next `goto` recreates the
|
|
554
643
|
session's tab automatically (sessions self-heal; `list` shows `stale`).
|