jevway 0.1.2 → 0.3.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);
+        }
+    });
+};

package/dist/daemon/server.js

@@ -0,0 +1,339 @@
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { dirname, join } from 'node:path';
+import { InboxError } from '../inbox/inbox.js';
+import { createInboxRegistry } from '../inbox/inbox-registry.js';
+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>' };
+    }
+    if (error instanceof InboxError)
+        return { code: error.code, message: error.message, hint: error.hint };
+    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, inboxes = createInboxRegistry() }) => {
+    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, pdf }) {
+            return { session, ...(await holderOf(session, 'session').service.look({ session, pdf: pdf === true })) };
+        },
+        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 };
+        },
+        // Inboxes are named `inbox`, never `session`, so the idle sweep never mistakes one for a busy session.
+        'inbox.create': ({ provider }) => inboxes.create({ provider }),
+        async 'inbox.wait'({ inbox, from, subject, timeoutS }, { signal, emit }) {
+            const address = inboxes.addressOf(inbox);
+            const message = await inboxes.wait(inbox, {
+                from,
+                subject,
+                timeoutMs: timeoutS * 1000,
+                signal,
+                onPoll: (elapsedMs) => emit({ type: 'inbox_wait', address, elapsed_s: Math.round(elapsedMs / 1000), timeout_s: timeoutS }),
+            });
+            return { message: message ?? null };
+        },
+        'inbox.list': ({ inbox }, { signal }) => inboxes.list(inbox, { signal }),
+        'inbox.read': ({ inbox, id }, { signal }) => inboxes.read(inbox, id, { signal }),
+    };
+    // 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/inbox/inbox-file.js

@@ -0,0 +1,43 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureOutRoot } from '../output/layout.js';
+import { inboxFrom } from './inbox.js';
+const ADDRESS = /^[a-z0-9._+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i;
+/** `<root>/inboxes/<address>.env`; anything that is not a plain address is refused, so it never escapes the folder. */
+export const inboxFilePath = (root, address) => {
+    if (!ADDRESS.test(address) || address.includes('..'))
+        throw new Error(`"${address}" is not an email address`);
+    return join(root, 'inboxes', `${address.toLowerCase()}.env`);
+};
+/**
+ * Writes the one-shot CLI's credentials as the standalone script's `ADDR=` / `PASS=` / `API=` lines, mode 600 in a
+ * 700 folder, under an output root whose `.gitignore` is `*`. Returns the path.
+ */
+export const writeInboxFile = (root, inbox) => {
+    ensureOutRoot(root);
+    const path = inboxFilePath(root, inbox.address);
+    mkdirSync(join(root, 'inboxes'), { recursive: true, mode: 0o700 });
+    chmodSync(join(root, 'inboxes'), 0o700);
+    writeFileSync(path, `ADDR=${inbox.address}\nPASS=${inbox.password}\nAPI=${inbox.api}\n`, { mode: 0o600 });
+    // `mode` only applies when the file is created.
+    chmodSync(path, 0o600);
+    return path;
+};
+/** The inbox stored for `address` under `root`, or undefined when there is no file. */
+export const readInboxFile = (root, address) => {
+    let text;
+    try {
+        text = readFileSync(inboxFilePath(root, address), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const fields = Object.fromEntries(text
+        .split('\n')
+        .map((line) => /^(\w+)=(.*)$/.exec(line.trim()))
+        .filter((match) => match !== null)
+        .map(([, key, value]) => [key, value]));
+    if (!fields.ADDR || !fields.PASS || !fields.API)
+        return undefined;
+    return inboxFrom({ address: fields.ADDR, password: fields.PASS, api: fields.API });
+};

package/dist/inbox/inbox-registry.js

@@ -0,0 +1,33 @@
+import { randomUUID } from 'node:crypto';
+import { createInbox, InboxError, listMessages, PROVIDERS, providerOf, readMessage, waitForMessage, } from './inbox.js';
+/**
+ * The inboxes one process holds in memory (the MCP server, or the CLI daemon), each named by a UUID and found by
+ * that id or its address. They end with the process.
+ *
+ * @example
+ * const inboxes = createInboxRegistry();
+ * const { inbox, address } = await inboxes.create();
+ * await inboxes.wait(inbox, { from: 'staylist', timeoutMs: 120_000 });
+ */
+export const createInboxRegistry = (client = {}) => {
+    const inboxes = new Map();
+    const find = (handle) => {
+        const inbox = inboxes.get(handle) ?? [...inboxes.values()].find(({ address }) => address === handle.toLowerCase());
+        if (inbox)
+            return inbox;
+        throw new InboxError('unknown_inbox', `Unknown inbox "${handle}": inboxes live in memory and end when this jevway process (or its daemon) stops.`, 'Create a new one with jevway_inbox_create (CLI: jevway inbox create) and sign up again with its address.');
+    };
+    return {
+        async create({ provider } = {}) {
+            const inbox = await createInbox({ ...client, ...(provider && { api: PROVIDERS[provider] }) });
+            const id = randomUUID();
+            inboxes.set(id, inbox);
+            return { inbox: id, address: inbox.address, provider: providerOf(inbox.api) };
+        },
+        /** The inbox's address; throws `unknown_inbox`. */
+        addressOf: (handle) => find(handle).address,
+        wait: async (handle, options) => waitForMessage(find(handle), { ...client, ...options }),
+        list: async (handle, options = {}) => listMessages(find(handle), { ...client, ...options }),
+        read: async (handle, id, options = {}) => readMessage(find(handle), id, { ...client, ...options }),
+    };
+};