dsh-web-search-tavily

A DeepSeek Harness (dsh) plugin that
provides web search through the Tavily Search API.

Requires dsh >= 0.1.2-rc.1 — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the latest/next dist-tags at runtime). The alpha line is no longer supported.

It replaces the default DeepSeek web search — which spends a full auxiliary model call
per search (Anthropic-compatible Messages API + web_search_20250305 server tool) —
with a plain Tavily REST call: ~1s, 1 credit at basic depth, no model tokens.

The plugin registers a WebSearchProvider (id: "tavily") with the official
ctx.web capability seam,
so everything around the tool stays exactly as shipped: the model still calls the same
web_search tool, with the same citation formatting, searchMaxResults bound, and
timeout budget. A provider swap changes how the harness reaches the web, nothing else.

Requirements

• dsh >= 0.1.2-rc.1 (peer deps resolve to the profile's shared @deepseek-ai closure)
• A Tavily API key (tvly-…, free tier available)

Install

One command:

dsh plugin --profile <name> add @aiwayds/dsh-web-search-tavily

dsh plugin installs the package into the profile (via pnpm) and registers it in
dsh.profile.bundles automatically. Restart dsh — the provider is registered and ready.
Local development: dsh plugin --profile <name> add link:/path/to/dsh-web-search-tavily
(relative path specs anchor to your invoking directory). The manual route — adding the
dependency and the bundle entry to ~/.dsh/profiles/<name>/package.json yourself and
running pnpm install there — works identically.

Unlike the anysearch sibling plugin, this one does not claim the web_search
default on install — Tavily needs an API key, and a selected-but-unconfigured provider
would fail every search. After storing the key, select it with one patch entry (below).

@deepseek-ai/* packages are peer dependencies by design: they must resolve to
the profile's single shared dsh closure (link-dsh-closure). Putting them in
dependencies installs a second cordis instance and crashes the loader.

Configure

1. API key. Store the key in dsh's managed credentials document
(~/.dsh/.credentials.yaml) — resolved per search, never written to config files:

version: 1
refs:
  TAVILY_API_KEY: tvly-xxxxxxxx

Fallbacks, in resolution order: TAVILY_API_KEY in the launching environment, then a
literal apiKey in the plugin config (discouraged).

2. Select the provider. The base bundle pins web.searchProvider to
deepseek-official, and a configured id always wins — so add the override to the
profile's cordis.patch.yml (or the home-level ~/.dsh/cordis.patch.yml for every
profile):

- id: web
  config:
    searchProvider: tavily

Optionally retire the DeepSeek search plugin entirely:

- id: web-search-deepseek
  disabled: true

Restart dsh. Verify the composed tree:

dsh --profile <name> --dump-config | grep -A3 'id: web$'   # searchProvider: tavily

Rollback: delete the patch entries and restart — web_search returns to the
shipped DeepSeek provider.

Plugin config (all optional; via a patch layer, read at startup):

Example patch entry with config:

- insert:
    - id: web-search-tavily
      name: '@aiwayds/dsh-web-search-tavily'
      config:
        searchDepth: advanced
        topic: news

Behavior

• results[].content → the portable snippet; Tavily's answer → the result's
  content; the API returns no publication dates, so publishedAt is never set.
• Follows the ctx.web seam contract: cancellation as WEB_ABORTED, a missing key as
  WEB_PROVIDER_CREDENTIAL_MISSING (naming TAVILY_API_KEY), provider failures as
  WEB_PROVIDER_ERROR with Tavily's own error detail surfaced; a rejected key reads
  Tavily rejected the API key (HTTP 401).
• available() is a local check only (credential source present, base URL parseable) —
  it never makes network calls.
• Result-count requests are clamped to Tavily's max_results cap (20); the seam
  additionally enforces the tool's searchMaxResults bound (default 8).

Develop

npm install
npm run check   # tsc --noEmit
npm test        # build + node --test (14 tests)

After editing src/, run npm run build and restart dsh — the plugin loads from
lib/. Unit tests cover response mapping, availability, the request shape, and the
HTTP/abort/credential error branches with mocked fetch.

License

MIT