@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/e2b/runtime.js

@@ -1,58 +1,106 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
 // ---------------------------------------------------------------------------
-// E2B provider for the SandboxRuntime contract.
+// E2B provider for both public runtime planes.
 //
-// The `e2b` npm package is imported LAZILY (`await import("e2b")`), never at
-// module top level, so consumers using a different provider never bundle it.
-// The SDK surface is modeled structurally below (from e2b@2.19.0) so typecheck
-// and unit tests do not hard-couple to the SDK type graph, and a fake factory
-// can drive every path without a real E2B API key.
+// The `e2b` package is imported lazily so a consumer using another provider
+// does not eagerly load it. The structural surface below follows the installed
+// e2b v2 contract while keeping tests independent from an API key.
 // ---------------------------------------------------------------------------
-// Command-LIFETIME budget for a background run (NOT a request timeout).
-//
-// Callers commonly pass a short `options.timeoutMs` meaning "how long to wait
-// for the START call to return". For E2B that value is the SDK *request* cap,
-// not the command lifetime — mapping it onto the background command's
-// `timeoutMs` would kill every long-running command when the start request
-// deadline elapses. We instead set the command lifetime and the microVM
-// timeout to this budget, and route the caller's short timeout to
-// `requestTimeoutMs`.
 const DEFAULT_RUN_BUDGET_MS = 30 * 60_000;
 const DEFAULT_CREATE_TIMEOUT_MS = 120_000;
-const SCRIPT_LOG_READ_MAX_BYTES = 200_000;
+const DEFAULT_LOOKUP_TIMEOUT_MS = 10_000;
+const ADMISSION_RECONCILIATION_TIMEOUT_MS = 1_000;
+const ADMISSION_RECONCILIATION_INTERVAL_MS = 25;
+const SCRIPT_LOG_READ_MAX_BYTES = 262_144;
+const ASYNC_SESSION_ENV = "AGENTWORKFORCE_E2B_ASYNC_SESSION";
+const ASYNC_REQUEST_ENV = "AGENTWORKFORCE_E2B_ASYNC_REQUEST";
+/** Terminal status used when E2B confirms that an admitted process is gone
+ * before it can publish an exit sidecar. */
+export const E2B_ASYNC_PROCESS_LOST_EXIT_CODE = 255;
 export class E2BSandboxRuntime {
     id = "e2b";
-    // `start`/`stop` below are unconditional no-ops (pause/resume is a warm-reuse
-    // follow-up), so lifecycle must be declared false rather than inferred from
-    // their presence. Label search IS real server-side (`Sandbox.list` with a
-    // metadata query), so warm leases are meaningful; `collectByLabels` keeps its
-    // own `[]`-degrade for an SDK build that lacks `list`.
-    declaredCapabilities = { warmLease: true, lifecycle: false };
+    capabilities = {
+        // The SDK has a PTY API, but this adapter does not expose one through the
+        // public runtime contract.
+        pty: false,
+        // Launches always use the caller-provided template/snapshot identifier.
+        snapshots: true,
+        isolation: "strong",
+        // Handles can be resolved by id in a later process/request.
+        persistentHandle: true,
+        // Polling returns bounded snapshots; it does not expose a streaming API.
+        streamingLogs: false,
+    };
+    // E2B v2 performs metadata-filtered server-side lookup, and stop/start map
+    // to pause/connect (connect resumes a paused sandbox).
+    declaredCapabilities = { warmLease: true, lifecycle: true };
     apiKey;
     template;
     runBudgetMs;
+    syncRunBudgetMs;
+    sandboxLifetimeMs;
     createTimeoutMs;
     injectedStatics;
     staticsPromise;
-    // Cache live Sandbox instances launched this process; cross-request access
-    // (the poll ticks) resolves via Sandbox.connect(id) — the reattach that lets
-    // a run outlive the request that started it.
-    sandboxes = new Map();
+    registrations = new Map();
+    asyncAdmissions = new Map();
     constructor(options) {
-        this.apiKey = options.apiKey;
-        this.template = options.template.trim();
-        this.runBudgetMs = options.runBudgetMs ?? DEFAULT_RUN_BUDGET_MS;
-        this.createTimeoutMs = options.createTimeoutMs ?? DEFAULT_CREATE_TIMEOUT_MS;
+        const apiKey = options.apiKey.trim();
+        if (!apiKey) {
+            throw new Error("E2B API key is required");
+        }
+        const template = options.template.trim();
+        if (!template) {
+            throw new Error("E2B sandbox template is required");
+        }
+        this.apiKey = apiKey;
+        this.template = template;
+        this.runBudgetMs = positiveDuration(options.runBudgetMs, DEFAULT_RUN_BUDGET_MS);
+        this.syncRunBudgetMs = positiveDuration(options.syncRunBudgetMs, this.runBudgetMs);
+        this.sandboxLifetimeMs = positiveDuration(options.sandboxLifetimeMs, this.runBudgetMs);
+        this.createTimeoutMs = positiveDuration(options.createTimeoutMs, DEFAULT_CREATE_TIMEOUT_MS);
         this.injectedStatics = options.sandbox;
     }
     async findByLabels(labels, options = {}) {
-        const handles = await this.findAllByLabels(labels, options);
-        const excluded = new Set(options.excludeIds ?? []);
-        return handles.find((handle) => !excluded.has(handle.id)) ?? null;
+        const states = options.states === undefined ? ["STARTED"] : options.states;
+        const providerStates = toE2BStates(states);
+        if (providerStates?.length === 0) {
+            return null;
+        }
+        const excludedIds = new Set(options.excludeIds ?? []);
+        const deadline = lookupDeadline(options.timeoutMs);
+        const paginator = await this.listSandboxes(labels, providerStates, pageSize(options));
+        while (paginator.hasNext) {
+            const page = await awaitLookupOperation(paginator.nextItems(), deadline, "listing matching E2B sandboxes");
+            for (const info of page) {
+                if (!matchesState(info.state, states) || excludedIds.has(info.sandboxId)) {
+                    continue;
+                }
+                return this.registerInfo(info, options);
+            }
+        }
+        return null;
     }
     async findAllByLabels(labels, options = {}) {
         const states = options.states === undefined ? ["STARTED"] : options.states;
-        const limit = options.limit ?? options.pageSize;
-        return this.collectByLabels(labels, states, limit);
+        const providerStates = toE2BStates(states);
+        if (providerStates?.length === 0) {
+            return [];
+        }
+        const deadline = lookupDeadline(options.timeoutMs);
+        const paginator = await this.listSandboxes(labels, providerStates, pageSize(options));
+        const handles = [];
+        const excludedIds = new Set(options.excludeIds ?? []);
+        while (paginator.hasNext) {
+            const page = await awaitLookupOperation(paginator.nextItems(), deadline, "listing matching E2B sandboxes");
+            for (const info of page) {
+                if (matchesState(info.state, states) && !excludedIds.has(info.sandboxId)) {
+                    handles.push(this.registerInfo(info, options));
+                }
+            }
+        }
+        return handles;
     }
     async countByLabels(labels, options = {}) {
         const maxCount = options.maxCount === undefined
@@ -62,100 +110,100 @@ export class E2BSandboxRuntime {
             return 0;
         }
         const states = options.states === undefined ? ["STARTED"] : options.states;
-        const cap = Number.isFinite(maxCount) ? maxCount : undefined;
-        const handles = await this.collectByLabels(labels, states, cap);
-        return handles.length;
-    }
-    /**
-     * Drain the E2B sandbox list (server-side metadata-filtered), keep the ones
-     * matching `states`, and stop once `cap` handles are collected. Returns `[]`
-     * when the provider build lacks server-side label search — an EXPLICIT
-     * warm-lease-degrades-to-cold gate, not a silent behavior change.
-     */
-    async collectByLabels(labels, states, cap) {
-        const statics = await this.statics();
-        if (typeof statics.list !== "function") {
-            return [];
+        const providerStates = toE2BStates(states);
+        if (providerStates?.length === 0) {
+            return 0;
         }
-        const query = serializeMetadataQuery(labels);
-        const paginator = statics.list({
-            apiKey: this.apiKey,
-            ...(query ? { query: { metadata: query } } : {}),
-        });
-        const handles = [];
+        const deadline = lookupDeadline(options.timeoutMs);
+        const paginator = await this.listSandboxes(labels, providerStates, pageSize(options));
+        let count = 0;
         while (paginator.hasNext) {
-            const page = await paginator.nextItems();
+            const page = await awaitLookupOperation(paginator.nextItems(), deadline, "counting matching E2B sandboxes");
             for (const info of page) {
                 if (!matchesState(info.state, states)) {
                     continue;
                 }
-                handles.push(handleFromE2BInfo(info));
-                if (cap !== undefined && handles.length >= cap) {
-                    return handles;
+                count += 1;
+                if (count >= maxCount) {
+                    return count;
                 }
             }
         }
-        return handles;
+        return count;
     }
     async launch(options = {}) {
         const statics = await this.statics();
+        const name = options.name?.trim() || options.label?.trim();
         const metadata = {
             ...(options.labels ?? {}),
-            ...(options.name ? { name: options.name } : {}),
+            ...(name ? { name } : {}),
         };
-        const timeoutMs = options.createTimeoutSeconds
-            ? options.createTimeoutSeconds * 1000
+        const requestTimeoutMs = options.createTimeoutSeconds && options.createTimeoutSeconds > 0
+            ? Math.ceil(options.createTimeoutSeconds * 1000)
             : this.createTimeoutMs;
         const sandbox = await statics.create(this.template, {
             apiKey: this.apiKey,
-            ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+            requestTimeoutMs,
+            timeoutMs: this.sandboxLifetimeMs,
+            ...(hasEntries(metadata) ? { metadata } : {}),
             ...(hasEntries(options.env) ? { envs: options.env } : {}),
-            timeoutMs,
         });
-        this.sandboxes.set(sandbox.sandboxId, sandbox);
-        return { id: sandbox.sandboxId, state: "STARTED" };
-    }
-    async launchDetached(options = {}) {
-        // E2B sandboxes persist server-side the instant create() returns and are
-        // re-attachable by id via Sandbox.connect — so a "detached" launch is just
-        // launch. This is what lets a short-lived request context return before
-        // the run finishes and a later tick reconnect, instead of holding a
-        // request open until it hits a gateway timeout.
-        return this.launch(options);
+        return this.registerSandbox(sandbox, {
+            owned: true,
+            workdir: options.workdir,
+        });
     }
     async getById(id, options = {}) {
-        const sandbox = await this.connectSandbox(id);
-        if (!sandbox) {
-            return null;
+        const statics = await this.statics();
+        let info;
+        try {
+            info = await statics.getInfo(id, { apiKey: this.apiKey });
+        }
+        catch (error) {
+            if (isSandboxNotFound(error)) {
+                return null;
+            }
+            throw error;
         }
-        // Sandbox.connect only succeeds against a running microVM; a paused/killed
-        // one throws NotFound (→ null above). So a resolved handle is "STARTED".
-        const handle = { id: sandbox.sandboxId, state: "STARTED" };
         const states = options.states === undefined ? null : options.states;
-        return matchesState("running", states) ? handle : null;
-    }
-    async uploadBundle(handle, options) {
-        const sandbox = await this.requireSandbox(handle);
-        for (const file of options.files) {
-            const data = typeof file.source === "string" ? file.source : toArrayBuffer(file.source);
-            await sandbox.files.write(file.destination, data);
+        if (!matchesState(info.state, states)) {
+            return null;
         }
+        return this.registerInfo(info, options);
+    }
+    attachSandbox(sandbox, options = {}) {
+        return this.registerSandbox(sandbox, {
+            owned: options.owned ?? false,
+            homeDir: options.homeDir,
+            workdir: options.workdir,
+        });
+    }
+    async exec(handle, command, options = {}) {
+        const result = await this.runScript(handle, { command, ...options });
+        return {
+            output: result.output,
+            exitCode: result.exitCode ?? 0,
+        };
     }
     async runScript(handle, options) {
         const sandbox = await this.requireSandbox(handle);
-        // Synchronous foreground run: here options.timeoutMs IS the intended command
-        // lifetime (a bounded sync exec), so mapping it to `timeoutMs` is correct.
+        const explicitTimeoutMs = options.timeoutMs && options.timeoutMs > 0
+            ? options.timeoutMs
+            : undefined;
         try {
+            // Only an explicit caller timeout may push the sandbox past its
+            // configured lifetime; the implicit budget below must not.
+            await sandbox.setTimeout(Math.max(this.sandboxLifetimeMs, explicitTimeoutMs ?? 0));
             const result = await sandbox.commands.run(options.command, {
-                ...(options.timeoutMs && options.timeoutMs > 0 ? { timeoutMs: options.timeoutMs } : {}),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+                // Always send a timeout. E2B applies its own 60s command default when
+                // the field is omitted, which no other provider imposes and which the
+                // orchestrator does not expect: it omits `timeoutMs` on most execs, so
+                // an inherited 60s wall would kill long synchronous work on E2B alone.
+                timeoutMs: explicitTimeoutMs ?? this.syncRunBudgetMs,
                 ...(hasEntries(options.env) ? { envs: options.env } : {}),
             });
-            return {
-                output: combineOutput(result.stdout, result.stderr),
-                ...(result.stdout ? { stdout: result.stdout } : {}),
-                ...(result.stderr ? { stderr: result.stderr } : {}),
-                exitCode: typeof result.exitCode === "number" ? result.exitCode : null,
-            };
+            return commandResult(result);
         }
         catch (error) {
             const normalized = normalizeCommandError(error);
@@ -168,128 +216,407 @@ export class E2BSandboxRuntime {
     async startScript(handle, options) {
         const sandbox = await this.requireSandbox(handle);
         const sessionId = options.sessionId ?? `run-${handle.id}-${Date.now()}`;
-        const dir = scriptRunDir(sessionId);
-        const outPath = `${dir}/out`;
-        const exitPath = `${dir}/exit`;
-        // Durable-file wrapper: capture combined stdout/stderr + the final exit code
-        // to files under /tmp so getScriptStatus/getScriptLogs survive disconnect
-        // and reconnect across poll ticks (mirrors Daytona's per-session redirect).
-        const wrapped = `mkdir -p ${shellSingleQuote(dir)}; ` +
-            `{ ${options.command}\n} > ${shellSingleQuote(outPath)} 2>&1; ` +
-            `echo $? > ${shellSingleQuote(exitPath)}`;
-        // Keep the microVM alive for the whole run, independent of the submit call.
-        await sandbox.setTimeout(this.runBudgetMs);
-        // The critical distinction: command LIFETIME is the run budget
-        // (`timeoutMs`), while the caller's short `options.timeoutMs` bounds only
-        // the submit HTTP request (`requestTimeoutMs`). A naive
-        // `timeoutMs: options.timeoutMs` would kill every run the moment the
-        // submit deadline elapsed.
-        const started = await sandbox.commands.run(wrapped, {
-            background: true,
-            timeoutMs: this.runBudgetMs,
-            ...(options.timeoutMs && options.timeoutMs > 0 ? { requestTimeoutMs: options.timeoutMs } : {}),
-            ...(hasEntries(options.env) ? { envs: options.env } : {}),
+        const paths = scriptRunPaths(sessionId);
+        const fingerprint = asyncRequestFingerprint(options);
+        const admissionKey = `${handle.id}\0${paths.sessionToken}`;
+        const known = this.asyncAdmissions.get(admissionKey);
+        if (known) {
+            if (known.fingerprint !== fingerprint) {
+                throw asyncSessionConflict(sessionId);
+            }
+            await this.killDuplicateProcesses(sandbox, paths.sessionToken, fingerprint, known.pid);
+            return { sessionId, commandId: String(known.pid), reconciled: true };
+        }
+        // mkdir is the atomic admission claim. An existing directory is immutable:
+        // retries reconcile its durable request/process identity and never erase it
+        // or submit a second copy.
+        const claim = await this.runScript(handle, {
+            command: [
+                "# AGENTWORKFORCE_E2B_ASYNC_CLAIM",
+                `mkdir -p ${shellSingleQuote(paths.root)} || exit $?`,
+                `if mkdir ${shellSingleQuote(paths.dir)} 2>/dev/null; then`,
+                `  printf '%s\\n' ${shellSingleQuote(fingerprint)} > ${shellSingleQuote(paths.requestTmp)} &&`,
+                `  mv ${shellSingleQuote(paths.requestTmp)} ${shellSingleQuote(paths.request)} &&`,
+                "  printf '%s\\n' created",
+                "else",
+                "  printf '%s\\n' existing",
+                "fi",
+            ].join("\n"),
+            cwd: options.cwd,
+            env: options.env,
+            timeoutMs: 30_000,
         });
-        return { sessionId, commandId: String(started.pid) };
+        if (claim.exitCode !== 0) {
+            throw new Error(`Failed to claim E2B async session ${sessionId}: ${claim.output || "claim failed"}`);
+        }
+        const claimState = claim.stdout?.trim() ?? claim.output.trim();
+        if (claimState === "existing") {
+            const reconciled = await this.reconcileExistingAdmission(sandbox, sessionId, paths, fingerprint);
+            this.asyncAdmissions.set(admissionKey, reconciled);
+            return { sessionId, commandId: String(reconciled.pid), reconciled: true };
+        }
+        if (claimState !== "created") {
+            throw new Error(`E2B async session ${sessionId} returned an invalid claim result`);
+        }
+        const wrapped = [
+            `printf '%s\\n%s\\n' "$$" ${shellSingleQuote(fingerprint)} > ${shellSingleQuote(paths.admissionTmp)}`,
+            `mv ${shellSingleQuote(paths.admissionTmp)} ${shellSingleQuote(paths.admission)}`,
+            "{",
+            options.command,
+            `} > ${shellSingleQuote(paths.output)} 2>&1`,
+            "e2b_run_status=$?",
+            `printf '%s\\n' "$e2b_run_status" > ${shellSingleQuote(paths.exitTmp)}`,
+            `mv ${shellSingleQuote(paths.exitTmp)} ${shellSingleQuote(paths.exit)}`,
+            'exit "$e2b_run_status"',
+        ].join("\n");
+        await sandbox.setTimeout(Math.max(this.sandboxLifetimeMs, this.runBudgetMs));
+        try {
+            const started = await sandbox.commands.run(wrapped, {
+                background: true,
+                timeoutMs: this.runBudgetMs,
+                ...(options.timeoutMs && options.timeoutMs > 0
+                    ? { requestTimeoutMs: options.timeoutMs }
+                    : {}),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+                envs: {
+                    ...(options.env ?? {}),
+                    [ASYNC_SESSION_ENV]: paths.sessionToken,
+                    [ASYNC_REQUEST_ENV]: fingerprint,
+                },
+            });
+            if (!Number.isInteger(started.pid) || started.pid <= 0) {
+                throw new Error("E2B async command did not return a process id");
+            }
+            this.asyncAdmissions.set(admissionKey, { fingerprint, pid: started.pid });
+            return { sessionId, commandId: String(started.pid) };
+        }
+        catch (error) {
+            if (isOutcomeUnknownAdmissionError(error)) {
+                const reconciled = await this.reconcileOutcomeUnknownAdmission(sandbox, paths, fingerprint);
+                if (reconciled) {
+                    this.asyncAdmissions.set(admissionKey, reconciled);
+                    return {
+                        sessionId,
+                        commandId: String(reconciled.pid),
+                        reconciled: true,
+                    };
+                }
+            }
+            throw error;
+        }
     }
-    async getScriptStatus(handle, sessionId, _commandId) {
+    async getScriptStatus(handle, sessionId, commandId) {
         const sandbox = await this.requireSandbox(handle);
-        const exitPath = `${scriptRunDir(sessionId)}/exit`;
-        // Durable exit file is the source of truth: empty/missing → still running.
-        const raw = await this.readFileBestEffort(sandbox, exitPath, 64);
-        const trimmed = raw.trim();
-        if (!trimmed) {
+        const paths = scriptRunPaths(sessionId);
+        const firstExit = parseShellExitCode(await this.readOptionalTextFile(sandbox, paths.exit) ?? "");
+        if (firstExit !== null) {
+            return { exitCode: firstExit };
+        }
+        const pid = parseProcessId(commandId);
+        if (pid === null) {
+            throw new Error(`Invalid E2B async command id "${commandId}"`);
+        }
+        const processes = await sandbox.commands.list();
+        if (processes.some((process) => isSessionProcess(process, paths.sessionToken, pid))) {
             return { exitCode: null };
         }
-        const parsed = Number.parseInt(trimmed, 10);
-        return { exitCode: Number.isFinite(parsed) ? parsed : null };
+        // Close the race where the process exits after list() but before its
+        // wrapper atomically publishes the exit sidecar.
+        const finalExit = parseShellExitCode(await this.readOptionalTextFile(sandbox, paths.exit) ?? "");
+        return {
+            exitCode: finalExit ?? E2B_ASYNC_PROCESS_LOST_EXIT_CODE,
+        };
     }
     async getScriptLogs(handle, sessionId, commandId) {
         const sandbox = await this.requireSandbox(handle);
-        const outPath = `${scriptRunDir(sessionId)}/out`;
-        const output = await this.readFileBestEffort(sandbox, outPath, SCRIPT_LOG_READ_MAX_BYTES);
-        // exitCode:null — status is the source of truth for the exit code (matches
-        // Daytona/Local getScriptLogs).
+        const output = await this.readBoundedFile(sandbox, scriptRunPaths(sessionId).output, SCRIPT_LOG_READ_MAX_BYTES);
         return { output, exitCode: null, cmdId: commandId };
     }
+    startExec(handle, command, options = {}) {
+        return this.startScript(handle, {
+            command,
+            cwd: options.cwd,
+            env: options.env,
+            timeoutMs: options.timeoutMs,
+            sessionId: options.sessionId,
+            suppressInputEcho: true,
+        });
+    }
+    getExecStatus(handle, sessionId, commandId) {
+        return this.getScriptStatus(handle, sessionId, commandId);
+    }
+    async getExecLogs(handle, sessionId, commandId) {
+        const status = await this.getScriptStatus(handle, sessionId, commandId);
+        if (status.exitCode === null) {
+            throw new Error(`E2B async command "${commandId}" is still running`);
+        }
+        const logs = await this.getScriptLogs(handle, sessionId, commandId);
+        return { output: logs.output, exitCode: status.exitCode };
+    }
+    async uploadFile(handle, source, destination) {
+        const sandbox = await this.requireSandbox(handle);
+        const bytes = typeof source === "string"
+            ? await import("node:fs/promises").then((fs) => fs.readFile(source))
+            : source;
+        await sandbox.files.write(destination, toArrayBuffer(bytes));
+    }
+    async uploadBundle(handle, options) {
+        for (const file of options.files) {
+            await this.uploadFile(handle, file.source, file.destination);
+        }
+        const destinations = options.files.map((file) => file.destination);
+        if (options.manifest !== undefined) {
+            const manifestPath = options.manifestPath ?? "/workspace/manifest.json";
+            await this.uploadFile(handle, Buffer.from(JSON.stringify(options.manifest, null, 2), "utf8"), manifestPath);
+            destinations.push(manifestPath);
+        }
+        await this.verifyUploadedBundleFiles(handle, destinations);
+    }
+    async downloadFile(handle, source, destination) {
+        const sandbox = await this.requireSandbox(handle);
+        const bytes = await sandbox.files.read(source, { format: "bytes" });
+        const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        if (destination) {
+            await import("node:fs/promises").then((fs) => fs.writeFile(destination, buffer));
+            return;
+        }
+        return buffer;
+    }
+    async getHomeDir(handle) {
+        if (handle.homeDir) {
+            return handle.homeDir;
+        }
+        const result = await this.runScript(handle, {
+            command: `printf '%s' "$HOME"`,
+            timeoutMs: 30_000,
+        });
+        const homeDir = result.exitCode === 0 ? result.stdout?.trim() ?? "" : "";
+        if (!homeDir) {
+            throw new Error(`Failed to resolve home directory for E2B sandbox "${handle.id}"`);
+        }
+        handle.homeDir = homeDir;
+        return homeDir;
+    }
+    async stop(handle) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry || !entry.owned) {
+            return;
+        }
+        const statics = await this.statics();
+        await statics.pause(handle.id, { apiKey: this.apiKey });
+        entry.sandbox = undefined;
+        entry.state = "paused";
+        handle.state = "STOPPED";
+    }
     async start(handle) {
-        // E2B pause/resume is a warm-reuse follow-up (see PR needs-key list); until
-        // then start is a no-op that returns the handle, matching Local's 501 no-op.
+        const entry = this.registrations.get(handle.id);
+        if (!entry || !entry.owned) {
+            return handle;
+        }
+        const statics = await this.statics();
+        const sandbox = await statics.connect(handle.id, {
+            apiKey: this.apiKey,
+            timeoutMs: this.sandboxLifetimeMs,
+        });
+        entry.sandbox = sandbox;
+        entry.state = "running";
+        handle.state = "STARTED";
         return handle;
     }
-    async stop(_handle) {
-        // No-op (see start): pause/resume lifecycle deferred to warm-reuse follow-up.
-    }
     async destroy(handle) {
-        const sandbox = await this.connectSandbox(handle.id);
-        this.sandboxes.delete(handle.id);
-        if (!sandbox) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry) {
+            return;
+        }
+        if (!entry.owned) {
+            this.registrations.delete(handle.id);
             return;
         }
-        await sandbox.kill();
+        const statics = await this.statics();
+        await statics.kill(handle.id, { apiKey: this.apiKey });
+        this.registrations.delete(handle.id);
     }
-    // --- internals ----------------------------------------------------------
     async statics() {
         if (this.injectedStatics) {
             return this.injectedStatics;
         }
         if (!this.staticsPromise) {
-            // Lazy — keeps `e2b` out of every non-E2B bundle and off the eager-import
-            // ban list.
             this.staticsPromise = import("e2b").then((mod) => mod.Sandbox);
         }
         return this.staticsPromise;
     }
+    async listSandboxes(labels, states, limit) {
+        const statics = await this.statics();
+        const query = {
+            ...(hasEntries(labels) ? { metadata: labels } : {}),
+            ...(states ? { state: states } : {}),
+        };
+        return statics.list({
+            apiKey: this.apiKey,
+            limit,
+            ...(hasEntries(query) ? { query } : {}),
+        });
+    }
+    registerInfo(info, options) {
+        const existing = this.registrations.get(info.sandboxId);
+        this.registrations.set(info.sandboxId, {
+            ...(existing?.sandbox ? { sandbox: existing.sandbox } : {}),
+            owned: options.owned ?? false,
+            state: info.state,
+        });
+        return {
+            ...handleFromE2BInfo(info),
+            ...(options.homeDir ? { homeDir: options.homeDir } : {}),
+            ...(options.workdir ? { workdir: options.workdir } : {}),
+        };
+    }
+    registerSandbox(sandbox, options) {
+        this.registrations.set(sandbox.sandboxId, {
+            sandbox,
+            owned: options.owned,
+            state: "running",
+        });
+        return {
+            id: sandbox.sandboxId,
+            state: "STARTED",
+            ...(options.homeDir ? { homeDir: options.homeDir } : {}),
+            ...(options.workdir ? { workdir: options.workdir } : {}),
+        };
+    }
     async requireSandbox(handle) {
-        const sandbox = await this.connectSandbox(handle.id);
-        if (!sandbox) {
-            throw new Error(`E2B sandbox "${handle.id}" is no longer available`);
+        const registered = this.registrations.get(handle.id);
+        if (registered?.state === "paused") {
+            throw new Error(`E2B sandbox "${handle.id}" is paused; call start() before using it`);
         }
-        return sandbox;
-    }
-    async connectSandbox(id) {
-        const cached = this.sandboxes.get(id);
-        if (cached) {
-            return cached;
+        if (registered?.sandbox) {
+            return registered.sandbox;
         }
         const statics = await this.statics();
         try {
-            const sandbox = await statics.connect(id, { apiKey: this.apiKey });
-            this.sandboxes.set(id, sandbox);
+            const sandbox = await statics.connect(handle.id, {
+                apiKey: this.apiKey,
+                timeoutMs: this.sandboxLifetimeMs,
+            });
+            this.registrations.set(handle.id, {
+                sandbox,
+                owned: registered?.owned ?? false,
+                state: "running",
+            });
             return sandbox;
         }
         catch (error) {
             if (isSandboxNotFound(error)) {
-                return null;
+                throw new Error(`E2B sandbox "${handle.id}" is no longer available`, { cause: error });
             }
             throw error;
         }
     }
-    async readFileBestEffort(sandbox, path, maxBytes) {
-        // Read via a bounded foreground `tail -c` rather than files.read: it returns
-        // "" (never throws) when the file is still absent, and caps the bytes pulled
-        // back into the Worker.
+    async verifyUploadedBundleFiles(handle, destinations) {
+        if (destinations.length === 0) {
+            return;
+        }
+        const result = await this.runScript(handle, {
+            command: destinations
+                .map((destination) => `test -f ${shellSingleQuote(destination)}`)
+                .join(" && "),
+            timeoutMs: 30_000,
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(`Failed to verify uploaded E2B bundle files: ${result.output || "remote file check failed"}`);
+        }
+    }
+    async reconcileExistingAdmission(sandbox, sessionId, paths, fingerprint) {
+        const recordedRequest = (await this.readOptionalTextFile(sandbox, paths.request))?.trim();
+        if (!recordedRequest) {
+            throw new Error(`E2B async session ${sessionId} is already claimed but has no authoritative request record`);
+        }
+        if (recordedRequest !== fingerprint) {
+            throw asyncSessionConflict(sessionId);
+        }
+        const recordedAdmission = parseAdmissionRecord(await this.readOptionalTextFile(sandbox, paths.admission));
+        if (recordedAdmission && recordedAdmission.fingerprint !== fingerprint) {
+            throw new Error(`E2B async session ${sessionId} has a mismatched admission record`);
+        }
+        const processes = matchingSessionProcesses(await sandbox.commands.list(), paths.sessionToken, fingerprint);
+        if (recordedAdmission) {
+            await this.killProcessesExcept(sandbox, processes, recordedAdmission.pid);
+            return recordedAdmission;
+        }
+        if (processes.length === 1) {
+            const admission = { fingerprint, pid: processes[0].pid };
+            await sandbox.files.write(paths.admission, `${admission.pid}\n${admission.fingerprint}\n`);
+            return admission;
+        }
+        if (processes.length > 1) {
+            await this.killProcessesExcept(sandbox, processes, null);
+        }
+        throw new Error(`E2B async session ${sessionId} is already claimed but admission cannot be proven`);
+    }
+    async reconcileOutcomeUnknownAdmission(sandbox, paths, fingerprint) {
+        const deadline = Date.now() + ADMISSION_RECONCILIATION_TIMEOUT_MS;
+        do {
+            const recorded = parseAdmissionRecord(await this.readOptionalTextFile(sandbox, paths.admission));
+            const processes = matchingSessionProcesses(await sandbox.commands.list(), paths.sessionToken, fingerprint);
+            if (recorded?.fingerprint === fingerprint) {
+                await this.killProcessesExcept(sandbox, processes, recorded.pid);
+                return recorded;
+            }
+            if (processes.length === 1) {
+                const admission = { fingerprint, pid: processes[0].pid };
+                await sandbox.files.write(paths.admission, `${admission.pid}\n${admission.fingerprint}\n`);
+                return admission;
+            }
+            if (processes.length > 1) {
+                await this.killProcessesExcept(sandbox, processes, null);
+                return null;
+            }
+            if (Date.now() < deadline) {
+                await delay(ADMISSION_RECONCILIATION_INTERVAL_MS);
+            }
+        } while (Date.now() < deadline);
+        return null;
+    }
+    async killDuplicateProcesses(sandbox, sessionToken, fingerprint, admittedPid) {
+        const matches = matchingSessionProcesses(await sandbox.commands.list(), sessionToken, fingerprint);
+        await this.killProcessesExcept(sandbox, matches, admittedPid);
+    }
+    async killProcessesExcept(sandbox, processes, admittedPid) {
+        for (const process of processes) {
+            if (process.pid !== admittedPid) {
+                await sandbox.commands.kill(process.pid);
+            }
+        }
+    }
+    async readOptionalTextFile(sandbox, path, requestTimeoutMs) {
         try {
-            const result = await sandbox.commands.run(`tail -c ${maxBytes} ${shellSingleQuote(path)} 2>/dev/null || true`);
-            return result.stdout ?? "";
+            return await sandbox.files.read(path, {
+                format: "text",
+                ...(requestTimeoutMs ? { requestTimeoutMs } : {}),
+            });
         }
-        catch {
-            return "";
+        catch (error) {
+            if (isFileNotFound(error)) {
+                return null;
+            }
+            throw error;
         }
     }
+    async readBoundedFile(sandbox, path, maxBytes, requestTimeoutMs) {
+        // Unlike `runScript`, this runs a fixed bounded `tail`, not caller work, so
+        // E2B's own command default is an appropriate wall when no cap is given.
+        const result = await sandbox.commands.run(`tail -c ${maxBytes} ${shellSingleQuote(path)} 2>/dev/null || true`, requestTimeoutMs
+            ? { timeoutMs: requestTimeoutMs, requestTimeoutMs }
+            : undefined);
+        return result.stdout ?? "";
+    }
 }
-// --- helpers --------------------------------------------------------------
-function serializeMetadataQuery(labels) {
-    const entries = Object.entries(labels).filter(([key]) => key.length > 0);
-    if (entries.length === 0) {
-        return "";
-    }
-    // e2b's metadata filter is a URL-encoded "k=v&k2=v2" string, not an object.
-    const params = new URLSearchParams();
-    for (const [key, value] of entries) {
-        params.append(key, value);
-    }
-    return params.toString();
+function commandResult(result) {
+    return {
+        output: combineOutput(result.stdout, result.stderr),
+        ...(result.stdout ? { stdout: result.stdout } : {}),
+        ...(result.stderr ? { stderr: result.stderr } : {}),
+        exitCode: typeof result.exitCode === "number" ? result.exitCode : null,
+    };
 }
 function handleFromE2BInfo(info) {
     return {
@@ -299,22 +626,49 @@ function handleFromE2BInfo(info) {
     };
 }
 function normalizeE2BState(state) {
-    // Map to the normalized vocabulary the delivery path reasons about (Daytona
-    // STARTED/STOPPED). A paused E2B sandbox is not cold-reusable in this PR
-    // (warm resume is the follow-up) so it reads as STOPPED and is excluded by the
-    // default ["STARTED"] filter → cold provisioning.
     return state === "running" ? "STARTED" : "STOPPED";
 }
+function normalizeRequestedState(state) {
+    const normalized = state.toUpperCase();
+    if (normalized === "RUNNING") {
+        return "STARTED";
+    }
+    if (normalized === "PAUSED") {
+        return "STOPPED";
+    }
+    return normalized;
+}
 function matchesState(state, states) {
     if (states === null) {
         return true;
     }
-    const normalized = normalizeE2BState(state ?? "running");
-    return states.includes(normalized);
+    if (!state) {
+        return false;
+    }
+    const actual = normalizeE2BState(state);
+    return states.some((candidate) => normalizeRequestedState(candidate) === actual);
+}
+function toE2BStates(states) {
+    if (states === null) {
+        return null;
+    }
+    const providerStates = new Set();
+    for (const state of states) {
+        const normalized = normalizeRequestedState(state);
+        if (normalized === "STARTED") {
+            providerStates.add("running");
+        }
+        else if (normalized === "STOPPED") {
+            providerStates.add("paused");
+        }
+    }
+    return [...providerStates];
 }
 function combineOutput(stdout, stderr) {
     if (stdout && stderr) {
-        return stdout.endsWith("\n") || stderr.startsWith("\n") ? `${stdout}${stderr}` : `${stdout}\n${stderr}`;
+        return stdout.endsWith("\n") || stderr.startsWith("\n")
+            ? `${stdout}${stderr}`
+            : `${stdout}\n${stderr}`;
     }
     return stdout || stderr || "";
 }
@@ -336,15 +690,46 @@ function normalizeCommandError(error) {
         exitCode: candidate.exitCode,
     };
 }
+function isOutcomeUnknownAdmissionError(error) {
+    const record = error && typeof error === "object"
+        ? error
+        : null;
+    const code = typeof record?.code === "string" ? record.code.toUpperCase() : "";
+    const name = typeof record?.name === "string" ? record.name : "";
+    const message = error instanceof Error
+        ? error.message
+        : typeof record?.message === "string"
+            ? record.message
+            : String(error);
+    return (code === "ECONNABORTED"
+        || code === "ETIMEDOUT"
+        || code === "ECONNRESET"
+        || name === "TimeoutError"
+        || /\btimed out\b/iu.test(message)
+        || /\bnetwork connection lost\b/iu.test(message)
+        || /\bsocket hang up\b/iu.test(message)
+        || /\bfetch failed\b/iu.test(message));
+}
 function isSandboxNotFound(error) {
     if (typeof error !== "object" || error === null) {
         return false;
     }
-    const name = error.name;
-    const message = error.message;
-    return (name === "NotFoundError" ||
-        name === "SandboxNotFoundError" ||
-        (typeof message === "string" && /not\s*found/i.test(message)));
+    const record = error;
+    return (record.name === "NotFoundError"
+        || record.name === "SandboxNotFoundError"
+        || record.status === 404
+        || record.statusCode === 404
+        || (typeof record.message === "string" && /not\s*found/i.test(record.message)));
+}
+function isFileNotFound(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const record = error;
+    return (record.name === "FileNotFoundError"
+        || record.status === 404
+        || record.statusCode === 404
+        || (typeof record.message === "string" && /file.*not\s*found|no such file/iu.test(record.message)));
 }
 function toArrayBuffer(buffer) {
     return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
@@ -352,9 +737,109 @@ function toArrayBuffer(buffer) {
 function hasEntries(record) {
     return !!record && Object.keys(record).length > 0;
 }
-function scriptRunDir(sessionId) {
-    const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, "_");
-    return `/tmp/e2b-run/${safe}`;
+function positiveDuration(value, fallback) {
+    return Number.isFinite(value) && value !== undefined && value > 0
+        ? Math.ceil(value)
+        : fallback;
+}
+function pageSize(options) {
+    const value = options.limit ?? options.pageSize ?? 10;
+    return Number.isFinite(value) && value > 0 ? Math.max(1, Math.floor(value)) : 10;
+}
+function lookupDeadline(timeoutMs) {
+    const normalized = positiveDuration(timeoutMs, DEFAULT_LOOKUP_TIMEOUT_MS);
+    return { endsAt: Date.now() + normalized, timeoutMs: normalized };
+}
+async function awaitLookupOperation(operation, deadline, description) {
+    const remainingMs = deadline.endsAt - Date.now();
+    if (remainingMs <= 0) {
+        throw new Error(`E2B sandbox lookup exceeded ${deadline.timeoutMs}ms while ${description}`);
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(`E2B sandbox lookup exceeded ${deadline.timeoutMs}ms while ${description}`));
+                }, remainingMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+function parseShellExitCode(value) {
+    const normalized = value.trim();
+    if (!/^\d{1,3}$/u.test(normalized)) {
+        return null;
+    }
+    const exitCode = Number(normalized);
+    return Number.isInteger(exitCode) && exitCode >= 0 && exitCode <= 255
+        ? exitCode
+        : null;
+}
+function parseProcessId(value) {
+    const normalized = value.trim();
+    if (!/^\d+$/u.test(normalized)) {
+        return null;
+    }
+    const pid = Number(normalized);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+function parseAdmissionRecord(value) {
+    if (value === null) {
+        return null;
+    }
+    const [rawPid, fingerprint, ...extra] = value.trim().split(/\s+/u);
+    const pid = parseProcessId(rawPid ?? "");
+    if (pid === null || !fingerprint || extra.length > 0 || !/^[a-f\d]{64}$/u.test(fingerprint)) {
+        return null;
+    }
+    return { fingerprint, pid };
+}
+function asyncRequestFingerprint(options) {
+    const env = Object.entries(options.env ?? {}).sort(([left], [right]) => left.localeCompare(right));
+    return createHash("sha256").update(JSON.stringify({
+        command: options.command,
+        cwd: options.cwd ?? null,
+        env,
+    })).digest("hex");
+}
+function asyncSessionConflict(sessionId) {
+    return new Error(`E2B async session ${sessionId} is already claimed by a different request`);
+}
+function matchingSessionProcesses(processes, sessionToken, fingerprint) {
+    return processes.filter((process) => (process.envs?.[ASYNC_SESSION_ENV] === sessionToken
+        && process.envs?.[ASYNC_REQUEST_ENV] === fingerprint));
+}
+function isSessionProcess(process, sessionToken, pid) {
+    return process.pid === pid && process.envs?.[ASYNC_SESSION_ENV] === sessionToken;
+}
+function delay(timeoutMs) {
+    return new Promise((resolve) => setTimeout(resolve, timeoutMs));
+}
+function scriptRunPaths(sessionId) {
+    // Base64url is filesystem-safe and collision-free for the original UTF-8
+    // bytes, unlike replacing punctuation with underscores.
+    const safe = Buffer.from(sessionId, "utf8").toString("base64url") || "empty";
+    const root = "/tmp/e2b-run";
+    const dir = `${root}/${safe}`;
+    return {
+        root,
+        dir,
+        output: `${dir}/out`,
+        exit: `${dir}/exit`,
+        exitTmp: `${dir}/exit.tmp`,
+        admission: `${dir}/admission`,
+        admissionTmp: `${dir}/admission.tmp`,
+        request: `${dir}/request`,
+        requestTmp: `${dir}/request.tmp`,
+        sessionToken: safe,
+    };
 }
 function shellSingleQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;