@mini-z/dsh-search-providers

A modular DeepSeek Harness (DSH) plugin that provides web_search and read_page through multiple search services with capability-aware fallback and cooldown handling.

Codex is the default web_search provider. If its static credential is unavailable, or a request fails, the plugin proceeds through the configured fallback chain.

Features

• Replaces the native web_search provider through the DSH web seam.
• Registers read_page for clean, structured page extraction.
• Uses Codex-first search routing by default.
• Filters fallback candidates by capability, so search-only providers are never used for page fetching.
• Temporarily cools failing provider capabilities instead of repeatedly calling them.
• Disables only confirmed authentication failures until DSH restarts.
• Propagates caller cancellation without cooling providers or continuing fallback.
• Supports custom active-provider and fallback order configuration.
• Includes a key-free demo provider for wiring tests.

Provider support and default routing

Provider	web_search	read_page	Credential
Codex	✅	❌	Static credential JSON referenced by CODEX_CREDENTIAL_FILE
TinyFish	✅	✅	TINYFISH_API_KEY
Tavily	✅	❌	TAVILY_API_KEY
Exa	✅	✅	EXA_API_KEY
Firecrawl	✅	✅	FIRECRAWL_API_KEY
Demo	✅	✅	None

Default web_search order:

1. Codex
2. TinyFish
3. Tavily
4. Exa
5. Firecrawl

Default read_page order:

1. TinyFish
2. Exa
3. Firecrawl

Codex and Tavily are skipped automatically for read_page because they do not implement page fetching. Providers without usable credentials are skipped without being marked as failed.

Installation

Install from npm

npx -y @deepseek-ai/dsh plugin --profile web add @mini-z/dsh-search-providers

Replace web with another DSH profile name when needed. Restart the corresponding DSH process after installation or configuration changes.

Install from a local checkout or tarball

npx -y @deepseek-ai/dsh plugin --profile web add /path/to/dsh-search-providers

The npm package and release tarballs include the built dsh/ artifacts. A local source checkout only needs rebuilding after source changes:

bun install --frozen-lockfile
bun run build

Configuration

DSH loads secrets from ~/.dsh/.env. Configure at least one provider:

# Default web_search provider
CODEX_CREDENTIAL_FILE=/absolute/path/to/codex-credential.json

# Optional fallback providers
TINYFISH_API_KEY=...
TAVILY_API_KEY=...
EXA_API_KEY=...
FIRECRAWL_API_KEY=...

API-key providers also accept these optional environment variables, using the corresponding prefix (TINYFISH, TAVILY, EXA, or FIRECRAWL):

EXA_BASE_URL=https://api.exa.ai
EXA_TIMEOUT_MS=55000

Codex supports CODEX_TIMEOUT_MS. The default provider request timeout is 55 seconds. Environment variables take precedence over values in the Cordis configuration.

Change the active provider or fallback chain

Add an id-targeted override to ~/.dsh/profiles/<profile>/cordis.patch.yml:

- id: search-providers
  config:
    provider: exa
    fallbackChain: [codex, tinyfish, tavily, firecrawl]
    providers:
      exa:
        timeoutMs: 55000

Routing rules:

• provider is always attempted first when it is available and supports the requested capability.
• fallbackChain contains the providers attempted afterward.
• Duplicate provider ids are removed while preserving order.
• fallbackChain: [] disables fallback and uses only the active provider.
• Providers that do not support the requested capability are omitted from attempts and diagnostics.

For TinyFish, Tavily, Exa, and Firecrawl, provider entries support apiKey, baseUrl, timeoutMs, and provider-specific options. Prefer ~/.dsh/.env for secrets rather than storing API keys in profile YAML. TinyFish has one additional page-fetch endpoint option:

- id: search-providers
  config:
    providers:
      tinyfish:
        options:
          fetchBaseUrl: https://api.fetch.tinyfish.ai

Codex only uses timeoutMs from provider configuration. Its endpoint is fixed, and it intentionally ignores apiKey, baseUrl, and options; credentials come exclusively from CODEX_CREDENTIAL_FILE.

Fallback, cooldown, and cancellation behavior

The plugin rechecks provider state before every attempt instead of relying on a stale snapshot. A provider whose cooldown expires while other providers are being tried may participate again in the same request.

Failure class	Effect
Confirmed authentication failure	Provider disabled globally until DSH restarts
HTTP 429/432, quota, or rate limit	Current capability cooled for 5 minutes
Network error or timeout	Current capability cooled for 30 seconds
Other request failure	Current capability cooled for 10 seconds

Transient state is capability-scoped: a search failure does not cool read_page, and a fetch failure does not cool web_search. Authentication disablement is provider-wide.

The first eligible provider uses its configured request timeout. Each subsequent fallback attempt has an additional 20-second outer limit, which also stops providers that ignore AbortSignal. The registered read_page tool has a 200-second aggregate deadline. These request deadlines are separate from the cooldown durations in the table above.

Caller cancellation is different from failure: it propagates immediately, preserves the original abort reason, does not continue fallback, and does not alter provider state.

Successful search output identifies the provider that actually answered and reports fallback, cooling, and disabled-provider state. Final errors list the providers genuinely attempted and the current live state.

Codex credential file

Codex uses the standalone ChatGPT Codex search endpoint and is independent of model/login plugins. It only reads an existing static credential file; it never starts a login, refreshes a token, checks local expiry timestamps, or writes credential data.

Minimal supported JSON:

{
  "access_token": "eyJ...",
  "account_id": "account-id"
}

The parser also accepts credential and tokens wrappers, access as an alternative token field, and accountId as an alternative account field. If the account id is omitted, the plugin reads the standard chatgpt_account_id claim from the access token. Missing or malformed credentials make Codex unavailable. Codex HTTP 401/403 responses are treated as confirmed credential failures and trigger the normal fallback chain.

Restrict the credential file to the owning user. Codex does not implement read_page, and its standalone endpoint does not apply this plugin's recency, domain, location, language, or maximum-result filters.

Usage

After loading the plugin and configuring at least one provider, ask the model to search:

Search the web for "latest Rust memory safety features".

Successful results start with the provider that actually answered:

[Search provider: TinyFish]

Read a specific page with:

Read this page: https://example.com/article

read_page returns structured evidence containing a summary, extracted content, outgoing links, uncertainty, and operational warnings.

Demo mode

Run DSH with the key-free demo provider on POSIX shells:

SEARCH_PROVIDERS_DEMO=1 npx -y @deepseek-ai/dsh --profile web --no-open --port 9876

PowerShell:

$env:SEARCH_PROVIDERS_DEMO = '1'
npx -y @deepseek-ai/dsh --profile web --no-open --port 9876

Alternatively set provider: demo in the plugin configuration. Demo mode returns canned search and page-fetch results for integration testing.

Development

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build

Main components:

• src/providers/types.ts — provider interfaces and result types.
• src/providers/registry.ts — provider registration and active-provider selection.
• src/providers/cooldown.ts — authentication disablement and capability cooldown state.
• src/providers/*.ts — provider implementations.
• src/tools/web-search.ts — DSH web seam adapter and search fallback.
• src/tools/read-page.ts — read_page registration and fetch fallback.
• src/index.ts — plugin entry point and default provider order.

To add a provider, implement SearchProvider, register it in src/index.ts, and add its configuration resolution.

Publishing

1. Bump the version in package.json.
2. Run the development checks and inspect bun pm pack --dry-run.
3. Log in with npm login.
4. Publish the public scoped package with npm publish --access public.

Published npm versions are immutable; every release requires a new version number.

License

MIT. The Codex interoperability implementation was developed with reference to dsh-codex-connect (Apache-2.0); no runtime dependency on that package is required.