windows-development-sandbox 1.9.0 → 1.11.3

package/dist/host/web/server.js

@@ -5,9 +5,10 @@ import fs from 'node:fs';
 import http from 'node:http';
 import { WebSocketServer } from 'ws';
 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 { 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 { LiveHub } from './live.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. */
@@ -16,6 +17,10 @@ export const CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self'; s
 const MAX_BODY_BYTES = 16 * 1024;
 const MAX_TERMINALS = 16;
 const MAX_RPC_SOCKETS = 8;
+/** Every socket is pinged this often; one that has not answered the last ping by the next is dropped. */
+const HEARTBEAT_MS = 20_000;
+/** The server ends after this long with no request, no socket and no sandbox running (it starts again with one). */
+export const IDLE_EXIT_MS = 30 * 60_000;
 const SESSION_PATH = /^\/api\/sessions\/([A-Za-z0-9_-]{1,64})\/terminal$/;
 export const RPC_PATH = '/api/rpc';
 class HttpFailure extends Error {
@@ -35,15 +40,23 @@ export class WebServer {
     });
     auth;
     files;
-    terminals = 0;
-    rpcSockets = 0;
+    tracked = new Map();
+    /** One poll per live query for all browsers together. */
+    live;
     actualPort = 0;
+    lastUsed = Date.now();
+    heartbeat;
+    idleCheck;
     constructor(options) {
         this.options = options;
         this.auth = new WebAuth(options.token);
         this.files = new StaticFiles(options.staticRoot);
+        this.live = options.rpc ? new LiveHub(options.rpc) : undefined;
         this.server = http.createServer((req, res) => void this.handle(req, res));
-        this.server.on('upgrade', (req, socket, head) => this.upgrade(req, socket, head));
+        this.server.on('upgrade', (req, socket, head) => {
+            this.lastUsed = Date.now();
+            this.upgrade(req, socket, head);
+        });
         this.server.headersTimeout = 15000;
         this.server.requestTimeout = 0; // creating a session waits for the agent to start
     }
@@ -56,11 +69,75 @@ export class WebServer {
             this.server.listen(this.options.port, '127.0.0.1', () => {
                 this.server.off('error', reject);
                 this.actualPort = this.server.address().port;
+                this.heartbeat = setInterval(() => this.beat(), this.options.heartbeatMs ?? HEARTBEAT_MS);
+                this.heartbeat.unref();
+                if (this.options.idleExitMs) {
+                    this.idleCheck = setInterval(() => void this.checkIdle(), Math.min(60_000, this.options.idleExitMs));
+                    this.idleCheck.unref();
+                }
                 resolve();
             });
         });
     }
+    /** How many browser sockets are open, by kind. */
+    openSockets(kind) {
+        return [...this.tracked.values()].filter((t) => t.kind === kind).length;
+    }
+    /**
+     * Drops sockets that did not answer the last ping (a tab that went away without closing: sleep, a killed browser),
+     * so they never hold a slot or a session connection.
+     */
+    beat() {
+        for (const [ws, t] of this.tracked) {
+            if (!t.alive) {
+                ws.terminate();
+                continue;
+            }
+            t.alive = false;
+            try {
+                ws.ping();
+            }
+            catch {
+                ws.terminate(); // the socket broke between the check and the ping
+            }
+        }
+    }
+    /** Nothing has used the server for a while and no sandbox runs: it ends (the next launch starts it again). */
+    async checkIdle() {
+        const limit = this.options.idleExitMs ?? 0;
+        if (!limit || this.tracked.size > 0 || Date.now() - this.lastUsed < limit)
+            return;
+        try {
+            if ((await this.options.backend.info()).sandbox === 'running')
+                return;
+        }
+        catch {
+            return; // cannot tell: keep running
+        }
+        this.options.onStop?.();
+    }
+    /** Counts a new socket; at the limit, the oldest of its kind makes room (a new tab always works). */
+    track(ws, kind, limit) {
+        const same = [...this.tracked.entries()]
+            .filter(([, t]) => t.kind === kind)
+            .sort((a, b) => a[1].opened - b[1].opened);
+        for (const [old] of same.slice(0, Math.max(0, same.length - limit + 1)))
+            old.close(4000, 'replaced by a newer page');
+        this.tracked.set(ws, { kind, opened: Date.now(), alive: true });
+        ws.on('pong', () => {
+            const t = this.tracked.get(ws);
+            if (t)
+                t.alive = true;
+        });
+        ws.on('message', () => (this.lastUsed = Date.now()));
+        ws.on('close', () => {
+            this.tracked.delete(ws);
+            this.lastUsed = Date.now();
+        });
+    }
     stop() {
+        clearInterval(this.heartbeat);
+        clearInterval(this.idleCheck);
         for (const client of this.sockets.clients)
             client.close(1001, 'server stopping');
         this.server.closeAllConnections();
@@ -82,6 +159,7 @@ export class WebServer {
         res.end(JSON.stringify(body));
     }
     async handle(req, res) {
+        this.lastUsed = Date.now();
         try {
             if (!hostAllowed(req.headers.host, this.actualPort))
                 throw new HttpFailure(421, 'Wrong host name.');
@@ -141,13 +219,6 @@ export class WebServer {
             return this.json(res, 200, await backend.info());
         if (pathname === '/api/sessions' && method === 'GET')
             return this.json(res, 200, await backend.sessions());
-        if (pathname === '/api/sessions' && method === 'POST') {
-            this.requireSameSite(req);
-            const request = newSessionRequest(await this.body(req));
-            if (!request)
-                throw new HttpFailure(400, 'Choose an agent and a project.');
-            return this.json(res, 201, await backend.create(request));
-        }
         if (pathname === '/api/stop' && method === 'POST') {
             this.requireSameSite(req);
             this.json(res, 200, { ok: true });
@@ -198,30 +269,24 @@ export class WebServer {
         if (!this.auth.signedIn(req.headers.cookie))
             return refuse('401 Unauthorized');
         if (rpc)
-            return this.upgradeRpc(req, socket, head, rpc, refuse);
+            return this.upgradeRpc(req, socket, head, rpc);
         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]);
         if (!endpoint)
             return refuse('404 Not Found');
         const cols = bounded(url.searchParams.get('cols'), MIN_COLS, MAX_COLS, 120);
         const rows = bounded(url.searchParams.get('rows'), MIN_ROWS, MAX_ROWS, 30);
         this.sockets.handleUpgrade(req, socket, head, (ws) => {
-            this.terminals++;
-            ws.on('close', () => this.terminals--);
+            this.track(ws, 'terminal', MAX_TERMINALS);
             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');
+    upgradeRpc(req, socket, head, rpc) {
         this.sockets.handleUpgrade(req, socket, head, (ws) => {
-            this.rpcSockets++;
-            ws.on('close', () => this.rpcSockets--);
-            new RpcSession(ws, rpc).start();
+            this.track(ws, 'rpc', MAX_RPC_SOCKETS);
+            new RpcSession(ws, rpc, this.live).start();
         });
     }
 }
@@ -229,10 +294,3 @@ function bounded(text, min, max, fallback) {
     const n = Number(text);
     return text !== null && Number.isInteger(n) && n >= min && n <= max ? n : fallback;
 }
-function newSessionRequest(body) {
-    if (typeof body !== 'object' || body === null)
-        return null;
-    const { harness, project } = body;
-    const ok = (v) => typeof v === 'string' && /^[A-Za-z0-9_.-]{1,64}$/.test(v);
-    return ok(harness) && ok(project) ? { harness, project } : null;
-}

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

@@ -4,6 +4,7 @@ export declare const WebStateSchema: z.ZodObject<{
     port: z.ZodNumber;
     token: z.ZodString;
     startedAt: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type WebState = z.output<typeof WebStateSchema>;
 export declare class WebStore {

package/dist/host/web/state.js

@@ -10,6 +10,8 @@ export const WebStateSchema = z.strictObject({
     port: z.number().int().min(1).max(65535),
     token: z.string().regex(/^[0-9a-f]{64}$/),
     startedAt: z.string().max(64),
+    /** The version that started it (missing: an older one). Another version is replaced, never reused. */
+    version: z.string().max(64).optional(),
 });
 export class WebStore {
     storageRoot;

package/dist/runtime/agent.js

@@ -25418,6 +25418,9 @@ var AttachSchema = external_exports.strictObject({
   ),
   autoHide: external_exports.boolean().describe(
     "Hide the Windows Sandbox window whenever this terminal attaches; it keeps running (sandbox show brings it back)."
+  ),
+  confirmCtrlC: external_exports.boolean().describe(
+    'In an attached terminal and the sandbox window, a single Ctrl+C is held back (the title says so) and only a second one within 1.5 seconds reaches the agent: a Ctrl+C meant as "copy" no longer stops it. Esc still stops an agent.'
   )
 });
 var AgentCommandsSchema = external_exports.strictObject({
@@ -25462,7 +25465,9 @@ 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.'),
+  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. Never more than this PC can keep in RAM for it (its RAM minus the larger of reserveHostMb and 25 %, 2 GB more with vGPU): a bigger value is lowered.'
+  ),
   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).`),
   cpuLimit: external_exports.union([external_exports.literal("none"), external_exports.number().int().min(5).max(100)]).describe(
@@ -25475,10 +25480,10 @@ var SandboxSchema = external_exports.strictObject({
     '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.'
+    'The last resort that keeps the sandbox up, in MB below its commit limit (RAM plus paging file): builds are slowed down long before (sandbox.pressureResponse); only if everything the agents start together would take the sandbox to the very edge of its memory, where Windows inside it would start failing, is a build refused memory instead of Windows. "auto" = the larger of 1536 MB and 3 % of the commit limit; "none" = no backstop. 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."
+    "When the sandbox (or this PC) runs low on memory, slow builds down in steps, like a PC that gets slower instead of failing: build programs get lower CPU and memory priority, then less CPU, then compilers take turns (the waiting ones briefly suspended and trimmed to the paging file). Nothing is stopped or killed, and the agents themselves are never touched. 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)."
@@ -25624,7 +25629,7 @@ var ToolchainsSchema = external_exports.strictObject({
       `GNU host: "lld" links with Rust's own lld through MinGW's gcc (much less memory than GNU ld), "gnu" with GNU ld.`
     ),
     linkSlots: external_exports.union([external_exports.literal("auto"), external_exports.number().int().min(1).max(32)]).describe(
-      'GNU host: how many programs may link at the same time in the whole sandbox (other links wait). "auto" = one per 8 GB of sandbox memory, 2 to 4. Several agents linking big programs at once can take Windows down.'
+      'GNU host: how many programs may link at the same time in the whole sandbox (other links wait). "auto" = one per 3 GB of sandbox memory after 6 GB, 2 to 8 (the memory governor slows links down too when memory runs short).'
     )
   }),
   msvc: external_exports.strictObject({
@@ -25699,7 +25704,7 @@ var ToolchainsSchema = external_exports.strictObject({
   }),
   cli: external_exports.strictObject({
     gh: EnabledSchema.describe(
-      'GitHub CLI (gh). Only with provisioning.git.access "full": gh can push and merge through the GitHub API, past a read-only git. Your PC\'s gh login is never copied; `gh auth login` inside persists (GH_CONFIG_DIR). "auto" = when the project has a .github folder.'
+      'GitHub CLI (gh). Only with provisioning.git.access "full": gh can push and merge through the GitHub API, past a read-only git. Your PC\'s gh login is never copied; `gh auth login` inside persists (GH_CONFIG_DIR), unless a token you saved for sandboxes is handed over (github.shareToken). "auto" = when the project has a .github folder.'
     ),
     zstd: EnabledSchema.describe('Zstandard (zstd). "auto" = off; set true to get it.'),
     openssl: EnabledSchema.describe(
@@ -26562,16 +26567,17 @@ var ResumeSchema = external_exports.strictObject({
 // src/core/schema/web.ts
 var WebSchema = external_exports.strictObject({
   enabled: external_exports.boolean().describe(
-    "(Beta) Allow the web UI: your sandbox sessions in a browser on this PC. Off by default, and nothing starts it by itself yet: sandbox web start works either way and runs it until sandbox web stop (or a restart of the PC)."
+    "(Beta) The web UI: your sandbox sessions in a browser on this PC (http://127.0.0.1:<port>, this PC only). On: every sandbox start also starts it in the background (it keeps running until sandbox web stop or a restart of the PC). Off: only sandbox web start runs it. Open it signed in with sandbox web open."
   ),
-  port: external_exports.number().int().min(1024).max(65535).describe("Port of the web UI on 127.0.0.1 (this PC only). Pick another when it is taken.")
+  port: external_exports.number().int().min(1024).max(65535).describe("Port of the web UI on 127.0.0.1 (this PC only). Pick another when it is taken."),
+  openOnLaunch: external_exports.boolean().describe("(Beta) With the web UI on: open it in your browser, already signed in, every time a sandbox starts.")
 });
 
 // src/core/schema/vpn.ts
 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)."
+    "(Alpha: not yet tried on a real PC) 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). wireguard-file: your own WireGuard .conf (configFile), e.g. from your company."
@@ -26586,6 +26592,13 @@ var VpnSchema = external_exports.strictObject({
   )
 });
 
+// src/core/schema/github.ts
+var GithubSchema = external_exports.strictObject({
+  shareToken: external_exports.boolean().describe(
+    'Give each sandbox the GitHub token you saved with `sandbox github login` (best a fine-grained token limited to some repositories and permissions), so gh and https git work there without logging in. Only with provisioning.git.access "full". The agent in the sandbox can read the token and use it for whatever it allows. A project file (.sandbox-config.json) cannot turn this on.'
+  )
+});
+
 // src/core/schema/config.ts
 var ConfigSchema = external_exports.strictObject({
   $schema: SchemaRefSchema.optional(),
@@ -26616,6 +26629,7 @@ var ConfigSchema = external_exports.strictObject({
   }),
   network: NetworkSchema,
   vpn: VpnSchema,
+  github: GithubSchema,
   provisioning: ProvisioningSchema,
   downloads: DownloadsSchema,
   toolchains: ToolchainsSchema,
@@ -26778,19 +26792,25 @@ var GuestRequestSchema = external_exports.discriminatedUnion("kind", [
     id: IdSchema,
     reason: Text(300),
     seconds: external_exports.number().int().min(10).max(300),
+    /** "severe": the PC is nearly out of memory; builds go to the governor's last step at once. */
+    level: external_exports.enum(["slow", "severe"]).optional(),
     createdAt: TimeSchema
   })
 ]);
 var PressureStatusSchema = external_exports.object({
   level: external_exports.enum(["ok", "throttled", "suspending"]),
+  /** The governor's dial, 0 (nothing wrong) to 4 (one compiler at a time). */
+  step: external_exports.number().int().min(0).max(4).optional(),
   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). */
+  /** Compilers waiting their turn right now (name, process id, seconds until they may go on). */
   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 CPU share the compilers get together (percent; 100 = no cap). */
+  cpuPercent: external_exports.number().int().min(0).max(100).optional(),
   /** The PC itself asked for slowing down (its memory or CPU is low). */
   pcLow: external_exports.boolean(),
   lastAction: Text(300),
@@ -26834,6 +26854,8 @@ var VpnStatusSchema = external_exports.object({
   state: external_exports.enum(["off", "starting", "up", "failed"]),
   message: Text(2e3),
   killSwitch: external_exports.boolean(),
+  /** A direct connection was tried after the kill switch was applied: false = it still got out. */
+  killSwitchHeld: external_exports.boolean().optional(),
   /** The server's name, e.g. uk2201.nordvpn.com. */
   server: Text(128).optional(),
   /** What the sandbox's traffic looks like from outside, once the tunnel is up. */
@@ -26977,6 +26999,8 @@ var RunDir = class {
   vpnFile;
   /** What the memory governor in the sandbox is doing (pressure.json). */
   pressureFile;
+  /** What the sandbox's programs may really use (budget.json): processors, memory, build jobs, link slots. */
+  budgetFile;
   requestsDir;
   responsesDir;
   sessionsDir;
@@ -26990,6 +27014,7 @@ var RunDir = class {
     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.budgetFile = path5.join(this.root, "budget.json");
     this.requestsDir = path5.join(this.root, "requests");
     this.responsesDir = path5.join(this.root, "responses");
     this.sessionsDir = path5.join(this.root, "sessions");
@@ -27359,12 +27384,6 @@ var githubAssetFromPage = async (repo, pattern, searchOlder) => {
 };
 
 // src/guest/runtime/process.ts
-function exec(file2, args, options = {}) {
-  const result = spawnSync(file2, args, { stdio: "inherit", windowsHide: true, ...options });
-  if (result.error) throw result.error;
-  if (result.status !== 0)
-    throw new Error(path11.basename(file2) + " " + args.slice(0, 3).join(" ") + " failed with exit code " + result.status);
-}
 async function execAsync(file2, args, options = {}) {
   const code = await spawnAsync(file2, args, { stdio: "inherit", ...options });
   if (code !== 0)
@@ -27375,7 +27394,16 @@ function execOutput(file2, args, options = {}) {
   return result.status === 0 ? String(result.stdout ?? "").trim() : "";
 }
 function runScript(name, args = []) {
-  exec(SYSTEM.powershell(), scriptArgs(name, args));
+  const result = spawnSync(SYSTEM.powershell(), scriptArgs(name, args), {
+    stdio: ["inherit", "inherit", "pipe"],
+    encoding: "utf8",
+    windowsHide: true
+  });
+  if (result.error) throw result.error;
+  const errors = String(result.stderr ?? "").trim();
+  if (errors) process.stderr.write(errors + "\n");
+  if (result.status !== 0)
+    throw new Error(name + " failed with exit code " + result.status + (errors ? ": " + errors.slice(0, 400) : ""));
 }
 function runScriptWithJson(name, param, data, args = []) {
   const dir = fs10.mkdtempSync(path11.join(os3.tmpdir(), "sbx-"));