opencode-telegram-connect 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terrera AG contributors
+
+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,205 @@
+# OpenCode Telegram Control
+
+Steuere eine laufende OpenCode-Session über deinen eigenen Telegram-Bot. Nachrichten werden an OpenCode weitergeleitet; Antworten, Freigaben und Rückfragen erscheinen in Telegram.
+
+**Telegram bleibt beim Start von OpenCode ausgeschaltet.** Erst wenn du deinen Agenten zum Verbinden aufforderst und er `telegram_connect` aufruft, startet die Verbindung. Es gibt keinen Telegram-Befehl zum Einschalten. Der frühere Startbefehl wird ignoriert und nicht an das Modell weitergeleitet.
+
+## Voraussetzungen
+
+- OpenCode mit npm-Plugin-Unterstützung; getestet mit OpenCode 1.18.29.
+- Eine funktionierende Modellkonfiguration in OpenCode.
+- Node.js ab Version 20 und npm für die unten gezeigten Hilfsbefehle.
+- Telegram auf deinem Handy oder Computer und Internetzugang auf dem OpenCode-Rechner.
+
+OpenCode muss während der Nutzung laufen. Das Plugin startet keinen zusätzlichen OpenCode-Server. Es öffnet keinen eingehenden Telegram-Port.
+
+## 1. Plugin installieren
+
+Öffne die globale OpenCode-Konfiguration:
+
+- Windows: `%USERPROFILE%\.config\opencode\opencode.json`
+- Linux/macOS: `~/.config/opencode/opencode.json`
+
+Ergänze das Paket in der vorhandenen `plugin`-Liste. Andere Einstellungen und Plugins beibehalten:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-telegram-connect@1.0.0"]
+}
+```
+
+OpenCode installiert dieses npm-Paket beim nächsten Start automatisch. Eine globale Installation allein aktiviert das Plugin nicht. Entferne alte Einträge dieses Plugins und lokale `file://`-Einbindungen, damit es nur einmal geladen wird.
+
+Optional kannst du das Paket samt Hilfsbefehl global installieren:
+
+```sh
+npm install -g opencode-telegram-connect@1.0.0
+```
+
+Siehe auch die [OpenCode-Plugin-Dokumentation](https://opencode.ai/docs/plugins/).
+
+## 2. Bot und Token bekommen
+
+1. Öffne in Telegram den offiziellen [@BotFather](https://t.me/BotFather).
+2. Sende ihm `/newbot`.
+3. Wähle einen Anzeigenamen und einen verfügbaren Benutzernamen für deinen Bot. Der Benutzername endet auf `bot`.
+4. BotFather gibt dir einen API-Token. Bewahre ihn wie ein Passwort auf.
+5. Öffne den Chat mit deinem neuen Bot und sende ihm eine normale Nachricht wie `Hallo`. Eine Antwort ist zu diesem Zeitpunkt noch nicht zu erwarten.
+
+Der Token gehört zum Bot. Deine persönliche Benutzer-ID wird im nächsten Schritt separat ermittelt. Anleitung von Telegram: [Bot erstellen](https://core.telegram.org/bots/tutorial#obtain-your-bot-token).
+
+## 3. Token und Benutzer-ID hinterlegen
+
+Erstelle diese Datei:
+
+- Windows: `C:\Users\<DEIN-NAME>\.config\opencode\telegram.env`
+- Linux/macOS: `~/.config/opencode/telegram.env`
+
+Unter Windows kannst du sie so öffnen:
+
+```powershell
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null
+notepad "$env:USERPROFILE\.config\opencode\telegram.env"
+```
+
+Trage zunächst deinen echten Bot-Token ein:
+
+```ini
+TELEGRAM_TOKEN=DEIN_BOT_TOKEN
+```
+
+Speichere die Datei genau als `telegram.env`, nicht als `telegram.env.txt`.
+
+### Deine Benutzer-ID ermitteln
+
+Lass die Telegram-Verbindung in OpenCode ausgeschaltet. Nachdem du deinem Bot privat `Hallo` geschickt hast, führe aus:
+
+```sh
+npx --yes --package=opencode-telegram-connect@1.0.0 opencode-telegram-user-id
+```
+
+Der Hilfsbefehl liest den Token aus deiner Datei und zeigt die Benutzer-IDs der vorhandenen Nachrichten an, beispielsweise `DeinName: TELEGRAM_USER=123456789`. Er sendet keine Nachricht und gibt den Token nicht aus. Falls mehrere Personen angezeigt werden, nimm deine eigene ID. Falls nichts angezeigt wird, sende erneut `Hallo` und wiederhole den Hilfsbefehl. Währenddessen darf keine andere Anwendung mit diesem Bot Nachrichten abfragen.
+
+Ergänze die Datei anschließend:
+
+```ini
+TELEGRAM_TOKEN=DEIN_BOT_TOKEN
+TELEGRAM_USER=123456789
+TELEGRAM_PAIRING=false
+```
+
+Die Benutzer-ID ist eine Zahl, kein `@Benutzername` und nicht die ID des Bots. Mehrere erlaubte Benutzer werden mit Kommas getrennt. Mit dieser Konfiguration können nur die eingetragenen Benutzer den Bot steuern.
+
+Du brauchst keinen npm-Token für Installation oder Nutzung. Ein API-Schlüssel für dein Modell gehört in die OpenCode-Modellkonfiguration, nicht in diese Datei. Token niemals in Prompts, Screenshots oder ins Repository kopieren.
+
+## 4. Verbinden und erster Test
+
+Starte OpenCode in deinem gewünschten Projektordner:
+
+```sh
+cd pfad/zu/deinem/projekt
+opencode
+```
+
+Schreibe deinem OpenCode-Agenten:
+
+> Verbinde diese Session mit Telegram. Verwende telegram_connect.
+
+Erst dieser Werkzeugaufruf prüft den Token und startet das Telegram-Polling. Der Bot sendet dir jetzt automatisch die Anleitung. Daf?r musst du ihm zuvor einmal privat geschrieben haben und darfst ihn nicht blockiert haben. Ohne statische Freigabe erscheint die Anleitung erst nach erfolgreichem Pairing. Zustellfehler werden beim Verbinden gemeldet; die Verbindung bleibt nutzbar.
+
+Sende danach deinem Bot:
+
+```text
+/current
+```
+
+Die Ausgabe zeigt die gewählte Session. Sende anschließend:
+
+```text
+Antworte nur mit HALLO.
+```
+
+Du erhältst zunächst die Session-ID und danach die Modellantwort. Das Modell arbeitet mit den Werkzeugen und Berechtigungen deiner laufenden OpenCode-Instanz.
+
+## 5. Bedienung in Telegram
+
+| Nachricht/Befehl | Funktion |
+| --- | --- |
+| Normaler Text | Als Prompt an die gewählte Session senden |
+| `/start` oder `/help` | Vollst?ndige Bedienungsanleitung anzeigen |
+| `/current` | Aktuelle Session und Modell anzeigen |
+| `/sessions` | Bis zu 20 Sessions auflisten |
+| `/session 2` | Session aus der Liste auswählen |
+| `/session <id>` | Session anhand ihrer gelisteten ID auswählen |
+| `/new Mein Test` | Neue Session erstellen und auswählen |
+| `/rename Neuer Titel` | Aktuelle Session umbenennen |
+| `/models` | Verfügbare Modelle auflisten |
+| `/model 2` | Modell aus der Liste auswählen |
+| `/model anbieter/modell` | Modell anhand seines vollständigen Namens auswählen |
+| `/abort` | Laufende Verarbeitung abbrechen |
+| `/permissions` | Offene Freigaben anzeigen |
+| `/approve <id>` | Einmal erlauben |
+| `/always <id>` | Passende Berechtigung dauerhaft erlauben |
+| `/deny <id>` | Berechtigung ablehnen |
+| `/questions` | Offene Rückfragen anzeigen |
+| `/answer <id> Antwort` | Rückfrage beantworten |
+| `/rejectquestion <id>` | Rückfrage ablehnen |
+| `/disconnect` | Zuordnung dieses Chats entfernen; statische Benutzerfreigaben bleiben gültig |
+
+Für mehrere Rückfragen: `/answer <id> Antwort eins || Antwort zwei`. Bei Mehrfachauswahl: `Option A; Option B`. Bei einfachen Auswahlfragen und Freigaben kannst du die mitgesendeten Schaltflächen verwenden.
+
+Andere Slash-Befehle werden als Text an OpenCode übermittelt; das führt nicht automatisch einen OpenCode-Slash-Befehl aus. Der entfernte Startbefehl ist ausdrücklich davon ausgenommen.
+
+### Telegram vollständig ausschalten
+
+Sage deinem OpenCode-Agenten:
+
+> Trenne Telegram. Verwende telegram_disconnect.
+
+Das stoppt das Polling und gibt die Bot-Sperre frei. `/disconnect` in Telegram entfernt dagegen nur die Chat-Zuordnung. Für einen laufenden Auftrag zuerst `/abort` verwenden; das vollständige Trennen wartet auf bereits laufende Nachrichtenverarbeitung.
+
+Nach einem Neustart von OpenCode musst du erneut verbinden. Nur eine OpenCode-Instanz kann gleichzeitig mit demselben Bot verbunden sein. Andere Instanzen übernehmen den Bot nicht automatisch. Trenne die bisherige Instanz und fordere dann den gewünschten Agenten zum Verbinden auf.
+
+## Alternative Konfiguration
+
+Vorhandene Umgebungsvariablen haben Vorrang. Akzeptierte Namen:
+
+| Variable | Bedeutung |
+| --- | --- |
+| `TELEGRAM_BOT_TOKEN` | Umgebungsvariable für den Bot-Token; in Dateien ist auch `TELEGRAM_TOKEN` erlaubt |
+| `TELEGRAM_ALLOWED_USER_IDS` | Erlaubte Benutzer; in Dateien auch `TELEGRAM_USER` |
+| `TELEGRAM_ALLOWED_CHAT_IDS` | Erlaubte Chats, mit Kommas getrennt |
+| `TELEGRAM_PAIRING` | `true` oder `false` |
+| `TELEGRAM_ENV_FILE` | Expliziter Pfad zu einer Konfigurationsdatei |
+
+Dateisuche: expliziter Pfad, globale `telegram.env`, globale `telegram.json`, dann `.env.opencode-telegram` und `.env` im Projekt oder übergeordneten Verzeichnissen. Bevorzuge die globale Datei. Nach Änderungen OpenCode neu starten, damit zuvor geladene Werte ersetzt werden.
+
+Alternatives JSON-Format: `{"token":"DEIN_BOT_TOKEN","userId":"123456789"}`.
+
+Eine Chat-Freigabe erlaubt allen Benutzern dieses Chats die Steuerung. Benutzer- und Chat-Freigaben werden mit ODER verknüpft. Für private Nutzung genügt deine Benutzer-ID.
+
+Ohne Benutzer-/Chat-Freigabe ist einmaliges Pairing möglich: `telegram_connect` liefert einen Code, den du als `/pair <code>` an deinen Bot sendest. Der Code verfällt nach Verwendung oder beim Beenden der Verbindung. Bei `TELEGRAM_PAIRING=false` muss eine Freigabe konfiguriert sein.
+
+## Fehlerbehebung
+
+- **Bot antwortet nicht:** OpenCode muss laufen und `telegram_connect` erfolgreich ausgeführt worden sein. Prüfe über den Agenten `telegram_status`.
+- **Unauthorized:** Prüfe deine numerische Benutzer-ID und starte OpenCode nach der Korrektur neu.
+- **Tokenfehler:** Kopiere den Token aus BotFather erneut in die Datei. Prüfe Dateiname und Pfad.
+- **Andere Instanz verbunden / Telegram Conflict:** Trenne andere OpenCode-Instanzen oder Programme, die denselben Bot abfragen.
+- **Webhook-Konflikt:** Dieses Plugin verwendet Long Polling. Verwende einen eigenen Bot ohne bestehenden Webhook.
+- **Keine Modellantwort:** Teste denselben Auftrag zuerst direkt in OpenCode. Modellzugang, offene Berechtigungen und Rückfragen prüfen.
+- **Werkzeuge fehlen:** Plugin-Eintrag prüfen, alte lokale Einbindungen entfernen und OpenCode neu starten.
+
+## Entwicklung
+
+```sh
+npm ci
+npm test
+npm run check
+npm run pack:dry
+```
+
+Die Tests prüfen Autorisierung, Pairing, Session- und Modellwahl, Berechtigungen, Fragen, das echte SDK-Requestformat mit simuliertem HTTP-Transport sowie den Verbindungslebenszyklus ohne Netzwerkzugriff.
+
+Version 1.0.0: Erstver?ffentlichung unter dem Paketnamen `opencode-telegram-connect`. Telegram wird ausschlie?lich ?ber `telegram_connect` aktiviert. Nach dem Verbinden und Pairing erscheint die Bedienungsanleitung automatisch; `/start` und `/help` zeigen sie erneut an.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "opencode-telegram-connect",
+  "version": "1.0.0",
+  "description": "Native OpenCode plugin to securely control sessions from Telegram.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    },
+    "./server": {
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "telegram",
+    "plugin",
+    "agent",
+    "remote-control"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check": "node --check src/index.js && node --check src/bridge.js && node --check src/telegram.js && node --check src/opencode.js && node --check src/env.js && node --check src/lock.js && node --check src/user-id.js",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@opencode-ai/sdk": "1.18.28"
+  },
+  "bin": {
+    "opencode-telegram-user-id": "src/user-id.js"
+  }
+}

package/src/bridge.js

@@ -0,0 +1,391 @@
+import { randomInt } from "node:crypto";
+import { extractText, normalizeProviders, normalizeSessions, promptSession, replyPermission, replyQuestion, rejectQuestion, unwrap } from "./opencode.js";
+
+const CMD_HELP = `OpenCode ist mit Telegram verbunden.
+
+Sende normalen Text, um in der verbundenen Session zu arbeiten. Beispiel: Erkl?re mir dieses Projekt.
+
+/start oder /help - diese Anleitung
+/current - aktuelle Session und Modell
+/sessions - Sessions auflisten
+/session <Nummer|ID> - Session ausw?hlen
+/new [Titel] - neue Session erstellen
+/rename <Titel> - Session umbenennen
+/models - Modelle auflisten
+/model <Nummer|Anbieter/Modell> - Modell ausw?hlen
+/abort - laufenden Auftrag abbrechen
+/permissions - offene Freigaben
+/approve <ID> - einmal erlauben
+/always <ID> - passende Berechtigung dauerhaft erlauben
+/deny <ID> - Freigabe ablehnen
+/questions - offene R?ckfragen
+/answer <ID> <Antwort> - R?ckfrage beantworten
+/rejectquestion <ID> - R?ckfrage ablehnen
+/disconnect - Chat-Zuordnung entfernen (statische Freigaben bleiben g?ltig)
+/pair <Code> - einmaliges Pairing, falls keine Benutzer-/Chat-Freigabe eingerichtet ist
+
+Mehrere Antworten mit || trennen; Mehrfachauswahl mit ;. Freigaben und einfache Auswahlfragen lassen sich auch ?ber Schaltfl?chen beantworten.
+
+OpenCode muss weiterlaufen. Vollst?ndig ausschalten: Deinen OpenCode-Agenten bitten, telegram_disconnect aufzurufen. Erneut verbinden: telegram_connect. /start zeigt nur diese Hilfe und kann eine ausgeschaltete Verbindung nicht einschalten.
+
+Andere Slash-Befehle werden als Prompt-Text an das Modell weitergeleitet.`;
+
+function idOfSession(s) { return s?.id || s?.sessionID; }
+async function callApi(fn, options) {
+  const result = await fn(options);
+  if (result && typeof result === "object" && "error" in result && result.error) {
+    const e = result.error;
+    throw new Error(e.message || e.name || e._tag || JSON.stringify(e));
+  }
+  return result;
+}
+function titleOfSession(s) { return s?.title || s?.name || "Untitled"; }
+function parseIds(value) {
+  return new Set(String(value || "").split(",").map((x) => x.trim()).filter(Boolean));
+}
+
+export class Bridge {
+  constructor({ client, telegram, env = process.env, logger = async () => {} }) {
+    this.client = client;
+    this.telegram = telegram;
+    this.logger = logger;
+    this.allowedUsers = parseIds(env.TELEGRAM_ALLOWED_USER_IDS);
+    this.allowedChats = parseIds(env.TELEGRAM_ALLOWED_CHAT_IDS);
+    this.pairingEnabled = String(env.TELEGRAM_PAIRING || "true").toLowerCase() !== "false";
+    this.pairedUsers = new Set();
+    this.pairedChats = new Set();
+    this.bindings = new Map();
+    this.pendingPermissions = new Map();
+    this.pendingQuestions = new Map();
+    this.pairCode = null;
+    this.pollAbort = null;
+    this.pollPromise = null;
+    this.offset = 0;
+    this.inflightUpdates = new Set();
+  }
+
+  isAuthorized(userId, chatId) {
+    const u = String(userId ?? "");
+    const c = String(chatId ?? "");
+    if (this.allowedUsers.size || this.allowedChats.size) {
+      return this.allowedUsers.has(u) || this.allowedChats.has(c);
+    }
+    return this.pairedUsers.has(u) && this.pairedChats.has(c);
+  }
+
+  startPairing(sessionID) {
+    if (!this.pairingEnabled && !this.allowedUsers.size && !this.allowedChats.size) {
+      throw new Error("No Telegram allowlist configured and pairing is disabled");
+    }
+    this.defaultSessionID = sessionID;
+    for (const binding of this.bindings.values()) binding.sessionID = sessionID;
+    if (this.allowedUsers.size || this.allowedChats.size) {
+      return { code: null, message: "Telegram bridge active. Configured allowlist will be used." };
+    }
+    this.pairCode = String(randomInt(10000000, 100000000));
+    this.defaultSessionID = sessionID;
+    return { code: this.pairCode, message: `Telegram bridge active. Send /pair ${this.pairCode} to the bot. The code is one-time and expires when used or OpenCode exits.` };
+  }
+
+  async sendGuide(chatId) {
+    return this.telegram.sendMessage(chatId, CMD_HELP);
+  }
+
+  async announceConnection() {
+    const targets = new Set([...this.allowedUsers, ...this.allowedChats, ...this.bindings.keys()]);
+    const failed = [];
+    for (const chatId of targets) {
+      try {
+        await this.sendGuide(chatId);
+        this.binding(chatId);
+      } catch {
+        failed.push(chatId);
+        await this.logger("warn", "Could not deliver Telegram connection guide; user must message the bot first or unblock it.");
+      }
+    }
+    return failed.length ? " Anleitung konnte nicht an alle Chats zugestellt werden. ?ffne den Bot, sende ihm eine Nachricht und rufe /start bei aktiver Verbindung auf." : "";
+  }
+
+  async start() {
+    if (this.pollPromise) return;
+    this.pollAbort = new AbortController();
+    this.pollPromise = this.pollLoop(this.pollAbort.signal).finally(() => { this.pollPromise = null; });
+  }
+
+  async stop() {
+    if (!this.pollAbort) return;
+    this.pollAbort.abort();
+    try { await this.pollPromise; } catch (error) { if (error?.name !== "AbortError") throw error; }
+    await Promise.allSettled([...this.inflightUpdates]);
+    this.pollAbort = null;
+  }
+
+  async pollLoop(signal) {
+    while (!signal.aborted) {
+      try {
+        const updates = await this.telegram.getUpdates(this.offset, 25, signal);
+        if (!Array.isArray(updates)) throw new Error(`Telegram getUpdates returned non-array: ${JSON.stringify(updates)?.slice(0, 300)}`);
+        for (const update of updates || []) {
+          this.offset = Math.max(this.offset, Number(update.update_id || 0) + 1);
+          const task = this.handleUpdate(update)
+            .catch((error) => this.logger("error", `Telegram update error: ${error.message}`))
+            .finally(() => this.inflightUpdates.delete(task));
+          this.inflightUpdates.add(task);
+        }
+      } catch (error) {
+        if (signal.aborted) return;
+        const conflict = /Conflict/i.test(error.message || "");
+        await this.logger(conflict ? "warn" : "error", `Telegram polling error: ${error.message}`);
+        await new Promise((resolve) => setTimeout(resolve, conflict ? 5000 : 1200));
+      }
+    }
+  }
+
+  async handleUpdate(update) {
+    if (update.callback_query) return this.handleCallback(update.callback_query);
+    const msg = update.message;
+    if (!msg || typeof msg.text !== "string") return;
+    const chatId = msg.chat?.id;
+    const userId = msg.from?.id;
+    const text = msg.text;
+
+    if (!this.client?.session?.create) {
+      await this.telegram.sendMessage(chatId, "OpenCode client is not connected in this plugin host; the bridge cannot proxy prompts.");
+      return;
+    }
+
+    if (text.startsWith("/pair ")) {
+      const code = text.slice(6).trim();
+      if (!this.pairingEnabled || !this.pairCode || code !== this.pairCode) {
+        await this.telegram.sendMessage(chatId, "Pairing failed.");
+        return;
+      }
+      this.pairedUsers.add(String(userId));
+      this.pairedChats.add(String(chatId));
+      this.pairCode = null;
+      this.bindings.set(String(chatId), { sessionID: this.defaultSessionID, model: null });
+      await this.sendGuide(chatId);
+      return;
+    }
+
+    if (!this.isAuthorized(userId, chatId)) {
+      await this.telegram.sendMessage(chatId, "Unauthorized Telegram user/chat.");
+      return;
+    }
+
+    if (text.startsWith("/")) return this.handleCommand(chatId, text);
+    return this.forwardPrompt(chatId, text);
+  }
+
+  binding(chatId) {
+    const key = String(chatId);
+    if (!this.bindings.has(key)) this.bindings.set(key, { sessionID: this.defaultSessionID || null, model: null });
+    return this.bindings.get(key);
+  }
+
+  async ensureSession(chatId) {
+    const binding = this.binding(chatId);
+    if (binding.sessionID) return binding.sessionID;
+    const session = unwrap(await callApi((o) => this.client.session.create(o), { title: "Telegram" }));
+    binding.sessionID = idOfSession(session);
+    return binding.sessionID;
+  }
+
+  async forwardPrompt(chatId, text) {
+    const binding = this.binding(chatId);
+    const sessionID = await this.ensureSession(chatId);
+    await this.telegram.sendMessage(chatId, `→ ${sessionID}`);
+    try {
+      const result = await promptSession(this.client, sessionID, text, binding.model);
+      const answer = extractText(result) || "OpenCode returned no text response.";
+      await this.telegram.sendMessage(chatId, answer);
+    } catch (error) {
+      await this.telegram.sendMessage(chatId, `OpenCode error: ${error.message}`);
+    }
+  }
+
+  async handleCommand(chatId, raw) {
+    const [head, ...rest] = raw.trim().split(/\s+/);
+    const command = head.toLowerCase().split("@")[0];
+    const arg = raw.trim().slice(head.length).trim();
+    const binding = this.binding(chatId);
+
+    if (command === "/start" || command === "/help") return this.sendGuide(chatId);
+    if (command === "/sessions") {
+      const sessions = normalizeSessions(await callApi((o) => this.client.session.list(o), undefined)).slice(0, 20);
+      const lines = sessions.map((s, i) => `${i + 1}. ${idOfSession(s) === binding.sessionID ? "*" : " "} ${titleOfSession(s)} — ${idOfSession(s)}`);
+      return this.telegram.sendMessage(chatId, lines.length ? lines.join("\n") : "No sessions.");
+    }
+    if (command === "/session") {
+      if (!arg) return this.telegram.sendMessage(chatId, "Usage: /session <id|number>");
+      const sessions = normalizeSessions(await callApi((o) => this.client.session.list(o), undefined)).slice(0, 20);
+      const n = Number(arg);
+      const selected = Number.isInteger(n) && n > 0 ? sessions[n - 1] : sessions.find((s) => idOfSession(s) === arg);
+      if (!selected) return this.telegram.sendMessage(chatId, "Session not found.");
+      binding.sessionID = idOfSession(selected);
+      return this.telegram.sendMessage(chatId, `Selected session: ${titleOfSession(selected)} (${binding.sessionID})`);
+    }
+    if (command === "/new") {
+      const created = unwrap(await callApi((o) => this.client.session.create(o), { title: arg || "Telegram" }));
+      binding.sessionID = idOfSession(created);
+      return this.telegram.sendMessage(chatId, `Created and selected: ${titleOfSession(created)} (${binding.sessionID})`);
+    }
+    if (command === "/models") {
+      const models = normalizeProviders(await callApi((o) => this.client.config.providers(o), undefined));
+      const lines = models.map((m, i) => `${i + 1}. ${binding.model?.providerID === m.providerID && binding.model?.modelID === m.modelID ? "*" : " "} ${m.label}`);
+      return this.telegram.sendMessage(chatId, lines.length ? lines.join("\n") : "No models reported by OpenCode.");
+    }
+    if (command === "/model") {
+      if (!arg) return this.telegram.sendMessage(chatId, "Usage: /model <provider/model|number>");
+      const models = normalizeProviders(await callApi((o) => this.client.config.providers(o), undefined));
+      const n = Number(arg);
+      const selected = Number.isInteger(n) && n > 0 ? models[n - 1] : models.find((m) => m.label === arg);
+      if (!selected) return this.telegram.sendMessage(chatId, "Model not found.");
+      binding.model = selected;
+      return this.telegram.sendMessage(chatId, `Selected model for Telegram prompts: ${selected.label}`);
+    }
+    if (command === "/current") {
+      return this.telegram.sendMessage(chatId, `Session: ${binding.sessionID || "auto"}\nModel: ${binding.model?.label || "OpenCode session/default"}`);
+    }
+    if (command === "/abort") {
+      const id = await this.ensureSession(chatId);
+      await callApi((o) => this.client.session.abort(o), { sessionID: id });
+      return this.telegram.sendMessage(chatId, `Abort requested for ${id}.`);
+    }
+    if (command === "/rename") {
+      if (!arg) return this.telegram.sendMessage(chatId, "Usage: /rename <title>");
+      const id = await this.ensureSession(chatId);
+      await callApi((o) => this.client.session.update(o), { sessionID: id, title: arg });
+      return this.telegram.sendMessage(chatId, `Renamed ${id} to ${arg}.`);
+    }
+    if (command === "/permissions") {
+      const list = [...this.pendingPermissions.values()].filter((p) => !binding.sessionID || p.sessionID === binding.sessionID);
+      if (!list.length) return this.telegram.sendMessage(chatId, "No pending permissions.");
+      return this.telegram.sendMessage(chatId, list.map((p) => `${p.id}: ${p.permission || p.title || "permission"} ${Array.isArray(p.patterns) ? p.patterns.join(", ") : ""}`).join("\n"));
+    }
+    if (command === "/questions") {
+      const list = [...this.pendingQuestions.values()].filter((q) => !binding.sessionID || q.sessionID === binding.sessionID);
+      if (!list.length) return this.telegram.sendMessage(chatId, "No pending questions.");
+      return this.telegram.sendMessage(chatId, list.map((q) => `${q.id}: ${(q.questions || []).map((x) => x.question || x.header || "Question").join(" | ")}`).join("\n"));
+    }
+    if (command === "/answer") {
+      const firstSpace = arg.indexOf(" ");
+      if (firstSpace < 1) return this.telegram.sendMessage(chatId, "Usage: /answer <question-id> <answer1> || <answer2>");
+      const id = arg.slice(0, firstSpace).trim();
+      const text = arg.slice(firstSpace + 1);
+      const pending = this.pendingQuestions.get(id);
+      if (!pending) return this.telegram.sendMessage(chatId, "Question not found or no longer pending.");
+      const segments = text.split(/\s+\|\|\s+/);
+      const questions = pending.questions || [];
+      if (questions.length > 1 && segments.length !== questions.length) {
+        return this.telegram.sendMessage(chatId, `Expected ${questions.length} answers separated by ||.`);
+      }
+      const answers = (questions.length > 1 ? segments : [text]).map((x) => x.split(/\s*;\s*/).filter(Boolean));
+      await replyQuestion(this.client, id, answers);
+      this.pendingQuestions.delete(id);
+      return this.telegram.sendMessage(chatId, `Question ${id} answered.`);
+    }
+    if (command === "/rejectquestion") {
+      if (!arg) return this.telegram.sendMessage(chatId, "Usage: /rejectquestion <question-id>");
+      if (!this.pendingQuestions.has(arg)) return this.telegram.sendMessage(chatId, "Question not found or no longer pending.");
+      await rejectQuestion(this.client, arg);
+      this.pendingQuestions.delete(arg);
+      return this.telegram.sendMessage(chatId, `Question ${arg} rejected.`);
+    }
+    if (["/approve", "/always", "/deny"].includes(command)) {
+      if (!arg) return this.telegram.sendMessage(chatId, `Usage: ${command} <permission-id>`);
+      const pending = this.pendingPermissions.get(arg);
+      if (!pending) return this.telegram.sendMessage(chatId, "Permission not found or no longer pending.");
+      const reply = command === "/approve" ? "once" : command === "/always" ? "always" : "reject";
+      await replyPermission(this.client, pending.sessionID, pending.id, reply);
+      this.pendingPermissions.delete(arg);
+      return this.telegram.sendMessage(chatId, `Permission ${arg}: ${reply}.`);
+    }
+    if (command === "/disconnect") {
+      this.pairedChats.delete(String(chatId));
+      this.bindings.delete(String(chatId));
+      return this.telegram.sendMessage(chatId, "Telegram chat disconnected from OpenCode.");
+    }
+
+    // Unknown slash commands are forwarded unchanged, preserving OpenCode custom commands.
+    return this.forwardPrompt(chatId, raw);
+  }
+
+  async handleCallback(query) {
+    const chatId = query.message?.chat?.id;
+    const userId = query.from?.id;
+    if (!this.isAuthorized(userId, chatId)) return this.telegram.answerCallbackQuery(query.id, "Unauthorized");
+    const data = String(query.data || "");
+    const qmatch = /^q:([^:]+):(\d+)$/.exec(data);
+    if (qmatch) {
+      const pending = this.pendingQuestions.get(qmatch[1]);
+      if (!pending) return this.telegram.answerCallbackQuery(query.id, "Question expired");
+      const option = pending.questions?.[0]?.options?.[Number(qmatch[2])];
+      const answer = option?.label ?? option?.value;
+      if (answer == null) return this.telegram.answerCallbackQuery(query.id, "Option expired");
+      await replyQuestion(this.client, pending.id, [[String(answer)]]);
+      this.pendingQuestions.delete(pending.id);
+      return this.telegram.answerCallbackQuery(query.id, "Answered");
+    }
+    const match = /^(once|always|reject):(.+)$/.exec(data);
+    if (!match) return this.telegram.answerCallbackQuery(query.id, "Unknown action");
+    const pending = this.pendingPermissions.get(match[2]);
+    if (!pending) return this.telegram.answerCallbackQuery(query.id, "Permission expired");
+    await replyPermission(this.client, pending.sessionID, pending.id, match[1]);
+    this.pendingPermissions.delete(pending.id);
+    await this.telegram.answerCallbackQuery(query.id, match[1]);
+  }
+
+  async onEvent(event) {
+    if (!event || typeof event.type !== "string") return;
+    if (event.type === "permission.asked" || event.type === "permission.v2.asked") {
+      const p = event.properties || {};
+      if (!p.id || !p.sessionID) return;
+      this.pendingPermissions.set(p.id, p);
+      for (const [chatId, binding] of this.bindings) {
+        if (binding.sessionID !== p.sessionID) continue;
+        const patterns = Array.isArray(p.patterns) ? `\n${p.patterns.join("\n")}` : "";
+        await this.telegram.sendMessage(chatId, `Permission required\nID: ${p.id}\n${p.permission || p.title || "permission"}${patterns}`, {
+          reply_markup: { inline_keyboard: [[
+            { text: "Allow once", callback_data: `once:${p.id}` },
+            { text: "Always", callback_data: `always:${p.id}` },
+            { text: "Reject", callback_data: `reject:${p.id}` },
+          ]] },
+        });
+      }
+    }
+    if (event.type === "question.asked") {
+      const q = event.properties || {};
+      if (!q.id || !q.sessionID) return;
+      this.pendingQuestions.set(q.id, q);
+      for (const [chatId, binding] of this.bindings) {
+        if (binding.sessionID !== q.sessionID) continue;
+        const questions = q.questions || [];
+        let text = `OpenCode question\nID: ${q.id}`;
+        questions.forEach((item, i) => {
+          text += `\n\n${i + 1}. ${item.question || item.header || "Question"}`;
+          if (Array.isArray(item.options)) text += `\n${item.options.map((o, j) => `  ${j + 1}) ${o.label || o.value}`).join("\n")}`;
+          if (item.multiple) text += "\n(multiple: separate choices with ;)";
+        });
+        text += `\n\nReply: /answer ${q.id} <answer1> || <answer2>`;
+        const extra = {};
+        if (questions.length === 1 && !questions[0]?.multiple && Array.isArray(questions[0]?.options) && questions[0].options.length <= 8) {
+          extra.reply_markup = { inline_keyboard: questions[0].options.map((o, i) => [{ text: String(o.label || o.value).slice(0, 40), callback_data: `q:${q.id}:${i}` }]) };
+        }
+        await this.telegram.sendMessage(chatId, text, extra);
+      }
+    }
+    if (event.type === "question.replied" || event.type === "question.rejected") {
+      const id = event.properties?.requestID || event.properties?.id;
+      if (id) this.pendingQuestions.delete(id);
+    }
+    if (event.type === "session.error") {
+      const p = event.properties || {};
+      for (const [chatId, binding] of this.bindings) {
+        if (p.sessionID && binding.sessionID === p.sessionID) {
+          await this.telegram.sendMessage(chatId, `Session error: ${p.error?.message || p.error?.name || "unknown error"}`);
+        }
+      }
+    }
+  }
+}

package/src/env.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export function parseEnvFile(content) {
+  const out = {};
+  for (const line of content.split(/\r?\n/)) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+    if (!m) continue;
+    let value = m[2];
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    } else {
+      value = value.replace(/\s+#.*$/, "").trim();
+    }
+    out[m[1]] = value;
+  }
+  return out;
+}
+
+export function findUp(name, startDir) {
+  let dir = resolve(startDir || process.cwd());
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, name);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function loadTelegramEnv(startDir, homeDir) {
+  const env = process.env;
+  const home = homeDir || homedir();
+  const candidates = [
+    env.TELEGRAM_ENV_FILE,
+    join(home, ".config", "opencode", "telegram.env"),
+    join(home, ".config", "opencode", "telegram.json"),
+    findUp(".env.opencode-telegram", startDir),
+    findUp(".env", startDir),
+  ].filter(Boolean);
+  for (const file of candidates) {
+    try {
+      if (!existsSync(file)) continue;
+      const raw = readFileSync(file, "utf8").replace(/^\uFEFF/, "");
+      let parsed = {};
+      if (file.endsWith(".json")) {
+        const json = JSON.parse(raw);
+        parsed = {
+          TELEGRAM_BOT_TOKEN: json.token || json.botToken || json.TELEGRAM_BOT_TOKEN,
+          TELEGRAM_ALLOWED_USER_IDS: json.userId || json.allowedUsers || json.TELEGRAM_ALLOWED_USER_IDS,
+        };
+      } else {
+        parsed = parseEnvFile(raw);
+      }
+      for (const key of ["TELEGRAM_ALLOWED_CHAT_IDS", "TELEGRAM_PAIRING"]) {
+        if (!env[key] && parsed[key] !== undefined) env[key] = String(parsed[key]);
+      }
+      const token = parsed.TELEGRAM_BOT_TOKEN || parsed.TELEGRAM_TOKEN;
+      const users = parsed.TELEGRAM_ALLOWED_USER_IDS || parsed.TELEGRAM_USER || parsed.TELEGRAM_ALLOWED_USERS;
+      if (!env.TELEGRAM_BOT_TOKEN && token) env.TELEGRAM_BOT_TOKEN = token;
+      if (!env.TELEGRAM_ALLOWED_USER_IDS && users) env.TELEGRAM_ALLOWED_USER_IDS = String(users);
+      if (env.TELEGRAM_BOT_TOKEN) return file;
+    } catch {}
+  }
+  return null;
+}

package/src/index.js

@@ -0,0 +1,119 @@
+import { tool } from "@opencode-ai/plugin";
+import { acquirePollLock } from "./lock.js";
+import { loadTelegramEnv } from "./env.js";
+import { Bridge } from "./bridge.js";
+import { TelegramApi } from "./telegram.js";
+
+let singleton;
+let pollLock;
+let lifecycle = Promise.resolve();
+function serialize(action) {
+  const result = lifecycle.then(action);
+  lifecycle = result.catch(() => {});
+  return result;
+}
+
+async function buildClient(ctx, log) {
+  const { client, directory, serverUrl } = ctx;
+  const v1Config = client?._client?.getConfig?.() ?? {};
+  const inProcessFetch = typeof v1Config.fetch === "function" ? v1Config.fetch : undefined;
+  const baseUrl = (typeof v1Config.baseUrl === "string" && v1Config.baseUrl) || (typeof serverUrl === "string" && serverUrl) || "http://localhost:4096";
+  let sdk;
+  try {
+    sdk = await withTimeout(import("@opencode-ai/sdk/v2/client").catch(() => import("@opencode-ai/sdk/v2")), 10000, "SDK import");
+  } catch (e) {
+    await log("warn", `SDK v2 import failed: ${e.message}`);
+    throw new Error("OpenCode SDK v2 is required to start the Telegram bridge");
+  }
+  const factory = sdk.createOpencodeClient || sdk.default?.createOpencodeClient;
+  if (factory) {
+    const v2 = factory({ ...v1Config, baseUrl, throwOnError: true, ...(directory ? { directory } : {}), ...(inProcessFetch ? { fetch: inProcessFetch } : {}) });
+    return { client: v2, via: inProcessFetch ? "v2-inprocess" : "v2-http" };
+  }
+  throw new Error("OpenCode SDK v2 client factory is unavailable");
+}
+
+async function withTimeout(promise, ms, label) {
+  let timer;
+  try {
+    return await Promise.race([promise, new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(label + " timed out")), ms);
+    })]);
+  } finally { clearTimeout(timer); }
+}
+
+export const TelegramControlPlugin = async (ctx) => {
+  const { client } = ctx;
+  const envFile = loadTelegramEnv(ctx.directory);
+  const log = async (level, message, extra = {}) => {
+    try {
+      await client.app.log({ body: { service: "opencode-telegram-connect", level, message, extra } });
+    } catch {}
+  };
+  if (envFile) await log("info", `Telegram env loaded from ${envFile}`);
+
+  return {
+    event: async ({ event }) => {
+      if (singleton) await singleton.onEvent(event);
+    },
+    tool: {
+      telegram_connect: tool({
+        description: "Connect this OpenCode session to the configured Telegram bot. Use this when the user asks to connect, control, continue, or use this session from Telegram.",
+        args: {},
+        async execute(_args, context) {
+          return serialize(async () => {
+            loadTelegramEnv(ctx.directory);
+            if (!process.env.TELEGRAM_BOT_TOKEN) throw new Error("Configure the Telegram token before connecting.");
+            if (singleton) {
+              const result = singleton.startPairing(context.sessionID);
+              return result.message + await singleton.announceConnection();
+            }
+            const telegram = new TelegramApi(process.env.TELEGRAM_BOT_TOKEN);
+            const me = await telegram.call("getMe", {}, AbortSignal.timeout(10000));
+            const lock = acquirePollLock(String(me.id));
+            if (!lock.owned) throw new Error("Another OpenCode instance is connected to this bot. Disconnect it first, then retry telegram_connect.");
+            try {
+              const built = await buildClient(ctx, log);
+              const bridge = new Bridge({ client: built.client, telegram, logger: log });
+              const result = bridge.startPairing(context.sessionID);
+              const notice = await bridge.announceConnection();
+              await bridge.start();
+              singleton = bridge;
+              pollLock = lock;
+              await log("info", "Telegram bridge polling started by telegram_connect");
+              return result.message + notice;
+            } catch (error) {
+              lock.release();
+              throw error;
+            }
+          });
+        },
+      }),
+      telegram_status: tool({
+        description: "Show whether the OpenCode Telegram control bridge is configured and running.",
+        args: {},
+        async execute(_args, context) {
+          if (!process.env.TELEGRAM_BOT_TOKEN) return "Telegram is not configured. TELEGRAM_BOT_TOKEN is missing.";
+          if (!singleton) return "Telegram is inactive. Ask the agent to call telegram_connect to start it.";
+          return `Telegram bridge is running. Session: ${context.sessionID}. Authorized chats: ${singleton.bindings.size}.`;
+        },
+      }),
+      telegram_disconnect: tool({
+        description: "Stop Telegram polling and disconnect this OpenCode plugin instance.",
+        args: {},
+        async execute() {
+          return serialize(async () => {
+            if (!singleton) return "Telegram is already inactive.";
+            await singleton.stop();
+            singleton = undefined;
+            pollLock?.release();
+            pollLock = undefined;
+            return "Telegram stopped. Call telegram_connect to reconnect.";
+          });
+        },
+      }),
+    },
+  };
+};
+
+export default TelegramControlPlugin;

package/src/lock.js

@@ -0,0 +1,32 @@
+import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// A live owner must never lose its lock just because its event loop is busy.
+export function acquirePollLock(key, directory = tmpdir()) {
+  const file = join(directory, `opencode-telegram-connect-${key}.lock`);
+  const mine = `${process.pid}:${Date.now()}`;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(file, "wx");
+      try { writeFileSync(fd, mine); } finally { closeSync(fd); }
+      const release = () => {
+        try { if (readFileSync(file, "utf8") === mine) unlinkSync(file); } catch {}
+        process.removeListener("exit", release);
+      };
+      process.once("exit", release);
+      return { file, owned: true, release };
+    } catch (error) {
+      if (error.code !== "EEXIST") return { file, owned: false };
+      try {
+        const owner = readFileSync(file, "utf8");
+        const pid = Number(owner.split(":")[0]);
+        if (!Number.isInteger(pid) || pid <= 0) return { file, owned: false };
+        try { process.kill(pid, 0); return { file, owned: false }; }
+        catch (e) { if (e.code !== "ESRCH") return { file, owned: false }; }
+        if (readFileSync(file, "utf8") === owner) unlinkSync(file);
+      } catch { return { file, owned: false }; }
+    }
+  }
+  return { file, owned: false };
+}

package/src/opencode.js

@@ -0,0 +1,87 @@
+export function unwrap(value) {
+  return value && typeof value === "object" && "data" in value ? value.data : value;
+}
+
+export function extractText(result) {
+  const value = unwrap(result);
+  const parts = value?.parts || value?.message?.parts || [];
+  const texts = parts
+    .filter((p) => p && p.type === "text" && typeof p.text === "string")
+    .map((p) => p.text);
+  if (texts.length) return texts.join("\n");
+  if (typeof value?.text === "string") return value.text;
+  return "";
+}
+
+export function normalizeSessions(result) {
+  const value = unwrap(result);
+  return Array.isArray(value) ? value : value?.sessions || [];
+}
+
+export function normalizeProviders(result) {
+  const value = unwrap(result) || {};
+  const providers = value.providers || [];
+  const models = [];
+  for (const provider of providers) {
+    const providerID = provider.id || provider.providerID || provider.name;
+    const list = Array.isArray(provider.models)
+      ? provider.models
+      : provider.models && typeof provider.models === "object"
+        ? Object.values(provider.models)
+        : [];
+    for (const model of list) {
+      const modelID = model.id || model.modelID || model.name;
+      if (providerID && modelID) {
+        models.push({ providerID, modelID, label: `${providerID}/${modelID}` });
+      }
+    }
+  }
+  return models;
+}
+
+export async function promptSession(client, sessionID, text, model) {
+  const body = { parts: [{ type: "text", text }] };
+  if (model) body.model = { providerID: model.providerID, modelID: model.modelID };
+  const result = await client.session.prompt({ sessionID, ...body });
+  if (result && typeof result === "object" && "error" in result && result.error) {
+    const e = result.error;
+    throw new Error(e.message || e.name || e._tag || JSON.stringify(e));
+  }
+  return result;
+}
+
+export async function replyPermission(client, sessionID, requestID, reply) {
+  if (typeof client.permission?.reply === "function") {
+    return client.permission.reply({ sessionID, requestID, reply });
+  }
+  if (typeof client.permission?.respond === "function") {
+    return client.permission.respond({ sessionID, permissionID: requestID, response: reply });
+  }
+  if (typeof client.postSessionByIdPermissionsByPermissionId === "function") {
+    return client.postSessionByIdPermissionsByPermissionId({
+      path: { id: sessionID, permissionID: requestID },
+      body: { response: reply },
+    });
+  }
+  if (typeof client.session?.permissionReply === "function") {
+    return client.session.permissionReply({
+      path: { id: sessionID, requestID },
+      body: { reply },
+    });
+  }
+  throw new Error("OpenCode permission reply API is unavailable in this version");
+}
+
+export async function replyQuestion(client, requestID, answers) {
+  if (typeof client.question?.reply === "function") {
+    return client.question.reply({ requestID, answers });
+  }
+  throw new Error("OpenCode question reply API is unavailable in this version");
+}
+
+export async function rejectQuestion(client, requestID) {
+  if (typeof client.question?.reject === "function") {
+    return client.question.reject({ requestID });
+  }
+  throw new Error("OpenCode question reject API is unavailable in this version");
+}

package/src/telegram.js

@@ -0,0 +1,63 @@
+const MAX_TELEGRAM_TEXT = 4096;
+
+export function splitTelegramText(text, limit = MAX_TELEGRAM_TEXT) {
+  const value = String(text ?? "");
+  if (value.length <= limit) return [value];
+  const chunks = [];
+  let rest = value;
+  while (rest.length > limit) {
+    let cut = rest.lastIndexOf("\n", limit);
+    if (cut < Math.floor(limit * 0.6)) cut = rest.lastIndexOf(" ", limit);
+    if (cut < Math.floor(limit * 0.6)) cut = limit;
+    chunks.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^\n/, "");
+  }
+  if (rest) chunks.push(rest);
+  return chunks;
+}
+
+export class TelegramApi {
+  constructor(token, fetchImpl = globalThis.fetch) {
+    if (!token) throw new Error("TELEGRAM_BOT_TOKEN is required");
+    if (typeof fetchImpl !== "function") throw new Error("fetch is unavailable");
+    this.base = `https://api.telegram.org/bot${token}`;
+    this.fetch = fetchImpl;
+  }
+
+  async call(method, body = {}, signal) {
+    const response = await this.fetch(`${this.base}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: signal || AbortSignal.timeout(15000),
+    });
+    const json = await response.json();
+    if (!response.ok || !json.ok) {
+      throw new Error(`Telegram ${method} failed: ${json.description || response.status}`);
+    }
+    return json.result;
+  }
+
+  getUpdates(offset, timeoutSeconds, signal) {
+    return this.call("getUpdates", {
+      offset,
+      timeout: timeoutSeconds,
+      allowed_updates: ["message", "callback_query"],
+    }, signal);
+  }
+
+  async sendMessage(chatId, text, extra = {}) {
+    for (const chunk of splitTelegramText(text)) {
+      await this.call("sendMessage", {
+        chat_id: chatId,
+        text: chunk || " ",
+        disable_web_page_preview: true,
+        ...extra,
+      });
+    }
+  }
+
+  answerCallbackQuery(id, text) {
+    return this.call("answerCallbackQuery", { callback_query_id: id, text, show_alert: false });
+  }
+}

package/src/user-id.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { loadTelegramEnv } from "./env.js";
+import { TelegramApi } from "./telegram.js";
+
+loadTelegramEnv(process.cwd());
+try {
+  const api = new TelegramApi(process.env.TELEGRAM_BOT_TOKEN);
+  const updates = await api.getUpdates(undefined, 0, AbortSignal.timeout(10000));
+  const users = new Map();
+  for (const update of updates) {
+    const user = update.message?.from;
+    if (user && !user.is_bot) users.set(user.id, user.username || user.first_name || "Telegram user");
+  }
+  for (const [id, name] of users) console.log(`${name}: TELEGRAM_USER=${id}`);
+  if (!users.size) console.log("Send a private message such as Hallo to your bot, then run this command again. Keep the OpenCode Telegram bridge disconnected during setup.");
+} catch {
+  console.error("Could not read Telegram updates. Check telegram.env, your network, and that no other instance polls this bot. The token is not printed.");
+  process.exitCode = 1;
+}