bamboo-server 2026.7.17

HTTP server and API layer for the Bamboo agent framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

//! The `Platform` trait + shared inbound/outbound message types.
//!
//! Per epic #447: cc-connect's proven 5-method core, with capabilities
//! EXPLICIT (not type-asserted) so the bridge/render layer never guesses what
//! an adapter can do. `ReplyCtx` is platform-opaque (`serde_json::Value`),
//! carried on every [`InboundMessage`] and handed back to
//! `Platform::reply`/`Platform::edit` unmodified — mirrors cc-connect's
//! `replyCtx any` pattern.

use tokio::sync::mpsc;

/// What a platform adapter supports. MVP adapters (Telegram, phase 1) advertise
/// everything `false` except plain text — buttons/streaming-edit are phase 2.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Capabilities {
    /// Inline approval/action buttons on a message.
    pub buttons: bool,
    /// In-place message editing (`Platform::edit`) — used for streaming
    /// edit-in-place in a later phase.
    pub edit_message: bool,
    /// Sending image attachments.
    pub images: bool,
    /// Sending file attachments.
    pub files: bool,
}

/// Platform-opaque context handed back unmodified to `Platform::reply`/`edit`.
/// Concrete shape is decided by each adapter (e.g. Telegram stores `chat_id`).
#[derive(Debug, Clone, PartialEq)]
pub struct ReplyCtx(pub serde_json::Value);

/// A reference to a previously-sent message, for `Platform::edit`
/// (capability-gated on [`Capabilities::edit_message`]).
#[derive(Debug, Clone, PartialEq)]
pub struct MessageRef(pub serde_json::Value);

/// A message received from a platform, normalized to the shape the bridge
/// understands. Fields beyond `text`/`reply_ctx` exist to let the bridge
/// enforce security policy (allow-list, dedup) generically across every
/// platform adapter, without knowing platform-specific wire formats.
#[derive(Debug, Clone)]
pub struct InboundMessage {
    /// Platform name (matches `Platform::name`), e.g. `"telegram"`.
    pub platform: String,
    /// Platform-scoped chat identifier.
    pub chat_id: String,
    /// Platform-scoped sender identifier (checked against `allow_from`).
    pub user_id: String,
    /// Platform-scoped, per-platform-unique message id used for dedup (e.g.
    /// Telegram's `update_id`, stringified).
    pub message_id: String,
    /// When the platform says the message was sent — used to drop stale
    /// backlog delivered right after a restart (older than process start).
    pub sent_at: chrono::DateTime<chrono::Utc>,
    /// Message text.
    pub text: String,
    /// Opaque context to hand back to `Platform::reply`/`edit`.
    pub reply_ctx: ReplyCtx,
}

/// One inline approval/action button (phase 2, issue #458). `callback_data`
/// is echoed back verbatim on press — the ONLY thing it may carry is a short
/// ask-nonce + option selector (`"{nonce}:{option_index}"`, see
/// `connect::approvals`), NEVER raw user text or anything else sensitive.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Button {
    pub label: String,
    pub callback_data: String,
}

impl Button {
    pub fn new(label: impl Into<String>, callback_data: impl Into<String>) -> Self {
        Self {
            label: label.into(),
            callback_data: callback_data.into(),
        }
    }
}

/// A message to send to a platform.
#[derive(Debug, Clone)]
pub struct OutboundMessage {
    pub text: String,
    /// Inline keyboard rows (capability-gated on [`Capabilities::buttons`]).
    /// Adapters that don't advertise `buttons` ignore this field.
    pub buttons: Option<Vec<Vec<Button>>>,
}

impl OutboundMessage {
    pub fn text(text: impl Into<String>) -> Self {
        Self {
            text: text.into(),
            buttons: None,
        }
    }

    pub fn with_buttons(mut self, buttons: Vec<Vec<Button>>) -> Self {
        self.buttons = Some(buttons);
        self
    }
}

/// An inline-button press received from a platform (capability-gated on
/// [`Capabilities::buttons`]) — the counterpart to a text [`InboundMessage`].
#[derive(Debug, Clone)]
pub struct CallbackQuery {
    /// Platform name (matches `Platform::name`), e.g. `"telegram"`.
    pub platform: String,
    /// Platform-scoped chat identifier.
    pub chat_id: String,
    /// Platform-scoped sender identifier (checked against `allow_from`,
    /// exactly like [`InboundMessage::user_id`]).
    pub user_id: String,
    /// Platform-scoped callback-query identifier. Every callback query MUST
    /// be acknowledged via `Platform::answer_callback` exactly once — success
    /// or not (stale/forged data still gets acked, just silently dropped).
    pub callback_query_id: String,
    /// The pressed button's `callback_data`, verbatim.
    pub data: String,
    /// Opaque context to hand back to `Platform::reply`/`edit`.
    pub reply_ctx: ReplyCtx,
}

/// Everything a platform can push onto its inbound channel: a text message or
/// a button press. Kept as one enum (rather than two channels) so a platform
/// whose transport interleaves both in a single feed (Telegram's
/// `getUpdates`) preserves delivery order end to end.
#[derive(Debug, Clone)]
pub enum Inbound {
    Message(InboundMessage),
    Callback(CallbackQuery),
}

/// Error returned by a `Platform` adapter operation.
#[derive(Debug, thiserror::Error)]
pub enum PlatformError {
    #[error("{0}")]
    Other(String),
}

impl PlatformError {
    pub fn other(msg: impl Into<String>) -> Self {
        Self::Other(msg.into())
    }
}

pub type PlatformResult<T> = std::result::Result<T, PlatformError>;

/// An IM-platform adapter. cc-connect's proven 5-method core (`start`,
/// `reply`, `edit`, `stop`, plus `capabilities`/`name`) — see epic #447.
#[async_trait::async_trait]
pub trait Platform: Send + Sync {
    /// Short identifier, e.g. `"telegram"`. Matches [`InboundMessage::platform`].
    fn name(&self) -> &str;

    /// What this adapter supports.
    fn capabilities(&self) -> Capabilities;

    /// Start receiving inbound events (messages and/or button presses),
    /// sending each onto `inbound`. Runs for the adapter's lifetime (a
    /// long-poll loop, a WS connection, …); returns only on an unrecoverable
    /// error or `stop()`.
    async fn start(&self, inbound: mpsc::Sender<Inbound>) -> PlatformResult<()>;

    /// Send a message in reply to `ctx`.
    async fn reply(&self, ctx: &ReplyCtx, msg: OutboundMessage) -> PlatformResult<MessageRef>;

    /// Edit a previously-sent message in place. Capability-gated on
    /// [`Capabilities::edit_message`]; adapters that don't support it may
    /// return an error — callers must check the capability first.
    async fn edit(&self, msg_ref: &MessageRef, new: OutboundMessage) -> PlatformResult<()>;

    /// Acknowledge a callback query (capability-gated on
    /// [`Capabilities::buttons`] — adapters without button support never
    /// receive one to acknowledge, so the default no-op is correct for them).
    /// Telegram requires exactly one ack per callback query, success or not;
    /// `text`, when `Some`, is shown as a brief toast (e.g. an "expired"
    /// notice for a stale/forged nonce).
    async fn answer_callback(
        &self,
        _callback_query_id: &str,
        _text: Option<&str>,
    ) -> PlatformResult<()> {
        Ok(())
    }

    /// Stop the adapter (best-effort; graceful shutdown).
    async fn stop(&self) -> PlatformResult<()>;
}