dsh-monitor

dsh-monitor

Monitor plugin for DeepSeek Harness — background bash watchers that interrupt the agent loop with the captured output (the Monitor() pattern), with a live status bar docked above the composer.

◉ pnpm test --watch            espera /passed/    vigilando · 2m14s  ✕
◉ while ! curl -sf :3000/health …  espera /200/    vigilando · 41s    ✕

What it does

• monitor(command, match?, timeout_ms?, repeat?) — starts a background process and returns immediately. The monitor fires once when the combined output matches the regex, when the process exits, or when the optional timeout expires — and in that moment it injects a steering message into the agent's inbox with the captured output tail, waking the agent even from idle.
• repeat: true — the monitor stays live and refires on every new match (incremental match window + 1.5 s cooldown), in an unbounded chain until stopped.
• monitor_stop(id?) — stops one or all monitors (explicit agent action, no steering).
• Status bar — every row renders live (state, elapsed, fire count, reason tooltip) from a session projection; the ✕ kills the monitor silently.
• Teardown is fiber-owned: stopping the plugin kills live processes and unregisters everything.

Install

npm install @macorreag/dsh-monitor

Then add one row to your composition. Per-session (agent preset, agent.cordis.yml):

- id: monitor
  name: '@macorreag/dsh-monitor'
  inject: ['timer', 'shell', 'tools', 'sessionProjections']

The row-level inject matters: the composition loader resolves service access from the row's options (entry.options.inject), so the services the plugin touches must be declared there even though the module also exports inject. Or globally (host cordis.yml). The plugin publishes no services — it registers the two tools, the monitor session projection, and the web surface.

Sandbox notes

Monitor processes run under the harness process sandbox: read-only filesystem (watch output, don't write files) and the interactive bash tool cannot observe their PIDs. Details in packages/dsh-monitor/docs/sandbox-notes.md.

Status

v0.1.0 — the full behavior matrix (11 routes) was validated live against a running deployment; see docs/test-matrix.md. The static port is in dogfooding.

License

MIT