windows-development-sandbox 1.7.0 → 1.9.0

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

@@ -1,8 +1,10 @@
 import type net from 'node:net';
+import type { RpcHost } from '../../app/kernel/index.js';
 import type { Endpoint } from '../../shared/pty/index.js';
 import type { WebBackend } from './backend.js';
 /** No inline script: the page and its script are files from this server. Inline styles are what xterm.js needs. */
 export declare const CONTENT_SECURITY_POLICY: string;
+export declare const RPC_PATH = "/api/rpc";
 export interface WebServerOptions {
     /** 0 picks a free port (tests). */
     readonly port: number;
@@ -14,6 +16,8 @@ export interface WebServerOptions {
     readonly onStop?: () => void;
     /** How terminals reach a session (tests use a fake on loopback). */
     readonly dial?: (endpoint: Endpoint) => Promise<net.Socket>;
+    /** The shared core's operations and queries the browser may run (none: /api/rpc is not served). */
+    readonly rpc?: RpcHost;
 }
 export declare class WebServer {
     private readonly options;
@@ -22,6 +26,7 @@ export declare class WebServer {
     private readonly auth;
     private readonly files;
     private terminals;
+    private rpcSockets;
     private actualPort;
     constructor(options: WebServerOptions);
     get port(): number;
@@ -37,4 +42,6 @@ export declare class WebServer {
     /** A small JSON body (application/json only). */
     private body;
     private upgrade;
+    /** The RPC socket (after the same Origin and cookie checks as a terminal). */
+    private upgradeRpc;
 }

package/dist/host/web/server.js

@@ -1,5 +1,6 @@
-// The web UI's HTTP server: the app's files, a small JSON API for sessions, and the terminal WebSocket. Loopback only;
-// nothing works without the token's cookie, and Host / Origin / CSRF checks keep other sites out (docs/web-ui.md).
+// The web UI's HTTP server: the app's files, a small JSON API for sessions, the terminal WebSocket and the RPC
+// WebSocket of the shared core. Loopback only; nothing works without the token's cookie, and Host / Origin / CSRF
+// checks keep other sites out (docs/web-ui.md).
 import fs from 'node:fs';
 import http from 'node:http';
 import { WebSocketServer } from 'ws';
@@ -7,13 +8,16 @@ import { UserError, safeText } from '../../core/util/index.js';
 import { MAX_CLIENT_MESSAGE_BYTES, MAX_COLS, MAX_ROWS, MIN_COLS, MIN_ROWS, } from '../../shared/web/index.js';
 import { cookieHeader, csrfOk, hostAllowed, originAllowed, WebAuth } from './auth.js';
 import { TerminalBridge } from './bridge.js';
+import { RpcSession } from './rpc.js';
 import { StaticFiles } from './static-files.js';
 /** No inline script: the page and its script are files from this server. Inline styles are what xterm.js needs. */
 export const CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; " +
     "connect-src 'self'; font-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'";
 const MAX_BODY_BYTES = 16 * 1024;
 const MAX_TERMINALS = 16;
+const MAX_RPC_SOCKETS = 8;
 const SESSION_PATH = /^\/api\/sessions\/([A-Za-z0-9_-]{1,64})\/terminal$/;
+export const RPC_PATH = '/api/rpc';
 class HttpFailure extends Error {
     status;
     constructor(status, message) {
@@ -32,6 +36,7 @@ export class WebServer {
     auth;
     files;
     terminals = 0;
+    rpcSockets = 0;
     actualPort = 0;
     constructor(options) {
         this.options = options;
@@ -184,13 +189,18 @@ export class WebServer {
         };
         const url = new URL(req.url ?? '/', 'http://127.0.0.1');
         const match = SESSION_PATH.exec(url.pathname);
-        if (!match)
+        const rpc = url.pathname === RPC_PATH ? this.options.rpc : undefined;
+        if (!match && !rpc)
             return refuse('404 Not Found');
         // The Origin must be this page (a page of another site can open WebSockets too) and the cookie is the login.
         if (!originAllowed(req.headers.origin, req.headers.host, this.actualPort))
             return refuse('403 Forbidden');
         if (!this.auth.signedIn(req.headers.cookie))
             return refuse('401 Unauthorized');
+        if (rpc)
+            return this.upgradeRpc(req, socket, head, rpc, refuse);
+        if (!match)
+            return refuse('404 Not Found');
         if (this.terminals >= MAX_TERMINALS)
             return refuse('503 Service Unavailable');
         const endpoint = this.options.backend.endpoint(match[1]);
@@ -204,6 +214,16 @@ export class WebServer {
             void new TerminalBridge(ws, endpoint, cols, rows, this.options.dial).start();
         });
     }
+    /** The RPC socket (after the same Origin and cookie checks as a terminal). */
+    upgradeRpc(req, socket, head, rpc, refuse) {
+        if (this.rpcSockets >= MAX_RPC_SOCKETS)
+            return refuse('503 Service Unavailable');
+        this.sockets.handleUpgrade(req, socket, head, (ws) => {
+            this.rpcSockets++;
+            ws.on('close', () => this.rpcSockets--);
+            new RpcSession(ws, rpc).start();
+        });
+    }
 }
 function bounded(text, min, max, fallback) {
     const n = Number(text);

package/dist/runtime/agent.js

@@ -5553,6 +5553,7 @@ var SYSTEM = {
   shutdown: () => system32("shutdown.exe"),
   dism: () => system32("Dism.exe"),
   msiexec: () => system32("msiexec.exe"),
+  sc: () => system32("sc.exe"),
   /** The .NET Framework C# compiler that ships with Windows (C# 5). */
   csc: () => path.join(systemRoot(), "Microsoft.NET", "Framework64", "v4.0.30319", "csc.exe")
 };
@@ -25378,6 +25379,9 @@ var HarnessSchema = external_exports.strictObject({
   localState: external_exports.record(external_exports.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), SubfolderSchema).optional().describe(
     "Environment variable -> folder below the agent's own state folder (state\\<agent>) for SQLite databases. SQLite cannot run in a mapped folder, so the agent runs from a copy on the sandbox's disk (the variable points to it) that is copied from and back to that folder."
   ),
+  bootReset: external_exports.array(SubfolderSchema).max(32).optional().describe(
+    "Files and folders below the agent's own state folder (state\\<agent>) that only work on the machine that wrote them (keys sealed with Windows DPAPI, local accounts it created). Every sandbox is a new machine, so they are deleted at each boot and the agent sets them up again."
+  ),
   resumeArguments: StringsSchema.optional().describe(
     "Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation."
   ),
@@ -25455,6 +25459,9 @@ var MappingSchema = external_exports.strictObject({
   optional: external_exports.boolean().optional().describe("true = skip it quietly when the host folder does not exist.")
 });
 var SandboxSchema = external_exports.strictObject({
+  engine: external_exports.enum(["windows-sandbox", "hcs"]).describe(
+    '(alpha) What runs the sandbox. "windows-sandbox" = Windows Sandbox (the default: desktop, Windows Terminal, GPU, clipboard, audio, printers). "hcs" = a headless Hyper-V isolated Server Core container for agents (no desktop, GPU or clipboard); it needs Windows features and an image on this PC (sandbox engine check hcs lists what is missing), and starting it is not enabled yet in this alpha. sandbox engine shows what each engine can do. Yours only: a project file (.sandbox-config.json) cannot set it.'
+  ),
   memoryMb: external_exports.union([external_exports.literal("auto"), external_exports.number().int().min(2048)]).describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb.'),
   maxMemoryMb: external_exports.number().int().positive().describe('Upper limit for memoryMb "auto".'),
   maxMemoryPercent: external_exports.number().int().min(10).max(100).describe(`memoryMb "auto" never takes more than this share of this PC's total RAM (percent).`),
@@ -25464,10 +25471,22 @@ var SandboxSchema = external_exports.strictObject({
   pageFileMb: external_exports.number().int().min(0).max(262144).describe(
     `Size of the sandbox's paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with "The paging file is too small", and Windows grows the file under load. 0 = leave Windows' own.`
   ),
-  reserveHostMb: external_exports.number().int().nonnegative().describe('RAM always left for this PC when memoryMb is "auto".'),
-  vGpu: external_exports.boolean().describe("Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface."),
+  reserveHostMb: external_exports.number().int().nonnegative().describe(
+    'Memory always left for this PC when memoryMb is "auto": the sandbox gets at most (free RAM, and RAM plus paging file still unused) minus this.'
+  ),
+  agentMemoryHeadroomMb: external_exports.union([external_exports.literal("auto"), external_exports.literal("none"), external_exports.number().int().min(0)]).describe(
+    'Memory kept out of the agents reach inside the sandbox, in MB: everything the agents start (their builds, tests, tools) together may use at most the sandbox memory minus this; a runaway parallel build then gets out-of-memory errors in its own session instead of freezing or crashing the whole sandbox. "auto" = the larger of 2048 MB and 10 % of the sandbox memory; "none" = no limit. Yours only: a project file cannot change it.'
+  ),
+  pressureResponse: external_exports.boolean().describe(
+    "When the sandbox (or this PC) runs low on memory, slow the heaviest build programs down (lower priority) and, if that is not enough, pause the biggest compiler for a few seconds at a time, so heavy parallel builds slow down instead of closing the sandbox. Never touches the agents themselves. Yours only: a project file cannot change it."
+  ),
+  vGpu: external_exports.boolean().describe(
+    "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface. The sandbox then uses this PC's graphics card, and with some graphics drivers heavy use can freeze the whole PC: turn it on only when a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it)."
+  ),
   networking: external_exports.boolean().describe("Internet access. false is the only hard network isolation Windows Sandbox offers."),
-  clipboard: external_exports.boolean().describe("Shared clipboard between this PC and the sandbox."),
+  clipboard: external_exports.boolean().describe(
+    "Shared clipboard between this PC and the sandbox. Also lets an agent's copy (in sandbox attach) reach this PC's clipboard."
+  ),
   audioInput: external_exports.boolean().describe("Microphone access."),
   videoInput: external_exports.boolean().describe("Camera access."),
   printerRedirection: external_exports.boolean().describe("Printers from this PC."),
@@ -26549,18 +26568,18 @@ var WebSchema = external_exports.strictObject({
 });
 
 // src/core/schema/vpn.ts
-var VPN_PROVIDERS = ["nordvpn", "openvpn-file"];
+var VPN_PROVIDERS = ["nordvpn", "openvpn-file", "wireguard-file"];
 var VpnSchema = external_exports.strictObject({
   enabled: external_exports.boolean().describe(
     "Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (sandbox vpn login). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."
   ),
   provider: external_exports.enum(VPN_PROVIDERS).describe(
-    "nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile)."
+    "nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile). wireguard-file: your own WireGuard .conf (configFile), e.g. from your company."
   ),
   protocol: external_exports.enum(["udp", "tcp"]).describe("udp is faster; tcp gets through networks that block udp."),
   country: external_exports.string().regex(/^([A-Za-z][A-Za-z .'-]{0,39})?$/, "a country name or code like uk or Germany").describe("nordvpn: the country of the server, e.g. uk, us or Germany. Empty = the best server anywhere."),
   configFile: external_exports.string().describe(
-    "openvpn-file: the .ovpn file on this PC (its certificates inside it). Files that run programs (script-security, up, down, plugin ...) are refused. A project's file can never set this."
+    "openvpn-file / wireguard-file: the .ovpn or .conf file on this PC (an .ovpn has its certificates inside it). Files that run programs (script-security, up, down, plugin, PostUp ...) are refused. A WireGuard file holds your private key: it is read when a sandbox starts and handed over in a one-shot file. A project's file can never set this."
   ),
   killSwitch: external_exports.boolean().describe(
     "Block all traffic that does not go through the tunnel: when the tunnel cannot start, the sandbox stays offline instead of using your normal connection. A project can only turn this on, never off."
@@ -26587,6 +26606,10 @@ var ConfigSchema = external_exports.strictObject({
     markSandboxFiles: external_exports.boolean().describe(
       `Programs and scripts (.exe, .ps1, .bat, .cmd, .msi, .lnk ...) that appear or change in your project while a sandbox runs get Windows' "downloaded from the internet" mark, so SmartScreen and PowerShell ask before they run on this PC.`
     ),
+    contained: external_exports.enum(["off", "vhdx"]).describe(
+      '(beta) Keep the sandbox tools, state and logs inside one disk image file (vhdx) instead of loose folders, so scanning programs on this PC see one file. Not yet tried on a real PC. Turn it on with sandbox storage contained on (it moves your files and asks first); Windows asks for permission to mount the image when a sandbox starts. "off" = loose folders, as always. Yours only: a project file (.sandbox-config.json) cannot set it.'
+    ),
+    containedMaxGb: external_exports.number().int().min(8).max(4096).describe("(beta) Largest size, in GB, the disk image of storage.contained may grow to."),
     warnDataGb: external_exports.number().min(0).describe(
       "Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. sandbox data shows what takes the space."
     )
@@ -26630,7 +26653,13 @@ var LocalOverridesSchema = external_exports.strictObject({
     "Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent."
   ),
   // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
-  sandbox: SandboxSchema.omit({ cpuLimit: true, pageFileMb: true }).partial(),
+  sandbox: SandboxSchema.omit({
+    cpuLimit: true,
+    pageFileMb: true,
+    engine: true,
+    agentMemoryHeadroomMb: true,
+    pressureResponse: true
+  }).partial(),
   // A project may block more (the LAN, hosts); it never opens hosts, ports, DNS or a proxy.
   network: NetworkSchema.pick({ blockPrivateRanges: true, blockHosts: true }).partial(),
   // A project may turn the kill switch on, never off, and never choose a VPN, a server, a file or a login.
@@ -26739,8 +26768,34 @@ var GuestRequestSchema = external_exports.discriminatedUnion("kind", [
     cwd: Text().optional(),
     createdAt: TimeSchema
   }),
-  external_exports.strictObject({ kind: external_exports.literal("ping"), id: IdSchema, createdAt: TimeSchema })
+  external_exports.strictObject({ kind: external_exports.literal("ping"), id: IdSchema, createdAt: TimeSchema }),
+  /**
+   * The PC's own memory or CPU is running low (the host watchdog): the sandbox slows its heaviest builds down for
+   * `seconds` (it never stops them) so Windows does not have to close it. Repeated while the PC stays low.
+   */
+  external_exports.strictObject({
+    kind: external_exports.literal("pressure"),
+    id: IdSchema,
+    reason: Text(300),
+    seconds: external_exports.number().int().min(10).max(300),
+    createdAt: TimeSchema
+  })
 ]);
+var PressureStatusSchema = external_exports.object({
+  level: external_exports.enum(["ok", "throttled", "suspending"]),
+  profile: external_exports.enum(["normal", "gentle"]),
+  /** Share of the sandbox's RAM still free and of its commit limit in use (percent). */
+  ramFreePercent: external_exports.number().int().min(0).max(100),
+  commitPercent: external_exports.number().int().min(0).max(100),
+  /** Programs running at lower priority because of it. */
+  lowered: external_exports.number().int().min(0).max(1024),
+  /** Programs paused right now (name, process id, seconds left). */
+  paused: external_exports.array(external_exports.object({ name: Text(64), pid: external_exports.number().int(), seconds: external_exports.number().int().min(0).max(60) })).max(8),
+  /** The PC itself asked for slowing down (its memory or CPU is low). */
+  pcLow: external_exports.boolean(),
+  lastAction: Text(300),
+  updatedAt: TimeSchema
+});
 var GuestResponseSchema = external_exports.object({
   id: IdSchema,
   ok: external_exports.boolean(),
@@ -26920,6 +26975,8 @@ var RunDir = class {
   root;
   sandboxFile;
   vpnFile;
+  /** What the memory governor in the sandbox is doing (pressure.json). */
+  pressureFile;
   requestsDir;
   responsesDir;
   sessionsDir;
@@ -26932,6 +26989,7 @@ var RunDir = class {
     this.root = path5.join(dataDir2, "run");
     this.sandboxFile = path5.join(this.root, "sandbox.json");
     this.vpnFile = path5.join(this.root, "vpn.json");
+    this.pressureFile = path5.join(this.root, "pressure.json");
     this.requestsDir = path5.join(this.root, "requests");
     this.responsesDir = path5.join(this.root, "responses");
     this.sessionsDir = path5.join(this.root, "sessions");
@@ -26960,6 +27018,9 @@ var RunDir = class {
   readVpnStatus() {
     return readValid(VpnStatusSchema, this.vpnFile);
   }
+  readPressure() {
+    return readValid(PressureStatusSchema, this.pressureFile);
+  }
   readSession(id) {
     return readValid(SessionStatusSchema, this.sessionFile(id));
   }