@deepseek-ai/dsh-client-audio-alert

English | 中文

Sound alerts for the moments a session needs you: an interrupted turn (approval request), a question, or a finished turn — a reminder to come back without keeping the tab in view. The node half registers the audio-alert settings namespace; the browser half subscribes to the session list and plays a sound on three attention edges: an approval request (pendingInteraction becomes approval or plan-review), an ask-user question (pendingInteraction becomes question), and a finished turn (a session's running bit flips true → false).

Sounds are configurable per trigger through the audio-alert settings namespace (Settings → plugin configuration, or the settings.yaml document). Each field is optional: enabled (default true), volume (default 0.8, in [0, 1]), approvalSound / questionSound / doneSound, and debug (default false). A sound field accepts a data URI, an http(s)/blob URL, a root-relative URL (leading /), or a local filesystem path. An empty field selects the built-in synthesized tone. debug: true logs the resolved config and each play to the browser console and the server log.

A local path (for example C:/sounds/alert.mp3, ~/sounds/alert.mp3, or ./alert.mp3) is read by the node half on the machine running dsh web and served to the browser over /audio-alert/audio/<kind>, so the browser never touches the filesystem itself. Write the path with no data: or file: scheme prefix.

Installation

Prerequisites — a dsh web deployment (DeepSeek Harness; the web profile is created on first use), Node ^22.19 || >=24, and pnpm. The plugin resolves its @deepseek-ai/* peers from the profile's own node_modules, so no extra packages are needed.

Install — dsh plugin forwards its arguments to pnpm inside the profile directory:

# from GitHub (recommended; the build runs automatically on install)
dsh plugin --profile web add https://github.com/ellelkktrraaa/dsh-audio-alert.git

# or from a local checkout
dsh plugin --profile web add C:\path\to\dsh-audio-alert

# remove again (by package name)
dsh plugin --profile web remove @deepseek-ai/dsh-client-audio-alert

Configure — create an audio-alert: section in $DSH_HOME/settings.yaml (default C:\Users\<you>\.dsh\settings.yaml):

audio-alert:
  enabled: true
  volume: 0.8
  approvalSound: "C:/sounds/approval.mp3"   # empty = built-in tone; or a data:/http(s) URL
  questionSound: "C:/sounds/question.mp3"
  doneSound: "C:/sounds/done.mp3"
  debug: true

Then restart dsh web.

Verify — with debug: true, the browser console (F12) shows the resolved config and each alert:

[audio-alert] browser half mounted
[audio-alert] scope changed: {"status":"ready","writable":true,"value":{"enabled":true,"volume":0.8,...}}
[audio-alert] alert kind: approval

Trigger an approval, an ask-user question, or a finished turn and listen for the sound.

Host requirement for custom sounds — the browser reads the audio-alert settings namespace through the host API proxy, which only serves namespaces on an explicit allowlist. On the current DeepSeek Harness checkout this needs 'audio-alert' added to WEB_SETTINGS_NAMESPACES in packages/host/apiproxy/src/api-proxy.ts (a namespace absent there answers settings-not-exposed). Without it the plugin still plays built-in tones at the default volume, but the custom sounds are not read by the browser.

Troubleshooting

• No [audio-alert] lines in the console → the browser is serving a cached client.js; hard-refresh (Ctrl+Shift+R) or open a fresh tab.
• Scope stuck at "unavailable" → the host does not expose the audio-alert namespace (see the host requirement above).
• Built-in tone plays but not the configured file → the path must exist and be readable on the machine running dsh web; the server log (debug: true) prints [audio-alert] serving approval from ... or the failure reason.
• First sound is silent → the browser autoplay policy blocks playback until the page has had a user gesture; click anywhere once.

Compatibility Evidence

Following the dsh-plugin-radar evidence ladder, this repository carries evidence at every level:

Level	Check	Status
L0 discovery	topic, visibility, metadata	dsh-plugin topic set; repository public; keywords / homepage / repository present in package.json
L1 manifest	package.json, name, entry fields	@deepseek-ai/dsh-client-audio-alert; main → lib/index.js, exports["./client"] → lib/client.js
L2 static compat	patches, seams, dependency ranges	Seams: the audio-alert settings namespace (installSettingsSection), the /audio-alert/audio web-server route, and the browser sessions.list / settingsScope services. Peer dependencies are pinned to the 0.1.0-rc.x dsh family
L3 compile experiment	type/syntax check in a workspace	pnpm typecheck (tsc -b) and pnpm build (tsc -b && tsdown) pass on Node 22/24
L4 runtime test	install, load, minimal task	Install via dsh plugin add (see the tutorial above); 37 unit tests pass; with debug: true the browser console logs [audio-alert] scope changed: {"status":"ready",...} and each alert kind

Known boundaries — the radar's own caveats apply here too: mainline and plugins change fast, so conclusions age quickly; a static pass does not guarantee runtime success; a compile failure can come from the environment or missing dependencies rather than real API drift; and the runtime checks above only cover the minimal path described here.

Model Experience

None, as the plugin only plays a browser sound on live session-list attention edges; nothing here reaches a model request.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

• Done fires on the running edge — a turn ending for any reason (completed, error, aborted) announces once; the sound does not distinguish the reason.
• Autoplay policy — the first sound can be suppressed until the browser has registered a user gesture on the page; playback rejection is contained, never retried.
• First observation is silent — sessions already pending or idle at load do not replay their attention, matching the session list's own reminder semantics.
• Local files are read on the server — the node half reads the file on the machine running dsh web, whole into memory, per request; a path is not portable to another machine.
• Leading-slash paths are URLs — a /-prefixed value is a root-relative URL, never a local file, so a POSIX absolute path must be written ~-relative or cwd-relative instead.