@sema-agent/server 7.134.0 → 7.136.0

package/dist/session-sync.js

@@ -1,5 +1,33 @@
 import { classifySyncRelationship } from "./session-sync-kernel.js";
 import { loosenReasons, normalizeRules } from "@sema-agent/core";
+import { headReadOf } from "./session-incarnation.js";
+import { judgeSessionRulesWrite } from "@sema-agent/core";
+export class FileHistoryUnreadableError extends Error {
+    sessionId;
+    failure;
+    code = "state.file_history_unreadable";
+    constructor(sessionId, failure) {
+        super(`file history of session ${sessionId} cannot be read whole (${failure.code}): ${failure.message}`);
+        this.sessionId = sessionId;
+        this.failure = failure;
+        this.name = "FileHistoryUnreadableError";
+    }
+}
+export async function exportedFileHistory(store, sessionId) {
+    if (typeof store.exportHistory !== "function")
+        return null;
+    const exported = await store.exportHistory(sessionId);
+    if (!exported.ok)
+        throw new FileHistoryUnreadableError(sessionId, exported.error);
+    return exported.history;
+}
+export function syncBlobFacesOf(store) {
+    return store.syncBlobFaces === true && typeof store.putBlob === "function" && typeof store.getBlob === "function" ? store : undefined;
+}
+export function blobGetterOf(store) {
+    const faces = syncBlobFacesOf(store);
+    return faces ? (hash) => faces.getBlob(hash) : async () => undefined;
+}
 export function fileHistoryImportFace(fs) {
     const candidate = fs?.importHistory;
     if (typeof candidate !== "function")
@@ -11,10 +39,21 @@ export async function replayFileHistory(store, scope, envelope, srcGetBlob, opts
     if (face === undefined) {
         return { ok: false, error: { code: "unsupported_format", message: "this deployment's file-history store has no importHistory seam" } };
     }
-    let r = await face.importHistory(scope, envelope, srcGetBlob);
+    const attempt = async () => {
+        let missing;
+        const observed = async (hash) => {
+            const bytes = await srcGetBlob(hash);
+            if (bytes === undefined && missing === undefined)
+                missing = hash;
+            return bytes;
+        };
+        const r = await face.importHistory(scope, envelope, observed);
+        return r.ok || missing === undefined ? r : { ok: false, error: r.error, missingBlob: missing };
+    };
+    let r = await attempt();
     if (!r.ok && r.error.code === "conflict" && opts.allowReplace && typeof store.deleteBySession === "function") {
         await store.deleteBySession(scope);
-        r = await face.importHistory(scope, envelope, srcGetBlob);
+        r = await attempt();
     }
     return r;
 }
@@ -29,10 +68,10 @@ export async function exportSessionManifest(sessionId, srcBackend, historyStore)
     const entryIds = await listEntryIds(sessionId);
     if (entryIds === null)
         return null;
-    const getLeafId = session.getLeafId?.bind(session);
-    const leafId = getLeafId ? await getLeafId(sessionId) : null;
+    const headOf = headReadOf(session);
+    const leafId = headOf ? ((await headOf(sessionId))?.leafId ?? null) : null;
     const fs = historyStore;
-    const fileHistory = typeof fs.exportHistory === "function" ? await fs.exportHistory(sessionId) : null;
+    const fileHistory = await exportedFileHistory(fs, sessionId);
     const policyStore = srcBackend.sessionPolicy();
     const policy = typeof policyStore.listBySession === "function"
         ? await policyStore.listBySession(sessionId)
@@ -43,8 +82,7 @@ export async function exportSessionManifest(sessionId, srcBackend, historyStore)
     if (summaryOf === undefined)
         throw new Error("exportSessionManifest: the session store has no row read face (sessionSummaryOf) — the sessionSync fact should have refused this deployment");
     const row = await summaryOf(sessionId);
-    const getBlobFn = fs.getBlob?.bind(fs);
-    const getBlob = getBlobFn ? (hash) => getBlobFn(hash) : async () => undefined;
+    const getBlob = blobGetterOf(fs);
     return {
         manifest: { sessionId, entryIds, entryCount: entryIds.length, leafId, fileHistory, policy, anchors, ...(row !== undefined ? { title: row.title, pinned: row.pinned } : {}) },
         getBlob,
@@ -57,18 +95,25 @@ export async function planSync(sessionId, srcBackend, dstBackend) {
     const dstEntries = (await ownerAware(dstBackend).exportEntries?.(sessionId)) ?? null;
     return classifySyncRelationship(srcEntries, dstEntries);
 }
-export function sameRulesContent(stored, incoming) {
+export function sameRulesContent(stored, incoming, operator) {
     if (stored === null)
         return false;
     const norm = (r) => JSON.stringify(normalizeRules(r));
     if (norm(stored) !== norm(incoming))
         return false;
-    return loosenReasons(stored, incoming).length === 0 && loosenReasons(incoming, stored).length === 0;
+    if (loosenReasons(stored, incoming).length !== 0 || loosenReasons(incoming, stored).length !== 0)
+        return false;
+    return operatorPartUnmoved(stored, incoming, operator);
+}
+function operatorPartUnmoved(stored, incoming, operator) {
+    const next = judgeSessionRulesWrite(stored, incoming, { operator });
+    const partOf = (row) => JSON.stringify(normalizeRules(row.operatorRules ?? row));
+    return partOf(next) === partOf(stored);
 }
 export async function replayPolicyRecords(store, sessionId, records, operatorOk) {
     for (const rec of records) {
         const cur = await store.getRules(sessionId, rec.principal);
-        if (sameRulesContent(cur, rec.rules))
+        if (sameRulesContent(cur, rec.rules, operatorOk))
             continue;
         await store.putRules(sessionId, rec.principal, rec.rules, { operator: operatorOk });
     }

package/dist/session-titler.d.ts

@@ -27,10 +27,6 @@
 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,
-     *  listed over HTTP, and logged, all outside the trace redact pipeline; wire src/trace/redact.ts here). */
-    redact?: (text: string) => string;
     /** Write-once store leg (SQL twins / local sidecar). Resolves false when a title already existed. */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
     /** Cheap pre-LLM probe: "titled" = skip (a restart/evicted-seen/another replica
@@ -68,8 +64,13 @@ export interface SessionTitler {
      *  已有标题 / 竞态输了 / 模型失败 / 空标题 / 这个会话已有一次在飞的调用,都不调。回调同步执行、**不许抛**;抛了也不影响已落行的标题(见下 `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. */
+/** 标题的显示预算(码元,含截断记号)—— 界的属主是出口座的 `session-title` 行,这里读它;落在 `title` 列宽 `SESSION_TITLE_MAX_CHARS`(session-row.ts)之内。 */
+export declare const TITLE_MAX_CHARS: number;
+/**
+ * 模型回的标题 → 落行的标题:**经出口座的 `session-title` 行**([ref])—— 脱敏(按单行出门形读:被控制字符拆开、被换行拆开的令牌都读过)→ 渲染 →
+ * 单行化(换行折成空格、剥控制与双向字符、去首尾空白与首尾引号)→ 按记号边界截到 {@link TITLE_MAX_CHARS} 码元(含 `…`)。
+ * 此前是「可选注入的脱敏 → 剥 → 截」三步各在一处:没注入就不脱;剥在脱之后,BEL 拆开的令牌两半在剥时拼回整枚;截在脱之后,界切进记号留半枚。
+ */
 export declare function sanitizeTitle(raw: string): string;
 export declare function buildTitlePrompt(objective: string): string;
 export declare function createSessionTitler(deps: SessionTitlerDeps): SessionTitler;

package/dist/session-titler.js

@@ -1,13 +1,11 @@
-import { stripControlAndBidi } from "@sema-agent/settings-schema";
 import { recordFailOpen } from "./observability/fail-open.js";
-import { redactSecrets } from "./trace/redact.js";
+import { seatMaxChars, seatText } from "./trace/exit-seat.js";
 import { userAuthoredText } from "./user-authored-text.js";
 import { buildSessionTitledFrame } from "./session-titled-frame.js";
-export const TITLE_MAX_CHARS = 80;
+export const TITLE_MAX_CHARS = seatMaxChars("session-title");
 const OBJECTIVE_SNIPPET_CHARS = 600;
 const LLM_TIMEOUT_MS = 15_000;
 const NO_ROW_RETRY_MS = 20_000;
-const FAIL_CAUSE_KEY_CHARS = 80;
 const SEEN_CAP = 10_000;
 function failOpenTagFor(code) {
     switch (code) {
@@ -30,9 +28,7 @@ function failOpenTagFor(code) {
     }
 }
 export function sanitizeTitle(raw) {
-    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;
+    return seatText("session-title", raw);
 }
 export function buildTitlePrompt(objective) {
     const text = userAuthoredText(objective);
@@ -46,11 +42,10 @@ export function buildTitlePrompt(objective) {
 }
 export function createSessionTitler(deps) {
     const seen = new Set();
-    const redactedError = (error) => redactSecrets(error);
     const logFailure = (sessionId, error, code) => {
-        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));
+        const safe = seatText("operator-log-text", error);
+        deps.logger?.debug?.("session_title_failed", { sessionId, error: safe });
+        recordFailOpen(failOpenTagFor(code), safe);
     };
     const probeOrContinue = async (sessionId, continueWord) => deps
         .probeTitle(sessionId)
@@ -90,7 +85,7 @@ export function createSessionTitler(deps) {
                     logFailure(sessionId, r.error, r.code);
                     return;
                 }
-                const title = sanitizeTitle(deps.redact ? deps.redact(r.text) : r.text);
+                const title = sanitizeTitle(r.text);
                 if (!title) {
                     deps.metrics?.inc("session_title_total", { outcome: "empty" });
                     return;
@@ -112,7 +107,7 @@ export function createSessionTitler(deps) {
                     }
                     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) });
+                        deps.logger?.warn?.("session_titled_frame_failed", { sessionId, error: seatText("operator-log-text", String(e)) });
                     }
                 }
             })().catch((e) => {

package/dist/session-watch.d.ts

@@ -16,7 +16,7 @@
  *  - **冷启动 warm**:新条目 lastChangeAt=0(没观测到变化就不算热)——首拍一次 hotMs 快确认后即落
  *    warm 拍距,直到真观测到跳变才进热窗(codex:重连风暴下 256 会话×200ms=对存储的自造尖峰)。
  *
- * Deliberately backend-agnostic (tidb|pg|local all go through getLeafId — the seamless-local-cloud
+ * Deliberately backend-agnostic (tidb|pg|local all go through the session store's one by-id read `headOf` — the seamless-local-cloud
  * invariant): no PG LISTEN/NOTIFY specialization, no shared bus. Latest-wins semantics: subscribers
  * converge on the newest leafId; intermediate hops may be dropped (content still comes from tail faces).
  */
@@ -38,7 +38,7 @@ export declare class SessionWatchRegistry {
     /** 五轮复审:owner 与 leaf **同拍原子读**——探针每拍先核 owner(被删=undefined/换主=≠条目 owner
      *  ⇒ dropSession 断全部订阅者),匹配才应用 leaf。跨副本 reclaim 的披露窗从 25s 心跳收紧到
      *  ≤一个探针拍(hot 200ms/warm 2s),且旧流在新主推进**之前**先死(owner 检查先于 leaf 应用)。 */
-    private readonly getHead;
+    private readonly readHead;
     private readonly entries;
     private readonly hotMs;
     private readonly warmMs;
@@ -48,7 +48,7 @@ export declare class SessionWatchRegistry {
     /** 五轮复审:owner 与 leaf **同拍原子读**——探针每拍先核 owner(被删=undefined/换主=≠条目 owner
      *  ⇒ dropSession 断全部订阅者),匹配才应用 leaf。跨副本 reclaim 的披露窗从 25s 心跳收紧到
      *  ≤一个探针拍(hot 200ms/warm 2s),且旧流在新主推进**之前**先死(owner 检查先于 leaf 应用)。 */
-    getHead: (sessionId: string) => Promise<{
+    readHead: (sessionId: string) => Promise<{
         leafId: string | null | undefined;
         owner: string | null | undefined;
     }>, opts?: SessionWatchOptions);

package/dist/session-watch.js

@@ -5,14 +5,14 @@ export function posIntEnv(raw, fallback, max = 3_600_000) {
     return Number.isInteger(n) && n > 0 && n <= max ? n : fallback;
 }
 export class SessionWatchRegistry {
-    getHead;
+    readHead;
     entries = new Map();
     hotMs;
     warmMs;
     hotWindowMs;
     maxWatched;
-    constructor(getHead, opts) {
-        this.getHead = getHead;
+    constructor(readHead, opts) {
+        this.readHead = readHead;
         this.hotMs = opts?.hotMs ?? 200;
         this.warmMs = opts?.warmMs ?? 2000;
         this.hotWindowMs = opts?.hotWindowMs ?? 60_000;
@@ -109,7 +109,7 @@ export class SessionWatchRegistry {
             e.urgent = false;
             const revAtStart = e.rev;
             try {
-                const head = await this.getHead(sessionId);
+                const head = await this.readHead(sessionId);
                 if (this.entries.get(sessionId) !== e)
                     return;
                 if (head.owner === undefined || head.owner !== e.owner) {

package/dist/sighup-idle.d.ts

@@ -9,14 +9,14 @@
  *
  * 诚实边界:idle-but-live 的 peer(两 turn 之间静默超过窗口)会碰到引擎已退→壳 dead-respawn 1-2s 自愈
  * (伤害面从 mid-turn 斩降级为冷启动)。
- * S-1281:附着(打开着的 SSE 流)是判据的第二格 `attached` —— 只读订阅自此不进 inflight(排空不该等一个看着的壳),而一个只挂着订阅流的
+ * [ref]:附着(打开着的 SSE 流)是判据的第二格 `attached` —— 只读订阅自此不进 inflight(排空不该等一个看着的壳),而一个只挂着订阅流的
  * peer 壳(cli 附着形:`GET /v1/approvals/stream` 常开)仍然是「有人在用」,靠这一格不被当成孤儿。修前这一形是订阅流被算进 inflight
  * 时顺带挡住的;拆开之后两件事各有一格,规则不变:inflight = 0 ∧ attached = 0 ∧ 活性静默满窗才关。
  */
 export interface SighupIdleDeps {
     /** This replica's in-flight legs (drainState.inflight). */
     inflight: () => number;
-    /** S-1281:打开着的 SSE 流条数(drainState.attachedStreams,附着租约同一只 getter)。> 0 ⇒ 有壳挂着,同 inflight 一样重置窗口。
+    /** [ref]:打开着的 SSE 流条数(drainState.attachedStreams,附着租约同一只 getter)。> 0 ⇒ 有壳挂着,同 inflight 一样重置窗口。
      *  缺席 ⇒ 视为 0(单测 / 嵌入形)。 */
     attached?: () => number;
     /** MONOTONIC-clock ms of the last non-probe HTTP request (drainState.lastActivityAt). Covers what inflight

package/dist/spec-fields.d.ts

@@ -44,9 +44,9 @@ export declare function normalizeResumeAtMode(v: unknown, resumeAtResolved: bool
  *  **技能**条数帽不是同一轴:技能清单由引擎按预算渲染(超了裁描述),agent 定义没有那个预算面。 */
 export declare const MAX_TASK_AGENTS = 32;
 /**
- * core 7.41.0 #1303 —— 技能的两只清单 `allowedTools` / `disallowedTools`(`dist/core/agent-definition.d.ts`:本次 run 的 allow 规则来源 /
+ * core 7.41.0 [ref] —— 技能的两只清单 `allowedTools` / `disallowedTools`(`dist/core/agent-definition.d.ts`:本次 run 的 allow 规则来源 /
  * deny 规则来源,不是围栏)的**形**谓词。两道技能门(顶层 `body.skills[]` 的 `validateUserSkills`、`agents[].skills[]` 的
- * {@link SKILL_FIELD_SHAPES})**同一只**:一边判一边不判 = 同一个键两种话(S-377 baseDir 吃过的亏)。
+ * {@link SKILL_FIELD_SHAPES})**同一只**:一边判一边不判 = 同一个键两种话([ref] baseDir 吃过的亏)。
  *
  * 本谓词只判「字符串数组」(core 7.42.0 起与请求的 `settings.permissions.allow`、运维的 `APPROVAL_GRANT` **同一只**:`rule-entry-list.ts` 的
  * `ruleEntryListShapeOk`):引擎直接 `for (const entry of list)` —— 一个裸字符串 `"Bash"` 会被逐字符迭代成 `B` / `a` / `s` / `h` 四条
@@ -80,7 +80,7 @@ export interface TaskAgentsRefusal {
 /** [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 起
+ *  **名字归引擎一只判**(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`)四类全拒(近似名 · 退役名 · 文法读不出 · `*`),
  *  **放行侧**(`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` 点名现名、续跑按方向分流;
@@ -150,7 +150,7 @@ export declare function retainBackgroundProcessesFromBody(raw: unknown, requireP
  *  undefined(不挂键=core 缺省,byte-compat)。HTTP 门另有 fail-loud 400(提交面邻居姿势)。 */
 export declare function toolNameListFromBody(raw: unknown): string[] | undefined;
 /**
- * S-1448(core 7.49.0 #1623 / [ref])—— body.allowTools → `TaskSpec.allowTools`:引擎的**可用性选择器**,原样透传。
+ * [ref](core 7.49.0 [ref] / [ref])—— body.allowTools → `TaskSpec.allowTools`:引擎的**可用性选择器**,原样透传。
  *
  * 一条规则:这一 run 能用哪些工具由引擎一只运算答(`universe ∩ ceiling ∩ allow − deny`,prepare 对真实挂载的一切算一次)。
  * 本仓**零读法** —— 不算补集、不逐项过滤(`[]` = 什么都不给,是合法值,不折成缺席;非串条目与未知名由引擎在 prepare 拒,

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

@@ -1,5 +1,5 @@
 /**
- * S-131 —— SQL **引擎姿态**的运维读面(单一推导点,同 `memory-posture.ts` 的形制)。
+ * [ref] —— SQL **引擎姿态**的运维读面(单一推导点,同 `memory-posture.ts` 的形制)。
  *
  * ## 病
  *
@@ -11,7 +11,7 @@
  *
  * `sql-driver.ts` 的连接初始化在**每条池连接**上钉死这两件事并**回读复核**(`@contract txn.read-semantics`)。
  * 本模块把那份读数拿出来,一次推导两个读面:operator 面(`GET /v1/diagnostics/wiring` 的 `sqlEngine` 段,
- * 全量)与消费端面(`GET /v1/capabilities` 的 `store.sql` 位(7.106.0 起;此前顶层 `sql`,S-866 ①),窄投影)。两面同源 —— 「诊断页说悲观、能力位说
+ * 全量)与消费端面(`GET /v1/capabilities` 的 `store.sql` 位(7.106.0 起;此前顶层 `sql`,[ref] ①),窄投影)。两面同源 —— 「诊断页说悲观、能力位说
  * 乐观」在结构上不可能。
  *
  * ## 两条诚实纪律(与 memory-posture 同源)
@@ -52,7 +52,7 @@ export type SqlEngineSeatIssue = "required" | "bad_shape";
  * 都是 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` 缺席。 */
+/** 消费端窄投影(`GET /v1/capabilities` 的 `store.sql` 位;7.106.0 前是顶层 `sql`,[ref] ①)。`null` = 驱动此刻给不出事实 ⇒ `store.sql` 缺席。 */
 export interface SqlEngineCapability {
     engine: SqlEngineFacts["engine"];
     isolation: string;

package/dist/store-posture.d.ts

@@ -1,5 +1,5 @@
 /**
- * S-866 ①(设计稿 v1.1 §2①)—— 「这台副本**真的在持久化吗**」的单一推导点:caps `store`、`/health.storeDegraded` / `durable:false`、
+ * [ref] ①(设计稿 v1.1 §2①)—— 「这台副本**真的在持久化吗**」的单一推导点:caps `store`、`/health.storeDegraded` / `durable:false`、
  * gauge `store_backend_degraded` 三面读**同一只装配值**({@link StorePosture},`boot/stores.ts` 铸一次)。
  *
  * ## 病
@@ -53,7 +53,7 @@ export interface StoreCapability {
     readonly durable: boolean;
     readonly degradedReason?: StoreDegradedReason;
     /** 7.105.0 及以前的顶层 `sql` 对象,原样搬入(`{engine, isolation, txnMode}`)。present-iff `backend ∈ {mysql, pg}` ∧ 驱动此刻给得出
-     *  回读复核过的事实 —— 最近一次连接初始化被拒(S-137 ④)时驱动交 `null`,本键随之缺席(此前是顶层 `sql:null`)。 */
+     *  回读复核过的事实 —— 最近一次连接初始化被拒([ref] ④)时驱动交 `null`,本键随之缺席(此前是顶层 `sql:null`)。 */
     readonly sql?: SqlEngineCapability;
 }
 /** 装配值 → caps 投影(纯函数)。 */

package/dist/stored-request-tool-axes-m19.d.ts

@@ -9,7 +9,7 @@
  * ⇒ 永远批不过去。持久数据面不能「翻红」,所以给它一次性迁移:窗开着时,续跑重放腿把判官判不过的那一格按升级前的读法重读一次,产物**再交同一只判官**
  * (不过 ⇒ 原臂:整条不进);真挂上的这类 server 由请求腿说一行运维 warn `mcp_tool_axes_read_as_before_upgrade`。窗关之后回到今天的读法,删码零行为变化。
  *
- * ## A2A 一面(同一种病,同一只重读座;core 7.53.0 #1835 提货批)
+ * ## A2A 一面(同一种病,同一只重读座;core 7.53.0 [ref] 提货批)
  * core 7.53.0 起 A2A 请求腿的 `toolAxes` 读者也是引擎的判官(`readToolAxes(…, "a2a")`)。7.131.x 的 A2A 请求腿读者对每只 skill 的记录只挑三个轴、**多余成员静默忽略**、
  * 照挂 ⇒ 存量体里带多余成员的那条对端,续跑重放时整条不进,停驻在它某只 skill 审批上的任务同样永远批不过去。同一只重读座覆盖它,律只有一句:**重读复现那一面升级前
  * 的读法,一个成员都不多救** —— A2A 那一面交 {@link readA2aToolAxesAsServer7131M19}(7.131.x 的读者逐字:未知成员忽略;已知轴写坏 —— `effect` / `irreversibility` 出词表、

package/dist/task-a2a.d.ts

@@ -1,100 +1,73 @@
-/**
- * [DESIGN-269 车1 §2.2/§2.3 — A2A client seam] — project a caller's per-request A2A peers
- * (`TaskRequest.a2aPeers`) into the engine, so a `sema` run can talk to the agents the USER declares,
- * not only the ones the deployment's web-admin declares. Point-for-point mirror of `task-mcp.ts`
- * (the MCP seam), because the trust question is the same question — and deliberately NOT a copy where
- * the two protocols differ (see 「A2A 比 MCP 窄」 below).
- *
- * 🔒 SECURITY — an A2A peer is a remote **AGENT**, not a data source: it acts on its own side. core ruled
- * (2026-08-03, `A2aServerSpec` doc) that every skill such a peer advertises mounts with `egress: true` +
- * `effect: "write"`, i.e.接入即引入对外写通道 — it registers the approval gate, is never auto-allowed on a
- * no-policy deployment, and its replies reach the model inside an untrusted-data fence. The trust boundary
- * is therefore the SAME one the MCP seam draws, for the same reason:
- *   - SINGLE-USER deployment (`requirePrincipal !== false`… i.e. `!== true`): the requester IS the
- *     super-admin of their own worker, so the peers they name are their own choice (CC-parity), on EVERY
- *     execution lane — an A2A call is a plain outbound HTTPS request made by the worker, so the lane where
- *     the agent's TOOL CALLS run is irrelevant (exactly the fact that decoupled the MCP gate from the lane).
- *   - MULTI-TENANT deployment (`requirePrincipal === true`): a tenant must NOT make the SHARED worker POST
- *     to a body-chosen URL (SSRF) carrying body-chosen headers, nor mount write-capable tools from an agent
- *     the operator never vetted. Gate CLOSED → body peers ignored; the fleet gets peers only through center
- *     config (`config.a2aPeers`).
- * When the gate is closed a sent `a2aPeers` is IGNORED — and SAID (`a2a_injection_ignored` + the
- * `capabilities.a2aInjection` advertisement), never silently swallowed.
- *
- * ⚠️ **A2A 的轴比 MCP 窄,这不是简化而是协议事实**:A2A has no per-skill annotation vocabulary, so there is
- * no server-hint leg to fold — `toolAxes` (the CALLER's own judgement) is the ONLY thing that can move an axis
- * off the fail-closed default. core says as much on `A2aToolAxis`: `irreversibility:"never"` / `egress:false`
- * 「appears ONLY via an explicit caller override」, enforcement ignores the loosening (tighten-only) and the
- * ask's risk-axes REPORT face consumes it. So this module carries the caller's overrides through verbatim —
- * they are a judgement, not silence — while knowing that core will not let them widen enforcement.
- *
- * ⚠️ **两票判据的词表在 core 5.36 尚未到货**(分单件 C-1/C-2,core 已认领排 5.37 后首个 A2A 窗):
- * `LockedKey` 是 `"mcp"|"toolPolicy"|"compliancePosture"|"retentionPolicy"`,`ComplianceCapability` 是
- * `"mcp_servers"|"workflows"|"web_fetch"|"org_memory_mount"` —— 两张表里都还没有 A2A 的位。本模块因此按
- * **字符串**判(server config 的 `lockedConfigKeys` 本就是 server 自己的声明面,不经 core 闭集型),
- * 判据一到货就换 core 真源、钉子逐字不用改。
- * 🔴 **今天这两票在 env 通道上还打不响**,而这是刻意如实记下的、不是被忽略的缺口:`LOCKED_CONFIG_KEYS`
- * 经 core 的 `resolveLockedKeys` 校验(未知键拒启)、`COMPLIANCE_ADDITIONAL_DENIES` 经 `COMPLIANCE_CAPABILITIES`
- * 校验(同拒),所以运维今天**写不进** `a2a` / `a2a_peers`。而且合规那一票还有第二层:即便有人跳过 boot 期
- * 校验把 `a2a_peers` 塞进档位,`resolveComplianceDenies` 对闭集外的词是**抛**(亲测 core 5.36),于是这条
- * 请求腿的失败方向是**响亮**(500)而不是安静放行 —— 方向正确,故本模块不加任何兜底。两票的代码先在场是
- * 纵深:core 词表到货那一拍这条腿自己就活了,不需要有人记得回来补;反过来(等词表到了再写判据)才是
- * 「广告了却拦不住」的那一类缺口。钉在 `test/task-a2a.test.ts`(含到货后该怎么改那一格的原地说明)。
- */
-import { type A2aServerSpec, type CompliancePosture } from "@sema-agent/core";
+import type { A2aServerSpec } from "@sema-agent/core";
+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";
 /** Bound on caller-supplied peers (anti-DoS; a real declaration names a handful of agents). */
 export declare const MAX_REQUEST_A2A_PEERS = 32;
-/** The deployment-facing shape this module reads. `lockedConfigKeys` is deliberately `readonly string[]`
- *  and not core's `LockedKey[]`: the `a2a` member does not exist in core's union yet (see module header),
- *  and a predicate that cannot even NAME the key it guards is a predicate that silently guards nothing. */
-export interface A2aGateConfig {
-    requirePrincipal?: boolean;
-    lockedConfigKeys?: readonly string[];
-    compliancePosture?: CompliancePosture;
+/**
+ * 一条**没有被挂上**的请求腿对端的事实 —— 运维 warn `a2a_injection_dropped` 的 `dropped` 条目(`validateRequestA2a` 的 `dropped` 同形)。与 MCP 面 {@link McpInjectionDrop}(`mcp_injection_dropped`)
+ * **同形同键名**:`reason` · `field`,只有名字键各座自己的(MCP `server` ↔ A2A `peer`;键集两向钉在下面的 `_GuardDropKeys*` 上,任一边改名 ⇒ 编译红)。
+ *  · `peer`:申报名(调用方文本,限长 128,读不出 ⇒ `<malformed>`;撞帽的尾项是一条合并标签 `(+N over cap of 32)`);
+ *  · `reason`:**判官表**({@link A2A_PEER_KEY_JUDGES})对这一键的原因句 —— 与同一份体上新提交门 400 拒句里的那一句逐字同一句(同一只组句器 `declarationIssueFacts`,不回显值),**只有一臂例外**:
+ *    一次性迁移 M19 的重读入参克隆不了(访问器成员 / BigInt / Proxy / 环 / 非纯数据)⇒ 句子带前缀 `declaration not cloneable (<because>) — the one-time migration re-reads the stored declaration as plain JSON data and this one is not; `,**其后**才是判官对原声明的那一句(新提交门不铸这一臂,所以 400 拒句里没有这个前缀);
+ *    条目不是对象 = 列表级骨架的头一句(`declarationEntryNotObject`);撞帽 = 撞帽铸点的头一句(`declarationOverCapFacts`,受理口撞帽拒句以同一句开头)。**`reason` 只有一种内容 = 句子**,本座不自铸原因词,
+ *    机读词(`over_cap`)留在 400 拒体的 `facts`、不进日志的 `reason`;
+ *  · `field`:体内坐标 `a2aPeers[i].<键路径>`(条目不是对象 ⇒ `a2aPeers[i]`;撞帽 ⇒ `a2aPeers`),与受理口拒体 `field` 同一个坐标系。
+ * 与 MCP 面的差只有两处,都是各自协议的事实:MCP 的 `reason` 是引擎词表的闭集词(`malformed_entry` …),A2A 引擎没有这张词表,`reason` 恒是句子(判官的答案 / 撞帽句);MCP 的 `field` 是条目内键路径,
+ * A2A 的是体内绝对坐标(它的拒体 `field` 本就如此)。
+ */
+export interface A2aInjectionDrop {
+    readonly peer: string;
+    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;
 /**
- * Does THIS deployment honor caller-supplied per-request A2A peers? Three vetoes, ALL of them here (this
- * predicate is the single owner — the capability bit and the request leg both read it, so there is exactly
- * one place where the answer can be wrong):
- *   ① the deployment locks the `a2a` key — a locked deployment that advertised `a2aInjection:true` would
- *      hand every consumer an affordance whose every use 400s (`config.locked_key`); "says yes ⟺ route
- *      works" breaks on the spot. Same conjunction, same reason, as `mcpInjectionHonored`'s lock veto;
- *   ② the compliance posture denies `a2a_peers` — advertised-but-refused again;
- *   ③ multi-tenant (`requirePrincipal === true`) — a tenant cannot point the shared worker at an agent.
- *
- * ⚠️ **`resolveComplianceDenies` is deliberately NOT wrapped in try/catch** (same ruling as the MCP twin):
- * it is fail-loud on a posture outside the closed set, and the posture has already been validated twice
- * before reaching here (config parse + boot assembly). If it ever throws here, someone bypassed both doors
- * and the LOUD direction (route 500) is the correct one — swallowing it into a boolean would let a
- * deployment with a broken posture keep advertising the capability (仓规:安全轴禁静默兜底).
+ * 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.
  */
 export declare function a2aInjectionHonored(config: A2aGateConfig): boolean;
+/**
+ * 请求体 `a2aPeers[i]` 的**键闭集**(判序 = 本数组序:名 → 对端地址 → 它的 agent card 地址 → 凭据头 → 身份头 → 技能收窄 → 轴覆写)。两向钉在 core 的 `A2aServerSpec` 上:
+ * 型上多一个键而表没跟 ⇒ 编译红(新键会被词表外的键门 400 掉 —— wire 上的静默回归);表里写一个型上没有的词 ⇒ 也红。于是这张表是从 core 的型**派生**出来的数据,而不是谁记得去同步的清单。
+ */
+export declare const A2A_PEER_ENTRY_KEYS: readonly ["name", "url", "cardUrl", "headers", "principalHeader", "allowSkills", "toolAxes"];
+/**
+ * **请求入口的一次读**(`boot/resolve-spec.ts` 在腿首铸一份,受理门与读器——续跑重放腿只有读器——都吃这一份):`body.a2aPeers` 若是数组,返回同形数组
+ * (每个对象条目换成它的 {@link PeerSnapshot};非对象条目原样;长度保真 —— 界外的条数仍是受理门撞帽拒与读器丢弃留声的依据,只快照界内的条目);不是数组(缺席 / `null` / 别的形)原样返回。
+ * 为什么在入口铸而不是各调用点各铸:快照按调用点铸,受理口一份、读器一份,嵌入方递来的 getter 对象在两次读之间变形(第一次给干净 URL、第二次给带凭据 URL;`headers` 成员第一次
+ * `Bearer accepted`、第二次 `Bearer changed`)就让门判第一份、读器挂第二份 —— 门独有的凭据一问被绕过、鉴权头被换掉。入口铸一次、往下传,「门判的就是读器挂的」才字面成立;
+ * 快照是纯数据到叶子(见 {@link PeerSnapshot}),后续任何读者都不再触碰源对象。
+ */
+export declare function snapshotRequestA2a(raw: unknown, options: {
+    readonly reread: boolean;
+}): unknown;
 /** 读这条对端的是哪条腿:`fresh` = 新提交;`resume` = 续跑重放升级前存下的请求体(`boot/resolve-spec.ts` 的 `opts.leg` 分流,同一个读法)。 */
 type A2aRequestLeg = "fresh" | "resume";
 /**
  * Shape-check the raw `body.a2aPeers`. `null` → a non-array (caller error; the route may 400). Otherwise the
- * valid subset + the names of dropped (malformed/over-cap) entries.
+ * valid subset + the dropped (malformed/over-cap) entries as {@link A2aInjectionDrop} facts (peer name · reason · body coordinate).
  */
 export declare function validateRequestA2a(raw: unknown): {
     ok: A2aServerSpec[];
-    dropped: string[];
+    dropped: A2aInjectionDrop[];
 } | null;
 /**
- * DESIGN-269 §2.4 —— **同步**拒面:部署锁了 `a2a` 而请求仍带 `a2aPeers` ⇒ 400 `config.locked_key`
- * (逐字沿用 `assertRequestMcpUnlocked` 的裁定,连错误码都同一个 —— 消费端判的是「某个键被行政锁住了」,
- * 不是「哪个键」;码分裂只会让 SDK 多写一条等价分支)。
- *
- * 判据是「请求**占位**」而不是「请求的值合不合法」:锁是两态的,占了就整拒,不静默丢(静默丢正是把
- * 判决变成探针的那一形)。键缺席 / 显式 `null` 都不是占位;**空数组是占位**(调用方确实写了这个键)。
- *
- * ⚠️ **不看车道**:多租户腿本来就会忽略 body peers(`a2aInjectionHonored` 关),但锁在场时「忽略」是
- * 错的失败方向 —— operator 声明了「本部署不收任务自带 A2A peer」,那就该说出来。
+ * 请求体 `a2aPeers`「这份声明能不能原样用」的回答者(与 MCP 的 `requestMcpDeclarationRefusal` 同一副骨架、同一个拒形):
+ *  ① **列表**:在场却不是数组 / 超过 {@link MAX_REQUEST_A2A_PEERS} 条(撞帽机读位一组键)/ 某一条不是对象 ⇒ `400 request.field_invalid`;
+ *  ② **键名**:条目上词表外的键 ⇒ `400 request.body_shape` + `unknownKeys`;
+ *  ③ **键值**:逐键问判官表 {@link A2A_PEER_KEY_JUDGES} ⇒ `400 request.field_invalid`,拒句点名 `a2aPeers[i].<键路径>`、peer 名与该键判官的原因句;`url` / `cardUrl` 带凭据时拒体另带机读 `field` / `reason`。
+ * 整份拒而不是挂前 32 条 / 丢掉读不出的那条 / 整只忽略:一份被悄悄截短、少了几条或整只没生效的声明,在发送方那里读起来是「生效了」(修前:这些形全部 200 + 运维 warn;其中 `allowSkills`
+ * 写成 `allowSkill` 的对端照样挂上远端卡声明的全部技能 —— 收窄意图坏形时退化成放行)。同时这份体整份落盘,界内每一条的 `url` / `cardUrl` 都被判官看过 —— 超过界的列表整份拒,所以扫描有界。
  *
- * ⚠️ 参数类型是 `ReadonlySet<string>`:core 的 `LockedKey` 尚无 `a2a` 成员(见模块头),而
- * `ReadonlySet<LockedKey>` 结构上可当 `ReadonlySet<string>` 传入,所以调用点无需任何转换。
+ * 纯值域、与租户车道无关(多租户腿整只 `a2aPeers` 本会被忽略,告诉调用方「这样写不行」只多不少)。
+ * 只在 fresh 门上判(`boot/resolve-spec.ts` 在 MCP 条目门旁):重放存量 body 的腿不问它 —— 拒会砖死升级前停驻的任务(本仓 `opts.leg` 先例),走宽容读器({@link resolveRequestA2a}:坏条目不挂 +
+ * `a2a_injection_dropped` 留声)。A2A serve 腿(`routes/a2a-serve.ts`)铸的体只有 `objective` / `taskId` / `sessionId` / `scenario` 四键,到不了这一座。
  */
-export declare function assertRequestA2aUnlocked(bodyA2a: unknown, lockedKeys: ReadonlySet<string>): void;
+export declare function requestA2aDeclarationRefusal(list: unknown): DeclarationRefusal | undefined;
+/** 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
  * clash — a caller can ADD a peer but can never SHADOW a configured one. This is load-bearing on THIS lane