@generativereality/browser-automation 0.4.11 → 0.4.12
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 +516 -98
- package/package.json +1 -1
- package/scripts/launch-chrome.sh +13 -4
- package/skills/browser/SKILL.md +64 -10
|
@@ -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.12",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/dist/index.js
CHANGED
|
@@ -4,12 +4,12 @@ import { cli, define } from "gunshi";
|
|
|
4
4
|
import { consola } from "consola";
|
|
5
5
|
import { homedir } from "node:os";
|
|
6
6
|
import { basename, dirname, extname, join, resolve } from "node:path";
|
|
7
|
-
import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
7
|
+
import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
8
8
|
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.12";
|
|
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,
|
|
@@ -388,6 +388,26 @@ async function createTab(url = "about:blank", { timeout } = {}) {
|
|
|
388
388
|
}, timeout)).targetId;
|
|
389
389
|
}, timeout);
|
|
390
390
|
}
|
|
391
|
+
/**
|
|
392
|
+
* Bring a target to the front of its window.
|
|
393
|
+
*
|
|
394
|
+
* **This raises the Chrome window over whatever the operator is using** —
|
|
395
|
+
* measured on macOS 2026-09-11, with the terminal deliberately frontmost:
|
|
396
|
+
* Target.activateTarget, GET /json/activate/<id>, Page.bringToFront and
|
|
397
|
+
* createTarget(background:false) all moved the frontmost app from the terminal
|
|
398
|
+
* to Google Chrome. There is no quiet variant.
|
|
399
|
+
*
|
|
400
|
+
* It is here because a backgrounded target's renderer can take 12+ seconds to
|
|
401
|
+
* answer while an activated one answers in ~19ms (see core/renderer-wake.ts),
|
|
402
|
+
* and a brief flicker beats refusing to work. Nothing calls it casually:
|
|
403
|
+
* `ensureRenderer` spends it only after a grace period has expired, and hands
|
|
404
|
+
* the window straight back.
|
|
405
|
+
*/
|
|
406
|
+
async function activateTab(targetId) {
|
|
407
|
+
return withBrowser(async (s) => {
|
|
408
|
+
await s.send("Target.activateTarget", { targetId });
|
|
409
|
+
});
|
|
410
|
+
}
|
|
391
411
|
async function closeTab(targetId) {
|
|
392
412
|
return withBrowser(async (s) => {
|
|
393
413
|
return !!(await s.send("Target.closeTarget", { targetId })).success;
|
|
@@ -475,39 +495,303 @@ function normalizeUrl(input) {
|
|
|
475
495
|
return `https://${input}`;
|
|
476
496
|
}
|
|
477
497
|
//#endregion
|
|
498
|
+
//#region src/core/renderer-wake.ts
|
|
499
|
+
/** How long a new tab gets to produce a renderer on its own before we wake it. */
|
|
500
|
+
const DEFAULT_GRACE = 2e3;
|
|
501
|
+
/** How long the woken tab then gets. Generous: waking is the expensive step. */
|
|
502
|
+
const DEFAULT_BUDGET = 1e4;
|
|
503
|
+
function envInt(name, fallback) {
|
|
504
|
+
const v = Number(process.env[name]);
|
|
505
|
+
return Number.isFinite(v) && v > 0 ? Math.floor(v) : fallback;
|
|
506
|
+
}
|
|
507
|
+
/**
|
|
508
|
+
* Ask ONE existing target's renderer to evaluate `1+1`.
|
|
509
|
+
*
|
|
510
|
+
* Deliberately not a navigation: the question is "can this renderer execute",
|
|
511
|
+
* which is the narrowest thing that separates a busy browser from a broken one
|
|
512
|
+
* without involving the network or the site.
|
|
513
|
+
*/
|
|
514
|
+
async function askRenderer(targetId, timeout = 5e3) {
|
|
515
|
+
const started = Date.now();
|
|
516
|
+
const ms = () => Date.now() - started;
|
|
517
|
+
let ws;
|
|
518
|
+
try {
|
|
519
|
+
ws = await targetWsUrl(targetId);
|
|
520
|
+
} catch (e) {
|
|
521
|
+
return {
|
|
522
|
+
outcome: "error",
|
|
523
|
+
ms: ms(),
|
|
524
|
+
reason: String(e?.message ?? e)
|
|
525
|
+
};
|
|
526
|
+
}
|
|
527
|
+
if (!ws) return {
|
|
528
|
+
outcome: "gone",
|
|
529
|
+
ms: ms(),
|
|
530
|
+
reason: "the target vanished before we could attach to it"
|
|
531
|
+
};
|
|
532
|
+
let session;
|
|
533
|
+
try {
|
|
534
|
+
session = await connect(ws, { timeout });
|
|
535
|
+
} catch (e) {
|
|
536
|
+
const msg = String(e?.message ?? e);
|
|
537
|
+
return /timed out|timeout|WebSocket error/i.test(msg) ? {
|
|
538
|
+
outcome: "unattachable",
|
|
539
|
+
ms: ms(),
|
|
540
|
+
reason: `the target is listed, but its CDP connection would not open within ${timeout}ms (${msg})`
|
|
541
|
+
} : {
|
|
542
|
+
outcome: "error",
|
|
543
|
+
ms: ms(),
|
|
544
|
+
reason: msg
|
|
545
|
+
};
|
|
546
|
+
}
|
|
547
|
+
try {
|
|
548
|
+
const value = (await session.send("Runtime.evaluate", {
|
|
549
|
+
expression: "1+1",
|
|
550
|
+
returnByValue: true
|
|
551
|
+
}, timeout))?.result?.value;
|
|
552
|
+
if (value === 2) return {
|
|
553
|
+
outcome: "ok",
|
|
554
|
+
ms: ms()
|
|
555
|
+
};
|
|
556
|
+
return {
|
|
557
|
+
outcome: "wrong-answer",
|
|
558
|
+
ms: ms(),
|
|
559
|
+
reason: `the renderer answered with ${JSON.stringify(value)} instead of 2`
|
|
560
|
+
};
|
|
561
|
+
} catch (e) {
|
|
562
|
+
const msg = String(e?.message ?? e);
|
|
563
|
+
return /timed out|timeout/i.test(msg) ? {
|
|
564
|
+
outcome: "silent",
|
|
565
|
+
ms: ms(),
|
|
566
|
+
reason: `attached to the target, but its renderer did not answer within ${timeout}ms`
|
|
567
|
+
} : {
|
|
568
|
+
outcome: "error",
|
|
569
|
+
ms: ms(),
|
|
570
|
+
reason: msg
|
|
571
|
+
};
|
|
572
|
+
} finally {
|
|
573
|
+
session.close();
|
|
574
|
+
}
|
|
575
|
+
}
|
|
576
|
+
/**
|
|
577
|
+
* The macOS app currently in front, as a bundle path we can hand focus back to.
|
|
578
|
+
*
|
|
579
|
+
* `lsappinfo`, not AppleScript: `tell application "System Events" to get name
|
|
580
|
+
* of first application process whose frontmost is true` needs Accessibility
|
|
581
|
+
* permission, and a permission dialog appearing in the middle of an automated
|
|
582
|
+
* command is worse than the focus steal it is trying to undo. `lsappinfo` needs
|
|
583
|
+
* nothing and is present on every macOS.
|
|
584
|
+
*/
|
|
585
|
+
function frontmostApp() {
|
|
586
|
+
if (process.platform !== "darwin") return null;
|
|
587
|
+
try {
|
|
588
|
+
const asn = execFileSync("lsappinfo", ["front"], {
|
|
589
|
+
encoding: "utf8",
|
|
590
|
+
stdio: [
|
|
591
|
+
"ignore",
|
|
592
|
+
"pipe",
|
|
593
|
+
"ignore"
|
|
594
|
+
]
|
|
595
|
+
}).trim();
|
|
596
|
+
if (!asn) return null;
|
|
597
|
+
const info = execFileSync("lsappinfo", [
|
|
598
|
+
"info",
|
|
599
|
+
"-only",
|
|
600
|
+
"bundlepath",
|
|
601
|
+
asn
|
|
602
|
+
], {
|
|
603
|
+
encoding: "utf8",
|
|
604
|
+
stdio: [
|
|
605
|
+
"ignore",
|
|
606
|
+
"pipe",
|
|
607
|
+
"ignore"
|
|
608
|
+
]
|
|
609
|
+
});
|
|
610
|
+
return /"LSBundlePath"="([^"]+)"/.exec(info)?.[1] ?? null;
|
|
611
|
+
} catch {
|
|
612
|
+
return null;
|
|
613
|
+
}
|
|
614
|
+
}
|
|
615
|
+
/** Put the operator's app back in front. Best effort, and never fatal. */
|
|
616
|
+
function raiseApp(bundlePath) {
|
|
617
|
+
if (!bundlePath || process.platform !== "darwin") return;
|
|
618
|
+
if (/Google Chrome\.app|Chromium\.app/.test(bundlePath)) return;
|
|
619
|
+
try {
|
|
620
|
+
execFileSync("open", ["-a", bundlePath], { stdio: "ignore" });
|
|
621
|
+
} catch {}
|
|
622
|
+
}
|
|
623
|
+
/**
|
|
624
|
+
* Which tab the operator is looking at, so it can be put back afterwards.
|
|
625
|
+
*
|
|
626
|
+
* Chrome lists page targets most-recently-active first. That is an observation,
|
|
627
|
+
* not a documented guarantee — it held in every trial here, and when it is
|
|
628
|
+
* wrong the cost is that the window comes back to a different tab of the
|
|
629
|
+
* automation browser, not a failure.
|
|
630
|
+
*/
|
|
631
|
+
async function activePageId() {
|
|
632
|
+
try {
|
|
633
|
+
return (await listPageTargets())[0]?.id;
|
|
634
|
+
} catch {
|
|
635
|
+
return;
|
|
636
|
+
}
|
|
637
|
+
}
|
|
638
|
+
/**
|
|
639
|
+
* Make sure `targetId` has a renderer that answers — cheaply if possible.
|
|
640
|
+
*
|
|
641
|
+
* Grace period first (the common case: no focus is taken at all), then one
|
|
642
|
+
* wake, then the verdict. `allowWake: false` (or BROWSER_AUTOMATION_NO_WAKE=1)
|
|
643
|
+
* keeps the window untouched for callers who would rather fail than flicker.
|
|
644
|
+
*/
|
|
645
|
+
async function ensureRenderer(targetId, { grace, budget, allowWake = !process.env.BROWSER_AUTOMATION_NO_WAKE } = {}) {
|
|
646
|
+
const graceMs = grace ?? envInt("BROWSER_AUTOMATION_RENDERER_GRACE", DEFAULT_GRACE);
|
|
647
|
+
const budgetMs = budget ?? envInt("BROWSER_AUTOMATION_RENDERER_BUDGET", DEFAULT_BUDGET);
|
|
648
|
+
const started = Date.now();
|
|
649
|
+
const first = await askRenderer(targetId, graceMs);
|
|
650
|
+
if (first.outcome === "ok") return {
|
|
651
|
+
...first,
|
|
652
|
+
ok: true,
|
|
653
|
+
woke: false,
|
|
654
|
+
ms: Date.now() - started
|
|
655
|
+
};
|
|
656
|
+
if (!allowWake || first.outcome !== "silent" && first.outcome !== "unattachable") return {
|
|
657
|
+
...first,
|
|
658
|
+
ok: false,
|
|
659
|
+
woke: false,
|
|
660
|
+
ms: Date.now() - started
|
|
661
|
+
};
|
|
662
|
+
const previousApp = frontmostApp();
|
|
663
|
+
const previousTab = await activePageId();
|
|
664
|
+
try {
|
|
665
|
+
await activateTab(targetId);
|
|
666
|
+
} catch (e) {
|
|
667
|
+
return {
|
|
668
|
+
...first,
|
|
669
|
+
ok: false,
|
|
670
|
+
woke: false,
|
|
671
|
+
ms: Date.now() - started,
|
|
672
|
+
reason: `${first.reason}; and it could not be activated either (${e?.message ?? e})`
|
|
673
|
+
};
|
|
674
|
+
}
|
|
675
|
+
const second = await askRenderer(targetId, budgetMs);
|
|
676
|
+
if (previousTab && previousTab !== targetId) await activateTab(previousTab).catch(() => {});
|
|
677
|
+
raiseApp(previousApp);
|
|
678
|
+
return {
|
|
679
|
+
...second,
|
|
680
|
+
ok: second.outcome === "ok",
|
|
681
|
+
woke: true,
|
|
682
|
+
ms: Date.now() - started
|
|
683
|
+
};
|
|
684
|
+
}
|
|
685
|
+
//#endregion
|
|
478
686
|
//#region src/core/renderer-health.ts
|
|
687
|
+
/** First attempt's budget. Later attempts double it. */
|
|
688
|
+
const DEFAULT_TIMEOUT = 5e3;
|
|
689
|
+
/** How many times we ask before we are willing to call a browser broken. */
|
|
690
|
+
const DEFAULT_ATTEMPTS = 3;
|
|
691
|
+
/** Breathing room between attempts — a browser mid-GC deserves a second look. */
|
|
692
|
+
const RETRY_PAUSE = 400;
|
|
693
|
+
/**
|
|
694
|
+
* The verdict, from the probe and the corroborations — and from nothing else.
|
|
695
|
+
*
|
|
696
|
+
* Pure, and separate from the probing, because this is the decision that was
|
|
697
|
+
* wrong: every failure used to become 'wedged' by default. Now 'wedged'
|
|
698
|
+
* requires `rendezvous === false`, which is the only thing that has ever
|
|
699
|
+
* actually meant it.
|
|
700
|
+
*/
|
|
701
|
+
function rendererVerdict(outcome, e) {
|
|
702
|
+
if (outcome === "ok") return "healthy";
|
|
703
|
+
if (e?.rendezvous === false) return "wedged";
|
|
704
|
+
if (e?.rendezvous === true && (e.renderers ?? 0) > 0) return "busy";
|
|
705
|
+
return "unknown";
|
|
706
|
+
}
|
|
479
707
|
/**
|
|
480
708
|
* Create a throwaway tab, make its renderer prove it is alive, close it.
|
|
481
709
|
*
|
|
482
|
-
*
|
|
483
|
-
*
|
|
484
|
-
*
|
|
485
|
-
*
|
|
710
|
+
* Three things changed after 2026-09-11, and each of them is load-bearing:
|
|
711
|
+
*
|
|
712
|
+
* 1. It goes through `ensureRenderer`, so the probe opens its tab the way the
|
|
713
|
+
* tool opens tabs AND gets the same wake treatment. A probe that is harsher
|
|
714
|
+
* on itself than `goto` is on a real tab reports failures `goto` would not
|
|
715
|
+
* have had.
|
|
716
|
+
* 2. It retries with a doubling budget. One 5s timeout is not evidence of a
|
|
717
|
+
* permanent condition; it is evidence of 5 seconds.
|
|
718
|
+
* 3. It stops early when the Mach name is ABSENT — the one state where more
|
|
719
|
+
* waiting is genuinely pointless — so the real failure is still reported
|
|
720
|
+
* fast while a slow browser gets the benefit of the doubt.
|
|
486
721
|
*/
|
|
487
|
-
async function probeRenderer({ timeout
|
|
722
|
+
async function probeRenderer({ timeout, attempts } = {}) {
|
|
723
|
+
const base = timeout ?? envInt("BROWSER_AUTOMATION_PROBE_TIMEOUT", DEFAULT_TIMEOUT);
|
|
724
|
+
const maxAttempts = Math.max(1, attempts ?? envInt("BROWSER_AUTOMATION_PROBE_ATTEMPTS", DEFAULT_ATTEMPTS));
|
|
488
725
|
const started = Date.now();
|
|
489
726
|
let pageTargets = 0;
|
|
490
727
|
try {
|
|
491
728
|
pageTargets = (await listPageTargets()).length;
|
|
492
729
|
} catch {}
|
|
730
|
+
const tries = [];
|
|
731
|
+
let evidence;
|
|
732
|
+
for (let i = 0; i < maxAttempts; i++) {
|
|
733
|
+
const budget = base * 2 ** i;
|
|
734
|
+
tries.push(await probeOnce(budget));
|
|
735
|
+
if (tries[tries.length - 1].outcome === "ok") return finish({
|
|
736
|
+
ok: true,
|
|
737
|
+
started,
|
|
738
|
+
pageTargets,
|
|
739
|
+
tries,
|
|
740
|
+
evidence
|
|
741
|
+
});
|
|
742
|
+
evidence ??= gatherEvidence();
|
|
743
|
+
if (evidence.rendezvous === false) break;
|
|
744
|
+
if (i + 1 < maxAttempts) await new Promise((r) => setTimeout(r, RETRY_PAUSE));
|
|
745
|
+
}
|
|
746
|
+
return finish({
|
|
747
|
+
ok: false,
|
|
748
|
+
started,
|
|
749
|
+
pageTargets,
|
|
750
|
+
tries,
|
|
751
|
+
evidence
|
|
752
|
+
});
|
|
753
|
+
}
|
|
754
|
+
function finish({ ok, started, pageTargets, tries, evidence }) {
|
|
755
|
+
const last = tries[tries.length - 1];
|
|
756
|
+
const health = {
|
|
757
|
+
ok,
|
|
758
|
+
ms: Date.now() - started,
|
|
759
|
+
pageTargets,
|
|
760
|
+
reason: last?.reason,
|
|
761
|
+
outcome: last?.outcome ?? "error",
|
|
762
|
+
verdict: rendererVerdict(last?.outcome ?? "error", evidence),
|
|
763
|
+
attempts: tries,
|
|
764
|
+
evidence
|
|
765
|
+
};
|
|
766
|
+
recordProbe(health);
|
|
767
|
+
return health;
|
|
768
|
+
}
|
|
769
|
+
/** One create -> ensure -> close cycle. */
|
|
770
|
+
async function probeOnce(budget) {
|
|
771
|
+
const started = Date.now();
|
|
493
772
|
let targetId;
|
|
494
773
|
try {
|
|
495
|
-
targetId = await createTab("about:blank", { timeout });
|
|
774
|
+
targetId = await createTab("about:blank", { timeout: budget });
|
|
496
775
|
} catch (e) {
|
|
497
776
|
return {
|
|
498
|
-
|
|
777
|
+
outcome: "error",
|
|
778
|
+
budget,
|
|
499
779
|
ms: Date.now() - started,
|
|
500
|
-
|
|
780
|
+
woke: false,
|
|
501
781
|
reason: `could not create a target at all: ${e?.message ?? e}`
|
|
502
782
|
};
|
|
503
783
|
}
|
|
504
784
|
try {
|
|
505
|
-
const
|
|
785
|
+
const r = await ensureRenderer(targetId, {
|
|
786
|
+
grace: budget,
|
|
787
|
+
budget
|
|
788
|
+
});
|
|
506
789
|
return {
|
|
507
|
-
|
|
790
|
+
outcome: r.outcome,
|
|
791
|
+
budget,
|
|
508
792
|
ms: Date.now() - started,
|
|
509
|
-
|
|
510
|
-
reason: reason
|
|
793
|
+
woke: r.woke,
|
|
794
|
+
reason: r.reason
|
|
511
795
|
};
|
|
512
796
|
} finally {
|
|
513
797
|
if (targetId) await closeTab(targetId).catch(() => {});
|
|
@@ -516,68 +800,83 @@ async function probeRenderer({ timeout = 5e3 } = {}) {
|
|
|
516
800
|
/**
|
|
517
801
|
* Ask an EXISTING target's renderer to prove it is alive.
|
|
518
802
|
*
|
|
519
|
-
*
|
|
520
|
-
*
|
|
521
|
-
*
|
|
803
|
+
* Kept returning `string | null` because that is what `gc` wants (a reason to
|
|
804
|
+
* print beside a tab it is about to close). New callers should prefer
|
|
805
|
+
* `askRenderer`, which says WHICH failure it was.
|
|
522
806
|
*/
|
|
523
|
-
async function renderersAnswer(targetId, timeout =
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
if (!ws) return "the target vanished immediately";
|
|
527
|
-
const s = await connect(ws, { timeout });
|
|
528
|
-
try {
|
|
529
|
-
const value = (await s.send("Runtime.evaluate", {
|
|
530
|
-
expression: "1+1",
|
|
531
|
-
returnByValue: true
|
|
532
|
-
}, timeout))?.result?.value;
|
|
533
|
-
return value === 2 ? null : `the renderer answered with ${JSON.stringify(value)} instead of 2`;
|
|
534
|
-
} finally {
|
|
535
|
-
s.close();
|
|
536
|
-
}
|
|
537
|
-
} catch (e) {
|
|
538
|
-
const msg = String(e?.message ?? e);
|
|
539
|
-
return /timed out|timeout/i.test(msg) ? "the target exists, but no renderer ever answered it" : msg;
|
|
540
|
-
}
|
|
807
|
+
async function renderersAnswer(targetId, timeout = DEFAULT_TIMEOUT) {
|
|
808
|
+
const r = await askRenderer(targetId, timeout);
|
|
809
|
+
return r.outcome === "ok" ? null : r.reason ?? r.outcome;
|
|
541
810
|
}
|
|
542
811
|
/**
|
|
543
812
|
* The port we are actually talking to.
|
|
544
813
|
*
|
|
545
814
|
* NOT always `cdpPort()`: `BROWSER_AUTOMATION_CDP` points the CLI at an
|
|
546
|
-
* arbitrary host:port, and everything here that shells out to `
|
|
547
|
-
* `launchctl` has to ask about THAT browser. Using the uid-derived port
|
|
548
|
-
*
|
|
549
|
-
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
815
|
+
* arbitrary host:port, and everything here that shells out to `ps` or
|
|
816
|
+
* `launchctl` has to ask about THAT browser. Using the uid-derived port instead
|
|
817
|
+
* finds the user's default Chrome and cheerfully reports its health as if it
|
|
818
|
+
* were the one being driven — caught while testing this module against a second
|
|
819
|
+
* Chrome, where a perfectly healthy browser was accused of having lost a
|
|
820
|
+
* bootstrap name that in fact belonged to a different pid.
|
|
552
821
|
*/
|
|
553
822
|
function targetPort() {
|
|
554
823
|
const explicit = process.env.BROWSER_AUTOMATION_CDP;
|
|
555
|
-
if (explicit) {
|
|
824
|
+
if (explicit) try {
|
|
556
825
|
const p = Number(new URL(explicit).port);
|
|
557
826
|
if (Number.isInteger(p) && p > 0) return p;
|
|
558
|
-
}
|
|
827
|
+
} catch {}
|
|
559
828
|
return cdpPort();
|
|
560
829
|
}
|
|
561
|
-
/**
|
|
562
|
-
|
|
830
|
+
/**
|
|
831
|
+
* The browser process serving our port, and how many renderers it has.
|
|
832
|
+
*
|
|
833
|
+
* One `ps`, not one `pgrep` plus one `ps` per hit: on a Chrome with 40 children
|
|
834
|
+
* that was 41 forks to answer two questions, and it ran on the error path of a
|
|
835
|
+
* browser already thought to be struggling.
|
|
836
|
+
*
|
|
837
|
+
* The executable check is not decoration. Matching on the command line alone
|
|
838
|
+
* (as `pgrep -f` does) hits any process that merely CONTAINS the debugging-port
|
|
839
|
+
* flag — the `grep` looking for it, or a shell running `browser-automation`
|
|
840
|
+
* with the flag as an argument. One of those, having no `--type=`, would have
|
|
841
|
+
* been reported as the browser pid, and its absent Mach name read as the
|
|
842
|
+
* permanent failure. Seen while writing this: a `ugrep` for the flag sat in
|
|
843
|
+
* `ps` output alongside the real Chrome.
|
|
844
|
+
*/
|
|
845
|
+
function chromeProcesses() {
|
|
846
|
+
const flag = `--remote-debugging-port=${targetPort()}`;
|
|
847
|
+
const uid = String(process.getuid?.() ?? -1);
|
|
848
|
+
let out;
|
|
563
849
|
try {
|
|
564
|
-
|
|
565
|
-
"
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
850
|
+
out = execFileSync("ps", ["-Ao", "pid=,uid=,command="], {
|
|
851
|
+
encoding: "utf8",
|
|
852
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
853
|
+
stdio: [
|
|
854
|
+
"ignore",
|
|
855
|
+
"pipe",
|
|
856
|
+
"ignore"
|
|
857
|
+
]
|
|
858
|
+
});
|
|
859
|
+
} catch {
|
|
860
|
+
return {
|
|
861
|
+
browser: null,
|
|
862
|
+
renderers: null
|
|
863
|
+
};
|
|
864
|
+
}
|
|
865
|
+
let browser = null;
|
|
866
|
+
let renderers = 0;
|
|
867
|
+
for (const line of out.split("\n")) {
|
|
868
|
+
const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
|
|
869
|
+
if (!m) continue;
|
|
870
|
+
const [, pid, u, cmd] = m;
|
|
871
|
+
if (u !== uid || !cmd.includes(flag)) continue;
|
|
872
|
+
if (!/chrome|chromium|brave|msedge|thorium/i.test(cmd.split(" --")[0])) continue;
|
|
873
|
+
if (/--type=renderer\b/.test(cmd)) renderers++;
|
|
874
|
+
else if (!cmd.includes("--type=")) browser = Number(pid);
|
|
875
|
+
}
|
|
876
|
+
return {
|
|
877
|
+
browser,
|
|
878
|
+
renderers
|
|
879
|
+
};
|
|
581
880
|
}
|
|
582
881
|
/**
|
|
583
882
|
* macOS only: is the browser's Mach port rendezvous service still registered?
|
|
@@ -585,7 +884,7 @@ function browserPid() {
|
|
|
585
884
|
* This is the ROOT CAUSE signal, not a symptom — when it is missing, every
|
|
586
885
|
* child process Chrome launches kills itself on startup. Returns null when we
|
|
587
886
|
* cannot tell (not macOS, `launchctl` unavailable, pid unknown), which is
|
|
588
|
-
* different from `false` and must
|
|
887
|
+
* different from `false` and must never be reported as a fault.
|
|
589
888
|
*/
|
|
590
889
|
function rendezvousRegistered(pid) {
|
|
591
890
|
if (process.platform !== "darwin" || !pid) return null;
|
|
@@ -603,51 +902,143 @@ function rendezvousRegistered(pid) {
|
|
|
603
902
|
return null;
|
|
604
903
|
}
|
|
605
904
|
}
|
|
905
|
+
/** Both corroborations, in one pass. Cheap enough to run on every failure. */
|
|
906
|
+
function gatherEvidence() {
|
|
907
|
+
const { browser, renderers } = chromeProcesses();
|
|
908
|
+
return {
|
|
909
|
+
pid: browser,
|
|
910
|
+
renderers: browser === null ? null : renderers,
|
|
911
|
+
rendezvous: rendezvousRegistered(browser)
|
|
912
|
+
};
|
|
913
|
+
}
|
|
606
914
|
/** Where `launch` writes Chrome's stdout/stderr — Chrome logs the real reason there. */
|
|
607
915
|
function chromeLogPath() {
|
|
608
916
|
const tmp = process.env.TMPDIR?.replace(/\/$/, "") || "/tmp";
|
|
609
917
|
return process.env.BROWSER_AUTOMATION_LOG || `${tmp}/chrome-${targetPort()}.log`;
|
|
610
918
|
}
|
|
919
|
+
function probeLogPath() {
|
|
920
|
+
return process.env.BROWSER_AUTOMATION_PROBE_LOG || join(homedir(), ".browser-automation", "renderer-probes.jsonl");
|
|
921
|
+
}
|
|
922
|
+
function recordProbe(h) {
|
|
923
|
+
const line = JSON.stringify({
|
|
924
|
+
t: (/* @__PURE__ */ new Date()).toISOString(),
|
|
925
|
+
ok: h.ok,
|
|
926
|
+
verdict: h.verdict,
|
|
927
|
+
outcome: h.outcome,
|
|
928
|
+
ms: h.ms,
|
|
929
|
+
attempts: h.attempts.map((a) => ({
|
|
930
|
+
outcome: a.outcome,
|
|
931
|
+
ms: a.ms,
|
|
932
|
+
budget: a.budget,
|
|
933
|
+
woke: a.woke
|
|
934
|
+
})),
|
|
935
|
+
pageTargets: h.pageTargets,
|
|
936
|
+
evidence: h.evidence
|
|
937
|
+
});
|
|
938
|
+
try {
|
|
939
|
+
const path = probeLogPath();
|
|
940
|
+
mkdirSync(join(path, ".."), { recursive: true });
|
|
941
|
+
try {
|
|
942
|
+
if (statSync(path).size > 256 * 1024) {
|
|
943
|
+
const kept = readFileSync(path, "utf8").split("\n").slice(-500).join("\n");
|
|
944
|
+
writeFileSync(path, kept.endsWith("\n") ? kept : kept + "\n");
|
|
945
|
+
}
|
|
946
|
+
} catch {}
|
|
947
|
+
appendFileSync(path, line + "\n");
|
|
948
|
+
} catch {}
|
|
949
|
+
}
|
|
950
|
+
/** Recent probe timings, for `doctor`. Returns null when there is no history. */
|
|
951
|
+
function recentProbeStats(limit = 50) {
|
|
952
|
+
try {
|
|
953
|
+
const rows = readFileSync(probeLogPath(), "utf8").trim().split("\n").slice(-limit).map((l) => {
|
|
954
|
+
try {
|
|
955
|
+
return JSON.parse(l);
|
|
956
|
+
} catch {
|
|
957
|
+
return null;
|
|
958
|
+
}
|
|
959
|
+
}).filter(Boolean);
|
|
960
|
+
if (!rows.length) return null;
|
|
961
|
+
const okMs = rows.filter((r) => r.ok).map((r) => r.ms).sort((a, b) => a - b);
|
|
962
|
+
return {
|
|
963
|
+
n: rows.length,
|
|
964
|
+
failures: rows.filter((r) => !r.ok).length,
|
|
965
|
+
median: okMs.length ? okMs[Math.floor(okMs.length / 2)] : -1,
|
|
966
|
+
worst: okMs.length ? okMs[okMs.length - 1] : -1
|
|
967
|
+
};
|
|
968
|
+
} catch {
|
|
969
|
+
return null;
|
|
970
|
+
}
|
|
971
|
+
}
|
|
972
|
+
function evidenceLines(e) {
|
|
973
|
+
if (!e) return [];
|
|
974
|
+
const mach = e.rendezvous === true ? `registered for pid ${e.pid} — the permanent failure's signature is ABSENT` : e.rendezvous === false ? `NOT REGISTERED for pid ${e.pid} — this is the permanent failure` : `could not check (${e.pid ? `pid ${e.pid}, ` : "browser pid unknown, "}not macOS or launchctl unavailable)`;
|
|
975
|
+
const rend = e.renderers === null ? `could not count` : `${e.renderers} live renderer process(es) for this browser`;
|
|
976
|
+
return [` mach service: ${mach}`, ` renderers: ${rend}`];
|
|
977
|
+
}
|
|
978
|
+
/** The cheap recovery. Always printed, always before anything expensive. */
|
|
979
|
+
function cheapRecovery() {
|
|
980
|
+
return [
|
|
981
|
+
`Try these first, cheapest first:`,
|
|
982
|
+
``,
|
|
983
|
+
` 1. Run the command again. A new tab's renderer has been measured taking`,
|
|
984
|
+
` 12s and more on a loaded machine, and it is not broken, only late.`,
|
|
985
|
+
` 2. Use a tab that already works. An existing tab navigates same-origin`,
|
|
986
|
+
` without needing a new renderer, so it keeps working throughout:`,
|
|
987
|
+
` browser-automation list`,
|
|
988
|
+
` browser-automation eval -t <id> "location.href='<url>'"`,
|
|
989
|
+
` 3. browser-automation doctor — re-measures, and prints recent probe times.`
|
|
990
|
+
];
|
|
991
|
+
}
|
|
611
992
|
/**
|
|
612
993
|
* A ready-to-print explanation of a renderer failure, with the recovery.
|
|
613
994
|
*
|
|
614
995
|
* Written to be read by somebody who has just been told a site blocks them, so
|
|
615
|
-
* it says what is and is not true before it says what to do
|
|
996
|
+
* it says what is and is not true before it says what to do — and it says only
|
|
997
|
+
* what was actually established. The four verdicts get four different endings
|
|
998
|
+
* because they need four different actions, and exactly one of them is worth
|
|
999
|
+
* anybody's tabs.
|
|
616
1000
|
*/
|
|
617
1001
|
function explainRendererFailure(h) {
|
|
618
|
-
const
|
|
619
|
-
const
|
|
1002
|
+
const e = h.evidence ?? gatherEvidence();
|
|
1003
|
+
const verdict = h.verdict ?? rendererVerdict(h.outcome, e);
|
|
1004
|
+
const tried = h.attempts?.length ?? 1;
|
|
1005
|
+
const longest = h.attempts?.length ? Math.max(...h.attempts.map((a) => a.budget)) : 0;
|
|
1006
|
+
const woke = h.attempts?.some((a) => a.woke);
|
|
620
1007
|
const lines = [
|
|
621
|
-
`Chrome
|
|
1008
|
+
`Chrome did not give a new tab a working renderer.`,
|
|
622
1009
|
``,
|
|
623
|
-
` probe:
|
|
624
|
-
`
|
|
625
|
-
`
|
|
1010
|
+
` probe: ${tried} attempt(s), longest budget ${longest}ms, ${h.ms}ms total`,
|
|
1011
|
+
` ${h.reason ?? "no renderer answered"}`,
|
|
1012
|
+
...woke ? [` (it was also activated to force a renderer, and still did not answer)`] : [],
|
|
1013
|
+
` page targets: ${h.pageTargets} (context only — NOT the cause; a healthy Chrome has`,
|
|
1014
|
+
` been driven to 421 tabs with every renderer alive)`,
|
|
1015
|
+
...evidenceLines(e),
|
|
1016
|
+
``
|
|
626
1017
|
];
|
|
627
|
-
if (
|
|
628
|
-
else if (
|
|
629
|
-
lines.push(
|
|
1018
|
+
if (verdict === "wedged") lines.push(`VERDICT: this browser process can never make a renderer again.`, ``, `Chrome registers "com.google.Chrome.MachPortRendezvousServer.${e.pid}" once, at`, `startup, and every child process looks that name up to receive its shared`, `memory. The name is gone, so every renderer Chrome launches from now on exits`, `within milliseconds. Nothing re-registers it, and closing tabs does not help.`, ``, `This is NOT the site blocking automation. Two tells: same-origin navigations in`, `tabs that already work keep working (they reuse a renderer that exists), and`, `cross-origin ones fail with ERR_ABORTED (site isolation needs a new renderer).`, ``, ...cheapRecovery(), ``, `Only then, and only because the signature above is confirmed present, a restart`, `is the real fix:`, ``, ` browser-automation launch --restart # closes ALL tabs, for EVERY session`, ``, `Other sessions are driving this Chrome. Their open tabs go with it, and they`, `will not be told why — agree on it first. \`browser-automation list\` shows who`, `holds what.`);
|
|
1019
|
+
else if (verdict === "busy") lines.push(`VERDICT: Chrome is NOT in the permanent, restart-only state.`, ``, `Its Mach rendezvous service is registered and ${e.renderers} renderer processes are`, `alive. Both are absent in that failure, so whatever this is, a restart is not`, `the fix for it — the probe asked ${tried} times, waited up to ${longest}ms, and did not`, `get an answer. That happens on a loaded machine and it usually clears by itself.`, ``, ...cheapRecovery(), ``, `Do NOT restart Chrome on the strength of this message. \`launch --restart\` closes`, `every tab of every session sharing this browser, and the evidence above says`, `this is not the failure a restart fixes.`);
|
|
1020
|
+
else lines.push(`VERDICT: undiagnosed — and specifically, NOT confirmed as the permanent failure.`, ``, `The probe failed, but the signature of the restart-only condition (an ABSENT`, `Mach rendezvous service) could not be confirmed, so this may equally be a slow`, `or heavily loaded browser. Those need opposite responses, and guessing wrong`, `costs every session on this browser its tabs.`, ``, ...cheapRecovery(), ``, `If it keeps failing, get the corroboration before doing anything drastic:`, ``, ` browser-automation doctor`, ` tail -50 ${chromeLogPath()}`, ``, `A \`doctor\` that reports the Mach service ABSENT is the permanent failure, and`, `only that justifies \`launch --restart\` — which closes every tab for every`, `session sharing this Chrome.`);
|
|
630
1021
|
return lines.join("\n");
|
|
631
1022
|
}
|
|
632
1023
|
/**
|
|
633
|
-
* Does this error look like it could be
|
|
1024
|
+
* Does this error look like it could be a renderer failure rather than the site?
|
|
634
1025
|
*
|
|
635
|
-
* Kept deliberately narrow. These
|
|
636
|
-
*
|
|
637
|
-
*
|
|
1026
|
+
* Kept deliberately narrow. These are the ONLY shapes the failure takes through
|
|
1027
|
+
* the CLI, and each of them has an innocent explanation too — so a hit here
|
|
1028
|
+
* buys a probe, never a conclusion.
|
|
638
1029
|
*/
|
|
639
1030
|
function mayBeRendererFailure(err) {
|
|
640
1031
|
const m = String(err?.message ?? err);
|
|
641
|
-
return /Page\.enable timed out/i.test(m) || /net::ERR_ABORTED/i.test(m) || /Runtime\.evaluate timed out/i.test(m) || /Render process gone/i.test(m) || /CDP connect timeout/i.test(m);
|
|
1032
|
+
return /Page\.enable timed out/i.test(m) || /Target\.createTarget timed out/i.test(m) || /net::ERR_ABORTED/i.test(m) || /Runtime\.evaluate timed out/i.test(m) || /Render process gone/i.test(m) || /CDP connect timeout/i.test(m);
|
|
642
1033
|
}
|
|
643
1034
|
/**
|
|
644
|
-
* Run `fn`; if it fails in a way
|
|
1035
|
+
* Run `fn`; if it fails in a way a renderer failure could explain, spend one
|
|
645
1036
|
* probe finding out, and re-throw with the diagnosis attached.
|
|
646
1037
|
*
|
|
647
1038
|
* The probe only ever runs on the error path, so the happy path pays nothing.
|
|
648
1039
|
* If the probe comes back healthy the original error is re-thrown untouched —
|
|
649
|
-
*
|
|
650
|
-
* the browser
|
|
1040
|
+
* and since the probe now retries and can wake a late renderer, "healthy" is
|
|
1041
|
+
* the answer a loaded browser gets, which is the September bug not happening.
|
|
651
1042
|
*/
|
|
652
1043
|
async function withRendererDiagnosis(fn) {
|
|
653
1044
|
try {
|
|
@@ -683,21 +1074,22 @@ const newCommand = define({
|
|
|
683
1074
|
const name = ctx.values.session || defaultSessionName();
|
|
684
1075
|
const url = ctx.positionals[1] ? normalizeUrl(ctx.positionals[1]) : "about:blank";
|
|
685
1076
|
if (loadSession(name) && !ctx.values.force) consola.warn(`Session "${name}" already maps to a tab. Use --force to open another, or just \`browser-automation goto -s ${name} <url>\`.`);
|
|
686
|
-
const targetId = await createTab(url);
|
|
1077
|
+
const targetId = await withRendererDiagnosis(() => createTab(url));
|
|
687
1078
|
saveSession({
|
|
688
1079
|
name,
|
|
689
1080
|
targetId,
|
|
690
1081
|
url,
|
|
691
1082
|
createdAt: (/* @__PURE__ */ new Date()).toISOString()
|
|
692
1083
|
});
|
|
693
|
-
const
|
|
694
|
-
if (
|
|
1084
|
+
const r = await ensureRenderer(targetId);
|
|
1085
|
+
if (r.woke) consola.warn(`[${name}] 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.`);
|
|
1086
|
+
if (!r.ok) {
|
|
695
1087
|
const health = await probeRenderer().catch(() => null);
|
|
696
1088
|
if (health && !health.ok) {
|
|
697
1089
|
consola.error(`[${name}] tab ${targetId.slice(0, 12)}… was created but has no working renderer.\n\n${explainRendererFailure(health)}`);
|
|
698
1090
|
process.exit(1);
|
|
699
1091
|
}
|
|
700
|
-
consola.warn(`[${name}] tab ${targetId.slice(0, 12)}… did not answer yet (${
|
|
1092
|
+
consola.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.`);
|
|
701
1093
|
}
|
|
702
1094
|
consola.success(`[${name}] opened background tab ${targetId.slice(0, 12)}… → ${url}`);
|
|
703
1095
|
}
|
|
@@ -815,6 +1207,9 @@ const gotoCommand = define({
|
|
|
815
1207
|
const target = normalizeUrl(url);
|
|
816
1208
|
const opts = targetOpts(ctx.values);
|
|
817
1209
|
const { targetId, created } = await withRendererDiagnosis(() => resolveOrCreateTargetId(opts));
|
|
1210
|
+
if (created) {
|
|
1211
|
+
if ((await ensureRenderer(targetId)).woke) consola.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.");
|
|
1212
|
+
}
|
|
818
1213
|
await withRendererDiagnosis(() => navigate(targetId, target));
|
|
819
1214
|
if (!opts.match && !opts.target) {
|
|
820
1215
|
const name = opts.session || defaultSessionName();
|
|
@@ -2014,6 +2409,10 @@ const listCommand = define({
|
|
|
2014
2409
|
type: "boolean",
|
|
2015
2410
|
description: "Output raw JSON"
|
|
2016
2411
|
},
|
|
2412
|
+
all: {
|
|
2413
|
+
type: "boolean",
|
|
2414
|
+
description: "Also list stale session bookmarks (tabs that no longer exist), instead of just counting them"
|
|
2415
|
+
},
|
|
2017
2416
|
frames: {
|
|
2018
2417
|
type: "boolean",
|
|
2019
2418
|
description: "Also list cross-origin child iframes (OOPIFs) — their targetIds/URLs let you drive Stripe Elements, embedded SSO widgets, etc. via -F <substr> or -t <id>."
|
|
@@ -2032,11 +2431,15 @@ const listCommand = define({
|
|
|
2032
2431
|
return;
|
|
2033
2432
|
}
|
|
2034
2433
|
const liveIds = new Set(targets.map((t) => t.id));
|
|
2035
|
-
|
|
2036
|
-
|
|
2037
|
-
|
|
2038
|
-
|
|
2039
|
-
|
|
2434
|
+
const live = sessions.filter((s) => liveIds.has(s.targetId));
|
|
2435
|
+
const stale = sessions.filter((s) => !liveIds.has(s.targetId));
|
|
2436
|
+
const shown = ctx.values.all ? sessions : live;
|
|
2437
|
+
if (shown.length) {
|
|
2438
|
+
consola.log(`# sessions (${shown.length}${ctx.values.all ? "" : " live"})`);
|
|
2439
|
+
for (const s of shown) consola.log(` ${s.name.padEnd(16)} [${liveIds.has(s.targetId) ? "live" : "stale"}] ${s.url ?? ""}`);
|
|
2440
|
+
} else if (sessions.length) consola.log(`# sessions (0 live)`);
|
|
2441
|
+
if (stale.length && !ctx.values.all) consola.log(` + ${stale.length} stale bookmark(s) whose tab is gone — \`list --all\` to see them, \`gc --sessions\` to clear them`);
|
|
2442
|
+
if (sessions.length) consola.log("");
|
|
2040
2443
|
consola.log(`# open tabs (${targets.length}) — address with -t <id> or -m <substr>`);
|
|
2041
2444
|
for (const t of targets) {
|
|
2042
2445
|
const owner = sessions.find((s) => s.targetId === t.id);
|
|
@@ -2167,13 +2570,17 @@ const launchCommand = define({
|
|
|
2167
2570
|
ok: false,
|
|
2168
2571
|
ms: 0,
|
|
2169
2572
|
pageTargets: 0,
|
|
2170
|
-
reason: String(e?.message ?? e)
|
|
2573
|
+
reason: String(e?.message ?? e),
|
|
2574
|
+
outcome: "error",
|
|
2575
|
+
verdict: "unknown",
|
|
2576
|
+
attempts: []
|
|
2171
2577
|
}));
|
|
2172
2578
|
if (health.ok) {
|
|
2173
|
-
|
|
2579
|
+
const woke = health.attempts.some((a) => a.woke);
|
|
2580
|
+
consola.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.` + (woke ? " (It had to be activated to get there — this browser is slow to give background tabs a renderer.)" : ""));
|
|
2174
2581
|
return;
|
|
2175
2582
|
}
|
|
2176
|
-
consola.error("Chrome is up, but it
|
|
2583
|
+
consola.error(health.verdict === "wedged" ? "Chrome is up, but it can never make a renderer again — this browser is unusable.\n" : "Chrome is up, but a new tab did not get a working renderer in time.\n");
|
|
2177
2584
|
for (const line of explainRendererFailure(health).split("\n")) consola.log(line);
|
|
2178
2585
|
consola.log(`\nChrome's own log: ${chromeLogPath()}`);
|
|
2179
2586
|
process.exit(1);
|
|
@@ -2244,21 +2651,32 @@ const doctorCommand = define({
|
|
|
2244
2651
|
ok: false,
|
|
2245
2652
|
ms: 0,
|
|
2246
2653
|
pageTargets: 0,
|
|
2247
|
-
reason: String(e?.message ?? e)
|
|
2654
|
+
reason: String(e?.message ?? e),
|
|
2655
|
+
outcome: "error",
|
|
2656
|
+
verdict: "unknown",
|
|
2657
|
+
attempts: []
|
|
2248
2658
|
}));
|
|
2249
2659
|
if (health.ok) {
|
|
2660
|
+
const woke = health.attempts.some((a) => a.woke);
|
|
2250
2661
|
ok(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms`);
|
|
2251
|
-
|
|
2252
|
-
|
|
2253
|
-
consola.log(`
|
|
2662
|
+
if (woke) {
|
|
2663
|
+
consola.log(` ⚠ it only answered after being activated — this Chrome is slow to give`);
|
|
2664
|
+
consola.log(` BACKGROUND tabs a renderer (measured: median 367ms, tail past 30s).`);
|
|
2665
|
+
consola.log(` Commands will work; new tabs may briefly raise the Chrome window.`);
|
|
2666
|
+
}
|
|
2667
|
+
const ev = gatherEvidence();
|
|
2668
|
+
if (ev.rendezvous === false) {
|
|
2669
|
+
consola.log(` ⚠ but the Mach rendezvous service for pid ${ev.pid} is NOT registered —`);
|
|
2254
2670
|
consola.log(` new renderers are expected to start failing. Restart Chrome soon:`);
|
|
2255
2671
|
consola.log(` browser-automation launch --restart`);
|
|
2256
2672
|
}
|
|
2257
2673
|
} else {
|
|
2258
|
-
bad(`Renderer capacity: FAILED`);
|
|
2674
|
+
bad(`Renderer capacity: FAILED (${health.verdict})`);
|
|
2259
2675
|
for (const line of explainRendererFailure(health).split("\n")) consola.log(` ${line}`);
|
|
2260
2676
|
consola.log(` Chrome's own log: ${chromeLogPath()}`);
|
|
2261
2677
|
}
|
|
2678
|
+
const stats = recentProbeStats();
|
|
2679
|
+
if (stats) consola.log(` • last ${stats.n} renderer probe(s): ${stats.failures} failed` + (stats.median >= 0 ? `, median ${stats.median}ms, slowest success ${stats.worst}ms` : ""));
|
|
2262
2680
|
const sessions = listSessions();
|
|
2263
2681
|
let live = 0;
|
|
2264
2682
|
try {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.12",
|
|
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
|
@@ -104,7 +104,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
104
104
|
| Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
|
|
105
105
|
| Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
|
|
106
106
|
| Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
|
|
107
|
-
| Restart Chrome (
|
|
107
|
+
| Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
|
|
108
108
|
| Forget a session (tab stays open) | `browser-automation close -s work` |
|
|
109
109
|
| Forget **and** close the browser tab | `browser-automation close -s work --tab` |
|
|
110
110
|
|
|
@@ -287,11 +287,49 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
287
287
|
isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
|
|
288
288
|
confirm processing started, then grab the result (often a download endpoint you
|
|
289
289
|
can pull with `download --url`).
|
|
290
|
+
- **A NEW tab's renderer can be slow rather than broken — do not restart Chrome for it.**
|
|
291
|
+
⚠️ **Read this before acting on the wedge diagnosis below.** Measured 2026-09-11 on
|
|
292
|
+
Chrome 152.0.7977.83, time from `Target.createTarget` to the first `Runtime.evaluate`
|
|
293
|
+
returning, 8 trials each:
|
|
294
|
+
|
|
295
|
+
| how the target was created | median | worst |
|
|
296
|
+
|---|---|---|
|
|
297
|
+
| `background: true` (how this tool opens every tab) | 367ms | 12517ms, and >30s once |
|
|
298
|
+
| `background: true` + `Target.activateTarget` | 19ms | 65ms |
|
|
299
|
+
| `background: false` | 18ms | 22ms |
|
|
300
|
+
|
|
301
|
+
The renderer **process exists** in every arm — `ps` gains a `--type=renderer` child either
|
|
302
|
+
way. A background target is simply not given a renderer that answers promptly, and on a
|
|
303
|
+
loaded machine (this one was at load average 38) the tail runs past any budget worth
|
|
304
|
+
waiting. **This is not the wedge**, and a restart does nothing for it.
|
|
305
|
+
|
|
306
|
+
It cost real work to learn: for three weeks `goto` reported this as the permanent,
|
|
307
|
+
restart-only condition below, and `launch --restart` closes every tab of every session
|
|
308
|
+
sharing this Chrome. It twice destroyed unrecoverable work belonging to another session —
|
|
309
|
+
a finished AlternativeTo submission with hand edits, and an Azure signup flow mid-form.
|
|
310
|
+
|
|
311
|
+
**Since fixed (v0.4.12+):** `new`/`goto` wait for a late renderer and, if it still has not
|
|
312
|
+
answered, briefly activate the tab to force one and hand the window straight back (you get
|
|
313
|
+
a `WARN` saying so). The probe retries with a doubling budget, and the verdict now names
|
|
314
|
+
the permanent failure **only when its own signature is present**. On an older CLI, the
|
|
315
|
+
cheap move is to retry, or to drive a tab that already works.
|
|
316
|
+
|
|
317
|
+
**Whatever the version: before restarting anything, check the two corroborations.** Both
|
|
318
|
+
were decisive and neither used to be consulted:
|
|
319
|
+
```bash
|
|
320
|
+
launchctl print "gui/$(id -u)" | grep MachPortRendezvousServer.<browser-pid>
|
|
321
|
+
ps -Ao command= | grep -c -- '--type=renderer'
|
|
322
|
+
```
|
|
323
|
+
Mach name **present** + renderers **alive** ⇒ this is slowness, not the wedge. Retry, or use
|
|
324
|
+
a live tab. Mach name **absent** ⇒ it is the wedge, and only then is a restart the answer.
|
|
325
|
+
|
|
290
326
|
- **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
|
|
291
327
|
A browser process can permanently lose the ability to launch **renderer processes** while
|
|
292
328
|
looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
|
|
293
329
|
until you open a tab or navigate somewhere new, and then the errors read as the remote site's
|
|
294
330
|
doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
|
|
331
|
+
⚠️ **This is a real condition and a rare one.** Confirm the Mach name is absent (above)
|
|
332
|
+
before you believe it — a slow background renderer produces every symptom in this list.
|
|
295
333
|
|
|
296
334
|
How it shows up:
|
|
297
335
|
- `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
|
|
@@ -366,18 +404,34 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
366
404
|
`Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
|
|
367
405
|
site's bot-protection docs.
|
|
368
406
|
|
|
369
|
-
**Recovery —
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
407
|
+
**Recovery — cheapest first, and a restart only once the Mach name is confirmed absent.**
|
|
408
|
+
|
|
409
|
+
1. **Retry.** A new tab's renderer has been measured taking 12s and more on a loaded
|
|
410
|
+
machine, and late is not broken.
|
|
411
|
+
2. **Drive a tab that already works.** An existing tab navigates same-origin without
|
|
412
|
+
needing a new renderer, so it keeps working throughout even during a genuine wedge:
|
|
413
|
+
```bash
|
|
414
|
+
browser-automation list
|
|
415
|
+
browser-automation eval -t <id> "location.href='<url>'"
|
|
416
|
+
```
|
|
417
|
+
3. **`browser-automation doctor`** — re-measures, prints the two corroborations, and shows
|
|
418
|
+
the recent probe-time distribution from `~/.browser-automation/renderer-probes.jsonl`.
|
|
419
|
+
4. **Only if `doctor` reports the Mach rendezvous service ABSENT**, restart. The bootstrap
|
|
420
|
+
name is registered at startup and never re-registered, so nothing short of a new browser
|
|
421
|
+
process helps; closing tabs does not, and plain `launch` will not either (idempotent by
|
|
422
|
+
design — it sees a live browser and exits happy):
|
|
423
|
+
```bash
|
|
424
|
+
browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
|
|
425
|
+
```
|
|
426
|
+
It reports how many tabs it is about to close. **Those tabs belong to every parallel
|
|
427
|
+
Claude Code session sharing this Chrome — ask Fred first, never restart unilaterally.**
|
|
377
428
|
|
|
378
429
|
**Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
|
|
379
430
|
(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.
|
|
431
|
+
closes tabs whose renderer does not answer. Use `--dry` first. `list` now counts stale
|
|
432
|
+
bookmarks instead of printing them (`list --all` to see them) — 105 stale lines above a
|
|
433
|
+
24-tab Chrome is how "there are a hundred tabs open" became the leading theory for a
|
|
434
|
+
renderer failure that has nothing to do with tab count. It is genuinely useful, but it is
|
|
381
435
|
**not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
|
|
382
436
|
— tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
|
|
383
437
|
nobody wants it.
|