humanish 0.136.1 → 0.138.0

package/dist/routes/terminal/live-sandbox.js

@@ -11,6 +11,7 @@ import { extractLocalActorVerdict, normalizeLocalActorTranscript, } from "../../
 import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { observeDesktopResources, } from "../../substrates/e2b/desktop-resources.js";
 import { acquireE2BShellSandbox } from "../../substrates/e2b/sandbox.js";
+import { loadModalShellModule } from "../../substrates/modal/sandbox.js";
 import { e2bAccount } from "../../substrates/e2b/connection.js";
 import { E2BDesktopStartupError, loadE2BDesktopModule, } from "../../substrates/e2b/sdk.js";
 import { shellQuote } from "../../substrates/shell.js";
@@ -60,7 +61,10 @@ export class LiveTerminalSandbox {
         const { requestTimeoutMs, sandboxTimeoutMs } = this;
         // Declared egress allowlist, or undefined for the historical unrestricted default.
         const egressAllow = plan.egressAllow;
-        const sandboxModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
+        const provider = plan.sandboxProvider;
+        const providerName = provider === "modal" ? "Modal" : "E2B";
+        const sandboxModule = await (deps.desktopModule ??
+            (provider === "modal" ? () => loadModalShellModule(this.inputs.env) : loadE2BDesktopModule))();
         await validatePreparedRunArtifactPaths(runPaths);
         // No sandbox-global env in either mode. In openai-egress, only this host-side SDK request
         // carries the real runtime key; participant commands receive an inert placeholder. The proxy
@@ -83,6 +87,7 @@ export class LiveTerminalSandbox {
         this.account = e2bAccount(sandboxModule, options);
         const acquired = await acquireE2BShellSandbox({
             module: sandboxModule,
+            provider,
             options,
             retry: {
                 // A failed first attempt may have allocated a sandbox whose id never reached this run;
@@ -103,8 +108,8 @@ export class LiveTerminalSandbox {
         this.sandboxId = sandboxId;
         this.createdAtMs = now();
         await validatePreparedRunArtifactPaths(runPaths);
-        recordLifecycle("terminal-lab.sandbox.created", `E2B shell sandbox ${sandboxId} created with allowlisted metadata and kill-on-timeout, and with no sandbox-wide environment variables.`);
-        const sandboxResources = await observeDesktopResources(sandbox);
+        recordLifecycle("terminal-lab.sandbox.created", `${providerName} shell sandbox ${sandboxId} created with allowlisted metadata and kill-on-timeout, and with no sandbox-wide environment variables.`);
+        const sandboxResources = await observeDesktopResources(sandbox, undefined, provider === "modal" ? "modal.create" : "e2b.getInfo");
         this.resources = sandboxResources;
         if ("reason" in sandboxResources) {
             warnings.push(`Sandbox resource size unavailable (${sandboxResources.reason}); its compute cost remains unpriced.`);

package/dist/routes/terminal/plan.js

@@ -7,8 +7,9 @@ import { isReasoningEffort } from "../../actors/reasoning-effort.js";
 import { actorRegistry, isTerminalActorDescriptor } from "../../actors/registry.js";
 import { isNonEmpty, planBase } from "../../study/plan-base.js";
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
-import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { desktopMediaValidationReason, networkCaptureValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { ceilingAdvice } from "../../substrates/e2b/lifetime.js";
+import { MODAL_MAX_SANDBOX_MS, MODAL_TOKEN_ID_ENV, MODAL_TOKEN_SECRET_ENV, } from "../../substrates/modal/sdk.js";
 import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
 import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
@@ -24,7 +25,7 @@ export function planTerminalStudy(config, input) {
     });
     if (String(config.comms?.email?.kind) === "real")
         return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", "Real email receiving is unsupported on the terminal route. Use a supported hosted computer-use browser study.");
-    const mediaReason = desktopMediaValidationReason(config);
+    const mediaReason = desktopMediaValidationReason(config) ?? networkCaptureValidationReason(config, "terminal");
     if (mediaReason)
         return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", mediaReason);
     // A library caller's config skips the parser, which refuses these first.
@@ -34,6 +35,10 @@ export function planTerminalStudy(config, input) {
     const runtimeAuth = config.execution?.runtimeAuth;
     if (runtimeAuth !== undefined && runtimeAuth !== "openai-egress" && runtimeAuth !== "openai-env")
         return refuse("HUMANISH_TERMINAL_CREDENTIAL_DENIED", "`execution.runtimeAuth` must be openai-egress or openai-env. Leave it out for openai-egress, which keeps the OpenAI key outside the sandbox.");
+    const sandboxProvider = config.execution?.target === "modal-terminal" ? "modal" : "e2b";
+    const modal = sandboxProvider === "modal" ? modalRefusal(config) : undefined;
+    if (modal !== undefined)
+        return refuse(modal.code, modal.message);
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
         return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
@@ -64,6 +69,7 @@ export function planTerminalStudy(config, input) {
     const shared = {
         ...base,
         route: "terminal",
+        sandboxProvider,
         actor: descriptor.id,
         product: { ...product, publicSurfaces: surfaces },
         ...(actor?.persona === undefined ? {} : { personaId: actor.persona }),
@@ -107,14 +113,16 @@ export function planTerminalStudy(config, input) {
     // The sandbox's timeout covers the steps before the codex command, maxMinutes and the teardown
     // buffer, and E2B refuses a sandbox past the plan's ceiling. Refuse here, with the arithmetic,
     // rather than after the plan prints, from a provider 400 that names neither knob.
-    const ceiling = input.sandboxCeiling;
+    const ceiling = sandboxProvider === "modal"
+        ? { ok: true, ms: MODAL_MAX_SANDBOX_MS, source: "default" }
+        : input.sandboxCeiling;
     if (!ceiling.ok)
         return refuse("HUMANISH_TERMINAL_CAPS_INVALID", ceiling.message, descriptor.id);
     const productInstall = shared.product.install !== undefined;
     const sandboxTimeoutMs = terminalSandboxTimeoutMs({ maxMinutes, productInstall });
     if (sandboxTimeoutMs > ceiling.ms) {
         const headroomMinutes = (sandboxTimeoutMs - maxMinutes * 60_000) / 60_000;
-        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", `caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${ceiling.ms / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower caps.maxMinutes to at most ${ceiling.ms / 60_000 - headroomMinutes}.${ceilingAdvice(sandboxTimeoutMs)} No sandbox was created and the runtime key was not used.`, descriptor.id);
+        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", `caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${ceiling.ms / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower caps.maxMinutes to at most ${ceiling.ms / 60_000 - headroomMinutes}.${sandboxProvider === "modal" ? " Modal ends every sandbox after 24 hours." : ceilingAdvice(sandboxTimeoutMs)} No sandbox was created and the runtime key was not used.`, descriptor.id);
     }
     return {
         ok: true,
@@ -122,10 +130,45 @@ export function planTerminalStudy(config, input) {
             ...shared,
             dryRun: false,
             caps: { ...caps, maxUsd, maxMinutes },
-            requirements: [
-                { kind: "key", name: "E2B_API_KEY" },
-                { kind: "key-one-of", names: ["CODEX_API_KEY", "OPENAI_API_KEY"] },
-            ],
+            requirements: liveRequirements(sandboxProvider),
         },
     };
 }
+/** The sandbox provider's keys, then the runtime key the agent's command gets. */
+function liveRequirements(provider) {
+    return [
+        ...(provider === "modal"
+            ? [
+                { kind: "key", name: MODAL_TOKEN_ID_ENV },
+                { kind: "key", name: MODAL_TOKEN_SECRET_ENV },
+            ]
+            : [{ kind: "key", name: "E2B_API_KEY" }]),
+        { kind: "key-one-of", names: ["CODEX_API_KEY", "OPENAI_API_KEY"] },
+    ];
+}
+/** What a terminal study on Modal cannot have that one on E2B can. */
+function modalRefusal(config) {
+    // E2B adds the key to requests at its egress proxy for each sandbox. Modal does that only from a
+    // Secret stored in the operator's workspace, so humanish does not place the key there itself.
+    if (config.execution?.runtimeAuth !== "openai-env")
+        return {
+            code: "HUMANISH_TERMINAL_CREDENTIAL_DENIED",
+            message: "On Modal, humanish cannot keep the OpenAI key outside the sandbox: Modal adds a key to outbound requests only from a Secret stored in your Modal workspace. Set `execution.runtimeAuth: openai-env`, which passes the key to the codex command only, or use `execution.target: e2b-terminal`.",
+        };
+    const egress = modalEgressReason(config.execution?.egressAllow);
+    return egress === undefined
+        ? undefined
+        : { code: "HUMANISH_TERMINAL_SUBJECT_INVALID", message: egress };
+}
+const CIDR = /^[0-9a-f:.]+\/\d{1,3}$/i;
+/**
+ * Why a declared egress allowlist cannot run on Modal, or undefined when it can. Modal limits
+ * egress to listed domains or CIDR ranges; an entry that is neither, such as a bare IP address,
+ * has no Modal form.
+ */
+function modalEgressReason(egressAllow) {
+    const unsupported = (egressAllow ?? []).filter((entry) => !CIDR.test(entry) && !/^(\*\.)?([a-z0-9-]+\.)+[a-z0-9-]*[a-z][a-z0-9-]*$/i.test(entry));
+    return unsupported.length === 0
+        ? undefined
+        : `Modal limits egress to domain names and CIDR ranges, and \`execution.egressAllow\` lists ${unsupported.map((entry) => `"${entry}"`).join(", ")}. Write a bare address as a /32 range, or use \`execution.target: e2b-terminal\`.`;
+}

package/dist/routes/terminal/session.js

@@ -95,6 +95,7 @@ export async function runLiveTerminalSession(args) {
         verdictNonce,
         maxMinutes,
         e2bApiKey,
+        env,
         runPaths,
         metadata: buildSandboxMetadata({ studyId: plan.studyId, recordId: "sim-001", runId }),
         warnings,
@@ -160,7 +161,13 @@ async function prepareLivePrompt(args) {
     // anything persists (a key has no detectable "shape" if it is an arbitrary token); redactText is
     // the second pass for secret-shaped content. Applied pre-truncation so a cut can never split a
     // value past the scrubber.
-    const secrets = new RunSecrets([runtimeEnv.keyValue, env.E2B_API_KEY?.trim() ?? ""]);
+    // The sandbox provider's credentials too: a provider error that quotes one reaches the run.
+    const secrets = new RunSecrets([
+        runtimeEnv.keyValue,
+        env.E2B_API_KEY?.trim() ?? "",
+        env.MODAL_TOKEN_ID?.trim() ?? "",
+        env.MODAL_TOKEN_SECRET?.trim() ?? "",
+    ]);
     const sanitize = (text) => redactText(secrets.scrub(text));
     const persona = terminalPersonaRef(terminalPersona, promptDigest, secrets.scrub);
     return {

package/dist/run/bundle.d.ts

@@ -441,7 +441,8 @@ export interface RunCostLine {
             cpuCount: number;
             memoryMiB: number;
         };
-        resourceSource?: "e2b.getInfo";
+        /** E2B's report of the allocation, or the size humanish asked Modal for. */
+        resourceSource?: "e2b.getInfo" | "modal.create";
         resourceUnavailableReason?: "metadata_unavailable" | "metadata_invalid" | "metadata_timeout";
         usdPerSecond?: number;
     };

package/dist/run/cost-summary.js

@@ -1,4 +1,4 @@
-import { estimateActorCostForExecution, estimateAllocatedDesktopCost, estimateDesktopCost, round6, } from "./pricing.js";
+import { estimateActorCostForExecution, estimateAllocatedDesktopCost, estimateDesktopCost, MODAL_SANDBOX_RESOURCE_RATE, round6, } from "./pricing.js";
 import {} from "./bundle.js";
 export function buildRunCostSummary(args) {
     const breakdown = [...modelCostLines(args.participants), ...desktopCostLines(args)];
@@ -76,8 +76,11 @@ function desktopCostLines(args) {
     const breakdown = [];
     for (const usage of args.desktops ?? []) {
         const observation = usage.observation;
-        const resources = observation && "resources" in observation ? observation.resources : undefined;
-        const estimate = estimateAllocatedDesktopCost(usage.minutes, resources);
+        const observed = observation && "resources" in observation ? observation : undefined;
+        const resources = observed?.resources;
+        const estimate = observed?.source === "modal.create"
+            ? estimateAllocatedDesktopCost(usage.minutes, resources, MODAL_SANDBOX_RESOURCE_RATE)
+            : estimateAllocatedDesktopCost(usage.minutes, resources);
         breakdown.push({
             kind: "desktop-minutes",
             ...(usage.participantId === undefined ? {} : { laneId: usage.participantId }),
@@ -88,7 +91,9 @@ function desktopCostLines(args) {
             desktop: {
                 minutes: estimate.minutes,
                 durationBasis: "host-acquired-to-cleanup",
-                ...(resources === undefined ? {} : { resources, resourceSource: "e2b.getInfo" }),
+                ...(observed === undefined
+                    ? {}
+                    : { resources: observed.resources, resourceSource: observed.source }),
                 ...(observation && "reason" in observation
                     ? { resourceUnavailableReason: observation.reason }
                     : {}),

package/dist/run/live-items.d.ts

@@ -13,11 +13,29 @@ export interface LiveItemsCursor {
     items: number;
     bytes: number;
 }
+/** How run.json binds a file of JSON lines: its byte count, its sha256 and its number of lines. */
+export interface JsonLinesIndex {
+    path: string;
+    bytes: number;
+    sha256: string;
+    lines: number;
+}
+/** What a refusal calls one line of a file and several: `an item` and `items` for a live file. */
+export interface LineNoun {
+    one: string;
+    many: string;
+}
 /**
- * The items the indexed prefix of a live file holds, or why the bytes do not match the index:
+ * The JSON object on each line of a file run.json binds, or why the bytes do not match the index:
  * `bytes` must be exactly the indexed byte count, hash to the indexed sha256, and hold the indexed
- * number of lines, each a JSON object.
+ * number of lines, each a JSON object. A refusal names the file and counts, never what it holds.
  */
+export declare function boundJsonLines(bytes: Buffer, index: JsonLinesIndex, noun: LineNoun): {
+    lines: Record<string, unknown>[];
+} | {
+    refused: string;
+};
+/** The items the indexed prefix of a live file holds, or why the bytes do not match the index. */
 export declare function liveItemsFromBytes(bytes: Buffer, index: LiveItemsIndex): {
     items: ActorTraceItem[];
 } | {

package/dist/run/live-items.js

@@ -29,19 +29,24 @@ export function isLiveItemsIndex(value) {
         typeof value.sha256 === "string" &&
         /^[0-9a-f]{64}$/.test(value.sha256));
 }
+const ITEM = { one: "an item", many: "items" };
 /**
- * The items the indexed prefix of a live file holds, or why the bytes do not match the index:
+ * The JSON object on each line of a file run.json binds, or why the bytes do not match the index:
  * `bytes` must be exactly the indexed byte count, hash to the indexed sha256, and hold the indexed
- * number of lines, each a JSON object.
+ * number of lines, each a JSON object. A refusal names the file and counts, never what it holds.
  */
-export function liveItemsFromBytes(bytes, index) {
+export function boundJsonLines(bytes, index, noun) {
     if (bytes.length !== index.bytes)
         return {
             refused: `${index.path} holds ${bytes.length} bytes and run.json records ${index.bytes}`,
         };
     if (createHash("sha256").update(bytes).digest("hex") !== index.sha256)
         return { refused: `${index.path} does not match the sha256 run.json records for it` };
-    return itemLinesOf(bytes, index.items, index.path);
+    return objectLinesOf(bytes, index.lines, index.path, noun);
+}
+/** The items the indexed prefix of a live file holds, or why the bytes do not match the index. */
+export function liveItemsFromBytes(bytes, index) {
+    return asItems(boundJsonLines(bytes, { ...index, lines: index.items }, ITEM));
 }
 /**
  * The items past `after` in the indexed prefix of a live file, from the file's bytes between
@@ -59,10 +64,14 @@ export function liveItemsAfter(bytes, index, after) {
         };
     if (bytes[0] !== 0x0a)
         return { refused: `${index.path} has no line end before byte ${after.bytes}` };
-    return itemLinesOf(bytes.subarray(1), index.items - after.items, index.path);
+    return asItems(objectLinesOf(bytes.subarray(1), index.items - after.items, index.path, ITEM));
+}
+/** A live file's lines as trace items. */
+function asItems(read) {
+    return "refused" in read ? read : { items: read.lines };
 }
 /** The JSON object on each of `count` lines in `bytes`, which must be UTF-8 and end a line. */
-function itemLinesOf(bytes, count, file) {
+function objectLinesOf(bytes, count, file, noun) {
     let text;
     try {
         text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
@@ -74,21 +83,21 @@ function itemLinesOf(bytes, count, file) {
     if (lines.length > 0 && lines.pop() !== "")
         return { refused: `${file} does not end its indexed bytes at a line end` };
     if (lines.length !== count)
-        return { refused: `${file} holds ${lines.length} items and run.json records ${count}` };
-    const items = [];
+        return { refused: `${file} holds ${lines.length} ${noun.many} and run.json records ${count}` };
+    const objects = [];
     for (const line of lines) {
-        let item;
+        let value;
         try {
-            item = JSON.parse(line);
+            value = JSON.parse(line);
         }
         catch {
             return { refused: `${file} holds a line that is not JSON` };
         }
-        if (!isRecord(item))
-            return { refused: `${file} holds a line that is not an item` };
-        items.push(item);
+        if (!isRecord(value))
+            return { refused: `${file} holds a line that is not ${noun.one}` };
+        objects.push(value);
     }
-    return { items };
+    return { lines: objects };
 }
 /** The warning for a participant whose live items were written in full on two writes in a row. */
 function rewrittenEvent(stream, position) {

package/dist/run/pricing.d.ts

@@ -50,6 +50,12 @@ export interface DesktopResourceRate {
     usdPerGiBSecond: number;
     asOf: string;
     source: string;
+    /** The sizes the public sheet prices; a size outside them stays unpriced. Absent: any size. */
+    sheet?: {
+        cpuCounts: readonly number[];
+        minMemoryMiB: number;
+        maxMemoryMiB: number;
+    };
 }
 /**
  * The token-derived cost estimate for one actor trace. `estimatedCostUsd: null` = declared absent
@@ -104,6 +110,11 @@ export interface DesktopCostEstimate {
     usdPerSecond?: number;
 }
 export declare const MODEL_RATES: Record<string, ModelRate>;
+/**
+ * Modal's Sandbox rate, per vCPU: Modal prices a physical core, $0.00003942 a second, and counts
+ * it as two vCPU. Modal prices every size the same way.
+ */
+export declare const MODAL_SANDBOX_RESOURCE_RATE: DesktopResourceRate;
 /**
  * The refusal for a spend cap on a model this table cannot price. It names the priced models,
  * since an npm install cannot edit this file.

package/dist/run/pricing.js

@@ -91,6 +91,19 @@ const DESKTOP_RESOURCE_RATE = {
     asOf: "2026-09-05",
     // A source label rather than an executable URL; runtime URL redaction protects E2B streams.
     source: "e2b.dev/pricing",
+    // The public Hobby/Pro sheet stops at 8 CPU / 8 GiB; larger allocations may have negotiated
+    // prices, so their resource evidence is kept without extrapolating a standard rate to them.
+    sheet: { cpuCounts: [1, 2, 4, 6, 8], minMemoryMiB: 512, maxMemoryMiB: 8192 },
+};
+/**
+ * Modal's Sandbox rate, per vCPU: Modal prices a physical core, $0.00003942 a second, and counts
+ * it as two vCPU. Modal prices every size the same way.
+ */
+export const MODAL_SANDBOX_RESOURCE_RATE = {
+    usdPerCpuSecond: 0.00003942 / 2,
+    usdPerGiBSecond: 0.00000667,
+    asOf: "2026-10-19",
+    source: "modal.com/pricing",
 };
 // Planning assumption behind the public estimateDesktopCost helper: stock desktops observed on
 // 2026-09-05 had 8 vCPU / 8 GiB. This is the largest CPU/RAM combination on that public sheet, not
@@ -131,11 +144,11 @@ export function estimateAllocatedDesktopCost(minutes, resources, rate = DESKTOP_
             minutes: round6(minutes),
         };
     }
-    // The public Hobby/Pro sheet stops at 8 CPU / 8 GiB; larger allocations may have negotiated
-    // prices. Retain the resource evidence without extrapolating a standard rate to them.
-    if (![1, 2, 4, 6, 8].includes(resources.cpuCount) ||
-        resources.memoryMiB < 512 ||
-        resources.memoryMiB > 8192 ||
+    const { sheet } = rate;
+    if ((sheet !== undefined &&
+        (!sheet.cpuCounts.includes(resources.cpuCount) ||
+            resources.memoryMiB < sheet.minMemoryMiB ||
+            resources.memoryMiB > sheet.maxMemoryMiB)) ||
         !Number.isFinite(rate.usdPerCpuSecond) ||
         rate.usdPerCpuSecond < 0 ||
         !Number.isFinite(rate.usdPerGiBSecond) ||

package/dist/run/reclaim-outcomes.d.ts

@@ -1,5 +1,8 @@
 import { type E2BTagSearch } from "../substrates/e2b/sandbox.js";
 import type { E2BAccount } from "../substrates/e2b/connection.js";
+import { type SandboxProviderId } from "./sandbox-receipts.js";
+/** The account reclaim reaches each provider through; absent when it could not be set up. */
+export type ProviderAccounts = Partial<Record<SandboxProviderId, E2BAccount>>;
 import { type ContainedRefusal, type PreparedOutputRoot } from "./contained-output.js";
 export declare const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
 export declare const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
@@ -50,7 +53,7 @@ export interface Target {
  * kills leaves a record of each one not yet confirmed gone.
  */
 export declare function targetSet(options: {
-    e2b: E2BAccount | undefined;
+    accounts: ProviderAccounts;
     check: boolean;
     requestTimeoutMs: number;
     earlier: ReclaimOutcome[];

package/dist/run/reclaim-outcomes.js

@@ -4,6 +4,7 @@
 // receipt writer. src/run/reclaim.ts decides what to find; this module records what happened.
 import { REDACTED_SANDBOX_ID, redactText, sandboxIdDigest, toErrorMessage, } from "../evidence/redaction.js";
 import { destroyE2BSandbox, findE2BSandboxesByTags, inspectE2BSandbox, } from "../substrates/e2b/sandbox.js";
+import { isSandboxProviderId } from "./sandbox-receipts.js";
 import { readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "./contained-output.js";
 import { scrubSandboxIds } from "./sandbox-ids.js";
 import { isRecord } from "./type-guards.js";
@@ -15,7 +16,7 @@ export const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
  * kills leaves a record of each one not yet confirmed gone.
  */
 export function targetSet(options) {
-    const { e2b, check, requestTimeoutMs, earlier, persist } = options;
+    const { accounts, check, requestTimeoutMs, earlier, persist } = options;
     const targets = new Map();
     const work = [];
     const queued = [];
@@ -25,7 +26,7 @@ export function targetSet(options) {
         const seen = new Set(current.map((outcome) => outcome.sandboxIdDigest));
         return [...current, ...carried.filter((outcome) => !seen.has(outcome.sandboxIdDigest))];
     };
-    const act = (target) => actOn(e2b, target, { check, requestTimeoutMs }).then((settled) => {
+    const act = (target) => actOn(accounts, target, { check, requestTimeoutMs }).then((settled) => {
         target.outcome = settled;
         void persist.write(snapshot(), "unknown");
     });
@@ -95,17 +96,18 @@ export async function searchTagSets(e2b, tagSets, options) {
     };
 }
 /** Kill (or look up) one sandbox, and say what happened in reclaim's vocabulary. */
-async function actOn(e2b, target, options) {
+async function actOn(accounts, target, options) {
     const { outcome, provider, rawId } = target;
-    if (provider !== "e2b" || e2b === undefined)
+    const account = isSandboxProviderId(provider) ? accounts[provider] : undefined;
+    if (account === undefined)
         return {
             ...outcome,
             state: "unsupported-provider",
             detail: `provider ${JSON.stringify(provider)} is not supported by this humanish version; nothing was attempted, and that provider's own timeout is the backstop`,
         };
     const attempt = options.check
-        ? await inspectE2BSandbox(e2b, rawId, options)
-        : await destroyE2BSandbox(e2b, rawId, options);
+        ? await inspectE2BSandbox(account, rawId, options)
+        : await destroyE2BSandbox(account, rawId, options);
     const { detail: _previous, ...rest } = outcome;
     // A provider error that quotes the id is scrubbed; the raw id stays in sandbox-receipts.ndjson.
     return "detail" in attempt

package/dist/run/reclaim.d.ts

@@ -1,3 +1,4 @@
+import { type E2BAccount } from "../substrates/e2b/connection.js";
 import { type E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import { type StoppedSandboxCreates } from "./sandbox-creates.js";
 import { RECLAIM_RECEIPT_ARTIFACT, RECLAIM_RESULT_SCHEMA, type ReclaimOutcome, type ReclaimState, type ReclaimTagSearch } from "./reclaim-outcomes.js";
@@ -33,13 +34,15 @@ export interface ReclaimResult {
 export interface ReclaimHooks {
     /** Tests inject a fake @e2b/desktop module; default loads the real one. */
     loadModule?: () => Promise<E2BDesktopModule>;
+    /** Tests inject a fake Modal account; default reads the Modal credentials from `env`. */
+    loadModalAccount?: (env: Readonly<Record<string, string | undefined>>) => Promise<E2BAccount>;
     /**
      * The env whose E2B_API_KEY and E2B_DOMAIN every E2B call carries. Defaults to process.env, where
      * the CLI put the run's key before the run started.
      */
     env?: Readonly<Record<string, string | undefined>>;
     requestTimeoutMs?: number;
-    /** Ask E2B whether each sandbox still exists, and kill nothing. */
+    /** Ask the provider whether each sandbox still exists, and kill nothing. */
     check?: boolean;
     /** The signal handler's view of this run's creates: the ids they reported, and those still
      *  in flight, whose sandboxes are killed as their ids arrive. */