@x1a0f3n9/dsh-web-search-exa 0.1.5-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/web/web-search-exa/README.md
+README.md: 214a8f8636cbdaddc01a234cc655e1296860e5a1
+README.zh.md: a91a588a7160d25938769c8dc63dd66bc1820e8b

package/README.md

@@ -0,0 +1,143 @@
+---
+description: "The Exa-backed search provider for ctx.web: how deployments mount vendor-native web search with portable snippets and publication dates."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-exa
+
+English | [中文](README.zh.md)
+
+## Summary
+
+With `dsh-web-search-exa`, the harness searches the web through Exa and gets vendor-native results with portable snippets and publication dates. Choose it when a deployment has an Exa API key and wants Exa's keyword or neural search. Exa returns no generated answer, so results carry no `content` — only citeable sources. A result with no non-blank highlight is dropped, so a call can return fewer sources than requested. The model-facing `web_search` tool lives in `dsh-tool-web`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the provider in a composition that already loads the web service; it registers as the `exa` search provider, so `ctx.web.search()` resolves it automatically when it is the only usable search backend — or pin it with `searchProvider: exa`.
+
+### When to choose it
+
+Choose this backend when a deployment holds an Exa API key and wants Exa's keyword or neural search with per-result highlight snippets and publication dates. The provider is unavailable — and every search call fails with a structured error — when the key is empty or the endpoint base does not parse.
+
+### Minimal configuration
+
+Load the web service and the provider; the API key falls back to `$EXA_API_KEY` from the launch environment, and all other settings have safe defaults.
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-exa'
+  config:
+    apiKey: !!js process.env.EXA_API_KEY
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `apiKey` | `$EXA_API_KEY` | Exa API key; empty or absent makes the provider unavailable |
+| `baseURL` | `https://api.exa.ai` | Endpoint base; `/search` is appended. An unparseable value makes the provider unavailable |
+| `searchType` | `auto` | Retrieval mode sent as Exa's `type`: `auto`, `keyword`, or `neural` |
+| `numResults` | (unset) | Default result count when a request carries no `maxResults`; must be a positive integer |
+| `highlightsPerResult` | `1` | Highlight sentences requested per result (Exa's `highlightsPerUrl`); must be a positive integer |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-exa) is the exhaustive source for every accepted field and its JSDoc.
+
+### What a search returns
+
+Each Exa result maps to a `WebSearchSource`: `url`, `title`, the first non-blank highlight as `snippet`, and `publishedDate` as `publishedAt`; a result with no highlight has no portable snippet and is dropped. A request's `maxResults` wins over the configured `numResults` default and is sent to Exa as a cost and latency optimization — the final bound is enforced by the service, which truncates and flags. Exa returns no generated answer, so the result carries no `content`.
+
+### Failures and recovery
+
+Provider failures — HTTP errors, network failures, unparseable or wrong-shape bodies — surface as `WebError` `WEB_PROVIDER_ERROR`; an aborted request surfaces as `WEB_ABORTED`. HTTP redirects are rejected before the `Location` target is contacted and surface as `WEB_PROVIDER_ERROR`. Callers route on the code; the model-facing `web_search` tool surfaces failures to the model under its own error wrapper.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the provider; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The provider is a thin adapter over Exa's API with two deliberate rules:
+
+- **Portable snippets only.** A source gains a `snippet` only from a real highlight; inventing one from other fields would make the seam lie, so snippet-less results are dropped entirely.
+- **No invented answers.** Exa returns no generated answer, so `content` is omitted rather than fabricating provider prose the model might trust.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: config schema, environment fallback, provider registration |
+| [`src/provider.ts`](src/provider.ts) | The `ExaSearchProvider`: request dispatch, abort classification, result mapping |
+| [`src/types.ts`](src/types.ts) | Exa wire types: `ExaSearchResponse`, `ExaResult`, `ExaError` |
+| — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. |
+
+### Request and mapping flow
+
+`search()` posts the query, retrieval mode, highlight request, and optional result count to `{baseURL}/search` with `redirect: 'error'`, so a redirect fails the request without contacting the target. The parsed `results[]` are mapped one by one, snippet-less entries dropped, and the service applies the final `maxResults` bound on the way back. An abort — a `DOMException` named `AbortError` — becomes `WEB_ABORTED`; anything else becomes `WEB_PROVIDER_ERROR`.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shared vocabulary to the service, the model-facing tools, and the design rationale.
+
+- [Web subsystem](../../../docs/subsystems/web.md) — the exhaustive search request/result vocabulary and error codes.
+- [Web package map](../README.md) — the seven-package family and each role.
+- [dsh-web](../web/README.md) — the web service this provider registers into.
+- [dsh-tool-web](../tool-web/README.md) — the model-facing `web_search` tool that renders this provider's sources.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-exa) — every accepted config field and its source declaration.
+- [Web capability seam decision](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) — why search and fetch share one provider-selection service.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through `dsh-tool-web`, which retains this provider's `maxResults`-bounded URLs, titles, first highlights, and publication dates or its exact `Exa search aborted`, `Exa search request failed: <error>`, and `Exa returned an unprocessable response body: <error>` failures under the consumer's error wrapper.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the provider is a poor fit. They are current package constraints.
+
+- **A result with no non-blank highlight is dropped entirely** — there is no portable snippet to map, so fewer sources than requested can return.
+- **Only `searchType`/`numResults`/`highlightsPerResult` are exposed** — Exa's other controls (livecrawl, category, domain/date filters, full-text contents) wait on provider-neutral service fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
+- **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (such as `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior, limits, and rationale live in the sections above and the linked Agent Notes.
+
+#### Future: wider Exa control surface
+
+Exa's livecrawl, category, domain and date filters, and full-text contents stay unexposed. Exposing them needs provider-neutral service fields first, so the family adds one coordinated control rather than a vendor-specific argument.
+
+</details>

package/README.zh.md

@@ -0,0 +1,143 @@
+---
+description: "ctx.web 的 Exa 搜索提供方：部署方如何挂载厂商原生 web 搜索，获得可移植 snippet 与发布日期。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-exa
+
+[English](README.md) | 中文
+
+## 概述
+
+有了 `dsh-web-search-exa`，harness 可以通过 Exa 搜索 web，获得带可移植 snippet 与发布日期的厂商原生结果。当部署持有 Exa API 密钥、并希望使用 Exa 的关键词或神经搜索时选择它。Exa 不返回生成答案，因此结果不携带 `content`——只产出可引用的来源。没有非空白高亮的来源会被丢弃，因此一次调用返回的来源可能少于请求数量。面向模型的 `web_search` 工具位于 `dsh-tool-web`。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在已加载 web 服务的组合中挂载本提供方；它以 `exa` 搜索提供方身份注册，因此当它是唯一可用的搜索后端时，`ctx.web.search()` 会自动解析到它——也可以用 `searchProvider: exa` 固定。
+
+### 何时选择
+
+当部署持有 Exa API 密钥，并希望使用 Exa 的关键词或神经搜索、获得每项结果的高亮 snippet 与发布日期时，选择此后端。密钥为空或端点基址无法解析时，提供方不可用——每次搜索调用都会以结构化错误失败。
+
+### 最小配置
+
+加载 web 服务与本提供方；API 密钥回退到启动环境中的 `$EXA_API_KEY`，其余设置都有安全默认值。
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-exa'
+  config:
+    apiKey: !!js process.env.EXA_API_KEY
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `apiKey` | `$EXA_API_KEY` | Exa API 密钥；为空或缺失时提供方不可用 |
+| `baseURL` | `https://api.exa.ai` | 端点基址；追加 `/search`。无法解析时提供方不可用 |
+| `searchType` | `auto` | 以 Exa `type` 发送的检索模式：`auto`、`keyword` 或 `neural` |
+| `numResults` | （未设置） | 请求不含 `maxResults` 时使用的默认结果数；必须是正整数 |
+| `highlightsPerResult` | `1` | 每个结果请求的 highlight 句子数（Exa `highlightsPerUrl`）；必须是正整数 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-exa)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 搜索返回什么
+
+每项 Exa 结果映射为 `WebSearchSource`：`url`、`title`、以首个非空白高亮作为 `snippet`、`publishedDate` 作为 `publishedAt`；没有高亮的来源缺少可移植的 snippet，会被丢弃。请求的 `maxResults` 优先于已配置的默认 `numResults`，并作为成本与延迟优化发送给 Exa——最终上限由服务强制执行：截断并标记。Exa 不返回生成答案，因此结果不携带 `content`。
+
+### 失败与恢复
+
+提供方失败——HTTP 错误、网络失败、响应体无法解析或结构不符——以 `WebError` `WEB_PROVIDER_ERROR` 呈现；中止请求以 `WEB_ABORTED` 呈现。HTTP 重定向会在访问 `Location` 指向的目标之前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。调用方根据错误码进行分流；面向模型的 `web_search` 工具会在自己的错误包装层内把失败呈现给模型。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释提供方背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+该提供方是 Exa API 之上的薄适配器，遵循两条刻意的规则：
+
+- **只取可移植的 snippet。** 来源只有在真实高亮存在时才获得 `snippet`；用其他字段捏造会让 seam 说谎，因此没有 snippet 的结果被整个丢弃。
+- **不虚构答案。** Exa 不返回生成答案，因此省略 `content`，而不是编造模型可能信任的提供方文本。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：配置 schema、环境变量回退、提供方注册 |
+| [`src/provider.ts`](src/provider.ts) | `ExaSearchProvider`：请求分发、中止分类、结果映射 |
+| [`src/types.ts`](src/types.ts) | Exa 协议类型：`ExaSearchResponse`、`ExaResult`、`ExaError` |
+| — | 不发布运行时不变量配套入口；除所属 seam 强制执行的约定外，本包没有独立的事件序列或可变数据关系。 |
+
+### 请求与映射流程
+
+`search()` 以 `redirect: 'error'` 把查询、检索模式、高亮请求与可选结果数 POST 到 `{baseURL}/search`，因此重定向会在不接触目标的情况下使请求失败。解析后的 `results[]` 逐项映射，没有 snippet 的条目被丢弃，服务在返回路径上应用最终的 `maxResults` 上限。中止——名为 `AbortError` 的 `DOMException`——变为 `WEB_ABORTED`；其余情况变为 `WEB_PROVIDER_ERROR`。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从共享词汇逐步进入服务、面向模型的工具与设计依据。
+
+- [web 子系统](../../../docs/subsystems/web.zh.md)——穷尽式的搜索请求／结果词汇与错误码。
+- [web 包映射](../README.zh.md)——七包家族与各角色。
+- [dsh-web](../web/README.zh.md)——本提供方注册进入的 web 服务。
+- [dsh-tool-web](../tool-web/README.zh.md)——渲染本提供方来源的面向模型 `web_search` 工具。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-exa)——每个受支持配置字段及其源声明。
+- [web 能力 seam 决策](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)——搜索与抓取为何共用一项提供方选择服务。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过 `dsh-tool-web` 间接影响模型体验。该工具保留本提供方经 `maxResults` 限制的 URL、标题、首条高亮与发布日期；如果发生失败，则会在消费方的错误包装层内保留原样错误消息 `Exa search aborted`、`Exa search request failed: <error>` 和 `Exa returned an unprocessable response body: <error>`。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明提供方在哪些情况下不合适。它们是当前包约束。
+
+- **没有非空白高亮的来源会被整个丢弃**——没有可映射的可移植 snippet，因此返回来源可能少于请求数量。
+- **只公开 `searchType`／`numResults`／`highlightsPerResult`**——Exa 的其他控制项（livecrawl、category、域名／日期过滤条件、全文内容）等待提供方无关的服务字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)）。
+- **按错误形状分类中止**——只有名为 `AbortError` 的 `DOMException` 才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）呈现为 `WEB_PROVIDER_ERROR`。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文和相关 Agent Note 为准。
+
+#### 未来：更宽的 Exa 控制面
+
+Exa 的 livecrawl、category、域名与日期过滤条件以及全文内容仍未公开。公开它们需要先有提供方无关的服务字段，让家族以一个协调一致的控制项、而非厂商专有参数的方式新增。
+
+</details>

package/lib/index.js

@@ -0,0 +1,154 @@
+import { launchEnvironmentOf } from "@x1a0f3n9/dsh-launch-environment";
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@x1a0f3n9/dsh-web";
+//#region lib/types/provider.js
+/**
+* `ExaSearchProvider`: a `WebSearchProvider` backed by the Exa search API (`POST /search` with
+* highlight contents). It maps the first non-blank highlight to `snippet`, maps
+* `publishedDate` to `publishedAt`, drops entries without a snippet, and omits `content`
+* because Exa returns no generated answer.
+* @module @x1a0f3n9/dsh-web-search-exa/provider
+*/
+/** Stable id this provider registers under. */
+const EXA_PROVIDER_ID = "exa";
+/** Default Exa search endpoint; `/search` is the operation. */
+const EXA_DEFAULT_BASE_URL = "https://api.exa.ai";
+/** Default retrieval mode: let Exa pick between keyword and neural search. */
+const EXA_DEFAULT_SEARCH_TYPE = "auto";
+/** Default number of highlight sentences requested per result. */
+const EXA_DEFAULT_HIGHLIGHTS_PER_RESULT = 1;
+/** Attribution header sent on every request. Bump with the package version. */
+const USER_AGENT = "deepseek-harness/0.0.1";
+/**
+* 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).
+*
+* @param result - one entry of Exa's `results[]`.
+* @returns the normalized source, or `undefined` when the entry has no
+*   non-blank highlight.
+*/
+function mapExaResult(result) {
+	const snippet = result.highlights?.find((highlight) => highlight.trim().length > 0);
+	if (snippet === void 0) return void 0;
+	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.
+*
+* @param response - the parsed `POST /search` response body.
+* @returns the normalized result; snippet-less entries are dropped
+*   ({@link mapExaResult}).
+*/
+function mapExaResponse(response) {
+	return {
+		sources: (response.results ?? []).map(mapExaResult).filter((source) => source !== void 0),
+		truncated: false
+	};
+}
+/** The Exa-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+var ExaSearchProvider = class {
+	options;
+	id = "exa";
+	constructor(options) {
+		this.options = options;
+	}
+	available() {
+		return this.options.apiKey.length > 0 && isValidBaseUrl(this.options.baseURL) && isPositiveInteger(this.options.highlightsPerResult) && (this.options.numResults === void 0 || isPositiveInteger(this.options.numResults));
+	}
+	async search(request, signal) {
+		const numResults = request.maxResults ?? this.options.numResults;
+		let response;
+		try {
+			response = await fetch(`${this.options.baseURL}/search`, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"authorization": `Bearer ${this.options.apiKey}`,
+					"content-type": "application/json",
+					"accept": "application/json",
+					"user-agent": USER_AGENT
+				},
+				body: JSON.stringify({
+					query: request.query,
+					type: this.options.searchType,
+					contents: { highlights: { highlightsPerUrl: this.options.highlightsPerResult } },
+					...numResults !== void 0 ? { numResults } : {}
+				}),
+				...signal !== void 0 ? { signal } : {}
+			});
+		} catch (error) {
+			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) {
+			let message = `Exa API error (HTTP ${response.status})`;
+			try {
+				const parsed = await response.json();
+				const detail = parsed.error ?? parsed.message;
+				if (detail !== void 0 && detail.length > 0) message = detail;
+			} catch (error) {
+				if (isAbortError(error)) throw new WebError("Exa search aborted", "WEB_ABORTED", { cause: error });
+			}
+			throw new WebError(message, "WEB_PROVIDER_ERROR");
+		}
+		try {
+			return mapExaResponse(await response.json());
+		} catch (error) {
+			if (isAbortError(error)) throw new WebError("Exa search aborted", "WEB_ABORTED", { cause: error });
+			throw new WebError(`Exa returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+	}
+};
+/** True when `baseURL` parses as an absolute URL (a cheap local config check). */
+function isValidBaseUrl(baseURL) {
+	return URL.canParse(baseURL);
+}
+/** True for a request limit that can be sent to Exa (a positive whole number). */
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Exa-backed `WebSearchProvider` plugin. It contributes to the `ctx.web`
+* registry without owning the service.
+*
+* @module @x1a0f3n9/dsh-web-search-exa
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-search-exa";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const Config = z.object({
+	apiKey: z.string(),
+	baseURL: z.string(),
+	searchType: z.union([
+		"auto",
+		"keyword",
+		"neural"
+	]),
+	numResults: z.number().step(1).min(1),
+	highlightsPerResult: z.number().step(1).min(1)
+});
+/** Register the Exa search provider with `ctx.web`. */
+function apply(ctx, config) {
+	ctx.web.registerSearchProvider(new ExaSearchProvider({
+		apiKey: config.apiKey ?? launchEnvironmentOf(ctx).get("EXA_API_KEY")?.value ?? "",
+		baseURL: config.baseURL ?? "https://api.exa.ai",
+		searchType: config.searchType ?? "auto",
+		highlightsPerResult: config.highlightsPerResult ?? 1,
+		...config.numResults !== void 0 ? { numResults: config.numResults } : {}
+	}));
+}
+//#endregion
+export { Config, EXA_DEFAULT_BASE_URL, EXA_DEFAULT_HIGHLIGHTS_PER_RESULT, EXA_DEFAULT_SEARCH_TYPE, EXA_PROVIDER_ID, ExaSearchProvider, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Exa-backed `WebSearchProvider` plugin. It contributes to the `ctx.web`
+ * registry without owning the service.
+ *
+ * @module @x1a0f3n9/dsh-web-search-exa
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { EXA_DEFAULT_BASE_URL, EXA_DEFAULT_HIGHLIGHTS_PER_RESULT, EXA_DEFAULT_SEARCH_TYPE, EXA_PROVIDER_ID, ExaSearchProvider, } from './provider.ts';
+export type { ExaSearchProviderOptions } from './provider.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-search-exa";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+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;
+    /** Retrieval mode sent as Exa's `type`. Defaults to `auto`. */
+    searchType?: 'auto' | 'keyword' | 'neural';
+    /** Default result count when a request carries no `maxResults`. Omitted = none. */
+    numResults?: number;
+    /** Highlight sentences requested per result. Defaults to 1. */
+    highlightsPerResult?: number;
+}
+export declare const Config: z<Config>;
+/** Register the Exa search provider with `ctx.web`. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `ExaSearchProvider`: a `WebSearchProvider` backed by the Exa search API (`POST /search` with
+ * highlight contents). It maps the first non-blank highlight to `snippet`, maps
+ * `publishedDate` to `publishedAt`, drops entries without a snippet, and omits `content`
+ * because Exa returns no generated answer.
+ * @module @x1a0f3n9/dsh-web-search-exa/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource } from '@x1a0f3n9/dsh-web';
+import type { ExaResult, ExaSearchResponse } from './types.ts';
+/** Stable id this provider registers under. */
+export declare const EXA_PROVIDER_ID = "exa";
+/** Default Exa search endpoint; `/search` is the operation. */
+export declare const EXA_DEFAULT_BASE_URL = "https://api.exa.ai";
+/** Default retrieval mode: let Exa pick between keyword and neural search. */
+export declare const EXA_DEFAULT_SEARCH_TYPE = "auto";
+/** Default number of highlight sentences requested per result. */
+export declare const EXA_DEFAULT_HIGHLIGHTS_PER_RESULT = 1;
+/** Resolved provider options (the plugin's `apply` supplies env-var and constant defaults). */
+export interface ExaSearchProviderOptions {
+    /** Exa API key. Empty/absent makes the provider unavailable. */
+    apiKey: string;
+    /** Endpoint base; `/search` is appended. */
+    baseURL: string;
+    /** Retrieval mode sent as Exa's `type`. */
+    searchType: 'auto' | 'keyword' | 'neural';
+    /** Default result count when a request carries no `maxResults`. */
+    numResults?: number;
+    /** Highlight sentences requested per result (Exa's `highlightsPerUrl`). */
+    highlightsPerResult: number;
+}
+/**
+ * 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).
+ *
+ * @param result - one entry of Exa's `results[]`.
+ * @returns the normalized source, or `undefined` when the entry has no
+ *   non-blank highlight.
+ */
+export declare function mapExaResult(result: ExaResult): WebSearchSource | undefined;
+/**
+ * Map an Exa response envelope to a normalized search result.
+ *
+ * @param response - the parsed `POST /search` response body.
+ * @returns the normalized result; snippet-less entries are dropped
+ *   ({@link mapExaResult}).
+ */
+export declare function mapExaResponse(response: ExaSearchResponse): WebSearchResult;
+/** The Exa-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+export declare class ExaSearchProvider implements WebSearchProvider {
+    private readonly options;
+    readonly id = "exa";
+    constructor(options: ExaSearchProviderOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 @x1a0f3n9/dsh-web-search-exa/types
+ */
+/** Request body sent to Exa's search endpoint. */
+export interface ExaSearchRequest {
+    query: string;
+    /** Retrieval mode: keyword, neural (embeddings), or auto (Exa decides). */
+    type: 'auto' | 'keyword' | 'neural';
+    /** 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: {
+            highlightsPerUrl: number;
+        };
+    };
+}
+/** 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@x1a0f3n9/dsh-web-search-exa",
+  "description": "Exa-backed search provider for the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.1.5-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/web/web-search-exa"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-web": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-web": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.2"
+  }
+}