dsh-plugin-safety: Plugin Health Alerts and Automatic Repair

DSH (DeepSeek Harness) adopts an “everything is a plugin” philosophy. As the plugin ecosystem expands, managing plugin health becomes a necessary part of daily operations. Plugins may fail due to missing dependencies, code errors, or configuration issues. dsh-plugin-safety provides the final two layers of failure prevention and control: pre-start validation and runtime automatic repair.

What It Is¶

This is a DSH plugin maintained by Seryta. Its core function is plugin health alerting: failed pre-checks automatically disable the plugin and persistently display a page-level alert; alerts for unavailable plugins automatically create a headless repair session.

• License: MIT
• Dependencies: Zero third-party dependencies; only uses the Node/Python standard libraries

Core Features¶

1. Automatic disabling and persistent alerts on pre-check failure: Before dsh-web starts, the pre-check script inspects plugins that are not disabled in the profile. For plugins that fail to import, it automatically writes disabled: true (or removes the bundle if it is a bundle), and persists the alert.
2. Persistent alerts + automatic repair session creation: The browser side renders a red alert card that reappears after refreshing or reopening the page. The Host side creates a repair session for each alert action before returning the alert.
3. Consistent repair: Whenever an alert indicates that an “unavailable plugin has been disabled / requires manual handling,” the Host side automatically creates a repair session. This rule applies regardless of whether the alert comes from the pre-check script or is written directly to notice.json.

Working Principles¶

The Host side and Client side are separated. Before returning alerts through GET /plugins/dsh-plugin-safety/notice, the Host side checks whether fixActionIds covers all actions. If it does not, it calls check-profile-plugins.py --ensure-fix to start a repair session.

To prevent duplicate concurrent startup, the system uses a file lock mechanism. Repair sessions are headless tasks, and their failure does not block the Host.

Components¶

Alert File¶

Alert data is stored in $DSH_HOME/storages/plugin-safety/notice.json (defaults to ~/.dsh/storages/plugin-safety/notice.json).

{
  "at": 1786799000000,
  "actions": [
    {
      "id": "some-plugin",
      "name": "some-plugin",
      "kind": "patch",
      "reason": "Cannot find package 'some-plugin'",
      "disabledAt": 1786799000000,
      "autoDisabled": true,
      "profile": "/home/me/.dsh/profiles/web"
    }
  ],
  "fixStartedAt": 1786799001000,
  "fixActionIds": ["some-plugin"],
  "fixWorkspace": "/home/me/.dsh/plugin-maintenance",
  "fixLogFile": "/home/me/.dsh/plugin-maintenance/plugin-safety-fix.log"
}

Users can clear the alert via POST to the same endpoint. The file is reset to {"at": 0, "actions": []}; the next new alert will be regenerated.

Installation and Enablement¶

Install using the DSH plugin command:

dsh plugin --profile web add github:Seryta/dsh-plugin-safety

After installation, restart dsh-web (the Host side requires the process to import again; the Client side is a static service, and refreshing the page before restart can also load the new logic).

Pre-Start Check (Recommended)¶

Place the bundled script under $DSH_HOME/scripts and hook it into systemd ExecStartPre:

mkdir -p ~/.dsh/scripts
cp ~/.dsh/profiles/web/node_modules/dsh-plugin-safety/scripts/check-profile-plugins.py \
   ~/.dsh/scripts/check-profile-plugins.py

Add the following to the systemd service configuration:

ExecStartPre=-/home/<you>/.dsh/scripts/check-profile-plugins.py

The - prefix means that pre-check failure does not block startup; the script returns 0 for failures that can be automatically disabled, and returns 1 for failures that cannot be automatically disabled and require manual handling.

Verification¶

npm test                       # host/script/client logic tests; all use a fake dsh and do not create real sessions
node --check index.js
python3 -m py_compile scripts/check-profile-plugins.py

Notes¶

• Browser Polling Mechanism: The browser only polls once on page load; alerts newly written while the page remains open will appear on the next refresh.
• Headless Task: The automatic repair session is a headless DSH task; if it cannot repair itself, it reports the blocking reason within the session, and the Host does not block or retry.
• DSH_HOME: Both the Host and pre-check script consistently respect $DSH_HOME; systemd pre-check typically does not set this variable, so the default ~/.dsh is used.

Summary¶

dsh-plugin-safety addresses automated recovery when plugins fail by using script pre-checks and automatic repair sessions. It relies on no third-party libraries, keeping it lightweight. After installation, restarting the service is enough to take effect; for stricter pre-start checks, refer to the ExecStartPre integration example above.

GitHub repository | Plugin directory