humanish 0.0.1 → 0.15.1

package/dist/e2b-desktop-executor.js

@@ -0,0 +1,309 @@
+import { PNG } from "pngjs";
+import { commandFailureInfo, tailOf } from "./command-failure.js";
+const DEFAULT_WAIT_MS = 500;
+const DEFAULT_SCROLL_AMOUNT_PER_TICK = 100;
+const TYPE_FALLBACK_TIMEOUT_MS = 15_000;
+/** Coerce screenshot bytes (Uint8Array or Buffer) to a Node Buffer without copying when possible. */
+function toBuffer(bytes) {
+    return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * A `type` action that failed after both the primary write and the clipboard
+ * paste fallback. Carries a redacted attempt chain (path labels only, never the
+ * typed text), the failing phase, and a sanitized stderr/stdout tail when the
+ * substrate produced one. The loop records `.name` + `.message` into the actor
+ * trace notice, so the bundle proves WHERE the type stopped, not just that it did.
+ */
+export class CuaTypeFallbackError extends Error {
+    phase;
+    attemptChain;
+    stderrTail;
+    constructor(phase, attemptChain, stderrTail, cause) {
+        const chain = attemptChain.join(" -> ");
+        const suffix = stderrTail !== undefined && stderrTail.length > 0 ? ` (stderr: ${stderrTail})` : "";
+        super(`type fallback failed at ${phase}: ${chain}${suffix}`);
+        this.name = "CuaTypeFallbackError";
+        this.phase = phase;
+        this.attemptChain = attemptChain;
+        if (stderrTail !== undefined && stderrTail.length > 0)
+            this.stderrTail = stderrTail;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/** Map a clipboard-command exit code to a CuaTypeFallbackError phase and throw. */
+function throwClipboardCommandFailure(exitCode, stderrTail, attemptChain, cause) {
+    if (exitCode === 127) {
+        throw new CuaTypeFallbackError("clipboard-utility-missing", [...attemptChain, "no xclip/xsel clipboard utility"], stderrTail, cause);
+    }
+    throw new CuaTypeFallbackError("clipboard-command", [
+        ...attemptChain,
+        exitCode === undefined ? "clipboard command errored" : `clipboard command failed (exit ${exitCode})`,
+    ], stderrTail, cause);
+}
+/**
+ * Best-effort clipboard-paste fallback for a `type` action after the primary
+ * `desktop.write` failed. Records each attempt into `attemptChain` (path labels
+ * only) and throws a CuaTypeFallbackError naming the failing phase + a sanitized
+ * stderr tail when the chain cannot complete. The typed text is transferred via a
+ * temp file (never shell-quoted) and is never included in the chain or error.
+ */
+async function pasteTextViaClipboard(desktop, text, attemptChain) {
+    const files = desktop.files;
+    const commands = desktop.commands;
+    if (!files || !commands) {
+        throw new CuaTypeFallbackError("clipboard-unavailable", [
+            ...attemptChain,
+            "clipboard fallback unavailable (no command/file surface)",
+        ]);
+    }
+    const path = `/tmp/humanish-cua-type-${Date.now()}-${Math.random().toString(16).slice(2)}.txt`;
+    try {
+        await files.write(path, text, { requestTimeoutMs: TYPE_FALLBACK_TIMEOUT_MS });
+    }
+    catch (writeError) {
+        throw new CuaTypeFallbackError("clipboard-tempfile", [...attemptChain, "clipboard temp-file write failed"], undefined, writeError);
+    }
+    const clipboardCommand = [
+        "set -euo pipefail",
+        "export DISPLAY=\"${DISPLAY:-:0}\"",
+        `text_path=${shellSingleQuote(path)}`,
+        "cleanup() { rm -f \"$text_path\"; }",
+        "trap cleanup EXIT",
+        // Try xclip, then fall back to xsel if xclip is absent OR fails; distinguish a
+        // missing utility (exit 127) from a utility that ran but failed (exit 1) so the
+        // caller can name the phase.
+        "if command -v xclip >/dev/null 2>&1 && xclip -selection clipboard < \"$text_path\"; then",
+        "  :",
+        "elif command -v xsel >/dev/null 2>&1 && xsel --clipboard --input < \"$text_path\"; then",
+        "  :",
+        "elif command -v xclip >/dev/null 2>&1 || command -v xsel >/dev/null 2>&1; then",
+        "  echo 'clipboard utility present but failed to set the clipboard' >&2",
+        "  exit 1",
+        "else",
+        "  echo 'no xclip/xsel clipboard utility available for paste fallback' >&2",
+        "  exit 127",
+        "fi"
+    ].join("\n");
+    // The real @e2b/desktop Sandbox THROWS CommandExitError on any non-zero exit
+    // (it does not return a non-zero exitCode), so the exit code + stderr must be
+    // recovered from the thrown error. A structural fake that returns a non-zero
+    // exitCode instead of throwing is also handled, so both shapes are covered.
+    let runResult;
+    let runError;
+    try {
+        runResult = await commands.run(clipboardCommand, {
+            requestTimeoutMs: TYPE_FALLBACK_TIMEOUT_MS,
+            timeoutMs: TYPE_FALLBACK_TIMEOUT_MS
+        });
+    }
+    catch (error) {
+        runError = error;
+    }
+    if (runError !== undefined) {
+        const detail = commandFailureInfo(runError);
+        throwClipboardCommandFailure(detail.exitCode, detail.stderrTail, attemptChain, runError);
+    }
+    if (runResult !== undefined && runResult.exitCode !== undefined && runResult.exitCode !== 0) {
+        throwClipboardCommandFailure(runResult.exitCode, tailOf(runResult.stderr ?? runResult.stdout), attemptChain);
+    }
+    attemptChain.push("clipboard write ok");
+    try {
+        await desktop.press(["Control", "v"]);
+    }
+    catch (pressError) {
+        throw new CuaTypeFallbackError("paste-keypress", [...attemptChain, "paste keypress (Control+V) failed"], undefined, pressError);
+    }
+}
+/**
+ * Create a CuaExecutor backed by an E2B desktop (or any structural E2BDesktopLike,
+ * e.g. a CI fake). observe() captures a frame and computes its perceptual
+ * signature; execute() dispatches one CuaAction to the matching desktop method.
+ * Every desktop call is awaited so sync and async implementations both work. No
+ * screenshot or action is ever logged.
+ */
+export function createE2BDesktopExecutor(desktop, options = {}) {
+    const defaultWaitMs = options.defaultWaitMs ?? DEFAULT_WAIT_MS;
+    const scrollAmountPerTick = options.scrollAmountPerTick ?? DEFAULT_SCROLL_AMOUNT_PER_TICK;
+    return {
+        async observe() {
+            // Probe browser state before the screenshot so a deterministic stopWhen match
+            // and its persisted frame describe the same settled surface as closely as the
+            // desktop substrate allows.
+            const browserState = await options.observeBrowserState?.().catch(() => undefined);
+            const raw = await desktop.screenshot();
+            const screenshot = toBuffer(raw);
+            return {
+                screenshot,
+                stateSignature: perceptualSignature(screenshot),
+                ...(browserState?.url === undefined ? {} : { url: browserState.url }),
+                ...(browserState?.title === undefined ? {} : { title: browserState.title }),
+                ...(browserState?.text === undefined ? {} : { text: browserState.text })
+            };
+        },
+        async execute(action) {
+            switch (action.kind) {
+                case "click": {
+                    const button = action.button ?? "left";
+                    if (button === "right") {
+                        await desktop.rightClick(action.x, action.y);
+                    }
+                    else if (button === "middle") {
+                        await desktop.middleClick(action.x, action.y);
+                    }
+                    else {
+                        await desktop.leftClick(action.x, action.y);
+                    }
+                    return;
+                }
+                case "double_click":
+                    await desktop.doubleClick(action.x, action.y);
+                    return;
+                case "move":
+                    await desktop.moveMouse(action.x, action.y);
+                    return;
+                case "scroll": {
+                    // The real SDK scroll is vertical only and takes no position, so move the
+                    // cursor to the scroll point first (the action targets a specific spot;
+                    // scrolling at the wrong cursor position would scroll the wrong panel).
+                    // dx (horizontal) has no SDK target and is ignored; a zero dy is a no-op.
+                    if (action.dy === 0)
+                        return;
+                    await desktop.moveMouse(action.x, action.y);
+                    const direction = action.dy > 0 ? "down" : "up";
+                    const amount = Math.max(1, Math.round(Math.abs(action.dy) / scrollAmountPerTick));
+                    await desktop.scroll(direction, amount);
+                    return;
+                }
+                case "type": {
+                    const attemptChain = [];
+                    try {
+                        await desktop.write(action.text);
+                        return;
+                    }
+                    catch {
+                        // The primary write failed; record the path and try the clipboard
+                        // fallback, which throws a CuaTypeFallbackError naming the phase if it
+                        // also fails. (The write error carries no diagnostics beyond "it
+                        // threw"; the typed text is never recorded.)
+                        attemptChain.push("desktop.write failed");
+                    }
+                    await pasteTextViaClipboard(desktop, action.text, attemptChain);
+                    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);
+                    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
+                    // distinct endpoint, so it is also a no-op (no spurious click/move).
+                    const path = action.path;
+                    if (path.length < 2)
+                        return;
+                    const from = path[0];
+                    const to = path[path.length - 1];
+                    if (from === undefined || to === undefined)
+                        return;
+                    await desktop.drag([from.x, from.y], [to.x, to.y]);
+                    return;
+                }
+                case "wait":
+                    await desktop.wait(action.ms ?? defaultWaitMs);
+                    return;
+                case "screenshot":
+                    // No-op: the loop calls observe() separately to capture each frame, so
+                    // capturing here would double-capture. Leave the desktop untouched.
+                    return;
+            }
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Perceptual signature.
+//
+// A coarse, deterministic hash of a frame for no-progress detection in the loop.
+// It is robust to small noise (a blinking cursor, a single changed clock digit)
+// because it area-averages the frame down to a 16x16 grayscale grid and then
+// quantizes each cell to 4 levels (2 bits). Two visually-identical frames produce
+// the same signature; a clearly different frame differs. It is NOT reversible to
+// the image, so exposing it (e.g. in a trace) is public-safe. On any decode
+// failure it returns a stable fallback so two unreadable frames compare equal.
+// ---------------------------------------------------------------------------
+const SIGNATURE_GRID = 16;
+const SIGNATURE_FALLBACK = "unreadable";
+/**
+ * A coarse perceptual hash of a PNG frame for no-progress detection. Decodes the
+ * PNG, area-averages it to a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid,
+ * quantizes each cell to 2 bits (gray >> 6, four levels), and packs the
+ * (SIGNATURE_GRID^2) two-bit cells into a compact hex string. Deterministic (no
+ * Date, no random). Returns SIGNATURE_FALLBACK on any decode failure so two
+ * unreadable frames compare equal.
+ */
+export function perceptualSignature(pngBytes) {
+    let cells;
+    try {
+        const source = Buffer.isBuffer(pngBytes) ? pngBytes : Buffer.from(pngBytes);
+        if (source.length === 0)
+            return SIGNATURE_FALLBACK;
+        const decoded = PNG.sync.read(source);
+        const srcW = decoded.width;
+        const srcH = decoded.height;
+        if (!srcW || !srcH)
+            return SIGNATURE_FALLBACK;
+        cells = quantizedGrid(decoded.data, srcW, srcH);
+    }
+    catch {
+        return SIGNATURE_FALLBACK;
+    }
+    return packCells(cells);
+}
+/** Area-average an RGBA buffer to a grid of 2-bit (0..3) grayscale cells. */
+function quantizedGrid(data, srcW, srcH) {
+    const cells = [];
+    const xRatio = srcW / SIGNATURE_GRID;
+    const yRatio = srcH / SIGNATURE_GRID;
+    for (let gy = 0; gy < SIGNATURE_GRID; gy += 1) {
+        const sy0 = Math.floor(gy * yRatio);
+        const sy1 = Math.min(srcH, Math.max(sy0 + 1, Math.floor((gy + 1) * yRatio)));
+        for (let gx = 0; gx < SIGNATURE_GRID; gx += 1) {
+            const sx0 = Math.floor(gx * xRatio);
+            const sx1 = Math.min(srcW, Math.max(sx0 + 1, Math.floor((gx + 1) * xRatio)));
+            let sum = 0;
+            let n = 0;
+            for (let sy = sy0; sy < sy1; sy += 1) {
+                for (let sx = sx0; sx < sx1; sx += 1) {
+                    const si = (sy * srcW + sx) * 4;
+                    const r = data[si] ?? 0;
+                    const g = data[si + 1] ?? 0;
+                    const b = data[si + 2] ?? 0;
+                    sum += Math.round((r + g + b) / 3);
+                    n += 1;
+                }
+            }
+            const gray = n ? Math.round(sum / n) : 0;
+            // Quantize 0..255 to four levels (0..3). Clamp the 255 edge so it stays in
+            // range (255 >> 6 === 3 already, but Math.min guards any rounding surprise).
+            cells.push(Math.min(3, gray >> 6));
+        }
+    }
+    return cells;
+}
+/** Pack 2-bit cells (4 per hex... actually 2 per byte) into a compact hex string. */
+function packCells(cells) {
+    // Pack four 2-bit cells per byte, then hex-encode. SIGNATURE_GRID^2 cells.
+    const bytes = Buffer.alloc(Math.ceil(cells.length / 4));
+    for (let i = 0; i < cells.length; i += 1) {
+        const byteIndex = i >> 2;
+        const shift = (i & 3) * 2;
+        const value = (cells[i] ?? 0) & 3;
+        bytes[byteIndex] = (bytes[byteIndex] ?? 0) | (value << shift);
+    }
+    return bytes.toString("hex");
+}
+//# sourceMappingURL=e2b-desktop-executor.js.map

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

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

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

@@ -0,0 +1,144 @@
+export interface E2BDesktopModule {
+    Sandbox: {
+        /** Default `desktop` template (no custom image). The historical, byte-stable call shape. */
+        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>;
+        /**
+         * ACCOUNT-WIDE enumeration. Kept only for the routes that already avoid it for cleanup
+         * (shared-world/scripted/cua/preflight kill by exact id and never call this); no cleanup
+         * proof in this codebase should call it (see e2b-terminal-lab.ts teardownSandbox and
+         * oss-meta-lab.ts, both of which reclaim and verify by id, never by listing).
+         */
+        list?(options: E2BSandboxListOptions): E2BSandboxPaginator;
+    };
+}
+export interface E2BSandboxListOptions {
+    metadata?: Record<string, string>;
+    requestTimeoutMs?: number;
+}
+export interface E2BSandboxInfo {
+    id?: string;
+    metadata?: Record<string, string>;
+    sandboxID?: string;
+    sandboxId?: string;
+    state?: string;
+}
+export interface E2BSandboxPaginator {
+    hasNext: boolean;
+    nextItems(options?: {
+        requestTimeoutMs?: number;
+    }): Promise<E2BSandboxInfo[]>;
+}
+export interface E2BDesktopCreateOptions {
+    apiKey: string;
+    dpi?: number;
+    envs?: Record<string, string>;
+    lifecycle?: {
+        onTimeout: "kill" | "pause";
+    };
+    metadata?: Record<string, string>;
+    requestTimeoutMs?: number;
+    resolution?: [number, number];
+    timeoutMs?: number;
+}
+export interface E2BCommandRunOptions {
+    background?: false;
+    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 {
+    error?: string;
+    exitCode?: number;
+    stderr?: string;
+    stdout?: string;
+}
+export interface E2BDesktopSandbox {
+    sandboxId: string;
+    commands: {
+        run(command: string, options?: E2BCommandRunOptions): Promise<E2BCommandResult>;
+    };
+    files: {
+        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>;
+    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 function isMissingE2BDesktopDependency(error: unknown): boolean;
+/**
+ * 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;
+/**
+ * Create an E2B desktop sandbox, optionally on a CUSTOM template (image). The ONE seam every
+ * desktop-creating route calls so the default and custom-template paths are decided in a single
+ * place.
+ *
+ * When `template` is undefined (the default — no `execution.desktop.template` configured), this is
+ * BYTE-STABLE with the historical `Sandbox.create(options)` call: the stock `desktop` template, the
+ * options object passed as the sole argument. When `template` is a non-empty name/id, it selects
+ * the SDK's `Sandbox.create(template, options)` overload so the lab runs on an adopter's image.
+ * The template (when set) is a public-safe label, never a secret.
+ */
+export declare function createDesktopSandbox(module: E2BDesktopModule, options: E2BDesktopCreateOptions, template?: string): Promise<E2BDesktopSandbox>;

package/dist/e2b-desktop-launch.js

@@ -0,0 +1,59 @@
+// Shared E2B desktop substrate: the optional-peer loader + the structural interfaces for the
+// real @e2b/desktop Sandbox. Hoisted out of oss-meta-lab.ts so both the OSS meta-lab and the
+// computer-use lab (cua-actor-lab.ts) launch desktops through one seam (the peer dep is
+// optional and lazily loaded, so neither path pulls @e2b/desktop into the published tarball
+// or CI).
+//
+// E2BDesktopSandbox stays shape-compatible with what the meta path has always used (so meta is
+// unchanged); `open` is declared optional because older SDKs may lack it (the CUA lab falls
+// back to launch). The CUA executor needs the additional mouse/keyboard methods (E2BDesktopLike
+// in e2b-desktop-executor.ts); the live Sandbox has them, so the CUA call site casts the
+// launched sandbox to E2BDesktopLike rather than widening this interface across the whole
+// meta file.
+export async function loadE2BDesktopModule() {
+    try {
+        return await import("@e2b/desktop");
+    }
+    catch (error) {
+        if (isMissingE2BDesktopDependency(error)) {
+            throw new Error("Live E2B desktop launch requires optional peer dependency @e2b/desktop. Install it in this project with `npm i -D @e2b/desktop`, or run `humanish lab run oss --dry-run`.");
+        }
+        throw error;
+    }
+}
+export 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";
+}
+/**
+ * Create an E2B desktop sandbox, optionally on a CUSTOM template (image). The ONE seam every
+ * desktop-creating route calls so the default and custom-template paths are decided in a single
+ * place.
+ *
+ * When `template` is undefined (the default — no `execution.desktop.template` configured), this is
+ * BYTE-STABLE with the historical `Sandbox.create(options)` call: the stock `desktop` template, the
+ * options object passed as the sole argument. When `template` is a non-empty name/id, it selects
+ * the SDK's `Sandbox.create(template, options)` overload so the lab runs on an adopter's image.
+ * The template (when set) is a public-safe label, never a secret.
+ */
+export async function createDesktopSandbox(module, options, template) {
+    return template === undefined
+        ? module.Sandbox.create(options)
+        : module.Sandbox.create(template, options);
+}
+//# sourceMappingURL=e2b-desktop-launch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"e2b-desktop-launch.js","sourceRoot":"","sources":["../src/e2b-desktop-launch.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,6FAA6F;AAC7F,wFAAwF;AACxF,4FAA4F;AAC5F,UAAU;AACV,EAAE;AACF,+FAA+F;AAC/F,4FAA4F;AAC5F,gGAAgG;AAChG,yFAAyF;AACzF,0FAA0F;AAC1F,aAAa;AA4Hb,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,cAAc,CAAgC,CAAC;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,6BAA6B,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,2KAA2K,CAC5K,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC1D,MAAM,KAAK,GAAG,KAA4C,CAAC;IAC3D,OAAO,KAAK,CAAC,IAAI,KAAK,sBAAsB,IAAI,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;AACnG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,KAAK,GAAG,KAA6D,CAAC;IAC5E,OAAO,KAAK,CAAC,IAAI,KAAK,sBAAsB,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,sBAAsB,CAAC;AACrG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAwB,EACxB,OAAgC,EAChC,QAAiB;IAEjB,OAAO,QAAQ,KAAK,SAAS;QAC3B,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAChC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC"}

package/dist/e2b-detached.d.ts

@@ -0,0 +1,53 @@
+import type { E2BDesktopSandbox } from "./e2b-desktop-launch.js";
+export interface DetachedTimers {
+    /** Injected clock (ms) for tests. */
+    now?: () => number;
+    /** Injected sleep for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface DetachedStepOptions extends DetachedTimers {
+    /** Short [a-z0-9-] label; names the script/status/log files under /tmp. */
+    name: string;
+    /** The shell command to run (the lab author's own command — package.json-script trust). */
+    command: string;
+    cwd?: string;
+    /** Wall-clock budget for the step. */
+    timeoutMs: number;
+    pollIntervalMs?: number;
+    requestTimeoutMs?: number;
+}
+export interface DetachedStepResult {
+    ok: boolean;
+    exitCode?: number;
+    timedOut: boolean;
+    /** Capped, UNREDACTED log tail — redact before persisting. */
+    logTail: string;
+}
+/** Read the capped log tail for a step (raw — caller redacts). */
+export declare function readDetachedLog(desktop: E2BDesktopSandbox, name: string, requestTimeoutMs?: number): Promise<string>;
+/**
+ * Run a BOUNDED step (install/build) detached, polling its atomic status file until it
+ * exits or the budget runs out. On timeout the process group is killed and the log tail is
+ * still captured so failures stay diagnosable.
+ */
+export declare function runDetachedStep(desktop: E2BDesktopSandbox, options: DetachedStepOptions): Promise<DetachedStepResult>;
+/**
+ * Launch a LONG-LIVED process (the subject's server) fully detached and return immediately.
+ * No status polling: liveness is the caller's readiness probe, and reclamation belongs to
+ * the sandbox lifecycle (create with kill-on-timeout).
+ */
+export declare function startDetachedProcess(desktop: E2BDesktopSandbox, options: {
+    name: string;
+    command: string;
+    cwd?: string;
+    requestTimeoutMs?: number;
+}): Promise<void>;
+/**
+ * Poll a URL from INSIDE the sandbox until it answers 2xx/3xx or the budget runs out.
+ * Returns true when the subject is ready.
+ */
+export declare function probeUrl(desktop: E2BDesktopSandbox, url: string, options: {
+    timeoutMs: number;
+    intervalMs?: number;
+    requestTimeoutMs?: number;
+} & DetachedTimers): Promise<boolean>;