dsh-turn-chime

dsh-turn-chime

English | 简体中文

Plays a chime when a conversation task actually finishes. The decision is made on the host side, the sound is emitted in the client, and the tone is synthesized on the fly with Web Audio — no audio files involved.

What it solves

DeepSeek Harness's api-session/status only tells you whether the agent is busy right now. Using it directly as a completion signal runs into two problems:

• It can't tell "finished" from "interrupted". When the user hits stop, a run exits with an error, or a hook blocks it, the status flips back to idle all the same.
• A single task can consist of multiple drivers. Subagents feeding results back, goal rounds continuing the run — every driver that stops flips idle once, so one stretch of work chimes several times.

This plugin moves the decision to the host side, so it chimes exactly once, and only when a user-initiated task finishes normally.

Install

Put the repository in any directory, then:

node install.mjs                  # install into %DSH_HOME%\profiles\desktop
node install.mjs web              # install into the named profile (multiple allowed)
node install.mjs X:\path\to\profile

The script does three things: writes a file: dependency into the profile's package.json, adds the plugin name to dsh.profile.bundles, and creates a junction under node_modules/<plugin> pointing at this repository (so source edits take effect immediately, with no copy to re-sync).

DSH must be restarted after installing — the client module manifest is generated at startup, so the plugin won't load without a restart.

To uninstall: remove that line from dsh.profile.bundles, then delete node_modules/dsh-turn-chime.

Usage

Settings → Chime:

The configuration is stored in the browser's localStorage (dsh-turn-chime:config:v1).

When it fires

All three conditions must hold:

1. session/event's user/message, with source.kind === "user" — the user really sent a message (time-context injection, subagent feedback, and hook injection don't count);
2. session/event's turn/end, with reason.kind === "completed" — finished normally. Interrupted (aborted), errored (error), blocked by a hook (blocked), and hitting max-tokens all stay silent;
3. agent/status flipping to idle — one driver has come to a full stop.

One user message chimes once: the pending flag is consumed on the first ring, so automatic continuation of the same task doesn't ring again.

The verdict is pushed to the client over SSE at /dsh-turn-chime/events.

Troubleshooting

Host-side diagnostic log:

%DSH_HOME%\logs\dsh-turn-chime.log

A normal wrap-up looks like this:

client-ready {"hasSessions":false,"audio":true,"sse":true,...}
sse-open
chime        {"sessionId":"...","clients":1}
play         {"sessionId":"...","voice":"chime","ok":true,"count":1}

Three routes from the same source:

• GET /dsh-turn-chime/events — SSE completion event stream
• GET /dsh-turn-chime/log — reads back the last 120 lines
• POST /dsh-turn-chime/clear — clears the log

Debug entry points in the browser console:

__dshTurnChime.play('chime', 0.6)  // preview manually
__dshTurnChime.status()            // { connected, chimes, config }
__dshTurnChime.onChime('x')        // simulate a completion event → should chime once

Why it's split this way

Sound can only come from the renderer process. Playing audio in the host means either spawning a PowerShell/player process (hundreds of milliseconds of cold start, plus process reaping to manage), or using Electron's shell.beep() (no choice of tone). Web Audio is zero-dependency, zero-latency, cross-platform, and can synthesize tones on the fly.

The decision can only live in the host. The api-session/status the client receives is a boolean, so it can't show whether this turn ended normally or someone pressed stop; the turn/end reason and the user/message source exist only on the host event bus.

Files

Tests

node test/test-logic.mjs   # or npm test

Covers six scenarios: normal finish → chime; user interrupt → silent; time-context injection only → silent; one message with two drivers → chime once; error → silent; interrupt followed by a new message that finishes → chime.

Known limitations

• The chime only plays in the browser renderer process, so there is no sound while DSH is fully closed.
• The decision depends on DSH internal events (session/event, agent/status). If their shape changes in a major DSH upgrade, lib/index.js needs a matching update.
• It only chimes on reason.kind === "completed"; a turn that errors out is silent. To make errors ring as well (with a different sound), change CHIME_REASON in lib/index.js.

License

MIT