Preface

In DSH plugin or Agent development, fault paths and recovery behaviors often need to be validated independently. dsh-tool-chaos turns this kind of validation into reproducible experiments: first run a dry-run to confirm matching and boundaries, then decide whether to proceed with actual injection, and output JSON / Markdown reports with a tri-state verdict. Below is an introduction to its positioning, installation, typical usage, and considerations.

What This Is

dsh-tool-chaos is a DSH plugin maintained by cyanseek, licensed under MIT, currently at version 0.1.0-next.0 as a prerelease. It targets the DeepSeek Harness tool pipeline, providing deterministic fault injection, autonomous resilience experiments, and machine-readable evidence.

DSH’s philosophy is “everything is a plugin”; the community directory is a standalone site, not an official app store, and does not imply official affiliation with DeepSeek or High-Flyer.

Since DSH is still in developer preview, pin the version when using dsh-tool-chaos and verify against the tested compatibility matrix.

Core Capabilities

  • Five DSH-native actions: deny, error, delay, abort, block.
  • Reproducible matching and sampling with no runtime randomness.
  • Disabled by default with dry-run, bounded injection, and global wildcard requiring explicit opt-in.
  • Outputs JSON and Markdown reports with structured decision events and a tri-state verdict.
  • Provides a Native Cordis plugin, zero-runtime-dependency CLI, TypeScript engine API, and Codex/Agent Skill surfaces.

Installation and Enablement

The npm prerelease has not been published yet; npx dsh-tool-chaos will only be available after the npm prerelease is published. For now, you can install using a local tarball path:

dsh plugin --profile chaos-demo add ./dsh-tool-chaos-0.1.0-next.0.tgz

After installation, fault injection is disabled by default. The defaults are as follows:

enabled: false
dryRun: true
allowGlobalWildcard: false
rules: []

If you want to install from a pinned GitHub commit, use the pinned form:

dsh plugin --profile chaos-demo add github:cyanseek/dsh-tool-chaos#<commit-sha>

pnpm 10+ may block the prepare script for Git dependencies. If this happens, review the pinned source first, then write the exact package key printed by pnpm into the profile’s pnpm-workspace.yaml.

Typical Usage

First, initialize a patch file:

node bin/dsh-tool-chaos.mjs init .dsh-chaos/retry.patch.yml --preset retry

Then perform a dry-run on a disposable profile:

node bin/dsh-tool-chaos.mjs run \
  --mode dry-run \
  --profile chaos-demo \
  --patch .dsh-chaos/retry.patch.yml \
  --task "Use web_fetch and recover from one transient failure" \
  --expect "expected stable phrase" \
  --no-install \
  --json

This step stays in dry-run. First run the dry-run to confirm that the exact intended match is visible, then decide whether to proceed with the actual experiment.

To integrate with Codex, you can use the Codex plugin installation entry point in the repository:

codex plugin marketplace add /absolute/path/to/dsh-tool-chaos
codex plugin add dsh-tool-chaos@dsh-tool-chaos

For the TypeScript engine API, the entry point is:

import { ChaosEngine, resolveConfig } from 'dsh-tool-chaos/engine'

Applicable Scenarios and Considerations

dsh-tool-chaos is suitable for plugin authors and Agent authors to validate fault paths, recovery behaviors, and retain machine-readable evidence on the DSH tool pipeline. Before using it, note the following:

  • Use disposable profiles, along with synthetic or read-only test inputs.
  • Keep dryRun: true until the exact intended match is visible.
  • Precise global * requires allowGlobalWildcard: true.
  • By default, each rule injects at most once.
  • The runtime plugin does not rewrite arguments, read files, or access the network.
  • abort is cooperative; for same-process tools that ignore AbortSignal, hard-kill is not possible.
  • Production/shared profiles, external mutations, credentials, broad targeting, and privilege changes all require independent safeguards and explicit authorization.
  • Do not represent skipped or unobservable checks as success.
  • The plugin runs with the current dsh process permissions; inspect the source and MIT license before installation.
  • The npm prerelease has not been published; npx dsh-tool-chaos will only be available after the npm prerelease is published.

Conclusion

The value of dsh-tool-chaos is turning “can it recover from faults” from a verbal judgment into reproducible experiments and structured evidence. It is still in prerelease, and is suitable for use in small-scale, controlled DSH toolchains.

The current materials do not provide a directory page URL; GitHub repository: cyanseek/dsh-tool-chaos.