Merge pull request #68 from Alibaba-Agent-Sandbox/fix/provider-preflight-20261018

fix(providers): enforce native PTY before context or wire access

Author: anycodes

.agents/README.md

@@ -77,3 +77,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 - [Final provider convergence acceptance](evidence/verify/2026-10-18-provider-convergence-acceptance.md)
 
 - [Provider-owned metadata follow-up](evidence/verify/2026-10-18-provider-owned-metadata-followup.md)
+
+- [Provider preflight](notes/proposed/feature/2026-10-18-provider-preflight.md) · [verification](evidence/verify/2026-10-18-provider-preflight.md)

.agents/evidence/verify/2026-10-18-provider-preflight.md

@@ -0,0 +1,20 @@
+# Native provider preflight verification — 2026-10-18
+
+Result: scoped local PASS; exact-head full hosted matrix pending.
+
+Base5a99f0fa; Python3.13 with the locked development environment and actual current
+client/server sources selected before imports.
+
+- Regression before fix:1 FAIL (session.url accessed on absent context); after:
+ 1 PASS with ProviderFeatureNotSupportedError before context or wire access.
+- Full maintained client2180 PASS/24 SKIP. Lint/format/typecheck PASS for both packages.
+- Actual local Express suite112 PASS/2 Volume opt-in SKIP/2 slow DESELECT/1 existing
+ KI-009 XFAIL (Jupyter404 and documented shell fallback). No assertion weakened.
+- Task tracker cleanup executed; independent complete read-only list confirmed zero
+ current-date E2E-tagged sandboxes. No unrelated resource was deleted.
+- Server code/distribution metadata are unchanged; full hosted Python3.10/3.11/3.12
+ client/server/package matrix is required before merge. No cloud/model Actions run.
+- Final owner record/link/hygiene checks follow preparation.
+
+The standard migration and successful account-dependent pause/snapshot acceptance
+remain separate in PR47. This patch enables no new capability or package release.

.agents/notes/proposed/feature/2026-10-18-provider-preflight.md

@@ -0,0 +1,36 @@
+# Decision: Check native PTY before terminal context or wire access
+
+Status: proposed
+
+## Problem
+The native Express terminal implementation did not enforce its declared PTY
+feature before touching the supplied session and wire adapter. The fix was trapped
+in the larger conditional migration branch.
+
+## Decision
+Apply the provider declaration check at the start of open_terminal. Preserve the
+existing native public API and available Express behavior independently of migration.
+
+## API Design
+Undeclared PTY raises ProviderFeatureNotSupportedError before context or network
+access. Valid declared terminal calls continue through the existing adapter.
+
+## Alternatives considered
+Waiting for unrelated snapshot/standard frontend prerequisites leaves the defect
+on main. Failing later with attribute or transport errors loses the typed contract.
+
+## Dependencies
+Current accepted main5a99f0fa. Related owner migration issue:
+https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/36
+Companion CLI issue https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/issues/33.
+
+## Test Strategy
+Observe failing unguarded access, verify the feature error, run all maintained client
+checks and real available Express lifecycle/terminal/server coverage and cleanup.
+
+## Acceptance criteria
+Regression, maintained client checks and real available backend acceptance pass;
+latest full hosted matrix passes before normal merge. No conditional feature is enabled.
+
+## Evidence
+[Verification](../../../evidence/verify/2026-10-18-provider-preflight.md).

CHANGELOG.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Fixed
 
+- Reject undeclared native Express PTY before session/context or wire access.
+
 - Reconcile provider isolation with accepted native transport, explicit-key authentication and retired-module cleanup; preserve canonical compatibility aliases and pure configuration metadata.
 
 ### Documentation

client-sdk/src/agent_sandbox/providers/alicloud_express/provider.py

@@ -156,6 +156,7 @@ async def prepare_session(
         return binding
 
     async def open_terminal(self, sandbox: Any, **options: Any) -> Any:
+        self.require("pty")
         from agent_sandbox.providers.shared.e2b.terminal import TerminalSession
 
         return await TerminalSession.create(

client-sdk/tests/test_providers/test_terminal_feature_contract.py

@@ -0,0 +1,13 @@
+"""Declared absence must refuse PTY before touching session or wire state."""
+
+import pytest
+
+from agent_sandbox.models.errors import ProviderFeatureNotSupportedError
+from agent_sandbox.providers.alicloud_express.provider import AlicloudExpressProvider
+
+
+async def test_native_terminal_checks_feature_before_session_access() -> None:
+    provider = AlicloudExpressProvider()
+    provider.features = provider.features - {"pty"}
+    with pytest.raises(ProviderFeatureNotSupportedError):
+        await provider.open_terminal(None)

docs/en/guide/providers.md

@@ -400,3 +400,8 @@ A package can also publish an entry point in the group `agent_sandbox.providers`
 - [Configuration reference](../reference/configuration.md) — names, aliases, precedence
 - [Authentication](authentication.md)
 - [Design: providers and credentials](../design/providers-and-credentials.md)
+
+Native terminal access enforces the provider's `pty` declaration before reading
+session context or starting its wire adapter. An unsupported terminal returns the
+typed provider feature error; declaring a client method does not enable an account
+or function capability.

docs/zh/guide/providers.md

@@ -395,3 +395,6 @@ register_provider(MyProvider())
 - [配置参考](../reference/configuration.md) —— 名称、别名、优先级
 - [认证详解](authentication.md)
 - [设计：提供方与凭证](../design/providers-and-credentials.md)
+
+原生终端在读取会话上下文或启动协议适配器前检查 Provider 的 `pty` 声明。
+不支持时返回明确的能力错误；客户端存在方法并不代表账号或函数已开通该能力。