webhand 0.2.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/cli.js CHANGED
@@ -8,15 +8,20 @@ import { readFileSync, statSync } from "node:fs";
8
8
  import { join } from "node:path";
9
9
  import * as agent from "./agent.js";
10
10
  import { Budget, execute, runAgent } from "./agent.js";
11
+ import * as auth from "./auth.js";
11
12
  import { Browser } from "./browser.js";
13
+ import { collectScan, MAX_COLLECTED } from "./collect.js";
14
+ import { compareScan, MAX_PAGES, MAX_SCROLLS } from "./compare.js";
15
+ import { describeError, quote, show, stamp, toJson } from "./format.js";
16
+ import { Knowledge } from "./knowledge.js";
12
17
  import * as learn from "./learn.js";
13
- import { gitState, logOnce, Recorder, summarize } from "./metrics.js";
18
+ import { gitState, logOnce, maskUrls, pageEvent, Recorder, safeUrl, summarize } from "./metrics.js";
19
+ import { loadMore } from "./more.js";
14
20
  import { actionSpace, offscreen, planText, resolve } from "./policies/base.js";
15
21
  import { JevPolicy } from "./policies/jev.js";
16
- import { describeError, pyJson, pyLen, pyRepr, pyRound, pyStr, stamp, utcIso } from "./py.js";
22
+ import { RemoteBrowser } from "./remote.js";
17
23
  import * as runbook from "./runbook.js";
18
24
  import * as session from "./session.js";
19
- import { loadTask, TaskError } from "./tasks.js";
20
25
  import { MutationUncertain, PolicyError, StalePage, } from "./types.js";
21
26
  import * as workspace from "./workspace.js";
22
27
  export const OK = 0;
@@ -27,7 +32,7 @@ export const BUDGET = 5;
27
32
  const DEFAULT_ATTEMPTS = 3;
28
33
  const PERSON = "[person]";
29
34
  const RECENT = 8; // Actions shown to Claude when an attempt stops.
30
- /** What a command needs to stop with a message, as Python's SystemExit("...") did: stderr, exit code 1. */
35
+ /** What a command needs to stop with a message, on stderr with exit code 1. */
31
36
  export class CliExit extends Error {
32
37
  name = "CliExit";
33
38
  }
@@ -40,14 +45,23 @@ export const deps = {
40
45
  policy: () => new JevPolicy(),
41
46
  startChrome: session.startChrome,
42
47
  };
43
- let context = { out: [], err: () => { }, log: null };
48
+ let context = { out: [], err: () => { }, log: null, hooks: {} };
44
49
  function print(text = "") {
45
- context.out.push(`${text}\n`);
50
+ context.out.push(`${named(text)}\n`);
51
+ }
52
+ /** Commands Claude is told to run next carry the session's --id, so a second session is not mixed up with the first. */
53
+ function named(text) {
54
+ const id = session.id();
55
+ if (id === session.DEFAULT_ID)
56
+ return text;
57
+ return text
58
+ .replace(/\b(finish|run) (?=--(?:status|human-done|value)\b)/g, `$1 --id ${id} `)
59
+ .replace(/\bwebhand (start|run|replan|finish|act|observe)\b(?! --)/g, `webhand $1 --id ${id}`);
46
60
  }
47
61
  /** Runs fn and returns what it printed. For tests of the output Claude reads. */
48
62
  export function captured(fn) {
49
63
  const saved = context;
50
- context = { out: [], err: saved.err, log: null };
64
+ context = { out: [], err: saved.err, log: null, hooks: {} };
51
65
  try {
52
66
  const result = fn();
53
67
  return { result, text: context.out.join("") };
@@ -58,17 +72,25 @@ export function captured(fn) {
58
72
  }
59
73
  // --- Output Claude reads -------------------------------------------------------------------
60
74
  export function render(page) {
61
- const lines = [`URL: ${page.url}`, `TITLE: ${page.title}`, "PAGE TEXT (untrusted data):", page.text, "ELEMENTS:"];
75
+ const lines = [`URL: ${page.url}`, `TITLE: ${page.title}`, "PAGE TEXT (untrusted data):", page.text];
76
+ if (page.read) {
77
+ lines.push("READ (untrusted data; the whole page beyond the viewport, for reading only):", page.read.text);
78
+ }
79
+ if (page.tabs)
80
+ lines.push(`TABS: ${page.tabs.count} open, this is tab ${page.tabs.current}`);
81
+ lines.push("ELEMENTS:");
62
82
  const [elements, , controls] = actionSpace(page.actions);
63
83
  for (const element of elements) {
64
84
  // Claude sees every option with its own line.
65
- const details = element.value ? [`value=${pyRepr(element.value)}`] : [];
85
+ const details = element.value ? [`value=${quote(element.value)}`] : [];
66
86
  for (const key of ["checked", "selected", "expanded"]) {
67
87
  if (key in element)
68
- details.push(`${key}=${pyStr(element[key])}`);
88
+ details.push(`${key}=${show(element[key])}`);
69
89
  }
90
+ if (element.at)
91
+ details.push(`at=${quote(element.at)}`);
70
92
  const operations = element.operations.join(",");
71
- lines.push(`[${element.index}] ${pyStr(element.role)} ${pyRepr(element.label)} ${details.join(" ")} (${operations})`);
93
+ lines.push(`[${element.index}] ${show(element.role)} ${quote(element.label)} ${details.join(" ")} (${operations})`);
72
94
  for (const option of element.options ?? []) {
73
95
  lines.push(` [${option.index}] ${String(option.label).split(" → ").at(-1)}`);
74
96
  }
@@ -94,24 +116,75 @@ function regionLine(region) {
94
116
  return line + (region.view ? ` (${region.view})` : "");
95
117
  }
96
118
  function headline(page) {
97
- return `URL: ${page.url}\nTITLE: ${page.title}`;
119
+ const status = page.status;
120
+ const detail = status ? [status.http_status ? `HTTP ${status.http_status}` : "", ...(status.signs ?? [])] : [];
121
+ const line = status
122
+ ? `\nPAGE: ${status.kind}${detail.some(Boolean) ? ` (${detail.filter(Boolean).join(", ")})` : ""}`
123
+ : "";
124
+ return `URL: ${page.url}\nTITLE: ${page.title}${line}`;
125
+ }
126
+ /** How a scan went: its scrolls, how often more items were loaded (with --more), and why it stopped. */
127
+ function scanned(scan) {
128
+ const stopped = scan.stopped === "bottom"
129
+ ? "reached the bottom"
130
+ : scan.stopped === "pages"
131
+ ? `stopped after loading more ${MAX_PAGES} times`
132
+ : `stopped at ${MAX_SCROLLS} scrolls`;
133
+ const more = scan.pages === undefined ? "" : `, loaded more ${scan.pages} times`;
134
+ return `${scan.rounds} scrolls${more}, ${stopped}`;
135
+ }
136
+ /**
137
+ * Said when a scan stopped before the end of the list. In round 22, three runs sent 4 of 11 items and finished
138
+ * done after "stopped at 20 scrolls", read as the end of the list.
139
+ */
140
+ function cutShort(scan, what) {
141
+ if (scan.stopped === "bottom")
142
+ return [];
143
+ return [
144
+ `NOT THE WHOLE LIST: the scan stopped before the end of the list, and items further down were not read. ${what} ` +
145
+ "Unless the goal needs none of the rest, say the answer is partial and finish blocked.",
146
+ ];
147
+ }
148
+ export function comparedLine(compared) {
149
+ return [
150
+ `COMPARED (${scanned(compared)}): ${compared.best ?? "nothing fit the criterion"}`,
151
+ ...cutShort(compared, "This is the best among the items read."),
152
+ ].join("\n");
153
+ }
154
+ export function collectedLine(collected) {
155
+ const lines = [
156
+ `COLLECTED (${scanned(collected)}): ${collected.matched} of ${collected.seen} items meet: ${collected.criterion}`,
157
+ ...collected.items.map((item) => `- ${item}`),
158
+ ];
159
+ if (collected.matched > collected.items.length)
160
+ lines.push(`(the first ${MAX_COLLECTED} are shown)`);
161
+ lines.push(...cutShort(collected, "These are the matching items among those read."));
162
+ return lines.join("\n");
98
163
  }
99
164
  export function describePlan(plan, view = null) {
100
165
  const text = planText(plan);
101
166
  const lines = [`GOAL: ${plan.goal}`, "PLAN:", ...(text.length ? text : ["(goal only)"]).map((line) => ` ${line}`)];
102
167
  if (plan.values.length)
103
168
  lines.push(`VALUES: ${plan.values.map((value) => value.label).join(", ")}`);
104
- for (const key of ["focus", "skip"]) {
169
+ for (const key of ["focus", "skip", "read"]) {
105
170
  if (view?.[key]?.length)
106
171
  lines.push(`${key.toUpperCase()}: ${view[key].join(", ")}`);
107
172
  }
173
+ if (plan.compare)
174
+ lines.push(`COMPARE: ${plan.compare}`);
175
+ if (plan.collect)
176
+ lines.push(`COLLECT: ${plan.collect}`);
177
+ if (plan.more)
178
+ lines.push(`MORE: ${plan.more}`);
179
+ if (plan.flow)
180
+ lines.push(`FLOW: ${plan.flow}`);
108
181
  return lines.join("\n");
109
182
  }
110
183
  // biome-ignore lint/suspicious/noExplicitAny: the session state.
111
184
  export function recentActions(state) {
112
185
  const rows = state.history.filter((h) => h.attempt === state.plan.attempt).slice(-RECENT);
113
- const lines = rows.map((h) => ` ${h.step}. ${h.kind !== "human" ? h.operation : "HUMAN"} ${pyRepr(h.action)}` +
114
- (h.text ? ` text=${pyRepr(h.text)}` : "") +
186
+ const lines = rows.map((h) => ` ${h.step}. ${h.kind !== "human" ? h.operation : "HUMAN"} ${quote(h.action)}` +
187
+ (h.text ? ` text=${quote(h.text)}` : "") +
115
188
  (h.page_changed ? "" : " (page unchanged)"));
116
189
  return `ACTIONS THIS ATTEMPT:\n${lines.length ? lines.join("\n") : " (none)"}`;
117
190
  }
@@ -121,7 +194,7 @@ function parseValues(pairs) {
121
194
  const at = pair.indexOf("=");
122
195
  const label = at < 0 ? "" : pair.slice(0, at).trim();
123
196
  if (at < 0 || !label)
124
- throw new CliExit(`Expected --value LABEL=VALUE, got ${pyRepr(pair)}`);
197
+ throw new CliExit(`Expected --value LABEL=VALUE, got ${quote(pair)}`);
125
198
  return { label, value: pair.slice(at + 1) };
126
199
  });
127
200
  }
@@ -145,10 +218,35 @@ function requireSession() {
145
218
  context.log = state.log;
146
219
  return state;
147
220
  }
148
- async function openPage(state, url = null) {
149
- const browser = await Browser.open(url, { port: state.port, view: state.view ?? null });
221
+ /** The session's browser: Chrome by CDP port, or the daemon that holds an engine's page (Lightpanda, Obscura) by socket. Opens url when given. */
222
+ async function attach(state, url, view) {
223
+ if (state.socket) {
224
+ const remote = await RemoteBrowser.connect(state.socket, view ?? null);
225
+ try {
226
+ if (url)
227
+ await remote.goto(url);
228
+ }
229
+ catch (error) {
230
+ await remote.close();
231
+ throw error;
232
+ }
233
+ return remote;
234
+ }
235
+ return await Browser.open(url, { port: state.port, view });
236
+ }
237
+ async function openPage(state, url = null, restart = false) {
238
+ const browser = await attach(state, url, browserView(state));
150
239
  try {
151
240
  state.page = await browser.observe();
241
+ if (restart && process.env.WEBHAND_SCREENSHOTS === "1") {
242
+ const recorder = new Recorder(state.log);
243
+ try {
244
+ await agent.captureScreenshot(browser, recorder, state.history.length, state.plan.attempt, "restart", state.page.url);
245
+ }
246
+ finally {
247
+ recorder.close();
248
+ }
249
+ }
152
250
  }
153
251
  finally {
154
252
  await browser.close();
@@ -162,6 +260,24 @@ function defaultLog(name) {
162
260
  return process.env.WEBHAND_LOG || join(workspace.home(), "runs", stamp(), `${name}.jsonl`);
163
261
  }
164
262
  // --- Commands ------------------------------------------------------------------------------
263
+ /** A URL replan may open: http, https, or file. */
264
+ function openableUrl(url) {
265
+ try {
266
+ return ["http:", "https:", "file:"].includes(new URL(url).protocol);
267
+ }
268
+ catch {
269
+ return false;
270
+ }
271
+ }
272
+ /** Why Jev refused, for the run log only. */
273
+ function jevDiagnostic(error) {
274
+ return error instanceof PolicyError && error.diagnostic ? { jev: error.diagnostic } : {};
275
+ }
276
+ /** The snapshot's view: learned and Claude's regions, and with flow v2, the whole page. */
277
+ function browserView(state) {
278
+ const view = (state.view ?? null);
279
+ return state.plan?.flow === "v2" ? { ...(view ?? {}), whole: true } : view;
280
+ }
165
281
  /** Everything learned, for Claude to plan from. */
166
282
  async function commandCatalog(args) {
167
283
  const project = workspace.projectRoot();
@@ -200,8 +316,8 @@ async function commandCatalog(args) {
200
316
  print(" (no service.toml)");
201
317
  }
202
318
  for (const procedure of entry.procedures) {
203
- print(` PROCEDURE ${procedure.name} [${pyStr(procedure.status)}] (${procedure.scope}): ${pyStr(procedure.goal)}`);
204
- print(` start_url: ${pyStr(procedure.start_url)}`);
319
+ print(` PROCEDURE ${procedure.name} [${show(procedure.status)}] (${procedure.scope}): ${show(procedure.goal)}`);
320
+ print(` start_url: ${show(procedure.start_url)}`);
205
321
  for (const [key, description] of Object.entries(procedure.params))
206
322
  print(` param ${key}: ${description}`);
207
323
  if (procedure.human_steps)
@@ -216,6 +332,12 @@ async function commandCatalog(args) {
216
332
  const profiles = session.listProfiles(chrome);
217
333
  print(`CHROME: ${chrome}${note ? ` (${note})` : ""}`);
218
334
  print(`SAVED PROFILES: ${profiles.length ? profiles.join(", ") : "(none)"}`);
335
+ const open = session.active();
336
+ if (open.length) {
337
+ print("ACTIVE SESSIONS (use --id on every command of one):");
338
+ for (const [id, state] of open)
339
+ print(` ${id}: ${quote(String(state.plan?.goal ?? "").slice(0, 80))}`);
340
+ }
219
341
  return OK;
220
342
  }
221
343
  function chooseChrome(choice) {
@@ -229,27 +351,18 @@ function chooseChrome(choice) {
229
351
  }
230
352
  }
231
353
  async function commandStart(args) {
232
- if (session.load())
233
- throw new CliExit("A session is active. Run: webhand finish --status abandoned");
234
- let task = null;
235
- if (args.task) {
236
- try {
237
- task = await loadTask(args.task);
238
- }
239
- catch (error) {
240
- if (error instanceof TaskError)
241
- throw new CliExit(error.message);
242
- throw error;
243
- }
354
+ if (session.load()) {
355
+ throw new CliExit(named("A session is active. Run: webhand finish --status abandoned, or start another with --id"));
244
356
  }
245
- if (task && args.goal)
246
- throw new CliExit("A task supplies its own goal. Drop --goal");
357
+ const task = context.hooks.task ?? null;
247
358
  let book = null;
248
359
  let service = null;
249
360
  let serviceName = null;
250
361
  let profile;
251
362
  let chrome;
363
+ let engine;
252
364
  let note;
365
+ let login = null;
253
366
  try {
254
367
  if (args.runbook) {
255
368
  book = runbook.load(args.runbook, runbook.parseValues(args.param));
@@ -260,7 +373,19 @@ async function commandStart(args) {
260
373
  serviceName = args.service || (book ? book.service : null);
261
374
  service = serviceName ? runbook.loadService(serviceName) : null;
262
375
  profile = session.parseSession(args.session);
263
- [chrome, note] = session.chooseChrome(args.chrome);
376
+ if (args.auth) {
377
+ if (profile)
378
+ throw new CliExit("--auth is for a new session: a saved profile already keeps its own sign-in");
379
+ auth.checkName(args.auth);
380
+ if (!auth.exists(args.auth)) {
381
+ const known = auth.names();
382
+ throw new CliExit(`No saved login ${args.auth}. Saved: ${known.length ? known.join(", ") : "(none)"}. Save one with: webhand auth save NAME`);
383
+ }
384
+ login = auth.load(args.auth);
385
+ }
386
+ engine = session.chooseEngine(args.engine, { headed: args.headed, profile, chrome: args.chrome });
387
+ // --chrome says where Chrome runs; the other engines have no such choice.
388
+ [chrome, note] = engine === "chrome" ? chooseChrome(args.chrome) : ["linux", null];
264
389
  }
265
390
  catch (error) {
266
391
  if (error instanceof runbook.RunbookError || error instanceof session.SessionError) {
@@ -268,10 +393,10 @@ async function commandStart(args) {
268
393
  }
269
394
  throw error;
270
395
  }
271
- const goal = task ? task.GOAL : args.goal || (book ? book.goal : null);
272
- const url = task ? task.startUrl(process.cwd()) : args.url || (book ? book.start_url : null);
396
+ const goal = args.goal || (book ? book.goal : null);
397
+ const url = args.url || (book ? book.start_url : null);
273
398
  if (!(goal && url))
274
- throw new CliExit("Give --task, --runbook, or both --goal and --url");
399
+ throw new CliExit("Give --runbook, or both --goal and --url");
275
400
  let steps = [];
276
401
  if (args.step.length)
277
402
  steps = parseSteps(args.step);
@@ -286,6 +411,8 @@ async function commandStart(args) {
286
411
  if (steps.some((step) => step.actor === "human") && !args.headed) {
287
412
  throw new CliExit("This plan has [person] steps. Add --headed so the person can see the window");
288
413
  }
414
+ if (!FLOWS.includes(args.flow))
415
+ throw new CliExit(`WEBHAND_FLOW must be one of: ${FLOWS.join(", ")}`);
289
416
  if (!process.env.TYPESAFE_API_KEY) {
290
417
  throw new CliExit("TYPESAFE_API_KEY is not set. Set it as an environment variable");
291
418
  }
@@ -296,10 +423,18 @@ async function commandStart(args) {
296
423
  notes: [],
297
424
  attempt: 1,
298
425
  service: service ? { description: service.description, facts: service.facts } : null,
426
+ ...(args.compare ? { compare: args.compare } : {}),
427
+ ...(args.collect ? { collect: args.collect } : {}),
428
+ ...(args.more ? { more: args.more } : {}),
429
+ ...(args.flow === "v2" ? { flow: "v2" } : {}),
299
430
  };
431
+ if (plan.compare && plan.collect)
432
+ throw new CliExit("Use --compare or --collect, not both");
433
+ if (plan.more && !plan.compare && !plan.collect)
434
+ throw new CliExit("--more needs --compare or --collect");
300
435
  let chromeState;
301
436
  try {
302
- chromeState = await deps.startChrome({ headed: args.headed, profile, chrome });
437
+ chromeState = await deps.startChrome({ headed: args.headed, profile, chrome, engine });
303
438
  }
304
439
  catch (error) {
305
440
  if (error instanceof session.SessionError)
@@ -307,16 +442,17 @@ async function commandStart(args) {
307
442
  throw error;
308
443
  }
309
444
  const learned = runbook.view(runbook.serviceView(service), book);
310
- const claudeView = { focus: args.focus, skip: args.skip };
445
+ const claudeView = { focus: args.focus, skip: args.skip, read: args.read };
311
446
  const state = {
312
447
  ...chromeState,
313
448
  view_learned: learned,
314
449
  view_claude: claudeView,
315
450
  view: runbook.view(learned, claudeView),
316
- task: args.task ?? null,
451
+ task,
317
452
  start_url: session.browserUrl(url, chrome),
318
453
  plan,
319
454
  runbook: book ? { name: book.name, status: book.status, digest: book.digest, scope: book.scope } : null,
455
+ service: serviceName,
320
456
  history: [],
321
457
  decisions: 0,
322
458
  attempt_decisions: 0,
@@ -326,36 +462,61 @@ async function commandStart(args) {
326
462
  max_actions: args.max_actions,
327
463
  max_decisions: args.max_decisions,
328
464
  started: Date.now() / 1000,
329
- log: defaultLog(args.task || "adhoc"),
465
+ log: defaultLog(task || "adhoc"),
330
466
  };
331
467
  context.log = state.log;
332
468
  const recorder = new Recorder(state.log);
333
469
  let browser = null;
470
+ let skipped = [];
334
471
  try {
335
- browser = await Browser.open(state.start_url, { port: chromeState.port, view: state.view });
472
+ if (login) {
473
+ browser = await attach(chromeState, null, browserView(state));
474
+ skipped = await browser.restore(login.state, state.start_url);
475
+ }
476
+ else {
477
+ browser = await attach(chromeState, state.start_url, browserView(state));
478
+ }
336
479
  state.page = await browser.observe();
337
480
  recorder.event("run_start", {
338
- task: args.task ?? null,
481
+ task,
339
482
  goal,
340
483
  chrome: browser.version,
341
484
  chrome_host: chrome,
485
+ ...(engine !== "chrome" ? { engine } : {}),
342
486
  session: profile ? "profile" : "new",
487
+ ...(args.auth ? { auth: args.auth } : {}),
343
488
  git: gitState(),
344
489
  runbook: state.runbook,
345
490
  service: serviceName,
346
491
  view: state.view,
492
+ ...(plan.flow ? { flow: plan.flow } : {}),
347
493
  max_attempts: args.max_attempts,
348
- started_at: utcIso(),
494
+ started_at: new Date().toISOString(),
349
495
  });
350
496
  recorder.event("plan", {
351
497
  attempt: 1,
352
498
  steps: planText(plan),
353
499
  values: values.map((v) => v.label),
354
500
  view: state.view,
501
+ ...(plan.compare ? { compare: plan.compare } : {}),
502
+ ...(plan.collect ? { collect: plan.collect } : {}),
503
+ ...(plan.more ? { more: plan.more } : {}),
355
504
  source: book && !args.step.length ? "runbook" : "claude",
356
505
  });
506
+ recorder.event("page", pageEvent(state.page, 1));
507
+ await agent.checkPage(browser, recorder, "start", 1, state.page.url);
508
+ await agent.captureScreenshot(browser, recorder, 0, 1, "start", state.page.url);
357
509
  }
358
510
  catch (error) {
511
+ // A failed start is a run too: keep why it failed, not only the empty handoff.
512
+ recorder.event("start_failed", {
513
+ error: maskUrls(describeError(error).split("\n")[0]),
514
+ url: safeUrl(state.start_url),
515
+ chrome_host: chrome,
516
+ ...(engine !== "chrome" ? { engine } : {}),
517
+ session: profile ? "profile" : "new",
518
+ started_at: new Date().toISOString(),
519
+ });
359
520
  await session.stopChrome(chromeState);
360
521
  throw error;
361
522
  }
@@ -366,14 +527,60 @@ async function commandStart(args) {
366
527
  session.save(state);
367
528
  if (note)
368
529
  print(`NOTE: ${note}`);
369
- print(`${describePlan(plan, state.view)}\nSESSION: ${args.session} (${chrome} Chrome)\n${headline(state.page)}`);
530
+ if (args.auth) {
531
+ print(`SIGNED IN with saved login ${args.auth}. Pages opened signed in are sent to Jev`);
532
+ if (skipped.length)
533
+ print(`NOTE: localStorage of other sites was not restored: ${skipped.join(", ")}`);
534
+ }
535
+ print(`${describePlan(plan, state.view)}\nSESSION: ${args.session} (${session.hostName(engine, chrome)})\n${headline(state.page)}`);
370
536
  print("NEXT: webhand run");
371
537
  return OK;
372
538
  }
539
+ /** Outcomes after which `answer` continues the same attempt (v2). */
540
+ const ANSWERABLE = [agent.ESCALATE, agent.STUCK, agent.BLOCKED, agent.GOAL_REPORTED, agent.JEV_FAILED];
541
+ /** v2: parts of the page webhand cannot see into, said plainly so that Claude looks for another way. */
542
+ function unseenHint(page) {
543
+ if (!agent.unseenParts(page))
544
+ return "";
545
+ const unseen = (page.status?.unseen ?? {});
546
+ return (`. The page has ${unseen.canvases ?? 0} canvas, ${unseen.frames ?? 0} frame, and ${unseen.objects ?? 0} plugin parts ` +
547
+ "whose content webhand cannot see: what Jev needs may be inside one. Answering cannot reveal it; look for another way " +
548
+ "(a list or text version, another page, a keyboard route) or ask the person");
549
+ }
550
+ /** Why the run came back, from the log of this attempt only. No page text. */
551
+ function diagnose(state, outcome) {
552
+ const status = state.page?.status;
553
+ if (status?.kind === "check")
554
+ return "the page is a bot check or CAPTCHA; a person must pass it";
555
+ if (status?.kind === "sign_in")
556
+ return "the page asks for a sign-in; a person must sign in";
557
+ if (status?.kind === "error")
558
+ return "the page is an error page";
559
+ if (status?.kind === "dialog")
560
+ return "a dialog covers the page";
561
+ const rows = state.history.filter((h) => (h.attempt ?? 1) === state.plan.attempt).slice(-3);
562
+ const count = (kind) => rows.filter((h) => h.kind === kind).length;
563
+ if (outcome === agent.STUCK) {
564
+ if (agent.looping(state.history, state.plan.attempt)) {
565
+ return "Jev scrolled up and down three times and chose nothing: what it needs may not be on this page, or is elsewhere on it";
566
+ }
567
+ if (count("stale"))
568
+ return "the last choices were refused as stale: the page keeps changing under the target";
569
+ if (count("missing"))
570
+ return `Jev could not find the element it needs in what was offered${unseenHint(state.page)}`;
571
+ return "the last three actions did not change the page";
572
+ }
573
+ if (outcome === agent.GOAL_REPORTED)
574
+ return "Jev thinks the goal is met and asks Claude to check the page";
575
+ if (outcome === agent.JEV_FAILED)
576
+ return "Jev gave no usable decision; nothing was executed";
577
+ const handed = "Jev handed the decision to Claude: the page is not what the plan expects, nothing offered fits, or the operation cannot be undone";
578
+ return `${handed}${unseenHint(state.page)}`;
579
+ }
373
580
  /** What Claude needs for this outcome, and nothing more. */
374
581
  export function report(state, result) {
375
582
  const outcome = result.outcome;
376
- print(`OUTCOME ${outcome} (${attemptLabel(state)}): ${pyStr(result.detail)}`);
583
+ print(`OUTCOME ${outcome} (${attemptLabel(state)}): ${show(result.detail)}`);
377
584
  if (outcome === agent.UNCERTAIN) {
378
585
  print("Do not repeat or replan. Run: webhand finish --status error");
379
586
  return UNCERTAIN;
@@ -383,11 +590,17 @@ export function report(state, result) {
383
590
  return OK;
384
591
  }
385
592
  if (outcome === agent.NEEDS_VALUE) {
386
- print(`FIELD: ${pyJson(result.field)}`);
593
+ print(`FIELD: ${toJson(result.field)}`);
387
594
  print("Give the value with: run --value 'LABEL=VALUE'. Never invent personal data; ask the person");
388
595
  return OK;
389
596
  }
390
597
  print(`${recentActions(state)}\n${render(state.page)}`);
598
+ if (state.plan.flow === "v2" && ANSWERABLE.includes(outcome)) {
599
+ print(`WHY: ${diagnose(state, outcome)}`);
600
+ print("NEXT: answer --note '...' [--value 'LABEL=VALUE'] [--url URL] continues this attempt; replan changes the plan; " +
601
+ "if it cannot be done, ask the person with AskUserQuestion; finish");
602
+ return OK;
603
+ }
391
604
  if (outcome === agent.GOAL_REPORTED) {
392
605
  print("Check the page against the goal. If it is met: finish --status done. Otherwise: replan");
393
606
  }
@@ -415,8 +628,8 @@ async function commandRun(args) {
415
628
  print("REJECTED: this field needs run --value 'LABEL=VALUE'");
416
629
  return FAILED;
417
630
  }
418
- if ([agent.GOAL_REPORTED, agent.BLOCKED, agent.STUCK, agent.ATTEMPT_BUDGET].includes(outcome)) {
419
- print(`REJECTED: the attempt ended with ${outcome}. Run replan, act, or finish`);
631
+ if ([agent.GOAL_REPORTED, agent.BLOCKED, agent.STUCK, agent.ATTEMPT_BUDGET, agent.ESCALATE].includes(outcome)) {
632
+ print(`REJECTED: the attempt ended with ${outcome}. Run ${state.plan.flow === "v2" ? "answer, " : ""}replan, act, or finish`);
420
633
  return FAILED;
421
634
  }
422
635
  if (args.value.length) {
@@ -447,14 +660,97 @@ async function commandRun(args) {
447
660
  state.outcome = null;
448
661
  session.save(state);
449
662
  const policy = deps.policy();
450
- const browser = await Browser.open(null, { port: state.port, view: state.view ?? null });
663
+ const browser = await attach(state, null, browserView(state));
451
664
  const recorder = new Recorder(state.log);
452
665
  let result;
666
+ // With --more, a scan presses Claude's control for more items when the list ends.
667
+ const more = () => {
668
+ const control = state.plan.more;
669
+ if (!control)
670
+ return null;
671
+ if (!("more" in policy))
672
+ throw new CliExit("This chooser cannot find a control for more items");
673
+ const chooser = policy;
674
+ return loadMore(browser, chooser, state.plan, control, recorder, state.plan.attempt);
675
+ };
676
+ // Pressing the control is an action: when its result is uncertain, the run stops as UNCERTAIN.
677
+ const uncertain = (error, scan) => {
678
+ recorder.event(`${scan}_failed`, { attempt: state.plan.attempt, error: error.message, uncertain: true });
679
+ state.outcome = agent.UNCERTAIN;
680
+ session.save(state);
681
+ print(`OUTCOME ${agent.UNCERTAIN}: ${error.message} while loading more items. Do not repeat or replan. Run: webhand finish --status error`);
682
+ return UNCERTAIN;
683
+ };
453
684
  try {
685
+ // With a criterion, compare the whole list once per attempt before anything is acted on.
686
+ if (state.plan.compare && !state.plan.compared) {
687
+ if (!("compare" in policy))
688
+ throw new CliExit("This chooser cannot compare items");
689
+ let scan;
690
+ try {
691
+ scan = await compareScan(browser, policy, state.plan, state.plan.compare, recorder, {
692
+ loadMore: more(),
693
+ });
694
+ }
695
+ catch (error) {
696
+ if (error instanceof MutationUncertain)
697
+ return uncertain(error, "compare");
698
+ if (!(error instanceof PolicyError || error instanceof StalePage))
699
+ throw error;
700
+ // Only scrolls happened. The attempt goes on; run again, or replan.
701
+ recorder.event("compare_failed", {
702
+ attempt: state.plan.attempt,
703
+ error: error.message,
704
+ ...jevDiagnostic(error),
705
+ });
706
+ print(`COMPARE FAILED: ${error.message} Nothing was clicked or typed. Run again, or replan`);
707
+ return FAILED;
708
+ }
709
+ state.plan.compared = scan.compared;
710
+ state.page = scan.page;
711
+ session.save(state);
712
+ print(comparedLine(scan.compared));
713
+ }
714
+ // With a condition, collect the matching items once per attempt and give them to Claude; nothing is acted on.
715
+ if (state.plan.collect && !state.plan.collected) {
716
+ if (!("collect" in policy))
717
+ throw new CliExit("This chooser cannot collect items");
718
+ let scan;
719
+ try {
720
+ scan = await collectScan(browser, policy, state.plan, state.plan.collect, recorder, {
721
+ loadMore: more(),
722
+ });
723
+ }
724
+ catch (error) {
725
+ if (error instanceof MutationUncertain)
726
+ return uncertain(error, "collect");
727
+ if (!(error instanceof PolicyError || error instanceof StalePage))
728
+ throw error;
729
+ recorder.event("collect_failed", {
730
+ attempt: state.plan.attempt,
731
+ error: error.message,
732
+ ...jevDiagnostic(error),
733
+ });
734
+ print(`COLLECT FAILED: ${error.message} Nothing was clicked or typed. Run again, or replan`);
735
+ return FAILED;
736
+ }
737
+ state.plan.collected = scan.collected;
738
+ state.page = scan.page;
739
+ session.save(state);
740
+ print(collectedLine(scan.collected));
741
+ print("Nothing was clicked or typed, and the page is back where it was. Check these items against the goal and " +
742
+ "write the answer from them. To put the answer into the page, give it as a value: run --value " +
743
+ "'LABEL=VALUE' (Jev types only values). Otherwise: finish");
744
+ return OK;
745
+ }
454
746
  result = await runAgent(browser, policy, state.plan, recorder, new Budget(state.max_actions, state.max_decisions), {
455
747
  history: state.history,
456
748
  page: state.page,
457
749
  decisions: state.attempt_decisions,
750
+ // v2 records what its operations did, for the next run on the site (WEBHAND_KNOWLEDGE=0 turns it off).
751
+ knowledge: state.plan.flow === "v2" && process.env.WEBHAND_KNOWLEDGE !== "0"
752
+ ? new Knowledge(undefined, process.env.WEBHAND_KNOWLEDGE_USE !== "0")
753
+ : undefined,
458
754
  onChange: (page) => {
459
755
  state.page = page;
460
756
  session.save(state);
@@ -466,7 +762,15 @@ async function commandRun(args) {
466
762
  });
467
763
  state.page = result.page;
468
764
  state.outcome = result.outcome;
469
- recorder.event("escalation", { reason: result.outcome, attempt: state.plan.attempt, detail: result.detail });
765
+ recorder.event("escalation", {
766
+ reason: result.outcome,
767
+ attempt: state.plan.attempt,
768
+ detail: result.detail,
769
+ ...(result.jev ? { jev: result.jev } : {}),
770
+ });
771
+ if (agent.CHECKED_OUTCOMES.includes(result.outcome)) {
772
+ await agent.checkPage(browser, recorder, "escalation", state.plan.attempt, result.page.url);
773
+ }
470
774
  if (result.outcome === agent.NEEDS_HUMAN) {
471
775
  recorder.event("human_step", { status: "requested", attempt: state.plan.attempt });
472
776
  }
@@ -479,6 +783,61 @@ async function commandRun(args) {
479
783
  }
480
784
  return report(state, result);
481
785
  }
786
+ /** v2: Claude answers Jev's question. The same attempt continues: history and budget are kept. */
787
+ async function commandAnswer(args) {
788
+ const state = requireSession();
789
+ const plan = state.plan;
790
+ if (plan.flow !== "v2") {
791
+ print("REJECTED: answer is for --flow v2. Use replan");
792
+ return FAILED;
793
+ }
794
+ if (!ANSWERABLE.includes(state.outcome)) {
795
+ print(`REJECTED: nothing is waiting for an answer (${state.outcome ?? "the run is not stopped"}). Run: webhand run`);
796
+ return FAILED;
797
+ }
798
+ if (args.url) {
799
+ let url;
800
+ try {
801
+ url = runbook.resolveUrl(args.url);
802
+ }
803
+ catch (error) {
804
+ if (!(error instanceof runbook.RunbookError))
805
+ throw error;
806
+ print(`REJECTED: ${error.message.replace("start_url", "--url")}`);
807
+ return FAILED;
808
+ }
809
+ if (!openableUrl(url)) {
810
+ print("REJECTED: --url needs an http, https, or file URL, or a local file path");
811
+ return FAILED;
812
+ }
813
+ await openPage(state, session.browserUrl(url, state.chrome ?? "linux"), true);
814
+ }
815
+ const values = parseValues(args.value);
816
+ if (values.length)
817
+ plan.values = mergeValues(plan.values, values);
818
+ plan.instructions = [...(plan.instructions ?? []), args.note];
819
+ // Not an action: it neither counts against the budget nor hides that the page did not change.
820
+ state.history.push({
821
+ step: state.history.length + 1,
822
+ attempt: plan.attempt,
823
+ kind: "answer",
824
+ operation: "ANSWER",
825
+ action: "Claude answered",
826
+ text: null,
827
+ url: state.page.url,
828
+ page_changed: true,
829
+ });
830
+ logOnce(state.log, "answer", {
831
+ attempt: plan.attempt,
832
+ after: state.outcome,
833
+ chars: [...args.note].length,
834
+ values: values.map((v) => v.label),
835
+ ...(args.url ? { url: safeUrl(args.url) } : {}),
836
+ });
837
+ state.outcome = null;
838
+ session.save(state);
839
+ return commandRun({ ...args, value: [], human_done: false });
840
+ }
482
841
  /** Claude revises the plan after an attempt fell short, and starts the next attempt. */
483
842
  async function commandReplan(args) {
484
843
  const state = requireSession();
@@ -491,6 +850,29 @@ async function commandReplan(args) {
491
850
  print(`ATTEMPTS EXHAUSTED (${state.max_attempts}). Run: webhand finish --status blocked`);
492
851
  return BUDGET;
493
852
  }
853
+ if (args.url && args.restart) {
854
+ print("REJECTED: use --url or --restart, not both");
855
+ return FAILED;
856
+ }
857
+ let url = null;
858
+ if (args.url) {
859
+ // A path without a scheme is a local file, as the catalog shows a learned page (tasks/fixtures/...).
860
+ try {
861
+ url = runbook.resolveUrl(args.url);
862
+ }
863
+ catch (error) {
864
+ if (!(error instanceof runbook.RunbookError))
865
+ throw error;
866
+ print(`REJECTED: ${error.message.replace("start_url", "--url")}`);
867
+ return FAILED;
868
+ }
869
+ if (!openableUrl(url)) {
870
+ print("REJECTED: --url needs an http, https, or file URL, or a local file path");
871
+ return FAILED;
872
+ }
873
+ // As start does: the Windows Chrome on WSL opens a local file by its Windows path (round 19).
874
+ url = session.browserUrl(url, state.chrome ?? "linux");
875
+ }
494
876
  if (args.step.length) {
495
877
  const steps = parseSteps(args.step);
496
878
  if (steps.some((step) => step.actor === "human") && !state.headed) {
@@ -500,10 +882,32 @@ async function commandReplan(args) {
500
882
  plan.steps = steps;
501
883
  }
502
884
  plan.values = mergeValues(plan.values, parseValues(args.value));
503
- const viewChanged = args.focus.length || args.skip.length;
885
+ if (args.compare)
886
+ plan.compare = args.compare === "none" ? null : args.compare;
887
+ plan.compared = null; // Each attempt compares again from the top.
888
+ if (args.collect)
889
+ plan.collect = args.collect === "none" ? null : args.collect;
890
+ plan.collected = null; // and collects again.
891
+ if (args.more)
892
+ plan.more = args.more === "none" ? null : args.more;
893
+ if (plan.compare && plan.collect) {
894
+ print("REJECTED: use --compare or --collect, not both (turn one off with none)");
895
+ return FAILED;
896
+ }
897
+ if (plan.more && !plan.compare && !plan.collect) {
898
+ print("REJECTED: --more needs --compare or --collect (turn it off with --more none)");
899
+ return FAILED;
900
+ }
901
+ const viewChanged = args.focus.length || args.skip.length || args.read.length;
504
902
  if (viewChanged) {
505
- // Claude's region choice is replaced, on top of what was learned.
506
- state.view_claude = { focus: args.focus, skip: args.skip };
903
+ // Claude's region choice is replaced, on top of what was learned. --read alone keeps the regions.
904
+ const regions = args.focus.length || args.skip.length;
905
+ const earlier = state.view_claude ?? { focus: [], skip: [] };
906
+ state.view_claude = {
907
+ focus: regions ? args.focus : earlier.focus,
908
+ skip: regions ? args.skip : earlier.skip,
909
+ read: args.read.length ? args.read : earlier.read,
910
+ };
507
911
  state.view = runbook.view(state.view_learned, state.view_claude);
508
912
  }
509
913
  const ended = state.outcome || "CLAUDE_STOPPED";
@@ -519,12 +923,19 @@ async function commandReplan(args) {
519
923
  steps: planText(plan),
520
924
  values: plan.values.map((v) => v.label),
521
925
  view: state.view ?? null,
926
+ ...(plan.compare ? { compare: plan.compare } : {}),
927
+ ...(plan.collect ? { collect: plan.collect } : {}),
928
+ ...(plan.more ? { more: plan.more } : {}),
522
929
  restart: args.restart,
930
+ ...(url ? { url: safeUrl(url) } : {}),
523
931
  source: "claude",
524
932
  });
525
- if (args.restart)
526
- await openPage(state, state.start_url); // Navigation only; no earlier mutation is repeated.
527
- if (!args.restart && viewChanged)
933
+ // Navigation only; no earlier mutation is repeated.
934
+ if (url)
935
+ await openPage(state, url, true);
936
+ else if (args.restart)
937
+ await openPage(state, state.start_url, true);
938
+ else if (viewChanged)
528
939
  await openPage(state); // Observe again with the new regions.
529
940
  print(`${describePlan(plan, state.view ?? null)}\nATTEMPT ${plan.attempt}/${state.max_attempts}\n${headline(state.page)}`);
530
941
  print("NEXT: webhand run");
@@ -572,12 +983,13 @@ async function commandAct(args) {
572
983
  decision.text = decision.action.kind === "fill" ? args.text : null;
573
984
  state.decisions += 1;
574
985
  session.save(state);
575
- const browser = await Browser.open(null, { port: state.port, view: state.view ?? null });
986
+ const browser = await attach(state, null, browserView(state));
576
987
  const recorder = new Recorder(state.log);
577
988
  try {
578
989
  await execute(browser, state.page, decision, state.history, recorder, {
579
990
  decidedBy: "claude",
580
991
  attempt: state.plan.attempt,
992
+ values: state.plan.values,
581
993
  onChange: (page) => {
582
994
  state.page = page;
583
995
  session.save(state);
@@ -617,6 +1029,7 @@ function runTotals(log) {
617
1029
  let handoffs = 0;
618
1030
  let handoffChars = 0;
619
1031
  let notVisible = 0;
1032
+ let stale = 0;
620
1033
  for (const line of readFileSync(log, "utf8").split("\n")) {
621
1034
  if (!line.trim())
622
1035
  continue;
@@ -629,6 +1042,8 @@ function runTotals(log) {
629
1042
  decidedBy[event.decided_by] = (decidedBy[event.decided_by] ?? 0) + 1;
630
1043
  else if (type === "not_visible")
631
1044
  notVisible += 1;
1045
+ else if (type === "stale")
1046
+ stale += 1;
632
1047
  else if (type === "handoff") {
633
1048
  handoffs += 1;
634
1049
  handoffChars += event.chars;
@@ -641,19 +1056,21 @@ function runTotals(log) {
641
1056
  handoffs,
642
1057
  handoff_chars: handoffChars,
643
1058
  not_visible: notVisible,
1059
+ stale,
644
1060
  };
645
1061
  }
646
- /** Verifies the page independently. The status is what the agent claims, nothing more. */
1062
+ /** Verifies the page independently when a verifier was given. The status is what the agent claims, nothing more. */
647
1063
  async function commandFinish(args) {
648
1064
  const state = session.load();
649
1065
  if (state === null)
650
1066
  throw new CliExit("No active session. Run: webhand start");
651
1067
  let verdict = { success: null, evidence: "no verifier" };
652
1068
  try {
653
- if (state.task) {
654
- const browser = await Browser.open(null, { port: state.port });
1069
+ const verify = context.hooks.verify;
1070
+ if (verify) {
1071
+ const browser = await attach(state, null);
655
1072
  try {
656
- verdict = await (await loadTask(state.task)).verify(browser);
1073
+ verdict = await verify(browser, state); // A remote browser has evaluate, which is what verifiers use.
657
1074
  }
658
1075
  finally {
659
1076
  await browser.close();
@@ -668,23 +1085,29 @@ async function commandFinish(args) {
668
1085
  session.clear();
669
1086
  }
670
1087
  const plan = state.plan;
1088
+ // v2: a run that finished as done marks its steps as the way that worked.
1089
+ if (args.status === "done" && plan.flow === "v2" && process.env.WEBHAND_KNOWLEDGE !== "0") {
1090
+ new Knowledge().confirm(state.history);
1091
+ }
671
1092
  const outcomes = [...state.outcomes, { attempt: plan.attempt, outcome: state.outcome, reason: args.reason }];
672
1093
  const totals = runTotals(state.log);
673
1094
  logOnce(state.log, "run_end", {
674
1095
  status: args.status,
675
1096
  reason: args.reason,
1097
+ service: state.service ?? null,
1098
+ runbook: state.runbook ?? null,
676
1099
  goal: plan.goal,
677
1100
  plan: planText(plan),
678
1101
  attempts: plan.attempt,
679
1102
  attempt_outcomes: outcomes,
680
- actions: state.history.length,
1103
+ actions: agent.executed(state.history).length,
681
1104
  decisions: state.decisions,
682
- elapsed_ms: pyRound((Date.now() / 1000 - state.started) * 1000),
1105
+ elapsed_ms: Math.round((Date.now() / 1000 - state.started) * 1000),
683
1106
  verified: verdict.success,
684
1107
  evidence: verdict.evidence,
685
1108
  ...totals,
686
1109
  });
687
- print(`FINISHED status=${args.status} verified=${pyStr(verdict.success)} attempts=${plan.attempt} log=${state.log}`);
1110
+ print(`FINISHED status=${args.status} verified=${show(verdict.success)} attempts=${plan.attempt} log=${state.log}`);
688
1111
  return OK;
689
1112
  }
690
1113
  function parentAlive(pid) {
@@ -729,7 +1152,7 @@ async function commandLearn(args) {
729
1152
  const parts = String(args.name).split("/");
730
1153
  serviceFile = parts.length > 1 ? runbook.servicePath(parts[0], args.scope) : null;
731
1154
  profile = session.parseSession(args.session);
732
- [chrome, note] = session.chooseChrome(args.chrome);
1155
+ [chrome, note] = chooseChrome(args.chrome);
733
1156
  }
734
1157
  catch (error) {
735
1158
  if (error instanceof runbook.RunbookError || error instanceof session.SessionError) {
@@ -764,7 +1187,7 @@ async function commandLearn(args) {
764
1187
  chrome_host: chrome,
765
1188
  session: profile ? "profile" : "new",
766
1189
  git: gitState(),
767
- started_at: utcIso(),
1190
+ started_at: new Date().toISOString(),
768
1191
  });
769
1192
  counts = await learn.record(browser, session.browserUrl(args.url, chrome), recorder, () => signals.stopped() || performance.now() >= deadline);
770
1193
  recorder.event("learn_end", { counts });
@@ -777,7 +1200,7 @@ async function commandLearn(args) {
777
1200
  }
778
1201
  if (note)
779
1202
  print(`NOTE: ${note}`);
780
- print(`RECORDED ${pyRepr(counts)} log=${log}`);
1203
+ print(`RECORDED ${quote(counts)} log=${log}`);
781
1204
  print(`WRITE THE RUNBOOK TO ${runbookFile}`);
782
1205
  if (serviceFile)
783
1206
  print(`WRITE THE SERVICE INFORMATION TO ${serviceFile}`);
@@ -800,7 +1223,7 @@ async function commandProfile(args) {
800
1223
  let chrome;
801
1224
  try {
802
1225
  let note;
803
- [chrome, note] = session.chooseChrome(args.chrome);
1226
+ [chrome, note] = chooseChrome(args.chrome);
804
1227
  if (note)
805
1228
  print(`NOTE: ${note}`);
806
1229
  if (args.action === "list") {
@@ -822,9 +1245,8 @@ async function commandProfile(args) {
822
1245
  }
823
1246
  if (!args.url)
824
1247
  throw new CliExit("profile login needs --url");
825
- const active = session.load();
826
- if (active && active.saved_profile === args.name) {
827
- throw new CliExit(`Profile ${args.name} is in use by the active run. Finish it first`);
1248
+ if (session.active().some(([, state]) => state.saved_profile === args.name)) {
1249
+ throw new CliExit(`Profile ${args.name} is in use by an active run. Finish it first`);
828
1250
  }
829
1251
  chromeState = await session.startChrome({ headed: true, profile: args.name, chrome });
830
1252
  }
@@ -848,8 +1270,75 @@ async function commandProfile(args) {
848
1270
  print(`SAVED profile ${args.name}. Use it with: start --session profile:${args.name}`);
849
1271
  return OK;
850
1272
  }
1273
+ /** Saved logins. `save` takes the sign-in of a running session; `start --auth NAME` begins a new session with it. */
1274
+ async function commandKnowledge(args) {
1275
+ const knowledge = new Knowledge();
1276
+ if (args.action === "list") {
1277
+ const hosts = knowledge.hosts();
1278
+ if (!hosts.length)
1279
+ print("KNOWN SITES: (none)");
1280
+ for (const h of hosts)
1281
+ print(`${h.host}: ${h.pages} pages, ${h.operations} operations, ${h.worked} that worked`);
1282
+ return OK;
1283
+ }
1284
+ if (args.action === "show") {
1285
+ if (!args.name)
1286
+ throw new CliExit("knowledge show needs a HOST");
1287
+ const lines = knowledge.describe(args.name);
1288
+ print(lines.length ? lines.join("\n") : `Nothing is known about ${args.name}`);
1289
+ return lines.length ? OK : FAILED;
1290
+ }
1291
+ const removed = knowledge.forget(args.name ?? null);
1292
+ print(`FORGOT ${removed} ${removed === 1 ? "site" : "sites"}${args.name ? ` (${args.name})` : ""}`);
1293
+ return OK;
1294
+ }
1295
+ async function commandAuth(args) {
1296
+ try {
1297
+ if (args.action === "list") {
1298
+ const names = auth.names();
1299
+ print(`SAVED LOGINS: ${names.length ? names.join(", ") : "(none)"}`);
1300
+ return OK;
1301
+ }
1302
+ if (!args.name)
1303
+ throw new CliExit(`auth ${args.action} needs a NAME`);
1304
+ auth.checkName(args.name);
1305
+ if (args.action === "delete") {
1306
+ if (!auth.remove(args.name)) {
1307
+ print(`No saved login ${args.name}`);
1308
+ return FAILED;
1309
+ }
1310
+ print(`DELETED login ${args.name}`);
1311
+ return OK;
1312
+ }
1313
+ const state = requireSession();
1314
+ const replaced = auth.exists(args.name);
1315
+ const browser = await attach(state, null, browserView(state));
1316
+ let storage;
1317
+ try {
1318
+ storage = await browser.storageState();
1319
+ }
1320
+ finally {
1321
+ await browser.close();
1322
+ }
1323
+ auth.save(args.name, storage);
1324
+ print(`${replaced ? "REPLACED" : "SAVED"} login ${args.name} (${auth.summary(auth.load(args.name))}). Use it with: start --auth ${args.name}`);
1325
+ return OK;
1326
+ }
1327
+ catch (error) {
1328
+ if (error instanceof session.SessionError)
1329
+ throw new CliExit(error.message);
1330
+ throw error;
1331
+ }
1332
+ }
1333
+ const FLOWS = ["v1", "v2"];
851
1334
  function commands() {
852
1335
  const chromeDefault = process.env.WEBHAND_CHROME ?? "auto";
1336
+ const idOption = {
1337
+ name: "id",
1338
+ type: "string",
1339
+ default: session.DEFAULT_ID,
1340
+ help: "Name of the session, to run several at once. Give the same --id to every command of one session",
1341
+ };
853
1342
  const chromeOption = {
854
1343
  name: "chrome",
855
1344
  type: "string",
@@ -857,6 +1346,13 @@ function commands() {
857
1346
  default: chromeDefault,
858
1347
  help: "auto uses the Windows Chrome on WSL when it is reachable",
859
1348
  };
1349
+ const engineOption = {
1350
+ name: "engine",
1351
+ type: "string",
1352
+ choices: [...session.ENGINE_CHOICES],
1353
+ default: process.env.WEBHAND_ENGINE ?? "auto",
1354
+ help: "What runs the browser. auto (default) uses the headless shell when it is installed and the run needs no window or saved profile, else Chrome. headless-shell, lightpanda and obscura have no window and no saved profile, and --chrome does not apply to them. Default: WEBHAND_ENGINE, else auto",
1355
+ };
860
1356
  const viewOptions = [
861
1357
  {
862
1358
  name: "focus",
@@ -866,7 +1362,33 @@ function commands() {
866
1362
  help: "A region to show first, such as form:予約",
867
1363
  },
868
1364
  { name: "skip", type: "string", multiple: true, metavar: "REGION", help: "A region to leave out" },
1365
+ {
1366
+ name: "read",
1367
+ type: "string",
1368
+ multiple: true,
1369
+ metavar: "KIND",
1370
+ choices: [...runbook.READ_KINDS, "none"],
1371
+ help: "Content to read beyond the viewport: outline, text, table, list, link, control, media; none clears it",
1372
+ },
869
1373
  ];
1374
+ const compareOption = {
1375
+ name: "compare",
1376
+ type: "string",
1377
+ metavar: "CRITERION",
1378
+ help: "Before acting, scroll through the whole list and find the item that best meets this; none clears it",
1379
+ };
1380
+ const collectOption = {
1381
+ name: "collect",
1382
+ type: "string",
1383
+ metavar: "CONDITION",
1384
+ help: "First scroll through the whole list and collect every item that meets this, then stop; none clears it",
1385
+ };
1386
+ const moreOption = {
1387
+ name: "more",
1388
+ type: "string",
1389
+ metavar: "CONTROL",
1390
+ help: "With --compare or --collect, press this control when the list ends, such as Next page; none clears it",
1391
+ };
870
1392
  return {
871
1393
  catalog: {
872
1394
  help: "List learned services, procedures, and saved profiles",
@@ -876,6 +1398,7 @@ function commands() {
876
1398
  start: {
877
1399
  help: "Record Claude's plan and open the start page",
878
1400
  options: [
1401
+ idOption,
879
1402
  { name: "goal", type: "string" },
880
1403
  { name: "url", type: "string" },
881
1404
  { name: "step", type: "string", multiple: true, help: 'A plan step. "[person] ..." is done by a person' },
@@ -885,45 +1408,79 @@ function commands() {
885
1408
  { name: "param", type: "string", multiple: true, metavar: "KEY=VALUE", help: "A runbook parameter" },
886
1409
  { name: "allow-draft", type: "boolean", help: "Trial a runbook no person has approved yet" },
887
1410
  ...viewOptions,
888
- { name: "task", type: "string", help: "A task in tasks/ with an independent verify() (research repository)" },
1411
+ compareOption,
1412
+ collectOption,
1413
+ moreOption,
1414
+ {
1415
+ name: "flow",
1416
+ type: "string",
1417
+ choices: [...FLOWS],
1418
+ default: process.env.WEBHAND_FLOW || "v1",
1419
+ help: "v2: offer Jev the whole page (research). Default: WEBHAND_FLOW, else v1",
1420
+ },
889
1421
  { name: "session", type: "string", default: "new", help: "new (temporary) or profile:NAME (saved sign-in)" },
1422
+ {
1423
+ name: "auth",
1424
+ type: "string",
1425
+ metavar: "NAME",
1426
+ help: "Start signed in with a login saved by `auth save`. For a new session only: not with --id or profile:NAME",
1427
+ },
890
1428
  chromeOption,
1429
+ engineOption,
891
1430
  { name: "headed", type: "boolean" },
892
1431
  { name: "max-attempts", type: "int", default: DEFAULT_ATTEMPTS },
893
1432
  { name: "max-actions", type: "int", default: Budget.MAX_ACTIONS, help: "Per attempt" },
894
1433
  { name: "max-decisions", type: "int", default: Budget.MAX_DECISIONS, help: "Per attempt" },
895
1434
  ],
1435
+ conflicts: [["auth", "id"]],
896
1436
  run: commandStart,
897
1437
  },
898
1438
  run: {
899
1439
  help: "Jev: work toward the goal until Claude or a person is needed",
900
1440
  options: [
1441
+ idOption,
901
1442
  { name: "value", type: "string", multiple: true, metavar: "LABEL=VALUE", help: "Add or replace a value" },
902
1443
  { name: "human-done", type: "boolean", help: "The person finished what NEEDS_HUMAN asked" },
903
1444
  ],
904
1445
  run: commandRun,
905
1446
  },
1447
+ answer: {
1448
+ help: "Claude (v2): answer Jev's question and continue the same attempt",
1449
+ options: [
1450
+ idOption,
1451
+ { name: "note", type: "string", required: true, help: "A short instruction for Jev; it sees it" },
1452
+ { name: "value", type: "string", multiple: true, metavar: "LABEL=VALUE", help: "Add or replace a value" },
1453
+ { name: "url", type: "string", help: "Open this page first (the same attempt continues)" },
1454
+ ],
1455
+ run: commandAnswer,
1456
+ },
906
1457
  replan: {
907
1458
  help: "Claude: revise the plan and start the next attempt",
908
1459
  options: [
1460
+ idOption,
909
1461
  { name: "reason", type: "string", required: true, help: "Why the last attempt fell short; Jev sees it" },
910
1462
  { name: "step", type: "string", multiple: true, help: "Replace the steps" },
911
1463
  { name: "value", type: "string", multiple: true, metavar: "LABEL=VALUE" },
912
1464
  { name: "restart", type: "boolean", help: "Open the start URL again before the next attempt" },
1465
+ { name: "url", type: "string", help: "Open this URL before the next attempt instead (another way in)" },
913
1466
  ...viewOptions,
1467
+ compareOption,
1468
+ collectOption,
1469
+ moreOption,
914
1470
  ],
915
1471
  run: commandReplan,
916
1472
  },
917
1473
  act: {
918
1474
  help: "Claude: override Jev with one operation",
919
- options: [{ name: "text", type: "string" }],
1475
+ options: [idOption, { name: "text", type: "string" }],
920
1476
  positionals: [{ name: "operation" }, { name: "target", optional: true }],
921
1477
  run: commandAct,
922
1478
  },
923
- observe: { help: "Print the current page", options: [], run: commandObserve },
1479
+ observe: { help: "Print the current page", options: [idOption], run: commandObserve },
924
1480
  finish: {
925
1481
  help: "Verify, log, and close Chrome",
926
1482
  options: [
1483
+ idOption,
927
1484
  {
928
1485
  name: "status",
929
1486
  type: "string",
@@ -953,6 +1510,24 @@ function commands() {
953
1510
  ],
954
1511
  run: commandLearn,
955
1512
  },
1513
+ auth: {
1514
+ help: "Saved logins: list, save NAME (from a session), delete NAME",
1515
+ options: [idOption],
1516
+ positionals: [
1517
+ { name: "action", choices: ["list", "save", "delete"] },
1518
+ { name: "name", optional: true },
1519
+ ],
1520
+ run: commandAuth,
1521
+ },
1522
+ knowledge: {
1523
+ help: "What webhand learned about sites from its own runs: list, show HOST, clear [HOST]",
1524
+ options: [],
1525
+ positionals: [
1526
+ { name: "action", choices: ["list", "show", "clear"] },
1527
+ { name: "name", optional: true },
1528
+ ],
1529
+ run: commandKnowledge,
1530
+ },
956
1531
  profile: {
957
1532
  help: "Saved profiles: list, login NAME --url URL, delete NAME",
958
1533
  options: [{ name: "url", type: "string" }, chromeOption, { name: "max-minutes", type: "float", default: 15 }],
@@ -1011,7 +1586,7 @@ function mainHelp(specs) {
1011
1586
  lines.push("", " --version Print the version", " --help Print this help; COMMAND --help prints a command's options");
1012
1587
  return `${lines.join("\n")}\n`;
1013
1588
  }
1014
- /** Parses argv as argparse did. Throws UsageError, or returns help text to print. */
1589
+ /** Parses argv, with argparse-style messages. Throws UsageError, or returns help text to print. */
1015
1590
  export function parse(argv) {
1016
1591
  const specs = commands();
1017
1592
  const [name, ...rest] = argv;
@@ -1023,7 +1598,7 @@ export function parse(argv) {
1023
1598
  return { help: `${version()}\n` };
1024
1599
  const spec = specs[name];
1025
1600
  if (!spec)
1026
- throw new UsageError(`argument command: invalid choice: ${pyRepr(name)}`);
1601
+ throw new UsageError(`argument command: invalid choice: ${quote(name)}`);
1027
1602
  const args = {};
1028
1603
  const positionals = [];
1029
1604
  const byName = new Map(spec.options.map((option) => [option.name, option]));
@@ -1054,7 +1629,7 @@ export function parse(argv) {
1054
1629
  seen.add(option.name);
1055
1630
  if (option.type === "boolean") {
1056
1631
  if (at >= 0)
1057
- throw fail(`argument --${option.name}: ignored explicit argument ${pyRepr(token.slice(at + 1))}`);
1632
+ throw fail(`argument --${option.name}: ignored explicit argument ${quote(token.slice(at + 1))}`);
1058
1633
  args[key] = true;
1059
1634
  continue;
1060
1635
  }
@@ -1072,18 +1647,18 @@ export function parse(argv) {
1072
1647
  let value = raw;
1073
1648
  if (option.type === "int") {
1074
1649
  if (!/^\s*[-+]?\d+\s*$/.test(raw))
1075
- throw fail(`argument --${option.name}: invalid int value: ${pyRepr(raw)}`);
1650
+ throw fail(`argument --${option.name}: invalid int value: ${quote(raw)}`);
1076
1651
  value = Number.parseInt(raw, 10);
1077
1652
  }
1078
1653
  else if (option.type === "float") {
1079
1654
  const number = Number(raw);
1080
1655
  if (!raw.trim() || Number.isNaN(number)) {
1081
- throw fail(`argument --${option.name}: invalid float value: ${pyRepr(raw)}`);
1656
+ throw fail(`argument --${option.name}: invalid float value: ${quote(raw)}`);
1082
1657
  }
1083
1658
  value = number;
1084
1659
  }
1085
1660
  if (option.choices && !option.choices.includes(String(value))) {
1086
- throw fail(`argument --${option.name}: invalid choice: ${pyRepr(value)} (choose from ${option.choices.map(pyRepr).join(", ")})`);
1661
+ throw fail(`argument --${option.name}: invalid choice: ${quote(value)} (choose from ${option.choices.map(quote).join(", ")})`);
1087
1662
  }
1088
1663
  if (option.multiple)
1089
1664
  args[key].push(value);
@@ -1101,10 +1676,14 @@ export function parse(argv) {
1101
1676
  declared.forEach((positional, i) => {
1102
1677
  const value = positionals[i] ?? null;
1103
1678
  if (value !== null && positional.choices && !positional.choices.includes(value)) {
1104
- throw fail(`argument ${positional.name}: invalid choice: ${pyRepr(value)} (choose from ${positional.choices.map(pyRepr).join(", ")})`);
1679
+ throw fail(`argument ${positional.name}: invalid choice: ${quote(value)} (choose from ${positional.choices.map(quote).join(", ")})`);
1105
1680
  }
1106
1681
  args[positional.name] = value;
1107
1682
  });
1683
+ for (const [a, b] of spec.conflicts ?? []) {
1684
+ if (seen.has(a) && seen.has(b))
1685
+ throw fail(`argument --${a}: not allowed with argument --${b}`);
1686
+ }
1108
1687
  const required = spec.options.filter((option) => option.required && !seen.has(option.name));
1109
1688
  if (required.length) {
1110
1689
  throw fail(`the following arguments are required: ${required.map((option) => `--${option.name}`).join(", ")}`);
@@ -1123,22 +1702,41 @@ const processIO = {
1123
1702
  * Runs one command and returns its exit code. A CliExit or UsageError is thrown after the output is written,
1124
1703
  * so the caller prints its message and exits with 1 or 2.
1125
1704
  */
1126
- export async function main(argv, io = processIO) {
1705
+ const SESSION_COMMANDS = ["start", "run", "answer", "replan", "act", "observe", "finish"];
1706
+ /** Picks the session a command works on and holds its lock until the command ends. Returns the release function. */
1707
+ function takeSession(command, args) {
1708
+ if (!SESSION_COMMANDS.includes(command) && !(command === "auth" && args.action === "save")) {
1709
+ session.use();
1710
+ return () => { };
1711
+ }
1712
+ try {
1713
+ session.use(args.id);
1714
+ return session.lock();
1715
+ }
1716
+ catch (error) {
1717
+ if (error instanceof session.SessionError)
1718
+ throw new CliExit(error.message);
1719
+ throw error;
1720
+ }
1721
+ }
1722
+ export async function main(argv, io = processIO, hooks = {}) {
1127
1723
  const parsed = parse(argv);
1128
1724
  if ("help" in parsed) {
1129
1725
  io.out(parsed.help);
1130
1726
  return OK;
1131
1727
  }
1132
- context = { out: [], err: io.err, log: null };
1728
+ context = { out: [], err: io.err, log: null, hooks };
1133
1729
  const current = context;
1730
+ const release = takeSession(parsed.command, parsed.args);
1134
1731
  // What Claude must read is a real cost of this design, so every handoff is sized and logged.
1135
1732
  try {
1136
1733
  return await parsed.run(parsed.args);
1137
1734
  }
1138
1735
  finally {
1736
+ release();
1139
1737
  const text = current.out.join("");
1140
1738
  io.out(text);
1141
1739
  if (current.log)
1142
- logOnce(current.log, "handoff", { command: parsed.command, chars: pyLen(text) });
1740
+ logOnce(current.log, "handoff", { command: parsed.command, chars: [...text].length });
1143
1741
  }
1144
1742
  }