mai-bot/src/plugin_runtime/host/supervisor.py

from dataclasses import dataclass, field
from pathlib import Path
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple

import asyncio
import contextlib
import json
import os
import sys

from src.common.logger import get_logger
from src.config.config import config_manager, global_config
from src.platform_io import DriverKind, InboundMessageEnvelope, RouteBinding, RouteKey, get_platform_io_manager
from src.platform_io.drivers import PluginPlatformDriver
from src.platform_io.route_key_factory import RouteKeyFactory
from src.plugin_runtime import (
    ENV_EXTERNAL_PLUGIN_IDS,
    ENV_GLOBAL_CONFIG_SNAPSHOT,
    ENV_HOST_VERSION,
    ENV_IPC_ADDRESS,
    ENV_PLUGIN_DIRS,
    ENV_SESSION_TOKEN,
)
from src.plugin_runtime.protocol.envelope import (
    BootstrapPluginPayload,
    ConfigReloadScope,
    ConfigUpdatedPayload,
    Envelope,
    HealthPayload,
    InspectPluginConfigPayload,
    InspectPluginConfigResultPayload,
    MessageGatewayStateUpdatePayload,
    MessageGatewayStateUpdateResultPayload,
    PROTOCOL_VERSION,
    ReceiveExternalMessageResultPayload,
    RegisterPluginPayload,
    ReloadPluginResultPayload,
    ReloadPluginsPayload,
    ReloadPluginsResultPayload,
    RouteMessagePayload,
    RunnerReadyPayload,
    ShutdownPayload,
    UnregisterPluginPayload,
    ValidatePluginConfigPayload,
    ValidatePluginConfigResultPayload,
)
from src.plugin_runtime.protocol.codec import MsgPackCodec
from src.plugin_runtime.protocol.errors import ErrorCode, RPCError
from src.plugin_runtime.transport.factory import create_transport_server

from .authorization import AuthorizationManager
from .api_registry import APIRegistry
from .capability_service import CapabilityService
from .component_registry import ComponentRegistry
from .event_dispatcher import EventDispatcher
from .hook_dispatcher import HookDispatchResult, HookDispatcher
from .hook_spec_registry import HookSpecRegistry
from .logger_bridge import RunnerLogBridge
from .message_gateway import MessageGateway
from .rpc_server import RPCServer

if TYPE_CHECKING:
    from src.chat.message_receive.message import SessionMessage

logger = get_logger("plugin_runtime.host.runner_manager")


@dataclass(slots=True)
class _MessageGatewayRuntimeState:
    """保存消息网关当前的运行时连接状态。"""

    ready: bool = False
    platform: Optional[str] = None
    account_id: Optional[str] = None
    scope: Optional[str] = None
    metadata: Dict[str, Any] = field(default_factory=dict)


class PluginRunnerSupervisor:
    """插件 Runner 监督器。

    负责 Host 侧与单个 Runner 子进程之间的生命周期、内部 RPC、
    健康检查和插件级重载协调。
    """

    def __init__(
        self,
        plugin_dirs: Optional[List[Path]] = None,
        group_name: str = "third_party",
        hook_spec_registry: Optional[HookSpecRegistry] = None,
        socket_path: Optional[str] = None,
        health_check_interval_sec: Optional[float] = None,
        max_restart_attempts: Optional[int] = None,
        runner_spawn_timeout_sec: Optional[float] = None,
    ) -> None:
        """初始化 Supervisor。

        Args:
            plugin_dirs: 由当前 Runner 负责加载的插件目录列表。
            group_name: 当前 Supervisor 所属运行时分组名称。
            hook_spec_registry: 可选的共享 Hook 规格注册中心。
            socket_path: 自定义 IPC 地址；留空时由传输层自动生成。
            health_check_interval_sec: 健康检查间隔，单位秒。
            max_restart_attempts: 自动重启 Runner 的最大次数。
            runner_spawn_timeout_sec: 等待 Runner 建连并就绪的超时时间，单位秒。
        """
        runtime_config = global_config.plugin_runtime
        self._group_name: str = str(group_name or "third_party").strip() or "third_party"
        self._plugin_dirs: List[Path] = plugin_dirs or []
        self._health_interval: float = health_check_interval_sec or runtime_config.health_check_interval_sec or 30.0
        self._runner_spawn_timeout: float = runner_spawn_timeout_sec or runtime_config.runner_spawn_timeout_sec or 30.0
        self._max_restart_attempts: int = max_restart_attempts or runtime_config.max_restart_attempts or 3

        self._transport = create_transport_server(socket_path=socket_path)
        self._authorization = AuthorizationManager()
        self._capability_service = CapabilityService(self._authorization)
        self._api_registry = APIRegistry()
        self._component_registry = ComponentRegistry(hook_spec_registry=hook_spec_registry)
        self._event_dispatcher = EventDispatcher(self._component_registry)
        self._hook_dispatcher = HookDispatcher(
            lambda: [self],
            hook_spec_registry=hook_spec_registry,
        )
        self._message_gateway = MessageGateway(self._component_registry)
        self._log_bridge = RunnerLogBridge()

        codec = MsgPackCodec()
        self._rpc_server = RPCServer(transport=self._transport, codec=codec)

        self._runner_process: Optional[asyncio.subprocess.Process] = None
        self._registered_plugins: Dict[str, RegisterPluginPayload] = {}
        self._message_gateway_states: Dict[str, Dict[str, _MessageGatewayRuntimeState]] = {}
        self._external_available_plugins: Dict[str, str] = {}
        self._runner_ready_events: asyncio.Event = asyncio.Event()
        self._runner_ready_payloads: RunnerReadyPayload = RunnerReadyPayload()
        self._health_task: Optional[asyncio.Task[None]] = None
        self._stderr_drain_task: Optional[asyncio.Task[None]] = None
        self._restart_count: int = 0
        self._running: bool = False

        self._register_internal_methods()

    @property
    def authorization_manager(self) -> AuthorizationManager:
        """返回授权管理器。"""
        return self._authorization

    @property
    def group_name(self) -> str:
        """返回当前 Supervisor 的运行时分组名称。"""

        return self._group_name

    @property
    def capability_service(self) -> CapabilityService:
        """返回能力服务。"""
        return self._capability_service

    @property
    def api_registry(self) -> APIRegistry:
        """返回 API 专用注册表。"""
        return self._api_registry

    @property
    def component_registry(self) -> ComponentRegistry:
        """返回组件注册表。"""
        return self._component_registry

    @property
    def event_dispatcher(self) -> EventDispatcher:
        """返回事件分发器。"""
        return self._event_dispatcher

    @property
    def hook_dispatcher(self) -> HookDispatcher:
        """返回 Hook 分发器。"""
        return self._hook_dispatcher

    @property
    def message_gateway(self) -> MessageGateway:
        """返回消息网关。"""
        return self._message_gateway

    @property
    def rpc_server(self) -> RPCServer:
        """返回底层 RPC 服务端。"""
        return self._rpc_server

    def set_external_available_plugins(self, plugin_versions: Dict[str, str]) -> None:
        """设置当前 Runner 启动/重载时可视为已满足的外部依赖版本映射。

        Args:
            plugin_versions: 外部插件版本映射，键为插件 ID，值为插件版本。
        """
        self._external_available_plugins = {
            str(plugin_id or "").strip(): str(plugin_version or "").strip()
            for plugin_id, plugin_version in plugin_versions.items()
            if str(plugin_id or "").strip() and str(plugin_version or "").strip()
        }

    def get_loaded_plugin_ids(self) -> List[str]:
        """返回当前 Supervisor 已注册的插件 ID 列表。"""

        return sorted(self._registered_plugins.keys())

    def get_loaded_plugin_versions(self) -> Dict[str, str]:
        """返回当前 Supervisor 已注册插件的版本映射。

        Returns:
            Dict[str, str]: 已注册插件版本映射，键为插件 ID，值为插件版本。
        """
        return {plugin_id: registration.plugin_version for plugin_id, registration in self._registered_plugins.items()}

    @staticmethod
    def _normalize_reload_plugin_ids(plugin_ids: Optional[List[str] | str]) -> List[str]:
        """规范化批量重载入参。

        Args:
            plugin_ids: 原始插件 ID 列表或单个插件 ID。

        Returns:
            List[str]: 去重且去空白后的插件 ID 列表。
        """

        raw_plugin_ids: List[str]
        if plugin_ids is None:
            raw_plugin_ids = []
        elif isinstance(plugin_ids, str):
            raw_plugin_ids = [plugin_ids]
        else:
            raw_plugin_ids = list(plugin_ids)

        normalized_plugin_ids: List[str] = []
        seen_plugin_ids: set[str] = set()
        for plugin_id in raw_plugin_ids:
            normalized_plugin_id = str(plugin_id or "").strip()
            if not normalized_plugin_id or normalized_plugin_id in seen_plugin_ids:
                continue
            seen_plugin_ids.add(normalized_plugin_id)
            normalized_plugin_ids.append(normalized_plugin_id)
        return normalized_plugin_ids

    async def dispatch_event(
        self,
        event_type: str,
        message: Optional["SessionMessage"] = None,
        extra_args: Optional[Dict[str, Any]] = None,
    ) -> Tuple[bool, Optional["SessionMessage"]]:
        """分发事件到已注册的事件处理器。

        Args:
            event_type: 事件类型。
            message: 可选的消息对象。
            extra_args: 附加参数。

        Returns:
            Tuple[bool, Optional[SessionMessage]]: 是否继续处理，以及插件可能修改后的消息。
        """
        return await self._event_dispatcher.dispatch_event(event_type, self, message, extra_args)

    async def invoke_hook(self, hook_name: str, **kwargs: Any) -> HookDispatchResult:
        """在当前 Supervisor 内触发一次命名 Hook 调用。

        Args:
            hook_name: 本次触发的 Hook 名称。
            **kwargs: 传递给 Hook 处理器的关键字参数。

        Returns:
            HookDispatchResult: 聚合后的 Hook 调用结果。
        """

        return await self._hook_dispatcher.invoke_hook(hook_name, **kwargs)

    async def send_message_to_external(
        self,
        internal_message: "SessionMessage",
        *,
        enabled_only: bool = True,
        save_to_db: bool = True,
    ) -> bool:
        """通过插件消息网关发送外部消息。

        Args:
            internal_message: 系统内部消息对象。
            enabled_only: 是否仅使用启用的网关组件。
            save_to_db: 发送成功后是否写入数据库。

        Returns:
            bool: 是否发送成功。
        """
        return await self._message_gateway.send_message_to_external(
            internal_message,
            self,
            enabled_only=enabled_only,
            save_to_db=save_to_db,
        )

    async def start(self) -> None:
        """启动 Supervisor。"""
        if self._running:
            logger.warning("PluginRunnerSupervisor 已在运行，跳过重复启动")
            return

        self._running = True
        self._restart_count = 0
        self._clear_runner_state()

        try:
            await self._rpc_server.start()
            await self._spawn_runner()

            try:
                await self._wait_for_runner_connection(timeout_sec=self._runner_spawn_timeout)
                await self._wait_for_runner_ready(timeout_sec=self._runner_spawn_timeout)
            except TimeoutError:
                if not self._rpc_server.is_connected:
                    logger.warning("Runner 未在限定时间内完成连接，后续操作可能失败")
                else:
                    logger.warning("Runner 未在限定时间内完成初始化，后续操作可能失败")
        except Exception:
            await self._shutdown_runner(reason="startup_failed")
            await self._rpc_server.stop()
            self._clear_runner_state()
            self._running = False
            raise

        self._health_task = asyncio.create_task(self._health_check_loop(), name="PluginRunnerSupervisor.health")
        logger.info("PluginRunnerSupervisor 已启动")

    async def stop(self) -> None:
        """停止 Supervisor。"""
        if not self._running:
            return

        self._running = False

        if self._health_task is not None:
            self._health_task.cancel()
            with contextlib.suppress(asyncio.CancelledError):
                await self._health_task
            self._health_task = None

        await self._event_dispatcher.stop()
        await self._hook_dispatcher.stop()
        await self._shutdown_runner(reason="host_stop")
        await self._rpc_server.stop()
        self._clear_runner_state()

        logger.info("PluginRunnerSupervisor 已停止")

    async def invoke_plugin(
        self,
        method: str,
        plugin_id: str,
        component_name: str,
        args: Optional[Dict[str, Any]] = None,
        timeout_ms: int = 30000,
    ) -> Envelope:
        """调用 Runner 内的插件组件。

        Args:
            method: RPC 方法名。
            plugin_id: 目标插件 ID。
            component_name: 组件名。
            args: 调用参数。
            timeout_ms: RPC 超时时间，单位毫秒。

        Returns:
            Envelope: RPC 响应信封。
        """
        return await self._rpc_server.send_request(
            method,
            plugin_id,
            {"component_name": component_name, "args": args or {}},
            timeout_ms,
        )

    async def invoke_message_gateway(
        self,
        plugin_id: str,
        component_name: str,
        args: Optional[Dict[str, Any]] = None,
        timeout_ms: int = 30000,
    ) -> Envelope:
        """调用插件声明的消息网关方法。

        Args:
            plugin_id: 目标插件 ID。
            component_name: 消息网关组件名称。
            args: 传递给网关方法的关键字参数。
            timeout_ms: RPC 超时时间，单位毫秒。

        Returns:
            Envelope: Runner 返回的响应信封。
        """

        return await self.invoke_plugin(
            method="plugin.invoke_message_gateway",
            plugin_id=plugin_id,
            component_name=component_name,
            args=args,
            timeout_ms=timeout_ms,
        )

    async def invoke_api(
        self,
        plugin_id: str,
        component_name: str,
        args: Optional[Dict[str, Any]] = None,
        timeout_ms: int = 30000,
    ) -> Envelope:
        """调用插件声明的 API 方法。

        Args:
            plugin_id: 目标插件 ID。
            component_name: API 组件名称。
            args: 传递给 API 方法的关键字参数。
            timeout_ms: RPC 超时时间，单位毫秒。

        Returns:
            Envelope: Runner 返回的响应信封。
        """

        return await self.invoke_plugin(
            method="plugin.invoke_api",
            plugin_id=plugin_id,
            component_name=component_name,
            args=args,
            timeout_ms=timeout_ms,
        )

    async def reload_plugin(
        self,
        plugin_id: str,
        reason: str = "manual",
        external_available_plugins: Optional[Dict[str, str]] = None,
    ) -> bool:
        """按插件 ID 触发精确重载。

        Args:
            plugin_id: 目标插件 ID。
            reason: 重载原因。
            external_available_plugins: 视为已满足的外部依赖插件版本映射。

        Returns:
            bool: 是否重载成功。
        """
        try:
            response = await self._rpc_server.send_request(
                "plugin.reload",
                plugin_id=plugin_id,
                payload={
                    "plugin_id": plugin_id,
                    "reason": reason,
                    "external_available_plugins": external_available_plugins or self._external_available_plugins,
                },
                timeout_ms=max(int(self._runner_spawn_timeout * 1000), 10000),
            )
        except Exception as exc:
            logger.error(f"插件 {plugin_id} 重载请求失败: {exc}")
            return False

        result = ReloadPluginResultPayload.model_validate(response.payload)
        if not result.success:
            logger.warning(f"插件 {plugin_id} 重载失败: {result.failed_plugins}")
        return result.success

    async def reload_plugins(
        self,
        plugin_ids: Optional[List[str] | str] = None,
        reason: str = "manual",
        external_available_plugins: Optional[Dict[str, str]] = None,
    ) -> bool:
        """批量重载插件。

        Args:
            plugin_ids: 目标插件 ID 列表；为空时重载当前已注册的全部插件。
            reason: 重载原因。
            external_available_plugins: 视为已满足的外部依赖插件版本映射。

        Returns:
            bool: 是否全部重载成功。
        """
        ordered_plugin_ids = self._normalize_reload_plugin_ids(plugin_ids)
        if not ordered_plugin_ids:
            ordered_plugin_ids = list(self._registered_plugins.keys())
        if not ordered_plugin_ids:
            return True

        if len(ordered_plugin_ids) == 1:
            return await self.reload_plugin(
                plugin_id=ordered_plugin_ids[0],
                reason=reason,
                external_available_plugins=external_available_plugins,
            )

        try:
            response = await self._rpc_server.send_request(
                "plugin.reload_batch",
                payload=ReloadPluginsPayload(
                    plugin_ids=ordered_plugin_ids,
                    reason=reason,
                    external_available_plugins=external_available_plugins or self._external_available_plugins,
                ).model_dump(),
                timeout_ms=max(int(self._runner_spawn_timeout * 1000), 10000),
            )
        except Exception as exc:
            logger.error(f"插件批量重载请求失败: {exc}")
            return False

        result = ReloadPluginsResultPayload.model_validate(response.payload)
        if not result.success:
            logger.warning(f"插件批量重载失败: {result.failed_plugins}")
        return result.success

    async def notify_plugin_config_updated(
        self,
        plugin_id: str,
        config_data: Optional[Dict[str, Any]] = None,
        config_version: str = "",
        config_scope: str | ConfigReloadScope = "self",
    ) -> bool:
        """向 Runner 推送插件配置更新。

        Args:
            plugin_id: 目标插件 ID。
            config_data: 配置内容。
            config_version: 配置版本号。
            config_scope: 配置变更范围。

        Returns:
            bool: 请求是否成功送达并被 Runner 接受。
        """
        try:
            normalized_scope = ConfigReloadScope(config_scope)
        except ValueError:
            logger.warning(f"插件 {plugin_id} 配置更新通知失败: 非法的 config_scope={config_scope}")
            return False

        payload = ConfigUpdatedPayload(
            plugin_id=plugin_id,
            config_scope=normalized_scope,
            config_version=config_version,
            config_data=config_data or {},
        )
        try:
            response = await self._rpc_server.send_request(
                "plugin.config_updated",
                plugin_id=plugin_id,
                payload=payload.model_dump(),
                timeout_ms=10000,
            )
        except Exception as exc:
            logger.warning(f"插件 {plugin_id} 配置更新通知失败: {exc}")
            return False

        return bool(response.payload.get("acknowledged", False))

    async def validate_plugin_config(self, plugin_id: str, config_data: Dict[str, Any]) -> Dict[str, Any]:
        """请求 Runner 使用插件自身配置模型校验配置。

        Args:
            plugin_id: 目标插件 ID。
            config_data: 待校验的配置内容。

        Returns:
            Dict[str, Any]: 插件模型归一化后的配置字典。

        Raises:
            ValueError: 插件拒绝该配置或校验失败时抛出。
        """

        payload = ValidatePluginConfigPayload(config_data=config_data)
        try:
            response = await self._rpc_server.send_request(
                "plugin.validate_config",
                plugin_id=plugin_id,
                payload=payload.model_dump(),
                timeout_ms=10000,
            )
        except Exception as exc:
            raise ValueError(f"插件配置校验请求失败: {exc}") from exc

        if response.error:
            raise ValueError(str(response.error.get("message", "插件配置校验失败")))

        result = ValidatePluginConfigResultPayload.model_validate(response.payload)
        if not result.success:
            raise ValueError("插件配置校验失败")
        return dict(result.normalized_config)

    async def inspect_plugin_config(
        self,
        plugin_id: str,
        config_data: Optional[Dict[str, Any]] = None,
        *,
        use_provided_config: bool = False,
    ) -> InspectPluginConfigResultPayload:
        """请求 Runner 解析插件配置元数据。

        Args:
            plugin_id: 目标插件 ID。
            config_data: 可选的配置内容。
            use_provided_config: 是否优先使用传入配置而不是磁盘配置。

        Returns:
            InspectPluginConfigResultPayload: 插件配置解析结果。

        Raises:
            ValueError: Runner 无法解析插件或返回了错误响应时抛出。
        """

        payload = InspectPluginConfigPayload(
            config_data=config_data or {},
            use_provided_config=use_provided_config,
        )
        try:
            response = await self._rpc_server.send_request(
                "plugin.inspect_config",
                plugin_id=plugin_id,
                payload=payload.model_dump(),
                timeout_ms=10000,
            )
        except Exception as exc:
            raise ValueError(f"插件配置解析请求失败: {exc}") from exc

        if response.error:
            raise ValueError(str(response.error.get("message", "插件配置解析失败")))

        result = InspectPluginConfigResultPayload.model_validate(response.payload)
        if not result.success:
            raise ValueError("插件配置解析失败")
        return result

    def get_config_reload_subscribers(self, scope: str) -> List[str]:
        """返回订阅指定全局配置广播的插件列表。

        Args:
            scope: 配置变更范围，仅支持 ``bot`` 或 ``model``。

        Returns:
            List[str]: 已声明订阅该范围的插件 ID 列表。
        """

        return [
            plugin_id
            for plugin_id, registration in self._registered_plugins.items()
            if scope in registration.config_reload_subscriptions
        ]

    async def _wait_for_runner_connection(self, timeout_sec: float) -> None:
        """等待 Runner 建立 RPC 连接。

        Args:
            timeout_sec: 超时时间，单位秒。

        Raises:
            TimeoutError: 在超时时间内 Runner 未完成连接。
        """

        async def wait_for_connection() -> None:
            """轮询等待 RPC 连接建立。"""
            while True:
                if self._rpc_server.is_connected:
                    return

                if not self._running:
                    raise RuntimeError("Supervisor 已停止，等待 Runner 连接已取消")

                if failure_reason := self._get_runner_startup_failure_reason():
                    raise RuntimeError(f"等待 Runner 连接失败: {failure_reason}")

                await asyncio.sleep(0.1)

        try:
            await asyncio.wait_for(wait_for_connection(), timeout=timeout_sec)
            logger.info("Runner 已连接到 RPC Server")
        except asyncio.TimeoutError as exc:
            raise TimeoutError(f"等待 Runner 连接超时（{timeout_sec}s）") from exc

    async def _wait_for_runner_ready(self, timeout_sec: float = 30.0) -> RunnerReadyPayload:
        """等待 Runner 完成启动初始化。

        Args:
            timeout_sec: 超时时间，单位秒。

        Returns:
            RunnerReadyPayload: Runner 上报的就绪信息。

        Raises:
            TimeoutError: 在超时时间内 Runner 未完成初始化。
        """

        async def wait_for_ready() -> RunnerReadyPayload:
            """轮询等待 Runner 上报就绪。"""
            while True:
                if self._runner_ready_events.is_set():
                    return self._runner_ready_payloads

                if not self._running:
                    raise RuntimeError("Supervisor 已停止，等待 Runner 就绪已取消")

                if failure_reason := self._get_runner_startup_failure_reason():
                    raise RuntimeError(f"等待 Runner 就绪失败: {failure_reason}")

                if not self._rpc_server.is_connected:
                    raise RuntimeError("等待 Runner 就绪失败: Runner RPC 连接已断开")

                await asyncio.sleep(0.1)

        try:
            payload = await asyncio.wait_for(wait_for_ready(), timeout=timeout_sec)
            logger.info("Runner 已完成初始化并上报就绪")
            return payload
        except asyncio.TimeoutError as exc:
            raise TimeoutError(f"等待 Runner 就绪超时（{timeout_sec}s）") from exc

    def _register_internal_methods(self) -> None:
        """注册 Host 侧内部 RPC 方法。"""
        self._rpc_server.register_method("cap.call", self._capability_service.handle_capability_request)
        self._rpc_server.register_method("host.route_message", self._handle_route_message)
        self._rpc_server.register_method("host.update_message_gateway_state", self._handle_update_message_gateway_state)
        self._rpc_server.register_method("plugin.bootstrap", self._handle_bootstrap_plugin)
        self._rpc_server.register_method("plugin.register_components", self._handle_register_plugin)
        self._rpc_server.register_method("plugin.register_plugin", self._handle_register_plugin)
        self._rpc_server.register_method("plugin.unregister", self._handle_unregister_plugin)
        self._rpc_server.register_method("runner.log_batch", self._log_bridge.handle_log_batch)
        self._rpc_server.register_method("runner.ready", self._handle_runner_ready)

    async def _handle_bootstrap_plugin(self, envelope: Envelope) -> Envelope:
        """处理插件 bootstrap 请求。

        Args:
            envelope: RPC 请求信封。

        Returns:
            Envelope: RPC 响应信封。
        """
        try:
            payload = BootstrapPluginPayload.model_validate(envelope.payload)
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        if payload.capabilities_required:
            self._authorization.register_plugin(payload.plugin_id, payload.capabilities_required)
        else:
            self._authorization.revoke_permission_token(payload.plugin_id)

        return envelope.make_response(payload={"accepted": True, "plugin_id": payload.plugin_id})

    async def _handle_register_plugin(self, envelope: Envelope) -> Envelope:
        """处理插件组件注册请求。

        Args:
            envelope: RPC 请求信封。

        Returns:
            Envelope: RPC 响应信封。
        """
        try:
            payload = RegisterPluginPayload.model_validate(envelope.payload)
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        component_declarations = [component.model_dump() for component in payload.components]
        runtime_components, api_components = self._split_component_declarations(component_declarations)
        try:
            registered_count = self._component_registry.register_plugin_components(
                payload.plugin_id,
                runtime_components,
            )
        except Exception as exc:
            logger.error(f"插件 {payload.plugin_id} 组件注册失败: {exc}")
            return envelope.make_error_response(
                ErrorCode.E_BAD_PAYLOAD.value,
                str(exc),
                details={
                    "plugin_id": payload.plugin_id,
                    "component_count": len(runtime_components),
                },
            )

        self._api_registry.remove_apis_by_plugin(payload.plugin_id)
        registered_api_count = self._api_registry.register_plugin_apis(payload.plugin_id, api_components)
        await self._unregister_all_message_gateway_drivers_for_plugin(payload.plugin_id)
        self._registered_plugins[payload.plugin_id] = payload
        self._message_gateway_states[payload.plugin_id] = {}

        return envelope.make_response(
            payload={
                "accepted": True,
                "plugin_id": payload.plugin_id,
                "registered_components": registered_count,
                "registered_apis": registered_api_count,
                "message_gateways": len(
                    self._component_registry.get_message_gateways(plugin_id=payload.plugin_id, enabled_only=False)
                ),
            }
        )

    async def _handle_unregister_plugin(self, envelope: Envelope) -> Envelope:
        """处理插件注销请求。

        Args:
            envelope: RPC 请求信封。

        Returns:
            Envelope: RPC 响应信封。
        """
        try:
            payload = UnregisterPluginPayload.model_validate(envelope.payload)
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        removed_components = self._component_registry.remove_components_by_plugin(payload.plugin_id)
        removed_apis = self._api_registry.remove_apis_by_plugin(payload.plugin_id)
        self._authorization.revoke_permission_token(payload.plugin_id)
        removed_registration = self._registered_plugins.pop(payload.plugin_id, None) is not None
        await self._unregister_all_message_gateway_drivers_for_plugin(payload.plugin_id)
        self._message_gateway_states.pop(payload.plugin_id, None)

        return envelope.make_response(
            payload={
                "accepted": True,
                "plugin_id": payload.plugin_id,
                "reason": payload.reason,
                "removed_components": removed_components,
                "removed_apis": removed_apis,
                "removed_registration": removed_registration,
            }
        )

    @staticmethod
    def _is_api_component(component: Dict[str, Any]) -> bool:
        """判断组件声明是否属于 API。

        Args:
            component: 原始组件声明字典。

        Returns:
            bool: 是否为 API 组件。
        """

        return str(component.get("component_type", "") or "").strip().upper() == "API"

    def _split_component_declarations(
        self,
        components: List[Dict[str, Any]],
    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
        """拆分通用组件声明和 API 声明。

        Args:
            components: Runner 上报的原始组件声明列表。

        Returns:
            Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
                第一个列表为需要进入通用组件表的声明，
                第二个列表为需要进入 API 专用表的声明。
        """

        runtime_components: List[Dict[str, Any]] = []
        api_components: List[Dict[str, Any]] = []
        for component in components:
            if self._is_api_component(component):
                api_components.append(component)
            else:
                runtime_components.append(component)
        return runtime_components, api_components

    @staticmethod
    def _build_message_gateway_driver_id(plugin_id: str, gateway_name: str) -> str:
        """构造消息网关驱动 ID。

        Args:
            plugin_id: 插件 ID。
            gateway_name: 网关组件名称。

        Returns:
            str: 对应 Platform IO 中的驱动 ID。
        """

        return f"gateway:{plugin_id}:{gateway_name}"

    @staticmethod
    def _normalize_runtime_route_value(value: str) -> Optional[str]:
        """规范化运行时路由字段。

        Args:
            value: 待规范化的原始字符串。

        Returns:
            Optional[str]: 规范化后非空则返回字符串，否则返回 ``None``。
        """

        normalized_value = str(value or "").strip()
        return normalized_value or None

    def _resolve_message_gateway_entry(
        self,
        plugin_id: str,
        gateway_name: str,
    ) -> Optional[Any]:
        """解析指定插件的消息网关组件。

        Args:
            plugin_id: 插件 ID。
            gateway_name: 网关组件名称；为空时按兼容规则推断。

        Returns:
            Optional[Any]: 匹配到的消息网关组件条目。
        """

        if gateway_name:
            return self._component_registry.get_message_gateway(
                plugin_id=plugin_id,
                name=gateway_name,
                enabled_only=False,
            )

        gateways = self._component_registry.get_message_gateways(plugin_id=plugin_id, enabled_only=False)
        return gateways[0] if len(gateways) == 1 else None

    async def _register_message_gateway_driver(
        self,
        plugin_id: str,
        gateway_entry: Any,
        route_key: RouteKey,
    ) -> None:
        """为消息网关注册驱动并绑定发送/接收路由。

        Args:
            plugin_id: 插件 ID。
            gateway_entry: 消息网关组件条目。
            route_key: 当前链路对应的路由键。
        """

        await self._unregister_message_gateway_driver(plugin_id, gateway_entry.name)

        platform_io_manager = get_platform_io_manager()
        driver = PluginPlatformDriver(
            driver_id=self._build_message_gateway_driver_id(plugin_id, gateway_entry.name),
            platform=route_key.platform,
            account_id=route_key.account_id,
            scope=route_key.scope,
            plugin_id=plugin_id,
            component_name=gateway_entry.name,
            supports_send=bool(gateway_entry.supports_send),
            supervisor=self,
            metadata={
                "protocol": gateway_entry.protocol,
                "route_type": gateway_entry.route_type,
                **gateway_entry.metadata,
            },
        )

        try:
            if platform_io_manager.is_started:
                await platform_io_manager.add_driver(driver)
            else:
                platform_io_manager.register_driver(driver)
        except Exception:
            with contextlib.suppress(Exception):
                if platform_io_manager.is_started:
                    await platform_io_manager.remove_driver(driver.driver_id)
                else:
                    platform_io_manager.unregister_driver(driver.driver_id)
            raise

        binding_metadata = {
            "plugin_id": plugin_id,
            "gateway_name": gateway_entry.name,
            "protocol": gateway_entry.protocol,
            "route_type": gateway_entry.route_type,
            **gateway_entry.metadata,
        }
        binding = RouteBinding(
            route_key=route_key,
            driver_id=driver.driver_id,
            driver_kind=DriverKind.PLUGIN,
            metadata=binding_metadata,
        )
        if gateway_entry.supports_send:
            platform_io_manager.bind_send_route(binding)
        if gateway_entry.supports_receive:
            platform_io_manager.bind_receive_route(binding)

    async def _unregister_message_gateway_driver(self, plugin_id: str, gateway_name: str) -> None:
        """从 Platform IO 注销单个消息网关驱动。

        Args:
            plugin_id: 插件 ID。
            gateway_name: 网关组件名称。
        """

        platform_io_manager = get_platform_io_manager()
        driver_id = self._build_message_gateway_driver_id(plugin_id, gateway_name)
        platform_io_manager.send_route_table.remove_bindings_by_driver(driver_id)
        platform_io_manager.receive_route_table.remove_bindings_by_driver(driver_id)

        with contextlib.suppress(Exception):
            if platform_io_manager.is_started:
                await platform_io_manager.remove_driver(driver_id)
            else:
                platform_io_manager.unregister_driver(driver_id)

    async def _unregister_all_message_gateway_drivers_for_plugin(self, plugin_id: str) -> None:
        """注销指定插件的全部消息网关驱动。

        Args:
            plugin_id: 插件 ID。
        """

        gateway_names = list(self._message_gateway_states.get(plugin_id, {}).keys())
        for gateway_name in gateway_names:
            await self._unregister_message_gateway_driver(plugin_id, gateway_name)

    def _build_message_gateway_route_key(
        self,
        gateway_entry: Any,
        payload: MessageGatewayStateUpdatePayload,
    ) -> RouteKey:
        """根据消息网关运行时状态构造路由键。

        Args:
            gateway_entry: 消息网关组件条目。
            payload: 网关上报的运行时状态。

        Returns:
            RouteKey: 当前链路对应的路由键。

        Raises:
            ValueError: 当平台信息缺失时抛出。
        """

        if not (platform := str(payload.platform or gateway_entry.platform or "").strip()):
            raise ValueError(f"消息网关 {gateway_entry.full_name} 未提供有效的平台名称")

        return RouteKey(
            platform=platform,
            account_id=self._normalize_runtime_route_value(payload.account_id) or gateway_entry.account_id or None,
            scope=self._normalize_runtime_route_value(payload.scope) or gateway_entry.scope or None,
        )

    def _apply_message_gateway_state(
        self,
        plugin_id: str,
        gateway_entry: Any,
        payload: MessageGatewayStateUpdatePayload,
    ) -> Tuple[_MessageGatewayRuntimeState, Dict[str, Any]]:
        """应用消息网关运行时状态，并同步 Platform IO 路由。

        Args:
            plugin_id: 插件 ID。
            gateway_entry: 消息网关组件条目。
            payload: 网关上报的运行时状态。

        Returns:
            Tuple[_MessageGatewayRuntimeState, Dict[str, Any]]: 更新后的状态与路由键字典。
        """

        plugin_states = self._message_gateway_states.setdefault(plugin_id, {})
        if not payload.ready:
            runtime_state = _MessageGatewayRuntimeState(
                ready=False,
                platform=self._normalize_runtime_route_value(payload.platform) or gateway_entry.platform or None,
                account_id=self._normalize_runtime_route_value(payload.account_id) or gateway_entry.account_id or None,
                scope=self._normalize_runtime_route_value(payload.scope) or gateway_entry.scope or None,
                metadata=dict(payload.metadata),
            )
            plugin_states[gateway_entry.name] = runtime_state
            return runtime_state, {}

        route_key = self._build_message_gateway_route_key(gateway_entry, payload)
        runtime_state = _MessageGatewayRuntimeState(
            ready=True,
            platform=route_key.platform,
            account_id=route_key.account_id,
            scope=route_key.scope,
            metadata=dict(payload.metadata),
        )
        plugin_states[gateway_entry.name] = runtime_state
        return runtime_state, {
            "platform": route_key.platform,
            "account_id": route_key.account_id,
            "scope": route_key.scope,
        }

    @staticmethod
    def _attach_inbound_route_metadata(
        session_message: "SessionMessage",
        route_key: RouteKey,
        route_metadata: Dict[str, Any],
    ) -> None:
        """将入站路由信息写回消息的 ``additional_config``。

        Args:
            session_message: 已构造好的内部消息对象。
            route_key: Host 为该消息解析出的标准路由键。
            route_metadata: 插件通过 RPC 补充的原始路由辅助元数据。
        """

        additional_config = session_message.message_info.additional_config
        if not isinstance(additional_config, dict):
            additional_config = {}
            session_message.message_info.additional_config = additional_config

        for key, value in route_metadata.items():
            if value is None:
                continue
            normalized_value = str(value).strip()
            if normalized_value:
                additional_config[key] = value

        if route_key.account_id:
            additional_config.setdefault("platform_io_account_id", route_key.account_id)
        if route_key.scope:
            additional_config.setdefault("platform_io_scope", route_key.scope)

    def _build_inbound_route_key(
        self,
        gateway_entry: Any,
        runtime_state: _MessageGatewayRuntimeState,
        message: Dict[str, Any],
        route_metadata: Dict[str, Any],
    ) -> RouteKey:
        """为入站消息构造归一路由键。

        Args:
            gateway_entry: 接收消息的网关组件条目。
            runtime_state: 当前网关的运行时状态。
            message: 标准消息字典。
            route_metadata: 插件补充的路由辅助元数据。

        Returns:
            RouteKey: 供 Platform IO 使用的规范化路由键。
        """

        platform = str(
            message.get("platform")
            or route_metadata.get("platform")
            or runtime_state.platform
            or gateway_entry.platform
            or ""
        ).strip()
        if not platform:
            raise ValueError(f"消息网关 {gateway_entry.full_name} 的入站消息缺少平台信息")

        try:
            route_key = RouteKeyFactory.from_message_dict(message)
        except Exception:
            route_key = RouteKey(platform=platform)

        route_account_id, route_scope = RouteKeyFactory.extract_components(route_metadata)
        account_id = (
            route_key.account_id or route_account_id or runtime_state.account_id or gateway_entry.account_id or None
        )
        scope = route_key.scope or route_scope or runtime_state.scope or gateway_entry.scope or None
        return RouteKey(
            platform=platform,
            account_id=account_id,
            scope=scope,
        )

    async def _handle_update_message_gateway_state(self, envelope: Envelope) -> Envelope:
        """处理消息网关上报的运行时状态更新。

        Args:
            envelope: RPC 请求信封。

        Returns:
            Envelope: 状态更新处理结果。
        """

        try:
            payload = MessageGatewayStateUpdatePayload.model_validate(envelope.payload)
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        gateway_entry = self._resolve_message_gateway_entry(envelope.plugin_id, payload.gateway_name)
        if gateway_entry is None:
            return envelope.make_error_response(
                ErrorCode.E_METHOD_NOT_ALLOWED.value,
                f"插件 {envelope.plugin_id} 未声明消息网关 {payload.gateway_name or '<auto>'}",
            )

        try:
            if payload.ready:
                route_key = self._build_message_gateway_route_key(gateway_entry, payload)
                await self._register_message_gateway_driver(envelope.plugin_id, gateway_entry, route_key)
            else:
                await self._unregister_message_gateway_driver(envelope.plugin_id, gateway_entry.name)
            runtime_state, route_key_dict = self._apply_message_gateway_state(
                plugin_id=envelope.plugin_id,
                gateway_entry=gateway_entry,
                payload=payload,
            )
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        response = MessageGatewayStateUpdateResultPayload(
            accepted=True,
            ready=runtime_state.ready,
            route_key=route_key_dict,
        )
        return envelope.make_response(payload=response.model_dump())

    async def _handle_route_message(self, envelope: Envelope) -> Envelope:
        """处理消息网关上报的外部入站消息。

        Args:
            envelope: RPC 请求信封。

        Returns:
            Envelope: 注入结果响应。
        """

        try:
            payload = RouteMessagePayload.model_validate(envelope.payload)
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        gateway_entry = self._resolve_message_gateway_entry(envelope.plugin_id, payload.gateway_name)
        if gateway_entry is None or not bool(gateway_entry.supports_receive):
            return envelope.make_error_response(
                ErrorCode.E_METHOD_NOT_ALLOWED.value,
                f"插件 {envelope.plugin_id} 未声明可接收的消息网关 {payload.gateway_name}",
            )

        runtime_state = self._message_gateway_states.get(envelope.plugin_id, {}).get(
            gateway_entry.name,
            _MessageGatewayRuntimeState(),
        )
        if not runtime_state.ready:
            return envelope.make_error_response(
                ErrorCode.E_METHOD_NOT_ALLOWED.value,
                f"消息网关 {gateway_entry.full_name} 尚未就绪，不能注入外部消息",
            )

        try:
            route_key = self._build_inbound_route_key(
                gateway_entry=gateway_entry,
                runtime_state=runtime_state,
                message=payload.message,
                route_metadata=payload.route_metadata,
            )
            session_message = self._message_gateway.build_session_message(payload.message)
            self._attach_inbound_route_metadata(session_message, route_key, payload.route_metadata)
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        platform_io_manager = get_platform_io_manager()
        accepted = await platform_io_manager.accept_inbound(
            InboundMessageEnvelope(
                route_key=route_key,
                driver_id=self._build_message_gateway_driver_id(envelope.plugin_id, gateway_entry.name),
                driver_kind=DriverKind.PLUGIN,
                external_message_id=payload.external_message_id or str(payload.message.get("message_id") or "") or None,
                dedupe_key=payload.dedupe_key or None,
                session_message=session_message,
                payload=payload.message,
                metadata={
                    "plugin_id": envelope.plugin_id,
                    "gateway_name": gateway_entry.name,
                    "protocol": gateway_entry.protocol,
                    **payload.route_metadata,
                },
            )
        )
        response = ReceiveExternalMessageResultPayload(
            accepted=accepted,
            route_key={
                "platform": route_key.platform,
                "account_id": route_key.account_id,
                "scope": route_key.scope,
            },
        )
        return envelope.make_response(payload=response.model_dump())

    async def _handle_runner_ready(self, envelope: Envelope) -> Envelope:
        """处理 Runner 就绪通知。

        Args:
            envelope: RPC 请求信封。

        Returns:
            Envelope: RPC 响应信封。
        """
        try:
            payload = RunnerReadyPayload.model_validate(envelope.payload)
        except Exception as exc:
            return envelope.make_error_response(ErrorCode.E_BAD_PAYLOAD.value, str(exc))

        self._runner_ready_payloads = payload
        self._runner_ready_events.set()
        return envelope.make_response(payload={"accepted": True})

    def _build_runner_environment(self) -> Dict[str, str]:
        """构建拉起 Runner 所需的环境变量。

        Returns:
            Dict[str, str]: 传递给 Runner 进程的环境变量映射。
        """
        global_config_snapshot = config_manager.get_global_config().model_dump(mode="json")
        global_config_snapshot["model"] = config_manager.get_model_config().model_dump(mode="json")
        return {
            ENV_EXTERNAL_PLUGIN_IDS: json.dumps(self._external_available_plugins, ensure_ascii=False),
            ENV_GLOBAL_CONFIG_SNAPSHOT: json.dumps(global_config_snapshot, ensure_ascii=False),
            ENV_HOST_VERSION: PROTOCOL_VERSION,
            ENV_IPC_ADDRESS: self._transport.get_address(),
            ENV_PLUGIN_DIRS: os.pathsep.join(str(path) for path in self._plugin_dirs),
            ENV_SESSION_TOKEN: self._rpc_server.session_token,
        }

    async def _spawn_runner(self) -> None:
        """拉起 Runner 子进程。"""
        if self._runner_process is not None and self._runner_process.returncode is None:
            logger.warning("Runner 已在运行，跳过重复拉起")
            return

        self._clear_runner_state()

        env = os.environ.copy()
        env.update(self._build_runner_environment())

        self._runner_process = await asyncio.create_subprocess_exec(
            sys.executable,
            "-m",
            "src.plugin_runtime.runner.runner_main",
            env=env,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.PIPE,
        )

        if self._runner_process.stderr is not None:
            self._stderr_drain_task = asyncio.create_task(
                self._drain_runner_stderr(self._runner_process.stderr),
                name="PluginRunnerSupervisor.stderr",
            )

        logger.info(f"Runner 已拉起，pid={self._runner_process.pid}")

    async def _drain_runner_stderr(self, stream: asyncio.StreamReader) -> None:
        """持续排空 Runner 的 stderr。

        Args:
            stream: Runner 的 stderr 流。
        """
        try:
            while True:
                line = await stream.readline()
                if not line:
                    return
                if message := line.decode("utf-8", errors="replace").rstrip():
                    logger.warning(f"[runner-stderr] {message}")
        except asyncio.CancelledError:
            raise
        except Exception as exc:
            logger.warning(f"排空 Runner stderr 失败: {exc}")

    async def _shutdown_runner(self, reason: str = "normal") -> None:
        """优雅关闭 Runner 子进程。

        Args:
            reason: 关停原因。
        """
        process = self._runner_process
        if process is None:
            return

        payload = ShutdownPayload(reason=reason)

        if process.returncode is None and self._rpc_server.is_connected:
            with contextlib.suppress(Exception):
                await self._rpc_server.send_request(
                    "plugin.prepare_shutdown",
                    payload=payload.model_dump(),
                    timeout_ms=payload.drain_timeout_ms,
                )
            with contextlib.suppress(Exception):
                await self._rpc_server.send_request(
                    "plugin.shutdown",
                    payload=payload.model_dump(),
                    timeout_ms=payload.drain_timeout_ms,
                )

        if process.returncode is None:
            try:
                await asyncio.wait_for(process.wait(), timeout=max(payload.drain_timeout_ms / 1000.0, 1.0))
            except asyncio.TimeoutError:
                logger.warning("Runner 优雅退出超时，尝试 terminate")
                process.terminate()
                try:
                    await asyncio.wait_for(process.wait(), timeout=5.0)
                except asyncio.TimeoutError:
                    logger.warning("Runner terminate 超时，尝试 kill")
                    process.kill()
                    with contextlib.suppress(Exception):
                        await asyncio.wait_for(process.wait(), timeout=5.0)

        self._runner_process = None

        if self._stderr_drain_task is not None:
            self._stderr_drain_task.cancel()
            with contextlib.suppress(asyncio.CancelledError):
                await self._stderr_drain_task
            self._stderr_drain_task = None

        for plugin_id in list(self._message_gateway_states.keys()):
            await self._unregister_all_message_gateway_drivers_for_plugin(plugin_id)
        self._clear_runner_state()

    async def _health_check_loop(self) -> None:
        """周期性检查 Runner 健康状态，并在必要时重启。"""
        timeout_ms = max(int(self._health_interval * 1000), 1000)

        while self._running:
            try:
                await asyncio.sleep(self._health_interval)
            except asyncio.CancelledError:
                return

            if not self._running:
                return

            process = self._runner_process
            if process is None or process.returncode is not None:
                reason = "runner_process_exited" if process is not None else "runner_process_missing"
                restarted = await self._restart_runner(reason=reason)
                if not restarted:
                    return
                continue

            try:
                response = await self._rpc_server.send_request("plugin.health", timeout_ms=timeout_ms)
                health = HealthPayload.model_validate(response.payload)
                if not health.healthy:
                    restarted = await self._restart_runner(reason="health_check_unhealthy")
                    if not restarted:
                        return
            except asyncio.CancelledError:
                return
            except (RPCError, Exception) as exc:
                logger.warning(f"Runner 健康检查失败: {exc}")
                restarted = await self._restart_runner(reason="health_check_failed")
                if not restarted:
                    return

    async def _restart_runner(self, reason: str) -> bool:
        """在 Runner 异常时执行整进程级重启。

        Args:
            reason: 触发重启的原因。

        Returns:
            bool: 是否重启成功。
        """
        if not self._running:
            return False

        if self._restart_count >= self._max_restart_attempts:
            logger.error(f"Runner 自动重启次数已达上限，停止重启。reason={reason}")
            return False

        self._restart_count += 1
        logger.warning(f"准备重启 Runner，第 {self._restart_count} 次，reason={reason}")

        await self._shutdown_runner(reason=reason)

        try:
            await self._spawn_runner()
            await self._wait_for_runner_connection(timeout_sec=self._runner_spawn_timeout)
            await self._wait_for_runner_ready(timeout_sec=self._runner_spawn_timeout)
        except Exception as exc:
            await self._shutdown_runner(reason="restart_failed")
            logger.error(f"Runner 重启失败: {exc}", exc_info=True)
            return False

        self._restart_count = 0
        logger.info("Runner 已成功重启")
        return True

    def _clear_runner_state(self) -> None:
        """清理当前 Runner 对应的 Host 侧注册状态。"""
        self._authorization.clear()
        self._api_registry.clear()
        self._component_registry.clear()
        self._registered_plugins.clear()
        self._message_gateway_states.clear()
        self._runner_ready_events = asyncio.Event()
        self._runner_ready_payloads = RunnerReadyPayload()
        self._rpc_server.clear_handshake_state()

    def _get_runner_startup_failure_reason(self) -> Optional[str]:
        """获取 Runner 在启动阶段已经暴露出的失败原因。

        Returns:
            Optional[str]: 若已检测到失败则返回失败原因，否则返回 ``None``。
        """
        if handshake_reason := self._rpc_server.last_handshake_rejection_reason:
            return f"握手被拒绝: {handshake_reason}"

        process = self._runner_process
        if process is None:
            return "Runner 进程不存在"

        if process.returncode is not None:
            return f"Runner 进程已退出，退出码 {process.returncode}"

        return None


PluginSupervisor = PluginRunnerSupervisor