@sema-agent/server 7.43.0 → 7.44.0

package/dist/http/routes/a2a-serve.js

@@ -1,75 +1,3 @@
-/**
- * DESIGN-269 §3 车2 —— **server-as-peer** 半场:这台 sema-server 被别的 orchestrator 当成一个 A2A agent 调用。
- *
- * 两条路由,**刻意分挂在服务凭据门的两侧**(clay 终裁 R-11,2026-08-16):
- *  · `GET /.well-known/agent-card.json` —— 门**外**。公网匿名可发现:一张卡就是「这里有一个 agent、
- *    它叫什么、能干什么、往哪儿调」,没有它对端连协商都开始不了。卡上**零存量信息**(没有任何 task /
- *    run / session 面),所以匿名可读不构成披露。
- *  · `POST /v1/a2a` —— 门**内**。JSON-RPC 调用面,吃与本仓其余 API 同一套服务凭据(`headers` 形),
- *    与我们 client 腿发出去的鉴权形对称。
- *
- * 总旋钮 `A2A_SERVE_ENABLED` 默认 **OFF**,OFF ⇒ 两条路由**都** 404(`config.a2aServe === undefined`
- * 即 OFF —— 缺席即关,见 config-types 的 {@link import("../../config-types.js").A2aServeConfig})。
- * 「不是发卡但拒调」是设计稿 §3.3 的原话:对外不存在就该整个不存在。
- *
- * ## 演化槽(设计稿 §4,本模块吸收其中三个)
- *  · **版本槽**:读请求 `a2a-version` 头 —— 认识与否都照常答,响应恒带自己的版本头。版本头是**诊断材料**
- *    不是拒绝闸(开集容忍);真不兼容会在方法/形状层自然显形为具名错误。
- *  · **方法槽**:分派器是一张 {@link A2A_METHODS} 方法表,新方法=加一行;未知方法恒 `-32601`。
- *    这是**协议内置的能力协商机制** —— 调用方按码降级,我们不自铸能力表。
- *  · **词表槽**:任务态只发 core `A2A_TASK_STATES` 九词闭集(我们是铸点)。
- *
- * ## v1 明确不做(成文定界,防镀金 —— 设计稿 §3 尾)
- *  · `message/stream`(SSE 腿)、push notification —— 未实现方法走 -32601,调用方按协议降级到轮询。
- *  · `tasks/cancel` —— v2 映射到既有 cancel 链(`POST /v1/runs/:id/cancel`);v1 不做半吊子取消。
- *  · card `securitySchemes` —— 我们的鉴权是**头形**,卡上如实不声明 OAuth 类 scheme,不假装。
- *  · file / data part 的**消费** —— v1 只收 text part,其余 part **具名拒绝**(-32005),不静默丢:
- *    静默丢一个附件等于把「我没看见你给的文件」渲染成「我看过了」。
- *  · 批量(数组形)JSON-RPC —— 一个批里半数成功半数失败的**记账**语义要单独想清楚,先具名拒。
- *
- * ## 🔴 id 域的定谳(施工期裁决,与设计稿 §3.2 的措辞有偏离,理由成文于此)
- * 设计稿 §3.2 写的是「`canAccessAgentRecord` 门后 `toA2ATaskState(record)` 投影」,那三只 core 原语
- * 的入参是 **`BackgroundAgentRecord`**(`a*` 句柄域 = 一次 run **内部**派生的后台子 agent 行)。而
- * 本车的硬约束是「`message/send` 必须复用既有提交链、不另铸提交路径」——既有提交链(`prepareSpec`
- * → `createDurableRun`)产出的是一条 **run 行**(`RunRecord`,uuidv7 taskId),它**永远不会**是一条
- * `BackgroundAgentRecord`(那是 core 在 run 内部为子 agent 铸的行,server 没有直接铸它的口)。两者的
- * status 词表也不同(run:`running|suspended|needs_review|completed|failed|blocked`;bg agent:
- * `running|parked|completed|failed|killed`),`toA2ATaskState` 的穷举 switch 对 `RunRecord` 根本不可调用。
- * ⇒ 采「run 句柄域」(施工任务书明列的两案之一):`Task.id` = run 的 `taskId`,`contextId` = `sessionId`,
- * 反枚举门 = 与 `GET /v1/runs/:id` **同一条** owner 判据,态投影 = {@link a2aStateForRun}
- * (与 core `toA2ATaskState` 同纪律:词表增删两向都是编译期红——载体是
- * {@link A2A_STATE_BY_RUN_STATUS} 的 `satisfies`;park 与否另问属主谓词 `isParkedRunStatus`,
- * 本文件零 park 词表。运行期只发九词闭集)。
- * 这不是「绕过 core 原语」:那几只原语的定义域里没有我们要投影的这条行,硬套才是撒谎。
- *
- * ## 🔎 方言对账(codex 轮4 R4-1/R4-2 的驳,证据在码上)
- * 有复审主张我们该改用 `SendMessage`/`GetTask` + `supportedInterfaces` 的 proto 派生绑定。**驳**:本
- * 半场的第一顺位互操作对象是 core 自己那条 A2A **客户端**腿(设计稿 §0 的立项理由就是「client 腿全链
- * 真实现、server 全树零接线」)。装树 `@sema-agent/core/dist/core/a2a.js` 亲读:它发 `message/send`
- * (:513)/`tasks/get`(:483)、置头 `a2a-version: 1.0`(:149,`A2A_PROTOCOL_VERSION = "1.0"` :28)、
- * 先拉 `/.well-known/agent-card.json`(:27)、按**顶层 `url` + `preferredTransport`** 协商(:244)。
- * 照那条建议改,恰好会与我们唯一能亲验的消费方互不相通。这条对账已钉成机器判据(见
- * `a2a-serve-rpc.test.ts` 的「轮4」格):装树换方言时当场红,那才是重新裁定的时刻。
- * 🟠 其中**一条**留作 v2 候选(不在 v1 射程,设计稿 §3 尾已把它列进「明确不做」):卡上不声明任何
- * security scheme ⇒ 发现面不告诉调用方「调用需要凭据」。R-11 裁的是「不假装 OAuth」,而一个如实的
- * `http: bearer` 声明并不构成假装 —— 值得在 v2 连同 card 字段面一起重议。
- *
- * ## 🟡 已知残余(登记,不假装没有)
- * ① `/v1/a2a` 是 `isBillableSubmitPath` 的**静态**成员(纯 url 谓词)。于是在「没有任何 service token
- *   且未开 `ALLOW_UNAUTHED_WRITES`」这一形的部署上,`POST /v1/a2a` 拿到的是 503
- *   `auth.service_token_required` 而不是本模块的 404 —— 即便旋钮是 OFF。那是一条很弱的指纹(「这个
- *   build 认得 /v1/a2a」),射程仅限一台**拒收一切写**的机器,且 server 的版本/能力面本就可发现。
- *   不修的理由:那道门必须在**解析请求体之前**判(未鉴权的写不该先被解析),而它只有 url 可看。
- *   (drain / model-roster 两道**可用性**门已按方法下沉,见 `submitUnavailable` —— 它们不在这条残余里。)
- * ② `prepareSpec` 的**显式字段校验**分支(objective 空、sessionId 超长…)仍以裸 HTTP 4xx 应答,不进
- *   JSON-RPC 信封。射程有界且不泄漏:那些文案只谈**本腿自己铸**的字段、不含任何内部词表(会泄漏的
- *   typed 分支已经走 `onTypedFailure` 钩子改口,见 `rpcErrorFromTypedFailure`)。彻底收口要把那一串
- *   `sendError` 全改成 typed 返回值 —— 那是共享腿的形变更,留给后续批。
- *
- * 分层:本模块只值 import `http/` 的叶子(send / principal-gate / idempotency / route-ctx)、
- * `routes/runs.js` 的**提交腿导出**(单向边,runs.ts 不反向引用本模块 ⇒ 不成环)与 src 下的普通模块
- * —— 绝不值 import server.ts(见 route-ctx.ts 头注的分层硬约束)。
- */
 import { createHash } from "node:crypto";
 import { A2A_TASK_STATES } from "@sema-agent/core";
 import { isParkedRunStatus } from "../../plugins/store-contracts.js";
@@ -78,12 +6,8 @@ import { scopedIdempotencyKey } from "../idempotency.js";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal } from "../principal-gate.js";
 import { createDurableRun } from "./runs.js";
-/** 本实现说的 A2A 协议版本 —— 卡的 `protocolVersion` 与每条 RPC 响应的 `a2a-version` 头同源(单点)。 */
 export const A2A_PROTOCOL_VERSION = "1.0";
-/** 版本头名。**读**请求侧的它只是诊断材料(开集容忍:认识与否都照常答),**写**响应侧的它是我们自报
- *  家门 —— 设计稿 §4-1 版本槽。 */
 export const A2A_VERSION_HEADER = "a2a-version";
-/** 配置 → 卡(纯投影,零 I/O、零存量读)。`build*`:返回纯数据。 */
 export function buildAgentCard(serve) {
     return {
         name: serve.name,
@@ -91,20 +15,9 @@ export function buildAgentCard(serve) {
         protocolVersion: A2A_PROTOCOL_VERSION,
         url: serve.url,
         preferredTransport: "JSONRPC",
-        // 🔒 逐键**白名单**构造(fleet 的 stripT 同纪律):配置条目新增字段时默认**不**上卡,要上必须在这里
-        //    显式写一行 —— 反过来(spread 配置对象再删几个键)会让下一个加到 A2aServeSkill 上的内部字段
-        //    静默出现在公网文档上,那正是本行要防的事故形。
         skills: serve.skills.map((s) => ({ id: s.id, name: s.name ?? s.id, ...(s.description !== undefined ? { description: s.description } : {}) })),
     };
 }
-/**
- * 域入口①:公开发现面。**位置即契约** —— 必须挂在 `server.ts` 的全局 service-credential 门**之前**
- * (R-11「公网匿名可发现」;挂在门后等于要凭据才能发现,协商第一步就断)。
- *
- * 命名:本模块有**两个**域入口(卡在凭据门外、RPC 在门内),而 `route-shape-roster` 层E 的判据是
- * 「域名词干 ⊆ 某个 capability 位名」。两个名字都取成 `capabilities.a2aServe` 的**子串**
- * (`a2aServe` / `a2a`),于是两条都被那道门如实认出来 —— 而不是去放宽那道门的判据。
- */
 export async function handleA2aServe(req, res, url, ctx) {
     const miss = { fell: false };
     await handleA2aServeBody(req, res, url, ctx, miss);
@@ -114,8 +27,6 @@ async function handleA2aServeBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     if (req.method === "GET" && url === "/.well-known/agent-card.json") {
         const serve = deps.config.a2aServe;
-        // OFF ⇒ 404,与「本部署没有这条路由」逐字节同形:对外不存在就是不存在,不发一个「功能已禁用」的
-        // 具名错误(那本身就是一条「这里跑的是 sema-server 且它认得 A2A」的指纹)。
         if (!serve) {
             sendError(res, 404, "not_found.route", "not found");
             return;
@@ -126,52 +37,16 @@ async function handleA2aServeBody(req, res, url, ctx, miss) {
     }
     miss.fell = true;
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// 件2:JSON-RPC 端点(服务凭据门**内**)
-// ─────────────────────────────────────────────────────────────────────────────
-/** JSON-RPC 2.0 传输层错误码(协议保留段)。 */
 const JSONRPC_PARSE_ERROR = -32700;
 const JSONRPC_INVALID_REQUEST = -32600;
 const JSONRPC_METHOD_NOT_FOUND = -32601;
 const JSONRPC_INVALID_PARAMS = -32602;
 const JSONRPC_INTERNAL_ERROR = -32603;
-/** A2A 自有错误码(spec 的 -32001..-32006 段)。只用我们真会发的三只。 */
 const A2A_TASK_NOT_FOUND = -32001;
 const A2A_UNSUPPORTED_OPERATION = -32004;
 const A2A_CONTENT_TYPE_NOT_SUPPORTED = -32005;
-/**
- * 🔴 **反枚举不变式(A-041)在本模块的执行点**:`tasks/get` 的「这条 task 不存在」与「这条 task 不是
- * 你的」必须**逐字节**同形 —— 同一个 code、同一条 message、同一个(缺席的)data。两臂共用**这一个**
- * 常量就是那条不变式的机制支撑:任何一臂想说得更具体,都得先改这里,而改这里会被
- * `a2a-serve-rpc.test.ts` 的逐字节比对当场钉住。
- *
- * (同族先例:`route-ctx.ts` 的 `RUN_NOT_FOUND_MESSAGE` —— #262 抓到的正是两臂**文案长度**不同就足以
- * 枚举他人 run id 的存在性。JSON-RPC 侧一模一样,只是载体从 HTTP body 换成了 error 对象。)
- */
 export const A2A_TASK_NOT_FOUND_MESSAGE = "task not found";
-/** 无 durable run store 时两个方法的**同一条**具名回答(不是静默降级成一次同步跑)。 */
 const A2A_NO_RUN_STORE_MESSAGE = "this deployment has no durable run store, so A2A tasks cannot be created or polled (set DB_BACKEND=mysql|pg|local)";
-/**
- * `RunRecord["status"]` → A2A 任务态的**逐词处置表**。
- *
- * `satisfies Record<RunRecord["status"], …>` 是这张表的执法点(fleet 的 `SCOPED_TASK_KEY_DISPOSITION`
- * 同纪律):core 给 `TaskStatus` **增**一个成员 ⇒ 表不完整、tsc 红,加成员的人被迫当场回答「这个新态
- * 投成哪个协议词」;**删**一个成员 ⇒ 多余键同样红。写成表而不是 `switch` 的第二个理由见下面 `null` 那两行。
- *
- * 逐词理由:
- *  · `running` → `working`。
- *  · `completed` → `completed`。
- *  · `failed` → `failed`(`errorCode === "cancelled"` 的分叉在读点:那是**有人明确要求**的停止,写
- *    `POST /v1/runs/:id/cancel` 时落的字面量。与 core 对 `killed` 行按 `stoppedBy` 分叉的判词同源 ——
- *    `canceled` 断言的是一个意图,没人表达过就不许替他断言)。
- *  · `blocked` → `failed`。它是终局的「跑不下去了」;协议的 `rejected` 说的是**准入时**拒收
- *    (我们准入拒收会在 RPC 层直接报错、根本不建行),投它会撒谎。
- *  · **park 族两词 → `null`**,读作「这个词的归属不归本表裁,归 `store-contracts.ts` 的
- *    `isParkedRunStatus`(词表属主:穷举 switch + `never` 臂)」。本文件**不留第二张 park 词表** ——
- *    那正是 `source-hygiene-gate` 点名的病:手抄形绕开属主的编译期执法,core 新增一个 park 类成员时
- *    手抄处会静默判「非 park」。运行期这两个值到不了(读点先问属主);到得了就说明两边不一致,那时
- *    诚实答 `unknown` 好过在这里再猜一次。
- */
 const A2A_STATE_BY_RUN_STATUS = {
     running: "working",
     completed: "completed",
@@ -180,47 +55,26 @@ const A2A_STATE_BY_RUN_STATUS = {
     suspended: null,
     needs_review: null,
 };
-/**
- * run 行 → A2A 任务态。词表槽(设计稿 §4-2):我们是铸点,只发 core `A2A_TASK_STATES` 九词闭集。
- *
- * 判据分工:park 与否问**属主谓词**;其余按 {@link A2A_STATE_BY_RUN_STATUS} 投影(那张表的
- * `satisfies` 是词表增删两向的编译期执行点)。
- *
- * park → `input-required` 的语义:协议的「等调用方给点什么」在本引擎被**收窄**成「等一个审批决议」,
- * 而那个决议走的是持久审批口、不是一条回信 —— 与 core 对自己 `parked` 行的裁词同源。A2A 调用方因此
- * **不能**靠再发一条 message 解开它(附录 C.3 的表里成文写着这句)。
- */
 export function a2aStateForRun(run, stale) {
-    // stale 折叠与 `GET /v1/runs/:id` 同源:那条读面把「running 但心跳超期」直接答成 failed;两个读面
-    // 对同一行给出不同的终局判断会是最难查的一类不一致。
     if (stale)
         return "failed";
     if (isParkedRunStatus(run.status))
-        return "input-required"; // 判据属主单源,本文件零 park 词表
-    // 表外的词 = 滚动升级里更新副本写入的新状态(运行期真会发生:SQL 文本列被裸 cast 成联合)。
-    // `unknown` 是九词闭集里**为此而设**的那一个,也是唯一诚实的答案:本进程读不懂这行就说读不懂,
-    // 而不是猜一个终局态让对端停止轮询。
+        return "input-required";
     const mapped = A2A_STATE_BY_RUN_STATUS[run.status];
     if (mapped === null || mapped === undefined)
         return "unknown";
     return mapped === "failed" && run.errorCode === "cancelled" ? "canceled" : mapped;
 }
-/** 一条我们铸的 agent 消息(`status.message`)。 */
 function agentMessage(taskId, contextId, text) {
     return {
         kind: "message",
         role: "agent",
-        // messageId 由**我们**铸(协议要求每条消息有 id);由 taskId 派生 ⇒ 同一条 task 的重复读稳定同值。
         messageId: `${taskId}:status`,
         parts: [{ kind: "text", text }],
         taskId,
         contextId,
     };
 }
-/** 状态文本。终局 completed 发最终文本(与 `GET /v1/runs/:id` 发的 `result` 是**同一份数据**,同样
- *  不裁剪 —— 裁剪会造出一个「其余部分在哪里」的问题,而这条协议面没有第二个读口可指);失败发错误
- *  文本;park 态发一句**不带任何工具/门细节**的通用说明(对端是外部 agent,不该从状态行里读出我们
- *  内部拦了什么工具)。 */
 function statusTextForRun(run, state) {
     if (state === "input-required")
         return "this task is suspended awaiting an approval decision on the serving deployment; it resumes once that decision is made";
@@ -232,8 +86,6 @@ function statusTextForRun(run, state) {
         return run.result.errorMessage;
     return undefined;
 }
-/** run 行 → A2A Task。**最小披露**:只发 id / contextId / 态 / 一段状态文本 —— stats、cost、model、
- *  source、jobId、owner 一律不上(对端要的是「做完没有、结果是什么」,其余都是内部账)。 */
 function taskFromRun(run, stale) {
     const state = a2aStateForRun(run, stale);
     const text = statusTextForRun(run, state);
@@ -248,7 +100,6 @@ function taskFromRun(run, stale) {
         },
     };
 }
-/** 具名 RPC 错误 —— 处理器抛它,分派器翻成 JSON-RPC error 体。 */
 class RpcError extends Error {
     code;
     constructor(code, message) {
@@ -256,7 +107,6 @@ class RpcError extends Error {
         this.code = code;
     }
 }
-// ── 请求形校验(小纯函数,便于逐条钉) ─────────────────────────────────────────
 function asRecord(v, what) {
     if (typeof v !== "object" || v === null || Array.isArray(v))
         throw new RpcError(JSONRPC_INVALID_PARAMS, `${what} must be an object`);
@@ -269,17 +119,10 @@ function asNonEmptyString(v, what, max) {
         throw new RpcError(JSONRPC_INVALID_PARAMS, `${what} must be at most ${max} characters`);
     return v;
 }
-/** 上限:与 `prepareSpec` 的 `sessionId` 列宽同源(64)—— 越界在这里具名拒,不留给 INSERT 去截断。 */
 const MAX_CONTEXT_ID_CHARS = 64;
-/** `messageId` 只当幂等键用,长度按既有 Idempotency-Key 面同量级收窄。 */
 const MAX_MESSAGE_ID_CHARS = 200;
-/** task id 读面上限(uuidv7 远短于此;这一格防的是无界字符串进 store 查询)。 */
 const MAX_TASK_ID_CHARS = 128;
-/** skill id 上限与 config 侧声明面同源。 */
 const MAX_SKILL_ID_CHARS = 128;
-/** `message.parts` → objective。**只收 text part,其余具名拒绝**(v1 定界):静默丢一个 file part
- *  等于把「我没看你给的文件」渲染成「我看过了」。A2A 的 `kind` 与旧稿的 `type` 两种拼法都认(读侧
- *  开集容忍;写侧我们只铸 `kind`)。 */
 function objectiveFromParts(parts) {
     if (!Array.isArray(parts) || parts.length === 0)
         throw new RpcError(JSONRPC_INVALID_PARAMS, "params.message.parts must be a non-empty array");
@@ -300,13 +143,7 @@ function objectiveFromParts(parts) {
         throw new RpcError(JSONRPC_INVALID_PARAMS, "params.message carries no non-empty text part — there is nothing to work on");
     return objective;
 }
-/** 我们在 `message.metadata` 上认的**唯一**扩展键:调用方用它点名一条**卡上公告过**的 skill。
- *  A2A spec 本身没有 skill 选择字段(卡只做广告),`metadata` 是它的开放扩展点 —— 命名空间前缀防撞。
- *  缺席 ⇒ 走部署缺省场景(既有行为);在场但不认识 ⇒ **具名拒绝**:路由输入静默回落到缺省场景 =
- *  请求以为自己选了 A、实际跑了 B,是最坏的一种「成功」。 */
 const SKILL_METADATA_KEY = "sema.skillId";
-/** `message.metadata["sema.skillId"]` → 那条**已声明**的 skill(缺席 ⇒ undefined = 走部署缺省场景)。
- *  ⚠️ 错误文案里**不回显** scenario —— 卡公开的是 skill id,内部场景键不是公开面。 */
 function skillFromMetadata(metadata, serve) {
     if (metadata === undefined || metadata === null)
         return undefined;
@@ -320,16 +157,6 @@ function skillFromMetadata(metadata, serve) {
         throw new RpcError(JSONRPC_INVALID_PARAMS, `unknown skill id ${JSON.stringify(id)} — the skills this agent serves are the ones listed on its agent card`);
     return skill;
 }
-/**
- * typed 提交拒绝(`HttpError`)→ JSON-RPC 错误。**只带我们自己的话**:原 `message` 与 `extra` 一律不上线。
- *
- * 🔴 codex 轮2 R2-4:那些 `extra` 里装的是给壳看的指路材料 —— `scenario_unknown` 的 extra 是**本部署的
- * 全部场景名**,`scenario_not_allowed` 的是这位 principal 的场景白名单。发给一个**外部 peer** 就是内部
- * 词表泄漏,而 skill 声明制存在的全部理由正是不把场景名给公网(设计稿 §3.1)。这里改口成:只说**公开的**
- * skill id 出了什么问题,真因(哪个场景不存在)只进服务端日志。
- *
- * 4xx = 调用方的参数问题 ⇒ -32602;其余(5xx/意外)⇒ -32603,同样不带内部细节。
- */
 function rpcErrorFromTypedFailure(err, skillId) {
     const where = skillId !== undefined ? `skill ${JSON.stringify(skillId)}` : "this request";
     if (err.status >= 400 && err.status < 500) {
@@ -337,31 +164,13 @@ function rpcErrorFromTypedFailure(err, skillId) {
     }
     return new RpcError(JSONRPC_INTERNAL_ERROR, "internal error");
 }
-/**
- * **可用性**两门,按**方法**判(不是按 url)。
- *
- * `handle()` 里那两道 503(drain / model-roster-pending)挂在 `isBillableSubmitPath` 上,而那是一张**纯
- * url** 谓词表 —— 对 `/v1/a2a` 一刀切的代价是 `tasks/get` 这条纯读也一起 503。单副本部署(或卡上公告的
- * 就是这一台)于是恰好在重启/依赖降级的窗口里取不回已完成的结果,而那正是外部 peer 最需要读的时刻。
- * ⇒ `handle()` 对本 url **跳过**这两道(见 `isMethodDispatchedSubmitPath`),改由本函数在 `message/send`
- * 里施加。**服务凭据门那一道不动**:它判的是「这台机没有任何 service token 时能不能收写」,与方法无关,
- * 而把它挪进方法层会让一次未鉴权的提交先被解析、再被拒 —— 门必须尽早。
- * 文案与 `handle()` 的两道逐字同源(消费端按 `error:"draining"` 字面判型,那是冻结的 wire 契约)。
- * 🔴 **同源不止文案,还包括体上的 additive 键**(A-054.9,2026-08-19 合并重扫 confirmed):#291 给
- * draining 503 体加 `reason` 时只加在 `handle()` 那道门上,本函数一个字没带 —— 而 wire 契约附录 A 的
- * 序言明写「**码是判别语义**,同一语义的多个站点共用同一个码」(按码编排、跨站点、无路径辖域),
- * `draining` 行又逐字承诺「7.35.0+:体上可带 additive 键 `reason`」,C.5 还让 a2a 消费端就地读 503 体。
- * agent card 只公告 `/v1/a2a` 一个 url ⇒ 外部 peer 在这条腿上读不到因由就是真的读不到。此前那句
- * 「文案逐字同源」不算说谎(漂的是键不是文案),但它正是让人以为两道同源、从而漏补的诱因 —— 所以本注
- * 从此把「同源」的范围写死到体级。新增站点照抄这一条:同码 ⇒ 同键集。
- */
 function submitUnavailable(res, ctx) {
     const { deps } = ctx;
     if (deps.drainState?.draining) {
         res.setHeader("retry-after", "15");
         sendError(res, 503, "draining", "draining", {
             message: "this instance is draining for shutdown/upgrade — retry against the replacement instance",
-            ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}), // 未声明 ⇒ 键缺席(additive 纪律)
+            ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}),
         });
         return true;
     }
@@ -372,8 +181,6 @@ function submitUnavailable(res, ctx) {
     }
     return false;
 }
-/** `configuration.blocking` 的读取。spec 缺省 false;非布尔值**具名拒**(一个 `"true"` 字符串被当成
- *  真,会让调用方以为自己在同步等)。 */
 function readBlocking(params) {
     if (params.configuration === undefined)
         return false;
@@ -384,21 +191,9 @@ function readBlocking(params) {
         throw new RpcError(JSONRPC_INVALID_PARAMS, "params.configuration.blocking must be a boolean");
     return c.blocking;
 }
-/** 与 `GET /v1/runs/:id` 逐字同源的 stale 判据(running 但心跳超期 ⇒ 折成 failed)。 */
 function isStaleRun(run, runStaleSec) {
     return run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > runStaleSec * 1000;
 }
-/**
- * 有界等待一条 run 走出 `working`。`budgetMs<=0` ⇒ 只读一次(非 blocking 形)。
- * 轮询 durable 行而不是挂进程内事件:这条 run 可能由**另一个副本**驱动,durable 行才是跨副本的唯一真相。
- *
- * 🔴 codex 轮4 R4-3 随修的两条**止损**(同族病:一个不看外界的循环在依赖降级时最能放大伤害):
- *  ① **对端断了就停**:每拍检查 `res.writableEnded / socket.destroyed`。没有这一条,一个已经走掉的
- *    调用方仍能让我们对库读满整个窗(fleet 那条流的 ackIfAlive 是同一句判词)。
- *  ② **库读失败不再静默当 miss**:原先 `.catch(() => undefined)` 会把一次真故障读成「还没好」,于是
- *    在库正挂着的时候反而把读打满(把故障隐藏 + 放大)。改成**当拍停**并把已知的最后一手交回去 ——
- *    调用方拿到的是 `submitted`/上一拍的真状态,自己去轮询,而不是我们替他空转。
- */
 async function waitForRun(ctx, res, taskId, budgetMs) {
     const { deps } = ctx;
     const store = deps.runStore;
@@ -413,7 +208,7 @@ async function waitForRun(ctx, res, taskId, budgetMs) {
         }
         catch (e) {
             deps.logger?.warn?.("a2a_serve_wait_read_failed", { error: e?.message });
-            return last; // ② 读挂了就别再敲它
+            return last;
         }
         last = run ?? last;
         if (run && a2aStateForRun(run, isStaleRun(run, deps.config.runStaleSec)) !== "working")
@@ -422,7 +217,7 @@ async function waitForRun(ctx, res, taskId, budgetMs) {
         if (left <= 0)
             return run;
         if (res.writableEnded || res.socket?.destroyed)
-            return run; // ① 对端已走,别替他继续读库
+            return run;
         await new Promise((r) => {
             const t = setTimeout(r, Math.min(250, Math.max(1, left)));
             if (typeof t.unref === "function")
@@ -430,18 +225,6 @@ async function waitForRun(ctx, res, taskId, budgetMs) {
         });
     }
 }
-/**
- * `message/send` —— 翻译进**既有**任务提交链。
- *
- * 复用点(不另铸提交路径):`ctx.legs.prepareSpec(req, res, body)` 的读体/校验/建 spec 段 +
- * {@link createDurableRun}(`POST /v1/runs` 的建行+驱动段,本车从 runs.ts 提取成具名腿,两个调用方
- * 共用同一份实现)。本模块**没有**自己的 `createRun` / `runInBackground` 调用。
- *
- * blocking 语义:A2A `configuration.blocking` 缺省 false(spec)。true 时按 `A2A_SERVE_BLOCKING_WAIT_MS`
- * 有界等待 —— blocking 的意思是「尽力等」,不是「必须等到终局」:窗到期回 `working` 态 + id,调用方按
- * 协议转 `tasks/get` 轮询,这是**正常路径**不是降级。窗必须远小于 core 客户端腿的 10min 总预算:那是
- * **调用方**的钱包,而按住一条 inbound 请求 10 分钟花的是**我们**的连接池。
- */
 async function handleMessageSend({ req, res, ctx, params, serve }) {
     const { deps } = ctx;
     const { rateLimited, quotaExceeded } = ctx.helpers;
@@ -449,41 +232,15 @@ async function handleMessageSend({ req, res, ctx, params, serve }) {
     if (message.role !== "user")
         throw new RpcError(JSONRPC_INVALID_PARAMS, `params.message.role must be "user" (this is the inbound leg — an agent-role message has no meaning here)`);
     const objective = objectiveFromParts(message.parts);
-    // contextId = 我们的 sessionId(协议的「同一段对话」与本引擎的 session 是同一个概念)。缺席 ⇒ 提交链铸新的。
     const contextId = message.contextId === undefined ? undefined : asNonEmptyString(message.contextId, "params.message.contextId", MAX_CONTEXT_ID_CHARS);
-    // 🔴 codex 轮 H2a:`messageId` **必填**。协议本就把它列为 `Message` 的必填字段,而在这里它还兼着
-    // **幂等键** —— 收一条没有它的消息 = 悄悄把去重整个关掉(重发即第二条 run、第二笔账),那正是
-    // 「无声 fail-open」。缺席具名拒,不给「宽容」留口子。
     const messageId = asNonEmptyString(message.messageId, "params.message.messageId", MAX_MESSAGE_ID_CHARS);
     const skill = skillFromMetadata(message.metadata, serve);
     const skillId = skill?.id;
     const scenario = skill?.scenario;
-    // 🔴 codex 轮3 R3-1(验真后修):**请求形校验必须全部走完再动状态**。这一行原先在下面等待窗那里才求值 ——
-    // 于是一个 `blocking:"true"`(字符串)会拿到 -32602,而一条计费 run 已经建好并在跑:调用方既没有收据、
-    // 重试还会再开一条。「拒了却已经烧上钱」是最坏的组合,校验不该有先后之分。
     const blocking = readBlocking(params);
     if (!deps.runStore)
         throw new RpcError(A2A_UNSUPPORTED_OPERATION, A2A_NO_RUN_STORE_MESSAGE);
-    // 幂等两道(与 `POST /v1/runs` **同一对**机制,不新铸第三种):
-    //  ① in-memory:按身份加盐的 `Idempotency-Key` 缓存 —— 同副本内的并发/快速重试共享同一次产出。
-    //  ② durable:caller-minted `body.taskId` 重放,读的是 run **store** ⇒ 跨副本、跨重启都成立。
-    //     A2A 调用方不知道我们的 taskId 体例,所以由**我们**从 (身份, messageId) 派生一个 uuidv7 形的 id。
-    //     🔒 **按身份加盐**是承重的,不是装饰:不加盐时两位租户用同一个 messageId 会派生出同一个 taskId,
-    //     后到的那位撞上 `409 taskId already exists` —— 那是一个现成的跨租户存在性 oracle(猜 messageId
-    //     就能验证别人发过没有),与 A-041 直接冲突。加盐后各租户各得各的键,那条臂对 A2A 面不可达。
-    //
-    // 🔴 codex 轮2 R2-2(验真后修):键里**必须**含请求内容。只按 (身份, messageId) 取键时,一个复用了
-    // 旧 messageId 的**新**请求会被判成重试 —— 它**从未执行**,而调用方拿回一条与自己所问无关的旧结果
-    // (无凭据部署下两位调用方还共用同一个键空间,后果更糟)。判据改成:幂等键 = (身份, messageId,
-    // **这条消息的规范化内容**)。于是 ①真重试(逐字节相同)照旧只跑一次;②同 id 换内容 = 另一条任务,
-    // 真的会被执行。v1 **不**做 Stripe 式「同键异体 ⇒ 409 拒」——那需要一列持久指纹(= SQL 面,不在本车),
-    // 而它要防的伤害在此已经没有了:代价从「静默回放无关结果」降到「多一条本来就该跑的任务」。
     const idemScope = `${ctx.req.source ?? ""}\x1f${gatedPrincipal(req, deps.config) ?? ""}`;
-    //
-    // 🔴 codex 轮3 R3-3(验真后修):指纹只由**线上输入**构成 —— 取调用方给的 `skillId`,**不取**服务端
-    // 解析出的内部 `scenario`。后者是**可变的服务端路由**:滚动配置变更期两台副本可以把同一个已公告的
-    // skill 映射到不同场景 ⇒ 同一条线请求在两台上派生出不同 taskId ⇒ 一次 failover 重试开出第二条 run,
-    // 恰恰推翻我们对外承诺的「跨副本/跨重启只有一条」。幂等的自变量必须是调用方看得见的那些字节。
     const fingerprint = createHash("sha256")
         .update(messageId).update("\x1f")
         .update(objective).update("\x1f")
@@ -497,23 +254,8 @@ async function handleMessageSend({ req, res, ctx, params, serve }) {
         ...(contextId !== undefined ? { sessionId: contextId } : {}),
         ...(scenario !== undefined ? { scenario } : {}),
     };
-    // 🔴 codex 轮 H1:准入门。顺序与 `POST /v1/runs` 逐字同源 —— **重放先于 rate/quota**(一次重试不该
-    // 因为窗满改判 429、把一条已经建好的 run 的收据吞掉;那条口的「复审 C1」注写的就是这件事),
-    // 而一次**真新**的提交必须与原生提交面吃同一组限流与累计成本门。修前这条链上只有 lease/治理窗,
-    // 于是一个已鉴权的外部 peer 可以无视本部署配置的 `RATE_LIMIT_RPM` / `MAX_PRINCIPAL_COST_USD`。
-    // 🔴 codex 轮3 R3-2(验真后修):**durable 重放是 message/send 的第一个有状态动作**,排在 rate/quota
-    // 之前。只查进程内缓存不够 —— 丢响应后的重试、重启后的重试、LB failover 全都落到一台**缓存是空的**
-    // 副本上;那时先撞 429 的后果不是「稍后再试」,而是调用方**永远拿不到**一条已经在跑、已经在计费的
-    // task 的句柄。与「重放先于 rate/quota」是同一条判据,只是把它从进程内延伸到跨副本。
-    // owner 门与 `tasks/get` 同源(验证过的 principal;`owner === null` = 无主部署的行)。
     const replay = await deps.runStore.getRun(body.taskId).catch(() => undefined);
     if (replay && (replay.owner === null || replay.owner === gatedPrincipal(req, deps.config))) {
-        // 🔴 codex 轮4 R4-3(验真后修):重放**立即**作答,**不**进等待循环 —— 哪怕 `blocking:true`。
-        // 理由是位置决定的:这一段排在 rate/quota **之前**(R3-2 要求如此,否则重试拿不到已计费 task 的
-        // 句柄),于是任何在这里发生的等待都**不受任何准入门约束** —— 一场重试风暴能对同一条 task 叠出
-        // 任意多个各自每 250ms 读一次库的独立循环,而且恰好发生在依赖降级、库最脆弱的时候。
-        // 语义上也正确:重放的对象是一条**已经受理**的 task,协议给调用方的出路就是 `tasks/get` 轮询;
-        // `blocking` 是「这次**提交**尽力等」,不是「每次重试都再等一轮」。
         return taskFromRun(replay, isStaleRun(replay, deps.config.runStaleSec));
     }
     const cached = idemKey ? ctx.registry.idemCache.peek(idemKey) : undefined;
@@ -522,14 +264,10 @@ async function handleMessageSend({ req, res, ctx, params, serve }) {
         receipt = await cached;
     }
     else {
-        // 🔴 codex 轮2 R2-3(验真后修):**可用性**两门(drain / model-roster-pending)在这里、按**方法**判,
-        // 而不是在 `handle()` 里按 url 判 —— 见 `isMethodDispatchedSubmitPath` 的顶注:整条 `/v1/a2a` 按 url
-        // 一刀切会让 `tasks/get` 这条**纯读**在排空/roster 未落时一并 503,而单副本部署恰恰在重启窗里最需要
-        // 取回已完成的结果。写面照旧 503(一台正在下线的副本不许开新模型工作)。
         if (submitUnavailable(res, ctx))
             return undefined;
         if (rateLimited(req, res) || quotaExceeded(req, res))
-            return undefined; // 已应答 429
+            return undefined;
         let typed;
         const prepared = await ctx.legs.prepareSpec(req, res, body, (e) => {
             typed = e;
@@ -537,14 +275,13 @@ async function handleMessageSend({ req, res, ctx, params, serve }) {
         if (typed)
             throw rpcErrorFromTypedFailure(typed, skillId);
         if (!prepared)
-            return undefined; // prepareSpec 的显式字段校验分支已自行应答(见下方 🟡 残余注)
+            return undefined;
         receipt = await createDurableRun(req, res, ctx, prepared, idemKey);
     }
     if (!receipt)
-        return undefined; // 提交腿已应答
+        return undefined;
     const receiptBody = receipt.body;
     if (receipt.status !== 202 || typeof receiptBody.taskId !== "string" || typeof receiptBody.sessionId !== "string") {
-        // 既有提交链的非 202 收据(会话占用 409 等)。翻成具名 RPC 错误,**不**假装建成了一条 task。
         throw new RpcError(JSONRPC_INVALID_PARAMS, `the serving deployment did not accept this submission (it answered ${receipt.status}); a session already running a turn must finish or be cancelled before the next message on the same contextId`);
     }
     const taskId = receiptBody.taskId;
@@ -552,7 +289,6 @@ async function handleMessageSend({ req, res, ctx, params, serve }) {
     const run = await waitForRun(ctx, res, taskId, blocking ? serve.blockingWaitMs : 0);
     if (run)
         return taskFromRun(run, isStaleRun(run, deps.config.runStaleSec));
-    // 行刚建完还没读回来(或读失败):照 202 收据答 `submitted` —— 协议里正是「已受理、尚未开始」那个词。
     return {
         kind: "task",
         id: taskId,
@@ -560,19 +296,6 @@ async function handleMessageSend({ req, res, ctx, params, serve }) {
         status: { state: "submitted", timestamp: new Date().toISOString() },
     };
 }
-/**
- * (身份, messageId) → 一个 **uuidv7 形**的确定性 taskId,喂给既有的 caller-minted `body.taskId`
- * durable 幂等通道(`createDurableRun` 里那段读 run store 的重放)。
- *
- * 为什么派生而不是直接用 messageId:那条通道的形门是 `isUuidV7`(server 自己铸的字母表,防调用方注入
- * 任意 PK 形),而 A2A 的 `messageId` 是任意字符串。派生同时解决三件事 —— 形合法、**跨副本/跨重启**
- * 生效(读的是 store,不是进程内缓存)、且**按身份加盐**(见调用点的 🔒 注:不加盐就是一个跨租户
- * 存在性 oracle)。
- *
- * 摘要 → uuid 的位改写:第 7 字节高半字节写 `7`(version),第 9 字节高两位写 `10`(RFC4122 variant),
- * 与 `UUIDV7_RE` 的两处约束一一对应。**不含时间戳**(v7 通常前 48 位是毫秒时钟)——本 id 的用途是
- * 「同一条消息恒定映射到同一行」,时间序会破坏这一点;形门只校形,不校时钟。
- */
 function durableIdempotencyTaskId(scope, messageId) {
     const digest = createHash("sha256").update(scope).update("\x1f").update(messageId).digest();
     const b = Buffer.from(digest.subarray(0, 16));
@@ -581,14 +304,6 @@ function durableIdempotencyTaskId(scope, messageId) {
     const hex = b.toString("hex");
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
-/**
- * `tasks/get` —— 读回一条 task。
- *
- * 🔴 反枚举:**不存在**与**不属于你**走同一条出路({@link A2A_TASK_NOT_FOUND_MESSAGE},同 code 同文,
- * 逐字节相同)。这是 A-041 不变式在 JSON-RPC 侧的执行点 —— 一个外部 peer 不该能靠错误文案的差别枚举
- * 本部署里别人的 task id。principal 门在**查库之前**求值(与 `GET /v1/runs/:id` 同序),免得 401 与
- * not-found 的先后本身成为存在性 oracle;那道门在分派器入口(见本文件的域入口②)。
- */
 async function handleTasksGet({ req, ctx, params }) {
     const { deps } = ctx;
     const id = asNonEmptyString(params.id, "params.id", MAX_TASK_ID_CHARS);
@@ -597,30 +312,14 @@ async function handleTasksGet({ req, ctx, params }) {
     const run = await deps.runStore.getRun(id);
     if (!run)
         throw new RpcError(A2A_TASK_NOT_FOUND, A2A_TASK_NOT_FOUND_MESSAGE);
-    // owner 判据与 `runOwnerOk` 同源:比对**验证过的** principal(gatedPrincipal),绝不比 principal 头
-    // (直连门上那是可伪造的 —— 伪一个头就能读别人的 task)。`owner === null` = 无主部署的行,任何已过
-    // 服务凭据门的调用方可读(与那条 HTTP 读面逐字同判)。
     if (run.owner !== null && gatedPrincipal(req, deps.config) !== run.owner)
         throw new RpcError(A2A_TASK_NOT_FOUND, A2A_TASK_NOT_FOUND_MESSAGE);
     return taskFromRun(run, isStaleRun(run, deps.config.runStaleSec));
 }
-/** 演化槽 §4-4 —— **方法表**。新方法 = 加一行;表外的一切恒 -32601(协议内置的能力协商)。 */
 const A2A_METHODS = {
     "message/send": handleMessageSend,
     "tasks/get": handleTasksGet,
 };
-/**
- * 域入口②:JSON-RPC 端点。**位置即契约** —— 挂在全局 service-credential 门**之后**(R-11「持服务凭据
- * 才可调」),且在 drain / model-roster-pending 两道 503 门之后(`/v1/a2a` 进 `isBillableSubmitPath`:
- * `message/send` 会烧模型)。
- *
- * ⚠️ 代价成文:端点是**单 URL** 的(卡上只能公告一个 `url`),所以排空期 `tasks/get` 也一并 503。
- * 方向取「宁紧」—— 让一台正在下线的副本开新模型工作,正是那几道门存在的全部理由;而读面的补偿是
- * 现成的:行是 durable 的,调用方按 A2A 的传输层重试语义换一台副本读同一条行即可。
- *
- * 命名(`handleA2a`,与 `handleA2aServe` 同族):见域入口①的命名注 —— 两个名字都取成
- * `capabilities.a2aServe` 的子串,好让 `route-shape-roster` 层E 如实认出它们。
- */
 export async function handleA2a(req, res, url, ctx) {
     const miss = { fell: false };
     await handleA2aRpcBody(req, res, url, ctx, miss);
@@ -634,14 +333,11 @@ async function handleA2aRpcBody(req, res, url, ctx, miss) {
     }
     const serve = deps.config.a2aServe;
     if (!serve) {
-        // OFF ⇒ 与卡同形的 404(整条路由对外不存在),不是「功能已禁用」的具名错误。
         sendError(res, 404, "not_found.route", "not found");
         return;
     }
-    // 版本槽:**读**请求头只为诊断,认识与否都照常答;响应恒带自己的版本(开集容忍)。
     const requestedVersion = req.headers[A2A_VERSION_HEADER];
     res.setHeader(A2A_VERSION_HEADER, A2A_PROTOCOL_VERSION);
-    // principal 门在**任何查库之前**(与 runs 面同序:401 与 not-found 的先后不得成为存在性 oracle)。
     if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
         deps.metrics?.inc("a2a_serve_rejected_total", { reason: "principal_required" });
         sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
@@ -669,8 +365,6 @@ async function handleA2aRpcBody(req, res, url, ctx, miss) {
         return;
     }
     const method = rpc.method;
-    // 方法槽:表里没有 ⇒ 恒 -32601。这是协议**自带**的能力协商 —— 调用方据此降级(例如 message/stream
-    // 拿到 -32601 就转 message/send + tasks/get 轮询),所以我们不自铸一张能力表。
     const handler = A2A_METHODS[method];
     if (!handler) {
         deps.metrics?.inc("a2a_serve_rpc_total", { method: "(unknown)", outcome: "method_not_found" });
@@ -685,12 +379,10 @@ async function handleA2aRpcBody(req, res, url, ctx, miss) {
         sendRpc(res, { jsonrpc: "2.0", id, error: { code: JSONRPC_INVALID_PARAMS, message: "params must be an object (positional params are not supported)" } });
         return;
     }
-    // 版本头进日志(诊断维),**不**进任何判据;限长防超长头把日志行撑爆(车1 自审第四镜同族)。
     deps.logger?.debug?.("a2a_serve_rpc", { method, ...(typeof requestedVersion === "string" ? { requestedVersion: requestedVersion.slice(0, 32) } : {}) });
     try {
         const result = await handler({ req, res, ctx, params: params, serve });
         if (result === undefined) {
-            // 处理器已自行应答(提交链的 400/409 走 HTTP 形 —— 那是**传输层**的拒绝,不是一次成功的 RPC)。
             deps.metrics?.inc("a2a_serve_rpc_total", { method, outcome: "refused" });
             return;
         }
@@ -704,17 +396,13 @@ async function handleA2aRpcBody(req, res, url, ctx, miss) {
             sendRpc(res, { jsonrpc: "2.0", id, error: { code: e.code, message: e.message } });
             return;
         }
-        // 非具名异常:回一条**不含内部细节**的 -32603(栈/消息只进日志,不上线)。
         deps.logger?.error?.("a2a_serve_rpc_failed", { method, error: e?.message });
         deps.metrics?.inc("a2a_serve_rpc_total", { method, outcome: "internal_error" });
         sendRpc(res, { jsonrpc: "2.0", id, error: { code: JSONRPC_INTERNAL_ERROR, message: "internal error" } });
     }
 }
-/** JSON-RPC 响应体。**HTTP 恒 200**(错误在 body 的 `error` 成员里)—— 这是 JSON-RPC over HTTP 的常规:
- *  把 RPC 级错误映射成 4xx 会让传输层的重试逻辑把「参数写错了」当成「网络抖了」反复重发。 */
 function sendRpc(res, body) {
     sendJson(res, 200, body);
 }
-/** 九词闭集的对外可见锚(测试用它证明我们只发闭集词;也让「加一个自造词」在这里就被看见)。 */
 export const A2A_SERVE_TASK_STATES = A2A_TASK_STATES;
 //# sourceMappingURL=a2a-serve.js.map

package/dist/http/routes/admin-config-refresh.js

@@ -26,8 +26,6 @@ async function handleAdminConfigRefreshBody(req, res, url, ctx, miss) {
     const trigger = deps.configRefreshNow;
     const outcome = trigger ? await trigger() : "not-wired";
     if (outcome === "failed") {
-        // 🔴 codex R2-F3:定时拍吞掉异常是为了保住循环,但**按下刷新的那个人**必须知道这一拍真的失败了
-        // ——「中心超时」与「已刷新」在回执上不可分辨,正是这个口存在的反面。502:失败在依赖侧(配置源)。
         sendError(res, 502, "internal.config_refresh_failed", "the config refresh tick failed (source unreachable / unreadable / apply error) — the live config is unchanged; see the worker's sema_registry_refresh_failed log line for the cause");
         return;
     }
@@ -35,8 +33,6 @@ async function handleAdminConfigRefreshBody(req, res, url, ctx, miss) {
         sendError(res, 409, "config.refresh_unavailable", "this deployment has no config pipeline to refresh — set CONFIG_CENTER (remote control plane) or CONFIG_PROVIDER=local (config.d on disk); an env-only worker has nothing to pull");
         return;
     }
-    // 世代号取自世代账(与 /health 的 configTargetVersion/configAppliedVersion 同一份读数)。账缺席只发生在
-    // 「触发口在场但世代账没接线」的夹具形 —— 诚实报 0(不编一个看起来像真答案的数)。
     const gen = deps.configApplyState?.();
     sendJson(res, 200, { triggered: true, targetVersion: gen?.configTargetVersion ?? 0, appliedVersion: gen?.configAppliedVersion ?? 0 });
 }