dsh-web-search-plugin 0.4.0 → 0.5.0

package/lib/deepseek.js

@@ -4,16 +4,24 @@
  * 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).
+ * This plugin implements DeepSeek as an internal backend so its configuration
+ * can sit beside the REST engines. The bundle patch disables
+ * the in-box `web-search-deepseek` host plugin so this bundle owns the selected
+ * search provider and its configuration. The seam-facing id registered by this
+ * plugin is `dsh-web-search`; `deepseek-official` is an internal backend choice.
+ *
+ * Authentication follows the official provider: a search started from a
+ * DeepSeek-account session authenticates with the account token
+ * (`x-dsh-auth-token`) when the account service allows this endpoint; every
+ * other search reuses `DEEPSEEK_API_KEY`. When a session initiator exists,
+ * the secret-free request is recorded as a
+ * `web/deepseek-search-llm-request` session event before dispatch.
  *
  * @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";
+import { MAX_RESULTS_CAP, USER_AGENT, abortable, 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";
@@ -21,6 +29,12 @@ export const DEEPSEEK_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic/v1"
 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";
+/**
+ * Provider route id `dsh-llm-deepseek-account` registers; the session's
+ * `request/context` records it per Session. Only such a session may spend
+ * account quota on auxiliary search.
+ */
+const ACCOUNT_PROVIDER = "deepseek-account";
 const DEFAULT_MODEL = "deepseek-v4-flash";
 const DEFAULT_API_VERSION = "2023-06-01";
 const DEFAULT_MAX_TOKENS = 4096;
@@ -41,7 +55,7 @@ function citationSnippets(blocks) {
 }
 
 /** Map an Anthropic Messages response to a normalized search result. */
-function mapAnthropicResponse(response) {
+function mapAnthropicResponse(response, maxResults) {
 	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");
@@ -59,7 +73,9 @@ function mapAnthropicResponse(response) {
 			...typeof item.page_age === "string" && item.page_age.length > 0 ? { publishedAt: item.page_age } : {}
 		});
 	}
-	return { sources, truncated: false };
+	return sources.length > maxResults
+		? { sources: sources.slice(0, maxResults), truncated: true }
+		: { sources, truncated: false };
 }
 
 /** The DeepSeek-backed search backend; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
@@ -70,7 +86,9 @@ export class DeepSeekSearchProvider {
 
 	available() {
 		const options = this.resolveOptions();
-		return ((options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== void 0)
+		const hasKey = (options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== void 0;
+		const canUseAccount = options.resolveAccountToken !== void 0;
+		return (hasKey || canUseAccount)
 			&& URL.canParse(options.baseURL)
 			&& Number.isInteger(options.maxTokens) && options.maxTokens > 0
 			&& Number.isInteger(options.maxUses) && options.maxUses > 0;
@@ -78,9 +96,26 @@ export class DeepSeekSearchProvider {
 
 	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`;
+		// An account-authorized search spends account quota and must not need a
+		// stored API key; every other search resolves `DEEPSEEK_API_KEY`.
+		let accountToken;
+		try {
+			accountToken = await abortable(Promise.resolve().then(() => options.resolveAccountToken?.(endpoint)), signal);
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(`DeepSeek account token resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		throwIfSearchAborted(signal);
+		let authHeaders;
+		if (typeof accountToken === "string" && accountToken.length > 0) {
+			authHeaders = { "x-dsh-auth-token": accountToken };
+		} else {
+			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`);
+			authHeaders = { "x-api-key": apiKey, "authorization": `Bearer ${apiKey}` };
+		}
+		throwIfSearchAborted(signal);
 		const body = {
 			model: options.model,
 			max_tokens: options.maxTokens,
@@ -90,6 +125,9 @@ export class DeepSeekSearchProvider {
 			}],
 			tools: [{ type: "web_search_20250305", name: "web_search", max_uses: options.maxUses }]
 		};
+		// Record the exact secret-free request before it leaves; a throw here
+		// prevents dispatch rather than logging an unrecorded model input.
+		options.recordRequest?.({ endpoint, apiVersion: options.apiVersion, body });
 		throwIfSearchAborted(signal);
 		let response;
 		try {
@@ -97,8 +135,7 @@ export class DeepSeekSearchProvider {
 				method: "POST",
 				redirect: "error",
 				headers: {
-					"x-api-key": apiKey,
-					"authorization": `Bearer ${apiKey}`,
+					...authHeaders,
 					"anthropic-version": options.apiVersion,
 					"content-type": "application/json",
 					"accept": "application/json",
@@ -123,7 +160,8 @@ export class DeepSeekSearchProvider {
 			throw new WebError(message, "WEB_PROVIDER_ERROR");
 		}
 		try {
-			return mapAnthropicResponse(await response.json());
+			const maxResults = Math.min(request.maxResults ?? MAX_RESULTS_CAP, options.maxResults ?? 8, MAX_RESULTS_CAP);
+			return mapAnthropicResponse(await response.json(), maxResults);
 		} catch (error) {
 			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
 			if (error instanceof WebError) throw error;
@@ -132,17 +170,35 @@ export class DeepSeekSearchProvider {
 	}
 }
 
-/** Project the plugin section into DeepSeek backend options. */
+/**
+ * Project the plugin section into DeepSeek backend options.
+ *
+ * `available()` accepts a search that can authenticate *either* way: a stored
+ * API key, an account-authorized session, or both.
+ * @param ctx - plugin context supplying the credential and environment planes.
+ * @param config - one detached section snapshot.
+ * @returns options for one search.
+ */
 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,
+		// Only a DeepSeek-account session may spend account quota; every other
+		// session falls back to the API key resolved above.
+		resolveAccountToken: async (endpoint) => {
+			if (ctx.get("agents")?.currentInitiator()?.session.requestContext()?.provider !== ACCOUNT_PROVIDER) return void 0;
+			return await ctx.get("deepseekAccount")?.resolveToken(endpoint);
+		},
+		recordRequest: (request) => {
+			ctx.get("agents")?.currentInitiator()?.session.append("web/deepseek-search-llm-request", request);
+		},
+		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
+		maxUses: config.maxUses ?? DEFAULT_MAX_USES,
+		maxResults: config.maxResults ?? 8
 	};
 }

package/lib/index.js

@@ -1,23 +1,26 @@
 /**
  * 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
+ * `dsh-web-search` and dispatches each search to one of nine backends
+ * according to the `provider` setting — so switching backends does
  * not require a `web.searchProvider` patch change.
  *
  * 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).
+ * tool and authenticates with an account token or `DEEPSEEK_API_KEY` (the
+ * in-box `web-search-deepseek` host plugin is disabled by the bundle patch).
  *
- * No backend writes custom session events; tool results already go through
- * the seam's own events.
+ * DeepSeek records a secret-free model request as a session event before
+ * dispatch; the REST backends do not write custom session events.
+ *
+ * Adapted to DeepSeek Harness `0.2.x`: configuration is read from `volatile()`
+ * Config accessors instead of the `settings.installSection()` callback pair
+ * removed in `0.2.0`.
  *
  * @module dsh-web-search-plugin
  */
 import z from "@deepseek-ai/schemastery";
-import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 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";
@@ -36,86 +39,93 @@ const inject = ["web"];
 /** Settings namespace carrying this plugin's backend switch and options. */
 const WEB_SEARCH_SETTINGS_NAMESPACE = "dsh-web-search-plugin";
 
-/** Plugin config (all optional — `apply` fills defaults). */
+/**
+ * Plugin config. Every field is `volatile()`: DeepSeek Harness `0.2.x` saves
+ * settings into the active Profile's plugin configuration and only reloads a
+ * running instance when a *non*-volatile field changes, so a volatile field can
+ * be edited from the settings form without restarting the plugin. The previous
+ * `settings.installSection()` + `setSource` mechanism was removed in `0.2.0`,
+ * which makes these accessors the only way to read live configuration.
+ */
 const Config = z.object({
-	/** Active backend: `deepseek-official` (default), `tavily`, `brave`, `serper`, `serpapi`, `exa`, or `searxng`. */
-	provider: z.string().default("deepseek-official"),
+	/** Active backend: `deepseek-official` (default), `tavily`, `brave`, `serper`, `serpapi`, `exa`, `searxng`, `scavio`, or `firecrawl`. */
+	provider: z.string().default("deepseek-official").volatile(),
 	/** Tavily auth mode: `keyless` (default) or `keyed`. */
-	mode: z.string().default("keyless"),
+	mode: z.string().default("keyless").volatile(),
 	/** Literal Tavily API key; prefer {@link apiKeyEnv}. */
-	apiKey: z.string().role("secret").default(""),
+	apiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for keyed Tavily search. */
-	apiKeyEnv: z.string().role("credential-ref").default(TAVILY_DEFAULT_API_KEY_ENV),
+	apiKeyEnv: z.string().role("credential-ref").default(TAVILY_DEFAULT_API_KEY_ENV).volatile(),
 	/** Tavily REST API base. `/search` is appended. */
-	baseURL: z.string().default(TAVILY_DEFAULT_BASE_URL),
+	baseURL: z.string().default("").volatile(),
 	/** Upper bound on returned sources; both backends accept 1..20. */
-	maxResults: z.number().step(1).min(1).max(MAX_RESULTS_CAP).default(8),
+	maxResults: z.number().step(1).min(1).max(MAX_RESULTS_CAP).default(8).volatile(),
 	/** Tavily search depth: `basic` (default) or `advanced`. */
-	searchDepth: z.string().default("basic"),
+	searchDepth: z.string().default("basic").volatile(),
 	/** Request Tavily's generated answer text; surfaced as the result `content`. */
-	includeAnswer: z.boolean().default(true),
+	includeAnswer: z.boolean().default(true).volatile(),
 	/** Tavily topic: `general` (default) or `news`. */
-	topic: z.string().default("general"),
+	topic: z.string().default("general").volatile(),
 	/** Literal Brave subscription token; prefer {@link braveApiKeyEnv}. */
-	braveApiKey: z.string().role("secret").default(""),
+	braveApiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for Brave search. */
-	braveApiKeyEnv: z.string().role("credential-ref").default(BRAVE_DEFAULT_API_KEY_ENV),
+	braveApiKeyEnv: z.string().role("credential-ref").default(BRAVE_DEFAULT_API_KEY_ENV).volatile(),
 	/** Brave Search API web-results endpoint. */
-	braveBaseURL: z.string().default(BRAVE_DEFAULT_BASE_URL),
+	braveBaseURL: z.string().default(BRAVE_DEFAULT_BASE_URL).volatile(),
 	/** Optional Brave `country` (ISO 2-letter, e.g. `cn`). */
-	country: z.string().default(""),
+	country: z.string().default("").volatile(),
 	/** Optional Brave `search_lang` (e.g. `zh-hans`). */
-	searchLang: z.string().default(""),
+	searchLang: z.string().default("").volatile(),
 	/** 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(""),
+	freshness: z.string().default("").volatile(),
+	/** Optional HTTP(S) proxy URL for Brave; blank inherits DSH's global proxy policy. */
+	proxy: z.string().default("").volatile(),
 	/** Literal Serper API key; prefer {@link serperApiKeyEnv}. */
-	serperApiKey: z.string().role("secret").default(""),
+	serperApiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for Serper search. */
-	serperApiKeyEnv: z.string().role("credential-ref").default("SERPER_API_KEY"),
+	serperApiKeyEnv: z.string().role("credential-ref").default("SERPER_API_KEY").volatile(),
 	/** Serper endpoint base. `/search` is appended. */
-	serperBaseURL: z.string().default("https://google.serper.dev"),
+	serperBaseURL: z.string().default("https://google.serper.dev").volatile(),
 	/** Literal SerpApi API key; prefer {@link serpapiApiKeyEnv}. */
-	serpapiApiKey: z.string().role("secret").default(""),
+	serpapiApiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for SerpApi search. */
-	serpapiApiKeyEnv: z.string().role("credential-ref").default("SERPAPI_API_KEY"),
+	serpapiApiKeyEnv: z.string().role("credential-ref").default("SERPAPI_API_KEY").volatile(),
 	/** SerpApi endpoint base. `/search.json` is appended. */
-	serpapiBaseURL: z.string().default("https://serpapi.com"),
+	serpapiBaseURL: z.string().default("https://serpapi.com").volatile(),
 	/** Literal Exa API key; prefer {@link exaApiKeyEnv}. */
-	exaApiKey: z.string().role("secret").default(""),
+	exaApiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for Exa search. */
-	exaApiKeyEnv: z.string().role("credential-ref").default("EXA_API_KEY"),
+	exaApiKeyEnv: z.string().role("credential-ref").default("EXA_API_KEY").volatile(),
 	/** Exa endpoint base. `/search` is appended. */
-	exaBaseURL: z.string().default("https://api.exa.ai"),
+	exaBaseURL: z.string().default("https://api.exa.ai").volatile(),
 	/** Optional SearXNG instance base URL (self-hosted). `/search` is appended. */
-	searxngBaseURL: z.string().default("https://searx.be"),
+	searxngBaseURL: z.string().default("https://searx.be").volatile(),
 	/** Literal Scavio API key; prefer {@link scavioApiKeyEnv}. */
-	scavioApiKey: z.string().role("secret").default(""),
+	scavioApiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for Scavio search. */
-	scavioApiKeyEnv: z.string().role("credential-ref").default("SCAVIO_API_KEY"),
+	scavioApiKeyEnv: z.string().role("credential-ref").default("SCAVIO_API_KEY").volatile(),
 	/** Scavio endpoint base. `/api/v2/google` is appended. */
-	scavioBaseURL: z.string().default("https://api.scavio.dev"),
+	scavioBaseURL: z.string().default("https://api.scavio.dev").volatile(),
 	/** Literal Firecrawl API key; prefer {@link firecrawlApiKeyEnv}. */
-	firecrawlApiKey: z.string().role("secret").default(""),
+	firecrawlApiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for Firecrawl search. */
-	firecrawlApiKeyEnv: z.string().role("credential-ref").default("FIRECRAWL_API_KEY"),
+	firecrawlApiKeyEnv: z.string().role("credential-ref").default("FIRECRAWL_API_KEY").volatile(),
 	/** Firecrawl endpoint base. `/v2/search` is appended. */
-	firecrawlBaseURL: z.string().default("https://api.firecrawl.dev"),
+	firecrawlBaseURL: z.string().default("https://api.firecrawl.dev").volatile(),
 	/** Literal DeepSeek API key; prefer {@link deepseekApiKeyEnv}. */
-	deepseekApiKey: z.string().role("secret").default(""),
+	deepseekApiKey: z.string().role("secret").default("").volatile(),
 	/** Credential reference for DeepSeek search. */
-	deepseekApiKeyEnv: z.string().role("credential-ref").default(DEEPSEEK_DEFAULT_API_KEY_ENV),
+	deepseekApiKeyEnv: z.string().role("credential-ref").default(DEEPSEEK_DEFAULT_API_KEY_ENV).volatile(),
 	/** DeepSeek Anthropic-compatible Messages base URL. `/messages` is appended. */
-	deepseekBaseURL: z.string().default(DEEPSEEK_DEFAULT_BASE_URL),
+	deepseekBaseURL: z.string().default("").volatile(),
 	/** Anthropic-format model name for the Messages request. */
-	model: z.string().default("deepseek-v4-flash"),
+	model: z.string().default("deepseek-v4-flash").volatile(),
 	/** `anthropic-version` header value. */
-	apiVersion: z.string().default("2023-06-01"),
+	apiVersion: z.string().default("2023-06-01").volatile(),
 	/** Upper bound on generated tokens for the Messages request. */
-	maxTokens: z.number().step(1).min(1).default(4096),
+	maxTokens: z.number().step(1).min(1).default(4096).volatile(),
 	/** Maximum `web_search` server-tool uses per request. */
-	maxUses: z.number().step(1).min(1).default(5)
+	maxUses: z.number().step(1).min(1).default(5).volatile()
 });
 
 /**
@@ -129,18 +139,10 @@ class PluginSearchProvider {
 	constructor(resolveOptions, usage) {
 		this.resolveOptions = resolveOptions;
 		this.deepseek = new DeepSeekSearchProvider(() => this.resolveOptions().deepseek);
-		this.tavily = new TavilySearchProvider(() => ({
-			...this.resolveOptions().tavily,
-			onUsage: (credits) => usage?.recordTavilyCredits(credits)
-		}));
-		this.brave = new BraveSearchProvider(() => ({
-			...this.resolveOptions().brave,
-			onRateLimit: (headers) => usage?.recordBraveHeaders(headers)
-		}));
 		this.rest = new Map();
 		for (const providerId of BUILTIN_REST_IDS) {
 			this.rest.set(providerId, new RestSearchProvider(providerId, () => this.resolveOptions().rest[providerId], {
-				onUsage: providerId === "tavily" ? (credits) => usage?.recordTavilyCredits(credits) : void 0,
+				onUsage: providerId === "tavily" ? (credits, apiKey) => usage?.recordTavilyCredits(credits, apiKey) : void 0,
 				onRateLimit: providerId === "brave" ? (headers) => usage?.recordBraveHeaders(headers) : void 0
 			}));
 		}
@@ -169,12 +171,13 @@ class PluginSearchProvider {
 function resolveOptions(ctx, config) {
 	const isBuiltIn = config.provider === "tavily" || config.provider === "brave" || config.provider === "deepseek-official" || BUILTIN_REST_IDS.includes(config.provider);
 	const provider = isBuiltIn ? config.provider : "deepseek-official";
+	const tavily = provider === "tavily" ? resolveTavilyOptions(ctx, config) : void 0;
 	// Per-provider literal key / optional endpoint override, used when the
 	// metadata row's default is not enough (self-hosted SearXNG, proxied
 	// providers, custom key refs).
 	const keySourceByProvider = {
-		brave: { literal: config.braveApiKey, envName: config.braveApiKeyEnv ?? BRAVE_DEFAULT_API_KEY_ENV, baseURL: config.braveBaseURL ?? "", proxy: config.proxy || launchEnvironmentOf(ctx).get("HTTPS_PROXY")?.value || launchEnvironmentOf(ctx).get("HTTP_PROXY")?.value || "" },
-		tavily: { literal: config.apiKey, envName: config.apiKeyEnv ?? TAVILY_DEFAULT_API_KEY_ENV, baseURL: config.baseURL ?? "" },
+		brave: { literal: config.braveApiKey, envName: config.braveApiKeyEnv ?? BRAVE_DEFAULT_API_KEY_ENV, baseURL: config.braveBaseURL ?? "", proxy: config.proxy ?? "" },
+		tavily: { literal: config.apiKey, envName: config.apiKeyEnv ?? TAVILY_DEFAULT_API_KEY_ENV, baseURL: tavily?.baseURL ?? "" },
 		serper: { literal: config.serperApiKey, envName: config.serperApiKeyEnv ?? "SERPER_API_KEY", baseURL: config.serperBaseURL ?? "" },
 		serpapi: { literal: config.serpapiApiKey, envName: config.serpapiApiKeyEnv ?? "SERPAPI_API_KEY", baseURL: config.serpapiBaseURL ?? "" },
 		exa: { literal: config.exaApiKey, envName: config.exaApiKeyEnv ?? "EXA_API_KEY", baseURL: config.exaBaseURL ?? "" },
@@ -191,7 +194,7 @@ function resolveOptions(ctx, config) {
 		includeAnswer: config.includeAnswer
 	};
 	const rest = {};
-	for (const providerId of BUILTIN_REST_IDS) {
+	for (const providerId of provider === "deepseek-official" ? [] : [provider]) {
 		const row = findProvider(providerId);
 		if (row === void 0) continue;
 		const source = keySourceByProvider[providerId] ?? {};
@@ -208,9 +211,9 @@ function resolveOptions(ctx, config) {
 	}
 	return {
 		provider,
-		deepseek: resolveDeepseekOptions(ctx, config),
-		tavily: resolveTavilyOptions(ctx, config),
-		brave: resolveBraveOptions(ctx, config),
+		deepseek: provider === "deepseek-official" ? resolveDeepseekOptions(ctx, config) : void 0,
+		tavily,
+		brave: provider === "brave" ? resolveBraveOptions(ctx, config) : void 0,
 		rest
 	};
 }
@@ -247,18 +250,74 @@ function sendJson(res, statusCode, data) {
 	res.end(body);
 }
 
-/** Register the dispatched search provider with `ctx.web`. */
+/**
+ * Read the live configuration section.
+ *
+ * Every Config field is `volatile()`, so `field.get()` always yields the value
+ * the settings form last wrote — replacing the `installSection` / `setSource`
+ * pair this plugin used on Harness `0.1.x`. Snapshotted once per operation by
+ * each backend's `resolveOptions`, so one search never mixes two sections.
+ * @param config - the plugin's volatile Config accessors.
+ * @returns one detached plain section.
+ */
+function readSection(config) {
+	return {
+		provider: config.provider.get(),
+		mode: config.mode.get(),
+		apiKey: config.apiKey.get(),
+		apiKeyEnv: config.apiKeyEnv.get(),
+		baseURL: config.baseURL.get(),
+		maxResults: config.maxResults.get(),
+		searchDepth: config.searchDepth.get(),
+		includeAnswer: config.includeAnswer.get(),
+		topic: config.topic.get(),
+		braveApiKey: config.braveApiKey.get(),
+		braveApiKeyEnv: config.braveApiKeyEnv.get(),
+		braveBaseURL: config.braveBaseURL.get(),
+		country: config.country.get(),
+		searchLang: config.searchLang.get(),
+		freshness: config.freshness.get(),
+		proxy: config.proxy.get(),
+		serperApiKey: config.serperApiKey.get(),
+		serperApiKeyEnv: config.serperApiKeyEnv.get(),
+		serperBaseURL: config.serperBaseURL.get(),
+		serpapiApiKey: config.serpapiApiKey.get(),
+		serpapiApiKeyEnv: config.serpapiApiKeyEnv.get(),
+		serpapiBaseURL: config.serpapiBaseURL.get(),
+		exaApiKey: config.exaApiKey.get(),
+		exaApiKeyEnv: config.exaApiKeyEnv.get(),
+		exaBaseURL: config.exaBaseURL.get(),
+		searxngBaseURL: config.searxngBaseURL.get(),
+		scavioApiKey: config.scavioApiKey.get(),
+		scavioApiKeyEnv: config.scavioApiKeyEnv.get(),
+		scavioBaseURL: config.scavioBaseURL.get(),
+		firecrawlApiKey: config.firecrawlApiKey.get(),
+		firecrawlApiKeyEnv: config.firecrawlApiKeyEnv.get(),
+		firecrawlBaseURL: config.firecrawlBaseURL.get(),
+		deepseekApiKey: config.deepseekApiKey.get(),
+		deepseekApiKeyEnv: config.deepseekApiKeyEnv.get(),
+		deepseekBaseURL: config.deepseekBaseURL.get(),
+		model: config.model.get(),
+		apiVersion: config.apiVersion.get(),
+		maxTokens: config.maxTokens.get(),
+		maxUses: config.maxUses.get()
+	};
+}
+
+/**
+ * Register the dispatched search provider with `ctx.web`.
+ *
+ * Harness `0.2.x` saves plugin settings into the active Profile's plugin
+ * configuration and exposes them through `settings.describe()`; a plugin with
+ * no custom page gets an auto-generated one for free. This plugin keeps that
+ * default (it never calls `settings.configure({ auto: false })`) and edits the
+ * `dsh-web-search-plugin` namespace through the browser card in
+ * `lib/client.js`.
+ * @param ctx - plugin context.
+ * @param config - volatile Config accessors supplied by the Loader.
+ */
 function apply(ctx, config) {
-	let current = () => config;
-	ctx.inject(["settings"], (settingsCtx) => {
-		settingsCtx.settings.installSection(ctx, WEB_SEARCH_SETTINGS_NAMESPACE, Config, config, {
-			setSource: (source) => {
-				current = source;
-			},
-			onChange: () => {}
-		});
-	});
-	const live = () => resolveOptions(ctx, current());
+	const live = () => resolveOptions(ctx, readSection(config));
 	const usage = new UsageTracker({
 		getTavilyOptions: () => live().tavily
 	});
@@ -266,7 +325,7 @@ function apply(ctx, config) {
 		let cancelled = false;
 		void usage.hydrate().then(() => {
 			if (cancelled) return;
-			if (live().provider === "tavily" && live().tavily.mode === "keyed") return usage.refreshTavily(undefined, true);
+			if (live().provider === "tavily" && live().tavily.mode === "keyed") return usage.refreshTavily();
 		}).catch(() => {});
 		return () => {
 			cancelled = true;
@@ -294,9 +353,7 @@ function apply(ctx, config) {
 				const url = new URL(req.url ?? "/", "http://127.0.0.1");
 				const force = req.method === "POST" || url.searchParams.get("force") === "1" || url.searchParams.get("force") === "true";
 				const options = live();
-				const tavilyState = usage.snapshot().tavily;
-				const missingIdentity = tavilyState.plan == null && tavilyState.limit == null;
-				if ((force || missingIdentity) && options.provider === "tavily" && options.tavily.mode === "keyed") {
+				if (options.provider === "tavily" && options.tavily.mode === "keyed") {
 					try {
 						if (req.method === "POST") await readJsonBody(req).catch(() => ({}));
 						await usage.refreshTavily(undefined, force);
@@ -309,7 +366,7 @@ function apply(ctx, config) {
 					res.end();
 					return;
 				}
-				sendJson(res, 200, usage.serialize(options.provider, options.tavily.mode));
+				sendJson(res, 200, usage.serialize(options.provider, options.tavily?.mode));
 			}
 		}), "dsh-web-search-plugin: usage route");
 	});

package/lib/providers.js

@@ -1,9 +1,9 @@
 /**
  * Static metadata table for every built-in REST web-search provider.
  *
- * This module is intentionally **data, not code**: adding a new REST provider
- * means adding one row here (plus an optional official "get a key" link in the
- * settings card), with zero per-provider execution code. The generic backend in
+ * This module is intentionally **data, not code**: a new REST provider needs
+ * one row here, plus configuration and a browser selector entry, with zero
+ * per-provider execution code. The generic backend in
  * `lib/rest.js` reads a row and performs `method` / `path` / `queryParam` /
  * `countParam` / `params` / `auth` / `response` / `hooks`.
  *
@@ -118,13 +118,13 @@ export const REST_PROVIDERS = [
 		path: "/search",
 		queryIn: "body",
 		queryParam: "query",
-		countParam: "num_results",
+		countParam: "numResults",
 		auth: { type: "bearer" },
 		keyRequired: true,
 		apiKeyRef: "EXA_API_KEY",
 		response: "exa",
 		params: [
-			{ key: "contents", value: "text", when: "always" }
+			{ key: "contents", value: { highlights: true }, when: "always" }
 		],
 		officialUrl: "https://dashboard.exa.ai/",
 		hooks: []
@@ -138,7 +138,7 @@ export const REST_PROVIDERS = [
 		path: "/search",
 		queryIn: "query",
 		queryParam: "q",
-		countParam: "count",
+		countParam: "",
 		auth: { type: "none" },
 		keyRequired: false,
 		apiKeyRef: "",
@@ -185,7 +185,7 @@ export const REST_PROVIDERS = [
 		apiKeyRef: "FIRECRAWL_API_KEY",
 		response: "firecrawl",
 		params: [
-			{ key: "sources", value: "web", when: "always" }
+			{ key: "sources", value: ["web"], when: "always" }
 		],
 		officialUrl: "https://firecrawl.dev/",
 		hooks: []

package/lib/rest.js

@@ -28,9 +28,11 @@ function str(value) {
 }
 
 /** Resolve a `params[]` entry to `{ key, value }` or `null` (skip). */
-/** Keep the param's native type: booleans stay booleans (JSON true/false). */
+/** Keep JSON booleans and arrays in their native form. */
 function paramValue(value) {
 	if (typeof value === "boolean") return value;
+	if (Array.isArray(value)) return value;
+	if (value !== null && typeof value === "object") return value;
 	return value === void 0 ? "" : String(value);
 }
 
@@ -171,9 +173,9 @@ export class RestSearchProvider {
 		const method = options.method === "GET" ? "GET" : "POST";
 		const queryIn = options.queryIn === "query" ? "query" : "body";
 		const queryParam = str(options.queryParam) || "query";
-		const countParam = str(options.countParam) || "max_results";
+		const countParam = options.countParam === "" ? "" : str(options.countParam) || "max_results";
 		const responseHint = str(options.response) || "tavily";
-		const count = Math.min(request.maxResults ?? options.maxResults ?? 8, MAX_RESULTS_CAP);
+		const count = Math.min(request.maxResults ?? MAX_RESULTS_CAP, options.maxResults ?? 8, MAX_RESULTS_CAP);
 
 		let apiKey;
 		if (auth.type !== "none") {
@@ -259,9 +261,12 @@ export class RestSearchProvider {
 			const json = await httpResponse.json();
 			if (responseHint === "tavily" && typeof this.hooks.onUsage === "function") {
 				const credits = Number(json?.usage?.credits);
-				if (Number.isFinite(credits) && credits >= 0) this.hooks.onUsage(credits);
+				if (Number.isFinite(credits) && credits >= 0) this.hooks.onUsage(credits, apiKey);
 			}
-			return mapCustomResponse(json, responseHint);
+			const result = mapCustomResponse(json, responseHint);
+			return result.sources.length > count
+				? { ...result, sources: result.sources.slice(0, count), truncated: true }
+				: result;
 		} catch (error) {
 			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
 			if (error instanceof WebError) throw error;

package/lib/shared.js

@@ -7,7 +7,7 @@ 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.4.0";
+export const USER_AGENT = "dsh-web-search-plugin/0.5.0";
 /** Shared cap: Tavily `max_results` and Brave `count` both accept 1..20. */
 export const MAX_RESULTS_CAP = 20;
 

package/lib/tavily.js

@@ -71,7 +71,7 @@ export class TavilySearchProvider {
 		const keyed = options.mode === "keyed";
 		const body = {
 			query: request.query,
-			max_results: Math.min(request.maxResults ?? options.maxResults, MAX_RESULTS_CAP),
+			max_results: Math.min(request.maxResults ?? MAX_RESULTS_CAP, options.maxResults ?? 8, MAX_RESULTS_CAP),
 			search_depth: options.searchDepth,
 			topic: options.topic,
 			include_answer: options.includeAnswer === true,
@@ -131,7 +131,7 @@ export function resolveTavilyOptions(ctx, config) {
 			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,
+		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,