hermes - 💡(How to fix) Fix Epic: Telegram Business assistant mode

Goal

Add official Telegram Business support to Hermes Agent so a Telegram bot connected to a user's Telegram Business account can receive incoming private-chat messages and help the owner reply from that connected Business account, using Telegram's business_connection_id flow.

In MVP, Hermes should generate owner-approved replies, not silent full auto-replies: inbound Business messages become isolated Hermes sessions; the owner receives a draft/approval prompt; pressing Send replies to the original Business chat via Telegram Bot API with the correct business_connection_id.

Official Telegram docs

• Telegram Business bot feature guide: https://core.telegram.org/bots/features#telegram-business
• Bot API BusinessConnection: https://core.telegram.org/bots/api#businessconnection
• Bot API Update business fields: https://core.telegram.org/bots/api#update
• Bot API Message.business_connection_id: https://core.telegram.org/bots/api#message
• Bot API sendMessage.business_connection_id: https://core.telegram.org/bots/api#sendmessage
• Bot API sendChatAction.business_connection_id: https://core.telegram.org/bots/api#sendchataction

Current state / gap

Hermes Telegram gateway currently starts polling with allowed_updates=Update.ALL_TYPES, and the installed python-telegram-bot version supports Telegram Business fields and business_connection_id parameters.

However, Hermes currently:

• handles update.message, not update.business_message;
• does not persist or inspect BusinessConnection.can_reply;
• does not carry business_connection_id through MessageEvent metadata/session routing;
• sends normal Telegram replies without business_connection_id;
• has no owner approval flow for Business replies.

Functional requirements

FR1: Activation model

Telegram controls capability; Hermes controls behavior.

• Do not require an additional telegram.business.enabled: false default switch.
• Treat the feature as available when Telegram sends an active BusinessConnection with is_enabled == true.
• Treat replying as allowed only when Telegram reports can_reply == true.
• Provide a behavior mode / kill-switch such as telegram.business.mode: ignore|notify|draft|approve|auto.
• Default behavior should be safe but useful: draft or approve, not ignore.

FR2: Business connection handling

Hermes must process and store enough state from business_connection updates:

• business_connection_id
• is_enabled
• can_reply
• Business account/user id if available
• last update time

If a connection is disabled or loses reply permission, Hermes must stop attempting Business sends for it.

FR3: Inbound Business messages

Hermes must process:

• business_message
• edited_business_message at least enough not to crash; full edit semantics can be follow-up work
• deleted_business_messages at least enough not to crash; full deletion semantics can be follow-up work

For MVP, focus on new text business_message updates.

FR4: Session isolation

Business chats must not share history/session keys with normal bot DMs, groups, or forum topics.

A logical session key should include:

• platform: Telegram
• source kind: Business
• business_connection_id
• Business chat id / contact chat id

Example shape:

telegram:business:<business_connection_id>:chat:<chat_id>

FR5: Owner approval / draft flow

For MVP, inbound Business messages should create a draft or approval prompt for the owner.

The owner notification should include:

• contact/chat identity available from Telegram
• inbound message text
• generated draft reply
• clear action controls, at minimum Send and Ignore

The owner notification must be delivered only to the configured owner target/home DM, never to the source Business chat or a public group.

FR6: Business send path

When the owner approves a reply, Hermes must call Telegram Bot API send methods with the correct business_connection_id.

MVP must support:

• sendMessage(..., business_connection_id=...)
• sendChatAction(..., business_connection_id=...)

Normal Telegram sends must not accidentally include business_connection_id.

FR7: Safety policy

Auto-send should not be part of MVP. Future auto mode must degrade to approve/draft for sensitive cases such as:

• money transfers or payments
• 2FA / passwords / secrets
• medical, legal, or financial decisions
• emergencies or threats
• unknown contacts
• messages requiring the owner's personal commitment

FR8: Privacy / logs

• Business messages must never be mirrored into group chats by default.
• Avoid logging full private message content at INFO level.
• Session transcript storage behavior should be documented.

MVP scope

Implement only:

• Business connection state handling.
• New inbound text business_message handling.
• Business-specific MessageEvent/session metadata.
• Owner draft/approval prompt.
• Send approved text reply using business_connection_id.
• Typing indicator with business_connection_id.
• Unit tests for the above.
• User docs for Telegram Business setup and behavior.

Out of MVP:

• automatic replies without approval
• voice/media replies
• read receipts via readBusinessMessage
• message edits/deletes beyond safe no-crash handling
• story/checklist/gifts/business account management
• complex per-contact policy UI

Acceptance criteria

• Given an active Telegram BusinessConnection, Hermes stores connection state including can_reply.
• Given an inbound update.business_message, Hermes creates a Business-scoped message event/session instead of ignoring it.
• Given Business mode draft/approve, Hermes sends the owner a private draft/approval notification.
• Given owner approval and can_reply == true, Hermes sends a text reply to the original Business chat with the correct business_connection_id.
• Given can_reply == false or disabled connection, Hermes does not attempt Business sends and notifies/falls back safely.
• Normal Telegram group/topic/DM behavior remains unchanged.
• Tests prove business_connection_id is present only for Business sends and absent for normal sends.
• Docs link to the official Telegram Business/Bot API pages above.

Suggested Kanban decomposition for Pi agents

1. Research/spec worker: verify exact python-telegram-bot objects and write implementation notes.
2. Gateway event worker: implement BusinessConnection and business_message ingestion tests/code.
3. Session/routing worker: implement Business session isolation and metadata propagation.
4. Approval UI worker: implement owner draft/approval callback flow.
5. Send-path worker: propagate business_connection_id to sendMessage/sendChatAction only for Business sends.
6. Docs/tests/review worker: add user docs and run focused regression tests.

Each Pi worker should operate in an isolated worktree and end with a structured report. Hermes must independently inspect diffs and run tests before merging.