@braedonsaunders/appkit-desk 0.4.0

package/host.js

@@ -0,0 +1,1038 @@
+/**
+ * The desk host: lifecycle, leases, and the screen service over a backend.
+ *
+ * One host manages many desks against one capacity budget. A desk is
+ * headless by default; the screen is a service started on demand on the
+ * machine the agent is already using. The host owns lease accounting (idle
+ * suspend, a hard concurrency cap with a FIFO queue beyond it), event
+ * emission to the consumer's ports, and the handover masking contract. It
+ * never touches a database and knows nothing about tenants or approvals.
+ */
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { buildDeskLaunchPlan, cleanDeskId, DEFAULT_KVM_PATH, DEFAULT_VMM_PATH, DeskError, } from './plan.js';
+import { cloudHypervisorBackend, } from './backend.js';
+import { parseCapabilities, parseClipboardText, parseExecResult, parseHandoverBegun, parseJobStarted, parseObservation, } from './protocol.js';
+export const DEFAULT_CAPACITY = 4;
+export const DEFAULT_IDLE_SUSPEND_MS = 5 * 60_000;
+export const DEFAULT_LEASE_MS = 15 * 60_000;
+export const DEFAULT_CID_BASE = 100;
+const MAX_BUFFERED_FRAMES = 60;
+/**
+ * Video chunks a slow consumer may fall behind by before its stream is ended.
+ * Larger than the frame bound because a fragment is a fraction of a frame's
+ * bytes, and enforced by ENDING rather than by dropping — see the comment at
+ * the overrun.
+ */
+const MAX_BUFFERED_VIDEO_CHUNKS = 600;
+const MIN_TIMER_DELAY_MS = 25;
+/**
+ * Event kinds that must never reach the recording port while a handover is
+ * active. Human input and everything derived from watching the human act is
+ * masked; only the handover boundaries themselves cross.
+ */
+const HANDOVER_MASKED_KINDS = new Set([
+    'click',
+    'type',
+    'key',
+    'scroll',
+    'drag',
+    'window_focus',
+    'app_launch',
+]);
+export function createDeskHost(options) {
+    const ports = options.ports;
+    if (typeof ports?.onEvent !== 'function' || typeof ports?.audit !== 'function') {
+        throw new DeskError('createDeskHost requires ports with onEvent and audit functions.');
+    }
+    const backend = options.backend ?? cloudHypervisorBackend;
+    const now = options.now ?? Date.now;
+    const pathExists = options.pathExists ?? existsSync;
+    const deviceExists = options.deviceExists ?? existsSync;
+    const capacity = positiveInteger(options.capacity ?? DEFAULT_CAPACITY, 'capacity');
+    const idleSuspendMs = positiveInteger(options.idleSuspendMs ?? DEFAULT_IDLE_SUSPEND_MS, 'idleSuspendMs');
+    const defaultLeaseMs = positiveInteger(options.defaultLeaseMs ?? DEFAULT_LEASE_MS, 'defaultLeaseMs');
+    const kernelPath = options.kernelPath ?? join(options.imageRoot, 'vmlinux');
+    // Default the initramfs to <imageRoot>/initrd when present so a modular
+    // cloud kernel boots without every caller having to name it; an explicit
+    // option always wins.
+    const defaultInitramfs = join(options.imageRoot, 'initrd');
+    const initramfsPath = options.initramfsPath ?? (pathExists(defaultInitramfs) ? defaultInitramfs : undefined);
+    const kernelCmdline = options.kernelCmdline;
+    const records = new Map();
+    const queue = [];
+    let occupied = 0;
+    let nextCid = positiveInteger(options.cidBase ?? DEFAULT_CID_BASE, 'cidBase');
+    let lastStartedAt = null;
+    let lastSuspendedAt = null;
+    let lastError = null;
+    let reconnects = 0;
+    let lastReconnectAt = null;
+    let lastReconnectDeskId = null;
+    function iso(timestamp) {
+        return new Date(timestamp).toISOString();
+    }
+    function emit(record, detail) {
+        if (record.screen?.handover && HANDOVER_MASKED_KINDS.has(detail.kind))
+            return;
+        ports.onEvent({ ...detail, deskId: record.deskId, at: iso(now()) });
+    }
+    function touch(record) {
+        record.lastActivityAt = now();
+    }
+    function requireMachine(record, epoch) {
+        if (record.status !== 'resident' || record.epoch !== epoch || !record.machine) {
+            throw new DeskError(`Desk ${record.deskId} is not resident; resume it first.`);
+        }
+        return record.machine;
+    }
+    function requireScreen(record, epoch) {
+        requireMachine(record, epoch);
+        const screen = record.screen;
+        if (!screen?.running) {
+            throw new DeskError(`Desk ${record.deskId} has no screen running; call screen.start first.`);
+        }
+        return screen;
+    }
+    function assertCoordinates(record, points) {
+        const observation = record.screen?.lastObservation;
+        if (!observation) {
+            throw new DeskError('Coordinate input needs a frame of reference: call observe(), or start '
+                + 'frames() and wait for one. Coordinates are the pixel space of the '
+                + 'most recent of those, one to one.');
+        }
+        for (const point of points) {
+            if (!Number.isInteger(point.x)
+                || !Number.isInteger(point.y)
+                || point.x < 0
+                || point.y < 0
+                || point.x >= observation.width
+                || point.y >= observation.height) {
+                throw new DeskError(`Coordinates (${point.x}, ${point.y}) are outside the most recent view `
+                    + `(${observation.width}x${observation.height}); observe() again before targeting.`);
+            }
+        }
+    }
+    function armTimer(record) {
+        if (record.timer)
+            clearTimeout(record.timer);
+        record.timer = null;
+        if (record.status !== 'resident')
+            return;
+        const deadlines = [record.leaseDeadline, record.lastActivityAt + idleSuspendMs];
+        const handover = record.screen?.handover;
+        if (handover)
+            deadlines.push(handover.deadline);
+        const delayMs = Math.max(Math.min(...deadlines) - now(), MIN_TIMER_DELAY_MS);
+        record.timer = setTimeout(() => {
+            sweep()
+                .then(() => {
+                if (record.status === 'resident')
+                    armTimer(record);
+            })
+                .catch((error) => {
+                lastError = errorMessage(error);
+            });
+        }, delayMs);
+        record.timer.unref();
+    }
+    async function endHandover(record, reason) {
+        const screen = record.screen;
+        const handover = screen?.handover;
+        if (!screen || !handover)
+            return;
+        screen.handover = null;
+        if (record.machine) {
+            try {
+                await record.machine.request({ op: 'handover-end' });
+            }
+            catch (error) {
+                lastError = errorMessage(error);
+            }
+        }
+        const durationMs = Math.max(0, now() - handover.beganAt);
+        emit(record, { kind: 'handover_end', actor: handover.actor, durationMs });
+        ports.audit({
+            kind: 'handover_end',
+            deskId: record.deskId,
+            actor: handover.actor,
+            durationMs,
+            reason,
+            at: iso(now()),
+        });
+    }
+    async function teardown(record) {
+        if (record.status !== 'resident')
+            return;
+        await endHandover(record, 'revoked');
+        for (const stop of [...record.streamStops])
+            stop();
+        record.streamStops.clear();
+        if (record.screen?.running) {
+            record.screen.running = false;
+            emit(record, { kind: 'screen_close' });
+        }
+        record.screen = null;
+        for (const job of record.jobs.values()) {
+            if (job.status !== 'running')
+                continue;
+            job.status = 'exited';
+            job.signal = 'SIGKILL';
+            emit(record, { kind: 'job_exit', jobId: job.jobId, exitCode: null, signal: 'SIGKILL' });
+        }
+        record.unsubscribe?.();
+        record.unsubscribe = null;
+        record.unwatchConnection?.();
+        record.unwatchConnection = null;
+        if (record.timer)
+            clearTimeout(record.timer);
+        record.timer = null;
+        const machine = record.machine;
+        record.machine = null;
+        record.status = 'suspended';
+        record.handle = null;
+        if (machine) {
+            try {
+                await machine.shutdown();
+            }
+            catch (error) {
+                lastError = errorMessage(error);
+            }
+        }
+        lastSuspendedAt = iso(now());
+        occupied -= 1;
+        drainQueue();
+    }
+    function drainQueue() {
+        while (occupied < capacity && queue.length > 0) {
+            const entry = queue.shift();
+            if (!entry)
+                break;
+            occupied += 1;
+            entry.run().then(entry.resolve, (error) => {
+                occupied -= 1;
+                entry.reject(error instanceof Error ? error : new Error(String(error)));
+                drainQueue();
+            });
+        }
+    }
+    function admit(run) {
+        if (occupied < capacity) {
+            occupied += 1;
+            return run().catch((error) => {
+                occupied -= 1;
+                drainQueue();
+                throw error;
+            });
+        }
+        return new Promise((resolvePromise, rejectPromise) => {
+            queue.push({ run, resolve: resolvePromise, reject: rejectPromise });
+        });
+    }
+    async function boot(deskId, startOptions) {
+        const plan = buildDeskLaunchPlan({
+            deskId,
+            vmmPath: options.vmmPath,
+            kvmPath: options.kvmPath,
+            kernelPath,
+            ...(initramfsPath === undefined ? {} : { initramfsPath }),
+            baseImagePath: startOptions.baseImage,
+            overlayPath: startOptions.overlayPath,
+            memoryMb: startOptions.memoryMb,
+            vcpus: startOptions.vcpus,
+            vsockCid: nextCid++,
+            runtimeDir: options.runtimeDir,
+            tapDevice: startOptions.network?.tapDevice,
+            macAddress: startOptions.network?.macAddress,
+            // Forward the host's cmdline only when set; otherwise the plan falls
+            // back to DEFAULT_KERNEL_CMDLINE.
+            ...(kernelCmdline === undefined ? {} : { kernelCmdline }),
+            launcherIdentity: options.launcherIdentity,
+        }, { pathExists, deviceExists });
+        let machine;
+        try {
+            machine = await backend.boot(plan);
+        }
+        catch (error) {
+            lastError = errorMessage(error);
+            throw error instanceof DeskError
+                ? error
+                : new DeskError(`Desk ${deskId} failed to boot: ${errorMessage(error)}`);
+        }
+        let record = records.get(deskId);
+        if (!record) {
+            record = {
+                deskId,
+                startOptions,
+                status: 'resident',
+                machine,
+                epoch: 1,
+                leaseDeadline: 0,
+                lastActivityAt: 0,
+                jobs: new Map(),
+                screen: null,
+                unsubscribe: null,
+                unwatchConnection: null,
+                handle: null,
+                timer: null,
+                streamStops: new Set(),
+            };
+            records.set(deskId, record);
+        }
+        else {
+            record.startOptions = startOptions;
+            record.status = 'resident';
+            record.machine = machine;
+            record.epoch += 1;
+            record.jobs = new Map();
+            record.screen = null;
+            record.streamStops = new Set();
+        }
+        const current = record;
+        const epoch = current.epoch;
+        current.leaseDeadline = now() + positiveInteger(startOptions.leaseMs ?? defaultLeaseMs, 'leaseMs');
+        current.lastActivityAt = now();
+        current.unsubscribe = machine.subscribe((event) => {
+            handleGuestEvent(current, epoch, event);
+        });
+        current.unwatchConnection =
+            machine.onConnectionChange?.((change) => {
+                handleConnectionChange(current, epoch, change);
+            }) ?? null;
+        current.handle = makeHandle(current, epoch);
+        lastStartedAt = iso(now());
+        armTimer(current);
+        return current.handle;
+    }
+    function handleGuestEvent(record, epoch, event) {
+        if (record.status !== 'resident' || record.epoch !== epoch)
+            return;
+        if (event.event === 'job-exit') {
+            const job = record.jobs.get(event.jobId);
+            if (!job || job.status !== 'running')
+                return;
+            job.status = 'exited';
+            job.exitCode = event.exitCode;
+            job.signal = event.signal;
+            emit(record, {
+                kind: 'job_exit',
+                jobId: event.jobId,
+                exitCode: event.exitCode,
+                signal: event.signal,
+            });
+            return;
+        }
+        if (event.event === 'window-focus') {
+            if (record.screen)
+                record.screen.lastFocusedId = event.window.id;
+            emit(record, { kind: 'window_focus', window: event.window });
+        }
+    }
+    /**
+     * What a desk losing (and regaining) its guest channel means up here.
+     *
+     * The backend can get the CHANNEL back; it cannot get the GUEST's state
+     * back, and pretending otherwise is how a consumer ends up waiting forever
+     * on a stream that will never produce another byte. So a reconnect is
+     * treated as a discontinuity that the caller is able to see, and a
+     * permanent loss retires the desk instead of leaving a dead one leased.
+     */
+    function handleConnectionChange(record, epoch, change) {
+        if (record.status !== 'resident' || record.epoch !== epoch)
+            return;
+        if (change.state === 'reconnected') {
+            reconnects += 1;
+            lastReconnectAt = iso(now());
+            lastReconnectDeskId = record.deskId;
+            // Never silent. A reconnect that hides a guest agent restarting is a
+            // debugging trap: the desk misbehaves and nothing anywhere says why.
+            lastError = `Desk ${record.deskId} reconnected to its guest agent after ${change.downtimeMs}ms (${change.reason}).`;
+            // The guest's capture state did not necessarily come back with the
+            // channel. An agent that restarted has no screen, no frame encoder and
+            // no video encoder; even one that survived starts a fresh encoder whose
+            // sequence numbers and init segment do not continue the old stream. A
+            // consumer resumed mid-stream decodes nothing, silently — so every live
+            // stream is ENDED. `frames()`/`video()` complete normally, which is how
+            // the consumer notices, and it can start a new one on a guest that is
+            // now definitely capturing.
+            for (const stop of [...record.streamStops])
+                stop();
+            record.streamStops.clear();
+            // The coordinate anchor goes with them: the screen behind it may be
+            // gone, or recreated at another size, and a click aimed at the pixel
+            // space of a screen that no longer exists lands somewhere nobody chose.
+            // Input then refuses until the caller observes again — the existing
+            // contract, not a new one.
+            if (record.screen)
+                record.screen.lastObservation = null;
+            // A handover is deliberately NOT ended here. If a human is still on that
+            // screen, dropping the mask would start recording them; letting the TTL
+            // expire it fails in the safe direction.
+            return;
+        }
+        // Lost for good. Left resident, this desk would answer every call with
+        // "no longer connected" for the rest of the lease and `resume()` would
+        // hand back the same dead handle — the exact product failure this release
+        // is about. Suspending it frees the capacity slot and makes the next
+        // `resume()` boot a healthy desk.
+        lastError = change.reason;
+        void teardown(record).catch((error) => {
+            lastError = errorMessage(error);
+        });
+    }
+    function makeHandle(record, epoch) {
+        const execImplementation = async (execOptions) => {
+            const machine = requireMachine(record, epoch);
+            const command = nonEmptyString(execOptions.command, 'command');
+            const args = [...(execOptions.args ?? [])];
+            const keepAlive = execOptions.keepAlive === true;
+            if (ports.policy?.allowExec && !ports.policy.allowExec({
+                deskId: record.deskId,
+                command,
+                args,
+                keepAlive,
+            })) {
+                throw new DeskError(`Policy denied exec of ${command} on desk ${record.deskId}.`);
+            }
+            touch(record);
+            const startedAt = iso(now());
+            if (keepAlive) {
+                const { jobId } = parseJobStarted(await machine.request({
+                    op: 'job-start',
+                    command,
+                    args,
+                    cwd: execOptions.cwd,
+                    env: execOptions.env,
+                }));
+                const job = {
+                    jobId,
+                    deskId: record.deskId,
+                    command,
+                    args,
+                    startedAt,
+                    status: 'running',
+                    exitCode: null,
+                    signal: null,
+                };
+                record.jobs.set(jobId, job);
+                emit(record, { kind: 'job_start', jobId, command, args });
+                return { ...job };
+            }
+            const result = parseExecResult(await machine.request({
+                op: 'exec',
+                command,
+                args,
+                cwd: execOptions.cwd,
+                env: execOptions.env,
+                timeoutMs: execOptions.timeoutMs,
+            }, execOptions.timeoutMs === undefined ? {} : { timeoutMs: execOptions.timeoutMs + 5_000 }));
+            emit(record, {
+                kind: 'shell_command',
+                command,
+                args,
+                cwd: execOptions.cwd ?? null,
+                exitCode: result.exitCode,
+                signal: result.signal,
+            });
+            return {
+                deskId: record.deskId,
+                command,
+                args,
+                exitCode: result.exitCode,
+                signal: result.signal,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                truncated: result.truncated,
+                startedAt,
+                finishedAt: iso(now()),
+            };
+        };
+        const screenService = {
+            async start({ width, height }) {
+                const machine = requireMachine(record, epoch);
+                if (record.screen?.running)
+                    return record.screen.handle;
+                const cleanWidth = positiveInteger(width, 'width');
+                const cleanHeight = positiveInteger(height, 'height');
+                if (ports.policy?.allowScreen && !ports.policy.allowScreen({
+                    deskId: record.deskId,
+                    width: cleanWidth,
+                    height: cleanHeight,
+                })) {
+                    throw new DeskError(`Policy denied opening a screen on desk ${record.deskId}.`);
+                }
+                touch(record);
+                await machine.request({ op: 'screen-start', width: cleanWidth, height: cleanHeight });
+                const handle = makeScreenHandle(record, epoch);
+                record.screen = {
+                    running: true,
+                    width: cleanWidth,
+                    height: cleanHeight,
+                    lastObservation: null,
+                    lastFocusedId: null,
+                    handover: null,
+                    handle,
+                };
+                emit(record, { kind: 'screen_open', width: cleanWidth, height: cleanHeight });
+                return handle;
+            },
+            async stop() {
+                const machine = requireMachine(record, epoch);
+                const screen = record.screen;
+                if (!screen?.running)
+                    return;
+                await endHandover(record, 'revoked');
+                for (const stop of [...record.streamStops])
+                    stop();
+                record.streamStops.clear();
+                screen.running = false;
+                record.screen = null;
+                touch(record);
+                await machine.request({ op: 'screen-stop' });
+                emit(record, { kind: 'screen_close' });
+            },
+            get running() {
+                return record.screen?.running === true;
+            },
+        };
+        return {
+            deskId: record.deskId,
+            renewLease(ms) {
+                requireMachine(record, epoch);
+                record.leaseDeadline = now() + positiveInteger(ms, 'ms');
+                touch(record);
+                armTimer(record);
+            },
+            exec: execImplementation,
+            jobs() {
+                return [...record.jobs.values()]
+                    .filter((job) => job.status === 'running')
+                    .map((job) => ({ ...job }));
+            },
+            screen: screenService,
+        };
+    }
+    function makeScreenHandle(record, epoch) {
+        async function sendInput(detail, input) {
+            const machine = requireMachine(record, epoch);
+            touch(record);
+            await machine.request({ op: 'input', input });
+            if (detail)
+                emit(record, detail);
+        }
+        return {
+            async observe() {
+                const machine = requireMachine(record, epoch);
+                const screen = requireScreen(record, epoch);
+                touch(record);
+                const observation = parseObservation(await machine.request({ op: 'observe' }));
+                screen.lastObservation = { width: observation.width, height: observation.height };
+                if (observation.focused && observation.focused.id !== screen.lastFocusedId) {
+                    screen.lastFocusedId = observation.focused.id;
+                    emit(record, { kind: 'window_focus', window: observation.focused });
+                }
+                return {
+                    png: Buffer.from(observation.png, 'base64'),
+                    width: observation.width,
+                    height: observation.height,
+                    a11y: observation.a11y,
+                    windows: observation.windows,
+                    focused: observation.focused,
+                };
+            },
+            input: {
+                async move(x, y) {
+                    requireScreen(record, epoch);
+                    assertCoordinates(record, [{ x, y }]);
+                    await sendInput(null, { type: 'move', x, y });
+                },
+                async click(x, y, button = 'left') {
+                    requireScreen(record, epoch);
+                    assertCoordinates(record, [{ x, y }]);
+                    await sendInput({ kind: 'click', x, y, button }, { type: 'click', x, y, button });
+                },
+                async type(text) {
+                    requireScreen(record, epoch);
+                    const cleanText = requireStringValue(text, 'text');
+                    await sendInput({ kind: 'type', text: cleanText }, { type: 'type', text: cleanText });
+                },
+                async key(combo) {
+                    requireScreen(record, epoch);
+                    const cleanCombo = nonEmptyString(combo, 'combo');
+                    await sendInput({ kind: 'key', combo: cleanCombo }, { type: 'key', combo: cleanCombo });
+                },
+                async scroll(x, y, dx, dy) {
+                    requireScreen(record, epoch);
+                    assertCoordinates(record, [{ x, y }]);
+                    if (!Number.isInteger(dx) || !Number.isInteger(dy)) {
+                        throw new DeskError('Scroll deltas must be integers.');
+                    }
+                    await sendInput({ kind: 'scroll', x, y, dx, dy }, { type: 'scroll', x, y, dx, dy });
+                },
+                async drag(from, to) {
+                    requireScreen(record, epoch);
+                    assertCoordinates(record, [from, to]);
+                    await sendInput({ kind: 'drag', from, to }, { type: 'drag', from, to });
+                },
+            },
+            a11y: {
+                async invoke(nodeId, action) {
+                    const machine = requireMachine(record, epoch);
+                    requireScreen(record, epoch);
+                    touch(record);
+                    await machine.request({
+                        op: 'a11y-invoke',
+                        nodeId: nonEmptyString(nodeId, 'nodeId'),
+                        action: nonEmptyString(action, 'action'),
+                    });
+                },
+            },
+            async launch(appId, args = []) {
+                const machine = requireMachine(record, epoch);
+                requireScreen(record, epoch);
+                touch(record);
+                const cleanAppId = nonEmptyString(appId, 'appId');
+                await machine.request({ op: 'launch', appId: cleanAppId, args: [...args] });
+                emit(record, { kind: 'app_launch', appId: cleanAppId, args: [...args] });
+            },
+            clipboard: {
+                async read() {
+                    const machine = requireMachine(record, epoch);
+                    const screen = requireScreen(record, epoch);
+                    if (screen.handover) {
+                        // The human may have just typed a credential that is now on the
+                        // clipboard; reading it during a handover would carry it into the
+                        // agent's context and the consumer's record.
+                        throw new DeskError('The clipboard is masked while a handover is active.');
+                    }
+                    touch(record);
+                    return parseClipboardText(await machine.request({ op: 'clipboard-read' }));
+                },
+                async write(text) {
+                    const machine = requireMachine(record, epoch);
+                    requireScreen(record, epoch);
+                    touch(record);
+                    await machine.request({ op: 'clipboard-write', text: requireStringValue(text, 'text') });
+                },
+            },
+            frames(frameOptions = {}) {
+                return {
+                    [Symbol.asyncIterator]: () => {
+                        const machine = requireMachine(record, epoch);
+                        const screen = requireScreen(record, epoch);
+                        const fps = positiveInteger(frameOptions.fps ?? 10, 'fps');
+                        const width = positiveInteger(frameOptions.width ?? screen.width, 'width');
+                        const height = positiveInteger(frameOptions.height ?? screen.height, 'height');
+                        const format = frameOptions.format;
+                        const buffered = [];
+                        let waiting = null;
+                        let finished = false;
+                        const unsubscribe = machine.subscribe((event) => {
+                            if (finished || event.event !== 'frame')
+                                return;
+                            // Masking contract: no frame reaches a recording consumer while
+                            // a handover is active.
+                            if (record.screen?.handover)
+                                return;
+                            const frame = {
+                                seq: event.seq,
+                                width: event.width,
+                                height: event.height,
+                                data: Buffer.from(event.data, 'base64'),
+                                format: event.format,
+                                at: iso(now()),
+                            };
+                            // A frame anchors coordinates exactly as an observation does.
+                            // The contract is that a click lands in the pixel space of the
+                            // most recent thing the caller was SHOWN, and a live view is
+                            // shown the frame stream, not observe(). Without this a viewer
+                            // that watches frames and clicks what it sees is refused for
+                            // never having called observe() — technically true and useless.
+                            if (record.screen) {
+                                record.screen.lastObservation = { width: frame.width, height: frame.height };
+                            }
+                            if (waiting) {
+                                const resume = waiting;
+                                waiting = null;
+                                resume({ value: frame, done: false });
+                            }
+                            else {
+                                buffered.push(frame);
+                                if (buffered.length > MAX_BUFFERED_FRAMES)
+                                    buffered.shift();
+                            }
+                        });
+                        const finish = () => {
+                            if (finished)
+                                return;
+                            finished = true;
+                            unsubscribe();
+                            record.streamStops.delete(finish);
+                            if (record.status === 'resident' && record.machine) {
+                                record.machine.request({ op: 'frames-stop' }).catch((error) => {
+                                    lastError = errorMessage(error);
+                                });
+                            }
+                            if (waiting) {
+                                const resume = waiting;
+                                waiting = null;
+                                resume({ value: undefined, done: true });
+                            }
+                        };
+                        record.streamStops.add(finish);
+                        const started = machine
+                            .request({ op: 'frames-start', fps, width, height, format })
+                            .catch((error) => {
+                            finish();
+                            throw error instanceof Error ? error : new Error(String(error));
+                        });
+                        return {
+                            async next() {
+                                await started;
+                                const bufferedFrame = buffered.shift();
+                                if (bufferedFrame)
+                                    return { value: bufferedFrame, done: false };
+                                if (finished)
+                                    return { value: undefined, done: true };
+                                return new Promise((resolvePromise) => {
+                                    waiting = resolvePromise;
+                                });
+                            },
+                            async return() {
+                                finish();
+                                return { value: undefined, done: true };
+                            },
+                            async throw(error) {
+                                finish();
+                                throw error instanceof Error ? error : new Error(String(error));
+                            },
+                        };
+                    },
+                };
+            },
+            video(videoOptions = {}) {
+                return {
+                    [Symbol.asyncIterator]: () => {
+                        const machine = requireMachine(record, epoch);
+                        const screen = requireScreen(record, epoch);
+                        const fps = positiveInteger(videoOptions.fps ?? 30, 'fps');
+                        const width = positiveInteger(videoOptions.width ?? screen.width, 'width');
+                        const height = positiveInteger(videoOptions.height ?? screen.height, 'height');
+                        const buffered = [];
+                        let waiting = null;
+                        let finished = false;
+                        const unsubscribe = machine.subscribe((event) => {
+                            if (finished || event.event !== 'video-chunk')
+                                return;
+                            // The same masking contract frames are held to: while a handover
+                            // is active a person is on that screen, and nothing derived from
+                            // watching them may reach a recording consumer.
+                            if (record.screen?.handover)
+                                return;
+                            const chunk = {
+                                seq: event.seq,
+                                kind: event.kind,
+                                codec: event.codec,
+                                width: event.width,
+                                height: event.height,
+                                keyframe: event.keyframe,
+                                data: Buffer.from(event.data, 'base64'),
+                                at: iso(now()),
+                            };
+                            // A video chunk anchors coordinates exactly as a frame does, and
+                            // for the same reason: a viewer driving by video is aiming at the
+                            // pixel space the video showed it. Anchoring on every chunk, not
+                            // only the first, is what re-asserts the space when the encoder
+                            // restarts at a new resolution.
+                            if (record.screen) {
+                                record.screen.lastObservation = { width: chunk.width, height: chunk.height };
+                            }
+                            if (waiting) {
+                                const resume = waiting;
+                                waiting = null;
+                                resume({ value: chunk, done: false });
+                            }
+                            else {
+                                buffered.push(chunk);
+                                // Dropping the OLDEST would drop the init segment, and a
+                                // consumer without it decodes nothing at all — so an overrun
+                                // ends the stream instead. A caller that cannot keep up with a
+                                // video stream is one that should re-subscribe and be resynced
+                                // from a keyframe, not one that should be handed a hole.
+                                if (buffered.length > MAX_BUFFERED_VIDEO_CHUNKS)
+                                    finish();
+                            }
+                        });
+                        const finish = () => {
+                            if (finished)
+                                return;
+                            finished = true;
+                            unsubscribe();
+                            record.streamStops.delete(finish);
+                            if (record.status === 'resident' && record.machine) {
+                                record.machine.request({ op: 'video-stop' }).catch((error) => {
+                                    lastError = errorMessage(error);
+                                });
+                            }
+                            if (waiting) {
+                                const resume = waiting;
+                                waiting = null;
+                                resume({ value: undefined, done: true });
+                            }
+                        };
+                        record.streamStops.add(finish);
+                        const started = machine
+                            .request({ op: 'video-start', fps, width, height })
+                            .catch((error) => {
+                            finish();
+                            throw error instanceof Error ? error : new Error(String(error));
+                        });
+                        return {
+                            async next() {
+                                await started;
+                                const bufferedChunk = buffered.shift();
+                                if (bufferedChunk)
+                                    return { value: bufferedChunk, done: false };
+                                if (finished)
+                                    return { value: undefined, done: true };
+                                return new Promise((resolvePromise) => {
+                                    waiting = resolvePromise;
+                                });
+                            },
+                            async return() {
+                                finish();
+                                return { value: undefined, done: true };
+                            },
+                            async throw(error) {
+                                finish();
+                                throw error instanceof Error ? error : new Error(String(error));
+                            },
+                        };
+                    },
+                };
+            },
+            handover: {
+                async begin({ ttlMs, scope = 'control', actor }) {
+                    const machine = requireMachine(record, epoch);
+                    const screen = requireScreen(record, epoch);
+                    if (screen.handover) {
+                        throw new DeskError(`A handover is already active on desk ${record.deskId}.`);
+                    }
+                    const cleanTtl = positiveInteger(ttlMs, 'ttlMs');
+                    if (ports.policy?.allowHandover && !ports.policy.allowHandover({
+                        deskId: record.deskId,
+                        scope,
+                        ttlMs: cleanTtl,
+                    })) {
+                        throw new DeskError(`Policy denied a handover on desk ${record.deskId}.`);
+                    }
+                    touch(record);
+                    const begun = parseHandoverBegun(await machine.request({ op: 'handover-begin', ttlMs: cleanTtl, scope }));
+                    const startedAt = now();
+                    screen.handover = {
+                        actor: actor ?? null,
+                        scope,
+                        beganAt: startedAt,
+                        deadline: startedAt + cleanTtl,
+                    };
+                    // The boundary events are the one thing that crosses the mask.
+                    emit(record, { kind: 'handover_begin', actor: actor ?? null, scope });
+                    ports.audit({
+                        kind: 'handover_begin',
+                        deskId: record.deskId,
+                        actor: actor ?? null,
+                        scope,
+                        ttlMs: cleanTtl,
+                        at: iso(startedAt),
+                    });
+                    armTimer(record);
+                    return { url: begun.url };
+                },
+                async end() {
+                    requireMachine(record, epoch);
+                    await endHandover(record, 'ended');
+                },
+                get active() {
+                    return record.screen?.handover != null;
+                },
+            },
+        };
+    }
+    async function start(startOptions) {
+        const deskId = cleanDeskId(startOptions.deskId);
+        const existing = records.get(deskId);
+        if (existing?.status === 'resident' && existing.handle)
+            return existing.handle;
+        return admit(() => boot(deskId, { ...startOptions, deskId }));
+    }
+    async function resume(deskId) {
+        const record = records.get(cleanDeskId(deskId));
+        if (!record)
+            throw new DeskError(`Unknown desk: ${deskId}`);
+        if (record.status === 'resident' && record.handle)
+            return record.handle;
+        return admit(() => boot(record.deskId, record.startOptions));
+    }
+    async function suspend(deskId) {
+        const record = records.get(cleanDeskId(deskId));
+        if (!record)
+            return;
+        await teardown(record);
+    }
+    async function destroy(deskId) {
+        const id = cleanDeskId(deskId);
+        const record = records.get(id);
+        if (!record)
+            return;
+        await teardown(record);
+        records.delete(id);
+    }
+    async function sweep() {
+        const timestamp = now();
+        let suspendedCount = 0;
+        for (const record of [...records.values()]) {
+            if (record.status !== 'resident')
+                continue;
+            const handover = record.screen?.handover;
+            if (handover && handover.deadline <= timestamp) {
+                await endHandover(record, 'expired');
+            }
+            if (record.leaseDeadline <= timestamp
+                || timestamp - record.lastActivityAt >= idleSuspendMs) {
+                await teardown(record);
+                suspendedCount += 1;
+            }
+        }
+        return suspendedCount;
+    }
+    function stats() {
+        let suspended = 0;
+        for (const record of records.values()) {
+            if (record.status === 'suspended')
+                suspended += 1;
+        }
+        return {
+            resident: occupied,
+            queued: queue.length,
+            capacity,
+            suspended,
+            lastStartedAt,
+            lastSuspendedAt,
+            reconnects,
+            lastReconnectAt,
+            lastReconnectDeskId,
+            lastError,
+        };
+    }
+    return { start, resume, suspend, destroy, stats, sweep };
+}
+/**
+ * Boot-time probe. Distinguishes a host that is unusable — wrong platform,
+ * missing VMM, missing images — which throws, from capabilities that are
+ * merely absent, which are reported as booleans: `kvm` (no boot possible
+ * without it), `vsock` (the guest agent answered), and `virtioGpu` (a screen
+ * would have hardware-backed rendering). It boots a throwaway microVM through
+ * the backend, asks it two questions, and discards it.
+ */
+export async function verifyDeskHost(options) {
+    const platform = options.platform ?? process.platform;
+    const pathExists = options.pathExists ?? existsSync;
+    const deviceExists = options.deviceExists ?? existsSync;
+    const idFactory = options.idFactory ?? randomUUID;
+    const backend = options.backend ?? cloudHypervisorBackend;
+    const vmmPath = options.vmmPath ?? DEFAULT_VMM_PATH;
+    const kvmPath = options.kvmPath ?? DEFAULT_KVM_PATH;
+    if (platform !== 'linux') {
+        throw new DeskError(`The AppKit desk requires Linux; received ${platform}.`);
+    }
+    if (!pathExists(vmmPath)) {
+        throw new DeskError(`Cloud Hypervisor was not found at ${vmmPath}.`);
+    }
+    if (!pathExists(options.kernelPath)) {
+        throw new DeskError(`Guest kernel does not exist: ${options.kernelPath}`);
+    }
+    if (!pathExists(options.baseImagePath)) {
+        throw new DeskError(`Base image does not exist: ${options.baseImagePath}`);
+    }
+    if (!deviceExists(kvmPath)) {
+        return { supported: false, vmmPath, kvm: false, vsock: false, virtioGpu: false };
+    }
+    const scratchDir = options.scratchDir ?? tmpdir();
+    const deskId = `verify-${idFactory()}`;
+    const overlayPath = join(scratchDir, `${deskId}.raw`);
+    const plan = buildDeskLaunchPlan({
+        deskId,
+        vmmPath,
+        kvmPath,
+        kernelPath: options.kernelPath,
+        ...(options.initramfsPath === undefined ? {} : { initramfsPath: options.initramfsPath }),
+        ...(options.kernelCmdline === undefined ? {} : { kernelCmdline: options.kernelCmdline }),
+        baseImagePath: options.baseImagePath,
+        overlayPath,
+        vsockCid: 3,
+        runtimeDir: options.runtimeDir,
+        launcherIdentity: options.launcherIdentity,
+    }, { pathExists, deviceExists });
+    let machine;
+    try {
+        machine = await backend.boot(plan);
+    }
+    catch (error) {
+        throw new DeskError(`Desk verification could not boot a probe VM: ${errorMessage(error)}`);
+    }
+    let vsock = false;
+    let virtioGpu = false;
+    try {
+        try {
+            await machine.request({ op: 'ping' });
+            vsock = true;
+        }
+        catch {
+            vsock = false;
+        }
+        if (vsock) {
+            try {
+                virtioGpu = parseCapabilities(await machine.request({ op: 'capabilities' })).virtioGpu;
+            }
+            catch {
+                virtioGpu = false;
+            }
+        }
+    }
+    finally {
+        try {
+            await machine.shutdown();
+        }
+        catch {
+            // The probe VM is discarded regardless of how cleanly it stops.
+        }
+        await rm(overlayPath, { force: true });
+    }
+    return { supported: vsock, vmmPath, kvm: true, vsock, virtioGpu };
+}
+function nonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new DeskError(`${field} must be a non-empty string.`);
+    }
+    return value;
+}
+function requireStringValue(value, field) {
+    if (typeof value !== 'string') {
+        throw new DeskError(`${field} must be a string.`);
+    }
+    return value;
+}
+function positiveInteger(value, field) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new DeskError(`${field} must be a positive integer.`);
+    }
+    return value;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=host.js.map