dsh-telegram-control

dsh-telegram-control

Remote-control plugin for DeepSeek Harness (dsh).
Runs a Telegram bot inside the harness process so you can drive your agents, jobs, and harness
status from your phone: send a message to the bot and it becomes a follow-up to your agent, whose
reply comes back to you as a Telegram message.

Everything is a plugin in dsh — this one is a Cordis function plugin that talks to the Telegram
Bot API over long-polling with zero runtime dependencies beyond the harness itself.

Features

• Remote agent control — plain text messages are sent as follow-ups to the chat's selected
  conversation and appear as ordinary user messages in the desktop Web UI conversation. The agent's
  reply — including its thinking/reasoning blocks, marked with 💭 — is relayed back the moment
  its turn closes (turn-tracked, so delivery does not depend on the agent ever reporting idle).
• Command surface — /status, /agents, /agent <session id>, /jobs, /kill <job id>,
  /cancel, /watch / /unwatch, /chatid, /help.
• Approval on the phone — harness permission requests (sandbox escalations and other
  approval/request asks) arrive in Telegram with ✅ Allow once / ❌ Reject inline buttons;
  the answer is applied and the message is edited with the outcome. If Telegram cannot be reached
  the question falls back to the Web UI dialog instead of failing closed.
• Command menu — the bot's slash commands are published via setMyCommands, so /agents,
  /agent, /jobs, … show up in the Telegram input field without being typed by hand.
• Live push — /watch forwards every assistant message from live sessions to your chat.
• Auth by chat allowlist — unknown chats get an onboarding hint with their chat id, nothing else.
• Safe output — all dynamic text is HTML-escaped before it reaches Telegram; long replies are
  split into Telegram-sized chunks.

Requirements

• dsh running from the npm package (npx @deepseek-ai/dsh) or a repository checkout.
• Node.js with a global fetch (Node ≥ 18; dsh itself needs Node ≥ 22).
• A Telegram bot token from @BotFather.

Installation

1. Get a bot token: message @BotFather, run /newbot, and copy the token.

2. Install the plugin into a profile. Either from this repository

   dsh plugin --profile web add github:jackControls/dsh-telegram-control
   

   or, from a local checkout:

   dsh plugin --profile web add /path/to/dsh-telegram-control
   

   (Replace web with the profile you run. The package declares dsh.bundle, so dsh plugin add
   installs it and activates it as a profile layer automatically — you don't need to touch
   cordis.patch.yml. lib/ is committed, so git installs work without a build step.)

3. Configure via environment in the same process that runs dsh:

   export DSH_TELEGRAM_TOKEN='123456:ABC-DEF...'
   export DSH_TELEGRAM_ALLOWED_CHATS='123456789,987654321'   # comma-separated chat ids
   

4. Restart dsh. Start a private chat with your bot, send /chatid to learn your chat id if you
   haven't added it yet, then /help.

Manual patch (no dsh plugin add)

If you prefer to mount it by hand, add a row to your profile's cordis.patch.yml
($DSH_HOME/profiles/<profile>/cordis.patch.yml):

- insert:
    - id: telegram-control
      name: 'dsh-telegram-control'
      config:
        # optional: pin values here instead of the environment
        token: '123456:ABC-DEF...'
        allowedChatIds: [123456789]

Configuration

Commands

Plain messages are sent as follow-ups to the selected conversation. Selection order: the chat's
/agent choice, then defaultAgentId, then the single conversation if there is exactly one. A
paused (persisted-but-not-live) conversation is resumed on first message exactly like the Web
UI does it — the session's stored agent preset is re-mounted, so history replays under the same
composition it was produced under. Each chat's selection is persisted to
$DSH_HOME/telegram-control-state.json, so it survives harness restarts. Conversation names come
from the harness's session titles (session/title events — the auto-summary or your manual
rename, the same names the Web UI shows); the bracketed workspace is the session's cwd.

How it works

• apply(ctx, config) runs a long-polling getUpdates loop inside the harness process
  (fetch-based, no bot framework). A 409 from the API (another poller) stops that poller cleanly;
  network errors back off up to 30 s.
• Plain messages call agent.followup(createUserMessage(...)) with source: { kind: 'user' } —
  the same source the Web UI's own input uses, so the text shows up as a normal user bubble in the
  desktop conversation.
• The plugin listens to the durable session/event feed and the live agent/inbox/claimed /
  agent/status / agent/error / agent/disposed events. Each follow-up's message id is matched
  against agent/inbox/claimed to learn its turn number, and the accumulated reply (visible text +
  💭 reasoning) is flushed when that turn's turn/end lands — an idle flush and a timeout note
  cover the remaining cases. Tool-call and error notices relay as they happen; typing indicators
  show while the agent runs.
• All registrations are Cordis effects, so unloading the plugin (HMR, profile reload) tears the
  bot down cleanly.

Security

• Every inbound message is authorized before any action. Each update's chat id is checked
  against allowedChatIds (or DSH_TELEGRAM_ALLOWED_CHATS) before anything is dispatched: no
  commands run, no messages reach an agent, and no approval answers are accepted for an
  unlisted chat. A stored userId is never treated as authorization.
• An empty allowlist denies everyone (fail closed): with no chat id configured, every
  message is rejected and the only reply an unlisted chat ever receives is the onboarding hint
  that tells it its own chat id.
• The bot is a remote shell into your harness by design: only listed chats may issue
  commands or answer approvals. Keep the allowlist tight.
• The token is a bearer credential: prefer the environment variable over a committed patch file.
• The plugin does not widen any harness capability — it can only do what your running harness can
  do, and the harness's own sandbox/approval policies still apply to agent work.

Development

npm install                 # dev deps (typecheck + build)
npx tsc                     # typecheck + emit lib/
node --test 'tests/*.test.mjs'   # unit tests for the pure helpers
node tests/smoke.mjs        # end-to-end: boots a real `dsh web` in an isolated $DSH_HOME,
                            # with fake Telegram + mock-LLM servers, and asserts the whole
                            # message→agent→relay loop (set DSH_CLI to your dsh bin if needed)

Known limitations

• Telegram webhooks are not supported; long-polling only (fine for a personal remote control).
• The plugin observes the session event feed; very high-frequency sessions could flood a watching
  chat — /unwatch is your friend.
• sessionId-keyed reply buffering assumes one user drives one agent; two chats driving the same
  agent get one combined reply per turn (each chat receives it).

License

MIT