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/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 { tmpdir } from "node:os";
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
- const STARTUP_MS = 15_000;
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 join(home(), "session.json");
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 = join(home(), "session.tmp");
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
- "--window-size=1120,867", // The browser UI takes 87px; the page viewport is 1120x780.
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 (chrome === "windows") {
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 = { pid, profile: folder, saved_profile: profile, chrome, headed };
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
- if (!state.saved_profile)
292
- rmSync(state.profile, { recursive: true, force: true });
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 {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webhand",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Claude plans, asks, checks, and replans; Jev operates the browser toward the goal.",
5
5
  "license": "MIT",
6
6
  "author": "sakamoto66",