A local-first multi-agent app development platform, built on PenguinHarness
/**
* What the card's buttons do: install WSL (elevated, once), initialize the sandbox distro, check
* that it confines, and remove it. Each runs in the background and reports the step it is on;
* the card shows that as a progress notice and reads it again until the task ends.
*/
import { spawn } from "node:child_process";
import { createHash } from "node:crypto";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import type { SandboxPolicy } from "@adelie/core/plugin";
import {
decodeOutput,
localDrives,
pathKind,
readHost,
readState,
removeState,
runWsl,
stateDir,
wslExe,
writeState,
} from "./host.js";
import type { HostFacts, WslState } from "./host.js";
import { wslArgs } from "./launch.js";
import type { LaunchJob } from "./launch.js";
import { bwrapArgs, chdirRoots, linuxProgram, toLinuxPath } from "./profile.js";
/** The Linux the distro is built from. */
export type BaseImage = "ubuntu" | "alpine";
/** This backend's settings, as it reads them from its group. */
export interface WslSettings {
distro: string;
base: BaseImage;
exposeWindowsDrives: boolean;
/** A package mirror for the chosen base, or "" for its official one. */
mirror: string;
packages: string[];
}
export const DEFAULT_DISTRO = "penguin-sandbox";
/**
* Ubuntu by default, not Alpine. Alpine's rootfs is a tenth of the size, but it is musl: a
* prebuilt native npm module, a pip wheel or a downloaded binary that works everywhere else
* does not run on it, and what a person finds when they search for the error is glibc advice.
* The sandbox is where an agent's commands live, so it has to be the ordinary Linux.
*/
export const DEFAULT_BASE: BaseImage = "ubuntu";
/** The Ubuntu LTS series the base rootfs comes from. */
export const UBUNTU_SERIES = "24.04";
/** Where each base's official images and packages come from. */
export const UBUNTU_IMAGES = "https://cdimage.ubuntu.com/ubuntu-base/releases";
export const UBUNTU_ARCHIVE = "http://archive.ubuntu.com/ubuntu";
export const UBUNTU_SECURITY = "http://security.ubuntu.com/ubuntu";
export const ALPINE_MIRROR = "https://dl-cdn.alpinelinux.org/alpine";
/** `nodejs` is what runs the harness's hook scripts and its file-tool helper inside the distro (see core's fs-worker.ts); the rest is what a shell session expects to find. */
export const DEFAULT_PACKAGES = ["git", "curl", "nodejs"];
/** The account commands run as inside the distro: not root, so bwrap is the only way up. */
export const SANDBOX_USER = "penguin";
/** Its group's stored document as settings; anything unusable falls back to the default. */
export function wslSettingsOf(doc: Record<string, unknown>): WslSettings {
const distro = typeof doc.distro === "string" ? doc.distro.trim() : "";
const mirror = typeof doc.mirror === "string" ? doc.mirror.trim() : "";
const packages = Array.isArray(doc.packages)
? doc.packages.map((p) => String(p).trim()).filter((p) => /^[a-z0-9][a-z0-9._+-]*$/.test(p))
: DEFAULT_PACKAGES;
return {
distro: /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(distro) ? distro : DEFAULT_DISTRO,
base: doc.base === "alpine" ? "alpine" : DEFAULT_BASE,
exposeWindowsDrives: doc.exposeWindowsDrives === true,
mirror: /^https?:\/\//.test(mirror) ? mirror.replace(/\/+$/, "") : "",
packages,
};
}
/** The launcher job for one command under one policy — what the provider and the check share. */
export function launchJob(
argv: readonly string[],
policy: SandboxPolicy,
settings: WslSettings,
state: WslState,
): LaunchJob {
const host = {
distro: state.distro,
exposeWindowsDrives: settings.exposeWindowsDrives,
drives: localDrives(),
kind: pathKind,
};
return {
wsl: wslExe(),
distro: state.distro,
user: state.user,
bwrap: bwrapArgs(policy, host),
chdirRoots: chdirRoots(policy, host),
command: [linuxProgram(argv[0] ?? "bash"), ...argv.slice(1)],
};
}
/** Two languages for everything the card says. */
export interface Text {
en: string;
zh: string;
}
export type TaskKind = "install" | "initialize" | "check" | "remove";
export const TASK_TITLES: Record<TaskKind, Text> = {
install: { en: "Installing WSL", zh: "正在安装 WSL" },
initialize: { en: "Initializing the sandbox distro", zh: "正在初始化沙盒发行版" },
check: { en: "Checking confinement", zh: "正在检查隔离效果" },
remove: { en: "Removing the sandbox distro", zh: "正在移除沙盒发行版" },
};
/** One line of the confinement check. `ok: null` is information, not a verdict. */
export interface CheckLine {
name: Text;
ok: boolean | null;
detail: string;
}
export interface TaskOutcome {
kind: TaskKind;
ok: boolean;
message: Text;
at: number;
/** Set by an install whose features only take effect after a restart. */
restart?: boolean;
}
/** Everything the card reads, kept for the life of the plugin's module. */
export class Tasks {
running: { kind: TaskKind; step: Text; startedAt: number } | null = null;
last: TaskOutcome | null = null;
lastCheck: { at: number; lines: CheckLine[] } | null = null;
host: HostFacts | null = null;
private hostRead: Promise<void> | null = null;
private hostReadAt = 0;
/** Reads the machine again; concurrent callers share one read. */
refreshHost(): Promise<void> {
if (this.hostRead !== null) return this.hostRead;
this.hostRead = readHost()
.then((facts) => {
this.host = facts;
})
.finally(() => {
this.hostRead = null;
this.hostReadAt = Date.now();
});
return this.hostRead;
}
/** A stale reading is refreshed in the background; the card shows what it has meanwhile. */
touchHost(maxAgeMs = 15_000): void {
if (this.running === null && Date.now() - this.hostReadAt > maxAgeMs) void this.refreshHost();
}
/** Starts a task unless one runs; resolves when it ends, having recorded its outcome. */
start(
kind: TaskKind,
body: (report: (step: Text) => void) => Promise<Omit<TaskOutcome, "kind" | "at">>,
): Promise<void> | null {
if (this.running !== null) return null;
const task = { kind, step: { en: "starting…", zh: "开始…" }, startedAt: Date.now() };
this.running = task;
const report = (step: Text) => {
task.step = step;
};
return body(report)
.catch((err: unknown) => {
const text = err instanceof Error ? err.message : String(err);
return { ok: false, message: { en: text, zh: text } };
})
.then(async (outcome) => {
this.last = { kind, at: Date.now(), ...outcome };
await this.refreshHost();
this.running = null;
});
}
}
// ---------------------------------------------------------------------------------------------
// Install WSL — the one step that needs an administrator.
// ---------------------------------------------------------------------------------------------
function installScript(): string {
return fileURLToPath(new URL("../setup/install-wsl.ps1", import.meta.url));
}
function powershell(env: NodeJS.ProcessEnv = process.env): string {
return path.win32.join(
env.SystemRoot ?? "C:\\Windows",
"System32",
"WindowsPowerShell",
"v1.0",
"powershell.exe",
);
}
/** The command that raises the consent prompt for the install script (each argument quoted once). */
export function elevationCommand(script: string, log: string): string {
const args = ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script, "-Log", log]
.map((arg) => `'${arg.replace(/'/g, "''")}'`)
.join(",");
return (
`$ErrorActionPreference='Stop'; ` +
`Start-Process -FilePath 'powershell.exe' -Verb RunAs -WindowStyle Hidden -ArgumentList @(${args})`
);
}
function readText(file: string): string {
try {
return decodeOutput(fs.readFileSync(file)).replace(/\0/g, "");
} catch {
return "";
}
}
/** The last thing a progress-writing program printed: its last non-empty line or `\r` segment. */
export function lastSegment(text: string): string {
const parts = text.split(/[\r\n]+/).map((s) => s.trim());
for (let i = parts.length - 1; i >= 0; i--) if (parts[i] !== "") return parts[i]!;
return "";
}
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
export async function installWsl(
report: (step: Text) => void,
): Promise<Omit<TaskOutcome, "kind" | "at">> {
const script = installScript();
if (!fs.existsSync(script)) {
const text = `the install script is missing from this installation (${script})`;
return { ok: false, message: { en: text, zh: `本次安装缺少脚本(${script})` } };
}
const log = path.win32.join(stateDir(), "install.log");
fs.mkdirSync(stateDir(), { recursive: true });
for (const f of [log, `${log}.out`, `${log}.err`]) fs.rmSync(f, { force: true });
// Not detached: ShellExecute's RunAs verb raises no prompt from a process without a console
// (measured on Windows 11 by the account backend). `unref` keeps the server free of it.
let failure = "";
const child = spawn(powershell(), ["-NoProfile", "-Command", elevationCommand(script, log)], {
stdio: "ignore",
windowsHide: true,
});
child.on("error", (err) => {
failure = err.message;
});
child.on("exit", (code) => {
if (code !== 0 && code !== null) failure = `the permission request exited ${code}`;
});
child.unref();
report({
en: "waiting for you to accept the Windows permission prompt on this machine's screen",
zh: "等待你在这台机器的屏幕上确认 Windows 授权弹窗",
});
const started = Date.now();
let exit: number | null = null;
while (exit === null) {
await sleep(1000);
if (failure !== "") {
return {
ok: false,
message: {
en: `No prompt was shown: ${failure}. Run ${script} -Log <file> from an administrator PowerShell instead.`,
zh: `没有弹出授权窗口:${failure}。请改为在管理员 PowerShell 中运行 ${script} -Log <文件>。`,
},
};
}
const text = readText(log);
if (text === "") {
if (Date.now() - started > 5 * 60_000) {
return {
ok: false,
message: {
en: "Nobody accepted the Windows permission prompt within five minutes, so WSL was not installed.",
zh: "五分钟内没有人确认 Windows 授权弹窗,WSL 未安装。",
},
};
}
continue;
}
const done = /PENGUIN-EXIT (-?\d+)/.exec(text);
if (done) {
exit = Number(done[1]);
break;
}
const tail = lastSegment(readText(`${log}.out`)) || lastSegment(readText(`${log}.err`));
report({
en: tail === "" ? "wsl --install is running" : `wsl --install: ${tail}`,
zh: tail === "" ? "wsl --install 正在运行" : `wsl --install:${tail}`,
});
if (Date.now() - started > 60 * 60_000) {
return {
ok: false,
message: {
en: "wsl --install ran for an hour without finishing.",
zh: "wsl --install 运行一小时仍未结束。",
},
};
}
}
const output = `${readText(`${log}.out`)}\n${readText(`${log}.err`)}`;
report({ en: "reading what the install left", zh: "读取安装结果" });
const host = await readHost();
const restart = exit === 3010 || /restart|reboot|重新启动|重启/i.test(output);
if (exit === 0 || exit === 3010) {
if (host.wsl === "installed" && !restart) {
return {
ok: true,
message: {
en: `WSL is installed (${host.version ?? ""}). Initialize the sandbox distro next.`,
zh: `WSL 已安装(${host.version ?? ""})。下一步初始化沙盒发行版。`,
},
};
}
return {
ok: true,
restart: true,
message: {
en: "WSL is installed. Restart Windows to finish, then come back and initialize the sandbox distro.",
zh: "WSL 已安装。重启 Windows 完成安装后,回到这里初始化沙盒发行版。",
},
};
}
const reason = lastSegment(output) || `exit code ${exit}`;
return {
ok: false,
message: { en: `wsl --install failed: ${reason}`, zh: `wsl --install 失败:${reason}` },
};
}
// ---------------------------------------------------------------------------------------------
// Initialize — unelevated: download Alpine, import it, provision it.
// ---------------------------------------------------------------------------------------------
/** The rootfs one base offers: where to get it, what it should hash to, and its version. */
export interface BaseRelease {
version: string;
file: string;
url: string;
sha256: string;
size: number;
}
/** The minirootfs entry of an Alpine latest-releases.yaml (a list of flat maps). */
export function parseMinirootfs(yaml: string): Omit<BaseRelease, "url"> | null {
for (const block of yaml.split(/^-\s*$/m)) {
const field = (key: string) => new RegExp(`^\\s*${key}:\\s*(.+?)\\s*$`, "m").exec(block)?.[1];
if (field("flavor") !== "alpine-minirootfs") continue;
const file = field("file");
const sha256 = field("sha256");
if (file === undefined || sha256 === undefined) continue;
return {
version: field("version") ?? "",
file,
sha256: sha256.toLowerCase(),
size: Number(field("size") ?? 0),
};
}
return null;
}
/**
* The newest ubuntu-base tarball for one architecture, out of the release directory's
* SHA256SUMS — which is both the listing and the checksum, so one fetch answers both.
*/
export function parseUbuntuSums(
sums: string,
arch: string,
): Omit<BaseRelease, "url" | "size"> | null {
const pattern = new RegExp(
`^([0-9a-f]{64}) \\*?(ubuntu-base-([0-9.]+)-base-${arch}\\.tar\\.gz)$`,
);
let best: Omit<BaseRelease, "url" | "size"> | null = null;
const order = (v: string) => v.split(".").map(Number);
for (const line of sums.split(/\r?\n/)) {
const m = pattern.exec(line.trim());
if (m === null) continue;
const candidate = { sha256: m[1]!.toLowerCase(), file: m[2]!, version: m[3]! };
if (best === null) best = candidate;
else {
const [a, b] = [order(candidate.version), order(best.version)];
for (let i = 0; i < Math.max(a.length, b.length); i++) {
if ((a[i] ?? 0) === (b[i] ?? 0)) continue;
if ((a[i] ?? 0) > (b[i] ?? 0)) best = candidate;
break;
}
}
}
return best;
}
/** Asks the chosen base where its rootfs is. Rejects with what to tell the person. */
export async function resolveRelease(
base: BaseImage,
fetchImpl: typeof fetch,
arch: string = process.arch,
): Promise<BaseRelease> {
if (base === "ubuntu") {
const dir = `${UBUNTU_IMAGES}/${UBUNTU_SERIES}/release`;
const res = await fetchImpl(`${dir}/SHA256SUMS`);
if (!res.ok)
throw new Error(`could not read Ubuntu's checksums (HTTP ${res.status} from ${dir})`);
const release = parseUbuntuSums(await res.text(), arch === "arm64" ? "arm64" : "amd64");
if (release === null)
throw new Error(`Ubuntu ${UBUNTU_SERIES} publishes no base rootfs for this architecture`);
return { ...release, url: `${dir}/${release.file}`, size: 0 };
}
const dir = `${ALPINE_MIRROR}/latest-stable/releases/${arch === "arm64" ? "aarch64" : "x86_64"}`;
const res = await fetchImpl(`${dir}/latest-releases.yaml`);
if (!res.ok)
throw new Error(`could not read Alpine's release list (HTTP ${res.status} from ${dir})`);
const release = parseMinirootfs(await res.text());
if (release === null) throw new Error("Alpine's release list names no minirootfs");
return { ...release, url: `${dir}/${release.file}` };
}
/** How a base is named on the card. */
export const BASE_TITLES: Record<BaseImage, string> = { ubuntu: "Ubuntu", alpine: "Alpine" };
/** The provisioning script, run as root inside the distro with sh reading it from stdin. */
export function provisionScript(
base: BaseImage,
mirror: string,
packages: readonly string[],
): string {
const wslConf = [
// Interop off is what makes the sandbox a sandbox: with it on, any Windows program started
// inside bwrap runs as an ordinary host process, outside every namespace (measured).
"cat > /etc/wsl.conf <<'EOF'",
"[interop]",
"enabled=false",
"appendWindowsPath=false",
"[user]",
`default=${SANDBOX_USER}`,
"EOF",
];
if (base === "ubuntu") {
const pkgs = ["bubblewrap", "ca-certificates", ...packages].filter(
(p, i, all) => all.indexOf(p) === i,
);
return [
"set -e",
...wslConf,
"export DEBIAN_FRONTEND=noninteractive",
...(mirror === ""
? []
: [
// Both archives, since a mirror that carries one carries the other.
`sed -i 's|${UBUNTU_ARCHIVE}/*|${mirror}/|; s|${UBUNTU_SECURITY}/*|${mirror}/|' /etc/apt/sources.list.d/ubuntu.sources`,
]),
'echo "apt-get update"',
"apt-get update",
`echo "apt-get install ${pkgs.join(" ")}"`,
`apt-get install -y --no-install-recommends ${pkgs.join(" ")}`,
// Recommends are off, so the account tools are named rather than assumed.
`id ${SANDBOX_USER} >/dev/null 2>&1 || useradd -m -s /bin/bash ${SANDBOX_USER}`,
"bwrap --version",
"echo PENGUIN-PROVISIONED",
"",
].join("\n");
}
const pkgs = ["bubblewrap", "bash", ...packages].filter((p, i, all) => all.indexOf(p) === i);
const repo = mirror === "" ? ALPINE_MIRROR : mirror;
return [
"set -e",
...wslConf,
"ver=$(cut -d. -f1,2 /etc/alpine-release)",
`printf '%s/v%s/main\\n%s/v%s/community\\n' '${repo}' "$ver" '${repo}' "$ver" > /etc/apk/repositories`,
'echo "apk update"',
"apk update",
`echo "apk add ${pkgs.join(" ")}"`,
`apk add --no-progress ${pkgs.join(" ")}`,
`id ${SANDBOX_USER} >/dev/null 2>&1 || adduser -D -s /bin/bash ${SANDBOX_USER}`,
"bwrap --version",
"echo PENGUIN-PROVISIONED",
"",
].join("\n");
}
export async function initialize(
settings: WslSettings,
report: (step: Text) => void,
fetchImpl: typeof fetch = fetch,
): Promise<Omit<TaskOutcome, "kind" | "at">> {
const fail = (en: string, zh: string) => ({ ok: false, message: { en, zh } });
const baseName = BASE_TITLES[settings.base];
report({ en: "checking WSL", zh: "检查 WSL" });
const host = await readHost();
if (host.wsl !== "installed") {
return fail(
`WSL does not work on this machine yet (${host.problem ?? "not installed"}): install it first.`,
`这台机器上的 WSL 还不可用(${host.problem ?? "未安装"}):请先安装。`,
);
}
const distro = settings.distro;
const previous = readState();
let version =
previous?.distro === distro && previous.base === settings.base ? previous.version : "";
const exists = host.distros.some((d) => d.toLowerCase() === distro.toLowerCase());
if (exists) {
// A distro already there is provisioned in place — with the package manager IT has, which
// is not necessarily the one the setting now names. Asking it beats running apt in an
// Alpine and reporting "apt-get: not found".
report({ en: "reading what the existing distro is", zh: "读取现有发行版的类型" });
const os = await runWsl(
[
"-d",
distro,
"-u",
"root",
"--cd",
"/",
"--exec",
"/bin/sh",
"-c",
". /etc/os-release; echo id=$ID",
],
{ timeoutMs: 60_000 },
);
const id = /id=(\w+)/.exec(os.stdout)?.[1] ?? "";
if (id !== "" && id !== settings.base) {
return fail(
`${distro} already exists and is ${BASE_TITLES[id === "alpine" ? "alpine" : "ubuntu"]}, not ${baseName}. Remove it first, or set the base Linux back to what it is.`,
`${distro} 已存在,且是 ${BASE_TITLES[id === "alpine" ? "alpine" : "ubuntu"]} 而非 ${baseName}。请先移除它,或把「基础 Linux」改回它本来的类型。`,
);
}
}
if (!exists) {
report({ en: `asking ${baseName} for its base image`, zh: `查询 ${baseName} 的基础镜像` });
let release;
try {
release = await resolveRelease(settings.base, fetchImpl);
} catch (err) {
const why = err instanceof Error ? err.message : String(err);
return fail(`${why}.`, `${why}。`);
}
version = release.version;
const rootfsDir = path.win32.join(stateDir(), "rootfs");
fs.mkdirSync(rootfsDir, { recursive: true });
const tarball = path.win32.join(rootfsDir, release.file);
const sha = (file: string) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
if (!fs.existsSync(tarball) || sha(tarball) !== release.sha256) {
const res = await fetchImpl(release.url);
if (!res.ok || res.body === null) {
return fail(
`downloading ${release.file} failed: HTTP ${res.status}`,
`下载 ${release.file} 失败:HTTP ${res.status}`,
);
}
const total = release.size || Number(res.headers.get("content-length") ?? 0);
const chunks: Buffer[] = [];
let got = 0;
for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
chunks.push(Buffer.from(chunk));
got += chunk.byteLength;
const pct = total > 0 ? ` ${Math.floor((got / total) * 100)}%` : "";
report({
en: `downloading ${baseName} ${release.version} (${(got / 1048576).toFixed(1)} MB${pct})`,
zh: `下载 ${baseName} ${release.version}(${(got / 1048576).toFixed(1)} MB${pct})`,
});
}
fs.writeFileSync(`${tarball}.part`, Buffer.concat(chunks));
fs.renameSync(`${tarball}.part`, tarball);
if (sha(tarball) !== release.sha256) {
fs.rmSync(tarball, { force: true });
return fail(
`${release.file} does not match its published sha256`,
`${release.file} 与发布的 sha256 不符`,
);
}
}
report({ en: `importing ${distro} into WSL`, zh: `导入 ${distro} 到 WSL` });
const disk = path.win32.join(stateDir(), "distros", distro);
fs.mkdirSync(disk, { recursive: true });
const imported = await runWsl(["--import", distro, disk, tarball, "--version", "2"], {
timeoutMs: 10 * 60_000,
});
if (imported.code !== 0) {
const why = imported.stdout || imported.stderr || `exit ${imported.code}`;
return fail(`wsl --import failed: ${why}`, `wsl --import 失败:${why}`);
}
}
report({
en: "installing bubblewrap and tools inside the distro",
zh: "在发行版内安装 bubblewrap 与工具",
});
let lastLine = "";
const provisioned = await runWsl(
["-d", distro, "-u", "root", "--cd", "/", "--exec", "/bin/sh", "-s"],
{
timeoutMs: 20 * 60_000,
input: provisionScript(settings.base, settings.mirror, settings.packages),
onLine: (line) => {
lastLine = line.trim();
report({ en: `inside the distro: ${lastLine}`, zh: `发行版内:${lastLine}` });
},
},
);
if (provisioned.code !== 0 || !provisioned.stdout.includes("PENGUIN-PROVISIONED")) {
const why = provisioned.stderr || lastLine || `exit ${provisioned.code}`;
return fail(
`provisioning ${distro} failed: ${why}. If packages could not be downloaded, set a reachable mirror.`,
`配置 ${distro} 失败:${why}。如果是软件包下载失败,请设置一个可访问的镜像。`,
);
}
report({
en: "restarting the distro so interop stays off",
zh: "重启发行版,使 interop 关闭生效",
});
await runWsl(["--terminate", distro], { timeoutMs: 60_000 });
const state: WslState = {
distro,
user: SANDBOX_USER,
base: settings.base,
version,
packages: settings.packages,
initializedAt: new Date().toISOString(),
};
writeState(state);
return {
ok: true,
message: {
en: `The sandbox distro ${distro} (${baseName} ${version}) is ready: agent commands now run inside it under bubblewrap. Run the check to see what it confines.`,
zh: `沙盒发行版 ${distro}(${baseName} ${version})已就绪:Agent 的命令现在在其中通过 bubblewrap 执行。运行检查可查看隔离效果。`,
},
};
}
// ---------------------------------------------------------------------------------------------
// Check — runs real commands through the same profile the provider builds.
// ---------------------------------------------------------------------------------------------
export async function check(
settings: WslSettings,
report: (step: Text) => void,
): Promise<{ result: Omit<TaskOutcome, "kind" | "at">; lines: CheckLine[] }> {
const state = readState();
if (state === null) {
const text = { en: "The sandbox distro is not initialized yet.", zh: "沙盒发行版尚未初始化。" };
return { result: { ok: false, message: text }, lines: [] };
}
const root = path.win32.join(stateDir(), "check");
const ws = path.win32.join(root, "workspace");
const outside = path.win32.join(root, "outside");
const masked = path.win32.join(ws, "masked");
fs.rmSync(root, { recursive: true, force: true });
fs.mkdirSync(masked, { recursive: true });
fs.mkdirSync(outside, { recursive: true });
fs.writeFileSync(path.win32.join(masked, "token.txt"), "secret\n");
const lx = (p: string) => toLinuxPath(p, state.distro) ?? p;
const lines: CheckLine[] = [];
const confined = async (policy: SandboxPolicy, script: string) => {
const job = launchJob(["bash", "-c", script], policy, settings, state);
return runWsl(wslArgs(job, ws), { timeoutMs: 60_000 });
};
const base: SandboxPolicy = { mode: "workspace-write", workspaceRoot: ws, writableTemp: true };
const add = (en: string, zh: string, ok: boolean | null, detail: string) => {
lines.push({ name: { en, zh }, ok, detail });
};
report({ en: "Windows interop is off", zh: "Windows interop 已关闭" });
const interop = await runWsl(
[
"-d",
state.distro,
"-u",
"root",
"--cd",
"/",
"--exec",
"/bin/sh",
"-c",
"/mnt/c/Windows/System32/cmd.exe /c exit 0 >/dev/null 2>&1; echo rc=$?",
],
{ timeoutMs: 60_000 },
);
add(
"A Windows program cannot start from the distro",
"发行版内无法启动 Windows 程序",
!/rc=0\b/.test(interop.stdout),
interop.stdout || interop.stderr,
);
report({ en: "the sandbox runs", zh: "沙盒可以运行" });
const alive = await confined(base, "uname -sr; id -un");
add(
"bubblewrap starts a confined command",
"bubblewrap 能启动被隔离的命令",
alive.code === 0,
alive.stdout || alive.stderr,
);
report({ en: "Node is in the distro", zh: "发行版里有 Node" });
const node = await confined(base, "node --version");
add(
"Node runs hook scripts and the file tools' helper",
"Node 能运行钩子脚本与文件工具的助手",
node.code === 0,
node.code === 0
? node.stdout.trim()
: "nodejs is not installed: hook scripts and the file tools fail under this sandbox until the distro is initialized again with it.",
);
report({ en: "writing the Workspace", zh: "写工作区" });
await confined(base, "echo ok > probe.txt");
const wrote = fs.existsSync(path.win32.join(ws, "probe.txt"));
add(
"workspace-write: the Workspace is writable",
"workspace-write:工作区可写",
wrote,
wrote ? "probe.txt written" : "no file appeared on Windows",
);
report({ en: "writing outside the Workspace", zh: "写工作区外" });
// The command must FAIL, not merely leave Windows untouched: a write that lands in the
// covering tmpfs reports success and disappears with the command, which reads to an agent
// as permission it does not have.
const out = await confined(base, `echo x > '${lx(outside)}/probe.txt' && echo WROTE`);
const escaped = fs.existsSync(path.win32.join(outside, "probe.txt"));
add(
"workspace-write: a write outside the Workspace is refused, not silently lost",
"workspace-write:工作区外的写入被拒绝,而不是悄悄丢失",
!escaped && !out.stdout.includes("WROTE"),
out.stderr || out.stdout || "the write reported success",
);
report({ en: "writing where the drives are covered", zh: "写被遮盖的磁盘路径" });
const covered = await confined(base, "echo x > /mnt/c/Users/penguin-probe.txt && echo WROTE");
add(
"the mount that hides the drives refuses writes too",
"遮盖磁盘的挂载同样拒绝写入",
!covered.stdout.includes("WROTE"),
covered.stderr || covered.stdout || "the write reported success",
);
report({ en: "read-only mode", zh: "只读模式" });
const ro = await confined({ ...base, mode: "read-only" }, "echo x > ro.txt");
const roWrote = fs.existsSync(path.win32.join(ws, "ro.txt"));
add(
"read-only: the Workspace is not writable",
"read-only:工作区不可写",
!roWrote,
ro.stderr || ro.stdout,
);
report({ en: "the Windows drives", zh: "Windows 磁盘" });
const drive = await confined(base, "test -e /mnt/c/Windows && echo visible || echo hidden");
const visible = drive.stdout.includes("visible");
add(
settings.exposeWindowsDrives
? "Windows drives are visible read-only (setting on)"
: "Windows drives outside the Workspace are hidden (setting off)",
settings.exposeWindowsDrives
? "Windows 磁盘以只读方式可见(设置已开)"
: "工作区以外的 Windows 磁盘不可见(设置已关)",
visible === settings.exposeWindowsDrives,
drive.stdout || drive.stderr,
);
report({ en: "the network", zh: "网络" });
// A name rather than a literal address: a machine behind a proxy that rewrites addresses
// refuses a connection to 1.1.1.1 while the network it actually uses works.
const netProbe =
"timeout 8 bash -c 'exec 3<>/dev/tcp/example.com/443' && echo connected || echo blocked";
// Resolution is its own question: covering /mnt and /run took away the file
// /etc/resolv.conf points at, so names failed while addresses still worked.
const dnsProbe = "getent hosts example.com >/dev/null && echo resolved || echo unresolved";
const none = await confined({ ...base, network: "none" }, netProbe);
add(
"network none: no connection",
"network none:无法连接",
none.stdout.includes("blocked"),
none.stdout || none.stderr,
);
const open = await confined(base, netProbe);
add(
"network allowed: connects (information)",
"允许网络:可以连接(仅供参考)",
open.stdout.includes("connected") ? true : null,
open.stdout || open.stderr,
);
const dns = await confined(base, dnsProbe);
add(
"network allowed: a host name resolves",
"允许网络:域名可以解析",
dns.stdout.includes("resolved") ? true : open.stdout.includes("connected") ? false : null,
dns.stdout || dns.stderr,
);
report({ en: "a masked path", zh: "屏蔽路径" });
const mask = await confined(
{ ...base, maskPaths: [masked] },
`cat '${lx(masked)}/token.txt' 2>&1 || true`,
);
add(
"mask-paths: a masked file cannot be read",
"mask-paths:被屏蔽的文件不可读",
!mask.stdout.includes("secret"),
mask.stdout || mask.stderr,
);
report({ en: "writable temp", zh: "可写临时目录" });
const tmp = await confined(base, "echo x > /tmp/probe && echo ok");
add(
"the temp directory is writable",
"临时目录可写",
tmp.stdout.includes("ok"),
tmp.stdout || tmp.stderr,
);
fs.rmSync(root, { recursive: true, force: true });
const failed = lines.filter((l) => l.ok === false);
return {
lines,
result:
failed.length === 0
? {
ok: true,
message: {
en: `All ${lines.length} checks passed.`,
zh: `全部 ${lines.length} 项检查通过。`,
},
}
: {
ok: false,
message: {
en: `${failed.length} of ${lines.length} checks failed: ${failed.map((l) => l.name.en).join("; ")}`,
zh: `${lines.length} 项检查中有 ${failed.length} 项失败:${failed.map((l) => l.name.zh).join(";")}`,
},
},
};
}
export async function remove(
settings: WslSettings,
report: (step: Text) => void,
): Promise<Omit<TaskOutcome, "kind" | "at">> {
const distro = readState()?.distro ?? settings.distro;
report({ en: `wsl --unregister ${distro}`, zh: `wsl --unregister ${distro}` });
const res = await runWsl(["--unregister", distro], { timeoutMs: 5 * 60_000 });
removeState();
fs.rmSync(path.win32.join(stateDir(), "distros", distro), { recursive: true, force: true });
if (
res.code !== 0 &&
!/WSL_E_DISTRO_NOT_FOUND|no distribution/i.test(`${res.stdout}${res.stderr}`)
) {
const why = res.stdout || res.stderr;
return {
ok: false,
message: { en: `wsl --unregister failed: ${why}`, zh: `wsl --unregister 失败:${why}` },
};
}
return {
ok: true,
message: {
en: `${distro} is removed with everything inside it. The sandbox backend stays off until you initialize again.`,
zh: `${distro} 及其中所有内容已移除。在重新初始化之前,沙盒后端保持停用。`,
},
};
}