Introduction

The web_search tool in DSH relies on external search providers (such as exa and deepseek-official). These providers may fail due to network instability, API rate limiting, credential errors, or timeouts. The DSH seam does not provide provider-level timeout control, nor does it include a built-in automatic failover mechanism. This plugin adds an ordered fallback layer on top of the providers registered in ctx.web: it does not implement search backends or handle credentials; instead, it chains providers together. When a provider is unavailable, returns an error, times out, or returns empty results, the plugin automatically switches to the next provider until a usable result is found or all providers fail.

Core Features

  • Ordered fallback for web search providers: Tries multiple search providers sequentially in the configured order.
  • Works on top of registered providers: Reads and processes providers registered in ctx.web (such as exa and deepseek-official).
  • Configuration support: Controlled through order (priority), exclude (exclusion list), timeoutSeconds (timeout budget), and fallbackOnEmpty (empty-result handling).
  • Automatic failover: Automatically moves to the next provider when a provider is unavailable, times out, or returns empty results.
  • Error handling: Handles errors such as WEB_PROVIDER_ERROR and WEB_PROVIDER_UNAVAILABLE.

Installation and Enablement

Install the plugin using the official command. The package includes cordis.patch.yml. The dsh plugin command appends it to the dsh.profile.bundles of the target profile, and at startup points web.searchProvider to this plugin.

Installation command:

dsh plugin --profile web add github:killcerr/dsh-web-search-order

Local development:
If you need to modify the source code, install it using a local path. After making changes, simply restart DSH; no reinstallation is required:

dsh plugin --profile web add C:\path\to\dsh-web-search-order

Configuration and Behavior

The plugin supports the following configuration options:

  • order: A list of provider IDs. Earlier entries have higher priority. Providers not listed are appended after them in registration order. Uninstalled or unrecognized IDs are ignored, with a one-time warning.
  • exclude: A list of provider IDs that are never tried. This takes precedence over order.
  • timeoutSeconds: The timeout budget for a single attempt, in seconds. The plugin implements this timeout itself, because the DSH seam does not provide provider-level timeouts.
  • fallbackOnEmpty: When neither sources nor answer text are returned, whether to treat it as a miss and try the next provider. If set to false, the empty result is returned as-is.

Version-specific behavior:
* 0.1.5 line: Supports configuration under the web-search-order section in ~/.dsh/settings.yaml, with hot reloading.
* 0.1.6+ line: Configure it in the config field of the plugin entry. Editing the settings page writes changes back to the profile patch.

Compatibility and Environment

  • Node.js version: Requires Node.js >= 22.19.0.
  • DSH version: Declared compatibility is >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0.
    • Note: The 0.1.7 line uses config-entry configuration and no longer supports settings.yaml.
  • 0.2.0+: No compatibility is declared.

Ecosystem Context

The DSH philosophy is “everything is a plugin.” This plugin belongs to the web tools category in the community directory, is maintained by killcerr, and is released under the MIT License.