jevway 0.1.0 → 0.2.0

package/dist/daemon/server.js

@@ -0,0 +1,320 @@
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { dirname, join } from 'node:path';
+import { ensureOutRoot } from '../output/layout.js';
+import { createSessionService, UnknownSession } from '../session/session-service.js';
+import { presentSummary } from '../task/present.js';
+import { readLines, sendLine } from './protocol.js';
+/** Another daemon already answers on the socket. */
+export class DaemonRunning extends Error {
+    code = 'daemon_running';
+}
+const STOP_WAIT_MS = 10_000;
+// 3600000 → '1 h', 1800000 → '30 min'.
+const idleWords = (ms) => (ms % 3_600_000 === 0 ? `${ms / 3_600_000} h` : `${Math.round(ms / 60_000)} min`);
+const listen = (server, path) => new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(path, () => {
+        server.off('error', reject);
+        resolve();
+    });
+});
+const answers = (path) => new Promise((resolve) => {
+    const probe = createConnection(path);
+    probe.once('connect', () => {
+        probe.destroy();
+        resolve(true);
+    });
+    probe.once('error', () => resolve(false));
+});
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref());
+const errorBody = (error) => {
+    if (error instanceof UnknownSession) {
+        return { code: 'unknown_session', message: error.message, hint: 'List the open ones with jevway sessions, or start one with jevway run --session new --url <url> --goal <goal>' };
+    }
+    return { code: 'failed', message: error instanceof Error ? error.message : String(error), hint: 'The message says what failed; jevway doctor checks the key and the browser.' };
+};
+/**
+ * Serves the session service over a local socket until stopped or idle: one runner per browser/model choice, one
+ * service per output root, sessions found by id in whichever service holds them, and `sessions.json` kept in each
+ * output root. A socket file nothing answers on is replaced; one another daemon answers on is `DaemonRunning`.
+ *
+ * @example
+ * const daemon = await startDaemon({ socket, version, fingerprint, idleMs: 3_600_000, runnerFor, log });
+ * await daemon.closed;
+ */
+export const startDaemon = async ({ socket, version, fingerprint, idleMs, runnerFor, log }) => {
+    const runners = new Map();
+    const services = new Map();
+    const connections = new Set();
+    const controllers = new Set();
+    const pending = new Set();
+    const busy = new Map();
+    const startedAt = new Date();
+    let lastActivity = Date.now();
+    let stopping;
+    let markClosed;
+    const closed = new Promise((resolve) => (markClosed = resolve));
+    const lifetime = `Sessions end when the daemon stops${idleMs ? ` or after ${idleWords(idleMs)} idle` : ''}`;
+    const unknown = (id, kind) => new UnknownSession(kind === 'session'
+        ? `Unknown session "${id}". ${lifetime}; start a new one with --session new and --url (or --tab).`
+        : `Unknown journey "${id}". Journeys end when finished, or as sessions do: ${lifetime.toLowerCase()}; start a new one with jevway journey start --url <url>.`);
+    const allSessions = () => [...services.values()].flatMap(({ service }) => service.listSessions());
+    const holderOf = (id, kind) => {
+        for (const holder of services.values())
+            if (holder.service.listSessions().some(({ session }) => session === id))
+                return holder;
+        throw unknown(id, kind);
+    };
+    const serviceFor = (choice, place) => {
+        const runnerKey = JSON.stringify([choice.browser, choice.model ?? null, choice.screenshots ?? null]);
+        let runner = runners.get(runnerKey);
+        if (!runner)
+            runners.set(runnerKey, (runner = runnerFor(choice)));
+        const key = JSON.stringify([runnerKey, place.outDir, place.journeysDir ?? null]);
+        let holder = services.get(key);
+        if (!holder) {
+            const env = place.journeysDir ? { JEVWAY_JOURNEYS_DIR: place.journeysDir } : {};
+            holder = { service: createSessionService(runner, { outDir: place.outDir, cwd: place.cwd, env, idleMs: idleMs || undefined }), outDir: place.outDir };
+            services.set(key, holder);
+        }
+        return holder;
+    };
+    /** Rewrites `<root>/sessions.json` in every output root this daemon writes to. */
+    const writeSessionFiles = () => {
+        const byRoot = new Map();
+        for (const { service, outDir } of services.values())
+            byRoot.set(outDir, [...(byRoot.get(outDir) ?? []), ...service.listSessions()]);
+        for (const [root, sessions] of byRoot) {
+            try {
+                ensureOutRoot(root);
+                sessions.sort((a, b) => a.started_at.localeCompare(b.started_at));
+                writeFileSync(join(root, 'sessions.json'), `${JSON.stringify({ updated_at: new Date().toISOString(), sessions }, null, 1)}\n`);
+            }
+            catch {
+                // A folder that can't be written never fails a call.
+            }
+        }
+    };
+    const endOne = ({ service }, { session, kind }, keepTab = false) => kind === 'journey' ? service.journeyFinish(session, { keepTab }) : service.end(session, { keepTab });
+    const hello = () => ({
+        version,
+        fingerprint,
+        pid: process.pid,
+        sessions: allSessions().length,
+        idle_timeout_s: idleMs ? idleMs / 1000 : null,
+        started_at: startedAt.toISOString(),
+    });
+    const withoutPreview = ({ journey, report }) => ({ journey, ...report });
+    const handlers = {
+        hello: () => hello(),
+        async task({ request, detail, runner, place }, { signal, emit, track }) {
+            const { service } = request.session ? holderOf(request.session, 'session') : serviceFor(runner, place);
+            const result = await service.task(request, {
+                signal,
+                onEvent: (event) => {
+                    if (event.type === 'started') {
+                        track(event.session);
+                        writeSessionFiles();
+                    }
+                    emit(event);
+                },
+            });
+            writeSessionFiles();
+            return presentSummary(result, { detail });
+        },
+        async look({ session }) {
+            return { session, ...(await holderOf(session, 'session').service.look({ session })) };
+        },
+        async end({ session, keepTab }) {
+            const holder = holderOf(session, 'session');
+            const info = holder.service.listSessions().find((entry) => entry.session === session);
+            const ended = await endOne(holder, info, keepTab);
+            writeSessionFiles();
+            return info.kind === 'journey' ? { journey: session, ...ended } : ended;
+        },
+        sessions: () => ({ daemon: hello(), sessions: allSessions().sort((a, b) => a.started_at.localeCompare(b.started_at)) }),
+        async 'journey.start'({ request, runner, place }) {
+            const reply = await serviceFor(runner, place).service.journeyStart(request);
+            writeSessionFiles();
+            return withoutPreview(reply);
+        },
+        async 'journey.step'({ journey, input }) {
+            return withoutPreview(await holderOf(journey, 'journey').service.journeyStep(journey, input));
+        },
+        async 'journey.autopilot'({ journey, input }) {
+            return withoutPreview(await holderOf(journey, 'journey').service.journeyAutopilot(journey, input));
+        },
+        'journey.annotate'({ journey, screen, notes, relabel }) {
+            holderOf(journey, 'journey').service.journeyAnnotate(journey, screen, notes, relabel);
+            return { journey, screen, annotated: true };
+        },
+        async 'journey.finish'({ journey, keepTab }) {
+            const summary = await holderOf(journey, 'journey').service.journeyFinish(journey, { keepTab });
+            writeSessionFiles();
+            return { journey, ...summary };
+        },
+    };
+    // Ending (not destroying) lets the last replies reach their clients first.
+    const finish = () => {
+        for (const connection of connections) {
+            connection.end();
+            setTimeout(() => connection.destroy(), 1_000).unref();
+        }
+        markClosed();
+    };
+    const shutdown = (reason) => (stopping ??= (async () => {
+        clearInterval(timer);
+        server.close();
+        for (const controller of controllers)
+            controller.abort();
+        await Promise.race([Promise.allSettled([...pending]), delay(STOP_WAIT_MS)]);
+        let ended = 0;
+        for (const holder of services.values()) {
+            for (const info of holder.service.listSessions()) {
+                try {
+                    await endOne(holder, info);
+                    ended++;
+                }
+                catch {
+                    // A tab that is already gone is ended all the same.
+                }
+            }
+        }
+        for (const runner of runners.values())
+            await runner.close().catch(() => undefined);
+        writeSessionFiles();
+        log({ event: 'stopped', reason, ended });
+        return ended;
+    })());
+    const handle = async (socket, mine, { id, method, params = {} }) => {
+        if (method === 'stop') {
+            const ended = await shutdown('stop');
+            sendLine(socket, { id, result: { stopped: true, ended } });
+            finish();
+            return;
+        }
+        if (stopping) {
+            sendLine(socket, { id, error: { code: 'daemon_unavailable', message: 'The daemon is stopping.', hint: 'Run the command again: it starts a new daemon.' } });
+            return;
+        }
+        const handler = handlers[method];
+        if (!handler) {
+            sendLine(socket, { id, error: { code: 'unknown_method', message: `Unknown method "${method}"`, hint: 'The daemon and this jevway may differ in version: run jevway stop.' } });
+            return;
+        }
+        const controller = new AbortController();
+        mine.set(id, controller);
+        controllers.add(controller);
+        const tracked = [];
+        const track = (session) => {
+            tracked.push(session);
+            busy.set(session, (busy.get(session) ?? 0) + 1);
+        };
+        for (const session of [params.session, params.journey, params.request?.session])
+            if (typeof session === 'string')
+                track(session);
+        const began = Date.now();
+        lastActivity = began;
+        let failed;
+        const work = (async () => {
+            try {
+                const result = await handler(params, { signal: controller.signal, emit: (event) => sendLine(socket, { id, event }), track });
+                sendLine(socket, { id, result });
+            }
+            catch (error) {
+                const body = errorBody(error);
+                failed = body.code;
+                sendLine(socket, { id, error: body });
+            }
+        })();
+        pending.add(work);
+        await work;
+        pending.delete(work);
+        mine.delete(id);
+        controllers.delete(controller);
+        for (const session of tracked) {
+            const left = (busy.get(session) ?? 1) - 1;
+            if (left > 0)
+                busy.set(session, left);
+            else
+                busy.delete(session);
+        }
+        lastActivity = Date.now();
+        log({ event: 'request', method, id, ...(tracked[0] && { session: tracked[0] }), ms: lastActivity - began, ...(failed && { error: failed }) });
+    };
+    const onConnection = (socket) => {
+        connections.add(socket);
+        const mine = new Map();
+        readLines(socket, (message) => {
+            if (typeof message?.cancel === 'number')
+                mine.get(message.cancel)?.abort();
+            else if (typeof message?.id === 'number' && typeof message?.method === 'string')
+                void handle(socket, mine, message);
+        });
+        // A client that goes away cancels its running calls, as a cancelled MCP request does.
+        socket.on('close', () => {
+            connections.delete(socket);
+            for (const controller of mine.values())
+                controller.abort();
+        });
+        socket.on('error', () => undefined);
+    };
+    let sweeping = false;
+    const sweep = async () => {
+        if (sweeping || stopping)
+            return;
+        sweeping = true;
+        try {
+            const cutoff = Date.now() - idleMs;
+            let changed = false;
+            for (const holder of services.values()) {
+                for (const info of holder.service.listSessions()) {
+                    if (info.running || busy.has(info.session) || Date.parse(info.last_used_at) > cutoff)
+                        continue;
+                    await endOne(holder, info).catch(() => undefined);
+                    changed = true;
+                    log({ event: 'idle_end', session: info.session, kind: info.kind });
+                }
+            }
+            if (changed)
+                writeSessionFiles();
+            if (!allSessions().length && !pending.size && lastActivity <= cutoff) {
+                await shutdown('idle');
+                finish();
+            }
+        }
+        finally {
+            sweeping = false;
+        }
+    };
+    if (process.platform !== 'win32')
+        mkdirSync(dirname(socket), { recursive: true, mode: 0o700 });
+    let server = createServer(onConnection);
+    try {
+        await listen(server, socket);
+    }
+    catch (error) {
+        if (error.code !== 'EADDRINUSE')
+            throw error;
+        if (await answers(socket))
+            throw new DaemonRunning(`A jevway daemon already answers on ${socket}`);
+        // A socket file left by a daemon that died: nothing answers on it.
+        rmSync(socket, { force: true });
+        server = createServer(onConnection);
+        await listen(server, socket);
+    }
+    if (process.platform !== 'win32')
+        chmodSync(socket, 0o600);
+    const timer = idleMs > 0 ? setInterval(() => void sweep(), Math.min(Math.max(idleMs / 4, 25), 60_000)) : undefined;
+    timer?.unref();
+    log({ event: 'started', pid: process.pid, version, socket, idle_timeout_s: idleMs ? idleMs / 1000 : null });
+    return {
+        socket,
+        closed,
+        async stop() {
+            await shutdown('stopped');
+            finish();
+        },
+    };
+};

package/dist/jev/replay.js

@@ -15,7 +15,6 @@ export class ReplayMiss extends Error {
         this.pageDiff = pageDiff;
     }
 }
-const DEFAULT_DIR = 'verify/out/replay/default';
 const IMAGE = '<image>';
 const LOCAL_ORIGIN = /\b(127\.0\.0\.1|localhost):\d+/g;
 /**
@@ -33,8 +32,13 @@ export const replayMode = () => {
         throw new Error(`JEVWAY_REPLAY must be record or replay, got "${mode}".`);
     return mode;
 };
-/** The recording folder: `JEVWAY_REPLAY_DIR`, or `verify/out/replay/default` under the working directory. */
-export const replayDir = () => resolve(process.env.JEVWAY_REPLAY_DIR?.trim() || DEFAULT_DIR);
+/** The recording folder, `JEVWAY_REPLAY_DIR`: required whenever `JEVWAY_REPLAY` is set, so no run writes into a guessed folder. */
+export const replayDir = () => {
+    const dir = process.env.JEVWAY_REPLAY_DIR?.trim();
+    if (!dir)
+        throw new Error('JEVWAY_REPLAY needs JEVWAY_REPLAY_DIR: the folder that holds the recordings.');
+    return resolve(dir);
+};
 const isPlainObject = (value) => typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;
 /**
  * The request as it is matched: keys sorted at every depth, every image (an SDK `Image`, an `image_url` part, a

package/dist/jev/retry.js

@@ -0,0 +1,29 @@
+/** A busy or flaky model API (5xx incl. 529 overload, 429, 499, timeouts, dropped connections): worth another try. */
+const TRANSIENT_MODEL_ERROR = /^(5\d\d|429|499)\b|timeout|timed out|ECONNRESET|ETIMEDOUT|fetch failed|socket hang up/i;
+/**
+ * Whether a model call failed for a reason that may pass on its own.
+ *
+ * @example
+ * isTransientModelError(new Error('529 We are currently experiencing high traffic')) // true
+ */
+export const isTransientModelError = (error) => error instanceof Error && TRANSIENT_MODEL_ERROR.test(error.message);
+/**
+ * An `Ask` that tries again after a transient failure, waiting each of `delaysMs` in turn; any other failure, or the
+ * last one, is thrown as it came.
+ *
+ * @example
+ * const ask = retryingAsk(createAsk(profile), { delaysMs: [1000, 3000] });
+ */
+export const retryingAsk = (ask, { delaysMs, wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) => async (request) => {
+    for (const delay of delaysMs) {
+        try {
+            return await ask(request);
+        }
+        catch (error) {
+            if (!isTransientModelError(error))
+                throw error;
+            await wait(delay);
+        }
+    }
+    return ask(request);
+};

package/dist/journeys/journey-doc.js

@@ -44,7 +44,8 @@ export const buildFlows = (steps) => {
     return [...flows.values()];
 };
 const parentOf = (name) => (name.includes('/') ? name.slice(0, name.lastIndexOf('/')) : null);
-const describeAction = (step) => {
+/** A step's action as a person reads it: `Tap "Search"`, `Type into "Destination" → "Lisbon"`. */
+export const describeAction = (step) => {
     const verb = { CLICK: 'Tap', TYPE_TEXT: 'Type into', SELECT: 'Choose' }[step.action.operation] ?? step.action.operation;
     return `${verb} "${step.action.label}"${step.action.value ? ` → "${step.action.value}"` : ''}`;
 };

package/dist/journeys/journey-session.js

@@ -10,6 +10,9 @@ import { buildFlows, hotspotOf } from './journey-doc.js';
 import { pickNextMove } from './pick-next-move.js';
 import { renderViewer } from './render-viewer.js';
 import { qaFindings, readScreenJudgments, screenQuestions, } from './screen-judgments.js';
+import { screenFileName } from '../output/layout.js';
+import { writeManifest } from '../output/manifest.js';
+import { outsideHosts } from '../task/hosts.js';
 const EXPLORE_GOAL = `Explore this site the way a first-time mobile visitor would, one screen at a time.
 Open the next screen that matters most for the site's core user journeys: discovering, searching, comparing,
 and evaluating its main offering. Prefer primary navigation, search, results, and detail screens over legal,
@@ -24,7 +27,7 @@ footer, social, app-download, or external links. Dismiss blocking banners. Never
  * journey.report();                                   // screen s01 + Jev's suggested next tap
  * await journey.step({ next: 4, flow: 'Search', insight: 'Search is a full-screen sheet' });
  * await journey.autopilot({ screens: 5, flow: 'Search/Results' });
- * journey.finish();                                   // → journey.json, index.html, screens/*.png
+ * journey.finish();                                   // → journey.json, index.html, manifest.json, screens/s01-home.png …
  */
 export class JourneySession {
     doc;
@@ -227,7 +230,8 @@ export class JourneySession {
                 continue;
             }
             const scope = this.#options.stayWithin ?? new URL(this.#options.startUrl).origin;
-            if (!(await this.#tab.observe()).url.startsWith(scope)) {
+            const landed = (await this.#tab.observe()).url;
+            if (!landed.startsWith(scope) || this.#outsideHosts(landed)) {
                 await this.#goBack();
                 this.#logMove('left_scope', move.action.label);
                 continue;
@@ -286,9 +290,15 @@ export class JourneySession {
         return this.report();
     }
     // Observe → one Jev request (next step + screen understanding) → dedupe → screenshot → QA → save.
+    #outsideHosts(url) {
+        return this.#options.hosts && outsideHosts(url, this.#options.hosts);
+    }
     async #capture(arrival) {
         await this.#diagnostics.waitForIdle();
         const page = await this.#settledPage();
+        const outside = this.#outsideHosts(page.url);
+        if (outside)
+            throw new Error(`The page is outside the server's hosts: ${outside}. Take \`back\` to return.`);
         const seesScreen = (this.#options.screenshots ?? 'off') !== 'off';
         const boxed = seesScreen && Boolean(this.#options.box);
         const decision = await decide(this.#ask, {
@@ -320,7 +330,7 @@ export class JourneySession {
             mergeFindings(this.#screen(existing).qa, findings);
         }
         else {
-            const screenshot = `screens/${id}.png`;
+            const screenshot = screenFileName(id, judgments.type);
             writeFileSync(join(this.outDir, screenshot), Buffer.from(await this.#tab.screenshot(), 'base64'));
             this.doc.screens.push({
                 id,
@@ -433,6 +443,7 @@ export class JourneySession {
         this.doc.flows = buildFlows(this.doc.steps);
         writeFileSync(join(this.outDir, 'journey.json'), JSON.stringify(this.doc, null, 2));
         writeFileSync(join(this.outDir, 'index.html'), renderViewer(this.doc));
+        writeManifest(this.outDir, 'journey');
     }
 }
 // "https://site/#/" and "https://site/" are the same route.