@240xu/dsh-websearch 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xu198440 (ova442757@163.com)
+
+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.md

@@ -0,0 +1,136 @@
+# @240xu/dsh-websearch
+
+> Aggregated web search provider for [DeepSeek Harness](https://github.com/deepseek-ai/dsh) — one plugin id `unified` that fans out to eleven backends concurrently, merges + URL-dedups results, and stays usable even when some backends go down.
+
+A pure-Cordis drop-in: registers ONE provider at `ctx.web` so the `dsh-web` selection rule never fires `WEB_PROVIDER_AMBIGUOUS`. Zero-config search out of the box (Exa + Parallel + DuckDuckGo + SearXNG are keyless); API-key backends (DeepSeek / Anthropic / OpenAI / Brave / Tavily / Serper / Mojeek) auto-activate once their key is supplied via the credentials service or env.
+
+---
+
+DSH（[DeepSeek Harness](https://github.com/deepseek-ai/dsh)）原生插件：向 `ctx.web` 注册**唯一**的聚合搜索 provider `unified`，内置十一后端并发 fan-out，合并 + URL 去重后返回——即使部分后端宕机仍可用。
+
+纯 Cordis 直插：只注册一个 provider，所以 `dsh-web` 的选择规则永远不会触发 `WEB_PROVIDER_AMBIGUOUS`。**零配置即可搜索**——Exa + Parallel + DuckDuckGo + SearXNG 四者皆无 key、开箱即用；DeepSeek / Anthropic / OpenAI / Brave / Tavily / Serper / Mojeek 在提供 API key 后自动激活。
+
+## Backends | 后端
+
+| id | key | endpoint | how it returns | notes |
+|---|---|---|---|---|
+| `exa` | none | `https://mcp.exa.ai/mcp` | streamable-http MCP, tool `web_search_exa { query, numResults }`, text blocks "Title:/URL:/Published:/Highlights:" | opencode 同源,无 key |
+| `parallel` | none | `https://search.parallel.ai/mcp` | streamable-http MCP, tool `web_search { objective, search_queries[], session_id?, model_name? }` returns JSON-string `{ search_id, results: [{ url, title, publish_date, excerpts[] }] }` | opencode 同源,无 key |
+| `ddg` | none | `https://html.duckduckgo.com/html/` | HTML scrape, decode `uddg=` redirect param for real URL + `result__snippet` | 兜底,零依赖 |
+| `searxng` | none/optional | `https://searx.be/search` (default) | REST JSON `/search?q=`, public instances unlimited | 元搜索,隐私友好 |
+| `brave` | `BRAVE_API_KEY` | `https://api.search.brave.com/res/v1/web/search` | REST JSON, independent index, 2000/mo free | 高质量,无 Google 偏见 |
+| `tavily` | `TAVILY_API_KEY` | `https://api.tavily.com/search` | REST JSON, AI-focused, `answer` + `results[]`, deep search | AI 专用,含答案摘要 |
+| `serper` | `SERPER_API_KEY` | `https://google.serper.dev/search` | REST JSON, scrapes Google `organic[]`, 2500/mo free | 极速,结构化 |
+| `mojeek` | `MOJEEK_API_KEY` | `https://api.mojeek.com/v1/search` | REST JSON, independent index, 1000/day free | 无追踪,英文为主 |
+| `deepseek` | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/anthropic/v1/messages` | Anthropic Messages API + native `web_search_20250305` server tool, model `deepseek-v4-flash` | 与 dav web-search-deepseek 同机制 |
+| `anthropic` | `ANTHROPIC_API_KEY` | `https://api.anthropic.com/v1/messages` | Anthropic Messages + `web_search_20250305`, model `claude-sonnet-4-6` | Claude Code 同机制 |
+| `openai` | `OPENAI_API_KEY` | `https://api.openai.com/v1/responses` | Responses API native `web_search` tool, parse `url_citation` annotations | Codex 同机制 |
+
+**Default enabled set**: `["exa", "parallel", "ddg", "searxng"]` — all keyless. The key-gated backends only join when their `available()` returns true (key present + baseURL reachable).
+
+## Install | 安装
+
+### 方式一：作为 profile 依赖安装（推荐，规范做法）
+
+```bash
+cd ~/.dsh/profiles/web
+# 在 package.json 的 dependencies 里加入：
+#   "@240xu/dsh-websearch": "file:/path/to/@240xu/dsh-websearch"
+pnpm install
+```
+
+插件自带 `dsh.bundle` 元数据（package.json 声明 `"dsh": {"bundle": {"patch": "./cordis.patch.yml"}}`），把它加入 profile package.json 的 `dsh.profile.bundles` 列表后即自动注册，**无需**在 cordis.patch.yml 手写条目。
+
+只需在 `~/.dsh/profiles/web/cordis.patch.yml` 里把内置 web_search 工具指到 unified provider：
+
+```yaml
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: unified
+- id: web-search-deepseek
+  name: '@deepseek-ai/dsh-web-search-deepseek'
+  disabled: true
+```
+
+重启 `dsh web` 即生效。
+
+## Settings | 配置
+
+插件向 DSH 设置面板注册 `unified-search` namespace（Settings → Unified Search），全部字段扁平化、开箱可编辑：
+
+**全局**
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `numResults` | 8 | 每次搜索返回结果数（1-50） |
+| `concurrency` | 6 | 并发后端数（1-10） |
+| `backendTimeoutMs` | 30000 | 单后端超时毫秒 |
+
+**11 个后端开关**：`enableExa` / `enableParallel` / `enableDdg` / `enableSearxng`（默认开）；`enableBrave` / `enableTavily` / `enableSerper` / `enableMojeek` / `enableDeepseek` / `enableAnthropic` / `enableOpenai`（默认关）
+
+**API Key 授权**（credential-ref，填环境变量名，实际 key 存于 credentials 服务或环境变量）：
+
+| 字段 | 默认引用 |
+|---|---|
+| `braveApiKeyEnv` | `BRAVE_API_KEY` |
+| `tavilyApiKeyEnv` | `TAVILY_API_KEY` |
+| `serperApiKeyEnv` | `SERPER_API_KEY` |
+| `mojeekApiKeyEnv` | `MOJEEK_API_KEY` |
+| `deepseekApiKeyEnv` | `DEEPSEEK_API_KEY` |
+| `anthropicApiKeyEnv` | `ANTHROPIC_API_KEY` |
+| `openaiApiKeyEnv` | `OPENAI_API_KEY` |
+| `searxngApiKeyEnv` | `SEARXNG_API_KEY`（私有实例可选） |
+
+**Base URL / Model**：每个 key-gated 后端都有对应 `${id}BaseURL`；DeepSeek/Anthropic/OpenAI 另有 `${id}Model`；Tavily 有 `tavilySearchDepth`（basic/advanced）。
+
+环境变量兜底：未在 credentials 配置时回退读同名环境变量；`DSH_UNIFIED_SEARCH_BACKENDS` 可逗号分隔强制指定启用集合。
+
+## Design | 设计
+
+- **One provider, no ambiguity**: a single `registeredSearchProvider({id:"unified"})` — the `dsh-web` seam's selection rule picks it unambiguously, and `search()` caps `maxResults` itself.
+- **`Promise.allSettled` fan-out**: every enabled + available backend fires concurrently; a single backend failure is demoted to a soft `null` so the rest still contribute — only when ALL fail does the provider throw `WEB_PROVIDER_ERROR`.
+- **Per-backend abort demotion**: a single backend aborting becomes soft-null; the provider only rethrows `WEB_ABORTED` when the caller's own `AbortSignal` fires.
+- **URL dedup + merge**: results across backends are merged and deduped by case-insensitive URL; missing title/snippet/publishedAt from one backend get filled in from another (e.g. Exa's title + Parallel's excerpt).
+- **Concurrency & Timeout Control**: `concurrency` (default 6) limits simultaneous calls; `backendTimeoutMs` (default 30s) caps each backend.
+- **Streamable-http MCP, custom handshake**: `lib/util/mcp-client.js` implements `initialize → notifications/initialized → tools/call` with `Mcp-Session-Id` header caching against Exa and Parallel — no dependency on the full MCP SDK.
+- **hooks.recordRequest/recordOutcome bridge**: each backend routes its request/outcome to `lib/util/log.js` which records `web/unified-search-backend-request` / `…backend-outcome` events onto the active DSH session via `ctx.get("agents")?.currentInitiator()?.session.append(...)` (mirrors `dsh-web-search-deepseek`).
+
+## Architecture | 架构
+
+```
+lib/
+  index.js                 # name/inject/Config/apply — registers settings + provider
+  provider.js              # UnifiedSearchProvider — fan-out, abort demotion, dedup, truncate, concurrency, timeout
+  util/
+    abort.js               # isAbortError / searchAborted / throwIfSearchAborted / maybeAbortError
+    mcp-client.js          # streamable-http MCP client (initialize + tools/call + session cache)
+    log.js                 # recordBackendRequest / recordBackendOutcome → session event log
+  backends/
+    exa.js                 # Exa (web_search_exa) via mcp-client
+    parallel.js            # Parallel (web_search) via mcp-client
+    ddg.js                 # DuckDuckGo HTML scrape (uddg redirect decode)
+    searxng.js             # SearXNG REST JSON (keyless)
+    brave.js               # Brave Search REST (key-gated)
+    tavily.js              # Tavily REST (key-gated, AI answer + deep search)
+    serper.js              # Serper.dev REST (key-gated, Google scrape)
+    mojeek.js              # Mojeek REST (key-gated)
+    anthropic-like.js      # shared: DeepSeek + Anthropic (Messages API + web_search_* server tool)
+    openai.js              # OpenAI /responses + web_search tool (url_citation parsing)
+    index.js               # unified registry + individual exports
+tests/
+  parse.test.js            # 28 unit tests for each backend's pure parse fn
+  provider.test.js         # 5 fan-out tests (merge/dedup, abort demotion, all-fail, maxResults cap, concurrency)
+```
+
+## Test | 测试
+
+```bash
+node --test tests/parse.test.js tests/provider.test.js
+```
+
+33/33 pass.
+
+## License | 许可
+
+MIT © 2026 240xu

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-websearch
+      name: '@240xu/dsh-websearch'

package/examples/cordis.patch.yml

@@ -0,0 +1,17 @@
+# ── dsh-websearch v2.0: unified free web search ───────────────────────
+# Registers provider id "unified" that fans out to 11 backends concurrently:
+#   keyless:    exa, parallel, ddg, searxng
+#   key-gated:  deepseek, anthropic, openai, brave, tavily, serper, mojeek
+#               (activate when their API key is set via Settings > Unified Search)
+#
+# web-search-deepseek stays disabled because the unified plugin supersedes it.
+# web.searchProvider pins the built-in web_search tool onto the unified provider.
+- id: unified-search
+  name: "@deepseek-ai/dsh-websearch"
+- id: web-search-deepseek
+  name: "@deepseek-ai/dsh-web-search-deepseek"
+  disabled: true
+- id: web
+  name: "@deepseek-ai/dsh-web"
+  config:
+    searchProvider: unified

package/lib/backends/anthropic-like.js

@@ -0,0 +1,262 @@
+// anthropic-like.js — shared backend for DeepSeek & Anthropic Messages-API
+// providers using the native web_search server tool. Both speak the
+// Anthropic-compatible Messages API; they differ only in baseURL, default
+// model name, and api-version header. DeepSeek's endpoint is
+// https://api.deepseek.com/anthropic/v1 (note the /anthropic prefix — chat
+// completions use a different base, NOT reused here).
+//
+// Response shape (Anthropic Messages format):
+//   content: [
+//     { type: "web_search_tool_result", content: [ { type:"web_search_result", url, title, page_age }, ... ] },
+//     { type: "text", text, citations:[{url, cited_text}] },
+//     ...
+//   ]
+// The snippet comes from a text block's citation[] (keyed by url, first match
+// wins). Each search costs a model turn; absence of a web_search_tool_result
+// block is an error, not a prose fallback.
+
+import { throwIfSearchAborted, searchAborted, isAbortError } from "../util/abort.js";
+import { WebError } from "@deepseek-ai/dsh-web";
+
+/** Attribution header; bumped with the package version. */
+const UA = "dsh-websearch/2.0";
+
+/**
+ * Factory: create an Anthropic-like Messages backend.
+ *
+ * @param {object} spec
+ * @param {string} spec.id          backend id ("deepseek" | "anthropic")
+ * @param {string} spec.defaultBaseURL
+ * @param {string} spec.defaultModel
+ * @param {string} spec.defaultApiVersion   e.g. "2023-06-01"
+ * @param {string} spec.toolName            "web_search_20250305"
+ * @param {string} [spec.futureToolName]    optional newer tool for dual fallback
+ * @returns {object} backend object { id, requiresCredential, available, search }
+ */
+export function createAnthropicLikeBackend(spec) {
+  const {
+    id,
+    defaultBaseURL,
+    defaultModel,
+    defaultApiVersion,
+    toolName,
+    futureToolName,
+  } = spec;
+
+  return {
+    id,
+    requiresCredential: true,
+
+    /**
+     * options provider by provider.js: { apiKey, baseURL?, model?, apiVersion?, maxTokens?, maxUses?, apiVersion }
+     */
+    available(options) {
+      // Per the official reference impl (dsh-web-search-deepseek): a backend is
+      // usable when it has either a literal apiKey OR a lazy resolver function —
+      // availability is a cheap local check, the key is resolved per search.
+      const okKey = (typeof options?.apiKey === "string" && options.apiKey.length > 0)
+        || typeof options?.resolveApiKey === "function";
+      const urlOk = typeof options?.baseURL === "string" && URL.canParse(options.baseURL);
+      return okKey && urlOk;
+    },
+
+    /**
+     * @param {WebSearchRequest} request
+     * @param {AbortSignal} signal
+     * @param {object} options   resolved options (apiKey, baseURL, model, apiVersion, maxTokens, maxUses)
+     * @param {{ recordRequest?: Function, recordOutcome?: Function }} [hooks]
+     * @returns {Promise<WebSearchResult>}
+     */
+    async search(request, signal, options, hooks = {}) {
+      throwIfSearchAborted(signal);
+      const apiKey = options?.apiKey ?? await options?.resolveApiKey?.();
+      if (!apiKey || apiKey.length === 0) {
+        hooks.recordOutcome?.({ status: "error", message: "credential missing" });
+        throw new WebError(
+          `${id} search has no API key`,
+          "WEB_PROVIDER_CREDENTIAL_MISSING",
+        );
+      }
+
+      const baseURL = options.baseURL || defaultBaseURL;
+      const model = options.model || defaultModel;
+      const apiVersion = options.apiVersion || defaultApiVersion;
+      const maxTokens = options.maxTokens ?? 4096;
+      const maxUses = options.maxUses ?? 5;
+      const endpoint = `${baseURL.replace(/\/$/, "")}/messages`;
+
+      const body = {
+        model,
+        max_tokens: maxTokens,
+        messages: [
+          {
+            role: "user",
+            content: [
+              {
+                type: "text",
+                text: `Perform a web search for the query: ${request.query}`,
+              },
+            ],
+          },
+        ],
+        tools: [{ type: toolName, name: "web_search", max_uses: maxUses }],
+      };
+
+      hooks.recordRequest?.({
+        endpoint,
+        toolName: `${id}:web_search`,
+        body: { model, max_tokens: maxTokens, max_uses: maxUses, query: request.query },
+        headers: { "anthropic-version": apiVersion },
+      });
+
+      throwIfSearchAborted(signal);
+
+      let response;
+      try {
+        response = await fetch(endpoint, {
+          method: "POST",
+          redirect: "error",
+          headers: {
+            "x-api-key": apiKey,
+            "authorization": `Bearer ${apiKey}`,
+            "anthropic-version": apiVersion,
+            "content-type": "application/json",
+            "accept": "application/json",
+            "user-agent": UA,
+          },
+          body: JSON.stringify(body),
+          ...(signal !== undefined ? { signal } : {}),
+        });
+      } catch (err) {
+        if (signal?.aborted === true || isAbortError(err)) throw searchAborted(signal, err);
+        hooks.recordOutcome?.({ status: "error", message: String(err?.message ?? err) });
+        throw new WebError(
+          `${id} search request failed: ${String(err?.message ?? err)}`,
+          "WEB_PROVIDER_ERROR",
+          { cause: err },
+        );
+      }
+
+      if (!response.ok) {
+        let message = `${id} API error (HTTP ${response.status})`;
+        try {
+          const parsed = await response.json();
+          const detail =
+            typeof parsed.error === "string"
+              ? parsed.error
+              : parsed.error?.message ?? parsed.message;
+          if (detail !== undefined && detail.length > 0) message = detail;
+        } catch (err) {
+          if (signal?.aborted === true || isAbortError(err)) throw searchAborted(signal, err);
+        }
+        hooks.recordOutcome?.({ status: "error", message });
+        throw new WebError(message, "WEB_PROVIDER_ERROR");
+      }
+
+      try {
+        const result = mapAnthropicResponse(await response.json(), id, futureToolName);
+        hooks.recordOutcome?.({ status: "ok", sources: result.sources.length });
+        return { sources: result.sources, content: undefined, truncated: false };
+      } catch (err) {
+        if (signal?.aborted === true || isAbortError(err)) throw searchAborted(signal, err);
+        if (err instanceof WebError) {
+          hooks.recordOutcome?.({ status: "error", message: err.message });
+          throw err;
+        }
+        hooks.recordOutcome?.({ status: "error", message: String(err?.message ?? err) });
+        throw new WebError(
+          `${id} returned an unprocessable response body: ${String(err?.message ?? err)}`,
+          "WEB_PROVIDER_ERROR",
+          { cause: err },
+        );
+      }
+    },
+  };
+}
+
+/**
+ * Optional dual-tool fallback: try the newer tool first; if that tool name is
+ * rejected by the API (HTTP error mapping is upstream of us), the provider
+ * retries with the established fallback. Here we just expose both — the
+ * provider loops through candidates and uses whichever result block appears.
+ */
+export function tryDualToolResponse(response, id, primaryTool, fallbackTool) {
+  return mapAnthropicResponse(response, id, primaryTool);
+}
+
+/**
+ * Walk web_search_tool_result blocks for citeable web_search_result items,
+ * join each to its citation excerpt as snippet, dedupe by url.
+ * @param {object} response  parsed Messages body
+ * @param {string} id        backend id (for error message)
+ * @returns {{sources: WebSearchSource[]}}
+ */
+export function mapAnthropicResponse(response, id) {
+  const blocks = response?.content ?? [];
+  const resultBlocks = blocks.filter(
+    (b) => b.type === "web_search_tool_result",
+  );
+  if (resultBlocks.length === 0) {
+    throw new WebError(
+      `${id} returned no web_search_tool_result blocks; native web search may not have triggered`,
+      "WEB_PROVIDER_ERROR",
+    );
+  }
+  const snippets = citationSnippets(blocks);
+  const seen = new Set();
+  const sources = [];
+  for (const block of resultBlocks) {
+    for (const item of block.content ?? []) {
+      if (item.type !== "web_search_result" || !item.url || item.url.length === 0 || seen.has(item.url)) continue;
+      seen.add(item.url);
+      const snippet = snippets.get(item.url);
+      const source = { url: item.url };
+      if (item.title != null && item.title.length > 0) source.title = item.title;
+      if (snippet != null && snippet.length > 0) source.snippet = snippet;
+      if (item.page_age != null && item.page_age.length > 0) source.publishedAt = item.page_age;
+      sources.push(source);
+    }
+  }
+  return { sources };
+}
+
+/**
+ * Build a url → cited_text map from text blocks' citations[] (first wins).
+ * web_search_result items carry url/title/page_age but typically no inline
+ * snippet; the excerpt lives in a separate text block's citation keyed by url.
+ */
+function citationSnippets(blocks) {
+  const map = new Map();
+  for (const block of blocks) {
+    if (block.type !== "text") continue;
+    for (const cite of block.citations ?? []) {
+      if (
+        cite.url != null &&
+        cite.url.length > 0 &&
+        cite.cited_text != null &&
+        cite.cited_text.length > 0 &&
+        !map.has(cite.url)
+      ) {
+        map.set(cite.url, cite.cited_text);
+      }
+    }
+  }
+  return map;
+}
+
+/** Pre-built instances for the two anthropic-like providers we ship. */
+export const deepseekBackend = createAnthropicLikeBackend({
+  id: "deepseek",
+  defaultBaseURL: "https://api.deepseek.com/anthropic/v1",
+  defaultModel: "deepseek-v4-flash",
+  defaultApiVersion: "2023-06-01",
+  toolName: "web_search_20250305",
+});
+
+export const anthropicBackend = createAnthropicLikeBackend({
+  id: "anthropic",
+  defaultBaseURL: "https://api.anthropic.com/v1",
+  defaultModel: "claude-sonnet-4-6",
+  defaultApiVersion: "2023-06-01",
+  toolName: "web_search_20250305",
+});

package/lib/backends/brave.js

@@ -0,0 +1,98 @@
+/**
+ * Brave Search backend for dsh-websearch.
+ * REST API: https://api.search.brave.com/res/v1/web/search
+ * Auth: X-Subscription-Token header
+ * Free tier: 2,000 requests/month
+ */
+
+import { WebError } from "@deepseek-ai/dsh-web";
+import { throwIfSearchAborted, searchAborted, isAbortError } from "../util/abort.js";
+
+const BRAVE_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+
+/** @type {import("../provider.js").Backend} */
+export const braveBackend = {
+  id: "brave",
+  requiresCredential: true,
+
+  available(options) {
+    return typeof options?.resolveApiKey === "function";
+  },
+
+  async search(request, signal, options, hooks) {
+    throwIfSearchAborted(signal);
+    const backendOpts = options ?? {};
+
+    const apiKey = await backendOpts.resolveApiKey?.();
+    if (!apiKey) {
+      throw new WebError("Brave Search: API key not configured", "WEB_PROVIDER_UNAVAILABLE");
+    }
+
+    const baseURL = backendOpts.baseURL ?? BRAVE_ENDPOINT;
+    const count = Math.min(request.maxResults ?? 8, 20);
+    const url = new URL(baseURL);
+    url.searchParams.set("q", request.query);
+    url.searchParams.set("count", String(count));
+
+    hooks?.recordRequest?.({
+      endpoint: baseURL,
+      toolName: "brave_search",
+      body: { q: request.query, count },
+    });
+
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "X-Subscription-Token": apiKey,
+          "Accept": "application/json",
+          "User-Agent": "dsh-websearch/2.0",
+        },
+        signal,
+      });
+    } catch (error) {
+      if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+      throw new WebError(`Brave Search request failed: ${error}`, "WEB_PROVIDER_ERROR", { cause: error });
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      hooks?.recordOutcome?.({ status: "error", message: `HTTP ${response.status}: ${text}` });
+      throw new WebError(`Brave Search API error (HTTP ${response.status}): ${text}`, "WEB_PROVIDER_ERROR");
+    }
+
+    let data;
+    try {
+      data = await response.json();
+    } catch (error) {
+      throw new WebError("Brave Search: invalid JSON response", "WEB_PROVIDER_ERROR", { cause: error });
+    }
+
+    const sources = parseBraveResult(data, request.maxResults ?? 8);
+    hooks?.recordOutcome?.({ status: "success", count: sources.length });
+    return { sources };
+  },
+};
+
+/**
+ * Parse Brave Search API response.
+ * @param {object} data - Response JSON
+ * @param {number} maxResults - Maximum results to return
+ * @returns {Array<{url:string,title?:string,snippet?:string,publishedAt?:string}>}
+ */
+export function parseBraveResult(data, maxResults) {
+  const results = data?.web?.results ?? [];
+  const sources = [];
+  for (const item of results) {
+    if (sources.length >= maxResults) break;
+    if (!item?.url) continue;
+    sources.push({
+      url: item.url,
+      ...(item.title ? { title: item.title } : {}),
+      ...(item.description ? { snippet: item.description } : {}),
+      ...(item.age ? { publishedAt: item.age } : {}),
+    });
+  }
+  return sources;
+}

package/lib/backends/ddg.js

@@ -0,0 +1,136 @@
+// ddg.js — DuckDuckGo HTML backend (keyless, no API key required)
+// Endpoint: https://html.duckduckgo.com/html/  (POST form-encoded q=...)
+// Returns a simple HTML results page. We extract .result__a (anchor with
+// href through duckduckgo.com/l/?uddg=<encoded-url> redirect), .result__title
+// text, and .result__snippet text. This is a fallback tier: Exa/Parallel
+// are richer, DDG is the zero-dependency safety-net.
+
+import { searchAborted, isAbortError } from "../util/abort.js";
+import { WebError } from "@deepseek-ai/dsh-web";
+
+export const DDG_ENDPOINT = "https://html.duckduckgo.com/html/";
+
+export const ddgBackend = {
+  id: "ddg",
+  requiresCredential: false,
+
+  available() {
+    return true; // keyless
+  },
+
+  /**
+   * @param {WebSearchRequest} request
+   * @param {AbortSignal} signal
+   * @param {{ recordRequest?: Function, recordOutcome?: Function }} [hooks]
+   * @returns {Promise<WebSearchResult>}
+   */
+  async search(request, signal, options, hooks = {}) {
+    throwIfSearchAborted(signal);
+    const body = "q=" + encodeURIComponent(request.query) + "&b=" + Math.random().toString().slice(2);
+    hooks.recordRequest?.({ endpoint: DDG_ENDPOINT, toolName: "html", body: { q: request.query }, headers: {} });
+
+    let text;
+    try {
+      const res = await fetch(DDG_ENDPOINT, {
+        method: "POST",
+        redirect: "error",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "Accept": "text/html",
+          "User-Agent": "dsh-websearch/2.0",
+        },
+        body,
+        ...(signal !== undefined ? { signal } : {}),
+      });
+      if (!res.ok) {
+        let detail = "";
+        try { detail = (await res.text()).slice(0, 200); } catch {}
+        throw new WebError(`ddg HTTP ${res.status}${detail ? ": " + detail : ""}`, "WEB_PROVIDER_ERROR");
+      }
+      text = await res.text();
+    } catch (err) {
+      if (signal?.aborted === true || isAbortError(err)) throw searchAborted(signal, err);
+      hooks.recordOutcome?.({ status: "error", message: String(err?.message ?? err) });
+      throw new WebError(
+        `ddg search failed: ${String(err?.message ?? err)}`,
+        "WEB_PROVIDER_ERROR",
+        { cause: err },
+      );
+    }
+
+    hooks.recordOutcome?.({ status: "ok" });
+
+    const sources = parseDdgHtml(text, request.maxResults ?? 8);
+    return { sources, content: undefined, truncated: false };
+  },
+};
+
+/**
+ * Minimal regex-based DDG HTML parser. Extracts result blocks:
+ *   <a class="result__a" href="...uddg=<encoded>...">Title Text</a>
+ *   <a class="result__snippet" ...>Snippet text</a>
+ * The real URL is the uddg= query param (DDG wraps results in a redirect).
+ *
+ * Resilient to class-attribute ordering / whitespace variations.
+ *
+ * @param {string} html
+ * @param {number} maxResults
+ * @returns {Array<{url:string,title?:string,snippet?:string}>}
+ */
+export function parseDdgHtml(html, maxResults) {
+  if (!html) return [];
+  // Result anchors: <a ... class="result__a" ... href="<url>">Title</a>
+  const anchorRe = /<a\b[^>]*\bclass="[^"]*result__a[^"]*"[^>]*\bhref="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+  const sources = [];
+  let m;
+  while ((m = anchorRe.exec(html)) !== null) {
+    const rawHref = m[1];
+    const url = decodeDdgUddg(rawHref);
+    if (!url) continue;
+
+    // Title text: strip nested tags inside the anchor.
+    const title = stripTags(m[2]).trim();
+
+    // Snippet: search forward from this anchor for the nearest result__snippet.
+    const after = html.slice(m.index + m[0].length);
+    const snipRe = /<a\b[^>]*\bclass="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/i;
+    const snipM = snipRe.exec(after);
+    const snippet = snipM ? stripTags(snipM[1]).trim() : undefined;
+
+    const source = { url };
+    if (title) source.title = title;
+    if (snippet && snippet.length > 0) source.snippet = snippet;
+    sources.push(source);
+    if (sources.length >= maxResults) break;
+  }
+  return sources;
+}
+
+/**
+ * Decode DDG's uddg= redirect param to the real target URL.
+ * Links look like //duckduckgo.com/l/?uddg=<encoded>&rut=...  — we want <decoded>.
+ */
+function decodeDdgUddg(href) {
+  try {
+    // Strip optional protocol-relative prefix.
+    const u = href.replace(/^\/\//, "https://");
+    const idx = u.indexOf("uddg=");
+    if (idx === -1) {
+      // If there's no uddg param but it's a clean http(s) URL, use as-is.
+      return /^https?:\/\//.test(u) ? u : null;
+    }
+    const tail = u.slice(idx + 5);
+    const amp = tail.indexOf("&");
+    const enc = amp === -1 ? tail : tail.slice(0, amp);
+    return decodeURIComponent(enc);
+  } catch {
+    return null;
+  }
+}
+
+/** Strip all HTML tags from a fragment, collapse whitespace. */
+function stripTags(s) {
+  return String(s).replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+export default ddgBackend;