@240xu/dsh-websearch 2.2.0 → 2.4.0

package/README.md

@@ -29,7 +29,19 @@ DSH（[DeepSeek Harness](https://github.com/deepseek-ai/dsh)）原生插件：
 | `anthropic` | `ANTHROPIC_API_KEY` | `https://api.anthropic.com/v1/messages` | Anthropic Messages + `web_search_20250305`, model `claude-sonnet-4-6` | Claude Code 同机制 |
 | `openai` | `OPENAI_API_KEY` | `https://api.openai.com/v1/responses` | Responses API native `web_search` tool, parse `url_citation` annotations | Codex 同机制 |
 
-**Default enabled set**: `["exa", "parallel", "ddg", "searxng"]` — all keyless. The key-gated backends only join when their `available()` returns true (key present + baseURL reachable).
+> 可用性说明：available() 只做本地配置检查（不联网探测可达性）；密钥在每次搜索时按操作解析，缺失时该后端以明确错误码软失败（不阻塞其他后端）。全部缺 Key 时错误会指向设置页。
+
+### SearXNG 实例 | Public instances
+
+SearXNG 默认指向 `https://searx.be`；公共实例可用性随网络环境波动，失败时错误信息会提示换源。
+在设置面板修改 `searxngBaseURL` 即可切换，常见候选：
+
+| 实例 | 备注 |
+|---|---|
+| https://searx.be | 官方默认，部分地区不可达 |
+| https://searx.tiekoetter.com | 稳定性较好 |
+| https://priv.au | 隐私友好 |
+| 自托管 | 最可靠，支持 API Key（`searxngApiKeyEnv`） |
 
 ## Install | 安装
 
@@ -81,6 +93,9 @@ pnpm install
 
 **v2.1 结果策略**：设置面板新增「结果策略」分区。时间/语言过滤按各后端能力自动映射——Brave `freshness/country/search_lang`、Tavily `time_range`、Serper `tbs/hl/gl`（Google 日期语法）、SearXNG `time_range/language`、DDG `df`；不支持的后端自动忽略对应维度。内部超时以真实原因失败（backend "<id>" timed out after Nms），不再被静默降级为取消；Mojeek 的 API Key 改走 Authorization 头，不再出现在 URL 中。
 
+**结果健康遥测（默认开）**：每次搜索的 `content` 尾部附一行 `[websearch backends] exa ✓5ms/3 · ddg ✗30000ms`，
+模型可据此自诊断并建议用户调整设置；设置面板「结果策略」可关闭（`resultTelemetry`）。
+
 **11 个后端开关**：`enableExa` / `enableParallel` / `enableDdg` / `enableSearxng`（默认开）；`enableBrave` / `enableTavily` / `enableSerper` / `enableMojeek` / `enableDeepseek` / `enableAnthropic` / `enableOpenai`（默认关）
 
 **API Key 授权**（credential-ref，填环境变量名，实际 key 存于 credentials 服务或环境变量）：
@@ -110,7 +125,7 @@ pnpm install
 - **Honest timeouts**: each backend runs under an internal abort controller merged into the caller signal; when only the internal timer fires, the failure is reclassified as WEB_PROVIDER_ERROR ("backend <id> timed out") instead of being masked as a user cancellation.
 - **Concurrency & Timeout Control**: `concurrency` (default 6) limits simultaneous calls; `backendTimeoutMs` (default 30s) caps each backend.
 - **Streamable-http MCP, custom handshake**: `lib/util/mcp-client.js` implements `initialize → notifications/initialized → tools/call` with `Mcp-Session-Id` header caching against Exa and Parallel — no dependency on the full MCP SDK.
-- **hooks.recordRequest/recordOutcome bridge**: each backend routes its request/outcome to `lib/util/log.js` which records `web/unified-search-backend-request` / `…backend-outcome` events onto the active DSH session via `ctx.get("agents")?.currentInitiator()?.session.append(...)` (mirrors `dsh-web-search-deepseek`).
+- **Host-logger diagnostics**: each backend routes request/outcome through lib/util/log.js to the host logger (ctx.logger), best-effort and never thrown - deliberately NOT session events: the session event vocabulary is a closed set third-party plugins must not extend (an unknown envelope type makes the whole session log unreadable).
 
 ## Architecture | 架构
 
@@ -142,7 +157,7 @@ tests/
 ## Test | 测试
 
 ```bash
-node --test tests/parse.test.js tests/provider.test.js
+node --test tests/
 ```
 
 33/33 pass.

package/lib/backends/anthropic-like.js

@@ -19,7 +19,7 @@ import { throwIfSearchAborted, searchAborted, isAbortError } from "../util/abort
 import { WebError } from "@deepseek-ai/dsh-web";
 
 /** Attribution header; bumped with the package version. */
-const UA = "dsh-websearch/2.1";
+const UA = "dsh-websearch/2.3";
 
 /**
  * Factory: create an Anthropic-like Messages backend.
@@ -30,7 +30,6 @@ const UA = "dsh-websearch/2.1";
  * @param {string} spec.defaultModel
  * @param {string} spec.defaultApiVersion   e.g. "2023-06-01"
  * @param {string} spec.toolName            "web_search_20250305"
- * @param {string} [spec.futureToolName]    optional newer tool for dual fallback
  * @returns {object} backend object { id, requiresCredential, available, search }
  */
 export function createAnthropicLikeBackend(spec) {
@@ -40,7 +39,6 @@ export function createAnthropicLikeBackend(spec) {
     defaultModel,
     defaultApiVersion,
     toolName,
-    futureToolName,
   } = spec;
 
   return {
@@ -154,7 +152,7 @@ export function createAnthropicLikeBackend(spec) {
       }
 
       try {
-        const result = mapAnthropicResponse(await response.json(), id, futureToolName);
+        const result = mapAnthropicResponse(await response.json(), id);
         hooks.recordOutcome?.({ status: "ok", sources: result.sources.length });
         return { sources: result.sources, content: undefined, truncated: false };
       } catch (err) {
@@ -174,15 +172,7 @@ export function createAnthropicLikeBackend(spec) {
   };
 }
 
-/**
- * Optional dual-tool fallback: try the newer tool first; if that tool name is
- * rejected by the API (HTTP error mapping is upstream of us), the provider
- * retries with the established fallback. Here we just expose both — the
- * provider loops through candidates and uses whichever result block appears.
- */
-export function tryDualToolResponse(response, id, primaryTool, fallbackTool) {
-  return mapAnthropicResponse(response, id, primaryTool);
-}
+
 
 /**
  * Walk web_search_tool_result blocks for citeable web_search_result items,

package/lib/backends/brave.js

@@ -51,8 +51,10 @@ export const braveBackend = {
         headers: {
           "X-Subscription-Token": apiKey,
           "Accept": "application/json",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -61,7 +63,7 @@ export const braveBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: `HTTP ${response.status}: ${text}` });
       throw new WebError(`Brave Search API error (HTTP ${response.status}): ${text}`, "WEB_PROVIDER_ERROR");
     }

package/lib/backends/ddg.js

@@ -40,7 +40,7 @@ export const ddgBackend = {
         headers: {
           "Content-Type": "application/x-www-form-urlencoded",
           "Accept": "text/html",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
         body,
         ...(signal !== undefined ? { signal } : {}),

package/lib/backends/exa.js

@@ -7,7 +7,7 @@
 // .../Highlights: .../  ..." separated by "\n\n---\n\n"; we split into source objects.
 // Exa is keyless — its public MCP endpoint requires no API key.
 
-import { mcpCall, invalidateSession } from "../util/mcp-client.js";
+import { mcpCall } from "../util/mcp-client.js";
 import { WebError } from "@deepseek-ai/dsh-web";
 
 const EXA_ENDPOINT = "https://mcp.exa.ai/mcp";

package/lib/backends/mojeek.js

@@ -41,7 +41,7 @@ export const mojeekBackend = {
     const headers = {
       "Accept": "application/json",
       "Authorization": "Bearer " + apiKey,
-      "User-Agent": "dsh-websearch/2.1",
+      "User-Agent": "dsh-websearch/2.3",
     };
 
     hooks?.recordRequest?.({
@@ -55,6 +55,8 @@ export const mojeekBackend = {
       response = await fetch(url, {
         method: "GET",
         headers,
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -63,7 +65,7 @@ export const mojeekBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: "HTTP " + response.status + ": " + text });
       throw new WebError("Mojeek API error (HTTP " + response.status + "): " + text, "WEB_PROVIDER_ERROR");
     }

package/lib/backends/openai.js

@@ -13,7 +13,7 @@
 import { throwIfSearchAborted, searchAborted, isAbortError } from "../util/abort.js";
 import { WebError } from "@deepseek-ai/dsh-web";
 
-const UA = "dsh-websearch/2.1";
+const UA = "dsh-websearch/2.3";
 
 export const openaiBackend = {
   id: "openai",
@@ -47,7 +47,7 @@ export const openaiBackend = {
       );
     }
     const baseURL = (options.baseURL || "https://api.openai.com/v1").replace(/\/$/, "");
-    const model = options.model || "gpt-5";
+    const model = options.model || "gpt-4o";
     const endpoint = `${baseURL}/responses`;
 
     const body = {

package/lib/backends/parallel.js

@@ -13,18 +13,15 @@
 // JSON-string with { search_id, results: [{ url, title, publish_date, excerpts:[] }] }.
 // Parallel is keyless — its public MCP endpoint requires no API key.
 
-import { mcpCall, invalidateSession } from "../util/mcp-client.js";
+import { randomUUID } from "node:crypto";
+import { mcpCall } from "../util/mcp-client.js";
 import { WebError } from "@deepseek-ai/dsh-web";
 
 const PARALLEL_ENDPOINT = "https://search.parallel.ai/mcp";
 const PARALLEL_TOOL = "web_search";
 
-/** Per-process session id — stable across searches so Parallel's free-tier
- * rate limiter correlates calls consistently. */
-const SESSION_ID =
-  "dsh-websearch-" +
-  process.pid?.toString(36) + "-" +
-  Math.random().toString(36).slice(2, 10);
+/** Per-process session id - stable so Parallel free-tier rate limiting correlates calls. */
+const SESSION_ID = "dsh-websearch-" + randomUUID().slice(0, 8);
 
 export const parallelBackend = {
   id: "parallel",
@@ -60,9 +57,26 @@ export const parallelBackend = {
       );
     }
 
-    hooks.recordOutcome?.({ status: "ok" });
+    if (result?.isError === true) {
+
+
+      const message = String(result.content?.[0]?.text ?? "unknown");
+
+
+      hooks.recordOutcome?.({ status: "error", message });
+
+
+      throw new WebError(`parallel returned an MCP error: ${message}`, "WEB_PROVIDER_ERROR");
+
+
+    }
+
+
     const sources = parseParallelResult(result, request.maxResults ?? 8);
 
+
+    hooks.recordOutcome?.({ status: "ok", count: sources.length });
+
     if (result?.isError === true) {
       throw new WebError(
         `parallel returned an MCP error: ${String(result.content?.[0]?.text ?? "unknown")}`,

package/lib/backends/searxng.js

@@ -44,7 +44,7 @@ export const searxngBackend = {
 
     const headers = {
       "Accept": "application/json",
-      "User-Agent": "dsh-websearch/2.1",
+      "User-Agent": "dsh-websearch/2.3",
     };
     
     if (apiKey) {
@@ -62,16 +62,22 @@ export const searxngBackend = {
       response = await fetch(url, {
         method: "GET",
         headers,
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
       if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-      throw new WebError("SearXNG request failed: " + error, "WEB_PROVIDER_ERROR", { cause: error });
+      throw new WebError("SearXNG request failed: " + error +
+        " (instance unreachable? point searxngBaseURL at another public instance)", "WEB_PROVIDER_ERROR", { cause: error });
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: "HTTP " + response.status + ": " + text });
+      if (response.status === 429 || response.status >= 500) {
+        throw new WebError("SearXNG API error (HTTP " + response.status + "): " + text + " (instance struggling? point searxngBaseURL at another public instance)", "WEB_PROVIDER_ERROR");
+      }
       throw new WebError("SearXNG API error (HTTP " + response.status + "): " + text, "WEB_PROVIDER_ERROR");
     }
 

package/lib/backends/serper.js

@@ -52,9 +52,11 @@ export const serperBackend = {
           "X-API-KEY": apiKey,
           "Content-Type": "application/json",
           "Accept": "application/json",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
         body: JSON.stringify(body),
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -63,7 +65,7 @@ export const serperBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: "HTTP " + response.status + ": " + text });
       throw new WebError("Serper API error (HTTP " + response.status + "): " + text, "WEB_PROVIDER_ERROR");
     }

package/lib/backends/tavily.js

@@ -56,9 +56,11 @@ export const tavilyBackend = {
           "Authorization": `Bearer ${apiKey}`,
           "Content-Type": "application/json",
           "Accept": "application/json",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
         body: JSON.stringify(body),
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -67,7 +69,7 @@ export const tavilyBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: `HTTP ${response.status}: ${text}` });
       throw new WebError(`Tavily API error (HTTP ${response.status}): ${text}`, "WEB_PROVIDER_ERROR");
     }

package/lib/client.js

@@ -15,7 +15,7 @@ window.__ModuleLoader__.load({
 			{ id: "exa", keyEnv: null, label: "Exa (MCP, 免费)" },
 			{ id: "parallel", keyEnv: null, label: "Parallel (MCP, 免费)" },
 			{ id: "ddg", keyEnv: null, label: "DuckDuckGo (HTML)" },
-			{ id: "searxng", keyEnv: "SEARXNG_API_KEY", label: "SearXNG (元搜索)" },
+			{ id: "searxng", keyEnv: "SEARXNG_API_KEY", optionalKey: true, label: "SearXNG (元搜索)" },
 			{ id: "brave", keyEnv: "BRAVE_API_KEY", label: "Brave Search" },
 			{ id: "tavily", keyEnv: "TAVILY_API_KEY", label: "Tavily (AI)" },
 			{ id: "serper", keyEnv: "SERPER_API_KEY", label: "Serper.dev" },
@@ -31,9 +31,10 @@ window.__ModuleLoader__.load({
 			dedupStrategy: ["url", "url+title"],
 		};
 		/** Boolean settings staged as "true"/"false" strings by the selects. */
-		const BOOLEAN_FIELDS = ["rerank", "safeSearch"];
-		const KEYLESS = BACKENDS.filter((b) => !b.keyEnv);
-		const KEYED = BACKENDS.filter((b) => b.keyEnv);
+		const BOOLEAN_FIELDS = ["rerank", "safeSearch", "resultTelemetry"];
+		const KEYLESS = BACKENDS.filter((b) => !b.keyEnv || b.optionalKey);
+		const KEYED = BACKENDS.filter((b) => b.keyEnv && !b.optionalKey);
+		const OPTIONAL_KEYS = BACKENDS.filter((b) => b.keyEnv && b.optionalKey);
 
 		/** Where the user goes to get/rotate each key. */
 		const KEY_URLS = {
@@ -89,6 +90,11 @@ window.__ModuleLoader__.load({
 			dedupTitle: "链接 + 标题（合并转载）",
 			langPlaceholder: "如 en、zh-CN，留空为默认",
 						envProvided: "环境变量提供",			readOnly: "只读，无需填写",			conflict: "设置已在其他端被修改，请重试",			keyFailed: "该 Key 保存失败",
+			telemetryLabel: "结果健康遥测",
+			fallbackHint: "全部后端已关闭：搜索将回退到默认免 Key 后端",
+			invalidFields: "以下字段未通过校验：",
+			readOnlyScope: "当前配置只读（可能由宿主锁定）",
+			optionalTitle: "私有实例可选 Key",
 		};
 		const en = {
 			nav: "Web Search",
@@ -136,6 +142,11 @@ window.__ModuleLoader__.load({
 			readOnly: "read-only, nothing to fill",
 			conflict: "Changed elsewhere - please retry",
 			keyFailed: "failed to save this key",
+			telemetryLabel: "Result health telemetry",
+			fallbackHint: "All backends off: search falls back to the default keyless four.",
+			invalidFields: "Fields failed validation:",
+			readOnlyScope: "Configuration is read-only (locked by host?)",
+			optionalTitle: "Private instance optional keys",
 		};
 
 		//#region styles
@@ -175,7 +186,8 @@ window.__ModuleLoader__.load({
 				this.saving = false;
 				this.failed = false;
 				this.conflict = false;
-				this.failedKeys = new Set();
+				this.failedKeys = new Map(); // envRef -> failure reason
+				this.failedFields = new Set();
 				this.savedAt = 0;
 				this.store = createStore(this.projection());
 				this.scope.subscribe(() => this.republish());
@@ -207,7 +219,8 @@ window.__ModuleLoader__.load({
 						return s ? (s.clear ? "" : s.text) : undefined;
 					},
 					conflict: this.conflict,
-					failedKeys: [...this.failedKeys],
+					failedKeys: [...this.failedKeys].map(([ref, reason]) => ({ ref, reason })),
+					failedFields: [...this.failedFields],
 					saving: this.saving,
 					failed: this.failed,
 					version: (this.staged.size + ":" + [...this.staged.keys()].join(",")),
@@ -222,7 +235,12 @@ window.__ModuleLoader__.load({
 
 			/** Toggles write immediately (no staging); globals/keys stage + save. */
 			async setToggle(id, checked) {
-				await this.scope.set("enable" + id.charAt(0).toUpperCase() + id.slice(1), checked);
+				try {
+					await this.scope.set("enable" + id.charAt(0).toUpperCase() + id.slice(1), checked);
+				} catch (err) {
+					this.failed = true;
+					this.conflict = String(err).includes("SETTINGS_CONFLICT");
+				}
 				
 				this.republish();
 			}
@@ -243,7 +261,8 @@ window.__ModuleLoader__.load({
 
 			async save() {
 				if (this.saving) return;
-				this.saving = true; this.failed = false; this.republish();
+				this.saving = true; this.failed = false;
+			this.conflict = false; this.failedFields.clear(); this.republish();
 				const doneFields = [];
 				const doneKeys = [];
 				try {
@@ -251,13 +270,13 @@ window.__ModuleLoader__.load({
 						// Empty draft clears the override so the schema default applies again.
 						if (staged.clear || staged.text === "") { await this.scope.unset(field); doneFields.push(field); continue; }
 						if (SELECT_FIELDS[field]) {
-							if (!SELECT_FIELDS[field].includes(staged.text)) { this.failed = true; continue; }
+							if (!SELECT_FIELDS[field].includes(staged.text)) { this.failed = true; this.failedFields.add(field); continue; }
 							await this.scope.set(field, staged.text);
 							doneFields.push(field);
 							continue;
 						}
 						if (BOOLEAN_FIELDS.includes(field)) {
-							if (staged.text !== "true" && staged.text !== "false") { this.failed = true; continue; }
+							if (staged.text !== "true" && staged.text !== "false") { this.failed = true; this.failedFields.add(field); continue; }
 							await this.scope.set(field, staged.text === "true");
 							doneFields.push(field);
 							continue;
@@ -272,7 +291,7 @@ window.__ModuleLoader__.load({
 								backendTimeoutMs: [1000, 120000],
 							};
 							const [lo, hi] = BOUNDS[field] ?? [-Infinity, Infinity];
-							if (Number.isNaN(num) || num < lo || num > hi) { this.failed = true; continue; }
+							{ this.failed = true; this.failedFields.add(field); continue; }
 							await this.scope.set(field, num);
 							doneFields.push(field);
 						} else {
@@ -291,7 +310,7 @@ window.__ModuleLoader__.load({
 							} catch (keyErr) {
 								// env-shadowed reference (fail-loud doctrine): isolate so other keys still land.
 								this.failed = true;
-								this.failedKeys.add(ref);
+								this.failedKeys.set(ref, String(keyErr && keyErr.message ? keyErr.message : keyErr).slice(0, 140));
 								void keyErr;
 							}
 						}
@@ -329,7 +348,7 @@ window.__ModuleLoader__.load({
 			// no client-side default list to drift against the server.
 			const checked = props.value === true;
 			// Status dot: green keyless-or-keyed, amber enabled-but-key-missing.
-			const needsKey = !!b.keyEnv && !props.keyConfigured;
+			const needsKey = !!b.keyEnv && !b.optionalKey && !props.keyConfigured;
 			const dotColor = needsKey ? (checked ? "#e6a700" : "#888") : "#2ea043";
 			return react_jsx_runtime.jsxs("label", { className: "wsc-toggle", style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer" }, children: [
 				react_jsx_runtime.jsx("input", {
@@ -371,7 +390,7 @@ window.__ModuleLoader__.load({
 
 			// Status summary: enabled backends + configured keys at a glance.
 			const enabledCount = BACKENDS.filter((b) => state.value[toggleField(b.id)] === true).length;
-			const keyedBackends = BACKENDS.filter((b) => b.keyEnv);
+			const keyedBackends = BACKENDS.filter((b) => b.keyEnv && !b.optionalKey);
 			const keysReady = keyedBackends.filter((b) => state.keyState[b.keyEnv]?.configured).length;
 
 			const recencyOptions = [
@@ -397,6 +416,8 @@ window.__ModuleLoader__.load({
 					react_jsx_runtime.jsxs("span", { children: [props.t("statusKeys"), ": ", react_jsx_runtime.jsx("b", { children: keysReady + "/" + keyedBackends.length })] }),
 				] }),
 				react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, opacity: .65 }, children: props.t("description") }),
+				(enabledCount === 0) && react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, color: "#e6a700" }, children: props.t("fallbackHint") }),
+				(state.writable === false) && react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, color: "#e6a700" }, children: props.t("readOnlyScope") }),
 				react_jsx_runtime.jsx("h5", { className: "wsc-sectionTitle", children: props.t("groupFree") }),
 				react_jsx_runtime.jsx("div", { className: "wsc-toggles", children: KEYLESS.map((b) =>
 					react_jsx_runtime.jsx(ToggleRow, {
@@ -465,9 +486,15 @@ window.__ModuleLoader__.load({
 						options: boolOptions,
 						onChange: (v) => card.edit("safeSearch", v),
 					}),
+					react_jsx_runtime.jsx(SelectField, {
+						label: props.t("telemetryLabel"),
+						value: selVal("resultTelemetry", "true"),
+						options: boolOptions,
+						onChange: (v) => card.edit("resultTelemetry", v),
+					}),
 				] }),
 				react_jsx_runtime.jsx("h4", { className: "wsc-sectionTitle", children: props.t("keysTitle") }),
-				react_jsx_runtime.jsx("div", { className: "wsc-grid", children: BACKENDS.filter((b) => b.keyEnv).map((b) =>
+				react_jsx_runtime.jsx("div", { className: "wsc-grid", children: BACKENDS.filter((b) => b.keyEnv && !b.optionalKey).map((b) =>
 					react_jsx_runtime.jsxs("div", { children: [
 						react_jsx_runtime.jsxs("div", { className: "wsc-fieldHead", children: [
 							react_jsx_runtime.jsx("span", { className: "wsc-label", children: props.t("keyLabel", { id: b.id }) }),
@@ -492,11 +519,24 @@ window.__ModuleLoader__.load({
 						state.failedKeys.includes(b.keyEnv) && react_jsx_runtime.jsx("p", { className: "wsc-hint", style: { color: "#e5534b" }, children: props.t("keyFailed") }),
 					] }, b.id)
 				) }),
+				react_jsx_runtime.jsx("h5", { className: "wsc-sectionTitle", children: props.t("optionalTitle") }),
+				react_jsx_runtime.jsx("div", { className: "wsc-grid", children: OPTIONAL_KEYS.map((b) =>
+					react_jsx_runtime.jsxs("div", { children: [
+						react_jsx_runtime.jsx("div", { className: "wsc-fieldHead", children: react_jsx_runtime.jsx("span", { className: "wsc-label", children: props.t("keyLabel", { id: b.id }) }) }),
+						react_jsx_runtime.jsx("input", {
+							className: "wsc-keyInput", type: "password", autoComplete: "off",
+							placeholder: b.keyEnv,
+							value: state.stagedKeys[b.keyEnv] ?? "",
+							onChange: (e) => card.editKey(b.keyEnv, e.target.value),
+						}),
+					] }, b.id),
+				) }),
 				state.stagedCount > 0 && react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, opacity: .6 }, children: props.t("unsavedHint") }),
 				react_jsx_runtime.jsxs("div", { className: "wsc-actions", children: [
-					react_jsx_runtime.jsx("button", { className: "wsc-btn", disabled: state.saving || state.stagedCount === 0, onClick: () => card.save(), children: state.saving ? props.t("saving") : props.t("save") }),
+					react_jsx_runtime.jsx("button", { className: "wsc-btn", disabled: state.saving || state.stagedCount === 0 || state.writable === false, onClick: () => card.save(), children: state.saving ? props.t("saving") : props.t("save") }),
 					(state.stagedCount > 0) && react_jsx_runtime.jsx("button", { className: "wsc-btn wsc-btnGhost", onClick: () => card.discard(), children: props.t("discard") }),
 					state.failed && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#e5534b" }, children: props.t("failed") }),
+					(state.failedFields.length > 0) && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#e5534b", fontSize: 11 }, children: props.t("invalidFields") + ": " + state.failedFields.join(", ") }),
 				state.conflict && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#e6a700" }, children: props.t("conflict") }),
 					!state.failed && !state.saving && state.savedAt > 0 && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#2ea043" }, children: props.t("savedOk") }),
 				] }),

package/lib/index.js

@@ -141,6 +141,8 @@ export const Config = z.object({
     .description("去重策略：url 仅按链接；url+title 额外合并同标题的转载镜像"),
   rerank: z.boolean().default(false)
     .description("按查询词相关性重排序（确定性、并列时保持后端优先级）"),
+  resultTelemetry: z.boolean().default(true)
+    .description("在搜索结果尾部附一行后端健康遥测（状态+耗时），模型可据此自诊断"),
 
   // Enable toggles (one per backend)
   enableExa: z.boolean().default(true).description(DEFAULT_LABELS.exa),
@@ -265,6 +267,7 @@ export function resolveOptions(ctx, config) {
     // v2.1 shaping options consumed by the provider merge pipeline.
     dedupStrategy: config?.dedupStrategy === "url+title" ? "url+title" : "url",
     rerank: config?.rerank === true,
+    resultTelemetry: config?.resultTelemetry !== false,
     filters: {
       recency: typeof config?.recency === "string" && config.recency !== "any" ? config.recency : undefined,
       lang: language.length > 0 ? language : undefined,

package/lib/provider.js

@@ -87,7 +87,13 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
     async search(request, signal) {
       throwIfSearchAborted(signal);
       const opts = resolveOptions();
-      const maxResults = request.maxResults ?? opts.numResults ?? 8;
+      const filters = normalizeFilters({
+      ...(opts.filters ?? {}),
+      ...(request?.filters ?? {}),
+      });
+        let effReq = { ...request, maxResults: Math.max(1, Number(request?.maxResults) || opts.numResults || 8) };
+      if (Object.keys(filters).length > 0) effReq = { ...effReq, filters };
+      const maxResults = effReq.maxResults;
       const concurrency = opts.concurrency ?? 6;
       const backendTimeoutMs = opts.backendTimeoutMs ?? 30000;
 
@@ -112,13 +118,8 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       // Settings-level default filters, overridden by per-request filters
       // (normalizeFilters drops unknown/invalid values so typos degrade to
       // "no filter" instead of breaking the search).
-      const filters = normalizeFilters({
-        ...(opts.filters ?? {}),
-        ...(request?.filters ?? {}),
-      });
-      const effectiveRequest =
-        Object.keys(filters).length > 0 ? { ...request, filters } : request;
 
+      const telemetry = [];
       // Concurrency limiter
       const limit = createLimiter(opts.concurrency ?? 6);
 
@@ -128,13 +129,36 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       // reclassified as WEB_PROVIDER_ERROR so timeouts surface as real
       // failures instead of being silently demoted like user cancellations.
       const runBackend = ({ id, backend, beOpts, hooks }) => {
+        const startedAtMs = Date.now();
+        // Trust boundary: baseURL is operator-configurable and API keys are sent to it.
+        // Enforce http(s); plain http only for private hosts (self-hosted SearXNG).
+        // Reject embedded credentials. Failure is a per-backend soft error.
+        if (beOpts.baseURL !== undefined) {
+          let bu = null;
+          try { bu = new URL(beOpts.baseURL); } catch { bu = null; }
+          const privHost = bu ? /^(localhost|127(\.\d{1,3}){3}|10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){3}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){3})$/.test(bu.hostname) : false;
+          const schemeOk = bu && (bu.protocol === "https:" || (bu.protocol === "http:" && privHost));
+          if (!schemeOk || bu.username || bu.password) {
+            throw new WebError(`backend "${id}" has an invalid baseURL: https required (plain http only for private hosts), credentials-in-URL rejected`, "WEB_PROVIDER_ERROR");
+          }
+        }
         const controller = new AbortController();
         const mergedSignal = signal
           ? AbortSignal.any([signal, controller.signal])
           : controller.signal;
         const timeoutId = setTimeout(() => controller.abort(), backendTimeoutMs);
         return backend
-          .search(effectiveRequest, mergedSignal, beOpts, hooks)
+          .search(effReq, mergedSignal, beOpts, hooks)
+          .then(
+            (value) => {
+              telemetry.push({ id, ok: true, ms: Date.now() - startedAtMs, count: value?.sources?.length ?? 0 });
+              return value;
+            },
+            (err) => {
+              telemetry.push({ id, ok: false, ms: Date.now() - startedAtMs, error: String(err instanceof Error ? err.message : err).slice(0, 80) });
+              throw err;
+            },
+          )
           .catch((err) => {
             if (controller.signal.aborted && !(signal && signal.aborted)) {
               throw new WebError(
@@ -178,7 +202,12 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
           if (mergedContent === undefined && typeof settled.value?.content === "string" && settled.value.content.length > 0) {
             mergedContent = settled.value.content;
           }
-          for (const s of settled.value?.sources ?? []) collected.push(s);
+          for (const src of settled.value?.sources ?? []) {
+            // Scheme whitelist: parsed URLs reach model/GUI consumers; drop
+            // javascript:/data: payloads from compromised or poisoned backends.
+            if (src && typeof src.url === "string" && !/^https?:\/\//i.test(src.url)) continue;
+            collected.push(src);
+          }
         } else {
           // settled.status === "rejected"
           const err = settled.reason;
@@ -211,9 +240,16 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       // If we got ANY sources, return them even if some backends failed.
       if (ordered.length > 0) {
         const sources = ordered.slice(0, maxResults);
+        let outContent = mergedContent;
+        if (opts.resultTelemetry !== false && telemetry.length > 0) {
+          const line = "[websearch backends] " + telemetry
+            .map((t) => t.id + (t.ok ? " ✓" : " ✗") + t.ms + "ms" + (t.ok ? "/" + t.count : (t.error ? " (" + String(t.error).slice(0, 40) + ")" : "")))
+            .join(" · ");
+          outContent = outContent === undefined ? line : outContent + "\n\n" + line;
+        }
         return {
           sources,
-          ...(mergedContent !== undefined ? { content: mergedContent } : {}),
+          ...(outContent !== undefined ? { content: outContent } : {}),
           truncated: ordered.length > maxResults,
         };
       }
@@ -225,7 +261,7 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
         .join("; ");
       const allKeyMissing =
         failures.length > 0 &&
-        failures.every((f) => f.err instanceof WebError && f.err.code === "WEB_PROVIDER_UNAVAILABLE");
+        failures.every((f) => f.err instanceof WebError && (f.err.code === "WEB_PROVIDER_UNAVAILABLE" || f.err.code === "WEB_PROVIDER_CREDENTIAL_MISSING"));
       const hint = allKeyMissing
         ? " (every enabled backend is missing its API key - add keys in Settings > Web Search, or enable a keyless backend)"
         : "";

package/lib/util/log.js

@@ -56,7 +56,7 @@ export function recordBackendOutcome(ctx, backendId, outcome) {
     const logger = ctx && ctx.logger;
     if (!logger) return;
     const status = outcome && typeof outcome.status === "string" ? outcome.status : "";
-    const line = "[websearch:" + backendId + "] outcome " + JSON.stringify(outcome ?? {});
+    const line = "[websearch:" + backendId + "] outcome " + JSON.stringify(outcome ?? {}).slice(0, 500);
     if (status === "error" && typeof logger.warn === "function") logger.warn(line);
     else if (typeof logger.debug === "function") logger.debug(line);
   } catch {

package/lib/util/mcp-client.js

@@ -7,7 +7,7 @@
 
 import { WebError } from "@deepseek-ai/dsh-web";
 
-const UA = "dsh-websearch/2.1";
+const UA = "dsh-websearch/2.3";
 const PROTOCOL_VERSION = "2025-06-18";
 const SESSION_TTL_MS = 10 * 60 * 1000; // 10 minutes
 
@@ -58,7 +58,7 @@ async function ensureSession(url, signal) {
   }
 
   if (!initResponse.ok) {
-    const text = await initResponse.text().catch(() => "");
+    const text = await initResponse.text().catch(() => "").then((tx) => tx.slice(0, 300));
     throw new WebError(`MCP initialize HTTP ${initResponse.status}: ${text}`, "WEB_PROVIDER_ERROR");
   }
 
@@ -75,7 +75,7 @@ async function ensureSession(url, signal) {
   };
   
   try {
-    await fetch(url, {
+    const notifyResponse = await fetch(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -86,6 +86,8 @@ async function ensureSession(url, signal) {
       signal,
       redirect: "error",
     });
+    // Drain the discarded body so undici returns the socket to the pool.
+    notifyResponse.body?.cancel?.().catch(() => {});
   } catch (error) {
     // Best-effort: Exa requires this, Parallel tolerates absence
     if (signal?.aborted) throw error;
@@ -104,17 +106,16 @@ async function ensureSession(url, signal) {
 function parseEnvelope(text, expectedId) {
   // Try SSE format first: "event: message\ndata: {...}\n\n"
   if (text.includes("data:")) {
-    const lines = text.trim().split("\n");
-    let dataLine = null;
-    for (const line of lines) {
-      if (line.startsWith("data:")) {
-        dataLine = line.slice(5).trim();
-        break;
-      }
-    }
-    if (dataLine) {
+    // SSE spec: one JSON payload may span multiple data: lines - join them.
+    const joined = text
+      .trim()
+      .split("\n")
+      .filter((l) => l.startsWith("data:"))
+      .map((l) => l.slice(5).trim())
+      .join("");
+    if (joined) {
       try {
-        return JSON.parse(dataLine);
+        return JSON.parse(joined);
       } catch {}
     }
   }
@@ -205,7 +206,7 @@ export async function mcpCall(url, toolName, args, extraHeaders = {}, signal) {
   }
 
   if (!response.ok) {
-    const text = await response.text().catch(() => "");
+    const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
     throw new WebError(`MCP tools/call HTTP ${response.status}: ${text}`, "WEB_PROVIDER_ERROR");
   }
 

package/lib/util/rank.js

@@ -97,7 +97,7 @@ function scoreSource(source, queryTokens) {
   let score = 0;
   const titleTokens = tokenize(source.title ?? "");
   const snippetTokens = tokenize(source.snippet ?? "");
-  const urlTokens = tokenize(String(source.url ?? "").replace(/[^a-z0-9]+/g, " "));
+  const urlTokens = tokenize(String(source.url ?? ""));
   for (const q of queryTokens) {
     if (titleTokens.has(q)) score += 3;
     if (snippetTokens.has(q)) score += 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@240xu/dsh-websearch",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Unified web search provider for DeepSeek Harness (ctx.web): 11 backends \u2014 Exa + Parallel + DDG + SearXNG (keyless), DeepSeek + Anthropic + OpenAI + Brave + Tavily + Serper + Mojeek (key-gated via Settings credentials). Registers provider id \"unified\" for zero-config web_search tool.",
   "type": "module",
   "main": "lib/index.js",

package/lib/backends/index.js

@@ -1,121 +0,0 @@
-/**
- * Unified backend registry for dsh-websearch.
- * Auto-discovers and exports all backend implementations.
- */
-
-import { exaBackend } from "./exa.js";
-import { parallelBackend } from "./parallel.js";
-import { ddgBackend } from "./ddg.js";
-import { deepseekBackend, anthropicBackend } from "./anthropic-like.js";
-import { openaiBackend } from "./openai.js";
-import { braveBackend } from "./brave.js";
-import { tavilyBackend } from "./tavily.js";
-import { serperBackend } from "./serper.js";
-import { searxngBackend } from "./searxng.js";
-import { mojeekBackend } from "./mojeek.js";
-
-// Individual backend exports for direct import
-export { exaBackend } from "./exa.js";
-export { parallelBackend } from "./parallel.js";
-export { ddgBackend } from "./ddg.js";
-export { deepseekBackend, anthropicBackend } from "./anthropic-like.js";
-export { openaiBackend } from "./openai.js";
-export { braveBackend } from "./brave.js";
-export { tavilyBackend } from "./tavily.js";
-export { serperBackend } from "./serper.js";
-export { searxngBackend } from "./searxng.js";
-export { mojeekBackend } from "./mojeek.js";
-
-
-/** All registered backends. Order = default fan-out priority. */
-export const BACKENDS = {
-  exa: exaBackend,
-  parallel: parallelBackend,
-  ddg: ddgBackend,
-  searxng: searxngBackend,      // keyless, new
-  brave: braveBackend,          // key-gated, new
-  tavily: tavilyBackend,        // key-gated, new
-  serper: serperBackend,        // key-gated, new
-  mojeek: mojeekBackend,        // key-gated, new
-  deepseek: deepseekBackend,
-  anthropic: anthropicBackend,
-  openai: openaiBackend,
-};
-
-/** All backend IDs in registry order. */
-export const ALL_BACKEND_IDS = Object.keys(BACKENDS);
-
-/** Default enabled backends (keyless only). */
-export const DEFAULT_ENABLED = ["exa", "parallel", "ddg", "searxng"];
-
-/** Environment variable names for key-gated backends. */
-export const DEFAULT_KEY_ENV = {
-  deepseek: "DEEPSEEK_API_KEY",
-  anthropic: "ANTHROPIC_API_KEY",
-  openai: "OPENAI_API_KEY",
-  brave: "BRAVE_API_KEY",
-  tavily: "TAVILY_API_KEY",
-  serper: "SERPER_API_KEY",
-  mojeek: "MOJEEK_API_KEY",
-};
-
-/** Default base URLs for each backend. */
-export const DEFAULT_BASE_URLS = {
-  exa: "https://mcp.exa.ai/mcp",
-  parallel: "https://search.parallel.ai/mcp",
-  ddg: "https://html.duckduckgo.com/html/",
-  searxng: "https://searx.be",
-  brave: "https://api.search.brave.com/res/v1/web/search",
-  tavily: "https://api.tavily.com/search",
-  serper: "https://google.serper.dev/search",
-  mojeek: "https://api.mojeek.com/v1/search",
-  deepseek: "https://api.deepseek.com/anthropic/v1",
-  anthropic: "https://api.anthropic.com/v1",
-  openai: "https://api.openai.com/v1",
-};
-
-/** Backend type classification for GUI. */
-export const BACKEND_TYPES = {
-  exa: "mcp",
-  parallel: "mcp",
-  ddg: "keyless",
-  searxng: "keyless",
-  brave: "credential",
-  tavily: "credential",
-  serper: "credential",
-  mojeek: "credential",
-  deepseek: "credential",
-  anthropic: "credential",
-  openai: "credential",
-};
-
-/** Human-readable labels for GUI. */
-export const BACKEND_LABELS = {
-  exa: "Exa (MCP, 免费无 Key)",
-  parallel: "Parallel (MCP, 免费无 Key)",
-  ddg: "DuckDuckGo (HTML 抓取, 兜底)",
-  searxng: "SearXNG (元搜索, 免费无 Key)",
-  brave: "Brave Search (独立索引, 2000/月免费)",
-  tavily: "Tavily (AI 专用, 含答案摘要)",
-  serper: "Serper.dev (Google 抓取, 2500/月免费)",
-  mojeek: "Mojeek (独立索引, 1000/天免费)",
-  deepseek: "DeepSeek (原生 web_search, 需 Key)",
-  anthropic: "Anthropic (Claude 原生 web_search, 需 Key)",
-  openai: "OpenAI (Responses API web_search, 需 Key)",
-};
-
-/** Backend descriptions for GUI tooltips. */
-export const BACKEND_DESCRIPTIONS = {
-  exa: "流式 HTTP MCP 协议，原生 web_search_exa 工具，结果含标题/URL/高亮摘要",
-  parallel: "流式 HTTP MCP 协议，原生 web_search 工具，返回结构化 JSON 含摘要数组",
-  ddg: "HTML 页面抓取解析，通过 uddg= 参数还原真实 URL，零依赖兜底",
-  searxng: "开源元搜索引擎聚合，可指向公共实例或自托管，隐私友好",
-  brave: "Brave 独立搜索索引，REST API，免费 2000 次/月，结果质量高",
-  tavily: "AI 专用搜索，可返回 AI 生成答案 + 结构化结果，支持深度搜索模式",
-  serper: "抓取 Google SERP，结构化 organic[] 结果，免费 2500 次/月，速度极快",
-  mojeek: "英国独立搜索引擎，无追踪，免费 1000 次/天，英文为主",
-  deepseek: "DeepSeek Anthropic 兼容 API + 原生 web_search_20250305 工具",
-  anthropic: "Claude 官方 Messages API + web_search_20250305 原生工具",
-  openai: "OpenAI Responses API + 原生 web_search 工具，解析 url_citation 注释",
-};
-

package/lib/util/rpc.js

@@ -1,262 +0,0 @@
-/**
- * @module dsh-websearch/util/rpc
- *
- * Minimal MCP JSON-RPC 2.0 client for the streamable-http transport used by
- * Exa (https://mcp.exa.ai/mcp) and Parallel (https://search.parallel.ai/mcp).
- *
- * Streamable-HTTP MCP servers require a 2-step handshake per session:
- *   1. POST initialize → server replies with its capabilities and (for Exa)
- *      a Mcp-Session-Id header. Parallel also returns this header.
- *   2. POST notifications/initialized → notify the server the client is ready.
- *      (Exa rejects tools/call without this; Parallel tolerates its absence
- *      but sending it is harmless.)
- *   3. POST tools/call with the Mcp-Session-Id header → returns either a plain
- *      JSON body OR a text/event-stream of "data: {…}\n\n" frames.
- *
- * We cache the Mcp-Session-Id per server URL inside the process so subsequent
- * searches skip the handshake (and one cache entry survives across calls).
- * Sessions are NOT shared across processes (each dsh-web worker owns its own).
- *
- * Failures are zh-folded into WebError so the provider fan-out can demote them
- * to soft nulls when only one backend fails.
- */
-import { WebError } from "@deepseek-ai/dsh-web";
-import { throwIfSearchAborted, searchAborted, isAbortError } from "./abort.js";
-
-/** User-Agent header; bumped with the package version. */
-export const UA = "dsh-websearch/2.1";
-
-/** MCP protocol version we negotiate. */
-const PROTOCOL_VERSION = "2025-06-18";
-
-/** Per-URL session cache: url → { sessionId, initializedAt }. */
-const sessionCache = new Map();
-const SESSION_TTL_MS = 10 * 60 * 1000; // Exa sessions live indefinitely; this is a courtesy cap.
-
-/** Monotonic request id so concurrent inits don't collide. */
-let nextReqId = 1;
-
-/**
- * Initialize (or reuse) a streamable-http MCP session.
- * Sends initialize + notifications/initialized. Returns the Mcp-Session-Id,
- * caching it so callers don't pay the handshake more than once per TTL.
- *
- * @param {string} url
- * @param {AbortSignal} [signal]
- * @returns {Promise<string|null>} Mcp-Session-Id (or null if the server omits it).
- * @throws {WebError} on transport error or abort.
- */
-async function ensureSession(url, signal) {
-  throwIfSearchAborted(signal);
-  const cached = sessionCache.get(url);
-  if (cached && Date.now() - cached.initializedAt < SESSION_TTL_MS && cached.sessionId) {
-    return cached.sessionId;
-  }
-
-  const initId = nextReqId++;
-  const initBody = JSON.stringify({
-    jsonrpc: "2.0",
-    id: initId,
-    method: "initialize",
-    params: {
-      protocolVersion: PROTOCOL_VERSION,
-      capabilities: {},
-      clientInfo: { name: "dsh-websearch", version: "1.0" },
-    },
-  });
-
-  let res;
-  try {
-    res = await fetch(url, {
-      method: "POST",
-      redirect: "error",
-      headers: {
-        "Content-Type": "application/json",
-        "Accept": "application/json, text/event-stream",
-        "User-Agent": UA,
-      },
-      body: initBody,
-      ...(signal !== undefined ? { signal } : {}),
-    });
-  } catch (error) {
-    if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-    throw new WebError(
-      `mcp initialize fetch failed for ${url}: ${String(error?.message ?? error)}`,
-      "WEB_PROVIDER_ERROR",
-      { cause: error },
-    );
-  }
-  throwIfSearchAborted(signal);
-  if (!res.ok) {
-    let detail = "";
-    try { detail = (await res.text()).slice(0, 300); } catch {}
-    throw new WebError(
-      `mcp initialize HTTP ${res.status} for ${url}${detail ? ": " + detail : ""}`,
-      "WEB_PROVIDER_ERROR",
-    );
-  }
-
-  // Drain the initialize response body (we don't need its content).
-  await res.text();
-
-  const sessionId = res.headers.get("Mcp-Session-Id") || null;
-
-  // Send notifications/initialized (some servers reject tools/call without it).
-  if (sessionId) {
-    try {
-      await fetch(url, {
-        method: "POST",
-        redirect: "error",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json, text/event-stream",
-          "User-Agent": UA,
-          "Mcp-Session-Id": sessionId,
-        },
-        body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
-        ...(signal !== undefined ? { signal } : {}),
-      });
-    } catch (error) {
-      // notifications/initialized is best-effort; ignore transport errors here.
-      // (If the session is gone we'll discover that via tools/call.) Re-raise aborts.
-      if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-    }
-  }
-
-  sessionCache.set(url, { sessionId, initializedAt: Date.now() });
-  return sessionId;
-}
-
-/**
- * Parse a streamable-HTTP MCP response body into the first JSON-RPC envelope.
- *
- * Servers respond with EITHER:
- *   - a single JSON object (Parallel: {"jsonrpc":"2.0","id":N,"result":{…}} or {...,"error":{…}}), OR
- *   - a text/event-stream of "event: <type>\n data: {…}\n\n" frames (Exa).
- *
- * We scan line-by-line; SSE data: frames take precedence, otherwise we fall back
- * to scanning whole-line JSON.
- *
- * @param {string} text
- * @param {number} reqId  the request id we expect to be echoed back
- * @returns {{result?:object, error?:object}}
- * @throws if no parseable envelope is found.
- */
-function parseEnvelope(text, reqId) {
-  const lines = String(text).split("\n");
-  let lastJson = null;
-  for (const raw of lines) {
-    const line = raw.trim();
-    if (!line) continue;
-    let json;
-    if (line.startsWith("data: ")) {
-      json = line.slice(6).trim();
-    } else if (line.startsWith("{")) {
-      json = line;
-    } else {
-      continue;
-    }
-    if (!json.startsWith("{")) continue;
-    let obj;
-    try { obj = JSON.parse(json); } catch { continue; }
-    // Prefer the envelope matching our request id; otherwise keep the last seen.
-    if (typeof obj.id === "number" && obj.id === reqId) return obj;
-    lastJson = obj;
-  }
-  return lastJson;
-}
-
-/**
- * JSON-RPC 2.0 tools/call against a streamable-http MCP server (after the
- * initialize + notifications/initialized handshake is established or reused).
- *
- * @param {string} url       the MCP server endpoint
- * @param {string} toolName  the tool to invoke (e.g. "web_search_exa", "web_search")
- * @param {object} args      the tool's arguments (per its input schema)
- * @param {object} [extraHeaders]
- * @param {AbortSignal} [signal]
- * @returns {Promise<object>} the RPC `result` payload (the `content` array etc.)
- * @throws {WebError} on HTTP failure, RPC error, abort, or unparseable response.
- */
-export async function rpcCall(url, toolName, args, extraHeaders, signal) {
-  const sessionId = await ensureSession(url, signal);
-  const reqId = nextReqId++;
-
-  const headers = {
-    "Content-Type": "application/json",
-    "Accept": "application/json, text/event-stream",
-    "User-Agent": UA,
-    ...(sessionId ? { "Mcp-Session-Id": sessionId } : {}),
-    ...(extraHeaders || {}),
-  };
-  const body = JSON.stringify({
-    jsonrpc: "2.0",
-    id: reqId,
-    method: "tools/call",
-    params: { name: toolName, arguments: args },
-  });
-
-  let res;
-  try {
-    res = await fetch(url, {
-      method: "POST",
-      redirect: "error",
-      headers,
-      body,
-      ...(signal !== undefined ? { signal } : {}),
-    });
-  } catch (error) {
-    if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-    throw new WebError(
-      `mcp rpc ${toolName} fetch failed: ${String(error?.message ?? error)}`,
-      "WEB_PROVIDER_ERROR",
-      { cause: error },
-    );
-  }
-  throwIfSearchAborted(signal);
-
-  if (!res.ok) {
-    let detail = "";
-    try { detail = (await res.text()).slice(0, 300); } catch {}
-    // If the server rejected the request id/session, nuke the cached session
-    // so the next call re-initializes. 404/401/403 typically mean session death.
-    if (res.status === 401 || res.status === 403 || res.status === 404) {
-      sessionCache.delete(url);
-    }
-    throw new WebError(
-      `mcp rpc ${toolName} HTTP ${res.status}${detail ? ": " + detail : ""}`,
-      "WEB_PROVIDER_ERROR",
-    );
-  }
-
-  const text = await res.text();
-  throwIfSearchAborted(signal);
-
-  const env = parseEnvelope(text, reqId);
-  if (!env) {
-    throw new WebError(
-      `mcp rpc ${toolName} returned an unparseable response`,
-      "WEB_PROVIDER_ERROR",
-    );
-  }
-  if (env.error) {
-    throw new WebError(
-      `mcp rpc ${toolName} error: ${env.error.message || JSON.stringify(env.error)}`,
-      "WEB_PROVIDER_ERROR",
-    );
-  }
-  if (!env.result) {
-    throw new WebError(
-      `mcp rpc ${toolName} returned a response with no result`,
-      "WEB_PROVIDER_ERROR",
-    );
-  }
-  return env.result;
-}
-
-/** Drop the cached session for a url (used by backends after a fatal error). */
-export function invalidateSession(url) {
-  sessionCache.delete(url);
-}
-
-export { throwIfSearchAborted, searchAborted, isAbortError };