humanish 0.79.0 → 0.81.0

package/dist/e2b-desktop-launch.d.ts

@@ -61,12 +61,20 @@ export interface E2BNetworkOptions {
     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>;
-    /** Absent means unrestricted egress, which is the historical behavior and stays the default. */
+    /** Routing and optional header transforms; absent allowOut/denyOut retains unrestricted egress. */
     network?: E2BNetworkOptions;
     lifecycle?: {
         onTimeout: "kill" | "pause";
@@ -130,6 +138,24 @@ export interface E2BDesktopSandbox {
     };
 }
 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 without a catch.
+ * 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;
 export declare function isMissingE2BDesktopDependency(error: unknown): boolean;
 /**
  * Detect a SandboxNotFoundError-shaped error from the real @e2b/desktop SDK, WITHOUT importing
@@ -185,3 +211,4 @@ export declare function isTransientE2BError(error: unknown): boolean;
  * warning should say.
  */
 export declare function withOneRetryOnTransientE2BError<T>(attempt: () => Promise<T>, hooks?: TransientRetryHooks): Promise<T>;
+export {};

package/dist/e2b-desktop-launch.js

@@ -12,9 +12,10 @@
 // meta file.
 import { sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { protectDesktopScreenshotCleanup } from "./e2b-desktop-screenshot-cleanup.js";
 export async function loadE2BDesktopModule() {
     try {
-        return await import("@e2b/desktop");
+        return guardDesktopSandboxCreate(await import("@e2b/desktop"));
     }
     catch (error) {
         if (isMissingE2BDesktopDependency(error)) {
@@ -29,6 +30,90 @@ export async function loadE2BDesktopModule() {
         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 without a catch.
+ * 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) {
+            let cleanupOwned;
+            const CallingSandbox = this;
+            class AttemptSandbox extends CallingSandbox {
+                constructor(...args) {
+                    super(...args);
+                    cleanupOwned = this.kill.bind(this);
+                }
+            }
+            try {
+                const args = typeof templateOrOptions === "string" ? [templateOrOptions, options] : [templateOrOptions];
+                const desktop = await Reflect.apply(SdkSandbox.create, AttemptSandbox, args);
+                // The loader also serves direct Sandbox.create callers (terminal/legacy meta routes).
+                return protectDesktopScreenshotCleanup(desktop);
+            }
+            catch (error) {
+                if (cleanupOwned === undefined)
+                    throw error;
+                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;
+                const cleanup = await reclaimFailedDesktopCreate(cleanupOwned, timeoutMs);
+                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?
  *
@@ -94,6 +179,8 @@ export const TRANSIENT_RETRY_DELAY_MS = 3_000;
  * 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;

package/dist/e2b-desktop-launch.js.map

@@ -1 +1 @@
-{"version":3,"file":"e2b-desktop-launch.js","sourceRoot":"","sources":["../src/e2b-desktop-launch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"e2b-desktop-launch.js","sourceRoot":"","sources":["../src/e2b-desktop-launch.ts"],"names":[],"mappings":"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"}

package/dist/e2b-desktop-screenshot-cleanup.d.ts

@@ -0,0 +1,15 @@
+import type { E2BDesktopSandbox } from "./e2b-desktop-launch.js";
+/** Runtime diagnostic only; no provider errors, file paths, or image contents are retained. */
+export declare function desktopScreenshotCleanupFailures(desktop: object): number;
+/**
+ * @e2b/desktop 2.3.3 screenshot() awaits capture and files.read(path), then discards the
+ * files.remove(path) promise. A removal that races sandbox teardown can therefore crash Node
+ * AFTER valid bytes were returned. Installed-SDK conformance tests pin that behavior (#662).
+ *
+ * Observe only removal of a file successfully read within THIS screenshot invocation. The
+ * exact path comes from the SDK, not a guessed filename pattern. AsyncLocalStorage isolates
+ * concurrent screenshots and unrelated file operations without changing SDK method receivers.
+ * The ORIGINAL removal promise is returned: an SDK version (or caller) that awaits it still
+ * receives the original rejection. No process-wide rejection handler or filesystem retry.
+ */
+export declare function protectDesktopScreenshotCleanup<T extends E2BDesktopSandbox>(desktop: T): T;

package/dist/e2b-desktop-screenshot-cleanup.js

@@ -0,0 +1,67 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const guarded = new WeakSet();
+const failureCounts = new WeakMap();
+// One long-lived context instance: creating one per desktop would require disable() on every
+// teardown for AsyncLocalStorage itself to be collected. Invocation stores follow async work.
+const screenshotScope = new AsyncLocalStorage();
+/** Runtime diagnostic only; no provider errors, file paths, or image contents are retained. */
+export function desktopScreenshotCleanupFailures(desktop) {
+    return failureCounts.get(desktop) ?? 0;
+}
+/**
+ * @e2b/desktop 2.3.3 screenshot() awaits capture and files.read(path), then discards the
+ * files.remove(path) promise. A removal that races sandbox teardown can therefore crash Node
+ * AFTER valid bytes were returned. Installed-SDK conformance tests pin that behavior (#662).
+ *
+ * Observe only removal of a file successfully read within THIS screenshot invocation. The
+ * exact path comes from the SDK, not a guessed filename pattern. AsyncLocalStorage isolates
+ * concurrent screenshots and unrelated file operations without changing SDK method receivers.
+ * The ORIGINAL removal promise is returned: an SDK version (or caller) that awaits it still
+ * receives the original rejection. No process-wide rejection handler or filesystem retry.
+ */
+export function protectDesktopScreenshotCleanup(desktop) {
+    if (guarded.has(desktop))
+        return desktop;
+    const files = desktop.files;
+    const read = files.read;
+    const remove = files.remove;
+    if (typeof read !== "function" || typeof remove !== "function")
+        return desktop;
+    const screenshot = desktop.screenshot;
+    files.read = function (path, ...args) {
+        const pending = read.call(this, path, ...args);
+        const scope = screenshotScope.getStore();
+        if (scope?.desktop !== desktop)
+            return pending;
+        return pending.then((value) => {
+            scope.paths.add(path);
+            return value;
+        });
+    };
+    files.remove = function (path, ...args) {
+        const pending = remove.call(this, path, ...args);
+        const scope = screenshotScope.getStore();
+        if (scope?.desktop === desktop && scope.paths.has(path)) {
+            // The secondary handler resolves independently. Returning pending (not catch's promise)
+            // preserves awaited removal failures while observing the SDK's detached rejection.
+            void pending.catch(() => {
+                const count = desktopScreenshotCleanupFailures(desktop) + 1;
+                failureCounts.set(desktop, count);
+                try {
+                    process.stderr.write(`humanish desktop: screenshot temporary-file cleanup failed (${count}); image read completed. Sandbox teardown reclaims temporary files.\n`);
+                }
+                catch {
+                    // A closed diagnostic stream must not turn this secondary rejection observer into a
+                    // new unhandled rejection. The per-instance counter remains available.
+                }
+            });
+        }
+        return pending;
+    };
+    desktop.screenshot = function (...args) {
+        return screenshotScope.run({ desktop, paths: new Set() }, () => screenshot.apply(this, args));
+    };
+    guarded.add(desktop);
+    return desktop;
+}
+//# sourceMappingURL=e2b-desktop-screenshot-cleanup.js.map

package/dist/e2b-desktop-screenshot-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"e2b-desktop-screenshot-cleanup.js","sourceRoot":"","sources":["../src/e2b-desktop-screenshot-cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAU,CAAC;AACtC,MAAM,aAAa,GAAG,IAAI,OAAO,EAAkB,CAAC;AACpD,6FAA6F;AAC7F,8FAA8F;AAC9F,MAAM,eAAe,GAAG,IAAI,iBAAiB,EAA2C,CAAC;AAEzF,+FAA+F;AAC/F,MAAM,UAAU,gCAAgC,CAAC,OAAe;IAC9D,OAAO,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,+BAA+B,CAA8B,OAAU;IACrF,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAwB,CAAC;IAC/C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,UAAU,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC;IAE/E,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACtC,KAAK,CAAC,IAAI,GAAG,UAAU,IAAI,EAAE,GAAG,IAAI;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;QACzC,IAAI,KAAK,EAAE,OAAO,KAAK,OAAO;YAAE,OAAO,OAAO,CAAC;QAC/C,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YAC5B,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtB,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IACF,KAAK,CAAC,MAAM,GAAG,UAAU,IAAI,EAAE,GAAG,IAAI;QACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;QACzC,IAAI,KAAK,EAAE,OAAO,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxD,wFAAwF;YACxF,mFAAmF;YACnF,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;gBACtB,MAAM,KAAK,GAAG,gCAAgC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC5D,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBAClC,IAAI,CAAC;oBACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+DAA+D,KAAK,uEAAuE,CAAC,CAAC;gBACpK,CAAC;gBAAC,MAAM,CAAC;oBACP,oFAAoF;oBACpF,uEAAuE;gBACzE,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IACF,OAAO,CAAC,UAAU,GAAG,UAAU,GAAG,IAAI;QACpC,OAAO,eAAe,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,EAAU,EAAE,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IACxG,CAAC,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACrB,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/e2b-terminal-lab.d.ts

@@ -1,6 +1,6 @@
 import type { ActorCompletionReason, ActorPersonaRef, ActorStatus, ActorTrace } from "./actor-contract.js";
 import { type RunLabProvenance } from "./run-status.js";
-import type { LabConfig, LabScenarioCaps } from "./lab-config.js";
+import type { LabConfig, LabScenarioCaps, LabRuntimeAuth } from "./lab-config.js";
 import { type E2BDesktopModule } from "./e2b-desktop-launch.js";
 import { renderObserver, type ObserverResult } from "./observer.js";
 import { type ResolvedPersona } from "./persona.js";
@@ -59,7 +59,7 @@ export interface TerminalProductLabHooks {
     /**
      * The operator environment the lane reads the runtime key from (and from which it asserts no
      * banned credential is requested). Defaults to process.env. The runtime key is injected ONLY
-     * into the command-scoped `codex` invocation — NEVER Sandbox.create envs (the credential
+     * into command-scoped `codex` env or an external header transform — NEVER Sandbox.create envs (the credential
      * boundary); tests plant a fake key here and assert it never reaches metadata/global env/artifacts.
      */
     env?: Record<string, string | undefined>;
@@ -363,6 +363,7 @@ export declare function buildLiveTerminalProductBundle(args: {
     publicSurfaces: string[];
     caps?: LabScenarioCaps;
     runtimeAuthKeyName: string;
+    runtimeAuth?: LabRuntimeAuth;
     policies: {
         allowPrivateRepoAccess: boolean;
         allowProviderCredentials: boolean;