@kanyun-ai-infra/agenthub 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.22.0
+
+本版的主线是 vault MCP 按目标限制工具（#5719）：`sessions.create` 可以对调用方 vault 里每个 remote MCP 目标声明允许的工具。同时，服务端以后新增的取值不再让调用失败：托管 MCP 与项目秘密的 `status` / `credentialState` 改为开放集合，`vaults.credentials.update` 会按原样返回 SDK 尚未建模的凭据类型。本版还包含 1.21.0 之后合入的托管 MCP 会话身份校验、定时任务的 webhook 目标与 `sessions:terminate` 签发规则调整。
+
+### 新增（主入口）
+
+- `sessions.create` 的可选 `vault_mcp_bindings`（#5719）：形如 `[{ vaultId: "vlt_…", targetUrl, tools: ["search"] }]`，限制会话里该 vault 在 `targetUrl` 上的 remote MCP 只能调用 `tools` 中的工具；`tools: []` 表示该目标一个工具都不能调。每个 `vaultId` 必须同时出现在 `vault_ids` 里，否则 SDK 在发请求前拒绝。只对 `managed_agent` 会话生效，策略在建会话时冻结，之后改 agent 定义不影响已建会话。服务端拒绝码：400 `SESSION_VAULT_MCP_TARGET_NOT_FOUND`（该 vault 在此地址没有可用凭据）、409 `SESSION_VAULT_MCP_TARGET_CONFLICT`（同一地址被另一个绑定的 vault 或托管 MCP 占用）、409 `VALIDATION_ERROR`（非 `managed_agent` 会话带了声明）。带非空 `vault_mcp_bindings` 的请求不走预热池。同一 `idempotencyKey` 换了声明会回 `IDEMPOTENCY_REPLAY_MISMATCH`。服务端须部署 #5719 D2b 才接受该字段；模型侧只看到允许的工具需要部署 D3a（#5795），未部署时 gateway 仍按冻结策略拦截越权调用。
+- `verifySessionIdentity(request, options)`（#5728）：托管 MCP 的上游服务用它校验平台签发的 `X-Pilot-Session-Identity`，公钥取自平台公开 JWKS。用法与缓存规则见 README「验证托管 MCP 会话身份」。新导出类型 `SessionIdentityClaims`、`SessionIdentityJwksSource`、`SessionIdentityRejection`、`SessionIdentityVerificationOptions`。
+- 托管 MCP 的 `sessionIdentity: "off" | "signed"`（#5728）：`managedMcps.create` / `update` 可设，记录上返回。只有项目管理员能写，否则 403 `managed_mcp_session_identity_requires_manager`；只对 `remote` 生效，给 `stdio` 设置返回 400 `managed_mcp_session_identity_requires_gateway`。
+- 托管 MCP 与项目秘密的「值待填」状态（#5740）：记录上新增可选 `credentialState`（`pending` / `ready`），`status` 新增 `pending_credential`；托管 MCP 记录另有 `pendingFields`，只列出仍缺的必填字段名，不含值。秘密记录新增可选 `status`（`active` / `pending_credential` / `archived`）。
+- 定时任务的 `targetKind: "webhook"`（#5721）：到点时向订阅了 `schedule.fired` 的 webhook 投递事件，不起会话。trigger 与 `runNow` 的响应用 `dispatchedWebhookEventId` 标识这次投递。新失败原因 `WEBHOOK_DELIVERY_FAILED`、`WEBHOOK_SUBSCRIBER_REQUIRED`、`SCHEDULE_OUT_OF_WINDOW`。webhook 订阅可选事件类型 `schedule.fired`。
+- 冻结的 agent 插件（#5765）：`workloads.create` 的 `version.managedAgentProfileSnapshot` 与 `workloads.publishRevision` 的 `managedAgentProfileSnapshot` 新增可选 `plugins`（`[{ name, version, integrity }]`，按顺序记录锁定的 npm 插件身份），workload 与 revision 的读面返回同名可选字段。
+- `bindings.bindProjectRepo` 的返回新增可选 `warning`（#5686）：绑定已落库，但仓库索引或 GitLab push / merge hook 没有接上，push 暂时不会触发流水线；用同样的请求重跑是幂等的，会重试接线。没有该字段表示接线完整。
+
+### 行为变化
+
+- `managedMcps` 与 `secrets` 返回的 `status`、`credentialState` 是开放集合（#5719 D3b）。SDK 不认识的值按原字符串返回，不再抛 `ZodError`；非字符串仍然报错。类型是 `ManagedMcpStatus | (string & {})` 这类联合，原有字面量的补全保留。
+- `vaults.credentials.update` 的返回类型改为 `VaultCredentialRecord | UnknownVaultCredentialRecord`（#5815）。服务端新增的凭据类型（如 `net_secret`）在 `update` 后按服务端原样返回，不再在写入已经生效后抛 `ZodError`；已知类型的行格式不对仍然报错。新导出守卫 `isKnownVaultCredential(row)` 和类型 `UnknownVaultCredentialRecord`。`create` 只发 SDK 已建模的类型（mcp、`git_token`），返回仍按这些类型严格解析；`net_secret` 等新类型在 SDK 建模之前走 `update` 透传。SDK 没有 `credentials.list` / `get`，所以只有 `update` 受影响。
+- `sessions:terminate` 不再只限管理员签发（#5688）：任何用户都可以在 `custom` token 上勾选它，它不进任何预设；终止会话仍受会话所属项目的范围限制。
+
+### 随包文档
+
+- `SKILL.md`：补 `vault_mcp_bindings` 与开放集合的读法（#5719 D3b）、`update` 返回未建模凭据时先调 `isKnownVaultCredential`（#5815）、「Verify managed MCP session identity」一节（#5728）；「Revisiting a session」里重建上文的长度上限改为每条用户消息 64,000 字符、每条 agent 回复 8,000、合计 96,000（#5665，服务端行为）。随包 skill 版本由 0.30.1 升至 0.31.1。
+- `README.md`：新增「按目标限制 vault MCP 的工具」（#5719 D3b）与「验证托管 MCP 会话身份」（#5728）两节。
+
+### 迁移说明
+
+- **类型层面的小破坏**（#5815）：`vaults.credentials.update` 的返回类型多了开放的一臂，`row.authType === "git_token"` 不再能直接把 `row` 窄化成 git 记录。迁移写法是先 `if (isKnownVaultCredential(row))`，在守卫里面再按 `authType` 窄化。
+- 对 `status` / `credentialState` 写穷举 `switch` 的代码要加 `default` 分支，未知值按「暂不可用」处理（#5719 D3b）。
+- 闭集枚举新增成员（#5721）：`WebhookEventType` 加了 `schedule.fired`，定时任务的 `targetKind` 加了 `webhook`。对它们写了穷举 `switch`（`never` 兜底）的代码升级后编译报错，需要补这两个分支。
+- 以下类型改由 SDK 自己声明，字段与 main 上的契约相同，只是服务端契约以后变化时 SDK 不跟着变：`ManagedMcpRecord`、`ListManagedMcpsPlatformResponse`、`SecretRecord`、`SecretListItem`（放宽了 `status` / `credentialState`，#5719 D3b）；`CreateCredentialRequest`、`VaultCredentialRecord`（只含 SDK 已建模的凭据类型，#5815）。
+- 旧版本的风险：1.21.0 的 `managedMcps.list` / `get` / `create` / `update` 只认 `active` / `retiring` / `archived`，项目里只要有一条 `pending_credential` 的托管 MCP，`list` 整页抛 `ZodError`；1.21.0 的 `secrets` 会剥掉不认识的 `status` 字段，不抛错。用到 `managedMcps` 的调用方应在服务端开始返回 `pending_credential` 之前升级到 1.22.0。1.21.0 的 `vaults.credentials.update` 遇到服务端新增的凭据类型会在写入生效后抛 `ZodError`。
+- 1.21.0 的 `bindings.bindProjectRepo` 响应 schema 是 strict，服务端返回带 `warning` 的响应时抛 `ZodError`。这只发生在接线失败的分支，绑定其实已经落库。1.21.0 的 workload / revision 读面会剥掉 `plugins`，不抛错；请求里不能带 `plugins`。
+
 ## 1.21.0
 
 AgentHub 组（spec `agenthub-groups.md` §6.3）要求 SDK 先发：服务端在项目与环境响应里返回组字段之前，调用方先换上能解析这些字段的 SDK。本版同时带上 1.20.0 之后合入的项目秘密、定时任务、托管 MCP、模型服务写入，以及 `sessions.listEvents` 的事件过滤和回合的续接信号 `Turn.continuation`。默认 User-Agent 改为带真实包版本。

package/README.md

@@ -265,6 +265,28 @@ https://octopus.zhenguanyu.com/#/trace-explorer?env=<test|online>&time=<起-止,
 一个绝对时间窗（ms，通常取该轮 `dispatchedAt` 前后各 1 小时）；`traceExplorerQuery`
 是 `trace_id = <traceId>` 整体 URL-encoded 后的结果。
 
+## 按目标限制 vault MCP 的工具
+
+`sessions.create` 传 `vault_ids` 时，可以再传 `vault_mcp_bindings`，限制会话在某个 vault 的某个 remote MCP 地址上能调用哪些工具，只对 `managed_agent` 会话生效：
+
+```ts
+await agenthub.sessions.create({
+  projectId,
+  agentId,
+  vault_ids: ["vlt_…"],
+  vault_mcp_bindings: [
+    { vaultId: "vlt_…", targetUrl: "https://docs.example.com/mcp", tools: ["search"] },
+  ],
+});
+```
+
+- 每个 `vaultId` 都必须出现在 `vault_ids` 里，否则 SDK 在发请求前拒绝。
+- `tools: []` 表示该地址上一个工具都不能调。
+- 策略在建会话时冻结，之后改 agent 定义不影响已建会话。
+- 该 vault 在此地址没有可用凭据时 400 `SESSION_VAULT_MCP_TARGET_NOT_FOUND`；地址已被另一个绑定的 vault 或托管 MCP 占用时 409 `SESSION_VAULT_MCP_TARGET_CONFLICT`。
+
+托管 MCP 与项目秘密记录上的 `status` / `credentialState` 是开放集合：服务端新增、本 SDK 还不认识的值按原字符串返回，不抛错。对它们做 `switch` 时加 `default` 分支，按「暂不可用」处理。
+
 ## 完整参考
 
 下面这些内容日常写业务代码用不到，需要时查
@@ -431,3 +453,14 @@ try {
 ### 摘要与按需详情
 
 服务启用 Turn wire 版本 2 后，用 `sessions.turns.listSummaries` 轮询轻量摘要，按需调用 `getMetadata`、`listParts`、`getPartContent`。`listParts({ fromOrdinal })` 支持直接定位尾部；正文变化返回 `TURN_CONTENT_CHANGED`，应丢弃未完成拼装后重新打开。`getComplete` 是显式全量拼装，只有 `allowLegacy: true` 才允许旧回合或截断 metadata 的完整读取。原 `list/get` 保持完整 Turn，不能把新摘要当旧 Turn 使用。
+
+
+## 验证托管 MCP 会话身份
+
+上游可用 `verifySessionIdentity(request, options)` 校验 `X-Pilot-Session-Identity`。`request.body` 必须是 JSON 解析前的原始字节；`request.url` 是登记给平台的完整规范 URL（含 query），不要从反向代理改写后的 Host 推导。
+
+`options.issuer` 与 `options.keys.jwksUrl` 由上游成对配置，JWKS URL 只接受 HTTPS，不从请求头或 token 推导。复用同一个 `keys` 对象以共享公钥缓存；缓存不超过端点 max-age、调用方上限与 600 秒，扣除响应 Age。未知 kid 最多每 30 秒触发一次提前刷新，刷新失败返回 `keys_unavailable`，不使用过期缓存。JWKS 请求不跟随重定向。未知 kid 与刷新失败后的重试限频 30 秒；失败冷却内返回 keys_unavailable。已知 kid 的成功响应严格按 max-age 使用，no-store 不缓存，下一次请求重新拉取。过期公钥不复用（不做 stale-if-error）：这保证吊销窗口不超过缓存期，代价是 JWKS 不可用期间拒绝请求。JWKS 响应在读取过程中限制为 64 KiB，超限取消流。
+
+调用方必须实现 `isAudienceAllowed(aud)`，查询本上游接受的托管 MCP ID（重建退场期可能同时接受新旧 ID）；必须实现 `claimJti(jti, expiresAtSeconds)`，用跨实例共享的原子写登记 nonce，例如数据库唯一键或 Redis SET NX，直到绝对 Unix 秒时间戳到期。已登记返回 false。存储或回调异常会向上传播，上游应拒绝请求。
+
+返回 `ok: true` 后，还需按 `claims.sub` 查本地会话，并核对 `claims.project_id`。actor 字段只用于审计，不能授予权限。缺头、签名/请求绑定失败、过期、未知公钥和重放都返回 `ok: false` 及具体 reason；配置错误抛 TypeError。时钟容差默认 30 秒，允许降低，不允许增加。