dsh-telegram-notify

dsh plugin --profile web add dsh-telegram-notify

dsh-telegram-notify



One-way Telegram notifications for DeepSeek Harness.

When you are away from the DSH UI, the bot tells you that a turn finished,

failed, is waiting for an answer, has a plan ready for review, or needs a tool

approval. It never reads Telegram updates, so the bot stays send-only.

The plugin ships its own Settings → Telegram page: paste the bot token,

enter the chat id, and pick which events notify you. No YAML editing needed.

Events

Event · Message · Toggle

A turn completes · ✅ Turn complete · notifyTurnComplete

A turn fails, is blocked, or hits the token limit · ❌ / ⚠️ · notifyTurnError

A turn is cancelled · ⏹ Turn cancelled · notifyTurnAborted (off by default)

ask_user_question waits for an answer · ❓ Waiting for your input · notifyQuestions

A plan is presented for approval (exit_plan_mode / plan-review question) · 📋 Plan ready for approval · notifyPlanReviews

A tool approval waits for a human · 🔐 Approval needed · notifyApprovals

Subagent sessions are ignored. Approval and question notifications wait 400 ms

and are cancelled if the corresponding decision/tool result arrives first, so

instantly rejected approvals and instantly failing tool calls stay quiet.

Messages are fire-and-forget. A Telegram outage is logged as a warning and

never fails, blocks, or delays an agent turn.

Install

dsh plugin --profile web add dsh-telegram-notify

If your app runs the desktop profile, use --profile desktop. From a local

checkout (before the npm release), use dsh plugin --profile web add link:$PWD.

Enable the bundle by adding "dsh-telegram-notify" to dsh.profile.bundles in

~/.dsh/profiles/web/package.json (or enable it from the DSH Plugin Manager).

The bundle patch mounts the telegram-notify row.

Restart DSH, open Settings → Telegram, and:

1. Paste the bot token and press Save token. It is stored in the DSH

credential store under the reference shown on the page

(TELEGRAM_BOT_TOKEN by default), never in the plugin configuration.

2. Enter the chat id and press Save settings.

3. Pick the events you want and save again.

Getting a bot and chat id

Create a bot with @BotFather and copy its token.

Send the bot a message first, then ask a helper bot such as

@userinfobot for your numeric id. For a group, add

the bot to the group and use the group's negative id (for example

-1001234567890); @channelusername also works for public channels.

The plugin only calls sendMessage. It never calls getUpdates, so it cannot

consume messages meant for another Telegram integration.

Configuration reference

The Settings page writes the profile patch for the telegram-notify row. The

same fields remain editable in ~/.dsh/profiles/web/cordis.patch.yml:

- id: telegram-notify
  config:
    chatId: "123456789"
    tokenRef: TELEGRAM_BOT_TOKEN
    notifyTurnComplete: true
    notifyTurnError: true
    notifyTurnAborted: false
    notifyQuestions: true
    notifyPlanReviews: true
    notifyApprovals: true
    silent: false

Field · Default · Meaning

chatId · "" (disabled) · Target chat id, or @channelusername.

tokenRef · TELEGRAM_BOT_TOKEN · Credential reference holding the bot token.

token · unset · Literal token for headless/one-off runs. The Settings page never writes this; prefer tokenRef.

apiBase · https://api.telegram.org · Bot API base URL; only change for a local Bot API server.

silent · false · Send without a notification sound.

notifyTurnComplete · true · Completed turns.

notifyTurnError · true · Failed, blocked, and max-token turns.

notifyTurnAborted · false · Cancelled turns.

notifyQuestions · true · Pending user questions.

notifyPlanReviews · true · Plans waiting for approval.

notifyApprovals · true · Pending tool approvals.

The Settings page is keyed to the loader row id telegram-notify; mounting the

plugin under a different id makes the page report the namespace as unavailable.

The editable page fields are schemastery volatile config, so saves apply to

the running plugin without a restart. Messages are plain text (no parse mode),

so model output cannot break formatting or inject markup; text is clipped to

Telegram's 4096-character limit.

If you also run a two-way Telegram bridge such as dsh-im, sessions handled by

that bridge produce their own replies, and this plugin will additionally send

turn notifications for them. Disable the bridge or turn off the turn toggles

if that is noisy.

How it works

The Host half subscribes to session/event. It formats messages from

turn/end, tool/call (ask_user_question, exit_plan_mode),

approval/asked/approval/decided, assistant/message, user/message, and

session/title, and posts them with fetch. The browser half registers a

settings.section slot and reads/writes the telegram-notify namespace through

ctx.configForms; the token goes through the credentials remote. The Host

plugin disables the auto-generated config form so the secret token field is

never exposed by a generic page.

Development

pnpm install
pnpm check        # typecheck, build, node:test

Source layout: src/index.ts (Host), src/client.ts (browser settings page,

compiled as a classic module-loader script), test/ (Host event pipeline,

client registration, and server-rendered settings page). No test touches

Telegram; the transport tests use a local HTTP stub.

The first npm publish must aut

…(truncated)