docs: README — direct tool methods + S3 workspace backend examples

- Main README: add write_file/ls/edit_file/patch_file to the Direct Tools
  section of the Python and Node API-glance examples; include
  workspace_backend / workspaceBackend in the SessionOptions example;
  import LocalWorkspaceBackend and S3WorkspaceBackend in both stubs.
- Node SDK README: add a dedicated S3-compatible storage section
  alongside the existing LocalWorkspaceBackend example.
- Python SDK README: import S3WorkspaceBackend; add an S3-backed
  session example showing write_file/read_file/ls against an
  S3-compatible endpoint.

No code changes — documents the v2.6.0 surface area for SDK users.

Author: claude

README.md

@@ -98,6 +98,8 @@ from a3s_code import (
     FileMemoryStore,
     FileSessionStore,
     HttpTransport,
+    LocalWorkspaceBackend,
+    S3WorkspaceBackend,
 )
 
 # 1. Configure a session — typed extension options, not raw flags.
@@ -118,6 +120,7 @@ opts.session_store = FileSessionStore("./sessions")
 opts.session_id = "my-session"
 opts.auto_save = True
 opts.ahp_transport = HttpTransport("http://localhost:8080/ahp")
+opts.workspace_backend = LocalWorkspaceBackend("/my-project")  # or S3WorkspaceBackend(bucket=..., prefix=..., ...)
 
 agent = Agent.create("agent.acl")
 session = agent.session("/my-project", opts)
@@ -132,6 +135,10 @@ for event in session.stream({"prompt": "Continue the refactor"}):
 
 # 3. Direct tools (bypass the LLM).
 session.read_file("src/main.py")
+session.write_file("src/new_module.py", "def hello():\n    return 'world'\n")
+session.edit_file("src/main.py", old_string="old_value", new_string="new_value")
+session.patch_file("src/main.py", diff="@@ -1,2 +1,2 @@\n-old\n+new")
+session.ls("src")
 session.bash("pytest -q")
 session.glob("**/*.py")
 session.grep("PermissionPolicy")
@@ -242,6 +249,8 @@ import {
   FileMemoryStore,
   FileSessionStore,
   HttpTransport,
+  LocalWorkspaceBackend,
+  S3WorkspaceBackend,
 } from '@a3s-lab/code';
 
 // 1. Configure a session — typed extension options, not raw flags.
@@ -264,6 +273,7 @@ const opts: SessionOptions = {
   sessionId: 'my-session',
   autoSave: true,
   ahpTransport: new HttpTransport('http://localhost:8080/ahp'),
+  workspaceBackend: new LocalWorkspaceBackend('/my-project'),   // or new S3WorkspaceBackend({ bucket, prefix, ... })
 };
 
 const agent = await Agent.create('agent.acl');
@@ -280,6 +290,10 @@ for await (const event of stream) {
 
 // 3. Direct tools (bypass the LLM).
 await session.readFile('src/main.ts');
+await session.writeFile('src/newModule.ts', "export const hello = () => 'world';\n");
+await session.editFile('src/main.ts', 'old_value', 'new_value');
+await session.patchFile('src/main.ts', '@@ -1,2 +1,2 @@\n-old\n+new');
+await session.ls('src');
 await session.bash('npm test');
 await session.glob('**/*.ts');
 await session.grep('PermissionPolicy');

sdk/node/README.md

@@ -55,9 +55,8 @@ Scripts can also be loaded from workspace-relative `.js` or `.mjs` files with
 ## Workspace Backends And Direct Files
 
 The default workspace backend is the local filesystem rooted at the session
-workspace. SDK callers can pass the explicit typed backend now, using the same
-option surface that remote, browser, DFS, and container-backed workspaces will
-use:
+workspace. SDK callers can pass an explicit typed backend through the same
+option surface used by remote, browser, DFS, and container-backed workspaces:
 
 ```js
 const { Agent, LocalWorkspaceBackend } = require('@a3s-lab/code')
@@ -74,6 +73,39 @@ await session.editFile('notes.txt', 'one', 'uno')
 await session.patchFile('notes.txt', '@@ -1,2 +1,2 @@\n uno\n-two\n+dos')
 ```
 
+### S3-compatible object storage
+
+`S3WorkspaceBackend` lets built-in file tools (`read`, `write`, `edit`,
+`patch`, `ls`) target any S3-compatible endpoint — AWS S3, MinIO, RustFS,
+Cloudflare R2, Backblaze B2, etc. `bash`, `git`, `grep`, and `glob` are
+automatically hidden from the model because object storage cannot service
+them.
+
+```js
+const { Agent, S3WorkspaceBackend } = require('@a3s-lab/code')
+
+const agent = await Agent.create('agent.acl')
+const session = agent.session('s3://workspace/users/u1/sessions/s1', {
+  workspaceBackend: new S3WorkspaceBackend({
+    endpoint: 'https://minio.local:9000',     // omit for AWS S3
+    region: 'us-east-1',
+    accessKeyId: 'AKIA...',
+    secretAccessKey: '...',
+    bucket: 'workspace',
+    prefix: 'users/u1/sessions/s1',
+    forcePathStyle: true,                     // true for MinIO/RustFS/R2
+  }),
+})
+
+await session.writeFile('notes/hello.txt', 'one\ntwo\n')
+await session.readFile('notes/hello.txt')
+await session.ls('notes')
+```
+
+S3 has no atomic read-modify-write, so concurrent writers to the same key
+overwrite each other (last-writer-wins). Partition workspaces per session or
+user via the `prefix` field when running multi-tenant.
+
 ## Planning Events
 
 Planning is automatic by default. Prefer the explicit tri-state

sdk/python/README.md

@@ -61,6 +61,7 @@ from a3s_code import (
     FileSessionStore,
     HttpTransport,
     LocalWorkspaceBackend,
+    S3WorkspaceBackend,
 )
 
 agent = Agent.create("agent.acl")
@@ -111,6 +112,24 @@ session.grep("TODO")
 session.tool_names()
 session.tool_definitions()
 
+# S3-compatible workspace — point the same direct tools at object storage.
+# `bash`, `git`, `grep`, `glob` are automatically hidden because object
+# storage cannot service them. Works with AWS S3, MinIO, RustFS, R2, B2.
+s3_opts = SessionOptions()
+s3_opts.workspace_backend = S3WorkspaceBackend(
+    bucket="workspace",
+    prefix="users/u1/sessions/s1",
+    access_key_id="AKIA...",
+    secret_access_key="...",
+    endpoint="https://minio.local:9000",         # omit for AWS S3
+    region="us-east-1",
+    force_path_style=True,                       # True for MinIO/RustFS/R2
+)
+s3_session = agent.session("s3://workspace/users/u1/sessions/s1", s3_opts)
+s3_session.write_file("notes/hello.txt", "one\ntwo\n")
+s3_session.read_file("notes/hello.txt")
+s3_session.ls("notes")
+
 # Programmatic Tool Calling (embedded QuickJS)
 program = session.program({
     "source": """