dsh-popup-notify

English | 中文

Modal desktop popups for DeepSeek Harness. Three moments that need you back at the window each raise a topmost dialog that stays until you dismiss it — not a toast that fades after a few seconds.

• Needs permission — a tool asks for approval.
• Needs a decision — the model asks you a question, or submits a plan for review.
• Run finished — a root agent goes from running to idle.

Zero npm dependencies. No bundled binaries, no build step, no post-install script: 340 lines of plain ESM driving PowerShell. Windows only.

Requires DeepSeek Harness 0.2.1-rc.2 or newer.

Install

dsh plugin --profile web add dsh-popup-notify

Then restart, or let the profile patch layer hot-reload. The bundle inserts one row:

- insert:
    - id: popup-notify
      name: 'dsh-popup-notify'

Uninstall with dsh plugin --profile web remove dsh-popup-notify.

The Plugins page shows this bundle's card from resources the package exports: ./locale/en.json and ./locale/zh.json supply meta.title and meta.description, and ./icon supplies the artwork. DSH resolves those paths through Node's module resolver without loading the plugin, so a manifest that exports only . renders the bare package name with no description and the default icon.

Why a modal instead of a toast

Windows toasts disappear on their own and stack up in Notification Center, where it is easy to miss them. When a run is blocked waiting for you, a dialog that refuses to leave until dismissed is the honest representation of that state.

The dialog runs in its own process, so it never blocks the agent loop. Only one is on screen at a time — further notices queue and appear as you close the current one.

Configuration

Override any key on the row's config in your profile's cordis.patch.yml. A patch replaces the whole config value, so restate the keys you want.

- id: popup-notify
  config:
    notifyOnComplete: false
    sound: false

Behaviour

Key	Default	Meaning
notifyOnApproval	true	Pop when a tool asks for approval.
notifyOnQuestion	true	Pop when ask_user_question or exit_plan_mode runs.
notifyOnComplete	true	Pop when a root agent finishes a run.
ignoreSubagents	true	Silence subagents, workflow workers, and AgentTeams members.
sound	true	Play the system asterisk sound with the dialog.
completeCooldownMs	10000	Minimum gap between two completion popups for one session.
plainDialog	false	Drop the topmost owner form. Use if a dialog lands somewhere odd; it may then open behind other windows.
testOnStart	false	Pop once on mount to confirm the PowerShell path works.
traceFile	''	Append a diagnostic line per event and per dialog. Empty disables it.

Message templates

Every message is a template. {placeholder} is filled from the event; unknown placeholders stay verbatim.

Key	Default
title	DeepSeek Harness
approvalMessage	工具 {tool} 需要你的权限确认
approvalReasonSuffix	\n\n理由：{reason}
questionMessage	需要你的回答：{question}
questionCountSuffix	\n\n（共 {count} 个问题，请在对话里逐个回答）
planReviewMessage	有一份计划等你审阅：批准，或继续规划。
completeMessage	Agent 响应已结束，可以查看结果了。
completeReasonSuffix	\n\n（结束原因：{reason}）
projectSuffix	\n\n项目：{project}

{reason} is the turn's end reason — absent for completed, otherwise aborted, error, max-tokens, and so on. {project} is the session working directory's basename. Set projectSuffix: '' to drop the source line, and completeReasonSuffix: '' to stop naming abnormal endings.

How it hooks in

Extension point	Mode	Use
approval/request	waterfall	Pops, then next() so the configured answerers still decide.
tools/pre-execute	waterfall	Matches ask_user_question and exit_plan_mode, pops, then next() so the tool runs.
agent/status	emit	Pops on the running → idle edge of a root agent.

DSH exposes no question event: ctx.userQuestions.ask() is a service call, and the pending question reaches the browser as a mux frame the host plugin never sees. Matching the two asking tool names at tools/pre-execute is the observable point that fires before you answer, which is what a reminder needs.

Both waterfalls call next(). A listener that returns without it would short-circuit the chain, so approval would resolve unavailable and the asking tool would never run.

Known limitations

• Windows only. Other platforms log one warning per notice and skip.
• Not every approval pops. With the never approval policy the service returns rejected before dispatching approval/request, so nothing can observe the ask. Session approvals only exist under the ask policy.
• The dialog is not clickable through to the conversation. It reports state; answering still happens in the DSH window.
• Only the two asking tools are recognised. A future interaction tool that also blocks on a human needs its name added to the matcher.
• One dialog at a time. A long absence can leave several queued behind the one on screen.
• plainDialog: true loses topmost. The no-owner MessageBox may open behind other windows.

Development

npm test                      # 22 unit tests, no dialogs spawned
node tests/smoke-dialog.mjs   # opens and closes one real dialog

The unit suite injects a fake spawnDialog, so it never touches the screen. smoke-dialog.mjs is the only file that opens a real window.

License

MIT