kestrel-channel-telegram 0.1.0

Telegram channel for Kestrel agents — isolated-venv feature (Telegram Bot API).

kestrel-channel-telegram

Telegram channel for Kestrel agents — an isolated-venv feature where the agent talks over a Telegram bot it owns (a Bot API token), not a device grafted onto a personal account.

Unlike the WhatsApp channel (a companion device linked to a personal number), Telegram gives the agent its own identity with almost no friction:

• Create a bot with @BotFather → you get a token. No phone number, no QR, no linked device.
• You DM the bot; the agent replies as the bot.
• Access is default-deny: with an empty allowed_senders the bot replies to no one. Send /start to the bot and it tells you your Telegram user id; add that id (or your @username) to allowed_senders to enable the conversation.

How it works

The package has two roles (same shape as kestrel-channel-whatsapp):

• Discovery marker TelegramFeature (SDK-only) — installed into the host.
• Transport service kestrel_channel_telegram.service — its only dep is httpx (the [service] extra), installed by the host loader into a per-agent isolated venv and run as the kestrel-telegram-service console script over the SDK stdio JSON-RPC contract.

The service:

• registers telegram_send, telegram_status, telegram_link tools;
• long-polls the Bot API (getUpdates) for inbound and emits channel.inbound for allowed senders (routed into ChannelFeature.handle_inbound);
• sends via sendMessage.

Config

key	meaning
enabled	turn the channel on/off
token	Bot API token from @BotFather (the agent's identity)
allowed_senders	Telegram numeric user ids or @usernames allowed to DM the agent. Empty = deny all.

Development

uv run --no-project --with "kestrel-sovereign-sdk>=0.29.0" --with httpx \
  --with pytest --with pytest-asyncio python -m pytest -q

Release

Bump version in pyproject.toml (+ uv.lock), tag vX.Y.Z; publish.yml verifies the tag matches and publishes to PyPI via OIDC trusted publishing (environment: pypi).

License

MIT