dsh-tool-notify

A DeepSeek Harness (DSH) plugin that adds a model-facing notify tool. The agent calls it when a long task finishes or something needs attention, and a message is delivered to your notification channel.

Supports two channel types:

• ntfy (default) — publishes to a topic on an ntfy server (https://ntfy.sh or self-hosted).
• webhook — POSTs a JSON payload to any generic webhook endpoint.

Status

> Developer preview. DeepSeek Harness is iterating rapidly and breaking changes are expected. This plugin is tested against DSH 0.1.0-rc.6 / cordis 4.0.1 / Node 22.19+. Pin versions when you install.

Requirements

• Node.js >=22.19 (or >=24)
• pnpm via Corepack (packageManager: pnpm@11.7.0)
• A running DeepSeek Harness profile (dsh --profile <name>)

Install

From npm (prebuilt, no build permission needed)

dsh plugin --profile demo add dsh-tool-notify

From GitHub (sources — build runs at install)

dsh plugin --profile demo add github:rizkirmdhn/dsh-tool-notify#<commit-sha>

pnpm ≥10 refuses to run the package's prepare build script until you allow it. dsh prints the exact package key; add it to the profile's pnpm-workspace.yaml:

allowBuilds:
  dsh-tool-notify: true

and re-run the add. That allowance means "run this package's code on my machine at install time" — only add packages whose source you trust, and pin a commit.

From a tarball

pnpm pack
dsh plugin --profile demo add ./dsh-tool-notify-0.1.0.tgz

Configuration

The bundle inserts a row with id notify. Override it in your profile's cordis.patch.yml (later layers win per row; a patch replaces the whole config):

- patch:
    - id: notify
      config:
        endpoint: https://ntfy.sh
        defaultTopic: dsh-alerts
        timeoutMs: 10000
        channel: ntfy
        # tokenRef: NTFY_TOKEN

| Field | Type | Default | Description | |---|---|---|---| | endpoint | string | https://ntfy.sh | Base URL of the ntfy server or the full webhook URL | | defaultTopic | string | dsh-alerts | Topic used when the model does not pass one (ntfy only) | | timeoutMs | number | 10000 | HTTP request timeout | | channel | 'ntfy' \| 'webhook' | 'ntfy' | Channel type | | tokenRef | string | — | Credential reference (env-var style name) for a Bearer token |

Auth via credentials

Secrets never go in config. Set tokenRef to the name of a credential (e.g. NTFY_TOKEN), then configure that credential through DSH's normal credential provider (env var, .env, or the UI). The plugin resolves it once per call through ctx.credentials, so a rotated token reaches the next call without a restart.

Usage

The model sees a notify tool with parameters:

{
  "message": "string (required)",
  "title": "string (optional)",
  "priority": "'min' | 'low' | 'default' | 'high' | 'max' (optional, ntfy)",
  "topic": "string (optional, ntfy override)"
}

A successful call returns { ok: true, status, channel }; a non-2xx response returns { ok: false, status, channel } (not an error). Network failures and timeouts are reported as tool errors.

ntfy

POSTs to {endpoint}/{topic} with body { topic, message, title, priority }.

webhook

POSTs to {endpoint} directly with body { message, title } — no ntfy-specific fields.

Development

pnpm install
pnpm run typecheck
pnpm run test
pnpm run build

The package is a standard DSH bundle: package.json declares "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }, the plugin registers via ctx.tools.register(defineTool(...)), and registrations are effects that unwind when the plugin unloads.

License

MIT