@x1a0f3n9/dsh-web-search-free 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-free/README.md
+README.md: 28948c1bbec3e37ce9db20d6b0691429e1685224
+README.zh.md: 4d0052fcf6658601e867dfd9c64858cc371a2f64

package/README.md

@@ -0,0 +1,140 @@
+---
+description: "The keyless Bing/DuckDuckGo search provider for ctx.web: how deployments mount HTML search that works without a vendor API key."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-free
+
+English | [中文](README.zh.md)
+
+## Summary
+
+With `dsh-web-search-free`, the harness searches the web through Bing HTML first and DuckDuckGo HTML if Bing yields no sources. Choose it when a deployment needs `web_search` for every chat model and does not hold a Perplexity, Exa, or DeepSeek search key. The backend follows HTML redirects and sends a Mozilla-compatible product token; it returns no generated answer, so results carry no `content` — only citeable sources. URL-only hits are kept. 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 `free` search provider, so `ctx.web.search()` resolves it automatically when it is the only usable search backend — or pin it with `searchProvider: free`. The shipped base lists it last in `searchProviderOrder: [perplexity, exa, free]`.
+
+### When to choose it
+
+Choose this backend when search must work without a vendor API key, including Grok and other pi-ai chat routes. The provider is unavailable — and every search call fails with a structured error — when either HTML origin does not parse, the user agent is empty, or a configured `numResults` is not a positive integer.
+
+### Minimal configuration
+
+Load the web service and the provider; bases and the user agent have public defaults, and no environment key is read.
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-free'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `bingBaseURL` | `https://www.bing.com` | Bing origin; `/search` is appended. An unparseable value makes the provider unavailable |
+| `ddgBaseURL` | `https://html.duckduckgo.com` | DuckDuckGo HTML origin; `/html/` is appended. An unparseable value makes the provider unavailable |
+| `userAgent` | a Mozilla-compatible product token | `User-Agent` sent on every request; empty makes the provider unavailable |
+| `numResults` | (unset) | Default result count when a request carries no `maxResults`; must be a positive integer |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#x1a0f3n9dsh-web-search-free) is the exhaustive source for every accepted field and its JSDoc.
+
+### What a search returns
+
+Bing sources with a recoverable http(s) URL become `WebSearchSource` values (`url`, optional `title`, optional `snippet`). If Bing returns none, DuckDuckGo HTML is queried the same way. A request's `maxResults` wins over the configured `numResults` default and is sent to Bing as `count`; DuckDuckGo has no count control, and the service still enforces the bound. Neither engine returns a generated answer, so the result carries no `content`. If either engine succeeds with zero hits, the result is empty rather than an error. Both engines must fail before the call throws.
+
+### Failures and recovery
+
+Provider failures — HTTP errors, network failures, unreadable bodies — surface as `WebError` `WEB_PROVIDER_ERROR` after both engines fail; an aborted request surfaces as `WEB_ABORTED` and does not fall through. HTML engines geo-redirect, so this backend follows redirects instead of rejecting them. 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 HTML adapter with two deliberate rules:
+
+- **Keyless search is a `ctx.web` backend, not the chat model's API.** Grok and other chat routes have no search endpoint here; this package is how those turns still call `web_search`.
+- **No invented answers.** Bing and DuckDuckGo HTML return citations, 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 and provider registration |
+| [`src/provider.ts`](src/provider.ts) | The `FreeSearchProvider`: Bing-then-DuckDuckGo dispatch, abort classification, empty-vs-error policy |
+| [`src/html.ts`](src/html.ts) | SERP HTML parsers and tracking-URL recovery |
+| — | 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()` GETs `{bingBaseURL}/search` with `redirect: 'follow'`. Non-empty Bing sources return immediately. Otherwise it GETs `{ddgBaseURL}/html/`. An abort — a `DOMException` named `AbortError`, already mapped to `WEB_ABORTED` — does not fall through; anything else from one engine is an engine error, and only dual failure 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#x1a0f3n9dsh-web-search-free) — 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 URLs, titles, and snippets or its exact `Bing search aborted`, `DuckDuckGo search aborted`, `Bing search request failed: <error>`, `DuckDuckGo search request failed: <error>`, `Bing search HTTP <status>`, `DuckDuckGo search HTTP <status>`, `Bing returned an unreadable response body: <error>`, `DuckDuckGo returned an unreadable response body: <error>`, and `Free search failed: Bing: <error>; DuckDuckGo: <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.
+
+- **HTML layout is vendor-controlled** — selectors are pinned in tests against fixture markup; a live SERP redesign can yield empty sources until the parsers are updated.
+- **No generated answer and no `publishedAt`** — sources carry URL, title, and snippet only, so the tool has no provider prose and no publication date.
+- **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: additional keyless engines
+
+A third HTML engine can join the fallback list if Bing and DuckDuckGo both start returning empty pages in a region. That change belongs in this provider, not in a second `ctx.web` package, so the ordered policy stays one id: `free`.
+
+</details>

package/README.zh.md

@@ -0,0 +1,140 @@
+---
+description: "ctx.web 的无需密钥 Bing/DuckDuckGo 搜索提供方：部署方如何挂载不依赖厂商 API 密钥的 HTML 搜索。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-free
+
+[English](README.md) | 中文
+
+## 概述
+
+有了 `dsh-web-search-free`，harness 会先通过 Bing HTML 搜索 web，Bing 没有来源时再走 DuckDuckGo HTML。当部署需要让每个聊天模型都能 `web_search`、又没有 Perplexity、Exa 或 DeepSeek 搜索密钥时选择它。此后端会跟随 HTML 重定向，并发送 Mozilla 兼容的产品标识；它不返回生成答案，因此结果不携带 `content`——只产出可引用的来源。只含 URL 的命中也会保留。面向模型的 `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 服务的组合中挂载本提供方；它以 `free` 搜索提供方身份注册，因此当它是唯一可用的搜索后端时，`ctx.web.search()` 会自动解析到它——也可以用 `searchProvider: free` 固定。已交付的 base 把它放在 `searchProviderOrder: [perplexity, exa, free]` 的最后。
+
+### 何时选择
+
+当搜索必须在没有厂商 API 密钥时也能工作——包括 Grok 和其他 pi-ai 聊天路由——时选择此后端。任一 HTML 源无法解析、User-Agent 为空，或已配置的 `numResults` 不是正整数时，提供方不可用——每次搜索调用都会以结构化错误失败。
+
+### 最小配置
+
+加载 web 服务与本提供方；源站和 User-Agent 都有公开默认值，不读取任何环境密钥。
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-free'
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `bingBaseURL` | `https://www.bing.com` | Bing 源站；追加 `/search`。无法解析时提供方不可用 |
+| `ddgBaseURL` | `https://html.duckduckgo.com` | DuckDuckGo HTML 源站；追加 `/html/`。无法解析时提供方不可用 |
+| `userAgent` | Mozilla 兼容的产品标识 | 每次请求发送的 `User-Agent`；为空时提供方不可用 |
+| `numResults` | （未设置） | 请求不含 `maxResults` 时使用的默认结果数；必须是正整数 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#x1a0f3n9dsh-web-search-free)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 搜索返回什么
+
+Bing 中可恢复的 http(s) URL 会变成 `WebSearchSource`（`url`、可选 `title`、可选 `snippet`）。如果 Bing 没有来源，就用同样方式查询 DuckDuckGo HTML。请求的 `maxResults` 优先于已配置的默认 `numResults`，并作为 Bing 的 `count` 发送；DuckDuckGo 没有数量控制，服务仍会强制执行上限。两个引擎都不返回生成答案，因此结果不携带 `content`。任一引擎成功但零命中时，结果为空而不是错误。两个引擎都失败后，调用才会抛错。
+
+### 失败与恢复
+
+提供方失败——HTTP 错误、网络失败、响应体不可读——在两个引擎都失败后以 `WebError` `WEB_PROVIDER_ERROR` 呈现；中止请求以 `WEB_ABORTED` 呈现，并且不会回退到下一个引擎。HTML 搜索引擎会按地区重定向，因此此后端跟随重定向而不是拒绝它们。调用方根据错误码进行分流；面向模型的 `web_search` 工具会在自己的错误包装层内把失败呈现给模型。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释提供方背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+该提供方是 HTML 之上的薄适配器，遵循两条刻意的规则：
+
+- **无需密钥的搜索是 `ctx.web` 后端，不是聊天模型的 API。** Grok 和其他聊天路由在这里没有搜索端点；本包就是这些回合仍然能调用 `web_search` 的方式。
+- **不虚构答案。** Bing 和 DuckDuckGo HTML 返回的是引用，因此省略 `content`，而不是编造模型可能信任的提供方文本。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：配置 schema 与提供方注册 |
+| [`src/provider.ts`](src/provider.ts) | `FreeSearchProvider`：先 Bing 再 DuckDuckGo 的分发、中止分类、空结果与错误策略 |
+| [`src/html.ts`](src/html.ts) | SERP HTML 解析与跟踪 URL 还原 |
+| — | 不发布运行时不变量配套入口；除所属 seam 强制执行的约定外，本包没有独立的事件序列或可变数据关系。 |
+
+### 请求与映射流程
+
+`search()` 以 `redirect: 'follow'` GET `{bingBaseURL}/search`。Bing 只要有非空来源就立即返回。否则再 GET `{ddgBaseURL}/html/`。中止——名为 `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#x1a0f3n9dsh-web-search-free)——每个受支持配置字段及其源声明。
+- [web 能力 seam 决策](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)——搜索与抓取为何共用一项提供方选择服务。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过 `dsh-tool-web` 间接影响模型体验。该工具保留本提供方的 URL、标题与 snippet；如果发生失败，则会在消费方的错误包装层内保留原样错误消息 `Bing search aborted`、`DuckDuckGo search aborted`、`Bing search request failed: <error>`、`DuckDuckGo search request failed: <error>`、`Bing search HTTP <status>`、`DuckDuckGo search HTTP <status>`、`Bing returned an unreadable response body: <error>`、`DuckDuckGo returned an unreadable response body: <error>` 和 `Free search failed: Bing: <error>; DuckDuckGo: <error>`。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明提供方在哪些情况下不合适。它们是当前包约束。
+
+- **HTML 布局由厂商控制**——选择器在测试里对着夹具 markup 钉死；线上 SERP 改版可能导致空来源，直到解析器更新。
+- **没有生成答案，也没有 `publishedAt`**——来源只有 URL、标题和 snippet，因此工具没有提供方散文，也没有发布日期。
+- **按错误形状分类中止**——只有名为 `AbortError` 的 `DOMException` 才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）呈现为 `WEB_PROVIDER_ERROR`。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文和相关 Agent Note 为准。
+
+#### 未来：更多无需密钥的引擎
+
+如果某个地区 Bing 和 DuckDuckGo 都开始返回空页，可以再加入第三个 HTML 引擎。这个改动应留在本提供方内，而不是再做一个 `ctx.web` 包，这样有序列表仍然只有一个 id：`free`。
+
+</details>

package/lib/index.js

@@ -0,0 +1,329 @@
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@x1a0f3n9/dsh-web";
+//#region lib/types/html.js
+/**
+* HTML parsers for the keyless Bing and DuckDuckGo search backends.
+* Layout-sensitive: tests pin the selectors against fixture markup, not live pages.
+*
+* @module @x1a0f3n9/dsh-web-search-free/html
+*/
+const NAMED_ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " "
+};
+/** True when `value` is an absolute http(s) URL. */
+function isHttpUrl(value) {
+	return /^https?:\/\//i.test(value);
+}
+/**
+* Decode a common subset of HTML entities in attribute values and text.
+*
+* @param text - raw HTML text that may contain named or numeric entities.
+* @returns the decoded text; unknown entities are left unchanged.
+*/
+function decodeHtmlEntities(text) {
+	return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, body) => {
+		if (body.startsWith("#")) {
+			const hex = body[1] === "x" || body[1] === "X";
+			const code = Number.parseInt(hex ? body.slice(2) : body.slice(1), hex ? 16 : 10);
+			if (!Number.isFinite(code) || code < 0 || code > 1114111) return match;
+			return String.fromCodePoint(code);
+		}
+		return NAMED_ENTITIES[body.toLowerCase()] ?? match;
+	});
+}
+/**
+* Strip tags and collapse whitespace from an HTML fragment.
+*
+* @param html - an HTML fragment that may contain tags and entities.
+* @returns plain text, or `undefined` when nothing remains.
+*/
+function visibleText(html) {
+	const text = decodeHtmlEntities(html.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+	return text.length > 0 ? text : void 0;
+}
+/**
+* Read one HTML attribute value, decoding entities.
+*
+* @param attrs - the raw attribute string inside a start tag.
+* @param name - the attribute name to read.
+* @returns the decoded value, or `undefined` when the attribute is absent.
+*/
+function attributeValue(attrs, name) {
+	const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i").exec(attrs);
+	const raw = match?.[1] ?? match?.[2];
+	return raw === void 0 ? void 0 : decodeHtmlEntities(raw);
+}
+/**
+* Recover the destination URL from a Bing result href, including `/ck/a` tracking links.
+*
+* @param href - the `href` attribute from a Bing result anchor.
+* @returns an absolute http(s) URL, or `undefined` when none can be recovered.
+*/
+function decodeBingHref(href) {
+	const trimmed = decodeHtmlEntities(href.trim());
+	let url;
+	try {
+		url = new URL(trimmed, "https://www.bing.com/");
+	} catch {
+		return;
+	}
+	const tracked = url.searchParams.get("u");
+	if (tracked !== null && tracked.length > 0) {
+		const decoded = decodeBingTrackedParam(tracked);
+		if (decoded !== void 0) return decoded;
+	}
+	if (isHttpUrl(trimmed) && !trimmed.includes("bing.com/ck/") && !isBingHost(url.hostname)) return trimmed;
+	if (isHttpUrl(url.href) && !isBingHost(url.hostname)) return url.href;
+	if (isHttpUrl(trimmed) && !trimmed.includes("bing.com/ck/")) return trimmed;
+}
+/**
+* Recover the destination URL from a DuckDuckGo HTML result href, including `uddg=`.
+*
+* @param href - the `href` attribute from a DuckDuckGo result anchor.
+* @returns an absolute http(s) URL, or `undefined` when none can be recovered.
+*/
+function decodeDdgHref(href) {
+	const trimmed = decodeHtmlEntities(href.trim());
+	const absolute = trimmed.startsWith("//") ? `https:${trimmed}` : trimmed;
+	let url;
+	try {
+		url = new URL(absolute, "https://html.duckduckgo.com/");
+	} catch {
+		return;
+	}
+	const uddg = url.searchParams.get("uddg");
+	if (uddg !== null && isHttpUrl(uddg)) return uddg;
+	if (isHttpUrl(absolute) && !url.hostname.endsWith("duckduckgo.com")) return absolute;
+	return isHttpUrl(absolute) ? absolute : void 0;
+}
+/**
+* Parse Bing SERP HTML into portable sources.
+*
+* @param html - a Bing `/search` HTML document.
+* @returns sources that have a recoverable http(s) URL; snippet-less hits are kept.
+*/
+function parseBingHtml(html) {
+	const sources = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of html.matchAll(/<li\b[^>]*\bb_algo\b[^>]*>([\s\S]*?)<\/li>/gi)) {
+		const block = String(match[1]);
+		const heading = /<h2\b[^>]*>[\s\S]*?<a\b([^>]*)>([\s\S]*?)<\/a>/i.exec(block);
+		const href = heading === null ? void 0 : attributeValue(String(heading[1]), "href");
+		const title = heading === null ? void 0 : visibleText(String(heading[2]));
+		const cite = visibleText(/<cite\b[^>]*>([\s\S]*?)<\/cite>/i.exec(block)?.[1] ?? "");
+		const snippet = visibleText(/<p\b[^>]*>([\s\S]*?)<\/p>/i.exec(block)?.[1] ?? /class="[^"]*\bb_lineclamp\d*\b[^"]*"[^>]*>([\s\S]*?)<\/(?:p|div)>/i.exec(block)?.[1] ?? "");
+		pushSource(sources, seen, (href === void 0 ? void 0 : decodeBingHref(href)) ?? urlFromCite(cite), title, snippet);
+	}
+	return sources;
+}
+/**
+* Parse DuckDuckGo HTML SERP markup into portable sources.
+*
+* @param html - a DuckDuckGo `/html/` document.
+* @returns sources that have a recoverable http(s) URL; snippet-less hits are kept.
+*/
+function parseDdgHtml(html) {
+	const sources = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of html.matchAll(/<a\b([^>]*\bresult__a\b[^>]*)>([\s\S]*?)<\/a>/gi)) {
+		const attrs = String(match[1]);
+		const title = visibleText(String(match[2]));
+		const href = attributeValue(attrs, "href");
+		const url = href === void 0 ? void 0 : decodeDdgHref(href);
+		const start = Number(match.index);
+		const after = html.slice(start + match[0].length, start + match[0].length + 1200);
+		pushSource(sources, seen, url, title, visibleText(/<a\b[^>]*\bresult__snippet\b[^>]*>([\s\S]*?)<\/a>/i.exec(after)?.[1] ?? /class="[^"]*\bresult__snippet\b[^"]*"[^>]*>([\s\S]*?)<\//i.exec(after)?.[1] ?? ""));
+	}
+	return sources;
+}
+/** Bing tracking `u` values are base64 (optionally prefixed with two marker bytes). */
+function decodeBingTrackedParam(value) {
+	if (isHttpUrl(value)) return value;
+	const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+	for (const candidate of [padded.slice(2), padded]) {
+		if (candidate.length === 0) continue;
+		const decoded = Buffer.from(candidate, "base64").toString("utf8");
+		if (isHttpUrl(decoded)) return decoded;
+	}
+}
+function isBingHost(hostname) {
+	return hostname === "bing.com" || hostname.endsWith(".bing.com");
+}
+function urlFromCite(cite) {
+	if (cite === void 0) return void 0;
+	if (isHttpUrl(cite)) return cite;
+	const host = String(cite.split(/[›»|/]/)[0]).trim();
+	if (/^[\w.-]+\.[a-z]{2,}$/i.test(host)) return `https://${host}`;
+}
+function pushSource(sources, seen, url, title, snippet) {
+	if (url === void 0 || seen.has(url)) return;
+	seen.add(url);
+	sources.push({
+		url,
+		...title !== void 0 ? { title } : {},
+		...snippet !== void 0 ? { snippet } : {}
+	});
+}
+//#endregion
+//#region lib/types/provider.js
+/**
+* `FreeSearchProvider`: a keyless `WebSearchProvider` that reads Bing HTML first
+* and DuckDuckGo HTML if Bing yields no sources. It maps recovered URLs, titles,
+* and snippets onto the seam vocabulary and omits `content` because neither
+* engine returns a generated answer.
+*
+* @module @x1a0f3n9/dsh-web-search-free/provider
+*/
+/** Stable id this provider registers under. */
+const FREE_PROVIDER_ID = "free";
+/** Default Bing search origin; `/search` is the operation. */
+const FREE_DEFAULT_BING_BASE_URL = "https://www.bing.com";
+/** Default DuckDuckGo HTML origin; `/html/` is the operation. */
+const FREE_DEFAULT_DDG_BASE_URL = "https://html.duckduckgo.com";
+/**
+* HTML engines treat a product-only UA as a bot. Identify the product inside a
+* Mozilla-compatible token so the request is still attributable.
+*/
+const FREE_DEFAULT_USER_AGENT = "Mozilla/5.0 (compatible; deepseek-harness/0.0.1; +https://github.com/LunFengChen/deepseek-harness)";
+/** The keyless Bing-then-DuckDuckGo search provider. */
+var FreeSearchProvider = class {
+	options;
+	id = FREE_PROVIDER_ID;
+	constructor(options) {
+		this.options = options;
+	}
+	available() {
+		return isValidBaseUrl(this.options.bingBaseURL) && isValidBaseUrl(this.options.ddgBaseURL) && this.options.userAgent.length > 0 && (this.options.numResults === void 0 || isPositiveInteger(this.options.numResults));
+	}
+	async search(request, signal) {
+		const limit = request.maxResults ?? this.options.numResults;
+		const bing = await this.runEngine("bing", request.query, limit, signal);
+		if (bing.kind === "ok" && bing.sources.length > 0) return {
+			sources: [...bing.sources],
+			truncated: false
+		};
+		const ddg = await this.runEngine("ddg", request.query, limit, signal);
+		if (ddg.kind === "ok" && ddg.sources.length > 0) return {
+			sources: [...ddg.sources],
+			truncated: false
+		};
+		if (bing.kind === "ok" || ddg.kind === "ok") return {
+			sources: [],
+			truncated: false
+		};
+		throw new WebError(`Free search failed: Bing: ${bing.message}; DuckDuckGo: ${ddg.message}`, "WEB_PROVIDER_ERROR");
+	}
+	async runEngine(engine, query, limit, signal) {
+		const label = engine === "bing" ? "Bing" : "DuckDuckGo";
+		try {
+			const html = await this.fetchHtml(engine, query, limit, signal);
+			return {
+				kind: "ok",
+				sources: engine === "bing" ? parseBingHtml(html) : parseDdgHtml(html)
+			};
+		} catch (error) {
+			if (isAbortedWebError(error)) throw error;
+			if (error instanceof WebError) return {
+				kind: "error",
+				message: error.message
+			};
+			return {
+				kind: "error",
+				message: `${label} search request failed: ${String(error)}`
+			};
+		}
+	}
+	async fetchHtml(engine, query, limit, signal) {
+		const label = engine === "bing" ? "Bing" : "DuckDuckGo";
+		const url = engine === "bing" ? bingSearchUrl(this.options.bingBaseURL, query, limit) : ddgSearchUrl(this.options.ddgBaseURL, query);
+		let response;
+		try {
+			response = await fetch(url, {
+				method: "GET",
+				redirect: "follow",
+				headers: {
+					"accept": "text/html,application/xhtml+xml",
+					"user-agent": this.options.userAgent
+				},
+				...signal !== void 0 ? { signal } : {}
+			});
+		} catch (error) {
+			if (isAbortError(error)) throw new WebError(`${label} search aborted`, "WEB_ABORTED", { cause: error });
+			throw new WebError(`${label} search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		let body;
+		try {
+			body = await response.text();
+		} catch (error) {
+			if (isAbortError(error)) throw new WebError(`${label} search aborted`, "WEB_ABORTED", { cause: error });
+			throw new WebError(`${label} returned an unreadable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (!response.ok) throw new WebError(`${label} search HTTP ${String(response.status)}`, "WEB_PROVIDER_ERROR");
+		return body;
+	}
+};
+/** Build the Bing `/search` URL, attaching `count` when a positive limit is known. */
+function bingSearchUrl(baseURL, query, limit) {
+	const url = new URL("search", withTrailingSlash(baseURL));
+	url.searchParams.set("q", query);
+	if (limit !== void 0) url.searchParams.set("count", String(limit));
+	return url.href;
+}
+/** Build the DuckDuckGo `/html/` URL. */
+function ddgSearchUrl(baseURL, query) {
+	const url = new URL("html/", withTrailingSlash(baseURL));
+	url.searchParams.set("q", query);
+	return url.href;
+}
+function withTrailingSlash(baseURL) {
+	return baseURL.endsWith("/") ? baseURL : `${baseURL}/`;
+}
+/** 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 Bing (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";
+}
+function isAbortedWebError(error) {
+	return error instanceof WebError && error.code === "WEB_ABORTED";
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Keyless Bing/DuckDuckGo `WebSearchProvider` plugin. It contributes to the
+* `ctx.web` registry without owning the service.
+*
+* @module @x1a0f3n9/dsh-web-search-free
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-search-free";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const Config = z.object({
+	bingBaseURL: z.string(),
+	ddgBaseURL: z.string(),
+	userAgent: z.string(),
+	numResults: z.number().step(1).min(1)
+});
+/** Register the keyless search provider with `ctx.web`. */
+function apply(ctx, config) {
+	ctx.web.registerSearchProvider(new FreeSearchProvider({
+		bingBaseURL: config.bingBaseURL ?? "https://www.bing.com",
+		ddgBaseURL: config.ddgBaseURL ?? "https://html.duckduckgo.com",
+		userAgent: config.userAgent ?? "Mozilla/5.0 (compatible; deepseek-harness/0.0.1; +https://github.com/LunFengChen/deepseek-harness)",
+		...config.numResults !== void 0 ? { numResults: config.numResults } : {}
+	}));
+}
+//#endregion
+export { Config, FREE_DEFAULT_BING_BASE_URL, FREE_DEFAULT_DDG_BASE_URL, FREE_DEFAULT_USER_AGENT, FREE_PROVIDER_ID, FreeSearchProvider, apply, bingSearchUrl, ddgSearchUrl, decodeBingHref, decodeDdgHref, decodeHtmlEntities, inject, isHttpUrl, name, parseBingHtml, parseDdgHtml, visibleText };

package/lib/types/html.d.ts

@@ -0,0 +1,60 @@
+/**
+ * HTML parsers for the keyless Bing and DuckDuckGo search backends.
+ * Layout-sensitive: tests pin the selectors against fixture markup, not live pages.
+ *
+ * @module @x1a0f3n9/dsh-web-search-free/html
+ */
+import type { WebSearchSource } from '@x1a0f3n9/dsh-web';
+/** True when `value` is an absolute http(s) URL. */
+export declare function isHttpUrl(value: string): boolean;
+/**
+ * Decode a common subset of HTML entities in attribute values and text.
+ *
+ * @param text - raw HTML text that may contain named or numeric entities.
+ * @returns the decoded text; unknown entities are left unchanged.
+ */
+export declare function decodeHtmlEntities(text: string): string;
+/**
+ * Strip tags and collapse whitespace from an HTML fragment.
+ *
+ * @param html - an HTML fragment that may contain tags and entities.
+ * @returns plain text, or `undefined` when nothing remains.
+ */
+export declare function visibleText(html: string): string | undefined;
+/**
+ * Read one HTML attribute value, decoding entities.
+ *
+ * @param attrs - the raw attribute string inside a start tag.
+ * @param name - the attribute name to read.
+ * @returns the decoded value, or `undefined` when the attribute is absent.
+ */
+export declare function attributeValue(attrs: string, name: string): string | undefined;
+/**
+ * Recover the destination URL from a Bing result href, including `/ck/a` tracking links.
+ *
+ * @param href - the `href` attribute from a Bing result anchor.
+ * @returns an absolute http(s) URL, or `undefined` when none can be recovered.
+ */
+export declare function decodeBingHref(href: string): string | undefined;
+/**
+ * Recover the destination URL from a DuckDuckGo HTML result href, including `uddg=`.
+ *
+ * @param href - the `href` attribute from a DuckDuckGo result anchor.
+ * @returns an absolute http(s) URL, or `undefined` when none can be recovered.
+ */
+export declare function decodeDdgHref(href: string): string | undefined;
+/**
+ * Parse Bing SERP HTML into portable sources.
+ *
+ * @param html - a Bing `/search` HTML document.
+ * @returns sources that have a recoverable http(s) URL; snippet-less hits are kept.
+ */
+export declare function parseBingHtml(html: string): WebSearchSource[];
+/**
+ * Parse DuckDuckGo HTML SERP markup into portable sources.
+ *
+ * @param html - a DuckDuckGo `/html/` document.
+ * @returns sources that have a recoverable http(s) URL; snippet-less hits are kept.
+ */
+export declare function parseDdgHtml(html: string): WebSearchSource[];
+//# sourceMappingURL=html.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Keyless Bing/DuckDuckGo `WebSearchProvider` plugin. It contributes to the
+ * `ctx.web` registry without owning the service.
+ *
+ * @module @x1a0f3n9/dsh-web-search-free
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { FREE_DEFAULT_BING_BASE_URL, FREE_DEFAULT_DDG_BASE_URL, FREE_DEFAULT_USER_AGENT, FREE_PROVIDER_ID, FreeSearchProvider, bingSearchUrl, ddgSearchUrl, } from './provider.ts';
+export type { FreeSearchProviderOptions } from './provider.ts';
+export { decodeBingHref, decodeDdgHref, decodeHtmlEntities, isHttpUrl, parseBingHtml, parseDdgHtml, visibleText, } from './html.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-search-free";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config (all optional — `apply` fills constant defaults). */
+export interface Config {
+    /** Bing origin; `/search` is appended. Defaults to the public site. */
+    bingBaseURL?: string;
+    /** DuckDuckGo HTML origin; `/html/` is appended. Defaults to the public site. */
+    ddgBaseURL?: string;
+    /** `User-Agent` sent on every request. Defaults to a Mozilla-compatible product token. */
+    userAgent?: string;
+    /** Default result count when a request carries no `maxResults`. Omitted = none. */
+    numResults?: number;
+}
+export declare const Config: z<Config>;
+/** Register the keyless 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,46 @@
+/**
+ * `FreeSearchProvider`: a keyless `WebSearchProvider` that reads Bing HTML first
+ * and DuckDuckGo HTML if Bing yields no sources. It maps recovered URLs, titles,
+ * and snippets onto the seam vocabulary and omits `content` because neither
+ * engine returns a generated answer.
+ *
+ * @module @x1a0f3n9/dsh-web-search-free/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@x1a0f3n9/dsh-web';
+/** Stable id this provider registers under. */
+export declare const FREE_PROVIDER_ID = "free";
+/** Default Bing search origin; `/search` is the operation. */
+export declare const FREE_DEFAULT_BING_BASE_URL = "https://www.bing.com";
+/** Default DuckDuckGo HTML origin; `/html/` is the operation. */
+export declare const FREE_DEFAULT_DDG_BASE_URL = "https://html.duckduckgo.com";
+/**
+ * HTML engines treat a product-only UA as a bot. Identify the product inside a
+ * Mozilla-compatible token so the request is still attributable.
+ */
+export declare const FREE_DEFAULT_USER_AGENT = "Mozilla/5.0 (compatible; deepseek-harness/0.0.1; +https://github.com/LunFengChen/deepseek-harness)";
+/** Resolved provider options (the plugin's `apply` supplies constant defaults). */
+export interface FreeSearchProviderOptions {
+    /** Bing origin; `/search` is appended. */
+    bingBaseURL: string;
+    /** DuckDuckGo HTML origin; `/html/` is appended. */
+    ddgBaseURL: string;
+    /** `User-Agent` sent on every request. */
+    userAgent: string;
+    /** Default result count when a request carries no `maxResults`. */
+    numResults?: number;
+}
+/** The keyless Bing-then-DuckDuckGo search provider. */
+export declare class FreeSearchProvider implements WebSearchProvider {
+    private readonly options;
+    readonly id = "free";
+    constructor(options: FreeSearchProviderOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    private runEngine;
+    private fetchHtml;
+}
+/** Build the Bing `/search` URL, attaching `count` when a positive limit is known. */
+export declare function bingSearchUrl(baseURL: string, query: string, limit: number | undefined): string;
+/** Build the DuckDuckGo `/html/` URL. */
+export declare function ddgSearchUrl(baseURL: string, query: string): string;
+//# sourceMappingURL=provider.d.ts.map

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@x1a0f3n9/dsh-web-search-free",
+  "description": "Keyless Bing/DuckDuckGo HTML 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-free"
+  },
+  "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-web": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-web": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.2"
+  }
+}