From 08c51248bb3c1a6f1380bdb3d33126cda23bb7ec Mon Sep 17 00:00:00 2001
From: anycodes <21079031+anycodes@users.noreply.github.com>
Date: Mon, 19 Oct 2026 08:45:50 +0000
Subject: [PATCH 1/6] fix: acknowledge native server process startup

---
 .agents/README.md                             |   2 +
 ...2026-10-19-server-start-acknowledgement.md |  14 +++
 ...2026-10-19-server-start-acknowledgement.md |  31 ++++++
 CHANGELOG.md                                  |   4 +
 client-sdk/src/agent_sandbox/api/sandbox.py   |  87 ++++++++++++---
 .../server_e2e/test_sandbox_server_helpers.py | 101 +++++++++++++++++-
 docs/en/guide/server-sdk.md                   |  23 ++++
 docs/zh/guide/server-sdk.md                   |  23 ++++
 8 files changed, 269 insertions(+), 16 deletions(-)
 create mode 100644 .agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
 create mode 100644 .agents/notes/proposed/feature/2026-10-19-server-start-acknowledgement.md

diff --git a/.agents/README.md b/.agents/README.md
index 29cd66b..6d650b8 100644
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -91,3 +91,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 - [Provider preflight](notes/proposed/feature/2026-10-18-provider-preflight.md) · [verification](evidence/verify/2026-10-18-provider-preflight.md)
 
 - [Conditional Express acceptance](notes/proposed/feature/2026-10-19-conditional-acceptance.md) · [verification](evidence/verify/2026-10-19-conditional-acceptance.md)
+
+- [Dispatch native server startup before readiness](notes/proposed/feature/2026-10-19-server-start-acknowledgement.md) · [verification](evidence/verify/2026-10-19-server-start-acknowledgement.md)
diff --git a/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
new file mode 100644
index 0000000..ca47dab
--- /dev/null
+++ b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
@@ -0,0 +1,14 @@
+# Verification: native server startup acknowledgement — 2026-10-19
+
+Result: PASS for focused regression and local real-component acceptance; complete current-head hosted matrix required before merge.
+
+Scope: native client helper/tests and matching bilingual server guide, based on SDK `27c84e2b87427664b3e5fcb707d7c52dda6e4252`; Python3.12.13, Linux x86_64. Client/server version0.3.0. Fresh paired wheels installed outside the source checkout, all extras and dependency compatibility checked.
+
+- Before fix: meaningful lazy-reader regression FAIL (launch counter0); 12 existing tests PASS. The initial real probe reached native HTTP502 with no listener. A subsequent console-command probe correctly failed startup when the base image process environment did not provide its entry point. No failed attempt is relabeled.
+- After fix: 16 focused helper tests PASS, including bounded missing acknowledgement, no private output in errors, wait=False dispatch, process exit during health, and reader release.
+- Full local client checkpoint:2186 PASS/24 SKIP/10 integration deselected. Subsequent focused final helper tests16 PASS; full current-head hosted matrix remains required. Ruff/format and mypy105 source files PASS.
+- Full unchanged server suite checkpoint:852 PASS/3 FAIL/1 SKIP. One failure was an audit venv missing pip; after installing pip, its isolated package-list test PASS. Two raw HTTP/WebSocket framing tests receive proxy HTTP502 in this controlled environment. Assertions are preserved; no local full-server pass claimed. Server lint and mypy56 files PASS.
+- Real locally initiated Express acceptance from installed wheels plus actual installed npm artifact and SEA: wheel create/execute and file write/read; npm and SEA exec; native named hello through public port; reconnect after closing the creator client still invokes the retained remote server. All six checks PASS. Explicit module command used for the task-owned installed server. Native foreground process execution also PASS.
+- Cleanup: owned sandboxes destroyed in finally and independently listed absent, zero residuals. No template or snapshot created; no cloud/model Actions or secret upload.
+
+Build/twine and public source-pair checks are recorded with their actual result before publication. Version0.3.0 on source/wheels is not a claim of PyPI publication or current-main GitHub Release. Issue: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/69 .
diff --git a/.agents/notes/proposed/feature/2026-10-19-server-start-acknowledgement.md b/.agents/notes/proposed/feature/2026-10-19-server-start-acknowledgement.md
new file mode 100644
index 0000000..9f9f050
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-10-19-server-start-acknowledgement.md
@@ -0,0 +1,31 @@
+# Decision: Dispatch native server startup before readiness
+
+Status: proposed
+
+## Problem
+
+The native helper returned a lazy process stream without iterating it. A healthy response could be accepted before any process Start request. Existing tests replaced the stream with an opaque object and missed the dispatch boundary.
+
+## Decision
+
+Drain the actual lazy stream in a bounded-memory task, await a remote process acknowledgement even with wait=False, reject early exit/failed startup, and release local readers at close/kill without killing retained remote resources. Keep standard clients and provider ownership unchanged.
+
+## API Design
+
+ProviderSandbox.start_server keeps its parameters and ServerClient result. wait=False skips health polling only. Startup errors omit raw process output and point callers to the executable/process PATH. A command override can use the installed Python module.
+
+## Alternatives considered
+
+Changing every CommandsModule background call would broaden its lazy-stream contract. Accepting only health reproduces the false-ready defect. A detached shell workaround alone would not fix the SDK helper.
+
+## Dependencies
+
+Python asyncio and existing StreamReader/process acknowledgement contract; no new runtime dependency. Fixes https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/69 .
+
+## Test Strategy
+
+Reproduce zero dispatch with a real lazy reader, then verify acknowledgement, wait=False, timeout, safe failure, process exit during health, and local-reader cleanup. Build paired wheels, install in a clean consumer and exercise real Express named commands/retention/cleanup locally. Run full tests, typing, lint and hosted matrix.
+
+## Acceptance criteria
+
+New behavior regressions pass; clean artifacts install with matched versions; real named command and retained-server receipt passes; no owned sandbox remains; latest-head required CI passes before merge. Source installation recipes pin a tested immutable implementation.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 929e1e9..d19c4c7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Fixed
+
+- Start native SandboxServer processes before reporting readiness; bound startup acknowledgement, drain output without accumulation and release local readers while retaining remote ownership. / 原生 SandboxServer 启动先确认进程，限制等待并释放本地读取连接，保留远程资源所有权。
+
 ### Changed
 
 - Align Alibaba Express standard lifecycle, process, file and interpreter behavior with the pinned E2B contract; use canonical `E2B_*` connection settings.
diff --git a/client-sdk/src/agent_sandbox/api/sandbox.py b/client-sdk/src/agent_sandbox/api/sandbox.py
index 3aaa2e8..8ed12de 100644
--- a/client-sdk/src/agent_sandbox/api/sandbox.py
+++ b/client-sdk/src/agent_sandbox/api/sandbox.py
@@ -35,6 +35,7 @@
 
 if TYPE_CHECKING:
     import builtins
+    from asyncio import Task
     from collections.abc import Callable
 
     from agent_sandbox.api.code import CodeContextModule as CodeContextModule
@@ -233,6 +234,7 @@ def __init__(
             )
         self._http_client = http_client
         self._killed = False
+        self._server_stream_tasks: set[Task[None]] = set()
         self._auth = auth
         self._envd_token = envd_token
         self._domain = domain if domain is not None else config.sandbox_domain
@@ -460,7 +462,7 @@ async def start_server(
             token: Sets ``ABX_SERVER_TOKEN`` for the server and authenticates the client.
             env: Extra environment variables for the server process.
             command: Full command line override (default ``agent-sandbox-server serve``).
-            wait: Wait until healthy.
+            wait: Wait until healthy. Process startup is acknowledged even when False.
             timeout: Seconds to wait for health.
 
         Raises:
@@ -469,6 +471,8 @@ async def start_server(
         import asyncio
 
         from agent_sandbox.models.errors import ConnectionError_
+        from agent_sandbox.models.process import ProcessChunkType
+        from agent_sandbox.transport.streaming import StreamReader
 
         server_env: dict[str, str] = dict(env or {})
         if token:
@@ -481,24 +485,71 @@ async def start_server(
                 cmd += f" --commands {shlex.quote(commands)}"
             if isinstance(policy, str):
                 cmd += f" --preset {shlex.quote(policy)}"
-        self._server_process = await self.commands.run(
+        stream = await self.commands.run(
             cmd, background=True, env=server_env or None, timeout=86400
         )
+        if not isinstance(stream, StreamReader):
+            raise ConnectionError_("SandboxServer did not return a process stream")
+        self._server_process = stream
+        started: asyncio.Future[bool] = asyncio.get_running_loop().create_future()
+
+        async def drain() -> None:
+            try:
+                async for chunk in stream:
+                    if chunk.pid and not started.done():
+                        started.set_result(True)
+                    if chunk.type == ProcessChunkType.EXIT:
+                        break
+            except Exception:
+                # Process output and transport errors can contain command secrets.
+                logger.debug("SandboxServer process stream stopped")
+            finally:
+                if not started.done():
+                    started.set_result(False)
+                await stream.cancel()
+
+        task = asyncio.create_task(drain())
+        self._server_stream_tasks.add(task)
+        task.add_done_callback(self._server_stream_tasks.discard)
         client = self.server_at(port, token=token)
-        if not wait:
-            return client
         loop = asyncio.get_running_loop()
         deadline = loop.time() + timeout
-        while True:
-            if await client.health():
-                return client
-            if loop.time() >= deadline:
-                await client.aclose()
+        try:
+            try:
+                acknowledged = await asyncio.wait_for(started, timeout)
+            except asyncio.TimeoutError:
+                raise ConnectionError_(
+                    "SandboxServer process did not acknowledge startup"
+                ) from None
+            if not acknowledged or task.done():
                 raise ConnectionError_(
-                    f"SandboxServer did not become healthy on port {port} within {timeout:g}s",
-                    suggestion="Is agent-sandbox-server installed in the template image?",
+                    "SandboxServer process stopped before startup",
+                    suggestion="Check the server executable and process PATH, or pass command= "
+                    "with an absolute path or python3 -m agent_sandbox.server serve.",
                 )
-            await asyncio.sleep(0.5)
+            if not wait:
+                return client
+            while True:
+                if task.done():
+                    raise ConnectionError_("SandboxServer process stopped before becoming healthy")
+                if await client.health():
+                    if task.done():
+                        raise ConnectionError_(
+                            "SandboxServer process stopped before becoming healthy"
+                        )
+                    return client
+                if loop.time() >= deadline:
+                    raise ConnectionError_(
+                        f"SandboxServer did not become healthy on port {port} within {timeout:g}s",
+                        suggestion="Is agent-sandbox-server installed in the template image?",
+                    )
+                await asyncio.sleep(0.5)
+        except BaseException:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+            self._server_stream_tasks.discard(task)
+            await client.aclose()
+            raise
 
     # ---- Factory classmethods ----
 
@@ -1063,12 +1114,24 @@ async def kill(self) -> None:
             self._killed = True
             logger.info("Sandbox killed: %s", self.id)
         finally:
+            await self._close_server_streams()
             await self._http_client.close()
 
     async def close(self) -> None:
         """Release client-side resources (connections, plugin process); the sandbox stays up."""
+        await self._close_server_streams()
         await self._http_client.close()
 
+    async def _close_server_streams(self) -> None:
+        """Release local readers without killing the remote server or sandbox."""
+        import asyncio
+
+        tasks = list(self._server_stream_tasks)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        self._server_stream_tasks.difference_update(tasks)
+
     async def set_timeout(self, timeout: int) -> None:
         """Update sandbox timeout."""
         await self._sandbox_protocol.set_timeout(self.id, timeout)
diff --git a/client-sdk/tests/test_api/server_e2e/test_sandbox_server_helpers.py b/client-sdk/tests/test_api/server_e2e/test_sandbox_server_helpers.py
index fbcd967..fdac88e 100644
--- a/client-sdk/tests/test_api/server_e2e/test_sandbox_server_helpers.py
+++ b/client-sdk/tests/test_api/server_e2e/test_sandbox_server_helpers.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 from typing import TYPE_CHECKING, Any
 from unittest.mock import AsyncMock
@@ -10,8 +11,12 @@
 
 from agent_sandbox.api.server_client import ServerClient
 from agent_sandbox.models.errors import ConnectionError_
+from agent_sandbox.models.process import ProcessChunk, ProcessChunkType
+from agent_sandbox.transport.streaming import StreamReader
 
 if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
     from agent_sandbox.api.sandbox import Sandbox
 
 
@@ -48,17 +53,31 @@ async def test_every_call_to_server_at_is_a_new_client(self, sandbox: Sandbox) -
 class _Spy:
     def __init__(self) -> None:
         self.calls: list[tuple[str, dict[str, Any]]] = []
+        self.started = 0
+        self.closed = 0
 
-    async def run(self, cmd: str, **kwargs: Any) -> object:
+    async def run(self, cmd: str, **kwargs: Any) -> StreamReader[ProcessChunk]:
         self.calls.append((cmd, kwargs))
-        return object()
+
+        async def frames() -> AsyncIterator[dict[str, Any]]:
+            self.started += 1
+            try:
+                yield {"pid": 42}
+                await asyncio.Event().wait()
+            finally:
+                self.closed += 1
+
+        return StreamReader(
+            frames(), lambda frame: ProcessChunk(type=ProcessChunkType.STDOUT, pid=frame["pid"])
+        )
 
 
 @pytest.fixture
-def spy(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> _Spy:
+async def spy(sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch) -> AsyncIterator[_Spy]:
     spy = _Spy()
     monkeypatch.setattr(sandbox.commands, "run", spy.run)
-    return spy
+    yield spy
+    await sandbox.close()
 
 
 @pytest.fixture
@@ -69,6 +88,79 @@ def healthy(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
 
 
 class TestStartServer:
+    async def test_activates_lazy_process_before_reporting_ready(
+        self, sandbox: Sandbox, spy: _Spy, healthy: AsyncMock
+    ) -> None:
+        client = await sandbox.start_server()
+        assert spy.started == 1
+        await client.aclose()
+        await sandbox.close()
+        assert spy.closed == 1
+
+    async def test_start_failure_is_bounded_and_does_not_expose_remote_output(
+        self, sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, healthy: AsyncMock
+    ) -> None:
+        async def frames() -> AsyncIterator[dict[str, Any]]:
+            raise RuntimeError("private process output")
+            yield {}
+
+        stream = StreamReader(frames(), lambda frame: ProcessChunk(type=ProcessChunkType.STDOUT))
+        monkeypatch.setattr(sandbox.commands, "run", AsyncMock(return_value=stream))
+        with pytest.raises(ConnectionError_, match="stopped before startup") as exc:
+            await sandbox.start_server()
+        assert "private" not in str(exc.value)
+        healthy.assert_not_awaited()
+        assert not sandbox._server_stream_tasks
+
+    async def test_wait_false_still_requires_start_acknowledgement(
+        self, sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch, healthy: AsyncMock
+    ) -> None:
+        closed = asyncio.Event()
+
+        async def frames() -> AsyncIterator[dict[str, Any]]:
+            try:
+                await asyncio.Event().wait()
+                yield {}
+            finally:
+                closed.set()
+
+        stream = StreamReader(frames(), lambda frame: ProcessChunk(type=ProcessChunkType.STDOUT))
+        monkeypatch.setattr(sandbox.commands, "run", AsyncMock(return_value=stream))
+        with pytest.raises(ConnectionError_, match="did not acknowledge startup"):
+            await sandbox.start_server(wait=False, timeout=0.05)
+        assert closed.is_set()
+        healthy.assert_not_awaited()
+        assert not sandbox._server_stream_tasks
+
+    async def test_existing_health_does_not_hide_process_exit(
+        self, sandbox: Sandbox, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        stop = asyncio.Event()
+
+        async def frames() -> AsyncIterator[dict[str, Any]]:
+            yield {"pid": 42}
+            await stop.wait()
+            yield {"exited": True}
+
+        stream = StreamReader(
+            frames(),
+            lambda frame: ProcessChunk(
+                type=ProcessChunkType.EXIT if frame.get("exited") else ProcessChunkType.STDOUT,
+                pid=frame.get("pid"),
+            ),
+        )
+
+        async def health(_client: ServerClient) -> bool:
+            stop.set()
+            await asyncio.sleep(0)
+            return True
+
+        monkeypatch.setattr(sandbox.commands, "run", AsyncMock(return_value=stream))
+        monkeypatch.setattr(ServerClient, "health", health)
+        with pytest.raises(ConnectionError_, match="stopped before becoming healthy"):
+            await sandbox.start_server()
+        assert not sandbox._server_stream_tasks
+
     async def test_default_command_and_background(
         self, sandbox: Sandbox, spy: _Spy, healthy: AsyncMock
     ) -> None:
@@ -121,6 +213,7 @@ async def test_wait_false_does_not_probe(
     ) -> None:
         client = await sandbox.start_server(wait=False)
         healthy.assert_not_awaited()
+        assert spy.started == 1
         await client.aclose()
 
     async def test_polls_until_healthy(
diff --git a/docs/en/guide/server-sdk.md b/docs/en/guide/server-sdk.md
index 75e9485..311899c 100644
--- a/docs/en/guide/server-sdk.md
+++ b/docs/en/guide/server-sdk.md
@@ -66,3 +66,26 @@ These `commands.py` files start with the image. See the [example index](../../..
 - `examples/templates/agents-cli/commands.py` — only the session Agents routes are open
 
 `examples/templates/python-hello/call_api.py` is not the Server SDK. It runs outside the sandbox and sends HTTP to a server that is already listening. That script is a Client SDK example.
+
+## Starting from the native client
+
+`ProviderSandbox.start_server()` starts an installed runtime and waits for the remote process acknowledgement before checking health. `wait=False` skips the health polling, but still starts the process. The native process API's lazy output stream is drained while the local client remains open. Closing the local client releases that reader and leaves the remote server and sandbox running; destroy an owned sandbox explicitly when finished.
+
+The runtime must be installed in the image and reachable from its process environment. When a user-installed console script is missing from the process PATH, use its absolute path or the matching Python interpreter:
+
+```python
+from agent_sandbox import ProviderSandbox
+
+sandbox = await ProviderSandbox.connect(sandbox_id)
+client = await sandbox.start_server(
+    command="python3 -m agent_sandbox.server serve --port 9000 --commands /app/commands.py",
+    timeout=30,
+)
+try:
+    result = await client.commands.run("hello", name="Ada")
+finally:
+    await client.aclose()
+    await sandbox.close()
+```
+
+Startup failures and timeout errors omit raw process output, which may contain secrets. Successful installation alone does not establish a running server.
diff --git a/docs/zh/guide/server-sdk.md b/docs/zh/guide/server-sdk.md
index 9a37dca..5efc7ef 100644
--- a/docs/zh/guide/server-sdk.md
+++ b/docs/zh/guide/server-sdk.md
@@ -64,3 +64,26 @@ agent-sandbox-server serve --commands ./commands.py --port 9000
 - `examples/templates/agents-cli/commands.py` — 只打开发话相关的 Agents 路由
 
 `examples/templates/python-hello/call_api.py` 不是 Server SDK。它在沙箱外面，对已经在听的服务发请求，归在 Client SDK。
+
+## 从原生客户端启动
+
+`ProviderSandbox.start_server()` 会消费远程进程的启动确认，再检查健康状态。`wait=False` 只跳过健康轮询，仍然真正启动进程。客户端保持连接时会持续消费惰性输出流；关闭本地客户端只释放读取连接，保留远程服务和沙箱。自建沙箱用完后应显式销毁。
+
+镜像必须安装运行时，且进程环境能找到它。用户目录安装的控制台脚本不在进程 PATH 时，使用绝对路径或对应的 Python 解释器：
+
+```python
+from agent_sandbox import ProviderSandbox
+
+sandbox = await ProviderSandbox.connect(sandbox_id)
+client = await sandbox.start_server(
+    command="python3 -m agent_sandbox.server serve --port 9000 --commands /app/commands.py",
+    timeout=30,
+)
+try:
+    result = await client.commands.run("hello", name="Ada")
+finally:
+    await client.aclose()
+    await sandbox.close()
+```
+
+启动失败或超时不会附带可能包含密钥的原始进程输出。安装成功并不意味着服务已经启动。

From 63846125baad6085b12c791a09f1b3d733ba67c5 Mon Sep 17 00:00:00 2001
From: anycodes <21079031+anycodes@users.noreply.github.com>
Date: Mon, 19 Oct 2026 08:45:56 +0000
Subject: [PATCH 2/6] docs: pin fresh consumer recipes to the startup fix

---
 README.md                        | 14 +++++++-------
 README.zh-CN.md                  | 14 +++++++-------
 client-sdk/README.md             | 12 ++++++------
 docs/en/guide/client-sdk.md      |  4 ++--
 docs/en/guide/getting-started.md |  8 ++++----
 docs/en/guide/install-python.md  | 12 ++++++------
 docs/en/guide/server-sdk.md      |  2 +-
 docs/en/guide/troubleshooting.md |  4 ++--
 docs/zh/guide/client-sdk.md      |  4 ++--
 docs/zh/guide/getting-started.md |  8 ++++----
 docs/zh/guide/install-python.md  | 10 +++++-----
 docs/zh/guide/server-sdk.md      |  2 +-
 docs/zh/guide/troubleshooting.md |  4 ++--
 examples/README.md               |  8 ++++----
 examples/README.zh-CN.md         |  8 ++++----
 server-sdk/README.md             |  4 ++--
 16 files changed, 59 insertions(+), 59 deletions(-)

diff --git a/README.md b/README.md
index 40e2408..249dc6a 100644
--- a/README.md
+++ b/README.md
@@ -34,8 +34,8 @@ the server only ships `agent_sandbox/server/`) and are **versioned in lockstep**
 
 | Site | URL |
 |---|---|
-| Official site | https://www.agent-sandbox.com |
-| Provider registry | https://registry.agent-sandbox.com |
+| Official site | https://www.agent-sandbox.cn |
+| Provider registry | https://registry.agent-sandbox.cn |
 
 The installer fetches the catalog index at `https://registry.agent-sandbox.cn/providers/index.json`. `ABX_PROVIDER_REGISTRY` overrides that URL.
 
@@ -66,16 +66,16 @@ Current version 0.3.0 is not on PyPI. Use the [paired source installation guide]
 ```bash
 # Client and matching runtime
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # Optional extras (MCP + fast JSON + sessions + declarative)
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # Container-side runtime (install this inside your sandbox image)
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk"
+python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk"
 pip install playwright                       # only if you enable the browser capability group
 
 # Development (from the repository root; includes test & lint tooling for both packages)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 2733d79..feecb21 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -32,8 +32,8 @@ Node.js 项目，位于 [`cli`](https://github.com/alibaba-agent-sandbox/agent-s
 
 | 网站 | 地址 |
 |---|---|
-| 官网 | https://www.agent-sandbox.com |
-| 提供方注册站 | https://registry.agent-sandbox.com |
+| 官网 | https://www.agent-sandbox.cn |
+| 提供方注册站 | https://registry.agent-sandbox.cn |
 
 安装器拉取的目录索引是 `https://registry.agent-sandbox.cn/providers/index.json`。`ABX_PROVIDER_REGISTRY` 可以改这个地址。
 
@@ -64,16 +64,16 @@ Node.js 项目，位于 [`cli`](https://github.com/alibaba-agent-sandbox/agent-s
 ```bash
 # 仅核心客户端 SDK
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # 完整安装（MCP + 快速 JSON + 会话 + 声明式 + server）
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # 容器侧运行时（安装到你的沙箱镜像内）
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk"
+python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk"
 pip install playwright                       # 仅在启用 browser 能力组时需要
 
 # 开发环境（在仓库根目录执行；含两个包的测试与 lint 工具）
diff --git a/client-sdk/README.md b/client-sdk/README.md
index 32ab93a..aefad08 100644
--- a/client-sdk/README.md
+++ b/client-sdk/README.md
@@ -1,6 +1,6 @@
 # agent-sandbox-client
 
-For the current version, use the [paired source installation guide](../docs/en/guide/install-python.md); source references below keep client and server versions matched.
+For the current version, use the [paired source installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md); source references below keep client and server versions matched.
 
 **Client SDK.** The product is Agent Sandbox. The import path is `agent_sandbox`. This package runs on your machine: create a sandbox, use it, and kill it. The HTTP service inside the image is [`agent-sandbox-server`](../server-sdk/README.md). Guide: [Client SDK](../docs/en/guide/client-sdk.md).
 
@@ -10,7 +10,7 @@ The standard root Sandbox/AsyncSandbox and code_interpreter APIs follow Alibaba-
 This package is the `agent_sandbox` import namespace *except* `agent_sandbox.server`, which is
 the container-side runtime shipped separately as
 [`agent-sandbox-server`](../server-sdk/README.md) (a hard dependency pinned to the same version,
-so [paired source installation guide](../docs/en/guide/install-python.md) still provides `agent_sandbox.server`; the `[server]` extra is a
+so [paired source installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md) still provides `agent_sandbox.server`; the `[server]` extra is a
 no-op alias kept for compatibility).
 
 The command-line tool (`abx`) is a separate Node.js project that lives in the [`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository.
@@ -19,11 +19,11 @@ The command-line tool (`abx`) is a separate Node.js project that lives in the [`
 
 ```bash
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 ```
 
 Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project.
diff --git a/docs/en/guide/client-sdk.md b/docs/en/guide/client-sdk.md
index d02fe9d..a826286 100644
--- a/docs/en/guide/client-sdk.md
+++ b/docs/en/guide/client-sdk.md
@@ -6,8 +6,8 @@ The Client SDK runs on **your machine**. It creates a sandbox, connects to one t
 
 ```bash
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 ```
 
 Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project.
diff --git a/docs/en/guide/getting-started.md b/docs/en/guide/getting-started.md
index 22a2832..4800c8a 100644
--- a/docs/en/guide/getting-started.md
+++ b/docs/en/guide/getting-started.md
@@ -19,13 +19,13 @@ This tutorial covers the lifecycle from install through teardown.
 ```bash
 # Install the SDK
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # Install with all extras (recommended)
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 ```
 
 Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project.
diff --git a/docs/en/guide/install-python.md b/docs/en/guide/install-python.md
index 45676c7..55d1292 100644
--- a/docs/en/guide/install-python.md
+++ b/docs/en/guide/install-python.md
@@ -4,12 +4,12 @@ Current development version 0.3.0 is not published on PyPI: both distribution me
 
 ## Paired immutable source
 
-Use a virtual environment with Python 3.10 or newer. This accepted native-runtime revision includes the auth and mutation-recovery fixes; it is a tested immutable source, not a claim that it is the latest main commit.
+Use a virtual environment with Python 3.10 or newer. This tested immutable implementation includes standard sync/async clients, native provider/server extensions, and the server startup acknowledgement fix. It does not claim to be the latest main commit.
 
 ```bash
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 python -m pip check
 python -c "import agent_sandbox, agent_sandbox.server; from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))"
 ```
@@ -22,8 +22,8 @@ For all extras, retain the same server URL and use the client extra on its direc
 
 ```bash
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 ```
 
 Replace `[all]` with `[mcp]`, `[declarative]`, `[session]` or `[fast]` for that subset. MCP needs its extra; the empty `[server]` alias alone does not add features. Browser automation requires separately installed Playwright in the image.
@@ -31,7 +31,7 @@ Replace `[all]` with `[mcp]`, `[declarative]`, `[session]` or `[fast]` for that
 ## Server-only image installation
 
 ```bash
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk"
+python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk"
 ```
 
 The in-sandbox service and the local client have different roles; installing the server does not create a sandbox.
diff --git a/docs/en/guide/server-sdk.md b/docs/en/guide/server-sdk.md
index 311899c..eebcb61 100644
--- a/docs/en/guide/server-sdk.md
+++ b/docs/en/guide/server-sdk.md
@@ -5,7 +5,7 @@ For current SDK installation, use the [paired source installation guide](install
 The Server SDK runs **inside the sandbox**. It is the HTTP service the image keeps listening on, port 9000 by default. The package is `agent-sandbox-server`. Import `agent_sandbox.server`. A template's `commands.py` uses it to register commands, turn capabilities on, and call `start(9000)`.
 
 ```bash
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk"
+python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk"
 ```
 
 ```python
diff --git a/docs/en/guide/troubleshooting.md b/docs/en/guide/troubleshooting.md
index 705ce8b..6f203d0 100644
--- a/docs/en/guide/troubleshooting.md
+++ b/docs/en/guide/troubleshooting.md
@@ -230,8 +230,8 @@ Check file permissions. The default user in the sandbox is `user`; you can speci
 ```bash
 # Ensure the correct package name
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # If dependency conflicts occur
 python -m pip check
diff --git a/docs/zh/guide/client-sdk.md b/docs/zh/guide/client-sdk.md
index 56f0eb7..529ab96 100644
--- a/docs/zh/guide/client-sdk.md
+++ b/docs/zh/guide/client-sdk.md
@@ -6,8 +6,8 @@ Client SDK 跑在**你的机器**上。它创建沙箱、连上已经存在的
 
 ```bash
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 ```
 
 不要执行 `pip install agent-sandbox`。PyPI 上的 `agent-sandbox` 是另一个无关项目。
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index 47efe05..61534ad 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -19,13 +19,13 @@
 ```bash
 # 安装 SDK
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # 安装全部额外依赖（推荐）
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 ```
 
 不要执行 `pip install agent-sandbox`。PyPI 上的 `agent-sandbox` 是另一个无关项目。
diff --git a/docs/zh/guide/install-python.md b/docs/zh/guide/install-python.md
index b638ff3..11eeef1 100644
--- a/docs/zh/guide/install-python.md
+++ b/docs/zh/guide/install-python.md
@@ -8,8 +8,8 @@
 
 ```bash
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 python -m pip check
 python -c "import agent_sandbox, agent_sandbox.server; from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))"
 ```
@@ -22,8 +22,8 @@ python -c "import agent_sandbox, agent_sandbox.server; from importlib.metadata i
 
 ```bash
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 ```
 
 可把 `[all]` 换成 `[mcp]`、`[declarative]`、`[session]` 或 `[fast]`。MCP 需要相应 extra；空的 `[server]` 别名本身不添加功能。浏览器自动化还需在镜像内单独安装 Playwright。
@@ -31,7 +31,7 @@ python -m pip install \
 ## 镜像内只安装服务端
 
 ```bash
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk"
+python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk"
 ```
 
 沙箱内服务端和本地客户端职责不同，安装服务端不会创建沙箱。
diff --git a/docs/zh/guide/server-sdk.md b/docs/zh/guide/server-sdk.md
index 5efc7ef..dff56bf 100644
--- a/docs/zh/guide/server-sdk.md
+++ b/docs/zh/guide/server-sdk.md
@@ -5,7 +5,7 @@
 Server SDK 跑在**沙箱里面**。它是镜像启动后一直听着的 HTTP 服务，默认端口 9000。包名是 `agent-sandbox-server`，导入 `agent_sandbox.server`。模板的 `commands.py` 用它注册命令、打开能力，然后 `start(9000)`。
 
 ```bash
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk"
+python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk"
 ```
 
 ```python
diff --git a/docs/zh/guide/troubleshooting.md b/docs/zh/guide/troubleshooting.md
index f2b26e0..0676766 100644
--- a/docs/zh/guide/troubleshooting.md
+++ b/docs/zh/guide/troubleshooting.md
@@ -230,8 +230,8 @@ entries = await sandbox.files.list("/home/user")
 ```bash
 # 确保使用正确的包名
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # 如果遇到依赖冲突
 python -m pip check
diff --git a/examples/README.md b/examples/README.md
index 01efb48..9bfb522 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -15,13 +15,13 @@ Examples are split by which package they exercise.
 ```bash
 # Full install (recommended — includes the declarative decorator, MCP server, ...)
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # Or install selectively
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[declarative] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[declarative] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # From source (run from the python-sdk repository root)
 pip install -e ./server-sdk -e ./client-sdk
diff --git a/examples/README.zh-CN.md b/examples/README.zh-CN.md
index c9e324c..39045b6 100644
--- a/examples/README.zh-CN.md
+++ b/examples/README.zh-CN.md
@@ -15,13 +15,13 @@
 ```bash
 # 完整安装（推荐，包含声明式装饰器、MCP 服务等）
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # 或按需安装
 python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[declarative] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/cceb318d58fad0096def8809165d6646029a35e2.tar.gz#subdirectory=client-sdk"
+  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk" \
+  "agent-sandbox-client[declarative] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=client-sdk"
 
 # 从源码安装（在 python-sdk 仓库根目录执行）
 pip install -e ./server-sdk -e ./client-sdk
diff --git a/server-sdk/README.md b/server-sdk/README.md
index a1ac6a7..1150195 100644
--- a/server-sdk/README.md
+++ b/server-sdk/README.md
@@ -1,6 +1,6 @@
 # agent-sandbox-server
 
-For the current version, use the [paired source installation guide](../docs/en/guide/install-python.md); source references below keep client and server versions matched.
+For the current version, use the [paired source installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md); source references below keep client and server versions matched.
 
 **Server SDK.** This package runs *inside* a sandbox image. It is the HTTP service the image starts (default port 9000). It does not create the sandbox. Creating and calling the sandbox is the [client SDK](https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/client-sdk/README.md) or the `abx` CLI. Guide: [Server SDK](https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/docs/en/guide/server-sdk.md).
 
@@ -12,7 +12,7 @@ Import path: `agent_sandbox.server` (a namespace shared with `agent-sandbox-clie
 ## Install
 
 ```bash
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/e86cb0be24e0083a27396b260298e7cf27b660d6.tar.gz#subdirectory=server-sdk"
+python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/08c51248bb3c1a6f1380bdb3d33126cda23bb7ec.tar.gz#subdirectory=server-sdk"
 ```
 
 The opt-in browser capability group imports Playwright lazily; install `playwright` in the

From 8271503c2734420a0c1d6d6f7876585fd3fcf6be Mon Sep 17 00:00:00 2001
From: anycodes <21079031+anycodes@users.noreply.github.com>
Date: Mon, 19 Oct 2026 08:52:46 +0000
Subject: [PATCH 3/6] docs: record fresh source and wheel acceptance

---
 .../evidence/verify/2026-10-19-server-start-acknowledgement.md  | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
index ca47dab..c11c60c 100644
--- a/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
+++ b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
@@ -12,3 +12,5 @@ Scope: native client helper/tests and matching bilingual server guide, based on
 - Cleanup: owned sandboxes destroyed in finally and independently listed absent, zero residuals. No template or snapshot created; no cloud/model Actions or secret upload.
 
 Build/twine and public source-pair checks are recorded with their actual result before publication. Version0.3.0 on source/wheels is not a claim of PyPI publication or current-main GitHub Release. Issue: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/69 .
+
+Final distribution/source checks: server and fixed-client sdist/wheel builds and twine metadata checks PASS. A second fresh seeded consumer installed the public immutable source archive `08c51248bb3c1a6f1380bdb3d33126cda23bb7ec` as a matching server + client[all] pair:52 dependencies resolved, pip check PASS, sync/async/native/server/interpreter imports PASS. Installed native implementation SHA256 `9d3db1f720028c3a4329bd52cd72439607b39203a2343fc285c674097c98659f` matches the exercised fix. All sixteen current install recipes point to that immutable implementation; package README guide links also render outside GitHub. Canonical website links use .cn. No package publication performed.

From 873642a51ae71297cadadefd48b9019425e03660 Mon Sep 17 00:00:00 2001
From: anycodes <21079031+anycodes@users.noreply.github.com>
Date: Mon, 19 Oct 2026 08:57:31 +0000
Subject: [PATCH 4/6] docs: correct public onboarding and security package
 names

---
 ...2026-10-19-server-start-acknowledgement.md |  2 ++
 .github/CONTRIBUTING.md                       |  6 +++---
 .github/DISCUSSION_TEMPLATE/welcome.md        | 15 +++++++------
 .github/PULL_REQUEST_TEMPLATE.md              |  2 +-
 .github/SECURITY.md                           | 10 ++++-----
 .github/discussions/welcome-post.md           | 21 ++++++-------------
 README.md                                     |  6 +++---
 README.zh-CN.md                               |  6 +++---
 docs/en/guide/command-map.md                  |  6 ++++--
 docs/en/guide/sdk-usage.md                    |  4 +---
 docs/zh/guide/command-map.md                  |  6 ++++--
 docs/zh/guide/sdk-usage.md                    |  4 +---
 12 files changed, 40 insertions(+), 48 deletions(-)

diff --git a/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
index c11c60c..75c346a 100644
--- a/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
+++ b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
@@ -14,3 +14,5 @@ Scope: native client helper/tests and matching bilingual server guide, based on
 Build/twine and public source-pair checks are recorded with their actual result before publication. Version0.3.0 on source/wheels is not a claim of PyPI publication or current-main GitHub Release. Issue: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/69 .
 
 Final distribution/source checks: server and fixed-client sdist/wheel builds and twine metadata checks PASS. A second fresh seeded consumer installed the public immutable source archive `08c51248bb3c1a6f1380bdb3d33126cda23bb7ec` as a matching server + client[all] pair:52 dependencies resolved, pip check PASS, sync/async/native/server/interpreter imports PASS. Installed native implementation SHA256 `9d3db1f720028c3a4329bd52cd72439607b39203a2343fc285c674097c98659f` matches the exercised fix. All sixteen current install recipes point to that immutable implementation; package README guide links also render outside GitHub. Canonical website links use .cn. No package publication performed.
+
+Additional public-entry-point review found stale PyPI-only instructions in native SDK usage and discussion sources, wrong distribution names in SECURITY, and an old cross-product command map. Corrected both SDK usage languages to the tested paired guide, corrected community sync example/CLI binary links, fixed owner/package labels without changing security contacts or response policy, and clearly labeled historical comparison tables while preserving their link anchors. No discussion message was posted.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 0db7d5e..36a8bb7 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -9,11 +9,11 @@ distributions that share the `agent_sandbox` namespace and are versioned in lock
 
 | Folder | PyPI distribution | Import path | Purpose |
 |--------|-------------------|-------------|---------|
-| `client-sdk/` | `agent-sandbox-client` | `agent_sandbox` | Async client SDK (`Sandbox`, `ServerClient`, `@sandbox`, MCP server, E2B migration helper, ...) |
+| `client-sdk/` | `agent-sandbox-client` | `agent_sandbox` | Standard sync/async clients and native provider/server extensions (`ProviderSandbox`, `ServerClient`, `@sandbox`, MCP server, ...) |
 | `server-sdk/` | `agent-sandbox-server` | `agent_sandbox.server` | Container-side runtime that runs inside sandbox images |
 
 The `abx` command-line tool is a separate Node.js/TypeScript project that lives in the
-`cli` repository. CLI issues and pull requests belong there, not here.
+`agent-sandbox` repository. CLI issues and pull requests belong there, not here.
 
 ## Development Setup
 
@@ -194,7 +194,7 @@ Your template repository should include:
 
 ### Searching Templates
 
-Use the CLI (`abx`, from the `cli` repository) to search the remote index:
+Use the CLI (`abx`, from the `agent-sandbox` repository) to search the remote index:
 ```bash
 abx template search python      # search by tag or keyword
 abx template search ai-agent    # find AI agent templates
diff --git a/.github/DISCUSSION_TEMPLATE/welcome.md b/.github/DISCUSSION_TEMPLATE/welcome.md
index c56e879..c08a435 100644
--- a/.github/DISCUSSION_TEMPLATE/welcome.md
+++ b/.github/DISCUSSION_TEMPLATE/welcome.md
@@ -5,7 +5,7 @@ labels: []
 
 👋 **Welcome to the Agent Sandbox community!**
 
-We're excited to have you here. Agent Sandbox is a Python SDK (and the `abx` CLI, maintained in the `cli` repository) for creating, managing, and interacting with cloud sandboxes designed for AI agents — with E2B-style method names and Alibaba Cloud authentication and templates.
+We're excited to have you here. Agent Sandbox is a Python SDK (and the `abx` CLI, maintained in the `agent-sandbox` repository) for creating, managing, and interacting with cloud sandboxes designed for AI agents — with E2B-style method names and Alibaba Cloud authentication and templates.
 
 ## 🗂️ Community Guide
 
@@ -20,19 +20,18 @@ Please use the right channel for your needs:
 
 ## 🚀 Quick Start
 
-```bash
-pip install agent-sandbox-client
-```
+Install the matching client/server pair with the [source installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md); these packages are not yet published on PyPI. Configure your local credentials as described in [getting started](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/getting-started.md).
 
 ```python
 from agent_sandbox import Sandbox
 
-async def main():
-    async with await Sandbox.create(template="python-base") as sb:
-        result = await sb.run_code("print('Hello from sandbox!')")
-        print(result.text)
+with Sandbox.create("base", timeout=60) as sb:
+    result = sb.commands.run("printf hello")
+    print(result.stdout)
 ```
 
+For code execution use [the code-interpreter guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/client-sdk.md). The separate `abx` CLI is installed through its [binary installation guide](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md).
+
 ## 📚 Resources
 
 - 📖 [Documentation](https://github.com/alibaba-agent-sandbox/python-sdk#readme)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index f8ed59a..029a448 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,7 +2,7 @@
 
 <!-- Briefly describe what this PR does -->
 
-> This repository contains the Python SDK (`client-sdk/`, `server-sdk/`). Changes to the `abx` CLI belong in the `cli` repository.
+> This repository contains the Python SDK (`client-sdk/`, `server-sdk/`). Changes to the `abx` CLI belong in the `agent-sandbox` repository.
 
 ## Type of Change
 
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
index 3c41f8f..9ee2019 100644
--- a/.github/SECURITY.md
+++ b/.github/SECURITY.md
@@ -21,8 +21,8 @@ Alternatively, report privately through GitHub Security Advisories:
 🔒 https://github.com/alibaba-agent-sandbox/python-sdk/security/advisories/new
 
 This applies to all security issues in the Agent Sandbox Python packages
-(`agent-sandbox` and `agent-sandbox-server`), the `abx` CLI (maintained in the
-`cli` repository, which follows the same private reporting process), and the
+(`agent-sandbox-client` and `agent-sandbox-server`), the `abx` CLI (maintained in the
+`agent-sandbox` repository, which follows the same private reporting process), and the
 project's code.
 
 ### What to Include
@@ -54,15 +54,15 @@ When reporting a vulnerability, please include:
 
 ## Security Best Practices for Users
 
-- Keep `agent-sandbox` and `agent-sandbox-server` updated to the latest version (they are released in lockstep)
+- Keep `agent-sandbox-client` and `agent-sandbox-server` updated to the latest version (they are released in lockstep)
 - Never commit API keys, tokens, or credentials to your repository
 - Use environment variables or the SDK's keychain for authentication
 - Review sandbox templates before deploying to production
 
 ## Scope
 
-This security policy covers the Agent Sandbox project code: the `agent-sandbox`
-and `agent-sandbox-server` Python packages, and the `abx` CLI (in the `cli`
+This security policy covers the Agent Sandbox project code: the `agent-sandbox-client`
+and `agent-sandbox-server` Python packages, and the `abx` CLI (in the `agent-sandbox`
 repository).
 
 Thank you for helping keep Agent Sandbox and its users safe! 🔒
diff --git a/.github/discussions/welcome-post.md b/.github/discussions/welcome-post.md
index a885276..cce3e6c 100644
--- a/.github/discussions/welcome-post.md
+++ b/.github/discussions/welcome-post.md
@@ -4,7 +4,7 @@ Hey everyone! Welcome to the **Agent Sandbox** community — we're thrilled to h
 
 ## What is Agent Sandbox?
 
-Agent Sandbox is a Python SDK (and the `abx` CLI, maintained in the `cli` repository) for creating, managing, and interacting with cloud sandboxes designed for AI agents. It uses E2B-style method names to ease porting, and adds Alibaba Cloud authentication and templates. Whether you're building autonomous agents, code interpreters, or secure execution environments, Agent Sandbox gives you the tools to do it with zero-config simplicity.
+Agent Sandbox is a Python SDK (and the `abx` CLI, maintained in the `agent-sandbox` repository) for creating, managing, and interacting with cloud sandboxes designed for AI agents. It uses E2B-style method names to ease porting, and adds Alibaba Cloud authentication and templates. Whether you're building autonomous agents, code interpreters, or secure execution environments, Agent Sandbox gives you the tools to do it with zero-config simplicity.
 
 ## 🗂️ How to Use This Community
 
@@ -19,26 +19,17 @@ We want to keep things organized so everyone can find what they need:
 
 ## 🚀 Quick Start
 
-```bash
-pip install agent-sandbox-client
-```
+Install the matching client/server pair with the [source installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md); these packages are not yet published on PyPI. Configure your local credentials as described in [getting started](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/getting-started.md).
 
 ```python
 from agent_sandbox import Sandbox
 
-async def main():
-    async with await Sandbox.create(template="python-base") as sb:
-        result = await sb.run_code("print('Hello from sandbox!')")
-        print(result.text)  # Hello from sandbox!
+with Sandbox.create("base", timeout=60) as sb:
+    result = sb.commands.run("printf hello")
+    print(result.stdout)
 ```
 
-Or use the CLI (a separate Node.js project in the `cli` repository):
-
-```bash
-npm install -g @agent-sandbox/cli
-abx create --template python-base
-abx exec <sandbox-id> "echo hello"
-```
+For code execution use [the code-interpreter guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/client-sdk.md). The separate `abx` CLI is installed through its [binary installation guide](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md).
 
 ## 📚 Key Links
 
diff --git a/README.md b/README.md
index 249dc6a..ffc5904 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ standard sync/async runtime and Template client. Project provider/server templat
 ports with few changes; the standard API follows Alibaba-supported E2B behavior (see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md)).
 
 This repository (`python-sdk`) contains the **Python SDK**, packaged as two lock-step distributions. The `abx` command-line tool is a separate Node.js project that lives in the
-[`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository (see [Related: the abx CLI](#related-the-abx-cli)).
+[`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository (see [Related: the abx CLI](#related-the-abx-cli)).
 
 | Folder | Distribution | Import path | Purpose |
 |--------|-------------------|-------------|---------|
@@ -87,7 +87,7 @@ Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated projec
 `agent-sandbox-client` depends on `agent-sandbox-server` of the same version, so installing the [paired sources](docs/en/guide/install-python.md) also provides `agent_sandbox.server` (needed locally by the `@sandbox` decorator's server proxy). The `[server]` extra is kept as a harmless alias.
 
 The `abx` CLI is no longer part of the Python package (there is no `[cli]` extra and no `abx`
-console script); it is distributed from the [`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository
+console script); it is distributed from the [`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository
 (see [Related: the abx CLI](#related-the-abx-cli)).
 
 ## Quick Start
@@ -246,7 +246,7 @@ Lower layers never import upper layers. Full design: [`docs/en/design/architectu
 ## Related: the abx CLI
 
 The `abx` command-line tool (`@agent-sandbox/cli`, Node.js) is developed in the
-[`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository. It shares sandboxes, templates and
+[`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository. It shares sandboxes, templates and
 credentials with this SDK. Its installation, command reference, tutorials, MCP server
 commands and the Agent Skill (`SKILL.md`) are documented there:
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index feecb21..9c59efd 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -14,7 +14,7 @@
 方便 E2B 代码迁移，标准接口遵循阿里云支持版本的行为契约（见[从 E2B 迁移](docs/zh/guide/migrate-from-e2b.md)）。
 
 本仓库（`python-sdk`）包含 **Python SDK**，以两个版本同步的分发包提供。命令行工具 `abx` 是独立的
-Node.js 项目，位于 [`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库（见[相关：abx CLI](#相关abx-cli)）。
+Node.js 项目，位于 [`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库（见[相关：abx CLI](#相关abx-cli)）。
 
 | 目录 | PyPI 分发包 | 导入路径 | 用途 |
 |------|-------------|----------|------|
@@ -85,7 +85,7 @@ pip install -e ./server-sdk -e "./client-sdk[dev]"
 `agent-sandbox-client` 依赖同版本的 `agent-sandbox-server`，因此 [配套源码安装指南](docs/zh/guide/install-python.md) 同样会提供 `agent_sandbox.server`（`@sandbox` 装饰器的 server 代理在本地需要它）。`[server]` extra 作为无害的别名保留。
 
 `abx` CLI 不再属于 Python 包（不再有 `[cli]` extra，也没有 `abx` 控制台脚本），由
-[`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库分发（见[相关：abx CLI](#相关abx-cli)）。
+[`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库分发（见[相关：abx CLI](#相关abx-cli)）。
 
 ## 快速开始
 
@@ -238,7 +238,7 @@ graph TB
 
 ## 相关：abx CLI
 
-命令行工具 `abx`（`@agent-sandbox/cli`，Node.js）在 [`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库中开发，
+命令行工具 `abx`（`@agent-sandbox/cli`，Node.js）在 [`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库中开发，
 与本 SDK 共享沙箱、模板与凭证。其安装方式、命令参考、教程、MCP Server 命令以及 Agent Skill（`SKILL.md`）
 均在该仓库中维护：
 
diff --git a/docs/en/guide/command-map.md b/docs/en/guide/command-map.md
index 4434368..88234aa 100644
--- a/docs/en/guide/command-map.md
+++ b/docs/en/guide/command-map.md
@@ -1,8 +1,10 @@
 # Command and SDK map
 
+> Historical native-interface comparison: these tables predate the current standard CLI/client migration and do not specify the current command surface. For working installation and current APIs, use [Python installation](install-python.md), [E2B migration](migrate-from-e2b.md), [native SDK usage](sdk-usage.md), and the [current CLI README](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox#readme). External product versions below are historical references.
+
 Each row is the closest entry point for the same job in the three products. It is not parameter-for-parameter compatibility, and it does not shrink Agent Sandbox to a subset of either product.
 
-`abx` is the Agent Sandbox command line. The Python SDK is `agent-sandbox`. The default provider is Alibaba Cloud Express. After the `opensandbox` provider is installed, the `abx` command names stay the same and the calls go to an OpenSandbox server. That is a different command from running `osb`.
+`abx` is the Agent Sandbox command line. The Python distribution is `agent-sandbox-client`. The default provider is Alibaba Cloud Express. After the `opensandbox` provider is installed, the `abx` command names stay the same and the calls go to an OpenSandbox server. That is a different command from running `osb`.
 
 Public surfaces used for this map:
 
@@ -20,7 +22,7 @@ A cell with "—" means that side has no matching public command or method.
 
 | Job | abx | Agent Sandbox SDK | e2b | E2B SDK | osb | OpenSandbox SDK |
 |---|---|---|---|---|---|---|
-| Install | `npm install -g @agent-sandbox/cli` | `pip install agent-sandbox-client` | `npm install -g @e2b/cli` | `pip install e2b` | `pip install opensandbox-cli` | `pip install opensandbox` |
+| Install | [CLI binary installation](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md) | [Paired source install](install-python.md) | `npm install -g @e2b/cli` | `pip install e2b` | `pip install opensandbox-cli` | `pip install opensandbox` |
 | Store a credential | `abx config set sandbox_api_key` | environment variable `E2B_API_KEY` | `e2b auth login` | environment variable `E2B_API_KEY` | `osb config set connection.api_key` | `ConnectionConfig(api_key=…)` or `OPEN_SANDBOX_API_KEY` |
 | Show the effective config | `abx config list` | — | `e2b auth info` | — | `osb config show` | — |
 
diff --git a/docs/en/guide/sdk-usage.md b/docs/en/guide/sdk-usage.md
index 5d8204a..0aadcc4 100644
--- a/docs/en/guide/sdk-usage.md
+++ b/docs/en/guide/sdk-usage.md
@@ -6,9 +6,7 @@ This page documents the asynchronous **ProviderSandbox** provider/server extensi
 
 ## Installation
 
-```bash
-pip install agent-sandbox-client
-```
+Follow the [paired source installation guide](install-python.md). The client/server0.3.0 packages are not yet published on PyPI; install both from the same tested revision.
 
 Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project.
 
diff --git a/docs/zh/guide/command-map.md b/docs/zh/guide/command-map.md
index 97f5017..4619f5f 100644
--- a/docs/zh/guide/command-map.md
+++ b/docs/zh/guide/command-map.md
@@ -1,5 +1,7 @@
 # 命令与 SDK 对照
 
+> 历史原生接口对照：下表早于当前标准 CLI/客户端迁移，不定义当前命令面。请以[Python 安装](install-python.md)、[E2B 迁移](migrate-from-e2b.md)、[原生 SDK 使用](sdk-usage.md)和[当前 CLI README](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox#readme)为准；下列其他产品版本也仅为历史参考。
+
 同一行是同一件事在三家产品里的最近入口。它不是参数级兼容，也不是把 Agent Sandbox 收成其中一家的子集。
 
 `abx` 是 Agent Sandbox 的命令行。Python SDK 是 `agent-sandbox-client`。默认提供方是阿里云极速版。装上 `opensandbox` 提供方之后，`abx` 的命令名不变，请求改发到 OpenSandbox 服务。那和直接运行 `osb` 不是同一条命令。
@@ -8,7 +10,7 @@
 
 | 产品 | 命令行 | SDK |
 |---|---|---|
-| Agent Sandbox | `abx`（`@agent-sandbox/cli`） | `agent-sandbox`，`from agent_sandbox.api.sandbox import Sandbox` |
+| Agent Sandbox | `abx`（`@agent-sandbox/cli`） | `agent-sandbox-client`，`from agent_sandbox.api.sandbox import Sandbox` |
 | E2B | `e2b`（`@e2b/cli`，文档版本 2.16.1） | `e2b`，`from e2b import Sandbox` |
 | OpenSandbox | `osb`（`opensandbox-cli`，[CLI 文档](https://open-sandbox.ai/cli/)） | `opensandbox`，`from opensandbox import Sandbox`（[Python SDK](https://open-sandbox.ai/sdks/python)） |
 
@@ -20,7 +22,7 @@ E2B 形状的少量方法也可以从 `agent_sandbox.compat` 导入。差异和
 
 | 做什么 | abx | Agent Sandbox SDK | e2b | E2B SDK | osb | OpenSandbox SDK |
 |---|---|---|---|---|---|---|
-| 安装 | `npm install -g @agent-sandbox/cli` | `pip install agent-sandbox-client` | `npm install -g @e2b/cli` | `pip install e2b` | `pip install opensandbox-cli` | `pip install opensandbox` |
+| 安装 | [CLI binary installation](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md) | [Paired source install](install-python.md) | `npm install -g @e2b/cli` | `pip install e2b` | `pip install opensandbox-cli` | `pip install opensandbox` |
 | 写入凭证 | `abx config set sandbox_api_key` | 环境变量 `E2B_API_KEY` | `e2b auth login` | 环境变量 `E2B_API_KEY` | `osb config set connection.api_key` | `ConnectionConfig(api_key=…)` 或 `OPEN_SANDBOX_API_KEY` |
 | 查看生效配置 | `abx config list` | — | `e2b auth info` | — | `osb config show` | — |
 
diff --git a/docs/zh/guide/sdk-usage.md b/docs/zh/guide/sdk-usage.md
index 3c6f819..0c015d7 100644
--- a/docs/zh/guide/sdk-usage.md
+++ b/docs/zh/guide/sdk-usage.md
@@ -7,9 +7,7 @@
 
 ## 安装
 
-```bash
-pip install agent-sandbox-client
-```
+请按[配套源码安装指南](install-python.md)安装。客户端/服务端0.3.0尚未发布到 PyPI；应从同一已验证提交安装两个发行包。
 
 不要执行 `pip install agent-sandbox`。PyPI 上的 `agent-sandbox` 是另一个无关项目。
 

From 3a00bb2626d0a8e6a1eb6c0bb874e0b57fdd4079 Mon Sep 17 00:00:00 2001
From: anycodes <21079031+anycodes@users.noreply.github.com>
Date: Mon, 19 Oct 2026 08:58:17 +0000
Subject: [PATCH 5/6] docs: align bilingual immutable source scope

---
 docs/en/guide/install-python.md | 2 +-
 docs/zh/guide/install-python.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/en/guide/install-python.md b/docs/en/guide/install-python.md
index 55d1292..7644725 100644
--- a/docs/en/guide/install-python.md
+++ b/docs/en/guide/install-python.md
@@ -1,6 +1,6 @@
 # Install the Python packages
 
-Current development version 0.3.0 is not published on PyPI: both distribution metadata endpoints returned 404 on 2026-10-18. Package names do not prove publication. Use the tested paired source recipe below or a development checkout. The CLI is installed separately from its own repository.
+Current development version 0.3.0 is not published on PyPI: both distribution metadata endpoints returned 404 on 2026-10-19. Package names do not prove publication. Use the tested paired source recipe below or a development checkout. The CLI is installed separately from its own repository.
 
 ## Paired immutable source
 
diff --git a/docs/zh/guide/install-python.md b/docs/zh/guide/install-python.md
index 11eeef1..fcd16f7 100644
--- a/docs/zh/guide/install-python.md
+++ b/docs/zh/guide/install-python.md
@@ -1,10 +1,10 @@
 # 安装 Python 配套包
 
-当前开发版本0.3.0尚未发布到 PyPI：2026-10-18 两个发行包的元数据端点均返回404。包名存在于项目中不等于已发布。请使用下面验证过的配套源码安装方式，或从开发检出安装。CLI 从其独立仓库安装。
+当前开发版本0.3.0尚未发布到 PyPI：2026-10-19 两个发行包的元数据端点均返回404。包名存在于项目中不等于已发布。请使用下面验证过的配套源码安装方式，或从开发检出安装。CLI 从其独立仓库安装。
 
 ## 固定提交的配套源码
 
-使用 Python 3.10或更高版本及虚拟环境。这个已验收的原生运行时提交包含鉴权、变更请求恢复修复；它是已测试的固定来源，不代表最新主线提交。
+使用 Python 3.10或更高版本及虚拟环境。此已验证的固定实现包含标准同步/异步客户端、原生 Provider/server 扩展及服务启动确认修复；并不声称它是最新主线提交。
 
 ```bash
 python -m pip install \

From e405535a203b772cc8af2a314795ee55609b88bb Mon Sep 17 00:00:00 2001
From: anycodes <21079031+anycodes@users.noreply.github.com>
Date: Mon, 19 Oct 2026 09:01:01 +0000
Subject: [PATCH 6/6] docs: reconcile implementation record lifecycle

---
 .agents/README.md                                           | 2 +-
 .../verify/2026-10-19-server-start-acknowledgement.md       | 2 ++
 .../feature/2026-10-19-server-start-acknowledgement.md      | 6 +++++-
 3 files changed, 8 insertions(+), 2 deletions(-)
 rename .agents/notes/{proposed => implemented}/feature/2026-10-19-server-start-acknowledgement.md (87%)

diff --git a/.agents/README.md b/.agents/README.md
index 6d650b8..7becc14 100644
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -92,4 +92,4 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 
 - [Conditional Express acceptance](notes/proposed/feature/2026-10-19-conditional-acceptance.md) · [verification](evidence/verify/2026-10-19-conditional-acceptance.md)
 
-- [Dispatch native server startup before readiness](notes/proposed/feature/2026-10-19-server-start-acknowledgement.md) · [verification](evidence/verify/2026-10-19-server-start-acknowledgement.md)
+- [Dispatch native server startup before readiness](notes/implemented/feature/2026-10-19-server-start-acknowledgement.md) · [verification](evidence/verify/2026-10-19-server-start-acknowledgement.md)
diff --git a/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
index 75c346a..b7ccaef 100644
--- a/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
+++ b/.agents/evidence/verify/2026-10-19-server-start-acknowledgement.md
@@ -16,3 +16,5 @@ Build/twine and public source-pair checks are recorded with their actual result
 Final distribution/source checks: server and fixed-client sdist/wheel builds and twine metadata checks PASS. A second fresh seeded consumer installed the public immutable source archive `08c51248bb3c1a6f1380bdb3d33126cda23bb7ec` as a matching server + client[all] pair:52 dependencies resolved, pip check PASS, sync/async/native/server/interpreter imports PASS. Installed native implementation SHA256 `9d3db1f720028c3a4329bd52cd72439607b39203a2343fc285c674097c98659f` matches the exercised fix. All sixteen current install recipes point to that immutable implementation; package README guide links also render outside GitHub. Canonical website links use .cn. No package publication performed.
 
 Additional public-entry-point review found stale PyPI-only instructions in native SDK usage and discussion sources, wrong distribution names in SECURITY, and an old cross-product command map. Corrected both SDK usage languages to the tested paired guide, corrected community sync example/CLI binary links, fixed owner/package labels without changing security contacts or response policy, and clearly labeled historical comparison tables while preserving their link anchors. No discussion message was posted.
+
+Delivery review: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/70 . Decision moved with matching implemented status; this file does not claim a future merge or deployment. Latest-head hosted checks remain mandatory.
diff --git a/.agents/notes/proposed/feature/2026-10-19-server-start-acknowledgement.md b/.agents/notes/implemented/feature/2026-10-19-server-start-acknowledgement.md
similarity index 87%
rename from .agents/notes/proposed/feature/2026-10-19-server-start-acknowledgement.md
rename to .agents/notes/implemented/feature/2026-10-19-server-start-acknowledgement.md
index 9f9f050..cf17f77 100644
--- a/.agents/notes/proposed/feature/2026-10-19-server-start-acknowledgement.md
+++ b/.agents/notes/implemented/feature/2026-10-19-server-start-acknowledgement.md
@@ -1,6 +1,6 @@
 # Decision: Dispatch native server startup before readiness
 
-Status: proposed
+Status: implemented
 
 ## Problem
 
@@ -29,3 +29,7 @@ Reproduce zero dispatch with a real lazy reader, then verify acknowledgement, wa
 ## Acceptance criteria
 
 New behavior regressions pass; clean artifacts install with matched versions; real named command and retained-server receipt passes; no owned sandbox remains; latest-head required CI passes before merge. Source installation recipes pin a tested immutable implementation.
+
+## Implementation
+
+Implementation and scoped local verification are complete. Hosted checks and actual merge state are separate gates recorded in the PR; public deployment readback, where applicable, remains a post-merge acceptance check. No package release is implied.