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