dsh-tool-notify

Readme

# dsh-tool-notify

A [DeepSeek Harness](https://github.com/deepseek-ai/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)

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

### From GitHub (sources — build runs at install)

```sh
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`:

```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

```sh
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`):

```yaml
- 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:

```jsonc
{
  "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

```sh
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