@sema-agent/server 3.18.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

@@ -41,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 期探活会给每次启动加一次出网,多租/离线部署要能关。
@@ -86,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

@@ -41,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 期探活会给每次启动加一次出网,多租/离线部署要能关。
@@ -201,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.18.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",