From 27389e78fe2b3621ef6003cc9b220f2b45d589c4 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:24:14 +0000 Subject: [PATCH] docs: clarify Express pause and snapshot allowlist support --- .agents/README.md | 2 + .../2026-10-19-express-conditional-support.md | 11 +++++ .../2026-10-19-express-conditional-support.md | 27 ++++++++++++ CHANGELOG.md | 4 ++ docs/en/guide/conditional-acceptance.md | 43 +++++++++++++++++-- docs/zh/guide/conditional-acceptance.md | 42 +++++++++++++++++- 6 files changed, 124 insertions(+), 5 deletions(-) create mode 100644 .agents/evidence/verify/2026-10-19-express-conditional-support.md create mode 100644 .agents/notes/implemented/process/2026-10-19-express-conditional-support.md diff --git a/.agents/README.md b/.agents/README.md index db23e2e..9c17b56 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -95,3 +95,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ - [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) - [Canonical guide links](notes/implemented/process/2026-10-19-canonical-guide-links.md) · [verification](evidence/verify/2026-10-19-canonical-guide-links.md) + +- [Express conditional support](notes/implemented/process/2026-10-19-express-conditional-support.md) · [verification](evidence/verify/2026-10-19-express-conditional-support.md) diff --git a/.agents/evidence/verify/2026-10-19-express-conditional-support.md b/.agents/evidence/verify/2026-10-19-express-conditional-support.md new file mode 100644 index 0000000..5a40ae0 --- /dev/null +++ b/.agents/evidence/verify/2026-10-19-express-conditional-support.md @@ -0,0 +1,11 @@ +# Verification: Express conditional support documentation — 2026-10-19 + +Result: PASS for source/API/document review; local health/hygiene and hosted current-head gates are recorded before merge. + +Reviewed python-sdk based4d93e8cbb986f33a8868f7a4139ed0edb49eaba, EN/ZH conditional-acceptance guides, Unreleased changelog and owner note/index. Official current compatible API, pause/resume and Snapshot invited-test pages explicitly document allowlist support and generation2 snapshots. No runtime or vendored standard code changes. + +The preserved real receipt [conditional acceptance](2026-10-19-conditional-acceptance.md) records actual generation2 execution. SDK companion PR47 and CLI companion PR40 were previously merged; SDK5 and CLI2 real cases passed with zero owned residuals. That is historical evidence, not a fresh run in this documentation task. Source check confirms current public Python sync/async pause/create/list/delete snapshot methods and CLI pause/resume/snapshot dispatch remain present. + +No cloud/model calls were added to Actions or initiated merely for prose; no resources were created. Source/API checks, example syntax, relative links, health/hygiene and current-head CI are completed before merge. Existing unrelated local contributor-policy files and an obsolete unpushed alternative branch are outside this scoped change. + +Final local document checks: Python example AST parse, relative-link resolution, actual installed CLI help (pause/resume/snapshot create/list/delete) and git diff --check PASS. SDK health106 PASS/1 WARN/0 FAIL; make hygiene PASS. Fresh paired source runtime installation and actual public sync/async method signatures verified. diff --git a/.agents/notes/implemented/process/2026-10-19-express-conditional-support.md b/.agents/notes/implemented/process/2026-10-19-express-conditional-support.md new file mode 100644 index 0000000..17fbe7e --- /dev/null +++ b/.agents/notes/implemented/process/2026-10-19-express-conditional-support.md @@ -0,0 +1,27 @@ +# Decision: Describe implemented Express conditional capabilities accurately + +Status: implemented + +## Problem +The local discussion conflated backend allowlist admission with missing product support. The current accepted standard Python sync/async public methods and the separate native Provider facade already exist, but the conditional guide is focused on fixture provisioning and leaves this distinction implicit. + +## Decision +Clarify the existing supported standard entry, explicit pause/snapshot allowlist conditions, generation2 snapshot requirement, connect-based resume, request timeout and cleanup. Add concrete EN/ZH SDK and CLI examples and link the current official Agent Sandbox pages. Keep native Provider extension gates distinct and preserve historical acceptance as historical evidence. + +## API Design +No runtime API changes. This documents interfaces already accepted on main; no features are newly enabled or falsely declared for native providers. Python uses create_snapshot, not a camelCase alias. Current guide scope is standard Python sync/async public methods and the separate native Provider facade. + +## Alternatives considered +Changing a feature flag without implementing a provider's matching wire contract would misrepresent support. Repeating already verified cloud tests for prose would create unrelated resources. Treating an account/template admission failure as globally unsupported contradicts the official service contract. + +## Dependencies +Accepted python-sdk sourced4d93e8cbb986f33a8868f7a4139ed0edb49eaba; companion owner https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/conditional-acceptance.md . Official service references are linked directly from the guides. No provider/template catalog schema change is needed. + +## Test Strategy +Check actual standard public method/command availability, parse Python examples, validate relative links and run repository health/hygiene. Preserve the existing real generation2 receipt instead of claiming a new cloud run. Require current-head hosted CI before merge. + +## Acceptance criteria +The EN/ZH guide distinguishes implemented standard support from admission and native extension contracts; examples map to actual symbols and commands. Historical failures/receipts remain unchanged and only scoped documentation/records are committed. + +## Evidence +See [verification](../../../evidence/verify/2026-10-19-express-conditional-support.md). diff --git a/CHANGELOG.md b/CHANGELOG.md index ef8db8e..bf56d98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ### Documentation +- Clarify implemented Express pause/resume and Snapshot standard interfaces, allowlist/runtime requirements and safe cleanup. / 明确极速版标准入口已实现暂停恢复与快照，以及白名单、运行时和清理要求。 + +### Documentation + - Use the verified canonical website and registry links in active English/Chinese guides. ### Fixed diff --git a/docs/en/guide/conditional-acceptance.md b/docs/en/guide/conditional-acceptance.md index f7cc8af..3b8069a 100644 --- a/docs/en/guide/conditional-acceptance.md +++ b/docs/en/guide/conditional-acceptance.md @@ -6,11 +6,48 @@ E2B_API_KEY/API_URL/DOMAIN. Never send an Express key to another provider. Official template operations separately need ALICLOUD_ACCESS_KEY_ID and ALICLOUD_ACCESS_KEY_SECRET; a runtime key cannot replace that authorization. +## Implemented interfaces and backend admission + +Express supports pause/resume and Snapshot after the corresponding account/region allowlist is enabled. Snapshot additionally requires a generation2 MicroVM runtime. Failure on a default template or a particular account does not establish that the service lacks these features. + +| Operation | Standard synchronous Python entry | Standard CLI entry | +| --- | --- | --- | +| Pause | `sandbox.pause()` | `abx sandbox pause "$SANDBOX_ID"` | +| Resume the same sandbox | `Sandbox.connect(sandbox_id)` | `abx sandbox resume "$SANDBOX_ID"` | +| Create a snapshot | `sandbox.create_snapshot(name="checkpoint", request_timeout=300)` | `abx sandbox snapshot create "$SANDBOX_ID" --name checkpoint` | +| List snapshots | `Sandbox.list_snapshots(sandbox_id=sandbox_id)`, consume the paginator | `abx sandbox snapshot list "$SANDBOX_ID" --format json` | +| Create from a snapshot | `Sandbox.create(template=snapshot.snapshot_id)` | `abx create "$SNAPSHOT_ID" --detach` | +| Delete a snapshot | `Sandbox.delete_snapshot(snapshot.snapshot_id)` | `abx sandbox snapshot delete "$SNAPSHOT_ID"` | + +Python examples use `from agent_sandbox import Sandbox`; asynchronous callers use `AsyncSandbox` and await the appropriate operations. These standard clients are distinct from the native Provider/Server extension at `agent_sandbox.api.sandbox.Sandbox`. A native provider feature gate is not a statement that the Express standard API is unavailable. Python spells the method `create_snapshot`; TypeScript uses `createSnapshot`, with argument shapes determined by the installed SDK version. + +```python +import os +from agent_sandbox import Sandbox + +sandbox = Sandbox.create(template=os.environ["E2E_PAUSE_TEMPLATE"], timeout=600) +try: + sandbox.files.write("/tmp/checkpoint.txt", "before-pause") + sandbox.pause() # requires allowlist admission + sandbox = Sandbox.connect(sandbox.sandbox_id) + assert sandbox.files.read("/tmp/checkpoint.txt") == "before-pause" +finally: + sandbox.kill() +``` + +Use `request_timeout=300` for snapshot creation; sandbox lifetime `timeout` is a different setting. Snapshot creation requires a running source. Same-name/same-tag conflicts fail without overwriting an existing snapshot. Filesystem-only pause via `keep_memory=False` is currently unavailable. Automatic pause/resume uses `lifecycle={"on_timeout": "pause", "auto_resume": True}` and remains subject to allowlisting. + +Snapshots outlive their source sandbox and must be deleted separately after killing any restored sandboxes that occupy them. Keep the returned Snapshot ID; delete by that ID or a returned qualified name rather than a short name. After an ambiguous create timeout, reconcile existing results by the owned source sandbox before retrying. + +This repository already records real generation2 acceptance in its [historical verification](../../../.agents/evidence/verify/2026-10-19-conditional-acceptance.md). It is historical execution evidence, not a new run performed for this documentation change. + +Official references: [compatible APIs](https://help.aliyun.com/zh/agent-sandbox/e2b-sdk-compatible-api-list), [pause/resume](https://help.aliyun.com/zh/agent-sandbox/pause-and-resume), and [Snapshot invited test](https://help.aliyun.com/zh/agent-sandbox/snapshot-invited-test). + ## Design and prerequisites Pause/resume and snapshot tests use separate selectors. Prefer an isolated -MicroVM generation2 fixture. Generation1 pause may need enablement; snapshots -require MicroVM and account/region access. Provisioning or admission errors remain +MicroVM generation2 fixture. Pause/resume requires allowlisting; snapshots additionally +require a generation2 MicroVM runtime. Provisioning or admission errors remain failures, not evidence that a local API key is absent. The public-image fixture needs no local Docker build or private registry credentials. @@ -64,7 +101,7 @@ Do not upload credentials or dispatch cloud/model acceptance in Actions. [Official template setup](https://help.aliyun.com/zh/agent-sandbox/build-and-manage-custom-templates-with-code), [compatibility](https://www.alibabacloud.com/help/en/agent-sandbox/e2b-compatibility-explanation), -[snapshot limits](https://help.aliyun.com/zh/functioncompute/snapshots). +[snapshot limits](https://help.aliyun.com/zh/agent-sandbox/snapshot-invited-test). ## SDK test / SDK 测试 diff --git a/docs/zh/guide/conditional-acceptance.md b/docs/zh/guide/conditional-acceptance.md index f4632a4..3b67028 100644 --- a/docs/zh/guide/conditional-acceptance.md +++ b/docs/zh/guide/conditional-acceptance.md @@ -6,10 +6,48 @@ E2B_API_URL、E2B_DOMAIN。不要把极速版密钥发给其他提供商。 官方模板操作另需 ALICLOUD_ACCESS_KEY_ID、ALICLOUD_ACCESS_KEY_SECRET， 运行时 API Key 不能代替控制面授权。 +## 已实现的接口与服务准入 + +极速版已提供暂停/恢复和 Snapshot；需要先开通对应账号/地域的白名单。Snapshot 还要求二代 MicroVM 运行时。不能因为默认模板或某次账号调用失败，就把整个服务标记为“不支持”。 + +| 操作 | Python 标准入口（同步） | CLI 标准入口 | +| --- | --- | --- | +| 暂停 | `sandbox.pause()` | `abx sandbox pause "$SANDBOX_ID"` | +| 恢复同一个沙箱 | `Sandbox.connect(sandbox_id)` | `abx sandbox resume "$SANDBOX_ID"` | +| 创建快照 | `sandbox.create_snapshot(name="checkpoint", request_timeout=300)` | `abx sandbox snapshot create "$SANDBOX_ID" --name checkpoint` | +| 快照列表 | `Sandbox.list_snapshots(sandbox_id=sandbox_id)`，通过分页器读取 | `abx sandbox snapshot list "$SANDBOX_ID" --format json` | +| 从快照新建沙箱 | `Sandbox.create(template=snapshot.snapshot_id)` | `abx create "$SNAPSHOT_ID" --detach` | +| 删除快照 | `Sandbox.delete_snapshot(snapshot.snapshot_id)` | `abx sandbox snapshot delete "$SNAPSHOT_ID"` | + +上表 Python 使用 `from agent_sandbox import Sandbox`；异步使用 `AsyncSandbox` 并 await 相应操作。它们是标准 SDK 入口，不能与 `agent_sandbox.api.sandbox.Sandbox` 的原生 Provider/Server 扩展入口混为一谈，也不能把原生提供方的特性门禁当成极速版标准 API 的服务能力结论。Python 命名为 `create_snapshot`，TypeScript 命名为 `createSnapshot`；参数形式以实际 SDK 版本为准。 + +```python +import os +from agent_sandbox import Sandbox + +sandbox = Sandbox.create(template=os.environ["E2E_PAUSE_TEMPLATE"], timeout=600) +try: + sandbox.files.write("/tmp/checkpoint.txt", "before-pause") + sandbox.pause() # 需白名单 + sandbox = Sandbox.connect(sandbox.sandbox_id) + assert sandbox.files.read("/tmp/checkpoint.txt") == "before-pause" +finally: + sandbox.kill() +``` + +快照创建请求建议 `request_timeout=300`，它与沙箱生命周期 `timeout` 不同。只能对运行中的沙箱创建；同名同 tag 冲突时服务会失败，不会覆盖已有快照。只有文件系统的 `keep_memory=False` 暂停方式暂不支持。自动暂停/恢复使用 `lifecycle={"on_timeout": "pause", "auto_resume": True}`，同样受白名单限制。 + +快照独立于源沙箱存续，源沙箱 kill 后仍须单独删除快照；先清理从快照创建的沙箱以释放占用。保存创建返回的 Snapshot ID，删除时使用该 ID 或完整名称，避免误用短名。创建超时后按源沙箱查询并核对已有结果，不盲目重试。 + +本仓库已有真实二代模板验收记录： +[历史验证](../../../.agents/evidence/verify/2026-10-19-conditional-acceptance.md)。它是已有运行结果，不是本次文档修改重新执行的结果。 + +官方说明：[兼容 API](https://help.aliyun.com/zh/agent-sandbox/e2b-sdk-compatible-api-list)、[暂停与恢复](https://help.aliyun.com/zh/agent-sandbox/pause-and-resume)、[Snapshot 邀测](https://help.aliyun.com/zh/agent-sandbox/snapshot-invited-test)。 + ## 设计与前置条件 暂停/恢复和快照分别选择测试模板。优先创建隔离的二代 MicroVM 模板； -一代暂停可能需要启用，快照需要 MicroVM 以及账号和地域的相应权限。 +暂停/恢复需白名单；快照需二代 MicroVM 及相应白名单。 构建或准入错误应如实记录，不能归因为缺少本地 API Key。 官方公共镜像无需本地 Docker 构建，也不需要私人仓库凭据。 @@ -56,7 +94,7 @@ SDK 测试校验仅保存在 Python 进程内存中的随机标记、文件、 [官方模板配置](https://help.aliyun.com/zh/agent-sandbox/build-and-manage-custom-templates-with-code)、 [兼容边界](https://www.alibabacloud.com/help/en/agent-sandbox/e2b-compatibility-explanation)、 -[快照限制](https://help.aliyun.com/zh/functioncompute/snapshots)。 +[快照限制](https://help.aliyun.com/zh/agent-sandbox/snapshot-invited-test)。 ## SDK test / SDK 测试