@bytesbrains/pi-telegram-bridge 1.3.1 → 1.4.0

package/README.md

@@ -1,153 +1,45 @@
 # pi-telegram-bridge
 
-Telegram bot bridge for pi agents — send messages, ask questions, receive photos, and get a live project dashboard on "hi".
+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@1.1.6
+pi install npm:@bytesbrains/pi-telegram-bridge
 ```
 
-## Quick Setup
+## Configuration
 
-### 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
+Set the following environment variables:
 
 ```bash
 export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11"
 export TELEGRAM_CHAT_ID="123456789"
 ```
 
-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?`) |
+| 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 (text and photos) from the human.
+Check for new inbound messages from the human.
 
 ```
 telegram_listen()
 ```
 
-Returns photo paths and captions if a photo was received.
-
 ### telegram_send
 
-Send a one-way text message.
+Send a one-way message. Use for status updates and progress reports.
 
 ```
 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).
@@ -195,7 +87,6 @@ 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`:
@@ -212,11 +103,33 @@ 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 (from @BotFather)
-- A chat ID
+- A Telegram bot token
+- A chat ID to send/receive messages
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytesbrains/pi-telegram-bridge",
-  "version": "1.3.1",
+  "version": "1.4.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__/commands.test.ts

@@ -0,0 +1,200 @@
+/**
+ * pi-telegram-bridge — Commands Tests
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ── Mock helpers module ───────────────────────────────────────────
+// Must be before any import of the module under test
+let mockSendMsg: any;
+let mockGetChatId: any;
+
+vi.mock("../helpers", () => ({
+	sendMsg: (...args: any[]) => mockSendMsg(...args),
+	getChatId: () => mockGetChatId(),
+}));
+
+// Import after mocks
+import { isPossibleCommand, handleCommand } from "../commands";
+
+function mockPi() {
+	const messages: string[] = [];
+	return {
+		sendUserMessage: vi.fn((msg: string) => messages.push(msg)),
+		getMessages: () => messages,
+	};
+}
+
+beforeEach(() => {
+	vi.restoreAllMocks();
+	mockSendMsg = vi.fn().mockResolvedValue(12345);
+	mockGetChatId = vi.fn().mockReturnValue("987654321");
+});
+
+// ── isPossibleCommand ─────────────────────────────────────────────
+
+describe("isPossibleCommand", () => {
+	it("detects slash-prefixed messages", () => {
+		expect(isPossibleCommand("/stop")).toBe(true);
+		expect(isPossibleCommand("/s")).toBe(true);
+		expect(isPossibleCommand("/help")).toBe(true);
+		expect(isPossibleCommand("/status")).toBe(true);
+		expect(isPossibleCommand("/i")).toBe(true);
+	});
+
+	it("rejects non-slash messages", () => {
+		expect(isPossibleCommand("hello")).toBe(false);
+		expect(isPossibleCommand("stop")).toBe(false);
+		expect(isPossibleCommand("")).toBe(false);
+	});
+
+	it("detects slash with leading whitespace", () => {
+		expect(isPossibleCommand("  /stop")).toBe(true);
+	});
+
+	it("rejects non-slash with leading whitespace", () => {
+		expect(isPossibleCommand("  hello")).toBe(false);
+	});
+});
+
+// ── handleCommand — Bridge Commands ───────────────────────────────
+
+describe("handleCommand — bridge commands", () => {
+	it("handles /help and /status as bridge commands", async () => {
+		for (const cmd of ["/help", "/h", "/status", "/st", "/HELP", "/Status"]) {
+			const pi = mockPi();
+			const result = await handleCommand(cmd, pi as any, false);
+			expect(result.handled).toBe(true);
+			if (result.handled) expect(result.type).toBe("bridge");
+			expect(pi.sendUserMessage).not.toHaveBeenCalled();
+		}
+	});
+});
+
+// ── handleCommand — Agent Commands ────────────────────────────────
+
+describe("handleCommand — agent commands", () => {
+	const agentCommands = [
+		"/stop",
+		"/s",
+		"/go",
+		"/g",
+		"/sum",
+		"/redo",
+		"/r",
+		"/commit",
+		"/c",
+		"/push",
+		"/p",
+		"/skip",
+		"/files",
+		"/f",
+		"/issue",
+		"/i",
+	];
+
+	for (const cmd of agentCommands) {
+		it(`handles ${cmd} and injects to agent`, async () => {
+			const pi = mockPi();
+			const result = await handleCommand(cmd, pi as any, false);
+			expect(result.handled).toBe(true);
+			if (result.handled) expect(result.type).toBe("agent");
+			expect(pi.sendUserMessage).toHaveBeenCalledTimes(1);
+			expect(pi.getMessages()[0]).toContain("[COMMAND:");
+		});
+	}
+
+	it("handles commands case-insensitively", async () => {
+		const pi = mockPi();
+		const result = await handleCommand("/STOP", pi as any, false);
+		expect(result.handled).toBe(true);
+	});
+
+	it("handles commands with extra text", async () => {
+		const pi = mockPi();
+		const result = await handleCommand("/stop now please", pi as any, false);
+		expect(result.handled).toBe(true);
+	});
+
+	it("/issue injects full behavior spec", async () => {
+		const pi = mockPi();
+		await handleCommand("/issue", pi as any, false);
+		const injected = pi.getMessages()[0];
+		expect(injected).toContain("RESEARCH the project");
+		expect(injected).toContain("project_create_issue");
+		expect(injected).toContain("Do NOT ask permission to create");
+	});
+});
+
+// ── handleCommand — Unknown Commands ──────────────────────────────
+
+describe("handleCommand — unknown commands", () => {
+	it("returns not handled for unknown / slash inputs", async () => {
+		const pi = mockPi();
+		const result = await handleCommand("/foobar", pi as any, false);
+		expect(result.handled).toBe(false);
+		expect(pi.sendUserMessage).not.toHaveBeenCalled();
+	});
+
+	it("returns not handled for paths like /usr/bin/node", async () => {
+		const pi = mockPi();
+		const result = await handleCommand("/usr/bin/node", pi as any, false);
+		expect(result.handled).toBe(false);
+	});
+
+	it("returns not handled for empty string", async () => {
+		const pi = mockPi();
+		const result = await handleCommand("", pi as any, false);
+		expect(result.handled).toBe(false);
+	});
+});
+
+// ── handleCommand — Ack Behavior ──────────────────────────────────
+
+describe("handleCommand — ack behavior", () => {
+	it("sends ack when sendAck is true", async () => {
+		const pi = mockPi();
+		await handleCommand("/stop", pi as any, true);
+		expect(mockSendMsg).toHaveBeenCalledWith(
+			expect.stringContaining("Stopping"),
+		);
+	});
+
+	it("does not send ack when sendAck is false", async () => {
+		const pi = mockPi();
+		mockSendMsg.mockClear();
+		await handleCommand("/stop", pi as any, false);
+		expect(mockSendMsg).not.toHaveBeenCalled();
+	});
+});
+
+// ── Alias Disambiguation ──────────────────────────────────────────
+
+describe("alias disambiguation", () => {
+	it("/st maps to /status, not /stop", async () => {
+		const pi = mockPi();
+		const result = await handleCommand("/st", pi as any, false);
+		expect(result.handled).toBe(true);
+		if (result.handled) expect(result.type).toBe("bridge");
+	});
+
+	it("single-letter aliases map correctly", async () => {
+		const tests: Array<[string, string]> = [
+			["/s", "/stop"],
+			["/g", "/go"],
+			["/r", "/redo"],
+			["/c", "/commit"],
+			["/p", "/push"],
+			["/f", "/files"],
+			["/i", "/issue"],
+			["/h", "/help"],
+		];
+		for (const [_alias, _canonical] of tests) {
+			const pi = mockPi();
+			const result = await handleCommand(_alias, pi as any, false);
+			expect(result.handled).toBe(true);
+			if (result.handled) {
+				expect(["bridge", "agent"]).toContain(result.type);
+			}
+		}
+	});
+});

package/src/__tests__/helpers.test.ts

@@ -440,7 +440,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith('Hello agent!', '987654321');
+    expect(onMessage).toHaveBeenCalledWith("Hello agent!");
     expect(onUpdateId).toHaveBeenCalledWith(100);
   }, 15000);
 
@@ -618,7 +618,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith('recovered', '987654321');
+    expect(onMessage).toHaveBeenCalledWith("recovered");
   }, 20000);
 
   it("handles network errors with retry", async () => {
@@ -663,7 +663,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith('eventually', '987654321');
+    expect(onMessage).toHaveBeenCalledWith("eventually");
   }, 25000);
 
   it("stops gracefully when aborted immediately", async () => {
@@ -734,7 +734,7 @@ describe("pollUpdates", () => {
       controller.signal, onMessage, vi.fn(), onUpdateId,
     );
 
-    expect(onMessage).toHaveBeenCalledWith('after not-ok', '987654321');
+    expect(onMessage).toHaveBeenCalledWith("after not-ok");
   }, 20000);
 
   it("ignores messages without text field", async () => {

package/src/__tests__/index.test.ts

@@ -577,86 +577,4 @@ describe("session lifecycle", () => {
 		await new Promise((r) => setTimeout(r, 100));
 		expect(mockPollUpdates).toHaveBeenCalledTimes(1);
 	});
-
-	it("does not crash when TELEGRAM_BOT_TOKEN is not set (graceful degradation)", async () => {
-		vi.stubEnv("TELEGRAM_BOT_TOKEN", "");
-		vi.stubEnv("TELEGRAM_CHAT_ID", "");
-		const consoleWarn = vi
-			.spyOn(console, "warn")
-			.mockImplementation(() => {});
-
-		const pi = createMockPI();
-		telegramBridge(pi as any);
-
-		const ctx = {
-			sessionManager: { getEntries: () => [] },
-		};
-
-		// Should NOT throw
-		await expect(
-			pi._listeners["session_start"][0]({}, ctx),
-		).resolves.toBeUndefined();
-
-		// Should have warned about missing config
-		expect(consoleWarn).toHaveBeenCalledWith(
-			expect.stringContaining("TELEGRAM_BOT_TOKEN"),
-		);
-
-		// Listener should NOT have been started
-		expect(mockPollUpdates).not.toHaveBeenCalled();
-
-		consoleWarn.mockRestore();
-	});
-
-	it("does not crash when only TELEGRAM_BOT_TOKEN is missing", async () => {
-		vi.stubEnv("TELEGRAM_BOT_TOKEN", "");
-		// CHAT_ID is set
-		const consoleWarn = vi
-			.spyOn(console, "warn")
-			.mockImplementation(() => {});
-
-		const pi = createMockPI();
-		telegramBridge(pi as any);
-
-		const ctx = {
-			sessionManager: { getEntries: () => [] },
-		};
-
-		await expect(
-			pi._listeners["session_start"][0]({}, ctx),
-		).resolves.toBeUndefined();
-
-		expect(consoleWarn).toHaveBeenCalledWith(
-			expect.stringContaining("TELEGRAM_BOT_TOKEN"),
-		);
-		expect(mockPollUpdates).not.toHaveBeenCalled();
-
-		consoleWarn.mockRestore();
-	});
-
-	it("does not crash when only TELEGRAM_CHAT_ID is missing", async () => {
-		vi.stubEnv("TELEGRAM_CHAT_ID", "");
-		// BOT_TOKEN is set
-		const consoleWarn = vi
-			.spyOn(console, "warn")
-			.mockImplementation(() => {});
-
-		const pi = createMockPI();
-		telegramBridge(pi as any);
-
-		const ctx = {
-			sessionManager: { getEntries: () => [] },
-		};
-
-		await expect(
-			pi._listeners["session_start"][0]({}, ctx),
-		).resolves.toBeUndefined();
-
-		expect(consoleWarn).toHaveBeenCalledWith(
-			expect.stringContaining("TELEGRAM_BOT_TOKEN"),
-		);
-		expect(mockPollUpdates).not.toHaveBeenCalled();
-
-		consoleWarn.mockRestore();
-	});
 });

package/src/commands.ts

@@ -0,0 +1,285 @@
+/**
+ * pi-telegram-bridge — Slash Command Handler
+ *
+ * Detects slash-prefixed messages and either:
+ *   - Handles directly (bridge-only commands: /help, /status)
+ *   - Injects structured instruction to agent (control commands)
+ *   - Falls through for unknown commands (could be paths)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { sendMsg, getChatId } from "./helpers";
+import * as cp from "node:child_process";
+import * as util from "node:util";
+const execAsync = util.promisify(cp.exec);
+
+// ── Command Definitions ─────────────────────────────────────────────
+
+interface CommandDef {
+	name: string;
+	aliases: string[];
+	type: "bridge" | "agent";
+	description: string;
+	/** For agent-type commands: structured instruction injected to the agent */
+	inject?: string;
+	/** Acknowledgment sent back to Telegram */
+	ack: string;
+}
+
+const COMMANDS: CommandDef[] = [
+	{
+		name: "/stop",
+		aliases: ["/s"],
+		type: "agent",
+		description: "Pause current action at next safe point",
+		ack: "⏹ Stopping at next safe point...",
+		inject:
+			"[COMMAND: /stop]\n" +
+			"⚠️ Human requested you pause your current action. Stop at the next safe point and wait for further instructions.",
+	},
+	{
+		name: "/go",
+		aliases: ["/g"],
+		type: "agent",
+		description: "Proceed with current plan",
+		ack: "▶️ Proceeding...",
+		inject:
+			"[COMMAND: /go]\n" +
+			"✅ Human confirmed — proceed with your current plan.",
+	},
+	{
+		name: "/sum",
+		aliases: [],
+		type: "agent",
+		description: "Give a 3-bullet summary of current work",
+		ack: "📋 Summarizing...",
+		inject:
+			"[COMMAND: /sum]\n" +
+			"📋 SUMMARIZE: Give a quick 3-bullet summary of what you're doing right now — current task, progress, next step.",
+	},
+	{
+		name: "/redo",
+		aliases: ["/r"],
+		type: "agent",
+		description: "Retry last failed action",
+		ack: "🔄 Retrying last failed action...",
+		inject: "[COMMAND: /redo]\n" + "🔄 REDO: Retry your last failed action.",
+	},
+	{
+		name: "/commit",
+		aliases: ["/c"],
+		type: "agent",
+		description: "Commit current changes (checkpoint)",
+		ack: "📦 Committing changes...",
+		inject:
+			"[COMMAND: /commit]\n" +
+			"📦 COMMIT: This is a good checkpoint — commit your current staged/working changes now via contrib_propose.",
+	},
+	{
+		name: "/push",
+		aliases: ["/p"],
+		type: "agent",
+		description: "Push commits",
+		ack: "🚀 Pushing...",
+		inject: "[COMMAND: /push]\n" + "🚀 PUSH: Push your commits now.",
+	},
+	{
+		name: "/skip",
+		aliases: [],
+		type: "agent",
+		description: "Skip current step, move to next",
+		ack: "⏭ Skipping current step...",
+		inject:
+			"[COMMAND: /skip]\n" +
+			"⏭ SKIP: Skip the current step and move on to what's next.",
+	},
+	{
+		name: "/files",
+		aliases: ["/f"],
+		type: "agent",
+		description: "List modified files",
+		ack: "📁 Listing modified files...",
+		inject:
+			"[COMMAND: /files]\n" +
+			"📁 FILES: List what files you've modified so far in this session.",
+	},
+	{
+		name: "/issue",
+		aliases: ["/i"],
+		type: "agent",
+		description: "Create an issue from session context",
+		ack: "🎫 Creating issue from session context...",
+		inject:
+			"[COMMAND: /issue]\n" +
+			"🎫 Create a well-structured issue from the current session context. Follow this workflow:\n" +
+			"\n" +
+			"1. READ the session context — review conversation history, current branch, modified files.\n" +
+			"2. RESEARCH the project — read README, AGENTS.md, check for duplicate issues via project_list_issues.\n" +
+			"3. DECIDE if clarification is genuinely needed:\n" +
+			"   - YES only if: scope is ambiguous, multiple valid approaches exist, or critical info is missing.\n" +
+			"   - NO if: problem is clear from context, you can infer a good title and body.\n" +
+			"4. If NO clarification needed: draft the issue with a clear conventional title and structured body, create it via project_create_issue, share the ID and URL.\n" +
+			"5. If YES clarification needed: ask 1-2 focused questions via telegram_ask, then create the issue.\n" +
+			"6. NOTIFY the human via telegram_notify(kind='issue') with the created issue details.\n" +
+			"\n" +
+			"CRITICAL: Do NOT ask permission to create — /issue IS permission. Limit clarification to 1 round max. If no context found, say so and ask for a title.",
+	},
+	{
+		name: "/help",
+		aliases: ["/h"],
+		type: "bridge",
+		description: "Show available commands",
+		ack: "📖 Sending command list...",
+	},
+	{
+		name: "/status",
+		aliases: ["/st"],
+		type: "bridge",
+		description: "Show session status",
+		ack: "📊 Checking session status...",
+	},
+];
+
+// ── Lookup ──────────────────────────────────────────────────────────
+
+/** Case-insensitive, aliases included. Returns the canonical CommandDef. */
+function findCommand(input: string): CommandDef | null {
+	const normalized = input.trim().toLowerCase();
+	// Exact match on name or any alias
+	for (const cmd of COMMANDS) {
+		if (normalized === cmd.name || cmd.aliases.includes(normalized)) {
+			return cmd;
+		}
+	}
+	// Also match prefix if it starts with the command name followed by space or end
+	// e.g. "/stop now please" should match /stop
+	const firstWord = normalized.split(/\s+/)[0];
+	for (const cmd of COMMANDS) {
+		if (firstWord === cmd.name || cmd.aliases.includes(firstWord)) {
+			return cmd;
+		}
+	}
+	return null;
+}
+
+// ── Bridge-Handled Commands ────────────────────────────────────────
+
+async function handleHelp(): Promise<string> {
+	const lines: string[] = ["<b>⌨️ Available Commands</b>\n"];
+	lines.push("<b>━━━━━━━━━━━━━━━━━━━━</b>\n");
+
+	lines.push("<b>🎛 Control</b>");
+	for (const cmd of COMMANDS.filter((c) => c.type === "agent")) {
+		const aliases = cmd.aliases.length > 0 ? cmd.aliases.join(" ") + " " : "";
+		lines.push(`  <code>${aliases}${cmd.name}</code> — ${cmd.description}`);
+	}
+
+	lines.push("\n<b>ℹ️ Info</b>");
+	for (const cmd of COMMANDS.filter((c) => c.type === "bridge")) {
+		const aliases = cmd.aliases.length > 0 ? cmd.aliases.join(" ") + " " : "";
+		lines.push(`  <code>${aliases}${cmd.name}</code> — ${cmd.description}`);
+	}
+
+	return lines.join("\n");
+}
+
+async function handleStatus(): Promise<string> {
+	let branch = "unknown";
+	try {
+		const { stdout } = await execAsync("git rev-parse --abbrev-ref HEAD", {
+			timeout: 3000,
+		});
+		branch = stdout.trim();
+	} catch {
+		/* ignore */
+	}
+
+	let nodeVersion = "unknown";
+	try {
+		nodeVersion = process.version;
+	} catch {
+		/* ignore */
+	}
+
+	const lines: string[] = [];
+	lines.push("<b>📊 Session Status</b>");
+	lines.push("<b>━━━━━━━━━━━━━━━━━━━━</b>");
+	lines.push(`<b>Branch:</b> <code>${escapeHtmlCmd(branch)}</code>`);
+	lines.push(`<b>Node:</b> <code>${escapeHtmlCmd(nodeVersion)}</code>`);
+	lines.push(`<b>Chat ID:</b> <code>${escapeHtmlCmd(getChatId())}</code>`);
+
+	// Uptime from process
+	const uptime = Math.floor(process.uptime());
+	const mins = Math.floor(uptime / 60);
+	const hrs = Math.floor(mins / 60);
+	const uptimeStr =
+		hrs > 0 ? `${hrs}h ${mins % 60}m` : `${mins}m ${uptime % 60}s`;
+	lines.push(`<b>Process uptime:</b> <code>${uptimeStr}</code>`);
+
+	return lines.join("\n");
+}
+
+function escapeHtmlCmd(s: string): string {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// ── Main Handler ────────────────────────────────────────────────────
+
+export type CommandResult =
+	| { handled: true; type: "bridge" }
+	| { handled: true; type: "agent" }
+	| { handled: false };
+
+/**
+ * Process a slash command from a Telegram message.
+ *
+ * @param text - The raw message text (e.g., "/stop" or "/status")
+ * @param pi - ExtensionAPI for injecting agent messages
+ * @param sendAck - Whether to send an acknowledgment to Telegram
+ * @returns Result indicating how the command was handled
+ */
+export async function handleCommand(
+	text: string,
+	pi: ExtensionAPI,
+	sendAck = true,
+): Promise<CommandResult> {
+	const cmd = findCommand(text);
+	if (!cmd) return { handled: false };
+
+	// Send acknowledgment
+	if (sendAck) {
+		await sendMsg(cmd.ack).catch(() => {});
+	}
+
+	if (cmd.type === "bridge") {
+		if (cmd.name === "/help") {
+			const helpText = await handleHelp();
+			await sendMsg(helpText, undefined, "HTML").catch(() => {});
+		} else if (cmd.name === "/status") {
+			const statusText = await handleStatus();
+			await sendMsg(statusText, undefined, "HTML").catch(() => {});
+		}
+		return { handled: true, type: "bridge" };
+	}
+
+	// Agent-directed: inject structured instruction
+	if (cmd.inject) {
+		pi.sendUserMessage(cmd.inject);
+	}
+	return { handled: true, type: "agent" };
+}
+
+/**
+ * Check if a message starts with a slash (potential command).
+ * Used as a quick pre-filter before calling handleCommand.
+ */
+export function isPossibleCommand(text: string): boolean {
+	return text.trimStart().startsWith("/");
+}
+
+/**
+ * Get all command definitions (for /help formatting).
+ */
+export function getCommands(): CommandDef[] {
+	return COMMANDS;
+}

package/src/helpers.ts

@@ -57,11 +57,7 @@ export async function sendMsg(
 	} 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"))
-		) {
+		if (parseMode && msg.includes("400") && (msg.includes("parse") || msg.includes("entity"))) {
 			delete body.parse_mode;
 			const r2 = (await telegramApi("sendMessage", body)) as {
 				ok: boolean;
@@ -70,8 +66,7 @@ export async function sendMsg(
 			return r2.result.message_id;
 		}
 		throw e;
-	}
-}
+	}}
 
 // ── Photo / File Support ────────────────────────────────────────────
 
@@ -82,11 +77,14 @@ export async function sendMsg(
 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 }),
-		});
+		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;
@@ -104,10 +102,7 @@ export async function getFileUrl(fileId: string): Promise<string | null> {
  * Returns the file path on success, null on failure.
  * Creates parent directories automatically.
  */
-export async function downloadFile(
-	fileId: string,
-	destPath: string,
-): Promise<string | null> {
+export async function downloadFile(fileId: string, destPath: string): Promise<string | null> {
 	try {
 		const fileUrl = await getFileUrl(fileId);
 		if (!fileUrl) return null;
@@ -151,7 +146,7 @@ export async function sendPhoto(
 	const token = getToken();
 	const formData = new FormData();
 	formData.set("chat_id", getChatId());
-	const blob = new Blob([fileData]);
+	const blob = new Blob([fileData] as any);
 	formData.set("photo", blob, filename);
 	if (caption) {
 		formData.set("caption", caption);
@@ -167,11 +162,7 @@ export async function sendPhoto(
 	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"))
-		) {
+		if (caption && res.status === 400 && (errText.includes("parse") || errText.includes("entity"))) {
 			return sendPhoto(photoPath);
 		}
 		throw new Error(`sendPhoto failed: ${res.status} ${errText}`);
@@ -317,7 +308,7 @@ export async function pollUpdates(
 	botId: number | null,
 	lastUpdateId: number,
 	signal: AbortSignal,
-	onMessage: (text: string, msgChatId: string) => void,
+	onMessage: (text: string) => void,
 	onPhoto: (photoId: string, caption?: string) => void,
 	onUpdateId: (id: number) => void,
 ): Promise<void> {
@@ -342,12 +333,7 @@ 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;
-						}>;
+						photo?: Array<{ file_id: string; file_unique_id: string; width: number; height: number }>;
 						caption?: string;
 					};
 					callback_query?: unknown;
@@ -363,7 +349,10 @@ export async function pollUpdates(
 				// Skip callback queries (handled by telegram_ask)
 				if (u.callback_query) continue;
 				// Process messages from the configured chat, not from our bot
-				if (u.message && 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;
 					}
@@ -375,7 +364,7 @@ export async function pollUpdates(
 					}
 					// Text message
 					if (u.message.text) {
-						onMessage(u.message.text, String(u.message.chat.id));
+						onMessage(u.message.text);
 					}
 				}
 			}

package/src/index.ts

@@ -32,149 +32,12 @@ import {
 	notifySchema,
 	sendPhotoSchema,
 } from "./tools/telegram";
+import { handleCommand, isPossibleCommand } from "./commands";
 
 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 ───────────────────────────────────────────
 
@@ -189,23 +52,8 @@ export default function telegramBridge(pi: ExtensionAPI) {
 				lastUpdateId = (entry.data as { update_id: number }).update_id;
 			}
 		}
-		// Skip listener if Telegram is not configured
-		if (!process.env.TELEGRAM_BOT_TOKEN || !process.env.TELEGRAM_CHAT_ID) {
-			console.warn(
-				"pi-telegram-bridge: TELEGRAM_BOT_TOKEN or TELEGRAM_CHAT_ID not set. Listener disabled.",
-			);
-			return;
-		}
 		// Start background listener
-		try {
-			mentionTrigger = await resolveMentionTrigger();
-			startListener();
-		} catch (e: unknown) {
-			console.warn(
-				"pi-telegram-bridge: Failed to start listener:",
-				e instanceof Error ? e.message : e,
-			);
-		}
+		startListener();
 	});
 
 	pi.on("session_shutdown", () => {
@@ -242,21 +90,16 @@ export default function telegramBridge(pi: ExtensionAPI) {
 			botId,
 			lastUpdateId,
 			signal,
-			// 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;
+			// onMessage: check for slash commands first, otherwise forward to pi
+			async (text: string) => {
+				if (isPossibleCommand(text)) {
+					const result = await handleCommand(text, pi, true);
+					if (result.handled) return; // bridge or agent handled it
+					// Unknown command — fall through to forward as regular message
 				}
-				messageCount++;
-				pi.sendUserMessage(cleanedText);
+				pi.sendUserMessage(text);
 				await sendMsg(
-					`👂 Got it! Working on: _${cleanedText.slice(0, 100)}_`,
+					`👂 Got it! Working on: _${text.slice(0, 100)}_`,
 					undefined,
 					"Markdown",
 				);
@@ -395,14 +238,39 @@ export default function telegramBridge(pi: ExtensionAPI) {
 						}
 						// Text message
 						if (u.message.text) {
+							const text = u.message.text;
+							// Check for slash commands
+							if (isPossibleCommand(text)) {
+								const result = await handleCommand(text, pi, false);
+								if (result.handled) {
+									const label =
+										result.type === "bridge"
+											? "(handled by bridge)"
+											: "(injected to agent)";
+									return {
+										content: [
+											{
+												type: "text",
+												text: `🔧 Command processed: "${text}" ${label}`,
+											},
+										],
+										details: {
+											message: text,
+											command: true,
+											commandType: result.type,
+										},
+									};
+								}
+								// Unknown command — fall through to return as regular message
+							}
 							return {
 								content: [
 									{
 										type: "text",
-										text: `📩 New message: "${u.message.text}"`,
+										text: `📩 New message: "${text}"`,
 									},
 								],
-								details: { message: u.message.text },
+								details: { message: text },
 							};
 						}
 					}

package/src/templates.ts

@@ -12,7 +12,10 @@ const BAR = "━".repeat(20);
 
 /** Escape user text for safe embedding inside HTML tags. */
 function escapeHtml(s: string): string {
-	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
 }
 
 function bold(s: string) {
@@ -28,7 +31,7 @@ function strike(s: string) {
 	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}">${escapeHtml(text)}</a>`;
@@ -254,7 +257,7 @@ export function ciPipeline(p: CIPipeline): string {
 	msg += `${BAR}\n`;
 	msg += labelValue("Run", `#${p.runNumber}`) + "\n";
 	msg += labelValue("Branch", code(p.branch)) + "\n";
-	msg += labelValue("Trigger", escapeHtml(p.event)) + "\n";
+	msg += labelValue("Trigger", p.event) + "\n";
 	if (p.triggeredBy) msg += labelValue("By", code(p.triggeredBy)) + "\n";
 	msg += `${BAR}\n`;