Introduction

When developing a DeepSeek Harness (DSH) Agent, it is often necessary to monitor its lifecycle states, such as when the Agent becomes idle, is interrupted, requires user input, or exits. When running in the background, developers may have difficulty obtaining these states. The dsh-push plugin provides a mechanism to push Agent lifecycle event notifications to external channels, making monitoring and debugging easier.

What It Is

dsh-push is a DSH plugin maintained by kiim-wong. It forwards Agent lifecycle events (such as idle, interrupted, needInput, and exit) to Bark, Feishu, WeCom, DingTalk, ntfy, or a generic webhook. The plugin is mounted via cordis.patch.yml and does not require modifying DSH core code or writing configuration files.

Installation

Before installing, make sure DSH is installed. Choose the corresponding installation command based on the DSH Profile you are using.

dsh plugin --profile web add dsh-push
dsh plugin --profile headless add dsh-push

If you need to install from GitHub and pin the version, use the following command:

dsh plugin --profile web add github:kiim-wong/dsh-push#<sha>

Note: Installing from Git will run the package’s prepare script. Before the first installation, allow builds in the target Profile’s pnpm-workspace.yaml:

allowBuilds:
  dsh-push: true

Configuration

The plugin uses a JSON-format configuration file. The default path is $DSH_HOME/dsh-push/config.json. You can specify a different path with the DSH_PUSH_CONFIG environment variable.

Configuration values can be referenced from environment variables using the format $VAR or ${VAR}. The log file is written to push.log in the configuration file directory by default.

Each notification channel requires at least a type (channel type) and destination (destination). Sensitive information should be stored in the configuration file or environment variables, not in cordis.patch.yml.

Events and Commands

After the plugin is loaded, it listens for and forwards the following event types:
* idle
* interrupted
* needInput
* exit

The plugin also provides a command-line interface. Even in Headless configurations without a command service, the event listener is loaded normally.

The available commands are as follows:
* /push status: view the push service status
* /push list: list configured channels
* /push get: get a specific configuration
* /push set: set a configuration
* /push enable / /push disable: enable or disable a specific channel
* /push test: test a specific channel
* /push events: list available events
* /push on / /push off: globally enable or disable event listening

Advanced Usage

  • Filtering Idle Events: By setting minDurationSec, you can filter out idle events that last too briefly.
  • Including Subagents: By default, subagent events are excluded. Setting includeSubagents: true includes session header events with origin: "subagent".

Notes and Limitations

  1. Delivery Policy: Notification delivery does not support retries. If delivery fails, the message is lost.
  2. Timeouts and Flushing: Each request has an independent timeout limit, and bounded flushing is used when the process is destroyed.
  3. Meaning of the Exit Event: The exit event indicates that the plugin tree is being destroyed, not that a single Web session is closing.
  4. Content Scope: The notification body contains only a lifecycle summary and does not include specific conversation content.

Summary

dsh-push provides DSH Agent developers with a standardized way to receive lifecycle notifications. By configuring various push channels, real-time monitoring of Agent runtime status can be achieved. Be aware that retries are not supported and the notification content is limited.

Plugin Catalog
GitHub Repository