@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/tool-result-store-sql.js

@@ -1,50 +1,8 @@
-/**
- * Durable backing store for offloaded large tool results (core 1.47 offload / 1.49 durable contract) —
- * SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical
- * `TiDBToolResultStore` / `PgToolResultStore` class names survive as thin ctor subclasses so every consumer
- * (store-backend.ts, the fake-pool unit suites, the real-DB integration suites) is untouched.
- *
- * Mirrors core's reference `TiDbToolResultStore` adapter. Without this, the Runner defaults to a
- * task-scoped in-memory store: an async run that wakes on ANOTHER replica can't `read_tool_result` an
- * offloaded result (the ref misses → the model is told it's unavailable; the preview still stands, so it
- * degrades, never crashes). A durable store survives wake/resume across the stateless fleet.
- *
- * core namespaces the ref as `tr_<sessionId>~<toolCallId>~<contentCoordinate>` (1.49, re-minted injectively in
- * 5.26.0 #119 — `~`-separated, four segments max, content-addressed) → globally unique → usable directly as
- * the PRIMARY KEY (no composite key needed). `put` is write-once (idempotent on replay/retry: a retry is
- * a NEW toolCallId → new ref, so a given ref never changes content). Retention is anchored to a run's
- * RECOVERABLE window via TTL (`reapOlderThan`): a resumable run may re-fetch an old ref after wake, but a
- * completed run only needs the preview for audit/replay — so a TTL comfortably exceeding the run lifetime
- * bounds storage without losing recoverable full-text.
- *
- * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
- *   - `?` placeholders vs `$n`
- *   - write-once insert = `INSERT IGNORE` vs `INSERT ... ON CONFLICT (ref) DO NOTHING`
- *   - affectedRows vs rowCount (via SqlDriver)
- *   - `SUBSTRING(content, ?, ?)` (1-indexed, comma form) vs the ANSI `SUBSTRING(content FROM $n::int FOR
- *     $m::int)` positional form WITH explicit `::int` casts — node-pg binds bare params as text, and
- *     `SUBSTRING(s FROM <text>)` is the POSIX-REGEX overload (it would treat $1 as a pattern); the cast
- *     forces the positional integer overload. `CHAR_LENGTH` is ANSI and shared.
- *   - content column: TiDB LONGTEXT vs PG TEXT (PG has no LONGTEXT; TEXT is unbounded), DATETIME(3) vs
- *     TIMESTAMPTZ(3) — schema only (TiDB DDL in tidb-pool.ts; PG DDL self-contained below, exported for the
- *     integration test + pg-pool.ts's central apply).
- *   - `put`'s UTF-16 sanitize is a GENUINE algorithm divergence, not just SQL text — see the dialect branch
- *     inline for why.
- *   - (历史条目,已随码消失)ESCAPE-clause literal:`deleteBySession` 曾按 ref 前缀 LIKE 选行,两方言因此
- *     各自显式声明转义符。重扫二轮起该腿改为**只按 `owner_session_id` 出处选行**(core 契约:ref 是
- *     opaque handle,禁解析),本文件已无 LIKE,这条方言差随之退役 —— 留档以防有人「照旧例」把前缀
- *     选行请回来。
- */
 import { MAX_MINTED_TOOL_RESULT_REF_CHARS, assertSafeToolResultRef, assertToolResultProvenanceMatch, normalizeToolResultProvenance } from "@sema-agent/core";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
-/** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
- *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
- *  tables, so a self-contained ensureSchema is safe (central pg-pool aggregation is done separately). */
 export const PG_TOOL_RESULT_SCHEMA = [
-    // #119(core 5.26.0):宽度与出处两列与 TiDB 双生逐字对齐 —— 理由写在 tidb-pool.ts 的同一张 DDL 上
-    // (`MAX_MINTED_TOOL_RESULT_REF_CHARS` = 518;截断主键 = 两枚 ref 折成一行 = 身份故障)。
     `CREATE TABLE IF NOT EXISTS tool_result (
      ref              VARCHAR(518) COLLATE "C" NOT NULL,
      content          TEXT COLLATE "C"         NOT NULL,
@@ -55,33 +13,15 @@ export const PG_TOOL_RESULT_SCHEMA = [
    )`,
     `CREATE INDEX IF NOT EXISTS idx_tool_result_created ON tool_result (created_at)`,
 ];
-/** Idempotent schema apply for the tool_result table (for the integration test to call). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_TOOL_RESULT_SCHEMA)
         await pool.query(stmt);
 }
-/**
- * #119 升级前置断言 —— **拒启**,不是 warn(codex 复审 [high],已核真)。
- *
- * 病:本仓不发 `ALTER TABLE` 迁移(标准裁定:改列就改 CREATE + 删库重建)。于是一台**没删表**就升上来的
- * 部署,`CREATE TABLE IF NOT EXISTS` 对它是空操作,旧表既没有出处两列也只有 `VARCHAR(190)` 的 ref 列。
- * 那样跑起来的后果不是「少个功能」:每一次 offload 写都会撞 unknown column 报错,而 core 的 offload
- * 失败臂会把错误吞成一条内联占位("[offload LOST at write time…]")—— 服务照跑,工具产物全丢,日志里只有
- * 一句看不出根因的话。这正是「响亮或 fail-closed,禁静默降级」那条要挡的形态。
- *
- * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
- * 探不通即拒启,错误文案直接给出两条方言的动作(删表重建),不让运维去猜。
- */
 export async function assertToolResultProvenanceSchema(query, dialect) {
-    // ② 键宽(codex 复审 round2 [high],已核真):只探两列会放过「有出处列、但 ref 仍是 VARCHAR(190)」的
-    // 半迁移表 —— 而这道断言的文案与 CHANGELOG 都在宣称它护着加宽后的键。截断的主键把两枚不同的 ref 折成
-    // 同一行 = 身份故障,正是本次升级要消灭的东西,所以宽度必须**真查**,不能靠「列在 ⇒ 表是新的」推断。
     const widthRow = await query(dialect === "tidb"
         ? "SELECT CHARACTER_MAXIMUM_LENGTH AS len FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'tool_result' AND column_name = 'ref'"
         : "SELECT character_maximum_length AS len FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = 'tool_result' AND column_name = 'ref'").catch(() => ({ rows: [] }));
     const width = Number(widthRow.rows[0]?.len ?? NaN);
-    // 查不到宽度(权限受限的 information_schema / 意外的列类型)⇒ **不**据此拒启:那是「没看见」,不是
-    // 「看见了不合格」。看见了才判,判就判死。
     if (Number.isFinite(width) && width < MAX_MINTED_TOOL_RESULT_REF_CHARS) {
         throw new Error(`tool_result.ref is VARCHAR(${width}) but core 5.26.0 mints refs up to ${MAX_MINTED_TOOL_RESULT_REF_CHARS} characters ` +
             `(#119 made the ref injective: four \`~\`-separated segments). A truncating primary key aliases two distinct refs onto ` +
@@ -103,30 +43,16 @@ export async function assertToolResultProvenanceSchema(query, dialect) {
             `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-/** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export class SqlToolResultStore {
     db;
-    /** #270 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而三方法的实现体在 `retention-store-sql.ts`」
-     *  逐字见 {@link MANAGED_RETENTION}(本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
     retention = MANAGED_RETENTION;
     constructor(db) {
         this.db = db;
     }
-    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    /** D1(试剂盒揪出,RB-266 语义):ref 是主键,而 `deleteBySession` 只认**记录下来的出处**与单射的
-     *  `tr_<sid>~` 前缀(重扫二轮起;旧注写的 `tr_<sid>_%` 前缀清理已作废,理由见该方法顶注)——
-     *  不合规 ref 的行既进不来、也就谈不上被 session 删除清掉,只能等 TTL。
-     *
-     *  🔴 判定**单源**:直调 core 的 `assertSafeToolResultRef`(core 2.8.0 起入公共面)。
-     *  在此之前这里是那 6 个判别条件的**本地镜像** —— 我在 [2159] 主动交出过这条裂缝:镜像是第二真源,
-     *  core 哪天收紧一格(加 Windows 保留名、长度上限……)我方不会跟着动,而**试剂盒会继续绿**
-     *  (它测的是「拒不拒」,不是「按同一张表拒」)。core 按请求追加了导出,镜像随之删除,裂缝闭合。
-     *  抛错文案与 core 逐字相同,所以 wire 与既有钉都不变。 */
     isUnsafeRef(ref) {
-        // core 只给 assert 形(它就是判定本体);读面要的是谓词,由同一个 assert 派生 —— 仍是单源。
         try {
             assertSafeToolResultRef(ref);
             return false;
@@ -138,49 +64,17 @@ export class SqlToolResultStore {
     assertSafeRef(ref) {
         assertSafeToolResultRef(ref);
     }
-    /**
-     * #119(core 5.26.0)—— 出处的**写面**。语义一律取 core 单源(`assertToolResultProvenanceMatch`),
-     * 本方法只负责把它落到 SQL 上:
-     *  · **写一次选举同时定属主** —— 内容与属主是同一条 INSERT,不存在「内容写进去了属主还没跟上」的窗口
-     *    (core 头注允许 file 双对象后端出现这个窗口,单行后端没有,别自造);
-     *  · 抢输的那一方(IGNORE / DO NOTHING ⇒ affected=0)回读已存属主再判:同属主(或本次无出处)=
-     *    幂等空转;异属主 = `ToolResultRefConflictError` typed 拒。**绝不静默 keep-first**:ref 是主键,
-     *    静默空转会让第二位写者拿着自己的 ref 读回第一位的字节;
-     *  · 无出处的行永久 unowned —— 后续带出处的 put 不回填(没有证据的收养),`ownerOf` 继续答 undefined。
-     */
     async put(ref, content, provenance) {
         this.assertSafeRef(ref);
-        // Sanitize invalid UTF-16 (lone/half surrogates — a JS string CAN hold them, e.g. a binary-ish tool
-        // output) to U+FFFD so the column accepts the FULL value via a Buffer utf8 round-trip (valid content is
-        // unchanged). Shared by both dialects.
         let safe = Buffer.from(content, "utf8").toString("utf8");
-        // 🔴 Genuine algorithm divergence (not just SQL text): TiDB's `INSERT IGNORE` downgrades an invalid-byte
-        // rejection to a warning + SILENT TRUNCATION (the utf8 round-trip above is enough — TiDB never sees a NUL
-        // complaint). PG's `ON CONFLICT DO NOTHING` does NOT paper over an encoding error — it errors — and node-pg's
-        // TEXT columns additionally reject a bare NUL (u0000) that a lone-surrogate round-trip alone does NOT strip
-        // (codex H4). `pgSanitizeText` double-scans (NUL + lone surrogate → U+FFFD) so PG never sees either. Never
-        // "unify" onto one engine's sanitize: TiDB doesn't need the NUL scan, and skipping it on PG reintroduces 22P05.
         if (this.db.dialect === "pg")
             safe = pgSanitizeText(safe);
-        // write-once / keep-first: a replay re-puts the SAME ref+content → IGNORE / DO NOTHING keeps the original row.
         const owner = provenance !== undefined ? normalizeToolResultProvenance(provenance) : undefined;
         const insert = async () => (await this.db.query(this.q("INSERT IGNORE INTO tool_result (ref, content, owner_session_id, owner_task_id, created_at) VALUES (?,?,?,?,?)", "INSERT INTO tool_result (ref, content, owner_session_id, owner_task_id, created_at) VALUES ($1,$2,$3,$4,$5) ON CONFLICT (ref) DO NOTHING"), [ref, safe, owner?.sessionId ?? null, owner?.taskId ?? null, new Date()])).affected;
-        // 🔴 codex 复审(medium,已核真)——**抢输之后那一行可能已经不在了**。选举(INSERT)与观察(SELECT)
-        // 是两条语句,中间可以插进 TTL reap 或 §0.5 会话清除。那时 `readOwner` 回 `absent`,而 core 的比较器
-        // 对「缺一侧」是**不下判决**的(设计如此:无出处的行不许被收养)—— 于是 put 会**成功返回**,而库里
-        // 既没有内容也没有属主,调用方拿着一枚当场读不出来的 ref。
-        //
-        // 🔴 处置是**抛**,不是重投(codex 复审两轮的合取解;第一版写的重投被第二轮当场驳回,理由成立):
-        // 重投会让**删除输**。§0.5 会话清除 DELETE 掉这一行之后,一次重投就把它原地复活 —— 而 core 的部分
-        // offload 写点是不 await 的,能活过 active-run 围栏,于是被删会话的产物重新落库、留到 TTL 才消失,
-        // 直接违背 E21 的删除权保证。「少存一份可恢复窗口内的缓存」与「删了又回来」不是同一个量级的代价。
-        // 抛出去会走到 core 的 offload 失败臂 —— 它把这次卸载记成 "[offload LOST at write time: …]" 并保住
-        // 内联预览,模型看到的是实话。
         if ((await insert()) > 0)
-            return; // 本次赢下选举:内容与属主同一条语句落地
+            return;
         const stored = await this.readOwner(ref);
         if (stored.present) {
-            // 抢输(或纯重放):属主判定归 core 的单源比较器 —— 「同属主」在两个 store 里不许有两种含义。
             assertToolResultProvenanceMatch(ref, stored.owner, owner);
             return;
         }
@@ -188,121 +82,52 @@ export class SqlToolResultStore {
             `(a concurrent TTL reap or session purge deleted it). Nothing was stored — reporting the loss rather than ` +
             `re-inserting (which would resurrect a purged session's content) or returning a ref that reads back empty.`);
     }
-    /** 一次回读同时回答两件事:**行在不在**(reap/purge 窗口的判别位)与**属主是谁**。两件事必须来自同一
-     *  条 SELECT —— 分两次问会重新引入它要消灭的那个窗口。 */
     async readOwner(ref) {
         const { rows } = await this.db.query(this.q("SELECT owner_session_id, owner_task_id FROM tool_result WHERE ref = ?", "SELECT owner_session_id, owner_task_id FROM tool_result WHERE ref = $1"), [ref]);
         const row = rows[0];
         if (!row)
             return { present: false, owner: undefined };
-        // 🔴 缺席的判别位**只有 SQL NULL**(codex 复审 round2 [medium],已核真):曾经写成
-        // `sessionId.length === 0` 也算无属主 —— 那会把一个 `sessionId: ""` 的合法(core 的
-        // `normalizeToolResultProvenance` 不拒空串)出处在往返中悄悄折成 unowned,与内存后端的逐字比较分家;
-        // `taskId: ""` 折成缺席更糟 —— 授权面会从「task 级」放宽成「整条 session」。字符串一律原样还原。
         const sessionId = row.owner_session_id;
         if (typeof sessionId !== "string")
-            return { present: true, owner: undefined }; // NULL 列 = 行在但无属主
+            return { present: true, owner: undefined };
         const taskId = row.owner_task_id;
-        // 键**缺席**而不是 present-as-undefined:core 的比较器把「缺 taskId」与「显式 undefined」当同一个值,
-        // 但调用方(和本仓的 toEqual 钉)看得见键在不在,落库的 NULL 只能还原成缺席形。
         return { present: true, owner: typeof taskId === "string" ? { sessionId, taskId } : { sessionId } };
     }
-    /**
-     * #119 —— 出处的**读面**。未知 ref 与「存了但无属主」两种情况都答 `undefined`:读面对二者一视同仁
-     * (fail-closed,谁都没被授权),所以这里也不必把它们分开报。
-     */
     async ownerOf(ref) {
         if (this.isUnsafeRef(ref))
-            return undefined; // 与 get 同尺:写面拒过的 ref 必不在库,不把驱动层错误漏出去
+            return undefined;
         return (await this.readOwner(ref)).owner;
     }
     async get(ref, opts = {}) {
-        // D1 读面半条(RB-266「the read face degrades instead」):unsafe ref 在读面**降级**返回 undefined
-        // (该 ref 写入面就被拒 ⇒ 必不在库),不把驱动层错误(PG 22021 对 NUL)漏给调用方。
         if (this.isUnsafeRef(ref))
             return undefined;
         const offset = Math.max(0, Math.floor(opts.offset ?? 0));
         const hasLimit = opts.limit !== undefined && Number.isFinite(opts.limit);
         const limit = hasLimit ? Math.max(0, Math.floor(opts.limit)) : 0;
-        // One round-trip: SUBSTRING is 1-indexed (offset+1); CHAR_LENGTH gives the full (character) length for the
-        // slice header. With no limit, return the remainder from `offset`.
         const sql = hasLimit
             ? this.q("SELECT SUBSTRING(content, ?, ?) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = ?", "SELECT SUBSTRING(content FROM $1::int FOR $2::int) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = $3")
             : this.q("SELECT SUBSTRING(content, ?) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = ?", "SELECT SUBSTRING(content FROM $1::int) AS slice, CHAR_LENGTH(content) AS total FROM tool_result WHERE ref = $2");
         const params = hasLimit ? [offset + 1, limit, ref] : [offset + 1, ref];
         const { rows } = await this.db.query(sql, params);
         if (rows.length === 0)
-            return undefined; // unknown ref (e.g. reaped) → core reports "no longer available"
+            return undefined;
         return { content: String(rows[0].slice ?? ""), offset, totalChars: Number(rows[0].total) };
     }
-    /** TTL reap: delete results older than `cutoffMs`. Returns rows removed.
-     *  C6: a real DB error must NOT collapse into the same `0` a legitimate "nothing was old enough" returns —
-     *  those are different facts (query failed vs. query succeeded on an empty set) and folding them together
-     *  makes a stuck/broken reaper indistinguishable from a healthy quiet one. Matches every sibling reaper's
-     *  form (roster-store-sql.ts `reapOlderThan`, checkpoint-store-sql.ts `reapExpired`,
-     *  workflow-journal-store-sql.ts `reapExpired`): let the error propagate — the periodic-sweep call site
-     *  (boot/reapers.ts) already wraps this call in `.catch(() => undefined)` so the reap loop itself never dies. */
     async reapOlderThan(cutoffMs) {
         const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE created_at < ?", "DELETE FROM tool_result WHERE created_at < $1"), [new Date(cutoffMs)]);
         return affected;
     }
-    /**
-     * E21 (§0.5 session delete) — purge offloaded tool results for one session. Selection is by the row's
-     * **recorded provenance** (`owner_session_id`, the #119 column `put` writes in the same statement as the
-     * content) and by NOTHING else — **zero ref-derived arms**(codex R1-[high] 收窄:连单射新前缀也不作
-     * 属主证据,理由在方法体内逐字引 core 顶注)。Returns `{deleted, unattributable}`; why NO prefix
-     * (legacy `_` or injective `~`) is a deletion selector is inline below.
-     *
-     * ⚠️ 旧注两处已作废(重扫二轮更正,留档防复辟):① 「core namespaces every ref as `tr_<sid>_<callId>`」——
-     * 5.26.0 起是 `~` 分隔的单射四段形,`_` 形只剩存量;② 「there is no `session_id` (or `owner`) column to
-     * guard on」—— #119 起**有**(`owner_session_id` / `owner_task_id`,boot 期还有拒启断言把没升级的表挡在
-     * 外面),所以「按出处选行」不再是「awkward ref-correlated EXISTS」,它就是本方法现在的主选择器。
-     *
-     * 路由侧的 owner 门照旧在(DELETE 路由先 `ownerOf` 对属主、同一协调器里先跑 owner-guarded 的 run 账本
-     * 删除),但它不再是唯一防线:LIKE 转义只挡「精心构造的 id 把前缀撑宽」,挡不住「**合法**的邻会话 id
-     * 恰好是本会话 id 的扩展」——那一条现在由出处判定挡。
-     */
     async deleteBySession(sessionId) {
-        // 🔴 **选行只按记录下来的出处,一个 ref 也不解析**(重扫二轮红先修 + codex 复审 R1-[high] 收窄)。
-        // core `tool-result-store.d.ts` 对本操作写死了三条,逐字照做:
-        //  ① 「**selection is by RECORDED PROVENANCE, never by parsing the ref.** A ref is an opaque handle:
-        //     its session segment may be folded, refs minted before the injective form decompose two ways
-        //     (`tr_team_blue_x` is both ("team","blue_x") and ("team_blue","x")), **and a caller may mint its
-        //     own**. Prefix-matching a ref therefore both misses rows and reaches rows of a NEIGHBOURING
-        //     session, and over-deletion here destroys a live session's readable bytes」;
-        //  ② 「**`taskId` is ignored in the match**」——`{sessionId, taskId}` 是同一会话的窄化,不是别的属主;
-        //  ③ 「**an UNOWNED entry is never deleted** … It is counted instead (`unattributable`) so the caller
-        //     learns the deletion was incomplete rather than being told a clean "done"」。
-        //
-        // 旧形拿两条 LIKE 前缀全删,踩的正是 ①:提交面对 session id **只限长、不限形**(`server.ts` 的
-        // "a client MAY supply an ARBITRARY id … LENGTH-ONLY — NOT a uuidv7 shape check"),而 `_` 在 core 的
-        // `NATIVE_REF_CHARSET`(`/^[A-Za-z0-9_.-]+$/`)里 ⇒ 会话 `<uuid>_sub` 合法,它的产物铸出
-        // `tr_<uuid>_sub~c1~s<hash>`;删父会话 `<uuid>`(过得了 DELETE 路由的 uuidv7 门)时旧前缀 LIKE 命中它,
-        // 一条**活着的**邻会话的卸载全文被销毁,还被算进本次的 `deleted`。
-        // 🔴 **新前缀也不作属主证据**(codex R1-[high],验真后收):`tr_<sid>~` 的单射只保证「core 用这个
-        // sessionId 铸出来的 ref 长这样」,**不**保证「长这样的 ref 一定是 core 用这个 sessionId 铸的」——
-        // `put(ref, content)` 的 ref 是 opaque handle、两参形合法、调用方可自铸(core 顶注 ① 逐字点名)。
-        // 拿它删无出处行 = 又一次「按 ref 猜属主」,只是猜得像一点。
-        //
-        // ⇒ `deleted` = `owner_session_id` 命中的行(ref 形状无关,会话 id 触发 `refSegment` 折叠时也不漏);
-        //    `unattributable` = 库里**所有**无出处行的计数(与 core `InMemoryToolResultStore.deleteBySession`
-        //    逐字同口径:它遍历全表,`provenance === undefined` 的一律 `unattributable++` 且**跳过不删**)。
-        //    这个数是「本店有多少行没人认领」这一**全库**事实,读法 = 「这次会话删除不可能是完整的」,
-        //    不是「本会话残留了 N 行」。存量无出处行的实体清理归 TTL(`reapOlderThan`)。
-        // ⚠️ 登记后续件:`owner_session_id` 上没有索引(本表只有 PK(ref) 与 created_at 索引),删与计数都是
-        // 全表扫。会话删除是管理面低频动作,先取正确与完整;要提速得改 DDL + 重生成两方言 baseline,那是独立一车。
         const deletion = await this.db.query(this.q("DELETE FROM tool_result WHERE owner_session_id = ?", "DELETE FROM tool_result WHERE owner_session_id = $1"), [sessionId]);
         const { rows } = await this.db.query(this.q("SELECT COUNT(*) AS n FROM tool_result WHERE owner_session_id IS NULL", "SELECT COUNT(*) AS n FROM tool_result WHERE owner_session_id IS NULL"));
         return { deleted: deletion.affected, unattributable: Number(rows[0]?.n ?? 0) };
     }
 }
-/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBToolResultStore extends SqlToolResultStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
-/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgToolResultStore extends SqlToolResultStore {
     constructor(pool) {
         super(pgDriver(pool));

package/dist/plugins/usage-window-store-sql.js

@@ -1,7 +1,5 @@
 import { EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord } from "@sema-agent/core";
 export const USAGE_WINDOW_TABLE = "usage_window";
-/** record 列 → UsageWindowRecord。坏形 fail-loud(治理窗算错=计费面撒谎;与快照/凭据类 store 的
- *  onCorruptRead 披露座不同族——这里没有「跳过一行继续」的安全语义,账本坏=停)。 */
 function parseRecord(raw, key) {
     let v;
     try {
@@ -14,8 +12,6 @@ function parseRecord(raw, key) {
     if (typeof v !== "object" || v === null || !Array.isArray(r.slots) || !Array.isArray(r.buckets)) {
         throw new Error(`usage_window record for key "${key}" has an invalid shape (expected {slots[],buckets[]}) — refusing to mis-count a governance window`);
     }
-    // 深度对齐 core FileUsageWindowStore(validateSlots/validateBuckets):内层坏形若放过,非数值
-    // tokens 参与累加得 "0oops" ⇒ exhausted:false,超额账户被判未耗尽。逐条校验,任一不合即 fail-loud。
     const badShape = (detail) => new Error(`usage_window record for key "${key}" has an invalid shape (${detail}) — refusing to mis-count a governance window`);
     const finite = (x) => typeof x === "number" && Number.isFinite(x);
     const slots = r.slots.map((s) => {
@@ -62,7 +58,6 @@ export class TiDBUsageWindowStore {
         const c = await this.pool.getConnection();
         try {
             await c.beginTransaction();
-            // ensure-first:幂等建空行(EMPTY record)⇒ 下一步 FOR UPDATE 行恒在(锁语义干净,无 gap-lock 死锁形)。
             await c.query(`INSERT IGNORE INTO ${USAGE_WINDOW_TABLE} (usage_key, record, updated_at_ms) VALUES (?, ?, ?)`, [
                 key,
                 JSON.stringify(EMPTY_USAGE_WINDOW_RECORD),
@@ -70,7 +65,6 @@ export class TiDBUsageWindowStore {
             ]);
             const [rows] = (await c.query(`SELECT record FROM ${USAGE_WINDOW_TABLE} WHERE usage_key = ? FOR UPDATE`, [key]));
             if (rows.length === 0) {
-                // 本表无删除臂(不同于 mailbox 的 drop/reap),ensure 后空 = 真障碍 fail-loud。
                 throw new Error(`usage_window row for key "${key}" vanished between ensure and lock — refusing to drop a governance charge`);
             }
             const record = parseRecord(rows[0].record, key);
@@ -101,8 +95,6 @@ export class PgUsageWindowStore {
         const c = await this.pool.connect();
         try {
             await c.query("BEGIN");
-            // ensure-first(TiDB 同注):ON CONFLICT DO NOTHING 幂等建空行,再锁——插入不带锁,锁只从
-            // FOR UPDATE 来(复审靶1 的 PG 交错:并发首充双双 ensure,后到方 DO NOTHING 后必须真锁行)。
             await c.query(`INSERT INTO ${USAGE_WINDOW_TABLE} (usage_key, record, updated_at_ms) VALUES ($1, $2, $3) ON CONFLICT (usage_key) DO NOTHING`, [
                 key,
                 JSON.stringify(EMPTY_USAGE_WINDOW_RECORD),

package/dist/plugins/web-search.js

@@ -1,63 +1,8 @@
-/**
- * design/102 (K-8 CC full-body) — the WebSearch BACKEND (BRAIN / model-service leg) that core leaves
- * deployment-injected (`WebSearchConfig.search`; core ships NONE, the same boundary as the model gateway). Wiring a
- * backend here is what makes `assembleFullBodyTools({ webSearch })` actually mount the WebSearch tool.
- *
- * Multi-provider, picked by `WEB_SEARCH_PROVIDER`:
- *   - `brave`   — Brave Web Search API (GET, `X-Subscription-Token` header)
- *   - `tavily`  — Tavily Search API (POST, `Authorization: Bearer`, native include/exclude_domains)
- *   - `searxng` — a self-hosted SearXNG instance (GET `?format=json`, no auth)
- *
- * Each returns `{ title, url, snippet }[]`; core does the rest — it `delimitUntrusted`-fences the (UNTRUSTED) results
- * and re-enforces the `allowed_domains`/`blocked_domains` FLOOR on them, so honoring `opts` here is an optimization,
- * not a correctness requirement (a backend MAY ignore it). The API key comes from deployment env — it never enters
- * the model prompt or the tool args. `effect:"read"` (idempotent) is core's concern; this is just the transport.
- *
- * ── 立案:装配层四条缺口([2176] 我方认领,2026-08-01 调研,**尚未实施**)────────────────────
- *
- * ① **`opts` 仍有 brave 腿不消费**(只剩 `brave` 的 switch 分支不传 `opts`;`searxng` 腿已随 ② 的
- *    还债改动接住 `opts` 并透传给 core 的 adapter,由它把 `allowedDomains` 原生下推成 `site:` 前缀。
- *    立案时的原话是「`opts` 只有 tavily 腿在消费(`brave`/`searxng` 都不传)」,② 落地后已部分还清)。
- *    定性:**优化缺失,不是正确性缺口** —— 上面那句「core 再执行一次 FLOOR」经亲验属实
- *    (core `dist/tools/web.js` 的 `webSearchResultAllowed(url, allowed, blocked)`,按 hostname
- *    逐条过滤 blocked/allowed)。所以模型请求的域限制**不会**被静默丢弃。
- *    但代价真实:后端搜回一堆注定被 core 丢掉的结果 ⇒ 白花配额、白等延迟,极端情况下
- *    「限域搜索」返回 0 条(拿回来的 N 条全不在 allowed 里)而后端其实能做原生过滤。
- *    ⚠️ 判据留痕:我第一轮把这条判成了「约束被静默丢弃」的安全缺口,是**亲读 core 结果侧代码**
- *    才推翻的。「别处已经处理了」这种声明必须验证 —— 这次它是真的,但真假只能靠读。
- *
- * ② ~~**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)。
- *    我在黑板 [2190] 已公开表态「按 core 的接、不再自铸第二真源」—— 这条是待兑现的债。
- *    换的时候要核对的等价点:本文件的 `normalize()` 统一形状 + `max` 截断 +
- *    `setWebSearchBadPayloadObserver` 观测器,core 的 adapter 都没有,得在外层补回来。
- *
- * ③ **四级优先级语义未定**(env / config-center / per-scenario / per-request 谁压谁)。
- *    🔴 三问里「谁被伤」这条决定了默认值:一个**只配了模型 key** 的既有部署,若新语义让某一级
- *    能自行打开搜索,它就在升级后**凭空长出一条出网工具** —— 那是安全姿态变更,不是特性。
- *    ⇒ 语义定稿前,任何新的开启通道**默认 OFF**;开启必须是部署方的显式动作。
- *
- * ④ ~~**探活 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";
 const TAVILY_BASE = "https://api.tavily.com/search";
-/** Combine the caller's AbortSignal with a per-search timeout into one signal; `done()` clears the timer + listener. */
 function withTimeout(signal, ms) {
     const ctrl = new AbortController();
     const onAbort = () => ctrl.abort();
@@ -74,13 +19,6 @@ function withTimeout(signal, ms) {
 async function errorText(res) {
     return (await res.text().catch(() => "")).slice(0, 200);
 }
-/**
- * Normalize an UNTRUSTED provider results payload: guard a non-array (a misconfigured proxy / buggy self-hosted
- * SearXNG could return a non-list or null elements), skip null/non-object rows, coerce every field to a string, drop
- * url-less rows, cap to max. `pick` maps each provider's row to the common shape (Brave→description, others→content).
- */
-/** LOW (SILENT-FALLBACK P1): a provider returning a non-array `results` used to silently become zero results
- *  for the model. main.ts wires this to web_search_bad_payload_total{provider} + a warn. */
 let onBadPayload;
 export function setWebSearchBadPayloadObserver(fn) {
     onBadPayload = fn;
@@ -91,18 +29,18 @@ function normalize(raw, pick, max, provider) {
             try {
                 onBadPayload?.(provider);
             }
-            catch { /* observability never breaks search */ }
+            catch { }
         }
-        return []; // absent field (undefined/null) = legitimately empty; a PRESENT non-array = malformed payload
-    } // 🔴 review LOW: a non-array `results` must not throw a raw TypeError upstream
+        return [];
+    }
     const out = [];
     for (const row of raw) {
         if (!row || typeof row !== "object")
-            continue; // a null / non-object element is not a result
+            continue;
         const f = pick(row);
         const url = typeof f.url === "string" ? f.url : "";
         if (!url)
-            continue; // no URL ⇒ useless to the model (and to core's domain re-enforcement)
+            continue;
         out.push({ title: typeof f.title === "string" ? f.title : "", url, snippet: typeof f.snippet === "string" ? f.snippet : "" });
         if (out.length >= max)
             break;
@@ -114,8 +52,7 @@ async function braveSearch(fetchImpl, cfg, query, max, signal) {
         throw new Error("WEB_SEARCH_API_KEY is required for the brave provider");
     const url = new URL(cfg.endpoint || BRAVE_BASE);
     url.searchParams.set("q", query);
-    url.searchParams.set("count", String(Math.min(20, max))); // Brave caps count at 20
-    // Brave has no native include/exclude_domains param — core re-enforces the domain floor on the results.
+    url.searchParams.set("count", String(Math.min(20, max)));
     const res = await fetchImpl(url, { headers: { Accept: "application/json", "X-Subscription-Token": cfg.apiKey }, signal });
     if (!res.ok)
         throw new Error(`brave search failed (${res.status}): ${await errorText(res)}`);
@@ -127,7 +64,7 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
         throw new Error("WEB_SEARCH_API_KEY is required for the tavily provider");
     const body = { query, max_results: Math.min(20, max) };
     if (opts?.allowedDomains?.length)
-        body.include_domains = opts.allowedDomains.slice(0, 300); // Tavily native domain filter
+        body.include_domains = opts.allowedDomains.slice(0, 300);
     if (opts?.blockedDomains?.length)
         body.exclude_domains = opts.blockedDomains.slice(0, 150);
     const res = await fetchImpl(cfg.endpoint || TAVILY_BASE, {
@@ -141,27 +78,9 @@ 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");
 }
-/**
- * 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, timeoutMs, opts) {
     if (!cfg.endpoint)
         throw new Error("WEB_SEARCH_ENDPOINT (the SearXNG instance URL) is required for the searxng provider");
-    // 🔴 timeoutMs 必须显式传:core 的 adapter 内部是 `options.timeoutMs ?? 10_000`,不传就用它自己的
-    //    10 秒。外层 createWebSearchBackend 那道 withTimeout 只在**更短**时先到 —— 部署方把
-    //    WEB_SEARCH_TIMEOUT_MS 设成大于 10s 的值(慢实例/自建 SearXNG 的常见需要)会被**静默封顶在 10s**,
-    //    而 3.18.0 的 CHANGELOG 还把 core「自带 timeout」当纯收益卖(见 3.20.0 的更正段)。
-    //    两层同值不冲突:内层是 adapter 自己的 AbortSignal.any,外层是本文件的 withTimeout。
     const search = createSearxngSearchBackend(cfg.endpoint, {
         fetchImpl,
         timeoutMs,
@@ -172,25 +91,18 @@ async function searxngSearch(fetchImpl, cfg, query, max, signal, timeoutMs, opts
         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 */ }
+            catch { }
             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
- * stays captured in this closure — it is never surfaced to the model or the tool args.
- */
 export function createWebSearchBackend(cfg) {
     const fetchImpl = cfg.fetchImpl ?? fetch;
     const maxResults = Math.max(1, Math.min(20, cfg.maxResults ?? DEFAULT_MAX_RESULTS));
@@ -213,22 +125,8 @@ export function createWebSearchBackend(cfg) {
     };
     return { search, maxResults };
 }
-/**
- * `WEB_SEARCH_SEARXNG_PARAMS` / `settings.webSearch.searxngParams` 的解析 —— SearXNG 实例侧参数
- * (`engines=` / `language=` 等)。
- *
- * 🔴 [2240] cli 逐串直证:3.18.0 我加了 `searxngParams` 字段和消费点,**却没开任何配置入口** ——
- * 两条门都没有位置填它,于是我在 [2239] 说的「这条是给你们的」是句空话。单测直接构造
- * `WebSearchBackendConfig` 传进去,**天然绕过了配置入口这一层**,于是「能力在」与「配得进」之间
- * 断开,而两边的绿都是真的。判据:**按消费端实际能填的那个入口验,不是按自己构造的对象验。**
- *
- * 形状:`k=v` 用 `;` 分隔(`engines=bing,duckduckgo;language=zh-CN`)——值里本来就常含逗号,
- * 所以分隔符取 `;` 而不是 `,`。整串解析不出任何一对 ⇒ **返回 undefined,键整个不铸**
- * (不产出空对象:空对象会让下游以为「配了但是空的」,与本仓「缺席就要缺席得干净」同源)。
- */
 export function parseSearxngParams(raw) {
     if (typeof raw === "object" && raw !== null) {
-        // settings 门传的是已解析的表;只收「字符串→字符串」,任一值非字符串 ⇒ 整表不铸(不半吞)。
         const entries = Object.entries(raw);
         if (entries.length === 0 || entries.some(([, v]) => typeof v !== "string"))
             return undefined;
@@ -248,44 +146,26 @@ export function parseSearxngParams(raw) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
-/**
- * #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();
     if (provider !== "brave" && provider !== "tavily" && provider !== "searxng")
         return undefined;
-    const searxngParams = parseSearxngParams(env.WEB_SEARCH_SEARXNG_PARAMS); // [2240] 部署 env 门
+    const searxngParams = parseSearxngParams(env.WEB_SEARCH_SEARXNG_PARAMS);
     const maxRaw = Number(env.WEB_SEARCH_MAX_RESULTS ?? "");
     const timeoutRaw = Number(env.WEB_SEARCH_TIMEOUT_MS ?? "");
     return {
         provider,
         ...(env.WEB_SEARCH_API_KEY ? { apiKey: env.WEB_SEARCH_API_KEY } : {}),
         ...(env.WEB_SEARCH_ENDPOINT ? { endpoint: env.WEB_SEARCH_ENDPOINT } : {}),
-        ...(searxngParams ? { searxngParams } : {}), // [2240] 解析不出任何一对 ⇒ 键整个不铸(不产出空对象)
+        ...(searxngParams ? { searxngParams } : {}),
         ...(Number.isFinite(maxRaw) && maxRaw > 0 ? { maxResults: Math.floor(maxRaw) } : {}),
         ...(Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? { timeoutMs: Math.floor(timeoutRaw) } : {}),
     };
 }
-/**
- * Parse an UNTRUSTED per-request `body.settings.webSearch` (the user's shell settings — `{provider, apiKey?, endpoint?,
- * maxResults?}`) into a backend config. Returns `undefined` for a missing/invalid provider — NEVER throws, so a bad
- * per-request config falls back to the deployment-env backend rather than failing the task. 🔒 The CALLER gates this to
- * the single-user host lane (a per-request `endpoint`/`apiKey` is a capability config; on multi-tenant a tenant could
- * point `searxng` at an internal URL = SSRF, so multi-tenant uses ONLY the deployment-env backend — design/107 axis).
- */
 export function webSearchConfigFromSettings(raw) {
     if (!raw || typeof raw !== "object")
         return undefined;
@@ -298,8 +178,6 @@ export function webSearchConfigFromSettings(raw) {
         provider,
         ...(typeof s.apiKey === "string" && s.apiKey ? { apiKey: s.apiKey } : {}),
         ...(typeof s.endpoint === "string" && s.endpoint ? { endpoint: s.endpoint } : {}),
-        // [2240]:与 endpoint **同门同辖域** —— 安全边界不在字段粒度,而在调用方把整条门 gate 到
-        // 单用户 host lane(见本函数头注的 SSRF 段)。单独把它挡在门外是个没有理由的例外。
         ...(() => {
             const p = parseSearxngParams(s.searxngParams);
             return p ? { searxngParams: p } : {};