In DSH Web client development, clearly indicating the end of an Agent turn is a common requirement. dsh-web-ding is a plugin that synthesizes and plays a sound in the browser, addressing the problem of not knowing when an Agent is truly idle.

Plugin Purpose

This is a browser-only “ding” sound notification plugin. It consists of two parts: a Host-side listener detects the idle state in agent/status and pushes a signal to the falling-ts-web-ding settings namespace; the browser-side client mirrors that namespace, synthesizes the notification sound via the Web Audio API, and displays a notification.

Installation and Prerequisites

Run the following command to add the plugin to the Web Profile:

dsh plugin --profile web add github:falling-ts/dsh-web-ding

Before installing, ensure the Web app includes a client package (the dsh.client declaration in package.json).

Core Features

  1. Synthesized beep: Uses the Web Audio API to synthesize a “ding” sound in the front end (three sine oscillators plus an exponential decay envelope). The Host does not play audio or invoke system notifications.
  2. Host-side listening: Watches for Agent/Status idle transitions (all turns ended, including sub-Agents). Only a new idle transition triggers the signal; repeated idle states remain silent.
  3. Browser-side client: Mirrors the settings namespace and responds to user configuration in real time. Supports Win11-style Toast notifications in the bottom-right corner.
  4. Notification drawer: Clicking a Toast opens a notification drawer that lists turn-end messages. Messages are stored in localStorage, up to 100 messages are retained, and you can delete a single message or clear all.

Configuration

Configuration items are stored in the falling-ts-web-ding namespace and can be adjusted in the Settings → Beep Configuration panel. The plugin contains two independent configuration blocks:

Block 1 — User Selection Popup

It triggers when a [data-question-key] element appears in the browser; detection is purely a front-end operation. Adjustable parameters:
* questionEnabled: Toggle.
* questionVolume: Volume (0..1).
* questionFreq: Frequency (80..4000 Hz).
* questionDecayMs: Decay duration (100..4000 ms).

Block 2 — Turn End

Watches for Agent idle transitions. The Host publishes a done signal when it detects an agent/status idle change. Adjustable parameters:
* turnEndEnabled: Toggle.
* turnEndVolume: Volume (0..1).
* turnEndFreq: Frequency (80..4000 Hz).
* turnEndDecayMs: Decay duration (100..4000 ms).

Notes

  1. Browser autoplay policy: Browsers block audio playback until the user interacts with the page (click, keypress). Before first use, click once on the page or use the “Preview” button to warm up the AudioContext.
  2. Background tabs: Browsers may suspend the AudioContext in background tabs. Keep the tab visible to hear the sound.
  3. Data isolation: The message log is stored entirely in the browser’s localStorage. The Host does not read or write this data.

Source Code and Documentation

The plugin depends on the settings/document-updated mirror channel to communicate with the browser side. Source code and repository page: https://github.com/falling-ts/dsh-web-ding