In the development of DeepSeek Harness (DSH), model failures (such as server overload, network fluctuations, or PI_AI_ERROR) often cause request interruptions or task failures. The deepseek-harness-retry plugin is designed to address this issue by providing a configurable automatic retry mechanism and interrupted session recovery capabilities.

Plugin Positioning and Architecture

The plugin is maintained by community developer syncended and is a Host plugin. It sits in the agent/request-error flow and, before the application’s own fallback budget, prioritizes delegating to DSH’s built-in recovery strategies.

Core value:
* Handles common transient model failures (such as PI_AI_ERROR or UNKNOWN).
* After a DSH crash or restart, only continues work confirmed to be incomplete.
* Provides precise provider routing control.

Installation and Activation

When installing the plugin, DSH automatically registers it as a model-error-retry plugin entry, so there is no need to manually add a plugin entry.

dsh plugin --profile web add @syncended/dsh-retry

After installation or upgrade, restart the selected DSH Profile for the configuration to take effect.

Core Features

  1. Intelligent Retry Strategy

    • Handles configured transient errors such as PI_AI_ERROR or UNKNOWN.
    • Retries twice by default after the original request.
    • For explicit overload errors reported by the Codex server, retries 5 times with longer delays.

  2. Delay Control

    • Supports Exponential Backoff policies.
    • Incorporates random Jitter to avoid the thundering herd effect.
    • Supports the Retry-After header returned by providers.

  3. Recovery and Interruption Handling

    • Abort-aware waiting: During retry waits, if user cancellation or plugin teardown is detected, waiting stops immediately.
    • Session recovery: After a DSH crash or restart, safely continues unfinished tasks using persisted session history (by default retains unfinished tasks from within the last 24 hours).
    • Inbox protection: The plugin never removes, reorders, or replaces existing persisted inbox items.

  4. Events and Routing

    • Emits standard non-superficial session events (llm/retry or llm/retry-started).
    • Supports precise control of retry provider routing through providers (allowlist) and excludeProviders (denylist).

Configuration Methods

After installation, the default configuration works immediately. To customize it, edit the corresponding Profile configuration file.

Editing path:
$DSH_HOME/profiles/<profile>/cordis.patch.yml

Configuration example:
Find the entry with id: model-error-retry and modify the config section.

- id: model-error-retry
  config:
    maxRetries: 3
    overloadMaxRetries: 5
    retryableCodes:
      - PI_AI_ERROR
      - UNKNOWN
      - STREAM_CLOSED
      - EMPTY_RESPONSE
      - RATE_LIMIT
      - SERVER
      - TIMEOUT
      - TRANSPORT
    initialDelayMs: 750
    overloadInitialDelayMs: 2000
    maxDelayMs: 15000
    jitterRatio: 0.15
    respectRetryAfter: true
    resumeInterrupted: true
    resumeMaxAgeMs: 86400000
    providers:
      - openai
      - openrouter

Main configuration items:
* maxRetries: Number of retries for general errors, default is 2. Set to 0 to disable request error retries.
* overloadMaxRetries: Number of retries for overload errors, default is 5.
* resumeMaxAgeMs: Maximum wait time for unfinished tasks (milliseconds), default is 86400000 (24 hours).
* providers: List of providers allowed for retries; leave empty to allow all.

System Requirements and Considerations

  1. Environment dependencies:

    • Node.js 20 or higher is required.
    • DeepSeek Harness 0.1.0-rc.7+ or 0.1.1-rc.2+ is required.
    • The built-in plugin @deepseek-ai/dsh-llm-retry is required (this plugin depends on it rather than replacing it).

  2. Behavioral constraints:

    • Cost: Each retry is a new provider request and can incur additional charges.
    • History: Retry errors and delays are not added to the model-visible history.
    • Permissions: As a Host plugin, it does not require browser connection steps or plugin-specific environment variables.

Summary

The deepseek-harness-retry plugin enhances DSH’s robustness when handling unstable networks or model states through automated retry and session recovery mechanisms. Developers can flexibly adjust retry strategies via the configuration file to balance request success rate and resource consumption.

Resource links:
* GitHub repository
* DSH plugin catalog