dsh-notify-push

Push DeepSeek Harness agent notifications to your phone and watch via ntfy, Bark, Gotify, Telegram or a webhook — without keeping the browser tab open.
English | 简体中文

A DeepSeek Harness (dsh)
plugin. It pushes a short notification to your phone — and, through the
phone's own notification mirroring, to your watch — whenever an agent
finishes a turn, hits an error, or is waiting on your approval.

Unlike a browser notification, this leaves the machine: it goes out over the
network to a push service you choose, so it arrives while the Harness tab is
closed and the laptop lid is shut.

Settings ▸ Notify Push       v0.4.3 Author: icrefin [icrefinai@gmail.com]
└── delivery state, an editable configuration form,
the exact server and topic to subscribe to, armed triggers,
a live preview, the delivery log,
and one "Send test notification" button

It is a section of the Settings panel, not a page in the working area: a
notifier is configured once and glanced at occasionally, so giving it a permanent
sidebar icon and a whole centre column overstated it. The Settings shell owns the
trigger, the nav entry, the panel and the scrolling container, so this plugin
contributes only the section body — deliberately with no height, no second
scroll and no horizontal padding, all of which the shell already provides.

The version beside the title is read from the manifest at runtime, not baked
in at build time, so it names the build the harness actually loaded. That matters
because installing a new package does not re-compose a running profile: a swap on
disk leaves the old code live until a restart, and the chip is the fastest way to
tell those two situations apart. The author credit the repo style contract
requires — Author: icrefin [icrefinai@gmail.com] — rides in the same chip, to
the right of the version.

What a notification says

Every notification carries the same three facts, in a fixed shape:

So a lock screen reads:

Agent finished · workstation.local
Fix the login redirect
done in 42s

The event type is one of Agent finished, Agent error, Approval needed,
Question asked or Test notification. titlePrefix prepends a literal
(DSH · …) when you run more than one Harness.

A Question asked notification carries the question itself, not just word that
one exists — a prompt that only said "the agent has a question" would make you
open the app to find out whether it mattered:

Question asked · workstation.local
Fix the login redirect
Choose Mode — Which deployment should I target?
Blue · Green

The heading, the question and (when there are a few) the offered choices, so the
lock screen carries enough to decide whether to answer now. A longer question is
truncated here, with a visible ellipsis, rather than left for the OS to cut
mid-word.

Screenshots

How an event reaches your phone: the engine paces and de-duplicates, the formatter composes the two lines, the provider delivers.

Rendered from this plugin's own formatter output — the exact title and body strings, shown as they appear on a lock screen. Not a device screenshot.

Layout mockup of the Settings ▸ Notify Push section (illustrative, not a screenshot).

Surfaces

One slot registration, into settings.section — a list slot declared by
@deepseek-ai/dsh-client-ui-settings-general, whose entries carry
{ id, order, label } and whose active entry the shell renders inside its own
scrolling panel. dsh.client.inject names both that package and
@deepseek-ai/dsh-client-ui-settings, which owns the canonical slot contract and
is what makes the registration type-check against the real slot map.

Every route is loopback-fenced, method-checked and body-size-capped. The config
route additionally validates its patch against the field specs before anything is
written — a rejected key never reaches the settings document, which outlives the
process and would otherwise be reapplied on every boot.

How the browser half addresses these routes

The routes above are host paths and stay absolute; the browser half asks for
them relative to the document (CLIENT_API, derived from API by
clientPath() in src/protocol.ts). That is not a style choice. The web client
can be mounted under a path prefix — dsh-remote-control serves the real client
at /s// — and a request beginning with / resolves against the
origin, escaping that prefix. The prefix's own host then answers for /api/…:
through the relay that is its pairing page, a 200 text/html body, which
response.json() reports as Unexpected token '<'. A document-relative path
resolves against document.baseURI and stays inside whatever prefix the page is
served from, which is how the harness's own channels address the host.
test/protocol.spec.ts resolves both forms against a mounted base to pin it.

Install

pnpm install
pnpm check                              # typecheck both halves, build, then vitest
pnpm run pack                           # -> dist/dsh-notify-push-0.4.3.tgz

The desktop profile is owned by the Electron application, so dsh plugin add
refuses it: install the packed tarball from Settings → Plugins. A bundle
added to a running profile needs a restart before its entry can be imported;
the browser half additionally needs the page reloaded.

Configure

Edit it in the panel. Open Settings → Notify Push; the Configuration
section renders a form for the selected provider: pick the backend, fill in its
fields, press Save. A saved value applies immediately — no restart — because
every field of the row's schema is volatile, so the loader swaps it into the
running fiber rather than waiting for the next boot. It is also written to the
host's settings document, so it comes back after a restart.

Secret fields (tokens, device keys) are write-only: the stored value never
leaves the host, so the input starts blank and shows stored or not set.
Leaving it blank keeps what is there — there is no clear action, deliberately, so
a save can never wipe a working credential by accident.

Each secret field carries its own eye button, which unmasks what you are
typing so you can check a paste before saving. It cannot show the stored value,
because the browser was never given it — an untouched field stays empty with its
stored placeholder, revealed or not.

Configuration also works from the profile's cordis.patch.yml, which survives
plugin upgrades. The row id is dsh-notify-push:

- id: dsh-notify-push
name: dsh-notify-push
config:
provider: ntfy
ntfyServer: https://ntfy.sh
ntfyTopic:

Both paths write the same thing, so you can set a value in YAML and later adjust
it in the panel, or the reverse. If a deployment composes no settings service the
form renders read-only and says so, rather than accepting a change with nowhere
to put it.

Installing changes nothing on its own. Every trigger defaults to on, but no
provider is configured until you supply a topic, key or token, so the plugin is
inert out of the box and cannot surprise you with traffic. The panel says
Not configured and names the missing field.

Triggers and pacing

Pacing and de-duplication are what keep a noisy agent from becoming a noisy
phone: an error that repeats per step, or a burst of short turns, is collapsed
and counted as suppressed in the panel rather than delivered.

The two waiting triggers are observed, never claimed

approval/request and user-questions/request are both waterfalls, and the
listener that claims one owns the outcome. This plugin only ever observes: both
listeners notify and then delegate with next(), propagating whatever the real
answerer returns.

For questions that is not a style preference. The answerer behind
user-questions/request is the only thing that lets the agent continue, so a
listener that returned early would not merely drop a notification — it would
block the turn forever, behind a prompt nobody could reach. test/questions.spec.ts
asserts that the answerer runs and that its return value survives the
round trip.

Both are registered { prepend: true }, and that is load-bearing

Observing is not enough on its own. A waterfall composes outermost-first, and
next() walks inwards — but a listener that claims the request does not walk
at all: it resolves with the user's answer and the chain stops there.
@deepseek-ai/dsh-api-remotes is exactly that claimer and it is already
registered by the time this plugin loads, so a listener appended behind it is
never invoked.

That was a real bug here, not a hypothetical. 0.4.0 registered both listeners
plainly; when a question was asked the delivery log stayed completely empty — not
even a suppressed row, because the listener never ran — while the question
appeared in the UI perfectly normally. prepend: true puts the observer
outermost, where it can notify and then hand the request on, leaving the claimer
to own the outcome exactly as before.

The regression test is built on Cordis's own ordering rules (prepend unshifts,
appending pushes, the chain stops at a non-delegating listener) and registers a
claimer before the plugin. Removing the prepend makes it fail with a
request timeout — the production symptom. A test that only asserted "a listener
is registered" passed throughout the outage, which is why it was replaced.

Providers

Exactly one provider is active, selected by provider.

ntfy — iOS, Android, desktop

The simplest path, and the one that needs no account. Subscribe to a topic in
the ntfy app, then publish to it.

provider: ntfy
ntfyServer: https://ntfy.sh
ntfyTopic:

> On a public ntfy server the topic name is the password. Anyone who guesses
> it can read your notifications, which will contain session titles. Use a long
> random one, or self-host with authentication.

The panel prints the full server and topic under Subscribe on your phone, so
the string you type into the app is never something you have to go read out of
the profile YAML. Clicking a value selects all of it.

That is the one place a credential is shown in full, and it is deliberate: the
topic is the subscription identifier, so masking it makes the phone
impossible to set up. Publish tokens and device keys — which only authorize
sending — stay masked everywhere, and the target line remains a masked
summary for the log.

The topic therefore appears twice in the status payload: once here, and once as
the current value of the form's ntfyTopic field, which is what prefills that
input. Both are required for the page to be usable, and a test asserts it appears
nowhere else — not in target, the sample, or the counters.

Priority follows the event (3 info, 4 warn, 5 urgent) and each kind gets a
recognisable tag.

Bark — iOS

Reliable on iOS, including Focus-breaking delivery for approval requests.

provider: bark
barkKey:

Gotify — Android, self-hosted

provider: gotify
gotifyServer: https://gotify.example.com
gotifyToken:

Priority is 2 / 5 / 8 for info / warn / error.

Telegram

provider: telegram
telegramBotToken:
telegramChatId:

Generic webhook

Posts the event JSON to any URL — Slack, Discord, n8n, a script of yours:

provider: webhook
webhookUrl: https://example.com/hook

The body carries the resolved title, body and a Slack-compatible text
(plus content for Discord), alongside the raw kind, level, host,
session, detail and ts fields so a receiver can route on them.

Self-hosting ntfy

Any ntfy server works; point ntfyServer at it and add a token.

provider: ntfy
ntfyServer: https://ntfy.example.com
ntfyTopic:
ntfyToken:

A Docker deployment with authentication on:

services:
ntfy:
image: binwiederhier/ntfy
container_name: ntfy
restart: unless-stopped
command: serve
environment:
NTFY_BASE_URL: "https://ntfy.example.com"
NTFY_LISTEN_HTTP: ":80"
NTFY_CACHE_FILE: /var/lib/ntfy/cache.db
NTFY_AUTH_FILE: /var/lib/ntfy/auth.db
NTFY_AUTH_DEFAULT_ACCESS: deny-all
NTFY_BEHIND_PROXY: "true"
NTFY_ENABLE_LOGIN: "true"
volumes:
- ./data:/var/lib/ntfy
ports:
- "127.0.0.1:8080:80"

Create a user and a token, then keep the token server-side and give the phone
app the username and password:

docker exec -it ntfy ntfy user add --role=admin
docker exec -it ntfy ntfy token add

Two things to get right:

• Terminate TLS in front of it. The ntfy apps are unreliable against plain
  http:// on a public host, and on iOS an unsigned plain-HTTP origin is
  rejected outright. ntfy speaks plain HTTP; put Caddy, nginx or a tunnel in
  front of it, and set NTFY_BASE_URL to the https:// origin.
• Do not bind it to 0.0.0.0 before TLS is in place. The example above
  binds loopback so only the reverse proxy can reach it.

Why not just use the remote-control tunnel

dsh-remote-control already puts the real Harness client on your phone. It
still cannot deliver these notifications: a backgrounded browser tab's
WebSocket is suspended by the OS, so when the screen is off nothing arrives.
Reliable delivery needs a real push path — which is exactly what this plugin
adds. The two are complementary: the push tells you that something needs you,
the tunnel lets you act on it.

Limitations

• agent/error carries no agent or session in its payload, so the session
  name is resolved by registering a second listener on each agent's own context
  via agent/created. If that context is unreachable the notification is still
  sent, with the host and event type but no session line.
• One provider at a time. Use the webhook provider if you need to fan out.
• The delivery log is in memory and resets when the host restarts.
• Suppressed events are counted and logged, but are not themselves notified.

Verification

What has actually been checked, and how:

• pnpm check — both halves typecheck, the bundle builds, 111 tests pass.
• The tests are behavioural, not shape assertions: the engine is driven with an
  injected clock to prove pacing and de-duplication, the routes are served from
  a real loopback socket, and a regression test pins the ntfy publish URL to the
  server root (posting JSON to {server}/{topic} is accepted with HTTP 200 and
  puts the raw JSON on the lock screen).
• The built lib/index.js was mounted on a fake cordis context and driven
  through a real running → idle transition against a live ntfy server; the
  notification was read back off the topic and matched. That exercises the host
  half end to end, not a mock.
• test/status.spec.ts mounts the real apply() and drives the real status
  handler to pin the subscribe decision: the topic is reported in full, and
  the masked target is asserted not to contain it. It also asserts the reported
  version equals the manifest's, and that packageVersion() genuinely resolves
  from the installed location rather than falling back to unknown.
• Saving was checked against the built artifact, not just the source: the
  shipped lib/index.js was mounted with a settings service that assigns a patch
  into the live config — which is what the loader does to a volatile field —
  and the round trip went configured: false → POST /config (200, namespace
  dsh-notify-push) → configured: true with a later read already reflecting the
  value, no re-mount in between. An unknown key came back 400 without touching
  the config.
• The question trigger was checked against the built artifact too, because
  the delegation obligation is the kind of thing a bundle could break silently:
  the shipped lib/index.js registered user-questions/request, ran the real
  answerer, propagated its answer object unchanged, and delivered a
  Question asked payload whose body was exactly
  Choose Mode — Which deployment?\nBlue · Green. Both halves of the contract in
  one run: notify, and still let the answer through.
• The ordering requirement is covered by a test known to fail without the
  fix, and that was checked rather than assumed: removing the prepend drops the
  suite to 104 passing with two failures, one of them the claimer test timing out
  on a request that never arrived — the production symptom exactly. The
  registration-only assertions kept passing, which is the point: they could not
  have caught this.
• test/fields.spec.ts covers the trust boundary: unknown keys, wrong primitive
  types, out-of-range numbers, unlisted select values, over-long strings and
  non-object patches are all refused, and the descriptors are asserted never to
  carry a stored secret.
• The settings.section registration is type-checked against the real slot
  contract, not against a guess: @deepseek-ai/dsh-client-ui-settings ships the
  canonical SlotMap augmentation, so a wrong slot id, a missing id, or an
  option the slot does not accept fails pnpm typecheck rather than silently
  registering nothing at runtime.
• The built bundle was inspected for the surface itself: it registers
  settings.section and contains zero references to sidebar.panellist or
  main, and none of the centre-column page geometry (height:100%,
  max-width:960px, margin:0 auto, the darwin frame clearance) survives — all
  of which would have doubled what the settings shell already provides.
• The section renders — its live runs are what surfaced the missing topic, the
  missing version chip, the missing configuration form and the ambiguous Show
  toggle — but its appearance has not been inspected in the GUI by the author,
  and neither theme has been compared side by side with a shipped page. The move
  into Settings is the least visually verified change here: the geometry was
  reasoned from the shell's own container rule, not seen.
• Component behaviour is not tested. There is no React rendering test, so the
  form's interaction — the eye buttons, the pending-draft bookkeeping, the
  no-change guard — is covered by typecheck and the built bundle only. The wiring
  behind it (validation, the write, the read-back) is tested at the route and
  module level, which is where the failures would actually cost something.

Layout

License

MIT

> If this plugin saves you a trip back to your desk, a ⭐ star helps other DSH users find it.

<!-- Optional — delete this comment block if you don't want a star-history chart.
Star history, once the repository is public:

-->