chore: fork @llblab/[email protected].0 as @evandrodevbr/oh-my-pi-telegram

Fork of upstream llblab/[email protected].0 (SHA afe09c5) repackaged as a drop-in extension for can1357/oh-my-pi (omp >= 16.5.2). Changes vs upstream: - Rename package: @llblab/pi-telegram -> @evandrodevbr/oh-my-pi-telegram - Bump version: 0.22.0 -> 0.22.0-evandro.1 - Update repository/homepage/bugs URLs to evandrodevbr - Add omp field in package.json (displayName + compatibleWith) - README: prepend 'Oh My Pi (omp) Compatibility' section with install commands, verified-components table, upstream lineage, and rationale - CHANGELOG: add '0.22.0-evandro.1' entry under Unreleased - docs/: rename @llblab/pi-telegram imports to @evandrodevbr/oh-my-pi-telegram - tests/public-api.test.ts: rename package import paths Gates re-run on the fork: - npm run typecheck -> tsc --noEmit (success) - npm test -> 1229 pass / 0 fail / 1 platform-only skip - npm run audit -> found 0 vulnerabilities - npm run pack:check -> evandrodevbr-oh-my-pi-telegram-0.22.0-evandro.1.tgz Verified: - omp install --link ./pi-telegram -> Linked OK - omp plugin list -> @evandrodevbr/[email protected].0-evandro.1 Upstream lineage: badlogic/pi-telegram -> llblab/pi-telegram (0.22.0) -> evandrodevbr/oh-my-pi-telegram (this fork)
2026-07-15 14:18:16 -03:00
commit d1d04001d0
@@ -0,0 +1,240 @@
+---
+name: telegram-bot
+description: Local Telegram Bot API reference lookup for bot transport, updates, forum topics, Rich Messages, media/files, callbacks, reactions, and Bot API method capability checks.
+metadata:
+  version: 1.0.0
+---
+
+# Telegram Bot API Reference Skill
+
+Use this skill when implementation or review depends on Telegram Bot API details: update shapes, method parameters, response objects, forum topic/thread support, Rich Messages, files/media, callback queries, reactions, or Bot API error semantics.
+
+The local reference is `api.md` in this skill directory. Treat it as vendored reference material: search it, cite the relevant anchor or section in reasoning, but do not reshape it for prose style.
+
+## Lookup Protocol
+
+Use the reference through multiple indexing dimensions. Do not rely on only one navigation mode.
+
+1. Start with the task-shaped index below to choose a likely region.
+2. Use line ranges when the region is known. Line references use an `L` prefix (`L393`, `L1000`) to make them visually distinct from anchors, ids, and limits. When calling `read`, drop the prefix: `L393` means `offset: 393`.
+3. Use substring search for exact fields, methods, and error text. Prefer exact symbols with `rg`, for example `rg "message_thread_id|sendChatAction|ForumTopic" .agents/skills/telegram-bot/api.md`.
+4. Use anchors as a semantic cross-check. Bot API method/type names usually map to Markdown anchors by lowercasing the name: `sendRichMessageDraft` -> `#sendrichmessagedraft`, `MessageReactionUpdated` -> `#messagereactionupdated`.
+5. Read only the relevant section around the match. If a section is large, read the first lines for the field table, then search inside the section for the exact field.
+6. Verify both sides of a feature:
+   - Inbound shape: `Update`, `Message`, `CallbackQuery`, reaction/update object, etc.
+   - Outbound capability: send/edit/delete/answer method parameters and return type.
+7. Distinguish documented capability from live-client behavior. If the reference says a parameter exists but client UX is uncertain, mark it as a live/manual verification item.
+8. Keep project docs concise. Link to this skill/reference for capability evidence; do not duplicate large Bot API tables in operator docs.
+
+## Reading By Line Range
+
+`api.md` is large vendored reference material. Use these line bands to jump directly to useful blocks:
+
+- `L1-L132` — Recent Bot API changelog entries; useful for new capabilities such as Rich Messages and guest mode.
+- `L133-L179` — Authorization, request formats, response envelope, and local Bot API server behavior.
+- `L180-L285` — Updates, `Update`, `getUpdates`, webhooks, and webhook info.
+- `L286-L318` — Start of available types, including `User`.
+- `L319-L392` — `Chat` and `ChatFullInfo`.
+- `L393-L614` — `Message`, message ids, inaccessible messages, entities, quotes, replies, origins, and reply parameters.
+- `L668-L805` — Core media message objects: photo, animation, audio, document, live photo, video, video note, voice.
+- `L1267-L1302` — Forum-topic service message objects.
+- `L1493-L1569` — Link preview, direct-message/topic helpers, profiles, and `File`.
+- `L1573-L1751` — Keyboards, inline keyboard buttons, callback queries, force replies.
+- `L1821-L1957` — Chat member updates, members, join requests, permissions.
+- `L2142-L2219` — Reaction types/counts, reaction updates, and `ForumTopic`.
+- `L2764-L2797` — Guest replies, prepared inline messages, response parameters.
+- `L2798-L2956` — `InputMedia*` variants and `InputFile`.
+- `L3054-L3124` — Sending files notes, colors, and inline mode object prelude.
+- `L3125-L3836` — Main send methods: `sendMessage`, formatting, media sends, albums, polls, drafts, chat actions, reactions.
+- `L3847-L4307` — File download, chat moderation/management, forum topic lifecycle.
+- `L4308-L4834` — Callback/guest answers, bot metadata, gifts/business/story/web app/prepared inline methods.
+- `L4835-L5020` — Updating/deleting messages and reaction deletion.
+- `L5021-L5242` — Stickers.
+- `L5243-L6116` — Rich Messages formatting, send/draft methods, `RichText*`, and `RichBlock*`.
+- `L6117-L6662` — Inline mode, inline query answers/results, and `InputMessageContent` variants.
+- `L6663-L7054` — Payments and stars.
+- `L7055-L7230` — Telegram Passport.
+- `L7231-L7306` — Games.
+
+For exact section boundaries, run:
+
+```bash
+rg -n "^(###|####) " .agents/skills/telegram-bot/api.md
+```
+
+## Freshness-First Lens
+
+The highest-value use of this skill is not generic Telegram bot knowledge. Models often already know older Bot API concepts. The local `api.md` is most valuable for **new or recently changed Bot API surface** that may be absent, stale, or hallucinated in model training data.
+
+Before relying on prior knowledge, check the freshness layer when work touches newly evolving areas such as Rich Messages, guest mode, managed bots, forum/thread behavior, reactions, drafts, business/gift/story APIs, paid media, or new update fields.
+
+### Freshness protocol
+
+1. Read the recent changelog first: `L1-L132` (`offset: 1, limit: 132`).
+2. Extract the exact new symbols mentioned there: method names, class names, fields, parameters.
+3. Search each symbol in the full reference before designing code: `rg -n "sendRichMessageDraft|guest_query_id|message_thread_id" .agents/skills/telegram-bot/api.md`.
+4. Compare old intuition against the local reference. If they differ, trust `api.md` and note the delta.
+5. When adding support for a fresh symbol, verify all three surfaces when applicable:
+   - Changelog mention: what changed and in which Bot API version.
+   - Type/method definition: exact field/parameter shape.
+   - Runtime route: which `Update` or method response can carry it.
+6. Treat unobserved client behavior as live-gated even when the Bot API surface is documented.
+
+### Recent-surface index
+
+- `L1-L35` — Bot API 10.1, Rich Messages, join request queries, poll media links.
+- `L36-L91` — Bot API 10.0, guest mode, reaction deletion methods, live photos, managed bot access settings, empty drafts.
+- `L92-L132` — Bot API 9.6, managed bots, prepared keyboard buttons, poll/checklist/date-time changes.
+
+Use this lens when a task asks “does Telegram support X now?”, “why is this update field unknown?”, “can we use this new method?”, or when a capability sounds newer than common bot knowledge.
+
+## Task-Oriented Lookup Recipes
+
+Use these recipes when the user asks a product/runtime question rather than naming an exact Bot API symbol.
+
+### Preserve forum topic/thread routing
+
+1. Search: `rg -n "message_thread_id|is_topic_message|ForumTopic" .agents/skills/telegram-bot/api.md`.
+2. Read `Message`: `L393-L532` (`offset: 393, limit: 140`).
+3. Read forum topic objects: `L1267-L1306` and `L2142-L2231`.
+4. Read relevant outbound methods: `sendMessage` at `L3142`, media sends at `L3385-L3630`, drafts/actions at `L3778-L3805`, Rich sends at `L5545-L5574`.
+5. Treat missing thread metadata on secondary update types as a reason to use stored message ownership rather than inventing fields.
+
+### Route callbacks from inline buttons
+
+1. Read inline keyboard/button types: `L1670-L1739`.
+2. Read `CallbackQuery`: `L1735-L1759`.
+3. Read `answerCallbackQuery`: `L4308-L4327`.
+4. Cross-check whether callback `message` has enough chat/thread metadata; if not, join with local message ownership.
+
+### Handle reactions safely
+
+1. Read reaction types and updates: `L2142-L2221`.
+2. Search: `rg -n "message_reaction|allowed_updates|deleteMessageReaction|setMessageReaction" .agents/skills/telegram-bot/api.md`.
+3. Read `getUpdates` allowed updates: `L220-L234`.
+4. Read reaction methods: `L3806-L3825` and `L5000-L5021`.
+5. Check admin/allowed-update requirements before assuming reactions arrive.
+
+### Send or download files/media
+
+1. Read upload/download contracts: `L2953-L2977` and `L3847-L3858`.
+2. Read local Bot API server limits: `L163-L179`.
+3. Read the concrete send method: photos `L3385`, documents `L3462`, voice `L3545`, albums `L3614`, stickers `L5082`.
+4. For inbound attachments, map `Message` media fields to `File`/`getFile` before modeling download behavior.
+
+### Use Rich Messages and drafts
+
+1. Read Rich Message overview and formatting examples: `L5243-L5352`.
+2. Read send/draft methods: `L5545-L5574`.
+3. Read `RichText`/`RichBlock` unions: `L5575-L5619` and `L5880-L5924`.
+4. Search for the exact primitive: `rg -n "RichBlockThinking|RichBlockMathematicalExpression|RichBlockPreformatted|RichBlockDetails" .agents/skills/telegram-bot/api.md`.
+5. Mark client rendering/draft UX as live verification unless already observed.
+
+### Answer guest or inline queries
+
+1. Read guest message fields on `Message`: `L393-L532`, then search `guest_query_id`.
+2. Read `SentGuestMessage`: `L2764-L2778`.
+3. Read `answerGuestQuery`: `L4322-L4331`.
+4. For inline mode, read `L6117-L6186` and `InputMessageContent` at `L6553`.
+
+## Cross-Cutting Field Matrix
+
+| Field/capability | Read first | Then verify on methods |
+| --- | --- | --- |
+| `message_thread_id` | `Message` `L393-L514`, `ForumTopic` `L2210-L2219` | `sendMessage`, media sends, `sendMediaGroup`, `sendMessageDraft`, `sendChatAction`, Rich sends/drafts |
+| `reply_parameters` | `ReplyParameters` `L600-L615` | Send/copy/forward methods that attach replies |
+| `reply_markup` | `InlineKeyboardMarkup` `L1670-L1677` | Send/edit methods and callback routing |
+| `rich_message` | `Message` `L393-L514`, `RichMessage` `L5525-L5533` | `sendRichMessage`, `sendRichMessageDraft`, `editMessageText` |
+| `guest_query_id` | `Message` `L393-L514`, `SentGuestMessage` `L2764-L2771` | `answerGuestQuery` |
+| `allowed_updates` | `getUpdates` `L220-L234`, `setWebhook` `L235-L257` | Reaction/chat-member update assumptions |
+| File id/path | `File` `L1560-L1569`, `InputFile` `L2953-L2956` | `getFile`, concrete send methods, local Bot API server limits |
+| Reactions | `ReactionType*` / `MessageReaction*` `L2142-L2209` | `setMessageReaction`, `deleteMessageReaction`, `deleteAllMessageReactions` |
+
+## Risk And Live-Verification Index
+
+Treat these as high-friction zones where the reference is necessary but may not be sufficient:
+
+- Polling/webhook exclusivity: `getUpdates` cannot run while a webhook is set.
+- `allowed_updates`: reactions and chat-member style updates often require explicit opt-in and sometimes admin rights.
+- Forum topics: documented `message_thread_id` support does not prove every update shape carries thread context.
+- Deleted/stale topics: classify errors narrowly and keep live smoke coverage for actual Telegram error text.
+- Rich drafts: Bot API method existence does not settle per-client draft UX.
+- File transport: cloud Bot API and local Bot API server have materially different upload/download limits.
+- Callback/reaction routing: if an update lacks target metadata, prefer durable sent-message ownership over guessing.
+
+## Search Synonym Index
+
+- Topic/forum/thread: `ForumTopic`, `message_thread_id`, `is_topic_message`, `createForumTopic`.
+- Button/menu/callback: `InlineKeyboardMarkup`, `InlineKeyboardButton`, `CallbackQuery`, `answerCallbackQuery`, `callback_data`.
+- Attachment/file/download/upload: `InputFile`, `File`, `getFile`, `file_id`, `file_path`, `sendDocument`, `sendPhoto`.
+- Draft/streaming preview: `sendMessageDraft`, `sendRichMessageDraft`, `RichBlockThinking`.
+- Rich Markdown/native rendering: `RichMessage`, `InputRichMessage`, `RichText`, `RichBlock`, `sendRichMessage`.
+- Reaction/emoji shortcut: `ReactionType`, `MessageReactionUpdated`, `setMessageReaction`, `deleteMessageReaction`.
+- Guest/inline response: `guest_message`, `guest_query_id`, `answerGuestQuery`, `InlineQuery`, `InputMessageContent`.
+
+## Anchor And Topic Index
+
+### Transport And Request Basics
+
+- `#authorizing-your-bot` — Bot token basics.
+- `#making-requests` — HTTP methods, JSON/form/multipart request formats, response envelope.
+- `#using-a-local-bot-api-server` — Local server behavior, larger upload/download limits, local file paths.
+
+### Updates And Routing
+
+- `#getting-updates` — Long polling vs webhooks.
+- `#update` — Top-level inbound update union.
+- `#getupdates` — Long polling method and `allowed_updates`.
+- `#setwebhook` / `#deletewebhook` — Webhook setup and removal.
+- `#message` — Main message object; check `message_thread_id`, `is_topic_message`, media, `rich_message`, guest fields.
+- `#callbackquery` — Button callback payload and callback message metadata.
+- `#messagereactionupdated` / `#messagereactioncountupdated` — Reaction updates and their available routing fields.
+
+### Chats, Forums, And Thread Targets
+
+- `#chat` / `#chatfullinfo` — Chat shape, including forum-related fields.
+- `#forumtopic` — Forum topic response object.
+- `#createforumtopic` — Topic provisioning and returned `message_thread_id`.
+- `#editforumtopic`, `#closeforumtopic`, `#reopenforumtopic`, `#deleteforumtopic`, `#unpinallforumtopicmessages` — Topic lifecycle.
+- Search `message_thread_id` — Thread target support across send, edit, media, draft, and action methods.
+
+### Sending, Editing, Drafts, And Chat Actions
+
+- `#sendmessage` — Text messages and thread targeting.
+- `#editmessagetext` — Editing text/rich messages.
+- `#deletemessage` / `#deletemessages` — Deletion semantics.
+- `#sendchataction` — Typing/upload action support, including thread targeting.
+- `#sendmessagedraft` — Plain draft behavior.
+- `#sendrichmessage` / `#sendrichmessagedraft` — Native Rich Message send/streaming draft APIs.
+
+### Rich Messages
+
+- `#rich-messages` — Bot API changelog entry for Rich Messages.
+- `#richmessage` / `#inputrichmessage` / `#inputrichmessagecontent` — Rich message payload objects.
+- `#richblock` / `#richtext` — Rich block/text unions.
+- Search `RichBlockThinking`, `RichBlockMathematicalExpression`, `RichBlockPreformatted`, `RichBlockTable`, `RichBlockDetails` for specific rendering primitives.
+
+### Files, Media, And Albums
+
+- `#inputfile` — Upload contract.
+- `#getfile` — File download metadata.
+- `#sendphoto`, `#senddocument`, `#sendvoice`, `#sendaudio`, `#sendvideo`, `#sendanimation`, `#sendsticker` — Common media sends.
+- `#sendmediagroup` — Album/grouped media behavior.
+- Search `InputMedia` for per-media payload variants.
+
+### Buttons, Inline Mode, Guest Replies
+
+- `#inlinekeyboardmarkup` / `#inlinekeyboardbutton` — Inline button markup.
+- `#answercallbackquery` — Callback acknowledgement.
+- `#inlinequery`, `#answerinlinequery`, `#inputmessagecontent` — Inline mode.
+- `#answerguestquery` / `#sentguestmessage` — Guest message replies.
+
+### Errors And Edge Semantics
+
+- `#responseparameters` — Retry/migration hints in failed responses.
+- Search exact Telegram error text when modeling stale topic, deleted message, migration, or permission behavior.
+- Prefer narrow error classification in code; broad string matching should be justified and covered by tests.
+
+## Output Expectations
+
+When this skill informs a code or documentation change, summarize the Bot API evidence in one sentence and name the anchor or symbol used. Example: `Bot API evidence: sendChatAction accepts message_thread_id, so chat actions can preserve forum targets.`