@bytesbrains/pi-telegram-bridge 1.1.6 → 1.2.0

package/README.md

@@ -1,45 +1,153 @@
 # pi-telegram-bridge
 
-Telegram bot bridge for pi agents — send messages, ask questions, and listen for human replies via Telegram.
+Telegram bot bridge for pi agents — send messages, ask questions, receive photos, and get a live project dashboard on "hi".
 
 ## Install
 
 ```bash
-pi install npm:@bytesbrains/pi-telegram-bridge
+pi install npm:@bytesbrains/pi-telegram-bridge@1.1.6
 ```
 
-## Configuration
+## Quick Setup
 
-Set the following environment variables:
+### 1. Create a bot with @BotFather
+
+Open Telegram and chat with [@BotFather](https://t.me/BotFather):
+
+```
+/newbot
+```
+
+Follow the prompts. You'll get a token like:
+
+```
+123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11
+```
+
+### 2. Get your Chat ID
+
+Send ANY message to your new bot on Telegram, then visit this URL in your browser:
+
+```
+https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
+```
+
+Look for `"chat":{"id":123456789}` in the response. That's your chat ID.
+
+> **For group chats:** Add the bot to a group, send a message mentioning the bot, then check the same URL. Use the group chat ID.
+
+### 3. Set environment variables
 
 ```bash
 export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11"
 export TELEGRAM_CHAT_ID="123456789"
 ```
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `TELEGRAM_BOT_TOKEN` | ✅ | Bot token from [@BotFather](https://t.me/BotFather) |
-| `TELEGRAM_CHAT_ID` | ✅ | Target chat ID (your personal chat or a group) |
+Add them to your shell profile (`~/.zshrc`, `~/.bashrc`) to persist across sessions.
+
+### 4. Verify
+
+Start pi and run `telegram_status()`. You should see:
+
+```
+Active. Bot: @your_bot_name (listener: 🟢 running)
+```
+
+## Environment Variables
+
+| Variable             | Required | Default                 | Description                                                     |
+| -------------------- | -------- | ----------------------- | --------------------------------------------------------------- |
+| `TELEGRAM_BOT_TOKEN` | ✅       | —                       | Bot token from @BotFather                                       |
+| `TELEGRAM_CHAT_ID`   | ✅       | —                       | Chat ID to send/receive messages                                |
+| `TELEGRAM_MENTION`   | ❌       | `@pi` (or bot username) | Only respond to messages containing this mention in group chats |
+
+### TELEGRAM_MENTION
+
+Controls which messages the agent responds to in **group chats**:
+
+```bash
+# Use a custom mention trigger
+export TELEGRAM_MENTION="@mybot"
+
+# Or let it auto-detect from the bot username
+export TELEGRAM_MENTION=""   # defaults to @bot_username
+```
+
+- **Private chat** (direct message to bot): All messages are treated as directed — no mention needed
+- **Group chat**: Only messages containing `@botname` are forwarded to the agent. Everything else is ignored.
+
+## Features
+
+### Status Dashboard
+
+Send `hi`, `/status`, or `status` to your bot on Telegram. It replies with a live project summary:
+
+```
+📊 pi-ext Status
+
+📋 Open Issues: 3
+   #1 telegram-bridge HTML parse crash
+   #5 status dashboard on hi message
+
+🔀 Open PRs: 2
+   ✅ #2 fix(telegram-bridge): escape HTML entities
+
+🔧 Last CI: ⏳ queued (5 recent runs)
+```
+
+### Photo Support
+
+**Send photos to the agent:** Send any photo to the bot — the agent downloads it and can use `read()` to view it. Add a caption for context:
+
+> 📸 Photo: `login page broken, 404 in console`
+
+**Send photos from the agent:** Use `telegram_send_photo()` to share screenshots or diagrams:
+
+```
+telegram_send_photo(photoPath="/tmp/screenshot.png", caption="Build output")
+```
+
+### @Mention Support
+
+In group chats, the bot only responds to messages that mention it. This lets humans talk freely without triggering the agent.
+
+| Chat type | Message                  | Bot responds?                            |
+| --------- | ------------------------ | ---------------------------------------- |
+| Private   | `hi`                     | ✅                                       |
+| Private   | `@pi what's the status?` | ✅ (mention stripped)                    |
+| Group     | `hi`                     | ❌                                       |
+| Group     | `@pi what's the status?` | ✅ (agent receives `what's the status?`) |
 
 ## Tools
 
 ### telegram_listen
 
-Check for new inbound messages from the human.
+Check for new inbound messages (text and photos) from the human.
 
 ```
 telegram_listen()
 ```
 
+Returns photo paths and captions if a photo was received.
+
 ### telegram_send
 
-Send a one-way message. Use for status updates and progress reports.
+Send a one-way text message.
 
 ```
 telegram_send(message="Build completed successfully ✅")
 ```
 
+### telegram_send_photo
+
+Send a photo — supports local file paths and remote URLs.
+
+```
+telegram_send_photo(photoPath="/tmp/screenshot.png")
+telegram_send_photo(photoPath="/tmp/screenshot.png", caption="Error in console")
+telegram_send_photo(photoPath="https://example.com/image.jpg")
+```
+
 ### telegram_ask
 
 Ask a question with inline keyboard options and **wait** for a human reply. Blocks until answered or timeout (default 30 min).
@@ -87,6 +195,7 @@ telegram_override(
 | `timedOut` | `boolean` | Whether the request timed out |
 
 **Agent workflow:**
+
 1. Agent gets blocked by supervisor
 2. Calls `telegram_override(command, reason, context)`
 3. Checks `details.action`:
@@ -103,33 +212,11 @@ Check if the bridge is configured and running.
 telegram_status()
 ```
 
-## Background Listener
-
-The extension starts a background listener on session start that polls for incoming Telegram messages. Any non-bot text message in the configured chat is forwarded to the agent as a user message. The agent responds with a confirmation.
-
-The listener runs automatically — no manual setup needed.
-
-## How It Works
-
-1. **Session start**: The bridge restores the last processed update ID from session state and starts polling
-2. **Inbound messages**: Non-bot text messages in the configured chat are forwarded to the agent
-3. **Session end**: The listener stops cleanly on session shutdown
-4. **Update ID is persisted** across sessions to avoid processing duplicate messages
-
-## Get a Bot Token
-
-1. Open Telegram and chat with [@BotFather](https://t.me/BotFather)
-2. Send `/newbot` and follow the prompts
-3. Copy the token and set `TELEGRAM_BOT_TOKEN`
-4. Send a message to your bot, then visit:
-   `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
-5. Copy the `chat.id` from the response and set `TELEGRAM_CHAT_ID`
-
 ## Requirements
 
 - Node.js >= 18
-- A Telegram bot token
-- A chat ID to send/receive messages
+- A Telegram bot token (from @BotFather)
+- A chat ID
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bytesbrains/pi-telegram-bridge",
-  "version": "1.1.6",
-  "description": "Telegram bot bridge for pi agents \u2014 send messages, ask questions, and listen for human replies via Telegram.",
+  "version": "1.2.0",
+  "description": "Telegram bot bridge for pi agents — send messages, ask questions, and listen for human replies via Telegram.",
   "keywords": [
     "pi-package",
     "pi-extension",

package/src/__tests__/helpers.test.ts

@@ -440,7 +440,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith("Hello agent!");
+    expect(onMessage).toHaveBeenCalledWith('Hello agent!', '987654321');
     expect(onUpdateId).toHaveBeenCalledWith(100);
   }, 15000);
 
@@ -618,7 +618,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith("recovered");
+    expect(onMessage).toHaveBeenCalledWith('recovered', '987654321');
   }, 20000);
 
   it("handles network errors with retry", async () => {
@@ -663,7 +663,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith("eventually");
+    expect(onMessage).toHaveBeenCalledWith('eventually', '987654321');
   }, 25000);
 
   it("stops gracefully when aborted immediately", async () => {
@@ -734,7 +734,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith("after not-ok");
+    expect(onMessage).toHaveBeenCalledWith('after not-ok', '987654321');
   }, 20000);
 
   it("ignores messages without text field", async () => {

package/src/helpers.ts

@@ -57,7 +57,11 @@ export async function sendMsg(
 	} catch (e: unknown) {
 		// Retry without parse_mode if formatting caused a 400 parse error
 		const msg = e instanceof Error ? e.message : String(e);
-		if (parseMode && msg.includes("400") && (msg.includes("parse") || msg.includes("entity"))) {
+		if (
+			parseMode &&
+			msg.includes("400") &&
+			(msg.includes("parse") || msg.includes("entity"))
+		) {
 			delete body.parse_mode;
 			const r2 = (await telegramApi("sendMessage", body)) as {
 				ok: boolean;
@@ -66,7 +70,8 @@ export async function sendMsg(
 			return r2.result.message_id;
 		}
 		throw e;
-	}}
+	}
+}
 
 // ── Photo / File Support ────────────────────────────────────────────
 
@@ -77,14 +82,11 @@ export async function sendMsg(
 export async function getFileUrl(fileId: string): Promise<string | null> {
 	const token = getToken();
 	try {
-		const res = await fetch(
-			`${BASE_URL}${token}/getFile`,
-			{
-				method: "POST",
-				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({ file_id: fileId }),
-			},
-		);
+		const res = await fetch(`${BASE_URL}${token}/getFile`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ file_id: fileId }),
+		});
 		if (!res.ok) return null;
 		const data = (await res.json()) as {
 			ok: boolean;
@@ -102,7 +104,10 @@ export async function getFileUrl(fileId: string): Promise<string | null> {
  * Returns the file path on success, null on failure.
  * Creates parent directories automatically.
  */
-export async function downloadFile(fileId: string, destPath: string): Promise<string | null> {
+export async function downloadFile(
+	fileId: string,
+	destPath: string,
+): Promise<string | null> {
 	try {
 		const fileUrl = await getFileUrl(fileId);
 		if (!fileUrl) return null;
@@ -162,7 +167,11 @@ export async function sendPhoto(
 	if (!res.ok) {
 		const errText = await res.text();
 		// Retry without caption if parse_mode caused a 400
-		if (caption && res.status === 400 && (errText.includes("parse") || errText.includes("entity"))) {
+		if (
+			caption &&
+			res.status === 400 &&
+			(errText.includes("parse") || errText.includes("entity"))
+		) {
 			return sendPhoto(photoPath);
 		}
 		throw new Error(`sendPhoto failed: ${res.status} ${errText}`);
@@ -308,7 +317,7 @@ export async function pollUpdates(
 	botId: number | null,
 	lastUpdateId: number,
 	signal: AbortSignal,
-	onMessage: (text: string) => void,
+	onMessage: (text: string, msgChatId: string) => void,
 	onPhoto: (photoId: string, caption?: string) => void,
 	onUpdateId: (id: number) => void,
 ): Promise<void> {
@@ -333,7 +342,12 @@ export async function pollUpdates(
 						chat: { id: number };
 						from?: { id: number; is_bot?: boolean };
 						text?: string;
-						photo?: Array<{ file_id: string; file_unique_id: string; width: number; height: number }>;
+						photo?: Array<{
+							file_id: string;
+							file_unique_id: string;
+							width: number;
+							height: number;
+						}>;
 						caption?: string;
 					};
 					callback_query?: unknown;
@@ -349,10 +363,7 @@ export async function pollUpdates(
 				// Skip callback queries (handled by telegram_ask)
 				if (u.callback_query) continue;
 				// Process messages from the configured chat, not from our bot
-				if (
-					u.message &&
-					String(u.message.chat.id) === chatId
-				) {
+				if (u.message && String(u.message.chat.id) === chatId) {
 					if (u.message.from?.is_bot || u.message.from?.id === botId) {
 						continue;
 					}
@@ -364,7 +375,7 @@ export async function pollUpdates(
 					}
 					// Text message
 					if (u.message.text) {
-						onMessage(u.message.text);
+						onMessage(u.message.text, String(u.message.chat.id));
 					}
 				}
 			}

package/src/index.ts

@@ -37,6 +37,144 @@ export default function telegramBridge(pi: ExtensionAPI) {
 	let botId: number | null = null;
 	let listenerAbort: AbortController | null = null;
 	let lastUpdateId = 0;
+	let mentionTrigger = "@pi"; // configurable via TELEGRAM_MENTION env var
+	const sessionStartTime = Date.now();
+	let messageCount = 0;
+
+	// ── Mention support ────────────────────────────────────────────
+
+	async function resolveMentionTrigger(): Promise<string> {
+		// 1. Explicit env var overrides everything
+		const envMention = process.env.TELEGRAM_MENTION;
+		if (envMention)
+			return envMention.startsWith("@") ? envMention : "@" + envMention;
+		// 2. Try bot username from getMe
+		try {
+			const r = (await telegramApi("getMe", {})) as {
+				result: { username: string };
+			};
+			if (r.result?.username) return "@" + r.result.username;
+		} catch {
+			/* fall through */
+		}
+		return "@pi";
+	}
+
+	/** Strip mention from message text and return cleaned text + whether it was mentioned. */
+	function checkMention(
+		text: string,
+		isPrivateChat: boolean,
+	): { mentioned: boolean; cleanedText: string } {
+		if (isPrivateChat) return { mentioned: true, cleanedText: text };
+		const trigger = mentionTrigger.slice(1).toLowerCase(); // strip @
+		const patterns = [
+			new RegExp(`@${trigger}\\b`, "i"), // @pi at start or middle
+			new RegExp(`^${trigger}\\b`, "i"), // pi at start (no @)
+		];
+		for (const re of patterns) {
+			if (re.test(text)) {
+				const cleaned = text.replace(re, "").trim();
+				return { mentioned: true, cleanedText: cleaned || text };
+			}
+		}
+		return { mentioned: false, cleanedText: text };
+	}
+
+	// ── Dashboard helper ────────────────────────────────────────────
+
+	async function sendDashboard() {
+		const token = getToken();
+		const giteaToken = process.env.GITEA_TOKEN || process.env.GIT_TOKEN || "";
+		const apiBase = "http://127.0.0.1:3001/api/v1/repos/factory/pi-ext";
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+		};
+		if (giteaToken) headers["Authorization"] = `token ${giteaToken}`;
+
+		try {
+			const [issuesR, prsR, runsR] = await Promise.all([
+				fetch(`${apiBase}/issues?state=open&limit=10`, { headers })
+					.then((r) => r.json())
+					.catch(() => []),
+				fetch(`${apiBase}/pulls?state=open&limit=10`, { headers })
+					.then((r) => r.json())
+					.catch(() => []),
+				fetch(`${apiBase}/actions/runs?limit=3`, { headers })
+					.then((r) => r.json())
+					.catch(() => ({ workflow_runs: [] })),
+			]);
+
+			const issues = Array.isArray(issuesR) ? issuesR : [];
+			const prs = Array.isArray(prsR) ? prsR : [];
+			const runs = (runsR as any).workflow_runs ?? [];
+
+			const lines: string[] = [];
+			lines.push("📊 <b>pi-ext Status</b>");
+			lines.push("");
+
+			// Open issues
+			lines.push(`📋 <b>Open Issues:</b> ${issues.length}`);
+			if (issues.length > 0) {
+				for (const i of (issues as any[]).slice(0, 5)) {
+					const labels = i.labels?.length
+						? ` [${i.labels.map((l: any) => l.name).join(", ")}]`
+						: "";
+					lines.push(`   #${i.number} ${i.title.slice(0, 60)}${labels}`);
+				}
+			} else {
+				lines.push("   (none)");
+			}
+			lines.push("");
+
+			// Open PRs
+			lines.push(`🔀 <b>Open PRs:</b> ${prs.length}`);
+			if (prs.length > 0) {
+				for (const p of (prs as any[]).slice(0, 5)) {
+					const mergeIcon = p.mergeable ? "✅" : "❌";
+					lines.push(`   ${mergeIcon} #${p.number} ${p.title.slice(0, 55)}`);
+				}
+			} else {
+				lines.push("   (none)");
+			}
+			lines.push("");
+
+			// CI status
+			if (runs.length > 0) {
+				const latest = runs[0];
+				const statusIcon =
+					latest.status === "success"
+						? "✅"
+						: latest.status === "failure"
+							? "❌"
+							: latest.status === "running"
+								? "🔄"
+								: "⏳";
+				lines.push(
+					`🔧 <b>Last CI:</b> ${statusIcon} ${latest.status} (${runs.length} recent runs)`,
+				);
+			} else {
+				lines.push("🔧 <b>Last CI:</b> no runs");
+			}
+			lines.push("");
+
+			// Session metrics
+			const uptimeMin = Math.floor((Date.now() - sessionStartTime) / 60000);
+			const uptimeStr =
+				uptimeMin < 60
+					? `${uptimeMin}m`
+					: `${Math.floor(uptimeMin / 60)}h ${uptimeMin % 60}m`;
+			lines.push("🤖 <b>Session</b>");
+			lines.push(`   Uptime: ${uptimeStr}`);
+			lines.push(`   Messages: ${messageCount}`);
+			lines.push(`   Mention: ${mentionTrigger}`);
+
+			await sendMsg(lines.join("\n"), undefined, "HTML");
+		} catch {
+			await sendMsg(
+				"⚠️ Could not fetch project dashboard. Gitea may be unreachable.",
+			);
+		}
+	}
 
 	// ── Session lifecycle ───────────────────────────────────────────
 
@@ -52,6 +190,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 			}
 		}
 		// Start background listener
+		mentionTrigger = await resolveMentionTrigger();
 		startListener();
 	});
 
@@ -89,11 +228,21 @@ export default function telegramBridge(pi: ExtensionAPI) {
 			botId,
 			lastUpdateId,
 			signal,
-			// onMessage: forward text or photo to pi as user message
-			async (text: string) => {
-				pi.sendUserMessage(text);
+			// onMessage: forward to pi (with mention check in groups), or dashboard on "hi"
+			async (text: string, msgChatId: string) => {
+				const isPrivate = msgChatId === chatId;
+				const { mentioned, cleanedText } = checkMention(text, isPrivate);
+				if (!mentioned) return; // ignore unmentioned messages in groups
+
+				const trimmed = cleanedText.trim().toLowerCase();
+				if (trimmed === "hi" || trimmed === "/status" || trimmed === "status") {
+					await sendDashboard();
+					return;
+				}
+				messageCount++;
+				pi.sendUserMessage(cleanedText);
 				await sendMsg(
-					`👂 Got it! Working on: _${text.slice(0, 100)}_`,
+					`👂 Got it! Working on: _${cleanedText.slice(0, 100)}_`,
 					undefined,
 					"Markdown",
 				);
@@ -111,8 +260,12 @@ export default function telegramBridge(pi: ExtensionAPI) {
 					);
 					await sendMsg("📸 Photo received! Processing...");
 				} else {
-					pi.sendUserMessage("📸 Photo received from Telegram but could not be downloaded.");
-					await sendMsg("⚠️ Could not download your photo. Please check the bot configuration.");
+					pi.sendUserMessage(
+						"📸 Photo received from Telegram but could not be downloaded.",
+					);
+					await sendMsg(
+						"⚠️ Could not download your photo. Please check the bot configuration.",
+					);
 				}
 			},
 			// onUpdateId: persist offset
@@ -177,38 +330,53 @@ export default function telegramBridge(pi: ExtensionAPI) {
 					lastUpdateId = u.update_id;
 					pi.appendEntry("tg-last-update", { update_id: lastUpdateId });
 					if (u.callback_query) continue;
-					if (
-						u.message &&
-						String(u.message.chat.id) === chatId
-					) {
+					if (u.message && String(u.message.chat.id) === chatId) {
 						if (u.message.from?.is_bot || u.message.from?.id === botId)
 							continue;
 						// Photo message
 						if (u.message.photo && u.message.photo.length > 0) {
-							const photoId = u.message.photo[u.message.photo.length - 1].file_id;
+							const photoId =
+								u.message.photo[u.message.photo.length - 1].file_id;
 							const caption = u.message.caption || "";
 							const timestamp = Date.now();
 							const fsPromises = await import("node:fs/promises");
 							const photoDirLocal = path.join(os.tmpdir(), "telegram-photos");
-							await fsPromises.mkdir(photoDirLocal, { recursive: true }).catch(() => {});
-							const destFile = path.join(photoDirLocal, `photo_${timestamp}.jpg`);
+							await fsPromises
+								.mkdir(photoDirLocal, { recursive: true })
+								.catch(() => {});
+							const destFile = path.join(
+								photoDirLocal,
+								`photo_${timestamp}.jpg`,
+							);
 							const result = await downloadFile(photoId, destFile);
 							const captionInfo = caption ? `\nCaption: "${caption}"` : "";
 							if (result) {
 								return {
-									content: [{
-										type: "text",
-										text: `📸 Photo received from Telegram\nPath: ${result}${captionInfo}\n\nUse read("${result}") to view the image.`,
-									}],
-									details: { message: caption, photoPath: result, hasPhoto: true },
+									content: [
+										{
+											type: "text",
+											text: `📸 Photo received from Telegram\nPath: ${result}${captionInfo}\n\nUse read("${result}") to view the image.`,
+										},
+									],
+									details: {
+										message: caption,
+										photoPath: result,
+										hasPhoto: true,
+									},
 								};
 							}
 							return {
-								content: [{
-									type: "text",
-									text: `📸 Photo received from Telegram but could not be downloaded.${captionInfo}`,
-								}],
-								details: { message: caption, hasPhoto: true, downloadFailed: true },
+								content: [
+									{
+										type: "text",
+										text: `📸 Photo received from Telegram but could not be downloaded.${captionInfo}`,
+									},
+								],
+								details: {
+									message: caption,
+									hasPhoto: true,
+									downloadFailed: true,
+								},
 							};
 						}
 						// Text message
@@ -398,7 +566,11 @@ export default function telegramBridge(pi: ExtensionAPI) {
 					action = "explain";
 				}
 
-				await sendMsg(`✅ Choice received: <i>${choice}</i>`, undefined, "HTML");
+				await sendMsg(
+					`✅ Choice received: <i>${choice}</i>`,
+					undefined,
+					"HTML",
+				);
 
 				return {
 					content: [
@@ -478,7 +650,10 @@ export default function telegramBridge(pi: ExtensionAPI) {
 		description:
 			"Send a photo to the Telegram chat. Supports local file paths and remote URLs.",
 		parameters: sendPhotoSchema,
-		async execute(_id: string, params: { photoPath: string; caption?: string }) {
+		async execute(
+			_id: string,
+			params: { photoPath: string; caption?: string },
+		) {
 			try {
 				const mid = await sendPhoto(params.photoPath, params.caption);
 				return {