Foreword

When developing agents or proxies with DeepSeek Harness (DSH), request timeouts are a frequent issue. DSH requests can time out at multiple layers: the idle watchdog, SDK requests, HTTP timers, the model server, or tool calls. The UI usually only displays the final error, which often lacks enough specificity. For example, “Request timed out” may be caused by an SDK timeout or by undici’s 300-second header timer timeout. This can easily lead developers to adjust the wrong configuration. dsh-turn-doctor identifies the most likely failure point by measuring each model request’s timing data (time to first byte, longest byte gap, and total request time).

Plugin Overview

dsh-turn-doctor is a diagnostic plugin for DeepSeek Harness. It is used to explain the reasons for turn failures and provide remediation suggestions. It is maintained by developer d3vmeh and licensed under the MIT license.

Core Features

  1. Analyzes multi-layer timeouts: covers DSH idle watchdog, SDK requests, Node/undici HTTP timers, model server, tool calls, and other layers.
  2. Identifies the specific failure layer: uses timing data to locate the specific failure point (for example, a 300-second timeout).
  3. Provides targeted remediation suggestions: offers specific configuration or operational advice (for example, installing a plugin or adjusting parameters).
  4. Captures missed failures: can identify compression failures and tool timeouts.

Installation and Enablement

Use the official command to install the plugin:

dsh plugin --profile web add dsh-turn-doctor

After installation, the verdict results are printed in the dsh terminal.

Typical Usage

  1. View verdicts: Enter the /why command in the chat to view the most recent verdict for the current session.
  2. Configure timeouts: Set streamIdleTimeoutMs or timeoutMs in the configuration file ~/.dsh/profiles/web/cordis.patch.yml so the plugin can correctly classify failure reasons.

Applicable Scenarios and Notes

This plugin is only used to diagnose failure reasons. It does not retry requests, change settings, or inject context. Verdicts exist only in memory (within the dsh process lifecycle) and are not written to session logs. If both the SDK timer and undici header timer are set to 300 seconds, a first-byte timeout may be ambiguous (the plugin will report undici).

Difference from dsh-error-lens: dsh-error-lens groups by HTTP status, while dsh-turn-doctor distinguishes by request timing/timeout layer.

Ecosystem context: The DSH philosophy is “everything is a plugin.” The community catalog is an independent site (for example, Skillhub) and has no official affiliation with DeepSeek / High-Flyer.

Conclusion

By identifying the specific timeout layer, developers can avoid blindly adjusting configuration and quickly locate the root cause of the problem.

GitHub repository: https://github.com/d3vmeh/dsh-turn-doctor