@lalilulelo3/dsh-notify

🌏 中文文档：README_ZH.md · English

中文简介：DeepSeek Harness 的 Windows 桌面通知插件 —— agent 完成任务、或需要你回答 / 授权时，弹出原生系统通知（toast）并响铃。完整中文文档见 README_ZH.md。

Windows desktop notifications for DeepSeek Harness — get a native toast and a sound when the agent finishes a turn, or when it is waiting for you.

Why

DSH runs long tasks. If you are not staring at the conversation window, you miss the moment the agent finishes or blocks on your input. dsh-notify observes the harness event bus on the host and raises a Windows toast, so it works whether the browser tab is focused, in the background, or closed.

A turn ended · the harness is waiting for your answer · the harness is waiting for your approval

Requirements

• Windows 10 or 11
• DeepSeek Harness booted with the web profile
• Node.js >= 20

Install

dsh plugin --profile web add @lalilulelo3/dsh-notify

Then restart dsh web. The package declares dsh.bundle.patch, so the CLI adds it to dsh.profile.bundles and the profile boot mounts it — no profile file edits are required.

What triggers a notification

Moment	Hook	Notified
A turn ends	turn/end session event	completed / error / blocked / max-tokens
The harness waits for your answer	user-questions/request waterfall	always
The harness waits for your approval	approval/asked session event	always

The plugin is observe-only: its user-questions/request listener is prepended, notifies, and then calls next(), so the real answerer still receives the request untouched. A failed notification is swallowed and never disturbs the agent loop. Top-level sessions are labelled by their workspace folder name (falling back to a short session id), and child (subagent) sessions stay silent unless you set subagents: true.

Configuration

Every field is optional. Add an id-targeted override to your profile patch file (~/.dsh/profiles/web/cordis.patch.yml), which the profile reloads live:

- id: dsh-notify
  config:
    sound: false
    reasons: [completed, error]

Field	Type	Default	Meaning
enabled	boolean	true	Master switch; false disables the plugin
turnEnd	boolean	true	Notify when a turn ends
question	boolean	true	Notify when the harness waits for an answer
approval	boolean	true	Notify when the harness waits for approval
reasons	string[]	[completed, error, blocked, max-tokens]	Which turn/end reasons notify (aborted, interrupted are opt-in)
subagents	boolean	false	Also notify for subagent (child) sessions; off keeps multi-agent runs quiet
appId	string	com.lalilulelo3.dsh-notify	AppUserModelID the toast is sent under; Windows lists it as DSH Notify
sound	boolean	true	Play the Windows default notification sound
title	string	DSH	Toast heading

How it works

The package has one host half (lib/index.js) and no client half, so nothing in the Web UI needs rebuilding. On mount it subscribes to:

• session/event — the session firehose. turn/end carries { turn, reason: { kind } }; approval/asked carries { id, toolName }.
• user-questions/request — the Cordis waterfall the ask_user_question tool dispatches. The listener is prepended so the notification fires before the Web answerer consumes the request, then delegates with next().

A notification spawns powershell.exe -EncodedCommand with a small WinRT toast script. The child is fire-and-forget; the plugin never awaits it.

App identity

Toasts are sent under the plugin's own AppUserModelID (com.lalilulelo3.dsh-notify), registered on first use through HKCU\Software\Classes\AppUserModelId\… with the display name DSH Notify.

Earlier releases borrowed powershell.exe's identity instead — the usual trick for scripting a toast. That identity is shared with the Windows PowerShell app, so switching "Windows PowerShell" off in Settings → Notifications silently disabled every notification, and nothing in that list pointed back to this plugin. With a dedicated identity the plugin is listed by its own name and can only be toggled on purpose.

On first mount the plugin provisions both pieces Windows requires, in the background and idempotently (lib/win-identity.ps1):

1. the HKCU\Software\Classes\AppUserModelId\… registration, so the app appears in Settings → Notifications at all, and
2. a Start Menu shortcut (DSH Notify.lnk) carrying that AUMID. Without the shortcut Windows accepts the toast but only files it in the notification centre — no banner and no sound.

Both writes are best-effort: a failure degrades to a banner-less toast, never a broken boot.

On non-Windows platforms the plugin loads and stays inert, so a shared profile still boots.

Uninstall

dsh plugin --profile web remove @lalilulelo3/dsh-notify

Then restart dsh web.

Troubleshooting

No toast appears at all.

1. Restart dsh web — a newly installed bundle only mounts at boot.
2. Confirm it is in the composed config: dsh --profile web --dump-config should list @lalilulelo3/dsh-notify.
3. Check Windows notifications: Settings → System → Notifications, and make sure Focus Assist / Do Not Disturb is off.
4. The plugin is Windows-only; elsewhere it loads and stays inert by design.

Multi-agent runs are noisy. Child (subagent) sessions are skipped by default. If you still see too many, narrow the reasons:

- id: dsh-notify
  config:
    reasons: [completed, error]

Notifications stopped after something was switched off. Find DSH Notify in Settings → System → Notifications and switch it back on. Releases before 0.2.0 sent toasts under "Windows PowerShell" instead, so that entry — not this plugin's — was the one to check.

The toast lands in the notification centre with no banner and no sound. Windows needs the Start Menu shortcut for a desktop app's banner. Delete %APPDATA%\Microsoft\Windows\Start Menu\Programs\DSH Notify.lnk, restart dsh web, and the plugin rebuilds it on mount.

dsh web no longer starts. Remove the plugin and restart:

dsh plugin --profile web remove @lalilulelo3/dsh-notify

License

MIT