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