Introduction

When using model families other than DeepSeek in DeepSeek Harness Web, developers often encounter gateway compatibility errors, session deadlocks (consecutive failures), and inconsistent permission state management. The dsh-tool-adapt plugin provides a compatibility and safety adaptation layer designed to address these issues, ensuring that unofficial models run more stably in the DSH Web environment.

Plugin Overview

This is a compatibility and safety adaptation layer for non-DeepSeek model families in DeepSeek Harness Web. It is maintained by YrracOwl and licensed under the MIT License.

Core Features

The plugin mainly provides the following capabilities:

  1. Dead-session protection: When a session is in a “dead” state (for example, sandbox permissions are already set to danger-full-access or the approval policy is never), the plugin removes or strips the sandbox_permissions and justification fields from the model-side tool schema to avoid infinite loops.
  2. Model-family convention injection: Injects specific calling conventions based on the characteristics of the model family.
  3. Circuit breaker: Breaks or disables consecutive failed requests to prevent session lockups caused by network or gateway-level instability.
  4. Lifecycle-safe settings card: Provides a safe configuration management approach and supports modifying settings in the settings panel.
  5. Gateway compatibility diagnostics and auto-repair: Detects and attempts to fix HTTP 422 errors caused by the gateway rejecting the developer role (supportsDeveloperRole). This diagnostic is passively reported and will not directly modify configuration unless the auto-repair switch is enabled.
  6. Surface limit recovery: Renames the INVALID_REQUEST error returned by the gateway to CONTEXT_WINDOW_EXCEEDED, allowing the dsh-compaction-basic plugin to correctly recognize it and execute recovery logic.

Installation and Enablement

Run the following command in the terminal to install the plugin:

dsh plugin --profile web add dsh-tool-adapt

After installation, you must restart the DSH Web process. The host scans the plugin list at startup, and the settings card and optional status pill will appear only after a restart.

The enablement method depends on the DSH version:
* ≤ 0.1.5: Find the ADAPT card under Settings → Plugins.
* ≥ 0.1.7-rc.2: Find dsh-tool-adapt in the Plugins panel in the sidebar, then click the configuration control under the tool-adapt row.

Typical Usage

The plugin supports hot configuration; changes take effect immediately.

1. Show the status pill
By default, the status pill is hidden. In the ADAPT card, find the “Show status pill” switch and turn it on, or set ui.pill to true in the configuration. The pill appears in one of the four corners of the chat input box and supports dragging to switch anchors.

2. Fix gateway role rejection
If the gateway returns HTTP 422 invalid_request_error, it is usually because the gateway does not support the developer role. In the plugin panel or configuration, modify the following settings for the corresponding route:

providers:
  <route>:
    compat:
      supportsDeveloperRole: false

After enabling the “gateway compat auto-repair” switch, the plugin automatically writes this configuration during diagnostics.

3. Configuration management
The full set of configuration options can be modified in the settings card, or by using the settings.plugin.item path in older RC environments and the plugins.row.config path in newer environments.

Notes

  • Status pill hidden by default: The status pill is not displayed by default and must be enabled manually.
  • Configuration hot reload: Configuration changes made through the settings card are applied immediately.
  • Legacy fallback: DSH 0.1.2+ uses the remote.settings path; older RC hosts without remote.settings automatically fall back to the connection API.
  • Passive diagnostics: Gateway compatibility diagnostics are passive by default (report-only) and will not automatically modify configuration unless auto-repair is manually enabled.
  • Dependency requirements: Requires @deepseek-ai/schemastery version ≥ 3.18.4.

Summary

dsh-tool-adapt focuses on resolving edge-case compatibility issues for unofficial models in DSH Web. By protecting against dead sessions, injecting model conventions, and providing diagnostic and repair tools, it reduces the maintenance cost of unofficial gateway integration. For more details, see the plugin directory or the GitHub repository.