humanish 0.137.0 → 0.138.0

package/dist/run/reclaim.js

@@ -1,14 +1,16 @@
 // `humanish reclaim`: stop an interrupted run's sandboxes and report what happened to each. It
 // finds them three ways: the exact ids the run journaled at create time (sandbox-receipts.ndjson),
 // the ids a create in this process reported before its receipt landed (the signal handler only),
-// and E2B's list of sandboxes tagged with the run's owner tags (sandboxOwnerTags), which covers a
-// sandbox whose id never reached the run. The list is filtered server-side by the run's tags and
+// and each provider's list of sandboxes tagged with the run's owner tags (sandboxOwnerTags), which
+// covers a sandbox whose id never reached the run. Every sandbox is acted on through the provider
+// its receipt or owner line names: E2B, or Modal (src/substrates/modal/sandbox.ts). The list is filtered server-side by the run's tags and
 // each result is checked against every tag again, so it can only return this run's sandboxes; an
 // account-wide operation once destroyed unrelated infrastructure. Kills run concurrently, and
 // reclaim-receipt.json is written before the first kill and after each one, so an exit at any
-// point leaves a record of every sandbox not yet confirmed gone. `--check` asks E2B the same
-// questions and kills nothing.
+// point leaves a record of every sandbox not yet confirmed gone. `--check` asks the providers the
+// same questions and kills nothing.
 import { e2bAccount, e2bConnection } from "../substrates/e2b/connection.js";
+import { modalAccount } from "../substrates/modal/sandbox.js";
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
 import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
@@ -261,6 +263,45 @@ function unreadableMessage(file, refusal) {
     const kept = file === SANDBOX_RECEIPTS_ARTIFACT ? "the receipts were kept" : "the receipt was kept";
     return `${refusalText(file, refusal)}. Nothing was killed and ${kept}; check the file, then run reclaim again.`;
 }
+/**
+ * The account for each provider the run's journal names, or the message that stops reclaim when
+ * one it needs cannot be reached. A run with no record and creates in flight is an E2B run unless
+ * its owner line says otherwise, as every run was before Modal.
+ */
+async function reachProviders(receipts, owners, hooks) {
+    const env = hooks.env ?? process.env;
+    const recorded = new Set([
+        ...receipts.map((receipt) => receipt.provider),
+        ...owners.map((owner) => owner.provider),
+    ]);
+    // A create this process began counts too: its receipt and owner line may not have landed.
+    for (const provider of hooks.creates?.providers() ?? [])
+        recorded.add(provider);
+    const needsE2B = recorded.has("e2b") || (hooks.creates !== undefined && !recorded.has("modal"));
+    // E2B's SDK lists by tag as well as killing by id, so it is needed even with no receipt. Without
+    // it, an E2B receipt cannot be acted on; with no E2B receipt, only the tag search is lost.
+    const accounts = {};
+    const unavailable = {};
+    try {
+        const module = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        accounts.e2b = e2bAccount(module, e2bConnection(env));
+    }
+    catch (error) {
+        unavailable.e2b = `Cannot load @e2b/desktop to reach E2B: ${redactText(toErrorMessage(error))}`;
+        if (needsE2B)
+            return unavailable.e2b;
+    }
+    // Modal is reached only for a run that recorded a Modal sandbox or owner line.
+    if (recorded.has("modal")) {
+        try {
+            accounts.modal = await (hooks.loadModalAccount ?? modalAccount)(env);
+        }
+        catch (error) {
+            return `Cannot reach Modal: ${redactText(toErrorMessage(error))}`;
+        }
+    }
+    return { accounts, unavailable, recorded, needsE2B };
+}
 /**
  * Find and stop (or, for `--check`, look up) every sandbox one directory owns: its receipts, the
  * creates this process reported, and E2B's tagged list, each once by exact id.
@@ -277,19 +318,10 @@ async function reclaimRoot(root, label, hooks, warnings) {
     const owners = parseSandboxOwners(journal, label);
     const check = hooks.check === true;
     const requestTimeoutMs = hooks.requestTimeoutMs ?? 60_000;
-    // The SDK lists by tag as well as killing by id, so it is needed even with no receipt. Without
-    // it, an E2B receipt cannot be acted on; with no E2B receipt, only the tag search is lost.
-    let e2b;
-    let moduleError;
-    try {
-        const module = await (hooks.loadModule ?? loadE2BDesktopModule)();
-        e2b = e2bAccount(module, e2bConnection(hooks.env ?? process.env));
-    }
-    catch (error) {
-        moduleError = `Cannot load @e2b/desktop to reach E2B: ${redactText(toErrorMessage(error))}`;
-        if (receipts.some((receipt) => receipt.provider === "e2b") || hooks.creates !== undefined)
-            return { kind: "module-unavailable", receiptCount: receipts.length, message: moduleError };
-    }
+    const reached = await reachProviders(receipts, owners, hooks);
+    if (typeof reached === "string")
+        return { kind: "module-unavailable", receiptCount: receipts.length, message: reached };
+    const { accounts, unavailable, recorded, needsE2B } = reached;
     // An earlier reclaim may have killed a sandbox no receipt names (the signal handler's creates
     // and tag finds). Its outcome is carried forward, so a later reclaim never erases that record.
     const earlier = check ? [] : await earlierOutcomes(root, label);
@@ -297,7 +329,7 @@ async function reclaimRoot(root, label, hooks, warnings) {
     if (!Array.isArray(earlier))
         return { kind: "unreadable", message: unreadableMessage(RECLAIM_RECEIPT_ARTIFACT, earlier) };
     const set = targetSet({
-        e2b,
+        accounts,
         check,
         requestTimeoutMs,
         earlier,
@@ -312,38 +344,53 @@ async function reclaimRoot(root, label, hooks, warnings) {
         if (replaying)
             replayed.set(sandbox.sandboxId, sandbox);
         else
-            set.add("e2b", sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
+            set.add(sandbox.provider, sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
     });
     replaying = false;
     for (const receipt of receipts) {
-        const released = receipt.provider === "e2b" && replayed.get(receipt.sandboxId)?.released;
+        const create = replayed.get(receipt.sandboxId);
+        const released = create?.provider === receipt.provider && create.released;
         set.add(receipt.provider, receipt.sandboxId, receipt.laneId, "receipt", released === true);
     }
     for (const sandbox of replayed.values())
-        set.add("e2b", sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
+        set.add(sandbox.provider, sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
     await set.start();
     if (hooks.creates !== undefined)
         await settledWithin(hooks.creates.settled, hooks.createsWaitMs);
-    // The tags the run recorded before each create, and this directory's own: a copied or moved
-    // run directory computes other tags than the ones its sandboxes carry.
-    const search = await searchTagSets(e2b, [...owners, sandboxOwnerTags(root)], {
-        requestTimeoutMs,
-        unavailable: moduleError ?? "no E2B SDK",
-    });
+    // Each provider is searched with the tags the run recorded for it before each create, and with
+    // this directory's own: a copied or moved run directory computes other tags than the ones its
+    // sandboxes carry. E2B is searched unless the journal names only Modal, as before Modal existed.
+    const providers = [
+        ...(needsE2B || !recorded.has("modal") ? ["e2b"] : []),
+        ...(accounts.modal === undefined ? [] : ["modal"]),
+    ];
+    const searches = await Promise.all(providers.map(async (provider) => {
+        const tagSets = [
+            ...owners.filter((owner) => owner.provider === provider).map((owner) => owner.tags),
+            sandboxOwnerTags(root),
+        ];
+        const result = await searchTagSets(accounts[provider], tagSets, {
+            requestTimeoutMs,
+            unavailable: unavailable[provider] ?? `no ${provider} account`,
+        });
+        return { provider, result };
+    }));
     let found = 0;
-    for (const listed of search.sandboxes) {
-        const metadata = listed.metadata ?? {};
-        const participant = metadata.participantId ?? metadata.kind ?? "unknown";
-        if (set.add("e2b", listed.sandboxId, participant, "tag"))
-            found += 1;
-    }
+    for (const { provider, result } of searches)
+        for (const listed of result.sandboxes) {
+            const metadata = listed.metadata ?? {};
+            const participant = metadata.participantId ?? metadata.kind ?? "unknown";
+            if (set.add(provider, listed.sandboxId, participant, "tag"))
+                found += 1;
+        }
+    const search = searches.find(({ result }) => result.status !== "done")?.result ?? searches[0].result;
     const tagSearch = {
         status: search.status,
         found,
         ...(search.detail === undefined ? {} : { detail: search.detail }),
     };
     if (search.status !== "done")
-        warnings.push(`Could not search E2B for sandboxes tagged with ${label}: ${search.detail ?? search.status}. A sandbox whose id never reached a receipt would not be found.`);
+        warnings.push(`Could not search for sandboxes tagged with ${label}: ${search.detail ?? search.status}. A sandbox whose id never reached a receipt would not be found.`);
     // A create that reports its id while the search or a kill is still running is killed too.
     await set.drain();
     unwatch?.();

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

@@ -1,5 +1,5 @@
 import type { PreparedOutputRoot } from "./contained-output.js";
-import type { SandboxOwnerTags } from "./sandbox-receipts.js";
+import type { SandboxOwnerTags, SandboxProviderId } from "./sandbox-receipts.js";
 /** Refuses a sandbox create for a run directory whose process is stopping. */
 export declare class SandboxCreateRefusedError extends Error {
     constructor();
@@ -7,6 +7,7 @@ export declare class SandboxCreateRefusedError extends Error {
 /** One sandbox a create in this process reported, and what its route did with it. */
 export interface CreatedSandbox {
     sandboxId: string;
+    provider: SandboxProviderId;
     /** The participant or subject label the receipt also records. */
     participantId: string;
     /** True once the route's own release confirmed the sandbox gone. */
@@ -32,14 +33,14 @@ export interface SandboxCreateTicket {
     settled(): void;
 }
 /** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
-export declare function beginSandboxCreate(root: PreparedOutputRoot, participantId: string): SandboxCreateTicket;
+export declare function beginSandboxCreate(root: PreparedOutputRoot, participantId: string, provider: SandboxProviderId): SandboxCreateTicket;
 /**
- * Run `write` once per directory and return its promise to every caller. Creates that start
+ * Run `write` once per directory and provider and return its promise to every caller. Creates that start
  * together then resume in the order they called, so the order they reach the provider does not
  * depend on which file append finishes first. A write that reports failure is forgotten, so the
  * next create tries again.
  */
-export declare function recordSandboxOwnerOnce(root: PreparedOutputRoot, write: () => Promise<boolean>): Promise<void>;
+export declare function recordSandboxOwnerOnce(root: PreparedOutputRoot, provider: SandboxProviderId, write: () => Promise<boolean>): Promise<void>;
 /** What the signal handler holds after stopping a directory's creates. */
 export interface StoppedSandboxCreates {
     /**
@@ -51,6 +52,8 @@ export interface StoppedSandboxCreates {
     settled: Promise<void>;
     /** How many of those creates have not settled yet. */
     inFlight(): number;
+    /** The providers creates began on, including those whose id has not arrived. */
+    providers(): ReadonlySet<SandboxProviderId>;
 }
 /**
  * Stop `root`'s creates: any create that starts from now on is refused. Called synchronously when

package/dist/run/sandbox-creates.js

@@ -36,6 +36,8 @@ function directoryFor(root) {
         return existing;
     const created = {
         stopping: false,
+        ownerLines: new Map(),
+        providers: new Set(),
         created: new Map(),
         inFlight: new Set(),
         listeners: new Set(),
@@ -73,10 +75,11 @@ export function sandboxOwnerTags(root) {
     return { tool: "humanish", runId: path.basename(where), runKey };
 }
 /** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
-export function beginSandboxCreate(root, participantId) {
+export function beginSandboxCreate(root, participantId, provider) {
     const directory = directoryFor(root);
     if (directory.stopping)
         throw new SandboxCreateRefusedError();
+    directory.providers.add(provider);
     let settle;
     const done = new Promise((resolve) => {
         settle = resolve;
@@ -87,7 +90,7 @@ export function beginSandboxCreate(root, participantId) {
         created(sandboxId) {
             if (directory.created.has(sandboxId))
                 return;
-            const sandbox = { sandboxId, participantId, released: false };
+            const sandbox = { sandboxId, provider, participantId, released: false };
             directory.created.set(sandboxId, sandbox);
             for (const listener of directory.listeners)
                 listener(sandbox);
@@ -104,17 +107,21 @@ export function beginSandboxCreate(root, participantId) {
     };
 }
 /**
- * Run `write` once per directory and return its promise to every caller. Creates that start
+ * Run `write` once per directory and provider and return its promise to every caller. Creates that start
  * together then resume in the order they called, so the order they reach the provider does not
  * depend on which file append finishes first. A write that reports failure is forgotten, so the
  * next create tries again.
  */
-export function recordSandboxOwnerOnce(root, write) {
-    const directory = directoryFor(root);
-    const pending = (directory.ownerLine ??= write().then((written) => {
-        if (!written && directory.ownerLine === pending)
-            delete directory.ownerLine;
-    }));
+export function recordSandboxOwnerOnce(root, provider, write) {
+    const { ownerLines } = directoryFor(root);
+    const existing = ownerLines.get(provider);
+    if (existing !== undefined)
+        return existing;
+    const pending = write().then((written) => {
+        if (!written && ownerLines.get(provider) === pending)
+            ownerLines.delete(provider);
+    });
+    ownerLines.set(provider, pending);
     return pending;
 }
 /**
@@ -136,5 +143,6 @@ export function stopSandboxCreates(root) {
         },
         settled: Promise.all(pending).then(() => undefined),
         inFlight: () => pending.filter((create) => directory.inFlight.has(create)).length,
+        providers: () => directory.providers,
     };
 }

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

@@ -258,15 +258,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 +275,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,11 @@ 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-terminal") {
+            return invalid("`execution.target` must be local, e2b-desktop, e2b-terminal, or modal-terminal.");
         }
         execution.target = target;
     }

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. */
  | {
@@ -223,6 +224,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-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/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/modal/image.d.ts

@@ -0,0 +1,9 @@
+import type { ModalClient, ModalImage } from "./sdk.js";
+/** The sandbox account commands run as, matching E2B's `user` and its home. */
+export declare const MODAL_SANDBOX_USER: {
+    readonly name: "user";
+    readonly uid: 1000;
+    readonly home: "/home/user";
+};
+/** The terminal route's image: a Debian shell with a passwordless-sudo `user`, as on E2B. */
+export declare function modalShellImage(client: ModalClient): ModalImage;