In DeepSeek Harness (DSH), background Jobs typically notify the Agent only when the task ends. For long-running backend services, errors may occur before the process exits. This plugin adds a runtime event channel.

Positioning and Features

dsh-tool-monitor is a plugin maintained by yoke233 and categorized as a web tool. It allows subscribing to already running Bash or PowerShell Jobs and immediately delivering events to the Agent when a backend service errors. The plugin does not start a second business process and preserves the original job_output.

Core features include:
* Subscribing to streaming background Jobs that are already running.
* Preserving the original job_output without starting a second business process.
* Lazily enabling tee to avoid unnecessary polling of the Job.
* Supporting output filtering with JavaScript regular expressions.
* Supporting case sensitivity and timeout settings.
* Compatible with the official job_* tools.

Installation and Enabling

Install the plugin to the specified profile:

dsh plugin --profile web add github:yoke233/dsh-tool-monitor

After installation, start or restart the profile:

dsh --profile web

Typical Usage

First start a backend service normally:

pwsh(command: "npm run dev", run_in_background: true)

The terminal usually returns a Job ID, for example → pwsh-1.

Then have job_monitor subscribe to this Job:

{
  "job_id": "pwsh-1",
  "description": "监听后端错误",
  "pattern": "error|fatal|exception"
}

The terminal returns the Monitor’s Job ID, for example → monitor-1.

At this point, monitor-1 only subscribes to the output of pwsh-1. Once the specified regular expression matches, the plugin delivers a session event to the owning Agent; the original service always runs as a single instance.

How It Works

The plugin extends DSH’s JobRegistry (compatible with the official LocalJobRegistry) and reuses semantics such as ownership isolation, waiting, cancellation, and completion notification.

  • Lazy reading: The Monitor reads data by lazily enabling the tee mechanism; unsubscribed Jobs retain the official reading path.
  • Lifecycle: The Monitor itself is also a normal Job.
    • job_list displays both the target Job and the Monitor.
    • job_output reads the raw output of the target Job and the matching output of the Monitor respectively.
    • job_kill monitor-1 only stops the subscription and does not terminate the target Job.
    • When the target Job ends, the associated Monitor ends automatically and flushes the last incomplete output line.

Tool Parameters

Parameter Required Description
job_id Yes The id of an existing streaming background Job, usually from bash or pwsh with run_in_background: true
description Yes A short description displayed in Monitor notifications
pattern No A JavaScript regular expression, matched against complete output lines
case_sensitive No Whether matching is case-sensitive; defaults to false
timeout_ms No Subscription time limit; by default it continues until the target Job ends

Compatibility and Boundaries

  • Output format: Supports LF output from Bash and CRLF output from PowerShell.
  • Job type: Only supports background Jobs that expose a streaming readOutput(); non-streaming background Jobs are not supported.
  • Session isolation: Cannot monitor Jobs of other Agents across sessions; ownership validation is still performed by the DSH Registry.
  • Persistence: Jobs and Monitors are in-process state in the Host process and are not persisted across DSH Host restarts.
  • Historical Jobs: Historical Jobs created before installing the plugin cannot be retroactively subscribed to.
  • Buffering: Buffers have a limit set in UTF-8 bytes, and when drops occur, job_output displays an explicit notice.

Summary

dsh-tool-monitor provides a lightweight solution for capturing backend service errors in real time in DSH Agent environments. By reusing the official Job ecosystem, it adds runtime monitoring capabilities without changing the logic of the original business process.