@generativereality/browser-automation 0.4.10 → 0.4.11
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/dist/index.js +37 -13
- package/package.json +2 -2
- package/scripts/launch-chrome.sh +15 -3
- package/skills/browser/SKILL.md +74 -5
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "browser-automation",
|
|
3
3
|
"description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
4
|
-
"version": "0.4.
|
|
4
|
+
"version": "0.4.11",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,7 @@ import { execFileSync, spawnSync } from "node:child_process";
|
|
|
9
9
|
import { fileURLToPath } from "node:url";
|
|
10
10
|
//#region package.json
|
|
11
11
|
var name = "@generativereality/browser-automation";
|
|
12
|
-
var version = "0.4.
|
|
12
|
+
var version = "0.4.11";
|
|
13
13
|
var 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.";
|
|
14
14
|
var package_default = {
|
|
15
15
|
name,
|
|
@@ -29,7 +29,7 @@ var package_default = {
|
|
|
29
29
|
"typecheck": "tsc --noEmit",
|
|
30
30
|
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
|
|
31
31
|
"test": "node --test \"test/**/*.test.mjs\"",
|
|
32
|
-
"release": "
|
|
32
|
+
"release": "echo 'Releases publish from CI, not here. Bump package.json + .claude-plugin/plugin.json, commit onto master, then: git tag vX.Y.Z && git push origin vX.Y.Z — then approve the gated job in GitHub Actions. `npm publish` from a laptop 404s (granular token). See .github/workflows/release.yml.' >&2; exit 1",
|
|
33
33
|
"sync-plugin": "bash scripts/sync-plugin.sh",
|
|
34
34
|
"prepack": "npm run build"
|
|
35
35
|
},
|
|
@@ -361,22 +361,32 @@ async function forceForeground(s) {
|
|
|
361
361
|
await s.send("Page.setWebLifecycleState", { state: "active" }).catch(() => {});
|
|
362
362
|
}
|
|
363
363
|
/** Run `fn` against the browser-level endpoint (Target.* commands), then close. */
|
|
364
|
-
async function withBrowser(fn) {
|
|
365
|
-
const s = await connect(await browserWsUrl());
|
|
364
|
+
async function withBrowser(fn, timeout) {
|
|
365
|
+
const s = await connect(await browserWsUrl(), timeout === void 0 ? void 0 : { timeout });
|
|
366
366
|
try {
|
|
367
367
|
return await fn(s);
|
|
368
368
|
} finally {
|
|
369
369
|
s.close();
|
|
370
370
|
}
|
|
371
371
|
}
|
|
372
|
-
/**
|
|
373
|
-
|
|
372
|
+
/**
|
|
373
|
+
* Create a new tab in the BACKGROUND (never steals focus) -> returns targetId.
|
|
374
|
+
*
|
|
375
|
+
* `timeout` exists for the health probe. On a browser that has lost the ability
|
|
376
|
+
* to make renderers, `Target.createTarget` itself can hang rather than fail, so
|
|
377
|
+
* a caller that means to spend ~100ms deciding whether the browser works would
|
|
378
|
+
* otherwise sit on the default 30s — measured 2026-09-07, when this put a 30s
|
|
379
|
+
* stall in front of every `launch` on a wedged Chrome. Ordinary callers pass
|
|
380
|
+
* nothing and keep the generous default, which is right for them: a real tab
|
|
381
|
+
* opening slowly should still open.
|
|
382
|
+
*/
|
|
383
|
+
async function createTab(url = "about:blank", { timeout } = {}) {
|
|
374
384
|
return withBrowser(async (s) => {
|
|
375
385
|
return (await s.send("Target.createTarget", {
|
|
376
386
|
url,
|
|
377
387
|
background: true
|
|
378
|
-
})).targetId;
|
|
379
|
-
});
|
|
388
|
+
}, timeout)).targetId;
|
|
389
|
+
}, timeout);
|
|
380
390
|
}
|
|
381
391
|
async function closeTab(targetId) {
|
|
382
392
|
return withBrowser(async (s) => {
|
|
@@ -482,7 +492,7 @@ async function probeRenderer({ timeout = 5e3 } = {}) {
|
|
|
482
492
|
} catch {}
|
|
483
493
|
let targetId;
|
|
484
494
|
try {
|
|
485
|
-
targetId = await createTab("about:blank");
|
|
495
|
+
targetId = await createTab("about:blank", { timeout });
|
|
486
496
|
} catch (e) {
|
|
487
497
|
return {
|
|
488
498
|
ok: false,
|
|
@@ -616,7 +626,7 @@ function explainRendererFailure(h) {
|
|
|
616
626
|
];
|
|
617
627
|
if (rendezvous === false) lines.push(` root cause: the browser process (pid ${pid}) has lost its Mach bootstrap`, ` service "com.google.Chrome.MachPortRendezvousServer.${pid}".`, ` Chrome registers that name once, at startup; every child`, ` process looks it up to receive its shared memory. With the`, ` name gone, every renderer Chrome launches immediately exits.`, ` This is permanent for this browser process.`);
|
|
618
628
|
else if (rendezvous === true) lines.push(` note: the Mach rendezvous service for pid ${pid} IS still registered,`, ` so this is a different renderer failure from the one seen on`, ` 2026-08-22. Chrome's own log will say why:`, ` tail -50 ${chromeLogPath()}`);
|
|
619
|
-
lines.push(``, `This is a browser-level failure. It is NOT the site blocking automation, and`, `retrying, changing the URL, or adding a user agent will not help. Two tells:`, `same-origin navigations in tabs that already work keep working (they reuse a`, `renderer that already exists), and cross-origin ones fail with ERR_ABORTED`, `(site isolation needs a new renderer, which is the thing Chrome can't do).`, ``, `Recovery: restart Chrome. Nothing else clears it — closing tabs does not,`, `and plain \`launch\` will not either (it
|
|
629
|
+
lines.push(``, `This is a browser-level failure. It is NOT the site blocking automation, and`, `retrying, changing the URL, or adding a user agent will not help. Two tells:`, `same-origin navigations in tabs that already work keep working (they reuse a`, `renderer that already exists), and cross-origin ones fail with ERR_ABORTED`, `(site isolation needs a new renderer, which is the thing Chrome can't do).`, ``, `Recovery: restart Chrome. Nothing else clears it — closing tabs does not,`, `and plain \`launch\` will not either: it now DETECTS this (it runs this same`, `probe and fails), but it will never restart a browser other sessions may be`, `using without being told to. Restarting is always something you type.`, ``, ` browser-automation launch --restart # closes ALL tabs, then relaunches`, ``, `If other sessions are driving this Chrome, agree on the restart first — their`, `open tabs go with it. \`browser-automation list\` shows who holds what.`);
|
|
620
630
|
return lines.join("\n");
|
|
621
631
|
}
|
|
622
632
|
/**
|
|
@@ -2129,11 +2139,11 @@ function launchScriptPath() {
|
|
|
2129
2139
|
//#region src/commands/launch.ts
|
|
2130
2140
|
const launchCommand = define({
|
|
2131
2141
|
name: "launch",
|
|
2132
|
-
description: "Start (idempotent) this user's headed Chrome with the persistent profile",
|
|
2142
|
+
description: "Start (idempotent) this user's headed Chrome with the persistent profile, and verify it can still make renderers",
|
|
2133
2143
|
args: {
|
|
2134
2144
|
status: {
|
|
2135
2145
|
type: "boolean",
|
|
2136
|
-
description: "Only report whether the CDP browser is up (exit 0/1)"
|
|
2146
|
+
description: "Only report whether the CDP browser is up (exit 0/1) — reachability, not health"
|
|
2137
2147
|
},
|
|
2138
2148
|
restart: {
|
|
2139
2149
|
type: "boolean",
|
|
@@ -2152,7 +2162,21 @@ const launchCommand = define({
|
|
|
2152
2162
|
...ctx.values.status ? ["--status"] : [],
|
|
2153
2163
|
...ctx.values.restart ? ["--restart"] : []
|
|
2154
2164
|
]], { stdio: "inherit" });
|
|
2155
|
-
process.exit(r.status ?? 1);
|
|
2165
|
+
if (r.status !== 0 || ctx.values.status) process.exit(r.status ?? 1);
|
|
2166
|
+
const health = await probeRenderer().catch((e) => ({
|
|
2167
|
+
ok: false,
|
|
2168
|
+
ms: 0,
|
|
2169
|
+
pageTargets: 0,
|
|
2170
|
+
reason: String(e?.message ?? e)
|
|
2171
|
+
}));
|
|
2172
|
+
if (health.ok) {
|
|
2173
|
+
consola.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.`);
|
|
2174
|
+
return;
|
|
2175
|
+
}
|
|
2176
|
+
consola.error("Chrome is up, but it cannot make renderers — this browser is unusable.\n");
|
|
2177
|
+
for (const line of explainRendererFailure(health).split("\n")) consola.log(line);
|
|
2178
|
+
consola.log(`\nChrome's own log: ${chromeLogPath()}`);
|
|
2179
|
+
process.exit(1);
|
|
2156
2180
|
}
|
|
2157
2181
|
});
|
|
2158
2182
|
//#endregion
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.11",
|
|
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": {
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"typecheck": "tsc --noEmit",
|
|
19
19
|
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
|
|
20
20
|
"test": "node --test \"test/**/*.test.mjs\"",
|
|
21
|
-
"release": "
|
|
21
|
+
"release": "echo 'Releases publish from CI, not here. Bump package.json + .claude-plugin/plugin.json, commit onto master, then: git tag vX.Y.Z && git push origin vX.Y.Z — then approve the gated job in GitHub Actions. `npm publish` from a laptop 404s (granular token). See .github/workflows/release.yml.' >&2; exit 1",
|
|
22
22
|
"sync-plugin": "bash scripts/sync-plugin.sh",
|
|
23
23
|
"prepack": "npm run build"
|
|
24
24
|
},
|
package/scripts/launch-chrome.sh
CHANGED
|
@@ -133,11 +133,23 @@ if [ "$RESTART" = "1" ] && is_up; then
|
|
|
133
133
|
sleep 1
|
|
134
134
|
fi
|
|
135
135
|
|
|
136
|
+
# A held port is the ONLY thing this branch establishes. It is emphatically not
|
|
137
|
+
# a health check: a Chrome that can no longer give a new tab a renderer keeps
|
|
138
|
+
# serving this port, answering /json/version and listing targets, while every
|
|
139
|
+
# goto fails. Only a round-trip through a renderer tells the two apart, and
|
|
140
|
+
# that lives in the CLI (src/core/renderer-health.ts) -- `browser-automation
|
|
141
|
+
# launch` runs it right after this script returns and prints the real verdict.
|
|
142
|
+
#
|
|
143
|
+
# This used to print a standing "use --restart if renderers are broken" hint
|
|
144
|
+
# here. It was correct advice and it did not work: printed on every launch,
|
|
145
|
+
# directly under the words "nothing to do", it read as boilerplate rather than
|
|
146
|
+
# as a diagnosis, and an operator burned many minutes on 25-30s `goto`s in
|
|
147
|
+
# 2026-09 without it registering. Advice that is always on screen carries no
|
|
148
|
+
# information. The verdict now appears only when it is true.
|
|
136
149
|
if is_up; then
|
|
137
|
-
echo "Already running on :${PORT} —
|
|
150
|
+
echo "Already running on :${PORT} — the port is held."
|
|
138
151
|
echo "Drive it with: browser-automation goto -s <session> <url>"
|
|
139
|
-
echo "(
|
|
140
|
-
echo " longer launch renderers — use: browser-automation launch --restart)"
|
|
152
|
+
echo "(Port held is not health. Check it works: browser-automation doctor)"
|
|
141
153
|
exit 0
|
|
142
154
|
fi
|
|
143
155
|
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -56,12 +56,26 @@ file under `~/.browser-automation/sessions/`.
|
|
|
56
56
|
|
|
57
57
|
```bash
|
|
58
58
|
npm install -g @generativereality/browser-automation
|
|
59
|
-
browser-automation launch # start
|
|
60
|
-
browser-automation doctor # verify Node, Chrome, targets, sessions
|
|
59
|
+
browser-automation launch # start Chrome, and prove it can still make renderers
|
|
60
|
+
browser-automation doctor # verify Node, Chrome, renderer capacity, targets, sessions
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
`launch` is idempotent — safe to call when Chrome is already up.
|
|
64
|
-
|
|
63
|
+
`launch` is idempotent — safe to call when Chrome is already up. **It also
|
|
64
|
+
verifies the browser works**, which is a different question from whether one is
|
|
65
|
+
running: it ends with either
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
✔ Renderer capacity: a new tab got a live renderer in 47ms — this Chrome works.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
or a non-zero exit and the full renderer-wedge diagnosis. That matters because a
|
|
72
|
+
held port, a `/json/version` that answers and a `list` full of targets are all
|
|
73
|
+
properties of the browser **process**, and the way a long-lived Chrome dies is
|
|
74
|
+
that it keeps all three while losing the ability to give any new tab a
|
|
75
|
+
**renderer** (see Gotchas). Older CLIs printed `nothing to do.` in exactly that
|
|
76
|
+
state — **if your `launch` ends without a `Renderer capacity:` line, you are on
|
|
77
|
+
one of those; run `doctor`, which is the same probe.** Override the profile path
|
|
78
|
+
with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
|
|
65
79
|
`BROWSER_AUTOMATION_CDP=http://localhost:PORT` if needed.
|
|
66
80
|
|
|
67
81
|
## Commands
|
|
@@ -71,7 +85,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
71
85
|
|
|
72
86
|
| Need | Command |
|
|
73
87
|
|---|---|
|
|
74
|
-
| Start
|
|
88
|
+
| Start the Chrome + verify it can make renderers | `browser-automation launch` |
|
|
75
89
|
| Diagnose setup (incl. renderer capacity) | `browser-automation doctor` |
|
|
76
90
|
| List sessions + every open tab (id, title, url) | `browser-automation list` |
|
|
77
91
|
| Open a background tab | `browser-automation new -s work [url]` |
|
|
@@ -291,6 +305,26 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
291
305
|
right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
|
|
292
306
|
`Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
|
|
293
307
|
|
|
308
|
+
**It gets SLOW before it fails outright — that is the early warning.** Observed 2026-09-07 on a
|
|
309
|
+
Chrome that had been up 12 days: every `goto` took ~25–30s, and a batch of three blew a 120s
|
|
310
|
+
timeout, hours before anything failed hard. That was misread as "large files, slow browser" and
|
|
311
|
+
worked around with longer timeouts for many minutes; the actual fix was one `launch --restart`,
|
|
312
|
+
after which the same pages loaded instantly and 14 `file://` tabs opened in two quick batches.
|
|
313
|
+
**A `goto` that has quietly become slow is this, not your page.** Raise the timeout at most once,
|
|
314
|
+
then run `doctor`.
|
|
315
|
+
|
|
316
|
+
**Every cheap signal stays green, so do not take any of them as health.** On that same wedged
|
|
317
|
+
browser: `launch` said `Already running on :9223 — nothing to do.`, `curl :9223/json/version`
|
|
318
|
+
answered normally, and `list` cheerfully returned 10 targets — while `goto` exited 1 and `eval`
|
|
319
|
+
died with `CDP Runtime.evaluate timed out after 30000ms`. Port held, HTTP endpoint answering and
|
|
320
|
+
targets listed are all properties of the **browser** process; the thing that is broken is its
|
|
321
|
+
ability to start a **renderer**, and only a probe that runs code in one can see it.
|
|
322
|
+
**Since fixed:** `launch` now runs that probe itself and exits non-zero with the diagnosis
|
|
323
|
+
instead of reporting "nothing to do", so this particular green-across-the-board trap is closed.
|
|
324
|
+
It still will not restart for you — that stays something you type, because the tabs are not
|
|
325
|
+
only yours. On a CLI old enough to lack it, `doctor` is the same probe; nothing cheaper
|
|
326
|
+
substitutes for either.
|
|
327
|
+
|
|
294
328
|
**The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
|
|
295
329
|
keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
|
|
296
330
|
restart):
|
|
@@ -354,6 +388,41 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
354
388
|
is a completely different client. Check the browser first: if `doctor` says renderer capacity is
|
|
355
389
|
fine and a boring cross-origin URL loads, *then* start suspecting the site.
|
|
356
390
|
|
|
391
|
+
- **A backgrounded tab may never paint at all — and `read`/`snapshot` will not tell you.** Distinct
|
|
392
|
+
from "still loading": `document.readyState` reaches `complete`, but the SPA never renders, so
|
|
393
|
+
`read` returns a stale shell (e.g. a bare "Loading") and `snapshot` lists none of the real
|
|
394
|
+
controls. The trap is that this looks exactly like *the page does not have that element*, and you
|
|
395
|
+
will go hunting for a different selector or conclude the flow changed. Measured 2026-09-02 on
|
|
396
|
+
Google's `accounts.google.com/v3/signin/challenge/pwd`: `readyState: "complete"`,
|
|
397
|
+
`body.innerText.length: 202` frozen on the previous step's text, and the password field present in
|
|
398
|
+
the DOM but `offsetParent === null` for as long as the tab stayed backgrounded.
|
|
399
|
+
**Diagnose** before changing your selector:
|
|
400
|
+
```bash
|
|
401
|
+
browser-automation eval -s x '({ready:document.readyState,vis:document.visibilityState,len:document.body.innerText.length})'
|
|
402
|
+
```
|
|
403
|
+
`visibilityState: "hidden"` with a **stuck `len`** is this, not a selector problem. Note the
|
|
404
|
+
stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
|
|
405
|
+
backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
|
|
406
|
+
painted text — so never read `hidden` alone as a diagnosis.
|
|
407
|
+
**Fix:** front the tab. There is no `activate` command — a `click --trusted` on any harmless
|
|
408
|
+
element (a wrapper `div` from the snapshot works; avoid submit buttons and links) brings the tab
|
|
409
|
+
to front and waits for it to be visible, and the page paints immediately. Same root cause as the
|
|
410
|
+
WebAuthn note above, different symptom: that one refuses, this one silently never renders.
|
|
411
|
+
|
|
412
|
+
**Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
|
|
413
|
+
isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
|
|
414
|
+
other closes every tab in the browser. What separates them:
|
|
415
|
+
|
|
416
|
+
| | backgrounded tab never paints | Chrome cannot make renderers |
|
|
417
|
+
|---|---|---|
|
|
418
|
+
| `goto` | succeeds, rc=0 (may be slow) | **rc=1**, or `Page.enable timed out` |
|
|
419
|
+
| `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
|
|
420
|
+
| scope | that one tab | **every** new tab / cross-origin nav |
|
|
421
|
+
| `doctor` | `✓ Renderer capacity` | names the wedge + pid |
|
|
422
|
+
| fix | `click --trusted` on the tab | `launch --restart` (**ask first**) |
|
|
423
|
+
|
|
424
|
+
`eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
|
|
425
|
+
painting case. If it times out, stop poking the page and run `doctor`.
|
|
357
426
|
- **Page still loading.** `goto` waits for the load event, but SPAs render after.
|
|
358
427
|
If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
|
|
359
428
|
once a known element should be present.
|