@sema-agent/server 7.26.0 → 7.27.0

package/dist/http/server.js

@@ -46,6 +46,7 @@ import { handleSessions, createSessionsLocal } from "./routes/sessions.js";
 import { handleSessionSync, createSessionSyncLocal } from "./routes/session-sync.js";
 import { handleAttachments } from "./routes/attachments.js";
 import { handleFleet } from "./routes/fleet.js";
+import { handleA2aServe, handleA2a } from "./routes/a2a-serve.js";
 import { handleTraceUsage } from "./routes/trace-usage.js";
 import { handleWorkflows, handleWorkflowAgentSteer } from "./routes/workflows.js";
 import { handleNotifyWake, SESSION_WAKE_RE } from "./routes/notify-wake.js";
@@ -193,10 +194,12 @@ const ROUTE_DOMAINS = [
     handleTraceUsage,
     handleWorkflows,
     handleFleet,
+    handleA2aServe,
     handleCapabilities,
     handleSideQuery,
     handleTasks,
     handleRuns,
+    handleA2a,
     handleWorkflowAgentSteer,
     handleRunVerbs,
     handleLeader,
@@ -559,6 +562,12 @@ export function createHttpServer(rawDeps) {
         // design/158 A9 域模块:MF-Fleet 实时舰队流(routes/fleet.ts)。服务凭据门之前,按 principal 自门。
         if (await handleFleet(req, res, url, ctx))
             return;
+        // DESIGN-269 车2 件1 域模块:A2A agent card(routes/a2a-serve.ts)。
+        // ⚠️ 位置即契约:必须留在下面的全局 service-credential 门**之前** —— 卡是 R-11 裁定的「公网匿名
+        // 可发现」面(挂在门后=要凭据才能发现,A2A 协商第一步就断)。它**零存量披露**(纯 config 投影,
+        // 不读任何 task/run/session),所以匿名可读不构成披露;同域的 JSON-RPC 调用面在门**内**(下方)。
+        if (await handleA2aServe(req, res, url, ctx))
+            return;
         // Service-credential gate + SOURCE derivation: which system's token authenticated this request.
         // `source` is set ONLY here, from the credential — a caller cannot claim another system's identity.
         let source = null;
@@ -608,7 +617,7 @@ export function createHttpServer(rawDeps) {
         // resume-flavored assistant verbs + approvals responds — each starts a model turn) with 503 + Retry-After so
         // the shell/orchestrator retries against the replacement. Everything else stays open: reads (events/health/
         // trace), cancel, steer/respond on in-flight runs — those help the drained turns finish, they don't start new ones.
-        if (deps.drainState?.draining && req.method === "POST" && isBillableSubmitPath(url)) {
+        if (deps.drainState?.draining && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
             res.setHeader("retry-after", "15");
             // errorCode 补齐(2026-07-28 核查:cli 的 pre-stream drain 重试只能靠 `error` 文案字面判型——
             // SDK 的 code 臂恒 undefined 是死码;server 改文案=对端重试静默失效)。`error:"draining"` 字面
@@ -620,7 +629,7 @@ export function createHttpServer(rawDeps) {
         // 首次 effective pull 落 roster 之前 worker 只有占位模型——计费提交打占位=垃圾任务,503 让编排器/壳重试
         // 到 roster 落地(通常 <秒)。镜像 draining 姿势(同 billable 集合;读面/cancel/steer 全开);/health 带
         // ready:false 加性旗。env 模型在(操作员显式声明)或非 registry 部署=恒 ready,现有部署零影响。
-        if (deps.modelReady && !deps.modelReady() && req.method === "POST" && isBillableSubmitPath(url)) {
+        if (deps.modelReady && !deps.modelReady() && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
             res.setHeader("retry-after", "5");
             sendError(res, 503, "state.model_roster_pending", "model_roster_pending", { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" });
             return;
@@ -650,6 +659,13 @@ export function createHttpServer(rawDeps) {
         // design/158 A9 域模块:异步 run 面 + run 级动词(routes/runs.ts)。与 tasks 域共用 ctx.legs.prepareSpec。
         if (await handleRuns(req, res, url, ctx))
             return;
+        // DESIGN-269 车2 件2 域模块:A2A JSON-RPC 端点 POST /v1/a2a(routes/a2a-serve.ts)。
+        // ⚠️ 位置即契约:服务凭据门**之后**(R-11「持凭据才可调」),且在 drain / model-roster-pending 两道
+        // 503 之后 —— `/v1/a2a` 在 isBillableSubmitPath 里(message/send 会烧模型)。排在 handleRuns 之后是
+        // 因为它**复用** runs 域导出的提交腿(createDurableRun):次序上先让原生 run 面各就各位,再挂它的
+        // 协议门面,评审读这张链时的因果方向才与实现一致。
+        if (await handleA2a(req, res, url, ctx))
+            return;
         // design/158 A9 域模块:SVC-5 workflow agent steer(routes/workflows.ts,与上面的只读三路同域)。
         if (await handleWorkflowAgentSteer(req, res, url, ctx))
             return;
@@ -708,9 +724,14 @@ export function createHttpServer(rawDeps) {
     function runnerFor(spec) {
         return deps.runnerFor?.(spec) ?? deps.runner;
     }
-    /** Read + validate the body, authorize, and build the spec. Returns null if it already responded. */
-    async function prepareSpec(req, res) {
-        const body = (await readJson(req));
+    /** Read + validate the body, authorize, and build the spec. Returns null if it already responded.
+     *
+     *  `bodyIn` (DESIGN-269 车2):调用方**已经**把体解析出来了(A2A 的 JSON-RPC 腿 —— 那条请求的正文是
+     *  一次 `message/send`,腿把它翻成 `TaskRequestBody` 再进这条链)。缺席 ⇒ 照旧 `readJson(req)`。
+     *  分歧只在**入口**:往下的每一条校验/授权/resolveSpec 都是同一段代码,这正是本参数的全部意义
+     *  (给 A2A 抄一份校验 = 抄一份会漂的 400 语义)。 */
+    async function prepareSpec(req, res, bodyIn, onTypedFailure) {
+        const body = bodyIn ?? (await readJson(req));
         if (!body || typeof body.objective !== "string") {
             sendError(res, 400, "request.field_invalid", "missing 'objective' string");
             return null;
@@ -1312,6 +1333,15 @@ export function createHttpServer(rawDeps) {
         }
         catch (err) {
             if (err instanceof HttpError) {
+                // 🔴 codex 轮2 R2-4(验真后修):`onTypedFailure` 在场 ⇒ **不写响应**,把 typed 失败交回调用方。
+                // 为什么必须有这个口:本仓的 typed 拒绝会把结构化 `extra` 一起回显(`scenario_unknown` 的
+                // extra 是**本部署的全部场景名**)。那对壳/SDK 是指路材料,对一个 **A2A 外部 peer** 却是内部
+                // 词表泄漏 —— 而 DESIGN-269 车2 的整条 skill 声明制,存在的理由就是不把场景名给公网。
+                // 加钩子而不是重构响应形:三个既有调用方一字不传 ⇒ 行为逐字节不变(仍是这一行 sendError)。
+                if (onTypedFailure) {
+                    onTypedFailure(err);
+                    return null;
+                }
                 // Typed rejection: echo the stable `code` + any structured extras (e.g. the scenario
                 // allowlist) beside the human message — machine code on the wire, prose stays with the shell/web.
                 sendError(res, err.status, httpErrorCode(err.status, err.code), err.message, { ...(err.extra ?? {}) });
@@ -3115,12 +3145,37 @@ function checkpointRowRedeemableElsewhere(reason) {
  *  via resumeCheckpoint/store.decide → paid tokens). Keep this in sync when adding a billable POST route. */
 // [#104/#87-A3] exported for the declaration gate (test/billable-route-declaration.test.ts):每条路由
 // 标签必须显式申明 billable,与本谓词逐样本对账——「Keep this in sync」从注释请求变成机器断言。
+/**
+ * 「这条 url **是**计费提交面,但它到底提不提交由**请求体里的方法**决定」—— 目前只有 A2A 的
+ * JSON-RPC 端点(单 URL 承载 `message/send` 写 + `tasks/get` 读,因为 agent card 只能公告一个 `url`)。
+ *
+ * 用途:两道**可用性** 503(drain / model-roster-pending)按 url 一刀切会把 `tasks/get` 这条纯读一起
+ * 关掉,而单副本部署恰好在重启/依赖降级窗口里最需要取回已完成的结果(codex 轮2 R2-3,验真后修)。
+ * 本谓词让 `handle()` 对这条 url **跳过**那两道,改由域模块在 `message/send` 分支里施加同样的两道
+ * (`routes/a2a-serve.ts` 的 `submitUnavailable`,文案逐字同源)。
+ *
+ * 🔴 **只豁免那两道,不豁免安全轴**:`isBillableSubmitPath` 本身**不变**(它仍答 true),所以
+ *  ① 无 service token 的部署上那道 fail-closed 503 照旧罩着这条 url —— 它判的是「这台机能不能收写」,
+ *    与方法无关,而且门必须在解析请求体**之前**;
+ *  ② billable 申明门钉的仍是那只纯谓词(表里 `/v1/a2a` 依旧 billable=true)。
+ * 新成员进本表 = 承诺「该域在自己的方法分支里补齐那两道」,漏补就是一条静默旁路;所以本表只该有
+ * 「单 URL 多方法」这一种成员,加一条要连同它的域内补门一起过评审。
+ */
+export function isMethodDispatchedSubmitPath(url) {
+    return url === "/v1/a2a";
+}
 export function isBillableSubmitPath(url) {
     return (url === "/v1/side-query" || // [1469] one-shot brain call — runs the model, so it rides every billable-submit gate
         url === "/v1/tasks" ||
         url === "/v1/tasks/stream" ||
         url === "/v1/runs" ||
         url === "/v1/leader" ||
+        // DESIGN-269 车2:A2A JSON-RPC 端点。`message/send` 走的是与 /v1/runs **同一条**提交腿 ⇒ 它烧模型
+        // ⇒ 三道 503 门(drain / model-roster-pending / 无 service-token)必须对它生效,否则一台正在下线的
+        // 副本会照收外部 peer 的新任务(wake 当年漏在名单外犯的就是这一条)。
+        // ⚠️ 端点是**单 URL** 的(A2A 卡只公告一个 url),所以同一道门也会在排空期挡下 `tasks/get` 的读。
+        // 方向取「宁紧」:开新模型工作不可回滚,而读面有现成补偿(行是 durable 的,换一台副本读同一条)。
+        url === "/v1/a2a" ||
         ASSISTANT_RESUME_RE.test(url) || // resource_limit/preempt resume runs the model → BILLABLE (preempt is not)
         ASSISTANT_PLAN_REVIEW_RE.test(url) || // plan_review approve/edit resumes + runs the model → BILLABLE
         RUN_SUBAGENT_RESUME_RE.test(url) || // 对抗复查 B-2(HIGH):subagent revive (handle.resume) STARTS model work → BILLABLE
@@ -3189,7 +3244,7 @@ const ROUTE_LABEL_PATTERNS = [
     [/^\/v1\/images\/[^/]+$/, "/v1/images/:profile"],
     [/^\/v1\/approvals\/[^/]+\/decide$/, "/v1/approvals/:id/decide"],
     [/^\/v1\/approvals\/[^/]+\/exemptions(\/[^/]+)?$/, "/v1/approvals/:id/exemptions"],
-    [/^\/v1\/sessions\/[^/]+\/(wake|fork|init|notify|events|head|mcp|policy|settings)$/, "/v1/sessions/:id/$verb"],
+    [/^\/v1\/sessions\/[^/]+\/(wake|fork|init|notify|events|head|mcp|a2a|policy|settings)$/, "/v1/sessions/:id/$verb"],
     [/^\/v1\/sessions\/[^/]+\/sync\/(manifest|entries|plan)$/, "/v1/sessions/:id/sync/$verb"],
     [/^\/v1\/sessions\/[^/]+\/sync\/import(\/[^/]+\/entries)?$/, "/v1/sessions/:id/sync/import"],
     [/^\/v1\/sessions\/[^/]+\/sync\/blobs(\/[^/]+)?$/, "/v1/sessions/:id/sync/blobs"],
@@ -3248,6 +3303,10 @@ const ROUTE_LABEL_LITERALS = new Set([
     // #203 §2:撤销面两口(GET 列举 / DELETE 撤销)共用一个字面路径。同样写字面量而不是引 `RULES_PATH`
     // 常量,理由与上一条逐字相同(名册门与 billable 申明门都扫源码文本)。
     "/v1/rules",
+    // DESIGN-269 车2:server-as-peer 两口。卡是**公网匿名**面(唯一一条不吃服务凭据的 2xx 路由),
+    // 它的 QPS 与 duration 是判断「有没有人在扫我们」的第一手材料;RPC 口是外部 peer 的提交面。
+    // 两条都落进 `other` 桶 = 对外暴露面在 metrics 上不可分。同上,写**字面量**不引常量(两道门扫源码文本)。
+    "/.well-known/agent-card.json", "/v1/a2a",
 ]);
 /** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`).
  *  [#104] 字面量**先于**模式:此前模式先查,五条精确路由被形状桶吞掉(`/v1/approvals/stream`

package/dist/http/wire-types.d.ts

@@ -6,7 +6,7 @@
  * cut: ONLY TaskRequestBody (its field types are inline or core imports — no other server.ts-local satellites);
  * sibling request/response shapes can migrate here later on the same pattern.
  */
-import type { AgentDefinition, McpServerSpec } from "@sema-agent/core";
+import type { A2aServerSpec, AgentDefinition, McpServerSpec } from "@sema-agent/core";
 export interface TaskRequestBody {
     objective: string;
     sessionId?: string;
@@ -336,6 +336,17 @@ export interface TaskRequestBody {
      *  worker, not the exec env); IGNORED on multi-tenant deployments (can't make the shared worker run an arbitrary
      *  command). Validated + gated downstream; the center/config baseline wins on a name clash. */
     mcpServers?: McpServerSpec[];
+    /** [DESIGN-269 车1] Caller-supplied per-request A2A peers (remote agents this task may call), aligned to
+     *  core `A2aServerSpec`. 🔒 honored on a SINGLE-USER deployment that has neither locked the `a2a` key nor
+     *  had `a2a_peers` denied by its compliance posture (task-a2a.ts `a2aInjectionHonored`, the same three-veto
+     *  predicate `capabilities.a2aInjection` advertises) — the requester is the super-admin of their OWN worker,
+     *  on ANY execution lane (an A2A call is a plain outbound HTTPS request from the worker, so the lane where
+     *  tool calls run is irrelevant); IGNORED on multi-tenant (a tenant can't point the shared worker at an
+     *  agent of their choosing). A locked deployment refuses the whole request instead: 400 `config.locked_key`.
+     *  🔴 Every skill a peer advertises mounts `egress:true` + `effect:"write"` (core's ruling) — declaring a
+     *  peer is declaring an outbound WRITE channel, not a data source. Validated + gated downstream; the
+     *  center/config baseline wins on a name clash (the peer name IS the tool namespace). */
+    a2aPeers?: A2aServerSpec[];
     /** CC parity (Workflow super-set): per-task activation of the LLM-authored workflow engine (core `run_workflow`).
      *  `true` → `spec.selfOrchestration` (the engine mounts run_workflow), gated on the deployment's `selfOrchestrationEnabled`
      *  (else a harmless no-op) + core's `allowWorkflows` per-principal entitlement on multi-tenant (single-user honors

package/dist/main.js

@@ -614,6 +614,23 @@ async function main() {
     // 同源,恒有 durableEnabled === !!checkpointStore。
     if (durableEnabled)
         logger.info("durable_approval_enabled", { toolApprovalGate: config.approvalRequire.length });
+    // DESIGN-269 车2 件3 —— server-as-peer 上场的**感知链路**(#266 memory_persistence_capable_auto_declared
+    // 同族纪律:一条对外暴露面上了线,必须在 boot 日志里一眼可核)。这行是 `A2A_SERVE_ENABLED=true` **唯一**
+    // 的启动期回声:运维据此确认「这台机现在对外是一个 A2A agent、卡在这个路径上、公告的是这个 URL、
+    // 声明了几条 skill」。OFF(默认)⇒ 一个字都不发,零噪声。
+    // ⚠️ 半配置的诚实:开了旋钮却没有 durable run store 时,两个 RPC 方法会回具名 -32004 —— 那不是静默
+    // 降级,但它发生在**调用时**,而运维想在启动时就知道。所以这一行连带把 runStore 在不在场说出来。
+    if (config.a2aServe) {
+        logger.info("a2a_serve_enabled", {
+            card: "/.well-known/agent-card.json",
+            rpc: "/v1/a2a",
+            advertisedUrl: config.a2aServe.url,
+            skills: config.a2aServe.skills.length,
+            blockingWaitMs: config.a2aServe.blockingWaitMs,
+            // false = 卡照发(发现面不依赖 store),但 message/send 与 tasks/get 会回 -32004 UnsupportedOperation。
+            tasksUsable: runStore !== undefined,
+        });
+    }
     // 修4(三路复审 W3):the fs-write ask gate (resolveSpec, applyTaskSettings wiring below) mounts purely off the
     // host-semantics lane — DELIBERATELY decoupled from any approval face, so no assembly path is ever gateless:
     // with no live coordinator and no durable park, a permissionMode default/auto Write/Edit ask fail-closed

package/dist/observability/metrics.js

@@ -274,6 +274,17 @@ export function createMetrics() {
     // NOT need the fire-and-forget consolidation() to be awaited.
     m.counter("memory_consolidation_ops_total", "Memory consolidation store ops (1.62 B-full), by op (update/delete)");
     m.counter("mcp_server_unavailable_total", "MCP servers skipped fail-open at task start (1.68), unreachable/misconfigured");
+    // DESIGN-269 车1:A2A peer 在任务起手不可用(卡取不到 / skill 铸不出)—— 与 mcp 同族的 fail-open 计数。
+    m.counter("a2a_peer_unavailable_total", "A2A peers skipped at task start (DESIGN-269 client leg): card unreachable / spec unusable");
+    // DESIGN-269 车2:server-as-peer 的**对外**面。两只计数器刻意分开,它们回答两个不同的问题:
+    //  · `a2a_serve_rpc_total{method,outcome}` = 每个方法各被调了多少次、结果是什么(ok / refused /
+    //    error_<code> / method_not_found / internal_error)。`method_not_found` 那一格是**路线图信号**:
+    //    外部 peer 在真实拓扑里到底在要哪个还没做的方法(message/stream?tasks/cancel?),比我们猜准。
+    //  · `a2a_serve_rejected_total{reason}` = **没能进到方法层**的那些(凭据/形/版本以外的门),
+    //    它是「有人在扫我们 / 有人接错了」的第一手材料。混进上面那只会让「协议用错」与「跑失败了」
+    //    在同一条曲线上不可分。
+    m.counter("a2a_serve_rpc_total", "A2A server-as-peer JSON-RPC calls by method and outcome (DESIGN-269 车2)");
+    m.counter("a2a_serve_rejected_total", "A2A server-as-peer requests refused before reaching a method handler, by reason (DESIGN-269 车2)");
     // Remote execution env (design/48 E2B adapter): lifecycle outcomes by provider/result.
     m.counter("remote_env_connect_total", "E2B remote-env connect outcomes (provider/result)");
     m.counter("remote_env_destroy_total", "E2B remote-env destroy outcomes (provider/result)");

package/dist/run-local.js

@@ -59,7 +59,7 @@ import { applyCatalogToSource } from "./capabilities/center-prompts.js";
 import { validatePromptsDomain, CORE_ENGINE_VERSION } from "./prompts-domain-validate.js";
 import { loadConfig, logConfigDiagnostics, numEnv } from "./config.js";
 import { createConfigProvider } from "./config-provider.js";
-import { applyEffective, resolveMcpServers, mcpForScenario } from "./config-center/facade.js";
+import { applyEffective, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./config-center/facade.js";
 import { hostExecutionEnvFactory } from "./plugins/remote-env-host.js";
 import { makeLoadProjectMemory, makeProbeInstructionSources } from "./project-memory.js";
 import { loadSkills } from "./capabilities/skills.js";
@@ -339,6 +339,14 @@ export async function runLocal(argv, deps = {}) {
             // covers models/roles/gates/teams) so run-local matches the server path (main.ts:446). Restart-to-apply.
             if (effective?.mcp)
                 config.mcpServers = resolveMcpServers(effective.mcp, logger);
+            // DESIGN-269 车1 件1:A2A peers, same line as MCP — applied HERE so run-local matches the server path
+            // (boot/config-center.ts). Restart-to-apply.
+            // ⚠️ 如实记(codex 对抗复审 finding 4,验真后采纳为**文档更正**):今天只有**远端 center** 的
+            // `/effective` 里带 `a2a` 域时这一行才写得进值。**本地 config.d 车道还接不上** —— registry-core
+            // 锁定版的可移植域表里没有 a2a,`config-provider.ts` 的 `mapToServiceEffective` 闭式投影也就没有这
+            // 一域可投。补齐属于 registry-core(上游件),不在本车射程;在那之前别在文档里承诺 config.d/a2a.json。
+            if (effective?.a2a)
+                config.a2aPeers = resolveA2aPeers(effective.a2a, logger);
             logger.info("config_loaded", { source: configProvider.kind, version: r.effective.version });
         }
     }
@@ -724,6 +732,10 @@ export async function runLocal(argv, deps = {}) {
     const taskTimeoutSec = Math.max(0, Math.floor(numEnv("TASK_TIMEOUT_SEC", "0")));
     const timeoutSec = taskWallClockSec(taskTimeoutSec, false, scenarioName === "team");
     const mcp = mcpForScenario(config.mcpServers, scenarioName);
+    // DESIGN-269 车1 件3(本腿半场):A2A peers 同样按场景过滤进 spec。**只有 center/config 基线这一半**
+    // —— run-local 无 HTTP body,所以没有「调用方自带 peer」那条腿(与 [854]④ 的 body.limits 同姿势:
+    // 要 CLI flag 时另开件,别在这里半做)。缺席仍是缺席:`a2aForScenario` 恒返回 undefined 而非 []。
+    const a2a = a2aForScenario(config.a2aPeers, scenarioName);
     // A-002.9(#180 governance 缺口的同文件兄弟残余):运营方预算天花板两枚 —— 与 server 主路径
     // (boot/resolve-spec.ts)**同键同算法**,共用 budget.ts 的 `cappedCeiling`。此腿无 body(见上一段
     // 的 [854]④ 记账),所以 requested 恒缺席 ⇒ env 天花板在场时**直接成为** spec 值,天花板为 0/未设时
@@ -765,6 +777,7 @@ export async function runLocal(argv, deps = {}) {
         // [849]→[2400] 场景层定死终验已无生产者(autonomous 退役);OR 折入形保留,与 resolveSpec 同语义。
         ...(cap.finalVerification === true ? { finalVerification: true } : {}),
         ...(mcp ? { mcp } : {}),
+        ...(a2a ? { a2a } : {}),
         // core 5.8.0:timeoutSec 键退役 → maxWalltimeMs(毫秒);taskWallClockSec 仍产秒,换算在上方 limits 合成处。
         ...(Object.keys(limits).length > 0 ? { limits } : {}),
     }, config, workspaceDir);

package/dist/task-a2a.d.ts

@@ -0,0 +1,114 @@
+/**
+ * [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 config center 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";
+/** 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;
+}
+/**
+ * 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 (仓规:安全轴禁静默兜底).
+ */
+export declare function a2aInjectionHonored(config: A2aGateConfig): boolean;
+/**
+ * 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.
+ */
+export declare function validateRequestA2a(raw: unknown): {
+    ok: A2aServerSpec[];
+    dropped: string[];
+} | null;
+/**
+ * DESIGN-269 §2.4 —— **同步**拒面:部署锁了 `a2a` 而请求仍带 `a2aPeers` ⇒ 400 `config.locked_key`
+ * (逐字沿用 `assertRequestMcpUnlocked` 的裁定,连错误码都同一个 —— 消费端判的是「某个键被行政锁住了」,
+ * 不是「哪个键」;码分裂只会让 SDK 多写一条等价分支)。
+ *
+ * 判据是「请求**占位**」而不是「请求的值合不合法」:锁是两态的,占了就整拒,不静默丢(静默丢正是把
+ * 判决变成探针的那一形)。键缺席 / 显式 `null` 都不是占位;**空数组是占位**(调用方确实写了这个键)。
+ *
+ * ⚠️ **不看车道**:多租户腿本来就会忽略 body peers(`a2aInjectionHonored` 关),但锁在场时「忽略」是
+ * 错的失败方向 —— operator 声明了「本部署不收任务自带 A2A peer」,那就该说出来。
+ *
+ * ⚠️ 参数类型是 `ReadonlySet<string>`:core 的 `LockedKey` 尚无 `a2a` 成员(见模块头),而
+ * `ReadonlySet<LockedKey>` 结构上可当 `ReadonlySet<string>` 传入,所以调用点无需任何转换。
+ */
+export declare function assertRequestA2aUnlocked(bodyA2a: unknown, lockedKeys: ReadonlySet<string>): 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
+ * 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.
+ * Returns the baseline unchanged when there is nothing to add.
+ */
+export declare function mergeRequestA2a(baseline: A2aServerSpec[] | undefined, gated: A2aServerSpec[]): 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
+ * (or with no caller peers) returns the baseline unchanged. Logs `a2a_injection_ignored` when a caller SENT
+ * 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?: {
+    info?(m: string, meta?: unknown): void;
+    warn(m: string, meta?: unknown): void;
+}): A2aServerSpec[] | undefined;
+//# sourceMappingURL=task-a2a.d.ts.map