windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/engines/hcs/engine.js

@@ -0,0 +1,171 @@
+// The HCS engine (alpha): a Hyper-V isolated Windows container for agents, behind the SandboxEngine interface.
+// plan() is pure and tested; start() is DISABLED until the owner's go/no-go test (docs/design/engines.md) has passed
+// on a real PC.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { fail, UserError } from '../../../core/util/index.js';
+import { selfTestRunning } from '../../test-guard.js';
+import { checkHcs, realHcsProbes } from './check.js';
+import { buildDocuments, HCS_OWNER } from './documents.js';
+import { HcsHelper, hcsHostExe } from './helper.js';
+import { findImage } from './images.js';
+export const HCS_CAPABILITIES = {
+    desktop: false,
+    gpu: false,
+    clipboard: false,
+    audio: false,
+    video: false,
+    printers: false,
+    liveFolderAdd: true,
+    attachedDisks: true,
+    multipleInstances: true,
+    hvsocket: true,
+};
+export const HCS_ALPHA_MESSAGE = 'The HCS engine is in alpha and starting it is not enabled yet; see docs/design/engines.md';
+export const HCS_FLAG = 'AGENT_SANDBOX_HCS_EXPERIMENTAL';
+/** Starting is allowed only with the owner's flag, and never inside the self-test. */
+export function hcsStartEnabled(env, selfTest) {
+    return env[HCS_FLAG] === '1' && !selfTest;
+}
+const PlanFileSchema = z.object({
+    version: z.literal(1),
+    uvmId: z.string().regex(/^agent-sandbox-[A-Za-z0-9._-]{1,100}$/),
+    containerId: z.string().regex(/^agent-sandbox-[A-Za-z0-9._-]{1,100}$/),
+    uvmFile: z.string(),
+    containerFile: z.string(),
+    scratchVhdx: z.string(),
+    disks: z.array(z.object({ image: z.string(), maxGb: z.number().int().min(1).max(4096), lun: z.number().int() })),
+    logonCommand: z.string(),
+    notes: z.array(z.string()),
+});
+const SystemListSchema = z.array(z.object({ Id: z.string(), Owner: z.string().optional() }).passthrough());
+export class HcsEngine {
+    image;
+    probes;
+    storageRoot;
+    deps;
+    id = 'hcs';
+    /** `image` and `probes` come from the check (see HcsEngine.open); `storageRoot` is where HcsHost.exe is built. */
+    constructor(image, probes, storageRoot, deps = {}) {
+        this.image = image;
+        this.probes = probes;
+        this.storageRoot = storageRoot;
+        this.deps = deps;
+    }
+    /** The engine for this PC when its check passes; otherwise a clear stop with the check's reasons and fixes. */
+    static async open(storageRoot, probes = realHcsProbes(), deps = {}) {
+        const check = checkHcs(probes);
+        if (!check.available)
+            fail('The HCS engine cannot run on this PC: ' + check.reasons.join(' '), 'Fix: ' + check.fixes.join(' | '));
+        return new HcsEngine(findImage(probes.imageStores()).image, probes, storageRoot, deps);
+    }
+    capabilities() {
+        return HCS_CAPABILITIES;
+    }
+    check() {
+        return Promise.resolve(checkHcs(this.probes));
+    }
+    plan(launch) {
+        if (!this.image)
+            fail('No base image is available for the HCS engine.', 'Run: sandbox engine check hcs');
+        const slug = path.basename(launch.launchPath).replace(/[^A-Za-z0-9._-]/g, '-');
+        const dir = path.join(launch.launchPath, 'hcs');
+        const scratchVhdx = path.join(dir, 'scratch.vhdx');
+        const docs = buildDocuments({
+            launch,
+            image: this.image,
+            id: 'agent-sandbox-' + slug,
+            scratchVhdx,
+            hostCpus: (this.deps.hostCpus ?? (() => os.cpus().length))(),
+        });
+        const planFile = {
+            version: 1,
+            uvmId: docs.uvmId,
+            containerId: docs.containerId,
+            uvmFile: path.join(dir, 'uvm.json'),
+            containerFile: path.join(dir, 'container.json'),
+            scratchVhdx,
+            disks: [...docs.disks],
+            logonCommand: launch.logonCommand,
+            notes: [...docs.notes],
+        };
+        const entry = path.join(dir, 'plan.json');
+        const pretty = (v) => JSON.stringify(v, null, 2) + '\n';
+        return {
+            engine: this.id,
+            entry,
+            files: [
+                { path: planFile.uvmFile, text: pretty(docs.uvm) },
+                { path: planFile.containerFile, text: pretty(docs.container) },
+                { path: entry, text: pretty(planFile) },
+            ],
+        };
+    }
+    helper() {
+        return this.deps.helper ?? new HcsHelper(() => hcsHostExe(this.storageRoot));
+    }
+    async start(plan) {
+        const enabled = hcsStartEnabled(this.deps.env ?? process.env, (this.deps.selfTest ?? selfTestRunning)());
+        if (!enabled)
+            fail(HCS_ALPHA_MESSAGE);
+        const file = PlanFileSchema.parse(JSON.parse(fs.readFileSync(plan.entry, 'utf8')));
+        const exists = this.deps.exists ?? fs.existsSync;
+        const helper = this.helper();
+        const disks = [...file.disks.map((d) => d.image), file.scratchVhdx];
+        for (const d of file.disks)
+            if (!exists(d.image))
+                helper.createVhdx(d.image, d.maxGb);
+        // The writable layer is made by HcsInitializeWritableLayer, which this phase does not have.
+        if (!exists(file.scratchVhdx))
+            fail('The writable layer of this sandbox has not been prepared (not built yet).');
+        const created = [];
+        try {
+            for (const disk of disks)
+                helper.grantVmAccess(file.uvmId, disk);
+            helper.create(file.uvmId, fs.readFileSync(file.uvmFile, 'utf8'));
+            created.push(file.uvmId);
+            helper.start(file.uvmId);
+            helper.create(file.containerId, fs.readFileSync(file.containerFile, 'utf8'));
+            created.push(file.containerId);
+            helper.start(file.containerId);
+        }
+        catch (e) {
+            for (const id of created.reverse())
+                this.tryTerminate(helper, id);
+            throw e;
+        }
+        return { id: file.uvmId, engine: this.id, started: Date.now() };
+    }
+    tryTerminate(helper, id) {
+        try {
+            helper.terminate(id);
+        }
+        catch (e) {
+            if (!(e instanceof UserError))
+                throw e; // a system that is already gone is fine
+        }
+    }
+    /** Ours: the compute systems the helper lists with our owner name. */
+    ours(helper) {
+        const parsed = SystemListSchema.safeParse(JSON.parse(helper.enumerate().json || '[]'));
+        return parsed.success ? parsed.data.filter((s) => s.Owner === HCS_OWNER).map((s) => s.Id) : [];
+    }
+    running() {
+        try {
+            return Promise.resolve(this.ours(this.helper()).length > 0);
+        }
+        catch {
+            return Promise.resolve(false); // no helper or no service: nothing of ours can be running
+        }
+    }
+    stop() {
+        const helper = this.helper();
+        // The container goes before the machine that hosts it.
+        const ids = this.ours(helper).sort((a, b) => Number(b.endsWith('-c')) - Number(a.endsWith('-c')));
+        for (const id of ids)
+            this.tryTerminate(helper, id);
+        return Promise.resolve();
+    }
+}

package/dist/host/engines/hcs/helper.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const HcsReplySchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    hresult: z.ZodString;
+    message: z.ZodString;
+    json: z.ZodString;
+    values: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export type HcsReply = z.infer<typeof HcsReplySchema>;
+export interface RunResult {
+    readonly status: number | null;
+    readonly error?: string;
+}
+/** Starts the helper: replaceable in tests. */
+export type HelperRunner = (exe: string, args: readonly string[], timeoutMs: number) => RunResult;
+export declare const spawnRunner: HelperRunner;
+/** Compiles the helper's sources to `exe` with the .NET Framework csc (C# 5). False when it cannot be built. */
+export declare function buildHcsHostTo(exe: string): boolean;
+/**
+ * <storage>\bin\hcs\<hash of its sources>\HcsHost.exe, built the first time. Its own folder: HostTools' cleanup of old
+ * builds only touches twelve-digit hash folders directly in bin. Null when it cannot be built.
+ */
+export declare function hcsHostExe(storageRoot: string): string | null;
+export declare class HcsHelper {
+    private readonly exe;
+    private readonly run;
+    private readonly tempRoot;
+    /** `exe`: where HcsHost.exe is (built when asked); `tempRoot`: where the private folders for one call go. */
+    constructor(exe: () => string | null, run?: HelperRunner, tempRoot?: string);
+    /** One helper call: `args` then `--out <response>`. Returns the checked answer, whatever it says. */
+    call(args: readonly string[], request?: unknown): HcsReply;
+    /** The same, but a failed answer stops with the helper's own message. */
+    private must;
+    check(): HcsReply;
+    enumerate(): HcsReply;
+    properties(id: string): HcsReply;
+    /** `document` is the HCS JSON text; it travels as a string inside the request file. */
+    create(id: string, document: string): HcsReply;
+    start(id: string): HcsReply;
+    terminate(id: string): HcsReply;
+    grantVmAccess(vmId: string, file: string): HcsReply;
+    createVhdx(file: string, maxGb: number): HcsReply;
+}

package/dist/host/engines/hcs/helper.js

@@ -0,0 +1,173 @@
+// Runs HcsHost.exe (native\csharp\HcsHost, built on first use) with JSON files in a private temp folder. The answer
+// is a file too: size-bounded and checked with zod, never trusted as it is. HcsHost only talks to the Windows Host
+// Compute Service and virtdisk; it takes no guest data.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { z } from 'zod';
+import { fail, UserError } from '../../../core/util/index.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { nativeFile } from '../../native.js';
+import { refuseInSelfTest } from '../../test-guard.js';
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const CALL_TIMEOUT_MS = 240000;
+/** Only ids this tool gives its compute systems (HcsHost.exe refuses any other, and checks the Owner too). */
+const SAFE_ID = /^agent-sandbox-[A-Za-z0-9._-]{1,100}$/;
+export const HcsReplySchema = z.object({
+    ok: z.boolean(),
+    hresult: z.string().max(16),
+    message: z.string().max(4000),
+    json: z.string().max(MAX_RESPONSE_BYTES),
+    values: z.record(z.string().max(64), z.string().max(2000)),
+});
+export const spawnRunner = (exe, args, timeoutMs) => {
+    const r = spawnSync(exe, [...args], {
+        windowsHide: true,
+        timeout: timeoutMs,
+        maxBuffer: 1024 * 1024,
+        stdio: 'ignore',
+    });
+    return { status: r.status, error: r.error?.message };
+};
+/** Compiles the helper's sources to `exe` with the .NET Framework csc (C# 5). False when it cannot be built. */
+export function buildHcsHostTo(exe) {
+    const dir = nativeFile('csharp', 'HcsHost');
+    let sources;
+    try {
+        sources = fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.cs'))
+            .sort()
+            .map((f) => path.join(dir, f));
+    }
+    catch {
+        return false; // no sources next to this package
+    }
+    if (!fs.existsSync(SYSTEM.csc()))
+        return false;
+    fs.mkdirSync(path.dirname(exe), { recursive: true });
+    const r = spawnSync(SYSTEM.csc(), ['/nologo', '/optimize', '/target:exe', '/r:System.Web.Extensions.dll', '/out:' + exe, ...sources], { windowsHide: true, timeout: 120000 });
+    return r.status === 0 && fs.existsSync(exe);
+}
+/**
+ * <storage>\bin\hcs\<hash of its sources>\HcsHost.exe, built the first time. Its own folder: HostTools' cleanup of old
+ * builds only touches twelve-digit hash folders directly in bin. Null when it cannot be built.
+ */
+export function hcsHostExe(storageRoot) {
+    refuseInSelfTest('build HcsHost.exe');
+    const dir = nativeFile('csharp', 'HcsHost');
+    const hash = crypto.createHash('sha256');
+    try {
+        for (const f of fs
+            .readdirSync(dir)
+            .filter((n) => n.endsWith('.cs'))
+            .sort())
+            hash.update(fs.readFileSync(path.join(dir, f)));
+    }
+    catch {
+        return null; // no sources
+    }
+    const exe = path.join(storageRoot, 'bin', 'hcs', hash.digest('hex').slice(0, 12), 'HcsHost.exe');
+    return fs.existsSync(exe) || buildHcsHostTo(exe) ? exe : null;
+}
+/** A path argument: absolute, not an option. Nothing else reaches the helper's command line. */
+function pathArg(value, what) {
+    if (!path.isAbsolute(value) || value.startsWith('-'))
+        fail('Not a full path for ' + what + ': ' + value);
+    return value;
+}
+function idArg(value) {
+    if (!SAFE_ID.test(value))
+        fail('Not a valid sandbox id: ' + value);
+    return value;
+}
+export class HcsHelper {
+    exe;
+    run;
+    tempRoot;
+    /** `exe`: where HcsHost.exe is (built when asked); `tempRoot`: where the private folders for one call go. */
+    constructor(exe, run = spawnRunner, tempRoot = os.tmpdir()) {
+        this.exe = exe;
+        this.run = run;
+        this.tempRoot = tempRoot;
+    }
+    /** One helper call: `args` then `--out <response>`. Returns the checked answer, whatever it says. */
+    call(args, request) {
+        const exe = this.exe();
+        if (!exe)
+            fail('HcsHost.exe could not be built.', 'It needs the .NET Framework compiler that ships with Windows.');
+        const dir = fs.mkdtempSync(path.join(this.tempRoot, 'agent-sandbox-hcs-'));
+        try {
+            const out = path.join(dir, 'response.json');
+            const full = [...args];
+            if (request !== undefined) {
+                const file = path.join(dir, 'request.json');
+                fs.writeFileSync(file, JSON.stringify(request), 'utf8');
+                full.push(file);
+            }
+            const result = this.run(exe, [...full, '--out', out], CALL_TIMEOUT_MS);
+            return readReply(out, result);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    /** The same, but a failed answer stops with the helper's own message. */
+    must(args, request) {
+        const reply = this.call(args, request);
+        if (!reply.ok)
+            fail('The Host Compute Service said: ' + reply.message + ' (' + reply.hresult + ')');
+        return reply;
+    }
+    check() {
+        return this.call(['check']);
+    }
+    enumerate() {
+        return this.must(['enumerate']);
+    }
+    properties(id) {
+        return this.must(['properties', idArg(id)]);
+    }
+    /** `document` is the HCS JSON text; it travels as a string inside the request file. */
+    create(id, document) {
+        return this.must(['create'], { id: idArg(id), document });
+    }
+    start(id) {
+        return this.must(['start', idArg(id)]);
+    }
+    terminate(id) {
+        return this.must(['terminate', idArg(id)]);
+    }
+    grantVmAccess(vmId, file) {
+        return this.must(['grant-vm-access', idArg(vmId), pathArg(file, 'the disk')]);
+    }
+    createVhdx(file, maxGb) {
+        if (!Number.isInteger(maxGb) || maxGb < 1 || maxGb > 4096)
+            fail('The disk size must be 1 to 4096 GB.');
+        return this.must(['create-vhdx', pathArg(file, 'the disk'), String(maxGb)]);
+    }
+}
+function readReply(file, result) {
+    let text;
+    try {
+        if (fs.statSync(file).size > MAX_RESPONSE_BYTES)
+            fail('HcsHost.exe answered with too much text.');
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e instanceof UserError)
+            throw e;
+        fail('HcsHost.exe gave no answer' + (result.error ? ': ' + result.error : '') + '.');
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return fail('HcsHost.exe answered with something that is not JSON.');
+    }
+    const parsed = HcsReplySchema.safeParse(json);
+    return parsed.success ? parsed.data : fail('HcsHost.exe answered in a form this version does not know.');
+}

package/dist/host/engines/hcs/images.d.ts

@@ -0,0 +1,37 @@
+import type { HcsImage } from './documents.js';
+/** What a store says when it has no image: said to the user in plain words. */
+export interface ImageResult {
+    readonly image: HcsImage | null;
+    readonly reason: string;
+}
+export interface ImageStore {
+    readonly name: string;
+    find(): ImageResult;
+}
+/** The file reads a store does, so tests give it a fake disk. Every read is bounded and a miss is null. */
+export interface ImageFiles {
+    readText(file: string): string | null;
+    isDir(folder: string): boolean;
+}
+export declare const REAL_IMAGE_FILES: ImageFiles;
+/** Docker's chain ids: id(1) = diffId(1); id(n) = sha256(id(n-1) + " " + diffId(n)). */
+export declare function chainIds(diffIds: readonly string[]): string[];
+/** An image Docker Desktop (Windows containers) already pulled: found by reading its metadata, never changed. */
+export declare class DockerImageStore implements ImageStore {
+    private readonly root;
+    private readonly files;
+    readonly name = "an image Docker already pulled";
+    constructor(root?: string, files?: ImageFiles);
+    find(): ImageResult;
+}
+/** Your own image folder (AGENT_SANDBOX_HCS_IMAGE): a folder with image.json {layers (base first), utilityVmFiles}. */
+export declare class FolderImageStore implements ImageStore {
+    private readonly folder;
+    private readonly files;
+    readonly name = "an image folder you named";
+    constructor(folder?: string | undefined, files?: ImageFiles);
+    find(): ImageResult;
+}
+export declare function defaultImageStores(): ImageStore[];
+/** The first image any store has, or every store's reason. */
+export declare function findImage(stores: readonly ImageStore[]): ImageResult;

package/dist/host/engines/hcs/images.js

@@ -0,0 +1,152 @@
+// Where the HCS engine gets its base image (Windows Server Core, ltsc2022). This phase never downloads one: it only
+// finds an image that is already on this PC, read-only. The layout of Docker's image store is from memory of Docker's
+// windowsfilter graph driver [U]; nothing here writes to it.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+const MAX_TEXT = 4 * 1024 * 1024;
+export const REAL_IMAGE_FILES = {
+    readText: (file) => {
+        try {
+            if (fs.statSync(file).size > MAX_TEXT)
+                return null;
+            return fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            return null; // missing or unreadable: the store reports "not found"
+        }
+    },
+    isDir: (folder) => {
+        try {
+            return fs.statSync(folder).isDirectory();
+        }
+        catch {
+            return false; // missing: not a folder
+        }
+    },
+};
+/** The repository and tag of the image we look for: Windows Server Core 2022, any registry spelling. */
+const WANTED = /(^|\/)windows\/servercore:ltsc2022$/i;
+const RepositoriesSchema = z.object({ Repositories: z.record(z.string(), z.record(z.string(), z.string())) });
+const ImageConfigSchema = z.object({
+    rootfs: z.object({
+        diff_ids: z
+            .array(z.string().regex(/^sha256:[0-9a-f]{64}$/))
+            .min(1)
+            .max(200),
+    }),
+});
+const HEX64 = /^[0-9a-f]{64}$/;
+const CACHE_ID = /^[0-9a-zA-Z]{1,128}$/;
+/** Docker's chain ids: id(1) = diffId(1); id(n) = sha256(id(n-1) + " " + diffId(n)). */
+export function chainIds(diffIds) {
+    const out = [];
+    for (const diff of diffIds) {
+        const prev = out[out.length - 1];
+        out.push(prev
+            ? 'sha256:' +
+                crypto
+                    .createHash('sha256')
+                    .update(prev + ' ' + diff)
+                    .digest('hex')
+            : diff);
+    }
+    return out;
+}
+/** An image Docker Desktop (Windows containers) already pulled: found by reading its metadata, never changed. */
+export class DockerImageStore {
+    root;
+    files;
+    name = 'an image Docker already pulled';
+    constructor(root = path.join(process.env.ProgramData ?? 'C:\\ProgramData', 'docker'), files = REAL_IMAGE_FILES) {
+        this.root = root;
+        this.files = files;
+    }
+    find() {
+        const meta = path.join(this.root, 'image', 'windowsfilter');
+        const repos = this.files.readText(path.join(meta, 'repositories.json'));
+        if (repos === null)
+            return { image: null, reason: 'Docker has no Windows images on this PC.' };
+        const parsed = RepositoriesSchema.safeParse(safeJson(repos));
+        if (!parsed.success)
+            return { image: null, reason: "Docker's image list could not be read." };
+        let imageId = null;
+        for (const tags of Object.values(parsed.data.Repositories))
+            for (const [name, id] of Object.entries(tags))
+                if (!imageId && WANTED.test(name) && /^sha256:[0-9a-f]{64}$/.test(id))
+                    imageId = id;
+        if (!imageId)
+            return { image: null, reason: 'Docker has no windows/servercore:ltsc2022 image.' };
+        const config = ImageConfigSchema.safeParse(safeJson(this.files.readText(path.join(meta, 'imagedb', 'content', 'sha256', imageId.slice(7))) ?? ''));
+        if (!config.success)
+            return { image: null, reason: "Docker's record of the Server Core image could not be read." };
+        const layers = [];
+        for (const chain of chainIds(config.data.rootfs.diff_ids)) {
+            const hex = chain.slice(7);
+            if (!HEX64.test(hex))
+                return { image: null, reason: 'A layer id of the Server Core image is not valid.' };
+            const cacheId = (this.files.readText(path.join(meta, 'layerdb', 'sha256', hex, 'cache-id')) ?? '').trim();
+            if (!CACHE_ID.test(cacheId))
+                return { image: null, reason: 'A layer of the Server Core image is not on disk.' };
+            const folder = path.join(this.root, 'windowsfilter', cacheId);
+            if (!this.files.isDir(folder))
+                return { image: null, reason: 'A layer of the Server Core image is missing.' };
+            layers.push(folder);
+        }
+        const utilityVmFiles = path.join(layers[0], 'UtilityVM', 'Files');
+        if (!this.files.isDir(utilityVmFiles))
+            return { image: null, reason: 'The Server Core image has no UtilityVM folder (Hyper-V isolation needs it).' };
+        return { image: { id: imageId, layers, utilityVmFiles }, reason: '' };
+    }
+}
+const FolderImageSchema = z.object({
+    layers: z.array(z.string().min(3).max(260)).min(1).max(200),
+    utilityVmFiles: z.string().min(3).max(260),
+});
+/** Your own image folder (AGENT_SANDBOX_HCS_IMAGE): a folder with image.json {layers (base first), utilityVmFiles}. */
+export class FolderImageStore {
+    folder;
+    files;
+    name = 'an image folder you named';
+    constructor(folder = process.env.AGENT_SANDBOX_HCS_IMAGE, files = REAL_IMAGE_FILES) {
+        this.folder = folder;
+        this.files = files;
+    }
+    find() {
+        if (!this.folder)
+            return { image: null, reason: 'No image folder is set (AGENT_SANDBOX_HCS_IMAGE).' };
+        const parsed = FolderImageSchema.safeParse(safeJson(this.files.readText(path.join(this.folder, 'image.json')) ?? ''));
+        if (!parsed.success)
+            return { image: null, reason: 'There is no valid image.json in ' + this.folder + '.' };
+        const all = [...parsed.data.layers, parsed.data.utilityVmFiles];
+        if (!all.every((p) => path.isAbsolute(p) && this.files.isDir(p)))
+            return { image: null, reason: 'A folder named in ' + path.join(this.folder, 'image.json') + ' is missing.' };
+        return {
+            image: { id: 'folder', layers: parsed.data.layers, utilityVmFiles: parsed.data.utilityVmFiles },
+            reason: '',
+        };
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null; // not JSON: the schema check then fails with a plain message
+    }
+}
+export function defaultImageStores() {
+    return [new FolderImageStore(), new DockerImageStore()];
+}
+/** The first image any store has, or every store's reason. */
+export function findImage(stores) {
+    const reasons = [];
+    for (const store of stores) {
+        const result = store.find();
+        if (result.image)
+            return result;
+        reasons.push(result.reason);
+    }
+    return { image: null, reason: reasons.join(' ') };
+}

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

@@ -0,0 +1,7 @@
+export type { SandboxEngine } from './engine.js';
+export type { EngineCapabilities, EngineCheck, EngineId, EnginePlan, LaunchDevices, LaunchPlan, RunningSandbox, } from './types.js';
+export { engineFor, engineReports, openEngine, type EngineReport } from './registry.js';
+export { WindowsSandboxEngine } from './windows-sandbox/engine.js';
+export { wsbText } from './windows-sandbox/wsb-text.js';
+export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
+export { checkHcs, realHcsProbes, type HcsProbes } from './hcs/check.js';

package/dist/host/engines/index.js

@@ -0,0 +1,5 @@
+export { engineFor, engineReports, openEngine } from './registry.js';
+export { WindowsSandboxEngine } from './windows-sandbox/engine.js';
+export { wsbText } from './windows-sandbox/wsb-text.js';
+export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
+export { checkHcs, realHcsProbes } from './hcs/check.js';

package/dist/host/engines/registry.d.ts

@@ -0,0 +1,16 @@
+import type { Config } from '../../core/types.js';
+import type { SandboxEngine } from './engine.js';
+import { type HcsProbes } from './hcs/check.js';
+import type { EngineCapabilities, EngineCheck, EngineId } from './types.js';
+/** The engine for the settings when nothing is looked up first (Windows Sandbox); hcs is opened with openEngine. */
+export declare function engineFor(config: Config): SandboxEngine;
+/** The engine to launch with. HCS is returned only when its check passes; otherwise this stops with the reasons. */
+export declare function openEngine(config: Config, hcsProbes?: HcsProbes): Promise<SandboxEngine>;
+export interface EngineReport {
+    readonly id: EngineId;
+    readonly inUse: boolean;
+    readonly capabilities: EngineCapabilities;
+    readonly check: EngineCheck;
+}
+/** Every engine with its capabilities and whether it can be used on this PC. */
+export declare function engineReports(config: Config, hcsProbes?: HcsProbes): Promise<EngineReport[]>;

package/dist/host/engines/registry.js

@@ -0,0 +1,30 @@
+import { fail } from '../../core/util/index.js';
+import { checkHcs, realHcsProbes } from './hcs/check.js';
+import { HCS_CAPABILITIES, HcsEngine } from './hcs/engine.js';
+import { WindowsSandboxEngine } from './windows-sandbox/engine.js';
+/** The engine for the settings when nothing is looked up first (Windows Sandbox); hcs is opened with openEngine. */
+export function engineFor(config) {
+    if (config.sandbox.engine === 'hcs')
+        fail('The HCS engine has to be opened first (its check looks at this PC).', 'Run: sandbox engine check hcs');
+    return new WindowsSandboxEngine(config.sandbox);
+}
+/** The engine to launch with. HCS is returned only when its check passes; otherwise this stops with the reasons. */
+export async function openEngine(config, hcsProbes) {
+    if (config.sandbox.engine === 'hcs')
+        return HcsEngine.open(config.storage.root, hcsProbes);
+    return engineFor(config);
+}
+/** Every engine with its capabilities and whether it can be used on this PC. */
+export async function engineReports(config, hcsProbes = realHcsProbes()) {
+    const windows = new WindowsSandboxEngine(config.sandbox);
+    const inUse = config.sandbox.engine;
+    return [
+        {
+            id: 'windows-sandbox',
+            inUse: inUse === 'windows-sandbox',
+            capabilities: windows.capabilities(),
+            check: await windows.check(),
+        },
+        { id: 'hcs', inUse: inUse === 'hcs', capabilities: HCS_CAPABILITIES, check: checkHcs(hcsProbes) },
+    ];
+}