@tormentalabs/opencode-telegram-plugin 0.2.0

package/README.md

@@ -0,0 +1,222 @@
+# opencode-telegram-plugin
+
+Telegram bot plugin for [OpenCode](https://opencode.ai) — remote control and independent sessions from your phone.
+
+## Features
+
+- **Remote Control** — attach to your active TUI session, see streaming responses in real-time, send prompts, and approve/deny permission requests via inline buttons
+- **Independent Sessions** — create standalone sessions for async work from your phone
+- **Live Streaming** — AI responses stream into Telegram with throttled in-place message edits
+- **Permission Handling** — tool permission prompts appear as inline keyboards (Approve / Deny)
+- **Tool Status** — see which tools are executing in real-time
+- **Multi-session** — switch between sessions, list active sessions, create new ones
+- **Config Management** — built-in `/telegram` slash command for setup without leaving OpenCode
+
+## Quick Start
+
+### 1. Install the plugin
+
+**Local install** (recommended for development):
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["/path/to/opencode-telegram-plugin"]
+}
+```
+
+Then install dependencies:
+
+```bash
+cd /path/to/opencode-telegram-plugin
+bun install
+```
+
+**From npm** (after publishing):
+
+```json
+{
+  "plugin": ["opencode-telegram-plugin"]
+}
+```
+
+### 2. Create a Telegram bot
+
+1. Message [@BotFather](https://t.me/BotFather) on Telegram
+2. Send `/newbot` and follow the prompts
+3. Copy the bot token
+
+### 3. Configure the token
+
+**Option A — Using the `/telegram` slash command** (recommended):
+
+Launch OpenCode and run:
+
+```
+/telegram set-token 123456789:ABCdef-GHIjkl_MNOpqr
+```
+
+Then restart OpenCode.
+
+**Option B — Environment variable**:
+
+```bash
+export TELEGRAM_BOT_TOKEN="123456789:ABCdef-GHIjkl_MNOpqr"
+```
+
+**Option C — Config file** (manually):
+
+Create `~/.config/opencode/telegram.json`:
+
+```json
+{
+  "botToken": "123456789:ABCdef-GHIjkl_MNOpqr"
+}
+```
+
+### 4. (Optional) Restrict access
+
+Restrict the bot to your Telegram user ID only. To get your ID, message [@jsondumpbot](https://t.me/jsondumpbot) on Telegram — your ID is in the `from.id` field of the response.
+
+```
+/telegram set-users 123456789
+```
+
+### 5. Start using it
+
+1. Launch OpenCode — the bot starts automatically
+2. Open your bot in Telegram and send `/start`
+3. Send a message — it's relayed as a prompt to OpenCode
+4. Watch the streaming response appear with live edits
+
+## Configuration
+
+Configuration is resolved by layering **env vars** over the **config file** over **defaults**. Env vars always take priority.
+
+### Config file
+
+Located at `~/.config/opencode/telegram.json`:
+
+```json
+{
+  "botToken": "123456789:ABCdef...",
+  "allowedUsers": "111111,222222",
+  "editIntervalMs": 2500,
+  "autoAttach": true
+}
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TELEGRAM_BOT_TOKEN` | Telegram Bot API token | — |
+| `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs (empty = all) | `""` |
+| `TELEGRAM_EDIT_INTERVAL_MS` | Min interval between message edits (ms) | `2500` |
+| `TELEGRAM_AUTO_ATTACH` | Auto-attach to active session on `/start` | `true` |
+
+## `/telegram` Slash Command
+
+Manage configuration from within OpenCode without editing files manually.
+
+| Command | Description |
+|---------|-------------|
+| `/telegram set-token <TOKEN>` | Save bot token from @BotFather |
+| `/telegram remove-token` | Remove saved bot token |
+| `/telegram set-users <id1,id2,...>` | Restrict bot to specific Telegram user IDs |
+| `/telegram remove-users` | Remove user restriction (allow all) |
+| `/telegram set-interval <ms>` | Set edit throttle interval (default: 2500) |
+| `/telegram auto-attach <on\|off>` | Toggle auto-attach on `/start` |
+| `/telegram status` | Show resolved config (file + env combined) |
+| `/telegram show` | Show raw config file contents |
+| `/telegram path` | Show config file location |
+| `/telegram help` | Show help |
+
+Changes to the config file require an **OpenCode restart** to take effect.
+
+## Telegram Bot Commands
+
+Once the bot is running, these commands are available in Telegram:
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Initialize bot, auto-attach to active session |
+| `/attach` | Attach to an active TUI session (shows picker) |
+| `/detach` | Detach from the current session |
+| `/new` | Create an independent session |
+| `/sessions` | List all sessions |
+| `/switch` | Switch to a different session |
+| `/model` | List available models with favorites marked |
+| `/model <provider/model-id>` | Set a specific model for this chat |
+| `/model reset` | Reset to the default model |
+| `/effort` | Show current effort level |
+| `/effort <low\|medium\|high>` | Set reasoning effort level |
+| `/status` | Show current connection status |
+| `/abort` | Abort the current session |
+| `/help` | Show help |
+
+## How It Works
+
+### Modes
+
+- **Attached** (default) — mirrors an active TUI session. You see what the TUI sees, and your messages are sent as prompts to that session.
+- **Independent** — a standalone session created via `/new`. Runs separately from the TUI.
+- **Detached** — no active session. Messages are ignored until you `/attach` or `/new`.
+
+### Streaming
+
+AI responses are streamed to Telegram using a state machine:
+
+```
+IDLE → PENDING_SEND → SENT → EDITING → FINAL
+```
+
+- First chunk is sent as a new message
+- Subsequent chunks edit the message in-place (throttled to avoid rate limits)
+- Long responses are automatically split into multiple messages (entity-aware HTML chunking at 4096 chars)
+- Markdown from the AI is converted to Telegram-safe HTML
+
+### Permissions
+
+When OpenCode requests tool permissions, an inline keyboard appears in Telegram:
+
+```
+🔐 Permission requested: bash
+Command: git status
+[✅ Approve] [❌ Deny]
+```
+
+Tapping a button responds to the permission request in OpenCode.
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Plugin entry — lifecycle, event dispatcher, /telegram command
+├── config.ts             # Config file management (~/.config/opencode/telegram.json)
+├── bot.ts                # grammY bot creation, middleware, command registration
+├── handlers/
+│   ├── commands.ts       # Telegram bot command handlers
+│   ├── messages.ts       # Text message → prompt relay
+│   └── callbacks.ts      # Inline button callback resolution
+├── hooks/
+│   ├── message.ts        # message.updated → stream to Telegram
+│   ├── session.ts        # Session lifecycle notifications
+│   ├── permission.ts     # Permission prompts → inline keyboards
+│   └── tool.ts           # Tool execution status updates
+├── state/
+│   ├── store.ts          # Per-chat state, stream tracker, callback registry
+│   ├── mode.ts           # Session mode manager
+│   └── mapping.ts        # Persistent chat ↔ session mapping
+└── utils/
+    ├── format.ts         # Markdown → Telegram HTML conversion
+    ├── chunk.ts          # Entity-aware message splitting
+    ├── throttle.ts       # Edit rate limiter
+    ├── safeSend.ts       # Error-classified Telegram API wrapper
+    └── typing.ts         # Typing indicator manager
+```
+
+## License
+
+[GPL-3.0-or-later](LICENSE)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@tormentalabs/opencode-telegram-plugin",
+  "version": "0.2.0",
+  "description": "Telegram bot plugin for OpenCode — remote control and independent sessions from your phone",
+  "type": "module",
+  "main": "./src/index.ts",
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "GPL-3.0-or-later",
+  "keywords": [
+    "opencode",
+    "telegram",
+    "bot",
+    "plugin",
+    "remote-control",
+    "ai",
+    "coding-assistant"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marco-jardim/opencode-telegram-plugin.git"
+  },
+  "author": "marco-jardim",
+  "dependencies": {
+    "grammy": "^1.35.0",
+    "@grammyjs/auto-retry": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  }
+}

package/src/bot.ts

@@ -0,0 +1,143 @@
+import { Bot } from "grammy";
+import { autoRetry } from "@grammyjs/auto-retry";
+
+import {
+  startCommand,
+  helpCommand,
+  attachCommand,
+  detachCommand,
+  newCommand,
+  sessionsCommand,
+  switchCommand,
+  modelCommand,
+  effortCommand,
+  statusCommand,
+  abortCommand,
+  setClient as setCommandsClient,
+} from "./handlers/commands.js";
+import {
+  handleTextMessage,
+  setClient as setMessagesClient,
+} from "./handlers/messages.js";
+import {
+  handleCallback,
+  setClient as setCallbacksClient,
+} from "./handlers/callbacks.js";
+import { cleanExpiredCallbacks } from "./state/store.js";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const CLEANUP_INTERVAL_MS = 120_000; // 2 minutes
+
+// ---------------------------------------------------------------------------
+// Bot factory
+// ---------------------------------------------------------------------------
+
+export interface CreateBotOptions {
+  /** Telegram Bot API token. */
+  token: string;
+  /** Comma-separated list of allowed Telegram user IDs (empty = allow all). */
+  allowedUsers: string;
+  /** Optional error logger; defaults to console.error if not provided. */
+  onError?: (message: string, error: unknown) => void;
+}
+
+/**
+ * Create and configure the grammY bot instance.
+ *
+ * This does **not** start polling — call `bot.start()` separately with an
+ * `AbortSignal` so the lifecycle is controlled by the plugin entry point.
+ */
+export function createBot(opts: CreateBotOptions): Bot {
+  const { token, allowedUsers, onError } = opts;
+  const logError = onError ?? ((msg, err) => console.error(msg, err));
+  const bot = new Bot(token);
+
+  // ── Auto-retry plugin (handles 429 / 500 transparently) ─────────────────
+  bot.api.config.use(autoRetry());
+
+  // ── Global error handler — prevents unhandled errors from killing the bot
+  bot.catch((err) => {
+    logError("[telegram-plugin] Unhandled error in middleware:", err.error);
+  });
+
+  // ── Middleware: private-chat only ───────────────────────────────────────
+  bot.use(async (ctx, next) => {
+    if (ctx.chat?.type !== "private") return; // silently drop group messages
+    await next();
+  });
+
+  // ── Middleware: user whitelist ──────────────────────────────────────────
+  const allowedSet = parseAllowedUsers(allowedUsers);
+  if (allowedSet.size > 0) {
+    bot.use(async (ctx, next) => {
+      const userId = ctx.from?.id;
+      if (userId === undefined || !allowedSet.has(userId)) return;
+      await next();
+    });
+  }
+
+  // ── Commands ───────────────────────────────────────────────────────────
+  bot.command("start", startCommand);
+  bot.command("help", helpCommand);
+  bot.command("attach", attachCommand);
+  bot.command("detach", detachCommand);
+  bot.command("new", newCommand);
+  bot.command("sessions", sessionsCommand);
+  bot.command("switch", switchCommand);
+  bot.command("model", modelCommand);
+  bot.command("effort", effortCommand);
+  bot.command("status", statusCommand);
+  bot.command("abort", abortCommand);
+
+  // ── Callback queries ──────────────────────────────────────────────────
+  bot.on("callback_query:data", handleCallback);
+
+  // ── Text messages (must be registered after commands) ──────────────────
+  bot.on("message:text", handleTextMessage);
+
+  // ── Periodic cleanup of expired callbacks ─────────────────────────────
+  const cleanupTimer = setInterval(cleanExpiredCallbacks, CLEANUP_INTERVAL_MS);
+  // Ensure the timer doesn't prevent the Node process from exiting.
+  if (typeof cleanupTimer === "object" && "unref" in cleanupTimer) {
+    cleanupTimer.unref();
+  }
+
+  return bot;
+}
+
+// ---------------------------------------------------------------------------
+// Client injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject the OpenCode SDK client into all handler modules.
+ *
+ * Must be called once before the bot starts processing updates.
+ */
+export function injectClient(client: unknown): void {
+  setCommandsClient(client);
+  setMessagesClient(client);
+  setCallbacksClient(client);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseAllowedUsers(raw: string): Set<number> {
+  const set = new Set<number>();
+  if (!raw) return set;
+
+  for (const part of raw.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const n = Number(trimmed);
+    if (Number.isFinite(n)) {
+      set.add(n);
+    }
+  }
+  return set;
+}

package/src/config.ts

@@ -0,0 +1,218 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TelegramConfig {
+  botToken: string | null;
+  allowedUsers: string | null;
+  editIntervalMs: number | null;
+  autoAttach: boolean | null;
+}
+
+type ConfigKey = keyof TelegramConfig;
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const CONFIG_DIR = join(homedir(), ".config", "opencode");
+const CONFIG_FILE = join(CONFIG_DIR, "telegram.json");
+
+export function getConfigPath(): string {
+  return CONFIG_FILE;
+}
+
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+
+/** Read the config file from disk. Returns an empty config on any error. */
+export function readConfigFile(): Partial<TelegramConfig> {
+  try {
+    if (!existsSync(CONFIG_FILE)) return {};
+    const raw = readFileSync(CONFIG_FILE, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object") return {};
+    const obj = parsed as Record<string, unknown>;
+
+    const result: Partial<TelegramConfig> = {};
+    if (typeof obj.botToken === "string") result.botToken = obj.botToken;
+    if (typeof obj.allowedUsers === "string") result.allowedUsers = obj.allowedUsers;
+    if (typeof obj.editIntervalMs === "number" && Number.isFinite(obj.editIntervalMs)) {
+      result.editIntervalMs = obj.editIntervalMs;
+    }
+    if (typeof obj.autoAttach === "boolean") result.autoAttach = obj.autoAttach;
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+
+/** Merge partial config into the file (atomic write). */
+export function writeConfigFile(updates: Partial<TelegramConfig>): void {
+  const existing = readConfigFile();
+  const merged = { ...existing, ...updates };
+
+  // Remove null/undefined entries so the file stays clean
+  const clean: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(merged)) {
+    if (v !== null && v !== undefined) {
+      clean[k] = v;
+    }
+  }
+
+  mkdirSync(CONFIG_DIR, { recursive: true });
+
+  const data = JSON.stringify(clean, null, 2) + "\n";
+  const tmpPath = CONFIG_FILE + "." + randomBytes(4).toString("hex") + ".tmp";
+  try {
+    writeFileSync(tmpPath, data, "utf-8");
+    renameSync(tmpPath, CONFIG_FILE);
+  } catch (err) {
+    // Clean up temp file on failure
+    try {
+      if (existsSync(tmpPath)) {
+        const { unlinkSync } = require("node:fs") as typeof import("node:fs");
+        unlinkSync(tmpPath);
+      }
+    } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Delete a key
+// ---------------------------------------------------------------------------
+
+export function deleteConfigKey(key: ConfigKey): void {
+  const existing = readConfigFile();
+  delete existing[key];
+  writeConfigFile(existing);
+}
+
+// ---------------------------------------------------------------------------
+// Resolve config: file < env vars
+// ---------------------------------------------------------------------------
+
+export interface ResolvedConfig {
+  botToken: string | null;
+  allowedUsers: string;
+  editIntervalMs: number;
+  autoAttach: boolean;
+  /** Where the bot token came from */
+  tokenSource: "env" | "config" | "none";
+}
+
+/**
+ * Resolve final config by layering env vars over the config file.
+ *
+ * Priority: env vars > config file > defaults.
+ */
+export function resolveConfig(): ResolvedConfig {
+  const file = readConfigFile();
+
+  // Bot token: env > file
+  const envToken = process.env["TELEGRAM_BOT_TOKEN"];
+  let botToken: string | null = null;
+  let tokenSource: ResolvedConfig["tokenSource"] = "none";
+  if (envToken) {
+    botToken = envToken;
+    tokenSource = "env";
+  } else if (file.botToken) {
+    botToken = file.botToken;
+    tokenSource = "config";
+  }
+
+  // Allowed users: env > file > ""
+  const allowedUsers =
+    process.env["TELEGRAM_ALLOWED_USERS"] ?? file.allowedUsers ?? "";
+
+  // Edit interval: env > file > 2500
+  const envInterval = Number(process.env["TELEGRAM_EDIT_INTERVAL_MS"]);
+  let editIntervalMs = 2500;
+  if (Number.isFinite(envInterval) && envInterval > 0) {
+    editIntervalMs = envInterval;
+  } else if (
+    file.editIntervalMs !== null &&
+    file.editIntervalMs !== undefined &&
+    Number.isFinite(file.editIntervalMs) &&
+    file.editIntervalMs > 0
+  ) {
+    editIntervalMs = file.editIntervalMs;
+  }
+
+  // Auto-attach: env > file > true
+  const envAutoAttach = process.env["TELEGRAM_AUTO_ATTACH"];
+  let autoAttach = true;
+  if (envAutoAttach !== undefined) {
+    autoAttach = envAutoAttach !== "false";
+  } else if (file.autoAttach !== null && file.autoAttach !== undefined) {
+    autoAttach = file.autoAttach;
+  }
+
+  return { botToken, allowedUsers, editIntervalMs, autoAttach, tokenSource };
+}
+
+// ---------------------------------------------------------------------------
+// Status summary (for /telegram status)
+// ---------------------------------------------------------------------------
+
+export function getConfigStatus(): string {
+  const file = readConfigFile();
+  const resolved = resolveConfig();
+
+  const lines: string[] = [];
+  lines.push("**Telegram Plugin Configuration**\n");
+
+  // Token
+  if (resolved.botToken) {
+    const masked = resolved.botToken.slice(0, 6) + "..." + resolved.botToken.slice(-4);
+    lines.push(`- **Bot Token**: \`${masked}\` (from ${resolved.tokenSource})`);
+  } else {
+    lines.push("- **Bot Token**: _not set_");
+  }
+
+  // Allowed users
+  if (resolved.allowedUsers) {
+    lines.push(`- **Allowed Users**: \`${resolved.allowedUsers}\``);
+  } else {
+    lines.push("- **Allowed Users**: _all users_ (no restriction)");
+  }
+
+  // Edit interval
+  lines.push(`- **Edit Interval**: ${resolved.editIntervalMs}ms`);
+
+  // Auto-attach
+  lines.push(`- **Auto-Attach**: ${resolved.autoAttach ? "enabled" : "disabled"}`);
+
+  // Config file
+  lines.push(`\n**Config file**: \`${CONFIG_FILE}\``);
+  if (existsSync(CONFIG_FILE)) {
+    const keys = Object.keys(file);
+    lines.push(`  - Exists with ${keys.length} key(s): ${keys.map(k => `\`${k}\``).join(", ") || "_empty_"}`);
+  } else {
+    lines.push("  - Does not exist yet");
+  }
+
+  // Env var overrides
+  const envOverrides: string[] = [];
+  if (process.env["TELEGRAM_BOT_TOKEN"]) envOverrides.push("TELEGRAM_BOT_TOKEN");
+  if (process.env["TELEGRAM_ALLOWED_USERS"]) envOverrides.push("TELEGRAM_ALLOWED_USERS");
+  if (process.env["TELEGRAM_EDIT_INTERVAL_MS"]) envOverrides.push("TELEGRAM_EDIT_INTERVAL_MS");
+  if (process.env["TELEGRAM_AUTO_ATTACH"]) envOverrides.push("TELEGRAM_AUTO_ATTACH");
+
+  if (envOverrides.length > 0) {
+    lines.push(`\n**Active env overrides**: ${envOverrides.map(e => `\`${e}\``).join(", ")}`);
+  }
+
+  return lines.join("\n");
+}