humanish 0.137.0 → 0.139.0

package/dist/run/sandbox-receipts.d.ts

@@ -1,7 +1,9 @@
 import { type PreparedOutputRoot } from "./contained-output.js";
 export declare const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
 /** The providers humanish allocates sandboxes from. Reclaim dispatches on this id. */
-export type SandboxProviderId = "e2b";
+export type SandboxProviderId = "e2b" | "modal";
+/** Whether this humanish can act on sandboxes from `provider`. */
+export declare function isSandboxProviderId(provider: string): provider is SandboxProviderId;
 export interface SandboxReceipt {
     at: string;
     /** The participant or subject label the sandbox belongs to (public-safe token). */
@@ -31,18 +33,24 @@ export declare function appendedSandboxIds(root: PreparedOutputRoot): string[];
  */
 export declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<boolean>;
 /** Append one owner line; false when the write failed, which never fails the create. */
-export declare function appendSandboxOwner(root: PreparedOutputRoot, owner: SandboxOwnerTags): Promise<boolean>;
+export declare function appendSandboxOwner(root: PreparedOutputRoot, owner: SandboxOwnerTags, provider: SandboxProviderId): Promise<boolean>;
 /** The owner tags every sandbox carries; sandboxOwnerTags in src/run/sandbox-creates.ts. */
 export type SandboxOwnerTags = {
     tool: "humanish";
     runId: string;
     runKey: string;
 };
+/** One owner line: the provider searched and the tags searched for. */
+export interface SandboxOwner {
+    provider: SandboxProviderId;
+    tags: SandboxOwnerTags;
+}
 /**
  * The owner tag sets a journal's owner lines record for the run named `runId`. Only a complete
- * tuple counts: provider e2b, `tool: humanish`, this run's id and a well-formed key, and nothing
- * else. A partial or foreign line would widen reclaim's search past this run, so it is skipped.
+ * tuple counts: a provider this version knows, `tool: humanish`, this run's id and a well-formed
+ * key, and nothing else. A partial or foreign line would widen reclaim's search past this run, so
+ * it is skipped.
  */
-export declare function parseSandboxOwners(text: string, runId: string): SandboxOwnerTags[];
+export declare function parseSandboxOwners(text: string, runId: string): SandboxOwner[];
 /** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */
 export declare function parseSandboxReceipts(text: string): ParsedSandboxReceipt[];

package/dist/run/sandbox-receipts.js

@@ -6,6 +6,11 @@
 import { appendFile } from "node:fs/promises";
 import { prepareContainedOutputFile } from "./contained-output.js";
 export const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
+const SANDBOX_PROVIDERS = new Set(["e2b", "modal"]);
+/** Whether this humanish can act on sandboxes from `provider`. */
+export function isSandboxProviderId(provider) {
+    return SANDBOX_PROVIDERS.has(provider);
+}
 /**
  * The ids this process has receipted for each run directory, kept even when the append fails, so
  * the run's other records can still be scrubbed of them. Keyed by the directory's identity, so a
@@ -51,9 +56,9 @@ export async function appendSandboxReceipt(root, receipt) {
     }
 }
 /** Append one owner line; false when the write failed, which never fails the create. */
-export async function appendSandboxOwner(root, owner) {
+export async function appendSandboxOwner(root, owner, provider) {
     try {
-        const line = { at: new Date().toISOString(), provider: "e2b", owner };
+        const line = { at: new Date().toISOString(), provider, owner };
         const filePath = await prepareContainedOutputFile(root, SANDBOX_RECEIPTS_ARTIFACT);
         // The leading newline ends a line an earlier append left torn, so this record parses.
         await appendFile(filePath, `\n${JSON.stringify(line)}\n`, "utf8");
@@ -68,8 +73,9 @@ export async function appendSandboxOwner(root, owner) {
 const RUN_KEY = /^[0-9a-f]{16}$/;
 /**
  * The owner tag sets a journal's owner lines record for the run named `runId`. Only a complete
- * tuple counts: provider e2b, `tool: humanish`, this run's id and a well-formed key, and nothing
- * else. A partial or foreign line would widen reclaim's search past this run, so it is skipped.
+ * tuple counts: a provider this version knows, `tool: humanish`, this run's id and a well-formed
+ * key, and nothing else. A partial or foreign line would widen reclaim's search past this run, so
+ * it is skipped.
  */
 export function parseSandboxOwners(text, runId) {
     const owners = new Map();
@@ -80,13 +86,19 @@ export function parseSandboxOwners(text, runId) {
         try {
             const parsed = JSON.parse(trimmed);
             const owner = parsed.owner;
-            if (parsed.provider !== "e2b" || owner === null || typeof owner !== "object")
+            const provider = parsed.provider;
+            if (typeof provider !== "string" || !isSandboxProviderId(provider))
+                continue;
+            if (owner === null || typeof owner !== "object")
                 continue;
             if (Object.keys(owner).length !== 3 || owner.tool !== "humanish" || owner.runId !== runId)
                 continue;
             if (typeof owner.runKey !== "string" || !RUN_KEY.test(owner.runKey))
                 continue;
-            owners.set(owner.runKey, { tool: "humanish", runId, runKey: owner.runKey });
+            owners.set(JSON.stringify([provider, owner.runKey]), {
+                provider,
+                tags: { tool: "humanish", runId, runKey: owner.runKey },
+            });
         }
         catch {
             // A torn line: skip it.

package/dist/study/composition-rules.js

@@ -111,8 +111,9 @@ function appUrlValidationReason(config) {
             }
         }
         else {
-            if (config.execution?.target !== "e2b-desktop" && config.execution?.target !== "local") {
-                return "app-url computer-use subjects require `execution.target: local` or `e2b-desktop`.";
+            const target = config.execution?.target;
+            if (target !== "e2b-desktop" && target !== "modal-desktop" && target !== "local") {
+                return "app-url computer-use subjects require `execution.target: local`, `e2b-desktop` or `modal-desktop`.";
             }
             if (!actorResolvesToComputerUse(type)) {
                 return `actor.type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
@@ -258,15 +259,15 @@ function desktopCliValidationReason(config) {
     return null;
 }
 // terminal-product route: a real autonomous agent studies a CLI/product from public surfaces inside
-// an E2B shell. Fail-closed (claims match mechanism: a field that cannot act on this route is a
-// parse error): a registered terminal actor only, execution.target e2b-terminal or absent (absent
-// defaults to e2b-terminal, the only target where an in-sandbox agent runs), one participant until
-// fan-out lands.
+// a hosted shell. Fail-closed (claims match mechanism: a field that cannot act on this route is a
+// parse error): a registered terminal actor only, execution.target e2b-terminal, modal-terminal or
+// absent (absent defaults to e2b-terminal), one participant until fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
         const type = config.actor?.type ?? "";
-        if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
-            return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
+        const target = config.execution?.target;
+        if (target !== undefined && target !== "e2b-terminal" && target !== "modal-terminal") {
+            return "A terminal-product subject runs its agent in a hosted shell. Set `execution.target` to e2b-terminal or modal-terminal, or omit it for e2b-terminal; `local` and `e2b-desktop` are not supported.";
         }
         if (!actorResolvesToTerminal(type)) {
             return `actor.type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
@@ -275,10 +276,11 @@ function terminalValidationReason(config) {
             return "Terminal fan-out to more than one participant is not supported yet; set participants to 1.";
         }
     }
-    else if (config.execution?.target === "e2b-terminal") {
-        // e2b-terminal is the terminal-product substrate only. Any other source declaring it is a
-        // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
-        return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
+    else if (config.execution?.target === "e2b-terminal" ||
+        config.execution?.target === "modal-terminal") {
+        // The terminal targets are the terminal-product substrates only. Any other source declaring one
+        // is a mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
+        return `\`execution.target: ${config.execution.target}\` requires \`subject.source: terminal-product\` with a registered terminal actor.`;
     }
     else if (actorResolvesToTerminal(config.actor?.type)) {
         // A registered terminal actor on a non-terminal-product subject: rejected, never ignored (the

package/dist/study/doctor.js

@@ -279,7 +279,7 @@ async function realEmailCheck(connection, keys, args) {
 /** How the participant authenticates: the terminal model key, or a local agent's login. */
 async function participantChecks(config, route, keys, local, args, checkAccount) {
     if (route === "terminal") {
-        const key = keys.find((name) => name !== "E2B_API_KEY");
+        const key = keys.find((name) => name === "CODEX_API_KEY" || name === "OPENAI_API_KEY");
         return [
             {
                 name: "terminal model authentication",

package/dist/study/parse/execution.js

@@ -14,8 +14,12 @@ export function parseExecution(raw) {
     const execution = {};
     if (raw.target !== undefined) {
         const target = str(raw.target);
-        if (target !== "local" && target !== "e2b-desktop" && target !== "e2b-terminal") {
-            return invalid("`execution.target` must be local, e2b-desktop, or e2b-terminal.");
+        if (target !== "local" &&
+            target !== "e2b-desktop" &&
+            target !== "e2b-terminal" &&
+            target !== "modal-desktop" &&
+            target !== "modal-terminal") {
+            return invalid("`execution.target` must be local, e2b-desktop, e2b-terminal, modal-desktop, or modal-terminal.");
         }
         execution.target = target;
     }

package/dist/study/plan-base.d.ts

@@ -7,6 +7,7 @@ export declare function provisionedSubject(config: StudyConfig): ProvisionedSubj
 /** Keys, env and local tools a live run checks right before it acquires anything. */
 export declare function desktopRequirements(config: StudyConfig, args: {
     e2b: boolean;
+    modal?: boolean;
     brain: Brain;
     localVm: boolean;
     externalCatch: boolean;

package/dist/study/plan-base.js

@@ -73,6 +73,8 @@ export function desktopRequirements(config, args) {
     const requirements = [];
     if (args.e2b)
         requirements.push({ kind: "key", name: "E2B_API_KEY" });
+    if (args.modal === true)
+        requirements.push({ kind: "key", name: "MODAL_TOKEN_ID" }, { kind: "key", name: "MODAL_TOKEN_SECRET" });
     if (args.localVm)
         requirements.push({ kind: "local-vm" });
     if (args.brain.kind === "openai")

package/dist/study/plan-types.d.ts

@@ -4,6 +4,7 @@ import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { BrowserSurface } from "../actors/scripted-browser/types.js";
 import type { ScriptedRefusal } from "../routes/scripted/plan.js";
 import type { TerminalRefusal } from "../routes/terminal/plan.js";
+import type { SandboxProviderId } from "../run/sandbox-receipts.js";
 import type { RunStudyProvenance } from "../run/study-provenance.js";
 import type { ArrivalPlan } from "./arrivals.js";
 import type { BundleEstimate } from "./bundle-estimate.js";
@@ -19,7 +20,7 @@ type AtLeastTwo<T> = readonly [T, T, ...T[]];
  */
 export type Requirement = {
     readonly kind: "key";
-    readonly name: "OPENAI_API_KEY" | "E2B_API_KEY";
+    readonly name: "OPENAI_API_KEY" | "E2B_API_KEY" | "MODAL_TOKEN_ID" | "MODAL_TOKEN_SECRET";
 }
 /** The terminal runtime key: CODEX_API_KEY, else OPENAI_API_KEY. */
  | {
@@ -132,6 +133,8 @@ export interface AppUrlSubject {
  */
 export type ComputerUseRunner = {
     readonly desktop: "e2b-desktop";
+    /** Who hosts the desktop: E2B, or Modal for `execution.target: modal-desktop`. */
+    readonly provider: SandboxProviderId;
     readonly brain: Brain;
     readonly participants: NonEmpty<ComputerUseParticipant>;
     readonly subject: AppUrlSubject | ProvisionedSubject | {
@@ -223,6 +226,8 @@ export interface SharedWorldPlan extends PlanBase {
 }
 export type TerminalPlan = PlanBase & {
     readonly route: "terminal";
+    /** Where the shell sandbox runs: `execution.target` modal-terminal, else E2B. */
+    readonly sandboxProvider: SandboxProviderId;
     /** The registered terminal actor that runs. */
     readonly actor: string;
     readonly product: StudySubjectProduct & {

package/dist/study/requirements.js

@@ -9,9 +9,14 @@ import { localAgentRefusal } from "../actors/local-agent/readiness.js";
 import { describeMissingKeys } from "../keys/key-resolution.js";
 import { MODEL_RATES, unpricedCapMessage } from "../run/pricing.js";
 /** Provider keys in the order the routes name them in a refusal. */
-const KEY_ORDER = ["OPENAI_API_KEY", "E2B_API_KEY"];
+const KEY_ORDER = [
+    "OPENAI_API_KEY",
+    "E2B_API_KEY",
+    "MODAL_TOKEN_ID",
+    "MODAL_TOKEN_SECRET",
+];
 const present = (env, name) => (env[name]?.trim() ?? "") !== "";
-/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
+/** The `key` requirements whose value `env` lacks, in KEY_ORDER. */
 function missingKeys(requirements, env) {
     const required = new Set(requirements.flatMap((requirement) => (requirement.kind === "key" ? [requirement.name] : [])));
     return KEY_ORDER.filter((name) => required.has(name) && !present(env, name));

package/dist/study/routing.d.ts

@@ -69,7 +69,7 @@ export declare function isScriptedBrowserComposition(config: StudyConfig): boole
 export declare function isProvisionedScriptedBrowserComposition(config: StudyConfig): boolean;
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal, modal-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */

package/dist/study/routing.js

@@ -177,7 +177,7 @@ export function isProvisionedScriptedBrowserComposition(config) {
 }
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal, modal-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */

package/dist/study/types.d.ts

@@ -467,7 +467,7 @@ export interface StudyActor {
      */
     dwell?: DwellWindow;
 }
-type StudyExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal";
+type StudyExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal" | "modal-desktop" | "modal-terminal";
 /** Terminal transport: the captured non-interactive exec stream (stdin disabled). It is not an
  *  interactive duplex PTY; labeling captured exec output "pty" would be a claim/mechanism
  *  mismatch, so this route uses "exec-stream". */

package/dist/study/warnings.js

@@ -262,7 +262,9 @@ function routesOf(config) {
         terminal: isTerminalProductComposition(config),
         shared,
         externalPublic: shared && config.subject.source === "app-url",
-        hostedCuaBrowser: config.execution?.target === "e2b-desktop" && cua,
+        hostedCuaBrowser: (config.execution?.target === "e2b-desktop" ||
+            config.execution?.target === "modal-desktop") &&
+            cua,
         createsE2BDesktop: (cua || (scripted && config.subject.source === "clone")) &&
             config.execution?.target === "e2b-desktop",
     };

package/dist/substrates/e2b/desktop-resources.d.ts

@@ -1,11 +1,13 @@
 import type { E2BDesktopSandbox } from "./sdk.js";
 import { type DesktopResources } from "../../run/pricing.js";
+/** Where an allocation's size came from: E2B's report, or the size humanish asked Modal for. */
+export type DesktopResourceSource = "e2b.getInfo" | "modal.create";
 export type DesktopResourceObservation = {
     resources: DesktopResources;
-    source: "e2b.getInfo";
+    source: DesktopResourceSource;
 } | {
     reason: "metadata_unavailable" | "metadata_invalid" | "metadata_timeout";
 };
 /** Called once after the caller owns and journals the handle. Never throws or delays cleanup
  * beyond the bounded wait. Persist only resource quantities, never the raw info/connection. */
-export declare function observeDesktopResources(desktop: Pick<E2BDesktopSandbox, "getInfo">, timeoutMs?: number): Promise<DesktopResourceObservation>;
+export declare function observeDesktopResources(desktop: Pick<E2BDesktopSandbox, "getInfo">, timeoutMs?: number, source?: DesktopResourceSource): Promise<DesktopResourceObservation>;

package/dist/substrates/e2b/desktop-resources.js

@@ -1,7 +1,7 @@
 import { isDesktopResources } from "../../run/pricing.js";
 /** Called once after the caller owns and journals the handle. Never throws or delays cleanup
  * beyond the bounded wait. Persist only resource quantities, never the raw info/connection. */
-export async function observeDesktopResources(desktop, timeoutMs = 1_000) {
+export async function observeDesktopResources(desktop, timeoutMs = 1_000, source = "e2b.getInfo") {
     const controller = new AbortController();
     let timer;
     try {
@@ -16,7 +16,7 @@ export async function observeDesktopResources(desktop, timeoutMs = 1_000) {
                 });
                 const resources = { cpuCount: info?.cpuCount, memoryMiB: info?.memoryMB };
                 return isDesktopResources(resources)
-                    ? { resources, source: "e2b.getInfo" }
+                    ? { resources, source }
                     : { reason: "metadata_invalid" };
             }),
             new Promise((resolve) => {

package/dist/substrates/e2b/peer-install.js

@@ -139,7 +139,7 @@ export function desktopPeerAdvice(install, spec = "@e2b/desktop") {
             return {
                 where: ", and humanish is running from a source checkout",
                 command: "pnpm install",
-                advice: spec === "@e2b/desktop"
+                advice: spec === "@e2b/desktop" || spec === "modal"
                     ? "Run `pnpm install` in the humanish checkout, which installs it as a dev dependency."
                     : `Set ${spec} in the humanish checkout's package.json, then run \`pnpm install\` there.`,
             };

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

@@ -1,3 +1,4 @@
+import { type SandboxProviderId } from "../../run/sandbox-receipts.js";
 import type { PreparedOutputRoot } from "../../run/contained-output.js";
 import { type DesktopReleaseResult, type OwnedDesktopAllocation } from "../desktop-session.js";
 import type { StudyConfig } from "../../study/types.js";
@@ -13,6 +14,8 @@ interface E2BSandboxReceiptTarget {
 }
 export interface E2BSandboxRequest {
     module: E2BDesktopModule;
+    /** Who `module` creates sandboxes on; receipts and owner lines name it. Defaults to e2b. */
+    provider?: SandboxProviderId;
     options: E2BDesktopCreateOptions;
     retry?: TransientRetryHooks;
     /**

package/dist/substrates/e2b/sandbox.js

@@ -9,7 +9,7 @@
 // journal at that point, so a startup error that quotes it is scrubbed from every run file.
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { beginSandboxCreate, recordSandboxOwnerOnce, SandboxCreateRefusedError, sandboxOwnerTags, } from "../../run/sandbox-creates.js";
-import { appendSandboxOwner, appendSandboxReceipt } from "../../run/sandbox-receipts.js";
+import { appendSandboxOwner, appendSandboxReceipt, } from "../../run/sandbox-receipts.js";
 import { ownDesktopAllocation, } from "../desktop-session.js";
 import { e2bAccount } from "./connection.js";
 import { E2B_DEBUG_KILL_DETAIL, E2BDesktopStartupError, e2bDebugMode, isSandboxNotFoundError, observeDesktopAllocation, } from "./sdk.js";
@@ -23,9 +23,10 @@ export function acquireE2BShellSandbox(request) {
 }
 async function acquire(request, template) {
     const { module } = request;
+    const provider = request.provider ?? "e2b";
     const target = request.receipt;
     // Refused before any provider call once the run is stopping.
-    const ticket = target === null ? undefined : beginSandboxCreate(target.root, target.participantId);
+    const ticket = target === null ? undefined : beginSandboxCreate(target.root, target.participantId, provider);
     // The receipts written when the guard reported an id, before desktop startup. A startup error
     // can quote the id and the create may never return, so the journal holds it first.
     const reported = new Map();
@@ -35,7 +36,7 @@ async function acquire(request, template) {
         // journal records them first, so reclaim knows which tags to search for.
         const owner = target === null ? undefined : sandboxOwnerTags(target.root);
         if (target !== null && owner !== undefined)
-            await recordSandboxOwnerOnce(target.root, () => appendSandboxOwner(target.root, owner));
+            await recordSandboxOwnerOnce(target.root, provider, () => appendSandboxOwner(target.root, owner, provider));
         const options = owner === undefined
             ? request.options
             : { ...request.options, metadata: { ...request.options.metadata, ...owner } };
@@ -46,7 +47,7 @@ async function acquire(request, template) {
             return appendSandboxReceipt(root, {
                 at: new Date(now()).toISOString(),
                 laneId: participantId,
-                provider: "e2b",
+                provider,
                 sandboxId,
                 ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
             });

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

@@ -211,6 +211,11 @@ export declare const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10000;
  * the id.
  */
 export declare function observeDesktopAllocation(options: E2BDesktopCreateOptions, observer: (sandboxId: string) => void): void;
+/**
+ * Tell the observer registered for `options` that its sandbox exists, for a module that starts its
+ * own desktop after create, as the Modal one does. An observer that throws does not fail the create.
+ */
+export declare function reportDesktopAllocation(options: E2BDesktopCreateOptions, sandboxId: string): void;
 type DesktopCreateCleanup = "killed" | "already_gone" | "unconfirmed";
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export declare class E2BDesktopStartupError extends Error {

package/dist/substrates/e2b/sdk.js

@@ -31,6 +31,18 @@ const allocationObservers = new WeakMap();
 export function observeDesktopAllocation(options, observer) {
     allocationObservers.set(options, observer);
 }
+/**
+ * Tell the observer registered for `options` that its sandbox exists, for a module that starts its
+ * own desktop after create, as the Modal one does. An observer that throws does not fail the create.
+ */
+export function reportDesktopAllocation(options, sandboxId) {
+    try {
+        allocationObservers.get(options)?.(sandboxId);
+    }
+    catch {
+        // The resolved handle reports the id as well.
+    }
+}
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export class E2BDesktopStartupError extends Error {
     cleanup;

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

@@ -0,0 +1,16 @@
+import { ReadableStream } from "node:stream/web";
+import type { E2BCommandResult, E2BCommandRunOptions } from "../e2b/sdk.js";
+import type { ModalSandbox } from "./sdk.js";
+/** Modal takes sandbox and command timeouts in whole seconds; a shorter one is rounded up. */
+export declare const wholeSeconds: (ms: number) => number;
+/** Run `command` as the sandbox user, to completion or, with `background`, returning a handle. */
+export declare function runCommand(sandbox: ModalSandbox, command: string, options?: E2BCommandRunOptions): Promise<E2BCommandResult>;
+/** Relative paths are under the sandbox user's home, as on E2B. */
+export declare function sandboxPath(path: string): string;
+export declare function writeFile(sandbox: ModalSandbox, path: string, data: string | ArrayBuffer): Promise<{
+    path: string;
+}>;
+/** A file's bytes as a stream, read as the sandbox user. */
+export declare function readFile(sandbox: ModalSandbox, path: string): Promise<ReadableStream<Uint8Array>>;
+/** A file's bytes, whole. */
+export declare function readBytes(sandbox: ModalSandbox, path: string): Promise<Uint8Array>;

package/dist/substrates/modal/commands.js

@@ -0,0 +1,174 @@
+// Commands and files in a Modal sandbox, with the E2B SDK's contracts, which the routes were written
+// against: a non-zero exit throws CommandExitError, a timeout throws TimeoutError, relative paths
+// are under the user's home, and a background command returns a handle to wait on, kill or feed.
+//
+// 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. Modal has no way to signal one exec, so a
+// background command records its pid in a file and is killed by that pid.
+import { randomUUID } from "node:crypto";
+import { ReadableStream } from "node:stream/web";
+import { shellQuote } from "../shell.js";
+import { MODAL_SANDBOX_USER } from "./image.js";
+/** 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 takes sandbox and command timeouts in whole seconds; a shorter one is rounded up. */
+export const wholeSeconds = (ms) => Math.ceil(ms / 1000) * 1000;
+/** 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;
+}
+/** Modal ends a command at its timeout and reports it as a deadline; E2B names it TimeoutError. */
+function named(error, timeoutMs) {
+    if (!(error instanceof Error) || !/deadline exceeded/i.test(error.message))
+        return error;
+    const timeout = new Error(`Command did not finish within ${timeoutMs} ms.`, { cause: error });
+    timeout.name = "TimeoutError";
+    return timeout;
+}
+/** Run `command` as the sandbox user, to completion or, with `background`, returning a handle. */
+export async function runCommand(sandbox, command, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+    const pidFile = options.background === true ? `/tmp/humanish-exec-${randomUUID()}.pid` : "";
+    const line = options.background === true
+        ? `printf '%s\\n' "$$" > ${pidFile}; exec bash -c ${shellQuote(command)}`
+        : command;
+    let finished;
+    let child;
+    try {
+        child = await sandbox.exec(asSandboxUser(line), {
+            env: { ...USER_ENV, ...options.envs },
+            ...(options.cwd === undefined ? {} : { workdir: options.cwd }),
+            ...(timeoutMs > 0 ? { timeoutMs: wholeSeconds(timeoutMs) } : {}),
+        });
+        // E2B starts a command with no stdin unless asked; a Modal exec keeps the pipe open, and a
+        // reader such as codex exec would wait on it until its timeout.
+        if (options.stdin !== true)
+            await child.closeStdin();
+        const running = child;
+        finished = Promise.all([
+            collect(running.stdout, options.onStdout),
+            collect(running.stderr, options.onStderr),
+            running.wait(),
+        ]).then(([stdout, stderr, exitCode]) => {
+            if (exitCode !== 0)
+                throw new ModalCommandExitError(exitCode, stdout, stderr);
+            return { exitCode, stdout, stderr };
+        });
+    }
+    catch (error) {
+        throw named(error, timeoutMs);
+    }
+    if (options.background !== true)
+        return finished.catch((error) => {
+            throw named(error, timeoutMs);
+        });
+    // The caller decides when to wait; an exit nobody waits for is not an unhandled rejection.
+    finished.catch(() => { });
+    const running = child;
+    // E2B's handle carries the process's pid, which owners such as the recorder check.
+    const pid = await backgroundPid(sandbox, pidFile);
+    return {
+        ...(pid === undefined ? {} : { pid }),
+        wait: () => finished,
+        kill: async () => {
+            const killed = await runCommand(sandbox, `kill -KILL "$(cat ${pidFile})" 2>/dev/null && echo killed || true`, { timeoutMs: 10_000 });
+            return killed.stdout?.trim() === "killed";
+        },
+        sendStdin: (data) => typeof data === "string" ? running.stdin.writeText(data) : running.stdin.writeBytes(data),
+        closeStdin: () => running.stdin.close(),
+    };
+}
+/** How long a background command has to record its pid before its handle reports none. */
+const PID_WAIT_MS = 5_000;
+/** The pid a background command wrote to `pidFile`, or undefined if none arrived in time. */
+async function backgroundPid(sandbox, pidFile) {
+    for (const end = Date.now() + PID_WAIT_MS; Date.now() < end;) {
+        const read = await runCommand(sandbox, `cat ${pidFile} 2>/dev/null || true`, {
+            timeoutMs: 10_000,
+        });
+        const pid = Number(read.stdout?.trim());
+        if (Number.isSafeInteger(pid) && pid > 0)
+            return pid;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return undefined;
+}
+/** Relative paths are under the sandbox user's home, as on E2B. */
+export function sandboxPath(path) {
+    return path.startsWith("/") ? path : `${MODAL_SANDBOX_USER.home}/${path}`;
+}
+export 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));
+    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 };
+}
+/** A file's bytes as a stream, read as the sandbox user. */
+export async function readFile(sandbox, path) {
+    const child = await sandbox.exec(asSandboxUser('cat -- "$0"').concat(sandboxPath(path)), {
+        mode: "binary",
+        env: USER_ENV,
+    });
+    await child.closeStdin();
+    const bytes = async function* () {
+        for await (const chunk of child.stdout)
+            yield typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+        const exitCode = await child.wait();
+        if (exitCode !== 0)
+            throw new ModalCommandExitError(exitCode, "", await child.stderr.readText());
+    };
+    return ReadableStream.from(bytes());
+}
+/** A file's bytes, whole. */
+export async function readBytes(sandbox, path) {
+    const parts = [];
+    for await (const chunk of await readFile(sandbox, path))
+        parts.push(chunk);
+    return Buffer.concat(parts);
+}

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

@@ -0,0 +1,16 @@
+import type { E2BCommandResult, E2BCommandRunOptions, E2BDesktopSandbox } from "../e2b/sdk.js";
+type Run = (command: string, options?: E2BCommandRunOptions) => Promise<E2BCommandResult>;
+/** The X display and the ports the desktop's stream uses, as @e2b/desktop sets them. */
+export declare const MODAL_DESKTOP_DISPLAY = ":0";
+export declare const MODAL_STREAM_PORT = 6080;
+/** Start Xvfb at the requested size, then an XFCE session, as @e2b/desktop's create does. */
+export declare function startModalDesktop(run: Run, options: {
+    resolution?: [number, number];
+    dpi?: number;
+}): Promise<void>;
+/**
+ * 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 declare function modalDesktopSurface(run: Run, readBytes: (path: string) => Promise<Uint8Array>, hosts: ReadonlyMap<number, string>): Omit<E2BDesktopSandbox, "sandboxId" | "getInfo" | "commands" | "files">;
+export {};