humanish 0.109.1 → 0.110.1

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

@@ -1,7 +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 E2BDesktopCreateOptions, type E2BDesktopModule, type E2BDesktopSandbox } from "./sdk.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`. */
 interface E2BSandboxReceiptTarget {
@@ -16,7 +16,7 @@ export interface E2BSandboxRequest {
     retry?: TransientRetryHooks;
     /**
      * Required so every caller decides. `null` is only for a caller that could not open a journal;
-     * that sandbox is reclaimable by its create-time `timeoutMs` alone.
+     * that sandbox carries no owner tags and is reclaimable by its create-time `timeoutMs` alone.
      */
     receipt: E2BSandboxReceiptTarget | null;
 }
@@ -57,13 +57,39 @@ export type E2BSandboxDestroyOutcome = {
     state: "kill-failed";
     detail: string;
 };
-/**
- * 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.
- */
+/** 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: {
     requestTimeoutMs: number;
 }): Promise<E2BSandboxDestroyOutcome>;
+/** What `reclaim --check` learned about one sandbox by its exact id. */
+export type E2BSandboxPresence = {
+    state: "running" | "already-gone";
+} | {
+    state: "check-failed";
+    detail: string;
+};
+/**
+ * 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: {
+    requestTimeoutMs: number;
+}): Promise<E2BSandboxPresence>;
+/** What E2B listed for a run's owner tags. `sandboxes` holds exact matches only. */
+export interface E2BTagSearch {
+    status: "done" | "unavailable" | "failed";
+    sandboxes: E2BListedSandbox[];
+    detail?: string;
+}
+/**
+ * List the sandboxes E2B matches to every one of `tags`, filtered server-side. Each result is
+ * 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: {
+    requestTimeoutMs: number;
+}): Promise<E2BTagSearch>;
 /** Versioned public template built by runtime/browser-media/e2b-template.mjs. */
 export declare const E2B_SPEECH_TEMPLATE = "7409n13kr83f7g7abx5g";
 /** The desktop template a study asks for; undefined selects the SDK default. */
@@ -74,6 +100,8 @@ export declare function e2bDesktopTemplate(config: {
 export interface TransientRetryHooks {
     onRetry?: (reason: string) => void;
     sleep?: (ms: number) => Promise<void>;
+    /** False skips the retry, as when the run started stopping during the first attempt. */
+    canRetry?: () => boolean;
 }
 /** Wall-clock pause before the single retry; envd routing settles within a few seconds. */
 export declare const TRANSIENT_RETRY_DELAY_MS = 3000;

package/dist/substrates/e2b/sandbox.js

@@ -1,13 +1,16 @@
 // 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
+// so each allocation runs the same steps in the same order: register the create with the run's
+// in-process registry, tag the sandbox with the run's owner tags, 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.
+// startup fails has already reclaimed its handle when the error reaches the retry here, and it
+// reports the id to the registry before desktop startup begins.
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
-import { appendSandboxReceipt } from "../../run/sandbox-receipts.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 { E2B_DEBUG_KILL_DETAIL, E2BDesktopStartupError, e2bDebugMode, isSandboxNotFoundError, } from "./sdk.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) {
     return acquire(request, request.template);
@@ -17,33 +20,57 @@ 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);
+    const { module } = request;
+    const target = request.receipt;
+    // Refused before any provider call once the run is stopping.
+    const ticket = target === null ? undefined : beginSandboxCreate(target.root, target.participantId);
     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 participant.
-            await appendSandboxReceipt(root, {
-                at: new Date(now()).toISOString(),
-                laneId: participantId,
-                provider: "e2b",
-                sandboxId: allocation.resourceId,
-                ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
-            });
+        // The owner tags let reclaim find this sandbox on E2B even if its id never reaches this
+        // process: a create that throws after E2B allocated, or a process that dies mid-create. The
+        // journal records them first, so reclaim knows which tags to search for.
+        const owner = target === null ? undefined : sandboxOwnerTags(target.root);
+        if (target !== null && owner !== undefined)
+            await recordSandboxOwnerOnce(target.root, () => appendSandboxOwner(target.root, owner));
+        const options = owner === undefined
+            ? request.options
+            : { ...request.options, metadata: { ...request.options.metadata, ...owner } };
+        if (ticket !== undefined)
+            observeDesktopAllocation(options, (sandboxId) => ticket.created(sandboxId));
+        const sandbox = await withOneRetryOnTransientE2BError(() => {
+            if (ticket?.stopping())
+                throw new SandboxCreateRefusedError();
+            // Without a template the SDK's one-argument create chooses its stock desktop template.
+            return template === undefined
+                ? module.Sandbox.create(options)
+                : module.Sandbox.create(template, options);
+        }, { ...request.retry, canRetry: () => ticket?.stopping() !== true });
+        ticket?.created(sandbox.sandboxId);
+        const allocation = ownE2BSandbox(module, sandbox.sandboxId, ticket);
+        try {
+            if (target !== null) {
+                const { root, participantId, now = Date.now } = target;
+                // Best effort by contract: a failed write leaves the owner tags and the TTL as the
+                // backstops and never fails the participant.
+                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 };
     }
-    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;
+    finally {
+        ticket?.settled();
     }
-    return { sandbox, allocation };
 }
 /** The provider's kill method bound to its class, or undefined when the SDK has none. */
 function boundKill(module) {
@@ -57,7 +84,7 @@ function boundKill(module) {
  * 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. A true in debug mode sent no
- * request, so it confirms nothing. Never list the account.
+ * request, so it confirms nothing.
  */
 async function killById(kill, sandboxId, options) {
     if (kill === undefined)
@@ -84,12 +111,18 @@ async function killById(kill, sandboxId, options) {
         return { status: "unconfirmed", reason: "release_failed", error };
     }
 }
-function ownE2BSandbox(module, resourceId) {
+function ownE2BSandbox(module, resourceId, ticket) {
     // 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 }),
+        release: async () => {
+            const released = await killById(kill, resourceId, { requestTimeoutMs: 60_000 });
+            // The signal handler skips a sandbox its route already released.
+            if (released.status === "released")
+                ticket?.released(resourceId);
+            return released;
+        },
     });
 }
 /**
@@ -136,10 +169,8 @@ export function releaseUnavailableDetail(detail) {
         ? "installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the sandbox"
         : `${detail}; if the sandbox exists, server-side kill-on-timeout will reclaim it`;
 }
-/**
- * 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.
- */
+/** 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);
     if (released.status === "released")
@@ -156,6 +187,68 @@ export async function destroyE2BSandbox(module, sandboxId, options) {
             return { state: "kill-failed", detail: redactText(toErrorMessage(released.error)) };
     }
 }
+/**
+ * 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")
+        return {
+            state: "check-failed",
+            detail: "the installed @e2b/desktop SDK has no Sandbox.getInfo",
+        };
+    try {
+        await module.Sandbox.getInfo(sandboxId, options);
+        return { state: "running" };
+    }
+    catch (error) {
+        if (isSandboxNotFoundError(error))
+            return { state: "already-gone" };
+        return { state: "check-failed", detail: redactText(toErrorMessage(error)) };
+    }
+}
+const TAG_SEARCH_PAGE_SIZE = 100;
+// One run tags at most a few dozen sandboxes. More pages than this means the filter was not
+// applied, and reading on would walk the whole account.
+const TAG_SEARCH_MAX_PAGES = 3;
+/**
+ * List the sandboxes E2B matches to every one of `tags`, filtered server-side. Each result is
+ * 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")
+        return {
+            status: "unavailable",
+            sandboxes: [],
+            detail: "the installed @e2b/desktop SDK has no Sandbox.list",
+        };
+    const sandboxes = [];
+    try {
+        const pages = module.Sandbox.list({
+            query: { metadata: tags },
+            limit: TAG_SEARCH_PAGE_SIZE,
+            requestTimeoutMs: options.requestTimeoutMs,
+        });
+        for (let page = 0; pages.hasNext; page += 1) {
+            if (page === TAG_SEARCH_MAX_PAGES)
+                return {
+                    status: "failed",
+                    sandboxes,
+                    detail: `E2B returned more than ${TAG_SEARCH_MAX_PAGES * TAG_SEARCH_PAGE_SIZE} sandboxes for one run's tags, so the search stopped before reading the rest`,
+                };
+            for (const listed of await pages.nextItems()) {
+                const metadata = listed.metadata ?? {};
+                if (Object.entries(tags).every(([key, value]) => metadata[key] === value))
+                    sandboxes.push(listed);
+            }
+        }
+        return { status: "done", sandboxes };
+    }
+    catch (error) {
+        return { status: "failed", sandboxes, detail: redactText(toErrorMessage(error)) };
+    }
+}
 /** Versioned public template built by runtime/browser-media/e2b-template.mjs. */
 export const E2B_SPEECH_TEMPLATE = "7409n13kr83f7g7abx5g";
 /** The desktop template a study asks for; undefined selects the SDK default. */
@@ -206,7 +299,7 @@ export async function withOneRetryOnTransientE2BError(attempt, hooks) {
         return await attempt();
     }
     catch (error) {
-        if (!isTransientE2BError(error))
+        if (!isTransientE2BError(error) || hooks?.canRetry?.() === false)
             throw error;
         const reason = error instanceof Error ? error.message : String(error);
         hooks?.onRetry?.(reason);

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

@@ -27,7 +27,32 @@ export interface E2BDesktopModule {
         getInfo?(sandboxId: string, options?: {
             requestTimeoutMs?: number;
         }): 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)
+         * and re-checks each tag on what comes back. The e2b SDK on the supported @e2b/desktop range
+         * (2.38 and later) returns a paginator.
+         */
+        list?(options?: E2BSandboxListOptions): E2BSandboxPaginator;
+    };
+}
+interface E2BSandboxListOptions {
+    query?: {
+        metadata?: Record<string, string>;
     };
+    limit?: number;
+    requestTimeoutMs?: number;
+}
+interface E2BSandboxPaginator {
+    readonly hasNext: boolean;
+    nextItems(): Promise<E2BListedSandbox[]>;
+}
+/** One sandbox as the list endpoint describes it. */
+export interface E2BListedSandbox {
+    sandboxId: string;
+    metadata?: Record<string, string>;
+    /** `running` or `paused`. */
+    state?: string;
 }
 interface E2BSandboxInfo {
     id?: string;
@@ -161,6 +186,14 @@ export interface E2BDesktopSandbox {
 }
 export declare function loadE2BDesktopModule(): Promise<E2BDesktopModule>;
 export declare const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10000;
+/**
+ * Call `observer` with the sandbox id as soon as the guarded SDK constructs the handle for a
+ * create made with this exact options object, before desktop startup runs. Startup can take
+ * seconds after E2B created the sandbox; this is the earliest point the id exists in this process.
+ * A module without the guard (a test fake) never calls it, and create's own result still reports
+ * the id.
+ */
+export declare function observeDesktopAllocation(options: E2BDesktopCreateOptions, observer: (sandboxId: string) => void): void;
 type DesktopCreateCleanup = "killed" | "already_gone" | "unconfirmed";
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export declare class E2BDesktopStartupError extends Error {

package/dist/substrates/e2b/sdk.js

@@ -5,27 +5,32 @@
 // E2BDesktopSandbox is the command, file, stream, launch and input subset the participants use; `open` is
 // optional because older SDKs lack it (the computer-use route 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";
+import { desktopPeerAdvice, humanishInstall } from "./peer-install.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. Node resolves the peer relative to humanish itself, so a copy installed in this project " +
-                    "is not found. Install both into the project and run it from there: " +
-                    "`npm i -D humanish @e2b/desktop` then `npx humanish run <study>`.");
+            const { where, advice } = desktopPeerAdvice(humanishInstall());
+            throw new Error(`Live E2B desktop launch requires the optional peer @e2b/desktop${where}. ${advice}`);
         }
         throw error;
     }
 }
 export const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10_000;
+const allocationObservers = new WeakMap();
+/**
+ * Call `observer` with the sandbox id as soon as the guarded SDK constructs the handle for a
+ * create made with this exact options object, before desktop startup runs. Startup can take
+ * seconds after E2B created the sandbox; this is the earliest point the id exists in this process.
+ * A module without the guard (a test fake) never calls it, and create's own result still reports
+ * the id.
+ */
+export function observeDesktopAllocation(options, observer) {
+    allocationObservers.set(options, observer);
+}
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export class E2BDesktopStartupError extends Error {
     cleanup;
@@ -67,6 +72,7 @@ export function guardDesktopSandboxCreate(module) {
                 : DESKTOP_CREATE_CLEANUP_TIMEOUT_MS;
             let cleanupOwned;
             let restoreKill;
+            const observeAllocation = createOptions === undefined ? undefined : allocationObservers.get(createOptions);
             // oxlint-disable-next-line typescript/no-this-alias -- the attempt subclasses whichever SDK class was called
             const CallingSandbox = this;
             class AttemptSandbox extends CallingSandbox {
@@ -91,6 +97,12 @@ export function guardDesktopSandboxCreate(module) {
                         else
                             Reflect.deleteProperty(this, "kill");
                     };
+                    try {
+                        observeAllocation?.(this.sandboxId);
+                    }
+                    catch {
+                        // An observer that throws must not fail the create; the resolved handle reports the id.
+                    }
                 }
             }
             try {
@@ -144,18 +156,6 @@ async function reclaimFailedDesktopCreate(kill, timeoutMs) {
             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;

package/dist/substrates/shell.d.ts

@@ -39,6 +39,8 @@ export declare function runOrThrow(shell: Shell, command: string, options?: Shel
 export declare function throwOnExit(result: ShellResult): ShellResult;
 /** Single-quote a value for a Shell command line. */
 export declare function shellQuote(value: string): string;
+/** A command-line argument, single-quoted only when the shell would split or expand it. */
+export declare function shellArg(value: string): string;
 /** Sanitized, whitespace-collapsed, length-capped tail of command output. */
 export declare function tailOf(value: string | undefined): string;
 export {};

package/dist/substrates/shell.js

@@ -16,6 +16,10 @@ export function throwOnExit(result) {
 export function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
+/** A command-line argument, single-quoted only when the shell would split or expand it. */
+export function shellArg(value) {
+    return /^[\w@%+=:,./-]+$/.test(value) ? value : shellQuote(value);
+}
 /** Sanitized, whitespace-collapsed, length-capped tail of command output. */
 export function tailOf(value) {
     return (value ?? "").trim().replace(/\s+/g, " ").slice(-240);