humanish 0.115.0 → 0.116.0

package/dist/study/warnings.js

@@ -1,6 +1,6 @@
 import { cli } from "../cli/invocation.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
-import { declaredParticipantIds } from "./plan-participants.js";
+import { computerUseParticipants, declaredParticipantIds, sharedWorldParticipants, } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
 import { participantList, participantInstruction, declaredParticipantCount, } from "./study-fields.js";
 // The computer-use and terminal routes consume mission/persona/model (they compose the agent prompt
@@ -269,12 +269,11 @@ export function inertFieldPaths(config) {
 /**
  * The warning for `execution.egressAllow` on a route that ignores it, or undefined. Only the
  * terminal route creates its sandbox with the list as an outbound allowlist; on any other route the
- * study author would trust a list that blocks nothing. `humanish study check` and every run print
- * it, and the run records it in its bundle.
+ * study author would trust a list that blocks nothing.
  * Removed in the first minor release on or after 2026-11-04: deprecated on 2026-10-05. That release refuses the field off the terminal
  * route.
  */
-export function egressAllowIgnoredWarning(config) {
+function egressAllowIgnoredWarning(config) {
     if (config.execution?.egressAllow === undefined || config.route === "terminal")
         return undefined;
     return `\`execution.egressAllow\` is ignored on route: ${config.route}. Only route: terminal creates its sandbox with that outbound allowlist, and this route's browser desktops can reach any site. Remove the field: the first minor release on or after 2026-11-04 refuses it on every route except terminal.`;
@@ -289,9 +288,6 @@ export function forwardDeclaredWarnings(config) {
         : [
             `These fields are set, but no route reads them yet, so they have no effect: ${inert.join(", ")}.`,
         ];
-    const egressIgnored = egressAllowIgnoredWarning(config);
-    if (egressIgnored !== undefined)
-        warnings.push(egressIgnored);
     // A declared cap below the participant count is legal but loud: the roster promises N live actors
     // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
     // waves is otherwise indistinguishable from the all-live run the author meant.
@@ -312,7 +308,20 @@ export function forwardDeclaredWarnings(config) {
             warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants. These get no inbox and are never told one exists: ${uncovered.join(", ")}. Add a recipient with an address for each one whose flow needs email.`);
         }
     }
-    return [...warnings, ...scriptedMissionWarnings(config)];
+    return [...warnings, ...recordedStudyWarnings(config)];
+}
+/**
+ * The warnings about a study's own fields that a run records in its bundle as `study.warning`
+ * events: `execution.egressAllow` off the terminal route, and participant text that reads like a
+ * script. parseStudy reports them too, after its other warnings, so `study check` and every run
+ * print them.
+ */
+export function recordedStudyWarnings(config) {
+    const egressIgnored = egressAllowIgnoredWarning(config);
+    return [
+        ...(egressIgnored === undefined ? [] : [egressIgnored]),
+        ...scriptedMissionWarnings(config),
+    ];
 }
 const UI_ACTION = /\b(?:click|tap|press|type\b[^.!?\n]*?\binto|select\b[^.!?\n]*?\bfrom)\b/gi;
 function normalizedUrl(value) {
@@ -343,7 +352,7 @@ function actionChain(text) {
             /\bthen\b/i.test(text.slice((actions[0]?.index ?? 0) + (actions[0]?.[0].length ?? 0)))));
 }
 /** Authored participant text is checked before runtime instructions or researcher criteria join it. */
-export function scriptedMissionWarnings(config) {
+function scriptedMissionWarnings(config) {
     if (config.route !== "computer-use" && config.route !== "shared-world")
         return [];
     const fields = [
@@ -374,20 +383,32 @@ export function scriptedMissionWarnings(config) {
         ];
     });
 }
-/** Backgrounds give participants a reason to act beyond the assigned task. */
-export function personaBackgroundWarnings(config, personas) {
-    if (config.route !== "computer-use" && config.route !== "shared-world")
-        return [];
-    const roster = participantList(config);
-    return declaredParticipantIds(config).flatMap((id, index) => {
-        const personaId = roster?.[index]?.persona ?? config.actor?.persona;
+/**
+ * A warning for each participant whose persona has no background, which gives a participant a
+ * reason to act beyond the assigned task. `participants` are the records the planner builds: a
+ * computer-use or shared-world plan's participants, or `plannedParticipants` before a plan exists.
+ */
+export function personaBackgroundWarnings(studyId, participants, personas) {
+    return participants.flatMap(({ id, personaId }) => {
         if (personaId && personas.get(personaId)?.background)
             return [];
         const reason = personaId
             ? `persona ${personaId} has no readable background`
             : "no persona is assigned";
         return [
-            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run ${cli(`study show ${config.id} --json`)} to see what the participant receives.`,
+            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run ${cli(`study show ${studyId} --json`)} to see what the participant receives.`,
         ];
     });
 }
+/**
+ * The participant records planStudy builds for a study's declared participants, for `study check`
+ * and `study show`, which run no plan. Only computer-use and shared-world studies have them; a run's
+ * `--count` is not applied.
+ */
+export function plannedParticipants(config) {
+    if (config.route === "computer-use")
+        return computerUseParticipants(config);
+    if (config.route === "shared-world")
+        return sharedWorldParticipants(config).participants;
+    return [];
+}

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

@@ -0,0 +1,12 @@
+import type { E2BConnection, E2BDesktopModule } from "./sdk.js";
+/** The connection an env names: E2B_API_KEY and E2B_DOMAIN, trimmed, each only when set. */
+export declare function e2bConnection(env: Readonly<Record<string, string | undefined>>): E2BConnection;
+/** The calls humanish makes on sandboxes that already exist. */
+export type E2BAccount = Pick<E2BDesktopModule["Sandbox"], "kill" | "getInfo" | "list">;
+/**
+ * The kill, getInfo and list of `module`, each carrying `connection`'s key and domain over the
+ * call's own options. `connection` may be a create's options, so the release of a sandbox reaches
+ * the account that created it. Each method is bound now: a hook that later replaces one on the
+ * shared module does not change this account. A method the installed SDK lacks stays absent.
+ */
+export declare function e2bAccount(module: E2BDesktopModule, connection: E2BConnection): E2BAccount;

package/dist/substrates/e2b/connection.js

@@ -0,0 +1,35 @@
+/** The connection an env names: E2B_API_KEY and E2B_DOMAIN, trimmed, each only when set. */
+export function e2bConnection(env) {
+    return named({ apiKey: env.E2B_API_KEY?.trim(), domain: env.E2B_DOMAIN?.trim() });
+}
+/**
+ * The kill, getInfo and list of `module`, each carrying `connection`'s key and domain over the
+ * call's own options. `connection` may be a create's options, so the release of a sandbox reaches
+ * the account that created it. Each method is bound now: a hook that later replaces one on the
+ * shared module does not change this account. A method the installed SDK lacks stays absent.
+ */
+export function e2bAccount(module, connection) {
+    const sdk = module.Sandbox;
+    const reached = named(connection);
+    const account = {};
+    if (typeof sdk.kill === "function") {
+        const kill = sdk.kill.bind(sdk);
+        account.kill = (sandboxId, options) => kill(sandboxId, { ...options, ...reached });
+    }
+    if (typeof sdk.getInfo === "function") {
+        const getInfo = sdk.getInfo.bind(sdk);
+        account.getInfo = (sandboxId, options) => getInfo(sandboxId, { ...options, ...reached });
+    }
+    if (typeof sdk.list === "function") {
+        const list = sdk.list.bind(sdk);
+        account.list = (options) => list({ ...options, ...reached });
+    }
+    return account;
+}
+/** Only the key and the domain, and only when non-empty: the SDK reads an empty one as unset. */
+function named(values) {
+    return {
+        ...(values.apiKey ? { apiKey: values.apiKey } : {}),
+        ...(values.domain ? { domain: values.domain } : {}),
+    };
+}

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

@@ -6,7 +6,7 @@ import type { CuaExecutor, CuaObservation } from "../../actors/computer-use/loop
  * executor awaits every call, which is correct for both sync and async returns.
  */
 export interface E2BDesktopLike {
-    /** Optional command surface used only for best-effort substrate fallbacks. */
+    /** The sandbox's command surface: keypresses, held modifiers and typed text run xdotool here. */
     commands?: {
         run(command: string, options?: {
             requestTimeoutMs?: number;
@@ -48,8 +48,6 @@ export interface E2BDesktopLike {
     scroll(direction?: "up" | "down", amount?: number): Promise<void> | void;
     /** Write text at the current cursor position (the SDK's typing method). */
     write(text: string): Promise<void> | void;
-    /** Press a key or chord (the SDK's key method); accepts the keys array. */
-    press(key: string | string[]): Promise<void> | void;
     /** Drag from one coordinate tuple to another. */
     drag(from: [number, number], to: [number, number]): Promise<void> | void;
     /** Wait for the given number of milliseconds. */

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

@@ -2,11 +2,11 @@ import { shellQuote } from "../shell.js";
 import { perceptualSignature } from "../../evidence/frame-signature.js";
 import { commandFailureInfo } from "../command-failure.js";
 import { ComputerUseExecutorError } from "../../actors/computer-use/executor-error.js";
-import { xdotoolHeldModifiers } from "../../guest/desktop-keys.js";
+import { xdotoolChord, xdotoolHeldModifiers } from "../../guest/desktop-keys.js";
 const DEFAULT_WAIT_MS = 500;
 const DEFAULT_SCROLL_AMOUNT_PER_TICK = 100;
 const TYPE_COMMAND_TIMEOUT_MS = 15_000;
-const HELD_KEYS_TIMEOUT_MS = 15_000;
+const KEY_COMMAND_TIMEOUT_MS = 15_000;
 const CURSOR_READ_TIMEOUT_MS = 500;
 /**
  * The stock image's xdotool waits ~15s on a synchronized move to its current position.
@@ -234,11 +234,15 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
                 }
                 return;
             }
-            case "keypress":
-                // The SDK press() accepts a string[] directly; pass the keys through so
-                // a chord (e.g. ["Control", "a"]) is pressed together, not in sequence.
-                await desktop.press(action.keys);
+            case "keypress": {
+                // One chord, so ctrl and a are pressed together. A name the table cannot map is
+                // refused here, before anything reaches the desktop.
+                const chord = xdotoolChord(action.keys);
+                if (!desktop.commands)
+                    throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
+                await runKeyCommand(desktop.commands, `key --clearmodifiers ${chord}`);
                 return;
+            }
             case "drag": {
                 // The SDK drag takes two endpoints, not an N-point path: drag from the
                 // first to the last point. 0 points is a safe no-op; 1 point has no
@@ -279,11 +283,10 @@ async function withHeldModifiers(desktop, chord, run) {
     const commands = desktop.commands;
     if (!commands)
         throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
-    const options = { requestTimeoutMs: HELD_KEYS_TIMEOUT_MS, timeoutMs: HELD_KEYS_TIMEOUT_MS };
     let failed = false;
     let failure;
     try {
-        await commands.run(`xdotool keydown ${chord}`, options);
+        await runKeyCommand(commands, `keydown ${chord}`);
         await run();
     }
     catch (error) {
@@ -292,7 +295,7 @@ async function withHeldModifiers(desktop, chord, run) {
     }
     // A keydown that failed may still have pressed some keys, so the release always runs.
     try {
-        await commands.run(`xdotool keyup ${chord}`, options);
+        await runKeyCommand(commands, `keyup ${chord}`);
     }
     catch {
         throw new ComputerUseExecutorError("execution_failed", "outcome_uncertain");
@@ -300,3 +303,33 @@ async function withHeldModifiers(desktop, chord, run) {
     if (failed)
         throw failure;
 }
+/**
+ * A key command xdotool did not complete. The loop reads `exitCode` and `stderr` the way it reads
+ * the SDK's CommandExitError, so it records the action as a failed desktop command and skips it.
+ */
+class ComputerUseKeyError extends Error {
+    exitCode;
+    stderr;
+    constructor(exitCode, stderr) {
+        super(`key command failed (exit ${exitCode})`);
+        this.name = "ComputerUseKeyError";
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}
+/**
+ * Run an xdotool key command: `key`, `keydown` or `keyup` with a chord from the key table, whose
+ * names are plain shell words, so the command and its stderr hold no participant text. The SDK
+ * throws its own error on a non-zero exit. xdotool skips a name it cannot resolve with a "No such
+ * key name" warning and still exits 0, so that warning fails the command too.
+ */
+async function runKeyCommand(commands, command) {
+    const result = await commands.run(`xdotool ${command}`, {
+        requestTimeoutMs: KEY_COMMAND_TIMEOUT_MS,
+        timeoutMs: KEY_COMMAND_TIMEOUT_MS,
+    });
+    const exitCode = result.exitCode ?? 0;
+    const stderr = result.stderr ?? "";
+    if (exitCode !== 0 || stderr.includes("No such key name"))
+        throw new ComputerUseKeyError(exitCode, stderr);
+}

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

@@ -1,9 +1,29 @@
 /**
- * E2B refuses a sandbox lifetime over one hour ("400: Timeout cannot be greater than 1 hours").
- * A derived deadline has to stay under it, and saying so at plan time beats discovering it from a
- * raw provider 400 after a plan has already printed.
+ * The longest lifetime humanish asks E2B for, in milliseconds, and whether it is the default or
+ * the setting; or why the setting cannot be read.
  */
-export declare const MAX_SANDBOX_MS: number;
+export type SandboxCeiling = {
+    readonly ok: true;
+    readonly ms: number;
+    readonly source: "default" | "setting";
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * The sandbox ceiling: HUMANISH_E2B_MAX_SANDBOX_MINUTES when set, else 60 minutes. E2B refuses a
+ * longer sandbox with a 400 ("Timeout cannot be greater than 1 hours" on Hobby), and neither its
+ * API nor its SDK says which plan a key is on, so the operator states it. A derived deadline has
+ * to stay under the ceiling, and saying so at plan time beats a provider 400 after the plan printed.
+ */
+export declare function sandboxCeiling(env: Readonly<Record<string, string | undefined>>): SandboxCeiling;
+/** The ceiling in use and where it came from, or why the setting cannot be read (doctor's row). */
+export declare function describeSandboxCeiling(ceiling: SandboxCeiling): string;
+/**
+ * The sentence a plan refusal adds when a `deadlineMs` sandbox deadline passes the ceiling: the
+ * setting value that would admit it, when an E2B plan allows that long.
+ */
+export declare function ceilingAdvice(deadlineMs: number): string;
 /** Server-side reclamation buffer past a participant's own wall-clock stop. */
 export declare const SANDBOX_TIMEOUT_BUFFER_MS: number;
 /** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */

package/dist/substrates/e2b/lifetime.js

@@ -2,12 +2,49 @@
 // deadline when they set a sandbox's server-side timeout. A dead host process can never orphan a
 // sandbox past that timeout, so every route derives it from these values.
 import { readPositiveInt } from "../../study/parse/values.js";
+/** The setting that tells humanish how long the operator's E2B plan lets a sandbox live. */
+const SANDBOX_CEILING_SETTING = "HUMANISH_E2B_MAX_SANDBOX_MINUTES";
+/** E2B's Hobby plan ends a sandbox after 1 hour, so a key on any plan can use this ceiling. */
+const DEFAULT_CEILING_MINUTES = 60;
+/** E2B's Pro plan allows 24 hours, the longest lifetime E2B documents. */
+const LARGEST_CEILING_MINUTES = 24 * 60;
 /**
- * E2B refuses a sandbox lifetime over one hour ("400: Timeout cannot be greater than 1 hours").
- * A derived deadline has to stay under it, and saying so at plan time beats discovering it from a
- * raw provider 400 after a plan has already printed.
+ * The sandbox ceiling: HUMANISH_E2B_MAX_SANDBOX_MINUTES when set, else 60 minutes. E2B refuses a
+ * longer sandbox with a 400 ("Timeout cannot be greater than 1 hours" on Hobby), and neither its
+ * API nor its SDK says which plan a key is on, so the operator states it. A derived deadline has
+ * to stay under the ceiling, and saying so at plan time beats a provider 400 after the plan printed.
  */
-export const MAX_SANDBOX_MS = 60 * 60_000;
+export function sandboxCeiling(env) {
+    const declared = env[SANDBOX_CEILING_SETTING]?.trim() ?? "";
+    if (declared === "")
+        return { ok: true, ms: DEFAULT_CEILING_MINUTES * 60_000, source: "default" };
+    const minutes = /^\d+$/.test(declared) ? Number.parseInt(declared, 10) : Number.NaN;
+    if (!(minutes >= 1 && minutes <= LARGEST_CEILING_MINUTES))
+        return {
+            ok: false,
+            message: `${SANDBOX_CEILING_SETTING} must be a whole number of minutes from 1 to ${LARGEST_CEILING_MINUTES} (got "${declared.slice(0, 40)}"). Set it to the sandbox lifetime your E2B plan allows: ${DEFAULT_CEILING_MINUTES} on Hobby, ${LARGEST_CEILING_MINUTES} on Pro. Unset, it is ${DEFAULT_CEILING_MINUTES}.`,
+        };
+    return { ok: true, ms: minutes * 60_000, source: "setting" };
+}
+/** The ceiling in use and where it came from, or why the setting cannot be read (doctor's row). */
+export function describeSandboxCeiling(ceiling) {
+    if (!ceiling.ok)
+        return ceiling.message;
+    const minutes = ceiling.ms / 60_000;
+    return ceiling.source === "setting"
+        ? `${minutes} minutes, from ${SANDBOX_CEILING_SETTING}. A study whose sandbox deadline is longer is refused before any sandbox is created, and E2B refuses a lifetime past the plan's own limit.`
+        : `${minutes} minutes, E2B's Hobby limit. On a plan with longer sandboxes (Pro allows ${LARGEST_CEILING_MINUTES} minutes), set ${SANDBOX_CEILING_SETTING} to that plan's limit.`;
+}
+/**
+ * The sentence a plan refusal adds when a `deadlineMs` sandbox deadline passes the ceiling: the
+ * setting value that would admit it, when an E2B plan allows that long.
+ */
+export function ceilingAdvice(deadlineMs) {
+    const needed = Math.ceil(deadlineMs / 60_000);
+    return needed <= LARGEST_CEILING_MINUTES
+        ? ` If your E2B plan allows longer sandboxes (Pro allows ${LARGEST_CEILING_MINUTES} minutes), set ${SANDBOX_CEILING_SETTING} to ${needed} or more.`
+        : ` No E2B plan humanish knows allows a sandbox past ${LARGEST_CEILING_MINUTES} minutes.`;
+}
 /** Server-side reclamation buffer past a participant's own wall-clock stop. */
 export const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
 /** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */

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

@@ -1,6 +1,7 @@
 import type { PreparedOutputRoot } from "../../run/contained-output.js";
 import { type DesktopReleaseResult, type OwnedDesktopAllocation } from "../desktop-session.js";
 import type { StudyConfig } from "../../study/types.js";
+import { type E2BAccount } from "./connection.js";
 import { type E2BDesktopCreateOptions, type E2BDesktopModule, type E2BDesktopSandbox, type E2BListedSandbox } from "./sdk.js";
 /** Where an allocation's receipt goes: the run's prepared root, under a public-safe participant
  *  label. The receipt line saves it as `laneId`. */
@@ -59,7 +60,7 @@ export type E2BSandboxDestroyOutcome = {
 };
 /** Kill one sandbox by its exact id, for reclaim, and map the shared release result onto
  *  reclaim's persisted outcome. */
-export declare function destroyE2BSandbox(module: E2BDesktopModule, sandboxId: string, options: {
+export declare function destroyE2BSandbox(account: E2BAccount, sandboxId: string, options: {
     requestTimeoutMs: number;
 }): Promise<E2BSandboxDestroyOutcome>;
 /** What `reclaim --check` learned about one sandbox by its exact id. */
@@ -73,7 +74,7 @@ export type E2BSandboxPresence = {
  * Ask E2B whether one sandbox still exists, by exact id. A SandboxNotFoundError, recognized by
  * type, means gone; any other error leaves the answer open.
  */
-export declare function inspectE2BSandbox(module: E2BDesktopModule, sandboxId: string, options: {
+export declare function inspectE2BSandbox(account: E2BAccount, sandboxId: string, options: {
     requestTimeoutMs: number;
 }): Promise<E2BSandboxPresence>;
 /** What E2B listed for a run's owner tags. `sandboxes` holds exact matches only. */
@@ -87,7 +88,7 @@ export interface E2BTagSearch {
  * checked against every tag again, so a server that ignored the filter still cannot hand back
  * another run's sandbox, and the search stops after a few pages instead of walking the account.
  */
-export declare function findE2BSandboxesByTags(module: E2BDesktopModule, tags: Record<string, string>, options: {
+export declare function findE2BSandboxesByTags(account: E2BAccount, tags: Record<string, string>, options: {
     requestTimeoutMs: number;
 }): Promise<E2BTagSearch>;
 /** Versioned public template built by runtime/browser-media/e2b-template.mjs. */

package/dist/substrates/e2b/sandbox.js

@@ -11,6 +11,7 @@ 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 { ownDesktopAllocation, } from "../desktop-session.js";
+import { e2bAccount } from "./connection.js";
 import { E2B_DEBUG_KILL_DETAIL, E2BDesktopStartupError, e2bDebugMode, isSandboxNotFoundError, observeDesktopAllocation, } from "./sdk.js";
 /** A desktop sandbox, on the stock `desktop` template or a named one. */
 export function acquireE2BDesktopSandbox(request) {
@@ -67,7 +68,8 @@ async function acquire(request, template) {
                 : module.Sandbox.create(template, options);
         }, { ...request.retry, canRetry: () => ticket?.stopping() !== true });
         ticket?.created(sandbox.sandboxId);
-        const allocation = ownE2BSandbox(module, sandbox.sandboxId, ticket);
+        // The release reaches the account the create used, whatever process.env names.
+        const allocation = ownE2BSandbox(e2bAccount(module, options), sandbox.sandboxId, ticket);
         try {
             // Best effort by contract: a failed write leaves the owner tags and the TTL as the
             // backstops and never fails the participant. One line per sandbox: a receipt the guard's
@@ -90,12 +92,6 @@ async function acquire(request, template) {
         ticket?.settled();
     }
 }
-/** The provider's kill method bound to its class, or undefined when the SDK has none. */
-function boundKill(module) {
-    return typeof module.Sandbox.kill === "function"
-        ? module.Sandbox.kill.bind(module.Sandbox)
-        : undefined;
-}
 /**
  * Kill one sandbox by exact id and read the answer in the release vocabulary both callers share.
  * The SDK resolves false for an id it no longer knows (a 404), and a SandboxNotFoundError,
@@ -129,9 +125,8 @@ async function killById(kill, sandboxId, options) {
         return { status: "unconfirmed", reason: "release_failed", error };
     }
 }
-function ownE2BSandbox(module, resourceId, ticket) {
-    // Bind the provider method now, before any hook can replace it on the shared module.
-    const kill = boundKill(module);
+function ownE2BSandbox(account, resourceId, ticket) {
+    const { kill } = account;
     return ownDesktopAllocation({
         resourceId,
         release: async () => {
@@ -189,8 +184,8 @@ export function releaseUnavailableDetail(detail) {
 }
 /** Kill one sandbox by its exact id, for reclaim, and map the shared release result onto
  *  reclaim's persisted outcome. */
-export async function destroyE2BSandbox(module, sandboxId, options) {
-    const released = await killById(boundKill(module), sandboxId, options);
+export async function destroyE2BSandbox(account, sandboxId, options) {
+    const released = await killById(account.kill, sandboxId, options);
     if (released.status === "released")
         return { state: released.reason === "terminated" ? "killed" : "already-gone" };
     switch (released.reason) {
@@ -209,14 +204,14 @@ export async function destroyE2BSandbox(module, sandboxId, options) {
  * Ask E2B whether one sandbox still exists, by exact id. A SandboxNotFoundError, recognized by
  * type, means gone; any other error leaves the answer open.
  */
-export async function inspectE2BSandbox(module, sandboxId, options) {
-    if (typeof module.Sandbox.getInfo !== "function")
+export async function inspectE2BSandbox(account, sandboxId, options) {
+    if (account.getInfo === undefined)
         return {
             state: "check-failed",
             detail: "the installed @e2b/desktop SDK has no Sandbox.getInfo",
         };
     try {
-        await module.Sandbox.getInfo(sandboxId, options);
+        await account.getInfo(sandboxId, options);
         return { state: "running" };
     }
     catch (error) {
@@ -234,8 +229,8 @@ const TAG_SEARCH_MAX_PAGES = 3;
  * checked against every tag again, so a server that ignored the filter still cannot hand back
  * another run's sandbox, and the search stops after a few pages instead of walking the account.
  */
-export async function findE2BSandboxesByTags(module, tags, options) {
-    if (typeof module.Sandbox.list !== "function")
+export async function findE2BSandboxesByTags(account, tags, options) {
+    if (account.list === undefined)
         return {
             status: "unavailable",
             sandboxes: [],
@@ -243,7 +238,7 @@ export async function findE2BSandboxesByTags(module, tags, options) {
         };
     const sandboxes = [];
     try {
-        const pages = module.Sandbox.list({
+        const pages = account.list({
             query: { metadata: tags },
             limit: TAG_SEARCH_PAGE_SIZE,
             requestTimeoutMs: options.requestTimeoutMs,

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

@@ -15,18 +15,14 @@ export interface E2BDesktopModule {
          * killed, false otherwise (the SDK's own doc comment). This boolean is the primary by-id
          * cleanup proof: a caller never needs to re-list to confirm reclamation.
          */
-        kill?(sandboxId: string, options?: {
-            requestTimeoutMs?: number;
-        }): Promise<boolean>;
+        kill?(sandboxId: string, options?: E2BRequestOptions): Promise<boolean>;
         /**
          * Fetch one sandbox by its exact id (never account-wide). Throws a SandboxNotFoundError-
          * shaped error (see isSandboxNotFoundError below) when the id no longer exists; that thrown
          * error is the by-id confirmation that a killed sandbox is gone. Optional: older SDKs may
          * lack it, so callers fall back to kill()'s own boolean rather than ever calling Sandbox.list.
          */
-        getInfo?(sandboxId: string, options?: {
-            requestTimeoutMs?: number;
-        }): Promise<E2BSandboxInfo>;
+        getInfo?(sandboxId: string, options?: E2BRequestOptions): Promise<E2BSandboxInfo>;
         /**
          * List sandboxes whose metadata matches every `query.metadata` pair, filtered server-side.
          * Reclaim calls it only with a run's owner tags (sandboxOwnerTags in src/run/sandbox-creates.ts)
@@ -36,12 +32,23 @@ export interface E2BDesktopModule {
         list?(options?: E2BSandboxListOptions): E2BSandboxPaginator;
     };
 }
-interface E2BSandboxListOptions {
+/**
+ * Which E2B account a call reaches. The SDK reads E2B_API_KEY and E2B_DOMAIN from process.env for
+ * a call that names neither, and an empty value counts as none.
+ */
+export interface E2BConnection {
+    apiKey?: string;
+    domain?: string;
+}
+/** The options of a call on a sandbox that exists: its account, and how long the request may take. */
+interface E2BRequestOptions extends E2BConnection {
+    requestTimeoutMs?: number;
+}
+interface E2BSandboxListOptions extends E2BRequestOptions {
     query?: {
         metadata?: Record<string, string>;
     };
     limit?: number;
-    requestTimeoutMs?: number;
 }
 interface E2BSandboxPaginator {
     readonly hasNext: boolean;
@@ -78,7 +85,11 @@ export interface E2BNetworkOptions {
         };
     }[]>;
 }
-export interface E2BDesktopCreateOptions {
+/**
+ * A create names its account. e2bAccount (connection.ts) gives every later call on the sandbox the
+ * same one.
+ */
+export interface E2BDesktopCreateOptions extends E2BConnection {
     apiKey: string;
     dpi?: number;
     envs?: Record<string, string>;

package/dist/substrates/local/capacity.d.ts

@@ -53,8 +53,23 @@ export declare function localCapacity(host: LocalCapacity["host"], size: Machine
 }): LocalCapacity;
 /** This machine's memory and CPUs, or the size a test passes in. */
 export declare function machineSize(machine?: MachineSize): MachineSize;
-/** A new VM's size: room for four desktops, capped at half the Mac's memory and CPUs. */
-export declare function defaultVmSize(mac: MachineSize): VmSize;
+/** The humanish Lima VM as `limactl list` shows it: whether it exists, and its size when listed. */
+interface LimaVmListing {
+    readonly exists: boolean;
+    readonly size?: MachineSize;
+}
+/**
+ * The humanish Lima VM's memory and CPUs: the size Lima lists for it, or for a VM that does not
+ * exist yet, the size setup creates (room for four desktops, capped at half the Mac's memory and
+ * CPUs). Undefined for an existing VM that lists no size: Lima omits the memory it cannot parse,
+ * and a default in its place would be a guess.
+ */
+export declare function limaVmSize(vm: LimaVmListing, mac: MachineSize): VmSize | undefined;
+/**
+ * Desktops the humanish Lima VM holds, or will hold once setup creates it. Undefined when its size
+ * is unknown.
+ */
+export declare function limaCapacity(vm: LimaVmListing, mac: MachineSize): LocalCapacity | undefined;
 /**
  * Why a VM size the user asked for cannot work, or undefined: it must hold at least one desktop
  * and fit within the Mac.
@@ -73,3 +88,4 @@ export declare function capacityShortfall(capacity: LocalCapacity, needed: numbe
 } | undefined;
 /** What a participant whose desktop Docker killed for memory is told, with what to change. */
 export declare function outOfMemoryMessage(host: LocalCapacity["host"]): string;
+export {};

package/dist/substrates/local/capacity.js

@@ -50,14 +50,33 @@ function vmSizeFor(desktops) {
 export function machineSize(machine) {
     return machine ?? { memoryBytes: totalmem(), cpus: availableParallelism() };
 }
-/** A new VM's size: room for four desktops, capped at half the Mac's memory and CPUs. */
-export function defaultVmSize(mac) {
+/**
+ * The humanish Lima VM's memory and CPUs: the size Lima lists for it, or for a VM that does not
+ * exist yet, the size setup creates (room for four desktops, capped at half the Mac's memory and
+ * CPUs). Undefined for an existing VM that lists no size: Lima omits the memory it cannot parse,
+ * and a default in its place would be a guess.
+ */
+export function limaVmSize(vm, mac) {
+    if (vm.size !== undefined)
+        return { memoryGiB: vm.size.memoryBytes / GiB, cpus: vm.size.cpus };
+    if (vm.exists)
+        return undefined;
     const wanted = vmSizeFor(DEFAULT_VM_DESKTOPS);
     return {
         memoryGiB: Math.min(wanted.memoryGiB, Math.floor(mac.memoryBytes / GiB / 2)),
         cpus: Math.min(wanted.cpus, Math.floor(mac.cpus / 2)),
     };
 }
+/**
+ * Desktops the humanish Lima VM holds, or will hold once setup creates it. Undefined when its size
+ * is unknown.
+ */
+export function limaCapacity(vm, mac) {
+    const size = limaVmSize(vm, mac);
+    if (size === undefined)
+        return undefined;
+    return localCapacity("lima-vm", { memoryBytes: size.memoryGiB * GiB, cpus: size.cpus }, { planned: !vm.exists, machine: mac });
+}
 /**
  * Why a VM size the user asked for cannot work, or undefined: it must hold at least one desktop
  * and fit within the Mac.