A desktop coding agent with free access to frontier models.
TypeScript
feat: ranked sandbox backends per os
ogsamratb4c01fc61438
diff --git a/apps/server/src/box/backends/apple.ts b/apps/server/src/box/backends/apple.tsnew file mode 100644index 00000000..f9971ad2--- /dev/null+++ b/apps/server/src/box/backends/apple.ts@@ -0,0 +1,313 @@+// Ported from the CLI (omnirush-cli src/box/backends/apple.js,+// feat/local-box-backends); keep the two in step. Desktop differences: types;+// the container-name prefix (containerName's env); boxd missing from the+// sidecars is a reason.+//+// Apple's `container` (github.com/apple/container) as a box backend: macOS 26++// on Apple silicon, each container its own lightweight VM, no Docker. One+// persistent container per project, made with `container create`, the+// project and the run folder shared in at their paths (virtiofs), boxd+// started as the entrypoint from the run folder and published on this+// machine's loopback at a port chosen here (`-p` needs one named), with the+// container's own address as the second way in. Snapshots are boxd's index+// walk (there is no `container diff`).+//+// Written to the CLI of the 1.x line (1.0.0 froze the CLI; checked against+// docs/command-reference.md and the Swift sources of 1.5.0, Sep 2026):+// container system version --format json [{appName, version, buildType, commit}]+// container system status exit 0 while the API server runs+// container create|start|delete --force|inspect|list --all --format json+// container image pull --platform linux/arm64 | image inspect | image list --format json | image delete+// create: --name --label k=v --mount type=bind,source=,target=[,readonly] -p ip:host:container+// -e K=V --workdir --cpus --memory --init --entrypoint+// list/inspect JSON: { configuration: { id, image: { reference, descriptor: { digest } },+// labels, publishedPorts }, status: running|stopped|stopping|unknown,+// networks: [{ ipv4Address: "192.168.64.3/24" }] }++import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";+import os from "node:os";+import path from "node:path";++import { BOX_PORT, HOME_IN_BOX, LABEL, RUN_DIR, SHIMS_DIR, containerName, containerRoot, firstLine, freePort, helperPath, newToken, type BoxInstallLog, type BoxRuntime } from "../common.js";+import { runCommand, type RunCommand } from "../run.js";+import type { RuntimeResult } from "../runtime.js";+import { versionAtLeast } from "./shared.js";+import type { BoxDriver, OpenContext, Opened, PresentImage } from "./types.js";++type Env = NodeJS.ProcessEnv;++/** The `container` releases this backend is written for: 1.x (the CLI is frozen within it). */+export const SUPPORTED = { min: "1.0.0", below: "2.0.0", tested: "1.5.0" };++const BIN_DIRS = ["/usr/local/bin", "/opt/homebrew/bin"];++export function findAppleBin({ env = process.env, exists = existsSync }: { env?: Env; exists?: (file: string) => boolean } = {}): string | null {+ const asked = String(env.OMNIRUSH_BOX_APPLE_BIN || "").trim();+ if (asked) return exists(asked) ? asked : null;+ const dirs = [...String(env.PATH || "").split(":").filter(Boolean), ...BIN_DIRS];+ for (const dir of dirs) {+ const file = path.posix.join(dir, "container");+ if (exists(file)) return file;+ }+ return null;+}++/** macOS major version from the Darwin kernel release (Darwin 25 = macOS 26). */+export function macosMajor(release = os.release()): number | null {+ const darwin = Number.parseInt(String(release).split(".")[0] ?? "", 10);+ return Number.isFinite(darwin) && darwin >= 20 ? darwin + 1 : null;+}++function record(value: unknown): Record<string, unknown> {+ return value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : {};+}++/** Versions from `container system version --format json` (or `--version` text). */+export function parseVersions(stdout: unknown): { version: string; server?: string | null } {+ const text = String(stdout ?? "").trim();+ try {+ const list: unknown = JSON.parse(text);+ if (Array.isArray(list)) {+ const entries = list.map(record);+ const cli = entries.find((entry) => /^container$|cli/i.test(String(entry.appName ?? ""))) ?? entries[0];+ const server = entries.find((entry) => /apiserver/i.test(String(entry.appName ?? "")));+ return { version: String(cli?.version ?? ""), server: server ? String(server.version ?? "") : null };+ }+ } catch { /* text */ }+ const match = /(\d+\.\d+\.\d+)/.exec(text);+ return { version: match ? match[1]! : "" };+}++export async function probeApple({ env = process.env, platform = process.platform, arch = process.arch, release = os.release(), run = runCommand, exists = existsSync, timeoutMs = 6_000 }: { env?: Env; platform?: NodeJS.Platform; arch?: string; release?: string; run?: RunCommand; exists?: (file: string) => boolean; timeoutMs?: number } = {}): Promise<RuntimeResult> {+ const base = { name: "apple", backend: "apple" };+ if (platform !== "darwin") return { ...base, ok: false, reason: "Apple container is macOS only" };+ if (arch !== "arm64") return { ...base, ok: false, reason: "Apple container needs an Apple silicon Mac" };+ const major = macosMajor(release);+ if (major !== null && major < 26) return { ...base, ok: false, reason: `Apple container needs macOS 26 or later (this is macOS ${major})` };+ const bin = findAppleBin({ env, exists });+ if (!bin) return { ...base, ok: false, reason: "Apple container is not installed (github.com/apple/container releases)" };+ let res = await run(bin, ["system", "version", "--format", "json"], { env, timeoutMs });+ let versions = res.code === 0 ? parseVersions(res.stdout) : { version: "" };+ if (!versions.version) {+ res = await run(bin, ["--version"], { env, timeoutMs });+ versions = parseVersions(res.stdout);+ }+ const { version } = versions;+ if (!version) return { ...base, ok: false, bin, reason: `could not read Apple container's version: ${firstLine(res.stderr) || res.code}` };+ if (!versionAtLeast(version, SUPPORTED.min) || versionAtLeast(version, SUPPORTED.below)) {+ return { ...base, ok: false, bin, version, reason: `Apple container ${version} is outside the supported ${SUPPORTED.min.split(".")[0]}.x line (tested with ${SUPPORTED.tested})` };+ }+ const status = await run(bin, ["system", "status"], { env, timeoutMs });+ const said = `${status.stdout}\n${status.stderr}`;+ if (status.code !== 0 || /not running|not registered|unavailable/i.test(said) || versions.server === null) {+ return { ...base, ok: false, bin, version, reason: "Apple container is installed but not started (run `container system start` once)" };+ }+ return { ...base, ok: true, bin, version, os: "linux", arch: "arm64", flavor: "apple-container", rootless: true, vm: true };+}++const DIGEST = /^sha256:[0-9a-f]{64}$/;++/** The first sha256 digest of an image record (index, descriptor, then anywhere). */+export function findDigest(value: unknown): string | null {+ const ok = (d: unknown): d is string => typeof d === "string" && DIGEST.test(d);+ const rec = record(Array.isArray(value) ? value[0] : value);+ const configuration = record(rec.configuration);+ for (const cand of [record(rec.index).digest, record(rec.descriptor).digest, record(record(configuration.image).descriptor).digest, rec.digest]) if (ok(cand)) return cand;+ let found: string | null = null;+ const walk = (v: unknown) => {+ if (found || v === null || typeof v !== "object") return;+ for (const [k, x] of Object.entries(v)) {+ if (k === "digest" && ok(x)) { found = x; return; }+ walk(x);+ }+ };+ walk(rec);+ return found;+}++function parseJson(text: unknown): unknown {+ try { return JSON.parse(String(text ?? "").trim()); } catch { return null; }+}++export type AppleBoxInfo = { id: string; running: boolean; status: string; image: string; digest: string | null; labels: Record<string, string>; address: string | null; created: string | null };++export function snapshotInfo(snap: unknown): AppleBoxInfo {+ const s = record(snap);+ const cfg = record(s.configuration);+ const image = record(cfg.image);+ const networks = Array.isArray(s.networks) ? s.networks.map(record) : [];+ const address = networks.map((n) => String(n.ipv4Address ?? n.address ?? "").split("/")[0]).find(Boolean) ?? null;+ const labels = Object.fromEntries(Object.entries(record(cfg.labels)).map(([k, v]) => [k, String(v)]));+ const digest = record(image.descriptor).digest;+ return {+ id: String(cfg.id ?? ""),+ running: String(s.status ?? "") === "running",+ status: String(s.status ?? ""),+ image: String(image.reference ?? ""),+ digest: typeof digest === "string" ? digest : null,+ labels,+ address,+ created: typeof cfg.creationDate === "string" || typeof cfg.creationDate === "number" ? String(cfg.creationDate) : null,+ };+}++async function inspectBox(runtime: BoxRuntime, name: string, run: RunCommand): Promise<AppleBoxInfo | null> {+ const res = await run(runtime.bin, ["inspect", name], { timeoutMs: 20_000 });+ if (res.code !== 0) return null;+ const parsed = parseJson(res.stdout);+ const snap = Array.isArray(parsed) ? parsed[0] : parsed;+ if (!record(snap).configuration) return null;+ return snapshotInfo(snap);+}++/** VM size for a box: what the user asked, else half the Mac (2–8 CPUs, 2–8 GiB; Apple's default 1 GiB is too small for installs). */+export function appleResources({ env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { env?: Env; cpus?: number; memory?: number } = {}): string[] {+ const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);+ const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();+ const c = askedCpus > 0 ? askedCpus : Math.max(2, Math.min(8, Math.floor(cpus / 2)));+ const m = askedMem || `${Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)))}G`;+ return ["--cpus", String(c), "--memory", m];+}++export function createAppleArgs({ name, key, root, croot, image, runFolder, shims = null, pkglog = null, token, port, env = process.env }: { name: string; key: string; root: string; croot: string; image: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; port: number; env?: Env }): string[] {+ return [+ "create", "--name", name,+ "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`, "--label", `${LABEL}.port=${port}`,+ "--mount", `type=bind,source=${root},target=${croot}`,+ "--mount", `type=bind,source=${runFolder},target=${RUN_DIR}`,+ "--mount", `type=bind,source=${path.join(runFolder, "bin")},target=/opt/omnirush/bin,readonly`,+ ...(shims ? ["--mount", `type=bind,source=${shims},target=${SHIMS_DIR}-src,readonly`] : []),+ ...(pkglog ? ["--mount", `type=bind,source=${pkglog.root},target=${containerRoot(pkglog.root, "darwin")}`] : []),+ "-p", `127.0.0.1:${port}:${BOX_PORT}`,+ "-e", `BOXD_TOKEN=${token}`, "-e", "BOXD_UID=0", "-e", "BOXD_GID=0", "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,+ "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",+ "--workdir", croot,+ ...appleResources({ env }),+ "--init",+ "--entrypoint", "/opt/omnirush/bin/boxd",+ image,+ ];+}++/** Copy boxd into the run folder's bin/ (mounted read-only at /opt/omnirush/bin). */+function placeBoxd(runFolder: string, env: Env): string | null {+ const source = helperPath("boxd", { goos: "linux", goarch: "arm64", env });+ if (!source) return "the sandbox helper boxd (linux-arm64) is missing from this install";+ const dir = path.join(runFolder, "bin");+ mkdirSync(dir, { recursive: true });+ const target = path.join(dir, "boxd");+ let same = false;+ try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }+ if (!same) {+ copyFileSync(source, `${target}.tmp`);+ chmodSync(`${target}.tmp`, 0o755);+ copyFileSync(`${target}.tmp`, target);+ chmodSync(target, 0o755);+ }+ return null;+}++async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<PresentImage | null> {+ const res = await run(runtime.bin, ["image", "inspect", image.pull], { timeoutMs: 20_000 });+ if (res.code !== 0) return null;+ const parsed = parseJson(res.stdout);+ if (!parsed || (Array.isArray(parsed) && parsed.length === 0)) return null;+ const digest = findDigest(parsed);+ return { id: digest || image.pull, digest, arch: "arm64" };+}++async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ ok: true } | { ok: false; error: string }> {+ const res = await run(runtime.bin, ["image", "pull", "--platform", "linux/arm64", image.pull], { timeoutMs: 60 * 60_000 });+ return res.code === 0 ? { ok: true } : { ok: false, error: firstLine(res.stderr) || `image pull exited ${res.code}` };+}++async function open(ctx: OpenContext): Promise<Opened> {+ const { key, name, root, croot, runtime, run, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling } = ctx;+ let info = await inspectBox(runtime, name, run);+ if (info && info.labels[`${LABEL}.root`] && info.labels[`${LABEL}.root`] !== root) return { ok: false, error: `container ${name} belongs to another folder` };+ const placed = placeBoxd(runFolder, env);+ if (placed) return { ok: false, error: placed };+ const tokenFile = path.join(runFolder, "box-token");+ let created = null;+ if (!info) {+ let present = await imagePresent(runtime, image, { run });+ if (!present) {+ if (!mayPull) return { ok: false, error: "the sandbox image is not downloaded yet" };+ onPulling();+ const pulled = await pull(runtime, image, { run });+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };+ present = await imagePresent(runtime, image, { run });+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };+ }+ const token = newToken();+ writeFileSync(tokenFile, token, { mode: 0o600 });+ const port = await freePort();+ const made = await run(runtime.bin, createAppleArgs({ name, key, root, croot, image: image.pull, runFolder, shims, pkglog, token, port, env }), { timeoutMs: 120_000 });+ if (made.code !== 0) return { ok: false, error: `could not create the sandbox: ${firstLine(made.stderr)}` };+ created = { ref: image.ref, pull: image.pull, digest: image.digest || present.digest, id: present.id, stack: image.stack };+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "apple" });+ info = await inspectBox(runtime, name, run);+ if (!info) return { ok: false, error: "the sandbox was created but cannot be inspected" };+ }+ if (!info.running) {+ const started = await run(runtime.bin, ["start", name], { timeoutMs: 120_000 });+ if (started.code !== 0) return { ok: false, error: `could not start the sandbox: ${firstLine(started.stderr)}` };+ info = (await inspectBox(runtime, name, run)) ?? info;+ }+ let token = "";+ try { token = readFileSync(tokenFile, "utf8").trim(); } catch { /* none */ }+ const port = Number(info.labels[`${LABEL}.port`]) || 0;+ if (!token || !port) return { ok: false, error: "the sandbox has no port or token (Reset sandbox makes a new one)" };+ const alternates = info.address ? [{ host: info.address, port: BOX_PORT, token }] : [];+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token }, alternates, uid: 0, gid: 0, containerId: info.id || name, imageId: info.digest || info.image, mounts: [croot, RUN_DIR, ...(shims ? [`${SHIMS_DIR}-src`] : []), ...(pkglog ? [containerRoot(pkglog.root, "darwin")] : [])] };+}++export const appleDriver: BoxDriver = {+ kind: "apple",+ execFallback: false,+ imagePresent,+ pull,+ pullCommand(runtime, image) {+ return { bin: runtime.bin, args: ["image", "pull", "--platform", "linux/arm64", image.pull] };+ },+ async exists(runtime, key, { run = runCommand, env = process.env } = {}) {+ return Boolean(await inspectBox(runtime, containerName(key, env), run));+ },+ open,+ async list(runtime, { run = runCommand } = {}) {+ const res = await run(runtime.bin, ["list", "--all", "--format", "json"], { timeoutMs: 30_000 });+ if (res.code !== 0) return [];+ const parsed = parseJson(res.stdout);+ if (!Array.isArray(parsed)) return [];+ return parsed.map(snapshotInfo).filter((info) => info.labels[LABEL] === "1").map((info) => ({ key: info.labels[`${LABEL}.key`] ?? "", name: info.id, root: info.labels[`${LABEL}.root`] ?? "", running: info.running, image: info.image, created: String(info.created ?? "") }));+ },+ async remove(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await run(runtime.bin, ["delete", "--force", containerName(key, env)], { timeoutMs: 60_000 });+ return { removed: res.code === 0 };+ },+ async gcImages(runtime, { run = runCommand, current, used }) {+ const removed = [];+ const res = await run(runtime.bin, ["image", "list", "--format", "json"], { timeoutMs: 30_000 });+ const parsed = parseJson(res.stdout);+ for (const entry of Array.isArray(parsed) ? parsed.map(record) : []) {+ const ref = String(entry.reference ?? entry.name ?? "");+ if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref)) continue;+ const del = await run(runtime.bin, ["image", "delete", ref], { timeoutMs: 60_000 });+ if (del.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });+ }+ return removed;+ },+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await run(runtime.bin, ["stop", containerName(key, env)], { timeoutMs: 60_000 });+ return { stopped: res.code === 0 };+ },+ async upperBytes() {+ return null;+ },+ shellCommand(runtime, { key, croot, env = process.env }) {+ return { bin: runtime.bin, args: ["exec", "--interactive", "--tty", "--workdir", croot, containerName(key, env), "/bin/bash", "-l"] };+ },+ execCommand(runtime, { key, env = process.env }) {+ return { bin: runtime.bin, args: ["exec", "--interactive", containerName(key, env)], env: {} };+ },+};diff --git a/apps/server/src/box/backends/bwrap.ts b/apps/server/src/box/backends/bwrap.tsnew file mode 100644index 00000000..3bec757b--- /dev/null+++ b/apps/server/src/box/backends/bwrap.ts@@ -0,0 +1,281 @@+// Ported from the CLI (omnirush-cli src/box/backends/bwrap.js,+// feat/local-box-backends); keep the two in step. Desktop differences: types;+// the one-time admin step (`sudo omnirush sandbox enable`) is the CLI's, so+// the AppArmor reason names the CLI; boxrun missing from the sidecars is a+// reason, not a path.+//+// The bubblewrap backend (Linux; also what runs inside the OmniRush WSL+// distro): no daemon, no root, nothing to install where unprivileged user+// namespaces work. `boxrun` (box/go/cmd/boxrun) pulls the pinned image and+// unpacks it (~/.omnirush/box/bwrap/store), and runs each project's box as+// that root filesystem under a per-project overlay upper layer+// (~/.omnirush/box/bwrap/boxes/<key>), in its own user, mount, PID, IPC and+// UTS namespaces, on the host's network. The upper layer stays on disk, so+// installs survive restarts; boxd is the same helper the containers run.+//+// Ubuntu 23.10+ blocks unprivileged user namespaces through AppArmor+// (kernel.apparmor_restrict_unprivileged_userns=1): the probe says so in one+// line and the next backend (rootless Podman, Docker) is used.++import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";+import os from "node:os";+import path from "node:path";++import { GOARCH, RUN_DIR, SHIMS_DIR, containerName, containerRoot, helperPath, newToken, readJson, writeJson, type BoxInstallLog, type BoxRuntime } from "../common.js";+import { runCommand, type RunCommand } from "../run.js";+import type { RuntimeResult } from "../runtime.js";+import { boxshExec, num, parseOut, str } from "./shared.js";+import type { BoxDriver, ListedBox, OpenContext, Opened, PresentImage, Removed } from "./types.js";++export { parseOut } from "./shared.js";++type Env = NodeJS.ProcessEnv;++/** Where `sudo omnirush sandbox enable` (the CLI) puts OmniRush's bwrap (root-owned, profiled). */+export const ENABLED_BWRAP = "/usr/local/lib/omnirush/bwrap";+export const APPARMOR_PROFILE = "/etc/apparmor.d/omnirush-bwrap";+/** boxd exits (and the box with it) after this long with no request. */+export const IDLE_MINUTES = 120;++export function bwrapHome(home: string): string {+ return path.join(home, "bwrap");+}+const storeDir = (home: string) => path.join(bwrapHome(home), "store");+const boxDir = (home: string, key: string) => path.join(bwrapHome(home), "boxes", key);+const metaFile = (home: string, key: string) => path.join(bwrapHome(home), "boxes", `${key}.json`);++/** A box's own record (boxes/<key>.json under the backend's folder). */+export type BoxMeta = {+ v: 1; key: string; root: string; croot: string; image: string; arch: string; ref: string; pull: string; digest: string | null;+ config?: string; stack: string; token: string; instance: string; created_at: string; mounts?: string[];+};++/** boxrun for this machine's architecture (inside a box: linux/<arch>); null when this install has none. */+export function boxrunPath({ env = process.env, arch = process.arch }: { env?: Env; arch?: string } = {}): string | null {+ return helperPath("boxrun", { goos: "linux", goarch: GOARCH[arch] || "amd64", env });+}++/**+ * The bwrap to use, best first: OMNIRUSH_BOX_BWRAP, the profiled copy+ * `sandbox enable` installed, the one shipped with OmniRush (static, for+ * systems without bubblewrap). Null: boxrun looks for the system's.+ */+export function bwrapPath({ env = process.env, arch = process.arch, exists = existsSync }: { env?: Env; arch?: string; exists?: (file: string) => boolean } = {}): string | null {+ const asked = String(env.OMNIRUSH_BOX_BWRAP || "").trim();+ if (asked) return asked;+ if (exists(ENABLED_BWRAP)) return ENABLED_BWRAP;+ const shipped = helperPath("bwrap", { goos: "linux", goarch: GOARCH[arch] || "amd64", env });+ return shipped && exists(shipped) ? shipped : null;+}++/** One line for each reason boxrun's probe gives. */+export function explainProbe(out: Record<string, unknown> | null): string {+ const reason = str(out?.reason) || "bubblewrap could not start";+ switch (out?.code) {+ case "apparmor":+ return `${reason}; one-time admin fix: \`sudo omnirush sandbox enable\` (OmniRush CLI)`;+ case "no_bwrap":+ return `${reason} (\`sudo apt install bubblewrap\` or your system's package)`;+ case "userns_off":+ return `${reason}; an admin can allow them, or use Podman or Docker`;+ default:+ return reason;+ }+}++/** Can boxes run here with bubblewrap? A real start (5–20 ms), never a guess from the distro. */+export async function probeBwrap({ env = process.env, boxHome, run = runCommand, timeoutMs = 6_000, arch = process.arch, exists = existsSync, platform = process.platform }: { env?: Env; boxHome: string; run?: RunCommand; timeoutMs?: number; arch?: string; exists?: (file: string) => boolean; platform?: NodeJS.Platform }): Promise<RuntimeResult> {+ const base = { name: "bwrap", backend: "bwrap" };+ if (platform !== "linux") return { ...base, ok: false, reason: "bubblewrap is Linux only" };+ const bin = boxrunPath({ env, arch });+ if (!bin || !exists(bin)) return { ...base, ok: false, ...(bin ? { bin } : {}), reason: "the sandbox helper boxrun is missing from this install" };+ try { mkdirSync(boxHome, { recursive: true }); } catch { /* the probe says */ }+ const args = ["probe", "--dir", boxHome];+ const bw = bwrapPath({ env, arch, exists });+ if (bw) args.push("--bwrap", bw);+ const res = await run(bin, args, { env: { PATH: env.PATH || "/usr/bin:/bin", USER: env.USER || "" }, timeoutMs });+ const out = parseOut(res.stdout);+ if (!out) return { ...base, ok: false, bin, reason: res.error === "timeout" ? "the bubblewrap probe did not answer in time" : `boxrun probe failed: ${String(res.stderr || "").trim().slice(0, 200)}` };+ if (!out.ok) return { ...base, ok: false, bin, code: str(out.code), reason: explainProbe(out) };+ return {+ ...base, ok: true, bin, bwrap: str(out.bwrap) || bw || null,+ version: str(out.bwrap_version),+ os: "linux", arch: GOARCH[arch] || arch,+ flavor: out.overlay === "fuse" ? "fuse-overlayfs" : "overlayfs",+ idmap: str(out.idmap) || "single", launcher: str(out.launcher) || "bwrap",+ rootless: !out.root, vm: false, kernel: str(out.kernel) || os.release(),+ };+}++function storeArgs(home: string): string[] {+ return ["--store", storeDir(home)];+}++function presentOf(out: Record<string, unknown> | null): PresentImage | null {+ if (!out?.present) return null;+ return { id: str(out.id), digest: str(out.digest) || null, arch: str(out.arch), config: str(out.config) };+}++async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, home = "" }: { run?: RunCommand; home?: string } = {}): Promise<PresentImage | null> {+ const res = await run(runtime.bin, ["image", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"], { timeoutMs: 15_000 });+ return presentOf(parseOut(res.stdout));+}++async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, home = "" }: { run?: RunCommand; home?: string } = {}): Promise<{ ok: true } | { ok: false; error: string }> {+ const res = await run(runtime.bin, ["pull", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"], { timeoutMs: 60 * 60_000 });+ const out = parseOut(res.stdout);+ return out?.ok ? { ok: true } : { ok: false, error: String(out?.error || res.stderr || `boxrun pull exited ${res.code}`).slice(0, 300) };+}++/** boxd's environment in a box (what `docker create -e` gives the containers). */+export function boxdEnv({ token, croot, idleMinutes = IDLE_MINUTES, listen = "127.0.0.1:0" }: { token: string; croot: string; idleMinutes?: number; listen?: string }): string[] {+ return [+ `BOXD_TOKEN=${token}`, "BOXD_UID=0", "BOXD_GID=0", "BOXD_HOME=/root", `BOXD_ROOT=${croot}`,+ `BOXD_ENV_FILE=${RUN_DIR}/env`, `BOXD_LISTEN=${listen}`, `BOXD_PORT_FILE=${RUN_DIR}/boxd.port`, `BOXD_IDLE_EXIT=${idleMinutes}`,+ "LANG=C.UTF-8", "DEBIAN_FRONTEND=noninteractive",+ ];+}++/** `boxrun up` arguments for a project's box. */+export function upArgs({ box, store, image, boxd, portFile, root, croot, runFolder, shims = null, pkglog = null, token, bwrap = null, idleMinutes = IDLE_MINUTES, listen, platform = "linux", mapPath = (p: string) => p }: { box: string; store: string; image: string; boxd: string; portFile: string; root: string; croot: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; bwrap?: string | null; idleMinutes?: number; listen?: string; platform?: NodeJS.Platform; mapPath?: (p: string) => string }): string[] {+ const args = ["up", "--box", box, "--store", store, "--image", image, "--boxd", boxd, "--port-file", portFile,+ "--bind", `${mapPath(root)}=${croot}`, "--bind", `${mapPath(runFolder)}=${RUN_DIR}`];+ if (shims) args.push("--ro-bind", `${mapPath(shims)}=${SHIMS_DIR}-src`);+ if (pkglog) args.push("--bind", `${mapPath(pkglog.root)}=${containerRoot(pkglog.root, platform)}`);+ for (const kv of boxdEnv({ token, croot, idleMinutes, ...(listen ? { listen } : {}) })) args.push("--env", kv);+ if (bwrap) args.push("--bwrap", bwrap);+ return args;+}++/** A new box's own record. */+export function newMeta({ key, root, croot, present, image }: { key: string; root: string; croot: string; present: PresentImage; image: { ref: string; pull: string; digest: string | null; stack: string } }): BoxMeta {+ return { v: 1, key, root, croot, image: present.id, arch: present.arch, ref: image.ref, pull: image.pull, digest: image.digest || present.digest, ...(present.config ? { config: present.config } : {}), stack: image.stack, token: newToken(), instance: newToken().slice(0, 12), created_at: new Date().toISOString() };+}++async function open(ctx: OpenContext): Promise<Opened> {+ const { key, root, croot, runtime, run, home, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling } = ctx;+ const file = metaFile(home, key);+ let meta = readJson<BoxMeta>(file);+ if (meta && meta.root !== root) return { ok: false, error: `box ${key} belongs to another folder` };+ let created = null;+ if (!meta || !existsSync(boxDir(home, key))) {+ let present = await imagePresent(runtime, image, { run, home });+ if (!present) {+ if (!mayPull) return { ok: false, error: "the sandbox image is not downloaded yet" };+ onPulling();+ const pulled = await pull(runtime, image, { run, home });+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };+ present = await imagePresent(runtime, image, { run, home });+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };+ }+ meta = newMeta({ key, root, croot, present, image });+ mkdirSync(path.dirname(file), { recursive: true });+ writeJson(file, meta);+ created = { ref: image.ref, pull: image.pull, digest: meta.digest, id: present.config || present.id, stack: image.stack };+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "bwrap" });+ }+ const boxd = helperPath("boxd", { goos: "linux", goarch: GOARCH[meta.arch] || runtime.arch || "amd64", env });+ if (!boxd) return { ok: false, error: "the sandbox helper boxd is missing from this install" };+ const portFile = path.join(runFolder, "boxd.port");+ const idle = Number(env.OMNIRUSH_BOX_IDLE_MIN) > 0 ? Number(env.OMNIRUSH_BOX_IDLE_MIN) : IDLE_MINUTES;+ const args = upArgs({ box: boxDir(home, key), store: storeDir(home), image: meta.image, boxd, portFile, root, croot, runFolder, shims, pkglog, token: meta.token, bwrap: runtime.bwrap ?? null, idleMinutes: idle });+ const res = await run(runtime.bin, args, { timeoutMs: 45_000, env: { PATH: env.PATH || "/usr/bin:/bin", USER: env.USER || "" } });+ const out = parseOut(res.stdout);+ const port = num(out?.port);+ if (!out?.ok || !port) return { ok: false, error: `could not start the sandbox: ${String(out?.error || res.stderr || res.error || res.code).slice(0, 300)}` };+ // The folders this running box was started with (a box another session+ // started keeps its own until it stops).+ const mounts = [croot, RUN_DIR, ...(shims ? [`${SHIMS_DIR}-src`] : []), ...(pkglog ? [containerRoot(pkglog.root)] : [])];+ if (!out.reused) writeJson(file, { ...meta, mounts, started_at: new Date().toISOString(), launcher: out.launcher, idmap: out.idmap, overlay: out.overlay });+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token: meta.token }, uid: 0, gid: 0, containerId: `bwrap_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: out.reused ? (meta.mounts ?? mounts) : mounts, timing: { ...(num(out.ms) !== null ? { ms: num(out.ms) ?? 0 } : {}), reused: Boolean(out.reused) } };+}++function pidAlive(pid: unknown): boolean {+ if (typeof pid !== "number" || !pid) return false;+ try { process.kill(pid, 0); return true; } catch (error) { return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM"; }+}++async function list(_runtime: BoxRuntime, { home = "" }: { home?: string } = {}): Promise<ListedBox[]> {+ const dir = path.join(bwrapHome(home), "boxes");+ let names: string[] = [];+ try { names = readdirSync(dir).filter((name) => name.endsWith(".json")); } catch { return []; }+ const out: ListedBox[] = [];+ for (const name of names) {+ const meta = readJson<BoxMeta>(path.join(dir, name));+ if (!meta?.key) continue;+ let running = false;+ try { running = pidAlive(JSON.parse(readFileSync(path.join(boxDir(home, meta.key), "state.json"), "utf8")).pid); } catch { /* stopped */ }+ out.push({ key: meta.key, name: containerName(meta.key), root: meta.root, running, image: meta.pull || meta.ref || meta.image, created: meta.created_at || "" });+ }+ return out;+}++export const bwrapDriver: BoxDriver = {+ kind: "bwrap",+ execFallback: false,+ imagePresent,+ pull,+ pullCommand(runtime, image, home) {+ return { bin: runtime.bin, args: ["pull", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"] };+ },+ async exists(_runtime, key, { home = "" } = {}) {+ return existsSync(metaFile(home, key)) && existsSync(boxDir(home, key));+ },+ open,+ list,+ async remove(runtime, key, { run = runCommand, home = "" } = {}) {+ const res = await run(runtime.bin, ["rm", "--box", boxDir(home, key), ...(runtime.bwrap ? ["--bwrap", runtime.bwrap] : [])], { timeoutMs: 120_000 });+ const had = existsSync(metaFile(home, key));+ rmSync(metaFile(home, key), { force: true });+ return { removed: had && Boolean(parseOut(res.stdout)?.ok) };+ },+ async stop(runtime, key, { run = runCommand, home = "" } = {}) {+ const res = await run(runtime.bin, ["stop", "--box", boxDir(home, key)], { timeoutMs: 60_000 });+ return { stopped: Boolean(parseOut(res.stdout)?.ok) };+ },+ async gcImages(runtime, { run = runCommand, home = "", current, used }) {+ const removed: Removed[] = [];+ const dir = path.join(storeDir(home), "images");+ let ids: string[] = [];+ try { ids = readdirSync(dir); } catch { return removed; }+ const usedIds = new Set<string>();+ for (const box of await list(runtime, { home })) {+ const meta = readJson<BoxMeta>(metaFile(home, box.key));+ if (meta?.image) usedIds.add(meta.image);+ }+ const plain = (ref: unknown) => String(ref || "").replace(/@sha256:[0-9a-f]{64}$/, "").replace(/^docker\.io\//, "");+ const currentPlain = new Set([...current].map(plain));+ for (const id of ids) {+ const img = readJson<{ ref?: string }>(path.join(dir, id, "image.json"));+ if (!img || usedIds.has(id) || used.has(String(img.ref)) || currentPlain.has(plain(img.ref))) continue;+ if (!/(^|\/)omnirush-ai\/box-[a-z]+:/.test(String(img.ref))) continue;+ const res = await run(runtime.bin, ["rmimage", ...storeArgs(home), "--id", id], { timeoutMs: 120_000 });+ if (parseOut(res.stdout)?.ok) removed.push({ kind: "image", name: String(img.ref), reason: "not current" });+ }+ return removed;+ },+ async upperBytes(runtime, key, { run = runCommand, home = "" } = {}) {+ const res = await run(runtime.bin, ["status", "--box", boxDir(home, key)], { timeoutMs: 60_000 });+ return num(parseOut(res.stdout)?.upper_bytes);+ },+ shellCommand(runtime, { key, croot, home }) {+ return { bin: runtime.bin, args: ["enter", "--box", boxDir(home, key), "--wd", croot, "--", "/bin/bash", "-l"] };+ },+ execCommand: (_runtime, { key, home }) => boxshExec({ key, home }),+};++/** The AppArmor profile `sudo omnirush sandbox enable` (the CLI) installs for OmniRush's own bwrap copy. */+export function apparmorProfile(bwrap = ENABLED_BWRAP): string {+ return `# OmniRush sandbox: lets OmniRush's own bubblewrap copy (root-owned) create+# user namespaces on systems that restrict them (Ubuntu 23.10+). Written by+# \`sudo omnirush sandbox enable\`; \`sudo omnirush sandbox enable --undo\` removes it.+abi <abi/4.0>,+include <tunables/global>++profile omnirush-bwrap ${bwrap} flags=(unconfined) {+ userns,++ include if exists <local/omnirush-bwrap>+}+`;+}diff --git a/apps/server/src/box/backends/container.ts b/apps/server/src/box/backends/container.tsnew file mode 100644index 00000000..9576a94e--- /dev/null+++ b/apps/server/src/box/backends/container.ts@@ -0,0 +1,304 @@+// Ported from the CLI (omnirush-cli src/box/backends/container.js,+// feat/local-box-backends); keep the two in step. Desktop differences:+// types; the container-name prefix (containerName's env).+//+// Container engines as box backends: Docker (and what speaks its CLI:+// Docker Desktop, OrbStack, colima, Rancher Desktop, a Docker engine in+// WSL 2) and Podman (rootless on Linux, Podman machine elsewhere). One+// persistent container per project; boxd is copied in and published on+// this machine's loopback.++import { readFileSync } from "node:fs";+import os from "node:os";++import { BOX_PORT, GOARCH, HOME_IN_BOX, LABEL, RUN_DIR, SHIMS_DIR, containerName, containerRoot, firstLine, helperPath, newToken, wslPath, type BoxInstallLog, type BoxRuntime } from "../common.js";+import { runCommand, type RunCommand, type RunOptions } from "../run.js";+import type { BoxDriver, ListedBox, OpenContext, Opened } from "./types.js";++type Env = NodeJS.ProcessEnv;++/**+ * A tar with one executable file at `name` (and its folders), for `cp - <c>:/`:+ * `cp <file> <c>:<path>` needs the folder to exist in the image already.+ */+export function singleFileTar(name: string, data: Buffer, mode = 0o755): Buffer {+ const blocks: Buffer[] = [];+ const header = (entry: string, type: string, size: number, entryMode: number) => {+ const h = Buffer.alloc(512);+ h.write(entry, 0, 100, "utf8");+ h.write(`${entryMode.toString(8).padStart(7, "0")}\0`, 100);+ h.write("0000000\0", 108);+ h.write("0000000\0", 116);+ h.write(`${size.toString(8).padStart(11, "0")}\0`, 124);+ h.write(`${Math.floor(Date.now() / 1000).toString(8).padStart(11, "0")}\0`, 136);+ h.write(" ", 148);+ h.write(type, 156);+ h.write("ustar\0", 257);+ h.write("00", 263);+ let sum = 0;+ for (const byte of h) sum += byte;+ h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);+ return h;+ };+ const parts = name.split("/");+ for (let i = 1; i < parts.length; i += 1) blocks.push(header(`${parts.slice(0, i).join("/")}/`, "5", 0, 0o755));+ blocks.push(header(name, "0", data.length, mode));+ blocks.push(data, Buffer.alloc((512 - (data.length % 512)) % 512), Buffer.alloc(1024));+ return Buffer.concat(blocks);+}++// --- the runtime CLI ------------------------------------------------------------++/** Runs the runtime's CLI (`wsl.exe -e docker ...` for a WSL engine, `docker --context x ...`). */+export function rt(runtime: BoxRuntime, run: RunCommand = runCommand) {+ const prefix = Array.isArray(runtime.prefix) ? runtime.prefix : [];+ return (args: string[], opts: RunOptions = {}) => run(runtime.bin, [...prefix, ...args], { timeoutMs: 60_000, ...opts });+}++/** Where the runtime finds a folder of this machine (a WSL engine sees Windows drives under /mnt). */+function source(runtime: BoxRuntime, p: string): string {+ return runtime.wsl ? wslPath(p) : p;+}++/** Whether `image` is present locally; its id and repo digest when it is. */+export async function inspectImage(runtime: BoxRuntime, image: string, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ id: string; digest: string | null; arch: string; size: number } | null> {+ const res = await rt(runtime, run)(["image", "inspect", image, "--format", "{{json .}}"], { timeoutMs: 20_000 });+ if (res.code !== 0) return null;+ try {+ const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");+ const digests: unknown[] = Array.isArray(info.RepoDigests) ? info.RepoDigests : [];+ const digest = digests.map((entry) => String(entry).split("@")[1]).find((d) => /^sha256:[0-9a-f]{64}$/.test(d || "")) || null;+ return { id: String(info.Id || ""), digest, arch: String(info.Architecture || ""), size: Number(info.Size || 0) };+ } catch {+ return null;+ }+}++/** `pull` with retries (a flaky link picks up where it stopped). */+export async function pullImage(runtime: BoxRuntime, image: string, { run = runCommand, pauses = [2_000, 8_000], timeoutMs = 60 * 60_000, sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)) }: { run?: RunCommand; pauses?: number[]; timeoutMs?: number; sleep?: (ms: number) => Promise<unknown> } = {}): Promise<{ ok: true; attempts: number } | { ok: false; error: string }> {+ let last = null;+ for (let attempt = 0; attempt <= pauses.length; attempt += 1) {+ last = await rt(runtime, run)(["pull", image], { timeoutMs });+ if (last.code === 0) return { ok: true, attempts: attempt + 1 };+ if (attempt < pauses.length) await sleep(pauses[attempt]!);+ }+ const said = String(last?.stderr || "").split(/\r?\n/).map((line) => line.trim()).find(Boolean) || `pull exited with ${last?.code}`;+ return { ok: false, error: said.slice(0, 300) };+}++type ContainerInfo = { id: string; running: boolean; image: string; labels: Record<string, string>; env: string[]; mounts: string[] };++async function inspectContainer(runtime: BoxRuntime, name: string, run: RunCommand): Promise<ContainerInfo | null> {+ const res = await rt(runtime, run)(["container", "inspect", name, "--format", "{{json .}}"], { timeoutMs: 20_000 });+ if (res.code !== 0) return null;+ try {+ const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");+ return {+ id: String(info.Id || ""),+ running: Boolean(info.State?.Running),+ image: String(info.Image || ""),+ labels: info.Config?.Labels ?? {},+ env: Array.isArray(info.Config?.Env) ? info.Config.Env : [],+ mounts: Array.isArray(info.Mounts) ? info.Mounts.map((mount: { Destination?: unknown }) => String(mount.Destination ?? "")) : [],+ };+ } catch {+ return null;+ }+}++/** The host port boxd is published on. */+async function publishedPort(runtime: BoxRuntime, name: string, run: RunCommand): Promise<number | null> {+ const res = await rt(runtime, run)(["port", name, `${BOX_PORT}/tcp`], { timeoutMs: 15_000 });+ if (res.code !== 0) return null;+ for (const line of res.stdout.split("\n")) {+ const match = /:(\d+)\s*$/.exec(line.trim());+ if (match) return Number(match[1]);+ }+ return null;+}++/** Resource limits a new box gets (a VM runtime has its own; only the process cap then). */+export function resourceArgs({ runtime, env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { runtime: BoxRuntime; env?: Env; cpus?: number; memory?: number }): string[] {+ const args = ["--pids-limit", String(Number(env.OMNIRUSH_BOX_PIDS) || 4096)];+ const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);+ const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();+ if (askedCpus > 0) args.push("--cpus", String(askedCpus));+ else if (!runtime.vm) args.push("--cpus", String(Math.max(1, Math.min(8, cpus - 1))));+ if (askedMem) args.push("--memory", askedMem);+ else if (!runtime.vm) {+ const gib = Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)));+ args.push("--memory", `${gib}g`);+ }+ return args;+}++/** Who commands run as: root where root maps to the user (rootless, VMs), else the user's own uid. */+export function commandUser(runtime: BoxRuntime, { platform = process.platform, uid = process.getuid?.(), gid = process.getgid?.() }: { platform?: NodeJS.Platform; uid?: number; gid?: number } = {}): { uid: number; gid: number } {+ if (platform !== "linux" || runtime.rootless || runtime.vm || uid === undefined || gid === undefined || uid === 0) return { uid: 0, gid: 0 };+ return { uid, gid };+}++/**+ * Create a box container (not started): the project folder at `croot`, the+ * launcher's run folder at /run/omnirush, the package-manager wrappers (when+ * there are) read-only, boxd published on this machine's loopback only.+ * Nothing else of this machine goes in: no home folder, no credentials, no+ * docker socket.+ */+export function createArgs({ name, key, root, croot, image, runtime, run: runFolder, shims, pkglog = null, token, user, env = process.env, platform = process.platform }: { name: string; key: string; root: string; croot: string; image: string; runtime: BoxRuntime; run: string; shims: string | null; pkglog?: BoxInstallLog | null; token: string; user: { uid: number; gid: number }; env?: Env; platform?: NodeJS.Platform }): string[] {+ return [+ "create", "--name", name, "--hostname", "omnirush-box", "--init",+ "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`,+ "--mount", `type=bind,source=${source(runtime, root)},target=${croot}`,+ "--mount", `type=bind,source=${source(runtime, runFolder)},target=${RUN_DIR}`,+ ...(shims ? ["--mount", `type=bind,source=${source(runtime, shims)},target=${SHIMS_DIR}-src,readonly`] : []),+ // The install log's folder (phase 1: its wrappers, pip hook and the per-run folders the+ // wrappers note calls in), at the path the launcher reads it at.+ ...(pkglog ? ["--mount", `type=bind,source=${source(runtime, pkglog.root)},target=${containerRoot(pkglog.root, platform)}`] : []),+ "-p", `127.0.0.1::${BOX_PORT}`,+ "-e", `BOXD_TOKEN=${token}`, "-e", `BOXD_UID=${user.uid}`, "-e", `BOXD_GID=${user.gid}`,+ "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,+ "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",+ "-w", croot,+ ...resourceArgs({ runtime, env }),+ ...(runtime.name === "podman" ? ["--security-opt", "label=disable"] : []),+ ...(user.uid === 0 ? ["--security-opt", "no-new-privileges"] : []),+ "--entrypoint", "/opt/omnirush/bin/boxd",+ image,+ ];+}++/** "57.2MB (virtual 1.1GB)" -> bytes of the first number. */+export function parseSize(text: unknown): number | null {+ const match = /([\d.]+)\s*([kKMGT]?i?B)/.exec(String(text));+ if (!match) return null;+ const unit = match[2]!.replace(/i/, "").toUpperCase();+ const mult = ({ B: 1, KB: 1e3, MB: 1e6, GB: 1e9, TB: 1e12 } satisfies Record<string, number>)[unit] ?? 1;+ return Math.round(Number(match[1]) * mult);+}++// --- the driver ------------------------------------------------------------------++/** Create (or start) the project's container; boxd answers on a published loopback port. */+async function open(ctx: OpenContext): Promise<Opened> {+ const { key, name, root, croot, runtime, run, runFolder, image, pull, shims, pkglog, env, platform, log, onPulling } = ctx;+ let info = await inspectContainer(runtime, name, run);+ if (info && info.labels?.[`${LABEL}.root`] && info.labels[`${LABEL}.root`] !== root) {+ return { ok: false, error: `container ${name} belongs to another folder` };+ }+ let created = null;+ if (!info) {+ let present = await inspectImage(runtime, image.pull, { run });+ if (!present) {+ if (!pull) return { ok: false, error: "the sandbox image is not downloaded yet" };+ onPulling();+ const pulled = await pullImage(runtime, image.pull, { run });+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };+ present = await inspectImage(runtime, image.pull, { run });+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };+ }+ const goarch = GOARCH[present.arch] || GOARCH[runtime.arch ?? ""] || "amd64";+ const boxd = helperPath("boxd", { goos: "linux", goarch, env });+ if (!boxd) return { ok: false, error: `the sandbox helper is missing (linux-${goarch}/boxd)` };+ const user = commandUser(runtime, { platform });+ const made = await rt(runtime, run)(createArgs({ name, key, root, croot, image: image.pull, runtime, run: runFolder, shims, pkglog, token: newToken(), user, env, platform }), { timeoutMs: 120_000 });+ if (made.code !== 0) return { ok: false, error: `could not create the sandbox: ${firstLine(made.stderr)}` };+ const copied = await rt(runtime, run)(["cp", "-", `${name}:/`], { timeoutMs: 60_000, input: singleFileTar("opt/omnirush/bin/boxd", readFileSync(boxd)) });+ if (copied.code !== 0) {+ await rt(runtime, run)(["rm", "-f", name], { timeoutMs: 30_000 });+ return { ok: false, error: `could not copy the sandbox helper in: ${firstLine(copied.stderr)}` };+ }+ created = { ref: image.ref, pull: image.pull, digest: image.digest || present.digest, id: present.id, stack: image.stack };+ info = await inspectContainer(runtime, name, run);+ if (!info) return { ok: false, error: "the sandbox was not there after it was created" };+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: runtime.backend ?? runtime.name });+ }+ if (!info.running) {+ const started = await rt(runtime, run)(["start", name], { timeoutMs: 60_000 });+ if (started.code !== 0) return { ok: false, error: `could not start the sandbox: ${firstLine(started.stderr)}` };+ }+ const env0 = info.env;+ const envOf = (k: string, d = "") => (env0.find((kv) => kv.startsWith(`${k}=`)) || `${k}=${d}`).slice(k.length + 1);+ const port = await publishedPort(runtime, name, run);+ const token = envOf("BOXD_TOKEN");+ if (!port || !token) return { ok: false, error: "the sandbox started without its port" };+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token }, uid: Number(envOf("BOXD_UID", "0")), gid: Number(envOf("BOXD_GID", "0")), containerId: info.id, imageId: info.image, mounts: info.mounts };+}++/** Boxes on this machine: { key, name, root, running, image, created }[] */+export async function listContainers(runtime: BoxRuntime, { run = runCommand }: { run?: RunCommand } = {}): Promise<ListedBox[]> {+ const res = await rt(runtime, run)(["ps", "-a", "--filter", `label=${LABEL}=1`, "--format", "{{json .}}"], { timeoutMs: 30_000 });+ if (res.code !== 0) return [];+ const out: ListedBox[] = [];+ for (const line of res.stdout.split("\n")) {+ if (!line.trim()) continue;+ try {+ const row = JSON.parse(line);+ const labels: Record<string, string> = typeof row.Labels === "string"+ ? Object.fromEntries(row.Labels.split(",").map((kv: string) => { const i = kv.indexOf("="); return [kv.slice(0, i), kv.slice(i + 1)]; }))+ : (row.Labels ?? {});+ const name = Array.isArray(row.Names) ? row.Names[0] : String(row.Names ?? "");+ out.push({ key: labels[`${LABEL}.key`] ?? "", name, root: labels[`${LABEL}.root`] ?? "", running: /^up|running/i.test(String(row.Status ?? row.State ?? "")), image: String(row.Image ?? ""), created: String(row.CreatedAt ?? row.Created ?? "") });+ } catch { /* skip */ }+ }+ return out;+}++export const containerDriver: BoxDriver = {+ kind: "container",+ /** `docker exec` works when boxd is down (boxsh's fallback). */+ execFallback: true,+ async imagePresent(runtime, image, { run = runCommand } = {}) {+ const found = await inspectImage(runtime, image.pull, { run });+ return found ? { id: found.id, digest: found.digest, arch: found.arch } : null;+ },+ pull(runtime, image, { run = runCommand } = {}) {+ return pullImage(runtime, image.pull, { run });+ },+ /** The detached download (the app keeps no handle on it). */+ pullCommand(runtime, image) {+ return { bin: runtime.bin, args: [...(runtime.prefix ?? []), "pull", image.pull] };+ },+ async exists(runtime, key, { run = runCommand, env = process.env, timeoutMs = 20_000 } = {}) {+ const res = await rt(runtime, run)(["container", "inspect", containerName(key, env), "--format", "{{.Id}}"], { timeoutMs });+ return res.code === 0;+ },+ open,+ list: (runtime, { run = runCommand } = {}) => listContainers(runtime, { run }),+ async remove(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await rt(runtime, run)(["rm", "-f", containerName(key, env)], { timeoutMs: 60_000 });+ return { removed: res.code === 0 };+ },+ /** Box images that no box uses and that are not the current pins (`omnirush-ai/box-*` only; never a prune). */+ async gcImages(runtime, { run = runCommand, current, used }) {+ const removed = [];+ const images = await rt(runtime, run)(["images", "--format", "{{.Repository}}:{{.Tag}} {{.ID}}"], { timeoutMs: 30_000 });+ for (const line of images.stdout.split("\n")) {+ const [ref, id] = line.trim().split(/\s+/);+ if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref) || (id && used.has(id))) continue;+ const res = await rt(runtime, run)(["rmi", ref], { timeoutMs: 60_000 });+ if (res.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });+ }+ return removed;+ },+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await rt(runtime, run)(["stop", "-t", "1", containerName(key, env)], { timeoutMs: 60_000 });+ return { stopped: res.code === 0 };+ },+ async upperBytes(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await rt(runtime, run)(["ps", "-a", "-s", "--filter", `name=^/?${containerName(key, env)}$`, "--format", "{{.Size}}"], { timeoutMs: 30_000 });+ return parseSize(res.stdout);+ },+ diff(runtime, key, { run = runCommand, env = process.env } = {}) {+ return rt(runtime, run)(["diff", containerName(key, env)], { timeoutMs: 120_000, maxBytes: 256 << 20 });+ },+ /** An interactive shell in the box. */+ shellCommand(runtime, { key, croot, uid, gid, env = process.env }) {+ const user = uid ? ["-u", `${uid}:${gid ?? uid}`] : [];+ return { bin: runtime.bin, args: [...(runtime.prefix ?? []), "exec", "-it", ...user, "-e", `HOME=${HOME_IN_BOX}`, "-w", croot, containerName(key, env), "/bin/bash"] };+ },+ /** How to run a program in the box with stdin open (files-used reads). */+ execCommand(runtime, { key, env = process.env }) {+ return { bin: runtime.bin, args: [...(runtime.prefix ?? []), "exec", "-i", containerName(key, env)], env: {} };+ },+};diff --git a/apps/server/src/box/backends/index.ts b/apps/server/src/box/backends/index.tsnew file mode 100644index 00000000..8b56a7f3--- /dev/null+++ b/apps/server/src/box/backends/index.ts@@ -0,0 +1,282 @@+// Ported from the CLI (omnirush-cli src/box/backends/index.js,+// feat/local-box-backends); keep the two in step. Desktop differences: types;+// the "asked" reason names the desktop setting.+//+// Which backend runs this machine's boxes: the best one that works, in a+// ranked order per OS, unless the user (the desktop setting,+// OMNIRUSH_BOX_BACKEND) or the server (its allowlist) says otherwise. Every+// backend gives the same thing: a persistent Linux box per project from the+// same pinned image, boxd inside, per-turn snapshots in the same+// `__sandbox__` format, so the converter and the rebuild do not change.+//+// Linux: bwrap (no daemon, no root) > rootless Podman > Docker+// macOS: Apple container (macOS 26+) > OrbStack > colima > Docker Desktop > Rancher > Podman machine+// Windows: WSL containers (wslc, WSL 3.0.1+) > OmniRush's WSL distro > Docker Desktop > Podman machine+// > Docker in the default WSL distro+//+// Nothing found: the project runs on this machine with one line saying why+// (never an install, never a wait).++import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";+import os from "node:os";+import path from "node:path";++import { runCommand, type RunCommand } from "../run.js";+import { CACHE_FAIL_MS, CACHE_OK_MS, candidates, isWsl, probe as probeContainer, probeWsl, wslLauncher, type BackendAlternative, type DetectOptions, type RuntimeFailure, type RuntimeInfo, type RuntimeResult, type RuntimeTried } from "../runtime.js";+import { appleDriver, probeApple } from "./apple.js";+import { bwrapDriver, probeBwrap } from "./bwrap.js";+import { containerDriver } from "./container.js";+import type { BoxDriver } from "./types.js";+import { probeWslDistro, wslDriver } from "./wsl.js";+import { probeWslc, wslcDriver } from "./wslc.js";++type Env = NodeJS.ProcessEnv;++export const ORDER: Record<"linux" | "darwin" | "win32", string[]> = {+ linux: ["bwrap", "podman", "docker"],+ darwin: ["apple", "orbstack", "colima", "docker-desktop", "rancher", "podman", "docker"],+ win32: ["wslc", "wsl", "docker-desktop", "podman", "docker", "wsl-engine"],+};++/** What the backend setting takes (and what uploads record as sandbox.backend). */+export const BACKENDS = ["bwrap", "apple", "wslc", "wsl", "orbstack", "colima", "docker-desktop", "rancher", "docker", "podman", "wsl-engine"] as const;+export type BackendId = (typeof BACKENDS)[number];+export const LABELS: Record<string, string> = {+ bwrap: "bubblewrap (no daemon)", apple: "Apple container", wslc: "WSL containers (wslc)", wsl: "OmniRush WSL distro", orbstack: "OrbStack", colima: "colima",+ "docker-desktop": "Docker Desktop", rancher: "Rancher Desktop", docker: "Docker", podman: "Podman", "wsl-engine": "Docker/Podman in WSL",+};++/** The ranked backends of a platform (the setting's choices there). */+export function backendsFor(platform: NodeJS.Platform = process.platform): string[] {+ return platform === "darwin" ? ORDER.darwin : platform === "win32" ? ORDER.win32 : ORDER.linux;+}++/** The driver (image, open, list, remove, ...) for a detected runtime. */+export function driverFor(runtime: { backend?: string } | null | undefined): BoxDriver {+ switch (runtime?.backend) {+ case "bwrap": return bwrapDriver;+ case "apple": return appleDriver;+ case "wsl": return wslDriver;+ case "wslc": return wslcDriver;+ default: return containerDriver;+ }+}++/** The backend id of a probed container runtime (from what answered `info`). */+export function containerBackendId(runtime: Pick<RuntimeInfo, "name" | "wsl" | "prefix" | "flavor">): string {+ if (runtime.name === "podman") return "podman";+ if (runtime.wsl && runtime.prefix?.[0] === "-e") return "wsl-engine";+ switch (runtime.flavor) {+ case "desktop": return "docker-desktop";+ case "orbstack": return "orbstack";+ case "colima": return "colima";+ case "rancher": return "rancher";+ default: return "docker";+ }+}++/** The backend an OMNIRUSH_BOX_RUNTIME path names when it is not a Docker/Podman CLI. */+export function runtimeBackend(value: unknown, platform: NodeJS.Platform = process.platform): string | null {+ const base = String(value || "").split(/[\\/]/).pop()?.toLowerCase().replace(/\.exe$/, "") ?? "";+ if (base === "wslc") return "wslc";+ if (base === "container" && platform !== "win32") return "apple";+ if (base === "boxrun" || base === "bwrap") return "bwrap";+ const lower = String(value || "").toLowerCase();+ if (["bwrap", "apple", "wslc", "wsl"].includes(lower)) return lower;+ return null;+}++function isBackendId(value: string): value is BackendId {+ return BACKENDS.some((id) => id === value);+}++/** The backend setting's value: a backend id, "auto", or "native" (no box). Aliases accepted; null: unknown. */+export function normalizeBackend(value: unknown): BackendId | "auto" | "native" | null {+ const v = String(value ?? "").trim().toLowerCase();+ if (!v || v === "auto" || v === "default") return "auto";+ const alias: Record<string, string> = { bubblewrap: "bwrap", "apple-container": "apple", container: "apple", "wsl-containers": "wslc", "wsl-container": "wslc", desktop: "docker-desktop", "docker desktop": "docker-desktop", "podman-machine": "podman", off: "native", none: "native", host: "native" };+ const id = alias[v] ?? v;+ if (id === "native") return "native";+ return isBackendId(id) ? id : null;+}++/** Docker contexts (macOS, Windows): OrbStack, colima, Docker Desktop and Rancher each register one. */+export async function dockerContexts(bin: string, { run = runCommand, env = process.env, timeoutMs = 5_000 }: { run?: RunCommand; env?: Env; timeoutMs?: number } = {}): Promise<Array<{ name: string; endpoint: string; current: boolean }>> {+ const res = await run(bin, ["context", "ls", "--format", "{{json .}}"], { env, timeoutMs });+ if (res.code !== 0) return [];+ const out = [];+ for (const line of String(res.stdout).split("\n")) {+ try {+ const row = JSON.parse(line);+ if (row && typeof row.Name === "string" && row.Name) out.push({ name: row.Name, endpoint: String(row.DockerEndpoint ?? ""), current: Boolean(row.Current) });+ } catch { /* skip */ }+ }+ return out;+}++type Probed = RuntimeResult & { backend: string };++function contextBackendGuess(name: string): string {+ if (/orbstack/i.test(name)) return "orbstack";+ if (/colima/i.test(name)) return "colima";+ if (/desktop/i.test(name)) return "docker-desktop";+ if (/rancher/i.test(name)) return "rancher";+ return "docker";+}++/** Every container runtime here, probed, each with its backend id. */+export async function probeContainers({ platform, env, home, exists, run, wsl, timeoutMs }: { platform: NodeJS.Platform; env: Env; home: string; exists: (file: string) => boolean; run: RunCommand; wsl: boolean; timeoutMs?: number | undefined }): Promise<Probed[]> {+ const out: Probed[] = [];+ const seen = new Set<string>();+ const limit = timeoutMs ? { timeoutMs } : {};+ for (const candidate of candidates({ platform, home, env, exists, wsl })) {+ // /bin/docker and /usr/bin/docker are one program on merged-/usr systems.+ let real = candidate.bin;+ try { real = realpathSync(candidate.bin); } catch { /* keep */ }+ if (seen.has(real)) continue;+ seen.add(real);+ if (candidate.name === "docker" && platform !== "linux" && !env.DOCKER_HOST && !env.DOCKER_CONTEXT && !candidate.skipped) {+ const contexts = await dockerContexts(candidate.bin, { run, env });+ const named = contexts.filter((c) => c.name !== "default");+ if (named.length) {+ for (const ctx of [...named, ...contexts.filter((c) => c.name === "default")]) {+ const prefix = ["--context", ctx.name];+ const probed = await probeContainer({ ...candidate, prefix }, { run, env, platform, wsl, ...limit });+ out.push(probed.ok+ ? { ...probed, prefix, context: ctx.name, backend: containerBackendId(probed) }+ : { ...probed, context: ctx.name, backend: contextBackendGuess(ctx.name) });+ }+ continue;+ }+ }+ const probed = await probeContainer(candidate, { run, env, platform, wsl, ...limit });+ out.push({ ...probed, backend: probed.ok ? containerBackendId(probed) : candidate.name });+ }+ return out;+}++function cacheFile(boxHome: string): string {+ return path.join(boxHome, "runtime.json");+}++function readCache(boxHome: string, now: number, key: string): RuntimeResult | null {+ try {+ const cached = JSON.parse(readFileSync(cacheFile(boxHome), "utf8"));+ if (cached?.key !== key) return null;+ const age = now - Number(cached.at);+ if (!(age >= 0)) return null;+ if (cached.result?.ok ? age < CACHE_OK_MS : age < CACHE_FAIL_MS) return cached.result;+ } catch { /* none */ }+ return null;+}++function writeCache(boxHome: string, key: string, result: RuntimeResult, now: number): void {+ try {+ mkdirSync(boxHome, { recursive: true });+ const file = cacheFile(boxHome);+ const tmp = `${file}.${process.pid}.tmp`;+ writeFileSync(tmp, JSON.stringify({ key, at: now, result }), { mode: 0o600 });+ renameSync(tmp, file);+ } catch { /* best effort */ }+}++/** One line when nothing works, with the free option to install. */+export function noneReason(platform: NodeJS.Platform): string {+ if (platform === "linux") return "no sandbox backend works here (install bubblewrap, Podman or Docker)";+ if (platform === "darwin") return "no container runtime found (free: `brew install colima docker && colima start`; also Apple container on macOS 26, OrbStack, Docker Desktop, Podman)";+ return "no sandbox backend found (turn on WSL 2: `wsl --install --no-distribution` as administrator, then `wsl --update` for WSL containers; or Docker Desktop, Podman)";+}++function alternative(r: Probed | { backend: string; name: string; ok: false; reason: string }): BackendAlternative {+ const version = "version" in r && typeof r.version === "string" ? r.version : null;+ const flavor = r.ok ? r.flavor : null;+ const reason = r.ok ? null : r.reason;+ const context = "context" in r && typeof r.context === "string" ? r.context : undefined;+ return { backend: r.backend, name: r.name ?? r.backend, ok: r.ok, version, flavor, reason, ...(context ? { context } : {}) };+}++/**+ * The backend for boxes on this machine (cached; `fresh` skips the cache;+ * `all` probes every backend and lists them as `alternatives`, for the+ * status). Returns the runtime ({ ok: true, backend, name, bin, version,+ * flavor, ..., why }) or { ok: false, reason, tried }. `asked`: a backend id+ * or "auto" (the setting); `allow`: the server's allowlist (null: any).+ */+export async function detectBackend({ boxHome, env = process.env, platform = process.platform, home = os.homedir(), exists = existsSync, run = runCommand, wsl = platform === "linux" && isWsl(env), now = Date.now(), fresh = false, all = false, timeoutMs, asked = env.OMNIRUSH_BOX_BACKEND, allow = null, arch = process.arch, release = os.release() }: DetectOptions = {}): Promise<RuntimeResult> {+ let wanted = normalizeBackend(asked);+ let legacyRuntime = String(env.OMNIRUSH_BOX_RUNTIME || "").trim();+ // OMNIRUSH_BOX_RUNTIME naming a backend's own program picks that backend (the host kits do).+ const named = runtimeBackend(legacyRuntime, platform);+ if (named && wanted === "auto") { wanted = normalizeBackend(named); legacyRuntime = ""; }+ const allowList = Array.isArray(allow) ? allow.map(normalizeBackend).filter((id): id is BackendId | "auto" | "native" => Boolean(id)) : null;+ const key = JSON.stringify([2, platform, wanted, allowList, legacyRuntime, env.DOCKER_HOST || "", env.PATH || env.Path || "", env.OMNIRUSH_BOX_BWRAP || ""]);+ if (boxHome && !fresh && !all) {+ const cached = readCache(boxHome, now, key);+ if (cached) return { ...cached, cached: true };+ }+ if (wanted === null) return { ok: false, reason: `unknown sandbox backend "${asked}" (one of: auto, ${BACKENDS.join(", ")}, native)`, tried: [] };+ if (wanted === "native") return { ok: false, reason: "the sandbox backend is set to native (this machine)", tried: [], native: true };+ let order: string[] = backendsFor(platform);+ // OMNIRUSH_BOX_RUNTIME (docker, podman or a path) keeps meaning "this container CLI".+ if (legacyRuntime) order = order.filter((id) => !["bwrap", "apple", "wslc", "wsl", "wsl-engine"].includes(id));+ let why = `the first that works here, in order: ${order.join(" > ")}`;+ if (wanted !== "auto") {+ order = [wanted];+ why = "chosen in Settings (sandbox backend)";+ }+ const skipped: Array<{ backend: string; name: string; ok: false; reason: string }> = [];+ if (allowList) {+ for (const id of order) if (!allowList.some((allowed) => allowed === id)) skipped.push({ backend: id, name: id, ok: false, reason: "not allowed by the server" });+ order = order.filter((id) => allowList.some((allowed) => allowed === id));+ why += `; the server allows ${allowList.join(", ")}`;+ }+ const limit = timeoutMs ? { timeoutMs } : {};+ let containers: Probed[] | null = null;+ const containerList = async () => (containers ??= await probeContainers({ platform, env, home, exists, run, wsl, timeoutMs }));+ const results: Array<Probed | { backend: string; name: string; ok: false; reason: string }> = [];+ let chosen: (RuntimeInfo & { backend: string }) | null = null;+ for (const id of order) {+ let found: Probed[];+ if (id === "bwrap") found = [{ backend: "bwrap", ...(await probeBwrap({ env, boxHome: boxHome ?? path.join(home, ".omnirush", "box"), run, exists, platform, arch, ...limit })) }];+ else if (id === "apple") found = [{ backend: "apple", ...(await probeApple({ env, platform, arch, release, run, exists, ...limit })) }];+ else if (id === "wsl") found = [{ backend: "wsl", ...(await probeWslDistro({ env, platform, run, exists, arch, ...limit })) }];+ else if (id === "wslc") found = [{ backend: "wslc", ...(await probeWslc({ env, platform, run, exists, arch, ...limit })) }];+ else if (id === "wsl-engine") {+ if (platform !== "win32" || env.OMNIRUSH_BOX_WSL === "0") continue;+ const bin = wslLauncher({ env, exists });+ if (!bin) continue;+ const probed = await probeWsl(bin, { run, env, ...limit });+ found = [{ ...probed, backend: "wsl-engine" }];+ } else {+ const list = await containerList();+ found = list.filter((r) => r.backend === id || (wanted === id && id === "docker" && r.name === "docker"));+ // A runtime that failed before its flavor was known (a stopped colima) shows up once, under its guess.+ if (!found.length) {+ if (all) results.push({ backend: id, name: id, ok: false, reason: "not found" });+ continue;+ }+ }+ for (const result of found) {+ results.push(result);+ if (result.ok && !chosen) chosen = result;+ }+ if (chosen && !all) break;+ }+ if (all && containers === null) await containerList();+ const probedContainers: Probed[] = containers ?? [];+ if (all) for (const r of probedContainers) if (!results.some((x) => "bin" in x && x.bin === r.bin && ("context" in x ? x.context : undefined) === r.context && x.name === r.name)) results.push(r);+ const failed = [...skipped, ...results.filter((r) => !r.ok)];+ const tried: RuntimeTried[] = failed.map((r) => ({ backend: r.backend, ...(r.name ? { name: r.name } : {}), ...("bin" in r && r.bin ? { bin: r.bin } : {}), reason: r.ok ? "" : r.reason }));+ let result: RuntimeResult;+ if (chosen) {+ result = { ...chosen, why };+ } else {+ const reasons = tried.filter((t) => t.reason).map((t) => `${t.backend}: ${t.reason}`);+ const failure: RuntimeFailure = { ok: false, reason: reasons.length ? reasons.join("; ") : noneReason(platform), tried };+ if (platform === "darwin" && !results.some((r) => r.ok)) failure.hint = "colima";+ result = failure;+ }+ if (all) result.alternatives = [...skipped, ...results].map(alternative);+ if (boxHome && !all) writeCache(boxHome, key, result, now);+ return result;+}diff --git a/apps/server/src/box/backends/shared.ts b/apps/server/src/box/backends/shared.tsnew file mode 100644index 00000000..5d58b0fb--- /dev/null+++ b/apps/server/src/box/backends/shared.ts@@ -0,0 +1,54 @@+// Ported from the CLI (omnirush-cli src/box/backends/shared.js,+// feat/local-box-backends); keep the two in step. Desktop: the shell link is+// in <home>/shell-desktop (common.ts shellDir).+//+// What every backend without a container CLI shares.++import path from "node:path";++import { shellDir } from "../common.js";+import type { BoxExec } from "./types.js";++/**+ * Run a program in the box with stdin open (the files-used reader) through+ * boxsh, the engine's shell: `bash -c 'exec "$0" "$@"' prog args...`.+ */+export function boxshExec({ key, home, platform = process.platform }: { key: string; home: string; platform?: NodeJS.Platform }): BoxExec {+ return {+ bin: path.join(shellDir(home), platform === "win32" ? "bash.exe" : "bash"),+ args: ["-c", 'exec "$0" "$@"'],+ env: { OMNIRUSH_BOX_KEY: key, OMNIRUSH_BOX_HOME: home },+ };+}++/** "1.4.1" >= "1.0.0"; non-numeric parts count as 0. */+export function versionAtLeast(version: unknown, min: string): boolean {+ const a = String(version).split(/[.+-]/).map((x) => Number.parseInt(x, 10) || 0);+ const b = String(min).split(".").map((x) => Number.parseInt(x, 10) || 0);+ for (let i = 0; i < Math.max(a.length, b.length); i += 1) {+ if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);+ }+ return true;+}++/** The last JSON object a helper printed (boxrun prints one line per answer). */+export function parseOut(stdout: unknown): Record<string, unknown> | null {+ const lines = String(stdout ?? "").split("\n").map((line) => line.trim()).filter((line) => line.startsWith("{"));+ for (let i = lines.length - 1; i >= 0; i -= 1) {+ try {+ const value: unknown = JSON.parse(lines[i]!);+ if (value && typeof value === "object" && !Array.isArray(value)) return Object.fromEntries(Object.entries(value));+ } catch { /* next */ }+ }+ return null;+}++/** A field of a helper's answer as a string ("" when absent). */+export function str(value: unknown): string {+ return typeof value === "string" ? value : value === undefined || value === null ? "" : String(value);+}++/** A field of a helper's answer as a number (null when not one). */+export function num(value: unknown): number | null {+ return typeof value === "number" && Number.isFinite(value) ? value : null;+}diff --git a/apps/server/src/box/backends/types.ts b/apps/server/src/box/backends/types.tsnew file mode 100644index 00000000..45c17c25--- /dev/null+++ b/apps/server/src/box/backends/types.ts@@ -0,0 +1,81 @@+// The shape every box backend's driver has (the CLI's drivers are plain+// objects of the same functions: src/box/backends/*.js).++import type { ChildProcess, SpawnOptions } from "node:child_process";++import type { BoxEndpoint } from "../client.js";+import type { BoxInstallLog, BoxLog, BoxRuntime } from "../common.js";+import type { BoxImage } from "../images.js";+import type { RunCommand, RunResult } from "../run.js";++type Env = NodeJS.ProcessEnv;++export type SpawnLike = (command: string, args: string[], options: SpawnOptions) => ChildProcess;++/** How to run a program in the box with stdin open (files-used reads) when it is not `docker exec`. */+export type BoxExec = { bin: string; args: string[]; env?: Record<string, string> };++export type CreatedImage = { ref: string; pull: string; digest: string | null; id: string; stack: string };++export type OpenContext = {+ key: string;+ name: string;+ root: string;+ croot: string;+ runtime: BoxRuntime;+ run: RunCommand;+ home: string;+ runFolder: string;+ image: BoxImage;+ pull: boolean;+ shims: string | null;+ pkglog: BoxInstallLog | null;+ env: Env;+ platform: NodeJS.Platform;+ log: BoxLog;+ onPulling: () => void;+ spawnImpl?: SpawnLike;+};++export type Opened =+ | {+ ok: true;+ created: CreatedImage | null;+ endpoint: BoxEndpoint;+ /** Other ways to boxd, tried in turn when the first does not answer (Apple: the container's own address). */+ alternates?: BoxEndpoint[];+ uid: number;+ gid: number;+ containerId: string;+ imageId: string;+ mounts: string[];+ timing?: { ms?: number; reused: boolean };+ }+ | { ok: false; error: string };++export type PresentImage = { id: string; digest: string | null; arch: string; config?: string };+export type ListedBox = { key: string; name: string; root: string; running: boolean; image: string; created: string };+export type Removed = { kind: string; name: string; reason: string };+export type DriverOptions = { run?: RunCommand; env?: Env; home?: string; timeoutMs?: number; log?: BoxLog };++export type BoxDriver = {+ kind: "container" | "bwrap" | "apple" | "wsl" | "wslc";+ /** boxsh may fall back to `<runtime> exec` when boxd does not answer (container engines and wslc). */+ execFallback: boolean;+ imagePresent: (runtime: BoxRuntime, image: BoxImage, opts?: DriverOptions) => Promise<PresentImage | null>;+ pull: (runtime: BoxRuntime, image: BoxImage, opts?: DriverOptions) => Promise<{ ok: true } | { ok: false; error: string }>;+ /** The detached download; null: the download runs in this process (Desktop: the WSL distro). */+ pullCommand: (runtime: BoxRuntime, image: BoxImage, home: string) => { bin: string; args: string[] } | null;+ exists: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<boolean>;+ open: (ctx: OpenContext) => Promise<Opened>;+ list: (runtime: BoxRuntime, opts?: DriverOptions) => Promise<ListedBox[]>;+ remove: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<{ removed: boolean }>;+ stop: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<{ stopped: boolean }>;+ gcImages: (runtime: BoxRuntime, opts: DriverOptions & { current: Set<string>; used: Set<string> }) => Promise<Removed[]>;+ upperBytes: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<number | null>;+ /** `<runtime> diff` (container engines only): the snapshot fallback when boxd cannot walk. */+ diff?: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<RunResult>;+ /** An interactive shell in the box. */+ shellCommand: (runtime: BoxRuntime, opts: { key: string; croot: string; home: string; uid?: number; gid?: number; env?: Env }) => { bin: string; args: string[] };+ execCommand: (runtime: BoxRuntime, opts: { key: string; home: string; env?: Env }) => BoxExec;+};diff --git a/apps/server/src/box/backends/wsl.ts b/apps/server/src/box/backends/wsl.tsnew file mode 100644index 00000000..7d0f012c--- /dev/null+++ b/apps/server/src/box/backends/wsl.ts@@ -0,0 +1,425 @@+// Ported from the CLI (omnirush-cli src/box/backends/wsl.js + wsl.json,+// feat/local-box-backends); keep the two in step. Desktop differences: types;+// wsl.json is a copy of the CLI's; the download (the distro, the helpers,+// the image) runs in the app's own process (pullCommand null: there is no+// `omnirush sandbox pull` to start detached).+//+// Windows: OmniRush's own WSL 2 distro as the box backend, so no Docker+// Desktop is needed. The distro ("OmniRushBox") is a small pinned root+// filesystem built FROM the same Debian base as the box images, with boxrun+// and boxd in /opt/omnirush and a wsl.conf that keeps Windows out (no+// Windows PATH, no interop: the 2.2.x "npm is the Windows npm" failure). It+// is imported per user with `wsl --import` (no admin once WSL is on). Each+// project's box runs inside it exactly like the Linux bubblewrap backend+// (boxrun, as root in the distro: unshare + overlay), from the same pinned+// images, so a Windows box is the same environment as a Linux one.+//+// The distro stays up while the app runs: a `wsl.exe ... boxrun up+// --foreground` keeper is this process's child (its stdin open). boxd+// listens on the distro's loopback; WSL forwards it to Windows' 127.0.0.1+// (NAT mode's localhost forwarding, or mirrored networking). With+// OMNIRUSH_BOX_WSL_LISTEN=any it listens on every address and the distro's+// own address is the second way in.+//+// WSL that is not enabled is never installed from here (`wsl --install`+// needs admin and a restart): one line gives the command, and the project+// runs on this machine meanwhile.++import { spawn, type ChildProcess } from "node:child_process";+import { createHash } from "node:crypto";+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";+import https from "node:https";+import path from "node:path";++import { GOARCH, containerName, containerRoot, firstLine, helperPath, readJson, writeJson, wslPath, type BoxLog, type BoxRuntime } from "../common.js";+import { runCommand, type RunCommand, type RunResult } from "../run.js";+import type { RuntimeResult } from "../runtime.js";+import bundledPins from "../wsl.json" with { type: "json" };+import { IDLE_MINUTES, newMeta, upArgs, type BoxMeta } from "./bwrap.js";+import { boxshExec, num, parseOut, str } from "./shared.js";+import type { BoxDriver, OpenContext, Opened, PresentImage, SpawnLike } from "./types.js";++type Env = NodeJS.ProcessEnv;+type WslRuntime = Pick<BoxRuntime, "bin" | "distro" | "arch" | "installed">;++export const DEFAULT_DISTRO = "OmniRushBox";+export const STORE = "/var/lib/omnirush/store";+export const BOXES = "/var/lib/omnirush/boxes";+export const ENABLE_HINT = "WSL 2 is not enabled on this Windows. One time, in an administrator terminal: `wsl --install --no-distribution`, then restart Windows";++export type WslAsset = { url: string | null; sha256: string | null; bytes?: number | null };+export type WslPins = { version?: string; distro?: string; base?: string; assets?: Record<string, WslAsset | undefined> };++export function loadWslPins(): WslPins {+ return bundledPins;+}++export function distroName(env: Env = process.env): string {+ return String(env.OMNIRUSH_BOX_WSL_DISTRO || "").trim() || DEFAULT_DISTRO;+}++/** wsl.exe, when Windows has it (System32). */+export function wslExe({ env = process.env, exists = existsSync }: { env?: Env; exists?: (file: string) => boolean } = {}): string | null {+ const root = env.SystemRoot || env.SYSTEMROOT || "C:\\Windows";+ const file = path.win32.join(root, "System32", "wsl.exe");+ return exists(file) ? file : null;+}++/**+ * wsl.exe's own output is UTF-16LE (with a BOM sometimes) unless WSL_UTF8=1+ * is honoured; read either way.+ */+export function decodeWsl(data: unknown): string {+ let text: string;+ if (Buffer.isBuffer(data)) {+ const nuls = data.subarray(0, 200).filter((b) => b === 0).length;+ const utf16 = nuls > 0 && nuls >= Math.min(data.length, 200) / 4;+ text = utf16 ? data.toString("utf16le") : data.toString("utf8");+ } else {+ text = String(data ?? "");+ }+ return text.replace(/^\uFEFF/, "").replace(/\uFEFF/g, "").replace(/\u0000/g, "").replace(/\r/g, "");+}++export type WslRow = { name: string; state: string; version: string; isDefault: boolean };++/** `wsl --list --verbose`: [{ name, state, version, isDefault }] (the header line is skipped). */+export function parseWslList(text: unknown): WslRow[] {+ const rows: WslRow[] = [];+ for (const raw of decodeWsl(text).split("\n")) {+ const line = raw.trimEnd();+ if (!line.trim() || /^\s*\*?\s*NAME\s+STATE\s+VERSION/i.test(line)) continue;+ const isDefault = /^\s*\*/.test(line);+ const parts = line.replace(/^\s*\*?\s*/, "").split(/\s{2,}|\t+/).map((p) => p.trim()).filter(Boolean);+ if (parts.length < 3 || !/^[12]$/.test(parts[parts.length - 1]!)) continue;+ rows.push({ name: parts.slice(0, parts.length - 2).join(" "), state: parts[parts.length - 2]!, version: parts[parts.length - 1]!, isDefault });+ }+ return rows;+}++const NOT_ENABLED = /not installed|is not enabled|optional component|virtual machine platform|HCS_E_HYPERV_NOT_INSTALLED|WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED|0x8007019e|0x80370102|wsl\.exe --install|enable the .*feature/i;+const NO_DISTROS = /no installed distributions|WSL_E_DEFAULT_DISTRO_NOT_FOUND|has no installed distributions/i;++/** Run wsl.exe; its output decoded (UTF-16 or UTF-8). */+export async function wslCall(bin: string, args: string[], { run = runCommand, env = process.env, timeoutMs = 20_000, input }: { run?: RunCommand; env?: Env; timeoutMs?: number; input?: string | Buffer } = {}): Promise<RunResult> {+ const res = await run(bin, args, { env: { ...env, WSL_UTF8: "1" }, timeoutMs, ...(input !== undefined ? { input } : {}) });+ return { ...res, stdout: decodeWsl(res.stdout), stderr: decodeWsl(res.stderr) };+}++/** A command inside the distro, as root, no shell in between. */+export function inDistro(runtime: Pick<BoxRuntime, "distro">, argv: string[]): string[] {+ return ["-d", runtime.distro ?? DEFAULT_DISTRO, "-u", "root", "--cd", "/", "--exec", ...argv];+}++function assetFor(pins: WslPins | null, arch: string): WslAsset | null {+ const asset = pins?.assets?.[GOARCH[arch] || "amd64"];+ return asset?.url && /^[0-9a-f]{64}$/.test(String(asset.sha256 || "")) ? asset : null;+}++export async function probeWslDistro({ env = process.env, platform = process.platform, run = runCommand, exists = existsSync, timeoutMs = 15_000, arch = process.arch }: { env?: Env; platform?: NodeJS.Platform; run?: RunCommand; exists?: (file: string) => boolean; timeoutMs?: number; arch?: string } = {}): Promise<RuntimeResult> {+ const base = { name: "wsl", backend: "wsl" };+ if (platform !== "win32") return { ...base, ok: false, reason: "the OmniRush WSL distro is for Windows" };+ if (env.OMNIRUSH_BOX_WSL === "0") return { ...base, ok: false, reason: "turned off (OMNIRUSH_BOX_WSL=0)" };+ const bin = wslExe({ env, exists });+ if (!bin) return { ...base, ok: false, reason: ENABLE_HINT };+ const status = await wslCall(bin, ["--status"], { run, env, timeoutMs });+ const said = `${status.stdout}\n${status.stderr}`;+ if (NOT_ENABLED.test(said) || (status.code !== 0 && !NO_DISTROS.test(said))) {+ return { ...base, ok: false, bin, reason: NOT_ENABLED.test(said) || status.error === "ENOENT" ? ENABLE_HINT : `\`wsl --status\` failed: ${firstLine(said) || status.code}` };+ }+ if (/default version:\s*1\b/i.test(said) && /wsl 2 is not supported|requires an update/i.test(said)) {+ return { ...base, ok: false, bin, reason: ENABLE_HINT };+ }+ const listed = await wslCall(bin, ["--list", "--verbose"], { run, env, timeoutMs });+ const rows = listed.code === 0 ? parseWslList(listed.stdout) : [];+ const distro = distroName(env);+ const mine = rows.find((row) => row.name.toLowerCase() === distro.toLowerCase());+ if (mine && mine.version === "1") return { ...base, ok: false, bin, reason: `the ${distro} distro runs as WSL 1 (\`wsl --set-version ${distro} 2\`)` };+ if (!mine && !String(env.OMNIRUSH_BOX_WSL_ROOTFS || "").trim() && !assetFor(loadWslPins(), arch)) {+ return { ...base, ok: false, bin, reason: "the OmniRush WSL image is not published yet (OMNIRUSH_BOX_WSL_ROOTFS=<built tar> to use one)" };+ }+ const ver = await wslCall(bin, ["--version"], { run, env, timeoutMs });+ const version = (/(\d+\.\d+\.\d+(?:\.\d+)?)/.exec(ver.code === 0 ? ver.stdout : "") ?? [])[1] ?? "";+ return { ...base, ok: true, bin, distro, installed: Boolean(mine), state: mine?.state ?? null, version, flavor: "omnirush-distro", os: "linux", arch: GOARCH[arch] || "amd64", rootless: false, vm: true };+}++// --- the distro ----------------------------------------------------------------------++/** Where the distro's disk lives (per user, no admin). */+export function installDir(env: Env = process.env, distro = DEFAULT_DISTRO): string {+ const local = env.LOCALAPPDATA || path.win32.join(env.USERPROFILE || "C:\\Users\\Default", "AppData", "Local");+ return path.win32.join(local, "OmniRush", "wsl", distro);+}++/** sha256 of a file. */+export function sha256File(file: string): Promise<string> {+ return new Promise((resolve, reject) => {+ const hash = createHash("sha256");+ createReadStream(file).on("error", reject).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve(hash.digest("hex")));+ });+}++/** Download over https (redirects followed) to `dest`, checked against `sha256`. */+export async function download(url: string, dest: string, sha256: string | null, { maxRedirects = 5 }: { maxRedirects?: number } = {}): Promise<string> {+ mkdirSync(path.dirname(dest), { recursive: true });+ const tmp = `${dest}.${process.pid}.part`;+ await new Promise<void>((resolve, reject) => {+ const fetch = (u: string, left: number) => {+ https.get(u, { headers: { "user-agent": "omnirush" } }, (res) => {+ if ([301, 302, 303, 307, 308].includes(res.statusCode ?? 0) && res.headers.location && left > 0) {+ res.resume();+ fetch(new URL(res.headers.location, u).toString(), left - 1);+ return;+ }+ if (res.statusCode !== 200) { res.resume(); reject(new Error(`download: HTTP ${res.statusCode}`)); return; }+ const out = createWriteStream(tmp);+ res.pipe(out);+ out.on("finish", () => resolve());+ out.on("error", reject);+ res.on("error", reject);+ }).on("error", reject);+ };+ if (!/^https:\/\//.test(url)) { reject(new Error("download: https only")); return; }+ fetch(url, maxRedirects);+ });+ const got = await sha256File(tmp);+ if (sha256 && got !== sha256) { rmSync(tmp, { force: true }); throw new Error(`download: sha256 mismatch (${got.slice(0, 12)}…)`); }+ renameSync(tmp, dest);+ return dest;+}++/** The pinned root filesystem tarball: OMNIRUSH_BOX_WSL_ROOTFS (a local file), else the pinned release asset. */+export async function rootfsTarball({ env = process.env, home, arch = process.arch, pins = loadWslPins(), fetchFile = download }: { env?: Env; home: string; arch?: string; pins?: WslPins; fetchFile?: typeof download }): Promise<string> {+ const asked = String(env.OMNIRUSH_BOX_WSL_ROOTFS || "").trim();+ if (asked) {+ if (!existsSync(asked)) throw new Error(`OMNIRUSH_BOX_WSL_ROOTFS: ${asked} is missing`);+ return asked;+ }+ const asset = assetFor(pins, arch);+ if (!asset?.url || !asset.sha256) throw new Error("the OmniRush WSL image is not published yet (set OMNIRUSH_BOX_WSL_ROOTFS to a built one)");+ const dest = path.join(home, "wsl", "cache", `${asset.sha256}.tar.gz`);+ if (existsSync(dest) && (await sha256File(dest)) === asset.sha256) return dest;+ return fetchFile(asset.url, dest, asset.sha256);+}++/** Import the distro when it is not there yet (`wsl --import <name> <dir> <tar> --version 2`). */+export async function ensureDistro(runtime: WslRuntime, { env = process.env, home, run = runCommand, log = () => {}, tarball = rootfsTarball }: { env?: Env; home: string; run?: RunCommand; log?: BoxLog; tarball?: typeof rootfsTarball }): Promise<{ ok: true; imported: boolean } | { ok: false; error: string }> {+ const distro = runtime.distro ?? DEFAULT_DISTRO;+ const listed = await wslCall(runtime.bin, ["--list", "--verbose"], { run, env });+ if (parseWslList(listed.stdout).some((row) => row.name.toLowerCase() === distro.toLowerCase())) return { ok: true, imported: false };+ let tar;+ try { tar = await tarball({ env, home }); } catch (error) { return { ok: false, error: error instanceof Error ? error.message : String(error) }; }+ const dir = installDir(env, distro);+ mkdirSync(dir, { recursive: true });+ const res = await wslCall(runtime.bin, ["--import", distro, dir, tar, "--version", "2"], { run, env, timeoutMs: 20 * 60_000 });+ if (res.code !== 0) return { ok: false, error: `wsl --import failed: ${firstLine(res.stderr) || firstLine(res.stdout) || res.code}` };+ log("info", "box wsl distro imported", { distro });+ return { ok: true, imported: true };+}++/** A stamp of the helpers this install ships (copied into the distro when it changes). */+function helperStamp(files: string[]): string {+ return files.map((f) => { try { const s = statSync(f); return `${s.size}-${Math.floor(s.mtimeMs)}`; } catch { return "0"; } }).join("_");+}++/** Copy boxrun and boxd into /opt/omnirush when this install's differ (cheap: one stamp file). */+export async function syncHelpers(runtime: WslRuntime, { env = process.env, run = runCommand }: { env?: Env; run?: RunCommand } = {}): Promise<{ ok: true } | { ok: false; error: string }> {+ const goarch = runtime.arch || "amd64";+ const boxrun = helperPath("boxrun", { goos: "linux", goarch, env });+ const boxd = helperPath("boxd", { goos: "linux", goarch, env });+ if (!boxrun || !boxd) return { ok: false, error: "the sandbox helpers (linux boxrun, boxd) are missing from this install" };+ const stamp = helperStamp([boxrun, boxd]);+ const script = 'set -e; [ "$(cat /opt/omnirush/helpers.stamp 2>/dev/null)" = "$3" ] && exit 0; mkdir -p /opt/omnirush; install -m 0755 "$1" /opt/omnirush/boxrun.new; install -m 0755 "$2" /opt/omnirush/boxd.new; mv /opt/omnirush/boxrun.new /opt/omnirush/boxrun; mv /opt/omnirush/boxd.new /opt/omnirush/boxd; echo "$3" > /opt/omnirush/helpers.stamp';+ const res = await wslCall(runtime.bin, inDistro(runtime, ["/bin/sh", "-c", script, "sh", wslPath(boxrun), wslPath(boxd), stamp]), { run, env, timeoutMs: 120_000 });+ return res.code === 0 ? { ok: true } : { ok: false, error: `could not update the helpers in WSL: ${firstLine(res.stderr) || res.code}` };+}++async function boxrun(runtime: WslRuntime, args: string[], { run = runCommand, env = process.env, timeoutMs = 60_000 }: { run?: RunCommand; env?: Env; timeoutMs?: number } = {}) {+ const res = await wslCall(runtime.bin, inDistro(runtime, ["/opt/omnirush/boxrun", ...args]), { run, env, timeoutMs });+ return { res, out: parseOut(res.stdout) };+}++const metaFile = (home: string, key: string) => path.join(home, "wsl", "boxes", `${key}.json`);++/** An image reference as boxrun in the distro reads it: a local archive's Windows path through /mnt. */+export function distroRef(ref: string): string {+ const m = /^(docker-archive|oci-archive):(.+)$/.exec(String(ref));+ return m ? `${m[1]}:${wslPath(m[2]!)}` : String(ref);+}+const boxPath = (key: string) => `${BOXES}/${key}`;++async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, env = process.env }: { run?: RunCommand; env?: Env } = {}): Promise<PresentImage | null> {+ if (!runtime.installed) {+ const listed = await wslCall(runtime.bin, ["--list", "--verbose"], { run, env });+ const distro = (runtime.distro ?? DEFAULT_DISTRO).toLowerCase();+ if (!parseWslList(listed.stdout).some((row) => row.name.toLowerCase() === distro)) return null;+ }+ const { out } = await boxrun(runtime, ["image", "--store", STORE, "--ref", distroRef(image.pull), "--arch", runtime.arch || "amd64"], { run, env, timeoutMs: 60_000 });+ return out?.present ? { id: str(out.id), digest: str(out.digest) || null, arch: str(out.arch), config: str(out.config) } : null;+}++/** "Download": the distro (once), the helpers, then the image inside it. */+async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, env = process.env, home = "", log = () => {} }: { run?: RunCommand; env?: Env; home?: string; log?: BoxLog } = {}): Promise<{ ok: true } | { ok: false; error: string }> {+ const distro = await ensureDistro(runtime, { env, home, run, log });+ if (!distro.ok) return { ok: false, error: distro.error };+ const synced = await syncHelpers(runtime, { env, run });+ if (!synced.ok) return { ok: false, error: synced.error };+ const { res, out } = await boxrun(runtime, ["pull", "--store", STORE, "--ref", distroRef(image.pull), "--arch", runtime.arch || "amd64"], { run, env, timeoutMs: 60 * 60_000 });+ return out?.ok ? { ok: true } : { ok: false, error: String(out?.error || firstLine(res.stderr) || res.code).slice(0, 300) };+}++type Keeper = { child: ChildProcess; endpoint: { host: string; port: number; token: string }; alternates: Array<{ host: string; port: number; token: string }> };++/** Keepers (wsl.exe boxrun up --foreground) of this process, per box. */+const keepers = new Map<string, Keeper>();++export type KeeperResult = { ok: true; out: Record<string, unknown>; child: ChildProcess } | { ok: false; error: string };++/** Start the keeper and read boxrun's first JSON line (the port). */+export function startKeeper(runtime: WslRuntime, args: string[], { env = process.env, spawnImpl = spawn, timeoutMs = 180_000 }: { env?: Env; spawnImpl?: SpawnLike; timeoutMs?: number } = {}): Promise<KeeperResult> {+ return new Promise((resolve) => {+ let child: ChildProcess;+ try {+ child = spawnImpl(runtime.bin, inDistro(runtime, ["/opt/omnirush/boxrun", ...args, "--foreground"]), { env: { ...env, WSL_UTF8: "1" }, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });+ } catch (error) {+ resolve({ ok: false, error: error instanceof Error ? error.message : String(error) });+ return;+ }+ let buffered = "";+ let errText = "";+ let done = false;+ const finish = (value: { ok: true; out: Record<string, unknown> } | { ok: false; error: string }) => {+ if (done) return;+ done = true;+ clearTimeout(timer);+ if (value.ok) {+ // Keep it running for this process's lifetime, without holding the process open.+ child.stdout?.removeAllListeners("data");+ child.stdout?.resume();+ child.unref();+ for (const handle of [child.stdin, child.stdout, child.stderr]) {+ if (handle && "unref" in handle && typeof handle.unref === "function") handle.unref();+ }+ resolve({ ...value, child });+ } else {+ try { child.kill(); } catch { /* gone */ }+ resolve(value);+ }+ };+ const timer = setTimeout(() => finish({ ok: false, error: `WSL did not start the box in ${Math.round(timeoutMs / 1000)} s` }), timeoutMs);+ child.stdout?.on("data", (chunk: Buffer) => {+ buffered += decodeWsl(chunk);+ const out = parseOut(buffered.split("\n").filter((line) => line.trim().startsWith("{")).join("\n"));+ if (out) finish(out.ok ? { ok: true, out } : { ok: false, error: str(out.error) || "boxrun up failed" });+ });+ child.stderr?.on("data", (chunk: Buffer) => { if (errText.length < 4000) errText += decodeWsl(chunk); });+ child.on("error", (error) => finish({ ok: false, error: error.message }));+ child.on("close", (code) => finish({ ok: false, error: `the WSL keeper exited (${code}): ${firstLine(errText)}` }));+ });+}++type WslMeta = BoxMeta & { mounts?: string[] };++async function open(ctx: OpenContext): Promise<Opened> {+ const { key, root, croot, runtime, run, home, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling, spawnImpl } = ctx;+ const file = metaFile(home, key);+ let meta = readJson<WslMeta>(file);+ if (meta && meta.root !== root) return { ok: false, error: `box ${key} belongs to another folder` };+ const live = keepers.get(key);+ if (live && live.child.exitCode === null && meta) {+ return { ok: true, created: null, endpoint: live.endpoint, alternates: live.alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: meta.mounts ?? [] };+ }+ let present = await imagePresent(runtime, image, { run, env });+ if (!present && !meta) {+ if (!mayPull) return { ok: false, error: runtime.installed ? "the sandbox image is not downloaded yet" : "the OmniRush WSL distro is not set up yet" };+ onPulling();+ const pulled = await pull(runtime, image, { run, env, home, log });+ if (!pulled.ok) return { ok: false, error: `could not set up the sandbox: ${pulled.error}` };+ present = await imagePresent(runtime, image, { run, env });+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };+ } else {+ const synced = await syncHelpers(runtime, { env, run });+ if (!synced.ok) return { ok: false, error: synced.error };+ }+ let created = null;+ if (!meta) {+ if (!present) return { ok: false, error: "the sandbox image is not downloaded yet" };+ meta = newMeta({ key, root, croot, present, image });+ mkdirSync(path.dirname(file), { recursive: true });+ writeJson(file, meta);+ created = { ref: image.ref, pull: image.pull, digest: meta.digest, id: present.config || present.id, stack: image.stack };+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "wsl" });+ }+ const listenAny = String(env.OMNIRUSH_BOX_WSL_LISTEN || "").toLowerCase() === "any";+ const idle = Number(env.OMNIRUSH_BOX_IDLE_MIN) > 0 ? Number(env.OMNIRUSH_BOX_IDLE_MIN) : IDLE_MINUTES;+ const args = upArgs({+ box: boxPath(key), store: STORE, image: meta.image, boxd: "/opt/omnirush/boxd", portFile: `${wslPath(runFolder)}/boxd.port`,+ root, croot, runFolder, shims, pkglog, token: meta.token, idleMinutes: idle, listen: listenAny ? "0.0.0.0:0" : "127.0.0.1:0",+ platform: "win32", mapPath: wslPath,+ });+ const kept = await startKeeper(runtime, args, { env, ...(spawnImpl ? { spawnImpl } : {}) });+ if (!kept.ok) return { ok: false, error: `could not start the sandbox: ${kept.error}` };+ const port = num(kept.out.port) ?? 0;+ const endpoint = { host: "127.0.0.1", port, token: meta.token };+ const alternates: Keeper["alternates"] = [];+ if (listenAny) {+ const ip = await wslCall(runtime.bin, inDistro(runtime, ["/bin/sh", "-c", "hostname -I"]), { run, env });+ const addr = String(ip.stdout).split(/\s+/).find((a) => /^\d+\.\d+\.\d+\.\d+$/.test(a));+ if (addr) alternates.push({ host: addr, port, token: meta.token });+ }+ const mounts = [croot, "/run/omnirush", ...(shims ? ["/opt/omnirush/pkglog-src"] : []), ...(pkglog ? [containerRoot(pkglog.root, "win32")] : [])];+ if (!kept.out.reused) writeJson(file, { ...meta, mounts, started_at: new Date().toISOString() });+ keepers.set(key, { child: kept.child, endpoint, alternates });+ return { ok: true, created, endpoint, alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: kept.out.reused ? (meta.mounts ?? mounts) : mounts };+}++function keeperAlive(key: string): boolean {+ const live = keepers.get(key);+ return Boolean(live && live.child.exitCode === null);+}++export const wslDriver: BoxDriver = {+ kind: "wsl",+ execFallback: false,+ imagePresent,+ pull,+ /** Desktop: the distro import, the helpers and the image download run in this process (launch.ts pullInBackground). */+ pullCommand() {+ return null;+ },+ async exists(_runtime, key, { home = "" } = {}) {+ return existsSync(metaFile(home, key));+ },+ open,+ async list(_runtime, { home = "" } = {}) {+ const dir = path.join(home, "wsl", "boxes");+ let names: string[] = [];+ try { names = readdirSync(dir).filter((n) => n.endsWith(".json")); } catch { return []; }+ return names.map((n) => readJson<WslMeta>(path.join(dir, n))).filter((m): m is WslMeta => Boolean(m?.key)).map((m) => ({ key: m.key, name: containerName(m.key), root: m.root, running: keeperAlive(m.key), image: m.pull || m.ref, created: m.created_at || "" }));+ },+ async remove(runtime, key, { run = runCommand, env = process.env, home = "" } = {}) {+ keepers.get(key)?.child.kill();+ keepers.delete(key);+ const { out } = await boxrun(runtime, ["rm", "--box", boxPath(key)], { run, env, timeoutMs: 120_000 });+ const had = existsSync(metaFile(home, key));+ rmSync(metaFile(home, key), { force: true });+ return { removed: had && Boolean(out?.ok) };+ },+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {+ keepers.get(key)?.child.kill();+ keepers.delete(key);+ const { out } = await boxrun(runtime, ["stop", "--box", boxPath(key)], { run, env });+ return { stopped: Boolean(out?.ok) };+ },+ async gcImages() {+ return [];+ },+ async upperBytes(runtime, key, { run = runCommand, env = process.env } = {}) {+ const { out } = await boxrun(runtime, ["status", "--box", boxPath(key)], { run, env });+ return num(out?.upper_bytes);+ },+ shellCommand(runtime, { key, croot }) {+ return { bin: runtime.bin, args: inDistro(runtime, ["/opt/omnirush/boxrun", "enter", "--box", boxPath(key), "--wd", croot, "--", "/bin/bash", "-l"]) };+ },+ execCommand: (_runtime, { key, home }) => boxshExec({ key, home, platform: "win32" }),+};diff --git a/apps/server/src/box/backends/wslc.ts b/apps/server/src/box/backends/wslc.tsnew file mode 100644index 00000000..9eb45fdc--- /dev/null+++ b/apps/server/src/box/backends/wslc.ts@@ -0,0 +1,275 @@+// Ported from the CLI (omnirush-cli src/box/backends/wslc.js,+// feat/local-box-backends); keep the two in step. Desktop differences: types;+// the container-name prefix (containerName's env); boxd missing from the+// sidecars is a reason.+//+// Windows: WSL containers (`wslc.exe`, alias `container.exe`), the container+// engine built into WSL since 3.0.1 (GA 2026-09-29; preview from 2.9.3).+// Containers share WSL 2's kernel; bind mounts take Windows paths and go+// over VirtioFS; `-p` publishes on Windows' loopback. One persistent+// container per project, like the Docker backend, with boxd mounted in from+// the run folder (there is no `cp -` from a tar stream) and published on a+// port chosen here. Snapshots are boxd's index walk (wslc has no `diff`).+//+// Written to wslc's real CLI (microsoft/WSL src/windows/wslc, Oct 2026:+// arguments/ArgumentDefinitions.h, commands/ContainerCreateCommand.cpp,+// VersionCommand.cpp, common/MountSpecParsing.cpp):+// wslc version --format json {"Client":{"Version":"3.0.1.0"}}+// wslc container create --name --label k=v --mount type=bind,source=C:\..,target=/..[,readonly]+// -p [ip:]host:container -e K=V -w DIR --entrypoint CMD --cpus N -m 4G IMAGE+// wslc container start|inspect|remove --force|list --all [--size] --format json+// wslc image pull|inspect|list|remove; wslc exec -i [-t] [-u] [-w] [-e] NAME CMD...+// No --init: boxd is PID 1 and reaps itself (boxd's init mode).++import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";+import os from "node:os";+import path from "node:path";++import { BOX_PORT, HOME_IN_BOX, LABEL, RUN_DIR, SHIMS_DIR, containerName, containerRoot, firstLine, freePort, helperPath, newToken, type BoxInstallLog, type BoxRuntime } from "../common.js";+import { runCommand, type RunCommand, type RunResult } from "../run.js";+import type { RuntimeResult } from "../runtime.js";+import { parseSize } from "./container.js";+import { versionAtLeast } from "./shared.js";+import type { BoxDriver, OpenContext, Opened, PresentImage } from "./types.js";+import { ENABLE_HINT, decodeWsl, wslCall, wslExe } from "./wsl.js";++type Env = NodeJS.ProcessEnv;+type Row = Record<string, unknown>;++/** WSL containers went GA in WSL 3.0.1; earlier previews (2.9.x) changed their CLI. */+export const SUPPORTED = { min: "3.0.1" };+export const UPDATE_HINT = "WSL is older than 3.0.1, which brings WSL containers (`wsl --update`, once)";++export function findWslc({ env = process.env, exists = existsSync }: { env?: Env; exists?: (file: string) => boolean } = {}): string | null {+ const asked = String(env.OMNIRUSH_BOX_WSLC_BIN || "").trim();+ if (asked) return exists(asked) ? asked : null;+ const dirs = String(env.Path || env.PATH || "").split(";").filter(Boolean);+ const pf = env.ProgramFiles || "C:\\Program Files";+ const local = env.LOCALAPPDATA || "";+ for (const dir of [...dirs, path.win32.join(pf, "WSL"), ...(local ? [path.win32.join(local, "Microsoft", "WindowsApps")] : [])]) {+ const file = path.win32.join(dir, "wslc.exe");+ if (exists(file)) return file;+ }+ return null;+}++/** `wslc version` (json or text): "3.0.1.0". */+export function parseWslcVersion(text: unknown): string {+ const s = decodeWsl(text).trim();+ try {+ const v: unknown = JSON.parse(s)?.Client?.Version;+ if (typeof v === "string" && v) return v;+ } catch { /* text */ }+ return (/(\d+\.\d+\.\d+(?:\.\d+)?)/.exec(s) ?? [])[1] ?? "";+}++export async function probeWslc({ env = process.env, platform = process.platform, run = runCommand, exists = existsSync, timeoutMs = 15_000, arch = process.arch }: { env?: Env; platform?: NodeJS.Platform; run?: RunCommand; exists?: (file: string) => boolean; timeoutMs?: number; arch?: string } = {}): Promise<RuntimeResult> {+ const base = { name: "wslc", backend: "wslc" };+ if (platform !== "win32") return { ...base, ok: false, reason: "WSL containers are Windows only" };+ if (env.OMNIRUSH_BOX_WSL === "0") return { ...base, ok: false, reason: "turned off (OMNIRUSH_BOX_WSL=0)" };+ const bin = findWslc({ env, exists });+ if (!bin) {+ // Tell "WSL is old" (one `wsl --update`) from "WSL is off" (admin, restart).+ const wsl = wslExe({ env, exists });+ if (!wsl) return { ...base, ok: false, reason: ENABLE_HINT };+ const ver = await wslCall(wsl, ["--version"], { run, env, timeoutMs });+ const version = (/(\d+\.\d+\.\d+(?:\.\d+)?)/.exec(ver.code === 0 ? ver.stdout : "") ?? [])[1] ?? "";+ if (!version) return { ...base, ok: false, reason: ver.code === 0 ? UPDATE_HINT : ENABLE_HINT };+ return { ...base, ok: false, reason: versionAtLeast(version, SUPPORTED.min) ? "wslc.exe is missing although WSL is 3.0.1 or later (`wsl --update`)" : `${UPDATE_HINT}; this is WSL ${version}` };+ }+ const res = await run(bin, ["version", "--format", "json"], { env, timeoutMs });+ let version = res.code === 0 ? parseWslcVersion(res.stdout) : "";+ if (!version) version = parseWslcVersion((await run(bin, ["version"], { env, timeoutMs })).stdout);+ if (!version) return { ...base, ok: false, bin, reason: `\`wslc version\` failed: ${firstLine(decodeWsl(res.stderr)) || res.code}` };+ if (!versionAtLeast(version, SUPPORTED.min)) return { ...base, ok: false, bin, version, reason: `${UPDATE_HINT}; wslc is ${version}` };+ return { ...base, ok: true, bin, version, os: "linux", arch: arch === "arm64" ? "arm64" : "amd64", flavor: "wslc", rootless: false, vm: true };+}++function rowOf(value: unknown): Row {+ return value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : {};+}++/** `container list --format json`: an array, or one object per line. */+export function parseJsonRows(text: unknown): Row[] {+ const s = decodeWsl(text).trim();+ if (!s) return [];+ try {+ const parsed: unknown = JSON.parse(s);+ return (Array.isArray(parsed) ? parsed : [parsed]).map(rowOf);+ } catch { /* lines */ }+ const out: Row[] = [];+ for (const line of s.split("\n")) {+ try { out.push(rowOf(JSON.parse(line))); } catch { /* skip */ }+ }+ return out;+}++/** Labels as a map (an object, or docker's "k=v,k=v"). */+export function labelsOf(value: unknown): Record<string, string> {+ if (value && typeof value === "object" && !Array.isArray(value)) return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, String(v)]));+ if (typeof value !== "string") return {};+ return Object.fromEntries(value.split(",").filter(Boolean).map((kv) => { const i = kv.indexOf("="); return i < 0 ? [kv, ""] : [kv.slice(0, i), kv.slice(i + 1)]; }));+}++export function wslcResources({ env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { env?: Env; cpus?: number; memory?: number } = {}): string[] {+ const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);+ const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();+ const c = askedCpus > 0 ? Math.round(askedCpus) : Math.max(1, Math.min(8, cpus - 1));+ // wslc takes upper-case units only (512M, 4G).+ const m = askedMem ? askedMem.toUpperCase() : `${Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)))}G`;+ return ["--cpus", String(c), "-m", m];+}++export function createWslcArgs({ name, key, root, croot, image, runFolder, shims = null, pkglog = null, token, port, env = process.env }: { name: string; key: string; root: string; croot: string; image: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; port: number; env?: Env }): string[] {+ return [+ "container", "create", "--name", name,+ "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`, "--label", `${LABEL}.port=${port}`,+ "--hostname", "omnirush-box",+ "--mount", `type=bind,source=${root},target=${croot}`,+ "--mount", `type=bind,source=${runFolder},target=${RUN_DIR}`,+ "--mount", `type=bind,source=${path.win32.join(runFolder, "bin")},target=/opt/omnirush/bin,readonly`,+ ...(shims ? ["--mount", `type=bind,source=${shims},target=${SHIMS_DIR}-src,readonly`] : []),+ ...(pkglog ? ["--mount", `type=bind,source=${pkglog.root},target=${containerRoot(pkglog.root, "win32")}`] : []),+ "-p", `127.0.0.1:${port}:${BOX_PORT}`,+ "-e", `BOXD_TOKEN=${token}`, "-e", "BOXD_UID=0", "-e", "BOXD_GID=0", "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,+ "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",+ "-w", croot,+ ...wslcResources({ env }),+ "--entrypoint", "/opt/omnirush/bin/boxd",+ image,+ ];+}++function placeBoxd(runFolder: string, env: Env, goarch: string): string | null {+ const source = helperPath("boxd", { goos: "linux", goarch, env });+ if (!source) return `the sandbox helper boxd (linux-${goarch}) is missing from this install`;+ const dir = path.join(runFolder, "bin");+ mkdirSync(dir, { recursive: true });+ const target = path.join(dir, "boxd");+ let same = false;+ try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }+ if (!same) {+ copyFileSync(source, target);+ try { chmodSync(target, 0o755); } catch { /* Windows */ }+ }+ return null;+}++async function wslc(runtime: BoxRuntime, args: string[], { run = runCommand, timeoutMs = 60_000, env }: { run?: RunCommand; timeoutMs?: number; env?: Env } = {}): Promise<RunResult> {+ const res = await run(runtime.bin, args, { timeoutMs, ...(env ? { env } : {}) });+ return { ...res, stdout: decodeWsl(res.stdout), stderr: decodeWsl(res.stderr) };+}++const nameOf = (r: Row) => String(r.Names ?? r.Name ?? "").replace(/^\//, "");++async function row(runtime: BoxRuntime, name: string, { run, size = false }: { run: RunCommand; size?: boolean }): Promise<Row | null> {+ const res = await wslc(runtime, ["container", "list", "--all", ...(size ? ["--size"] : []), "--no-trunc", "--format", "json"], { run, timeoutMs: 30_000 });+ if (res.code !== 0) return null;+ return parseJsonRows(res.stdout).find((r) => nameOf(r) === name) ?? null;+}++async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<PresentImage | null> {+ const res = await wslc(runtime, ["image", "inspect", image.pull], { run, timeoutMs: 20_000 });+ if (res.code !== 0) return null;+ const info = parseJsonRows(res.stdout)[0] ?? {};+ const digest = (Array.isArray(info.RepoDigests) ? info.RepoDigests : []).map((d) => String(d).split("@")[1]).find((d) => /^sha256:[0-9a-f]{64}$/.test(d || "")) ?? null;+ return { id: String(info.Id ?? info.ID ?? image.pull), digest, arch: String(info.Architecture ?? "") };+}++async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ ok: true } | { ok: false; error: string }> {+ const res = await wslc(runtime, ["image", "pull", image.pull], { run, timeoutMs: 60 * 60_000 });+ return res.code === 0 ? { ok: true } : { ok: false, error: firstLine(res.stderr) || firstLine(res.stdout) || `image pull exited ${res.code}` };+}++async function open(ctx: OpenContext): Promise<Opened> {+ const { key, name, root, croot, runtime, run, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling } = ctx;+ let info = await row(runtime, name, { run });+ const labels = labelsOf(info?.Labels);+ if (info && labels[`${LABEL}.root`] && labels[`${LABEL}.root`] !== root) return { ok: false, error: `container ${name} belongs to another folder` };+ const placed = placeBoxd(runFolder, env, runtime.arch || "amd64");+ if (placed) return { ok: false, error: placed };+ const tokenFile = path.join(runFolder, "box-token");+ let created = null;+ if (!info) {+ let present = await imagePresent(runtime, image, { run });+ if (!present) {+ if (!mayPull) return { ok: false, error: "the sandbox image is not downloaded yet" };+ onPulling();+ const pulled = await pull(runtime, image, { run });+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };+ present = await imagePresent(runtime, image, { run });+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };+ }+ const token = newToken();+ writeFileSync(tokenFile, token, { mode: 0o600 });+ const port = await freePort();+ const made = await wslc(runtime, createWslcArgs({ name, key, root, croot, image: image.pull, runFolder, shims, pkglog, token, port, env }), { run, timeoutMs: 120_000 });+ if (made.code !== 0) return { ok: false, error: `could not create the sandbox: ${firstLine(made.stderr) || firstLine(made.stdout)}` };+ created = { ref: image.ref, pull: image.pull, digest: image.digest || present.digest, id: present.id, stack: image.stack };+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "wslc" });+ info = await row(runtime, name, { run });+ if (!info) return { ok: false, error: "the sandbox was created but is not listed" };+ }+ if (!/running/i.test(String(info.State ?? ""))) {+ const started = await wslc(runtime, ["container", "start", name], { run, timeoutMs: 120_000 });+ if (started.code !== 0) return { ok: false, error: `could not start the sandbox: ${firstLine(started.stderr) || firstLine(started.stdout)}` };+ }+ let token = "";+ try { token = readFileSync(tokenFile, "utf8").trim(); } catch { /* none */ }+ const port = Number(labelsOf(info.Labels)[`${LABEL}.port`]) || 0;+ if (!token || !port) return { ok: false, error: "the sandbox has no port or token (Reset sandbox makes a new one)" };+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token }, uid: 0, gid: 0, containerId: String(info.ID ?? info.Id ?? name), imageId: String(info.Image ?? ""), mounts: [croot, RUN_DIR, ...(shims ? [`${SHIMS_DIR}-src`] : []), ...(pkglog ? [containerRoot(pkglog.root, "win32")] : [])] };+}++export const wslcDriver: BoxDriver = {+ kind: "wslc",+ /** boxsh's fallback `<runtime> exec -i -w -u -e` matches wslc exec's flags. */+ execFallback: true,+ imagePresent,+ pull,+ pullCommand(runtime, image) {+ return { bin: runtime.bin, args: ["image", "pull", image.pull] };+ },+ async exists(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await wslc(runtime, ["container", "inspect", containerName(key, env)], { run, timeoutMs: 20_000 });+ return res.code === 0 && parseJsonRows(res.stdout).length > 0;+ },+ open,+ async list(runtime, { run = runCommand } = {}) {+ const res = await wslc(runtime, ["container", "list", "--all", "--no-trunc", "--format", "json"], { run, timeoutMs: 30_000 });+ if (res.code !== 0) return [];+ return parseJsonRows(res.stdout).map((r) => ({ r, labels: labelsOf(r.Labels) })).filter(({ labels }) => labels[LABEL] === "1").map(({ r, labels }) => ({+ key: labels[`${LABEL}.key`] ?? "", name: nameOf(r), root: labels[`${LABEL}.root`] ?? "",+ running: /running/i.test(String(r.State ?? "")), image: String(r.Image ?? ""), created: String(r.CreatedAt ?? ""),+ }));+ },+ async remove(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await wslc(runtime, ["container", "remove", "--force", containerName(key, env)], { run, timeoutMs: 60_000 });+ return { removed: res.code === 0 };+ },+ async gcImages(runtime, { run = runCommand, current, used }) {+ const removed = [];+ const res = await wslc(runtime, ["image", "list", "--format", "json"], { run, timeoutMs: 30_000 });+ for (const img of parseJsonRows(res.stdout)) {+ const ref = img.Repository && img.Tag ? `${img.Repository}:${img.Tag}` : String(img.Name ?? img.Reference ?? "");+ if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref)) continue;+ const del = await wslc(runtime, ["image", "remove", ref], { run, timeoutMs: 60_000 });+ if (del.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });+ }+ return removed;+ },+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {+ const res = await wslc(runtime, ["container", "stop", "-t", "1", containerName(key, env)], { run, timeoutMs: 60_000 });+ return { stopped: res.code === 0 };+ },+ async upperBytes(runtime, key, { run = runCommand, env = process.env } = {}) {+ const r = await row(runtime, containerName(key, env), { run, size: true });+ return r ? parseSize(r.Size) : null;+ },+ shellCommand(runtime, { key, croot, env = process.env }) {+ return { bin: runtime.bin, args: ["exec", "-it", "-w", croot, containerName(key, env), "/bin/bash", "-l"] };+ },+ execCommand(runtime, { key, env = process.env }) {+ return { bin: runtime.bin, args: ["exec", "-i", containerName(key, env)], env: {} };+ },+};diff --git a/apps/server/src/box/box-backends.test.ts b/apps/server/src/box/box-backends.test.tsnew file mode 100644index 00000000..877b4a9d--- /dev/null+++ b/apps/server/src/box/box-backends.test.ts@@ -0,0 +1,444 @@+// Ported from the CLI (omnirush-cli test/box-backends.test.js,+// feat/local-box-backends): the ranked choice per OS and each backend against+// its real CLI's output, mocked (no runtime on the test machine is touched):+// bubblewrap (boxrun's JSON), Apple `container` (1.x JSON), the OmniRush WSL+// distro (wsl.exe's UTF-16 output), WSL containers (wslc 3.0.1 JSON), and the+// overrides (the backend setting, the server's allowlist). Desktop additions:+// the service's status and setting, files-used through a non-container box.+import { afterEach, describe, expect, test } from "bun:test";+import { ChildProcess } from "node:child_process";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import os from "node:os";+import path from "node:path";+import { PassThrough } from "node:stream";++import { BACKENDS, backendsFor, detectBackend, driverFor, normalizeBackend, ORDER } from "./backends/index.js";+import { apparmorProfile, boxdEnv, boxrunPath, explainProbe, parseOut, probeBwrap, upArgs } from "./backends/bwrap.js";+import { createAppleArgs, findDigest, macosMajor, parseVersions, probeApple, snapshotInfo, SUPPORTED as APPLE } from "./backends/apple.js";+import { versionAtLeast } from "./backends/shared.js";+import { decodeWsl, ENABLE_HINT, inDistro, parseWslList, probeWslDistro, startKeeper } from "./backends/wsl.js";+import { createWslcArgs, labelsOf, parseJsonRows, parseWslcVersion, probeWslc, UPDATE_HINT } from "./backends/wslc.js";+import { Box, setToolsRoot } from "./box.js";+import { askedBackend, readBackend, rememberServerDefault, saveBackend, serverBackends } from "./launch.js";+import type { RunCommand, RunResult } from "./run.js";+import { BoxService, backendChoices, type BoxWorkspace } from "./service.js";+import { sandboxFilesUsed } from "../session-archive/files-used-sandbox.js";++const dirs: string[] = [];+const tmp = () => {+ const dir = mkdtempSync(path.join(os.tmpdir(), "box-be-"));+ dirs.push(dir);+ return dir;+};+afterEach(() => {+ setToolsRoot(null);+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });+});++const set = (...files: Array<string | null>) => (file: string) => files.includes(file);+const ok = (stdout: unknown): RunResult => ({ code: 0, stdout: typeof stdout === "string" ? stdout : JSON.stringify(stdout), stderr: "" });+const fail = (stderr: string, code = 1): RunResult => ({ code, stdout: "", stderr });++/** A helpers folder with linux boxrun and boxd (empty stand-ins): the desktop finds helpers only where they are. */+function helperBin(): string {+ const dir = tmp();+ for (const arch of ["amd64", "arm64"]) {+ mkdirSync(path.join(dir, `linux-${arch}`), { recursive: true });+ for (const name of ["boxrun", "boxd"]) writeFileSync(path.join(dir, `linux-${arch}`, name), "");+ }+ return dir;+}++// --- ranking and overrides ---------------------------------------------------------------++describe("box backends: ranking and overrides", () => {+ test("the ranked order per OS", () => {+ expect(ORDER.linux).toEqual(["bwrap", "podman", "docker"]);+ expect(ORDER.darwin).toEqual(["apple", "orbstack", "colima", "docker-desktop", "rancher", "podman", "docker"]);+ expect(ORDER.win32).toEqual(["wslc", "wsl", "docker-desktop", "podman", "docker", "wsl-engine"]);+ for (const list of Object.values(ORDER)) for (const id of list) expect(BACKENDS.some((b) => b === id)).toBe(true);+ expect(backendsFor("linux")).toEqual(ORDER.linux);+ expect(backendChoices("win32").map((c) => c.id)).toEqual(["auto", ...ORDER.win32, "native"]);+ });++ test("setting values: ids, aliases, auto, native; anything else is refused", () => {+ expect(normalizeBackend("")).toBe("auto");+ expect(normalizeBackend("Bubblewrap")).toBe("bwrap");+ expect(normalizeBackend("container")).toBe("apple");+ expect(normalizeBackend("wsl-containers")).toBe("wslc");+ expect(normalizeBackend("desktop")).toBe("docker-desktop");+ expect(normalizeBackend("off")).toBe("native");+ expect(normalizeBackend("lxc")).toBeNull();+ });+});++// --- Linux: bubblewrap ------------------------------------------------------------------------++const BWRAP_OK = { ok: true, launcher: "bwrap", bwrap: "/usr/bin/bwrap", bwrap_version: "0.9.0", overlay: "kernel", idmap: "subuid", kernel: "6.8.0", apparmor_restrict_unprivileged_userns: 0, root: false, ms: 9 };+const BWRAP_AA = { ok: false, launcher: "bwrap", bwrap: "/usr/bin/bwrap", bwrap_version: "0.9.0", kernel: "6.8.0", apparmor_restrict_unprivileged_userns: 1, code: "apparmor", reason: "AppArmor blocks unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1, Ubuntu 23.10+)", detail: "bwrap: setting up uid map: Permission denied" };+const podmanInfo = { host: { arch: "amd64", os: "linux", security: { rootless: true } }, version: { Version: "4.9.3" } };++function linuxRun(bwrapAnswer: unknown, { podman = true }: { podman?: boolean } = {}) {+ const calls: string[] = [];+ const run: RunCommand = async (bin, args) => {+ calls.push([path.basename(bin), ...args].join(" "));+ if (bin.endsWith("boxrun")) return ok(bwrapAnswer);+ if (bin.endsWith("podman")) return podman ? ok(podmanInfo) : fail("podman: not found", 127);+ return fail("Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?");+ };+ return { run, calls };+}++describe("box backends: Linux", () => {+ test("bubblewrap first when its probe starts a namespace", async () => {+ const home = tmp();+ const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };+ const { run } = linuxRun(BWRAP_OK);+ const found = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, wsl: false });+ expect(found).toMatchObject({ ok: true, backend: "bwrap", flavor: "overlayfs", idmap: "subuid", version: "0.9.0" });+ if (found.ok) expect(found.why).toMatch(/bwrap > podman > docker/);+ expect(driverFor(found.ok ? found : null).kind).toBe("bwrap");+ });++ test("AppArmor's userns restriction: one-line reason with the admin fix, rootless Podman is used", async () => {+ const home = tmp();+ const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };+ const found = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run: linuxRun(BWRAP_AA).run, fresh: true, all: true, wsl: false });+ expect(found).toMatchObject({ ok: true, backend: "podman" });+ const bw = found.alternatives?.find((a) => a.backend === "bwrap");+ expect(bw?.ok).toBe(false);+ expect(bw?.reason).toMatch(/AppArmor .*sudo omnirush sandbox enable/);+ expect(bw?.reason).not.toMatch(/\n/);+ // Nothing else either: the project runs natively and says why in one line.+ const none = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env })), run: linuxRun(BWRAP_AA, { podman: false }).run, fresh: true, wsl: false });+ expect(none.ok).toBe(false);+ if (!none.ok) expect(none.reason).toMatch(/^bwrap: AppArmor/);+ });++ test("bwrap probe reasons: no bwrap, userns off, helper missing, garbage", async () => {+ expect(explainProbe({ code: "no_bwrap", reason: "bubblewrap (bwrap) is not installed" })).toMatch(/apt install bubblewrap/);+ expect(explainProbe({ code: "userns_off", reason: "x" })).toMatch(/Podman or Docker/);+ const home = tmp();+ const missing = await probeBwrap({ env: { OMNIRUSH_BOX_BIN_DIR: "/nope" }, boxHome: home, exists: () => false, platform: "linux" });+ expect(missing.ok ? "" : missing.reason).toMatch(/boxrun is missing/);+ const garbage = await probeBwrap({ env: { OMNIRUSH_BOX_BIN_DIR: helperBin() }, boxHome: home, exists: () => true, platform: "linux", run: async () => ({ code: 1, stdout: "", stderr: "segfault" }) });+ expect(garbage.ok).toBe(false);+ expect(parseOut('noise\n{"a":1}\n{"ok":true,"port":5}\n')).toEqual({ ok: true, port: 5 });+ });++ test("the setting picks one backend; native turns the box off; the server's allowlist skips the rest", async () => {+ const home = tmp();+ const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };+ const { run, calls } = linuxRun(BWRAP_OK);+ const asked = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, asked: "podman", wsl: false });+ expect(asked).toMatchObject({ ok: true, backend: "podman" });+ if (asked.ok) expect(asked.why).toMatch(/chosen in Settings/);+ expect(calls.some((c) => c.startsWith("boxrun"))).toBe(false);+ const native = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: () => true, run, fresh: true, asked: "native" });+ expect(native).toMatchObject({ ok: false, native: true });+ const unknown = await detectBackend({ boxHome: home, platform: "linux", home, env, run, fresh: true, asked: "lxc" });+ expect(unknown.ok ? "" : unknown.reason).toMatch(/unknown sandbox backend "lxc"/);+ const allowed = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, all: true, allow: ["podman", "docker"], wsl: false });+ expect(allowed).toMatchObject({ ok: true, backend: "podman" });+ expect(allowed.alternatives?.find((a) => a.backend === "bwrap")?.reason).toBe("not allowed by the server");+ });++ test("the backend setting and the server's allowlist are remembered", () => {+ const state = tmp();+ expect(readBackend(state)).toBe("auto");+ expect(saveBackend(state, "Bubblewrap")).toBe("bwrap");+ expect(askedBackend({ env: {}, stateDir: state })).toEqual({ backend: "bwrap", source: "setting" });+ expect(askedBackend({ env: { OMNIRUSH_BOX_BACKEND: "docker" }, stateDir: state })).toEqual({ backend: "docker", source: "env" });+ expect(() => saveBackend(state, "nope")).toThrow();+ expect(JSON.parse(readFileSync(path.join(state, "box.json"), "utf8"))).toEqual({ backend: "bwrap" });+ expect(rememberServerDefault(state, { local_box: { default: "offer", backends: ["bwrap", "docker", 3] } })).toBe(true);+ expect(serverBackends(state)).toEqual(["bwrap", "docker"]);+ expect(rememberServerDefault(state, { local_box: { default: "offer", backends: ["bwrap", "docker"] } })).toBe(false);+ rememberServerDefault(state, { local_box: { default: "off" } });+ expect(serverBackends(state)).toBeNull();+ });++ test("bwrap box start: the project at its path, the run folder, boxd on loopback with a port file, nothing of $HOME", () => {+ const args = upArgs({ box: "/h/.omnirush/box/bwrap/boxes/k", store: "/h/.omnirush/box/bwrap/store", image: "abc-amd64", boxd: "/pkg/boxd", portFile: "/h/.omnirush/box/projects/k/boxd.port", root: "/home/u/proj", croot: "/home/u/proj", runFolder: "/h/.omnirush/box/projects/k", pkglog: { root: "/h/.omnirush/pkglog" }, token: "t0k", idleMinutes: 90 });+ const binds = args.flatMap((a, i) => (a === "--bind" || a === "--ro-bind" ? [args[i + 1]] : []));+ expect(binds).toEqual(["/home/u/proj=/home/u/proj", "/h/.omnirush/box/projects/k=/run/omnirush", "/h/.omnirush/pkglog=/h/.omnirush/pkglog"]);+ const env = args.flatMap((a, i) => (a === "--env" ? [args[i + 1]] : []));+ expect(env).toContain("BOXD_LISTEN=127.0.0.1:0");+ expect(env).toContain("BOXD_PORT_FILE=/run/omnirush/boxd.port");+ expect(env).toContain("BOXD_IDLE_EXIT=90");+ expect(env).toContain("BOXD_TOKEN=t0k");+ expect(binds.some((b) => b?.startsWith("/h=") || b?.includes(".ssh"))).toBe(false);+ expect(boxdEnv({ token: "x", croot: "/c" }).filter((kv) => kv.startsWith("BOXD_UID") || kv.startsWith("BOXD_HOME"))).toEqual(["BOXD_UID=0", "BOXD_HOME=/root"]);+ });++ test("the AppArmor profile the CLI installs covers OmniRush's own bwrap only (userns), never the sysctl", () => {+ const profile = apparmorProfile("/usr/local/lib/omnirush/bwrap");+ expect(profile).toMatch(/profile omnirush-bwrap \/usr\/local\/lib\/omnirush\/bwrap flags=\(unconfined\) \{\n userns,/);+ expect(/sysctl|apparmor_restrict/.test(profile.replace(/^#.*$/gm, ""))).toBe(false);+ });+});++// --- macOS: Apple container -----------------------------------------------------------------++const APPLE_BIN = "/usr/local/bin/container";+const appleVersions = [{ appName: "container", version: "1.5.0", buildType: "release", commit: "abc" }, { appName: "container-apiserver", version: "1.5.0", buildType: "release", commit: "abc" }];++describe("box backends: macOS", () => {+ test("Apple container: macOS 26 on Apple silicon, the 1.x line, its service running", async () => {+ expect(macosMajor("25.0.0")).toBe(26);+ expect(macosMajor("24.6.0")).toBe(25);+ expect(parseVersions(JSON.stringify(appleVersions))).toEqual({ version: "1.5.0", server: "1.5.0" });+ expect(parseVersions("container CLI version 0.5.0 (build: release, commit: 1234)").version).toBe("0.5.0");+ const base = { platform: "darwin" as const, arch: "arm64", release: "25.1.0", env: { PATH: "/usr/bin" }, exists: set(APPLE_BIN) };+ const good: RunCommand = async (_bin, args) => (args[1] === "version" ? ok(appleVersions) : ok("apiserver is running"));+ expect(await probeApple({ ...base, run: good })).toMatchObject({ ok: true, version: "1.5.0", arch: "arm64", vm: true });+ const reason = async (run: RunCommand, extra: Record<string, unknown> = {}) => {+ const r = await probeApple({ ...base, ...extra, run });+ return r.ok ? "" : r.reason;+ };+ expect(await reason(good, { arch: "x64" })).toMatch(/Apple silicon/);+ expect(await reason(good, { release: "24.6.0" })).toMatch(/macOS 26 or later \(this is macOS 25\)/);+ expect(await reason(good, { exists: () => false })).toMatch(/not installed/);+ expect(await reason(async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "0.11.0" }]) : ok("")))).toMatch(/0\.11\.0 is outside the supported 1\.x line/);+ expect((await probeApple({ ...base, run: async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "2.0.0" }]) : ok("")) })).ok).toBe(false);+ expect(await reason(async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "1.4.1" }]) : fail("apiserver is not running and not registered with launchd")))).toMatch(/container system start/);+ expect(versionAtLeast("1.4.1", APPLE.min) && !versionAtLeast("1.4.1", APPLE.below)).toBe(true);+ });++ test("Apple container: create args, list/inspect JSON, image digest", () => {+ const args = createAppleArgs({ name: "omnirush-box-k", key: "k", root: "/Users/sam/proj", croot: "/Users/sam/proj", image: `ghcr.io/omnirush-ai/box-base@sha256:${"a".repeat(64)}`, runFolder: "/Users/sam/.omnirush/box/projects/k", token: "t", port: 50123, env: { OMNIRUSH_BOX_MEMORY: "6G" } });+ expect(args).toContain("type=bind,source=/Users/sam/proj,target=/Users/sam/proj");+ expect(args).toContain("type=bind,source=/Users/sam/.omnirush/box/projects/k/bin,target=/opt/omnirush/bin,readonly");+ expect(args.slice(args.indexOf("-p"), args.indexOf("-p") + 2)).toEqual(["-p", "127.0.0.1:50123:7777"]);+ expect(args[args.indexOf("--memory") + 1]).toBe("6G");+ expect(args[args.indexOf("--entrypoint") + 1]).toBe("/opt/omnirush/bin/boxd");+ expect(args).toContain("--init");+ expect(args).toContain("ai.omnirush.box.port=50123");+ const snap = { configuration: { id: "omnirush-box-k", image: { reference: "ghcr.io/omnirush-ai/box-base:1", descriptor: { digest: `sha256:${"b".repeat(64)}` } }, labels: { "ai.omnirush.box": "1", "ai.omnirush.box.key": "k" } }, status: "running", networks: [{ network: "default", hostname: "omnirush-box-k", ipv4Address: "192.168.64.7/24", ipv4Gateway: "192.168.64.1" }] };+ expect(snapshotInfo(snap)).toMatchObject({ running: true, address: "192.168.64.7", digest: `sha256:${"b".repeat(64)}` });+ expect(snapshotInfo({ ...snap, networks: [{ address: "192.168.64.9/24" }] }).address).toBe("192.168.64.9");+ expect(findDigest([{ name: "x", index: { digest: `sha256:${"c".repeat(64)}` } }])).toBe(`sha256:${"c".repeat(64)}`);+ expect(findDigest({ variants: [{ config: { digest: `sha256:${"d".repeat(64)}` } }] })).toBe(`sha256:${"d".repeat(64)}`);+ });++ test("ranking: Apple container first, then OrbStack, colima, Docker Desktop through docker contexts", async () => {+ const docker = "/usr/local/bin/docker";+ const infos: Record<string, unknown> = { orbstack: { OperatingSystem: "OrbStack", Name: "orbstack", ServerVersion: "27.0", OSType: "linux", Architecture: "aarch64" }, colima: { OperatingSystem: "Ubuntu 24.04", Name: "colima", ServerVersion: "27.1", OSType: "linux" }, "desktop-linux": { OperatingSystem: "Docker Desktop", ServerVersion: "28.0", OSType: "linux" } };+ const contexts = ["desktop-linux", "colima", "default"].map((Name) => JSON.stringify({ Name, DockerEndpoint: `unix:///x/${Name}.sock` })).join("\n");+ const run: RunCommand = async (bin, args) => {+ if (bin === APPLE_BIN) return fail("not installed", 127);+ if (args[0] === "context") return ok(contexts);+ if (args[0] === "--context") return infos[args[1] ?? ""] ? ok(infos[args[1] ?? ""]) : fail("Cannot connect to the Docker daemon");+ return fail("no");+ };+ const home = tmp();+ const found = await detectBackend({ boxHome: home, platform: "darwin", arch: "arm64", release: "24.0.0", home: "/Users/sam", env: { PATH: "/usr/local/bin" }, exists: set(docker), run, fresh: true, all: true });+ expect(found).toMatchObject({ ok: true, backend: "colima", prefix: ["--context", "colima"] });+ expect(found.alternatives?.find((a) => a.backend === "apple")?.reason).toMatch(/macOS 26/);+ expect(found.alternatives?.some((a) => a.backend === "docker-desktop" && a.ok)).toBe(true);+ const none = await detectBackend({ boxHome: home, platform: "darwin", home: "/Users/sam", env: { PATH: "/usr/bin" }, exists: () => false, run, fresh: true });+ expect(none).toMatchObject({ ok: false, hint: "colima" });+ });+});++// --- Windows: the OmniRush WSL distro --------------------------------------------------------++const WSL = "C:\\Windows\\System32\\wsl.exe";+const winEnv = { Path: "C:\\Windows\\System32", SystemRoot: "C:\\Windows", ProgramFiles: "C:\\Program Files", LOCALAPPDATA: "C:\\Users\\sam\\AppData\\Local" };+const utf16 = (text: string) => Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(text, "utf16le")]);++function wslRun({ status = ok("Default Version: 2\r\n"), list = ok(" NAME STATE VERSION\r\n"), version = ok("WSL version: 2.6.1.0\r\nKernel version: 6.6.87.2-1\r\n") }: { status?: RunResult; list?: RunResult; version?: RunResult } = {}): RunCommand {+ return async (_bin, args) => {+ if (args[0] === "--status") return status;+ if (args[0] === "--list") return list;+ if (args[0] === "--version") return version;+ return fail("unexpected");+ };+}++/** A child process with pipes and no process behind it (the WSL keeper's stand-in). */+class FakeChild extends ChildProcess {+ override stdout = new PassThrough();+ override stderr = new PassThrough();+ override stdin = new PassThrough();+}+const fakeChild = () => new FakeChild();++describe("box backends: Windows", () => {+ test("wsl.exe output: UTF-16LE with a BOM or UTF-8, the verbose list with its default marker", () => {+ const list = " NAME STATE VERSION\r\n* Ubuntu-24.04 Running 2\r\n OmniRushBox Stopped 2\r\n Legacy Distro Stopped 1\r\n";+ expect(decodeWsl(utf16(list))).toBe(decodeWsl(Buffer.from(list)));+ expect(parseWslList(utf16(list))).toEqual([+ { name: "Ubuntu-24.04", state: "Running", version: "2", isDefault: true },+ { name: "OmniRushBox", state: "Stopped", version: "2", isDefault: false },+ { name: "Legacy Distro", state: "Stopped", version: "1", isDefault: false },+ ]);+ // What runCommand hands over when it read UTF-16 as UTF-8: NULs between letters.+ expect(decodeWsl("W\u0000S\u0000L\u0000")).toBe("WSL");+ });++ test("distro probe: not enabled is the one-time admin hint (never an install); WSL 1 and unpublished images say so", async () => {+ const reason = (r: Awaited<ReturnType<typeof probeWslDistro>>) => (r.ok ? "" : r.reason);+ const off = await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun({ status: fail(Buffer.from("Windows Subsystem for Linux is not installed. You can install by running 'wsl.exe --install'.", "utf16le").toString("utf8")) }) });+ expect(reason(off)).toBe(ENABLE_HINT);+ expect(ENABLE_HINT).toMatch(/administrator terminal: `wsl --install --no-distribution`, then restart/);+ expect(reason(await probeWslDistro({ platform: "win32", env: winEnv, exists: () => false, run: wslRun() }))).toBe(ENABLE_HINT);+ const v1 = await probeWslDistro({ platform: "win32", env: { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" }, exists: set(WSL), run: wslRun({ list: ok(" NAME STATE VERSION\r\n OmniRushBox Stopped 1\r\n") }) });+ expect(reason(v1)).toMatch(/WSL 1/);+ expect(reason(await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun() }))).toMatch(/not published yet/);+ const ready = await probeWslDistro({ platform: "win32", env: { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" }, exists: set(WSL), run: wslRun() });+ expect(ready).toMatchObject({ ok: true, installed: false, distro: "OmniRushBox", version: "2.6.1.0" });+ const installed = await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun({ list: ok(utf16(" NAME STATE VERSION\r\n OmniRushBox Running 2\r\n").toString("latin1")) }) });+ expect(installed.ok).toBe(true);+ });++ test("distro box: Windows paths bound as /mnt/c into /c, commands as root without a shell", () => {+ expect(inDistro({ distro: "OmniRushBox" }, ["/opt/omnirush/boxrun", "status"])).toEqual(["-d", "OmniRushBox", "-u", "root", "--cd", "/", "--exec", "/opt/omnirush/boxrun", "status"]);+ const wslPath = (p: string) => `/mnt/${p[0]!.toLowerCase()}/${p.slice(3).replace(/\\/g, "/")}`;+ const args = upArgs({ box: "/var/lib/omnirush/boxes/k", store: "/var/lib/omnirush/store", image: "id", boxd: "/opt/omnirush/boxd", portFile: "/mnt/c/Users/Sam/.omnirush/box/projects/k/boxd.port", root: "C:\\Users\\Sam\\proj", croot: "/c/Users/Sam/proj", runFolder: "C:\\Users\\Sam\\.omnirush\\box\\projects\\k", token: "t", platform: "win32", mapPath: wslPath });+ expect(args).toContain("/mnt/c/Users/Sam/proj=/c/Users/Sam/proj");+ expect(args).toContain("/mnt/c/Users/Sam/.omnirush/box/projects/k=/run/omnirush");+ });++ test("keeper: the first JSON line (UTF-16 or not) gives the port; the keeper stays as a child", async () => {+ let spawnedArgs: string[] = [];+ const kept = await startKeeper({ bin: WSL, distro: "OmniRushBox" }, ["up", "--box", "/var/lib/omnirush/boxes/k"], {+ timeoutMs: 2_000,+ spawnImpl: (_bin, args) => {+ spawnedArgs = args;+ const child = fakeChild();+ setTimeout(() => child.stdout.emit("data", utf16('{"ok":true,"reused":false,"pid":41,"port":40123,"launcher":"unshare","overlay":"kernel"}\n')), 5);+ return child;+ },+ });+ expect(kept.ok).toBe(true);+ if (kept.ok) expect(kept.out.port).toBe(40123);+ expect(spawnedArgs.at(-1)).toBe("--foreground");+ const bad = await startKeeper({ bin: WSL, distro: "OmniRushBox" }, ["up"], {+ timeoutMs: 2_000,+ spawnImpl: () => {+ const child = fakeChild();+ setTimeout(() => child.emit("close", 1), 5);+ return child;+ },+ });+ expect(bad.ok).toBe(false);+ });++ const WSLC = "C:\\Program Files\\WSL\\wslc.exe";++ test("wslc: `wslc version` JSON or text; 3.0.1+ only; an older WSL gets the `wsl --update` hint, a missing one the enable hint", async () => {+ expect(parseWslcVersion('{"Client":{"Version":"3.0.1.0"}}')).toBe("3.0.1.0");+ expect(parseWslcVersion(utf16("wslc 3.0.2.0\r\n"))).toBe("3.0.2.0");+ const good = await probeWslc({ platform: "win32", env: winEnv, exists: set(WSLC), run: async () => ok('{"Client":{"Version":"3.0.1.0"}}') });+ expect(good).toMatchObject({ ok: true, version: "3.0.1.0", backend: "wslc", flavor: "wslc" });+ const reason = (r: Awaited<ReturnType<typeof probeWslc>>) => (r.ok ? "" : r.reason);+ expect(reason(await probeWslc({ platform: "win32", env: winEnv, exists: set(WSLC), run: async () => ok('{"Client":{"Version":"2.9.4.0"}}') }))).toMatch(/wsl --update/);+ const oldWsl = await probeWslc({ platform: "win32", env: winEnv, exists: set(WSL), run: async (_bin, args) => (args[0] === "--version" ? ok(utf16("WSL version: 2.6.1.0\r\n").toString("latin1")) : fail("x")) });+ expect(reason(oldWsl)).toBe(`${UPDATE_HINT}; this is WSL 2.6.1.0`);+ expect(reason(await probeWslc({ platform: "win32", env: winEnv, exists: () => false, run: async () => fail("x") }))).toBe(ENABLE_HINT);+ });++ test("wslc: create args take the Windows path as the bind source, publish boxd on loopback, upper-case memory, no --init", () => {+ const args = createWslcArgs({ name: "omnirush-box-k", key: "k", root: "C:\\Users\\Sam\\proj", croot: "/c/Users/Sam/proj", image: "ghcr.io/omnirush-ai/box-base:1", runFolder: "C:\\Users\\Sam\\.omnirush\\box\\projects\\k", token: "t", port: 50999, env: { OMNIRUSH_BOX_MEMORY: "4g" } });+ expect(args.slice(0, 2)).toEqual(["container", "create"]);+ expect(args).toContain("type=bind,source=C:\\Users\\Sam\\proj,target=/c/Users/Sam/proj");+ expect(args).toContain("type=bind,source=C:\\Users\\Sam\\.omnirush\\box\\projects\\k\\bin,target=/opt/omnirush/bin,readonly");+ expect(args).toContain("127.0.0.1:50999:7777");+ expect(args[args.indexOf("-m") + 1]).toBe("4G");+ expect(args).not.toContain("--init");+ expect(args.at(-1)).toBe("ghcr.io/omnirush-ai/box-base:1");+ });++ test("wslc: list JSON (an array or one object per line), labels as a map or docker's string", () => {+ const rows = [{ ID: "abc", Names: "omnirush-box-k", Image: "ghcr.io/omnirush-ai/box-base:1", State: "running", Labels: { "ai.omnirush.box": "1", "ai.omnirush.box.key": "k" }, Size: "57.2MB (virtual 1.1GB)" }];+ expect(parseJsonRows(JSON.stringify(rows))).toEqual(rows);+ expect(parseJsonRows(rows.map((r) => JSON.stringify(r)).join("\n"))).toEqual(rows);+ expect(labelsOf("a=1,b=x=y")).toEqual({ a: "1", b: "x=y" });+ });++ test("ranking: wslc, then the OmniRush distro, then Docker Desktop", async () => {+ const docker = "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe";+ const desktop = { ServerVersion: "27.3.1", OSType: "linux", OperatingSystem: "Docker Desktop" };+ const run: RunCommand = async (bin, args) => {+ if (bin === WSLC) return ok('{"Client":{"Version":"3.0.1.0"}}');+ if (bin === WSL) return wslRun()(bin, args);+ if (args[0] === "context") return ok("");+ return ok(desktop);+ };+ const env = { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" };+ expect(await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSLC, WSL, docker), run, fresh: true })).toMatchObject({ backend: "wslc" });+ const noWslc = await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSL, docker), run, fresh: true, all: true });+ expect(noWslc).toMatchObject({ ok: true, backend: "wsl" });+ expect(noWslc.alternatives?.find((a) => a.backend === "wslc")?.reason).toMatch(/wsl --update/);+ expect(await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSLC, WSL, docker), run, fresh: true, asked: "docker-desktop" })).toMatchObject({ backend: "docker-desktop" });+ });+});++// --- the record, the upload label, the desktop status ----------------------------------------++describe("box backends: record, label, status", () => {+ test("record and label: the backend is named; boxsh gets no exec fallback where there is no exec", () => {+ const home = tmp();+ const runFolder = path.join(home, "projects", "k");+ mkdirSync(runFolder, { recursive: true });+ const run: RunCommand = async () => ok("");+ const box = new Box({ key: "k", name: "omnirush-box-k", root: "/p", croot: "/p", runtime: { name: "bwrap", backend: "bwrap", bin: "/pkg/boxrun", version: "0.9.0", flavor: "overlayfs", rootless: true, arch: "amd64" }, home, runFolder, run, log: () => {}, platform: "linux", env: {} });+ box.connect({ port: 5, token: "t", uid: 0, gid: 0, containerId: "bwrap_k_1", imageId: `sha256:${"e".repeat(64)}` });+ box.writeRecord();+ const rec = JSON.parse(readFileSync(path.join(home, "boxes", "k.json"), "utf8"));+ expect({ backend: rec.backend, runtime: rec.runtime, args: rec.runtime_args }).toEqual({ backend: "bwrap", runtime: "", args: [] });+ mkdirSync(path.join(home, "chains", "k"), { recursive: true });+ writeFileSync(path.join(home, "chains", "k", "image.json"), JSON.stringify({ ref: "ghcr.io/omnirush-ai/box-base:2026.10.1", digest: `sha256:${"f".repeat(64)}`, stack: "base" }));+ const label = box.label();+ expect(label.backend).toBe("bwrap");+ expect(label.image.digest).toBe(`sha256:${"f".repeat(64)}`);+ const docker = new Box({ key: "d", name: "omnirush-box-d", root: "/p", croot: "/p", runtime: { name: "docker", backend: "docker-desktop", bin: "/usr/bin/docker", prefix: ["--context", "desktop-linux"] }, home, runFolder, run, log: () => {}, platform: "linux", env: {} });+ docker.connect({ port: 6, token: "t", uid: 0, gid: 0, containerId: "c", imageId: "i" });+ docker.writeRecord();+ const drec = JSON.parse(readFileSync(path.join(home, "boxes", "d.json"), "utf8"));+ expect({ backend: drec.backend, runtime: drec.runtime, args: drec.runtime_args }).toEqual({ backend: "docker-desktop", runtime: "/usr/bin/docker", args: ["--context", "desktop-linux"] });+ });++ test("files used read a non-container box through its exec (boxsh), not `docker exec`", async () => {+ if (process.platform === "win32") return;+ const dir = tmp();+ const file = path.join(dir, "note.txt");+ writeFileSync(file, "hello");+ const view = sandboxFilesUsed({ container: "omnirush-box-k", manifest: { home: "/root", workspaces: [] }, cwd: dir, hostHome: null, docker: "/nonexistent/docker", exec: { bin: "/bin/sh", args: ["-c", 'exec "$0" "$@"'], env: { OMNIRUSH_BOX_KEY: "k" } } });+ const facts = await view?.view.inspect([file], 1024);+ expect(facts?.get(file)).toMatchObject({ kind: "file", size: 5 });+ });++ test("the settings card's status: the backend, its version and why, the others, the setting and its choices", async () => {+ const stateDir = tmp();+ const home = tmp();+ const root = tmp();+ const workspace: BoxWorkspace = { id: "ws_1", path: root, workspaceType: "local" };+ const settings = new Map<string, { mode: "on" | "off" | null; offered: boolean }>([["ws_1", { mode: "on", offered: true }]]);+ const env = { OMNIRUSH_BOX_HOME: home, OMNIRUSH_BOX_BIN_DIR: tmp(), PATH: "", OMNIRUSH_BOX_RUNTIME: "/nonexistent/docker" };+ const boxes = new BoxService({+ stateDir,+ readSettings: async (id) => settings.get(id) ?? { mode: null, offered: false },+ writeSettings: async () => {},+ workspaces: () => [workspace],+ pluginPath: () => "/plugins/omnirush-box.js",+ env,+ });+ const status = await boxes.status(workspace, { fresh: true });+ expect(status.backendSetting).toMatchObject({ value: "auto", source: "auto" });+ expect(status.backendSetting.choices[0]).toEqual({ id: "auto", label: "Automatic" });+ expect(status.backendSetting.choices.at(-1)?.id).toBe("native");+ expect(status.backend).toMatchObject({ id: null, allowed: null });+ expect(status.backend?.why).toBeTruthy();+ expect(status.backend?.alternatives.every((alt) => typeof alt.id === "string" && typeof alt.ok === "boolean")).toBe(true);+ expect(await boxes.setBackend("native")).toBe("native");+ const native = await boxes.status(workspace, { fresh: true });+ expect(native.backendSetting).toMatchObject({ value: "native", source: "setting" });+ expect(native.state).toBe("unavailable");+ await expect(boxes.setBackend("lxc")).rejects.toThrow(/unknown sandbox backend/);+ rememberServerDefault(stateDir, { local_box: { default: "off", backends: ["podman"] } });+ await boxes.setBackend("auto");+ expect((await boxes.status(workspace, { fresh: true })).backend?.allowed).toEqual(["podman"]);+ });+});diff --git a/apps/server/src/box/box-server.test.ts b/apps/server/src/box/box-server.test.tsindex fc1e586d..bf59dd97 100644--- a/apps/server/src/box/box-server.test.ts+++ b/apps/server/src/box/box-server.test.ts@@ -133,7 +133,7 @@ describe("Linux sandbox through the server", () => {expect(names).toEqual(expect.arrayContaining(["app.py", `__sandbox__/${sessionId}/record.json`, `__sandbox__/${sessionId}/turn-1.json`, `__sandbox__/${sessionId}/turn-1.tar`]));expect(names).not.toContain(`__sandbox__/${sessionId}/.chain.json`);- const label: BoxLabel = { kind: "omnirush-box", box_id: "box_abc", runtime: { name: "docker", flavor: "desktop", version: "27", rootless: false }, image: { ref: "r", digest: null, stack: "base" }, host_os: "darwin", host_arch: "arm64" };+ const label: BoxLabel = { kind: "omnirush-box", box_id: "box_abc", backend: "docker-desktop", runtime: { name: "docker", flavor: "desktop", version: "27", rootless: false }, image: { ref: "r", digest: null, stack: "base" }, host_os: "darwin", host_arch: "arm64" };const environment: UploadEnvironment = { os: "darwin", os_version: "24.0.0", arch: "arm64", app_version: "1", engine_version: "e", harness: { ...BUNDLED_HARNESS }, node_version: "24", shell: "zsh", locale: null, timezone: null, git_version: null };expect(boxEnvironment(environment, label)).toEqual({ os: "linux", host_os: "darwin", host_arch: "arm64", host_os_version: "24.0.0", shell: "bash" });expect(boxEnvironment(environment, null)).toEqual({});diff --git a/apps/server/src/box/box.test.ts b/apps/server/src/box/box.test.tsindex 1458cee1..4be1368b 100644--- a/apps/server/src/box/box.test.ts+++ b/apps/server/src/box/box.test.ts@@ -80,7 +80,8 @@ describe("box runtime", () => {let calls = 0;const run: RunCommand = async () => { calls += 1; return { code: 0, stdout: "{}", stderr: "" }; };const result = await detectRuntime({ boxHome: home, platform: "linux", env: { PATH: "" }, exists: () => false, run, now: 1_000 });- expect(result).toMatchObject({ ok: false, reason: "no container runtime found (install Podman or Docker)" });+ // Linux ranks bubblewrap first: without boxrun it says so, and no container CLI is there either.+ expect(result).toMatchObject({ ok: false, reason: "bwrap: the sandbox helper boxrun is missing from this install" });expect(await detectRuntime({ boxHome: home, platform: "linux", env: { PATH: "" }, exists: () => false, run, now: 2_000 })).toMatchObject({ ok: false, cached: true });expect(calls).toBe(0);});@@ -276,12 +277,16 @@ describe("box on Windows: a WSL engine (detected, never installed)", () => {const winEnv = { Path: "C:\\Windows\\System32", SystemRoot: "C:\\Windows", ProgramFiles: "C:\\Program Files", LOCALAPPDATA: "C:\\Users\\sam\\AppData\\Local" };const has = (...files: string[]) => (file: string) => files.includes(file);- test("Docker Desktop is used when it is there (the WSL engine is not even asked)", async () => {+ test("Docker Desktop is used when WSL is off (the WSL engine is not even asked)", async () => {const asked: string[] = [];- const run: RunCommand = async (bin, args) => { asked.push([bin, ...args].join(" ")); return { code: 0, stdout: JSON.stringify({ ServerVersion: "27.3.1", OSType: "linux", Architecture: "x86_64", OperatingSystem: "Docker Desktop" }), stderr: "" }; };+ const run: RunCommand = async (bin, args) => {+ asked.push([bin, ...args].join(" "));+ if (bin === WSL) return { code: 1, stdout: "", stderr: "Windows Subsystem for Linux is not installed. You can install by running 'wsl.exe --install'." };+ return { code: 0, stdout: JSON.stringify({ ServerVersion: "27.3.1", OSType: "linux", Architecture: "x86_64", OperatingSystem: "Docker Desktop" }), stderr: "" };+ };const found = await detectRuntime({ platform: "win32", home: "C:\\Users\\sam", env: winEnv, exists: has("C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe", WSL), run, fresh: true });- expect(found).toMatchObject({ ok: true, flavor: "desktop" });- expect(asked.some((line) => line.startsWith(WSL))).toBe(false);+ expect(found).toMatchObject({ ok: true, flavor: "desktop", backend: "docker-desktop" });+ expect(asked.some((line) => line.startsWith(`${WSL} -e`))).toBe(false);});test("without Docker Desktop: Docker in the default WSL distro, through wsl.exe", async () => {diff --git a/apps/server/src/box/box.ts b/apps/server/src/box/box.tsindex 3aff65cd..1bc080e9 100644--- a/apps/server/src/box/box.ts+++ b/apps/server/src/box/box.ts@@ -1,339 +1,53 @@-// Ported from the CLI (omnirush-cli src/box/box.js, feat/local-box); keep the-// two in step. Desktop differences, each marked "Desktop:": types; the-// helpers' folder is the desktop's sidecars (setToolsRoot) and there is no-// checkout box/bin fallback beyond OMNIRUSH_BOX_BIN_DIR; the shell link lives-// in <home>/shell-desktop (the CLI's own is <home>/shell); a container-name-// prefix override for test rigs (OMNIRUSH_BOX_CONTAINER_PREFIX).+// Ported from the CLI (omnirush-cli src/box/box.js, feat/local-box-backends);+// keep the two in step. Desktop differences, each marked "Desktop:": types;+// what common.ts lists (the sidecars' helpers, the shell-desktop link, the+// container-name prefix).//-// OmniRush box: one persistent Linux container per project, opt-in. The-// engine, the app and the model calls stay on this machine; the engine's-// shell tool runs in the box (boxsh -> boxd). The project folder is-// bind-mounted at the same path (Windows: /c/Users/...), so the user's-// editor, git and files stay as they are, and chat history stays in the-// engine's one store. Installs live in the container, which survives-// resume, restarts and new sessions until the user resets it.+// OmniRush box: one persistent Linux box per project, opt-in. The engine,+// the app and the model calls stay on this machine; the engine's shell tool+// runs in the box (boxsh -> boxd). The project folder is mounted at the same+// path (Windows: /c/Users/...), so the user's editor, git and files stay as+// they are, and chat history stays in the engine's one store. Installs live+// in the box, which survives resume, restarts and new sessions until the+// user resets it.//-// Each turn's starting environment is a checkpoint of what the container-// changed (`docker diff` against the image, then only what changed since-// the session's previous checkpoint), written where the project archive-// picks it up (<state>/sandbox/snapshots/<session>/turn-N.{json,tar}, the-// same transport the 2.2.3 sandbox used; record schema 2).+// What runs the box is a backend (backends/: bubblewrap, Apple container,+// WSL containers, OmniRush's WSL distro, Docker, Podman and what speaks+// their CLIs), chosen per machine by backends/index.ts. Every backend runs+// the same boxd from the same pinned image, so a box is the same+// environment everywhere.+//+// Each turn's starting environment is a checkpoint of what the box changed+// (boxd's walk against the image index it took at the first start; a+// container's `diff` as the fallback), then only what changed since the+// session's previous checkpoint, written where the project archive picks it+// up (<state>/sandbox/snapshots/<session>/turn-N.{json,tar}, the same+// transport the 2.2.3 sandbox used; record schema 2).import { createHash, randomBytes } from "node:crypto";-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";import os from "node:os";import path from "node:path";import * as client from "./client.js";import type { BoxEndpoint, BoxStat } from "./client.js";+import { DEPS_MAX_BYTES, FILE_MAX_BYTES, HOME_IN_BOX, RECORD_SCHEMA, RUN_DIR, SHIMS_DIR, TAR_MAX_BYTES, boxHome, boxKey, containerName, containerRoot, firstLine, readJson, readRecord, recordFile, runDir, writeJson, type BoxInstallLog, type BoxLog, type BoxRecord, type BoxRuntime } from "./common.js";+import { driverFor } from "./backends/index.js";+import type { ListedBox, SpawnLike } from "./backends/types.js";import { detectStack, imageFor, type BoxImage, type ImagePins } from "./images.js";-import { runCommand, type RunCommand, type RunOptions, type RuntimeInfo } from "./runtime.js";+import { runCommand, type RunCommand } from "./run.js";type Env = NodeJS.ProcessEnv;-export type BoxLog = (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;--export const RECORD_SCHEMA = 2;-export const LABEL = "ai.omnirush.box";-export const BOX_PORT = 7777;-export const RUN_DIR = "/run/omnirush";-export const SHIMS_DIR = "/opt/omnirush/pkglog";-export const HOME_IN_BOX = "/root";-/** One snapshot tar past this is cut (system paths first, then dependency folders). */-export const TAR_MAX_BYTES = 256 * 1024 * 1024;-/** A single file past this is left out of a snapshot (listed with its size). */-export const FILE_MAX_BYTES = 128 * 1024 * 1024;-/** Project dependency folders (node_modules, .venv) go into a turn's snapshot up to this. */-export const DEPS_MAX_BYTES = 128 * 1024 * 1024;--// --- where things are --------------------------------------------------------export function boxHome(env: Env = process.env, home = os.homedir()): string {- return path.resolve(String(env.OMNIRUSH_BOX_HOME || "").trim() || path.join(home, ".omnirush", "box"));-}--/** The canonical form of a project folder (the box key hashes it). */-export function canonicalRoot(root: string, { platform = process.platform, realpath = realpathSync.native }: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {- let resolved = path.resolve(root);- try { resolved = realpath(resolved); } catch { /* keep */ }- return platform === "win32" ? resolved.toLowerCase() : resolved;-}-export function boxKey(root: string, opts: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {- return createHash("sha256").update(canonicalRoot(root, opts)).digest("hex").slice(0, 12);-}--/** Desktop: OMNIRUSH_BOX_CONTAINER_PREFIX renames the containers (test rigs on shared machines). */-export function containerName(key: string, env: Env = process.env): string {- const prefix = String(env.OMNIRUSH_BOX_CONTAINER_PREFIX || "").trim();- return `${/^[a-z0-9][a-z0-9_.-]*$/.test(prefix) ? prefix : "omnirush-box-"}${key}`;-}--/** Where the project folder is inside: the same path; on Windows C:\x\y -> /c/x/y. */-export function containerRoot(root: string, platform: NodeJS.Platform = process.platform): string {- if (platform !== "win32") return root;- const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(root);- if (!match) return `/w/${root.replace(/[\\]+/g, "/").replace(/^\/+/, "")}`;- return `/${match[1]!.toLowerCase()}/${match[2]!.replace(/[\\]+/g, "/")}`.replace(/\/+$/, "") || "/";-}+export { BOX_PORT, DEPS_MAX_BYTES, FILE_MAX_BYTES, GOARCH, GOOS, HOME_IN_BOX, LABEL, RECORD_SCHEMA, RUN_DIR, SHIMS_DIR, TAR_MAX_BYTES, boxHome, boxKey, canonicalRoot, containerName, containerRoot, helperDirs, helperPath, installShell, readRecord, recordFile, runDir, setToolsRoot, wslPath, type BoxInstallLog, type BoxLog, type BoxRecord, type BoxRuntime } from "./common.js";+export { commandUser, createArgs, inspectImage, parseSize, pullImage, resourceArgs, rt, singleFileTar } from "./backends/container.js";+export type { ListedBox } from "./backends/types.js";/** Where the server saves each chat's turn checkpoints (the project archive carries them: session-archive/index.ts). */export function boxSnapshotsDir(stateDir: string): string {return path.join(stateDir, "sandbox", "snapshots");}-export function recordFile(home: string, key: string): string {- return path.join(home, "boxes", `${key}.json`);-}--export function runDir(home: string, key: string): string {- return path.join(home, "projects", key);-}--function writeJson(file: string, value: unknown, mode = 0o600): void {- mkdirSync(path.dirname(file), { recursive: true });- const tmp = `${file}.${process.pid}.${randomBytes(3).toString("hex")}.tmp`;- writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode });- renameSync(tmp, file);-}--function readJson<T = Record<string, unknown>>(file: string): T | null {- try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }-}--/** The record boxsh reads (boxes/<key>.json). */-export type BoxRecord = {- v: 1; key: string; root: string; croot: string; container: string; runtime: string; runtime_args: string[];- host: string; port: number; token: string; state: string; error: string; uid: number; gid: number;- home: string; shell: string; path_prefix: string; env_file: string; updated: number; pid: number;-};--export function readRecord(home: string, key: string): BoxRecord | null {- return readJson<BoxRecord>(recordFile(home, key));-}--// --- helper binaries -----------------------------------------------------------export const GOOS: Partial<Record<string, string>> = { linux: "linux", darwin: "darwin", win32: "windows" };-export const GOARCH: Partial<Record<string, string>> = { x64: "amd64", arm64: "arm64", amd64: "amd64", aarch64: "arm64" };--/**- * Folders holding the helpers, best first: OMNIRUSH_BOX_BIN_DIR, then the- * desktop's sidecars folder's box/ (setToolsRoot). Each has- * <goos>-<goarch>/boxsh and linux-<arch>/boxd.- */-export function helperDirs({ env = process.env, toolsRoot = null }: { env?: Env; toolsRoot?: string | null } = {}): string[] {- const asked = String(env.OMNIRUSH_BOX_BIN_DIR || "").trim();- return [...(asked ? [asked] : []), ...(toolsRoot ? [path.join(toolsRoot, "box")] : [])];-}--// Desktop: the sidecars folder (the engine binary's folder), set by the server at start.-let platformTools: string | null = null;-export function setToolsRoot(dir: string | null | undefined): void {- platformTools = dir || null;-}--/** The helper's file, or null when no folder has it (the box is then unavailable). */-export function helperPath(name: string, { goos, goarch, env = process.env, toolsRoot = platformTools }: { goos: string | undefined; goarch: string | undefined; env?: Env; toolsRoot?: string | null }): string | null {- if (!goos || !goarch) return null;- const ext = goos === "windows" && name === "boxsh" ? ".exe" : "";- const rel = path.join(`${goos}-${goarch}`, name + ext);- return helperDirs({ env, toolsRoot }).map((dir) => path.join(dir, rel)).find((file) => existsSync(file)) ?? null;-}--/**- * The shell file the engine is given: a link (Windows: a copy) named `bash`- * to boxsh, so the engine describes its shell tool as bash.- */-export function installShell(home: string, { platform = process.platform, arch = process.arch, env = process.env }: { platform?: NodeJS.Platform; arch?: string; env?: Env } = {}): string {- const source = helperPath("boxsh", { goos: GOOS[platform], goarch: GOARCH[arch], env });- if (!source) throw new Error(`the sandbox shell helper is missing (${GOOS[platform] ?? platform}-${GOARCH[arch] ?? arch}/boxsh)`);- const dir = path.join(home, "shell-desktop");- mkdirSync(dir, { recursive: true });- const target = path.join(dir, platform === "win32" ? "bash.exe" : "bash");- if (platform === "win32") {- let same = false;- try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }- if (!same) {- const tmp = `${target}.${process.pid}.tmp`;- copyFileSync(source, tmp);- try { renameSync(tmp, target); } catch { rmSync(tmp, { force: true }); }- }- return target;- }- let current: string | null = null;- try { current = lstatSync(target).isSymbolicLink() ? path.resolve(dir, readlinkSync(target)) : null; } catch { /* missing */ }- if (current !== source) {- const tmp = `${target}.${process.pid}.tmp`;- rmSync(tmp, { force: true });- symlinkSync(source, tmp);- renameSync(tmp, target);- }- return target;-}--/**- * A tar with one executable file at `name` (and its folders), for `cp - <c>:/`:- * `cp <file> <c>:<path>` needs the folder to exist in the image already.- */-export function singleFileTar(name: string, data: Buffer, mode = 0o755): Buffer {- const blocks: Buffer[] = [];- const header = (entry: string, type: string, size: number, entryMode: number) => {- const h = Buffer.alloc(512);- h.write(entry, 0, 100, "utf8");- h.write(`${entryMode.toString(8).padStart(7, "0")}\0`, 100);- h.write("0000000\0", 108);- h.write("0000000\0", 116);- h.write(`${size.toString(8).padStart(11, "0")}\0`, 124);- h.write(`${Math.floor(Date.now() / 1000).toString(8).padStart(11, "0")}\0`, 136);- h.write(" ", 148);- h.write(type, 156);- h.write("ustar\0", 257);- h.write("00", 263);- let sum = 0;- for (const byte of h) sum += byte;- h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);- return h;- };- const parts = name.split("/");- for (let i = 1; i < parts.length; i += 1) blocks.push(header(`${parts.slice(0, i).join("/")}/`, "5", 0, 0o755));- blocks.push(header(name, "0", data.length, mode));- blocks.push(data, Buffer.alloc((512 - (data.length % 512)) % 512), Buffer.alloc(1024));- return Buffer.concat(blocks);-}--// --- the runtime CLI --------------------------------------------------------------export type BoxRuntime = Pick<RuntimeInfo, "name" | "bin"> & Partial<Pick<RuntimeInfo, "version" | "flavor" | "rootless" | "arch" | "vm" | "prefix" | "wsl">>;--/** Runs the runtime's CLI (`wsl.exe -e docker ...` for a WSL engine). */-export function rt(runtime: BoxRuntime, run: RunCommand = runCommand) {- const prefix = Array.isArray(runtime.prefix) ? runtime.prefix : [];- return (args: string[], opts: RunOptions = {}) => run(runtime.bin, [...prefix, ...args], { timeoutMs: 60_000, ...opts });-}--/** A Windows path as a WSL engine mounts it: C:\x\y -> /mnt/c/x/y. */-export function wslPath(p: string): string {- const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(String(p));- if (!match) return String(p).replace(/\\/g, "/");- return `/mnt/${match[1]!.toLowerCase()}/${match[2]!.replace(/\\/g, "/")}`.replace(/\/+$/, "");-}--/** Where the runtime finds a folder of this machine (a WSL engine sees Windows drives under /mnt). */-function source(runtime: BoxRuntime, p: string): string {- return runtime.wsl ? wslPath(p) : p;-}--/** Whether `image` is present locally; its id and repo digest when it is. */-export async function inspectImage(runtime: BoxRuntime, image: string, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ id: string; digest: string | null; arch: string; size: number } | null> {- const res = await rt(runtime, run)(["image", "inspect", image, "--format", "{{json .}}"], { timeoutMs: 20_000 });- if (res.code !== 0) return null;- try {- const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");- const digests: unknown[] = Array.isArray(info.RepoDigests) ? info.RepoDigests : [];- const digest = digests.map((entry) => String(entry).split("@")[1]).find((d) => /^sha256:[0-9a-f]{64}$/.test(d || "")) || null;- return { id: String(info.Id || ""), digest, arch: String(info.Architecture || ""), size: Number(info.Size || 0) };- } catch {- return null;- }-}--/** `pull` with retries (a flaky link picks up where it stopped). */-export async function pullImage(runtime: BoxRuntime, image: string, { run = runCommand, pauses = [2_000, 8_000], timeoutMs = 60 * 60_000, sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)) }: { run?: RunCommand; pauses?: number[]; timeoutMs?: number; sleep?: (ms: number) => Promise<unknown> } = {}): Promise<{ ok: true; attempts: number } | { ok: false; error: string }> {- let last = null;- for (let attempt = 0; attempt <= pauses.length; attempt += 1) {- last = await rt(runtime, run)(["pull", image], { timeoutMs });- if (last.code === 0) return { ok: true, attempts: attempt + 1 };- if (attempt < pauses.length) await sleep(pauses[attempt]!);- }- const said = String(last?.stderr || "").split(/\r?\n/).map((line) => line.trim()).find(Boolean) || `pull exited with ${last?.code}`;- return { ok: false, error: said.slice(0, 300) };-}--type ContainerInfo = { id: string; running: boolean; image: string; labels: Record<string, string>; env: string[]; mounts: string[] };--async function inspectContainer(runtime: BoxRuntime, name: string, run: RunCommand): Promise<ContainerInfo | null> {- const res = await rt(runtime, run)(["container", "inspect", name, "--format", "{{json .}}"], { timeoutMs: 20_000 });- if (res.code !== 0) return null;- try {- const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");- return {- id: String(info.Id || ""),- running: Boolean(info.State?.Running),- image: String(info.Image || ""),- labels: info.Config?.Labels ?? {},- env: Array.isArray(info.Config?.Env) ? info.Config.Env : [],- mounts: Array.isArray(info.Mounts) ? info.Mounts.map((mount: { Destination?: unknown }) => String(mount.Destination ?? "")) : [],- };- } catch {- return null;- }-}--/** The host port boxd is published on. */-async function publishedPort(runtime: BoxRuntime, name: string, run: RunCommand): Promise<number | null> {- const res = await rt(runtime, run)(["port", name, `${BOX_PORT}/tcp`], { timeoutMs: 15_000 });- if (res.code !== 0) return null;- for (const line of res.stdout.split("\n")) {- const match = /:(\d+)\s*$/.exec(line.trim());- if (match) return Number(match[1]);- }- return null;-}--/** Resource limits a new box gets (a VM runtime has its own; only the process cap then). */-export function resourceArgs({ runtime, env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { runtime: BoxRuntime; env?: Env; cpus?: number; memory?: number }): string[] {- const args = ["--pids-limit", String(Number(env.OMNIRUSH_BOX_PIDS) || 4096)];- const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);- const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();- if (askedCpus > 0) args.push("--cpus", String(askedCpus));- else if (!runtime.vm) args.push("--cpus", String(Math.max(1, Math.min(8, cpus - 1))));- if (askedMem) args.push("--memory", askedMem);- else if (!runtime.vm) {- const gib = Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)));- args.push("--memory", `${gib}g`);- }- return args;-}--/** Who commands run as: root where root maps to the user (rootless, VMs), else the user's own uid. */-export function commandUser(runtime: BoxRuntime, { platform = process.platform, uid = process.getuid?.(), gid = process.getgid?.() }: { platform?: NodeJS.Platform; uid?: number; gid?: number } = {}): { uid: number; gid: number } {- if (platform !== "linux" || runtime.rootless || runtime.vm || uid === undefined || gid === undefined || uid === 0) return { uid: 0, gid: 0 };- return { uid, gid };-}--/**- * Create a box container (not started): the project folder at `croot`, the- * launcher's run folder at /run/omnirush, the package-manager wrappers (when- * there are) read-only, boxd published on this machine's loopback only.- * Nothing else of this machine goes in: no home folder, no credentials, no- * docker socket.- */-/** The install log (phase 1): its folder, the wrappers' folder and the pip hook's, all on this machine. */-export type BoxInstallLog = { root: string; bin: string; py: string };--export function createArgs({ name, key, root, croot, image, runtime, run: runFolder, shims, pkglog = null, token, user, env = process.env, platform = process.platform }: { name: string; key: string; root: string; croot: string; image: string; runtime: BoxRuntime; run: string; shims: string | null; pkglog?: BoxInstallLog | null; token: string; user: { uid: number; gid: number }; env?: Env; platform?: NodeJS.Platform }): string[] {- return [- "create", "--name", name, "--hostname", "omnirush-box", "--init",- "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`,- "--mount", `type=bind,source=${source(runtime, root)},target=${croot}`,- "--mount", `type=bind,source=${source(runtime, runFolder)},target=${RUN_DIR}`,- ...(shims ? ["--mount", `type=bind,source=${source(runtime, shims)},target=${SHIMS_DIR}-src,readonly`] : []),- // The install log's folder (phase 1: its wrappers, pip hook and the per-run folders the- // wrappers note calls in), at the path the launcher reads it at.- ...(pkglog ? ["--mount", `type=bind,source=${source(runtime, pkglog.root)},target=${containerRoot(pkglog.root, platform)}`] : []),- "-p", `127.0.0.1::${BOX_PORT}`,- "-e", `BOXD_TOKEN=${token}`, "-e", `BOXD_UID=${user.uid}`, "-e", `BOXD_GID=${user.gid}`,- "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,- "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",- "-w", croot,- ...resourceArgs({ runtime, env }),- ...(runtime.name === "podman" ? ["--security-opt", "label=disable"] : []),- ...(user.uid === 0 ? ["--security-opt", "no-new-privileges"] : []),- "--entrypoint", "/opt/omnirush/bin/boxd",- image,- ];-}-// --- snapshot rules -------------------------------------------------------------const H = HOME_IN_BOX;@@ -478,12 +192,12 @@ export type BoxState = "starting" | "pulling" | "ready" | "failed";type OnState = (state: BoxState, error: string | null) => void;/**- * Open (create or start) the project's box. Returns a Box. `onState` sees- * "starting", "pulling", "ready", "failed" (the record boxsh reads says the- * same). Throws only for programming errors; a box that cannot start is a- * Box with state "failed" and `error`.+ * Open (create or start) the project's box with the runtime's backend.+ * Returns a Box. `onState` sees "starting", "pulling", "ready", "failed"+ * (the record boxsh reads says the same). Throws only for programming+ * errors; a box that cannot start is a Box with state "failed" and `error`.*/-export async function openBox({ root, runtime, env = process.env, platform = process.platform, home = boxHome(env), run = runCommand, log = () => {}, shims = null, pkglog = null, pull = true, image: asked = null, onState = () => {} }: { root: string; runtime: BoxRuntime; env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand; log?: BoxLog; shims?: string | null; pkglog?: BoxInstallLog | null; pull?: boolean; image?: BoxImage | null; onState?: OnState }): Promise<Box> {+export async function openBox({ root, runtime, env = process.env, platform = process.platform, home = boxHome(env), run = runCommand, log = () => {}, shims = null, pkglog = null, pull = true, image: asked = null, onState = () => {}, spawnImpl, readyMs = 15_000 }: { root: string; runtime: BoxRuntime; env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand; log?: BoxLog; shims?: string | null; pkglog?: BoxInstallLog | null; pull?: boolean; image?: BoxImage | null; onState?: OnState; spawnImpl?: SpawnLike; readyMs?: number }): Promise<Box> {const projectRoot = path.resolve(root);const key = boxKey(projectRoot, { platform });const name = containerName(key, env);@@ -491,63 +205,31 @@ export async function openBox({ root, runtime, env = process.env, platform = proconst runFolder = runDir(home, key);mkdirSync(path.join(runFolder, "state"), { recursive: true });const box = new Box({ key, name, root: projectRoot, croot, runtime, home, runFolder, run, log, platform, env });+ const driver = driverFor(runtime);const lock = await acquireLock(home, key);try {box.setState("starting", null, onState);- let info = await inspectContainer(runtime, name, run);- if (info && info.labels?.[`${LABEL}.root`] && info.labels[`${LABEL}.root`] !== projectRoot) {- throw new Error(`container ${name} belongs to another folder`);- }- if (!info) {- const chosen = asked ?? imageFor(detectStack(projectRoot), { env });- let present = await inspectImage(runtime, chosen.pull, { run });- if (!present) {- if (!pull) return box.fail("the sandbox image is not downloaded yet", onState);- box.setState("pulling", null, onState);- const pulled = await pullImage(runtime, chosen.pull, { run });- if (!pulled.ok) return box.fail(`could not download the sandbox image: ${pulled.error}`, onState);- present = await inspectImage(runtime, chosen.pull, { run });- if (!present) return box.fail("the sandbox image is not there after the download", onState);- }- const goarch = GOARCH[present.arch] || GOARCH[runtime.arch ?? ""] || "amd64";- const boxd = helperPath("boxd", { goos: "linux", goarch, env });- if (!boxd) return box.fail(`the sandbox helper is missing (linux-${goarch}/boxd)`, onState);- const token = randomBytes(24).toString("hex");- const user = commandUser(runtime, { platform });- const created = await rt(runtime, run)(createArgs({ name, key, root: projectRoot, croot, image: chosen.pull, runtime, run: runFolder, shims, pkglog, token, user, env, platform }), { timeoutMs: 120_000 });- if (created.code !== 0) return box.fail(`could not create the sandbox: ${firstLine(created.stderr)}`, onState);- const copied = await rt(runtime, run)(["cp", "-", `${name}:/`], { timeoutMs: 60_000, input: singleFileTar("opt/omnirush/bin/boxd", readFileSync(boxd)) });- if (copied.code !== 0) {- await rt(runtime, run)(["rm", "-f", name], { timeoutMs: 30_000 });- return box.fail(`could not copy the sandbox helper in: ${firstLine(copied.stderr)}`, onState);- }- writeJson(path.join(home, "chains", key, "image.json"), { ref: chosen.ref, pull: chosen.pull, digest: chosen.digest || present.digest, id: present.id, stack: chosen.stack, created_at: new Date().toISOString() });- info = await inspectContainer(runtime, name, run);- if (!info) return box.fail("the sandbox was not there after it was created", onState);- log("info", "box created", { key, image: chosen.pull, stack: chosen.stack });- }- if (!info.running) {- const started = await rt(runtime, run)(["start", name], { timeoutMs: 60_000 });- if (started.code !== 0) return box.fail(`could not start the sandbox: ${firstLine(started.stderr)}`, onState);- }- const token = (info.env.find((kv) => kv.startsWith("BOXD_TOKEN=")) || "").slice("BOXD_TOKEN=".length);- const uid = Number((info.env.find((kv) => kv.startsWith("BOXD_UID=")) || "BOXD_UID=0").slice(9));- const gid = Number((info.env.find((kv) => kv.startsWith("BOXD_GID=")) || "BOXD_GID=0").slice(9));- const port = await publishedPort(runtime, name, run);- if (!port || !token) return box.fail("the sandbox started without its port", onState);- box.connect({ port, token, uid, gid, containerId: info.id, imageId: info.image });- const endpoint = box.endpoint!;- const deadline = Date.now() + 15_000;+ const chosen = asked ?? imageFor(detectStack(projectRoot), { env });+ const opened = await driver.open({ key, name, root: projectRoot, croot, runtime, run, home, runFolder, image: chosen, pull, shims, pkglog, env, platform, log, ...(spawnImpl ? { spawnImpl } : {}), onPulling: () => box.setState("pulling", null, onState) });+ if (!opened.ok) return box.fail(opened.error, onState);+ if (opened.created) writeJson(path.join(home, "chains", key, "image.json"), { ...opened.created, backend: runtime.backend ?? runtime.name, created_at: new Date().toISOString() });+ // The first address that answers: the published/loopback one, then the box's own (Apple, WSL any).+ const ways = [opened.endpoint, ...(opened.alternates ?? [])];let identity = null;- while (!identity && Date.now() < deadline) {- identity = await client.ping(endpoint, { timeoutMs: 1_000 });- if (!identity) await new Promise((resolve) => setTimeout(resolve, 100));+ for (let i = 0; i < ways.length && !identity; i += 1) {+ box.connect({ ...ways[i]!, uid: opened.uid, gid: opened.gid, containerId: opened.containerId, imageId: opened.imageId });+ const endpoint = box.endpoint!;+ const deadline = Date.now() + (i === ways.length - 1 ? readyMs : Math.min(readyMs, 5_000));+ while (!identity && Date.now() < deadline) {+ identity = await client.ping(endpoint, { timeoutMs: 1_000 });+ if (!identity) await new Promise((resolve) => setTimeout(resolve, 50));+ }}if (!identity) return box.fail("the sandbox helper did not answer", onState);box.identity = identity;if (shims) await box.installShims().catch((error) => log("warn", "box wrappers not installed", { error: String(error?.message || error) }));else if (pkglog) {- if (info.mounts.includes(containerRoot(pkglog.root, platform))) box.useInstallLog(pkglog);+ if (opened.mounts.includes(containerRoot(pkglog.root, platform))) box.useInstallLog(pkglog);else log("info", "box made before the install log: its wrappers are not in this box (Reset sandbox adds them)", { key });}box.setState("ready", null, onState);@@ -559,10 +241,6 @@ export async function openBox({ root, runtime, env = process.env, platform = pro}}-function firstLine(text: unknown): string {- return String(text ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean)?.slice(0, 300) ?? "";-}-async function acquireLock(home: string, key: string, { waitMs = 60_000 }: { waitMs?: number } = {}): Promise<{ release: () => void }> {const file = path.join(home, "locks", `${key}.lock`);mkdirSync(path.dirname(file), { recursive: true });@@ -615,6 +293,8 @@ type Chain = { container: string; last: string | null; signatures: Record<stringexport type BoxLabel = {kind: string;box_id: string;+ /** The backend id (backends/index.ts BACKENDS). */+ backend: string;runtime: { name: string; flavor: string; version: string | null; rootless: boolean };image: { ref: string | null; digest: string | null; stack: string | null };host_os: string;@@ -662,8 +342,8 @@ export class Box {this.container = name;}- connect({ port, token, uid, gid, containerId, imageId }: { port: number; token: string; uid: number; gid: number; containerId: string; imageId: string }): void {- this.endpoint = { host: "127.0.0.1", port, token };+ connect({ host = "127.0.0.1", port, token, uid, gid, containerId, imageId }: BoxEndpoint & { uid: number; gid: number; containerId: string; imageId: string }): void {+ this.endpoint = { host, port, token };this.uid = uid;this.gid = gid;this.containerId = containerId;@@ -672,8 +352,11 @@ export class Box {/** The record boxsh reads (boxes/<key>.json). */writeRecord(): void {+ const fallback = driverFor(this.runtime).execFallback;const record: BoxRecord = {- v: 1, key: this.key, root: this.root, croot: this.croot, container: this.name, runtime: this.runtime?.bin ?? "", runtime_args: this.runtime?.prefix ?? [],+ v: 1, key: this.key, root: this.root, croot: this.croot, container: this.name, backend: this.runtime.backend ?? this.runtime.name ?? "",+ // boxsh's fallback when boxd does not answer: `<runtime> exec` (container engines and wslc only).+ runtime: fallback ? this.runtime.bin ?? "" : "", runtime_args: fallback ? this.runtime.prefix ?? [] : [],host: this.endpoint?.host ?? "127.0.0.1", port: this.endpoint?.port ?? 0, token: this.endpoint?.token ?? "",state: this.state, error: this.error ?? "", uid: this.uid ?? 0, gid: this.gid ?? 0, home: HOME_IN_BOX, shell: "/bin/bash",path_prefix: this.pathPrefix, env_file: `${RUN_DIR}/env`, updated: Date.now(), pid: process.pid,@@ -754,6 +437,7 @@ export class Box {schema: RECORD_SCHEMA,kind: "omnirush-box",box: { id: `box_${this.key}`, container: this.name, created_at: image.created_at ?? null },+ backend: this.runtime.backend ?? this.runtime.name,runtime: { name: this.runtime.name, version: this.runtime.version ?? null, flavor: this.runtime.flavor ?? "unknown", rootless: Boolean(this.runtime.rootless), os: "linux", arch: this.runtime.arch || null },image: { ref: image.ref ?? null, digest: image.digest ?? null, id: image.id ?? this.imageId ?? null, stack: image.stack ?? null },host: { os: this.platform, arch: process.arch, os_version: os.release() },@@ -767,7 +451,7 @@ export class Box {/** The block trace envelopes carry as environment.sandbox. */label(): BoxLabel {const d = this.describe();- return { kind: d.kind, box_id: d.box.id, runtime: { name: d.runtime.name, flavor: d.runtime.flavor, version: d.runtime.version, rootless: d.runtime.rootless }, image: { ref: d.image.ref, digest: d.image.digest, stack: d.image.stack }, host_os: d.host.os, host_arch: d.host.arch };+ return { kind: d.kind, box_id: d.box.id, backend: d.backend, runtime: { name: d.runtime.name, flavor: d.runtime.flavor, version: d.runtime.version, rootless: d.runtime.rootless }, image: { ref: d.image.ref, digest: d.image.digest, stack: d.image.stack }, host_os: d.host.os, host_arch: d.host.arch };}/** Run a command in the box (toolchain probes, status). */@@ -812,7 +496,9 @@ export class Box {stats = walked.filter((entry) => entry.kind !== "D" && keptPaths.has(entry.path));} else {source = "diff";- const diff = await rt(this.runtime, this.run)(["diff", this.name], { timeoutMs: 120_000, maxBytes: 256 << 20 });+ const driver = driverFor(this.runtime);+ if (!driver.diff) throw new Error("the sandbox helper could not list the changes");+ const diff = await driver.diff(this.runtime, this.key, { run: this.run, home: this.home, env: this.env });if (diff.code !== 0) throw new Error(`diff failed: ${firstLine(diff.stderr)}`);entries = filterChanges(parseDiff(diff.stdout), { mounts });const present = entries.filter((entry) => entry.kind !== "D").map((entry) => entry.path);@@ -928,83 +614,61 @@ export class Box {};}- /** Disk the container's own layer uses (bytes), when the runtime says. */- async upperBytes(): Promise<number | null> {- const res = await rt(this.runtime, this.run)(["ps", "-a", "-s", "--filter", `name=^/?${this.name}$`, "--format", "{{.Size}}"], { timeoutMs: 30_000 });- return parseSize(res.stdout);+ /** Disk the box's own layer uses (bytes), when the backend says. */+ upperBytes(): Promise<number | null> {+ return driverFor(this.runtime).upperBytes(this.runtime, this.key, { run: this.run, home: this.home, env: this.env });}}-/** "57.2MB (virtual 1.1GB)" -> bytes of the first number. */-export function parseSize(text: string): number | null {- const match = /([\d.]+)\s*([kKMGT]?i?B)/.exec(String(text));- if (!match) return null;- const unit = match[2]!.replace(/i/, "").toUpperCase();- const mult = ({ B: 1, KB: 1e3, MB: 1e6, GB: 1e9, TB: 1e12 } as Record<string, number>)[unit] ?? 1;- return Math.round(Number(match[1]) * mult);-}-// --- status, reset, gc ---------------------------------------------------------------export type ListedBox = { key: string; name: string; root: string; running: boolean; image: string; created: string };+type Removed = Array<{ kind: string; name: string; reason: string }>;/** Boxes on this machine: { key, name, root, running, image, created }[] */-export async function listBoxes(runtime: BoxRuntime, { run = runCommand }: { run?: RunCommand } = {}): Promise<ListedBox[]> {- const res = await rt(runtime, run)(["ps", "-a", "--filter", `label=${LABEL}=1`, "--format", "{{json .}}"], { timeoutMs: 30_000 });- if (res.code !== 0) return [];- const out: ListedBox[] = [];- for (const line of res.stdout.split("\n")) {- if (!line.trim()) continue;- try {- const row = JSON.parse(line);- const labels: Record<string, string> = typeof row.Labels === "string"- ? Object.fromEntries(row.Labels.split(",").map((kv: string) => { const i = kv.indexOf("="); return [kv.slice(0, i), kv.slice(i + 1)]; }))- : (row.Labels ?? {});- const name = Array.isArray(row.Names) ? row.Names[0] : String(row.Names ?? "");- out.push({ key: labels[`${LABEL}.key`] ?? "", name, root: labels[`${LABEL}.root`] ?? "", running: /^up|running/i.test(String(row.Status ?? row.State ?? "")), image: String(row.Image ?? ""), created: String(row.CreatedAt ?? row.Created ?? "") });- } catch { /* skip */ }- }- return out;+export async function listBoxes(runtime: BoxRuntime, { run = runCommand, env = process.env, home = boxHome(env) }: { run?: RunCommand; env?: Env; home?: string } = {}): Promise<ListedBox[]> {+ return driverFor(runtime).list(runtime, { run, env, home });}/** Remove a project's box (the next start makes a new one). */export async function resetBox(runtime: BoxRuntime, root: string, { env = process.env, platform = process.platform, home = boxHome(env), run = runCommand }: { env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand } = {}): Promise<{ key: string; removed: boolean }> {const key = boxKey(root, { platform });- const res = await rt(runtime, run)(["rm", "-f", containerName(key, env)], { timeoutMs: 60_000 });+ const res = await driverFor(runtime).remove(runtime, key, { run, env, home });rmSync(recordFile(home, key), { force: true });rmSync(path.join(home, "chains", key), { recursive: true, force: true });- return { key, removed: res.code === 0 };+ return { key, removed: Boolean(res.removed) };+}++/** Stop a project's box (its installs stay; the next chat starts it again). */+export async function stopBox(runtime: BoxRuntime, root: string, { env = process.env, platform = process.platform, home = boxHome(env), run = runCommand }: { env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand } = {}): Promise<{ key: string; stopped: boolean }> {+ const key = boxKey(root, { platform });+ return { key, ...(await driverFor(runtime).stop(runtime, key, { run, env, home })) };}/*** Remove boxes whose folder is gone or that were not used for `maxIdleDays`,- * and box images no box uses that are not the current pins. Only containers- * and images labelled/named as OmniRush boxes are touched; nothing is pruned.+ * and box images no box uses that are not the current pins. Only boxes and+ * images labelled/named as OmniRush boxes are touched; nothing is pruned.*/-export async function gcBoxes(runtime: BoxRuntime, { env = process.env, home = boxHome(env), run = runCommand, maxIdleDays = 30, pins = null, now = Date.now(), exists = existsSync }: { env?: Env; home?: string; run?: RunCommand; maxIdleDays?: number; pins?: ImagePins | null; now?: number; exists?: (file: string) => boolean } = {}): Promise<Array<{ kind: string; name: string; reason: string }>> {- const removed: Array<{ kind: string; name: string; reason: string }> = [];- const boxes = await listBoxes(runtime, { run });+export async function gcBoxes(runtime: BoxRuntime, { env = process.env, home = boxHome(env), run = runCommand, maxIdleDays = 30, pins = null, now = Date.now(), exists = existsSync }: { env?: Env; home?: string; run?: RunCommand; maxIdleDays?: number; pins?: ImagePins | null; now?: number; exists?: (file: string) => boolean } = {}): Promise<Removed> {+ const driver = driverFor(runtime);+ const removed: Removed = [];+ const boxes = await driver.list(runtime, { run, env, home });for (const box of boxes) {const rec = readRecord(home, box.key);const idle = rec?.updated ? (now - rec.updated) / 86_400_000 : Infinity;if ((box.root && !exists(box.root)) || idle > maxIdleDays) {- const res = await rt(runtime, run)(["rm", "-f", box.name], { timeoutMs: 60_000 });- if (res.code === 0) {+ const res = await driver.remove(runtime, box.key, { run, env, home });+ if (res.removed) {removed.push({ kind: "container", name: box.name, reason: box.root && !exists(box.root) ? "folder gone" : "unused" });rmSync(recordFile(home, box.key), { force: true });rmSync(path.join(home, "chains", box.key), { recursive: true, force: true });}}}- const images = await rt(runtime, run)(["images", "--format", "{{.Repository}}:{{.Tag}} {{.ID}}"], { timeoutMs: 30_000 });const current = new Set(Object.values(pins?.images ?? {}).map((pin) => pin.ref));- const used = new Set((await listBoxes(runtime, { run })).map((box) => box.image));- for (const line of images.stdout.split("\n")) {- const [ref, id] = line.trim().split(/\s+/);- if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref) || (id && used.has(id))) continue;- const res = await rt(runtime, run)(["rmi", ref], { timeoutMs: 60_000 });- if (res.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });- }+ const used = new Set<string>();+ for (const box of await driver.list(runtime, { run, env, home })) used.add(box.image);+ removed.push(...await driver.gcImages(runtime, { run, env, home, current, used }));return removed;}diff --git a/apps/server/src/box/common.ts b/apps/server/src/box/common.tsnew file mode 100644index 00000000..77ca9427--- /dev/null+++ b/apps/server/src/box/common.ts@@ -0,0 +1,196 @@+// Ported from the CLI (omnirush-cli src/box/common.js,+// feat/local-box-backends); keep the two in step. Desktop differences, each+// marked "Desktop:": types; the helpers' folder is the desktop's sidecars+// (setToolsRoot) and there is no checkout box/bin fallback beyond+// OMNIRUSH_BOX_BIN_DIR (helperPath is null when missing); the shell link+// lives in <home>/shell-desktop (the CLI's own is <home>/shell); a+// container-name prefix override for test rigs (OMNIRUSH_BOX_CONTAINER_PREFIX).+//+// Shared by the box and its backends: where things are, the helper+// binaries, the box record, small file helpers.++import { createHash, randomBytes } from "node:crypto";+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";+import net from "node:net";+import os from "node:os";+import path from "node:path";++import type { RuntimeInfo } from "./runtime.js";++type Env = NodeJS.ProcessEnv;+export type BoxLog = (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;++export const RECORD_SCHEMA = 2;+export const LABEL = "ai.omnirush.box";+export const BOX_PORT = 7777;+export const RUN_DIR = "/run/omnirush";+export const SHIMS_DIR = "/opt/omnirush/pkglog";+export const HOME_IN_BOX = "/root";+/** One snapshot tar past this is cut (system paths first, then dependency folders). */+export const TAR_MAX_BYTES = 256 * 1024 * 1024;+/** A single file past this is left out of a snapshot (listed with its size). */+export const FILE_MAX_BYTES = 128 * 1024 * 1024;+/** Project dependency folders (node_modules, .venv) go into a turn's snapshot up to this. */+export const DEPS_MAX_BYTES = 128 * 1024 * 1024;++/** What runs a box: a probed backend (runtime.ts RuntimeInfo), or the parts of one a caller has. */+export type BoxRuntime = Pick<RuntimeInfo, "name" | "bin"> & Partial<Omit<RuntimeInfo, "ok" | "name" | "bin">>;++/** The install log (phase 1): its folder, the wrappers' folder and the pip hook's, all on this machine. */+export type BoxInstallLog = { root: string; bin: string; py: string };++// --- where things are ------------------------------------------------------++export function boxHome(env: Env = process.env, home = os.homedir()): string {+ return path.resolve(String(env.OMNIRUSH_BOX_HOME || "").trim() || path.join(home, ".omnirush", "box"));+}++/** The canonical form of a project folder (the box key hashes it). */+export function canonicalRoot(root: string, { platform = process.platform, realpath = realpathSync.native }: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {+ let resolved = path.resolve(root);+ try { resolved = realpath(resolved); } catch { /* keep */ }+ return platform === "win32" ? resolved.toLowerCase() : resolved;+}++export function boxKey(root: string, opts: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {+ return createHash("sha256").update(canonicalRoot(root, opts)).digest("hex").slice(0, 12);+}++/** Desktop: OMNIRUSH_BOX_CONTAINER_PREFIX renames the containers (test rigs on shared machines). */+export function containerName(key: string, env: Env = process.env): string {+ const prefix = String(env.OMNIRUSH_BOX_CONTAINER_PREFIX || "").trim();+ return `${/^[a-z0-9][a-z0-9_.-]*$/.test(prefix) ? prefix : "omnirush-box-"}${key}`;+}++/** Where the project folder is inside: the same path; on Windows C:\x\y -> /c/x/y. */+export function containerRoot(root: string, platform: NodeJS.Platform = process.platform): string {+ if (platform !== "win32") return root;+ const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(root);+ if (!match) return `/w/${root.replace(/[\\]+/g, "/").replace(/^\/+/, "")}`;+ return `/${match[1]!.toLowerCase()}/${match[2]!.replace(/[\\]+/g, "/")}`.replace(/\/+$/, "") || "/";+}++export function recordFile(home: string, key: string): string {+ return path.join(home, "boxes", `${key}.json`);+}++export function runDir(home: string, key: string): string {+ return path.join(home, "projects", key);+}++export function writeJson(file: string, value: unknown, mode = 0o600): void {+ mkdirSync(path.dirname(file), { recursive: true });+ const tmp = `${file}.${process.pid}.${randomBytes(3).toString("hex")}.tmp`;+ writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode });+ renameSync(tmp, file);+}++export function readJson<T = Record<string, unknown>>(file: string): T | null {+ try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }+}++/** The record boxsh reads (boxes/<key>.json). `runtime` is empty when the backend has no exec fallback. */+export type BoxRecord = {+ v: 1; key: string; root: string; croot: string; container: string; backend: string; runtime: string; runtime_args: string[];+ host: string; port: number; token: string; state: string; error: string; uid: number; gid: number;+ home: string; shell: string; path_prefix: string; env_file: string; updated: number; pid: number;+};++export function readRecord(home: string, key: string): BoxRecord | null {+ return readJson<BoxRecord>(recordFile(home, key));+}++// --- helper binaries ---------------------------------------------------------++export const GOOS: Partial<Record<string, string>> = { linux: "linux", darwin: "darwin", win32: "windows" };+export const GOARCH: Partial<Record<string, string>> = { x64: "amd64", arm64: "arm64", amd64: "amd64", aarch64: "arm64" };++/**+ * Folders holding the helpers, best first: OMNIRUSH_BOX_BIN_DIR, then the+ * desktop's sidecars folder's box/ (setToolsRoot). Each has+ * <goos>-<goarch>/boxsh, linux-<arch>/boxd and linux-<arch>/boxrun.+ */+export function helperDirs({ env = process.env, toolsRoot = null }: { env?: Env; toolsRoot?: string | null } = {}): string[] {+ const asked = String(env.OMNIRUSH_BOX_BIN_DIR || "").trim();+ return [...(asked ? [asked] : []), ...(toolsRoot ? [path.join(toolsRoot, "box")] : [])];+}++// Desktop: the sidecars folder (the engine binary's folder), set by the server at start.+let platformTools: string | null = null;+export function setToolsRoot(dir: string | null | undefined): void {+ platformTools = dir || null;+}++/** The helper's file, or null when no folder has it (the box is then unavailable). */+export function helperPath(name: string, { goos, goarch, env = process.env, toolsRoot = platformTools }: { goos: string | undefined; goarch: string | undefined; env?: Env; toolsRoot?: string | null }): string | null {+ if (!goos || !goarch) return null;+ const ext = goos === "windows" && name === "boxsh" ? ".exe" : "";+ const rel = path.join(`${goos}-${goarch}`, name + ext);+ return helperDirs({ env, toolsRoot }).map((dir) => path.join(dir, rel)).find((file) => existsSync(file)) ?? null;+}++/**+ * The shell file the engine is given: a link (Windows: a copy) named `bash`+ * to boxsh, so the engine describes its shell tool as bash.+ */+export function installShell(home: string, { platform = process.platform, arch = process.arch, env = process.env }: { platform?: NodeJS.Platform; arch?: string; env?: Env } = {}): string {+ const source = helperPath("boxsh", { goos: GOOS[platform], goarch: GOARCH[arch], env });+ if (!source) throw new Error(`the sandbox shell helper is missing (${GOOS[platform] ?? platform}-${GOARCH[arch] ?? arch}/boxsh)`);+ const dir = shellDir(home);+ mkdirSync(dir, { recursive: true });+ const target = path.join(dir, platform === "win32" ? "bash.exe" : "bash");+ if (platform === "win32") {+ let same = false;+ try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }+ if (!same) {+ const tmp = `${target}.${process.pid}.tmp`;+ copyFileSync(source, tmp);+ try { renameSync(tmp, target); } catch { rmSync(tmp, { force: true }); }+ }+ return target;+ }+ let current: string | null = null;+ try { current = lstatSync(target).isSymbolicLink() ? path.resolve(dir, readlinkSync(target)) : null; } catch { /* missing */ }+ if (current !== source) {+ const tmp = `${target}.${process.pid}.tmp`;+ rmSync(tmp, { force: true });+ symlinkSync(source, tmp);+ renameSync(tmp, target);+ }+ return target;+}++/** Desktop: the shell link's folder (the CLI's is <home>/shell). */+export function shellDir(home: string): string {+ return path.join(home, "shell-desktop");+}++export function firstLine(text: unknown): string {+ return String(text ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean)?.slice(0, 300) ?? "";+}++/** A Windows path as a WSL engine mounts it: C:\x\y -> /mnt/c/x/y. */+export function wslPath(p: string): string {+ const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(String(p));+ if (!match) return String(p).replace(/\\/g, "/");+ return `/mnt/${match[1]!.toLowerCase()}/${match[2]!.replace(/\\/g, "/")}`.replace(/\/+$/, "");+}++/** A free TCP port on this machine's loopback (for a runtime that needs one named). */+export function freePort(): Promise<number> {+ return new Promise((resolve, reject) => {+ const server = net.createServer();+ server.unref();+ server.on("error", reject);+ server.listen(0, "127.0.0.1", () => {+ const address = server.address();+ const port = typeof address === "object" && address ? address.port : 0;+ server.close(() => resolve(port));+ });+ });+}++/** A token for a new box's boxd. */+export function newToken(): string {+ return randomBytes(24).toString("hex");+}diff --git a/apps/server/src/box/launch.ts b/apps/server/src/box/launch.tsindex 52afcfd1..1c5ae2c8 100644--- a/apps/server/src/box/launch.ts+++ b/apps/server/src/box/launch.ts@@ -1,8 +1,12 @@-// Ported from the CLI (omnirush-cli src/box/launch.js, feat/local-box); keep-// the shared parts in step. Desktop differences: the per-project choice lives-// in the workspace's OmniRush settings (service.ts), not box.json; the plan-// is per workspace (one engine serves every project); a run tracks its turns-// per chat; there is no --sandbox flag (OMNIRUSH_BOX=1|0 still overrides).+// Ported from the CLI (omnirush-cli src/box/launch.js,+// feat/local-box-backends); keep the shared parts in step. Desktop+// differences: the per-project choice lives in the workspace's OmniRush+// settings (service.ts), not box.json (box.json keeps only the machine's+// backend, as the CLI's does); the plan is per workspace (one engine serves+// every project); a run tracks its turns per chat; there is no --sandbox or+// --sandbox-backend flag (OMNIRUSH_BOX=1|0 and OMNIRUSH_BOX_BACKEND still+// override); a download with no detached command (the WSL distro) runs in+// this process.//// Whether a chat runs in its project's box, and the box's part in a run:// the engine config bits (shell, plugin), the per-turn checkpoints, the@@ -14,10 +18,12 @@// background, and a shell call waits for it (boxsh).import { spawn, type ChildProcess } from "node:child_process";-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";import path from "node:path";-import { boxKey, containerName, gcBoxes, inspectImage, installShell, openBox, recordFile, rt, savedTurns, type Box, type BoxInstallLog, type BoxLabel, type BoxLog, type BoxRuntime, type CheckpointSummary } from "./box.js";+import { boxKey, containerName, gcBoxes, installShell, openBox, recordFile, savedTurns, type Box, type BoxInstallLog, type BoxLabel, type BoxLog, type BoxRuntime, type CheckpointSummary } from "./box.js";+import { driverFor, normalizeBackend } from "./backends/index.js";+import type { BoxExec } from "./backends/types.js";import { detectStack, imageFor, loadPins, type BoxImage } from "./images.js";import { detectRuntime, runCommand, type RunCommand, type RuntimeResult } from "./runtime.js";@@ -42,18 +48,73 @@ export function serverDefault(stateDir: string): ServerBoxDefault {}}-/** Remembers local_box.default of a capabilities answer; whether it changed. */+/** The server's allowlist of backends (local_box.backends; null: any). */+export function serverBackends(stateDir: string): string[] | null {+ try {+ const value = JSON.parse(readFileSync(path.join(stateDir, "box-server.json"), "utf8"));+ return Array.isArray(value?.backends) ? value.backends.filter((b: unknown): b is string => typeof b === "string") : null;+ } catch {+ return null;+ }+}++/** Remembers local_box.default (and its backends allowlist) of a capabilities answer; whether either changed. */export function rememberServerDefault(stateDir: string, capabilities: { local_box?: unknown } | null | undefined): boolean {const block = capabilities?.local_box;if (!block || typeof block !== "object") return false;- const fields = block as { default?: unknown; max_turn_bytes?: unknown };+ const fields: { default?: unknown; max_turn_bytes?: unknown; backends?: unknown } = block;const value = isMode(fields.default) ? fields.default : "off";- const before = serverDefault(stateDir);+ const backends = Array.isArray(fields.backends) ? fields.backends.filter((b): b is string => typeof b === "string").slice(0, 32) : null;+ const before = JSON.stringify([serverDefault(stateDir), serverBackends(stateDir)]);try {mkdirSync(stateDir, { recursive: true });- writeFileSync(path.join(stateDir, "box-server.json"), JSON.stringify({ default: value, max_turn_bytes: fields.max_turn_bytes ?? null, at: Date.now() }), { mode: 0o600 });+ writeFileSync(path.join(stateDir, "box-server.json"), JSON.stringify({ default: value, max_turn_bytes: fields.max_turn_bytes ?? null, backends, at: Date.now() }), { mode: 0o600 });} catch { /* best effort */ }- return before !== value;+ return before !== JSON.stringify([value, backends]);+}++// --- the backend --------------------------------------------------------------------++/** What the backend setting holds: "auto" (the ranked order), one backend id, or "native" (no box). */+export type BackendSetting = string;++/** The machine's box settings file (the CLI's box.json; the desktop keeps only `backend` in it). */+export function settingsFile(stateDir: string): string {+ return path.join(stateDir, "box.json");+}++/** The saved backend setting ("auto" when none). */+export function readBackend(stateDir: string): BackendSetting {+ try {+ return normalizeBackend(JSON.parse(readFileSync(settingsFile(stateDir), "utf8"))?.backend) || "auto";+ } catch {+ return "auto";+ }+}++/** Save the backend boxes on this machine use: "auto" or one id (the desktop setting). */+export function saveBackend(stateDir: string, backend: unknown): BackendSetting {+ const id = normalizeBackend(backend);+ if (!id) throw new Error(`unknown sandbox backend "${String(backend)}"`);+ let current: Record<string, unknown> = {};+ try {+ const value: unknown = JSON.parse(readFileSync(settingsFile(stateDir), "utf8"));+ if (value && typeof value === "object" && !Array.isArray(value)) current = Object.fromEntries(Object.entries(value));+ } catch { /* none */ }+ mkdirSync(stateDir, { recursive: true });+ const file = settingsFile(stateDir);+ const tmp = `${file}.${process.pid}.tmp`;+ writeFileSync(tmp, `${JSON.stringify({ ...current, backend: id }, null, 2)}\n`, { mode: 0o600 });+ renameSync(tmp, file);+ return id;+}++/** The backend asked for, and by whom: OMNIRUSH_BOX_BACKEND, then the saved setting. */+export function askedBackend({ env = process.env, stateDir }: { env?: NodeJS.ProcessEnv; stateDir: string }): { backend: string; source: "env" | "setting" | "auto" } {+ const flag = String(env.OMNIRUSH_BOX_BACKEND || "").trim();+ if (flag) return { backend: normalizeBackend(flag) ?? flag, source: "env" };+ const saved = readBackend(stateDir);+ return { backend: saved, source: saved !== "auto" ? "setting" : "auto" };}/**@@ -72,14 +133,19 @@ export function resolveMode({ env = process.env, project, server, offered = fals// --- background download ----------------------------------------------------------------function pullMarker(home: string, image: string): string {- return path.join(home, "pulls", `${image.replace(/[^a-zA-Z0-9._-]+/g, "_")}.pid`);+function pullMarker(home: string, runtime: Pick<BoxRuntime, "backend" | "name">, image: string): string {+ return path.join(home, "pulls", `${runtime.backend ?? runtime.name}-${image.replace(/[^a-zA-Z0-9._-]+/g, "_")}.pid`);}-/** Whether a background download of `image` is running. */-export function pulling(home: string, image: string): boolean {+/** Downloads running in this process (a backend with no detached command: the WSL distro). */+const inProcess = new Set<string>();++/** Whether a background download of `image` with this backend is running. */+export function pulling(home: string, runtime: Pick<BoxRuntime, "backend" | "name">, image: string): boolean {+ const marker = pullMarker(home, runtime, image);+ if (inProcess.has(marker)) return true;try {- const pid = Number(readFileSync(pullMarker(home, image), "utf8"));+ const pid = Number(readFileSync(marker, "utf8"));if (!pid) return false;process.kill(pid, 0);return true;@@ -88,15 +154,30 @@ export function pulling(home: string, image: string): boolean {}}-/** Start `pull` detached (survives this run); one at a time per image. */-export function pullInBackground(runtime: BoxRuntime, image: string, home: string, { spawnImpl = spawn }: { spawnImpl?: (command: string, args: string[], options: { detached: boolean; stdio: "ignore"; windowsHide: boolean }) => Pick<ChildProcess, "pid" | "unref"> } = {}): { started: boolean; pid: number | undefined } {- const marker = pullMarker(home, image);+/**+ * Start the backend's download detached (survives this run); one at a time+ * per image. A backend without a detached command (the WSL distro, whose+ * download imports the distro first) downloads in this process instead.+ */+export function pullInBackground(runtime: BoxRuntime, image: BoxImage, home: string, { spawnImpl = spawn, env = process.env, log = () => {} }: { spawnImpl?: (command: string, args: string[], options: { detached: boolean; stdio: "ignore"; windowsHide: boolean }) => Pick<ChildProcess, "pid" | "unref">; env?: NodeJS.ProcessEnv; log?: BoxLog } = {}): { started: boolean; pid: number | undefined } {+ const marker = pullMarker(home, runtime, image.pull);+ if (inProcess.has(marker)) return { started: false, pid: process.pid };try {const pid = Number(readFileSync(marker, "utf8"));if (pid) { process.kill(pid, 0); return { started: false, pid }; }} catch { /* none running */ }mkdirSync(path.dirname(marker), { recursive: true });- const child = spawnImpl(runtime.bin, [...(runtime.prefix ?? []), "pull", image], { detached: true, stdio: "ignore", windowsHide: true });+ const driver = driverFor(runtime);+ const cmd = driver.pullCommand(runtime, image, home);+ if (!cmd) {+ inProcess.add(marker);+ void driver.pull(runtime, image, { home, env, log })+ .then((res) => { if (!res.ok) log("warn", "box download failed", { backend: runtime.backend, error: res.error }); })+ .catch((error) => log("warn", "box download failed", { backend: runtime.backend, error: String(error?.message || error) }))+ .finally(() => inProcess.delete(marker));+ return { started: true, pid: process.pid };+ }+ const child = spawnImpl(cmd.bin, cmd.args, { detached: true, stdio: "ignore", windowsHide: true });child.unref?.();try { writeFileSync(marker, String(child.pid ?? "")); } catch { /* best effort */ }return { started: true, pid: child.pid };@@ -123,10 +204,10 @@ export type BoxPlan = ReadyPlan | NativePlan;* { box: null, notice } when its chats run on this machine for now (no* runtime, no helpers, the image still downloading), else a ready plan.*/-export async function planBox({ env = process.env, home, root, log = () => {}, run = runCommand, probeMs = 4_000, shims = null }: { env?: NodeJS.ProcessEnv; home: string; root: string; log?: BoxLog; run?: RunCommand; probeMs?: number; shims?: string | null }): Promise<BoxPlan> {+export async function planBox({ env = process.env, home, root, log = () => {}, run = runCommand, probeMs = 4_000, shims = null, asked = null, allow = null }: { env?: NodeJS.ProcessEnv; home: string; root: string; log?: BoxLog; run?: RunCommand; probeMs?: number; shims?: string | null; asked?: string | null; allow?: string[] | null }): Promise<BoxPlan> {const key = boxKey(root);const bounded = <T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> => Promise.race([promise, new Promise<T>((resolve) => setTimeout(() => resolve(fallback), ms))]);- const runtime = await bounded<RuntimeResult>(detectRuntime({ boxHome: home, env, run }), probeMs, { ok: false, reason: "the container runtime did not answer in time" });+ const runtime = await bounded<RuntimeResult>(detectRuntime({ boxHome: home, env, run, ...(asked ? { asked } : {}), allow }), probeMs, { ok: false, reason: "the sandbox backend did not answer in time" });if (!runtime.ok) {log("info", "box unavailable", { reason: runtime.reason });return { box: null, notice: `Sandbox off for now: ${runtime.reason}.`, runtime };@@ -138,13 +219,14 @@ export async function planBox({ env = process.env, home, root, log = () => {}, rreturn { box: null, notice: `Sandbox off for now: ${error instanceof Error ? error.message : String(error)}.`, runtime };}// A box already made keeps its image (and its installs); a new one needs the image here.- const existing = await bounded(rt(runtime, run)(["container", "inspect", containerName(key, env), "--format", "{{.Id}}"], { timeoutMs: probeMs }), probeMs, { code: -1, stdout: "", stderr: "" });- if (existing.code !== 0) {+ const driver = driverFor(runtime);+ const existing = await bounded(driver.exists(runtime, key, { run, home, env, timeoutMs: probeMs }), probeMs, false);+ if (!existing) {const image = imageFor(detectStack(root), { env });- const present = await bounded(inspectImage(runtime, image.pull, { run }), probeMs, null);+ const present = await bounded(driver.imagePresent(runtime, image, { run, home, env }), probeMs, null);if (!present) {- pullInBackground(runtime, image.pull, home);- return { box: null, notice: `Sandbox is downloading (${image.approxMb ? `about ${image.approxMb} MB, ` : ""}once); chats here run on this machine until it is ready.`, runtime, image, downloading: true };+ pullInBackground(runtime, image, home, { env, log });+ return { box: null, notice: `Sandbox is downloading (${image.approxMb ? `about ${image.approxMb} MB, ` : ""}once${runtime.backend === "wsl" && !runtime.installed ? ", with the OmniRush WSL distro" : ""}); chats here run on this machine until it is ready.`, runtime, image, downloading: true };}}if (env.OMNIRUSH_BOX_GC !== "off") setTimeout(() => gcInBackground(runtime, home, { log }), 30_000).unref?.();@@ -220,6 +302,10 @@ export type BoxRun = {runtimeBin: string;/** Arguments before the runtime's own (`-e docker` for a WSL engine). */runtimeArgs: string[];+ /** The backend id (backends/index.ts). */+ backend: string;+ /** How to run a program in the box with stdin open when it is not `docker exec` (files-used reads); null for container engines. */+ exec: BoxExec | null;root: string;readonly native: boolean;readonly box: Box | null;@@ -264,6 +350,8 @@ export function boxRun(plan: ReadyPlan, { log = () => {}, readyWaitMs = 30_000,container: containerName(key),runtimeBin: runtime.bin,runtimeArgs: runtime.prefix ?? [],+ backend: runtime.backend ?? runtime.name,+ exec: driverFor(runtime).kind === "container" ? null : driverFor(runtime).execCommand(runtime, { key, home }),root,get native() { return native; },get box() { return box; },diff --git a/apps/server/src/box/run.ts b/apps/server/src/box/run.tsnew file mode 100644index 00000000..d7649d4d--- /dev/null+++ b/apps/server/src/box/run.ts@@ -0,0 +1,53 @@+// Ported from the CLI (omnirush-cli src/box/run.js, feat/local-box-backends);+// keep the two in step. Only types were added here.+//+// Running a runtime's CLI: a time limit, output caps, never a throw.++import { spawn, type ChildProcess } from "node:child_process";++type Env = NodeJS.ProcessEnv;++export type RunResult = { code: number; stdout: string; stderr: string; error?: string };+export type RunOptions = { env?: Env; timeoutMs?: number; input?: string | Buffer; maxBytes?: number; cwd?: string };+export type RunCommand = (bin: string, args: string[], options?: RunOptions) => Promise<RunResult>;++function errorText(error: unknown): string {+ return error instanceof Error ? error.message : String(error);+}++function errorCode(error: unknown): string {+ const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;+ return typeof code === "string" ? code : "spawn";+}++/** Run a program with a time limit; never throws. */+export function runCommand(bin: string, args: string[], { env = process.env, timeoutMs = 8_000, input, maxBytes = 64 << 20, cwd }: RunOptions = {}): Promise<RunResult> {+ return new Promise((resolve) => {+ let child: ChildProcess;+ try {+ child = spawn(bin, args, { env, cwd, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true });+ } catch (error) {+ resolve({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) });+ return;+ }+ const out: Buffer[] = [];+ let outBytes = 0;+ const err: Buffer[] = [];+ let done = false;+ const finish = (value: RunResult) => {+ if (done) return;+ done = true;+ clearTimeout(timer);+ resolve(value);+ };+ const timer = setTimeout(() => {+ try { child.kill("SIGKILL"); } catch { /* gone */ }+ finish({ code: -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8"), error: "timeout" });+ }, timeoutMs);+ child.stdout?.on("data", (chunk: Buffer) => { outBytes += chunk.length; if (outBytes <= maxBytes) out.push(chunk); });+ child.stderr?.on("data", (chunk: Buffer) => { if (err.length < 64) err.push(chunk); });+ child.on("error", (error) => finish({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) }));+ child.on("close", (code) => finish({ code: code ?? -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") }));+ if (input !== undefined) child.stdin?.end(input);+ });+}diff --git a/apps/server/src/box/runtime.ts b/apps/server/src/box/runtime.tsindex 43970dd7..d88fa378 100644--- a/apps/server/src/box/runtime.ts+++ b/apps/server/src/box/runtime.ts@@ -1,9 +1,10 @@-// Ported from the CLI (omnirush-cli src/box/runtime.js, feat/local-box);-// keep the two in step. Only types were added here.+// Ported from the CLI (omnirush-cli src/box/runtime.js,+// feat/local-box-backends); keep the two in step. Only types were added here.//-// Which container runtime runs a project's box: rootless Podman or Docker on-// Linux, Docker Desktop / OrbStack / colima / Rancher Desktop / Podman-// machine on macOS and Windows, Docker inside WSL2. Never blocks a start: a+// The container engines a box backend can be (backends/container.ts): rootless+// Podman or Docker on Linux, Docker Desktop / OrbStack / colima / Rancher+// Desktop / Podman machine on macOS and Windows, Docker inside WSL2. Which+// backend runs a box is chosen by backends/index.ts. Never blocks a start: a// probe has a short time limit, its result is cached, and "none" means the// session runs on this machine with one line saying why.//@@ -12,22 +13,26 @@// /mnt/c, the docker-group permission error shown as "the reason is above".// Each of those has a rule below and a test.-import { spawn, type ChildProcess } from "node:child_process";-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";+import { existsSync } from "node:fs";import os from "node:os";import path from "node:path";+import { runCommand, type RunCommand, type RunResult } from "./run.js";++export { runCommand, type RunCommand, type RunOptions, type RunResult } from "./run.js";+/** Probe results are reused this long (ms): a working runtime, and a missing one. */export const CACHE_OK_MS = 10 * 60_000;export const CACHE_FAIL_MS = 2 * 60_000;type Env = NodeJS.ProcessEnv;-export type RunResult = { code: number; stdout: string; stderr: string; error?: string };-export type RunOptions = { env?: Env; timeoutMs?: number; input?: string | Buffer; maxBytes?: number };-export type RunCommand = (bin: string, args: string[], options?: RunOptions) => Promise<RunResult>;+/** A container CLI to probe; `prefix` goes before every call (`--context <name>`). */+export type RuntimeCandidate = { name: string; bin: string; skipped?: string; prefix?: string[] };++/** One backend as `all` lists it (the settings card's "others"). */+export type BackendAlternative = { backend: string; name: string; ok: boolean; version: string | null; flavor: string | null; reason: string | null; context?: string };-export type RuntimeCandidate = { name: string; bin: string; skipped?: string };export type RuntimeInfo = {ok: true;name: string;@@ -38,12 +43,45 @@ export type RuntimeInfo = {rootless: boolean;flavor: string;vm: boolean;- /** A WSL engine: arguments before the runtime's own (["-e", "docker"] through wsl.exe). */+ /** The backend id (backends/index.ts BACKENDS): what uploads record as sandbox.backend. */+ backend?: string;+ /** Why this backend: the ranked order, the setting, the server's allowlist. */+ why?: string;+ /** Arguments before the runtime's own (["-e", "docker"] through wsl.exe, ["--context", "colima"]). */prefix?: string[];+ /** The docker context the runtime answered through (macOS, Windows). */+ context?: string;wsl?: boolean;+ /** The OmniRush WSL distro: its name, whether it is imported yet. */+ distro?: string;+ installed?: boolean;+ state?: string | null;+ /** bubblewrap: the bwrap boxrun runs, the id mapping, the launcher. */+ bwrap?: string | null;+ idmap?: string;+ launcher?: string;+ kernel?: string;+ cached?: boolean;+ alternatives?: BackendAlternative[];+};+export type RuntimeTried = { backend?: string; name?: string; bin?: string; reason: string };+export type RuntimeFailure = {+ ok: false;+ name?: string;+ bin?: string;+ backend?: string;+ version?: string;+ code?: string;+ context?: string;+ reason: string;+ tried?: RuntimeTried[];cached?: boolean;+ /** The backend is set to native (this machine): no box, not a failure. */+ native?: boolean;+ /** macOS with nothing: the free option to offer (colima). */+ hint?: string;+ alternatives?: BackendAlternative[];};-export type RuntimeFailure = { ok: false; name?: string; bin?: string; reason: string; tried?: Array<{ name?: string; bin?: string; reason: string }>; cached?: boolean };export type RuntimeResult = RuntimeInfo | RuntimeFailure;/** Whether this Linux is WSL (the kernel says Microsoft). */@@ -117,47 +155,6 @@ export function candidates({ platform = process.platform, home = os.homedir(), ereturn out;}-function errorText(error: unknown): string {- return error instanceof Error ? error.message : String(error);-}--function errorCode(error: unknown): string {- const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;- return typeof code === "string" ? code : "spawn";-}--/** Run a program with a time limit; never throws. */-export function runCommand(bin: string, args: string[], { env = process.env, timeoutMs = 8_000, input, maxBytes = 64 << 20 }: RunOptions = {}): Promise<RunResult> {- return new Promise((resolve) => {- let child: ChildProcess;- try {- child = spawn(bin, args, { env, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true });- } catch (error) {- resolve({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) });- return;- }- const out: Buffer[] = [];- let outBytes = 0;- const err: Buffer[] = [];- let done = false;- const finish = (value: RunResult) => {- if (done) return;- done = true;- clearTimeout(timer);- resolve(value);- };- const timer = setTimeout(() => {- try { child.kill("SIGKILL"); } catch { /* gone */ }- finish({ code: -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8"), error: "timeout" });- }, timeoutMs);- child.stdout?.on("data", (chunk: Buffer) => { outBytes += chunk.length; if (outBytes <= maxBytes) out.push(chunk); });- child.stderr?.on("data", (chunk: Buffer) => { if (err.length < 64) err.push(chunk); });- child.on("error", (error) => finish({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) }));- child.on("close", (code) => finish({ code: code ?? -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") }));- if (input !== undefined) child.stdin?.end(input);- });-}-function firstLine(text: unknown): string {return String(text ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? "";}@@ -249,7 +246,8 @@ export async function probe(candidate: RuntimeCandidate, { run = runCommand, envreturn { ok: false, name, bin, reason: "DOCKER_HOST points at another machine, which cannot see this folder" };}}- const args = name === "podman" ? ["info", "--format", "json"] : ["info", "--format", "{{json .}}"];+ const prefix = Array.isArray(candidate.prefix) ? candidate.prefix : [];+ const args = [...prefix, ...(name === "podman" ? ["info", "--format", "json"] : ["info", "--format", "{{json .}}"])];const result = await run(bin, args, { env, timeoutMs });if (result.code !== 0) return { ok: false, name, bin, reason: explainFailure(name, result, { platform, env }) };let info: Info;@@ -326,70 +324,34 @@ export async function probeWsl(wslExe: string, { run = runCommand, env = processreturn { ok: false, name: "wsl", bin: wslExe, reason: "no Docker or Podman engine answers in the default WSL distribution" };}-function cacheFile(boxHome: string): string {- return path.join(boxHome, "runtime.json");-}--function readCache(boxHome: string, now: number, key: string): RuntimeResult | null {- try {- const cached = JSON.parse(readFileSync(cacheFile(boxHome), "utf8"));- if (cached?.key !== key) return null;- const age = now - Number(cached.at);- if (!(age >= 0)) return null;- if (cached.result?.ok ? age < CACHE_OK_MS : age < CACHE_FAIL_MS) return cached.result;- } catch { /* none */ }- return null;-}--function writeCache(boxHome: string, key: string, result: RuntimeResult, now: number): void {- try {- mkdirSync(boxHome, { recursive: true });- const file = cacheFile(boxHome);- const tmp = `${file}.${process.pid}.tmp`;- writeFileSync(tmp, JSON.stringify({ key, at: now, result }), { mode: 0o600 });- renameSync(tmp, file);- } catch { /* best effort */ }-}-/**- * The runtime for boxes on this machine (cached; `fresh` skips the cache):- * the first candidate that answers, or { ok: false, reason, tried } where- * `reason` is one line for the user.+ * The backend for boxes on this machine (backends/index.ts: bubblewrap,+ * Apple container, WSL containers, the OmniRush WSL distro, then the+ * container engines above, in a ranked order per OS). Kept here under its+ * old name.*/-export async function detectRuntime({ boxHome, env = process.env, platform = process.platform, home = os.homedir(), exists = existsSync, run = runCommand, wsl = platform === "linux" && isWsl(env), now = Date.now(), fresh = false, timeoutMs }: { boxHome?: string; env?: Env; platform?: NodeJS.Platform; home?: string; exists?: (file: string) => boolean; run?: RunCommand; wsl?: boolean; now?: number; fresh?: boolean; timeoutMs?: number } = {}): Promise<RuntimeResult> {- const key = JSON.stringify([platform, env.OMNIRUSH_BOX_RUNTIME || "", env.DOCKER_HOST || "", env.PATH || env.Path || ""]);- if (boxHome && !fresh) {- const cached = readCache(boxHome, now, key);- if (cached) return { ...cached, cached: true };- }- const list = candidates({ platform, home, env, exists, wsl });- const tried: RuntimeFailure[] = [];- let result: RuntimeResult | null = null;- for (const candidate of list) {- const probed = await probe(candidate, { run, env, platform, wsl, ...(timeoutMs ? { timeoutMs } : {}) });- if (probed.ok) { result = probed; break; }- tried.push(probed);- }- // Windows: a Docker or Podman engine inside an existing WSL 2 distro, used- // through wsl.exe (never installed or started for the user).- if (!result && platform === "win32" && env.OMNIRUSH_BOX_WSL !== "0") {- const wslExe = wslLauncher({ env, exists });- if (wslExe) {- const probed = await probeWsl(wslExe, { run, env, ...(timeoutMs ? { timeoutMs } : {}) });- if (probed.ok) result = probed;- else tried.push(probed);- }- }- if (!result) {- const reason = tried.length- ? tried.map((entry) => entry.reason).join("; ")- : platform === "linux"- ? "no container runtime found (install Podman or Docker)"- : platform === "darwin"- ? "no container runtime found (install Docker Desktop, OrbStack, colima or Podman)"- : "no container runtime found (install Docker Desktop with the WSL 2 backend, or Podman)";- result = { ok: false, reason, tried: tried.map(({ name, bin, reason: why }) => ({ name, bin, reason: why })) };- }- if (boxHome) writeCache(boxHome, key, result, now);- return result;+export async function detectRuntime(opts: DetectOptions = {}): Promise<RuntimeResult> {+ const { detectBackend } = await import("./backends/index.js");+ return detectBackend(opts);}++export type DetectOptions = {+ boxHome?: string;+ env?: Env;+ platform?: NodeJS.Platform;+ home?: string;+ exists?: (file: string) => boolean;+ run?: RunCommand;+ wsl?: boolean;+ now?: number;+ fresh?: boolean;+ /** Probe every backend and list them as `alternatives` (status). */+ all?: boolean;+ timeoutMs?: number;+ /** A backend id, "auto" or "native" (the desktop setting); default OMNIRUSH_BOX_BACKEND. */+ asked?: string | null;+ /** The server's allowlist (local_box.backends); null: any. */+ allow?: string[] | null;+ arch?: string;+ release?: string;+};diff --git a/apps/server/src/box/service.ts b/apps/server/src/box/service.tsindex 65edcbca..a868ab33 100644--- a/apps/server/src/box/service.ts+++ b/apps/server/src/box/service.ts@@ -10,7 +10,10 @@* - <box home>/desktop-projects.json, the projects the plugin routes to* their box (everything else runs natively through the same shell);* - each project's run: the per-turn checkpoints and the label its chats'- * uploads carry.+ * uploads carry;+ * - the machine's backend setting (`auto`, one backend id, or `native`) in+ * <state>/box.json, and the server's allowlist of backends+ * (local_box.backends, remembered in <state>/box-server.json).** Nothing here blocks opening a project: probes are bounded, a missing image* downloads in the background, a box that cannot start leaves its project@@ -21,12 +24,14 @@import { mkdir, readFile, rename, writeFile } from "node:fs/promises";import { join } from "node:path";-import { boxHome, boxKey, boxSnapshotsDir, containerName, inspectImage, installShell, listBoxes, readRecord, resetBox, savedTurns, type BoxLabel, type BoxLog } from "./box.js";+import { boxHome, boxKey, boxSnapshotsDir, containerName, installShell, listBoxes, readRecord, resetBox, savedTurns, type BoxLabel, type BoxLog } from "./box.js";+import { LABELS, backendsFor, driverFor } from "./backends/index.js";+import type { BoxExec } from "./backends/types.js";import { detectStack, imageFor } from "./images.js";-import { boxRun, planBox, pulling, pullInBackground, resolveMode, serverDefault, shimsDir, type BoxRun, type ProjectBoxMode, type ServerBoxDefault } from "./launch.js";+import { askedBackend, boxRun, planBox, pulling, pullInBackground, resolveMode, saveBackend, serverBackends, serverDefault, shimsDir, type BoxRun, type ProjectBoxMode, type ServerBoxDefault } from "./launch.js";import type { BoxInstallLogPaths } from "./install-log.js";import { DESKTOP_PROJECTS_FILE } from "./plugin-lib.js";-import { detectRuntime, type RuntimeResult } from "./runtime.js";+import { detectRuntime, type BackendAlternative, type DetectOptions, type RuntimeResult } from "./runtime.js";/** What the capture side needs of a chat's box (plain data: it crosses to the capture worker). */export type BoxCaptureInfo = {@@ -37,6 +42,10 @@ export type BoxCaptureInfo = {runtimeBin: string;/** Arguments before the runtime's own (`-e docker` for a WSL engine). */runtimeArgs: string[];+ /** The backend id (backends/index.ts). */+ backend: string;+ /** How files-used reads the box when it is not `docker exec` (bubblewrap, Apple container, the WSL distro). */+ exec: BoxExec | null;/** environment.sandbox of the chat's uploads. */label: BoxLabel;};@@ -54,6 +63,10 @@ export type BoxStatus = {offer: boolean;state: "off" | "unavailable" | "downloading" | "starting" | "ready" | "failed";runtime: { ok: boolean; name: string | null; flavor: string | null; version: string | null; reason: string | null } | null;+ /** What runs the box on this machine: the chosen backend, why, and the others (each with why not). */+ backend: BoxBackendView | null;+ /** The machine's backend setting and the values it takes here. */+ backendSetting: { value: string; source: "env" | "setting" | "auto"; choices: Array<{ id: string; label: string }> };image: { ref: string; stack: string; present: boolean | null; downloading: boolean } | null;container: { name: string; exists: boolean; running: boolean } | null;/** One line for the user (why it is off, that it is downloading). */@@ -61,6 +74,25 @@ export type BoxStatus = {error: string | null;};+export type BoxBackendView = {+ /** The chosen backend's id (null when none works here). */+ id: string | null;+ label: string | null;+ version: string | null;+ flavor: string | null;+ /** Why this one (the ranked order, the setting, the server's allowlist), or why none. */+ why: string | null;+ /** Every backend tried here: id, whether it works, one line why not. Empty until the first full check. */+ alternatives: Array<{ id: string; label: string; ok: boolean; reason: string | null }>;+ /** The server limits the backends (local_box.backends). */+ allowed: string[] | null;+};++/** The backend choices of a platform: auto, the ranked ids there, native. */+export function backendChoices(platform: NodeJS.Platform = process.platform): Array<{ id: string; label: string }> {+ return [{ id: "auto", label: "Automatic" }, ...backendsFor(platform).map((id) => ({ id, label: LABELS[id] ?? id })), { id: "native", label: "Off (this computer)" }];+}+export type BoxServiceOptions = {/** The capture state dir: the server default is remembered here, snapshots go under sandbox/snapshots. */stateDir: string;@@ -79,6 +111,8 @@ type Project = { run: BoxRun | null; notice: string | null; planning: Promise<Boconst REPLAN_MS = 15_000;/** A prompt waits at most this long for its turn's checkpoint. */const FREEZE_WAIT_MS = 90_000;+/** The full backend check (every backend, for the status card's "others") is reused this long. */+const ALTERNATIVES_MS = 60_000;export function boxRoot(workspace: BoxWorkspace): string {return workspace.directory?.trim() || workspace.path;@@ -92,6 +126,7 @@ export class BoxService {private log: BoxLog;private projectsWrite: Promise<void> = Promise.resolve();private installLog: BoxInstallLogPaths | null = null;+ private alternatives: { at: number; key: string; list: BackendAlternative[] } | null = null;constructor(private readonly options: BoxServiceOptions) {this.env = options.env ?? process.env;@@ -121,6 +156,36 @@ export class BoxService {return serverDefault(this.options.stateDir);}+ /** The backend detection's inputs: the setting (or OMNIRUSH_BOX_BACKEND) and the server's allowlist. */+ private detectOptions(): Pick<DetectOptions, "asked" | "allow"> {+ return { asked: askedBackend({ env: this.env, stateDir: this.options.stateDir }).backend, allow: serverBackends(this.options.stateDir) };+ }++ private detect(extra: DetectOptions = {}): Promise<RuntimeResult> {+ return detectRuntime({ boxHome: this.home, env: this.env, ...this.detectOptions(), ...extra });+ }++ /**+ * Save the machine's backend ("auto", one backend id, "native"). Projects+ * are planned again with it (a running box keeps going until its project+ * is planned again). Throws for an unknown value.+ */+ async setBackend(value: unknown): Promise<string> {+ const saved = saveBackend(this.options.stateDir, value);+ this.alternatives = null;+ const now = await this.detect({ fresh: true });+ const chosen = now.ok ? now.backend ?? now.name : null;+ for (const project of this.projects.values()) {+ if (project.run && project.run.backend === chosen) continue;+ project.run = null;+ project.notice = null;+ project.nextPlanAt = 0;+ }+ await this.writeProjects();+ void this.ensureAll();+ return saved;+ }+private async mode(workspace: BoxWorkspace) {const settings = await this.options.readSettings(workspace.id).catch(() => ({ mode: null, offered: false }));const server = this.serverDefault();@@ -169,7 +234,7 @@ export class BoxService {}if (project.run && !project.run.native) return project.run;if (Date.now() < project.nextPlanAt) return null;- const plan = await planBox({ env: this.env, home: this.home, root, log: this.log, shims: shimsDir(this.env) });+ const plan = await planBox({ env: this.env, home: this.home, root, log: this.log, shims: shimsDir(this.env), ...this.detectOptions() });if (!plan.box) {project.run = null;project.notice = plan.notice;@@ -246,24 +311,43 @@ export class BoxService {const key = boxKey(root);const project = this.projects.get(key);const base = { mode: settings.mode, serverDefault: server, on, source, offer, error: null };- if (workspace.workspaceType !== "local") return { ...base, on: false, offer: false, state: "off", runtime: null, image: null, container: null, notice: "The sandbox is for folders on this computer." };+ const backendSetting = { ...askedBackend({ env: this.env, stateDir: this.options.stateDir }), choices: backendChoices() };+ const setting = { value: backendSetting.backend, source: backendSetting.source, choices: backendSetting.choices };+ if (workspace.workspaceType !== "local") return { ...base, on: false, offer: false, state: "off", runtime: null, backend: null, backendSetting: setting, image: null, container: null, notice: "The sandbox is for folders on this computer." };+ // The full check (every backend) on a fresh look or once a minute; the cached choice otherwise.+ const { asked, allow } = this.detectOptions();+ const altKey = JSON.stringify([asked, allow]);+ const full = fresh || !this.alternatives || this.alternatives.key !== altKey || Date.now() - this.alternatives.at > ALTERNATIVES_MS;+ const timeout = full ? 10_000 : 4_000;const runtime = await Promise.race([- detectRuntime({ boxHome: this.home, env: this.env, fresh }),- new Promise<RuntimeResult>((resolve) => setTimeout(() => resolve({ ok: false, reason: "the container runtime did not answer in time" }), 4_000)),+ this.detect(full ? { all: true } : {}),+ new Promise<RuntimeResult>((resolve) => setTimeout(() => resolve({ ok: false, reason: "the sandbox backend did not answer in time" }), timeout)),]);+ if (full && runtime.alternatives) this.alternatives = { at: Date.now(), key: altKey, list: runtime.alternatives };+ const alternatives = (runtime.alternatives ?? this.alternatives?.list ?? []).map((alt) => ({ id: alt.backend, label: LABELS[alt.backend] ?? alt.backend, ok: alt.ok, reason: alt.reason ? alt.reason.split("\n")[0]!.slice(0, 300) : null }));const runtimeView = runtime.ok? { ok: true, name: runtime.name, flavor: runtime.flavor, version: runtime.version, reason: null }: { ok: false, name: null, flavor: null, version: null, reason: runtime.reason };+ const backendId = runtime.ok ? runtime.backend ?? runtime.name : null;+ const backend: BoxBackendView = {+ id: backendId,+ label: backendId ? LABELS[backendId] ?? backendId : null,+ version: runtime.ok ? runtime.version || null : null,+ flavor: runtime.ok ? runtime.flavor || null : null,+ why: runtime.ok ? runtime.why ?? null : runtime.reason,+ alternatives,+ allowed: allow ?? null,+ };const image = imageFor(detectStack(root), { env: this.env });const name = containerName(key, this.env);let present: boolean | null = null;let container: BoxStatus["container"] = null;if (runtime.ok) {- present = Boolean(await inspectImage(runtime, image.pull).catch(() => null));- const mine = (await listBoxes(runtime).catch(() => [])).find((box) => box.key === key && box.name === name);+ present = Boolean(await driverFor(runtime).imagePresent(runtime, image, { home: this.home, env: this.env }).catch(() => null));+ const mine = (await listBoxes(runtime, { env: this.env, home: this.home }).catch(() => [])).find((box) => box.key === key);container = { name, exists: Boolean(mine), running: Boolean(mine?.running) };}- const downloading = runtime.ok && pulling(this.home, image.pull);+ const downloading = runtime.ok && pulling(this.home, runtime, image.pull);const record = readRecord(this.home, key);const run = project?.run ?? null;const state: BoxStatus["state"] = !on ? "off"@@ -275,6 +359,8 @@ export class BoxService {...base,state,runtime: runtimeView,+ backend,+ backendSetting: setting,image: { ref: image.pull, stack: image.stack, present, downloading },container,notice: on ? project?.notice ?? (runtime.ok ? null : `Sandbox off for now: ${runtime.reason}.`) : null,@@ -286,7 +372,7 @@ export class BoxService {async reset(workspace: BoxWorkspace): Promise<{ removed: boolean }> {const root = boxRoot(workspace);const key = boxKey(root);- const runtime = await detectRuntime({ boxHome: this.home, env: this.env });+ const runtime = await this.detect();const project = this.projects.get(key);if (project) {project.run = null;@@ -301,11 +387,11 @@ export class BoxService {/** Download the project's image now (the toggle turned on with no image here). */async pull(workspace: BoxWorkspace): Promise<boolean> {- const runtime = await detectRuntime({ boxHome: this.home, env: this.env });+ const runtime = await this.detect();if (!runtime.ok) return false;const image = imageFor(detectStack(boxRoot(workspace)), { env: this.env });- if (await inspectImage(runtime, image.pull)) return false;- pullInBackground(runtime, image.pull, this.home);+ if (await driverFor(runtime).imagePresent(runtime, image, { home: this.home, env: this.env })) return false;+ pullInBackground(runtime, image, this.home, { env: this.env, log: this.log });return true;}@@ -344,7 +430,7 @@ export class BoxService {const label = run.label(sessionId);const box = run.box;if (!label || !box) return null;- return { key: run.key, root: run.root, croot: box.croot, container: box.container, runtimeBin: run.runtimeBin, runtimeArgs: run.runtimeArgs, label };+ return { key: run.key, root: run.root, croot: box.croot, container: box.container, runtimeBin: run.runtimeBin, runtimeArgs: run.runtimeArgs, backend: run.backend, exec: run.exec, label };}/** Whether chats ran in a box during this run (they get a `final` checkpoint at quit). */diff --git a/apps/server/src/box/wsl.json b/apps/server/src/box/wsl.jsonnew file mode 100644index 00000000..2a855f4e--- /dev/null+++ b/apps/server/src/box/wsl.json@@ -0,0 +1,9 @@+{+ "version": "2026.10.1",+ "distro": "OmniRushBox",+ "base": "debian:bookworm-slim@sha256:7c7b2c966bc9ee8cedfeef67e0e279108992c77681fa595db4a9d65c06ccc587",+ "assets": {+ "amd64": { "url": null, "sha256": null, "bytes": null },+ "arm64": { "url": null, "sha256": null, "bytes": null }+ }+}diff --git a/apps/server/src/capture-host.ts b/apps/server/src/capture-host.tsindex 3bd00905..38cb5063 100644--- a/apps/server/src/capture-host.ts+++ b/apps/server/src/capture-host.ts@@ -225,7 +225,7 @@ export class CaptureHost {}this.boxChats.set(sessionId, box.container);if (!this.boxViews.has(box.container)) {- const view = sandboxFilesUsed({ container: box.container, manifest: { home: "/root", workspaces: [box.croot] }, cwd: box.root, hostHome: null, docker: box.runtimeBin, dockerArgs: box.runtimeArgs, log: this.log });+ const view = sandboxFilesUsed({ container: box.container, manifest: { home: "/root", workspaces: [box.croot] }, cwd: box.root, hostHome: null, docker: box.runtimeBin, dockerArgs: box.runtimeArgs, exec: box.exec, log: this.log });if (view) this.boxViews.set(box.container, view);}}diff --git a/apps/server/src/server.ts b/apps/server/src/server.tsindex f08de642..60304401 100644--- a/apps/server/src/server.ts+++ b/apps/server/src/server.ts@@ -178,6 +178,7 @@ import {import { boxServiceFor } from "./box/desktop.js";import { prepareBoxInstallLog } from "./box/install-log.js";import { rememberServerDefault } from "./box/launch.js";+import { normalizeBackend } from "./box/backends/index.js";import { buildOmniRushRuntimeConfigObject, omnirushGatewayConfigured, omnirushRuntimeConfigFilePath, writeOmniRushRuntimeConfigFile } from "./omnirush-runtime-config.js";import { assertMcpAllowed, mcpAllowed, mcpPolicyForConfig, MCP_DISABLED_MESSAGE } from "./mcp-policy.js";import { omnirushModelWantsReasoningSummary, readOmniRushModelCatalog } from "./omnirush-model-catalog.js";@@ -3779,13 +3780,18 @@ function createRoutes(const workspace = await resolveWorkspace(config, ctx.params.id);const body = await readJsonBody(ctx.request);const mode = body.mode;- if ((mode !== "on" && mode !== "off" && mode !== null) || Object.keys(body).some((key) => key !== "mode")) {- throw new ApiError(400, "invalid_payload", "mode must be \"on\", \"off\" or null and the only field");+ const keys = Object.keys(body);+ // `mode`: the project's choice; `backend`: what runs boxes on this computer (auto, one backend id, native).+ if (!keys.length || keys.some((key) => key !== "mode" && key !== "backend")+ || ("mode" in body && mode !== "on" && mode !== "off" && mode !== null)+ || ("backend" in body && (typeof body.backend !== "string" || !normalizeBackend(body.backend)))) {+ throw new ApiError(400, "invalid_payload", "mode must be \"on\", \"off\" or null; backend must be \"auto\", a sandbox backend or \"native\"");}if (workspace.workspaceType !== "local") throw new ApiError(400, "box_unsupported", "The sandbox is for folders on this computer");const boxes = boxServiceFor(config);const before = JSON.stringify(await boxes.engineBits());- const status = await boxes.setMode(workspace, mode);+ if (typeof body.backend === "string") await boxes.setBackend(body.backend);+ const status = "mode" in body && (mode === "on" || mode === "off" || mode === null) ? await boxes.setMode(workspace, mode) : await boxes.status(workspace, { fresh: true });// The engine gets the box shell and plugin when the first workspace turns its box on (and loses them with the last).const engine = JSON.stringify(await boxes.engineBits()) === before ? { status: "unchanged" as const } : await applyBoxEngineConfig(config, "local_box");return jsonResponse({ ...status, engine });diff --git a/apps/server/src/session-archive/files-used-sandbox.ts b/apps/server/src/session-archive/files-used-sandbox.tsindex 2768d219..ccbd87d4 100644--- a/apps/server/src/session-archive/files-used-sandbox.ts+++ b/apps/server/src/session-archive/files-used-sandbox.ts@@ -172,7 +172,10 @@ export type ViewRunner = (request: unknown, maxOutputBytes: number) => Promise<R* failed, slow or oversized answer ends the process and the next request* starts another.*/-export function dockerExecRunner(container: string, docker = "docker", timeoutMs = STEP_TIMEOUT_MS, dockerArgs: readonly string[] = []): ViewRunner {+/** How to run a program in the box with stdin open (a box backend without `docker exec`: boxsh, `container exec`). */+export type BoxExec = { bin: string; args: readonly string[]; env?: Record<string, string> };++export function dockerExecRunner(container: string, docker = "docker", timeoutMs = STEP_TIMEOUT_MS, dockerArgs: readonly string[] = [], boxExec: BoxExec | null = null): ViewRunner {type Live = { child: ChildProcessWithoutNullStreams; buffer: Buffer[]; size: number; waiting: ((line: Buffer | null) => void) | null };let live: Live | null = null;let tail: Promise<unknown> = Promise.resolve();@@ -198,7 +201,9 @@ export function dockerExecRunner(container: string, docker = "docker", timeoutMsconst start = (): Live | null => {let child: ChildProcessWithoutNullStreams;try {- child = spawn(docker, [...dockerArgs, "exec", "-i", container, "/usr/bin/python3", "-I", "-c", FILES_USED_VIEW_SCRIPT], { stdio: ["pipe", "pipe", "ignore"] as const, windowsHide: true }) as unknown as ChildProcessWithoutNullStreams;+ child = (boxExec+ ? spawn(boxExec.bin, [...boxExec.args, "/usr/bin/python3", "-I", "-c", FILES_USED_VIEW_SCRIPT], { stdio: ["pipe", "pipe", "ignore"] as const, windowsHide: true, env: { ...process.env, ...(boxExec.env ?? {}) } })+ : spawn(docker, [...dockerArgs, "exec", "-i", container, "/usr/bin/python3", "-I", "-c", FILES_USED_VIEW_SCRIPT], { stdio: ["pipe", "pipe", "ignore"] as const, windowsHide: true })) as unknown as ChildProcessWithoutNullStreams;} catch {return null;}@@ -335,6 +340,8 @@ export function sandboxFilesUsed(input: {docker?: string;/** Arguments before docker's own (`-e docker` when docker is reached through wsl.exe). */dockerArgs?: readonly string[];+ /** The box backend's way in when it is not a container engine (bubblewrap, Apple container, the WSL distro). */+ exec?: BoxExec | null;log?: (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;}): FilesUsedSandbox | null {if (!input.container) return null;@@ -342,7 +349,7 @@ export function sandboxFilesUsed(input: {const home = typeof manifest.home === "string" && manifest.home.startsWith("/") ? manifest.home : "/home/omnirush";const workspaces = Array.isArray(manifest.workspaces) ? manifest.workspaces.filter((entry): entry is string => typeof entry === "string" && entry.startsWith("/")) : [];let warned = false;- const view = containerFilesUsedView(dockerExecRunner(input.container, input.docker || "docker", STEP_TIMEOUT_MS, input.dockerArgs ?? []), (op) => {+ const view = containerFilesUsedView(dockerExecRunner(input.container, input.docker || "docker", STEP_TIMEOUT_MS, input.dockerArgs ?? [], input.exec ?? null), (op) => {if (warned) return;warned = true;input.log?.("warn", "OmniRush files used: the sandbox could not be read; its files are listed, not kept", { op });