pi-telegram-notifier 0.1.3 → 0.1.5

package/README.md

@@ -12,7 +12,24 @@ export PI_TELEGRAM_BOT_TOKEN='your-bot-token'
 pi
 ```
 
-If Pi is already running, run `/reload` after installing the package (restart Pi if you just set the token). If you previously installed a local checkout, run `pi list`, then `pi remove /absolute/path/to/pi-telegram-notifier` to avoid loading both copies. To get future releases, run `pi update npm:pi-telegram-notifier`. In Pi run `/telegram-pair`. Within five minutes send **`/start <code>`** to your bot in a private Telegram chat using the displayed one-time code. The extension stores only the numeric chat ID in `~/.pi/agent/pi-telegram-notifier.json` (or `$PI_CODING_AGENT_DIR/pi-telegram-notifier.json`), with mode 0600. To switch chats, run `/telegram-pair` again; the existing chat stays paired if pairing fails. The bot needs to receive messages via `getUpdates` during pairing: a webhook or another updates consumer must be disconnected first. There is no always-on polling after pairing.
+### Update or reload Pi
+
+If Pi is already running, run `/reload` after installing the package (restart Pi if you just set the token). To update a published install later, run `pi update npm:pi-telegram-notifier`. If you previously installed a local checkout, run `pi list`, then `pi remove /absolute/path/to/pi-telegram-notifier` to avoid loading both copies.
+
+### Pair a private chat
+
+1. In Pi, run `/telegram-pair`.
+2. In a private chat, send the bot the displayed **`/start <code>`** within five minutes.
+
+During pairing, the bot must receive updates through `getUpdates`; disconnect any webhook or other updates consumer first. If pairing fails, the existing chat remains paired.
+
+### Check pairing status
+
+In Pi, run `/telegram-status` to see whether the bot token is configured and a private chat is paired. This reports saved local state; it does not check live Telegram connectivity.
+
+### Switch chats and pairing storage
+
+Run `/telegram-pair` again to switch chats. The extension stores only the numeric chat ID in `~/.pi/agent/pi-telegram-notifier.json` (or `$PI_CODING_AGENT_DIR/pi-telegram-notifier.json`), with mode 0600. Pairing uses `getUpdates` only during setup; there is no always-on polling afterward.
 
 **Privacy:** final agent responses and the device hostname are sent to Telegram. Responses can contain sensitive text; only use this package if that is acceptable for your projects and Telegram chat. Bot and provider tokens are not stored in the package or sent as message text. Telegram Bot API uses the bot token in the request URL; do not log outgoing URLs. Keep your shell environment and Pi credentials private. A lost or compromised Telegram bot token must be revoked with BotFather.
 

package/extensions/index.ts

@@ -2,28 +2,59 @@ import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { pairChat, saveChatId } from '#src/telegram';
+import { loadChatId, pairChat, saveChatId } from '#src/telegram';
 import { registerNotifications } from '#src/notification';
 
 const agentDir = () => process.env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
 
 export default function (pi: ExtensionAPI) {
   registerNotifications(pi, agentDir(), process.env.PI_TELEGRAM_BOT_TOKEN);
+  pi.registerCommand('telegram-status', {
+    description: 'Show the Telegram bot configuration and pairing status',
+    handler: async (_args, ctx) => {
+      const tokenConfigured = !!process.env.PI_TELEGRAM_BOT_TOKEN;
+      const paired = loadChatId(agentDir()) !== undefined;
+      ctx.ui.notify([
+        'Telegram connection',
+        '',
+        'Configuration',
+        `Bot token: ${tokenConfigured ? 'Configured' : 'Not configured'}`,
+        `Private chat: ${paired ? 'Paired' : 'Not paired'}`,
+        '',
+        'Connectivity',
+        'Live check: Not performed',
+        ...(!tokenConfigured || !paired ? [
+          '',
+          'Next steps',
+          ...(!tokenConfigured ? ['Set PI_TELEGRAM_BOT_TOKEN and restart Pi.'] : []),
+          ...(!paired ? ['Run /telegram-pair to pair a private chat.'] : []),
+        ] : []),
+      ].join('\n'), 'info');
+    },
+  });
   pi.registerCommand('telegram-pair', {
     description: 'Pair a private Telegram chat with this Pi installation',
     handler: async (_args, ctx) => {
       const token = process.env.PI_TELEGRAM_BOT_TOKEN;
       if (!token) {
-        ctx.ui.notify('Set PI_TELEGRAM_BOT_TOKEN before starting Pi', 'error');
+        ctx.ui.notify('Telegram pairing unavailable\n\nSet PI_TELEGRAM_BOT_TOKEN before starting Pi.', 'error');
         return;
       }
       const code = randomBytes(16).toString('hex');
-      ctx.ui.notify(`Send /start ${code} to your Telegram bot within 5 minutes`, 'info');
+      ctx.ui.notify([
+        'Pair Telegram',
+        '',
+        'In your private chat with the bot, send:',
+        '',
+        `/start ${code}`,
+        '',
+        'Code expires in 5 minutes.',
+      ].join('\n'), 'info');
       try {
         saveChatId(agentDir(), await pairChat(token, code));
-        ctx.ui.notify('Private Telegram chat paired', 'info');
+        ctx.ui.notify('Telegram paired\n\nPrivate chat linked successfully.', 'info');
       } catch (error) {
-        ctx.ui.notify(error instanceof Error ? error.message : 'Telegram pairing failed', 'error');
+        ctx.ui.notify(`Telegram pairing failed\n\n${error instanceof Error ? error.message : 'Telegram pairing failed'}`, 'error');
       }
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-telegram-notifier",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Telegram notifications for final Pi agent responses and provider balances",
   "type": "module",
   "license": "MIT",