@e2e-dev/e2b 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+@e2e-dev/e2b
+Copyright 2026 TesterArmy, Inc.
+
+This product includes software developed at TesterArmy, Inc.
+(https://tester.army).

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @e2e-dev/e2b
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run Android and web tests in [E2B](https://e2b.dev) sandboxes. Each worker gets its own
+Android 16 sandbox with your `.apk` installed, and the sandbox is deleted when the run ends.
+No Android SDK or `adb` is needed on your machine. For web tests, see [Browsers](#browsers).
+
+```bash
+npm install --save-dev e2e @e2e-dev/mobile @e2e-dev/e2b e2b
+```
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+import { e2b } from '@e2e-dev/e2b';
+
+export default {
+  targets: [
+    {
+      engine: mobile({ platform: 'android', device: e2b() }),
+      app: { bundleId: 'com.example.app', appPath: 'build/app-debug.apk' },
+    },
+  ],
+  workers: 4,
+} satisfies E2EConfig;
+```
+
+Set `E2B_API_KEY` from the [E2B dashboard](https://e2b.dev/dashboard), and `E2B_DOMAIN`
+for a dedicated E2B cluster. Android on E2B is x86_64 only, without Google Play Services.
+Sandboxes refuse public traffic; tests reach them through a local tunnel on `127.0.0.1`.
+
+See the [integration guide](https://e2e.tester.army/docs/integrations/e2b) for every
+option and the limits.
+
+## Browsers
+
+`web({ browser: e2bBrowsers() })` runs a web target in Chromium in an E2B sandbox: one
+sandbox per worker, or per attempt with `scope: 'attempt'`. Import it from
+`@e2e-dev/e2b/web`, which needs only `@e2e-dev/web`.
+
+```bash
+npm install --save-dev e2e @e2e-dev/web @e2e-dev/e2b e2b
+```
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+import { e2bBrowsers } from '@e2e-dev/e2b/web';
+
+export default {
+  targets: [{ engine: web({ browser: e2bBrowsers() }), app: { url: 'https://staging.example.com' } }],
+  workers: 4,
+} satisfies E2EConfig;
+```
+
+It uses the same `E2B_API_KEY`, and a sandbox template with Chromium that you build once
+from the Playwright image. The browser runs in E2B's cloud, so `app.url` must be reachable
+from the internet. See the
+[integration guide](https://e2e.tester.army/docs/integrations/e2b) for the template, the
+defaults, and the limits.
+
+## License
+
+Apache-2.0

package/dist/.build.json

@@ -0,0 +1 @@
+{"version":"0.0.0"}

package/dist/browsers.d.ts

@@ -0,0 +1,32 @@
+/** Chromium in E2B sandboxes as a `BrowserProvider` for the web engine. */
+import type { BrowserProvider, BrowserProviderScope } from '@e2e-dev/web';
+export interface E2BBrowsersOptions {
+    /**
+     * Sandbox template with Playwright's Chromium under `/ms-playwright`, such as one built from the Playwright image
+     * `@e2e-dev/web` pins. `e2e-chromium` by default.
+     */
+    readonly template?: string | undefined;
+    /**
+     * `worker` (default): one browser sandbox per worker slot, leased in
+     * `prepare` and released in `finish`. `attempt`: a fresh sandbox per test
+     * attempt.
+     */
+    readonly scope?: BrowserProviderScope | undefined;
+    /**
+     * How long a sandbox lives before E2B kills it, in milliseconds. Defaults to
+     * one hour: the backstop for a run that died before it could release.
+     */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * E2B browsers for `web({ browser: e2bBrowsers() })`: Chromium in an E2B
+ * sandbox per worker slot, or per attempt with `scope: 'attempt'`. Chromium
+ * listens on the sandbox's loopback, and E2B's edge masks each request's
+ * `Host` as localhost so DevTools accepts it. The sandbox refuses public
+ * traffic: the lease's `cdpEndpoint` is a loopback tunnel on the runner's
+ * machine that adds E2B's traffic access token, so it carries no secret.
+ * Sandboxes are tagged with the run, target, slot, and attempt, killed at
+ * release, swept at the end of the run, and killed by E2B after `timeoutMs`
+ * if the run died first.
+ */
+export declare function e2bBrowsers(options?: E2BBrowsersOptions): BrowserProvider;

package/dist/browsers.js

@@ -0,0 +1,130 @@
+/** Chromium in E2B sandboxes as a `BrowserProvider` for the web engine. */
+import { rejectUnknownKeys } from 'e2e/engine';
+import { sandboxClients } from './client.js';
+import { leaseMetadata, messageOf, poll, sandboxLeases, templateOption, timeoutOption, withLog } from './lease.js';
+const OPTION_KEYS = Object.keys({
+    template: true,
+    scope: true,
+    timeoutMs: true,
+});
+const DEFAULT_TEMPLATE = 'e2e-chromium';
+const DEFAULT_TIMEOUT_MS = 60 * 60_000;
+/** Chromium's DevTools port, on the sandbox's loopback only. */
+const CHROMIUM_CDP_PORT = 9222;
+/**
+ * Chromium refuses a DevTools request whose `Host` is neither an IP address
+ * nor localhost, which every request through E2B's public host would be, so
+ * E2B's edge rewrites `Host` to this on the way into the sandbox. `${PORT}`
+ * is E2B's placeholder for the port, not a template literal.
+ */
+const MASKED_HOST = 'localhost:${PORT}';
+/** Where each browser saves downloads on its own disk, for the engine to read back through the sandbox filesystem. */
+const DOWNLOADS_DIR = '/tmp/e2e-downloads';
+/** Chromium's output, read into the error when it never answers. */
+const CHROMIUM_LOG = '/tmp/e2e-chromium.log';
+/** Bounds Chromium's start and its first answer from outside, together. */
+const START_TIMEOUT_MS = 60_000;
+/**
+ * Finds the template's Playwright Chromium and prints its path, run in the foreground so a
+ * template without it fails the lease at once, with this message, instead of at the start timeout.
+ */
+const FIND_CHROMIUM = [
+    `mkdir -p ${DOWNLOADS_DIR}`,
+    'chrome=$(find /ms-playwright -maxdepth 3 -type f -name chrome 2>/dev/null | head -n 1)',
+    '[ -x "$chrome" ] || { echo "Playwright Chromium is missing from the sandbox template: no /ms-playwright/*/chrome-linux*/chrome" >&2; exit 1; }',
+    'printf %s "$chrome"',
+].join('\n');
+/** A path `find` printed for Chromium, as the only shape that reaches the start command. */
+const CHROMIUM_PATH = /^\/ms-playwright\/[\w./-]+$/;
+/** Starts Chromium at `chrome` headless, with DevTools on loopback. */
+function startChromium(chrome) {
+    if (!CHROMIUM_PATH.test(chrome))
+        throw new Error(`unexpected Chromium path ${JSON.stringify(chrome)} in the sandbox template`);
+    // A history restore from Chromium's back/forward cache emits no load event
+    // over CDP, so Playwright goBack({ waitUntil: 'load' }) otherwise hangs.
+    return `exec ${chrome} --headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage --no-first-run --no-default-browser-check --disable-features=BackForwardCache --remote-debugging-port=${CHROMIUM_CDP_PORT} --user-data-dir=/tmp/e2e-chromium about:blank > ${CHROMIUM_LOG} 2>&1`;
+}
+/** The browser WebSocket URL in a `/json/version` answer, or `undefined`. */
+function debuggerUrl(body) {
+    return typeof body === 'object' && body !== null && 'webSocketDebuggerUrl' in body ? body.webSocketDebuggerUrl : undefined;
+}
+/**
+ * Polls Chromium through the tunnel until it answers, and resolves to its
+ * browser WebSocket endpoint on the tunnel. Chromium reports the endpoint
+ * under the masked `localhost` host, so only its path is kept: the endpoint a
+ * lease carries is a bare loopback URL.
+ */
+function browserEndpoint(tunnel, signal) {
+    return poll('Chromium did not answer through the sandbox tunnel', signal, async (attempt) => {
+        const response = await fetch(`${tunnel.url}/json/version`, { signal: attempt });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        const endpoint = debuggerUrl(await response.json());
+        const path = typeof endpoint === 'string' && URL.canParse(endpoint) ? new URL(endpoint).pathname : '';
+        if (!path.startsWith('/devtools/browser/'))
+            throw new Error('no WebSocket endpoint in /json/version');
+        return `${tunnel.url.replace(/^http:/, 'ws:')}${path}`;
+    });
+}
+/**
+ * E2B browsers for `web({ browser: e2bBrowsers() })`: Chromium in an E2B
+ * sandbox per worker slot, or per attempt with `scope: 'attempt'`. Chromium
+ * listens on the sandbox's loopback, and E2B's edge masks each request's
+ * `Host` as localhost so DevTools accepts it. The sandbox refuses public
+ * traffic: the lease's `cdpEndpoint` is a loopback tunnel on the runner's
+ * machine that adds E2B's traffic access token, so it carries no secret.
+ * Sandboxes are tagged with the run, target, slot, and attempt, killed at
+ * release, swept at the end of the run, and killed by E2B after `timeoutMs`
+ * if the run died first.
+ */
+export function e2bBrowsers(options = {}) {
+    rejectUnknownKeys('e2bBrowsers()', options, OPTION_KEYS);
+    const template = templateOption('e2bBrowsers()', options.template, DEFAULT_TEMPLATE);
+    const timeoutMs = timeoutOption('e2bBrowsers()', options.timeoutMs, DEFAULT_TIMEOUT_MS);
+    const clientFor = sandboxClients();
+    const leases = sandboxLeases(clientFor);
+    /** Starts Chromium and resolves to the endpoint a worker attaches to, through the lease's tunnel. */
+    async function ready(sandbox, tunnel, request) {
+        request.log(`browser sandbox ${sandbox.sandboxId}`);
+        const signal = AbortSignal.any([request.signal, AbortSignal.timeout(START_TIMEOUT_MS)]);
+        const chrome = await sandbox.run(FIND_CHROMIUM, { timeoutMs: START_TIMEOUT_MS, signal });
+        await sandbox.start(startChromium(chrome.trim()), { signal });
+        const cdpEndpoint = await browserEndpoint(tunnel, signal).catch(async (cause) => {
+            throw await withLog(sandbox, CHROMIUM_LOG, cause);
+        });
+        return { id: sandbox.sandboxId, cdpEndpoint };
+    }
+    return {
+        name: 'e2b',
+        ...(options.scope === undefined ? {} : { scope: options.scope }),
+        async acquire(request) {
+            const metadata = { ...leaseMetadata(request), ...(request.attemptId === undefined ? {} : { e2e_attempt: request.attemptId }) };
+            return leases.acquire(request, { template, timeoutMs, metadata, maskRequestHost: MASKED_HOST, port: CHROMIUM_CDP_PORT }, (sandbox, tunnel) => ready(sandbox, tunnel, request));
+        },
+        release: (lease, context) => leases.release(lease.id, context),
+        async sweep(context) {
+            const client = clientFor(context.env);
+            const open = await client.list({ e2e_run: context.runId, e2e_target: context.targetName }, context.signal);
+            const settled = await Promise.allSettled(open.map((id) => client.kill(id, context.signal)));
+            const killed = [];
+            const failed = [];
+            settled.forEach((result, index) => {
+                const id = open[index];
+                if (result.status === 'rejected') {
+                    failed.push(`${id} (${messageOf(result.reason)})`);
+                }
+                else if (result.value) {
+                    killed.push(id);
+                }
+            });
+            if (failed.length > 0) {
+                throw new Error(`killed ${killed.length === 0 ? 'none' : killed.join(', ')}; could not kill ${failed.join(', ')}, so E2B ends them after timeoutMs`);
+            }
+            return killed;
+        },
+        downloads: {
+            dir: DOWNLOADS_DIR,
+            read: (lease, file, context) => clientFor(context.env).readFile(lease.id, file, context.signal),
+        },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The slice of the E2B SDK both providers use, loaded on first use so a
+ * config load never pays for it, and the connection the run's environment
+ * names.
+ */
+export interface E2BCreateParams {
+    readonly template: string;
+    readonly timeoutMs: number;
+    readonly metadata: Readonly<Record<string, string>>;
+    /**
+     * The `Host` E2B's edge puts on every request it forwards into the sandbox,
+     * with `${PORT}` standing for the port, such as `localhost:${PORT}`. Unset,
+     * a request arrives with the public host it was sent to.
+     */
+    readonly maskRequestHost?: string | undefined;
+}
+interface StartOptions {
+    /** Environment variables for the command only, such as a token kept out of the command text E2B receives. */
+    readonly envs?: Record<string, string> | undefined;
+    readonly signal: AbortSignal;
+}
+/** One running sandbox, as much of it as the providers drive. */
+export interface E2BSandbox {
+    readonly sandboxId: string;
+    /** The token E2B wants on every request to a sandbox port: sandboxes refuse public traffic. */
+    readonly trafficToken: string;
+    /** Runs a shell command to completion and resolves to its stdout; rejects when it exits non-zero, with its output in the message. */
+    run(command: string, options: {
+        readonly timeoutMs: number;
+        readonly signal: AbortSignal;
+    }): Promise<string>;
+    /** Starts a shell command and leaves it running. */
+    start(command: string, options: StartOptions): Promise<void>;
+    /** The public host a port inside the sandbox answers on, without the scheme. */
+    host(port: number): string;
+}
+export interface E2BSandboxes {
+    /**
+     * Creates a sandbox under a budget of its own: a creation request cut off by
+     * the run's interrupt could still start a sandbox whose id never arrives, so
+     * the caller checks its own signal once the id is in hand.
+     */
+    create(params: E2BCreateParams): Promise<E2BSandbox>;
+    /** The bytes of one file on the disk of a sandbox another process may have created. */
+    readFile(sandboxId: string, file: string, signal: AbortSignal): Promise<Uint8Array>;
+    /** Kills a sandbox; one E2B no longer knows counts as killed. Resolves to whether E2B still knew it. */
+    kill(sandboxId: string, signal: AbortSignal): Promise<boolean>;
+    /** The ids of the running sandboxes carrying every one of `metadata`. */
+    list(metadata: Readonly<Record<string, string>>, signal: AbortSignal): Promise<string[]>;
+}
+/** The last `OUTPUT_TAIL_CHARS` of a command's output. */
+export declare function tail(text: string | undefined): string;
+/** The SDK client for a run's environment. */
+export type ClientFor = (env: Readonly<Record<string, string | undefined>>) => E2BSandboxes;
+/** One SDK client per connection, shared by every request a provider serves. */
+export declare function sandboxClients(): ClientFor;
+export {};

package/dist/client.js

@@ -0,0 +1,155 @@
+/**
+ * The slice of the E2B SDK both providers use, loaded on first use so a
+ * config load never pays for it, and the connection the run's environment
+ * names.
+ */
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { ConfigurationError } from 'e2e/engine';
+/** Bounds one creation request: E2B answers in seconds, so a minute means it is not coming. */
+const CREATE_TIMEOUT_MS = 60_000;
+/**
+ * Appended to the `User-Agent` of every E2B request, so E2B can tell this integration's traffic apart.
+ * The version is this package's, not e2e's.
+ */
+const INTEGRATION = `e2e-e2b/${createRequire(import.meta.url)('../package.json').version}`;
+/** How much of a failed command's output its error keeps: enough to name what failed without flooding the run's error line. */
+const OUTPUT_TAIL_CHARS = 600;
+/** The last `OUTPUT_TAIL_CHARS` of a command's output. */
+export function tail(text) {
+    const trimmed = (text ?? '').trim();
+    return trimmed.length > OUTPUT_TAIL_CHARS ? `...${trimmed.slice(-OUTPUT_TAIL_CHARS)}` : trimmed;
+}
+/**
+ * A signal that follows `signal` only until `settled` does. The SDK ties a
+ * command's signal to its output stream for the command's whole life, so a
+ * long-running command gets one that can cancel its start but never its stream.
+ */
+async function untilSettled(signal, settled) {
+    signal.throwIfAborted();
+    const starting = new AbortController();
+    const onAbort = () => starting.abort(signal.reason);
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        return await settled(starting.signal);
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+/** E2B sandboxes for one connection, through the SDK. */
+function e2bSandboxes(connection) {
+    const sdk = import('e2b').then((module) => {
+        // Read when the SDK builds a connection config, so it runs before the first request.
+        module.ConnectionConfig.setIntegration(INTEGRATION);
+        return module;
+    });
+    const { sandboxUrl, ...rest } = connection;
+    const opts = { ...rest, ...(sandboxUrl === undefined ? {} : { sandboxUrl }), debug: false };
+    async function wrap(sandbox) {
+        const { CommandExitError } = await sdk;
+        const trafficToken = sandbox.trafficAccessToken;
+        if (trafficToken === undefined || trafficToken === '') {
+            throw new Error(`E2B created sandbox ${sandbox.sandboxId} without a traffic access token`);
+        }
+        return {
+            sandboxId: sandbox.sandboxId,
+            trafficToken,
+            async run(command, { timeoutMs, signal }) {
+                try {
+                    // Aborting ends only the SDK's stream; the process dies with the sandbox the failed lease kills.
+                    const result = await sandbox.commands.run(command, { timeoutMs, signal });
+                    return result.stdout;
+                }
+                catch (cause) {
+                    if (signal.aborted)
+                        throw signal.reason;
+                    if (cause instanceof CommandExitError)
+                        throw new Error(`exited ${cause.exitCode}: ${tail(cause.stderr) || tail(cause.stdout)}`, { cause });
+                    throw cause;
+                }
+            },
+            async start(command, { envs, signal }) {
+                const handle = await untilSettled(signal, (starting) => sandbox.commands.run(command, { background: true, timeoutMs: 0, signal: starting, ...(envs === undefined ? {} : { envs }) }));
+                // The process keeps running; only the SDK's output stream for it closes.
+                await handle.disconnect();
+            },
+            host: (port) => sandbox.getHost(port),
+        };
+    }
+    return {
+        async create(params) {
+            const { Sandbox } = await sdk;
+            const sandbox = await Sandbox.create(params.template, {
+                ...opts,
+                timeoutMs: params.timeoutMs,
+                metadata: { ...params.metadata },
+                network: { allowPublicTraffic: false, ...(params.maskRequestHost === undefined ? {} : { maskRequestHost: params.maskRequestHost }) },
+                // The SDK retries a failed create; the key makes E2B answer a retry with the same sandbox.
+                idempotencyKey: `e2e-${randomUUID()}`,
+                signal: AbortSignal.timeout(CREATE_TIMEOUT_MS),
+            });
+            try {
+                return await wrap(sandbox);
+            }
+            catch (cause) {
+                await sandbox.kill().catch(() => { });
+                throw cause;
+            }
+        },
+        async readFile(sandboxId, file, signal) {
+            const { Sandbox } = await sdk;
+            const sandbox = await Sandbox.connect(sandboxId, { ...opts, signal });
+            return sandbox.files.read(file, { format: 'bytes', signal });
+        },
+        async kill(sandboxId, signal) {
+            const { Sandbox } = await sdk;
+            return Sandbox.kill(sandboxId, { ...opts, signal });
+        },
+        async list(metadata, signal) {
+            const { Sandbox } = await sdk;
+            const paginator = Sandbox.list({ ...opts, query: { metadata: { ...metadata }, state: ['running'] } });
+            const ids = [];
+            while (paginator.hasNext) {
+                signal.throwIfAborted();
+                for (const info of await paginator.nextItems({ signal }))
+                    ids.push(info.sandboxId);
+            }
+            return ids;
+        },
+    };
+}
+/** A non-empty variable from the run's environment, trimmed, or `undefined`. */
+function envValue(env, name) {
+    const value = env[name]?.trim();
+    return value === undefined || value === '' ? undefined : value;
+}
+/** The connection the run's environment names, never `process.env`. */
+function connectionFor(env) {
+    const apiKey = envValue(env, 'E2B_API_KEY');
+    if (apiKey === undefined) {
+        throw new ConfigurationError('INVALID_CONFIG', '@e2e-dev/e2b requires E2B_API_KEY in the run environment');
+    }
+    const sandboxUrl = envValue(env, 'E2B_SANDBOX_URL');
+    // The SDK reads the runner's `E2B_SANDBOX_URL` when given none.
+    const ambient = envValue(process.env, 'E2B_SANDBOX_URL');
+    if (ambient !== undefined && ambient !== sandboxUrl) {
+        throw new ConfigurationError('INVALID_CONFIG', "@e2e-dev/e2b: unset E2B_SANDBOX_URL in the runner's environment, or set the same value in the run environment; the E2B SDK reads it whatever the run environment says");
+    }
+    const domain = envValue(env, 'E2B_DOMAIN') ?? 'e2b.app';
+    return { apiKey, domain, apiUrl: envValue(env, 'E2B_API_URL') ?? `https://api.${domain}`, ...(sandboxUrl === undefined ? {} : { sandboxUrl }) };
+}
+/** One SDK client per connection, shared by every request a provider serves. */
+export function sandboxClients() {
+    const clients = new Map();
+    return (env) => {
+        const connection = connectionFor(env);
+        const key = `${connection.apiUrl}\n${connection.sandboxUrl ?? ''}\n${connection.domain}\n${connection.apiKey}`;
+        let client = clients.get(key);
+        if (client === undefined) {
+            client = e2bSandboxes(connection);
+            clients.set(key, client);
+        }
+        return client;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@e2e-dev/e2b` public surface: `e2b()`, a device provider that runs each
+ * worker slot's Android on an E2B `android-16` sandbox for `@e2e-dev/mobile`.
+ * `e2bBrowsers()`, for Chromium in E2B sandboxes on `@e2e-dev/web`, is
+ * exported from `@e2e-dev/e2b/web`.
+ */
+export { e2b } from './provider.ts';
+export type { E2BOptions } from './provider.ts';

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@e2e-dev/e2b` public surface: `e2b()`, a device provider that runs each
+ * worker slot's Android on an E2B `android-16` sandbox for `@e2e-dev/mobile`.
+ * `e2bBrowsers()`, for Chromium in E2B sandboxes on `@e2e-dev/web`, is
+ * exported from `@e2e-dev/e2b/web`.
+ */
+export { e2b } from './provider.js';

package/dist/lease.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The lease lifecycle both providers share: create a sandbox, open the tunnel
+ * to its port, wait until the provider's service is ready, and on any failure
+ * close the tunnel and kill the sandbox; plus the option checks and the
+ * polling and log reading the ready steps use.
+ */
+import { type ClientFor, type E2BCreateParams, type E2BSandbox } from './client.ts';
+import { type Tunnel } from './tunnel.ts';
+/** What a lease needs from the engine's request: the run's environment and its interrupt. */
+interface LeaseRequest {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly signal: AbortSignal;
+}
+/** A sandbox to create, and the port inside it the lease's tunnel reaches. */
+export interface LeaseParams extends E2BCreateParams {
+    readonly port: number;
+}
+/** The message of a thrown value, for an error line. */
+export declare function messageOf(cause: unknown): string;
+/**
+ * Calls `probe` every `POLL_INTERVAL_MS`, each call bounded to
+ * `PROBE_TIMEOUT_MS`, until it resolves, and resolves to its value. When
+ * `signal` ends first, fails with `what` and the last probe's error.
+ */
+export declare function poll<T>(what: string, signal: AbortSignal, probe: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/**
+ * `cause` with the last lines of `log` in the sandbox, for a service that never answered: the log says
+ * why. `secret` is cut from them. Reading the log is best-effort and bounded on its own clock.
+ */
+export declare function withLog(sandbox: E2BSandbox, log: string, cause: unknown, secret?: string): Promise<Error>;
+/** A template option: a non-empty name, or the provider's default when absent. */
+export declare function templateOption(factory: string, template: unknown, fallback: string): string;
+/** A sandbox lifetime option: a positive integer of milliseconds, or the provider's default when absent. */
+export declare function timeoutOption(factory: string, timeoutMs: unknown, fallback: number): number;
+/** The tags every sandbox carries, so a sweep or a person can find a run's sandboxes. */
+export declare function leaseMetadata(request: {
+    readonly runId: string;
+    readonly targetName: string;
+    readonly slot: number;
+}): Record<string, string>;
+/**
+ * The leases one provider holds. `acquire` creates a sandbox, opens the tunnel
+ * to `params.port`, and hands both to `ready`, which resolves to the lease. Any
+ * failure after the id is known closes the tunnel and kills the sandbox,
+ * including a run interrupted while the creation request was in flight.
+ * `release` kills the lease's sandbox and closes its tunnel.
+ */
+export declare function sandboxLeases(clientFor: ClientFor): {
+    acquire<T>(request: LeaseRequest, params: LeaseParams, ready: (sandbox: E2BSandbox, tunnel: Tunnel) => Promise<T>): Promise<T>;
+    release(id: string, context: LeaseRequest): Promise<void>;
+};
+export {};

package/dist/lease.js

@@ -0,0 +1,119 @@
+/**
+ * The lease lifecycle both providers share: create a sandbox, open the tunnel
+ * to its port, wait until the provider's service is ready, and on any failure
+ * close the tunnel and kill the sandbox; plus the option checks and the
+ * polling and log reading the ready steps use.
+ */
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ConfigurationError } from 'e2e/engine';
+import { tail } from './client.js';
+import { openTunnel } from './tunnel.js';
+/** Bounds the kill of a sandbox whose lease failed. */
+const KILL_TIMEOUT_MS = 30_000;
+/** How often `poll` asks, and how long one answer may take. */
+const POLL_INTERVAL_MS = 500;
+const PROBE_TIMEOUT_MS = 5_000;
+/** Bounds the read of a log for an error message. */
+const LOG_TIMEOUT_MS = 10_000;
+/** The message of a thrown value, for an error line. */
+export function messageOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * Calls `probe` every `POLL_INTERVAL_MS`, each call bounded to
+ * `PROBE_TIMEOUT_MS`, until it resolves, and resolves to its value. When
+ * `signal` ends first, fails with `what` and the last probe's error.
+ */
+export async function poll(what, signal, probe) {
+    let last = 'no answer';
+    while (true) {
+        if (signal.aborted)
+            throw new Error(`${what}: ${last}`, { cause: signal.reason });
+        try {
+            return await probe(AbortSignal.any([signal, AbortSignal.timeout(PROBE_TIMEOUT_MS)]));
+        }
+        catch (cause) {
+            if (!signal.aborted)
+                last = messageOf(cause);
+        }
+        await sleep(POLL_INTERVAL_MS, undefined, { signal }).catch(() => { });
+    }
+}
+/**
+ * `cause` with the last lines of `log` in the sandbox, for a service that never answered: the log says
+ * why. `secret` is cut from them. Reading the log is best-effort and bounded on its own clock.
+ */
+export async function withLog(sandbox, log, cause, secret) {
+    const read = await sandbox.run(`tail -n 20 ${log} 2>/dev/null || true`, { timeoutMs: LOG_TIMEOUT_MS, signal: AbortSignal.timeout(LOG_TIMEOUT_MS) }).catch(() => '');
+    const lines = tail(secret === undefined ? read : read.replaceAll(secret, '<redacted>'));
+    if (lines === '')
+        return cause instanceof Error ? cause : new Error(messageOf(cause));
+    return new Error(`${messageOf(cause)}; ${log}: ${lines}`, { cause });
+}
+/** A template option: a non-empty name, or the provider's default when absent. */
+export function templateOption(factory, template, fallback) {
+    if (template === undefined)
+        return fallback;
+    if (typeof template !== 'string' || template.trim() === '') {
+        throw new ConfigurationError('INVALID_CONFIG', `${factory}: template must be a non-empty template name`);
+    }
+    return template;
+}
+/** A sandbox lifetime option: a positive integer of milliseconds, or the provider's default when absent. */
+export function timeoutOption(factory, timeoutMs, fallback) {
+    if (timeoutMs === undefined)
+        return fallback;
+    if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new ConfigurationError('INVALID_CONFIG', `${factory}: timeoutMs must be a positive integer of milliseconds`);
+    }
+    return timeoutMs;
+}
+/** The tags every sandbox carries, so a sweep or a person can find a run's sandboxes. */
+export function leaseMetadata(request) {
+    return { e2e_run: request.runId, e2e_target: request.targetName, e2e_slot: String(request.slot) };
+}
+/**
+ * The leases one provider holds. `acquire` creates a sandbox, opens the tunnel
+ * to `params.port`, and hands both to `ready`, which resolves to the lease. Any
+ * failure after the id is known closes the tunnel and kills the sandbox,
+ * including a run interrupted while the creation request was in flight.
+ * `release` kills the lease's sandbox and closes its tunnel.
+ */
+export function sandboxLeases(clientFor) {
+    const tunnels = new Map();
+    return {
+        async acquire(request, params, ready) {
+            const client = clientFor(request.env);
+            const { port, ...create } = params;
+            request.signal.throwIfAborted();
+            const sandbox = await client.create(create);
+            let tunnel;
+            try {
+                request.signal.throwIfAborted();
+                tunnel = await openTunnel({ host: sandbox.host(port), trafficToken: sandbox.trafficToken });
+                const lease = await ready(sandbox, tunnel);
+                tunnels.set(sandbox.sandboxId, tunnel);
+                return lease;
+            }
+            catch (cause) {
+                await tunnel?.close();
+                try {
+                    await client.kill(sandbox.sandboxId, AbortSignal.timeout(KILL_TIMEOUT_MS));
+                }
+                catch (cleanup) {
+                    throw new AggregateError([cause, cleanup], `E2B lease failed: ${messageOf(cause)}; killing sandbox ${sandbox.sandboxId} also failed, so E2B ends it after timeoutMs: ${messageOf(cleanup)}`, { cause: cleanup });
+                }
+                throw cause;
+            }
+        },
+        async release(id, context) {
+            try {
+                await clientFor(context.env).kill(id, context.signal);
+            }
+            finally {
+                await tunnels.get(id)?.close();
+                tunnels.delete(id);
+            }
+        },
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,23 @@
+/** E2B's `android-16` sandboxes as a `DeviceProvider` for the mobile engine. */
+import type { DeviceProvider } from '@e2e-dev/mobile';
+export interface E2BOptions {
+    /** Sandbox template that boots Android, `android-16` by default. */
+    readonly template?: string | undefined;
+    /**
+     * How long a sandbox lives before E2B kills it, in milliseconds. Defaults to
+     * one hour: the backstop for a run that died before it could release.
+     */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * E2B Android for `mobile({ platform: 'android', device: e2b() })`: one
+ * `android-16` sandbox per worker slot. Each sandbox runs the engine's
+ * agent-device behind `agent-device proxy`, with a bearer token minted per
+ * lease, so the runner needs no adb of its own. The sandbox refuses public
+ * traffic: the lease's daemon is a loopback tunnel on the runner's machine
+ * that adds E2B's traffic access token. A target's `app.appPath` (an `.apk`)
+ * is installed through that daemon. Sandboxes are tagged
+ * with the run, target, and slot, killed at release, and killed by E2B after
+ * `timeoutMs` if the run died first.
+ */
+export declare function e2b(options?: E2BOptions): DeviceProvider;

package/dist/provider.js

@@ -0,0 +1,130 @@
+/** E2B's `android-16` sandboxes as a `DeviceProvider` for the mobile engine. */
+import { randomBytes } from 'node:crypto';
+import { createAgentDeviceClient } from 'agent-device';
+import { ConfigurationError, rejectUnknownKeys } from 'e2e/engine';
+import { sandboxClients } from './client.js';
+import { leaseMetadata, poll, sandboxLeases, templateOption, timeoutOption, withLog } from './lease.js';
+const OPTION_KEYS = Object.keys({
+    template: true,
+    timeoutMs: true,
+});
+const DEFAULT_TEMPLATE = 'android-16';
+const DEFAULT_TIMEOUT_MS = 60 * 60_000;
+/** The adb serial the template's Android answers on; the same device is also listed as `emulator-5554`. */
+const SERIAL = '127.0.0.1:5555';
+/** Port the agent-device proxy listens on inside the sandbox. */
+const PROXY_PORT = 4310;
+/** The proxy's errors, read into the error when it never answers. */
+const PROXY_LOG = '/tmp/agent-device-proxy.log';
+/** The template ships no Node; agent-device needs one. */
+const NODE_VERSION = '24.11.1';
+/** The SHA-256 nodejs.org publishes for that version's linux-x64 tarball (`SHASUMS256.txt`). */
+const NODE_SHA256 = '58a5ff5cc8f2200e458bea22e329d5c1994aa1b111d499ca46ec2411d58239ca';
+/** Bounds the in-sandbox setup, Android's boot, the proxy's first answer, and the build's install, together. */
+const SETUP_TIMEOUT_MS = 300_000;
+/** A plain semver version: the only shape of `agentDeviceVersion` that reaches a shell. */
+const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+/**
+ * Installs Node and the engine's agent-device in the sandbox and waits for
+ * Android to finish booting. It runs on every sandbox because it cannot be
+ * baked into a template: custom templates built on `android-16` do not boot
+ * Android.
+ */
+function setupScript(agentDeviceVersion) {
+    return [
+        'set -eu',
+        // One command per line: under `set -e` a failed step inside an `&&` chain would not stop the script.
+        'if ! command -v node >/dev/null; then',
+        `  curl -fsSL https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.gz -o /tmp/node.tar.gz`,
+        `  echo "${NODE_SHA256}  /tmp/node.tar.gz" | sha256sum -c --quiet -`,
+        '  sudo tar -xzf /tmp/node.tar.gz -C /usr/local --strip-components=1',
+        'fi',
+        `sudo npm install --global --no-fund --no-audit --loglevel=error agent-device@${agentDeviceVersion}`,
+        `adb connect ${SERIAL} >/dev/null`,
+        `until [ "$(adb -s ${SERIAL} shell getprop sys.boot_completed | tr -d '\\r')" = 1 ]; do sleep 1; done`,
+    ].join('\n');
+}
+/**
+ * Installs the target's `.apk` through the lease's own daemon, resolving to
+ * the package agent-device reports: the client uploads the build to the
+ * proxy, the same way the engine's `device.installApp()` does.
+ */
+async function installBuild(sandbox, request, appPath, daemon, signal) {
+    if (!appPath.toLowerCase().endsWith('.apk')) {
+        throw new ConfigurationError('INVALID_CONFIG', `e2b() installs an .apk; app.appPath of target "${request.targetName}" is ${appPath}`);
+    }
+    // A session of its own, closed before the worker opens its session on the device.
+    const client = createAgentDeviceClient({ session: `e2e-install-${sandbox.sandboxId}`, daemonBaseUrl: daemon.baseUrl, daemonAuthToken: daemon.authToken });
+    try {
+        const installed = await client.apps.install({ appPath, platform: 'android', serial: SERIAL, signal, ...(request.app === undefined ? {} : { app: request.app }) });
+        // The same order the mobile engine reads an install's identity in.
+        const app = installed.bundleId ?? installed.package ?? installed.appId ?? request.app;
+        if (app === undefined)
+            throw new Error(`installing ${appPath} reported no package; set app.bundleId to the package to open`);
+        return app;
+    }
+    finally {
+        await client.sessions.close({ signal }).catch(() => { });
+    }
+}
+/** Polls the proxy's unauthenticated health route through the tunnel until it answers. */
+async function waitForProxy(baseUrl, signal) {
+    await poll(`agent-device proxy at ${baseUrl} did not answer`, signal, async (attempt) => {
+        const response = await fetch(`${baseUrl}/health`, { signal: attempt });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+    });
+}
+/**
+ * E2B Android for `mobile({ platform: 'android', device: e2b() })`: one
+ * `android-16` sandbox per worker slot. Each sandbox runs the engine's
+ * agent-device behind `agent-device proxy`, with a bearer token minted per
+ * lease, so the runner needs no adb of its own. The sandbox refuses public
+ * traffic: the lease's daemon is a loopback tunnel on the runner's machine
+ * that adds E2B's traffic access token. A target's `app.appPath` (an `.apk`)
+ * is installed through that daemon. Sandboxes are tagged
+ * with the run, target, and slot, killed at release, and killed by E2B after
+ * `timeoutMs` if the run died first.
+ */
+export function e2b(options = {}) {
+    rejectUnknownKeys('e2b()', options, OPTION_KEYS);
+    const template = templateOption('e2b()', options.template, DEFAULT_TEMPLATE);
+    const timeoutMs = timeoutOption('e2b()', options.timeoutMs, DEFAULT_TIMEOUT_MS);
+    const leases = sandboxLeases(sandboxClients());
+    /** Sets the sandbox up, starts agent-device behind its proxy, installs the build, and resolves to the lease. */
+    async function ready(sandbox, baseUrl, request) {
+        request.log(`sandbox ${sandbox.sandboxId}`);
+        const signal = AbortSignal.any([request.signal, AbortSignal.timeout(SETUP_TIMEOUT_MS)]);
+        await sandbox.run(setupScript(request.agentDeviceVersion), { timeoutMs: SETUP_TIMEOUT_MS, signal }).catch((cause) => {
+            // The setup's own budget, not the run's interrupt: say which step ran out of time.
+            if (signal.aborted && !request.signal.aborted) {
+                throw new Error(`Android setup did not finish within ${SETUP_TIMEOUT_MS / 1000}s: installing Node and agent-device, or waiting for Android to boot`, { cause });
+            }
+            throw cause;
+        });
+        const daemon = { baseUrl, authToken: randomBytes(32).toString('hex') };
+        // Through `envs`, so the token is not in the command E2B receives. Not AGENT_DEVICE_DAEMON_AUTH_TOKEN:
+        // the daemon the proxy starts would inherit it. The proxy prints its token, so stdout is dropped.
+        await sandbox.start(`exec agent-device proxy --host 0.0.0.0 --port ${PROXY_PORT} --daemon-auth-token "$PROXY_TOKEN" >/dev/null 2>${PROXY_LOG}`, {
+            envs: { PROXY_TOKEN: daemon.authToken },
+            signal,
+        });
+        await waitForProxy(baseUrl, signal).catch(async (cause) => {
+            throw await withLog(sandbox, PROXY_LOG, cause, daemon.authToken);
+        });
+        const installedApp = request.appPath === undefined ? undefined : await installBuild(sandbox, request, request.appPath, daemon, signal);
+        return { id: sandbox.sandboxId, daemon, deviceId: SERIAL, ...(installedApp === undefined ? {} : { installedApp }) };
+    }
+    return {
+        name: 'e2b',
+        async acquire(request) {
+            if (request.platform !== 'android') {
+                throw new ConfigurationError('INVALID_CONFIG', `e2b() serves Android only; target "${request.targetName}" asks for ${request.platform}`);
+            }
+            if (!SEMVER.test(request.agentDeviceVersion))
+                throw new Error(`unexpected agent-device version ${JSON.stringify(request.agentDeviceVersion)}`);
+            return leases.acquire(request, { template, timeoutMs, metadata: leaseMetadata(request), port: PROXY_PORT }, (sandbox, tunnel) => ready(sandbox, tunnel.url, request));
+        },
+        release: (lease, context) => leases.release(lease.id, context),
+    };
+}

package/dist/tunnel.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A loopback proxy on the runner's machine to one port of one sandbox. The
+ * providers create every sandbox with public traffic off, so E2B refuses any
+ * request to a sandbox port without the sandbox's traffic access token in a
+ * header. The web engine connects with a CDP URL alone, and agent-device's
+ * client has no option for a custom header, so both talk to this proxy
+ * instead, and it adds the token. A lease carries only the proxy's `127.0.0.1` URL, so the
+ * traffic token reaches no lease, log line, or error the engine reports. It answers only requests
+ * addressed to that URL.
+ */
+export interface TunnelTarget {
+    /** The sandbox port's public host, without the scheme. */
+    readonly host: string;
+    /** The sandbox's traffic access token. */
+    readonly trafficToken: string;
+    /** Port and scheme of the public host: 443 over TLS unless a test says otherwise. */
+    readonly port?: number | undefined;
+    readonly tls?: boolean | undefined;
+}
+export interface Tunnel {
+    /** `http://127.0.0.1:<port>`: the base URL that reaches the sandbox port. */
+    readonly url: string;
+    close(): Promise<void>;
+}
+/** Opens a tunnel to one sandbox port on a free loopback port. */
+export declare function openTunnel(target: TunnelTarget): Promise<Tunnel>;

package/dist/tunnel.js

@@ -0,0 +1,153 @@
+/**
+ * A loopback proxy on the runner's machine to one port of one sandbox. The
+ * providers create every sandbox with public traffic off, so E2B refuses any
+ * request to a sandbox port without the sandbox's traffic access token in a
+ * header. The web engine connects with a CDP URL alone, and agent-device's
+ * client has no option for a custom header, so both talk to this proxy
+ * instead, and it adds the token. A lease carries only the proxy's `127.0.0.1` URL, so the
+ * traffic token reaches no lease, log line, or error the engine reports. It answers only requests
+ * addressed to that URL.
+ */
+import { createServer, request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { connect as netConnect } from 'node:net';
+import { pipeline } from 'node:stream';
+import { connect as tlsConnect } from 'node:tls';
+/** The header E2B's edge reads a sandbox's traffic access token from. */
+const TRAFFIC_TOKEN_HEADER = 'e2b-traffic-access-token';
+/** The request's headers for the sandbox, with its own `Host` and the traffic token, less `proxy-connection`, which only a proxy reads. */
+function forwardedHeaders(req, target) {
+    const headers = { ...req.headers, host: target.host, [TRAFFIC_TOKEN_HEADER]: target.trafficToken };
+    delete headers['proxy-connection'];
+    return headers;
+}
+/** The request line and forwarded headers of `req`, as the raw HTTP/1.1 head a socket to the sandbox starts with. */
+function requestHead(req, target) {
+    const lines = [`${req.method ?? 'GET'} ${req.url ?? '/'} HTTP/1.1`];
+    for (const [name, value] of Object.entries(forwardedHeaders(req, target))) {
+        // A header Node received more than once arrives as an array: one line each.
+        for (const one of [value].flat()) {
+            if (one !== undefined)
+                lines.push(`${name}: ${one}`);
+        }
+    }
+    return `${lines.join('\r\n')}\r\n\r\n`;
+}
+/**
+ * Whether `req` names the tunnel itself as its `Host`. A page in the user's browser that points its own
+ * domain at 127.0.0.1 sends that domain instead. The tunnel replaces `Host` on the way out, so
+ * Chromium's own check of it never sees the page's: the tunnel makes that check here.
+ */
+function addressedHere(req, port) {
+    return req.headers.host === `127.0.0.1:${port}` || req.headers.host === `localhost:${port}`;
+}
+/**
+ * Whether `answer` is JSON the tunnel can rewrite. A link in it to the sandbox's public host fails
+ * without the token, as agent-device's upload preflight does: it names the `Host` it was asked on.
+ */
+function rewritable(answer) {
+    return answer.headers['content-encoding'] === undefined && /^application\/json\s*(;|$)/i.test(answer.headers['content-type'] ?? '');
+}
+/** Sends a JSON `answer` on with every link that matches `publicOrigin` pointed at `url` instead. */
+function sendRewritten(answer, res, publicOrigin, url) {
+    const chunks = [];
+    answer.on('data', (chunk) => chunks.push(chunk));
+    answer.on('error', () => res.destroy());
+    answer.on('end', () => {
+        const body = Buffer.from(Buffer.concat(chunks).toString('utf8').replace(publicOrigin, url));
+        const headers = { ...answer.headers, 'content-length': String(body.length) };
+        delete headers['transfer-encoding'];
+        res.writeHead(answer.statusCode ?? 502, headers);
+        res.end(body);
+    });
+}
+/**
+ * Joins two sockets: bytes flow both ways, and either one going away ends the other. Node keeps the
+ * client's half open after it ends, and an upstream still in its TLS handshake would hold the piped
+ * end, so the client's `end` counts as gone too.
+ */
+function relay(client, upstream) {
+    client.pipe(upstream).pipe(client);
+    upstream.on('error', () => client.destroy());
+    client.on('error', () => upstream.destroy());
+    upstream.on('close', () => client.destroy());
+    client.on('close', () => upstream.destroy());
+    client.on('end', () => upstream.destroy());
+}
+/** Opens a tunnel to one sandbox port on a free loopback port. */
+export async function openTunnel(target) {
+    const secure = target.tls ?? true;
+    const port = target.port ?? (secure ? 443 : 80);
+    // The whole host only, not the start of a longer one such as `<host>.example`.
+    const publicOrigin = new RegExp(`https?://${target.host.replaceAll('.', '\\.')}(?::\\d+)?(?![\\w.:-])`, 'g');
+    const sockets = new Set();
+    const track = (socket) => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+    };
+    let local = 0;
+    let url = '';
+    const server = createServer((req, res) => {
+        if (!addressedHere(req, local)) {
+            res.writeHead(403).end();
+            return;
+        }
+        const send = secure ? httpsRequest : httpRequest;
+        const upstream = send({ host: target.host, port, servername: target.host, path: req.url ?? '/', method: req.method, headers: forwardedHeaders(req, target) }, (answer) => {
+            if (rewritable(answer)) {
+                sendRewritten(answer, res, publicOrigin, url);
+                return;
+            }
+            res.writeHead(answer.statusCode ?? 502, answer.headers);
+            pipeline(answer, res, () => { });
+        });
+        // The client went away: stop the request to the sandbox too.
+        res.once('close', () => {
+            if (!res.writableFinished)
+                upstream.destroy();
+        });
+        // The upstream error names the sandbox host, never the token; the client sees only the status.
+        upstream.on('error', () => {
+            if (!res.headersSent)
+                res.writeHead(502);
+            res.end();
+        });
+        req.pipe(upstream);
+    });
+    server.on('upgrade', (req, client, head) => {
+        track(client);
+        // Node drops the server's error handler from an upgraded socket; without one, a reset would crash the run.
+        client.on('error', () => client.destroy());
+        if (!addressedHere(req, local)) {
+            client.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+            return;
+        }
+        const upstream = secure ? tlsConnect({ host: target.host, port, servername: target.host }) : netConnect(port, target.host);
+        track(upstream);
+        // The socket holds writes until it connects, so relaying starts at once.
+        upstream.write(requestHead(req, target));
+        if (head.length > 0)
+            upstream.write(head);
+        relay(client, upstream);
+    });
+    server.on('connection', track);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    // An open tunnel never keeps the process alive; a run that ends without releasing exits anyway.
+    server.unref();
+    local = server.address().port;
+    url = `http://127.0.0.1:${local}`;
+    return {
+        url,
+        close: () => new Promise((resolve) => {
+            for (const socket of sockets)
+                socket.destroy();
+            server.close(() => resolve());
+        }),
+    };
+}

package/dist/web.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@e2e-dev/e2b/web` public surface: `e2bBrowsers()`, a browser provider for
+ * Chromium in E2B sandboxes on `@e2e-dev/web`. Its types never reference
+ * `@e2e-dev/mobile`, and the package root's never reference `@e2e-dev/web`,
+ * so a project installs only the engine it uses.
+ */
+export { e2bBrowsers } from './browsers.ts';
+export type { E2BBrowsersOptions } from './browsers.ts';

package/dist/web.js

@@ -0,0 +1,7 @@
+/**
+ * `@e2e-dev/e2b/web` public surface: `e2bBrowsers()`, a browser provider for
+ * Chromium in E2B sandboxes on `@e2e-dev/web`. Its types never reference
+ * `@e2e-dev/mobile`, and the package root's never reference `@e2e-dev/web`,
+ * so a project installs only the engine it uses.
+ */
+export { e2bBrowsers } from './browsers.js';

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@e2e-dev/e2b",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "E2B sandboxes for e2e: Android on the android-16 template for mobile tests, and Chromium for web tests",
+  "keywords": [
+    "e2e",
+    "end-to-end",
+    "testing",
+    "mobile-testing",
+    "e2b",
+    "sandbox",
+    "android-emulator",
+    "agent-device",
+    "cloud-browsers",
+    "hosted-browsers",
+    "chromium",
+    "cdp",
+    "ci"
+  ],
+  "license": "Apache-2.0",
+  "contributors": [
+    "Tomas Varga <tomasvarga@sudolabs.io>"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/e2e-inc/e2e.git",
+    "directory": "packages/e2b"
+  },
+  "bugs": {
+    "url": "https://github.com/e2e-inc/e2e/issues"
+  },
+  "homepage": "https://github.com/e2e-inc/e2e/tree/main/packages/e2b#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "latest"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "default": "./dist/web.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "peerDependencies": {
+    "@e2e-dev/mobile": ">=0.12.6 <1",
+    "@e2e-dev/web": ">=0.11.0 <1",
+    "e2b": ">=2.62.0 <3",
+    "e2e": ">=0.15.0 <1"
+  },
+  "peerDependenciesMeta": {
+    "@e2e-dev/mobile": {
+      "optional": true
+    },
+    "@e2e-dev/web": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@e2e-dev/mobile": "0.12.6",
+    "@e2e-dev/web": "0.15.5",
+    "@types/node": "26.6.6",
+    "e2b": "2.63.0",
+    "e2e": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.1.0"
+  },
+  "engines": {
+    "node": "^22.22.3 || >=24.8.0"
+  },
+  "dependencies": {
+    "agent-device": "0.21.36"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc --project tsconfig.build.json && node ../../scripts/stamp-dist.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit"
+  }
 }