webhand 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ja.md +19 -4
- package/README.md +19 -4
- package/assets/recorder.js +4 -0
- package/assets/snapshot.js +218 -3
- package/dist/agent.js +136 -9
- package/dist/auth.js +62 -0
- package/dist/browser.js +701 -22
- package/dist/cli.js +641 -35
- package/dist/collect.js +70 -0
- package/dist/compare.js +173 -0
- package/dist/daemon.js +125 -0
- package/dist/knowledge.js +206 -0
- package/dist/learn.js +10 -3
- package/dist/metrics.js +19 -2
- package/dist/more.js +58 -0
- package/dist/policies/base.js +105 -9
- package/dist/policies/jev.js +243 -16
- package/dist/remote.js +165 -0
- package/dist/runbook.js +6 -1
- package/dist/session.js +256 -12
- package/dist/types.js +12 -0
- package/package.json +1 -1
package/dist/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
|
|
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
|
-
|
|
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
|
-
|
|
148
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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", {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
515
|
-
|
|
516
|
-
|
|
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
|
|
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
|
|
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] =
|
|
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] =
|
|
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
|
-
|
|
819
|
-
|
|
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)
|