@kanyun-ai-infra/agenthub 1.23.0 → 1.25.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.25.0
+
+本版带上 1.24.0（85b344c33，#5864，11-05）之后合入 main 的公开面变化：`sessions.create` 钉 `revisionId` 起会话时显式指定 environment 的两个可选入参（#5871，F6）。无破坏性变化，不传新字段逐字不变。期间合入的 #5872（pending 凭据建壳）不进 SDK 类型面，只新增一个透传错误码。
+
+### 新增（主入口）
+
+- `sessions.create` 的可选 `environmentId` / `environmentVersion`（#5871，F6；Band 从 blocks 板 #1569 真依赖的读回路径）：钉 `revisionId`（别名 `versionId`）起会话时，让会话跑在显式指定的 environment（`runtime_templates` 行 id）上，而不是 revision 快照的基础模板。三件事：
+  - **不传 `environmentId` 时与 1.24.0 完全一样**：pin 路径的 environment 保持 `null`，用 revision 快照的模板；`stage` 路径不受影响，环境仍来自槽位绑定。
+  - **传了按显式环境走**：`environmentVersion` 缺省取该环境当时的可服务版本（current servable version），实际解析到的版本冻进会话；显式传的版本不存在或不可服务 → 400 `ENVIRONMENT_VERSION_NOT_FOUND`，不退到最新版。环境必须可被会话所属项目引用（同项目或平台共享、未归档），否则拒绝且不写会话行。
+  - **他项目的环境与不存在的 id 同形**：都是 404 `ENVIRONMENT_NOT_FOUND`（#3410 反枚举口径）；已归档是 422 `ENVIRONMENT_ARCHIVED`。
+  - 边界：`environmentId` 没有 `revisionId` 相伴 → 400 `ENVIRONMENT_REQUIRES_REVISION_PIN`（与 `stage` 同传也拒，stage 路径的环境来自槽位绑定）；`environmentVersion` 单独出现（无 `environmentId`）也被拒；公开项目的非成员访客带它 → 403 `public_viewer_cannot_declare_environment`；`(environmentId, environmentVersion)` 进 `idempotencyKey` 的请求身份（同 key 换环境 = 幂等冲突），带 `environmentId` 的 pin 请求不走预热池（`revisionId` 本身已退出预热）。请求 schema 是 `.strict()`：1.24.0 及更早版本传 `environmentId` 会在发请求前被本地 zod 拒绝，要用先升级到 1.25.0。需要服务端部署 #5871。
+- 错误码透传（#5872，不改调用方式）：SDK 按服务端原样透传的 zod 内联闭集（`dist/index.js` 里的 `MANAGED_MCP_ERROR_CODES` 数组）新增成员 `managed_mcp_pending_credential`（409：值待填的壳不能退场 / 重建）。该闭集不在 d.ts 类型面（1.24.0 起即如此），不构成类型变化。闭集在构建时内联进 SDK bundle：1.24.0 的 bundle 构建于 85b344c33，里面没有这个成员——服务端部署 #5872 后，1.24.0 收到它会投影成 `UNKNOWN_ERROR`（`PilotPlatformApiError`，status 409，非原样 code）；要原样透出，先升级到 1.25.0。
+
+### 随包文档
+
+- `SKILL.md`：「Pinning a revision with an explicit environment: `environmentId`」一节（用法、错误码、幂等与预热池边界）已在 #5871 随源码进 main。随包 skill 版本由 0.33.0 升至 0.34.0（npm 1.24.0 包里实测 `version: 0.33.0`）。
+
+### 导出面核对
+
+`npm pack @kanyun-ai-infra/agenthub@1.24.0` 解包后的 `dist/index.d.ts` 与本分支构建产物逐块对比，全部非注释差异：`CreatePlatformSessionRequestSchema`（即 `CreateSessionRequestSchema`）对象内新增 `environmentId: z.ZodOptional<z.ZodString>` 与 `environmentVersion: z.ZodOptional<z.ZodNumber>` 两行（#5871）。没有删除行。`dist/realtime.d.ts` 逐字节相同。JS 运行时 diff（ESM 与 CJS 同内容）的其余部分均为 #5872 带入、SDK 不导出的内联 schema 与常量：`CreatePendingManagedMcpRemoteSchema` / `CreatePendingManagedMcpStdioSchema` / `CreatePendingManagedMcpRequestSchema` / `CreatePendingSecretRequestSchema`（pending 建壳，仅经 contracts 源码树进入 bundle，不在 SDK 出参 / 入参 / 导出类型上）、`MANAGED_MCP_ERROR_CODES` 数组新增成员 `managed_mcp_pending_credential`、以及 #5871 的两个 refine 消息文本；不构成类型面变化。#5869（迁移）不触及 SDK。
+
+### 迁移说明
+
+无破坏性变化，不需要迁移。两个字段均可选，不传逐字不变。1.24.0 的 `sessions.create` 请求 schema 是 strict，传 `environmentId` 会在发请求前被拒，要用先升级到 1.25.0。
+
+## 1.24.0
+
+本版带上 1.23.0（9a5aad9fe，#5829，11-04）之后合入 main 的两组公开面变化：`workloads.getRevisionById`（#5856，Band 从槽位 `revisionId` 得到版本名的依赖），以及凭据直写收紧到项目管理员带来的新 403 错误码（#5858）。均不破坏编译。
+
+### 新增（主入口）
+
+- `workloads.getRevisionById({ projectId, revisionId })`（#5856）：`GET /api/revisions/{revisionId}?projectId=`，按 id 读一条已发布 revision——手里只有槽位视图的 `revisionId`、拿不到版本名时用它。返回与 `getRevision`（slug + version）同一对象（`version`、`plugins` 在内，不含 `sequence`），别名 `agents.getRevisionById` 同一方法。`projectId` 必填：别的项目的 revision 与不存在的 id 同形，都是 404 `REVISION_NOT_FOUND`；token scope 外的 `projectId` 在任何读之前 403 `PROJECT_NOT_IN_TOKEN_SCOPE`。需要 `agents:read`。新入参类型 `GetRevisionByIdInput`（与 `GetRevisionInput` 同模式，不单独从入口导出）。需要服务端部署 #5856。
+- eval run 读面（`evals.listRuns` / `getRun` 返回的 `summary`）新增可选字段 `sessionRevisionIds: string[]`（#5729 巡检线，99314ac0b）：巡检 run（trigger `schedule`）的会话实际用到的 revision，按首次出现排序去重，首项即 run 的实际版本；run 中途换过版本时长度大于 1。非巡检 run、一个会话都没建成或 run 不由 worker 收口时缺省。schema 本就 `.loose()`，未知消费方不受影响；该字段只出现在读面，eval 写 API 不在 SDK 公开面。
+
+### 行为变化
+
+- 凭据值的直接写入收紧到项目管理员（canManage，#5858）：`secrets.rotate`（沿用 403 `SECRET_FORBIDDEN`，文案改为「只有项目管理员可以轮换密钥」）与 `managedMcps.update` 里携带 `accessToken` / 非空 `secretValues` / `customHeaders`（整包算凭据）的请求、携带这些字段的 rebuild，普通成员 / 组成员 / 组主体 token（协作级）现在收到 403；托管 MCP 侧新错误码 **`managed_mcp_credential_requires_manager`**（403）。读、列表、新建、只改 `displayName` / `toolApprovalPolicies` 仍是协作级。放行：owner、平台管理员、组管理员。这是**服务端行为变化**（无 flag，随服务端发版生效），SDK 版本不改变它；升级 SDK 的意义是新错误码进入 `ManagedMcpErrorCode` 闭集。以协作级 token 做自动化凭据轮换的调用方，改用项目管理员 token。需要服务端部署 #5858。
+
+### 随包文档
+
+- `SKILL.md`：`getRevisionById` 的用法与资源表更新已在 #5856 进 main。随包 skill 版本由 0.32.0 升至 0.33.0（npm 1.23.0 包里实测是 0.32.0）。
+
+### 导出面核对
+
+`npm pack @kanyun-ai-infra/agenthub@1.23.0` 解包后的 `dist/index.d.ts` 与本分支构建产物逐块对比，全部非注释差异：`workloads.getRevisionById` 方法与 `GetRevisionByIdInput`；`EvalRunSummarySchema` / `EvalRunSummaryWriteSchema` 的 `summary` 内新增 `sessionRevisionIds: z.ZodOptional<z.ZodArray<z.ZodString>>`（两处，#5729）。没有删除行。`dist/realtime.d.ts` 逐字节相同。JS 运行时 diff 的其余部分均为 zod 别名重编号、#5808 的注释措辞（判官→grader）与 SDK 不导出的内联 schema（groups-portal 巡检控制台 wire、eval patrol、`managed_mcp_credential_requires_manager` 错误码常量），不构成类型面变化。
+
+### 迁移说明
+
+无破坏性变化，不需要迁移。旧版本风险：服务端部署 #5858 后，1.23.0 及更早版本里能收到这个码的路径（`managedMcps.update` 携带凭据字段）会把它按旧白名单投影成 `UNKNOWN_ERROR`（`PilotPlatformApiError`，status 403，message 固定文案，非原样 code）；要区分出 `managed_mcp_credential_requires_manager` 本身，先升级到 1.24.0（闭集含它，原样透出）。`getRevisionById` 是新方法，旧版本没有对应路径。
+
 ## 1.23.0
 
 本版带上 1.22.0 之后合入的两组公开面改动：`sessions.create` 按会话选择项目模型服务（`modelServiceId`，#5809），以及选择流水线克隆绑定仓库所用凭据的 `bindings.setRepoCredentialMode` / `getRepoCredentialStatus`（#5770 PR 2a，#5802）。两组都是新增，没有破坏性变化。