telegram-bot

The telegram-bot is a bridge between a Telegram bot and the harness agent stack. It owns the Telegram UX — slash commands, model-picker keyboards, live message edits, and approval prompts — and delegates turn execution, streaming, and durability to harness, session-manager, and approval-gate. Inbound text becomes a harness::send turn; the assistant's output flows back as Telegram messages. It is not a general bot framework and exposes no scriptable "send a message" surface of its own.

Reach for it to put an existing harness agent in front of Telegram users. Prerequisites: the sibling stack installed (harness session-manager llm-router context-manager approval-gate) and a telegram-bot configuration entry with a bot_token. A model is chosen per chat through the /start picker or fixed with default_model; the agent only gets the tools you grant via functions_allow. Update ingress is either long-polling (default, no public URL) or an HTTPS webhook, and every config field hot-reloads.

When to Use

• Expose a harness agent to Telegram users with streaming replies and live edits.
• Let a chat user pick or switch models and steer or cancel a running turn from chat.
• Approve or reject held tool calls inline from Telegram (Approve / Reject / Approve always).
• Mirror a session's transcript into a chat at a configurable verbosity.

Boundaries

• No public "send arbitrary text to a chat" function. Output reaches a chat only as the rendered result of a harness turn on a session mapped to that chat.
• No scheduler, cron, or timer. The worker never fires delayed or proactive messages on its own — see Message flow for how a reminder is actually delivered.
• Renders output only for sessions it holds a chat_id ↔ session_id mapping for; a turn on an unrelated session produces nothing in Telegram.
• Turn execution, tool-calling, and approval policy live in harness and approval-gate; this worker is only the Telegram surface. Deploying it without the sibling stack is unsupported.

Functions

HTTP-triggered (operator/ingress only — not agent-callable):

• telegram-bot::webhook — receive a Telegram update in webhook mode and route commands, messages, and callback queries.
• telegram-bot::set-webhook — register the configured webhook URL with Telegram.

Internal bindings (auto-registered against sibling triggers; not called directly):

• telegram-bot::on-message-added — post each new assistant or function_result entry into the chat (from session::message-added).
• telegram-bot::on-message-updated — stream throttled assistant edits (from session::message-updated).
• telegram-bot::on-status-changed — show a typing indicator while the session is working (from session::status-changed).
• telegram-bot::on-turn-completed — finalize streaming, post the outcome toast, and drain the FIFO queue (from harness::turn-completed).
• telegram-bot::on-pending-created — show an inline approval keyboard for a held call (from approval::pending-created).
• telegram-bot::on-pending-resolved — clear the approval prompt once the call resolves (from approval::pending-resolved).
• telegram-bot::on-config-change — hot-reload configuration.

Message flow

The worker registers no trigger type for others to bind. It is a bidirectional bridge between one Telegram chat and one harness session, and that round-trip is the whole job.

Inbound: a Telegram update arrives by long-poll or webhook and lands in the telegram-bot::webhook handler. Slash commands are handled locally; any other text is sent to harness::send with the chat's session, the selected model, the composed system prompt (built-in Telegram channel context per channel_context plus the configured system_prompt, sent per system_prompt_mode), and the functions_allow policy. The first message in a chat mints the session id bot-side and persists a chat_id ↔ session_id mapping; later messages continue that session until the next /start.

Proactive outbound: the agent can reach the user out-of-band via telegram-bot::notify (session-scoped), e.g. a cron-bound reminder targeting this session.

Outbound: as the turn runs, session-manager, harness, and approval-gate emit events. The worker's bound handlers consume them and render into the originating chat — resolving which chat by looking the session up in the chat_id ↔ session_id mapping. Assistant text streams via message edits (or native drafts) and is finalized on harness::turn-completed.

Reminder round-trip: a user asking the bot to "remind me at 5pm" gets an immediate reply in the same turn — that is just the normal inbound-to-outbound path. The later notification is a second turn: when the time comes, something must call harness::send on that same chat-bound session_id, and its assistant output then streams back through the same bindings. Because this worker has no scheduler and no push API, the timing lives elsewhere (an external scheduler, cron, or another worker that holds the session_id); the bridge's only role is routing that session's output back to the chat.