@sema-agent/server 7.131.0 → 7.133.0

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-titled-frame.d.ts

@@ -0,0 +1,33 @@
+/**
+ * **会话标题帧 `session_titled`** —— 标题器把标题写进会话行**之后**,在**这条 run 的活流**上自铸的一帧(契约 §4a-ttl)。
+ *
+ * ## 为什么有这一帧
+ * 标题器是 fire-and-forget:run 被引擎受理之后才起、在 run 跑的同时生成,写成时那条 run 的流往往还开着。此前写成只落行
+ * (`setTitleIfNull`)+ 一行运维日志 —— wire 上零通知,端上(桌面 / web 座位)只能在首轮之后有界轮询读会话行。
+ * 这一帧把「标题写成了」交给已经在 tail 这条流的人,轮询可以删。
+ *
+ * ## 律(一条)
+ * **只活不存**:会话行是标题的唯一真源,本帧只是「行刚刚变了」的活通知 —— 不落账本(`GET /v1/runs/:id/events` 回放读不出它)、
+ * 不进任何重放面;冷启动 / 多窗口 / 断线重连读会话行(`GET /v1/sessions` 的列表行 `title`;`/v1/sessions/:id/head` 只带 `leafId`,不是标题的读面)。因此:
+ *  · 读者 = **这条 run 的流读者**,与会话行的读权同一(流是提交这条 run 的人开的,会话行归同一个人);
+ *  · 只有持活流的腿才收得到(今天 = `POST /v1/tasks/stream`);同步 JSON 腿 / durable 后台腿没有活流 ⇒ 这一帧结构上不存在,读行;
+ *  · 流已经走到终帧(`done`)或连接已断 ⇒ 丢弃(终帧是流的最后一帧);
+ *  · `PATCH /v1/sessions/:id` 的改名 / 置顶不经标题器 ⇒ 不发(调用方自知);用户清空标题后下一次提交由标题器重填,那一次重填照发(例外:本进程里此前为这个会话生成失败 / 回空过 —— 标题器不再为它重试,直到进程重启)。
+ *
+ * ## 谁铸
+ * 唯一铸点 = {@link buildSessionTitledFrame},唯一调用方 = `session-titler.ts`(落行成功的那一支,实参 = 落进行里的**同一个**标题 ——
+ * 已脱敏、已清洗;帧上的标题与行上的标题是一个值,不从模型原文另铸)。键集登记在 `trace/self-minted-wire.ts` 的 `sessionTitledFrameKey`
+ * (成员集 `satisfies Record<keyof SessionTitledFrame, …>`:加一个键而登记没跟 ⇒ tsc 红)。
+ *
+ * 帧上没有 `eventId` ⇒ SSE 不发 `id:` 行(契约 §0.6「无锚不发行」):它不是引擎的内容帧,没有续流位置可言。
+ */
+/** 标题帧的形 —— 键集就是这个接口的键(登记表按 `keyof` 绑定)。 */
+export interface SessionTitledFrame {
+    readonly type: "session_titled";
+    readonly sessionId: string;
+    /** 落进会话行的那个标题(已过标题器的脱敏与清洗,≤ `TITLE_MAX_CHARS` 个字符)。 */
+    readonly title: string;
+}
+/** 唯一铸点:纯数据,无行为。 */
+export declare function buildSessionTitledFrame(sessionId: string, title: string): SessionTitledFrame;
+//# sourceMappingURL=session-titled-frame.d.ts.map

package/dist/session-titled-frame.js

@@ -0,0 +1,4 @@
+export function buildSessionTitledFrame(sessionId, title) {
+    return { type: "session_titled", sessionId, title };
+}
+//# sourceMappingURL=session-titled-frame.js.map

package/dist/session-titler.d.ts

@@ -13,6 +13,11 @@
  * cheap-model one-liner via the deployment's hookLlm face (summarize role → MODEL_CHEAP_ID when configured, else the
  * main model; bounded + timed out).
  *
+ * WRITE-AFTER NOTICE: the title that lands is announced to the run that triggered it — `maybeTitle`'s `onTitled` hands the
+ * seat (`run-acceptance.ts`) the one `session_titled` frame (`session-titled-frame.ts`, contract §4a-ttl) built from the
+ * SAME string the row now holds; the seat forwards it to the live stream when the leg has one. Live-only: the row is the
+ * truth, nothing else stores the frame.
+ *
  * FAILURE POSTURE: everything is best-effort — a generation/store failure logs and leaves title null (the
  * list falls back to objectivePreview). The fail-open tag it leaves names the CAUSE FAMILY (one tag, one family):
  * the llm face's failure CODE picks it (`failOpenTagFor`), never the error's wording. An in-process pending set dedupes concurrent submits on the same
@@ -20,6 +25,7 @@
  * call at worst, and exactly one title lands).
  */
 import type { HookLlmFailureCode } from "./hooks/hook-runner.js";
+import { type SessionTitledFrame } from "./session-titled-frame.js";
 export interface SessionTitlerDeps {
     /** Secret scrub applied to the RAW llm text before sanitize/persist (workflow audit 2026-07-13: the
      *  objective may carry a pasted secret and the model can echo it into the title — titles are persisted,
@@ -58,7 +64,9 @@ export interface SessionTitlerDeps {
 export interface SessionTitler {
     /** Fire-and-forget: maybe generate + persist a title for this session. Never throws, never blocks the caller. */
     /** `model`([ref]②)= 本 turn 真实驱动的模型——带上则标题 hook 同链路,不再裸落 env 缺省。 */
-    maybeTitle(sessionId: string, objective: string, model?: string): void;
+    /** `onTitled` = 这一次调用**自己**把标题写成之后(`setTitleIfNull` 落行)交出的活通知(`session_titled` 帧,契约 §4a-ttl):只在落行的那一支调用恰一次 ——
+     *  已有标题 / 竞态输了 / 模型失败 / 空标题 / 这个会话已有一次在飞的调用,都不调。回调同步执行、**不许抛**;抛了也不影响已落行的标题(见下 `frame_failed`)。 */
+    maybeTitle(sessionId: string, objective: string, model?: string, onTitled?: (frame: SessionTitledFrame) => void): void;
 }
 export declare const TITLE_MAX_CHARS = 80;
 /** Single line, control chars stripped, hard cap; surrounding quotes (a common LLM tic) trimmed. */

package/dist/session-titler.js

@@ -1,7 +1,8 @@
-import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
+import { stripControlAndBidi } from "@sema-agent/settings-schema";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { redactSecrets } from "./trace/redact.js";
 import { userAuthoredText } from "./user-authored-text.js";
+import { buildSessionTitledFrame } from "./session-titled-frame.js";
 export const TITLE_MAX_CHARS = 80;
 const OBJECTIVE_SNIPPET_CHARS = 600;
 const LLM_TIMEOUT_MS = 15_000;
@@ -10,16 +11,26 @@ 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) {
-    const oneLine = raw.replace(/[\r\n]+/g, " ").replace(CONTROL_AND_BIDI_STRIP_RE, "").trim();
+    const oneLine = stripControlAndBidi(raw.replace(/[\r\n]+/g, " ")).trim();
     const unquoted = oneLine.replace(/^["'「『]+/, "").replace(/["'」』]+$/, "").trim();
     return unquoted.length > TITLE_MAX_CHARS ? `${unquoted.slice(0, TITLE_MAX_CHARS - 1)}…` : unquoted;
 }
@@ -35,8 +46,9 @@ export function buildTitlePrompt(objective) {
 }
 export function createSessionTitler(deps) {
     const seen = new Set();
+    const redactedError = (error) => redactSecrets(error);
     const logFailure = (sessionId, error, code) => {
-        const safe = redactSecrets(error);
+        const safe = redactedError(error);
         deps.logger?.debug?.("session_title_failed", { sessionId, error: safe.slice(0, 200) });
         recordFailOpen(failOpenTagFor(code), safe.slice(0, FAIL_CAUSE_KEY_CHARS));
     };
@@ -45,7 +57,7 @@ export function createSessionTitler(deps) {
         .then((state) => ({ state, unreadable: false }))
         .catch(() => ({ state: continueWord, unreadable: true }));
     return {
-        maybeTitle(sessionId, objective, model) {
+        maybeTitle(sessionId, objective, model, onTitled) {
             if (!sessionId || !userAuthoredText(objective))
                 return;
             if (seen.has(sessionId))
@@ -94,6 +106,15 @@ export function createSessionTitler(deps) {
                 seen.delete(sessionId);
                 deps.metrics?.inc("session_title_total", { outcome: "set" });
                 deps.logger?.info?.("session_titled", { sessionId, titleChars: title.length });
+                if (onTitled) {
+                    try {
+                        onTitled(buildSessionTitledFrame(sessionId, title));
+                    }
+                    catch (e) {
+                        deps.metrics?.inc("session_title_total", { outcome: "frame_failed" });
+                        deps.logger?.warn?.("session_titled_frame_failed", { sessionId, error: redactedError(String(e)).slice(0, 200) });
+                    }
+                }
             })().catch((e) => {
                 deps.metrics?.inc("session_title_total", { outcome: "error" });
                 logFailure(sessionId, String(e));

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 { ABSOLUTE_HOST_PATH_MAX, isAbsoluteHostPath } from "@sema-agent/settings-schema";
+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 = {
@@ -111,6 +110,23 @@ const skillOk = (s) => {
     }
     return true;
 };
+const skillsLimit = (v) => {
+    if (!Array.isArray(v))
+        return undefined;
+    const j = v.findIndex((s) => !skillOk(s));
+    const s = j < 0 ? undefined : v[j];
+    if (!plainObject(s))
+        return undefined;
+    const content = s["content"];
+    const baseDir = s["baseDir"];
+    if (typeof content === "string" && content.length > MAX_AGENT_SKILL_CONTENT_CHARS) {
+        return { sub: `[${j}].content`, measure: "characters", count: content.length, cap: MAX_AGENT_SKILL_CONTENT_CHARS, keepShapeSentence: true };
+    }
+    if (typeof baseDir === "string" && baseDir.length > ABSOLUTE_HOST_PATH_MAX) {
+        return { sub: `[${j}].baseDir`, measure: "characters", count: baseDir.length, cap: ABSOLUTE_HOST_PATH_MAX, keepShapeSentence: true };
+    }
+    return undefined;
+};
 const memoryOk = (v) => {
     if (!plainObject(v))
         return false;
@@ -132,14 +148,16 @@ 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),
+        limit: skillsLimit,
     },
     background: { desc: "a boolean", ok: (v) => typeof v === "boolean" },
     isolation: { desc: '"worktree"', ok: (v) => v === "worktree" },
@@ -149,57 +167,65 @@ 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}`;
+        const limit = { rel, measure: hit.measure, count: hit.count, cap: hit.cap };
+        return hit.keepShapeSentence === true ? { message: `agent.${k} must be ${shape.desc}`, limit } : { message: describeLimit(`agent.${rel}`, hit.measure, hit.count, hit.cap), limit };
     }
     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 +250,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 +298,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;

package/dist/sql-engine-posture.d.ts

@@ -24,9 +24,34 @@
  * 不在这里 —— 在 `sql-driver.ts` 的连接初始化里(TiDB 乐观模式设不成悲观 / 隔离级复核不符 ⇒ 响亮抛)。
  * 本模块在 boot 期借一条连接**触发**那次初始化,于是那句拒绝落在启动期而不是第一次业务写上。
  */
-import { type SqlEngineFacts } from "./plugins/sql-driver.js";
+import { type SqlEngineFacts, type SqlEngineReading } from "./plugins/sql-driver.js";
+import type { StoreBackend } from "./plugins/store-backend.js";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+/**
+ * 一只店后端交出的 SQL 池(至多一只:`mysqlPool()` 只在 MySQL 协议后端上有值,`pgPool()` 只在 PG 后端上;local 后端 / 没有后端 ⇒ 两个都 `undefined`)。
+ * **「SQL 后端在场」只有这一个谓词**:boot 期据它建立引擎读口({@link establishSqlEnginePosture}),`createHttpServer` 据它判「读口必填」——
+ * 两处读同一只函数,所以本服务自己的装配(有池 ⇒ 有读口)恒满足那道起服门,嵌入方少给读口则被它拒。
+ */
+export declare function sqlPoolsOf(backend: Pick<StoreBackend, "mysqlPool" | "pgPool"> | undefined): {
+    mysqlPool: MySqlPool | undefined;
+    pgPool: PgPool | undefined;
+};
+/**
+ * `ServiceDeps.sqlEngine` 座的**值形**判:`{ dialect: "tidb" | "pg", facts }`,`facts` 是 `null`(池上连接初始化还没成功)或一份引擎事实 —— 判到墙判官 `sqlWallsOf` 读的那几位
+ * (`maxRowBytes` / `maxPacketBytes` 是 `null` 或数,`wallSources` 两位是出处词)。一个函数(7.131.x 的事实读口 `() => facts` 只改了键名)、缺 `facts` 的对象、错方言词都不是它。
+ * `facts` 是活读(getter):这里读一次,判的是装配这一刻看得到的那一份。
+ */
+export declare function isSqlEngineReading(v: unknown): v is SqlEngineReading;
+/** 引擎读口座的装配问题(闭集;{@link sqlEngineSeatIssue} 的产物):`required` = SQL 后端在场而座缺席;`bad_shape` = 座在场但形不对。 */
+export type SqlEngineSeatIssue = "required" | "bad_shape";
+/**
+ * 🔴 **引擎读口座的装配判官**(`createHttpServer` 起服时调;两臂一只函数):
+ *  · 座在场 ⇒ 判值形({@link isSqlEngineReading}),不对 ⇒ `bad_shape`;
+ *  · 座缺席 ⇒ 看后端交没交出 SQL 池({@link sqlPoolsOf},与 boot 期建立读口同一个谓词):交了 ⇒ `required`(席缺席只表示「没有 SQL 后端」,不能被判官读成「没有墙」);没交 ⇒ 过。
+ * 都是 fail-closed:墙门只认这一席,席坏了或漏了,代价是每份超出库墙的体照样受理或每次提交 500,不是起服时一句话。
+ */
+export declare function sqlEngineSeatIssue(backend: Pick<StoreBackend, "mysqlPool" | "pgPool"> | undefined, sqlEngine: unknown): SqlEngineSeatIssue | undefined;
 /** 消费端窄投影(`GET /v1/capabilities` 的 `store.sql` 位;7.106.0 前是顶层 `sql`,S-866 ①)。`null` = 驱动此刻给不出事实 ⇒ `store.sql` 缺席。 */
 export interface SqlEngineCapability {
     engine: SqlEngineFacts["engine"];
@@ -34,8 +59,10 @@ export interface SqlEngineCapability {
     txnMode: SqlEngineFacts["txnMode"];
 }
 /**
- * Boot 期建立引擎事实:借一条池连接(初始化随之跑),再原样归还。返回一个 **live getter** —— 事实由
- * 驱动持有,重连后它会被下一次初始化刷新,快照会说谎。
+ * Boot 期建立引擎事实:借一条池连接(初始化随之跑),再原样归还。返回本池的**引擎读口**(驱动本身:方言 + 活的 `facts`)—— 事实由
+ * 驱动持有,重连后它会被下一次初始化刷新,快照会说谎;方言与事实同出这一只,写入要装进的墙(`sqlWallsOf`)只读它。读到的是**最近一次初始化的那条连接**的事实:隔离级 / 事务模式每条连接
+ * 同钉同验,所以就是池的事实;包墙 `maxPacketBytes` 是会话值、随连接不同,这里只是那一条连接的读数(池见过的最新读数 —— 只在有连接初始化时才更新,DBA 调了全局值之后、下一条连接初始化之前它仍是旧值;
+ * 运维读面与提交受理口的提前一跑读它),终判读将要执行写入的那条连接自己的读数(`sql-driver.ts` `connectJudged`)。
  *
  * 抛出 = 拒启:连接初始化拒绝了这个后端(TiDB 乐观模式设不成悲观、隔离级复核不符、服务器太旧读不出
  * `@@transaction_isolation`)。这条错**刻意不吞** —— 本仓所有 `FOR UPDATE` 判据都以它为前提。
@@ -43,7 +70,7 @@ export interface SqlEngineCapability {
 export declare function establishSqlEnginePosture(pools: {
     mysqlPool?: MySqlPool | undefined;
     pgPool?: PgPool | undefined;
-}): Promise<(() => SqlEngineFacts | null) | undefined>;
+}): Promise<SqlEngineReading | undefined>;
 /** operator 面 → 消费端面的窄投影(`version` 是运维料,刻意不进能力位:它只对排障有意义)。 */
 export declare function projectSqlEngineCapability(facts: SqlEngineFacts | null | undefined): SqlEngineCapability | null;
 //# sourceMappingURL=sql-engine-posture.d.ts.map

package/dist/sql-engine-posture.js

@@ -1,11 +1,46 @@
 import { mysqlDriver, pgDriver } from "./plugins/sql-driver.js";
+export function sqlPoolsOf(backend) {
+    return { mysqlPool: backend?.mysqlPool?.(), pgPool: backend?.pgPool?.() };
+}
+const DIALECT_WORDS = { tidb: true, pg: true };
+const WALL_SOURCE_WORDS = { reported: true, assumed: true };
+const isWallBytes = (v) => v === null || (typeof v === "number" && Number.isFinite(v) && v >= 0);
+const isWallSourceWord = (v) => typeof v === "string" && Object.hasOwn(WALL_SOURCE_WORDS, v);
+export function isSqlEngineReading(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const r = v;
+    if (typeof r.dialect !== "string" || !Object.hasOwn(DIALECT_WORDS, r.dialect))
+        return false;
+    if (!("facts" in v))
+        return false;
+    const facts = v.facts;
+    if (facts === null)
+        return true;
+    if (typeof facts !== "object")
+        return false;
+    const f = facts;
+    if (!isWallBytes(f.maxRowBytes) || !isWallBytes(f.maxPacketBytes))
+        return false;
+    const sources = f.wallSources;
+    if (typeof sources !== "object" || sources === null)
+        return false;
+    const src = sources;
+    return isWallSourceWord(src.maxRowBytes) && isWallSourceWord(src.maxPacketBytes);
+}
+export function sqlEngineSeatIssue(backend, sqlEngine) {
+    if (sqlEngine !== undefined)
+        return isSqlEngineReading(sqlEngine) ? undefined : "bad_shape";
+    const { mysqlPool, pgPool } = sqlPoolsOf(backend);
+    return mysqlPool !== undefined || pgPool !== undefined ? "required" : undefined;
+}
 export async function establishSqlEnginePosture(pools) {
     const driver = pools.mysqlPool ? mysqlDriver(pools.mysqlPool) : pools.pgPool ? pgDriver(pools.pgPool) : undefined;
     if (driver === undefined)
         return undefined;
     const conn = await driver.connect();
     conn.release();
-    return () => driver.facts;
+    return driver;
 }
 export function projectSqlEngineCapability(facts) {
     return facts == null ? null : { engine: facts.engine, isolation: facts.isolation, txnMode: facts.txnMode };