From 503d29ffed29c941c1f0226cbfdbb49293924e38 Mon Sep 17 00:00:00 2001 From: Junyan Qin Date: Thu, 7 May 2026 18:44:05 +0800 Subject: [PATCH] docs: add eba adapter migration records --- docs/event-based-agents/adapters/00-index.md | 26 +++++ docs/event-based-agents/adapters/discord.md | 108 ++++++++++++++++++ docs/event-based-agents/adapters/telegram.md | 112 +++++++++++++++++++ 3 files changed, 246 insertions(+) create mode 100644 docs/event-based-agents/adapters/00-index.md create mode 100644 docs/event-based-agents/adapters/discord.md create mode 100644 docs/event-based-agents/adapters/telegram.md diff --git a/docs/event-based-agents/adapters/00-index.md b/docs/event-based-agents/adapters/00-index.md new file mode 100644 index 00000000..24417b0a --- /dev/null +++ b/docs/event-based-agents/adapters/00-index.md @@ -0,0 +1,26 @@ +# EBA Adapter Migration Records + +This directory records adapter-level migration details for the Event-Based Agents architecture. Each adapter document should be kept close to the implementation and must answer four questions: + +1. What changed in the adapter structure. +2. Which configuration fields are required. +3. Which events and APIs are supported. +4. What has been verified end to end. + +## Adapter Documents + +| Adapter | Status | Document | +|---------|--------|----------| +| Telegram | Migrated and live-tested | [Telegram](./telegram.md) | +| Discord | In progress | [Discord](./discord.md) | + +## Documentation Checklist + +When migrating a new adapter, add one document here with: + +- Configuration table matching the adapter manifest. +- Supported event list. +- Supported common API list. +- Supported `call_platform_api` action list. +- Known unsupported APIs and the reason. +- Live test notes, including platform, channel type, destructive operations, and residual risks. diff --git a/docs/event-based-agents/adapters/discord.md b/docs/event-based-agents/adapters/discord.md new file mode 100644 index 00000000..971dbd57 --- /dev/null +++ b/docs/event-based-agents/adapters/discord.md @@ -0,0 +1,108 @@ +# Discord EBA Adapter + +## Status + +Discord is currently being migrated from the legacy source adapter: + +```text +src/langbot/pkg/platform/sources/discord.py +src/langbot/pkg/platform/sources/discord.yaml +``` + +Target EBA directory: + +```text +src/langbot/pkg/platform/adapters/discord/ +├── adapter.py +├── api_impl.py +├── event_converter.py +├── manifest.yaml +├── message_converter.py +├── platform_api.py +├── types.py +└── voice.py +``` + +## Configuration + +| Field | Required | Default | Description | +|-------|----------|---------|-------------| +| `client_id` | Yes | `""` | Discord application client ID. | +| `token` | Yes | `""` | Discord bot token. | + +The bot needs gateway permissions and intents for the target test server. Message content intent is required for message-based EBA events. + +## Planned Events + +Initial EBA migration should support: + +- `message.received` +- `message.edited` +- `message.deleted` +- `message.reaction` +- `group.member_joined` +- `group.member_left` +- `bot.invited_to_group` +- `bot.removed_from_group` +- `platform.specific` + +Discord-specific events that do not map cleanly to common events should be surfaced as `platform.specific`. + +## Planned Common APIs + +| API | Expected Status | Notes | +|-----|-----------------|-------| +| `send_message` | Supported | Text plus attachment files. | +| `reply_message` | Supported | Uses Discord message references. | +| `edit_message` | Supported | Bot can edit its own messages. | +| `delete_message` | Supported | Requires message management permissions for non-bot messages. | +| `forward_message` | Emulated | Discord has no native forward API; copy content and attachments when possible. | +| `get_group_info` | Supported | Maps Discord guild/channel metadata into EBA group info depending on target ID. | +| `get_group_member_list` | Supported | Requires member cache or guild member fetch permissions. | +| `get_group_member_info` | Supported | Maps Discord roles/permissions into EBA member roles. | +| `get_user_info` | Supported | Uses Discord user fetch/cache. | +| `upload_file` | Not standalone | Discord uploads files as message attachments; standalone upload should raise `NotSupportedError` unless a storage-backed design is added. | +| `get_file_url` | Supported for attachment URLs | Discord attachment URLs are already downloadable URLs. | +| `mute_member` | Supported where possible | Prefer Discord timeout API for guild members. | +| `unmute_member` | Supported where possible | Clears timeout. | +| `kick_member` | Supported | Destructive; test only with a disposable account/bot. | +| `leave_group` | Supported | Bot leaves a guild; destructive and should run last. | +| `call_platform_api` | Supported | Discord-specific actions live here. | + +## Planned Platform-Specific APIs + +Initial actions to expose through `call_platform_api`: + +- `get_channel` +- `get_guild` +- `get_guild_channels` +- `get_guild_roles` +- `create_invite` +- `pin_message` +- `unpin_message` +- `add_reaction` +- `remove_reaction` +- `typing` + +Voice actions should stay Discord-specific: + +- `join_voice_channel` +- `leave_voice_channel` +- `get_voice_connection_status` +- `list_active_voice_connections` +- `get_voice_channel_info` + +## Live Test Plan + +Use the LangBot Discord server debug channel for end-to-end verification: + +1. Create or reuse a Discord bot application. +2. Invite it to the LangBot server with message, member, reaction, and moderation permissions needed by the test. +3. Run the Discord EBA adapter in standalone test mode. +4. Send a message in the debug channel and verify `message.received`. +5. Verify send/reply/edit/delete/forward message APIs. +6. Verify attachment/file URL behavior. +7. Verify guild/channel/member info APIs. +8. Verify platform-specific APIs such as typing, pin/unpin, invite, reaction. +9. Verify moderation APIs against a disposable target member if available. +10. Run destructive `leave_group` only at the very end or skip it when preserving the server membership matters. diff --git a/docs/event-based-agents/adapters/telegram.md b/docs/event-based-agents/adapters/telegram.md new file mode 100644 index 00000000..eed6fd10 --- /dev/null +++ b/docs/event-based-agents/adapters/telegram.md @@ -0,0 +1,112 @@ +# Telegram EBA Adapter + +## Status + +Telegram has been migrated to the EBA adapter directory: + +```text +src/langbot/pkg/platform/adapters/telegram/ +├── adapter.py +├── api_impl.py +├── event_converter.py +├── manifest.yaml +├── message_converter.py +├── platform_api.py +└── types.py +``` + +The adapter is registered as `telegram-eba`. + +## Configuration + +| Field | Required | Default | Description | +|-------|----------|---------|-------------| +| `token` | Yes | `""` | Telegram Bot API token from BotFather. | +| `markdown_card` | No | `true` | Whether to render Markdown card style replies. | +| `enable-stream-reply` | Yes | `false` | Whether to use Telegram streaming reply mode. | + +## Events + +Telegram declares these EBA events: + +- `message.received` +- `message.edited` +- `message.reaction` +- `group.member_joined` +- `group.member_left` +- `group.member_banned` +- `bot.invited_to_group` +- `bot.removed_from_group` +- `bot.muted` +- `bot.unmuted` +- `platform.specific` + +`platform.specific` is currently used for Telegram-only callback and chat-member update payloads that do not yet have a more specific common event type. + +## Common APIs + +| API | Status | Notes | +|-----|--------|-------| +| `send_message` | Supported | Supports text, image, file, and mixed message chains. | +| `reply_message` | Supported | Supports quoted replies through the original message event. | +| `edit_message` | Supported | Uses Telegram message editing APIs. | +| `delete_message` | Supported | Deletes messages where bot permissions allow it. | +| `forward_message` | Supported | Forwards a message between Telegram chats. | +| `get_group_info` | Supported | Uses Telegram chat metadata. | +| `get_group_member_list` | Supported | Telegram only exposes administrators through the Bot API; this returns the available member set. | +| `get_group_member_info` | Supported | Maps Telegram member status to EBA member roles. | +| `get_user_info` | Supported | Uses Telegram `get_chat` for user chat metadata. | +| `upload_file` | Not supported | Telegram has no standalone upload endpoint; files are uploaded as part of messages. The adapter raises `NotSupportedError`. | +| `get_file_url` | Supported | Returns the Bot API file URL. Test output redacts the bot token. | +| `mute_member` | Supported | Requires a supergroup and bot moderation permission. | +| `unmute_member` | Supported | Uses current `telegram.ChatPermissions` fields. | +| `kick_member` | Supported | Destructive; should only be run against disposable users/bots in tests. | +| `leave_group` | Supported | Destructive; should run at the end of a live test. | +| `call_platform_api` | Supported | See below. | + +## Platform-Specific APIs + +`call_platform_api(action, params)` supports: + +- `pin_message` +- `unpin_message` +- `unpin_all_messages` +- `get_chat_administrators` +- `set_chat_title` +- `set_chat_description` +- `get_chat_member_count` +- `send_chat_action` +- `create_chat_invite_link` +- `answer_callback_query` + +## Live Test Record + +The live probe is: + +```bash +uv run python tests/e2e/live_telegram_eba_probe.py --help +``` + +It supports private chat tests, group/supergroup tests, moderation tests, destructive tests, and a callback-only mode. + +Verified on May 7, 2026: + +- Private chat message APIs: send, reply, edit, delete, forward. +- Private chat media APIs: image/file sending and `get_file_url`. +- User API: `get_user_info`. +- Supergroup APIs: group info, member list, member info, administrators, member count, invite link. +- Supergroup mutation APIs: pin, unpin, unpin all, set title, restore title, set description, restore description. +- Moderation APIs: mute and unmute against a non-owner target bot. +- Destructive APIs: kick a disposable target bot, then make the test bot leave the test group. +- Event conversion observed for `message.received`, `group.member_banned`, `group.member_left`, `bot.removed_from_group`, and Telegram-specific chat-member updates. + +The test fixed one real compatibility issue: `unmute_member` previously used Telegram's removed `can_send_media_messages` permission field. It now uses the split media permission fields required by current `python-telegram-bot`. + +## Notes for Future Adapters + +Telegram is the reference implementation for: + +- Keeping platform-specific actions behind `call_platform_api`. +- Treating unsupported common APIs as explicit `NotSupportedError`. +- Marking destructive live test operations behind CLI flags. +- Redacting access tokens from live probe output.