dsh-turn-notify · AI Agent Hub Blog

DSH Notification Plugin: Send Windows system notifications whenever the Agent needs your intervention.

During an Agent run, developers often need to leave their screens to handle other tasks. At such times, it can be difficult to know immediately when the Agent has finished a task, encountered a block, or is waiting for human approval. dsh-turn-notify notifies developers when the Agent requires human action by using Windows Toast notifications and system sounds.

Features¶

Triggering points
The plugin covers key states during Agent execution, including:
* Turn completed
* Goal blocked / paused
* Conversation interrupted / aborted
* Turn error
* Output limit reached
* Session interrupted (crash recovery)
* Awaiting approval
* Awaiting an answer (Agent initiated question)
* Plan pending review
* Run error (step-level error)

Notification style and behavior
* Notification type: Supports Windows Toast long banner and specific templates.
* Content preview: Displays session number and Q&A content preview (default truncated to 15 characters).
* Sound: Plays Windows Background.wav by default, synchronized with the popup.
* Subagent silence: Notifies only the root session; notifications generated by subagents are filtered.
* Storm prevention: Similar key events in the same session are merged into one notification within 1.5 seconds to avoid duplicate popups.
* Multi-session isolation: Distinguished by session.id, without interfering with each other.
* Bilingual support: Supports Chinese and English.

Fallback behavior
* Prefers the C#-compiled dsh-notify.exe.
* Automatically falls back to the notify.ps1 script when it is missing.
* Falls back to logging when notification delivery fails.

Installation and Enabling¶

Install the plugin using the official command. After installation, enable notifications for the corresponding events in the configuration file.

1. Install the plugin

dsh plugin --profile web add github:Ruiming-cn/dsh-turn-notify

2. Configuration patch
Add config settings to the turn-notify entry in ~/.dsh/profiles/web/cordis.patch.yml. The following configuration items are optional; the plugin code already has internal default values:

    - id: turn-notify
      config:
        language: zh            # zh | en
        sound: true
        notify:
          completed: true
          blocked: true
          aborted: true
          error: true
          maxTokens: true
          interrupted: true
          goals: true
          approvals: true
          questions: true
          planReview: true
          agentError: true
        cooldownMs: 10000
        mergeWindowMs: 1500
        previewChars: 15
        titlePrefix: DSH
        showSessionTag: true
        timeoutMs: 10000
        dryRun: false
        rootSessionsOnly: true

3. Restart DSH
After modifying plugin code, you must restart the DSH GUI for changes to take effect.

Building the Native Notifier¶

The plugin repository does not include the dsh-notify.exe binary; you need to compile it yourself.

1. Prepare the environment
Ensure the system has csc.exe for .NET Framework 4.8 (usually located at C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe) and Windows.winmd from the Windows SDK.

2. Compile
In the plugin/ directory, run the following command to compile the C# source code:

$winmd = "C:\Program Files (x86)\Windows Kits\10\UnionMetadata\10.0.26100.0\Windows.winmd"
$sysruntime = "C:\Windows\Microsoft.NET\assembly\GAC_MSIL\System.Runtime\v4.0_4.0.0.0__b03f5f7f11d50a3a\System.Runtime.dll"
& "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe" /nologo /nostdlib /target:exe /out:"dsh-notify.exe" /r:mscorlib.dll /r:System.dll /r:System.Core.dll /r:"$sysruntime" /r:System.Windows.Forms.dll /r:System.Drawing.dll /r:System.Runtime.WindowsRuntime.dll /r:"$winmd" "dsh-notify.cs"

After compilation, copy the entire plugin/ directory to the global DSH directory and restart the GUI to use the native notifier.

Notes¶

System requirements: Supports Windows 10/11 only.
Restart required: After modifying plugin code (JS or C#), you must restart the DSH GUI to load the new code.
Security software: The PowerShell fallback script may be blocked by security software; it is recommended that you build dsh-notify.exe yourself.
Notification characteristics: Notifications are system-level UI and are independent of DSH window focus; if the system’s “Focus Assist” is enabled, it may prevent notifications from appearing.

Features¶

Installation and Enabling¶

Building the Native Notifier¶

Notes¶

Tags