"""MessageBus ABC — Agent 间通信抽象基类。

与 protocol.py 的 Protocol 定义并存，提供 ABC 版本用于显式继承。
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Callable, Awaitable

from agentkit.bus.message import AgentMessage


class MessageBus(ABC):
    """Agent 间消息总线抽象基类。

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

    @abstractmethod
    async def publish(self, message: AgentMessage) -> bool:
        """发布消息，返回是否成功。"""
        ...

    @abstractmethod
    async def subscribe(
        self,
        agent_name: str,
        handler: Callable[[AgentMessage], Awaitable[None]],
    ) -> None:
        """订阅消息。"""
        ...

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

    @abstractmethod
    async def request(
        self,
        message: AgentMessage,
        timeout_seconds: float = 30.0,
    ) -> AgentMessage | None:
        """发送请求并等待响应。超时返回 None。"""
        ...
