windows-development-sandbox 1.4.0 → 1.4.3

package/dist/guest/toolchains/{cli.js → tools/cli.js}

@@ -2,16 +2,26 @@
 // `openssl` shim onto the copy Git for Windows already ships.
 import fs from 'node:fs';
 import path from 'node:path';
-import { dryRun, errMsg, exists, log, mkdirp, stateDir, warn } from '../env.js';
-import { projectWorkspace } from '../project-context.js';
-import { CLI_TOOLS, decideCli } from './catalogue.js';
-import { arch, tool } from './common.js';
-import { setupSingleExe } from './runtimes.js';
-import { ensureCompiled } from '../helpers.js';
-/** gh keeps `gh auth login` here, under the agent state (persists like Claude's own login; never copied from the PC). */
-export const ghConfigDir = () => path.join(stateDir, 'gh');
+import { dryRun } from '../../runtime/paths.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log, warn } from '../../runtime/log.js';
+import { stateDir } from '../../runtime/session.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { projectWorkspace } from '../../runtime/project-context.js';
+import { CLI_TOOLS, decideCli } from '../catalogue.js';
+import { arch, tool } from '../tool-env.js';
+import { setupSingleExe } from '../runtimes.js';
+import { ensureCompiled } from '../../runtime/csc.js';
+/** gh keeps `gh auth login` here, under the agent state (persists like Claude's login; never copied from the PC). */
+export function ghConfigDir() {
+    return path.join(stateDir, 'gh');
+}
 const toolVars = {
-    gh: () => ({ GH_CONFIG_DIR: mkdirp(ghConfigDir()), GH_NO_UPDATE_NOTIFIER: '1', GH_NO_EXTENSION_UPDATE_NOTIFIER: '1' }),
+    gh: () => ({
+        GH_CONFIG_DIR: mkdirp(ghConfigDir()),
+        GH_NO_UPDATE_NOTIFIER: '1',
+        GH_NO_EXTENSION_UPDATE_NOTIFIER: '1',
+    }),
 };
 /**
  * tools\shims\openssl.exe (sandbox/openssl.cs), a launcher for Git's mingw64\bin\openssl.exe. A real .exe so programs
@@ -28,22 +38,28 @@ const shimOpenssl = (env) => {
     // An earlier version wrote a .cmd; it would still win for shells that prefer it.
     fs.rmSync(path.join(shims, 'openssl.cmd'), { force: true });
     env.prepend.push(shims);
-    env.summary.push('openssl: Git for Windows\' copy');
+    env.summary.push("openssl: Git for Windows' copy");
 };
 /**
  * Installs the tools toolchains.cli asks for. Settings still "auto" here (normally the host decides) use the same
  * rules on the workspace as the host would. The gh rule is enforced here again, whatever the host sent.
  */
-export const setupCli = async (env, settings, gitAccess, refresh = false) => {
+export async function setupCli(env, settings, gitAccess, refresh = false) {
     const decisions = decideCli(settings, { gitAccess, hasGithubDir: exists(path.join(projectWorkspace(), '.github')) });
     if (settings.gh && !decisions.gh.on) {
         env.summary.push('gh: off (' + decisions.gh.reason + ')');
         // A login from an earlier full-access sandbox is still on disk; the agent could read the token from there.
         if (exists(path.join(ghConfigDir(), 'hosts.yml')))
-            warn('gh is off (git access is not "full"), but an earlier gh login is still stored in ' + ghConfigDir() + ' and readable by the agent. Run `gh auth logout` in a full-access sandbox, or delete that folder.');
+            warn('gh is off (git access is not "full"), but an earlier gh login is still stored in ' +
+                ghConfigDir() +
+                ' and readable by the agent. Run `gh auth logout` in a full-access sandbox, or delete that folder.');
     }
     if (dryRun) {
-        log('(dry run) would provision CLI tools: ' + Object.entries(decisions).filter(([, d]) => d.on).map(([n]) => n).join(', '));
+        log('(dry run) would provision CLI tools: ' +
+            Object.entries(decisions)
+                .filter(([, d]) => d.on)
+                .map(([n]) => n)
+                .join(', '));
         return;
     }
     for (const entry of CLI_TOOLS) {
@@ -51,7 +67,11 @@ export const setupCli = async (env, settings, gitAccess, refresh = false) => {
         if (!decisions[name].on)
             continue;
         try {
-            await setupSingleExe(env, name, entry.repo, entry.asset(arch), entry.exe, tool('cli', name), { refresh, subdir: entry.subdir, size: entry.size });
+            await setupSingleExe(env, name, entry.repo, entry.asset(arch), entry.exe, tool('cli', name), {
+                refresh,
+                subdir: entry.subdir,
+                size: entry.size,
+            });
             Object.assign(env.vars, toolVars[name]?.() ?? {});
         }
         catch (e) {
@@ -69,4 +89,4 @@ export const setupCli = async (env, settings, gitAccess, refresh = false) => {
             env.summary.push('openssl: FAILED');
         }
     }
-};
+}

package/dist/guest/toolchains/tools/git.d.ts

@@ -0,0 +1,3 @@
+import type { GitAccess } from '../../../core/types.js';
+import { type ToolEnv } from '../tool-env.js';
+export declare function setupGit(env: ToolEnv, hostCopy: boolean, refresh: boolean, access: GitAccess): Promise<void>;

package/dist/guest/toolchains/{git.js → tools/git.js}

@@ -2,20 +2,32 @@
 // provisioning.git.access decides what the agent gets: 'full' git, a 'readonly' guarded git, or 'none' (bash only).
 import fs from 'node:fs';
 import path from 'node:path';
-import { download, githubAsset, moveIntoPlace, stagingFolder } from '../../shared/download.js';
-import { safeRemove } from '../../shared/safe-remove.js';
-import { dataDir, dryRun, errMsg, execAsync, execOutput, exists, hostToolsDir, launchDir, log, mkdirp, robocopy, toolsDir, warn } from '../env.js';
-import { ensureCompiled } from '../helpers.js';
-import { arch, tool } from './common.js';
-import { duringSession } from '../project-context.js';
-const BLOCKED_HOOKS = ['pre-commit', 'commit-msg', 'pre-merge-commit', 'pre-push', 'pre-rebase', 'pre-applypatch', 'applypatch-msg'];
+import { downloader, githubAsset, moveIntoPlace, stagingFolder } from '../../../shared/download/index.js';
+import { safeRemove } from '../../../shared/io/safe-remove.js';
+import { dataDir, dryRun, hostToolsDir, launchDir, toolsDir } from '../../runtime/paths.js';
+import { execAsync, execOutput, robocopy } from '../../runtime/process.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log, warn } from '../../runtime/log.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { ensureCompiled } from '../../runtime/csc.js';
+import { arch, tool } from '../tool-env.js';
+import { duringSession } from '../../runtime/project-context.js';
+const BLOCKED_HOOKS = [
+    'pre-commit',
+    'commit-msg',
+    'pre-merge-commit',
+    'pre-push',
+    'pre-rebase',
+    'pre-applypatch',
+    'applypatch-msg',
+];
 const posix = (p) => p.replace(/\\/g, '/');
 const installPortableGit = async (root) => {
     const asset = await githubAsset('git-for-windows/git', arch === 'arm64' ? /^PortableGit-[\d.]+-arm64\.7z\.exe$/ : /^PortableGit-[\d.]+-64-bit\.7z\.exe$/);
     const sfx = tool(asset.name);
     log('Downloading Git for Windows (' + asset.name + ', ~60 MB once) ...');
     try {
-        await download(asset.url, sfx, asset.sha256);
+        await downloader.file(asset.url, sfx, asset.sha256);
         await execAsync(sfx, ['-o' + root, '-y'], { stdio: 'ignore' });
     }
     finally {
@@ -31,7 +43,9 @@ const installGuard = (env, access, realGit) => {
     const guard = path.join(launchDir, 'runtime', 'gitguard.js');
     // A real git.exe (programs like Claude Code only look for .exe); a .cmd only if the C# compiler is unavailable.
     // A project added later reuses the boot's: sessions may be running it, and Windows cannot replace a running exe.
-    if (duringSession() && (exists(path.join(dir, 'git.exe')) || exists(path.join(dir, 'git.cmd')))) { /* keep it */ }
+    if (duringSession() && (exists(path.join(dir, 'git.exe')) || exists(path.join(dir, 'git.cmd')))) {
+        /* keep it */
+    }
     else
         try {
             fs.copyFileSync(ensureCompiled('gitshim'), path.join(dir, 'git.exe'));
@@ -44,14 +58,21 @@ const installGuard = (env, access, realGit) => {
     fs.writeFileSync(path.join(dir, 'bashenv.sh'), 'git() { "' + posix(process.execPath) + '" "' + posix(guard) + '" "$@"; }\nexport -f git\n');
     env.prepend.unshift(dir);
     Object.assign(env.vars, {
-        AGENT_GIT_ACCESS: access, AGENT_REAL_GIT: access === 'readonly' ? realGit : '',
-        AGENT_GUARD_NODE: process.execPath, AGENT_GUARD_SCRIPT: guard, BASH_ENV: posix(path.join(dir, 'bashenv.sh')),
+        AGENT_GIT_ACCESS: access,
+        AGENT_REAL_GIT: access === 'readonly' ? realGit : '',
+        AGENT_GUARD_NODE: process.execPath,
+        AGENT_GUARD_SCRIPT: guard,
+        BASH_ENV: posix(path.join(dir, 'bashenv.sh')),
     });
     if (access === 'readonly') {
         const hooks = mkdirp(path.join(dir, 'hooks'));
         for (const hook of BLOCKED_HOOKS)
             fs.writeFileSync(path.join(hooks, hook), '#!/bin/sh\necho "git is read-only in this sandbox: ' + hook + ' refused." >&2\nexit 1\n');
-        Object.assign(env.vars, { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'core.hooksPath', GIT_CONFIG_VALUE_0: posix(hooks) });
+        Object.assign(env.vars, {
+            GIT_CONFIG_COUNT: '1',
+            GIT_CONFIG_KEY_0: 'core.hooksPath',
+            GIT_CONFIG_VALUE_0: posix(hooks),
+        });
     }
     else {
         // Even a git.exe found some other way sees no repository.
@@ -73,7 +94,7 @@ const pointAtOwnCertificates = (root) => {
     if (fixed !== text)
         fs.writeFileSync(config, fixed);
 };
-export const setupGit = async (env, hostCopy, refresh, access) => {
+export async function setupGit(env, hostCopy, refresh, access) {
     const root = tool('git');
     const bash = path.join(root, 'bin', 'bash.exe');
     const gitExe = path.join(root, 'cmd', 'git.exe');
@@ -117,5 +138,7 @@ export const setupGit = async (env, hostCopy, refresh, access) => {
         return;
     }
     installGuard(env, access, gitExe);
-    env.summary.push(access === 'readonly' ? 'git: ' + version + ' READ-ONLY (status/log/diff/show/blame; no commit, push, checkout, ...)' : 'git: DISABLED (bash only; the agent cannot use git)');
-};
+    env.summary.push(access === 'readonly'
+        ? 'git: ' + version + ' READ-ONLY (status/log/diff/show/blame; no commit, push, checkout, ...)'
+        : 'git: DISABLED (bash only; the agent cannot use git)');
+}

package/dist/guest/toolchains/tools/pwsh.d.ts

@@ -0,0 +1,4 @@
+import { type ToolEnv } from '../tool-env.js';
+/** Where pwsh.exe lives (the host's Windows Terminal profile points at the same folder under C:\AgentData). */
+export declare function pwshDir(): string;
+export declare function setupPwsh(env: ToolEnv, refresh?: boolean): Promise<void>;

package/dist/guest/toolchains/{pwsh.js → tools/pwsh.js}

@@ -1,14 +1,21 @@
 // PowerShell 7 (pwsh): the portable zip from PowerShell/PowerShell releases (no MSI: Windows Sandbox would lose it on
 // every boot). Only `pwsh` is added; Windows PowerShell 5.1 (`powershell`, SYSTEM.powershell()) stays what the
 // sandbox's own hooks and scripts use.
-import { pwshAsset } from './catalogue.js';
-import { arch, tool } from './common.js';
-import { setupSingleExe } from './runtimes.js';
+import { pwshAsset } from '../catalogue.js';
+import { arch, tool } from '../tool-env.js';
+import { setupSingleExe } from '../runtimes.js';
 /** Where pwsh.exe lives (the host's Windows Terminal profile points at the same folder under C:\AgentData). */
-export const pwshDir = () => tool('pwsh');
-export const setupPwsh = async (env, refresh = false) => {
+export function pwshDir() {
+    return tool('pwsh');
+}
+export async function setupPwsh(env, refresh = false) {
     // pwsh.exe sits at the zip's root next to its runtime and modules: the whole folder is kept.
-    await setupSingleExe(env, 'pwsh', 'PowerShell/PowerShell', pwshAsset(arch), 'pwsh.exe', pwshDir(), { refresh, size: '100 MB', versionArgs: ['-Version'], note: ' (PowerShell 7; powershell is still 5.1)' });
+    await setupSingleExe(env, 'pwsh', 'PowerShell/PowerShell', pwshAsset(arch), 'pwsh.exe', pwshDir(), {
+        refresh,
+        size: '100 MB',
+        versionArgs: ['-Version'],
+        note: ' (PowerShell 7; powershell is still 5.1)',
+    });
     // No update banner or telemetry from a copy that provisioning.refresh replaces anyway.
     Object.assign(env.vars, { POWERSHELL_UPDATECHECK: 'Off', POWERSHELL_TELEMETRY_OPTOUT: '1' });
-};
+}

package/dist/guest/toolchains/{vscode-profile.d.ts → tools/vscode-profile.d.ts}

@@ -16,15 +16,15 @@ export interface ToolPaths {
     ruby?: string;
     deno?: string;
 }
-/** User settings for the sandbox's VS Code. Only keys with a value are set; the caller removes the ones it set before. */
-export declare const vscodeSettings: (p: ToolPaths) => Record<string, unknown>;
+/** User settings for the sandbox's VS Code. Only keys with a value are set; the caller removes those it set before. */
+export declare function vscodeSettings(p: ToolPaths): Record<string, unknown>;
 export declare const EXTENSION_ID: RegExp;
 /** The extensions to have: always EditorConfig, then per toolchain and database in use, the project's, and yours. */
-export declare const vscodeExtensions: (o: {
+export declare function vscodeExtensions(o: {
     toolchains: string[];
     databases: string[];
     recommended: string[];
     extra: string[];
-}) => string[];
-/** Extensions not installed yet, from the names of the folders in VS Code's extensions folder (publisher.name-1.2.3). */
-export declare const missingExtensions: (wanted: string[], folders: string[]) => string[];
+}): string[];
+/** Extensions not installed yet, from the folder names in VS Code's extensions folder (publisher.name-1.2.3). */
+export declare function missingExtensions(wanted: string[], folders: string[]): string[];

package/dist/guest/toolchains/{vscode-profile.js → tools/vscode-profile.js}

@@ -2,8 +2,8 @@
 // for the languages in use. Pure (tested); vscode.ts finds the paths and writes them.
 /** The JDK's major version from its folder name (jdk-21.0.5+11 -> 21). */
 const javaMajor = (home) => /(?:jdk|jre)?-?(\d{1,2})(?:[.+_-]|$)/i.exec(home.split(/[\\/]/).pop() ?? '')?.[1];
-/** User settings for the sandbox's VS Code. Only keys with a value are set; the caller removes the ones it set before. */
-export const vscodeSettings = (p) => {
+/** User settings for the sandbox's VS Code. Only keys with a value are set; the caller removes those it set before. */
+export function vscodeSettings(p) {
     const profiles = {};
     if (p.pwsh)
         profiles['PowerShell 7'] = { path: p.pwsh, args: ['-NoLogo'] };
@@ -18,14 +18,18 @@ export const vscodeSettings = (p) => {
         'terminal.integrated.defaultProfile.windows': p.pwsh ? 'PowerShell 7' : undefined,
         'python.defaultInterpreterPath': p.python,
         'java.jdt.ls.java.home': p.javaHome,
-        'java.configuration.runtimes': p.javaHome ? [{ name: 'JavaSE-' + (javaMajor(p.javaHome) ?? '21'), path: p.javaHome, default: true }] : undefined,
+        'java.configuration.runtimes': p.javaHome
+            ? [{ name: 'JavaSE-' + (javaMajor(p.javaHome) ?? '21'), path: p.javaHome, default: true }]
+            : undefined,
         'maven.terminal.useJavaHome': p.javaHome ? true : undefined,
         'go.goroot': p.goRoot,
         'go.alternateTools': p.go ? { go: p.go } : undefined,
         'C_Cpp.default.compilerPath': p.cl ?? p.gcc,
         'cmake.cmakePath': p.cmake,
         'dotnet.dotnetPath': p.dotnet ? p.dotnet.replace(/[\\/]dotnet\.exe$/i, '') : undefined,
-        'dotnetAcquisitionExtension.existingDotnetPath': p.dotnet ? [{ extensionId: 'ms-dotnettools.csharp', path: p.dotnet }] : undefined,
+        'dotnetAcquisitionExtension.existingDotnetPath': p.dotnet
+            ? [{ extensionId: 'ms-dotnettools.csharp', path: p.dotnet }]
+            : undefined,
         'php.validate.executablePath': p.php,
         'php.debug.executablePath': p.php,
         'rubyLsp.rubyVersionManager': p.ruby ? { identifier: 'none' } : undefined,
@@ -34,12 +38,18 @@ export const vscodeSettings = (p) => {
         'npm.packageManager': 'auto',
     };
     return Object.fromEntries(Object.entries(settings).filter(([, v]) => v !== undefined));
-};
+}
 /** Extensions per toolchain (Marketplace ids). */
 const BY_TOOLCHAIN = {
     node: ['dbaeumer.vscode-eslint', 'esbenp.prettier-vscode'],
     python: ['ms-python.python', 'ms-python.debugpy'],
-    java: ['redhat.java', 'vscjava.vscode-java-debug', 'vscjava.vscode-java-test', 'vscjava.vscode-maven', 'vscjava.vscode-gradle'],
+    java: [
+        'redhat.java',
+        'vscjava.vscode-java-debug',
+        'vscjava.vscode-java-test',
+        'vscjava.vscode-maven',
+        'vscjava.vscode-gradle',
+    ],
     go: ['golang.go'],
     rust: ['rust-lang.rust-analyzer', 'vadimcn.vscode-lldb'],
     cpp: ['ms-vscode.cpptools', 'ms-vscode.cmake-tools'],
@@ -58,12 +68,18 @@ const BY_DATABASE = {
 };
 export const EXTENSION_ID = /^[\w-]+\.[\w-]+$/;
 /** The extensions to have: always EditorConfig, then per toolchain and database in use, the project's, and yours. */
-export const vscodeExtensions = (o) => {
-    const all = ['editorconfig.editorconfig', ...o.toolchains.flatMap((t) => BY_TOOLCHAIN[t] ?? []), ...o.databases.flatMap((d) => BY_DATABASE[d] ?? []), ...o.recommended, ...o.extra];
+export function vscodeExtensions(o) {
+    const all = [
+        'editorconfig.editorconfig',
+        ...o.toolchains.flatMap((t) => BY_TOOLCHAIN[t] ?? []),
+        ...o.databases.flatMap((d) => BY_DATABASE[d] ?? []),
+        ...o.recommended,
+        ...o.extra,
+    ];
     return [...new Set(all.map((e) => e.toLowerCase()))].filter((e) => EXTENSION_ID.test(e));
-};
-/** Extensions not installed yet, from the names of the folders in VS Code's extensions folder (publisher.name-1.2.3). */
-export const missingExtensions = (wanted, folders) => {
+}
+/** Extensions not installed yet, from the folder names in VS Code's extensions folder (publisher.name-1.2.3). */
+export function missingExtensions(wanted, folders) {
     const have = folders.map((f) => f.toLowerCase());
     return wanted.filter((id) => !have.some((f) => f.startsWith(id + '-')));
-};
+}

package/dist/guest/toolchains/{vscode.d.ts → tools/vscode.d.ts}

@@ -1,11 +1,11 @@
-import type { Toolchains } from '../../core/types.js';
-import { type ToolEnv } from './common.js';
+import type { Toolchains } from '../../../core/types.js';
+import { type ToolEnv } from '../tool-env.js';
 /**
  * After every toolchain is installed: points VS Code at the sandbox's own JDK, Python, Go, compilers, .NET, Git and
  * terminals (user settings; only the keys this tool manages are changed, your own stay), and installs the extensions
  * for the languages in use in the background (they persist, so only new ones are downloaded).
  */
-export declare const configureVscode: (tools: {
+export declare function configureVscode(tools: {
     vars: Record<string, string>;
     prepend: string[];
     append: string[];
@@ -13,7 +13,7 @@ export declare const configureVscode: (tools: {
 }, o: {
     toolchains: string[];
     databases: string[];
-    config: Toolchains["vscode"];
+    config: Toolchains['vscode'];
     workspace: string;
-}) => void;
-export declare const setupVscode: (env: ToolEnv, refresh: boolean) => Promise<void>;
+}): void;
+export declare function setupVscode(env: ToolEnv, refresh: boolean): Promise<void>;

package/dist/guest/toolchains/{vscode.js → tools/vscode.js}

@@ -5,10 +5,13 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser';
-import { fetchJson, installArchive } from '../../shared/download.js';
-import { SYSTEM } from '../../shared/system.js';
-import { dryRun, exists, isWin, log, logsDir, mkdirp, powershell } from '../env.js';
-import { arch, tool } from './common.js';
+import { downloader, fetchJson } from '../../../shared/download/index.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { dryRun, isWin, logsDir } from '../../runtime/paths.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log } from '../../runtime/log.js';
+import { powershell } from '../../runtime/process.js';
+import { arch, tool } from '../tool-env.js';
 import { EXTENSION_ID, missingExtensions, vscodeExtensions, vscodeSettings } from './vscode-profile.js';
 /** Newer builds keep their files under a commit-hash folder, so the installed version is recorded here. */
 const VERSION_MARKER = '.agent-sandbox-version';
@@ -17,7 +20,13 @@ const desktopShortcut = (exe) => {
         return;
     const link = path.join(os.homedir(), 'Desktop', 'Visual Studio Code.lnk');
     const q = (s) => "'" + s.replace(/'/g, "''") + "'";
-    powershell('$s = (New-Object -ComObject WScript.Shell).CreateShortcut(' + q(link) + '); $s.TargetPath = ' + q(exe) + '; $s.Arguments = ' + q('"' + (process.env.AGENT_WORKSPACE ?? '') + '"') + '; $s.Save()');
+    powershell('$s = (New-Object -ComObject WScript.Shell).CreateShortcut(' +
+        q(link) +
+        '); $s.TargetPath = ' +
+        q(exe) +
+        '; $s.Arguments = ' +
+        q('"' + (process.env.AGENT_WORKSPACE ?? '') + '"') +
+        '; $s.Save()');
 };
 /** The first of `names` in one of `dirs`. */
 const findIn = (dirs, ...names) => {
@@ -36,7 +45,9 @@ const recommendedBy = (workspace) => {
         if (!exists(file) || fs.statSync(file).size > 64 * 1024)
             return [];
         const data = parseJsonc(fs.readFileSync(file, 'utf8'));
-        return Array.isArray(data?.recommendations) ? data.recommendations.filter((r) => typeof r === 'string' && EXTENSION_ID.test(r)).slice(0, 50) : [];
+        return Array.isArray(data?.recommendations)
+            ? data.recommendations.filter((r) => typeof r === 'string' && EXTENSION_ID.test(r)).slice(0, 50)
+            : [];
     }
     catch {
         return [];
@@ -47,7 +58,7 @@ const recommendedBy = (workspace) => {
  * terminals (user settings; only the keys this tool manages are changed, your own stay), and installs the extensions
  * for the languages in use in the background (they persist, so only new ones are downloaded).
  */
-export const configureVscode = (tools, o) => {
+export function configureVscode(tools, o) {
     const root = tool('vscode');
     const code = path.join(root, 'bin', 'code.cmd');
     if (dryRun) {
@@ -59,26 +70,51 @@ export const configureVscode = (tools, o) => {
     const dirs = [...tools.prepend, ...tools.append];
     const git = findIn([tool('git', 'cmd'), ...dirs], 'git.exe');
     const settings = vscodeSettings({
-        javaHome: tools.vars.JAVA_HOME, goRoot: tools.vars.GOROOT, go: findIn(dirs, 'go.exe'), python: findIn(dirs, 'python.exe'), gcc: findIn(dirs, 'gcc.exe'), cl: findIn(dirs, 'cl.exe'),
-        cmake: findIn(dirs, 'cmake.exe'), dotnet: findIn(dirs, 'dotnet.exe'), node: findIn(dirs, 'node.exe'), pwsh: findIn(dirs, 'pwsh.exe'), git,
-        bash: git ? findIn([path.join(path.dirname(path.dirname(git)), 'bin')], 'bash.exe') : undefined, php: findIn(dirs, 'php.exe'), ruby: findIn(dirs, 'ruby.exe'), deno: findIn(dirs, 'deno.exe'),
+        javaHome: tools.vars.JAVA_HOME,
+        goRoot: tools.vars.GOROOT,
+        go: findIn(dirs, 'go.exe'),
+        python: findIn(dirs, 'python.exe'),
+        gcc: findIn(dirs, 'gcc.exe'),
+        cl: findIn(dirs, 'cl.exe'),
+        cmake: findIn(dirs, 'cmake.exe'),
+        dotnet: findIn(dirs, 'dotnet.exe'),
+        node: findIn(dirs, 'node.exe'),
+        pwsh: findIn(dirs, 'pwsh.exe'),
+        git,
+        bash: git ? findIn([path.join(path.dirname(path.dirname(git)), 'bin')], 'bash.exe') : undefined,
+        php: findIn(dirs, 'php.exe'),
+        ruby: findIn(dirs, 'ruby.exe'),
+        deno: findIn(dirs, 'deno.exe'),
     });
     writeManagedSettings(path.join(root, 'data', 'user-data', 'User', 'settings.json'), path.join(root, 'data', '.agent-sandbox-managed.json'), settings);
-    const wanted = vscodeExtensions({ toolchains: o.toolchains, databases: o.databases, recommended: o.config.recommended ? recommendedBy(o.workspace) : [], extra: o.config.extensions });
+    const wanted = vscodeExtensions({
+        toolchains: o.toolchains,
+        databases: o.databases,
+        recommended: o.config.recommended ? recommendedBy(o.workspace) : [],
+        extra: o.config.extensions,
+    });
     let folders = [];
     try {
         folders = fs.readdirSync(path.join(root, 'data', 'extensions'));
     }
-    catch { /* none yet */ }
+    catch {
+        /* none yet */
+    }
     const missing = missingExtensions(wanted, folders);
-    tools.summary.push('vscode: set up for ' + (o.toolchains.join(', ') || 'Node') + (missing.length ? '; installing ' + missing.length + ' extension(s) in the background' : '; extensions ready'));
+    tools.summary.push('vscode: set up for ' +
+        (o.toolchains.join(', ') || 'Node') +
+        (missing.length ? '; installing ' + missing.length + ' extension(s) in the background' : '; extensions ready'));
     if (!missing.length)
         return;
     // In the background: the Marketplace can take a minute, and nothing else waits for it.
     const logFile = fs.openSync(path.join(logsDir, 'vscode-extensions.log'), 'a');
-    spawn(SYSTEM.cmd(), ['/d', '/c', code, ...missing.flatMap((id) => ['--install-extension', id])], { detached: true, stdio: ['ignore', logFile, logFile], windowsHide: true }).unref();
+    spawn(SYSTEM.cmd(), ['/d', '/c', code, ...missing.flatMap((id) => ['--install-extension', id])], {
+        detached: true,
+        stdio: ['ignore', logFile, logFile],
+        windowsHide: true,
+    }).unref();
     fs.closeSync(logFile);
-};
+}
 /**
  * Sets `values` in a settings file, keeping everything else (comments too), and removes keys this tool set last time
  * but no longer has a value for (a toolchain turned off). The keys it manages are remembered in `managedFile`.
@@ -89,7 +125,9 @@ const writeManagedSettings = (file, managedFile, values) => {
     try {
         before = JSON.parse(fs.readFileSync(managedFile, 'utf8'));
     }
-    catch { /* first time */ }
+    catch {
+        /* first time */
+    }
     const format = { formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' } };
     for (const key of before.filter((k) => !(k in values))) {
         if (parseJsonc(text)?.[key] !== undefined)
@@ -101,7 +139,7 @@ const writeManagedSettings = (file, managedFile, values) => {
     fs.writeFileSync(file, text);
     fs.writeFileSync(managedFile, JSON.stringify(Object.keys(values)));
 };
-export const setupVscode = async (env, refresh) => {
+export async function setupVscode(env, refresh) {
     const root = tool('vscode');
     const exe = path.join(root, 'Code.exe');
     if (dryRun) {
@@ -109,7 +147,9 @@ export const setupVscode = async (env, refresh) => {
         return;
     }
     if (!exists(exe) || refresh) {
-        const release = await fetchJson('https://update.code.visualstudio.com/api/update/win32-' + (arch === 'arm64' ? 'arm64' : 'x64') + '-archive/stable/latest');
+        const release = await fetchJson('https://update.code.visualstudio.com/api/update/win32-' +
+            (arch === 'arm64' ? 'arm64' : 'x64') +
+            '-archive/stable/latest');
         log('Downloading VS Code ' + release.productVersion + ' (~150 MB once) ...');
         // Keep settings/extensions across a refresh: move the portable data folder aside and back, also when the install
         // fails (finally). A folder still parked from an interrupted earlier run is the one to keep.
@@ -120,7 +160,11 @@ export const setupVscode = async (env, refresh) => {
             fs.renameSync(keep, parked);
         }
         try {
-            await installArchive(release.url, root, { sha256: release.sha256hash, locate: 'Code.exe', fileName: 'vscode.zip' });
+            await downloader.archive(release.url, root, {
+                sha256: release.sha256hash,
+                locate: 'Code.exe',
+                fileName: 'vscode.zip',
+            });
             fs.writeFileSync(path.join(root, VERSION_MARKER), release.productVersion);
         }
         finally {
@@ -134,6 +178,8 @@ export const setupVscode = async (env, refresh) => {
     mkdirp(path.join(root, 'data'));
     env.prepend.push(path.join(root, 'bin'));
     desktopShortcut(exe);
-    const version = exists(path.join(root, VERSION_MARKER)) ? fs.readFileSync(path.join(root, VERSION_MARKER), 'utf8').trim() : 'installed';
+    const version = exists(path.join(root, VERSION_MARKER))
+        ? fs.readFileSync(path.join(root, VERSION_MARKER), 'utf8').trim()
+        : 'installed';
     env.summary.push('vscode: ' + version + ' (portable; run code . or use the desktop shortcut)');
-};
+}

package/dist/guest/toolchains/version-cache.d.ts

@@ -0,0 +1,16 @@
+export declare class VersionCache {
+    private readonly file;
+    /** Set after a network failure: the remaining lookups go straight to the remembered versions. */
+    private offline;
+    constructor(file?: () => string);
+    /**
+     * Resolves a version online and remembers it for a day (provisioning.refresh looks again). After a network failure
+     * the remaining lookups use the remembered versions instead of each waiting for the network; other errors (no such
+     * version) do not.
+     */
+    resolve(key: string, resolve: () => Promise<string>): Promise<string>;
+    private remembered;
+}
+export declare const versionCache: VersionCache;
+/** versionCache.resolve: the version for `key`, looked up at most once a day. */
+export declare function resolveCached(key: string, resolve: () => Promise<string>): Promise<string>;

package/dist/guest/toolchains/version-cache.js

@@ -0,0 +1,67 @@
+// Versions looked up online, remembered in tools\resolved-versions.json so most boots make no lookups and an offline
+// boot reuses what was installed last time.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { warn } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { toolsDir } from '../runtime/paths.js';
+import { errMsg } from '../../core/util/errors.js';
+import { tool } from './tool-env.js';
+import { readState } from './state-file.js';
+/** A remembered lookup; plain strings are what older versions wrote (treated as stale, still usable offline). */
+const ResolvedSchema = z.record(z.string(), z.union([z.string(), z.strictObject({ value: z.string(), at: z.number() })]));
+/** How long a looked-up version is trusted: boots within a day make no version lookups at all. */
+const FRESH_MS = 24 * 60 * 60 * 1000;
+function isNetworkError(e) {
+    return /fetch failed|timed? ?out|aborted|ENOTFOUND|EAI_AGAIN|ECONN|ENETUNREACH|EHOSTUNREACH|HTTP 5\d\d|socket/i.test(errMsg(e) + ' ' + String(e?.cause ?? ''));
+}
+export class VersionCache {
+    file;
+    /** Set after a network failure: the remaining lookups go straight to the remembered versions. */
+    offline = false;
+    constructor(file = () => tool('resolved-versions.json')) {
+        this.file = file;
+    }
+    /**
+     * Resolves a version online and remembers it for a day (provisioning.refresh looks again). After a network failure
+     * the remaining lookups use the remembered versions instead of each waiting for the network; other errors (no such
+     * version) do not.
+     */
+    async resolve(key, resolve) {
+        const cached = this.remembered()[key];
+        if (cached && (this.offline || (!session.provisioning.refresh && Date.now() - cached.at < FRESH_MS)))
+            return cached.value;
+        try {
+            const value = await resolve();
+            fs.mkdirSync(toolsDir, { recursive: true });
+            writeJsonAtomic(this.file(), { ...this.remembered(), [key]: { value, at: Date.now() } });
+            return value;
+        }
+        catch (e) {
+            if (isNetworkError(e))
+                this.offline = true;
+            if (!cached)
+                throw e;
+            warn('Could not look up the latest ' +
+                key +
+                ' online (' +
+                errMsg(e) +
+                '); using ' +
+                cached.value +
+                ' from an earlier start.');
+            return cached.value;
+        }
+    }
+    remembered() {
+        return Object.fromEntries(Object.entries(readState(this.file(), ResolvedSchema, {})).map(([k, v]) => [
+            k,
+            typeof v === 'string' ? { value: v, at: 0 } : v,
+        ]));
+    }
+}
+export const versionCache = new VersionCache();
+/** versionCache.resolve: the version for `key`, looked up at most once a day. */
+export function resolveCached(key, resolve) {
+    return versionCache.resolve(key, resolve);
+}

package/dist/host/agent-commands/commands.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from '../../core/types.js';
+export declare const commandsDir: (storageRoot: string) => string;
+export interface AgentCommand {
+    harness: string;
+    command: string;
+    real: string;
+}
+/** cmd.exe expands % and ^ even inside quotes: such paths cannot go into a forwarding file safely. */
+export declare const cmdSafe: (p: string) => boolean;
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export declare const realAgent: (command: string, skipDir: string, pathValue?: string) => string | null;
+/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
+export declare const agentCommands: (config: Config, storageRoot: string, pathValue?: string) => AgentCommand[];