Preface¶

In DSH scenarios, a failure often isn’t just a single line of error. It might occur during a tool call, at turn end, or as an Agent runtime error, and diagnosing it requires understanding what happened before the failure, the project’s state at that time, the runtime environment, and the plugin combination. Ordinary error logs often only show “where it finally blew up.”

dsh-failure-capsule is a DeepSeek Harness plugin maintained by YiHarvest, licensed under MIT. It generates a sanitized ZIP evidence package upon tool or Agent failure. It has been verified against the native session/event and agent/error interfaces of @deepseek-ai/dsh@0.1.0-rc.7.

What This Is¶

dsh-failure-capsule is a local-first failure evidence packaging plugin. After a failure occurs, it consolidates relevant signals into a ZIP and writes it to a local directory.

It does not modify the Harness core, does not upload data, and does not call models to diagnose failures.

Core Features¶

Below are its default behaviors and capabilities:

• Generates a failure evidence ZIP on tool/result with isError=true, turn/end / error, turn/end / blocked, turn/end / interrupted, and agent/error. turn/end / aborted does not trigger by default but can be enabled via configuration.
• Local-first: ZIPs are written only to the local machine; no network requests or telemetry backends.
• Redacts sensitive fields, credentials, tokens, AWS access keys, environment variable assignments, URL user passwords, private key blocks, and local paths by default.
• Captures Git evidence, runtime information, Loader plugin manifests, and a bounded Session Event timeline.
• Can deobfuscate minified JS stack frames if local source maps are available.
• Supports configuration overrides via cordis.patch.yml.

There are also boundaries on collection and triggering:

• The timeline includes a maximum of 80 events by default.
• Each Git command is limited to 512 KiB by default; hitting the budget terminates the command and explicitly marks the truncation.
• Git commands are executed directly via argument arrays, not through a shell; they do not read untracked file contents, nor do they run hooks or textconv.
• The same Session Event is only packaged once within a plugin lifecycle; agent/error briefly waits for the corresponding turn/end to avoid packaging the same failure twice.
• Misconfigurations fail immediately at plugin load time, with no silent fallback.
• On plugin unload, it waits for any started evidence package writes to complete.

Installation and Enablement¶

Requires Node ^22.19.0 || >=24.0.0.

Web and headless are two separate profiles and need to be installed individually:

dsh plugin --profile web add dsh-failure-capsule
dsh plugin --profile headless add dsh-failure-capsule

After installation, first check the composition-layer configuration:

dsh --profile web --dump-config

The output should include:

id: failure-capsule
name: dsh-failure-capsule

If validating with a local tarball:

dsh plugin --profile web add ./dsh-failure-capsule-0.2.1.tgz
dsh --profile web --dump-config

Typical Usage¶

Install the plugin first, then use DSH as usual. After a failure occurs, the plugin writes the evidence package to the default location:

.dsh/failure-capsules/

You can review it by following these steps:

1. Identify the failure type: a tool/result tool failure, a turn/end turn failure, or an agent/error.
2. Open the corresponding ZIP and examine the Session Event timeline, Git evidence, runtime information, and Loader plugin manifests before and after the failure.
3. If the failure includes a minified JS stack, review the stack frames after local source map deobfuscation.
4. Manually inspect the ZIP contents before sharing, especially free-text fields, source code diffs, and custom plugin events.

To adjust configuration in a specific profile, you can override the entire configuration block in that profile’s cordis.patch.yml using row id failure-capsule.

Applicable Scenarios and Considerations¶

This plugin is suitable for scenarios requiring offline investigation of DSH tool failures, turn failures, or Agent runtime errors. It keeps evidence local, does not upload data, and does not call models to diagnose failures.

Points to note before use:

• The plugin runs with the permissions of the current dsh process; review the source code and license before installation.
• Automatic redaction does not guarantee the absolute absence of business secrets in the ZIP; manual inspection is still required before sharing.
• Requires Node ^22.19.0 || >=24.0.0.
• Verified against the native session/event and agent/error interfaces of @deepseek-ai/dsh@0.1.0-rc.7; compatibility and security should still be judged based on reproducible tests and source code review.
• Listing in directories like the Awesome DSH Plugins Radar only indicates discoverability, not compatibility or security endorsement.

Conclusion¶

dsh-failure-capsule consolidates pre-failure events, project state, runtime information, and plugin combinations into a local sanitized ZIP, making it suitable for offline failure post-mortems within DSH profiles.

Repository: https://github.com/YiHarvest/dsh-failure-capsule