@tonydua/dsh-web-search-exa 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-anything contributors
+
+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,5 @@
+# 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.
+README.md: 43f37d9ed00f718982fecc2684e40f2ce1ea997c
+README.zh.md: c525e2ccac7569211e76321e43982bae1d38342c

package/README.md

@@ -0,0 +1,212 @@
+# @tonydua/dsh-web-search-exa
+
+> **Built with [deepseek-v4-flash](https://api-docs.deepseek.com) inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh).**
+
+An Exa-backed `WebSearchProvider` for the DeepSeek Harness web capability seam
+(`ctx.web`), with an **anonymous** fallback: when no API key is configured,
+search routes through Exa's hosted MCP server (`https://mcp.exa.ai/mcp`) via
+JSON-RPC 2.0 with **no credentials at all** — Exa's documented unauthenticated
+public MCP fallback (rate-limited). With an `EXA_API_KEY`, the lighter REST
+endpoint is used instead.
+
+This is an implementation package: it registers a provider INTO `ctx.web`
+(`inject: ['web']`) and owns no model-facing tools (those belong to
+`@deepseek-ai/dsh-tool-web`). The model-facing `web_search` / `web_fetch` tools,
+their prompt sections, and the Web result cards are unchanged.
+
+## Why this package exists (difference from the official one)
+
+The DeepSeek Harness ships an official Exa provider,
+[`@deepseek-ai/dsh-web-search-exa`](https://www.npmjs.com/package/@deepseek-ai/dsh-web-search-exa).
+This package is the **zero-config variant**: it adds the anonymous MCP fallback
+the official one does not have, and keeps the same keyed REST behavior when an
+API key is configured.
+
+| | Official `@deepseek-ai/dsh-web-search-exa` | This package `@tonydua/dsh-web-search-exa` |
+|---|---|---|
+| REST path (`POST /search`) | ✅ only path | ✅ used when a key is configured |
+| Requires an API key | ✅ **yes — empty key makes it unavailable** | ❌ no — keyless anonymous MCP fallback |
+| Anonymous MCP (`mcp.exa.ai/mcp`) | ❌ not implemented | ✅ default when no key |
+| Zero-config install | ❌ | ✅ |
+| Provider id | `exa` (fixed) | `exa` by default, **configurable via `providerId`** |
+| Cordis plugin name | `web-search-exa` | `web-search-exa` |
+| Config keys | `apiKey`, `baseURL`, `searchType`, `numResults`, `highlightsPerResult` | `apiKey`, `apiKeyEnv`, `apiURL`, `mcpURL`, `searchType`, `numResults`, `highlightsPerResult`, `providerId` |
+
+## Acknowledgements
+
+The anonymous MCP integration follows the `web_search` implementation in
+[can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) (`packages/coding-agent/src/web/search/providers/exa.ts`
+and `src/exa/mcp-client.ts`) and the
+[`@oh-my-pi/exa`](https://www.npmjs.com/package/@oh-my-pi/exa) plugin: same
+"REST when a key exists, credential-free `mcp.exa.ai/mcp` otherwise" strategy,
+same `x-exa-source` attribution header, same `Title:`-section response parsing.
+Thanks to the oh-my-pi (omp) project for pioneering the zero-config Exa
+integration.
+
+Thanks also to **[Exa](https://exa.ai)** for providing and operating the
+**free, unauthenticated hosted MCP server** (`mcp.exa.ai/mcp`) that makes this
+package's zero-config default possible. Exa's hosted MCP is an official Exa
+product; anonymous usage is rate-limited (see Known limitations).
+
+## How it works
+
+| Condition | Path | Endpoint |
+|---|---|---|
+| `apiKey` / `EXA_API_KEY` set | REST `POST /search` with `Authorization: Bearer` | `https://api.exa.ai/search` (configurable) |
+| No key configured | Anonymous MCP `tools/call web_search_exa` (JSON-RPC 2.0, no credentials) | `https://mcp.exa.ai/mcp` (configurable) |
+
+The anonymous MCP path sends no credentials; attribution rides the
+`x-exa-source: dsh-anything` header. Results are normalized to the seam's
+`WebSearchSource` shape (`url`, `title`, `snippet`, `publishedAt`) and the seam
+enforces `maxResults` on the way back. Anonymous usage is rate-limited by Exa:
+an HTTP 429 surfaces as a `WEB_PROVIDER_ERROR` with a hint to configure an API
+key (which also switches to the REST path automatically).
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `providerId` | `exa` | Provider id registered into `ctx.web`. Only change it when both this and the official package are installed (see next section). |
+| `apiKey` | unset | Literal Exa API key. Empty/missing enables the anonymous MCP path. |
+| `apiKeyEnv` | `EXA_API_KEY` | Environment variable consulted when no literal `apiKey` is set. |
+| `apiURL` | `https://api.exa.ai/search` | REST search endpoint (keyed path only). |
+| `mcpURL` | `https://mcp.exa.ai/mcp` | Exa hosted MCP endpoint (anonymous path). |
+| `searchType` | `auto` | REST retrieval mode: `auto` / `keyword` / `neural`. |
+| `numResults` | unset | Default result count when the request carries no `maxResults`. |
+| `highlightsPerResult` | `1` | Highlight sentences requested per result on the REST path. |
+
+## Coexistence with the official package
+
+Both packages register their provider under the **same default provider id
+(`exa`)** and the same cordis plugin name (`web-search-exa`). The seam rejects
+duplicate ids with `WEB_DUPLICATE_PROVIDER`, so **installing both into one
+profile without changes breaks at startup**.
+
+There is **no silent override** — coexistence is explicit, via the `providerId`
+switch:
+
+1. Keep the official package on `exa` (its id is fixed).
+2. Give this package a distinct id — set `providerId: exa-anon` (any unique
+   string) in this plugin's `config`.
+3. Select the anonymous variant explicitly with
+   `searchProvider: exa-anon` on the `web` seam (or
+   `$DSH_WEB_SEARCH_PROVIDER=exa-anon`), and keep
+   `searchProvider: exa` → the official one if you want it selectable too.
+
+```yaml
+- insert:
+    - id: web-search-exa
+      name: '@tonydua/dsh-web-search-exa'
+      config:
+        providerId: exa-anon
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: exa-anon
+```
+
+Simplest alternative: install only one of the two packages per profile — the
+defaults then work as-is.
+
+## Installation (into a dsh profile)
+
+From this repository:
+
+```powershell
+dsh plugin --profile web add ../plugins/dsh-web-search-exa
+```
+
+Then enable the provider and select it. Either merge into
+`$DSH_HOME/profiles/web/cordis.patch.yml` (persistent):
+
+```yaml
+- id: web-search-exa
+  name: '@tonydua/dsh-web-search-exa'
+  config:
+    apiKeyEnv: EXA_API_KEY
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: exa
+```
+
+…or pass `patches/exa-anon-search.patch.yml` as an overlay:
+
+```powershell
+dsh --profile web --patch patches/exa-anon-search.patch.yml
+```
+
+Alternatively, select the provider at runtime with the environment variable
+`$DSH_WEB_SEARCH_PROVIDER=exa` (no config edit needed).
+
+Restart `dsh web` for changes to take effect. The existing model-facing
+`web_search` tool then routes through this provider — no tool config changes.
+
+### Runtime singleton compatibility
+
+`@deepseek-ai/dsh-tools` is a dsh runtime singleton and must resolve to one
+physical package instance in a profile. This provider does not depend on it;
+the requirement belongs to the host profile. If another third-party plugin
+installs `@deepseek-ai/dsh-tools` as a nested regular dependency instead of a
+peer dependency, fix that plugin's dependency declaration or make the profile
+package manager resolve the shared instance before debugging search errors.
+Otherwise dsh's agent loop can fail before the provider is called with an
+error such as `Cannot read properties of undefined (reading 'prepare')`.
+
+## In the Web panel
+
+**Status: configuration is done in the profile patch layer, not the Web UI —
+this version ships no editable UI entry.** The Settings UI only renders cards
+that are hand-registered by client plugins for fixed namespaces (`shell`,
+`agent-loop`, `web-search-deepseek`); it has no generic form for arbitrary
+plugin namespaces. What is true today:
+
+- **Plugin inventory** (Settings → Plugins): the entry appears automatically
+  as `web-search-exa` (`@tonydua/dsh-web-search-exa`) once enabled — the
+  inventory reads the live Cordis loader, no extra code needed.
+- **Settings namespace** (server-side): the plugin registers the
+  `web-search-exa` section via `installSettingsSection`, so the data layer is
+  writable — but **no client card binds to it**, so nothing shows in the UI.
+  The built-in "Web search" card edits the official
+  `web-search-deepseek` namespace, not this plugin.
+- **Changing configuration today**: edit the plugin's `config` in
+  `$DSH_HOME/profiles/web/cordis.patch.yml` (fields and defaults in the table
+  above) and restart `dsh web`; or set `EXA_API_KEY` / `$DSH_WEB_SEARCH_PROVIDER`
+  as environment variables. The `apiKey` field is `role('secret')`: it never
+  appears in `describe()` responses.
+- **Search result cards**: `web_search` calls render the usual `web` cards
+  (sources, snippets, dates) through `dsh-tool-web`, independent of the
+  provider — anonymous Exa results display exactly like DeepSeek ones.
+
+**Roadmap (next version)**: a client-side card registered into the
+`settings.plugin.item` slot bound to the `web-search-exa` namespace, so all
+fields above become editable live in Settings → Plugins (mirroring how the
+official cards work).
+
+## Open-source notes
+
+- License: MIT (see `LICENSE`).
+- Repository: <https://github.com/TonyDua/dsh-web-search-exa>.
+- The package is npm-packable: `publishConfig.access: public`, `files` limited
+  to `lib/`, ESM with an `exports` map and bundled type declarations. Run
+  `npm test` and `npm pack --dry-run` before publishing.
+- To publish: `npm login` (against `registry.npmjs.org`, not the npmmirror
+  default in your `.npmrc`), then
+  `npm publish --registry https://registry.npmjs.org --cache <writable-cache>`.
+  The `@tonydua` scope is claimed on first publish by the publishing account.
+
+## Known limitations
+
+- **Anonymous MCP is rate-limited** (HTTP 429 → `WEB_PROVIDER_ERROR` with a
+  hint). Configure `EXA_API_KEY` for higher limits; the provider then uses the
+  REST path automatically.
+- **Snippet-less results are dropped** (seam rule: no portable snippet).
+  Anonymous MCP usually returns full `Text` blocks, which are truncated to
+  `MAX_SNIPPET_CHARS` (500) for the snippet.
+- **Only `query` + result-count controls are exposed**; recency, domain
+  filters, and deep-search modes are not mapped (they can be added later, as
+  the seam's provider-neutral fields evolve).
+- Anonymous MCP responses are parsed from the `Title:`-section text format;
+  structural changes to Exa's hosted MCP output may require a parser update.
+- **No Web UI settings entry yet** — configuration goes through the profile
+  patch layer (see "In the Web panel").

package/README.zh.md

@@ -0,0 +1,134 @@
+# @tonydua/dsh-web-search-exa
+
+> **使用 [deepseek-v4-flash](https://api-docs.deepseek.com) 与 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）开发。**
+
+为 DeepSeek Harness web 能力 seam（`ctx.web`）提供的 Exa 搜索提供方（`WebSearchProvider`），内置**匿名兜底**：未配置 API key 时，搜索经由 Exa 官方托管的 MCP 服务器（`https://mcp.exa.ai/mcp`）以 JSON-RPC 2.0 发起，**完全不携带任何凭据** —— 即 Exa 官方提供的免认证公共 MCP fallback（有限流）。配置了 `EXA_API_KEY` 时则改用更轻量的 REST 端点。
+
+这是一个**实现**包：它向 `ctx.web` 注册提供方（`inject: ['web']`），不拥有面向模型的工具（后者属于 `@deepseek-ai/dsh-tool-web`）。模型侧的 `web_search` / `web_fetch` 工具、提示词区段与 Web 结果卡片均不受影响。
+
+## 为什么有这个包（与官方包的差异）
+
+DeepSeek Harness 自带官方 Exa 提供方 [`@deepseek-ai/dsh-web-search-exa`](https://www.npmjs.com/package/@deepseek-ai/dsh-web-search-exa)。本包是它的**零配置变体**：补上了官方没有的匿名 MCP 兜底，同时保留配置 key 后的相同 REST 行为。
+
+| | 官方 `@deepseek-ai/dsh-web-search-exa` | 本包 `@tonydua/dsh-web-search-exa` |
+|---|---|---|
+| REST 路径（`POST /search`） | ✅ 唯一路径 | ✅ 配置 key 时使用 |
+| 必须有 API key | ✅ **是——key 为空则不可用** | ❌ 不需要——无 key 走匿名 MCP 兜底 |
+| 匿名 MCP（`mcp.exa.ai/mcp`） | ❌ 未实现 | ✅ 无 key 时默认路径 |
+| 零配置安装 | ❌ | ✅ |
+| Provider id | `exa`（固定） | 默认 `exa`，**可用 `providerId` 配置** |
+| Cordis 插件名 | `web-search-exa` | `web-search-exa` |
+| 配置键 | `apiKey`、`baseURL`、`searchType`、`numResults`、`highlightsPerResult` | `apiKey`、`apiKeyEnv`、`apiURL`、`mcpURL`、`searchType`、`numResults`、`highlightsPerResult`、`providerId` |
+
+## 致谢（Acknowledgements）
+
+匿名 MCP 接入方式参考了 [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) 的 `web_search` 实现（`packages/coding-agent/src/web/search/providers/exa.ts` 与 `src/exa/mcp-client.ts`）以及 [`@oh-my-pi/exa`](https://www.npmjs.com/package/@oh-my-pi/exa) 插件：同样的"有 key 走 REST、无 key 走免凭据 `mcp.exa.ai/mcp`"策略、同样的 `x-exa-source` 来源头、同样的 `Title:` 分节响应解析。感谢 oh-my-pi（omp）项目率先打通了零配置的 Exa 接入。
+
+同时感谢 **[Exa](https://exa.ai)** 提供并运营这个**免费、免认证的托管 MCP 服务器**（`mcp.exa.ai/mcp`）——正是它让本包的零配置默认路径成为可能。Exa 托管 MCP 是 Exa 的官方产品；匿名使用有限流（见"已知限制"）。
+
+## 工作原理
+
+| 条件 | 路径 | 端点 |
+|---|---|---|
+| 配置了 `apiKey` / `EXA_API_KEY` | REST `POST /search`，`Authorization: Bearer` | `https://api.exa.ai/search`（可配置） |
+| 未配置任何 key | 匿名 MCP `tools/call web_search_exa`（JSON-RPC 2.0，无凭据） | `https://mcp.exa.ai/mcp`（可配置） |
+
+匿名 MCP 路径不发送任何凭据，来源标识通过 `x-exa-source: dsh-anything` 头携带。结果按 seam 的 `WebSearchSource` 形状规范化（`url`、`title`、`snippet`、`publishedAt`），`maxResults` 由 seam 在返回路径上强制执行。匿名使用受 Exa 限流：HTTP 429 会以 `WEB_PROVIDER_ERROR` 呈现，并提示配置 API key（配置后自动切换到 REST 路径）。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `providerId` | `exa` | 注册进 `ctx.web` 的提供方 id。仅当本包与官方包同时安装时才需要改（见下一节）。 |
+| `apiKey` | 未设置 | Exa API 密钥字面值。为空/缺失时启用匿名 MCP 路径。 |
+| `apiKeyEnv` | `EXA_API_KEY` | 未设置字面 `apiKey` 时读取的环境变量名。 |
+| `apiURL` | `https://api.exa.ai/search` | REST 搜索端点（仅带 key 的路径使用）。 |
+| `mcpURL` | `https://mcp.exa.ai/mcp` | Exa 托管 MCP 端点（匿名路径使用）。 |
+| `searchType` | `auto` | REST 检索模式：`auto` / `keyword` / `neural`。 |
+| `numResults` | 未设置 | 请求未携带 `maxResults` 时的默认结果数。 |
+| `highlightsPerResult` | `1` | REST 路径每个结果请求的 highlight 句子数。 |
+
+## 与官方包共存
+
+两个包默认在 `ctx.web` 下注册**相同的 provider id（`exa`）**，cordis 插件名也都是 `web-search-exa`。seam 会拒绝重复 id（`WEB_DUPLICATE_PROVIDER`），所以**不改配置就把两个包装进同一个 profile 会在启动时报错**。
+
+**没有黑箱覆盖**——共存必须显式配置，通过 `providerId` 开关完成：
+
+1. 官方包保持 `exa`（它的 id 固定）。
+2. 给本包一个不同 id——在本插件 `config` 里设 `providerId: exa-anon`（任意唯一字符串）。
+3. 在 `web` seam 上显式选中匿名变体：`searchProvider: exa-anon`（或用环境变量 `$DSH_WEB_SEARCH_PROVIDER=exa-anon`）；若还想用官方包，再配 `searchProvider: exa` 切换。
+
+```yaml
+- insert:
+    - id: web-search-exa
+      name: '@tonydua/dsh-web-search-exa'
+      config:
+        providerId: exa-anon
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: exa-anon
+```
+
+最简单的替代方案：每个 profile 只装其中一个包，默认配置即可直接使用。
+
+## 安装（装入 dsh profile）
+
+在本仓库目录下：
+
+```powershell
+dsh plugin --profile web add ../plugins/dsh-web-search-exa
+```
+
+然后启用并选中该提供方。合并进 `$DSH_HOME/profiles/web/cordis.patch.yml`（持久生效）：
+
+```yaml
+- id: web-search-exa
+  name: '@tonydua/dsh-web-search-exa'
+  config:
+    apiKeyEnv: EXA_API_KEY
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: exa
+```
+
+或把 `patches/exa-anon-search.patch.yml` 作为覆盖层传入：
+
+```powershell
+dsh --profile web --patch patches/exa-anon-search.patch.yml
+```
+
+也可以不修改配置，直接用环境变量 `$DSH_WEB_SEARCH_PROVIDER=exa` 在运行时选中该提供方。
+
+重启 `dsh web` 生效。模型侧的 `web_search` 工具随即走该提供方，无需改任何工具配置。
+
+### 运行时单例兼容性
+
+`@deepseek-ai/dsh-tools` 是 dsh 的运行时单例包，一个 profile 中必须解析到同一份物理包实例。本插件本身不依赖它；这是宿主 profile 的依赖约束。如果 profile 中的其他第三方插件把 `@deepseek-ai/dsh-tools` 错误声明成普通嵌套依赖，而不是 peer dependency，应先修正该插件的依赖声明，或让 profile 的包管理器统一解析到共享实例，再排查搜索错误。否则 dsh agent loop 可能在 provider 被调用前就因 `Cannot read properties of undefined (reading 'prepare')` 失败。
+
+## 在 Web 面板中的呈现
+
+**状态：本版本的配置入口在 profile 补丁层，不在 Web UI —— 没有可编辑的界面入口。** Settings UI 只渲染客户端插件为固定命名空间（`shell`、`agent-loop`、`web-search-deepseek`）手工注册的卡片，对任意插件命名空间没有通用表单。当前实际情况：
+
+- **插件清单**（Settings → Plugins）：启用后自动出现 `web-search-exa`（`@tonydua/dsh-web-search-exa`）条目 —— 清单直接读取 Cordis loader 的实时条目，无需额外代码。
+- **设置命名空间**（服务端）：插件通过 `installSettingsSection` 注册了 `web-search-exa` 段，数据层可写——但**没有任何客户端卡片绑定它**，所以界面上不显示。内置的 "Web search" 卡片编辑的是官方 `web-search-deepseek` 命名空间，与本插件无关。
+- **现在怎么改配置**：编辑 `$DSH_HOME/profiles/web/cordis.patch.yml` 里本插件的 `config`（字段与默认值见上方配置表），重启 `dsh web`；或用环境变量 `EXA_API_KEY` / `$DSH_WEB_SEARCH_PROVIDER`。`apiKey` 标记了 `role('secret')`，任何 `describe()` 响应都不会暴露其值。
+- **搜索结果卡片**：`web_search` 调用经 `dsh-tool-web` 照常渲染 `web` 结果卡片（来源、摘要、日期），与提供方无关 —— 匿名 Exa 的结果与 DeepSeek 搜索显示完全一致。
+
+**路线图（下一版本）**：新增注册到 `settings.plugin.item` slot 的客户端卡片，绑定 `web-search-exa` 命名空间，让上表所有字段可以在 Settings → Plugins 里实时编辑（与官方卡片同机制）。
+
+## 开源说明
+
+- 许可证：MIT（见 `LICENSE`）。
+- 仓库：<https://github.com/TonyDua/dsh-web-search-exa>。
+- 包已可执行 npm 打包：`publishConfig.access: public`、`files` 仅含 `lib/`、ESM 且带 `exports` 映射与类型声明。发布前请执行 `npm test` 和 `npm pack --dry-run`。
+- 发布：先 `npm login`（对着 `registry.npmjs.org`，不是 `.npmrc` 里的 npmmirror 默认源），再 `npm publish --registry https://registry.npmjs.org --cache <可写缓存目录>`。`@tonydua` scope 会在首次发布时自动归属到发布账号。
+
+## 已知限制
+
+- **匿名 MCP 有限流**（HTTP 429 → `WEB_PROVIDER_ERROR` 并附提示）。配置 `EXA_API_KEY` 可提额，提供方会自动切到 REST 路径。
+- **无 snippet 的结果会被丢弃**（seam 规则：没有可移植的摘要）。匿名 MCP 通常返回完整 `Text` 块，会截断到 `MAX_SNIPPET_CHARS`（500 字符）作为 snippet。
+- **只暴露查询与结果数控制**：新近程度、域名过滤、深度搜索等尚未映射（可等 seam 的提供方无关字段扩展后补充）。
+- 匿名 MCP 响应按 `Title:` 分节文本格式解析；Exa 托管 MCP 输出结构变化时可能需要更新解析器。
+- **暂无 Web UI 设置入口**——配置走 profile 补丁层（见"在 Web 面板中的呈现"）。

package/lib/index.js

@@ -0,0 +1,431 @@
+/**
+ * @tonydua/dsh-web-search-exa
+ *
+ * Exa-backed `WebSearchProvider` for the DeepSeek Harness web capability seam
+ * (`ctx.web`), with an **anonymous** fallback: when no API key is configured,
+ * search routes through Exa's hosted MCP server (`https://mcp.exa.ai/mcp`) via
+ * JSON-RPC 2.0 with no credentials — Exa's documented unauthenticated public
+ * MCP fallback (rate-limited). With a key, the lighter REST endpoint
+ * (`POST {apiURL}`) is used instead, mirroring `@deepseek-ai/dsh-web-search-exa`.
+ *
+ * The anonymous-MCP strategy and its response parsing follow the `web_search`
+ * implementation in can1357/oh-my-pi (see README acknowledgements).
+ *
+ * This is an implementation package: it registers a provider INTO `ctx.web`
+ * (`inject: ['web']`) and owns no model-facing tools (those belong to
+ * `@deepseek-ai/dsh-tool-web`). It also installs a Settings section
+ * (`web-search-exa`) into the settings service; editing it from the Web UI
+ * needs a client card (planned for a later version) — today it is configured
+ * through the profile patch layer (see README "In the Web panel").
+ */
+
+import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { WebError } from "@deepseek-ai/dsh-web";
+import z from "@deepseek-ai/schemastery";
+
+/** Default provider id this provider registers under (`ctx.web` registry key). */
+const DEFAULT_PROVIDER_ID = "exa";
+/** Backward-compatible alias for the default provider id. */
+const PROVIDER_ID = DEFAULT_PROVIDER_ID;
+/** Exa REST search endpoint; used only when an API key is configured. */
+const DEFAULT_API_URL = "https://api.exa.ai/search";
+/** Exa hosted MCP endpoint; the anonymous fallback path. */
+const DEFAULT_MCP_URL = "https://mcp.exa.ai/mcp";
+/** Environment variable consulted when no literal `apiKey` is configured. */
+const DEFAULT_API_KEY_ENV = "EXA_API_KEY";
+/** Default retrieval mode for the REST path: let Exa pick. */
+const DEFAULT_SEARCH_TYPE = "auto";
+/** Default number of highlight sentences requested per result (REST path). */
+const DEFAULT_HIGHLIGHTS_PER_RESULT = 1;
+/** MCP tool name for plain web search on Exa's hosted server. */
+const MCP_TOOL = "web_search_exa";
+/** Attribution header sent on anonymous MCP requests. Bump with the version. */
+const MCP_SOURCE = "dsh-anything";
+/** User agent for REST requests. */
+const USER_AGENT = "deepseek-harness-exa/0.1.0";
+/** Snippet cap for text-derived snippets (matching oh-my-pi's choice). */
+const MAX_SNIPPET_CHARS = 500;
+/** Settings namespace carrying this provider's configuration. */
+const SETTINGS_NAMESPACE = settingsNamespace("web-search-exa");
+
+/** True for a positive whole number (cheap local config check). */
+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";
+}
+
+/** Throw the seam's stable cancellation error when the caller is already aborted. */
+function throwIfAborted(signal) {
+	if (signal?.aborted === true) {
+		throw new WebError("Exa search aborted", "WEB_ABORTED", { cause: signal.reason });
+	}
+}
+
+/**
+ * Resolve the API key: literal config first, then the environment variable.
+ * `undefined` means the anonymous MCP path is used.
+ */
+function resolveApiKey(options) {
+	if (options.apiKey != null && options.apiKey.length > 0) return options.apiKey;
+	const fromEnv = process.env[options.apiKeyEnv];
+	if (fromEnv != null && fromEnv.length > 0) return fromEnv;
+	return undefined;
+}
+
+// ── REST path (with API key) ────────────────────────────────────────────────
+
+/**
+ * Map one Exa REST result to a normalized source, or `undefined` when it has
+ * no portable snippet (same rule as the official provider).
+ */
+function mapRestResult(result) {
+	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 } : {},
+	};
+}
+
+// ── Anonymous MCP path (no API key) ─────────────────────────────────────────
+
+/**
+ * Parse an SSE (`text/event-stream`) response body into its first `data:`
+ * payload, falling back to plain JSON. Returns `null` when neither parses.
+ */
+function parseSsePayload(text) {
+	const dataLines = text.split(/\r?\n/)
+		.filter((line) => line.startsWith("data:"))
+		.map((line) => line.slice(5).replace(/^\s/, ""));
+	if (dataLines.length > 0) {
+		try {
+			return JSON.parse(dataLines.join("\n"));
+		} catch {
+			return null;
+		}
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Collect non-blank `content[].text` blocks from a normalized MCP result
+ * payload, joined with blank lines.
+ */
+function collectMcpText(payload) {
+	const content = payload?.result?.content;
+	if (!Array.isArray(content)) return [];
+	return content
+		.map((item) => (typeof item?.text === "string" ? item.text.replace(/\r\n?/g, "\n").trim() : ""))
+		.filter((text) => text.length > 0);
+}
+
+/**
+ * Parse one `Title:`-led section of Exa MCP text output into a partial source.
+ * Handles both `Published:` and `Published Date:` field spellings.
+ */
+function parseExaSection(section) {
+	const out = {};
+	let field = null;
+	let textLines = null;
+	for (const line of section.split("\n")) {
+		const title = line.match(/^Title:\s*(.*)$/);
+		const url = line.match(/^URL:\s*(.*)$/);
+		const published = line.match(/^Published(?: Date)?:\s*(.*)$/);
+		const author = line.match(/^Author:\s*(.*)$/);
+		if (title) {
+			out.title = title[1].trim();
+			field = null;
+		} else if (url) {
+			out.url = url[1].trim();
+			field = null;
+		} else if (published) {
+			out.publishedAt = published[1].trim();
+			field = null;
+		} else if (author) {
+			out.author = author[1].trim();
+			field = null;
+		} else if (/^Highlights:\s*$/.test(line)) {
+			field = "highlights";
+		} else if (/^Text:\s*$/.test(line)) {
+			field = "text";
+			textLines = [];
+		} else if (field === "highlights") {
+			const trimmed = line.trim();
+			if (trimmed.length > 0) {
+				out.highlights ??= [];
+				out.highlights.push(trimmed.replace(/^[-•]\s*/, ""));
+			}
+		} else if (field === "text" && textLines !== null) {
+			textLines.push(line);
+		}
+	}
+	if (textLines !== null) out.text = textLines.join("\n").trim();
+	if (out.publishedAt === "N/A") delete out.publishedAt;
+	if (out.author === "N/A") delete out.author;
+	return out;
+}
+
+/** Split joined MCP text into per-result sections, each starting with `Title:`. */
+function splitExaSections(joined) {
+	return joined
+		.split(/\n{2,}(?=Title:\s*)/)
+		.map((section) => section.trim())
+		.filter((section) => section.length > 0 && section.startsWith("Title:"));
+}
+
+/** Map parsed Exa MCP sections to normalized sources (snippet-less entries dropped). */
+function mapMcpSections(sections) {
+	const sources = [];
+	for (const section of sections) {
+		const parsed = parseExaSection(section);
+		if (!parsed.url || parsed.url.length === 0) continue;
+		const highlight = parsed.highlights?.find((item) => item.trim().length > 0);
+		const snippet = highlight ?? (parsed.text ? parsed.text.slice(0, MAX_SNIPPET_CHARS) : undefined);
+		if (snippet === undefined) continue;
+		sources.push({
+			url: parsed.url,
+			...parsed.title != null && parsed.title.length > 0 ? { title: parsed.title } : {},
+			snippet,
+			...parsed.publishedAt != null && parsed.publishedAt.length > 0 ? { publishedAt: parsed.publishedAt } : {},
+		});
+	}
+	return sources;
+}
+
+// ── Provider ────────────────────────────────────────────────────────────────
+
+/**
+ * Project one resolved configuration section into the options the provider
+ * serves its next search with. Called per operation so live Settings edits
+ * take effect on the next search.
+ */
+function resolveOptions(section) {
+	return {
+		providerId: section.providerId ?? DEFAULT_PROVIDER_ID,
+		apiKey: section.apiKey ?? "",
+		apiKeyEnv: section.apiKeyEnv ?? DEFAULT_API_KEY_ENV,
+		apiURL: section.apiURL ?? DEFAULT_API_URL,
+		mcpURL: section.mcpURL ?? DEFAULT_MCP_URL,
+		searchType: section.searchType ?? DEFAULT_SEARCH_TYPE,
+		numResults: section.numResults,
+		highlightsPerResult: section.highlightsPerResult ?? DEFAULT_HIGHLIGHTS_PER_RESULT,
+	};
+}
+
+class ExaSearchProvider {
+	resolveOptions;
+	id;
+
+	/**
+	 * @param resolveOptions - thunk returning the options for the NEXT
+	 * operation, snapshotted once at each operation's entry so one search
+	 * never mixes two settings sections (same pattern as the official
+	 * DeepSeek provider).
+	 */
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+		this.id = resolveOptions().providerId ?? PROVIDER_ID;
+	}
+
+	/** The anonymous MCP path needs no credentials, so the provider is always usable. */
+	available() {
+		const options = this.resolveOptions();
+		return URL.canParse(options.apiURL) && URL.canParse(options.mcpURL);
+	}
+
+	async search(request, signal) {
+		throwIfAborted(signal);
+		const options = this.resolveOptions();
+		const apiKey = resolveApiKey(options);
+		return apiKey !== undefined
+			? await this.#restSearch(request, apiKey, options, signal)
+			: await this.#anonymousMcpSearch(request, options, signal);
+	}
+
+	/** REST search with an API key: `POST {apiURL}` with Bearer auth. */
+	async #restSearch(request, apiKey, options, signal) {
+		throwIfAborted(signal);
+		const numResults = request.maxResults ?? options.numResults;
+		let response;
+		try {
+			response = await fetch(options.apiURL, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"authorization": `Bearer ${apiKey}`,
+					"content-type": "application/json",
+					"accept": "application/json",
+					"user-agent": USER_AGENT,
+				},
+				body: JSON.stringify({
+					query: request.query,
+					type: options.searchType,
+					contents: { highlights: { highlightsPerUrl: options.highlightsPerResult } },
+					...numResults !== undefined ? { numResults } : {},
+				}),
+				...signal !== undefined ? { signal } : {},
+			});
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw new WebError("Exa search aborted", "WEB_ABORTED", { cause: signal?.reason ?? 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 !== undefined && detail.length > 0) message = detail;
+			} catch (error) {
+				if (signal?.aborted === true || isAbortError(error)) throw new WebError("Exa search aborted", "WEB_ABORTED", { cause: signal?.reason ?? error });
+				// keep the generic message
+			}
+			throw new WebError(message, "WEB_PROVIDER_ERROR");
+		}
+		let parsed;
+		try {
+			parsed = await response.json();
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw new WebError("Exa search aborted", "WEB_ABORTED", { cause: signal?.reason ?? error });
+			throw new WebError(`Exa returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		const sources = (parsed.results ?? []).map(mapRestResult).filter((source) => source !== undefined);
+		return { sources, truncated: false };
+	}
+
+	/**
+	 * Anonymous search through Exa's hosted MCP server. No credentials are
+	 * sent; the `x-exa-source` header carries attribution. Rate-limited by Exa
+	 * (HTTP 429) — configuring an API key lifts the limit via the REST path.
+	 */
+	async #anonymousMcpSearch(request, options, signal) {
+		throwIfAborted(signal);
+		const args = { query: request.query };
+		const numResults = request.maxResults ?? options.numResults;
+		if (numResults !== undefined) args.numResults = numResults;
+		let response;
+		try {
+			response = await fetch(options.mcpURL, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"content-type": "application/json",
+					"accept": "application/json, text/event-stream",
+					"x-exa-source": MCP_SOURCE,
+				},
+				body: JSON.stringify({
+					jsonrpc: "2.0",
+					id: Math.random().toString(36).slice(2),
+					method: "tools/call",
+					params: { name: MCP_TOOL, arguments: args },
+				}),
+				...signal !== undefined ? { signal } : {},
+			});
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw new WebError("Exa anonymous search aborted", "WEB_ABORTED", { cause: signal?.reason ?? error });
+			throw new WebError(`Exa anonymous search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (!response.ok) {
+			if (response.status === 429) {
+				throw new WebError(
+					"Exa anonymous MCP rate limit reached (HTTP 429); configure an EXA_API_KEY for higher limits",
+					"WEB_PROVIDER_ERROR",
+				);
+			}
+			throw new WebError(`Exa anonymous MCP error (HTTP ${response.status})`, "WEB_PROVIDER_ERROR");
+		}
+		let payload;
+		try {
+			payload = parseSsePayload(await response.text());
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw new WebError("Exa anonymous search aborted", "WEB_ABORTED", { cause: signal?.reason ?? error });
+			throw new WebError(`Exa returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (payload === null) {
+			throw new WebError("Exa anonymous MCP returned an unprocessable response body", "WEB_PROVIDER_ERROR");
+		}
+		if (payload.error != null) {
+			throw new WebError(`Exa MCP error: ${String(payload.error.message ?? JSON.stringify(payload.error))}`, "WEB_PROVIDER_ERROR");
+		}
+		if (payload.result?.isError === true) {
+			const detail = collectMcpText(payload).join("\n").trim();
+			throw new WebError(`Exa MCP tool error${detail.length > 0 ? `: ${detail}` : ""}`, "WEB_PROVIDER_ERROR");
+		}
+		const sections = splitExaSections(collectMcpText(payload).join("\n\n"));
+		const sources = mapMcpSections(sections);
+		return { sources, truncated: false };
+	}
+}
+
+// ── Cordis plugin wiring ────────────────────────────────────────────────────
+
+/** 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({
+	/**
+	 * Provider id registered into `ctx.web`. Defaults to `exa` (same as the
+	 * official `@deepseek-ai/dsh-web-search-exa`). Change it only when BOTH
+	 * packages are installed in one profile — the seam rejects duplicate ids
+	 * with `WEB_DUPLICATE_PROVIDER`. There is no silent override: pick a
+	 * distinct id here (e.g. `exa-anon`) and select it explicitly with
+	 * `searchProvider` / `$DSH_WEB_SEARCH_PROVIDER`.
+	 */
+	providerId: z.string().default(DEFAULT_PROVIDER_ID),
+	/** Literal Exa API key; an empty/missing value enables the anonymous MCP path. */
+	apiKey: z.string().role("secret"),
+	/** Environment variable consulted when no literal `apiKey` is configured. */
+	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+	/** REST search endpoint, used only when an API key is available. */
+	apiURL: z.string().default(DEFAULT_API_URL),
+	/** Exa hosted MCP endpoint, used by the anonymous fallback. */
+	mcpURL: z.string().default(DEFAULT_MCP_URL),
+	/** REST retrieval mode: `auto`, `keyword`, or `neural`. */
+	searchType: z.union(["auto", "keyword", "neural"]).default(DEFAULT_SEARCH_TYPE),
+	/** Default result count when the request carries no `maxResults`. */
+	numResults: z.number().step(1).min(1),
+	/** Highlight sentences requested per result on the REST path. */
+	highlightsPerResult: z.number().step(1).min(1).default(DEFAULT_HIGHLIGHTS_PER_RESULT),
+});
+
+/**
+ * Register the Exa search provider with `ctx.web` and install its Settings
+ * section, so the Web panel edits the same config the provider serves.
+ */
+function apply(ctx, config) {
+	let current = () => config;
+	installSettingsSection(ctx, SETTINGS_NAMESPACE, Config, config, {
+		setSource: (source) => {
+			current = source;
+		},
+		onChange: () => {},
+	});
+	ctx.web.registerSearchProvider(new ExaSearchProvider(() => resolveOptions(current())));
+}
+
+export {
+	Config,
+	DEFAULT_API_KEY_ENV,
+	DEFAULT_API_URL,
+	DEFAULT_HIGHLIGHTS_PER_RESULT,
+	DEFAULT_MCP_URL,
+	DEFAULT_PROVIDER_ID,
+	DEFAULT_SEARCH_TYPE,
+	PROVIDER_ID,
+	SETTINGS_NAMESPACE,
+	ExaSearchProvider,
+	apply,
+	inject,
+	name,
+};

package/lib/types/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Type declarations for `@tonydua/dsh-web-search-exa`.
+ * @module @tonydua/dsh-web-search-exa
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { WebSearchProvider } from '@deepseek-ai/dsh-web';
+
+/** Config schema type (fields are optional at the load boundary). */
+export interface ExaSearchProviderConfig {
+	/** Literal Exa API key; empty/missing enables the anonymous MCP path. */
+	apiKey?: string;
+	/** Environment variable consulted when no literal `apiKey` is configured. */
+	apiKeyEnv?: string;
+	/** REST search endpoint, used only when an API key is available. */
+	apiURL?: string;
+	/** Exa hosted MCP endpoint, used by the anonymous fallback. */
+	mcpURL?: string;
+	/** REST retrieval mode: `auto`, `keyword`, or `neural`. */
+	searchType?: 'auto' | 'keyword' | 'neural';
+	/** Default result count when the request carries no `maxResults`. */
+	numResults?: number;
+	/** Highlight sentences requested per result on the REST path. */
+	highlightsPerResult?: number;
+}
+
+/** The Exa-backed provider with anonymous MCP fallback. */
+export class ExaSearchProvider implements WebSearchProvider {
+	readonly id: string;
+	constructor(resolveOptions: () => {
+		apiKey: string;
+		apiKeyEnv: string;
+		apiURL: string;
+		mcpURL: string;
+		searchType: 'auto' | 'keyword' | 'neural';
+		numResults?: number;
+		highlightsPerResult: number;
+	});
+	available(): boolean;
+	search(request: { query: string; maxResults?: number }, signal?: AbortSignal): Promise<{
+		sources: ReadonlyArray<{ url: string; title?: string; snippet?: string; publishedAt?: string }>;
+		truncated: boolean;
+	}>;
+}
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name: string;
+/** The web seam this provider registers into. */
+export const inject: readonly ['web'];
+/** Config schema (schemastery). */
+export const Config: import('@deepseek-ai/schemastery').Schema<ExaSearchProviderConfig>;
+/** Settings namespace for the Web panel section. */
+export const SETTINGS_NAMESPACE: string;
+/** Register the Exa search provider with `ctx.web` and install its Settings section. */
+export function apply(ctx: Context, config: ExaSearchProviderConfig): void;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@tonydua/dsh-web-search-exa",
+  "description": "Exa-backed WebSearchProvider for the DeepSeek Harness web capability seam (ctx.web), with an anonymous MCP fallback — no API key required",
+  "version": "0.1.0",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "cordis",
+    "exa",
+    "web-search",
+    "anonymous"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TonyDua/dsh-web-search-exa.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/index.test.js"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-web": "^0.1.0-rc.6"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-web": "^0.1.0-rc.6"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}