@generativereality/browser-automation 0.4.15 → 0.4.16
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 +87 -2
- package/package.json +1 -1
- package/skills/browser/SKILL.md +19 -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.16",
|
|
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).
|
|
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.16";
|
|
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,68 @@ async function withRendererDiagnosis(fn) {
|
|
|
1094
1098
|
}
|
|
1095
1099
|
}
|
|
1096
1100
|
//#endregion
|
|
1101
|
+
//#region src/core/show.ts
|
|
1102
|
+
/** On for this command: `--show`, or `BAC_SHOW_TAB=1` set once by a skill. */
|
|
1103
|
+
function wantsShow(flag) {
|
|
1104
|
+
return flag === true || /^(1|true|yes|on)$/i.test(process.env.BAC_SHOW_TAB ?? "");
|
|
1105
|
+
}
|
|
1106
|
+
/**
|
|
1107
|
+
* Is the Chrome we drive the frontmost app? `null` when this platform cannot
|
|
1108
|
+
* say — which must not be treated as "yes".
|
|
1109
|
+
*
|
|
1110
|
+
* `lsappinfo`, not AppleScript: it needs no Accessibility or Automation grant,
|
|
1111
|
+
* and a permission dialog mid-command is worse than the problem.
|
|
1112
|
+
*/
|
|
1113
|
+
function ourChromeIsFrontmost() {
|
|
1114
|
+
const injected = process.env.BROWSER_AUTOMATION_TEST_FRONTMOST;
|
|
1115
|
+
if (injected) return injected === "chrome";
|
|
1116
|
+
if (process.platform !== "darwin") return null;
|
|
1117
|
+
try {
|
|
1118
|
+
const asn = execFileSync("lsappinfo", ["front"], {
|
|
1119
|
+
encoding: "utf8",
|
|
1120
|
+
stdio: [
|
|
1121
|
+
"ignore",
|
|
1122
|
+
"pipe",
|
|
1123
|
+
"ignore"
|
|
1124
|
+
]
|
|
1125
|
+
}).trim();
|
|
1126
|
+
if (!asn) return null;
|
|
1127
|
+
const info = execFileSync("lsappinfo", [
|
|
1128
|
+
"info",
|
|
1129
|
+
"-only",
|
|
1130
|
+
"pid",
|
|
1131
|
+
asn
|
|
1132
|
+
], {
|
|
1133
|
+
encoding: "utf8",
|
|
1134
|
+
stdio: [
|
|
1135
|
+
"ignore",
|
|
1136
|
+
"pipe",
|
|
1137
|
+
"ignore"
|
|
1138
|
+
]
|
|
1139
|
+
});
|
|
1140
|
+
const front = Number(/pid\s*=\s*(\d+)/.exec(info)?.[1]);
|
|
1141
|
+
const ours = browserPid();
|
|
1142
|
+
if (!front || !ours) return null;
|
|
1143
|
+
return front === ours;
|
|
1144
|
+
} catch {
|
|
1145
|
+
return null;
|
|
1146
|
+
}
|
|
1147
|
+
}
|
|
1148
|
+
/** Select `targetId` in its window if, and only if, that raises nothing. */
|
|
1149
|
+
async function showTab(targetId) {
|
|
1150
|
+
const front = ourChromeIsFrontmost();
|
|
1151
|
+
if (front === null) return "unsupported";
|
|
1152
|
+
if (!front) return "not-frontmost";
|
|
1153
|
+
await activateTab(targetId);
|
|
1154
|
+
return "shown";
|
|
1155
|
+
}
|
|
1156
|
+
/** One line for the agent when it asked and did not get it — never silent, never loud. */
|
|
1157
|
+
function describeNotShown(outcome) {
|
|
1158
|
+
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.";
|
|
1159
|
+
if (outcome === "unsupported") return "Tab not shown: cannot tell which app is in front here (macOS only), so --show did nothing rather than risk taking the screen.";
|
|
1160
|
+
return null;
|
|
1161
|
+
}
|
|
1162
|
+
//#endregion
|
|
1097
1163
|
//#region src/commands/new.ts
|
|
1098
1164
|
const newCommand = define({
|
|
1099
1165
|
name: "new",
|
|
@@ -1108,6 +1174,10 @@ const newCommand = define({
|
|
|
1108
1174
|
type: "boolean",
|
|
1109
1175
|
short: "f",
|
|
1110
1176
|
description: "Open a new tab even if the session already has one"
|
|
1177
|
+
},
|
|
1178
|
+
show: {
|
|
1179
|
+
type: "boolean",
|
|
1180
|
+
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
1181
|
}
|
|
1112
1182
|
},
|
|
1113
1183
|
async run(ctx) {
|
|
@@ -1131,7 +1201,14 @@ const newCommand = define({
|
|
|
1131
1201
|
}
|
|
1132
1202
|
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
1203
|
}
|
|
1134
|
-
|
|
1204
|
+
let shown = false;
|
|
1205
|
+
if (wantsShow(ctx.values.show)) {
|
|
1206
|
+
const outcome = await showTab(targetId).catch(() => "unsupported");
|
|
1207
|
+
shown = outcome === "shown";
|
|
1208
|
+
const note = describeNotShown(outcome);
|
|
1209
|
+
if (note) consola$1.info(note);
|
|
1210
|
+
}
|
|
1211
|
+
consola$1.success(`[${name}] opened ${shown ? "and showed" : "background"} tab ${targetId.slice(0, 12)}… → ${url}`);
|
|
1135
1212
|
}
|
|
1136
1213
|
});
|
|
1137
1214
|
//#endregion
|
|
@@ -1236,6 +1313,10 @@ const gotoCommand = define({
|
|
|
1236
1313
|
url: {
|
|
1237
1314
|
type: "positional",
|
|
1238
1315
|
description: "URL to navigate to"
|
|
1316
|
+
},
|
|
1317
|
+
show: {
|
|
1318
|
+
type: "boolean",
|
|
1319
|
+
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
1320
|
}
|
|
1240
1321
|
},
|
|
1241
1322
|
async run(ctx) {
|
|
@@ -1251,6 +1332,10 @@ const gotoCommand = define({
|
|
|
1251
1332
|
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
1333
|
}
|
|
1253
1334
|
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.");
|
|
1335
|
+
if (wantsShow(ctx.values.show)) {
|
|
1336
|
+
const note = describeNotShown(await showTab(targetId).catch(() => "unsupported"));
|
|
1337
|
+
if (note) consola$1.info(note);
|
|
1338
|
+
}
|
|
1254
1339
|
if (!opts.match && !opts.target) {
|
|
1255
1340
|
const name = opts.session || defaultSessionName();
|
|
1256
1341
|
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.16",
|
|
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,24 @@ 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 only; elsewhere `--show`
|
|
66
|
+
reports that it cannot tell and does nothing.
|
|
49
67
|
- **Self-healing.** If the tab was closed (or Chrome restarted and reissued
|
|
50
68
|
targetIds), the next `goto` just opens a fresh background tab for that session.
|
|
51
69
|
- **Refs live in the DOM.** `snapshot` stamps `data-ba-ref="e7"` onto each
|
|
@@ -140,6 +158,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
140
158
|
| Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
|
|
141
159
|
| Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
|
|
142
160
|
| Make a hidden tab render (charts, video, polling) | `browser-automation focus -s work` (add `--raise` to really front it) |
|
|
161
|
+
| Let a person watching Chrome see the tab you work in | `goto --show` / `new --show`, or `export BAC_SHOW_TAB=1` once |
|
|
143
162
|
| Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
|
|
144
163
|
| Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
|
|
145
164
|
| Forget a session (tab stays open) | `browser-automation close -s work` |
|