Preface

Coding agents don’t just fail—they repeatedly fail in the same way. Before evidence is folded, compressed, or simply pushed beyond the context window by later attempts, no one can see the pattern. DSH session logs are the model’s context; they are rewritten, folded, and pruned, making them unsuitable as storage for failure history.

This plugin provides an independent logging mechanism that writes abnormally terminated tool calls to a JSONL file on disk and preserves that data beyond the process lifecycle.

Feature Overview

This is a DeepSeek Harness (DSH) host plugin. It listens to tools/result events and captures exceptions in tool calls, output schema violations, unknown tool names, rejected calls, or canceled calls. All records are appended to an on-disk log, and an algorithm collapses highly similar failures into unique “signatures” and counts.

Core capabilities include:

  • Signature folding: hashes the tool name, error code, and normalized error message, merging multiple similar failures into a single record for easier analysis.
  • Regression detection: flags tool calls that succeeded earlier in the session but failed later.
  • Built-in remediation hints: records include clear remediation suggestions for specific error types (such as COMMAND_NOT_FOUND, EDIT_NO_MATCH, etc.).
  • Persistent storage: log files are persistently stored under the <DSH_HOME>/failure-journal/sessions/ directory.

Installation and Enablement

The installation process is consistent with other DSH plugins. Use the dsh plugin command to add the package to the specified configuration file.

dsh plugin --profile web add github:catsenior507/dsh-tool-failure-journal

After installation, restart the host for the configuration to take effect, then verify that the plugin is mounted correctly with the following command:

failure_journal action=selftest

The selftest action checks whether the observer is mounted and writes a test file into the log directory to verify write permissions.

Configuration

To change default behavior, edit the config field in the configuration file. The configuration file is usually in cordis.patch.yml under the profile directory:

- insert:
    - id: tool-failure-journal
      name: '@dsh-external/dsh-tool-failure-journal'
      config:
        maxBytes: 4194304
        clusterThreshold: 3
        excludeTools: ['todo_write']
        recordSuccesses: false
        exposeTool: true
  • maxBytes: the maximum byte size of a single log file (default 4MB).
  • clusterThreshold: the similarity threshold that triggers signature folding.
  • excludeTools: the list of tools to exclude from logging.
  • recordSuccesses: whether to log successful calls (defaults to false; set to true to track actual command execution results).
  • exposeTool: whether to expose the failure_journal tool to the agent.

Usage

The plugin exposes the failure_journal tool to the agent and supports the following actions:

Action Description
stats Counts the most frequent errors and groups them by signature. This is the starting point for analysis.
list Lists the most recent failure records in reverse chronological order.
show <signature> Shows detailed records for all failures under a specific signature.
sessions Lists existing log files on disk and their sizes.
clear Archives the current active log page and clears it, starting a new log.

Example usage:

failure_journal action=stats
failure_journal action=list
failure_journal action=show 9f2c1ab73e04
failure_journal action=sessions
failure_journal action=clear

Storage and Design

  • File storage: logs are stored in JSONL format, with one file per session (<sessionId>.jsonl).
  • Log retention: files are rotated by size, but rotated old files are retained and not deleted. This ensures historical data remains available when the agent enters a loop of repeated errors.
  • Runtime behavior: the observer runs in-process, performs synchronous append writes, and does not block the main flow. It does not depend on build steps, native code, or network requests at runtime.

Notes

  • Runtime dependency: the plugin requires Node.js version >= 20.
  • Permission requirements: the plugin runs with the current DSH process permissions. Ensure the directories are writable.
  • License: MIT license.