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

Readme

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

English | [中文](README.zh.md)

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:

```bash
# 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`):

```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](https://github.com/AdamPlatin123/awesome-dsh-plugins#本仓库如何判定), 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.