# dsh-notify-plus

[English](README.md) | [中文](README.zh.md)

Context-rich native notifications for **DSH Desktop** — both the official
**DeepSeek Harness** shell (`0.2.0-rc.x`) and the earlier `DSH Desktop` shell
(`2.0.x`).

DSH Desktop's built-in notification told you that *a* turn finished. It never
told you *which* conversation, or *what* the turn actually produced — so the
toast was impossible to act on:

| | Built-in | dsh-notify-plus |
| --- | --- | --- |
| Title | `用户回合已完成` / `User Turn Completed` | `重构通知插件` — the live conversation title |
| Body | `一个由你发起的回合已完成。` / `A user-initiated turn has finished.` | `已经修复了通知排序，现在会优先选择最近的助手…` — a distilled one-liner |

On the earlier shell the plugin replaces that built-in row and reuses its
settings namespace, so the existing Desktop toggles keep working and no user
preference is lost. The official 0.2.0 shell removed the row *and* the
notification service a plugin could call, so there the plugin raises the toast
itself. See [How the replacement works](#how-the-replacement-works).

## What it does

- **Titles every toast with the live conversation title.** The title comes from
  the log-backed session title service, so it follows renames and automatic
  title revisions instead of being a constant.
- **Distils the turn into one actionable line.** For CJK replies the body is
  10–20 characters; for Latin replies it stays inside the Windows toast body
  envelope. Nothing is sent to a model — the distillation is deterministic, so
  it costs no tokens and adds no latency.
- **Keeps failure reasons.** A failed turn reports the actual error instead of a
  generic apology, and a context-exhaustion stop is labelled separately.
- **Carries the job label** on background job notifications, so `pnpm test`
  finishing is distinguishable from several other jobs finishing at once.
- **Never fires for internal fan-out.** Delegated subagent sessions and turns
  that no user message started are ignored, exactly like the built-in row.

## Requirements

| | |
| --- | --- |
| DSH Desktop | the official **DeepSeek Harness** shell — verified against `0.2.0-rc.2` — and the earlier `DSH Desktop` shell — verified against `2.0.3` |
| Harness | `@deepseek-ai/dsh 0.2.0-rc.x`, and `0.1.1-rc.x` on the earlier shell |
| Windows | 10 or 11. The toast path uses Windows PowerShell 5.1 and the installed DSH Desktop AUMID |
| Node | `>=22.19.0` (only for development and tests) |

The plugin depends on one harness-provided module, `@deepseek-ai/schemastery`,
which DSH already mounts. You do not need to install it yourself.

## Install

### From the DSH Desktop Market

Search for `dsh-notify-plus` in the Desktop plugin market and install it. The
market writes the package into the active profile's `dsh.profile.bundles`, which
is all this plugin needs.

### From the command line

```powershell
dsh plugin --profile <your-profile> add dsh-notify-plus
```

`dsh plugin` is a pnpm forwarder: it installs the package into the profile and
reconciles `dsh.profile.bundles` against the installed state. A package that
declares `dsh.bundle.patch` — this one does — joins the layer stack
automatically.

### From a local checkout

```powershell
git clone https://github.com/hoyin-law/dsh-notify-plus.git
dsh plugin --profile <your-profile> add C:\path\to\dsh-notify-plus
```

Then restart DSH Desktop. Confirm the row is live before assuming anything:

```powershell
dsh --profile <your-profile> dump-config | Select-String "dsh-notify-plus"
```

## How the replacement works

Both rows are Cordis plugins. Rather than racing the built-in observer (which
would raise two toasts per turn), this plugin ships a bundle patch that disables
the built-in row and inserts its own:

```yaml
- id: desktop-notifications
  disabled: true

- insert:
    - id: dsh-notify-plus
      name: dsh-notify-plus
```

On the official 0.2.0 shell there is no `desktop-notifications` row to disable,
and the DSH loader reports an id-targeted patch that matches nothing as a
warning, so the first entry is inert there and the plugin is purely additive.

### Raising the toast

The notification surface changed underneath this plugin, and the change is the
reason 0.2.0 needs its own path:

| | earlier `DSH Desktop` 2.0.x | official `DeepSeek Harness` 0.2.0 |
| --- | --- | --- |
| Host process | Cordis host boots inside the Electron main process | host boots as a **separate Node child process** (`spawn(node, [...dsh-desktop-host/lib/index.js])`) |
| Plugin surface | `desktopRuntime.notifyAttention({ title, body })` | **none** — `desktopRuntime` has zero occurrences in the shipped app |
| Built-in row | `desktop-notifications` with hard-coded copy | removed entirely; `dsh-desktop-notifications` has zero occurrences |
| Host → shell IPC | in-process | open, but a closed protocol: only `ready`, `platform-session`, `fatal`, `shutdown-complete`, `update-tasks`, and `quit-inspection` are accepted, and an unknown message makes the shell kill the host |

So the plugin keeps `desktopRuntime` as an **optional** injection — where it
exists, the original call is used unchanged — and otherwise raises a native
Windows toast itself:

1. the notification is encoded as base64 UTF-8 JSON, so quotes, newlines, and
   CJK never touch a command line where PowerShell's `-File` parsing could
   mangle them;
2. Windows PowerShell **5.1** (not `pwsh`, which dropped the WinRT type
   projection) decodes it and shows a `ToastText02` through
   `CreateToastNotifier("com.deepseek.dsh")` — the AUMID of the installed
   Start Menu shortcut, which is what makes the toast read as DeepSeek Harness
   and land in the Action Center;
3. before showing, the script checks whether `DeepSeek Harness.exe` owns the
   foreground window and stays silent if it does, matching the old host's
   focus suppression. The check **fails open**: an unreadable foreground window
   raises the toast rather than swallowing it.

The sink also degrades instead of throwing: if PowerShell cannot be spawned the
plugin keeps running, logs once, and stops trying, so a broken notification path
can never disturb the turn that produced it.

### Why the bundle declares no DSH peer dependencies

DSH 0.2.0 refuses to load any plugin whose `peerDependencies` on
`@deepseek-ai/dsh*` do not satisfy the running runtime — a `^0.1.0-rc.x` range
fails against `0.2.0-rc.2`, and the row is disabled before it is imported. This
plugin consumes only services (`sessions`, `jobs`, `settings`, `sessionTitle`,
`desktopRuntime`) and imports nothing from the harness except `schemastery`,
which is not covered by that check. Staying off the DSH peer surface is
therefore deliberate: it is what lets one build load on both hosts.

## Settings

On the official 0.2.0 shell the plugin exports a Cordis `Config`, so every field
appears in **Settings** and is persisted into the active profile's
`cordis.patch.yml`:

| Key | Default | Effect |
| --- | --- | --- |
| `enabled` | `true` | Master switch for every notification |
| `notifyOnTurnCompletion` | `true` | A conversation turn finished |
| `notifyOnTurnFailure` | `true` | A conversation turn failed or ran out of context |
| `notifyOnJobCompletion` | `true` | A background job finished |
| `notifyOnJobFailure` | `true` | A background job failed |
| `locale` | `auto` | `auto` follows the host locale; `zh` or `en` force one |
| `appId` | `com.deepseek.dsh` | AUMID the toast is attributed to |
| `suppressWhenFocused` | `true` | Stay silent while DSH Desktop owns the foreground |
| `focusProcess` | `DeepSeek Harness` | Process name that counts as focused |

The same values can be set by hand in the profile:

```yaml
- id: dsh-notify-plus
  config:
    notifyOnJobCompletion: false
    locale: zh
```

On the earlier 2.0.x shell the plugin additionally registers the
`dsh-desktop-notifications` namespace with the same five switches, so
**Settings → Notifications** keeps controlling it exactly as before. That
namespace wins over the row config, and it is only registered where the old
scope API still exists.

Nothing fires for work you are already watching: the toast script stays silent
while the DSH Desktop window owns the foreground.

### A known upstream caveat

This applies to the earlier 2.0.x shell, which still ships the
`profile-preferences` record.

On those releases, edits made in **Settings → Notifications** may revert on the
next launch. The desktop keeps a private copy of `mode`, `openBrowser`,
`networkExposure`, and `notifications` under
`<userData>/profile-preferences/<profileHash>/state.json` and mirrors it back
into `settings.yaml` at startup, while the settings page only writes
`settings.yaml`. This plugin reads whatever the document says, so it inherits the
revert exactly as the built-in row does.

Tracked upstream as
[issue #947](https://github.com/anywhere-labs/deepseek-harness-desktop/issues/947).
DSH Desktop 2.0.3 does not contain that mechanism and is unaffected; the report
is against 2.0.9, and the mirroring code first appears in a later release than
2.0.3.

This is deliberately **not** worked around here. That record is another
component's private source of truth: writing it from a plugin would add a second
writer to a single-document record that also holds the user's browser and
network-exposure choices.

## What the body line is

`lib/summarize.js` is dependency-free and deterministic. It:

1. strips fenced code, inline code, link targets, bare URLs, HTML tags,
   headings, list markers, blockquotes, emphasis, and control characters;
2. splits the remainder into sentences, keeping terminators attached;
3. drops a leading acknowledgement clause (`好的，`, `Sure,`) so the line starts
   with the work rather than the pleasantry;
4. accumulates sentences until the script's minimum is met;
5. truncates at a clause boundary inside the budget, appending `…`.

Budgets live in one place and are easy to argue with:

```js
export const DEFAULT_LIMITS = Object.freeze({
  cjk: Object.freeze({ min: 10, max: 20 }),
  latin: Object.freeze({ min: 40, max: 140 }),
});
```

When a turn produced tool work but no prose at all, the body falls back to a
tool-call count (`已完成 3 项工具调用…`) rather than a hollow "done".

## Compatibility

This plugin reads harness internals that are not a stable public contract:
`sessions.on("session/event")`, `ctx.get("sessionTitle")`, the background-job
settlement stream (`jobs.onJobDone` on 0.1.x, `jobs.events.subscribe` on 0.2.0),
and the notification surface (`desktopRuntime.notifyAttention` on 0.1.x; a
self-contained Windows toast on 0.2.0). Each of those is driven behind a
feature check and covered by tests against the verified shapes.

Because the notification surface is now the plugin's own, a host that provides
nothing still loads: the session observers run, the sink reports why it stayed
silent, and one broken notification never disturbs the turn that produced it.
A release that changes the session or job shapes will stop producing that kind
of notification; please open an issue with your DSH Desktop version.

## DSH STORE status

This plugin is **not listed in [DSH STORE](https://dsh.store/)**. The store's
automated policy declines any bundle patch that disables a shipped entry, and
disabling one is exactly what makes this plugin work: without it, the built-in
`desktop-notifications` row keeps raising its own toast, and the two plugins
cannot coexist at all — both register the `dsh-desktop-notifications` settings
namespace, and `settings.register()` throws on a duplicate, so the second one
fails its row.

That is a deliberate, documented trade rather than an oversight:

- The row this plugin disables belongs to `dsh-plugin-desktop` (the DSH Desktop
  launcher), not to a `@deepseek-ai/*` package. No official harness package,
  entry ID, or namespace is modified.
- The replacement is exact: the plugin re-registers the same settings namespace
  with the same five keys, so the Desktop switches keep working and no user
  preference is lost.
- Install and start were verified end to end on DSH Desktop 2.0.3; see
  [Verifying a live install](#verifying-a-live-install).

Install it from the repository instead:

```powershell
dsh plugin --profile <your-profile> add https://github.com/hoyin-law/dsh-notify-plus
```

A future release may make the disable an explicit opt-in in the user's own
profile layer, which would let the bundle patch become purely additive. That
needs the plugin to fall back to its own settings namespace when the built-in
row is still present, so it is a behaviour change rather than a packaging tweak.

### Upstream status

The capability this plugin adds is being implemented natively. Upstream `master`
still ships the hard-coded copy, but
[PR #969](https://github.com/anywhere-labs/deepseek-harness-desktop/pull/969)
adds session titles as notification headings plus a final-answer preview, and
[issue #951](https://github.com/anywhere-labs/deepseek-harness-desktop/issues/951)
asks for host-level governance of third-party plugin notifications.
[`docs/upstream-request.md`](docs/upstream-request.md) records the duplicate
check that stopped us filing a new request, the relevant threads, and what is
worth contributing to them.

If that work lands in a DSH Desktop release, this plugin should be retired
rather than kept alive by disabling an official row that is already correct.

### Declared compatibility

`package.json` carries a per-release declaration under
`dsh.compatibility.dshReleases`. Every entry is either runtime-verified or
interface-verified against the published package — never assumed:

| DSH release | Basis |
| --- | --- |
| `0.2.0-rc.2` | runtime-verified: installed into a live profile on the official **DeepSeek Harness** shell and observed raising a correctly-shaped toast through the AUMID path |
| `0.1.1-rc.2` | runtime-verified: installed into a live `web` profile on DSH Desktop 2.0.3 and observed raising correctly-shaped toasts |
| `0.1.5-alpha.2` | interface-verified: every consumed surface has an identical signature and payload shape |
| `0.1.5-rc.1` | interface-verified: same |
| `0.1.5-rc.2` | interface-verified: same |

"Interface-verified" means the consumed surfaces — `sessions.on("session/event")`
with the `turn/start`, `turn/end`, `assistant/message`, and `user/message`
payloads; `sessionTitle.get(session)`; the job settlement stream; and
`settings.register(ns, schema, options)` — were diffed against each release's
published types and sources and found unchanged. It is a source-level claim, not
a runtime acceptance, and it is labelled as such.

`0.2.0-rc.2` additionally changed three of those surfaces, all of which are
handled here: `jobs.onJobDone(snapshot)` became
`jobs.events.subscribe({ owners }, listener)` delivering a `settled` event whose
`job` carries `status` and `label`; the namespace-scope settings API was
replaced by a `Config`-derived form model, so the plugin exports `Config` and
keeps the legacy namespace only as a bridge; and the native notification service
disappeared with the in-process host.

Only `win32` and the DSH Desktop host are declared. The observation layer is
platform-neutral, but the notification path is Windows-only, so nothing else has
been run.

## Development

```powershell
npm install            # only needed for the harness-provided schemastery peer
npm test               # 106 assertions across 7 suites, no harness required
npm run verify:layering   # composes the real patch layers via the dsh CLI
```

The test suite covers the pure layers — summarisation, copy, session
projections, the turn/job state machine, the settings bridge, and the
notification sinks — with hand-built fixtures and an injected spawn stub, so the
behavioural contract is checked without launching Electron or raising a toast.

`.volatile()` is feature-detected: the dev schemastery (3.18.2) predates it, so
the suite exercises the fallback path and skips the volatility assertion; the
0.2.0 Desktop ships 3.18.4 and the 0.1.x Desktop ships 3.18.1.

`verify:layering` is the one check that needs DSH Desktop installed. It builds a
throwaway `DSH_HOME`, stands in for the launcher-owned layer, and asks the real
`dsh --dump-config` to compose the tree, asserting that the built-in row ends up
`disabled: true`, that this plugin's row follows it, and that a host without the
built-in row still exits `0` with only a warning. Point it elsewhere if your
installation is not in the default location:

```powershell
node scripts/verify-layering.mjs --app "D:\Apps\DSH Desktop\DSH Desktop.exe"
```

```
lib/
  index.js       Cordis wiring: config, settings bridge, jobs, sessions
  notify.js      notification sinks: host runtime, Windows toast, null
  turn.js        session event -> notification payload state machine
  summarize.js   deterministic text distillation
  copy.js        localized copy for every locale
  session.js     read-only projections over DSH session values
  settings.js    Cordis Config plus the legacy dsh-desktop-notifications namespace
cordis.patch.yml bundle patch: disable the built-in row, insert this one
scripts/
  toast.ps1               Windows toast through the DSH Desktop AUMID
  verify-layering.mjs     composes the real patch layers through the dsh CLI
tools/
  asar.mjs                reads harness interfaces out of app.asar
  read-windows-toasts.mjs reads delivered toasts out of the Windows history DB
```

### Verifying a live install

Neither notification path leaves an application log line — Electron's
`Notification` did not, and a PowerShell toast does not — so the only reliable
check is the shell's own toast history:

```powershell
node tools/read-windows-toasts.mjs --limit 10
```

Both paths also stay silent while the DSH Desktop window owns the foreground, so
a focused test can look like a no-op. To observe a toast without waiting for a
real turn to finish, exercise the sink directly; this raises one regardless of
focus and proves the whole chain — PowerShell resolution, payload encoding,
spawn, script, AUMID:

```powershell
node --input-type=module -e "import('file:///C:/path/to/dsh-notify-plus/lib/notify.js').then(async ({createToastSink}) => { const s = createToastSink({ readConfig: () => ({ enabled: true, locale: 'zh', appId: 'com.deepseek.dsh', focusProcess: '', suppressWhenFocused: false }) }); s.notifyAttention({ title: 'dsh-notify-plus', body: 'sink check' }); })"
```

A working replacement looks like this, with the cutover exactly at the restart:

```
2026/9/14 04:33:35  title="重构通知插件"   body="已经修复了通知排序逻辑，现在会优先…"
2026/9/14 04:23:24  title="用户回合已完成"  body="一个由你发起的回合已完成。"
```

One row per turn, the title is a real conversation name, the body is a truncated
distillation rather than a fixed sentence, and the hard-coded row stops appearing
at the restart rather than alongside the new one — which is what proves the
built-in observer was disabled instead of merely joined.

## License

MIT