windows-development-sandbox 1.7.0 → 1.9.0

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) },
+    ];
+}

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

@@ -0,0 +1,58 @@
+import type { Config, ResolvedMapping } from '../../core/types.js';
+import type { StorageAttachment } from '../storage/providers/index.js';
+export type EngineId = Config['sandbox']['engine'];
+export interface EngineCapabilities {
+    readonly desktop: boolean;
+    readonly gpu: boolean;
+    readonly clipboard: boolean;
+    readonly audio: boolean;
+    readonly video: boolean;
+    readonly printers: boolean;
+    /** Folders can be added to a running sandbox. */
+    readonly liveFolderAdd: boolean;
+    readonly attachedDisks: boolean;
+    readonly multipleInstances: boolean;
+    readonly hvsocket: boolean;
+}
+export interface EngineCheck {
+    readonly available: boolean;
+    readonly reasons: readonly string[];
+    readonly fixes: readonly string[];
+}
+export interface LaunchDevices {
+    readonly gpu: boolean;
+    readonly clipboard: boolean;
+    readonly audioInput: boolean;
+    readonly videoInput: boolean;
+    readonly printers: boolean;
+    readonly protectedClient: boolean;
+}
+/** One launch, whatever runs it. Pure data: nothing in it is engine-specific. */
+export interface LaunchPlan {
+    /** The launch folder: where an engine writes its own files. */
+    readonly launchPath: string;
+    readonly memoryMb: number;
+    /** Percent of this PC's CPU, or 'none'. The guest applies it; an engine may use it as a hint. */
+    readonly cpuLimit: 'none' | number;
+    readonly networking: boolean;
+    readonly devices: LaunchDevices;
+    /** Every folder shared in, in order (the folder attachments of `storage` are among them). */
+    readonly mappings: readonly ResolvedMapping[];
+    /** The command the guest runs at logon. */
+    readonly logonCommand: string;
+    readonly storage: readonly StorageAttachment[];
+}
+/** What an engine made of a LaunchPlan: files to write and the one to start from. Callers do not look inside. */
+export interface EnginePlan {
+    readonly engine: EngineId;
+    readonly files: readonly {
+        readonly path: string;
+        readonly text: string;
+    }[];
+    readonly entry: string;
+}
+export interface RunningSandbox {
+    readonly id: string;
+    readonly engine: EngineId;
+    readonly started: number;
+}

package/dist/host/engines/types.js

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

package/dist/host/engines/windows-sandbox/engine.d.ts

@@ -0,0 +1,16 @@
+import type { Config } from '../../../core/types.js';
+import type { SandboxEngine } from '../engine.js';
+import type { EngineCapabilities, EngineCheck, EnginePlan, LaunchPlan, RunningSandbox } from '../types.js';
+export declare class WindowsSandboxEngine implements SandboxEngine {
+    private readonly sandbox;
+    private readonly hasWsbCli;
+    readonly id = "windows-sandbox";
+    /** `hasWsbCli`: whether wsb.exe is on this PC (adding folders to a running sandbox needs it). */
+    constructor(sandbox: Config['sandbox'], hasWsbCli?: () => boolean);
+    capabilities(): EngineCapabilities;
+    check(): Promise<EngineCheck>;
+    plan(launch: LaunchPlan): EnginePlan;
+    start(plan: EnginePlan): Promise<RunningSandbox>;
+    running(): Promise<boolean>;
+    stop(): Promise<void>;
+}

package/dist/host/engines/windows-sandbox/engine.js

@@ -0,0 +1,63 @@
+// Windows Sandbox behind the engine interface: the .wsb file, and the existing start / wait / running code.
+import path from 'node:path';
+import { fail, isWin } from '../../../core/util/index.js';
+import { confirmSandboxStarted, findWsb, isSandboxRunning, sandboxFeatureInstalled, startSandbox, } from '../../sandbox/index.js';
+import { wsbText } from './wsb-text.js';
+const WSB_FILE = 'agent.wsb';
+export class WindowsSandboxEngine {
+    sandbox;
+    hasWsbCli;
+    id = 'windows-sandbox';
+    /** `hasWsbCli`: whether wsb.exe is on this PC (adding folders to a running sandbox needs it). */
+    constructor(sandbox, hasWsbCli = () => findWsb() !== null) {
+        this.sandbox = sandbox;
+        this.hasWsbCli = hasWsbCli;
+    }
+    capabilities() {
+        return {
+            desktop: true,
+            gpu: this.sandbox.vGpu,
+            clipboard: this.sandbox.clipboard,
+            audio: this.sandbox.audioInput,
+            video: this.sandbox.videoInput,
+            printers: this.sandbox.printerRedirection,
+            liveFolderAdd: this.hasWsbCli(),
+            attachedDisks: false,
+            multipleInstances: false,
+            hvsocket: false,
+        };
+    }
+    check() {
+        if (!isWin)
+            return Promise.resolve({
+                available: false,
+                reasons: ['Windows Sandbox only runs on Windows.'],
+                fixes: ['Use sandbox generate to only write the files.'],
+            });
+        if (!sandboxFeatureInstalled())
+            return Promise.resolve({
+                available: false,
+                reasons: ['Windows Sandbox is not enabled on this PC.'],
+                fixes: [
+                    'Run in an admin PowerShell, then reboot: Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All  (needs Windows Pro, Enterprise or Education)',
+                ],
+            });
+        return Promise.resolve({ available: true, reasons: [], fixes: [] });
+    }
+    plan(launch) {
+        const entry = path.join(launch.launchPath, WSB_FILE);
+        return { engine: this.id, files: [{ path: entry, text: wsbText(launch) }], entry };
+    }
+    async start(plan) {
+        startSandbox(plan.entry);
+        await confirmSandboxStarted(plan.entry);
+        return { id: path.basename(path.dirname(plan.entry)), engine: this.id, started: Date.now() };
+    }
+    running() {
+        return Promise.resolve(isSandboxRunning());
+    }
+    stop() {
+        // Windows Sandbox shuts itself down from inside, through the session channel; it is never killed from outside.
+        return Promise.resolve().then(() => fail('Windows Sandbox is not stopped from outside.', 'Use sandbox stop (it shuts down from inside).'));
+    }
+}

package/dist/host/engines/windows-sandbox/wsb-text.d.ts

@@ -0,0 +1,2 @@
+import type { LaunchPlan } from '../types.js';
+export declare function wsbText(plan: LaunchPlan): string;

package/dist/host/engines/windows-sandbox/wsb-text.js

@@ -0,0 +1,29 @@
+// The .wsb file Windows Sandbox starts from: memory, devices and the folders mapped in, written from a LaunchPlan.
+import { xmlEscape } from '../../../core/util/index.js';
+import { sandboxFolder } from '../../../shared/paths/index.js';
+function element(name, value) {
+    return '<' + name + '>' + value + '</' + name + '>';
+}
+function toggle(value) {
+    return value ? 'Enable' : 'Disable';
+}
+export function wsbText(plan) {
+    const d = plan.devices;
+    // Guest paths on other drive letters (F:\x) really live under C:\Mirror\F; bootstrap.ps1 substs F: onto it at boot.
+    const folders = plan.mappings
+        .map((m) => element('MappedFolder', element('HostFolder', xmlEscape(m.host)) +
+        element('SandboxFolder', xmlEscape(sandboxFolder(m.guest))) +
+        element('ReadOnly', String(m.readOnly))))
+        .join('');
+    // The elements are in the order Windows Sandbox expects.
+    return element('Configuration', element('MemoryInMB', String(plan.memoryMb)) +
+        element('vGPU', toggle(d.gpu)) +
+        element('Networking', toggle(plan.networking)) +
+        element('ClipboardRedirection', toggle(d.clipboard)) +
+        element('AudioInput', toggle(d.audioInput)) +
+        element('VideoInput', toggle(d.videoInput)) +
+        element('PrinterRedirection', toggle(d.printers)) +
+        element('ProtectedClient', toggle(d.protectedClient)) +
+        element('MappedFolders', folders) +
+        element('LogonCommand', element('Command', xmlEscape(plan.logonCommand))));
+}

package/dist/host/launch/generate.d.ts

@@ -1,4 +1,8 @@
 import type { GenerateOptions, Generated } from '../../core/types.js';
-export declare function generateSandbox(given: GenerateOptions): Generated & {
+import { type EnginePlan, type SandboxEngine } from '../engines/index.js';
+export declare function generateSandbox(given: GenerateOptions, 
+/** The engine launch.ts opened (hcs needs a look at this PC first); Windows Sandbox when left out. */
+opened?: SandboxEngine): Generated & {
     personalization: string;
+    enginePlan: EnginePlan;
 };