Metadata-Version: 2.4
Name: kestrel-channel-telegram
Version: 0.1.0
Summary: Telegram channel for Kestrel agents — isolated-venv feature (Telegram Bot API).
License-Expression: MIT
Requires-Python: <3.15,>=3.11
Requires-Dist: kestrel-sovereign-sdk<1,>=0.29.0
Provides-Extra: service
Requires-Dist: httpx<1,>=0.27; extra == 'service'
Description-Content-Type: text/markdown

# kestrel-channel-telegram

Telegram channel for [Kestrel](https://github.com/KestrelSovereignAI/kestrel-sovereign)
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](https://t.me/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

```bash
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
