humanish 0.138.0 → 0.139.1

package/dist/routes/computer-use/participant-deps.d.ts

@@ -36,7 +36,7 @@ interface DesktopRunFacts {
 }
 /** The fields one desktop route sets and the other does not. Undefined leaves a field out. */
 type DesktopRouteOverrides = {
-    [K in "createDesktop" | "createProvider" | "inProcessExecutor" | "localTreeArchiveBuffer" | "desktopFiles" | "externalComms" | "receiving" | "screenMismatchPolicy"]?: CuaParticipantDeps[K] | undefined;
+    [K in "createDesktop" | "createProvider" | "inProcessExecutor" | "localTreeArchiveBuffer" | "desktopFiles" | "externalComms" | "receiving" | "screenMismatchPolicy" | "sandboxProvider"]?: CuaParticipantDeps[K] | undefined;
 };
 /**
  * One run's participant deps. Call it once per run: the run budget it creates is the one ledger

package/dist/routes/computer-use/plan.js

@@ -2,6 +2,7 @@
 // in its order and with its codes, then the plan the run uses. What stays in the route reads
 // external state: committed personas, a rerun's source run, keys, the local agent, subject env
 // values, spend-cap prices and the comms catch.
+import { MODAL_MAX_SANDBOX_MS } from "../../substrates/modal/sdk.js";
 import { DESKTOP_FILES_ROUTE_REASON } from "../../study/desktop-files.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
@@ -206,12 +207,14 @@ function startsOf(config, runner, limits, ceilingMs) {
     const declared = config.execution?.concurrency;
     const n = runner.participants.length;
     const hosted = runner.desktop === "e2b-desktop";
+    // The E2B plan's limit binds only E2B desktops; Modal's container limit is far above a study's.
+    const e2bHosted = hosted && runner.provider === "e2b";
     const atOnce = participantsAtOnce({
         concurrency: boundedConcurrency(declared, n),
         declared: declared !== undefined,
         participants: n,
     }, {
-        ...(hosted ? { sandboxes: limits.concurrentSandboxes } : {}),
+        ...(e2bHosted ? { sandboxes: limits.concurrentSandboxes } : {}),
         cap: limits.concurrencyCap,
     });
     if (!atOnce.ok)
@@ -265,6 +268,54 @@ function timeZoneRunnerReason(desktop, participants) {
         ? `${declared} This study runs on the local browser runtime. Remove actor.clock and participants[].clock, or set execution.target: e2b-desktop.`
         : `${declared} This study drives your own browser through RunStudyOptions.inProcess. Remove actor.clock and participants[].clock, and set the zone in that browser yourself, or run on a hosted desktop.`;
 }
+/** Who hosts the study's desktops and the longest sandbox they allow, or why it cannot run. */
+function hostingOf(config, e2bCeiling) {
+    if (config.execution?.target !== "modal-desktop")
+        return e2bCeiling.ok
+            ? { provider: "e2b", ceiling: e2bCeiling }
+            : { refusal: e2bCeiling.message };
+    const refusal = modalDesktopRefusal(config);
+    return refusal === undefined
+        ? { provider: "modal", ceiling: { ms: MODAL_MAX_SANDBOX_MS } }
+        : { refusal };
+}
+/** The app-url subject the study names, and the subject a hosted desktop provisions. */
+function subjectsOf(config) {
+    const appUrl = config.subject.appUrl ?? "";
+    const declaredServeUrl = config.subject.serve?.url;
+    const serveUrl = declaredServeUrl === undefined ? {} : { serveUrl: declaredServeUrl };
+    const appUrlSubject = {
+        kind: "app-url",
+        appUrl,
+        publicTargets: config.policies?.allowPublicTargets === true,
+        ...serveUrl,
+    };
+    const product = config.subject.product;
+    const hosted = config.subject.source === "desktop-cli" && product !== undefined
+        ? { kind: "desktop-cli", product, ...serveUrl }
+        : (provisionedSubject(config) ?? appUrlSubject);
+    return { appUrl, appUrlSubject, hosted };
+}
+/**
+ * What a study on a Modal desktop cannot have that one on an E2B desktop can, or undefined. The
+ * Modal desktop runs an app-url subject in Chromium; provisioned subjects, a terminal subject,
+ * E2B templates and the speech template are E2B's.
+ */
+function modalDesktopRefusal(config) {
+    const desktop = config.execution?.desktop;
+    if (config.subject.source !== "app-url")
+        return `A Modal desktop runs app-url subjects only, and this study's subject is ${config.subject.source}. Set execution.target: e2b-desktop.`;
+    if (config.route === "shared-world")
+        return "A shared-world study runs on E2B desktops only. Set execution.target: e2b-desktop.";
+    if (desktop?.template !== undefined)
+        return "execution.desktop.template names an E2B template, which a Modal desktop cannot use. Remove it, or set execution.target: e2b-desktop.";
+    if (desktop?.media !== undefined)
+        return "execution.desktop.media needs the E2B speech or camera template, which a Modal desktop does not have. Remove it, or set execution.target: e2b-desktop.";
+    const browser = desktop?.browser;
+    if (browser !== undefined && browser !== "default" && browser !== "chromium")
+        return `A Modal desktop has Chromium only, and execution.desktop.browser is ${browser}. Set it to chromium or default, or set execution.target: e2b-desktop.`;
+    return undefined;
+}
 /** What the participants declare that this runner cannot do, with its code, or undefined. */
 function runnerRefusal(desktop, participants) {
     const files = desktopFilesRunnerReason(desktop, participants);
@@ -304,9 +355,10 @@ export function planComputerUseStudy(config, input) {
     if (!descriptor || !isCuaActorDescriptor(descriptor))
         return refuse("in-scope", "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered computer-use actor.`);
     const actor = descriptor.id;
-    const ceiling = input.sandboxCeiling;
-    if (!ceiling.ok)
-        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", ceiling.message, actor);
+    const hosting = hostingOf(config, input.sandboxCeiling);
+    if ("refusal" in hosting)
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", hosting.refusal, actor);
+    const { provider, ceiling } = hosting;
     const rejection = cuaStudyRejection(config, hasRunSession, driving, declaredSubjectRoute(config, driving), ceiling.ms);
     if (rejection)
         return refuse("in-scope", rejection.code, rejection.message, actor);
@@ -335,19 +387,7 @@ export function planComputerUseStudy(config, input) {
         return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunStudyOptions.inProcess): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
     if (first === undefined)
         throw new Error("computerUseParticipants returned no participant");
-    const appUrl = config.subject.appUrl ?? "";
-    const declaredServeUrl = config.subject.serve?.url;
-    const serveUrl = declaredServeUrl === undefined ? {} : { serveUrl: declaredServeUrl };
-    const appUrlSubject = {
-        kind: "app-url",
-        appUrl,
-        publicTargets: config.policies?.allowPublicTargets === true,
-        ...serveUrl,
-    };
-    const product = config.subject.product;
-    const hosted = source === "desktop-cli" && product !== undefined
-        ? { kind: "desktop-cli", product, ...serveUrl }
-        : (provisionedSubject(config) ?? appUrlSubject);
+    const { appUrl, appUrlSubject, hosted } = subjectsOf(config);
     const brain = brainOf(config, driving.createProvider);
     const runner = driving.inProcess
         ? {
@@ -358,7 +398,13 @@ export function planComputerUseStudy(config, input) {
         }
         : isLocalBrowserStudy(config)
             ? { desktop: "local-vm", brain, participants: [first, ...rest], subject: appUrlSubject }
-            : { desktop: "e2b-desktop", brain, participants: [first, ...rest], subject: hosted };
+            : {
+                desktop: "e2b-desktop",
+                provider,
+                brain,
+                participants: [first, ...rest],
+                subject: hosted,
+            };
     const unsupported = runnerRefusal(runner.desktop, participants);
     if (unsupported)
         return refuse("in-scope", unsupported.code, unsupported.message, actor);
@@ -382,7 +428,8 @@ export function planComputerUseStudy(config, input) {
             requirements: base.dryRun || runner.desktop === "in-process"
                 ? []
                 : desktopRequirements(config, {
-                    e2b: runner.desktop === "e2b-desktop",
+                    e2b: runner.desktop === "e2b-desktop" && runner.provider === "e2b",
+                    modal: runner.desktop === "e2b-desktop" && runner.provider === "modal",
                     brain,
                     localVm: runner.desktop === "local-vm",
                     externalCatch: !provisioned,

package/dist/routes/computer-use/setup.js

@@ -125,13 +125,8 @@ export async function admitCuaRun(plan, input, config) {
     // Read keys once into locals (names only; values never logged or persisted).
     const openaiApiKey = env.OPENAI_API_KEY?.trim() ?? "";
     const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
-    // Literal scrubber for every known provisioned value (no secret "shape" to pattern-match).
-    // Dry and in-process runs scrub both keys too: a mission or persona can still quote them.
-    const secrets = new RunSecrets([
-        openaiApiKey,
-        e2bApiKey,
-        ...subjectEnvNames.map((name) => env[name] ?? ""),
-    ]);
+    // Every known key and subject value, scrubbed literally, in dry and in-process runs too.
+    const secrets = new RunSecrets([openaiApiKey, e2bApiKey, ...otherValues(env, subjectEnvNames)]);
     sanitizeParticipantRuns(participantRuns, secrets.scrub);
     const desktopFiles = await readStudyDesktopFiles(input.cwd, plan, participantRuns, secrets.scrub);
     if (!desktopFiles.ok)
@@ -342,6 +337,7 @@ function cuaParticipantDeps(plan, input, admitted, run) {
         prepareDesktop: input.prepareDesktop,
     }, {
         createDesktop: input.localVm?.desktop,
+        sandboxProvider: plan.runner.desktop === "e2b-desktop" ? plan.runner.provider : undefined,
         ...callerDriving(input, config),
         localTreeArchiveBuffer: admitted.localTreeArchiveBuffer,
         desktopFiles: admitted.desktopFiles.size === 0 ? undefined : admitted.desktopFiles,
@@ -373,3 +369,14 @@ function subjectPhaseReporter(input) {
         input.emit?.(phaseEvent(event, { kind: "participant", participant }));
     };
 }
+/**
+ * The Modal token pair's values, which a provider error can quote into run warnings, and the
+ * subject env values the study names.
+ */
+function otherValues(env, subjectEnv) {
+    return [
+        env.MODAL_TOKEN_ID?.trim() ?? "",
+        env.MODAL_TOKEN_SECRET?.trim() ?? "",
+        ...subjectEnv.map((name) => env[name] ?? ""),
+    ];
+}

package/dist/routes/computer-use/types.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxProviderId } from "../../run/sandbox-receipts.js";
 import type { Verdict } from "../../run/judge.js";
 import type { HostSuspensionReading } from "../../run/host-suspension.js";
 import type { LocalCapacity } from "../../substrates/local/capacity.js";
@@ -344,6 +345,8 @@ export interface E2BDesktopDeps {
     now: () => number;
     /** Loads the E2B SDK for the participant's desktop. Defaults to loadE2BDesktopModule. */
     desktopModule?: () => Promise<E2BDesktopModule>;
+    /** Who hosts the participant's desktop; E2B when unset. */
+    sandboxProvider?: SandboxProviderId;
     /** The caller's prepareDesktop, called with the participant as its target. */
     prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
     /** Clock and sleep for detached provisioning steps. */

package/dist/run/bundle-shape.js

@@ -93,7 +93,7 @@ export function isRunOutcome(value) {
 function isRunProviderResource(value) {
     return (isRecord(value) &&
         value.schema === "humanish.provider-resource.v1" &&
-        value.provider === "e2b-desktop" &&
+        (value.provider === "e2b-desktop" || value.provider === "modal-desktop") &&
         value.kind === "sandbox" &&
         typeof value.id === "string" &&
         value.id.trim().length > 0 &&

package/dist/run/bundle.d.ts

@@ -53,7 +53,7 @@ export interface RunFeedbackCandidate {
     scenario_id: string;
     persona_id: string;
     actor: "codex-tui" | "codex-exec" | "codex-app-server" | "computer-use" | "synthetic-dry-run" | "unknown";
-    substrate: "e2b-desktop" | "local-desktop" | "e2b-terminal" | "local-filesystem" | "codex-app-server" | "unknown";
+    substrate: "e2b-desktop" | "modal-desktop" | "local-desktop" | "e2b-terminal" | "local-filesystem" | "codex-app-server" | "unknown";
     failure_owner: "harness" | "target-app" | "actor" | "environment" | "unknown";
     summary: string;
     expected: string;
@@ -479,7 +479,8 @@ export interface RunCostSummary {
 }
 export interface RunProviderResource {
     schema: "humanish.provider-resource.v1";
-    provider: "e2b-desktop";
+    /** The hosted desktop's provider: E2B, or Modal for `execution.target: modal-desktop`. */
+    provider: "e2b-desktop" | "modal-desktop";
     kind: "sandbox";
     /**
      * "[redacted-sandbox-id]" in runs from 0.110 on; earlier runs recorded the raw id here. The raw id

package/dist/run/feedback-shape.js

@@ -66,6 +66,7 @@ function isFeedbackActor(value) {
 }
 function isFeedbackSubstrate(value) {
     return (value === "e2b-desktop" ||
+        value === "modal-desktop" ||
         value === "local-desktop" ||
         value === "e2b-terminal" ||
         value === "local-filesystem" ||

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}".`;

package/dist/study/doctor.d.ts

@@ -22,10 +22,13 @@ type CodexReadiness = {
     protocolIncompatibilities?: readonly string[];
     /** Schema values beyond the baseline, recorded by a launch that passed. */
     protocolAdditions?: readonly string[];
+    /** What in the operator's Codex setup the launch refused, without paths or values. */
+    refusalReason?: string;
 };
 /** What doctor's hosted Codex participant check found: a readiness result and what it admitted. */
 type HostedCodexReadiness = CodexReadiness & {
     cliVersion?: string;
+    operatorInstructionFiles?: readonly string[];
     resolvedModel?: string;
     authentication?: "chatgpt-account" | "api-key";
 };

package/dist/study/doctor.js

@@ -5,6 +5,7 @@ import { capacityShortfall, describeCapacity, } from "../substrates/local/capaci
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { localAgentReady, localAgentVersionRefusal, } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
+import { operatorInstructionsWarning } from "../actors/codex/operator-instructions.js";
 import { admissionRule } from "../analysis/admission.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
@@ -90,6 +91,8 @@ function codexRecovery(readiness, fallback) {
             return codexVersionRecovery(readiness.detectedCliVersion, readiness.installation);
         case "codex_incompatible_release":
             return `${protocolIncompatibilityMessage(readiness.detectedCliVersion, readiness.protocolIncompatibilities ?? [])} ${codexInstallAdvice(readiness.installation)} Then sign in with a ChatGPT account (\`codex login\`).`;
+        case "codex_unsafe_configuration":
+            return unsafeConfigurationRecovery(readiness.refusalReason, fallback);
         case "codex_login_required":
             return "Codex is installed but not signed in. Run `codex login` and sign in with a ChatGPT account.";
         case "codex_unsupported_auth":
@@ -107,6 +110,12 @@ function codexRecovery(readiness, fallback) {
             return fallback;
     }
 }
+/** What the refused setting is and how to change it; the fallback when no reason was recorded. */
+function unsafeConfigurationRecovery(reason, fallback) {
+    if (reason === undefined)
+        return fallback;
+    return `humanish stopped the Codex launch because ${reason}. Change that setting in the Codex config (~/.codex/config.toml, a profile, or a system config) if you want hosted participants to use it, then rerun doctor.`;
+}
 /** Shared read-only Codex account check for local participants in doctor and the TUI. */
 export async function localCodexParticipantCheck(args) {
     const readiness = await (args.readiness ?? codexAccountReadiness)(args.env).catch(() => ({ ready: false, errorCode: "codex_unavailable" }));
@@ -320,6 +329,7 @@ async function hostedCodexParticipantCheck(args, actor) {
         ...(actor?.reasoningEffort === undefined ? {} : { reasoningEffort: actor.reasoningEffort }),
     };
     const readiness = await (args.codexParticipantReadiness ?? hostedCodexReadiness)(args.env, declared).catch(() => ({ ready: false, errorCode: "codex_unavailable" }));
+    const operatorNote = operatorInstructionsWarning(readiness.operatorInstructionFiles);
     const account = readiness.authentication === "api-key"
         ? "an API key, which bills its usage to that key"
         : "a ChatGPT account";
@@ -327,7 +337,7 @@ async function hostedCodexParticipantCheck(args, actor) {
         name: "local participant authentication",
         ok: readiness.ready,
         message: readiness.ready
-            ? readyMessage(`Codex CLI ${readiness.cliVersion ?? "(unknown release)"} passed the operator handshake without a turn (initialize, config/read, account/read and an ephemeral thread/start): model ${readiness.resolvedModel ?? "(not reported)"} on ${account}. E2B supplies the desktop; no OpenAI API key is required for this participant.`, readiness)
+            ? readyMessage(`Codex CLI ${readiness.cliVersion ?? "(unknown release)"} passed the operator handshake without a turn (initialize, config/read, account/read and an ephemeral thread/start): model ${readiness.resolvedModel ?? "(not reported)"} on ${account}. E2B supplies the desktop; no OpenAI API key is required for this participant.${operatorNote === undefined ? "" : ` ${operatorNote}`}`, readiness)
             : `Hosted Codex participant setup is unavailable (${readiness.errorCode}). ${codexRecovery(readiness, "Check `codex login status` and the operator's Codex configuration, then rerun doctor.")} No API fallback is used.`,
     };
 }

package/dist/study/parse/execution.js

@@ -17,8 +17,9 @@ export function parseExecution(raw) {
         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, or 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

@@ -133,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 | {

package/dist/study/types.d.ts

@@ -467,7 +467,7 @@ export interface StudyActor {
      */
     dwell?: DwellWindow;
 }
-type StudyExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal" | "modal-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/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 {};