@sema-agent/server 7.135.0 → 7.136.0

package/dist/plugins/sql-errors.d.ts

@@ -129,11 +129,13 @@ export declare function rowTooLargeWallOf(dialect: SqlDialect, err: unknown): Ro
  * (`ErrEntryTooLarge`,事务层的语句错;真库读数:同池上 8025 写之后的读照常 —— `checkpoint-row-size-db-integration` ②③④)。
  * 断连形(`ECONNRESET` / `EPIPE` / `PROTOCOL_CONNECTION_LOST`)也不在表里:那是 mysql2 的**致命错误**,连接对象自己已经 `_removeFromPool`。
  * PostgreSQL 没有对应面:node-pg 的 `pool.query` 对任何错误都丢弃那条 client。
+ * `statementRefusal`:这一行的错说的是**这一条语句**被拒(连接坏只是后果)—— 同一句话换一条连接重试仍被拒。{@link isConnectionFaultError} 读同一张表,认其余各行为连接类故障,唯独不认带这个标记的行。
  * 新增一行 = 改表 + 在 `test/db-closed-connection-never-pooled.test.ts` 的码表里加一格。
  */
 export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
     readonly errno: number;
     readonly code: string;
+    readonly statementRefusal?: true;
 }>;
 /**
  * 「抛出这个错误的那条连接还能不能回池」的单一判据:{@link MYSQL_CONNECTION_UNUSABLE_ERRORS} 里的错 ⇒ **不能** —— 持连接的一方(`sql-driver.ts` 的 `leaseOf`)
@@ -141,6 +143,43 @@ export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
  * 认不出的一律不是(连接照常归还;断连形由 mysql2 自己清出池)。只管 MySQL 协议的错误形:PG 的错误没有这两个键,恒 false。
  */
 export declare function isConnectionUnusableError(err: unknown): boolean;
+/**
+ * **连接类故障**的识别表(闭集;逐行登记「为什么」)—— 「到库的那条连接坏了 / 库此刻不接」:与这一条语句的内容无关、什么都不改稍后再试可能成。
+ * 读者(整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf`,三处同读):审批队列读口、文件历史店的折点(`permanence: "transient"`)、会话同步拉取口(`503`)。
+ *
+ * 识别集 = 三张表的并集,**没有第四处**:
+ *  · 本表(下):套接字层与协议层的断连 / 拒连 / 连接数满 / 库的关停与只读切换,按 `code` 登记(MySQL 协议的数字 errno 在场的并登 —— 同本文件其余谓词的姿势:`errno` 与 `code` 是同一件事的两种写法);
+ *  · {@link MYSQL_CONNECTION_UNUSABLE_ERRORS}(「这条连接不许再回池」的 MySQL 协议错):整表读入,**唯独不认带 `statementRefusal` 的行**(1153:拒的是这一条语句,不是连接);
+ *  · {@link CONNECTION_FAULT_DRIVER_SENTENCES}:驱动自己抛的**无 `code` 的裸 `Error`**(node-pg 的断连在这一形),按整句相等认。
+ *
+ * **不在识别集里**(认不出一律不是 —— 错判成连接类的代价是调用方被劝「再试」去撞一个注定失败的语句):
+ *  · 语句级的错:唯一键冲突、CHECK 被拒、缺表缺列、语法错、权限错、行 / 包超墙(1153 / 8025 / `54000`);
+ *  · 死锁(引擎的仲裁产物,重试的前提在调用方的整事务重来,见 {@link isDeadlockError})与锁等待 / 语句超时(延迟信号,重试只把长等待乘上次数);
+ *  · 认证类拒连(MySQL 1045、PG `28xxx`、`08004`:凭据 / 白名单要人去改)与协议违例(PG `08P01`、mysql2 `PROTOCOL_ERROR`:我方的码病);
+ *  · TiDB 自己的忙 / 区域不可用(9001 / 9005 一族)—— 候真库逐码读数再登,今天不在表里(登记在案的未收项);
+ *  · 池已被我方关闭(`Pool is closed.` / `Cannot use a pool after calling end on the pool`):那是本进程在收摊,不是库的事。
+ * 只看被抛出的**这一只**对象(不沿 `cause` 链往下找):店层把驱动错包进自己的类时,包它的那一层要不要继承连接类,归那一层的契约说,不在这里猜。
+ */
+export declare const CONNECTION_FAULT_ERRORS: ReadonlyArray<{
+    readonly code: string;
+    readonly errno?: number;
+    readonly why: string;
+}>;
+/**
+ * 驱动**自己抛的、不带 `code` 的裸 `Error`** 的整句 —— 连接类故障的第三种归因键。node-pg 的断连 / 池连接超时就是这一形(`new Error('Connection terminated unexpectedly')`,
+ * 没有任何结构化字段可读),mysql2 的「连接已关闭」同形。**整句相等**才认(不是 `includes`):一句夹着用户路径 / 数据的散文伪造不出驱动句;且只认 `code` 缺席的 `Error`。
+ * 每一行的 `source` 是它在驱动源码里的出处文件,`test/store-fault-judge.test.ts` 读已装驱动的源码核句子仍在(驱动升级改了句子 ⇒ 红,而不是判官悄悄静音)。
+ */
+export declare const CONNECTION_FAULT_DRIVER_SENTENCES: ReadonlyArray<{
+    readonly sentence: string;
+    readonly source: string;
+    readonly why: string;
+}>;
+/**
+ * 「这个错误**是**连接类故障吗」—— {@link CONNECTION_FAULT_ERRORS} 的唯一判据(识别集与排除项见该表头注)。纯谓词、不抛;认不出的一律不是。
+ * 归因键三种:`code`(字符串)、`errno`(数字)、无 `code` 的驱动裸 `Error` 的整句 —— 只读被抛出的这一只对象身上的结构化字段 / 整句,**不读散文里的在册词**。
+ */
+export declare function isConnectionFaultError(err: unknown): boolean;
 /**
  * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
  * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。

package/dist/plugins/sql-errors.js

@@ -64,7 +64,7 @@ export function rowTooLargeWallOf(dialect, err) {
 export const MYSQL_CONNECTION_UNUSABLE_ERRORS = [
     { errno: 1053, code: "ER_SERVER_SHUTDOWN" },
     { errno: 1152, code: "ER_ABORTING_CONNECTION" },
-    { errno: 1153, code: "ER_NET_PACKET_TOO_LARGE" },
+    { errno: 1153, code: "ER_NET_PACKET_TOO_LARGE", statementRefusal: true },
     { errno: 1158, code: "ER_NET_READ_ERROR" },
     { errno: 1159, code: "ER_NET_READ_INTERRUPTED" },
     { errno: 1160, code: "ER_NET_ERROR_ON_WRITE" },
@@ -82,6 +82,54 @@ export function isConnectionUnusableError(err) {
     const code = keyOf(err, "code");
     return (typeof errno === "number" && UNUSABLE_ERRNOS.has(errno)) || (typeof code === "string" && UNUSABLE_CODES.has(code));
 }
+export const CONNECTION_FAULT_ERRORS = [
+    { code: "ECONNRESET", why: "对端重置了连接(库重启 / 代理断流 / 空闲连接被回收)" },
+    { code: "ECONNREFUSED", why: "库此刻不接连接(进程没起 / 端口没开 / 滚动重启中)" },
+    { code: "ECONNABORTED", why: "连接在建立或使用中被本机协议栈中止" },
+    { code: "EPIPE", why: "写一条对端已经关掉的连接" },
+    { code: "ETIMEDOUT", why: "连接 / 套接字超时(mysql2 的 `connectTimeout` 同答此码)" },
+    { code: "EHOSTUNREACH", why: "到库的主机不可达(路由 / 节点切换)" },
+    { code: "ENETUNREACH", why: "到库的网络不可达" },
+    { code: "EAI_AGAIN", why: "DNS 临时失败(「稍后再试」是它自己的定义)" },
+    { code: "PROTOCOL_CONNECTION_LOST", why: "mysql2:服务端关了连接(`Connection lost: The server closed the connection.`,带 `fatal: true`)" },
+    { code: "ER_CON_COUNT_ERROR", errno: 1040, why: "连接数满(`Too many connections`)—— 别人放连接之后就好" },
+    { code: "08000", why: "PG connection_exception" },
+    { code: "08001", why: "PG sqlclient_unable_to_establish_sqlconnection" },
+    { code: "08003", why: "PG connection_does_not_exist" },
+    { code: "08006", why: "PG connection_failure" },
+    { code: "57P01", why: "PG admin_shutdown(库被管理员关停 / 重启)" },
+    { code: "57P02", why: "PG crash_shutdown" },
+    { code: "57P03", why: "PG cannot_connect_now(启动 / 恢复中)" },
+    { code: "53300", why: "PG too_many_connections" },
+    { code: "25006", why: "PG read_only_sql_transaction(故障切换后落在只读节点)" },
+];
+export const CONNECTION_FAULT_DRIVER_SENTENCES = [
+    { sentence: "Connection terminated unexpectedly", source: "pg/lib/client.js", why: "node-pg:连接在使用中被对端关掉" },
+    { sentence: "Client has encountered a connection error and is not queryable", source: "pg/lib/client.js", why: "node-pg:这条 client 的连接已出错,后续语句直接拒" },
+    { sentence: "Connection terminated due to connection timeout", source: "pg-pool/index.js", why: "node-pg 池:建连超过 `connectionTimeoutMillis`" },
+    { sentence: "timeout exceeded when trying to connect", source: "pg-pool/index.js", why: "node-pg 池:排队等连接超过 `connectionTimeoutMillis`" },
+    { sentence: "Can't add new command when connection is in closed state", source: "mysql2/lib/base/connection.js", why: "mysql2:往一条已被对端关掉的连接上发语句(带 `fatal: true`、无 `code`)" },
+];
+const CONNECTION_FAULT_CODES = new Set([
+    ...CONNECTION_FAULT_ERRORS.map((r) => r.code),
+    ...MYSQL_CONNECTION_UNUSABLE_ERRORS.filter((r) => r.statementRefusal !== true).map((r) => r.code),
+]);
+const CONNECTION_FAULT_ERRNOS = new Set([
+    ...CONNECTION_FAULT_ERRORS.flatMap((r) => (r.errno === undefined ? [] : [r.errno])),
+    ...MYSQL_CONNECTION_UNUSABLE_ERRORS.filter((r) => r.statementRefusal !== true).map((r) => r.errno),
+]);
+const CONNECTION_FAULT_SENTENCES = new Set(CONNECTION_FAULT_DRIVER_SENTENCES.map((r) => r.sentence));
+export function isConnectionFaultError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const code = keyOf(err, "code");
+    const errno = keyOf(err, "errno");
+    if (typeof code === "string" && CONNECTION_FAULT_CODES.has(code))
+        return true;
+    if (typeof errno === "number" && CONNECTION_FAULT_ERRNOS.has(errno))
+        return true;
+    return err instanceof Error && code === undefined && CONNECTION_FAULT_SENTENCES.has(err.message);
+}
 export class StoreRowTooLargeError extends Error {
     row;
     wall;

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

@@ -0,0 +1,4 @@
+export type StoreFaultClass = "corrupt" | "connection" | "unclassified";
+/** 判官本体。纯函数、不抛;只看被抛出的这一只对象(不沿 `cause` 链找)。 */
+export declare function storeFaultClassOf(err: unknown): StoreFaultClass;
+//# sourceMappingURL=store-fault.d.ts.map

package/dist/plugins/store-fault.js

@@ -0,0 +1,8 @@
+import { isConnectionFaultError } from "./sql-errors.js";
+import { StoreCorruptError } from "./sql-json-column.js";
+export function storeFaultClassOf(err) {
+    if (err instanceof StoreCorruptError)
+        return "corrupt";
+    return isConnectionFaultError(err) ? "connection" : "unclassified";
+}
+//# sourceMappingURL=store-fault.js.map

package/dist/plugins/tidb-pool.js

@@ -86,7 +86,7 @@ export const SCHEMA_STATEMENTS = [
      placed_at                   DATETIME(3)  NULL,
      -- S-790 / S-506(design/330 §2):会话化身 —— 同一个会话 id 上**这一位住客**的不透明令牌。铸点只在新建行(register /
      -- 无 id 创建 / fork / 导入新行),删除随行消失,同 id 重登记铸新的;'' = 没铸过,读口响亮拒。列定义的唯一属主 =
-     -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库由一次性迁移 M5 用同一串补列 + 回填)。
+     -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由本建表语句生成)。
      -- 不上 wire、不进模型上下文、日志只打前 8 位。
      ${SESSION_META_INCARNATION_COLUMN.tidb},
      PRIMARY KEY (session_id),

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

@@ -54,7 +54,7 @@
  *    验证搜索配对不对。挂哪儿(boot 期一次性 warn / `/health` 子字段 / 显式端点)未定 ——
  *    注意 boot 期探活会给每次启动加一次出网,多租/离线部署要能关。
  */
-import { type UrlCredentialFacts } from "../url-credential.js";
+import { type UrlCredentialFacts } from "../url-credential-refusal.js";
 /**
  * Search providers this backend speaks —— **词表的唯一属主**(运行期与类型同一份)。
  * Absent `WEB_SEARCH_PROVIDER` ⇒ no backend ⇒ WebSearch is not assembled.

package/dist/plugins/web-search.js

@@ -1,8 +1,8 @@
 import { validateHeaderValue } from "node:http";
 import { createSearxngSearchBackend } from "@sema-agent/core";
-import { isHierarchicalUrl } from "@sema-agent/settings-schema";
+import { findUrlCredential, findUrlUserinfo, isHierarchicalUrl } from "@sema-agent/settings-schema";
 import { redactSecrets } from "../trace/redact.js";
-import { buildRequestUrlCredentialRefusal, findUrlCredential, findUrlUserinfo, urlCredentialFacts } from "../url-credential.js";
+import { buildRequestUrlCredentialRefusal, urlCredentialFacts } from "../url-credential-refusal.js";
 export const WEB_SEARCH_PROVIDERS = ["brave", "tavily", "searxng"];
 function isWebSearchProvider(word) {
     return WEB_SEARCH_PROVIDERS.includes(word);

package/dist/request-declaration-refusal.d.ts

@@ -0,0 +1,94 @@
+/**
+ * **请求体里「声明列表」(`mcpServers` · `a2aPeers`)这一类受理座的拒绝骨架** —— 列表级 / 条目级 / 键值级的拒形、拒句尾、撞帽机读位,在这里铸一处。
+ *
+ * ## 为什么在这里
+ * 两张列表是同一个问题的两个实例:调用方随请求带一份「我要挂这些外部服务」的声明,受理口要回答「这份声明能不能原样用」。答案的**形**一样 ——
+ *  ① **列表**:在场却不是数组 / 超过挂载上限 / 某一条不是对象 ⇒ `400 request.field_invalid`(整份拒而不是挂前 N 条 / 摘掉读不出的那条:一份被悄悄截短的声明,在发送方那里读起来是「生效了」);
+ *     超上限用撞帽的唯一铸点({@link limitRefusal}),拒体带机读位一组键(`field` · `reason:"over_cap"` · `count` · `cap`);
+ *  ② **键名**:条目层的词表外键 ⇒ `400 request.body_shape` + `unknownKeys`(句子由各座自己写 —— 受理键表与嵌套层是座位自己的事);
+ *  ③ **键值**:每个受理键一只判官 ⇒ `400 request.field_invalid`,句子 `<坐标>.<键路径> (<subject> "<名>") is not a usable declaration — <判官原因句>. …`,不回显值;
+ *     判官答「URL 带凭据」时拒体另带机读位 `field` / `reason`({@link urlCredentialFacts})。
+ * 第一处坏形即答:先列表、后条目;条目里先键名、后键值。各座只写**自己的**两件事:受理键表 + 键值判官表(以及它自己的词表外键句)。拒形、句尾、撞帽句不在座位文件里手拼 ——
+ * 两份手拼的拒形迟早分岔(`a2aPeers` 上线时就是缺了这一整套,坏形换回 200 + 运维 warn,调用方以为声明生效了)。
+ *
+ * ## 射程
+ * 纯值域、与租户车道无关;只在 fresh 提交腿上问(`boot/resolve-spec.ts` 的 `opts.leg`):重放存量 body 的腿走宽容读器,一个 4xx 打在 resume 上会永久砖死一条 parked 任务。
+ */
+import { type UrlCredential } from "@sema-agent/settings-schema";
+import { type LimitFacts } from "./limit-refusal.js";
+import { type UrlCredentialFacts } from "./url-credential-refusal.js";
+/** 一座声明列表的名字与上限、以及拒句里要用的称呼(座位的常量,铸点只读)。 */
+export interface DeclarationSeat {
+    /** 请求体里这张列表的键,也是机读坐标的根(`mcpServers` | `a2aPeers`)。 */
+    readonly list: string;
+    /** 挂载上限(条数;超过 ⇒ 撞帽拒)。 */
+    readonly cap: number;
+    /** 一条声明所声明的东西(拒句里的单数名词:`server` | `peer`)。 */
+    readonly subject: string;
+    /** 「一条声明」的整称(`an MCP server declaration`)。 */
+    readonly declaration: string;
+    /** 「多条声明」的整称(`MCP server declarations`)。 */
+    readonly declarations: string;
+}
+/** 一次拒绝:码 + 句 + 词表外的键名表(只在闭集那一形上在场)+ 机读位(撞帽 / URL 带凭据两形上在场)。受理口(同步 400)与探测口(`POST …/probe`)原样转述同一份。 */
+export interface DeclarationRefusal {
+    readonly errorCode: "request.body_shape" | "request.field_invalid";
+    readonly message: string;
+    /** 词表外的键,全路径形(已清洗 + 截长 + 排序 + 封顶)。 */
+    readonly unknownKeys?: readonly string[];
+    /** 撞帽:`field` · `reason:"over_cap"` · `count` · `cap`;URL 带凭据:`field` · `reason`(判官的拒因词)。 */
+    readonly facts?: UrlCredentialFacts | LimitFacts;
+}
+/** 一处键值坏形:键路径(相对条目)+ 判官的原因句;答「URL 带凭据」时另带判官的答案(⇒ 拒体带机读位)。 */
+export interface DeclarationKeyIssue {
+    readonly path: string;
+    readonly reason: string;
+    readonly credential?: UrlCredential;
+}
+/** 受理键 → 判官。`at` 是这一条的体内坐标(`a2aPeers[2]`),座位需要写绝对坐标的出路句时用。缺席(`undefined`)恒合法 = 真「没声明」;在场的 `null` 不是缺席。 */
+export type DeclarationKeyJudge<E extends Record<string, unknown> = Record<string, unknown>> = (entry: E, at: string) => DeclarationKeyIssue | undefined;
+/** 读不出名字的条目用的占位(非空:一条连名字都读不出的条目仍然要被说出来)。 */
+export declare const MALFORMED_NAME = "<malformed>";
+/** 条目的**申报名**(拿不到名字时的占位)—— 拒句、丢弃点、通告同读一只。 */
+export declare function declaredName(e: unknown): string;
+/** `name` 键的判官(两座同读:申报名线长界与首尾空白的唯一判官在契约包 {@link isUsableWireName})。 */
+export declare function declarationNameIssue(entry: Record<string, unknown>): DeclarationKeyIssue | undefined;
+/** 列表级拒句的收尾句:说清「为什么整份被拒、而不是只按读得出的那部分办」与出路(空列表 = 什么都不声明)。 */
+export declare const LIST_REFUSAL_TAIL: string;
+/** 列表级的一处坏形 → 拒(码恒 `request.field_invalid`)。`head` 只说位置与形的**种类**,不回显值。 */
+export declare function declarationListRefusal(head: string): DeclarationRefusal;
+/**
+ * 一处键值坏形**怎么被说出来**:体内坐标(`<条目坐标>.<键路径>`)+ 判官的原因句(只剥控制与双向字符,不回显值)。受理口的拒句与读器的丢弃因(请求腿运维 warn 的 `field` / `reason`)读**这一只** ——
+ * 原因只来自判官表,组句只在这里(两边各写一份,迟早分岔)。
+ */
+export declare function declarationIssueFacts(at: string, issue: DeclarationKeyIssue): {
+    readonly field: string;
+    readonly reason: string;
+};
+/**
+ * 列表条数撞帽**怎么被说出来**:坐标 = 列表键(`a2aPeers`)+ 撞帽铸点({@link limitRefusal})的头一句(`<列表> has N entries — at most M are accepted`)。受理口的撞帽拒句以同一句开头(接拒句尾),
+ * 读器的丢弃因读这一只 —— 与 {@link declarationIssueFacts} 同族:`reason` 只有一种内容 = 句子;机读词(`over_cap`)留在拒体的 `facts`,不进日志的 `reason`。
+ */
+export declare function declarationOverCapFacts(seat: DeclarationSeat, count: number): {
+    readonly field: string;
+    readonly reason: string;
+};
+/**
+ * 一条条目不是对象(`null` / 原始值 / 数组)的头一句:`<条目坐标> is <值的种类>, not <整称> (an object)`;是对象 ⇒ `undefined`。列表级拒({@link requestDeclarationRefusal})与读器的丢弃因读同一只,
+ * 「什么算对象」只在这里判。
+ */
+export declare function declarationEntryNotObject(seat: DeclarationSeat, entry: unknown, at: string): string | undefined;
+/** 一处键值坏形 → 拒。**所有键同一个形**;条目名过唯一的回显清洗,读不出名字的条目用占位,坐标与原因句由 {@link declarationIssueFacts} 铸。 */
+export declare function declarationFieldRefusal(seat: DeclarationSeat, entry: Record<string, unknown>, at: string, issue: DeclarationKeyIssue): DeclarationRefusal;
+/** 一条条目的键值判官表按受理键序问一遍,第一处坏形即返回。 */
+export declare function judgeDeclarationKeys<K extends string, E extends Record<string, unknown>>(seat: DeclarationSeat, entry: E, at: string, keys: readonly K[], judges: {
+    readonly [P in K]: DeclarationKeyJudge<E>;
+}): DeclarationRefusal | undefined;
+/**
+ * 一张声明列表「能不能原样用」的回答者骨架:列表级(缺席 / `null` ⇒ 没声明;不是数组 / 超上限 / 条目不是对象)在这里,条目级交座位的 `judgeEntry`(词表外的键 → 键值)。
+ * `undefined` = 能原样用(或没声明;各门自己定缺席的意思)。
+ */
+export declare function requestDeclarationRefusal(seat: DeclarationSeat, list: unknown, judgeEntry: (entry: Record<string, unknown>, at: string) => DeclarationRefusal | undefined): DeclarationRefusal | undefined;
+/** 受理口的转述:有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` / 机读位原样);没有 ⇒ 什么也不做。 */
+export declare function throwDeclarationRefusal(refusal: DeclarationRefusal | undefined): void;
+//# sourceMappingURL=request-declaration-refusal.d.ts.map

package/dist/request-declaration-refusal.js

@@ -0,0 +1,78 @@
+import { describeBadWireName, describeValueShape, isUsableWireName, stripControlAndBidi } from "@sema-agent/settings-schema";
+import { createCodedHttpError } from "./security.js";
+import { limitRefusal } from "./limit-refusal.js";
+import { echoKeyName } from "./request-key-closure.js";
+import { urlCredentialFacts } from "./url-credential-refusal.js";
+export const MALFORMED_NAME = "<malformed>";
+export function declaredName(e) {
+    return e && typeof e === "object" && typeof e.name === "string" && e.name !== ""
+        ? String(e.name)
+        : MALFORMED_NAME;
+}
+export function declarationNameIssue(entry) {
+    return isUsableWireName(entry.name) ? undefined : { path: "name", reason: `must be a non-empty string within the wire-name length bound — got ${describeBadWireName(entry.name)}` };
+}
+export const LIST_REFUSAL_TAIL = "The request is refused rather than acting on part of the list: declarations that silently did not apply would read as in effect to whoever sent them. " +
+    "Fix the list (an empty list declares none).";
+export function declarationListRefusal(head) {
+    return { errorCode: "request.field_invalid", message: `${head}. ${LIST_REFUSAL_TAIL}` };
+}
+function entryRefusalTail(subject) {
+    return (`The request is refused rather than mounting the ${subject} without it: a declaration that silently did not apply would leave the ${subject} running differently from what you declared. ` +
+        "Fix the entry (an optional key may also be omitted).");
+}
+export function declarationIssueFacts(at, issue) {
+    return { field: `${at}.${issue.path}`, reason: stripControlAndBidi(issue.reason) };
+}
+export function declarationOverCapFacts(seat, count) {
+    const capped = limitRefusal(seat.list, "entries", count, seat.cap);
+    return { field: capped.facts.field, reason: capped.message };
+}
+export function declarationEntryNotObject(seat, entry, at) {
+    return entry === null || typeof entry !== "object" || Array.isArray(entry) ? `${at} is ${describeValueShape(entry)}, not ${seat.declaration} (an object)` : undefined;
+}
+export function declarationFieldRefusal(seat, entry, at, issue) {
+    const name = echoKeyName("", declaredName(entry));
+    const { field, reason } = declarationIssueFacts(at, issue);
+    return {
+        errorCode: "request.field_invalid",
+        message: `${field} (${seat.subject} "${name}") is not a usable declaration — ${reason}. ${entryRefusalTail(seat.subject)}`,
+        ...(issue.credential === undefined ? {} : { facts: urlCredentialFacts(`${at}.${issue.path}`, issue.credential) }),
+    };
+}
+export function judgeDeclarationKeys(seat, entry, at, keys, judges) {
+    for (const key of keys) {
+        const issue = judges[key](entry, at);
+        if (issue !== undefined)
+            return declarationFieldRefusal(seat, entry, at, issue);
+    }
+    return undefined;
+}
+export function requestDeclarationRefusal(seat, list, judgeEntry) {
+    if (list === undefined || list === null)
+        return undefined;
+    if (!Array.isArray(list))
+        return declarationListRefusal(`${seat.list} is ${describeValueShape(list)}, not an array of ${seat.declarations}`);
+    if (list.length > seat.cap) {
+        const capped = limitRefusal(seat.list, "entries", list.length, seat.cap, { tail: LIST_REFUSAL_TAIL });
+        return { errorCode: "request.field_invalid", message: capped.message, facts: capped.facts };
+    }
+    for (let i = 0; i < list.length; i++) {
+        const entry = list[i];
+        const at = `${seat.list}[${i}]`;
+        const notObject = declarationEntryNotObject(seat, entry, at);
+        if (notObject !== undefined)
+            return declarationListRefusal(notObject);
+        const refusal = judgeEntry(entry, at);
+        if (refusal !== undefined)
+            return refusal;
+    }
+    return undefined;
+}
+export function throwDeclarationRefusal(refusal) {
+    if (refusal === undefined)
+        return;
+    const extra = { ...(refusal.unknownKeys === undefined ? {} : { unknownKeys: [...refusal.unknownKeys] }), ...(refusal.facts ?? {}) };
+    throw createCodedHttpError(400, refusal.errorCode, refusal.message, Object.keys(extra).length === 0 ? undefined : extra);
+}
+//# sourceMappingURL=request-declaration-refusal.js.map

package/dist/request-image-urls.d.ts

@@ -0,0 +1,6 @@
+import { type UrlCredentialRefusal } from "./url-credential-refusal.js";
+/** 请求体 `images` 的 URL 座:任一条目的串值 `url` 带凭据 ⇒ 拒(整句 + 机读位),列表序第一处即答;没有 ⇒ `undefined`。`images` 不是数组 / 缺席 ⇒ `undefined`(形归受理口别的门)。 */
+export declare function requestImageUrlRefusal(images: unknown): UrlCredentialRefusal | undefined;
+/** fresh 提交腿的 `images` URL 门:{@link requestImageUrlRefusal} 有答案 ⇒ 同步 400(码 / 句 / 机读位原样)。 */
+export declare function assertRequestImageUrls(bodyImages: unknown): void;
+//# sourceMappingURL=request-image-urls.d.ts.map

package/dist/request-image-urls.js

@@ -0,0 +1,27 @@
+import { createCodedHttpError } from "./security.js";
+import { findUrlCredential } from "@sema-agent/settings-schema";
+import { buildRequestUrlCredentialRefusal } from "./url-credential-refusal.js";
+function inlineImageExit(at) {
+    return `${at} can carry the image bytes inline: send { "data": <base64>, "mimeType": "image/png" | "image/jpeg" | "image/gif" | "image/webp" } instead of a URL that holds the credential`;
+}
+export function requestImageUrlRefusal(images) {
+    if (!Array.isArray(images))
+        return undefined;
+    for (const [i, image] of images.entries()) {
+        if (image === null || typeof image !== "object")
+            continue;
+        const url = image.url;
+        const found = typeof url === "string" ? findUrlCredential(url) : undefined;
+        if (found === undefined)
+            continue;
+        const at = `images[${i}]`;
+        return buildRequestUrlCredentialRefusal(`${at}.url`, found, inlineImageExit(at));
+    }
+    return undefined;
+}
+export function assertRequestImageUrls(bodyImages) {
+    const refusal = requestImageUrlRefusal(bodyImages);
+    if (refusal !== undefined)
+        throw createCodedHttpError(400, "request.field_invalid", refusal.message, refusal.facts);
+}
+//# sourceMappingURL=request-image-urls.js.map

package/dist/request-key-closure.d.ts

@@ -17,6 +17,11 @@ export declare function scanKeyClosure(bag: object, prefix: string, accepted: Re
     unknown: string[];
     unsupported: string[];
 }): void;
+/** {@link scanKeyClosure} 的名字形:键名已经由调用方读成一张表(请求入口的快照只带词表外的键**名**,值不读),分拣规则同一条。 */
+export declare function scanKeyNames(names: readonly string[], prefix: string, accepted: ReadonlySet<string>, tolerated: ReadonlySet<string>, into: {
+    unknown: string[];
+    unsupported: string[];
+}): void;
 /** 一张分类表的文案片段(封顶后只报数)。 */
 export declare function keyClosureClause(names: string[], label: string): string;
 /**

package/dist/request-key-closure.js

@@ -5,7 +5,10 @@ export function echoKeyName(prefix, key) {
     return `${prefix}${echoCallerText(key)}`;
 }
 export function scanKeyClosure(bag, prefix, accepted, tolerated, into) {
-    for (const k of Object.keys(bag)) {
+    scanKeyNames(Object.keys(bag), prefix, accepted, tolerated, into);
+}
+export function scanKeyNames(names, prefix, accepted, tolerated, into) {
+    for (const k of names) {
         if (accepted.has(k))
             continue;
         (tolerated.has(k) ? into.unsupported : into.unknown).push(echoKeyName(prefix, k));

package/dist/runtime-caps-resolver.js

@@ -95,7 +95,7 @@ export function createPrincipalEntitlementsClient(opts) {
         center: { baseUrl: opts.center.baseUrl, credential },
         cache: new Map(),
         inflight: new Map(),
-    }));
+    })).now;
     const readMintedDeny = new WeakSet();
     const MAX_CACHE = 10_000;
     const putCache = (cache, key, entry) => {

package/dist/sandbox-pkg-source.d.ts

@@ -1,4 +1,31 @@
-import { type UrlCredential } from "./url-credential.js";
+/**
+ * RFC B5/B4 抽象点② (sema-internal server/docs/design/ENV-SELECT-AND-REGION-SOURCE.md): the deployment-region package-source →
+ * sandbox env derivation. ENV-FIRST: pod/sandbox env OVERRIDES the image's baked `ENV` (k8s container env wins
+ * over image config and is visible to every exec'd process; e2b sandboxEnv likewise) — so the env-overridable
+ * ecosystem pieces (pip/uv/npm/corepack/go/rustup/flutter/playwright/nuget) switch region on EXISTING images,
+ * no rebake needed. Only the file-bound pieces (apt sources, /etc/gemrc, composer global config, cargo
+ * config.toml) still need the in-image `pkg-source.sh` hook (rebaked images; bake prep chowns those files).
+ *
+ * Profiles:
+ *   cn      → inject only the SEMA_PKG_SOURCE marker (the pool's images bake the CN set as their defaults).
+ *   global  → official endpoints for every env-overridable ecosystem (overrides the baked CN ENV values).
+ *   custom  → SEMA_* explicit URLs (from the service process env) forwarded verbatim + mapped onto the same
+ *             ecosystem variables where a mapping is unambiguous (apt has no env form — hook-only).
+ *
+ * The marker `SEMA_PKG_SOURCE` always rides along: the image's pkg-source.sh hook (pod-start / profile.d)
+ * materializes the file-bound pieces from it; images without the hook simply ignore it.
+ *
+ * ## One law: no URL that rides into the model-visible sandbox env carries a credential
+ * Everything this module derives lands in the env of every sandbox process — including the ones the model drives
+ * (`env`, `printenv`) — so `https://user:pass@mirror/…` or `https://mirror/simple?token=…` among the `custom` addresses would
+ * hand the deployment's package-source credential to the model. {@link customPkgSourceFromEnv} is the ONE reader of the six
+ * addresses and the one place that judges them, in two questions: the shape (the shared URL-shape judge `httpUrlFlaws`, the same
+ * one MEMORY_EMBEDDER_ENDPOINT / A2A_SERVE_URL answer to, plus this seat's backslash rule) and the credential (the shared
+ * credential judge `findUrlCredential` — userinfo, or a query / fragment parameter named in the log redactor's credential-name
+ * table; the request-face MCP `transport.url` answers to the same judge). Either says no ⇒ it throws, startup refuses. Never
+ * stripped, never rewritten, never forwarded quietly. The request face has no package-source address key at all (deployment face only).
+ */
+import { type UrlCredential } from "@sema-agent/settings-schema";
 /** Explicit URLs for `custom` (RFC B: 极端情况出口). Read from the service process env (operator-trusted). */
 export interface CustomPkgSource {
     aptMirror?: string;

package/dist/sandbox-pkg-source.js

@@ -1,6 +1,5 @@
-import { httpUrlFlaws } from "@sema-agent/settings-schema";
+import { findUrlCredential, httpUrlFlaws } from "@sema-agent/settings-schema";
 import { buildHttpUrlRefusal, buildUrlCredentialRefusal } from "./url-refusal.js";
-import { findUrlCredential } from "./url-credential.js";
 const GLOBAL_ENV = {
     PIP_INDEX_URL: "https://pypi.org/simple",
     UV_DEFAULT_INDEX: "https://pypi.org/simple",

package/dist/sealed-key.d.ts

@@ -54,6 +54,25 @@ export declare function projectSealedKeyCapability(face: SealedKeyPublicFace | u
 /** Default id = fingerprint of the RAW public-key bytes: `exec-<sha256(pk)[0..12) hex>`.
  *  Deterministic → regenerating the id from the same key file is stable across boots. */
 export declare function deriveKeyId(publicKeyRaw: Uint8Array): string;
+/** {@link judgeSealedKeyPublicKey} 的拒因(闭集)。 */
+export type SealedKeyPublicKeyFlaw = "non_canonical_base64" | "bad_length" | "small_order";
+/** 公钥判官的拒(类型化;`flaw` 闭集)。公钥是公开材料,句子里点名它无妨;从不带私钥 / 密文。 */
+export declare class SealedKeyPublicKeyRefusedError extends Error {
+    readonly flaw: SealedKeyPublicKeyFlaw;
+    constructor(flaw: SealedKeyPublicKeyFlaw);
+}
+/**
+ * **X25519 公钥的唯一判官** —— 保管店装载({@link ensureSealedKeyStore},每份钥匙文件)、向中心登记({@link reportExecutionPublicKey})、
+ * 封之前({@link createCheckpointCtxSealing},对着最新那把)三处同读这一只;过了交回原始 32 字节,不过抛 {@link SealedKeyPublicKeyRefusedError}。
+ *  1. **规范 base64**:解出来的字节再编码回去必须逐字等于原串 —— 一句话盖住字母表、补齐、填充位三件(一把钥匙只有一种写法);
+ *  2. **32 字节**;
+ *  3. **不是小阶点**:对 {@link SMALL_ORDER_PROBE_SCALAR} 做 `crypto_scalarmult`,结果全零 ⇔ 小阶(libsodium 此时不交结果、抛 `weak public key`)。
+ * 判法取「标量乘结果全零」而不是手抄小阶点表:与 noble 同一判(`x25519.getSharedSecret` 零结果即抛,包侧 `bad_public_key` 读的就是它)、
+ * 就是 RFC 7748 §6.1 要求的那一检;非规范编码(p、p+1)与第 255 位置位的写法由 X25519 自己的约化 / 掩位盖住,不必逐个列;
+ * 高位别名(第 255 位置位、掩掉后是同一个非小阶点)照收 —— 两边同口径。依赖已在树里(libsodium),不新增一张要人维护的表。
+ * 前置:libsodium 已就绪(三处调用方都先等过它);没就绪 ⇒ 当场抛普通错误(不是判决)。
+ */
+export declare function judgeSealedKeyPublicKey(publicKeyB64: string): Uint8Array;
 /**
  * Load every keypair under `dir` (creating dir + ONE fresh keypair when none exist) and return the
  * custody store. Invalid/corrupt files are skipped with a warn (they may be an OLD format or a

package/dist/sealed-key.js

@@ -27,6 +27,37 @@ function b64ToBytes(b64, what) {
         throw new Error(`${what}: not valid base64`);
     return new Uint8Array(Buffer.from(b64, "base64"));
 }
+export class SealedKeyPublicKeyRefusedError extends Error {
+    flaw;
+    constructor(flaw) {
+        super(`sealed-key public key refused (${flaw}): ${SEALED_KEY_PUBLIC_KEY_FLAW_TEXT[flaw]}`);
+        this.name = "SealedKeyPublicKeyRefusedError";
+        this.flaw = flaw;
+    }
+}
+const SEALED_KEY_PUBLIC_KEY_FLAW_TEXT = {
+    non_canonical_base64: "not the canonical standard-base64 spelling of 32 bytes (alphabet A-Z a-z 0-9 + /, `=` padding, zero padding bits)",
+    bad_length: "does not decode to 32 bytes",
+    small_order: "an X25519 small-order point — anything sealed against it can be opened without the private key",
+};
+const SMALL_ORDER_PROBE_SCALAR = new Uint8Array(32).fill(7);
+export function judgeSealedKeyPublicKey(publicKeyB64) {
+    const sodium = _sodium;
+    if (typeof sodium.crypto_scalarmult !== "function")
+        throw new Error("judgeSealedKeyPublicKey: libsodium is not initialized — await its ready promise first");
+    const bytes = new Uint8Array(Buffer.from(publicKeyB64, "base64"));
+    if (Buffer.from(bytes).toString("base64") !== publicKeyB64)
+        throw new SealedKeyPublicKeyRefusedError("non_canonical_base64");
+    if (bytes.length !== sodium.crypto_box_PUBLICKEYBYTES)
+        throw new SealedKeyPublicKeyRefusedError("bad_length");
+    try {
+        sodium.crypto_scalarmult(SMALL_ORDER_PROBE_SCALAR, bytes);
+    }
+    catch {
+        throw new SealedKeyPublicKeyRefusedError("small_order");
+    }
+    return bytes;
+}
 export async function ensureSealedKeyStore(dir, logger) {
     await _sodium.ready;
     const sodium = _sodium;
@@ -40,9 +71,9 @@ export async function ensureSealedKeyStore(dir, logger) {
             if (raw.alg !== SEALED_KEY_ALG || typeof raw.publicKey !== "string" || typeof raw.privateKey !== "string" || typeof raw.publicKeyId !== "string") {
                 throw new Error("missing/unsupported fields");
             }
-            const publicKey = b64ToBytes(raw.publicKey, "publicKey");
+            const publicKey = judgeSealedKeyPublicKey(raw.publicKey);
             const privateKey = b64ToBytes(raw.privateKey, "privateKey");
-            if (publicKey.length !== sodium.crypto_box_PUBLICKEYBYTES || privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
+            if (privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
                 throw new Error("bad key length");
             if (name !== `${raw.publicKeyId}.json`)
                 logger?.warn("sealed_key_filename_drift", { file: name, publicKeyId: raw.publicKeyId, note: "content publicKeyId wins; rename the file to silence this" });
@@ -53,7 +84,7 @@ export async function ensureSealedKeyStore(dir, logger) {
             keys.set(raw.publicKeyId, { publicKey, privateKey, publicKeyB64: raw.publicKey, createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "" });
         }
         catch (err) {
-            logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
+            logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : {}), note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
         }
     }
     if (keys.size === 0) {
@@ -101,7 +132,7 @@ export function createCheckpointCtxSealing(store) {
     if (typeof sodium.crypto_box_seal !== "function")
         throw new Error("createCheckpointCtxSealing: libsodium is not initialized — build the store with ensureSealedKeyStore() first");
     const { publicKeyId } = store.latest;
-    const publicKey = b64ToBytes(store.latest.publicKey, "publicKey");
+    const publicKey = judgeSealedKeyPublicKey(store.latest.publicKey);
     const sealing = createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey);
     const probeSession = "sealed-key-self-test";
     let roundTrip;
@@ -144,6 +175,18 @@ function createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey) {
 }
 export async function reportExecutionPublicKey(opts) {
     const { baseUrl, adminToken, key, notes, logger } = opts;
+    await _sodium.ready;
+    try {
+        judgeSealedKeyPublicKey(key.publicKey);
+    }
+    catch (err) {
+        logger?.warn("sealed_key_public_key_refused", {
+            publicKeyId: key.publicKeyId,
+            ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : { errKind: err instanceof Error ? err.name : "unknown" }),
+            note: "this public key is not registered with the center and not printed for manual registration — fix or remove the key file in the sealed-key directory and restart",
+        });
+        return;
+    }
     const manual = (why) => {
         logger?.warn("sealed_key_public_key", {
             publicKeyId: key.publicKeyId,