ChatGPTClaudeGrok / X / CursorGemini

DSH plugin web access: search, fetch, and provider choice

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessWeb accessWebFetchResultProvider selection
DSH plugin web access: why one capability has two operations, search caps, fetch status semantics, body unions, and provider selection rules.

Search and fetch share one seam, but their fields, errors, and degradation paths differ completely. DSH plugin puts both operations on one ctx.web to share provider selection and error vocabulary, not to reuse request structure. Read a fetch result with search habits and you will misjudge a 404 as a failure.

One capability, two operations

What is shared is selection policy and error vocabulary, not schemas.(source)

Search and fetch share neither request schema nor business logic, yet are deliberately designed as one ctx.web middle layer. The payoff has three parts: one owner of provider selection policy, one abort and error vocabulary, and one product-facing configuration surface for "how this harness accesses the web."

The cost is parallel searchX and fetchX method pairs on the service. The reference calls that parallelism intentional rather than an overlooked commonality, so do not abstract both into one generic "network request" downstream.

Providers register capabilities (WebSearchProvider or WebFetchProvider), not tools. Model-facing names, schemas, prompt guidance, and presentation all live in the single consumer dsh-tool-web. That is why swapping a search provider never changes how the model submits a query, and swapping a fetch provider never changes how it requests a URL.

Search: one query per request

The seam enforces the cap on return, so an over-returning provider never leaks to the model side.(source)

Each seam request carries exactly one query. Consumers accept a required queries array and fan it out into independent seam requests; a single-element array performs one search.

maxResults is a consumer-owned cap (dsh-tool-web's searchMaxResults, default 10), passed through the seam and enforced on return. When a provider returns too many, the seam truncates sources[] and sets truncated.

WebSearchResult has three fields: optional content (provider-generated answer text or summary), sources[] (a portable citation shape), and truncated. WebSearchSource requires only url; title, snippet, summary, and publishedAt are all optional — not every provider returns them, and forcing adapters to invent them would make the seam lie. dsh-tool-web displays title ?? hostname(url).

One recommendation worth adopting: if a provider API supports a result count (DeepSeek Search's count, for example), apply it at the request layer as a cost and latency optimization, but the seam enforces the cap regardless.

Fetch: the request intentionally carries only a URL

The "missing fields" on a fetch request are design, not omission.(source)

WebFetchRequest has only url. It deliberately omits timeout, format, prompt, and extraction controls: cancellation is a direct execution argument, and presentation plus higher-level LLM concerns sit outside safe retrieval.

The most important semantic lives here: an HTTP status code is part of the fetched resource's state and is not automatically a failure. Even a successful network fetch returning 404 or 500 still produces a WebFetchResult containing the status and a length-capped decoded body. WebError is reserved for cases where the resource cannot be fetched or represented safely.

WebFetchResult.url is the final URL after allowed redirects, not the request URL. statusCode is the response status, body is content-type-classified decoded text, and truncated says whether the provider truncated.

So judge "fetch failed" in two places: whether the call threw WebError, and whether statusCode is non-2xx. Looking at only one misjudges both ways.

Body types are a closed union

Adding a kind is a cross-package coordinated change, not a plugin extension point.(source)

WebFetchBody is a closed discriminated union owned by dsh-web, with two members today:

ts
type WebFetchBody =
  | { readonly kind: 'html'; readonly content: string }
  | { readonly kind: 'text'; readonly content: string }

Providers decode the kind and dsh-tool-web renders it. Consumers switch on kind with default: assertNever(...), so a new body kind fails compilation at every consumer until handled.

Each branch keeps its own object literal even though fields currently match, leaving room for one branch to gain fields the others lack. Adding a branch to WebFetchBody from a plugin has no effect — this is not an extension point.

Availability and readiness are different questions

available() answers "may this be selected"; ready() answers "does this route have credentials."(source)

available() is a cheap local check (credential presence, config parsability) and must not make network calls. It feeds provider selection at execution time; it is not a health-check system. search() and fetch() read it to pick a usable provider.

Registration is different and observable before operations run: listProviders() returns every registered search and fetch provider with id, optional title, and optional multilingual description, and every register or unregister fires a payload-free web/providers-changed event. Availability still only shows up at operation time.

ready(llmProvider) is optional and also configuration-only, never networked: it answers whether credentials exist for operations initiated by model requests on that conversation route. searchReady() and fetchReady() ask only about the provider search() or fetch() would select, treat providers without ready() as ready, and answer true when selection fails — because the operation itself will report that failure as a WebError.

Readiness is not a selection input. dsh-tool-web uses it as the activation condition for web_search and web_fetch, so a model step whose route answers false neither declares nor dispatches those tools.

Selection never depends on registration order

Without an explicit id, a single usable provider is chosen automatically and several produce an explicit ambiguity error.(source)

Selection resolves at each operation's execution, with these outcomes:

  1. configured id registered and available() — use it;
  2. configured id not registered — WEB_PROVIDER_CONFIGURED_MISSING;
  3. configured id registered but unavailable — WEB_PROVIDER_CONFIGURED_UNAVAILABLE;
  4. no id and exactly one registered usable provider — use it;
  5. no id and several usable — WEB_PROVIDER_AMBIGUOUS;
  6. no id and none usable — WEB_PROVIDER_UNAVAILABLE.

Case 5 matters: the reference states the first registered provider is never chosen. Each operation reads the configured id at execution time, so saved settings changes take effect on the next search or fetch without remounting ctx.web.

Network policy and error codes

The file sandbox does not govern web access; whether you can reach the network is a deployment question.(source)

The shipped Cordis, Code, and Standard presets expose web_fetch under every sandbox and approval mode without per-call confirmation. File sandbox presets do not govern web network access; deployments needing confirmation must add a tools/pre-execute policy or disable fetching.

HTTP providers do not restrict destinations: web_fetch reaches loopback, private networks, and cloud metadata hosts like any other host, and the model can send data to any URL it can reach. Cross-origin redirects require a new tool call. Deployments blocking private destinations must use network isolation, a tools/pre-execute policy, or not mount the fetch tool.

Error codes are divided by owner. WebError carries an open code string (consistent with LlmError and SubagentError), so consumers must tolerate unknown codes. Seam-independent codes from the shared runtime include WEB_PROVIDER_UNAVAILABLE, WEB_PROVIDER_CONFIGURED_MISSING, WEB_PROVIDER_CONFIGURED_UNAVAILABLE, WEB_PROVIDER_AMBIGUOUS, WEB_DUPLICATE_PROVIDER, WEB_ABORTED, and WEB_PROVIDER_ERROR.

Fetch transport codes belong to dsh-web-fetch-http: WEB_INVALID_URL, WEB_BLOCKED_URL, WEB_REDIRECT_BLOCKED, WEB_FETCH_TOO_LARGE, WEB_FETCH_TIMEOUT, WEB_UNSUPPORTED_CONTENT_TYPE. Another fetch backend need not throw them, so never treat them as seam contract.

Verification: one search and one fetch

Cover enforced truncation, non-2xx results, and selection failure.(source)

  1. Register a search provider returning 5 results when maxResults is 2 and assert sources holds 2 with truncated true.
  2. Call listProviders(), assert the provider appears, unregister it, and assert the list updates.
  3. Fetch a URL returning 404 and assert no throw, statusCode 404, and a non-empty body.
  4. Fetch a URL returning 302 to a new same-origin path and assert result.url is the final address.
  5. Register two usable search providers with no configured id and assert WEB_PROVIDER_AMBIGUOUS.
  6. Configure an unregistered id and assert WEB_PROVIDER_CONFIGURED_MISSING.

If step 3 throws WebError, first determine whether the network layer truly failed or the provider treated non-2xx as an exception — the latter violates seam semantics.

For diagnosing search and fetch errors, see web_search and web_fetch fixes; for custom gateways, see custom web gateway.

One line to close: the two operations share selection and errors but not schemas, search caps are enforced on return, non-2xx is a result rather than an exception, bodies are a closed union, and no id means an ambiguity error.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Does a 404 during DSH plugin fetch throw?

No. DSH plugin treats HTTP status as part of the fetched resource state. DSH plugin still returns a WebFetchResult for a successful network fetch with a non-2xx code, carrying the status and a length-capped decoded body.

Who enforces DSH plugin maxResults?

The DSH plugin seam enforces it on return. DSH plugin's maxResults is a consumer-owned cap, so an over-returning provider has its sources truncated by the seam, which also sets truncated.

Does DSH plugin available() make network requests?

No. DSH plugin requires it to be a cheap local check only, testing credential presence and config parsability. DSH plugin forbids network calls inside availability checks.

What happens with two usable DSH plugin providers and no id?

DSH plugin reports WEB_PROVIDER_AMBIGUOUS rather than picking the first registered. DSH plugin selection never depends on registration, configuration, or hot-reload order.

Related Terms

WebSearchResult
WebSearchResult is the normalized search outcome: optional provider answer text, a truncated source list, and a truncated flag.— packages/web/web/src/types.ts
WebFetchResult
WebFetchResult is the normalized fetch outcome: post-redirect final URL, HTTP status, decoded body, and a truncation flag.— packages/web/web/src/types.ts
WebFetchBody
WebFetchBody is the closed body union owned by dsh-web, currently holding only html and text kinds.— packages/web/web/src/types.ts
WEB_PROVIDER_AMBIGUOUS
WEB_PROVIDER_AMBIGUOUS is the structured code thrown when several providers are usable and no id is configured.— packages/web/web/src/types.ts

Sources