"""MessageBus Protocol — Agent 间通信抽象层。"""

from __future__ import annotations

from typing import Any, Callable, Awaitable, Protocol as TypingProtocol, runtime_checkable

from agentkit.bus.message import AgentMessage


@runtime_checkable
class MessageBus(TypingProtocol):
    """Agent 间通信总线协议。

    支持三种通信模式：
    - 点对点：publish() 指定 recipient
    - 广播：publish() 不指定 recipient（或 broadcast()）
    - 请求-响应：request() 等待对方通过 correlation_id 回复
    """

    async def publish(self, message: AgentMessage) -> None:
        """发布消息。如果 message.recipient 为 None，则广播。"""
        ...

    async def subscribe(
        self,
        agent_name: str,
        handler: Callable[[AgentMessage], Awaitable[None]],
    ) -> None:
        """订阅消息。handler 在收到消息时被调用。"""
        ...

    async def unsubscribe(self, agent_name: str) -> None:
        """取消订阅。"""
        ...

    async def request(
        self,
        message: AgentMessage,
        timeout: float = 30.0,
    ) -> AgentMessage:
        """请求-响应模式。发送消息并等待回复。

        Args:
            message: 请求消息
            timeout: 超时秒数

        Returns:
            响应消息

        Raises:
            TimeoutError: 超时未收到响应
        """
        ...

    async def broadcast(self, message: AgentMessage) -> None:
        """广播消息给所有订阅者。"""
        ...

    async def health_check(self) -> bool:
        """健康检查。"""
        ...