@kanyun-ai-infra/agenthub 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.21.0
+
+AgentHub 组（spec `agenthub-groups.md` §6.3）要求 SDK 先发：服务端在项目与环境响应里返回组字段之前，调用方先换上能解析这些字段的 SDK。本版同时带上 1.20.0 之后合入的项目秘密、定时任务、托管 MCP、模型服务写入，以及 `sessions.listEvents` 的事件过滤和回合的续接信号 `Turn.continuation`。默认 User-Agent 改为带真实包版本。
+
+### 组字段：落在哪个对象、是否破坏（#5652、#5632）
+
+| 字段 | 落点 | 是否破坏 | 说明 |
+| --- | --- | --- | --- |
+| `group`（`PlatformProjectGroupRef \| null`，可选） | 返回值：`projects.create` 的 `PlatformProject`；`projects.get` / `projects.list` 的 `PlatformProjectRead` | 否（新增可选字段） | 项目所属组的 `{ id, slug, displayName }`；不在组内为 `null`；旧服务端不返回。按 `project.group ?? null` 读。 |
+| `homeOfGroup`（`PlatformProjectGroupRef \| null`，可选） | 同上 | 否 | 只在组的 home 项目上有值（home 项目存放组级环境与模型服务，它自身的 `group` 为 `null`）。 |
+| `scope`（`"project" \| "group" \| "platform"`，可选） | 返回值：`environments.list` / `environments.get` 等返回的 `Environment` | 否 | `"group"` 表示继承自组的 home 项目；`"platform"` 与 `isPlatformShared: true` 同义。闭集外的值解析报错。 |
+| `groupId`（`string`，可选） | 请求：`projects.create` 的 `CreatePlatformProjectRequest` | 否（新增可选入参） | 在指定组内建项目。组主体 token 建的项目总落在它自己的组（省略或写本组；写别的组 403）；个人指定组时须是该组管理员；个人省略时与以前一样不入组。组不存在 404 `GROUP_NOT_FOUND`。 |
+
+1.20.0 对这些返回字段都会抛 `ZodError`：项目的写面与读面、环境响应在 1.20.0 都是 strict。服务端开始返回之前需要先升级到 1.21.0（环境 `scope` 随服务端发版直接返回；项目 `group` / `homeOfGroup` 由服务端开关控制，先在 testing 打开）。新导出 `PlatformProjectGroupRefSchema`、`EnvironmentScopeSchema` 与类型 `PlatformProjectGroupRef`、`EnvironmentScope`。
+
+### 新增（主入口）
+
+- `modelServices.create(projectId, body, { idempotencyKey?, signal? })`、`modelServices.update(projectId, serviceId, body)`、`modelServices.archive(projectId, serviceId)`（#5641）：模型服务的创建、原地轮换凭据或改非敏感字段、软归档。需要显式签发的新 scope `model-services:write`：它不在任何预设里，也不蕴含 `model-services:read`。`create` 发送 `Idempotency-Key`：同 key 同 body 重放原响应，换 body 409 `IDEMPOTENCY_KEY_CONFLICT`。`authScheme` 不可改（409 `llm_provider_config_scheme_mismatch`）；已归档行 410 `llm_provider_config_archived`；仍被在用 agent 或冻结版本引用时归档 409 `llm_provider_config_in_use`。写入的响应只有 `{ id, displayName, status }`，连接配置与凭据不回显，错误体里也没有。新导出 `ArchiveModelServiceResponse`、`CreateLlmProviderConfigRequest(Input)`、`UpdateLlmProviderConfigRequest(Input)`、`ModelServiceCreateOptions`、`ModelServiceRequestOptions`。
+- `secrets`（`SecretsResource`，#5560）：项目秘密的 `create`（可带 `idempotencyKey`）、`list`、`rotate`、`archive`。列表需要 `secrets:read`，写入需要 `secrets:write`，两者与 `secrets:resolve` 互不蕴含、都要显式勾选。响应只给元数据与 `sec_*` ID，不含明文或密文。新导出 `SecretRecord`、`SecretListItem`、`CreateSecretRequest`、`RotateSecretRequest`、`SecretCreateOptions`、`SecretListOptions`。
+- `schedules`（`SchedulesResource`，#5568）：workload 定时任务的 `create`（可带 `idempotencyKey`）、`list`、`get`、`update`、`delete`、`runNow`、`listTriggers`。scope `schedules:read` / `schedules:write` / `schedules:run` 互不蕴含、都不在预设里。owner 恒为 token 主体；不传 `targetRevisionId` 时用 production 槽位。新导出 `ScheduleView`、`ScheduleListResponse`、`ScheduleTriggerListResponse`、`RunScheduleResponse`、`CreateScheduleRequest`、`UpdateScheduleRequest`。
+- `managedMcps`（`ManagedMcpsResource`，#5577、#5579）：项目托管 MCP 的 `list`、`get`、`create`（可带 `idempotencyKey`）、`update`、`retire`、`archive`、`previewRushImport`。读需要 `managed-mcps:read`，写需要 `managed-mcps:write`，互不蕴含。`kind`、`mcpServerUrl`、`stdioConfig` 不可改；`archive` 不可撤销，会级联归档该 MCP 名下的凭据；有已部署槽位绑定时 `retire` / `archive` 409，可用 `force: true` 跳过；仍有会话在用时 `archive` 拒绝，不可 force。响应只给凭据名与是否存在，不含值。新导出 `ManagedMcpRecord`、`ListManagedMcpsPlatformResponse`、`CreateManagedMcpRequest`、`UpdateManagedMcpRequest`、`RushImportPreviewRequest`、`RushImportPreviewResponse`、`ManagedMcpCreateOptions`、`ManagedMcpLifecycleOptions`、`ManagedMcpListOptions`。
+- `projects.create(body, { idempotencyKey })`（#5574）：发送 `Idempotency-Key`。同 key、逐字节相同的 body 重放原响应（同一项目 id）；换 body 409 `IDEMPOTENCY_KEY_CONFLICT`；拿不到服务端重放锁时 409 `IDEMPOTENCY_LOCK_TIMEOUT`，用同 key 同 body 重试。新导出 `ProjectCreateOptions`。
+- `vaults.credentials.create` 接受 `git_token` 凭据（#5630）：请求体 `{ displayName, auth: { type: "git_token", gitOrigin, repoPath, accessToken, expiresAt? } }`，一把 GitLab project access token 对应一个仓库。写入前服务端用该 token 探测仓库，失败 422 `vault_credential_git_probe_failed`（`details.reason` 给原因），GitLab 不可达 503 `vault_credential_git_probe_unavailable`。`vaults.credentials.update` 传 `{ auth: { accessToken } }` 即原地轮换：id 不变，先探测再写入。`VaultCredentialRecord` 改为按 `authType` 区分的联合类型，`git_token` 记录带 `gitOrigin`、`repoPath`、`secretRotatedAt`、`rotationSeq`，不带 `mcpServerUrl`，也不含 token 值。
+- `sessions.create` 的可选 `repositories`（#5626、#5647）：目前最多 1 项，形如 `{ type: "git_repository", url, ref, credentialRef: { type: "vault_credential", id: "vcrd_…" }, delivery: { mode: "push_back", allowedPaths } }`，用调用方 vault 里的 `git_token` 凭据把会话钉到指定仓库，每轮推回 `ref` 分支。不能与 `repoUrl` / `repoRef` / `deliveryMode` / `pushBackPaths` 同用，SDK 在发请求前拒绝这些组合。调用方 token 须带 `vaults:read`（或 `vaults:admin`），客户端不能代其他用户调用（`actAs`）。服务端拒绝码：403 `REPO_RESOURCE_NOT_ALLOWED`、400 `REPO_CREDENTIAL_MISMATCH`、403 `REPO_NOT_GRANTED`、403 `REPO_PUSH_NOT_ALLOWED`、400 `REPO_CREDENTIAL_INVALID`、503 `REPO_CHECK_UNAVAILABLE`（可重试），功能未打开时 400 `REPO_RESOURCES_DISABLED`。功能可用需要服务端部署 #5633 并打开开关 `session_git_resources_enabled`。
+- `sessions.listEvents(sessionId, { chunkTypes } | { excludeChunkTypes })`（#5663）：按 `pilot_coder.chunk` 的 `payload.type`（如 `text-delta`、`reasoning-delta`）在服务端过滤事件。两个参数互斥，同时传 400；不传时行为不变。新 SDK 调旧服务端时参数被忽略，过滤不生效，也不报错。
+- `Turn.continuation`（可选，#5661）：跟进回合是续接上了上一轮的 CLI 会话，还是用平台重建的上文跑的；重建时说明上文有没有被截断。出现在 `sessions.turns.get` / `list` / `getMetadata` 的返回和 `waitForTurn` 返回的 `turn` 上。`state` 取 `resumed` / `rebuilt` / `resume_pending` / `resume_unconfirmed`；`rebuilt` 时带 `reason`（如 `prior_turn_not_completed`、`transcript_missing`、`session_revived`）、`parentTurnStatus` 和 `rebuiltContext`（`truncated`、`truncatedMessageCount`、`droppedMessageCount`、`truncatedMessages[{ index, role, originalChars, keptChars }]` 等）。`reason` / `parentTurnStatus` 类型是 `string`，服务端以后加新原因时照常解析。字段缺失表示「不知道」（首回合，或平台记录这项信息之前的回合），不表示续接上了。新导出类型 `TurnContinuation`、`TurnContinuationState`。
+- 事件流新增事件类型 `session.followup_context`（#5661）：每个跟进回合派发时写一条，payload 是派发判定（`resume` / `rebuild`）、原因与重建上文的长度统计，不含消息内容；`event_id` 为 `followup_context:<turnId>`。`listEvents` / `streamEvents` 的事件类型是字符串，已有调用方不受影响。
+
+### 修复
+
+- `environments.list` / `get` 不再因平台共享环境抛错（#5652）。平台共享环境属于平台默认项目，它的 id `00000000-0000-0000-0000-000000000001` 不是 RFC 4122 UUID，1.20.0 的 `Environment.projectId` 校验会拒绝它；而 `environments.list` 的结果总会包含平台共享环境，所以 1.20.0 对任何项目调用都抛 `ZodError`（`path: ["projectId"]`）。
+
+### 行为变化
+
+- 默认 `User-Agent` 由固定的 `@kanyun-ai-infra/agenthub/0.1.0` 改为 `@kanyun-ai-infra/agenthub/<包版本>`，本版即 `@kanyun-ai-infra/agenthub/1.21.0`（#5652）。服务端据此区分新旧 SDK 调用方。客户端选项 `userAgent` 照旧覆盖默认值。
+
+### Band 调用面（`workloads.stages` / `sessions.*`）
+
+| 改动 | 落点 | 是否破坏 |
+| --- | --- | --- |
+| `sessions.listEvents` 新增 `chunkTypes` / `excludeChunkTypes`（#5663） | 请求 options；返回结构不变 | 否 |
+| `sessions.create` 新增 `repositories`（#5626） | 请求体 | 否（可选入参；1.20.0 在发请求前以未知字段拒绝它） |
+| `Turn.continuation`（#5661） | 返回值：`sessions.turns.get` / `list` / `getMetadata`、`waitForTurn` 的 `turn` | 否（新增可选字段；1.20.0 的回合 schema 不是 strict，服务端先返回时旧 SDK 剥掉、不抛） |
+| 事件类型 `session.followup_context`（#5661） | `sessions.listEvents` / `streamEvents` 的事件 | 否（事件类型是字符串） |
+| `sessions.sendTurn` 超过 5 个附件时报 400 `TOO_MANY_ATTACHMENTS`（`err.body.max` = 5），不再截断（#5611） | 服务端行为，与 SDK 版本无关；本版只补 JSDoc | 对旧行为：原先静默保留前 5 个，现在整轮拒收 |
+| `workloads.stages` | 本版无变化 | — |
+
+`repositories` 与 `git_token` 的随包文档和错误码说明（#5647）随本版发布，运行时无变化；功能需服务端部署 #5633（P4）并打开 `session_git_resources_enabled`。
+
+### 随包文档
+
+- `SKILL.md` 补充组字段与环境 `scope`、模型服务写入、项目秘密、定时任务、托管 MCP、`projects.create` 的幂等键、`listEvents` 过滤，新增「git_token 凭据」与「仓库资源会话」两节（前置 scope、错误码与轮换方式，#5647），「Revisiting a session」一节补 `turn.continuation` 的读法（被截断的内容若是 agent 必须逐字遵循的协议或 schema，在跟进文本里重发）；随包 skill 版本由 0.29.2 升至 0.30.1（#5641、#5652、#5663、#5560、#5568、#5577、#5574、#5661、#5647）。`README.md` 补 `turn.continuation` 一节（#5661）。
+- 一步建 agent 的模型服务自动选择改为：项目恰有一个 active 文本模型服务时，即使钉了 `defaults.model` 或快照 `model` 也自动选（#5601，服务端行为，SDK 只改 JSDoc 与 skill）。
+
+### 迁移说明
+
+- 相对 npm 1.20.0 的声明文件，本版新增 40 个导出（356 → 396）、删除 0 个；`dist/realtime.d.ts` 与 1.20.0 逐字节相同。
+- **`projects.get()` / `projects.list()` 的读面（#5641）**：返回类型由 `PlatformProject` 改为 `PlatformProjectRead`。编译期：`slug` 由 `string` 放宽为 `string | null`（老门户项目可能是 `null` 或空串，此前一行就让整个 `list()` 抛错），其余字段的类型与可选性不变（本版新增的 `group` / `homeOfGroup` 见上文组字段表）；把 `project.slug` 当 `string` 用的代码需要收窄，例如 `project.slug ?? ""`。运行时：解析由 strict 改为剥离未知字段，服务端以后在项目上加字段，1.21.0 起的 `get` / `list` 不会因此抛 `ZodError`（未声明的字段读不到）。`projects.create()` 仍返回 strict 的 `PlatformProject`（`slug: string`）。
+- `VaultCredentialRecord` 改为按 `authType` 区分的联合类型（#5630）：读 `mcpServerUrl` 等 MCP 字段前先按 `authType` 收窄。
+- `AGENTHUB_SDK_USER_AGENT` 的声明类型由字面量改为 `string`，值见上文「行为变化」。
+- 其余变化均为新增导出、新增可选字段或新增资源属性（`PilotPlatformClient` 的 `secrets`、`schedules`、`managedMcps`）；流水线运行的 `trigger` 枚举与回合 `status` 枚举只是成员顺序变化，取值集合不变。
+- 供后续加字段参考：以下响应 schema 仍是 strict，服务端给它们加字段会让 1.21.0 及以前的 SDK 解析报错（`ZodError` 或 `MALFORMED_PLATFORM_RESPONSE`，视方法而定），须先发 SDK、调用方升级后再返回：`workloads.stages.list` 的 `ListStagesResponseSchema` / `StageSlotViewSchema`，`sendTurn` / `sessions.abort` 的派发结果（SDK 内部的 `DispatchOutcomeSchema`），`projects.create` 的 `PlatformProject`，环境的 `Environment`。
+
+## 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` 可以带初版定义一步出可跑版本，客户端可以声明代终端用户调用的归因用户。对导出面是纯增量，已有调用方不用改代码。

package/README.md

@@ -226,6 +226,34 @@ App 里点的"对"；`purge(projectId, { subjectKind, subjectId })` 按主体清
 轮次没有，`completed` 轮次遇到用量解析失败也会缺（看 `anomalies` 里的
 `usage_parse_failed`）；`traceId` 在没采到链路时是 `null`。
 
+### `continuation`：跟进回合是否续接上原 CLI 会话
+
+跟进回合（`kind === "followup"`）带可选字段 `continuation`，说明这一轮模型看到的上文从哪里来：
+
+| `continuation.state` | 含义 |
+| --- | --- |
+| `resumed` | 续接了上一轮的 CLI 会话，模型看到的是完整的原始对话记录。 |
+| `rebuilt` | 没有续接，平台从会话事件重建上文后随本轮下发。`reason` 说明原因，`rebuiltContext` 说明重建的上文是否被截断。 |
+| `resume_pending` | 已按续接派发，沙箱还没报告结果。 |
+| `resume_unconfirmed` | 已按续接派发，回合已结束，但沙箱没有报告续接成功或回退（沙箱先退出，或镜像不发这两条事件）。 |
+
+`reason` 的取值（字符串，后续可能新增，消费代码不要按封闭枚举处理）：
+
+| `reason` | 含义 |
+| --- | --- |
+| `prior_turn_not_completed` | 上一轮没有正常完成。`parentTurnStatus` 给出上一轮的结局：`aborted`（被停）、`failed` / `rejected`（平台或沙箱侧失败）、`not_terminal`（没有终态事件）。 |
+| `transcript_missing` | 派发时准备续接，但沙箱里已经没有原 CLI 会话的记录（沙箱被回收或重建过），回退到重建。 |
+| `resume_stream_failed_early` / `resume_stream_empty` | 续接后模型在产出任何内容前报错 / 空回复，回退到重建。 |
+| `session_revived` | 会话复活后的第一轮：新沙箱上没有原 CLI 会话。 |
+| `binding_changed` | 上一轮跑在另一个沙箱上。 |
+| `no_cli_session_reported` | 上一轮没有回报 CLI 会话 id（老镜像，或不是 Claude Code 执行器）。 |
+| `usage_kind` | 会话不是 `conversation` 用途，跟进回合一律重建。 |
+| `flag_off` | 平台没有开启续接。 |
+
+`rebuiltContext` 只在 `rebuilt` 时出现：`messageCount` / `totalChars` 是下发的上文条数与总字符数；`truncated` 为 `true` 表示有内容被截掉；`truncatedMessages[]` 逐条给出被截断消息在上文中的位置、角色、原长 `originalChars` 与保留长度 `keptChars`（含截断标记）；`droppedMessageCount` 是因总长度上限被整条丢掉的较早消息数。长度按 JS 字符串长度计。
+
+`continuation` 缺失表示「不知道」，不表示续接成功：首轮（`prompt`）没有这个字段；平台记录该信息之前派发的跟进回合也没有；读取失败时同样省略。对应的会话事件是 `session.followup_context`（派发时写入）、`agent.followup_resumed` 与 `agent.followup_resume_fallback`（沙箱写入），可经 `GET /sessions/:id/events` 读取。
+
 `traceId` 的 Octopus 深链（照 `apps/agent-hub` 里 `octopusTraceUrl` 的真实参数，
 query 名是 `traceExplorerQuery` 而非 `traceId`）：