@deepseek-ai/dsh-web-search-deepseek 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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-deepseek/README.md
+README.md: fb9e528633954b8eb9fd0fec8d19e24381a63f12
+README.zh.md: 4e761aa6ef1a67ce17fbc1cabf595af7f24e15e6

package/README.md

@@ -0,0 +1,84 @@
+# @deepseek-ai/dsh-web-search-deepseek
+
+English | [中文](README.zh.md)
+
+A [DeepSeek](https://deepseek.com)-backed `WebSearchProvider` for the harness [web capability seam](../web/README.md) (`ctx.web`). It calls DeepSeek's **Anthropic-compatible Messages API** (`POST {baseURL}/messages`) with the native `web_search_20250305` server tool enabled, and maps the structured `web_search_tool_result` blocks DeepSeek returns into the seam's normalized `WebSearchResult`.
+
+This is an **implementation** package: it registers a provider into `ctx.web`, resolves its credential for each search through the optional `ctx.credentials` seam, records the auxiliary request in the initiating Agent session when one exists, and does not register a model-facing tool. Like `@deepseek-ai/dsh-llm-deepseek`, it is a function/namespace plugin (`inject: ['web']`). The Anthropic wire shape is a provider-private detail — it does **not** make this provider depend on `ctx.llm`.
+
+## How it differs from a dedicated search endpoint
+
+Exa and Perplexity expose dedicated search endpoints; DeepSeek does not. Instead this provider issues a **full Messages model call** carrying the `web_search` server tool, so one search costs a complete model turn in latency and tokens — heavier than a pure retrieval endpoint. DeepSeek runs the search server-side and returns **structured** `web_search_tool_result` blocks; the provider parses those blocks and **never scrapes URLs out of model prose**.
+
+**Strict mode**: if the response carries no `web_search_tool_result` block (native search did not trigger), the provider throws `WebError` `WEB_PROVIDER_ERROR` rather than degrading to prose-scraping.
+
+It reuses the `DEEPSEEK_API_KEY` credential reference (no new secret) but **not** `$DEEPSEEK_BASE_URL`: the search endpoint is the Anthropic-compatible base (`https://api.deepseek.com/anthropic/v1`), distinct from the chat-completions base (`https://api.deepseek.com`) the LLM adapter uses. A mounted credentials service is authoritative; without one, the provider falls back to the launching process environment. The reference is resolved for each search, so a key stored or rotated by the Web Models page reaches the next call without a restart.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `apiKey` | omitted | Literal DeepSeek API key. Prefer `apiKeyEnv` so no secret enters configuration; a non-empty literal wins. |
+| `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each search through `ctx.credentials`, or from the process environment when that seam is absent. A missing value fails the call as `WEB_PROVIDER_CREDENTIAL_MISSING`. |
+| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic-compatible endpoint base; `/messages` is appended. Falls back to `$DEEPSEEK_SEARCH_BASE_URL` from any environment layer; do not reuse `$DEEPSEEK_BASE_URL`, which belongs to the chat-completions LLM adapter. An unparseable value makes the provider unavailable. |
+| `model` | `deepseek-v4-flash` | Anthropic-format model name. |
+| `apiVersion` | `2023-06-01` | `anthropic-version` header value. |
+| `maxTokens` | `4096` | Positive-integer upper bound on generated tokens for the Messages request. |
+| `maxUses` | `5` | Positive-integer maximum `web_search` server-tool uses per request. |
+
+```yaml
+- id: web-search-deepseek
+  name: '@deepseek-ai/dsh-web-search-deepseek'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    baseURL: https://gateway.internal/anthropic/v1
+```
+
+## Mapping
+
+DeepSeek returns no provider-generated answer surface this provider trusts as `content`, so `content` is omitted. `sources[]` comes from `web_search_result` items inside `web_search_tool_result` blocks: `url` ← `url`, `title` ← `title`, and `publishedAt` ← `page_age`. Snippets live separately as URL-keyed `cited_text` entries in a text block's `citations[]`; the provider joins them, leaving `snippet` absent when no excerpt exists.
+
+Results are deduplicated by URL because one request may surface the same page across searches. DeepSeek exposes `maxUses`, not a result-count knob, so the seam enforces `maxResults` by truncating `sources[]` and setting `truncated`.
+
+Provider failures become `WEB_PROVIDER_ERROR`; caller cancellation becomes `WEB_ABORTED`. HTTP redirects are rejected before the `Location` target is contacted and surface as `WEB_PROVIDER_ERROR`.
+
+## Request logging
+
+Immediately before dispatch, a search running under an initiating Agent appends the log-only `web/deepseek-search-llm-request` session event. It contains the resolved endpoint, API version, and exact secret-free JSON body sent to DeepSeek; headers and credentials are excluded. Credential failures and cancellations before dispatch create no event, while later HTTP or response failures leave the attempted request durable. Direct programmatic provider calls outside an Agent have no initiating session to log.
+
+## Model Experience
+
+### Auxiliary DeepSeek search request
+
+#### What the model sees
+
+A separate DeepSeek model receives exactly `Perform a web search for the query: <query>` as its user text and one native `web_search` server-tool definition. This request is not part of the conversation model's context.
+
+#### Token effect
+
+Separate provider input and output tokens are incurred for each search; `maxTokens` caps generated output and `maxUses` caps native search uses.
+
+#### KV Cache effect
+
+Independent of the conversation request cache. The auxiliary instruction and native tool definition can form a stable prefix, but each changed query or model route prevents reuse from its first difference.
+
+### Conversation tool result, indirectly
+
+#### What the model sees
+
+Through [`dsh-tool-web`](../tool-web/README.md), the conversation model sees deduplicated URLs, titles, dates, and citation snippets from structured search blocks; provider prose is not trusted as an answer. This provider's exact failures include the actionable missing-credential message, `DeepSeek search credential resolution failed: <error>`, `DeepSeek search aborted`, `DeepSeek search request failed: <error>`, `DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search`, and `DeepSeek returned an unprocessable response body: <error>`; HTTP failures preserve the provider message. The consumer owns the error wrapper.
+
+#### Token effect
+
+Zero direct conversation tokens from registration. Result tokens scale with returned sources and snippets, then the seam enforces the requested source bound.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **One search costs a full Messages model turn** — latency plus generated tokens, with up to `maxUses` server-side searches; DeepSeek exposes no dedicated retrieval endpoint.
+- **Dynamic credential availability resolves inside the operation** — the synchronous `available()` contract can establish that a resolver exists but cannot query an asynchronous credential store. A selected keyless provider therefore fails the search with `WEB_PROVIDER_CREDENTIAL_MISSING`; the stable `web_search` schema remains registered. Caller cancellation races this preflight locally, but cannot force an arbitrary credential backend itself to stop work.
+- **Over-returned sources still cost tokens** — with no result-count knob on the wire, `maxResults` is enforced only post-hoc by seam truncation.
+- **Uncited results carry no `snippet`** — a source gains one only when a `text` block citation (`cited_text`) matches its URL.

package/README.zh.md

@@ -0,0 +1,84 @@
+# @deepseek-ai/dsh-web-search-deepseek
+
+[English](README.md) | 中文
+
+由 [DeepSeek](https://deepseek.com) 支持的 `WebSearchProvider`，用于 harness [web 能力 seam](../web/README.md)（`ctx.web`）。它调用 DeepSeek 的 **Anthropic 兼容 Messages API**（`POST {baseURL}/messages`），启用原生 `web_search_20250305` 服务器工具，并把 DeepSeek 返回的结构化 `web_search_tool_result` 块映射为 seam 规范化的 `WebSearchResult`。
+
+这是一个**实现**包：它向 `ctx.web` 注册提供方，通过可选的 `ctx.credentials` seam 为每次搜索解析凭据，若存在发起请求的 agent（智能体）会话，还会在其中记录该辅助请求，且不注册面向模型的工具。与 `@deepseek-ai/dsh-llm-deepseek` 一样，它是函数／命名空间插件（`inject: ['web']`）。Anthropic 协议格式（wire format）是提供方私有细节，并**不**使该提供方依赖 `ctx.llm`。
+
+## 与专用搜索端点的区别
+
+Exa 和 Perplexity 提供专用搜索端点，DeepSeek 则没有。该提供方改为发起一次携带 `web_search` 服务器工具的**完整 Messages 模型调用**，因此一次搜索会消耗完整模型轮次的延迟与 token，比纯检索端点更重。DeepSeek 在服务器侧执行搜索，返回**结构化** `web_search_tool_result` 块；提供方解析这些块，**绝不会从模型文本中抓取 URL**。
+
+**严格模式**：如果响应不含 `web_search_tool_result` 块（未触发原生搜索），提供方会抛出 `WebError` `WEB_PROVIDER_ERROR`，而非降级为文本抓取。
+
+它复用 `DEEPSEEK_API_KEY` 凭据引用（不增加密钥），但**不会**复用 `$DEEPSEEK_BASE_URL`：搜索端点使用 Anthropic 兼容基址（`https://api.deepseek.com/anthropic/v1`），不同于大语言模型（LLM）适配器使用的 chat-completions 基址（`https://api.deepseek.com`）。已挂载的凭据服务具有权威性；没有该服务时，提供方会回退到启动进程的环境变量。每次搜索都会解析该引用，因此在 Web 的 Models 页中存储或轮换的密钥无需重启，即可用于下一次调用。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `apiKey` | 未设置 | DeepSeek API 密钥字面值。优先使用 `apiKeyEnv`，避免密钥进入配置；非空字面值优先。 |
+| `apiKeyEnv` | `DEEPSEEK_API_KEY` | 每次搜索都会通过 `ctx.credentials` 解析该凭据引用；没有该 seam 时则从进程环境解析。值缺失时，调用以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败。 |
+| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic 兼容端点基址；追加 `/messages`。缺省时回退到任一环境层中的 `$DEEPSEEK_SEARCH_BASE_URL`；禁止复用属于 chat-completions LLM 适配器的 `$DEEPSEEK_BASE_URL`。无法解析时提供方不可用。 |
+| `model` | `deepseek-v4-flash` | Anthropic 格式模型名称。 |
+| `apiVersion` | `2023-06-01` | `anthropic-version` 标头值。 |
+| `maxTokens` | `4096` | Messages 请求生成 token 的正整数上限。 |
+| `maxUses` | `5` | 每次请求使用 `web_search` 服务器工具的正整数上限。 |
+
+```yaml
+- id: web-search-deepseek
+  name: '@deepseek-ai/dsh-web-search-deepseek'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    baseURL: https://gateway.internal/anthropic/v1
+```
+
+## 映射
+
+DeepSeek 不返回该提供方可作为 `content` 信任的提供方生成答案表层，因此省略 `content`。`sources[]` 来自 `web_search_result` 配置项，这些配置项位于 `web_search_tool_result` 块内：`url` ← `url`、`title` ← `title`、`publishedAt` ← `page_age`。`cited_text` 配置项按 URL 标识，单独位于文本块的 `citations[]` 中；提供方会将其作为 snippet 连接，没有摘录时省略 `snippet`。
+
+结果按 URL 去重，因为一次请求可能在多次搜索中呈现同一页面。DeepSeek 公开 `maxUses` 而非结果数量旋钮，因此 seam 会强制执行 `maxResults`：截断 `sources[]` 并设置 `truncated`。
+
+提供方失败变为 `WEB_PROVIDER_ERROR`；调用方取消变为 `WEB_ABORTED`。HTTP 重定向会在接触 `Location` 目标前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。
+
+## 请求日志
+
+由 agent 发起的搜索会在发出请求前一刻，向相应会话追加仅用于日志的 `web/deepseek-search-llm-request` 会话事件。其中包含已解析端点、API 版本，以及发送给 DeepSeek 且不含密钥的精确 JSON 请求体；不包含标头和凭据。发出请求前发生凭据处理失败或取消时不会创建事件；发出请求后才发生 HTTP 或响应失败时，本次请求尝试仍保留持久记录。在 agent 之外通过程序直接调用提供方时，没有发起会话可供记录。
+
+## 模型体验
+
+### 辅助 DeepSeek 搜索请求
+
+#### 模型看到的内容
+
+独立的 DeepSeek 模型会原样接收 `Perform a web search for the query: <query>` 作为用户文本，并收到一个原生 `web_search` 服务器工具定义。该请求不属于会话模型上下文。
+
+#### Token 影响
+
+每次搜索都会产生独立的提供方输入与输出 token；`maxTokens` 限制生成输出，`maxUses` 限制原生搜索次数。
+
+#### KV Cache 影响
+
+与会话请求缓存相互独立。辅助指令与原生工具定义可以形成稳定前缀，但查询或模型路由的每次变化都会阻止从首个差异起的复用。
+
+### 间接的会话工具结果
+
+#### 模型看到的内容
+
+通过 [`dsh-tool-web`](../tool-web/README.md)，会话模型会看到结构化搜索块中去重后的 URL、标题、日期与引用 snippet；提供方文本不会作为答案受到信任。该提供方的具体错误消息包括带有处理指引的凭据缺失消息、`DeepSeek search credential resolution failed: <error>`、`DeepSeek search aborted`、`DeepSeek search request failed: <error>`、`DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search` 和 `DeepSeek returned an unprocessable response body: <error>`；HTTP 失败保留提供方消息。错误包装属于消费方。
+
+#### Token 影响
+
+注册不会直接产生会话 token。结果 token 随返回源与 snippet 增长，随后 seam 会强制执行请求的源数量上限。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **一次搜索需要完整的 Messages 模型轮次**：会产生延迟与生成 token，并且最多执行 `maxUses` 次服务器侧搜索；DeepSeek 不公开专用检索端点。
+- **动态凭据的可用性在操作内部解析**：同步的 `available()` 约定可以确认解析器存在，但无法查询异步凭据存储。因此，选中的无密钥提供方会使搜索以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；稳定的 `web_search` schema 仍保持注册。调用方取消在本地与该预检存在竞态，但无法强制任意凭据后端自行停止工作。
+- **超量返回的源仍消耗 token**：协议没有结果数量旋钮，`maxResults` 只能由 seam 在事后截断。
+- **未引用的结果没有 `snippet`**：只有 `text` 块中的引用（`cited_text`）匹配其 URL 时，源才会获得 snippet。

package/lib/index.js

@@ -0,0 +1,266 @@
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { environmentOf } from "@deepseek-ai/dsh-environment";
+import { WebError } from "@deepseek-ai/dsh-web";
+//#region lib/types/provider.js
+/**
+* DeepSeek search through an Anthropic-compatible Messages model call with the native
+* `web_search_20250305` server tool. Each search costs a model turn, but returns structured
+* result blocks; absence of those blocks is an error rather than a prose-scraping fallback.
+* The wire format and native `fetch` client are provider-private and do not use `ctx.llm`.
+* @module @deepseek-ai/dsh-web-search-deepseek/provider
+*/
+/** Stable id this provider registers under. */
+const DEEPSEEK_PROVIDER_ID = "deepseek-official";
+/**
+* Default endpoint: DeepSeek's Anthropic-compatible surface, `/v1` included
+* (`/messages` is appended). This is NOT the chat-completions base
+* (`https://api.deepseek.com`) `@deepseek-ai/dsh-llm-deepseek` uses, so this
+* provider does NOT reuse `$DEEPSEEK_BASE_URL` — only the API key is shared.
+*/
+const DEEPSEEK_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic/v1";
+/** Default Anthropic-format model name (aligned with the repo's DeepSeek model vocabulary). */
+const DEEPSEEK_DEFAULT_MODEL = "deepseek-v4-flash";
+/** Default `anthropic-version` header value. */
+const DEEPSEEK_DEFAULT_API_VERSION = "2023-06-01";
+/** Default upper bound on generated tokens for the Messages request. */
+const DEEPSEEK_DEFAULT_MAX_TOKENS = 4096;
+/** Default maximum `web_search` server-tool uses per request. */
+const DEEPSEEK_DEFAULT_MAX_USES = 5;
+/** Attribution header sent on every request. Bump with the package version. */
+const USER_AGENT = "deepseek-harness/0.0.1";
+/**
+* Build a `url → cited_text` map from every `text` block's `citations[]`. This
+* is the snippet surface: Anthropic `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` (first occurrence wins).
+*
+* @param blocks - the response's content blocks; non-`text` blocks are skipped.
+* @returns the `url → cited_text` map (empty when no citations are present).
+*/
+function citationSnippets(blocks) {
+	const map = /* @__PURE__ */ 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;
+}
+/**
+* Map a DeepSeek Anthropic Messages response to a normalized search result. Walks
+* `web_search_tool_result` blocks for citeable `web_search_result` items, joins each to its
+* citation excerpt as `snippet`, and dedupes by `url` (a `max_uses > 1` request can surface
+* the same URL across searches). The web service owns the final `maxResults` truncation, so
+* `truncated` is always `false` here.
+*
+* @param response - the parsed Messages response body.
+* @returns the normalized result with deduped, snippet-joined sources.
+* @throws {@link WebError} when native search produced no result block.
+*/
+function mapAnthropicResponse(response) {
+	const blocks = response.content ?? [];
+	const resultBlocks = blocks.filter((block) => block.type === "web_search_tool_result");
+	if (resultBlocks.length === 0) throw new WebError("DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search", "WEB_PROVIDER_ERROR");
+	const snippets = citationSnippets(blocks);
+	const seen = /* @__PURE__ */ new Set();
+	const sources = [];
+	for (const block of resultBlocks) for (const item of block.content ?? []) {
+		if (item.type !== "web_search_result" || item.url.length === 0 || seen.has(item.url)) continue;
+		seen.add(item.url);
+		const snippet = snippets.get(item.url);
+		sources.push({
+			url: item.url,
+			...item.title != null && item.title.length > 0 ? { title: item.title } : {},
+			...snippet != null && snippet.length > 0 ? { snippet } : {},
+			...item.page_age != null && item.page_age.length > 0 ? { publishedAt: item.page_age } : {}
+		});
+	}
+	return {
+		sources,
+		truncated: false
+	};
+}
+/** The DeepSeek-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+var DeepSeekSearchProvider = class {
+	options;
+	id = DEEPSEEK_PROVIDER_ID;
+	constructor(options) {
+		this.options = options;
+	}
+	available() {
+		return ((this.options.apiKey?.length ?? 0) > 0 || this.options.resolveApiKey !== void 0) && URL.canParse(this.options.baseURL) && isPositiveInteger(this.options.maxTokens) && isPositiveInteger(this.options.maxUses);
+	}
+	async search(request, signal) {
+		const apiKey = await this.apiKey(signal);
+		throwIfSearchAborted(signal);
+		const endpoint = `${this.options.baseURL}/messages`;
+		const body = {
+			model: this.options.model,
+			max_tokens: this.options.maxTokens,
+			messages: [{
+				role: "user",
+				content: [{
+					type: "text",
+					text: `Perform a web search for the query: ${request.query}`
+				}]
+			}],
+			tools: [{
+				type: "web_search_20250305",
+				name: "web_search",
+				max_uses: this.options.maxUses
+			}]
+		};
+		this.options.recordRequest?.({
+			endpoint,
+			apiVersion: this.options.apiVersion,
+			body
+		});
+		throwIfSearchAborted(signal);
+		let response;
+		try {
+			response = await fetch(endpoint, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"x-api-key": apiKey,
+					"authorization": `Bearer ${apiKey}`,
+					"anthropic-version": this.options.apiVersion,
+					"content-type": "application/json",
+					"accept": "application/json",
+					"user-agent": USER_AGENT
+				},
+				body: JSON.stringify(body),
+				...signal !== void 0 ? { signal } : {}
+			});
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(`DeepSeek search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (!response.ok) {
+			let message = `DeepSeek 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 !== void 0 && detail.length > 0) message = detail;
+			} catch (error) {
+				if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			}
+			throw new WebError(message, "WEB_PROVIDER_ERROR");
+		}
+		try {
+			return mapAnthropicResponse(await response.json());
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			if (error instanceof WebError) throw error;
+			throw new WebError(`DeepSeek returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+	}
+	/** Resolve one operation's credential without retaining it on the provider. */
+	async apiKey(signal) {
+		throwIfSearchAborted(signal);
+		if (this.options.apiKey !== void 0 && this.options.apiKey.length > 0) return this.options.apiKey;
+		let resolved;
+		try {
+			resolved = await abortable(this.options.resolveApiKey?.() ?? Promise.resolve(void 0), signal);
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(`DeepSeek search credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (resolved !== void 0 && resolved.length > 0) return resolved;
+		throw new WebError(`DeepSeek search has no API key for "${this.options.apiKeyEnv ?? "DEEPSEEK_API_KEY"}"; store it through the credentials service (the web Models page writes it), export it in the launching environment, or set a literal "apiKey" in the web-search-deepseek config`, "WEB_PROVIDER_CREDENTIAL_MISSING");
+	}
+};
+/**
+* Race a same-process asynchronous preflight against caller cancellation. The
+* attached settlement handlers keep observing an uncooperative operation after
+* abort so a later rejection cannot become unhandled.
+*/
+function abortable(operation, signal) {
+	if (signal === void 0) return operation;
+	if (signal.aborted) return Promise.reject(searchAborted(signal));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			reject(searchAborted(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(new Error(String(error).replace(/^Error: /u, ""), { cause: error }));
+		});
+	});
+}
+/** Throw the provider's stable cancellation error when the caller already aborted. */
+function throwIfSearchAborted(signal) {
+	if (signal?.aborted === true) throw searchAborted(signal);
+}
+/** Build the provider's stable cancellation error while retaining the caller's reason. */
+function searchAborted(signal, fallback) {
+	return new WebError("DeepSeek search aborted", "WEB_ABORTED", { cause: signal?.aborted === true ? signal.reason : fallback });
+}
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+/** True for DeepSeek request limits that can be sent to the Messages API. */
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Register a DeepSeek-backed provider in `ctx.web`. It calls the Anthropic-compatible Messages API
+* with native `web_search_20250305`. The provider reuses `DEEPSEEK_API_KEY` but not
+* `DEEPSEEK_BASE_URL`, because search and chat-completions use different bases.
+* @module @deepseek-ai/dsh-web-search-deepseek
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-search-deepseek";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
+const Config = z.object({
+	apiKey: z.string().role("secret"),
+	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+	baseURL: z.string(),
+	model: z.string(),
+	apiVersion: z.string(),
+	maxTokens: z.number().step(1).min(1),
+	maxUses: z.number().step(1).min(1)
+});
+/**
+* Environment variable naming this provider's endpoint. Deliberately distinct
+* from `$DEEPSEEK_BASE_URL`, which belongs to the chat-completions adapter:
+* search speaks the Anthropic-compatible Messages API, so one variable cannot
+* serve both.
+*/
+const SEARCH_BASE_URL_ENV = "DEEPSEEK_SEARCH_BASE_URL";
+/** Register the DeepSeek search provider with `ctx.web`. */
+function apply(ctx, config) {
+	const maxTokens = config.maxTokens ?? 4096;
+	const maxUses = config.maxUses ?? 5;
+	const apiKeyEnv = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
+	const literalApiKey = config.apiKey !== void 0 && config.apiKey.length > 0 ? config.apiKey : void 0;
+	ctx.web.registerSearchProvider(new DeepSeekSearchProvider({
+		...literalApiKey === void 0 ? {} : { apiKey: literalApiKey },
+		resolveApiKey: async () => {
+			const credentials = ctx.get("credentials");
+			if (credentials !== void 0) return (await credentials.resolve(apiKeyEnv))?.value;
+			const ambient = environmentOf(ctx).get(apiKeyEnv);
+			return ambient !== void 0 && ambient.value.length > 0 ? ambient.value : void 0;
+		},
+		apiKeyEnv,
+		baseURL: config.baseURL ?? environmentOf(ctx).get(SEARCH_BASE_URL_ENV)?.value ?? "https://api.deepseek.com/anthropic/v1",
+		model: config.model ?? "deepseek-v4-flash",
+		apiVersion: config.apiVersion ?? "2023-06-01",
+		maxTokens,
+		maxUses,
+		recordRequest: (request) => {
+			ctx.get("agents")?.currentInitiator()?.session.append("web/deepseek-search-llm-request", request);
+		}
+	}));
+}
+//#endregion
+export { Config, DEEPSEEK_DEFAULT_API_VERSION, DEEPSEEK_DEFAULT_BASE_URL, DEEPSEEK_DEFAULT_MAX_TOKENS, DEEPSEEK_DEFAULT_MAX_USES, DEEPSEEK_DEFAULT_MODEL, DEEPSEEK_PROVIDER_ID, DeepSeekSearchProvider, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-web-search-deepseek`.
+* @module @deepseek-ai/dsh-web-search-deepseek/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-web-search-deepseek";
+/** Cordis companion plugin name. */
+const name = "web-search-deepseek-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the package emits a pre-dispatch log event but owns no
+* later authoritative dispatch event to relate it to. Exact envelope equality
+* is pinned at the provider boundary instead.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Register a DeepSeek-backed provider in `ctx.web`. It calls the Anthropic-compatible Messages API
+ * with native `web_search_20250305`. The provider reuses `DEEPSEEK_API_KEY` but not
+ * `DEEPSEEK_BASE_URL`, because search and chat-completions use different bases.
+ * @module @deepseek-ai/dsh-web-search-deepseek
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { DeepSeekSearchProvider, DEEPSEEK_DEFAULT_API_VERSION, DEEPSEEK_DEFAULT_BASE_URL, DEEPSEEK_DEFAULT_MAX_TOKENS, DEEPSEEK_DEFAULT_MAX_USES, DEEPSEEK_DEFAULT_MODEL, DEEPSEEK_PROVIDER_ID, } from './provider.ts';
+export type { DeepSeekSearchLlmRequest, DeepSeekSearchProviderOptions } from './provider.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-search-deepseek";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+    /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+    apiKey?: string;
+    /** Credential reference resolved for each search; defaults to `DEEPSEEK_API_KEY`. */
+    apiKeyEnv?: string;
+    /** Anthropic-compatible endpoint base; `/messages` is appended. */
+    baseURL?: string;
+    /** Anthropic-format model name. Defaults to `deepseek-v4-flash`. */
+    model?: string;
+    /** `anthropic-version` header value. Defaults to `2023-06-01`. */
+    apiVersion?: string;
+    /** Upper bound on generated tokens for the Messages request. Defaults to 4096. */
+    maxTokens?: number;
+    /** Maximum `web_search` server-tool uses per request. Defaults to 5. */
+    maxUses?: number;
+}
+export declare const Config: z<Config>;
+/** Register the DeepSeek search provider with `ctx.web`. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-web-search-deepseek`.
+ * @module @deepseek-ai/dsh-web-search-deepseek/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-search-deepseek-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,123 @@
+/**
+ * DeepSeek search through an Anthropic-compatible Messages model call with the native
+ * `web_search_20250305` server tool. Each search costs a model turn, but returns structured
+ * result blocks; absence of those blocks is an error rather than a prose-scraping fallback.
+ * The wire format and native `fetch` client are provider-private and do not use `ctx.llm`.
+ * @module @deepseek-ai/dsh-web-search-deepseek/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials';
+import type { AnthropicResponse, ContentBlock } from './types.ts';
+/** Stable id this provider registers under. */
+export declare const DEEPSEEK_PROVIDER_ID = "deepseek-official";
+/**
+ * Default endpoint: DeepSeek's Anthropic-compatible surface, `/v1` included
+ * (`/messages` is appended). This is NOT the chat-completions base
+ * (`https://api.deepseek.com`) `@deepseek-ai/dsh-llm-deepseek` uses, so this
+ * provider does NOT reuse `$DEEPSEEK_BASE_URL` — only the API key is shared.
+ */
+export declare const DEEPSEEK_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic/v1";
+/** Default Anthropic-format model name (aligned with the repo's DeepSeek model vocabulary). */
+export declare const DEEPSEEK_DEFAULT_MODEL = "deepseek-v4-flash";
+/** Default `anthropic-version` header value. */
+export declare const DEEPSEEK_DEFAULT_API_VERSION = "2023-06-01";
+/** Default upper bound on generated tokens for the Messages request. */
+export declare const DEEPSEEK_DEFAULT_MAX_TOKENS = 4096;
+/** Default maximum `web_search` server-tool uses per request. */
+export declare const DEEPSEEK_DEFAULT_MAX_USES = 5;
+/**
+ * Exact secret-free DeepSeek Messages request recorded immediately before one
+ * auxiliary search dispatch.
+ */
+export interface DeepSeekSearchLlmRequest {
+    /** Fully resolved Messages endpoint. */
+    readonly endpoint: string;
+    /** `anthropic-version` header value. */
+    readonly apiVersion: string;
+    /** Exact JSON body sent to the provider. */
+    readonly body: {
+        readonly model: string;
+        readonly max_tokens: number;
+        readonly messages: readonly [
+            {
+                readonly role: 'user';
+                readonly content: readonly [
+                    {
+                        readonly type: 'text';
+                        readonly text: string;
+                    }
+                ];
+            }
+        ];
+        readonly tools: readonly [
+            {
+                readonly type: 'web_search_20250305';
+                readonly name: 'web_search';
+                readonly max_uses: number;
+            }
+        ];
+    };
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
+        'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest;
+    }
+}
+/** Resolved provider options (the plugin's `apply` supplies credential and constant defaults). */
+export interface DeepSeekSearchProviderOptions {
+    /** Literal DeepSeek API key; when present it wins over {@link resolveApiKey}. */
+    apiKey?: string;
+    /** Resolve the current DeepSeek API key for one search operation. */
+    resolveApiKey?: () => Promise<string | undefined>;
+    /** Credential reference named by missing-credential diagnostics. */
+    apiKeyEnv?: CredentialRef;
+    /** Endpoint base; `/messages` is appended. */
+    baseURL: string;
+    /** Anthropic-format model name. */
+    model: string;
+    /** `anthropic-version` header value. */
+    apiVersion: string;
+    /** Upper bound on generated tokens for the Messages request. */
+    maxTokens: number;
+    /** Maximum `web_search` server-tool uses per request. */
+    maxUses: number;
+    /**
+     * Record the exact secret-free request immediately before dispatch. A throw
+     * prevents dispatch so model-visible auxiliary input cannot escape logging.
+     */
+    recordRequest?: (request: DeepSeekSearchLlmRequest) => void;
+}
+/**
+ * Build a `url → cited_text` map from every `text` block's `citations[]`. This
+ * is the snippet surface: Anthropic `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` (first occurrence wins).
+ *
+ * @param blocks - the response's content blocks; non-`text` blocks are skipped.
+ * @returns the `url → cited_text` map (empty when no citations are present).
+ */
+export declare function citationSnippets(blocks: readonly ContentBlock[]): Map<string, string>;
+/**
+ * Map a DeepSeek Anthropic Messages response to a normalized search result. Walks
+ * `web_search_tool_result` blocks for citeable `web_search_result` items, joins each to its
+ * citation excerpt as `snippet`, and dedupes by `url` (a `max_uses > 1` request can surface
+ * the same URL across searches). The web service owns the final `maxResults` truncation, so
+ * `truncated` is always `false` here.
+ *
+ * @param response - the parsed Messages response body.
+ * @returns the normalized result with deduped, snippet-joined sources.
+ * @throws {@link WebError} when native search produced no result block.
+ */
+export declare function mapAnthropicResponse(response: AnthropicResponse): WebSearchResult;
+/** The DeepSeek-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+export declare class DeepSeekSearchProvider implements WebSearchProvider {
+    private readonly options;
+    readonly id = "deepseek-official";
+    constructor(options: DeepSeekSearchProviderOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    /** Resolve one operation's credential without retaining it on the provider. */
+    private apiKey;
+}
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Provider-private wire types for DeepSeek's Anthropic-compatible Messages API. Citeable
+ * result items and citation excerpts arrive in separate blocks; the provider joins them by
+ * URL. These types do not create a dependency on `ctx.llm`.
+ * @module @deepseek-ai/dsh-web-search-deepseek/types
+ */
+/** A `web_search_result` item inside a `web_search_tool_result` block. */
+export interface WebSearchResultItem {
+    type: string;
+    url: string;
+    title?: string | null;
+    /** Provider-supplied page age/recency string (mapped to `publishedAt`). */
+    page_age?: string | null;
+}
+/** A `web_search_tool_result` content block: the citeable result surface. */
+export interface WebSearchToolResultBlock {
+    type: 'web_search_tool_result';
+    content?: WebSearchResultItem[];
+}
+/** One citation location inside a `text` block (the snippet surface). */
+export interface CitationLocation {
+    type?: string;
+    url?: string | null;
+    cited_text?: string | null;
+}
+/** A `text` content block: the model's prose plus per-URL citations. */
+export interface TextBlock {
+    type: 'text';
+    text?: string | null;
+    citations?: CitationLocation[];
+}
+/** Any content block; only `web_search_tool_result` and `text` are consumed. */
+export type ContentBlock = WebSearchToolResultBlock | TextBlock | {
+    type: string;
+};
+/** DeepSeek's Anthropic Messages response envelope. */
+export interface AnthropicResponse {
+    content?: ContentBlock[];
+}
+/** DeepSeek's error response envelope (best-effort; fields vary). */
+export interface AnthropicError {
+    error?: {
+        message?: string;
+    } | string;
+    message?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@deepseek-ai/dsh-web-search-deepseek",
+  "description": "DeepSeek-backed search provider (native web_search via the Anthropic-compatible API) for the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/web/web-search-deepseek"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-credentials": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-environment": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-web": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-credentials": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-credentials-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-environment": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-web": "^0.0.1-rc.1"
+  }
+}