@sema-agent/server 7.131.0 → 7.133.0

package/dist/hooks/hook-source.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 请求面**来源**闭集 —— 一个 hook 组(`settings.hooks[event][i].source`)是谁写的。词表与「托管与否」的映射**只在这里**;
+ * hooks 执行器按它分车道(`hook-runner.ts` 的三相),将来请求面别处的来源键(MCP 服务器条目)读同一张词表,不另立第二份。
+ *
+ * 词表(闭集;集外词 = 形错,受理面整份拒,fail-closed;缺席 = 非托管):
+ *  · `managedPolicy`          —— 组织策略(托管设置)。**托管**,且是终判相。
+ *  · `managedPlugin:<name>`   —— 托管设置启用的插件(壳在「只许托管 hook」治理下仍保留它们)。**托管**。
+ *  · `user` / `project` / `local` / `flag` —— 设置文件的各层与启动时给的 `--settings`。非托管。
+ *  · `plugin:<name>`          —— 用户启用的插件。非托管(来源不可信)。
+ * `<name>` 非空、至多 {@link MAX_HOOK_SOURCE_NAME_CHARS} 字;**名只留痕,不作判据**(相只看前缀)。
+ */
+/** 不带名的来源词 → 它跑在哪一相。`satisfies Record<…>`:加一个词不写相 = 编译红。 */
+declare const HOOK_SOURCE_WORD_PHASE: {
+    readonly managedPolicy: "managedPolicy";
+    readonly user: "unmanaged";
+    readonly project: "unmanaged";
+    readonly local: "unmanaged";
+    readonly flag: "unmanaged";
+};
+/** 带名的来源前缀(`<prefix>:<name>`)→ 它跑在哪一相。 */
+declare const HOOK_SOURCE_PREFIX_PHASE: {
+    readonly managedPlugin: "managedPlugin";
+    readonly plugin: "unmanaged";
+};
+type HookSourceWord = keyof typeof HOOK_SOURCE_WORD_PHASE;
+type HookSourcePrefix = keyof typeof HOOK_SOURCE_PREFIX_PHASE;
+/** 一个 hook 组的来源(闭集;见文件头)。 */
+export type HookGroupSource = HookSourceWord | `${HookSourcePrefix}:${string}`;
+/**
+ * 执行相 —— **固定次序**就是这张数组的次序:非托管 → 托管插件 → 托管策略(终判)。后一相在前一相的最终输入上跑;结果按信任序(倒序)读。
+ * 托管 = 后两相;非托管与托管各一只事件墙钟(见 `hook-runner.ts`)。
+ */
+export declare const HOOK_PHASES: readonly ["unmanaged", "managedPlugin", "managedPolicy"];
+export type HookPhase = (typeof HOOK_PHASES)[number];
+/** 来源的名的长度上限(`managedPlugin:` / `plugin:` 之后那一段)。 */
+export declare const MAX_HOOK_SOURCE_NAME_CHARS = 128;
+/** 受理面的读法:合形 ⇒ 来源;否则 `undefined`(调用方铸拒)。只认 own 词(`Object.hasOwn`:原型上的名字不是词表成员)。 */
+export declare function readHookGroupSource(raw: unknown): HookGroupSource | undefined;
+/** 来源 → 相。缺席 ⇒ 非托管(老包不带 `source`:行为与此前逐字同)。 */
+export declare function hookPhaseOf(source: HookGroupSource | undefined): HookPhase;
+/** 拒句里的词表(由两张表派生,不另写一份)。 */
+export declare const HOOK_SOURCE_VOCABULARY_SENTENCE: string;
+export {};
+//# sourceMappingURL=hook-source.d.ts.map

package/dist/hooks/hook-source.js

@@ -0,0 +1,40 @@
+const HOOK_SOURCE_WORD_PHASE = {
+    managedPolicy: "managedPolicy",
+    user: "unmanaged",
+    project: "unmanaged",
+    local: "unmanaged",
+    flag: "unmanaged",
+};
+const HOOK_SOURCE_PREFIX_PHASE = {
+    managedPlugin: "managedPlugin",
+    plugin: "unmanaged",
+};
+export const HOOK_PHASES = ["unmanaged", "managedPlugin", "managedPolicy"];
+export const MAX_HOOK_SOURCE_NAME_CHARS = 128;
+export function readHookGroupSource(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    if (Object.hasOwn(HOOK_SOURCE_WORD_PHASE, raw))
+        return raw;
+    const colon = raw.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const prefix = raw.slice(0, colon);
+    const name = raw.slice(colon + 1);
+    if (!Object.hasOwn(HOOK_SOURCE_PREFIX_PHASE, prefix))
+        return undefined;
+    if (name.length === 0 || name.length > MAX_HOOK_SOURCE_NAME_CHARS)
+        return undefined;
+    return raw;
+}
+export function hookPhaseOf(source) {
+    if (source === undefined)
+        return "unmanaged";
+    if (Object.hasOwn(HOOK_SOURCE_WORD_PHASE, source))
+        return HOOK_SOURCE_WORD_PHASE[source];
+    return HOOK_SOURCE_PREFIX_PHASE[source.slice(0, source.indexOf(":"))];
+}
+export const HOOK_SOURCE_VOCABULARY_SENTENCE = `${Object.keys(HOOK_SOURCE_WORD_PHASE).join(" / ")}, or ${Object.keys(HOOK_SOURCE_PREFIX_PHASE)
+    .map((p) => `${p}:<name>`)
+    .join(" / ")} with a non-empty name of at most ${MAX_HOOK_SOURCE_NAME_CHARS} characters`;
+//# sourceMappingURL=hook-source.js.map

package/dist/http/active-run-conflict.d.ts

@@ -39,16 +39,8 @@ export declare const ACTIVE_RUN_CONFLICT_BASE_TEXT = "session already has an act
  * **不是** token 摘要,理由是「最需要它的投影面恰恰是拿不到 token 的那些」——本载体就是其中之一)。
  * ⚠️ 它**不是** askId 的替代:askId 是 `approval_ask` 行的身份,checkpointId 是 checkpoint 行的身份,
  * 两者一对多且今天仍无反查读口(那条记账原样有效,别据本键认为它已销账)。
- * ⚠️ **辖域如实**:本批只把这一位投到**本载体**(409 体 + 其 done 帧)。另外三条 park 读面今天都**没有**
- * 这一格,而且它们的**代价不同**(亲核过读面真码,别按一句「都补上」估工):
- *   · `/v1/assistant/inbox` 读 `listByScope` ⇒ core 的 `CheckpointSummary`,**值已经在手**(core
- *     `summarizeCheckpoint` 单源投影里就带着),补它 = 那张显式白名单上加一行,零 SQL 面;
- *   · `GET /v1/approvals` 与 `/v1/approvals/stream` 读的是**本仓自己的** `PendingCheckpoint`
- *     (`checkpoint-store-sql.ts` 的 `listPending`,**按列 SELECT、刻意不拉 blob** —— 那是它避免读放大
- *     的既定姿势),所以这一位**不在手**:要补得给 checkpoint 表反范式一列(与 `gate_kind` /
- *     `bound_input_hash` / `risk_descriptor` 同族)⇒ **SQL 面 = 双库集成门**,不是顺手一行。
- * 补它们是另一批的事(各自过三问:谁需要跨面 join、join 不上谁受伤、补偿是什么),别在文档或消费码里
- * 预支「两面能对上」。
+ * 7.133.0 起三条 durable 读面(运维队列行 `GET /v1/approvals` + `/v1/approvals/stream` 帧、停驻收件 `GET /v1/assistant/inbox` 行)同带这一格,
+ * 同一信任边界({@link trustedCheckpointId}),在那三面上它是 join 键(有可信值就带;缺它的行照列、键缺席 + 计数,见 `checkpoint-identity.ts`)。
  *
  * 🔴 **keyset 门辖域外,故在此成文**:`src/trace/core-keyset-guard.ts` 的七个面是
  * TaskNotificationPayload / BackgroundChildEvent / RosterEntry / AskRequest+ToolApprovalFrame /
@@ -62,11 +54,11 @@ export interface PendingGateMaterial {
     /** 见 {@link PendingGateMaterial} 顶注:`true` 才在场,恒不写 `false`。 */
     governanceForced?: true;
     /** [ref](core 5.42.0):这道 park 门的**非秘密稳定身份**(`Checkpoint.checkpointId`)。逐字过境,
-     *  server 绝不自铸、绝不派生(信任边界校验见 `safeCheckpointIdOf`)。
+     *  server 绝不自铸、绝不派生(信任边界校验见 `checkpoint-identity.ts` 的 `trustedCheckpointId`)。
      *  🔴 **缺席是三成因合流的一个形**(R3-[low] 验真后改真 —— 此前这里只写了第一条,那是失真):
      *    ① **legacy 行**:该键诞生前 park 的(core 明写「absent ⇒ legacy row, read compatibly, no backfill」);
-     *    ② **服务端校验拒绝**:行上有值但没过 `safeCheckpointIdOf`(空串 / 超长 / 含 token) ⇒ **数据污染**,
-     *       而它在运维面上今天**与 ① 不可分辨**(见该函数顶注末段的残留登记);
+     *    ② **服务端校验拒绝**:行上有值但没过 `trustedCheckpointId`(空串 / 超长 / 含 token) ⇒ **数据污染**;
+     *       本载体上它与 ① 同形(键缺席、不计数 —— best-effort 分诊材料),durable 读面上两者分计(`checkpoint-identity.ts` 头注);
      *    ③ **材料读取失败**:整只 `pendingGate` 都不在(那时本键连位置都没有)。
      *  ⇒ 读作「不知道这道门叫什么」,**不是**「这道门没有身份」,更**不是**「这一定是条老行」。
      *

package/dist/http/active-run-conflict.js

@@ -2,6 +2,8 @@ import { governanceOriginOf } from "../runtime-governance.js";
 import { isParkedRunStatus } from "../plugins/store-contracts.js";
 import { LIVE_RUN_GATE_KINDS } from "../plugins/checkpoint-store-sql.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { refusalBody } from "./refusal-body.js";
+import { trustedCheckpointId } from "../checkpoint-identity.js";
 export const ACTIVE_RUN_CONFLICT_BASE_TEXT = "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)";
 export function resumeEntryForGate(kind, ids) {
     switch (kind) {
@@ -18,15 +20,6 @@ export function resumeEntryForGate(kind, ids) {
             return null;
     }
 }
-const MAX_CHECKPOINT_ID_CHARS = 128;
-function safeCheckpointIdOf(raw, token) {
-    if (typeof raw !== "string" || raw === "" || raw.length > MAX_CHECKPOINT_ID_CHARS)
-        return undefined;
-    const secret = token === undefined || token === null ? "" : String(token).toLowerCase();
-    if (secret !== "" && raw.toLowerCase().includes(secret))
-        return undefined;
-    return raw;
-}
 export function isActiveRunConflictBody(body) {
     return typeof body === "object" && body !== null && "activeTaskId" in body && body.errorCode === "conflict.session_active_run";
 }
@@ -42,12 +35,15 @@ export function toDoneFrameResult(body) {
         ...(body.pendingGate !== undefined ? { pendingGate: body.pendingGate } : {}),
     };
 }
+function activeRunConflictBody(message, facts) {
+    const body = refusalBody({ errorCode: "conflict.session_active_run", message, facts });
+    if (!isActiveRunConflictBody(body))
+        throw new Error("session-active-run conflict body lost its identity keys (errorCode / activeTaskId)");
+    return body;
+}
 export async function buildActiveRunConflict(deps, sessionId, activeTaskId) {
-    const base = {
-        error: ACTIVE_RUN_CONFLICT_BASE_TEXT,
-        errorCode: "conflict.session_active_run",
-        activeTaskId: activeTaskId ?? null,
-    };
+    const baseFacts = { activeTaskId: activeTaskId ?? null };
+    const base = activeRunConflictBody(ACTIVE_RUN_CONFLICT_BASE_TEXT, baseFacts);
     if (!activeTaskId)
         return base;
     try {
@@ -60,13 +56,12 @@ export async function buildActiveRunConflict(deps, sessionId, activeTaskId) {
             const updatedAtMs = row?.updatedAt !== undefined ? new Date(row.updatedAt).getTime() : Number.NaN;
             const staleMs = (deps.runStaleSec ?? 0) * 1000;
             const stale = staleMs > 0 && Number.isFinite(updatedAtMs) && Date.now() - updatedAtMs > staleMs;
-            return {
-                ...base,
-                error: "session already has an active run — POST /v1/runs/{activeTaskId}/steer injects a message into the running turn (queued, applied at the next turn boundary), or POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)",
+            return activeRunConflictBody("session already has an active run — POST /v1/runs/{activeTaskId}/steer injects a message into the running turn (queued, applied at the next turn boundary), or POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)", {
+                ...baseFacts,
                 activeTaskStatus: status,
                 ...(lastAt !== undefined ? { msSinceLastActivity: Math.max(0, Date.now() - lastAt) } : {}),
                 ...(stale ? { stale: true } : {}),
-            };
+            });
         }
         const cs = deps.checkpointStore;
         let pendingGate;
@@ -79,7 +74,7 @@ export async function buildActiveRunConflict(deps, sessionId, activeTaskId) {
             const kind = gate?.kind;
             const decidePath = kind ? resumeEntryForGate(kind, { sessionId, taskId: activeTaskId }) : null;
             const governanceForced = governanceOriginOf(gate, deps.governance);
-            const checkpointId = safeCheckpointIdOf(row?.checkpointId, token);
+            const checkpointId = trustedCheckpointId(row?.checkpointId, token);
             if (kind && decidePath) {
                 pendingGate = {
                     kind,
@@ -89,14 +84,9 @@ export async function buildActiveRunConflict(deps, sessionId, activeTaskId) {
                 };
             }
         }
-        return {
-            ...base,
-            error: pendingGate
-                ? `session already has an active run — it is parked waiting for a decision (${status}); resolve it via POST ${pendingGate.decidePath}, or POST /v1/runs/{activeTaskId}/cancel abandons it`
-                : `session already has an active run — it is parked (${status}); POST /v1/runs/{activeTaskId}/cancel abandons it (its pending decision could not be located on this instance)`,
-            activeTaskStatus: status,
-            ...(pendingGate ? { pendingGate } : {}),
-        };
+        return activeRunConflictBody(pendingGate
+            ? `session already has an active run — it is parked waiting for a decision (${status}); resolve it via POST ${pendingGate.decidePath}, or POST /v1/runs/{activeTaskId}/cancel abandons it`
+            : `session already has an active run — it is parked (${status}); POST /v1/runs/{activeTaskId}/cancel abandons it (its pending decision could not be located on this instance)`, { ...baseFacts, activeTaskStatus: status, ...(pendingGate ? { pendingGate } : {}) });
     }
     catch {
         recordFailOpen("server.approvals.active-run-conflict-material-unavailable");

package/dist/http/admission.d.ts

@@ -6,6 +6,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { TaskRequestBody } from "./wire-types.js";
 import { HttpError } from "../security.js";
+import { type LimitFacts } from "../limit-refusal.js";
 import type { PreparedTaskSubmission, RouteHelpers } from "./route-ctx.js";
 import type { FlatServiceDeps } from "./server.js";
 /** = core `SKILL_CONTENT_MAX_CHARS`(1MB 加载门,core 1.293 起 invoke 全文零截断、超 1MB 整拒;常量在
@@ -22,7 +23,7 @@ export declare const MAX_SYSTEM_PROMPT_CHARS = 16384;
  *  validation cost. 32KB comfortably holds a rich nested schema while bounding the abuse surface. */
 export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
 /**
- * Validate `body.skills` —— **形**校验 + 一条引擎孪生门。返回错误串(→ 400)或 null。
+ * Validate `body.skills` —— 逐条:**形**校验 + 一条引擎孪生门,再判两只清单的条数帽(与全部工具名清单同一只判)。返回拒({@link UserSkillsRefusal}:句子 + 撞帽时的机读位 → 400)或 null。
  *
  * 🔴 **[ref](7.77.0,硬 BREAKING;零别名零双读)**:此前这里有三条本仓自造的拒绝臂,全部退役 ——
  *  · `at most 10 skills per request`(条数帽);
@@ -51,7 +52,12 @@ export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
  *
  * 🔴 **server 侧禁裁列表 / 禁截描述**:渲染归引擎(单一属主)。本函数只判「这一条技能的形能不能用」。
  */
-export declare function validateUserSkills(skills: unknown): string | null;
+export declare function validateUserSkills(skills: unknown): UserSkillsRefusal | null;
+/** `body.skills` 的拒:句子 + 撞帽时的机读位(`field` / `reason` / `count` / `cap`;形错只有句子)。与子代定义那道门(`spec-fields.ts` 的 `TaskAgentsRefusal`)同形。 */
+export interface UserSkillsRefusal {
+    readonly message: string;
+    readonly facts?: LimitFacts;
+}
 /**
  * core 7.41.0 #1303 —— 顶层技能带 `manifest` 的拒因句(单铸点)。出路只点本服务上**真存在**的旋钮:技能的两只清单
  * (`allowedTools` / `disallowedTools`)、圈工具 = deny 规则(请求 `settings.permissions.deny` / 运维 `APPROVAL_DENY`)或子代定义的