anycodes · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git 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/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
@@ -0,0 +1,20 @@
+# 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 .
+
+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/implemented/feature/2026-10-19-server-start-acknowledgement.md b/.agents/notes/implemented/feature/2026-10-19-server-start-acknowledgement.md
@@ -0,0 +1,35 @@
+# Decision: Dispatch native server startup before readiness
+
+Status: implemented
+
+## 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.
+
+## 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.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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/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/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 |
 |--------|-------------------|-------------|---------|
@@ -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)
@@ -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:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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/implemented/feature/2026-10-19-server-start-acknowledgement.md) · [verification](evidence/verify/2026-10-19-server-start-acknowledgement.md)