humanish 0.137.0 → 0.139.0

package/dist/substrates/modal/desktop.js

@@ -0,0 +1,195 @@
+// A desktop in a Modal sandbox, with @e2b/desktop's behavior: the same Xvfb and XFCE start, the
+// same xdotool commands for each input, scrot for screenshots and x11vnc behind noVNC for the live
+// stream. The executor and every e2b-desktop module were tuned against that SDK, so this follows it
+// command for command (the Sandbox class of @e2b/desktop 2.4.0) rather than improving on it.
+import { randomBytes } from "node:crypto";
+import { shellQuote } from "../shell.js";
+/** The X display and the ports the desktop's stream uses, as @e2b/desktop sets them. */
+export const MODAL_DESKTOP_DISPLAY = ":0";
+const VNC_PORT = 5900;
+export const MODAL_STREAM_PORT = 6080;
+const KEYS = {
+    alt: "Alt_L",
+    alt_left: "Alt_L",
+    alt_right: "Alt_R",
+    backspace: "BackSpace",
+    break: "Pause",
+    caps_lock: "Caps_Lock",
+    cmd: "Super_L",
+    command: "Super_L",
+    control: "Control_L",
+    control_left: "Control_L",
+    control_right: "Control_R",
+    ctrl: "Control_L",
+    del: "Delete",
+    delete: "Delete",
+    down: "Down",
+    end: "End",
+    enter: "Return",
+    esc: "Escape",
+    escape: "Escape",
+    f1: "F1",
+    f2: "F2",
+    f3: "F3",
+    f4: "F4",
+    f5: "F5",
+    f6: "F6",
+    f7: "F7",
+    f8: "F8",
+    f9: "F9",
+    f10: "F10",
+    f11: "F11",
+    f12: "F12",
+    home: "Home",
+    insert: "Insert",
+    left: "Left",
+    menu: "Menu",
+    meta: "Meta_L",
+    num_lock: "Num_Lock",
+    page_down: "Page_Down",
+    page_up: "Page_Up",
+    pause: "Pause",
+    print: "Print",
+    right: "Right",
+    scroll_lock: "Scroll_Lock",
+    shift: "Shift_L",
+    shift_left: "Shift_L",
+    shift_right: "Shift_R",
+    space: "space",
+    super: "Super_L",
+    super_left: "Super_L",
+    super_right: "Super_R",
+    tab: "Tab",
+    up: "Up",
+    win: "Super_L",
+    windows: "Super_L",
+};
+const mapKey = (key) => KEYS[key.toLowerCase()] ?? key.toLowerCase();
+/** Run `command` every `intervalMs` until it exits 0, for at most `timeoutMs`. */
+async function waitUntil(run, command, timeoutMs, intervalMs = 500) {
+    for (const end = Date.now() + timeoutMs; Date.now() < end;) {
+        try {
+            await run(command);
+            return true;
+        }
+        catch (error) {
+            if (error.name !== "CommandExitError")
+                throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    return false;
+}
+/** Start Xvfb at the requested size, then an XFCE session, as @e2b/desktop's create does. */
+export async function startModalDesktop(run, options) {
+    const [width, height] = options.resolution ?? [1024, 768];
+    const display = MODAL_DESKTOP_DISPLAY;
+    await run(`setsid -f Xvfb ${display} -ac -screen 0 ${width}x${height}x24 -retro -dpi ${options.dpi ?? 96} -nolisten tcp -nolisten unix </dev/null >/tmp/xvfb.log 2>&1`);
+    if (!(await waitUntil(run, `xdpyinfo -display ${display} >/dev/null`, 10_000)))
+        throw new Error("Could not start Xvfb");
+    await run("setsid -f startxfce4 </dev/null >/tmp/xfce4.log 2>&1");
+    if (!(await waitUntil(run, "pgrep -x xfce4-session >/dev/null && pgrep -x xfwm4 >/dev/null && pgrep -x xfdesktop >/dev/null", 60_000, 1_000)))
+        throw new Error("Could not start XFCE");
+}
+/**
+ * The desktop half of a sandbox handle. `hosts` maps each tunneled port to the host Modal serves it
+ * on; `readBytes` reads a file in the sandbox.
+ */
+export function modalDesktopSurface(run, readBytes, hosts) {
+    const getHost = (port) => {
+        const host = hosts.get(port);
+        if (host === undefined)
+            throw new Error(`Port ${port} has no Modal tunnel in this sandbox.`);
+        return host;
+    };
+    const moveMouse = async (x, y) => {
+        await run(`xdotool mousemove --sync ${x} ${y}`);
+    };
+    // The SDK moves only when both coordinates are truthy, so a click at x or y 0 clicks in place.
+    const clickAt = async (x, y, click) => {
+        if (x && y)
+            await moveMouse(x, y);
+        await run(`xdotool click ${click}`);
+    };
+    let streamUrl;
+    let password;
+    return {
+        getHost,
+        async screenshot() {
+            const path = `/tmp/screenshot-${randomBytes(8).toString("hex")}.png`;
+            await run(`scrot --pointer ${path}`);
+            try {
+                return await readBytes(path);
+            }
+            finally {
+                void run(`rm -f ${path}`).catch(() => { });
+            }
+        },
+        wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        leftClick: (x, y) => clickAt(x, y, "1"),
+        rightClick: (x, y) => clickAt(x, y, "3"),
+        middleClick: (x, y) => clickAt(x, y, "2"),
+        doubleClick: (x, y) => clickAt(x, y, "--repeat 2 1"),
+        moveMouse,
+        async getCursorPosition() {
+            const result = await run("xdotool getmouselocation");
+            const match = (result.stdout ?? "").match(/x:(\d+)\s+y:(\d+)/);
+            if (!match)
+                throw new Error(`Failed to parse cursor position from output: ${result.stdout}`);
+            return { x: Number.parseInt(match[1], 10), y: Number.parseInt(match[2], 10) };
+        },
+        async scroll(direction = "down", amount = 1) {
+            await run(`xdotool click --repeat ${amount} ${direction === "up" ? "4" : "5"}`);
+        },
+        async write(text) {
+            for (let at = 0; at < text.length; at += 25)
+                await run(`xdotool type --delay 75 -- ${shellQuote(text.slice(at, at + 25))}`);
+        },
+        async press(key) {
+            await run(`xdotool key ${Array.isArray(key) ? key.map(mapKey).join("+") : mapKey(key)}`);
+        },
+        async drag(from, to) {
+            await moveMouse(...from);
+            await run("xdotool mousedown 1");
+            await moveMouse(...to);
+            await run("xdotool mouseup 1");
+        },
+        async open(fileOrUrl) {
+            await run(`setsid -f xdg-open ${fileOrUrl} </dev/null >/dev/null 2>&1`);
+        },
+        async launch(application, uri) {
+            await run(`setsid -f gtk-launch ${application} ${uri ?? ""} </dev/null >/dev/null 2>&1`);
+        },
+        stream: {
+            getAuthKey() {
+                if (password === undefined)
+                    throw new Error("Unable to retrieve stream auth key, check if requireAuth is enabled");
+                return password;
+            },
+            getUrl({ autoConnect = true, viewOnly = false, resize = "scale", authKey } = {}) {
+                if (streamUrl === undefined)
+                    throw new Error("Server is not running");
+                const url = new URL(streamUrl);
+                if (autoConnect)
+                    url.searchParams.set("autoconnect", "true");
+                if (viewOnly)
+                    url.searchParams.set("view_only", "true");
+                if (resize)
+                    url.searchParams.set("resize", resize);
+                if (authKey)
+                    url.searchParams.set("password", authKey);
+                return url.toString();
+            },
+            async start({ requireAuth = false, windowId } = {}) {
+                password = requireAuth ? randomBytes(12).toString("base64url") : undefined;
+                streamUrl = new URL(`https://${getHost(MODAL_STREAM_PORT)}/vnc.html`);
+                if (password !== undefined)
+                    await run(`mkdir -p ~/.vnc && x11vnc -storepasswd ${password} ~/.vnc/passwd`);
+                await run(`x11vnc -bg -display ${MODAL_DESKTOP_DISPLAY} -forever -wait 50 -shared -rfbport ${VNC_PORT} ${password === undefined ? "-nopw" : "-usepw"} 2>/tmp/x11vnc_stderr.log${windowId === undefined ? "" : ` -id ${windowId}`}`);
+                await run(`setsid -f websockify --web /usr/share/novnc ${MODAL_STREAM_PORT} localhost:${VNC_PORT} </dev/null >/tmp/novnc.log 2>&1`);
+                if (!(await waitUntil(run, `netstat -tuln | grep ":${MODAL_STREAM_PORT} "`, 10_000)))
+                    throw new Error("Could not start noVNC server");
+            },
+        },
+    };
+}

package/dist/substrates/modal/image.d.ts

@@ -0,0 +1,11 @@
+import type { ModalClient, ModalImage } from "./sdk.js";
+/** The sandbox account commands run as, matching E2B's `user` and its home. */
+export declare const MODAL_SANDBOX_USER: {
+    readonly name: "user";
+    readonly uid: 1000;
+    readonly home: "/home/user";
+};
+/** The terminal route's image: a Debian shell with a passwordless-sudo `user`, as on E2B. */
+export declare function modalShellImage(client: ModalClient): ModalImage;
+/** The computer-use route's image: the shell's packages and an XFCE desktop with Chromium. */
+export declare function modalDesktopImage(client: ModalClient): ModalImage;

package/dist/substrates/modal/image.js

@@ -0,0 +1,71 @@
+const DEBIAN_BASE = "debian@sha256:7792b1f7702a86946cd518db72b6a407302c3e9bc1635634368b878189e8221c";
+const DEBIAN_SNAPSHOT = "20260923T083042Z";
+const SECURITY_SNAPSHOT = "20260922T123247Z";
+/** The sandbox account commands run as, matching E2B's `user` and its home. */
+export const MODAL_SANDBOX_USER = { name: "user", uid: 1000, home: "/home/user" };
+const SNAPSHOT_SOURCES = `printf 'Types: deb\\nURIs: http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}/\\nSuites: trixie trixie-updates\\nComponents: main\\nSigned-By: /usr/share/keyrings/debian-archive-keyring.gpg\\nCheck-Valid-Until: no\\n\\nTypes: deb\\nURIs: http://snapshot.debian.org/archive/debian-security/${SECURITY_SNAPSHOT}/\\nSuites: trixie-security\\nComponents: main\\nSigned-By: /usr/share/keyrings/debian-archive-keyring.gpg\\nCheck-Valid-Until: no\\n'` +
+    " > /etc/apt/sources.list.d/humanish.sources";
+// What the terminal route's steps call: the Node bootstrap's prerequisites (curl, coreutils, tar,
+// gzip, sudo), git for product installs, and python3 and unzip, which E2B's stock template has.
+const SHELL_PACKAGES = [
+    "bash",
+    "ca-certificates",
+    "curl",
+    "git",
+    "gzip",
+    "less",
+    "procps",
+    "python3",
+    "sudo",
+    "tar",
+    "unzip",
+    "xz-utils",
+];
+// What the e2b-desktop modules call in a desktop, beside the shell's packages: Xvfb and an XFCE
+// session as @e2b/desktop starts them, xdotool and scrot for input and screenshots, x11vnc and
+// noVNC for the stream, the X utilities the geometry and screen probes run, wmctrl, ffmpeg and
+// PulseAudio for recordings, Chromium, and fonts for Latin, Chinese, Japanese, Korean and emoji
+// text.
+const DESKTOP_PACKAGES = [
+    "chromium",
+    "dbus-x11",
+    "ffmpeg",
+    "fonts-dejavu",
+    "fonts-noto-cjk",
+    "fonts-noto-color-emoji",
+    "net-tools",
+    "novnc",
+    "pulseaudio",
+    "pulseaudio-utils",
+    "scrot",
+    "websockify",
+    "wmctrl",
+    "x11-utils",
+    "x11-xserver-utils",
+    "x11vnc",
+    "xdg-utils",
+    "xdotool",
+    "xfce4",
+    "xfce4-terminal",
+    "xvfb",
+];
+/** The terminal route's image: a Debian shell with a passwordless-sudo `user`, as on E2B. */
+export function modalShellImage(client) {
+    return debianImage(client, SHELL_PACKAGES);
+}
+/** The computer-use route's image: the shell's packages and an XFCE desktop with Chromium. */
+export function modalDesktopImage(client) {
+    return debianImage(client, [...SHELL_PACKAGES, ...DESKTOP_PACKAGES]);
+}
+function debianImage(client, packages) {
+    const { name, uid, home } = MODAL_SANDBOX_USER;
+    // prose-check: script
+    return client.images
+        .fromRegistry(DEBIAN_BASE)
+        .dockerfileCommands([
+        "ENV DEBIAN_FRONTEND=noninteractive",
+        `RUN rm -f /etc/apt/sources.list /etc/apt/sources.list.d/* && ${SNAPSHOT_SOURCES} && apt-get update && apt-get install -y --no-install-recommends ${packages.join(" ")} && rm -rf /var/lib/apt/lists/*`,
+        `RUN useradd --uid ${uid} --create-home --home-dir ${home} --shell /bin/bash ${name} && printf '${name} ALL=(ALL) NOPASSWD:ALL\\n' > /etc/sudoers.d/${name} && chmod 0440 /etc/sudoers.d/${name}`,
+        `WORKDIR ${home}`,
+    ]);
+}

package/dist/substrates/modal/sandbox.d.ts

@@ -0,0 +1,30 @@
+import type { E2BDesktopModule } from "../e2b/sdk.js";
+import type { E2BAccount } from "../e2b/connection.js";
+import { type ModalClient, type ModalConnection, type ModalImage, type ModalModule } from "./sdk.js";
+/** The size and image of the sandboxes one module creates. */
+export interface ModalSandboxProfile {
+    image: (client: ModalClient) => ModalImage;
+    /** Physical cores; Modal counts one core as two vCPU. */
+    cpu: number;
+    memoryMiB: number;
+    /** Start an X desktop after create and tunnel its stream, as @e2b/desktop's create does. */
+    desktop?: true;
+}
+/**
+ * A sandbox port over one Modal account. `create` maps E2B's create options onto Modal's; `kill`,
+ * `getInfo` and `list` keep the E2B SDK's contracts, which release and reclaim read.
+ */
+export declare function modalSandboxModule(client: ModalClient, connection: ModalConnection, profile: ModalSandboxProfile): E2BDesktopModule;
+/**
+ * The calls on sandboxes that already exist, with the E2B SDK's contracts: `kill` is true when it
+ * ended a running sandbox and false when the sandbox was gone, `getInfo` throws an error named
+ * SandboxNotFoundError for a gone id, and `list` filters by every given tag. None of them creates
+ * anything, so `reclaim --check` stays read-only.
+ */
+export declare function modalSandboxes(client: ModalClient, connection: ModalConnection): Required<E2BAccount>;
+/** The Modal account `env` names, for release by id and reclaim. Throws when it names none. */
+export declare function modalAccount(env: Readonly<Record<string, string | undefined>>, load?: () => Promise<ModalModule>): Promise<Required<E2BAccount>>;
+/** A sandbox port that creates the computer-use route's desktops on the Modal account `env` names. */
+export declare function loadModalDesktopModule(env: Readonly<Record<string, string | undefined>>, load?: () => Promise<ModalModule>): Promise<E2BDesktopModule>;
+/** A sandbox port that creates the terminal route's shell sandboxes on the Modal account `env` names. */
+export declare function loadModalShellModule(env: Readonly<Record<string, string | undefined>>, load?: () => Promise<ModalModule>): Promise<E2BDesktopModule>;

package/dist/substrates/modal/sandbox.js

@@ -0,0 +1,325 @@
+// Modal sandboxes behind the sandbox port the E2B routes already use (E2BDesktopModule and
+// E2BDesktopSandbox in src/substrates/e2b/sdk.ts). acquire() in src/substrates/e2b/sandbox.ts,
+// the receipts, the release by id and reclaim then work the same on both providers.
+//
+// Modal runs every exec as root and ignores the image's user setting, so each command drops to the
+// sandbox user here, the account E2B runs commands as. Sandboxes use Modal's VM runtime: its
+// default gVisor runtime sets no_new_privs on every process, so the user's sudo, which the Node
+// bootstrap and product installs run, cannot work there.
+import { E2BDesktopStartupError, reportDesktopAllocation } from "../e2b/sdk.js";
+import { readBytes, readFile, runCommand, sandboxPath, wholeSeconds, writeFile, } from "./commands.js";
+import { MODAL_DESKTOP_DISPLAY, MODAL_STREAM_PORT, modalDesktopSurface, startModalDesktop, } from "./desktop.js";
+import { MODAL_SANDBOX_USER, modalDesktopImage, modalShellImage } from "./image.js";
+import { isModalNotFoundError, loadModalModule, modalConnection, MODAL_TOKEN_ID_ENV, MODAL_TOKEN_SECRET_ENV, withoutTokens, } from "./sdk.js";
+/** The Modal App every humanish sandbox is created in, inside the connection's environment. */
+const MODAL_APP_NAME = "humanish";
+/** How long a release waits for Modal to report a terminated sandbox finished; about 130 ms seen. */
+const TERMINATE_WAIT_MS = 30_000;
+/** `fn`, with any error it throws stripped of the connection's tokens. */
+function hidingTokens(connection, fn) {
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            throw withoutTokens(error, connection);
+        }
+    };
+}
+/** Modal's own default sandbox lifetime is 5 minutes, as E2B's is. */
+const DEFAULT_SANDBOX_TIMEOUT_MS = 5 * 60_000;
+/** A Modal sandbox was asked for something only an E2B sandbox has. */
+class ModalUnsupportedError extends Error {
+    constructor(what) {
+        super(`${what} is not available on Modal sandboxes in this version of humanish.`);
+        this.name = "ModalUnsupportedError";
+    }
+}
+/**
+ * A sandbox port over one Modal account. `create` maps E2B's create options onto Modal's; `kill`,
+ * `getInfo` and `list` keep the E2B SDK's contracts, which release and reclaim read.
+ */
+export function modalSandboxModule(client, connection, profile) {
+    const humanishApp = appLookup(client, connection, true);
+    // The E2B SDK's second overload names a template first; Modal sandboxes have no templates.
+    async function create(templateOrOptions) {
+        if (typeof templateOrOptions === "string")
+            throw new ModalUnsupportedError("A desktop template");
+        const options = templateOrOptions;
+        const desktop = profile.desktop === true;
+        const env = { ...options.envs, ...(desktop ? { DISPLAY: MODAL_DESKTOP_DISPLAY } : {}) };
+        const params = {
+            cpu: profile.cpu,
+            memoryMiB: profile.memoryMiB,
+            timeoutMs: wholeSeconds(options.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS),
+            runtime: "vm",
+            workdir: MODAL_SANDBOX_USER.home,
+            ...(Object.keys(env).length === 0 ? {} : { env }),
+            ...(options.metadata === undefined ? {} : { tags: { ...options.metadata } }),
+            ...(desktop ? { encryptedPorts: [MODAL_STREAM_PORT] } : {}),
+            ...modalNetwork(options.network),
+        };
+        const sandbox = await client.sandboxes.create(await humanishApp(), profile.image(client), params);
+        if (!desktop)
+            return modalSandboxHandle(sandbox, profile, connection, new Map());
+        // The id reaches the run's journal before the desktop starts, as E2B's create guard reports it.
+        reportDesktopAllocation(options, sandbox.sandboxId);
+        try {
+            const run = (command, runOptions) => runCommand(sandbox, command, runOptions);
+            await startModalDesktop(run, {
+                ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
+                ...(options.dpi === undefined ? {} : { dpi: options.dpi }),
+            });
+            const tunnels = await sandbox.tunnels(30_000);
+            const hosts = new Map(Object.entries(tunnels).map(([port, tunnel]) => [Number(port), new URL(tunnel.url).host]));
+            return modalSandboxHandle(sandbox, profile, connection, hosts);
+        }
+        catch (error) {
+            const gone = await modalSandboxes(client, connection)
+                .kill(sandbox.sandboxId)
+                .then(() => "killed")
+                .catch(() => "unconfirmed");
+            throw new E2BDesktopStartupError(error, gone);
+        }
+    }
+    return {
+        Sandbox: {
+            create: hidingTokens(connection, create),
+            ...modalSandboxes(client, connection),
+        },
+    };
+}
+/** The humanish App in the connection's environment; only a create may make it. */
+function appLookup(client, connection, createIfMissing) {
+    let app;
+    return () => (app ??= client.apps.fromName(MODAL_APP_NAME, {
+        ...(connection.environment === undefined ? {} : { environment: connection.environment }),
+        createIfMissing,
+    }));
+}
+/** A Modal request's default deadline, as E2B's SDK sets its own. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+/** How often a release asks whether a terminated sandbox has finished. */
+const TERMINATE_POLL_MS = 500;
+/**
+ * `request`, or a rejection once `ms` pass. The SDK takes no deadline of its own, so a stalled
+ * RPC would otherwise hold a release or reclaim with no end.
+ */
+async function within(request, ms, what) {
+    let timer;
+    try {
+        return await Promise.race([
+            request,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`Modal did not answer ${what} within ${ms} ms.`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The calls on sandboxes that already exist, with the E2B SDK's contracts: `kill` is true when it
+ * ended a running sandbox and false when the sandbox was gone, `getInfo` throws an error named
+ * SandboxNotFoundError for a gone id, and `list` filters by every given tag. None of them creates
+ * anything, so `reclaim --check` stays read-only.
+ */
+export function modalSandboxes(client, connection) {
+    const existingApp = appLookup(client, connection, false);
+    const deadline = (options) => options?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    /** The sandbox's exit code, null while it runs, or undefined when Modal has no such id. */
+    async function exitOf(sandboxId, ms) {
+        try {
+            const sandbox = await within(client.sandboxes.fromId(sandboxId), ms, "a sandbox lookup");
+            return await within(sandbox.poll(), ms, "a sandbox poll");
+        }
+        catch (error) {
+            if (isModalNotFoundError(error))
+                return undefined;
+            throw error;
+        }
+    }
+    async function kill(sandboxId, options) {
+        const ms = deadline(options);
+        if ((await exitOf(sandboxId, ms)) !== null)
+            return false;
+        const sandbox = await within(client.sandboxes.fromId(sandboxId), ms, "a sandbox lookup");
+        await within(sandbox.terminate(), ms, "a terminate");
+        // terminate returns before the sandbox stops. Polling, unlike the SDK's wait, ends when this
+        // loop does; a sandbox still running at the end leaves the kill unconfirmed.
+        for (const end = Date.now() + TERMINATE_WAIT_MS; Date.now() < end;) {
+            if ((await exitOf(sandboxId, ms)) !== null)
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, TERMINATE_POLL_MS));
+        }
+        throw new Error(`Modal had not reported the sandbox finished ${TERMINATE_WAIT_MS / 1000} s after it was terminated.`);
+    }
+    async function getInfo(sandboxId, options) {
+        if ((await exitOf(sandboxId, deadline(options))) !== null)
+            throw sandboxNotFound(sandboxId);
+        return { sandboxId, state: "running" };
+    }
+    /** One page: Modal filters by tags server-side, and a run tags a few dozen sandboxes at most. */
+    async function listed(tags, ms) {
+        let app;
+        try {
+            app = await within(existingApp(), ms, "an app lookup");
+        }
+        catch (error) {
+            // No humanish App in this environment: no sandbox of any run is there.
+            if (isModalNotFoundError(error))
+                return [];
+            throw error;
+        }
+        const found = [];
+        const search = async () => {
+            for await (const sandbox of client.sandboxes.list({
+                appId: app.appId,
+                ...(tags === undefined ? {} : { tags }),
+                ...(connection.environment === undefined ? {} : { environment: connection.environment }),
+            }))
+                found.push({
+                    sandboxId: sandbox.sandboxId,
+                    metadata: await sandbox.getTags(),
+                    state: "running",
+                });
+        };
+        await within(search(), ms, "a sandbox list");
+        return found;
+    }
+    return {
+        kill: hidingTokens(connection, kill),
+        getInfo: hidingTokens(connection, getInfo),
+        list: (options) => {
+            let read = false;
+            return {
+                get hasNext() {
+                    return !read;
+                },
+                nextItems: hidingTokens(connection, () => {
+                    read = true;
+                    return listed(options?.query?.metadata, deadline(options));
+                }),
+            };
+        },
+    };
+}
+function sandboxNotFound(sandboxId) {
+    const error = new Error(`Modal has no running sandbox ${sandboxId}.`);
+    error.name = "SandboxNotFoundError";
+    return error;
+}
+const CIDR = /^[0-9a-f:.]+\/\d{1,3}$/i;
+/**
+ * E2B's egress shapes that Modal can express: unrestricted, or deny-all with an allowlist of hosts
+ * and CIDRs. Header transforms and other deny lists have no Modal form, so plan validation refuses
+ * them first and this throws if one gets through.
+ */
+function modalNetwork(network) {
+    if (network === undefined)
+        return {};
+    if (network.rules !== undefined && Object.keys(network.rules).length > 0)
+        throw new ModalUnsupportedError("An outbound header transform");
+    const allow = network.allowOut ?? [];
+    const deny = network.denyOut ?? [];
+    if (deny.length === 0 && allow.length === 0)
+        return {};
+    if (deny.length !== 1 || deny[0] !== "0.0.0.0/0")
+        throw new ModalUnsupportedError("An egress deny list other than 0.0.0.0/0");
+    if (allow.length === 0)
+        return { blockNetwork: true };
+    const cidrs = allow.filter((entry) => CIDR.test(entry));
+    const domains = allow.filter((entry) => !CIDR.test(entry));
+    return {
+        ...(cidrs.length === 0 ? {} : { outboundCidrAllowlist: cidrs }),
+        ...(domains.length === 0 ? {} : { outboundDomainAllowlist: domains }),
+    };
+}
+function modalSandboxHandle(sandbox, profile, connection, hosts) {
+    const run = hidingTokens(connection, (command, options) => runCommand(sandbox, command, options));
+    const shell = {
+        sandboxId: sandbox.sandboxId,
+        // Modal reports no allocation for a sandbox; the create's request is what it bills.
+        getInfo: () => Promise.resolve({ cpuCount: profile.cpu * 2, memoryMB: profile.memoryMiB }),
+        commands: { run },
+        files: {
+            write: hidingTokens(connection, (path, data) => writeFile(sandbox, path, data)),
+            read: hidingTokens(connection, (path) => readFile(sandbox, path)),
+            getInfo: hidingTokens(connection, async (path) => {
+                const result = await runCommand(sandbox, `stat -c %s -- '${sandboxPath(path).replaceAll("'", "'\\''")}'`);
+                return { size: Number(result.stdout?.trim()) };
+            }),
+        },
+    };
+    if (profile.desktop === true)
+        return {
+            ...shell,
+            ...modalDesktopSurface(run, hidingTokens(connection, (path) => readBytes(sandbox, path)), hosts),
+        };
+    const desktopOnly = (what) => () => Promise.reject(new ModalUnsupportedError(what));
+    return {
+        ...shell,
+        wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        launch: desktopOnly("A desktop application launch"),
+        screenshot: desktopOnly("A desktop screenshot"),
+        leftClick: desktopOnly("Desktop input"),
+        rightClick: desktopOnly("Desktop input"),
+        middleClick: desktopOnly("Desktop input"),
+        doubleClick: desktopOnly("Desktop input"),
+        moveMouse: desktopOnly("Desktop input"),
+        scroll: desktopOnly("Desktop input"),
+        write: desktopOnly("Desktop input"),
+        press: desktopOnly("Desktop input"),
+        drag: desktopOnly("Desktop input"),
+        stream: {
+            getAuthKey: () => {
+                throw new ModalUnsupportedError("A desktop stream");
+            },
+            getUrl: () => {
+                throw new ModalUnsupportedError("A desktop stream");
+            },
+            start: desktopOnly("A desktop stream"),
+        },
+    };
+}
+/** The Modal account `env` names, for release by id and reclaim. Throws when it names none. */
+export async function modalAccount(env, load = loadModalModule) {
+    const connection = requireModalConnection(env);
+    const { ModalClient: Client } = await load();
+    return modalSandboxes(new Client(connection), connection);
+}
+/** The terminal route's shell: Codex needs little CPU, so it runs smaller than E2B's 8 vCPU desktop. */
+const MODAL_SHELL_PROFILE = {
+    image: modalShellImage,
+    cpu: 2,
+    memoryMiB: 4096,
+};
+/**
+ * The computer-use route's desktop: 4 vCPU and 8 GiB, under E2B's 8 vCPU stock desktop, since a
+ * participant's browser and XFCE use little CPU between actions.
+ */
+const MODAL_DESKTOP_PROFILE = {
+    image: modalDesktopImage,
+    cpu: 2,
+    memoryMiB: 8192,
+    desktop: true,
+};
+/** A sandbox port that creates the computer-use route's desktops on the Modal account `env` names. */
+export async function loadModalDesktopModule(env, load = loadModalModule) {
+    const connection = requireModalConnection(env);
+    const { ModalClient: Client } = await load();
+    return modalSandboxModule(new Client(connection), connection, MODAL_DESKTOP_PROFILE);
+}
+/** A sandbox port that creates the terminal route's shell sandboxes on the Modal account `env` names. */
+export async function loadModalShellModule(env, load = loadModalModule) {
+    const connection = requireModalConnection(env);
+    const { ModalClient: Client } = await load();
+    return modalSandboxModule(new Client(connection), connection, MODAL_SHELL_PROFILE);
+}
+function requireModalConnection(env) {
+    const connection = modalConnection(env);
+    if (connection === undefined)
+        throw new Error(`No Modal credentials: set ${MODAL_TOKEN_ID_ENV} and ${MODAL_TOKEN_SECRET_ENV}, or run \`modal token new\`.`);
+    return connection;
+}