@kanyun-ai-infra/agenthub 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.20.0
+
+### 新增（主入口）
+
+- `sessions.create` 的 `CreateSessionRequestInput` 与 `CreatePlatformSessionRequestSchema` 支持可选的 `pushBackPaths: string[]`，用于创建 Rondo 会话。与 `deliveryMode: "push_back"`、`repoUrl`、`repoRef` 配合使用；路径数组按原顺序发送，保留重复项，省略或传 `undefined` 时不输出该字段。Rondo 授权与 glob 规则由服务端校验，SDK 不另加路径校验。字段随共享请求契约引入（#5489），wire 回归测试及公开说明见 #5537。
+
+### 随包文档
+
+- Quickstart 按签发令牌、创建带初版的 agent、创建会话、发送回合四步组织，补充宿主接入前置条件、scope 和模型服务要求（#5504）。
+- `SKILL.md` 补充 Rondo 会话示例、路径范围与服务端前置条件；随包 skill 版本由 0.29.0 升至 0.29.2（#5504、#5537）。
+
+### 迁移说明
+
+- 相对 npm 1.19.0，公开导出名称不增不减；请求 schema 新增可选字段，已有调用方无需改代码。`realtime` 子入口的类型声明不变。需要 `pushBackPaths` 的调用方应升级到 1.20.0；1.19.0 会在发送请求前以未知字段拒绝它（#5489、#5537）。
+
+## 1.19.0
+
+宿主接入线（#5492）R0 的 SDK 面：新增 webhook 订阅、vault 与凭据、项目模型服务、项目级 agent 列表四个入口，`agents.create` 可以带初版定义一步出可跑版本，客户端可以声明代终端用户调用的归因用户。对导出面是纯增量，已有调用方不用改代码。
+
+### 新增（主入口）
+
+- `webhookSubscriptions`（`WebhookSubscriptionsResource`，scope `project:settings`）：出站 webhook 订阅的 `create`、`list`、`update`、`delete`、`rotateSecret`。平台在 run / session / turn 结束时向订阅地址 POST 一条只带 id 的签名事件（`turn.ended` 等），后端不必停在 `waitForTurn` 上等结果。签名密钥只在 `create` 与 `rotateSecret` 的返回里出现一次，之后读不回来；`rotateSecret` 立即切换，没有双密钥窗口；删除订阅会级联删除投递历史。同项目订阅数有上限，超出 409 `SUBSCRIPTION_LIMIT_EXCEEDED`；URL 过不了 SSRF 策略 400 `WEBHOOK_URL_FORBIDDEN`。新导出 `WebhookEventTypeSchema`、`WebhookEventPayloadSchema`、`WebhookSubscriptionSchema`、`WebhookSubscriptionWithSecretSchema`、`WebhookSubscriptionStatusSchema`、`WebhookSubscriptionErrorCodeSchema`、`CreateWebhookSubscriptionRequestSchema`、`UpdateWebhookSubscriptionRequestSchema`、`WEBHOOK_EVENT_TYPES`、`MAX_WEBHOOK_SUBSCRIPTIONS_PER_PROJECT`、`MAX_WEBHOOK_EVENT_ID_LENGTH`、`OUTBOUND_WEBHOOK_SIGNATURE_HEADER`、`WEBHOOK_SECRET_PREFIX` 及对应类型。
+- `vaults`（`VaultsResource`）与 `vaults.credentials`（`VaultCredentialsResource`）：vault 的 `create`、`list`、`get`、`archive`，以及凭据的 `create`、`update`、`validateMcpOAuth`。返回的是公开 metadata，不含凭据值。需要显式签发的 `vaults:read` / `vaults:write`：没有任何预设 token 带这两个 scope，`vaults:admin` 仍不可签发。token 能访问多个工作区时 `workspaceId` 必填。新导出 `VaultRequestOptions`、`ListVaultsOptions`、`ListVaultsResult`，以及 contracts 的 `CreateVaultRequest`、`CreateCredentialRequest`、`UpdateCredentialRequest`、`VaultRecord`、`VaultCredentialRecord`、`VaultCredentialValidation`。
+- `modelServices.list(projectId, { signal })`（`ModelServicesResource`）：列出一个项目的模型服务身份与状态（`{ id, displayName, status }`，`active` 与 `archived` 都给），宿主不必再用显示名反查 `llmp_` ID。需要 `model-services:read`；连接配置、鉴权类型、凭据、环境变量和内部 UUID 都不返回。项目不存在、不在 token allowlist 内或不在 ACL 内通常报 403 `PROJECT_NOT_IN_TOKEN_SCOPE`；ACL 通过后项目被删的竞态报 404 `PROJECT_NOT_FOUND`。新导出 `ModelServiceSummary`、`ListModelServicesResponse`。
+- `workloads.list({ projectId, limit?, cursor? })`（与 `agents.list` 是同一个方法）：列出一个项目内的 agent 元数据，按 ID 稳定排序；`limit` 默认 50、上限 200，翻页把上一页返回的 `nextCursor` 原样作为 `cursor` 传入。需要 `agents:read`；不可访问与不存在的项目都报 404 `PROJECT_NOT_FOUND`。新导出 `ListPlatformWorkloadsQuerySchema`、`ListPlatformWorkloadsResponseSchema` 及对应类型。
+- `agents.create({ version })`：一步出可跑版本（R0-4，#5492 宿主接入）。可选初版定义的形状与 `publishVersion` 的 body 一致（去掉 `projectId` / `workloadSlug` / `setDefault`；`workerContract` 可省，省略时继承 create 的 `kind`）；服务端在同一事务里建 workload + 首版 Revision + 默认指针 + 首发 `test` 槽位。初版省略 `llmProviderRef`（且未钉 `defaults.model` / 快照 `model`）时按「项目恰有一个 active 文本模型服务」自动选，0 个或多个 → 400 `MODEL_SERVICE_REQUIRED` 并列出候选。带初版的 create 是 create-only：同名 slug 409 `WORKLOAD_SLUG_TAKEN`。返回值新增 `revision`（含 `versionId` 镜像）；新导出类型 `WorkloadInitialVersionApplyResult`。
+- 客户端选项 `onBehalfOf`：宿主代终端用户调 API 时声明归因用户。设置后每个请求（JSON、multipart、SSE 首连与 `Last-Event-ID` 重连）都带 `X-AgentHub-On-Behalf-Of`，调用方自己带的同名头（任意大小写）不能覆盖。它只进审计与 `createdBy` 展示，不参与鉴权，不扩大 token 能做的事。空白值、或与 `actAs` 同时配置，构造时即抛 `CONFIG_INVALID_ON_BEHALF_OF`；头值形状由服务端判，非法值 400 `ON_BEHALF_OF_INVALID`。
+
+### 随包文档
+
+- `SKILL.md` 补充 webhook 订阅、vault 与凭据、模型服务、项目级 agent 列表与 `agents.create` 的 `version`，版本 0.24.0 → 0.29.0。
+
+### 迁移说明
+
+- 相对 npm 1.18.0 的声明文件，本版新增 41 个导出（315 → 356）、删除 0 个，`dist/realtime.d.ts` 与 1.18.0 逐字节相同。五个原有声明有变化，全部是可选字段或新成员：`PilotPlatformClientConfig.onBehalfOf?`、`PilotPlatformClient` 新增 `modelServices` / `webhookSubscriptions` / `vaults` 三个 `readonly` 资源属性、`CreatePlatformWorkloadRequestSchema` 的可选 `version`、`WorkloadApplyResult.revision?`、`WorkloadsResource`（即 `AgentsResource`）新增 `list()`。另有一个声明只改了 JSDoc（`CreateSessionRequestInput` 的 `stage` 说明），不涉及签名。没有不兼容的签名变化。
+
 ## 1.18.0
 
 浏览器实时语音入口新增级联通话的按键说话；主入口新增会话预览、回合摘要与按需读正文、项目仓库读写，以及客户端回合计时上报。