dsh-web-search-gateway

Grounded web search for DeepSeek Harness, on the gateway you already pay for.

Why

The built-in web_search runs on DeepSeek's own endpoint and bills that account — one search is a full model turn, because DeepSeek exposes no dedicated search endpoint. If your chat runs somewhere cheaper, your search does not.

This plugin moves the search call onto an OpenRouter-compatible gateway, so search is billed where your chat already is, at your gateway's price and with the model you pick:

• Your model. The search model is configured separately from the chat model, so a cheap chat model can stay exactly as it is.
• Your price. On api.b.ai: chat on a discounted deepseek-v4.1-flash, search on gpt-5.4-nano — the cheapest model there that actually searches.
• Your ceiling. dsh-tool-web's searchMaxQueries (default 4) can turn one tool call into four searches. Set it to 1 and the cost is one search.

Nothing about the model-facing tool changes: same tool, same arguments, same citeable results. Only the engine behind it moves.

The cheap models usually cannot search. On api.b.ai the DeepSeek, GLM, Qwen, MiniMax and MiMo models accept the request and silently never search — so on that gateway the search model must differ from your chat model. The plugin fails loudly instead of returning the model's memory as results. See Verified gateways.

Install

dsh plugin add dsh-web-search-gateway --profile web
dsh credential set OPENROUTER_API_KEY   # or export it before launching dsh

The package ships a bundle patch, so the first line composes everything: it points the web seam at this provider and inserts the provider row. The key is resolved per search (credentials service, then the process environment), so rotating it never needs a restart — but the patch and a linked host entry are read at boot, so restart dsh web once after installing.

dsh plugin add github:vitas/dsh-web-search-gateway --profile web

git clone https://github.com/vitas/dsh-web-search-gateway.git
cd dsh-web-search-gateway && npm install && npm run build
dsh plugin add link:$PWD --profile web

Quick start

1. Install, then restart dsh web.
2. Settings → Plugins → Web search (OpenRouter).
3. Set Endpoint, Search model, paste the API key.
4. Test search — you get a source count, the latency, and the first hits.

Verified gateways

Web search is a server tool: the gateway must implement it for the model you name, and it is not part of the OpenAI-compatible standard — only the message shape is. "OpenAI-compatible" therefore says nothing about whether search works, which is why every claim here is measured rather than assumed.

Why not just point the built-in provider at my gateway?

The built-in dsh-web-search-deepseek provider is Anthropic-compatible and does expose baseURL and model, so re-pointing it is the obvious first idea. On api.b.ai it doesn't work: the request is accepted and the search never runs — deepseek-v4.1-flash answers from memory (0 results, 44 input tokens for the whole turn), and gpt-5.4-nano gets the tool back as a client-side call. Only /v1/responses with the native OpenAI tool searches there, and only for the OpenAI family. Measurements: docs/gateways.md.

api.b.ai (protocol openai)

Works on /v1/responses with tools: [{ type: 'web_search' }]; hits arrive as url_citation annotations. Cheapest first:

| Model | Citations | Notes | |---|---|---| | gpt-5.4-nano | 2 | cheapest verified; ~8.5k input tokens per query | | gpt-5.4-mini | 4 | | | gpt-5.5-instant | 8 | | | gpt-5-mini | 4 | large input token count | | gpt-6-astra, gpt-6-sol, gpt-5.6-sol, gpt-5.5 | 1–4 | |

Not supported — glm-*, deepseek-*, qwen*, minimax-*, mimo-*, and gpt-5-nano all return HTTP 200 with no search at all (they don't implement OpenAI's server-side tool, and an unknown entry in tools is dropped rather than rejected); Gemini and Anthropic are refused at the route with not supported on /v1/responses; :online, plugins: [{ id: 'web' }] and openrouter:web_search are OpenRouter's conventions and don't exist here.

Input tokens tell a real search from a silent no-op. A search that ran injects its results into the context, so the same prompt suddenly costs thousands of tokens: 4313 for gpt-5.4-nano, against 18 for gpt-5-nano and 24–105 for the non-OpenAI families. That is why the provider checks searched rather than trusting a 200. Per-model failures and cost levers: docs/gateways.md.

openrouter.ai (protocol openrouter)

baseURL: https://openrouter.ai/api/v1 plus a model carrying the web-search badge. engine, searchContextSize, maxUses, maxTotalResults and the domain filters pass through as server-tool parameters. On a gateway that isn't OpenRouter this protocol is rejected — that's the gateway talking, not the plugin.

For OpenAI proper (https://api.openai.com/v1) the default protocol works as-is; sources arrive as web_search_call.action.sources[] and take the same code path.

Protocols

| protocol | Wire shape | Use for | |---|---|---| | openai (default) | tools: [{ type: 'web_search' }] | OpenAI, Azure, and aggregators that proxy the native tool (api.b.ai) | | openrouter | tools: [{ type: 'openrouter:web_search', parameters }] | openrouter.ai, and gateways that adopted the server tool | | plugin (deprecated) | plugins: [{ id: 'web', … }] | older gateways that never adopted the server tool |

The provider also reads web_search_call.action.sources[], openrouter:web_search.action.sources[] and url_citation annotations — including snippets sliced out of the cited span when the gateway sends no excerpt.

Settings

Every field is editable from the card and can be seeded from the composition entry. Where the card lives depends on your harness version: DSH 0.1.7 puts it on the row's own page under Plugins (the sidebar entry), DSH 0.1.5 under Settings → web-search-openrouter. Edits land in the profile's patch, or in settings.yaml on 0.1.5. A value that overrides the composition entry is marked overridden and can be reset from the card.

| Field | Default | Meaning | |---|---|---| | protocol | openai | Enablement surface (above) | | baseURL | https://openrouter.ai/api/v1 | Gateway base; /responses is appended | | model | openai/gpt-5.2 | Model that exposes web search on that gateway | | apiKeyEnv | OPENROUTER_API_KEY | Credential reference, resolved per search | | apiKey | — | Literal key; wins over apiKeyEnv (keep it out of shared profiles) | | maxResults | 5 | Requested results, 1–25; lower is cheaper | | maxOutputTokens | 1024 | max_output_tokens for one search turn | | includeAnswer | false | Return the search model's prose as content too | | allowedDomains, excludedDomains | — | Restrict results to, or drop results from, these hostnames | | engine, searchContextSize, maxUses, maxTotalResults | — | openrouter protocol only; passed through as server-tool parameters | | referer, title | — | HTTP-Referer / X-Title attribution headers |

Cost

Billed as tokens on the search model, not per query. Levers, cheapest first: pick the cheapest model that searches (and only that one — the chat model is separate), set searchMaxQueries: 1, keep maxResults low, leave includeAnswer off. Measured numbers: docs/gateways.md.

Troubleshooting

| Symptom | Cause | |---|---| | WEB_PROVIDER_CREDENTIAL_MISSING | No key under apiKeyEnv; set it in the card or export it before launching dsh. | | "the gateway ran no server-side search for model …" | That model doesn't expose web search on that gateway. Pick one from the table above. | | "Invalid value: 'openrouter:web_search'" | The gateway doesn't implement OpenRouter's server tool; switch protocol to openai. | | "node only allows access to inference API paths" | A gateway-side proxy restriction; check baseURL (a stray trailing slash used to produce //responses). | | HTTP 404 on /responses | Chat-completions-only gateway; this provider needs a Responses endpoint. |

Development

npm install          # esbuild + typescript
npm run check        # host syntax check + client typecheck
npm test             # 35 tests, no network, no credentials (1 skipped: the live one)
npm run check-locales
npm run build        # rebuild the committed lib/client.js (also runs on npm pack)

# Live smoke test — opt-in, never in CI.
DSH_WEB_SEARCH_LIVE=1 OPENROUTER_API_KEY=sk-... \
DSH_WEB_SEARCH_BASE_URL=https://api.b.ai/v1 DSH_WEB_SEARCH_MODEL=gpt-5.4-nano \
node --test test/live.test.mjs

Architecture, seam contracts and the release process: docs/. Three protocols; one browser card (English / 中文 / Русский); no @deepseek-ai/* runtime imports; no install-time script — the bundle is committed and CI fails if it drifted.

Privacy

No stored data, no background work. Per search, one HTTPS request to baseURL with your query, the model name and the configured parameters; the gateway's own terms govern the rest. The key is read from the DSH credential store at call time and is never written to settings, logs or the browser.

License

Apache-2.0.