agents-plugins#task-complete-notify-for-dsh

task-complete-notify-for-dsh

DSH (DeepSeek Harness) plugin: desktop notification + chime when a run finishes — completion, errors, and approval requests — with a configurable duration threshold.

The essence: a custom chime that works on all three OSes. Replace

lib/assets/prompt-tone.mp3 with any audio you like and the sound changes

everywhere — Windows, macOS, Linux — not just Linux.

Cross-platform

Runs on Windows, macOS and Linux from the same package — no code changes. Notification and the custom chime work on each OS (see Platform support).

Features

Why this is a safer install than curl | bash plugins

This package ships pre-built lib/ with no prepare/postinstall/install build script — dsh plugin add has nothing to execute beyond loading the published JS. Build-time code only runs on the author's machine at publish (prepublishOnly), never on your machine at install. This avoids the "install runs a remote build script" supply-chain concern.

Install

Source: github.com/lxp731/agents-plugins/tree/main/task-complete-notify-for-dsh

From npm (recommended):

dsh plugin --profile web add task-complete-notify-for-dsh

From the GitHub monorepo (alternative): the plugin lives in the agents-plugins monorepo, so point dsh at the subdirectory with #path::

dsh plugin --profile web add github:lxp731/agents-plugins#path:/task-complete-notify-for-dsh

Then restart dsh web. Or via the dsh-market panel: Settings → Plugin Market.

How it works

• One notification per run, not per turn. A run can span many turns; the plugin records the latest turn/end reason and fires once when the root agent returns to agent/status 'idle' (the harness's own "run ended" signal).
• Errors and token limits carry the final turn/end reason, so a run that errors gets a critical "任务失败" with the true final result.
• Approval / question fire an immediate critical notification, because each is a separate "the session is waiting on you" moment.
• Subagent sessions are excluded (header.origin === 'subagent') so a top-level run produces one notification.

Configuration

Declare the row in ~/.dsh/profiles/web/cordis.patch.yml (the user layer, applied last):

- id: task-complete-notify
  name: task-complete-notify-for-dsh
  config:
    enabled: true             # master switch
    threshold: 0              # min run duration (s) before notifying; 0 = always
    title: DeepSeek Harness   # notification title
    sound: true               # play a chime
    onQuestion: true          # notify when the model asks a question
    onApproval: true          # notify when the harness waits for approval
    chimeFile: ''             # absolute path to a custom mp3; empty = bundled default
    lang: zh                  # message language: 'zh' (default) or 'en'
    blockedCooldownSec: 60    # min seconds between question/approval notifications per session
    toolCooldownSec: 10       # min seconds between model-invoked notify tool calls

Runtime threshold (/notify-threshold) — persists

/notify-threshold <秒> sets the threshold and persists it to the user layer (cordis.patch.yml), so it survives a restart — no need to edit the file by hand. With no argument it prints the current value. Example: /notify-threshold 30 notifies only on runs longer than 30s.

Custom chime (chimeFile)

Point chimeFile at your own audio file to override the bundled prompt:

- id: task-complete-notify
  name: task-complete-notify-for-dsh
  config:
    chimeFile: /usr/local/music/xx.mp3

Any mp3 works; the file is played on all platforms (see Platform support). If chimeFile is configured but the file is missing, the plugin logs a warning at startup and falls back to the default.

Model-callable notify tool

The model can explicitly notify the user for important events:

notify(message: "Data export complete: 100,000 records", status: "success")
notify(message: "Build failed: TypeScript compilation error", status: "failure")

Breaking change in v0.2.0: status values changed from `"完成"/"失败"

to "success"/"failure". Update any prompts that pass Chinese values.

Calls are rate-limited (toolCooldownSec, default 10s); suppressed calls return { ok: false, throttled: true }.

Platform support

On Linux, the display session (DISPLAY/WAYLAND_DISPLAY) is discovered from the actual session sockets instead of hardcoded defaults, so notifications work under systemd user services too.

The custom chime works on every platform. The plugin's core idea is a replaceable audio file (lib/assets/prompt-tone.mp3) — swap the file to change the sound. On all three OSes it first auto-detects an available player and plays the mp3; only when no player exists does it fall back to the platform system sound (macOS Glass / Windows SystemSounds).

• macOS: afplay ships with the OS and plays mp3 natively, so the custom

chime works with zero install.

• Windows: has no built-in mp3 player (PowerShell's SoundPlayer only

plays .wav), so install any one of mpv / ffplay / mplayer / mpg123 / cvlc to enable the custom chime.

To change the sound without touching config, replace lib/assets/prompt-tone.mp3 (any mp3 works). To keep your own file elsewhere, use the chimeFile config.

Notifications are fire-and-forget (detached, unref'd) — a missing notifier never breaks the run it reports on. Every failure is logged via the plugin logger, so a silent no-op is diagnosable from dsh logs.

Reliability

• Self-check: warns once if no harness events arrive within 5 minutes of an active session — an early signal that a dsh update changed its event API.
• Profile safety: if the active profile cannot be determined, persistence falls back to 'web' and logs a warning.
• Config persistence preserves comments: edits go through a YAML AST, so your annotations in cordis.patch.yml survive /notify-threshold; writes are atomic (temp file + rename) with a best-effort lockfile.
• Bounded memory: per-session tracking state is capped and consumed at idle.

See CHANGELOG.md for the full history.

Development

npm install           # resolves schemastery + peers via package-lock.json
npm test              # node --test tests/*.test.mjs
npm run lint          # eslint lib tests

If peer deps aren't resolvable from a fresh clone, bash scripts/smoke.sh links them from a dsh install's node_modules automatically.

Install locally for testing (from a clone of the agents-plugins monorepo):

git clone [email protected]:lxp731/agents-plugins.git
cd agents-plugins/task-complete-notify-for-dsh
dsh plugin --profile web add link:.

Note for systemd-managed setups (dsh-service-control): after any change

to lib/, reload the plugin by restarting the service, e.g.

systemctl --user restart dsh-web.service.

Development notes (read before extending)

• Cordis services must be injected. ctx.tools and ctx.commands are

not directly readable — accessing them without declaration throws cannot get property "tools" without inject and fails the whole plugin tree at boot. Always use ctx.inject(['tools'], (sctx) => …) / ctx.inject(['commands'], …) and register inside sctx.effect(...).

• The harness's typed session/event / agent/status declarations live in the

unpublished @deepseek-ai/dsh-session / dsh-agent packages, so event listeners register with a narrowed cast; payload shapes are pinned in lib/notifier.js.

• Config persistence uses the yaml package to read/merge/write the

plugin's row in the profile user layer (cordis.patch.yml, via lib/persist.js). DSH_HOME already points at the .dsh data dir (default ~/.dsh); the resolver must NOT append .dsh again when DSH_HOME is set.

• Profile resolution is robust: resolveProfile() picks the active profile

from, in order, an explicit argument, the DSH_PROFILE env var, --profile in argv, then a 'web' fallback. Never rely on argv alone.

• writeConfig is crash-safe: it refuses to clobber a cordis.patch.yml

that isn't a valid top-level YAML array, and never overwrites an unparseable file with an empty one (that would wipe a real user config).

• The notify tool is built with defineTool() from @deepseek-ai/dsh-tools

(a harness peer). defineTool requires required: true on mandatory parameters; omit required entirely for optional ones (a bare required: false is rejected).

License

MIT