humanish 0.137.0 → 0.138.0

package/dist/substrates/modal/image.js

@@ -0,0 +1,36 @@
+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",
+];
+/** The terminal route's image: a Debian shell with a passwordless-sudo `user`, as on E2B. */
+export function modalShellImage(client) {
+    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 ${SHELL_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,26 @@
+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;
+}
+/**
+ * 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 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,367 @@
+import { MODAL_SANDBOX_USER, 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) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            throw withoutTokens(error, connection);
+        }
+    };
+}
+/** 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. */
+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 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 } }),
+            ...(options.metadata === undefined ? {} : { tags: { ...options.metadata } }),
+            ...modalNetwork(options.network),
+        };
+        const sandbox = await client.sandboxes.create(await humanishApp(), profile.image(client), params);
+        return modalSandboxHandle(sandbox, profile, connection);
+    }
+    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 }),
+    };
+}
+/** 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 {
+        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)),
+        },
+        files: {
+            write: hidingTokens(connection, (path, data) => writeFile(sandbox, path, data)),
+            getInfo: hidingTokens(connection, async (path) => {
+                const result = await run(sandbox, `stat -c %s -- '${sandboxPath(path).replaceAll("'", "'\\''")}'`);
+                return { size: Number(result.stdout?.trim()) };
+            }),
+        },
+        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,
+};
+/** 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;
+}

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

@@ -0,0 +1,112 @@
+/** Which Modal workspace and environment a call reaches. */
+export interface ModalConnection {
+    tokenId: string;
+    tokenSecret: string;
+    /** Modal's own default environment is used when unset. */
+    environment?: string;
+}
+/** The variables a Modal connection is read from, as Modal's own CLI and SDK name them. */
+export declare const MODAL_TOKEN_ID_ENV = "MODAL_TOKEN_ID";
+export declare const MODAL_TOKEN_SECRET_ENV = "MODAL_TOKEN_SECRET";
+/**
+ * The connection an env names, or undefined when either token is missing. The SDK would otherwise
+ * fall back to process.env and ~/.modal.toml, which a library caller's env may not match, and a
+ * release could then reach another workspace than the create.
+ */
+export declare function modalConnection(env: Readonly<Record<string, string | undefined>>): ModalConnection | undefined;
+export interface ModalReadStream extends AsyncIterable<string | Uint8Array> {
+    readText(): Promise<string>;
+    readBytes(): Promise<Uint8Array>;
+}
+export interface ModalProcess {
+    stdout: ModalReadStream;
+    stderr: ModalReadStream;
+    stdin: {
+        writeText(text: string): Promise<void>;
+        writeBytes(bytes: Uint8Array): Promise<void>;
+        /** End of input after what was written. */
+        close(): Promise<void>;
+    };
+    /** End of input at offset 0: it ends input only before anything was written. */
+    closeStdin(): Promise<void>;
+    wait(): Promise<number>;
+}
+export interface ModalExecParams {
+    mode?: "text" | "binary";
+    stdout?: "pipe" | "ignore";
+    stderr?: "pipe" | "ignore";
+    workdir?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}
+export interface ModalSandbox {
+    readonly sandboxId: string;
+    exec(command: string[], params?: ModalExecParams): Promise<ModalProcess>;
+    terminate(): Promise<void>;
+    /** The exit code once the sandbox has finished, null while it runs. */
+    poll(): Promise<number | null>;
+    /** Resolves with the exit code once the sandbox has finished. */
+    wait(): Promise<number>;
+    getTags(): Promise<Record<string, string>>;
+    tunnels(timeoutMs?: number): Promise<Record<number, {
+        url: string;
+    }>>;
+}
+export interface ModalSandboxCreateParams {
+    cpu?: number;
+    memoryMiB?: number;
+    timeoutMs?: number;
+    workdir?: string;
+    env?: Record<string, string>;
+    encryptedPorts?: number[];
+    blockNetwork?: boolean;
+    outboundCidrAllowlist?: string[];
+    outboundDomainAllowlist?: string[];
+    runtime?: "gvisor" | "vm";
+    tags?: Record<string, string>;
+}
+export interface ModalImage {
+    dockerfileCommands(commands: string[]): ModalImage;
+}
+export interface ModalClient {
+    apps: {
+        fromName(name: string, params?: {
+            environment?: string;
+            createIfMissing?: boolean;
+        }): Promise<{
+            appId: string;
+        }>;
+    };
+    images: {
+        fromRegistry(tag: string): ModalImage;
+    };
+    sandboxes: {
+        create(app: {
+            appId: string;
+        }, image: ModalImage, params?: ModalSandboxCreateParams): Promise<ModalSandbox>;
+        fromId(sandboxId: string): Promise<ModalSandbox>;
+        list(params?: {
+            appId?: string;
+            tags?: Record<string, string>;
+            environment?: string;
+        }): AsyncIterable<ModalSandbox>;
+    };
+    close?(): void;
+}
+export interface ModalModule {
+    ModalClient: new (params: ModalConnection) => ModalClient;
+}
+export declare function loadModalModule(): Promise<ModalModule>;
+/**
+ * `error` with the connection's tokens replaced in its message and stack. The SDK can quote a
+ * token, for instance when gRPC refuses one with a stray zero-width character as metadata, and a
+ * provider error reaches run warnings and reclaim receipts.
+ */
+export declare function withoutTokens(error: unknown, connection: ModalConnection): unknown;
+/**
+ * Whether `error` is Modal's answer that no sandbox has this id: a gRPC NOT_FOUND (code 5), which
+ * the SDK raises from the first call on a handle `fromId` returned for an unknown id.
+ */
+export declare function isModalNotFoundError(error: unknown): boolean;
+/** Modal ends a sandbox after 24 hours on every plan. */
+export declare const MODAL_MAX_SANDBOX_MS: number;

package/dist/substrates/modal/sdk.js

@@ -0,0 +1,61 @@
+// The optional `modal` peer: a lazy loader and the structural subset of its JavaScript SDK that
+// humanish calls. Like @e2b/desktop it stays out of the published tarball, and these interfaces
+// keep its types out of humanish's own declarations.
+import { desktopPeerAdvice, humanishInstall } from "../e2b/peer-install.js";
+/** The variables a Modal connection is read from, as Modal's own CLI and SDK name them. */
+export const MODAL_TOKEN_ID_ENV = "MODAL_TOKEN_ID";
+export const MODAL_TOKEN_SECRET_ENV = "MODAL_TOKEN_SECRET";
+const MODAL_ENVIRONMENT_ENV = "MODAL_ENVIRONMENT";
+/**
+ * The connection an env names, or undefined when either token is missing. The SDK would otherwise
+ * fall back to process.env and ~/.modal.toml, which a library caller's env may not match, and a
+ * release could then reach another workspace than the create.
+ */
+export function modalConnection(env) {
+    const tokenId = env[MODAL_TOKEN_ID_ENV]?.trim();
+    const tokenSecret = env[MODAL_TOKEN_SECRET_ENV]?.trim();
+    if (!tokenId || !tokenSecret)
+        return undefined;
+    const environment = env[MODAL_ENVIRONMENT_ENV]?.trim();
+    return { tokenId, tokenSecret, ...(environment ? { environment } : {}) };
+}
+export async function loadModalModule() {
+    try {
+        return (await import("modal"));
+    }
+    catch (error) {
+        const value = error;
+        if (value.code === "ERR_MODULE_NOT_FOUND" && value.message?.includes("'modal'") === true) {
+            const { where, advice } = desktopPeerAdvice(humanishInstall(), "modal");
+            throw new Error(`Running on Modal requires the optional peer modal${where}. ${advice}`);
+        }
+        throw error;
+    }
+}
+/**
+ * `error` with the connection's tokens replaced in its message and stack. The SDK can quote a
+ * token, for instance when gRPC refuses one with a stray zero-width character as metadata, and a
+ * provider error reaches run warnings and reclaim receipts.
+ */
+export function withoutTokens(error, connection) {
+    if (!(error instanceof Error))
+        return error;
+    const tokens = [connection.tokenId, connection.tokenSecret];
+    const hide = (text) => tokens.reduce((hidden, token) => hidden.replaceAll(token, "[REDACTED_MODAL_TOKEN]"), text);
+    error.message = hide(error.message);
+    if (error.stack !== undefined)
+        error.stack = hide(error.stack);
+    return error;
+}
+/**
+ * Whether `error` is Modal's answer that no sandbox has this id: a gRPC NOT_FOUND (code 5), which
+ * the SDK raises from the first call on a handle `fromId` returned for an unknown id.
+ */
+export function isModalNotFoundError(error) {
+    if (error === null || typeof error !== "object")
+        return false;
+    const value = error;
+    return value.name === "NotFoundError" || value.code === 5;
+}
+/** Modal ends a sandbox after 24 hours on every plan. */
+export const MODAL_MAX_SANDBOX_MS = 24 * 60 * 60_000;

package/docs/architecture/terminal-product-route.md

@@ -28,7 +28,7 @@ fail-closed cross-validation, and forward-declared warnings.
 | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `subject.source`                  | `terminal-product`                                                                                                                                    |
 | `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                              |
-| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                  |
+| `execution.target`                | `e2b-terminal` (or absent → implied), or `modal-terminal` for a Modal sandbox                                                                         |
 | `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                         |
 | `execution.runtimeAuth`           | `openai-egress` (default) or opt-in `openai-env`; names-only durable evidence                                                                         |
 | `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                               |

package/docs/contracts/run-bundle.md

@@ -703,8 +703,10 @@ Dry runs omit `cost`. A live run that spends nothing records an explicit zero: n
 `breakdown` lines, `estimatedTotalUsd: 0`, `ratesAsOf: null` and `fullyEstimated: true`.
 A local scripted run (no model request, no hosted desktop) is such a run; a scripted run on
 a provisioned clone records the clone's desktop as a `laneId: subject` line. A live bundle
-without `cost` has an unmeasured spend. A live terminal run's `cost` prices the E2B terminal
-sandbox as a `desktop-minutes` line from its acquired-to-cleanup span and `e2b.getInfo` size.
+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.
 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,10 +336,10 @@ 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`, or `e2b-terminal`), plus
+- `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
-  scripted-browser actor; terminal-product subjects pair `e2b-terminal` (or absent → implied)
+  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
   computer-use and scripted-browser routes refuse it when a library caller skips
@@ -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`). Do not emit this schema.
+(`execution.target: local | e2b-desktop | e2b-terminal | modal-terminal`). Do not emit this schema.
 
 ## Serve Result And Reserved Control-Plane Namespace
 
@@ -1578,12 +1578,13 @@ Three new `.v1` schema tags ship, all additive and optional so
   lines remain readable.
   A desktop line's optional `desktop` object records `minutes`,
   `durationBasis: host-acquired-to-cleanup`, observed `resources` (`cpuCount`,
-  `memoryMiB`), `resourceSource: e2b.getInfo`, and `usdPerSecond` when priceable.
+  `memoryMiB`), `resourceSource` (`e2b.getInfo`, or `modal.create` for the size humanish asked
+  Modal for), and `usdPerSecond` when priceable.
   Failed metadata reads record `resourceUnavailableReason`; no resource guess is used.
   Resource metadata and missing/unsupported rates produce a null line. A kept or
   unconfirmed allocation adds `desktop_lifetime_incomplete` as a second null line.
   Live terminal-product runs emit the same summary: one `desktop-minutes` line for
-  the E2B shell sandbox (its acquired-to-cleanup span and `e2b.getInfo` size) and
+  the shell sandbox (its acquired-to-cleanup span and its `e2b.getInfo` or `modal.create` size) and
   one `model-tokens` line for the Codex participant, priced from the model the route passed
   to Codex (`gpt-5.6-sol` unless the study declares one) with `basis:
   aggregated_turns_base_rate`, or `null` with `no_token_usage`. Older terminal bundles record