Trait Channel 

pub trait Channel:
    Send
    + Sync
    + Attributable {
    // Required methods
    fn name(&self) -> &str;
    fn send<'life0, 'life1, 'async_trait>(
        &'life0 self,
        message: &'life1 SendMessage,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn listen<'life0, 'async_trait>(
        &'life0 self,
        tx: Sender<ChannelMessage>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn health_check<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn start_typing<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _recipient: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn stop_typing<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _recipient: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn supports_draft_updates(&self) -> bool { ... }
    fn self_handle(&self) -> Option<String> { ... }
    fn self_addressed_mention(&self) -> Option<String> { ... }
    fn drop_self_messages(&self, msg: &ChannelMessage) -> bool { ... }
    fn supports_multi_message_streaming(&self) -> bool { ... }
    fn multi_message_delay_ms(&self) -> u64 { ... }
    fn send_draft<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _message: &'life1 SendMessage,
    ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn update_draft<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        _recipient: &'life1 str,
        _message_id: &'life2 str,
        _text: &'life3 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn update_draft_progress<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        _recipient: &'life1 str,
        _message_id: &'life2 str,
        _text: &'life3 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn finalize_draft<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        _recipient: &'life1 str,
        _message_id: &'life2 str,
        _text: &'life3 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn cancel_draft<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _recipient: &'life1 str,
        _message_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn add_reaction<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        _channel_id: &'life1 str,
        _message_id: &'life2 str,
        _emoji: &'life3 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn remove_reaction<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        _channel_id: &'life1 str,
        _message_id: &'life2 str,
        _emoji: &'life3 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn pin_message<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _channel_id: &'life1 str,
        _message_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn unpin_message<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _channel_id: &'life1 str,
        _message_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn redact_message<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _channel_id: &'life1 str,
        _message_id: &'life2 str,
        _reason: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn request_approval<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _recipient: &'life1 str,
        _request: &'life2 ChannelApprovalRequest,
    ) -> Pin<Box<dyn Future<Output = Result<Option<ChannelApprovalResponse>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn request_choice<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _question: &'life1 str,
        _choices: &'life2 [String],
        _timeout: Duration,
    ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn supports_free_form_ask(&self) -> bool { ... }
}

Core channel trait — implement for any messaging platform.

Every Channel is Attributable: the orchestrator’s spawn site opens attribution_span!(&*ch) so log emissions from within listen() / send() inherit channel = <type>.<alias> from the trait object’s role + alias.

Required Methods

fn name(&self) -> &str

Human-readable channel name

fn send<'life0, 'life1, 'async_trait>( &'life0 self, message: &'life1 SendMessage, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Send a message through this channel

fn listen<'life0, 'async_trait>( &'life0 self, tx: Sender<ChannelMessage>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Start listening for incoming messages (long-running)

Provided Methods

fn health_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Check if channel is healthy

fn start_typing<'life0, 'life1, 'async_trait>( &'life0 self, _recipient: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Signal that the bot is processing a response (e.g. “typing” indicator).

fn stop_typing<'life0, 'life1, 'async_trait>( &'life0 self, _recipient: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Stop any active typing indicator.

fn supports_draft_updates(&self) -> bool

Whether this channel supports progressive message updates via draft edits.

fn self_handle(&self) -> Option<String>

Self-loop guard for multi-agent runs.

Returns the bot’s own handle/identity on this channel (e.g. @my_bot for Telegram, the bot’s user ID for Discord) when known, so the orchestrator can drop inbound events whose sender matches: a bot must never respond to its own messages, even if a misconfigured peer group lists the bot’s handle as an external peer.

Channels that handle inbound traffic must override this. The default None makes both layers of the orchestrator’s self-loop guard (the SDK-side drop_self_messages here, and the agent-loop fallback peers::should_drop_self_loop) into no-ops — both layers consult the same self_handle, so a channel that returns None has no protection from looping on its own outbound. Outbound-only channels (webhook, gmail-push, voice-call) never see inbound and can keep the default. The in-tree overrides currently cover Telegram (bot_username cache), IRC (configured nickname), Discord (decoded from token), Slack (cached auth.test user_id); other inbound channels remain on the default and rely on per-impl filtering instead of the shared guard.

fn self_addressed_mention(&self) -> Option<String>

The exact form the bot expects to see when addressed by users on this channel. Discord wraps the snowflake as <@1088...>, Telegram presents @bot_username, Matrix presents @bot:server, Slack wraps the user ID as <@U02...>. Returned verbatim into the per-channel system prompt so the agent recognizes its own mention without guessing, and uses the same form to tag itself or peers in outbound replies.

Default None for channels that have no inbound mention concept (CLI, webhook, hardware, ACP elicitation). Channels that override self_handle should usually override this too, applying their platform-native mention wrapper to the handle.

fn drop_self_messages(&self, msg: &ChannelMessage) -> bool

Whether the orchestrator should drop an inbound message as self-authored (multi-agent self-loop guard).

Default implementation compares msg.sender against Self::self_handle case-insensitively, after stripping a leading @ from each side so Telegram-style handles match regardless of which form the SDK delivers. Override only for platforms whose identity comparison is non-string (e.g. a numeric Discord user ID is as_str already; this default works there too).

fn supports_multi_message_streaming(&self) -> bool

Whether this channel supports multi-message streaming delivery.

fn multi_message_delay_ms(&self) -> u64

Minimum delay (ms) between sending each paragraph in multi-message mode.

fn send_draft<'life0, 'life1, 'async_trait>( &'life0 self, _message: &'life1 SendMessage, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Send an initial draft message. Returns a platform-specific message ID for later edits.

fn update_draft<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _recipient: &'life1 str, _message_id: &'life2 str, _text: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Update a previously sent draft message with new accumulated content.

fn update_draft_progress<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _recipient: &'life1 str, _message_id: &'life2 str, _text: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Show a progress/status update (e.g. tool execution status).

fn finalize_draft<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _recipient: &'life1 str, _message_id: &'life2 str, _text: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Finalize a draft with the complete response (e.g. apply Markdown formatting).

fn cancel_draft<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _recipient: &'life1 str, _message_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Cancel and remove a previously sent draft message if the channel supports it.

fn add_reaction<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, _emoji: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Add a reaction (emoji) to a message.

fn remove_reaction<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, _emoji: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Remove a reaction (emoji) from a message previously added by this bot.

fn pin_message<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Pin a message in the channel.

fn unpin_message<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Unpin a previously pinned message.

fn redact_message<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, _reason: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Redact (delete) a message from the channel.

fn request_approval<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _recipient: &'life1 str, _request: &'life2 ChannelApprovalRequest, ) -> Pin<Box<dyn Future<Output = Result<Option<ChannelApprovalResponse>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Request interactive tool-call approval from the channel operator.

Returns Ok(Some(response)) when the operator answers within the channel’s configured approval_timeout_secs; timeouts are surfaced as Deny. Returns Ok(None) only for channels that do not implement the prompt at all — the caller should fall back to its default policy (typically auto-deny).

Surface varies by channel:

• Telegram uses inline keyboard buttons.
• Slack Socket Mode uses Block Kit buttons; webhook fallback and non–Socket Mode deployments use a token text reply.
• Discord, Signal, Matrix, WhatsApp embed a 6-character alphanumeric token in the prompt and wait for a <token> approve|deny|always reply on the same conversation.

fn request_choice<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _question: &'life1 str, _choices: &'life2 [String], _timeout: Duration, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Ask the user a multiple-choice question and return the chosen option’s text.

Returns Ok(Some(answer)) if the channel handled the question natively (e.g. ACP session/request_permission, Telegram inline keyboard). Returns Ok(None) to signal the caller should fall back to the generic send + listen flow. Default impl returns None.

Free-form questions (no choices) are not modeled here yet — they require the ACP elicitation RFD to land for a clean cross-channel API.

fn supports_free_form_ask(&self) -> bool

Whether this channel can answer free-form (no-choices) ask_user questions via the standard send + listen flow.

Channels that can only handle structured choices (e.g. ACP today, until the elicitation RFD lands) should return false so callers can fail fast with a useful error instead of timing out on listen.

Implementors