feat(workspace): S3-compatible workspace backend

Adds S3WorkspaceBackend behind the new `s3` Cargo feature. The backend
implements WorkspaceFileSystem against any S3-compatible endpoint (AWS
S3, MinIO, RustFS, Cloudflare R2, Backblaze B2, ...) via the AWS Rust
SDK. It deliberately does NOT implement WorkspaceCommandRunner,
WorkspaceSearch, or any git provider trait — capability gating then
prevents bash/grep/glob/git from being registered when the backend is
in use, so the model never sees tools the backend cannot service.

Includes:
- core/src/workspace/s3.rs: S3WorkspaceBackend + S3BackendConfig builder
  (endpoint / region / session_token / force_path_style / request_timeout),
  with_client() injection for tests.
- WorkspaceServices::s3(config) and WorkspaceServices::from_s3_backend()
  factories with a 60s default per-operation timeout.
- 11 unit tests covering key/prefix derivation, list prefix handling,
  capability matrix, and config builder.
- core/tests/test_s3_backend.rs: env-gated end-to-end integration test
  that exercises the full session executor (read/write/edit/patch/ls,
  asserting bash/git/grep/glob are not registered) against a real
  S3-compatible endpoint; auto-cleans the per-run UUID prefix.
- Node and Python SDKs expose S3WorkspaceBackend alongside
  LocalWorkspaceBackend via the same workspaceBackend / workspace_backend
  option surface; both SDK Rust crates depend on a3s-code-core with the
  s3 feature enabled.
- README documents the new backend with cross-language usage examples.

The new feature is fully optional: building a3s-code-core without
`--features s3` keeps the dependency tree slim and excludes the AWS SDK.

Author: claude

Cargo.lock

@@ -455,6 +455,108 @@ Intent-gated tools:
 
 This follows the same direction as modern agent harnesses: remove routine tool clutter from the model's context and expose capabilities only when the task asks for them.
 
+Workspace backends are capability providers behind the stable built-in tool
+contracts. By default, `read`, `write`, `edit`, `patch`, `ls`, `grep`, `glob`,
+`bash`, and `git` operate on the local workspace. Embedded hosts can supply
+`WorkspaceServices` through `SessionOptions::with_workspace_backend(...)` so
+those same tools target a DFS, browser workspace, remote container, or other
+host-managed environment.
+
+```rust
+use a3s_code_core::{Agent, SessionOptions, WorkspaceServices};
+
+# async fn run() -> anyhow::Result<()> {
+let agent = Agent::new("agent.acl").await?;
+let workspace = WorkspaceServices::local("/repo");
+let session = agent.session(
+    "/repo",
+    Some(SessionOptions::new().with_workspace_backend(workspace)),
+)?;
+# Ok(())
+# }
+```
+
+For non-local backends, A3S Code exposes tools according to declared workspace
+capabilities. `bash` is exposed only when a command runner is available,
+`grep`/`glob` only when a search provider is available, and `git` only when a
+workspace Git provider is available. Browser hosts can pair a virtual file
+system with a browser Git implementation, while cloud hosts can route the same
+tool contract through DFS or RPC-backed providers.
+
+#### S3-compatible storage backend
+
+When the `s3` Cargo feature is enabled, `S3WorkspaceBackend` lets built-in
+file tools (`read`, `write`, `edit`, `patch`, `ls`) target any S3-compatible
+endpoint — AWS S3, MinIO, RustFS, Cloudflare R2, Backblaze B2, and so on.
+`bash`, `git`, `grep`, and `glob` are intentionally not registered because
+object storage cannot service them.
+
+```toml
+# Cargo.toml
+[dependencies]
+a3s-code-core = { version = "2.6", features = ["s3"] }
+```
+
+```rust
+use a3s_code_core::{Agent, S3BackendConfig, SessionOptions, WorkspaceServices};
+
+# async fn run() -> anyhow::Result<()> {
+let agent = Agent::new("agent.acl").await?;
+let config = S3BackendConfig::new(
+    "workspace",                     // bucket
+    "users/u1/sessions/s1",          // workspace prefix inside the bucket
+    "AKIA...",                       // access key id
+    "...",                           // secret access key
+)
+.endpoint("https://minio.local:9000")  // omit for AWS S3
+.region("us-east-1")
+.force_path_style(true);               // true for MinIO/RustFS, false for AWS
+let session = agent.session(
+    "s3://workspace/users/u1/sessions/s1",
+    Some(SessionOptions::new().with_workspace_backend(WorkspaceServices::s3(config))),
+)?;
+# Ok(())
+# }
+```
+
+The Node and Python SDKs expose the same backend:
+
+```js
+// Node
+import { Agent, S3WorkspaceBackend } from '@a3s-lab/code';
+const session = agent.session(workspaceUri, {
+    workspaceBackend: new S3WorkspaceBackend({
+        endpoint: 'https://minio.local:9000',
+        region: 'us-east-1',
+        accessKeyId: 'AKIA...',
+        secretAccessKey: '...',
+        bucket: 'workspace',
+        prefix: 'users/u1/sessions/s1',
+        forcePathStyle: true,
+    }),
+});
+```
+
+```python
+# Python
+from a3s_code import Agent, S3WorkspaceBackend, SessionOptions
+opts = SessionOptions()
+opts.workspace_backend = S3WorkspaceBackend(
+    bucket="workspace",
+    prefix="users/u1/sessions/s1",
+    access_key_id="AKIA...",
+    secret_access_key="...",
+    endpoint="https://minio.local:9000",
+    region="us-east-1",
+    force_path_style=True,
+)
+session = agent.session(workspace_uri, opts)
+```
+
+S3 has no atomic read-modify-write, so concurrent writers to the same key may
+overwrite each other. Partition workspaces per session/user via the `prefix`
+field when running multi-tenant.
+
 ### 4. Programmatic Tool Calling
 
 High-frequency tool chains should move out of the LLM loop.

README.md

@@ -104,6 +104,12 @@ uuid = { version = "1.6", features = ["v4", "serde"] }
 chrono = { version = "0.4", features = ["serde"] }
 rquickjs = { version = "0.11.0", features = ["futures"] }
 
+# S3-compatible workspace backend (optional, gated by `s3` feature)
+aws-sdk-s3 = { version = "1", default-features = false, features = ["rt-tokio", "rustls"], optional = true }
+aws-credential-types = { version = "1", optional = true }
+aws-smithy-types = { version = "1", optional = true }
+aws-smithy-runtime-api = { version = "1", optional = true }
+
 [target.'cfg(unix)'.dependencies]
 a3s-ahp = { version = "2.4", path = "../../ahp", optional = true, features = ["http", "websocket", "unix-socket"] }
 
@@ -122,6 +128,15 @@ telemetry = [
 ]
 # Enable AHP (Agent Harness Protocol) integration for external supervision
 ahp = ["dep:a3s-ahp"]
+# Enable the S3-compatible workspace backend (`S3WorkspaceBackend`).
+# Brings in the AWS Rust SDK and is safe to point at any S3-compatible
+# endpoint (AWS S3, MinIO, RustFS, Cloudflare R2, ...).
+s3 = [
+    "dep:aws-sdk-s3",
+    "dep:aws-credential-types",
+    "dep:aws-smithy-types",
+    "dep:aws-smithy-runtime-api",
+]
 
 [dev-dependencies]
 # AHP for integration tests

core/Cargo.toml

@@ -147,3 +147,5 @@ pub use workspace::{
     WorkspacePathResolver, WorkspaceRef, WorkspaceSearch, WorkspaceServices,
     WorkspaceServicesBuilder, WorkspaceWriteOutcome,
 };
+#[cfg(feature = "s3")]
+pub use workspace::{S3BackendConfig, S3WorkspaceBackend};

core/src/lib.rs

@@ -8,8 +8,12 @@
 //! [`WorkspaceServices`] through [`WorkspaceServicesBuilder`].
 
 mod local;
+#[cfg(feature = "s3")]
+mod s3;
 
 pub use local::LocalWorkspaceBackend;
+#[cfg(feature = "s3")]
+pub use s3::{S3BackendConfig, S3WorkspaceBackend};
 
 use anyhow::{anyhow, bail, Result};
 use async_trait::async_trait;