docs: correct ProviderSandbox parameter help and prepare alpha a4

.agents/README.md

@@ -189,3 +189,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 - [Prepared-template readiness](notes/proposed/feature/2026-10-25-prepared-template-readiness.md) · [verification](evidence/verify/2026-10-25-prepared-template-readiness.md).
 
 - [Current public a3 guidance](notes/proposed/process/2026-10-25-current-public-a3.md) · [verification](evidence/verify/2026-10-25-public-a3-docs.md).
+
+- [Provider parameter documentation correction](notes/proposed/process/2026-10-25-provider-parameter-docstrings.md) · [candidate verification](evidence/verify/2026-10-25-provider-parameter-docstrings.md). Candidate a4 is not yet a public-install recommendation.

.agents/evidence/verify/2026-10-25-provider-parameter-docstrings-wheel-http.json

@@ -0,0 +1,16 @@
+{
+  "packages": {
+    "agent-sandbox-client": "0.4.0a4",
+    "agent-sandbox-server": "0.4.0a4"
+  },
+  "source_install": false,
+  "scope": "candidate wheels, real local HTTP; no cloud or model call",
+  "health": true,
+  "shell_exit": 0,
+  "shell_stdout": "4\n",
+  "file_roundtrip": true,
+  "owned_process_exit": -15,
+  "owned_pid_independently_absent": true,
+  "script_sha256": "49571ac7a80e2e24c7329d3adc3527a0f2ede0f17e54f18af97ce846d9a7a701",
+  "result": "PASS"
+}

.agents/evidence/verify/2026-10-25-provider-parameter-docstrings.json

@@ -0,0 +1,59 @@
+{
+  "candidate_version": "0.4.0a4",
+  "base": "53956043008d0658340448c97fcb453387da62d1",
+  "methods": {
+    "create": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "create_sync": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "connect": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "connect_sync": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "list": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "list_sync": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "kill_by_id": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "kill_by_id_sync": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "get_info_by_id": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "get_info_by_id_sync": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "set_timeout_by_id": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    },
+    "set_timeout_by_id_sync": {
+      "signature_unchanged": true,
+      "documented_names_valid": true
+    }
+  },
+  "actual_old_keyword_rejections": 24,
+  "network_calls": 0,
+  "provider_executable_ast_unchanged": true,
+  "standard_ApiParams_unchanged": true,
+  "result": "PASS"
+}

.agents/evidence/verify/2026-10-25-provider-parameter-docstrings.md

@@ -0,0 +1,53 @@
+# Provider lifecycle parameter documentation verification
+
+Date: 2026-10-25
+Result: PARTIAL (candidate checks; publication and final delivery pending)
+
+Base: main 53956043008d0658340448c97fcb453387da62d1. Issue:
+https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/124.
+Candidate client/server 0.4.0a4; not yet public. Current public install recipes
+remain a3. No old publication evidence was edited.
+
+## Actual scope
+
+Fresh installed public a3 exposed four stale original lifecycle docstrings and
+four copied synchronous docstrings. create/connect/list documented removed
+api_key/api_url (and domain on create/connect); kill_by_id additionally listed
+sandbox_domain absent from its actual signature. No compatibility behavior exists.
+get_info_by_id/set_timeout_by_id themselves list no stale parameters, but refer
+to kill_by_id for override help.
+
+Candidate introspection: all 12 create/connect/list/kill/info/timeout async/sync
+signatures equal the public-a3 signatures; all documented argument names match
+those signatures. All 24 actual calls with retired api_key/api_url/domain fail
+with TypeError before any coroutine/provider/network request. The standard
+ApiParams contract still contains all three valid standard-client names.
+Executable AST of api/sandbox.py equals the base after removing docstrings.
+[Sanitized contract receipt](2026-10-25-provider-parameter-docstrings.json).
+
+## Checks
+
+- New signature/help regression: 12 PASS.
+- Focused lifecycle, standard-contract and documentation suite: 101 PASS.
+- Both packages lint, format and mypy: PASS.
+- Full client `pytest tests -m "not integration"`: 2277 PASS, 26 SKIP, 10 deselected.
+- Full server: 878 PASS, 2 FAIL. The same previously observed local raw-HTTP
+  expectations fail: Responses WebSocket upgrade without a key returns 501 rather
+  than 400; policy Transfer-Encoding framing returns 502 rather than 400.
+  No assertion was weakened and no server executable statement changed. Required
+  remote Python 3.10/3.11/3.12 matrices must independently pass before merge.
+- Four candidate wheel/sdist builds, `make dist-check`, fresh combined-wheel
+  installation/imports and pip check: PASS. A uv-created runtime environment
+  initially had no pip module; seeding pip fixed that tooling prerequisite.
+- Real HTTP from the installed candidate wheels: health, authenticated shell
+  result 4, file round-trip and owned server SIGTERM -15: PASS. Exact owned PID
+  independently absent. [Local HTTP receipt](2026-10-25-provider-parameter-docstrings-wheel-http.json).
+- Document/record health: 106 PASS, one warning, zero failures; hygiene and diff
+  checks: PASS.
+- Exact latest-head 13-check CI, independent review, normal merge and immutable
+  a4 publication/official fresh install: pending.
+
+This change does not alter provider/server behavior or the readiness fix. No new
+cloud resources/model calls were created for docstrings; existing real Docker
+fixture jobs remain required owner gates. Earlier real public-a3 cloud results
+retain their original version scope and do not become a4 evidence.

.agents/notes/proposed/process/2026-10-25-provider-parameter-docstrings.md

@@ -0,0 +1,55 @@
+# Decision: Match provider parameter help to the callable contract
+
+Status: proposed
+
+## Problem
+
+Public a3 ProviderSandbox.create, connect, list and kill_by_id still document
+removed api_key/api_url/domain parameters and alias-agreement behavior. Their
+four generated synchronous wrappers copy those docstrings. kill_by_id also
+lists sandbox_domain, which its control-plane signature does not accept.
+
+## Decision
+
+Describe only the actual sandbox_api_key and sandbox_base_url overrides, plus
+sandbox_domain on create/connect/list. Remove nonexistent parameters and alias
+claims. Keep every signature and executable provider statement unchanged.
+Prepare lockstep client/server 0.4.0a4 for immutable package delivery; do not
+recommend installing it before its successful official publication/readback.
+
+## API Design
+
+No new API, alias, fallback or schema. Standard Sandbox/AsyncSandbox ApiParams
+retain their valid api_key/api_url/domain contract. get_info_by_id and
+set_timeout_by_id keep their existing reference to the corrected kill_by_id help.
+
+## Alternatives considered
+
+Restoring aliases contradicts the current contract and the maintainer's request.
+Overwriting public a3 artifacts is prohibited. A generic documentation framework
+or broad parameter renaming is unnecessary for four source docstrings.
+
+## Dependencies
+
+- https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/124
+- https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/123
+- https://github.com/Alibaba-Agent-Sandbox/python-sdk/releases/tag/v0.4.0a3
+
+## Test Strategy
+
+Compare real installed public-a3 signatures/help against the candidate. Verify
+all 12 lifecycle async/sync signatures are unchanged, document names are valid,
+and 24 actual retired-keyword calls still reject before any provider/network
+operation. Compare executable AST after excluding docstrings. Run the focused
+regression, owner lint/type/tests/build/distribution checks and exact-head CI.
+After review/merge, use the existing immutable release and official readback flow.
+
+## Acceptance criteria
+
+Four original docstrings and copied sync help match actual signatures; no runtime
+contract changes. Bilingual configuration guidance and changelog are updated.
+Owner checks, independent review and normal merge pass before publication. Public
+artifact verification/fresh install receive new evidence; previous a3 evidence
+and current installation claims remain accurate.
+
+[Verification](../../../evidence/verify/2026-10-25-provider-parameter-docstrings.md).

CHANGELOG.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Fixed
 
+- Align ProviderSandbox lifecycle parameter docstrings and copied synchronous docs with their actual canonical signatures; remove nonexistent alias/domain entries without changing runtime behavior. Prepare lockstep client/server 0.4.0a4. / 对齐 ProviderSandbox 生命周期及同步版本文档与真实规范参数，删除不存在的别名和域名参数说明；运行行为不变，准备同版本双包 0.4.0a4。
+
 - Wait for prepared-template readiness inside one bounded `readiness_timeout` instead of failing after the first early nonzero probe; preserve timeout/cancellation cleanup. Prepare lockstep client/server 0.4.0a3 without changing published a2 artifacts. / 修复模板进程启动后首次就绪探测过早失败的问题，在单一预算内等待就绪，并保留超时和取消时的资源清理；准备同版本双包 0.4.0a3，不覆盖公开 a2。
 
 - Build both SDK offline fixtures from the exact public a2 server on official PyPI, remove unreachable local-wheel fallback, and verify actual guest HTTP behavior and cleanup in CI. / SDK 两个离线夹具统一从官方 PyPI 安装精确 a2 服务端，删除不可达的本地 wheel 回退，并通过 CI 验证真实镜像 HTTP 行为及清理。

client-sdk/pyproject.toml

@@ -44,7 +44,7 @@ dependencies = [
     "tomli>=2.0; python_version < '3.11'",
     # The client uses the matching local server runtime for its server/declarative helpers.
     # Keep the required distribution version equal to ``_version.py``.
-    "agent-sandbox-server==0.4.0a3",
+    "agent-sandbox-server==0.4.0a4",
 ]
 
 [project.optional-dependencies]

client-sdk/src/agent_sandbox/_version.py

@@ -1 +1 @@
-__version__ = "0.4.0a3"
+__version__ = "0.4.0a4"

client-sdk/src/agent_sandbox/api/sandbox.py

@@ -635,13 +635,10 @@ async def create(
                 the built-in provider behaves as ``True`` (port access requires an access
                 token) and plugin providers receive no ``secure`` hint, so their own default
                 applies. Pass ``True``/``False`` to send an explicit request.
-            api_key: API key override.
-            api_url: Platform API URL override.
-            domain: Platform domain for port URL computation.
             access_key_id: AK/SK access key ID.
             access_key_secret: AK/SK access key secret.
-            sandbox_api_key: Canonical name of *api_key* (same value; a different one is an error).
-            sandbox_base_url: Canonical name of *api_url*.
+            sandbox_api_key: Sandbox platform API key override.
+            sandbox_base_url: Sandbox platform API base URL override.
             sandbox_domain: Provider data-plane domain.
             region: Built-in provider region (derives the API URL and domain).
             provider: Provider id (or a ``Provider`` object). Default: ``ABX_PROVIDER`` /
@@ -713,13 +710,10 @@ async def connect(
 
         Args:
             sandbox_id: The ID of the sandbox to connect to.
-            api_key: API key override.
-            api_url: Platform API URL override.
-            domain: Platform domain for port URL computation.
             access_key_id: AK/SK access key ID.
             access_key_secret: AK/SK access key secret.
-            sandbox_api_key: Canonical name of *api_key* (same value; a different one is an error).
-            sandbox_base_url: Canonical name of *api_url*.
+            sandbox_api_key: Sandbox platform API key override.
+            sandbox_base_url: Sandbox platform API base URL override.
             sandbox_domain: Provider data-plane domain.
             region: Built-in provider region (derives the API URL and domain).
             provider: Provider id (or a ``Provider`` object). Default: ``ABX_PROVIDER`` /
@@ -767,12 +761,10 @@ async def list(
             status: Filter by sandbox status.
             limit: Maximum number of sandboxes to return.
             offset: Pagination offset.
-            api_key: API key override.
-            api_url: Platform API URL override.
             access_key_id: AK/SK access key ID.
             access_key_secret: AK/SK access key secret.
-            sandbox_api_key: Canonical name of *api_key* (same value; a different one is an error).
-            sandbox_base_url: Canonical name of *api_url*.
+            sandbox_api_key: Sandbox platform API key override.
+            sandbox_base_url: Sandbox platform API base URL override.
             sandbox_domain: Provider data-plane domain.
             region: Built-in provider region (derives the API URL and domain).
             provider: Provider id (or a ``Provider`` object). Default: ``ABX_PROVIDER`` /
@@ -927,13 +919,10 @@ async def kill_by_id(
 
         Args:
             sandbox_id: The ID of the sandbox to kill.
-            api_key: API key override.
-            api_url: Platform API URL override.
             access_key_id: AK/SK access key ID.
             access_key_secret: AK/SK access key secret.
-            sandbox_api_key: Canonical name of *api_key* (same value; a different one is an error).
-            sandbox_base_url: Canonical name of *api_url*.
-            sandbox_domain: Provider data-plane domain.
+            sandbox_api_key: Sandbox platform API key override.
+            sandbox_base_url: Sandbox platform API base URL override.
             region: Built-in provider region (derives the API URL and domain).
             provider: Provider id (or a ``Provider`` object). Default: ``ABX_PROVIDER`` /
                 ``[core] provider`` / ``alicloud-express``. A qualified ``provider:id``

client-sdk/tests/test_api/test_provider_docstrings.py

@@ -0,0 +1,31 @@
+"""Keep ProviderSandbox lifecycle help aligned with its callable parameters."""
+
+import inspect
+import re
+
+import pytest
+
+from agent_sandbox import ProviderSandbox
+
+
+@pytest.mark.parametrize(
+    "method_name",
+    [
+        name + suffix
+        for name in (
+            "create",
+            "connect",
+            "list",
+            "kill_by_id",
+            "get_info_by_id",
+            "set_timeout_by_id",
+        )
+        for suffix in ("", "_sync")
+    ],
+)
+def test_lifecycle_docstrings_match_signatures(method_name: str) -> None:
+    method = getattr(ProviderSandbox, method_name)
+    doc = inspect.getdoc(method) or ""
+    documented_parameters = set(re.findall(r"^    ([a-z_]+):", doc, re.MULTILINE))
+    assert documented_parameters <= inspect.signature(method).parameters.keys()
+    assert not re.search(r"\*(?:api_key|api_url)\*", doc)

docs/en/reference/configuration.md

@@ -202,6 +202,8 @@ explain_config()   # {"sandbox_api_key": {"value": "****3dc1", "source": "enviro
 
 ## SDK Parameter Override
 
+`ProviderSandbox.create`, `connect` and `list` accept only `sandbox_api_key`, `sandbox_base_url` and `sandbox_domain` for these overrides. Control-plane `kill_by_id`, `get_info_by_id` and `set_timeout_by_id` accept the first two and do not need a data-plane domain. Their `_sync` variants use the same parameters. Standard `Sandbox` / `AsyncSandbox` retain their separate `ApiParams` contract.
+
 Pass parameters directly in code (highest priority):
 
 ```python

docs/zh/reference/configuration.md

@@ -202,6 +202,8 @@ explain_config()   # {"sandbox_api_key": {"value": "****3dc1", "source": "enviro
 
 ## SDK 参数覆盖
 
+`ProviderSandbox.create`、`connect` 和 `list` 的这些覆盖参数仅为 `sandbox_api_key`、`sandbox_base_url` 和 `sandbox_domain`。控制面方法 `kill_by_id`、`get_info_by_id` 和 `set_timeout_by_id` 接受前两个参数，不需要数据面域名；其 `_sync` 版本使用相同参数。标准 `Sandbox` / `AsyncSandbox` 保留各自的 `ApiParams` 契约。
+
 在代码中直接传参（最高优先级）：
 
 ```python

server-sdk/src/agent_sandbox/server/_version.py

@@ -1 +1 @@
-__version__ = "0.4.0a3"
+__version__ = "0.4.0a4"