feat(agent): web.search / web.fetch via Brave Search (WEB-1)

- adapters/websearch: Brave client (X-Subscription-Token, error classes),
  result normalization with redaction/truncation, SSRF guard, HTML→text fetch
  (10s, 512KB, text/html|text/plain only)
- modules/websearch: 10-min PG cache (region websearch), cross-process
  per-minute limit, web.fetch allowlist = URLs from the caller's latest
  web.search; POST /websearch/test
- settings.agent.webSearch (key write-only → secret_ref); settings card
  under Agent; web.* offered to the model only when enabled, plus a system
  prompt rule; outputs marked untrusted
- capability count 27 → 29; e2e E13; runbook docs/runbook/websearch.md

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/contracts/src/api.ts

@@ -4,6 +4,7 @@ import * as assets from "./assets.ts";
 import * as auth from "./auth.ts";
 import * as browser from "./browser.ts";
 import * as cache from "./cache.ts";
+import { WebSearchTestInput, WebSearchTestResult } from "./capabilities-io.ts";
 import { CapabilityDescriptor, KnownCapabilityId } from "./capability.ts";
 import { type ApiScope, CursorQuery, cursorPage, HealthStatus, Id, IdParam } from "./common.ts";
 import * as content from "./content.ts";
@@ -1645,6 +1646,18 @@ export const Api = {
     }),
   },
 
+  // ── 网页搜索(WEB-1,docs/runbook/websearch.md) ──
+  websearch: {
+    test: ep({
+      method: "post",
+      path: "/websearch/test",
+      scope: "admin",
+      summary: "用已保存的搜索服务 Key 实际查询一次（不走缓存，计入每分钟上限）",
+      body: WebSearchTestInput,
+      response: WebSearchTestResult,
+    }),
+  },
+
   // ── 设置 ──
   settings: {
     get: ep({ method: "get", path: "/settings", scope: "read", summary: "全局设置", response: GlobalSettings }),