windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/guest/toolchains/scripting.js

@@ -0,0 +1,137 @@
+// Ruby (RubyInstaller) and PHP (windows.php.net, with Composer), plus the Visual C++ runtime PHP and other native
+// tools need. Gems and Composer's global packages live in persistent storage.
+import fs from 'node:fs';
+import path from 'node:path';
+import { download, fetchJson, fetchText, installArchive, spawnAsync } from '../../shared/download.js';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, execAsync, execOutput, exists, log, mkdirp } from '../env.js';
+import { installOnce, resolveCached, tool, versionFromFiles, versionOf } from './common.js';
+import { pickPackageVersion } from './versions.js';
+/** Writes `<name>.cmd` into tools\shims (on PATH). */
+const shim = (env, name, command) => {
+    fs.writeFileSync(path.join(mkdirp(tool('shims')), name + '.cmd'), '@echo off\r\n' + command + ' %*\r\n');
+    env.prepend.push(tool('shims'));
+};
+// ---- Visual C++ runtime ----------------------------------------------------------------------------------------------
+const VC_REDIST = 'https://aka.ms/vs/17/release/vc_redist.x64.exe';
+/**
+ * vcruntime140.dll & co. A real installer (it writes to System32), so it runs on every boot; the installer itself is
+ * kept in persistent storage and only run when Microsoft's signature on it checks out. Resolves true when this call
+ * ran the installer. Only the "Visual C++ runtime" step reports it (`summary`); PHP calls it again just to be sure.
+ */
+export const setupVcRuntime = async (env, summary = true) => {
+    if (dryRun) {
+        log('(dry run) would install the Visual C++ runtime');
+        return false;
+    }
+    const system32 = path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32');
+    const missing = !exists(path.join(system32, 'vcruntime140.dll')) || !exists(path.join(system32, 'msvcp140.dll'));
+    if (missing) {
+        const installer = tool('vcredist', 'vc_redist.x64.exe');
+        if (!exists(installer)) {
+            log('Downloading the Visual C++ runtime ...');
+            await download(VC_REDIST, installer);
+        }
+        const signer = execOutput(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-Command', "$s = Get-AuthenticodeSignature -LiteralPath '" + installer.replace(/'/g, "''") + "'; if ($s.Status -eq 'Valid') { $s.SignerCertificate.Subject }"]);
+        if (signer.trim() !== 'CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US') {
+            fs.rmSync(installer, { force: true });
+            throw new Error('vc_redist.x64.exe is not signed by Microsoft; deleted it (it is downloaded again next boot)');
+        }
+        log('Installing the Visual C++ runtime ...');
+        // 1638: a newer version is already installed; 3010: installed, a restart would finish it (not needed for the DLLs).
+        const code = await spawnAsync(installer, ['/install', '/quiet', '/norestart']);
+        if (![0, 1638, 3010].includes(code ?? -1) || !exists(path.join(system32, 'vcruntime140.dll')))
+            throw new Error('the Visual C++ runtime installer failed (exit ' + code + ')');
+    }
+    if (summary)
+        env.summary.push('vc++ runtime: installed');
+    return missing;
+};
+const RUBY_ASSET = /^rubyinstaller-(\d+\.\d+\.\d+)-(\d+)-x64\.7z$/;
+/** RubyInstaller builds per Ruby version (newest build of each), from its GitHub releases. */
+const rubyBuilds = async () => {
+    const releases = await fetchJson('https://api.github.com/repos/oneclick/rubyinstaller2/releases?per_page=100');
+    const builds = new Map();
+    for (const asset of releases.filter((r) => !r.draft && !r.prerelease).flatMap((r) => r.assets)) {
+        const match = RUBY_ASSET.exec(asset.name);
+        const known = match && builds.get(match[1]);
+        if (match && (!known || Number(RUBY_ASSET.exec(known.name)[2]) < Number(match[2])))
+            builds.set(match[1], asset);
+    }
+    return builds;
+};
+export const setupRuby = async (env, config) => {
+    const wantedSpec = versionFromFiles(['.ruby-version']) ?? { spec: config.version, source: 'config' };
+    if (dryRun) {
+        log('(dry run) would provision Ruby ' + wantedSpec.spec);
+        return;
+    }
+    const version = await resolveCached('ruby:' + wantedSpec.spec, async () => pickPackageVersion([...(await rubyBuilds()).keys()], wantedSpec.spec) ?? Promise.reject(new Error('No RubyInstaller build matches "' + wantedSpec.spec + '"')));
+    const home = tool('ruby', version);
+    if (!exists(path.join(home, 'bin', 'ruby.exe'))) {
+        const asset = (await rubyBuilds()).get(version);
+        if (!asset)
+            throw new Error('RubyInstaller ' + version + ' is no longer published');
+        log('Downloading ' + asset.name + ' ...');
+        await installArchive(asset.browser_download_url, home, { sha256: asset.digest?.startsWith('sha256:') ? asset.digest.slice(7) : null, locate: 'ruby.exe', up: 1, fileName: asset.name });
+    }
+    const gems = tool('ruby-gems', version.split('.').slice(0, 2).join('.'));
+    Object.assign(env.vars, { GEM_HOME: gems, BUNDLE_USER_HOME: tool('bundle-home') });
+    env.prepend.push(path.join(home, 'bin'), path.join(gems, 'bin'));
+    env.summary.push('ruby: ' + versionOf(path.join(home, 'bin', 'ruby.exe')) + ' (from ' + wantedSpec.source + '; gems with C extensions need MSYS2, not included)');
+    const gem = path.join(home, 'bin', 'gem.cmd');
+    await installOnce(env, 'gem@' + version, config.gems, (pkg) => execAsync(SYSTEM.cmd(), ['/d', '/c', gem, 'install', pkg, '--no-document'], { env: { ...process.env, GEM_HOME: gems } }));
+};
+const PHP_EXTENSIONS = ['curl', 'fileinfo', 'gd', 'intl', 'mbstring', 'openssl', 'pdo_mysql', 'pdo_pgsql', 'pdo_sqlite', 'sodium', 'sqlite3', 'zip'];
+/** The non-thread-safe x64 zip of the newest release matching `spec` ("8" -> newest 8.x, "8.3" -> newest 8.3.x). */
+const phpBuild = async (spec) => {
+    const releases = await fetchJson('https://windows.php.net/downloads/releases/releases.json');
+    const pick = pickPackageVersion(Object.values(releases).map((r) => r.version), spec);
+    const release = Object.values(releases).find((r) => r.version === pick);
+    const build = release && Object.entries(release).find(([key, value]) => /^nts-vs\d+-x64$/.test(key) && typeof value === 'object' && value.zip)?.[1];
+    if (!release || typeof build !== 'object' || !build.zip)
+        throw new Error('No PHP build for Windows matches "' + spec + '"');
+    return { version: release.version, ...build.zip };
+};
+/** php.ini from the development template with the common extensions switched on. */
+const writePhpIni = (home) => {
+    const ini = path.join(home, 'php.ini');
+    if (exists(ini) || !exists(path.join(home, 'php.ini-development')))
+        return;
+    let text = fs.readFileSync(path.join(home, 'php.ini-development'), 'utf8')
+        .replace(/^;\s*extension_dir\s*=\s*"ext"/m, 'extension_dir = "' + path.join(home, 'ext') + '"');
+    for (const ext of PHP_EXTENSIONS.filter((e) => exists(path.join(home, 'ext', 'php_' + e + '.dll'))))
+        text = text.replace(new RegExp('^;(extension=' + ext + ')\\s*$', 'm'), '$1');
+    fs.writeFileSync(ini, text);
+};
+export const setupPhp = async (env, config) => {
+    const wantedSpec = versionFromFiles(['.php-version']) ?? { spec: config.version, source: 'config' };
+    if (dryRun) {
+        log('(dry run) would provision PHP ' + wantedSpec.spec + (config.composer ? ' + Composer' : ''));
+        return;
+    }
+    // No summary line of its own: the Visual C++ runtime step (which runs first) already reports it.
+    await setupVcRuntime(env, false);
+    const version = await resolveCached('php:' + wantedSpec.spec, async () => (await phpBuild(wantedSpec.spec)).version);
+    const home = tool('php', version);
+    if (!exists(path.join(home, 'php.exe'))) {
+        const build = await phpBuild(version);
+        log('Downloading ' + build.path + ' ...');
+        await installArchive('https://windows.php.net/downloads/releases/' + build.path, home, { sha256: build.sha256, locate: 'php.exe', fileName: build.path });
+    }
+    writePhpIni(home);
+    env.prepend.push(home);
+    env.summary.push('php: ' + version + ' (from ' + wantedSpec.source + ')');
+    if (!config.composer)
+        return;
+    const phar = tool('composer', 'composer.phar');
+    if (!exists(phar)) {
+        log('Downloading Composer ...');
+        await download('https://getcomposer.org/download/latest-stable/composer.phar', phar, (await fetchText('https://getcomposer.org/download/latest-stable/composer.phar.sha256sum')).trim().split(/\s+/)[0]);
+    }
+    const composerHome = tool('composer-home');
+    env.vars.COMPOSER_HOME = composerHome;
+    env.prepend.push(path.join(composerHome, 'vendor', 'bin'));
+    shim(env, 'composer', '"' + path.join(home, 'php.exe') + '" "' + phar + '"');
+    env.summary.push('composer: ' + (/\d+\.\d+\.\d+/.exec(execOutput(path.join(home, 'php.exe'), [phar, '--version', '--no-ansi']))?.[0] ?? 'installed'));
+};

package/dist/guest/toolchains/versions.d.ts

@@ -0,0 +1,47 @@
+export interface NodeRelease {
+    version: string;
+    lts: string | false;
+}
+/** Turns an .nvmrc-style spec (20, v20.11.1, lts/*, lts/iron, node, latest) into an exact version like 20.11.1. */
+export declare const pickNodeVersion: (releases: NodeRelease[], spec: string) => string | null;
+/**
+ * Which of this PC's nvm versions to copy along with `current`: at most `max` in total, current included, the rest
+ * spread across the range (newest of each major first, then evenly spaced from oldest to newest).
+ */
+export declare const pickSpreadVersions: (available: string[], current: string, max: number) => string[];
+/** Newest stable version matching a prefix spec ("3" -> 3.13.1, "3.12" -> 3.12.10). */
+export declare const pickPackageVersion: (all: string[], spec: string) => string | null;
+/** Version spec from a version file's text (.ruby-version "ruby-3.3.1", .java-version "temurin-21", ...): its first x[.y[.z]]. */
+export declare const specFromVersionFile: (text: string) => string | null;
+/** Java major version from .java-version ("21", "17.0.9", "1.8", "temurin-21") or .sdkmanrc ("java=21.0.2-tem"). */
+export declare const javaMajorFrom: (text: string, sdkmanrc?: boolean) => string | null;
+export interface GoRelease {
+    version: string;
+    stable: boolean;
+    files: {
+        filename: string;
+        os: string;
+        arch: string;
+        kind: string;
+        sha256: string;
+    }[];
+}
+/** "stable" / "latest" -> newest stable release; "1.23" -> newest 1.23.x; "1.23.2" -> exactly that. Returns go.dev's entry. */
+export declare const pickGoRelease: (releases: GoRelease[], spec: string) => GoRelease | null;
+/**
+ * Does the project use a language? `entries` are file names in the workspace root and one folder down ("api/go.mod");
+ * markers are exact names or "*.ext".
+ */
+export declare const projectUses: (entries: readonly string[], markers: readonly string[]) => boolean;
+/** Newest MSVC tools version among VS manifest package ids ("microsoft.vc.14.44.17.14.tools.hostx64.targetx64.base"). */
+export declare const pickMsvcVersion: (packageIds: string[], spec?: string) => string | null;
+/** Newest Windows SDK build among component ids ("microsoft.visualstudio.component.windows11sdk.26100"). */
+export declare const pickWindowsSdk: (packageIds: string[], spec?: string) => {
+    build: string;
+    componentId: string;
+} | null;
+/** The .cab files an SDK .msi refers to (their names are inside the msi as plain "<32 hex>.cab"). */
+export declare const msiCabs: (msi: Buffer) => string[];
+/** The oldest CMake many projects (OpenMoHAA among them) accept. */
+export declare const CMAKE_FLOOR = "3.25";
+export declare const cmakeTooOld: (version: string) => boolean;

package/dist/guest/toolchains/versions.js

@@ -0,0 +1,77 @@
+// Version picking for the toolchains. Pure functions only (no environment, no I/O), so the host and the tests can
+// import them without loading the guest runtime.
+/** Turns an .nvmrc-style spec (20, v20.11.1, lts/*, lts/iron, node, latest) into an exact version like 20.11.1. */
+export const pickNodeVersion = (releases, spec) => {
+    const s = spec.trim().toLowerCase().replace(/^v/, '');
+    const hit = ['node', 'latest', 'current', 'stable'].includes(s) ? releases[0]
+        : s === 'lts' || s === 'lts/*' ? releases.find((r) => r.lts)
+            : s.startsWith('lts/') ? releases.find((r) => typeof r.lts === 'string' && r.lts.toLowerCase() === s.slice(4))
+                : releases.find((r) => r.version === 'v' + s || r.version.startsWith('v' + s + '.'));
+    return hit ? hit.version.slice(1) : null;
+};
+/**
+ * Which of this PC's nvm versions to copy along with `current`: at most `max` in total, current included, the rest
+ * spread across the range (newest of each major first, then evenly spaced from oldest to newest).
+ */
+export const pickSpreadVersions = (available, current, max) => {
+    const byVersion = (a, b) => a.localeCompare(b, undefined, { numeric: true });
+    const exact = available.filter((v) => /^\d+\.\d+\.\d+$/.test(v) && v !== current).sort(byVersion);
+    const newestPerMajor = exact.filter((v, i) => exact[i + 1]?.split('.')[0] !== v.split('.')[0]);
+    const pool = newestPerMajor.filter((v) => v.split('.')[0] !== current.split('.')[0]);
+    const want = Math.max(0, max - 1);
+    const picked = want >= pool.length ? pool
+        : want === 1 ? [pool[pool.length - 1]]
+            : Array.from({ length: want }, (_, i) => pool[Math.round(i * (pool.length - 1) / (want - 1))]);
+    return [current, ...picked];
+};
+/** Newest stable version matching a prefix spec ("3" -> 3.13.1, "3.12" -> 3.12.10). */
+export const pickPackageVersion = (all, spec) => {
+    const s = spec.trim().replace(/^python-?/i, '');
+    const stable = all.filter((v) => /^\d+(\.\d+)*$/.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    return stable.find((v) => v === s || v.startsWith(s + '.')) ?? null;
+};
+/** Version spec from a version file's text (.ruby-version "ruby-3.3.1", .java-version "temurin-21", ...): its first x[.y[.z]]. */
+export const specFromVersionFile = (text) => /(\d+(?:\.\d+){0,2})/.exec(text.split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).find(Boolean) ?? '')?.[1] ?? null;
+/** Java major version from .java-version ("21", "17.0.9", "1.8", "temurin-21") or .sdkmanrc ("java=21.0.2-tem"). */
+export const javaMajorFrom = (text, sdkmanrc = false) => {
+    const line = sdkmanrc ? /^\s*java\s*=\s*(.+)$/m.exec(text)?.[1] : text;
+    const spec = line ? specFromVersionFile(line) : null;
+    if (!spec)
+        return null;
+    const [major, minor] = spec.split('.');
+    return major === '1' && minor ? minor : major;
+};
+/** "stable" / "latest" -> newest stable release; "1.23" -> newest 1.23.x; "1.23.2" -> exactly that. Returns go.dev's entry. */
+export const pickGoRelease = (releases, spec) => {
+    const s = spec.trim().toLowerCase().replace(/^go/, '');
+    const stable = releases.filter((r) => r.stable);
+    if (s === 'stable' || s === 'latest')
+        return stable[0] ?? null;
+    return stable.find((r) => r.version === 'go' + s || r.version.startsWith('go' + s + '.')) ?? null;
+};
+/**
+ * Does the project use a language? `entries` are file names in the workspace root and one folder down ("api/go.mod");
+ * markers are exact names or "*.ext".
+ */
+export const projectUses = (entries, markers) => entries.some((entry) => {
+    const name = entry.split(/[\/]/).pop().toLowerCase();
+    return markers.some((m) => (m.startsWith('*.') ? name.endsWith(m.slice(1).toLowerCase()) : name === m.toLowerCase()));
+});
+/** Newest MSVC tools version among VS manifest package ids ("microsoft.vc.14.44.17.14.tools.hostx64.targetx64.base"). */
+export const pickMsvcVersion = (packageIds, spec = 'latest') => {
+    const versions = packageIds.map((id) => /^microsoft\.vc\.(\d+\.\d+\.\d+\.\d+)\.tools\.hostx64\.targetx64\.base$/i.exec(id)?.[1]).filter((v) => Boolean(v));
+    const sorted = [...new Set(versions)].sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    return (spec === 'latest' ? sorted[0] : sorted.find((v) => v === spec || v.startsWith(spec + '.'))) ?? null;
+};
+/** Newest Windows SDK build among component ids ("microsoft.visualstudio.component.windows11sdk.26100"). */
+export const pickWindowsSdk = (packageIds, spec = 'latest') => {
+    const found = packageIds.map((id) => ({ id, build: /^microsoft\.visualstudio\.component\.windows1[01]sdk\.(\d+)$/i.exec(id)?.[1] })).filter((x) => Boolean(x.build));
+    const sorted = found.sort((a, b) => Number(b.build) - Number(a.build));
+    const hit = spec === 'latest' ? sorted[0] : sorted.find((x) => x.build === spec.replace(/^10\.0\./, '').split('.')[0]);
+    return hit ? { build: hit.build, componentId: hit.id } : null;
+};
+/** The .cab files an SDK .msi refers to (their names are inside the msi as plain "<32 hex>.cab"). */
+export const msiCabs = (msi) => [...new Set([...msi.toString('latin1').matchAll(/([0-9a-f]{32}\.cab)/gi)].map((m) => m[1].toLowerCase()))];
+/** The oldest CMake many projects (OpenMoHAA among them) accept. */
+export const CMAKE_FLOOR = '3.25';
+export const cmakeTooOld = (version) => /^\d+\.\d+/.test(version) && version.localeCompare(CMAKE_FLOOR, undefined, { numeric: true }) < 0;

package/dist/guest/toolchains/vscode.d.ts

@@ -0,0 +1,2 @@
+import { type ToolEnv } from './common.js';
+export declare const setupVscode: (env: ToolEnv, refresh: boolean) => Promise<void>;

package/dist/guest/toolchains/vscode.js

@@ -0,0 +1,53 @@
+// VS Code for debugging inside the sandbox: the portable zip build, checksum-verified. A `data` folder next to Code.exe
+// switches it to portable mode, so settings and extensions live in C:\AgentData\tools\vscode\data and persist.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../shared/download.js';
+import { dryRun, exists, isWin, log, mkdirp, powershell } from '../env.js';
+import { arch, tool } from './common.js';
+/** Newer builds keep their files under a commit-hash folder, so the installed version is recorded here. */
+const VERSION_MARKER = '.agent-sandbox-version';
+const desktopShortcut = (exe) => {
+    if (!isWin)
+        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()');
+};
+export const setupVscode = async (env, refresh) => {
+    const root = tool('vscode');
+    const exe = path.join(root, 'Code.exe');
+    if (dryRun) {
+        log('(dry run) would provision VS Code');
+        return;
+    }
+    if (!exists(exe) || refresh) {
+        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.
+        const keep = path.join(root, 'data');
+        const parked = root + '-data';
+        if (exists(keep)) {
+            fs.rmSync(parked, { recursive: true, force: true });
+            fs.renameSync(keep, parked);
+        }
+        try {
+            await installArchive(release.url, root, { sha256: release.sha256hash, locate: 'Code.exe', fileName: 'vscode.zip' });
+            fs.writeFileSync(path.join(root, VERSION_MARKER), release.productVersion);
+        }
+        finally {
+            if (exists(parked)) {
+                mkdirp(root);
+                fs.rmSync(keep, { recursive: true, force: true });
+                fs.renameSync(parked, keep);
+            }
+        }
+    }
+    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';
+    env.summary.push('vscode: ' + version + ' (portable; run code . or use the desktop shortcut)');
+};

package/dist/guest/view.d.ts

@@ -0,0 +1 @@
+export declare const viewSession: (id: string) => Promise<number>;

package/dist/guest/view.js

@@ -0,0 +1,22 @@
+// A terminal tab inside the sandbox that shows one agent session (same pseudo console the host can attach to).
+// Usage: node view.js <sessionId>
+import { connect, runTerminalClient } from '../shared/pty-client.js';
+import { readSession } from '../shared/rundir.js';
+import { dataDir } from './env.js';
+export const viewSession = async (id) => {
+    const session = readSession(dataDir, id);
+    if (!session?.attach) {
+        console.error('Session ' + id + ' is not running.');
+        return 1;
+    }
+    const socket = await connect({ ...session.attach, addresses: ['127.0.0.1'] });
+    const result = await runTerminalClient(socket, session.attach.token);
+    if (result.reason === 'exit')
+        console.log(session.harness + ' exited with code ' + result.exitCode + '.');
+    else if (result.reason === 'error')
+        console.log('Session error: ' + result.message);
+    return result.reason === 'exit' ? result.exitCode : 1;
+};
+if (process.argv[1]?.endsWith('view.js') && process.argv[2]) {
+    viewSession(process.argv[2]).then((code) => { process.exitCode = code; }, (e) => { console.error(e instanceof Error ? e.message : String(e)); process.exitCode = 1; });
+}

package/dist/host/accounts.d.ts

@@ -0,0 +1,32 @@
+export interface Account {
+    name: string;
+    savedAt: string;
+    email: string | null;
+    credentials: unknown;
+    oauthAccount: unknown;
+}
+export interface AccountRow {
+    name: string;
+    email: string | null;
+    isDefault: boolean;
+    isActive: boolean;
+    savedAt: string;
+}
+export declare const accountsDir: (storageRoot: string) => string;
+export declare const sandboxClaudeDir: (dataPath: string) => string;
+export declare const readAccount: (storageRoot: string, name: string) => Account | null;
+export declare const defaultAccount: (storageRoot: string) => string | null;
+export declare const activeAccount: (dataPath: string) => string | null;
+export declare const listAccounts: (storageRoot: string, dataPath: string) => AccountRow[];
+/** Saves the sandbox's current login (or this PC's, with fromHost) under `name`. */
+export declare const saveAccount: (storageRoot: string, dataPath: string, name: string, fromHost: {
+    claudeDir: string;
+    globalStateFile: string;
+} | null) => Account;
+/**
+ * Makes `name` the sandbox's login. Claude refreshes (rotates) tokens while it runs, so the outgoing account's
+ * current tokens are saved back first; otherwise its stored refresh token could already be invalid.
+ */
+export declare const activateAccount: (storageRoot: string, dataPath: string, name: string) => Account;
+export declare const setDefaultAccount: (storageRoot: string, name: string | null) => void;
+export declare const removeAccount: (storageRoot: string, name: string) => void;

package/dist/host/accounts.js

@@ -0,0 +1,119 @@
+// Several Claude logins for the sandbox. Each account is a saved copy of Claude's .credentials.json plus the
+// `oauthAccount` block of .claude.json, kept in host-only storage (<storage>\accounts, never mapped into a sandbox).
+// Switching writes them into the sandbox's persistent Claude state; when the sandbox is running the agent is then
+// restarted in place with --continue so the conversation carries on.
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertNoLinks, fail, fileExists, isLink, removeLink, tryReadJson, writeJson } from '../core/util.js';
+const NAME = /^[A-Za-z0-9_-]{1,40}$/;
+const ACCOUNT_CACHES = ['remote-settings.json', 'policy-limits.json', 'policy-limits.json.stamp.json'];
+const MAX_LOGIN_BYTES = 1024 * 1024;
+/** .claude.json holds per-project state and can be large; it is still capped so a hostile file cannot exhaust memory. */
+const MAX_STATE_BYTES = 256 * 1024 * 1024;
+export const accountsDir = (storageRoot) => path.join(storageRoot, 'accounts');
+export const sandboxClaudeDir = (dataPath) => path.join(dataPath, 'state', 'claude');
+const storageOf = (dataPath) => path.dirname(path.dirname(dataPath));
+const dataName = (dataPath) => path.basename(dataPath);
+const accountFile = (storageRoot, name) => path.join(accountsDir(storageRoot), name + '.json');
+const indexFile = (storageRoot) => path.join(accountsDir(storageRoot), 'index.json');
+const readIndex = (storageRoot) => tryReadJson(indexFile(storageRoot)) ?? {};
+const updateIndex = (storageRoot, change) => writeJson(indexFile(storageRoot), change(readIndex(storageRoot)));
+const assertName = (name) => { if (!NAME.test(name))
+    fail('Invalid account name "' + name + '".', 'Use letters, numbers, - and _ only (max 40), e.g. work or personal.'); };
+const emailOf = (oauthAccount) => {
+    const email = oauthAccount?.emailAddress;
+    return typeof email === 'string' ? email.slice(0, 200) : null;
+};
+export const readAccount = (storageRoot, name) => (NAME.test(name) ? tryReadJson(accountFile(storageRoot, name)) : null);
+export const defaultAccount = (storageRoot) => readIndex(storageRoot).default ?? null;
+export const activeAccount = (dataPath) => readIndex(storageOf(dataPath)).active?.[dataName(dataPath)] ?? null;
+const setActive = (dataPath, name) => updateIndex(storageOf(dataPath), (i) => ({ ...i, active: { ...i.active, [dataName(dataPath)]: name } }));
+export const listAccounts = (storageRoot, dataPath) => {
+    const dir = accountsDir(storageRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    const def = defaultAccount(storageRoot);
+    const active = activeAccount(dataPath);
+    return fs.readdirSync(dir)
+        .filter((f) => f.endsWith('.json') && f !== 'index.json')
+        .map((f) => readAccount(storageRoot, f.slice(0, -5)))
+        .filter((a) => a !== null)
+        .map((a) => ({ name: a.name, email: a.email, isDefault: a.name === def, isActive: a.name === active, savedAt: a.savedAt }));
+};
+/** Reads a JSON file that may be sandbox-written: no links, size-capped. */
+const readUntrusted = (file, max) => (fileExists(file) && !isLink(file) && fs.statSync(file).size <= max ? tryReadJson(file) : null);
+/** The login currently in a Claude config folder (+ its global state file). */
+const readLogin = (claudeDir, globalStateFile) => {
+    const credentials = readUntrusted(path.join(claudeDir, '.credentials.json'), MAX_LOGIN_BYTES);
+    if (!credentials || typeof credentials !== 'object')
+        fail('No Claude login found in ' + claudeDir + '.', 'Sign in to Claude first (inside the sandbox, or on this PC with --from-host), then save it again.');
+    return { credentials, oauthAccount: readUntrusted(globalStateFile, MAX_STATE_BYTES)?.oauthAccount ?? null };
+};
+const store = (storageRoot, name, login) => {
+    const account = { name, savedAt: new Date().toISOString(), email: emailOf(login.oauthAccount), ...login };
+    writeJson(accountFile(storageRoot, name), account);
+    return account;
+};
+const sandboxLogin = (dataPath) => {
+    assertNoLinks(dataPath, sandboxClaudeDir(dataPath));
+    return { claudeDir: sandboxClaudeDir(dataPath), globalStateFile: path.join(sandboxClaudeDir(dataPath), '.claude.json') };
+};
+/** Saves the sandbox's current login (or this PC's, with fromHost) under `name`. */
+export const saveAccount = (storageRoot, dataPath, name, fromHost) => {
+    assertName(name);
+    const source = fromHost ?? sandboxLogin(dataPath);
+    const account = store(storageRoot, name, readLogin(source.claudeDir, source.globalStateFile));
+    if (!fromHost)
+        setActive(dataPath, name);
+    if (!defaultAccount(storageRoot))
+        setDefaultAccount(storageRoot, name);
+    return account;
+};
+/** Replaces a file that may be a sandbox-planted link instead of writing through it. */
+const writeSandboxJson = (file, value) => {
+    if (isLink(file))
+        removeLink(file);
+    writeJson(file, value);
+};
+/**
+ * Makes `name` the sandbox's login. Claude refreshes (rotates) tokens while it runs, so the outgoing account's
+ * current tokens are saved back first; otherwise its stored refresh token could already be invalid.
+ */
+export const activateAccount = (storageRoot, dataPath, name) => {
+    const account = readAccount(storageRoot, name) ?? fail('Unknown account "' + name + '".', 'Saved accounts: ' + (listAccounts(storageRoot, dataPath).map((a) => a.name).join(', ') || 'none yet; save one with sandbox account save <name>'));
+    const { claudeDir, globalStateFile } = sandboxLogin(dataPath);
+    const outgoing = activeAccount(dataPath);
+    if (outgoing && outgoing !== name && readAccount(storageRoot, outgoing) && fileExists(path.join(claudeDir, '.credentials.json'))) {
+        try {
+            store(storageRoot, outgoing, readLogin(claudeDir, globalStateFile));
+        }
+        catch { /* nothing usable to save back */ }
+    }
+    fs.mkdirSync(claudeDir, { recursive: true });
+    // Caches tied to the previous account (Claude deletes these on /logout); otherwise its org policy could linger.
+    for (const cache of ACCOUNT_CACHES) {
+        const file = path.join(claudeDir, cache);
+        if (isLink(file))
+            removeLink(file);
+        else
+            fs.rmSync(file, { force: true });
+    }
+    writeSandboxJson(path.join(claudeDir, '.credentials.json'), account.credentials);
+    const state = readUntrusted(globalStateFile, MAX_STATE_BYTES);
+    if (account.oauthAccount && (state || !fileExists(globalStateFile)))
+        writeSandboxJson(globalStateFile, { ...(state ?? {}), oauthAccount: account.oauthAccount });
+    setActive(dataPath, name);
+    return account;
+};
+export const setDefaultAccount = (storageRoot, name) => {
+    if (name !== null && !readAccount(storageRoot, name))
+        fail('Unknown account "' + name + '".', 'See your accounts with: sandbox account list');
+    updateIndex(storageRoot, (i) => ({ ...i, default: name ?? undefined }));
+};
+export const removeAccount = (storageRoot, name) => {
+    if (!readAccount(storageRoot, name))
+        fail('Unknown account "' + name + '".', 'See your accounts with: sandbox account list');
+    fs.rmSync(accountFile(storageRoot, name));
+    if (defaultAccount(storageRoot) === name)
+        setDefaultAccount(storageRoot, null);
+};

package/dist/host/channel.d.ts

@@ -0,0 +1,37 @@
+import os from 'node:os';
+import type { GuestRequest, GuestResponse, SandboxStatus, SessionStatus } from '../core/types.js';
+import { type Viewers } from '../shared/pty-client.js';
+/**
+ * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
+ * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
+ */
+export declare const isSandboxAddress: (ip: string, interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>) => boolean;
+/** Waits until the sandbox finished provisioning, printing each boot step. */
+export declare const waitForReady: (dataPath: string, launchId: string | null, isAlive: () => boolean) => Promise<SandboxStatus>;
+export declare const sendRequest: (dataPath: string, request: GuestRequest) => void;
+export declare const waitForResponse: (dataPath: string, requestId: string, isAlive: () => boolean, timeoutMs: number) => Promise<GuestResponse>;
+export declare const requestSession: (dataPath: string, harness: string, args: string[], cwd: string) => string;
+export declare const waitForSession: (dataPath: string, sessionId: string, isAlive: () => boolean, timeoutMs?: number) => Promise<SessionStatus>;
+/** Runs a command inside the sandbox (in the workspace or a folder below it) and returns its output. */
+export declare const execInSandbox: (dataPath: string, command: string[], cwd: string, timeoutSeconds: number, isAlive: () => boolean) => Promise<GuestResponse>;
+/** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
+export declare const restartSessions: (dataPath: string, harness: string | null, isAlive: () => boolean) => Promise<GuestResponse>;
+export declare const pingSandbox: (dataPath: string, isAlive: () => boolean) => Promise<GuestResponse>;
+export declare const runningSessions: (dataPath: string) => SessionStatus[];
+/** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
+export declare const MAX_QUERIED_SESSIONS = 32;
+/** Running sessions of the sandbox that is running now (its launch id), newest last, capped. */
+export declare const currentSessions: (dataPath: string) => SessionStatus[];
+/** The session with this id (or id prefix), else the most recently started running one. */
+export declare const pickSession: (dataPath: string, sessionId?: string) => SessionStatus;
+/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
+export declare const sessionViewers: (session: SessionStatus) => Promise<Viewers | null>;
+/**
+ * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
+ * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
+ */
+export declare const findUnwatchedSession: (dataPath: string, harness: string, cwd: string) => Promise<SessionStatus | null>;
+/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
+export declare const attachTerminal: (session: SessionStatus) => Promise<number>;
+/** Forgets status from a previous sandbox run so nothing stale is picked up. */
+export declare const resetRunDir: (dataPath: string) => void;