agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/studio/dsh_capability_service.py

@@ -14,13 +14,14 @@ import json
 import os
 import re
 import secrets
+import threading
 from collections.abc import Callable, Coroutine, Mapping, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from dataclasses import field as dataclass_field
 from pathlib import Path
-from typing import Any, Literal, cast
+from typing import Any
 
-import httpx
+import httpx as httpx  # Preserve the existing injected HTTP-client seam.
 from pydantic import ValidationError
 
 from ksadk.plugins.bridges.dsh import (
@@ -28,12 +29,21 @@ from ksadk.plugins.bridges.dsh import (
     DshProfilePluginBridge,
     DshProfileProjection,
 )
+from ksadk.plugins.companion_artifacts import DshCompanionArtifact, companion_artifact
+from ksadk.plugins.companions import (
+    CompanionError,
+    DshCompanionDefinition,
+    DshPluginCompanionManager,
+)
+from ksadk.plugins.dsh_home import (
+    DshHomeVersionError,
+    default_studio_dsh_home,
+    prepare_studio_dsh_home,
+    studio_dsh_home,
+)
 from ksadk.plugins.dsh_toolchain import DshToolchainManager
 from ksadk.plugins.host import PluginHostError
 from ksadk.plugins.providers.dsh_capabilities import (
-    DSH_CAPABILITY_BUNDLE_PACKAGE,
-    DSH_CAPABILITY_HOST_VERSION,
-    DSH_CAPABILITY_MCP_PROTOCOL,
     DshCapabilityTool,
     DshMcpConnectorLease,
     DshProfileCapabilityDescriptor,
@@ -48,6 +58,16 @@ from ksadk.resource_runtime.supervisor import (
     ResourceSupervisor,
 )
 from ksadk.resource_runtime.worker import WorkerInitialization
+from ksadk.studio.dsh_lifecycle import DshStartupLifecycle
+from ksadk.studio.dsh_mcp_transport import (
+    DshMcpTransport,
+)
+from ksadk.studio.dsh_mcp_transport import (
+    _duplicate_rejecting_object as _duplicate_rejecting_object,
+)
+from ksadk.studio.dsh_mcp_transport import (
+    _reject_non_finite as _reject_non_finite,
+)
 from ksadk.studio.errors import StudioError
 
 _CALL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$")
@@ -74,6 +94,7 @@ class DshCapabilityRuntimeSnapshot:
 
     descriptor: DshProfileCapabilityDescriptor
     lease: DshMcpConnectorLease = dataclass_field(repr=False)
+    generation_id: str = ""
 
 
 @dataclass(frozen=True)
@@ -103,20 +124,7 @@ def _strict_json_size(value: Any) -> int:
     return len(encoded)
 
 
-def _duplicate_rejecting_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
-    value: dict[str, Any] = {}
-    for key, item in pairs:
-        if key in value:
-            raise ValueError("duplicate JSON member")
-        value[key] = item
-    return value
-
-
-def _reject_non_finite(value: str) -> None:
-    raise ValueError(f"non-finite JSON number: {value}")
-
-
-class StudioDshCapabilityService:
+class StudioDshCapabilityService(DshStartupLifecycle, DshMcpTransport):
     """Lazy, generation-fenced access to a DSH Profile's real MCP lease."""
 
     def __init__(
@@ -166,16 +174,101 @@ class StudioDshCapabilityService:
         self._active_calls: dict[str, _ActiveCall] = {}
         self._closed = False
         self.model_projection = None
+        self._companion_definitions: tuple[DshCompanionDefinition, ...] = ()
+        self._companion_manager: DshPluginCompanionManager | None = None
+        self._startup_stage = "not_started"
+        self._startup_failure: dict[str, Any] | None = None
+        # Cached result of ``has_enabled_profile_plugins`` keyed by the managed
+        # state file mtime (``None`` when the file is absent), so repeated page
+        # loads never re-run the Node bridge probe.
+        self._plugins_probe_cache: tuple[float | None, bool] | None = None
+        self._probe_warmup_tasks: set[asyncio.Task[None]] = set()
+        self._probe_inflight: asyncio.Task[bool] | None = None
+        self._resolved_command: tuple[str, ...] | None = None
+        self._resolve_lock = threading.Lock()
+
+    def schedule_plugin_probe_warmup(self) -> None:
+        """Warm the enabled-plugin probe once, off the request path.
+
+        Fire and forget: failures are swallowed because the entry point has
+        its own bounded fallback, and tasks are tracked so shutdown can
+        cancel them.
+        """
+
+        async def _warm() -> None:
+            try:
+                await self.has_enabled_profile_plugins()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                return
+
+        task = asyncio.create_task(_warm())
+        self._probe_warmup_tasks.add(task)
+        task.add_done_callback(self._probe_warmup_tasks.discard)
+
+    def configure_companions(self, definitions: Sequence[DshCompanionDefinition]) -> None:
+        """Configure trusted lifecycle callbacks before this Profile starts."""
+        if self._host is not None or self._closed:
+            raise CompanionError("COMPANION_CONFIGURATION_BUSY")
+        if any(item.profile != self._profile for item in definitions):
+            raise CompanionError("COMPANION_PROFILE_MISMATCH")
+        self._companion_definitions = tuple(definitions)
+
+    @property
+    def companion_manager(self) -> DshPluginCompanionManager | None:
+        return self._companion_manager
+
+    async def call_companion_tool(
+        self, plugin_id: str, principal: Any, operation: str, arguments: Mapping[str, Any],
+        *, call_id: str, deadline_ms: int = 60_000,
+    ) -> dict[str, Any]:
+        """Run an actual Cordis tool with a host-issued opaque invocation scope."""
+        if not re.fullmatch(r"[A-Za-z0-9_.:-]{1,128}", call_id) or not 1 <= deadline_ms <= 120_000:
+            raise CompanionError("COMPANION_REQUEST_INVALID")
+        if _strict_json_size(arguments) > self._max_argument_bytes:
+            raise CompanionError("COMPANION_REQUEST_INVALID")
+        async with self._lock:
+            host, lease = await self._ensure_ready_locked()
+            manager = self._companion_manager
+            if manager is None or operation not in {tool.name for tool in host.descriptor.tools}:
+                raise CompanionError("COMPANION_UNAVAILABLE")
+            handle = manager.issue_invocation(
+                plugin_id, principal, operations=frozenset({operation}),
+                ttl_seconds=deadline_ms / 1000,
+            )
+            token = lease.companion_bearer_token(
+                plugin_id=plugin_id, generation_id=manager.generation_id,
+                handle=handle, tool_name=operation, call_id=call_id,
+                ttl_seconds=max(1, (deadline_ms + 999) // 1000),
+            )
+            scoped = replace(lease, _bearer_token=token, _browser_token="")
+        try:
+            result = await self._mcp_request(
+                scoped, request_id=call_id, method="tools/call",
+                params={"name": operation, "arguments": dict(arguments)},
+                timeout_seconds=deadline_ms / 1000,
+            )
+            if result.get("isError"):
+                code = result.get("_meta", {}).get("io.ksadk/dsh", {}).get("code", "")
+                raise CompanionError(code if isinstance(code, str) and re.fullmatch(
+                    r"COMPANION_[A-Z_]{1,96}", code
+                ) else "COMPANION_TOOL_FAILED")
+            value = result.get("structuredContent")
+            if not isinstance(value, dict):
+                raise CompanionError("COMPANION_RESPONSE_INVALID")
+            return value
+        except (asyncio.TimeoutError, StudioError) as error:
+            # Preserve the caller's native call_id. A retry must reuse it so
+            # the domain can look up an already committed result.
+            raise CompanionError("COMPANION_OUTCOME_UNCERTAIN") from error
+        finally:
+            manager.revoke_invocation(handle)
 
     @classmethod
     def discover_or_create_workspace_default(cls, workspace: Path) -> "StudioDshCapabilityService":
         root = workspace.resolve()
-        configured_home = os.environ.get("KSADK_DSH_HOME", "").strip()
-        dsh_home = (
-            Path(configured_home).expanduser()
-            if configured_home
-            else root / ".agentkit" / "dsh-home"
-        )
+        dsh_home = studio_dsh_home(root)
         profile = os.environ.get("KSADK_DSH_PROFILE", "").strip() or "web"
         configured_bin = os.environ.get("KSADK_DSH_BIN", "").strip()
         command = (str(Path(configured_bin).expanduser()),) if configured_bin else None
@@ -195,7 +288,7 @@ class StudioDshCapabilityService:
         command = (str(Path(configured_bin).expanduser()),) if configured_bin else None
         return cls(
             root,
-            dsh_home=root / ".agentkit" / "dsh-home",
+            dsh_home=default_studio_dsh_home(root),
             profile="agentkit-resources",
             dsh_command=command,
             mount_studio_app=False,
@@ -225,8 +318,69 @@ class StudioDshCapabilityService:
                     "DSH capability service 已关闭",
                     status_code=503,
                 )
+            # This check is used by the HTTP entry point only to choose the
+            # initial document.  Starting a Node/DSH bridge here made every
+            # fresh page and workspace switch wait several seconds.  The
+            # managed state file is the same source consumed by
+            # ``DshProfilePluginBridge.list_plugins``; read it directly and
+            # fall back to the validated bridge only for legacy/incomplete
+            # profiles.  The result is cached against the state file mtime so
+            # legacy profiles do not pay a cold Node bridge on every page.
+            state_mtime = self._profile_state_mtime()
+            cached = self._plugins_probe_cache
+            if cached is not None and cached[0] == state_mtime:
+                return cached[1]
+            fast = self._profile_has_enabled_plugins_from_state()
+            if fast is not None:
+                self._plugins_probe_cache = (state_mtime, fast)
+                return fast
+            if self._probe_inflight is None:
+                self._probe_inflight = asyncio.create_task(
+                    self._run_bridge_probe(state_mtime)
+                )
+            inflight = self._probe_inflight
+        # The slow Node bridge probe must run WITHOUT ``self._lock`` held:
+        # every DSH-dependent request (session creation, /studio-core/ lease)
+        # queues on that lock, so pinning it for the whole cold probe turned
+        # warmup into a service-wide stall.  ``shield`` keeps the shared
+        # probe alive when a bounded caller (index timeout) gives up.
+        return await asyncio.shield(inflight)
+
+    async def _run_bridge_probe(self, state_mtime: float | None) -> bool:
+        result: bool | None = None
+        try:
             command = await asyncio.to_thread(self._resolve_command)
-            return await asyncio.to_thread(self._profile_has_enabled_plugins, command)
+            result = await asyncio.to_thread(self._profile_has_enabled_plugins, command)
+        finally:
+            async with self._lock:
+                self._probe_inflight = None
+                if result is not None and not self._closed:
+                    self._plugins_probe_cache = (self._profile_state_mtime(), result)
+        return result
+
+    def _profile_state_mtime(self) -> float | None:
+        """Return the managed plugin state file mtime, or ``None`` if absent."""
+
+        try:
+            return self._profile_state_path().stat().st_mtime
+        except OSError:
+            return None
+
+    def _profile_state_path(self) -> Path:
+        return self._dsh_home / "profiles" / self._profile / ".ksadk-dsh-plugins.json"
+
+    def _profile_has_enabled_plugins_from_state(self) -> bool | None:
+        """Return enabled state without invoking npm/Node, or ``None`` if unavailable."""
+
+        try:
+            state = json.loads(self._profile_state_path().read_text(encoding="utf-8"))
+            order = state.get("order")
+            disabled = set(state.get("disabled") or ())
+            if not isinstance(order, list) or not all(isinstance(item, str) for item in order):
+                return None
+            return any(item not in disabled for item in order)
+        except (OSError, UnicodeError, ValueError, TypeError, AttributeError):
+            return None
 
     def capture_resource_build_snapshot(self) -> DshProfileBuildSnapshot:
         """Capture immutable Profile inputs for a caller-owned Build staging area.
@@ -267,7 +421,9 @@ class StudioDshCapabilityService:
             host, lease = await self._ensure_ready_locked()
             descriptor = host.descriptor
             self._validate_lease(descriptor, lease)
-            return DshCapabilityRuntimeSnapshot(descriptor=descriptor, lease=lease)
+            return DshCapabilityRuntimeSnapshot(
+                descriptor=descriptor, lease=lease, generation_id=self._require_generation_id()
+            )
 
     async def capability_snapshot(self) -> DshCapabilitySnapshot:
         """Read descriptor, tools and health without crossing a refresh."""
@@ -517,6 +673,17 @@ class StudioDshCapabilityService:
             await self._dispose_generation_locked()
 
     async def aclose(self) -> None:
+        # Cancel tracked warmup probes first; a slow Node bridge probe must
+        # not delay shutdown.  The shared in-flight probe is shielded from
+        # its awaiters, so cancel it explicitly here.
+        for task in tuple(self._probe_warmup_tasks):
+            task.cancel()
+        if self._probe_warmup_tasks:
+            await asyncio.gather(*self._probe_warmup_tasks, return_exceptions=True)
+        inflight = self._probe_inflight
+        if inflight is not None:
+            inflight.cancel()
+            await asyncio.gather(inflight, return_exceptions=True)
         async with self._lock:
             if self._closed:
                 return
@@ -529,7 +696,7 @@ class StudioDshCapabilityService:
         async with self._lock:
             return await self._ensure_ready_locked()
 
-    async def _ensure_ready_locked(
+    async def _ensure_ready_generation_locked(
         self,
     ) -> tuple[DshProfileCapabilityHost, DshMcpConnectorLease]:
         if self._closed:
@@ -554,8 +721,11 @@ class StudioDshCapabilityService:
             return await self._start_host_locked(host, projection)
 
         try:
+            self._startup_stage = "toolchain"
             command = await asyncio.to_thread(self._resolve_command)
+            self._startup_stage = "profile_projection"
             projection = await asyncio.to_thread(self._project_profile, command)
+            self._startup_stage = "host_configuration"
             host = self._host_factory(
                 command,
                 projection=projection,
@@ -591,10 +761,39 @@ class StudioDshCapabilityService:
         # A restarted Core must never inherit workers or resource handles from
         # the previous generation, including when the restart subsequently fails.
         self._resource_generation_snapshot = None
+        self._startup_stage = "previous_generation_cleanup"
+        await self._close_companions_locked()
         await self._close_resource_supervisor_locked()
         generation_id = f"dshgen_{secrets.token_urlsafe(24)}"
         try:
+            self._startup_stage = "companion_graph"
+            definitions = []
+            for definition in self._companion_definitions:
+                packages = set(definition.components.values())
+                present = packages.intersection(projection.bundles)
+                if present and present != packages:
+                    raise CompanionError("COMPANION_GRAPH_INCOMPLETE")
+                if present:
+                    definitions.append(definition)
+            if definitions:
+                self._startup_stage = "companion_artifact"
+                command = await asyncio.to_thread(self._resolve_command)
+                artifacts = await asyncio.to_thread(
+                    self._capture_companion_artifacts, command, definitions, projection,
+                )
+                manager = DshPluginCompanionManager(
+                    profile=self._profile, generation_id=generation_id,
+                    definitions=tuple(definitions),
+                    artifacts=artifacts,
+                )
+                self._companion_manager = manager
+                self._startup_stage = "companion_broker"
+                await manager.start_broker()
+                await host.configure_companions(manager.configuration)
+            elif self._companion_definitions:
+                await host.configure_companions(None)
             if "@kingsoftcloud/dsh-platform-resources" in projection.bundles:
+                self._startup_stage = "resource_broker"
                 ledger = await asyncio.to_thread(
                     OperationLedger, self._workspace / ".agentkit" / "resource-operations"
                 )
@@ -603,7 +802,9 @@ class StudioDshCapabilityService:
                 )
                 socket_path = await self._resource_supervisor.start_broker()
                 await host.configure_resource_socket(socket_path)
+            self._startup_stage = "core_start"
             lease = await host.lease()
+            self._startup_stage = "core_protocol"
             descriptor = host.descriptor
             if (
                 lease.profile != projection.profile
@@ -612,18 +813,30 @@ class StudioDshCapabilityService:
             ):
                 raise self._protocol_error()
             await self._initialize_lease(lease)
+            if self._companion_manager is not None:
+                self._startup_stage = "companion_artifact_verification"
+                verified = await asyncio.to_thread(
+                    self._capture_companion_artifacts, command, definitions, projection,
+                )
+                if verified != artifacts:
+                    raise CompanionError("COMPANION_ARTIFACT_CHANGED_DURING_BOOT")
+                self._startup_stage = "companion_start"
+                await self._companion_manager.confirm_core_ready()
         except StudioError as error:
             self._lease = None
+            await self._close_companions_locked()
             await self._close_resource_supervisor_locked()
             if error.code == "DSH_CAPABILITY_PROTOCOL_INVALID":
                 await self._dispose_generation_locked()
             raise
         except (PluginHostError, OSError, ValueError) as error:
             self._lease = None
+            await self._close_companions_locked()
             await self._close_resource_supervisor_locked()
             raise self._unavailable(error) from error
         except BaseException:
             self._lease = None
+            await self._close_companions_locked()
             await self._close_resource_supervisor_locked()
             raise
         self._lease = lease
@@ -804,14 +1017,28 @@ class StudioDshCapabilityService:
             await self._finish_cleanup(supervisor.aclose())
 
     def _resolve_command(self) -> tuple[str, ...]:
-        try:
-            return tuple(DshToolchainManager().require_command(self._explicit_dsh_executable))
-        except Exception as error:
-            raise StudioError(
-                "DSH_CAPABILITY_HOST_UNAVAILABLE",
-                "DSH capability host 未安装、版本不匹配或不可用",
-                status_code=503,
-            ) from error
+        # pnpm/toolchain inspection is a multi-second cold subprocess chain;
+        # the result is deterministic for this process, so memoize it — both
+        # the warmup probe and the first Core startup otherwise re-pay it.
+        if self._resolved_command is not None:
+            return self._resolved_command
+        with self._resolve_lock:
+            if self._resolved_command is None:
+                try:
+                    prepare_studio_dsh_home(self._dsh_home)
+                    command = tuple(
+                        DshToolchainManager().require_command(self._explicit_dsh_executable)
+                    )
+                except DshHomeVersionError as error:
+                    raise self._unavailable(error) from error
+                except Exception as error:
+                    raise StudioError(
+                        "DSH_CAPABILITY_HOST_UNAVAILABLE",
+                        "DSH capability host 未安装、版本不匹配或不可用",
+                        status_code=503,
+                    ) from error
+                self._resolved_command = command
+            return self._resolved_command
 
     def _project_profile(self, command: Sequence[str]) -> DshProfileProjection:
         try:
@@ -837,6 +1064,34 @@ class StudioDshCapabilityService:
         except Exception as error:
             raise self._unavailable(error) from error
 
+    def _capture_companion_artifacts(
+        self,
+        command: Sequence[str],
+        definitions: Sequence[DshCompanionDefinition],
+        projection: DshProfileProjection,
+    ) -> dict[str, DshCompanionArtifact]:
+        with self._bridge_factory(
+            dsh_home=self._dsh_home,
+            profile=self._profile,
+            dsh_command=command,
+            cwd=self._workspace,
+        ) as bridge:
+            with bridge._profile_transaction(exclusive=False):
+                snapshot = bridge.snapshot_for_build()
+                if snapshot.projection != projection:
+                    raise CompanionError("COMPANION_ARTIFACT_PROFILE_MISMATCH")
+                inventory = bridge.list_plugins()
+                return {
+                    definition.plugin_id: companion_artifact(
+                        plugin_id=definition.plugin_id,
+                        components=definition.components,
+                        snapshot=snapshot,
+                        inventory=inventory,
+                        sources=definition.artifact_sources,
+                    )
+                    for definition in definitions
+                }
+
     def _verify_resource_build_snapshot(
         self, command: Sequence[str], expected: DshProfileBuildSnapshot
     ) -> None:
@@ -914,7 +1169,10 @@ class StudioDshCapabilityService:
         self._generation_id = None
         self._active_calls.clear()
         try:
-            await self._close_resource_supervisor_locked()
+            try:
+                await self._close_companions_locked()
+            finally:
+                await self._close_resource_supervisor_locked()
         finally:
             if active:
                 await asyncio.gather(
@@ -939,158 +1197,13 @@ class StudioDshCapabilityService:
         if interrupted:
             raise asyncio.CancelledError
 
-    async def _mcp_request(
-        self,
-        lease: DshMcpConnectorLease,
-        *,
-        request_id: str,
-        method: Literal[
-            "initialize",
-            "io.ksadk/scopes/revoke",
-            "tools/list",
-            "tools/call",
-        ],
-        params: Mapping[str, Any],
-        timeout_seconds: float,
-    ) -> dict[str, Any]:
-        payload = {
-            "jsonrpc": "2.0",
-            "id": request_id,
-            "method": method,
-            "params": dict(params),
-        }
-        headers = {**lease.headers(), "Content-Type": "application/json"}
-        try:
-            async with httpx.AsyncClient(
-                headers=headers,
-                timeout=timeout_seconds,
-                trust_env=False,
-            ) as client:
-                response = await client.post(lease.endpoint, json=payload)
-        except httpx.TimeoutException as error:
-            raise asyncio.TimeoutError from error
-        except httpx.HTTPError as error:
-            raise StudioError(
-                "DSH_CAPABILITY_HOST_UNAVAILABLE",
-                "DSH capability MCP 连接失败",
-                status_code=503,
-                details={"errorType": type(error).__name__},
-            ) from error
-        if response.status_code != 200 or len(response.content) > self._max_wire_response_bytes:
-            raise self._protocol_error()
-        try:
-            envelope = json.loads(
-                response.content,
-                object_pairs_hook=_duplicate_rejecting_object,
-                parse_constant=_reject_non_finite,
-            )
-        except (UnicodeError, ValueError, TypeError, RecursionError) as error:
-            raise self._protocol_error() from error
-        if (
-            not isinstance(envelope, dict)
-            or envelope.get("jsonrpc") != "2.0"
-            or envelope.get("id") != request_id
-        ):
-            raise self._protocol_error()
-        if "error" in envelope:
-            rpc_error = envelope.get("error")
-            code = rpc_error.get("code") if isinstance(rpc_error, dict) else None
-            raise StudioError(
-                "DSH_CAPABILITY_REQUEST_FAILED",
-                "DSH capability MCP 拒绝了请求",
-                status_code=502,
-                details={"rpcCode": code if isinstance(code, int) else None},
-            )
-        result = envelope.get("result")
-        if not isinstance(result, dict):
-            raise self._protocol_error()
-        try:
-            result_bytes = len(
-                json.dumps(
-                    result,
-                    allow_nan=False,
-                    ensure_ascii=False,
-                    separators=(",", ":"),
-                ).encode("utf-8")
-            )
-        except (TypeError, ValueError, RecursionError) as error:
-            raise self._protocol_error() from error
-        if result_bytes > self._max_result_bytes:
-            raise self._protocol_error()
-        return cast(dict[str, Any], result)
-
-    async def _initialize_lease(self, lease: DshMcpConnectorLease) -> None:
-        request_id = f"initialize-{os.urandom(12).hex()}"
-        result = await self._mcp_request(
-            lease,
-            request_id=request_id,
-            method="initialize",
-            params={
-                "protocolVersion": DSH_CAPABILITY_MCP_PROTOCOL,
-                "capabilities": {},
-                "clientInfo": {"name": "ksadk-studio", "version": "1.0.0"},
-            },
-            timeout_seconds=5.0,
-        )
-        server_info = result.get("serverInfo")
-        capabilities = result.get("capabilities")
-        if (
-            result.get("protocolVersion") != DSH_CAPABILITY_MCP_PROTOCOL
-            or not isinstance(server_info, dict)
-            or server_info.get("name") != DSH_CAPABILITY_BUNDLE_PACKAGE
-            or server_info.get("version") != DSH_CAPABILITY_HOST_VERSION
-            or not isinstance(capabilities, dict)
-            or not isinstance(capabilities.get("tools"), dict)
-        ):
-            raise self._protocol_error()
-        await self._send_notification(
-            lease,
-            method="notifications/initialized",
-            params={},
-            tolerate_failure=False,
-        )
-
-    async def _send_cancel(self, lease: DshMcpConnectorLease, call_id: str) -> None:
-        await self._send_notification(
-            lease,
-            method="notifications/cancelled",
-            params={"requestId": call_id, "reason": "Studio UI cancelled the call"},
-            tolerate_failure=True,
-        )
-
-    async def _send_notification(
-        self,
-        lease: DshMcpConnectorLease,
-        *,
-        method: Literal["notifications/initialized", "notifications/cancelled"],
-        params: Mapping[str, Any],
-        tolerate_failure: bool,
-    ) -> None:
-        headers = {**lease.headers(), "Content-Type": "application/json"}
-        payload = {"jsonrpc": "2.0", "method": method, "params": dict(params)}
-        try:
-            async with httpx.AsyncClient(headers=headers, timeout=2.0, trust_env=False) as client:
-                response = await client.post(lease.endpoint, json=payload)
-            if response.status_code not in {200, 202, 204}:
-                raise self._protocol_error()
-        except (httpx.HTTPError, StudioError):
-            # Disposal still kills the process and aborts all work.  Cancellation
-            # is best effort here so refresh/close cannot be held hostage by a
-            # broken loopback listener.
-            if tolerate_failure:
-                return
-            raise self._protocol_error() from None
-
-    @staticmethod
-    def _protocol_error() -> StudioError:
-        return StudioError(
-            "DSH_CAPABILITY_PROTOCOL_INVALID",
-            "DSH capability MCP 返回了无效响应",
-            status_code=502,
-        )
-
     @staticmethod
     def _unavailable(error: BaseException) -> StudioError:
+        if isinstance(error, DshHomeVersionError):
+            return StudioError(
+                "DSH_HOME_VERSION_UNVERIFIED", str(error), status_code=409,
+                details=error.diagnostic,
+            )
         reason = getattr(error, "code", None)
         return StudioError(
             "DSH_CAPABILITY_HOST_UNAVAILABLE",