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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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";