dsh-plugin-monitor

An event monitor for DeepSeek Harness: arm a background
watch — a shell command or a WebSocket — and every stdout line (or text frame) is delivered to
the owning agent session as an asynchronous event. The agent keeps working or goes idle;
inference happens only when something actually arrives.

Modeled on Claude Code's Monitor tool. The motivating use case is real-time agent-to-agent
messaging (e.g. Grapevine channels), where the alternative — a timed self-wakeup loop — costs a
model turn per empty poll and adds up to a full interval of latency per message.

Status

Working, and verified end to end. A DeepSeek Harness agent has held a live conversation over a
grapevine channel through this plugin — woken per message without polling, with batching, labels,
and job_kill all confirmed against a real dev profile. See the acceptance scenario and its
result in docs/design.md.

What dsh already has, and what this adds

The dsh background-job runtime (ctx.jobs) already owns job ids, cancellation, incremental
reads (readOutput() / job_output), and wake-on-completion for an idle owner. Separately,
agent.inject() appends context to the next model request — explicitly not a wake-up.

This plugin extends that from completion-only to per-output event. Delivery is
agent.send(event, 'next-step', true) — the runtime's waking send, which folds an event into
ongoing work and opens a turn when the owner is idle. The registry has no per-output
notification and needs none: the producer owns the stream in-process. Around that sit the
operational details that make it survivable:

• line/frame granularity — each output line is one event
• short-window batching (~200ms) so multi-line bursts arrive as one notification
• rate limiting with auto-kill on firehoses
• a per-monitor label carried in every notification
• timeout by default, opt-in session-length persistence, stoppable via job_kill

Development

Bun + Biome for local development (the published package is plain JS in dist/, so this is
invisible to consumers):

bun install
bun run build     # tsc → dist/
bun run check     # biome

Install into a dsh profile from a local checkout — note dsh plugin add forwards to pnpm
on the consumer side, and git installs need the prepare script allowlisted in the consumer's
pnpm-workspace.yaml; neither constrains this repo's own tooling:

dsh plugin --profile dev add /path/to/dsh-plugin-monitor

Add it to the profile you actually boot — the web UI runs the web profile, so installing
into dev and then launching the web UI is a correct command aimed at the wrong target. Verify
before launching:

dsh --dump-config | grep monitor

Tuning the delivery budgets

Optional. The defaults are the policy for almost everyone; override only if a
source legitimately needs more headroom, as a config: block on the profile entry:

- id: monitor
  name: dsh-plugin-monitor
  config:
    maxEventBytes: 32768 # bytes in one delivered event (default 16 KiB)
    throttleBytes: 262144 # bytes per 10s before throttling (default 128 KiB)
    killBytes: 1048576 # bytes per 10s before the monitor is stopped (default 512 KiB)
    spillBytes: 524288 # capacity for event-clipped output (default 256 KiB)

Config is validated at load, so a mistyped budget fails the boot rather than the
first overflowing event. Output clipped from an event is recoverable with
job_output <id>; the event says how many bytes were delivered and which spill
block holds the rest.

If tool calls start failing after installing this

A symptom worth recognising, because it looks like this plugin and is not:

Cannot read properties of undefined (reading 'prepare')

Every tool call in the profile fails, including ones unrelated to this plugin. It means two copies
of @deepseek-ai/dsh-tools are loaded: its dispatcher is keyed by a module-local Symbol(), so
the copies cannot see each other's scheduler. This is a known upstream issue —
deepseek-harness discussions #1849,
#3033,
#2078.

This package declares no runtime dependencies precisely to avoid causing it. If it happens anyway,
check for a rival copy and remove or link it:

ls $DSH_HOME/profiles/<name>/node_modules/@deepseek-ai

It is most likely when the harness is installed globally rather than under $DSH_HOME.

Layout

• src/index.ts — plugin entry (name, inject, apply); registers the monitor tool and
  the system-prompt section that tells the model events arrive unprompted
• src/events.ts — batching, rate limiting, and waking delivery to the owning agent
• src/command.ts — shell-command producer (own process group, so cancel kills pipelines)
• src/websocket.ts — WebSocket producer (one event per text frame)
• src/lines.ts — line splitting across chunk boundaries
• cordis.patch.yml — configuration layer applied when the bundle is added to a profile
• docs/design.md — design notes and open questions

References

• Plugin development guide
• Tool authoring
• Tool authoring cookbook (background work)
• Background job runtime design note