From b33d13c9f1bae264a1dfaba272aee815a88460e1 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Sun, 25 Oct 2026 09:33:37 +0000 Subject: [PATCH 1/3] docs: record verified Python 0.4.0a1 publication --- .agents/README.md | 4 + .../2026-10-25-python-040a1-public-release.md | 78 +++++++++++++++++++ CHANGELOG.md | 2 +- 3 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 .agents/evidence/verify/2026-10-25-python-040a1-public-release.md diff --git a/.agents/README.md b/.agents/README.md index 8b4acdbd..9c45ced9 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -1,5 +1,9 @@ # `.agents/` — engineering record of the python-sdk repository +## Published specification 5 alpha — 2026-10-25 + +Client/server **0.4.0a1** are public. [Release verification](evidence/verify/2026-10-25-python-040a1-public-release.md) records immutable tag identity, required CI, four public artifact hashes matched to the preserved candidate, and fresh exact-version installation. This host release does not update existing sandbox images or imply whole-catalog production certification. + ## Specification 5 migration — 2026-10-25 The [unified startup proposal](notes/proposed/architecture/2026-10-25-unified-template-launch.md) diff --git a/.agents/evidence/verify/2026-10-25-python-040a1-public-release.md b/.agents/evidence/verify/2026-10-25-python-040a1-public-release.md new file mode 100644 index 00000000..7c61b3f2 --- /dev/null +++ b/.agents/evidence/verify/2026-10-25-python-040a1-public-release.md @@ -0,0 +1,78 @@ +# Verification: public Python 0.4.0a1 pair + +- Date: 2026-10-25 +- Implementation: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/108 +- Source and immutable tag: `11e7e93486f852edd1fe23366c52936058d9d446`, `v0.4.0a1`. +- Result: PASS — both alpha distributions are public and independently installed. + +## Publication gates + +The final PR head `97888a7a8008053ecef2eb252324a0e8fa165dd6` passed all 11 checks. +The PR was merged with that expected head, and the actual merge SHA was confirmed. +[Main CI](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40179926574) +passed all 10 jobs before the new matching tag and +[GitHub prerelease](https://github.com/Alibaba-Agent-Sandbox/python-sdk/releases/tag/v0.4.0a1) +were created. Neither an existing tag nor a public version was replaced. + +[Publication run 40180399513](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40180399513) +passed on its first attempt: complete tag CI, paired build, artifact checks and +preservation, existing-public-file preflight, server upload, client upload, public +file verification and fresh installation. No upload or readback failure occurred +in this publication run. The configured repository credential remained in Actions; +its value was not copied into the workspace or written to evidence. + +## Independent public readback + +Both exact-version PyPI JSON responses contained one wheel and one sdist. Each was +downloaded independently, hashed, and compared against both the public SHA-256 and +the exact `python-release-candidate` artifact preserved by the successful workflow. +All four comparisons passed: + +| Public file | SHA-256 | +| --- | --- | +| `agent_sandbox_server-0.4.0a1-py3-none-any.whl` | `475422904a2f8f11a883ceefc02e5acd2bbfbe9c83ee2b9e7d0d04fec4982473` | +| `agent_sandbox_server-0.4.0a1.tar.gz` | `2ad964bf12c28ee60f2fab46f7ae73c2d582d2b2b5978f51767ed6a3d4d3b461` | +| `agent_sandbox_client-0.4.0a1-py3-none-any.whl` | `1db89a5ba669bb52d51844a07cc2180e13df790b215833f2db758114fb9a8eb2` | +| `agent_sandbox_client-0.4.0a1.tar.gz` | `335c10dcddb759c2f9e54294daabf0944171b39a28c1d12ae9dc0e6444533b71` | + +To reproduce: fetch `https://pypi.org/pypi//0.4.0a1/json` for +`agent-sandbox-server` and `agent-sandbox-client`; download each `urls` entry; compare +`hashlib.sha256(content).hexdigest()` with `digests.sha256`. Download the preserved +candidate from the linked publication run and compare the same filenames and hashes. + +## Fresh public installation + +From outside the source checkout, create a new virtual environment and run: + +```sh +python -m pip install --no-cache-dir --index-url https://pypi.org/simple 'agent-sandbox-client==0.4.0a1' +python -m pip check +python -c "from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))" +python -c 'from agent_sandbox.api import launch_template, TemplateSession, TemplateLaunchError; from agent_sandbox.server import start' +``` + +The independent check used Python 3.13.13. Installation and `pip check` exited 0; +both installed versions were 0.4.0a1, the client automatically required the exact +matching server, and module loading came from the new environment's `site-packages`. +The new template API and existing standard sync/async/Provider creation exports +imported successfully. The installed `launch_template` signature has no +`workflow_id`, and its packaged validator accepted a specification 5 native `base` +manifest. These are installed-distribution checks, not a new cloud acceptance claim. + +## Scope and retained limitations + +The previously recorded five real unified-template startup cases, original full +CLI pass, additional unexplained CLI failure, and focused successful file check +remain separate in the [runtime diagnostic evidence](2026-10-25-unified-template-cli-diagnostic.md). +https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109 remains open; this +release does not invent a cause or erase the failure. Local environment-intercepted +test failures also remain recorded in earlier evidence. + +The release is alpha. It does not certify all providers, every template operation, +or production readiness. Installing this host package does not update runtime +packages inside existing images. The public catalog/CLI cutover is coordinated in +their owner repositories; no catalog-dependent cloud experiment was run during +this documentation follow-up. + +Documentation-only verification: repository health 106 passes / 1 warning / 0 +failures, hygiene and whitespace checks passed. Historical evidence was preserved. diff --git a/CHANGELOG.md b/CHANGELOG.md index 3147e61e..8c6f6ba3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ## [0.4.0a1] - 2026-10-25 -Candidate: not yet published. +Published alpha pair: [v0.4.0a1](https://github.com/Alibaba-Agent-Sandbox/python-sdk/releases/tag/v0.4.0a1). Both distributions use the same version; see [publication verification](.agents/evidence/verify/2026-10-25-python-040a1-public-release.md). ### Changed From b82df381ab15ccc643c5a38f196ebb24879966de Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Sun, 25 Oct 2026 09:44:25 +0000 Subject: [PATCH 2/3] docs: verify released SDK against the public template catalog --- .../architecture/2026-10-25-unified-template-launch.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .agents/notes/{proposed => implemented}/architecture/2026-10-25-unified-template-launch.md (100%) diff --git a/.agents/notes/proposed/architecture/2026-10-25-unified-template-launch.md b/.agents/notes/implemented/architecture/2026-10-25-unified-template-launch.md similarity index 100% rename from .agents/notes/proposed/architecture/2026-10-25-unified-template-launch.md rename to .agents/notes/implemented/architecture/2026-10-25-unified-template-launch.md From 95addc3823456b8a425fdc5b648fcaf89c4b694e Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Sun, 25 Oct 2026 09:44:45 +0000 Subject: [PATCH 3/3] docs: finalize public catalog acceptance and implemented decision --- .agents/README.md | 4 +- .../2026-10-25-python-public-catalog-base.md | 92 +++++++++++++++++++ .../2026-10-25-unified-template-launch.md | 11 ++- 3 files changed, 103 insertions(+), 4 deletions(-) create mode 100644 .agents/evidence/verify/2026-10-25-python-public-catalog-base.md diff --git a/.agents/README.md b/.agents/README.md index 9c45ced9..feea600f 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -2,11 +2,11 @@ ## Published specification 5 alpha — 2026-10-25 -Client/server **0.4.0a1** are public. [Release verification](evidence/verify/2026-10-25-python-040a1-public-release.md) records immutable tag identity, required CI, four public artifact hashes matched to the preserved candidate, and fresh exact-version installation. This host release does not update existing sandbox images or imply whole-catalog production certification. +Client/server **0.4.0a1** are public. [Release verification](evidence/verify/2026-10-25-python-040a1-public-release.md) records immutable tag identity, required CI, four public artifact hashes matched to the preserved candidate, and fresh exact-version installation. The [public catalog integration](evidence/verify/2026-10-25-python-public-catalog-base.md) verifies the released SDK against the live specification 5 base manifest. This host release does not update existing sandbox images or imply whole-catalog production certification. ## Specification 5 migration — 2026-10-25 -The [unified startup proposal](notes/proposed/architecture/2026-10-25-unified-template-launch.md) +The [implemented unified startup design](notes/implemented/architecture/2026-10-25-unified-template-launch.md) removes workflow selection and preserves all template services. The [contract foundation](evidence/verify/2026-10-25-unified-template-contract.md) records local shared-vector checks only. [Runtime checkpoint](evidence/verify/2026-10-25-unified-template-runtime.md) records diff --git a/.agents/evidence/verify/2026-10-25-python-public-catalog-base.md b/.agents/evidence/verify/2026-10-25-python-public-catalog-base.md new file mode 100644 index 00000000..802df35b --- /dev/null +++ b/.agents/evidence/verify/2026-10-25-python-public-catalog-base.md @@ -0,0 +1,92 @@ +# Verification: released SDK and public catalog base manifest + +- Date: 2026-10-25 +- Result: PASS — one owned sandbox, expected output, independently confirmed absence. +- SDK: public PyPI client/server 0.4.0a1, freshly installed outside the source checkout. +- Catalog: , schema 3. +- TTL requested: 300 seconds. + +## Input and boundary + +The catalog response identified templates `45eb6c4`, CLI `408e618`, Python SDK +`11e7e93`, providers `48f0910`, Node SDK `f473f7d` and Registry `7986493`. Its fetched +bytes had SHA-256 `ffd21eb7058f35137fed1125dae4268a360e5d2ebc427fa78c2021baa9c297ac`. +The base entry's published manifest digest was +`sha256:8fcb10e223a4e592d3f4fa44069dcc966eeb91799cd768ce106470368f7acdd9`. + +The test selected the public catalog's `base` entry for `alicloud-express` and passed +its complete `manifest` mapping unchanged to `launch_template`. That manifest declares +specification 5, `template_id: base` and an empty `provides` map. No local substitute, +source checkout, manifest override or catalog cache was used. + +An earlier local invocation of `launch_template('base', ...)` returned +`FileNotFoundError` for `base` before creating any resource. This was an incorrect +test assumption: Python's documented string input is a local YAML path; bare-name +catalog resolution belongs to the CLI. The corrected experiment explicitly resolves +the public catalog manifest before calling Python. This observation is retained as +an input-contract boundary, not classified as a product defect or a successful cloud test. +No new registry resolver or patch release was introduced. + +## Result + +Elapsed times below start immediately before launch, after fetching the catalog: + +| Operation | Elapsed | Result | +| --- | --- | --- | +| `launch_template(manifest, provider='alicloud-express', timeout=300)` | 1.070 s | PASS; zero declared application services, as specified by base. | +| `session.sandbox.commands.run('printf 42', timeout=30)` | 1.463 s | PASS; exit 0, stdout exactly `42`. | +| `session.close()` in `finally` | 1.647 s | PASS. | +| Independent `ProviderSandbox.get_info_by_id` | 1.984 s | PASS; `SandboxNotFoundError` confirms owned resource absent. | + +The complete scenario took 2.049 seconds. The run journal ended with +`cleanup-intent`, `deleted`, `cleanup-complete`. Only one sandbox was created; +no full CLI acceptance suite or template matrix was rerun. No interpreter API, +application health/discovery or arbitrary service behavior is claimed by this +base shell-operation check. + +## Reproduce + +Use the exact public installation from the +[release record](2026-10-25-python-040a1-public-release.md) and configure the Express +account through `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN`. +Then run outside the source checkout: + +```python +import asyncio +import json +import urllib.request + +from agent_sandbox import ProviderSandbox +from agent_sandbox.api import launch_template +from agent_sandbox.models.errors import SandboxNotFoundError + +with urllib.request.urlopen("https://registry.agent-sandbox.cn/catalog.json") as response: + catalog = json.load(response) +assert catalog["schema"] == 3 +entry = next(row for row in catalog["templates"] + if row["name"] == "base" and row.get("native_provider") == "alicloud-express") +manifest = entry["manifest"] +assert manifest["spec_version"] == 5 + +async def main(): + session = await launch_template(manifest, provider="alicloud-express", timeout=300) + sandbox_id = session.sandbox.id + try: + result = await session.sandbox.commands.run("printf 42", timeout=30) + assert result.exit_code == 0 and result.stdout == "42" + finally: + await session.close() + try: + await ProviderSandbox.get_info_by_id(sandbox_id, provider="alicloud-express") + except SandboxNotFoundError: + pass + else: + raise AssertionError("Owned sandbox still exists") + +asyncio.run(main()) +``` + +The public catalog can advance; record its revision metadata and response digest +when reproducing. The earlier CLI diagnostic limitation remains independently +tracked in https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109. This +narrow success does not erase that historical result. diff --git a/.agents/notes/implemented/architecture/2026-10-25-unified-template-launch.md b/.agents/notes/implemented/architecture/2026-10-25-unified-template-launch.md index 0ab64d1a..2f69b016 100644 --- a/.agents/notes/implemented/architecture/2026-10-25-unified-template-launch.md +++ b/.agents/notes/implemented/architecture/2026-10-25-unified-template-launch.md @@ -1,6 +1,6 @@ # Decision: Launch a complete template without workflow selection -Status: proposed +Status: implemented ## Problem @@ -18,7 +18,9 @@ remain immutable historical inputs and do not certify specification 5 launches. `launch_template(manifest, provider=..., reference=...)` starts a previously prepared reference, checks SandboxServer protocol v2 services and returns all declared endpoints. Python does -not acquire source building. The static planner returns `supported`, required/missing +not acquire source building or bare-name catalog resolution: the input is a manifest +mapping or local YAML path. Catalog callers resolve a manifest before launching it. +The static planner returns `supported`, required/missing operations, all services and an optional unsupported-combination reason. ## Alternatives considered @@ -40,6 +42,11 @@ and real provider startup/cleanup. Five new startup scenarios passed; all 11 che for implementation head `66c86f2` passed. The separate CLI acceptance rerun has an unconfirmed file-transfer failure tracked in https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109. +The final PR, merged main and release-tag CI passed; client/server 0.4.0a1 were +published and independently installed. The public v3 catalog base manifest passed +launch, exec and independently confirmed cleanup through that installed release. +See [publication](../../../evidence/verify/2026-10-25-python-040a1-public-release.md) +and [public catalog integration](../../../evidence/verify/2026-10-25-python-public-catalog-base.md). ## Acceptance criteria