@tonydua/dsh-web-search-exa

English | 简体中文

Adds Exa web search to DeepSeek Harness (dsh).

dsh plugin --profile web add @tonydua/dsh-web-search-exa

Restart dsh web and it works. No API key, no config edits, no provider to select.

Background, for reference only:

• Exa is a search API. It retrieves pages by keyword or by meaning and returns citable sources with excerpts. It does not generate answers. Exa offers a REST API and also runs an unauthenticated public MCP server.
• The official dsh-web-search-exa is dsh's Exa search provider. It uses Exa's REST API and is only useful once you configure an API key.
• This package is a modified copy of the official one. The REST path works the same. What we added is a keyless channel: with no key it uses Exa's public MCP server, and with a key it still uses REST. The anonymous approach follows the oh-my-pi project, see Acknowledgements.

You can ignore all of this by default. Read Selecting a provider only if you also run the official package, or if dsh reports an ambiguous provider.

Built with deepseek-v4-flash inside DeepSeek Harness (dsh).

Features

• Works without a key. Searches go through Exa's public MCP server (mcp.exa.ai/mcp) and carry no credentials.
• Returns structured results on that keyless path. It calls web_search_advanced_exa, whose output is JSON in the REST field vocabulary, so sources carry real highlight snippets without text parsing.
• Upgrades itself when you add a key. Setting EXA_API_KEY switches to Exa's POST /search REST API for higher limits, with no behavior change.
• Drop-in. It registers into the dsh ctx.web seam; the model-facing web_search and web_fetch tools, their prompt sections, and the result cards all stay as they are.
• Works out of the box. With no official package installed there is no provider to select.
• Backs off when it fails. After repeated failures on the anonymous channel the plugin marks itself unavailable so dsh can pick another provider, instead of failing every search. See What happens when a search fails.

Installation

Pick one of three. The choice only decides where the code comes from; all three end up the same.

From npm. The dsh.bundle manifest ships the bundle patch, so the provider row is inserted for you and you do not edit any patch by hand.

dsh plugin --profile web add @tonydua/dsh-web-search-exa

From the GitHub Release. The same tarball, for when npm is unreachable.

dsh plugin --profile web add https://github.com/TonyDua/dsh-web-search-exa/releases/latest/download/dsh-web-search-exa.tgz

From the repository. Tracks main, including work not yet released.

dsh plugin --profile web add github:TonyDua/dsh-web-search-exa

For a local development checkout, use the same command with a path instead of a package name: dsh plugin --profile web add ../plugins/dsh-web-search-exa.

Restart dsh web afterwards. That is the whole procedure in most cases.

Selecting a provider

Skip this section unless you install the official package too.

Before each search, the dsh seam picks an available provider. If exactly one is available it is selected automatically. If more than one is available the seam raises WEB_PROVIDER_AMBIGUOUS and asks you to name one. So there are only two cases where you have to act:

• You installed the official package as well. Both packages register the provider id exa, so dsh web fails at startup with WEB_DUPLICATE_PROVIDER. You must give this package a different id first, see Coexistence with the official package.
• You see WEB_PROVIDER_AMBIGUOUS. Another provider is available. Name the one you want.

Two ways to name it:

# $DSH_HOME/profiles/web/cordis.patch.yml
- id: web
  name: '@deepseek-ai/dsh-web'
  config:
    searchProvider: exa

Or set $DSH_WEB_SEARCH_PROVIDER=exa at runtime.

Restart dsh web after the change. The model-facing web_search tool then uses the selected provider; no tool configuration changes.

peerDependencyRules:
  ignoreMissing:
    - '@deepseek-ai/cordis'
    - '@deepseek-ai/dsh-*'

Configuration

Where to put the config: edit this plugin's config in $DSH_HOME/profiles/web/cordis.patch.yml, then restart dsh web. The environment variables EXA_API_KEY and $DSH_WEB_SEARCH_PROVIDER work too. apiKey is marked role('secret'), so no describe() response exposes its value.

In the Web panel

In this version the config lives in the profile patch layer, not the Web UI, and there is no editable form. The Settings UI only renders cards that client plugins register by hand for fixed namespaces (shell, agent-loop, web-search-deepseek); it has no generic form for an arbitrary plugin namespace. The current state:

• Plugin inventory (Settings → Plugins): a web-search-exa entry appears automatically once the plugin is enabled. The inventory reads live entries from the Cordis loader, so no extra code is involved.
• Settings namespace (server side): the plugin registers a web-search-exa section through the ctx.settings.installSection API, and the data layer accepts writes. But no client card binds to it, so the UI does not show it. The built-in Web search card edits the official web-search-deepseek namespace, which is unrelated to this plugin.
• Search result cards: web_search calls render the usual web result cards through dsh-tool-web (sources, excerpts, dates), regardless of provider. Anonymous Exa results look identical to DeepSeek search results.

Roadmap: the next version adds a client card registered into the settings.plugin.item slot and bound to the web-search-exa namespace, so every field in the table above becomes editable in Settings → Plugins.

How it works

The anonymous MCP path sends no credentials; attribution rides the x-exa-source: dsh-anything header. Results are normalized to the seam's WebSearchSource shape (url, title, snippet, publishedAt), and the seam enforces maxResults on the way back.

The anonymous path calls web_search_advanced_exa by default. Its text content is a sanitized JSON search response whose entries use the same field names as the REST API, so a result maps to a source directly and no Title:-section text parsing is involved. Two consequences worth knowing:

• The structured tool is only served when the URL carries ?tools=…. The bare endpoint answers MCP error -32602: Tool web_search_advanced_exa not found, which is why that query is part of the default mcpURL and why the plugin splices it into any mcpURL that lacks it.
• It returns whole-page text for every hit, and we ask for highlights separately. Without enableHighlights the endpoint returns text-only entries, every result would lack a snippet, and the search would come back empty. The full text is discarded: a snippet is always a real highlight sentence, never generated and never lifted from the page body.

searchType is not forwarded here. The plugin's setting uses the REST vocabulary (auto, keyword, neural) while the tool accepts its own (auto, fast, instant), so forwarding it would make a configured keyword or neural fail argument validation and take the whole anonymous path down. The tool's default is what auto asks for anyway.

Pinning mcpTool: web_search_exa restores the older text-blob path, where the same results arrive as Title:-led sections. Use it if Exa changes the structured tool's shape; a body that is not the expected JSON already falls back to section parsing on its own.

Because the structured tool returns a whole page of text per hit, a response can be large. Anonymous responses are capped at 256 KiB: the declared content-length is checked before the body is read, and a body that keeps growing is aborted mid-transfer. Over-limit responses fail as transient errors rather than being truncated or silently parsed.

Rate limits

The anonymous channel is a public endpoint run by Exa, and it is rate-limited. When you hit the limit the search fails with the code WEB_RATE_LIMITED and a message telling you to configure EXA_API_KEY. That code is ours, so that you and the model can tell throttling apart from a broken network.

With a key configured, searches use the REST path and are not subject to this limit.

What happens when a search fails

What you will see:

• The anonymous channel is rate-limited: error code WEB_RATE_LIMITED, telling you to configure a key.
• The anonymous channel fails 3 times in a row: this plugin marks itself unavailable for a 5-minute cooldown. During that window available() returns false.
• You pinned searchProvider: exa and the cooldown is active: the search reports WEB_PROVIDER_CONFIGURED_UNAVAILABLE.
• You did not pin searchProvider and the cooldown is active: the seam skips this plugin and looks for another provider. With no other provider available it reports WEB_PROVIDER_UNAVAILABLE.
• You configured a key, so searches use REST: none of the above applies, and failures surface as usual.

Why it works this way. Before each search the seam calls available() to decide which provider to use. If this plugin always answered "available", a dead endpoint would make every search fail hard, and what the user sees is a broken dsh. So the plugin adds a circuit breaker: after 3 consecutive transient failures it admits it is temporarily unavailable, giving the seam a chance to choose someone else. That breaker is this plugin's design; Exa has no such mechanism.

How failures are counted. Only failures that a retry could fix: 5xx, 429, network errors, and unparseable response bodies. Three of them start a 5-minute cooldown, and any successful search clears the count immediately.

A 4xx other than 429 does not count. That is a configuration error and would fail identically on every retry, so hiding it behind a cooldown would only delay the same error by 5 minutes.

This trade-off has a cost. While Exa is down for those 5 minutes, a profile with a pinned searchProvider: exa reports an error instead of trying something else. The plugin cannot choose for you:

• Pinning searchProvider: exa: predictable behavior normally, but no fallback once the breaker opens.
• Leaving searchProvider unset: it can fall back when the breaker opens, at the cost that the seam raises WEB_PROVIDER_AMBIGUOUS whenever several providers are usable, and you have to name one.

Choose the second if you want fallback, and install only one alternative provider.

Compared with the official package

DeepSeek Harness has an official Exa provider, @deepseek-ai/dsh-web-search-exa, which you install separately; dsh does not include it by default. This package is its zero-config variant: it adds the anonymous MCP fallback the official one lacks and keeps the same REST behavior once you configure a key.

Which to use:

• You have an EXA_API_KEY and want the officially maintained package: use the official one, it is the canonical implementation.
• You want to try Exa search with no configuration, no key, and no cost commitment: use this package. It defaults to the anonymous MCP path and switches to REST once a key appears.
• You want both: install both and separate them with providerId, see the next section.

Coexistence with the official package

Both packages register the same provider id (exa) under ctx.web, and both use the cordis plugin name web-search-exa. The seam rejects duplicate ids with WEB_DUPLICATE_PROVIDER, so installing both into one profile without changing the config fails at startup.

Coexistence requires explicit configuration through the providerId switch:

1. The official package keeps exa; its id is fixed.
2. Give this package a different id. Set providerId: exa-anon in this plugin's config; any unique string works.
3. Name one of them on the web seam. Use searchProvider: exa-anon for the anonymous variant, or searchProvider: exa for the official package. $DSH_WEB_SEARCH_PROVIDER works too.

- insert:
    - id: web-search-exa
      name: '@tonydua/dsh-web-search-exa'
      config:
        providerId: exa-anon
- id: web
  name: '@deepseek-ai/dsh-web'
  config:
    searchProvider: exa-anon

The simplest alternative is to install only one of the two packages per profile, which works with the default config.

Troubleshooting

dsh web fails at startup with duplicate loader entry id: web. This is a 0.1.2 bug, fixed in 0.1.4, so upgrading the plugin resolves it. If you already run 0.1.4 or later, please open an issue with dsh --version and your cordis.patch.yml, because a user patch that inserts a web row produces the same error.

Startup fails with Cannot read properties of undefined (reading 'prepare'). @deepseek-ai/dsh-tools is a dsh runtime singleton and must resolve to one physical package instance per profile. This plugin does not depend on it. The usual cause is another third-party plugin in the profile declaring it as an ordinary nested dependency rather than a peer dependency. Fix that plugin's dependency declaration, or have the profile's package manager resolve one shared instance, and only then investigate search errors.

A search reports WEB_PROVIDER_AMBIGUOUS. More than one provider is available. Name one explicitly as described in Selecting a provider.

A search reports WEB_PROVIDER_CONFIGURED_UNAVAILABLE. The provider you pinned is currently unavailable. This happens when the keyless channel's breaker is open, see What happens when a search fails.

There is no settings entry in the Web UI. This version has no UI card; configure through cordis.patch.yml or environment variables, see In the Web panel.

Version compatibility

Every published dsh version from 0.1.2-alpha.2 to 0.2.1-alpha.1 has been tested. Testing means three things: installing that version in isolation, typechecking against its own declarations, and installing this plugin with npm under strict peer resolution. The last step is the one that fails most easily, because npm's peer rules are stricter than pnpm's. To reproduce: bash scripts/compat-matrix.sh.

Versions from the 0.2.0-rc.1 line onward are additionally declared, one full version at a time, under dsh.compatibility.dshReleases in package.json. That key is catalog metadata: the dsh runtime never reads it, and it does not affect resolution — registries such as DSH STORE require an exact per-version record, and a peer range is not installable evidence. The declarations cover 0.2.0-rc.1, 0.2.0-rc.2, and 0.2.1-alpha.1, all compatible.

What differs across versions

Probing the real export surface of every version, the ctx.web seam turns out to be completely stable: WebError is always exported from dsh-web and extends HarnessError, launchEnvironmentOf is always present, and ctx.settings is mounted in every version. Only two things differ.

First, 0.1.7-alpha.1 replaced the settings API. SettingsProvider.installSection is gone, and the service became SettingsForms, which derives a config page from the Config schema the Loader already holds (SettingsDescriptor.schema, autoGenerate). Code that called that method unconditionally throws a TypeError there: the plugin loads but fails. It now probes for the method, calls it only when present, and does nothing otherwise. On 0.1.7+ the Loader's schema drives the form and the plugin has nothing to register.

Second, the @deepseek-ai/cordis line moves with dsh, and it moves through pre-releases: 0.1.5/0.1.6 peer it at ^4.0.2 (exactly 4.0.2 for 0.1.5-rc.3), 0.1.7 at ^4.0.3, 0.2.0 at ~4.0.4, and 0.2.1-alpha.1 at ~4.0.5-alpha.1. Install the version the host asks for, and be careful how you pin it: ^4.0.2 resolves to 4.0.4, which the 0.1.5 releases were not published against, and this plugin then fails to install strictly beside them. The matrix script reads that range and pins its floor as a concrete version. This plugin's own peer range also needed a >=4.0.5-alpha.1 comparator, without which 0.2.1-alpha.1 would not install at all.

Also supported across that whole range: @deepseek-ai/dsh-web, dsh-settings (optional), and dsh-launch-environment. Node.js needs >=22.19.0, matching the harness's own floor.

"@deepseek-ai/dsh-web": ">=0.1.2-alpha.2 || >=0.1.3-alpha.2 || >=0.1.4-0 || >=0.1.5-alpha.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.1.8 || >=0.2.0-rc.1 || >=0.2.1-alpha.1"

Building from source

pnpm install
pnpm run build      # tsdown -> lib/index.js + lib/index.d.ts
pnpm run typecheck  # tsc --noEmit
pnpm test           # builds, then runs the node:test suite against lib/

src/ is the only source directory. lib/ is still committed, because both the npm package and git-based installs consume it.

Acknowledgements

The anonymous MCP integration follows the web_search implementation in can1357/oh-my-pi (packages/coding-agent/src/web/search/providers/exa.ts and src/exa/mcp-client.ts) and the @oh-my-pi/exa plugin: the same "REST when a key exists, credential-free mcp.exa.ai/mcp otherwise" strategy, the same x-exa-source attribution header, and the same Title:-section response parsing. Thanks to the oh-my-pi (omp) project for building the zero-config Exa integration first.

Thanks also to Exa for providing and operating the free, unauthenticated hosted MCP server (mcp.exa.ai/mcp) that makes this package's zero-config default possible. Exa's hosted MCP is an official Exa product, and anonymous usage is rate-limited, see Rate limits.

Thanks to @kahlos (PR #1), who found that web_search_advanced_exa returns a sanitized structured response and that the endpoint does not serve it without a ?tools= query. Neither is documented; both were established by measurement. The anonymous path now uses that tool by default, and the older Title:-section path remains as the fallback.

Changelog

See CHANGELOG.md for all notable changes.

License

MIT, see LICENSE.