dsh-telegram-channel

Readme

# DSH Telegram Bridge (todayer)

Telegram bridge (bot) for **DeepSeek Harness (dsh)**: manage local sessions, topics and media right from Telegram. Based on [`hi-wenw/dsh-telegram-channel`](https://github.com/hi-wenw/dsh-telegram-channel) and extended with mechanisms from the Telegram gateway of the [Hermes](https://github.com/NousResearch/hermes-agent) agent.

> **Quick start:** `dsh plugin --profile web add github:todayer/todayer-dsh-telegram-bridge`

---

## Features

- 🧵 **Per-chat/topic sessions** — each topic (forum / DM topic) is its own session; bot replies land in the same thread.
- 📌 **Topics** — `message_thread_id`, correct handling of the General topic (`1`), `createForumTopic`/`editForumTopic`/`deleteForumTopic`; **auto-renames the topic to the session title**.
- 💬 **DM Topics (Bot API 9.4)** — topics right in a 1-on-1 chat, each an isolated session; root-DM lobby mode. (`DSH_TELEGRAM_DM_TOPICS`)
- 👥 **Group gating** — `require_mention`, `allowed_chats`, `allowed_topics`, `free_response_chats/topics`, `guest_mode`, `ignored_threads`.
- 🖼 **Media in/out** — accept photos/videos/voices/files/stickers; send files natively via `MEDIA:/path` tags.
- ⌨️ **Commands** — `/new /reset /stop /sessions /last /model /status /unbind /help`.
- ✅ **Status indicator** Online/Offline (`setMyShortDescription`).
- 🛡 **Tool-call filter** — `<tool_calls>` never leak into Telegram.
- 🔥 **Polling resilience** (409 conflict + exponential backoff).
- 🔘 **Choice/clarify** — `ask_user_question` → inline buttons (when `userQuestions` is available).
- 🌐 **Bilingual** — Russian and English (set `DSH_TELEGRAM_LANG=ru|en`).

## Install

> Requires: Node ≥ 22, `dsh web` with a model, and a bot from `@BotFather`.

```bash
# locally (from this machine)
dsh plugin --profile web add ./dsh-telegram-channel-local

# from the repository
dsh plugin --profile web add github:todayer/todayer-dsh-telegram-bridge
# or from tarball
dsh plugin --profile web add ./dsh-telegram-channel-0.3.5.tgz
```

## Configuration (`~/.dsh/telegram.env`)

```ini
# required
DSH_TELEGRAM_TOKEN=123456789:AA...            # from @BotFather
DSH_TELEGRAM_ALLOWED_USER_IDS=123456789        # your user id (from @userinfobot)

# optional — topics/groups
DSH_TELEGRAM_LANG=ru                           # ru | en
DSH_TELEGRAM_REQUIRE_MENTION=false
DSH_TELEGRAM_ALLOWED_CHATS=
DSH_TELEGRAM_ALLOWED_TOPICS=
DSH_TELEGRAM_FREE_RESPONSE_CHATS=
DSH_TELEGRAM_FREE_RESPONSE_TOPICS=
DSH_TELEGRAM_GUEST_MODE=false
DSH_TELEGRAM_IGNORED_THREADS=

# DM topics (JSON)
DSH_TELEGRAM_DM_TOPICS=[{"chatId":1212123,"topics":[{"name":"General"}]}]

# status indicator
DSH_TELEGRAM_STATUS_INDICATOR=1
DSH_TELEGRAM_STATUS_ONLINE=🟢 Online
DSH_TELEGRAM_STATUS_OFFLINE=🔴 Offline
```

Put these in the `EnvironmentFile` of the `dsh.service` and restart:
```bash
sudo systemctl restart dsh.service
```

## Bot commands

| Command | Purpose |
|---|---|
| `/start` | Welcome / help |
| `/sessions` | List sessions by workspace + attach |
| `/new` | Create a new session (force-new) |
| `/reset` | Alias for `/new` |
| `/last` | Last turn of the bound session |
| `/model` | Switch model |
| `/status` | Current binding |
| `/stop` | Stop and detach |
| `/unbind` | Detach (without deleting) |
| `/help` | Full command list |

## Structure

```
lib/
  bridge.js      — core logic (message handling, topics, sessions, commands)
  client.js      — Telegram Bot API client (polling, files, topics)
  catalog.js     — sessions/workspaces catalog
  commands.js    — commands and messages (bilingual)
  format.js      — formatting/cleanup (incl. stripToolCalls)
  history.js     — "last turn"
  index.js       — plugin registration (Config/inject)
  ...
```

## License

[MIT](./LICENSE)

## Origin

Based on [hi-wenw/dsh-telegram-channel](https://github.com/hi-wenw/dsh-telegram-channel). Mechanics extended following the Telegram gateway of [Hermes Agent](https://github.com/NousResearch/hermes-agent).

---

**Русский:** [README.ru.md](./README.ru.md)