dsh-blocker-notify

English | 简体中文

Real-time attention alerts for DeepSeek Harness (DSH): when an agent gets stuck and needs you to step in, the web UI notifies you in real time — no need to watch the screen waiting for an action.


The three kinds of "blocked" signals that trigger a notification:

> Only events that need your action are alerted (approval / question / plan review). A sandbox denial is a completed event with nothing to act on, so it stays silent — even when the approval policy is never.

The four notification mechanisms

How to use

Option 1: Dynamic plugin (quick enable, ~5 minutes, recommended to try first)

Nothing to install, no DSH restart needed. Downside: process-memory only — re-enable after a DSH restart.

1. Get the source: git clone https://github.com/Frost-Reed/blocker-notify (or download from the GitHub page). 2. Open any session (preferably cordis / creator mode) and send this instruction to the agent (replace <repo-path> with your local clone path):

``text Please enable dsh-blocker-notify as a dynamic plugin: 1. Use the read tool to read <repo-path>/dynamic/host.js and <repo-path>/dynamic/client.js (these are the code.host and code.client function bodies — use the file contents directly). 2. Call cordis_define: plugin: { kind: "new", idPrefix: "ntfy" }; name: "blocker-notify"; purpose: one sentence; code.host = host.js content; code.client = client.js content. 3. Call cordis_run (mode: "run") with the pluginId/packageId returned by cordis_define. 4. The run may require the user to approve the Client half in the web UI; wait for the approval result, do not re-request. 5. When done, use cordis_inspect_self(pluginId, packageId) to confirm host/client are both running. ``

3. Approve the Client half's run request in the web UI (once). 4. Verify immediately (see "Verification" below).

Option 2: Formal bundle install (persistent, v0.2.0)

Packaged per DSH's official plugin spec (dsh.bundle + dsh.client); survives restarts once installed.

> If dsh is not on your PATH (e.g. running from a source checkout or not installed globally), replace dsh below with pnpm dsh (in the source repo root) or npx @deepseek-ai/dsh.

Install from GitHub (published, recommended):

dsh plugin --profile web add github:Frost-Reed/blocker-notify

Install from a local checkout (development):

dsh plugin --profile web add file:<local-clone-path>

After installing:

# Confirm it joined the layer stack
Get-Content $env:USERPROFILE\.dsh\profiles\web\package.json   # dsh-blocker-notify should appear in dsh.profile.bundles
# Confirm the row is in the config tree
dsh --dump-config --profile web | Select-String "dsh-blocker-notify"
# New dependencies/layers require a process restart
dsh web

> lib/ is committed build output (generated from src/ by tsdown). Git installs run the prepare build script, so pnpm needs a one-time allowBuilds authorization; alternatively install the npm package or a pnpm pack tarball (prebuilt, no authorization needed).

Verification (common to both options)

How it works

Host half (in-process, untagged scope → observes every agent's approvals/tool results)
  ├─ ctx.on('approval/request', (req, next) => …)   // waterfall: observe only, must return next()
  └─ ctx.on('tools/result', …)                       // detects FS_SANDBOX_DENIED
        │  writes to the in-process alert log (deduped by key, 10-min TTL, cap 60)
        ▼
  Details channel: formal = webServer route GET /api/dsh-blocker-notify/alerts
                   dynamic = harness.handle('blocker-notify/alerts') RPC
        ▼
Client half (browser page, root scope)
  ├─ useSessions (shell.overlay standard prop) → live pendingInteraction (approval / plan-review / question)
  ├─ polls details (fetch / host.call) → merges approval details (tool name / reason)
  ├─ CSS injection → flashes [data-state="warning"] dots
  ├─ Web Audio → plays a chime when an actionable blocker appears (AudioContext primed on first interaction)
  └─ Notification API → raises an OS notification for actionable blockers (one-click enable + self-test in the banner; clicking focuses the page)

• Host half: captures blocking signals and maintains the in-process alert log (plain JS, no UI).
• Client half: the four notification channels. Data comes from the shell.overlay standard prop useSessions (snapshot { ids, byId, … }; byId entries carry id / title / pendingInteraction) plus the Host details poll.
• The formal and dynamic versions share the same logic; only the "details channel" differs (webServer route vs. dynamic RPC) — see docs/ROUTE-B.md.

FAQ

Development & build

• src/ is TypeScript source (written the official source-repo way); lib/ is the tsdown build output (committed). pnpm build (tsdown, replicating the official clientBundle preset) generates lib/index.js (ESM named-export plugin) and lib/client.js (official window.__ModuleLoader__.load({ id, factory }) web bundle).
• Committing lib/ means git installs work; the prepare script (= tsdown) rebuilds on git install.
• Offline smoke test: node scripts/smoke.mjs (validates both halves' exports, inject, event listeners, route JSON, CSS injection, slot registration, rendering, UTF-8 copy).
• dynamic/ holds the dynamic-plugin function bodies (used by Option 1), logically identical to lib/ with a different channel.
• Full Route-B research and implementation record: docs/ROUTE-B.md; fresh-deployment enablement guide: docs/ENABLE.md.

Repository layout

dsh-blocker-notify/
├── LICENSE               # MIT
├── package.json          # bundle (dsh.bundle) + client (dsh.client) manifests
├── README.md             # Chinese readme
├── cordis.patch.yml      # bundle patch: inserts the Host row
├── src/                  # TypeScript source (official source-repo method)
│   ├── index.ts          # Host half (ESM name/inject/apply + webServer route)
│   └── client/index.ts   # Client half (built into the ModuleLoader web bundle)
├── tsdown.config.ts      # build config (replicates the official clientBundle preset)
├── tsconfig.json
├── lib/                  # tsdown build output (committed)
│   ├── index.js          # Host half
│   └── client.js         # Client half (ModuleLoader format)
├── scripts/
│   └── smoke.mjs         # offline smoke test
├── dynamic/              # dynamic-plugin function bodies (Option 1)
│   ├── host.js
│   └── client.js
└── docs/
    ├── ENABLE.md         # fresh-deployment enablement guide
    └── ROUTE-B.md        # Route-B formalization record

License

[MIT](LICENSE)