From 5b91f5d38de8c2e63daba4e455207e1601a930b0 Mon Sep 17 00:00:00 2001 From: AnyEnv Sandbox Date: Sun, 25 Oct 2026 17:05:55 +0000 Subject: [PATCH] docs: align provider lifecycle help with canonical parameters --- .agents/README.md | 2 + ...vider-parameter-docstrings-wheel-http.json | 16 +++++ ...6-10-25-provider-parameter-docstrings.json | 59 +++++++++++++++++++ ...026-10-25-provider-parameter-docstrings.md | 53 +++++++++++++++++ ...026-10-25-provider-parameter-docstrings.md | 55 +++++++++++++++++ CHANGELOG.md | 2 + client-sdk/pyproject.toml | 2 +- client-sdk/src/agent_sandbox/_version.py | 2 +- client-sdk/src/agent_sandbox/api/sandbox.py | 27 +++------ .../test_api/test_provider_docstrings.py | 31 ++++++++++ docs/en/reference/configuration.md | 2 + docs/zh/reference/configuration.md | 2 + .../src/agent_sandbox/server/_version.py | 2 +- 13 files changed, 233 insertions(+), 22 deletions(-) create mode 100644 .agents/evidence/verify/2026-10-25-provider-parameter-docstrings-wheel-http.json create mode 100644 .agents/evidence/verify/2026-10-25-provider-parameter-docstrings.json create mode 100644 .agents/evidence/verify/2026-10-25-provider-parameter-docstrings.md create mode 100644 .agents/notes/proposed/process/2026-10-25-provider-parameter-docstrings.md create mode 100644 client-sdk/tests/test_api/test_provider_docstrings.py diff --git a/.agents/README.md b/.agents/README.md index 018cc3d6..e9227e47 100644 --- a/.agents/README.md +++ b/.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. diff --git a/.agents/evidence/verify/2026-10-25-provider-parameter-docstrings-wheel-http.json b/.agents/evidence/verify/2026-10-25-provider-parameter-docstrings-wheel-http.json new file mode 100644 index 00000000..74b648d9 --- /dev/null +++ b/.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" +} diff --git a/.agents/evidence/verify/2026-10-25-provider-parameter-docstrings.json b/.agents/evidence/verify/2026-10-25-provider-parameter-docstrings.json new file mode 100644 index 00000000..6f3de28a --- /dev/null +++ b/.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" +} diff --git a/.agents/evidence/verify/2026-10-25-provider-parameter-docstrings.md b/.agents/evidence/verify/2026-10-25-provider-parameter-docstrings.md new file mode 100644 index 00000000..f7a5bf4f --- /dev/null +++ b/.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. diff --git a/.agents/notes/proposed/process/2026-10-25-provider-parameter-docstrings.md b/.agents/notes/proposed/process/2026-10-25-provider-parameter-docstrings.md new file mode 100644 index 00000000..20b42f1e --- /dev/null +++ b/.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). diff --git a/CHANGELOG.md b/CHANGELOG.md index ba8468ab..53e58928 100644 --- a/CHANGELOG.md +++ b/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 行为及清理。 diff --git a/client-sdk/pyproject.toml b/client-sdk/pyproject.toml index d947531d..d289a0cc 100644 --- a/client-sdk/pyproject.toml +++ b/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] diff --git a/client-sdk/src/agent_sandbox/_version.py b/client-sdk/src/agent_sandbox/_version.py index 4fbec93e..5ae007ca 100644 --- a/client-sdk/src/agent_sandbox/_version.py +++ b/client-sdk/src/agent_sandbox/_version.py @@ -1 +1 @@ -__version__ = "0.4.0a3" +__version__ = "0.4.0a4" diff --git a/client-sdk/src/agent_sandbox/api/sandbox.py b/client-sdk/src/agent_sandbox/api/sandbox.py index 10884d0a..b1673d08 100644 --- a/client-sdk/src/agent_sandbox/api/sandbox.py +++ b/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`` diff --git a/client-sdk/tests/test_api/test_provider_docstrings.py b/client-sdk/tests/test_api/test_provider_docstrings.py new file mode 100644 index 00000000..b6a965de --- /dev/null +++ b/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) diff --git a/docs/en/reference/configuration.md b/docs/en/reference/configuration.md index 880bb198..3086f749 100644 --- a/docs/en/reference/configuration.md +++ b/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 diff --git a/docs/zh/reference/configuration.md b/docs/zh/reference/configuration.md index 495a55ae..d8c28a93 100644 --- a/docs/zh/reference/configuration.md +++ b/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 diff --git a/server-sdk/src/agent_sandbox/server/_version.py b/server-sdk/src/agent_sandbox/server/_version.py index 4fbec93e..5ae007ca 100644 --- a/server-sdk/src/agent_sandbox/server/_version.py +++ b/server-sdk/src/agent_sandbox/server/_version.py @@ -1 +1 @@ -__version__ = "0.4.0a3" +__version__ = "0.4.0a4"