Introduction

In agent runtimes like DSH, tool call failures are not uncommon. More troublesome is that the failure reasons might not change, only the parameters change, yet the model continues to retry.

dsh-failbook addresses this with a layer of recording and interception: it writes tool call failures into a ledger, clusters them by failure reason, and injects suggestive reminders when the same failure signature repeats. It does not replace tool execution, nor does it modify tool results; it only provides visible records during failures and context for the next round of requests.

What is it

dsh-failbook is a DeepSeek Harness (DSH) plugin for recording tool call failures, clustering them by failure signatures, and intercepting failure-aware retries upon repetition. The plugin includes a Web UI settings panel, is MIT licensed, and is zero-configuration out of the box.

The repository address is G1en-114/dsh-failbook.

Key Features

Below are the main capabilities it is confirmed to provide:

  1. Automatic recording of tool call failures
    Including structured errors, non-zero exit codes, sandbox rejections, and common error text.

  2. Failure signature clustering
    The same failure reason is grouped into the same bucket; they are not scattered across multiple entries just because of different parameters.

  3. Cross-session persistence
    Stored via the official ctx.storageDomain, it persists across sessions; it automatically degrades to an in-memory ledger if that service is unavailable.

  4. Failure-aware retry interception
    When the same signature fails within a recent window reaching a threshold, a suggestive reminder is injected.

  5. Web UI Panel
    The settings page provides a failure ledger panel to view top failure signatures, counts, recent window, and last time, with support for mute, single delete, and clear.

  6. Muting and Exclusion
    False positive buckets can be muted with one click, or controlled more finely via excludeTools / patterns.

  7. Conservative Detection
    The design principle is to prefer missing a detection over a false positive; it only recognizes concrete failure markers.

Installation and Activation

Installation command:

dsh plugin --profile web add "github:G1en-114/dsh-failbook#main"

This command adds the plugin to the DSH configuration for the web profile.

If you do not use the installation command, you can also manually edit cordis.patch.yml in the config directory and insert the following content:

- insert:
    - id: failbook
      name: dsh-failbook
      config:
        enabled: true

After restarting dsh web, open:

Settings → Failure Ledger

You will be able to see the failure ledger panel.

Typical Configuration

The plugin is enabled by default. Confirmed default configurations include:

enabled: true
retryGuardThreshold: 2
reminderCooldownSec: 300
reminderLocale: "zh"
exitFailureMin: 2
excludeTools:
  - todo_write
maxBuckets: 1000

Several key items:

  • enabled: Total switch.
  • retryGuardThreshold: Trigger a reminder when the same signature fails that many times within the recent window.
  • reminderCooldownSec: Minimum cooldown time between two reminders for the same bucket.
  • reminderLocale: Reminder text language, e.g., "en" can be used here.
  • exitFailureMin: Only recorded as a failure when the exit code reaches this value.
  • excludeTools: List of tools not to track.
  • maxBuckets: Upper limit on the number of ledger buckets; evicts by most recent use when exceeded.

If you want the interception to be more aggressive, you can change it to:

- insert:
    - id: failbook
      name: dsh-failbook
      config:
        exitFailureMin: 1
        retryGuardThreshold: 1
        reminderLocale: "en"

This example includes exit code 1 in failure judgment and lowers the threshold for triggering a reminder to 1 time.

Runtime Behavior and Boundaries

Reminders from dsh-failbook are injected via additionalContexts. It does not modify tool results nor interrupt the tool execution pipeline; it only provides visible context when the model makes the next round of requests.

It also has several clear security boundaries:

  • Web API is accessible only on loopback addresses.
  • The ledger only saves truncated previews.
  • Full command output does not leave the host.
  • When ctx.storageDomain is unavailable, it automatically degrades to process-in / in-memory ledger. After degradation, recording and interception functions remain unchanged, but data is cleared on restart.

Development and Verification

The repository provides commands for local development and verification:

npm install
npm test
npm run test:integration
npm run build

npm test is used to run tests, npm run test:integration for integration verification, and npm run build for building.

Visible dependencies in package.json include:

"@deepseek-ai/schemastery": "^3.18.1",
"zod": "^4.4.3"

The peerDependencies in the materials are incomplete, so this article does not supplement the complete dependency list based on that.

Use Cases and Notes

It is suitable for these use cases:

  • Using DSH Web configuration and wanting to see a failure record panel.
  • Wanting to turn tool failures from temporary logs into a queryable ledger.
  • Wanting to reduce the model retrying repeatedly on similar errors.
  • Needing to mute and exclude certain tools or error patterns.

Notes before use:

  • The plugin runs on the DSH host side and runs with the current dsh process permissions.
  • You should check the source code, dependencies, and license before installing.
  • License is MIT.
  • If you rely on cross-session persistence, you need to confirm whether the current environment provides ctx.storageDomain; otherwise, it will degrade to an in-memory ledger.

Conclusion

The value of dsh-failbook lies in transforming “tool failures” into a ledger record that is trackable, aggregable, and remindable. It does not change DSH’s execution model but provides a layer of structured feedback after failures occur.

Related links: