dsh-web-search-plugin 0.1.1 → 0.1.2

package/lib/index.js

@@ -1,41 +1,28 @@
 /**
- * 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 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).
  *
- * 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.
+ * Neither backend writes custom session events. The community Brave plugin
+ * used to append `web/brave-search-request`, which is outside DSH's known
+ * event vocabulary and cannot be marked `ignorable`, so a cold load refused
+ * the conversation. 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";
 
-/** 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 +31,105 @@ 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: `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("")
 });
-/** 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.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() {
+		return this.resolveOptions().provider === "brave" ? this.brave : 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 both backends. */
 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;
 	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: config.provider === "brave" ? "brave" : "tavily",
+		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,
+	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");
+}

package/lib/tavily.js

@@ -0,0 +1,132 @@
+/**
+ * Tavily REST search backend (`POST {baseURL}/search`).
+ * @module dsh-web-search-plugin/tavily
+ */
+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 Tavily REST API base; `/search` is appended. */
+export const TAVILY_DEFAULT_BASE_URL = "https://api.tavily.com";
+/** Default credential reference resolved for every keyed search. */
+export const TAVILY_DEFAULT_API_KEY_ENV = "TAVILY_API_KEY";
+/** Environment variable naming this backend's endpoint override. */
+const TAVILY_BASE_URL_ENV = "TAVILY_BASE_URL";
+
+/**
+ * Normalize a standard Tavily search response into the seam's
+ * `WebSearchResult`. Sources are deduped by `url`; the provider-generated
+ * `answer` becomes `content` only when `includeAnswer` asked for it.
+ * @param json - the parsed Tavily response body.
+ * @param includeAnswer - whether the request requested `include_answer`.
+ * @returns the normalized search result.
+ */
+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
+	};
+}
+
+/** The Tavily-backed search backend; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+export class TavilySearchProvider {
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+
+	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);
+	}
+
+	async search(request, signal) {
+		const options = this.resolveOptions();
+		throwIfSearchAborted(signal);
+		let apiKey;
+		if (options.mode === "keyed") {
+			apiKey = await resolveApiKey(options, signal, `Tavily search has no API key for "${options.apiKeyEnv ?? TAVILY_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`);
+			throwIfSearchAborted(signal);
+		}
+		const endpoint = `${options.baseURL.replace(/\/+$/u, "")}/search`;
+		const body = {
+			query: request.query,
+			max_results: Math.min(request.maxResults ?? options.maxResults, 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 });
+		}
+	}
+}
+
+/** Project the plugin section into Tavily backend options. */
+export function resolveTavilyOptions(ctx, config) {
+	return {
+		mode: config.mode ?? "keyless",
+		...resolveSecret(ctx, {
+			literal: config.apiKey,
+			envName: config.apiKeyEnv ?? TAVILY_DEFAULT_API_KEY_ENV
+		}),
+		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"
+	};
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "dsh-web-search-plugin",
-  "version": "0.1.1",
-  "description": "Tavily web-search provider for the DeepSeek Harness web capability seam (ctx.web): keyless or API-key modes with a UI config card; provider framework extensible to more search APIs",
+  "version": "0.1.2",
+  "description": "Tavily and Brave Search providers for the DeepSeek Harness web capability seam (ctx.web): switch engines from the settings card without a custom session event",
   "keywords": [
     "dsh-plugin",
     "deepseek-harness",
     "dsh",
     "tavily",
+    "brave",
+    "brave-search",
     "web-search",
     "websearch",
     "search",
@@ -16,7 +18,10 @@
   "main": "lib/index.js",
   "files": [
     "lib",
-    "CHANGELOG.md"
+    "cordis.patch.yml",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18"
@@ -28,9 +33,13 @@
     "./client": {
       "default": "./lib/client.js"
     },
+    "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
   "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
     "client": {
       "platform": "web",
       "inject": [
@@ -44,7 +53,10 @@
     }
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/client.js"
+    "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/shared.js && node --check lib/tavily.js && node --check lib/brave.js"
+  },
+  "dependencies": {
+    "undici": "^6.21.0"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-web": "^0.1.0-rc.7",