dsh-plugin-mac-notify

macOS Notification Center alerts for DSH (DeepSeek Harness) sessions — so an unattended run can call you back to the machine.

┌──────────────────────────────────────────────┐
│ DSH · 任务完成                                │
│ browser_dsh                                  │
│ 插件已经写好并装好了，自检 57 项全过。        │
└──────────────────────────────────────────────┘
        ↑ click → the browser tab already showing DSH comes to the front

Host-only bundle: it subscribes to Host events and shells out to a notifier. There is no browser half, so nothing renders in the page and no page refresh is involved.

What it notifies

Host event	When	Banner
agent/status → idle	the turn ended (a running → idle transition)	DSH · 任务完成, body = the last assistant text
user-questions/request	the agent called ask_user_question and is blocked	DSH · 需要你的回答, body = header · question · options
approval/request	the agent is waiting on an approval decision	DSH · 需要你的批准, body = the reason or the tool name
agent/error	a step or turn errored	DSH · 执行出错; the closing banner then reads 任务结束（有报错）

Subagent children stay silent (includeSubagents: false by default), identical banners inside 5 s collapse into one, and consecutive non-urgent banners respect a pacing gap — while a question or approval always gets through.

Requirements

• macOS. On any other platform the plugin activates, logs a debug line, and sends nothing.
• Optional, for click-to-open: terminal-notifier (brew install terminal-notifier). Without it the plugin falls back to the osascript banner every macOS ships — same text, same sound, no click action.

On recent macOS an ad-hoc signed notifier is refused until you allow it once: System Settings → Notifications → terminal-notifier → Allow Notifications (style Banners, Play notification sound on). Until then terminal-notifier -diagnose reports authorization: not requested yet and sending returns Notifications are not allowed for this application.

Install

dsh plugin --profile web add /path/to/dsh-plugin-mac-notify   # local directory
dsh plugin --profile web add github:<owner>/dsh-plugin-mac-notify

The package declares dsh.bundle.patch, so the profile records it in dsh.profile.bundles, the layer applies on the next reconcile, and the plugin appears in the GUI's Plugins page with an enable switch and an uninstall action. No dependencies, no install scripts, no build step.

Upgrading needs a restart

DSH caches host-side module code for the life of the process: replacing the package, re-installing it, or toggling the row off and on re-runs the previous generation. Restart dsh web (or dsh tui) after an upgrade. Browser halves are the opposite — those need only a page refresh.

DSH has no plugin auto-update: upgrading means dsh plugin remove followed by dsh plugin add.

Configuration

The bundle row carries no config, so the defaults apply. Override them in the profile's own cordis.patch.yml (applied after every bundle layer):

- id: mac-notify
  name: 'dsh-plugin-mac-notify'
  config:
    sound: Ping
    notifyOnApproval: false
    url: 'http://127.0.0.1:3080'

Key	Default	Meaning
enabled	true	master switch
notifyOnFinish	true	turn finished
notifyOnQuestion	true	waiting for an answer
notifyOnApproval	true	waiting for a decision
notifyOnError	true	a step or turn errored
includeSubagents	false	also notify for subagent children
sound	'default'	'default' = your system alert sound (read from com.apple.sound.beep.sound); a name from /System/Library/Sounds (Ping, Glass, Hero, …); 'off' = silent
onClick	'focus'	'focus' = surface the existing DSH tab, else open the URL; 'open' = always open; 'none' = no click action
notifier	'auto'	'auto' prefers terminal-notifier, 'osascript' forces the built-in banner
url	''	click target; empty means auto-detect (see below)
language	'auto'	'auto' follows LANG/system locale, or pin 'zh' / 'en'
titlePrefix	'DSH'	banner title prefix
minIntervalMs	1500	pacing gap between non-urgent banners
bodyMaxChars	200	banner body budget

How the click target is resolved

url, else the port this Host actually serves the Web UI on (ctx.get('webServer').port), else DSH_WEB_URL from the environment — so a non-default port needs no configuration.

A click runs lib/click.mjs, which asks every running browser (Chrome, Edge, Brave, Vivaldi, Chromium, Safari — found with pgrep, so no browser is launched just to answer) whether one of its windows holds a tab whose URL starts with that target. The first match becomes the active tab and its window is raised. Only when no running browser has it does the helper fall back to /usr/bin/open <url>.

Reading another app's tabs needs macOS Automation permission, which the system grants per browser on first use (click Allow on the “terminal-notifier wants to control …” prompt). A denial is not fatal: the helper falls through to open, so you land on the DSH page in a new tab instead of the existing one.

Troubleshooting

Both switches are environment variables read at delivery time — set them on the process that launches DSH:

DSH_MAC_NOTIFY_DRY_RUN=1 dsh web     # decide everything, spawn nothing
DSH_MAC_NOTIFY_LOG=/tmp/dsh-notify.jsonl dsh web

The JSONL trace records one line per deliver, skip (with reason: disabled / duplicate / paced), failure, and sound-failed, including the resolved backend and click mode.

• No banner at all → check DSH_MAC_NOTIFY_LOG; on macOS also terminal-notifier -diagnose.
• Banner but no sound → the plugin puts your system alert sound on the banner, so the usual causes are the system output volume, or Play notification sound being off for the notifier in System Settings.
• Click does nothing → the click action only exists on the terminal-notifier backend; osascript banners have none. Check echo $DSH_MAC_NOTIFY_LOG for click: "focus" vs "none".
• Click opens a new tab → Automation permission for that browser was denied, or no running browser has the page (the helper then calls open).

Self-test

node selftest.mjs      # 57 assertions, no notification, no sound, no browser

The suite drives the same lib/index.js the Harness loads, with exec, exists and the clock stubbed: it covers the packaging contract (manifest, patch, locale, icon, the zero-dependency compatibility rule), the pure functions (config normalisation, copy, argv builders, parsers), the registration contract (which events apply subscribes), and event-driven behaviour (what each Host event actually sends, pacing, dedupe, subagent filtering, sound policy, backend fallback, dry-run and trace). It also proves through a real /bin/sh that a quoted click command round-trips.

Layout

lib/index.js     Cordis plugin: apply + the injectable runtime
lib/click.mjs    click handler: focus an existing tab, else open the URL
cordis.patch.yml bundle patch (one insert row)
locale/*.json    display title/description for the Plugins page
icon.svg         package icon
selftest.mjs     offline assertions

Security notes

• Notification text reaches the notifier as argv, never interpolated into AppleScript source, so a transcript line cannot become executed script.
• The click command is built from process.execPath, the package's own helper path, and the resolved URL, each single-quoted for the shell that runs it.
• The plugin reads agent/session state through ctx.get(...), so a missing or restricted service degrades it to "no workspace in the subtitle" instead of an error, and every listener is wrapped so a notification failure can never break Host dispatch.

Why every listener is global

Agent events are dispatched with a scope carrier, and Cordis keeps a listener only when hook.global || !filter || filter(carrier, hook.ctx). A listener registered through a scope-tagged context therefore receives that one agent's events and nothing else — and a row activated from inside an agent's scope, which is exactly what installing through a plugin-manager tool call does, gets that tag. Subscribing with { global: true } takes the listener out of the filter, so one plugin covers every agent in the process.

This is not theoretical: an earlier build registered plain listeners and notified for the installing session only. selftest.mjs asserts the flag on every registration so it cannot regress.

Community catalog

The ready-to-PR entry for awesome-dsh-plugin (the source behind awesome-dsh-plugin.com and dsh-market) lives in contrib/AK-blank__dsh-plugin-mac-notify.yml. To submit it, fork the list, copy that file to data/plugins/AK-blank__dsh-plugin-mac-notify.yml and open a PR — the list's CI requires the repository to be at least one day old, and the dsh-plugin topic (which this repo carries) is what makes dsh-plugin-radar pick it up in the meantime.

scripts/submit-catalog.mjs does the same thing without a local clone: it syncs a fork of the list with upstream main, adds that one file on its own branch, and opens the pull request. It is idempotent (a second run reports the pull request it already opened), refuses to run before the repository's age floor (exit code 3), and never force-pushes or touches an existing pull request.

node scripts/submit-catalog.mjs --dry-run   # validate the entry, write nothing
node scripts/submit-catalog.mjs             # fork, branch, commit, open the PR

License

MIT

Unofficial plugin. Not affiliated with, endorsed by, or supported by DeepSeek. “DeepSeek Harness” is a trademark of DeepSeek; this project uses the abbreviated “DSH” designation for the ecosystem, as the project's brand guidelines recommend.