@sema-agent/server 3.17.0 → 3.19.0

package/dist/main.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { Runner, TtlSessionStore, uuidv7, defaultTaskRegistry, combinePolicies, createDurableQuestionPolicy, createAllowDenyPolicy, workflowsCapability, createWebFetchSummarizer, resolveTaskModel as coreResolveTaskModel } from "@sema-agent/core";
+import { Runner, TtlSessionStore, uuidv7, defaultTaskRegistry, combinePolicies, createDurableQuestionPolicy, createAllowDenyPolicy, workflowsCapability, createWebFetchSummarizer, resolveTaskModel as coreResolveTaskModel, probeSearchBackend } from "@sema-agent/core";
 import { createSessionTitler } from "./session-titler.js";
 import { posIntEnv } from "./session-watch.js";
 import { selectEnvironmentTool } from "./capabilities/select-environment-tool.js";
@@ -12,7 +12,7 @@ import { isPricingConfigured } from "./budget.js"; // 缝合审 M3:capabilities.
 import { drainNumEnvWarnings } from "./plugins/remote-shell.js";
 import { ensureChildSessionDurableWithPromotion } from "./plugins/session-store.js";
 import { ForkRoutingSessionStore } from "./plugins/fork-routing-session-store.js";
-import { webSearchConfigFromEnv, createWebSearchBackend, setWebSearchBadPayloadObserver } from "./plugins/web-search.js";
+import { webSearchConfigFromEnv, createWebSearchBackend, setWebSearchBadPayloadObserver, shouldProbeWebSearchOnBoot } from "./plugins/web-search.js";
 import { createAuthorizer } from "./security.js";
 import { createDurableAskPolicy, hasOperatorGateIntent } from "./approval.js";
 import { loadSkills } from "./capabilities/skills.js";
@@ -506,6 +506,22 @@ async function main() {
     const webSearch = webSearchCfg ? createWebSearchBackend(webSearchCfg) : undefined;
     if (webSearch)
         logger.info(`WebSearch enabled (provider=${webSearchCfg.provider}, maxResults=${webSearch.maxResults})`);
+    // #81④ 探活(boot 期一次性,**默认 OFF**):部署方此前只能靠「跑一个真任务」验证搜索配没配对 ——
+    // cli 的一键装 SearXNG 向导([2226] 裁 1)装完那一步正需要这个。消费 core 的 `probeSearchBackend`
+    // (不自铸第二真源,与 searxng adapter 同一条纪律)。
+    // 🔴 **失败只 warn,不拒启**:搜索是可选工具,配错不该挡住整个服务(功能型能力缺席 ⇒ 降级;
+    //    与本仓「保护型 ⇒ fail-closed」的方向判据是同一条判据的两面)。
+    // 🔴 **不 await**:探活是一次真出网,让它拖住 boot 就是把一个可选工具变成启动路径上的依赖。
+    if (webSearch && shouldProbeWebSearchOnBoot()) {
+        void probeSearchBackend(webSearch.search, { timeoutMs: 10_000 })
+            .then((r) => {
+            if (r.ok)
+                logger.info("web_search_probe_ok", { provider: webSearchCfg.provider, results: r.results });
+            else
+                logger.warn("web_search_probe_failed", { provider: webSearchCfg.provider, error: r.error, note: "WebSearch stays mounted — the tool will fail per-call until this is fixed; the service is not blocked by it." });
+        })
+            .catch((e) => logger.warn("web_search_probe_failed", { provider: webSearchCfg.provider, error: e instanceof Error ? e.message : String(e) }));
+    }
     // core 1.382([1561] 提货单①②,design/153 parked 状态机)「同车必接」的 ensureChildSessionDurable 挂点:
     // 只在 checkpointStore 真在场时构造(与 core parkEligible 门「两者全在场才成立」的判据同源——checkpoint
     // 不在场时构造这个闭包毫无意义,连带把「local/无 durable backend 部署不该跑这条 acquire/release」的

package/dist/plugins/web-search.d.ts

@@ -24,7 +24,11 @@
  *    ⚠️ 判据留痕:我第一轮把这条判成了「约束被静默丢弃」的安全缺口,是**亲读 core 结果侧代码**
  *    才推翻的。「别处已经处理了」这种声明必须验证 —— 这次它是真的,但真假只能靠读。
  *
- * ② **searxng 腿是自铸的第二真源**。core 2.10 起已导出 `createSearxngSearchBackend`
+ * ② ~~**searxng 腿是自铸的第二真源**~~ —— ✅ **已还(2026-08-01,[2229] 裁定 searxng 为国内可达性
+ *    主路线之后)**:本腿改为消费 core 的 `createSearxngSearchBackend`,外层保住 maxResults 截断 /
+ *    统一形状 / 坏 payload 观测器三样(各有红先钉 + 变异实测),白得 `site:` 原生下推、`extraParams`、
+ *    自带 timeout。以下为原始立案文本,留档:
+ *    core 2.10 起已导出 `createSearxngSearchBackend`
  *    (+`SearxngBackendOptions`),而且比本文件的实现多三样:`allowedDomains` 拼 `site:` 原生下推、
  *    `extraParams`(实例特定的 `engines=`/`language=` 等)、**自带 timeout**
  *    (`AbortSignal.any([signal, timeout])`;本文件的 searxng 腿只吃外部 signal)。
@@ -37,7 +41,11 @@
  *    能自行打开搜索,它就在升级后**凭空长出一条出网工具** —— 那是安全姿态变更,不是特性。
  *    ⇒ 语义定稿前,任何新的开启通道**默认 OFF**;开启必须是部署方的显式动作。
  *
- * ④ **探活 verb 缺席**。core 2.10 起导出 `probeSearchBackend(search, {timeoutMs}) →
+ * ④ ~~**探活 verb 缺席**~~ —— ✅ **已还(2026-08-01)**:`shouldProbeWebSearchOnBoot` 门控 +
+ *    `main.ts` 消费 core 的 `probeSearchBackend`。**默认 OFF**(开着=给每个既有部署的每次启动凭空
+ *    加一次出网)、**只认明确真值**(含糊值当没开,别替部署方猜)、**失败只 warn 不拒启**(功能型
+ *    能力缺席 ⇒ 降级)、**不 await**(拖住 boot 就把可选工具变成启动依赖)。以下为原始立案文本,留档:
+ *    core 2.10 起导出 `probeSearchBackend(search, {timeoutMs}) →
  *    {ok:true,results:n} | {ok:false,error}`,正好填这条:部署方现在只能靠「跑一个真任务」
  *    验证搜索配对不对。挂哪儿(boot 期一次性 warn / `/health` 子字段 / 显式端点)未定 ——
  *    注意 boot 期探活会给每次启动加一次出网,多租/离线部署要能关。
@@ -48,6 +56,9 @@ export interface WebSearchBackendConfig {
     readonly provider: WebSearchProvider;
     /** API key (brave/tavily). From `WEB_SEARCH_API_KEY` — never reaches the model. */
     readonly apiKey?: string;
+    /** SearXNG 实例特定查询参数(`engines=` / `language=` 等)——透传给 core adapter 的 `extraParams`。
+     *  一键装 SearXNG 的向导用它把「选了哪些上游引擎」落到引擎侧。仅 searxng 腿消费。 */
+    readonly searxngParams?: Record<string, string>;
     /** SearXNG instance base URL (REQUIRED for searxng); for brave/tavily an optional base-URL override (proxy/test). */
     readonly endpoint?: string;
     /** Max results returned to the model (clamped 1..20; default 10). */
@@ -79,6 +90,17 @@ export declare function setWebSearchBadPayloadObserver(fn: ((provider: string) =
  * stays captured in this closure — it is never surfaced to the model or the tool args.
  */
 export declare function createWebSearchBackend(cfg: WebSearchBackendConfig): WebSearchBackend;
+/**
+ * #81④ 探活门控 —— **默认 OFF**,显式开才探。
+ *
+ * 为什么默认 OFF:探活是一次**真出网**。开着就等于给每个既有部署的每次启动凭空加一次外呼 ——
+ * 多租/离线部署不能被这样动。这与 #81③「任何新的开启通道默认 OFF」同源:
+ * 一个只配了模型 key 的部署,不该因为升级而多出网络行为。
+ *
+ * 为什么只认明确真值:`"yes"`/`"on"` 这类**含糊值当没开**。含糊值上放行 = 替部署方猜意图,
+ * 而猜错的方向是「凭空出网」。缺席要缺席得干净,含糊也一样。
+ */
+export declare function shouldProbeWebSearchOnBoot(env?: NodeJS.ProcessEnv): boolean;
 /** Parse the deployment env into a backend config; `undefined` when no provider is set (⇒ WebSearch not assembled). */
 export declare function webSearchConfigFromEnv(env?: NodeJS.ProcessEnv): WebSearchBackendConfig | undefined;
 /**

package/dist/plugins/web-search.js

@@ -24,7 +24,11 @@
  *    ⚠️ 判据留痕:我第一轮把这条判成了「约束被静默丢弃」的安全缺口,是**亲读 core 结果侧代码**
  *    才推翻的。「别处已经处理了」这种声明必须验证 —— 这次它是真的,但真假只能靠读。
  *
- * ② **searxng 腿是自铸的第二真源**。core 2.10 起已导出 `createSearxngSearchBackend`
+ * ② ~~**searxng 腿是自铸的第二真源**~~ —— ✅ **已还(2026-08-01,[2229] 裁定 searxng 为国内可达性
+ *    主路线之后)**:本腿改为消费 core 的 `createSearxngSearchBackend`,外层保住 maxResults 截断 /
+ *    统一形状 / 坏 payload 观测器三样(各有红先钉 + 变异实测),白得 `site:` 原生下推、`extraParams`、
+ *    自带 timeout。以下为原始立案文本,留档:
+ *    core 2.10 起已导出 `createSearxngSearchBackend`
  *    (+`SearxngBackendOptions`),而且比本文件的实现多三样:`allowedDomains` 拼 `site:` 原生下推、
  *    `extraParams`(实例特定的 `engines=`/`language=` 等)、**自带 timeout**
  *    (`AbortSignal.any([signal, timeout])`;本文件的 searxng 腿只吃外部 signal)。
@@ -37,11 +41,16 @@
  *    能自行打开搜索,它就在升级后**凭空长出一条出网工具** —— 那是安全姿态变更,不是特性。
  *    ⇒ 语义定稿前,任何新的开启通道**默认 OFF**;开启必须是部署方的显式动作。
  *
- * ④ **探活 verb 缺席**。core 2.10 起导出 `probeSearchBackend(search, {timeoutMs}) →
+ * ④ ~~**探活 verb 缺席**~~ —— ✅ **已还(2026-08-01)**:`shouldProbeWebSearchOnBoot` 门控 +
+ *    `main.ts` 消费 core 的 `probeSearchBackend`。**默认 OFF**(开着=给每个既有部署的每次启动凭空
+ *    加一次出网)、**只认明确真值**(含糊值当没开,别替部署方猜)、**失败只 warn 不拒启**(功能型
+ *    能力缺席 ⇒ 降级)、**不 await**(拖住 boot 就把可选工具变成启动依赖)。以下为原始立案文本,留档:
+ *    core 2.10 起导出 `probeSearchBackend(search, {timeoutMs}) →
  *    {ok:true,results:n} | {ok:false,error}`,正好填这条:部署方现在只能靠「跑一个真任务」
  *    验证搜索配对不对。挂哪儿(boot 期一次性 warn / `/health` 子字段 / 显式端点)未定 ——
  *    注意 boot 期探活会给每次启动加一次出网,多租/离线部署要能关。
  */
+import { createSearxngSearchBackend } from "@sema-agent/core";
 const DEFAULT_MAX_RESULTS = 10;
 const DEFAULT_TIMEOUT_MS = 10_000;
 const BRAVE_BASE = "https://api.search.brave.com/res/v1/web/search";
@@ -130,17 +139,45 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
     const data = (await res.json());
     return normalize(data.results, (r) => ({ title: r.title, url: r.url, snippet: r.content }), max, "tavily");
 }
-async function searxngSearch(fetchImpl, cfg, query, max, signal) {
+/**
+ * SearXNG 腿 —— **消费 core 的 `createSearxngSearchBackend`,不再自铸**(#81② 还债;[2190] 表态、
+ * [2229] 裁定 searxng 是国内可达性主路线之后该还的那笔)。
+ *
+ * core 的 adapter 比本文件此前的手写实现多三样,换过来就白得:
+ *   · `allowedDomains` **原生下推**成 `site:a OR site:b` 前缀(此前本腿完全忽略 opts —— core 工具层
+ *     有结果侧 FLOOR 兜底所以不是正确性缺口,但白搜一趟、白花配额,极端情况下限域搜索回 0 条);
+ *   · `extraParams`(实例特定的 `engines=` / `language=` 等)——一键装 SearXNG 的向导要用;
+ *   · **自带 timeout**(`AbortSignal.any([signal, timeout])`;此前本腿只吃外部 signal)。
+ *
+ * ⚠️ core adapter **不管**这三样,必须留在外层(换真源最容易丢的就是它们,已上红先钉):
+ *   ① `maxResults` 截断 ② 统一形状 `{title,url,snippet}` ③ 坏 payload 观测器。
+ */
+async function searxngSearch(fetchImpl, cfg, query, max, signal, opts) {
     if (!cfg.endpoint)
         throw new Error("WEB_SEARCH_ENDPOINT (the SearXNG instance URL) is required for the searxng provider");
-    const url = new URL("/search", cfg.endpoint); // endpoint is the deployment-configured instance base (trusted, not model-controlled)
-    url.searchParams.set("q", query);
-    url.searchParams.set("format", "json");
-    const res = await fetchImpl(url, { headers: { Accept: "application/json" }, signal }); // SearXNG needs no auth
-    if (!res.ok)
-        throw new Error(`searxng search failed (${res.status}): ${await errorText(res)}`);
-    const data = (await res.json());
-    return normalize(data.results, (r) => ({ title: r.title, url: r.url, snippet: r.content }), max, "searxng");
+    const search = createSearxngSearchBackend(cfg.endpoint, {
+        fetchImpl,
+        ...(cfg.searxngParams ? { extraParams: cfg.searxngParams } : {}),
+    });
+    let rows;
+    try {
+        rows = await search(query, signal, opts);
+    }
+    catch (e) {
+        // core 对「results 不是数组」抛具名错;本腿的既有契约是**不抛给上层、走观测器**(review LOW:
+        // 畸形 payload 不该变成裸 TypeError 上抛)。保持既有契约,把它翻译回观测器 + 空结果。
+        const msg = e instanceof Error ? e.message : String(e);
+        if (/no results array/i.test(msg)) {
+            try {
+                onBadPayload?.("searxng");
+            }
+            catch { /* observability never breaks search */ }
+            return [];
+        }
+        throw e;
+    }
+    // core 已回 `{title,url,snippet}` 形;仍过一遍 normalize —— ① 截断 ② 形状兜底 ③ 观测器同源。
+    return normalize(rows, (r) => ({ title: r.title, url: r.url, snippet: r.snippet }), max, "searxng");
 }
 /**
  * Build the `WebSearchConfig` (a `search` fn + `maxResults`) for `assembleFullBodyTools({ webSearch })`. The API key
@@ -159,7 +196,7 @@ export function createWebSearchBackend(cfg) {
             switch (cfg.provider) {
                 case "brave": return await braveSearch(fetchImpl, cfg, q, maxResults, sig);
                 case "tavily": return await tavilySearch(fetchImpl, cfg, q, maxResults, sig, opts);
-                case "searxng": return await searxngSearch(fetchImpl, cfg, q, maxResults, sig);
+                case "searxng": return await searxngSearch(fetchImpl, cfg, q, maxResults, sig, opts);
             }
         }
         finally {
@@ -168,6 +205,20 @@ export function createWebSearchBackend(cfg) {
     };
     return { search, maxResults };
 }
+/**
+ * #81④ 探活门控 —— **默认 OFF**,显式开才探。
+ *
+ * 为什么默认 OFF:探活是一次**真出网**。开着就等于给每个既有部署的每次启动凭空加一次外呼 ——
+ * 多租/离线部署不能被这样动。这与 #81③「任何新的开启通道默认 OFF」同源:
+ * 一个只配了模型 key 的部署,不该因为升级而多出网络行为。
+ *
+ * 为什么只认明确真值:`"yes"`/`"on"` 这类**含糊值当没开**。含糊值上放行 = 替部署方猜意图,
+ * 而猜错的方向是「凭空出网」。缺席要缺席得干净,含糊也一样。
+ */
+export function shouldProbeWebSearchOnBoot(env = process.env) {
+    const raw = env.WEB_SEARCH_PROBE_ON_BOOT?.trim().toLowerCase();
+    return raw === "true" || raw === "1";
+}
 /** Parse the deployment env into a backend config; `undefined` when no provider is set (⇒ WebSearch not assembled). */
 export function webSearchConfigFromEnv(env = process.env) {
     const provider = env.WEB_SEARCH_PROVIDER?.trim().toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.17.0",
+  "version": "3.19.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",