Preface

In DeepSeek Harness (DSH), agent-loop requests are typically bound to a provider/model. A single-provider deployment will cause the current request to fail directly when rate limits, timeouts, or server-side exceptions occur.

@visol-456/dsh-llm-fallback is a DSH community plugin designed to automatically retry the same request against configured (provider, model) fallback targets when the primary provider fails. Below, we cover its purpose, installation method, configuration options, and usage boundaries.

What This Is

  • Package name: @visol-456/dsh-llm-fallback
  • Type: A community plugin within the DeepSeek Harness dsh-plugin ecosystem, not part of the official repository
  • License: MIT
  • Repository: https://github.com/Visol-456/dsh-llm-fallback
  • Both the package name and GitHub repository point to Visol-456

The problem it solves is straightforward: when the primary provider fails, the current request is not immediately terminated; instead, it continues attempting to execute along a priority-ordered list of fallback targets.

Core Features

  1. When the primary provider fails, the same request is automatically retried on the next configured (provider, model) entry.

  2. Maintains a priority-ordered fallbacks list of fallback targets.

  3. Tracks consecutive switchable failures and opens a circuit breaker, failing over to the next healthy entry.

  4. Triggers switching based on failure codes allowed by switchCodes.

  5. Supports editing fallback targets via the Web UI page Settings -> Fallback Chain.

  6. Saved configuration is written to <DSH_HOME>/settings.yaml and takes effect on the next request without requiring a restart.

  7. Records llm/fallback and llm/fallback-route persistent session events.

  8. The plugin remains dormant when fallbacks is omitted, and all requests pass through unchanged.

Installation and Enablement

The plugin runs with the current dsh process permissions. You should review the source code and license before installation.

The following uses the web profile of dsh web as an example.

Using dsh plugin add

Run:

dsh plugin --profile web add @visol-456/dsh-llm-fallback

This command installs the plugin into the web profile.

Using npm

Depending on the deployment method, you may also install it using a package manager:

npm i @visol-456/dsh-llm-fallback

After installation, the plugin still needs to be mounted in the DSH configuration.

Mounting in cordis.yml

Create or edit cordis.yml, mount the plugin, and configure fallback targets:

- name: '@visol-456/dsh-llm-fallback'
  config:
    fallbacks:
      - provider: pi-ai
        model: glm-4.5
    switchCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, UNKNOWN_MODEL, TIMEOUT, TRANSPORT]
    failureThreshold: 1
    cooldownMs: 30000

Here, fallbacks is the list of fallback targets, switchCodes are the failure codes that trigger switching, and failureThreshold and cooldownMs control the circuit breaker and cooldown behavior.

If fallbacks is omitted, the plugin remains dormant and all requests pass through unchanged; you can later create fallback targets in the Web UI page Settings -> Fallback Chain.

Manual Patching and Diagnostics

Manual Patching

If you don’t use dsh plugin add, you can create a patch overlay:

# cordis.yml
- insert:
    - id: llm-fallback
      name: '@visol-456/dsh-llm-fallback'

Then run:

dsh web --patch ./cordis.yml

This patch entry must include insert and id before being applied to dsh web.

Diagnosing Combined Configurations

If the behavior after patching is not as expected, inspect the combined configuration tree:

node --import tsx/esm apps/cli/src/bin.ts web --dump-config --patch <file>

This command is used to view the merged configuration after patching, allowing you to confirm whether the plugin mount entry has taken effect.

Web UI Configuration

Once the plugin is loaded into the web profile, you can edit fallback targets in the Settings -> Fallback Chain page.

Available configuration options include:

  • fallbacks: Priority-ordered (provider, model) fallback targets
  • switchCodes: Failure codes allowed to trigger switching
  • failureThreshold: Consecutive switchable failure threshold
  • cooldownMs: Cooldown period for the chain head after switching

After saving, the configuration is written to:

<DSH_HOME>/settings.yaml

and takes effect on the next request without requiring a restart.

The browser reads and writes this configuration segment through the loopback-only endpoint /llm-fallback/config provided by the plugin. This endpoint rejects non-loopback origins and cross-site requests; it serves as an anti-miswrite/anti-cross-site fence, not an authentication layer.

Usage Boundaries

The following verified usage boundaries apply:

  1. Only agent-loop requests participate. Consumers that directly call ctx.llm.stream() remain single-provider.

  2. fallbacks is a single global fallback list shared by all requests.

  3. State is process-local only. Active entries, cooldowns, and consecutive counts reset to zero after a restart.

  4. Providers with a retry strategy of always will retry themselves, and the fallback mechanism will not observe their failures.

  5. The web profile base bundle already includes @deepseek-ai/dsh-llm-retry; mounting it again will stack retries.

  6. If the non-empty configuration is invalid, the plugin will report an error directly during loading or saving.

  7. Packages published less than 24 hours ago may be blocked by pnpm’s minimumReleaseAge.

  8. The old chains / match / providers configurations are deprecated in version 0.1.x.

Applicable Scenarios

This plugin is suitable for:

  • Deployments that want to add fallback provider/model options for dsh web / agent-loop requests
  • Cases where the primary provider encounters rate limits, timeouts, or server errors and you want the same request to continue trying the next fallback target
  • Auditing switching paths through llm/fallback and llm/fallback-route events after the fact

It is not suitable for:

  • Expecting consumers that directly call ctx.llm.stream() to automatically fall back as well
  • Expecting to maintain multiple independent fallback lists based on different agents or request dimensions
  • Expecting fallback state to persist across processes or restarts

Conclusion

The value of @visol-456/dsh-llm-fallback lies in extending the single-provider request chain into a priority-ordered fallback chain with retry logic, suitable for backup routing needs in the DSH community plugin ecosystem.

GitHub repository: https://github.com/Visol-456/dsh-llm-fallback. The directory page URL was not provided in the source material; you can search the community directory using the package name @visol-456/dsh-llm-fallback.