open-agents-ai 0.187.582 → 0.187.584

package/README.md

@@ -3365,7 +3365,7 @@ All settings commands accept `--local` to save to project `.oa/settings.json` in
 
 `/platforms menu` opens a keyboard-driven connectivity surface for platform status and onboarding. The same surface is available through `/gateway menu`.
 
-Supported adapter IDs are `telegram`, `discord`, `slack`, `matrix`, and `webhook`. Telegram is wired into the existing bridge controls, so the menu can save the bot token, save the admin user ID, start the bridge, stop it, and show status. The other platform adapters expose the shared connector configuration surface: enable/disable, token environment variable, base URL or webhook URL, default target/channel/room, polling vs webhook mode, redacted config display, and status/health reporting.
+Supported adapter IDs are `telegram`, `discord`, `slack`, `matrix`, and `webhook`. Telegram is wired into the existing bridge controls, so the menu can save the bot token, save the admin user ID, set the interaction mode, start the bridge, stop it, and show status. The other platform adapters expose the shared connector configuration surface: enable/disable, token environment variable, base URL or webhook URL, default target/channel/room, polling vs webhook mode, redacted config display, and status/health reporting.
 
 Use environment variables for credentials:
 
@@ -3416,7 +3416,7 @@ The steering sub-agent uses the same model and backend as the main agent with `m
 
 <div align="right"><a href="#top">back to top</a></div>
 
-Connect the agent to a Telegram bot. Each incoming message spawns a dedicated sub-agent that handles the conversation independently — visible in the terminal waterfall alongside other agent activity.
+Connect the agent to a Telegram bot. Telegram can run in auto, chat, or action mode: conversational messages get rapid streamed replies in chat mode, while codebase/file/run requests use dedicated action sub-agents that are visible in the terminal waterfall alongside other agent activity.
 
 ```bash
 /telegram --key <token>     # Save bot token (persisted to .oa/settings.json)
@@ -3424,9 +3424,56 @@ Connect the agent to a Telegram bot. Each incoming message spawns a dedicated su
 /telegram                   # Toggle bridge on/off (uses saved key)
 /telegram status            # Show connection status + active sub-agents
 /telegram stop              # Disconnect and kill all sub-agents
+/telegram mode auto|chat|action # Set interaction routing profile
+/telegram auth              # Show a one-time TUI-only admin auth code
+/telegram auth cancel       # Cancel the pending admin auth code
+/telegram bot <username> <text>              # Send bot-to-bot message by @username
+/telegram poll <chat> <question> | <a> [| <b>] # Send a poll
+/telegram live-photo <chat> <live> <photo> [caption] # Send a live photo
+/telegram draft <chat_id> <draft_id> [text]  # Set or clear a message draft
+/telegram admins <chat> [--bots]             # List chat administrators
+/telegram personal <user_id> <limit>         # Fetch profile personal chat messages
+/telegram access get <managed_bot_user_id>   # Show managed-bot access restrictions
+/telegram access set <managed_bot_user_id> <restricted|open> [user_ids] # Configure access
+/telegram delete-reaction <chat> <msg> --user <id> # Delete a message reaction
+/telegram delete-reactions <chat> --user <id>      # Delete recent reactions
 ```
 
-The bot token and admin ID are persisted to project settings, so you only need to set them once. After that, bare `/telegram` toggles the bridge on and off like a service watchdog.
+The bot token, admin ID, and interaction mode are persisted to settings, so you only need to set them once. After that, bare `/telegram` toggles the bridge on and off like a service watchdog.
+
+### Telegram Interaction Modes
+
+Use `/telegram mode auto|chat|action` to control how inbound Telegram messages are routed:
+
+- **auto** — short greetings, quick questions, playful messages, and conversational turns use fast streamed chat replies; explicit codebase/file/command/run/test requests use action sub-agents.
+- **chat** — every non-command message gets a direct quick-chat completion with no tool loop. This is best for rapid back-and-forth conversation.
+- **action** — every non-command message runs through the Telegram sub-agent path with the configured tool policy.
+
+Telegram quick-chat views and action sub-agent views both appear as blue plane-labeled items in the systems header. Clicking one swaps the main scrollable window to that Telegram-only content buffer; press Esc to return to the primary view.
+
+### Telegram Admin Authentication
+
+Run `/telegram auth` in the TUI to generate a one-time six-digit code. The code is rendered only in the terminal and is not inserted into agent prompts or Telegram sub-agent context. From the Telegram account that should become admin, send:
+
+```text
+/auth <code>
+```
+
+On success, that Telegram user ID is saved as the admin user and future private-DM slash commands are passed through the same command handler as the local TUI. `/telegram auth cancel` invalidates a pending code.
+
+### Bot API 10.0 Features
+
+The Telegram bridge handles modern Bot API traffic directly:
+
+- **Guest Mode** — inbound `guest_message` updates are normalized into regular agent work and answered through `answerGuestQuery`, so users can interact from profile-surface guest chats before a normal bot DM exists.
+- **Command menu registration** — when the bridge starts, OA registers the local slash-command surface with Telegram via `setMyCommands`; Telegram-safe names such as `/full_send_bless` are mapped back to canonical TUI commands like `/full-send-bless` before execution.
+- **Bot-to-bot sends** — `/telegram bot <username> <text>` targets another bot by username using Telegram's supported bot-to-bot message subset.
+- **Managed bot access** — `/telegram access get|set` reads and configures managed-bot access restrictions by managed bot user ID.
+- **Polls and live photos** — incoming polls, poll media summaries, option media, country/member limits, and live photos are captured as first-class Telegram message context; `/telegram poll` and `/telegram live-photo` send the matching Bot API payloads.
+- **Direct-message channels** — direct-message channel/topic metadata is preserved on normalized Telegram messages for routing and future adapter logic.
+- **Drafts and profile chat reads** — `/telegram draft` can set or clear message drafts, and `/telegram personal <user_id> <limit>` fetches recent messages from a user's profile personal chat.
+- **Reactions/admin helpers** — `/telegram delete-reaction` removes a message reaction, `/telegram delete-reactions` removes recent reactions by a user/chat, and `/telegram admins <chat> [--bots]` can include bot administrators.
+- **TUI Telegram visibility** — Telegram quick-chat and action conversations register as blue plane-labeled views in the systems panel; clicking a view swaps the main scrollable window to that Telegram-only buffer, and the footer shows an active plane indicator while the bridge or Telegram work is active.
 
 ### Admin Slash Command Passthrough