Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add just-bash sandbox option to supply custom filesystem (#1544)

prha601fb1338679
diff --git a/.changeset/bright-pandas-mount.md b/.changeset/bright-pandas-mount.md
new file mode 100644
index 000000000..7b64ef3d8
--- /dev/null
+++ b/.changeset/bright-pandas-mount.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Allow just-bash sandboxes to compose a custom filesystem around eve's durable, session-owned workspace.
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts b/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts
index 6d7205d72..fc9765c97 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash-runtime.ts
@@ -12,6 +12,7 @@ import { shellQuote } from "#execution/sandbox/shell-quote.js";
import { buildSandboxSession } from "#execution/sandbox/session.js";
import { loadOptionalEnginePackage } from "#internal/application/optional-package-install.js";
import type { SandboxBackendHandle } from "#public/definitions/sandbox-backend.js";
+import type { JustBashSandboxCreateOptions } from "#public/sandbox/just-bash-sandbox.js";
import { WORKSPACE_ROOT } from "#runtime/workspace/types.js";
import type {
SandboxProcess,
@@ -74,6 +75,7 @@ async function loadJustBashModule(input: {
export async function createBashSandbox(input: {
readonly appRoot: string;
readonly autoInstall: boolean;
+ readonly filesystem?: JustBashSandboxCreateOptions["filesystem"];
readonly rootPath: string;
readonly sessionKey: string;
}): Promise<BashSandbox> {
@@ -87,11 +89,22 @@ export async function createBashSandbox(input: {
await mkdir(filesystemRootPath, { recursive: true });
- const filesystem = new ReadWriteFs({
+ const defaultFilesystem = new ReadWriteFs({
allowSymlinks: true,
maxFileReadSize: Number.MAX_SAFE_INTEGER,
root: filesystemRootPath,
});
+ let filesystem: IFileSystem = defaultFilesystem;
+ if (input.filesystem !== undefined) {
+ try {
+ filesystem = await input.filesystem({
+ appRoot: input.appRoot,
+ defaultFilesystem,
+ });
+ } catch (error) {
+ throw new Error("Failed to create the custom just-bash filesystem.", { cause: error });
+ }
+ }
await ensureLocalSandboxDirectories(filesystem);
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts b/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts
index c70cffd06..656b963de 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash.scenario.test.ts
@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
import { mkdir, readdir, readFile, stat, utimes, writeFile } from "node:fs/promises";
import { join } from "node:path";
+import { MountableFs, ReadWriteFs } from "just-bash";
import { describe, expect, it } from "vitest";
import { useTemporaryDirectories } from "#internal/testing/use-temporary-app-roots.js";
@@ -10,6 +11,7 @@ import {
pruneJustBashSandboxTemplates,
} from "#execution/sandbox/bindings/just-bash.js";
import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import { justbash } from "#public/sandbox/backends/just-bash.js";
const createScratchDirectory = useTemporaryDirectories();
@@ -64,6 +66,78 @@ async function collectStream(stream: ReadableStream<Uint8Array>): Promise<string
}
describe("just-bash sandbox file API", () => {
+ it("composes a custom filesystem alongside the workspace", async () => {
+ const appRoot = await createTemporaryCacheDirectory("custom-filesystem-app");
+ const sourceRoot = join(appRoot, "agent");
+ await mkdir(sourceRoot, { recursive: true });
+ await writeFile(join(sourceRoot, "instructions.md"), "before");
+ let factoryCalls = 0;
+ const backend = justbash({
+ async filesystem(context) {
+ factoryCalls += 1;
+ expect(context.appRoot).toBe(appRoot);
+ await context.defaultFilesystem.mkdir("/source", { recursive: true });
+ return new MountableFs({
+ base: context.defaultFilesystem,
+ mounts: [
+ {
+ filesystem: new ReadWriteFs({
+ allowSymlinks: false,
+ maxFileReadSize: Number.MAX_SAFE_INTEGER,
+ root: sourceRoot,
+ }),
+ mountPoint: "/source",
+ },
+ ],
+ });
+ },
+ });
+
+ const handle = await backend.create({
+ runtimeContext: { appRoot },
+ sessionKey: "session-custom-filesystem",
+ templateKey: null,
+ });
+
+ expect(factoryCalls).toBe(1);
+ expect(await handle.session.readTextFile({ path: "/source/instructions.md" })).toBe("before");
+ await handle.session.writeTextFile({
+ content: "after",
+ path: "/source/instructions.md",
+ });
+ await handle.session.writeTextFile({ content: "scratch", path: "scratch.txt" });
+ expect(await readFile(join(sourceRoot, "instructions.md"), "utf8")).toBe("after");
+ expect(existsSync(join(sourceRoot, "scratch.txt"))).toBe(false);
+ await handle.shutdown();
+ });
+
+ it("applies the filesystem factory only to live sessions", async () => {
+ const appRoot = await createTemporaryCacheDirectory("filesystem-factory-lifecycle");
+ let factoryCalls = 0;
+ const backend = justbash({
+ async filesystem({ defaultFilesystem }) {
+ factoryCalls += 1;
+ return defaultFilesystem;
+ },
+ });
+
+ await backend.prewarm({
+ runtimeContext: { appRoot },
+ seedFiles: [{ content: "from template", path: "/workspace/seed.txt" }],
+ templateKey: "tpl-filesystem-factory",
+ });
+ expect(factoryCalls).toBe(0);
+
+ const handle = await backend.create({
+ runtimeContext: { appRoot },
+ sessionKey: "session-filesystem-factory",
+ templateKey: "tpl-filesystem-factory",
+ });
+ expect(factoryCalls).toBe(1);
+ await expect(handle.session.readTextFile({ path: "seed.txt" })).resolves.toBe("from template");
+ await handle.shutdown();
+ });
+
it("writes a file via the public session and reads it back", async () => {
const cacheDirectory = await createTemporaryCacheDirectory("file-api");
const handle = await createPrewarmedLocalHandle({
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash.ts b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
index eba04897b..bcd8d02c1 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
@@ -64,6 +64,7 @@ export function createJustBashSandboxBackend(
input: CreateJustBashSandboxBackendInput = {},
): SandboxBackend {
const autoInstall = input.createOptions?.autoInstall ?? true;
+ const filesystem = input.createOptions?.filesystem;
return {
name: JUST_BASH_BACKEND_NAME,
async prewarm(prewarmInput: SandboxBackendPrewarmInput): Promise<SandboxBackendPrewarmResult> {
@@ -157,6 +158,7 @@ export function createJustBashSandboxBackend(
const sandbox = await createBashSandbox({
appRoot: createInput.runtimeContext.appRoot,
autoInstall,
+ filesystem,
rootPath: sessionRootPath,
sessionKey: createInput.sessionKey,
});
diff --git a/packages/eve/src/public/sandbox/just-bash-sandbox.ts b/packages/eve/src/public/sandbox/just-bash-sandbox.ts
index 85aa6db12..126e732ce 100644
--- a/packages/eve/src/public/sandbox/just-bash-sandbox.ts
+++ b/packages/eve/src/public/sandbox/just-bash-sandbox.ts
@@ -1,3 +1,15 @@
+import type { IFileSystem } from "just-bash";
+
+/**
+ * Context passed to a custom just-bash filesystem factory for each live handle.
+ */
+export interface JustBashFilesystemContext {
+ /** Stable application root for this backend create call. */
+ readonly appRoot: string;
+ /** eve's durable, session-owned filesystem, including `/workspace`. */
+ readonly defaultFilesystem: IFileSystem;
+}
+
/**
* Options accepted by `justbash(opts)`.
*
@@ -14,4 +26,15 @@ export interface JustBashSandboxCreateOptions {
* actionable install error instead. Defaults to `true`.
*/
readonly autoInstall?: boolean;
+ /**
+ * Composes the filesystem used by each live sandbox handle. The factory is
+ * called when a handle opens with eve's durable default filesystem; return a
+ * fresh filesystem that preserves eve-owned paths such as `/workspace`,
+ * `/tmp`, and the home directory.
+ *
+ * This just-bash-specific escape hatch requires the application to install
+ * a compatible `just-bash` version. It is not invoked during template
+ * prewarming.
+ */
+ readonly filesystem?: (context: JustBashFilesystemContext) => IFileSystem | Promise<IFileSystem>;
}
diff --git a/packages/eve/src/public/sandbox/just-bash.ts b/packages/eve/src/public/sandbox/just-bash.ts
index d2907607a..bfe333a5e 100644
--- a/packages/eve/src/public/sandbox/just-bash.ts
+++ b/packages/eve/src/public/sandbox/just-bash.ts
@@ -1,2 +1,5 @@
export { justbash } from "#public/sandbox/backends/just-bash.js";
-export type { JustBashSandboxCreateOptions } from "#public/sandbox/just-bash-sandbox.js";
+export type {
+ JustBashFilesystemContext,
+ JustBashSandboxCreateOptions,
+} from "#public/sandbox/just-bash-sandbox.js";