"""飞书渠道在通用 ``ExecutorBackend`` / ``UserIdentityResolver`` 上的类型收窄。"""

from __future__ import annotations

from typing import Any, Protocol, runtime_checkable

from gateway.core.channels.feishu.types import FeishuReplyContext, IncomingFeishuEvent
from gateway.core.channels.protocols import ExecutorBackend, UserIdentityResolver

__all__ = ["FeishuExecutorBackend", "FeishuUserIdentityResolver"]


@runtime_checkable
class FeishuExecutorBackend(ExecutorBackend, Protocol):
    """飞书执行器——窄化 ``ExecutorBackend`` 的参数类型为飞书专属结构。"""

    async def handle_inbound_message(
        self,
        existing_agent_trace_id: str,
        text: str,
        reply_context: FeishuReplyContext,
        connector: Any,
        *,
        event: IncomingFeishuEvent,
    ) -> tuple[str, str]:
        """返回 ``(task_id, agent_trace_id)``；失败时 ``agent_trace_id`` 为空。"""
        ...


@runtime_checkable
class FeishuUserIdentityResolver(UserIdentityResolver, Protocol):
    """飞书用户身份解析器——窄化 ``UserIdentityResolver`` 的事件类型为 ``IncomingFeishuEvent``。"""

    def resolve_user_id(self, event: IncomingFeishuEvent) -> str:
        ...