dsh-task-sounds

Readme

# dsh-task-sounds

Task-complete & question notification sounds for the DeepSeek Harness Web UI.
A small chime plays when the agent **finishes a turn**, and a different
"ding-dong" plays when the agent **asks you a question** mid-task (questions,
plan reviews, and approval prompts all pause the agent waiting for your input).

No assets, no network, no host process: chimes are synthesized in the browser
with the Web Audio API, so the plugin is tiny and works offline. A mute toggle
sits in the session header (🔔 / 🔕) and the choice survives reloads.

![toggle](https://img.shields.io/badge/plugin-dsh_task_sounds-4c1)

## Install

```sh
dsh plugin --profile web add dsh-task-sounds
```

Restart `dsh web`, then start a task or let the agent run: you'll hear

- **done** — two ascending notes (E5 → B5) when a turn completes;
- **question** — a descending ding-dong (A5 → D5) when the agent asks you
  something and waits for your answer.

Click the 🔔 in the session header to mute; click again to unmute.

## How it works

A pure-client Cordis plugin (browser half only). It registers one small entry
in the session header utilities slot (`conversation.session.header.utilities`)
and watches the conversation snapshot the framework provides through the
standard session kit:

- `snapshot.turnEnds` — a new completed turn whose end time is recent triggers
  the **done** chime (history replay is seeded as seen on mount, so reloading
  or paging older messages never chimes);
- `snapshot.pending` — a new pending interaction (`question` / `plan-review` /
  `approval`) triggers the **question** chime.

Both signals are per-session and deduplicated, so each event chimes exactly
once. Audio is unlocked on the first pointer/key interaction to satisfy
browser autoplay policies, and the mute state lives in `localStorage`.

## Submit to the plugin store

The DSH plugin market ([dshmarket](https://github.com/dsh-market/dsh-market)) reads
its catalog from the curated
[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
registry. To list this plugin there:

1. **Push this repo to GitHub** (any public repo). Add the `dsh-plugin` topic
   to the repo. Note the registry's CI requirements: the repo must be
   **at least 1 day old** and have **10 or more commits** before the PR — so
   create and push the repo first, then submit the PR later.
2. **Publish to npm** (`npm publish` from this directory — the package is
   publish-ready; `npm run prepack` runs as a health check). The market
   registry-verifies the npm package against the repo, so publish **before**
   the PR.
3. **Open a PR** against `awesome-dsh-plugin/awesome-dsh-plugin` adding one
   file `data/plugins/henrytang2011win-coder__dsh-task-sounds.yml` — the exact
   content is in
   [`awesome-dsh-plugin-entry.yml`](./awesome-dsh-plugin-entry.yml), already
   filled in. Then, inside your clone of that repo, regenerate both READMEs
   and commit them together:

   ```sh
   npm ci
   node scripts/generate-readme.mjs
   ```

   The `dsh.bundle` manifest this package declares is exactly what the
   registry checks for installability.

The site and every market instance pick the entry up automatically (usually
within a day), after which anyone can install with:

```sh
dsh plugin --profile web add dsh-task-sounds
```

## Development

```
npm install          # no runtime deps — peer react only
npm run prepack      # health check used before publishing
```

The client half is plain JavaScript — no bundler needed. The module loader
resolves `require("react")` from the platform seed words, and the host half
(`lib/index.js`) is intentionally an empty `apply`.

## License

MIT