@generativereality/browser-automation 0.4.11 → 0.4.13
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 +1 -0
- package/dist/index.js +723 -197
- package/package.json +1 -1
- package/scripts/launch-chrome.sh +13 -4
- package/skills/browser/SKILL.md +90 -18
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.13",
|
|
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
|
@@ -11,10 +11,19 @@
|
|
|
11
11
|
# A browser process can permanently lose the ability to launch renderers (see
|
|
12
12
|
# src/core/renderer-health.ts for the mechanism). Every existing tab keeps
|
|
13
13
|
# working, so the browser looks fine, but no new tab or cross-origin
|
|
14
|
-
# navigation ever will again. Restarting is the
|
|
15
|
-
# `launch` cannot do it, because it is idempotent by
|
|
16
|
-
# reports "already running". Without an explicit flag the
|
|
17
|
-
# go and kill Chrome by hand, which is how a diagnosis
|
|
14
|
+
# navigation ever will again. Restarting is the only recovery FROM THAT ONE
|
|
15
|
+
# CONDITION — and plain `launch` cannot do it, because it is idempotent by
|
|
16
|
+
# design and correctly reports "already running". Without an explicit flag the
|
|
17
|
+
# only way out was to go and kill Chrome by hand, which is how a diagnosis
|
|
18
|
+
# ends up unactionable.
|
|
19
|
+
#
|
|
20
|
+
# It is a flag and not an automatic step because it closes every tab of every
|
|
21
|
+
# session sharing this browser. That condition is confirmed by ONE thing: the
|
|
22
|
+
# Mach bootstrap name being absent from `launchctl print gui/$UID`. A new tab
|
|
23
|
+
# whose renderer is merely slow to answer looks identical and is not it — for
|
|
24
|
+
# three weeks it was reported as it, and restarting for it twice destroyed
|
|
25
|
+
# another session's unrecoverable work. `browser-automation doctor` now prints
|
|
26
|
+
# which of the two it is; nothing here can tell them apart.
|
|
18
27
|
#
|
|
19
28
|
# Why this script exists:
|
|
20
29
|
# The `browser-automation` skill prefers to drive a real, persistent Chrome
|
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
|
|
@@ -103,8 +110,9 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
103
110
|
| 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
111
|
| Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
|
|
105
112
|
| Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
|
|
113
|
+
| Make a hidden tab render (charts, video, polling) | `browser-automation focus -s work` (add `--raise` to really front it) |
|
|
106
114
|
| Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
|
|
107
|
-
| Restart Chrome (
|
|
115
|
+
| Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
|
|
108
116
|
| Forget a session (tab stays open) | `browser-automation close -s work` |
|
|
109
117
|
| Forget **and** close the browser tab | `browser-automation close -s work --tab` |
|
|
110
118
|
|
|
@@ -287,11 +295,49 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
287
295
|
isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
|
|
288
296
|
confirm processing started, then grab the result (often a download endpoint you
|
|
289
297
|
can pull with `download --url`).
|
|
298
|
+
- **A NEW tab's renderer can be slow rather than broken — do not restart Chrome for it.**
|
|
299
|
+
⚠️ **Read this before acting on the wedge diagnosis below.** Measured 2026-09-11 on
|
|
300
|
+
Chrome 152.0.7977.83, time from `Target.createTarget` to the first `Runtime.evaluate`
|
|
301
|
+
returning, 8 trials each:
|
|
302
|
+
|
|
303
|
+
| how the target was created | median | worst |
|
|
304
|
+
|---|---|---|
|
|
305
|
+
| `background: true` (how this tool opens every tab) | 367ms | 12517ms, and >30s once |
|
|
306
|
+
| `background: true` + `Target.activateTarget` | 19ms | 65ms |
|
|
307
|
+
| `background: false` | 18ms | 22ms |
|
|
308
|
+
|
|
309
|
+
The renderer **process exists** in every arm — `ps` gains a `--type=renderer` child either
|
|
310
|
+
way. A background target is simply not given a renderer that answers promptly, and on a
|
|
311
|
+
loaded machine (this one was at load average 38) the tail runs past any budget worth
|
|
312
|
+
waiting. **This is not the wedge**, and a restart does nothing for it.
|
|
313
|
+
|
|
314
|
+
It cost real work to learn: for three weeks `goto` reported this as the permanent,
|
|
315
|
+
restart-only condition below, and `launch --restart` closes every tab of every session
|
|
316
|
+
sharing this Chrome. It twice destroyed unrecoverable work belonging to another session —
|
|
317
|
+
a finished AlternativeTo submission with hand edits, and an Azure signup flow mid-form.
|
|
318
|
+
|
|
319
|
+
**Since fixed (v0.4.12+):** `new`/`goto` wait for a late renderer and, if it still has not
|
|
320
|
+
answered, briefly activate the tab to force one and hand the window straight back (you get
|
|
321
|
+
a `WARN` saying so). The probe retries with a doubling budget, and the verdict now names
|
|
322
|
+
the permanent failure **only when its own signature is present**. On an older CLI, the
|
|
323
|
+
cheap move is to retry, or to drive a tab that already works.
|
|
324
|
+
|
|
325
|
+
**Whatever the version: before restarting anything, check the two corroborations.** Both
|
|
326
|
+
were decisive and neither used to be consulted:
|
|
327
|
+
```bash
|
|
328
|
+
launchctl print "gui/$(id -u)" | grep MachPortRendezvousServer.<browser-pid>
|
|
329
|
+
ps -Ao command= | grep -c -- '--type=renderer'
|
|
330
|
+
```
|
|
331
|
+
Mach name **present** + renderers **alive** ⇒ this is slowness, not the wedge. Retry, or use
|
|
332
|
+
a live tab. Mach name **absent** ⇒ it is the wedge, and only then is a restart the answer.
|
|
333
|
+
|
|
290
334
|
- **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
|
|
291
335
|
A browser process can permanently lose the ability to launch **renderer processes** while
|
|
292
336
|
looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
|
|
293
337
|
until you open a tab or navigate somewhere new, and then the errors read as the remote site's
|
|
294
338
|
doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
|
|
339
|
+
⚠️ **This is a real condition and a rare one.** Confirm the Mach name is absent (above)
|
|
340
|
+
before you believe it — a slow background renderer produces every symptom in this list.
|
|
295
341
|
|
|
296
342
|
How it shows up:
|
|
297
343
|
- `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
|
|
@@ -366,18 +412,34 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
366
412
|
`Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
|
|
367
413
|
site's bot-protection docs.
|
|
368
414
|
|
|
369
|
-
**Recovery —
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
415
|
+
**Recovery — cheapest first, and a restart only once the Mach name is confirmed absent.**
|
|
416
|
+
|
|
417
|
+
1. **Retry.** A new tab's renderer has been measured taking 12s and more on a loaded
|
|
418
|
+
machine, and late is not broken.
|
|
419
|
+
2. **Drive a tab that already works.** An existing tab navigates same-origin without
|
|
420
|
+
needing a new renderer, so it keeps working throughout even during a genuine wedge:
|
|
421
|
+
```bash
|
|
422
|
+
browser-automation list
|
|
423
|
+
browser-automation eval -t <id> "location.href='<url>'"
|
|
424
|
+
```
|
|
425
|
+
3. **`browser-automation doctor`** — re-measures, prints the two corroborations, and shows
|
|
426
|
+
the recent probe-time distribution from `~/.browser-automation/renderer-probes.jsonl`.
|
|
427
|
+
4. **Only if `doctor` reports the Mach rendezvous service ABSENT**, restart. The bootstrap
|
|
428
|
+
name is registered at startup and never re-registered, so nothing short of a new browser
|
|
429
|
+
process helps; closing tabs does not, and plain `launch` will not either (idempotent by
|
|
430
|
+
design — it sees a live browser and exits happy):
|
|
431
|
+
```bash
|
|
432
|
+
browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
|
|
433
|
+
```
|
|
434
|
+
It reports how many tabs it is about to close. **Those tabs belong to every parallel
|
|
435
|
+
Claude Code session sharing this Chrome — ask Fred first, never restart unilaterally.**
|
|
377
436
|
|
|
378
437
|
**Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
|
|
379
438
|
(they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
|
|
380
|
-
closes tabs whose renderer does not answer. Use `--dry` first.
|
|
439
|
+
closes tabs whose renderer does not answer. Use `--dry` first. `list` now counts stale
|
|
440
|
+
bookmarks instead of printing them (`list --all` to see them) — 105 stale lines above a
|
|
441
|
+
24-tab Chrome is how "there are a hundred tabs open" became the leading theory for a
|
|
442
|
+
renderer failure that has nothing to do with tab count. It is genuinely useful, but it is
|
|
381
443
|
**not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
|
|
382
444
|
— tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
|
|
383
445
|
nobody wants it.
|
|
@@ -404,10 +466,20 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
404
466
|
stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
|
|
405
467
|
backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
|
|
406
468
|
painted text — so never read `hidden` alone as a diagnosis.
|
|
407
|
-
**Fix:**
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
469
|
+
**Fix:** make the tab report itself visible.
|
|
470
|
+
```bash
|
|
471
|
+
browser-automation focus -s x # quiet: no window moves, you keep your frontmost app
|
|
472
|
+
```
|
|
473
|
+
`focus` emulates focus + visibility in the renderer, then **reads back what it actually
|
|
474
|
+
achieved** rather than reporting that it sent the command — so a partial result says which half
|
|
475
|
+
is missing instead of printing a tick over it. The page paints immediately. Add `--raise` only
|
|
476
|
+
when a *person* needs to see the tab: that genuinely fronts it and **takes the operator's
|
|
477
|
+
screen**, which is exactly what you normally want to avoid.
|
|
478
|
+
Same root cause as the WebAuthn note above, different symptom: that one refuses, this one
|
|
479
|
+
silently never renders.
|
|
480
|
+
*(Older CLIs had no `focus`; the workaround was a `click --trusted` on a harmless wrapper `div`,
|
|
481
|
+
which fronted the tab as a side effect of needing trusted input. Prefer `focus` — it says what it
|
|
482
|
+
achieved, and it does not click anything.)*
|
|
411
483
|
|
|
412
484
|
**Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
|
|
413
485
|
isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
|
|
@@ -419,7 +491,7 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
419
491
|
| `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
|
|
420
492
|
| scope | that one tab | **every** new tab / cross-origin nav |
|
|
421
493
|
| `doctor` | `✓ Renderer capacity` | names the wedge + pid |
|
|
422
|
-
| fix | `
|
|
494
|
+
| fix | `focus` on the tab | `launch --restart` (**ask first**) |
|
|
423
495
|
|
|
424
496
|
`eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
|
|
425
497
|
painting case. If it times out, stop poking the page and run `doctor`.
|