@sema-agent/server 7.13.0 → 7.15.0

package/dist/plugins/tool-result-store-sql.d.ts

@@ -1,4 +1,4 @@
-import type { ToolResultStore, ToolResultSlice } from "@sema-agent/core";
+import type { ToolResultProvenance, ToolResultStore, ToolResultSlice } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
@@ -8,6 +8,21 @@ import { type SqlDriver } from "./sql-driver.js";
 export declare const PG_TOOL_RESULT_SCHEMA: string[];
 /** Idempotent schema apply for the tool_result table (for the integration test to call). */
 export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>;
+/**
+ * #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 declare function assertToolResultProvenanceSchema(query: (sql: string) => Promise<{
+    rows: Record<string, unknown>[];
+}>, dialect: "tidb" | "pg"): Promise<void>;
 /** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
@@ -24,7 +39,25 @@ export declare class SqlToolResultStore implements ToolResultStore {
      *  抛错文案与 core 逐字相同,所以 wire 与既有钉都不变。 */
     private isUnsafeRef;
     private assertSafeRef;
-    put(ref: string, content: string): Promise<void>;
+    /**
+     * #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。
+     */
+    put(ref: string, content: string, provenance?: ToolResultProvenance): Promise<void>;
+    /** 一次回读同时回答两件事:**行在不在**(reap/purge 窗口的判别位)与**属主是谁**。两件事必须来自同一
+     *  条 SELECT —— 分两次问会重新引入它要消灭的那个窗口。 */
+    private readOwner;
+    /**
+     * #119 —— 出处的**读面**。未知 ref 与「存了但无属主」两种情况都答 `undefined`:读面对二者一视同仁
+     * (fail-closed,谁都没被授权),所以这里也不必把它们分开报。
+     */
+    ownerOf(ref: string): Promise<ToolResultProvenance | undefined>;
     get(ref: string, opts?: {
         offset?: number;
         limit?: number;

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

@@ -9,7 +9,8 @@
  * 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>` (1.49) → globally unique → usable directly as
+ * 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
@@ -35,7 +36,7 @@
  *     sessions' rows); PG spells `ESCAPE '\'` (its default escape char already, kept for lock-step intent
  *     with the TiDB twin rather than out of necessity).
  */
-import { assertSafeToolResultRef } from "@sema-agent/core";
+import { MAX_MINTED_TOOL_RESULT_REF_CHARS, assertSafeToolResultRef, assertToolResultProvenanceMatch, normalizeToolResultProvenance } from "@sema-agent/core";
 import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
@@ -43,10 +44,14 @@ import { mysqlDriver, pgDriver } from "./sql-driver.js";
  *  (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(190) COLLATE "C" NOT NULL,
-     content    TEXT COLLATE "C"         NOT NULL,
-     created_at TIMESTAMPTZ(3) NOT NULL,
+     ref              VARCHAR(518) COLLATE "C" NOT NULL,
+     content          TEXT COLLATE "C"         NOT NULL,
+     owner_session_id VARCHAR(190) COLLATE "C" NULL,
+     owner_task_id    VARCHAR(190) COLLATE "C" NULL,
+     created_at       TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (ref)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_tool_result_created ON tool_result (created_at)`,
@@ -56,6 +61,49 @@ 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 ` +
+            `one row — one run's tool output reads back from another run's ref. This repository ships no ALTER TABLE migrations: ` +
+            `run \`DROP TABLE tool_result;\` on the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart ` +
+            `(the schema is recreated at boot; offloaded results are a recoverable-window cache, inline previews are unaffected).`);
+    }
+    try {
+        await query("SELECT owner_session_id, owner_task_id FROM tool_result WHERE 1=0");
+    }
+    catch (err) {
+        throw new Error(`tool_result is missing the #119 provenance columns (owner_session_id / owner_task_id) — refusing to start. ` +
+            `This release picks up @sema-agent/core 5.26.0, which changed how an offloaded tool result is addressed ` +
+            `(the ref grew past the old VARCHAR(190) key) and made the store record who wrote each row. This repository ` +
+            `ships no ALTER TABLE migrations, so the table must be recreated: run \`DROP TABLE tool_result;\` on the ` +
+            `${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the schema is recreated at boot. ` +
+            `Offloaded tool results are a recoverable-window cache (the inline previews in transcripts are unaffected), ` +
+            `so the cost is at most the full text of results from runs still in flight. ` +
+            `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;
@@ -87,7 +135,17 @@ export class SqlToolResultStore {
     assertSafeRef(ref) {
         assertSafeToolResultRef(ref);
     }
-    async put(ref, content) {
+    /**
+     * #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
@@ -102,7 +160,58 @@ export class SqlToolResultStore {
         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.
-        await this.db.query(this.q("INSERT IGNORE INTO tool_result (ref, content, created_at) VALUES (?,?,?)", "INSERT INTO tool_result (ref, content, created_at) VALUES ($1,$2,$3) ON CONFLICT (ref) DO NOTHING"), [ref, safe, new Date()]);
+        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; // 本次赢下选举:内容与属主同一条语句落地
+        const stored = await this.readOwner(ref);
+        if (stored.present) {
+            // 抢输(或纯重放):属主判定归 core 的单源比较器 —— 「同属主」在两个 store 里不许有两种含义。
+            assertToolResultProvenanceMatch(ref, stored.owner, owner);
+            return;
+        }
+        throw new Error(`tool-result store: ref ${JSON.stringify(ref)} lost the write-once election and the elected row was already gone ` +
+            `(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 列 = 行在但无属主
+        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 (await this.readOwner(ref)).owner;
     }
     async get(ref, opts = {}) {
         // D1 读面半条(RB-266「the read face degrades instead」):unsafe ref 在读面**降级**返回 undefined
@@ -147,11 +256,18 @@ export class SqlToolResultStore {
      * data-layer protection that matters (a crafted id can't widen the prefix across tenants).
      */
     async deleteBySession(sessionId) {
-        // Escape the WHOLE literal prefix `tr_<sessionId>_` (incl. both literal underscores) so the only LIKE wildcard
-        // is the trailing `%` — a `_` left un-escaped is a single-char wildcard that could over-match across tenants.
-        const prefix = `${escapeLike(`tr_${sessionId}_`)}%`;
+        // Escape the WHOLE literal prefix `tr_<sessionId><sep>` (incl. the literal underscore in `tr_` and, on the
+        // legacy arm, the separator underscore) so the only LIKE wildcard is the trailing `%` — a `_` left
+        // un-escaped is a single-char wildcard that could over-match across tenants.
+        //
+        // 🔴 #119(core 5.26.0):**两个前缀**,因为铸法在 5.26.0 换了分隔符。5.25.0 及以前铸 `tr_<sid>_<callId>`,
+        // 5.26.0 起铸 `tr_<sid>~<callId>~<contentSeg>`(单射 ref)。只留旧前缀 = 升级后一行也命不中,§0.5 会话
+        // 删除**静默清零**;只留新前缀 = 升级前写下的存量行永远删不掉。删除面漏删比多跑一次 LIKE 贵得多,
+        // 所以两条都发,而且都保持「整段字面量转义 + 只有末尾 % 是通配」的老纪律。
+        const legacyPrefix = `${escapeLike(`tr_${sessionId}_`)}%`;
+        const modernPrefix = `${escapeLike(`tr_${sessionId}~`)}%`;
         // Explicit `ESCAPE` clause — see the file-header dialect-delta note for why each dialect spells it as it does.
-        const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE ref LIKE ? ESCAPE '\\\\'", "DELETE FROM tool_result WHERE ref LIKE $1 ESCAPE '\\'"), [prefix]);
+        const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE ref LIKE ? ESCAPE '\\\\' OR ref LIKE ? ESCAPE '\\\\'", "DELETE FROM tool_result WHERE ref LIKE $1 ESCAPE '\\' OR ref LIKE $2 ESCAPE '\\'"), [legacyPrefix, modernPrefix]);
         return affected;
     }
 }

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

@@ -15,7 +15,9 @@
  *
  * ── 立案:装配层四条缺口([2176] 我方认领,2026-08-01 调研,**尚未实施**)────────────────────
  *
- * ① **`opts` 只有 tavily 腿在消费**(`brave`/`searxng` 的 switch 分支不传 `opts`)。
+ * ① **`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)。所以模型请求的域限制**不会**被静默丢弃。

package/dist/plugins/web-search.js

@@ -15,7 +15,9 @@
  *
  * ── 立案:装配层四条缺口([2176] 我方认领,2026-08-01 调研,**尚未实施**)────────────────────
  *
- * ① **`opts` 只有 tavily 腿在消费**(`brave`/`searxng` 的 switch 分支不传 `opts`)。
+ * ① **`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)。所以模型请求的域限制**不会**被静默丢弃。

package/dist/security.js

@@ -171,7 +171,9 @@ export function createAuthorizer(config, sessionStore) {
                     }
                 }
                 // Enforce ownership whenever the session HAS an owner — including against callers that present
-                // no principal (audit B, security.ts:77): with the old `principal &&` guard, a caller that
+                // no principal (audit B — the fix IS this guard, right here in `createAuthorizer`; no line-number
+                // anchor on purpose, the old `security.ts:77` pointer had drifted onto an unrelated JSDoc):
+                // with the old `principal &&` guard, a caller that
                 // omitted the header under requirePrincipal=false could attach to ANY owned session by id.
                 // Anonymous callers may still attach to anonymous (owner=null) sessions, so single-tenant dev
                 // (no principals anywhere) is unaffected; flipping the requirePrincipal default is NOT needed.

package/dist/tool-approval.d.ts

@@ -190,6 +190,7 @@ export declare function parseToolApprovalResponse(body: unknown): {
     value: ToolApprovalDecision;
     updatedInput?: unknown;
     persistRule?: string;
+    note?: string;
 } | {
     ok: false;
     error: string;

package/dist/tool-approval.js

@@ -47,7 +47,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7, MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "./trace/redact.js";
 import { createLogger } from "./observability/logger.js";
-import { deriveAskId, deriveBatchId } from "./approval-ask-machine.js";
+import { deriveAskId, deriveBatchId, MAX_DECISION_NOTE_CHARS } from "./approval-ask-machine.js";
 import { ApprovalCardEnvelopeSchema, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, } from "./approval-card.js";
 import { governanceAskMarksFor, runWithGovernanceAskScope } from "./governance-ask-marks.js";
 /** #151 车2:本模块自有的日志出口——同 config-provider.ts/runtime-caps-resolver.ts 先例(协调器不走
@@ -159,7 +159,27 @@ export function parseToolApprovalResponse(body) {
             }
             persistRule = rule;
         }
-        return { ok: true, value: d, ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}), ...(persistRule !== undefined ? { persistRule } : {}) };
+        // #229(设计稿 233 稿B):回决**理由**。与 durable 腿(`http/routes/runs.ts` 的 `AskDecisionBodySchema.note`)
+        // **同词同源同上限**({@link MAX_DECISION_NOTE_CHARS}),落的也是同一列 `decision_note` —— 不造第三口径。
+        // 🔴 **任何 decision 都可带**(deny 也算),与 durable 腿的无条件记账形对齐:「为什么拒」正是审计面上
+        // 最值钱的那一条,做成 allow-only 等于把它扔掉。⚠️ `allow_session` 是 wire 上的三值之一,落到行上是
+        // `approve`(三值映二值)—— 它的 note 因此记在**那条 approve 行**上,不另开一行、也不丢。
+        // 坏形(非串 / 超上限)是**响亮 400**,不静默截断:一条被悄悄砍半的审计理由比没有理由更坏。
+        const rawNote = body.note;
+        let note;
+        if (rawNote !== undefined) {
+            if (typeof rawNote !== "string" || rawNote.length > MAX_DECISION_NOTE_CHARS) {
+                return { ok: false, error: `note must be a string of at most ${MAX_DECISION_NOTE_CHARS} characters` };
+            }
+            note = rawNote;
+        }
+        return {
+            ok: true,
+            value: d,
+            ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}),
+            ...(persistRule !== undefined ? { persistRule } : {}),
+            ...(note !== undefined ? { note } : {}),
+        };
     }
     return { ok: false, error: 'decision must be one of "allow" | "allow_session" | "deny"' };
 }
@@ -782,6 +802,25 @@ export class ToolApprovalCoordinator {
         //  ③ 引擎真铸了候选(`req.ruleSuggestions` 非空)—— 命令不可匹配(复合/重定向/替换)时 core 交空数组;
         //  ④ 命令原字节读得出(回决时**引擎**要拿它重铸候选;读不出就没有可兑付的路,投候选等于骗人)。
         // 读 `req.args.command` 走窄读:`args` 是 `unknown`,禁裸 as-cast(宪法 [2704])。
+        // 🔴 **core 5.27.0 起引擎自己也收窄了产源**(#231 提货,[3612]):mandated(`shellGate:"always"` /
+        // 工具自带 egress / irreversibility `always|maybe` 标记;⚠️ **不含 org 规则**,亲读 `persistedRuleMandateOf`
+        // 只收 {egress, irreversibility, shellGated} 三位)、`requiresRealApproval`、shadowed、hook 产、inherited-unresolved、ancestor-resolved、
+        // anonymous(无 principal 且未声明 local-owner)六族 ask **一律不带** `ruleSuggestions`(亲读
+        // `dist/core/runner/prepare-task.js` 的 `ruleSuggestionsOf`,不是读 CHANGELOG)。这与本仓那句
+        // 「发一格按下去无处可兑的『不再询问』= wire 谎言」是**同一条判据**,只是这次由引擎在源头执行。
+        // 上面四个合取项**一个都不删**:①③④ 是我方独有的前置(店装配 / 空数组不铸键 / 命令可读),
+        // ② 的 `governanceForced` 是**我方**的治理标(部署侧 AUTONOMY/commandPolicy/SENSITIVE_WRITE_PATTERNS,
+        // 引擎的 mandated 词表里没有它),六族里的另外四族只有引擎判得出(消音谓词 / hook 出处 / 继承未决 /
+        // 祖先决议),所以两侧不是重复,是各管各的那一段。
+        // 唯一**重叠**的是 anonymous 那一族:引擎的判据是 `spec.principal` 空且 `deps.localOwnerRules !== true`
+        // (我方从不设后者,亲验 `grep -rn localOwnerRules src` 只有 adoption 计划表里的一行声明位),
+        // 而我方的判据是 ask 的 `owner === null` —— 两者同源(`askOwner = gatedPrincipal(req) ?? null` 与
+        // `spec.principal = auth?.principal` 取自同一次鉴权)⇒ **本批对单机匿名部署零行为变化**(那种卡在
+        // #203 codex R1-F1 之后本来就不带候选)。⚠️ 记档:若将来要让单机形也能「不再询问」,正路是声明
+        // `RunnerDeps.localOwnerRules`(core 会在 provider 缺 `forLocalOwner` 时**抛**,不静默),而不是把
+        // 我方这道 owner 门放宽 —— 那会造出一张按下去无处可兑的卡。
+        // 候选**基数**同批从 ≤1 变成 ≤2(reviewed 前缀候选,`exact` 恒 index 0)——本层逐字透传整只数组,
+        // 不截长不重排;兑付口按**人报的文本**定位(`rules-consent.ts` 的 `findIndex`,不是 `[0]`)。
         // `let`:上面那条并集裁定可能在对账后把它撤回 undefined(行说这是治理门)。
         let ruleLaneMaterial = this.buildRuleLaneMaterial(req, primary.owner, governanceForced);
         const frame = {
@@ -1645,14 +1684,28 @@ export class ToolApprovalCoordinator {
      *  时仍是纯同步函数(D1)。`askStore`/`askId`/`batchId` 由调用方在已窄化的分支里传入(避免非空断言）。 */
     async respondWithCas(askStore, askId, batchId, id, entry, parsed) {
         let decidedWon = false;
+        // 🔴 #229 + codex 对抗复审 round1 [high](验真后修):`noteRecorded` 的判据比 `decidedWon` **更严**,
+        // 所以是**两个**变量而不是一个。`decidedWon` 回答「这条决议是不是终局」(单赢者 CAS 的语义,足够支撑
+        // 200/404 的分派与 `notifyExternalDecision`);`noteLanded` 回答「**这一次请求**的那段文本在不在行上」。
+        // 两者在**提交歧义**臂上会分岔(见下方 catch 里的理由),而回执上那句「你的理由记上了」只能由后者答。
+        let noteLanded = false;
         try {
-            const decided = await this.withStoreDeadline(askStore.decideAsk(askId, batchId, { decision: parsed.value === "deny" ? "deny" : "approve" }), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
+            const decided = await this.withStoreDeadline(
+            // #229:`decisionNote` 是**店缝上既有**的键(`DecideAskInput.decisionNote`,SQL twin 与 memory twin
+            // 都已实装)⇒ 零新 SQL、零新列,live 腿与 durable 腿写同一条 UPDATE 的同一列。
+            askStore.decideAsk(askId, batchId, {
+                decision: parsed.value === "deny" ? "deny" : "approve",
+                ...(parsed.note !== undefined ? { decisionNote: parsed.note } : {}),
+            }), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
                 // R3-1 迟到成功:HTTP 响应早已发出(这次调用报的是超时),但**决议真落了盘** —— 同 askId 下
                 // 还在悬挂的本地条目必须按真决议结清,否则它们只能等自己的窗/取消再绕一圈。
                 if (late.ok)
                     this.notifyExternalDecision(askId, parsed.value !== "deny", parsed.updatedInput);
             });
             decidedWon = decided.ok;
+            // 干净赢下 CAS ⇒ note 与决议是**同一条 UPDATE** 写的,赢即落,不必再读一次。
+            if (decided.ok)
+                noteLanded = true;
             if (!decided.ok) {
                 // CAS 输——respond 绝不覆盖赢家(D2)。逐字复用现行 404 形(409/410 分化留给车4)。
                 return { status: 404, body: { error: "no pending tool approval for this id (settled, expired, or not on this replica)", errorCode: "tool_approval.not_pending" } };
@@ -1668,8 +1721,18 @@ export class ToolApprovalCoordinator {
             // 那本就该回放成功)。复核读本身失败/超时 ⇒ 维持「不知道」,守卫照旧 404(不许把未知说成成功)。
             try {
                 const row = await this.withStoreDeadline(askStore.getAsk(askId), "getAsk(decideAsk-confirm)", DURABLE_CONVERGE_READ_TIMEOUT_MS);
-                if (row?.state === "DECIDED" && row.decision === (parsed.value === "deny" ? "deny" : "approve"))
+                if (row?.state === "DECIDED" && row.decision === (parsed.value === "deny" ? "deny" : "approve")) {
                     decidedWon = true;
+                    // 🔴 codex 对抗复审 round1 [high](真 finding,红先复现):**note 的判据不能沿用决议的判据**。
+                    // 上一段那句「别人不可能写出同一条决议再让我们看见」对**决议**成立(单赢者 CAS),对 `note`
+                    // **不成立** —— 两路并发 respond 完全可以带**同决议、不同 note**:一路干净赢下 CAS(写进去的是
+                    // 它的 note),另一路撞上提交歧义,在这次确认读里看见那条 DECIDED 行。只比决议的话,输的那一路
+                    // 会把别人的胜利认成自己的,回一句「你的理由记上了」,而行上是**别人**的理由 —— 恰好是本布尔
+                    // 存在的意义被反过来用。所以这里逐字比**行上的 note**:相等才算落地(文本真的相同就不是谎,
+                    // 哪怕是别人写的);行上没有 note、或与本次提交不同 ⇒ 如实 `false`。
+                    // 决议侧的 `decidedWon` 保持原样(200/404 的分派与 `notifyExternalDecision` 的判据不动)。
+                    noteLanded = parsed.note === undefined || row.decisionNote === parsed.note;
+                }
             }
             catch (confirmErr) {
                 this.noteStoreError(confirmErr, "getAsk(decideAsk-confirm)");
@@ -1707,9 +1770,12 @@ export class ToolApprovalCoordinator {
             // session 记忆照记(grant 谈的是**将来**的 ask,与这次投递是否由我完成无关)。
             // 但 `updatedInput` **没有**随那次结算送达闭包(R2-4)⇒ 显式声明未投递,回显里不许出现
             // `updatedInputForwarded`。
-            return this.finishRespond(id, entry, parsed, { updatedInputDelivered: false });
+            // #229:`noteRecorded` 取的是**店的真实结果**(`noteLanded`,比 `decidedWon` 更严——见其声明处),
+            // 与 `updatedInputForwarded` 的判据刻意分家:那一格问「闭包收到编辑没有」(本支恒否),
+            // 这一格问「行上记下的是不是**这次**的理由」。两件事,不共用一个布尔。
+            return this.finishRespond(id, entry, parsed, { updatedInputDelivered: false, noteRecorded: noteLanded });
         }
-        const result = this.finishRespond(id, entry, parsed);
+        const result = this.finishRespond(id, entry, parsed, { noteRecorded: noteLanded });
         // round5(pendingByAskId 顶注):回决赢下 CAS 时同样要收尾「同 askId 重复本地注册」那一支——与
         // windowExpired/runCancel/emitAllP 三条竞争者的赢家路径同精神(那三处已经这么做)。此处 entry 已经
         // 经 `finishRespond` 自行 settle 并从 pendingByAskId 的 Set 里摘除自己,故这里天然只会清算真正
@@ -1749,6 +1815,21 @@ export class ToolApprovalCoordinator {
         // 命令行);此时还回 `updatedInputForwarded: true` 等于告诉壳「你的编辑生效了」,是最不该撒的那种谎。
         // 调用方在 stale-entry 分支传 `updatedInputDelivered: false`,回显里这个键就整个缺席(壳按未透传处理)。
         const updatedInputDelivered = opts?.updatedInputDelivered ?? true;
+        // #229(设计稿 233 稿B v2 §1):`noteRecorded` = 这次回决的**理由到底有没有落进持久行**。
+        //
+        // 🔴 形照 `rulePersisted`(always-emit 布尔,只在请求真带了 `note` 时在场),值照**店的真实结果**
+        // (调用方传进来的 `decidedWon`,含 CAS 抛错后那次确认读的改判),不是「askStore 在不在」:
+        //  · 本方法被 `respond()` **直接**调到 = store 缺席,或 store 在场但 `ensureAsk` 失败已清掉坐标 ——
+        //    两种都是「压根没打过那条 UPDATE」,缺省 `false` 正是这一支的真相;
+        //  · `respondWithCas` 的 D5 fail-open 支(店抖动、确认读也没读到赢)同样 `false` —— **不知道不许
+        //    说成成功**(与 `updatedInputForwarded` 从不发 `false`、只在真投递时发 `true` 是同一条纪律的两面:
+        //    那一格靠缺席表达否定,这一格是三态里的一态,必须显式说 `false`,否则壳分不出「这台不支持」);
+        //  · 提交歧义臂上**赢了决议但行上是别人的 note**(同决议不同 note 的并发)同样 `false` —— 判据是
+        //    「行上那段文本是不是这次提交的」,不是「这条决议是不是终局」(codex round1 [high],见调用方
+        //    `respondWithCas` 里 `noteLanded` 的推导)。
+        // 能力位 `capabilities.approvalDecisionNote` 与本格**必须同车**:老服务对未知键静默丢 + 200,少了
+        // 能力位,「记上了」与「这台不认识 note」在 wire 上不可判别。
+        const noteRecorded = opts?.noteRecorded ?? false;
         return {
             status: 200,
             body: {
@@ -1757,6 +1838,7 @@ export class ToolApprovalCoordinator {
                 decision: parsed.value,
                 ...(rememberApplied !== undefined ? { rememberApplied } : {}),
                 ...(parsed.updatedInput !== undefined && allowed && updatedInputDelivered ? { updatedInputForwarded: true } : {}),
+                ...(parsed.note !== undefined ? { noteRecorded } : {}),
             },
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.13.0",
+  "version": "7.15.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",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.25.0",
+    "@sema-agent/core": "^5.27.0",
     "@sema-agent/registry-core": "^0.16.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
@@ -69,7 +69,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "^6.14.0",
+    "@sema-agent/sdk": "^6.16.0",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",