dsh-failbook: A Failure Ledger Plugin for DeepSeek Harness, Auto-Clustering and Intercepting Retries

What Does It Do?

dsh-failbook is a DSH plugin for DeepSeek Harness that automatically records every tool call failure, clusters them by failure signature, persists the ledger across sessions, and intercepts agent retries when the same error recurs. It solves the pain of agents repeatedly retrying the same error, wasting tokens and time, making the agent less error-prone over time. Core capabilities include failure signature clustering, failure-aware retry interception, a Web UI panel, and mute/exclusion controls, with zero-config out-of-the-box usage. Maintained by G1en-114 under the MIT license.

Core Features

• Automatic failure recording: hooks into tools/post-execute to capture structured errors, non-zero exit codes, sandbox rejections, and common error texts.
• Signature clustering: failures with the same cause (e.g., bash:command-not-found) are grouped into one bucket regardless of parameter differences.
• Cross-session persistence: stores via the official ctx.storageDomain, surviving restarts; falls back to in-memory ledger when the service is unavailable.
• Failure-aware retry interception: when the same signature fails ≥N times (default 2) within a recent window, injects a suggestive reminder with the failure reason and fix suggestion.
• Web UI panel: shows top failure signatures, counts, recent window, and last time; supports muting, single deletion, and clearing.
• Mute and exclusion: one-click mute for false-positive buckets, with excludeTools/patterns for fine-grained control.

How to Use This Plugin?

After enabling it in DSH, the plugin automatically hooks into tool execution with no extra steps. When the same failure signature recurs within the recent window and reaches the threshold, the plugin injects a reminder to the model, suggesting to stop retrying and providing a fix. You can view the failure ledger in the settings panel and adjust configs like retryGuardThreshold, reminderCooldownSec, and reminderLocale, or use mute and exclusion rules to reduce false positives.