@bytesbrains/pi-telegram-bridge 1.0.0

package/AGENTS.md

@@ -0,0 +1,170 @@
+# Telegram Bridge — Agent Usage Guide
+
+> You are an AI agent. Use telegram-bridge tools to communicate with humans via Telegram.
+> Ask questions, send status updates, and check for incoming messages.
+
+## Quickstart
+
+```bash
+telegram_status()                                                  # Check if bridge is configured
+telegram_send(message="Hello! I'm working on the task.")           # Send a status message
+telegram_listen()                                                  # Check for new messages
+telegram_ask(question="Should I proceed?", options=["Yes","No"])   # Ask and wait for reply
+telegram_override(command="git push --force", reason="Force push detected")   # Override blocked action
+```
+
+## Tools
+
+### telegram_listen
+
+Check for any new inbound messages from the human in the configured chat. Returns the latest message text, or indicates no new messages. The background listener automatically forwards messages, so this is for explicit polling.
+
+```bash
+telegram_listen()
+```
+
+### telegram_send
+
+Send a one-way message. Use for:
+- Status updates ("Build started", "Tests passed")
+- Progress reports ("Step 3/5 complete")
+- Notifications ("Deployment finished")
+- Errors or alerts
+
+```bash
+telegram_send(message="✅ All tests passed. Ready to deploy.")
+telegram_send(message="⚠️ Found 3 linting issues. Fixing now...")
+```
+
+### telegram_ask
+
+Ask a question and **WAIT** for a human reply. This tool **blocks** until the human responds or the timeout is reached. Use when you genuinely need human input — don't overuse it.
+
+**Parameters:**
+- `question` (required) — The question to ask
+- `options` (optional) — Array of button options (default: `["Yes", "No", "Explain"]`)
+- `timeoutMinutes` (optional) — How long to wait (default: 30 minutes)
+
+```bash
+# Simple yes/no
+telegram_ask(question="Deploy v2.1.0 to production?")
+
+# Custom options
+telegram_ask(
+  question="Which environment should I target?",
+  options=["production", "staging", "development"]
+)
+
+# Short timeout
+telegram_ask(
+  question="Approve this database migration?",
+  options=["Approve", "Reject"],
+  timeoutMinutes=5
+)
+```
+
+**Returns:**
+- On reply: `Reply: "Yes"` with `details.answer = "Yes"`
+- On timeout: `Timeout — proceeding autonomously` with `details.timedOut = true`
+
+### telegram_override
+
+Ask a human to approve or reject a **blocked action**. Use this when the supervisor blocks a dangerous operation (force push, destructive git ops, file deletion outside project boundary, etc.). This tool sends a structured message with the blocked command, reason, and context, then waits for the human to choose an action.
+
+**Parameters:**
+| Param | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `command` | ✅ | — | The blocked command exactly as the supervisor reported it |
+| `reason` | ✅ | — | Why the supervisor blocked it |
+| `context` | ❌ | — | Additional context (what the user originally asked for) |
+| `options` | ❌ | `["Yes, proceed", "No, cancel", "Explain more"]` | Custom button labels — 1st = proceed, 2nd = cancel, rest = explain |
+| `timeoutMinutes` | ❌ | `30` | How long to wait for a response |
+
+```bash
+# Force push override
+telegram_override(
+  command="git push gitea feat/add-check --force",
+  reason="Force push can overwrite remote history"
+)
+
+# Destructive operation with extra context
+telegram_override(
+  command="rm -rf node_modules",
+  reason="Recursive deletion outside project boundary",
+  context="User requested a clean reinstall of dependencies"
+)
+
+# Custom options
+telegram_override(
+  command="chmod -R 777 /var/www",
+  reason="Broad permission changes detected",
+  options=["Yes, it's safe", "No, cancel", "Use 755 instead", "Explain more"],
+  timeoutMinutes=10
+)
+```
+
+**Returns `details`:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `choice` | `string` | The exact button label the human clicked |
+| `action` | `"proceed"` \| `"abort"` \| `"explain"` | Mapped action based on which button was clicked |
+| `command` | `string` | The original blocked command (echoed back) |
+| `timedOut` | `boolean` | `true` if no response within timeout |
+
+**Mandatory workflow when blocked:**
+1. Supervisor blocks your command → you see the reason and blocked command
+2. Call `telegram_override(command, reason, context)` to ask the human
+3. Check `details.action`:
+   - **`"proceed"`** → call `supervisor_override(reason="<human approved>", command="<blocked command>")` then re-run
+   - **`"abort"`** → tell the user the action was cancelled: `telegram_send(message="Action cancelled as requested.")`
+   - **`"explain"`** → send more context via `telegram_send()`, then call `telegram_ask()` for follow-up
+4. If **`details.timedOut === true`** → abort the action and tell the user: `telegram_send(message="No response received. Action aborted.")`
+
+**On timeout:** Sends "⏰ No reply to override request. Aborting action." to Telegram and returns `details.timedOut = true`.
+
+**Behavior on timeout:** The agent proceeds without human input. A "No reply" message is sent to Telegram.
+
+### telegram_status
+
+Check if the bridge is configured and the background listener is running.
+
+```bash
+telegram_status()
+```
+
+**Possible responses:**
+- `Not configured. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.` — Missing env vars
+- `Active. Bot: @mybot (listener: 🟢 running)` — Fully operational
+- `Token set but unreachable.` — Network or auth issue
+
+## Background Listener
+
+A background listener starts automatically on session start and runs throughout the session. It:
+- Polls Telegram every 5 seconds for new messages
+- Forwards any non-bot text messages from the configured chat to the agent
+- Sends a confirmation (`👂 Got it! Working on: ...`) to acknowledge receipt
+- Stops cleanly on session shutdown
+
+The listener ignores:
+- Messages from bots (including itself)
+- Messages from other chats
+- Callback queries (button presses) — these are handled by `telegram_ask`
+
+## Best Practices
+
+1. **Use `telegram_send` for routine updates** — it's non-blocking
+2. **Use `telegram_ask` sparingly** — only when you truly need human input
+3. **Use `telegram_override` for blocked actions** — always ask before calling `supervisor_override`
+4. **Set reasonable timeouts** — don't block the agent indefinitely
+5. **Handle timeouts gracefully** — the agent should be able to proceed without human input
+6. **Check `telegram_status` first** — verify the bridge is configured before sending messages
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `telegram_status` says not configured | Set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` env vars |
+| Messages not being delivered | Check that the bot token is valid and the chat ID is correct |
+| Bot unreachable | Check network connectivity and Telegram API status |
+| Duplicate messages | The bridge tracks update IDs to avoid duplicates. If it persists, restart the session |
+| Listener stops unexpectedly | Check logs for errors. The listener auto-recovers from transient failures |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# pi-telegram-bridge
+
+Telegram bot bridge for pi agents — send messages, ask questions, and listen for human replies via Telegram.
+
+## Install
+
+```bash
+pi install npm:@bytesbrains/pi-telegram-bridge
+```
+
+## Configuration
+
+Set the following 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) |
+
+## Tools
+
+### telegram_listen
+
+Check for new inbound messages from the human.
+
+```
+telegram_listen()
+```
+
+### telegram_send
+
+Send a one-way message. Use for status updates and progress reports.
+
+```
+telegram_send(message="Build completed successfully ✅")
+```
+
+### telegram_ask
+
+Ask a question with inline keyboard options and **wait** for a human reply. Blocks until answered or timeout (default 30 min).
+
+```
+telegram_ask(question="Deploy to production?")
+telegram_ask(question="Which branch?", options=["main", "staging", "dev"])
+telegram_ask(question="Approve this change?", options=["Approve", "Reject", "Need changes"], timeoutMinutes=5)
+```
+
+### telegram_override
+
+Ask a human to approve or reject a blocked action (force push, destructive git ops, file deletion, etc.). Designed for supervisor override flows. Returns `details.action = "proceed"|"abort"|"explain"` so the agent can call `supervisor_override()` or abort.
+
+```
+telegram_override(
+  command="git push gitea feat/add-check --force",
+  reason="Force push can overwrite remote history"
+)
+
+telegram_override(
+  command="rm -rf node_modules",
+  reason="Recursive deletion outside project boundary",
+  context="User requested a clean reinstall of dependencies",
+  options=["Yes, it's fine", "No, cancel", "Use npx instead", "Explain more"],
+  timeoutMinutes=10
+)
+```
+
+**Parameters:**
+| Param | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `command` | ✅ | — | The blocked command or action |
+| `reason` | ✅ | — | Why it was blocked by the supervisor |
+| `context` | ❌ | — | Additional context (what the user asked for, etc.) |
+| `options` | ❌ | `["Yes, proceed", "No, cancel", "Explain more"]` | Custom button labels |
+| `timeoutMinutes` | ❌ | `30` | How long to wait for a response |
+
+**Returns `details`:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `choice` | `string` | The exact button label the human clicked |
+| `action` | `string` | `"proceed"` (first option), `"abort"` (second option), or `"explain"` (anything else) |
+| `command` | `string` | The original blocked command |
+| `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`:
+   - `"proceed"` → call `supervisor_override(reason, command)`
+   - `"abort"` → tell user action was cancelled
+   - `"explain"` → call `telegram_send(message="...")` with more context, then re-ask
+4. If `details.timedOut` → abort the action
+
+### telegram_status
+
+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
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@bytesbrains/pi-telegram-bridge",
+  "version": "1.0.0",
+  "description": "Telegram bot bridge for pi agents — send messages, ask questions, and listen for human replies via Telegram.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "telegram",
+    "bot",
+    "bridge",
+    "messaging"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nandal/pi-ext.git",
+    "directory": "telegram-bridge"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/telegram-bridge",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^2.1.9"
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,234 @@
+/**
+ * pi-telegram-bridge — Telegram API Helpers
+ */
+const BASE_URL = "https://api.telegram.org/bot";
+
+// ── Config ──────────────────────────────────────────────────────────
+
+export function getToken(): string {
+  const tok = process.env.TELEGRAM_BOT_TOKEN;
+  if (!tok) throw new Error("TELEGRAM_BOT_TOKEN not set");
+  return tok;
+}
+
+export function getChatId(): string {
+  const id = process.env.TELEGRAM_CHAT_ID;
+  if (!id) throw new Error("TELEGRAM_CHAT_ID not set");
+  return id;
+}
+
+// ── API ─────────────────────────────────────────────────────────────
+
+export async function telegramApi(
+  method: string,
+  body: Record<string, unknown>,
+): Promise<unknown> {
+  const url = `${BASE_URL}${getToken()}/${method}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw new Error(`Telegram API ${res.status}: ${await res.text()}`);
+  }
+  return res.json();
+}
+
+// ── Messaging ───────────────────────────────────────────────────────
+
+export async function sendMsg(
+  text: string,
+  replyMarkup?: object,
+): Promise<number> {
+  const body: Record<string, unknown> = {
+    chat_id: getChatId(),
+    text,
+    parse_mode: "Markdown",
+  };
+  if (replyMarkup) body.reply_markup = JSON.stringify(replyMarkup);
+  const r = (await telegramApi("sendMessage", body)) as {
+    ok: boolean;
+    result: { message_id: number };
+  };
+  return r.result.message_id;
+}
+
+// ── Polling ─────────────────────────────────────────────────────────
+
+export async function pollReply(
+  sentId: number,
+  chatId: string,
+  timeoutMs: number,
+): Promise<string | null> {
+  const token = getToken();
+  const deadline = Date.now() + timeoutMs;
+
+  // Drain pending updates to start fresh
+  let lastId = 0;
+  try {
+    const drain = await fetch(`${BASE_URL}${token}/getUpdates?timeout=0`);
+    if (drain.ok) {
+      const d = (await drain.json()) as {
+        ok: boolean;
+        result: Array<{ update_id: number }>;
+      };
+      if (d.ok && d.result.length > 0) {
+        lastId = d.result[d.result.length - 1].update_id;
+      }
+    }
+  } catch {
+    /* ignore drain errors */
+  }
+
+  while (Date.now() < deadline) {
+    const res = await fetch(
+      `${BASE_URL}${token}/getUpdates?offset=${lastId + 1}&timeout=5`,
+    );
+    if (!res.ok) {
+      await new Promise((r) => setTimeout(r, 3000));
+      continue;
+    }
+    const data = (await res.json()) as {
+      ok: boolean;
+      result: Array<{
+        update_id: number;
+        message?: {
+          message_id: number;
+          chat: { id: number };
+          text?: string;
+        };
+        callback_query?: {
+          id: string;
+          message: { message_id: number; chat: { id: number } };
+          data: string;
+        };
+      }>;
+    };
+    if (!data.ok) {
+      await new Promise((r) => setTimeout(r, 2000));
+      continue;
+    }
+    for (const u of data.result) {
+      lastId = u.update_id;
+      // Check for text reply
+      if (
+        u.message &&
+        u.message.chat.id === Number(chatId) &&
+        u.message.message_id > sentId &&
+        u.message.text
+      ) {
+        return u.message.text;
+      }
+      // Check for callback query (inline button)
+      if (
+        u.callback_query &&
+        u.callback_query.message.chat.id === Number(chatId)
+      ) {
+        await telegramApi("answerCallbackQuery", {
+          callback_query_id: u.callback_query.id,
+        });
+        return u.callback_query.data;
+      }
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  return null; // timeout
+}
+
+// ── Listener State ──────────────────────────────────────────────────
+
+export async function getBotId(): Promise<number | null> {
+  try {
+    const r = (await telegramApi("getMe", {})) as { result: { id: number } };
+    return r.result.id;
+  } catch {
+    return null;
+  }
+}
+
+export async function seedLastUpdateId(
+  lastUpdateId: number,
+  signal?: AbortSignal,
+): Promise<number> {
+  if (lastUpdateId !== 0) return lastUpdateId;
+  const token = getToken();
+  try {
+    const res = await fetch(`${BASE_URL}${token}/getUpdates?timeout=0`, {
+      signal,
+    });
+    if (res.ok) {
+      const d = (await res.json()) as {
+        ok: boolean;
+        result: Array<{ update_id: number }>;
+      };
+      if (d.ok && d.result.length > 0) {
+        return d.result[d.result.length - 1].update_id;
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return lastUpdateId;
+}
+
+export async function pollUpdates(
+  token: string,
+  chatId: string,
+  botId: number | null,
+  lastUpdateId: number,
+  signal: AbortSignal,
+  onMessage: (text: string) => void,
+  onUpdateId: (id: number) => void,
+): Promise<void> {
+  while (!signal.aborted) {
+    try {
+      const res = await fetch(
+        `${BASE_URL}${token}/getUpdates?offset=${lastUpdateId + 1}&timeout=10`,
+        { signal },
+      );
+      if (!res.ok) {
+        await new Promise((r) => setTimeout(r, 3000));
+        continue;
+      }
+      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) {
+        await new Promise((r) => setTimeout(r, 2000));
+        continue;
+      }
+      for (const u of data.result) {
+        lastUpdateId = u.update_id;
+        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
+        ) {
+          if (u.message.from?.is_bot || u.message.from?.id === botId) {
+            continue;
+          }
+          onMessage(u.message.text);
+        }
+      }
+    } catch (e: unknown) {
+      if (e instanceof Error && e.name === "AbortError") break;
+      await new Promise((r) => setTimeout(r, 3000));
+    }
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+}

package/src/index.ts

@@ -0,0 +1,381 @@
+/**
+ * pi-telegram-bridge — Telegram Bot Bridge
+ *
+ * Tools: telegram_listen, telegram_send, telegram_ask, telegram_override, telegram_status
+ * Config: TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables
+ *
+ * Starts a background listener on session start that polls for incoming
+ * messages and forwards them to the agent as user messages.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  getToken,
+  getChatId,
+  telegramApi,
+  sendMsg,
+  pollReply,
+  getBotId,
+  seedLastUpdateId,
+  pollUpdates,
+} from "./helpers";
+import {
+  listenSchema,
+  sendSchema,
+  askSchema,
+  statusSchema,
+  overrideSchema,
+} from "./tools/telegram";
+
+export default function telegramBridge(pi: ExtensionAPI) {
+  let botId: number | null = null;
+  let listenerAbort: AbortController | null = null;
+  let lastUpdateId = 0;
+
+  // ── 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_shutdown", () => {
+    listenerAbort?.abort();
+    listenerAbort = null;
+  });
+
+  // ── Background listener ─────────────────────────────────────────
+
+  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();
+    }
+
+    // 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 });
+      },
+    );
+  }
+
+  // ── 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();
+
+        const res = await fetch(
+          `https://api.telegram.org/bot${token}/getUpdates?offset=${lastUpdateId + 1}&timeout=5`,
+        );
+        if (!res.ok)
+          return {
+            content: [{ type: "text", text: "Could not reach Telegram." }],
+            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,
+          };
+
+        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,
+        };
+      }
+    },
+  });
+
+  // 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_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_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?_`;
+
+        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,
+            },
+          };
+        }
+
+        // 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}_`);
+
+        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,
+        };
+      }
+    },
+  });
+
+  // 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." }],
+        };
+      }
+    },
+  });
+}

package/src/tools/telegram.ts

@@ -0,0 +1,27 @@
+/**
+ * pi-telegram-bridge — Tool Schemas
+ *
+ * Tool parameter schemas and metadata. Execute functions are wired in
+ * index.ts so they can capture the pi ExtensionAPI via closure.
+ */
+import { Type } from "typebox";
+
+export const listenSchema = Type.Object({});
+
+export const sendSchema = Type.Object({ message: Type.String() });
+
+export const askSchema = Type.Object({
+  question: Type.String(),
+  options: Type.Optional(Type.Array(Type.String())),
+  timeoutMinutes: Type.Optional(Type.Number()),
+});
+
+export const statusSchema = Type.Object({});
+
+export const overrideSchema = Type.Object({
+  command: Type.String(),
+  reason: Type.String(),
+  context: Type.Optional(Type.String()),
+  options: Type.Optional(Type.Array(Type.String())),
+  timeoutMinutes: Type.Optional(Type.Number()),
+});

package/src/types.ts

@@ -0,0 +1,15 @@
+/**
+ * pi-telegram-bridge — Types
+ */
+
+export interface TelegramConfig {
+  /** Telegram Bot API token from @BotFather */
+  botToken: string;
+  /** Target chat ID to send messages to and listen from */
+  chatId: string;
+}
+
+/** Session state persisted across restarts */
+export interface TelegramSessionState {
+  update_id: number;
+}