@bytesbrains/pi-telegram-bridge 1.0.2 → 1.1.1

package/src/index.ts

@@ -9,378 +9,435 @@
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  getToken,
-  getChatId,
-  telegramApi,
-  sendMsg,
-  pollReply,
-  getBotId,
-  seedLastUpdateId,
-  pollUpdates,
+	getToken,
+	getChatId,
+	telegramApi,
+	sendMsg,
+	pollReply,
+	getBotId,
+	seedLastUpdateId,
+	pollUpdates,
 } from "./helpers";
 import {
-  listenSchema,
-  sendSchema,
-  askSchema,
-  statusSchema,
-  overrideSchema,
+	listenSchema,
+	sendSchema,
+	askSchema,
+	statusSchema,
+	overrideSchema,
+	notifySchema,
 } from "./tools/telegram";
 
 export default function telegramBridge(pi: ExtensionAPI) {
-  let botId: number | null = null;
-  let listenerAbort: AbortController | null = null;
-  let lastUpdateId = 0;
+	let botId: number | null = null;
+	let listenerAbort: AbortController | null = null;
+	let lastUpdateId = 0;
 
-  // ── Session lifecycle ───────────────────────────────────────────
+	// ── Session lifecycle ───────────────────────────────────────────
 
-  pi.on("session_start", async (_event, ctx) => {
-    // Restore lastUpdateId from session state
-    for (const entry of ctx.sessionManager.getEntries()) {
-      if (entry.type === "custom" && entry.customType === "tg-last-update") {
-        lastUpdateId = (entry.data as { update_id: number }).update_id;
-      }
-    }
-    // Start background listener
-    startListener();
-  });
+	pi.on("session_start", async (_event, ctx) => {
+		// Restore lastUpdateId from session state
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type === "custom" && entry.customType === "tg-last-update") {
+				lastUpdateId = (entry.data as { update_id: number }).update_id;
+			}
+		}
+		// Start background listener
+		startListener();
+	});
 
-  pi.on("session_shutdown", () => {
-    listenerAbort?.abort();
-    listenerAbort = null;
-  });
+	pi.on("session_shutdown", () => {
+		listenerAbort?.abort();
+		listenerAbort = null;
+	});
 
-  // ── Background listener ─────────────────────────────────────────
+	// ── Background listener ─────────────────────────────────────────
 
-  async function startListener() {
-    if (listenerAbort) return; // already running
-    listenerAbort = new AbortController();
-    const signal = listenerAbort.signal;
-    const token = getToken();
-    const chatId = getChatId();
+	async function startListener() {
+		if (listenerAbort) return; // already running
+		listenerAbort = new AbortController();
+		const signal = listenerAbort.signal;
+		const token = getToken();
+		const chatId = getChatId();
 
-    // Get bot's own ID once to filter out self-messages
-    if (!botId) {
-      botId = await getBotId();
-    }
+		// Get bot's own ID once to filter out self-messages
+		if (!botId) {
+			botId = await getBotId();
+		}
 
-    // Seed lastUpdateId
-    lastUpdateId = await seedLastUpdateId(lastUpdateId, signal);
+		// Seed lastUpdateId
+		lastUpdateId = await seedLastUpdateId(lastUpdateId, signal);
 
-    // Fire and forget — poll in background
-    pollUpdates(
-      token,
-      chatId,
-      botId,
-      lastUpdateId,
-      signal,
-      // onMessage: forward to pi as user message
-      async (text: string) => {
-        pi.sendUserMessage(text);
-        await sendMsg(`👂 Got it! Working on: _${text.slice(0, 100)}_`);
-      },
-      // onUpdateId: persist offset
-      (id: number) => {
-        lastUpdateId = id;
-        pi.appendEntry("tg-last-update", { update_id: id });
-      },
-    );
-  }
+		// Fire and forget — poll in background
+		pollUpdates(
+			token,
+			chatId,
+			botId,
+			lastUpdateId,
+			signal,
+			// onMessage: forward to pi as user message
+			async (text: string) => {
+				pi.sendUserMessage(text);
+				await sendMsg(`👂 Got it! Working on: _${text.slice(0, 100)}_`);
+			},
+			// onUpdateId: persist offset
+			(id: number) => {
+				lastUpdateId = id;
+				pi.appendEntry("tg-last-update", { update_id: id });
+			},
+		);
+	}
 
-  // ── Tools ───────────────────────────────────────────────────────
+	// ── Tools ───────────────────────────────────────────────────────
 
-  // telegram_listen
-  pi.registerTool({
-    name: "telegram_listen",
-    label: "Telegram Listen",
-    description:
-      "Check Telegram for any new inbound messages from the human. Returns the latest message text, or indicates no new messages.",
-    parameters: listenSchema,
-    async execute() {
-      try {
-        const token = getToken();
-        const chatId = getChatId();
-        if (!botId) botId = await getBotId();
+	// telegram_listen
+	pi.registerTool({
+		name: "telegram_listen",
+		label: "Telegram Listen",
+		description:
+			"Check Telegram for any new inbound messages from the human. Returns the latest message text, or indicates no new messages.",
+		parameters: listenSchema,
+		async execute() {
+			try {
+				const token = getToken();
+				const chatId = getChatId();
+				if (!botId) botId = await getBotId();
 
-        const res = await fetch(
-          `https://api.telegram.org/bot${token}/getUpdates`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ offset: lastUpdateId + 1, timeout: 5 }),
-          },
-        );
-        if (!res.ok)
-          return {
-            content: [{ type: "text", text: "Could not reach Telegram." }],
-            isError: true,
-          };
+				const res = await fetch(
+					`https://api.telegram.org/bot${token}/getUpdates`,
+					{
+						method: "POST",
+						headers: { "Content-Type": "application/json" },
+						body: JSON.stringify({ offset: lastUpdateId + 1, timeout: 5 }),
+					},
+				);
+				if (!res.ok)
+					return {
+						content: [{ type: "text", text: "Could not reach Telegram." }],
+						details: { message: "" },
+						isError: true,
+					};
 
-        const data = (await res.json()) as {
-          ok: boolean;
-          result: Array<{
-            update_id: number;
-            message?: {
-              message_id: number;
-              chat: { id: number };
-              from?: { id: number; is_bot?: boolean };
-              text?: string;
-            };
-            callback_query?: unknown;
-          }>;
-        };
-        if (!data.ok)
-          return {
-            content: [{ type: "text", text: "Telegram API error." }],
-            isError: true,
-          };
+				const data = (await res.json()) as {
+					ok: boolean;
+					result: Array<{
+						update_id: number;
+						message?: {
+							message_id: number;
+							chat: { id: number };
+							from?: { id: number; is_bot?: boolean };
+							text?: string;
+						};
+						callback_query?: unknown;
+					}>;
+				};
+				if (!data.ok)
+					return {
+						content: [{ type: "text", text: "Telegram API error." }],
+						details: { message: "" },
+						isError: true,
+					};
 
-        for (const u of data.result) {
-          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.from?.is_bot || u.message.from?.id === botId)
-              continue;
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: `📩 New message: "${u.message.text}"`,
-                },
-              ],
-              details: { message: u.message.text },
-            };
-          }
-        }
-        return { content: [{ type: "text", text: "No new messages." }] };
-      } catch (e: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Failed: ${e instanceof Error ? e.message : e}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-    },
-  });
+				for (const u of data.result) {
+					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.from?.is_bot || u.message.from?.id === botId)
+							continue;
+						return {
+							content: [
+								{
+									type: "text",
+									text: `📩 New message: "${u.message.text}"`,
+								},
+							],
+							details: { message: u.message.text },
+						};
+					}
+				}
+				return {
+					content: [{ type: "text", text: "No new messages." }],
+					details: { message: "" },
+				};
+			} catch (e: unknown) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Failed: ${e instanceof Error ? e.message : e}`,
+						},
+					],
+					details: { message: "" },
+					isError: true,
+				};
+			}
+		},
+	});
 
-  // telegram_send
-  pi.registerTool({
-    name: "telegram_send",
-    label: "Telegram Send",
-    description:
-      "Send a one-way message to Telegram. Use for status updates.",
-    parameters: sendSchema,
-    async execute(_id: string, params: { message: string }) {
-      try {
-        const mid = await sendMsg(params.message);
-        return { content: [{ type: "text", text: `Sent (id:${mid})` }] };
-      } catch (e: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Failed: ${e instanceof Error ? e.message : e}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-    },
-  });
+	// telegram_send
+	pi.registerTool({
+		name: "telegram_send",
+		label: "Telegram Send",
+		description: "Send a one-way message to Telegram. Use for status updates.",
+		parameters: sendSchema,
+		async execute(_id: string, params: { message: string }) {
+			try {
+				const mid = await sendMsg(params.message);
+				return {
+					content: [{ type: "text", text: `Sent (id:${mid})` }],
+					details: {},
+				};
+			} catch (e: unknown) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Failed: ${e instanceof Error ? e.message : e}`,
+						},
+					],
+					details: {},
+					isError: true,
+				};
+			}
+		},
+	});
 
-  // telegram_ask
-  pi.registerTool({
-    name: "telegram_ask",
-    label: "Telegram Ask",
-    description:
-      "Ask a question on Telegram and WAIT for a human reply. BLOCKS until you answer. Use when you need human input.",
-    parameters: askSchema,
-    async execute(
-      _id: string,
-      params: {
-        question: string;
-        options?: string[];
-        timeoutMinutes?: number;
-      },
-    ) {
-      try {
-        const chatId = getChatId();
-        const opts = params.options ?? ["Yes", "No", "Explain"];
-        const kb = opts.map((o: string) => [{ text: o, callback_data: o }]);
-        const timeoutMs = (params.timeoutMinutes ?? 30) * 60000;
-        const mid = await sendMsg(`❓ *${params.question}*`, {
-          inline_keyboard: kb,
-        });
-        const reply = await pollReply(mid, chatId, timeoutMs);
-        if (!reply) {
-          await sendMsg("⏰ No reply. Proceeding autonomously.");
-          return {
-            content: [
-              { type: "text", text: "Timeout — proceeding autonomously" },
-            ],
-            details: { timedOut: true },
-          };
-        }
-        return {
-          content: [{ type: "text", text: `Reply: "${reply}"` }],
-          details: { answer: reply },
-        };
-      } catch (e: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Failed: ${e instanceof Error ? e.message : e}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-    },
-  });
+	// telegram_ask
+	pi.registerTool({
+		name: "telegram_ask",
+		label: "Telegram Ask",
+		description:
+			"Ask a question on Telegram and WAIT for a human reply. BLOCKS until you answer. Use when you need human input.",
+		parameters: askSchema,
+		async execute(
+			_id: string,
+			params: {
+				question: string;
+				options?: string[];
+				timeoutMinutes?: number;
+			},
+		) {
+			try {
+				const chatId = getChatId();
+				const opts = params.options ?? ["Yes", "No", "Explain"];
+				const kb = opts.map((o: string) => [{ text: o, callback_data: o }]);
+				const timeoutMs = (params.timeoutMinutes ?? 30) * 60000;
+				const mid = await sendMsg(`❓ *${params.question}*`, {
+					inline_keyboard: kb,
+				});
+				const reply = await pollReply(mid, chatId, timeoutMs);
+				if (!reply) {
+					await sendMsg("⏰ No reply. Proceeding autonomously.");
+					return {
+						content: [
+							{ type: "text", text: "Timeout — proceeding autonomously" },
+						],
+						details: { timedOut: true, answer: "" },
+					};
+				}
+				return {
+					content: [{ type: "text", text: `Reply: "${reply}"` }],
+					details: { timedOut: false, answer: reply },
+				};
+			} catch (e: unknown) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Failed: ${e instanceof Error ? e.message : e}`,
+						},
+					],
+					details: { timedOut: false, answer: "" },
+					isError: true,
+				};
+			}
+		},
+	});
 
-  // telegram_override
-  pi.registerTool({
-    name: "telegram_override",
-    label: "Telegram Override",
-    description:
-      "Ask a human on Telegram to approve or reject a blocked action. " +
-      "Use when the supervisor blocks a dangerous command (force push, " +
-      "destructive git ops, file deletion, etc.) and you need human approval. " +
-      "Returns the human's choice so you can call supervisor_override or abort.",
-    parameters: overrideSchema,
-    async execute(
-      _id: string,
-      params: {
-        command: string;
-        reason: string;
-        context?: string;
-        options?: string[];
-        timeoutMinutes?: number;
-      },
-    ) {
-      try {
-        const chatId = getChatId();
-        const opts = params.options ?? [
-          "Yes, proceed",
-          "No, cancel",
-          "Explain more",
-        ];
-        const timeoutMs = (params.timeoutMinutes ?? 30) * 60000;
+	// telegram_override
+	pi.registerTool({
+		name: "telegram_override",
+		label: "Telegram Override",
+		description:
+			"Ask a human on Telegram to approve or reject a blocked action. " +
+			"Use when the supervisor blocks a dangerous command (force push, " +
+			"destructive git ops, file deletion, etc.) and you need human approval. " +
+			"Returns the human's choice so you can call supervisor_override or abort.",
+		parameters: overrideSchema,
+		async execute(
+			_id: string,
+			params: {
+				command: string;
+				reason: string;
+				context?: string;
+				options?: string[];
+				timeoutMinutes?: number;
+			},
+		) {
+			try {
+				const chatId = getChatId();
+				const opts = params.options ?? [
+					"Yes, proceed",
+					"No, cancel",
+					"Explain more",
+				];
+				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`;
-        if (params.context) {
-          message += `*Context:* ${params.context.slice(0, 300)}\n`;
-        }
-        message += `\n_What should I do?_`;
+				let message = `🛑 *Supervisor blocked an action*\n\n`;
+				message += `*Command:* \`${params.command.slice(0, 200)}\`\n`;
+				message += `*Reason:* ${params.reason.slice(0, 300)}\n`;
+				if (params.context) {
+					message += `*Context:* ${params.context.slice(0, 300)}\n`;
+				}
+				message += `\n_What should I do?_`;
 
-        const kb = opts.map((o: string) => [{ text: o, callback_data: o }]);
-        const mid = await sendMsg(message, { inline_keyboard: kb });
-        const reply = await pollReply(mid, chatId, timeoutMs);
+				const kb = opts.map((o: string) => [{ text: o, callback_data: o }]);
+				const mid = await sendMsg(message, { inline_keyboard: kb });
+				const reply = await pollReply(mid, chatId, timeoutMs);
 
-        if (!reply) {
-          await sendMsg("⏰ No reply to override request. Aborting action.");
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Timeout — no human response. Action aborted.",
-              },
-            ],
-            details: {
-              timedOut: true,
-              action: "abort",
-              command: params.command,
-            },
-          };
-        }
+				if (!reply) {
+					await sendMsg("⏰ No reply to override request. Aborting action.");
+					return {
+						content: [
+							{
+								type: "text",
+								text: "Timeout — no human response. Action aborted.",
+							},
+						],
+						details: {
+							timedOut: true,
+							action: "abort",
+							command: params.command,
+							choice: "",
+						},
+					};
+				}
 
-        // Map the reply to an action
-        const choice = reply.trim();
-        let action: string;
-        if (choice === opts[0]) {
-          action = "proceed";
-        } else if (choice === opts[1]) {
-          action = "abort";
-        } else {
-          action = "explain";
-        }
+				// Map the reply to an action
+				const choice = reply.trim();
+				let action: string;
+				if (choice === opts[0]) {
+					action = "proceed";
+				} else if (choice === opts[1]) {
+					action = "abort";
+				} else {
+					action = "explain";
+				}
 
-        await sendMsg(`✅ Choice received: _${choice}_`);
+				await sendMsg(`✅ Choice received: _${choice}_`);
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Human chose: "${choice}" → action: ${action}`,
-            },
-          ],
-          details: {
-            choice,
-            action,
-            command: params.command,
-            timedOut: false,
-          },
-        };
-      } catch (e: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Failed: ${e instanceof Error ? e.message : e}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-    },
-  });
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Human chose: "${choice}" → action: ${action}`,
+						},
+					],
+					details: {
+						choice,
+						action,
+						command: params.command,
+						timedOut: false,
+					},
+				};
+			} catch (e: unknown) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Failed: ${e instanceof Error ? e.message : e}`,
+						},
+					],
+					details: {
+						timedOut: false,
+						action: "",
+						command: "",
+						choice: "",
+					},
+					isError: true,
+				};
+			}
+		},
+	});
 
-  // telegram_status
-  pi.registerTool({
-    name: "telegram_status",
-    label: "Telegram Status",
-    description:
-      "Check if the Telegram bridge is configured and running.",
-    parameters: statusSchema,
-    async execute() {
-      if (!process.env.TELEGRAM_BOT_TOKEN || !process.env.TELEGRAM_CHAT_ID) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Not configured. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.",
-            },
-          ],
-        };
-      }
-      try {
-        const r = (await telegramApi("getMe", {})) as {
-          result: { username: string };
-        };
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Active. Bot: @${r.result.username} (listener: ${listenerAbort ? "🟢 running" : "🔴 stopped"})`,
-            },
-          ],
-        };
-      } catch {
-        return {
-          content: [{ type: "text", text: "Token set but unreachable." }],
-        };
-      }
-    },
-  });
+	// telegram_notify — rich formatted notifications
+	pi.registerTool({
+		name: "telegram_notify",
+		label: "Telegram Notify",
+		description:
+			"Send a rich, well-formatted notification to Telegram. " +
+			"Choose a kind: issue, pr, task, pipeline, session, alert, " +
+			"factory-job, standup, diff, decision, or ack. " +
+			"Fill the matching fields for that kind. " +
+			"All other fields are ignored — only provide fields relevant to your chosen kind.",
+		parameters: notifySchema,
+		async execute(_id: string, params: Record<string, unknown>) {
+			try {
+				const { buildNotification } = await import("./templates");
+				const message = buildNotification(
+					params as unknown as import("./templates").NotifyInput,
+				);
+				const mid = await sendMsg(message);
+				return {
+					content: [{ type: "text", text: `Notification sent (id:${mid})` }],
+					details: {},
+				};
+			} catch (e: unknown) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Failed: ${e instanceof Error ? e.message : e}`,
+						},
+					],
+					details: {},
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// telegram_status
+	pi.registerTool({
+		name: "telegram_status",
+		label: "Telegram Status",
+		description: "Check if the Telegram bridge is configured and running.",
+		parameters: statusSchema,
+		async execute() {
+			if (!process.env.TELEGRAM_BOT_TOKEN || !process.env.TELEGRAM_CHAT_ID) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "Not configured. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.",
+						},
+					],
+					details: {},
+				};
+			}
+			try {
+				const r = (await telegramApi("getMe", {})) as {
+					result: { username: string };
+				};
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Active. Bot: @${r.result.username} (listener: ${listenerAbort ? "🟢 running" : "🔴 stopped"})`,
+						},
+					],
+					details: {},
+				};
+			} catch {
+				return {
+					content: [{ type: "text", text: "Token set but unreachable." }],
+					details: {},
+				};
+			}
+		},
+	});
 }