windows-development-sandbox 1.18.4 → 1.23.0

package/dist/shared/apps/catalogue.d.ts

@@ -1,3 +1,4 @@
+import type { AppSigner } from '../signer.js';
 export type AppCategory = 'agents' | 'editors' | 'databases' | 'api' | 'git' | 'utilities' | 'browsers' | 'gamedev' | 'cloud' | 'diagrams' | 'network' | 'reversing' | 'cli';
 export declare const APP_CATEGORIES: {
     id: AppCategory;
@@ -23,13 +24,31 @@ export type AppSource = {
     locked: 'npm' | 'uv';
     package: string;
     version: string;
+}
+/** Nothing to download: a remote MCP server (AddonMcp.url). */
+ | {
+    remote: true;
 };
-/** An MCP server an add-on adds to the sandbox's Claude Code: `node <its folder>\<script> <args>`. */
+/**
+ * An MCP server an add-on adds to the sandbox's Claude Code (and Codex, with `codex`): `node <its folder>\<script>
+ * <args>`, the add-on's own program (`program`), or a remote server (`url`).
+ */
 export interface AddonMcp {
     /** The server's name in Claude Code (sbx-...: the sandbox removes its own names again when the add-on is off). */
     readonly name: string;
-    readonly script: string;
+    /** The script node runs, below the add-on's folder. */
+    readonly script?: string;
+    /** Instead: the add-on's own program (its exe) runs the server. */
+    readonly program?: boolean;
+    /** Instead: a remote server over HTTP; nothing runs in the sandbox, and it signs in with OAuth on first use. */
+    readonly url?: string;
     readonly args?: readonly string[];
+    /** Variables of the agent's environment the server reads (Codex passes on only those it is told about). */
+    readonly envVars?: readonly string[];
+    /** Fixed variables for the server (switches such as telemetry off; never a secret). */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Also in the sandbox's Codex (its config.toml), not only Claude Code. */
+    readonly codex?: boolean;
 }
 export interface AppEntry {
     id: string;
@@ -41,7 +60,7 @@ export interface AppEntry {
     /**
      * How the download is unpacked: an archive (zip/7z/tar, the default), the file itself, an NSIS installer or an MSI.
      */
-    unpack?: 'archive' | 'file' | 'nsis' | 'msi';
+    unpack?: 'archive' | 'file' | 'nsis' | 'msi' | 'chromium';
     /** The program to start (or the tool on PATH): a file name, or a regex (/.../) for names with a version in them. */
     exe: string;
     /** A command-line tool: its folder goes on PATH (no desktop shortcut). */
@@ -63,6 +82,11 @@ export interface AppEntry {
     service?: boolean;
     /** The MCP server it adds to the sandbox's Claude Code while it is on. */
     mcp?: AddonMcp;
+    /**
+     * Who must sign the download (Authenticode), for a vendor that publishes no checksum: a download signed by anyone
+     * else is refused, and it counts as integrity for downloads.requireChecksum.
+     */
+    signer?: AppSigner;
 }
 /** rtk (rtk-ai/rtk), pinned: the Apache-2.0 edition's Windows build. The checksum is the release's checksums.txt. */
 export declare const RTK_VERSION = "1.0.1";

package/dist/shared/apps/catalogue.js

@@ -3,6 +3,7 @@
 // shared by the menu on the PC (to list them) and the sandbox (to install them, guest/apps). VS Code and Windows
 // Terminal have settings of their own (toolchains.vscode, provisioning.terminal) and are listed here too, like
 // claude-mem (claudeProfile.syncClaudeMem) among the agent add-ons.
+import { AGENTS_WEB_APPS } from './catalogue-agents-web.js';
 import { GAMEDEV_APPS } from './catalogue-gamedev.js';
 import { MOBILE_APPS } from './catalogue-mobile.js';
 import { MODDING_APPS } from './catalogue-modding.js';
@@ -891,7 +892,7 @@ const CORE_APPS = [
     },
 ];
 /** Every app: the ones above, then the game-development, modding and mobile ones (each list in its own file). */
-export const APPS = [...CORE_APPS, ...GAMEDEV_APPS, ...MODDING_APPS, ...MOBILE_APPS];
+export const APPS = [...CORE_APPS, ...GAMEDEV_APPS, ...MODDING_APPS, ...MOBILE_APPS, ...AGENTS_WEB_APPS];
 export function appById(id) {
     return APPS.find((a) => a.id === id);
 }

package/dist/shared/apps/index.d.ts

@@ -1,3 +1,5 @@
 export { type AddonMcp, type AppCategory, APP_CATEGORIES, type AppSource, type AppEntry, APPS, appById, CCUSAGE_VERSION, CONTEXT7_MCP_VERSION, HEADROOM_VERSION, PLAYWRIGHT_MCP_VERSION, RTK_VERSION, } from './catalogue.js';
 export { exeMatcher, appsToInstall, appsNeedMesa, appsNeedUv } from './selection.js';
-export { ADDON_MCP_PREFIX, addonGuideLine, addonMcpServer, claudeManagedSettings, HEADROOM_ENV, HEADROOM_PORT, HEADROOM_UPSTREAM, headroomArgs, headroomEnv, headroomGuideLine, headroomUrl, type ManagedSettings, type McpServerConfig, rtkHookCommand, RTK_GUIDE_LINE, withAddonMcpServers, } from './agent-addons.js';
+export { signerMatches, type AppSigner, type Signature } from '../signer.js';
+export { AGENTS_WEB_APPS, BROWSER_USE_VERSION, CHROME_DEVTOOLS_MCP_VERSION, COMET_DOWNLOAD_URL, COMET_MCP_VERSION, COMET_SIGNER, PERPLEXITY_COMPUTER_MCP_URL, PERPLEXITY_MCP_VERSION, } from './catalogue-agents-web.js';
+export { ADDON_MCP_PREFIX, addonGuideLine, addonMcpServer, type AddonPlace, claudeManagedSettings, codexWithAddonMcpServers, type CodexMcpServer, HEADROOM_ENV, HEADROOM_PORT, HEADROOM_UPSTREAM, headroomArgs, headroomEnv, headroomGuideLine, headroomUrl, type ManagedSettings, type McpServerConfig, rtkHookCommand, RTK_GUIDE_LINE, withAddonMcpServers, } from './agent-addons.js';

package/dist/shared/apps/index.js

@@ -1,3 +1,5 @@
 export { APP_CATEGORIES, APPS, appById, CCUSAGE_VERSION, CONTEXT7_MCP_VERSION, HEADROOM_VERSION, PLAYWRIGHT_MCP_VERSION, RTK_VERSION, } from './catalogue.js';
 export { exeMatcher, appsToInstall, appsNeedMesa, appsNeedUv } from './selection.js';
-export { ADDON_MCP_PREFIX, addonGuideLine, addonMcpServer, claudeManagedSettings, HEADROOM_ENV, HEADROOM_PORT, HEADROOM_UPSTREAM, headroomArgs, headroomEnv, headroomGuideLine, headroomUrl, rtkHookCommand, RTK_GUIDE_LINE, withAddonMcpServers, } from './agent-addons.js';
+export { signerMatches } from '../signer.js';
+export { AGENTS_WEB_APPS, BROWSER_USE_VERSION, CHROME_DEVTOOLS_MCP_VERSION, COMET_DOWNLOAD_URL, COMET_MCP_VERSION, COMET_SIGNER, PERPLEXITY_COMPUTER_MCP_URL, PERPLEXITY_MCP_VERSION, } from './catalogue-agents-web.js';
+export { ADDON_MCP_PREFIX, addonGuideLine, addonMcpServer, claudeManagedSettings, codexWithAddonMcpServers, HEADROOM_ENV, HEADROOM_PORT, HEADROOM_UPSTREAM, headroomArgs, headroomEnv, headroomGuideLine, headroomUrl, rtkHookCommand, RTK_GUIDE_LINE, withAddonMcpServers, } from './agent-addons.js';

package/dist/shared/channel/schema.d.ts

@@ -17,14 +17,23 @@ export declare const BootProgressSchema: z.ZodObject<{
     done: z.ZodNumber;
     total: z.ZodNumber;
 }, z.core.$strict>;
+/** Work that goes on after the agent has started (Visual Studio installing): its name and how it is going. */
+export declare const BackgroundWorkSchema: z.ZodObject<{
+    name: z.ZodString;
+    state: z.ZodEnum<{
+        done: "done";
+        running: "running";
+        failed: "failed";
+    }>;
+}, z.core.$strict>;
 /** C:\AgentData\run\sandbox.json: boot progress of the sandbox as a whole. */
 export declare const SandboxStatusSchema: z.ZodObject<{
     launchId: z.ZodString;
     phase: z.ZodEnum<{
         provisioning: "provisioning";
+        failed: "failed";
         booting: "booting";
         ready: "ready";
-        failed: "failed";
     }>;
     message: z.ZodString;
     updatedAt: z.ZodString;
@@ -43,6 +52,14 @@ export declare const SandboxStatusSchema: z.ZodObject<{
         done: z.ZodNumber;
         total: z.ZodNumber;
     }, z.core.$strict>>>;
+    background: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        state: z.ZodEnum<{
+            done: "done";
+            running: "running";
+            failed: "failed";
+        }>;
+    }, z.core.$strict>>>>;
 }, z.core.$strip>;
 /**
  * A project the host registered after boot (sandbox claude from another folder): everything the guest needs to
@@ -93,6 +110,10 @@ export declare const ProjectSpecSchema: z.ZodObject<{
             acceptLicense: z.ZodBoolean;
             components: z.ZodArray<z.ZodString>;
             keepInstallFiles: z.ZodBoolean;
+            visualStudio: z.ZodEnum<{
+                full: "full";
+                autosdk: "autosdk";
+            }>;
             persistEngines: z.ZodBoolean;
             derivedDataCache: z.ZodEnum<{
                 persisted: "persisted";
@@ -326,6 +347,10 @@ export declare const GuestRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 acceptLicense: z.ZodBoolean;
                 components: z.ZodArray<z.ZodString>;
                 keepInstallFiles: z.ZodBoolean;
+                visualStudio: z.ZodEnum<{
+                    full: "full";
+                    autosdk: "autosdk";
+                }>;
                 persistEngines: z.ZodBoolean;
                 derivedDataCache: z.ZodEnum<{
                     persisted: "persisted";
@@ -579,6 +604,10 @@ export declare const GuestRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 acceptLicense: z.ZodBoolean;
                 components: z.ZodArray<z.ZodString>;
                 keepInstallFiles: z.ZodBoolean;
+                visualStudio: z.ZodEnum<{
+                    full: "full";
+                    autosdk: "autosdk";
+                }>;
                 persistEngines: z.ZodBoolean;
                 derivedDataCache: z.ZodEnum<{
                     persisted: "persisted";
@@ -854,9 +883,9 @@ export declare const SessionStatusSchema: z.ZodObject<{
     cwd: z.ZodString;
     project: z.ZodOptional<z.ZodString>;
     phase: z.ZodEnum<{
+        running: "running";
         failed: "failed";
         starting: "starting";
-        running: "running";
         exited: "exited";
     }>;
     message: z.ZodString;
@@ -878,8 +907,8 @@ export declare const ProjectStatusSchema: z.ZodObject<{
     workspace: z.ZodString;
     phase: z.ZodEnum<{
         provisioning: "provisioning";
-        ready: "ready";
         failed: "failed";
+        ready: "ready";
     }>;
     message: z.ZodString;
     updatedAt: z.ZodString;
@@ -898,6 +927,13 @@ export declare const VpnStatusSchema: z.ZodObject<{
         up: "up";
     }>;
     message: z.ZodString;
+    code: z.ZodOptional<z.ZodEnum<{
+        auth: "auth";
+        unreachable: "unreachable";
+        driver: "driver";
+        timeout: "timeout";
+        other: "other";
+    }>>;
     killSwitch: z.ZodBoolean;
     killSwitchHeld: z.ZodOptional<z.ZodBoolean>;
     server: z.ZodOptional<z.ZodString>;
@@ -910,6 +946,7 @@ export type ProjectStatus = z.output<typeof ProjectStatusSchema>;
 export type AttachEndpoint = z.output<typeof AttachEndpointSchema>;
 export type SandboxStatus = z.output<typeof SandboxStatusSchema>;
 export type BootProgress = z.output<typeof BootProgressSchema>;
+export type BackgroundWork = z.output<typeof BackgroundWorkSchema>;
 export type GuestRequest = z.output<typeof GuestRequestSchema>;
 export type GuestResponse = z.output<typeof GuestResponseSchema>;
 export type SessionStatus = z.output<typeof SessionStatusSchema>;

package/dist/shared/channel/schema.js

@@ -20,6 +20,11 @@ export const BootProgressSchema = z.strictObject({
     done: z.number().int().min(0).max(1000),
     total: z.number().int().min(0).max(1000),
 });
+/** Work that goes on after the agent has started (Visual Studio installing): its name and how it is going. */
+export const BackgroundWorkSchema = z.strictObject({
+    name: Text(64),
+    state: z.enum(['running', 'done', 'failed']),
+});
 /** C:\AgentData\run\sandbox.json: boot progress of the sandbox as a whole. */
 export const SandboxStatusSchema = z.object({
     launchId: Text(64),
@@ -33,6 +38,8 @@ export const SandboxStatusSchema = z.object({
     addresses: z.array(z.string().max(45)).max(8).optional(),
     /** A malformed progress is dropped, never the status (the phase still counts). */
     progress: BootProgressSchema.optional().catch(undefined),
+    /** Installs that continue after the boot is ready; a malformed list is dropped, never the status. */
+    background: z.array(BackgroundWorkSchema).max(16).optional().catch(undefined),
 });
 const VersionSchema = z.strictObject({ spec: Text(128), source: Text(256) });
 const DatabasePlanSchema = z.strictObject({
@@ -198,6 +205,8 @@ export const ProjectStatusSchema = z.object({
 export const VpnStatusSchema = z.object({
     state: z.enum(['off', 'starting', 'up', 'failed']),
     message: Text(2000),
+    /** Why it failed, when it did: `auth` (login refused), `unreachable`, `driver`, `timeout` or `other`. */
+    code: z.enum(['auth', 'unreachable', 'driver', 'timeout', 'other']).optional(),
     killSwitch: z.boolean(),
     /** A direct connection was tried after the kill switch was applied: false = it still got out. */
     killSwitchHeld: z.boolean().optional(),

package/dist/shared/channel/secrets.d.ts

@@ -51,6 +51,25 @@ export declare const SecretsFileSchema: z.ZodObject<{
             keyId: z.ZodString;
             p8: z.ZodString;
         }, z.core.$strict>>;
+        perplexity: z.ZodOptional<z.ZodObject<{
+            apiKey: z.ZodString;
+        }, z.core.$strict>>;
+        comet: z.ZodOptional<z.ZodObject<{
+            cookies: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                value: z.ZodString;
+                domain: z.ZodString;
+                path: z.ZodString;
+                expires: z.ZodOptional<z.ZodNumber>;
+                secure: z.ZodBoolean;
+                httpOnly: z.ZodBoolean;
+                sameSite: z.ZodOptional<z.ZodEnum<{
+                    Strict: "Strict";
+                    Lax: "Lax";
+                    None: "None";
+                }>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     liveFoldersKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;

package/dist/shared/concurrency/index.d.ts

@@ -0,0 +1,3 @@
+export { Limiter, asBackground, type Priority } from './limiter.js';
+export { ERROR_INSTALL_ALREADY_RUNNING, INSTALLER_RETRIES, INSTALLER_WAIT_MS, installerRetry, } from './installer-retry.js';
+export { net, heavy, installer } from './pools.js';

package/dist/shared/concurrency/index.js

@@ -0,0 +1,3 @@
+export { Limiter, asBackground } from './limiter.js';
+export { ERROR_INSTALL_ALREADY_RUNNING, INSTALLER_RETRIES, INSTALLER_WAIT_MS, installerRetry, } from './installer-retry.js';
+export { net, heavy, installer } from './pools.js';

package/dist/shared/concurrency/installer-retry.d.ts

@@ -0,0 +1,6 @@
+/** msiexec: "another installation is already in progress". */
+export declare const ERROR_INSTALL_ALREADY_RUNNING = 1618;
+export declare const INSTALLER_RETRIES = 20;
+export declare const INSTALLER_WAIT_MS = 15000;
+/** Whether an installer that exited with `code` after `attempt` tries (1 = the first) should be started again. */
+export declare function installerRetry(code: number | null, attempt: number): boolean;

package/dist/shared/concurrency/installer-retry.js

@@ -0,0 +1,10 @@
+// Windows Installer lets one install run at a time machine-wide: another process holding Global\_MSIExecute makes
+// msiexec exit with 1618. Pure.
+/** msiexec: "another installation is already in progress". */
+export const ERROR_INSTALL_ALREADY_RUNNING = 1618;
+export const INSTALLER_RETRIES = 20;
+export const INSTALLER_WAIT_MS = 15_000;
+/** Whether an installer that exited with `code` after `attempt` tries (1 = the first) should be started again. */
+export function installerRetry(code, attempt) {
+    return code === ERROR_INSTALL_ALREADY_RUNNING && attempt <= INSTALLER_RETRIES;
+}

package/dist/shared/concurrency/limiter.d.ts

@@ -0,0 +1,19 @@
+export type Priority = 'foreground' | 'background';
+/** Runs `work` so that every pool slot it asks for queues behind foreground work. */
+export declare function asBackground<T>(work: () => T): T;
+export declare class Limiter {
+    private readonly size;
+    readonly name: string;
+    private active;
+    private peakActive;
+    private readonly queues;
+    constructor(size: number, name?: string);
+    /** The most slots that were ever busy at once (tests). */
+    get peak(): number;
+    get running(): number;
+    /** Runs `work` in a free slot (waiting its turn), and frees the slot afterwards. */
+    run<T>(work: () => Promise<T> | T, priority?: Priority): Promise<T>;
+    private acquire;
+    private take;
+    private release;
+}

package/dist/shared/concurrency/limiter.js

@@ -0,0 +1,67 @@
+// A counting limiter for heavy work (downloads, unpacking, installers). FIFO, foreground before background. A task
+// that holds a slot may not take a slot of another limiter: nested pools throw, so a deadlock cannot happen. Pure.
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** The pool whose slot the current async context holds (at most one). */
+const held = new AsyncLocalStorage();
+/** The priority of work started in this async context (set by `asBackground`). */
+const priorityOf = new AsyncLocalStorage();
+/** Runs `work` so that every pool slot it asks for queues behind foreground work. */
+export function asBackground(work) {
+    return priorityOf.run('background', work);
+}
+export class Limiter {
+    size;
+    name;
+    active = 0;
+    peakActive = 0;
+    queues = { foreground: [], background: [] };
+    constructor(size, name = 'pool') {
+        this.size = size;
+        this.name = name;
+        if (!Number.isInteger(size) || size < 1)
+            throw new Error('A pool needs a size of at least 1');
+    }
+    /** The most slots that were ever busy at once (tests). */
+    get peak() {
+        return this.peakActive;
+    }
+    get running() {
+        return this.active;
+    }
+    /** Runs `work` in a free slot (waiting its turn), and frees the slot afterwards. */
+    async run(work, priority = priorityOf.getStore() ?? 'foreground') {
+        const holding = held.getStore();
+        if (holding)
+            throw new Error('nested pool: ' + this.name + ' requested while holding ' + holding.name);
+        await this.acquire(priority);
+        try {
+            return await held.run(this, async () => work());
+        }
+        finally {
+            this.release();
+        }
+    }
+    acquire(priority) {
+        if (this.active < this.size) {
+            this.take();
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.queues[priority].push({
+                start: () => {
+                    this.take();
+                    resolve();
+                },
+            });
+        });
+    }
+    take() {
+        this.active++;
+        this.peakActive = Math.max(this.peakActive, this.active);
+    }
+    release() {
+        this.active--;
+        const next = this.queues.foreground.shift() ?? this.queues.background.shift();
+        next?.start();
+    }
+}

package/dist/shared/concurrency/pools.d.ts

@@ -0,0 +1,7 @@
+import { Limiter } from './limiter.js';
+/** HTTP bodies. */
+export declare const net: Limiter;
+/** extractArchive, 7-Zip/NSIS unpack, npm ci/install, uv/pip, Steam, robocopy of big layouts, rustup/cargo. */
+export declare const heavy: Limiter;
+/** Every msiexec, vcredist, DXSETUP and the Visual Studio bootstrapper: Windows runs one install at a time. */
+export declare const installer: Limiter;

package/dist/shared/concurrency/pools.js

@@ -0,0 +1,9 @@
+// The three pools (one set per process): the limiter instances only, so pure code can take a slot. The guest wires
+// them to the downloader and extractor (guest/runtime/pools.ts installPools).
+import { Limiter } from './limiter.js';
+/** HTTP bodies. */
+export const net = new Limiter(4, 'net');
+/** extractArchive, 7-Zip/NSIS unpack, npm ci/install, uv/pip, Steam, robocopy of big layouts, rustup/cargo. */
+export const heavy = new Limiter(2, 'heavy');
+/** Every msiexec, vcredist, DXSETUP and the Visual Studio bootstrapper: Windows runs one install at a time. */
+export const installer = new Limiter(1, 'installer');

package/dist/shared/download/archive.d.ts

@@ -1,3 +1,4 @@
+import type { Limiter } from '../concurrency/index.js';
 /**
  * A fresh `<destination>.staging-<hex>` folder next to `destination`: fill it, then moveIntoPlace. An interrupted copy
  * or extraction leaves only the staging folder (cleanup/repair remove those), never a half-filled destination.
@@ -5,6 +6,7 @@
 export declare function stagingFolder(destination: string): string;
 /** Replaces `destination` with the finished `work` folder (a folder rename: the destination is never half there). */
 export declare function moveIntoPlace(work: string, destination: string): void;
+export declare function limitExtraction(limiter: Limiter | null): void;
 /**
  * Extracts .zip / .nupkg / .7z / .tar.gz with the tar.exe that ships with Windows, falling back to Expand-Archive.
  * `members` limits it to those paths inside the archive (e.g. skip pgAdmin in the PostgreSQL zip).

package/dist/shared/download/archive.js

@@ -18,11 +18,21 @@ export function moveIntoPlace(work, destination) {
     fs.mkdirSync(path.dirname(destination), { recursive: true });
     fs.renameSync(work, destination);
 }
+/** The guest's heavy pool (set by the guest at start-up; host code leaves it unset). */
+let extractLimit = null;
+export function limitExtraction(limiter) {
+    extractLimit = limiter;
+}
 /**
  * Extracts .zip / .nupkg / .7z / .tar.gz with the tar.exe that ships with Windows, falling back to Expand-Archive.
  * `members` limits it to those paths inside the archive (e.g. skip pgAdmin in the PostgreSQL zip).
  */
-export async function extractArchive(archive, destination, members = []) {
+export function extractArchive(archive, destination, members = []) {
+    return extractLimit
+        ? extractLimit.run(() => extract(archive, destination, members))
+        : extract(archive, destination, members);
+}
+async function extract(archive, destination, members) {
     fs.mkdirSync(destination, { recursive: true });
     let status = await spawnAsync(SYSTEM.tar(), ['-xf', archive, '-C', destination, ...members]);
     if (status !== 0 && /\.(zip|nupkg)$/i.test(archive)) {

package/dist/shared/download/bounded-fetch.d.ts

@@ -0,0 +1,13 @@
+/** Reads a URL as text, refusing more than `max` bytes. */
+export type Fetcher = (url: string, max: number) => Promise<string>;
+/** An answer whatever its status: the status, the header values asked for, and the body (at most `max` bytes). */
+export interface BoundedResponse {
+    readonly status: number;
+    readonly header: (name: string) => string | null;
+    readonly text: string;
+}
+/** Reads a request with headers (or any other init) once; a status that is not 200 is an answer, not an error. */
+export type RequestFetcher = (url: string, max: number, init?: RequestInit) => Promise<BoundedResponse>;
+export declare function fetchBounded(url: string, max: number): Promise<string>;
+/** One request with a timeout (10 s by default), no retries: for a check that should answer quickly. */
+export declare function fetchBoundedResponse(url: string, max: number, init?: RequestInit, timeoutMs?: number): Promise<BoundedResponse>;

package/dist/shared/download/bounded-fetch.js

@@ -0,0 +1,40 @@
+// Reading an answer from the internet with a size limit: a server cannot make this PC download without end. Node
+// built-ins only (it is part of the shared download helpers).
+import { fetchRetry } from './http.js';
+/** The body of a response, refusing more than `max` bytes. */
+async function readBounded(response, url, max) {
+    const host = new URL(url).host;
+    const length = Number(response.headers.get('content-length')) || 0;
+    if (length > max)
+        throw new Error('The answer from ' + host + ' is too big.');
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Empty answer from ' + host + '.');
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.length;
+        if (size > max) {
+            await reader.cancel();
+            throw new Error('The answer from ' + host + ' is too big.');
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export async function fetchBounded(url, max) {
+    return readBounded(await fetchRetry(url, {}, 2, 30000), url, max);
+}
+/** One request with a timeout (10 s by default), no retries: for a check that should answer quickly. */
+export async function fetchBoundedResponse(url, max, init = {}, timeoutMs = 10000) {
+    const response = await fetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { 'User-Agent': 'windows-development-sandbox', ...(init.headers ?? {}) },
+    });
+    const text = await readBounded(response, url, max);
+    return { status: response.status, header: (name) => response.headers.get(name), text };
+}

package/dist/shared/download/downloader.d.ts

@@ -1,3 +1,4 @@
+import type { Limiter } from '../concurrency/index.js';
 /** Expected checksums of a download; any that are given must match. */
 export interface Checksums {
     sha256?: string | null;
@@ -16,6 +17,8 @@ export interface ArchiveOptions extends Checksums {
     /** Folders above `locate`'s to keep. */
     up?: number;
     fileName?: string;
+    /** A copy of the archive that `file()` already downloaded (checked then): used and removed instead of downloading. */
+    cached?: string;
     members?: string[];
 }
 /**
@@ -26,6 +29,8 @@ export type DownloadWatcher = () => ((fraction: number) => void) | null;
 export declare class Downloader {
     /** downloads.requireChecksum: refuse anything without an expected hash. The guest sets it from session.json. */
     requireChecksum: boolean;
+    /** The guest's net pool: how many HTTP bodies stream at once. Host code leaves it null. */
+    limit: Limiter | null;
     private watcher;
     /** Reports coarse progress of the downloads that start from now on to `watcher` (null: stop). */
     watch(watcher: DownloadWatcher | null): void;

package/dist/shared/download/downloader.js

@@ -9,6 +9,8 @@ import { extractArchive, findFile, moveIntoPlace, stagingFolder } from './archiv
 export class Downloader {
     /** downloads.requireChecksum: refuse anything without an expected hash. The guest sets it from session.json. */
     requireChecksum = false;
+    /** The guest's net pool: how many HTTP bodies stream at once. Host code leaves it null. */
+    limit = null;
     watcher = null;
     /** Reports coarse progress of the downloads that start from now on to `watcher` (null: stop). */
     watch(watcher) {
@@ -28,48 +30,52 @@ export class Downloader {
                 url +
                 '): no checksum is published for it, and downloads.requireChecksum is on. Turn that setting off to allow downloads that cannot be verified.');
         }
-        const response = await fetchRetry(url, {}, 3, 20 * 60 * 1000);
-        if (!response.body)
-            throw new Error('Empty response for ' + url);
         fs.mkdirSync(path.dirname(destination), { recursive: true });
         // Only the hashes that will be checked (sha512 of a 330 MB archive is not free).
         const checks = ['sha256', 'sha512', 'sha1'].flatMap((kind) => {
             const want = sums[kind]?.trim().toLowerCase();
             return want ? [{ want, hash: crypto.createHash(kind) }] : [];
         });
-        // Progress for the boot screen: every 10% or 5 s at most, never per chunk; called here so it knows who is
-        // downloading.
-        const size = Number(response.headers.get('content-length')) || 0;
-        const report = size > 0 ? (this.watcher?.() ?? null) : null;
-        let received = 0;
-        let tenth = 0;
-        let reportedAt = Date.now();
-        const tap = new Transform({
-            transform(chunk, _encoding, done) {
-                for (const c of checks)
-                    c.hash.update(chunk);
-                if (report) {
-                    received += chunk.length;
-                    const now = Math.floor((received * 10) / size);
-                    if (now !== tenth || Date.now() - reportedAt > 5000) {
-                        tenth = now;
-                        reportedAt = Date.now();
-                        try {
-                            report(Math.min(1, received / size));
-                        }
-                        catch {
-                            /* progress never breaks a download */
-                        }
-                    }
-                }
-                done(null, chunk);
-            },
-        });
         // Written to <destination>.part and moved into place only once complete and verified, so an interrupted download
         // never leaves a partial file under the real name.
         const partial = destination + '.part';
-        try {
+        // Only the transfer holds a net slot; the signature check and the rename below stay outside it.
+        const transfer = async () => {
+            const response = await fetchRetry(url, {}, 3, 20 * 60 * 1000);
+            if (!response.body)
+                throw new Error('Empty response for ' + url);
+            // Progress for the boot screen: every 10% or 5 s at most, never per chunk; called here so it knows who is
+            // downloading.
+            const size = Number(response.headers.get('content-length')) || 0;
+            const report = size > 0 ? (this.watcher?.() ?? null) : null;
+            let received = 0;
+            let tenth = 0;
+            let reportedAt = Date.now();
+            const tap = new Transform({
+                transform(chunk, _encoding, done) {
+                    for (const c of checks)
+                        c.hash.update(chunk);
+                    if (report) {
+                        received += chunk.length;
+                        const now = Math.floor((received * 10) / size);
+                        if (now !== tenth || Date.now() - reportedAt > 5000) {
+                            tenth = now;
+                            reportedAt = Date.now();
+                            try {
+                                report(Math.min(1, received / size));
+                            }
+                            catch {
+                                /* progress never breaks a download */
+                            }
+                        }
+                    }
+                    done(null, chunk);
+                },
+            });
             await pipeline(Readable.fromWeb(response.body), tap, fs.createWriteStream(partial));
+        };
+        try {
+            await (this.limit ? this.limit.run(transfer) : transfer());
             if (checks.some((c) => c.hash.digest('hex') !== c.want))
                 throw new Error('Checksum mismatch for ' + url);
             if (sums.verify)
@@ -90,12 +96,18 @@ export class Downloader {
         const work = stagingFolder(destination);
         try {
             const archive = path.join(work, options.fileName ?? path.basename(new URL(url).pathname));
-            await this.file(url, archive, {
-                sha256: options.sha256,
-                sha512: options.sha512,
-                sha1: options.sha1,
-                ...(options.verify ? { verify: options.verify } : {}),
-            });
+            if (options.cached && fs.existsSync(options.cached)) {
+                fs.mkdirSync(work, { recursive: true });
+                fs.copyFileSync(options.cached, archive);
+                fs.rmSync(options.cached, { force: true });
+            }
+            else
+                await this.file(url, archive, {
+                    sha256: options.sha256,
+                    sha512: options.sha512,
+                    sha1: options.sha1,
+                    ...(options.verify ? { verify: options.verify } : {}),
+                });
             const extracted = path.join(work, 'x');
             await extractArchive(archive, extracted, options.members);
             let root = extracted;

package/dist/shared/download/index.d.ts

@@ -1,5 +1,6 @@
 export { fetchRetry, fetchJson, fetchText } from './http.js';
-export { stagingFolder, moveIntoPlace, extractArchive, findFile } from './archive.js';
+export { fetchBounded, fetchBoundedResponse, type BoundedResponse, type Fetcher, type RequestFetcher, } from './bounded-fetch.js';
+export { stagingFolder, moveIntoPlace, extractArchive, findFile, limitExtraction } from './archive.js';
 export { type ArchiveOptions, type Checksums, type DownloadWatcher, Downloader, downloader } from './downloader.js';
 export { spawnAsync } from './spawn.js';
 export { type ReleaseAsset, githubAsset, parseReleasePage, latestGithubTag, parseReleaseTags } from './github.js';