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).
2026-06-25 15:04:12 +08:00
parent a4091daa3d
commit d01f5f73b7
50 changed files with 3610 additions and 8 deletions
@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-web-search-exa
+
+An [Exa](https://exa.ai)-backed `WebSearchProvider` for the harness [web capability seam](../web/README.md) (`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. |
+
+```yaml
+- 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`. The provider passes `maxResults` through as Exa's `numResults` for a cost/latency optimization; the final bound is enforced by the seam. Provider failures (HTTP errors, network failure, unparseable bodies) surface as `WebError` `WEB_PROVIDER_ERROR`; an aborted request surfaces as `WEB_ABORTED`.
@@ -0,0 +1,33 @@
+{
+  "name": "@deepseek-ai/dsh-web-search-exa",
+  "description": "Exa-backed search provider for the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-web": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-web": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
@@ -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 }))
+}
@@ -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'
+}
@@ -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
+}
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { ExaSearchProvider, EXA_DEFAULT_BASE_URL } from '@deepseek-ai/dsh-web-search-exa'
+
+/**
+ * Real-API smoke for the Exa search provider. Self-skips without `$EXA_API_KEY`
+ * (CI has no secrets), per the with-key e2e policy in AGENTS.md § Secrets.
+ */
+const apiKey = process.env.EXA_API_KEY
+const maybe = apiKey !== undefined && apiKey.length > 0 ? describe : describe.skip
+
+maybe('ExaSearchProvider real API', () => {
+  it('returns sources for a live query', async () => {
+    const provider = new ExaSearchProvider({ apiKey: apiKey!, baseURL: process.env.EXA_BASE_URL ?? EXA_DEFAULT_BASE_URL })
+    const result = await provider.search({ query: 'DeepSeek coding agent', maxResults: 5 })
+    expect(result.providerId).toBe('exa')
+    expect(result.sources.length).toBeGreaterThan(0)
+    for (const source of result.sources) expect(source.url).toMatch(/^https?:\/\//)
+  }, 30_000)
+})
@@ -0,0 +1,193 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import WebService from '@deepseek-ai/dsh-web'
+import { ExaSearchProvider, mapExaResponse, mapExaResult, EXA_PROVIDER_ID } from '@deepseek-ai/dsh-web-search-exa'
+import * as exaPlugin from '@deepseek-ai/dsh-web-search-exa'
+
+const options = { apiKey: 'exa-key', baseURL: 'https://api.exa.test' }
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' }, ...init })
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('Exa result mapping', () => {
+  it('maps a full result entry', () => {
+    expect(mapExaResult({
+      url: 'https://a.test',
+      title: 'A',
+      publishedDate: '2026-01-01',
+      highlights: ['salient sentence', 'second'],
+    })).toEqual({ url: 'https://a.test', title: 'A', snippet: 'salient sentence', publishedAt: '2026-01-01' })
+  })
+
+  it('drops a result with no usable highlight', () => {
+    expect(mapExaResult({ url: 'https://a.test', highlights: [] })).toBeUndefined()
+    expect(mapExaResult({ url: 'https://a.test' })).toBeUndefined()
+    expect(mapExaResult({ url: 'https://a.test', highlights: ['  '] })).toBeUndefined()
+  })
+
+  it('omits null/empty optional fields rather than emitting them', () => {
+    expect(mapExaResult({ url: 'https://a.test', title: null, publishedDate: null, highlights: ['hi'] }))
+      .toEqual({ url: 'https://a.test', snippet: 'hi' })
+    expect(mapExaResult({ url: 'https://a.test', title: '', publishedDate: '', highlights: ['hi'] }))
+      .toEqual({ url: 'https://a.test', snippet: 'hi' })
+  })
+
+  it('maps a response to a result with no content and filtered sources', () => {
+    const result = mapExaResponse('q', {
+      results: [
+        { url: 'https://a.test', highlights: ['one'] },
+        { url: 'https://b.test' },
+        { url: 'https://c.test', title: 'C', highlights: ['three'] },
+      ],
+    })
+    expect(result).toEqual({
+      providerId: EXA_PROVIDER_ID,
+      query: 'q',
+      sources: [
+        { url: 'https://a.test', snippet: 'one' },
+        { url: 'https://c.test', title: 'C', snippet: 'three' },
+      ],
+      truncated: false,
+    })
+    expect(result.content).toBeUndefined()
+  })
+
+  it('tolerates a missing results array', () => {
+    expect(mapExaResponse('q', {}).sources).toEqual([])
+  })
+})
+
+describe('ExaSearchProvider status', () => {
+  it('is unavailable without a key', () => {
+    expect(new ExaSearchProvider({ apiKey: '', baseURL: options.baseURL }).status())
+      .toEqual({ available: false, reason: 'missing-credential' })
+  })
+
+  it('is available with a key', () => {
+    expect(new ExaSearchProvider(options).status()).toEqual({ available: true })
+  })
+})
+
+describe('ExaSearchProvider request mapping', () => {
+  it('sends query, highlights, numResults and bearer auth', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ results: [{ url: 'https://a.test', highlights: ['hi'] }] }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const provider = new ExaSearchProvider(options)
+    await provider.search({ query: 'hello', maxResults: 5 })
+
+    expect(fetchMock).toHaveBeenCalledOnce()
+    const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]
+    expect(url).toBe('https://api.exa.test/search')
+    expect((init.headers as Record<string, string>)['authorization']).toBe('Bearer exa-key')
+    expect(JSON.parse(init.body as string)).toEqual({ query: 'hello', contents: { highlights: true }, numResults: 5 })
+  })
+
+  it('omits numResults when maxResults is absent', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ results: [] }))
+    vi.stubGlobal('fetch', fetchMock)
+    await new ExaSearchProvider(options).search({ query: 'q' })
+    const [, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]
+    expect(JSON.parse(init.body as string)).not.toHaveProperty('numResults')
+  })
+
+  it('forwards the abort signal', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse({ results: [] }))
+    vi.stubGlobal('fetch', fetchMock)
+    const controller = new AbortController()
+    await new ExaSearchProvider(options).search({ query: 'q' }, { signal: controller.signal })
+    const [, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]
+    expect(init.signal).toBe(controller.signal)
+  })
+})
+
+describe('ExaSearchProvider error handling', () => {
+  it('maps an HTTP error to WEB_PROVIDER_ERROR with the provider message', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ error: 'bad key' }, { status: 401 })))
+    await expect(new ExaSearchProvider(options).search({ query: 'q' }))
+      .rejects.toThrow(expect.objectContaining({ code: 'WEB_PROVIDER_ERROR', message: 'bad key' }))
+  })
+
+  it('keeps a status-line message when the error body is not JSON', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('gateway down', { status: 502 })))
+    await expect(new ExaSearchProvider(options).search({ query: 'q' }))
+      .rejects.toThrow(expect.objectContaining({ code: 'WEB_PROVIDER_ERROR', message: 'Exa API error (HTTP 502)' }))
+  })
+
+  it('keeps the status-line message when the JSON error body carries no detail', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({}, { status: 500 })))
+    await expect(new ExaSearchProvider(options).search({ query: 'q' }))
+      .rejects.toThrow(expect.objectContaining({ message: 'Exa API error (HTTP 500)' }))
+  })
+
+  it('maps a network failure to WEB_PROVIDER_ERROR', async () => {
+    vi.stubGlobal('fetch', vi.fn(() => Promise.reject(new TypeError('connection refused'))))
+    await expect(new ExaSearchProvider(options).search({ query: 'q' }))
+      .rejects.toThrow(expect.objectContaining({ code: 'WEB_PROVIDER_ERROR' }))
+  })
+
+  it('maps an abort to WEB_ABORTED', async () => {
+    vi.stubGlobal('fetch', vi.fn(() => Promise.reject(new DOMException('aborted', 'AbortError'))))
+    await expect(new ExaSearchProvider(options).search({ query: 'q' }))
+      .rejects.toThrow(expect.objectContaining({ code: 'WEB_ABORTED' }))
+  })
+
+  it('maps an unparseable success body to WEB_PROVIDER_ERROR', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('not json', { status: 200 })))
+    await expect(new ExaSearchProvider(options).search({ query: 'q' }))
+      .rejects.toThrow(expect.objectContaining({ code: 'WEB_PROVIDER_ERROR' }))
+  })
+})
+
+describe('web-search-exa plugin registration', () => {
+  it('registers the provider into ctx.web (HMR-safe)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(WebService, { searchProvider: EXA_PROVIDER_ID })
+    const fiber = await ctx.plugin(exaPlugin, { apiKey: 'exa-key' })
+    expect(ctx.web.searchStatus()).toEqual({ available: true, providerId: EXA_PROVIDER_ID })
+    await fiber.dispose()
+    expect(ctx.web.searchStatus()).toEqual({ available: false, reason: 'configured-missing' })
+  })
+
+  it('has no default export (namespace plugin export shape)', () => {
+    expect('default' in exaPlugin).toBe(false)
+  })
+
+  it('falls back to $EXA_API_KEY and the default base URL when config omits them', async () => {
+    const prev = process.env.EXA_API_KEY
+    process.env.EXA_API_KEY = 'env-key'
+    try {
+      const fetchMock = vi.fn(async () => jsonResponse({ results: [] }))
+      vi.stubGlobal('fetch', fetchMock)
+      const ctx = new Context()
+      await ctx.plugin(WebService, { searchProvider: EXA_PROVIDER_ID })
+      const fiber = await ctx.plugin(exaPlugin, {})
+      expect(ctx.web.searchStatus()).toEqual({ available: true, providerId: EXA_PROVIDER_ID })
+      await ctx.web.search({ query: 'q' })
+      const [url] = fetchMock.mock.calls[0] as unknown as [string]
+      expect(url).toBe('https://api.exa.ai/search')
+      await fiber.dispose()
+    } finally {
+      if (prev === undefined) delete process.env.EXA_API_KEY
+      else process.env.EXA_API_KEY = prev
+    }
+  })
+
+  it('is unavailable when neither config nor env supplies a key', async () => {
+    const prev = process.env.EXA_API_KEY
+    delete process.env.EXA_API_KEY
+    try {
+      const ctx = new Context()
+      await ctx.plugin(WebService, { searchProvider: EXA_PROVIDER_ID })
+      await ctx.plugin(exaPlugin, {})
+      expect(ctx.web.searchStatus()).toEqual({ available: false, reason: 'configured-unavailable' })
+    } finally {
+      if (prev !== undefined) process.env.EXA_API_KEY = prev
+    }
+  })
+})
@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../web"
+    }
+  ]
+}