"""
消息账本协议：inbox / outbox 认领接口。

Memory 与 Postgres 实现共用此协议，通道运行时不依赖具体后端。
"""

from __future__ import annotations

from typing import Any, Optional, Protocol

from agent.channel.queue import InboxItem, OutboxItem
from agent.channel.wecom.models import InboundMessage


class MessageStore(Protocol):
    """inbox/outbox 账本协议。"""

    def enqueue_inbound(self, message: InboundMessage) -> tuple[bool, str]: ...

    def claim_inbound(self) -> Optional[InboxItem]: ...

    def complete_inbound(self, item_id: str, *, error: str = "") -> None: ...

    def enqueue_outbound(
        self,
        *,
        touser: str,
        content: str,
        dedupe_key: str = "",
        payload: Optional[dict[str, Any]] = None,
    ) -> tuple[bool, str]: ...

    def claim_outbound(self) -> Optional[OutboxItem]: ...

    def complete_outbound(
        self, item_id: str, *, error: str = "", permanent: bool = False
    ) -> None: ...

    def wait_inbox(self, timeout: float = 1.0) -> None: ...

    def wait_outbox(self, timeout: float = 1.0) -> None: ...

    def wait_outbound_done(self, item_id: str, timeout_sec: float = 12.0) -> bool: ...

    def stats(self) -> dict[str, Any]: ...