hasan-aghayev/dsh-session-resilience

---

description: "A DSH profile bundle for safe restarts, in-place reconnect, and policy-based session recovery on DSH 0.2+." kind: "package-bundle"

DSH Session Resilience

English | 中文

Summary

DSH Session Resilience keeps long-running web sessions recoverable when the local DSH host restarts, disconnects, reaches a token limit, or begins repeating the same work. It combines loopback restart and stop controls with a host-owned continuation engine, a verified in-place reconnect, four recovery policies, idempotency guards, adaptive backoff, loop protection, and a small live recovery panel.

What makes it different

• Recovery policies — Safe, Balanced, Long task, and Manual coordinate the recovery window, cooldown, retry cap, scan range, and backoff. Manual keeps every individual control editable.
• In-place reconnect — The browser exchanges the replacement host's launch token in the background, asks DSH to replace its live connection, and waits for the new connection before reporting success. The current page and its unsent draft stay in place.
• One recovery center — Restart, stop, automatic continuation, loop protection, error classification, notifications, statistics, and paused sessions are managed from one settings card.
• DSH-native control surface — The settings card uses DSH semantic tokens and compact field density, with a custom module rail and numbered control groups instead of a second visual theme.
• No false success — A restart is not reported as ready until the replacement host is reachable and its fresh launch URL has been found.
• Small model surface — The model receives only restart_dsh and shutdown_dsh; recovery policy and browser controls stay outside the model prompt.
• Local-first operation — Restart markers, helper logs, and control routes are local to the DSH host. The plugin has no analytics or remote service.

Install

Package install

Install the package into the environment used by the DSH profile, add dsh-session-resilience to the profile's bundle list, and run the profile's normal reconcile step.

The bundle patch inserts the Host entry and the web-client entry. The package includes prebuilt lib files so a GitHub installation does not depend on a local TypeScript build.

GitHub install

This repository is intended to be the source of truth for a public release. Pin an exact commit when adding it to a profile. Do not use a moving branch in a production profile.

Install or remove the bundle with the profile-aware DSH command:

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

Update an existing profile

Publishing a release does not replace the archive already pinned in a profile's package.json. If DSH reports dsh-session-resilience: pending (waiting for service: settingsScope), that profile is still using the 0.1.1 client bundle, which requests the removed settings service. Update the profile to 0.1.12 and restart it:

dsh plugin --profile web add -w https://github.com/hasan-aghayev/dsh-session-resilience/releases/download/v0.1.12/dsh-session-resilience-0.1.12.tgz

Replace web with the profile name. The DSH-managed command updates the pinned package URL and installed files; adding a release to a catalog does not upgrade profiles that already contain an older archive.

The repository metadata is already configured for this public GitHub repository. Submit one entry for its public URL to the awesome-dsh-plugin catalog after the local checks pass. The catalog validates the bundle manifest and generates the market data used by dsh-market; npm publication is not required for Git-based installation.

Controls

The web sidebar keeps two compact controls beside the status indicator:

• Restart records active root sessions, starts a replacement DSH host on the configured port, and reconnects the current page after the replacement is ready.
• Stop stops the active DSH host without starting a replacement process; the current page stays open but disconnected.

The status indicator follows DSH's public connection service and does not poll the host over HTTP. Restart and stop send a same-origin request without the DSH session cookie; the host accepts only direct loopback requests whose browser origin matches the host. The restart route always returns JSON and never navigates the browser to a loading page. The controls allow 15 seconds for DSH to confirm acceptance before recovery begins. During restart, the helper reads the replacement host’s own instance id (not the launcher process id) and waits for that host to report the same one-time request id before publishing its launch URL. The sidebar then exchanges its launch token in the background on the current origin, asks DSH to reconnect the existing page, and waits until the new connection is ready. The existing page, view, and unsent draft remain in place. If startup, authentication, or connection recovery takes longer than its deadline, the button reports an error and logs only the failed stage and error type; it never logs the launch URL or token. The page can still be refreshed manually if the browser cannot restore its connection.

The settings card remains available when automatic recovery is disabled, so a user can still perform a deliberate manual restart or stop.

Recovery policies

Policy	Intended use	Default behavior
Safe	Short or sensitive tasks	5-minute handoff, 2 consecutive resumes, smaller scan
Balanced	Everyday work	10-minute handoff, 3 consecutive resumes, moderate backoff
Long task	Builds, imports, and long agent sessions	30-minute handoff, 8 consecutive resumes, wider scan
Manual	Fine tuning	Uses the individual controls in the card

The policy is explicit configuration, not a hidden fallback inside the runtime. When Manual is selected, the individual fields are authoritative. The initial Manual values match the Balanced values and preserve the behavior of an existing configuration.

Safety behavior

The continuation engine resumes only machine-interrupted, transiently failed, or token-limited turns. User aborts and policy-blocked turns are not resumed automatically. Before a continuation, the idempotency guard can tell the model to verify a tool whose result is unknown or avoid repeating a tool that already succeeded.

Permanent failures such as authentication, balance, missing-model, and context-limit errors are skipped and can be surfaced through browser notifications. Repeated failures use adaptive backoff and stop at the configured limit. The loop guard can cancel and redirect a turn that repeats identical tool calls or assistant text.

Settings

Open Settings → Plugins → DSH Session Resilience. The card uses staged edits: values are validated locally and written only after Save. Reset on an individual field removes its user override and returns to the deployment default.

The card includes:

• restart handoff and reconnect window;
• continuation text and output-limit text;
• tool-result safety guard;
• interruption grace period and cooldown;
• boot/reconnect scan and transient-error classification;
• retryable provider patterns and adaptive backoff;
• browser notifications and verbose logging;
• loop guard thresholds;
• today's counters and paused-session controls.

Model Experience

Restart and shutdown tools

What the model sees

The model can call restart_dsh when the user asks to restart DSH or the current task explicitly requires it. It can call shutdown_dsh only for an explicit stop request. Both tools accept an empty object. Restart results include the instance, previous process, port, captured root sessions, and helper log paths.

Token effect

The two tool definitions and their result text use the normal tool-call and tool-result tokens for the active model request. Automatic recovery adds the configured continuation message only after a qualifying interruption.

KV Cache effect

The plugin adds no fixed system-prompt prefix. Its model-visible contribution is limited to the two tool definitions, their results, and a continuation message when recovery is triggered.

Compatibility and limitations

• Designed for a DSH web profile with the published Cordis, tools, LLM, session, and settings packages.
• Version 0.1.3 was smoke-tested in a clean Web profile on DeepSeek Harness 0.2.0-rc.2 and Node 24.18.0; activation and the plugin's local health route succeeded. Its used APIs were also checked against that source release.
• Package metadata also retains support for DSH >=0.1.0-rc.7 <0.2.0 and the 0.1.7-alpha.1 through 0.1.7 release line.
• The replacement process uses the profile's normal DSH web launch path and configured port; the plugin does not choose a GPU, model, or port.
• Restart recovery requires a root browser session that reconnects within the selected handoff window. The browser must permit same-origin action requests and the token exchange request.
• A process that is killed before it writes the restart marker cannot provide a session handoff.
• The browser must be allowed to reconnect to the local DSH launch URL. Browser policy, an external proxy, or a host-level process manager can still prevent recovery.
• Provider-specific errors may need a narrow custom retryable pattern. Broad patterns can repeat requests and should be avoided.

Development and release

The repository commits prebuilt lib artifacts because DSH GitHub installation does not assume a local TypeScript toolchain. Run the complete package check:

npm run pack:check

The verification script checks the standalone package identity, bundle patch, required publication files, and JavaScript syntax. The artifact tests cover client registration, the detached restart helper, and the local status-bridge safeguards. The GitHub workflow repeats the package check for every push and pull request. Version tags matching v* run the release workflow, which checks that the tag matches package.json, creates the package archive, and attaches it to a GitHub Release.

For the DSH Plugin Market submission, use a public repository whose root contains this package.json, cordis.patch.yml, README, license, and prebuilt lib files. Add one data/plugins/hasan-aghayev__dsh-session-resilience.yml entry to the awesome-dsh-plugin catalog and follow its validation pull request. After the catalog entry is merged, the market picks it up automatically. For reproducible installation, use dsh plugin add https://github.com/hasan-aghayev/dsh-session-resilience and pin the selected commit in the profile. A GitHub Release archive is also produced for each version tag.

License and attribution

MIT. This project is an independent community plugin and is not affiliated with DeepSeek AI. It uses the documented DSH plugin extension points and does not modify the DSH agent loop.