dsh-web-search-plugin 0.1.2 → 0.2.1

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,17 +1,18 @@
 /**
  * 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.
+ * `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.
  *
- * Tavily supports `keyless` (free, rate-limited) and `keyed` modes.
- * Brave always needs a subscription token (`BRAVE_API_KEY` by default).
+ * 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).
  *
- * 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.
+ * No backend writes custom session events; tool results already go through
+ * the seam's own events.
  *
  * @module dsh-web-search-plugin
  */
@@ -20,6 +21,8 @@ import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-sett
 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";
+import { TAVILY_USAGE_POLL_MS, UsageTracker } from "./usage.js";
 
 /** Stable id this plugin registers under on `ctx.web`. */
 const SEARCH_PROVIDER_ID = "dsh-web-search";
@@ -31,7 +34,7 @@ const inject = ["web"];
 
 /** Plugin config (all optional — `apply` fills defaults). */
 const Config = z.object({
-	/** Active backend: `tavily` (default) or `brave`. */
+	/** 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"),
@@ -62,7 +65,21 @@ const Config = z.object({
 	/** 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("")
+	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 plugin's backend switch and options. */
@@ -78,10 +95,17 @@ const WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE = WEB_SEARCH_SETTINGS_NAMESPACE;
 class PluginSearchProvider {
 	id = SEARCH_PROVIDER_ID;
 
-	constructor(resolveOptions) {
+	constructor(resolveOptions, usage) {
 		this.resolveOptions = resolveOptions;
-		this.tavily = new TavilySearchProvider(() => this.resolveOptions().tavily);
-		this.brave = new BraveSearchProvider(() => this.resolveOptions().brave);
+		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)
+		}));
 	}
 
 	available() {
@@ -93,19 +117,56 @@ class PluginSearchProvider {
 	}
 
 	backend() {
-		return this.resolveOptions().provider === "brave" ? this.brave : this.tavily;
+		const provider = this.resolveOptions().provider;
+		if (provider === "brave") return this.brave;
+		if (provider === "deepseek-official") return this.deepseek;
+		return this.tavily;
 	}
 }
 
-/** Project one resolved section into options for both backends. */
+/** Project one resolved section into options for each backend. */
 function resolveOptions(ctx, config) {
+	const provider = config.provider === "brave" || config.provider === "deepseek-official" ? config.provider : "tavily";
 	return {
-		provider: config.provider === "brave" ? "brave" : "tavily",
+		provider,
+		deepseek: resolveDeepseekOptions(ctx, config),
 		tavily: resolveTavilyOptions(ctx, config),
 		brave: resolveBraveOptions(ctx, config)
 	};
 }
 
+/** JSON body helper for the usage refresh POST. */
+function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		let body = "";
+		req.on("data", (chunk) => {
+			body += chunk;
+			if (body.length > 1e6) {
+				req.destroy();
+				reject(new Error("Payload too large"));
+			}
+		});
+		req.on("end", () => {
+			try {
+				resolve(body ? JSON.parse(body) : {});
+			} catch {
+				reject(new Error("Invalid JSON"));
+			}
+		});
+		req.on("error", reject);
+	});
+}
+
+function sendJson(res, statusCode, data) {
+	const body = JSON.stringify(data);
+	res.writeHead(statusCode, {
+		"Content-Type": "application/json; charset=utf-8",
+		"Cache-Control": "no-store",
+		"Content-Length": Buffer.byteLength(body)
+	});
+	res.end(body);
+}
+
 /** Register the dispatched search provider with `ctx.web`. */
 function apply(ctx, config) {
 	let current = () => config;
@@ -115,7 +176,61 @@ function apply(ctx, config) {
 		},
 		onChange: () => {}
 	});
-	ctx.web.registerSearchProvider(new PluginSearchProvider(() => resolveOptions(ctx, current())));
+	const live = () => resolveOptions(ctx, current());
+	const usage = new UsageTracker({
+		getTavilyOptions: () => live().tavily
+	});
+	ctx.effect(() => {
+		let cancelled = false;
+		void usage.hydrate().then(() => {
+			if (cancelled) return;
+			if (live().provider === "tavily" && live().tavily.mode === "keyed") return usage.refreshTavily(undefined, true);
+		}).catch(() => {});
+		return () => {
+			cancelled = true;
+			usage.dispose();
+		};
+	}, "dsh-web-search-plugin: usage hydrate");
+	ctx.effect(() => {
+		const tick = () => {
+			if (live().provider === "tavily" && live().tavily.mode === "keyed") void usage.refreshTavily().catch(() => {});
+		};
+		const timer = setInterval(tick, TAVILY_USAGE_POLL_MS);
+		return () => clearInterval(timer);
+	}, "dsh-web-search-plugin: tavily usage poll");
+	ctx.web.registerSearchProvider(new PluginSearchProvider(live, usage));
+	ctx.inject(["webServer"], (webCtx) => {
+		webCtx.effect(() => webCtx.webServer.register({
+			kind: "exact",
+			path: "/dsh-web-search/usage",
+			async handler(req, res) {
+				if (req.method !== "GET" && req.method !== "HEAD" && req.method !== "POST") {
+					res.writeHead(405, { Allow: "GET, HEAD, POST" });
+					res.end();
+					return;
+				}
+				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") {
+					try {
+						if (req.method === "POST") await readJsonBody(req).catch(() => ({}));
+						await usage.refreshTavily(undefined, force);
+					} catch {
+						/* serialize still returns the last cache */
+					}
+				}
+				if (req.method === "HEAD") {
+					res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+					res.end();
+					return;
+				}
+				sendJson(res, 200, usage.serialize(options.provider, options.tavily.mode));
+			}
+		}), "dsh-web-search-plugin: usage route");
+	});
 }
 
 export {
@@ -123,10 +238,15 @@ export {
 	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,
+	TAVILY_USAGE_POLL_MS,
 	TavilySearchProvider,
+	UsageTracker,
 	WEB_SEARCH_SETTINGS_NAMESPACE,
 	WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE,
 	apply,

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

package/lib/tavily.js

@@ -5,6 +5,7 @@
 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 { parseTavilySearchCredits } from "./usage.js";
 
 /** Default Tavily REST API base; `/search` is appended. */
 export const TAVILY_DEFAULT_BASE_URL = "https://api.tavily.com";
@@ -67,13 +68,15 @@ export class TavilySearchProvider {
 			throwIfSearchAborted(signal);
 		}
 		const endpoint = `${options.baseURL.replace(/\/+$/u, "")}/search`;
+		const keyed = options.mode === "keyed";
 		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
+			include_images: false,
+			...keyed ? { include_usage: true } : {}
 		};
 		const headers = {
 			"content-type": "application/json",
@@ -106,7 +109,12 @@ export class TavilySearchProvider {
 			throw new WebError(message, "WEB_PROVIDER_ERROR");
 		}
 		try {
-			return mapTavilyResponse(await response.json(), options.includeAnswer === true);
+			const json = await response.json();
+			if (keyed) {
+				const credits = parseTavilySearchCredits(json);
+				if (credits !== null) options.onUsage?.(credits);
+			}
+			return mapTavilyResponse(json, options.includeAnswer === true);
 		} catch (error) {
 			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
 			if (error instanceof WebError) throw error;