@sema-agent/server 7.137.0 → 7.139.0

package/dist/session-row.js

@@ -1,7 +1,50 @@
-import { normalizePeerName } from "@sema-agent/core";
+import { createHash } from "node:crypto";
+import { normalizePeerName, sessionRowMatches } from "@sema-agent/core";
 export const SESSION_TITLE_MAX_CHARS = 120;
-const SESSION_ROW_PATCH_KEYS = { title: true, pinned: true };
-const BODY_SHAPE_MESSAGE = "the body must be a JSON object carrying at least one of `title` and `pinned`, and nothing else";
+export const SESSION_ROW_CELL_DEFAULTS = { title: null, pinned: false };
+const SESSION_ROW_TAG_DOMAIN = "sema.session-row-tag/1";
+export const SESSION_ROW_TAG_SHAPE = /^[A-Za-z0-9_-]{43}$/;
+export function sessionRowTagOf(row) {
+    const keys = Object.keys(SESSION_ROW_CELL_DEFAULTS).sort();
+    const cells = keys.filter((k) => row.cells[k] !== SESSION_ROW_CELL_DEFAULTS[k]).map((k) => [k, row.cells[k]]);
+    return createHash("sha256").update(JSON.stringify([SESSION_ROW_TAG_DOMAIN, row.sessionId, row.owner, row.incarnation, cells]), "utf8").digest("base64url");
+}
+export function sessionRowTagKey(row) {
+    return row.incarnation === undefined ? {} : { rowTag: sessionRowTagOf({ sessionId: row.sessionId, owner: row.owner, incarnation: row.incarnation, cells: row.cells }) };
+}
+export function judgeSessionRowWrite(sessionId, how, locked, logNow) {
+    if (locked === undefined || !sessionRowMatches(how.row, { owner: locked.owner, incarnation: locked.incarnation }, logNow) || locked.placed)
+        return "absent";
+    switch (how.writer) {
+        case "replay":
+            return "write";
+        case "client": {
+            if (locked.mirror)
+                return "mirror";
+            if (how.rowTag === undefined)
+                return "write";
+            const current = locked.incarnation === undefined ? undefined : sessionRowTagOf({ sessionId, owner: locked.owner, incarnation: locked.incarnation, cells: locked.cells });
+            return current === how.rowTag ? "write" : "changed";
+        }
+        default: {
+            const unknownWriter = how;
+            throw new Error(`judgeSessionRowWrite: no writer ${JSON.stringify(unknownWriter)}`);
+        }
+    }
+}
+export function settleSessionRowWrite(how, verdict, answer) {
+    const judged = how.row.row;
+    if (judged === null || answer === undefined)
+        return { kind: "absent" };
+    if (!sessionRowMatches({ row: judged }, answer.occupant, unreachableLogMark))
+        return { kind: "absent" };
+    return verdict === "write" ? { kind: "written", row: answer.row } : { kind: "changed", row: answer.row };
+}
+function unreachableLogMark() {
+    throw new Error("settleSessionRowWrite: the answer row's occupant check carries no log mark, yet the judge asked for one");
+}
+const BODY_SHAPE_MESSAGE = "the body must be a JSON object carrying at least one of `title` and `pinned` (and, optionally, `expectedRowTag`), and nothing else";
+const ROW_TAG_INVALID_MESSAGE = "expectedRowTag must be the `rowTag` string a session list row carries (43 characters: letters, digits, `-` and `_`)";
 const EMPTY_TITLE_MESSAGE = "title must not be the empty string — send `null` to clear it back to the automatic title";
 const INVISIBLE_TITLE_MESSAGE = "title must contain at least one visible character";
 const C0_CONTROL = /[\u0000-\u001f]/u;
@@ -25,11 +68,13 @@ export function readSessionTitle(v) {
 export function readSessionPinned(v) {
     return typeof v === "boolean" ? { pinned: v } : { problem: { code: "request.field_invalid", message: "pinned must be a boolean" } };
 }
+const EXPECTED_ROW_TAG_KEY = "expectedRowTag";
 export function readSessionRowPatch(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { problem: { code: "request.body_shape", message: BODY_SHAPE_MESSAGE } };
     const keys = Object.keys(body);
-    if (keys.length === 0 || keys.some((k) => !Object.hasOwn(SESSION_ROW_PATCH_KEYS, k))) {
+    const isCell = (k) => Object.hasOwn(SESSION_ROW_CELL_DEFAULTS, k);
+    if (!keys.some(isCell) || keys.some((k) => !isCell(k) && k !== EXPECTED_ROW_TAG_KEY)) {
         return { problem: { code: "request.body_shape", message: BODY_SHAPE_MESSAGE } };
     }
     const b = body;
@@ -46,6 +91,11 @@ export function readSessionRowPatch(body) {
             return read;
         patch = { ...patch, pinned: read.pinned };
     }
-    return { patch };
+    if (!(EXPECTED_ROW_TAG_KEY in b))
+        return { patch };
+    const tag = b.expectedRowTag;
+    if (typeof tag !== "string" || !SESSION_ROW_TAG_SHAPE.test(tag))
+        return { problem: { code: "request.field_invalid", message: ROW_TAG_INVALID_MESSAGE } };
+    return { patch, expectedRowTag: tag };
 }
 //# sourceMappingURL=session-row.js.map

package/dist/session-titler.d.ts

@@ -5,8 +5,8 @@
  * submission's acceptance seat (`run-acceptance.ts`: the objective entered the conversation, or a result-only verify /
  * cascade leg came back having done work). A run the engine refuses before acceptance never reaches the titler (no
  * model call for a refused input). No need to wait for the run to finish, and the web Recents gets the title sooner. Fills a NULL title only (`setTitleIfNull`,
- * store-side `WHERE title IS NULL`) — the user writes the SAME column unconditionally (`PATCH /v1/sessions/:id` →
- * `patchSessionMeta`): a user-set title is never overwritten (the probe below reads "titled" and skips the model
+ * store-side `WHERE title IS NULL`) — the user writes the SAME column (`PATCH /v1/sessions/:id` → the session row's write
+ * primitive `writeSessionRowCells`, unconditional unless the request carries `expectedRowTag`): a user-set title is never overwritten (the probe below reads "titled" and skips the model
  * call), and a title the user cleared (`title: null` ⇒ NULL) is filled again at the next submit (law: `session-row.ts`).
  * "Has it a title?" is read from the column on every submit (one point read) — the process keeps NO "already titled"
  * memo, because such a memo would be a second answer to that question that a clear turns stale. Generation = one

package/dist/session-workspace.d.ts

@@ -0,0 +1,130 @@
+/**
+ * **会话的位置与项目** —— 一个事实、一个写者、一种读法(引擎 7.58.0:`workspace_changed` 是腿的整份快照;
+ * 会话行 = 该会话上最后一帧)。
+ *
+ * ## 律(三句)
+ *  · **判官只有引擎一只**:每条腿起点一帧 `workspace_changed`(`cwd` / `root` / `entered?` / `project?` / `remote`),之后每变一帧;
+ *    这条腿属于哪个项目由引擎对检出的 `.sema/project` 记号判一次(带了 `TaskSpec.projectId` 就必须等于记号,
+ *    否则整腿拒 `config.project_identity_mismatch`;没有记号时声明就是身份)。本仓**不判**项目、不读记号。
+ *  · **会话行只存一格**:`workspace` = 该会话上一条腿**自己的**最后一帧(SQL `session_meta.workspace`;local 店
+ *    `session-workspaces.json` 那一格)。成员由 {@link SESSION_WORKSPACE_DISPOSITIONS} 一张表定(引擎给帧加成员 ⇒ 表 tsc 红,
+ *    门在 `trace/core-keyset-guard.ts` ⑰ 读同一张表)。**唯一写者** = 腿的记录座 {@link createSessionWorkspaceRecorder}
+ *    (持流的四条腿逐帧喂同一只;委派子代转上来的帧 —— 带 `parentToolCallId` / `sourceTaskId` / `bgAgentId` —— 不是这条腿的位置,不认)。
+ *    每一笔写**在腿的流循环里等完**(不排队、没有在飞的写:腿从任何出口离开时都没有它的写还悬着 ⇒ 写恒落在这条腿的 run 认领之内,
+ *    同一会话的下一条腿不会被一笔晚到的写盖掉),并且**只写受理时见证到的那一位住客**({@link stampLegSessionWitness}:resolveSpec
+ *    受理时读会话行的化身那一读,同一只值也是委派树根的见证)—— 会话被删掉又以同一 id 重建之后,上一位住客的腿写不进新住客的行。
+ *  · **每条腿声明一个值**:`TaskSpec.projectId` = 这次提交自己带的 `projectId`(新提交的请求体;续跑腿重放的是持久化的同一个体)
+ *    ?? 会话行上最后一帧的 `project.id` —— **只当它是调用方声明过的**(`source: "declared"`:没有记号的检出里声明就是身份,行存它就是为了接着声明);
+ *    `source: "marker"` 是引擎对**那一次**检出的记号判决,不续声明(引擎每条腿对自己的检出再判 —— 记号改写 / 换检出之后续跑照跑);
+ *    都没有 ⇒ 不带(引擎在有记号的检出里自判)。唯一铸点 {@link legProjectIdOf},唯一调用点 `boot/resolve-spec.ts`(新提交与续跑同经那一只装配)。
+ *
+ * ## 什么因此变少
+ * 修前请求键 `projectId` 被提交口受理、却从不交给引擎(keyset 守卫记该引擎座「未接线」,与受理表相反 —— 编译门 ② 红着);
+ * 会话在没有记号的检出里续跑时,项目随每一次不带 `projectId` 的提交丢掉。现在:一个值进引擎、一格存引擎的答案、下一条腿读那一格。
+ *
+ * ## 不在这里的(如实)
+ *  · **记忆项目层**(单用户 `userrepo:` 键,`project-identity.ts` 的 git 检出身份)不是这个事实:它在装配期(任何帧之前)交给
+ *    `TaskSpec.memory.projectKey`,按 git 仓库(origin 远端 / 本机路径)键控,与 `.sema/project` 记号无关;引擎 7.58.0 自己也写明
+ *    「只声明的身份不改记忆的键」。两者是否该合成一个身份,是另一张设计票。
+ *  · 多租户记忆分区(`proj:<租户>/<projectId>`)与登记簿种子读的是**这次提交**的 `projectId`(按提交挑盘,修前即如此),不读行。
+ *  · 行上的 `root` / `cwd` / `entered` / `remote` 今天只存不读(会话面读它们归 wire 半场那一车);fork 出的新会话从「没有记录」起。
+ *  · **只回结果的腿(verify / cascade,含续跑的 verify 臂)不记行**:引擎在组合入口里自己排空内层腿的流,宿主手里没有流,而引擎给组合入口开的
+ *    帧座(`onStatusEvent` / `onWiringManifest`)没有这一帧 ⇒ 这条腿的位置与项目到不了行,行停在更早一条腿的那一帧(没有记号的检出里,
+ *    下一条不带 `projectId` 的提交续声明的是那一帧声明过的项目)。本仓不替引擎铸「这条腿站在哪里」;要引擎为组合入口开这一帧的座。
+ *  · **行读在 run 认领之前**(resolveSpec 的每一读都是):同一会话两次提交交叠、后一次的装配读行之后前一次才落定并放认领 ⇒ 后一次读到的是更早
+ *    一条腿的项目(有记号的检出里多一次 409,没有记号的检出里续声明旧项目)。修法要把声明的装配挪到认领之后,不在本模块补第二个写者。
+ */
+import type { TaskEvent, TaskSpec } from "@sema-agent/core";
+import type { DelegationRootWitness } from "./delegated-session-owner.js";
+/**
+ * `workspace_changed` 帧在会话行上的样子(**唯一**一张表;表序 = 存储形的键序)。`forward` = 原值存进行;`strip` = 不进行。
+ * 腿身份四键(`eventId` / `parentToolCallId` / `sourceTaskId` / `bgAgentId`)是这一帧在流上的身份,不是位置;`type` 是臂名。
+ */
+export declare const SESSION_WORKSPACE_DISPOSITIONS: {
+    readonly type: "strip";
+    readonly cwd: "forward";
+    readonly root: "forward";
+    readonly entered: {
+        readonly nested: {
+            readonly dir: "forward";
+            readonly byPath: "forward";
+        };
+    };
+    readonly project: {
+        readonly nested: {
+            readonly id: "forward";
+            readonly source: "forward";
+        };
+    };
+    readonly remote: "forward";
+    readonly eventId: "strip";
+    readonly parentToolCallId: "strip";
+    readonly sourceTaskId: "strip";
+    readonly bgAgentId: "strip";
+};
+type WorkspaceFrame = Extract<TaskEvent, {
+    type: "workspace_changed";
+}>;
+/** 表里存进行的键(`strip` 之外的)—— 存储形由表派生,不另写一份成员清单。 */
+type KeptKeys = {
+    [K in keyof typeof SESSION_WORKSPACE_DISPOSITIONS]: (typeof SESSION_WORKSPACE_DISPOSITIONS)[K] extends "strip" ? never : K;
+}[keyof typeof SESSION_WORKSPACE_DISPOSITIONS];
+/** 会话行上那一格的值:最后一帧里本仓存下的成员(型从引擎的帧臂派生)。 */
+export type SessionWorkspace = Pick<WorkspaceFrame, KeptKeys>;
+/** 会话店的这一面(两只方法都在才算 —— 只有一半的店让读写不同源)。 */
+export interface SessionWorkspaceStore {
+    /** 这只会话上最后一帧;没有记录 / 没有这一行 ⇒ `undefined`。格读不出 ⇒ 读作没有记录并计一次(`decodeSessionWorkspaceCell`)。 */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜),**只写住客是 `incarnation` 那一位的行**:行不在、或此刻坐的是另一位住客 ⇒ 不写、不抛(那一行不是这条腿的)。
+     * 写**没有提交**必须抛。SQL 两孪生走店的一般查询面(与腿循环里的账本追加同一形,不设每查询的客户端超时 —— 客户端放弃等待而服务端照跑完的写,
+     * 正是能在这条腿离开之后落地的那一形);卡住的上界归服务端(锁等待超时 / 部署的 `DB_QUERY_TIMEOUT_MS`)。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
+}
+/** 店有没有这一面 —— 结构判(包装店 `CachingSessionStore` 逐方法转发,判的是能力不是名字)。没有 ⇒ 不记、不读(core 的内存 dev 店)。 */
+export declare function sessionWorkspaceStoreOf(store: unknown): SessionWorkspaceStore | undefined;
+/**
+ * 这条腿的会话**在受理时**是哪一位住客(会话 id + 化身令牌)的 spec 字段键 —— 与 run 名册 / 执行车道字段同一形:symbol 键随 spread / rest 解构走
+ * (续跑腿的 `taskConfig` 是 rest 解构出来的),对引擎的键面不可见(JSON / 结构化克隆跳过 symbol 键)。铸点唯一 = resolveSpec 出口
+ * ({@link stampLegSessionWitness}),值 = 受理时读会话行的那**一**读(同一只值也交给场景层作委派树根的见证);读点唯一 = {@link legSessionWitnessOf}。
+ */
+export declare const LEG_SESSION_WITNESS_FIELD: unique symbol;
+/** 铸见证(**单一属主**:只许 resolveSpec 的出口调用)。`writable:false` + `configurable:false`:同一只 spec 被第二次铸 ⇒ 当场 TypeError。缺席 ⇒ 不铸。 */
+export declare function stampLegSessionWitness<T extends TaskSpec>(spec: T, witness: DelegationRootWitness | undefined): T;
+/** 读见证。`undefined` = 这只 spec 不是本仓装配出口产的,或这条腿没有会话 ⇒ 记录座不写(没有住客可认)。入参收 `object`:续跑腿手里是 rest 解构出来的 taskConfig。 */
+export declare function legSessionWitnessOf(spec: object): DelegationRootWitness | undefined;
+/**
+ * 一帧 → 会话行上那一格的值。只认这条腿**自己的**帧(腿身份三键任一在场 = 委派子代转上来的,不是这条腿站在哪里);
+ * 按表投影后过存储形的同一只读者(写得进的就是读得出的)。读不出(引擎不会铸出这种帧)⇒ 不记、计一次。
+ */
+export declare function sessionWorkspaceOfFrame(ev: TaskEvent): SessionWorkspace | undefined;
+/** 腿的记录座。 */
+export interface SessionWorkspaceRecorder {
+    /**
+     * 持流的腿**逐帧**调用并等它(在本腿的取消成因闩之后)。这条腿自己的 `workspace_changed` ⇒ 这一笔写写完(或失败计一次)才兑现 ——
+     * 帧按到达序一笔一笔写,最后一帧胜;腿从任何出口(`done`、断连 `break`、抛)离开时没有写还悬着。其余帧当场兑现。**从不抛、从不拒**。
+     */
+    observe(ev: TaskEvent): Promise<void>;
+}
+/**
+ * 记录座的**唯一**铸点(四条持流腿各在开流时铸一只:后台腿 `runs.ts`、活流腿与同步腿 `http/routes/tasks.ts`、续跑腿 `http/resume-legs.ts`),
+ * `witness` = 这条腿 spec 上的受理见证({@link legSessionWitnessOf})。店没有这一面、或见证缺席 / 受理时这只会话还没有住客令牌 ⇒
+ * 一只什么都不做的座(诚实缺席:认不出住客就不写 —— 写错住客比少记一次坏)。
+ *
+ * 失败方向(F 类):写失败(库抖 / 盘满 / 锁等待超时)⇒ 行停在上一帧,计一次;下一帧照写。放行的最坏后果 = 下一条不带 `projectId` 的提交读到旧的
+ * (或没有)项目 —— 有记号的检出里引擎照判记号(声明不等就响亮拒),没有记号的检出里这只会话少一次续声明。不放行的代价是把一条在跑的腿
+ * 为一次记录摔掉。等一笔写的代价 = 这条腿的流晚一次主键 UPDATE 的时延(引擎不等宿主消费,只是帧晚到;一条腿的帧只有起点一帧加每次换位一帧)。
+ * 库卡住(池取不到连接)时这条腿交给调用方的结果跟着等:后台腿与续跑腿的循环本来每一帧就等店写(账本追加);同步腿与不落账的活流腿此前循环里没有店写,
+ * 现在多等这一笔 —— 但同一只池上引擎自己的会话条目写(每一轮 `appendEntry`,`plugins/store-backend.ts` 的 `session()` 与其余店共用一池)本来就在
+ * 这条腿的关键路径上,池饿死时这条腿本来就停;上界归部署(`DB_QUERY_TIMEOUT_MS`、MySQL 池的排队上界)。local 后端的写不经池。
+ */
+export declare function createSessionWorkspaceRecorder(store: SessionWorkspaceStore | undefined, witness: DelegationRootWitness | undefined): SessionWorkspaceRecorder;
+/**
+ * **这条腿交给引擎的 `TaskSpec.projectId`**(唯一铸点;见文件头第三句)。`submitted` = 这次提交自己带的、已过形状门且折成小写的值
+ * (新提交:鉴权口的 `resolvedProjectId`;续跑:持久化体的同一个键)。它在场就不读行。行读失败(库抖)原样上抛 —— 读不到「这只会话的项目」
+ * 不能悄悄折成「没有项目」(那会把一只登记在项目下的会话在没有记号的检出里改成无项目)。
+ */
+export declare function legProjectIdOf(submitted: string | undefined, store: SessionWorkspaceStore | undefined, sessionId: string | undefined): Promise<string | undefined>;
+export {};
+//# sourceMappingURL=session-workspace.d.ts.map

package/dist/session-workspace.js

@@ -0,0 +1,83 @@
+import { recordFailOpen } from "./observability/fail-open.js";
+import { readSessionWorkspaceCell, SESSION_WORKSPACE_DEGRADED } from "./plugins/session-workspace-cell.js";
+import { projectByTable } from "./trace/projection-table.js";
+export const SESSION_WORKSPACE_DISPOSITIONS = {
+    type: "strip",
+    cwd: "forward",
+    root: "forward",
+    entered: { nested: { dir: "forward", byPath: "forward" } },
+    project: { nested: { id: "forward", source: "forward" } },
+    remote: "forward",
+    eventId: "strip",
+    parentToolCallId: "strip",
+    sourceTaskId: "strip",
+    bgAgentId: "strip",
+};
+export function sessionWorkspaceStoreOf(store) {
+    const s = store;
+    if (typeof s?.readSessionWorkspace !== "function" || typeof s.recordSessionWorkspace !== "function")
+        return undefined;
+    return { readSessionWorkspace: s.readSessionWorkspace.bind(s), recordSessionWorkspace: s.recordSessionWorkspace.bind(s) };
+}
+export const LEG_SESSION_WITNESS_FIELD = Symbol("sema-server.legSessionWitness");
+export function stampLegSessionWitness(spec, witness) {
+    if (witness !== undefined)
+        Object.defineProperty(spec, LEG_SESSION_WITNESS_FIELD, { value: Object.freeze({ ...witness }), enumerable: true, writable: false, configurable: false });
+    return spec;
+}
+export function legSessionWitnessOf(spec) {
+    return spec[LEG_SESSION_WITNESS_FIELD];
+}
+export function sessionWorkspaceOfFrame(ev) {
+    if (ev.type !== "workspace_changed")
+        return undefined;
+    if (ev.parentToolCallId !== undefined || ev.sourceTaskId !== undefined || ev.bgAgentId !== undefined)
+        return undefined;
+    const shape = readSessionWorkspaceCell(projectByTable("session_workspace", SESSION_WORKSPACE_DISPOSITIONS, ev, ev));
+    if (shape.problem !== undefined) {
+        recordFailOpen(SESSION_WORKSPACE_DEGRADED, `op=frame problem=${shape.problem.slice(0, 200)}`);
+        return undefined;
+    }
+    return shape.value;
+}
+const SETTLED = Promise.resolve();
+const NO_RECORD = { observe: () => SETTLED };
+export function createSessionWorkspaceRecorder(store, witness) {
+    if (store === undefined || witness === undefined || witness.incarnation === null)
+        return NO_RECORD;
+    const { sessionId, incarnation } = witness;
+    return {
+        async observe(ev) {
+            const snapshot = sessionWorkspaceOfFrame(ev);
+            if (snapshot === undefined)
+                return;
+            try {
+                await store.recordSessionWorkspace(sessionId, incarnation, snapshot);
+            }
+            catch (e) {
+                recordFailOpen(SESSION_WORKSPACE_DEGRADED, `op=write session=${sessionId} ${(e instanceof Error ? e.message : String(e)).slice(0, 200)}`);
+            }
+        },
+    };
+}
+export async function legProjectIdOf(submitted, store, sessionId) {
+    if (submitted !== undefined)
+        return submitted;
+    if (store === undefined || sessionId === undefined)
+        return undefined;
+    const project = (await store.readSessionWorkspace(sessionId))?.project;
+    return project === undefined ? undefined : replayedProjectIdOf(project);
+}
+function replayedProjectIdOf(project) {
+    switch (project.source) {
+        case "declared":
+            return project.id;
+        case "marker":
+            return undefined;
+        default: {
+            const unknownSource = project.source;
+            throw new Error(`session workspace: unknown project source word ${JSON.stringify(unknownSource)} (the row reader admits only marker / declared)`);
+        }
+    }
+}
+//# sourceMappingURL=session-workspace.js.map

package/dist/spec-fields.d.ts

@@ -108,7 +108,7 @@ export interface TaskAgentsRefusal {
  *  定义被悄悄削(一个丢掉的 isolation 就是放宽),比 400 更危险,故整条拒。`allowTools` / `denyTools` 本门只判形与条数(`toolList`),
  *  **名字归引擎一只判**(core 7.49.0 [ref] / [ref] 第二步起与根 run 的 `allowTools` / `excludeTools` 是同一只选择器,开跑前,三来源同判):core 7.51.0 [ref] 起
  *  没有任何工具答应的名字(无人挂的名、大小写孪生 / 退役名 `bash` / `BASH`)**引擎不拒 run** —— 条目原样保留、经 onError(config)告知一次(带该写的拼法);
- *  其中**写错现名的**(`denyTools:["BASH"]` 想禁的照用 = 静默放行;`allowTools:["BASH"]` 想放的什么也没放 = 静默收窄)由 `resolveSpec` 前置拒:**限制侧**(`denyTools`)四类全拒(近似名 · 退役名 · 文法读不出 · `*`),
+ *  其中**写错现名的**(`denyTools:["BASH"]` 想禁的照用 = 静默放行;`allowTools:["BASH"]` 想放的什么也没放 = 静默收窄)由 `resolveSpec` 前置拒:**限制侧**(`denyTools`)三类全拒(近似名 · 退役名 · 文法读不出);名内的 `*` 自 7.137.0 起是整名 glob、受理(孤 `*` = 每一只工具),`Tool(content)` 引擎读成整只工具、同样受理,
  *  **放行侧**(`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` 点名现名、续跑按方向分流;
  *  判官仍是引擎的条目读法,不是第二个判官);
  *  **真未知名**(没有近似也没有退役对应:懒挂载的合法形)照旧只告运维、不拒。

package/dist/standing-answer-grant.d.ts

@@ -1,12 +1,8 @@
-/** 卡载体:引擎铸的问 / 停驻行 / 它们的投影行(活的 `AskRequest`、停驻行的 `tool_approval` 臂、运维队列行都结构上满足)。 */
+/** 载体:引擎给一次调用盖过绑定词的任何形(活的 `AskRequest`、停驻行的 `tool_approval` 臂、运维队列行、策略层的 `ToolCallRequest` 都结构上满足)。 */
 export interface StandingAnswerCard {
     readonly boundGrantDigest?: unknown;
     readonly boundGrantAbsence?: unknown;
 }
-/** 调用载体:策略层的 `ToolCallRequest`、豁免店的行(只有工具名)。 */
-export interface StandingAnswerCall {
-    readonly toolName?: unknown;
-}
 /** 一问的授予绑定(闭集):`none` = 应答只覆盖这一次调用;`bound` = 授予、绑定可读;`unreadable` = 授予或说不清、绑定读不出。 */
 export type GrantBinding = {
     readonly kind: "none";
@@ -16,13 +12,6 @@ export type GrantBinding = {
 } | {
     readonly kind: "unreadable";
 };
-/** 卡上的授予绑定 —— 只读引擎的词(读法见文件头注):摘要是串 ⇒ bound;摘要不在且词是 `not_bindable` ⇒ none;其余 ⇒ unreadable。 */
+/** 载体上的授予绑定 —— 只读引擎的词(读法见文件头注):摘要是串 ⇒ bound;摘要不在且词是 `not_bindable` ⇒ none;其余 ⇒ unreadable。 */
 export declare function grantBindingOf(card: StandingAnswerCard): GrantBinding;
-/** 调用上的授予绑定 —— 调用上没有引擎的词,读引擎绑定工厂的那一条规则(见文件头注;🚧 引擎在调用上盖词之后退役)。 */
-export declare function callGrantBindingOf(call: StandingAnswerCall): GrantBinding;
-/**
- * 一问的授予绑定的**唯一折点**:读哪个载体由**问的属主**定 —— 名单自己的问(`deploymentListQuestion`,即 `standingAnswerHome` 的 `server_store` 家)读调用口,
- * 引擎铸的问读卡口(载体与理由见文件头注)。所有把「一张卡」折成 {@link StandingAnswerFacts} 的读者(活的问、待决条目、停驻行、运维队列行)经它取绑定,不各自选口。
- */
-export declare function questionGrantBindingOf(carrier: StandingAnswerCard & StandingAnswerCall, deploymentListQuestion: boolean): GrantBinding;
 //# sourceMappingURL=standing-answer-grant.d.ts.map

package/dist/standing-answer-grant.js

@@ -1,4 +1,3 @@
-import { SKILL_TOOL_NAME } from "@sema-agent/core";
 const NOT_BINDABLE = "not_bindable";
 export function grantBindingOf(card) {
     const digest = card.boundGrantDigest;
@@ -6,10 +5,4 @@ export function grantBindingOf(card) {
         return { kind: "bound", digest };
     return digest === undefined && card.boundGrantAbsence === NOT_BINDABLE ? { kind: "none" } : { kind: "unreadable" };
 }
-export function callGrantBindingOf(call) {
-    return call.toolName === SKILL_TOOL_NAME ? { kind: "unreadable" } : { kind: "none" };
-}
-export function questionGrantBindingOf(carrier, deploymentListQuestion) {
-    return deploymentListQuestion ? callGrantBindingOf(carrier) : grantBindingOf(carrier);
-}
 //# sourceMappingURL=standing-answer-grant.js.map

package/dist/task-a2a.d.ts

@@ -1,4 +1,5 @@
-import type { A2aServerSpec } from "@sema-agent/core";
+import { type A2aServerSpec, type CompliancePosture, type LockedKey } from "@sema-agent/core";
+import { type A2aDraft, type PeerDesk, type PeerLease } from "./peer-seat.js";
 import { type DeclarationRefusal } from "./request-declaration-refusal.js";
 import type { StoredToolAxesRereadM19 } from "./stored-request-tool-axes-m19.js";
 import { type PrincipalAxisInput } from "./deployment-shape.js";
@@ -21,18 +22,42 @@ export interface A2aInjectionDrop {
     readonly reason: string;
     readonly field: string;
 }
-/** The deployment-facing shape this module reads: the principal axis only (the single-user gate). */
-export type A2aGateConfig = PrincipalAxisInput;
+/** The deployment-facing shape this module reads: the principal axis, the operator locks and the compliance posture. */
+export type A2aGateConfig = PrincipalAxisInput & {
+    readonly lockedConfigKeys?: readonly LockedKey[];
+    readonly compliancePosture?: CompliancePosture;
+};
 /**
- * Does THIS deployment honor caller-supplied per-request A2A peers? One veto — multi-tenant (deployment-shape row `multiTenant`): a tenant cannot
- * point the shared worker at an agent. The capability bit and the request leg both read this predicate, so there is exactly one place where the answer can be wrong.
+ * Does THIS deployment honor caller-supplied per-request A2A peers? The same three vetoes as `task-mcp.ts mcpInjectionHonored`, each with its own
+ * engine word: multi-tenant (deployment-shape row `multiTenant`: a tenant cannot point the shared worker at an agent), the operator lock `a2a`, and a
+ * compliance posture that denies `a2a_peers` (the engine refuses a task that declares a peer under either at prepare — advertising the bit would be
+ * "says yes, every use refused"). The capability bit and the request leg both read this predicate, so there is exactly one place where the answer can be wrong.
+ * A posture that cannot be resolved throws here (validated twice before this site; loud beats a quiet boolean, same as the MCP gate).
  */
 export declare function a2aInjectionHonored(config: A2aGateConfig): boolean;
 /**
- * 请求体 `a2aPeers[i]` 的**键闭集**(判序 = 本数组序:名 → 对端地址 → 它的 agent card 地址 → 凭据头 → 身份头 → 技能收窄 → 轴覆写)。两向钉在 core 的 `A2aServerSpec` 上:
- * 型上多一个键而表没跟 ⇒ 编译红(新键会被词表外的键门 400 掉 —— wire 上的静默回归);表里写一个型上没有的词 ⇒ 也红。于是这张表是从 core 的型**派生**出来的数据,而不是谁记得去同步的清单。
+ * 请求面一条 `a2aPeers[]` 对端在 wire 上的形(= `TaskRequestBody.a2aPeers` 的元素型):引擎的 `A2aServerSpec` 去掉凭据引用位、加上 `headers`(件)。
+ * 交给引擎之前一律经 {@link toA2aDraft} 拆成草稿 —— 引擎的声明收据对带 `headers` 的声明整条拒,件由部署的对端座在每次发送时作答。
  */
-export declare const A2A_PEER_ENTRY_KEYS: readonly ["name", "url", "cardUrl", "headers", "principalHeader", "allowSkills", "toolAxes"];
+export type RequestA2aPeer = Omit<A2aServerSpec, "credentials"> & {
+    headers?: Record<string, string>;
+};
+/**
+ * 请求体 `a2aPeers[i]` 的**处置表** —— 同时是键闭集(判序 = 书写序:名 → 对端地址 → 它的 agent card 地址 → 凭据头 → 身份头 → 技能收窄 → 轴覆写)与每个键的去处:
+ * `headers` 是件(进草稿,交给引擎的声明里不带),其余进声明。三道编译格:对请求形两向(`satisfies`:请求形多一个键而表没写 / 表里写一个请求形上没有的词 ⇒ 红);
+ * 对引擎的 `A2aServerSpec` 两道(引擎长出 / 退役一个键,或退役凭据引用位 ⇒ 红)。于是这张表是从型**派生**出来的数据,而不是谁记得去同步的清单。
+ */
+export declare const A2A_PEER_DISPOSITION: {
+    readonly name: "engine";
+    readonly url: "engine";
+    readonly cardUrl: "engine";
+    readonly headers: "seat";
+    readonly principalHeader: "engine";
+    readonly allowSkills: "engine";
+    readonly toolAxes: "engine";
+};
+/** 请求体 `a2aPeers[i]` 的键闭集 = 处置表的键(书写序即判序)。 */
+export declare const A2A_PEER_ENTRY_KEYS: readonly ("name" | "headers" | "principalHeader" | "toolAxes" | "url" | "cardUrl" | "allowSkills")[];
 /**
  * **请求入口的一次读**(`boot/resolve-spec.ts` 在腿首铸一份,受理门与读器——续跑重放腿只有读器——都吃这一份):`body.a2aPeers` 若是数组,返回同形数组
  * (每个对象条目换成它的 {@link PeerSnapshot};非对象条目原样;长度保真 —— 界外的条数仍是受理门撞帽拒与读器丢弃留声的依据,只快照界内的条目);不是数组(缺席 / `null` / 别的形)原样返回。
@@ -45,12 +70,14 @@ export declare function snapshotRequestA2a(raw: unknown, options: {
 }): unknown;
 /** 读这条对端的是哪条腿:`fresh` = 新提交;`resume` = 续跑重放升级前存下的请求体(`boot/resolve-spec.ts` 的 `opts.leg` 分流,同一个读法)。 */
 type A2aRequestLeg = "fresh" | "resume";
+/** 请求面对端 → 草稿:按 {@link A2A_PEER_DISPOSITION} 拆(`headers` 进件,其余进声明;拆法与 MCP 请求腿同一只 `splitDeclaration`)。件缺席或空 ⇒ 草稿不带件。纯函数,不登记。 */
+export declare function toA2aDraft(peer: RequestA2aPeer): A2aDraft;
 /**
  * Shape-check the raw `body.a2aPeers`. `null` → a non-array (caller error; the route may 400). Otherwise the
- * valid subset + the dropped (malformed/over-cap) entries as {@link A2aInjectionDrop} facts (peer name · reason · body coordinate).
+ * valid subset as drafts (nothing registered) + the dropped (malformed/over-cap) entries as {@link A2aInjectionDrop} facts (peer name · reason · body coordinate).
  */
 export declare function validateRequestA2a(raw: unknown): {
-    ok: A2aServerSpec[];
+    ok: A2aDraft[];
     dropped: A2aInjectionDrop[];
 } | null;
 /**
@@ -69,13 +96,14 @@ export declare function requestA2aDeclarationRefusal(list: unknown): Declaration
 /** fresh 提交腿的 `a2aPeers` 门:{@link requestA2aDeclarationRefusal} 有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` / 机读位原样)。 */
 export declare function assertRequestA2aEntries(bodyA2a: unknown): void;
 /**
- * Merge GATED per-request peers OVER the deployment baseline (center/config). The baseline WINS on a name
+ * Merge GATED per-request peer drafts OVER the deployment baseline (center/config): **select first, then mint**. The baseline WINS on a name
  * clash — a caller can ADD a peer but can never SHADOW a configured one. This is load-bearing on THIS lane
  * specifically: the peer name is the tool-namespace segment (`a2a__<peer>__<skill>`), so shadowing would let
- * a caller keep the tool NAMES the model was told about while swapping the agent behind them.
+ * a caller keep the tool NAMES the model was told about while swapping the agent behind them. A draft that loses to the baseline never reaches
+ * the desk; each winner is minted once on `desk` under `lease` (`peer-seat.ts` `mintDeclaration`: the reference at the top level, zero header values).
  * Returns the baseline unchanged when there is nothing to add.
  */
-export declare function mergeRequestA2a(baseline: A2aServerSpec[] | undefined, gated: A2aServerSpec[]): A2aServerSpec[] | undefined;
+export declare function mergeRequestA2a(baseline: A2aServerSpec[] | undefined, drafts: readonly A2aDraft[], desk: Pick<PeerDesk, "declare">, lease: PeerLease): A2aServerSpec[] | undefined;
 /**
  * The single entry point the spec-builder calls: compute the effective `TaskSpec.a2a` = deployment baseline
  * (`a2aForScenario(config.a2aPeers, scenario)`) + the caller's gated per-request peers. Off the honored lane
@@ -83,7 +111,9 @@ export declare function mergeRequestA2a(baseline: A2aServerSpec[] | undefined, g
  * peers a closed gate dropped, so a shell never silently believes its declaration took effect (it also reads
  * `capabilities.a2aInjection`).
  */
-export declare function resolveRequestA2a(baseline: A2aServerSpec[] | undefined, bodyA2a: unknown, config: A2aGateConfig, logger?: {
+export declare function resolveRequestA2a(baseline: A2aServerSpec[] | undefined, bodyA2a: unknown, config: A2aGateConfig, 
+/** 对端座的 desk 与本腿的宿主租约(必填,与 MCP 请求腿同一对):胜出草稿在它下面铸成带引用的声明。 */
+desk: Pick<PeerDesk, "declare">, lease: PeerLease, logger?: {
     info?(m: string, meta?: unknown): void;
     warn(m: string, meta?: unknown): void;
 }, 

package/dist/task-a2a.js

@@ -1,18 +1,36 @@
 import { types } from "node:util";
+import { resolveComplianceDenies } from "@sema-agent/core";
 import { describeNotStringArray, describeValueShape, findUrlCredential, isStringArray } from "@sema-agent/settings-schema";
 import { errorKindOf } from "./observability/err-text.js";
-import { readPlainStringRecord } from "./plain-string-record.js";
+import { declarationKeys, readPlainStringRecord, splitDeclaration } from "./plain-string-record.js";
+import { mintDeclaration, peerSentence } from "./peer-seat.js";
 import { readRequestToolAxes } from "./request-tool-axes.js";
 import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyNames } from "./request-key-closure.js";
 import { urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential-refusal.js";
 import { declarationEntryNotObject, declarationIssueFacts, declarationNameIssue, declarationOverCapFacts, declaredName, judgeDeclarationKeys, requestDeclarationRefusal, throwDeclarationRefusal, } from "./request-declaration-refusal.js";
+import { principalHeaderOwnershipIssue } from "./task-mcp.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export const MAX_REQUEST_A2A_PEERS = 32;
 export function a2aInjectionHonored(config) {
+    if (config.lockedConfigKeys?.includes(A2A_LOCK_WORD) === true)
+        return false;
+    if (config.compliancePosture !== undefined && resolveComplianceDenies(config.compliancePosture).has(A2A_COMPLIANCE_WORD))
+        return false;
     return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
+const A2A_LOCK_WORD = "a2a";
+const A2A_COMPLIANCE_WORD = "a2a_peers";
 const HTTP_URL_RE = /^https?:\/\//i;
-export const A2A_PEER_ENTRY_KEYS = ["name", "url", "cardUrl", "headers", "principalHeader", "allowSkills", "toolAxes"];
+export const A2A_PEER_DISPOSITION = {
+    name: "engine",
+    url: "engine",
+    cardUrl: "engine",
+    headers: "seat",
+    principalHeader: "engine",
+    allowSkills: "engine",
+    toolAxes: "engine",
+};
+export const A2A_PEER_ENTRY_KEYS = declarationKeys(A2A_PEER_DISPOSITION);
 const A2A_PEER_ENTRY_KEY_SET = new Set(A2A_PEER_ENTRY_KEYS);
 const NO_TOLERATED_KEYS = new Set();
 const A2A_SEAT = {
@@ -133,11 +151,11 @@ export function snapshotRequestA2a(raw, options) {
     return kept;
 }
 function toolAxesIssue(read) {
-    return { path: "toolAxes", reason: read.problem };
+    return { path: "toolAxes", reason: peerSentence(read.problem) };
 }
 function toolAxesNotCloneableIssue(read, clone) {
     const because = clone === undefined || clone.ok ? "unavailable" : clone.because;
-    return { path: "toolAxes", reason: `declaration not cloneable (${because}) — the one-time migration re-reads the stored declaration as plain JSON data and this one is not; ${read.problem}` };
+    return { path: "toolAxes", reason: `declaration not cloneable (${because}) — the one-time migration re-reads the stored declaration as plain JSON data and this one is not; ${peerSentence(read.problem)}` };
 }
 const A2A_PEER_KEY_JUDGES = {
     name: declarationNameIssue,
@@ -152,7 +170,11 @@ const A2A_PEER_KEY_JUDGES = {
         const reserved = read.stripped[0];
         return reserved === undefined ? undefined : { path: HEADERS_RESERVED_MEMBER_PATH, reason: reserved.fault };
     },
-    principalHeader: (o) => (o.principalHeader === undefined || typeof o.principalHeader === "string" ? undefined : { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }),
+    principalHeader: (o) => o.principalHeader === undefined
+        ? undefined
+        : typeof o.principalHeader !== "string"
+            ? { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }
+            : principalHeaderOwnershipIssue(o.principalHeader, "a2a", "principalHeader"),
     allowSkills: (o) => o.allowSkills === undefined || isStringArray(o.allowSkills)
         ? undefined
         : { path: "allowSkills", reason: `must be an array of strings (omit the key to leave the peer's skills unrestricted) — got ${describeNotStringArray(o.allowSkills)}` },
@@ -162,10 +184,10 @@ const A2A_PEER_KEY_JUDGES = {
     },
 };
 function normalizeA2aPeer(e, leg, at, storedToolAxes) {
-    const dropBecause = (issue) => ({ spec: null, because: declarationIssueFacts(at, issue) });
+    const dropBecause = (issue) => ({ draft: null, because: declarationIssueFacts(at, issue) });
     const notObject = declarationEntryNotObject(A2A_SEAT, e, at);
     if (notObject !== undefined)
-        return { spec: null, because: { field: at, reason: notObject } };
+        return { draft: null, because: { field: at, reason: notObject } };
     const o = snapshotPeer(e, storedToolAxes !== undefined);
     for (const key of A2A_PEER_ENTRY_KEYS) {
         const issue = A2A_PEER_KEY_JUDGES[key](o, at);
@@ -206,12 +228,16 @@ function normalizeA2aPeer(e, leg, at, storedToolAxes) {
                 return unread;
             if (again.toolAxes !== undefined)
                 spec.toolAxes = again.toolAxes;
-            return { spec, toolAxesReread: axes.problem, ...lost };
+            return { draft: toA2aDraft(spec), toolAxesReread: peerSentence(axes.problem), ...lost };
         }
         if (axes.toolAxes !== undefined)
             spec.toolAxes = axes.toolAxes;
     }
-    return { spec, ...lost };
+    return { draft: toA2aDraft(spec), ...lost };
+}
+export function toA2aDraft(peer) {
+    const split = splitDeclaration(peer, A2A_PEER_DISPOSITION);
+    return { spec: split.engine, ...(split.pieces === undefined ? {} : { pieces: split.pieces }) };
 }
 export function validateRequestA2a(raw) {
     const v = validateRequestA2aEntries(raw, "fresh");
@@ -228,12 +254,12 @@ function validateRequestA2aEntries(raw, leg, storedToolAxes) {
     const headersLost = [];
     for (const [i, e] of raw.slice(0, MAX_REQUEST_A2A_PEERS).entries()) {
         const read = normalizeA2aPeer(e, leg, `${A2A_SEAT.list}[${i}]`, storedToolAxes);
-        if (read.spec !== null) {
-            ok.push(read.spec);
+        if (read.draft !== null) {
+            ok.push(read.draft);
             if (read.toolAxesReread !== undefined)
-                toolAxesReread.push({ peer: read.spec.name, problem: read.toolAxesReread });
+                toolAxesReread.push({ peer: read.draft.spec.name, sentence: read.toolAxesReread });
             if (read.headersLost !== undefined)
-                headersLost.push({ peer: read.spec.name, lost: read.headersLost });
+                headersLost.push({ peer: read.draft.spec.name, lost: read.headersLost });
         }
         else
             dropped.push({ peer: declaredName(e).slice(0, 128), ...read.because });
@@ -265,14 +291,14 @@ export function requestA2aDeclarationRefusal(list) {
 export function assertRequestA2aEntries(bodyA2a) {
     throwDeclarationRefusal(requestA2aDeclarationRefusal(bodyA2a));
 }
-export function mergeRequestA2a(baseline, gated) {
-    if (gated.length === 0)
+export function mergeRequestA2a(baseline, drafts, desk, lease) {
+    if (drafts.length === 0)
         return baseline;
     const taken = new Set((baseline ?? []).map((p) => p.name));
-    const add = gated.filter((p) => !taken.has(p.name));
-    return add.length === 0 ? baseline : [...(baseline ?? []), ...add];
+    const winners = drafts.filter((d) => !taken.has(d.spec.name));
+    return winners.length === 0 ? baseline : [...(baseline ?? []), ...winners.map((d) => mintDeclaration(desk, d, lease))];
 }
-export function resolveRequestA2a(baseline, bodyA2a, config, logger, leg = "fresh", storedToolAxes) {
+export function resolveRequestA2a(baseline, bodyA2a, config, desk, lease, logger, leg = "fresh", storedToolAxes) {
     if (bodyA2a === undefined || bodyA2a === null)
         return baseline;
     if (!a2aInjectionHonored(config)) {
@@ -286,7 +312,7 @@ export function resolveRequestA2a(baseline, bodyA2a, config, logger, leg = "fres
     }
     if (v.dropped.length > 0)
         logger?.warn("a2a_injection_dropped", { dropped: v.dropped });
-    const merged = mergeRequestA2a(baseline, v.ok);
+    const merged = mergeRequestA2a(baseline, v.ok, desk, lease);
     const baselineNames = new Set((baseline ?? []).map((p) => p.name));
     for (const r of v.toolAxesReread) {
         if (baselineNames.has(r.peer))
@@ -294,7 +320,7 @@ export function resolveRequestA2a(baseline, bodyA2a, config, logger, leg = "fres
         logger?.warn("a2a_tool_axes_read_as_before_upgrade", {
             peer: r.peer,
             migration: "M19",
-            problem: r.problem,
+            problem: r.sentence,
             note: "this replayed request was stored before the upgrade and the peer's toolAxes declaration does not pass the engine's reader; while one-time migration M19 is open it is read the way the pre-upgrade reader reads it (members that do not fit are dropped) and the peer stays mounted — once the window closes the same request leaves this peer unmounted",
         });
     }