dsh-helper

🌏 English · 中文

A DSH plugin that pops native Windows notifications when an agent session finishes, fails, or needs your confirmation — with an optional completion chime — so you can walk away from long runs and still know the moment something needs you.

✨ Features

• 🔔 Task notifications — a native Windows toast when the agent goes idle (task complete), hits an error, is about to ask you a question, or a tool needs permission approval.
• 🔊 Completion chime — plays a sound when a session finishes. Ships with a built-in synthesized two-note chime; volume is adjustable (0–100) and you can point it at any local audio file (wav / mp3 / wma).
• ⚙️ Settings panel — a Task Notifications (dsh-helper) section in DSH Settings with four notification toggles plus the sound controls.
• 🧪 Three test buttons — preview each real notification type (complete / multi-choice confirm / permission approval) with one click.
• 🪶 Zero native dependencies — notifications go through PowerShell WinRT Toast, so there is nothing to compile.
• 🔁 Hot reload — configuration is written back to the profile's cordis.patch.yml and picked up by DSH's patch watcher, no restart needed.

🚀 Installation

Prerequisites: DSH 0.1.2-rc.1+ with the web profile already initialized (run dsh web at least once), Node.js ≥ 20, pnpm ≥ 10.

Option 1 — npm

# from the git repo (works today)
npm install github:sunligh91/dsh-helper

# or from the npm registry
npm install dsh-helper

Then register it with your web profile:

dsh plugin --profile web add dsh-helper@latest

Option 2 — one-liner through DSH

dsh plugin --profile web add dsh-helper@latest

If pnpm 11 blocks build scripts, run pnpm approve-builds --all inside ~/.dsh/profiles/web and re-run the command.

Option 3 — from source

git clone https://github.com/sunligh91/dsh-helper.git
cd dsh-helper

# link it into your web profile
cd ~/.dsh/profiles/web
pnpm add file:/absolute/path/to/dsh-helper

Then add "dsh-helper" to the dsh.profile.bundles array in ~/.dsh/profiles/web/package.json, and hard-refresh your browser (Ctrl/Cmd + Shift + R).

⚙️ Configuration

Go to Settings → Task Notifications (dsh-helper).

Defaults ship in cordis.patch.yml; your overrides are written to ~/.dsh/profiles/web/cordis.patch.yml.

🔌 How it works

The settings HTTP route (/_dsh/dsh-helper/settings) is bound to localhost only — anything other than 127.0.0.1 / ::1 gets a 403.

🔄 Need auto-retry too? This plugin intentionally does notifications only. Pair it with a retry plugin such as dsh-task-reliability, which returns { kind: 'retry' } on the same event.

🛠️ Development

git clone https://github.com/sunligh91/dsh-helper.git
cd dsh-helper

Both halves are plain ES modules / UMD — there is no bundler, so edit and reload.

⚠️ Known limitations

• Notifications target Windows (PowerShell WinRT Toast). On macOS/Linux the plugin still loads, but toasts and sounds are silent no-ops.
• Sound playback uses WPF MediaPlayer via PowerShell. If that's unavailable it falls back to System.Media.SoundPlayer, which only plays wav and ignores the volume setting.
• If Windows Focus Assist / Do Not Disturb is on, toasts may be suppressed.
• Toasts are sent under Windows' built-in File Explorer app id (a registered AUMID), so no Start-Menu shortcut is required and notifications are never silently dropped for an unregistered custom id. They'll appear in Action Center grouped under "File Explorer".

📄 License

MIT © sunligh91

📝 Changelog

• 0.4.4 — Removed the global throttle introduced in 0.4.3 (it swallowed completion notifications from concurrent main sessions). Only the sub-agent filter remains.
• 0.4.3 — Fixed notification flooding: completion notifications no longer fire for sub-agents (dsh runs several sub-agents in parallel and each one finishing posted a "task complete" toast, flooding the notification center — main session ids carry a session- prefix while sub-agent ids are bare UUIDs, used for filtering); added a global 60s throttle so multiple main sessions finishing together still post at most one toast.
• 0.4.2 — The toast header now shows a real app name: the AUMID switched from the borrowed File Explorer GUID to dsh-helper, with its DisplayName idempotently written to HKCU\Software\Classes\AppUserModelId\dsh-helper before every send — the header changes from a hex GUID to dsh-helper.
• 0.4.1 — Fixed notifications falling back to a popup dialog: GetTemplateContent was mistakenly called on the ToastNotifier instance (the method belongs to the static ToastNotificationManager class), so the WinRT toast never actually succeeded and every notification took the WScript dialog fallback. Now calls the correct target — real toasts verified.
• 0.4.0 — Added a "needs permission" notification (hooks the approval/request event for tool approval dialogs); the settings panel now has three test buttons: complete / multi-choice confirm / permission.
• 0.3.2 — Fixed confirmation toasts not appearing. Windows silently drops WinRT toasts sent under an unregistered custom app id, so notifications are now sent under File Explorer's always-registered AUMID. Added a WScript.Shell popup fallback for environments where WinRT is unavailable.
• 0.3.1 — Added temporary diagnostic logging (to be removed once the confirm-notification issue is verified resolved).
• 0.3.0 — Added an optional completion chime (built-in synthesized two-note sound, adjustable volume, custom local file).
• 0.2.0 — Removed auto-retry; notifications only.
• 0.1.0 — Initial release: completion / error / confirm notifications.