@sema-agent/server 3.11.0 → 3.12.0

package/USAGE.md

@@ -67,6 +67,24 @@ ANTHROPIC_MAX_RETRIES=10             # 云 Anthropic 腿
 - 断路器**只在配了 `MODEL_GATEWAY_FALLBACK_URLS`(≥2 路)时才有意义**——它的价值是"开路即快速失败 → failover 立刻切备";单网关下它是 no-op(启动日志 `circuitBreakerNoop` 会提示)。只 `network/server/rate_limit` 计入连败,`auth`/`invalid_request` 不计(坏 key 熔断整网关无意义)。备用网关(最后一路)不套断路器。
 - **重试上限**(2026-07-31):两个键**不设就不传给引擎** —— 引擎默认当家。以前这里是 server 侧硬编码 `2`(openai 腿甚至零配置出口),而**显式传参压过引擎默认**,于是引擎抬默认对 server 部署毫无效果;第三方限流 provider 下"重试两次就放弃"正是由此而来。现在:不设=继承引擎默认(抬默认那天自动跟上),设了=按设的走。钉在 `test/brain.test.ts` 的「网关腿重试次数」两条上。
 - 断路器状态:配了 `SESSION_BACKEND=tidb` 时自动用**跨副本共享态**(TiDB `circuit_breaker` 表,写穿+刷新最终一致),否则进程内 Map。启动日志 `breakerState` 字段回显 `shared(tidb)`/`in-process`/`off`。详见 `design/27`。
+
+**可选 — WebSearch 后端(core 只留注入口,不自带任何 provider)**
+```bash
+WEB_SEARCH_PROVIDER=brave|tavily|searxng   # 缺席 = 不装配(WebSearch 工具根本不挂,不是挂了报错)
+WEB_SEARCH_API_KEY=…                       # brave/tavily 必填;只进 backend 闭包,永不进模型 prompt 或工具参数
+WEB_SEARCH_ENDPOINT=https://searx.example  # searxng 必填;brave/tavily 下是可选的 base-URL 覆盖(代理/测试)
+WEB_SEARCH_MAX_RESULTS=10                  # 1..20,返给模型的条数上限
+WEB_SEARCH_TIMEOUT_MS=10000                # 单次搜索墙钟
+```
+- 结果是**不可信输入**:core 会 `delimitUntrusted` 围栏并**重新施加** `allowed_domains`/`blocked_domains`
+  地板,所以 backend 遵不遵守 `opts` 是优化不是正确性要求 —— 换 provider(包括换成自建 SearXNG)
+  不会削弱域名地板。
+- 🔴 **`WEB_SEARCH_ENDPOINT` 的语义是「引擎可达的地址」,不是「用户机器上可达的地址」**
+  (2026-07-31 与 cli 对齐的跨机契约句):壳(TUI/桌面/web)与引擎**可以不在同一台机器**。壳在用户
+  笔记本上起的 localhost SearXNG,云端 worker 够不着 —— 所以「本地 SearXNG 兜底」这一档**只适用
+  壳自 spawn 本地引擎的同机形**;壳连接远程引擎时该档整级跳过,由运维在**引擎侧**配 `WEB_SEARCH_*`。
+  用户手填一个集中式 SearXNG 地址是合法形,照常放行。
+
 - **大工具结果落盘**(core 1.47/1.49):单条工具结果 > ~20000 字符时 core 把全文移出上下文、只留预览+ref,模型用 `read_tool_result` 按需分页回取。配了 TiDB 时自动用**durable `tool_result` 表**(跨副本 wake 仍能取回全文;否则 core 进程内默认 = 跨副本 wake 取不到→降级到预览,不崩)。`TOOL_RESULT_TTL_SEC`(默认 86400)按 TTL 回收(要 ≥ run 可恢复期)。启动日志 `toolResultStore` 回显 `shared(tidb)`/`in-process`。
 
 **可选 — 成本计量 + 预算闸（core 1.37）**

package/dist/approval.d.ts

@@ -9,6 +9,26 @@
  */
 import { type ToolPolicy } from "@sema-agent/core";
 import type { ApprovalStore } from "./plugins/store-backend.js";
+/**
+ * 运维**是否表达了门意图** —— boot 的单用户 allow-all 基线只在"零门意图"时才允许铺开,
+ * 所以这个谓词漏一格 = 那一格的意图被 allow-all 静默吞掉。
+ *
+ * 🔴 由来(2026-07-31 缝合审):这判据本来是 `main.ts` 里的一行内联表达式,只枚举了
+ * requireApproval / deny / durableApproval **三格**,漏了 `approvalNeverAuto`。漏的根因不是手滑,
+ * 是 `config-types.ts` 当时把 neverAuto 描述成 "Subset of approvalRequire" —— 若真是子集,
+ * 枚举 requireApproval 就覆盖了它。但本文件 inv#2 的执行面逐字相反(neverAuto ⊄ requireApproval),
+ * 于是「单用户 + 只配 APPROVAL_NEVER_AUTO=Bash」这一**语义完全合理**的形被判成零门意图 ⇒
+ * 落进 `createAllowDenyPolicy({})` 全面放行 ⇒ 那张"永远问人"的表从未进入任何 policy,Bash 直接跑。
+ *
+ * 判定挪到**与 inv#2 同一个文件**就是为了这个:两者再想漂开,得有人同时改这两段。
+ * 新增任何"门意图"配置项时,这里必须同步加一格(下面的表驱动测试会点名漏的那格)。
+ */
+export declare function hasOperatorGateIntent(config: {
+    approvalRequire: readonly string[];
+    approvalDeny: readonly string[];
+    approvalNeverAuto: readonly string[];
+    durableApproval: boolean;
+}): boolean;
 /**
  * Durable approval policy (core 1.67 / design/45): returns three-state **`ask`** for gated tools instead of
  * polling. With `TaskSpec.durableApproval` set + a `checkpointStore` on the Runner, core turns that `ask` into

package/dist/approval.js

@@ -8,6 +8,26 @@
  * dropped at the task deadline instead of holding the worker — design/06 F4 self-protection.
  */
 import { createApprovalPolicy, canonicalToolName, uuidv7 } from "@sema-agent/core";
+/**
+ * 运维**是否表达了门意图** —— boot 的单用户 allow-all 基线只在"零门意图"时才允许铺开,
+ * 所以这个谓词漏一格 = 那一格的意图被 allow-all 静默吞掉。
+ *
+ * 🔴 由来(2026-07-31 缝合审):这判据本来是 `main.ts` 里的一行内联表达式,只枚举了
+ * requireApproval / deny / durableApproval **三格**,漏了 `approvalNeverAuto`。漏的根因不是手滑,
+ * 是 `config-types.ts` 当时把 neverAuto 描述成 "Subset of approvalRequire" —— 若真是子集,
+ * 枚举 requireApproval 就覆盖了它。但本文件 inv#2 的执行面逐字相反(neverAuto ⊄ requireApproval),
+ * 于是「单用户 + 只配 APPROVAL_NEVER_AUTO=Bash」这一**语义完全合理**的形被判成零门意图 ⇒
+ * 落进 `createAllowDenyPolicy({})` 全面放行 ⇒ 那张"永远问人"的表从未进入任何 policy,Bash 直接跑。
+ *
+ * 判定挪到**与 inv#2 同一个文件**就是为了这个:两者再想漂开,得有人同时改这两段。
+ * 新增任何"门意图"配置项时,这里必须同步加一格(下面的表驱动测试会点名漏的那格)。
+ */
+export function hasOperatorGateIntent(config) {
+    return (config.approvalRequire.length > 0 ||
+        config.approvalDeny.length > 0 ||
+        config.approvalNeverAuto.length > 0 || // ← 漏了这格,见上面的由来
+        config.durableApproval);
+}
 /**
  * Durable approval policy (core 1.67 / design/45): returns three-state **`ask`** for gated tools instead of
  * polling. With `TaskSpec.durableApproval` set + a `checkpointStore` on the Runner, core turns that `ask` into

package/dist/config-types.d.ts

@@ -493,9 +493,17 @@ export interface ServiceConfigFlat {
      *  asks, the human only sees the rest". `APPROVAL_AUTO_BUDGET`. */
     approvalAutoBudget: number;
     /** design/80 D-E (inv#2 — safety asks are never budgetable): gated tools that ALWAYS require a human even when
-     *  the auto-budget is on — the "irreversible / never auto-approve" set. Subset of approvalRequire; empty = the
-     *  budget may auto-approve any required tool. (In-service every gated ask is gate.kind="human", so this set is
-     *  the ONLY way to keep an irreversible tool human-gated under an auto-budget.) `APPROVAL_NEVER_AUTO`. */
+     *  the auto-budget is on — the "irreversible / never auto-approve" set. empty = the budget may auto-approve any
+     *  required tool. (In-service every gated ask is gate.kind="human", so this set is the ONLY way to keep an
+     *  irreversible tool human-gated under an auto-budget.) `APPROVAL_NEVER_AUTO`.
+     *
+     *  🔴 **NOT required to be a subset of `approvalRequire`**(2026-07-31 修口)。这里原来写的是
+     *  "Subset of approvalRequire",而 `approval.ts` 的 inv#2 执行面逐字相反:
+     *  「even if it was not also listed in requireApproval — the footgun: neverAuto ⊄ requireApproval」。
+     *  两处文档互相矛盾**不是文字问题**:`main.ts` 的 `operatorGateIntent` 是照着"子集"那句写的
+     *  ——若真是子集,枚举 `approvalRequire.length > 0` 就覆盖了它,漏掉看着无害。实际不是子集,于是
+     *  「只配 APPROVAL_NEVER_AUTO」这一形被判成"零门意图" ⇒ 落进单用户 allow-all 基线 ⇒ 那张表
+     *  从未进入任何 policy。判定现在单源在 `hasOperatorGateIntent()`(与 inv#2 同文件)。 */
     approvalNeverAuto: string[];
     /** design/80 D-G (HMAC = integrity, not identity; ✅ WIRED — the "SCAFFOLD, not yet wired" note here was STALE,
      *  corrected 2026-07-25: consumed by `verifyDirectDoorProof` → `verifyApprovalHmac`, reached from the live decide

package/dist/main.js

@@ -14,7 +14,7 @@ import { ensureChildSessionDurableWithPromotion } from "./plugins/session-store.
 import { ForkRoutingSessionStore } from "./plugins/fork-routing-session-store.js";
 import { webSearchConfigFromEnv, createWebSearchBackend, setWebSearchBadPayloadObserver } from "./plugins/web-search.js";
 import { createAuthorizer } from "./security.js";
-import { createDurableAskPolicy } from "./approval.js";
+import { createDurableAskPolicy, hasOperatorGateIntent } from "./approval.js";
 import { loadSkills } from "./capabilities/skills.js";
 import { GiteaClient } from "./capabilities/repo-tools.js";
 import { buildScenarios, builtinScenarioDetails } from "./capabilities/scenarios.js";
@@ -30,6 +30,7 @@ import { performMemorySync } from "./memory-sync.js";
 import { startOtlpExporter } from "./observability/otel-exporter.js";
 import { HEARTBEAT_MS, backgroundAgentOutput, taskHandleOutput, taskHandleStop } from "./runs.js";
 import { SQL_BLOB_DEFAULT_MAX_BYTES } from "./plugins/blob-backend.js";
+import { counterStoreLabel } from "./plugins/store-backend.js";
 import { composeHooks } from "./hooks/hook-runner.js";
 import { createHookLlm } from "./hooks/hook-llm.js";
 import { startFleetClientFromEnv } from "./fleet-client.js";
@@ -367,7 +368,8 @@ async function main() {
     // backing store is wired (e.g. DB_BACKEND=local → no approvalStore/checkpointStore ⇒ approvalEnabled/durableEnabled
     // false), that is a MISCONFIG — do NOT mask it with allow-all; leave toolPolicy undefined so core's UNGATED warning
     // still surfaces it. So the baseline needs single-user turnkey ∧ zero expressed gate intent.
-    const operatorGateIntent = config.approvalRequire.length > 0 || config.approvalDeny.length > 0 || config.durableApproval;
+    // 单源在 approval.ts(与 inv#2 同文件)—— 这里原是内联的三格枚举,漏了 approvalNeverAuto,详见该函数顶注。
+    const operatorGateIntent = hasOperatorGateIntent(config);
     const singleUserAutoAcceptBaseline = config.requirePrincipal !== true && !operatorGateIntent;
     // design/45 durable-checkpoint (core 1.67): opt-in (DURABLE_APPROVAL + a pool). When on, F4 uses durable
     // suspend/resume instead of the poll gate — a gated `ask` suspends the task (status:"suspended" + checkpoint)
@@ -869,9 +871,9 @@ async function main() {
         memory: memoryEngine ? `engine(${memoryEngine.root})` : "off",
         instanceId,
         rateLimitPerMin: config.rateLimitPerMin,
-        rateLimit: config.rateLimitPerMin > 0 ? (backend ? `shared()` : "in-process") : "off",
+        rateLimit: config.rateLimitPerMin > 0 ? counterStoreLabel(backend?.rateLimiter, backend?.kind) : "off",
         maxPrincipalCostUsd: config.maxPrincipalCostUsd || null,
-        costQuota: config.maxPrincipalCostUsd > 0 ? (backend ? `shared()` : "in-process") : "off",
+        costQuota: config.maxPrincipalCostUsd > 0 ? counterStoreLabel(backend?.costQuota, backend?.kind) : "off",
         // durable offload store for large tool results (cross-replica wake); else core's in-process default
         toolResultStore: toolResultStore ? (backend?.kind === "local" ? "file(local)" : "shared(sql)") : "in-process",
         otel: config.otel ? config.otel.endpoint : null,

package/dist/plugins/store-backend.d.ts

@@ -186,6 +186,19 @@ export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "l
  *  field the 20G-workspace case needed; more knobs when a case shows up. Exported for tests
  *  (fractional-MB rounding + partial-merge semantics need a regression lock). */
 export declare function snapshotBoundsFromConfig(config: ServiceConfig): FileSnapshotBounds;
+/**
+ * 启动日志里「跨副本 or 进程内」那一格的标签。
+ *
+ * 🔴 判据必须是**那个 store 本身在不在**,不是「有没有 backend」(2026-07-31 缝合审)。
+ * `LocalBackend` 明确省略 `costQuota`/`rateLimiter`(见它类尾那行 "intentionally absent"),
+ * 而 `DB_BACKEND=local` 是**裸 boot 的默认值** —— 原来 main.ts 那两行用 `backend ? "shared()" : …` 判,
+ * 于是单机默认形配了 `RATE_LIMIT_PER_MIN` 会打出 `shared()`,实际跑的是每副本一份的进程内限流器。
+ * 运维扩到 N 副本时读这行判定"限流是跨副本的",真实额度是 N 倍。
+ * (同一个说谎病族在紧邻的 `breakerState` 上修过一次——"was hard-coded 'shared(tidb)' — lied under
+ * DB_BACKEND=pg"——`session:` 也跟着修了,这两行没跟上。顺带:原来的 `shared()` 括号是空的,
+ * 而兄弟行都写 `shared(${kind})`。)
+ */
+export declare function counterStoreLabel(store: unknown, kind: string | undefined): string;
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
  *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
 export declare function createStoreBackend(config: ServiceConfig): StoreBackend | undefined;

package/dist/plugins/store-backend.js

@@ -276,6 +276,21 @@ class LocalBackend {
     mysqlPool() { return undefined; }
     pgPool() { return undefined; }
 }
+/**
+ * 启动日志里「跨副本 or 进程内」那一格的标签。
+ *
+ * 🔴 判据必须是**那个 store 本身在不在**,不是「有没有 backend」(2026-07-31 缝合审)。
+ * `LocalBackend` 明确省略 `costQuota`/`rateLimiter`(见它类尾那行 "intentionally absent"),
+ * 而 `DB_BACKEND=local` 是**裸 boot 的默认值** —— 原来 main.ts 那两行用 `backend ? "shared()" : …` 判,
+ * 于是单机默认形配了 `RATE_LIMIT_PER_MIN` 会打出 `shared()`,实际跑的是每副本一份的进程内限流器。
+ * 运维扩到 N 副本时读这行判定"限流是跨副本的",真实额度是 N 倍。
+ * (同一个说谎病族在紧邻的 `breakerState` 上修过一次——"was hard-coded 'shared(tidb)' — lied under
+ * DB_BACKEND=pg"——`session:` 也跟着修了,这两行没跟上。顺带:原来的 `shared()` 括号是空的,
+ * 而兄弟行都写 `shared(${kind})`。)
+ */
+export function counterStoreLabel(store, kind) {
+    return store ? `shared(${kind ?? "unknown"})` : "in-process";
+}
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
  *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
 export function createStoreBackend(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.11.0",
+  "version": "3.12.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",