fix(volume): align API with E2B SDK

[LSX-s-Software]

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

• 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.

[github-actions]

🔍 OpenCodeReview found 4 issue(s) in this PR.

• ✅ Successfully posted inline: 4 comment(s)