dsh-notifier

One-Line Pitch

Unified notification and remote control plugin for DSH: host events (task completion/error/approval) and model-initiated pushes share a single notify() API to deliver messages to 27 push channels; 6 of those channels work bidirectionally to pull approvals, questions, and messages from phone back to desktop, and transform long-running tasks into a mobile command center with heartbeat and stop button.

Core Capabilities

• 27 Outbound Channels: Telegram, Slack, Discord, Feishu, DingTalk, Enterprise WeChat (group/app), QQ Bot, OneBot, Teams, Mattermost, Google Chat, Bark, Pushover, PushDeer, Chanify, ntfy, Gotify, iGot, WxPusher, PushPlus, Server酱, Qmsg, 息知, Webhook, Terminal Bell, System Desktop Notification
• Automatic Status Push: Host events (task start, completion, error, blocked, aborted, token limit reached, interrupted, approval needed) automatically forwarded to all configured channels; same-session rounds deduplicated with 10-second trailing-edge merging
• Tiered Routing: Emergency/Active/Passive three-tier semantics mapped to each channel's native delivery form (silent push, priority, @mention), with tiered retry
• Remote Approval & Dialogue: Six channels (Telegram, Feishu, QQ, WxPusher, WeChat, DingTalk) support callbacks; click buttons or reply 1/2 to remotely decide approvals; plain text messages enter agent session (follow-up questions/mid-course injection/steer)
• Mobile Command Center: Long tasks send first heartbeat after 15 minutes + one every 15 minutes after; no events for 10 minutes triggers potential stall warning; Telegram/Feishu cards come with one-stop stop button
• Remote Questions: ask_user tool pushes multiple-choice questions to phone (Feishu/Telegram option cards, other channels reply with number); user answers are sent back to agent; never auto-answer on timeout
• Local Web Console: Binds to 127.0.0.1 + Bearer token only, includes 6 pages: overview, notification stream, members, pairing codes, binding matrix, session ledger, channel credentials; mobile-adaptive
• Open Event Source: Other plugins can inject into notifier service for pushing, or subscribe to dsh-notifier/sent event to monitor each broadcast result; rate-limited to 10/min per source
• Identity System: Runtime pairing code admission, composite key binding (channel:userId isolates channel identity), member management, and QR code authorization; empty list starts in guided mode

Technical Implementation

• Language: JavaScript ESM (.mjs, pure ESM, zero build steps)
• Key Dependencies: @deepseek-ai/cordis (host plugin framework), @larksuiteoapi/node-sdk (Feishu long connection, lazy-loaded optional), @tencent-connect/qqbot-connector (QQ Bot, optional), qrcode-terminal (terminal QR code, optional)
• Architecture: Declarative spec engine (most channels generate adapters from data declaration tables) + 12 hand-written adapters; exposes service to host and other plugins via ctx.provide('notifier', facade); event bus auto-pushes on turn/end, approval/asked, agent/error; HMAC one-time token for remote approval
• Entry Files: src/index.mjs (apply entry), src/config.mjs (config parsing and defaults), src/notify.mjs (outbound core)

Use Cases

You have an agent running on DSH, but tasks often take 10+ minutes, and keeping a browser open on desktop to watch progress is exhausting; you want to receive completion/error notifications on your phone, click a card to stop a runaway turn, or even reply from the road to steer the agent's execution direction. The same configuration should cover both overseas/office IM like Telegram and Feishu, and domestic push apps like Server酱, Bark, and PushPlus, with new channels not requiring changes to the main flow.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:THEWOLFWALKER/dsh-notifier

Configuration Options

Written under config of the dsh-notifier entry in profile's cordis.patch.yml. Main blocks as follows (detailed schema in src/config.mjs):

FAQ

Q: What do I need to do first after installation to receive notifications?

A: Add channels under config of the dsh-notifier entry in profile's cordis.patch.yml, configuring credentials for at least one channel. Empty channels won't cause plugin errors—it will just subscribe to events without acting.

Q: How do I send approvals from phone back to desktop?

A: Enable the inbound section and configure at least one inbound channel (telegram/feishu/qq/wxpusher/wechat/dingtalk). On first deployment, write whitelist user IDs in inbound.allowUsers (after first YAML broadcast, managed via console or /pair). Then in the channel's private chat, click buttons or reply 1/2 to decide.

Q: How is notification frequency controlled?

A: Three dimensions stack: events section controls which host events trigger pushes; debounceMs controls same-session consecutive turn trailing-edge merge (default 10s); graceSeconds controls idle grace window (default 0). These three don't affect each other and can be tuned independently.

Q: How do I know a long-running task is still alive?

A: Both longRunning (first heartbeat after 15 minutes, then one every 15 minutes) and stall (no events for 10 minutes = potential stall) are on by default. Telegram/Feishu channel notification cards have a one-stop stop button—clicking it cancels the turn. turnStart is off by default to avoid alerting on every task start.

Q: Can other plugins use this notification system?

A: Yes. Inject notifier service (ctx.inject(['notifier'], …)) and call push(), or subscribe to dsh-notifier/sent event to monitor each broadcast result. Rate-limited to 10/min per source (public.limitPerMinutePerSource); excess returns structured skipped without throwing errors.

Q: Is the web console secure?

A: Host is hardcoded to 127.0.0.1, never binding to public internet (not configurable). Token is auto-generated on first start and printed to stdout once, validated with SHA-256 hash after restart; explicitly configured admin.token takes precedence. For remote access, set up your own reverse proxy.

Q: Will state data be retained after uninstall?

A: state.json stays in $HOME/dsh-notifier/ (stateDir configurable), recording whitelist, pairing codes, ledger, audit logs. Uninstalling the plugin doesn't auto-clean the disk; reinstallation can continue; manually delete the directory for complete cleanup.

Q: What happens when a channel quota is exhausted or network is down?

A: Each channel has independent circuit-breaking (short retry with backoff); when below threshold, tiered retry applies; when threshold exhausted, that channel is skipped, host continues running, ledger records failure count, other channels unaffected.

Learning Curve

Advanced — large configuration matrix (27 channels × bidirectional inbound/outbound × multi-level switches). Beginners should start with the web console (auto-generates config). When hand-writing YAML, note ${ENV:NAME} reference semantics (supported for both outbound and inbound).

Known Issues & Limitations

• WxPusher inbound depends on HTTP callback, requires public internet reach (frp/reverse proxy user responsibility); other 5 inbound channels use long connection/long polling, no public IP needed
• QQ/DingTalk/WeChat inbound don't support button cards, rely solely on number replies (reply 1 approve / 2 reject)
• Windows desktop notifications require PowerShell's BurntToast module, otherwise that channel is locally ineffective
• DingTalk Stream implementation reuses official SDK field naming (uesrAgent, noted in source) — upstream convention, copied as-is
• Feishu inbound depends on @larksuiteoapi/node-sdk (optionalDependency); when not installed, SDK load failure gives Chinese guidance then silently downgrades
• Long task heartbeat/stall warning interval min clamped at 60s (Math.max(60_000, Number(x) || default)), setting 0 not allowed — use enabled: false to disable
• state.json multi-process concurrent writes already have key-level merge + cross-process write lock + read coalescing three-layer defense, but extreme cases (massive concurrent writes) may degrade to lock-free writes with one-time warn
• v0.7.3 fixed Feishu WSClient logger: null silent crash and card message_id wrong value (CHANGELOG #1/#6), please confirm fix before upgrading
• Web console host hardcoded to 127.0.0.1 (not configurable), any attempt to expose is blocked at code level — remote access requires user-provided reverse proxy

Your agent, in your pocket. — 通知、审批、遥控，全在你的手机里。

English · 简体中文

Unified notification push plugin for DeepSeek Harness (DSH) — one minimal notify() API in front, 27 channels behind.

Your agent and the harness itself both push through it: session events (turn/end · approval/asked · agent/error) auto-notify, the model calls a notify tool directly, and six inbound channels bring approvals and conversations back from your phone. v0.3 adds a local web console and multi-agent routing; v0.4 adds native desktop notifications; v0.5 turns your phone into a command center — long-task heartbeats, stall alerts, and a stop button riding the notification itself; v0.7 upgrades "who counts as family" from opaque YAML strings into a runtime identity system — pairing codes, composite-key bindings, and a members page in the admin console — all with zero runtime dependencies.

How it works

DSH agent ──notify() tool─────────┐
                                  ├─▶ notifier core ─▶ 27 channels (IM webhooks / push apps / China apps)
DSH session events ──auto push────┘   level routing · tiered retries · segmentation · anti-disturb · ledger
                                      heartbeat ⏱ / stall ⚠ (v0.5) ──▶ cards with a ⏹ stop button
your phone ──6 inbound channels───▶   remote approval (buttons · reply 1/2) · remote conversation (followup/inject/steer)

Every message resolves through one chain — level (timeSensitive / active / passive) → routing (multi-agent matrix) → channel adapter (resolve(cfg) + send(msg)). Two trigger lines feed it: the harness auto-pushes session events (debounced, deduped), and the model calls the notify tool. Six inbound channels ride the same core in reverse for approvals and conversation — and since v0.5 the outbound line reports back too: long-running turns send heartbeats, silent turns raise stall alerts, and Telegram/Feishu notifications carry a one-click stop action.

Screenshots

The web admin console (admin.enabled: true, loopback only, mobile-friendly since v0.5) — all six pages (demo data):

Quick start

dsh plugin add dsh-notifier --profile <profile-name>

--profile is required (DSH 0.1.0-rc.6+): plugin installs target a named profile — use the one you run (e.g. web).

Add channels to your profile patch (cordis.patch.yml):

insert:
  - id: dsh-notifier
    name: dsh-notifier
    config:
      channels:
        - type: telegram
          botToken: "123456:ABC-DEF..."
          chatId: "987654321"
        - type: dingtalk
          webhook: "https://oapi.dingtalk.com/robot/send?access_token=..."
          secret: "SEC..."
        - type: bark
          key: "your-device-key"

That's it. turn/end, approval/asked, and agent/error events now reach every configured channel, and the model can push on its own with notify({ message, channel, title }). Long tasks send heartbeats and stall alerts out of the box (v0.5 defaults), and you can stop a runaway turn right from the notification card.

Core features

Configuration

All channels live under config.channels. Key example:

insert:
  - id: dsh-notifier
    config:
      channels:
        - type: telegram
          botToken: "123456:ABC-DEF..."
          chatId: "987654321"
        - type: feishu
          webhook: "https://open.feishu.cn/open-apis/bot/v2/hook/..."
        - type: wxpusher
          appToken: "AT_..."
          uids: ["UID_..."]
        - type: serverchan
          sct: "SCT..."

Optional blocks each opt in under their own key:

v0.5 status line defaults: longRunning and stall are on (15min first heartbeat, then every 15min; stall after 10min of silence) — zero-config long tasks are no longer a black box. turnStart is off by default (one message per turn is noise at the desk; turn it on when you fire a task and walk away). All timings clamp to a 60s floor; disable any of them with enabled: false.

Channels

Six channels also open inbound (remote approval + conversation): telegram, feishu, qq-bot, wxpusher, wechat, dingtalk — long-lived connections or long polling, so no public IP is required (only the WxPusher callback needs one). Since v0.5, telegram and feishu additionally carry notification action cards (stop button). Since v0.7, every inbound channel answers /help /whoami /pair /unpair registration commands, and outbound card targets resolve through a three-tier priority (per-channel bindings → channel config lists → global fallback) with per-channel id-shape guards.

Architecture

src/
  adapters/           27 channel adapters (resolve(cfg) + send(msg)) + declarative spec engine
  config.mjs          channel registry + config schema — single source of truth for the matrix
  index.mjs           plugin assembly: patch, tools, event listeners, admin wiring
  event-listener.mjs  auto-push line (debounce, dedup, level routing) + v0.5 status wiring
  status/             v0.5 turn tracker (heartbeat / stall detection, pure logic)
  actions.mjs         v0.5 notification action dispatch (turn/cancel, HMAC one-time tokens)
  notify.mjs          notify / notify_test tools + sliding-window rate limiting
  routing/            multi-agent matrix (resolveOutbound / resolveInbound)
  inbound/            six inbound channels (telegram/feishu/qq/wxpusher/wechat/dingtalk) + v0.7 identity stack
                      (identity.mjs bindings · pairing.mjs codes · commands.mjs registration · target-guard.mjs resolution)
  approval/           HMAC one-time tokens, dedup, escalation
  admin/              web console (6 pages, SSE, bearer auth, mobile layout)
  ledger.mjs          JSONL ledger + daily digest
  rules.mjs           anti-disturb gates (event / keyword / grace)
scripts/              channel-login.mjs · test-channel.mjs · route.mjs · gen-channel-matrix.mjs
test/                 846 tests (node --test)

Design rules: pure ESM (.mjs), zero runtime dependencies, a declarative spec engine for the bulk of channels, thin honest adapters, no build step.

Development

npm test          # node --test, 846 cases

To add a channel: implement the adapter interface (resolve(cfg) + send(msg)) in src/adapters/ and register it in src/config.mjs; the channel matrix above self-regenerates via node scripts/gen-channel-matrix.mjs.

License

MIT · third-party notices in THIRD_PARTY_NOTICES.md