feat(agents): add managed per-Session API runtime and bridge

.agents/README.md

@@ -1,5 +1,8 @@
 # `.agents/` — engineering record of the python-sdk repository
 
+- [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).
+
 - [Express SDK completion](notes/implemented/feature/2026-11-05-express-sdk-completion.md) · [verification](evidence/verify/2026-11-05-express-sdk-completion.md).
 - [Provider runtime setup](notes/proposed/process/2026-11-05-provider-runtime-setup.md) · [verification](evidence/verify/2026-11-05-provider-runtime-setup.md).
 

.agents/evidence/verify/2026-11-05-managed-agents-api.md

@@ -0,0 +1,60 @@
+# Verification: Managed Agents API runtime
+
+- Date: 2026-11-05
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/155
+- Result: PARTIAL — implementation and local component verification; full repository, cloud/model and release gates remain in progress.
+- Package under test: isolated feature-branch source; distribution versions remain 0.4.0a6. This does not describe the public 0.4.0a6 artifacts.
+- Environment: CPython 3.12.13 on Linux; isolated PID namespace component runner uses CPython 3.12.16. Real PostgreSQL supplied by pgserver 0.1.4; psycopg 3.3.8. No credential values recorded.
+
+## What was verified
+
+New managed Gateway, durable resources, Worker and private bridge behavior was exercised through
+actual loopback HTTP, disk state, real PostgreSQL and real CLI fixture subprocesses. The fixture
+implements deterministic Qwen stream events; it is not a real model or cloud acceptance claim.
+Legacy public in-sandbox routes are unchanged.
+
+## Commands run
+
+- `python -m pytest client-sdk/tests/test_managed_agents.py -q --disable-warnings --maxfail=1`, inside an isolated PID namespace with source packages and the task virtualenv mounted read-only where appropriate.
+- `mypy src/agent_sandbox/server/`, from `server-sdk`.
+- `mypy src/agent_sandbox/`, from `client-sdk`.
+- `ruff check` and `ruff format` over the new runtime and regression files.
+
+## Results
+
+| Scenario / test | Result | Notes |
+| --- | --- | --- |
+| Managed component regressions | PASS | 29 tests, 17.76 seconds at the recorded checkpoint; later review changes require rerunning |
+| Frozen V1 HTTP inventory | PASS | Every one of 39 operations actually called successfully, plus unauthorized rejection per protected operation, on SQLite and real PostgreSQL |
+| Files, two turns, independent artifact bytes, close/delete | PASS | Real bridge HTTP, filesystem and CLI subprocess; one reused resource and independent local absence |
+| Exact cancellation and durable target replay | PASS | First cancellation never targets the next turn; queued and creation-time cancellation stop submission |
+| Cooperative process stopping | PASS | Leader exits while a detached child continues writing; domain cleanup stops it. Unknown host processes force conservative whole-resource cleanup |
+| Observed tool deadline | PASS | Real sleep subprocess, start without done, and completed-tool control |
+| Limits and retention | PASS | Small output limit, partial HTTP body deadline, bounded GC/pending attachment protection, uncertain resources and more than 10,000 closed tombstones |
+| Lost guest response | PASS | Original durable receipt inspected; exactly one input POST and one filesystem effect |
+| Type checking | PASS | Server 58 source files and client 112 source files at the earlier checkpoint; rerun required for latest stream changes |
+| Full repository checks | IN PROGRESS | Required before merge |
+| Real Express/model deployment | IN PROGRESS | Coordinated separately; no success inferred from fixture tests or source-only installation |
+| Public package/template installation | NOT RUN | Public 0.4.0a6 lacks the new modules; a new actual release is required |
+
+## Cleanup
+
+Every local fixture resource is closed in teardown. PostgreSQL handles stop/delete their temporary
+clusters. Detached regression children are explicitly killed in `finally`. The isolated runner is
+removed after exit. Cloud resources and independent absence belong to the separate cloud evidence;
+no cloud cleanup success is inferred from this local report.
+
+## Problems found
+
+Adversarial reviews identified output-limit propagation, cancellation at the final dispatch fence,
+heartbeat during preparation, uncertain Session freeze, artifact ancestor traversal, depth scanning,
+retention and SSE deletion races. The implementation includes focused regressions; full latest-head
+checks and independent stream-gate review remain pending. Early shared-host process-domain tests
+correctly refused reuse when unrelated same-UID contributor processes appeared; production behavior
+was preserved and coexistence tests moved to an isolated PID namespace.
+
+## Not verified
+
+OpenAI SDK interoperability, arbitrary providers, hostile same-UID integrity, steering, functions,
+arbitrary MCP/subagents and dynamic Session settings are outside the supported V1 subset. Full
+repository CI, real cloud/model business completion and public release/install are not yet complete.

.agents/evidence/verify/2026-11-06-managed-agents-ci-artifacts.md

@@ -0,0 +1,76 @@
+# Verification: Managed Agents CI artifacts
+
+- Date: 2026-11-06
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/156, runtime commit `2ee960cb919d640c282cbbeff24d15aa051b7495`.
+- Result: PARTIAL — required remote CI and exact CI-wheel installation passed; publication and managed FC acceptance are coordinated separately.
+- Package under test: matching client/server 0.4.0a7, downloaded unchanged from the successful GitHub Actions artifact.
+- Environment: GitHub Ubuntu matrix on Python 3.10/3.11/3.12; fresh local CPython 3.12.13 wheel-install environment. No credential values recorded.
+
+## What was verified
+
+The [complete CI run](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/42157232742)
+and [documentation-link run](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/42157232731)
+both completed successfully at the exact runtime commit. The CI distribution archive was
+downloaded and its SHA-256 compared with GitHub's artifact digest before inspecting its members.
+The exact CI wheels were then installed together in a new environment outside the source tree.
+
+The preceding [local/component/cloud checkpoint](2026-11-06-managed-agents-release-candidate.md)
+is preserved. Its locally built packages and the CI packages have identical uncompressed wheel
+members, including code, `METADATA`, `WHEEL` and `RECORD`, but different ZIP external mode attributes:
+local files are `100755`, while CI files are `100644`. The shared development filesystem does
+not preserve normal file modes. These archives therefore have different bytes and must not be
+described as the same tested artifact. The CI originals are the selected publication candidates;
+earlier local artifacts remain a separate comparison, without overwriting either set.
+
+## Commands run
+
+- Fetch the exact commit's Actions runs/jobs and distribution artifact through GitHub.
+- Verify archive SHA-256 against the returned artifact digest.
+- Compare wheel members and ZIP metadata without executing downloaded code.
+- Create a new Python 3.12 environment and install both exact CI wheels, selecting the managed extra.
+- `uv pip check` in that environment.
+- Isolated interpreter probe: matching versions, native provider import without upper managed application imports, identical lower/old public `ManagedError`, server import, and a real SQLite transaction.
+
+## Results
+
+| Check | Result | Scope |
+| --- | --- | --- |
+| Six client/server matrix jobs | PASS | Python 3.10, 3.11 and 3.12; lint, formatting, mypy and complete non-integration tests. |
+| Pinned E2B callable contract | PASS | Public signatures and sync/async shapes. |
+| Python to Node provider engine | PASS | Required cross-language scenarios using the pinned CLI/provider fixtures. |
+| Public runtime fixtures | PASS | Both `python-hello` and `agents-cli` build, run actual HTTP checks and clean up their owned containers. |
+| Hygiene, build and distributions | PASS | Complete CI artifact checks. |
+| Documentation links | PASS | Independent workflow. |
+| Artifact identity | PASS | Artifact 13475860199; archive SHA-256 `26548e9e5a11a59fda47bd664dcf3acec97c773125fa492f198decaf76e2dd61`. |
+| CI versus local wheel payload | SAME FILE BYTES, DIFFERENT ARCHIVE | All 368 client and 65 server uncompressed entries match; only ZIP file-mode metadata differs. |
+| Fresh exact-CI-wheel install | PASS | CPython 3.12.13, consistent dependencies, same error class, no upper application imports from native provider, real SQLite transaction. |
+| PyPI upload/readback and joint managed FC deployment | PENDING | No publication or FC success is inferred from CI. |
+
+### Selected exact CI distributions
+
+| File | SHA-256 |
+| --- | --- |
+| `agent_sandbox_client-0.4.0a7-py3-none-any.whl` | `1fa30ec182465753d9b538b3837d625325da9b4340ba220cfbc0764de6fbca00` |
+| `agent_sandbox_server-0.4.0a7-py3-none-any.whl` | `210db5e796f4fc63e84156d19076c946d261b48c47ec6c8c1db82b8b60691f08` |
+| `agent_sandbox_client-0.4.0a7.tar.gz` | `7e2c9c33d7efa0cc7c89f417ef853089af4fb70e48a25e1661fca761980a1539` |
+| `agent_sandbox_server-0.4.0a7.tar.gz` | `f2e1f4fb6e8e17d272ad35e52e02df26a640c7adcb6e909515b501de517ac063` |
+
+## Cleanup
+
+This continuation performs read-only GitHub access and a bounded local installation/SQLite
+probe. It creates no cloud resource, management key, tag or public release. Temporary database
+files are removed by their context manager. The CI fixture jobs independently confirm deletion
+of their owned containers. The exact distribution archives remain as review artifacts.
+
+## Problems found
+
+Shared-filesystem mode normalization makes local archive hashes differ from canonical CI builds.
+No source or package-metadata content difference was found. Downstream validation must select
+and record one exact distribution set rather than silently treating the two archives as identical.
+
+## Not verified
+
+Public PyPI installation, active managed FC deployment and model business acceptance are not
+certified by this record. The management-key preparation E2E remains intentionally excluded
+pending its separate explicit consent. The generic cloud E2E checkpoint records its actual skips
+and corrected replays independently.

.agents/evidence/verify/2026-11-06-managed-agents-database-ca-argument.md

@@ -0,0 +1,59 @@
+# Verification: Managed database CA startup argument
+
+- Date: 2026-11-06
+- Change: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/156; continuation of runtime `2ee960cb919d640c282cbbeff24d15aa051b7495`.
+- Result: PARTIAL — focused local validation passed; latest full gates and actual FC argument readback are in progress.
+- Package under test: matching 0.4.0a7 source candidate, not yet published.
+- Environment: CPython 3.12.13, psycopg 3.3.8, real local PostgreSQL and SQLite, PID-isolated local CLI fixtures. No credential values recorded.
+
+## What was verified
+
+The deployment continuation identified environment configuration larger than the target FC budget.
+Independent review accepted a narrow public-CA startup argument rather than weakening TLS.
+`--database-ca-base64` decodes canonical Base64 ASCII with both encoded and decoded size bounds,
+rejects a simultaneous existing `ABX_MANAGED_DATABASE_CA_PEM` source, and passes the result to the
+existing certificate-only/X509 validator and private temporary CA-file context. No role credential
+is added to arguments. Existing environment-only usage remains supported.
+
+The official [CustomContainerConfig reference](https://www.alibabacloud.com/help/en/functioncompute/api-fc-2023-03-30-struct-customcontainerconfig)
+defines array startup arguments without a documented size guarantee. The local 64 KiB decode bound
+therefore does not establish FC support for a 64 KiB certificate argument. Actual accepted sizes
+must be recorded from the specific deployment/readback.
+
+## Commands run
+
+- Client Ruff and format checks for the entrypoint and new command tests.
+- `mypy src/agent_sandbox/` in `client-sdk/`.
+- `pytest tests/test_managed_entrypoint.py tests/test_managed_agents.py tests/test_providers/test_managed_import_boundary.py -q` in an isolated PID namespace.
+
+## Results
+
+| Scenario | Result | Scope |
+| --- | --- | --- |
+| Actual command parsing with public CA | PASS | Gateway, Worker and Dispatcher all reach the existing validator and a real 0600 temporary file, removed after startup returns. |
+| Environment compatibility and conflict | PASS | Existing environment source still works; a present source, including an empty one, conflicts with the argument. |
+| Malformed encoding/ASCII/size | PASS | Static parser errors without echoing the supplied value; noncanonical Base64, non-ASCII content and oversized input rejected. |
+| Invalid PEM/X509 and cleanup on startup failure | PASS | Other PEM types and invalid certificates rejected; an exception during startup removes the temporary file. |
+| Focused command/managed API/import regression | PASS | 57 tests, zero skipped, 26.81s. Includes 16 new command cases and the preceding 41 scenarios. |
+| Full client mypy | PASS | 114 files. |
+| Latest complete local/remote CI | IN PROGRESS | Separate results will identify the exact tested commit. |
+| Actual FC creation/startup argument readback | PENDING | No cloud argv-size or successful joint deployment claim is made here. |
+
+## Cleanup
+
+The new command tests start no cloud resource. Their public certificate files are created in
+private temporary directories and are checked absent after both normal return and startup error.
+The real local database and CLI fixture teardown remains unchanged.
+
+## Problems found
+
+The former CA environment-only transport can exceed a constrained deployment's environment
+budget. This optional argument changes transport only; `sslmode=verify-full`, explicit libpq
+CA configuration and certificate validation remain intact.
+
+## Not verified
+
+No new package is published. The preceding CI wheels predate this additional flag and cannot
+stand in for its final distribution. A new exact CI artifact and actual FC readback are required.
+Models/providers in the local regression remain fixtures; its real PostgreSQL/HTTP/process
+components do not imply a real-model FC active-cancellation acceptance.