feat: implement channel runtime connectors

app-instance/backend/beaver/foundation/events/__init__.py

@@ -1,5 +1,5 @@
 """Event contracts and dispatch helpers."""
 
-from .message_bus import InboundMessage, MessageBus, OutboundMessage
+from .message_bus import ChannelIdentity, InboundMessage, MessageBus, OutboundMessage
 
-__all__ = ["InboundMessage", "MessageBus", "OutboundMessage"]
+__all__ = ["ChannelIdentity", "InboundMessage", "MessageBus", "OutboundMessage"]

app-instance/backend/beaver/foundation/events/message_bus.py

@@ -9,12 +9,58 @@ from typing import Any
 from uuid import uuid4
 
 
+@dataclass(slots=True)
+class ChannelIdentity:
+    """Normalized channel routing identity.
+
+    `channel_id` is the Beaver adapter instance id, not the platform kind.
+    """
+
+    channel_id: str
+    kind: str
+    account_id: str
+    peer_id: str
+    thread_id: str | None = None
+    peer_type: str = "unknown"
+    user_id: str | None = None
+    message_id: str | None = None
+
+    def validation_error(self) -> str | None:
+        if not self.channel_id.strip():
+            return "channel_id is required"
+        if not self.account_id.strip():
+            return "account_id is required"
+        if not self.peer_id.strip():
+            return "peer_id is required"
+        return None
+
+    def session_id(self) -> str:
+        parts = [self.channel_id, self.account_id, self.peer_id]
+        if self.thread_id:
+            parts.append(self.thread_id)
+        return ":".join(_clean_session_part(part) for part in parts)
+
+    def dedupe_key(self) -> str | None:
+        if not self.message_id:
+            return None
+        return f"{self.session_id()}:{_clean_session_part(self.message_id)}"
+
+
+def _clean_session_part(value: str) -> str:
+    cleaned = str(value).strip()
+    if not cleaned:
+        return "unknown"
+    return cleaned.replace(":", "_")
+
+
 @dataclass(slots=True)
 class InboundMessage:
     """A minimal inbound message accepted by the gateway bridge."""
 
     channel: str
     content: str
+    content_type: str = "text"
+    channel_identity: ChannelIdentity | None = None
     session_id: str | None = None
     user_id: str | None = None
     title: str | None = None
@@ -35,6 +81,8 @@ class OutboundMessage:
     content: str
     session_id: str | None
     finish_reason: str
+    content_type: str = "text"
+    channel_identity: ChannelIdentity | None = None
     message_id: str = field(default_factory=lambda: str(uuid4()))
     run_id: str | None = None
     provider_name: str | None = None