feat: add pi telegram extension package

README.md

@@ -0,0 +1,135 @@
+# pi-telegram
+
+Telegram DM bridge for pi.
+
+## Install
+
+From git:
+
+```bash
+pi install git:github.com/badlogic/pi-telegram
+```
+
+Or for a single run:
+
+```bash
+pi -e git:github.com/badlogic/pi-telegram
+```
+
+## Configure
+
+### Telegram
+
+1. Open [@BotFather](https://t.me/BotFather)
+2. Run `/newbot`
+3. Pick a name and username
+4. Copy the bot token
+
+### pi
+
+Start pi, then run:
+
+```bash
+/telegram-setup
+```
+
+Paste the bot token when prompted.
+
+The extension stores config in:
+
+```text
+~/.pi/agent/telegram.json
+```
+
+## Connect a pi session
+
+The Telegram bridge is session-local. Connect it only in the pi session that should own the bot:
+
+```bash
+/telegram-connect
+```
+
+To stop polling in the current session:
+
+```bash
+/telegram-disconnect
+```
+
+Check status:
+
+```bash
+/telegram-status
+```
+
+## Pair your Telegram account
+
+After token setup and `/telegram-connect`:
+
+1. Open the DM with your bot in Telegram
+2. Send `/start`
+
+The first DM user becomes the allowed Telegram user for the bridge. The extension only accepts messages from that user.
+
+## Usage
+
+Chat with your bot in Telegram DMs.
+
+### Send text
+
+Send any message in the bot DM. It is forwarded into pi with a `[telegram]` prefix.
+
+### Send images and files
+
+Send images, albums, or files in the DM.
+
+The extension:
+- downloads them to `~/.pi/agent/tmp/telegram`
+- includes local file paths in the prompt
+- forwards inbound images as image inputs to pi
+
+### Ask for files back
+
+If you ask pi for a file or generated artifact, pi should call the `telegram_attach` tool. The extension then sends those files with the next Telegram reply.
+
+Examples:
+- `summarize this image`
+- `read this README and summarize it`
+- `write me a markdown file with the plan and send it back`
+- `generate a shell script and attach it`
+
+### Stop a run
+
+In Telegram, send:
+
+```text
+stop
+```
+
+or:
+
+```text
+/stop
+```
+
+That aborts the active pi turn.
+
+### Queue follow-ups
+
+If you send more Telegram messages while pi is busy, they are queued and processed in order.
+
+## Streaming
+
+The extension streams assistant text previews back to Telegram while pi is generating.
+
+It tries Telegram draft streaming first with `sendMessageDraft`. If that is not supported for your bot, it falls back to `sendMessage` plus `editMessageText`.
+
+## Notes
+
+- Only one pi session should be connected to the bot at a time
+- Replies are sent as normal Telegram messages, not quote-replies
+- Long replies are split below Telegram's 4096 character limit
+- Outbound files are sent via `telegram_attach`
+
+## License
+
+MIT

package.json

@@ -0,0 +1,26 @@
+{
+  "name": "pi-telegram",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Telegram DM bridge extension for pi",
+  "type": "module",
+  "keywords": ["pi-package", "pi", "telegram", "bot", "extension"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/badlogic/pi-telegram.git"
+  },
+  "homepage": "https://github.com/badlogic/pi-telegram",
+  "bugs": {
+    "url": "https://github.com/badlogic/pi-telegram/issues"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  }
+}