windows-development-sandbox 1.7.0 → 1.10.0

package/dist/host/storage/index.d.ts

@@ -4,3 +4,5 @@ export * from './root.js';
 export * from './move.js';
 export * from './history.js';
 export * from './offer.js';
+export * from './providers/index.js';
+export * from './contained/index.js';

package/dist/host/storage/index.js

@@ -4,3 +4,5 @@ export * from './root.js';
 export * from './move.js';
 export * from './history.js';
 export * from './offer.js';
+export * from './providers/index.js';
+export * from './contained/index.js';

package/dist/host/storage/providers/contained.d.ts

@@ -0,0 +1,15 @@
+import { type ContainedDeps, type HolderId } from '../contained/contained-storage.js';
+import type { DataSet, PreparedStorage, ProviderCheck, StorageProvider } from './types.js';
+export declare class ContainedStorageProvider implements StorageProvider {
+    private readonly deps;
+    private readonly holder;
+    private readonly availability;
+    readonly id = "vhdx-mounted";
+    private storage;
+    constructor(deps: ContainedDeps, holder?: HolderId, availability?: () => ProviderCheck);
+    check(): Promise<ProviderCheck>;
+    /** Mounts the image (the one Windows permission prompt of a launch, when it is not mounted yet). */
+    prepare(dataSet: DataSet): Promise<PreparedStorage>;
+    /** Lets go of the mount (a launch that stopped before the sandbox started). The watcher holds it afterwards. */
+    release(): Promise<void>;
+}

package/dist/host/storage/providers/contained.js

@@ -0,0 +1,39 @@
+// Contained storage for the Windows Sandbox engine (beta, untested on a real PC): the data set splits. `run\` stays
+// the plain data folder shared in as before; tools, state, logs, databases and cache live in a disk image that is
+// mounted at <storage>\mounts\<set> (no drive letter) and shared in from there, to the same guest paths.
+import fs from 'node:fs';
+import path from 'node:path';
+import { containedAvailability } from '../contained/check.js';
+import { ContainedStorage } from '../contained/contained-storage.js';
+import { containedMappings, setNameOf } from '../contained/layout.js';
+export class ContainedStorageProvider {
+    deps;
+    holder;
+    availability;
+    id = 'vhdx-mounted';
+    storage = null;
+    constructor(deps, holder = { id: 'launch', pid: process.pid }, availability = containedAvailability) {
+        this.deps = deps;
+        this.holder = holder;
+        this.availability = availability;
+    }
+    check() {
+        return Promise.resolve(this.availability());
+    }
+    /** Mounts the image (the one Windows permission prompt of a launch, when it is not mounted yet). */
+    async prepare(dataSet) {
+        const storage = new ContainedStorage(this.deps, setNameOf(dataSet.dataPath));
+        this.storage = storage;
+        const mount = await storage.acquire(this.holder);
+        fs.mkdirSync(path.join(dataSet.dataPath, 'run'), { recursive: true });
+        const mappings = containedMappings(dataSet.dataPath, mount, dataSet.guest);
+        return {
+            attachments: mappings.map((m) => ({ kind: 'folder', host: m.host, guest: m.guest, readOnly: m.readOnly })),
+            mappings,
+        };
+    }
+    /** Lets go of the mount (a launch that stopped before the sandbox started). The watcher holds it afterwards. */
+    async release() {
+        await this.storage?.release(this.holder.id);
+    }
+}

package/dist/host/storage/providers/folder.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedMapping } from '../../../core/types.js';
+import type { DataSet, PreparedStorage, ProviderCheck, StorageAttachment, StorageProvider } from './types.js';
+/** The data folder as a read/write attachment. */
+export declare function folderAttachment(dataSet: DataSet): StorageAttachment;
+/** The data folder as a mapping (the launch builds its mapping list synchronously, so this is the plain function). */
+export declare function dataMapping(dataSet: DataSet): ResolvedMapping;
+export declare class FolderStorageProvider implements StorageProvider {
+    readonly id = "folder";
+    check(): Promise<ProviderCheck>;
+    prepare(dataSet: DataSet): Promise<PreparedStorage>;
+    release(): Promise<void>;
+}

package/dist/host/storage/providers/folder.js

@@ -0,0 +1,20 @@
+/** The data folder as a read/write attachment. */
+export function folderAttachment(dataSet) {
+    return { kind: 'folder', host: dataSet.dataPath, guest: dataSet.guest, readOnly: false };
+}
+/** The data folder as a mapping (the launch builds its mapping list synchronously, so this is the plain function). */
+export function dataMapping(dataSet) {
+    return { host: dataSet.dataPath, guest: dataSet.guest, readOnly: false };
+}
+export class FolderStorageProvider {
+    id = 'folder';
+    check() {
+        return Promise.resolve({ available: true, reasons: [], fixes: [] });
+    }
+    prepare(dataSet) {
+        return Promise.resolve({ attachments: [folderAttachment(dataSet)], mappings: [dataMapping(dataSet)] });
+    }
+    release() {
+        return Promise.resolve();
+    }
+}

package/dist/host/storage/providers/index.d.ts

@@ -0,0 +1,4 @@
+export { FolderStorageProvider, dataMapping, folderAttachment } from './folder.js';
+export { ContainedStorageProvider } from './contained.js';
+export { providerFor, type ProviderOptions } from './registry.js';
+export type { DataSet, PreparedStorage, ProviderCheck, StorageAttachment, StorageProvider } from './types.js';

package/dist/host/storage/providers/index.js

@@ -0,0 +1,3 @@
+export { FolderStorageProvider, dataMapping, folderAttachment } from './folder.js';
+export { ContainedStorageProvider } from './contained.js';
+export { providerFor } from './registry.js';

package/dist/host/storage/providers/registry.d.ts

@@ -0,0 +1,9 @@
+import type { Config } from '../../../core/types.js';
+import type { ContainedDeps } from '../contained/contained-storage.js';
+import type { ProviderCheck, StorageProvider } from './types.js';
+export interface ProviderOptions {
+    readonly contained?: ContainedDeps;
+    /** Tests: the answer of the availability check. */
+    readonly availability?: () => ProviderCheck;
+}
+export declare function providerFor(config: Config, options?: ProviderOptions): StorageProvider;

package/dist/host/storage/providers/registry.js

@@ -0,0 +1,14 @@
+import { fail } from '../../../core/util/index.js';
+import { containedAvailability } from '../contained/check.js';
+import { FolderStorageProvider } from './folder.js';
+import { ContainedStorageProvider } from './contained.js';
+export function providerFor(config, options = {}) {
+    if (config.storage.contained === 'off')
+        return new FolderStorageProvider();
+    const check = (options.availability ?? containedAvailability)();
+    if (!check.available)
+        fail('Contained storage cannot be used: ' + check.reasons.join(' '), check.fixes.join(' ') || 'Set storage.contained to "off" (the default) in your settings.');
+    if (!options.contained)
+        fail('Contained storage was not set up for this command.', 'Set storage.contained to "off" and report this.');
+    return new ContainedStorageProvider(options.contained, undefined, options.availability);
+}

package/dist/host/storage/providers/types.d.ts

@@ -0,0 +1,33 @@
+import type { ResolvedMapping } from '../../../core/types.js';
+/** `folder`: a host folder shared in (it is also one of the plan's mappings). `disk`: an image the engine attaches. */
+export type StorageAttachment = {
+    readonly kind: 'folder';
+    readonly host: string;
+    readonly guest: string;
+    readonly readOnly: boolean;
+} | {
+    readonly kind: 'disk';
+    readonly image: string;
+    readonly guest: string;
+    readonly maxGb: number;
+};
+export interface DataSet {
+    readonly dataPath: string;
+    readonly guest: string;
+}
+export interface PreparedStorage {
+    readonly attachments: readonly StorageAttachment[];
+    /** The folder attachments as mappings, in the order they go in the launch. */
+    readonly mappings: readonly ResolvedMapping[];
+}
+export interface ProviderCheck {
+    readonly available: boolean;
+    readonly reasons: readonly string[];
+    readonly fixes: readonly string[];
+}
+export interface StorageProvider {
+    readonly id: 'folder' | 'vhdx-mounted' | 'vhdx-attached';
+    check(): Promise<ProviderCheck>;
+    prepare(dataSet: DataSet): Promise<PreparedStorage>;
+    release(): Promise<void>;
+}

package/dist/host/storage/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/host/tools/conpty.js

@@ -3,12 +3,13 @@ import path from 'node:path';
 import { downloader, extractArchive, fetchJson, moveIntoPlace, stagingFolder } from '../../shared/download/index.js';
 import { safeRemove } from '../../shared/io/index.js';
 import { assertTestWritable } from '../test-guard.js';
+import { hostDataFolder, hostDataRoot } from '../storage/index.js';
 import { z } from 'zod';
 import { assertNoLinks, errMsg, fileExists } from '../../core/util/index.js';
 // ---- conpty.dll -----------------------------------------------------------------------------------------------------
 /** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
 export function conptyDir(dataPath) {
-    return path.join(dataPath, 'tools', 'conpty');
+    return path.join(hostDataFolder(dataPath, 'tools'), 'conpty');
 }
 const NUGET_CONPTY = 'https://api.nuget.org/v3-flatcontainer/microsoft.windows.console.conpty/';
 const NugetVersionsSchema = z.object({ versions: z.array(z.string()) });
@@ -22,7 +23,7 @@ const NugetCatalogSchema = z.object({ packageHash: z.string(), packageHashAlgori
 export async function ensureConpty(dataPath, refresh) {
     const dir = conptyDir(dataPath);
     assertTestWritable(dir);
-    assertNoLinks(dataPath, dir);
+    assertNoLinks(hostDataRoot(dataPath), dir);
     if (fileExists(path.join(dir, 'conpty.dll')) && fileExists(path.join(dir, 'OpenConsole.exe')) && !refresh)
         return 'cached';
     const arch = process.arch === 'arm64' ? 'arm64' : 'x64';

package/dist/host/tools/windows-terminal.js

@@ -5,11 +5,12 @@ import path from 'node:path';
 import { downloader, githubAsset } from '../../shared/download/index.js';
 import { safeRemove, writeFileAtomic } from '../../shared/io/index.js';
 import { assertTestWritable } from '../test-guard.js';
+import { hostDataFolder, hostDataRoot } from '../storage/index.js';
 import { applyEdits, modify } from 'jsonc-parser';
 import { z } from 'zod';
 import { assertNoLinks, errMsg, fileExists, parseJsonc, writeJson } from '../../core/util/index.js';
 export function terminalDir(dataPath) {
-    return path.join(dataPath, 'tools', 'terminal');
+    return path.join(hostDataFolder(dataPath, 'tools'), 'terminal');
 }
 export function terminalExe(dataPath) {
     return path.join(terminalDir(dataPath), 'WindowsTerminal.exe');
@@ -82,10 +83,10 @@ export function withReloadEnvironment(settings) {
 export function syncPwshProfile(dataPath, allowed) {
     const file = path.join(terminalDir(dataPath), 'settings', 'settings.json');
     assertTestWritable(file);
-    assertNoLinks(dataPath, file);
+    assertNoLinks(hostDataRoot(dataPath), file);
     if (!fileExists(file) || fs.statSync(file).size > MAX_SETTINGS_BYTES)
         return;
-    const visible = allowed && fileExists(path.join(dataPath, 'tools', 'pwsh', 'pwsh.exe'));
+    const visible = allowed && fileExists(path.join(hostDataFolder(dataPath, 'tools'), 'pwsh', 'pwsh.exe'));
     let parsed;
     const text = fs.readFileSync(file, 'utf8');
     try {
@@ -130,9 +131,9 @@ const installTerminal = async (dataPath, refresh) => {
     const settings = path.join(dir, 'settings');
     // downloader.archive replaces tools\terminal: the portable settings folder waits here meanwhile (and goes back also
     // when the download fails). One still parked from an interrupted earlier run is the one to keep.
-    const parked = path.join(dataPath, 'tools', 'terminal-settings.parked');
-    assertNoLinks(dataPath, settings);
-    assertNoLinks(dataPath, parked);
+    const parked = path.join(hostDataFolder(dataPath, 'tools'), 'terminal-settings.parked');
+    assertNoLinks(hostDataRoot(dataPath), settings);
+    assertNoLinks(hostDataRoot(dataPath), parked);
     if (fileExists(exe) && !refresh)
         return { exe, message: 'cached' };
     try {
@@ -158,7 +159,7 @@ const installTerminal = async (dataPath, refresh) => {
                 fs.renameSync(parked, settings);
             }
             const settingsFile = path.join(settings, 'settings.json');
-            assertNoLinks(dataPath, settingsFile);
+            assertNoLinks(hostDataRoot(dataPath), settingsFile);
             if (fileExists(path.join(dir, '.portable')) && !fs.existsSync(settingsFile))
                 writeJson(settingsFile, SETTINGS);
         }

package/dist/host/vpn/index.d.ts

@@ -1,4 +1,4 @@
 export { VpnLogin, loginProblem, type LoginState, type VpnCredentials } from './login.js';
 export { fetchBounded, findCountry, nordProfile, recommendedServer, type Fetcher, type NordServer } from './nordvpn.js';
-export { prepareVpn, vpnNotes, type PrepareOptions } from './prepare.js';
+export { prepareVpn, vpnNotes, wireguardFileProblem, type PrepareOptions } from './prepare.js';
 export { hostPublicIp, readVpnLine, vpnLine, type VpnLine } from './status.js';

package/dist/host/vpn/index.js

@@ -1,4 +1,4 @@
 export { VpnLogin, loginProblem } from './login.js';
 export { fetchBounded, findCountry, nordProfile, recommendedServer } from './nordvpn.js';
-export { prepareVpn, vpnNotes } from './prepare.js';
+export { prepareVpn, vpnNotes, wireguardFileProblem } from './prepare.js';
 export { hostPublicIp, readVpnLine, vpnLine } from './status.js';

package/dist/host/vpn/prepare.d.ts

@@ -13,5 +13,7 @@ export interface PrepareOptions {
 }
 /** Null when the VPN is off. Throws a UserError that says what to do when it cannot be set up. */
 export declare function prepareVpn(o: PrepareOptions): Promise<PreparedVpn | null>;
+/** For doctor: null when vpn.configFile is a readable, safe WireGuard config, else a short reason (never a key). */
+export declare function wireguardFileProblem(configFile: string, base: string): string | null;
 /** What the launch says about the VPN: the warnings the user must see before trusting it. */
 export declare function vpnNotes(vpn: Config['vpn']): string[];

package/dist/host/vpn/prepare.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { expandPath, fail } from '../../core/util/index.js';
 import { assertSafeOvpn, MAX_OVPN_BYTES } from '../../shared/vpn/ovpn.js';
+import { assertSafeWireguard, inspectWireguard, MAX_WIREGUARD_BYTES, renderWireguard, } from '../../shared/vpn/wireguard.js';
 import { fetchBounded, nordProfile, recommendedServer } from './nordvpn.js';
 import { VpnLogin } from './login.js';
 /** Null when the VPN is off. Throws a UserError that says what to do when it cannot be set up. */
@@ -15,6 +16,8 @@ export async function prepareVpn(o) {
         fail('The VPN is on, but sandbox.networking is off: there is no network to put it on.', 'Turn one of them off.');
     if (o.sandboxRunning)
         fail('A sandbox is running already, so the VPN login is not handed over.', 'Start the VPN sandbox after it stops.');
+    if (vpn.provider === 'wireguard-file')
+        return prepareWireguard(o);
     const login = o.login ?? new VpnLogin(o.storageRoot);
     const credentials = login.read(vpn.provider) ??
         fail('The VPN is on, but no ' + (vpn.provider === 'nordvpn' ? 'NordVPN' : 'VPN') + ' login is saved.', 'Save it with: sandbox vpn login   (or turn the VPN off: sandbox config set vpn.enabled false)');
@@ -62,16 +65,74 @@ export async function prepareVpn(o) {
         credentials,
     };
 }
+/**
+ * wireguard-file: reads vpn.configFile on this PC (size capped), checks it as untrusted data and returns it written
+ * again from the checked values. It holds the private key, so it only ever goes in the one-shot secrets file. There is
+ * no saved login: the keys are in the file.
+ */
+function prepareWireguard(o) {
+    const { vpn } = o.config;
+    if (!vpn.configFile.trim())
+        fail('vpn.provider is wireguard-file but vpn.configFile is empty.', 'Set it: sandbox config set vpn.configFile <path to your .conf>');
+    const file = expandPath(vpn.configFile, o.base ?? process.cwd());
+    let size;
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile())
+            throw new Error('not a file');
+        size = stat.size;
+    }
+    catch {
+        return fail('The WireGuard config ' + file + ' does not exist.', 'Fix vpn.configFile.');
+    }
+    if (size > MAX_WIREGUARD_BYTES)
+        fail('The WireGuard config ' + file + ' is too big.', 'Use a plain .conf file.');
+    const text = fs.readFileSync(file, 'utf8');
+    try {
+        const config = assertSafeWireguard(text, path.basename(file));
+        return {
+            session: { provider: vpn.provider, protocol: 'udp', killSwitch: vpn.killSwitch, server: path.basename(file) },
+            wireguardConfig: renderWireguard(config),
+        };
+    }
+    catch (e) {
+        return fail(e instanceof Error ? e.message : String(e), 'Nothing was started. Use a config without PostUp, PreUp or other script lines.');
+    }
+}
+/** For doctor: null when vpn.configFile is a readable, safe WireGuard config, else a short reason (never a key). */
+export function wireguardFileProblem(configFile, base) {
+    if (!configFile.trim())
+        return 'vpn.configFile is empty';
+    const file = expandPath(configFile, base);
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile())
+            return file + ' is not a file';
+        if (stat.size > MAX_WIREGUARD_BYTES)
+            return file + ' is too big for a WireGuard config';
+        const report = inspectWireguard(fs.readFileSync(file, 'utf8'));
+        return report.ok ? null : 'refused: ' + report.problems.slice(0, 3).join('; ');
+    }
+    catch {
+        return file + ' cannot be read';
+    }
+}
 /** What the launch says about the VPN: the warnings the user must see before trusting it. */
 export function vpnNotes(vpn) {
     if (!vpn.enabled)
         return [];
     return [
         'VPN: ' +
-            (vpn.provider === 'nordvpn' ? 'NordVPN' + (vpn.country ? ' (' + vpn.country + ')' : '') : 'your profile') +
+            (vpn.provider === 'nordvpn'
+                ? 'NordVPN' + (vpn.country ? ' (' + vpn.country + ')' : '')
+                : vpn.provider === 'wireguard-file'
+                    ? 'your WireGuard config'
+                    : 'your profile') +
             (vpn.killSwitch
                 ? ', kill switch on: if the tunnel fails the sandbox stays offline.'
                 : ', kill switch OFF: if the tunnel fails the sandbox uses your normal connection.'),
-        'The agent in the sandbox can read the VPN login (a service login you can revoke) and can turn the tunnel off, because it is the administrator there.',
+        vpn.provider === 'wireguard-file'
+            ? 'The agent in the sandbox can read the WireGuard private key from your config and can turn the tunnel off, because it is the administrator there. Use a key you can revoke.'
+            : 'The agent in the sandbox can read the VPN login (a service login you can revoke) and can turn the tunnel off, because it is the administrator there.',
     ];
 }

package/dist/host/web/browser.d.ts

@@ -1 +1,3 @@
 export declare function openBrowser(url: string): void;
+/** Opens a GitHub new-issue address in the default browser (rundll32, so no shell reads the & in it). */
+export declare function openIssuePage(url: string): void;

package/dist/host/web/browser.js

@@ -1,6 +1,6 @@
 // Opens an address in the default browser (through cmd's start; the address is one we built, hex and digits only).
 import { spawn } from 'node:child_process';
-import { SYSTEM } from '../../shared/system.js';
+import { SYSTEM, system32 } from '../../shared/system.js';
 import { refuseInSelfTest } from '../test-guard.js';
 export function openBrowser(url) {
     refuseInSelfTest('open a browser');
@@ -8,3 +8,16 @@ export function openBrowser(url) {
         throw new Error('Not a web UI address.');
     spawn(SYSTEM.cmd(), ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
 }
+/** The one other page we open: a GitHub new-issue form (letters, digits and URL escapes only). */
+const ISSUE_URL = /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/new\?[\w%.~&=+-]*$/;
+/** Opens a GitHub new-issue address in the default browser (rundll32, so no shell reads the & in it). */
+export function openIssuePage(url) {
+    refuseInSelfTest('open a browser');
+    if (!ISSUE_URL.test(url) || url.length > 2000)
+        throw new Error('Not a GitHub new-issue address.');
+    spawn(system32('rundll32.exe'), ['url.dll,FileProtocolHandler', url], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    }).unref();
+}

package/dist/host/web/index.d.ts

@@ -1,9 +1,10 @@
 export { WebAuth, newToken, sameSecret, hostAllowed, originAllowed, csrfOk, cookieValue, cookieHeader, } from './auth.js';
 export type { WebBackend } from './backend.js';
-export { openBrowser } from './browser.js';
+export { openBrowser, openIssuePage } from './browser.js';
 export { TerminalBridge } from './bridge.js';
 export { WebControl, type WebStatus } from './control.js';
 export { WebRunner } from './runner.js';
-export { WebServer, CONTENT_SECURITY_POLICY, type WebServerOptions } from './server.js';
+export { RpcSession } from './rpc.js';
+export { WebServer, CONTENT_SECURITY_POLICY, RPC_PATH, type WebServerOptions } from './server.js';
 export { StaticFiles } from './static-files.js';
 export { WebStore, WebStateSchema, type WebState } from './state.js';

package/dist/host/web/index.js

@@ -1,8 +1,9 @@
 export { WebAuth, newToken, sameSecret, hostAllowed, originAllowed, csrfOk, cookieValue, cookieHeader, } from './auth.js';
-export { openBrowser } from './browser.js';
+export { openBrowser, openIssuePage } from './browser.js';
 export { TerminalBridge } from './bridge.js';
 export { WebControl } from './control.js';
 export { WebRunner } from './runner.js';
-export { WebServer, CONTENT_SECURITY_POLICY } from './server.js';
+export { RpcSession } from './rpc.js';
+export { WebServer, CONTENT_SECURITY_POLICY, RPC_PATH } from './server.js';
 export { StaticFiles } from './static-files.js';
 export { WebStore, WebStateSchema } from './state.js';

package/dist/host/web/rpc.d.ts

@@ -0,0 +1,24 @@
+import type { WebSocket } from 'ws';
+import { type RpcHost } from '../../app/kernel/index.js';
+export declare class RpcSession {
+    private readonly ws;
+    private readonly host;
+    private readonly calls;
+    private readonly subscriptions;
+    private closed;
+    constructor(ws: WebSocket, host: RpcHost);
+    start(): void;
+    private send;
+    /** A browser that sends something that is not one of our messages is closed. */
+    private refuse;
+    private receive;
+    private handle;
+    /** The id is free and the socket has room for one more call or subscription. */
+    private admit;
+    private call;
+    private answer;
+    private subscribe;
+    private unsubscribe;
+    /** The browser went away: subscriptions stop, and questions still open are answered no. */
+    private close;
+}

package/dist/host/web/rpc.js

@@ -0,0 +1,149 @@
+import { ANSWER_SCHEMAS, ClientMessageSchema, MAX_OPEN_PER_SOCKET, NO_QUESTIONS, ioFromAsker, toWireError, } from '../../app/kernel/index.js';
+/** What a question gets when the browser goes away before answering: no. */
+function declined(q) {
+    return q.kind === 'confirm' ? false : undefined;
+}
+export class RpcSession {
+    ws;
+    host;
+    calls = new Map();
+    subscriptions = new Map();
+    closed = false;
+    constructor(ws, host) {
+        this.ws = ws;
+        this.host = host;
+    }
+    start() {
+        this.ws.on('message', (data, binary) => this.receive(data, binary));
+        this.ws.on('close', () => this.close());
+        this.ws.on('error', () => this.close());
+    }
+    send(message) {
+        if (!this.closed && this.ws.readyState === this.ws.OPEN)
+            this.ws.send(JSON.stringify(message));
+    }
+    /** A browser that sends something that is not one of our messages is closed. */
+    refuse() {
+        this.ws.close(1008, 'bad message');
+        this.close();
+    }
+    receive(data, binary) {
+        if (binary)
+            return this.refuse();
+        let value;
+        try {
+            value = JSON.parse(data.toString());
+        }
+        catch {
+            return this.refuse();
+        }
+        const parsed = ClientMessageSchema.safeParse(value);
+        if (!parsed.success)
+            return this.refuse();
+        this.handle(parsed.data);
+    }
+    handle(m) {
+        switch (m.t) {
+            case 'call':
+                return this.call(m.id, m.op, m.input);
+            case 'answer':
+                return this.answer(m.id, m.value);
+            case 'subscribe':
+                return this.subscribe(m.id, m.query, m.input);
+            case 'unsubscribe':
+                return this.unsubscribe(m.id);
+        }
+    }
+    /** The id is free and the socket has room for one more call or subscription. */
+    admit(id) {
+        if (this.calls.has(id) || this.subscriptions.has(id)) {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'That id is in use.' } });
+            return false;
+        }
+        if (this.calls.size + this.subscriptions.size >= MAX_OPEN_PER_SOCKET) {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'Too many at once.' } });
+            return false;
+        }
+        return true;
+    }
+    call(id, op, input) {
+        if (!this.admit(id))
+            return;
+        if (!this.host.kind(op)) {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'There is no ' + op + ' here.' } });
+            return;
+        }
+        this.calls.set(id, null);
+        const io = ioFromAsker((question) => new Promise((resolve) => {
+            if (this.closed)
+                return resolve(declined(question));
+            this.calls.set(id, { question, resolve: resolve });
+            this.send({ t: 'ask', id, question });
+        }), {
+            progress: (text) => this.send({ t: 'progress', id, text }),
+            log: (text, tone) => this.send({ t: 'log', id, text, ...(tone ? { tone } : {}) }),
+        });
+        this.host
+            .run(op, input, io)
+            .then((output) => this.send({ t: 'result', id, output }), (e) => this.send({ t: 'error', id, error: toWireError(e) }))
+            .finally(() => this.calls.delete(id));
+    }
+    answer(id, value) {
+        const waiting = this.calls.get(id);
+        if (!waiting)
+            return;
+        const parsed = ANSWER_SCHEMAS[waiting.question.kind].safeParse(value);
+        this.calls.set(id, null);
+        waiting.resolve(parsed.success ? parsed.data : declined(waiting.question));
+    }
+    subscribe(id, query, input) {
+        if (!this.admit(id))
+            return;
+        if (this.host.kind(query) !== 'query') {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'There is no ' + query + ' here.' } });
+            return;
+        }
+        const sub = { timer: undefined, last: undefined, busy: false };
+        this.subscriptions.set(id, sub);
+        const read = async () => {
+            if (sub.busy)
+                return;
+            sub.busy = true;
+            try {
+                const output = await this.host.run(query, input, NO_QUESTIONS);
+                const text = JSON.stringify(output);
+                if (text !== sub.last && this.subscriptions.get(id) === sub) {
+                    sub.last = text;
+                    this.send({ t: 'data', id, output });
+                }
+            }
+            catch (e) {
+                sub.last = undefined;
+                this.send({ t: 'error', id, error: toWireError(e) });
+            }
+            finally {
+                sub.busy = false;
+            }
+        };
+        void read();
+        const every = this.host.liveMs(query);
+        if (every)
+            sub.timer = setInterval(() => void read(), every);
+    }
+    unsubscribe(id) {
+        const sub = this.subscriptions.get(id);
+        if (sub?.timer)
+            clearInterval(sub.timer);
+        this.subscriptions.delete(id);
+    }
+    /** The browser went away: subscriptions stop, and questions still open are answered no. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const id of [...this.subscriptions.keys()])
+            this.unsubscribe(id);
+        for (const waiting of this.calls.values())
+            waiting?.resolve(declined(waiting.question));
+    }
+}

package/dist/host/web/runner.d.ts

@@ -1,8 +1,10 @@
+import type { RpcHost } from '../../app/kernel/index.js';
 import type { WebBackend } from './backend.js';
 export interface WebRunOptions {
     readonly storageRoot: string;
     readonly port: number;
     readonly backend: WebBackend;
+    readonly rpc?: RpcHost;
     readonly staticRoot: string;
 }
 export declare class WebRunner {

package/dist/host/web/runner.js

@@ -1,5 +1,3 @@
-// The background process behind `sandbox web start`: starts the server, records pid, port and token in the private
-// state file, and removes it again when the server stops.
 import { fail } from '../../core/util/index.js';
 import { newToken } from './auth.js';
 import { WebServer } from './server.js';
@@ -20,6 +18,7 @@ export class WebRunner {
             port: this.options.port,
             token,
             backend: this.options.backend,
+            rpc: this.options.rpc,
             staticRoot: this.options.staticRoot,
             onStop: stop,
         });