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, or is about to ask you a question.
• 🔊 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 three notification toggles plus the sound controls.
• 🧪 Test button — fire a test toast and play the current sound to verify the pipeline on your machine.
• 🪶 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).

Key	Default	Description
notifyOnComplete	true	Notify when a session finishes (deduped to once per 60 s per session).
notifyOnError	true	Notify when a session hits an error.
notifyOnConfirm	true	Notify when the agent is about to ask you a question.
soundOnComplete	true	Play the completion chime after the completion toast.
soundVolume	70	Chime volume, 0–100.
soundFile	""	Path to a local audio file (wav / mp3 / wma). Empty = the bundled chime; if the custom file is missing it falls back to the bundled chime, then to Windows built-in notify sounds.

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

🔌 How it works

DSH event	Behaviour
agent/status (idle)	Completion toast + chime
agent/request-error	Error toast (passthrough — this plugin never blocks or retries)
tools/pre-execute (ask_user_question)	Confirmation toast

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

File	Role
lib/index.js	Host half — cordis plugin: event hooks + settings route
lib/client.js	Client half — registered via window.__ModuleLoader__, no build step
cordis.patch.yml	Default configuration inserted into the profile

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 is on, toasts may be suppressed — allow notifications for the dsh-helper app id.

📄 License

MIT © sunligh91