Introduction

In agent development scenarios with DeepSeek Harness (DSH), existing sessions often break when the local host restarts, the network disconnects, token limits are reached, or repeated work is detected. Manual recovery is not only time-consuming, but it can also cause context loss or inconsistent state.

The dsh-session-resilience plugin aims to solve these issues. It integrates a Bundle into the DSH configuration file that provides safe restart, token-aware reconnection, and policy-driven session recovery, enabling DSH to resume or continue previous tasks as seamlessly as possible after a restart.

Plugin Role

dsh-session-resilience is a DSH profile configuration plugin, or Bundle, maintained by developer hasan-aghayev.

Its core value is:
* Safe restart: Records active sessions, starts a replacement host, and does not report success until the connection is ready.
* Policy-driven recovery: Provides preset policies and manual controls to suit tasks of different durations.
* Local-first: All markers, logs, and control routes run on the local host and do not depend on remote services or analytics.

Core Features

The plugin provides the following verified capabilities:

  1. Safe DSH restart: Records the current active root session, starts a new DSH host on the configured port, and completes the current flow only after confirming that the new connection is available.
  2. Token-aware reconnection: Exchanges a new launch token in the browser background, asks DSH to replace the current connection, and waits until the new connection is established before reporting success.
  3. Policy-driven session recovery: Provides four policy configurations (Safe, Balanced, Long task, Manual), each controlling the handoff window, retry count, scan scope, and backoff strategy.
  4. In-place reconnection: Completes reconnection while preserving the current page and any unsent drafts.
  5. Single recovery center: Controls for restart, stop, auto-continue, loop protection, error classification, notifications, statistics, and session pauses are all managed in one settings card.
  6. No false success: The system does not report readiness when the replacement host is unreachable or the new launch URL is not found.
  7. DSH native control surface: Uses DSH semantic tokens and compact field density instead of a separate visual theme.

Installation and Enabling

Installing this plugin requires adding it to the environment used by the DSH profile, adding it to the profile’s Bundle list, and then running the profile’s normal Reconcile step.

The installation command is:

dsh plugin --profile <profile> add https://github.com/hasan-aghayev/dsh-session-resilience

After installation, restart the DSH instance to apply the changes.

Usage and Control

Model Tool Calls

On the model side, the plugin provides two native tool functions:
* restart_dsh: Called when the user explicitly requests a DSH restart or when the current task logic requires a restart.
* shutdown_dsh: Called only when the user explicitly requests a shutdown.

Both tools accept an empty object as input. The restart result includes instance information, the previous process, the port, the captured root session, and the help log path.

Recovery Policy Configuration

In the DSH settings interface (Settings → Plugins → DSH Session Resilience), configuration can be performed through a card. The card supports step-by-step editing, and changes are written to the configuration only after clicking Save.

The main policies are:

  • Safe: Suitable for short-term or sensitive tasks. Uses a 5-minute handoff window, up to 2 consecutive recoveries, and a smaller scan scope.
  • Balanced: Suitable for daily work. Uses a 10-minute handoff window, up to 3 consecutive recoveries, and moderate backoff.
  • Long task: Suitable for builds, imports, and long-running agent sessions. Uses a 30-minute handoff window, up to 8 consecutive recoveries, and a broader scan scope.
  • Manual: Suitable for fine-tuning. Uses the individual controls in the card, with initial values consistent with Balanced.

Safety Behavior

The recovery engine automatically continues only in cases of machine interruption, transient failure, or token limits. User-aborted turns and policy-blocked turns are not automatically recovered. Before recovery, an idempotency guard can prevent repeated calls to known successful tools or validate unknown results.

Notes

  1. Environment requirements:

    • Node.js version must be >= 22.19.0.
    • DSH version must satisfy: >=0.1.0-rc.7 <0.2.0 or >=0.1.7-alpha.1 <0.1.8 or 0.2.0-rc.2 or ^0.2.0.

  2. Local execution:

    • Restart markers, auxiliary logs, and control routes are limited to the local DSH host.
    • The plugin contains no analytics functionality or remote services.

  3. Readiness status:

    • A restart operation is not reported as ready until the replacement host is reachable and its new launch URL has been found.

Summary

dsh-session-resilience provides a local, policy-driven solution for handling DSH host restarts and session interruptions. By centralizing recovery controls in a single interface and ensuring that only verified connections are considered successful, it reduces the need for manual intervention and improves the stability of agent task execution.

For more information and the source code, visit: GitHub repository