Add web capability seam: ctx.web, search/fetch providers, web tools

Introduce web access as a first-class capability seam so the model-facing
web tools stay stable while backends change. dsh-web owns ctx.web as a
provider registry with registration-order-independent selection and the
WebError taxonomy; dsh-web-search-exa, dsh-web-search-perplexity, and
dsh-web-fetch-local register capabilities into it; dsh-tool-web is the sole
owner of the model-facing web_search/web_fetch schemas, prompt sections, and
HTML-to-markdown presentation. Search and fetch are deliberately one seam.

Providers ship as namespace plugins that register into ctx.web (like an
LlmAdapter into ctx.llm), not key-owning services, since multiple search
providers cannot each own the key. Tool registration follows product
enablement, not backend availability, so load order/credentials never enter
the model contract; the seam resolves the provider at execution time and
surfaces a structured WebError otherwise.

Moves the RFC to implemented/ amended to match what shipped. Example/app
configs are intentionally not wired yet (RFC migration step 6).

packages/web/web-search-exa/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * `@deepseek-ai/dsh-web-search-exa`: registers an Exa-backed `WebSearchProvider`
+ * with `ctx.web`. A function/namespace plugin (NOT a default-export service):
+ * a search provider does not own the `ctx.web` key — it registers INTO the
+ * seam's provider registry, exactly as `@deepseek-ai/dsh-llm-deepseek`
+ * registers an adapter into `ctx.llm`. The key is owned by `@deepseek-ai/dsh-web`.
+ *
+ * @module @deepseek-ai/dsh-web-search-exa
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type {} from '@deepseek-ai/dsh-web'
+import { ExaSearchProvider, EXA_DEFAULT_BASE_URL } from './provider.ts'
+
+export {
+  EXA_DEFAULT_BASE_URL,
+  EXA_PROVIDER_ID,
+  ExaSearchProvider,
+  mapExaResponse,
+  mapExaResult,
+} from './provider.ts'
+export type { ExaSearchProviderOptions } from './provider.ts'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'web-search-exa'
+
+/** The web seam this provider registers into. */
+export const inject = ['web']
+
+export interface Config {
+  /** Exa API key. Falls back to `$EXA_API_KEY`. Empty → provider unavailable. */
+  apiKey?: string
+  /** Endpoint base; `/search` is appended. Defaults to the public API. */
+  baseURL?: string
+}
+
+export const Config: z<Config> = z.object({
+  apiKey: z.string(),
+  baseURL: z.string(),
+})
+
+/** Register the Exa search provider with `ctx.web`. */
+export function apply(ctx: Context, config: Config): void {
+  const apiKey = config.apiKey ?? process.env.EXA_API_KEY ?? ''
+  const baseURL = config.baseURL ?? EXA_DEFAULT_BASE_URL
+  ctx.web.registerSearchProvider(new ExaSearchProvider({ apiKey, baseURL }))
+}

packages/web/web-search-exa/src/provider.ts

@@ -0,0 +1,130 @@
+/**
+ * `ExaSearchProvider`: a `WebSearchProvider` backed by the Exa search API
+ * (`POST /search` with highlight contents). Maps Exa's flat `results[]` into the
+ * seam's normalized `WebSearchResult`. Exa returns no provider-generated answer,
+ * so `content` is omitted; each result maps to a `WebSearchSource` with `url`,
+ * `title`, the first highlight as `snippet`, and `publishedDate` as
+ * `publishedAt`.
+ *
+ * Network requests use platform-native `fetch` (Node 24), mirroring
+ * `@deepseek-ai/dsh-llm-deepseek`'s adapter — not a cordis HTTP-client service.
+ *
+ * @module @deepseek-ai/dsh-web-search-exa/provider
+ */
+
+import { WebError } from '@deepseek-ai/dsh-web'
+import type {
+  WebProviderStatus,
+  WebSearchProvider,
+  WebSearchRequest,
+  WebSearchResult,
+  WebSearchSource,
+} from '@deepseek-ai/dsh-web'
+import type { ExaError, ExaResult, ExaSearchResponse } from './types.ts'
+
+/** Stable id this provider registers under. */
+export const EXA_PROVIDER_ID = 'exa'
+
+/** Default Exa search endpoint; `/search` is the operation. */
+export const EXA_DEFAULT_BASE_URL = 'https://api.exa.ai'
+
+/** Attribution header sent on every request. Bump with the package version. */
+const USER_AGENT = 'deepseek-harness/0.0.1'
+
+export interface ExaSearchProviderOptions {
+  /** Exa API key. Empty/absent → `status()` reports `missing-credential`. */
+  apiKey: string
+  /** Endpoint base; `/search` is appended. */
+  baseURL: string
+}
+
+/**
+ * Map one Exa result to a normalized source, or `undefined` when it carries no
+ * portable snippet (an entry with no highlight is dropped — the seam has no
+ * other field to derive a snippet from, and inventing one would lie).
+ */
+export function mapExaResult(result: ExaResult): WebSearchSource | undefined {
+  const snippet = result.highlights?.find(highlight => highlight.trim().length > 0)
+  if (snippet === undefined) return undefined
+  return {
+    url: result.url,
+    ...result.title != null && result.title.length > 0 ? { title: result.title } : {},
+    snippet,
+    ...result.publishedDate != null && result.publishedDate.length > 0 ? { publishedAt: result.publishedDate } : {},
+  }
+}
+
+/** Map an Exa response envelope to a normalized search result. */
+export function mapExaResponse(query: string, response: ExaSearchResponse): WebSearchResult {
+  const sources = (response.results ?? [])
+    .map(mapExaResult)
+    .filter((source): source is WebSearchSource => source !== undefined)
+  // Exa returns no generated answer, so `content` is omitted. The seam owns the
+  // final `maxResults` truncation, so this provider reports `truncated: false`.
+  return { providerId: EXA_PROVIDER_ID, query, sources, truncated: false }
+}
+
+/** The Exa-backed search provider. */
+export class ExaSearchProvider implements WebSearchProvider {
+  readonly id = EXA_PROVIDER_ID
+
+  constructor(private readonly options: ExaSearchProviderOptions) {}
+
+  status(): WebProviderStatus {
+    if (this.options.apiKey.length === 0) return { available: false, reason: 'missing-credential' }
+    return { available: true }
+  }
+
+  async search(request: WebSearchRequest, exec?: { readonly signal?: AbortSignal }): Promise<WebSearchResult> {
+    let response: Response
+    try {
+      response = await fetch(`${this.options.baseURL}/search`, {
+        method: 'POST',
+        headers: {
+          'authorization': `Bearer ${this.options.apiKey}`,
+          'content-type': 'application/json',
+          'accept': 'application/json',
+          'user-agent': USER_AGENT,
+        },
+        body: JSON.stringify({
+          query: request.query,
+          contents: { highlights: true },
+          ...request.maxResults !== undefined ? { numResults: request.maxResults } : {},
+        }),
+        ...exec?.signal ? { signal: exec.signal } : {},
+      })
+    } catch (error: unknown) {
+      if (isAbortError(error)) throw new WebError('Exa search aborted', 'WEB_ABORTED', { cause: error })
+      throw new WebError(`Exa search request failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error })
+    }
+
+    if (!response.ok) {
+      const status = response.status
+      let message = `Exa API error (HTTP ${status})`
+      try {
+        const parsed = await response.json() as ExaError
+        const detail = parsed.error ?? parsed.message
+        if (detail !== undefined && detail.length > 0) message = detail
+      } catch {
+        // The HTTP status is already captured in `message` above; a malformed or
+        // non-JSON error body (normal for gateway 5xx/429s) can only cost a
+        // richer provider message, never the real error. `response.json()` is
+        // the sole statement and nothing else of consequence reaches here.
+      }
+      throw new WebError(message, 'WEB_PROVIDER_ERROR')
+    }
+
+    let payload: ExaSearchResponse
+    try {
+      payload = await response.json() as ExaSearchResponse
+    } catch (error: unknown) {
+      throw new WebError(`Exa returned an unparseable response body: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error })
+    }
+    return mapExaResponse(request.query, payload)
+  }
+}
+
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'AbortError'
+}

packages/web/web-search-exa/src/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Wire types for the Exa search API (`POST https://api.exa.ai/search`). Types
+ * only — no runtime code. Exa returns a flat `results[]`; each entry carries a
+ * URL, optional title, optional `publishedDate`, and (when highlights are
+ * requested) a `highlights[]` array of salient sentences.
+ *
+ * @module @deepseek-ai/dsh-web-search-exa/types
+ */
+
+/** Request body sent to Exa's search endpoint. */
+export interface ExaSearchRequest {
+  query: string
+  /** Exa's result-count control; the seam still enforces the bound on return. */
+  numResults?: number
+  /** Ask Exa to return highlight sentences per result. */
+  contents: { highlights: true }
+}
+
+/** One entry of Exa's flat `results[]`. */
+export interface ExaResult {
+  url: string
+  title?: string | null
+  publishedDate?: string | null
+  highlights?: string[]
+}
+
+/** Exa's search response envelope. */
+export interface ExaSearchResponse {
+  results?: ExaResult[]
+}
+
+/** Exa's error response envelope (best-effort; fields vary by failure). */
+export interface ExaError {
+  error?: string
+  message?: string
+}