jevway 0.0.0-stage → 0.1.2

package/dist/browser/words.js

@@ -0,0 +1,51 @@
+// How the words a caller quotes are compared with what a page shows (see `BrowserTask` and `Tab.armConfirm`).
+// The words a confirmation names are compared the way a person would: case, accents and spacing set aside.
+const normalized = (text) => text.normalize('NFKC').toLowerCase().replace(/\s+/g, ' ').trim();
+const AT_THE_ENDS = /^[\s"'“”‘’`()[\]{}.,;:!?]+|[\s"'“”‘’`()[\]{}.,;:!?]+$/gu;
+// Words split on spaces and quotes; `/ . _ -` stay inside, so "ada/scratch" is one word.
+const WORD_BREAKS = /[\s,;:!?()"'“”‘’`]+/u;
+const MIN_WORD_CHARS = 3;
+// Words that join a phrase and name nothing: "the repository named ada/scratch".
+const FILLER_WORDS = new Set(['the', 'and', 'for', 'from', 'with', 'its', 'our', 'your', 'their', 'named', 'called', 'titled']);
+// Where a word may end or begin inside the page's text: next to a letter, a digit, "_" or "-" it is part of a longer word,
+// and so is a "." that goes on with another character ("v1.2" is not in "v1.2.3").
+const LONGER_BEFORE = '(?<![\\p{L}\\p{N}_-])';
+const LONGER_AFTER = '(?![\\p{L}\\p{N}_-]|\\.[\\p{L}\\p{N}])';
+const appearsWhole = (word, text) => new RegExp(`${LONGER_BEFORE}${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}${LONGER_AFTER}`, 'u').test(text);
+const wordsOf = (text) => normalized(text)
+    .split(WORD_BREAKS)
+    .map((word) => word.replace(AT_THE_ENDS, ''))
+    .filter((word) => word.length >= MIN_WORD_CHARS);
+/**
+ * Whether the page shows the user's words for the target. The words of the clicked control and filler words describe
+ * the action, not its target, so they never count; what is left must be there, every word, and at least one must be.
+ * Without that, "delete" would match any page that shows a Delete button. A word counts where the page has it whole:
+ * "app" is not in "apply", nor "ada/scratch" in "ada/scratch-2".
+ *
+ * @example
+ * showsTarget('the repository ada/scratch', 'Delete this repository', ['ada/scratch - Settings']) // true
+ * showsTarget('delete', 'Delete this repository', ['ada/scratch - Settings', 'Delete this repository']) // false
+ * showsTarget('anything unused', 'Delete this repository', ['ada/scratch - Settings']) // false
+ */
+export const showsTarget = (target, control, shown) => {
+    const controlWords = new Set(wordsOf(control));
+    const specific = wordsOf(target).filter((word) => !controlWords.has(word) && !FILLER_WORDS.has(word));
+    const corpus = shown.map(normalized).join('\n');
+    return specific.length > 0 && specific.every((word) => appearsWhole(word, corpus));
+};
+/**
+ * Whether a dialog's message names what the caller confirmed or the control they clicked: every word of either phrase
+ * (3+ characters, not filler) is in it, whole. A dialog about something else, like the draft comments a reload would
+ * discard, names neither.
+ *
+ * @example
+ * messageNames('Delete the draft?', ['the draft', 'Delete draft']) // true
+ * messageNames('Page will be reloaded, but there are draft comments. Continue?', ['Labels', 'Labels']) // false
+ */
+export const messageNames = (message, phrases) => {
+    const text = normalized(message);
+    return phrases.some((phrase) => {
+        const words = wordsOf(phrase).filter((word) => !FILLER_WORDS.has(word));
+        return words.length > 0 && words.every((word) => appearsWhole(word, text));
+    });
+};

package/dist/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { runDoctor } from './setup/doctor-command.js';
+import { loadEnvFile } from './setup/env-file.js';
+import { CHECKS } from './task/checks.js';
+import { createRunner } from './task/start-task.js';
+const USAGE = `jevway --goal "<outcome>" (--url <url> | --tab <url part>) [options]
+jevway doctor [--plan] [--live]   check the setup (key, browser, Node, ffmpeg); --help for more
+
+  --values '{"city":"Lisbon"}'   text values Jev may type
+  --secret-keys token,otp         keys of --values that are secrets: Jev sees the key only, output shows [secret:<key>]
+  --files '{"avatar":"/abs/me.png"}'   files Jev may upload (absolute paths; Jev sees names, never paths)
+  --done-when "<evidence>"        visible evidence of success
+  --checks '[{"type":"url_contains","text":"/issues/"}]'   facts checked by code on the final page
+  --browser auto|launch|launch-headless|http://127.0.0.1:9222   (default: auto, or $JEVWAY_BROWSER)
+  --model jev|pplx-decider|clef-omni|clef|clef-flash|gpt-6-luna   decision model (default: jev, or $JEVWAY_MODEL)
+  --screenshots off|fallback|always   marked screenshots, vision models only (default: per model, or $JEVWAY_SCREENSHOTS)
+  --max-steps 40
+  --allowed-hosts a.com,*.b.com   hosts the run may be on (narrows $JEVWAY_ALLOWED_HOSTS); leaving them ends it blocked
+  --blocked-hosts ads.com         hosts it must never be on (adds to $JEVWAY_BLOCKED_HOSTS)
+  --max-seconds 300               time budget; past it the run ends step_budget (Ctrl-C ends it blocked)
+  --keep-open                     leave the tabs open (auto/remote browsers), including any the run's clicks opened
+  --allow-coordinate-clicks       click a boxed control the DOM never reported (canvas, iframe); Jev 1.14 direct only
+  --record <dir>                  sharp screenshot before every action + final page, summary.json, index.html
+
+Prints one JSON summary. Exit code 0 only when status is "done".
+Needs TYPESAFE_API_KEY (Jev only) or OPENROUTER_API_KEY (every model), from the environment or ~/.config/jevway/env.`;
+// Keys and JEVWAY_* settings the environment lacks come from ~/.config/jevway/env.
+const fromEnvFile = loadEnvFile();
+if (process.argv[2] === 'doctor')
+    process.exit(await runDoctor(process.argv.slice(3), fromEnvFile));
+const { values: args } = parseArgs({
+    options: {
+        goal: { type: 'string' },
+        url: { type: 'string' },
+        tab: { type: 'string' },
+        values: { type: 'string' },
+        'secret-keys': { type: 'string' },
+        files: { type: 'string' },
+        'done-when': { type: 'string' },
+        checks: { type: 'string' },
+        browser: { type: 'string' },
+        model: { type: 'string' },
+        screenshots: { type: 'string' },
+        'max-steps': { type: 'string' },
+        'max-seconds': { type: 'string' },
+        'allowed-hosts': { type: 'string' },
+        'blocked-hosts': { type: 'string' },
+        'keep-open': { type: 'boolean' },
+        'allow-coordinate-clicks': { type: 'boolean' },
+        record: { type: 'string' },
+        help: { type: 'boolean', short: 'h' },
+    },
+});
+if (args.help || !args.goal || !(args.url || args.tab)) {
+    console.error(USAGE);
+    process.exit(args.help ? 0 : 2);
+}
+// Malformed checks, like model or key problems, are usage errors: report them before any browser starts.
+let checks;
+try {
+    checks = args.checks ? CHECKS.parse(JSON.parse(args.checks)) : undefined;
+}
+catch (error) {
+    console.error(`jevway: --checks: ${error.message}`);
+    process.exit(2);
+}
+let runner;
+try {
+    runner = createRunner(args.browser ?? process.env.JEVWAY_BROWSER ?? 'auto', {
+        model: args.model,
+        screenshots: args.screenshots,
+    });
+    runner.requireKey();
+}
+catch (error) {
+    console.error(`jevway: ${error.message}`);
+    process.exit(2);
+}
+try {
+    const task = await runner.start({
+        goal: args.goal,
+        url: args.url,
+        tab: args.tab,
+        values: args.values ? JSON.parse(args.values) : undefined,
+        secretKeys: args['secret-keys']?.split(',').map((key) => key.trim()).filter(Boolean),
+        files: args.files ? JSON.parse(args.files) : undefined,
+        doneWhen: args['done-when'],
+        checks,
+        maxSteps: args['max-steps'] ? Number(args['max-steps']) : undefined,
+        maxSeconds: args['max-seconds'] ? Number(args['max-seconds']) : undefined,
+        allowedHosts: args['allowed-hosts']?.split(','),
+        blockedHosts: args['blocked-hosts']?.split(','),
+        allowCoordinateClicks: args['allow-coordinate-clicks'],
+        recordDir: args.record,
+    });
+    // Ctrl-C stops the run at its next check (an action under way finishes), so the summary still prints and the tab closes.
+    const cancel = new AbortController();
+    process.once('SIGINT', () => cancel.abort());
+    const summary = await task.run({ signal: cancel.signal });
+    if (!args['keep-open'])
+        await task.closeTabs({ keepFirst: !args.url });
+    console.log(JSON.stringify(summary, null, 2));
+    process.exitCode = summary.status === 'done' ? 0 : 1;
+}
+catch (error) {
+    console.error(`jevway: ${error.message}`);
+    process.exitCode = 1;
+}
+finally {
+    await runner.close();
+}

package/dist/jev/action-space.js

@@ -0,0 +1,48 @@
+const OPERATION_BY_KIND = { click: 'CLICK', fill: 'TYPE_TEXT', select: 'SELECT', upload: 'UPLOAD' };
+/**
+ * Turns a snapshot's flat action list into Jev's dynamic action space:
+ * one index per element, and a separate valid-target set per operation.
+ *
+ * @example
+ * const { elements, targets } = buildActionSpace(page.actions);
+ * targets.TYPE_TEXT?.['3'] // the fill action for element [3]
+ */
+export const buildActionSpace = (actions) => {
+    const elements = [];
+    const indexByNode = new Map();
+    const targets = {};
+    const controls = {};
+    const marks = [];
+    for (const action of actions) {
+        if (!(action.kind in OPERATION_BY_KIND)) {
+            controls[action.id.toUpperCase()] = action;
+            continue;
+        }
+        const operation = OPERATION_BY_KIND[action.kind];
+        let index = indexByNode.get(action.node);
+        if (!index) {
+            index = String(elements.length + 1);
+            indexByNode.set(action.node, index);
+            elements.push({
+                index,
+                label: action.label.split(' → ')[0],
+                operations: [],
+                ...pick(action, ['role', 'value', 'checked', 'selected', 'expanded']),
+                ...(action.kind === 'select' && { value: action.current_value ?? '', options: [] }),
+            });
+            if (action.rect)
+                marks.push({ label: index, node: action.node, rect: action.rect });
+        }
+        const element = elements[Number(index) - 1];
+        if (!element.operations.includes(operation))
+            element.operations.push(operation);
+        let target = index;
+        if (action.kind === 'select') {
+            target = `${index}:${element.options.length + 1}`;
+            element.options.push({ index: target, label: action.label, value: action.value });
+        }
+        (targets[operation] ??= {})[target] = action;
+    }
+    return { elements, targets, controls, marks };
+};
+export const pick = (source, keys) => Object.fromEntries(keys.filter((key) => source[key] !== undefined).map((key) => [key, source[key]]));

package/dist/jev/box.js

@@ -0,0 +1,58 @@
+export const centerOf = (rect) => ({ x: rect.x + rect.w / 2, y: rect.y + rect.h / 2 });
+/**
+ * Where a Box answer sits in the viewport. The screenshot is exactly the viewport, so fractions map
+ * straight to CSS pixels.
+ *
+ * @example
+ * toViewportRect({ top: 0.7, bottom: 0.75, left: 0.1, right: 0.9 }, { w: 400, h: 800 }) // { x: 40, y: 560, w: 320, h: 40 }
+ */
+export const toViewportRect = (box, viewport) => ({
+    x: box.left * viewport.w,
+    y: box.top * viewport.h,
+    w: (box.right - box.left) * viewport.w,
+    h: (box.bottom - box.top) * viewport.h,
+});
+/** Intersection over union, 0 (apart) to 1 (identical). */
+export const overlap = (a, b) => {
+    const w = Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x));
+    const h = Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+    const shared = w * h;
+    const union = a.w * a.h + b.w * b.h - shared;
+    return union > 0 ? shared / union : 0;
+};
+// Below this a box and an element are different things; at or above it, the box points at the element.
+export const MATCH_OVERLAP = 0.3;
+export const contains = (rect, point) => point.x >= rect.x && point.x <= rect.x + rect.w && point.y >= rect.y && point.y <= rect.y + rect.h;
+// Boxes often hug a whole row around a narrower button: each centre inside the other also counts.
+const pointsAt = (box, element) => overlap(box, element) >= MATCH_OVERLAP || (contains(box, centerOf(element)) && contains(element, centerOf(box)));
+/**
+ * The observed target a box points at: the best-overlapping one that counts as a match.
+ * This is how a Box answer turns back into an observed id instead of a coordinate.
+ *
+ * @example
+ * matchTarget(boxRect, { '2': acceptButton, '5': searchBar }) // { index: '2', overlap: 0.81 }
+ */
+export const matchTarget = (rect, targets) => {
+    let best = { index: undefined, overlap: -1 };
+    let closest = 0;
+    for (const [index, action] of Object.entries(targets)) {
+        if (!action.rect)
+            continue;
+        const score = overlap(rect, action.rect);
+        closest = Math.max(closest, score);
+        if (pointsAt(rect, action.rect) && score > best.overlap)
+            best = { index, overlap: score };
+    }
+    return best.index ? best : { index: undefined, overlap: closest };
+};
+/** A malformed or inverted box reads as no box at all. */
+export const readBox = (answer) => {
+    const edges = answer?.box;
+    const valid = edges &&
+        ['top', 'bottom', 'left', 'right'].every((k) => typeof edges[k] === 'number' && edges[k] >= 0 && edges[k] <= 1) &&
+        edges.left < edges.right &&
+        edges.top < edges.bottom;
+    if (!valid)
+        return undefined;
+    return { edges, confidence: typeof answer.confidence === 'number' ? answer.confidence : 0 };
+};