@sema-agent/server 7.130.0 → 7.132.0

package/dist/prompts-domain-validate.js

@@ -1,122 +1,12 @@
-import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { verifyPromptArtifact } from "@sema-agent/core";
-import { PROMPT_SLOTS } from "@sema-agent/settings-schema";
-import { SHA256_DIGEST_RE } from "./digest-form.js";
-const ID_RE = /^[a-z0-9][a-z0-9/._-]*$/;
-const SLOTS = PROMPT_SLOTS;
-function declarationIssue(d, where) {
-    if (d === null || typeof d !== "object")
-        return `${where}: declaration is not an object`;
-    const o = d;
-    if (typeof o.id !== "string" || o.id.length === 0 || o.id.length > 128 || !ID_RE.test(o.id))
-        return `${where}: bad id`;
-    if (o.id.startsWith("core/"))
-        return `${where}: id in the reserved core/ namespace`;
-    if (typeof o.slot !== "string" || !SLOTS.includes(o.slot))
-        return `${where}: bad slot`;
-    if (typeof o.text !== "string" || o.text.length === 0)
-        return `${where}: text must be a non-empty string`;
-    if (typeof o.contentHash !== "string" || !SHA256_DIGEST_RE.test(o.contentHash))
-        return `${where}: contentHash is required (sha256:<64hex> — the epoch declaration axis needs it for byte-level change detection)`;
-    const expected = `sha256:${createHash("sha256").update(o.text).digest("hex")}`;
-    if (o.contentHash !== expected)
-        return `${where}: contentHash does not match sha256(text) — stale or altered declaration`;
-    return undefined;
-}
-export function validateCenterPrompts(raw) {
-    if (raw === null || typeof raw !== "object")
-        return { ok: false, error: "prompts is not an object" };
-    const p = raw;
-    if (typeof p.packId !== "string" || !/^center:[0-9a-f]{12}$/.test(p.packId))
-        return { ok: false, error: "bad packId form (center:<digest12>)" };
-    if (typeof p.contentDigest !== "string" || !SHA256_DIGEST_RE.test(p.contentDigest))
-        return { ok: false, error: "bad contentDigest form" };
-    const arrayIssue = (decls, where) => {
-        if (!Array.isArray(decls))
-            return `${where} is not an array`;
-        if (decls.length === 0)
-            return `${where} is empty (an empty replacement set is not a v1 semantic — omit the key instead)`;
-        const seen = new Set();
-        for (let i = 0; i < decls.length; i++) {
-            const issue = declarationIssue(decls[i], `${where}[${i}]`);
-            if (issue)
-                return issue;
-            const id = decls[i].id;
-            if (seen.has(id))
-                return `${where}[${i}]: duplicate id "${id}" (core composer throws on duplicates)`;
-            seen.add(id);
-        }
-        return undefined;
-    };
-    const sectionsIssue = arrayIssue(p.sections, "sections");
-    if (sectionsIssue)
-        return { ok: false, error: sectionsIssue };
-    if (p.scenarioOverrides !== undefined) {
-        if (p.scenarioOverrides === null || typeof p.scenarioOverrides !== "object" || Array.isArray(p.scenarioOverrides)) {
-            return { ok: false, error: "scenarioOverrides is not an object" };
-        }
-        for (const [name, decls] of Object.entries(p.scenarioOverrides)) {
-            const issue = arrayIssue(decls, `scenarioOverrides[${name}]`);
-            if (issue)
-                return { ok: false, error: issue };
-        }
-    }
-    return { ok: true, value: raw };
-}
-export const CORE_ENGINE_VERSION = (() => {
-    try {
-        const entry = createRequire(import.meta.url).resolve("@sema-agent/core");
-        return JSON.parse(readFileSync(join(dirname(entry), "..", "package.json"), "utf8")).version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-})();
-export function validatePromptsDomain(raw) {
-    if (raw === null || typeof raw !== "object")
-        return { ok: false, error: "prompts is not an object" };
-    const w = raw;
-    if (w.schemaVersion === undefined) {
-        return { ok: false, error: "prompts payload has no schemaVersion — the legacy flat shape was retired in 5.0.0; wrap as {schemaVersion:1, declarations:{...}} (registry-core EffectivePromptsWire)" };
-    }
-    if (w.schemaVersion !== 1)
-        return { ok: false, error: `unsupported prompts schemaVersion ${String(w.schemaVersion)}` };
-    if (w.declarations === undefined && w.catalog === undefined)
-        return { ok: false, error: "dual-axis prompts carries neither axis (at least one of declarations|catalog required)" };
-    const value = { identity: "", axes: [] };
-    if (w.declarations !== undefined) {
-        const d = validateCenterPrompts(w.declarations);
-        if (!d.ok)
-            return { ok: false, error: `declarations axis: ${d.error}` };
-        value.declarations = d.value;
-        value.axes.push("declarations");
-    }
-    if (w.catalog !== undefined) {
-        const c = verifyPromptArtifact(w.catalog, { engineVersion: CORE_ENGINE_VERSION });
-        if (!c.ok)
-            return { ok: false, error: `catalog axis: ${c.code}: ${c.reason}` };
-        value.catalog = w.catalog;
-        value.axes.push("catalog");
-    }
-    value.identity = `${value.declarations?.contentDigest ?? "-"}+${value.catalog?.artifact.artifactDigest ?? "-"}`;
-    return { ok: true, value };
-}
-export function centerPromptsFromEffective(eff) {
-    const prompts = eff?.prompts;
-    if (prompts === undefined || prompts === null)
-        return undefined;
-    if (typeof prompts !== "object" || Array.isArray(prompts))
-        return prompts;
-    const o = prompts;
-    if ("schemaVersion" in o)
-        return prompts;
-    if ("packId" in o && "contentDigest" in o && "sections" in o)
-        return prompts;
-    if (o.catalog !== undefined)
-        return { schemaVersion: 1, catalog: o.catalog };
-    return undefined;
+import { EffectivePromptsWire, formatConfigPath, sanitizeZodError } from "@sema-agent/settings-schema";
+export function judgePromptsWire(raw) {
+    const wire = EffectivePromptsWire.safeParse(raw);
+    if (!wire.success) {
+        const issues = sanitizeZodError(wire.error).issues.map((i) => `${i.path.length === 0 ? "prompts" : `prompts.${formatConfigPath(i.path.map((s) => (typeof s === "number" ? s : String(s))))}`}: ${i.message}`);
+        return { ok: false, error: issues.join("; ") };
+    }
+    const verified = verifyPromptArtifact(wire.data.artifact);
+    return verified.ok ? { ok: true, artifact: verified.artifact } : { ok: false, error: `prompts.artifact refused by the engine (${verified.code}): ${verified.reason}` };
 }
 //# sourceMappingURL=prompts-domain-validate.js.map

package/dist/question.d.ts

@@ -23,20 +23,29 @@ export interface QuestionFrame {
     /** "question" only: `serverNowMs + expiresInMs` — absolute deadline on the server's clock. */
     expiresAtMs?: number;
 }
-/** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's live stream; `abortSignal`
- *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts. */
+/** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's stream; `abortSignal`
+ *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts.
+ *
+ *  🔴 ONE LAW for every leg: a question frame that enters a run's stream has a LEDGER TWIN (the row
+ *  `GET /v1/runs/:id/events` replays — a page reload recovers the open card from it); the leg decides only whether it
+ *  ALSO writes a live socket. The background leg has no socket, so its `emit` IS the durable append; the synchronous
+ *  stream leg lands the same frame in the ledger first and then writes the SSE connection (`createLedgerTwinEmit`).
+ *  The ledger carries the CARD, not the answer door: `POST /v1/questions/:id/respond` stays live-only (this replica's
+ *  memory, `ttlMs`), so a replayed card is answerable only until its own `expiresAtMs` and only on this replica. */
 export interface QuestionRunContext {
     taskId: string;
     owner: string | null;
     emit: (frame: QuestionFrame) => void | Promise<void>;
     abortSignal?: AbortSignal;
-    /** OPTIONAL reachability predicate for this leg's delivery face, consulted by {@link QuestionCoordinator.hasLiveContext}
-     *  (the park-vs-live adjudication probe), NOT by `question` itself. CONSTRAINT: a leg whose face can go away WHILE the
-     *  leg keeps running MUST supply it — `/v1/tasks/stream` under `x-detach-on-disconnect: true` keeps executing inside
-     *  this ALS scope after the client left, and `emit` there writes to a dead socket and is silently dropped (question
-     *  frames have no durable ledger twin, unlike SendUserFile's ledgerSink). Without the predicate the adjudication would
-     *  read "live" and hand the leg to a face nobody can reach. ABSENT ⇒ always reachable, which is exactly right for the
-     *  background leg (emit appends to the durable events tail, readable whenever a client attaches). */
+    /** OPTIONAL reachability predicate for this leg's LIVE delivery face — one reading, two consumers:
+     *  {@link QuestionCoordinator.hasLiveContext} (the park-vs-live adjudication probe) and the OPEN frame itself (a face
+     *  that cannot show the card right now refuses the ask on the spot, the same failed-delivery arm, instead of parking it
+     *  to TTL on a ledger row nobody is watching). CONSTRAINT: a leg whose face can go away WHILE the leg keeps running MUST
+     *  supply it — `/v1/tasks/stream` under `x-detach-on-disconnect: true` keeps executing inside this ALS scope after the
+     *  client left. Without the predicate the adjudication would read "live" and hand the leg to a face nobody can reach.
+     *  ABSENT ⇒ always reachable, which is exactly right for the background leg (its face IS the durable events tail,
+     *  readable whenever a client attaches). The CLOSE frame never asks it: it is a record, and it lands in the ledger twin
+     *  whether or not the socket is still there. */
     deliverable?: () => boolean;
 }
 /** The per-run question window the deployment owns (core caps nothing). Env: `QUESTION_MAX_CONCURRENT_PER_RUN` /

package/dist/question.js

@@ -3,6 +3,16 @@ import { uuidv7 } from "@sema-agent/core";
 import { redactDeep } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 const MAX_QUESTIONS_BYTES = 16384;
+function isFaceReachable(ctx) {
+    if (ctx.deliverable === undefined)
+        return true;
+    try {
+        return ctx.deliverable();
+    }
+    catch {
+        return false;
+    }
+}
 export const DEFAULT_QUESTION_THROTTLE = {
     maxConcurrentPerRun: 2,
     maxTotalPerRun: 20,
@@ -103,13 +113,20 @@ export class QuestionCoordinator {
         ctx.abortSignal?.addEventListener("abort", onAbort, { once: true });
         this.pending.set(id, { settle, owner: ctx.owner, taskId: ctx.taskId });
         const emitted = (async () => {
+            if (!isFaceReachable(ctx))
+                throw new Error("question delivery face unreachable — the open frame has nobody to show it to");
             const now = Date.now();
-            return ctx.emit({ type: "question", questionId: id, questions, serverNowMs: now, expiresInMs: this.throttle.ttlMs, expiresAtMs: now + this.throttle.ttlMs });
+            await ctx.emit({ type: "question", questionId: id, questions, serverNowMs: now, expiresInMs: this.throttle.ttlMs, expiresAtMs: now + this.throttle.ttlMs });
+            return isFaceReachable(ctx) ? "ok" : "landed-face-gone";
         })()
-            .then(() => "ok", () => "failed");
+            .then((r) => r, () => "failed");
         const delivery = await Promise.race([emitted, answerP.then(() => "stalled")]);
-        if (delivery === "ok") {
+        if (delivery === "ok" || delivery === "landed-face-gone") {
             rc.total += 1;
+            if (delivery === "landed-face-gone") {
+                recordFailOpen("server.question.open-frame-undelivered", `question=${id} face-gone-while-landing`);
+                settle(UNAVAILABLE, "unanswered");
+            }
         }
         else if (delivery === "failed") {
             recordFailOpen("server.question.open-frame-undelivered", `question=${id}`);
@@ -146,16 +163,7 @@ export class QuestionCoordinator {
     }
     hasLiveContext() {
         const ctx = this.als.getStore();
-        if (ctx === undefined)
-            return false;
-        if (ctx.deliverable === undefined)
-            return true;
-        try {
-            return ctx.deliverable();
-        }
-        catch {
-            return false;
-        }
+        return ctx !== undefined && isFaceReachable(ctx);
     }
     countersFor(taskId) {
         let rc = this.counters.get(taskId);

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

@@ -1,8 +1,8 @@
 /** 拒体里逐字回显的键名条数上限。键名原样回显(不猜语义),但**条数有界** —— 一个塞满键的体不许把 400 响应
  *  放大成流量面。超出部分只报数。 */
 export declare const MAX_KEY_ECHO = 20;
-/** 键名回显的清洗:剥控制/双向字符(键名进的是 JSON 错误体与运维日志,一个 RLO 能把两行字读反),
- *  再按 {@link MAX_KEY_ECHO_CHARS} 截断。清洗之外**逐字**,不做大小写/近似猜测。 */
+/** 键名回显 = 前缀 + 调用方串的唯一回显口径(`caller-text-echo.ts`:剥控制 / 双向字符、截到 64 字 + …;键名进的是 JSON 错误体与运维日志,
+ *  一个 RLO 能把两行字读反)。清洗之外**逐字**,不做大小写/近似猜测。 */
 export declare function echoKeyName(prefix: string, key: string): string;
 /** 一次键闭集裁决的产物:一句 wire 文案 + 两张分类键名表(消费端可机读,不必解析文案)。 */
 export interface KeyClosureIssue {
@@ -54,9 +54,9 @@ export type ContentSteerBody = {
 export type InterruptSteerBody = {
     readonly [K in (typeof INTERRUPT_STEER_BODY_KEYS)[number]]?: unknown;
 };
-/** 送话口的三种体形(闭集;词外是编译错)。 */
+/** 送话口的体形(闭集;词外是编译错)。`interrupt` = `POST /v1/runs/:id/interrupt` 整扇门(bare 与带 `text` 两形同一张受理集)。 */
 export type SteerBodyForm = "run" | "content" | "interrupt";
-/** 送话口的顶层键裁决(四扇门同一只;`form` 选受理集)。 */
+/** 送话口的顶层键裁决(各形同一只;`form` 选受理集)。 */
 export declare function steerBodyKeyIssue(raw: unknown, form: SteerBodyForm): KeyClosureIssue | null;
 export {};
 //# sourceMappingURL=request-key-closure.d.ts.map

package/dist/request-key-closure.js

@@ -1,9 +1,7 @@
-import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
+import { echoCallerText } from "./caller-text-echo.js";
 export const MAX_KEY_ECHO = 20;
-const MAX_KEY_ECHO_CHARS = 64;
 export function echoKeyName(prefix, key) {
-    const clean = key.replace(CONTROL_AND_BIDI_STRIP_RE, "");
-    return `${prefix}${clean.length > MAX_KEY_ECHO_CHARS ? `${clean.slice(0, MAX_KEY_ECHO_CHARS)}…` : clean}`;
+    return `${prefix}${echoCallerText(key)}`;
 }
 export function scanKeyClosure(bag, prefix, accepted, tolerated, into) {
     for (const k of Object.keys(bag)) {
@@ -28,25 +26,28 @@ const TASK_BODY_DECLARED_KEYS = [
     "resilience", "restoreFiles", "resumeAt", "resumeAtMode", "retainBackgroundProcesses", "retainSubagentSessions",
     "rewindFiles", "rewindFilesTo", "sandboxImageProfile", "scenario", "scratchpadDir", "selfOrchestration",
     "sessionId", "settings", "skills", "suggestNextPrompts", "systemPrompt", "taskId", "toolMaterializeStrategy",
-    "userInvokedSkills", "verify", "verifyRounds",
+    "userAttachments", "userInvokedSkills", "verify", "verifyRounds",
 ];
 const TASK_BODY_SCENARIO_KEYS = ["repo"];
 const ACCEPTED_BODY = new Set([...TASK_BODY_DECLARED_KEYS, ...TASK_BODY_SCENARIO_KEYS]);
-const UNSUPPORTED_BODY_KEYS = ["handsReadOnly", "readDenyPatterns", "readFace", "shellGate", "userAttachments", "writeFace"];
-const UNSUPPORTED_BODY = new Set(UNSUPPORTED_BODY_KEYS);
-const UNSUPPORTED_LABEL = "unsupported (an engine seat this service does not read from the request body — set by the deployment, or not offered in this version)";
-function closedBodyKeyIssue(raw, accepted, door) {
+const UNSUPPORTED_BODY_KEYS = ["handsReadOnly", "readDenyPatterns", "readFace", "shellGate", "writeFace"];
+const UNSUPPORTED_BODY = {
+    keys: new Set(UNSUPPORTED_BODY_KEYS),
+    label: "unsupported (an engine seat this door does not read from the request body — set by the deployment)",
+};
+const OBJECTIVE_ONLY_BODY_KEYS = ["userAttachments"];
+function closedBodyKeyIssue(raw, accepted, unsupported, door) {
     if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
         return null;
     const buckets = { unknown: [], unsupported: [] };
-    scanKeyClosure(raw, "", accepted, UNSUPPORTED_BODY, buckets);
+    scanKeyClosure(raw, "", accepted, unsupported.keys, buckets);
     if (buckets.unknown.length === 0 && buckets.unsupported.length === 0)
         return null;
     buckets.unknown.sort();
     buckets.unsupported.sort();
     const parts = [
         ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, `unknown (not ${door} key — check the spelling)`)] : []),
-        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, UNSUPPORTED_LABEL)] : []),
+        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, unsupported.label)] : []),
     ];
     return {
         message: `body: unrecognized top-level key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
@@ -57,7 +58,7 @@ function closedBodyKeyIssue(raw, accepted, door) {
     };
 }
 export function taskBodyKeyIssue(raw) {
-    return closedBodyKeyIssue(raw, ACCEPTED_BODY, "a task-request");
+    return closedBodyKeyIssue(raw, ACCEPTED_BODY, UNSUPPORTED_BODY, "a task-request");
 }
 const RUN_STEER_BODY_KEYS = ["mode", "priority", "text"];
 const CONTENT_STEER_BODY_KEYS = ["content"];
@@ -67,7 +68,11 @@ const STEER_DOORS = {
     content: { accepted: new Set(CONTENT_STEER_BODY_KEYS), door: "a steer-request" },
     interrupt: { accepted: new Set(INTERRUPT_STEER_BODY_KEYS), door: "an interrupt-request" },
 };
+const STEER_UNSUPPORTED = {
+    keys: new Set([...UNSUPPORTED_BODY_KEYS, ...OBJECTIVE_ONLY_BODY_KEYS]),
+    label: "unsupported (an engine seat this door does not read from the request body — set by the deployment, or carried only by a new objective)",
+};
 export function steerBodyKeyIssue(raw, form) {
-    return closedBodyKeyIssue(raw, STEER_DOORS[form].accepted, STEER_DOORS[form].door);
+    return closedBodyKeyIssue(raw, STEER_DOORS[form].accepted, STEER_UNSUPPORTED, STEER_DOORS[form].door);
 }
 //# sourceMappingURL=request-key-closure.js.map

package/dist/rule-entry-list.d.ts

@@ -11,15 +11,25 @@
  *     请求 allow 桶、技能两只清单、运维表四张表同一只、同一句)。
  *  ② (7.116.0–7.122.x 的「引擎读不到的一形」—— 工具段为空的协议名 `mcp__srv__` 四张表都拒 —— 随 core 7.48.0 #1400 退役:引擎判官给它判词
  *     `unmintable_segment`,条目由下面 ③ 读成 `tool_name`,与对端段铸不出的名字同一条路。)
- *  ③ **引擎读成空的条目**({@link inertRuleEntriesOf},判据 = 引擎包根 `compileAllowList(entries, behavior, 名册)`,名册 = 空集 `NO_DECLARED_TOOL_NAMES`
- *     —— 条目的工具名也过引擎判官:退役名 / 无前缀短名 / 对端段或工具段铸不出、为空读成 `tool_name`,带判词与 1:1 现名;原因词是引擎的 `ALLOW_ENTRY_INERT_REASONS`):
- *     运维的 allow 表拒启(运维自己的配置,写错了当场改);技能的拒侧(`disallowedTools`)拒 —— 提交 400、存量体重放 409(下面的 {@link skillDenyInertEntryOf});
- *     请求的 allow 侧(`settings.permissions.allow`、技能 `allowedTools`)不拒:引擎在开跑时发 `permission.allowed_tool_not_granted`(受众 = 用户)。
+ *  ③ **引擎读成空的条目**({@link inertRuleEntriesOf},判据 = 引擎包根 `compileAllowList(entries, behavior, 名册)`;原因词是引擎的 `ALLOW_ENTRY_INERT_REASONS`)。
+ *     条目的工具名也过引擎判官:退役名 / 无前缀短名 / 对端段或工具段铸不出、为空读成 `tool_name`,带判词与 1:1 现名;名册里有那只工具、条目只差大小写 ⇒ `near_miss`(`BASH` ⇒ 现名 `Bash`)。
+ *     **名册只有一张**({@link TOOL_NAME_ROSTER}:引擎目录 ∪ 本仓自铸的工具名),每一处读条目名的地方都传它 —— 请求体的规则表(`settings.permissions.*`)、技能清单、选择器清单、
+ *     运维 / 中心的审批名单读同一份,没有「这一处空名册、那一处带名册」的两种读法。
+ *     **读成空的哪些原因词是拒面,按方向定**:**限制侧**(读成空 = 静默放行:技能 `disallowedTools`、`excludeTools` / 子代 `denyTools`、`settings.permissions.deny` / `ask`、运维 / 中心的审批名单)四类全拒 ——
+ *     近似名 · 退役名 · 文法读不出 · 不带内容形的工具带内容;**放行侧**(读成空 = 想放的什么也没放:`settings.permissions.allow`、根 / 子代 `allowTools`、技能 `allowedTools`)**只拒近似名**
+ *     ({@link allowSideReadsAsNothing}):近似名现名唯一、确定是笔误;退役名 / 内容形 / 文法读不出 / 协议名对端段通配照 7.130.0 受理、交引擎既有通告(其中选择器清单 `allowTools` 里**有后继**的退役名〔`Task` ⇒ `Agent`、`bash` ⇒ `Bash`〕core 7.52.0 起由引擎开跑前拒,不在本仓拒面;规则表上的退役名引擎照旧告运维 ——
+ *     壳转投的 CC 用户 settings 里这些极常见,尤其内容形里的 `$VAR`(`Bash(echo $HOME)`)读成 `grammar`,拒了 = 每次提交 400)。运维的 `APPROVAL_GRANT` 是运维自己的配置:任何读成空都拒启(写错了当场改)。
  *     技能拒侧那一拒与引擎 #1372(core 7.43.0:那只技能不激活)是同一件事的两处 —— 7.118.0 重估过、本版**不退**:本仓的续跑腿把引擎的
  *     `checkpoint.config_refused`(`config.skill_deny_unreadable`)答得不一(资源停车续跑腿 500、`/decide` 先结了卡、`/wake` 先铸了 run 行),先统一那一层再退
- *     (重估读数与退役条件在下面那只函数头注)。
+ *     (重估读数与退役条件在下面 {@link skillDenyInertEntryOf} 头注)。
+ *  ④ **工具名选择器清单**(请求顶层 `allowTools` / `excludeTools`、子代定义的 `allowTools` / `denyTools`;引擎的可用性选择器,**不是**规则条目表):读成空的条目在受理口**开跑前拒并点名现名**
+ *     (拒面按 ③ 的方向分),拒句点名有界({@link MAX_NAMED_INERT_ENTRIES} 条 + 计数),清单先过条数帽({@link inertToolListEntryOf})。
+ *     **真未知名**(拼写合法、没有近似也没有退役对应 —— 懒挂载的合法形,例如一台之后才连上的 MCP 服务器的工具)不是读成空:原样保留、运维行告知一次,不拒。
+ *     选择器读一条条目 = 引擎 `judgeToolNameList` 的读法({@link selectorEntryName}):先取工具名那一段再只判名字(限制侧 `Tool(content)` ⇒ 整只工具,内容里写什么都不读;放行侧内容形引擎告「什么也不授」,受理口不拒);
+ *     `*` 在放行侧是「本层不设名单」、在限制侧读成空;限制侧 `mcp__*` / `a2a__*`(整个协议的拒)合法。
  */
 import { compileAllowList } from "@sema-agent/core";
+import { type LimitRefusal } from "./limit-refusal.js";
 /** ① 形:字符串数组(空串也是字符串 —— 引擎把它读成 `grammar` 并通告 / 拒,见 ③)。 */
 export declare const ruleEntryListShapeOk: (v: unknown) => v is readonly string[];
 /**
@@ -33,45 +43,145 @@ export declare const ruleEntryListShapeOk: (v: unknown) => v is readonly string[
  * 没有真实用法需要上千条」。抬不抬这个数是产品判断,不随提货改。
  */
 export declare const MAX_ALLOW_LAYER_ENTRIES = 1000;
-/** 超帽的拒句(不截:截掉的尾项读起来像「在生效」)—— 句子的唯一铸点(请求 allow 桶的 wire 拒体按字段重铸也调它)。 */
+/** 超帽的拒句({@link allowLayerOverCap} 的句子;请求 allow 桶的拒句按字段重铸时读它)。 */
 export declare function describeAllowLayerOverCap(field: string, count: number): string;
-/** 一张条目表超了 {@link MAX_ALLOW_LAYER_ENTRIES} ⇒ 拒句 + 机读两数;没超 ⇒ `undefined`。四张表同调这一只。 */
-export declare function allowLayerEntryCountIssue(field: string, list: readonly unknown[]): {
-    readonly message: string;
-    readonly count: number;
-    readonly cap: number;
-} | undefined;
+/** 一张条目表超了 {@link MAX_ALLOW_LAYER_ENTRIES} ⇒ 拒(句子 + 机读位 `field` / `reason: "over_cap"` / `count` / `cap`);没超 ⇒ `undefined`。四张表同调这一只。 */
+export declare function allowLayerEntryCountIssue(field: string, list: readonly unknown[]): LimitRefusal | undefined;
 /** 一条引擎读成空的条目(引擎的形:原因词,名字层另带判词 / 1:1 现名;包根不导出这只具名型 ⇒ 从 `compileAllowList` 的返回型取,不手抄)。 */
 export type InertRuleEntry = ReturnType<typeof compileAllowList>["inert"][number];
-/** ③ 引擎按 `behavior` 读这张表时读成空的条目(引擎的整表读法:allow 表里的 `*` 让整表读成空;deny 表里的 `*` 只读空它自己);条目名过引擎判官(名册 = 空集)。 */
+/**
+ * ③ 引擎读一张**规则条目表**(`behavior` 方向)时读成空的条目(引擎的整表读法:allow 表里的 `*` 让整表读成空;deny 表里的 `*` 只读空它自己)。条目名过引擎判官,
+ * 名册是本仓**唯一**的一张({@link TOOL_NAME_ROSTER},`namespaced-rule-name.ts`:引擎目录 ∪ 本仓自铸的工具名)—— 两个方向、每一处读条目名的地方(请求体的规则表、技能清单、选择器清单、
+ * 运维 / 中心的审批名单)传同一张,没有「这一处空名册、那一处带名册」的两种读法。工具名选择器清单另走 {@link inertToolListEntryOf}。
+ */
 export declare function inertRuleEntriesOf(list: readonly string[], behavior: "allow" | "deny"): readonly InertRuleEntry[];
 /**
  * 原因词 → 「怎么写」(闭集穷举:引擎加一个原因词 ⇒ 编译红)。句子只说这一条为什么什么也不做、换成哪种写法;原因词本身原样带在句子里。
  * 名字层两词带引擎给的判词 / 1:1 现名(有就点名)。
  */
 export declare function inertRuleEntryGuidance(i: InertRuleEntry): string;
-/** ③ 的句子(`<field> entry "<e>" reads as nothing (<reason>): <怎么写>`;多条用分号连)。 */
+/**
+ * 拒句 / 通告句里点名条目的**条数上界**(点名有界,同引擎自己通告的「最多五条 + and N more」一个形:体再大,一句话的长度不随条目数长)。
+ * 每条点名至多约 600 字节(条目回显 ≤ 122 字符 + 原因词 + 引擎的怎么写),五条 + 尾 ≤ 3.5 KB。
+ */
+export declare const MAX_NAMED_INERT_ENTRIES = 5;
+/** ③ 的句子(`<field> entry "<e>" reads as nothing (<reason>): <怎么写>`;多条用分号连;只点名前 {@link MAX_NAMED_INERT_ENTRIES} 条,其余写成 `; and K more`)。全部读成空的句子的**唯一组句器**。 */
 export declare function describeInertRuleEntries(field: string, inert: readonly InertRuleEntry[]): string;
 /** 提交体里技能所在的层(命中句与排空读数点名用):顶层 `skills[]` / 子代 `agents[].skills[]`。 */
 export type SkillListLayer = "skills" | "agents.skills";
-/** 一份提交体里第一处「技能的拒侧清单里有引擎读成空的条目」:在哪一层、拒句是什么。 */
-export interface SkillDenyInertEntry {
-    readonly layer: SkillListLayer;
+/** 清单的方向:`allow` = 放行名单(读成空 = 想放的什么也没放 = 静默收窄),`deny` = 限制名单(读成空 = 放行)。续跑重放按方向分流(见 {@link inertToolListEntryOf})。 */
+export type ToolListSide = "allow" | "deny";
+/**
+ * 每一张清单(闭集;"层")的方向、读法与拒码。拒码沿用该清单此前的码:技能与请求规则表 ⇒ 请求字段非法;子代定义的两张选择器 ⇒ 引擎的子代名单拒码;顶层两张选择器 ⇒ 引擎的
+ * 根 run 名单拒码(同一张表的文法形 / `*` 引擎仍拒这一码,一张表一个码)。续跑腿把同一只码放进 409 的 `blockedBy`。加一张清单 ⇒ 这里加一行,{@link toolListsOf} 的扫描一起编译红。
+ */
+declare const TOOL_LIST_FACES: {
+    readonly skills: {
+        readonly side: "deny";
+        readonly kind: "rule_table";
+        readonly code: "request.field_invalid";
+    };
+    readonly "agents.skills": {
+        readonly side: "deny";
+        readonly kind: "rule_table";
+        readonly code: "request.field_invalid";
+    };
+    readonly "skills.allowedTools": {
+        readonly side: "allow";
+        readonly kind: "rule_table";
+        readonly code: "request.field_invalid";
+    };
+    readonly "agents.skills.allowedTools": {
+        readonly side: "allow";
+        readonly kind: "rule_table";
+        readonly code: "request.field_invalid";
+    };
+    readonly "agents.denyTools": {
+        readonly side: "deny";
+        readonly kind: "selector";
+        readonly code: "config.agent.unknown_tool";
+    };
+    readonly "agents.allowTools": {
+        readonly side: "allow";
+        readonly kind: "selector";
+        readonly code: "config.agent.unknown_tool";
+    };
+    readonly excludeTools: {
+        readonly side: "deny";
+        readonly kind: "selector";
+        readonly code: "config.tool_face_control";
+    };
+    readonly allowTools: {
+        readonly side: "allow";
+        readonly kind: "selector";
+        readonly code: "config.tool_face_control";
+    };
+    readonly "settings.permissions.allow": {
+        readonly side: "allow";
+        readonly kind: "rule_table";
+        readonly code: "request.field_invalid";
+    };
+};
+/** 提交体里读成空即拒的工具名清单所在的层(闭集 = {@link TOOL_LIST_FACES} 的键)。 */
+export type ToolListLayer = keyof typeof TOOL_LIST_FACES;
+/**
+ * 请求体 `settings.permissions.deny` / `ask`(规则编译器读的收紧表)所在的层 —— **不在** {@link toolListsOf} 的扫描里:它们的判与句子的唯一铸点在 `config.ts` 的
+ * `unmatchableToolNamesRefusal`(经 `task-settings.ts` 的 `rulePolicyBucketsRefusal`,单表桶序;拒点是 `applyTaskSettings`,422),存体预判(`http/stored-body-replay.ts`)调同一只函数(home 同源于部署配置),把命中装成本型。
+ * 层名进这个联合只为让命中能带坐标进 409 体与运维日志。
+ */
+export type RulePolicyLayer = "settings.permissions.deny" | "settings.permissions.ask";
+/** 一份提交体里第一处「工具名清单里有引擎读成空的条目」:在哪一层、哪个方向、拒码、拒句(超帽时另带机读字段,同 `settings.permissions.*` 桶超帽的形)。 */
+export interface InertToolListEntry {
+    readonly layer: ToolListLayer | RulePolicyLayer;
+    readonly side: ToolListSide;
+    readonly code: string;
     readonly message: string;
+    readonly extra?: Readonly<Record<string, unknown>>;
 }
 /**
- * ③ 的拒侧在**提交体**上的判(顶层 `skills[]` 与子代 `agents[].skills[]` 两层;第一处命中即答)。
+ * 存体预判里请求设置的命中装成本型(拒点自己抛:桶门在 `resolveSpec` 抛 400、deny / ask 的名字层与文法在 `applyTaskSettings` 抛 422,都不经本型)—— 两个来源一只装配函数:
+ * 桶门命中(三个桶任一,带机读字段 `extra`)与 deny / ask 的规则判命中(限制侧,无 `extra`)。
+ */
+export declare function replayInertEntry(layer: ToolListLayer | RulePolicyLayer, side: ToolListSide, code: string, message: string, extra?: Readonly<Record<string, unknown>>): InertToolListEntry;
+/** 技能层的命中(排空脚本只数这两层)。 */
+export interface SkillDenyInertEntry extends InertToolListEntry {
+    readonly layer: SkillListLayer;
+}
+/**
+ * 一条技能(顶层 `skills[k]` / 子代 `agents[i].skills[j]`,`at` = 它的体内坐标)两只清单的**条数帽**:先 `allowedTools` 后 `disallowedTools`(与 7.131.0 的判序同)。
+ * 判与句子就是 {@link overCapOfList} 那一只(拒点 `resolveSpec` 两腿同经的 {@link inertToolListEntryOf} 先过的也是它):受理口在技能的两道形门处调它
+ * (`http/admission.ts` 的 `validateUserSkills` 与 `spec-fields.ts` 的 `validateTaskAgents`:两道门都逐条先形、后帽 —— 与 7.131.0 的拒点与判序同,码与先后不变),句子与机读位点体内坐标。
+ */
+export declare function skillToolListsOverCap(skill: unknown, at: string, scope: "top" | "agent"): InertToolListEntry | undefined;
+/**
+ * ③ 的拒侧在**提交体**上的判,技能那两层(顶层 `skills[]` 与子代 `agents[].skills[]`;第一处命中即答)。全部工具名清单的判是 {@link inertToolListEntryOf}(调用点两处都调它);
+ * 本函数单独导出是给随包排空脚本:那条判据(`skill-deny-inert`)只数技能这两层,SQL 车道的孪生也只看技能的清单。
  *
- * 🔴 **调用点两处**:`resolveSpec`(`boot/resolve-spec.ts`,**拒点** —— 新提交与五条续跑腿都经过它,所以「新提交会被拒的体,续跑重放时同样拒」
- * 是结构性的)与 `http/checkpoint-ctx.ts` `storedBodyReplayRefusal`(存量体重放前的**预判**,五个续跑问点同调 —— 含 SLA 拒扫的跳过臂与终态 steer
- * 铸唤醒卡之前,这两处不经 `resolveSpec`)。提交腿 ⇒ 400 `request.field_invalid`;续跑腿 ⇒ 409 `resume_blocked_by_policy`(`blockedBy: request.field_invalid`,
- * 句子同一句,铸点 `checkpoint-ctx.ts` `resumeBlockedByPolicyAnswer`),拒在认领之前,行 / 卡 / ctx 不动。随包排空判据 `skill-deny-inert`
- * (`scripts/drain-check-local.mjs` 调本函数)。判据就是引擎的读法(`compileAllowList(entries, "deny", 名册 = 空集)`,与 {@link inertRuleEntriesOf} 同一只;
- * 7.118.0 起条目名也过引擎判官,退役名 / 对端段铸不出读成 `tool_name` —— 技能清单的名字层在受理口不再另判)。
+ * 判据就是引擎的读法({@link inertRuleEntriesOf};7.118.0 起条目名也过引擎判官,退役名 / 对端段铸不出读成 `tool_name` —— 技能清单的名字层在受理口不再另判)。
  * 7.118.0 重估(core 7.43.0 #1372 到货:读成空的拒侧条目让那只技能不激活)—— **本版不退**。实测(本判退掉之后跑同一批夹具):引擎的拒到本仓各续跑腿的
  * 答法不一 —— 资源停车续跑腿把 `checkpoint.config_refused` 答成 500 `internal.error`;工具审批 `/decide` 在引擎拒之前已把卡结掉;`/wake` 在引擎拒之前已铸
  * run 行;子代 `agents[].skills[]` 不在引擎的认领前屏里(续跑放行、技能在调用时被拒)。退役条件:本仓续跑腿对引擎 `checkpoint.config_refused` 的答法
  * 收成一只(拒在认领前、行 / 卡不动、同一个 409)之后,本判与本仓的预判一起退,排空判据随之重估。
  */
 export declare function skillDenyInertEntryOf(body: unknown): SkillDenyInertEntry | undefined;
+/**
+ * **凡工具名清单,读成空的条目 = 开跑前拒并点名现名;真未知名只告** —— 提交体上全部这类清单的判(见 {@link TOOL_LIST_FACES}:技能的 `disallowedTools` 两层、子代定义的 `denyTools` / `allowTools`、
+ * 顶层 `excludeTools` / `allowTools`、请求的 `settings.permissions.allow`;第一处命中即答,顺序见 {@link toolListsOf})。判官只有一只:引擎的条目读法(名册 = {@link TOOL_NAME_ROSTER}),
+ * 本函数只是「在体的哪几处取清单」;句子只有一个有界的组句器({@link describeInertRuleEntries}),清单先过条数帽({@link allowLayerEntryCountIssue})。
+ *
+ * 为什么限制侧四类全拒、放行侧只拒近似名:引擎 7.51.x 把「没有任何工具答应的名字」改成条目原样保留 + 运维行告知一次。限制侧读成空 = **静默放行**(`denyTools:["BASH"]` 以为禁了 `Bash`,子代照用);
+ * 放行侧读成空 = 想放的什么也没放 —— 其中**近似名**(现名唯一)是确定的笔误,拒并点名现名;**退役名**(选择器清单里有后继的由引擎开跑前拒)、**内容形**与**文法读不出**在放行侧照 7.130.0 受理、交引擎既有通告(见头注 ③)。
+ * **真未知名**(没有近似也没有退役对应)不在读成空之列,原样保留、告运维一次(之后挂上同名工具即生效)。请求的 `settings.permissions.deny` / `ask`
+ * 与运维 / 中心的审批名单读同一张名册,走另一只入口({@link unmatchableToolNamesRefusal},`config.ts`),不在本函数(存体预判调同一只判据、home 同源于部署配置,见 `http/stored-body-replay.ts`)。
+ *
+ * `sides` = 只看哪个方向的清单(缺省两个都看)。**条数帽是资源帽,不分方向**:超帽的清单(整只拒,不逐条读)在任一方向的过滤下都命中 —— 引擎每次准备都逐条播种这些表,一份超帽的清单不论条目读得出读不出都会卡住事件循环。
+ * **提交腿两个方向都拒**;**续跑重放按方向分流**:限制方向(`deny`)的存量条目读成空 ⇒ 拒(409:放宽方向不能默认,那条限制从没生效过);放行方向(`allow`)的存量条目读成空 ⇒ 照旧续跑、条目原样留着
+ * (升级前它本就这样跑着、没那只工具,继续是安全方向)+ 一行运维 warn。
+ *
+ * 🔴 **调用点两处**:`resolveSpec`(`boot/resolve-spec.ts`,**拒点** —— 新提交与五条续跑腿都经过它)与 `http/stored-body-replay.ts` `storedBodyReplayRefusal`
+ * (存量体重放前的**预判**,五个续跑问点同调,只问限制方向)。提交腿 ⇒ 400,码 = 该层的拒码;续跑腿 ⇒ 409 `resume_blocked_by_policy`(`blockedBy` = 同一只码,句子同一句,铸点
+ * `checkpoint-ctx.ts` `resumeBlockedByPolicyAnswer`),拒在认领之前,行 / 卡 / ctx 不动。
+ */
+export declare function inertToolListEntryOf(body: unknown, sides?: readonly ToolListSide[]): InertToolListEntry | undefined;
+export {};
 //# sourceMappingURL=rule-entry-list.d.ts.map