@sema-agent/server 7.26.0 → 7.27.0

package/USAGE.md

@@ -383,6 +383,35 @@ MCP_ELICITATION_TTL_MS=300000      # 一张没人填的表单挂多久后释放(
 - 总开关关着时四个节流钮解析照跑但无消费者——不设=行为不变。帧格式见
   [`docs/ASSISTANT-WIRE-CONTRACT.md` §4a-quater](docs/ASSISTANT-WIRE-CONTRACT.md)(`elicitation` / `elicitation_complete`)。
 
+**可选 — 把这台 worker 挂进别人的 A2A 拓扑(server-as-peer,DESIGN-269 车2):默认关**
+
+别家 orchestrator 把这台 sema-server 当成它拓扑里的一个 **A2A agent** 来调。开了才有两条对外路由;
+关着(默认)它们**都不存在**(404)——不是「发卡但拒调」。
+
+```bash
+A2A_SERVE_ENABLED=true                       # 总开关,默认 **false**(operator-knob 律;坏词拒启)
+A2A_SERVE_URL=https://agent.example.com/v1/a2a  # 【开了就必填】卡上公告的对外 JSON-RPC 端点
+A2A_SERVE_NAME=sema-edge                     # 卡上的 name(默认 "sema-server")
+A2A_SERVE_DESCRIPTION="…"                    # 可选
+A2A_SERVE_SKILLS='[{"id":"review","name":"Code review","description":"…","scenario":"code-review"}]'
+A2A_SERVE_BLOCKING_WAIT_MS=45000             # blocking:true 的服务端等待窗(默认 45000,有界 [0,300000])
+```
+- **`A2A_SERVE_URL` 开了就必填,且必须是可解析的 http(s) URL** —— 缺席/坏形**启动期拒**。可达地址是
+  运维声明的,服务端**不从请求 `Host` 头推导**:那等于让一个匿名的发现请求决定我们公网卡上公告的地址。
+  (同族先例:`FLEET_ADVERTISE_ADDRESS`。)🔒 URL **不许带 userinfo**(`https://user:pass@host/…`)——
+  它逐字上匿名可拉的卡,等于把凭据发给每个发现请求;带了**拒启**。入站鉴权走**头形**(服务凭据)。
+- **`A2A_SERVE_SKILLS` = JSON 数组,坏形拒启**(非 JSON / 非数组 / 条目缺 `id` 或 `scenario` / `id` 重复
+  / 超长 / 超过 64 条)。声明面**没有**「丢掉坏的那条继续跑」的合法语义:那会让你以为公告了一个技能而
+  对端根本看不到。每条 skill 的 `scenario` 是**内部**路由键 —— 它**不上卡**(自动枚举场景名给公网是
+  本设计唯一点名禁止的事),只决定点名这条 skill 的请求跑哪个场景。
+- 两条路由的**鉴权位置刻意不同**:`GET /.well-known/agent-card.json` 在服务凭据门**外**(公网匿名可
+  发现,零存量披露);`POST /v1/a2a` 在门**内**(与本仓其余 API 同一套凭据)。
+- `message/send` / `tasks/get` 还需要 **durable run store**(`DB_BACKEND=mysql|pg`)——缺它时两个方法
+  回具名 JSON-RPC `-32004`(卡照发)。开关打开时 boot 日志有一行 `a2a_serve_enabled`,里面的
+  `tasksUsable` 就是这件事。
+- 完整 wire 契约(方法表、错误码全表、Task 形与任务态投影、反枚举语义、版本槽)见
+  [`docs/ASSISTANT-WIRE-CONTRACT.md` 附录 C](docs/ASSISTANT-WIRE-CONTRACT.md)。
+
 **可选 — 父进程存活监视(`SEMA_PARENT_PID`,默认不装配)**
 
 壳(cli/TUI/桌面)自己 spawn 引擎的**同机形**里,壳被 `SIGKILL`(崩溃、`kill -9`、OOM killer)之后没有

package/dist/boot/config-center.js

@@ -46,7 +46,7 @@ import { defaultLkgPath, defaultSkillCacheDir, saveLkg, loadLkg } from "../confi
 import { createConfigProvider, raceBootFetch, BOOT_FETCH_DEFERRED } from "../config-provider.js";
 import { createKeyResolver } from "../key-resolver.js";
 import { ensureSealedKeyStore, reportExecutionPublicKey } from "../sealed-key.js";
-import { applyEffective, mutateInPlace, logEffectiveDiff, applyCenterSkills, resolveMcpServers, restartReasons, modelPlaneChanged, planeHasActiveTiers, fetchPromptArtifact } from "../config-center/facade.js";
+import { applyEffective, mutateInPlace, logEffectiveDiff, applyCenterSkills, resolveMcpServers, resolveA2aPeers, restartReasons, modelPlaneChanged, planeHasActiveTiers, fetchPromptArtifact } from "../config-center/facade.js";
 import { SHA256_HEX_RE } from "../digest-form.js";
 export async function createConfigCenterRuntime(ctx) {
     const { config, logger, metrics, localRoot } = ctx;
@@ -633,6 +633,10 @@ export async function createConfigCenterRuntime(ctx) {
             }
             if (effective?.mcp)
                 config.mcpServers = resolveMcpServers(effective.mcp, logger);
+            // DESIGN-269 车1 件1:A2A peers ride the SAME restart-to-apply line as MCP (one center pull, one
+            // resolution, no hot swap). Absent `a2a` domain ⇒ the key is never written ⇒ the leg does not exist.
+            if (effective?.a2a)
+                config.a2aPeers = resolveA2aPeers(effective.a2a, logger);
             return skills;
         },
         applyCenterScenarios(t) {

package/dist/boot/resolve-spec.js

@@ -43,9 +43,10 @@ import { gateExecutionLane } from "../runtime-caps-resolver.js";
 import { applyRuntimeGovernance, stripDelegationTools } from "../runtime-governance.js";
 import { HttpError, encodeCheckpointScope } from "../security.js";
 import { memorySpecForRequest } from "../memory-scope.js";
-import { mcpForScenario } from "../config-center/facade.js";
+import { a2aForScenario, mcpForScenario } from "../config-center/facade.js";
 import { normalizeAttachments, normalizeResilience, normalizeResumeAtMode, normalizeSuggestNextPrompts, promptProfileFromBody, resolveTaskLimits, retainBackgroundProcessesFromBody, taskAgentsSpecFragment, toolMaterializeStrategyFromBody, toolNameListFromBody } from "../spec-fields.js";
 import { cwdHonored, effectiveHostWorkspace, inProcessSingleUserLane, isValidCwd, parseAdditionalDirectories, satisfiedByProcessCwd, shellEnvMismatchCount } from "../task-cwd.js";
+import { assertRequestA2aUnlocked, resolveRequestA2a } from "../task-a2a.js";
 import { assertRequestMcpUnlocked, resolveRequestMcp } from "../task-mcp.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSettings, effectivePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, providerDropsAppend, shellGateForMode, withPermissionMode } from "../task-settings.js";
 import { enableForkFromBody, normalizeRetainSubagentSessions, selfOrchestrationFromBody } from "../task-workflow.js";
@@ -82,6 +83,10 @@ export function createResolveSpec(ctx) {
         // —— 一个最终 400 的请求若已经改掉了这两样,它就改变了**后续被接受的**任务会物化什么、在哪里执行。
         // core 对同一把锁的裁定原话是「Runs BEFORE any side effect of task preparation」,server 侧同姿势。
         assertRequestMcpUnlocked(body.mcpServers, lockedKeys);
+        // DESIGN-269 车1 件3:A2A 的同一条判据、同一个位置(同一批副作用要防)。锁键 `a2a` 在 core 5.36 的
+        // `LockedKey` 里尚不存在(分单件 C-1),所以这道门今天恒不触发 —— 它先在场是纵深:词表到货那一拍
+        // 它自己就活,而不是等着谁记起来补(见 task-a2a.ts 模块头的成文理由)。
+        assertRequestA2aUnlocked(body.a2aPeers, lockedKeys);
         // A10 留档件#2:六阶段流水线。顺序=原文顺序(每一阶段的体逐字搬运),阶段之间只传显式产出;
         // 六个阶段函数定义在本 `return` 之后(自上而下先读骨架、再读各阶段)。
         const gated = await gateScenarioAndAppend(body, auth, opts);
@@ -817,6 +822,13 @@ export function createResolveSpec(ctx) {
             // design/170 件C:锁形下本行不可达 —— `resolveSpec` 腿首已整拒(见那里的 F3 注)。`resolveRequestMcp`
             // 收下的 config 带着 `lockedConfigKeys`,所以即使将来有人绕开腿首那道门,honored 谓词也会翻假。
             mcp: resolveRequestMcp(mcpForScenario(config.mcpServers, scenarioName), body.mcpServers, config, logger),
+            // DESIGN-269 车1 件3 —— A2A peers,与上一行逐点同构:center 基线按场景过滤 + 调用方自带的 peer
+            // (单用户闸 ∧ 未锁 ∧ 合规未禁,`resolveRequestA2a` 里那只三票谓词是唯一属主),同名 baseline 赢。
+            // 🔴 与 MCP 的语义差:一个 peer 是**远端 agent**,core 给它的每条 skill 挂 `egress:true`+
+            // `effect:"write"`(2026-08-03 裁定)—— 所以这一行接出去的是对外写通道,不是数据源。两侧都缺席时
+            // 键整个不写(`a2aForScenario` 与 `resolveRequestA2a` 都恒返回 undefined 而非 []):缺席 = 本部署
+            // 没有这条腿,空表 = 「声明了一个空的 peer 集合」,对 core 与对读面都是两回事。
+            a2a: resolveRequestA2a(a2aForScenario(config.a2aPeers, scenarioName), body.a2aPeers, config, logger),
             // center prompts 投影([1057]①f):center 下发的场景终形(overrides[s] ?? 基线)赢过内置 provider
             // (center-wins,scenario overlay 同先例);无 pack/该场景空声明 ⇒ 内置照旧。声明数组逐字喂 typed
             // 钩子(contentHash 透传,core 1.315 校验入 manifest);packId 归因在采用日志(center_prompts_adopted)。

package/dist/boot/runner-deps.js

@@ -417,6 +417,16 @@ export function createRunnerDeps(ctx) {
                 metrics.inc("mcp_server_unavailable_total");
                 return;
             }
+            // "a2a" (DESIGN-269 车1 件4):an unreachable A2A peer was SKIPPED (core's materialize is fail-open per
+            // peer, `MaterializedA2a.warnings`) — the task still ran with the healthy peers' tools. Same posture as
+            // the MCP arm one line up, and for the same reason: a配置错/临时不可达的 peer 必须**可观测**,但它
+            // 不是任务失败,落 error 级会把它混进真故障的告警面。⚠️ 这不是「静默兜底」:fail-open 的裁决属 core
+            // (它已经决定跳过并把原因交出来),server 这一格只负责让它说出来 + 计数。
+            if (ctx.phase === "a2a") {
+                logger.warn("a2a_peer_unavailable", { sessionId: ctx.sessionId, info: String(err) });
+                metrics.inc("a2a_peer_unavailable_total");
+                return;
+            }
             // "prompt-cache" (1.22 low-hit + design/31 break detector): since core 1.89 the detector passes its
             // root cause as ctx.classification — "server-or-ttl" is usually benign in agentic tasks (slow tools ⇒
             // 5min+ request gaps expire provider caches) → warn; the prefix-bug causes

package/dist/config-center/facade.d.ts

@@ -42,6 +42,6 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, ConfigCenterHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
 export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, resolveDefaultModelName, logEffectiveDiff, runtimeHasActiveGate, } from "./apply-effective.js";
 export { restartReasons, planeHasActiveTiers, modelPlaneChanged, type RestartSlice, type RestartSliceCtx, type RestartSignal, } from "./restart-signal.js";
-export { applyCenterSkills, resolveMcpServers, mcpForScenario } from "./skills-mcp.js";
-export type { CenterSkillManifest, CenterMcpServer, EffectiveConfig, ExecutionRuling, SessionMirrorRuling, } from "./types.js";
+export { applyCenterSkills, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
+export type { CenterSkillManifest, CenterMcpServer, CenterA2aPeer, EffectiveConfig, ExecutionRuling, SessionMirrorRuling, } from "./types.js";
 //# sourceMappingURL=facade.d.ts.map

package/dist/config-center/facade.js

@@ -42,5 +42,5 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, ConfigCenterHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
 export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, resolveDefaultModelName, logEffectiveDiff, runtimeHasActiveGate, } from "./apply-effective.js";
 export { restartReasons, planeHasActiveTiers, modelPlaneChanged, } from "./restart-signal.js";
-export { applyCenterSkills, resolveMcpServers, mcpForScenario } from "./skills-mcp.js";
+export { applyCenterSkills, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
 //# sourceMappingURL=facade.js.map

package/dist/config-center/restart-signal.d.ts

@@ -1,5 +1,5 @@
 import type { EffectiveConfig } from "./types.js";
-export type RestartSlice = "skills" | "mcp" | "scenarios" | "runtime-gates" | "models-tiers" | "degrade-route";
+export type RestartSlice = "skills" | "mcp" | "a2a" | "scenarios" | "runtime-gates" | "models-tiers" | "degrade-route";
 /** What the CALLER must contribute about boot-baked catalog consumers that live OUTSIDE the Runner — the
  *  slices cannot see them, because they are configured from env (`ServiceConfig`), not from the center's
  *  EffectiveConfig. Absent/empty = that lane is off ⇒ its slice is inert (null on both sides). */

package/dist/config-center/restart-signal.js

@@ -7,7 +7,7 @@
  */
 import { resolveActiveTiers } from "@sema-agent/registry-core";
 import { RUNTIME_GATE_KEYS, runtimeGatePresent, resolveDefaultModelName } from "./apply-effective.js";
-const RESTART_SLICES = ["skills", "mcp", "scenarios", "runtime-gates", "models-tiers", "degrade-route"];
+const RESTART_SLICES = ["skills", "mcp", "a2a", "scenarios", "runtime-gates", "models-tiers", "degrade-route"];
 /** Canonical, key-sorted JSON (array order preserved) so two semantically-equal effective slices fingerprint
  *  identically regardless of object key order from the center serializer. */
 function stableStringify(v) {
@@ -70,6 +70,11 @@ function restartSliceValue(eff, slice, ctx) {
             return enabledOnly(eff.skills?.skills);
         case "mcp":
             return enabledOnly(eff.mcp?.servers);
+        case "a2a":
+            // 与 mcp 逐字同形:只指纹 ENABLED 条目(`resolveA2aPeers` 跳过 `enabled:false`,所以被禁条目的
+            // 内容零运行期效果),整条记录进指纹(url/cardUrl/headerRefs/principalHeader/allowSkills/scenarios
+            // 全是运行期相关字段;DENY-list 都不需要——本域没有 cost/quotaWeight 那种热字段)。
+            return enabledOnly(eff.a2a?.peers);
         case "scenarios":
             return enabledOnly(eff.scenarios?.scenarios);
         case "runtime-gates": {

package/dist/config-center/skills-mcp.d.ts

@@ -1,8 +1,8 @@
-import type { McpServerSpec } from "@sema-agent/core";
-import type { ScopedMcpServer } from "../config-types.js";
+import type { A2aServerSpec, McpServerSpec } from "@sema-agent/core";
+import type { ScopedA2aPeer, ScopedMcpServer } from "../config-types.js";
 import type { Logger } from "../observability/logger.js";
 import type { LoadedSkill } from "../capabilities/skills.js";
-import type { CenterMcpServer, CenterSkillManifest } from "./types.js";
+import type { CenterA2aPeer, CenterMcpServer, CenterSkillManifest } from "./types.js";
 /**
  * Merge center skills OVER the image baseline (design/41-sibling B1; `sema-registry docs/MCP-SKILLS.md`). Load order =
  * `loadSkills(SKILLS_DIR)` baseline → center skills lazily fetched by hash and overlaid BY NAME (center
@@ -29,4 +29,29 @@ export declare function resolveMcpServers(mcp: {
 }, logger?: Logger): ScopedMcpServer[];
 /** The MCP servers applicable to a scenario: tagged with it, or untagged (global). undefined when none. */
 export declare function mcpForScenario(servers: ScopedMcpServer[] | undefined, scenario: string): McpServerSpec[] | undefined;
+/**
+ * DESIGN-269 §2.1 —— resolve center A2A peers (`/effective.a2a`) into core `A2aServerSpec`s + the scenarios
+ * each applies to. Exact sibling of {@link resolveMcpServers}, same three rules:
+ *   · header-NAME refs → real values from THIS service's env (the secret boundary is unchanged — the center
+ *     never holds the bearer). A peer with ANY missing ref is SKIPPED wholesale (`resolveRefs` → null):
+ *     dialing a remote AGENT with half the credentials is the wrong failure direction.
+ *   · `enabled:false` skipped.
+ *   · restart-to-apply (filtered per scenario in `resolveSpec` via {@link a2aForScenario}).
+ *
+ * ⚠️ **No `toolAxes` on the center face, deliberately** (this is where the A2A lane STOPS mirroring MCP):
+ * core's ruling is that a caller override is the ONLY trusted way down from the fail-closed
+ * `egress:true`+`effect:"write"` default, and it names the CALLER as that trust root. An operator lowering
+ * an axis in center config would be vouching, on behalf of every future task, that a REMOTE agent's skill
+ * only reads — a claim the operator cannot actually verify and which core's own doc-comment reserves for
+ * the caller. Absent face > a face that quietly launders trust. (`allowSkills` is the operator's real
+ * knob here: narrow WHAT mounts, never re-label what it does.)
+ */
+export declare function resolveA2aPeers(a2a: {
+    peers: CenterA2aPeer[];
+}, logger?: Logger): ScopedA2aPeer[];
+/** The A2A peers applicable to a scenario: tagged with it, or untagged (global). undefined when none.
+ *  Twin of {@link mcpForScenario} — `undefined` (not `[]`) is load-bearing: an empty array would put an
+ *  `a2a: []` key on the spec, i.e. "this deployment declares an empty peer set", where absence means
+ *  "this leg does not exist here". */
+export declare function a2aForScenario(peers: ScopedA2aPeer[] | undefined, scenario: string): A2aServerSpec[] | undefined;
 //# sourceMappingURL=skills-mcp.d.ts.map

package/dist/config-center/skills-mcp.js

@@ -1,8 +1,11 @@
 /**
- * Two small consumption lanes that both project a center manifest domain onto a per-request runtime shape:
+ * Small consumption lanes that all project a center manifest domain onto a per-request runtime shape:
  * skills application (`applyCenterSkills` — merge center skills OVER the image baseline, content-addressed
- * fetch+verify+cache) and MCP server resolution (`resolveMcpServers`/`mcpForScenario` — env-NAME ref
- * resolution + per-scenario filtering). Split out of `facade.ts` (design/158 A13, internal-lossless —
+ * fetch+verify+cache), MCP server resolution (`resolveMcpServers`/`mcpForScenario` — env-NAME ref
+ * resolution + per-scenario filtering) and — since DESIGN-269 车1 — A2A peer resolution
+ * (`resolveA2aPeers`/`a2aForScenario`, the same two rules on the agent-to-agent lane; it lives HERE rather
+ * than in a new file because it shares `resolveRefs`, and a secret-boundary rule with two implementations
+ * is a rule with one that will drift). Split out of `facade.ts` (design/158 A13, internal-lossless —
  * the facade re-exports every symbol below unchanged).
  */
 import { skillContentHash } from "@sema-agent/registry-core";
@@ -86,15 +89,19 @@ diskCacheDir) {
 }
 /** Resolve env-NAME refs (target-key → ENV_NAME) to real values from THIS service's env. Returns null when
  *  ANY referenced env var is unset → the caller skips the whole server (fail-safe: never wire a half-credentialed
- *  endpoint). Mirrors the missing-apiKeyEnv handling for models (the secret boundary is unchanged). */
-function resolveRefs(refs, server, kind, logger) {
+ *  endpoint). Mirrors the missing-apiKeyEnv handling for models (the secret boundary is unchanged).
+ *
+ *  `event`/`skipNote` are per-lane so an operator reading logs sees WHICH lane dropped an entry (MCP server vs
+ *  A2A peer) — the resolution rule itself is one function on purpose (two copies of a secret-boundary rule is
+ *  how one of them drifts open). */
+function resolveRefs(refs, server, kind, logger, event = "sema_registry_mcp_env_missing", skipNote = "skipping this MCP server — referenced env var is unset in this service") {
     if (!refs)
         return {};
     const out = {};
     for (const [key, envName] of Object.entries(refs)) {
         const v = process.env[envName];
         if (v === undefined) {
-            logger?.warn("sema_registry_mcp_env_missing", { server, kind, key, envName, note: "skipping this MCP server — referenced env var is unset in this service" });
+            logger?.warn(event, { server, kind, key, envName, note: skipNote });
             return null;
         }
         out[key] = v;
@@ -146,4 +153,55 @@ export function mcpForScenario(servers, scenario) {
     const hit = servers.filter((s) => s.scenarios.length === 0 || s.scenarios.includes(scenario)).map((s) => s.spec);
     return hit.length > 0 ? hit : undefined;
 }
+/**
+ * DESIGN-269 §2.1 —— resolve center A2A peers (`/effective.a2a`) into core `A2aServerSpec`s + the scenarios
+ * each applies to. Exact sibling of {@link resolveMcpServers}, same three rules:
+ *   · header-NAME refs → real values from THIS service's env (the secret boundary is unchanged — the center
+ *     never holds the bearer). A peer with ANY missing ref is SKIPPED wholesale (`resolveRefs` → null):
+ *     dialing a remote AGENT with half the credentials is the wrong failure direction.
+ *   · `enabled:false` skipped.
+ *   · restart-to-apply (filtered per scenario in `resolveSpec` via {@link a2aForScenario}).
+ *
+ * ⚠️ **No `toolAxes` on the center face, deliberately** (this is where the A2A lane STOPS mirroring MCP):
+ * core's ruling is that a caller override is the ONLY trusted way down from the fail-closed
+ * `egress:true`+`effect:"write"` default, and it names the CALLER as that trust root. An operator lowering
+ * an axis in center config would be vouching, on behalf of every future task, that a REMOTE agent's skill
+ * only reads — a claim the operator cannot actually verify and which core's own doc-comment reserves for
+ * the caller. Absent face > a face that quietly launders trust. (`allowSkills` is the operator's real
+ * knob here: narrow WHAT mounts, never re-label what it does.)
+ */
+export function resolveA2aPeers(a2a, logger) {
+    const out = [];
+    for (const p of a2a.peers ?? []) {
+        if (p.enabled === false)
+            continue;
+        const headers = resolveRefs(p.headerRefs, p.name, "header", logger, "sema_registry_a2a_env_missing", "skipping this A2A peer — referenced env var is unset in this service");
+        if (headers === null)
+            continue;
+        out.push({
+            scenarios: p.scenarios ?? [],
+            spec: {
+                name: p.name,
+                url: p.url,
+                ...(p.cardUrl ? { cardUrl: p.cardUrl } : {}),
+                ...(Object.keys(headers).length ? { headers } : {}),
+                ...(p.principalHeader ? { principalHeader: p.principalHeader } : {}),
+                ...(p.allowSkills && p.allowSkills.length > 0 ? { allowSkills: p.allowSkills } : {}),
+            },
+        });
+    }
+    if (out.length > 0)
+        logger?.info("sema_registry_a2a", { peers: out.map((p) => p.spec.name) });
+    return out;
+}
+/** The A2A peers applicable to a scenario: tagged with it, or untagged (global). undefined when none.
+ *  Twin of {@link mcpForScenario} — `undefined` (not `[]`) is load-bearing: an empty array would put an
+ *  `a2a: []` key on the spec, i.e. "this deployment declares an empty peer set", where absence means
+ *  "this leg does not exist here". */
+export function a2aForScenario(peers, scenario) {
+    if (!peers || peers.length === 0)
+        return undefined;
+    const hit = peers.filter((p) => p.scenarios.length === 0 || p.scenarios.includes(scenario)).map((p) => p.spec);
+    return hit.length > 0 ? hit : undefined;
+}
 //# sourceMappingURL=skills-mcp.js.map

package/dist/config-center/types.d.ts

@@ -123,6 +123,29 @@ export interface CenterMcpServer {
         principalHeader?: string;
     };
 }
+/**
+ * DESIGN-269 §2.1 —— A2A peer registry entry (the `CenterMcpServer` sibling). `headerRefs` are env-NAME
+ * refs (header-name → ENV_NAME), **never** literal secrets: the bearer for a peer lives in THIS service's
+ * env, the center only ever stores the NAME. (A2A has a single transport — every peer is an https(s)
+ * endpoint — so unlike MCP there is no transport discriminant; the two ref-carrying shapes collapse to one.)
+ */
+export interface CenterA2aPeer {
+    name: string;
+    scenarios: string[];
+    enabled?: boolean;
+    /** The peer's service URL (also the origin the well-known agent-card path resolves against). */
+    url: string;
+    /** Explicit agent-card location when the peer does not publish at a well-known path. Set ⇒ used ALONE. */
+    cardUrl?: string;
+    /** env-NAME refs (header-name → ENV_NAME) resolved from THIS service's env at boot. A peer with ANY
+     *  unset ref is SKIPPED wholesale (fail-safe — never dial a peer half-credentialed). */
+    headerRefs?: Record<string, string>;
+    /** design/62, same contract as the MCP side: the header name the runner injects the task's authenticated
+     *  end-user principal into. Not a ref — a literal header NAME (the runner fills the value, never the model). */
+    principalHeader?: string;
+    /** Optional allowlist of the peer's skill ids to mount (others are not mounted). */
+    allowSkills?: string[];
+}
 export interface EffectiveConfig {
     version: number;
     updatedAt: string;
@@ -156,6 +179,11 @@ export interface EffectiveConfig {
     mcp?: {
         servers: CenterMcpServer[];
     };
+    /** DESIGN-269 §2.1: center-declared A2A peers. Absent (the shape every center ships today) ⇒ the leg
+     *  does not exist for this deployment — `config.a2aPeers` stays undefined, no peer is ever dialed. */
+    a2a?: {
+        peers: CenterA2aPeer[];
+    };
     /** Center-declared scenarios (composition-as-config; capability stays code-pinned): each entry names a
      *  deploy-registered TOOLSET (`none` / `repo-readonly`) + an optional static prompt (≤4KB, audited at
      *  publish). Restart-to-apply like skills/mcp (baked into the scenario table at boot). Center entries

package/dist/config-types.d.ts

@@ -6,7 +6,7 @@
  *  compiling unchanged. All imports below are top-level `import type` (erased — never a load edge,
  *  see test/module-cycle-gate.test.ts header on verbatimModuleSyntax). */
 import type { SealedKeyPoison } from "./sealed-key.js";
-import type { CompliancePosture, LockedKey, McpServerSpec, Model, ModelRoles, RetentionPolicy } from "@sema-agent/core";
+import type { A2aServerSpec, CompliancePosture, LockedKey, McpServerSpec, Model, ModelRoles, RetentionPolicy } from "@sema-agent/core";
 import type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.js";
 import type { ElicitationThrottle } from "./elicitation.js";
 import type { QuestionThrottle } from "./question.js";
@@ -35,6 +35,63 @@ export interface ScopedMcpServer {
     scenarios: string[];
     spec: McpServerSpec;
 }
+/** DESIGN-269 §2.1 —— an A2A PEER resolved to a core spec (header-NAME refs already → real values) plus
+ *  the scenarios it applies to (empty = all). Exact sibling of {@link ScopedMcpServer}: `resolveSpec`
+ *  filters by scenario (`a2aForScenario`) and passes `spec` to core as `TaskSpec.a2a`.
+ *
+ *  🔒 A peer is a remote AGENT, not a data source — core mounts every one of its skills with
+ *  `egress:true` + `effect:"write"` (ruled 2026-08-03), so a configured peer is an outbound WRITE
+ *  channel on every scenario it is scoped to. Scope deliberately, exactly as with an MCP server. */
+export interface ScopedA2aPeer {
+    scenarios: string[];
+    spec: A2aServerSpec;
+}
+/**
+ * DESIGN-269 §3.1 车2 —— ONE declared skill on the agent card this deployment publishes when it acts as
+ * an A2A **peer** (server-as-peer half). v1 is a **static declaration**: the operator writes the list,
+ * the server never enumerates its own scenarios into it.
+ *
+ * 🔒 Why static (设计稿 §3.1 逐字):auto-enumeration would publish this deployment's internal scenario
+ * names to an anonymous public discovery document. `scenario` is the ONE field that names an internal
+ * key, and it is deliberately **not** projected onto the wire card (see `buildAgentCard` — the card
+ * carries `id`/`name`/`description` only). It exists so a declared skill actually routes somewhere:
+ * a `message/send` naming this skill runs under that scenario.
+ */
+export interface A2aServeSkill {
+    /** Public, caller-facing skill id (what an A2A peer names to select it). Never an internal key. */
+    id: string;
+    /** Human label; defaults to `id` on the card when absent. */
+    name?: string;
+    description?: string;
+    /** INTERNAL scenario key this skill runs under. NEVER projected onto the card. */
+    scenario: string;
+}
+/**
+ * DESIGN-269 §3.3 车2 —— the server-as-peer block. **Absence IS the OFF state** (`A2A_SERVE_ENABLED`
+ * default OFF): with this field undefined both `/.well-known/agent-card.json` and `POST /v1/a2a` 404,
+ * i.e. "卡都不发=对外不存在" — not "publish a card but refuse the calls". Modelling OFF as absence
+ * (rather than an `enabled:false` member) makes the half-state structurally unrepresentable.
+ *
+ * `url` is REQUIRED here because it is required when the knob is on: a public discovery document that
+ * cannot say where to call is a broken card, and the reachable address is the operator's to declare —
+ * #123 `FLEET_ADVERTISE_ADDRESS` precedent, 不自猜可达地址(deriving it from the request `Host` header
+ * would let an anonymous caller decide what our public card advertises).
+ */
+export interface A2aServeConfig {
+    /** `A2A_SERVE_NAME` — the card's `name`. */
+    name: string;
+    /** `A2A_SERVE_DESCRIPTION` — the card's `description`. */
+    description?: string;
+    /** `A2A_SERVE_URL` — the PUBLIC JSON-RPC endpoint URL announced on the card (http/https, validated). */
+    url: string;
+    /** `A2A_SERVE_SKILLS` — declared skills (may be empty: an honest "I take work, I advertise no skill"). */
+    skills: A2aServeSkill[];
+    /** `A2A_SERVE_BLOCKING_WAIT_MS` — how long a `blocking:true` `message/send` waits for a terminal state
+     *  before answering `working` and letting the caller poll `tasks/get`. Server-side budget only — it is
+     *  NOT core's client-leg `A2A_CALL_TOTAL_TIMEOUT_MS` (that is the CALLER's 10-minute budget, and holding
+     *  an inbound HTTP request open for anything like that long is how you exhaust a connection pool). */
+    blockingWaitMs: number;
+}
 /** Sandbox-image-pool BAKE config (IMAGE-API-DESIGN.md §P2). `enabled=false` ⇒ the /v1/images/bakes* block is
  *  off (the control plane never mounts). The runner-facing facts (the runner principal, the build-host CACHE_BASE,
  *  the default base ref) live here so image-api injects only VETTED, server-fixed values into the build.sh argv —
@@ -435,6 +492,18 @@ export interface ServiceConfigFlat {
      *  filtered per scenario in `resolveSpec`. Not env-derived — populated by the sema-registry adapter when
      *  present (restart-to-apply, like models/roles); undefined = no center MCP (scenarios use no MCP). */
     mcpServers?: ScopedMcpServer[];
+    /** DESIGN-269 §2.1 —— A2A peers from the config center (`/effective.a2a`), resolved at startup
+     *  (header-NAME refs → values) and filtered per scenario in `resolveSpec` (`a2aForScenario`). Same
+     *  posture as {@link mcpServers}: not env-derived (no A2A_* env leg — a peer is a structured record,
+     *  not a scalar), populated by the config-center adapter when present, restart-to-apply.
+     *  undefined = no center peers ⇒ **the whole leg does not exist** for a task (`TaskSpec.a2a` stays
+     *  absent unless a single-user caller injects `body.a2aPeers`). */
+    a2aPeers?: ScopedA2aPeer[];
+    /** DESIGN-269 §3.3 车2 —— server-as-peer. **undefined = OFF** (the default), and OFF means both the
+     *  card and the JSON-RPC endpoint 404. See {@link A2aServeConfig}. Env-derived (`A2A_SERVE_*`), unlike
+     *  {@link a2aPeers}: the serve block is a handful of scalars an operator sets on the worker, not a
+     *  center-distributed record. */
+    a2aServe?: A2aServeConfig;
     tidb?: {
         host: string;
         port: number;
@@ -1222,8 +1291,8 @@ export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" |
 export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "sighupIdleGraceMs" | "parentPid" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
 /** 组:observability(可观测)。 */
 export type ServiceObservabilityConfig = Pick<ServiceConfigFlat, "metricsToken" | "traceToken" | "toolTrace" | "traceThinking" | "logLevel" | "otel">;
-/** 组:integrations(外部集成)。`mcpServers` 由 sema-registry 适配器填(无 env 腿),归本组。 */
-export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "gitApiKind" | "defaultScenario" | "skillsDir" | "configCenter" | "configProvider" | "configLocalDir">;
+/** 组:integrations(外部集成)。`mcpServers` / `a2aPeers` 由 sema-registry 适配器填(无 env 腿),归本组。 */
+export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "a2aPeers" | "a2aServe" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "gitApiKind" | "defaultScenario" | "skillsDir" | "configCenter" | "configProvider" | "configLocalDir">;
 /** 九个组槽。每组恒在场(`loadConfig` / `attachConfigGroups` 装好才交出配置),故不可选——新代码写
  *  `config.modelPlane.model` 不需要 `?.`(可选组会把 `Model` 污染成 `Model | undefined`)。 */
 export interface ServiceConfigGroups {

package/dist/config.d.ts

@@ -4,7 +4,8 @@ import type { ServiceConfig, ServiceConfigFlat, ServiceConfigGroups } from "./co
 /** design/158 A1: the config TYPE face lives in the leaf module config-types.ts; re-exported here so
  *  every existing `from "./config.js"` importer compiles unchanged (pure-type consumers should prefer
  *  importing config-types.js directly — a type-only leaf, no loader baggage). */
-export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig, ServiceConfigFlat, ServiceConfigGroups, ServiceStoreConfig, ServiceModelPlaneConfig, ServiceApprovalConfig, ServiceMemoryConfig, ServiceAuthConfig, ServiceOrchestrationConfig, ServiceLimitsHttpConfig, ServiceObservabilityConfig, ServiceIntegrationsConfig, MemoryEmbedderConfig, } from "./config-types.js";
+export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig, ServiceConfigFlat, ServiceConfigGroups, ServiceStoreConfig, ServiceModelPlaneConfig, ServiceApprovalConfig, ServiceMemoryConfig, ServiceAuthConfig, ServiceOrchestrationConfig, ServiceLimitsHttpConfig, ServiceObservabilityConfig, ServiceIntegrationsConfig, MemoryEmbedderConfig, // #228:embedder 坐标(plugins/memory-embedder.ts 消费同一属主类型)
+A2aServeConfig, A2aServeSkill, } from "./config-types.js";
 /** Parse the AUTONOMY env into a validated autonomy mode. Unset/empty → undefined (unmanaged → no extra
  *  tightening). An UNKNOWN value FAILS at startup rather than silently becoming a no-op (a typo'd `AUTONOMY=readonly`
  *  must not silently leave a deployment ungoverned — fail-loud, same discipline as numEnv). Exported so the HOT

package/dist/config.js

@@ -1090,8 +1090,9 @@ function parseDegradeOn(words) {
  * "only a tool literally named `Bash(ps:*)` may run" ⇒ Bash unavailable, with no warning anywhere. That is a
  * spelling-FAMILY error, not a typo, so it is refused on every list — with the two knobs that really do the job.
  *
- * 本批**不实现** CC 形语义(参数级规则是扩面,另候裁);判据只认括号的在场,残形(`Bash(ps`)同样拒——
- * 半个括号一样永不匹配活名。
+ * 🔴 CC 形语义(参数级规则)**已裁不支持,此为终态**(clay 终裁 2026-08-16,sema-comms
+ * audits/CLAY-RULINGS.md R-9;历史上已裁多遍,禁再上问)——响亮拒+指路即本面的完整承诺。
+ * 判据只认括号的在场,残形(`Bash(ps`)同样拒——半个括号一样永不匹配活名。
  */
 function ccRuleFormGuidance(name) {
     if (!name.includes("(") && !name.includes(")"))
@@ -2154,8 +2155,113 @@ function parseIntegrationsDomain() {
             : undefined,
         configProvider: process.env.CONFIG_PROVIDER || undefined,
         configLocalDir: process.env.CONFIG_LOCAL_DIR || undefined,
+        a2aServe: parseA2aServe(),
     };
 }
+/** 一条已声明 skill 的字段上限(卡是**公网文档**:无界的运维自由文本会让一张卡长到任何大小,而卡由
+ *  匿名调用方拉取)。id 短、文案宽,数量有帽。 */
+const A2A_SERVE_MAX_SKILLS = 64;
+const A2A_SERVE_MAX_ID_CHARS = 128;
+const A2A_SERVE_MAX_TEXT_CHARS = 2048;
+/**
+ * DESIGN-269 §3.3 车2 —— `A2A_SERVE_*` 域(server-as-peer 总旋钮 + 卡内容声明面)。
+ *
+ * 姿势(全是既有先例的照抄,不是新发明):
+ *  · **默认 OFF**(operator-knob 律:无客户端表态派生腿)。`A2A_SERVE_ENABLED` 走 {@link boolEnv} ⇒
+ *    坏词当场拒启(#123/#241-rc2 响亮拒族),不静默回默认。
+ *  · OFF ⇒ 返回 `undefined`,而不是一个 `enabled:false` 的块。缺席即 OFF 让「发了卡但拒调」这个半态
+ *    在类型上不可表达(设计稿 §3.3 的判词是「卡都不发=对外不存在」)。
+ *  · ON 而 `A2A_SERVE_URL` 缺席/坏形 ⇒ **拒启**。理由与 #123 `FLEET_ADVERTISE_ADDRESS` 逐字同族:
+ *    ①半配置的部署带病运行比起不来危险(卡上没有 `url`,对端拿到一张打不通的卡,失败点远离原因);
+ *    ②可达地址是**运维声明**的,不许自猜——从请求 `Host` 头推导等于让匿名调用方决定我们公网卡上
+ *    公告的地址(反射/缓存投毒面),本仓在 fleet 那条腿上已经拒绝过一次同样的诱惑。
+ *  · `A2A_SERVE_SKILLS` = JSON 数组,**坏形拒启**(声明面静默丢=部署方以为发出去了、对端看不到,
+ *    正是「无声 fail-open」;这里没有可用的降级语义)。
+ */
+function parseA2aServe() {
+    if (!boolEnv("A2A_SERVE_ENABLED", false))
+        return undefined;
+    const rawUrl = process.env.A2A_SERVE_URL ?? "";
+    if (rawUrl === "") {
+        throw new Error(`A2A_SERVE_ENABLED is on but A2A_SERVE_URL is not set — the agent card MUST announce where its JSON-RPC endpoint is reachable, ` +
+            `and that address is the operator's to declare (it is NOT derived from the request Host header: an anonymous discovery caller must not decide what our public card advertises). ` +
+            `Set A2A_SERVE_URL to this deployment's externally reachable /v1/a2a URL (e.g. "https://agent.example.com/v1/a2a").`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
+        throw new Error(`A2A_SERVE_URL must be a parseable http(s) URL (e.g. "https://agent.example.com/v1/a2a"); got ${JSON.stringify(rawUrl)}`);
+    }
+    // 🔴 codex 轮2 R2-1(HIGH,验真后修):URL **userinfo** 段拒启。这个值被**逐字**放进 agent card,而卡是
+    // 匿名可拉的公开文档 —— 一个看起来很合理的 Basic-auth 配置手滑(`https://user:pass@host/v1/a2a`)会把
+    // 凭据发给每一个发现请求。方向取**拒启**而不是脱敏:脱敏会让部署方以为自己配的鉴权生效了(实际
+    // 被抹掉),而这条路的鉴权本来就该走**头形**(R-11:RPC 持服务凭据)。同族先例=车1 自审第三镜给
+    // client 侧读面做的 endpoint 脱敏,只是那边是**读别人的**卡、这边是**发我们自己的**卡,故更严。
+    if (parsed.username !== "" || parsed.password !== "") {
+        throw new Error(`A2A_SERVE_URL must not carry userinfo (credentials before "@") — it is published verbatim on the ANONYMOUSLY readable agent card, so those credentials would be handed to every discovery caller. ` +
+            `Inbound authentication on this endpoint is header-shaped (a service credential), not URL-embedded; strip the userinfo and keep the secret in the caller's headers.`);
+    }
+    return {
+        name: env("A2A_SERVE_NAME", "sema-server"),
+        ...(process.env.A2A_SERVE_DESCRIPTION ? { description: process.env.A2A_SERVE_DESCRIPTION } : {}),
+        url: rawUrl,
+        skills: parseA2aServeSkills(process.env.A2A_SERVE_SKILLS),
+        // 服务端等待窗。**远小于** core 客户端腿的 10min 总预算(那是调用方的钱包,不是我们的连接池):
+        // 一条 inbound HTTP 请求被按住的每一秒都占着一条连接与一个 socket,而协议自带 `tasks/get` 轮询
+        // 出路,所以窗到期回 `working` 是**正常路径**、不是降级。上限 5min 是硬帽(比它更长请改用轮询)。
+        blockingWaitMs: numEnvBounded("A2A_SERVE_BLOCKING_WAIT_MS", "45000", 0, 300_000),
+    };
+}
+/** `A2A_SERVE_SKILLS` 的逐条校验。**在场即须合法,否则拒启**——声明面没有「丢掉坏的那条继续跑」的
+ *  合法语义:那会让部署方以为自己公告了一个技能而对端根本看不到(静默 fail-open 的教科书形)。 */
+function parseA2aServeSkills(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`A2A_SERVE_SKILLS must be a JSON array of {id, name?, description?, scenario} objects — it did not parse as JSON (${e.message})`);
+    }
+    if (!Array.isArray(parsed))
+        throw new Error(`A2A_SERVE_SKILLS must be a JSON ARRAY of {id, name?, description?, scenario} objects; got ${typeof parsed}`);
+    if (parsed.length > A2A_SERVE_MAX_SKILLS)
+        throw new Error(`A2A_SERVE_SKILLS declares ${parsed.length} skills — at most ${A2A_SERVE_MAX_SKILLS} are accepted (the card is a public document fetched by anonymous callers)`);
+    const seen = new Set();
+    return parsed.map((entry, i) => {
+        const at = `A2A_SERVE_SKILLS[${i}]`;
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            throw new Error(`${at} must be an object {id, name?, description?, scenario}`);
+        const e = entry;
+        const str = (key, required, max) => {
+            const v = e[key];
+            if (v === undefined) {
+                if (required)
+                    throw new Error(`${at}.${key} is required (a skill without it cannot be ${key === "id" ? "selected by a caller" : "routed to a scenario"})`);
+                return undefined;
+            }
+            if (typeof v !== "string" || v.length === 0)
+                throw new Error(`${at}.${key} must be a non-empty string`);
+            if (v.length > max)
+                throw new Error(`${at}.${key} must be at most ${max} characters`);
+            return v;
+        };
+        const id = str("id", true, A2A_SERVE_MAX_ID_CHARS);
+        if (seen.has(id))
+            throw new Error(`${at}.id ${JSON.stringify(id)} is declared twice — skill ids address a scenario, so a duplicate makes the routing ambiguous`);
+        seen.add(id);
+        const name = str("name", false, A2A_SERVE_MAX_TEXT_CHARS);
+        const description = str("description", false, A2A_SERVE_MAX_TEXT_CHARS);
+        const scenario = str("scenario", true, A2A_SERVE_MAX_ID_CHARS);
+        return { id, ...(name !== undefined ? { name } : {}), ...(description !== undefined ? { description } : {}), scenario };
+    });
+}
 const STORE_GROUP_KEYS = [
     "sessionBackend", "sessionCacheTtlSec", "storeProbeIntervalMs", "rewindSnapshotMaxMb", "dbBackend", "dbBackendExplicit", "localDataRoot",
     "tidb", "pg", "dbQueryTimeoutMs", "snapshotBlobStore", "snapshotBlobSqlMaxBytes", "snapshotBlobAllowSql", "sendUserFile",
@@ -2198,7 +2304,7 @@ const LIMITS_HTTP_GROUP_KEYS = [
 ];
 const OBSERVABILITY_GROUP_KEYS = ["metricsToken", "traceToken", "toolTrace", "traceThinking", "logLevel", "otel"];
 const INTEGRATIONS_GROUP_KEYS = [
-    "pluginsAllowHosts", "mcpServers", "configBootFetchBudgetMs", "gitApiBaseUrl", "gitApiToken", "gitApiKind", "defaultScenario",
+    "pluginsAllowHosts", "mcpServers", "a2aPeers", "a2aServe", "configBootFetchBudgetMs", "gitApiBaseUrl", "gitApiToken", "gitApiKind", "defaultScenario",
     "skillsDir", "configCenter", "configProvider", "configLocalDir",
 ];
 /** 组名 → 该组取景的平铺键(introspection 面:测试用它钉「每个平铺键恰好被一组取景」)。 */

package/dist/http/route-ctx.d.ts

@@ -125,8 +125,18 @@ export interface DriveResumeArgs {
  *  routes/* 互相值 import 的第二条环。做法:留在 `createHttpServer` 闭包里(实现逐字不动),只把**函数引用**
  *  装进这一格,域模块经 `ctx.legs.*` 调用。类型化 ⇒ 腿的形漂了是编译红,不是运行时静默 404。 */
 export interface RouteLegs {
-    /** POST /v1/tasks · /v1/tasks/stream · /v1/runs 的共同前段:读体 → 校验 → resolveSpec。null = 已应答(400/…)。 */
-    prepareSpec(req: IncomingMessage, res: ServerResponse): Promise<PreparedTaskSubmission | null>;
+    /** POST /v1/tasks · /v1/tasks/stream · /v1/runs 的共同前段:读体 → 校验 → resolveSpec。null = 已应答(400/…)。
+     *
+     *  `body` = **已解析好的**请求体,给那些体不是「这条 HTTP 请求的 JSON 正文」的调用方
+     *  (DESIGN-269 车2:A2A JSON-RPC 腿已经把正文读成了一条 `message/send` 请求,再 `readJson(req)`
+     *  一次只会读到空流)。缺席 ⇒ 照旧自己读体,既有三个调用方一字不改。
+     *  ⚠️ 这是**入口形**的分歧,不是校验面的分歧:传进来的体与自己读的体走**同一段**校验/授权/
+     *  resolveSpec —— 分叉出第二条校验路径正是本参数存在的理由的反面。
+     *
+     *  `onTypedFailure` = 「typed 拒绝**别写响应**,交回给我」。默认(缺席)行为不变:`HttpError` 走
+     *  `sendError` 连 `extra` 一起回显。DESIGN-269 车2 的 A2A 腿必须传它 —— 那些 `extra`(尤其
+     *  `scenario_unknown` 的**全部场景名**)对壳是指路材料,对一个外部 peer 是内部词表泄漏。 */
+    prepareSpec(req: IncomingMessage, res: ServerResponse, body?: TaskRequestBody, onTypedFailure?: (err: import("../security.js").HttpError) => void): Promise<PreparedTaskSubmission | null>;
     /** 同步腿的终局记账(计费/配额/指标),tasks 域用。 */
     finalizeTaskResult(result: TaskResult, principal: string | undefined, objective: string, sessionId: string | undefined): void;
     /** approvals 决策腿:session → pending checkpoint → markResuming CAS → 驱动续跑。