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/cli.js CHANGED
@@ -8,12 +8,18 @@ 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";
12
15
  import { describeError, quote, show, stamp, toJson } from "./format.js";
16
+ import { Knowledge } from "./knowledge.js";
13
17
  import * as learn from "./learn.js";
14
- import { gitState, logOnce, pageEvent, Recorder, summarize } from "./metrics.js";
18
+ import { gitState, logOnce, maskUrls, pageEvent, Recorder, safeUrl, summarize } from "./metrics.js";
19
+ import { loadMore } from "./more.js";
15
20
  import { actionSpace, offscreen, planText, resolve } from "./policies/base.js";
16
21
  import { JevPolicy } from "./policies/jev.js";
22
+ import { RemoteBrowser } from "./remote.js";
17
23
  import * as runbook from "./runbook.js";
18
24
  import * as session from "./session.js";
19
25
  import { MutationUncertain, PolicyError, StalePage, } from "./types.js";
@@ -41,7 +47,16 @@ export const deps = {
41
47
  };
42
48
  let context = { out: [], err: () => { }, log: null, hooks: {} };
43
49
  function print(text = "") {
44
- 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}`);
45
60
  }
46
61
  /** Runs fn and returns what it printed. For tests of the output Claude reads. */
47
62
  export function captured(fn) {
@@ -57,7 +72,13 @@ export function captured(fn) {
57
72
  }
58
73
  // --- Output Claude reads -------------------------------------------------------------------
59
74
  export function render(page) {
60
- 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:");
61
82
  const [elements, , controls] = actionSpace(page.actions);
62
83
  for (const element of elements) {
63
84
  // Claude sees every option with its own line.
@@ -66,6 +87,8 @@ export function render(page) {
66
87
  if (key in element)
67
88
  details.push(`${key}=${show(element[key])}`);
68
89
  }
90
+ if (element.at)
91
+ details.push(`at=${quote(element.at)}`);
69
92
  const operations = element.operations.join(",");
70
93
  lines.push(`[${element.index}] ${show(element.role)} ${quote(element.label)} ${details.join(" ")} (${operations})`);
71
94
  for (const option of element.options ?? []) {
@@ -93,17 +116,68 @@ function regionLine(region) {
93
116
  return line + (region.view ? ` (${region.view})` : "");
94
117
  }
95
118
  function headline(page) {
96
- 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");
97
163
  }
98
164
  export function describePlan(plan, view = null) {
99
165
  const text = planText(plan);
100
166
  const lines = [`GOAL: ${plan.goal}`, "PLAN:", ...(text.length ? text : ["(goal only)"]).map((line) => ` ${line}`)];
101
167
  if (plan.values.length)
102
168
  lines.push(`VALUES: ${plan.values.map((value) => value.label).join(", ")}`);
103
- for (const key of ["focus", "skip"]) {
169
+ for (const key of ["focus", "skip", "read"]) {
104
170
  if (view?.[key]?.length)
105
171
  lines.push(`${key.toUpperCase()}: ${view[key].join(", ")}`);
106
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}`);
107
181
  return lines.join("\n");
108
182
  }
109
183
  // biome-ignore lint/suspicious/noExplicitAny: the session state.
@@ -144,10 +218,35 @@ function requireSession() {
144
218
  context.log = state.log;
145
219
  return state;
146
220
  }
147
- async function openPage(state, url = null) {
148
- 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));
149
239
  try {
150
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
+ }
151
250
  }
152
251
  finally {
153
252
  await browser.close();
@@ -161,6 +260,24 @@ function defaultLog(name) {
161
260
  return process.env.WEBHAND_LOG || join(workspace.home(), "runs", stamp(), `${name}.jsonl`);
162
261
  }
163
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
+ }
164
281
  /** Everything learned, for Claude to plan from. */
165
282
  async function commandCatalog(args) {
166
283
  const project = workspace.projectRoot();
@@ -215,6 +332,12 @@ async function commandCatalog(args) {
215
332
  const profiles = session.listProfiles(chrome);
216
333
  print(`CHROME: ${chrome}${note ? ` (${note})` : ""}`);
217
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
+ }
218
341
  return OK;
219
342
  }
220
343
  function chooseChrome(choice) {
@@ -228,15 +351,18 @@ function chooseChrome(choice) {
228
351
  }
229
352
  }
230
353
  async function commandStart(args) {
231
- if (session.load())
232
- throw new CliExit("A session is active. Run: webhand finish --status abandoned");
354
+ if (session.load()) {
355
+ throw new CliExit(named("A session is active. Run: webhand finish --status abandoned, or start another with --id"));
356
+ }
233
357
  const task = context.hooks.task ?? null;
234
358
  let book = null;
235
359
  let service = null;
236
360
  let serviceName = null;
237
361
  let profile;
238
362
  let chrome;
363
+ let engine;
239
364
  let note;
365
+ let login = null;
240
366
  try {
241
367
  if (args.runbook) {
242
368
  book = runbook.load(args.runbook, runbook.parseValues(args.param));
@@ -247,7 +373,19 @@ async function commandStart(args) {
247
373
  serviceName = args.service || (book ? book.service : null);
248
374
  service = serviceName ? runbook.loadService(serviceName) : null;
249
375
  profile = session.parseSession(args.session);
250
- [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];
251
389
  }
252
390
  catch (error) {
253
391
  if (error instanceof runbook.RunbookError || error instanceof session.SessionError) {
@@ -273,6 +411,8 @@ async function commandStart(args) {
273
411
  if (steps.some((step) => step.actor === "human") && !args.headed) {
274
412
  throw new CliExit("This plan has [person] steps. Add --headed so the person can see the window");
275
413
  }
414
+ if (!FLOWS.includes(args.flow))
415
+ throw new CliExit(`WEBHAND_FLOW must be one of: ${FLOWS.join(", ")}`);
276
416
  if (!process.env.TYPESAFE_API_KEY) {
277
417
  throw new CliExit("TYPESAFE_API_KEY is not set. Set it as an environment variable");
278
418
  }
@@ -283,10 +423,18 @@ async function commandStart(args) {
283
423
  notes: [],
284
424
  attempt: 1,
285
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" } : {}),
286
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");
287
435
  let chromeState;
288
436
  try {
289
- chromeState = await deps.startChrome({ headed: args.headed, profile, chrome });
437
+ chromeState = await deps.startChrome({ headed: args.headed, profile, chrome, engine });
290
438
  }
291
439
  catch (error) {
292
440
  if (error instanceof session.SessionError)
@@ -294,7 +442,7 @@ async function commandStart(args) {
294
442
  throw error;
295
443
  }
296
444
  const learned = runbook.view(runbook.serviceView(service), book);
297
- const claudeView = { focus: args.focus, skip: args.skip };
445
+ const claudeView = { focus: args.focus, skip: args.skip, read: args.read };
298
446
  const state = {
299
447
  ...chromeState,
300
448
  view_learned: learned,
@@ -319,19 +467,29 @@ async function commandStart(args) {
319
467
  context.log = state.log;
320
468
  const recorder = new Recorder(state.log);
321
469
  let browser = null;
470
+ let skipped = [];
322
471
  try {
323
- 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
+ }
324
479
  state.page = await browser.observe();
325
480
  recorder.event("run_start", {
326
481
  task,
327
482
  goal,
328
483
  chrome: browser.version,
329
484
  chrome_host: chrome,
485
+ ...(engine !== "chrome" ? { engine } : {}),
330
486
  session: profile ? "profile" : "new",
487
+ ...(args.auth ? { auth: args.auth } : {}),
331
488
  git: gitState(),
332
489
  runbook: state.runbook,
333
490
  service: serviceName,
334
491
  view: state.view,
492
+ ...(plan.flow ? { flow: plan.flow } : {}),
335
493
  max_attempts: args.max_attempts,
336
494
  started_at: new Date().toISOString(),
337
495
  });
@@ -340,11 +498,25 @@ async function commandStart(args) {
340
498
  steps: planText(plan),
341
499
  values: values.map((v) => v.label),
342
500
  view: state.view,
501
+ ...(plan.compare ? { compare: plan.compare } : {}),
502
+ ...(plan.collect ? { collect: plan.collect } : {}),
503
+ ...(plan.more ? { more: plan.more } : {}),
343
504
  source: book && !args.step.length ? "runbook" : "claude",
344
505
  });
345
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);
346
509
  }
347
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
+ });
348
520
  await session.stopChrome(chromeState);
349
521
  throw error;
350
522
  }
@@ -355,10 +527,56 @@ async function commandStart(args) {
355
527
  session.save(state);
356
528
  if (note)
357
529
  print(`NOTE: ${note}`);
358
- 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)}`);
359
536
  print("NEXT: webhand run");
360
537
  return OK;
361
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
+ }
362
580
  /** What Claude needs for this outcome, and nothing more. */
363
581
  export function report(state, result) {
364
582
  const outcome = result.outcome;
@@ -377,6 +595,12 @@ export function report(state, result) {
377
595
  return OK;
378
596
  }
379
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
+ }
380
604
  if (outcome === agent.GOAL_REPORTED) {
381
605
  print("Check the page against the goal. If it is met: finish --status done. Otherwise: replan");
382
606
  }
@@ -404,8 +628,8 @@ async function commandRun(args) {
404
628
  print("REJECTED: this field needs run --value 'LABEL=VALUE'");
405
629
  return FAILED;
406
630
  }
407
- if ([agent.GOAL_REPORTED, agent.BLOCKED, agent.STUCK, agent.ATTEMPT_BUDGET].includes(outcome)) {
408
- 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`);
409
633
  return FAILED;
410
634
  }
411
635
  if (args.value.length) {
@@ -436,14 +660,97 @@ async function commandRun(args) {
436
660
  state.outcome = null;
437
661
  session.save(state);
438
662
  const policy = deps.policy();
439
- const browser = await Browser.open(null, { port: state.port, view: state.view ?? null });
663
+ const browser = await attach(state, null, browserView(state));
440
664
  const recorder = new Recorder(state.log);
441
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
+ };
442
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
+ }
443
746
  result = await runAgent(browser, policy, state.plan, recorder, new Budget(state.max_actions, state.max_decisions), {
444
747
  history: state.history,
445
748
  page: state.page,
446
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,
447
754
  onChange: (page) => {
448
755
  state.page = page;
449
756
  session.save(state);
@@ -455,7 +762,15 @@ async function commandRun(args) {
455
762
  });
456
763
  state.page = result.page;
457
764
  state.outcome = result.outcome;
458
- 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
+ }
459
774
  if (result.outcome === agent.NEEDS_HUMAN) {
460
775
  recorder.event("human_step", { status: "requested", attempt: state.plan.attempt });
461
776
  }
@@ -468,6 +783,61 @@ async function commandRun(args) {
468
783
  }
469
784
  return report(state, result);
470
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
+ }
471
841
  /** Claude revises the plan after an attempt fell short, and starts the next attempt. */
472
842
  async function commandReplan(args) {
473
843
  const state = requireSession();
@@ -480,6 +850,29 @@ async function commandReplan(args) {
480
850
  print(`ATTEMPTS EXHAUSTED (${state.max_attempts}). Run: webhand finish --status blocked`);
481
851
  return BUDGET;
482
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
+ }
483
876
  if (args.step.length) {
484
877
  const steps = parseSteps(args.step);
485
878
  if (steps.some((step) => step.actor === "human") && !state.headed) {
@@ -489,10 +882,32 @@ async function commandReplan(args) {
489
882
  plan.steps = steps;
490
883
  }
491
884
  plan.values = mergeValues(plan.values, parseValues(args.value));
492
- 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;
493
902
  if (viewChanged) {
494
- // Claude's region choice is replaced, on top of what was learned.
495
- 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
+ };
496
911
  state.view = runbook.view(state.view_learned, state.view_claude);
497
912
  }
498
913
  const ended = state.outcome || "CLAUDE_STOPPED";
@@ -508,12 +923,19 @@ async function commandReplan(args) {
508
923
  steps: planText(plan),
509
924
  values: plan.values.map((v) => v.label),
510
925
  view: state.view ?? null,
926
+ ...(plan.compare ? { compare: plan.compare } : {}),
927
+ ...(plan.collect ? { collect: plan.collect } : {}),
928
+ ...(plan.more ? { more: plan.more } : {}),
511
929
  restart: args.restart,
930
+ ...(url ? { url: safeUrl(url) } : {}),
512
931
  source: "claude",
513
932
  });
514
- if (args.restart)
515
- await openPage(state, state.start_url); // Navigation only; no earlier mutation is repeated.
516
- 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)
517
939
  await openPage(state); // Observe again with the new regions.
518
940
  print(`${describePlan(plan, state.view ?? null)}\nATTEMPT ${plan.attempt}/${state.max_attempts}\n${headline(state.page)}`);
519
941
  print("NEXT: webhand run");
@@ -561,7 +983,7 @@ async function commandAct(args) {
561
983
  decision.text = decision.action.kind === "fill" ? args.text : null;
562
984
  state.decisions += 1;
563
985
  session.save(state);
564
- const browser = await Browser.open(null, { port: state.port, view: state.view ?? null });
986
+ const browser = await attach(state, null, browserView(state));
565
987
  const recorder = new Recorder(state.log);
566
988
  try {
567
989
  await execute(browser, state.page, decision, state.history, recorder, {
@@ -607,6 +1029,7 @@ function runTotals(log) {
607
1029
  let handoffs = 0;
608
1030
  let handoffChars = 0;
609
1031
  let notVisible = 0;
1032
+ let stale = 0;
610
1033
  for (const line of readFileSync(log, "utf8").split("\n")) {
611
1034
  if (!line.trim())
612
1035
  continue;
@@ -619,6 +1042,8 @@ function runTotals(log) {
619
1042
  decidedBy[event.decided_by] = (decidedBy[event.decided_by] ?? 0) + 1;
620
1043
  else if (type === "not_visible")
621
1044
  notVisible += 1;
1045
+ else if (type === "stale")
1046
+ stale += 1;
622
1047
  else if (type === "handoff") {
623
1048
  handoffs += 1;
624
1049
  handoffChars += event.chars;
@@ -631,6 +1056,7 @@ function runTotals(log) {
631
1056
  handoffs,
632
1057
  handoff_chars: handoffChars,
633
1058
  not_visible: notVisible,
1059
+ stale,
634
1060
  };
635
1061
  }
636
1062
  /** Verifies the page independently when a verifier was given. The status is what the agent claims, nothing more. */
@@ -642,9 +1068,9 @@ async function commandFinish(args) {
642
1068
  try {
643
1069
  const verify = context.hooks.verify;
644
1070
  if (verify) {
645
- const browser = await Browser.open(null, { port: state.port });
1071
+ const browser = await attach(state, null);
646
1072
  try {
647
- verdict = await verify(browser, state);
1073
+ verdict = await verify(browser, state); // A remote browser has evaluate, which is what verifiers use.
648
1074
  }
649
1075
  finally {
650
1076
  await browser.close();
@@ -659,6 +1085,10 @@ async function commandFinish(args) {
659
1085
  session.clear();
660
1086
  }
661
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
+ }
662
1092
  const outcomes = [...state.outcomes, { attempt: plan.attempt, outcome: state.outcome, reason: args.reason }];
663
1093
  const totals = runTotals(state.log);
664
1094
  logOnce(state.log, "run_end", {
@@ -670,7 +1100,7 @@ async function commandFinish(args) {
670
1100
  plan: planText(plan),
671
1101
  attempts: plan.attempt,
672
1102
  attempt_outcomes: outcomes,
673
- actions: state.history.length,
1103
+ actions: agent.executed(state.history).length,
674
1104
  decisions: state.decisions,
675
1105
  elapsed_ms: Math.round((Date.now() / 1000 - state.started) * 1000),
676
1106
  verified: verdict.success,
@@ -722,7 +1152,7 @@ async function commandLearn(args) {
722
1152
  const parts = String(args.name).split("/");
723
1153
  serviceFile = parts.length > 1 ? runbook.servicePath(parts[0], args.scope) : null;
724
1154
  profile = session.parseSession(args.session);
725
- [chrome, note] = session.chooseChrome(args.chrome);
1155
+ [chrome, note] = chooseChrome(args.chrome);
726
1156
  }
727
1157
  catch (error) {
728
1158
  if (error instanceof runbook.RunbookError || error instanceof session.SessionError) {
@@ -793,7 +1223,7 @@ async function commandProfile(args) {
793
1223
  let chrome;
794
1224
  try {
795
1225
  let note;
796
- [chrome, note] = session.chooseChrome(args.chrome);
1226
+ [chrome, note] = chooseChrome(args.chrome);
797
1227
  if (note)
798
1228
  print(`NOTE: ${note}`);
799
1229
  if (args.action === "list") {
@@ -815,9 +1245,8 @@ async function commandProfile(args) {
815
1245
  }
816
1246
  if (!args.url)
817
1247
  throw new CliExit("profile login needs --url");
818
- const active = session.load();
819
- if (active && active.saved_profile === args.name) {
820
- 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`);
821
1250
  }
822
1251
  chromeState = await session.startChrome({ headed: true, profile: args.name, chrome });
823
1252
  }
@@ -841,8 +1270,75 @@ async function commandProfile(args) {
841
1270
  print(`SAVED profile ${args.name}. Use it with: start --session profile:${args.name}`);
842
1271
  return OK;
843
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"];
844
1334
  function commands() {
845
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
+ };
846
1342
  const chromeOption = {
847
1343
  name: "chrome",
848
1344
  type: "string",
@@ -850,6 +1346,13 @@ function commands() {
850
1346
  default: chromeDefault,
851
1347
  help: "auto uses the Windows Chrome on WSL when it is reachable",
852
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
+ };
853
1356
  const viewOptions = [
854
1357
  {
855
1358
  name: "focus",
@@ -859,7 +1362,33 @@ function commands() {
859
1362
  help: "A region to show first, such as form:予約",
860
1363
  },
861
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
+ },
862
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
+ };
863
1392
  return {
864
1393
  catalog: {
865
1394
  help: "List learned services, procedures, and saved profiles",
@@ -869,6 +1398,7 @@ function commands() {
869
1398
  start: {
870
1399
  help: "Record Claude's plan and open the start page",
871
1400
  options: [
1401
+ idOption,
872
1402
  { name: "goal", type: "string" },
873
1403
  { name: "url", type: "string" },
874
1404
  { name: "step", type: "string", multiple: true, help: 'A plan step. "[person] ..." is done by a person' },
@@ -878,44 +1408,79 @@ function commands() {
878
1408
  { name: "param", type: "string", multiple: true, metavar: "KEY=VALUE", help: "A runbook parameter" },
879
1409
  { name: "allow-draft", type: "boolean", help: "Trial a runbook no person has approved yet" },
880
1410
  ...viewOptions,
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
+ },
881
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
+ },
882
1428
  chromeOption,
1429
+ engineOption,
883
1430
  { name: "headed", type: "boolean" },
884
1431
  { name: "max-attempts", type: "int", default: DEFAULT_ATTEMPTS },
885
1432
  { name: "max-actions", type: "int", default: Budget.MAX_ACTIONS, help: "Per attempt" },
886
1433
  { name: "max-decisions", type: "int", default: Budget.MAX_DECISIONS, help: "Per attempt" },
887
1434
  ],
1435
+ conflicts: [["auth", "id"]],
888
1436
  run: commandStart,
889
1437
  },
890
1438
  run: {
891
1439
  help: "Jev: work toward the goal until Claude or a person is needed",
892
1440
  options: [
1441
+ idOption,
893
1442
  { name: "value", type: "string", multiple: true, metavar: "LABEL=VALUE", help: "Add or replace a value" },
894
1443
  { name: "human-done", type: "boolean", help: "The person finished what NEEDS_HUMAN asked" },
895
1444
  ],
896
1445
  run: commandRun,
897
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
+ },
898
1457
  replan: {
899
1458
  help: "Claude: revise the plan and start the next attempt",
900
1459
  options: [
1460
+ idOption,
901
1461
  { name: "reason", type: "string", required: true, help: "Why the last attempt fell short; Jev sees it" },
902
1462
  { name: "step", type: "string", multiple: true, help: "Replace the steps" },
903
1463
  { name: "value", type: "string", multiple: true, metavar: "LABEL=VALUE" },
904
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)" },
905
1466
  ...viewOptions,
1467
+ compareOption,
1468
+ collectOption,
1469
+ moreOption,
906
1470
  ],
907
1471
  run: commandReplan,
908
1472
  },
909
1473
  act: {
910
1474
  help: "Claude: override Jev with one operation",
911
- options: [{ name: "text", type: "string" }],
1475
+ options: [idOption, { name: "text", type: "string" }],
912
1476
  positionals: [{ name: "operation" }, { name: "target", optional: true }],
913
1477
  run: commandAct,
914
1478
  },
915
- observe: { help: "Print the current page", options: [], run: commandObserve },
1479
+ observe: { help: "Print the current page", options: [idOption], run: commandObserve },
916
1480
  finish: {
917
1481
  help: "Verify, log, and close Chrome",
918
1482
  options: [
1483
+ idOption,
919
1484
  {
920
1485
  name: "status",
921
1486
  type: "string",
@@ -945,6 +1510,24 @@ function commands() {
945
1510
  ],
946
1511
  run: commandLearn,
947
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
+ },
948
1531
  profile: {
949
1532
  help: "Saved profiles: list, login NAME --url URL, delete NAME",
950
1533
  options: [{ name: "url", type: "string" }, chromeOption, { name: "max-minutes", type: "float", default: 15 }],
@@ -1097,6 +1680,10 @@ export function parse(argv) {
1097
1680
  }
1098
1681
  args[positional.name] = value;
1099
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
+ }
1100
1687
  const required = spec.options.filter((option) => option.required && !seen.has(option.name));
1101
1688
  if (required.length) {
1102
1689
  throw fail(`the following arguments are required: ${required.map((option) => `--${option.name}`).join(", ")}`);
@@ -1115,6 +1702,23 @@ const processIO = {
1115
1702
  * Runs one command and returns its exit code. A CliExit or UsageError is thrown after the output is written,
1116
1703
  * so the caller prints its message and exits with 1 or 2.
1117
1704
  */
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
+ }
1118
1722
  export async function main(argv, io = processIO, hooks = {}) {
1119
1723
  const parsed = parse(argv);
1120
1724
  if ("help" in parsed) {
@@ -1123,11 +1727,13 @@ export async function main(argv, io = processIO, hooks = {}) {
1123
1727
  }
1124
1728
  context = { out: [], err: io.err, log: null, hooks };
1125
1729
  const current = context;
1730
+ const release = takeSession(parsed.command, parsed.args);
1126
1731
  // What Claude must read is a real cost of this design, so every handoff is sized and logged.
1127
1732
  try {
1128
1733
  return await parsed.run(parsed.args);
1129
1734
  }
1130
1735
  finally {
1736
+ release();
1131
1737
  const text = current.out.join("");
1132
1738
  io.out(text);
1133
1739
  if (current.log)