dsh-tool-notify: DeepSeek Harness Notification Tool

Foreword¶

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin,” allowing developers to enhance Agent capabilities through extension components. When building long-running Agent tasks, a common requirement is to be able to timely notify external channels when a task is completed or human intervention is needed. The dsh-tool-notify plugin is designed for this purpose. It provides the model with a native notify tool, supports sending notifications via ntfy or Webhook, and addresses the integration pain points between Agents and external systems.

Feature Overview¶

This plugin mainly provides the following capabilities:
* Model-native tool: The model can directly invoke the notify tool during execution.
* Dual-channel support:
* ntfy (default): Publishes to an ntfy server (such as https://ntfy.sh or a self-hosted service).
* webhook: Sends a JSON payload to any generic Webhook endpoint.
* Trigger timing: Typically invoked when an Agent task is completed or attention is required.

Installation and Enablement¶

Environment Requirements¶

Before installing, ensure the environment meets the following conditions:
* Node.js version: >=22.19 or >=24.
* Package manager: Enable pnpm via Corepack, with the version required as pnpm@11.7.0.
* A running DSH Profile: an environment started via dsh --profile <name>.

Installation Command¶

Install using the npm prebuilt package (recommended; no build permissions required):

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

Installing from GitHub Source¶

If installing from GitHub source, the build script is executed during installation. Note: if the pnpm version used is greater than 10, you must first configure build permissions:

1. In your profile configuration directory, find pnpm-workspace.yaml and add the following configuration:

allowBuilds:
  dsh-tool-notify: true

2. Re-run the installation command and specify the concrete commit SHA:

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

Configuration¶

After the plugin is installed, the default configuration must be overridden using cordis.patch.yml. This file is located in the profile configuration directory, and configuration from later layers overrides earlier configuration.

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

Configuration Items¶

Authentication¶

Never write secrets directly in configuration files. Set tokenRef to the credential name (for example, NTFY_TOKEN), then configure the credential using DSH’s credential provider (environment variables, a .env file, or the UI). The plugin resolves this credential through ctx.credentials on each invocation and supports dynamic refresh.

Typical Usage¶

When the model invokes the notify tool, it passes the following parameters:

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

ntfy Mode¶

When channel is set to ntfy, the plugin sends a POST request to {endpoint}/{topic} with a body containing:

{
  "topic": "...",
  "message": "...",
  "title": "...",
  "priority": "..."
}

Webhook Mode¶

When channel is set to webhook, the plugin sends a POST request directly to {endpoint} with a body containing only the basic information:

{
  "message": "...",
  "title": "..."
}

Return Value¶

Regardless of whether the request succeeds, the tool returns a status object instead of throwing an exception:
* Success: { ok: true, status, channel }
* Failure (non-2xx response): { ok: false, status, channel }
* Network/timeout errors: handled as a tool error.

Use Cases and Considerations¶

• Use cases: Ideal for developers who need to receive real-time notifications through a phone app (with ntfy.sh) or a custom Webhook system after an Agent completes a long-running task or detects an anomaly.
• Considerations:
  • Developer preview: This plugin is currently in developer preview. Breaking changes are expected, so use caution in production environments.
  • Permissions and security: When installing from GitHub source, the allowBuilds configuration means the plugin code is built and run on your machine. Only trust the source code you add.
  • Version pinning: It is recommended to lock the commit SHA during installation to avoid compatibility issues caused by rapid iteration.

Summary¶

dsh-tool-notify provides DeepSeek Harness with a standardized notification outlet. Through simple configuration and model-native tool invocation, an Agent can easily gain the ability to send notifications, enabling a more complete task loop.

• Plugin directory: https://www.skillhub.cn/plugins/rizkirmdhnnn/dsh-tool-notify
• GitHub repository: https://github.com/rizkirmdhnnn/dsh-tool-notify