webhand 0.3.0 → 0.4.0
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/README.ja.md +19 -4
- package/README.md +19 -4
- package/assets/recorder.js +4 -0
- package/assets/snapshot.js +218 -3
- package/dist/agent.js +136 -9
- package/dist/auth.js +62 -0
- package/dist/browser.js +701 -22
- package/dist/cli.js +641 -35
- package/dist/collect.js +70 -0
- package/dist/compare.js +173 -0
- package/dist/daemon.js +125 -0
- package/dist/knowledge.js +206 -0
- package/dist/learn.js +10 -3
- package/dist/metrics.js +19 -2
- package/dist/more.js +58 -0
- package/dist/policies/base.js +105 -9
- package/dist/policies/jev.js +243 -16
- package/dist/remote.js +165 -0
- package/dist/runbook.js +6 -1
- package/dist/session.js +256 -12
- package/dist/types.js +12 -0
- package/package.json +1 -1
package/dist/remote.js
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A browser that lives in another process. Lightpanda drops its pages when a CDP connection ends, so a daemon
|
|
3
|
+
* (daemon.ts) holds the connection and the page for the whole session, and each CLI command talks to it over a
|
|
4
|
+
* unix socket. RemoteBrowser has the shape of Browser for what the CLI uses; the daemon runs the real Browser,
|
|
5
|
+
* freshness check and all, so nothing is acted on without it.
|
|
6
|
+
*
|
|
7
|
+
* Wire format: one JSON object per line. Request {id, method, params, view}; reply {id, result} or
|
|
8
|
+
* {id, error: {name, message, changed}}.
|
|
9
|
+
*/
|
|
10
|
+
import { connect } from "node:net";
|
|
11
|
+
import { MutationUncertain, StalePage } from "./types.js";
|
|
12
|
+
/** The only methods the daemon runs for a client. */
|
|
13
|
+
export const METHODS = [
|
|
14
|
+
"version",
|
|
15
|
+
"observe",
|
|
16
|
+
"fresh",
|
|
17
|
+
"act",
|
|
18
|
+
"contexts",
|
|
19
|
+
"goto",
|
|
20
|
+
"rows",
|
|
21
|
+
"listEnd",
|
|
22
|
+
"check",
|
|
23
|
+
"unseen",
|
|
24
|
+
"ignoredWindows",
|
|
25
|
+
"screenshot",
|
|
26
|
+
"evaluate",
|
|
27
|
+
"storageState",
|
|
28
|
+
"restore",
|
|
29
|
+
"shutdown",
|
|
30
|
+
];
|
|
31
|
+
export function failure(error) {
|
|
32
|
+
if (error instanceof StalePage)
|
|
33
|
+
return { name: error.name, message: error.message, changed: error.changed };
|
|
34
|
+
if (error instanceof Error)
|
|
35
|
+
return { name: error.name, message: error.message };
|
|
36
|
+
return { name: "Error", message: String(error) };
|
|
37
|
+
}
|
|
38
|
+
/** The error the daemon saw, as the same class the CLI's callers already catch. */
|
|
39
|
+
function revive(error) {
|
|
40
|
+
if (error.name === "StalePage")
|
|
41
|
+
return new StalePage(error.message, error.changed ?? []);
|
|
42
|
+
if (error.name === "MutationUncertain")
|
|
43
|
+
return new MutationUncertain(error.message);
|
|
44
|
+
return new Error(error.message);
|
|
45
|
+
}
|
|
46
|
+
/** Splits a stream into lines; the last partial line waits for more. */
|
|
47
|
+
export function lines(onLine) {
|
|
48
|
+
let rest = "";
|
|
49
|
+
return (chunk) => {
|
|
50
|
+
rest += chunk.toString("utf8");
|
|
51
|
+
for (let at = rest.indexOf("\n"); at >= 0; at = rest.indexOf("\n")) {
|
|
52
|
+
const line = rest.slice(0, at);
|
|
53
|
+
rest = rest.slice(at + 1);
|
|
54
|
+
if (line)
|
|
55
|
+
onLine(line);
|
|
56
|
+
}
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
export class RemoteBrowser {
|
|
60
|
+
view;
|
|
61
|
+
version = "";
|
|
62
|
+
socket;
|
|
63
|
+
nextId = 1;
|
|
64
|
+
pending = new Map();
|
|
65
|
+
constructor(socket, view) {
|
|
66
|
+
this.socket = socket;
|
|
67
|
+
this.view = view;
|
|
68
|
+
socket.on("data", lines((line) => {
|
|
69
|
+
const reply = JSON.parse(line);
|
|
70
|
+
const waiting = this.pending.get(reply.id);
|
|
71
|
+
if (!waiting)
|
|
72
|
+
return;
|
|
73
|
+
this.pending.delete(reply.id);
|
|
74
|
+
if ("error" in reply)
|
|
75
|
+
waiting.reject(revive(reply.error));
|
|
76
|
+
else
|
|
77
|
+
waiting.resolve(reply.result);
|
|
78
|
+
}));
|
|
79
|
+
const lost = () => {
|
|
80
|
+
for (const waiting of this.pending.values())
|
|
81
|
+
waiting.reject(new Error("The browser daemon closed the connection"));
|
|
82
|
+
this.pending.clear();
|
|
83
|
+
};
|
|
84
|
+
socket.on("close", lost);
|
|
85
|
+
socket.on("error", lost);
|
|
86
|
+
}
|
|
87
|
+
/** Connects to the session's daemon. Nothing on the page changes. */
|
|
88
|
+
static async connect(path, view = null) {
|
|
89
|
+
const socket = await new Promise((resolve, reject) => {
|
|
90
|
+
const opened = connect(path);
|
|
91
|
+
opened.once("connect", () => resolve(opened));
|
|
92
|
+
opened.once("error", reject);
|
|
93
|
+
});
|
|
94
|
+
const remote = new RemoteBrowser(socket, view);
|
|
95
|
+
try {
|
|
96
|
+
remote.version = (await remote.call("version"));
|
|
97
|
+
}
|
|
98
|
+
catch (error) {
|
|
99
|
+
await remote.close();
|
|
100
|
+
throw error;
|
|
101
|
+
}
|
|
102
|
+
return remote;
|
|
103
|
+
}
|
|
104
|
+
// biome-ignore lint/suspicious/noExplicitAny: results are the browser method's own JSON.
|
|
105
|
+
call(method, ...params) {
|
|
106
|
+
return new Promise((resolve, reject) => {
|
|
107
|
+
const id = this.nextId++;
|
|
108
|
+
this.pending.set(id, { resolve, reject });
|
|
109
|
+
const request = { id, method, params, view: this.view };
|
|
110
|
+
this.socket.write(`${JSON.stringify(request)}\n`, (error) => {
|
|
111
|
+
if (error) {
|
|
112
|
+
this.pending.delete(id);
|
|
113
|
+
reject(error);
|
|
114
|
+
}
|
|
115
|
+
});
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
observe() {
|
|
119
|
+
return this.call("observe");
|
|
120
|
+
}
|
|
121
|
+
fresh(page, action = null) {
|
|
122
|
+
return this.call("fresh", page, action);
|
|
123
|
+
}
|
|
124
|
+
async act(action, page, text = null) {
|
|
125
|
+
await this.call("act", action, page, text);
|
|
126
|
+
}
|
|
127
|
+
contexts(nodes) {
|
|
128
|
+
return this.call("contexts", nodes);
|
|
129
|
+
}
|
|
130
|
+
async goto(url) {
|
|
131
|
+
await this.call("goto", url);
|
|
132
|
+
}
|
|
133
|
+
rows() {
|
|
134
|
+
return this.call("rows");
|
|
135
|
+
}
|
|
136
|
+
listEnd() {
|
|
137
|
+
return this.call("listEnd");
|
|
138
|
+
}
|
|
139
|
+
check() {
|
|
140
|
+
return this.call("check");
|
|
141
|
+
}
|
|
142
|
+
unseen() {
|
|
143
|
+
return this.call("unseen");
|
|
144
|
+
}
|
|
145
|
+
ignoredWindows() {
|
|
146
|
+
return this.call("ignoredWindows");
|
|
147
|
+
}
|
|
148
|
+
async screenshot() {
|
|
149
|
+
return Buffer.from((await this.call("screenshot")), "base64");
|
|
150
|
+
}
|
|
151
|
+
/** Read-only evaluation, for a research task's independent verification. */
|
|
152
|
+
evaluate(expression, options = {}) {
|
|
153
|
+
return this.call("evaluate", expression, options);
|
|
154
|
+
}
|
|
155
|
+
storageState() {
|
|
156
|
+
return this.call("storageState");
|
|
157
|
+
}
|
|
158
|
+
restore(state, url) {
|
|
159
|
+
return this.call("restore", state, url);
|
|
160
|
+
}
|
|
161
|
+
/** Ends this connection only. The daemon, its browser and the page stay until the session is stopped. */
|
|
162
|
+
async close() {
|
|
163
|
+
this.socket.destroy();
|
|
164
|
+
}
|
|
165
|
+
}
|
package/dist/runbook.js
CHANGED
|
@@ -19,6 +19,8 @@ const ACTORS = new Set(["jev", "human"]);
|
|
|
19
19
|
const STATUSES = new Set(["draft", "approved"]);
|
|
20
20
|
const DEFAULTS = new Set(["focus", "skip"]); // A region's default in service.toml. Without one, it is observed as usual.
|
|
21
21
|
const SERVICE_FILE = "service"; // runbooks/<service>/service.toml holds the service information.
|
|
22
|
+
/** Kinds the read layer can hold, by page structure. `none` clears an earlier choice. */
|
|
23
|
+
export const READ_KINDS = ["outline", "text", "table", "list", "link", "control", "media"];
|
|
22
24
|
/** The runbook folder of a scope, whether or not it exists. */
|
|
23
25
|
export function root(scope = "project") {
|
|
24
26
|
return join(scopeRoot(scope), "runbooks");
|
|
@@ -125,7 +127,10 @@ function regions(file, page) {
|
|
|
125
127
|
export function view(...layers) {
|
|
126
128
|
let focus = [];
|
|
127
129
|
let skip = [];
|
|
130
|
+
let read;
|
|
128
131
|
for (const layer of layers) {
|
|
132
|
+
if (layer?.read?.length)
|
|
133
|
+
read = layer.read.includes("none") ? undefined : [...layer.read]; // The later choice wins.
|
|
129
134
|
if (blank(layer))
|
|
130
135
|
continue;
|
|
131
136
|
const newFocus = [...(layer?.focus ?? [])];
|
|
@@ -134,7 +139,7 @@ export function view(...layers) {
|
|
|
134
139
|
focus = [...newFocus, ...focus.filter(kept)];
|
|
135
140
|
skip = [...skip.filter(kept), ...newSkip];
|
|
136
141
|
}
|
|
137
|
-
return { focus, skip };
|
|
142
|
+
return read ? { focus, skip, read } : { focus, skip };
|
|
138
143
|
}
|
|
139
144
|
/** What the service information says to focus on or skip on every page. */
|
|
140
145
|
export function serviceView(info) {
|
package/dist/session.js
CHANGED
|
@@ -11,14 +11,31 @@
|
|
|
11
11
|
*/
|
|
12
12
|
import { execFileSync, spawn } from "node:child_process";
|
|
13
13
|
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
|
|
14
|
-
import {
|
|
14
|
+
import { connect, createServer } from "node:net";
|
|
15
|
+
import { homedir, tmpdir } from "node:os";
|
|
15
16
|
import { delimiter, join } from "node:path";
|
|
17
|
+
import { fileURLToPath } from "node:url";
|
|
16
18
|
import { chromium } from "playwright-core";
|
|
17
19
|
import { quote, sleep } from "./format.js";
|
|
18
20
|
import * as workspace from "./workspace.js";
|
|
19
|
-
|
|
21
|
+
/** How long a browser may take to start. Tests set WEBHAND_STARTUP_MS higher: several suites at once load the machine. */
|
|
22
|
+
const STARTUP_MS = Number(process.env.WEBHAND_STARTUP_MS) || 15_000;
|
|
20
23
|
const PROFILE_NAME = /^[\p{L}\p{N}_-]+$/u;
|
|
24
|
+
/** Where Chrome runs (--chrome). */
|
|
21
25
|
export const CHROMES = ["auto", "linux", "windows"];
|
|
26
|
+
/** Engines that run as `serve` behind a daemon: no window, no saved profile, and pages that end with a CDP connection. */
|
|
27
|
+
const ENGINES = ["lightpanda", "obscura"];
|
|
28
|
+
/** What runs the browser (--engine). auto is the default: see chooseEngine. */
|
|
29
|
+
export const ENGINE_CHOICES = ["auto", "chrome", "headless-shell", ...ENGINES];
|
|
30
|
+
const ENGINE_NAMES = {
|
|
31
|
+
"headless-shell": "Chrome headless shell",
|
|
32
|
+
lightpanda: "Lightpanda",
|
|
33
|
+
obscura: "Obscura",
|
|
34
|
+
};
|
|
35
|
+
/** How a session's browser reads in output: "Lightpanda", or "linux Chrome". */
|
|
36
|
+
export function hostName(engine, chrome) {
|
|
37
|
+
return ENGINE_NAMES[engine] ?? `${chrome} Chrome`;
|
|
38
|
+
}
|
|
22
39
|
const WINDOWS_CHROME = [
|
|
23
40
|
"/mnt/c/Program Files/Google/Chrome/Application/chrome.exe",
|
|
24
41
|
"/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe",
|
|
@@ -30,20 +47,92 @@ export class SessionError extends Error {
|
|
|
30
47
|
export function home() {
|
|
31
48
|
return join(workspace.home(), "state");
|
|
32
49
|
}
|
|
50
|
+
export const DEFAULT_ID = "default";
|
|
51
|
+
const ID_PATTERN = /^[A-Za-z0-9_-]{1,40}$/;
|
|
52
|
+
let currentId = DEFAULT_ID;
|
|
53
|
+
/** Which session the commands that follow work on. Several can run at once, each with its own Chrome and state. */
|
|
54
|
+
export function use(id = DEFAULT_ID) {
|
|
55
|
+
if (!ID_PATTERN.test(id))
|
|
56
|
+
throw new SessionError(`Expected --id of letters, digits, - or _ (up to 40), got ${quote(id)}`);
|
|
57
|
+
currentId = id;
|
|
58
|
+
}
|
|
59
|
+
export function id() {
|
|
60
|
+
return currentId;
|
|
61
|
+
}
|
|
62
|
+
/** The value of --id (or --id=ID) in the arguments, for callers that look at the session before main() does. */
|
|
63
|
+
export function idFrom(argv) {
|
|
64
|
+
for (let i = 0; i < argv.length; i++) {
|
|
65
|
+
if (argv[i] === "--id")
|
|
66
|
+
return argv[i + 1] ?? "";
|
|
67
|
+
if (argv[i].startsWith("--id="))
|
|
68
|
+
return argv[i].slice("--id=".length);
|
|
69
|
+
}
|
|
70
|
+
return DEFAULT_ID;
|
|
71
|
+
}
|
|
72
|
+
/** The default session keeps the file names it always had. */
|
|
73
|
+
function file(stem, extension = "") {
|
|
74
|
+
return join(home(), currentId === DEFAULT_ID ? `${stem}${extension}` : `${stem}-${currentId}${extension}`);
|
|
75
|
+
}
|
|
33
76
|
function path() {
|
|
34
|
-
return
|
|
77
|
+
return file("session", ".json");
|
|
78
|
+
}
|
|
79
|
+
/** Where the tab the run is on is kept between commands. */
|
|
80
|
+
export function tabPath() {
|
|
81
|
+
return file("tab");
|
|
35
82
|
}
|
|
36
83
|
export function load() {
|
|
37
84
|
return existsSync(path()) ? JSON.parse(readFileSync(path(), "utf8")) : null;
|
|
38
85
|
}
|
|
86
|
+
/** Every session that is open, by id. */
|
|
87
|
+
export function active() {
|
|
88
|
+
if (!existsSync(home()))
|
|
89
|
+
return [];
|
|
90
|
+
const found = [];
|
|
91
|
+
for (const name of readdirSync(home())) {
|
|
92
|
+
const match = /^session(?:-([A-Za-z0-9_-]+))?\.json$/.exec(name);
|
|
93
|
+
if (!match)
|
|
94
|
+
continue;
|
|
95
|
+
try {
|
|
96
|
+
found.push([match[1] ?? DEFAULT_ID, JSON.parse(readFileSync(join(home(), name), "utf8"))]);
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
// A file being replaced; the next listing sees it.
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return found;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* One command at a time per session: two `run`s on the same Chrome would act twice. The lock holds the pid of the
|
|
106
|
+
* command, so one left by a command that died is taken over. Returns the release function.
|
|
107
|
+
*/
|
|
108
|
+
export function lock() {
|
|
109
|
+
mkdirSync(home(), { recursive: true });
|
|
110
|
+
const target = file("session", ".lock");
|
|
111
|
+
for (let attempt = 0;; attempt++) {
|
|
112
|
+
try {
|
|
113
|
+
writeFileSync(target, String(process.pid), { flag: "wx", mode: 0o600 });
|
|
114
|
+
return () => rmSync(target, { force: true });
|
|
115
|
+
}
|
|
116
|
+
catch (error) {
|
|
117
|
+
if (error.code !== "EEXIST")
|
|
118
|
+
throw error;
|
|
119
|
+
const holder = Number.parseInt(readFileSync(target, "utf8"), 10);
|
|
120
|
+
if (attempt > 0 || (Number.isInteger(holder) && holder !== process.pid && alive(holder))) {
|
|
121
|
+
throw new SessionError(`Session ${quote(currentId)} is busy: another webhand command is using it (pid ${holder}). Wait for it, or use another --id`);
|
|
122
|
+
}
|
|
123
|
+
rmSync(target, { force: true });
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
39
127
|
export function save(state) {
|
|
40
128
|
mkdirSync(home(), { recursive: true });
|
|
41
|
-
const temporary =
|
|
129
|
+
const temporary = file("session", ".tmp");
|
|
42
130
|
writeFileSync(temporary, JSON.stringify(state), { encoding: "utf8", mode: 0o600 });
|
|
43
131
|
renameSync(temporary, path());
|
|
44
132
|
}
|
|
45
133
|
export function clear() {
|
|
46
134
|
rmSync(path(), { force: true });
|
|
135
|
+
rmSync(tabPath(), { force: true });
|
|
47
136
|
}
|
|
48
137
|
/** 'new' gives null; 'profile:NAME' gives NAME. */
|
|
49
138
|
export function parseSession(spec) {
|
|
@@ -79,6 +168,9 @@ export const probes = {
|
|
|
79
168
|
windowsChrome() {
|
|
80
169
|
return WINDOWS_CHROME.find(isFile) ?? null;
|
|
81
170
|
},
|
|
171
|
+
headlessShell() {
|
|
172
|
+
return shellBinary();
|
|
173
|
+
},
|
|
82
174
|
networkingMode() {
|
|
83
175
|
try {
|
|
84
176
|
return run("wslinfo", ["--networking-mode"], { timeout: 5000 }) || null;
|
|
@@ -91,6 +183,20 @@ export const probes = {
|
|
|
91
183
|
return run("wslpath", ["-w", path]);
|
|
92
184
|
},
|
|
93
185
|
};
|
|
186
|
+
/**
|
|
187
|
+
* What auto means. A run that needs no window and no saved profile uses the headless shell when one is installed:
|
|
188
|
+
* half the memory, the same results (see docs/research-plan.md). A window or a profile keeps Chrome, and so does
|
|
189
|
+
* asking for the Windows Chrome (--chrome windows; --chrome auto only says "use it if you can", and a headless run
|
|
190
|
+
* gains nothing from it). A missing shell falls back to Chrome quietly: that is what the run used before. A named
|
|
191
|
+
* engine is taken as asked. `chrome` is what --chrome asked for, not where it resolved to.
|
|
192
|
+
*/
|
|
193
|
+
export function chooseEngine(engine, options) {
|
|
194
|
+
if (engine !== "auto")
|
|
195
|
+
return engine;
|
|
196
|
+
if (options.headed || options.profile || options.chrome === "windows")
|
|
197
|
+
return "chrome";
|
|
198
|
+
return probes.headlessShell() ? "headless-shell" : "chrome";
|
|
199
|
+
}
|
|
94
200
|
function windowsLocalAppData() {
|
|
95
201
|
let folder = "";
|
|
96
202
|
try {
|
|
@@ -164,10 +270,12 @@ export function chromeArgs(executable, userDataDir, options) {
|
|
|
164
270
|
"--no-first-run",
|
|
165
271
|
"--no-default-browser-check",
|
|
166
272
|
"--hide-crash-restore-bubble",
|
|
167
|
-
|
|
273
|
+
// Chrome's window includes 87px of browser UI, so 1120x867 shows a 1120x780 page. The headless shell has no UI:
|
|
274
|
+
// its window is the page, so it takes the page size. The same viewport, or the two read different elements.
|
|
275
|
+
options.shell ? "--window-size=1120,780" : "--window-size=1120,867",
|
|
168
276
|
"about:blank",
|
|
169
277
|
];
|
|
170
|
-
if (!options.headed)
|
|
278
|
+
if (!options.headed && !options.shell)
|
|
171
279
|
args.splice(1, 0, "--headless=new");
|
|
172
280
|
return args;
|
|
173
281
|
}
|
|
@@ -181,6 +289,33 @@ async function reachable(port) {
|
|
|
181
289
|
return false;
|
|
182
290
|
}
|
|
183
291
|
}
|
|
292
|
+
/** chrome-headless-shell: WEBHAND_HEADLESS_SHELL, PATH, or the newest one in Playwright's browser cache. */
|
|
293
|
+
function shellBinary() {
|
|
294
|
+
const given = process.env.WEBHAND_HEADLESS_SHELL;
|
|
295
|
+
if (given && isFile(given))
|
|
296
|
+
return given;
|
|
297
|
+
const onPath = which("chrome-headless-shell");
|
|
298
|
+
if (onPath)
|
|
299
|
+
return onPath;
|
|
300
|
+
const cache = process.env.PLAYWRIGHT_BROWSERS_PATH ?? join(homedir(), ".cache", "ms-playwright");
|
|
301
|
+
let builds = [];
|
|
302
|
+
try {
|
|
303
|
+
builds = readdirSync(cache).filter((name) => name.startsWith("chromium_headless_shell-"));
|
|
304
|
+
}
|
|
305
|
+
catch {
|
|
306
|
+
return null;
|
|
307
|
+
}
|
|
308
|
+
builds.sort((a, b) => Number.parseInt(b.split("-")[1], 10) - Number.parseInt(a.split("-")[1], 10));
|
|
309
|
+
for (const build of builds) {
|
|
310
|
+
const folder = join(cache, build);
|
|
311
|
+
for (const inner of readdirSync(folder).filter((name) => name.startsWith("chrome-headless-shell"))) {
|
|
312
|
+
const binary = join(folder, inner, "chrome-headless-shell");
|
|
313
|
+
if (isFile(binary))
|
|
314
|
+
return binary;
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
return null;
|
|
318
|
+
}
|
|
184
319
|
function which(command) {
|
|
185
320
|
for (const dir of (process.env.PATH ?? "").split(delimiter)) {
|
|
186
321
|
const file = join(dir, command);
|
|
@@ -197,13 +332,98 @@ function childExited(pid) {
|
|
|
197
332
|
return null;
|
|
198
333
|
return child.exitCode !== null || child.signalCode !== null;
|
|
199
334
|
}
|
|
335
|
+
async function freePort() {
|
|
336
|
+
return await new Promise((resolve, reject) => {
|
|
337
|
+
const server = createServer();
|
|
338
|
+
server.once("error", reject);
|
|
339
|
+
server.listen(0, "127.0.0.1", () => {
|
|
340
|
+
const { port } = server.address();
|
|
341
|
+
server.close(() => resolve(port));
|
|
342
|
+
});
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
/** Whether something accepts connections on this unix socket. */
|
|
346
|
+
async function listening(path) {
|
|
347
|
+
return await new Promise((resolve) => {
|
|
348
|
+
const probe = connect(path);
|
|
349
|
+
probe.once("connect", () => {
|
|
350
|
+
probe.destroy();
|
|
351
|
+
resolve(true);
|
|
352
|
+
});
|
|
353
|
+
probe.once("error", () => resolve(false));
|
|
354
|
+
});
|
|
355
|
+
}
|
|
356
|
+
/** daemon.ts, or daemon.js once built. */
|
|
357
|
+
function daemonScript() {
|
|
358
|
+
const ts = import.meta.url.endsWith(".ts");
|
|
359
|
+
return fileURLToPath(new URL(ts ? "./daemon.ts" : "./daemon.js", import.meta.url));
|
|
360
|
+
}
|
|
361
|
+
/** Where an engine's binary is: PATH, or WEBHAND_OBSCURA for Obscura (its release archive is not installed anywhere). */
|
|
362
|
+
function engineBinary(engine) {
|
|
363
|
+
const given = engine === "obscura" ? process.env.WEBHAND_OBSCURA : undefined;
|
|
364
|
+
return given && isFile(given) ? given : which(engine);
|
|
365
|
+
}
|
|
366
|
+
/**
|
|
367
|
+
* An engine (Lightpanda, Obscura) has no window and no profile, and drops its pages when a CDP connection ends. A
|
|
368
|
+
* daemon runs it and holds the connection for the session; commands reach the page through state.socket (see
|
|
369
|
+
* daemon.ts, remote.ts). Asks for a saved profile or a window fail here rather than being quietly dropped.
|
|
370
|
+
*/
|
|
371
|
+
async function startEngine(engine, options) {
|
|
372
|
+
const name = hostName(engine, "linux");
|
|
373
|
+
if (options.profile)
|
|
374
|
+
throw new SessionError(`${name} has no saved profile. Use --session new`);
|
|
375
|
+
if (options.headed)
|
|
376
|
+
throw new SessionError(`${name} has no window, so --headed is not available`);
|
|
377
|
+
const executable = engineBinary(engine);
|
|
378
|
+
if (!executable)
|
|
379
|
+
throw new SessionError(`${engine} was not found on PATH`);
|
|
380
|
+
const port = await freePort();
|
|
381
|
+
const folder = mkdtempSync(join(tmpdir(), "webhand-")); // Holds the socket; removed when the session stops.
|
|
382
|
+
const socket = join(folder, "rpc.sock");
|
|
383
|
+
const child = spawn(process.execPath, [daemonScript(), socket, engine, executable, String(port)], {
|
|
384
|
+
detached: true, // its own process group, so it outlives this CLI call and stops as a group with the engine
|
|
385
|
+
stdio: "ignore",
|
|
386
|
+
});
|
|
387
|
+
child.on("error", () => { });
|
|
388
|
+
child.unref();
|
|
389
|
+
const pid = child.pid;
|
|
390
|
+
children.set(pid, child);
|
|
391
|
+
const state = { pid, profile: folder, saved_profile: null, chrome: "linux", engine, headed: false, socket };
|
|
392
|
+
const deadline = performance.now() + STARTUP_MS;
|
|
393
|
+
while (performance.now() < deadline) {
|
|
394
|
+
if (childExited(pid))
|
|
395
|
+
break;
|
|
396
|
+
if (await listening(socket))
|
|
397
|
+
return state;
|
|
398
|
+
await sleep(50);
|
|
399
|
+
}
|
|
400
|
+
await stopChrome(state);
|
|
401
|
+
throw new SessionError(`${name} did not start`);
|
|
402
|
+
}
|
|
200
403
|
/** profile=null makes a new temporary folder. A saved profile is kept when the run ends. */
|
|
201
404
|
export async function startChrome(options = {}) {
|
|
202
405
|
const headed = options.headed ?? false;
|
|
203
406
|
const profile = options.profile ?? null;
|
|
204
407
|
const chrome = options.chrome ?? "linux";
|
|
408
|
+
if (options.engine && ENGINES.includes(options.engine))
|
|
409
|
+
return startEngine(options.engine, { headed, profile });
|
|
410
|
+
const shell = options.engine === "headless-shell";
|
|
411
|
+
if (shell) {
|
|
412
|
+
// No window to sign in in, and a profile made by Chrome may be newer than this build.
|
|
413
|
+
if (headed)
|
|
414
|
+
throw new SessionError("The headless shell has no window, so --headed is not available");
|
|
415
|
+
if (profile)
|
|
416
|
+
throw new SessionError("The headless shell has no saved profile. Use --session new");
|
|
417
|
+
if (chrome === "windows")
|
|
418
|
+
throw new SessionError("The headless shell runs on Linux only");
|
|
419
|
+
}
|
|
205
420
|
let executable;
|
|
206
|
-
if (
|
|
421
|
+
if (shell) {
|
|
422
|
+
executable = shellBinary();
|
|
423
|
+
if (!executable)
|
|
424
|
+
throw new SessionError("chrome-headless-shell was not found (set WEBHAND_HEADLESS_SHELL)");
|
|
425
|
+
}
|
|
426
|
+
else if (chrome === "windows") {
|
|
207
427
|
executable = probes.windowsChrome();
|
|
208
428
|
if (!executable)
|
|
209
429
|
throw new SessionError("chrome.exe was not found on Windows");
|
|
@@ -228,7 +448,7 @@ export async function startChrome(options = {}) {
|
|
|
228
448
|
folder = mkdtempSync(join(tmpdir(), "webhand-"));
|
|
229
449
|
}
|
|
230
450
|
const userDataDir = chrome === "windows" ? probes.toWindows(folder) : folder;
|
|
231
|
-
const [command, ...args] = chromeArgs(executable, userDataDir, { headed });
|
|
451
|
+
const [command, ...args] = chromeArgs(executable, userDataDir, { headed, shell });
|
|
232
452
|
const child = spawn(command, args, {
|
|
233
453
|
detached: true, // its own process group, so it outlives this CLI call and stops as a group
|
|
234
454
|
stdio: "ignore",
|
|
@@ -238,7 +458,14 @@ export async function startChrome(options = {}) {
|
|
|
238
458
|
child.unref();
|
|
239
459
|
const pid = child.pid;
|
|
240
460
|
children.set(pid, child);
|
|
241
|
-
const state = {
|
|
461
|
+
const state = {
|
|
462
|
+
pid,
|
|
463
|
+
profile: folder,
|
|
464
|
+
saved_profile: profile,
|
|
465
|
+
chrome,
|
|
466
|
+
headed,
|
|
467
|
+
...(shell ? { engine: "headless-shell" } : {}),
|
|
468
|
+
};
|
|
242
469
|
const portFile = join(folder, "DevToolsActivePort");
|
|
243
470
|
const deadline = performance.now() + STARTUP_MS;
|
|
244
471
|
while (performance.now() < deadline) {
|
|
@@ -287,9 +514,26 @@ export async function stopChrome(state) {
|
|
|
287
514
|
catch {
|
|
288
515
|
// Already gone.
|
|
289
516
|
}
|
|
290
|
-
await exited(state.pid, state.chrome === "windows" ? 5000 : 2000)
|
|
291
|
-
|
|
292
|
-
|
|
517
|
+
if (!(await exited(state.pid, state.chrome === "windows" ? 5000 : 2000))) {
|
|
518
|
+
// A browser slow to exit (a loaded machine) is still writing into its folder: end it, or the folder cannot go.
|
|
519
|
+
try {
|
|
520
|
+
process.kill(-state.pid, "SIGKILL");
|
|
521
|
+
}
|
|
522
|
+
catch {
|
|
523
|
+
// Already gone.
|
|
524
|
+
}
|
|
525
|
+
await exited(state.pid, 2000);
|
|
526
|
+
}
|
|
527
|
+
if (!state.saved_profile) {
|
|
528
|
+
// A temporary folder is only tidying: it may not fail the call, which has done what it was asked to
|
|
529
|
+
// (round of full test runs at once: ENOTEMPTY turned "the browser did not start" into a crash).
|
|
530
|
+
try {
|
|
531
|
+
rmSync(state.profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
|
|
532
|
+
}
|
|
533
|
+
catch {
|
|
534
|
+
// Left behind in the temporary folder.
|
|
535
|
+
}
|
|
536
|
+
}
|
|
293
537
|
}
|
|
294
538
|
function alive(pid) {
|
|
295
539
|
const own = childExited(pid);
|
package/dist/types.js
CHANGED
|
@@ -2,10 +2,22 @@
|
|
|
2
2
|
/** The model gave no usable decision. Nothing was executed. */
|
|
3
3
|
export class PolicyError extends Error {
|
|
4
4
|
name = "PolicyError";
|
|
5
|
+
/** Why the model refused, for the run log only (such as Jev's HTTP status, request size and error body). */
|
|
6
|
+
diagnostic;
|
|
7
|
+
constructor(message, diagnostic = null) {
|
|
8
|
+
super(message);
|
|
9
|
+
this.diagnostic = diagnostic;
|
|
10
|
+
}
|
|
5
11
|
}
|
|
6
12
|
/** A decision no longer refers to the observed page. Nothing was executed. */
|
|
7
13
|
export class StalePage extends Error {
|
|
8
14
|
name = "StalePage";
|
|
15
|
+
/** What differed from the observation, for the run log only (such as url, scroll, scope_text). */
|
|
16
|
+
changed;
|
|
17
|
+
constructor(message, changed = []) {
|
|
18
|
+
super(message);
|
|
19
|
+
this.changed = changed;
|
|
20
|
+
}
|
|
9
21
|
}
|
|
10
22
|
/** A browser mutation may have happened. It must never be retried. */
|
|
11
23
|
export class MutationUncertain extends Error {
|