dsh-work-done-bell
English | 简体中文
A DeepSeek Harness plugin that
rings a Windows system sound when a session has actually finished, and
shows a bottom-right toast naming the session that finished. A persistent
bottom-right switch turns both off, and that preference is stored in a real
settings namespace, so it survives a restart.
Why "idle" is not "done"
agent/status -> idle means only that the agent's driver has nothing scheduled.
Work routinely outlives it:
- a
run_in_background job keeps running and its settlement opens another
turn, and
- a delegated subagent keeps running while its parent sits idle.
Chiming on raw idle therefore rings two or three times per task. This plugin
waits for quiescence: idle and no running/stopping job owned by the
session and no running agent owned by it. A 90-second deadline bounds that
wait, so a long build cannot swallow the notification; once the deadline has
rung, the later true quiescence stays silent for the same episode.
What it sounds like
The reason comes from the durable session log (turn/end), not from a guess:
turn/end reason | Sound | Toast |
|---|
completed | Asterisk (default notification) | yes |
blocked (a plugin rejected the step) | Asterisk | yes |
max-tokens (output ceiling hit) | Asterisk | yes |
error | Hand (critical stop) | yes |
aborted — including your own Esc/Stop | silent | no |
interrupted (crash-orphaned turn) | silent | no |
Simultaneous completions within 2.5 s collapse into one sound, so five sessions
finishing together do not stack five players.
Install
Clone the repository, then install it from the directory you cloned into:
git clone https://github.com/FunctionHookTJU/dsh-work-done-bell
dsh plugin --profile web add file:/absolute/path/to/dsh-work-done-bell
then add the package name to the profile's bundle list, in
<DSH_HOME>/profiles/web/package.json:
{
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "...", "dsh-work-done-bell"]
}
}
}
(dsh plugin add reconciles that list itself when the installed package
declares dsh.bundle. Restart DSH afterwards; nothing else in the composition
needs editing.)
Use file:, not link:. The plugin resolves
@deepseek-ai/schemastery by walking up from its own directory into the
profile's node_modules. A link: install keeps the real path outside the
profile and the import fails at load.
Uninstall
dsh plugin --profile web remove dsh-work-done-bell
Remove it from dsh.profile.bundles (which dsh plugin remove also reconciles),
then restart. The work-done-bell namespace in settings.yaml is inert once
the plugin is gone and can be deleted by hand.
The switch
Bottom-right, always visible: 完成提示已开 / 完成提示已关. It writes
work-done-bell.enabled through the settings service, and both halves read it —
the host half stops the sound, the browser half stops the toast. The state lives
in <DSH_HOME>/settings.yaml, so it survives a restart.
Introspection
There is no model-facing tool, on purpose: @deepseek-ai/dsh-tools is not
present in the profile, and a plugin may only import what the profile already
carries (ESM resolution ignores NODE_PATH). The state route carries the same
information instead:
curl "http://127.0.0.1:3080/dsh-work-done-bell/state?verbose=1"
That returns tracked statuses, the last turn/end reason per session, open
quiescence episodes with their deadlines, the last sound exit code, and any
error the plugin swallowed. Without ?verbose=1 it returns only what the
browser half needs.
Requirements and known limits
- Windows only for the sound: it plays through
[System.Media.SystemSounds], executed via the composed shell service. On
other platforms the plugin loads and toasts, but stays silent. Porting it
means changing the command in play() to afplay / paplay.
- The sound command carries a resolved sandbox policy. A confining shell
service refuses a command that arrives without one, and the deployment
default may be a mode the host cannot enforce at all — on the machine this
was built on,
workspace-write fails because the Windows ACL runner wants a
temp root outside the workspace while the workspace is the user profile, so
nothing runs confined and an unpolicied command is simply refused. The
policy is therefore resolved per chime for the session being announced
(sandboxPolicy.resolve({ session })), which is that session's own
authority, never a widening of it. On such a host a session confined to
workspace-write stays silent; ?verbose=1 reports the reason in
lastError and the resolved mode in lastPolicy.
- The toast requires an open page; the sound does not.
- The browser half polls the host every second over
/dsh-work-done-bell/state. There is no push channel: the sanctioned
direction of package communication is browser -> host.
- Toasts label the session by a short id, not its title.
Development
Four suites, all runnable with no harness running:
npm test # all four
node test/state-machine.test.mjs # the decision table, on a manual clock
node test/integration.test.mjs # the plugin inside a REAL cordis app
node test/client-bundle.test.mjs # the browser bundle's contract
node test/docs-parity.test.mjs # the two readmes' shared skeleton
integration.test.mjs is the one that matters most: it boots a real
@deepseek-ai/cordis application with stub services and asserts that apply
runs, that ctx.inject fires, and that both HTTP routes register. An earlier
version of this plugin read ctx.get('webServer') once at apply time and
called jobs.onJobsChanged unguarded; it looked healthy while registering
nothing in production, because a host-composition row mounts during boot,
before its services exist.
The suites need @deepseek-ai/cordis, @deepseek-ai/cordis-plugin-timer,
@deepseek-ai/schemastery and @deepseek-ai/cosmokit resolvable from the
repository. A checkout links them from the harness installation; node_modules
is gitignored, so these links stay local:
$repo = (Get-Location).Path # this checkout
$dsh = "$env:APPDATA\npm\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai"
$web = "$env:USERPROFILE\.dsh\profiles\web\node_modules\@deepseek-ai"
New-Item -ItemType Directory -Force -Path "$repo\node_modules\@deepseek-ai" | Out-Null
foreach ($p in 'cordis','cordis-plugin-timer') {
New-Item -ItemType Junction -Path "$repo\node_modules\@deepseek-ai\$p" -Target "$dsh\$p"
}
foreach ($p in 'schemastery','cosmokit') {
New-Item -ItemType Junction -Path "$repo\node_modules\@deepseek-ai\$p" -Target "$web\$p"
}
docs-parity.test.mjs guards the two readmes against drift: the same heading
skeleton, the same code blocks, the same tables, the same inline technical
terms. It cannot judge the prose, but it fails the moment one language grows a
section the other lacks.
Layout
lib/index.js host half — quiescence state machine, sound, HTTP route
client/client.js client half — shell.overlay toast stack and switch
cordis.patch.yml the composition row this package contributes
test/ decision table, real-cordis integration, client + readme contracts
License
MIT
