@genesislcap/ai-assistant 15.86.1 → 15.87.0

package/dist/esm/headless-server/server.js

@@ -0,0 +1,746 @@
+import { __awaiter } from "tslib";
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { join, resolve } from 'node:path';
+import { capOutput, compactDecision, compactEvent, present, shortDecision } from './compact';
+import { DECISION_TEXTS, DEFAULT_DECISION_TEXT, } from './types';
+const DEFAULT_MAX_WAIT_MS = 100000;
+/** The longest a command may ask to wait (an hour), ms. A larger `maxWaitMs` is cut to it. */
+const MAX_WAIT_CAP_MS = 3600000;
+/** The ops the server answers itself: a host's `extraOps` cannot take their names. */
+const BUILTIN_OPS = [
+    'send',
+    'act',
+    'resolve',
+    'autopilot',
+    'wait',
+    'state',
+    'read',
+    'debugLog',
+    'stop',
+];
+const BYTES_PER_KB = 1024;
+const MAX_BODY_MB = 16;
+const MAX_BODY_BYTES = MAX_BODY_MB * BYTES_PER_KB * BYTES_PER_KB;
+/** HTTP statuses the server answers with. */
+const HTTP_OK = 200;
+const HTTP_BAD_REQUEST = 400;
+const HTTP_FORBIDDEN = 403;
+const HTTP_NOT_FOUND = 404;
+const HTTP_UNSUPPORTED_MEDIA_TYPE = 415;
+/** The addresses that mean this machine: a bound `host` that is none of them is the host's own choice. */
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '[::1]', '::1'];
+const HTTP_SERVER_ERROR = 500;
+/** How long `shutdown` lets a reply on its way finish before it drops every connection, ms. */
+const CLOSE_GRACE_MS = 500;
+/** Cost is reported to four decimal places. */
+const MONEY_SCALE = 10000;
+/** How long the log watcher sleeps between looks when nothing happens. */
+const WATCH_MS = 2000;
+const ALL_EVENT_TYPES = [
+    'decision',
+    'working',
+    'settled',
+    'message',
+    'turn',
+    'autopilot',
+    'probe',
+    'error',
+];
+/** `until` as the caller wrote it: one name or several. `idle` is the server's own, not an event type. */
+function untilOf(value) {
+    if (value === undefined)
+        return undefined;
+    const names = (Array.isArray(value) ? value : [value]).map(String);
+    return {
+        types: names.filter((n) => ALL_EVENT_TYPES.includes(n)),
+        idle: names.includes('idle'),
+    };
+}
+/** `maxWaitMs` as the caller wrote it: a finite number cut to `0..MAX_WAIT_CAP_MS`, else the default. */
+function waitMsOf(value, fallback) {
+    const n = Number(value !== null && value !== void 0 ? value : fallback);
+    return Number.isFinite(n) ? Math.min(Math.max(0, n), MAX_WAIT_CAP_MS) : fallback;
+}
+const hasOwn = (target, key) => !!target && Object.prototype.hasOwnProperty.call(target, key);
+const money = (usd) => Math.round(usd * MONEY_SCALE) / MONEY_SCALE;
+/**
+ * The headless server (PLAN §5, D7): `node:http` on 127.0.0.1, `GET /health` and `POST /cmd`.
+ *
+ * Every command is APPLIED and then LONG-POLLS (§5.5): the reply comes when the journey next needs the
+ * person (an interaction is held by them and ready), a turn ends, the run ends, or something fails, or at
+ * `maxWaitMs` with `status: "working"`. Nothing is lost on a client timeout: the command was applied before
+ * the wait, events carry `seq`, and `{op: "wait", since}` returns everything after it.
+ *
+ * The session is the only thing it drives; what the host owns is reached through {@link ServerOptions}.
+ */
+// oxlint-disable-next-line max-lines-per-function -- one closure over the session, the log and the HTTP server, as it was in Create
+export function createHeadlessServer(options) {
+    var _a, _b;
+    const runDir = resolve(options.runDir);
+    mkdirSync(runDir, { recursive: true });
+    const defaultMaxWaitMs = waitMsOf(options.defaultMaxWaitMs, DEFAULT_MAX_WAIT_MS);
+    let decisionText = (_a = options.decisionText) !== null && _a !== void 0 ? _a : DEFAULT_DECISION_TEXT;
+    const announce = (_b = options.announce) !== null && _b !== void 0 ? _b : ((line) => console.log(line));
+    const events = createWriteStream(join(runDir, 'events.jsonl'), { flags: 'a' });
+    const startedAt = Date.now();
+    let session;
+    let http;
+    let closing = false;
+    let loggedSeq = 0;
+    /** Serialises the APPLY phase of commands that change things; a long wait never holds it. */
+    let applying = Promise.resolve();
+    /** The save chain: every flush runs after the one before it, so the last one sees the latest state. */
+    let flushing = Promise.resolve();
+    let resolveClosed;
+    const closed = new Promise((r) => {
+        resolveClosed = r;
+    });
+    const appendLog = (line) => {
+        if (!events.writableEnded)
+            events.write(`${JSON.stringify(line)}\n`);
+    };
+    /** Write every event the log has not yet written. */
+    function drainLog() {
+        if (!session)
+            return;
+        for (const event of session.eventsSince(loggedSeq)) {
+            appendLog(Object.assign({ kind: 'event' }, event));
+            loggedSeq = event.seq;
+        }
+    }
+    /** Save what the host and the session hold, after any save already running. Never rejects. */
+    function flushAll() {
+        flushing = flushing.then(() => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                yield ((_a = options.flush) === null || _a === void 0 ? void 0 : _a.call(options));
+                yield (session === null || session === void 0 ? void 0 : session.flush());
+            }
+            catch (e) {
+                appendLog({
+                    kind: 'error',
+                    where: 'flush',
+                    message: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }));
+        return flushing;
+    }
+    /** Follow the log in the background: write it down, and save at every turn end, whoever's turn. */
+    function watch(s) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let cursor = s.state().lastSeq;
+            // Everything before the attach goes in the log too.
+            drainLog();
+            const watching = () => !closing && session === s;
+            while (watching()) {
+                try {
+                    // oxlint-disable-next-line no-await-in-loop -- a sequential watcher and poll: each step needs the last
+                    const woken = yield s.wait({ since: cursor, until: ALL_EVENT_TYPES, maxWaitMs: WATCH_MS });
+                    cursor = woken.nextSeq;
+                    drainLog();
+                    // oxlint-disable-next-line no-await-in-loop -- a sequential watcher and poll: each step needs the last
+                    if (woken.events.some((e) => e.type === 'turn'))
+                        yield flushAll();
+                    if (woken.status === 'closed')
+                        break;
+                }
+                catch (e) {
+                    appendLog({
+                        kind: 'error',
+                        where: 'watch',
+                        message: e instanceof Error ? e.message : String(e),
+                    });
+                    break;
+                }
+            }
+        });
+    }
+    const handle = {
+        get session() {
+            return session;
+        },
+        runDir,
+        get decisionText() {
+            return decisionText;
+        },
+        setDecisionText(mode) {
+            decisionText = mode;
+        },
+        attach(next) {
+            if (session === next)
+                return;
+            session = next;
+            // A new session numbers its events from 1: the old one's last `seq` would hide its first ones.
+            loggedSeq = 0;
+            void watch(next);
+        },
+        listen,
+        handle: runCommand,
+        shutdown,
+        closed,
+    };
+    if (options.session)
+        handle.attach(options.session);
+    // ---------------------------------------------------------------------------------------- replies
+    const composerOf = (state) => {
+        var _a;
+        if (!state)
+            return 'blocked:not-started';
+        const blocked = (_a = options.composerBlockedReason) === null || _a === void 0 ? void 0 : _a.call(options);
+        if (blocked)
+            return `blocked:${blocked}`;
+        return state.busy ? 'busy' : 'open';
+    };
+    /** The status a reply with no waiting reports: what the session is doing now. */
+    function statusNow(state) {
+        var _a, _b;
+        if (!state)
+            return 'idle';
+        if (state.pending)
+            return 'decision';
+        if ((_a = options.isEnded) === null || _a === void 0 ? void 0 : _a.call(options))
+            return 'ended';
+        if ((_b = state.autopilot) === null || _b === void 0 ? void 0 : _b.needsUser)
+            return 'needs-user';
+        return state.busy ? 'working' : 'idle';
+    }
+    const probeView = (state) => {
+        const view = options.probeEvent;
+        if (!view)
+            return undefined;
+        return Object.fromEntries(view.keys.map((key) => { var _a; return [key, (_a = state.probe[key]) !== null && _a !== void 0 ? _a : null]; }));
+    };
+    /** What is going on, in words: the host's account of the open widget, or whose turn it is with none open. */
+    function stageOf(state, other) {
+        var _a, _b, _c;
+        if (other) {
+            let stage;
+            try {
+                stage = (_a = options.describeWorking) === null || _a === void 0 ? void 0 : _a.call(options, other.interactionId, other.component);
+            }
+            catch (_d) {
+                /* a stage is a nicety: a host that cannot say is the same as one that has nothing to say */
+            }
+            if (stage)
+                return stage;
+            // A paused autopilot answers nothing, whatever its `working` flag says.
+            const idle = other.heldBy === 'autopilot' && ((_b = state.autopilot) === null || _b === void 0 ? void 0 : _b.mode) !== 'running';
+            return other.heldBy !== 'user' && !idle ? `${other.heldBy} is answering it` : undefined;
+        }
+        // The flag can stay true while the mode is `paused`: only a running autopilot is doing anything.
+        if (((_c = state.autopilot) === null || _c === void 0 ? void 0 : _c.working) && state.autopilot.mode === 'running') {
+            return 'autopilot is working';
+        }
+        return state.busy ? 'assistant is thinking (no widget open)' : undefined;
+    }
+    function workingInfo(state, startedMs) {
+        var _a;
+        const other = (_a = state.others.find((o) => !o.ready || o.heldBy !== 'user')) !== null && _a !== void 0 ? _a : state.others[0];
+        return Object.assign(Object.assign(Object.assign({}, (other ? { component: other.component, heldBy: other.heldBy } : {})), { elapsedMs: Date.now() - startedMs }), present({ probe: probeView(state), stage: stageOf(state, other) }));
+    }
+    /** A command's own `decisionText` when it names a valid one, else the server's. */
+    const decisionTextFor = (command) => DECISION_TEXTS.includes(command === null || command === void 0 ? void 0 : command.decisionText)
+        ? command.decisionText
+        : decisionText;
+    function reply(command, status, since, extra = {}, startedMs = Date.now()) {
+        var _a, _b, _c;
+        const state = session === null || session === void 0 ? void 0 : session.state();
+        const compact = since
+            .map((e) => compactEvent(e, { probeEvent: options.probeEvent }))
+            .filter((e) => !!e);
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ ok: (_a = extra.ok) !== null && _a !== void 0 ? _a : true }, ((command === null || command === void 0 ? void 0 : command.id) !== undefined ? { id: command.id } : {})), { status }), (compact.length ? { since: compact } : {})), ((state === null || state === void 0 ? void 0 : state.pending)
+            ? { decision: compactDecision(state.pending, decisionTextFor(command)) }
+            : {})), (status === 'working' && state ? { working: workingInfo(state, startedMs) } : {})), { composer: composerOf(state), cost: { usd: money((_b = state === null || state === void 0 ? void 0 : state.cost.costUsd) !== null && _b !== void 0 ? _b : 0) }, nextSeq: (_c = state === null || state === void 0 ? void 0 : state.lastSeq) !== null && _c !== void 0 ? _c : 0 }), extra);
+    }
+    /** A refusal: the reason, and where things stand (including the decision, if one is waiting). */
+    function refuse(command, error, reason, since = undefined, 
+    /** The interaction an `act` was refused on: when it is the pending one, its card is not sent again. */
+    shortFor) {
+        const state = session === null || session === void 0 ? void 0 : session.state();
+        const missed = session && since !== undefined ? session.eventsSince(since) : [];
+        const pending = state === null || state === void 0 ? void 0 : state.pending;
+        return reply(command, statusNow(state), missed, Object.assign(Object.assign({ ok: false, error }, (reason ? { reason } : {})), (pending && shortFor !== undefined && pending.interactionId === shortFor
+            ? { decision: shortDecision(pending.interactionId, pending.component, pending.actions) }
+            : {})));
+    }
+    /**
+     * The reply to an action that ran and did not settle the interaction (a form field set): at once, with what
+     * it returned and the actions as they now stand, and not the card, which the caller has read.
+     */
+    function edited(command, interactionId, result, cursor) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const s = session;
+        const state = s.state();
+        const open = ((_a = state.pending) === null || _a === void 0 ? void 0 : _a.interactionId) === interactionId ? state.pending : undefined;
+        const actions = (_d = (_c = (_b = result.description) === null || _b === void 0 ? void 0 : _b.actions) !== null && _c !== void 0 ? _c : open === null || open === void 0 ? void 0 : open.actions) !== null && _d !== void 0 ? _d : result.actions;
+        const component = (_j = (_g = (_f = (_e = result.description) === null || _e === void 0 ? void 0 : _e.component) !== null && _f !== void 0 ? _f : open === null || open === void 0 ? void 0 : open.component) !== null && _g !== void 0 ? _g : (_h = state.others.find((o) => o.interactionId === interactionId)) === null || _h === void 0 ? void 0 : _h.component) !== null && _j !== void 0 ? _j : '';
+        return reply(command, 'edited', s.eventsSince(cursor), Object.assign({ decision: shortDecision(interactionId, component, actions) }, (result.output !== undefined ? { output: capOutput(result.output) } : {})));
+    }
+    // ------------------------------------------------------------------------------------ the long poll
+    /**
+     * Wait for the journey to need the caller, then reply with everything since `cursor`. A `signal` that
+     * aborts (the connection closed) ends the wait with a `working` reply that no one will read. The terminal
+     * conditions are read from the session's live state, not from the events alone, so an event that has
+     * since been overtaken (a decision the autopilot took back) does not end the wait.
+     */
+    function poll(command, cursor, startedMs, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const s = session;
+            if (!s)
+                return reply(command, 'idle', [], {}, startedMs);
+            const maxWaitMs = waitMsOf(command.maxWaitMs, defaultMaxWaitMs);
+            const deadline = startedMs + maxWaitMs;
+            const until = untilOf(command.until);
+            let waitFrom = cursor;
+            for (;;) {
+                const since = s.eventsSince(cursor);
+                const state = s.state();
+                const verdict = terminal(since, state, until);
+                if (verdict) {
+                    // oxlint-disable-next-line no-await-in-loop -- a sequential watcher and poll: each step needs the last
+                    if (since.some((e) => e.type === 'turn') || verdict === 'ended')
+                        yield flushAll();
+                    drainLog();
+                    return reply(command, verdict, s.eventsSince(cursor), {}, startedMs);
+                }
+                const remaining = deadline - Date.now();
+                // A caller that hung up has no one to wait for: stop looking, and let the waiter go.
+                if (remaining <= 0 || (signal === null || signal === void 0 ? void 0 : signal.aborted)) {
+                    drainLog();
+                    return reply(command, 'working', since, {}, startedMs);
+                }
+                // oxlint-disable-next-line no-await-in-loop -- a sequential watcher and poll: each step needs the last
+                const woken = yield s.wait(Object.assign(Object.assign(Object.assign({ since: waitFrom }, (until ? { until: until.types } : {})), { maxWaitMs: remaining }), (signal ? { signal } : {})));
+                waitFrom = woken.nextSeq;
+                if (woken.status === 'closed') {
+                    drainLog();
+                    return reply(command, 'ended', s.eventsSince(cursor), {}, startedMs);
+                }
+            }
+        });
+    }
+    /** The status this state and these events call for, or `undefined` to keep waiting. */
+    function terminal(since, state, until) {
+        var _a, _b;
+        const turnEnded = since.some((e) => e.type === 'turn');
+        const failed = since.some((e) => e.type === 'error' || (e.type === 'turn' && e.failureReason));
+        if (((_a = options.isEnded) === null || _a === void 0 ? void 0 : _a.call(options)) && !state.pending && (turnEnded || !state.busy))
+            return 'ended';
+        if (until) {
+            if (state.pending && until.types.includes('decision'))
+                return 'decision';
+            if (since.some((e) => until.types.includes(e.type))) {
+                return since.some((e) => e.type === 'error')
+                    ? 'error'
+                    : turnEnded
+                        ? 'turn'
+                        : statusNow(state);
+            }
+            if (until.idle && !state.busy && !state.pending)
+                return 'idle';
+            return undefined;
+        }
+        if (state.pending)
+            return 'decision';
+        if (failed)
+            return 'error';
+        if (turnEnded)
+            return 'turn';
+        if ((_b = state.autopilot) === null || _b === void 0 ? void 0 : _b.needsUser)
+            return 'needs-user';
+        return undefined;
+    }
+    // ----------------------------------------------------------------------------------------- the ops
+    const isOpen = (state, interactionId) => {
+        var _a;
+        return ((_a = state.pending) === null || _a === void 0 ? void 0 : _a.interactionId) === interactionId ||
+            state.others.some((o) => o.interactionId === interactionId);
+    };
+    /** The standard refusal for a command on an interaction that is no longer (or never was) pending. */
+    const gone = (command, interactionId, since) => refuse(command, `interaction ${interactionId} is not pending: it has settled, or never existed`, 'ended', since);
+    const notStarted = (command) => {
+        var _a;
+        return refuse(command, ((_a = options.extraOps) === null || _a === void 0 ? void 0 : _a.start)
+            ? 'not started: send {"op":"start", …} first'
+            : 'no session is attached', 'not-started');
+    };
+    const str = (value) => typeof value === 'string' ? value : undefined;
+    /** `act`'s action: a digit string is the option's number. */
+    const actionOf = (value) => typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : value;
+    function applyOp(command, s, cursor) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const state = s.state();
+            switch (command.op) {
+                case 'send': {
+                    const text = str(command.text);
+                    if (text === undefined)
+                        return refuse(command, '`send` needs `text`', 'invalid-command');
+                    const paths = Array.isArray(command.files) ? command.files.map(String) : [];
+                    let attachments;
+                    if (paths.length) {
+                        if (!options.readAttachment) {
+                            return refuse(command, 'this server cannot read files', 'invalid-command');
+                        }
+                        try {
+                            attachments = yield Promise.all(paths.map((p) => options.readAttachment(p)));
+                        }
+                        catch (e) {
+                            return refuse(command, `could not read a file: ${e instanceof Error ? e.message : String(e)}`, 'invalid-command');
+                        }
+                    }
+                    const sent = s.send(text, Object.assign(Object.assign({}, (attachments ? { attachments } : {})), (str(command.agent) ? { agent: str(command.agent) } : {})));
+                    return sent.ok ? 'poll' : refuse(command, sent.error, 'refused', cursor);
+                }
+                case 'act': {
+                    const interactionId = str(command.interactionId);
+                    if (!interactionId || command.action === undefined) {
+                        return refuse(command, '`act` needs `interactionId` and `action`', 'invalid-command');
+                    }
+                    if (!isOpen(state, interactionId))
+                        return gone(command, interactionId, cursor);
+                    const result = yield s.act(interactionId, actionOf(command.action), Object.assign(Object.assign(Object.assign({}, (str(command.text) !== undefined ? { text: str(command.text) } : {})), (Array.isArray(command.options) ? { options: command.options.map(String) } : {})), (command.fields !== undefined ? { fields: command.fields } : {})));
+                    if (!result.ok)
+                        return refuse(command, result.message, result.error, cursor, interactionId);
+                    // An edit (not a finishing action) settles nothing, so there is nothing to wait for.
+                    if (result.finished === false)
+                        return edited(command, interactionId, result, cursor);
+                    return 'poll';
+                }
+                case 'resolve': {
+                    const interactionId = str(command.interactionId);
+                    if (!interactionId)
+                        return refuse(command, '`resolve` needs `interactionId` and `result`', 'invalid-command');
+                    if (!isOpen(state, interactionId))
+                        return gone(command, interactionId, cursor);
+                    const resolved = s.resolve(interactionId, command.result);
+                    return resolved.ok ? 'poll' : refuse(command, resolved.error, 'refused', cursor);
+                }
+                case 'autopilot': {
+                    const mode = {
+                        pause: 'pause',
+                        paused: 'pause',
+                        resume: 'resume',
+                        running: 'resume',
+                        stop: 'stop',
+                    }[String(command.mode)];
+                    if (!mode)
+                        return refuse(command, '`autopilot` needs `mode`: running, paused or stop', 'invalid-command');
+                    const done = s.autopilot(mode);
+                    return done.ok ? 'poll' : refuse(command, done.error, 'refused', cursor);
+                }
+                case 'wait':
+                    return 'poll';
+                default:
+                    return refuse(command, `unknown op "${command.op}"`, 'unknown-op');
+            }
+        });
+    }
+    /** Ops that report and do not wait. */
+    function readOp(command, s) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            switch (command.op) {
+                case 'state': {
+                    const state = s.state();
+                    return reply(command, statusNow(state), [], Object.assign(Object.assign(Object.assign(Object.assign({}, (state.others.length ? { others: state.others } : {})), (state.autopilot ? { autopilot: state.autopilot } : {})), (Object.keys(state.probe).length ? { probe: state.probe } : {})), { busy: state.busy }));
+                }
+                case 'read': {
+                    const interactionId = str(command.interactionId);
+                    if (!interactionId)
+                        return refuse(command, '`read` needs `interactionId`', 'invalid-command');
+                    const read = yield s.read(interactionId, Object.assign(Object.assign(Object.assign({}, (str(command.view) ? { view: str(command.view) } : {})), (str(command.tool) ? { tool: str(command.tool) } : {})), (command.args && typeof command.args === 'object'
+                        ? { args: command.args }
+                        : {})));
+                    return read.ok
+                        ? Object.assign(Object.assign({ ok: true }, (command.id !== undefined ? { id: command.id } : {})), { content: read.content })
+                        : Object.assign(Object.assign({ ok: false }, (command.id !== undefined ? { id: command.id } : {})), { error: read.error });
+                }
+                case 'debugLog': {
+                    yield flushAll();
+                    const log = yield s.debugLog();
+                    const path = join(runDir, 'debug-log.json');
+                    yield writeFile(path, JSON.stringify(log));
+                    const byKind = {};
+                    for (const entry of log.timeline) {
+                        const kind = String((_a = entry.kind) !== null && _a !== void 0 ? _a : 'unknown');
+                        byKind[kind] = ((_b = byKind[kind]) !== null && _b !== void 0 ? _b : 0) + 1;
+                    }
+                    const usd = (_d = (_c = log.sessionUsage) === null || _c === void 0 ? void 0 : _c.costUsd) !== null && _d !== void 0 ? _d : s.state().cost.costUsd;
+                    return reply(command, statusNow(s.state()), [], {
+                        path,
+                        entries: { total: log.timeline.length, byKind },
+                        cost: { usd: money(usd) },
+                    });
+                }
+                default:
+                    return undefined;
+            }
+        });
+    }
+    /** Run one command to its reply. Never throws: a failure is a reply. */
+    function runCommand(raw, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const startedMs = Date.now();
+            const command = raw;
+            if (!command || typeof command !== 'object' || typeof command.op !== 'string') {
+                return reply(undefined, statusNow(session === null || session === void 0 ? void 0 : session.state()), [], {
+                    ok: false,
+                    error: 'a command is a JSON object with a string `op`',
+                    reason: 'invalid-command',
+                });
+            }
+            appendLog({ kind: 'command', at: new Date().toISOString(), command });
+            if (command.decisionText !== undefined && !DECISION_TEXTS.includes(command.decisionText)) {
+                return refuse(command, `\`decisionText\` must be one of ${DECISION_TEXTS.join(', ')} (got ${JSON.stringify(command.decisionText)})`, 'invalid-command');
+            }
+            try {
+                const out = yield dispatch(command, startedMs, signal);
+                drainLog();
+                return out;
+            }
+            catch (e) {
+                drainLog();
+                appendLog({
+                    kind: 'error',
+                    where: `op:${command.op}`,
+                    message: e instanceof Error ? e.message : String(e),
+                });
+                return reply(command, statusNow(session === null || session === void 0 ? void 0 : session.state()), [], {
+                    ok: false,
+                    status: 'error',
+                    error: e instanceof Error ? e.message : String(e),
+                    reason: 'threw',
+                });
+            }
+        });
+    }
+    function dispatch(command, startedMs, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (command.op === 'stop') {
+                session === null || session === void 0 ? void 0 : session.stop();
+                const out = reply(command, 'ended', [], { stopped: true });
+                // After the reply is on its way: the process may exit when the shutdown finishes.
+                setTimeout(() => void shutdown(), 0);
+                return out;
+            }
+            // A built-in wins over a host op of the same name, and an op is an OWN property of `extraOps`:
+            // `toString` and `constructor` are not ops.
+            const isBuiltin = BUILTIN_OPS.includes(command.op);
+            const extra = !isBuiltin && hasOwn(options.extraOps, command.op)
+                ? options.extraOps[command.op]
+                : undefined;
+            if (!extra && !isBuiltin) {
+                return refuse(command, `unknown op "${command.op}"`, 'unknown-op');
+            }
+            if (command.op === 'state' || command.op === 'read' || command.op === 'debugLog') {
+                if (!session)
+                    return notStarted(command);
+                return (yield readOp(command, session));
+            }
+            // The cursor: where the log stood before the command, unless the caller names one.
+            const cursor = typeof command.since === 'number' ? command.since : ((_a = session === null || session === void 0 ? void 0 : session.state().lastSeq) !== null && _a !== void 0 ? _a : 0);
+            if (command.op === 'wait') {
+                if (!session)
+                    return notStarted(command);
+                return poll(command, cursor, startedMs, signal);
+            }
+            // The apply phase is serial; the wait that follows is not.
+            const previous = applying;
+            let release;
+            applying = new Promise((r) => {
+                release = r;
+            });
+            let applied;
+            try {
+                yield previous;
+                if (extra) {
+                    applied = yield extra(command, handle);
+                }
+                else {
+                    if (!session)
+                        return notStarted(command);
+                    applied = yield applyOp(command, session, cursor);
+                }
+            }
+            finally {
+                release();
+            }
+            if (applied === 'poll')
+                return poll(command, cursor, startedMs, signal);
+            if ('status' in applied)
+                return applied;
+            // An extra op's result.
+            if (!applied.ok)
+                return refuse(command, (_b = applied.error) !== null && _b !== void 0 ? _b : 'refused', 'refused', typeof command.since === 'number' ? cursor : undefined);
+            const wait = (_c = applied.poll) !== null && _c !== void 0 ? _c : !!session;
+            if (!wait || !session) {
+                const pending = session === null || session === void 0 ? void 0 : session.state().pending;
+                return reply(command, statusNow(session === null || session === void 0 ? void 0 : session.state()), [], Object.assign(Object.assign({}, applied.fields), (applied.shortDecision && pending
+                    ? { decision: shortDecision(pending.interactionId, pending.component, pending.actions) }
+                    : {})), startedMs);
+            }
+            const polled = yield poll(command, cursor, startedMs, signal);
+            return Object.assign(Object.assign({}, polled), applied.fields);
+        });
+    }
+    // ------------------------------------------------------------------------------------------- HTTP
+    function readBody(req) {
+        return new Promise((resolveBody, reject) => {
+            const chunks = [];
+            let size = 0;
+            req.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > MAX_BODY_BYTES) {
+                    reject(new Error('the command is too large'));
+                    req.destroy();
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            req.on('end', () => resolveBody(Buffer.concat(chunks).toString('utf8')));
+            req.on('error', reject);
+        });
+    }
+    function send(res, status, body) {
+        const json = JSON.stringify(body);
+        res.writeHead(status, {
+            'content-type': 'application/json; charset=utf-8',
+            'content-length': Buffer.byteLength(json),
+        });
+        res.end(json);
+    }
+    /**
+     * Whether a request may be answered. The socket is on this machine, but a web page open in the
+     * developer's browser can reach it: so a request that carries an `Origin` (a browser sent it) is
+     * refused, and the `Host` must be this server's own address (a rebound name is not), and a command is
+     * `application/json`, which a page cannot send without a preflight this server never answers.
+     */
+    function refusal(req, port) {
+        var _a, _b, _c;
+        if (req.headers.origin !== undefined) {
+            return { status: HTTP_FORBIDDEN, error: 'a request from a web page is refused' };
+        }
+        const bound = (_a = options.host) !== null && _a !== void 0 ? _a : '127.0.0.1';
+        // Only a loopback bind has a `Host` to hold to; a host that binds wider has chosen who reaches it.
+        if (LOOPBACK_HOSTS.includes(bound)) {
+            const host = ((_b = req.headers.host) !== null && _b !== void 0 ? _b : '').toLowerCase();
+            if (!LOOPBACK_HOSTS.some((name) => host === `${name}:${port}`)) {
+                return {
+                    status: HTTP_FORBIDDEN,
+                    error: `the Host must be 127.0.0.1:${port} or localhost:${port}`,
+                };
+            }
+        }
+        if (req.method === 'POST') {
+            const type = ((_c = req.headers['content-type']) !== null && _c !== void 0 ? _c : '').split(';')[0].trim().toLowerCase();
+            if (type !== 'application/json') {
+                return {
+                    status: HTTP_UNSUPPORTED_MEDIA_TYPE,
+                    error: 'POST /cmd takes content-type: application/json',
+                };
+            }
+        }
+        return undefined;
+    }
+    function onRequest(req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const refused = refusal(req, http.address().port);
+            if (refused) {
+                send(res, refused.status, { ok: false, status: 'error', error: refused.error });
+                return;
+            }
+            const url = ((_a = req.url) !== null && _a !== void 0 ? _a : '/').split('?')[0];
+            if (req.method === 'GET' && url === '/health') {
+                const state = session === null || session === void 0 ? void 0 : session.state();
+                send(res, HTTP_OK, Object.assign({ ok: true, started: !!session, runDir, pid: process.pid, uptimeMs: Date.now() - startedAt }, (state ? { status: statusNow(state), nextSeq: state.lastSeq } : {})));
+                return;
+            }
+            if (req.method === 'POST' && url === '/cmd') {
+                let command;
+                try {
+                    command = JSON.parse(yield readBody(req));
+                }
+                catch (e) {
+                    send(res, HTTP_BAD_REQUEST, {
+                        ok: false,
+                        status: 'error',
+                        error: `bad command: ${e instanceof Error ? e.message : String(e)}`,
+                    });
+                    return;
+                }
+                // A client that hangs up ends the wait it started; the command it sent was applied all the same.
+                const gone = new AbortController();
+                res.on('close', () => {
+                    if (!res.writableEnded)
+                        gone.abort();
+                });
+                const out = yield runCommand(command, gone.signal);
+                if (!gone.signal.aborted)
+                    send(res, HTTP_OK, out);
+                return;
+            }
+            send(res, HTTP_NOT_FOUND, {
+                ok: false,
+                error: 'GET /health, or POST /cmd with one JSON command',
+            });
+        });
+    }
+    function listen() {
+        return new Promise((resolveListen, reject) => {
+            var _a, _b;
+            http = createServer((req, res) => {
+                onRequest(req, res).catch((e) => {
+                    if (!res.headersSent)
+                        send(res, HTTP_SERVER_ERROR, { ok: false, status: 'error', error: String(e) });
+                    else
+                        res.end();
+                });
+            });
+            http.once('error', reject);
+            http.listen((_a = options.port) !== null && _a !== void 0 ? _a : 0, (_b = options.host) !== null && _b !== void 0 ? _b : '127.0.0.1', () => {
+                const { port } = http.address();
+                announce(`HEADLESS_READY port=${port} runDir=${runDir}`);
+                resolveListen({ port, runDir });
+            });
+        });
+    }
+    function shutdown() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (closing)
+                return closed;
+            closing = true;
+            try {
+                session === null || session === void 0 ? void 0 : session.stop();
+            }
+            catch (_b) {
+                /* stopping is best effort */
+            }
+            yield flushAll();
+            drainLog();
+            yield new Promise((r) => {
+                var _a;
+                if (!http) {
+                    r();
+                    return;
+                }
+                http.close(() => r());
+                (_a = http.closeIdleConnections) === null || _a === void 0 ? void 0 : _a.call(http);
+                // A reply on its way (`stop`'s) gets a moment; a long poll in flight must not hold the process open.
+                setTimeout(() => { var _a; return (_a = http === null || http === void 0 ? void 0 : http.closeAllConnections) === null || _a === void 0 ? void 0 : _a.call(http); }, CLOSE_GRACE_MS).unref();
+            });
+            yield new Promise((r) => {
+                events.end(r);
+            });
+            yield ((_a = options.onClosed) === null || _a === void 0 ? void 0 : _a.call(options));
+            resolveClosed();
+            return closed;
+        });
+    }
+    return handle;
+}