feat!: start complete templates without workflow selection

.agents/README.md

@@ -1,6 +1,19 @@
 # `.agents/` — engineering record of the python-sdk repository
 
-## Current delivery — 2026-10-24
+## Specification 5 migration — 2026-10-25
+
+The [unified startup proposal](notes/proposed/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
+real native-template acceptance and retained environment failures. The
+[cloud follow-up](evidence/verify/2026-10-25-unified-template-cloud.md) verifies all five
+startup scenarios including two HTTP services. The [CLI diagnostic follow-up](evidence/verify/2026-10-25-unified-template-cli-diagnostic.md) keeps the separate passing and failing CLI runs, final implementation CI and focused file-transfer results explicit;
+the previous 92-case matrix below remains specification 4 history, not v5 evidence.
+The [publication preflight](evidence/verify/2026-10-25-python-a1-publication-preflight.md)
+records candidate checks and stable installation requirements without claiming publication.
+
+## Previous delivery — 2026-10-24
 
 - Published client/server pair: **0.3.1a5**, with [immutable public artifacts, fresh installation and retained propagation failure](evidence/verify/2026-10-24-python-a5-public-release.md). This is an alpha release; host installation does not update in-image runtimes.
 - Standard `Sandbox`/`AsyncSandbox` and `code_interpreter` clients retain their migration contract. Asynchronous `ProviderSandbox` owns provider/server extensions; [SDK usage](../docs/en/guide/sdk-usage.md) now keeps process execution, interpreter calls, application HTTP and resource cleanup separate.

.agents/evidence/verify/2026-10-25-python-a1-publication-preflight.md

@@ -0,0 +1,38 @@
+# Verification: 0.4.0a1 publication preflight
+
+- Date: 2026-10-25
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/108
+- Result: PASS for the read-only preflight; no merge, tag creation or publication.
+
+At the time of this check, PR 108 was draft/open and mergeable without conflicts.
+Its head `14fad5c4a37ec01e41f859ea318f27353faf6421` passed all 11 remote CI jobs.
+Both public PyPI version endpoints for client/server 0.4.0a1 returned HTTP 404,
+as did the remote `v0.4.0a1` tag and GitHub release endpoints. This records absence
+at inspection time, not a claim about subsequent availability.
+
+`python scripts/check_release.py candidate --tag v0.4.0a1` passed. Both package
+versions and the required client dependency on the server are 0.4.0a1. The repository
+has the `PYPI_API_TOKEN` Actions secret name configured; its value was not read or
+printed, and this check does not establish its upload validity. The `pypi`
+environment reported no protection rules. No publication credential was copied.
+
+The publication procedure remains the existing one in CONTRIBUTING: after merge
+and required checks, bind an immutable matching tag; run tag CI; build and preserve
+four artifacts; verify their metadata, installation and any existing public hashes;
+upload server before client; verify public hashes and a fresh exact-version client
+installation with the matching server dependency. A GitHub prerelease triggers the
+existing release workflow; manual tag runs default to dry-run.
+
+The current English and Chinese installation guides now state the matching package
+requirements without the time-sensitive claim that the version is unpublished.
+Both specify CLI 0.5.0 for specification 5 template launch; the Chinese page's stale
+0.4.16 reference was corrected. Source-checkout installation remains available.
+Package README installation commands do not pin an obsolete release. Historical
+verification records were not rewritten.
+
+Documentation checks: repository health 106 passes / 1 warning / 0 failures;
+local-path/credential hygiene and whitespace checks passed. The new documentation
+head still requires its own remote checks. No unrelated cloud tests were repeated.
+The unexplained extra full CLI run remains tracked separately in
+https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109; the focused file
+check and unified-template startup passes do not erase that history.

.agents/evidence/verify/2026-10-25-unified-template-cli-diagnostic.md

@@ -0,0 +1,79 @@
+# Verification: CLI acceptance discrepancy and focused file diagnostic
+
+- Date: 2026-10-25
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/108
+- Diagnostic follow-up: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109
+- Candidate: paired Python packages 0.4.0a1 and built CLI 0.5.0.
+- Implementation head: `66c86f2b6dc7cd33e02c2a53d98dda2125d05236`.
+- Publication/merge: neither was performed by this verification.
+
+This follows the [earlier cloud checkpoint](2026-10-25-unified-template-cloud.md).
+The five unified-template startup cases passed, including two services started
+from one template. They are independent of the CLI file-transfer discrepancy below.
+
+## Final implementation CI
+
+All 11 remote checks passed for implementation head `66c86f2`: client and server
+on Python 3.10/3.11/3.12, Python-to-Node Provider engine, package build, hygiene,
+pinned standard contract and Markdown links. An evidence-only follow-up commit
+must still receive its own applicable checks.
+
+## Keep the two full CLI runs separate
+
+| Run | Result | Duration | Detail |
+| --- | --- | --- | --- |
+| Configured CLI follow-up | PASS | 376.63 s | Lifecycle, list, exec/stream, upload/download and repeated deletion passed. |
+| Additional explicit Express environment mapping | FAIL | 355.17 s | Lifecycle/list/exec/stream passed; upload exit 2, download exit 4 and absent downloaded content; both deletion calls exited 0. |
+
+The second run mapped the E2B API key, API URL and domain environment names to
+existing ABX_SANDBOX Express settings. Credential values are not recorded. Its
+second deletion reported the owned sandbox absent.
+
+Read-only review of `e2e/provider_live.py::cli_express` confirms that creation sets
+`--timeout 300` and each subprocess allows up to 240 seconds. The fixture discards
+file-command stderr and does not record individual operation durations or HTTP
+status. Both whole-run durations exceed 300 seconds, but the passing run was longer.
+This cannot establish that the failed transfer hit the sandbox deadline. Exit 2
+and exit 4 cover multiple error categories and cannot identify a cause alone.
+
+The failure's root cause remains **unconfirmed**. It is not attributed to template
+startup, Provider support, file API logic or network interception. Issue 109 owns
+the missing diagnostic evidence; no unrelated runtime or fixture change was added
+to the template refactor.
+
+## Focused real-provider file check
+
+A separate diagnostic used the same explicit Express environment mapping and
+built CLI, a fresh engine socket and a newly owned sandbox. It retained monotonic
+operation timings and sanitized stderr in memory. It ran only this command sequence:
+
+```sh
+abx --provider alicloud-express sandbox create base --detach --timeout 300
+abx --provider alicloud-express sandbox upload "$SANDBOX_ID" "$SOURCE_FILE" /tmp/unified-template-file-diagnostic.txt
+abx --provider alicloud-express sandbox download "$SANDBOX_ID" /tmp/unified-template-file-diagnostic.txt "$DEST_FILE"
+abx --provider alicloud-express sandbox kill "$SANDBOX_ID"
+abx --provider alicloud-express sandbox kill "$SANDBOX_ID"
+```
+
+The runner saved the detached ID from creation, used a temporary local directory,
+wrote `unified-template-file-diagnostic` followed by a newline, compared downloaded
+bytes exactly, and always ran deletion in `finally`. No credentials or raw private
+responses are included in this record. No retries or product changes were used.
+
+| Operation | Elapsed | Since start | Exit | Observation |
+| --- | --- | --- | --- | --- |
+| Create | 42.601 s | 42.601 s | 0 | One detached sandbox ID; stderr empty. |
+| Upload | 29.551 s | 72.153 s | 0 | stderr empty. |
+| Download | 30.885 s | 103.038 s | 0 | stderr empty; downloaded bytes equal source bytes. |
+| Delete | 38.036 s | 141.074 s | 0 | stderr empty. |
+| Delete again | 39.871 s | 180.945 s | 0 | Reports the owned sandbox was not found. |
+
+**Focused result: PASS**, total 180.946 seconds. File operations completed before
+300 seconds even when measuring from before creation; both cleanup commands passed
+and the owned sandbox was confirmed absent. The CLI exposed no failing HTTP status
+in this successful run, so none is invented here.
+
+This establishes that the candidate's real file upload/download and cleanup worked
+in this experiment. It does not explain or erase the failed full-gate run, prove
+repeatability under all conditions, or close Issue 109. No further cloud reruns or
+unsupported claims about deadline behavior were made.

.agents/evidence/verify/2026-10-25-unified-template-cloud.md

@@ -0,0 +1,62 @@
+# Verification: complete-template candidate and real startup
+
+- Date: 2026-10-25
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/108
+- Result: PARTIAL — startup and configured CLI acceptance passed; final-head remote CI is pending.
+- Packages: client/server 0.4.0a1, paired editable checkout and clean built-wheel install.
+- Environment: Linux Python 3.13.13, real Express account; credentials supplied through
+  process environment only. Nothing was published to PyPI during this verification.
+
+## Startup regression and correction
+
+The first real multi-service test was refused before resource creation because the
+Python Express Provider's startup metadata omitted `exec`, despite having an existing
+process startup implementation. Adding `exec` to that Provider's startup declarations
+is verified by the actual startup stream below. No capability checks were bypassed.
+
+`python -m pytest e2e/test_managed_template.py -q -ra`: **5 passed in 22.37 seconds**.
+The four native scenarios create `base`/`code-interpreter-v1` using provider name/object,
+execute shell commands and confirm deletion. The fifth starts two independent Python
+HTTP listeners from one `start_cmd`, executes the template's readiness command, resolves
+both Provider endpoints, requests the two declared `/health` routes from the host and
+confirms deletion. The journal contains exactly one `started` event. It does not test
+an interpreter API or claim arbitrary HTTP protocols have standard health routes.
+
+The final focused launcher suite passed 21 cases, including unknown protocol/version
+endpoints without invented health probes. Only SandboxServer protocol v2 receives
+built-in health/discovery; an author-supplied ready command checks overall readiness.
+
+## Broader validation
+
+- `make lint`, `make typecheck`: PASS for both packages.
+- `make format-check build dist-check`: PASS, including four distributions, twine,
+  clean combined installation, imports and both `py.typed` markers.
+- `make test`: 878 server passes and two environment-intercepted failures, so make
+  stopped before the client target. Separate full client run: **2260 passed,
+  20 skipped, 2 failed** (Cube engine HTTP 502). These failures remain recorded.
+- A localhost-only `NO_PROXY` rerun retained the invalid WebSocket upgrade HTTP 501;
+  chunked HTTP rejection passed alone. No test or server behavior was weakened.
+- Remote CI for `ff073167f8993a5c580c78cccccd5779db1f5836`: all 11 checks passed,
+  including client/server Python 3.10/3.11/3.12, engine integration, build and docs.
+  The later startup metadata/test commit requires its own remote checks.
+- Full `make e2e`: **124 passed, 9 skipped, 2 deselected, 1 failed**. The sole failure
+  is the CLI scenario lacking `ABX_BIN`; it ran no CLI sandbox operations. Skips are
+  missing installed optional providers, opt-in volume tests, CLI named-array setup,
+  and account-dependent pause/snapshot prerequisites. A separately configured CLI
+  follow-up using the built 0.5.0 CLI passed: **1 passed in 376.63 seconds**.
+  It exercised create/info/list, exec/stream, upload/download and repeated deletion.
+  The original missing-prerequisite failure is retained above.
+
+## Cleanup
+
+The five new startup scenarios verified owned resources absent after context exit.
+The E2E finalizer reported zero leaked tracked sandboxes. The required
+`python scripts/e2e-cleanup.py --all-tagged` dry run found zero tagged candidates;
+it deleted nothing. The configured CLI follow-up completed its sandbox deletion and repeated-deletion
+checks. A second explicitly scoped configuration run is still in progress.
+
+## Limits
+
+There is no new whole-catalog cloud matrix, source-image build test in Python,
+PyPI release, or claim that specification 4 receipts verify specification 5. The
+standard SDK contract remains independent. Application server behavior is unchanged.

.agents/evidence/verify/2026-10-25-unified-template-contract.md

@@ -0,0 +1,27 @@
+# Verification: unified template launch contract foundation
+
+- Date: 2026-10-25
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/107
+- Result: PARTIAL
+- Scope: `contracts/launch-v1.json`, `contracts/launch-vectors.json` and the working
+  Python planner used to evaluate them; runtime changes remain in progress.
+- Environment: isolated Linux Python development environment with both SDK packages.
+
+## Commands run
+
+`python -m pytest client-sdk/tests/test_workflows/test_launch_contract.py -q`
+
+## Results
+
+17 passed. Cases cover source preparation, prepared Python consumption, all services,
+native references, images, missing operations, unsupported provider combinations and
+strict rejection of old declarations. These are local static contract tests.
+
+## Cleanup
+
+No cloud resource was created by the contract tests.
+
+## Not verified
+
+The full runtime, real-cloud E2E and coordinated consumer migrations are pending.
+This foundation commit does not claim that specification 5 has been released.

.agents/evidence/verify/2026-10-25-unified-template-runtime.md

@@ -0,0 +1,56 @@
+# Verification: complete template startup candidate
+
+- Date: 2026-10-25
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/107
+- Result: PARTIAL
+- Package under test: matching editable client/server candidate 0.4.0a1; no PyPI
+  publication is claimed.
+- Environment: Linux, Python 3.13.13; Express credentials supplied only through
+  environment variables. The CI Python-version matrix remains a remote gate.
+
+## What was verified
+
+Specification 5 rejects workflow selection, starts one complete template, preserves
+all declared services and resources, and cleans every resolved client on failure.
+Provider operations remain independent from application service declarations.
+
+## Commands and results
+
+- `python -m pytest client-sdk/tests/test_workflows/test_launch_contract.py -q`:
+  17 passed, shared vectors.
+- Focused launcher/model/policy/capability/contract tests: 126 passed.
+- Launcher and offline catalog regressions: 57 passed, including multiple services,
+  later-service cleanup failure, preparation boundary and generic protocol exposure.
+- `make lint`: PASS, both packages.
+- `make typecheck`: PASS, 56 server and 99 client modules.
+- `bash scripts/check-repo-health.sh`: PASS=106, WARN=1, FAIL=0.
+- `python -m pytest e2e/test_managed_template.py -q -ra`: 4 passed in 18.46 seconds.
+  Real Express `base` and `code-interpreter-v1`, selected by provider name and built-in
+  instance, executed shell commands and confirmed deletion of the owned sandbox.
+  This does not test the interpreter API. This initial run preceded the candidate
+  version bump and exercised the same new launcher implementation.
+- `make test`: server suite 878 passed, 2 failed; it therefore did not start the
+  client suite. The separate full client run and full `make e2e` are in progress.
+- `make format-check build dist-check`: candidate artifacts built and twine checks
+  passed; combined-install verification is still running at this checkpoint.
+
+## Environment failures retained
+
+The same two server tests failed before the launcher changes and on repeat:
+`test_upgrade_without_a_key_is_a_400_not_a_hang` received HTTP 501 instead of 400;
+`test_transfer_encoding_rejected_in_policy_mode` received 502 instead of 400.
+A direct malformed upgrade request to the real loopback server returned plain text
+`项目网络审计已关闭`, demonstrating interception outside the server's JSON handler.
+The chunked test passed alone; the upgrade test still failed alone. Neither test nor
+server implementation was weakened. Remote CI must pass these checks before merge.
+
+## Cleanup
+
+Each of the four native scenarios confirmed the sandbox was absent after context
+exit. No template/image was built by Python. The full E2E cleanup report is pending.
+
+## Not verified
+
+Full remote CI, candidate publication, source-template Python application consumption
+and any specification 5 catalog-wide cloud matrix remain pending. Historical receipts
+were not rewritten or promoted to new-template verification.

.agents/notes/proposed/architecture/2026-10-25-unified-template-launch.md

@@ -0,0 +1,49 @@
+# Decision: Launch a complete template without workflow selection
+
+Status: proposed
+
+## Problem
+
+A template exposes several services, but selecting a workflow reduced launch to one
+operation and made callers choose source/image/native execution types.
+
+## Decision
+
+Specification 5 removes workflow declarations and retains the complete `provides`
+map plus the existing startup/readiness commands. `contracts/launch-v1.json` and
+`launch-vectors.json` define the shared static launch plan. Old receipt contracts
+remain immutable historical inputs and do not certify specification 5 launches.
+
+## API Design
+
+`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
+operations, all services and an optional unsupported-combination reason.
+
+## Alternatives considered
+
+- Hide the workflow flag while retaining selectable manifests: preserves the source
+  of conflicting behavior and incomplete service exposure.
+- Infer an old default workflow: hides migration and continues selecting a subset.
+
+## Dependencies
+
+- https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/107
+- CLI consumer: https://github.com/Alibaba-Agent-Sandbox/agent-sandbox
+- Template owner: https://github.com/Alibaba-Agent-Sandbox/awesome-templates
+
+## Test Strategy
+
+Shared cross-language vectors, SDK model and launcher regressions, full package CI,
+and real provider startup/cleanup. Five new startup scenarios passed; all 11 checks
+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.
+
+## Acceptance criteria
+
+- No workflow argument or current manifest workflow selection remains.
+- All declared services survive launch; no unrelated interpreter requirement blocks it.
+- Required tests, real-component validation, bilingual docs and changelog are recorded.
+- CLI and template consumers migrate together; current v5 receipts are not fabricated.