dsh-status-plugin

Usage

The plugin registers two exact routes on the profile's web server:

GET /api/status          # JSON snapshot on demand
GET /api/status/events   # Server-Sent Events stream

GET /api/status

Example response:

{
  "ok": true,
  "timestamp": "2026-08-14T03:50:00.000Z",
  "host": {
    "hostname": "host",
    "platform": "linux",
    "arch": "x64",
    "nodeVersion": "v22.23.2",
    "pid": 23185,
    "cwd": "/root/.dsh",
    "uptimeSeconds": 3600,
    "loadAvg": [0.1, 0.1, 0.1],
    "memory": { "rss": 123456, "heapTotal": 654321, "heapUsed": 432100, "external": 12345 },
    "lanAddresses": ["192.168.5.227"]
  },
  "webServer": {
    "host": "0.0.0.0",
    "port": 3080,
    "url": "http://localhost:3080"
  },
  "apiKey": {
    "configured": true,
    "source": "env"
  },
  "plugins": {
    "entries": [
      { "entryId": "llm", "moduleName": "@deepseek-ai/dsh-llm", "enabled": true, "fiberPhase": "active" }
    ]
  }
}

Fields

Field	Source
host.*	process + node:os (pid, uptime, memory, load, LAN IPv4 addresses)
webServer.*	ctx.webServer (bind host and actual listening port)
apiKey	DEEPSEEK_API_KEY in process.env, else the working directory .env, ~/.env, or $DSH_HOME/.env (checked in loadLayeredEnv priority order) — presence only, never the value
plugins.entries	ctx.pluginInventory.list() (live Cordis Loader entry state)

The API key check reports only whether a key is configured and where it was found; the value itself never leaves the process.

GET /api/status/events (SSE)

The host pushes to open browser streams — the server decides when the page needs new state, so idle pages make zero requests:

• snapshot — a full status snapshot, emitted immediately on connect and then every heartbeatMs (default 30 s). Each snapshot card dissects to loadAvg and memory fields inside host.* for alert-driven UIs.
• alert — emitted when an indicator crosses its threshold (entering alert) or recovers (leaving alert). Emitted on every transition and re-synchronized on connect so a page that opens mid-alert still learns about it:

event: snapshot
data: {"ok":true,"timestamp":"...","host":{...},"plugins":{...}}

event: alert
data: {"active":true,"reason":"load","value":4.39,"threshold":2}

Default thresholds (configurable via the plugin config in the profile's cordis.yml):

Config	Default	Meaning
loadWarning	2	1-minute load average above which an overload alert fires
memoryWarning	0.85	RSS share of total memory above which a memory alert fires
heartbeatMs	30000	snapshot push interval
checkIntervalMs	5000	alert monitor sampling interval

The browser side subscribes with a native EventSource (auto-reconnects on drop) and renders:

• a compact badge in the conversation header (status dot + uptime, click to open);
• a detail panel with process/resource/service/plugin sections and the last update time;
• a toast on every alert transition (auto-dismisses after 6 s) plus a pulsing badge while an alert is active.

Failure behavior

• A collection error inside the handler returns 500 with { "ok": false, "error": "" } — structured, no stack leak, never a hung socket.
• pluginInventory is optional: when the service is absent, plugins.entries is [] rather than an error.
• Responses carry cache-control: no-store (runtime data must not be cached); the SSE stream uses text/event-stream with x-accel-buffering: no.