@xingular/harness 1.3.1-unstable.3 → 1.3.1-unstable.4

package/dist/sdk/cli.js

@@ -52,6 +52,8 @@ Standalone terminal options:
                      Start in a new managed worktree of this repository, or in
                      the named one
   --variant <scope>  Run on this variant scope's head (default: interactive profile scope)
+  --remote-control, --rc
+                     Turn on /remote-control at start, to continue from a phone or iPad
 `;
 function flags(argv) {
     const values = {};

package/dist/sdk/commands/registry.d.ts

@@ -69,6 +69,14 @@ export declare const CORE_COMMANDS: readonly [{
     readonly group: "Session";
     readonly kind: "session";
     readonly methods: readonly ["sessions.tree", "sessions.fork"];
+}, {
+    readonly name: "remote-control";
+    readonly aliases: readonly ["rc"];
+    readonly args: "[off|tailscale|lan]";
+    readonly description: "Continue this session from your phone or iPad";
+    readonly group: "Session";
+    readonly kind: "page";
+    readonly methods: readonly ["terminal.remoteControl.start", "terminal.remoteControl.stop", "terminal.remoteControl.status"];
 }, {
     readonly name: "clone";
     readonly description: "Clone this branch into a new session";
@@ -228,6 +236,13 @@ export declare const CORE_COMMANDS: readonly [{
     readonly description: "Harness diagnostics and this conversation's run events";
     readonly group: "Inspect";
     readonly kind: "page";
+}, {
+    readonly name: "context";
+    readonly args: "[growth]";
+    readonly description: "What the latest request was made of, and where the rest of the window went";
+    readonly group: "Inspect";
+    readonly kind: "page";
+    readonly methods: readonly ["context.attribution"];
 }, {
     readonly name: "hotkeys";
     readonly description: "Keyboard controls";

package/dist/sdk/commands/registry.js

@@ -10,6 +10,7 @@ export const CORE_COMMANDS = [
     { name: 'session', aliases: ['resume'], args: '[path]', description: 'Choose a saved session in this account and folder', group: 'Session', kind: 'session' },
     { name: 'history', aliases: ['tree'], description: 'Navigate branches in the current session', group: 'Session', kind: 'session', methods: ['sessions.tree', 'sessions.navigate'] },
     { name: 'fork', description: 'Fork from an earlier message', group: 'Session', kind: 'session', methods: ['sessions.tree', 'sessions.fork'] },
+    { name: 'remote-control', aliases: ['rc'], args: '[off|tailscale|lan]', description: 'Continue this session from your phone or iPad', group: 'Session', kind: 'page', methods: ['terminal.remoteControl.start', 'terminal.remoteControl.stop', 'terminal.remoteControl.status'] },
     { name: 'clone', description: 'Clone this branch into a new session', group: 'Session', kind: 'session', methods: ['sessions.clone'] },
     { name: 'model', args: '[search]', description: 'Choose the model', group: 'Model', kind: 'session', methods: ['accounts.models'] },
     { name: 'effort', args: '[level]', description: 'Choose the thinking effort', group: 'Model', kind: 'session' },
@@ -37,6 +38,7 @@ export const CORE_COMMANDS = [
     { name: 'subagents', description: 'Watch current subagent tasks and activity', group: 'Harness', kind: 'page' },
     { name: 'agents', description: 'Browse and edit agent profiles', group: 'Harness', kind: 'page', methods: ['agents.list'] },
     { name: 'log', description: "Harness diagnostics and this conversation's run events", group: 'Inspect', kind: 'page' },
+    { name: 'context', args: '[growth]', description: 'What the latest request was made of, and where the rest of the window went', group: 'Inspect', kind: 'page', methods: ['context.attribution'] },
     { name: 'hotkeys', description: 'Keyboard controls', group: 'Core', kind: 'local' },
     { name: 'quit', description: 'Restore the terminal and exit', group: 'Core', kind: 'local' }
 ];

package/dist/sdk/remote/addresses.d.ts

@@ -0,0 +1,19 @@
+import { type NetworkInterfaceInfo } from 'node:os';
+export type RemoteAddressKind = 'tailscale' | 'lan';
+export type RemoteInterfaceChoice = 'auto' | RemoteAddressKind;
+export interface RemoteAddress {
+    kind: RemoteAddressKind;
+    address: string;
+    family: 'IPv4' | 'IPv6';
+    interface: string;
+}
+/** Tailscale hands out 100.64.0.0/10 and fd7a:115c:a1e0::/48. */
+export declare function isTailscale(address: string): boolean;
+/** RFC 1918 private IPv4 ranges. */
+export declare function isPrivateLan(address: string): boolean;
+/** Every address remote control may bind, Tailscale first. */
+export declare function remoteAddresses(interfaces?: NodeJS.Dict<NetworkInterfaceInfo[]>): RemoteAddress[];
+/** The one address to listen on for a choice, or a clear error when there is none. */
+export declare function pickRemoteAddress(choice: RemoteInterfaceChoice, candidates: readonly RemoteAddress[]): RemoteAddress;
+/** How a URL names the address. */
+export declare function hostPart(address: RemoteAddress): string;

package/dist/sdk/remote/addresses.js

@@ -0,0 +1,52 @@
+// Where remote control may listen: a Tailscale address or a private LAN address, never a public
+// one, never every interface (INV-RC-1).
+import { networkInterfaces } from 'node:os';
+import { HarnessError } from "../core/errors.js";
+const octets = (address) => address.split('.').map(Number);
+/** Tailscale hands out 100.64.0.0/10 and fd7a:115c:a1e0::/48. */
+export function isTailscale(address) {
+    if (address.includes(':'))
+        return address.toLowerCase().startsWith('fd7a:115c:a1e0:');
+    const [a, b] = octets(address);
+    return a === 100 && b >= 64 && b <= 127;
+}
+/** RFC 1918 private IPv4 ranges. */
+export function isPrivateLan(address) {
+    if (address.includes(':'))
+        return false;
+    const [a, b] = octets(address);
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+}
+/** Every address remote control may bind, Tailscale first. */
+export function remoteAddresses(interfaces = networkInterfaces()) {
+    const found = [];
+    for (const [name, entries] of Object.entries(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.internal)
+                continue;
+            const family = entry.family === 'IPv6' ? 'IPv6' : 'IPv4';
+            if (isTailscale(entry.address))
+                found.push({ kind: 'tailscale', address: entry.address, family, interface: name });
+            else if (isPrivateLan(entry.address))
+                found.push({ kind: 'lan', address: entry.address, family, interface: name });
+        }
+    }
+    // IPv4 first within a kind: it is what a person can type and what every phone resolves.
+    const rank = (address) => (address.kind === 'tailscale' ? 0 : 2) + (address.family === 'IPv4' ? 0 : 1);
+    return found.sort((a, b) => rank(a) - rank(b));
+}
+/** The one address to listen on for a choice, or a clear error when there is none. */
+export function pickRemoteAddress(choice, candidates) {
+    const pick = choice === 'auto' ? candidates[0] : candidates.find((candidate) => candidate.kind === choice);
+    if (pick)
+        return pick;
+    if (choice === 'tailscale')
+        throw new HarnessError('remote_unavailable', 'No Tailscale address found. Start Tailscale on this computer, or use the Wi-Fi address instead.');
+    if (choice === 'lan')
+        throw new HarnessError('remote_unavailable', 'No private Wi-Fi or LAN address found. Join a network, or use Tailscale instead.');
+    throw new HarnessError('remote_unavailable', 'No Tailscale or private network address found. Join a Wi-Fi network or start Tailscale, then try /remote-control again.');
+}
+/** How a URL names the address. */
+export function hostPart(address) {
+    return address.family === 'IPv6' ? `[${address.address}]` : address.address;
+}

package/dist/sdk/remote/pairing.d.ts

@@ -0,0 +1,59 @@
+import { ReplayGuard } from "./seal.js";
+export declare const MAX_DEVICES = 3;
+/** Under a minute: a phone's browser gives up on a request it waits on much longer. */
+export declare const CONFIRM_MS = 50000;
+export interface RemoteDevice {
+    id: string;
+    label: string;
+    key: Uint8Array;
+    pairedAt: number;
+    lastSeen: number;
+    /** The counters this device has sent. */
+    replay: ReplayGuard;
+    /** The counter of the last frame sent to it. */
+    lastOut: number;
+}
+export interface PairRequest {
+    id: string;
+    label: string;
+    at: number;
+}
+/** A short, printable name for a browser from its user agent. Nothing from the phone is trusted. */
+export declare function deviceLabel(userAgent: unknown): string;
+export declare class Pairing {
+    private readonly changed;
+    private readonly clock;
+    private link;
+    private linkReplay;
+    private pending;
+    private readonly devices;
+    private hellos;
+    private failures;
+    private notice;
+    constructor(changed?: () => void, clock?: () => number);
+    private newLink;
+    /** What follows `#` in the pairing URL. */
+    get fragment(): string;
+    get request(): PairRequest | null;
+    /** A warning for the terminal page, such as a link replaced after repeated bad attempts. */
+    get warning(): string | null;
+    list(): RemoteDevice[];
+    device(deviceId: string): RemoteDevice | null;
+    /** A new link; every paired device is dropped and a waiting request denied. */
+    rotate(): void;
+    forget(deviceId: string): void;
+    /** The person at the terminal allowed or refused a waiting request. */
+    confirm(requestId: string, allow: boolean): void;
+    private fail;
+    /**
+     * A phone opened the pairing link. Waits until the person at the terminal decides, then returns
+     * the device's id and key, sealed with the link key.
+     */
+    hello(pairingId: unknown, frame: unknown, confirmMs?: number): Promise<string>;
+    /** Opens a paired device's frame, enforcing its counter. */
+    openFrom<T = unknown>(deviceId: unknown, frame: unknown): {
+        device: RemoteDevice;
+        body: T;
+    };
+    sealFor(device: RemoteDevice, body: unknown): string;
+}

package/dist/sdk/remote/pairing.js

@@ -0,0 +1,160 @@
+// Pairing for remote control. The QR code carries a pairing link: an id and a key, in the URL's
+// fragment. A phone that opens it says hello, sealed with that key; the person at the terminal
+// confirms; the phone receives its own device key. A link pairs one device and is then replaced,
+// so the QR on screen always pairs the next one. Every key lives in memory only (INV-RC-2).
+import { randomBytes } from 'node:crypto';
+import { HarnessError } from "../core/errors.js";
+import { encode, newKey, open, ReplayGuard, sameSecret, seal } from "./seal.js";
+export const MAX_DEVICES = 3;
+const HELLO_WINDOW_MS = 60_000;
+const MAX_HELLOS = 10;
+const MAX_FAILURES = 20;
+/** Under a minute: a phone's browser gives up on a request it waits on much longer. */
+export const CONFIRM_MS = 50_000;
+/** A short, printable name for a browser from its user agent. Nothing from the phone is trusted. */
+export function deviceLabel(userAgent) {
+    const ua = typeof userAgent === 'string' ? userAgent.slice(0, 400) : '';
+    const device = /iPad/.test(ua) ? 'iPad'
+        : /iPhone/.test(ua) ? 'iPhone'
+            : /Android/.test(ua) ? 'Android'
+                : /Macintosh|Mac OS X/.test(ua) ? (/Mobile/.test(ua) ? 'iPad' : 'Mac')
+                    : /Windows/.test(ua) ? 'Windows'
+                        : /Linux/.test(ua) ? 'Linux' : 'Browser';
+    const browser = /EdgiOS|EdgA|Edg\//.test(ua) ? 'Edge'
+        : /CriOS|Chrome\//.test(ua) ? 'Chrome'
+            : /FxiOS|Firefox\//.test(ua) ? 'Firefox'
+                : /Safari\//.test(ua) ? 'Safari' : '';
+    return browser ? `${device} · ${browser}` : device;
+}
+const id = () => randomBytes(12).toString('base64url');
+export class Pairing {
+    changed;
+    clock;
+    link = { id: id(), key: newKey() };
+    linkReplay = new ReplayGuard();
+    pending = null;
+    devices = new Map();
+    hellos = [];
+    failures = 0;
+    notice = null;
+    constructor(changed = () => { }, clock = Date.now) {
+        this.changed = changed;
+        this.clock = clock;
+    }
+    newLink() {
+        this.link = { id: id(), key: newKey() };
+        this.linkReplay = new ReplayGuard();
+    }
+    /** What follows `#` in the pairing URL. */
+    get fragment() {
+        return `${this.link.id}.${encode(this.link.key)}`;
+    }
+    get request() {
+        return this.pending ? { id: this.pending.id, label: this.pending.label, at: this.pending.at } : null;
+    }
+    /** A warning for the terminal page, such as a link replaced after repeated bad attempts. */
+    get warning() {
+        return this.notice;
+    }
+    list() {
+        return [...this.devices.values()];
+    }
+    device(deviceId) {
+        for (const [known, device] of this.devices)
+            if (sameSecret(known, deviceId))
+                return device;
+        return null;
+    }
+    /** A new link; every paired device is dropped and a waiting request denied. */
+    rotate() {
+        this.newLink();
+        this.pending?.decide(false);
+        this.pending = null;
+        this.devices.clear();
+        this.failures = 0;
+        this.notice = null;
+        this.changed();
+    }
+    forget(deviceId) {
+        const device = this.device(deviceId);
+        if (device && this.devices.delete(device.id))
+            this.changed();
+    }
+    /** The person at the terminal allowed or refused a waiting request. */
+    confirm(requestId, allow) {
+        if (!this.pending || this.pending.id !== requestId)
+            throw new HarnessError('invalid_request', 'This pairing request is no longer waiting.');
+        this.pending.decide(allow);
+    }
+    fail() {
+        this.failures += 1;
+        if (this.failures >= MAX_FAILURES) {
+            this.newLink();
+            this.failures = 0;
+            this.notice = 'Too many failed pairing attempts. The link was replaced; scan the new QR code.';
+            this.changed();
+        }
+        return new HarnessError('unauthorized', 'This pairing link is not valid. Scan the QR code in the terminal again.');
+    }
+    /**
+     * A phone opened the pairing link. Waits until the person at the terminal decides, then returns
+     * the device's id and key, sealed with the link key.
+     */
+    async hello(pairingId, frame, confirmMs = CONFIRM_MS) {
+        const at = this.clock();
+        this.hellos = this.hellos.filter((time) => at - time < HELLO_WINDOW_MS);
+        if (this.hellos.length >= MAX_HELLOS)
+            throw new HarnessError('rate_limited', 'Too many pairing attempts. Wait a minute and try again.');
+        this.hellos.push(at);
+        if (typeof pairingId !== 'string' || typeof frame !== 'string' || !sameSecret(pairingId, this.link.id))
+            throw this.fail();
+        const link = this.link;
+        let body;
+        try {
+            body = open(link.key, frame, (n) => this.linkReplay.accept(n)).body ?? {};
+        }
+        catch {
+            throw this.fail();
+        }
+        if (this.pending)
+            throw new HarnessError('remote_busy', 'Another device is waiting for approval in the terminal.');
+        if (this.devices.size >= MAX_DEVICES)
+            throw new HarnessError('remote_full', `At most ${MAX_DEVICES} devices can control a session. Press n in /remote-control to start over.`);
+        const label = deviceLabel(body.userAgent);
+        const allowed = await new Promise((resolve) => {
+            const timer = setTimeout(() => decide(false), confirmMs);
+            timer.unref?.();
+            const decide = (allow) => {
+                clearTimeout(timer);
+                if (this.pending?.decide === decide)
+                    this.pending = null;
+                resolve(allow);
+                this.changed();
+            };
+            this.pending = { id: id(), label, at, decide };
+            this.changed();
+        });
+        // A rotation while the phone waited replaced this link; its request is void.
+        if (!allowed || this.link !== link)
+            throw new HarnessError('remote_denied', 'Pairing was not allowed at the terminal.');
+        const device = { id: id(), label, key: newKey(), pairedAt: this.clock(), lastSeen: this.clock(), replay: new ReplayGuard(), lastOut: 0 };
+        this.devices.set(device.id, device);
+        // The link paired its device; the QR on screen now pairs the next one.
+        this.newLink();
+        this.changed();
+        return seal(link.key, 1, { deviceId: device.id, deviceKey: encode(device.key), label });
+    }
+    /** Opens a paired device's frame, enforcing its counter. */
+    openFrom(deviceId, frame) {
+        const device = typeof deviceId === 'string' ? this.device(deviceId) : null;
+        if (!device || typeof frame !== 'string')
+            throw new HarnessError('unauthorized', 'This device is not paired with the session. Scan the QR code in the terminal again.');
+        const opened = open(device.key, frame, (n) => device.replay.accept(n));
+        device.lastSeen = this.clock();
+        return { device, body: opened.body };
+    }
+    sealFor(device, body) {
+        device.lastOut += 1;
+        return seal(device.key, device.lastOut, body);
+    }
+}

package/dist/sdk/remote/seal.d.ts

@@ -0,0 +1,28 @@
+export declare const KEY_BYTES: number;
+/** How far behind the highest counter a frame may arrive, for requests a phone sent at once. */
+export declare const REPLAY_WINDOW = 256;
+export interface Opened<T> {
+    n: number;
+    body: T;
+}
+export declare function newKey(): Uint8Array;
+/** URL-safe base64 without padding: it travels in fragments, query strings and SSE lines. */
+export declare function encode(bytes: Uint8Array): string;
+export declare function decode(text: string): Uint8Array;
+export declare function seal(key: Uint8Array, n: number, body: unknown): string;
+/**
+ * Opens a frame and asks `fresh` whether its counter is new. A frame that fails here is a wrong
+ * key, a tampered body, or a replay; callers answer all three the same way.
+ */
+export declare function open<T = unknown>(key: Uint8Array, frame: string, fresh: (n: number) => boolean): Opened<T>;
+/**
+ * Remembers the counters a sender used: a counter is fresh when it is above the highest seen, or
+ * within the window below it and not seen before.
+ */
+export declare class ReplayGuard {
+    private highest;
+    private readonly recent;
+    accept(n: number): boolean;
+}
+/** Compares two identifiers without leaking how much of them matched. */
+export declare function sameSecret(a: string, b: string): boolean;

package/dist/sdk/remote/seal.js

@@ -0,0 +1,84 @@
+// Sealed frames for remote control. A LAN page is served over plain HTTP, where the browser has no
+// WebCrypto and anyone on the Wi-Fi can read traffic, so every body is a NaCl secretbox
+// (XSalsa20-Poly1305) under a key the phone got from the QR code's fragment, which a browser never
+// sends. A random 24-byte nonce per frame; the counter inside the frame stops replays.
+import { timingSafeEqual } from 'node:crypto';
+import nacl from 'tweetnacl';
+import { HarnessError } from "../core/errors.js";
+export const KEY_BYTES = nacl.secretbox.keyLength;
+/** How far behind the highest counter a frame may arrive, for requests a phone sent at once. */
+export const REPLAY_WINDOW = 256;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function newKey() {
+    return nacl.randomBytes(KEY_BYTES);
+}
+/** URL-safe base64 without padding: it travels in fragments, query strings and SSE lines. */
+export function encode(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+export function decode(text) {
+    return new Uint8Array(Buffer.from(text, 'base64url'));
+}
+export function seal(key, n, body) {
+    const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
+    const box = nacl.secretbox(encoder.encode(JSON.stringify({ n, body })), nonce, key);
+    const frame = new Uint8Array(nonce.length + box.length);
+    frame.set(nonce);
+    frame.set(box, nonce.length);
+    return encode(frame);
+}
+const rejected = () => new HarnessError('unauthorized', 'This remote-control frame could not be opened.');
+/**
+ * Opens a frame and asks `fresh` whether its counter is new. A frame that fails here is a wrong
+ * key, a tampered body, or a replay; callers answer all three the same way.
+ */
+export function open(key, frame, fresh) {
+    if (typeof frame !== 'string' || frame.length > 1_500_000)
+        throw rejected();
+    const bytes = decode(frame);
+    const nonceLength = nacl.secretbox.nonceLength;
+    if (bytes.length <= nonceLength + nacl.secretbox.overheadLength)
+        throw rejected();
+    const plain = nacl.secretbox.open(bytes.subarray(nonceLength), bytes.subarray(0, nonceLength), key);
+    if (!plain)
+        throw rejected();
+    let value;
+    try {
+        value = JSON.parse(decoder.decode(plain));
+    }
+    catch {
+        throw rejected();
+    }
+    if (typeof value.n !== 'number' || !Number.isSafeInteger(value.n) || value.n < 1 || !fresh(value.n))
+        throw rejected();
+    return { n: value.n, body: value.body };
+}
+/**
+ * Remembers the counters a sender used: a counter is fresh when it is above the highest seen, or
+ * within the window below it and not seen before.
+ */
+export class ReplayGuard {
+    highest = 0;
+    recent = new Set();
+    accept(n) {
+        if (n > this.highest) {
+            this.highest = n;
+            this.recent.add(n);
+            for (const seen of this.recent)
+                if (seen <= n - REPLAY_WINDOW)
+                    this.recent.delete(seen);
+            return true;
+        }
+        if (n <= this.highest - REPLAY_WINDOW || this.recent.has(n))
+            return false;
+        this.recent.add(n);
+        return true;
+    }
+}
+/** Compares two identifiers without leaking how much of them matched. */
+export function sameSecret(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}

package/dist/sdk/remote/server.d.ts

@@ -0,0 +1,28 @@
+export interface RemoteAsset {
+    type: string;
+    body: string;
+}
+export interface RemoteStream {
+    /** Sends one sealed frame as an SSE message. */
+    send(frame: string): void;
+    end(): void;
+}
+export interface RemoteRoutes {
+    /** The page and its scripts, by path. */
+    asset(path: string): RemoteAsset | null;
+    hello(body: Record<string, unknown>): Promise<{
+        f: string;
+    }>;
+    call(body: Record<string, unknown>): Promise<{
+        f: string;
+    }>;
+    /** Opens a stream for a paired device; returns what to run when the phone hangs up. */
+    stream(deviceId: string, frame: string, stream: RemoteStream): () => void;
+}
+export interface RemoteListening {
+    host: string;
+    port: number;
+    close(): Promise<void>;
+}
+/** Starts the server on one address. `port` 0 picks a free one. */
+export declare function listenRemote(host: string, port: number, routes: RemoteRoutes): Promise<RemoteListening>;

package/dist/sdk/remote/server.js

@@ -0,0 +1,158 @@
+// The remote-control HTTP server: the phone page, pairing, sealed calls and a sealed event stream.
+// It listens on exactly one private or Tailscale address (INV-RC-1). Bodies are sealed (seal.ts),
+// so this layer only checks the Host and Origin, caps sizes, and routes.
+import { createServer } from 'node:http';
+import { HarnessError, toErrorShape } from "../core/errors.js";
+const MAX_HELLO = 64_000;
+const MAX_CALL = 1_200_000;
+const PING_MS = 15_000;
+const HEADERS = {
+    'cache-control': 'no-store',
+    'referrer-policy': 'no-referrer',
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'DENY',
+    'cross-origin-resource-policy': 'same-origin'
+};
+const CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; manifest-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+const STATUS = { unauthorized: 401, remote_denied: 403, rate_limited: 429, remote_busy: 409, remote_full: 409, session_busy: 409, terminal_has_draft: 409, too_large: 413, not_found: 404 };
+function reply(response, status, body) {
+    response.writeHead(status, { ...HEADERS, 'content-type': 'application/json; charset=utf-8' });
+    response.end(JSON.stringify(body));
+}
+function failure(response, error) {
+    const shape = toErrorShape(error);
+    reply(response, STATUS[shape.code] ?? 400, { error: { code: shape.code, message: shape.message } });
+}
+async function readBody(request, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > limit)
+            throw new HarnessError('too_large', 'This message is too large.');
+        chunks.push(chunk);
+    }
+    try {
+        const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            return value;
+    }
+    catch { }
+    throw new HarnessError('invalid_request', 'The request is not JSON.');
+}
+/** Starts the server on one address. `port` 0 picks a free one. */
+export async function listenRemote(host, port, routes) {
+    const sockets = new Set();
+    const streams = new Set();
+    let authority = '';
+    const handle = async (request, response) => {
+        // A page on another site cannot reach this server through DNS it controls (rebinding), and no
+        // other origin may post to it.
+        if (request.headers.host !== authority)
+            return reply(response, 421, { error: { code: 'wrong_host', message: 'Open the link shown in the terminal.' } });
+        const origin = request.headers.origin;
+        if (origin !== undefined && origin !== `http://${authority}`)
+            return reply(response, 403, { error: { code: 'wrong_origin', message: 'Requests from other sites are refused.' } });
+        const url = new URL(request.url ?? '/', `http://${authority}`);
+        if (request.method === 'GET' && url.pathname === '/rc/events') {
+            const deviceId = url.searchParams.get('d') ?? '';
+            const frame = url.searchParams.get('f') ?? '';
+            let ended = false;
+            let opened = false;
+            let ping = null;
+            // The route sends its first frame as the stream opens, so the headers go out with it.
+            const begin = () => {
+                if (opened)
+                    return;
+                opened = true;
+                response.writeHead(200, { ...HEADERS, 'content-type': 'text/event-stream; charset=utf-8', connection: 'keep-alive' });
+                response.write(': open\n\n');
+            };
+            const stream = {
+                send: (data) => {
+                    if (ended)
+                        return;
+                    begin();
+                    response.write(`data: ${data}\n\n`);
+                },
+                end: () => {
+                    if (ended)
+                        return;
+                    ended = true;
+                    streams.delete(stream);
+                    if (ping)
+                        clearInterval(ping);
+                    response.end();
+                }
+            };
+            let release;
+            try {
+                release = routes.stream(deviceId, frame, stream);
+            }
+            catch (error) {
+                return failure(response, error);
+            }
+            begin();
+            if (ended)
+                return release();
+            streams.add(stream);
+            ping = setInterval(() => { if (!ended)
+                response.write(': ping\n\n'); }, PING_MS);
+            ping.unref?.();
+            request.on('close', () => {
+                stream.end();
+                release();
+            });
+            return;
+        }
+        if (request.method === 'POST' && (url.pathname === '/rc/hello' || url.pathname === '/rc/call')) {
+            try {
+                const hello = url.pathname === '/rc/hello';
+                const body = await readBody(request, hello ? MAX_HELLO : MAX_CALL);
+                return reply(response, 200, hello ? await routes.hello(body) : await routes.call(body));
+            }
+            catch (error) {
+                return failure(response, error);
+            }
+        }
+        if (request.method === 'GET') {
+            const asset = routes.asset(url.pathname);
+            if (asset) {
+                response.writeHead(200, { ...HEADERS, 'content-type': asset.type, 'content-security-policy': CSP });
+                response.end(asset.body);
+                return;
+            }
+        }
+        reply(response, 404, { error: { code: 'not_found', message: 'Not found.' } });
+    };
+    const server = createServer((request, response) => {
+        handle(request, response).catch((error) => { if (!response.headersSent)
+            failure(response, error); });
+    });
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen({ host, port, exclusive: true }, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const bound = server.address().port;
+    authority = `${host.includes(':') ? `[${host}]` : host}:${bound}`;
+    return {
+        host,
+        port: bound,
+        close: async () => {
+            for (const stream of [...streams])
+                stream.end();
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                for (const socket of sockets)
+                    socket.destroy();
+            });
+        }
+    };
+}