humanish 0.138.0 → 0.139.0

package/CHANGELOG.md

@@ -8,6 +8,17 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.139.0: Computer-use studies can run on Modal desktops (2026-10-19)
+
+humanish 0.139.0 can run a computer-use study's desktops on Modal. Set
+`execution.target: modal-desktop` on an `app-url` study and each participant gets its own Modal
+sandbox running the same desktop the E2B route uses: Xvfb, XFCE, xdotool input, screenshots, a
+live noVNC stream, Chromium and recordings. The same study file runs on E2B or Modal
+with only the target changed. Clone and local-tree subjects, shared worlds, E2B templates and
+camera or speech media stay on E2B.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.139.0)
+
 ## 0.138.0: A terminal study can run on Modal (2026-10-19)
 
 humanish 0.138.0 can run a terminal study's shell on Modal as well as E2B. Set

package/dist/routes/computer-use/bundle-parts.d.ts

@@ -15,7 +15,10 @@ export declare function describeSubjectState(state: RunSubjectProvenance["state"
 /** Human-readable provenance line for the single-participant subject.provenance event of a clone
  *  or local-tree subject: claims "cloned/packed and served" only when it actually happened. */
 export declare function subjectProvenanceMessage(provenance: RunSubjectProvenance, publicAppUrl: string, dryRun: boolean, hasSession: boolean): string;
+/** The label a run records for the desktop `execution.target` names. */
+export declare function desktopSubstrate(target: string | undefined): "local-desktop" | "modal-desktop" | "e2b-desktop";
 export declare function providerResourcesForOutcome(args: {
+    provider: "e2b-desktop" | "modal-desktop";
     outcome: ParticipantRunOutcome | undefined;
     createdAt: string;
     ids: ParticipantIds;

package/dist/routes/computer-use/bundle-parts.js

@@ -73,6 +73,14 @@ export function subjectProvenanceMessage(provenance, publicAppUrl, dryRun, hasSe
     }
     return "Subject local-tree packing attempted; archive digest unresolved (provisioning failed before resolution)";
 }
+/** The label a run records for the desktop `execution.target` names. */
+export function desktopSubstrate(target) {
+    return target === "local"
+        ? "local-desktop"
+        : target === "modal-desktop"
+            ? "modal-desktop"
+            : "e2b-desktop";
+}
 export function providerResourcesForOutcome(args) {
     if (args.outcome?.sandboxId === undefined) {
         return [];
@@ -80,7 +88,7 @@ export function providerResourcesForOutcome(args) {
     return [
         {
             schema: "humanish.provider-resource.v1",
-            provider: "e2b-desktop",
+            provider: args.provider,
             kind: "sandbox",
             id: args.outcome.sandboxId,
             owner: "humanish",

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

@@ -6,7 +6,7 @@ import { judgeOneParticipant, judgeParticipants } from "../../run/judge.js";
 import { renderReviewMarkdown } from "../../run/review-markdown.js";
 import { desktopSpanToMinutes } from "../../run/cost-summary.js";
 import { e2bDesktopTemplate } from "../../substrates/e2b/sandbox.js";
-import { providerResourcesForOutcome } from "./bundle-parts.js";
+import { desktopSubstrate, providerResourcesForOutcome } from "./bundle-parts.js";
 import { participantFactsOf } from "./participant-facts.js";
 import { buildCuaFanoutBundle } from "./fanout-bundle.js";
 import { buildSingleParticipantBundle } from "./single-bundle.js";
@@ -96,9 +96,7 @@ function singleParticipantArgs(base, state) {
         desktopRoute: base.plan.runner.desktop !== "in-process",
         substrate: base.plan.runner.desktop === "in-process"
             ? "local-filesystem"
-            : plan.residual.execution?.target === "local"
-                ? "local-desktop"
-                : "e2b-desktop",
+            : desktopSubstrate(plan.residual.execution?.target),
         ...(outcome?.desktopGeometry === undefined ? {} : { desktopGeometry: outcome.desktopGeometry }),
         ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
         ...(outcome?.networkLog === undefined ? {} : { network: outcome.networkLog }),
@@ -127,6 +125,7 @@ function singleParticipantArgs(base, state) {
         ...(desktopTemplate === undefined ? {} : { desktopTemplate }),
         ...(outcome?.desktopBrowser === undefined ? {} : { desktopBrowser: outcome.desktopBrowser }),
         providerResources: providerResourcesForOutcome({
+            provider: base.plan.residual.execution?.target === "modal-desktop" ? "modal-desktop" : "e2b-desktop",
             outcome,
             createdAt: base.run.createdAt,
             ids: spec,

package/dist/routes/computer-use/e2b-desktop/prepare.js

@@ -11,6 +11,7 @@ import { observeDesktopResources } from "../../../substrates/e2b/desktop-resourc
 import { acquireE2BDesktopSandbox, e2bDesktopTemplate, withOneRetryOnTransientE2BError, } from "../../../substrates/e2b/sandbox.js";
 import { loadE2BDesktopModule } from "../../../substrates/e2b/sdk.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
+import { loadModalDesktopModule } from "../../../substrates/modal/sandbox.js";
 import { attachReceivingInbox, participantCommsEnv, startCommsCatch } from "./comms.js";
 import { participantSubjectEnv } from "../types.js";
 import { plural } from "../../../run/text.js";
@@ -30,11 +31,14 @@ export async function acquireParticipantDesktop(ctx, state) {
     // Off-app comms: the base-URL env is injected at sandbox create, so the app reads it at
     // boot; the catch starts right after create.
     const commsEnv = participantCommsEnv(ctx.comms);
-    const desktopModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
+    const provider = deps.sandboxProvider ?? "e2b";
+    const desktopModule = await (deps.desktopModule ??
+        (provider === "modal" ? () => loadModalDesktopModule(env) : loadE2BDesktopModule))();
     // An explicit template wins. Speech gets the versioned media image; ordinary
-    // browser studies retain the SDK default desktop.
+    // browser studies retain the SDK default desktop. A Modal desktop has one image.
     const acquired = await acquireE2BDesktopSandbox({
         module: desktopModule,
+        provider,
         options: {
             apiKey: deps.e2bApiKey,
             requestTimeoutMs: deps.requestTimeoutMs,
@@ -67,7 +71,7 @@ export async function acquireParticipantDesktop(ctx, state) {
             dpi: 96,
             lifecycle: { onTimeout: "kill" },
         },
-        template: e2bDesktopTemplate(residual),
+        template: provider === "modal" ? undefined : e2bDesktopTemplate(residual),
         retry: {
             // The default loader reclaims an acquired handle before retrying failed desktop startup.
             // Its error names the cleanup outcome; pre-construction allocation failures remain unowned.
@@ -92,7 +96,7 @@ export async function acquireParticipantDesktop(ctx, state) {
     state.sandboxId = acquired.allocation.resourceId;
     // The billed span starts the instant the sandbox exists.
     state.sandboxCreatedAtMs = deps.now();
-    const desktopResources = await observeDesktopResources(desktop);
+    const desktopResources = await observeDesktopResources(desktop, undefined, provider === "modal" ? "modal.create" : "e2b.getInfo");
     state.desktopResources = desktopResources;
     if ("reason" in desktopResources) {
         warnings.push(`Desktop resource size unavailable (${desktopResources.reason}); compute cost remains unpriced.`);

package/dist/routes/computer-use/fanout-bundle.js

@@ -5,7 +5,7 @@ import { cuaGoalSource } from "../../actors/goal-source.js";
 import { redactEncodedText } from "../../evidence/encoded-text.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, gapsListClause, skippedSentence, withCuaReviewProvenance, } from "../../run/outcomes.js";
-import { providerResourcesForOutcome, publicSafeAppUrlLabel, streakGaps } from "./bundle-parts.js";
+import { desktopSubstrate, providerResourcesForOutcome, publicSafeAppUrlLabel, streakGaps, } from "./bundle-parts.js";
 import { subjectName } from "../../run/subject-name.js";
 import { participantFeedbackCandidates } from "./participant-feedback.js";
 import { participantFactsOf } from "./participant-facts.js";
@@ -179,7 +179,7 @@ function fanoutFeedbackCandidates(args) {
             runId: args.run.runId,
             scenarioId: `cua-${plan.studyId}`,
             adapterId: plan.studyId,
-            substrate: plan.residual.execution?.target === "local" ? "local-desktop" : "e2b-desktop",
+            substrate: desktopSubstrate(plan.residual.execution?.target),
             participants: specs.map((spec, index) => {
                 const outcome = outcomes?.[index];
                 return {
@@ -241,6 +241,7 @@ export function buildCuaFanoutBundle(args) {
     const desktopTemplate = e2bDesktopTemplate(plan.residual);
     const desktopBrowser = fanoutDesktopBrowser(args);
     const providerResources = (outcomes ?? []).flatMap((outcome) => providerResourcesForOutcome({
+        provider: plan.residual.execution?.target === "modal-desktop" ? "modal-desktop" : "e2b-desktop",
         outcome,
         createdAt: args.run.createdAt,
         ids: outcome.spec,

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/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>;