Preface

The DeepSeek Harness (DSH) plugin ecosystem allows extending interaction capabilities in the browser. When developing agents or tools, the Agent may be running in the background, or the user may not be on the current page, and visual feedback is often overlooked. The dsh-sonic plugin synthesizes sound effects in real time in the browser, filling the gap in auditory feedback, and is used to play prompt tones when the Agent needs user confirmation (such as an approval request or waiting for an answer) or when a task is completed (the Agent status becomes idle).

Plugin Overview

dsh-sonic is a client-side plugin maintained by xjwwjx. It uses the Web Audio API to synthesize 8 sound effects in real time, without loading any external audio files. The plugin is intended to provide clear, immediate auditory feedback and help users perceive changes in the Agent’s status.

Core Features

Sound Triggering

  • Confirmation tone: Triggered on approval requests (sandbox privilege escalation, plugin execution authorization) and when ask_user_question is waiting for the user to answer.
  • Completion tone: Triggered when the Agent status changes from running to idle.

8 Real-Time Synthesized Sound Effects

All sound effects are synthesized in real time in the browser and support the following types:
- ding: single clear tone
- dingdong: doorbell two-tone
- pop: light bubble pop
- chime: soft three-note arpeggio
- success: rising arpeggio
- beep: short electronic beep
- alarm: reminder two-tone
- marimba: marimba strike

Settings Panel

In DeepSeek Harness Web: Settings → General, you can configure the following options:
- One-click mute
- Volume slider
- Select the confirmation tone and completion tone separately
- Click to preview
- Automatically save the configuration and sync it to the model

Model Tools

The plugin provides two tools to the model:
- sonic_play: Immediately play the specified sound effect (for testing or demonstration).
- sonic_status: Read the current selection state in the panel.

Installation and Enabling

dsh-sonic is installed as a bundle plugin, similar to @liustack/modlens, and is automatically loaded with the Web profile.

  1. Link this package into the profile. Edit ~/.dsh/profiles/web/package.json:
    - Add to dependencies: "dsh-sonic": "file:<path-to-this-package>"
    - Add to the dsh.profile.bundles list: "dsh-sonic"
  2. Run the install command in the profile directory: pnpm install
  3. Restart DeepSeek Harness Web — the plugin is loaded with the bundle and remains active after the process restarts.

How It Works

The plugin uses a separated Host and Browser architecture:

  • Host side: Listens for events such as approval/request, ask_user_question, and agent/status, and places notifications into a queue. It provides the POST /sonic/state endpoint to receive settings and the GET /sonic/drain endpoint for the browser to pull the queue of pending sounds.
  • Browser side: Polls /sonic/drain every 1 second and plays the corresponding sound based on the returned data. It also maintains the settings panel and receives user configuration via settings.general.item.

Custom Sounds

The sound effect configuration is located in the PRESETS constant in dsh/client.js. Each sound effect is a set of note parameters, supporting frequency (freq/endFreq), duration (at/dur), waveform (type), and volume (gain/attack).
To add a new sound effect, add an entry to PRESETS and append the corresponding key to the enumeration in the Host-side sonic_play tool.

Notes

  • Installation method: This article describes how to install a static bundle plugin. The dynamic version (loaded within a session via cordis_define) is located in examples/dynamic-host.js and examples/dynamic-client.js, for reference only, and will be lost after a process restart.
  • Permissions and paths: Static installation requires configuring the profile’s package.json and dsh.profile.bundles; ensure that the local file path is configured correctly.