Interfaces Overview

Platform API ──> Interface Adapter ──> InboundMessage ──> ChannelRegistry
                                                              │
                                                    InboundMessageRouter
                                                  (single source: access,
                                                   pairing, allowlist,
                                                   session key, agent binding)
                                                              │
                                                            Harness
                                                               │
Platform API <── Interface Adapter <── OutboundMessage <── Response

#[async_trait]
pub trait Channel: Send + Sync {
    /// Channel metadata (id, name, type, status, capabilities)
    fn info(&self) -> &ChannelInfo;

    /// Shared mutable state (status + inbound broadcast sender/receiver)
    fn state(&self) -> &ChannelState;

    /// Channel id (default: `info().id`)
    fn id(&self) -> &ChannelId { &self.info().id }
    /// Channel type (default: `info().channel_type`)
    fn channel_type(&self) -> &str { &self.info().channel_type }
    /// Current status (default: `state().status()`)
    fn status(&self) -> ChannelStatus { self.state().status() }
    /// Current health probe (default: `state().health()`)
    async fn health(&self) -> ChannelHealth { self.state().health().await }
    /// Capability table (default: `info().capabilities`)
    fn capabilities(&self) -> &ChannelCapabilities { &self.info().capabilities }

    /// Approval delivery capability (None by default; channels opt in)
    fn approval_capability(&self) -> Option<Arc<dyn ChannelApprovalCapability>> { None }

    /// Pairing payload (QR, code, ...) for channels that surface pairing
    async fn get_pairing_data(&self) -> ChannelResult<PairingData> { Ok(PairingData::None) }
    /// Active (non-expired) pairing codes — `(code, remaining_ttl_secs)`
    async fn list_active_pairing_codes(&self) -> ChannelResult<Vec<(String, u64)>> { Ok(vec![]) }

    /// Start the channel (connect, authenticate, begin polling/listening)
    async fn start(&mut self) -> ChannelResult<()>;
    /// Stop the channel (disconnect, cleanup)
    async fn stop(&mut self) -> ChannelResult<()>;

    /// Send a message through this channel
    async fn send(&self, message: OutboundMessage) -> ChannelResult<SendResult>;

    /// Subscribe to inbound messages — multiple subscribers each get their own
    /// `broadcast::Receiver<InboundMessage>`
    fn inbound_subscribe(&self) -> broadcast::Receiver<InboundMessage> {
        self.state().inbound_subscribe()
    }

    /// Send a typing indicator
    async fn send_typing(&self, conversation_id: &ConversationId) -> ChannelResult<()>;
    /// Mark a message as read
    async fn mark_read(&self, message_id: &MessageId) -> ChannelResult<()>;
    /// React to a message
    async fn react(&self, conversation_id: &ConversationId,
                   message_id: &MessageId, reaction: &str) -> ChannelResult<()>;
    /// Edit a previously sent message
    async fn edit(&self, conversation_id: &ConversationId,
                  message_id: &MessageId, new_text: &str) -> ChannelResult<()>;
    /// Delete a message
    async fn delete(&self, conversation_id: &ConversationId,
                    message_id: &MessageId) -> ChannelResult<()>;

    /// List conversations the agent can address (read-only, routing metadata)
    async fn list_conversations(&self, query: &str, limit: usize)
        -> ChannelResult<ConversationPage>;

    /// Native streaming handler (channels with `StreamProtocol::Native`)
    fn native_stream_handler(&self) -> Option<Arc<dyn NativeStreamHandler>> { None }
}

#[async_trait]
pub trait ChannelFactory: Send + Sync {
    /// Channel type this factory creates (e.g. "telegram", "discord")
    fn channel_type(&self) -> &str;
    /// Create a channel instance from configuration
    async fn create(&self, config: serde_json::Value) -> ChannelResult<Box<dyn Channel>>;
}

pub struct ChannelCapabilities {
    pub attachments: bool,
    pub images: bool,
    pub audio: bool,
    pub video: bool,
    pub reactions: bool,
    pub replies: bool,
    pub editing: bool,
    pub deletion: bool,
    pub typing_indicator: bool,
    pub read_receipts: bool,
    pub rich_text: bool,
    pub max_message_length: usize,    // 0 = unlimited
    pub max_attachment_size: u64,     // 0 = unlimited
    pub stream_protocol: StreamProtocol, // None | EditBased | Native
}

# Route all Telegram messages to the "personal" agent
[[bindings]]
agent_id = "personal"
[bindings.match_rule]
channel = "telegram"
account_id = "*"

# Route a specific Discord guild to the "work" agent
[[bindings]]
agent_id = "work"
[bindings.match_rule]
channel = "discord"
guild_id = "123456789"

[channels.telegram]
enabled = true
token = "${TELEGRAM_BOT_TOKEN}"

[channels.discord]
enabled = true
token = "${DISCORD_BOT_TOKEN}"
allowed_guilds = [123456789]

[channels.imessage]
# Local (macOS only): SQLite polling of ~/Library/Messages/chat.db
# AND/OR
# BlueBubbles (any OS): REST + webhook against a BlueBubbles server
enabled = true
db_path = "~/Library/Messages/chat.db"
poll_interval_ms = 1000