refactor: separate client installation from local server runtime

.agents/README.md

@@ -1,5 +1,12 @@
 # `.agents/` — engineering record of the python-sdk repository
 
+## Recent changes — 2026-11-10
+
+- [Owner change index](notes/proposed/process/2026-11-10-recent-change-index.md) · [records verification](evidence/verify/2026-11-10-recent-change-index.md).
+- This is a dated source/delivery index; Draft implementation, prior releases and new validation remain separate.
+
+- [Client/runtime boundaries](notes/proposed/architecture/2026-11-10-client-runtime-boundaries.md) · [verification](evidence/verify/2026-11-10-client-runtime-boundaries.md).
+
 - [Managed Agents API](notes/proposed/architecture/2026-11-05-managed-agents-api.md) · [initial verification](evidence/verify/2026-11-05-managed-agents-api.md) · [release-candidate verification](evidence/verify/2026-11-06-managed-agents-release-candidate.md) · [CI artifacts](evidence/verify/2026-11-06-managed-agents-ci-artifacts.md).
 - Managed Agents API cloud continuations: [private invocation/drain](evidence/verify/2026-11-06-managed-agents-fc-private-drain.md), [source business operations](evidence/verify/2026-11-06-managed-agents-fc-business-source.md), [private input boundary](evidence/verify/2026-11-06-managed-agents-empty-private-revision.md).
 
@@ -266,3 +273,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 - [Preview release notice and community](notes/proposed/process/2026-11-10-preview-release-community.md) · [verification](evidence/verify/2026-11-10-preview-release-community.md).
 
 - [Community QR replacement](notes/proposed/process/2026-11-10-refresh-community-qr.md) · [verification](evidence/verify/2026-11-10-refresh-community-qr.md).
+
+- [SDK simplification mainline reconciliation](evidence/verify/2026-11-10-simplification-main-merge.md).

.agents/evidence/verify/2026-11-10-client-runtime-boundaries.md

@@ -0,0 +1,106 @@
+# Verification: Client installation and local runtime boundaries
+
+- Date: 2026-11-10
+- Change: [Issue 157](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/157)
+- Result: PARTIAL — changed-surface checks pass; existing raw HTTP/SSE failures prevent a green local full-suite result. Cloud E2E remains separate.
+- Package under test: local client/server 0.4.0a7 sources and built wheels; no version bump or publication.
+- Environment: Linux, Python 3.11.15. No cloud credentials used by the local checks.
+
+## What was verified
+
+Client-only installation imports the standard synchronous/asynchronous clients,
+interpreter clients, ProviderSandbox, ServerClient and remote decorator without
+a server distribution. It performs a real localhost HTTP health request.
+Registration without a local runtime fails with installation guidance and no
+partial local registration. Installing the server extra resolves the exact local
+runtime wheel, preserves the shared namespace and registers a real function.
+Dynamic functions also register without unnecessary source inspection. Instance
+execution and actual remote-decorator behavior retain their existing regressions.
+
+## Commands run
+
+Run from the repository root using an isolated virtual environment (pip was seeded for the server package-list test):
+
+```bash
+uv pip install -e ./server-sdk -e './client-sdk[dev]' hatchling build twine
+python -m pytest client-sdk/tests/test_declarative client-sdk/tests/test_packaging.py client-sdk/tests/test_version_lockstep.py -q
+make lint typecheck format-check
+make build dist-check
+make test
+# make stopped after server failures; run the client suite separately:
+(cd client-sdk && python -m pytest tests/ -v --tb=short)
+python -m pytest client-sdk/tests/test_release_validation.py client-sdk/tests/test_declarative/test_register.py -q
+make hygiene
+bash scripts/check-repo-health.sh
+ruff check scripts/check_dists.py
+ruff format --check scripts/check_dists.py
+```
+
+## Results
+
+| Scenario / test | Result | Notes |
+|---|---|---|
+| Focused declarative, actual wheel metadata and lockstep tests | PASS | 112 passed; includes dynamically defined function registration |
+| Both package lint/type/format checks | PASS | 58 server and 114 client source files typechecked; 94 server and 260 client files formatted |
+| Both wheels and sdists; twine; py.typed | PASS | Built from the candidate source; all four artifacts accepted |
+| Client-only fresh wheel installation | PASS | Runtime distribution and namespace absent; client imports, decorator construction, explicit registration error and real HTTP pass |
+| Local server extra in the same fresh environment | PASS | Offline resolution from the local server wheel; registration and pip check pass |
+| Full server suite (`make test`, first phase) | FAIL | 877 passed, 3 failed; the client phase did not start because make stopped |
+| Server failures rechecked after seeding pip | FAIL | Package-list test passes; unchanged WebSocket handshake and transfer-encoding tests still receive 501/502 rather than 400 |
+| Full client suite run separately | FAIL | 2455 passed, 35 skipped, 8 failed; six existing raw HTTP/SSE cases and two outdated publication-workflow assertions |
+| Release-workflow and registration follow-up | PASS | 74 passed after updating the expected two-phase installation checks; dynamic registration uses an isolated real registry |
+| Hygiene | PASS | No local paths or credential-like strings found |
+| Repository health | PASS | 106 passed, 1 warning, 0 failed after adding this evidence |
+
+## Cleanup
+
+The distribution verifier shuts down its owned HTTP server, joins its thread,
+closes the HTTP client and removes its temporary virtual environment. No cloud
+resources were created by these checks.
+
+## Problems found
+
+The first packaging assertion assumed Hatchling retained an extra self-reference;
+actual wheel metadata expands `all`/`dev`. The corrected test checks their exact
+server dependency. The first HTTP probe used `close()` instead of the public
+`ServerClient.aclose()`; after correcting the probe, the complete isolated
+installation check passed. These were test-harness errors, not product failures.
+The uv-created development virtual environment initially lacked pip; the server
+package-list regression passed after installing pip. No server product source
+was changed. Two server tests still fail with 501/502 responses:
+`test_upgrade_without_a_key_is_a_400_not_a_hang` and
+`test_transfer_encoding_rejected_in_policy_mode`.
+
+The client managed-runtime failures concern private octet-stream rejection
+(dispatcher/worker), incomplete request bodies, HTTP/1.1 SSE framing, and
+post-header SSE failures (runtime/managed). They received timeouts or HTTP501.
+Those runtime implementations and test assertions were not modified. Their
+root cause has not been established by this change; no assertions were relaxed.
+The two publication tests initially assumed one install/import verification
+phase; their updated two-phase expectations pass, including existing failure
+and retry bounds.
+
+The existing pytest-asyncio default fixture-loop warning and mypy unused-section
+notice remain informational.
+
+## Not verified
+
+No package was published and no claim is made about an already published wheel
+adopting these source changes. Full cloud `make e2e`, conditional provider features
+and the Python 3.10/3.12 CI matrix have not been executed in this local check.
+
+## Current CLI documentation follow-up
+
+Current bilingual usage/reference guides and the SDK authoring skill were checked
+against the coordinated CLI source. The command map now describes first-party
+runtime and authoring responsibilities; template build/publish and named deploy
+are distinct, SDK instance methods are preserved, and CLI local names must be
+resolved to actual Sandbox IDs before Python connects. Archives/design history
+remain unchanged. Changed Markdown introduced no missing relative link targets;
+this is current-source guidance, not a claim of a new CLI/PyPI release.
+
+## Final documentation check
+
+- Changed Markdown local-link audit: 47 files checked, no introduced missing file links. URL anchors and remote pages were not fetched.
+- Current CLI examples use named deploy/status/delete, sandbox operations and Provider run with JSON input. Historical archived documents remain historical.
+- CHANGELOG updated; no version bump or package publication.

.agents/evidence/verify/2026-11-10-recent-change-index.md

@@ -0,0 +1,71 @@
+# Verification: recent python-sdk change records
+
+- Date: 2026-11-10
+- Result: PASS (records-only checks; implementation gates remain separate)
+- Scope: `.agents/README.md`, the recent-change process note and this evidence.
+- Source revision inspected: `2abbdb02500c12dd8841ab32211372c3ef883c12`.
+- Mainline revision inspected: `eb7c980a825d804483474923938277700e048571`.
+- Remote query timestamp: `2026-11-10T14:48:35.682193+00:00`.
+- Environment: Linux, Git, Python 3; source and remote metadata inspection only.
+
+## Commands and observations
+
+- `git fetch origin --prune`: exit 0 in the owning source repository.
+- `git status --short --branch`: the selected worktree was clean before this edit.
+- `git log origin/main --first-parent --since=2026-11-05 -8`: inspected source history.
+- `git rev-parse HEAD` and `git rev-parse origin/main`: revisions listed above.
+- GitHub REST GET repository PR and Actions runs: remote metadata queried separately
+  from any claim of executing tests locally. Authenticated REST supplied a consistent metadata snapshot.
+
+## Prior source CI snapshot
+
+[python-sdk PR #160](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/160) was open, Draft and unmerged.
+
+| Workflow | State | Result |
+| --- | --- | --- |
+| [CI](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/42806475630) | completed | success |
+| [Docs links](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/42806476211) | completed | success |
+
+These results belong to the source revision above, before this records commit.
+New commits require their own CI; a queued workflow is not a pass.
+
+## Local records validation
+
+- Scoped inline Markdown check below: exit 0; staged relative links resolved.
+- One-off ADR/scope/privacy validation: PASS; seven ordered required sections,
+  proposed lifecycle, 3 intended files, tracked index membership,
+  no machine paths or credential-pattern matches. All 166
+  relative links in the scoped documents resolved, including the existing README index.
+- `git diff --cached --check -- .agents`: exit 0.
+- Reviewed the staged `.agents` diff; no runtime/configuration/public article changes.
+- `bash scripts/check-repo-health.sh`: exit 0, 106 pass, 0 fail; one existing warning retained.
+- `make hygiene`: exit 0.
+- `bash .githooks/check-secrets.sh`: exit 0.
+
+Reproducible scoped link check, run from this repository after staging:
+
+```bash
+python3 - <<'PY'
+from pathlib import Path
+import re, subprocess
+files = subprocess.check_output(
+    ["git", "diff", "--cached", "--name-only"], text=True).splitlines()
+for name in files:
+    assert name.startswith(".agents/") and name.endswith(".md")
+    path = Path(name)
+    text = path.read_text()
+    for target in re.findall(r"\[[^\]]*\]\(([^\s)]+)\)", text):
+        if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*:", target) or target.startswith("#"):
+            continue
+        assert (path.parent / target.split("#", 1)[0]).exists(), (name, target)
+print("Scoped staged Markdown links: PASS")
+PY
+```
+
+
+## Not verified and cleanup
+
+No runtime, Docker, cloud, model, performance or new package-publication check was
+run for this records-only change. Earlier acceptance retains its original scope.
+No cloud resources were created, changed or deleted. Required implementation gates
+remain with their existing PRs; this task does not declare those PRs complete.

.agents/evidence/verify/2026-11-10-simplification-main-merge.md

@@ -0,0 +1,38 @@
+# SDK simplification mainline reconciliation — 2026-11-10
+
+Scope: merge the already published simplification branch with fixed main
+`eb7c980a825d804483474923938277700e048571` for
+https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/160 .
+
+## Diagnosis and resolution
+
+GitHub reported the PR as open/draft with `mergeable=false` and
+`mergeable_state=dirty`. Repository Actions were enabled; CI and Docs workflows
+were active and had succeeded for other commits earlier the same day. There were
+no Actions runs for the simplification head. Its queued check suite belonged to
+the Cursor app, not GitHub Actions. GitHub documents that pull_request workflows
+do not run while a PR has a merge conflict:
+https://docs.github.com/en/actions/how-tos/troubleshoot-workflows .
+
+A read-only merge-tree probe identified only the Unreleased CHANGELOG insertion
+as conflicting. The merge retains both the client/runtime boundary entries and
+mainline preview/community documentation. README announcements, QR image and
+PR #158/#159 engineering records remain intact. No runtime, dependency, release
+version, workflow trigger or approval policy was changed to unblock CI. The
+published branch was merged, not rebased or force-pushed.
+
+## Local verification
+
+- Targeted packaging, release-validation, version-lockstep, missing-server and
+  command-registration tests: **88 passed** on the existing Python 3.11 venv.
+- Repository hygiene and git diff whitespace checks passed.
+- Changed Markdown local-file links: 9 files checked, no missing targets. This
+  does not check remote HTTP links or anchor fragments.
+- Current mainline QR asset and four prior engineering record files matched the
+  fixed upstream bytes. Both README announcement and community lines matched
+  upstream verbatim.
+
+The broader earlier SDK verification and its recorded raw-network failures remain
+in `2026-11-10-client-runtime-boundaries.md`; this documentation merge does not
+claim a new full-suite or cloud result. Remote CI must run on the pushed merge
+commit before the PR can satisfy its merge gates.

.agents/notes/proposed/architecture/2026-11-10-client-runtime-boundaries.md

@@ -0,0 +1,82 @@
+# Decision: Separate client installation from local server execution
+
+Status: proposed
+
+## Problem
+
+The Python client installed the local application runtime even when callers only
+used standard cloud clients or application HTTP. The module-level `sandbox.run`
+also created an implicit code-interpreter sandbox and called a name without
+uploading the registered local function, obscuring the deployment boundary.
+
+## Decision
+
+Keep both distributions and their lockstep versions. Move the server dependency
+to the client `server` extra and include it in `all` and `dev`. Preserve standard
+clients, ProviderSandbox, ServerClient, shared client models, and the real remote
+execution decorator. Remove only the factory's legacy run/run_async and private
+execution helpers and unconsumed registered-function source capture. Local registration requires the server extra and fails with
+installation guidance before storing local metadata if the runtime is missing.
+
+## API Design
+
+- `pip install agent-sandbox-client` installs the client alone in future releases.
+- `agent-sandbox-client[server]` selects the exact matching local runtime.
+- `@sandbox(...)`, `@sandbox.register`, `sandbox.server` and `list_registered`
+  remain distinct operations. Registration does not deploy functions.
+- Remove `_SandboxFactory.run` and `run_async`. Use an explicitly selected
+  `ServerClient.commands.run` for deployed application commands.
+- Instance `ProviderSandbox.run` / `invoke` remain unchanged.
+
+No release version is changed or published in this work.
+
+## Alternatives considered
+
+- Keep the hard dependency: preserves unnecessary coupling and conceals the
+  difference between calling a remote application and running its server.
+- Remove the real decorator or merge standard/provider clients: independent
+  capabilities with observable contracts; outside the simplification scope.
+- Keep a compatibility factory forwarding to an arbitrary template: still cannot
+  deploy the local registered function and preserves the ambiguity.
+- Silently allow registration without a runtime: reports success for an unusable
+  command and becomes more common after making the dependency optional.
+
+## Dependencies
+
+Tracking: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/157
+
+
+The runtime remains a separate namespace distribution with its current exact
+version pin. No new library, framework, launcher or cloud resource is introduced.
+Release and health checks must enforce optionality rather than the old mandatory
+runtime invariant.
+
+## Test Strategy
+
+Run both package suites, lint, type checks, builds, repository health and hygiene.
+Inspect actual wheel metadata for base/server/all/dev requirements. Install the
+client wheel in an isolated environment outside source directories, assert the
+runtime is absent, import all client surfaces and perform a real local HTTP
+request. Resolve the server extra only from the locally built wheel and register
+a real function. Keep cloud E2E results separate from local distribution checks.
+
+## Acceptance criteria
+
+- Base installation works without a local runtime and calls application HTTP.
+- Optional server installation preserves namespace imports and registration.
+- Missing-runtime registration is actionable and leaves no partial registration.
+- Removed factory execution is absent; existing decorator/instance tests pass.
+- Both languages document installation and the explicit invocation boundary.
+- Required validation and its limits are recorded before merge.
+
+## Evidence
+
+- [Verification](../../../evidence/verify/2026-11-10-client-runtime-boundaries.md)
+
+## Mainline reconciliation
+
+PR #160 initially had no Actions run because its branch conflicted with the current mainline. GitHub reported `mergeable=false` / `mergeable_state=dirty`; repository Actions and CI/Docs workflows were enabled. The one queued check suite belonged to Cursor, not GitHub Actions.
+
+Merge fixed main `eb7c980a825d804483474923938277700e048571` without rebasing the published branch. Its changes are the preview/community announcement and QR replacement from PR #158/#159. Only the Unreleased changelog insertion conflicts; retain both sides' entries and preserve the README announcements, current QR asset and their historical records. No SDK/runtime/workflow changes are needed for this reconciliation. Parent review accepted this minimal resolution and documentation plus focused packaging validation.
+
+References: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/160 ; https://docs.github.com/en/actions/how-tos/troubleshoot-workflows .