@engenty/wizards-runtime 0.7.5 → 0.7.7

package/apps/runtime/dist/env.js

@@ -1,9 +1,9 @@
-import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { findChrome } from "./render/browser-path.js";
+import { enginesDir } from "./sandbox/install.js";
 /** Load `.env.local` then `.env` without overriding the real environment. */
 function loadEnvFiles() {
     for (const name of [".env.local", ".env"]) {
@@ -22,29 +22,6 @@ function loadEnvFiles() {
 }
 loadEnvFiles();
 const str = (key, fallback = "") => process.env[key]?.trim() || fallback;
-/**
- * Without `SANDBOX`: Docker when the sandbox image is on this machine, else none.
- * The image is not published, so a fresh install would otherwise offer a tool that cannot start.
- */
-function sandboxEngine(image) {
-    const engine = str("SANDBOX");
-    if (str("SANDBOX_ENABLED", "1") !== "1" || engine === "off") {
-        return "off";
-    }
-    if (engine) {
-        return "docker";
-    }
-    return dockerHasImage(image) ? "docker" : "off";
-}
-function dockerHasImage(image) {
-    try {
-        execFileSync("docker", ["image", "inspect", image], { stdio: "ignore", timeout: 5000 });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /** A comma-separated list. */
 const list = (key) => str(key)
     .split(",")
@@ -217,9 +194,16 @@ export const env = {
             : "/usr/bin/chromium")),
     /** Encodes widget animations to MP4; without it widgets offer no video. */
     ffmpegPath: str("FFMPEG_PATH", "ffmpeg"),
-    /** What runs an agent's shell and code: a Docker container or nothing. */
-    sandbox: sandboxEngine(sandboxImage),
+    /**
+     * The engine that runs an agent's shell and code (sandbox/index.ts): `off`, an engine's name,
+     * or empty for the first one that is ready here.
+     */
+    sandbox: str("SANDBOX_ENABLED", "1") === "1" ? str("SANDBOX").toLowerCase() : "off",
     sandboxImage,
+    /** Where `wizards sandbox add` installs the engines that aren't part of the runtime. */
+    sandboxEngines: enginesDir(),
+    /** Hosts an agentOS sandbox reaches besides the npm and PyPI registries: `api.example.com`. */
+    sandboxHosts: list("SANDBOX_ALLOW_HOSTS"),
     /** Assets and workspace files in an S3-compatible bucket (R2); empty = the data folder. */
     s3: {
         endpoint: str("S3_ENDPOINT").replace(/\/$/, ""),

package/apps/runtime/dist/routes/runs.js

@@ -1,6 +1,6 @@
 import { FORMATS, isLang, LANG_CODE, LANGS, LIST_FORMATS, TEXT_CLASSES, wizardLang, } from "@engenty-wizards/shared/definition";
 import { TableColumnValueError } from "@engenty-wizards/shared/engenty/data-tables";
-import { noteText } from "@engenty-wizards/shared/run";
+import { noteText, } from "@engenty-wizards/shared/run";
 import { machineTranslated, translateDefinition, } from "@engenty-wizards/shared/translation";
 import { getConnInfo } from "@hono/node-server/conninfo";
 import { and, eq } from "drizzle-orm";
@@ -220,6 +220,18 @@ async function publishedWizard(token) {
 function wantsTranslation(w, def, lang) {
     return w.translate && lang !== wizardLang(def);
 }
+/** What the wizard's pages ask, in order (`PublicWizard.fields`). */
+export function pageFields(def) {
+    return def.steps.flatMap((step) => step.type === "page"
+        ? step.fields.map((f) => ({
+            id: f.id,
+            label: f.label,
+            kind: f.kind,
+            ...(f.options?.length ? { options: f.options } : {}),
+            ...(f.required ? { required: true } : {}),
+        }))
+        : []);
+}
 /** What a wizard's page shows before a run: in the viewer's language where `as` is given. */
 async function publicBody(c, w, original, as) {
     const translated = as ? translateDefinition(original, as.memory) : null;
@@ -245,6 +257,7 @@ async function publicBody(c, w, original, as) {
                 machine: machineTranslated(as.memory, original),
             }
             : null,
+        fields: pageFields(def),
     };
 }
 export const publicRoutes = new Hono()

package/apps/runtime/dist/sandbox/agentos-package.js

@@ -0,0 +1,73 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+/**
+ * What `wizards sandbox add agentos` installs (install.ts): agentOS's core, about 340 MB, which
+ * only the computers and servers that run the sandbox with it need.
+ */
+export const AGENTOS_VERSION = "0.4.1";
+export const AGENTOS_CORE = "@rivet-dev/agentos-core";
+/** The helper agentOS ships for each platform, beside the core: `<package>/agentos-native-sidecar`. */
+const SIDECAR_PACKAGE = "@rivet-dev/agentos-runtime-sidecar-";
+/** Where the core keeps its programs, compiled to WebAssembly. */
+const COMMANDS = join("node_modules", "@rivet-dev", "agentos-runtime-core", "commands");
+/**
+ * Programs agentOS ships but leaves off the PATH; the install packs them so every VM has them.
+ * The ones from the `@agentos-software` registry are in a format 0.4 no longer reads.
+ */
+export const AGENTOS_EXTRA_COMMANDS = ["curl", "git", "jq", "sqlite3", "unzip", "zip"];
+/** Dependencies of the core that its code never imports: Google and AWS clients, about 140 MB. */
+const UNUSED = ["googleapis", "googleapis-common", "@aws-sdk", "@smithy", "better-sqlite3"];
+/** agentOS ships its helper for macOS and glibc Linux, on arm64 and x64. */
+export function agentOsSupported(platform = process.platform, arch = process.arch) {
+    return ["darwin", "linux"].includes(platform) && ["arm64", "x64"].includes(arch);
+}
+/** The package of extra programs every VM gets (AGENTOS_EXTRA_COMMANDS). */
+export const agentOsExtras = (dir) => join(dir, "extras");
+/** The helper with its routine lines filtered out, or null where there is no bash. */
+export const agentOsSidecar = (dir) => join(dir, "sidecar.sh");
+/** An agentOS package is a folder with a manifest and its programs in `bin/`. */
+function packExtras(dir) {
+    const bin = join(agentOsExtras(dir), "bin");
+    mkdirSync(bin, { recursive: true });
+    for (const command of AGENTOS_EXTRA_COMMANDS) {
+        const target = join(bin, command);
+        copyFileSync(join(dir, COMMANDS, command), target);
+        // Without the mode, the VM finds the program and refuses to run it.
+        chmodSync(target, 0o755);
+    }
+    writeFileSync(join(agentOsExtras(dir), "agentos-package.json"), `${JSON.stringify({ name: "engenty-wizards-extras", version: AGENTOS_VERSION })}\n`);
+}
+/**
+ * The helper prints a line on stderr for every engine it keeps warm, a few per command, and
+ * agentOS passes its stderr on to the server's. The wrapper leaves those lines out.
+ */
+function writeSidecarWrapper(dir) {
+    const bash = ["/bin/bash", "/usr/bin/bash"].find((path) => existsSync(path));
+    const modules = join(dir, "node_modules", "@rivet-dev");
+    const platform = readdirSync(modules).find((name) => `@rivet-dev/${name}`.startsWith(SIDECAR_PACKAGE));
+    const helper = platform && join(modules, platform, "agentos-native-sidecar");
+    if (!bash || !helper || !existsSync(helper)) {
+        return;
+    }
+    const quoted = `'${helper.replaceAll("'", `'\\''`)}'`;
+    writeFileSync(agentOsSidecar(dir), `#!${bash}\n` +
+        "# agentOS's helper without the lines it prints for every engine it keeps warm.\n" +
+        `exec ${quoted} "$@" 2> >(grep --line-buffered -v -e '^agentos-v8-runtime: ' -e 'vfs::posix::tar_fs' >&2)\n`);
+    chmodSync(agentOsSidecar(dir), 0o755);
+}
+export const AGENTOS_PACKAGE = {
+    label: "agentOS",
+    version: AGENTOS_VERSION,
+    packages: [`${AGENTOS_CORE}@${AGENTOS_VERSION}`],
+    size: "about 340 MB",
+    unsupported: () => agentOsSupported()
+        ? null
+        : `agentOS runs on macOS and Linux (arm64, x64), not on ${process.platform} ${process.arch}.`,
+    prepare(dir) {
+        for (const name of UNUSED) {
+            rmSync(join(dir, "node_modules", name), { recursive: true, force: true });
+        }
+        packExtras(dir);
+        writeSidecarWrapper(dir);
+    },
+};

package/apps/runtime/dist/sandbox/agentos.js

@@ -0,0 +1,162 @@
+import { existsSync } from "node:fs";
+import { join, posix } from "node:path";
+import { env } from "../env.js";
+import { AGENTOS_CORE, AGENTOS_EXTRA_COMMANDS, agentOsExtras, agentOsSidecar, } from "./agentos-package.js";
+import { importFromEngine, installedVersion } from "./install.js";
+const WORKDIR = "/workspace";
+const EXEC_TIMEOUT_MS = 120_000;
+/**
+ * Python starts in $HOME, whatever directory the shell is in. Before each command, `python3`
+ * becomes a function that hands it the shell's directory as HOME.
+ */
+const PYTHON_FOLLOWS_CD = 'python3() { HOME="$PWD" command python3 "$@"; }; python() { python3 "$@"; }\n';
+/** Where npm and Python packages come from: every VM reaches them. */
+const REGISTRIES = ["registry.npmjs.org", "pypi.org", "files.pythonhosted.org"];
+/**
+ * What an agentOS VM runs: a Linux userland compiled to WebAssembly (bash, coreutils and the
+ * extra programs the install packs), Node in a V8 isolate and Python 3.13 as Pyodide. No native
+ * programs: no ffmpeg, ImageMagick or LibreOffice.
+ */
+export function agentOsCapabilities(hosts = []) {
+    return {
+        commands: [
+            "bash",
+            "ls",
+            "cat",
+            "head",
+            "sort",
+            "grep",
+            "sed",
+            "awk",
+            "find",
+            "diff",
+            "tar",
+            "gzip",
+            ...AGENTOS_EXTRA_COMMANDS,
+            "node",
+            "npm",
+            "python3",
+        ],
+        network: hosts.length
+            ? `only the npm and PyPI registries and ${hosts.join(", ")}`
+            : "none, except the npm and PyPI registries",
+        notes: "python3 is Pyodide: numpy and pandas load offline; install other pure-Python packages with " +
+            `python3 -c "import micropip; await micropip.install('openpyxl')" (no pip command, no ` +
+            "pillow, matplotlib or scipy). node runs JavaScript, not TypeScript.",
+        uses: "calculations, tables or file conversion",
+        workdir: WORKDIR,
+    };
+}
+let runtime = null;
+/** One native helper process hosts the VMs of every run; the first sandbox starts it. */
+function agentOsRuntime(dir) {
+    runtime ??= (async () => {
+        // agentOS reads the helper's path from the environment when it starts the helper.
+        if (!process.env.AGENTOS_SIDECAR_BIN && existsSync(agentOsSidecar(dir))) {
+            process.env.AGENTOS_SIDECAR_BIN = agentOsSidecar(dir);
+        }
+        const mod = (await importFromEngine("agentos", dir, AGENTOS_CORE));
+        return { agentOs: mod.AgentOs, sidecar: await mod.AgentOs.createSidecar() };
+    })().catch((err) => {
+        runtime = null;
+        throw err;
+    });
+    return runtime;
+}
+/** Stops the helper process. The next sandbox starts a new one. */
+export async function stopAgentOs() {
+    const current = runtime;
+    runtime = null;
+    await (await current?.catch(() => null))?.sidecar.dispose();
+}
+function toResult(result) {
+    const stdout = result.stdout ?? "";
+    let stderr = result.stderr ?? "";
+    if (result.outcome === "timed_out") {
+        stderr = `${stderr}\ntimed out`.trim();
+    }
+    else if (result.outcome !== "succeeded" && !stdout && !stderr) {
+        stderr = result.error?.message ?? result.outcome;
+    }
+    return { exitCode: result.exitCode ?? (result.outcome === "succeeded" ? 0 : 1), stdout, stderr };
+}
+/** Where `wizards sandbox add agentos` put it. */
+export const agentOsDir = () => join(env.sandboxEngines, "agentos");
+/** Ready once `wizards sandbox add agentos` installed it. */
+export const agentOsEngine = {
+    name: "agentos",
+    ready: () => installedVersion(agentOsDir()) !== null,
+    capabilities: () => agentOsCapabilities(env.sandboxHosts),
+    create: () => new AgentOsSandbox(),
+};
+/** One agentOS VM per run, in the server's helper process: no Docker, no container. */
+export class AgentOsSandbox {
+    dir;
+    hosts;
+    capabilities;
+    machine = null;
+    constructor(dir = agentOsDir(), hosts = env.sandboxHosts) {
+        this.dir = dir;
+        this.hosts = hosts;
+        this.capabilities = agentOsCapabilities(hosts);
+    }
+    vm() {
+        this.machine ??= (async () => {
+            const { agentOs, sidecar } = await agentOsRuntime(this.dir);
+            const vm = await agentOs.create({
+                sidecar: { kind: "explicit", handle: sidecar },
+                software: [{ packagePath: agentOsExtras(this.dir) }],
+                // Anything not listed is refused, the host's own loopback and private networks included.
+                permissions: {
+                    fs: "allow",
+                    childProcess: "allow",
+                    process: "allow",
+                    env: "allow",
+                    network: {
+                        default: "deny",
+                        rules: [
+                            {
+                                mode: "allow",
+                                operations: ["*"],
+                                patterns: [...REGISTRIES, ...this.hosts].flatMap((host) => [
+                                    `dns://${host}`,
+                                    `tcp://${host}:443`,
+                                ]),
+                            },
+                        ],
+                    },
+                },
+            });
+            await vm.filesystem.mkdir(WORKDIR, { recursive: true });
+            return vm;
+        })();
+        this.machine.catch(() => {
+            this.machine = null;
+        });
+        return this.machine;
+    }
+    async exec(command, options = {}) {
+        const vm = await this.vm();
+        return toResult(await vm.process.exec(PYTHON_FOLLOWS_CD + command, {
+            cwd: options.cwd ?? WORKDIR,
+            env: { HOME: WORKDIR, ...options.env },
+            timeoutMs: options.timeoutMs ?? EXEC_TIMEOUT_MS,
+            output: { capture: "all" },
+        }));
+    }
+    async writeFile(path, data) {
+        const vm = await this.vm();
+        const target = posix.resolve(WORKDIR, path);
+        await vm.filesystem.mkdir(posix.dirname(target), { recursive: true });
+        await vm.filesystem.writeFile(target, data);
+    }
+    async readFile(path) {
+        const vm = await this.vm();
+        return vm.filesystem.readFile(posix.resolve(WORKDIR, path));
+    }
+    async destroy() {
+        const machine = this.machine;
+        this.machine = null;
+        await (await machine?.catch(() => null))?.dispose();
+    }
+}

package/apps/runtime/dist/sandbox/docker.js

@@ -1,8 +1,9 @@
+import { execFileSync } from "node:child_process";
 import { DockerSandbox } from "@mastra/docker";
+import { env } from "../env.js";
+import { MastraRunSandbox } from "./mastra.js";
 /** The image's own working directory, the one its unprivileged user may write to. */
 const WORKDIR = "/sandbox";
-/** Bytes per append when a file is written through the shell; stays far below ARG_MAX. */
-const WRITE_CHUNK = 48 * 1024;
 /** What the engenty-sandbox image carries. The container sits on Docker's default bridge. */
 export const DOCKER_CAPABILITIES = {
     commands: ["bash", "python3", "pip", "uv", "node", "npm", "bun", "jq", "curl", "git", "unzip"],
@@ -10,66 +11,35 @@ export const DOCKER_CAPABILITIES = {
     uses: "calculations, charts or file conversion",
     workdir: WORKDIR,
 };
-const quote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
-/** One container per run through the host's Docker. */
-export class DockerRunSandbox {
-    runId;
-    image;
-    capabilities = DOCKER_CAPABILITIES;
-    container = null;
-    constructor(runId, image) {
-        this.runId = runId;
-        this.image = image;
-    }
-    start() {
-        this.container ??= (async () => {
-            const sandbox = new DockerSandbox({
-                id: `wizards-${this.runId.toLowerCase()}`,
-                image: this.image,
-                memory: 1024 * 1024 * 1024,
-                pidsLimit: 256,
-                capDrop: ["ALL"],
-                securityOpt: ["no-new-privileges"],
-                workingDir: WORKDIR,
-                labels: { "engenty-wizards.run": this.runId },
-            });
-            await sandbox.start();
-            return sandbox;
-        })();
-        return this.container;
-    }
-    async exec(command, options = {}) {
-        const sandbox = await this.start();
-        const result = await sandbox.executeCommand(command, [], {
-            timeout: options.timeoutMs,
-            cwd: options.cwd,
-            env: options.env,
-        });
-        return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
-    }
-    async writeFile(path, data) {
-        const target = quote(path);
-        const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
-        await this.must(`mkdir -p "$(dirname ${target})" && : > ${target}`);
-        for (let at = 0; at < bytes.length; at += WRITE_CHUNK) {
-            const chunk = bytes.subarray(at, at + WRITE_CHUNK).toString("base64");
-            await this.must(`printf %s ${chunk} | base64 -d >> ${target}`);
-        }
-    }
-    async readFile(path) {
-        const result = await this.must(`base64 -w0 ${quote(path)}`);
-        return Buffer.from(result.stdout.trim(), "base64");
-    }
-    async must(command) {
-        const result = await this.exec(command);
-        if (result.exitCode !== 0) {
-            throw new Error(result.stderr.trim() || `exit code ${result.exitCode}`);
-        }
-        return result;
+/** One container per run through the host's Docker, with Mastra's Docker sandbox. */
+export function dockerSandbox(runId, image) {
+    return new MastraRunSandbox(DOCKER_CAPABILITIES, () => new DockerSandbox({
+        id: `wizards-${runId.toLowerCase()}`,
+        image,
+        memory: 1024 * 1024 * 1024,
+        pidsLimit: 256,
+        capDrop: ["ALL"],
+        securityOpt: ["no-new-privileges"],
+        workingDir: WORKDIR,
+        labels: { "engenty-wizards.run": runId },
+    }));
+}
+export function dockerHasImage(image) {
+    try {
+        execFileSync("docker", ["image", "inspect", image], { stdio: "ignore", timeout: 5000 });
+        return true;
     }
-    async destroy() {
-        const container = this.container;
-        this.container = null;
-        await (await container?.catch(() => null))?.destroy();
+    catch {
+        return false;
     }
 }
+/**
+ * Ready where Docker has the sandbox image (`SANDBOX_IMAGE`). The image is not published, so
+ * without the check a fresh install would offer a tool that cannot start.
+ */
+export const dockerEngine = {
+    name: "docker",
+    ready: () => dockerHasImage(env.sandboxImage),
+    capabilities: () => DOCKER_CAPABILITIES,
+    create: (runId) => dockerSandbox(runId, env.sandboxImage),
+};

package/apps/runtime/dist/sandbox/index.js

@@ -1,20 +1,49 @@
 import { env } from "../env.js";
-import { DOCKER_CAPABILITIES, DockerRunSandbox } from "./docker.js";
-/** What this server's sandbox runs, or null when it is switched off. */
-export function sandboxCapabilities() {
-    if (env.sandbox === "off") {
+import { agentOsEngine } from "./agentos.js";
+import { DOCKER_CAPABILITIES, dockerEngine } from "./docker.js";
+/**
+ * The engines, in the order one is picked when `SANDBOX` names none. Another engine joins
+ * here: one of Mastra's sandboxes through MastraRunSandbox (mastra.ts), its package installed
+ * with `wizards sandbox add <name>` when it isn't a dependency of the runtime (install.ts).
+ */
+export const ENGINES = [dockerEngine, agentOsEngine];
+/**
+ * `off`: none. An engine's name: that one, ready or not; it says what is missing when a run
+ * uses it. Empty: the first engine that is ready here.
+ */
+export function pickEngine(engines, requested) {
+    if (requested === "off") {
         return null;
     }
-    return DOCKER_CAPABILITIES;
+    if (requested) {
+        const engine = engines.find((e) => e.name === requested);
+        if (!engine) {
+            console.warn(`SANDBOX=${requested} is no engine (${engines.map((e) => e.name).join(", ")} or off): the sandbox is off.`);
+        }
+        return engine ?? null;
+    }
+    return engines.find((e) => e.ready()) ?? null;
+}
+let picked = null;
+/** The engine of this server, picked once at the first question. */
+export function sandboxEngine() {
+    picked ??= { engine: pickEngine(ENGINES, env.sandbox) };
+    return picked.engine;
+}
+/** What this server's sandbox runs, or null when it is switched off. */
+export function sandboxCapabilities() {
+    return sandboxEngine()?.capabilities() ?? null;
 }
 export function createSandbox(runId) {
-    if (env.sandbox === "off") {
+    const engine = sandboxEngine();
+    if (!engine) {
         throw new Error("The sandbox is switched off on this server.");
     }
-    return new DockerRunSandbox(runId, env.sandboxImage);
+    return engine.create(runId);
 }
 export function shellToolDescription(caps) {
-    return `Run a shell command in a private Linux sandbox (${caps.commands.join(", ")}). Working directory ${caps.workdir}. Network: ${caps.network}.`;
+    const notes = caps.notes ? ` ${caps.notes}` : "";
+    return `Run a shell command in a private Linux sandbox (${caps.commands.join(", ")}). Working directory ${caps.workdir}. Network: ${caps.network}.${notes}`;
 }
 /** The authoring guide's line about the sandbox tool. */
 export function sandboxGuideLine() {

package/apps/runtime/dist/sandbox/install.js

@@ -0,0 +1,122 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { wizardsHome } from "../cli/home.js";
+import { AGENTOS_PACKAGE } from "./agentos-package.js";
+export const ENGINE_PACKAGES = {
+    agentos: AGENTOS_PACKAGE,
+};
+/** Written last: a folder without it is an install that did not finish. */
+const MARKER = "engine.json";
+/** Where the engines go: `SANDBOX_ENGINES_DIR`, else `~/.engenty/wizards/engines`. */
+export function enginesDir(env = process.env) {
+    return resolve(env.SANDBOX_ENGINES_DIR?.trim() || join(wizardsHome(env), "engines"));
+}
+export const engineDir = (name, env = process.env) => join(enginesDir(env), name);
+/** The version installed in `dir`, or null when nothing usable is there. */
+export function installedVersion(dir) {
+    try {
+        const { version } = JSON.parse(readFileSync(join(dir, MARKER), "utf8"));
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The file an export map's entry names for `import`: conditions may nest (`import.default`). */
+function importTarget(target) {
+    if (typeof target === "string") {
+        return target;
+    }
+    if (Array.isArray(target)) {
+        return target.map(importTarget).find(Boolean);
+    }
+    if (target && typeof target === "object") {
+        for (const condition of ["import", "node", "default"]) {
+            const found = importTarget(target[condition]);
+            if (found) {
+                return found;
+            }
+        }
+    }
+    return undefined;
+}
+/** A package of an engine's folder, for `import()`: its export map's `.`, else its main. */
+export function packageEntry(dir, name) {
+    const root = join(dir, "node_modules", name);
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const { exports } = pkg;
+    const dot = exports && typeof exports === "object" && "." in exports ? exports["."] : exports;
+    return join(root, importTarget(dot) ?? pkg.main ?? "index.js");
+}
+/** Loads a package an engine installed; says how to install it when it isn't there. */
+export async function importFromEngine(engine, dir, name) {
+    if (!installedVersion(dir)) {
+        throw new Error(`${engine} isn’t installed in ${dir}: wizards sandbox add ${engine}`);
+    }
+    return import(pathToFileURL(packageEntry(dir, name)).href);
+}
+/**
+ * Installs an engine into `dir` with the given npm, replacing what was there. Install scripts do
+ * not run; an engine that needs one does its work in `prepare`.
+ */
+export async function installEngine(name, dir, npm) {
+    const engine = ENGINE_PACKAGES[name];
+    if (!engine) {
+        throw new Error(`There is no engine “${name}” to install. ${engineList()}`);
+    }
+    const unsupported = engine.unsupported?.();
+    if (unsupported) {
+        throw new Error(unsupported);
+    }
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), '{ "private": true }\n');
+    const result = await npm([
+        "install",
+        "--prefix",
+        dir,
+        "--no-audit",
+        "--no-fund",
+        "--ignore-scripts",
+        "--loglevel=error",
+        ...engine.packages,
+    ]);
+    if (result.code !== 0) {
+        throw new Error(`npm couldn’t install ${name}: ${result.tail.trim().split("\n").at(-1)}`);
+    }
+    engine.prepare?.(dir);
+    writeFileSync(join(dir, MARKER), `${JSON.stringify({ name, version: engine.version }, null, 2)}\n`);
+    return engine.version;
+}
+export function removeEngine(dir) {
+    rmSync(dir, { recursive: true, force: true });
+}
+export const engineList = () => `The engines to install: ${Object.keys(ENGINE_PACKAGES).join(", ")}.`;
+/** `node apps/runtime/dist/sandbox/install.js agentos …`: an image or a checkout installs so. */
+if (import.meta.main) {
+    const { spawn } = await import("node:child_process");
+    const npm = (args) => new Promise((resolve) => {
+        const child = spawn("npm", args, { stdio: ["ignore", "inherit", "inherit"] });
+        child.on("error", (err) => resolve({ code: 127, tail: err.message }));
+        child.on("close", (code) => resolve({ code: code ?? 1, tail: "" }));
+    });
+    const names = process.argv
+        .slice(2)
+        .flatMap((arg) => arg.split(","))
+        .filter(Boolean);
+    if (!names.length) {
+        console.error(`Name the engines to install. ${engineList()}`);
+        process.exitCode = 2;
+    }
+    for (const name of names) {
+        try {
+            const version = await installEngine(name, engineDir(name), npm);
+            console.log(`${name} ${version} is installed in ${engineDir(name)}.`);
+        }
+        catch (err) {
+            console.error(err.message);
+            process.exitCode = 1;
+        }
+    }
+}