pi-telegram-plus 0.0.1

package/README.md

@@ -0,0 +1,318 @@
+# pi-telegram-plus
+
+**Full Telegram control of [pi coding agent](https://github.com/earendil-works/pi-coding-agent) — commands, interactive UI, model/session management, file transfer, and real-time streaming output, all from Telegram.**
+
+`pi-telegram-plus` is a pi extension that turns Telegram into a full-featured remote control surface for the pi coding agent. It's not just a notification bot — it mirrors the core pi TUI experience into Telegram, with interactive menus, inline keyboards, file attachments, and live agent output rendering.
+
+---
+
+## Features
+
+### 🤖 Bot Connectivity
+- **Long polling** — receives messages and callback queries in real time
+- **Multi-instance safe** — file-based polling lock prevents multiple pi instances from racing on the same bot token
+- **Automatic reconnection** — exponential backoff on transient failures
+- **Bot command menu sync** — automatically syncs available commands to Telegram's BotMenu (up to 100 commands)
+
+### 🎮 Full Session Control
+All pi session lifecycle commands available via Telegram:
+
+| Command | Description |
+|---------|-------------|
+| `/new` | Start a new session |
+| `/fork` | Fork from a previous user message |
+| `/clone` | Clone at a previous user message |
+| `/tree` | Navigate session tree |
+| `/resume` | Resume a previous session |
+| `/compact` | Compact session context |
+| `/name` | Set or show session name |
+| `/session` | Show session statistics |
+
+### 🧠 Model & Authentication Management
+- `/model` — View available models / switch current model via interactive selection
+- `/scoped-models` — Toggle scoped model sets
+- `/thinking` — Adjust thinking level (off/minimal/low/medium/high/xhigh)
+- `/login` — OAuth or API key authentication with full interactive flow
+- `/logout` — Remove stored credentials
+
+### 📨 Message Modes
+Two modes for handling incoming messages while the agent is running:
+
+- **`steer`** (default) — New messages inject into the current turn via `streamingBehavior: "steer"`. The agent stays streaming while receiving new input.
+- **`queue`** — Messages wait in a per-chat queue for the current turn to finish.
+
+### 🖥️ Interactive Telegram UI
+Full interactive UI components built on inline keyboards:
+
+- **Notify** — status/error messages
+- **Confirm** — Yes / No / Cancel buttons
+- **Input** — text input with Cancel button; replies are captured as input
+- **InputSecret** — same as Input, but the prompt message is auto-deleted after reply to protect sensitive data
+- **Select** — paginated option list with Prev/Next navigation
+- **Editor** — multi-line text input prompt
+
+### 🎨 Message Rendering
+- **Markdown → Telegram HTML** — Full conversion via `marked` (tables, code blocks, blockquotes, lists, inline formatting)
+- **Tool execution rendering** — Configurable level (`hidden` / `brief` / `full`) for tool call visibility
+- **Thinking rendering** — Configurable level (`hidden` / `brief` / `full`) for agent thinking blocks
+- **Output splitting** — Safe UTF-8-aware splitting at Telegram's 4096-byte limit
+- **Image output** — Automatically sends agent-generated images as Telegram photos
+
+### 📎 File Attachments
+
+**Upload (agent → Telegram):**
+- Custom `tg_attach` tool available to the agent
+- Sends files/documents/photos to the active Telegram chat
+- Size limit enforcement (default 50 MB)
+- Sensitive path blocking (e.g., `/etc`, `~/.ssh`)
+- Automatic photo detection (jpg/png/webp → send as photo, fallback to document)
+
+**Download (Telegram → user → agent):**
+- Automatically saves incoming photos, documents, videos, audio, voice, stickers to the working directory
+- Reports saved paths back to the user
+- Handles name sanitization and deduplication
+
+### ⚙️ Telegram-Specific Commands
+
+| Command | Description |
+|---------|-------------|
+| `/tg-setup` | Configure Telegram bot token (first-time setup) |
+| `/tg-connect` | Enable / start Telegram connection |
+| `/tg-disconnect` | Disable / stop connection (keeps token) |
+| `/tg-config` | Configure rendering levels and message mode |
+| `/tg-bind-cwd` | Bind a workspace directory to a separate bot token |
+| `/tg-unbind-cwd` | Remove workspace bot binding |
+| `/tg-list` | List all Telegram bot bindings |
+
+### 🔧 Utility Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cwd` | Show current working directory |
+| `/cd` | Switch pi working directory |
+| `/stop` | Abort the current agent turn |
+| `/debug` | Show debug info (model, thinking, streaming, entries) |
+| `/settings` | Open settings menu |
+| `/copy` | Copy last assistant text |
+| `/export` | Export session to HTML/JSONL |
+| `/import` | Import a session JSONL file |
+| `/share` | Export session for sharing (gist) |
+| `/reload` | Reload extensions, skills, prompts |
+| `/quit` | Shut down pi |
+| `/changelog` | Show changelog link |
+| `/hotkeys` | Show keyboard shortcuts reference |
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 22.19.0
+- [pi coding agent](https://github.com/earendil-works/pi-coding-agent) installed globally
+- A Telegram bot token from [@BotFather](https://t.me/BotFather)
+
+### Setup
+
+1. **Clone or create the extension directory:**
+
+```bash
+git clone <repo-url> pi-telegram-plus
+cd pi-telegram-plus
+npm install
+```
+
+2. **Configure pi to load the extension:**
+
+```bash
+# Inside the pi-telegram-plus directory
+pi packages add .
+```
+
+This registers the extension via `.pi/settings.json`.
+
+3. **Start pi and configure your Telegram bot:**
+
+```bash
+pi
+```
+
+Inside pi, run:
+
+```
+/tg-setup
+```
+
+Paste your bot token when prompted. The bot will connect automatically.
+
+> **Note:** On first message from any user, pi-telegram-plus automatically authorizes that user ID. Only that user can control the bot afterward.
+
+---
+
+## Configuration
+
+### Per-Workspace Bot Tokens
+
+You can bind different bot tokens to different directories:
+
+```
+/tg-bind-cwd /path/to/project
+```
+
+This creates a workspace-specific binding in `~/.pi/agent/tg.json`. Workspace bindings take priority over the global configuration.
+
+### Rendering & Mode Settings
+
+Via interactive menu:
+
+```
+/tg-config
+```
+
+Or directly:
+
+```
+/tg-config tool brief       # Tool rendering: hidden | brief | full
+/tg-config thinking full    # Thinking rendering: hidden | brief | full
+/tg-config mode steer       # Message mode: queue | steer
+/tg-config retry 3          # API retry count: 0-10
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────────┐     Long Polling      ┌──────────────────────┐
+│   Telegram Bot   │ ◄──────────────────► │  pi-telegram-plus    │
+│  (api.telegram)  │     Callback Queries  │  (pi extension)      │
+└─────────────────┘                       │                      │
+        ▲                                 │  ┌────────────────┐  │
+        │ Messages / Files                │  │  Controller     │  │
+        │                                 │  │  ├─ handleMsg   │  │
+  ┌─────────┐                            │  │  ├─ handleCB    │  │
+  │  User    │                            │  │  └─ runPrompt   │  │
+  │ (Telegram)│                           │  │                  │  │
+  └─────────┘                            │  │  ┌─────────────┐ │  │
+        ▲                                │  │  │ TelegramUI  │ │  │
+        │ Streaming Output               │  │  │ (interactive)│ │  │
+        │ Live Tool/Thinking Events      │  │  └─────────────┘ │  │
+        │ File Attachments (tg_attach)   │  │                  │  │
+        └───────────────────────────────────┤  ┌─────────────┐ │  │
+                                          │  │  Renderer    │ │  │
+                                          │  │  (Markdown→  │ │  │
+                                          │  │   Telegram   │ │  │
+                                          │  │   HTML)      │ │  │
+                                          │  └─────────────┘ │  │
+                                          │         │         │  │
+                                          │         ▼         │  │
+                                          │  ┌─────────────┐  │  │
+                                          │  │ pi Agent    │  │  │
+                                          │  │ (session,   │  │  │
+                                          │  │ models,     │  │  │
+                                          │  │ tools, ...) │  │  │
+                                          │  └─────────────┘  │  │
+                                          └──────────────────────┘
+```
+
+### Architecture Overview
+
+- **`index.ts`** — Extension entry point. Wires all modules together and handles `session_start`/`session_shutdown` lifecycle events.
+- **`lib/telegram-api.ts`** — Raw Telegram Bot API client with retry logic and file upload/download.
+- **`lib/polling.ts`** — Long polling loop with multi-instance file lock. Re-reads config while holding the lock to prevent offset regressions.
+- **`lib/controller.ts`** — Message routing: slash commands, text prompts, media attachments, callback queries.
+- **`lib/telegram-ui.ts`** — Interactive UI layer: notify, confirm, input, select (pagination), editor.
+- **`lib/renderer.ts`** — Hooks into agent lifecycle events (`agent_start`, `tool_execution_*`, `message_end`) and streams rendered output to Telegram.
+- **`lib/markdown.ts`** — Custom `marked` renderer that converts Markdown to Telegram-compatible HTML.
+- **`lib/config.ts`** — Configuration persistence with file locking for concurrent-safe writes. Supports global + workspace scopes.
+- **`lib/attachments.ts`** — `tg_attach` tool registration and outbound attachment delivery.
+- **`lib/commands/`** — Command handler modules: model, session, auth (login/logout), lifecycle, settings, tg-config, telegram-commands.
+- **`lib/heartbeat.ts`** — Periodic typing indicator while processing.
+- **`lib/status.ts`** — TUI status line integration showing connection state.
+- **`lib/session-capture.ts`** — Monkeys patches `AgentSession.bindExtensions` to intercept session lifecycle and capture the active session reference.
+- **`lib/menu-commands.ts`** — Builds and syncs the Telegram BotMenu command list.
+- **`lib/callback-protocol.ts`** — Encodes/decodes inline button callback data.
+
+---
+
+## Project Structure
+
+```
+pi-telegram-plus/
+├── index.ts                     # Extension entry point
+├── pi-host.d.ts                 # Type augmentation for @earendil-works/pi-ai
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── .pi/
+│   └── settings.json            # pi package registration
+└── lib/
+    ├── types.ts                 # All TypeScript interfaces & types
+    ├── telegram-api.ts          # Telegram Bot HTTP API client
+    ├── polling.ts               # Long polling with multi-instance lock
+    ├── controller.ts            # Message router & prompt executor
+    ├── telegram-ui.ts           # Interactive UI (notify, confirm, input, select)
+    ├── renderer.ts              # Agent event → Telegram output renderer
+    ├── markdown.ts              # Markdown → Telegram HTML converter
+    ├── html.ts                  # HTML escaping utilities
+    ├── text-split.ts            # UTF-8-safe text splitter for 4096 byte limit
+    ├── command-parser.ts        # Slash command parser & bot-username normalizer
+    ├── config.ts                # Configuration store (global + workspace scopes)
+    ├── attachments.ts           # Outbound file attachment tool (tg_attach)
+    ├── heartbeat.ts             # Typing indicator pulse
+    ├── status.ts                # TUI status line formatter
+    ├── session-capture.ts       # Agent session capture & handler patching
+    ├── menu-commands.ts         # Telegram BotMenu sync
+    ├── callback-protocol.ts     # UI callback encoding/decoding
+    ├── commands/
+    │   ├── register.ts          # Command registry aggregator
+    │   ├── model.ts             # /model, /scoped-models, /thinking
+    │   ├── session.ts           # /new, /fork, /clone, /tree, /resume, /cd, /cwd, /name, /session
+    │   ├── auth.ts              # /login (OAuth + API key), /logout
+    │   ├── info.ts              # /copy, /export, /import, /share, /changelog, /hotkeys, /debug
+    │   ├── lifecycle.ts         # /compact, /reload, /stop, /quit
+    │   ├── settings.ts          # /settings menu
+    │   ├── tg-config.ts         # /tg-config
+    │   └── telegram-commands.ts # /tg-setup, /tg-connect, /tg-disconnect, /tg-bind-cwd, /tg-list
+    └── __tests__/
+        ├── attachments.test.ts
+        ├── callback-protocol.test.ts
+        ├── config.test.ts
+        ├── controller.test.ts
+        ├── html.test.ts
+        ├── markdown.test.ts
+        ├── status.test.ts
+        └── text-split.test.ts
+```
+
+---
+
+## Development
+
+```bash
+# Type checking
+npm run typecheck
+
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+```
+
+---
+
+## Security
+
+- **No secrets in source code** — All bot tokens and API keys are read from `~/.pi/agent/tg.json` and `~/.pi/agent/auth.json` at runtime.
+- **File permissions** — Configuration files are created with `chmod 600` (owner-only access).
+- **Sensitive input protection** — API key inputs use `inputSecret` which automatically deletes the user's message after reading.
+- **Attachment path safety** — Outbound `tg_attach` blocks sensitive paths (`/etc`, `~/.ssh`, etc.).
+- **Polling lock** — File-based lock prevents multiple pi instances from polling the same bot token simultaneously.
+- **First-user authorization** — The first Telegram user to message the bot is automatically authorized; subsequent users are rejected.
+
+---
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,327 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTelegramAttachmentTool } from "./lib/attachments.ts";
+import { readResolvedTelegramConfig, writeResolvedTelegramConfig } from "./lib/config.ts";
+import { createTelegramController, type TelegramCommandHandler } from "./lib/controller.ts";
+import { createHeartbeat } from "./lib/heartbeat.ts";
+import { registerTelegramRenderer } from "./lib/renderer.ts";
+import { getActiveSession, installAgentSessionCapture } from "./lib/session-capture.ts";
+import { createTelegramTransport, downloadTelegramFile, getTelegramBotUsername, getTelegramFile } from "./lib/telegram-api.ts";
+import { createTelegramUiRuntime } from "./lib/telegram-ui.ts";
+import { formatTelegramStatusLine, clearTelegramStatus, TELEGRAM_STATUS_KEY } from "./lib/status.ts";
+import { createTelegramPollingRuntime } from "./lib/polling.ts";
+import { registerAllCommands } from "./lib/commands/register.ts";
+import { registerTelegramCommands } from "./lib/commands/telegram-commands.ts";
+import { syncTelegramCommands } from "./lib/menu-commands.ts";
+import type { ResolvedTelegramConfig, TelegramConfig, TelegramTurn } from "./lib/types.ts";
+
+type TelegramPlusRuntimeState = {
+  dispose?: () => void;
+};
+
+const TELEGRAM_PLUS_RUNTIME_STATE = Symbol.for("pi-telegram-plus.runtime-state");
+
+function getTelegramPlusRuntimeState(): TelegramPlusRuntimeState {
+  const g = globalThis as typeof globalThis & Record<symbol, TelegramPlusRuntimeState | undefined>;
+  g[TELEGRAM_PLUS_RUNTIME_STATE] ??= {};
+  return g[TELEGRAM_PLUS_RUNTIME_STATE];
+}
+
+export default function piTelegramPlus(pi: ExtensionAPI): void {
+  installAgentSessionCapture();
+  const runtimeState = getTelegramPlusRuntimeState();
+  runtimeState.dispose?.();
+
+  let config: TelegramConfig = {};
+  let resolvedConfig: ResolvedTelegramConfig | undefined;
+  // Per-chat active turns: prevents interleaving across chats and allows
+  // beginTelegramTurn to reject when a chat is already busy.
+  const activeTurns = new Map<number, TelegramTurn>();
+  let lastStatusError: string | undefined;
+
+  const setConfig = (nextConfig: TelegramConfig) => {
+    config = nextConfig;
+    if (resolvedConfig) resolvedConfig.config = nextConfig;
+    refreshStatus();
+  };
+
+  const currentSessionCwd = (): string => {
+    const session = getActiveSession();
+    return session?.extensionRunner?.createCommandContext?.().cwd ?? process.cwd();
+  };
+
+  const sanitizeIncomingFileName = (value: string): string => {
+    const trimmed = value.trim().replace(/\.[^./\\]+$/, "");
+    const sanitized = trimmed
+      .replace(/[^a-zA-Z0-9._-]/g, "_")
+      .replace(/_+/g, "_");
+    const compact = sanitized.replace(/^\.+/, "").replace(/\.+$/, "");
+    return compact.slice(0, 120) || "attachment";
+  };
+
+  const inferIncomingExtension = (fileName: string | undefined, filePath: string | undefined): string => {
+    const source = filePath || fileName;
+    if (!source) return ".bin";
+    const extension = extname(source).toLowerCase();
+    return extension || ".bin";
+  };
+
+  const buildIncomingAttachmentPath = (fileId: string, fileName: string | undefined, filePath: string): string => {
+    const ext = inferIncomingExtension(fileName, filePath);
+    const base = fileName
+      ? sanitizeIncomingFileName(fileName)
+      : sanitizeIncomingFileName(filePath || "telegram-file");
+    const safeFileId = fileId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return resolve(currentSessionCwd(), `${Date.now()}-${safeFileId.slice(0, 18)}-${base}${ext}`);
+  };
+
+  const persistCurrentConfig = async (nextConfig = config): Promise<void> => {
+    if (!resolvedConfig) resolvedConfig = await readResolvedTelegramConfig(currentSessionCwd());
+    resolvedConfig = await writeResolvedTelegramConfig(resolvedConfig, nextConfig);
+    config = resolvedConfig.config;
+  };
+
+  const switchResolvedConfig = (next: ResolvedTelegramConfig) => {
+    resolvedConfig = next;
+    config = next.config;
+    refreshStatus();
+  };
+
+  const isTelegramEnabled = (): boolean => config.telegramEnabled ?? resolvedConfig?.scope !== "global";
+
+  const transport = createTelegramTransport(() => config);
+  const ui = createTelegramUiRuntime({
+    getSession: getActiveSession,
+    transport,
+  });
+
+  const heartbeat = createHeartbeat({
+    getConfig: () => config,
+    getActiveTurn: () => { for (const turn of activeTurns.values()) return turn; return undefined; },
+    sendChatAction: (chatId, action) => transport.sendChatAction(chatId, action),
+    ensurePollingStarted: () => { if (config.botToken && isTelegramEnabled() && !polling.isActive()) polling.start(); },
+  });
+
+  const telegramCommands = new Map<string, TelegramCommandHandler>();
+  const sessionDeps = { getSession: getActiveSession };
+  const sessionNameDeps = {
+    ...sessionDeps,
+    setSessionName: (name: string) => { const s = getActiveSession(); if (s) pi.setSessionName(name); },
+    getSessionName: () => pi.getSessionName(),
+  };
+  const tgConfigDeps = {
+    ...sessionDeps,
+    getConfig: () => config,
+    setConfig,
+    persistConfig: persistCurrentConfig,
+  };
+
+  // Custom pi-telegram-plus commands that should also appear in the TUI slash menu.
+  // Pi built-in commands (model, session, new, etc.) are already registered by pi core.
+  const TUI_VISIBLE_COMMANDS = new Set([
+    // tg-* commands
+    "tg-setup", "tg-connect", "tg-disconnect", "tg-config",
+    "tg-bind-cwd", "tg-unbind-cwd", "tg-list",
+    // other pi-telegram-plus custom commands (TUI-only command list excludes /import, which is now
+    // a built-in pi command; keep Telegram handler registration only.
+    "cwd", "cd", "thinking", "stop", "debug",
+  ]);
+
+  registerAllCommands({
+    registerCommand: (name: string, options: { description?: string; handler: TelegramCommandHandler }) => {
+      telegramCommands.set(name, options.handler);
+      if (TUI_VISIBLE_COMMANDS.has(name) && options.description) {
+        pi.registerCommand(name, { description: options.description, handler: options.handler });
+      }
+    },
+  }, sessionDeps, sessionNameDeps, tgConfigDeps);
+
+  registerTelegramCommands({
+    registerCommand: (name: string, options: { description?: string; handler: TelegramCommandHandler }) => {
+      telegramCommands.set(name, options.handler);
+      if (options.description) {
+        pi.registerCommand(name, { description: options.description, handler: options.handler });
+      }
+    },
+  }, {
+    getConfig: () => config,
+    setConfig,
+    persistConfig: persistCurrentConfig,
+    getResolvedConfig: () => resolvedConfig,
+    switchResolvedConfig,
+    isTelegramEnabled,
+    transport,
+    getPolling: () => polling,
+    refreshStatus,
+    syncTelegramCommands: () => syncTelegramCommands(config.botToken, pi),
+    startStatusHeartbeat: () => heartbeat.startStatusHeartbeat(refreshStatus),
+    clearStatusError: () => { lastStatusError = undefined; },
+  });
+
+  registerTelegramAttachmentTool(pi, {
+    getActiveTurn: () => { for (const turn of activeTurns.values()) return turn; return undefined; },
+    getDefaultChatId: () => config.activeChatId,
+    transport,
+  });
+
+  registerTelegramRenderer(pi, {
+    getConfig: () => config,
+    transport,
+    getActiveTurn: (chatId?: number) => {
+      if (chatId !== undefined) return activeTurns.get(chatId);
+      for (const turn of activeTurns.values()) return turn;
+      return undefined;
+    },
+  });
+
+  const controller = createTelegramController({
+    getSession: getActiveSession,
+    transport,
+    ui,
+    authorizeUser: async (userId) => {
+      if (userId === undefined) return false;
+      if (config.allowedUserId === undefined) {
+        config = { ...config, allowedUserId: userId };
+        await persistCurrentConfig(config);
+        refreshStatus();
+      }
+      return config.allowedUserId === userId;
+    },
+    telegramCommands,
+    saveIncomingTelegramAttachment: async (fileId, fileName, kind) => {
+      const token = config.botToken;
+      if (!token) {
+        throw new Error("Telegram bot token is not configured");
+      }
+      const fileInfo = await getTelegramFile(token, fileId);
+      const data = await downloadTelegramFile(token, fileInfo.file_path);
+      await mkdir(currentSessionCwd(), { recursive: true });
+      const candidateName = buildIncomingAttachmentPath(fileId, fileName || kind, fileInfo.file_path);
+      const outputPath = candidateName;
+      await writeFile(outputPath, data);
+      return outputPath;
+    },
+    getActiveTurn: (chatId: number) => activeTurns.get(chatId),
+    beginTelegramTurn: (chatId, replaceMessageId) => {
+      if (activeTurns.has(chatId)) return undefined; // reject if busy
+      const turn: TelegramTurn = { chatId, replaceMessageId, queuedAttachments: [] };
+      activeTurns.set(chatId, turn);
+      refreshStatus();
+      return turn;
+    },
+    endTelegramTurn: (chatId, turn) => {
+      if (activeTurns.get(chatId) === turn) activeTurns.delete(chatId);
+      refreshStatus();
+    },
+    setActiveChatId: async (chatId) => {
+      if (config.activeChatId === chatId) return;
+      config = { ...config, activeChatId: chatId };
+      await persistCurrentConfig(config);
+      refreshStatus();
+    },
+    getBotUsername: () => config.botUsername,
+    getMessageMode: () => config.messageMode ?? "steer",
+  });
+
+  const polling = createTelegramPollingRuntime({
+    getConfig: () => config,
+    setConfig,
+    persistConfig: persistCurrentConfig,
+    reloadConfig: async () => switchResolvedConfig(await readResolvedTelegramConfig(currentSessionCwd())),
+    handleUpdate: async (update) => {
+      refreshStatus();
+      if (update.callback_query) await controller.handleCallbackQuery(update.callback_query);
+      if (update.message) await controller.handleMessage(update.message);
+      lastStatusError = undefined;
+      refreshStatus();
+    },
+    onSuccess: () => {
+      if (lastStatusError !== undefined) { lastStatusError = undefined; refreshStatus(); }
+    },
+    onError: (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      lastStatusError = message;
+      refreshStatus(message);
+      if (message.startsWith("Telegram polling skipped:")) {
+        getActiveSession()?.extensionRunner.getUIContext().notify(message, "warning");
+        return;
+      }
+      const chatId = config.activeChatId;
+      if (chatId !== undefined && config.botToken) {
+        transport.sendText(chatId, `<b>error</b>\nTelegram polling failed`).catch(() => undefined);
+      } else {
+        getActiveSession()?.extensionRunner.getUIContext().notify(`Telegram polling failed: ${message}`, "error");
+      }
+    },
+  });
+
+  function buildStatusState(error?: string): Parameters<typeof formatTelegramStatusLine>[1] {
+    return {
+      hasBotToken: !!config.botToken,
+      pollingActive: polling.isActive(),
+      paired: config.allowedUserId !== undefined,
+      processing: activeTurns.size > 0,
+      error,
+      botUsername: config.botUsername,
+    };
+  }
+
+  function refreshStatus(error = lastStatusError): void {
+    const state = buildStatusState(error);
+    const session = getActiveSession();
+    const ctx = session?.extensionRunner?.createCommandContext?.();
+    if (ctx?.ui?.setStatus) {
+      ctx.ui.setStatus(TELEGRAM_STATUS_KEY, formatTelegramStatusLine(ctx.ui.theme, state));
+    }
+    heartbeat.refreshStatus(state);
+  }
+
+  function clearStatus(): void {
+    heartbeat.stopTypingOnly();
+    const session = getActiveSession();
+    const ctx = session?.extensionRunner?.createCommandContext?.();
+    if (ctx?.ui?.setStatus) clearTelegramStatus(ctx);
+  }
+
+  function disposeRuntime(): void {
+    void polling.stop();
+    heartbeat.dispose();
+    for (const turn of activeTurns.values()) activeTurns.delete(turn.chatId);
+    ui.dispose();
+    clearStatus();
+  }
+
+  runtimeState.dispose = disposeRuntime;
+
+  pi.on("session_start", async () => {
+    try {
+      switchResolvedConfig(await readResolvedTelegramConfig(currentSessionCwd()));
+    } catch (error) {
+      switchResolvedConfig({ store: { version: 2, global: {}, workspaces: [] }, scope: "global", config: {} });
+      getActiveSession()?.extensionRunner.getUIContext().notify(
+        `Telegram config is not v2 yet. Run /tg-setup to recreate it. ${error instanceof Error ? error.message : String(error)}`,
+        "error",
+      );
+    }
+    if (config.botToken && !config.botUsername) {
+      try {
+        const botUsername = await getTelegramBotUsername(config.botToken);
+        if (botUsername) {
+          config = { ...config, botUsername };
+          await persistCurrentConfig(config);
+        }
+      } catch { /* non-critical */ }
+    }
+    if (config.botToken && isTelegramEnabled() && !polling.isActive()) polling.start();
+    try { await syncTelegramCommands(config.botToken, pi); } catch { /* non-critical */ }
+    lastStatusError = undefined;
+    heartbeat.startStatusHeartbeat(refreshStatus);
+    refreshStatus();
+  });
+
+  pi.on("session_shutdown", () => {
+    disposeRuntime();
+    if (runtimeState.dispose === disposeRuntime) runtimeState.dispose = undefined;
+  });
+}