dsh-notify

简体中文 | English

A DeepSeek Harness (DSH) plugin that raises Windows desktop toasts when a root-session agent finishes, errors, or asks the user a question — plus browser notifications on remote devices (tablets / phones viewing the DSH Web UI over LAN or VPN).

Features

• Toast on the currently viewed root-session agent running → idle ("task done")
• Toast on agent errors (deduped per turn:step, up to 64 entries remembered)
• Host-side toast when ask_user_question actually starts waiting for the user (deduped per tool call; no toast if startup fails immediately)
• Browser notification whenever any foreground or background root session gains a question or plan-review interaction that needs the user
• /notify command: /notify status, /notify on|off, /notify test
• Settings tab "远程通知" (Remote Notifications) toggle, sharing one global switch with the /notify command (persisted in ~/.dsh/notify-state.json)
• Only root sessions notify — subagents stay silent

Install

This is a pure-local plugin (no @deepseek-ai imports), so a link: dependency is safe:

# assuming the plugin lives at ~/.dsh/plugins/dsh-notify
dsh plugin --profile web add ~/.dsh/plugins/dsh-notify

Or insert a row in your Cordis composition patch:

- insert:
    - id: notify
      name: dsh-notify
      inject: [webServer]   # required: wait for the webServer service before registering routes

Restart dsh web after changing the composition or updating the plugin, then reload the browser page. Keep any existing --trusted-host arguments when restarting.

Usage

• Desktop: native WinRT toast with the default notification sound when a task finishes, errors, or waits for the user's answer
• Remote devices (browser): the page uses a Service Worker (/dsh-notify/sw.js). Completion and error state follow the currently viewed session; question and plan-review waits are watched across every foreground/background root session.
• Permission: the browser asks for notification permission on first use. If it was previously denied, re-enable it in the site settings.
• Toggle: Settings → 远程通知, or /notify off (remote pages re-sync the switch when the tab becomes visible)

Compatibility

• Desktop toasts require Windows + WinRT
• Version 1.2.1 fixes the Failed to load plugins / dsh-notify startup error on DSH 0.1.7-rc.1; Web UI recovery was confirmed after restart.
• The all-session pending-interaction watcher reads uiSession.sessionStatus on DSH 0.1.7 and falls back to the older uiSession.pendingInteractions API.
• Regression tests cover both API shapes and prefer the new API when both are present. Older live-runtime compatibility and Android system notifications were not revalidated for this patch.

Testing

All tests are offline and use mocked services; no running DSH Web instance is required.

node test/notify-client-test.mjs legacy
node test/notify-client-test.mjs unified
node test/notify-client-test.mjs both
node test/notify-events-test.mjs
node test/notify-state-test.mjs

• notify-client-test.mjs: 35 checks per API mode covering all-session question / plan-review behavior, deduplication, current-session completion/errors, status-only updates, and cleanup
• notify-events-test.mjs: 9 checks covering Host ask_user_question waiting detection, call deduplication, unrelated tools, and root-only filtering
• notify-state-test.mjs: 17 checks covering GET/POST /dsh-notify/state, persistence, payload validation, same-origin handling, 405/413 responses, and sw.js

Support

If this plugin saves you time or a headache, a coffee is appreciated:

• PayPal: paypal.me/dawn388887

License

MIT © 2026 Dawn388887