@bytesbrains/pi-telegram-bridge 1.1.4 → 1.1.6

package/package.json

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

package/src/__tests__/helpers.test.ts

@@ -437,7 +437,7 @@ 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!");
@@ -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,7 +615,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).toHaveBeenCalledWith("recovered");
@@ -660,7 +660,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).toHaveBeenCalledWith("eventually");
@@ -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,7 +731,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).toHaveBeenCalledWith("after not-ok");
@@ -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,131 @@ 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 ─────────────────────────────────────────────────────────
@@ -189,6 +309,7 @@ export async function pollUpdates(
 	lastUpdateId: number,
 	signal: AbortSignal,
 	onMessage: (text: string) => void,
+	onPhoto: (photoId: string, caption?: string) => void,
 	onUpdateId: (id: number) => void,
 ): Promise<void> {
 	while (!signal.aborted) {
@@ -212,6 +333,8 @@ 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 +348,24 @@ 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
+				// Process messages from the configured chat, not from our bot
 				if (
 					u.message &&
-					u.message.text &&
 					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);
+					}
 				}
 			}
 		} 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,6 +30,7 @@ import {
 	statusSchema,
 	overrideSchema,
 	notifySchema,
+	sendPhotoSchema,
 } from "./tools/telegram";
 
 export default function telegramBridge(pi: ExtensionAPI) {
@@ -35,6 +41,10 @@ export default function telegramBridge(pi: ExtensionAPI) {
 	// ── 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") {
@@ -67,6 +77,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,7 +89,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 			botId,
 			lastUpdateId,
 			signal,
-			// onMessage: forward to pi as user message
+			// onMessage: forward text or photo to pi as user message
 			async (text: string) => {
 				pi.sendUserMessage(text);
 				await sendMsg(
@@ -83,6 +98,23 @@ export default function telegramBridge(pi: ExtensionAPI) {
 					"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;
@@ -147,20 +179,50 @@ export default function telegramBridge(pi: ExtensionAPI) {
 					if (u.callback_query) continue;
 					if (
 						u.message &&
-						u.message.text &&
 						String(u.message.chat.id) === chatId
 					) {
 						if (u.message.from?.is_bot || u.message.from?.id === botId)
 							continue;
-						return {
-							content: [
-								{
+						// 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: `📩 New message: "${u.message.text}"`,
-								},
-							],
-							details: { message: u.message.text },
-						};
+									text: `📸 Photo received from Telegram but could not be downloaded.${captionInfo}`,
+								}],
+								details: { message: caption, hasPhoto: true, downloadFailed: true },
+							};
+						}
+						// Text message
+						if (u.message.text) {
+							return {
+								content: [
+									{
+										type: "text",
+										text: `📩 New message: "${u.message.text}"`,
+									},
+								],
+								details: { message: u.message.text },
+							};
+						}
 					}
 				}
 				return {
@@ -295,16 +357,16 @@ export default function telegramBridge(pi: ExtensionAPI) {
 				];
 				const timeoutMs = (params.timeoutMinutes ?? 30) * 60000;
 
-				let message = `🛑 *Supervisor blocked an action*\n\n`;
-				message += `*Command:* \`${params.command.slice(0, 200)}\`\n`;
-				message += `*Reason:* ${params.reason.slice(0, 300)}\n`;
+				let message = `🛑 <b>Supervisor blocked an action</b>\n\n`;
+				message += `<b>Command:</b> <code>${params.command.slice(0, 200)}</code>\n`;
+				message += `<b>Reason:</b> ${params.reason.slice(0, 300)}\n`;
 				if (params.context) {
-					message += `*Context:* ${params.context.slice(0, 300)}\n`;
+					message += `<b>Context:</b> ${params.context.slice(0, 300)}\n`;
 				}
-				message += `\n_What should I do?_`;
+				message += `\n<i>What should I do?</i>`;
 
 				const kb = opts.map((o: string) => [{ text: o, callback_data: o }]);
-				const mid = await sendMsg(message, { inline_keyboard: kb }, "Markdown");
+				const mid = await sendMsg(message, { inline_keyboard: kb }, "HTML");
 				const reply = await pollReply(mid, chatId, timeoutMs);
 
 				if (!reply) {
@@ -336,7 +398,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 					action = "explain";
 				}
 
-				await sendMsg(`✅ Choice received: _${choice}_`, undefined, "Markdown");
+				await sendMsg(`✅ Choice received: <i>${choice}</i>`, undefined, "HTML");
 
 				return {
 					content: [
@@ -409,6 +471,35 @@ 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() });