dsh-web-search-plugin 0.1.1 → 0.2.0

package/lib/deepseek.js

@@ -0,0 +1,148 @@
+/**
+ * DeepSeek search backend: the Anthropic-compatible Messages API with the
+ * native `web_search_20250305` server tool. Each search costs a model turn
+ * and returns structured `web_search_tool_result` blocks; absence of those
+ * blocks is an error rather than a prose-scraping fallback.
+ *
+ * This plugin re-hosts the `deepseek-official` provider so the DeepSeek
+ * configuration can sit beside Tavily and Brave. The bundle patch disables
+ * the in-box `web-search-deepseek` host plugin (its namespace feed the legacy
+ * "plugins → web search" card, and re-registering its provider would collide).
+ *
+ * @module dsh-web-search-plugin/deepseek
+ */
+import { WebError } from "@deepseek-ai/dsh-web";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { MAX_RESULTS_CAP, USER_AGENT, isAbortError, resolveApiKey, resolveSecret, searchAborted, throwIfSearchAborted } from "./shared.js";
+
+/** Default endpoint: DeepSeek's Anthropic-compatible API (`/messages` appended). */
+export const DEEPSEEK_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic/v1";
+/** Default credential reference for this backend. */
+export const DEEPSEEK_DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
+/** Environment variable naming this backend's endpoint override. */
+const DEEPSEEK_SEARCH_BASE_URL_ENV = "DEEPSEEK_SEARCH_BASE_URL";
+const DEFAULT_MODEL = "deepseek-v4-flash";
+const DEFAULT_API_VERSION = "2023-06-01";
+const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_MAX_USES = 5;
+
+/**
+ * Build a `url → cited_text` map from `text` blocks' `citations[]` (the snippet
+ * source for Anthropic `web_search_result` items, which carry url/title but no
+ * inline excerpt).
+ */
+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 an Anthropic Messages response to a normalized search result. */
+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" || typeof item.url !== "string" || item.url.length === 0 || seen.has(item.url)) continue;
+		seen.add(item.url);
+		const snippet = snippets.get(item.url);
+		sources.push({
+			url: item.url,
+			...typeof item.title === "string" && item.title.length > 0 ? { title: item.title } : {},
+			...snippet !== void 0 ? { snippet } : {},
+			...typeof item.page_age === "string" && item.page_age.length > 0 ? { publishedAt: item.page_age } : {}
+		});
+	}
+	return { sources, truncated: false };
+}
+
+/** The DeepSeek-backed search backend; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+export class DeepSeekSearchProvider {
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+
+	available() {
+		const options = this.resolveOptions();
+		return ((options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== void 0)
+			&& URL.canParse(options.baseURL)
+			&& Number.isInteger(options.maxTokens) && options.maxTokens > 0
+			&& Number.isInteger(options.maxUses) && options.maxUses > 0;
+	}
+
+	async search(request, signal) {
+		const options = this.resolveOptions();
+		const apiKey = await resolveApiKey(options, signal, `DeepSeek search has no API key for "${options.apiKeyEnv ?? DEEPSEEK_DEFAULT_API_KEY_ENV}"; store it through the credentials service, export it in the launching environment, or set a literal "deepseekApiKey" in the dsh-web-search-plugin config`);
+		throwIfSearchAborted(signal);
+		const endpoint = `${options.baseURL.replace(/\/+$/u, "")}/messages`;
+		const body = {
+			model: options.model,
+			max_tokens: 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: options.maxUses }]
+		};
+		throwIfSearchAborted(signal);
+		let response;
+		try {
+			response = await fetch(endpoint, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"x-api-key": apiKey,
+					"authorization": `Bearer ${apiKey}`,
+					"anthropic-version": 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 (typeof detail === "string" && detail.length > 0) message = detail;
+			} catch {
+				/* non-JSON error body — keep the status-line message */
+			}
+			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 });
+		}
+	}
+}
+
+/** Project the plugin section into DeepSeek backend options. */
+export function resolveDeepseekOptions(ctx, config) {
+	return {
+		...resolveSecret(ctx, {
+			literal: config.deepseekApiKey,
+			envName: config.deepseekApiKeyEnv ?? DEEPSEEK_DEFAULT_API_KEY_ENV
+		}),
+		baseURL: config.deepseekBaseURL ?? launchEnvironmentOf(ctx).get(DEEPSEEK_SEARCH_BASE_URL_ENV)?.value ?? DEEPSEEK_DEFAULT_BASE_URL,
+		model: config.model ?? DEFAULT_MODEL,
+		apiVersion: config.apiVersion ?? DEFAULT_API_VERSION,
+		maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
+		maxUses: config.maxUses ?? DEFAULT_MAX_USES
+	};
+}

package/lib/index.js

@@ -1,41 +1,30 @@
 /**
- * Tavily-backed search provider for the DeepSeek Harness web capability seam
- * (`ctx.web`). Registers a `WebSearchProvider` under the stable id `tavily`
- * that calls the Tavily REST API (`POST {baseURL}/search`).
+ * Web-search provider plugin for the DeepSeek Harness web capability seam
+ * (`ctx.web`). Registers a single `WebSearchProvider` under the stable id
+ * `dsh-web-search` and dispatches each search to DeepSeek (official), Tavily,
+ * or Brave according to the `provider` setting — so switching backends does
+ * not require a `web.searchProvider` patch change.
  *
- * Two authentication modes are supported, switchable through this plugin's
- * settings section (`dsh-web-search-plugin`):
- * - `keyless`: free rate-limited access, no account or key. A single
- *   `X-Tavily-Access-Mode: keyless` header activates it.
- * - `keyed`: a Tavily API key resolved through the credentials service
- *   (`TAVILY_API_KEY` by default), the launching environment, or a literal
- *   `apiKey` in the config; sent as a Bearer token.
+ * Tavily supports `keyless` (free, rate-limited) and `keyed` modes. Brave
+ * always needs a subscription token (`BRAVE_API_KEY` by default). DeepSeek
+ * uses the Anthropic-compatible Messages API native `web_search_20250305`
+ * tool and reuses `DEEPSEEK_API_KEY` (the in-box `web-search-deepseek` host
+ * plugin is disabled by the bundle patch).
  *
- * Responses follow the standard Tavily schema and are normalized into the
- * seam's `WebSearchResult` (`answer` -> `content`, `results[]` -> `sources[]`).
- *
- * The plugin mirrors the structure of `@deepseek-ai/dsh-web-search-deepseek`:
- * a function/namespace Cordis plugin (`inject: ['web']`) that registers its
- * own settings section and never registers a model-facing tool.
+ * No backend writes custom session events; tool results already go through
+ * the seam's own events.
  *
  * @module dsh-web-search-plugin
  */
 import z from "@deepseek-ai/schemastery";
-import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
-import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
-import { WebError } from "@deepseek-ai/dsh-web";
+import { MAX_RESULTS_CAP } from "./shared.js";
+import { TAVILY_DEFAULT_API_KEY_ENV, TAVILY_DEFAULT_BASE_URL, TavilySearchProvider, resolveTavilyOptions } from "./tavily.js";
+import { BRAVE_DEFAULT_API_KEY_ENV, BRAVE_DEFAULT_BASE_URL, BraveSearchProvider, resolveBraveOptions } from "./brave.js";
+import { DEEPSEEK_DEFAULT_API_KEY_ENV, DEEPSEEK_DEFAULT_BASE_URL, DeepSeekSearchProvider, resolveDeepseekOptions } from "./deepseek.js";
 
-/** Stable id this provider registers under. */
-const TAVILY_PROVIDER_ID = "tavily";
-/** Default Tavily REST API base; `/search` is appended. */
-const TAVILY_DEFAULT_BASE_URL = "https://api.tavily.com";
-/** Default credential reference resolved for every keyed search. */
-const DEFAULT_API_KEY_ENV = "TAVILY_API_KEY";
-/** Attribution header sent on every request. */
-const USER_AGENT = "dsh-web-search-plugin/0.1.1";
-/** Tavily's hard cap on `max_results`. */
-const TAVILY_MAX_RESULTS_CAP = 20;
+/** Stable id this plugin registers under on `ctx.web`. */
+const SEARCH_PROVIDER_ID = "dsh-web-search";
 
 /** Cordis plugin name used by loader diagnostics. */
 const name = "dsh-web-search-plugin";
@@ -44,236 +33,128 @@ const inject = ["web"];
 
 /** Plugin config (all optional — `apply` fills defaults). */
 const Config = z.object({
-	/** Authentication mode: `keyless` (default, free rate-limited) or `keyed`. */
+	/** Active backend: `deepseek-official`, `tavily` (default), or `brave`. */
+	provider: z.string().default("tavily"),
+	/** Tavily auth mode: `keyless` (default) or `keyed`. */
 	mode: z.string().default("keyless"),
-	/** Literal Tavily API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+	/** Literal Tavily API key; prefer {@link apiKeyEnv}. */
 	apiKey: z.string().role("secret").default(""),
-	/** Credential reference resolved for each keyed search; defaults to `TAVILY_API_KEY`. */
-	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
-	/** Tavily REST API base. Defaults to `https://api.tavily.com`. */
+	/** Credential reference for keyed Tavily search. */
+	apiKeyEnv: z.string().role("credential-ref").default(TAVILY_DEFAULT_API_KEY_ENV),
+	/** Tavily REST API base. `/search` is appended. */
 	baseURL: z.string().default(TAVILY_DEFAULT_BASE_URL),
-	/** Upper bound on returned sources; Tavily accepts 1..20. */
-	maxResults: z.number().step(1).min(1).max(TAVILY_MAX_RESULTS_CAP).default(8),
-	/** Search depth: `basic` (default) or `advanced`. */
+	/** Upper bound on returned sources; both backends accept 1..20. */
+	maxResults: z.number().step(1).min(1).max(MAX_RESULTS_CAP).default(8),
+	/** Tavily search depth: `basic` (default) or `advanced`. */
 	searchDepth: z.string().default("basic"),
 	/** Request Tavily's generated answer text; surfaced as the result `content`. */
 	includeAnswer: z.boolean().default(true),
-	/** Search topic: `general` (default) or `news`. */
+	/** Tavily topic: `general` (default) or `news`. */
 	topic: z.string().default("general"),
-	/** Settings namespace carrying this provider's mode, endpoint, and key reference. */
+	/** Literal Brave subscription token; prefer {@link braveApiKeyEnv}. */
+	braveApiKey: z.string().role("secret").default(""),
+	/** Credential reference for Brave search. */
+	braveApiKeyEnv: z.string().role("credential-ref").default(BRAVE_DEFAULT_API_KEY_ENV),
+	/** Brave Search API web-results endpoint. */
+	braveBaseURL: z.string().default(BRAVE_DEFAULT_BASE_URL),
+	/** Optional Brave `country` (ISO 2-letter, e.g. `cn`). */
+	country: z.string().default(""),
+	/** Optional Brave `search_lang` (e.g. `zh-hans`). */
+	searchLang: z.string().default(""),
+	/** Optional Brave `freshness` (`pd` / `pw` / `pm` / `py`). */
+	freshness: z.string().default(""),
+	/** Optional HTTP(S) proxy URL for Brave (falls back to HTTPS_PROXY / HTTP_PROXY). */
+	proxy: z.string().default(""),
+	/** Literal DeepSeek API key; prefer {@link deepseekApiKeyEnv}. */
+	deepseekApiKey: z.string().role("secret").default(""),
+	/** Credential reference for DeepSeek search. */
+	deepseekApiKeyEnv: z.string().role("credential-ref").default(DEEPSEEK_DEFAULT_API_KEY_ENV),
+	/** DeepSeek Anthropic-compatible Messages base URL. `/messages` is appended. */
+	deepseekBaseURL: z.string().default(DEEPSEEK_DEFAULT_BASE_URL),
+	/** Anthropic-format model name for the Messages request. */
+	model: z.string().default("deepseek-v4-flash"),
+	/** `anthropic-version` header value. */
+	apiVersion: z.string().default("2023-06-01"),
+	/** Upper bound on generated tokens for the Messages request. */
+	maxTokens: z.number().step(1).min(1).default(4096),
+	/** Maximum `web_search` server-tool uses per request. */
+	maxUses: z.number().step(1).min(1).default(5)
 });
-/** Settings namespace carrying this provider's mode, endpoint, and key reference. */
-const WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE = settingsNamespace("dsh-web-search-plugin");
-/** Environment variable naming this provider's endpoint override. */
-const TAVILY_BASE_URL_ENV = "TAVILY_BASE_URL";
+
+/** Settings namespace carrying this plugin's backend switch and options. */
+const WEB_SEARCH_SETTINGS_NAMESPACE = settingsNamespace("dsh-web-search-plugin");
+/** @deprecated Use {@link WEB_SEARCH_SETTINGS_NAMESPACE}. */
+const WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE = WEB_SEARCH_SETTINGS_NAMESPACE;
 
 /**
- * Normalize a standard Tavily search response into the seam's
- * `WebSearchResult`. Sources are deduped by `url` (Tavily can surface the same
- * page twice); the provider-generated `answer` becomes `content` only when the
- * `includeAnswer` option asked for it. The seam owns the final `maxResults`
- * truncation, so `truncated` is always `false` here.
- *
- * @param json - the parsed Tavily response body.
- * @param includeAnswer - whether the request requested `include_answer`.
- * @returns the normalized search result.
- * @throws {@link WebError} when the body is not a usable object.
+ * One seam-facing provider whose `id` stays `dsh-web-search`. The active
+ * backend is read from the live settings section on every `available` /
+ * `search` call, so a card save takes effect on the next search.
  */
-function mapTavilyResponse(json, includeAnswer) {
-	if (json === null || typeof json !== "object") throw new WebError("Tavily returned a non-object response body", "WEB_PROVIDER_ERROR");
-	const results = Array.isArray(json.results) ? json.results : [];
-	if (results.length === 0) throw new WebError("Tavily returned no results", "WEB_PROVIDER_ERROR");
-	const seen = /* @__PURE__ */ new Set();
-	const sources = [];
-	for (const item of results) {
-		if (item === null || typeof item !== "object") continue;
-		if (typeof item.url !== "string" || item.url.length === 0 || seen.has(item.url)) continue;
-		seen.add(item.url);
-		sources.push({
-			url: item.url,
-			...typeof item.title === "string" && item.title.length > 0 ? { title: item.title } : {},
-			...typeof item.content === "string" && item.content.length > 0 ? { snippet: item.content } : {},
-			...typeof item.published_date === "string" && item.published_date.length > 0 ? { publishedAt: item.published_date } : {}
-		});
-	}
-	return {
-		...includeAnswer === true && typeof json.answer === "string" && json.answer.length > 0 ? { content: json.answer } : {},
-		sources,
-		truncated: false
-	};
-}
+class PluginSearchProvider {
+	id = SEARCH_PROVIDER_ID;
 
-/** The Tavily-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
-class TavilySearchProvider {
-	/**
-	 * @param resolveOptions - the options for the NEXT operation, snapshotted
-	 * once at each operation's entry so one search never mixes two sections.
-	 */
 	constructor(resolveOptions) {
 		this.resolveOptions = resolveOptions;
+		this.deepseek = new DeepSeekSearchProvider(() => this.resolveOptions().deepseek);
+		this.tavily = new TavilySearchProvider(() => this.resolveOptions().tavily);
+		this.brave = new BraveSearchProvider(() => this.resolveOptions().brave);
 	}
 
-	id = TAVILY_PROVIDER_ID;
-
-	/** Cheap local usability check; must not make network calls. */
 	available() {
-		const options = this.resolveOptions();
-		if (!URL.canParse(options.baseURL)) return false;
-		if (options.mode !== "keyed") return true;
-		return ((options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== void 0);
+		return this.backend().available();
 	}
 
-	/** Run one search through the Tavily REST API. */
 	async search(request, signal) {
-		const options = this.resolveOptions();
-		throwIfSearchAborted(signal);
-		let apiKey;
-		if (options.mode === "keyed") {
-			apiKey = await this.apiKey(options, signal);
-			throwIfSearchAborted(signal);
-		}
-		const endpoint = `${options.baseURL.replace(/\/+$/u, "")}/search`;
-		const body = {
-			query: request.query,
-			max_results: Math.min(request.maxResults ?? options.maxResults, TAVILY_MAX_RESULTS_CAP),
-			search_depth: options.searchDepth,
-			topic: options.topic,
-			include_answer: options.includeAnswer === true,
-			include_images: false
-		};
-		const headers = {
-			"content-type": "application/json",
-			"accept": "application/json",
-			"user-agent": USER_AGENT,
-			...options.mode === "keyless" ? { "x-tavily-access-mode": "keyless" } : { "authorization": `Bearer ${apiKey}` }
-		};
-		let response;
-		try {
-			response = await fetch(endpoint, {
-				method: "POST",
-				redirect: "error",
-				headers,
-				body: JSON.stringify(body),
-				...signal !== void 0 ? { signal } : {}
-			});
-		} catch (error) {
-			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-			throw new WebError(`Tavily search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
-		}
-		if (!response.ok) {
-			let message = `Tavily API error (HTTP ${response.status})`;
-			try {
-				const parsed = await response.json();
-				const detail = parsed?.detail?.error ?? parsed?.error ?? parsed?.message;
-				if (typeof detail === "string" && detail.length > 0) message = detail;
-			} catch {
-				/* non-JSON error body — keep the status-line message */
-			}
-			throw new WebError(message, "WEB_PROVIDER_ERROR");
-		}
-		try {
-			return mapTavilyResponse(await response.json(), options.includeAnswer === true);
-		} catch (error) {
-			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-			if (error instanceof WebError) throw error;
-			throw new WebError(`Tavily returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
-		}
+		return this.backend().search(request, signal);
 	}
 
-	/**
-	 * Resolve one operation's credential without retaining it on the provider.
-	 * @param options - the caller's snapshot; the certificate and the endpoint it is sent to come from one section.
-	 * @param signal - abort signal for the surrounding search.
-	 * @returns the resolved key.
-	 */
-	async apiKey(options, signal) {
-		throwIfSearchAborted(signal);
-		if (options.apiKey !== void 0 && options.apiKey.length > 0) return options.apiKey;
-		let resolved;
-		try {
-			resolved = await abortable(options.resolveApiKey?.() ?? Promise.resolve(void 0), signal);
-		} catch (error) {
-			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-			throw new WebError(`Tavily search credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
-		}
-		if (resolved !== void 0 && resolved.length > 0) return resolved;
-		throw new WebError(`Tavily search has no API key for "${options.apiKeyEnv ?? DEFAULT_API_KEY_ENV}"; store it through the credentials service, export it in the launching environment, or set a literal "apiKey" in the dsh-web-search-plugin config`, "WEB_PROVIDER_CREDENTIAL_MISSING");
+	backend() {
+		const provider = this.resolveOptions().provider;
+		if (provider === "brave") return this.brave;
+		if (provider === "deepseek-official") return this.deepseek;
+		return this.tavily;
 	}
 }
 
-/** Race a same-process asynchronous preflight against caller cancellation. */
-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("Tavily 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";
-}
-
-/**
- * Project one resolved section into the options the provider serves its next
- * search with. Environment fallbacks stay here rather than in the provider:
- * every value it reads is already fully defaulted.
- * @param ctx - plugin context supplying the credential and environment planes.
- * @param config - the currently authoritative section.
- * @returns options for one search.
- */
+/** Project one resolved section into options for each backend. */
 function resolveOptions(ctx, config) {
-	const apiKeyEnv = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
-	const literalApiKey = config.apiKey !== void 0 && config.apiKey.length > 0 ? config.apiKey : void 0;
+	const provider = config.provider === "brave" || config.provider === "deepseek-official" ? config.provider : "tavily";
 	return {
-		mode: config.mode ?? "keyless",
-		...literalApiKey === void 0 ? {} : { apiKey: literalApiKey },
-		resolveApiKey: async () => {
-			const credentials = ctx.get("credentials");
-			if (credentials !== void 0) return (await credentials.resolve(apiKeyEnv))?.value;
-			const ambient = launchEnvironmentOf(ctx).get(apiKeyEnv);
-			return ambient !== void 0 && ambient.value.length > 0 ? ambient.value : void 0;
-		},
-		apiKeyEnv,
-		baseURL: config.baseURL ?? launchEnvironmentOf(ctx).get(TAVILY_BASE_URL_ENV)?.value ?? TAVILY_DEFAULT_BASE_URL,
-		maxResults: config.maxResults ?? 8,
-		searchDepth: config.searchDepth ?? "basic",
-		includeAnswer: config.includeAnswer ?? true,
-		topic: config.topic ?? "general"
+		provider,
+		deepseek: resolveDeepseekOptions(ctx, config),
+		tavily: resolveTavilyOptions(ctx, config),
+		brave: resolveBraveOptions(ctx, config)
 	};
 }
 
-/** Register the Tavily search provider with `ctx.web`. */
+/** Register the dispatched search provider with `ctx.web`. */
 function apply(ctx, config) {
 	let current = () => config;
-	installSettingsSection(ctx, WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE, Config, config, {
+	installSettingsSection(ctx, WEB_SEARCH_SETTINGS_NAMESPACE, Config, config, {
 		setSource: (source) => {
 			current = source;
 		},
 		onChange: () => {}
 	});
-	ctx.web.registerSearchProvider(new TavilySearchProvider(() => resolveOptions(ctx, current())));
+	ctx.web.registerSearchProvider(new PluginSearchProvider(() => resolveOptions(ctx, current())));
 }
 
-export { Config, TAVILY_DEFAULT_BASE_URL, TAVILY_PROVIDER_ID, TavilySearchProvider, WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE, apply, inject, name };
+export {
+	BRAVE_DEFAULT_API_KEY_ENV,
+	BRAVE_DEFAULT_BASE_URL,
+	BraveSearchProvider,
+	Config,
+	DEEPSEEK_DEFAULT_API_KEY_ENV,
+	DEEPSEEK_DEFAULT_BASE_URL,
+	DeepSeekSearchProvider,
+	SEARCH_PROVIDER_ID,
+	TAVILY_DEFAULT_API_KEY_ENV,
+	TAVILY_DEFAULT_BASE_URL,
+	TavilySearchProvider,
+	WEB_SEARCH_SETTINGS_NAMESPACE,
+	WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE,
+	apply,
+	inject,
+	name
+};

package/lib/shared.js

@@ -0,0 +1,100 @@
+/**
+ * Shared abort / credential helpers for the Tavily and Brave backends.
+ * @module dsh-web-search-plugin/shared
+ */
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { WebError } from "@deepseek-ai/dsh-web";
+
+/** Attribution header sent on every request. */
+export const USER_AGENT = "dsh-web-search-plugin/0.1.2";
+/** Shared cap: Tavily `max_results` and Brave `count` both accept 1..20. */
+export const MAX_RESULTS_CAP = 20;
+
+/**
+ * Resolve one secret without retaining it: literal config, credentials
+ * service, launching environment, then `process.env`.
+ * @param ctx - plugin context.
+ * @param config - section fields naming the literal and the env/credential ref.
+ * @returns the snapshot used by one search.
+ */
+export function resolveSecret(ctx, config) {
+	const envName = config.envName;
+	const apiKeyEnv = credentialRef(envName);
+	const literal = config.literal !== void 0 && config.literal.length > 0 ? config.literal : void 0;
+	return {
+		...literal === void 0 ? {} : { apiKey: literal },
+		apiKeyEnv,
+		resolveApiKey: async () => {
+			const credentials = ctx.get("credentials");
+			if (credentials !== void 0) {
+				const stored = (await credentials.resolve(apiKeyEnv))?.value;
+				if (stored !== void 0 && stored.length > 0) return stored;
+			}
+			const ambient = launchEnvironmentOf(ctx).get(apiKeyEnv);
+			if (ambient !== void 0 && ambient.value.length > 0) return ambient.value;
+			const raw = process.env[apiKeyEnv];
+			return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+		}
+	};
+}
+
+/** Race a same-process asynchronous preflight against caller cancellation. */
+export 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. */
+export function throwIfSearchAborted(signal) {
+	if (signal?.aborted === true) throw searchAborted(signal);
+}
+
+/** Build the provider's stable cancellation error while retaining the caller's reason. */
+export function searchAborted(signal, fallback) {
+	return new WebError("Search aborted", "WEB_ABORTED", { cause: signal?.aborted === true ? signal.reason : fallback });
+}
+
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+export function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+
+/** True for positive integers (result counts and request bounds). */
+export function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+
+/**
+ * Resolve one operation's credential without retaining it on the provider.
+ * @param options - the caller's snapshot.
+ * @param signal - abort signal for the surrounding search.
+ * @param missingMessage - thrown when no key can be resolved.
+ * @returns the resolved key.
+ */
+export async function resolveApiKey(options, signal, missingMessage) {
+	throwIfSearchAborted(signal);
+	if (options.apiKey !== void 0 && options.apiKey.length > 0) return options.apiKey;
+	let resolved;
+	try {
+		resolved = await abortable(options.resolveApiKey?.() ?? Promise.resolve(void 0), signal);
+	} catch (error) {
+		if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+		throw new WebError(`Search credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+	}
+	if (resolved !== void 0 && resolved.length > 0) return resolved;
+	throw new WebError(missingMessage, "WEB_PROVIDER_CREDENTIAL_MISSING");
+}