@blaxel/eve-sandbox 0.3.12-preview.250

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Beamlit, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @blaxel/eve-sandbox
+
+[Blaxel](https://blaxel.ai) sandbox backend for [eve](https://eve.dev).
+
+Run eve's built-in shell and file tools in secure, durable Blaxel sandboxes. Each durable eve session reconnects to the same sandbox after an application restart without relying on preview-only Blaxel APIs.
+
+## Quick start
+
+You need Node.js 24 or later and an existing [eve project](https://eve.dev/docs/installation).
+
+### 1. Install the backend
+
+```bash
+npm install @blaxel/eve-sandbox
+```
+
+The package expects the `eve` and `ai` versions already installed by your eve project.
+
+### 2. Authenticate with Blaxel
+
+For local development, sign in with the [Blaxel CLI](https://docs.blaxel.ai/cli-reference/overview):
+
+```bash
+bl login YOUR-WORKSPACE
+```
+
+In CI and production, provide `BL_WORKSPACE` and `BL_API_KEY` to the application runtime. Do not copy those credentials into the sandbox.
+
+### 3. Select Blaxel in eve
+
+```ts
+// agent/sandbox.ts
+import { blaxel } from "@blaxel/eve-sandbox";
+import { defineSandbox } from "eve/sandbox";
+
+export default defineSandbox({
+  backend: blaxel({
+    image: "blaxel/ts-app:latest",
+    lifecycle: {
+      expirationPolicies: [{ type: "ttl-idle", value: "1d", action: "delete" }],
+    },
+    memory: 4096,
+  }),
+  async onSession({ use }) {
+    const sandbox = await use({
+      networkPolicy: { allow: ["github.com", "*.npmjs.org"] },
+    });
+    await sandbox.run({ command: "mkdir -p /workspace/project" });
+  },
+});
+```
+
+Start eve as usual:
+
+```bash
+npm run dev
+```
+
+The built-in `bash`, `read_file`, `write_file`, `glob`, and `grep` tools now operate inside the Blaxel sandbox. To smoke-test the setup in eve's terminal UI, ask the agent to create `/workspace/hello.txt` and read it back.
+
+A copy-ready sandbox definition is available in [`examples/agent/sandbox.ts`](./examples/agent/sandbox.ts).
+
+## What works
+
+- All five built-in eve sandbox tools
+- Blocking commands and streaming background processes
+- Text, binary, and streaming file operations
+- Durable filesystem and process state across turns and app restarts
+- Custom Blaxel images, regions, resources, volumes, environment variables, and lifecycle policies
+- Per-session setup through `onSession()`
+- Domain egress policies and secret-backed header transforms
+- Deterministic reconnection through eve's captured session metadata
+
+## Generally available capability scope
+
+The backend intentionally uses only generally available Blaxel sandbox APIs. It does not call Blaxel snapshot or fork APIs.
+
+eve's `bootstrap()` hook and files under `agent/sandbox/workspace` require a backend to clone a build-time template. This backend does not implement template prewarming. If either feature is configured, it fails with actionable guidance before serving traffic.
+
+Put reusable system dependencies and base files in a [custom Blaxel image](https://docs.blaxel.ai/Sandboxes/Templates). Put setup that must run once for each durable eve session in `onSession()`.
+
+## Lifecycle
+
+- `create()` reconnects a saved sandbox by name or creates a new sandbox from the configured image.
+- `onSession()` performs one-time setup for a new durable eve session.
+- Session names include the backend configuration identity, so a changed sandbox definition gets a new sandbox.
+- `captureState()` persists the Blaxel sandbox name in eve's durable session state.
+- `shutdown()` closes active log streams. Blaxel then moves the idle sandbox into standby while preserving memory, processes, and files.
+
+Session discovery uses Blaxel resources and does not depend on an in-process registry.
+
+## Network policy
+
+The backend supports:
+
+- `"allow-all"`
+- `"deny-all"`
+- Domain allow-lists
+- eve header transforms through Blaxel's secret-backed egress proxy
+
+The backend rejects subnet rules, request match conditions, and `forwardURL`. It does not silently weaken unsupported policies.
+
+The default is `"allow-all"`. For production or untrusted workloads, select `"deny-all"` or an explicit allow-list before the first command runs.
+
+## Options
+
+`blaxel()` accepts standard `SandboxCreateConfiguration` fields such as `image`, `memory`, `region`, `ports`, `envs`, `volumes`, `ttl`, `lifecycle`, and `labels`.
+
+| Option | Purpose | Default |
+| --- | --- | --- |
+| `backendName` | Stable eve backend identifier | `blaxel` |
+| `namePrefix` | Prefix for deterministic Blaxel resources | `eve` |
+| `networkPolicy` | Egress policy applied when a session sandbox is created | `"allow-all"` |
+| `processOutputBufferBytes` | Maximum unread stdout or stderr per process stream | 1 MiB |
+| `startupTimeoutMs` | Maximum cold-image readiness wait | 60 seconds |
+
+## Compatibility
+
+| Package | eve | AI SDK | Node.js | Default image |
+| --- | --- | --- | --- | --- |
+| `@blaxel/eve-sandbox` 0.2.x | 0.31.3 to less than 0.32 | 7.0.38 to less than 8 | 24 or later | `blaxel/ts-app:latest` |
+
+Each release must pass the adapter contract suite and a live eve agent evaluation against its declared range. A new eve minor requires a tested peer-range update.
+
+## Cleanup
+
+Blaxel sandboxes remain durable until their configured lifecycle removes them. Set `lifecycle` or `ttl` when the application requires automatic deletion of inactive sessions.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { type SandboxCreateConfiguration } from "@blaxel/core";
+import { type SandboxBackend, type SandboxNetworkPolicy } from "eve/sandbox";
+export type BlaxelEveUseOptions = {
+    readonly networkPolicy?: SandboxNetworkPolicy;
+};
+type BlaxelEveSandboxCreateOptions = Pick<SandboxCreateConfiguration, "envs" | "expires" | "extraArgs" | "image" | "labels" | "lifecycle" | "memory" | "ports" | "region" | "ttl" | "volumes">;
+export type BlaxelEveBackendOptions = BlaxelEveSandboxCreateOptions & {
+    /** Stable eve backend name. Changing it invalidates persisted backend state. */
+    readonly backendName?: string;
+    /** Prefix used for deterministic Blaxel resource names. */
+    readonly namePrefix?: string;
+    /** Initial policy for new session sandboxes. */
+    readonly networkPolicy?: SandboxNetworkPolicy;
+    /** Maximum buffered stdout or stderr bytes for an unread process stream. */
+    readonly processOutputBufferBytes?: number;
+    /** Maximum time to wait for a cold sandbox image to accept commands. */
+    readonly startupTimeoutMs?: number;
+};
+/** Create a first-party Blaxel implementation of eve's public SandboxBackend. */
+export declare function blaxel(options?: BlaxelEveBackendOptions): SandboxBackend<BlaxelEveUseOptions, BlaxelEveUseOptions>;
+export { createBlaxelEveSession } from "./session.js";
+export { toBlaxelNetworkPolicy } from "./network-policy.js";
+export default blaxel;

package/dist/index.js

@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto";
+import { ResponseError, SandboxInstance, isGatewayError, } from "@blaxel/core";
+import { toBlaxelNetworkPolicy } from "./network-policy.js";
+import { createBlaxelEveSession } from "./session.js";
+const DEFAULT_BACKEND_NAME = "blaxel";
+const DEFAULT_NAME_PREFIX = "eve";
+const DEFAULT_IMAGE = "blaxel/ts-app:latest";
+const DEFAULT_STARTUP_TIMEOUT_MS = 60_000;
+const MAX_SANDBOX_NAME_LENGTH = 49;
+/** Create a first-party Blaxel implementation of eve's public SandboxBackend. */
+export function blaxel(options = {}) {
+    const { backendName = DEFAULT_BACKEND_NAME, namePrefix = DEFAULT_NAME_PREFIX, networkPolicy, processOutputBufferBytes, startupTimeoutMs = DEFAULT_STARTUP_TIMEOUT_MS, ...sandboxOptions } = options;
+    validateOptions({
+        backendName,
+        namePrefix,
+        processOutputBufferBytes,
+        startupTimeoutMs,
+    });
+    const normalizedPrefix = normalizeNamePrefix(namePrefix);
+    const configurationIdentity = stableHash({
+        sandboxOptions,
+        networkPolicy: networkPolicy ?? "allow-all",
+    });
+    return {
+        name: backendName,
+        prewarm(input) {
+            return Promise.reject(templatePrewarmUnsupported(input.templateKey));
+        },
+        async create(input) {
+            try {
+                if (input.templateKey !== null) {
+                    throw templatePrewarmUnsupported(input.templateKey);
+                }
+                const labels = resourceLabels("session", input.tags, sandboxOptions.labels);
+                const existing = await findExistingSession(input);
+                if (existing) {
+                    await SandboxInstance.updateMetadata(existing.metadata.name, { labels });
+                    if (networkPolicy !== undefined)
+                        await applyNetworkPolicy(existing, networkPolicy);
+                    return createHandle(existing, input.sessionKey);
+                }
+                const sessionName = resourceName(normalizedPrefix, "session", `${input.sessionKey}\0${configurationIdentity}`);
+                const sandbox = await SandboxInstance.createIfNotExists({
+                    ...sandboxOptions,
+                    image: sandboxOptions.image ?? DEFAULT_IMAGE,
+                    labels,
+                    name: sessionName,
+                    network: initialNetwork(networkPolicy),
+                });
+                await ensureBaseRuntime(sandbox, startupTimeoutMs);
+                return createHandle(sandbox, input.sessionKey);
+            }
+            catch (error) {
+                throw new Error(`Blaxel backend failed to open sandbox session "${input.sessionKey}": ${errorMessage(error)}`, { cause: error });
+            }
+        },
+    };
+    async function findExistingSession(input) {
+        const persistedName = readString(input.existingMetadata, "sandboxName");
+        const deterministicName = resourceName(normalizedPrefix, "session", `${input.sessionKey}\0${configurationIdentity}`);
+        const names = [...new Set([persistedName, deterministicName].filter(Boolean))];
+        for (const name of names) {
+            const sandbox = await tryGetSandbox(name);
+            if (sandbox)
+                return sandbox;
+        }
+        return null;
+    }
+    function createHandle(sandbox, sessionKey) {
+        const openProcessStreams = new Set();
+        const session = createBlaxelEveSession({
+            id: sessionKey,
+            processOutputBufferBytes,
+            sandbox,
+            registerProcessStream(close) {
+                openProcessStreams.add(close);
+                return () => openProcessStreams.delete(close);
+            },
+        });
+        return {
+            session,
+            async useSessionFn(useOptions) {
+                if (useOptions?.networkPolicy !== undefined) {
+                    await applyNetworkPolicy(sandbox, useOptions.networkPolicy);
+                }
+                return session;
+            },
+            captureState() {
+                return Promise.resolve({
+                    backendName,
+                    metadata: { sandboxName: sandbox.metadata.name },
+                    sessionKey,
+                });
+            },
+            shutdown() {
+                for (const close of openProcessStreams)
+                    close();
+                openProcessStreams.clear();
+                // Blaxel automatically suspends an idle sandbox and preserves its full state.
+                return Promise.resolve();
+            },
+        };
+    }
+}
+export { createBlaxelEveSession } from "./session.js";
+export { toBlaxelNetworkPolicy } from "./network-policy.js";
+export default blaxel;
+async function applyNetworkPolicy(sandbox, policy) {
+    await SandboxInstance.updateNetwork(sandbox.metadata.name, {
+        network: toBlaxelNetworkPolicy(policy),
+    });
+}
+function initialNetwork(policy) {
+    return policy === undefined ? undefined : toBlaxelNetworkPolicy(policy);
+}
+async function ensureBaseRuntime(sandbox, startupTimeoutMs) {
+    const deadline = Date.now() + startupTimeoutMs;
+    let retryDelayMs = 500;
+    for (;;) {
+        try {
+            const result = await sandbox.process.exec({
+                command: "mkdir -p /workspace && command -v bash >/dev/null",
+                waitForCompletion: true,
+                workingDir: "/",
+            });
+            if (result.exitCode !== 0) {
+                throw new Error("The Blaxel sandbox image must provide bash.");
+            }
+            return;
+        }
+        catch (error) {
+            if (!isRetryableStartupError(error) || Date.now() >= deadline)
+                throw error;
+            const remainingMs = deadline - Date.now();
+            await delay(Math.min(retryDelayMs, remainingMs));
+            retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
+        }
+    }
+}
+async function tryGetSandbox(name) {
+    try {
+        return await SandboxInstance.get(name);
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return null;
+        throw error;
+    }
+}
+function resourceName(prefix, kind, identity) {
+    const hashLength = MAX_SANDBOX_NAME_LENGTH - prefix.length - kind.length - 2;
+    return `${prefix}-${kind}-${stableHash(identity).slice(0, hashLength)}`;
+}
+function resourceLabels(kind, tags, configured) {
+    const labels = {
+        ...(configured ?? {}),
+        "blaxel-integration": "eve",
+        "eve-resource": kind,
+    };
+    for (const [key, value] of Object.entries(tags ?? {})) {
+        labels[`eve-${normalizeLabel(key, 59)}`] = normalizeLabel(value, 63);
+    }
+    return labels;
+}
+function normalizeNamePrefix(value) {
+    const normalized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 20);
+    if (!normalized)
+        throw new Error("namePrefix must contain a letter or number");
+    return normalized;
+}
+function normalizeLabel(value, maxLength) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "")
+        .slice(0, maxLength)
+        .replace(/[^a-z0-9]+$/g, "") || "unknown";
+}
+function stableHash(value) {
+    return createHash("sha256").update(stableSerialize(value)).digest("hex");
+}
+function stableSerialize(value) {
+    if (value instanceof Date)
+        return JSON.stringify(value.toISOString());
+    if (Array.isArray(value))
+        return `[${value.map(stableSerialize).join(",")}]`;
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableSerialize(item)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function validateOptions(input) {
+    if (!input.backendName.trim())
+        throw new Error("backendName cannot be empty");
+    normalizeNamePrefix(input.namePrefix);
+    if (!Number.isFinite(input.startupTimeoutMs) || input.startupTimeoutMs <= 0) {
+        throw new Error("startupTimeoutMs must be a positive finite number");
+    }
+    if (input.processOutputBufferBytes !== undefined &&
+        (!Number.isInteger(input.processOutputBufferBytes) || input.processOutputBufferBytes <= 0)) {
+        throw new Error("processOutputBufferBytes must be a positive integer");
+    }
+}
+function isRetryableStartupError(error) {
+    if (isGatewayError(error))
+        return true;
+    return (error instanceof ResponseError &&
+        error.status === 404 &&
+        /WORKLOAD_UNAVAILABLE|currently not available/iu.test(error.message));
+}
+function isNotFoundError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return candidate.code === 404 || candidate.code === "404" || candidate.status === 404 || candidate.statusCode === 404;
+}
+function templatePrewarmUnsupported(templateKey) {
+    return new Error(`Blaxel eve template prewarming is not supported (template "${templateKey}"). ` +
+        "Use a custom Blaxel image for reusable dependencies and files, omit eve bootstrap() " +
+        "and agent/sandbox/workspace seed files, and perform one-time session setup in onSession().");
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (error && typeof error === "object") {
+        const { message } = error;
+        if (typeof message === "string")
+            return message;
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return "Unknown error object";
+        }
+    }
+    return String(error);
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/network-policy.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxNetwork } from "@blaxel/core";
+import type { SandboxNetworkPolicy } from "eve/sandbox";
+/** Convert eve's firewall shape into Blaxel's domain proxy configuration. */
+export declare function toBlaxelNetworkPolicy(policy: SandboxNetworkPolicy): SandboxNetwork;

package/dist/network-policy.js

@@ -0,0 +1,53 @@
+/** Convert eve's firewall shape into Blaxel's domain proxy configuration. */
+export function toBlaxelNetworkPolicy(policy) {
+    if (policy === "allow-all")
+        return {};
+    if (policy === "deny-all") {
+        return { proxy: { allowedDomains: [], routing: [] } };
+    }
+    const input = policy;
+    if ((input.subnets?.allow?.length ?? 0) > 0 || (input.subnets?.deny?.length ?? 0) > 0) {
+        throw new Error("The Blaxel eve backend does not support eve subnet allow or deny rules.");
+    }
+    const entries = normalizeAllowEntries(input.allow);
+    const allowAll = entries.some(([domain]) => domain === "*");
+    const allowedDomains = allowAll ? undefined : entries.map(([domain]) => domain);
+    const routing = entries.flatMap(([domain, rules], domainIndex) => {
+        const headers = {};
+        const secrets = {};
+        rules.forEach((rule, ruleIndex) => {
+            if (rule.match !== undefined) {
+                throw new Error(`The Blaxel eve backend cannot apply a request match condition for ${domain}.`);
+            }
+            if (rule.forwardURL !== undefined) {
+                throw new Error(`The Blaxel eve backend cannot forward requests for ${domain} to another URL.`);
+            }
+            rule.transform?.forEach((transform, transformIndex) => {
+                Object.entries(transform.headers ?? {}).forEach(([header, value], headerIndex) => {
+                    const secretName = `eve-${domainIndex}-${ruleIndex}-${transformIndex}-${headerIndex}`;
+                    headers[header] = `{{SECRET:${secretName}}}`;
+                    secrets[secretName] = value;
+                });
+            });
+        });
+        if (Object.keys(headers).length === 0)
+            return [];
+        return [{ destinations: [domain], headers, secrets }];
+    });
+    return {
+        proxy: {
+            ...(allowedDomains === undefined ? {} : { allowedDomains }),
+            routing,
+        },
+    };
+}
+function normalizeAllowEntries(allow) {
+    if (allow === undefined)
+        return [];
+    if (Array.isArray(allow))
+        return allow.map((domain) => [domain, []]);
+    return Object.entries(allow).map(([domain, rules]) => [
+        domain,
+        Array.isArray(rules) ? rules : [],
+    ]);
+}

package/dist/session.d.ts

@@ -0,0 +1,10 @@
+import { SandboxInstance } from "@blaxel/core";
+import type { SandboxSession } from "eve/sandbox";
+export type CreateBlaxelEveSessionOptions = {
+    readonly id: string;
+    readonly processOutputBufferBytes?: number;
+    readonly registerProcessStream?: (close: () => void) => () => void;
+    readonly sandbox: SandboxInstance;
+};
+/** Build eve's public sandbox session over one Blaxel sandbox. */
+export declare function createBlaxelEveSession(options: CreateBlaxelEveSessionOptions): SandboxSession;

package/dist/session.js

@@ -0,0 +1,376 @@
+import { posix as path } from "node:path";
+import { randomUUID } from "node:crypto";
+import { SandboxInstance } from "@blaxel/core";
+import { toBlaxelNetworkPolicy } from "./network-policy.js";
+const WORKSPACE_ROOT = "/workspace";
+const DEFAULT_PROCESS_OUTPUT_BUFFER_BYTES = 1024 * 1024;
+/** Build eve's public sandbox session over one Blaxel sandbox. */
+export function createBlaxelEveSession(options) {
+    const { sandbox } = options;
+    const processOutputBufferBytes = options.processOutputBufferBytes ?? DEFAULT_PROCESS_OUTPUT_BUFFER_BYTES;
+    const session = {
+        id: options.id,
+        resolvePath,
+        async run(runOptions) {
+            const { completion, process } = await spawnInternal(runOptions);
+            const [streamedStdout, streamedStderr, result] = await Promise.all([
+                streamToString(process.stdout),
+                streamToString(process.stderr),
+                completion,
+            ]);
+            return {
+                exitCode: result.exitCode,
+                stdout: result.stdout ?? streamedStdout,
+                stderr: result.stderr ?? streamedStderr,
+            };
+        },
+        spawn,
+        async readFile(readOptions) {
+            throwIfAborted(readOptions.abortSignal);
+            try {
+                const blob = await sandbox.fs.readBinary(resolvePath(readOptions.path));
+                throwIfAborted(readOptions.abortSignal);
+                return bytesToStream(new Uint8Array(await blob.arrayBuffer()));
+            }
+            catch (error) {
+                if (isNotFoundError(error))
+                    return null;
+                throw error;
+            }
+        },
+        async readBinaryFile(readOptions) {
+            const stream = await session.readFile(readOptions);
+            return stream === null ? null : streamToBytes(stream);
+        },
+        async readTextFile(readOptions) {
+            validateReadTextFileOptions(readOptions);
+            const bytes = await session.readBinaryFile(readOptions);
+            if (bytes === null)
+                return null;
+            return applyLineRange(decodeBytes(bytes, readOptions.encoding ?? "utf-8"), readOptions);
+        },
+        async writeFile(writeOptions) {
+            throwIfAborted(writeOptions.abortSignal);
+            const target = resolvePath(writeOptions.path);
+            await ensureParentDirectory(sandbox, target);
+            const bytes = await streamToBytes(writeOptions.content);
+            throwIfAborted(writeOptions.abortSignal);
+            await sandbox.fs.writeBinary(target, bytes);
+        },
+        async writeBinaryFile(writeOptions) {
+            throwIfAborted(writeOptions.abortSignal);
+            const target = resolvePath(writeOptions.path);
+            await ensureParentDirectory(sandbox, target);
+            await sandbox.fs.writeBinary(target, toUint8Array(writeOptions.content));
+            throwIfAborted(writeOptions.abortSignal);
+        },
+        async writeTextFile(writeOptions) {
+            throwIfAborted(writeOptions.abortSignal);
+            const target = resolvePath(writeOptions.path);
+            await ensureParentDirectory(sandbox, target);
+            const encoding = writeOptions.encoding ?? "utf-8";
+            if (encoding === "utf-8" || encoding === "utf8") {
+                await sandbox.fs.write(target, writeOptions.content);
+            }
+            else {
+                await sandbox.fs.writeBinary(target, Buffer.from(writeOptions.content, encoding));
+            }
+            throwIfAborted(writeOptions.abortSignal);
+        },
+        async removePath(removeOptions) {
+            throwIfAborted(removeOptions.abortSignal);
+            try {
+                await sandbox.fs.rm(resolvePath(removeOptions.path), removeOptions.recursive ?? false);
+            }
+            catch (error) {
+                if (removeOptions.force && isNotFoundError(error))
+                    return;
+                throw error;
+            }
+            throwIfAborted(removeOptions.abortSignal);
+        },
+        async setNetworkPolicy(policy) {
+            await SandboxInstance.updateNetwork(sandbox.metadata.name, {
+                network: toBlaxelNetworkPolicy(policy),
+            });
+        },
+    };
+    return session;
+    async function spawn(spawnOptions) {
+        return (await spawnInternal(spawnOptions)).process;
+    }
+    async function spawnInternal(spawnOptions) {
+        throwIfAborted(spawnOptions.abortSignal);
+        const result = await sandbox.process.exec({
+            command: spawnOptions.command,
+            env: spawnOptions.env,
+            keepAlive: false,
+            name: `eve-${randomUUID()}`,
+            timeout: 0,
+            waitForCompletion: false,
+            workingDir: spawnOptions.workingDirectory === undefined
+                ? WORKSPACE_ROOT
+                : resolvePath(spawnOptions.workingDirectory),
+        });
+        const pid = result.pid;
+        const stdout = createBoundedByteStream(processOutputBufferBytes);
+        const stderr = createBoundedByteStream(processOutputBufferBytes);
+        let state = "running";
+        let exitCode = 1;
+        let terminalError;
+        let closeStream = () => { };
+        const stream = sandbox.process.streamLogs(pid, {
+            onStdout: (value) => {
+                const error = stdout.push(new TextEncoder().encode(value));
+                if (error)
+                    failProcess(error);
+            },
+            onStderr: (value) => {
+                const error = stderr.push(new TextEncoder().encode(value));
+                if (error)
+                    failProcess(error);
+            },
+            onError: failProcess,
+        });
+        closeStream = stream.close;
+        const unregister = options.registerProcessStream?.(stream.close) ?? (() => { });
+        const kill = async () => {
+            if (state !== "running")
+                return;
+            state = "killed";
+            exitCode = 137;
+            stream.close();
+            await sandbox.process.kill(pid).catch((error) => {
+                if (!isNotFoundError(error))
+                    throw error;
+            });
+            stdout.finish();
+            stderr.finish();
+        };
+        const abort = () => void kill().catch(failProcess);
+        spawnOptions.abortSignal?.addEventListener("abort", abort, { once: true });
+        const completed = (async () => {
+            try {
+                await stream.wait();
+                if (terminalError)
+                    throw terminalError;
+                if (state === "killed")
+                    return { exitCode };
+                let final = await sandbox.process.get(pid);
+                while (final.status === "running") {
+                    await delay(250);
+                    final = await sandbox.process.get(pid);
+                }
+                exitCode = final.exitCode ?? 1;
+                state = final.status === "killed" || final.status === "stopped" ? "killed" : "exited";
+                stdout.finish();
+                stderr.finish();
+                return { exitCode, stderr: final.stderr, stdout: final.stdout };
+            }
+            catch (error) {
+                const normalized = asError(error);
+                terminalError ??= normalized;
+                stdout.finish(normalized);
+                stderr.finish(normalized);
+                throw normalized;
+            }
+            finally {
+                spawnOptions.abortSignal?.removeEventListener("abort", abort);
+                unregister();
+            }
+        })();
+        void completed.catch(() => undefined);
+        const process = {
+            stdout: stdout.stream,
+            stderr: stderr.stream,
+            wait: async () => ({ exitCode: (await completed).exitCode }),
+            kill,
+        };
+        return { completion: completed, process };
+        function failProcess(error) {
+            if (terminalError)
+                return;
+            terminalError = error;
+            closeStream();
+            void sandbox.process.kill(pid).catch(() => undefined);
+            stdout.finish(error);
+            stderr.finish(error);
+        }
+    }
+}
+function resolvePath(input) {
+    return input.startsWith("/") ? input : `${WORKSPACE_ROOT}/${input}`;
+}
+async function ensureParentDirectory(sandbox, filePath) {
+    const parent = path.dirname(filePath);
+    if (parent === "/" || parent === WORKSPACE_ROOT)
+        return;
+    const result = await sandbox.process.exec({
+        command: `mkdir -p -- ${shellQuote(parent)}`,
+        waitForCompletion: true,
+        workingDir: "/",
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(`Failed to create parent directory ${parent}: ${result.stderr}`);
+    }
+}
+function createBoundedByteStream(maxBufferedBytes) {
+    if (!Number.isInteger(maxBufferedBytes) || maxBufferedBytes <= 0) {
+        throw new Error("processOutputBufferBytes must be a positive integer");
+    }
+    const queue = [];
+    let bufferedBytes = 0;
+    let finished = false;
+    let terminalError;
+    let pendingController;
+    const stream = new ReadableStream({
+        pull(controller) {
+            if (queue.length > 0) {
+                const chunk = queue.shift();
+                bufferedBytes -= chunk.byteLength;
+                controller.enqueue(chunk);
+                return;
+            }
+            if (terminalError) {
+                controller.error(terminalError);
+                return;
+            }
+            if (finished) {
+                controller.close();
+                return;
+            }
+            pendingController = controller;
+        },
+        cancel() {
+            queue.length = 0;
+            bufferedBytes = 0;
+            pendingController = undefined;
+            finished = true;
+        },
+    });
+    return {
+        stream,
+        push(chunk) {
+            if (finished)
+                return terminalError;
+            if (pendingController) {
+                const controller = pendingController;
+                pendingController = undefined;
+                controller.enqueue(chunk);
+                return undefined;
+            }
+            if (bufferedBytes + chunk.byteLength > maxBufferedBytes) {
+                const error = new Error(`Blaxel process output exceeded the ${maxBufferedBytes}-byte buffer; consume output while the process runs.`);
+                this.finish(error);
+                return error;
+            }
+            queue.push(chunk);
+            bufferedBytes += chunk.byteLength;
+            return undefined;
+        },
+        finish(error) {
+            if (finished)
+                return;
+            finished = true;
+            terminalError = error;
+            if (!pendingController)
+                return;
+            const controller = pendingController;
+            pendingController = undefined;
+            if (error)
+                controller.error(error);
+            else
+                controller.close();
+        },
+    };
+}
+function bytesToStream(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+async function streamToBytes(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+            size += value.byteLength;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const result = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+async function streamToString(stream) {
+    return new TextDecoder().decode(await streamToBytes(stream));
+}
+function toUint8Array(content) {
+    if (content instanceof Uint8Array)
+        return content;
+    if (content instanceof ArrayBuffer)
+        return new Uint8Array(content);
+    return new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
+}
+function decodeBytes(bytes, encoding) {
+    if (encoding === "utf-8" || encoding === "utf8") {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString(encoding);
+}
+function validateReadTextFileOptions(options) {
+    const { startLine, endLine } = options;
+    if (startLine !== undefined && (!Number.isInteger(startLine) || startLine < 1)) {
+        throw new Error("startLine must be a positive integer (1-based).");
+    }
+    if (endLine !== undefined && (!Number.isInteger(endLine) || endLine < 1)) {
+        throw new Error("endLine must be a positive integer (1-based).");
+    }
+    if (startLine !== undefined && endLine !== undefined && startLine > endLine) {
+        throw new Error("startLine must not be greater than endLine.");
+    }
+}
+function applyLineRange(text, options) {
+    if (options.startLine === undefined && options.endLine === undefined)
+        return text;
+    const lines = text.match(/.*(?:\r\n|\r|\n)|.+$/g) ?? [];
+    const start = options.startLine ?? 1;
+    const end = Math.min(options.endLine ?? lines.length, lines.length);
+    return start > lines.length ? "" : lines.slice(start - 1, end).join("");
+}
+function isNotFoundError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return candidate.code === 404 || candidate.code === "404" || candidate.status === 404 || candidate.statusCode === 404;
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    if (signal.reason instanceof Error)
+        throw signal.reason;
+    throw new DOMException("The operation was aborted", "AbortError");
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/examples/agent/sandbox.ts

@@ -0,0 +1,21 @@
+import { blaxel } from "@blaxel/eve-sandbox";
+import { defineSandbox } from "eve/sandbox";
+
+export default defineSandbox({
+  backend: blaxel({
+    image: "blaxel/ts-app:latest",
+    labels: { application: "eve" },
+    memory: 4096,
+  }),
+  async onSession({ use }) {
+    const sandbox = await use({
+      networkPolicy: {
+        allow: ["api.github.com", "github.com", "registry.npmjs.org"],
+      },
+    });
+    const result = await sandbox.run({ command: "mkdir -p /workspace/project" });
+    if (result.exitCode !== 0) {
+      throw new Error(`Blaxel session setup failed: ${result.stderr}`);
+    }
+  },
+});

package/examples/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "lib": ["es2023"],
+    "module": "nodenext",
+    "target": "es2022",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "@blaxel/eve-sandbox",
+	"version": "0.3.12-preview.250",
+	"description": "Durable Blaxel sandbox backend for eve agents",
+	"license": "MIT",
+	"author": "Blaxel, INC (https://blaxel.ai)",
+	"homepage": "https://blaxel.ai",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/blaxel-ai/sdk-typescript",
+		"directory": "@blaxel/eve-sandbox"
+	},
+	"engines": {
+		"node": ">=24"
+	},
+	"keywords": [
+		"agent",
+		"ai-agent",
+		"blaxel",
+		"eve",
+		"sandbox",
+		"sandbox-backend",
+		"vercel"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"typesVersions": {
+		"*": {
+			".": [
+				"./dist/index.d.ts"
+			]
+		}
+	},
+	"files": [
+		"dist",
+		"examples",
+		"README.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false,
+	"scripts": {
+		"lint": "eslint src/ examples/ test/",
+		"typecheck:examples": "tsc --noEmit -p examples/tsconfig.json",
+		"dev": "tsc --watch",
+		"build": "NODE_OPTIONS='--max-old-space-size=8192' tsc -p tsconfig.json"
+	},
+	"dependencies": {
+		"@blaxel/core": "0.3.12-preview.250"
+	},
+	"peerDependencies": {
+		"ai": "^7.0.38",
+		"eve": "^0.31.3"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.39.5",
+		"ai": "^7.0.38",
+		"eslint": "9.39.2",
+		"eve": "^0.31.3",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.64.0"
+	}
+}