jevway 0.1.2 → 0.2.0

package/dist/cli/run-command.js

@@ -0,0 +1,173 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { createSessionService } from '../session/session-service.js';
+import { CHECKS } from '../task/checks.js';
+import { presentSummary } from '../task/present.js';
+import { callDaemon, daemonFor, placement, requireKey, runnerChoice, runnerFor, TIMEOUTS } from './daemon-call.js';
+import { choiceFlag, intFlag, jsonFlag, listFlag, parseFlags, usageError } from './flags.js';
+import { renderHelp } from './help.js';
+import { eventPrinter, printDoc } from './output.js';
+const TEXT_BY_KEY = z.record(z.string(), z.string());
+export const runSpec = {
+    name: 'run',
+    summary: 'hand a browser goal to Jev and print one JSON result',
+    examples: [
+        'jevway run --url https://en.wikipedia.org --goal "Open the article about the Rosetta Stone" --done-when "The Rosetta Stone article is open"',
+        'jevway run --session new --browser launch-headless --url https://shop.example/checkout --goal "Fill in the delivery details" --values \'{"name":"Ada Lovelace","email":"ada@example.com"}\'',
+        'jevway run --session <id> --goal "Fill in the delivery details" --values \'{"phone":"+44 20 7946 0000"}\'',
+        'jevway run --session <id> --goal "Delete the repository ada/scratch" --confirm-irreversible --confirm-target "ada/scratch"',
+    ],
+    flags: {
+        goal: { type: 'string', value: '<text>', describe: 'the full outcome wanted, in plain language (every call)' },
+        url: { type: 'string', value: '<url>', describe: 'open this page in a new tab (start)' },
+        tab: { type: 'string', value: '<url part>', describe: 'or drive an open tab whose URL contains this (start)' },
+        session: { type: 'string', value: '<id|new>', describe: 'new: keep the tab in the background daemon between calls; <id>: continue that session' },
+        values: { type: 'string', value: '<json>', describe: 'text values Jev may type, e.g. \'{"city":"Lisbon"}\'' },
+        'secret-keys': { type: 'string', value: '<a,b>', describe: 'keys of --values that are secrets: Jev sees the key only, output shows [secret:<key>]' },
+        files: { type: 'string', value: '<json>', describe: 'files Jev may upload, key to absolute path; Jev sees names, never paths' },
+        'done-when': { type: 'string', value: '<text>', describe: 'visible evidence of success on the page the call ends on' },
+        checks: { type: 'string', value: '<json>', describe: 'facts code checks on the final page, e.g. \'[{"type":"url_contains","text":"/issues/"}]\'' },
+        'confirm-irreversible': { type: 'boolean', describe: 'allow one click flagged irreversible, only when the user\'s request names it' },
+        'confirm-target': { type: 'string', value: '<words>', describe: 'with --confirm-irreversible: the user\'s words naming the target' },
+        'max-steps': { type: 'string', value: '<n>', describe: 'step limit, 1 to 100 (default 40)' },
+        'max-seconds': { type: 'string', value: '<n>', describe: 'time budget per call, 1 to 3600 (default 300); past it the run ends step_budget' },
+        'allowed-hosts': { type: 'string', value: '<a.com,*.b.com>', describe: 'hosts the run may be on; leaving them ends it blocked' },
+        'blocked-hosts': { type: 'string', value: '<a.com>', describe: 'hosts it must never be on' },
+        'allow-coordinate-clicks': { type: 'boolean', describe: 'click a boxed control the DOM never reported (Jev 1.14 direct only; start)' },
+        record: { type: 'boolean', describe: 'keep a recording for people in the run folder: video, step shots, index.html (start)' },
+        'record-dir': { type: 'string', value: '<dir>', describe: 'put the whole run folder, recording included, here instead (start; --record <dir> works too)' },
+        detail: { type: 'string', value: 'concise|full', describe: 'full adds the raw steps with confidences, Jev\'s stats and stuck candidates' },
+        screenshot: { type: 'boolean', describe: 'accepted for parity with MCP; the result always carries files.screenshot' },
+        browser: { type: 'string', value: '<source>', describe: 'auto, launch, launch-headless or http://127.0.0.1:<port> (default $JEVWAY_BROWSER or auto; start)' },
+        model: { type: 'string', value: '<name>', describe: 'jev, pplx-decider, clef-omni, clef, clef-flash or gpt-6-luna (default $JEVWAY_MODEL or jev; start)' },
+        screenshots: { type: 'string', value: 'off|fallback|always', describe: 'marked screenshots for vision models (default per model; start)' },
+        'keep-open': { type: 'boolean', describe: 'without --session: leave the tabs open at the end' },
+    },
+    notes: [
+        'Without --session the run happens in this process and its tabs close at the end, as before. With --session the',
+        'background daemon keeps the tab (and a launched browser) between calls; jevway end <id> closes it, jevway stop',
+        'stops the daemon. (start) flags count on a session\'s first call only.',
+        '',
+        'Prints { ok: true, session?, status, reason, next, story, url, title, page_text, files, … }; progress as NDJSON on',
+        'stderr. Exit 0 when status is done, 1 on a hand-back (needs_input, needs_confirmation, uncertain, step_budget,',
+        'blocked) or a tool error, 2 on bad usage or a missing key. outcome_unknown: the daemon went away mid-call; check',
+        'with jevway look --session <id> before repeating it.',
+    ],
+};
+/**
+ * `next` in the CLI's words: flags instead of MCP parameters, and the session to pass (or, for a one-shot run, how to
+ * keep one).
+ *
+ * @example
+ * cliNext('Add the missing values to `values` and call again with this session.', 'abc')
+ * // 'Add the missing values to `--values` and run again with `--session abc`.'
+ */
+export const cliNext = (next, session) => {
+    const again = (call, joiner = '') => {
+        const run = `${call === 'C' ? 'R' : 'r'}un again`;
+        if (session)
+            return `${run} with \`--session ${session}\`${joiner}`;
+        return joiner ? `${run} with ` : run;
+    };
+    let text = next
+        .replace(/`confirm_irreversible: true`/g, '`--confirm-irreversible`')
+        .replace(/`(values|goal|confirm_target|max_steps|max_seconds)`/g, (_, name) => `\`--${name.replace(/_/g, '-')}\``)
+        .replace(/([Cc])all again with this session(, | and )?/g, (_, call, joiner) => again(call, joiner));
+    text = session
+        ? text.replace('end the session when', `end it with \`jevway end ${session}\` when`)
+        : text.replace('; end the session when you no longer need its tab', '');
+    return !session && /un again/.test(text) ? `${text} Pass \`--session new\` to keep the tab between calls.` : text;
+};
+// Today's `--record <dir>` keeps working: a value after --record is the folder.
+const withRecordDir = (argv) => argv.flatMap((arg, i) => (arg === '--record' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-') ? ['--record-dir'] : [arg]));
+const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, inner]) => inner !== undefined));
+/** `jevway run`: one goal, in-process without `--session`, through the daemon with it. */
+export const runCommand = async (argv, deps) => {
+    const { flags } = parseFlags(runSpec, withRecordDir(argv), { positionals: 0 });
+    if (flags.help) {
+        await deps.io.out(renderHelp(runSpec));
+        return 0;
+    }
+    const text = (name) => (typeof flags[name] === 'string' ? flags[name] : undefined);
+    const yes = (name) => (flags[name] === true ? true : undefined);
+    const goal = text('goal');
+    if (!goal)
+        throw usageError('missing_flag', 'jevway run needs --goal', 'Example: jevway run --url https://example.com --goal "Open the pricing page"');
+    const session = text('session');
+    const starting = !session || session === 'new';
+    if (starting && !text('url') && !text('tab')) {
+        throw usageError('missing_flag', 'jevway run needs --url or --tab (or --session to continue)', 'Example: jevway run --url https://example.com --goal "Open the pricing page"');
+    }
+    const detail = choiceFlag('detail', text('detail'), ['concise', 'full']) ?? 'concise';
+    const recordDir = text('record-dir');
+    const request = defined({
+        goal,
+        url: text('url'),
+        tab: text('tab'),
+        values: jsonFlag('values', text('values'), TEXT_BY_KEY, '{"city":"Lisbon"}'),
+        secretKeys: listFlag(text('secret-keys')),
+        files: jsonFlag('files', text('files'), TEXT_BY_KEY, '{"avatar":"/Users/ada/me.png"}'),
+        doneWhen: text('done-when'),
+        checks: jsonFlag('checks', text('checks'), CHECKS, '[{"type":"url_contains","text":"/issues/"}]'),
+        maxSteps: intFlag('max-steps', text('max-steps'), { min: 1, max: 100 }),
+        maxSeconds: intFlag('max-seconds', text('max-seconds'), { min: 1, max: 3600 }),
+        allowedHosts: listFlag(text('allowed-hosts')),
+        blockedHosts: listFlag(text('blocked-hosts')),
+        confirmIrreversible: yes('confirm-irreversible'),
+        confirmTarget: text('confirm-target'),
+        allowCoordinateClicks: yes('allow-coordinate-clicks'),
+        record: yes('record'),
+        recordDir: recordDir && resolve(deps.cwd, recordDir),
+    });
+    const choice = runnerChoice(flags, deps.env);
+    if (!session)
+        return runHere(deps, request, { choice, detail, keepOpen: Boolean(yes('keep-open')) });
+    if (starting)
+        requireKey(runnerFor(deps, choice));
+    const connection = await daemonFor(deps, starting ? { start: true } : { session, kind: 'session' });
+    const printEvent = eventPrinter(deps.io);
+    let id = starting ? undefined : session;
+    const cancel = new AbortController();
+    const stopListening = deps.onInterrupt(() => cancel.abort());
+    try {
+        const result = await callDaemon(connection, 'task', { request: { ...request, ...(id && { session: id }) }, detail, runner: choice, place: placement(deps) }, {
+            writes: true,
+            session: () => id,
+            log: deps.daemon.log,
+            signal: cancel.signal,
+            timeoutMs: TIMEOUTS.task(request.maxSeconds, !starting),
+            onEvent: (event) => {
+                if (event?.type === 'started')
+                    id = event.session;
+                printEvent(event);
+            },
+        });
+        await printDoc(deps.io, { ok: true, ...result, next: cliNext(result.next, result.session) });
+        return result.status === 'done' ? 0 : 1;
+    }
+    finally {
+        stopListening();
+    }
+};
+/** A one-shot run in this process, as before the daemon: its own browser connection, its tabs closed at the end. */
+const runHere = async (deps, request, { choice, detail, keepOpen }) => {
+    const runner = runnerFor(deps, choice);
+    requireKey(runner);
+    const sessions = createSessionService(runner, { env: deps.env, cwd: deps.cwd });
+    // Ctrl-C stops the run at its next check (an action under way finishes), so the result still prints and the tab closes.
+    const cancel = new AbortController();
+    const stopListening = deps.onInterrupt(() => cancel.abort());
+    try {
+        const result = await sessions.task(request, { signal: cancel.signal, onEvent: eventPrinter(deps.io) });
+        if (!keepOpen)
+            await sessions.end(result.session).catch(() => undefined);
+        // Nothing is left to continue, so the result names no session.
+        const { session: _session, ...presented } = presentSummary(result, { detail });
+        await printDoc(deps.io, { ok: true, ...presented, next: cliNext(presented.next, undefined) });
+        return presented.status === 'done' ? 0 : 1;
+    }
+    finally {
+        stopListening();
+        await sessions.close().catch(() => undefined);
+    }
+};

package/dist/cli/session-commands.js

@@ -0,0 +1,132 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DaemonRunning, startDaemon } from '../daemon/server.js';
+import { envFingerprint } from '../daemon/paths.js';
+import { callDaemon, daemonFor, TIMEOUTS } from './daemon-call.js';
+import { CliError, durationFlag, parseFlags, usageError } from './flags.js';
+import { renderHelp } from './help.js';
+import { printDoc } from './output.js';
+export const sessionsSpec = {
+    name: 'sessions',
+    summary: 'list the daemon\'s open sessions and journeys',
+    examples: ['jevway sessions'],
+    flags: {},
+    notes: ['Prints { ok: true, daemon: { pid, version, socket, log, idle_timeout_s } | null, sessions: [{ session, kind, goal, status, url, running, run_dir, … }] }. Never starts the daemon.'],
+};
+export const endSpec = {
+    name: 'end',
+    argument: '<id>',
+    summary: 'end a session (or finish a journey) and close the tabs it opened',
+    examples: ['jevway end <id>', 'jevway end <id> --keep-tab'],
+    flags: {
+        session: { type: 'string', value: '<id>', describe: 'the session (or pass it as the argument)' },
+        'keep-tab': { type: 'boolean', describe: 'leave its tabs open' },
+    },
+    notes: ['Prints { ok: true, session, run_dir }. A session the daemon does not hold is unknown_session, exit 1.'],
+};
+export const serveSpec = {
+    name: 'serve',
+    summary: 'run the session daemon in the foreground (other commands start it in the background when needed)',
+    examples: ['jevway serve', 'jevway serve --idle-timeout 0'],
+    flags: { 'idle-timeout': { type: 'string', value: '<duration>', describe: 'end sessions idle this long, then exit: seconds, or 90s, 30m, 2h; 0 never (default 1h)' } },
+    notes: [
+        'Prints { ok: true, socket, pid, version, idle_timeout_s } once it listens, then NDJSON log lines on stderr until it stops.',
+        'Socket and log: $JEVWAY_STATE_DIR, else $XDG_RUNTIME_DIR/jevway, else ~/.cache/jevway (daemon.sock, daemon.log).',
+        'It keeps the environment it started with; after changing keys, jevway stop and the next command starts a fresh one.',
+    ],
+};
+export const stopSpec = {
+    name: 'stop',
+    summary: 'stop the daemon: end every session, close the tabs they opened and any browser it launched',
+    examples: ['jevway stop'],
+    flags: {},
+    notes: ['Prints { ok: true, stopped: true, ended: <sessions> }, or { ok: true, stopped: false } when none was running.'],
+};
+const helped = async (spec, argv, deps, positionals = 0) => {
+    const parsed = parseFlags(spec, argv, { positionals });
+    if (!parsed.flags.help)
+        return parsed;
+    await deps.io.out(renderHelp(spec));
+    return undefined;
+};
+const daemonInfo = (hello, deps) => ({
+    pid: hello.pid,
+    version: hello.version,
+    socket: deps.daemon.socket,
+    log: deps.daemon.log,
+    idle_timeout_s: hello.idle_timeout_s,
+    started_at: hello.started_at,
+});
+/** `jevway sessions`: what the running daemon holds; no daemon is an empty list. */
+export const sessionsCommand = async (argv, deps) => {
+    if (!(await helped(sessionsSpec, argv, deps)))
+        return 0;
+    const connection = await deps.daemon.find();
+    if (!connection) {
+        await printDoc(deps.io, { ok: true, daemon: null, sessions: [] });
+        return 0;
+    }
+    const { daemon, sessions } = await callDaemon(connection, 'sessions', {}, { writes: false, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+    await printDoc(deps.io, { ok: true, daemon: daemonInfo(daemon, deps), sessions });
+    return 0;
+};
+/** `jevway end <id>`: ends a session or finishes a journey. */
+export const endCommand = async (argv, deps) => {
+    const parsed = await helped(endSpec, argv, deps, 1);
+    if (!parsed)
+        return 0;
+    const session = parsed.positionals[0] ?? parsed.flags.session;
+    if (!session)
+        throw usageError('missing_flag', 'jevway end needs the session id', 'Example: jevway end <id> (jevway sessions lists them)');
+    const connection = await daemonFor(deps, { session, kind: 'session' });
+    const ended = await callDaemon(connection, 'end', { session, keepTab: parsed.flags['keep-tab'] === true }, { writes: true, session: () => session, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+    await printDoc(deps.io, { ok: true, ...ended });
+    return 0;
+};
+/** `jevway stop`: stops the running daemon, if any. */
+export const stopCommand = async (argv, deps) => {
+    if (!(await helped(stopSpec, argv, deps)))
+        return 0;
+    const connection = await deps.daemon.find();
+    if (!connection) {
+        await printDoc(deps.io, { ok: true, stopped: false });
+        return 0;
+    }
+    const result = await callDaemon(connection, 'stop', {}, { writes: false, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+    await Promise.race([connection.closed, new Promise((resolve) => setTimeout(resolve, 2_000).unref())]);
+    await printDoc(deps.io, { ok: true, ...result });
+    return 0;
+};
+/** `jevway serve`: the daemon in the foreground, until `jevway stop`, Ctrl-C or the idle timeout. */
+export const serveCommand = async (argv, deps) => {
+    const parsed = await helped(serveSpec, argv, deps);
+    if (!parsed)
+        return 0;
+    const raw = parsed.flags['idle-timeout'];
+    const idleMs = typeof raw === 'string' ? durationFlag('idle-timeout', raw) : 3_600_000;
+    const { socket } = deps.daemon;
+    if (process.platform !== 'win32')
+        mkdirSync(dirname(socket), { recursive: true, mode: 0o700 });
+    let daemon;
+    try {
+        daemon = await startDaemon({
+            socket,
+            version: deps.version,
+            fingerprint: envFingerprint(deps.env),
+            idleMs,
+            runnerFor: ({ browser, ...choice }) => deps.createRunner(browser, choice),
+            log: (entry) => deps.io.err(`${JSON.stringify({ time: new Date().toISOString(), ...entry })}\n`),
+        });
+    }
+    catch (error) {
+        if (error instanceof DaemonRunning)
+            throw new CliError(1, error.code, error.message, 'jevway sessions shows it; jevway stop stops it');
+        throw error;
+    }
+    const stopListening = deps.onInterrupt(() => void daemon.stop());
+    // One line, so a background daemon's log stays one JSON object per line.
+    await deps.io.out(`${JSON.stringify({ ok: true, socket, pid: process.pid, version: deps.version, idle_timeout_s: idleMs ? idleMs / 1000 : null })}\n`);
+    await daemon.closed;
+    stopListening();
+    return 0;
+};

package/dist/daemon/client.js

@@ -0,0 +1,175 @@
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, renameSync, rmSync, statSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { logPath } from './paths.js';
+import { readLines, sendLine } from './protocol.js';
+/**
+ * A daemon call that failed: the daemon's own error (`code`, `message`, `hint`), or `lost` when the connection closed
+ * or timed out before an answer, so the call may or may not have happened.
+ */
+export class DaemonFailure extends Error {
+    code;
+    hint;
+    lost;
+    constructor(code, message, hint, lost = false) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.lost = lost;
+    }
+}
+const NOT_LISTENING = new Set(['ENOENT', 'ECONNREFUSED', 'ENOTSOCK']);
+const HELLO_TIMEOUT_MS = 5_000;
+const STOP_TIMEOUT_MS = 60_000;
+const START_TIMEOUT_MS = 10_000;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const lostConnection = (timedOut) => new DaemonFailure('daemon_unavailable', timedOut ? 'The daemon did not answer in time.' : 'The connection to the daemon closed before it answered.', 'Run the command again; jevway sessions shows what the daemon holds.', true);
+const open = (socket) => new Promise((resolve, reject) => {
+    const connection = createConnection(socket);
+    const onError = (error) => {
+        if (NOT_LISTENING.has(error.code ?? ''))
+            resolve(undefined);
+        else
+            reject(new DaemonFailure('daemon_unavailable', `Could not reach the jevway daemon at ${socket}: ${error.message}`, 'Run jevway stop, then the command again.'));
+    };
+    connection.once('error', onError);
+    connection.once('connect', () => {
+        connection.off('error', onError);
+        resolve(connection);
+    });
+});
+/**
+ * Connects to the daemon on `socket` and says hello; undefined when nothing listens there.
+ *
+ * @example
+ * const daemon = await connectDaemon('/Users/ada/.cache/jevway/daemon.sock');
+ * daemon?.hello.version // '0.1.2'
+ */
+export const connectDaemon = async (socket) => {
+    const connection = await open(socket);
+    if (!connection)
+        return undefined;
+    const waiting = new Map();
+    let nextId = 0;
+    let markClosed;
+    const closed = new Promise((resolve) => (markClosed = resolve));
+    readLines(connection, (message) => {
+        const call = waiting.get(message?.id);
+        if (!call)
+            return;
+        if ('event' in message)
+            return call.onEvent?.(message.event);
+        waiting.delete(message.id);
+        if ('error' in message)
+            call.reject(new DaemonFailure(message.error.code, message.error.message, message.error.hint));
+        else
+            call.resolve(message.result);
+    });
+    connection.on('error', () => undefined);
+    connection.on('close', () => {
+        for (const call of waiting.values())
+            call.reject(lostConnection(false));
+        waiting.clear();
+        markClosed();
+    });
+    const request = (method, params = {}, { onEvent, timeoutMs, signal } = {}) => new Promise((resolve, reject) => {
+        if (connection.destroyed)
+            return reject(lostConnection(false));
+        const id = ++nextId;
+        const onAbort = () => sendLine(connection, { cancel: id });
+        const timer = timeoutMs
+            ? setTimeout(() => {
+                waiting.delete(id);
+                settle();
+                reject(lostConnection(true));
+                connection.destroy();
+            }, timeoutMs)
+            : undefined;
+        const settle = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        waiting.set(id, {
+            resolve: (value) => (settle(), resolve(value)),
+            reject: (error) => (settle(), reject(error)),
+            onEvent,
+        });
+        signal?.addEventListener('abort', onAbort, { once: true });
+        sendLine(connection, { id, method, params });
+        if (signal?.aborted)
+            onAbort();
+    });
+    try {
+        const hello = await request('hello', {}, { timeoutMs: HELLO_TIMEOUT_MS });
+        return { hello, request, close: () => connection.end(), closed };
+    }
+    catch (error) {
+        connection.destroy();
+        throw error;
+    }
+};
+/**
+ * How a command reaches the daemon on `socket`. `start` launches one (in the background for the real CLI, in-process in
+ * tests); the client then waits up to 10 s for it to answer.
+ */
+export const daemonAccess = ({ socket, log, version, fingerprint, start, startTimeoutMs = START_TIMEOUT_MS, }) => ({
+    socket,
+    log,
+    find: () => connectDaemon(socket),
+    async ensure(onEvent) {
+        let reason;
+        const running = await connectDaemon(socket);
+        if (running) {
+            const { hello } = running;
+            reason =
+                hello.version !== version
+                    ? `the running daemon is version ${hello.version}, this jevway is ${version}`
+                    : hello.fingerprint !== fingerprint
+                        ? 'the running daemon was started with other settings (keys, CHROME_PATH, JEVWAY_ALLOWED_HOSTS/JEVWAY_BLOCKED_HOSTS or JEVWAY_REPLAY)'
+                        : undefined;
+            if (!reason)
+                return running;
+            if (hello.sessions > 0) {
+                running.close();
+                throw new DaemonFailure('daemon_busy', `${reason}, and it holds ${hello.sessions} session${hello.sessions === 1 ? '' : 's'}`, 'List them with jevway sessions; jevway stop ends them and the next command starts a new daemon');
+            }
+            await running.request('stop', {}, { timeoutMs: STOP_TIMEOUT_MS }).catch(() => undefined);
+            running.close();
+            await Promise.race([running.closed, delay(STOP_TIMEOUT_MS)]);
+        }
+        else if (process.platform !== 'win32' && existsSync(socket)) {
+            // A socket file nothing answers on: its daemon died without removing it.
+            rmSync(socket, { force: true });
+        }
+        await start();
+        const deadline = Date.now() + startTimeoutMs;
+        while (Date.now() < deadline) {
+            const connection = await connectDaemon(socket).catch(() => undefined);
+            if (connection) {
+                onEvent({ type: 'daemon', event: reason ? 'restarted' : 'started', pid: connection.hello.pid, log, ...(reason && { reason }) });
+                return connection;
+            }
+            await delay(50);
+        }
+        throw new DaemonFailure('daemon_unavailable', `The jevway daemon did not start within ${startTimeoutMs / 1000} s`, `See ${log}, or run jevway serve to watch it start`);
+    },
+});
+// The daemon inherits the environment already loaded; an --env-file flag would only log a missing .env in its state dir.
+const daemonExecArgv = () => process.execArgv.filter((arg) => !arg.startsWith('--env-file'));
+/**
+ * Starts `node <entry> serve` detached in `stateDir`, its output appended to `daemon.log` (moved to `daemon.log.1`
+ * past 5 MB). Returns at once; the caller waits for the socket.
+ */
+export const spawnDaemon = ({ entry, stateDir, env, execArgv = daemonExecArgv() }) => {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const log = logPath(stateDir);
+    if ((statSync(log, { throwIfNoEntry: false })?.size ?? 0) > 5_000_000)
+        renameSync(log, `${log}.1`);
+    const fd = openSync(log, 'a', 0o600);
+    try {
+        spawn(process.execPath, [...execArgv, entry, 'serve'], { detached: true, stdio: ['ignore', fd, fd], cwd: stateDir, env, windowsHide: true }).unref();
+    }
+    finally {
+        closeSync(fd);
+    }
+};

package/dist/daemon/paths.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { homedir, tmpdir, userInfo } from 'node:os';
+import { join, resolve } from 'node:path';
+/** Where the daemon keeps its socket and log: `$JEVWAY_STATE_DIR`, else `$XDG_RUNTIME_DIR/jevway`, else `~/.cache/jevway`. */
+export const stateDir = (env = process.env, home = homedir()) => env.JEVWAY_STATE_DIR?.trim() || (env.XDG_RUNTIME_DIR?.trim() ? join(env.XDG_RUNTIME_DIR, 'jevway') : join(home, '.cache', 'jevway'));
+// Unix socket paths are capped at 104 bytes on macOS (108 on Linux), counting the terminating NUL.
+const SOCKET_PATH_BYTES = 103;
+const stateDigest = (dir) => createHash('sha256').update(`${userInfo().username}:${dir}`).digest('hex').slice(0, 16);
+/**
+ * `<state>/daemon.sock`, or `<tmp>/jevway-<digest>.sock` when the state dir is too deep for a Unix socket; on Windows
+ * a named pipe. One state dir always maps to one socket.
+ */
+export const socketPath = (dir, platform = process.platform, tmp = tmpdir()) => {
+    if (platform === 'win32')
+        return `\\\\.\\pipe\\jevway-${stateDigest(dir)}`;
+    const inState = join(dir, 'daemon.sock');
+    return Buffer.byteLength(inState) <= SOCKET_PATH_BYTES ? inState : join(tmp, `jevway-${stateDigest(dir)}.sock`);
+};
+export const logPath = (dir) => join(dir, 'daemon.log');
+/**
+ * The environment a daemon is started with: the caller's, with `JEVWAY_REPLAY_DIR` made absolute (the daemon runs in
+ * its state dir).
+ */
+export const daemonEnv = (env, cwd) => env.JEVWAY_REPLAY_DIR?.trim() ? { ...env, JEVWAY_REPLAY_DIR: resolve(cwd, env.JEVWAY_REPLAY_DIR.trim()) } : env;
+// What a daemon reads from its own environment rather than from each request. Keys count only as set or not.
+const KEYS = ['TYPESAFE_API_KEY', 'OPENROUTER_API_KEY'];
+const SETTINGS = ['CHROME_PATH', 'JEVWAY_ALLOWED_HOSTS', 'JEVWAY_BLOCKED_HOSTS', 'JEVWAY_REPLAY', 'JEVWAY_REPLAY_DIR'];
+/**
+ * A digest of the settings a daemon reads from its own environment, so a client can tell when a running daemon was
+ * started with other ones. Holds nothing derived from a key's value, only whether each key is set.
+ */
+export const envFingerprint = (env) => createHash('sha256')
+    .update(JSON.stringify([...KEYS.map((name) => Boolean(env[name]?.trim())), ...SETTINGS.map((name) => env[name]?.trim() ?? '')]))
+    .digest('hex')
+    .slice(0, 16);

package/dist/daemon/protocol.js

@@ -0,0 +1,28 @@
+export const sendLine = (socket, message) => {
+    if (!socket.destroyed && socket.writable)
+        socket.write(`${JSON.stringify(message)}\n`);
+};
+/** Calls `onMessage` with each JSON line the socket receives; a line that does not parse is dropped. */
+export const readLines = (socket, onMessage) => {
+    let buffer = '';
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk) => {
+        buffer += chunk;
+        let newline = buffer.indexOf('\n');
+        while (newline >= 0) {
+            const line = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            newline = buffer.indexOf('\n');
+            if (!line)
+                continue;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            onMessage(message);
+        }
+    });
+};