Introduction¶

DSH’s plugin system breaks capabilities into multiple plugins, but issues such as incomplete plugin declarations, tasks looping in place, deeply nested sub-agents, and host restarts interrupting sessions all affect executing tasks.

akira399/dsh-guardian provides detection and guidance for these situations: instead of directly terminating tasks, it guides the Agent to adjust direction by injecting user/message, while also providing preflight checks, status queries, and event log entry points.

What is it¶

Its positioning is: to provide detection and guidance via plugin preflight, loop detection, recursive protection, and interrupt awareness, never terminating tasks. package.json declares the runtime environment as node >=20.

Core Features¶

Plugin Preflight¶

Plugin preflight is used to check if service declarations in plugin source code are consistent with usage. It statically analyzes ctx.<service> usage against inject declarations, identifying missing services like timer, tools, settings, and provides fix suggestions.

The preflight command is as follows:

node <dsh-guardian>/scripts/preflight.mjs <plugin directory or index.js>

It can also be called within code:

import { scanSource } from "dsh-guardian/preflight";

Loop Detection¶

Loop detection focuses on whether the same tool call occurs repeatedly.

When the same tool call, judged by “name + parameter fingerprint”, repeats within a sliding window up to maxLoopRepeats, the plugin determines it as a loop, then injects a direction-change prompt and records LOOP_DETECTED.

Recursive Protection¶

Recursive protection focuses on the nesting depth of sub-agents and workflows.

When the nesting depth of a sub-agent or workflow exceeds maxSubagentDepth, the plugin injects a convergence prompt and records RECURSION_DETECTED.

Interrupt Awareness¶

Interrupt awareness provides current session runtime information via status routing.

Status routing returns:

running
busy
Nesting depth
Recent call count
safeToRestart

Among them, safeToRestart is used to determine if restarting is suitable at the moment. The safety restart helper in the documentation checks this field first: if there is a running session, it refuses to restart unless -Force is used.

Event Logs and Status Queries¶

Events are written to guardian/events.jsonl. The local viewing path provided in the documentation is:

~/.dsh/guardian/events.jsonl

Status routing can query the last 50 events.

No Task Termination¶

The core behavior of dsh-guardian is guidance, not termination.

It guides the Agent to adjust direction by injecting user/message and does not actively end the task.

Installation and Enablement¶

Since the plugin runs with the permissions of the current dsh process, it is recommended to check the source code and license before installation.

After confirming the environment meets node >=20, execute the installation command:

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-guardian

The plugin is enabled by default. Configuration changes take effect immediately, no restart needed.

Typical Usage¶

Running Plugin Preflight¶

Run preflight on a specific plugin directory or entry file:

node <dsh-guardian>/scripts/preflight.mjs <plugin directory or index.js>

Calling Preflight in Code¶

If you need to perform static checks in your own toolchain, you can import the preflight module:

import { scanSource } from "dsh-guardian/preflight";

Checking Status¶

Status routing is as follows:

GET /api/dsh-guardian/status

The documentation also provides specific address examples:

GET http://127.0.0.1:3080/api/dsh-guardian/status

The return content includes running, busy, nesting depth, recent call count, and safeToRestart, and allows querying the last 50 events.

Safety Restart Helper¶

The safety restart script checks safeToRestart first. If there is still a session running, it refuses to restart unless -Force is used.

Command example:

powershell -NoProfile -ExecutionPolicy Bypass -File <dsh-guardian>\scripts\safe-restart.ps1

The documentation only mentions that force restart can be done with -Force, without providing the complete command.

Configuration Example¶

The guardian configuration in settings.yaml is as follows:

guardian:
  maxLoopRepeats: 4
  maxSubagentDepth: 3

Configuration changes take effect immediately, no restart needed.

Viewing Event Logs¶

Event log path example:

~/.dsh/guardian/events.jsonl

The documentation shows the event log path appearing as both $DSH_HOME/guardian/events.jsonl and ~/.dsh/guardian/events.jsonl, the relationship between them is unclear.

Running Verification¶

The verification command provided in the documentation:

pnpm verify

Applicable Scenarios and Notes¶

Suitable for people who need to manage DSH plugins, check plugin declarations, observe long-running task status, and want to confirm if a session is safe before restarting.

Usage notes:

The plugin runs with the permissions of the current dsh process, so check the source code and license before installing.
dsh-guardian only does detection and guidance, it does not terminate tasks.
The documentation does not confirm plugin classification and star count.
The directory page link comes from leads, not scraped from the directory page body.
The documentation for safe-restart.ps1 force restart only mentions adding -Force, not the complete command.

Conclusion¶

The value of dsh-guardian lies in turning common risk points in DSH task execution into a checkable, observable, and guided protection path: plugin preflight, loop detection, recursive protection, interrupt awareness, and safety restart checks. It does not provide task termination actions, but helps Agents and developers keep tasks under control through prompts and event logging.

GitHub:
https://github.com/akira399/dsh-guardian

Directory Page (leads, body not scraped):
https://www.skillhub.cn/plugins/akira399/dsh-guardian

dsh-guardian: DSH Task Protection Plugin