dsh-telegram

Telegram runtime adapter for DeepSeek Harness — talk to your dsh agents from Telegram. Every allowed chat maps to one agent session; messages flow in via followup(), committed assistant text streams back to the chat. Zero runtime dependencies (plain HTTP over Node's built-in fetch).

Overview

dsh-telegram turns a DeepSeek Harness agent into a Telegram bot. It is a protocol driver in the dsh extension model: it adapts an external wire peer (Telegram) to ctx.agents, the same role the official ACP/JSON-RPC bridges play — but for human chat instead of automation.

Who is it for?

• Anyone who wants to query their DeepSeek agents from a phone, without opening the web UI.
• Teams that want a shared, auditable chat surface in front of a harness (Telegram history is kept by Telegram).
• Developers who want a minimal, readable reference for writing a protocol-driver plugin.

What it does

• Long-polls the Telegram Bot API (getUpdates) with no server, no webhook, no framework.
• Creates one dsh agent session per allowed chat on first message; subsequent messages followup() into the same session, so conversation history is preserved.
• Streams every committed assistant message back to the chat; long replies are split at Telegram's 4096-char limit.
• Supports /start, /new (fresh session), /status.
• Rejects unauthorized users outright (configurable allowlist).

What it does not do (yet)

• No webhook mode (requires a public HTTPS endpoint).
• No inline keyboards, media, voice, or rich messages — text in, text out.
• No cross-restart persistence of chat→session mapping (see Compatibility).

Compatibility

• Requires Node.js ≥ 22.19 (uses global fetch).
• Built and verified against @deepseek-ai/dsh@0.1.0-rc.6 / @deepseek-ai/cordis@^4.0.1.
• Last verified: 2026-08-13 against mainline commit of the same day (dsh repo master).
• dsh is in developer preview and iterates rapidly. Pin your dsh version and re-verify after updates; the plugin's peer dependencies (@deepseek-ai/dsh-agent, dsh-llm, dsh-session) may change shape between RC releases.
• Chat→session mapping lives in memory: restarting dsh loses open sessions (use /new to start a fresh one).

Install / Uninstall

Install into a dsh profile (local checkout; no build permission needed):

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-telegram

From GitHub (source install — pnpm runs the prepare script, so allow it once):

pnpm dsh plugin --profile web add github:<you>/dsh-telegram
# pnpm ≥10 blocks the build script on first install; copy the printed package key
# into <profile>/pnpm-workspace.yaml under allowBuilds, then re-run.

From npm (once published):

pnpm dsh plugin --profile web add dsh-telegram

Uninstall:

pnpm dsh plugin --profile web remove dsh-telegram

Quick start

1. Create a bot with @BotFather and copy the token.

2. Find your Telegram user id (e.g. message @userinfobot).

3. Set the token and your user id in the profile's cordis.patch.yml (or export DSH_TELEGRAM_BOT_TOKEN):

   - id: dsh-telegram
     name: dsh-telegram
     config:
       botToken: '123456:ABC-DEF...'
       allowedUserIds: [123456789]
       provider: deepseek-official
       model: deepseek-v4-flash

4. Start dsh, open your bot in Telegram, send /start, then any message.

Configuration

All keys live under the dsh-telegram row's config (patch layer; later layers win per row).

Permissions & data

• Authorization: the allowlist is the only gate. Unauthorized users receive ⛔ You are not authorized and are never given an agent session. The bot token itself is the secret that lets anyone call your bot; the allowlist decides who gets a session.
• Network: the plugin talks only to api.telegram.org (bot API). Agent model calls go through the harness's normal LLM provider path.
• Filesystem: no files are read or written by this plugin; agent sessions inherit the harness workspace policy.
• Secrets: never commit botToken to the repository. Use the env-var form in the shipped patch (process.env.DSH_TELEGRAM_BOT_TOKEN ?? '').
• Transcripts: Telegram keeps chat history on its servers; dsh sessions additionally persist per the harness session persistence config.

Troubleshooting

Development

pnpm install
pnpm run typecheck     # tsc --noEmit
pnpm run build         # tsc → lib/

Structure:

• src/index.ts — plugin entry (name/inject/Config/apply), Telegram client, long-poll loop, session mapping.
• cordis.patch.yml — the bundle patch layer that mounts the plugin row.

Design notes for contributors:

• Zero runtime dependencies is a goal: the Bot API surface used here is intentionally small (getUpdates, sendMessage, sendChatAction). Before adding a dependency, ask whether Node's built-ins cover it.
• Session mapping is deliberately naive (one chat = one agent, in memory). A future version may key sessions by (chat, bot) or persist them; see Compatibility.

License & security

MIT. Report security issues privately via the repository's security advisory (or open an issue without secrets). The plugin runs the Telegram token as configured by the operator; it executes no model code itself — all agent behavior is governed by the harness's own permission and sandbox policy.