Skip to content

Commit 64c0e5c

Browse files
authored
docs: remove stale compatibility contract descriptions (#87)
Co-authored-by: anycodes <21079031+anycodes@users.noreply.github.com>
1 parent 5e79e4d commit 64c0e5c

40 files changed

Lines changed: 160 additions & 253 deletions

‎.agents/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,3 +105,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
105105
- [Remove retired project compatibility](notes/implemented/architecture/2026-10-22-remove-legacy-compatibility.md) · [verification](evidence/verify/2026-10-22-remove-legacy-compatibility.md)
106106

107107
- [Compatibility cleanup remote acceptance](evidence/verify/2026-10-22-remove-legacy-acceptance.md)
108+
109+
- [Current compatibility-removal documentation verification](evidence/verify/2026-10-22-remove-legacy-docs.md).
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Verification: current documentation after compatibility removal
2+
3+
- Date: 2026-10-22
4+
- Scope: contributor entry point, current English/Chinese guides and references, documentation indexes and changelog; runtime code is unchanged.
5+
- Result: PASS for local documentation checks; latest-head remote CI remains required before merge.
6+
7+
## Behavior and sources
8+
9+
The maintainer requested one current project contract. Compare documentation with the merged native method signatures, provider-owned port hooks, official template API, single configuration registry and always-on server policy engine. Remove obsolete import/method/credential aliases, inert retry fields, old template API selectors and base64 transfer routes from current instructions. Standard upstream behavior and immutable historical engineering captures remain separately owned.
10+
11+
The implementation and real-component results are recorded in [original verification](2026-10-22-remove-legacy-compatibility.md) and [merged acceptance](2026-10-22-remove-legacy-acceptance.md). This documentation follow-up creates no cloud resources and performs no release or manual deployment.
12+
13+
## Validation
14+
15+
- PASS: `bash scripts/check-repo-health.sh` — 106 passes, 1 historical warnings, zero failures.
16+
- PASS: `make hygiene` — no local paths or credential-like strings.
17+
- PASS: `git diff --check` — no whitespace errors.
18+
- Reviewed current method signatures, policy token setup, file route ownership and configuration descriptors against the changed documentation. Retired names remain only as explicit rejection/removal descriptions or historical review material.
19+
- The latest-head remote CI and Markdown-link checks remain mandatory; product/cloud results belong to the linked implementation evidence, not to these document checks.

‎.agents/notes/implemented/architecture/2026-10-22-remove-legacy-compatibility.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,9 @@ Issue: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/84
3737
Verified merged implementation: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/85. The source merge commit is `d1a54f78e447bc67b90dbfdf48168b020275c871`.
3838

3939
- [Remote acceptance](../../../evidence/verify/2026-10-22-remove-legacy-acceptance.md)
40+
41+
## Current documentation follow-up
42+
43+
Remove stale instructions that still advertised retired imports, credential aliases, retry settings, template selectors and server transfer routes. The current API references, provider boundary pages and contributor entry point describe the merged implementation.
44+
45+
- [Documentation verification](../../../evidence/verify/2026-10-22-remove-legacy-docs.md)

‎AGENTS.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,6 @@ python-sdk/
3838
│ │ ├── api/ # High-level API and server client; provider-neutral lifecycle/session contracts
3939
│ │ ├── providers/ # Backend/session adapters; shared envd wire; external Node engine client
4040
│ │ ├── agent/ # AI agent tooling: MCP server, tool definitions
41-
│ │ ├── compat/ # Legacy migration helpers (preserve their explicit contract)
4241
│ │ ├── declarative/ # @sandbox decorator, config, serializer
4342
│ │ ├── session/ # Session persistence: local (LocalSessionStore)
4443
│ │ └── utils/ # Async bridge, secret store, logging, registry, retry
@@ -88,7 +87,6 @@ graph TB
8887
subgraph Upper["Upper Layers"]
8988
Agent["Agent/MCP — MCP server, tool defs"]
9089
Decl["Declarative — @sandbox decorator"]
91-
Compat["Compat — E2B migration helper"]
9290
Server["Server — SandboxServer SDK, HTTP routes"]
9391
Sess["Session — Persistence"]
9492
end
@@ -102,7 +100,6 @@ graph TB
102100
103101
Agent --> L3
104102
Decl --> L3
105-
Compat --> L3
106103
Server --> L0U
107104
Sess --> L3
108105
L3 --> L2 --> L1

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
88
99
## [Unreleased]
1010

11+
### Fixed
12+
13+
- Align contributor guidance and English/Chinese API, configuration and provider documentation with the removed project compatibility surface. / 同步贡献指南及中英文 API、配置和 Provider 文档,清除已删除项目兼容接口的旧说明。
14+
1115
### Removed
1216

1317
- Pre-release project compatibility: old template factories/APIs and selector flags, import aliases, migration commands, deprecated method aliases, old server transfer routes, custom AK/SK token exchange and implicit provider URL/port fallbacks.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Provider management operations are available through `agent_sandbox.providers.co
5050
- **MCP server** — expose sandbox operations as MCP tools for LLM agents.
5151
- **Declarative decorator** — `@sandbox` turns a plain function into a remote sandbox execution with automatic serialisation.
5252
- **Session persistence** — save and restore sandbox state across runs.
53-
- **E2B-shaped methods** — `agent_sandbox.compat` re-exports the standard Sandbox and AsyncSandbox; see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md).
53+
- **Standard sync/async clients** — `agent_sandbox` exports the standard Sandbox and AsyncSandbox; see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md).
5454

5555
## Server SDK
5656

‎README.zh-CN.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Node.js 项目,位于 [`agent-sandbox`](https://github.com/alibaba-agent-sandb
4848
- **MCP Server** —— 将沙箱操作暴露为 MCP 工具,供 LLM Agent 调用。
4949
- **声明式装饰器** —— `@sandbox` 将普通函数变为远程沙箱执行,自动序列化。
5050
- **会话持久化** —— 跨运行保存和恢复沙箱状态。
51-
- **E2B 风格方法名** —— `agent_sandbox.compat` 导出标准 Sandbox 与 AsyncSandbox,见[从 E2B 迁移](docs/zh/guide/migrate-from-e2b.md)。
51+
- **标准同步与异步客户端** —— `agent_sandbox` 导出标准 Sandbox 与 AsyncSandbox,见[从 E2B 迁移](docs/zh/guide/migrate-from-e2b.md)。
5252

5353
## Server SDK
5454

‎docs/en/DESIGN.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ This repository holds the Python SDK as two lock-step PyPI distributions — `ag
1414

1515
### Core Principles
1616

17-
1. **Pinned standard behavior and explicit provider extensions** — Root `Sandbox` is synchronous; `AsyncSandbox` is asynchronous. Standard and interpreter clients follow the Alibaba-supported E2B baseline through an owned MIT source port. `agent_sandbox.compat` re-exports the standard clients. Provider/server/declarative extensions use `ProviderSandbox`; `ABX_PROVIDER` does not switch the standard clients' protocol.
17+
1. **Pinned standard behavior and explicit provider extensions** — Root `Sandbox` is synchronous; `AsyncSandbox` is asynchronous. Standard and interpreter clients follow the Alibaba-supported E2B baseline through an owned MIT source port. Provider/server/declarative extensions use `ProviderSandbox`; `ABX_PROVIDER` does not switch the standard clients' protocol.
1818
2. **AI-First** — MCP Server as a first-class citizen, coding agents hosted through the Agents API
1919
3. **Explicit connection settings** — Reuse the existing Alibaba API key, API URL and sandbox domain; backend-dependent capabilities remain conditional.
2020

@@ -128,7 +128,6 @@ Chinese copies of these pages live under `docs/zh/`. `repository-layout.md` is E
128128
| MCP Server (Streamable HTTP) | **Implemented** | `mcp_http.py` |
129129
| FC deployment artifact application | **Implemented** | `agent_sandbox.agent.mcp_http:asgi_app`; the artifact is generated by `abx mcp deploy` in the CLI. See [mcp-server.md](design/mcp-server.md#7-fc-deployment) |
130130
| Template build/push/deploy | **In the CLI** | `abx template build` and `abx template deploy`; the SDK does not build templates |
131-
| E2B migration helper | **Implemented (partial)** | `agent_sandbox.compat` |
132131
| One environment variable per configuration key (SDK) | **Implemented** | See [Configuration](reference/configuration.md); CLI spec in `cli/docs/design/providers-and-credentials-cli.md` |
133132
| Provider plugins (SDK, `python -m agent_sandbox.providers`) | **Implemented** | See [Providers](guide/providers.md). The CLI loads installed `node`, `exec` and `rest` plugins (`abx provider`, `abx --provider`) |
134133
| Persistent sandbox | **Future** | Requires underlying platform support |

‎docs/en/design/architecture.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -260,7 +260,7 @@ The CLI (`abx`) formerly lived in `src/agent_sandbox/cli/` (Click commands under
260260

261261
## 6. Design Principles
262262

263-
1. **E2B-shaped, not E2B-compatible**: L3 uses E2B-shaped method names and ships a small migration helper (`agent_sandbox.compat`); L2 implements the protocol independently without depending on the E2B SDK
263+
1. **Explicit standard and provider contracts**: L3 uses E2B-shaped method names through the maintained standard clients; native provider extensions use ProviderSandbox without depending on the E2B SDK
264264
2. **Progressive Complexity**: Users start at L3 and explore downward or use advanced features upward as needed
265265
3. **Zero-Config Defaults**: Works out of the box with sensible defaults; just set the `ABX_SANDBOX_API_KEY` environment variable to get started
266266
4. **Alibaba Cloud Native**: Built for the Alibaba Cloud FC sandbox service
@@ -269,6 +269,6 @@ The CLI (`abx`) formerly lived in `src/agent_sandbox/cli/` (Click commands under
269269

270270
- [Provider implementation boundaries](provider-isolation.md)
271271

272-
Provider configuration discovery is assembled lazily by the package composition root. Transport consumes a low-level `ProviderSchema` value and an injected resolver from `_provider_schema.py`; it does not import the provider registry. Builtin configuration resolves without provider discovery. Registered, entry-point and installed providers retain the registry selection and derive/default/inheritance rules. The existing `transport.config.ProviderSchema` import remains an alias of the same schema class.
272+
Provider configuration discovery is assembled lazily by the package composition root. Transport consumes a low-level `ProviderSchema` value and an injected resolver from `_provider_schema.py`; it does not import the provider registry. Builtin configuration resolves without provider discovery. Registered, entry-point and installed providers retain the registry selection and derive/default/inheritance rules.
273273

274-
Builtin platform/envd HTTP uses one transport attempt. Legacy retry fields are compatibility data, with the exact boundary in [configuration](../reference/configuration.md#legacy-retry-compatibility); engine recovery remains separate.
274+
Builtin platform/envd HTTP uses one transport attempt; see [configuration](../reference/configuration.md#transport-attempts). Engine read recovery remains separate.

‎docs/en/design/client-server-alignment.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,6 @@ one-sided (section 4).
5151
| `GET /files/download-stream` | `files_download_stream` | `files.read/download` | `server.files.download(path)`, `.read_text`, `.download_file` | NEW |
5252
| `POST /files/archive` | `files_archive` | — | `server.files.archive(paths, format)` | NEW |
5353
| `GET /files/watch` | `files_watch` | `files.watch` (WatchDir) | `server.files.watch(path)` -> async iterator of `ServerWatchEvent` (a `WatchEvent` subclass with `is_dir`) | NEW server + client |
54-
| `POST /upload` (legacy) | `upload` | — | `server.files.upload_legacy(path, data)` | NEW (documented legacy) |
55-
| `GET /download` (legacy) | `download` | — | `server.files.download_legacy(path)` | NEW (documented legacy) |
5654

5755
### 2.3 Processes
5856

@@ -64,7 +62,7 @@ one-sided (section 4).
6462
| `GET /process/list` | `process_list` | `commands.list` | `server.process.list()` | NEW |
6563
| `GET /process/{pid}` | `process_detail` | `commands.connect` (status part) | `server.process.get(pid)` | NEW |
6664
| `POST /process/{pid}/signal` | `process_signal` | `commands.send_signal/kill` | `server.process.signal(pid, sig)`, `.kill(pid)` | NEW |
67-
| `POST /process/{pid}/stdin` | `process_stdin` | `commands.send_stdin` | `server.process.send_stdin(pid, data)` | NEW server + client |
65+
| `POST /process/{pid}/stdin` | `process_stdin` | `commands.send_input` | `server.process.send_stdin(pid, data)` | NEW server + client |
6866
| `GET /process/{pid}/output` | `process_output` | `commands.connect` (output part) | `server.process.output(pid, since, wait)` | NEW server + client |
6967

7068
### 2.4 Terminal
@@ -117,7 +115,7 @@ one-sided (section 4).
117115
| `commands.start` (background) | `process_start` | covered; added `env`, `capture_output`, `stdin` |
118116
| `commands.list` | `process_list` | covered |
119117
| `commands.connect(pid)` | **missing output attach** | **added** `process_output` (+ `?wait`) |
120-
| `commands.send_stdin` | **missing** | **added** `process_stdin` |
118+
| `commands.send_input` | **missing** | **added** `process_stdin` |
121119
| `commands.send_signal/kill` | `process_signal` | covered |
122120
| `ProcessProtocol.update` (pty resize via process) | `pty_resize` | **added** (PTY only) |
123121
| `get_terminal` (envd WS `/terminal`) | PTY WS on 9001 with REST session create | client `server.pty` implements the server protocol; envd path unchanged |

0 commit comments

Comments
 (0)