@sema-agent/server 7.147.0 → 7.149.0

package/dist/http/retired-skill-manifest.d.ts

@@ -2,7 +2,7 @@
  * 技能上已退役的 `manifest` 键 —— 「一条技能还带它」的**唯一判据**(core 7.41.0 起 `SkillSpec.manifest` 退役,零别名)。
  *
  * 两个读者,同一句话:
- *  · 提交口的顶层技能门(`admission.ts` 的 `validateUserSkills`):带它(任何值)⇒ 点名拒;
+ *  · 提交口的两道技能门(顶层 `skills[i]` 与子代 `agents[a].skills[j]`,同经 `spec-fields.ts` 的 `skillItemIssue` → `namedRefusalOf`):带它(任何值)⇒ 点名拒;
  *  · 随包排空脚本(`scripts/drain-check-local.mjs` 的 `retired-skill-manifest` 判据,经脚本隔壁的编译产物 `dist/http/retired-skill-manifest.js` 取):
  *    升级前停驻、持久化的提交体里仍带它的行,升级后续跑会被引擎按名拒(顶层 `skills[]`)或丢掉那只子代定义(`agents[].skills[]`),运维升级前要能数出来。
  *

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

@@ -17,7 +17,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { HostDecision } from "../host-decision.js";
 import type { EntryProblem } from "../entry-problems.js";
-import type { SessionOwnerCell } from "../security.js";
 import type { SessionNotifyDoor } from "../session-notify-door.js";
 import type { TaskStream, TaskSpec, TaskResult, QuestionAnswer, Checkpoint, CheckpointToken, ResumeOutcome, RunInternals, Runner, EngineNotice, PendingSteerInput } from "@sema-agent/core";
 import type { FlatServiceDeps, RequestAuth } from "./server.js";
@@ -37,6 +36,9 @@ import type { RootedTaskSpec } from "./execution-context.js";
 import type { GateCommitment, GateSettlementEvidence } from "../gate-settlement.js";
 import type { ResumeRestatement } from "./resume-restatement.js";
 import type { RememberLaneCannotRecord } from "../parked-decide.js";
+import type { RowWayOut } from "./resume-legs.js";
+import type { KeyCaller } from "../owner-faces.js";
+import type { Subject } from "../owner-brands.js";
 /** 跨域可变状态 = lens1 §C2 实测的那 8 条「运行期登记簿」,一个对象。
  *  [ref]:`cancelledViaVerb`(按 taskId 键控的「这次是取消动词」旁表)删除 —— 中止成因改挂在每条腿自己的
  *  {@link RunAbort} 句柄上(`inflightRuns` 的值),同寿同删,不再有一张与腿不同寿的旁表。 */
@@ -59,11 +61,12 @@ export interface RouteHelpers {
     readRawBody(req: IncomingMessage, max: number): Promise<Buffer>;
     rateLimited(req: IncomingMessage, res: ServerResponse): boolean;
     quotaExceeded(req: IncomingMessage, res: ServerResponse): boolean;
-    leaseDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+    /** `seat` 在场(提交门之后的调用点)⇒ 拒经出口座写(`submission-exit.ts`:先收场、再写);缺席(提交门之前)⇒ 当场写。下面 `usageWindowDenied` / `admitRun` 同。 */
+    leaseDenied(req: IncomingMessage, res: ServerResponse, seat?: TerminalSeat): Promise<boolean>;
     /**
      * 🔴 **[ref]:按**付费**方(不是请求方)判的成本配额准入 —— {@link quotaExceeded} 的孪生。**
      *
-     * `quotaExceeded` 键在 `gatedPrincipal(req)` = 谁点的按钮;本门键在**这笔钱记谁的账**。两者在自助
+     * `quotaExceeded` 键在 `gatedSubject(req)` = 谁点的按钮;本门键在**这笔钱记谁的账**。两者在自助
      * 场景恒相等,在「显式 operator 代别人动手」的场景不等 —— 那正是配额上限被绕过的那一支。
      * 参数 `owner` 由调用点从**已属主校验过的那一行**取(run 行的 `owner` / checkpoint 的 scope),
      * 本门不自己推身份(推得出来就说明调用点还有第二个身份源,那才是病)。
@@ -79,23 +82,14 @@ export interface RouteHelpers {
      *  「拿自己的额度去烧别人的账」的那一支。同样必须排在 owner 门之后、驱动之前。 */
     ownerLeaseDenied(res: ServerResponse, owner: string | undefined): Promise<boolean>;
     /** [ref]-T1:治理窗 pre-admission(异步 202 车道的唯一 429 出路;key 公式与 core 单源)。 */
-    usageWindowDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+    usageWindowDenied(req: IncomingMessage, res: ServerResponse, seat?: TerminalSeat): Promise<boolean>;
     /**
      * 在飞 run 并发帽的提交门准入(`RUN_MAX_CONCURRENT*`,缺省关;判据、席位与拒的形全文在 `http/run-concurrency-cap.ts`):放行 ⇒ 席位(登记那一拍与 `finally` 放);
-     * 超帽 ⇒ 已应答 429 + `Retry-After`、回 `undefined`。只挂**新提交**门(`createDurableRun` / `POST /v1/tasks` / `POST /v1/tasks/stream`),
+     * 超帽 ⇒ 已(经出口座)应答 429 + `Retry-After`、回 `undefined`。只挂**新提交**门(`createDurableRun` / `POST /v1/tasks` / `POST /v1/tasks/stream`),
      * 排在幂等重放与 `usageWindowDenied` 之后、任何建行 / 认领 / SSE 头之前。
      */
-    admitRun(req: IncomingMessage, res: ServerResponse): import("./run-concurrency-cap.js").RunSlot | undefined;
+    admitRun(req: IncomingMessage, res: ServerResponse, seat: TerminalSeat): Promise<import("./run-concurrency-cap.js").RunSlot | undefined>;
     safeDecode(seg: string): string | null;
-    /** run 面的属主门(谓词 `runOwnerReadable`;非属主 ⇒ 404 `not_found.run` + 长文,与 run 读口的 unknown 臂同码同串,[ref])。 */
-    runOwnerOk(req: IncomingMessage, res: ServerResponse, owner: string | null): boolean;
-    /** 会话面的属主门(谓词 `sessionOwnerReadable`,[ref]:没有身份边界的部署不钉人,与会话列表同读;非属主 ⇒ 404 `not_found.session` +
-     *  {@link SESSION_NOT_FOUND_MESSAGE},与会话读口的 unknown 臂同码同串 —— G52 [ref] / [ref])。每一个按会话寻址的属主判都走它。
-     *  `cell` = 调用点经 `security.ts` 的 `sessionOwnerCellOf` 读出的那一格([ref]:无主的委派子代 placed 行只对 fleet 调用方放行,判据 `ownerlessRowOpen`)。 */
-    sessionOwnerOk(req: IncomingMessage, res: ServerResponse, cell: SessionOwnerCell): boolean;
-    runSessionAcceptOk(req: IncomingMessage, res: ServerResponse, run: {
-        sessionId: string | null;
-    }, face: string, notFoundError?: string): boolean;
 }
 /** 单域独占状态(lens1 实测 12 条)——不进 registry,跟着各自的域模块走;每个 server 实例一份
  *  (模块级会把 rate-limiter / 缓存跨实例串味,测试里一个进程建几十个 server)。 */
@@ -126,6 +120,8 @@ export interface RouteRequestState {
 }
 /** B4①(命名化):`prepareSpec` 的返回形(tasks.ts/runs.ts 两域共同消费的属性面)——原为 6 成员内联匿名对象。
  *  命名后好处不只是过 B4 门:两个消费域现在都能对同一个符号做 `import type` 标注,而不是各自重推断结构。 */
+/** 提交门之后的拒交给出口座写的那一面(`submission-exit.ts`)。 */
+export type TerminalSeat = Pick<import("../submission-exit.js").SubmissionSeat, "deliverTerminal">;
 export interface PreparedTaskSubmission {
     /** 盖过根的 spec(`http/execution-context.ts` `stampSpecRoot` 是唯一写者):`sessionId` 恒在 = 这次提交的根会话。 */
     spec: RootedTaskSpec;
@@ -171,6 +167,11 @@ export interface PreparedTaskSubmission {
      * 不经提交门的内部车道(`/decide` 的宿主新 turn)铸一只不带标题器的座:不起标题。
      */
     acceptance: import("../run-acceptance.js").RunAcceptance;
+    /**
+     * 这次提交的**出口座**(`submission-exit.ts`):提交门在授权之前铸,授权器登记新行时把候选交给它、受理座挂在它上面。三条提交腿认领赢时交本次 run、
+     * 交出查询责任时标 record,终局应答经 `seat.deliverTerminal` 写,在自己的路径上、终局应答之前 `seat.close()` —— 被拒的提交铸下的会话在应答发出之前撤回。
+     */
+    seat: import("../submission-exit.js").SubmissionSeat;
     /**
      * 这次装配的**宿主租约**:受理漏斗在装配之前开(`peerDesk.lease("fresh")`),装配在它之下登记交给引擎的对端声明;漏斗成功即把它交到这里 ——
      * 拿到本产物的那只函数紧接着写 `try { … } finally { prepared.peerLease.release() }`,其后每个出口(早退、合流败方、建行拒、驱动返回)按构造都放。
@@ -291,6 +292,11 @@ export interface DriveResumeArgs {
         sessionId: string;
         ctx: CheckpointCtx;
     };
+    /**
+     * 判官判本引擎续不了这条腿要续的那张卡时,这张卡的出路(`resume-legs.ts` 的 `rowWayOutOf`;判 `ok` / 说不出 ⇒ 缺席)。`/plan_review` 与 `/resume` 在驱动前对载入行求它;
+     * catch 臂在引擎的拒留卡 pending(处置 `retriable`)时把它作 `wayOut` 加进拒体 —— 引擎的拒原样不改(码、`field`、`blockedBy`、`thrownName`、诊断都在)。
+     */
+    rowWayOut?: RowWayOut;
     /**
      * 这条续跑的**宿主租约**(续跑漏斗 `resolveResumeSpecOrBlocked` 开、装配在它之下登记对端声明;调用方作用域的 `finally` 放)。
      * 驱动腿经 `heldFor(args.peerLease, () => driveResumeLeg(…))` 自持一只:受理早回的那一形里,腿活过调用方作用域,自己落定才放。
@@ -302,7 +308,8 @@ export interface DriveResumeArgs {
     /** 这条腿的部署事实(`leg-facts.ts`):续跑漏斗在复制之前读出的那一份(与 {@link PreparedTaskSubmission.legFacts} 同一律)。读者 = 本腿的 `wiring_manifest.skills` 段与会话行记录座。 */
     legFacts: import("../leg-facts.js").LegFacts | undefined;
     sessionId: string;
-    principal: string | undefined;
+    /** 卡属主的**主体**(分区键;`decodeCheckpointScope(cp.scope)` 恢复):ALS 与行属主读它,付费方两道门读它背后的人(`personOf`)。 */
+    subject: string | undefined;
     fleetScope: string;
     taskConfig: Omit<TaskSpec, "objective" | "sessionId">;
     resumeObjective: string;
@@ -313,7 +320,8 @@ export interface DriveResumeArgs {
      * 它只是分类:位由受理点与终局体两个边界按它铸,从不只凭这一句声明铸;缺席的取消出口(`checkpoint.resume_aborted` / 抛出臂)不铸。
      */
     commitment: GateCommitment;
-    verifyRounds: VerifyRoundsSpec | undefined;
+    /** 续跑腿接着跑哪一只组合入口(verify 验证门 / cascade 梯子;缺席 = 普通腿);读法的唯一属主 = `resume-composition.ts`。 */
+    composition: import("./resume-composition.js").ResumeComposition | undefined;
     /**
      * **R-1**(车CJ 收车档 §10 R-1;[ref] 批落地)—— 本条 resume 腿**装配期**铸下的用户面通告
      * (`PreparedTaskSubmission.engineNotices` 的 resume 孪生;今天唯一一族:`mcp.injection_dropped`)。
@@ -356,7 +364,7 @@ export interface DriveResumeArgs {
      *  markResuming CAS(409 `conflict.not_resumable`)、pre-CAS CheckpointError(绑定不符 409 /
      *  卡不在 404)。异步化的只有模型往返段。
      *
-     *  ⚠️ **verify 腿(`verifyRounds` 在场)不受本位影响**:core 的 `resumeWithVerification` 是一次整包
+     *  ⚠️ **组合腿(`composition` 在场:verify / cascade)不受本位影响**:core 的 `resumeWithVerification` 是一次整包
      *  await,没有「CAS 已过、模型还没跑」这个缝可停 —— 在那条臂上提前受理就等于把绑定判别也异步化了
      *  (那是决策证明的一部分,不能丢)。故它维持同步长调用形,如实登记在 CHANGELOG/契约文档。
      *
@@ -468,10 +476,7 @@ export interface RouteLegs {
     acceptEarly?: boolean, 
     /** [ref]:调用方已验身份的裁定 —— stale 臂铸 `currentPending` 指路键前在被读回的行上重跑 decide 门
      *  同一属主判(缺席 ⇒ 恒不造键;判据属主=server.ts 铸键点注)。 */
-    decider?: {
-        principal?: string;
-        explicitOperator: boolean;
-    }, 
+    decider?: KeyCaller, 
     /** 续跑请求的重述键(`mcpServers` / `a2aPeers`),门读出并判过的那一份;缺席 = 冻结读法。语义属主 = `resume-restatement.ts` 顶注。 */
     restatement?: ResumeRestatement): Promise<ResumeCheckpointOutcome>;
     /** 全 resume 家族的共同下半场(lease admission + 写 run log + fleet 发布)。 */
@@ -482,16 +487,13 @@ export interface RouteLegs {
     acceptEarly?: boolean, 
     /** [ref]②([ref]):调用方已验身份的裁定 —— 腿内在被真正载入的 checkpoint 行上重跑属主判
      *  ([ref] R3 同形;缺席 = 匿名 dev 部署,不咬)。 */
-    decider?: {
-        principal?: string;
-        explicitOperator: boolean;
-    }, 
+    decider?: KeyCaller, 
     /** 续跑请求的重述键(同 {@link RouteLegs.resumeCheckpoint} 末参)。 */
     restatement?: ResumeRestatement): Promise<ResumeLegOutcome>;
     /** notify-wake 域:唤醒一条 parked checkpoint。 */
     resumeWake(sessionId: string, 
     /** 续跑首轮那段话连同框架位,由文本出处在铸点定好(HTTP `/wake` 正文 ⇒ `trusted: false`);语义属主 = `resume-legs.ts` 同名形参顶注。 */
-    message: PendingSteerInput | undefined, caller: string | undefined, req: IncomingMessage | undefined, 
+    message: PendingSteerInput | undefined, caller: Subject | undefined, req: IncomingMessage | undefined, 
     /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/wake` 腿传 `true`
      *  —— 本腿走 `mintFreshRun`,受理体里的 `taskId` 因此是**新铸的**那个(壳的 poll 锚)。 */
     acceptEarly?: boolean, 
@@ -515,10 +517,7 @@ export interface RouteLegs {
     }, 
     /** [ref]②([ref]):调用方已验身份的裁定(直连门 = HMAC 验出的 principal)—— 属主轻读与行级属主复核
      *  ([ref] R3 同形;缺席 = 匿名 dev 部署,不咬)。 */
-    decider?: {
-        principal?: string;
-        explicitOperator: boolean;
-    }, 
+    decider?: KeyCaller, 
     /** [ref]:决断方看到的那道门(决断体的 `checkpointId`);不是当前门 ⇒ `409 approval_stale`(`approval_stale` 律,语义属主 = `resume-legs.ts` 的同名形参顶注)。 */
     sighting?: GateSighting, 
     /** 续跑请求的重述键(同 {@link RouteLegs.resumeCheckpoint} 末参):盖在这一次 ctx 读上,存体预判按盖过的体判。 */
@@ -783,7 +782,7 @@ export declare const RUN_NOT_FOUND_MESSAGE = "run not found \u2014 the id belong
  *
  * 为什么是常量不是各点字面量:这句话要在**每一个**会话面的「不存在」臂与「非属主」臂上逐字节同串(G52 [ref] /
  * [ref] —— 两臂差一个码或一个字就是单端点内的存在性 oracle)。十余个出站点各抄一份,漂开的那天没有任何东西会说话;
- * 走一只常量 + `runOwnerOk(..., "session")` 的会话拼法,「改一处」就是改全域。
+ * 走一只常量 + `admitRunRow(..., "session")` 的会话拼法,「改一处」就是改全域。
  */
 export declare const SESSION_NOT_FOUND_MESSAGE = "session not found";
 /** [ref] 前缀=域判别子既成契约:a\* 与 wa\* 形 id 给任务句柄读腿 / journal 指路;其余给 {@link RUN_NOT_FOUND_MESSAGE}。 */

package/dist/http/routes/a2a-serve.d.ts

@@ -1,8 +1,10 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { A2ATaskState } from "@sema-agent/core";
-import type { A2aServeConfig } from "../../config-types.js";
+import type { A2aServeConfig, A2aServeSkill } from "../../config-types.js";
 import { type RunRecord } from "../../plugins/store-contracts.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
+import type { RunStore } from "../../plugins/store-backend.js";
+import type { Person } from "../../owner-brands.js";
 /** 本实现说的 A2A 协议版本 —— 卡的 `protocolVersion` 与每条 RPC 响应的 `a2a-version` 头同源(单点)。 */
 export declare const A2A_PROTOCOL_VERSION = "1.0";
 /** 版本头名。**读**请求侧的它只是诊断材料(开集容忍:认识与否都照常答),**写**响应侧的它是我们自报
@@ -15,17 +17,38 @@ interface A2aCardSkill {
     name: string;
     description?: string;
 }
-/** A2A AgentCard 的 server 铸面。**具名字段 + 允许未来 additive**(设计稿 §4-5 数据形扩展槽)。 */
+/** A2A AgentCard 的 server 铸面 —— **sema 方言**:字段族是 A2A v0.3 的(顶层 `url` + `preferredTransport`,方法名 v0.3 拼法),
+ *  标签 `protocolVersion: "1.0"` 跟随 core 客户端腿;**不是**完整的 v0.3 AgentCard(v0.3 要的 `version` / `capabilities` /
+ *  `defaultInputModes` / `defaultOutputModes` / 技能 `tags` / `securitySchemes` 本卡都没有 —— 已声明的方言差异,契约附录 C.1 列全)。
+ *  **具名字段 + 允许未来 additive**(设计稿 §4-5 数据形扩展槽)。公开卡与扩展卡**同形**,只差 `skills` 的过滤。 */
 interface A2aAgentCard {
     name: string;
     description?: string;
     protocolVersion: string;
     url: string;
     preferredTransport: "JSONRPC";
+    /** 扩展卡方法在不在方法表里(**派生**,不是常量也不是配置)⇒ 与配没配 `audience` 无关:匿名读者从卡上读不出「这里有隐藏技能」。 */
+    supportsAuthenticatedExtendedCard: boolean;
     skills: A2aCardSkill[];
 }
-/** 配置 → 卡(纯投影,零 I/O、零存量读)。`build*`:返回纯数据。 */
-export declare function buildAgentCard(serve: A2aServeConfig): A2aAgentCard;
+/** (配置, 这次请求验过的人, 方法表) → 卡(纯投影,零 I/O、零存量读)。`build*`:返回纯数据。
+ *  `reader` 缺席 = 公开卡;在场 = 扩展卡(按 {@link skillsOfferedTo} 过滤)。旗读方法表(调用点恒传 {@link A2A_METHODS})。 */
+export declare function buildAgentCard(serve: A2aServeConfig, reader: Person | undefined, methods: ReadonlyMap<string, A2aMethodHandler>): A2aAgentCard;
+/** sema 方言扩展卡的方法名(A2A v0.3 §7.10 的拼法,与 `message/send` / `tasks/get` 同一方言;不加 1.0 别名 —— 一种方言一个名字)。 */
+export declare const EXTENDED_CARD_METHOD = "agent/getAuthenticatedExtendedCard";
+/**
+ * 🔴 **发布规则(唯一谓词)**:提供给 `reader` 的技能 = 没写 `audience` 的技能 ∪ `audience` 含这个人的技能(声明序,只滤不排)。
+ * 三处同读 —— 公开卡(`reader` 缺席)、扩展卡、`message/send` 的 `sema.skillId` 选择 ⇒ **看得见 ⇔ 点得中**;本文件读
+ * `serve.skills` 的只有这一处。
+ *
+ * **发布 ≠ 授权**:它决定这条技能对谁公告、谁能按 id 点名,**不**决定谁能跑它背后的场景。场景的唯一授权门是场景门
+ * (中心白名单,只在接了中心时存在);不读技能的入口(不带 `sema.skillId` 走指派链 / 映射到同一场景的公开技能 /
+ * 原生提交族 `POST /v1/runs` · `POST /v1/tasks` · `POST /v1/tasks/stream` 体里的 `scenario`)都不经过本谓词。
+ *
+ * 形参收**验过的人**那只品牌:只带 service 凭据(含代部署本人)的请求没有人 ⇒ 只得公开技能;fleet 资格与运维名册**不**扩大投影 ——
+ * 这里不读它们,运维照他自己这个人投影(运维不提权、fleet 不算)。
+ */
+export declare function skillsOfferedTo(serve: A2aServeConfig, reader: Person | undefined): readonly A2aServeSkill[];
 /**
  * 域入口①:公开发现面。**位置即契约** —— 必须挂在 `server.ts` 的全局 service-credential 门**之前**
  * (R-11「公网匿名可发现」;挂在门后等于要凭据才能发现,协商第一步就断)。
@@ -55,7 +78,22 @@ export declare const A2A_TASK_NOT_FOUND_MESSAGE = "task not found";
  * 而那个决议走的是持久审批口、不是一条回信 —— 与 core 对自己 `parked` 行的裁词同源。A2A 调用方因此
  * **不能**靠再发一条 message 解开它(附录 C.3 的表里成文写着这句)。
  */
-export declare function a2aStateForRun(run: Pick<RunRecord, "status" | "errorCode">, stale: boolean): A2ATaskState;
+export declare function a2aStateForRun(run: Pick<RunRecord, "status" | "errorCode">): A2ATaskState;
+/** 一个方法处理器。返回 `result`(被包进 JSON-RPC 成功体)、返回 `undefined`(= 已自行应答)或抛 {@link RpcError}。 */
+type A2aMethodHandler = (args: {
+    req: IncomingMessage;
+    res: ServerResponse;
+    ctx: RouteCtx;
+    params: Record<string, unknown>;
+    serve: A2aServeConfig;
+    /** 事实 `a2aServe` 的见证:两只方法都站在这只 durable run 店上(无店 ⇒ 路由层已 404,走不到方法)。 */
+    runStore: RunStore;
+}) => Promise<unknown>;
+/**
+ * 技能选择拒句(**常量**,零技能 id):点名一条没声明的技能与点名一条没发布给你的技能,拒体逐字节相同 —— 同一个 throw 点、同一句话。
+ * 回显输入的 id 会把「这个 id 在这台部署上有没有含义」交给调用方比对(拼错的调用方看不到回显:它能看的技能名单就在它拉得到的卡上)。
+ */
+export declare const A2A_UNOFFERED_SKILL_MESSAGE = "unknown skill id \u2014 params.message.metadata[\"sema.skillId\"] does not name a skill offered to this caller; the skills a caller can name are the ones on the agent card it can read (the public card, or the authenticated extended card)";
 /**
  * 域入口②:JSON-RPC 端点。**位置即契约** —— 挂在全局 service-credential 门**之后**(R-11「持服务凭据
  * 才可调」),且在 drain / model-roster-pending 两道 503 门之后(`/v1/a2a` 进 `isBillableSubmitPath`:

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

@@ -6,25 +6,33 @@ import { HttpError } from "../../security.js";
 import { idemCallerOf, idemIdentityOf, idemKeyOf, inflightKeyOf } from "../idempotency.js";
 import { isRunExistsConflictBody, replayOfExistingRun } from "../submit-replay.js";
 import { isActiveRunConflictBody } from "../active-run-conflict.js";
-import { sendJson, sendError } from "../send.js";
+import { sendJson, sendError, sendHttpError } from "../send.js";
 import { admissionRefusalOf, readinessOf, sendBillableRefusal } from "../readiness.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
-import { readOwnedRun } from "../owner-access.js";
+import { gatedPerson, gatedSubject, sendPrincipalRefusal, verifiedIdentitySource } from "../principal-gate.js";
+import { callerOf, protocolEntry, readVisibleRun, runRowAt } from "../owner-access.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { createDurableRun } from "./runs.js";
 export const A2A_PROTOCOL_VERSION = "1.0";
 export const A2A_VERSION_HEADER = "a2a-version";
-export function buildAgentCard(serve) {
+export function buildAgentCard(serve, reader, methods) {
     return {
         name: serve.name,
         ...(serve.description !== undefined ? { description: serve.description } : {}),
         protocolVersion: A2A_PROTOCOL_VERSION,
         url: serve.url,
         preferredTransport: "JSONRPC",
-        skills: serve.skills.map((s) => ({ id: s.id, name: s.name ?? s.id, ...(s.description !== undefined ? { description: s.description } : {}) })),
+        supportsAuthenticatedExtendedCard: methods.has(EXTENDED_CARD_METHOD),
+        skills: skillsOfferedTo(serve, reader).map((s) => ({ id: s.id, name: s.name ?? s.id, ...(s.description !== undefined ? { description: s.description } : {}) })),
     };
 }
+export const EXTENDED_CARD_METHOD = "agent/getAuthenticatedExtendedCard";
+export function skillsOfferedTo(serve, reader) {
+    return serve.skills.filter((s) => s.audience === undefined || (reader !== undefined && s.audience.includes(reader)));
+}
+function cardReaderOf(req, config) {
+    return verifiedIdentitySource(req, config) === undefined ? undefined : gatedPerson(req, config);
+}
 export async function handleA2aServe(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
@@ -35,7 +43,7 @@ export async function handleA2aServe(req, res, match, ctx) {
                 return;
             }
             res.setHeader(A2A_VERSION_HEADER, A2A_PROTOCOL_VERSION);
-            sendJson(res, 200, buildAgentCard(peer.serve));
+            sendJson(res, 200, buildAgentCard(peer.serve, undefined, A2A_METHODS));
             return;
         }
         default:
@@ -58,9 +66,7 @@ const A2A_STATE_BY_RUN_STATUS = {
     suspended: null,
     needs_review: null,
 };
-export function a2aStateForRun(run, stale) {
-    if (stale)
-        return "failed";
+export function a2aStateForRun(run) {
     if (isParkedRunStatus(run.status))
         return "input-required";
     const mapped = A2A_STATE_BY_RUN_STATUS[run.status];
@@ -91,8 +97,8 @@ function statusTextForRun(run, state) {
         return memo("errorMessage", runPlaneMessage);
     return undefined;
 }
-function taskFromRun(run, stale) {
-    const state = a2aStateForRun(run, stale);
+function taskFromRun(run) {
+    const state = a2aStateForRun(run);
     const text = statusTextForRun(run, state);
     return {
         kind: "task",
@@ -153,7 +159,8 @@ function objectiveFromParts(parts) {
     return objective;
 }
 const SKILL_METADATA_KEY = "sema.skillId";
-function skillFromMetadata(metadata, serve) {
+export const A2A_UNOFFERED_SKILL_MESSAGE = `unknown skill id — params.message.metadata["${SKILL_METADATA_KEY}"] does not name a skill offered to this caller; the skills a caller can name are the ones on the agent card it can read (the public card, or the authenticated extended card)`;
+function skillFromMetadata(metadata, serve, reader) {
     if (metadata === undefined || metadata === null)
         return undefined;
     const meta = asRecord(metadata, "params.message.metadata");
@@ -161,15 +168,14 @@ function skillFromMetadata(metadata, serve) {
     if (raw === undefined)
         return undefined;
     const id = asNonEmptyString(raw, `params.message.metadata["${SKILL_METADATA_KEY}"]`, MAX_SKILL_ID_CHARS);
-    const skill = serve.skills.find((s) => s.id === id);
+    const skill = skillsOfferedTo(serve, reader).find((s) => s.id === id);
     if (!skill)
-        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`);
+        throw new RpcError(JSONRPC_INVALID_PARAMS, A2A_UNOFFERED_SKILL_MESSAGE);
     return skill;
 }
-function rpcErrorFromTypedFailure(err, skillId) {
-    const where = skillId !== undefined ? `skill ${JSON.stringify(skillId)}` : "this request";
+function rpcErrorFromTypedFailure(err) {
     if (err.status >= 400 && err.status < 500) {
-        return new RpcError(JSONRPC_INVALID_PARAMS, `the serving deployment refused this submission for ${where} (its configuration does not currently admit it); the operator's logs carry the reason`);
+        return new RpcError(JSONRPC_INVALID_PARAMS, "the serving deployment refused this request (its configuration does not currently admit it); the operator's logs carry the reason");
     }
     return new RpcError(JSONRPC_INTERNAL_ERROR, "internal error");
 }
@@ -191,9 +197,6 @@ function readBlocking(params) {
         throw new RpcError(JSONRPC_INVALID_PARAMS, "params.configuration.blocking must be a boolean");
     return c.blocking;
 }
-function isStaleRun(run, runStaleSec) {
-    return run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > runStaleSec * 1000;
-}
 async function waitForRun(ctx, store, res, taskId, budgetMs) {
     const { deps } = ctx;
     const deadline = Date.now() + budgetMs;
@@ -201,14 +204,15 @@ async function waitForRun(ctx, store, res, taskId, budgetMs) {
     for (;;) {
         let run;
         try {
-            run = (await store.getRun(taskId)) ?? null;
+            const raw = await store.getRun(taskId);
+            run = raw ? await runRowAt("run.a2a", store, raw) : null;
         }
         catch (e) {
             deps.logger?.warn?.("a2a_serve_wait_read_failed", { error: e?.message });
             return last;
         }
         last = run ?? last;
-        if (run && a2aStateForRun(run, isStaleRun(run, deps.config.runStaleSec)) !== "working")
+        if (run && a2aStateForRun(run) !== "working")
             return run;
         const left = deadline - Date.now();
         if (left <= 0)
@@ -231,7 +235,7 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
     const objective = objectiveFromParts(message.parts);
     const contextId = message.contextId === undefined ? undefined : asString(message.contextId, "params.message.contextId");
     const messageId = asNonEmptyString(message.messageId, "params.message.messageId", MAX_MESSAGE_ID_CHARS);
-    const skill = skillFromMetadata(message.metadata, serve);
+    const skill = skillFromMetadata(message.metadata, serve, cardReaderOf(req, deps.config));
     const skillId = skill?.id;
     const scenario = skill?.scenario;
     const blocking = readBlocking(params);
@@ -242,7 +246,7 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
         .update(contextId ?? "").update("\x1f")
         .update(skillId ?? "")
         .digest("hex");
-    const submitter = gatedPrincipal(req, deps.config);
+    const submitter = gatedSubject(req, deps.config);
     const idem = { key: idemKeyOf(fingerprint, caller, "run"), bodyFingerprint: fingerprint };
     const body = {
         objective,
@@ -251,9 +255,9 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
         ...(scenario !== undefined ? { scenario } : {}),
     };
     const keyed = (await runStore.getRunByIdem(idem.key).catch(() => undefined)) ?? (await runStore.getRun(body.taskId).catch(() => undefined));
-    const replay = keyed ? await replayOfExistingRun(keyed, { principal: submitter, clientTaskId: body.taskId, idem }, "durable", deps, runStore) : undefined;
+    const replay = keyed ? await replayOfExistingRun(keyed, { subject: submitter, clientTaskId: body.taskId, idem }, "durable", deps, runStore) : undefined;
     if (keyed && replay?.status === 202) {
-        return taskFromRun(keyed, isStaleRun(keyed, deps.config.runStaleSec));
+        return taskFromRun(await runRowAt("run.a2a", runStore, keyed));
     }
     const inflight = replay === undefined ? ctx.registry.idemCache.peek(inflightKeyOf(idem, "durable", body.taskId)) : undefined;
     let receipt;
@@ -273,8 +277,10 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
             typed = e;
         });
         if (!prepared) {
-            if (typed)
-                throw rpcErrorFromTypedFailure(typed, skillId);
+            if (typed) {
+                deps.logger?.warn?.("a2a_serve_submission_refused", { status: typed.status, ...(typed.code !== undefined ? { errorCode: typed.code } : {}) });
+                throw rpcErrorFromTypedFailure(typed);
+            }
             return undefined;
         }
         try {
@@ -294,7 +300,7 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
     const sessionId = receiptBody.sessionId;
     const run = await waitForRun(ctx, runStore, res, taskId, blocking ? serve.blockingWaitMs : 0);
     if (run)
-        return taskFromRun(run, isStaleRun(run, deps.config.runStaleSec));
+        return taskFromRun(run);
     return {
         kind: "task",
         id: taskId,
@@ -305,6 +311,8 @@ async function handleMessageSend({ req, res, ctx, params, serve, runStore }) {
 function rpcErrorFromRefusedReceipt(receipt) {
     const code = receipt.body?.errorCode;
     const head = `the serving deployment did not accept this submission (it answered ${receipt.status}${typeof code === "string" ? ` ${code}` : ""})`;
+    if (receipt.status >= 500)
+        return new RpcError(JSONRPC_INTERNAL_ERROR, `${head}; the failure is on the serving side and nothing was started, so the same message can be sent again later`);
     if (isActiveRunConflictBody(receipt.body))
         return new RpcError(JSONRPC_INVALID_PARAMS, `${head}; a session already running a turn must finish or be cancelled before the next message on the same contextId`);
     if (isRunExistsConflictBody(receipt.body))
@@ -322,15 +330,19 @@ function durableIdempotencyTaskId(scope, messageId) {
 async function handleTasksGet({ req, ctx, params, runStore }) {
     const { deps } = ctx;
     const id = asNonEmptyString(params.id, "params.id", MAX_TASK_ID_CHARS);
-    const run = await readOwnedRun(deps.config, runStore, gatedPrincipal(req, deps.config), id, "owner");
+    const run = await readVisibleRun(protocolEntry(req, deps, "run.a2a", callerOf(req, deps)), runStore, id);
     if (!run)
         throw new RpcError(A2A_TASK_NOT_FOUND, A2A_TASK_NOT_FOUND_MESSAGE);
-    return taskFromRun(run, isStaleRun(run, deps.config.runStaleSec));
+    return taskFromRun(run);
 }
-const A2A_METHODS = {
-    "message/send": handleMessageSend,
-    "tasks/get": handleTasksGet,
-};
+async function handleExtendedCard({ req, ctx, serve }) {
+    return buildAgentCard(serve, cardReaderOf(req, ctx.deps.config), A2A_METHODS);
+}
+const A2A_METHODS = new Map([
+    ["message/send", handleMessageSend],
+    ["tasks/get", handleTasksGet],
+    [EXTENDED_CARD_METHOD, handleExtendedCard],
+]);
 export async function handleA2a(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
@@ -347,7 +359,18 @@ export async function handleA2a(req, res, match, ctx) {
     const { serve, runStore } = peer;
     const requestedVersion = req.headers[A2A_VERSION_HEADER];
     res.setHeader(A2A_VERSION_HEADER, A2A_PROTOCOL_VERSION);
-    if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
+    let a2aSubject;
+    try {
+        a2aSubject = gatedSubject(req, deps.config);
+    }
+    catch (e) {
+        if (!(e instanceof HttpError))
+            throw e;
+        deps.metrics?.inc("a2a_serve_rejected_total", { reason: "identity_refused" });
+        sendHttpError(res, e);
+        return;
+    }
+    if (deps.config.requirePrincipal && !a2aSubject) {
         deps.metrics?.inc("a2a_serve_rejected_total", { reason: "principal_required" });
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -374,7 +397,7 @@ export async function handleA2a(req, res, match, ctx) {
         return;
     }
     const method = rpc.method;
-    const handler = A2A_METHODS[method];
+    const handler = A2A_METHODS.get(method);
     if (!handler) {
         deps.metrics?.inc("a2a_serve_rpc_total", { method: "(unknown)", outcome: "method_not_found" });
         deps.metrics?.inc("a2a_serve_rejected_total", { reason: "method_not_found" });

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

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import * as facts from "../../capability-facts.js";
 import { assertNever } from "../route-ctx.js";
 export const ADMIN_CONFIG_REFRESH_PATH = "/v1/admin/config/refresh";
@@ -8,7 +8,7 @@ export async function handleAdminConfigRefresh(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "admin-config-refresh": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;

package/dist/http/routes/admin-drain.js

@@ -1,6 +1,6 @@
 import { DRAIN_ACTION_ID, readDrainRequest } from "@sema-agent/settings-schema/fleet";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import * as facts from "../../capability-facts.js";
 import { fleetScopeOf } from "../../config-types.js";
 import { drainIdentityMismatches } from "../../fleet/drain-entry.js";
@@ -12,7 +12,7 @@ export async function handleAdminDrain(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "admin-drain": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;

package/dist/http/routes/admin-memory-optout.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { memoryOptOutPrincipalShapeProblem } from "../../plugins/memory-optout-grant-store-sql.js";
+import { PRINCIPAL_MAX_BYTES } from "../../principal-shape.js";
 export const ADMIN_MEMORY_OPTOUT_PATH = "/v1/admin/memory-optout";
 const PutBodySchema = z.object({ allow: z.boolean(), note: z.string().min(1).max(500).optional() }).strict();
 export async function handleMemoryOptOut(req, res, match, ctx) {
@@ -11,7 +12,7 @@ export async function handleMemoryOptOut(req, res, match, ctx) {
     const target = match.decl.id === "memory-optout-grants-list" || match.decl.id === "memory-optout-put-default"
         ? undefined
         : ctx.helpers.safeDecode(match.params.principal);
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -40,7 +41,7 @@ export async function handleMemoryOptOut(req, res, match, ctx) {
     }
     const store = fact.store;
     if (target !== undefined && (target === null || memoryOptOutPrincipalShapeProblem(target) !== undefined)) {
-        sendError(res, 400, "request.path_malformed", "invalid memory opt-out grant principal — the path segment must percent-decode to a non-empty principal of at most 190 chars with no leading/trailing whitespace or control characters (the deployment default row is addressed by PUT on the collection root, not by a path segment)");
+        sendError(res, 400, "request.path_malformed", `invalid memory opt-out grant principal — the path segment must percent-decode to a non-empty principal of at most ${PRINCIPAL_MAX_BYTES} UTF-8 bytes with no leading/trailing whitespace or control characters (the deployment default row is addressed by PUT on the collection root, not by a path segment)`);
         return;
     }
     switch (match.decl.id) {

package/dist/http/routes/adoption.d.ts

@@ -12,6 +12,9 @@
  *  · `adoption.destination_unrepresentable` (409):目的地身份装不进这次收编会**派生**出来的某个键
  *    (典型:memory 的 `proj:` 键 = 新 tenant 段 + 原有项目段后缀,合起来越过列宽)。与上一条分家的理由:
  *    运维的动作完全不同 —— 那条要去清理另一个 principal 的行,这条要换一个更短的目的地身份。
+ *  · `adoption.table_missing` (409):这个部署**接线了**某个可选存储面(记忆引擎 DB 后端 / 对象存储上的附件店),库上却没有它的表(表被人删了、或 boot 的建表没跑过)。
+ *    与前两条分家:那两条是**数据**事实、落永久终态;这条是**部署**事实 —— 弧不落终态(行停在 INTENT、零 UPDATE),补好表(重启一个副本,boot 会建缺的表)后**重发同一请求**即续。
+ *    **没接线的可选面不在此列**:缺省 file 记忆引擎 / 没配对象存储的部署上那些表本来就不存在,它们的腿不在回执里(`legs[]` 只列真跑的腿)。
  *  · `not_found.adoption` (404):operator 拿着一个不存在的 id 来读。
  *
  * 幂等:同参数重跑秒回**同一份** `AdoptionReceipt`(`immutableReport` 逐字节恒同 —— 它在 phase 6