windows-development-sandbox 1.7.0 → 1.10.0

package/dist/core/schema/vpn.js

@@ -1,13 +1,13 @@
 // The VPN setting (inside the sandbox only; the login is not a setting: it is kept encrypted by `sandbox vpn login`).
 import { z } from 'zod';
-export const VPN_PROVIDERS = ['nordvpn', 'openvpn-file'];
+export const VPN_PROVIDERS = ['nordvpn', 'openvpn-file', 'wireguard-file'];
 export const VpnSchema = z.strictObject({
     enabled: z
         .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)."),
+        .describe("(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: z
         .enum(VPN_PROVIDERS)
-        .describe('nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile).'),
+        .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.'),
     protocol: z.enum(['udp', 'tcp']).describe('udp is faster; tcp gets through networks that block udp.'),
     country: z
         .string()
@@ -15,7 +15,7 @@ export const VpnSchema = z.strictObject({
         .describe('nordvpn: the country of the server, e.g. uk, us or Germany. Empty = the best server anywhere.'),
     configFile: z
         .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."),
+        .describe("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: z
         .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.'),

package/dist/core/schema/web.d.ts

@@ -3,4 +3,5 @@ export declare const WEB_DEFAULT_PORT = 47800;
 export declare const WebSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     port: z.ZodNumber;
+    openOnLaunch: z.ZodBoolean;
 }, z.core.$strict>;

package/dist/core/schema/web.js

@@ -4,11 +4,14 @@ export const WEB_DEFAULT_PORT = 47800;
 export const WebSchema = z.strictObject({
     enabled: z
         .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).'),
+        .describe('(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: z
         .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: z
+        .boolean()
+        .describe('(Beta) With the web UI on: open it in your browser, already signed in, every time a sandbox starts.'),
 });

package/dist/core/types.d.ts

@@ -105,12 +105,15 @@ export interface DatabasePlan {
 /** The VPN decided at launch (host/vpn/prepare.ts): its checked profile, and the login for the one-shot file. */
 export interface PreparedVpn {
     session: GuestVpn;
-    /** The profile text, already checked. */
-    profile: string;
-    credentials: {
+    /** openvpn: the profile text, already checked (goes in the launch folder). */
+    profile?: string;
+    /** openvpn: the login (one-shot file). */
+    credentials?: {
         username: string;
         password: string;
     };
+    /** wireguard-file: the checked config; holds the private key (one-shot file only). */
+    wireguardConfig?: string;
 }
 /** databases / pcLanguages: use these instead of scanning (tests). */
 export interface GenerateOptions {
@@ -119,6 +122,8 @@ export interface GenerateOptions {
     harnessArgs: string[];
     probe: HostProbe;
     freeMemoryBytes?: number;
+    /** This PC's unused commit (RAM plus paging file) in MB from HostTools memory-status; omitted = not checked. */
+    commitAvailableMb?: number | null;
     databases?: DatabasePlan[];
     pcLanguages?: AutoToolchain[];
     /**
@@ -136,6 +141,8 @@ export interface GenerateOptions {
     };
     /** The VPN for this launch (vpn.enabled); its profile goes in the launch folder, its login in the one-shot file. */
     vpn?: PreparedVpn;
+    /** The data set's mappings from a storage provider (contained storage); else the data folder is one mapping. */
+    dataMappings?: ResolvedMapping[];
 }
 export interface Generated {
     wsbPath: string;
@@ -143,6 +150,8 @@ export interface Generated {
     launchId: string;
     sessionPath: string;
     memoryMb: number;
+    /** Plain words when the PC's commit made the memory much smaller than free RAM allowed. */
+    memoryNote: string | null;
     /** The config the sandbox boots with: the launch folder's plus what the other projects mapped at boot want. */
     bootConfig: Config;
     /** Boot settings turned on for another project (setting -> project). */
@@ -181,8 +190,8 @@ export interface GuestVpn {
     killSwitch: boolean;
     /** The server's name, for messages. */
     server: string;
-    /** The checked profile, relative to the launch folder. */
-    profile: string;
+    /** openvpn: the checked profile, relative to the launch folder (none for wireguard-file: its config is a secret). */
+    profile?: string;
 }
 /** Written by the host to C:\AgentLaunch\session.json (read-only for the guest): everything the guest needs to know. */
 export interface GuestSession {
@@ -253,6 +262,15 @@ export interface GuestSession {
     cpuLimitPercent?: number | null;
     /** sandbox.pageFileMb (0 = Windows' own); sandbox\scripts\set-page-file.ps1 applies it at logon. */
     pageFileMb?: number;
+    /**
+     * sandbox.agentMemoryHeadroomMb as a limit: the most memory (MB) everything the agents start may use together
+     * (the sandbox's memory minus the headroom); null = no limit. ptyhost puts each agent in a job object with it.
+     */
+    agentMemoryLimitMb?: number | null;
+    /** "gentle" when vGPU is on: the governor and the watchdog act earlier, compilers run below normal. */
+    loadProfile?: 'normal' | 'gentle';
+    /** sandbox.pressureResponse: the daemon slows builds down when memory runs low. */
+    pressureResponse?: boolean;
     /** Apps to install (catalogue ids and your own programs); missing in launch folders of older versions. */
     apps?: Config['apps'];
     /** audit.enabled and audit.processes: the sandbox reports the programs it starts (host keeps the log). */

package/dist/core/util/fs.d.ts

@@ -1,6 +1,8 @@
 export declare function ensureDir(p: string): void;
 export declare function dirExists(p: string): boolean;
 export declare function fileExists(p: string): boolean;
+/** fileExists without blocking the program (the menu looks for programs while it stays responsive). */
+export declare function fileExistsAsync(p: string): Promise<boolean>;
 export declare function readJson<T>(p: string): T;
 export declare function tryReadJson<T>(p: string): T | null;
 /** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */

package/dist/core/util/fs.js

@@ -19,6 +19,15 @@ export function fileExists(p) {
         return false;
     }
 }
+/** fileExists without blocking the program (the menu looks for programs while it stays responsive). */
+export async function fileExistsAsync(p) {
+    try {
+        return (await fs.promises.stat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 export function readJson(p) {
     return JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\uFEFF/, ''));
 }

package/dist/core/util/index.d.ts

@@ -1,7 +1,7 @@
 export { isWin, sleep, captureOutput } from './process.js';
 export { UserError, fail, errMsg } from './errors.js';
 export { parseJsonc, readJsonc } from './jsonc.js';
-export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
 export { xmlEscape, safeText, plainText } from './text.js';
 export { homeDir, expandPath, expandVariables, isRootPath, isUserProfile, isInsideOrEqual, findOnPath, } from './paths.js';
 export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/core/util/index.js

@@ -1,7 +1,7 @@
 export { isWin, sleep, captureOutput } from './process.js';
 export { UserError, fail, errMsg } from './errors.js';
 export { parseJsonc, readJsonc } from './jsonc.js';
-export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { ensureDir, dirExists, fileExists, fileExistsAsync, readJson, tryReadJson, writeJson, realPath } from './fs.js';
 export { xmlEscape, safeText, plainText } from './text.js';
 export { homeDir, expandPath, expandVariables, isRootPath, isUserProfile, isInsideOrEqual, findOnPath, } from './paths.js';
 export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/guest/agents/agent-files.d.ts

@@ -43,6 +43,11 @@ export interface LocalState {
     readonly legacy: string;
 }
 export declare function localStateEntries(agents: Readonly<Record<string, Harness>>, stateDir: string, localRoot: string): LocalState[];
+/** Every agent's bootReset paths, absolute below its state folder (the schema allows only plain relative paths). */
+export declare function bootResetPaths(agents: Readonly<Record<string, Harness>>, stateDir: string): {
+    agent: string;
+    path: string;
+}[];
 /** A SQLite database file or one of its -wal / -shm siblings. */
 export declare const isDatabaseFile: (name: string) => boolean;
 /** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */

package/dist/guest/agents/agent-files.js

@@ -57,6 +57,10 @@ export function localStateEntries(agents, stateDir, localRoot) {
         legacy: path.join(stateDir, agent),
     })));
 }
+/** Every agent's bootReset paths, absolute below its state folder (the schema allows only plain relative paths). */
+export function bootResetPaths(agents, stateDir) {
+    return Object.entries(agents).flatMap(([agent, harness]) => (harness.bootReset ?? []).map((rel) => ({ agent, path: path.join(stateDir, agent, rel) })));
+}
 /** A SQLite database file or one of its -wal / -shm siblings. */
 export const isDatabaseFile = (name) => /\.(sqlite3?|db)(-wal|-shm)?$/i.test(name);
 /** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */

package/dist/guest/agents/local-state.d.ts

@@ -3,6 +3,8 @@ import { type LocalState } from './agent-files.js';
 export declare function agentLocalStates(): LocalState[];
 /** Variable -> working folder, for the agent environment (and the machine environment of new terminal tabs). */
 export declare function localStateVars(): Record<string, string>;
+/** Boot: what an agent sealed to the last sandbox (bootReset) is deleted, so it sets it up again. Links are left. */
+export declare function resetMachineBound(): void;
 /** Boot: the saved databases of every configured agent are copied to the sandbox's disk, where the agent runs them. */
 export declare function restoreLocalState(): void;
 /**

package/dist/guest/agents/local-state.js

@@ -10,7 +10,7 @@ import { execOutput } from '../runtime/process.js';
 import { log, warn } from '../runtime/log.js';
 import { session, stateDir } from '../runtime/session.js';
 import { errMsg } from '../../core/util/errors.js';
-import { isCopyableDatabaseFile, isDatabaseFile, localStateEntries } from './agent-files.js';
+import { bootResetPaths, isCopyableDatabaseFile, isDatabaseFile, localStateEntries, } from './agent-files.js';
 const SQLITE_HEADER = 'SQLite format 3\0';
 /** The sandbox-disk folder that holds the working copies. */
 const localRoot = () => path.join(localDir, 'agent-state');
@@ -82,6 +82,26 @@ function adoptLegacy(s) {
         fs.rmSync(path.join(s.legacy, n), { force: true });
     log(s.agent + ': moved ' + copyable.length + ' database file(s) to ' + s.store + '.');
 }
+/** Boot: what an agent sealed to the last sandbox (bootReset) is deleted, so it sets it up again. Links are left. */
+export function resetMachineBound() {
+    if (dryRun)
+        return;
+    for (const { agent, path: target } of bootResetPaths(session.agents ?? {}, stateDir)) {
+        try {
+            const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+            if (!stat || stat.isSymbolicLink())
+                continue;
+            fs.rmSync(target, { recursive: true, force: true });
+            log(agent +
+                ': removed ' +
+                path.relative(path.join(stateDir, agent), target) +
+                ' (it only worked in the last sandbox).');
+        }
+        catch (e) {
+            warn(agent + ': could not remove ' + target + ' (' + errMsg(e) + ').');
+        }
+    }
+}
 /** Boot: the saved databases of every configured agent are copied to the sandbox's disk, where the agent runs them. */
 export function restoreLocalState() {
     if (dryRun)

package/dist/guest/boot/boot.js

@@ -6,7 +6,7 @@ import { writeGuides } from './guide.js';
 import { setupToolchains } from '../toolchains/index.js';
 import { agents } from '../agents/agent-installer.js';
 import { agentShims, sbxAgentText, shimText } from '../agents/agent-files.js';
-import { restoreLocalState } from '../agents/local-state.js';
+import { resetMachineBound, restoreLocalState } from '../agents/local-state.js';
 import { installShellPath } from '../setup/shell-path.js';
 import { linkProfileDirs } from '../agents/profile-links.js';
 import { restoreClaudeMem } from '../setup/claude-mem.js';
@@ -14,7 +14,7 @@ import { syncClaudeProfile } from '../setup/claude-profile.js';
 import { agentEnv, persistEnvironment } from '../setup/environment.js';
 import { runHooks } from '../setup/hooks.js';
 import { applyAllowOnly, proxyEnv } from '../network/allow-only.js';
-import { applyNetworkPolicy } from '../network/firewall.js';
+import { applyNetworkPolicy, networkProblems } from '../network/firewall.js';
 import { writeManagedSettings } from '../setup/managed-policy.js';
 import { applyPersonalization } from '../setup/desktop.js';
 import { setupGitConfig } from '../setup/git-identity.js';
@@ -175,6 +175,8 @@ export class Boot {
             databases: session.databases ?? [],
             apps: session.apps,
         });
+        for (const p of networkProblems())
+            tools.summary.push('PROTECTION MISSING: ' + p);
         if (!dryRun)
             tools.prepend.push(writeDbCommand());
         // network.allowOnly / network.proxy: everything started from now on uses the proxy.
@@ -225,6 +227,7 @@ export class Boot {
         if (session.harnessName === 'claude')
             await soft('Claude settings', () => syncClaudeProfile(this.secrets.claudeCredentials));
         await soft('claude-mem restore', restoreClaudeMem);
+        await soft('Agent files of the last sandbox', resetMachineBound);
         await soft('Agent databases restore', restoreLocalState);
         await soft('Sandbox guide for the agent', () => writeGuides(tools.summary, this.lan));
         await soft('Claude managed settings', () => writeManagedSettings(this.gitAccess));

package/dist/guest/daemon/daemon.js

@@ -4,6 +4,7 @@ import { saveClaudeMem } from '../setup/claude-mem.js';
 import { saveLocalState } from '../agents/local-state.js';
 import { execCommand } from './exec.js';
 import { sessions } from './sessions.js';
+import { governor } from '../governor/index.js';
 import { respond, safely } from './state.js';
 import { run } from '../runtime/paths.js';
 import { withRequestSecrets } from '../runtime/secrets.js';
@@ -53,6 +54,9 @@ export class Daemon {
                 return execCommand(req);
             case 'restart':
                 return sessions.restart(req);
+            case 'pressure':
+                // No response: the host repeats it every few seconds while its memory stays low.
+                return governor.hostPressure(req.seconds, req.reason);
             case 'ping':
                 return respond(req.id, { ok: true, message: 'pong (' + sessions.count + ' session(s) running)' });
         }

package/dist/guest/daemon/sessions.d.ts

@@ -2,6 +2,11 @@ import type { GuestRequest } from '../../core/types.js';
 type SessionRequest = Extract<GuestRequest, {
     kind: 'session';
 }>;
+/**
+ * What keeps heavy load from taking the sandbox down: the job object's memory limit for everything the agents start
+ * (ptyhost reads PTYHOST_JOB_MB) and cargo's parallel jobs sized to the sandbox's memory and the sessions building.
+ */
+export declare function memoryEnv(env: NodeJS.ProcessEnv, sessions: number): NodeJS.ProcessEnv;
 /** The agent sessions of this sandbox: the running ones, the ones starting, and what happens when one ends. */
 export declare class SessionManager {
     private readonly live;

package/dist/guest/daemon/sessions.js

@@ -3,11 +3,13 @@
 // (daemon/project).
 import path from 'node:path';
 import crypto from 'node:crypto';
+import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { FrameType, sendControl } from '../../shared/pty/index.js';
 import { isWithin } from '../../shared/paths/projects.js';
 import { now } from '../../shared/channel/run-dir.js';
 import { SYSTEM } from '../../shared/system.js';
+import { cargoJobs } from '../../shared/memory/index.js';
 import { commandLine } from '../sessions/cmdline.js';
 import { freePort } from '../runtime/ports.js';
 import { primaryProject } from '../boot/project-status.js';
@@ -48,8 +50,20 @@ const harnessFor = (req) => {
         return sent;
     throw new Error('Agent "' + req.harness + '" is not configured for this sandbox (it runs ' + session.harnessName + ').');
 };
+/**
+ * What keeps heavy load from taking the sandbox down: the job object's memory limit for everything the agents start
+ * (ptyhost reads PTYHOST_JOB_MB) and cargo's parallel jobs sized to the sandbox's memory and the sessions building.
+ */
+export function memoryEnv(env, sessions) {
+    const out = {};
+    if (session.agentMemoryLimitMb)
+        out.PTYHOST_JOB_MB = String(session.agentMemoryLimitMb);
+    if (!env.CARGO_BUILD_JOBS)
+        out.CARGO_BUILD_JOBS = String(cargoJobs(os.cpus().length, os.totalmem() / 1024 ** 3, sessions));
+    return out;
+}
 /** Starts ptyhost for the agent and waits until it listens; a failure carries the tail of ptyhost's own log. */
-const launchPtyHost = async (req, remote, env, say) => {
+const launchPtyHost = async (req, remote, env, say, sessions) => {
     const harness = harnessFor(req);
     // Never refresh here: main already did, and replacing a running agent's executable would fail.
     say('Preparing ' + req.harness);
@@ -66,7 +80,7 @@ const launchPtyHost = async (req, remote, env, say) => {
         rows: 32,
         id: req.id,
         cwd: req.cwd,
-        env: { ...withRegistryPath(env), ...harness.environment },
+        env: { ...withRegistryPath(env), ...harness.environment, ...memoryEnv(env, sessions) },
         remote,
         command: commandLine(launch.file, [...base, ...req.args]),
         restartCommand: commandLine(launch.file, [...base, ...(harness.resumeArguments ?? [])]),
@@ -145,7 +159,7 @@ export class SessionManager {
         try {
             const place = await placeFor(req, say);
             const remote = session.networking && session.attach.enabled;
-            const { child, port, token } = await launchPtyHost(req, remote, place.env, say);
+            const { child, port, token } = await launchPtyHost(req, remote, place.env, say, this.live.size + 1);
             const resumed = req.harness === 'claude' ? resumedConversation(req.args) : undefined;
             const running = {
                 ...status,

package/dist/guest/entries/daemon.js

@@ -9,10 +9,13 @@ import { log, warn } from '../runtime/log.js';
 import { adoptBootSecrets } from '../runtime/secrets.js';
 import { errMsg } from '../../core/util/errors.js';
 import { Daemon } from '../daemon/daemon.js';
+import { governor } from '../governor/index.js';
 process.on('uncaughtException', (e) => warn('daemon: unexpected error (continuing): ' + (e.stack ?? errMsg(e))));
 process.on('unhandledRejection', (e) => warn('daemon: unexpected error (continuing): ' + errMsg(e)));
 adoptBootSecrets();
 log('Session daemon started (pid ' + process.pid + ').');
 safely('port forwards', startRelays);
 safely('audit', startProcessCollector);
+safely('memory governor', () => governor.start());
+log('Memory governor: ' + governor.describe());
 new Daemon().start();

package/dist/guest/governor/decide.d.ts

@@ -0,0 +1,71 @@
+import type { GuestThresholds, LoadProfile } from '../../shared/memory/index.js';
+export type Priority = 'idle' | 'below' | 'normal';
+export interface ProcSample {
+    readonly pid: number;
+    readonly name: string;
+    /** Private memory in MB. */
+    readonly mb: number;
+    readonly prio: Priority;
+}
+export interface MemSample {
+    readonly ramTotalMb: number;
+    readonly ramAvailMb: number;
+    readonly commitLimitMb: number;
+    readonly commitAvailMb: number;
+    /** Only the processes in the agents' job. */
+    readonly procs: readonly ProcSample[];
+}
+export declare const isNeverTouched: (name: string) => boolean;
+export declare const canLower: (name: string) => boolean;
+export declare const isHeavyCompiler: (name: string) => boolean;
+export declare const canPause: (name: string) => boolean;
+export type Level = 'ok' | 'throttled' | 'suspending';
+export interface GovernorState {
+    /** Under pressure now (with hysteresis). */
+    readonly pressure: boolean;
+    /** Samples in a row that looked calm while under pressure. */
+    readonly calm: number;
+    /** Samples under pressure so far (resets when it ends). */
+    readonly samples: number;
+    /** What was lowered and to what, by pid. */
+    readonly lowered: Readonly<Record<number, Priority>>;
+    /** Until when (ms) the last pause lasts, and when another may start. */
+    readonly pausedUntil: number;
+    readonly nextPauseAt: number;
+    /** The PC asked for slowing down until this time (ms). */
+    readonly hostUntil: number;
+}
+export declare const INITIAL_STATE: GovernorState;
+export type Action = {
+    readonly kind: 'priority';
+    readonly pid: number;
+    readonly name: string;
+    readonly to: Priority;
+} | {
+    readonly kind: 'pause';
+    readonly pid: number;
+    readonly name: string;
+    readonly ms: number;
+}
+/** Waits (suspended) because more compilers run than the cap allows; repeated while it is over, never killed. */
+ | {
+    readonly kind: 'hold';
+    readonly pid: number;
+    readonly name: string;
+    readonly ms: number;
+};
+/** How long a held compiler waits before it gets a turn again (the governor repeats the hold while over the cap). */
+export declare const HOLD_MS = 3000;
+export interface Decision {
+    readonly state: GovernorState;
+    readonly actions: readonly Action[];
+    readonly level: Level;
+    readonly ramFreePercent: number;
+    readonly commitPercent: number;
+}
+export declare const PAUSE_MS = 5000;
+/**
+ * One step. `gentle` (vGPU on): compilers start below normal even without pressure. Programs go back to their normal
+ * priority only when pressure ends (several calm samples in a row).
+ */
+export declare function decide(prev: GovernorState, sample: MemSample, nowMs: number, thresholds: GuestThresholds, profile: LoadProfile, maxCompilers?: number | null): Decision;