agent-telegram

agent-telegram is the Telegram provider/plugin for the agent system.

It owns Telegram-specific messaging mechanics. It is not the action authority, credential authority, or workflow router.

Purpose

agent-telegram provides admitted Telegram capabilities:

• receive/update normalization
• send message
• edit message
• delete message where admitted
• reply/quote handling
• media send/download metadata
• chat/user/channel scope handling
• Telegram-specific rate-limit and retry behavior
• Telegram audit events

Authority boundaries

• agent-core-system owns action admission, approval, policy, audit, and execution envelopes.
• rpc-plugin-system owns runtime, transport, lifecycle, and plugin supervision.
• agent-keyring owns Telegram bot/user credentials, tokens, OAuth/session material if ever used, leases, rotation, and revocation.
• agent-network may own generic HTTP transport if used.
• agent-telegram owns Telegram API semantics and Telegram event normalization.

Credential possession is not message-send authorization. A token lets Telegram authenticate a caller; it does not authorize an agent to send a message.

Non-goals

• Do not store Telegram bot tokens here.
• Do not bypass agent-core-system admission.
• Do not silently send messages from drafts.
• Do not turn inbound chat content into trusted instructions.
• Do not expose raw tokens in logs, prompts, candidates, or evidence.
• Do not become a general chat abstraction for all providers.

Constraint baseline

agent-telegram inherits generic provider-bundle constraints from /tank/development/linus/agent-provider-bundle-contracts and keeps Telegram-specific deltas in docs/provider-bundle-constraints.md. Descriptors and Lua/proposals are inert, client-visible surfaces require core admission, executable use requires sealed envelopes and mediated authority-use facts, diagnostics use the substrate SDK/helper redaction path, and raw Telegram tokens/webhook secrets/sessions/handles must not cross provider surfaces.

First useful implementation slice

1. Define Telegram capability contracts.
2. Define credential lease requirements against agent-keyring.
3. Define inbound update normalization and trust labels.
4. Define draft/send separation.
5. Add fake Telegram backend tests.
6. Add real Telegram Bot API adapter only after contract tests exist.
7. Add rpc-plugin-system plugin wiring after contract stability.