ecb8aa5b8e
Every packages/*/* README now carries a canonical '## Known Limitations and
Deferred Work' section: condensed, evidence-backed bullets for consumer-visible
gaps (unimplemented features, platform caveats, MVP cuts) and consciously
postponed work (TODO/FIXME/XXX markers, RFC deferrals still open). The ten
pre-existing ad-hoc variants ('What is NOT here (TODO)', 'Deferred',
'Limitations (MVP)', 'Known limitations (tracked TODOs)', ...) are normalized
into the canonical heading.
A new doc-sync gate, scripts/verify-readme-limitations.ts, enforces the shape:
exactly one limitations-like heading per package README, byte-equal to the
canonical h2, with at least one bullet; near-miss headings fail so variants
cannot creep back. Packages with genuinely nothing to declare (dsh-brand,
dsh-timeout, dsh-subagent-mock, dsh-app-boot) are whitelisted in the script and
must NOT carry the section; whitelist entries are validated against the scanned
package set so a rename fails loud.
Wired into the doc-sync chain (package.json) and the run-gates doc-sync leaf
set; the standing rule lands in packages/AGENTS.md and the adding-a-package
cookbook; decision record in
docs/rfc/implemented/process/2026-07-10-readme-known-limitations-gate.md
(RFC index regenerated).
Also fixes two stale '(deferred)' markers claiming dsh-compact-basic is
unimplemented (the dsh-compact seam README's package table and the seam's
module doc comment).
@deepseek-ai/dsh-web-search-exa
An Exa-backed WebSearchProvider for the harness web capability seam (ctx.web). It calls Exa's POST /search endpoint with highlight contents and maps the flat results[] into the seam's normalized WebSearchResult.
This is an implementation package: it registers a provider into ctx.web, it does not own the ctx.web key and it does not register a model-facing tool (that is @deepseek-ai/dsh-tool-web). Like @deepseek-ai/dsh-llm-deepseek, it is a function/namespace plugin (inject: ['web']) that registers its backend, not a default-export service.
Config
| Key | Default | Meaning |
|---|---|---|
apiKey |
$EXA_API_KEY |
Exa API key. Empty/absent → provider status() reports missing-credential (the seam reports configured-unavailable/none). |
baseURL |
https://api.exa.ai |
Endpoint base; /search is appended. An unparseable value makes status() report misconfigured. |
searchType |
auto |
Retrieval mode sent as Exa's type: auto (Exa decides), keyword, or neural. |
numResults |
(unset) | Default result count when a request carries no maxResults. Unset sends no default. Must be a positive integer. |
highlightsPerResult |
1 |
Highlight sentences requested per result (Exa's highlightsPerUrl). Must be a positive integer. |
- id: web-search-exa
name: '@deepseek-ai/dsh-web-search-exa'
config:
apiKey: !!js process.env.EXA_API_KEY
Mapping
Exa returns a flat results[] and no generated answer, so content is omitted. Each result maps to a WebSearchSource: url ← url, title ← title, snippet ← the first non-empty highlights[] entry (a result with no highlight has no portable snippet and is dropped), publishedAt ← publishedDate. A request's maxResults wins over the configured numResults default and is sent as Exa's numResults for a cost/latency optimization; the final bound is enforced by the seam. Provider failures (HTTP errors, network failure, unparseable or wrong-shape bodies) surface as WebError WEB_PROVIDER_ERROR; an aborted request surfaces as WEB_ABORTED.
Known Limitations and Deferred Work
- A result with no non-blank highlight is dropped entirely — no portable snippet to map, so fewer sources than the requested count can return.
- Only
searchType/numResults/highlightsPerResultare exposed — Exa's other controls (livecrawl, category, domain/date filters, full-text contents) wait on provider-neutral seam fields (seam RFC). - Abort classification is error-shape-based — only a
DOMExceptionnamedAbortErrormaps toWEB_ABORTED; an abort carrying a custom reason (e.g.dsh-timeout'sTimeoutReason) surfaces asWEB_PROVIDER_ERROR.