windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/channel/attach.js

@@ -25,7 +25,7 @@ export function isSandboxAddress(ip, interfaces = os.networkInterfaces()) {
         }));
 }
 /** Where this PC may connect for a session: only addresses on its own Hyper-V network (null if there are none). */
-const hostEndpoint = (session) => {
+export const hostEndpoint = (session) => {
     // Inside the sandbox every session is on loopback; on the PC only addresses on its Hyper-V network are trusted.
     const addresses = insideSandbox()
         ? ['127.0.0.1']
@@ -53,7 +53,7 @@ export async function findUnwatchedSession(dataPath, harness, cwd) {
     return null;
 }
 /** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
-export async function attachTerminal(session) {
+export async function attachTerminal(session, o = {}) {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         fail('--terminal / attach needs an interactive terminal.', 'Run it directly in Windows Terminal or PowerShell, not through a pipe or script.');
     if (!session.attach)
@@ -71,7 +71,10 @@ export async function attachTerminal(session) {
         safeText(session.cwd) +
         '). Detach any time with Ctrl+]');
     await sleep(400);
-    const result = await runTerminalClient(socket, session.attach.token, { detachKey: DETACH_KEY });
+    const result = await runTerminalClient(socket, session.attach.token, {
+        detachKey: DETACH_KEY,
+        clipboardWrites: o.clipboardWrites,
+    });
     switch (result.reason) {
         case 'detach':
             console.log('Detached. The session keeps running; reattach with: sandbox attach ' + session.id);

package/dist/host/channel/channel.d.ts

@@ -1,5 +1,12 @@
 import type { GuestRequest, GuestResponse, Harness, SandboxStatus, SessionStatus } from '../../core/types.js';
 import type { ProjectSpec } from '../../shared/channel/index.js';
+/**
+ * The boot script writes its first status once Windows has booted the sandbox and logged on (a minute or two, longer on
+ * a slow PC or the very first start); none after this long means it never got going.
+ */
+export declare const FIRST_STATUS_MS: number;
+/** True when a boot is silent: no status of this launch yet, and the sandbox had its time to write one. */
+export declare function bootSilent(elapsedMs: number, seenStatus: boolean, limitMs?: number): boolean;
 /** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
 export declare const MAX_QUERIED_SESSIONS = 32;
 /** Where progress lines go: printed by default; a spinner passes its own. Text from the sandbox, made safe first. */
@@ -39,6 +46,8 @@ export declare class SandboxChannel {
     exec(command: string[], cwd: string, timeoutSeconds: number): Promise<GuestResponse>;
     /** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
     restart(harness: string | null, cwd?: string): Promise<GuestResponse>;
+    /** The PC is low on memory or CPU: the sandbox slows its builds down for `seconds`. Never waits for an answer. */
+    pressure(reason: string, seconds: number): void;
     ping(): Promise<GuestResponse>;
     runningSessions(): SessionStatus[];
     /** Running sessions of the sandbox that is running now (its launch id), newest last, capped. */

package/dist/host/channel/channel.js

@@ -7,8 +7,18 @@ import { isWithin } from '../../shared/paths/index.js';
 import { now, RunDir } from '../../shared/channel/index.js';
 import { safeRemove, writeJsonAtomic } from '../../shared/io/index.js';
 import { isSandboxRunning } from '../sandbox/index.js';
+import { withoutSecrets, writeSecrets } from '../secrets/index.js';
 import { assertTestWritable, refuseInSelfTest } from '../test-guard.js';
 const BOOT_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * The boot script writes its first status once Windows has booted the sandbox and logged on (a minute or two, longer on
+ * a slow PC or the very first start); none after this long means it never got going.
+ */
+export const FIRST_STATUS_MS = 8 * 60 * 1000;
+/** True when a boot is silent: no status of this launch yet, and the sandbox had its time to write one. */
+export function bootSilent(elapsedMs, seenStatus, limitMs = FIRST_STATUS_MS) {
+    return !seenStatus && elapsedMs > limitMs;
+}
 /** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
 export const MAX_QUERIED_SESSIONS = 32;
 const printLine = (line) => console.log(line);
@@ -57,10 +67,20 @@ export class SandboxChannel {
      */
     waitForReady(launchId, progress = (m) => printLine('  [sandbox] ' + m), onStatus) {
         let last = '';
+        let seen = false;
+        const started = Date.now();
         return this.until(BOOT_TIMEOUT_MS, () => {
             const status = this.run.readSandboxStatus();
-            if (!status || (launchId !== null && status.launchId !== launchId))
+            if (!status || (launchId !== null && status.launchId !== launchId)) {
+                if (bootSilent(Date.now() - started, seen))
+                    fail('The sandbox has not reported anything for ' + Math.round(FIRST_STATUS_MS / 60000) + ' minutes.', 'It may still be starting, or it cannot reach its folders. Look at its window (sbx-show), the run folder ' +
+                        this.run.root +
+                        ' and the data folder ' +
+                        this.dataPath +
+                        ', and check that you can write to both. sandbox logs shows what happened.');
                 return null;
+            }
+            seen = true;
             onStatus?.(status);
             if (status.message !== last) {
                 progress(safeText(status.message).slice(0, 300));
@@ -77,7 +97,11 @@ export class SandboxChannel {
         if (request.kind === 'exec' && /shutdown/i.test(request.command[0] ?? ''))
             refuseInSelfTest('shut down Windows Sandbox');
         assertNoLinks(this.dataPath, this.run.requestsDir);
-        writeJsonAtomic(this.run.requestFile(request.id), request);
+        // Agent environment values (they may be API keys) never go into run: they travel in a one-shot file next to it.
+        const { request: plain, secrets } = withoutSecrets(request);
+        if (secrets)
+            writeSecrets(this.dataPath, request.id, secrets);
+        writeJsonAtomic(this.run.requestFile(request.id), plain);
     }
     waitForResponse(requestId, timeoutMs) {
         return this.until(timeoutMs, () => {
@@ -155,6 +179,10 @@ export class SandboxChannel {
         this.send({ kind: 'restart', id: requestId, harness, ...(cwd ? { cwd } : {}), createdAt: now() });
         return this.waitForResponse(requestId, 30000);
     }
+    /** The PC is low on memory or CPU: the sandbox slows its builds down for `seconds`. Never waits for an answer. */
+    pressure(reason, seconds) {
+        this.send({ kind: 'pressure', id: newId(), reason, seconds, createdAt: now() });
+    }
     async ping() {
         const requestId = newId();
         this.send({ kind: 'ping', id: requestId, createdAt: now() });

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

@@ -0,0 +1,12 @@
+import type { EngineCapabilities, EngineCheck, EngineId, EnginePlan, LaunchPlan, RunningSandbox } from './types.js';
+export interface SandboxEngine {
+    readonly id: EngineId;
+    capabilities(): EngineCapabilities;
+    check(): Promise<EngineCheck>;
+    /** Pure: the engine's own files for this launch. */
+    plan(launch: LaunchPlan): EnginePlan;
+    /** Starts the sandbox from a plan whose files are written, and waits until it is up. */
+    start(plan: EnginePlan): Promise<RunningSandbox>;
+    running(): Promise<boolean>;
+    stop(): Promise<void>;
+}

package/dist/host/engines/engine.js

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

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

@@ -0,0 +1,25 @@
+import type { EngineCheck } from '../types.js';
+import { type ImageStore } from './images.js';
+/** Windows 10 1809: the first build with the Host Compute Service API (Microsoft HCS overview). */
+export declare const MIN_BUILD = 17763;
+export interface TokenGroups {
+    /** The token is an elevated member of Administrators. */
+    readonly elevatedAdministrator: boolean;
+    /** The token has Hyper-V Administrators (S-1-5-32-578). */
+    readonly hyperVAdministrators: boolean;
+}
+/** Everything the check looks at, so tests give it a fake PC. */
+export interface HcsProbes {
+    isWindows(): boolean;
+    windowsBuild(): number | null;
+    /** Whether a Windows service exists; null when that could not be told. */
+    serviceInstalled(name: string): boolean | null;
+    fileExists(file: string): boolean;
+    tokenGroups(): TokenGroups | null;
+    imageStores(): readonly ImageStore[];
+}
+export declare function checkHcs(p: HcsProbes): EngineCheck;
+/** The groups of a token from `whoami /groups /fo csv /nh`: name, type, SID, attributes per line. */
+export declare function parseWhoamiGroups(csv: string): TokenGroups;
+/** The real probes: sc.exe query, whoami, file checks. They only read. */
+export declare function realHcsProbes(): HcsProbes;

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

@@ -0,0 +1,95 @@
+// The HCS engine's check: what this PC has and lacks. Read-only: it looks (service list, files, the token's groups)
+// and answers with the reasons and the exact commands that would fix each one. It NEVER runs a fix: turning on a
+// Windows feature or adding a group member is the owner's choice (docs/design/engines.md, "Never").
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM, system32 } from '../../../shared/system.js';
+import { isWin } from '../../../core/util/index.js';
+import { defaultImageStores, findImage } from './images.js';
+/** Windows 10 1809: the first build with the Host Compute Service API (Microsoft HCS overview). */
+export const MIN_BUILD = 17763;
+const ENABLE = 'Enable-WindowsOptionalFeature -Online -All -FeatureName ';
+export function checkHcs(p) {
+    const reasons = [];
+    const fixes = [];
+    const need = (reason, fix) => {
+        reasons.push(reason);
+        fixes.push(fix);
+    };
+    if (!p.isWindows())
+        return { available: false, reasons: ['The HCS engine only runs on Windows.'], fixes: ['Use "windows-sandbox".'] };
+    const build = p.windowsBuild();
+    if (build !== null && build < MIN_BUILD)
+        need('Windows build ' +
+            build +
+            ' is too old: the Host Compute Service needs Windows 10 1809 (build ' +
+            MIN_BUILD +
+            ') or newer.', 'Update Windows.');
+    if (!p.fileExists(path.join(system32Dir(), 'computecore.dll')))
+        need('computecore.dll (the Host Compute Service API) is not on this PC.', 'It comes with the Windows virtualization features (not in Windows Home). In an admin PowerShell, then restart: ' +
+            ENABLE +
+            'VirtualMachinePlatform  (the owner decides: this changes Windows)');
+    if (p.serviceInstalled('vmcompute') === false)
+        need('The Hyper-V Host Compute Service (vmcompute) is not installed.', 'In an admin PowerShell, then restart: ' +
+            ENABLE +
+            'Microsoft-Hyper-V-All  (needs Windows Pro, Enterprise or Education)');
+    if (p.serviceInstalled('cexecsvc') === false)
+        need('The Windows Containers feature is not turned on (its Container Execution Agent service is missing).', 'In an admin PowerShell, then restart: ' + ENABLE + 'Containers');
+    const token = p.tokenGroups();
+    if (token && !token.elevatedAdministrator && !token.hyperVAdministrators)
+        need('This Windows user is neither an elevated Administrator nor in Hyper-V Administrators, and the Host Compute Service refuses anyone else (HCS_E_ACCESS_DENIED, https://aka.ms/hcsadmin).', 'Either start the terminal as administrator, or in an admin PowerShell add yourself, then sign out and in: net localgroup "Hyper-V Administrators" "%USERDOMAIN%\\%USERNAME%" /add');
+    const image = findImage(p.imageStores());
+    if (!image.image)
+        need('No Windows Server Core (ltsc2022) image is on this PC. ' + image.reason, 'Pull one with Docker Desktop (Windows containers mode): docker pull mcr.microsoft.com/windows/servercore:ltsc2022  - or put your own in a folder with an image.json and set AGENT_SANDBOX_HCS_IMAGE to it. This tool does not download images in this alpha.');
+    return { available: reasons.length === 0, reasons, fixes };
+}
+function system32Dir() {
+    return path.dirname(system32('x'));
+}
+/** The groups of a token from `whoami /groups /fo csv /nh`: name, type, SID, attributes per line. */
+export function parseWhoamiGroups(csv) {
+    let elevated = false;
+    let hyperV = false;
+    for (const line of csv.split(/\r?\n/)) {
+        const cells = [...line.matchAll(/"([^"]*)"/g)].map((m) => m[1]);
+        if (cells.length < 4)
+            continue;
+        const [, , sid, attributes] = cells;
+        const denyOnly = /deny only/i.test(attributes);
+        if (sid === 'S-1-5-32-544' && !denyOnly)
+            elevated = true;
+        if (sid === 'S-1-5-32-578' && !denyOnly)
+            hyperV = true;
+    }
+    return { elevatedAdministrator: elevated, hyperVAdministrators: hyperV };
+}
+const QUERY_TIMEOUT_MS = 10000;
+/** The real probes: sc.exe query, whoami, file checks. They only read. */
+export function realHcsProbes() {
+    return {
+        isWindows: () => isWin,
+        windowsBuild: () => {
+            const m = /^\d+\.\d+\.(\d+)/.exec(os.release());
+            return m ? Number(m[1]) : null;
+        },
+        serviceInstalled: (name) => {
+            const r = spawnSync(SYSTEM.sc(), ['query', name], { windowsHide: true, timeout: QUERY_TIMEOUT_MS });
+            if (r.status === 0)
+                return true;
+            return r.status === 1060 ? false : null; // 1060: the service does not exist
+        },
+        fileExists: (file) => fs.existsSync(file),
+        tokenGroups: () => {
+            const r = spawnSync(SYSTEM.whoami(), ['/groups', '/fo', 'csv', '/nh'], {
+                windowsHide: true,
+                timeout: QUERY_TIMEOUT_MS,
+                encoding: 'utf8',
+                maxBuffer: 1024 * 1024,
+            });
+            return r.status === 0 ? parseWhoamiGroups(r.stdout) : null;
+        },
+        imageStores: () => defaultImageStores(),
+    };
+}

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

@@ -0,0 +1,44 @@
+import type { LaunchPlan } from '../types.js';
+export declare const HCS_OWNER = "agent-sandbox";
+/** The Container's Windows-side folder for the agent disk's own sub-folders. */
+export declare const AGENT_DISK_FOLDERS: readonly ["tools", "state", "logs"];
+export type HcsDocument = Readonly<Record<string, unknown>>;
+/** A base image already on this PC. Layers are the folders of the image, base layer first. */
+export interface HcsImage {
+    readonly id: string;
+    /** Folders of the image layers, base first. */
+    readonly layers: readonly string[];
+    /** The base layer's UtilityVM\Files folder (the kernel and files of the utility VM). */
+    readonly utilityVmFiles: string;
+}
+export interface HcsDocumentInput {
+    readonly launch: LaunchPlan;
+    readonly image: HcsImage;
+    /** The utility VM's id; the container's is `<id>-c`. [a-zA-Z0-9._-] only. */
+    readonly id: string;
+    /** The writable layer (scratch) VHDX of this run: made before start, deleted after. */
+    readonly scratchVhdx: string;
+    /** Processors of this PC, to turn a CPU percentage into a count. */
+    readonly hostCpus: number;
+}
+export interface HcsDiskPlan {
+    readonly image: string;
+    readonly maxGb: number;
+    readonly lun: number;
+}
+export interface HcsDocuments {
+    readonly uvmId: string;
+    readonly containerId: string;
+    readonly uvm: HcsDocument;
+    readonly container: HcsDocument;
+    /** The agent disks (read-write) to create, give the utility VM access to and attach. */
+    readonly disks: readonly HcsDiskPlan[];
+    /** Things the plan asked for that this engine does not do (shown to the user). */
+    readonly notes: readonly string[];
+}
+/** A GUID made from a path, so a layer has the same id every time. [U] hcsshim names layers the same way. */
+export declare function layerGuid(folder: string): string;
+export declare function containerId(uvmId: string): string;
+/** Processors for a percentage of this PC ('none' = all of them), at least one. */
+export declare function cpuCount(limit: LaunchPlan['cpuLimit'], hostCpus: number): number;
+export declare function buildDocuments(input: HcsDocumentInput): HcsDocuments;

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

@@ -0,0 +1,155 @@
+// Pure: the HCS compute-system documents (schema 2.x JSON) for a Hyper-V isolated Windows container, from a
+// LaunchPlan.
+//
+// Two documents, as hcsshim does it for a container with Hyper-V isolation:
+//   1. the utility VM: ComputeSystem { VirtualMachine { Chipset, ComputeTopology,
+//      Devices { Scsi, VirtualSmb, HvSocket }, GuestConnection } }
+//   2. the container inside it: ComputeSystem { HostingSystemId, HostedSystem { Container { GuestOs, Storage, Memory,
+//      MappedDirectories, HvSocket } } }
+//
+// Schema reference used (learn.microsoft.com/virtualization/api/hcs/schemareference), field names and casing taken
+// from these tables: ComputeSystem, VirtualMachine, Topology, VirtualMachine_Memory, VirtualMachine_Processor,
+// Devices, Scsi, Attachment (AttachmentType "VirtualDisk", CachingMode), VirtualSmb, VirtualSmbShare,
+// VirtualSmbShareOptions, VirtualMachine_HvSocket, HvSocketSystemConfig, Chipset, Uefi, UefiBootEntry,
+// GuestConnection, HostedSystem, Container, GuestOs, Container_Memory, Layer (PathType "VirtualSmbShareName"),
+// MappedDirectory (HostPathType), Container_HvSocket, Version.
+//
+// NOT verified (each is marked [U] where it is used, and listed in the report):
+//   - the boot entry of the utility VM and the "os" share of the base layer's UtilityVM\Files (hcsshim from memory);
+//   - the order of the layers (topmost first here);
+//   - where a SCSI disk appears inside the utility VM and how a blank VHDX becomes a formatted volume there;
+//   - the scratch layer (a writable layer VHDX made by HcsInitializeWritableLayer: not built in this phase);
+//   - that Layers / MappedDirectories may name vSMB shares by share name (the PathType values exist in the schema).
+import crypto from 'node:crypto';
+export const HCS_OWNER = 'agent-sandbox';
+/** Schema 2.1 is the first with VirtualSmb options, SCSI caching and Layer.PathType (Windows 10 1809). */
+const SCHEMA = { Major: 2, Minor: 1 };
+/** The Container's Windows-side folder for the agent disk's own sub-folders. */
+export const AGENT_DISK_FOLDERS = ['tools', 'state', 'logs'];
+const GUEST_DATA = 'C:\\AgentData';
+/** Placeholder SDDL: SYSTEM and Administrators only. [U] whether this ACL is what the host side of HvSocket needs. */
+const HVSOCKET_SDDL = 'D:P(A;;FA;;;SY)(A;;FA;;;BA)';
+/** A GUID made from a path, so a layer has the same id every time. [U] hcsshim names layers the same way. */
+export function layerGuid(folder) {
+    const h = crypto.createHash('sha1').update(folder.toLowerCase()).digest('hex');
+    return [h.slice(0, 8), h.slice(8, 12), '5' + h.slice(13, 16), '8' + h.slice(17, 20), h.slice(20, 32)].join('-');
+}
+export function containerId(uvmId) {
+    return uvmId + '-c';
+}
+/** Processors for a percentage of this PC ('none' = all of them), at least one. */
+export function cpuCount(limit, hostCpus) {
+    if (limit === 'none')
+        return Math.max(1, hostCpus);
+    return Math.min(Math.max(1, hostCpus), Math.max(1, Math.ceil((hostCpus * limit) / 100)));
+}
+const hvSocketConfig = {
+    DefaultBindSecurityDescriptor: HVSOCKET_SDDL,
+    DefaultConnectSecurityDescriptor: HVSOCKET_SDDL,
+    ServiceTable: {},
+};
+export function buildDocuments(input) {
+    const { launch, image } = input;
+    const notes = [];
+    const uvmId = input.id;
+    const baseLayers = [...image.layers].reverse(); // topmost first [U]
+    // Utility VM shares: the OS files, each image layer, then the folders shared in.
+    const shares = [
+        {
+            Name: 'os',
+            Path: image.utilityVmFiles,
+            // [U] the options hcsshim gives the OS share of a Windows utility VM.
+            Options: { ReadOnly: true, ShareRead: true, CacheIo: true, TakeBackupPrivilege: true, PseudoOplocks: true },
+        },
+    ];
+    const layers = baseLayers.map((folder, i) => {
+        const name = 'layer' + i;
+        shares.push({ Name: name, Path: folder, Options: { ReadOnly: true, ShareRead: true, NoDirectmap: true } });
+        return { Id: layerGuid(folder), Path: name, PathType: 'VirtualSmbShareName' };
+    });
+    const folderMaps = [];
+    launch.mappings.forEach((m, i) => {
+        const name = 'dir' + i;
+        // NoDirectmap on every folder shared in: no direct file mapping into the guest.
+        shares.push({ Name: name, Path: m.host, Options: { ReadOnly: m.readOnly, NoDirectmap: true } });
+        folderMaps.push({
+            HostPath: name,
+            HostPathType: 'VirtualSmbShareName',
+            ContainerPath: m.guest,
+            ReadOnly: m.readOnly,
+        });
+    });
+    // SCSI controller 0: the agent disks (read-write), then the scratch layer.
+    const disks = [];
+    const attachments = {};
+    const attach = (file, readOnly, lun) => {
+        attachments[String(lun)] = { Type: 'VirtualDisk', Path: file, ReadOnly: readOnly, CachingMode: 'Uncached' };
+    };
+    for (const a of launch.storage) {
+        if (a.kind !== 'disk')
+            continue;
+        const lun = disks.length;
+        disks.push({ image: a.image, maxGb: a.maxGb, lun });
+        attach(a.image, false, lun);
+        // [U] the disk is formatted and mounted in the utility VM at this folder (a blank VHDX is not formatted yet).
+        const volume = 'C:\\agent-disk' + lun;
+        const target = a.guest || GUEST_DATA;
+        for (const folder of AGENT_DISK_FOLDERS)
+            folderMaps.push({
+                HostPath: volume + '\\' + folder,
+                HostPathType: 'AbsolutePath',
+                ContainerPath: target + '\\' + folder,
+                ReadOnly: false,
+            });
+    }
+    attach(input.scratchVhdx, false, disks.length);
+    if (launch.networking)
+        notes.push('Networking is not available in the HCS engine yet: the sandbox has no network adapter.');
+    if (launch.devices.gpu || launch.devices.clipboard || launch.devices.audioInput || launch.devices.videoInput)
+        notes.push('GPU, clipboard, microphone and camera do not exist in the HCS engine.');
+    const uvm = {
+        Owner: HCS_OWNER,
+        SchemaVersion: SCHEMA,
+        // false on purpose: the helper exits after creating the system, which closes its handle; true would end the
+        // system at once. Leftovers are found by owner (sandbox engine clean).
+        ShouldTerminateOnLastHandleClosed: false,
+        VirtualMachine: {
+            StopOnReset: true,
+            Chipset: {
+                // [U] hcsshim's boot entry for a Windows utility VM.
+                Uefi: { BootThis: { DeviceType: 'VmbFs', DevicePath: '\\EFI\\Microsoft\\Boot\\bootmgfw.efi' } },
+            },
+            ComputeTopology: {
+                Memory: { SizeInMB: launch.memoryMb, AllowOvercommit: true },
+                Processor: { Count: cpuCount(launch.cpuLimit, input.hostCpus) },
+            },
+            Devices: {
+                Scsi: { '0': { Attachments: attachments } },
+                VirtualSmb: { Shares: shares },
+                // Placeholder: the control channel's service ids are added when the guest side exists.
+                HvSocket: { HvSocketConfig: hvSocketConfig },
+                // No NetworkAdapters: no network by default.
+            },
+            GuestConnection: {},
+        },
+    };
+    const container = {
+        Owner: HCS_OWNER,
+        SchemaVersion: SCHEMA,
+        ShouldTerminateOnLastHandleClosed: false,
+        HostingSystemId: uvmId,
+        HostedSystem: {
+            SchemaVersion: SCHEMA,
+            Container: {
+                GuestOs: { HostName: 'agent-sandbox' },
+                // [U] Path is the scratch layer's folder as the utility VM sees it.
+                Storage: { Layers: layers, Path: 'C:\\scratch' },
+                Memory: { SizeInMB: launch.memoryMb },
+                MappedDirectories: folderMaps,
+                HvSocket: { Config: hvSocketConfig },
+                // No Networking section: no endpoint.
+            },
+        },
+    };
+    return { uvmId, containerId: containerId(uvmId), uvm, container, disks, notes };
+}

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

@@ -0,0 +1,39 @@
+import type { SandboxEngine } from '../engine.js';
+import type { EngineCapabilities, EngineCheck, EnginePlan, LaunchPlan, RunningSandbox } from '../types.js';
+import { type HcsProbes } from './check.js';
+import { type HcsImage } from './documents.js';
+import { HcsHelper } from './helper.js';
+export declare const HCS_CAPABILITIES: EngineCapabilities;
+export declare const HCS_ALPHA_MESSAGE = "The HCS engine is in alpha and starting it is not enabled yet; see docs/design/engines.md";
+export declare const HCS_FLAG = "AGENT_SANDBOX_HCS_EXPERIMENTAL";
+/** Starting is allowed only with the owner's flag, and never inside the self-test. */
+export declare function hcsStartEnabled(env: NodeJS.ProcessEnv, selfTest: boolean): boolean;
+export interface HcsEngineDeps {
+    readonly helper?: HcsHelper;
+    readonly env?: NodeJS.ProcessEnv;
+    /** Inside the self-test, starting is refused whatever the flag says. */
+    readonly selfTest?: () => boolean;
+    readonly hostCpus?: () => number;
+    readonly exists?: (file: string) => boolean;
+}
+export declare class HcsEngine implements SandboxEngine {
+    private readonly image;
+    private readonly probes;
+    private readonly storageRoot;
+    private readonly deps;
+    readonly id = "hcs";
+    /** `image` and `probes` come from the check (see HcsEngine.open); `storageRoot` is where HcsHost.exe is built. */
+    constructor(image: HcsImage | null, probes: HcsProbes, storageRoot: string, deps?: HcsEngineDeps);
+    /** The engine for this PC when its check passes; otherwise a clear stop with the check's reasons and fixes. */
+    static open(storageRoot: string, probes?: HcsProbes, deps?: HcsEngineDeps): Promise<HcsEngine>;
+    capabilities(): EngineCapabilities;
+    check(): Promise<EngineCheck>;
+    plan(launch: LaunchPlan): EnginePlan;
+    private helper;
+    start(plan: EnginePlan): Promise<RunningSandbox>;
+    private tryTerminate;
+    /** Ours: the compute systems the helper lists with our owner name. */
+    private ours;
+    running(): Promise<boolean>;
+    stop(): Promise<void>;
+}