Agent/gateway/core/channels/protocols.py

from __future__ import annotations

from typing import Any, Protocol, runtime_checkable

from gateway.core.channels.types import FeishuReplyContext, IncomingFeishuEvent


@runtime_checkable
class TraceBackend(Protocol):
    """与 Lifecycle.TraceManager 对接前的抽象：按渠道用户解析 trace_id。"""

    async def get_or_create_trace(
        self,
        *,
        channel: str,
        user_id: str,
        workspace_id: str,
        agent_type: str,
        metadata: dict[str, Any],
    ) -> str:
        ...


@runtime_checkable
class ExecutorBackend(Protocol):
    """与 Executor 对接前的抽象：处理入站用户文本并负责回呼飞书。"""

    async def handle_inbound_message(
        self,
        trace_id: str,
        text: str,
        reply_context: FeishuReplyContext,
        connector: Any,
        *,
        event: IncomingFeishuEvent,
    ) -> str:
        """返回 task_id 或占位 id。"""
        ...


@runtime_checkable
class UserIdentityResolver(Protocol):
    """将飞书事件映射为网关内统一 user_id（后续可换 DB 映射表）。"""

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