webhand 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/runbook.js CHANGED
@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
9
9
  import { dirname, join, resolve } from "node:path";
10
10
  import { pathToFileURL } from "node:url";
11
11
  import { parse } from "smol-toml";
12
- import { pyRepr, pyStr, pyTruthy } from "./py.js";
12
+ import { quote, show } from "./format.js";
13
13
  import { roots, scopeRoot } from "./workspace.js";
14
14
  const WORD = "[\\p{L}\\p{N}_-]+";
15
15
  const NAME = new RegExp(`^${WORD}(/${WORD})?$`, "u");
@@ -34,13 +34,13 @@ export class RunbookError extends Error {
34
34
  /** Checks a runbook name such as hotel/filter. */
35
35
  function checkName(name) {
36
36
  if (!NAME.test(name) || name.split("/").at(-1) === SERVICE_FILE) {
37
- throw new RunbookError(`Invalid runbook name: ${pyRepr(name)}`);
37
+ throw new RunbookError(`Invalid runbook name: ${quote(name)}`);
38
38
  }
39
39
  return name;
40
40
  }
41
41
  function checkService(service) {
42
42
  if (!SERVICE_NAME.test(service))
43
- throw new RunbookError(`Invalid service name: ${pyRepr(service)}`);
43
+ throw new RunbookError(`Invalid service name: ${quote(service)}`);
44
44
  return service;
45
45
  }
46
46
  /** Where a runbook of a scope is written. */
@@ -83,6 +83,16 @@ function readToml(file) {
83
83
  throw new RunbookError(`${file}: ${error instanceof Error ? error.message : String(error)}`);
84
84
  }
85
85
  }
86
+ /** Missing, false, zero, or an empty string, list, or table. */
87
+ function blank(value) {
88
+ if (value === null || value === undefined || value === false || value === 0 || value === "")
89
+ return true;
90
+ if (Array.isArray(value))
91
+ return value.length === 0;
92
+ if (typeof value === "object")
93
+ return Object.keys(value).length === 0;
94
+ return false;
95
+ }
86
96
  const get = (doc, key, fallback = undefined) => (key in doc ? doc[key] : fallback);
87
97
  /** Region patterns, such as "main/form:宿泊予約" or "footer". Anything else is an error. */
88
98
  function patterns(file, where, value) {
@@ -102,7 +112,7 @@ function regions(file, page) {
102
112
  throw new RunbookError(`${file}: a region on ${get(page, "url", "?")} has no key`);
103
113
  const fallback = get(region, "default", null);
104
114
  if (fallback !== null && !DEFAULTS.has(fallback)) {
105
- throw new RunbookError(`${file}: region ${pyRepr(key[0])} has unknown default ${pyRepr(fallback)}`);
115
+ throw new RunbookError(`${file}: region ${quote(key[0])} has unknown default ${quote(fallback)}`);
106
116
  }
107
117
  found.push({ key: key[0], purpose: get(region, "purpose", ""), default: fallback });
108
118
  }
@@ -116,7 +126,7 @@ export function view(...layers) {
116
126
  let focus = [];
117
127
  let skip = [];
118
128
  for (const layer of layers) {
119
- if (!pyTruthy(layer))
129
+ if (blank(layer))
120
130
  continue;
121
131
  const newFocus = [...(layer?.focus ?? [])];
122
132
  const newSkip = [...(layer?.skip ?? [])];
@@ -141,7 +151,7 @@ export function loadService(service) {
141
151
  return null;
142
152
  const { file, scope } = found;
143
153
  const { data } = readToml(file);
144
- const missing = ["service", "description", "base_url", "sources"].filter((key) => !pyTruthy(data[key]));
154
+ const missing = ["service", "description", "base_url"].filter((key) => blank(data[key]));
145
155
  if (missing.length)
146
156
  throw new RunbookError(`${file}: missing ${missing.join(", ")}`);
147
157
  const login = get(data, "login", {});
@@ -149,13 +159,13 @@ export function loadService(service) {
149
159
  service: data.service,
150
160
  description: String(data.description).trim(),
151
161
  base_url: data.base_url,
152
- login: { required: pyTruthy(get(login, "required")), url: get(login, "url", null) },
162
+ login: { required: !blank(get(login, "required")), url: get(login, "url", null) },
153
163
  pages: get(data, "pages", []).map((p) => ({
154
164
  url: get(p, "url", ""),
155
165
  purpose: get(p, "purpose", ""),
156
166
  regions: regions(file, p),
157
167
  })),
158
- facts: get(data, "facts", []).map(pyStr),
168
+ facts: get(data, "facts", []).map(show),
159
169
  scope,
160
170
  };
161
171
  }
@@ -207,7 +217,7 @@ export function parseValues(pairs) {
207
217
  for (const pair of pairs) {
208
218
  const at = pair.indexOf("=");
209
219
  if (at <= 0)
210
- throw new RunbookError(`Expected KEY=VALUE, got ${pyRepr(pair)}`);
220
+ throw new RunbookError(`Expected KEY=VALUE, got ${quote(pair)}`);
211
221
  values[pair.slice(0, at)] = pair.slice(at + 1);
212
222
  }
213
223
  return values;
@@ -235,40 +245,40 @@ export function load(name, values = {}) {
235
245
  }
236
246
  export function loadFile(file, name, scope, values = {}, base = process.cwd()) {
237
247
  const { raw, data } = readToml(file);
238
- const required = ["service", "name", "goal", "start_url", "status", "sources", "steps"];
239
- const missing = required.filter((key) => !pyTruthy(data[key]));
248
+ const required = ["service", "name", "goal", "start_url", "status", "steps"];
249
+ const missing = required.filter((key) => blank(data[key]));
240
250
  if (missing.length)
241
251
  throw new RunbookError(`${file}: missing ${missing.join(", ")}`);
242
252
  if (!STATUSES.has(data.status))
243
- throw new RunbookError(`${file}: unknown status ${pyRepr(data.status)}`);
253
+ throw new RunbookError(`${file}: unknown status ${quote(data.status)}`);
244
254
  const declared = get(data, "params", {});
245
255
  const unknown = Object.keys(values)
246
256
  .filter((key) => !(key in declared))
247
257
  .sort();
248
258
  if (unknown.length)
249
- throw new RunbookError(`${file}: unknown parameters ${pyRepr(unknown)}`);
259
+ throw new RunbookError(`${file}: unknown parameters ${quote(unknown)}`);
250
260
  const filled = {};
251
261
  for (const [key, spec] of Object.entries(declared))
252
262
  filled[key] = key in values ? values[key] : get(spec, "default");
253
263
  const fill = (text) => String(text).replace(PARAM, (_match, param) => {
254
264
  const value = filled[param];
255
265
  if (value === null || value === undefined) {
256
- throw new RunbookError(`${file}: parameter ${pyRepr(param)} has no value. Pass --param ${param}=VALUE`);
266
+ throw new RunbookError(`${file}: parameter ${quote(param)} has no value. Pass --param ${param}=VALUE`);
257
267
  }
258
- return pyStr(value);
268
+ return show(value);
259
269
  });
260
270
  const steps = data.steps.map((step, i) => {
261
271
  const number = i + 1;
262
272
  const actor = get(step, "actor", "jev");
263
273
  if (!ACTORS.has(actor))
264
- throw new RunbookError(`${file}: step ${number} has unknown actor ${pyRepr(actor)}`);
265
- if (!pyTruthy(step.instruction))
274
+ throw new RunbookError(`${file}: step ${number} has unknown actor ${quote(actor)}`);
275
+ if (blank(step.instruction))
266
276
  throw new RunbookError(`${file}: step ${number} has no instruction`);
267
277
  return {
268
278
  actor,
269
279
  instruction: fill(step.instruction),
270
280
  hints: get(step, "hints", []).map(fill),
271
- done_when: pyTruthy(step.done_when) ? fill(step.done_when) : null,
281
+ done_when: blank(step.done_when) ? null : fill(step.done_when),
272
282
  };
273
283
  });
274
284
  return {
package/dist/session.js CHANGED
@@ -14,7 +14,7 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSy
14
14
  import { tmpdir } from "node:os";
15
15
  import { delimiter, join } from "node:path";
16
16
  import { chromium } from "playwright-core";
17
- import { pyRepr, sleep } from "./py.js";
17
+ import { quote, sleep } from "./format.js";
18
18
  import * as workspace from "./workspace.js";
19
19
  const STARTUP_MS = 15_000;
20
20
  const PROFILE_NAME = /^[\p{L}\p{N}_-]+$/u;
@@ -53,7 +53,7 @@ export function parseSession(spec) {
53
53
  const kind = at < 0 ? spec : spec.slice(0, at);
54
54
  const name = at < 0 ? "" : spec.slice(at + 1);
55
55
  if (kind !== "profile" || !PROFILE_NAME.test(name)) {
56
- throw new SessionError(`Expected --session new or profile:NAME, got ${pyRepr(spec)}`);
56
+ throw new SessionError(`Expected --session new or profile:NAME, got ${quote(spec)}`);
57
57
  }
58
58
  return name;
59
59
  }
@@ -106,7 +106,7 @@ function windowsLocalAppData() {
106
106
  /** Returns ['linux' or 'windows', a note for the person when auto fell back]. */
107
107
  export function chooseChrome(choice) {
108
108
  if (!CHROMES.includes(choice))
109
- throw new SessionError(`Unknown --chrome ${pyRepr(choice)}`);
109
+ throw new SessionError(`Unknown --chrome ${quote(choice)}`);
110
110
  if (choice === "linux")
111
111
  return ["linux", null];
112
112
  let reason = null;
@@ -132,7 +132,7 @@ function profilesRoot(chrome) {
132
132
  }
133
133
  export function profileDir(chrome, name) {
134
134
  if (!PROFILE_NAME.test(name))
135
- throw new SessionError(`Invalid profile name: ${pyRepr(name)}`);
135
+ throw new SessionError(`Invalid profile name: ${quote(name)}`);
136
136
  return join(profilesRoot(chrome), name);
137
137
  }
138
138
  export function listProfiles(chrome) {
@@ -254,7 +254,7 @@ export async function startChrome(options = {}) {
254
254
  }
255
255
  await stopChrome(state);
256
256
  if (profile && childExited(pid)) {
257
- throw new SessionError(`Chrome exited at once. Is profile ${pyRepr(profile)} open in another Chrome window?`);
257
+ throw new SessionError(`Chrome exited at once. Is profile ${quote(profile)} open in another Chrome window?`);
258
258
  }
259
259
  throw new SessionError("Chrome did not open a reachable debugging port");
260
260
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webhand",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Claude plans, asks, checks, and replans; Jev operates the browser toward the goal.",
5
5
  "license": "MIT",
6
6
  "author": "sakamoto66",
@@ -25,22 +25,25 @@
25
25
  "assets",
26
26
  "LICENSE",
27
27
  "THIRD_PARTY_LICENSE_jev-ultrafast.txt",
28
- "README.md"
28
+ "README.md",
29
+ "README.ja.md"
29
30
  ],
30
31
  "engines": {
31
32
  "node": ">=22"
32
33
  },
33
34
  "scripts": {
34
- "build": "tsc -p tsconfig.build.json",
35
+ "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
35
36
  "lint": "biome check .",
36
37
  "typecheck": "tsc --noEmit",
37
38
  "knip": "knip",
38
39
  "check": "npm run lint && npm run typecheck && npm run knip",
40
+ "check:package": "node scripts/check-package.ts",
39
41
  "test": "vitest run",
40
42
  "test:coverage": "vitest run --coverage",
41
- "smoke": "node src/run.ts",
43
+ "test:golden:update": "UPDATE_GOLDEN=1 vitest run tests/golden.test.ts",
44
+ "smoke": "node research/smoke.ts",
42
45
  "prepare": "husky",
43
- "prepublishOnly": "npm run check && npm run build"
46
+ "prepublishOnly": "npm run check && npm run build && npm run check:package"
44
47
  },
45
48
  "dependencies": {
46
49
  "playwright-core": "~1.64.1",
@@ -49,7 +52,7 @@
49
52
  },
50
53
  "devDependencies": {
51
54
  "@biomejs/biome": "^2.6.4",
52
- "@types/node": "^24.19.2",
55
+ "@types/node": "^26.6.6",
53
56
  "@vitest/coverage-v8": "^5.1.0",
54
57
  "husky": "^9.1.7",
55
58
  "knip": "^6.44.1",
package/dist/py.js DELETED
@@ -1,141 +0,0 @@
1
- /**
2
- * Python-compatible formatting. What the CLI prints is measured (handoff chars) and read by Claude,
3
- * so it stays exactly as the Python implementation printed it.
4
- */
5
- // Python's str.isprintable() is false for these: other (Cc, Cf, Cs, Co, Cn) and separators except the space.
6
- const NOT_PRINTABLE = /[\p{C}\p{Z}]/u;
7
- function escapeChar(char, quote) {
8
- if (char === "\\")
9
- return "\\\\";
10
- if (char === quote)
11
- return `\\${quote}`;
12
- if (char === "\n")
13
- return "\\n";
14
- if (char === "\r")
15
- return "\\r";
16
- if (char === "\t")
17
- return "\\t";
18
- if (char !== " " && NOT_PRINTABLE.test(char)) {
19
- const code = char.codePointAt(0) ?? 0;
20
- if (code < 0x100)
21
- return `\\x${code.toString(16).padStart(2, "0")}`;
22
- if (code < 0x10000)
23
- return `\\u${code.toString(16).padStart(4, "0")}`;
24
- return `\\U${code.toString(16).padStart(8, "0")}`;
25
- }
26
- return char;
27
- }
28
- function reprString(text) {
29
- const quote = text.includes("'") && !text.includes('"') ? '"' : "'";
30
- let body = "";
31
- for (const char of text)
32
- body += escapeChar(char, quote);
33
- return quote + body + quote;
34
- }
35
- function reprNumber(value) {
36
- if (Number.isNaN(value))
37
- return "nan";
38
- if (!Number.isFinite(value))
39
- return value > 0 ? "inf" : "-inf";
40
- return String(value);
41
- }
42
- /** repr() of a JSON-like value. */
43
- export function pyRepr(value) {
44
- if (value === null || value === undefined)
45
- return "None";
46
- if (value === true)
47
- return "True";
48
- if (value === false)
49
- return "False";
50
- if (typeof value === "string")
51
- return reprString(value);
52
- if (typeof value === "number")
53
- return reprNumber(value);
54
- if (Array.isArray(value))
55
- return `[${value.map(pyRepr).join(", ")}]`;
56
- if (value instanceof Map) {
57
- return `{${[...value].map(([k, v]) => `${pyRepr(k)}: ${pyRepr(v)}`).join(", ")}}`;
58
- }
59
- if (typeof value === "object") {
60
- return `{${Object.entries(value)
61
- .map(([k, v]) => `${pyRepr(k)}: ${pyRepr(v)}`)
62
- .join(", ")}}`;
63
- }
64
- return String(value);
65
- }
66
- /** str() of a JSON-like value, as an f-string prints it. */
67
- export function pyStr(value) {
68
- if (typeof value === "string")
69
- return value;
70
- return pyRepr(value);
71
- }
72
- /**
73
- * json.dumps(value, ensure_ascii=False). Maps keep their order, which a plain object would not keep
74
- * for keys like "2" and "1". compact gives the separators httpx uses for a request body.
75
- */
76
- export function pyJson(value, compact = false) {
77
- const comma = compact ? "," : ", ";
78
- const colon = compact ? ":" : ": ";
79
- const encode = (item) => {
80
- if (item === null || item === undefined)
81
- return "null";
82
- if (typeof item === "number")
83
- return Number.isFinite(item) ? JSON.stringify(item) : "null";
84
- if (typeof item === "string" || typeof item === "boolean")
85
- return JSON.stringify(item);
86
- if (Array.isArray(item))
87
- return `[${item.map(encode).join(comma)}]`;
88
- const entries = item instanceof Map ? [...item] : Object.entries(item);
89
- return `{${entries
90
- .filter(([, v]) => v !== undefined)
91
- .map(([k, v]) => `${JSON.stringify(String(k))}${colon}${encode(v)}`)
92
- .join(comma)}}`;
93
- };
94
- return encode(value);
95
- }
96
- /** round() to an int: halves go to the even neighbour. */
97
- export function pyRound(value) {
98
- const floor = Math.floor(value);
99
- const diff = value - floor;
100
- if (diff > 0.5)
101
- return floor + 1;
102
- if (diff < 0.5)
103
- return floor;
104
- return floor % 2 === 0 ? floor : floor + 1;
105
- }
106
- /** Python truthiness: None, False, 0, "", [] and {} are false. */
107
- export function pyTruthy(value) {
108
- if (value === null || value === undefined || value === false || value === 0 || value === "")
109
- return false;
110
- if (Array.isArray(value))
111
- return value.length > 0;
112
- if (value instanceof Map)
113
- return value.size > 0;
114
- if (typeof value === "object")
115
- return Object.keys(value).length > 0;
116
- return true;
117
- }
118
- /** time.strftime("%Y%m%dT%H%M%S") in local time. */
119
- export function stamp(date = new Date()) {
120
- const pad = (n) => String(n).padStart(2, "0");
121
- return (`${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
122
- `T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`);
123
- }
124
- /** datetime.now(timezone.utc).isoformat(). */
125
- export function utcIso(date = new Date()) {
126
- return `${date.toISOString().slice(0, 23)}000+00:00`;
127
- }
128
- /** The length Python reports for a str: code points, not UTF-16 units. */
129
- export function pyLen(text) {
130
- let count = 0;
131
- for (const _ of text)
132
- count++;
133
- return count;
134
- }
135
- /** type(error).__name__: error, as Python formats an exception for a log. */
136
- export function describeError(error) {
137
- if (error instanceof Error)
138
- return `${error.name}: ${error.message}`;
139
- return `Error: ${String(error)}`;
140
- }
141
- export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
package/dist/run.js DELETED
@@ -1,80 +0,0 @@
1
- /** Harness smoke test: the fixed script, no model. Agent runs go through the webhand CLI. */
2
- import { join } from "node:path";
3
- import { parseArgs } from "node:util";
4
- import { Budget, GOAL_REPORTED, runAgent } from "./agent.js";
5
- import { Browser } from "./browser.js";
6
- import { gitState, Recorder, summarize } from "./metrics.js";
7
- import { ScriptedPolicy } from "./policies/scripted.js";
8
- import { describeError, pyStr, stamp, utcIso } from "./py.js";
9
- import { loadTask } from "./tasks.js";
10
- const ROOT = process.cwd();
11
- async function runOnce(taskName, task, repeat, folder, options) {
12
- const recorder = new Recorder(join(folder, `${taskName}-scripted-${repeat}.jsonl`));
13
- let browser = null;
14
- let result = { status: "error", reason: null };
15
- let verdict = { success: false, evidence: null };
16
- try {
17
- const policy = new ScriptedPolicy(task.SCRIPT);
18
- browser = await Browser.open(task.startUrl(ROOT), { headless: !options.headed });
19
- recorder.event("run_start", {
20
- task: taskName,
21
- goal: task.GOAL,
22
- policy: "scripted",
23
- repeat,
24
- config: policy.config(),
25
- chrome: browser.version,
26
- git: gitState(),
27
- started_at: utcIso(),
28
- });
29
- const plan = { goal: task.GOAL, steps: [], values: [] };
30
- const { page: _page, ...outcome } = await runAgent(browser, policy, plan, recorder, new Budget(options.maxActions, options.maxDecisions));
31
- result = { ...outcome, status: outcome.outcome === GOAL_REPORTED ? "done" : "blocked" };
32
- verdict = await task.verify(browser);
33
- }
34
- catch (error) {
35
- // A failed run is data: keep it and move to the next one.
36
- result = { ...result, reason: describeError(error) };
37
- }
38
- finally {
39
- await browser?.close();
40
- }
41
- const summary = summarize(recorder.calls);
42
- recorder.event("run_end", { ...result, verified: verdict.success, evidence: verdict.evidence, ...summary });
43
- recorder.close();
44
- const reason = result.reason || result.detail || null;
45
- console.log(`${taskName}#${repeat}: ${result.status} verified=${pyStr(verdict.success)} reason=${pyStr(reason)}`);
46
- return verdict.success === true;
47
- }
48
- export async function main(argv = process.argv.slice(2)) {
49
- const { values } = parseArgs({
50
- args: argv,
51
- options: {
52
- task: { type: "string" },
53
- repeat: { type: "string", default: "1" },
54
- headed: { type: "boolean", default: false },
55
- "max-actions": { type: "string", default: String(Budget.MAX_ACTIONS) },
56
- "max-decisions": { type: "string", default: String(Budget.MAX_DECISIONS) },
57
- },
58
- });
59
- if (!values.task)
60
- throw new Error("--task is required");
61
- const task = await loadTask(values.task);
62
- const folder = join(ROOT, "runs", stamp());
63
- const options = {
64
- headed: values.headed ?? false,
65
- maxActions: Number(values["max-actions"]),
66
- maxDecisions: Number(values["max-decisions"]),
67
- };
68
- const passed = [];
69
- for (let repeat = 1; repeat <= Number(values.repeat); repeat++) {
70
- passed.push(await runOnce(values.task, task, repeat, folder, options));
71
- }
72
- console.log(`${passed.filter(Boolean).length}/${passed.length} verified. Logs: ${folder}`);
73
- return passed.every(Boolean) ? 0 : 1;
74
- }
75
- if (import.meta.url === `file://${process.argv[1]}`) {
76
- main().then((code) => process.exit(code), (error) => {
77
- console.error(error instanceof Error ? error.message : error);
78
- process.exit(1);
79
- });
80
- }
package/dist/tasks.js DELETED
@@ -1,37 +0,0 @@
1
- /**
2
- * Research tasks: a fixed goal and an independent verify(). They live in the research repository's
3
- * tasks/ folder, are never shipped in the package, and are the only evidence of success in experiments.
4
- */
5
- var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
6
- if (typeof path === "string" && /^\.\.?\//.test(path)) {
7
- return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
8
- return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
9
- });
10
- }
11
- return path;
12
- };
13
- import { existsSync } from "node:fs";
14
- import { join } from "node:path";
15
- import { pathToFileURL } from "node:url";
16
- /** The task cannot be loaded. */
17
- export class TaskError extends Error {
18
- name = "TaskError";
19
- }
20
- export async function loadTask(name, root = process.cwd()) {
21
- if (!/^[\p{L}\p{N}_-]+$/u.test(name))
22
- throw new TaskError(`Unknown task: ${name}`);
23
- const file = join(root, "tasks", `${name}.ts`);
24
- if (!existsSync(file)) {
25
- if (!existsSync(join(root, "tasks"))) {
26
- throw new TaskError(`Unknown task: ${name}. Tasks are for the research repository; run from its root`);
27
- }
28
- throw new TaskError(`Unknown task: ${name}`);
29
- }
30
- try {
31
- return (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
32
- }
33
- catch (error) {
34
- const message = error instanceof Error ? error.message : String(error);
35
- throw new TaskError(`Could not load task ${name} (TypeScript tasks need Node 22.18 or later): ${message}`);
36
- }
37
- }