humanish 0.138.0 → 0.139.0

package/dist/substrates/modal/sandbox.js

@@ -1,11 +1,20 @@
-import { MODAL_SANDBOX_USER, modalShellImage } from "./image.js";
+// 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;
-/** Modal takes sandbox and command timeouts in whole seconds; a shorter one is rounded up. */
-const wholeSeconds = (ms) => Math.ceil(ms / 1000) * 1000;
 /** `fn`, with any error it throws stripped of the connection's tokens. */
 function hidingTokens(connection, fn) {
     return async (...args) => {
@@ -17,8 +26,6 @@ function hidingTokens(connection, fn) {
         }
     };
 }
-/** E2B's commands.run default, kept so a caller that sets no timeout gets the same bound. */
-const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
 /** 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. */
@@ -39,18 +46,41 @@ export function modalSandboxModule(client, connection, profile) {
         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,
-            ...(options.envs === undefined ? {} : { env: { ...options.envs } }),
+            ...(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);
-        return modalSandboxHandle(sandbox, profile, connection);
+        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: {
@@ -206,118 +236,30 @@ function modalNetwork(network) {
         ...(domains.length === 0 ? {} : { outboundDomainAllowlist: domains }),
     };
 }
-/** The argv that runs `command` in a login shell as the sandbox user, in their home. */
-function asSandboxUser(command) {
-    const { uid } = MODAL_SANDBOX_USER;
-    return [
-        "setpriv",
-        `--reuid=${uid}`,
-        `--regid=${uid}`,
-        "--init-groups",
-        "--",
-        "bash",
-        "-lc",
-        command,
-    ];
-}
-const USER_ENV = {
-    HOME: MODAL_SANDBOX_USER.home,
-    USER: MODAL_SANDBOX_USER.name,
-    LOGNAME: MODAL_SANDBOX_USER.name,
-};
-/** The E2B SDK throws this shape on a non-zero exit; src/substrates/command-failure.ts reads it. */
-class ModalCommandExitError extends Error {
-    exitCode;
-    stdout;
-    stderr;
-    constructor(exitCode, stdout, stderr) {
-        super(`Command exited with code ${exitCode}${stderr ? ` and error:\n${stderr}` : ""}`);
-        this.exitCode = exitCode;
-        this.stdout = stdout;
-        this.stderr = stderr;
-        this.name = "CommandExitError";
-    }
-    get error() {
-        return this.stderr;
-    }
-}
-async function collect(stream, onData) {
-    const decoder = new TextDecoder();
-    let text = "";
-    for await (const chunk of stream) {
-        const data = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
-        text += data;
-        if (onData !== undefined && data !== "")
-            await onData(data);
-    }
-    return text;
-}
-async function run(sandbox, command, options = {}) {
-    if (options.background === true || options.stdin === true)
-        throw new ModalUnsupportedError("A background command");
-    const timeoutMs = options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
-    let stdout;
-    let stderr;
-    let exitCode;
-    try {
-        const child = await sandbox.exec(asSandboxUser(command), {
-            env: { ...USER_ENV, ...options.envs },
-            ...(options.cwd === undefined ? {} : { workdir: options.cwd }),
-            ...(timeoutMs > 0 ? { timeoutMs: wholeSeconds(timeoutMs) } : {}),
-        });
-        // E2B starts a command with no stdin; a Modal exec keeps the pipe open, and a reader such as
-        // codex exec would wait on it until its timeout.
-        await child.closeStdin();
-        [stdout, stderr, exitCode] = await Promise.all([
-            collect(child.stdout, options.onStdout),
-            collect(child.stderr, options.onStderr),
-            child.wait(),
-        ]);
-    }
-    catch (error) {
-        // Modal ends a command at its timeout and reports it as a deadline; E2B names it TimeoutError.
-        if (error instanceof Error && /deadline exceeded/i.test(error.message)) {
-            const timeout = new Error(`Command did not finish within ${timeoutMs} ms.`, { cause: error });
-            timeout.name = "TimeoutError";
-            throw timeout;
-        }
-        throw error;
-    }
-    if (exitCode !== 0)
-        throw new ModalCommandExitError(exitCode, stdout, stderr);
-    return { exitCode, stdout, stderr };
-}
-/** Relative paths are under the sandbox user's home, as on E2B. */
-function sandboxPath(path) {
-    return path.startsWith("/") ? path : `${MODAL_SANDBOX_USER.home}/${path}`;
-}
-async function writeFile(sandbox, path, data) {
-    const target = sandboxPath(path);
-    const child = await sandbox.exec(asSandboxUser('mkdir -p -- "$(dirname -- "$0")" && cat > "$0"').concat(target), { mode: "binary", env: USER_ENV });
-    await child.stdin.writeBytes(typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data));
-    // closeStdin ends input at offset 0, which Modal ignores once bytes were written.
-    await child.stdin.close();
-    const [stderr, exitCode] = await Promise.all([child.stderr.readBytes(), child.wait()]);
-    if (exitCode !== 0)
-        throw new ModalCommandExitError(exitCode, "", new TextDecoder().decode(stderr));
-    return { path: target };
-}
-function modalSandboxHandle(sandbox, profile, connection) {
-    const desktopOnly = (what) => () => Promise.reject(new ModalUnsupportedError(what));
-    return {
+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: hidingTokens(connection, (command, options) => run(sandbox, command, options)),
-        },
+        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 run(sandbox, `stat -c %s -- '${sandboxPath(path).replaceAll("'", "'\\''")}'`);
+                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"),
@@ -353,6 +295,22 @@ const MODAL_SHELL_PROFILE = {
     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);

package/docs/contracts/run-bundle.md

@@ -706,7 +706,8 @@ a provisioned clone records the clone's desktop as a `laneId: subject` line. A l
 without `cost` has an unmeasured spend. A live terminal run's `cost` prices its shell sandbox
 as a `desktop-minutes` line from its acquired-to-cleanup span and size: E2B's report
 (`resourceSource: e2b.getInfo`), or the size humanish asked Modal for (`modal.create`), priced at
-Modal's sandbox rate.
+Modal's sandbox rate. A computer-use run on `execution.target: modal-desktop` records each
+desktop's `providerResources[].provider` as `modal-desktop` and prices it the same way.
 Its Codex `model-tokens` line prices the agent's tokens from the model passed as `--model`
 (`actor.model`, else `gpt-5.6-sol`). Codex reports usage per turn, summed over the turn's
 requests, so the line prices every token at the base tier and carries

package/docs/contracts/schemas.md

@@ -336,9 +336,9 @@ The rest of this section names keys by their v3 spelling:
 - `subject.appUrl`: a loopback http(s) URL a computer-use actor drives, or (on the
   external-public shared-world route) the non-loopback public deployment used as the
   shared plane (with `publicTarget` + `allowPublicTargets`);
-- `execution`: where it runs (`local`, `e2b-desktop`, `e2b-terminal` or `modal-terminal`), plus
-  desktop device/resolution and timeouts. app-url subjects pair `e2b-desktop`
-  or `local` with a computer-use actor, or `local` (or absent) with a
+- `execution`: where it runs (`local`, `e2b-desktop`, `e2b-terminal`, `modal-desktop` or
+  `modal-terminal`), plus desktop device/resolution and timeouts. app-url subjects pair
+  `e2b-desktop`, `modal-desktop` or `local` with a computer-use actor, or `local` (or absent) with a
   scripted-browser actor; terminal-product subjects pair `e2b-terminal` or `modal-terminal` (or absent → `e2b-terminal`)
   with a registered terminal actor. clone and local-tree subjects require an
   explicit `e2b-desktop`: any other target, or none, fails to parse, and the
@@ -1297,7 +1297,7 @@ items: []
 Reserved: `humanish.substrate.v1` is named here for layering intent but has
 never shipped; no code emits or validates it. Substrate truth today lives
 inside run bundles (per-stream transport and status) and study execution config
-(`execution.target: local | e2b-desktop | e2b-terminal | modal-terminal`). Do not emit this schema.
+(`execution.target: local | e2b-desktop | e2b-terminal | modal-desktop | modal-terminal`). Do not emit this schema.
 
 ## Serve Result And Reserved Control-Plane Namespace
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.138.0",
+  "version": "0.139.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",