@sema-agent/server 1.185.0

package/dist/plugins/remote-env-e2b.js

@@ -0,0 +1,931 @@
+import path from "node:path";
+import { Sandbox, CommandExitError, FileType } from "e2b";
+import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { BackgroundShellManager } from "./background-shell-support.js";
+const PROVIDER = "e2b";
+const DEFAULT_MOUNT_PATH = "/home/user";
+const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+const E2B_SANDBOX_MAX_MS = Math.max(60_000, Math.floor(Number(process.env.E2B_SANDBOX_MAX_MS ?? "")) || 3_600_000);
+const DEFAULT_RPC_TIMEOUT_MS = 60_000;
+const DEFAULT_LIVENESS_MS = 120_000;
+const DEFAULT_DATA_TIMEOUT_MS = 5 * 60_000;
+const E2B_BG_MAX_CONCURRENT = Math.max(1, Math.floor(Number(process.env.E2B_BG_MAX_CONCURRENT ?? "")) || 8);
+const E2B_BG_DEFAULT_TIMEOUT_SEC = Math.max(1, Math.floor(Number(process.env.E2B_BG_DEFAULT_TIMEOUT_SEC ?? "")) || 300);
+const E2B_BG_MAX_TIMEOUT_SEC = Math.max(E2B_BG_DEFAULT_TIMEOUT_SEC, Math.floor(Number(process.env.E2B_BG_MAX_TIMEOUT_SEC ?? "")) || 1800);
+const E2B_BG_PROVIDER_BACKSTOP_PAD_SEC = 30;
+const ok = (value) => ({ ok: true, value });
+export class RemoteContainerExecutionEnv {
+    cwd;
+    cfg;
+    sandboxApi;
+    sbx;
+    keepAlive;
+    handle;
+    destroyed = false;
+    connecting;
+    activeCommands = 0;
+    paused = false;
+    constructor(config, deps = {}) {
+        this.cfg = {
+            ...config,
+            mountPath: config.mountPath ?? DEFAULT_MOUNT_PATH,
+            timeoutMs: Math.min(config.timeoutMs ?? DEFAULT_TIMEOUT_MS, E2B_SANDBOX_MAX_MS),
+            allowInternetAccess: config.allowInternetAccess ?? true,
+            rpcTimeoutMs: config.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+            livenessMs: config.livenessMs ?? DEFAULT_LIVENESS_MS,
+            dataTimeoutMs: config.dataTimeoutMs ?? DEFAULT_DATA_TIMEOUT_MS,
+        };
+        this.cwd = this.cfg.mountPath;
+        this.sandboxApi = deps.sandboxApi ?? Sandbox;
+    }
+    capabilities = { isolation: true, suspendable: true };
+    workspaceHandle() {
+        if (!this.handle) {
+            throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");
+        }
+        return this.handle;
+    }
+    async getHost(port) {
+        const conn = await this.ensureConnected();
+        return conn.ok ? conn.value.getHost(port) : undefined;
+    }
+    async startBackground(command) {
+        const conn = await this.ensureConnected();
+        if (conn.ok)
+            await conn.value.commands.run(command, { background: true });
+    }
+    async connect(config) {
+        if (config?.snapshotId) {
+            return this.resumeVM(config.snapshotId, config.abortSignal ? { abortSignal: config.abortSignal } : undefined);
+        }
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (this.paused)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resumeVM(snapshotId) before use") };
+        if (this.sbx)
+            return ok(this.workspaceHandle());
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.doConnect(config);
+        const r = await this.connecting;
+        if (!r.ok)
+            this.connecting = undefined;
+        return r;
+    }
+    async doConnect(config) {
+        try {
+            const sbx = await this.rpc("sandbox.create", () => this.sandboxApi.create({
+                ...(this.cfg.template ? { template: this.cfg.template } : {}),
+                apiKey: this.cfg.apiKey,
+                timeoutMs: this.cfg.timeoutMs,
+                allowInternetAccess: this.cfg.allowInternetAccess,
+                ...(this.cfg.metadata ? { metadata: this.cfg.metadata } : {}),
+                ...(this.cfg.sandboxEnv && Object.keys(this.cfg.sandboxEnv).length > 0 ? { envs: this.cfg.sandboxEnv } : {}),
+            }), config?.abortSignal, this.cfg.dataTimeoutMs);
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
+            }
+            this.sbx = sbx;
+            this.paused = false;
+            this.startKeepAlive();
+            this.cfg.logger?.info?.("remote_env_connect", { sandboxId: sbx.sandboxId });
+            this.handle = {
+                sandboxId: sbx.sandboxId,
+                provider: PROVIDER,
+                mountPath: this.cfg.mountPath,
+                sessionToken: sbx.sandboxId,
+            };
+            if (config?.secrets?.length) {
+                this.cfg.logger?.warn?.("remote-env: connect secrets are not injected in v1 (control-plane resolution deferred)", {
+                    count: config.secrets.length,
+                });
+            }
+            this.cfg.metrics?.inc("remote_env_connect_total", { provider: PROVIDER, result: "ok" });
+            return ok(this.handle);
+        }
+        catch (e) {
+            this.cfg.metrics?.inc("remote_env_connect_total", { provider: PROVIDER, result: "error" });
+            return { ok: false, error: this.remoteError(e, "connect_failed") };
+        }
+    }
+    async suspendVM(options) {
+        const sbx = this.sbx;
+        if (!sbx)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "suspendVM before connect()") };
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
+        if (this.activeCommands > 0) {
+            return { ok: false, error: new RemoteExecutionError("command_in_flight", `suspendVM refused: ${this.activeCommands} command(s) in flight`) };
+        }
+        try {
+            await this.rpc("sandbox.pause", (signal) => sbx.pause({ signal }), options?.abortSignal, this.cfg.dataTimeoutMs);
+            if (this.destroyed) {
+                await sbx.kill().catch((e) => this.cfg.logger?.warn?.("remote-env: suspend-recheck kill failed (snapshot may orphan)", { error: errMsg(e) }));
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during suspend") };
+            }
+            this.paused = true;
+            this.connecting = undefined;
+            this.cfg.metrics?.inc("remote_env_suspend_total", { provider: PROVIDER, result: "ok" });
+            this.cfg.logger?.info?.("remote_env_suspend", { snapshotId: sbx.sandboxId });
+            return ok(sbx.sandboxId);
+        }
+        catch (e) {
+            this.cfg.metrics?.inc("remote_env_suspend_total", { provider: PROVIDER, result: "error" });
+            return { ok: false, error: this.remoteError(e, options?.abortSignal?.aborted ? "aborted" : "unknown") };
+        }
+    }
+    async resumeVM(snapshotId, options) {
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
+        if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
+            return ok(this.workspaceHandle());
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.doResumeVM(snapshotId, options);
+        const r = await this.connecting;
+        if (!r.ok)
+            this.connecting = undefined;
+        return r;
+    }
+    async doResumeVM(snapshotId, options) {
+        try {
+            const sbx = await this.rpc("sandbox.connect", (signal) => this.sandboxApi.connect(snapshotId, { apiKey: this.cfg.apiKey, timeoutMs: this.cfg.timeoutMs, signal }), options?.abortSignal, this.cfg.dataTimeoutMs);
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
+            }
+            this.sbx = sbx;
+            this.paused = false;
+            this.startKeepAlive();
+            this.cfg.logger?.info?.("remote_env_resume", { requested: snapshotId, connected: sbx.sandboxId });
+            this.handle = { sandboxId: sbx.sandboxId, provider: PROVIDER, mountPath: this.cfg.mountPath, snapshotId, sessionToken: sbx.sandboxId };
+            this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "ok" });
+            return ok(this.handle);
+        }
+        catch (e) {
+            this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "error" });
+            return { ok: false, error: this.remoteError(e, options?.abortSignal?.aborted ? "aborted" : "connect_failed") };
+        }
+    }
+    async reconnect(_sessionToken) {
+        return { ok: false, error: new RemoteExecutionError("unknown", "reconnect is deferred to v2 (v1.5 always snapshots → use resumeVM)") };
+    }
+    async postResumeInit() {
+        const sbx = this.sbx;
+        if (!sbx)
+            return { ok: false, error: new RemoteExecutionError("post_resume_failed", "postResumeInit before resume") };
+        try {
+            if (!(await this.rpc("sandbox.isRunning", () => sbx.isRunning()))) {
+                return { ok: false, error: new RemoteExecutionError("post_resume_failed", "resumed VM is not running") };
+            }
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: this.remoteError(e, "post_resume_failed") };
+        }
+    }
+    startKeepAlive() {
+        this.stopKeepAlive();
+        const everyMs = Math.max(30_000, Math.floor(this.cfg.timeoutMs * 0.8));
+        this.keepAlive = setInterval(() => {
+            if (this.destroyed || this.paused || !this.sbx)
+                return;
+            void this.sbx.setTimeout(this.cfg.timeoutMs).catch((e) => this.cfg.logger?.warn?.("remote_env_keepalive_failed", { error: errMsg(e) }));
+        }, everyMs);
+        this.keepAlive.unref?.();
+    }
+    stopKeepAlive() {
+        if (this.keepAlive) {
+            clearInterval(this.keepAlive);
+            this.keepAlive = undefined;
+        }
+    }
+    async destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.connecting = undefined;
+        this.stopKeepAlive();
+        await this.disposeBackgroundShells();
+        const sbx = this.sbx;
+        this.sbx = undefined;
+        if (!sbx)
+            return;
+        const startedAt = Date.now();
+        try {
+            await this.rpc("sandbox.kill", () => sbx.kill());
+            this.cfg.metrics?.inc("remote_env_destroy_total", { provider: PROVIDER, result: "ok" });
+            this.cfg.logger?.info?.("remote_env_destroy", { sandboxId: sbx.sandboxId, ms: Date.now() - startedAt });
+        }
+        catch (e) {
+            this.cfg.metrics?.inc("remote_env_destroy_total", { provider: PROVIDER, result: "error" });
+            this.cfg.logger?.warn?.("remote_env_destroy_failed", { sandboxId: sbx.sandboxId, ms: Date.now() - startedAt, error: errMsg(e) });
+        }
+    }
+    async cleanup() {
+        await this.destroy();
+    }
+    async exec(command, options) {
+        if (options?.abortSignal?.aborted)
+            return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
+        const conn = await this.ensureConnected();
+        if (!conn.ok)
+            return { ok: false, error: new ExecutionError("shell_unavailable", `remote connect failed: ${conn.error.message}`, conn.error) };
+        const sbx = conn.value;
+        this.activeCommands++;
+        const detachSignal = options?.detachSignal;
+        const tee = detachSignal
+            ? {
+                stdout: { tail: new RollingTailBuffer(), total: 0, cursor: 0 },
+                stderr: { tail: new RollingTailBuffer(), total: 0, cursor: 0 },
+            }
+            : undefined;
+        let detached = false;
+        const teePush = (s, d) => {
+            const b = Buffer.from(d, "utf8");
+            s.tail.push(b);
+            s.total += b.length;
+        };
+        let lastProgress = Date.now();
+        let handle;
+        try {
+            handle = await this.rpc("commands.run", () => sbx.commands.run(command, {
+                background: true,
+                cwd: this.resolve(options?.cwd ?? this.cwd),
+                ...(options?.env ? { envs: options.env } : {}),
+                timeoutMs: tee
+                    ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
+                    : this.commandTimeoutMs(options?.timeout),
+                onStdout: (d) => {
+                    if (tee)
+                        teePush(tee.stdout, d);
+                    if (!detached) {
+                        lastProgress = Date.now();
+                        options?.onStdout?.(d);
+                    }
+                },
+                onStderr: (d) => {
+                    if (tee)
+                        teePush(tee.stderr, d);
+                    if (!detached) {
+                        lastProgress = Date.now();
+                        options?.onStderr?.(d);
+                    }
+                },
+            }), options?.abortSignal, this.cfg.livenessMs);
+        }
+        catch (e) {
+            this.activeCommands--;
+            return { ok: false, error: this.execError(e, options?.abortSignal) };
+        }
+        const onAbort = () => { if (!detached)
+            void handle.kill().catch(() => { }); };
+        if (options?.abortSignal) {
+            if (options.abortSignal.aborted)
+                onAbort();
+            else
+                options.abortSignal.addEventListener("abort", onAbort, { once: true });
+        }
+        const waitP = handle.wait();
+        let fgResolved = false;
+        const markResolved = () => { fgResolved = true; };
+        waitP.then(markResolved, markResolved);
+        let fgSettled = false;
+        let adoptedShellId;
+        let onDetach;
+        const detachedP = detachSignal && tee
+            ? new Promise((res) => {
+                onDetach = () => {
+                    if (detached || fgSettled || fgResolved || options?.abortSignal?.aborted)
+                        return;
+                    const adopted = this.bgManager.adoptSync((ctx) => {
+                        waitP
+                            .then((r) => ctx.onTerminal(false, r.exitCode))
+                            .catch((e) => {
+                            if (e instanceof CommandExitError)
+                                ctx.onTerminal(false, e.exitCode);
+                            else
+                                ctx.onTerminal(true);
+                        });
+                        return { handle, stdout: tee.stdout, stderr: tee.stderr };
+                    });
+                    if (!adopted)
+                        return;
+                    adoptedShellId = adopted.shellId;
+                    detached = true;
+                    res("detached");
+                };
+                if (detachSignal.aborted)
+                    onDetach();
+                else
+                    detachSignal.addEventListener("abort", onDetach, { once: true });
+            })
+            : undefined;
+        try {
+            const fg = this.waitWithLiveness(handle, () => lastProgress, {
+                waitP,
+                disarmed: () => detached,
+                ...(tee ? { wallMs: this.commandTimeoutMs(options?.timeout) } : {}),
+            });
+            const winner = await (detachedP ? Promise.race([fg, detachedP]) : fg);
+            if (winner === "detached") {
+                const o = tee.stdout.tail.result();
+                const e = tee.stderr.tail.result();
+                return ok({
+                    stdout: markTruncated(o.text, o.droppedBytes),
+                    stderr: markTruncated(e.text, e.droppedBytes),
+                    exitCode: 0,
+                    detached: { shellId: adoptedShellId },
+                });
+            }
+            if (options?.abortSignal?.aborted && !detached) {
+                return { ok: false, error: new ExecutionError("aborted", "exec aborted (remote process killed)") };
+            }
+            return ok({ stdout: winner.stdout, stderr: winner.stderr, exitCode: winner.exitCode });
+        }
+        catch (e) {
+            if (options?.abortSignal?.aborted && !detached) {
+                return { ok: false, error: this.execError(e, options.abortSignal) };
+            }
+            if (e instanceof CommandExitError) {
+                return ok({ stdout: e.stdout, stderr: e.stderr, exitCode: e.exitCode });
+            }
+            return { ok: false, error: this.execError(e, options?.abortSignal) };
+        }
+        finally {
+            fgSettled = true;
+            if (onDetach && detachSignal)
+                detachSignal.removeEventListener("abort", onDetach);
+            this.activeCommands--;
+            options?.abortSignal?.removeEventListener("abort", onAbort);
+        }
+    }
+    async *execStream(command, options) {
+        const conn = await this.ensureConnected();
+        if (!conn.ok)
+            throw conn.error;
+        const sbx = conn.value;
+        const queue = [];
+        let finished = false;
+        let failure;
+        let exitCode = 0;
+        let wake;
+        const signalReady = () => {
+            const w = wake;
+            wake = undefined;
+            w?.();
+        };
+        let bytes = 0;
+        const cap = options?.maxOutputBytes;
+        const push = (type, data) => {
+            if (finished)
+                return;
+            bytes += Buffer.byteLength(data, "utf8");
+            queue.push({ type, data });
+            signalReady();
+        };
+        this.activeCommands++;
+        let handle;
+        try {
+            handle = await this.rpc("commands.run", () => sbx.commands.run(command, {
+                background: true,
+                cwd: this.resolve(options?.cwd ?? this.cwd),
+                ...(options?.env ? { envs: options.env } : {}),
+                timeoutMs: this.commandTimeoutMs(options?.timeout),
+                onStdout: (d) => push("stdout", d),
+                onStderr: (d) => push("stderr", d),
+            }), options?.signal, this.cfg.livenessMs);
+        }
+        catch (e) {
+            this.activeCommands--;
+            throw this.remoteError(e, "connect_failed");
+        }
+        handle
+            .wait()
+            .then((r) => {
+            if (finished)
+                return;
+            exitCode = r.exitCode;
+            finished = true;
+            signalReady();
+        })
+            .catch((e) => {
+            if (finished)
+                return;
+            if (e instanceof CommandExitError) {
+                exitCode = e.exitCode;
+            }
+            else {
+                failure = this.remoteError(e, "unknown");
+            }
+            finished = true;
+            signalReady();
+        });
+        const onAbort = () => {
+            if (finished)
+                return;
+            failure = new RemoteExecutionError("aborted", "execStream aborted");
+            finished = true;
+            void handle.kill().catch(() => { });
+            signalReady();
+        };
+        if (options?.signal) {
+            if (options.signal.aborted)
+                onAbort();
+            else
+                options.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        let head = 0;
+        const drainQueued = function* () {
+            while (head < queue.length) {
+                const chunk = queue[head++];
+                yield chunk;
+                if (cap != null && bytes > cap) {
+                    finished = true;
+                    void handle.kill().catch(() => { });
+                    throw new RemoteExecutionError("unknown", `execStream output exceeded maxOutputBytes=${cap}`);
+                }
+            }
+            queue.length = 0;
+            head = 0;
+        };
+        try {
+            while (true) {
+                yield* drainQueued();
+                if (finished)
+                    break;
+                const next = new Promise((resolve) => {
+                    wake = resolve;
+                });
+                const idleMs = options?.readTimeoutMs ?? this.cfg.livenessMs;
+                let timer;
+                const idle = new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new RemoteExecutionError("timeout", `execStream idle > ${idleMs}ms (provider hang / unreachable sandbox)`)), idleMs);
+                });
+                try {
+                    await Promise.race([next, idle]);
+                }
+                catch (e) {
+                    finished = true;
+                    void handle.kill().catch(() => { });
+                    this.cfg.metrics?.inc("remote_env_exec_stream_read_timeout_total", { provider: PROVIDER });
+                    throw e instanceof RemoteExecutionError ? e : this.remoteError(e);
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            }
+            yield* drainQueued();
+            if (failure)
+                throw failure;
+            yield { type: "exit", exitCode };
+        }
+        finally {
+            if (!finished) {
+                finished = true;
+                void handle.kill().catch(() => { });
+            }
+            this.activeCommands--;
+            options?.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    backgroundCapabilities = {
+        supported: true,
+        maxConcurrent: E2B_BG_MAX_CONCURRENT,
+        defaultBgTimeoutSec: E2B_BG_DEFAULT_TIMEOUT_SEC,
+        maxBgTimeoutSec: E2B_BG_MAX_TIMEOUT_SEC,
+        supportsDetach: true,
+    };
+    _bgManager;
+    get bgManager() {
+        return (this._bgManager ??= new BackgroundShellManager(this.makeBgDriver(), this.backgroundCapabilities));
+    }
+    makeBgDriver() {
+        const self = this;
+        return {
+            async launch(command, options, ctx) {
+                const conn = await self.ensureConnected();
+                if (!conn.ok)
+                    throw new Error(`remote connect failed: ${conn.error.message}`);
+                const sbx = conn.value;
+                const stdout = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
+                const stderr = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
+                const handle = await self.rpc("commands.run.bg", () => sbx.commands.run(command, {
+                    background: true,
+                    cwd: self.resolve(options?.cwd ?? self.cwd),
+                    ...(options?.env ? { envs: options.env } : {}),
+                    timeoutMs: (ctx.bgTimeoutSec + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000,
+                    onStdout: (d) => {
+                        const b = Buffer.from(d, "utf8");
+                        stdout.tail.push(b);
+                        stdout.total += b.length;
+                    },
+                    onStderr: (d) => {
+                        const b = Buffer.from(d, "utf8");
+                        stderr.tail.push(b);
+                        stderr.total += b.length;
+                    },
+                }), undefined, self.cfg.livenessMs);
+                handle
+                    .wait()
+                    .then((r) => ctx.onTerminal(false, r.exitCode))
+                    .catch((e) => {
+                    if (e instanceof CommandExitError)
+                        ctx.onTerminal(false, e.exitCode);
+                    else
+                        ctx.onTerminal(true);
+                });
+                return { handle, stdout, stderr };
+            },
+            async read(state) {
+                const slice = (s) => {
+                    const { text, droppedBytes } = s.tail.result();
+                    const droppedBeforeCursor = Math.max(0, droppedBytes - s.cursor);
+                    const startByte = Math.max(s.cursor, droppedBytes);
+                    const startInTail = startByte - droppedBytes;
+                    const reencoded = Buffer.from(text, "utf8");
+                    const delta = reencoded.length - (s.total - droppedBytes);
+                    const inc = startInTail <= 0 ? text : reencoded.subarray(startInTail + delta).toString("utf8");
+                    s.cursor = s.total;
+                    return { inc, droppedBeforeCursor };
+                };
+                const out = slice(state.stdout);
+                const er = slice(state.stderr);
+                return {
+                    stdout: out.inc,
+                    stderr: er.inc,
+                    bytesFromStart: state.stdout.total + state.stderr.total,
+                    bytesDroppedBeforeCursor: out.droppedBeforeCursor + er.droppedBeforeCursor,
+                };
+            },
+            async kill(state) {
+                await state.handle.kill().catch(() => { });
+            },
+            async disposeOne(state) {
+                await state.handle.kill().catch(() => { });
+            },
+        };
+    }
+    spawnBackground(command, options) {
+        return this.bgManager.spawn(command, options);
+    }
+    pollBackground(shellId) {
+        return this.bgManager.poll(shellId);
+    }
+    killBackground(shellId) {
+        return this.bgManager.kill(shellId);
+    }
+    disposeBackgroundShells(opts) {
+        return this._bgManager ? this._bgManager.dispose(opts) : Promise.resolve();
+    }
+    async absolutePath(p) {
+        return ok(this.resolve(p));
+    }
+    async joinPath(parts) {
+        return ok(path.posix.join(...parts));
+    }
+    async readTextFile(p, abortSignal) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        try {
+            const content = await this.rpc("files.read", (signal) => sbx.value.files.read(this.resolve(p), { format: "text", signal }), abortSignal, this.cfg.dataTimeoutMs);
+            return ok(content);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
+        }
+    }
+    async readTextLines(p, options) {
+        const r = await this.readTextFile(p, options?.abortSignal);
+        if (!r.ok)
+            return r;
+        let lines = r.value.split(/\r?\n/);
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        if (options?.maxLines != null)
+            lines = lines.slice(0, options.maxLines);
+        return ok(lines);
+    }
+    async readBinaryFile(p, abortSignal) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        try {
+            const content = await this.rpc("files.read", (signal) => sbx.value.files.read(this.resolve(p), { format: "bytes", signal }), abortSignal, this.cfg.dataTimeoutMs);
+            return ok(content);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
+        }
+    }
+    async writeFile(p, content, abortSignal) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        try {
+            const data = typeof content === "string" ? content : toArrayBuffer(content);
+            await this.rpc("files.write", (signal) => sbx.value.files.write(this.resolve(p), data, { signal }), abortSignal, this.cfg.dataTimeoutMs);
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
+        }
+    }
+    async appendFile(p, content, abortSignal) {
+        const abs = this.resolve(p);
+        const existing = await this.readBinaryFile(abs, abortSignal);
+        let base;
+        if (existing.ok) {
+            base = existing.value;
+        }
+        else if (existing.error.code === "not_found") {
+            base = new Uint8Array(0);
+        }
+        else {
+            return existing;
+        }
+        const add = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        const merged = new Uint8Array(base.length + add.length);
+        merged.set(base, 0);
+        merged.set(add, base.length);
+        return this.writeFile(abs, merged, abortSignal);
+    }
+    async fileInfo(p, abortSignal) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        try {
+            const info = await this.rpc("files.getInfo", (signal) => sbx.value.files.getInfo(this.resolve(p), { signal }), abortSignal);
+            return ok(this.toFileInfo(info));
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
+        }
+    }
+    async listDir(p, abortSignal) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        try {
+            const entries = await this.rpc("files.list", (signal) => sbx.value.files.list(this.resolve(p), { signal }), abortSignal);
+            return ok(entries.map((e) => this.toFileInfo(e)));
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
+        }
+    }
+    async canonicalPath(p, abortSignal) {
+        const abs = this.resolve(p);
+        const r = await this.exec(`realpath -- ${shellQuote(abs)}`, { abortSignal });
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        if (r.value.exitCode !== 0) {
+            const msg = r.value.stderr.trim();
+            if (/permission denied|access denied/i.test(msg))
+                return { ok: false, error: new FileError("permission_denied", msg, abs) };
+            if (/not a directory/i.test(msg))
+                return { ok: false, error: new FileError("not_directory", msg, abs) };
+            return { ok: false, error: new FileError("not_found", msg || `realpath failed for ${abs}`, abs) };
+        }
+        return ok(r.value.stdout.trim());
+    }
+    async exists(p, abortSignal) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        try {
+            const exists = await this.rpc("files.exists", (signal) => sbx.value.files.exists(this.resolve(p), { signal }), abortSignal);
+            return ok(exists);
+        }
+        catch (e) {
+            const fe = this.fileError(e, this.resolve(p), abortSignal);
+            if (fe.code === "not_found")
+                return ok(false);
+            return { ok: false, error: fe };
+        }
+    }
+    async createDir(p, options) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        try {
+            await this.rpc("files.makeDir", (signal) => sbx.value.files.makeDir(this.resolve(p), { signal }), options?.abortSignal);
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.resolve(p), options?.abortSignal) };
+        }
+    }
+    async remove(p, options) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
+        const abs = this.resolve(p);
+        if (options?.recursive) {
+            const flags = options.force ? "-rf" : "-r";
+            const r = await this.exec(`rm ${flags} -- ${shellQuote(abs)}`, { abortSignal: options.abortSignal });
+            if (!r.ok)
+                return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+            if (r.value.exitCode !== 0)
+                return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `rm failed for ${abs}`, abs) };
+            return ok(undefined);
+        }
+        try {
+            await this.rpc("files.remove", (signal) => sbx.value.files.remove(abs, { signal }), options?.abortSignal);
+            return ok(undefined);
+        }
+        catch (e) {
+            const fe = this.fileError(e, abs, options?.abortSignal);
+            if (options?.force && fe.code === "not_found")
+                return ok(undefined);
+            return { ok: false, error: fe };
+        }
+    }
+    async createTempDir(prefix = "tmp-", abortSignal) {
+        const r = await this.exec(`mktemp -d -t ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal });
+        return this.tempResult(r, "mktemp -d");
+    }
+    async createTempFile(options) {
+        const prefix = options?.prefix ?? "";
+        const suffix = options?.suffix ?? "";
+        const suffixArg = suffix ? `--suffix=${shellQuote(suffix)} -t` : "-t";
+        const r = await this.exec(`mktemp ${suffixArg} ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal: options?.abortSignal });
+        return this.tempResult(r, "mktemp");
+    }
+    resolve(p) {
+        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+    }
+    async rpc(label, op, userSignal, timeoutMs = this.cfg.rpcTimeoutMs) {
+        const deadline = new AbortController();
+        const timer = setTimeout(() => deadline.abort(), timeoutMs);
+        const combined = userSignal ? anySignal([userSignal, deadline.signal]) : undefined;
+        const signal = combined?.signal ?? deadline.signal;
+        const onDeadline = new Promise((_, reject) => deadline.signal.addEventListener("abort", () => {
+            this.cfg.metrics?.inc("remote_env_rpc_timeout_total", { provider: PROVIDER, op: label });
+            reject(new RemoteExecutionError("timeout", `remote ${label} exceeded ${timeoutMs}ms (provider RPC hang)`));
+        }, { once: true }));
+        try {
+            return await Promise.race([op(signal), onDeadline]);
+        }
+        finally {
+            clearTimeout(timer);
+            combined?.dispose();
+        }
+    }
+    commandTimeoutMs(timeoutSec) {
+        return timeoutSec != null ? timeoutSec * 1000 : this.cfg.timeoutMs;
+    }
+    async waitWithLiveness(handle, lastProgress, opts) {
+        let timer;
+        let wallTimer;
+        const idle = new Promise((_, reject) => {
+            const arm = () => {
+                timer = setTimeout(() => {
+                    if (opts?.disarmed?.())
+                        return;
+                    const idleFor = Date.now() - lastProgress();
+                    if (idleFor >= this.cfg.livenessMs) {
+                        void handle.kill().catch(() => { });
+                        this.cfg.metrics?.inc("remote_env_exec_idle_timeout_total", { provider: PROVIDER });
+                        reject(new RemoteExecutionError("timeout", `exec idle > ${this.cfg.livenessMs}ms (provider hang / unreachable sandbox)`));
+                    }
+                    else {
+                        arm();
+                    }
+                }, Math.max(this.cfg.livenessMs - (Date.now() - lastProgress()), 0));
+            };
+            arm();
+            if (opts?.wallMs != null) {
+                wallTimer = setTimeout(() => {
+                    if (opts.disarmed?.())
+                        return;
+                    void handle.kill().catch(() => { });
+                    reject(new RemoteExecutionError("timeout", `exec exceeded ${opts.wallMs}ms`));
+                }, opts.wallMs);
+            }
+        });
+        try {
+            return await Promise.race([opts?.waitP ?? handle.wait(), idle]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (wallTimer)
+                clearTimeout(wallTimer);
+        }
+    }
+    async ensureConnected() {
+        if (this.paused)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resume before fs/exec") };
+        if (this.sbx)
+            return ok(this.sbx);
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        const r = await this.connect();
+        if (!r.ok)
+            return { ok: false, error: r.error };
+        return ok(this.sbx);
+    }
+    async fsReady(p) {
+        const conn = await this.ensureConnected();
+        if (!conn.ok)
+            return { ok: false, error: new FileError("unknown", `remote connect failed: ${conn.error.message}`, this.resolve(p), conn.error) };
+        return ok(conn.value);
+    }
+    tempResult(r, op) {
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, undefined, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `${op} failed`) };
+        return ok(r.value.stdout.trim());
+    }
+    toFileInfo(e) {
+        const kind = e.symlinkTarget ? "symlink" : e.type === FileType.DIR ? "directory" : "file";
+        return {
+            name: e.name,
+            path: e.path,
+            kind,
+            size: e.size ?? 0,
+            mtimeMs: e.modifiedTime ? e.modifiedTime.getTime() : 0,
+        };
+    }
+    fileError(e, p, abortSignal) {
+        if (e instanceof FileError)
+            return e;
+        const msg = errMsg(e);
+        const name = e?.name;
+        if (abortSignal?.aborted || name === "AbortError")
+            return new FileError("aborted", msg, p);
+        if (e instanceof RemoteExecutionError && e.code === "timeout") {
+            this.cfg.metrics?.inc("remote_env_file_timeout_total", { provider: PROVIDER });
+            return new FileError("timeout", msg, p, e);
+        }
+        if (name === "SandboxNotFoundError" || /sandbox .*not found|sandbox .*not running|sandbox was not found/i.test(msg)) {
+            return new FileError("unknown", msg, p);
+        }
+        if (name === "FileNotFoundError" || name === "NotFoundError" || /no such file|file not found/i.test(msg)) {
+            return new FileError("not_found", msg, p);
+        }
+        if (name === "InvalidArgumentError")
+            return new FileError("invalid", msg, p);
+        if (/permission denied|access denied/i.test(msg))
+            return new FileError("permission_denied", msg, p);
+        if (/not a directory/i.test(msg))
+            return new FileError("not_directory", msg, p);
+        if (/is a directory/i.test(msg))
+            return new FileError("is_directory", msg, p);
+        return new FileError("unknown", msg, p);
+    }
+    execError(e, abortSignal) {
+        if (e instanceof ExecutionError)
+            return e;
+        const msg = errMsg(e);
+        const name = e?.name;
+        if (abortSignal?.aborted || name === "AbortError")
+            return new ExecutionError("aborted", msg);
+        if (name === "TimeoutError" || /timeout|timed out/i.test(msg))
+            return new ExecutionError("timeout", msg);
+        return new ExecutionError("unknown", msg, e instanceof Error ? e : undefined);
+    }
+    remoteError(e, code = "unknown") {
+        if (e instanceof RemoteExecutionError)
+            return e;
+        return new RemoteExecutionError(code, errMsg(e), e instanceof Error ? e : undefined);
+    }
+}
+export function e2bExecutionEnvFactory(config, deps) {
+    return (ctx) => new RemoteContainerExecutionEnv({
+        ...config,
+        metadata: { ...config.metadata, sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
+    }, deps);
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function anySignal(signals) {
+    const ctor = AbortSignal;
+    if (typeof ctor.any === "function")
+        return { signal: ctor.any(signals), dispose: () => { } };
+    const ctrl = new AbortController();
+    const onAbort = () => ctrl.abort();
+    const cleanups = [];
+    for (const s of signals) {
+        if (s.aborted) {
+            ctrl.abort();
+            break;
+        }
+        s.addEventListener("abort", onAbort, { once: true });
+        cleanups.push(() => s.removeEventListener("abort", onAbort));
+    }
+    return { signal: ctrl.signal, dispose: () => cleanups.forEach((c) => c()) };
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function toArrayBuffer(u) {
+    return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
+}
+//# sourceMappingURL=remote-env-e2b.js.map