@generativereality/browser-automation 0.4.15 → 0.4.17
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 +154 -2
- package/package.json +1 -1
- package/skills/browser/SKILL.md +21 -0
|
@@ -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.17",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/README.md
CHANGED
|
@@ -186,6 +186,7 @@ same one-action-per-snapshot rule as Playwright refs.
|
|
|
186
186
|
`doctor` prints it too, and warns if another user holds it.
|
|
187
187
|
- `BROWSER_AUTOMATION_CDP` — full CDP host, overriding the port entirely.
|
|
188
188
|
- `BROWSER_AUTOMATION_PROFILE` — Chrome profile dir for `launch`. Default `~/.browser-automation/chrome-profile`; a profile still at the old location inside Chrome's own folder is moved there on launch (`browser-automation profile --migrate` to do it by hand).
|
|
189
|
+
- `BAC_SHOW_TAB=1` — `--show` on every `goto`/`new`: select the tab in its window when the automation Chrome is already in front (never raises Chrome over another app). macOS and Windows.
|
|
189
190
|
- `BAC_SESSION` — default session name for page commands.
|
|
190
191
|
|
|
191
192
|
## License
|
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.17";
|
|
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,
|
|
@@ -918,6 +918,10 @@ function chromeProcesses() {
|
|
|
918
918
|
renderers
|
|
919
919
|
};
|
|
920
920
|
}
|
|
921
|
+
/** The pid of the browser process serving the port we are driving, if visible. */
|
|
922
|
+
function browserPid() {
|
|
923
|
+
return chromeProcesses().browser;
|
|
924
|
+
}
|
|
921
925
|
/**
|
|
922
926
|
* macOS only: is the browser's Mach port rendezvous service still registered?
|
|
923
927
|
*
|
|
@@ -1094,6 +1098,135 @@ async function withRendererDiagnosis(fn) {
|
|
|
1094
1098
|
}
|
|
1095
1099
|
}
|
|
1096
1100
|
//#endregion
|
|
1101
|
+
//#region src/core/windows-foreground.ts
|
|
1102
|
+
/** The script, with the port substituted. Exported so the test can read it. */
|
|
1103
|
+
function probeScript(port) {
|
|
1104
|
+
return [
|
|
1105
|
+
"$ErrorActionPreference = 'Stop'",
|
|
1106
|
+
"$ProgressPreference = 'SilentlyContinue'",
|
|
1107
|
+
"Add-Type -Namespace BrowserAutomation -Name User32 -MemberDefinition @'",
|
|
1108
|
+
"[DllImport(\"user32.dll\")] public static extern System.IntPtr GetForegroundWindow();",
|
|
1109
|
+
"[DllImport(\"user32.dll\")] public static extern uint GetWindowThreadProcessId(System.IntPtr hWnd, out uint processId);",
|
|
1110
|
+
"'@",
|
|
1111
|
+
"$U = [BrowserAutomation.User32]",
|
|
1112
|
+
"$h = $U::GetForegroundWindow()",
|
|
1113
|
+
"$fg = [uint32]0",
|
|
1114
|
+
"if ($h -ne [IntPtr]::Zero) { [void]$U::GetWindowThreadProcessId($h, [ref]$fg) }",
|
|
1115
|
+
`$re = '--remote-debugging-port=${port}(\\s|"|$)'`,
|
|
1116
|
+
"$sid = [System.Diagnostics.Process]::GetCurrentProcess().SessionId",
|
|
1117
|
+
"$b = Get-CimInstance Win32_Process -Filter \"Name = 'chrome.exe'\" |",
|
|
1118
|
+
" Where-Object { $_.SessionId -eq $sid -and $_.CommandLine -and $_.CommandLine -match $re -and $_.CommandLine -notmatch '--type=' } |",
|
|
1119
|
+
" Select-Object -First 1 -ExpandProperty ProcessId",
|
|
1120
|
+
"Write-Output ('BA-FG ' + $fg + ' ' + [int]$b)"
|
|
1121
|
+
].join("\n");
|
|
1122
|
+
}
|
|
1123
|
+
/**
|
|
1124
|
+
* Read the answer out of PowerShell's stdout.
|
|
1125
|
+
*
|
|
1126
|
+
* Scans for the line with the expected SHAPE rather than taking the first line:
|
|
1127
|
+
* a PowerShell child process can put other things on its streams (CLIXML
|
|
1128
|
+
* progress records, "Preparing modules for first use"), and keying on line one
|
|
1129
|
+
* is how a parser starts failing the day something precedes the answer.
|
|
1130
|
+
*/
|
|
1131
|
+
function parseProbe(stdout) {
|
|
1132
|
+
const m = /^BA-FG (\d+) (\d+)\s*$/m.exec(stdout);
|
|
1133
|
+
return m ? {
|
|
1134
|
+
foreground: Number(m[1]),
|
|
1135
|
+
browser: Number(m[2])
|
|
1136
|
+
} : null;
|
|
1137
|
+
}
|
|
1138
|
+
function windowsForeground(port) {
|
|
1139
|
+
const encoded = Buffer.from(probeScript(port), "utf16le").toString("base64");
|
|
1140
|
+
try {
|
|
1141
|
+
return parseProbe(execFileSync("powershell.exe", [
|
|
1142
|
+
"-NoProfile",
|
|
1143
|
+
"-NonInteractive",
|
|
1144
|
+
"-ExecutionPolicy",
|
|
1145
|
+
"Bypass",
|
|
1146
|
+
"-EncodedCommand",
|
|
1147
|
+
encoded
|
|
1148
|
+
], {
|
|
1149
|
+
encoding: "utf8",
|
|
1150
|
+
stdio: [
|
|
1151
|
+
"ignore",
|
|
1152
|
+
"pipe",
|
|
1153
|
+
"ignore"
|
|
1154
|
+
],
|
|
1155
|
+
timeout: 15e3,
|
|
1156
|
+
windowsHide: true
|
|
1157
|
+
}));
|
|
1158
|
+
} catch {
|
|
1159
|
+
return null;
|
|
1160
|
+
}
|
|
1161
|
+
}
|
|
1162
|
+
//#endregion
|
|
1163
|
+
//#region src/core/show.ts
|
|
1164
|
+
/** On for this command: `--show`, or `BAC_SHOW_TAB=1` set once by a skill. */
|
|
1165
|
+
function wantsShow(flag) {
|
|
1166
|
+
return flag === true || /^(1|true|yes|on)$/i.test(process.env.BAC_SHOW_TAB ?? "");
|
|
1167
|
+
}
|
|
1168
|
+
/**
|
|
1169
|
+
* Is the Chrome we drive the frontmost app? `null` when this platform cannot
|
|
1170
|
+
* say — which must not be treated as "yes".
|
|
1171
|
+
*
|
|
1172
|
+
* `lsappinfo`, not AppleScript: it needs no Accessibility or Automation grant,
|
|
1173
|
+
* and a permission dialog mid-command is worse than the problem.
|
|
1174
|
+
*/
|
|
1175
|
+
function ourChromeIsFrontmost() {
|
|
1176
|
+
const injected = process.env.BROWSER_AUTOMATION_TEST_FRONTMOST;
|
|
1177
|
+
if (injected) return injected === "chrome";
|
|
1178
|
+
if (process.platform === "win32") {
|
|
1179
|
+
const w = windowsForeground(targetPort());
|
|
1180
|
+
if (!w || !w.foreground || !w.browser) return null;
|
|
1181
|
+
return w.foreground === w.browser;
|
|
1182
|
+
}
|
|
1183
|
+
if (process.platform !== "darwin") return null;
|
|
1184
|
+
try {
|
|
1185
|
+
const asn = execFileSync("lsappinfo", ["front"], {
|
|
1186
|
+
encoding: "utf8",
|
|
1187
|
+
stdio: [
|
|
1188
|
+
"ignore",
|
|
1189
|
+
"pipe",
|
|
1190
|
+
"ignore"
|
|
1191
|
+
]
|
|
1192
|
+
}).trim();
|
|
1193
|
+
if (!asn) return null;
|
|
1194
|
+
const info = execFileSync("lsappinfo", [
|
|
1195
|
+
"info",
|
|
1196
|
+
"-only",
|
|
1197
|
+
"pid",
|
|
1198
|
+
asn
|
|
1199
|
+
], {
|
|
1200
|
+
encoding: "utf8",
|
|
1201
|
+
stdio: [
|
|
1202
|
+
"ignore",
|
|
1203
|
+
"pipe",
|
|
1204
|
+
"ignore"
|
|
1205
|
+
]
|
|
1206
|
+
});
|
|
1207
|
+
const front = Number(/pid\s*=\s*(\d+)/.exec(info)?.[1]);
|
|
1208
|
+
const ours = browserPid();
|
|
1209
|
+
if (!front || !ours) return null;
|
|
1210
|
+
return front === ours;
|
|
1211
|
+
} catch {
|
|
1212
|
+
return null;
|
|
1213
|
+
}
|
|
1214
|
+
}
|
|
1215
|
+
/** Select `targetId` in its window if, and only if, that raises nothing. */
|
|
1216
|
+
async function showTab(targetId) {
|
|
1217
|
+
const front = ourChromeIsFrontmost();
|
|
1218
|
+
if (front === null) return "unsupported";
|
|
1219
|
+
if (!front) return "not-frontmost";
|
|
1220
|
+
await activateTab(targetId);
|
|
1221
|
+
return "shown";
|
|
1222
|
+
}
|
|
1223
|
+
/** One line for the agent when it asked and did not get it — never silent, never loud. */
|
|
1224
|
+
function describeNotShown(outcome) {
|
|
1225
|
+
if (outcome === "not-frontmost") return "Tab not shown: another app (or another Chrome) is in front, and --show never brings this Chrome over it. It selects the tab once the automation Chrome is in front.";
|
|
1226
|
+
if (outcome === "unsupported") return "Tab not shown: cannot tell which app is in front here (supported on macOS and Windows), so --show did nothing rather than risk taking the screen.";
|
|
1227
|
+
return null;
|
|
1228
|
+
}
|
|
1229
|
+
//#endregion
|
|
1097
1230
|
//#region src/commands/new.ts
|
|
1098
1231
|
const newCommand = define({
|
|
1099
1232
|
name: "new",
|
|
@@ -1108,6 +1241,10 @@ const newCommand = define({
|
|
|
1108
1241
|
type: "boolean",
|
|
1109
1242
|
short: "f",
|
|
1110
1243
|
description: "Open a new tab even if the session already has one"
|
|
1244
|
+
},
|
|
1245
|
+
show: {
|
|
1246
|
+
type: "boolean",
|
|
1247
|
+
description: "Make this the SELECTED tab in its Chrome window, so someone watching Chrome sees it — only when the automation Chrome is already the frontmost app, so it never brings Chrome over another app. Default on with BAC_SHOW_TAB=1."
|
|
1111
1248
|
}
|
|
1112
1249
|
},
|
|
1113
1250
|
async run(ctx) {
|
|
@@ -1131,7 +1268,14 @@ const newCommand = define({
|
|
|
1131
1268
|
}
|
|
1132
1269
|
consola$1.warn(`[${name}] tab ${targetId.slice(0, 12)}… did not answer yet (${r.reason ?? r.outcome}). Chrome can still create renderers, so this is likely transient — retry the next command.`);
|
|
1133
1270
|
}
|
|
1134
|
-
|
|
1271
|
+
let shown = false;
|
|
1272
|
+
if (wantsShow(ctx.values.show)) {
|
|
1273
|
+
const outcome = await showTab(targetId).catch(() => "unsupported");
|
|
1274
|
+
shown = outcome === "shown";
|
|
1275
|
+
const note = describeNotShown(outcome);
|
|
1276
|
+
if (note) consola$1.info(note);
|
|
1277
|
+
}
|
|
1278
|
+
consola$1.success(`[${name}] opened ${shown ? "and showed" : "background"} tab ${targetId.slice(0, 12)}… → ${url}`);
|
|
1135
1279
|
}
|
|
1136
1280
|
});
|
|
1137
1281
|
//#endregion
|
|
@@ -1236,6 +1380,10 @@ const gotoCommand = define({
|
|
|
1236
1380
|
url: {
|
|
1237
1381
|
type: "positional",
|
|
1238
1382
|
description: "URL to navigate to"
|
|
1383
|
+
},
|
|
1384
|
+
show: {
|
|
1385
|
+
type: "boolean",
|
|
1386
|
+
description: "Make this the SELECTED tab in its Chrome window, so someone watching Chrome sees it — only when the automation Chrome is already the frontmost app, so it never brings Chrome over another app. Default on with BAC_SHOW_TAB=1."
|
|
1239
1387
|
}
|
|
1240
1388
|
},
|
|
1241
1389
|
async run(ctx) {
|
|
@@ -1251,6 +1399,10 @@ const gotoCommand = define({
|
|
|
1251
1399
|
if ((await ensureRenderer(targetId)).woke) consola$1.warn("The new tab's renderer did not start on its own, so the tab was activated briefly to force one. The Chrome window was raised and handed straight back.");
|
|
1252
1400
|
}
|
|
1253
1401
|
if (!(await withRendererDiagnosis(() => navigate(targetId, target))).loaded) consola$1.warn("No load event arrived, so the page may still be loading. The navigation itself was accepted; this is a statement about what could not be confirmed.");
|
|
1402
|
+
if (wantsShow(ctx.values.show)) {
|
|
1403
|
+
const note = describeNotShown(await showTab(targetId).catch(() => "unsupported"));
|
|
1404
|
+
if (note) consola$1.info(note);
|
|
1405
|
+
}
|
|
1254
1406
|
if (!opts.match && !opts.target) {
|
|
1255
1407
|
const name = opts.session || defaultSessionName();
|
|
1256
1408
|
saveSession({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.17",
|
|
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/skills/browser/SKILL.md
CHANGED
|
@@ -46,6 +46,26 @@ file under `~/.browser-automation/sessions/`.
|
|
|
46
46
|
`focus --raise`, which calls `Target.activateTarget` and **genuinely takes the
|
|
47
47
|
operator's screen**. `--raise` is the only one that does; reach for plain
|
|
48
48
|
`focus` unless a person needs to see the tab.
|
|
49
|
+
- **Show the work: `--show` / `BAC_SHOW_TAB=1`.** A person watching the Chrome
|
|
50
|
+
window sees whichever tab is SELECTED, and the tabs you work in are background
|
|
51
|
+
tabs — so by default they watch one stale page while titles change elsewhere
|
|
52
|
+
(filmed: eleven minutes on one tab during a real round). `goto --show` and
|
|
53
|
+
`new --show` make your tab the selected one; `export BAC_SHOW_TAB=1` turns it
|
|
54
|
+
on for every `goto`/`new` in the shell, so a skill sets it once.
|
|
55
|
+
**It only selects when the automation Chrome is already the frontmost app**,
|
|
56
|
+
and otherwise does nothing and says `Tab not shown: another app … is in front`.
|
|
57
|
+
That is the design, not a limitation to work around: on current Chrome every
|
|
58
|
+
way of selecting a tab from outside (`Target.activateTarget`,
|
|
59
|
+
`Page.bringToFront`, `/json/activate`, a foreground `new`, `window.open`)
|
|
60
|
+
also brings Chrome in front of whatever the person is using — measured
|
|
61
|
+
2026-09-29. When Chrome is already in front nothing gets raised, which is the
|
|
62
|
+
case of someone watching it. The person's everyday Chrome counts as "another
|
|
63
|
+
app": it is checked by process, not by name. ⛔ Do not reach for `focus --raise`
|
|
64
|
+
to "make it show" — that is the screen-taking version; keep it for the moments
|
|
65
|
+
a person must look (a sign-in, a CAPTCHA). **macOS and Windows**; on Linux
|
|
66
|
+
`--show` reports that it cannot tell and does nothing. On Windows each
|
|
67
|
+
`--show` costs about 0.9 s (a PowerShell probe of the foreground window), so
|
|
68
|
+
turn it on where someone may be watching, not by reflex for batch work.
|
|
49
69
|
- **Self-healing.** If the tab was closed (or Chrome restarted and reissued
|
|
50
70
|
targetIds), the next `goto` just opens a fresh background tab for that session.
|
|
51
71
|
- **Refs live in the DOM.** `snapshot` stamps `data-ba-ref="e7"` onto each
|
|
@@ -140,6 +160,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
140
160
|
| Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
|
|
141
161
|
| Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
|
|
142
162
|
| Make a hidden tab render (charts, video, polling) | `browser-automation focus -s work` (add `--raise` to really front it) |
|
|
163
|
+
| Let a person watching Chrome see the tab you work in | `goto --show` / `new --show`, or `export BAC_SHOW_TAB=1` once |
|
|
143
164
|
| Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
|
|
144
165
|
| Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
|
|
145
166
|
| Forget a session (tab stays open) | `browser-automation close -s work` |
|