humanish 0.136.1 → 0.138.0

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/dist/verify/network.d.ts

@@ -0,0 +1,10 @@
+import type { RunBundle } from "../run/bundle.js";
+import type { PreparedRunArtifactPaths } from "../run/paths.js";
+/**
+ * One finding per problem with the run's browser network logs: a stream index without the
+ * schema's shape or naming a file other than network/<its participant id>.ndjson, a file that is
+ * missing, unreadable or does not match its index's byte count, sha256 and record count, a record
+ * outside the schema or on an origin its index does not list, and a file under network/ that no
+ * index names. Each finding names the file and the line, never what the line holds.
+ */
+export declare function networkFindings(bundle: RunBundle, runPaths: PreparedRunArtifactPaths): Promise<string[]>;