dsh-shadow-mind
Parallel cognitive runtime for DeepSeek Harness (DSH / Cordis).
This project is a DSH plugin implementation of pi-shadow-mind. The plugin runs multiple "Shadow Mind" agents beside the main agent to provide independent reviews, fact-checking, and parallel cognitive work: after each main-agent turn, a heartbeat scheduler randomly activates configured shadows, each with its own responsibility, tool allowlist, and run timeout.
> Status: functional prototype. Core heartbeat scheduling, restricted-tool shadow agents, per-run timeouts, lifecycle cleanup, and management tools work end-to-end. See Known Limitations below.
Relation to pi-shadow-mind
- Original project: https://github.com/liuzhengdongfortest/pi-shadow-mind
- This repository is a DSH plugin (dsh-plugin) implementation of pi-shadow-mind: the shadow-mind concepts are reimplemented on the DSH/Cordis runtime as an independent package — not a fork, and not a line-by-line translation.
- DSH uses different primitives (continuable subagents, native background notices, and the Cordis plugin model), so the implementation adapts the original design to them.
Features
- Heartbeat scheduling: After each main-agent turn, randomly activates configured Shadow Minds.
- Restricted-tool shadows: Each shadow receives a sanitized main-session trajectory and an explicit tool allowlist. The default allowlist is read-only; configuring other tools can broaden that access.
- Per-run timeout:
timeout_seconds(or the config default) bounds each shadow run; an expired run is interrupted and its slot is released. - Lifecycle cleanup:
subagent/endremoves finished shadow runs, so slots andactivecounts stay accurate within an epoch. - Management tools: Create, update, delete, list, enable, and disable shadow definitions via model tools. Persistent writes are gated behind the DSH approval service when one is mounted.
- Config tools: Read and write the global configuration via model tools (writes validate the merged result before persisting).
- Pause/resume/epoch:
/shadow pauseand/shadow resume; pausing also aborts running shadows. New user input increments the epoch and cancels running shadows from the previous epoch. - Auto toggle:
/shadow auto on|offactually enables/disables heartbeat activation. - Tool-call argument redaction: Tool-call arguments are redacted before being forwarded to shadows (credentials are not leaked). Tool results are summarized.
Installation
DSH plugins are loaded through a Cordis composition (profile or agent preset).
1. Install the package into a DSH profile
dsh plugin --profile web add @winterchenhuan/dsh-shadow-mind@latest
For local development, build the package before adding the directory so dist/index.js exists:
cd /path/to/dsh-shadow-mind
npm install
npm run build
dsh plugin --profile web add /path/to/dsh-shadow-mind
The profile stores the local package as a path dependency; rerun npm run build after source changes, then restart DSH.
The current repository version is 0.1.7. The @latest suffix makes the add command re-resolve to the newest published version; a bare add keeps the range already recorded in the profile (e.g. ^0.1.6) and the lockfile-pinned version, so it will not upgrade an existing installation. To test an unpublished checkout, use the local-directory procedure above.
The package ships a cordis.patch.yml. The profile loader reads the package's dsh.bundle.patch manifest and applies it automatically; no manual profile cordis.patch.yml editing is needed.
2. Restart DSH
Restart DSH and the plugin will be loaded. The package exports a default Cordis plugin factory from dist/index.js.
Configuration
Global configuration is a user-settings namespace: the single source of truth is the shadow-mind: section of ~/.dsh/settings.yaml. It can be edited from three places that stay in sync:
- Settings page: DSH Web 设置页的「可配置插件」里有一张 Shadow Mind 卡片，按字段编辑、保存即写入（支持覆盖标记与重置）。
- Model tools:
write_shadow_config/read_shadow_config（写入前需要用户批准）。 - Manual edit: directly edit the
shadow-mind:section of~/.dsh/settings.yaml; changes are picked up live.
Shadow definitions (Markdown) still live in:
$DSH_HOME/agent/shadow-minds/
├── grounded-reviewer.md
├── requirement-keeper.md
└── ...
$DSH_HOME defaults to ~/.dsh (honoring the DSH_HOME environment variable), so the default location is ~/.dsh/agent/shadow-minds/.
Example settings.yaml section (fields absent from the section fall back to schema defaults):
shadow-mind:
heartbeatProbability: 0.33
maxParallelShadows: 2
defaultShadowTimeoutSeconds: 120
defaultThinkingLevel: low
Field reference:
| Field | Default | Meaning |
|---|---|---|
heartbeatProbability |
0.333… |
Per-turn activation probability per eligible shadow, 0..1 |
maxParallelShadows |
2 |
Concurrently running shadows, 1..8 |
defaultShadowTimeoutSeconds |
300 |
Per-shadow run timeout when the definition sets none |
headlessDrainTimeoutSeconds |
120 |
Grace window for settling children at shutdown |
resultBatchWindowMs |
400 |
Window coalescing multiple reports into one wakeup |
defaultShadowModel |
(unset → main model) | Model used when a shadow declares none |
defaultThinkingLevel |
low |
minimal / low / medium / high |
randomSeed |
(unset → random) | Deterministic heartbeat RNG seed; applies to the next session |
Legacy config.json migration
An old $DSH_HOME/agent/shadow-minds/config.json is imported into the settings section automatically on the first startup after upgrading, then renamed to config.json.migrated so it cannot resurrect stale values later. A file that fails validation is renamed aside too — the plugin keeps running on defaults and the values survive inside the .migrated copy.
The timeout and heartbeat fields are active. headless_drain_timeout_seconds, result_batch_window_ms, and default_thinking_level are accepted for configuration compatibility but are not active yet; see Known Limitations.
Example shadow definition grounded-reviewer.md:
---
id: grounded-reviewer
name: Project Grounding Checker
enabled: true
activation_probability: 0.6
run_with_model: openai/gpt-5-mini
thinking_level: low
tools:
- read
- grep
- glob
---
Check whether the main agent's claims are supported by the current workspace. If nothing is worth reporting, reply exactly: NOT_RELEVANT.
Usage
After installation, restart the target profile and start DSH Web normally:
dsh web
(dsh --profile web is equivalent.)
In the Web UI, continue using the main agent. Shadow activations happen after main-agent turns according to the configured probability. Use /shadow status first to confirm the plugin loaded and to see registry/config diagnostics.
Typical flow:
/shadow status— confirm the plugin loaded and see the current state./shadow list— see which shadows are defined and enabled./shadow probe grounded-reviewer— manually run one shadow once to check it works.- Shadows then activate automatically after main-agent turns (heartbeat), as long as auto mode is ON.
Commands
Use the single /shadow umbrella command:
/shadow status
/shadow probe [tools]
/shadow list
/shadow clean
/shadow auto
/shadow pause
/shadow resume
| Command | Purpose |
|---|---|
/shadow status |
Show the current state: active/paused, auto mode, epoch, running shadow count, event count, plus config/registry diagnostics. |
/shadow probe [tools] |
Manually run one shadow once without waiting for a heartbeat. ` selects the shadow (omit it to pick a random enabled one). Optional comma-separatedtools` overrides that shadow's tool allowlist. |
/shadow list |
List all shadow definitions: enabled/disabled, activation probability, and tool allowlist. |
/shadow clean |
Abort all currently running shadows and release their slots. |
/shadow auto |
Enable/disable heartbeat activation. off stops random activations; already-running shadows are not affected. |
/shadow pause / /shadow resume |
Pause/resume the whole shadow system for the current session. Pausing also aborts running shadows. A new user message (new epoch) also stops shadows left over from the previous epoch. |
Management Tools
These are registered as model-callable tools:
list_shadowscreate_shadowupdate_shadowdelete_shadowenable_shadowdisable_shadowtrigger_shadowread_shadow_configwrite_shadow_config
Known Limitations
The following areas are not fully implemented yet:
| Area | Status |
|---|---|
| Independent Shadow AgentSession | Partial: DSH continuable subagents are used instead of a separate agent session. |
report_to_main tool |
Missing: DSH native background notices are used instead. Report batching and steer/followUp are not yet replicated. |
| Tool allowlist resolution | Simplified: missing-tool reporting and report_to_main injection are not implemented. |
| Per-shadow model auth check | Missing: run_with_model is passed as agentOptions, but auth validation is not performed. |
Per-shadow timeout_seconds |
Enforced: each run is bounded by timeout_seconds or default_shadow_timeout_seconds; expired runs are interrupted and their slots released. |
Per-shadow thinking_level |
Not applied: DSH uses reasoning effort, which is not yet mapped. |
| Shutdown drain / headless mode | Missing: no headless drain on process shutdown. |
| UI status panel / message renderer | Partial: a Client indicator exists in the dynamic prototype; the real package currently only exposes /shadow. |
| Debug session logs | Not needed: shadow runs are DSH continuable subagents, and DSH Web already shows their execution (trajectory, tool calls, results) live. The debug frontmatter field was removed accordingly. |
| Test suite | Minimal: vitest suite covers the pure scheduling, parsing, serialization, config, and drain logic; no harness integration tests yet. |
See DESIGN.md for the project's design goals; some of them are not fully implemented yet.
Development
npm install
npm run typecheck
npm run verify # typecheck + unit tests
npm run build
npm pack runs prepack (i.e. npm run build) automatically, so a release tarball always contains dist/index.js.
License
MIT
