dsh-plugin-web-notify

dsh-plugin-web-notify

Browser notifications for the DeepSeek Harness Web GUI.

Targets DSH 0.1.5-rc.2 and its split session-controller / UI-session client APIs.

Shows a browser notification when:

• the agent explicitly sends a meaningful update during a long-running turn;
• a conversation turn finishes while you are not watching that session;
• the agent starts waiting for you — an approval request, a plan review, or a question.

Features

• Agent-requested updates — the model receives web_notify__send(message) and can notify you at a meaningful intermediate milestone without ending its turn. Routine progress, final completion, and pending interactions remain automatic and should not call it.
• Click to focus and switch — clicking the notification brings the GUI window to the front and switches to the finished/asking session.
• Work-segment summaries — when a logical work segment completes, the notification first shows a "summarizing…" hint (only when the host summary capability is detected) and is then replaced with a one-sentence summary of what the segment accomplished, generated by a small model (host-side; configurable provider/model).
• Continuation-aware completion — a turn that successfully hands off through Turn Memory does not notify. When the final continued turn finishes, the summary covers the complete linked work segment instead of only the last physical turn.
• Stays until dismissed — notifications use requireInteraction and stay on screen until you click or dismiss them (set the REQUIRE_INTERACTION constant in client/index.ts to false, then rebuild, for the OS default auto-dismiss timing).
• Chime — plays a short two-tone sound along with the notification (browsers allow page audio after the page has been interacted with at least once).
• No interruptions — no notification while the page is focused on the finished/asking session; you already see it.
• One toast per session — notifications for the same session replace each other instead of stacking.
• Subagents ignored — subagent sessions do not produce notifications.
• Permission on first click — the notification permission is requested automatically on the first click inside the page; grant it once and you are done.
• Bilingual — notification text follows the browser language (Chinese / English).

Install

Add the plugin to your dsh profile and register it in the Loader.

From GitHub

dsh plugin --profile web add github:vilicvane/dsh-plugin-web-notify

This is equivalent to running pnpm add github:vilicvane/dsh-plugin-web-notify inside the profile directory.

From npm

Once the package is published to the npm registry:

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

Then append an insert row to the profile's cordis.patch.yml ($DSH_HOME/profiles/web/cordis.patch.yml):

- insert:
    - id: web-notify
      name: dsh-plugin-web-notify
      config:
        provider: deepseek-official
        model: deepseek-chat

The config block is optional and defaults to deepseek-official / deepseek-chat. All settings and their defaults:

Restart dsh web, refresh the page, and click anywhere once to grant the notification permission.

How it works

• index.ts is the host assembly layer. It registers /web-notify/summary and /web-notify/capability on the DSH web server, registers the web_notify__send(message) tool and its session projection, and delegates to typed modules under lib/. Both HTTP routes use the DSH connection service's cookie authentication and origin checks.
• lib/tool.ts returns a normal successful tool result whose durable presentation metadata contains the notification request. It does not end the turn or append a plugin-private event. lib/projection.ts folds the latest successful request from Native tool/result events or Code Mode tool/code-dispatch events into webNotifyRequest.
• lib/turn-summary.ts finds the latest matching turn/start → turn/end interval and follows only verified Turn Memory continuation links to their predecessor turns. It includes human-authored user messages and text-bearing assistant messages from that completed logical segment, while excluding runtime/plugin context, unrelated older turns, and a later open turn.
• lib/summary-service.ts calls the configured model through ctx.llm.stream with the session-title purpose, deduplicates concurrent requests for the same completed logical segment, and bounds its in-memory cache.
• client/index.ts is the typed Cordis client source. It injects the sessions and uiSession services, watches the session-list snapshot for running → false transitions and changes to the webNotifyRequest projection, and independently subscribes to uiSession.pendingInteractions (approval / plan-review / question). Request keys distinguish successive interactions of the same kind. Pending interactions take priority over agent-requested updates while unresolved. It probes the capability route at apply (and again after server connection resets), so webNotifyCompletion projection suppresses the transient idle boundary after a successful continue_after_turn_compression handoff. Other completion notifications start with a "summarizing…" hint only when the host summary is actually available. The client polls the summary route; the summary replaces the hint (same tag) once ready, and failures degrade back to the plain completion text. A per-session generation invalidates an older summary request as soon as a newer completion or pending interaction arrives, preventing stale summaries from replacing actionable notices. Projection identities are seeded from the initial snapshot, so refreshing or reconnecting never replays an old agent-requested notification.
• scripts/build-client.mjs bundles client/index.ts into the published loader artifact client.js. The generated file is checked in so GitHub and npm installs work without a build step.

Notes

• Windows may deliver Chrome notifications quietly (notification center only, no banner, no sound). Check Windows Settings → System → Notifications → Google Chrome and enable "Show notification banners" and "Play a sound"; also make sure Focus Assist is off.
• Browsers do not expose a configurable auto-dismiss duration; the operating system controls it. This plugin uses requireInteraction so notifications stay visible until clicked or dismissed.
• The chime is subject to the browser autoplay policy: it plays only after the page has been interacted with at least once.
• Bringing a window to the front without a user gesture is restricted by browsers, so automatic focusing on show is best-effort; clicking the notification always focuses the window and switches to the session.
• Summaries are generated only when a completion notification actually fires (one small-model call per completed logical segment), and only the bounded human and assistant text from its verified continuation-linked turns is sent. Tool results, model reasoning, runtime snapshots, and unrelated session history are not transmitted.

Development

pnpm install
pnpm build:client
pnpm check

pnpm check proves that client.js matches its TypeScript source, runs the host/client behavior tests, and type-checks both environments. See design.md for the lifecycle and concurrency invariants.

License

MIT