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

ksadk/plugins/providers/dsh_descriptor_host.py

@@ -0,0 +1,226 @@
+"""Single frozen descriptor host for wheel-owned DSH AgentProviders.
+
+The provider key is a fixed command argument selected by KsADK.  The host
+owns discovery and lifecycle only; model credentials and execution services
+remain in the parent RuntimeAdapter bridge.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from typing import Any, Sequence
+
+from ksadk.plugins.providers.dsh import (
+    DSH_AGENT_PROVIDER_HOST_METHODS,
+    DSH_AGENT_PROVIDER_HOST_PROTOCOL,
+    DshAgentProviderDescriptor,
+)
+from ksadk.plugins.providers.shipped_dsh import (
+    SHIPPED_DSH_PROVIDER_SPECS,
+    ShippedDshProviderSpec,
+)
+
+
+class HostRequestError(RuntimeError):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass
+class DescriptorHostState:
+    spec: ShippedDshProviderSpec
+    profile: dict[str, Any] | None = None
+    descriptor: DshAgentProviderDescriptor | None = None
+    state: str = "ready"
+
+    def handshake(self, params: dict[str, Any]) -> dict[str, Any]:
+        projection = self._profile(params)
+        bundles = projection.get("bundles")
+        if not isinstance(bundles, list) or self.spec.package_name not in bundles:
+            raise HostRequestError(
+                self.spec.error_code("bundle_inactive"),
+                f"{self.spec.display_name} Bundle is not active in the selected DSH Profile",
+            )
+        if self.profile is not None and (
+            projection.get("configDigest") != self.profile.get("configDigest")
+        ):
+            raise HostRequestError(
+                self.spec.error_code("profile_changed"),
+                "host cannot cross a DSH Profile fence",
+            )
+        self.profile = projection
+        self.descriptor = DshAgentProviderDescriptor.model_validate(
+            {
+                "providerId": self.spec.provider_id,
+                "providerVersion": self.spec.version,
+                "displayName": self.spec.display_name,
+                "pluginName": self.spec.package_name,
+                "profile": projection.get("profile"),
+                "profileDigest": projection.get("configDigest"),
+                "runtimeProtocols": ["agentkit.runtime/v1"],
+            }
+        )
+        return {
+            "protocolVersion": DSH_AGENT_PROVIDER_HOST_PROTOCOL,
+            "methods": sorted(DSH_AGENT_PROVIDER_HOST_METHODS),
+            "hostVersion": self.spec.version,
+        }
+
+    def describe(self, params: dict[str, Any]) -> dict[str, Any]:
+        descriptor = self._require_ready_descriptor()
+        if self._profile(params).get("configDigest") != descriptor.profile_digest:
+            raise HostRequestError(
+                self.spec.error_code("profile_mismatch"),
+                "descriptor crossed a DSH Profile fence",
+            )
+        return descriptor.model_dump(by_alias=True, mode="json")
+
+    def preflight(self, params: dict[str, Any]) -> dict[str, Any]:
+        descriptor = self._require_ready_descriptor()
+        self._check_fences(params)
+        return {
+            "ready": self.state == "ready",
+            "descriptorDigest": descriptor.descriptor_digest,
+            "profileDigest": descriptor.profile_digest,
+        }
+
+    def inventory(self, params: dict[str, Any]) -> dict[str, Any]:
+        descriptor = self._require_descriptor()
+        self._check_fences(params, profile_optional=True)
+        return {
+            "providerId": descriptor.provider_id,
+            "providerVersion": descriptor.provider_version,
+            "profile": descriptor.profile,
+            "profileDigest": descriptor.profile_digest,
+            "descriptorDigest": descriptor.descriptor_digest,
+            "state": self.state,
+            "activationCount": 0,
+        }
+
+    def health(self, params: dict[str, Any]) -> dict[str, Any]:
+        if params.get("activationId"):
+            return {"healthy": False}
+        return {"healthy": self.state == "ready"}
+
+    def drain(self, params: dict[str, Any]) -> dict[str, Any]:
+        if params.get("scope") != "provider":
+            raise self._execution_bridge_required()
+        self.state = "draining"
+        return {"ok": True}
+
+    def dispose(self, params: dict[str, Any]) -> dict[str, Any]:
+        if params.get("scope") != "host":
+            raise self._execution_bridge_required()
+        self.state = "disposed"
+        return {"ok": True}
+
+    def dispatch(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        handler = getattr(self, method, None)
+        if method in {
+            "handshake",
+            "describe",
+            "preflight",
+            "inventory",
+            "health",
+            "drain",
+            "dispose",
+        } and callable(handler):
+            return handler(params)
+        raise self._execution_bridge_required()
+
+    def _profile(self, params: dict[str, Any]) -> dict[str, Any]:
+        value = params.get("profile")
+        if not isinstance(value, dict):
+            raise HostRequestError(
+                self.spec.error_code("profile_invalid"),
+                "request requires a DSH Profile projection",
+            )
+        return value
+
+    def _require_descriptor(self) -> DshAgentProviderDescriptor:
+        if self.descriptor is None:
+            raise HostRequestError(
+                self.spec.error_code("handshake_required"),
+                "DSH Profile handshake is incomplete",
+            )
+        return self.descriptor
+
+    def _require_ready_descriptor(self) -> DshAgentProviderDescriptor:
+        descriptor = self._require_descriptor()
+        if self.state != "ready":
+            raise HostRequestError(
+                self.spec.error_code("provider_unavailable"),
+                f"{self.spec.display_name} DSH provider is not ready",
+            )
+        return descriptor
+
+    def _check_fences(self, params: dict[str, Any], *, profile_optional: bool = False) -> None:
+        descriptor = self._require_descriptor()
+        if not profile_optional and params.get("profileDigest") != descriptor.profile_digest:
+            raise HostRequestError(
+                self.spec.error_code("profile_mismatch"),
+                "request crossed a DSH Profile fence",
+            )
+        if params.get("descriptorDigest") != descriptor.descriptor_digest:
+            raise HostRequestError(
+                self.spec.error_code("descriptor_mismatch"),
+                "request crossed a descriptor fence",
+            )
+
+    def _execution_bridge_required(self) -> HostRequestError:
+        return HostRequestError(
+            self.spec.bridge_required_code,
+            self.spec.bridge_required_message,
+        )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if len(arguments) != 1 or arguments[0] not in SHIPPED_DSH_PROVIDER_SPECS:
+        return 2
+    spec = SHIPPED_DSH_PROVIDER_SPECS[arguments[0]]
+    state = DescriptorHostState(spec)
+    for line in sys.stdin:
+        request: dict[str, Any] | None = None
+        try:
+            value = json.loads(line)
+            if not isinstance(value, dict):
+                raise HostRequestError(
+                    spec.error_code("request_invalid"), "request must be an object"
+                )
+            request = value
+            request_id = request.get("id")
+            method = request.get("method")
+            params = request.get("params") or {}
+            if (
+                not isinstance(request_id, str)
+                or method not in DSH_AGENT_PROVIDER_HOST_METHODS
+                or not isinstance(params, dict)
+            ):
+                raise HostRequestError(
+                    spec.error_code("request_invalid"), "request envelope is invalid"
+                )
+            response = {"id": request_id, "result": state.dispatch(str(method), params)}
+        except Exception as error:  # protocol boundary must always answer
+            response = {
+                "id": request.get("id") if isinstance(request, dict) else "unknown",
+                "error": {
+                    "code": getattr(error, "code", spec.error_code("internal_error")),
+                    "message": str(error),
+                },
+            }
+        sys.stdout.write(json.dumps(response, separators=(",", ":")) + "\n")
+        sys.stdout.flush()
+        if state.state == "disposed":
+            break
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - subprocess entrypoint
+    raise SystemExit(main())
+
+
+__all__ = ["DescriptorHostState", "HostRequestError", "main"]

ksadk/plugins/providers/dsh_mcp.py

@@ -0,0 +1,467 @@
+"""PluginHost adapter for the ephemeral DSH Profile MCP lease.
+
+The immutable Bundle records only the DSH Profile identity and capability
+digests.  The loopback URL and bearer credential are obtained from Studio's
+profile-level lifecycle service after PluginHost activation and are never
+serialized into the Agent spec, composition, or plugin lock.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from ksadk.harness.config import McpToolSpec
+from ksadk.plugins.bundle import ResolvedPluginBundle
+from ksadk.plugins.contracts import CompositionProfile, PluginManifest
+from ksadk.plugins.dsh_toolchain import DSH_PACKAGE_SPEC
+from ksadk.plugins.host import PluginHostError
+from ksadk.plugins.providers.dsh import DSH_HOST_USER_PERMISSION
+from ksadk.plugins.providers.dsh_capabilities import (
+    DshMcpConnectorLease,
+    DshProfileCapabilityDescriptor,
+    load_dsh_capability_bundle,
+)
+
+DSH_PROFILE_MCP_PLUGIN_ID = "io.ksadk.mcp.dsh-profile"
+DSH_PROFILE_MCP_PLUGIN_VERSION = "1.0.0"
+DSH_PROFILE_TOOL_PERMISSION = DSH_HOST_USER_PERMISSION
+_PLUGIN_REF = f"plugin://{DSH_PROFILE_MCP_PLUGIN_ID}@{DSH_PROFILE_MCP_PLUGIN_VERSION}"
+_MODEL_TOOL_NAME = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+
+def dsh_harness_tool_alias(name: str, prefix: str | None = None) -> str:
+    """Return a deterministic OpenAI-compatible alias for one DSH tool."""
+
+    normalized_prefix = (prefix or "").strip()
+    candidate = name
+    changed = not bool(_MODEL_TOOL_NAME.fullmatch(candidate))
+    if changed:
+        stem = re.sub(r"[^A-Za-z0-9_-]", "_", candidate).strip("_") or "tool"
+        candidate = f"{stem[:55]}_{hashlib.sha256(name.encode()).hexdigest()[:8]}"
+    if normalized_prefix:
+        candidate = f"{normalized_prefix}_{candidate}"
+    if len(candidate) > 64:
+        suffix = hashlib.sha256(name.encode()).hexdigest()[:8]
+        candidate = f"{candidate[:55]}_{suffix}"
+    if not _MODEL_TOOL_NAME.fullmatch(candidate):
+        raise PluginHostError(
+            "dsh_mcp_tool_alias_invalid",
+            "DSH tool alias is not compatible with the Harness model protocol",
+        )
+    return candidate
+
+
+def dsh_profile_mcp_manifest() -> PluginManifest:
+    """Return the deterministic platform adapter manifest."""
+
+    manifest_digest = load_dsh_capability_bundle().digest
+    return cast(
+        PluginManifest,
+        PluginManifest.model_validate(
+            {
+                "metadata": {
+                    "id": DSH_PROFILE_MCP_PLUGIN_ID,
+                    "version": DSH_PROFILE_MCP_PLUGIN_VERSION,
+                },
+                "spec": {
+                    "domain": "ksadk-platform",
+                    "runtime": "python",
+                    "entrypoint": "ksadk.plugins.providers.dsh_mcp:DshProfileMCPFactory",
+                    "provides": [
+                        {
+                            "definition": "mcp.connector/v1",
+                            "slot": "mcp.dsh-profile",
+                            "mode": "multiple",
+                        }
+                    ],
+                    "permissions": ["network:mcp", DSH_PROFILE_TOOL_PERMISSION],
+                    "isolation": "sidecar",
+                    "compatibility": {
+                        "kernelApi": ">=1,<2",
+                        "runtimeProtocols": ["agentkit.runtime/v1", "2025-06-18"],
+                        "python": ">=3.10,<3.15",
+                    },
+                    "healthContract": "plugin.health/v1",
+                    "provenance": {
+                        "source": "runtime-native",
+                        "digest": manifest_digest,
+                        "license": "Apache-2.0",
+                        "upstream": {
+                            "ecosystem": "dsh",
+                            "type": "runtime-native",
+                            "requested": DSH_PACKAGE_SPEC,
+                            "resolved": DSH_PACKAGE_SPEC,
+                        },
+                        "components": [
+                            {
+                                "id": "dsh-profile-mcp",
+                                "kind": "mcp",
+                                "digest": manifest_digest,
+                            }
+                        ],
+                    },
+                },
+            }
+        ),
+    )
+
+
+def _mapping(value: Any, *, code: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise PluginHostError(code, "expected an object")
+    return value
+
+
+def _required(value: Mapping[str, Any], field: str, *, code: str) -> str:
+    item = value.get(field)
+    if not isinstance(item, str) or not item.strip():
+        raise PluginHostError(code, f"{field} must be a non-empty string")
+    return item.strip()
+
+
+def _optional(value: Any, *, code: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise PluginHostError(code, "optional string configuration is invalid")
+    return value.strip() or None
+
+
+def _string_list(value: Any, *, code: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise PluginHostError(code, "toolFilter must be an array")
+    result: list[str] = []
+    for item in value:
+        if not isinstance(item, str) or not item.strip():
+            raise PluginHostError(code, "toolFilter entries must be non-empty strings")
+        result.append(item.strip())
+    if len(result) != len(set(result)):
+        raise PluginHostError(code, "toolFilter entries must be unique")
+    return tuple(result)
+
+
+def _profile_config(profile: CompositionProfile) -> Mapping[str, Any]:
+    matches = [item for item in profile.capabilities if item.ref == _PLUGIN_REF]
+    if len(matches) != 1:
+        raise PluginHostError(
+            "dsh_mcp_binding_missing",
+            "DSH Profile MCP requires one exact composition capability",
+        )
+    return cast(Mapping[str, Any], matches[0].config)
+
+
+def _resource_entry(config: Mapping[str, Any]) -> Mapping[str, Any]:
+    resources = config.get("resources")
+    if (
+        not isinstance(resources, Sequence)
+        or isinstance(resources, (str, bytes))
+        or len(resources) != 1
+    ):
+        raise PluginHostError(
+            "dsh_mcp_config_invalid",
+            "one DSH Profile MCP resource must be selected",
+        )
+    entry = _mapping(resources[0], code="dsh_mcp_config_invalid")
+    if entry.get("kind") != "mcp":
+        raise PluginHostError("dsh_mcp_config_invalid", "resource kind must be mcp")
+    for field in ("resourceId", "name", "version", "digest"):
+        _required(entry, field, code="dsh_mcp_config_invalid")
+    return entry
+
+
+class DshProfileMCPRuntime:
+    """Resolve a locked DSH descriptor into one process-scoped MCP spec."""
+
+    def __init__(self, *, service: Any, profile: CompositionProfile) -> None:
+        self._service = service
+        self._entry = _resource_entry(_profile_config(profile))
+        self._descriptor: DshProfileCapabilityDescriptor | None = None
+        self._lease: DshMcpConnectorLease | None = None
+        self._issued_scopes: dict[str, DshMcpConnectorLease] = {}
+        self._revocation_tasks: dict[str, asyncio.Task[None]] = {}
+        self._ready = False
+        self._disposed = False
+
+    async def start(self) -> None:
+        if self._disposed:
+            raise PluginHostError("dsh_mcp_disposed", "DSH MCP runtime is disposed")
+        await self._refresh_lease()
+        self._ready = True
+
+    async def _refresh_lease(self) -> None:
+        try:
+            snapshot = await self._service.runtime_snapshot()
+            descriptor = snapshot.descriptor
+            lease = snapshot.lease
+        except PluginHostError:
+            raise
+        except Exception as error:  # noqa: BLE001 - lifecycle service boundary
+            raise PluginHostError(
+                "dsh_mcp_lease_unavailable", "DSH Profile MCP lease is unavailable"
+            ) from error
+        self._validate_descriptor(descriptor, lease)
+        self._descriptor = descriptor
+        self._lease = lease
+
+    async def health(self) -> bool:
+        return self._ready and not self._disposed and self._lease is not None
+
+    async def drain(self) -> None:
+        self._ready = False
+
+    async def dispose(self) -> None:
+        self._ready = False
+        self._disposed = True
+        scopes = tuple(self._issued_scopes)
+        first_error: BaseException | None = None
+        for token in scopes:
+            try:
+                await self._revoke_tracked_scope(token)
+            except BaseException as error:  # revocation must continue
+                if first_error is None:
+                    first_error = error
+        self._descriptor = None
+        self._lease = None
+        if first_error is not None:
+            raise first_error
+
+    async def harness_mcp_specs(self, bundle: ResolvedPluginBundle) -> tuple[McpToolSpec, ...]:
+        if not self._ready or self._disposed:
+            raise PluginHostError("dsh_mcp_unavailable", "DSH Profile MCP is not ready")
+        # A supervised DSH sidecar may have restarted since this PluginHost
+        # graph was staged.  Resolve and fence the lease at every new Agent
+        # activation so stale ports or credentials never escape into a client.
+        await self._refresh_lease()
+        if self._descriptor is None or self._lease is None:  # pragma: no cover - invariant
+            raise PluginHostError("dsh_mcp_unavailable", "DSH Profile MCP is not ready")
+        resolved = self._resolved_resource(bundle)
+        self._validate_resolved_resource(resolved)
+        materializer = _mapping(self._entry.get("materializer"), code="dsh_mcp_config_invalid")
+        tool_filter = _string_list(
+            materializer.get("toolFilter"), code="dsh_mcp_tool_filter_invalid"
+        )
+        known_tools = {tool.name for tool in self._descriptor.tools}
+        unknown = sorted(set(tool_filter) - known_tools)
+        if unknown:
+            raise PluginHostError(
+                "dsh_mcp_tool_filter_invalid",
+                f"DSH toolFilter contains unknown tools: {', '.join(unknown)}",
+            )
+        prefix = _optional(
+            materializer.get("toolNamePrefix"),
+            code="dsh_mcp_config_invalid",
+        )
+        aliases = {dsh_harness_tool_alias(name, prefix): name for name in tool_filter}
+        if len(aliases) != len(tool_filter):
+            raise PluginHostError(
+                "dsh_mcp_tool_alias_collision",
+                "selected DSH tools produce duplicate Harness aliases",
+            )
+        resource_name = _required(resolved, "name", code="dsh_mcp_resource_invalid")
+        token = self._lease.bearer_token_for_runtime(aliases)
+        self._issued_scopes[token] = self._lease
+        return (
+            McpToolSpec(
+                name=resource_name,
+                url=self._lease.endpoint,
+                api_key=token,
+                tool_filter=tuple(aliases),
+                tool_name_prefix=None,
+            ),
+        )
+
+    async def activation_mcp_specs(
+        self,
+        bundle: ResolvedPluginBundle,
+        *,
+        activation_key: str,
+    ) -> tuple[McpToolSpec, ...]:
+        """Project the same lease through the provider-neutral activation ABI."""
+
+        del activation_key  # compatibility contexts predating PluginHost activation IDs
+        return await self.harness_mcp_specs(bundle)
+
+    async def release_activation_mcp_specs(
+        self,
+        activation_key: str,
+        specs: Sequence[McpToolSpec],
+    ) -> None:
+        del activation_key
+        await self.release_harness_mcp_specs(specs)
+
+    async def release_harness_mcp_specs(
+        self,
+        specs: Sequence[McpToolSpec],
+    ) -> None:
+        """Revoke every activation-scoped credential projected in ``specs``."""
+
+        first_error: BaseException | None = None
+        for spec in specs:
+            token = spec.api_key
+            if token is None:
+                continue
+            if token not in self._issued_scopes:
+                continue
+            try:
+                await self._revoke_tracked_scope(token)
+            except BaseException as error:  # revocation must continue
+                if first_error is None:
+                    first_error = error
+        if first_error is not None:
+            raise first_error
+
+    async def _revoke_tracked_scope(self, token: str) -> None:
+        lease = self._issued_scopes.get(token)
+        if lease is None:
+            return
+        task = self._revocation_tasks.get(token)
+        if task is None:
+            task = asyncio.create_task(self._revoke_scope(lease, token))
+            self._revocation_tasks[token] = task
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            # The owned task keeps the security action alive. The token stays
+            # tracked until revocation succeeds or a later dispose retries it.
+            raise
+        finally:
+            if task.done():
+                self._revocation_tasks.pop(token, None)
+        task.result()
+        self._issued_scopes.pop(token, None)
+
+    async def _revoke_scope(self, lease: DshMcpConnectorLease, token: str) -> None:
+        revoke = getattr(self._service, "revoke_runtime_token", None)
+        if not callable(revoke):
+            raise PluginHostError(
+                "dsh_mcp_revocation_unavailable",
+                "DSH capability lifecycle service cannot revoke runtime credentials",
+            )
+        await revoke(lease, token)
+
+    def _validate_descriptor(
+        self,
+        descriptor: DshProfileCapabilityDescriptor,
+        lease: DshMcpConnectorLease,
+    ) -> None:
+        materializer = _mapping(self._entry.get("materializer"), code="dsh_mcp_config_invalid")
+        expected = {
+            "profile": descriptor.profile,
+            "profileDigest": descriptor.profile_digest,
+            "descriptorDigest": descriptor.descriptor_digest,
+            "inventoryDigest": descriptor.inventory_digest,
+        }
+        if any(materializer.get(key) != value for key, value in expected.items()):
+            raise PluginHostError(
+                "dsh_mcp_descriptor_mismatch",
+                "DSH Profile changed after this Agent Build was compiled",
+            )
+        if (
+            _required(self._entry, "version", code="dsh_mcp_config_invalid")
+            != descriptor.dsh_version
+        ):
+            raise PluginHostError(
+                "dsh_mcp_descriptor_mismatch", "DSH runtime version changed after build"
+            )
+        if (
+            lease.profile != descriptor.profile
+            or lease.profile_digest != descriptor.profile_digest
+            or lease.descriptor_digest != descriptor.descriptor_digest
+        ):
+            raise PluginHostError(
+                "dsh_mcp_lease_mismatch", "DSH MCP lease does not match the locked descriptor"
+            )
+
+    def _resolved_resource(self, bundle: ResolvedPluginBundle) -> Mapping[str, Any]:
+        capabilities = _mapping(
+            bundle.resolved_agent_spec.get("capabilities"),
+            code="dsh_mcp_bundle_invalid",
+        )
+        raw = capabilities.get("mcpServers")
+        if not isinstance(raw, Sequence) or isinstance(raw, (str, bytes)):
+            raise PluginHostError("dsh_mcp_bundle_invalid", "mcpServers is missing")
+        matches = [
+            _mapping(item, code="dsh_mcp_bundle_invalid")
+            for item in raw
+            if isinstance(item, Mapping)
+            and item.get("name") == self._entry.get("name")
+            and item.get("version") == self._entry.get("version")
+            and item.get("digest") == self._entry.get("digest")
+        ]
+        if len(matches) != 1:
+            raise PluginHostError(
+                "dsh_mcp_resource_mismatch",
+                "locked DSH MCP resource is absent from the resolved Agent spec",
+            )
+        return matches[0]
+
+    def _validate_resolved_resource(self, resolved: Mapping[str, Any]) -> None:
+        assert self._descriptor is not None
+        expected = {
+            "transport": "http",
+            "materialization": "dsh-profile",
+            "profile": self._descriptor.profile,
+            "profileDigest": self._descriptor.profile_digest,
+            "descriptorDigest": self._descriptor.descriptor_digest,
+            "inventoryDigest": self._descriptor.inventory_digest,
+        }
+        if any(resolved.get(key) != value for key, value in expected.items()):
+            raise PluginHostError(
+                "dsh_mcp_resource_mismatch", "resolved DSH MCP metadata changed after build"
+            )
+        arguments = resolved.get("args")
+        environment = resolved.get("envRefs")
+        if (
+            resolved.get("endpointUrl") is not None
+            or resolved.get("command") is not None
+            or arguments not in (None, (), [])
+            or (environment is not None and (not isinstance(environment, Mapping) or environment))
+        ):
+            raise PluginHostError(
+                "dsh_mcp_secret_persisted",
+                "resolved DSH MCP must not contain runtime connection material",
+            )
+
+
+class DshProfileMCPFactory:
+    """Stage the platform adapter against Studio's shared Profile service."""
+
+    def __init__(self, service: Any) -> None:
+        self._service = service
+
+    async def stage(
+        self,
+        manifest: PluginManifest,
+        *,
+        profile: CompositionProfile,
+        services: Mapping[str, Any],
+    ) -> DshProfileMCPRuntime:
+        del services
+        service = self._service
+        if (
+            manifest.metadata.id != DSH_PROFILE_MCP_PLUGIN_ID
+            or manifest.metadata.version != DSH_PROFILE_MCP_PLUGIN_VERSION
+        ):
+            raise PluginHostError("dsh_mcp_manifest_mismatch", "DSH MCP manifest mismatch")
+        if service is None:
+            raise PluginHostError(
+                "dsh_mcp_service_unavailable", "DSH capability lifecycle service is unavailable"
+            )
+        return DshProfileMCPRuntime(service=service, profile=profile)
+
+
+__all__ = [
+    "DSH_PROFILE_MCP_PLUGIN_ID",
+    "DSH_PROFILE_MCP_PLUGIN_VERSION",
+    "DSH_PROFILE_TOOL_PERMISSION",
+    "DshProfileMCPFactory",
+    "DshProfileMCPRuntime",
+    "dsh_profile_mcp_manifest",
+    "dsh_harness_tool_alias",
+]