bob-core 0.2.2

Core domain types and port traits for Bob 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

//! # Channel Abstraction
//!
//! Multi-endpoint channel interface for the Bob Agent Framework.
//!
//! A **channel** is the boundary between the outside world (user) and the
//! agent loop. Its only responsibility is receiving user input and delivering
//! agent output — no agent logic lives here.
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────┐       ┌────────────┐       ┌───────────┐
//! │  User   │ ───→  │  Channel   │ ───→  │ AgentLoop │
//! │         │ ←───  │ (trait)    │ ←───  │           │
//! └─────────┘       └────────────┘       └───────────┘
//! ```
//!
//! Concrete implementations live in adapter or binary crates:
//!
//! | Channel      | Scenario                              |
//! |-------------|---------------------------------------|
//! | CLI          | One-shot `run --prompt "..."`          |
//! | REPL         | Interactive terminal                   |
//! | Telegram Bot | Long-polling with ACL                  |
//! | Discord Bot  | Gateway-based with channel filtering  |

use serde::{Deserialize, Serialize};

/// Incoming message from a channel to the agent.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChannelMessage {
    /// Raw user text (may be a slash command or natural language).
    pub text: String,
    /// Session identifier for conversation continuity.
    pub session_id: String,
    /// Optional sender identifier (username, user-id, etc.).
    pub sender: Option<String>,
}

/// Outgoing agent response delivered back through the channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChannelOutput {
    /// Response text.
    pub text: String,
    /// Whether this output represents an error condition.
    pub is_error: bool,
}

/// Errors that can occur during channel I/O.
#[derive(Debug, thiserror::Error)]
pub enum ChannelError {
    /// Sending a message to the user failed.
    #[error("send failed: {0}")]
    SendFailed(String),
    /// The requested feature is not supported by this channel.
    #[error("not supported: {0}")]
    NotSupported(String),
    /// The channel has been closed (user disconnected, etc.).
    #[error("channel closed")]
    Closed,
}

/// Abstract channel for multi-endpoint agent interaction.
///
/// Each channel implementation handles the transport-specific details
/// of receiving user input and delivering agent output. The agent loop
/// is decoupled from any specific transport.
///
/// ## Implementing a Channel
///
/// ```rust,ignore
/// use bob_core::channel::{Channel, ChannelMessage, ChannelOutput, ChannelError};
///
/// struct MyTelegramChannel { /* ... */ }
///
/// #[async_trait::async_trait]
/// impl Channel for MyTelegramChannel {
///     async fn recv(&mut self) -> Option<ChannelMessage> {
///         // Poll Telegram API for new messages...
///     }
///
///     async fn send(&self, output: ChannelOutput) -> Result<(), ChannelError> {
///         // Send via Telegram Bot API...
///         Ok(())
///     }
/// }
/// ```
#[async_trait::async_trait]
pub trait Channel: Send {
    /// Receive the next user input message.
    ///
    /// Returns `None` when the channel is closed (e.g. user disconnected,
    /// stdin EOF, or graceful shutdown).
    async fn recv(&mut self) -> Option<ChannelMessage>;

    /// Send an agent response back to the user.
    async fn send(&self, output: ChannelOutput) -> Result<(), ChannelError>;
}