Struct TelegramService 

pub struct TelegramService { /* private fields */ }

Coordinates the Telegram bot lifecycle with the Ralph event loop.

Manages startup, shutdown, message sending, and response waiting. Uses the host tokio runtime (from #[tokio::main]) for async operations.

Implementations

impl TelegramService

pub fn new( workspace_root: PathBuf, bot_token: Option<String>, timeout_secs: u64, loop_id: String, ) -> TelegramResult<Self>

Create a new TelegramService.

Resolves the bot token from config or RALPH_TELEGRAM_BOT_TOKEN env var.

pub fn workspace_root(&self) -> &PathBuf

Get a reference to the workspace root.

pub fn timeout_secs(&self) -> u64

Get the configured timeout in seconds.

pub fn bot_token_masked(&self) -> String

Get a reference to the bot token (masked for logging).

pub fn state_manager(&self) -> &StateManager

Get a reference to the state manager.

pub fn handler(&mut self) -> &mut MessageHandler

Get a mutable reference to the message handler.

pub fn loop_id(&self) -> &str

Get the loop ID this service is associated with.

pub fn shutdown_flag(&self) -> Arc<AtomicBool>

Returns a clone of the shutdown flag.

Signal handlers can set this flag to interrupt wait_for_response() without waiting for the full timeout.

pub fn start(&self) -> TelegramResult<()>

Start the Telegram service.

Spawns a background polling task on the host tokio runtime to receive incoming messages. Must be called from within a tokio runtime context.

pub fn stop(self)

Stop the Telegram service gracefully.

Signals the background polling task to shut down.

pub fn send_question(&self, payload: &str) -> TelegramResult<i32>

Send a question to the human via Telegram and store it as a pending question.

The question payload is extracted from the human.interact event. A pending question is stored in the state manager so that incoming replies can be routed back to the correct loop.

On send failure, retries up to 3 times with exponential backoff (1s, 2s, 4s). Returns the message ID of the sent Telegram message, or 0 if no chat ID is configured (question is logged but not sent).

pub fn send_checkin( &self, iteration: u32, elapsed: Duration, context: Option<&CheckinContext>, ) -> TelegramResult<i32>

Send a periodic check-in message via Telegram.

Loads the chat ID from state and sends a short status update so the human knows the loop is still running. Skips silently if no chat ID is configured. Returns Ok(0) when skipped, or the message ID on success.

When a CheckinContext is provided, the message includes richer details: current hat, task progress, and cumulative cost.

pub fn send_document( &self, file_path: &Path, caption: Option<&str>, ) -> TelegramResult<i32>

Send a document (file) to the human via Telegram.

Loads the chat ID from state and sends the file at file_path with an optional caption. Returns Ok(0) if no chat ID is configured.

pub fn send_photo( &self, file_path: &Path, caption: Option<&str>, ) -> TelegramResult<i32>

Send a photo to the human via Telegram.

Loads the chat ID from state and sends the image at file_path with an optional caption. Returns Ok(0) if no chat ID is configured.

pub fn wait_for_response( &self, events_path: &Path, ) -> TelegramResult<Option<String>>

Poll the events file for a human.response event, blocking until one arrives or the configured timeout expires.

Polls the given events_path every second for new lines containing "human.response". On response, removes the pending question and returns the response message. On timeout, removes the pending question and returns None.

Trait Implementations

impl Debug for TelegramService

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl RobotService for TelegramService

fn send_question(&self, payload: &str) -> Result<i32>

Send a question to the human and store it as pending.

fn wait_for_response(&self, events_path: &Path) -> Result<Option<String>>

Poll the events file for a human.response event.

fn send_checkin( &self, iteration: u32, elapsed: Duration, context: Option<&CheckinContext>, ) -> Result<i32>

Send a periodic check-in message.

fn timeout_secs(&self) -> u64

Get the configured response timeout in seconds.

fn shutdown_flag(&self) -> Arc<AtomicBool>

Get a clone of the shutdown flag for cooperative interruption.

fn stop(self: Box<Self>)

Stop the service gracefully.