@sema-agent/server 7.131.0 → 7.132.0

package/dist/server-secret-env.d.ts

@@ -10,7 +10,12 @@
  *
  * ## 律(一句;core #1753 定,本仓只传事实、不判)
  * 本包任何进程在宿主上 spawn 的子进程:env = 引擎 `inheritedHostEnv(policy, findings)` ∪ 部署方点名放回的键(只在运维真可能要传东西的腿上有旋钮),
- * 剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕;git 腿再叠 git 自己的两件({@link gitSubprocessEnv})。三个继承词只在引擎一处判:
+ * 剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕(现场按**腿**命名);git 腿再叠 git 自己的两件({@link gitSubprocessEnv})。射程 = **每一条**宿主腿:
+ * src 里每一只值引 `node:child_process` 的文件都是登记腿、其中每一次起子进程都显式交组合出的 env(普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
+ * 腿的继承词是调用点的事实,按「子进程里跑的是谁选的代码」定:模型命令(host shell,交任务自己的词)/ 仓里的钩子与凭据助手(三条 git 腿)/ 执行仓代码的
+ * 语言服务器 / 配方脚本 ⇒ 形状剥 `"scrub"`;请求带来的 settings hooks 命令 ⇒ 严格名单(引擎的 `[names]` 臂);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
+ * 在容器 / 设备里跑、那边的 env 由 `-e` 显式给)⇒ `"all"` —— 只扣本服务自有凭据,CLI 与它的凭据助手 / 插件要读的生态变量照交(形状剥会剥
+ * `ADB_VENDOR_KEYS` / `AWS_SECRET_ACCESS_KEY` 一类,实测)。三个继承词只在引擎一处判:
  *  · `"all"` = 整份环境 **减** 本进程声明的自有凭据名;`"scrub"`(缺省)= 形状剥 ∪ 该名单;`[names]` = 严格白名单,点到名单中的名 ⇒ 引擎响亮拒
  *    (`inheritEnvPolicyProblem`:构造时与 spawn 时两格都拒,拒句带名;本仓不自判 withheld、不留第二读法)。
  *  · 名单 = 配置目录(`config-catalog.ts`)全部 `type:"secret"` 名 ∪ 名单型旋钮名(`env-name-allowlist-knobs.ts`,其原文可能夹着被错展开的令牌)∪ **生效配置
@@ -23,17 +28,21 @@
  *    抛同路)。能力词 `inherit_env.own_credentials_withheld` 在本进程的事实 =
  *    {@link ownCredentialsWithheld}:最近一次成功声明的集合 ⊇ 当前生效配置应声明的集合(活配置经 {@link bindOwnCredentialsConfig} 在 `loadConfig()` 之后绑一次;
  *    未绑 / 未声明 ⇒ false,事实读不到应声明集合就不答 true)。
- *  · 调用方显式传入的 env(`cfg.env` / 单次命令的 `env` / 语言服务器与沙箱的点名放回)不是继承,照旧原样叠在组合结果之上 —— 那是适配器自己的凭据通道。
- * 各腿只调 {@link hostSubprocessEnv} / {@link gitSubprocessEnv} —— 不许再有内联拼装、不许再有 `{ ...process.env }`、不许本仓再判任何一个继承词
- * (类级门在 `test/secret-env-scrub-host-legs.test.ts`)。
+ *  · **值臂**(core 7.52.0 #1754):声明是一张表 `{ names, values }`。`values` = 本进程持有凭据的变量此刻的值(目录 secret 名 ∪ 模型条目 `apiKeyEnv`,{@link serverCredentialValueSources}),
+ *    逐个交给引擎的同一只判;引擎判「不是凭据值」的那一个不扣、名照扣、不拒启、点名一次。能力词 `inherit_env.own_credential_values_withheld` 的事实 = {@link ownCredentialValuesWithheld}(位真 ⇔ 值臂真扣)。
+ *  · 调用方显式传入的 env(`cfg.env` / 单次命令的 `env` / 沙箱的点名放回)不是继承,照旧原样叠在组合结果之上 —— 那是适配器自己的凭据通道。
+ * 各腿只调 {@link hostSubprocessEnv} / {@link gitSubprocessEnv} —— 不许再有内联拼装、不许再有 `{ ...process.env }`、不许本仓再判任何一个继承词、不许起子进程不交 env
+ * (类级门与普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
  *
  * ## 点名放行(S-699 / S-713,一只谓词各处用)
- * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给子进程」的唯一实现。调用:{@link hostSubprocessEnv}(剥后放回形:
- * 本地语言服务器的 `LSP_ENV_ALLOW`、bake-runner 的 `BAKE_ENV_ALLOW`)、沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` / `K8S_SANDBOX_ENV`(`config.ts`)。
+ * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给沙箱」的唯一实现。调用:沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` /
+ * `K8S_SANDBOX_ENV`(`config.ts`)与名单解析器的「在不在」判。宿主子进程的剥后放回(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)不经它 —— 那是引擎的严格名单臂(上一段)。
  * host shell 的 `inheritEnv:[names]`(hermetic 形)7.129.0 起由引擎读(与 core `NodeExecutionEnv` 同名选项同义,点到自有凭据名即拒),不经本谓词。
  * 名单型旋钮的**名单**另由 `config.ts` 的同一只解析器 `parseEnvNameAllowlist` 判形(形错拒启 / 源里没有的名按序号 warn),本函数只管取值。
  * 「点名」在各处同义:点到的键原样带值(空串值照带),密钥形也照过(点名 = 部署方显式承担);源里没有的名不产生条目。
- * ⚠️ 已知边界(不在本函数修):`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW` 点到自有凭据名会把它放回语言服务器 / 配方脚本(剥后放回形在引擎的减法之上);解析器今天只拒名单型旋钮名。
+ * 剥后放回形(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)的放回本身也经引擎:{@link composeHostSubprocessEnv} 把名单交引擎的严格名单臂(`inheritedHostEnv([names])`)叠在
+ * 继承结果之上 ⇒ 点到本服务自有凭据名 = 引擎抛(spawn 时;起服时解析器 `parseEnvNameAllowlist` 按表列 `channel` 已用同一只判 `inheritEnvPolicyProblem` 拒过),
+ * 点到的变量值是本服务凭据的副本 = 引擎扣下。本仓不另判。
  */
 import { type InheritEnvPolicy, type SecretEnvFinding } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
@@ -48,27 +57,44 @@ export type ModelApiKeyEnvTable = Readonly<Record<string, string>>;
  */
 export declare function serverWithheldEnvNames(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 🔴 **唯一声明点**:把本进程自有凭据名向引擎声明(core `declareWithheldEnv`;重声明即替换,从下一次 spawn 起生效)。`modelApiKeyEnv` = 这一次要并进名单的模型条目表
- * (起服第一步 = 空表;换代 = 候选表),名单 = 此前声明过的 ∪ 这张表的应声明集合 —— 名单只随**落地**的世代增长:落地过的名不再退出(改名 / 删条目之后它的值仍在
- * 本进程 env 里),没落地的候选不留痕(旧世代在 CAS 处就拒、不到这里;换装拒 ⇒ {@link withdrawServerWithheldEnv})。引擎对坏形名 / 运行时回填名(`PATH` / `HOME` /
- * `USER` …)响亮抛且声明保持原状 —— 本函数不接住:起服那次抛 = 拒启;换代那次抛 = 候选整拒(`applyEffective` 抛,与 stage 抛同路)。返回声明的名单(只名、不值)。
+ * 本进程**持有凭据值**的变量名(值臂的来源;core 7.52.0 #1754):目录 secret 名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少名单型旋钮名(它们的值是
+ * 一张变量名单,不是凭据)。纯函数,排序只为读数稳定。
+ */
+export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
+/**
+ * 🔴 **唯一声明点**:把本进程自有凭据向引擎声明(core 7.52.0 `declareWithheldEnv({ names, values })`;重声明即整表替换,从下一次 spawn 起生效)。`modelApiKeyEnv` = 这一次要并进的
+ * 模型条目表(起服第一步 = 空表;换代 = 候选表)。两臂都只随**落地**的世代增长(落地过的名 / 值来源不退出:本进程 env 是 boot 期输入;没落地的候选不留痕 ——
+ * 换装拒 ⇒ {@link withdrawServerWithheldEnv})。
+ *  · **名臂**:此前声明过的 ∪ 这张表的 {@link serverWithheldEnvNames}。引擎对坏形名 / 运行时回填名(`PATH` / `HOME` …)响亮抛且声明保持原状 —— 本函数不接住:
+ *    起服那次抛 = 拒启;换代那次抛 = 候选整拒(`applyEffective` 抛,与 stage 抛同路)。第一次交表带着名臂与**此前已收下的值**(引擎收过、env 不变 ⇒ 同值照收),
+ *    所以这一次抛只可能是名的问题。
+ *  · **值臂**:{@link serverCredentialValueSources} 的每一个变量此刻在 env 里的值,逐个交给引擎**同一只**判(不另写「什么算凭据值」的第二份判据):引擎收下 ⇒ 记进值臂;
+ *    引擎拒(不是凭据值:空白 / 占位词 / 一个字符重复 / 不足 8 字符;或它是每个子进程都会拿到的变量的值)⇒ 这一个值不扣、名照扣、**不拒启**(与引擎自己的收值口
+ *    `holdOwnCredentialValues` 同一姿势:不收 + 说一次),`console.warn` 点名那个变量一次(引擎的拒句从不回显值;本句也不),能力位 `inherit_env.own_credential_values_withheld`
+ *    因此答 false(位真 ⇔ 值臂真扣)。引擎拒一个值时声明保持上一份,所以逐个交表的中间态都是上一份的超集。
+ * 返回声明的名单(只名、不值)。
  */
 export declare function declareServerWithheldEnv(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 席位拒 ⇒ 撤回最近一次声明(回到它之前的集合):`applyEffective` 在 Runner 换装抛时调,紧跟着那一次 {@link declareServerWithheldEnv} —— 没落地的候选不留痕。
- * 退回去的集合是引擎之前接受过的(判名确定)⇒ 不抛;连撤两次是同一个结果(幂等)。
+ * 席位拒 ⇒ 撤回最近一次声明(两臂一起回到它之前的那一份):`applyEffective` 在 Runner 换装抛时调,紧跟着那一次 {@link declareServerWithheldEnv} —— 没落地的候选不留痕。
+ * 退回去的那一份是引擎之前接受过的(名确定、值来源的值随 env 不变)⇒ 不抛;连撤两次是同一个结果(幂等)。
  */
 export declare function withdrawServerWithheldEnv(): void;
 /** 把活配置交给能力位读(stage-01 / run-local 在 `loadConfig()` 之后各一次;读的是 `config.modelApiKeyEnv` 这个**属性**,commit 整表重赋值之后看到的就是新表)。 */
 export declare function bindOwnCredentialsConfig(config: Pick<ServiceConfig, "modelApiKeyEnv">): void;
 /**
- * 能力词 `inherit_env.own_credentials_withheld` 在本进程的事实:最近一次成功声明的集合 ⊇ 当前生效配置应声明的集合。是一次比较,不是「声明过」的旗 ——
+ * 能力词 `inherit_env.own_credentials_withheld` 在本进程的事实:最近一次成功声明的名单 ⊇ 当前生效配置应声明的名单。是一次比较,不是「声明过」的旗 ——
  * 活表若被谁绕过声明写了新名,这里立刻 false(位不替流程担保)。没绑活配置 / 没声明过 ⇒ false(fail-closed)。
  */
 export declare function ownCredentialsWithheld(): boolean;
-/** 测试缝:撤回声明(引擎侧重声明为空)、忘掉声明集合(含撤回格)与活配置;生产代码从不调它。 */
+/**
+ * 能力词 `inherit_env.own_credential_values_withheld`(core 7.52.0)在本进程的事实:当前生效配置的每一个凭据值来源({@link serverCredentialValueSources}),只要它此刻在 env 里
+ * 有值,那个值都已交进值臂、被引擎收下。位真 ⇔ 值臂真扣:一个值被引擎判「扣不了」⇒ false;env 里没有值的来源没有东西可扣,不影响事实。没绑活配置 / 没声明过 ⇒ false。
+ */
+export declare function ownCredentialValuesWithheld(): boolean;
+/** 测试缝:撤回声明(引擎侧重声明为空表)、忘掉两份声明镜像、点名记账与活配置;生产代码从不调它。 */
 export declare function __resetServerWithheldEnvForTest(): void;
-/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;只有模型可驱动的 host shell 交非缺省词)、部署方点名放回的键。 */
+/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;按头注「腿的继承词」一条由调用点定)、部署方点名放回的键。 */
 export interface HostSubprocessEnvRequest {
     readonly site: SecretEnvScrubSite;
     readonly policy?: InheritEnvPolicy | undefined;
@@ -78,8 +104,8 @@ export interface HostSubprocessEnvRequest {
  * 🔴 **宿主子进程 env 的唯一组合**:{@link composeHostSubprocessEnv} + 留痕。**没有按原样交给子进程**的名字(剥掉的)经 `site` 留痕;点名放回的键取回源值,
  * 不是剥除,不计数、不披露。源 env 恒为本进程 env(引擎只读 `process.env`,本仓没有第二个源)。
  *
- * 六条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell(三个继承词原样交给 `policy`)、project-memory / center-plugins / leader 三条 git 腿、
- * 本地语言服务器、bake-runner 的每一只子进程组。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
+ * 九条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell(三个继承词原样交给 `policy`)、project-memory / center-plugins / leader 三条 git 腿、
+ * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(严格名单)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
  * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句);其余现场传 `[]`。
  * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。
  * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。

package/dist/server-secret-env.js

@@ -7,18 +7,42 @@ const NO_MODEL_ENTRIES = Object.freeze({});
 export function serverWithheldEnvNames(modelApiKeyEnv = NO_MODEL_ENTRIES) {
     return [...new Set([...CATALOG_SECRET_ENV_NAMES, ...ENV_NAME_ALLOWLIST_KNOB_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
 }
+export function serverCredentialValueSources(modelApiKeyEnv = NO_MODEL_ENTRIES) {
+    return [...new Set([...CATALOG_SECRET_ENV_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
+}
 let declared;
 let beforeLast;
+const valueRefusalAnnounced = new Set();
 let liveConfig;
+const envValueOf = (name) => process.env[name];
+const valuesOf = (sources) => [...sources].map(envValueOf).filter((v) => typeof v === "string" && v !== "");
 export function declareServerWithheldEnv(modelApiKeyEnv = NO_MODEL_ENTRIES) {
-    const names = [...new Set([...(declared ?? []), ...serverWithheldEnvNames(modelApiKeyEnv)])].sort();
-    declareWithheldEnv(names);
+    const names = [...new Set([...(declared?.names ?? []), ...serverWithheldEnvNames(modelApiKeyEnv)])].sort();
+    const kept = [...(declared?.valueSources ?? [])];
+    declareWithheldEnv({ names, values: valuesOf(kept) });
+    const valueSources = new Set(kept);
+    for (const source of serverCredentialValueSources(modelApiKeyEnv)) {
+        if (valueSources.has(source) || valuesOf([source]).length === 0)
+            continue;
+        try {
+            declareWithheldEnv({ names, values: valuesOf([...valueSources, source]) });
+            valueSources.add(source);
+        }
+        catch (e) {
+            if (!valueRefusalAnnounced.has(source)) {
+                valueRefusalAnnounced.add(source);
+                console.warn(`[sema-server] own credential ${source}: its value is not withheld by value from spawned children — the engine refused it (${e instanceof Error ? e.message : String(e)}); ` +
+                    "the variable name is still withheld under every inheritEnv policy, but a variable holding the same string under another name is not, and GET /v1/capabilities answers inherit_env.own_credential_values_withheld: false. " +
+                    "Give it a real credential value (at least 8 characters, not a placeholder) to withhold copies of it too.");
+            }
+        }
+    }
     beforeLast = declared;
-    declared = new Set(names);
+    declared = { names: new Set(names), valueSources };
     return names;
 }
 export function withdrawServerWithheldEnv() {
-    declareWithheldEnv([...(beforeLast ?? [])]);
+    declareWithheldEnv({ names: [...(beforeLast?.names ?? [])], values: valuesOf(beforeLast?.valueSources ?? []) });
     declared = beforeLast;
 }
 export function bindOwnCredentialsConfig(config) {
@@ -27,23 +51,40 @@ export function bindOwnCredentialsConfig(config) {
 export function ownCredentialsWithheld() {
     if (declared === undefined || liveConfig === undefined)
         return false;
-    const own = declared;
+    const own = declared.names;
     return serverWithheldEnvNames(liveConfig.modelApiKeyEnv).every((name) => own.has(name));
 }
+export function ownCredentialValuesWithheld() {
+    if (declared === undefined || liveConfig === undefined)
+        return false;
+    const own = declared.valueSources;
+    return serverCredentialValueSources(liveConfig.modelApiKeyEnv).every((source) => own.has(source) || valuesOf([source]).length === 0);
+}
 export function __resetServerWithheldEnvForTest() {
-    declareWithheldEnv([]);
+    declareWithheldEnv({ names: [], values: [] });
     declared = undefined;
     beforeLast = undefined;
     liveConfig = undefined;
+    valueRefusalAnnounced.clear();
 }
 export function hostSubprocessEnv(o) {
     const findings = [];
     const composed = composeHostSubprocessEnv(o, findings);
-    recordSecretEnvScrub(o.site, findings.filter((f) => composed[f.key] !== process.env[f.key]), o.allow);
+    const disclosed = [];
+    const seen = new Set();
+    for (const f of findings) {
+        const k = `${f.key}=${f.kind}`;
+        if (composed[f.key] === envValueOf(f.key) || seen.has(k))
+            continue;
+        seen.add(k);
+        disclosed.push(f);
+    }
+    recordSecretEnvScrub(o.site, disclosed, o.allow);
     return composed;
 }
 export function composeHostSubprocessEnv(o, findings = []) {
-    return { ...inheritedHostEnv(o.policy ?? "scrub", findings), ...allowlistedEnv(o.allow, process.env) };
+    const putBack = o.allow.length > 0 ? inheritedHostEnv([...o.allow], findings) : {};
+    return { ...inheritedHostEnv(o.policy ?? "scrub", findings), ...putBack };
 }
 export function gitSubprocessEnv(o) {
     return {

package/dist/session-incarnation.d.ts

@@ -61,10 +61,19 @@ export declare class SessionIncarnationMissingError extends Error {
     constructor(sessionId: string);
 }
 /**
- * 行上化身那一格的**唯一解码**(三只店的 `sessionFaceOf` 与 SQL 两店 wake 带出的会话元数据都经它 —— 空值判据只写这一处)。
- * 不是非空字符串 ⇒ {@link SessionIncarnationMissingError}。
+ * 空化身那一格怎么读 —— {@link incarnationFromCell} 的参数(一只解码,两种**显式**读法;不是两只函数):
+ *  · `refuse`(缺省,读口):一位活住客必须有令牌 ⇒ 空 / 非串 = {@link SessionIncarnationMissingError}(响亮拒,不当通配);
+ *  · `absent`:调用方问的是「这一格里有没有一只令牌」,空 / 非串的答案是**没有**(`undefined`)—— 会话树删除时的空间键
+ *    (没有令牌 = 没有空间,不回收缓存卷)与整段换装的沿用判据(没有令牌 = 铸一只新的)。
  */
-export declare function incarnationFromCell(sessionId: string, cell: unknown): string;
+export type EmptyIncarnationReading = "refuse" | "absent";
+/**
+ * 行上化身那一格的**唯一解码**(三只店的 `sessionFaceOf`、SQL 两店 wake 带出的会话元数据、留存删除的空间键、整段换装的沿用判据都经它 ——
+ * 「是不是一只令牌」只判这一处)。非空字符串 ⇒ 那只令牌;否则按 `empty`({@link EmptyIncarnationReading}):缺省 `refuse` ⇒
+ * {@link SessionIncarnationMissingError},`absent` ⇒ `undefined`。
+ */
+export declare function incarnationFromCell(sessionId: string, cell: unknown, empty?: "refuse"): string;
+export declare function incarnationFromCell(sessionId: string, cell: unknown, empty: "absent"): string | undefined;
 /** 店把一行原始列读成 {@link SessionFace} 的唯一口(三只店共用;化身那一格经 {@link incarnationFromCell})。 */
 export declare function sessionFaceFromRow(sessionId: string, owner: string | null, incarnation: unknown): SessionFace;
 /** 按 id 读住客(core `SessionStore.incarnationOf` 的形):`undefined` = 没有这只会话;读抛 = 读故障,不是答案。 */
@@ -81,9 +90,10 @@ export declare function incarnationReadOf(store: Pick<SessionStore, "incarnation
 export declare function sessionFaceReadOf(store: object | undefined): SessionFaceReader | undefined;
 /**
  * session-sync **整段换装**(replace)时化身的去留 —— 三只店共用的一句判据:换装删掉再插回的是**同一位住客**的那一行
- * (删除带属主门),所以行在、属主相同、化身非空 ⇒ 沿用;行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。
+ * (删除带属主门),所以行在、属主相同、那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 沿用;
+ * 行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。
  */
-export declare function carriedIncarnation(prior: {
+export declare function carriedIncarnation(sessionId: string, prior: {
     owner?: unknown;
     incarnation?: unknown;
 } | undefined, owner: string | null): string;

package/dist/session-incarnation.js

@@ -24,10 +24,19 @@ export class SessionIncarnationMissingError extends Error {
         this.name = "SessionIncarnationMissingError";
     }
 }
-export function incarnationFromCell(sessionId, cell) {
-    if (typeof cell !== "string" || cell === "")
-        throw new SessionIncarnationMissingError(sessionId);
-    return cell;
+export function incarnationFromCell(sessionId, cell, empty = "refuse") {
+    if (typeof cell === "string" && cell !== "")
+        return cell;
+    switch (empty) {
+        case "refuse":
+            throw new SessionIncarnationMissingError(sessionId);
+        case "absent":
+            return undefined;
+        default: {
+            const unknownReading = empty;
+            throw new Error(`incarnationFromCell: no reading ${JSON.stringify(unknownReading)}`);
+        }
+    }
 }
 export function sessionFaceFromRow(sessionId, owner, incarnation) {
     return { owner, incarnation: incarnationFromCell(sessionId, incarnation) };
@@ -40,11 +49,9 @@ export function sessionFaceReadOf(store) {
     const read = store?.sessionFaceOf;
     return typeof read === "function" ? read.bind(store) : undefined;
 }
-export function carriedIncarnation(prior, owner) {
-    if (prior !== undefined && (prior.owner ?? null) === owner && typeof prior.incarnation === "string" && prior.incarnation !== "") {
-        return prior.incarnation;
-    }
-    return mintSessionIncarnation();
+export function carriedIncarnation(sessionId, prior, owner) {
+    const held = prior !== undefined && (prior.owner ?? null) === owner ? incarnationFromCell(sessionId, prior.incarnation, "absent") : undefined;
+    return held ?? mintSessionIncarnation();
 }
 export const SESSION_META_INCARNATION_COLUMN = {
     name: "incarnation",

package/dist/session-titler.js

@@ -10,12 +10,22 @@ const FAIL_CAUSE_KEY_CHARS = 80;
 const SEEN_CAP = 10_000;
 function failOpenTagFor(code) {
     switch (code) {
+        case "model_unresolved":
+            return "server.session-titler.model-unresolved";
+        case "route_refused":
+            return "server.session-titler.route-refused";
+        case "credential_custody_failed":
+            return "server.session-titler.credential-custody-failed";
         case "redirect_refused":
             return "server.session-titler.redirect-refused";
+        case "bad_response":
+            return "server.session-titler.bad-response";
         case "no_content":
-        case "hard_timeout":
-        case undefined:
+            return "server.session-titler.no-content";
+        case "unreachable":
             return "server.session-titler.gateway-unreachable";
+        case undefined:
+            return "server.session-titler.unclassified";
     }
 }
 export function sanitizeTitle(raw) {

package/dist/spec-fields.d.ts

@@ -4,6 +4,7 @@
  * body WITHOUT the HTTP-layer 400 validation, so a malformed value must fall back to a safe default, never throw.
  */
 import { type AgentDefinition, type TaskSpec } from "@sema-agent/core";
+import { type LimitFacts, type LimitMeasure } from "./limit-refusal.js";
 /**
  * E12 — normalize `body.suggestNextPrompts` → `TaskSpec.suggestNextPrompts`. `true` = on with core defaults
  * (count 3, cheap role); an object tunes `count` (clamped 1..10) / `role` (a free string — core validates it against
@@ -51,25 +52,38 @@ export declare const MAX_TASK_AGENTS = 32;
  * `ruleEntryListShapeOk`):引擎直接 `for (const entry of list)` —— 一个裸字符串 `"Bash"` 会被逐字符迭代成 `B` / `a` / `s` / `h` 四条
  * (deny 侧 = 意图静默落空,安全轴上的放宽方向)。条目的**文法与名字**是引擎的读法:允侧读不出的条目(`*` / 写路径 / 域名 / 退役名 …)引擎在开跑时发
  * `permission.allowed_tool_not_granted`(受众 = 用户);拒侧读成空的条目(文法或名字层)在 `resolveSpec` 拒(提交 400 / 续跑 409,`rule-entry-list.ts` 的
- * `inertToolListEntryOf`,判据 = 引擎的条目读法;同一只函数也拒请求的工具名选择器清单里的近似名 / 退役名)。形对之后两道门再问 {@link skillToolListRefusal}(条数帽 ⇒ 400)。
- * 条数帽 = 条目表那一只(`rule-entry-list.ts` `allowLayerEntryCountIssue`,准备开销的界;与请求 allow 桶、运维表同一只),
- * 在 {@link skillToolListRefusal} 里判;无长度帽([ref])。
+ * `inertToolListEntryOf`,判据 = 引擎的条目读法;同一只函数也拒请求的工具名选择器清单里的近似名 / 退役名)。
+ * **条数帽**是全部工具名清单的同一只判(`rule-entry-list.ts` 的 `skillToolListsOverCap`;句子与机读位 `field` 点体内坐标 `skills[1].allowedTools` /
+ * `agents[0].skills[2].disallowedTools`):顶层 `validateUserSkills` 与子代 {@link validateTaskAgents} 两道门都逐条先形、后帽(与 7.131.0 的拒点与判序同);
+ * 拒点 `resolveSpec` 两腿同经的 `inertToolListEntryOf` 先过同一只判;无长度帽([ref])。
  */
 export declare const skillToolListOk: (v: unknown) => v is readonly string[];
 /**
- * 一条技能(形已过两道门的字符串数组判)的两只清单在受理口的拒因 —— 都过 ⇒ `undefined`。两处受理口同调:顶层 `skills[]`
- * (`http/admission.ts` 的 `validateUserSkills`)、子代 `agents[].skills[]`({@link validateTaskAgents})。一问:条数帽。退役名 / 对端段或工具段铸不出、为空 /
- * 读成空的条目是引擎的读法(见上):允侧交引擎通告,拒侧由 `resolveSpec` 拒(7.116.0–7.122.x 本仓在这里另拒工具段为空的协议名,core 7.48.0 #1400 起
- * 它是引擎判官的判词,随之退役)。
+ * 一条子代定义的裁决:`message` = 一句可 400 的英文(不带下标,调用方加);撞帽时另带 `limit`(`rel` = 相对这条定义的坐标 `allowTools[3]` / `name`),
+ * 句子是撞帽的头一句(`agent.allowTools[3] has 129 characters — at most 128 are accepted`:撞了哪一条帽、送来多少、帽多少),
+ * {@link validateTaskAgents} 把它铸成体内坐标的机读位(`field: "agents[0].allowTools[3]"`)。
  */
-export declare function skillToolListRefusal(skill: Record<string, unknown>): string | undefined;
+export interface TaskAgentIssue {
+    readonly message: string;
+    readonly limit?: {
+        readonly rel: string;
+        readonly measure: LimitMeasure;
+        readonly count: number;
+        readonly cap: number;
+    };
+}
+/** 提交体 `agents` 的拒:句子(带下标)+ 撞帽时的机读位(`field` / `reason` / `count` / `cap`,`limit-refusal.ts` 一处铸)。 */
+export interface TaskAgentsRefusal {
+    readonly message: string;
+    readonly facts?: LimitFacts;
+}
 /** [ref] 单条 agent 定义的形状裁决:null=合法;否则一句可 400 的英文错误(不带索引,调用方自己加)。
  *  白名单外键 fail-loud —— 与 resilience/limits 的「容忍未知键」相反:agents 是能力定义,静默丢字段 =
  *  定义被悄悄削(一个丢掉的 isolation 就是放宽),比 400 更危险,故整条拒。`allowTools` / `denyTools` 本门只判形与条数(`toolList`),
  *  **名字归引擎一只判**(core 7.49.0 #1623 / #1433 第二步起与根 run 的 `allowTools` / `excludeTools` 是同一只选择器,开跑前,三来源同判):core 7.51.0 #1736 起
  *  没有任何工具答应的名字(无人挂的名、大小写孪生 / 退役名 `bash` / `BASH`)**引擎不拒 run** —— 条目原样保留、经 onError(config)告知一次(带该写的拼法);
  *  其中**写错现名的**(`denyTools:["BASH"]` 想禁的照用 = 静默放行;`allowTools:["BASH"]` 想放的什么也没放 = 静默收窄)由 `resolveSpec` 前置拒:**限制侧**(`denyTools`)四类全拒(近似名 · 退役名 · 文法读不出 · `*`),
- *  **放行侧**(`allowTools`)只拒近似名 —— 放行侧的退役名 / 内容形 / 文法读不出照 7.130.0 受理、交引擎既有通告(文法读不出的放行条目引擎在子代 prepare 整 run 拒 `config.agent.unknown_tool`,根 `allowTools` 同步腿 400 `config.tool_face_control`;`rule-entry-list.ts` `inertToolListEntryOf`:近似名提交 400 `config.agent.unknown_tool` 点名现名、续跑按方向分流;
+ *  **放行侧**(`allowTools`)只拒近似名 —— 放行侧的内容形 / 没有后继的退役名 / 文法读不出照 7.130.0 受理、交引擎既有通告(有后继的退役名〔`bash` · `Task`〕与文法读不出的放行条目引擎在子代 prepare 整 run 拒 `config.agent.unknown_tool`,根 `allowTools` 拒 `config.tool_face_control`,同步腿两码同为 400〔`runs.ts` `PREPARE_REFUSAL_HTTP_STATUS`〕;`rule-entry-list.ts` `inertToolListEntryOf`:近似名提交 400 `config.agent.unknown_tool` 点名现名、续跑按方向分流;
  *  判官仍是引擎的条目读法,不是第二个判官);
  *  **真未知名**(没有近似也没有退役对应:懒挂载的合法形)照旧只告运维、不拒。
  *  任何工具名都不可能有的拼法(`grammar`)与非字符串条目引擎照旧整 run 拒 `config.agent.unknown_tool` —— 主车道的委派工具带 extraTools 工厂,本仓在同一处
@@ -79,11 +93,11 @@ export declare function skillToolListRefusal(skill: Record<string, unknown>): st
  *  本门不做名字对照(拒侧的那一判在 `resolveSpec`,见上;本门只判形与条数)。
  *  ⚠️ 键判断必须 Object.hasOwn:`in` 走原型链,JSON 里的 "toString"/"constructor"/"__proto__" 键会被
  *  误判为白名单字段,随后 SHAPES[k].ok 不是函数 ⇒ TypeError(fresh 500 / resume 砖;cross-review 复现)。 */
-export declare function taskAgentIssue(item: unknown): string | null;
+export declare function taskAgentIssue(item: unknown): TaskAgentIssue | null;
 /** [ref] HTTP 门(fresh submit,server.ts prepareSpec):body.agents 在场必须是非空数组、每条过
  *  {@link taskAgentIssue}、name 数组内唯一、条数 ≤ {@link MAX_TASK_AGENTS}。返回 400 错误串或 null。
  *  RESUME 重放不过这道门 —— {@link taskAgentsFromBody} defensive(按条 DROP+warn,不砖 resume)。 */
-export declare function validateTaskAgents(v: unknown): string | null;
+export declare function validateTaskAgents(v: unknown): TaskAgentsRefusal | null;
 /** [ref] body.agents → `TaskSpec.agents`(resolveSpec 的唯一装配点;main.ts 只 spread)。两层门:
  *   - 🔒 TOB 租户门:多租户(requirePrincipal===true)暂不放行 —— [ref] 原文「TOB 面按租户 caps 门」,
  *     当前没有 per-tenant caps 面可挂,先 fail-closed 关多租(warn `task_agents_ignored`,capabilities
@@ -135,8 +149,6 @@ export declare function retainBackgroundProcessesFromBody(raw: unknown, requireP
  *  DEFENSIVE(resume 重放不过 HTTP 400 门):非数组 ⇒ undefined;项非非空字符串 ⇒ 逐项 DROP;空数组 ⇒
  *  undefined(不挂键=core 缺省,byte-compat)。HTTP 门另有 fail-loud 400(提交面邻居姿势)。 */
 export declare function toolNameListFromBody(raw: unknown): string[] | undefined;
-/** 引擎从哪一版起认 `TaskSpec.allowTools`(core 7.49.0 #1623,[ref])。 */
-export declare const ALLOW_TOOLS_MIN_ENGINE = "7.49.0";
 /**
  * S-1448(core 7.49.0 #1623 / [ref])—— body.allowTools → `TaskSpec.allowTools`:引擎的**可用性选择器**,原样透传。
  *
@@ -145,10 +157,10 @@ export declare const ALLOW_TOOLS_MIN_ENGINE = "7.49.0";
  * `config.tool_face_control`)、不与 allow 层 `allowedTools`(免问)混词。受理门只判 wire 形(与 `excludeTools` / `deferTools` 同一只门)。
  * 续跑重放同经此处:存量体逐字再投,坏形交引擎拒(收窄键丢了 = 放宽,所以不 DROP)。
  *
- * 装着的引擎不认该座(< {@link ALLOW_TOOLS_MIN_ENGINE})⇒ **响亮拒** 400 `request.field_invalid`(点名键、所需版本与装着的版本),
- * 不静默丢。`engineVersion` 缺省读装着的 core(`CORE_ENGINE_VERSION`);测试传假低版。
+ * **没有引擎版本臂**:core 精确钉在认这个座(7.49.0 起)的版本之上,「装着的引擎不认该座」在生产里不可达;「core 至少是哪一版」是依赖下限门
+ * 的事实(`test/core-dependency-floor.test.ts` + `test/helpers/core-floor.ts`),不是本函数运行期的比对(一个事实一只源)。
  */
-export declare function allowToolsSpecFragment(raw: unknown, engineVersion?: string): {
+export declare function allowToolsSpecFragment(raw: unknown): {
     allowTools?: string[];
 };
 /** [ref]/[ref] — body.promptProfile → `TaskSpec.promptProfile`(core 1.328 R2 主件,CC LT(model_id)

package/dist/spec-fields.js

@@ -1,9 +1,9 @@
 import { isThinkingLevel } from "@sema-agent/core";
 import { taskWallClockSec } from "./task-workflow.js";
 import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
-import { CORE_ENGINE_VERSION } from "./prompts-domain-validate.js";
-import { createCodedHttpError } from "./security.js";
-import { allowLayerEntryCountIssue, ruleEntryListShapeOk } from "./rule-entry-list.js";
+import { ruleEntryListShapeOk, skillToolListsOverCap } from "./rule-entry-list.js";
+import { describeLimit, limitFacts, limitRefusal } from "./limit-refusal.js";
+import { quotedCallerText } from "./caller-text-echo.js";
 export function normalizeSuggestNextPrompts(v) {
     if (v === true)
         return true;
@@ -67,20 +67,19 @@ const boundedString = (max) => (v) => typeof v === "string" && v.length <= max;
 const toolList = (v) => Array.isArray(v) &&
     v.length <= MAX_AGENT_TOOLS &&
     v.every((x) => typeof x === "string" && x.length > 0 && x.length <= MAX_AGENT_TOOL_NAME_CHARS);
+const charLimit = (max) => (v) => typeof v === "string" && v.length > max ? { sub: "", measure: "characters", count: v.length, cap: max } : undefined;
+const toolListLimit = (v) => {
+    if (!Array.isArray(v))
+        return undefined;
+    if (v.length > MAX_AGENT_TOOLS)
+        return { sub: "", measure: "entries", count: v.length, cap: MAX_AGENT_TOOLS };
+    if (!v.every((x) => typeof x === "string" && x.length > 0))
+        return undefined;
+    const j = v.findIndex((x) => x.length > MAX_AGENT_TOOL_NAME_CHARS);
+    return j < 0 ? undefined : { sub: `[${j}]`, measure: "characters", count: v[j].length, cap: MAX_AGENT_TOOL_NAME_CHARS };
+};
 const plainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 export const skillToolListOk = ruleEntryListShapeOk;
-const SKILL_TOOL_LISTS = ["allowedTools", "disallowedTools"];
-export function skillToolListRefusal(skill) {
-    for (const key of SKILL_TOOL_LISTS) {
-        const list = skill[key];
-        if (!ruleEntryListShapeOk(list))
-            continue;
-        const over = allowLayerEntryCountIssue(`skill.${key}`, list);
-        if (over !== undefined)
-            return over.message;
-    }
-    return undefined;
-}
 const skillFilesOk = (v) => Array.isArray(v) &&
     v.every((f) => plainObject(f) && typeof f.path === "string" && f.path.length > 0 && typeof f.content === "string");
 const SKILL_FIELD_SHAPES = {
@@ -132,11 +131,12 @@ const TASK_AGENT_FIELD_SHAPES = {
     name: {
         desc: `a non-empty string of at most ${MAX_AGENT_NAME_CHARS} characters`,
         ok: (v) => typeof v === "string" && v.length > 0 && v.length <= MAX_AGENT_NAME_CHARS,
+        limit: charLimit(MAX_AGENT_NAME_CHARS),
     },
-    whenToUse: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS) },
-    whenToUseLean: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS) },
-    allowTools: { desc: `an array of at most ${MAX_AGENT_TOOLS} non-empty strings of at most ${MAX_AGENT_TOOL_NAME_CHARS} characters each`, ok: toolList },
-    denyTools: { desc: `an array of at most ${MAX_AGENT_TOOLS} non-empty strings of at most ${MAX_AGENT_TOOL_NAME_CHARS} characters each`, ok: toolList },
+    whenToUse: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS), limit: charLimit(MAX_AGENT_TEXT_CHARS) },
+    whenToUseLean: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS), limit: charLimit(MAX_AGENT_TEXT_CHARS) },
+    allowTools: { desc: `an array of at most ${MAX_AGENT_TOOLS} non-empty strings of at most ${MAX_AGENT_TOOL_NAME_CHARS} characters each`, ok: toolList, limit: toolListLimit },
+    denyTools: { desc: `an array of at most ${MAX_AGENT_TOOLS} non-empty strings of at most ${MAX_AGENT_TOOL_NAME_CHARS} characters each`, ok: toolList, limit: toolListLimit },
     skills: {
         desc: "an array of { name, description, content } skill objects (optional allowedTools/disallowedTools/files/baseDir; allowedTools/disallowedTools are arrays of strings; files entries need { path, content }; baseDir must be an absolute path with no \"..\" segment) — no count cap; the engine renders the listing within its own byte budget",
         ok: (v) => Array.isArray(v) && v.every(skillOk),
@@ -149,57 +149,64 @@ const TASK_AGENT_FIELD_SHAPES = {
             (plainObject(v) && typeof v.id === "string" && v.id.length > 0),
     },
     thinking: { desc: "a thinking level (off/minimal/low/medium/high/xhigh/max)", ok: (v) => isThinkingLevel(v) },
-    systemPrompt: { desc: `a string of at most ${MAX_AGENT_SYSTEM_PROMPT_CHARS} characters`, ok: boundedString(MAX_AGENT_SYSTEM_PROMPT_CHARS) },
+    systemPrompt: { desc: `a string of at most ${MAX_AGENT_SYSTEM_PROMPT_CHARS} characters`, ok: boundedString(MAX_AGENT_SYSTEM_PROMPT_CHARS), limit: charLimit(MAX_AGENT_SYSTEM_PROMPT_CHARS) },
     maxTurns: {
         desc: `a positive integer of at most ${MAX_AGENT_MAX_TURNS}`,
         ok: (v) => typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= MAX_AGENT_MAX_TURNS,
     },
     memory: { desc: "a memory spec object ({ scopes?, writeScope?, enabled?, scopeContract? })", ok: memoryOk },
-    observer: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS) },
-    observerMessage: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS) },
+    observer: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS), limit: charLimit(MAX_AGENT_TEXT_CHARS) },
+    observerMessage: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS), limit: charLimit(MAX_AGENT_TEXT_CHARS) },
 };
 export function taskAgentIssue(item) {
     if (item === null || typeof item !== "object" || Array.isArray(item))
-        return "each agent must be an object";
+        return { message: "each agent must be an object" };
     const rec = item;
     for (const k of Object.keys(rec)) {
         if (k === "permissionMode")
-            return 'agent "permissionMode" is not accepted (deliberately excluded from the per-task agent contract)';
+            return { message: 'agent "permissionMode" is not accepted (deliberately excluded from the per-task agent contract)' };
         if (!Object.hasOwn(TASK_AGENT_FIELD_SHAPES, k))
-            return `unknown agent key "${k}"`;
+            return { message: `unknown agent key ${quotedCallerText(k)}` };
     }
     if (rec.name === undefined)
-        return "agent.name is required";
+        return { message: "agent.name is required" };
     for (const [k, v] of Object.entries(rec)) {
         if (v === undefined)
             continue;
         const shape = TASK_AGENT_FIELD_SHAPES[k];
-        if (!shape.ok(v))
-            return `agent.${k} must be ${shape.desc}`;
+        if (shape.ok(v))
+            continue;
+        const hit = shape.limit?.(v);
+        if (hit === undefined)
+            return { message: `agent.${k} must be ${shape.desc}` };
+        const rel = `${k}${hit.sub}`;
+        return { message: describeLimit(`agent.${rel}`, hit.measure, hit.count, hit.cap), limit: { rel, measure: hit.measure, count: hit.count, cap: hit.cap } };
     }
     return null;
 }
 export function validateTaskAgents(v) {
     if (!Array.isArray(v) || v.length === 0)
-        return "agents must be a non-empty array of agent definitions";
+        return { message: "agents must be a non-empty array of agent definitions" };
     if (v.length > MAX_TASK_AGENTS)
-        return `at most ${MAX_TASK_AGENTS} agents per request`;
+        return limitRefusal("agents", "entries", v.length, MAX_TASK_AGENTS);
     const names = new Set();
     for (let i = 0; i < v.length; i++) {
         const issue = taskAgentIssue(v[i]);
-        if (issue)
-            return `agents[${i}]: ${issue}`;
+        if (issue) {
+            const message = `agents[${i}]: ${issue.message}`;
+            return issue.limit === undefined ? { message } : { message, facts: limitFacts(`agents[${i}].${issue.limit.rel}`, issue.limit.measure, issue.limit.count, issue.limit.cap) };
+        }
         const skills = v[i].skills;
         if (Array.isArray(skills)) {
             for (let j = 0; j < skills.length; j++) {
-                const refusal = skillToolListRefusal(skills[j]);
-                if (refusal !== undefined)
-                    return `agents[${i}]: skills[${j}]: ${refusal}`;
+                const over = skillToolListsOverCap(skills[j], `agents[${i}].skills[${j}]`, "agent");
+                if (over !== undefined)
+                    return { message: over.message, ...(over.extra !== undefined ? { facts: over.extra } : {}) };
             }
         }
         const name = v[i].name;
         if (names.has(name))
-            return `agents[${i}]: duplicate agent name "${name}"`;
+            return { message: `agents[${i}]: duplicate agent name ${quotedCallerText(name)}` };
         names.add(name);
     }
     return null;
@@ -224,7 +231,7 @@ export function taskAgentsFromBody(raw, requirePrincipal, warn) {
         }
         const issue = taskAgentIssue(raw[i]);
         if (issue) {
-            warn("task_agent_dropped", { index: i, reason: issue });
+            warn("task_agent_dropped", { index: i, reason: issue.message });
             continue;
         }
         const rec = raw[i];
@@ -272,22 +279,8 @@ export function toolNameListFromBody(raw) {
     const names = raw.filter((v) => typeof v === "string" && v.length > 0);
     return names.length > 0 ? names : undefined;
 }
-export const ALLOW_TOOLS_MIN_ENGINE = "7.49.0";
-function engineAtLeast(version, floor) {
-    const parse = (v) => v.split(/[-+]/, 1)[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
-    const [a, b] = [parse(version), parse(floor)];
-    for (let i = 0; i < 3; i++)
-        if ((a[i] ?? 0) !== (b[i] ?? 0))
-            return (a[i] ?? 0) > (b[i] ?? 0);
-    return true;
-}
-export function allowToolsSpecFragment(raw, engineVersion = CORE_ENGINE_VERSION) {
-    if (raw === undefined)
-        return {};
-    if (!engineAtLeast(engineVersion, ALLOW_TOOLS_MIN_ENGINE)) {
-        throw createCodedHttpError(400, "request.field_invalid", `allowTools needs engine ${ALLOW_TOOLS_MIN_ENGINE} or later; this server runs engine ${engineVersion}, which would drop the list and leave every tool available — send the request without allowTools, or upgrade the server`);
-    }
-    return { allowTools: raw };
+export function allowToolsSpecFragment(raw) {
+    return raw === undefined ? {} : { allowTools: raw };
 }
 export function promptProfileFromBody(raw) {
     return raw === "simple" || raw === "classic" ? raw : undefined;