dsh-plugins/packages/telegram-remote/README.md

🤖 dsh-telegram-remote

Full remote control + live state visibility for the DeepSeek Harness — from Telegram.

Turn any Telegram chat into a pocket terminal for your harness: chat with your AI, watch replies stream live (thinking → tools → text), run commands, manage chats/subagents/goals/jobs, and control every harness feature — all through one bot with zero external services (direct Bot API long polling).

---

✨ Features

• 💬 Chat from Telegram — send a message, get a live-streamed structured reply (thinking, tools, final answer) edited in place
• 🎙️ Voice & audio — send a voice message or audio file; it is transcribed through your home-lab Whisper server (default large-v2 on CUDA GPU) and the text is sent to your AI
• 🎛 Full harness control — 49 commands: chats, models, sessions, subagents, goals, jobs, files, PowerShell, exports, presets, skills, settings, credentials, permissions, and more
• 📡 Live state — status, running turns, queued messages (steer / edit / remove), background jobs
• 🔐 Permission-aware — sandbox read/write/full control per chat, approval buttons for risky tools
• 🔔 Notifications — per-chat on/off/all, background activity pushed to you
• 🔄 Hot reload — plugin edits hot-reload with no restart (HMR)
• 🔒 Single-instance — a lock file guarantees exactly one poller per bot token (no Telegram 409s)
• 🖥 Works everywhere — long polling means no public IP / no webhooks / works behind NAT

📦 Requirements

• Node.js >= 22 (uses global fetch)
• A DeepSeek Harness installation with a profile (e.g. web)
• A Telegram bot token from @BotFather

🚀 Installation

1. Install the plugin into your harness profiles:

   # from your harness profile dir (e.g. ~/.dsh/profiles/web)
   npm install link:path/to/dsh-telegram-remote
   

   Or add it to the profile's package.json:

   {
     "dependencies": {
       "dsh-telegram-remote": "link:C:/path/to/dsh-telegram-remote"
     }
   }
   

2. Add the plugin to the profile patch (cordis.patch.yml):

   - insert:
       - id: telegram-remote
         name: 'dsh-telegram-remote'
         config:
           tokenFile: 'C:\path\to\telegram.token'   # file containing the bot token
           ownerChatId: 123456789                     # YOUR telegram user id (get it from /whoami)
           workspaceRoot: 'C:\path\to\workspace'
           allowEval: true
           notifyOnStartup: true
   

3. Create the token file (or set tokenEnv instead):

   Set-Content -Path telegram.token -Value "123456:ABC-your-bot-token" -NoNewline
   

4. Start the harness, open the chat with your bot, and send /start.

⚙️ Configuration

Key	Default	Description
botToken	""	Token directly (alternative to a file/env)
tokenEnv	"TELEGRAM_BOT_TOKEN"	Env var holding the token
tokenFile	""	File containing the token
ownerChatId	undefined	Your Telegram user id — full access
allowedUserIds	[]	Extra users allowed to chat
workspaceRoot	process.cwd()	Where /new chats start
allowEval	true	Enable /eval (runs JS in the harness)
notifyOnStartup	true	Send a "bot online" message on boot
stateFile / logFile	~/.dsh/...	Override runtime state / log paths
whisperBaseUrl	"http://192.168.31.159:8082"	Home-lab Whishper server base URL
whisperModel	"large-v2"	Whisper model used for transcription
whisperDevice	"cuda"	Whishper device (cuda or cpu; GPU is cuda)
whisperLanguage	"auto"	Language hint ("auto" = auto-detect; e.g. ru, en)
whisperTimeoutMs	120000	Max wait for a transcription to finish
whisperMaxBytes	20971520	Max accepted audio size in bytes (20 MiB)

💬 Usage

Just type a message — it goes to your AI and the reply streams back:

💭 Thinking
<live reasoning…>

🔧 Tools
⋯ write    ✅ read

🤖 Reply
<live streaming text…>

─────── ⋆⋅☆⋅⋆ ───────
⏳ 34s

Tap the /start keyboard or type /help for the full command list. Key commands:

• /chats · /new · /open — manage chats (/chats shows 10 at a time, /chats 2 pages; subagent chats are hidden)
• /model · /models — switch AI models (/model max for deepest thinking)
• /status — what's happening right now
• /queue /steer /edit /remove — control queued messages
• /cmd /fs /mkdir — run commands and manage files
• /agents /send /interrupt — subagents
• /goal — long-running objectives
• /jobs /kill — background tasks
• /export /search /archive — conversation history
• /permission — sandbox mode per chat
• /eval /raw /api — power-user harness access
• /reboot /shutdown — harness lifecycle (graceful)

🔒 Security notes

• The bot can control your computer — only add users you trust (ownerChatId / allowedUserIds).
• Every request is checked against the per-chat /permission mode; risky tools request approval.
• /eval and /cmd are powerful — consider allowEval: false unless you need them.
• No telemetry: the bot talks to Telegram, your harness, and (for voice/audio) your home-lab Whishper server only.

🔄 Hot reload (development)

With the harness HMR enabled, editing this plugin's lib/*.js files reloads it in ~2s:

- id: hmr
  disabled: false
  config:
    root: ['C:\path\to\dsh-telegram-remote']
    ignored: []

📄 License

MIT