@bytesbrains/pi-telegram-bridge 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytesbrains/pi-telegram-bridge",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Telegram bot bridge for pi agents — send messages, ask questions, and listen for human replies via Telegram.",
   "keywords": [
     "pi-package",
@@ -27,6 +27,7 @@
   },
   "files": [
     "src/",
+    "skills/",
     "README.md",
     "AGENTS.md",
     "LICENSE"
@@ -38,6 +39,9 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "scripts": {

package/skills/telegram-first/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: telegram-first
+description: Route ALL interactive communication through Telegram instead of terminal prompts. The human is reachable on Telegram — use telegram_ask for questions, telegram_notify for status, telegram_send for updates.
+---
+
+# Telegram-First Communication
+
+When telegram-bridge is active, route ALL interactive communication through Telegram instead of the terminal. The human is primarily reachable on Telegram — terminal prompts go unanswered.
+
+## Rules
+
+### Questions & Confirmations
+
+Use `telegram_ask` for ANY decision, confirmation, or question:
+
+- Approval requests (force push, destructive ops, deployments)
+- Clarification questions (ambiguous instructions, multiple approaches)
+- Dependency decisions (which library, which approach)
+- Priority calls (order of work, tradeoffs)
+
+Do NOT use terminal dialogs (`ctx.ui.confirm`, `ctx.ui.select`, `ctx.ui.input`) — the human won't see them.
+
+### Status Updates
+
+Use `telegram_notify` for structured status updates:
+
+- Issue created/updated → kind: `issue`
+- PR created/status change → kind: `pr`
+- Work started/progress/complete → kind: `task`
+- CI pipeline results → kind: `pipeline`
+- Session started/ended → kind: `session`
+- Factory job dispatched/completed → kind: `factory-job`
+- Errors or warnings → kind: `alert`
+- Commits or diffs → kind: `diff`
+- End-of-session roundup → kind: `standup`
+
+### One-Way Messages
+
+Use `telegram_send` for:
+
+- Quick acknowledgments ("Got it, working on it")
+- Simple progress notes not needing structured format
+- Links or references
+
+### Fallback
+
+Only use terminal UI if:
+
+- `telegram_status` reports Telegram is not configured or unreachable
+- A `telegram_ask` times out with no reply (then proceed autonomously and notify via `telegram_send`)
+
+## Session Flow
+
+1. **Start:** Send `session` notification via `telegram_notify`
+2. **During:** Route all questions through `telegram_ask`, progress through `telegram_notify(kind="task")`
+3. **Significant events:** CI results, PRs, issues, commits → `telegram_notify` with appropriate kind
+4. **End:** Send `standup` roundup summarizing completed, next, and blockers

package/src/index.ts

@@ -113,6 +113,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 				if (!res.ok)
 					return {
 						content: [{ type: "text", text: "Could not reach Telegram." }],
+						details: { message: "" },
 						isError: true,
 					};
 
@@ -132,6 +133,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 				if (!data.ok)
 					return {
 						content: [{ type: "text", text: "Telegram API error." }],
+						details: { message: "" },
 						isError: true,
 					};
 
@@ -157,7 +159,10 @@ export default function telegramBridge(pi: ExtensionAPI) {
 						};
 					}
 				}
-				return { content: [{ type: "text", text: "No new messages." }] };
+				return {
+					content: [{ type: "text", text: "No new messages." }],
+					details: { message: "" },
+				};
 			} catch (e: unknown) {
 				return {
 					content: [
@@ -166,6 +171,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 							text: `Failed: ${e instanceof Error ? e.message : e}`,
 						},
 					],
+					details: { message: "" },
 					isError: true,
 				};
 			}
@@ -181,7 +187,10 @@ export default function telegramBridge(pi: ExtensionAPI) {
 		async execute(_id: string, params: { message: string }) {
 			try {
 				const mid = await sendMsg(params.message);
-				return { content: [{ type: "text", text: `Sent (id:${mid})` }] };
+				return {
+					content: [{ type: "text", text: `Sent (id:${mid})` }],
+					details: {},
+				};
 			} catch (e: unknown) {
 				return {
 					content: [
@@ -190,6 +199,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 							text: `Failed: ${e instanceof Error ? e.message : e}`,
 						},
 					],
+					details: {},
 					isError: true,
 				};
 			}
@@ -226,12 +236,12 @@ export default function telegramBridge(pi: ExtensionAPI) {
 						content: [
 							{ type: "text", text: "Timeout — proceeding autonomously" },
 						],
-						details: { timedOut: true },
+						details: { timedOut: true, answer: "" },
 					};
 				}
 				return {
 					content: [{ type: "text", text: `Reply: "${reply}"` }],
-					details: { answer: reply },
+					details: { timedOut: false, answer: reply },
 				};
 			} catch (e: unknown) {
 				return {
@@ -241,6 +251,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 							text: `Failed: ${e instanceof Error ? e.message : e}`,
 						},
 					],
+					details: { timedOut: false, answer: "" },
 					isError: true,
 				};
 			}
@@ -301,6 +312,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 							timedOut: true,
 							action: "abort",
 							command: params.command,
+							choice: "",
 						},
 					};
 				}
@@ -340,6 +352,12 @@ export default function telegramBridge(pi: ExtensionAPI) {
 							text: `Failed: ${e instanceof Error ? e.message : e}`,
 						},
 					],
+					details: {
+						timedOut: false,
+						action: "",
+						command: "",
+						choice: "",
+					},
 					isError: true,
 				};
 			}
@@ -398,6 +416,7 @@ export default function telegramBridge(pi: ExtensionAPI) {
 							text: "Not configured. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.",
 						},
 					],
+					details: {},
 				};
 			}
 			try {
@@ -411,10 +430,12 @@ export default function telegramBridge(pi: ExtensionAPI) {
 							text: `Active. Bot: @${r.result.username} (listener: ${listenerAbort ? "🟢 running" : "🔴 stopped"})`,
 						},
 					],
+					details: {},
 				};
 			} catch {
 				return {
 					content: [{ type: "text", text: "Token set but unreachable." }],
+					details: {},
 				};
 			}
 		},