jevway 0.1.0 → 0.2.0

package/dist/setup/skill-command.js

@@ -0,0 +1,101 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { print, printError, printJson } from './command-output.js';
+export const SKILL_USAGE = `Examples:
+  jevway skill
+  jevway skill --install ~/.claude/skills
+
+jevway skill                      print the SKILL.md this version ships
+jevway skill --install <dir> [--force]   copy the skill folder into <dir>/jevway
+
+Examples:
+  jevway skill --install ~/.claude/skills
+  jevway skill --install ~/.codex/skills
+
+--install prints { ok, status: installed|unchanged|replaced, path, files }. A different jevway skill already in
+<dir>/jevway (or a symlink to one) is left alone unless --force is given.`;
+/** The `skill/jevway/` folder of the installed package: two levels up from both `src/setup/` and `dist/setup/`. */
+export const bundledSkillDir = () => fileURLToPath(new URL('../../skill/jevway/', import.meta.url));
+/** Every file under `dir`, as sorted paths relative to it. */
+const filesIn = (dir) => readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
+    .sort();
+/** True when `target` holds exactly the files of `source`, byte for byte (following a symlinked `target`). */
+const sameFolder = (source, target) => {
+    try {
+        const files = filesIn(source);
+        return (files.join('\n') === filesIn(target).join('\n') &&
+            files.every((file) => readFileSync(join(source, file)).equals(readFileSync(join(target, file)))));
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether `<parent>/jevway` is missing, the same as `source`, or something else (a different skill or a symlink to one). */
+export const skillState = (source, parent) => {
+    const path = join(parent, 'jevway');
+    if (!existsSync(path) && !lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
+        return 'missing';
+    return sameFolder(source, path) ? 'same' : 'different';
+};
+/**
+ * Copies `source` to `<parent>/jevway`. An identical copy is left as it is; a different folder or a symlink is
+ * replaced only with `force` (a symlink is removed, never its target). The copy lands under a temporary name first,
+ * so an interrupted install never leaves half a skill.
+ *
+ * @example
+ * installSkill(bundledSkillDir(), '/Users/ada/.claude/skills', { force: false })
+ * // { status: 'installed', path: '/Users/ada/.claude/skills/jevway', files: ['SKILL.md'] }
+ */
+export const installSkill = (source, parent, { force }) => {
+    const path = join(parent, 'jevway');
+    const files = filesIn(source);
+    const state = skillState(source, parent);
+    if (state === 'same')
+        return { status: 'unchanged', path, files };
+    if (state === 'different' && !force)
+        return { status: 'exists', path };
+    const present = state === 'different';
+    mkdirSync(parent, { recursive: true });
+    const incoming = join(parent, `.jevway-${process.pid}.incoming`);
+    cpSync(source, incoming, { recursive: true });
+    if (present)
+        rmSync(path, { recursive: true, force: true });
+    renameSync(incoming, path);
+    return { status: present ? 'replaced' : 'installed', path, files };
+};
+/**
+ * `jevway skill`: prints the bundled SKILL.md, or with `--install <dir>` copies the skill folder into `<dir>/jevway`.
+ *
+ * @example
+ * process.exit(await runSkill(process.argv.slice(3)));
+ */
+export const runSkill = async (argv) => {
+    let options;
+    try {
+        ({ values: options } = parseArgs({
+            args: argv,
+            options: { install: { type: 'string' }, force: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+        }));
+    }
+    catch (error) {
+        return printError(2, 'usage', `jevway skill: ${error.message}`, 'jevway skill --install <dir> [--force]');
+    }
+    if (options.help) {
+        await print(`${SKILL_USAGE}\n`);
+        return 0;
+    }
+    if (options.install === undefined) {
+        await print(readFileSync(join(bundledSkillDir(), 'SKILL.md'), 'utf8'));
+        return 0;
+    }
+    const result = installSkill(bundledSkillDir(), options.install, { force: Boolean(options.force) });
+    if (result.status === 'exists') {
+        return printError(1, 'skill_exists', `${result.path} already holds a different jevway skill (or a link to one); it was left as it is`, `Run again with --force to replace it with this version's skill: jevway skill --install ${options.install} --force`);
+    }
+    await printJson({ ok: true, ...result });
+    return 0;
+};

package/dist/setup/terminal-prompter.js

@@ -0,0 +1,51 @@
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+/**
+ * The real terminal for setup. Hidden answers are read through readline with its echo sent to a muted stream, and
+ * readline keeps no history, so a key is never drawn on screen nor kept after the question. Ctrl-C (or Ctrl-D) exits
+ * 130 at once: setup writes every file whole, so nothing is left half-written.
+ */
+export const terminalPrompter = () => {
+    let muted = false;
+    let closing = false;
+    const echo = new Writable({
+        write(chunk, encoding, done) {
+            if (!muted)
+                process.stdout.write(chunk, encoding);
+            done();
+        },
+    });
+    Object.defineProperty(echo, 'columns', { get: () => process.stdout.columns });
+    const rl = createInterface({ input: process.stdin, output: echo, terminal: true, historySize: 0 });
+    const stop = () => {
+        if (closing)
+            return;
+        muted = false;
+        process.stdout.write('\nStopped. Every file is as it was before, or written whole.\n');
+        process.exit(130);
+    };
+    rl.on('SIGINT', stop);
+    rl.on('close', stop);
+    const io = {
+        say: (text) => void process.stdout.write(`${text}\n`),
+        ask: (question) => rl.question(question),
+        askHidden: async (question) => {
+            process.stdout.write(question);
+            muted = true;
+            try {
+                return await rl.question('');
+            }
+            finally {
+                muted = false;
+                process.stdout.write('\n');
+            }
+        },
+    };
+    return {
+        io,
+        close: () => {
+            closing = true;
+            rl.close();
+        },
+    };
+};

package/dist/setup/unified-diff.js

@@ -0,0 +1,69 @@
+const CONTEXT = 3;
+const linesOf = (text) => (text === '' ? [] : text.replace(/\n$/, '').split('\n'));
+// Longest common subsequence, table-driven (config files are small enough for O(n·m)); removals print before additions.
+const lineOps = (before, after) => {
+    const common = Array.from({ length: before.length + 1 }, () => new Array(after.length + 1).fill(0));
+    for (let i = before.length - 1; i >= 0; i--) {
+        for (let j = after.length - 1; j >= 0; j--) {
+            common[i][j] = before[i] === after[j] ? common[i + 1][j + 1] + 1 : Math.max(common[i + 1][j], common[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < before.length || j < after.length) {
+        if (i < before.length && j < after.length && before[i] === after[j]) {
+            ops.push({ op: ' ', text: before[i++] });
+            j++;
+        }
+        else if (i < before.length && (j === after.length || common[i + 1][j] >= common[i][j + 1])) {
+            ops.push({ op: '-', text: before[i++] });
+        }
+        else {
+            ops.push({ op: '+', text: after[j++] });
+        }
+    }
+    return ops;
+};
+// Index ranges of `ops` to show: every change plus its context, merging ranges that touch.
+const hunkRanges = (ops) => {
+    const ranges = [];
+    ops.forEach(({ op }, index) => {
+        if (op === ' ')
+            return;
+        const start = Math.max(0, index - CONTEXT);
+        const end = Math.min(ops.length, index + CONTEXT + 1);
+        const last = ranges.at(-1);
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            ranges.push([start, end]);
+    });
+    return ranges;
+};
+// As diff -u: an empty side starts at the line before the hunk, and a count of 1 is left out.
+const side = (start, count) => (count === 1 ? `${start + 1}` : `${count ? start + 1 : start},${count}`);
+/**
+ * A unified diff of two texts with three lines of context, as `diff -u` prints it; `before` undefined is a new file
+ * (`--- /dev/null`). Empty when nothing changes.
+ *
+ * @example
+ * unifiedDiff('{}\n', '{\n  "a": 1\n}\n', '~/.cursor/mcp.json')
+ * // '--- ~/.cursor/mcp.json\n+++ ~/.cursor/mcp.json\n@@ -1 +1,3 @@ …'
+ */
+export const unifiedDiff = (before, after, path) => {
+    const ops = lineOps(linesOf(before ?? ''), linesOf(after));
+    const ranges = hunkRanges(ops);
+    if (!ranges.length)
+        return '';
+    const hunks = ranges.map(([start, end]) => {
+        const prior = ops.slice(0, start);
+        const shown = ops.slice(start, end);
+        const oldStart = prior.filter(({ op }) => op !== '+').length;
+        const newStart = prior.filter(({ op }) => op !== '-').length;
+        const oldCount = shown.filter(({ op }) => op !== '+').length;
+        const newCount = shown.filter(({ op }) => op !== '-').length;
+        return [`@@ -${side(oldStart, oldCount)} +${side(newStart, newCount)} @@`, ...shown.map(({ op, text }) => `${op}${text}`)];
+    });
+    return [`--- ${before === undefined ? '/dev/null' : path}`, `+++ ${path}`, ...hunks.flat(), ''].join('\n');
+};

package/dist/task/present.js

@@ -0,0 +1,90 @@
+import { describeStep } from '../recording/describe-step.js';
+// What the run appends to a step's element, in parentheses: a tab switch, a dialog, a scroll that moved nothing.
+const NOTE = / \((?=new tab opened: |the tab closed; |nothing moved: |the page then )/;
+const splitNotes = (element) => {
+    const [label, ...notes] = element.split(NOTE);
+    return { label, notes: notes.map((note) => note.replace(/\)$/, '')) };
+};
+const outcomeOf = (note) => {
+    if (note.startsWith('new tab opened: '))
+        return `a ${note}`;
+    if (note.startsWith('nothing moved: '))
+        return 'nothing moved';
+    return note;
+};
+const lowerFirst = (text) => text.charAt(0).toLowerCase() + text.slice(1);
+/**
+ * One step of a summary as a plain past-tense sentence, in the recording page's words, plus what happened when that
+ * was not the plain outcome. Steps are scrubbed before a summary leaves the run, so a secret shows only as its marker.
+ *
+ * @example
+ * storyLine({ operation: 'TYPE_TEXT', element: 'Destination', value_key: 'destination' })
+ * // 'Typed the "destination" value into "Destination".'
+ */
+export const storyLine = (step) => {
+    const { label, notes } = splitNotes(step.element);
+    const [element, option] = step.operation === 'SELECT' && label.includes(' → ') ? label.split(/ → (?=[^→]*$)/) : [label];
+    const intent = { operation: step.operation, element, valueKey: step.value_key, fileKey: step.file_key, option };
+    if (step.not_executed) {
+        return step.operation === 'DONE'
+            ? `Did not finish yet: ${step.not_executed}.`
+            : `Did not ${lowerFirst(describeStep(intent))}: ${step.not_executed}.`;
+    }
+    // The run's own Escapes say what they closed.
+    if (step.operation === 'PRESS_ESCAPE' && element.startsWith('closed '))
+        return `Pressed Escape and ${element}.`;
+    const outcomes = [...notes.map(outcomeOf), ...(step.value_kept === false ? ['the field did not keep the text'] : [])];
+    return `${describeStep(intent, 'done')}${outcomes.length ? `; ${outcomes.join('; ')}` : ''}.`;
+};
+/** A call's steps as one sentence each. */
+export const storyOf = (steps) => steps.map(storyLine);
+/**
+ * The one thing the caller does next after this status, in the tools' parameter names.
+ *
+ * @example
+ * nextFor({ status: 'needs_input', … }) // 'Add the missing values to `values` and call again with this session.'
+ */
+export const nextFor = ({ status, wall }) => {
+    switch (status) {
+        case 'done':
+            return 'Read the result in `page_text` (and `evidence`); end the session when you no longer need its tab.';
+        case 'needs_input':
+            return 'Add the missing values to `values` and call again with this session.';
+        case 'needs_confirmation':
+            return "Ask the user, unless their own request names this action and its target; then call again with this session, `confirm_irreversible: true` and `confirm_target` (the user's words naming the target).";
+        case 'uncertain':
+            return 'Look at the screenshot and `page_text`, then call again with this session and a clearer `goal`, or finish the step yourself.';
+        case 'step_budget':
+            return 'Call again with this session and a narrower `goal`, or a larger `max_steps` / `max_seconds`.';
+        case 'blocked':
+            if (wall?.kind === 'bot_check')
+                return 'Never try to get past it: ask the user to pass it in that tab, then call again with this session.';
+            if (wall?.kind === 'sign_in')
+                return `Sign in at ${wall.origin} (or pass the values the form wants), then call again with this session.`;
+            return 'Read the reason: tell the user, or change `goal` or `values` and call again with this session.';
+    }
+};
+const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, inner]) => inner !== undefined));
+export function presentSummary({ session, summary, files }, { detail = 'concise' } = {}) {
+    // The order both adapters print: how it ended and what to do first, then where, and the long page text last.
+    const { page_text, ...head } = {
+        status: summary.status,
+        reason: summary.reason,
+        story: storyOf(summary.steps),
+        next: nextFor(summary),
+        session,
+        url: summary.url,
+        title: summary.title,
+        missing: summary.missing,
+        wall: summary.wall,
+        checks: summary.checks,
+        evidence: summary.evidence,
+        confirm_ignored: summary.confirm_ignored,
+        files,
+        page_text: summary.page_text,
+    };
+    if (detail === 'concise')
+        return defined({ ...head, page_text });
+    const { steps, jev, stuck, elapsed_ms, done_probability } = summary;
+    return defined({ ...head, steps, jev, stuck, elapsed_ms, done_probability, page_text });
+}

package/dist/task/run-task.js

@@ -9,13 +9,17 @@ import { ANY_HOST, narrowHosts, outsideHosts } from './hosts.js';
 import { scrubberFor } from '../jev/secrets.js';
 import { describeFailure, runChecks } from './checks.js';
 import { deepLink, quoteSpans } from './evidence.js';
-import { Recording } from './recording.js';
+import { writeCall } from '../output/run-folder.js';
+import { Recording } from '../recording/recording.js';
 import { RunStopped, startRunLimit } from './run-limit.js';
 import { checkUploadFiles, fileNames } from './upload-files.js';
+import { isTransientModelError } from '../jev/retry.js';
 // How much of the final page's visible text a summary carries: enough to read a list or a settings section, not a whole page.
 const PAGE_TEXT_CHARS = 2500;
 // An agent must know when the text was cut, to read the rest with another call or chrome-devtools.
 export const pageTextFor = (text) => text.length > PAGE_TEXT_CHARS ? `${text.slice(0, PAGE_TEXT_CHARS)}\n…[${text.length - PAGE_TEXT_CHARS} more characters not shown]` : text;
+// The widest end-page screenshot a run folder keeps, in pixels: enough to read, light enough to inline in a result.
+const END_PAGE_WIDTH = 1280;
 // How much of the page title a needs_confirmation reason quotes.
 const CONFIRM_TITLE_CHARS = 80;
 // How much of a page dialog's text a step or a repeat reason quotes.
@@ -104,7 +108,6 @@ const ESCAPE = { id: 'press_escape', kind: 'escape', label: 'Press Escape to clo
 // Boxes on small targets land a row off (13 px checkboxes); pad before asking whether one covers the chosen control.
 const BOX_PADDING = 16;
 // A model call that fails like this (5xx, 499 "unexpected error", rate limit, network, timeout) is retried once; any other error is final.
-const TRANSIENT_MODEL_ERROR = /^(5\d\d|429|499)\b|timeout|timed out|ECONNRESET|ETIMEDOUT|fetch failed|socket hang up/i;
 // Pause before that one retry, so a rate limit or a restarting upstream has a moment to clear.
 const MODEL_RETRY_MS = 800;
 // Stands in for the page in a summary when the very first observe fails.
@@ -199,15 +202,27 @@ export class BrowserTask {
     #tabs;
     #ask;
     #recording;
+    /** The run folder each call writes to, every call's summary so far, and what the last call left there. */
+    #output;
+    #summaries = [];
+    #lastCall;
+    /** This call's step listener, and how many of the call's steps it was told. */
+    #onStep;
+    #stepsTold = 0;
     /** This call's stop signal (caller cancel or time budget); set while a call runs. */
     #limit;
-    constructor(tab, ask, { recordDir, ...options }) {
+    constructor(tab, ask, { recordDir, output, ...options }) {
         this.#tab = tab;
         this.#tabs = [tab];
         this.#ask = ask;
         this.#options = { ...DEFAULTS, values: {}, secretKeys: [], ...definedOnly(options), files: checkUploadFiles(options.files) };
-        if (recordDir)
-            this.#recording = new Recording(recordDir, (text) => this.#scrub(text));
+        this.#output = output ?? (recordDir ? { dir: recordDir, record: true } : undefined);
+        if (this.#output?.record)
+            this.#recording = new Recording(this.#output.dir, (text) => this.#scrub(text));
+    }
+    /** What the last call left in the run folder, and its end page as JPEG bytes (absent when the capture failed); none without `output`. */
+    get lastCall() {
+        return this.#lastCall;
     }
     /** The model a call's requests went to, and what its input tokens cost at that model's published rate. */
     #costOf(inputTokens) {
@@ -241,6 +256,10 @@ export class BrowserTask {
             })),
         };
     }
+    /** Reads the session's tab with no model call and no input, its secret values already masked: what `jevway_look` shows. */
+    look() {
+        return this.#observe();
+    }
     /** The tab the session is on now: a tab its clicks opened, once followed, or the one it started on. */
     get tab() {
         return this.#tab;
@@ -292,14 +311,17 @@ export class BrowserTask {
     }
     /** Merge new values, a new goal, narrower hosts (a widening list throws), or a one-time confirmation for the next irreversible click. */
     update(patch) {
-        const { confirmIrreversible, confirmTarget, values, secretKeys, files, recordDir: _recordDir, allowedHosts, blockedHosts, ...options } = patch;
+        const { confirmIrreversible, confirmTarget, values, secretKeys, files, recordDir: _recordDir, output: _output, allowedHosts, blockedHosts, ...options } = patch;
         // First, so a list that would widen the hosts throws before anything else changes.
         const hosts = narrowHosts(this.#options.hosts, { allowed: allowedHosts, blocked: blockedHosts });
+        const newGoal = options.goal !== undefined && options.goal !== this.#options.goal;
         // A new goal may be to flip back what the old one flipped.
-        if (options.goal !== undefined && options.goal !== this.#options.goal)
+        if (newGoal)
             this.#toggled.clear();
         this.#options = {
             ...this.#options,
+            // The old goal's done_when may already hold, and would end the new goal before it starts.
+            ...(newGoal && options.doneWhen === undefined && { doneWhen: undefined }),
             ...definedOnly(options),
             hosts,
             values: { ...this.#options.values, ...values },
@@ -320,9 +342,12 @@ export class BrowserTask {
     }
     /**
      * Runs until done or a hand-back. `signal` is the caller's cancel (the MCP request's): the run stops at its next
-     * check, `blocked` "Cancelled by the caller"; an input already under way finishes first.
+     * check, `blocked` "Cancelled by the caller"; an input already under way finishes first. `onStep` hears each step of
+     * this call (numbered from 1) once the run moves past it, with the page's URL then; a listener that throws is ignored.
      */
-    async run({ signal } = {}) {
+    async run({ signal, onStep } = {}) {
+        this.#onStep = onStep;
+        this.#stepsTold = 0;
         // The recording is for people: a browser failure while recording must not change or hang the run's outcome.
         await this.#recording?.start(this.#tab).catch(() => undefined);
         let settled;
@@ -340,9 +365,44 @@ export class BrowserTask {
         for (; this.#traceScrubbed < this.trace.length; this.#traceScrubbed++)
             this.trace[this.#traceScrubbed] = this.#scrub(this.trace[this.#traceScrubbed]);
         const summary = this.#scrub(settled);
-        await this.#recording?.finish(this.#tab, summary).catch(() => undefined);
+        this.#onStep = undefined;
+        await this.#recording?.finish(this.#tab, summary, { goal: this.#options.goal, doneWhen: this.#options.doneWhen }).catch(() => undefined);
+        if (this.#output)
+            await this.#writeCall(this.#output.dir, summary);
         return summary;
     }
+    // What a call leaves in the run folder; like the recording, it never changes or hangs the run's outcome.
+    async #writeCall(dir, summary) {
+        this.#summaries.push(summary);
+        const screenshot = await this.#endPage().catch(() => undefined);
+        try {
+            const files = writeCall({ dir, call: this.#summaries.length, status: summary.status, shot: screenshot, summaries: this.#summaries, recorded: Boolean(this.#recording) });
+            this.#lastCall = { files, ...(screenshot && { screenshot }) };
+        }
+        catch {
+            this.#lastCall = undefined;
+        }
+    }
+    /** The tab's viewport as a light JPEG for agents: quality 70, at most 1280 pixels wide. Pixels: a secret typed into a visible field shows. */
+    async #endPage() {
+        const ratio = Number(await this.#tab.evaluate('devicePixelRatio')) || 1;
+        const width = this.#ending?.page.w || END_PAGE_WIDTH;
+        const scale = Math.min(1, END_PAGE_WIDTH / (width * ratio));
+        return Buffer.from(await this.#tab.screenshot({ format: 'jpeg', quality: 70, scale }), 'base64');
+    }
+    /** Tells the step listener about this call's steps it has not heard yet; the page's URL is the one the run is on now. */
+    #tellSteps(firstStep, url) {
+        if (!this.#onStep)
+            return;
+        for (; firstStep + this.#stepsTold < this.#history.length; this.#stepsTold++) {
+            try {
+                this.#onStep(this.#scrub(this.#history[firstStep + this.#stepsTold]), this.#stepsTold + 1, url);
+            }
+            catch {
+                // A listener is the caller's (progress, a log line): it never decides how the run goes.
+            }
+        }
+    }
     async #loop(signal) {
         // The page's own scripts can read what it is told to look for, so a secret reaches the page only when typed into its field.
         this.#tab.want(Object.entries(this.#options.values).filter(([key]) => !this.#options.secretKeys.includes(key)).map(([, value]) => value), { files: Object.keys(this.#options.files).length > 0 });
@@ -370,6 +430,7 @@ export class BrowserTask {
         const stop = (status, reason, decision, { overridable = false } = {}) => {
             // A dialog that opened late still belongs on the step that caused it.
             this.#reportDialogs(firstStep);
+            this.#tellSteps(firstStep, page.url);
             // A hand-back asks a new question, so a confirmation still pending (a refused one) is spent.
             if (status === 'needs_confirmation')
                 this.#spendConfirmation();
@@ -492,6 +553,7 @@ export class BrowserTask {
                 const switchedLate = await this.#switchTabs();
                 if (switchedLate)
                     page = await this.#afterSwitch(switchedLate, firstStep);
+                this.#tellSteps(firstStep, page.url);
                 // Never a decision on a page outside the hosts: a start page, a redirect or a late navigation that left them ends the run.
                 const outside = outsideHosts(page.url, hosts);
                 if (outside)
@@ -696,6 +758,7 @@ export class BrowserTask {
                         operation: decision.operation,
                         element: action.label,
                         valueKey: decision.valueKey ?? undefined,
+                        fileKey: decision.fileKey ?? undefined,
                         option: action.kind === 'select' ? String(action.value) : undefined,
                         confidence: round(Math.min(decision.confidence, decision.targetConfidence ?? 1)),
                     }, decision.operation === 'CLICK_AT' ? decision.nextClick.rect : action.rect);
@@ -1086,7 +1149,7 @@ export class BrowserTask {
             return await this.#decide(page);
         }
         catch (error) {
-            if (!(error instanceof ModelCallError) || !TRANSIENT_MODEL_ERROR.test(error.message))
+            if (!(error instanceof ModelCallError) || !isTransientModelError(error))
                 throw error;
             await (this.#limit?.pause(MODEL_RETRY_MS) ?? new Promise((resolve) => setTimeout(resolve, MODEL_RETRY_MS)));
             return this.#decide(page);

package/dist/task/start-task.js

@@ -6,6 +6,7 @@ import { JourneySession } from '../journeys/journey-session.js';
 import { missingKeyMessage } from '../setup/env-file.js';
 import { hostsFromEnv, narrowHosts, outsideHosts } from './hosts.js';
 import { BrowserTask } from './run-task.js';
+import { retryingAsk } from '../jev/retry.js';
 /**
  * Connects a browser once and starts tasks on tabs inside it. Tasks and journeys need the chosen model's key:
  * `TYPESAFE_API_KEY` for Jev (default), `OPENROUTER_API_KEY` for Clef-omni. Without it the runner is still made, so an
@@ -39,9 +40,8 @@ export const createRunner = (source, choice = {}) => {
             const decider = ask();
             // The server's lists, narrowed by the call; a start URL outside them is never opened.
             const hosts = narrowHosts(hostsFromEnv(), { allowed: allowedHosts, blocked: blockedHosts });
-            const outside = url ? outsideHosts(url, hosts) : undefined;
-            if (outside)
-                throw new Error(`Not opened: ${outside}`);
+            if (url)
+                refuseOutside(url, hosts);
             const { cdp } = await browser();
             if (!url && !tab)
                 throw new Error('Pass `url` to open a new tab or `tab` to reuse an open one.');
@@ -57,9 +57,11 @@ export const createRunner = (source, choice = {}) => {
         },
         /** Reads a page with no model call and no input: an open tab by URL part, or a URL in a background tab closed again. */
         async look({ url, tab }) {
-            const { cdp } = await browser();
             if (!url && !tab)
                 throw new Error('Pass `url` to open a page or `tab` to read an open one.');
+            if (url)
+                refuseOutside(url, hostsFromEnv());
+            const { cdp } = await browser();
             const page = url ? await Tab.open(cdp, url) : await Tab.find(cdp, tab);
             try {
                 return await page.observe();
@@ -72,11 +74,17 @@ export const createRunner = (source, choice = {}) => {
         /** Mobile journey mapping; in the user's own Chrome it opens a separate window so screenshots keep rendering. */
         async startJourney(options) {
             const decider = ask();
+            // The server's host lists hold for journeys too: a start page outside them is never opened, and a step that
+            // lands outside them is refused before Jev is asked about the page.
+            const hosts = hostsFromEnv();
+            refuseOutside(options.startUrl, hosts);
             const { cdp } = await browser();
-            return JourneySession.start(cdp, decider, {
+            // A journey makes one model call per screen and has no loop-level retry, so a busy API gets two more tries.
+            return JourneySession.start(cdp, retryingAsk(decider, { delaysMs: JOURNEY_RETRY_MS }), {
                 newWindow: source === 'auto',
                 ...profileOptions(profile),
                 ...options,
+                hosts,
                 screenshots: options.screenshots ?? screenshots,
             });
         },
@@ -87,5 +95,13 @@ export const createRunner = (source, choice = {}) => {
         },
     };
 };
+// Waits before each retry of a journey's model call after a busy or flaky API answer.
+const JOURNEY_RETRY_MS = [1000, 3000];
+/** Throws before a page outside the host rules is opened. */
+const refuseOutside = (url, hosts) => {
+    const outside = outsideHosts(url, hosts);
+    if (outside)
+        throw new Error(`Not opened: ${outside}`);
+};
 // Optional MCP/CLI arguments arrive as explicit undefined; they must not erase profile settings.
 const definedOnly = (options) => Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jevway",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Hand a browser goal to TypeSafe Jev; get a short verified summary back. MCP server + CLI.",
   "keywords": [
     "mcp",
@@ -25,7 +25,7 @@
     "url": "git+https://github.com/AbdallahAHO/jevway.git"
   },
   "bin": {
-    "jevway": "dist/cli.js",
+    "jevway": "dist/cli/main.js",
     "jevway-mcp": "dist/mcp.js"
   },
   "files": [
@@ -39,13 +39,17 @@
     "node": ">=24"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && cp src/browser/snapshot.js dist/browser/snapshot.js && chmod +x dist/cli.js dist/mcp.js",
+    "build": "tsc -p tsconfig.build.json && cp src/browser/snapshot.js dist/browser/snapshot.js && chmod +x dist/cli/main.js dist/mcp.js",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "prepublishOnly": "pnpm typecheck && pnpm test && rm -rf dist && pnpm build",
+    "release": "node release/release.ts",
+    "release:status": "node release/release.ts status",
+    "release:check": "node release/release.ts check",
     "verify": "node --env-file-if-exists=.env verify/run.ts",
+    "verify:mcp": "node verify/mcp-consumer.ts",
     "mcp": "node --env-file-if-exists=.env src/mcp.ts",
-    "cli": "node --env-file-if-exists=.env src/cli.ts",
+    "cli": "node --env-file-if-exists=.env src/cli/main.ts",
     "verify:reader": "node verify/reader.ts",
     "verify:journeys": "node --env-file-if-exists=.env verify/journeys.ts",
     "verify:real": "node --env-file-if-exists=.env verify/real-world.ts",
@@ -58,7 +62,7 @@
     "verify:forgejo": "node --env-file-if-exists=.env verify/forgejo.ts",
     "verify:signup": "node --env-file-if-exists=.env verify/signup.ts",
     "verify:vikunja": "node --env-file-if-exists=.env verify/vikunja.ts",
-    "verify:agent": "node verify/agent.ts",
+    "verify:agent": "node verify/agent/agent.ts",
     "verify:replay": "node verify/replay.ts",
     "report:render": "node verify/jobs/rerender.ts",
     "apps:forgejo:up": "docker compose -p jevway-forgejo -f verify/apps/forgejo/compose.yml up -d --wait && node verify/apps/forgejo/seed.ts users",
@@ -67,12 +71,13 @@
     "apps:vikunja:down": "docker compose -p jevway-vikunja -f verify/apps/vikunja/compose.yml down -v"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/server": "^2.4.0",
     "@typesafe-ai/sdk": "^0.7.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^22.20.3",
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@types/node": "^24.19.2",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1"
   }