humanish 0.105.0 → 0.106.0

package/dist/substrates/e2b/sandbox.js

@@ -0,0 +1,202 @@
+// E2B sandbox acquisition and release. Every route that allocates an E2B sandbox calls this module,
+// so each allocation runs the same steps in the same order: create, one retry on a transient
+// provider error, capture of the exact id and kill authority, and a provider-qualified receipt in
+// the run directory before the caller gets the handle. The desktop startup guard
+// (guardDesktopSandboxCreate) is installed by loadE2BDesktopModule, so a create whose desktop
+// startup fails has already reclaimed its handle when the error reaches the retry here.
+import { redactText, toErrorMessage } from "../../evidence/redaction.js";
+import { appendSandboxReceipt } from "../../run/sandbox-receipts.js";
+import { ownDesktopAllocation, } from "../desktop-session.js";
+import { E2BDesktopStartupError, isSandboxNotFoundError, } from "./sdk.js";
+/** A desktop sandbox, on the stock `desktop` template or a named one. */
+export function acquireE2BDesktopSandbox(request) {
+    return acquire(request, request.template);
+}
+/** The terminal route's shell sandbox. It always runs on the stock template. */
+export function acquireE2BShellSandbox(request) {
+    return acquire(request, undefined);
+}
+async function acquire(request, template) {
+    const { module, options } = request;
+    // Without a template the SDK's one-argument create chooses its stock desktop template.
+    const sandbox = await withOneRetryOnTransientE2BError(() => template === undefined
+        ? module.Sandbox.create(options)
+        : module.Sandbox.create(template, options), request.retry);
+    const allocation = ownE2BSandbox(module, sandbox.sandboxId);
+    try {
+        if (request.receipt !== null) {
+            const { root, participantId, now = Date.now } = request.receipt;
+            // Best effort by contract: a failed write leaves the TTL as the only backstop and never
+            // fails the lane.
+            await appendSandboxReceipt(root, {
+                at: new Date(now()).toISOString(),
+                laneId: participantId,
+                provider: "e2b",
+                sandboxId: allocation.resourceId,
+                ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            });
+        }
+    }
+    catch (error) {
+        // The caller never receives this sandbox, so release it here. A throwing or invalid injected
+        // clock is the known case.
+        await allocation.close();
+        throw error;
+    }
+    return { sandbox, allocation };
+}
+/** 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,
+ * recognized by type, means the same. Every other throw is unconfirmed, whatever its message
+ * says: the SDK answers a 404 with false before it throws, so "not found" or "404" in a thrown
+ * message comes from some other failure, such as a trace id. Never list the account.
+ */
+async function killById(kill, sandboxId, options) {
+    if (kill === undefined)
+        return { status: "unconfirmed", reason: "release_unavailable" };
+    try {
+        const result = await kill(sandboxId, options);
+        if (result === true)
+            return { status: "released", reason: "terminated" };
+        if (result === false)
+            return { status: "released", reason: "already_gone" };
+        return { status: "unconfirmed", reason: "invalid_result" };
+    }
+    catch (error) {
+        if (isSandboxNotFoundError(error))
+            return { status: "released", reason: "already_gone" };
+        return { status: "unconfirmed", reason: "release_failed", error };
+    }
+}
+function ownE2BSandbox(module, resourceId) {
+    // Bind the provider method now, before any hook can replace it on the shared module.
+    const kill = boundKill(module);
+    return ownDesktopAllocation({
+        resourceId,
+        release: () => killById(kill, resourceId, { requestTimeoutMs: 60_000 }),
+    });
+}
+/**
+ * Read a release result the same way on every route. `label` names the sandbox in the warning
+ * ("Sandbox", "Subject sandbox"). `costSpan` adds that desktop cost uses the observed span when
+ * the sandbox was already gone, for routes that price its minutes. A retained sandbox is the
+ * caller's to describe.
+ */
+export function readE2BRelease(result, options) {
+    const { label, scrub } = options;
+    if (result.status === "retained")
+        return { released: false };
+    if (result.status === "released") {
+        if (result.reason === "terminated")
+            return { released: true };
+        return {
+            released: true,
+            warning: `${label} was already absent when cleanup ran; its exact termination time is unknown.${options.costSpan ? " Desktop cost uses the observed acquisition-to-cleanup span." : ""}`,
+        };
+    }
+    switch (result.reason) {
+        case "release_unavailable":
+            return {
+                released: false,
+                warning: `Installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the ${label.toLowerCase()}.`,
+            };
+        case "release_failed":
+            return {
+                released: false,
+                warning: `${label} teardown failed (server-side kill-on-timeout will reclaim it): ${redactText(scrub(toErrorMessage(result.error)))}`,
+            };
+        case "invalid_result":
+            return {
+                released: false,
+                warning: `${label} teardown returned an unexpected result; release is unconfirmed and server-side kill-on-timeout remains the backstop.`,
+            };
+    }
+}
+/**
+ * Kill one sandbox by its exact recorded id, for reclaim, and map the shared release result onto
+ * reclaim's persisted outcome. It never lists the account.
+ */
+export async function destroyE2BSandbox(module, sandboxId, options) {
+    const released = await killById(boundKill(module), sandboxId, options);
+    if (released.status === "released")
+        return { state: released.reason === "terminated" ? "killed" : "already-gone" };
+    switch (released.reason) {
+        case "release_unavailable":
+            return {
+                state: "kill-failed",
+                detail: "installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the sandbox",
+            };
+        case "invalid_result":
+            return {
+                state: "kill-failed",
+                detail: "Sandbox.kill returned neither true nor false, so the kill is unconfirmed",
+            };
+        case "release_failed":
+            return { state: "kill-failed", detail: redactText(toErrorMessage(released.error)) };
+    }
+}
+/** Versioned public template built by runtime/browser-media/e2b-template.mjs. */
+export const E2B_SPEECH_TEMPLATE = "7409n13kr83f7g7abx5g";
+/** The desktop template a lab asks for; undefined selects the SDK default. */
+export function e2bDesktopTemplate(config) {
+    if (config.execution?.target === "local")
+        return undefined;
+    return (config.execution?.desktop?.template ??
+        (config.execution?.desktop?.media?.microphone?.source === "speech"
+            ? E2B_SPEECH_TEMPLATE
+            : undefined));
+}
+/** Wall-clock pause before the single retry; envd routing settles within a few seconds. */
+export const TRANSIENT_RETRY_DELAY_MS = 3_000;
+/**
+ * The provider errors worth one retry, by the message the SDK throws. Each is a gap that clears
+ * within seconds of sandbox creation:
+ *
+ * - `12: [unimplemented] HTTP 404` and `[unavailable]`: the sandbox exists but its envd is not
+ *   routable yet, so the first request (the desktop SDK's Xvfb start) hits the proxy instead.
+ * - `Cannot read properties of undefined (reading 'envdVersion')` / `Response data is missing`:
+ *   the create API answered without a body.
+ * - `Expected to receive information about written file`: a file write the envd accepted without
+ *   describing, the same routing gap seen from the upload side.
+ * - transport resets (`fetch failed`, `ECONNRESET`, `socket hang up`, 502/503/504).
+ *
+ * NOT retried: timeouts (the budget is spent), auth (401/403), quota and rate limits (429: a burst
+ * that hit the limit should be spaced, not repeated), and anything that names the request as wrong.
+ */
+export function isTransientE2BError(error) {
+    if (error instanceof E2BDesktopStartupError && error.cleanup === "unconfirmed")
+        return false;
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error ?? "");
+    if (/timeout|timed out|deadline/i.test(message))
+        return false;
+    if (/\b(401|403|429)\b|unauthorized|forbidden|rate limit|quota/i.test(message))
+        return false;
+    return /\[unimplemented\]|\[unavailable\]|HTTP 404|HTTP 50[234]|\b50[234]\b|reading 'envdVersion'|Response data is missing|Expected to receive information about written file|fetch failed|ECONNRESET|ECONNREFUSED|socket hang up|UND_ERR/i.test(message);
+}
+/**
+ * Run `attempt`; on a transient provider error, say so through `onRetry`, wait, and run it once
+ * more. A second failure, or a non-transient first one, propagates as is. The first attempt may
+ * have allocated a sandbox this process never learned the id of (the SDK throws after the API
+ * call); the provider's own `timeoutMs` on that sandbox is what reclaims it, which the caller's
+ * warning should say.
+ */
+export async function withOneRetryOnTransientE2BError(attempt, hooks) {
+    try {
+        return await attempt();
+    }
+    catch (error) {
+        if (!isTransientE2BError(error))
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        hooks?.onRetry?.(reason);
+        await (hooks?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(TRANSIENT_RETRY_DELAY_MS);
+        return attempt();
+    }
+}

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

@@ -0,0 +1,194 @@
+export interface E2BDesktopModule {
+    Sandbox: {
+        /** The stock `desktop` template (no custom image). */
+        create(options: E2BDesktopCreateOptions): Promise<E2BDesktopSandbox>;
+        /**
+         * Launch on a CUSTOM E2B desktop template (image) by NAME or ID — the SDK's
+         * `Sandbox.create(template, opts)` overload. Lets a lab run on an adopter-maintained image
+         * with extra runtimes baked in (e.g. node/bun/a local Postgres the stock `desktop` template
+         * lacks), instead of the stock template. The base @e2b/desktop SDK implements this; the
+         * wrapper just exposes it. Threaded from `execution.desktop.template`.
+         */
+        create(template: string, options: E2BDesktopCreateOptions): Promise<E2BDesktopSandbox>;
+        /**
+         * Kill the sandbox specified by exact id. Returns true iff THAT sandbox was found and
+         * 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>;
+        /**
+         * 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>;
+    };
+}
+interface E2BSandboxInfo {
+    id?: string;
+    metadata?: Record<string, string>;
+    sandboxID?: string;
+    sandboxId?: string;
+    state?: string;
+}
+/** Sandbox egress policy. Domain filtering works for HTTP on :80 (Host header) and TLS on :443
+ *  (SNI); other ports need IPs. Passed straight through to the E2B SDK's `network` option. */
+export interface E2BNetworkOptions {
+    /** Hosts (or CIDRs) the sandbox may reach. Wildcards like `*.example.com` cover subdomains at
+     *  any depth; the apex is separate and needs its own entry. */
+    allowOut?: string[];
+    /** Denied traffic. `["0.0.0.0/0"]` with a populated allowOut is the deny-all-but shape. */
+    denyOut?: string[];
+    /** Static per-host HTTPS header transforms (E2B network rules). Header values override the
+     *  outbound request's values. These may contain secrets: never persist or log this object.
+     *  This is a structural subset of the installed SDK's SandboxNetworkRules contract. */
+    rules?: Record<string, {
+        transform?: {
+            headers?: Record<string, string>;
+        };
+    }[]>;
+}
+export interface E2BDesktopCreateOptions {
+    apiKey: string;
+    dpi?: number;
+    envs?: Record<string, string>;
+    /** Routing and optional header transforms; absent allowOut/denyOut retains unrestricted egress. */
+    network?: E2BNetworkOptions;
+    lifecycle?: {
+        onTimeout: "kill" | "pause";
+    };
+    metadata?: Record<string, string>;
+    requestTimeoutMs?: number;
+    resolution?: [number, number];
+    timeoutMs?: number;
+}
+export interface E2BCommandRunOptions {
+    background?: boolean;
+    stdin?: boolean;
+    cwd?: string;
+    envs?: Record<string, string>;
+    onStderr?: (data: string) => void | Promise<void>;
+    onStdout?: (data: string) => void | Promise<void>;
+    requestTimeoutMs?: number;
+    timeoutMs?: number;
+}
+export interface E2BCommandResult {
+    /** Present on the installed SDK's background CommandHandle. */
+    pid?: number;
+    error?: string;
+    exitCode?: number;
+    stderr?: string;
+    stdout?: string;
+    /** Streaming command handle, returned only when background is true. */
+    sendStdin?(data: string | Uint8Array, options?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
+    closeStdin?(options?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
+    kill?(): Promise<boolean>;
+    wait?(): Promise<E2BCommandResult>;
+}
+export interface E2BDesktopSandbox {
+    sandboxId: string;
+    /** Read the owned allocation's actual resources; available on the current E2B SDK. */
+    getInfo?(options?: {
+        requestTimeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        cpuCount?: number;
+        memoryMB?: number;
+    }>;
+    commands: {
+        run(command: string, options?: E2BCommandRunOptions): Promise<E2BCommandResult>;
+    };
+    files: {
+        read?(path: string, options: {
+            format: "stream";
+            requestTimeoutMs?: number;
+            streamIdleTimeoutMs?: number;
+            signal?: AbortSignal;
+        }): Promise<import("node:stream/web").ReadableStream<Uint8Array>>;
+        write(path: string, data: string | ArrayBuffer, options?: {
+            requestTimeoutMs?: number;
+            useOctetStream?: boolean;
+        }): Promise<unknown>;
+    };
+    launch(application: string, uri?: string): Promise<void>;
+    /** Open a file or URL with the desktop's default application (present on @e2b/desktop >= 1.x). */
+    open?(fileOrUrl: string): Promise<void>;
+    /**
+     * Map an in-sandbox port to a reachable host URL — `https://<port>-<sandboxId>.e2b.app`,
+     * TOKENLESS (no authKey, unlike `stream.getUrl`). The base `e2b` SDK (v2.27.0) implements this;
+     * the wrapper just exposes it. Used by the CONCURRENT shared-world topology (#164 phase 2) to
+     * expose the ONE subject service plane to N actor sandboxes. Optional: older SDKs may lack it, so
+     * the concurrent backend fails closed when it is absent rather than calling a missing method.
+     */
+    getHost?(port: number): string;
+    screenshot(format?: "bytes"): Promise<Uint8Array>;
+    wait(ms: number): Promise<void>;
+    leftClick(x?: number, y?: number): Promise<void>;
+    rightClick(x?: number, y?: number): Promise<void>;
+    middleClick(x?: number, y?: number): Promise<void>;
+    doubleClick(x?: number, y?: number): Promise<void>;
+    moveMouse(x: number, y: number): Promise<void>;
+    getCursorPosition?(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    scroll(direction?: "up" | "down", amount?: number): Promise<void>;
+    write(text: string): Promise<void>;
+    press(key: string | string[]): Promise<void>;
+    drag(from: [number, number], to: [number, number]): Promise<void>;
+    stream: {
+        getAuthKey(): string;
+        getUrl(options?: {
+            authKey?: string;
+            autoConnect?: boolean;
+            resize?: "off" | "scale" | "remote";
+            viewOnly?: boolean;
+        }): string;
+        start(options?: {
+            requireAuth?: boolean;
+            windowId?: string;
+        }): Promise<void>;
+    };
+}
+export declare function loadE2BDesktopModule(): Promise<E2BDesktopModule>;
+export declare const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10000;
+type DesktopCreateCleanup = "killed" | "already_gone" | "unconfirmed";
+/** Startup failed after this call acquired a handle. No credentials/options are included here. */
+export declare class E2BDesktopStartupError extends Error {
+    readonly cleanup: DesktopCreateCleanup;
+    constructor(error: unknown, cleanup: DesktopCreateCleanup);
+}
+/**
+ * Preserve ownership before the desktop SDK starts Xvfb/XFCE (#581). Its public generic create
+ * constructs `new this(...)` through the base SDK, then awaits desktop startup. Newer SDKs
+ * attempt their own kill before rejecting create; older SDKs leave cleanup to the caller.
+ * Both paths share one bounded cleanup result so an internal kill cannot delay our deadline
+ * or cause a second cleanup request. Successful creation restores normal kill semantics.
+ * Each call gets a separate subclass/closure so concurrent attempts cannot exchange handles.
+ *
+ * This deliberately depends on SDK construction order, not a copied private `_start` method.
+ * The real installed SDK's debug-mode conformance test must pass on dependency updates: the
+ * constructor must run before bootstrap and public create must preserve its subclass type.
+ * Failures before a constructor returns still have no acquired handle and remain unproven.
+ */
+export declare function guardDesktopSandboxCreate(module: E2BDesktopModule): E2BDesktopModule;
+/**
+ * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, WITHOUT importing
+ * its class (this module stays optional-peer / lazily-loaded, same as everything else here).
+ * The real SDK sets `this.name = "SandboxNotFoundError"` on the class (it extends the
+ * deprecated NotFoundError), so checking `.name` is the stable, import-free detection contract.
+ * The constructor-name fallback covers a bundler/transpile shape where `.name` was not copied
+ * onto the instance. A thrown SandboxNotFoundError from Sandbox.getInfo(id) is the by-id proof
+ * that the exact sandbox humanish created is gone (confirmed reclaimed), never a re-list.
+ */
+export declare function isSandboxNotFoundError(error: unknown): boolean;
+export {};

package/dist/substrates/e2b/sdk.js

@@ -0,0 +1,168 @@
+// Shared E2B desktop substrate: the optional-peer loader + the structural interfaces for the
+// real @e2b/desktop Sandbox. Every desktop route launches through this one seam; the peer dep is
+// optional and lazily loaded, so it stays out of the published tarball and CI.
+//
+// E2BDesktopSandbox is the command, file, stream, launch and input subset the lanes use; `open` is
+// optional because older SDKs lack it (the computer-use lane then falls back to launch). It
+// satisfies the executor's E2BDesktopLike port (src/substrates/e2b/desktop-executor.ts) as is.
+import { sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { protectDesktopScreenshotCleanup } from "./desktop-screenshot-cleanup.js";
+export async function loadE2BDesktopModule() {
+    try {
+        return guardDesktopSandboxCreate((await import("@e2b/desktop")));
+    }
+    catch (error) {
+        if (isMissingE2BDesktopDependency(error)) {
+            throw new Error(runningFromProject()
+                ? "Live E2B desktop launch requires the optional peer @e2b/desktop. Install it beside humanish " +
+                    "in this project: `npm i -D @e2b/desktop`."
+                : "Live E2B desktop launch requires the optional peer @e2b/desktop, and humanish is running from an " +
+                    "npx cache rather than from this project — so installing the peer here cannot help, because Node " +
+                    "resolves it relative to humanish itself. Install BOTH into the project and run it from there: " +
+                    "`npm i -D humanish @e2b/desktop` then `npx humanish run <lab>`.");
+        }
+        throw error;
+    }
+}
+export const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10_000;
+/** Startup failed after this call acquired a handle. No credentials/options are included here. */
+export class E2BDesktopStartupError extends Error {
+    cleanup;
+    constructor(error, cleanup) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const cleanupNote = cleanup === "killed"
+            ? "the allocated sandbox was reclaimed"
+            : cleanup === "already_gone"
+                ? "the allocated sandbox was already gone"
+                : "cleanup of the allocated sandbox was not confirmed; no retry is allowed and its provider timeout remains the backstop";
+        super(`Desktop startup failed after allocation; ${cleanupNote}. ${detail}`, { cause: error });
+        this.cleanup = cleanup;
+        this.name = "E2BDesktopStartupError";
+    }
+}
+/**
+ * Preserve ownership before the desktop SDK starts Xvfb/XFCE (#581). Its public generic create
+ * constructs `new this(...)` through the base SDK, then awaits desktop startup. Newer SDKs
+ * attempt their own kill before rejecting create; older SDKs leave cleanup to the caller.
+ * Both paths share one bounded cleanup result so an internal kill cannot delay our deadline
+ * or cause a second cleanup request. Successful creation restores normal kill semantics.
+ * Each call gets a separate subclass/closure so concurrent attempts cannot exchange handles.
+ *
+ * This deliberately depends on SDK construction order, not a copied private `_start` method.
+ * The real installed SDK's debug-mode conformance test must pass on dependency updates: the
+ * constructor must run before bootstrap and public create must preserve its subclass type.
+ * Failures before a constructor returns still have no acquired handle and remain unproven.
+ */
+export function guardDesktopSandboxCreate(module) {
+    const SdkSandbox = module.Sandbox;
+    class GuardedSandbox extends SdkSandbox {
+        static async create(templateOrOptions, options) {
+            const createOptions = typeof templateOrOptions === "string" ? options : templateOrOptions;
+            const requestedTimeout = createOptions?.requestTimeoutMs;
+            const timeoutMs = requestedTimeout !== undefined && Number.isFinite(requestedTimeout) && requestedTimeout > 0
+                ? Math.min(requestedTimeout, DESKTOP_CREATE_CLEANUP_TIMEOUT_MS)
+                : DESKTOP_CREATE_CLEANUP_TIMEOUT_MS;
+            let cleanupOwned;
+            let restoreKill;
+            // oxlint-disable-next-line typescript/no-this-alias -- the attempt subclasses whichever SDK class was called
+            const CallingSandbox = this;
+            class AttemptSandbox extends CallingSandbox {
+                constructor(...args) {
+                    super(...args);
+                    const kill = this.kill.bind(this);
+                    const ownKill = Object.getOwnPropertyDescriptor(this, "kill");
+                    let receipt;
+                    const reclaim = () => (receipt ??= reclaimFailedDesktopCreate(kill, timeoutMs));
+                    cleanupOwned = reclaim;
+                    // SDK 2.4 calls this method before create rejects. Keep its boolean contract while
+                    // recording unconfirmed cleanup independently of the SDK's catch-and-discard path.
+                    this.kill = async () => {
+                        const cleanup = await reclaim();
+                        if (cleanup === "unconfirmed")
+                            throw new Error("Desktop startup cleanup was not confirmed");
+                        return cleanup === "killed";
+                    };
+                    restoreKill = () => {
+                        if (ownKill)
+                            Object.defineProperty(this, "kill", ownKill);
+                        else
+                            Reflect.deleteProperty(this, "kill");
+                    };
+                }
+            }
+            try {
+                const args = typeof templateOrOptions === "string"
+                    ? [templateOrOptions, options]
+                    : [templateOrOptions];
+                const desktop = (await Reflect.apply(SdkSandbox.create, AttemptSandbox, args));
+                restoreKill?.();
+                // The loader also serves direct Sandbox.create callers, such as the terminal route.
+                return protectDesktopScreenshotCleanup(desktop);
+            }
+            catch (error) {
+                if (cleanupOwned === undefined)
+                    throw error;
+                const cleanup = await cleanupOwned();
+                throw new E2BDesktopStartupError(error, cleanup);
+            }
+        }
+    }
+    return { ...module, Sandbox: GuardedSandbox };
+}
+async function reclaimFailedDesktopCreate(kill, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    try {
+        const result = await Promise.race([
+            kill({ requestTimeoutMs: timeoutMs, signal: controller.signal }),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error("desktop create cleanup deadline reached"));
+                }, timeoutMs);
+            }),
+        ]);
+        // The installed SDK documents false as an exact-id 404: already absent is also reclaimed.
+        return result === true ? "killed" : result === false ? "already_gone" : "unconfirmed";
+    }
+    catch {
+        // Do not serialize cleanup options, connection state, or provider errors that may echo auth.
+        return "unconfirmed";
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Is humanish running from this project's node_modules, or from an npx cache?
+ *
+ * It decides which advice is TRUE. `npx humanish@latest` resolves its optional peer relative to
+ * ITSELF, so "install @e2b/desktop in this project" is advice that cannot work there — and that
+ * message cost two cold verification runs before the difference was noticed. A one-shot npx
+ * invocation cannot do a live desktop run at all; humanish has to be installed alongside the peer.
+ */
+function runningFromProject() {
+    const here = fileURLToPath(import.meta.url);
+    return here.startsWith(`${process.cwd()}${sep}node_modules${sep}`);
+}
+function isMissingE2BDesktopDependency(error) {
+    const value = error;
+    return value.code === "ERR_MODULE_NOT_FOUND" && value.message?.includes("@e2b/desktop") === true;
+}
+/**
+ * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, WITHOUT importing
+ * its class (this module stays optional-peer / lazily-loaded, same as everything else here).
+ * The real SDK sets `this.name = "SandboxNotFoundError"` on the class (it extends the
+ * deprecated NotFoundError), so checking `.name` is the stable, import-free detection contract.
+ * The constructor-name fallback covers a bundler/transpile shape where `.name` was not copied
+ * onto the instance. A thrown SandboxNotFoundError from Sandbox.getInfo(id) is the by-id proof
+ * that the exact sandbox humanish created is gone (confirmed reclaimed), never a re-list.
+ */
+export function isSandboxNotFoundError(error) {
+    if (error === null || typeof error !== "object")
+        return false;
+    const value = error;
+    return (value.name === "SandboxNotFoundError" || value.constructor?.name === "SandboxNotFoundError");
+}

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

@@ -0,0 +1,10 @@
+import type { Shell } from "../shell.js";
+import { type E2BDesktopSandbox } from "./sdk.js";
+/** The part of an E2B sandbox handle a Shell needs. */
+export type E2BShellHandle = Pick<E2BDesktopSandbox, "commands" | "files">;
+/**
+ * A Shell over an E2B sandbox. The SDK throws CommandExitError on a non-zero exit; this returns
+ * it as a result. Methods are read from the handle on every call, so a handle whose methods are
+ * replaced later is still the one used.
+ */
+export declare function e2bShell(sandbox: E2BShellHandle): Shell;

package/dist/substrates/e2b/shell.js

@@ -0,0 +1,61 @@
+import { isCommandExitError } from "../command-failure.js";
+import {} from "./sdk.js";
+import { withOneRetryOnTransientE2BError } from "./sandbox.js";
+/**
+ * A Shell over an E2B sandbox. The SDK throws CommandExitError on a non-zero exit; this returns
+ * it as a result. Methods are read from the handle on every call, so a handle whose methods are
+ * replaced later is still the one used.
+ */
+export function e2bShell(sandbox) {
+    const run = async (command, options) => {
+        try {
+            const result = await (options === undefined
+                ? sandbox.commands.run(command)
+                : sandbox.commands.run(command, sdkOptions(options)));
+            return {
+                exitCode: result.exitCode ?? 0,
+                stdout: result.stdout ?? "",
+                stderr: result.stderr ?? "",
+            };
+        }
+        catch (error) {
+            if (!isCommandExitError(error))
+                throw error;
+            return exitResult(error);
+        }
+    };
+    return {
+        run,
+        start: (command, options) => run(`setsid -f ${command} < /dev/null > /dev/null 2>&1`, options),
+        async writeFile(path, data, options) {
+            // Binary data goes as an octet stream, as the archive upload always has.
+            const writeOptions = {
+                ...(options?.requestTimeoutMs === undefined
+                    ? {}
+                    : { requestTimeoutMs: options.requestTimeoutMs }),
+                ...(typeof data === "string" ? {} : { useOctetStream: true }),
+            };
+            const write = () => Object.keys(writeOptions).length === 0
+                ? sandbox.files.write(path, data)
+                : sandbox.files.write(path, data, writeOptions);
+            if (options?.retryOnce === undefined)
+                await write();
+            else
+                await withOneRetryOnTransientE2BError(write, options.retryOnce);
+        },
+    };
+}
+/** The SDK names the per-command environment `envs`. */
+function sdkOptions({ env, ...options }) {
+    return env === undefined ? options : { ...options, envs: { ...env } };
+}
+function exitResult(error) {
+    const e = error;
+    const text = (value) => (typeof value === "string" ? value : "");
+    return {
+        exitCode: typeof e.exitCode === "number" ? e.exitCode : 1,
+        stdout: text(e.stdout),
+        // The SDK puts the process's stderr in `stderr` and the envd reason in `error`/`message`.
+        stderr: text(e.stderr) || text(e.error) || text(e.message),
+    };
+}

package/dist/substrates/local/captured-inbox.d.ts

@@ -0,0 +1,6 @@
+import { type ExternalCommsCatch } from "../../comms/sandbox-catch.js";
+/** Expose only this participant's existing catch pages through its local desktop. */
+export declare function startLocalCapturedInbox(external: ExternalCommsCatch, address: string): Promise<{
+    url: string;
+    close(): Promise<void>;
+}>;