dsh-web-search-brave

pnpm: @ownweb-me/dsh-web-search-brave

Registers the brave search provider on the shared web capability seam (ctx.web), backed by the Brave Search API (results capped at 20 by the API). It declares no tools — the model-facing web_search tool is owned by @deepseek-ai/dsh-tool-web and routes to whichever provider the seam selects.

Selection

dsh-base pins the built-in search backend (searchProvider: deepseek-official), and a web row in a patch replaces the whole row config. Route web_search to Brave with:

- id: web
  config:
    searchProvider: brave

or

export DSH_WEB_SEARCH_PROVIDER=brave

Without a pin, exactly one usable provider must be registered for search (auto-select); several usable providers without a pin fail with WEB_PROVIDER_AMBIGUOUS. If you've disabled the built-in provider rows in your profile layer (web-search-deepseek), any search provider without a registered/selected provider fails with WEB_PROVIDER_UNAVAILABLE.

Credentials

Resolved per call — the first source with a value wins:

| Priority | Source | |---|---| | 1 | braveApiKey literal config field (this plugin) | | 2 | BRAVE_API_KEY in the launching environment | | 3 | refs.BRAVE_API_KEY in the dsh credential store (~/.dsh/.credentials.yaml) | | 4 | BRAVE_API_KEY in the project .env / ~/.dsh/.env |

The env-var name is renamable via braveApiKeyEnv. The store file holds refs under refs: keyed by environment-variable name:

# ~/.dsh/.credentials.yaml (must be owner-readable only: chmod 600)
version: 1
refs:
  BRAVE_API_KEY: BSA-...

The store watches the file, so edits (including rotations and removals) take effect on the very next request — no restart, no config edit. A provider with no resolvable key is unavailable, and a pinned selection then fails with WEB_PROVIDER_CREDENTIAL_MISSING. Restate the entire config when overriding (patches replace, they do not merge):

- id: dsh-web-search-brave
  config:
    braveApiKey: '...'            # optional literal key; wins over the store
    braveApiKeyEnv: BRAVE_API_KEY

Run from source

The plugin resolves its @deepseek-ai/* imports from its own node_modules, so install first:

pnpm install
pnpm dsh web --patch ./cordis.yml

(The overlay uses an absolute path into this checkout; adjust if you move it. Note: the loader transpiles TS in strip-only mode — erasable syntax only, no parameter properties or enums.)

Install from npm

The package is published to the public npm registry, so no local registry or .npmrc is needed — the default registry is npmjs:

dsh plugin --profile demo add @ownweb-me/[email protected]
dsh --profile demo --dump-config     # shows the "# == dsh-web-*" layers

Name the version explicitly: pnpm ≥ 12 applies a 24-hour minimumReleaseAge supply-chain policy that filters freshly published versions out of bare-spec resolutions, so a bare add right after a release silently installs the previous version.

Unlike add ., a registry install also installs the package's own dependencies, and the tarball ships prebuilt JS (the prepare script runs at publish time; main points at the emitted .js), so no build step runs in the profile.

Install as a bundle

(Or install this local checkout as a bundle instead of the registry package:)

dsh plugin --profile demo add .
pnpm install     # add . doesn't install the package's dependencies
dsh --profile demo --dump-config     # shows the "# == dsh-web-*" layers

For git/path installs of this TypeScript package, pnpm runs the prepare script (esbuild) on install; if pnpm blocks the build, allowlist it in the profile's pnpm-workspace.yaml allowBuilds.

Either way, add the web row override to the profile's cordis.patch.yml (see "Selection").

Errors

All failures are WebErrors with machine-routable codes: WEB_PROVIDER_CREDENTIAL_MISSING (no key), WEB_PROVIDER_ERROR (provider HTTP/transport failure), WEB_ABORTED (cancellation).

Verification

BRAVE_API_KEY=BSA-fake pnpm dsh web --patch ./cordis.yml

Expect the [dsh-web-search-brave] registration line; a real web_search then reaches Brave (an invalid fake key → WEB_PROVIDER_ERROR wrapping the upstream HTTP error).