[PR #263] [MERGED] fix(volume): align API with E2B SDK #300

New issue

Closed

opened 2026-10-29 14:21:58 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:21:58 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/263
Author: @LSX-s-Software
Created: 9/8/2026
Status: ✅ Merged
Merged: 9/9/2026
Merged by: @yingdi-shan

Base: main ← Head: fix/volume-api

📝 Commits (3)

8933a7a fix(api): fix E2B SDK volume mounts compatibility
6e46d56 feat(volume): enhance logging for volume operations
eaae528 refactor(gateway): preserve sandbox fields during list aggregation

📊 Changes

18 files changed (+1166 additions, -504 deletions)

View changed files

📝 crates/aenv/src/client/sandboxes.rs (+21 -4)
📝 docs/src/concepts/volumes.md (+6 -3)
📝 docs/src/integration/e2b.md (+32 -0)
📝 scripts/tests/e2e/e2b_ts_sdk_compat.ts (+178 -27)
📝 scripts/tests/e2e/suites/09_e2b_compat.sh (+2 -2)
📝 scripts/tests/e2e/suites/15_volume.sh (+3 -2)
📝 scripts/tests/e2e/suites/16_volume_randomized.sh (+4 -3)
📝 services/gateway/internal/cluster_list.go (+45 -26)
📝 services/gateway/internal/cluster_list_test.go (+2 -2)
📝 services/gateway/internal/server_test.go (+72 -15)
📝 src/api/generated/src/apis/volumes.rs (+20 -14)
📝 src/api/generated/src/models.rs (+185 -35)
📝 src/api/generated/src/server/mod.rs (+185 -136)
📝 src/api/impls/sandbox.rs (+73 -9)
📝 src/api/impls/volumes.rs (+33 -21)
📝 src/api/openapi.yml (+204 -182)
📝 src/api/proxy.rs (+5 -12)
📝 src/volume.rs (+96 -11)

📄 Description

What

Align AgentENV's volume API boundary with the E2B OpenAPI contract while retaining AgentENV-specific volume fields.

Represent sandbox volume mounts as E2B-compatible { name, path } arrays in requests and responses.
Align volume endpoint placement, response variants, and generated server models with the E2B specification.
Return AgentENV's Volume model from create/get operations because the direct E2B volume-content data plane is not supported.
Convert the aenv client's existing path-to-volume map at the HTTP boundary.
Cover volume creation, mount, persistence across sandbox deletion, remount, and deletion with the official E2B TypeScript SDK.
Add structured lifecycle and publication-failure logging for managed volumes.

Why

The official E2B SDK serializes volumeMounts as an array, while AgentENV previously expected a map, so valid SDK sandbox creation failed with HTTP 422. The volume endpoints and models also differed enough to make the supported SDK control-plane behavior unclear and incomplete.

This change makes the supported volume lifecycle usable through the official SDK and documents the remaining data-plane limitation without returning placeholder credentials.

Closes #257.

Scope and non-goals

Included:

E2B-compatible volume and volumeMounts OpenAPI definitions.
Regenerated Rust server models and handlers.
CLI request conversion, documentation, shell E2E updates, and official TypeScript SDK compatibility coverage.
Volume lifecycle and backing-publication diagnostics.

Not included:

E2B's direct volume-content API or VolumeAndToken response model.
Placeholder token or domain values.
Changes to internal volume ownership, reservation, snapshot, or storage semantics.

Design and behavior changes

The public API now accepts and returns volume mounts as SandboxVolumeMount[]. API handlers convert that representation to the existing internal HashMap<mount_path, volume_reference> and reject duplicate mount paths with HTTP 400. Empty internal mount sets are returned as empty arrays.

Volume create, list, get, and delete keep AgentENV's existing size, mode, status, pagination, and image/COW extensions. Create and get return Volume, not VolumeAndToken, because AgentENV supports mounted access through sandboxes but does not expose E2B's direct content data plane.

The TypeScript compatibility suite uses Volume.create, passes the returned Volume directly to Sandbox.create, verifies data after deleting and recreating the sandbox, and cleans up with Volume.destroy.

Volume-manager logs now expose create/delete, reservation, backing materialization/publication, and publication-failure stages. Failure-state persistence errors are logged instead of being silently discarded.

Compatibility and operations

Public API or generated protocol: volumeMounts changes from a path-to-volume object to an E2B-compatible array. Volume routes/models are aligned with the E2B specification while retaining AgentENV extension fields.
Configuration or defaults: N/A; no configuration or default changes.
Snapshot manifest, artifact layout, or storage format: N/A; persisted formats and storage ownership are unchanged.
Upgrade and rollback: API clients sending the old map representation must update to the array representation or use the updated aenv client. Rolling back restores the old wire contract.
Host requirements, permissions, ports, or dependencies: N/A; no new host or runtime dependencies.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

cargo fmt --all -- --check
  passed
cargo test -p aenv
  passed: 72 tests
cargo clippy -p aenv --all-targets -- -D warnings
  passed
cargo check -p agentenv --lib
  passed
cargo test -p agentenv --lib api::impls::sandbox::tests::volume_mounts_ -- --nocapture
  passed: 2 tests
cargo test -p agentenv --lib api::proxy::tests::volume_mounts_use_name_and_path_entries -- --exact
  passed
TypeScript typecheck and Prettier checks
  passed
bash -n scripts/tests/e2e/suites/{09_e2b_compat,15_volume,16_volume_randomized}.sh
  passed
mdbook build docs
  passed (existing mdbook-mermaid version warning only)
git diff --check upstream/main...HEAD
  passed
Official E2B TypeScript SDK 2.38.0 against AgentENV at 127.0.0.1:8000
  passed: template build, Volume.create, mount/write, sandbox delete,
  remount/read, Volume.destroy, and cleanup verification

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/263 **Author:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Created:** 9/8/2026 **Status:** ✅ Merged **Merged:** 9/9/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `fix/volume-api` --- ### 📝 Commits (3) - [`8933a7a`](https://github.com/kvcache-ai/AgentENV/commit/8933a7a1b592f6b112d969efbf9466d28d6773af) fix(api): fix E2B SDK volume mounts compatibility - [`6e46d56`](https://github.com/kvcache-ai/AgentENV/commit/6e46d56c60c4d40b199215a12642ec90d7f70013) feat(volume): enhance logging for volume operations - [`eaae528`](https://github.com/kvcache-ai/AgentENV/commit/eaae5281478906417817d722f7a30556704c52ba) refactor(gateway): preserve sandbox fields during list aggregation ### 📊 Changes **18 files changed** (+1166 additions, -504 deletions) <details> <summary>View changed files</summary> 📝 `crates/aenv/src/client/sandboxes.rs` (+21 -4) 📝 `docs/src/concepts/volumes.md` (+6 -3) 📝 `docs/src/integration/e2b.md` (+32 -0) 📝 `scripts/tests/e2e/e2b_ts_sdk_compat.ts` (+178 -27) 📝 `scripts/tests/e2e/suites/09_e2b_compat.sh` (+2 -2) 📝 `scripts/tests/e2e/suites/15_volume.sh` (+3 -2) 📝 `scripts/tests/e2e/suites/16_volume_randomized.sh` (+4 -3) 📝 `services/gateway/internal/cluster_list.go` (+45 -26) 📝 `services/gateway/internal/cluster_list_test.go` (+2 -2) 📝 `services/gateway/internal/server_test.go` (+72 -15) 📝 `src/api/generated/src/apis/volumes.rs` (+20 -14) 📝 `src/api/generated/src/models.rs` (+185 -35) 📝 `src/api/generated/src/server/mod.rs` (+185 -136) 📝 `src/api/impls/sandbox.rs` (+73 -9) 📝 `src/api/impls/volumes.rs` (+33 -21) 📝 `src/api/openapi.yml` (+204 -182) 📝 `src/api/proxy.rs` (+5 -12) 📝 `src/volume.rs` (+96 -11) </details> ### 📄 Description ## What Align AgentENV's volume API boundary with the E2B OpenAPI contract while retaining AgentENV-specific volume fields. - Represent sandbox volume mounts as E2B-compatible `{ name, path }` arrays in requests and responses. - Align volume endpoint placement, response variants, and generated server models with the E2B specification. - Return AgentENV's `Volume` model from create/get operations because the direct E2B volume-content data plane is not supported. - Convert the `aenv` client's existing path-to-volume map at the HTTP boundary. - Cover volume creation, mount, persistence across sandbox deletion, remount, and deletion with the official E2B TypeScript SDK. - Add structured lifecycle and publication-failure logging for managed volumes. ## Why The official E2B SDK serializes `volumeMounts` as an array, while AgentENV previously expected a map, so valid SDK sandbox creation failed with HTTP 422. The volume endpoints and models also differed enough to make the supported SDK control-plane behavior unclear and incomplete. This change makes the supported volume lifecycle usable through the official SDK and documents the remaining data-plane limitation without returning placeholder credentials. ## Related issue Closes #257. ## Scope and non-goals Included: - E2B-compatible volume and `volumeMounts` OpenAPI definitions. - Regenerated Rust server models and handlers. - CLI request conversion, documentation, shell E2E updates, and official TypeScript SDK compatibility coverage. - Volume lifecycle and backing-publication diagnostics. Not included: - E2B's direct volume-content API or `VolumeAndToken` response model. - Placeholder `token` or `domain` values. - Changes to internal volume ownership, reservation, snapshot, or storage semantics. ## Design and behavior changes The public API now accepts and returns volume mounts as `SandboxVolumeMount[]`. API handlers convert that representation to the existing internal `HashMap<mount_path, volume_reference>` and reject duplicate mount paths with HTTP 400. Empty internal mount sets are returned as empty arrays. Volume create, list, get, and delete keep AgentENV's existing size, mode, status, pagination, and image/COW extensions. Create and get return `Volume`, not `VolumeAndToken`, because AgentENV supports mounted access through sandboxes but does not expose E2B's direct content data plane. The TypeScript compatibility suite uses `Volume.create`, passes the returned `Volume` directly to `Sandbox.create`, verifies data after deleting and recreating the sandbox, and cleans up with `Volume.destroy`. Volume-manager logs now expose create/delete, reservation, backing materialization/publication, and publication-failure stages. Failure-state persistence errors are logged instead of being silently discarded. ## Compatibility and operations - Public API or generated protocol: `volumeMounts` changes from a path-to-volume object to an E2B-compatible array. Volume routes/models are aligned with the E2B specification while retaining AgentENV extension fields. - Configuration or defaults: N/A; no configuration or default changes. - Snapshot manifest, artifact layout, or storage format: N/A; persisted formats and storage ownership are unchanged. - Upgrade and rollback: API clients sending the old map representation must update to the array representation or use the updated `aenv` client. Rolling back restores the old wire contract. - Host requirements, permissions, ports, or dependencies: N/A; no new host or runtime dependencies. ## Validation - [x] `make fmt` - [x] `make clippy` - [x] `make test-unit` - [x] Relevant Rust integration tests - [x] `make -C services test` (required when `services/` changes) - [x] Generated clients/server regenerated with the documented `make` target - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text cargo fmt --all -- --check passed cargo test -p aenv passed: 72 tests cargo clippy -p aenv --all-targets -- -D warnings passed cargo check -p agentenv --lib passed cargo test -p agentenv --lib api::impls::sandbox::tests::volume_mounts_ -- --nocapture passed: 2 tests cargo test -p agentenv --lib api::proxy::tests::volume_mounts_use_name_and_path_entries -- --exact passed TypeScript typecheck and Prettier checks passed bash -n scripts/tests/e2e/suites/{09_e2b_compat,15_volume,16_volume_randomized}.sh passed mdbook build docs passed (existing mdbook-mermaid version warning only) git diff --check upstream/main...HEAD passed Official E2B TypeScript SDK 2.38.0 against AgentENV at 127.0.0.1:8000 passed: template build, Volume.create, mount/write, sandbox delete, remount/read, Volume.destroy, and cleanup verification ``` ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:21:58 +00:00