DeepSeek Harness Plugin: dsh-notifier

Preface¶

In the agent development and runtime scenarios of DeepSeek Harness (DSH), approval requests, task completion status, and error messages are often easily buried under background processes. The dsh-notifier plugin solves this problem by providing an independent notification channel through the browser Notification API and system-native Toast notifications (Windows PowerShell WinRT / macOS osascript / Linux notify-send), ensuring that users receive key event reminders even when they are not in front of the browser. This plugin is forked from wingsky-1/dsh-notifier and provides DSH with lightweight event distribution capabilities.

Installation¶

Before installation, make sure dsh web is running normally. This plugin is built independently and does not depend on the upstream plugin repository.

dsh plugin --profile web add @jypjypjypjyp/dsh-notifier

After installing, uninstalling, or updating, restart dsh web once so that the bundle takes effect. If dsh is not installed globally, you can invoke it temporarily with npx (requires pnpm and Node.js installed locally):

npx @deepseek-ai/dsh plugin --profile web add @jypjypjypjyp/dsh-notifier

Access Methods¶

All plugin endpoints are protected by a loopback guard and accept only local loopback (127.0.0.1 / localhost) calls. Therefore, directly calling the HTTP endpoints from a LAN browser returns 403, and the notification channel will not work.

Use one of the following access modes:

Core Features¶

The plugin distributes events through dual channels and supports multiple management strategies.

1. Event Types¶

• Asks you a question (on by default): Notifies when ask_user_question / a GUI question popup is triggered.
• Approval reminder: Triggered by the real approval path, including task title, tool name, request reason, and action hints.
• Completion reminder: Notifies when a task transitions from running to idle. Subagent completion requires enabling notifySubagentDone (off by default).
• Error reminder: Notifies when a task errors. Error information is redacted (first 300 characters). Similar errors are automatically merged within 60 seconds.
• Turn completion (off by default): Notifies on agent/turn-stopping.

2. Notification Channels¶

• System notifications: Windows uses PowerShell WinRT, macOS uses osascript, and Linux uses notify-send; none require additional installation.
• Browser notifications: Delivered via SSE and shown only when the page is hidden.
• Fallback strategy: In non-secure contexts (such as LAN HTTP), automatically falls back to an in-page banner, notification sound, and title reminder.

3. Management Strategies¶

• Do Not Disturb hours: Supports settings that cross midnight (e.g., 22:00-08:00) and allows configuring urgent exceptions.
• Completion storm aggregation: When multiple tasks/subagents finish at the same time, they are aggregated into “N other tasks have completed” to avoid spam.
• Approval timeout re-reminder: Reminds again if still unprocessed after waiting more than askRemindMin minutes (default 5).

Configuration and APIs¶

The configuration file is located at ~/.dsh/dsh-notifier.json by default and can be read or written through the /api/dsh-notifier/config endpoint.

Common configuration items:

{
  "notifyAsk": true,
  "notifyTaskDone": true,
  "notifyTaskError": true,
  "notifySubagentDone": false,
  "quietHours": { "enabled": false, "start": "22:00", "end": "08:00", "allowKinds": [] },
  "errorMergeWindowMs": 60000,
  "askRemindMin": 5
}

Endpoint list:
- GET/PUT /api/dsh-notifier/config: Read/save configuration.
- GET /api/dsh-notifier/events: Subscribe to SSE notification frames.
- POST /api/dsh-notifier/test: Send a test notification (bypasses Do Not Disturb).
- GET /api/dsh-notifier/history: Fetch recent notification records (up to 200 entries).
- DELETE /api/dsh-notifier/history: Clear records.
- GET /api/dsh-notifier/health: Health check.

Security and Limitations¶

• Secure context: Browser notifications require HTTPS or localhost. Regular tabs in iOS Safari do not have the Web Notifications API; add the site to the home screen to obtain PWA-level notifications.
• Loopback protection: All endpoints reject non-local calls.
• Data redaction: Paths, private keys, tokens, passwords, and other sensitive information in error notifications, approval reasons, and question text are redacted into placeholders.
• Notification target distinction: Browser notifications are pushed to the current browser client; system notifications (Toasts) appear on the desktop of the host machine where dsh web is running.

Verification¶

Local health check:

curl -s http://127.0.0.1:3080/api/dsh-notifier/health