Crate ralph_telegram 

ralph-telegram

Telegram integration for human-in-the-loop orchestration in Ralph.

This crate provides bidirectional communication between AI agents and humans during orchestration loops via Telegram:

• AI → Human: Agents emit human.interact events; the bot sends questions to Telegram
• Human → AI: Humans reply or send proactive guidance via Telegram messages

Key Components

• StateManager — Persists chat ID, pending questions, and reply routing
• MessageHandler — Processes incoming messages and writes events to JSONL
• TelegramService — Lifecycle management for the bot within the event loop
• [error] — Error types for startup, send, and receive failures

Re-exports

pub use daemon::TelegramDaemon;

Modules

commands

daemon

Telegram daemon adapter.

Structs

CheckinContext

Additional context for enhanced check-in messages.

MessageHandler

Processes incoming Telegram messages and writes events to the correct loop’s events.jsonl.

PendingQuestion

A question sent to the human that is awaiting a response.

StateManager

Manages persistence of Telegram bot state to disk.

TelegramBot

Wraps a teloxide::Bot and provides formatted messaging for Ralph.

TelegramService

Coordinates the Telegram bot lifecycle with the Ralph event loop.

TelegramState

Persistent state for the Telegram bot, stored at .ralph/telegram-state.json.

Enums

TelegramError

Errors that can occur during Telegram bot operations.

Constants

BASE_RETRY_DELAY

Base delay for exponential backoff (1 second).

MAX_SEND_RETRIES

Maximum number of retry attempts for sending messages.

Traits

BotApi

Trait abstracting Telegram bot operations for testability.

Functions

escape_html

Escape special HTML characters for Telegram’s HTML parse mode.

markdown_to_telegram_html

Convert Ralph-generated markdown to Telegram HTML.

retry_with_backoff

Execute a fallible send operation with exponential backoff retry.

Type Aliases

TelegramResult

Result type alias for telegram operations.