dsh-tauri-notify-webhook
English · 简体中文
Forward a DSH desktop task notification to email (SMTP) or pushplus — when a task
stops abnormally or completes, and only while the window is not in front of you.
The problem this solves
The desktop shell already shows a toast when a turn ends, and it is easy to miss for a
reason worth stating precisely:
- A toast is a system notification. If the window is in front of you, you were already
watching the answer stream in — the toast is noise. If you walked away, the toast is
gone by the time you come back, and nothing remains on screen.
- The interesting endings are not equally interesting. A turn that ran to the end needs no
attention. A turn that errored, was aborted, hit the token ceiling or was blocked does.
- The host keeps only the latest
turn/end per session, so a finished session leaves no
queue to read later. Once you were away for that moment, the information is simply gone.
This plugin moves the notification off the screen and onto a channel that keeps history,
and it fires only for the two endings you would actually act on.
Install
dsh plugin --profile <name> add github:iuuuuuuuu/dsh-tauri-notify-webhook
The same spec works in the GUI plugin panel (设置 → 插件 → 安装), which accepts any npm
spec. For a local checkout, install the directory instead:
dsh plugin --profile <name> add link:D:/path/to/dsh-tauri-notify-webhook
There is no build step at install time: dist/ is committed. This is deliberate — the
desktop profile installs plugins as packages, and a package that has to be compiled after
installation would need a toolchain the profile does not have.
Restart DSH. This is required, not optional: the harness keeps loaded plugin modules in
its loader cache, and hmr.root defaults to [], so a newly installed plugin does not take
effect in a running host.
Use
Open 设置 → 任务推送, pick a channel, fill in its fields, press 发送测试, then
保存. The test button only becomes available once the form differs from what is saved,
so a successful test always describes exactly the values you are about to store.
| Channel | What it needs |
|---|
| 邮件 (SMTP) | SMTP host, port, security, from, to; username and password are optional for relays that accept anonymous mail |
| pushplus | A token from pushplus.plus; pushes go straight to the official /send endpoint |
| 关闭 | Nothing is sent. This is the default |
What it does
Two triggers
| Trigger | Fires when |
|---|
| 任务完成 | The turn ended with reason completed |
| 任务异常停止 | The turn ended any other way — aborted, error, blocked, max-tokens, interrupted, forked |
Both are on by default and are switched independently. Sub-agent sessions are skipped: they
are driven by their parent, so they would otherwise produce a burst of pushes for one task.
Only while you are away
A push is sent only when document.visibilityState === 'hidden'. The Tauri shell patches
document.hidden to the real window focus state, so this is "the window is not in front of
you" rather than "the tab is in the background". While you are watching the session, the
plugin stays silent.
How one push is decided
The client cannot read a turn's ending reason, so the decision takes two round trips:
- The session list flips a session from
running: true to false — that edge is the only
thing watched, so a session that was already finished when the plugin loaded is never
back-filled.
- After a 250 ms settle window (a turn can flicker its running flag), the client asks
GET /turn-end?sessionId=… for the reason the host recorded.
- If the session is still stopped and has not stopped again in the meantime, the client
posts
POST /delivery. The host re-reads the settings at that moment and sends.
Every step re-checks that the plugin is still loaded, so a reload mid-flight cannot deliver
a stale push.
Where your credentials live
Settings are stored on this machine only, at $DSH_HOME/notify-webhook/settings
(DSH_HOME defaults to ~/.dsh). The file is written through the shell's atomic-write
helper, so a crash mid-save cannot leave a truncated config. Nothing is uploaded anywhere
except the channel you configure.
The host routes are loopback-only, and every mutating request must also be same-origin;
a browser page on another origin cannot read your settings or make the plugin send mail.
Requirements
- The DSH desktop (Tauri) shell — this plugin is a client of the shell's
dsh-tauri
and dsh-tauri-ui runtime plugins, and of the settings.section slot, so it does not
apply to a browser-only profile.
- Node.js ≥ 22.15.0.
- For email: an SMTP server you can send through. For pushplus: a token.
Development
pnpm install
pnpm typecheck # tsc --noEmit
pnpm lint # eslint .
pnpm test # vitest run
pnpm build # tsdown -> dist/index.js, dist/index.d.ts, dist/client.cjs
CI runs the same four gates on Node 22 and 24, and then asserts that dist/ is up to date
(git diff --exit-code -- dist) — if you change src/, commit the rebuilt dist/ with it.
compat/ holds local stand-ins for the two modules the shell injects at runtime
(dsh-tauri, dsh-tauri/client, dsh-tauri-ui/client). They exist so that tsc and the
unit tests can run outside the desktop app; tsdown marks those specifiers external, so
none of this code reaches dist/.
License
MIT
