DSH plugin web seams: WebSearchRequest and WebFetchRequest

The DSH plugin web seam keeps search and fetch on one ctx.web, but not to share request shapes — the two do not even share a schema. What they share is middleware: a single owner of provider selection, one abort and error vocabulary, and one product configuration surface. The cost is parallel searchX/fetchX method pairs, which the docs call intentional. When writing a provider, two rules matter: maxResults is consumer-set and enforced by the seam on the way back, and non-2xx is a result, not an error.

DSH plugin web seam layers: definition, providers, one consumer

Bottom line: providers register capabilities, not tools; tool names, schemas, prompts and rendering live in the single consumer.

1. Service definition: dsh-web owns ctx.web and the provider registry.
2. Providers: exa, perplexity and deepseek for search; an http implementation for fetch.
3. Consumer: dsh-tool-web exclusively owns the web_search and web_fetch schemas and rendering.
4. Swapping providers keeps the call shape: how the model submits a query or URL does not change.
5. Optional capability: outside the agent loop mainline, with its vocabulary defined here rather than in core.

DSH plugin WebSearchRequest: one query, one bound

Bottom line: a seam request carries one query; the consumer sets the bound and the seam truncates on return.

interface WebSearchRequest { query: string; maxResults?: number }
interface WebSearchResult { content?: string; sources: WebSearchSource[]; truncated: boolean }

1. Fan-out: the consumer accepts a queries array and splits it into separate requests; a single element is one search.
2. Bound origin: maxResults is consumer configuration (default 8) passed through unchanged.
3. Enforcement: over-returning providers are truncated by the seam with truncated set.
4. Optional content: some providers return a generated answer, others only sources.
5. Source shape: url is required while title, snippet and publishedAt are optional — forcing adapters to invent them would make the seam lie.
6. Display fallback: the consumer renders title ?? hostname(url).

DSH plugin WebFetchRequest: URL only, status is resource state

Bottom line: the request deliberately carries only a URL; non-2xx still returns a result and WebError is reserved for unsafe retrieval.

interface WebFetchRequest { url: string }
interface WebFetchResult { url: string; statusCode: number; body: WebFetchBody; truncated: boolean }

1. Why one field: timeouts and cancellation are execution arguments, while format, prompts and extraction belong to higher layers.
2. Status semantics: 404 or 500 still produces a result with a bounded decoded body.
3. Final URL: the result's url is the final address after allowed redirects.
4. Closed body union: html or text, switched exhaustively so a new kind breaks compilation until handled.
5. Truncation flag: truncated means the provider capped the body.
6. Safety boundary: redirect and protocol limits belong to the fetch network policy; do not relax them inside a provider.

DSH plugin provider availability and selection: order-free

Bottom line: available() is a local check only; selection uses an explicit id or a single available provider, and ambiguity throws.

1. available() discipline: credential presence or parseable configuration — network calls are forbidden.
2. Selection timing: read at execution time, not a background health check.
3. Explicit ids: searchProvider / fetchProvider configuration or matching environment variables.
4. Single provider: auto-selected when exactly one is available.
5. Ambiguity: several available with no id throws WEB_PROVIDER_AMBIGUOUS instead of picking the first registered.
6. Order independence: registration, configuration and HMR order never participate.

DSH plugin web error classification: what actually fails

Bottom line: failure means the resource cannot be safely retrieved or represented; status code plus body is a result.

1. Selection failures: WEB_PROVIDER_AMBIGUOUS and similar, whose codes and messages identify missing ids or ambiguous candidates.
2. Fetch failures: unreachable networks, disallowed redirects, bodies that cannot be safely represented.
3. Search failures: provider call failures or unparsable responses.
4. Not failures: non-2xx status, truncated bodies and truncated source lists — all fields on results.
5. Branching: read the kind and code first, then decide whether to retry, switch providers or explain to the user.
6. Verify: request a 404 page on purpose and expect a result with statusCode: 404, not an exception.

DSH plugin web provider troubleshooting

Bottom line: separate no provider, blocked by policy and truncated results.

1. No provider — check credentials and configuration; available() false means it will not be selected.
2. Ambiguity errors — configure a provider id explicitly.
3. Body seems short — check truncated; it is a cap, not a failure.
4. Fewer sources — the maxResults bound was reached and the seam truncated.
5. 500 not retried — non-2xx is a result; retry policy belongs to your layer.
6. Repair status, stated honestly: the shared middleware rationale, request/result shapes, availability and selection rules follow the official Web access page; check network policy and signatures against that page and its Cordis API.

Sources: Web access, dsh-web source, dsh-tool-web.