@bytesbrains/pi-telegram-bridge 1.1.5 → 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,6 +1,6 @@
 {
   "name": "@bytesbrains/pi-telegram-bridge",
-  "version": "1.1.5",
+  "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",

package/src/__tests__/helpers.test.ts

@@ -437,10 +437,10 @@ describe("pollUpdates", () => {
     // pollUpdates has 5s delay between polls — this test takes ~5s
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith("Hello agent!");
+    expect(onMessage).toHaveBeenCalledWith('Hello agent!', '987654321');
     expect(onUpdateId).toHaveBeenCalledWith(100);
   }, 15000);
 
@@ -482,7 +482,7 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
     expect(onMessage).not.toHaveBeenCalled();
@@ -527,7 +527,7 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
     expect(onMessage).not.toHaveBeenCalled();
@@ -567,7 +567,7 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
     expect(onMessage).not.toHaveBeenCalled();
@@ -615,10 +615,10 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith("recovered");
+    expect(onMessage).toHaveBeenCalledWith('recovered', '987654321');
   }, 20000);
 
   it("handles network errors with retry", async () => {
@@ -660,10 +660,10 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith("eventually");
+    expect(onMessage).toHaveBeenCalledWith('eventually', '987654321');
   }, 25000);
 
   it("stops gracefully when aborted immediately", async () => {
@@ -681,7 +681,7 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
     expect(onMessage).not.toHaveBeenCalled();
@@ -731,10 +731,10 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      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 () => {
@@ -775,7 +775,7 @@ describe("pollUpdates", () => {
 
     await helpers.pollUpdates(
       TEST_TOKEN, TEST_CHAT_ID, 12345, 0,
-      controller.signal, onMessage, onUpdateId,
+      controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
     expect(onMessage).not.toHaveBeenCalled();

package/src/__tests__/index.test.ts

@@ -104,17 +104,18 @@ afterEach(() => {
 // ── Tool Registration ─────────────────────────────────────────────
 
 describe("extension registration", () => {
-	it("registers all 6 tools", () => {
+	it("registers all 7 tools", () => {
 		const pi = createMockPI();
 		telegramBridge(pi as any);
 
-		expect(pi.registerTool).toHaveBeenCalledTimes(6);
+		expect(pi.registerTool).toHaveBeenCalledTimes(7);
 		expect(pi._getTool("telegram_listen")).toBeDefined();
 		expect(pi._getTool("telegram_send")).toBeDefined();
 		expect(pi._getTool("telegram_ask")).toBeDefined();
 		expect(pi._getTool("telegram_override")).toBeDefined();
 		expect(pi._getTool("telegram_status")).toBeDefined();
 		expect(pi._getTool("telegram_notify")).toBeDefined();
+		expect(pi._getTool("telegram_send_photo")).toBeDefined();
 	});
 
 	it("registers session_start and session_shutdown handlers", () => {

package/src/helpers.ts

@@ -48,11 +48,140 @@ export async function sendMsg(
 		parse_mode: parseMode,
 	};
 	if (replyMarkup) body.reply_markup = JSON.stringify(replyMarkup);
-	const r = (await telegramApi("sendMessage", body)) as {
+	try {
+		const r = (await telegramApi("sendMessage", body)) as {
+			ok: boolean;
+			result: { message_id: number };
+		};
+		return r.result.message_id;
+	} 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"))
+		) {
+			delete body.parse_mode;
+			const r2 = (await telegramApi("sendMessage", body)) as {
+				ok: boolean;
+				result: { message_id: number };
+			};
+			return r2.result.message_id;
+		}
+		throw e;
+	}
+}
+
+// ── Photo / File Support ────────────────────────────────────────────
+
+/**
+ * Get a Telegram file URL for downloading.
+ * Returns { file_path } from the getFile API.
+ */
+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 }),
+		});
+		if (!res.ok) return null;
+		const data = (await res.json()) as {
+			ok: boolean;
+			result: { file_path: string };
+		};
+		if (!data.ok || !data.result?.file_path) return null;
+		return `https://api.telegram.org/file/bot${token}/${data.result.file_path}`;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Download a Telegram file to a local path.
+ * Returns the file path on success, null on failure.
+ * Creates parent directories automatically.
+ */
+export async function downloadFile(
+	fileId: string,
+	destPath: string,
+): Promise<string | null> {
+	try {
+		const fileUrl = await getFileUrl(fileId);
+		if (!fileUrl) return null;
+		const res = await fetch(fileUrl);
+		if (!res.ok) return null;
+		const buffer = Buffer.from(await res.arrayBuffer());
+		const path = await import("node:path");
+		const fsPromises = await import("node:fs/promises");
+		const dir = path.dirname(destPath);
+		await fsPromises.mkdir(dir, { recursive: true });
+		await fsPromises.writeFile(destPath, buffer);
+		return destPath;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Send a photo to the Telegram chat.
+ * Supports sending from a local file path or a remote URL.
+ */
+export async function sendPhoto(
+	photoPath: string,
+	caption?: string,
+): Promise<number> {
+	const fs = await import("node:fs/promises");
+	let fileData: Buffer;
+	let filename: string;
+
+	// Check if it's a URL
+	if (photoPath.startsWith("http://") || photoPath.startsWith("https://")) {
+		filename = "photo.jpg";
+		const res = await fetch(photoPath);
+		if (!res.ok) throw new Error(`Failed to fetch photo: ${res.status}`);
+		fileData = Buffer.from(await res.arrayBuffer());
+	} else {
+		filename = photoPath;
+		fileData = await fs.readFile(photoPath);
+	}
+
+	const token = getToken();
+	const formData = new FormData();
+	formData.set("chat_id", getChatId());
+	const blob = new Blob([fileData] as any);
+	formData.set("photo", blob, filename);
+	if (caption) {
+		formData.set("caption", caption);
+		formData.set("parse_mode", "HTML");
+	}
+
+	const url = `${BASE_URL}${token}/sendPhoto`;
+	const res = await fetch(url, {
+		method: "POST",
+		body: formData,
+	});
+
+	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"))
+		) {
+			return sendPhoto(photoPath);
+		}
+		throw new Error(`sendPhoto failed: ${res.status} ${errText}`);
+	}
+
+	const data = (await res.json()) as {
 		ok: boolean;
 		result: { message_id: number };
 	};
-	return r.result.message_id;
+	return data.result.message_id;
 }
 
 // ── Polling ─────────────────────────────────────────────────────────
@@ -188,7 +317,8 @@ 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> {
 	while (!signal.aborted) {
@@ -212,6 +342,13 @@ 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;
+						}>;
+						caption?: string;
 					};
 					callback_query?: unknown;
 				}>;
@@ -225,16 +362,21 @@ export async function pollUpdates(
 				onUpdateId(lastUpdateId);
 				// Skip callback queries (handled by telegram_ask)
 				if (u.callback_query) continue;
-				// Only process text messages from the configured chat, not from our bot
-				if (
-					u.message &&
-					u.message.text &&
-					String(u.message.chat.id) === chatId
-				) {
+				// Process messages from the configured chat, not from our bot
+				if (u.message && String(u.message.chat.id) === chatId) {
 					if (u.message.from?.is_bot || u.message.from?.id === botId) {
 						continue;
 					}
-					onMessage(u.message.text);
+					// Photo message
+					if (u.message.photo && u.message.photo.length > 0) {
+						const largest = u.message.photo[u.message.photo.length - 1];
+						onPhoto(largest.file_id, u.message.caption);
+						continue;
+					}
+					// Text message
+					if (u.message.text) {
+						onMessage(u.message.text, String(u.message.chat.id));
+					}
 				}
 			}
 		} catch (e: unknown) {

package/src/index.ts

@@ -13,11 +13,16 @@ import {
 	getChatId,
 	telegramApi,
 	sendMsg,
+	sendPhoto,
+	getFileUrl,
+	downloadFile,
 	pollReply,
 	getBotId,
 	seedLastUpdateId,
 	pollUpdates,
 } from "./helpers";
+import * as path from "node:path";
+import * as os from "node:os";
 import {
 	listenSchema,
 	sendSchema,
@@ -25,16 +30,159 @@ import {
 	statusSchema,
 	overrideSchema,
 	notifySchema,
+	sendPhotoSchema,
 } from "./tools/telegram";
 
 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 ───────────────────────────────────────────
 
 	pi.on("session_start", async (_event, ctx) => {
+		// Ensure photo download directory exists
+		const { mkdir } = await import("node:fs/promises");
+		const photoDir = path.join(os.tmpdir(), "telegram-photos");
+		await mkdir(photoDir, { recursive: true }).catch(() => {});
 		// Restore lastUpdateId from session state
 		for (const entry of ctx.sessionManager.getEntries()) {
 			if (entry.type === "custom" && entry.customType === "tg-last-update") {
@@ -42,6 +190,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 			}
 		}
 		// Start background listener
+		mentionTrigger = await resolveMentionTrigger();
 		startListener();
 	});
 
@@ -67,6 +216,11 @@ export default function telegramBridge(pi: ExtensionAPI) {
 		// Seed lastUpdateId
 		lastUpdateId = await seedLastUpdateId(lastUpdateId, signal);
 
+		// Create photo download directory
+		const fsPromises = await import("node:fs/promises");
+		const photoDir = path.join(os.tmpdir(), "telegram-photos");
+		await fsPromises.mkdir(photoDir, { recursive: true }).catch(() => {});
+
 		// Fire and forget — poll in background
 		pollUpdates(
 			token,
@@ -74,15 +228,46 @@ export default function telegramBridge(pi: ExtensionAPI) {
 			botId,
 			lastUpdateId,
 			signal,
-			// onMessage: forward 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",
 				);
 			},
+			// onPhoto: download and forward photo + caption to pi
+			async (photoId: string, caption?: string) => {
+				const timestamp = Date.now();
+				const filename = `photo_${timestamp}.jpg`;
+				const destPath = path.join(photoDir, filename);
+				const result = await downloadFile(photoId, destPath);
+				if (result) {
+					const captionText = caption ? `\n\n📝 Caption: ${caption}` : "";
+					pi.sendUserMessage(
+						`📸 Photo received from Telegram\nPath: ${result}${captionText}\n\nUse read("${result}") to view the image.`,
+					);
+					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.",
+					);
+				}
+			},
 			// onUpdateId: persist offset
 			(id: number) => {
 				lastUpdateId = id;
@@ -145,22 +330,67 @@ 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 &&
-						u.message.text &&
-						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;
-						return {
-							content: [
-								{
-									type: "text",
-									text: `📩 New message: "${u.message.text}"`,
+						// Photo message
+						if (u.message.photo && u.message.photo.length > 0) {
+							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`,
+							);
+							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,
+									},
+								};
+							}
+							return {
+								content: [
+									{
+										type: "text",
+										text: `📸 Photo received from Telegram but could not be downloaded.${captionInfo}`,
+									},
+								],
+								details: {
+									message: caption,
+									hasPhoto: true,
+									downloadFailed: true,
 								},
-							],
-							details: { message: u.message.text },
-						};
+							};
+						}
+						// Text message
+						if (u.message.text) {
+							return {
+								content: [
+									{
+										type: "text",
+										text: `📩 New message: "${u.message.text}"`,
+									},
+								],
+								details: { message: u.message.text },
+							};
+						}
 					}
 				}
 				return {
@@ -336,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: [
@@ -409,6 +643,38 @@ export default function telegramBridge(pi: ExtensionAPI) {
 		},
 	});
 
+	// telegram_send_photo
+	pi.registerTool({
+		name: "telegram_send_photo",
+		label: "Send Photo",
+		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 },
+		) {
+			try {
+				const mid = await sendPhoto(params.photoPath, params.caption);
+				return {
+					content: [{ type: "text", text: `Photo sent (id:${mid})` }],
+					details: { messageId: mid },
+				};
+			} catch (e: unknown) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Failed to send photo: ${e instanceof Error ? e.message : e}`,
+						},
+					],
+					details: {},
+					isError: true,
+				};
+			}
+		},
+	});
+
 	// telegram_status
 	pi.registerTool({
 		name: "telegram_status",

package/src/templates.ts

@@ -10,23 +10,31 @@
 
 const BAR = "━".repeat(20);
 
+/** Escape user text for safe embedding inside HTML tags. */
+function escapeHtml(s: string): string {
+	return s
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
 function bold(s: string) {
-	return `<b>${s}</b>`;
+	return `<b>${escapeHtml(s)}</b>`;
 }
 function italic(s: string) {
-	return `<i>${s}</i>`;
+	return `<i>${escapeHtml(s)}</i>`;
 }
 function code(s: string) {
-	return `<code>${s}</code>`;
+	return `<code>${escapeHtml(s)}</code>`;
 }
 function strike(s: string) {
-	return `<s>${s}</s>`;
+	return `<s>${escapeHtml(s)}</s>`;
 }
 function labelValue(label: string, value: string) {
-	return `${bold(label + ":")} ${value}`;
+	return `${bold(label + ":")} ${escapeHtml(value)}`;
 }
 function link(url: string, text: string) {
-	return `<a href="${url}">${text}</a>`;
+	return `<a href="${url}">${escapeHtml(text)}</a>`;
 }
 function progressBar(pct: number, width = 12) {
 	const filled = Math.round((pct / 100) * width);

package/src/tools/telegram.ts

@@ -199,6 +199,11 @@ export const notifySchema = Type.Object({
 	ackEmoji: Type.Optional(Type.String()),
 });
 
+export const sendPhotoSchema = Type.Object({
+	photoPath: Type.String({ description: "Local file path or remote URL of the photo to send" }),
+	caption: Type.Optional(Type.String({ description: "Optional caption text (HTML formatting supported)" })),
+});
+
 export const listenSchema = Type.Object({});
 
 export const sendSchema = Type.Object({ message: Type.String() });