@kanyun-ai-infra/agenthub 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.28.0
+
+本版带上 1.27.1 之后合入 main 的公开面变化：`sessions.sendTurn` 的单回合预算 `maxCostUsd`
+（#5946）、`sessions.terminate`、版本与槽位读面报告模型服务名、回合 `usage.durationMs` 的口径说明、
+幂等键 24 小时窗口，以及 `turns.abort` 对已终止会话的 409 说明（#5942）。除下面「行为变化」一条外
+均为新增或文档。
+
+### 新增（主入口）
+
+- `sessions.terminate(sessionId, { reason?, deadlineAt?, requireNoActiveWork? })`：显式终止会话，
+  scope **`sessions:terminate`**（任何预设都不含它，自定义 token 上显式勾选）。
+  - 202 返回生命周期迁移结果 `{ ok, sessionId, from, to, transitionId }`；沙箱由平台异步销毁，
+    `deadlineAt`（ISO 8601）是等待干净停止的上限，省略用服务端默认。
+  - `requireNoActiveWork` 默认 `true`：有回合在跑时**拒绝本次调用**，应答
+    422 `INVALID_TRANSITION`（等回合结束重试，或传 `false` 中途终止）。
+  - 404 `SESSION_NOT_FOUND`（不存在与不在你的项目范围是同一个 404）。**422 是所有生命周期拒绝的
+    状态码，具体看里面的 `code`**：`INVALID_TRANSITION` = active-work 拒绝（有回合在跑）或已
+    `terminating` / `reviving`（这两者同码，按自己的意图处理）；`ALREADY_TERMINAL` = 行已
+    `terminated`（重试时可当已达成、调用未改任何状态）。409 `SESSION_NOT_READY` 是另一件事：
+    会话行本身不是 `status = ready`。
+  - 终止不是删除：会话行保留，之后 `sendTurn` 会把它复活到新沙箱（202 `revival_in_progress`）；
+    在 `terminating` 期间发回合也会启动复活，终止 runner 会放弃销毁。
+- `agents.getRevision` / `getRevisionById` / `getVersion`（以及 `agents.get` 内嵌的
+  `defaultRevision`）新增可选 **`modelServiceId` / `modelServiceName`**：这个版本会冻结到的模型服务
+  （`llmp_*` public id 与显示名；legacy 版本回落到 workload 的 manifest 默认）。版本没声明模型服务
+  时两个键都缺省；服务行被硬删时 `modelServiceName` 为 `null`（归档后仍返回名字）。
+- `agents.stages.list` 在**信封层**新增 `stageModelServices`：
+  `[{ stage, modelServiceId, modelServiceName }]`，只含声明了模型服务的槽位。返回类型因此变为
+  `ListStagesResult`（= `ListStagesResponse & { stageModelServices? }`，原有字段一字不变）；旧服务端
+  不返回这个键——缺省表示「没报告」，不是「没有模型服务」。放在信封层而不是槽位对象里，是因为
+  `StageSlotViewSchema` 是 `.strict()` 且内联在已发布客户端里，槽位对象多键会让旧客户端解析失败。
+- `sessions.sendTurn` 接受 `maxCostUsd`（美元，> 0 且 ≤ 50）与 `requireAuthoritativePrice`
+  （#5946）：服务端按回合判停。无价目返回 400 `BUDGET_UNPRICED`，会话/镜像不支持预算返回
+  409 `BUDGET_UNSUPPORTED_RUNTIME`——两种都是重发时去掉 `maxCostUsd`。
+
+### 行为变化（唯一一条，影响面写全）
+
+- **嵌套错误信封的码被提升**：`pilotPlatformErrorFromResponse` 是**本 SDK 发出的请求**所有 HTTP
+  错误的唯一入口，它现在在顶层没有 `code` / `message` 时读 `body.error.code` /
+  `body.error.message`。生效范围是所有**经本 SDK 发送**、且平台回该信封的端点：
+  - `sessions.createVoiceTicket` —— 实测例：平台停用实时语音时 `err.code` 从 `REQUEST_FAILED` 变成
+    `REALTIME_DISABLED`；
+  - `sessions.terminate`（本版新增的面，回 `{ success: false, error: { code, message? } }`）；
+  - 任何未来经本 SDK 调用、且平台回这个信封形状的路由，自动跟上。
+  顶层 `code` / `message` 始终优先（两种形状同时出现时行为不变），`err.body` 里仍是原始 body，
+  `err.body.error.code` 照旧可读。**按旧兜底码（`NOT_FOUND` / `REQUEST_FAILED` / `SERVER_ERROR`）
+  分支这两类调用的调用方需要改成按真实码分支**；只按 `err.status` 分支的不受影响。
+  **不在射程内**：SDK 没有 `sessions.acquire` 方法（`/api/sessions/acquire` 是平台内部路由，SDK 不调用）；
+  浏览器实时语音入口（`createRealtimeVoiceClient`）走 WebSocket 与自己的错误类型，不抛
+  `PilotPlatformApiError`；服务端内部写口与语音合成 handler 不属于本 SDK 的调用面。
+
+### 随包文档
+
+- `SKILL.md`：`sessions.terminate` 用法与 scope；版本 / 槽位读面的模型服务字段；幂等键的
+  **24 小时**回放窗口（窗口内同键同体重放、同键不同体 409；过期后同一个键会再执行一次并新建
+  资源，不能当永久去重）；`usage.durationMs` / `usage.timeToFirstTokenMs` 的口径（provider 流时长，
+  **不是**回合墙钟；墙钟用 `dispatchedAt` → `completedAt`）。随包 skill 版本 0.36.1 → 0.37.0。
+- `README.md`：同上四块的对应小节。
+- `turns.abort` 的 JSDoc 与 SKILL 已由 #5942 写明：对 `terminated` 会话的 409 `SESSION_TERMINATED`
+  不可重试，该会话仍可由新的 `sendTurn` 复活。
+
+### 导出面核对
+
+把 `npm pack @kanyun-ai-infra/agenthub@1.27.1` 解包后的 `dist/index.d.ts` 与本分支构建产物对比，
+去掉注释后的差异：
+- `PlatformRevisionSchema` 与两处内嵌（workload 读面的 `defaultRevision`、`GetPlatformRevisionResponse`）
+  新增 `modelServiceId?` / `modelServiceName?`；
+- 新增 `ListStagesResult`、`SessionTerminateLifecyclePhase`、`SessionTerminateRequest`、
+  `SessionTerminateRequestInput`、`SessionTerminateResponse`、`SessionTerminateRequestSchema`、
+  `SessionTerminateResponseSchema`、`StageSlotModelServiceView`、`StageSlotModelServiceViewSchema`；
+- `SessionsResource` 新增 `terminate`；`WorkloadStagesResource.list` 的返回类型换成
+  `ListStagesResult`；
+- `SendTurnInput` 新增 `maxCostUsd?` / `requireAuthoritativePrice?`。
+
+没有删除。`dist/realtime.d.ts` 无非注释差异。
+
+### 迁移说明
+
+除「行为变化」那条错误码提升外没有破坏性变化；不用新方法、新入参时行为与 1.27.1 相同。
+
+## 1.27.1
+
+只改文档，没有行为变化。
+
+- `sessions.listEvents` 的 `cursorReset` 补了处理范式（JSDoc 与 SKILL.md）：收到 `cursorReset: true` 时，丢掉由旧游标得到的结果，用 `turns.list` 的快照重建，再用 `page.streamCursor ?? undefined` 接 `streamEvents`。
+- 平台计划把流式片段（`pilot_coder.chunk`）的保留期从 30 天缩短到 1 天（当前仍是 30 天）；缩短后 `afterEventId` 指向已删事件的情况会更常见；`cursorReset` 的语义不变，`listEvents` 的返回形状不变。
+- `waitForTurn` 与 `streamEvents` 不使用事件 id 游标，不受影响。
+
 ## 1.27.0
 
 本版带上 1.26.0（83d138380，#5880，11-06）之后合入 main 的公开面变化：凭据创建可带幂等键、凭据新增只读的 list / get（#5894），以及 `listArtifacts` 透出超限文件 `oversizedFiles`（#5893）。均为新增，不用新入参时行为与 1.26.0 相同。

package/README.md

@@ -156,6 +156,43 @@ Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一
 > 未声明的字段时会被忽略，不会报错；服务端新增字段不需要客户端升级。1.16.0 起
 > `PlatformRevision` 接受可选的 `sequence`（每个 Agent 内从 1 递增的版本序号，号可
 > 不连续）；服务端读面返回它之前，该字段为 `undefined`。
+>
+> 1.28.0 起版本读面还带 **`modelServiceId` / `modelServiceName`**：这个版本会冻结到
+> 的模型服务（`llmp_*` id 及显示名，legacy 版本回落到 workload 的 manifest 默认）。
+> 版本没声明模型服务时两个键都缺省；服务行被硬删时 `modelServiceName` 为 `null`
+> （归档后仍显示名字）。`agents.stages.list` 在**信封层**（不在 `stages` 元素内）多给
+> 一个 `stageModelServices: [{ stage, modelServiceId, modelServiceName }]`，只含声明了
+> 模型服务的槽位；旧服务端不给这个键——缺省表示"没报告"，不是"没有模型服务"。
+
+## 终止会话与自动复活
+
+```ts
+// 显式终止：只翻生命周期到 terminating，沙箱由平台异步销毁（deadlineAt 兜底）。
+const t = await agenthub.sessions.terminate(sessionId, {
+  reason: "user_request",        // 1–50 字符，默认 "api"
+  requireNoActiveWork: true,     // 默认 true：有回合在跑时 422 INVALID_TRANSITION（拒绝本次调用）
+});
+// t => { sessionId, from, to: "terminating", transitionId }
+
+// 终止不是删除：之后对同一会话 sendTurn 会自动复活到新沙箱。
+const sent = await agenthub.sessions.sendTurn(sessionId, { text: "继续" });
+// sent.kind === "revival_in_progress"（HTTP 202，别重发）；用 waitForTurn 等那一轮
+```
+
+- 需要 scope **`sessions:terminate`**（任何预设都不含它，自定义 token 里显式勾选）。
+- 404 同时表示"不存在"与"不在你的项目范围"。
+- **422 是所有生命周期拒绝的状态码，具体看里面的 `code`**：`INVALID_TRANSITION` 是 active-work
+  拒绝（等回合结束重试，或显式传 `false` 中途终止），或会话已在 `terminating` / `reviving`
+  ——这两者同码，按自己的意图处理；`ALREADY_TERMINAL` 是会话已经 `terminated`（重试时可当已达成，
+  本次调用没改任何状态）。409 `SESSION_NOT_READY` 是另一件事：会话行本身不是 `status = ready`。
+- 在 `terminating` 期间 `sendTurn` 会启动 Agent Recovery，终止 runner 发现
+  transition id 变了会放弃销毁——**想留在终止态就别在这时发回合**。
+- 带 `idempotencyKey` 的创建方法（`projects.create` / `secrets.create` /
+  `modelServices.create` / `managedMcps.create` / `schedules.create` /
+  `vaults.credentials.create`）**回放窗口是 24 小时**：窗口内同键同体重放原响应，
+  同键不同体 409；窗口过后同一个键会再执行一次并新建资源，幂等键不能当永久去重，
+  创建出来的 id 要自己存。
+
 
 ## 记忆（agenthub.memories）
 
@@ -214,7 +251,7 @@ App 里点的"对"；`purge(projectId, { subjectKind, subjectId })` 按主体清
 
 | 字段 | 含义 |
 | --- | --- |
-| `usage` | 模型用量（`inputTokens` / `outputTokens` / `totalTokens` 等）。其中 `costUsd` 是 Claude Code CLI **自报的列表价估算**（`costSource === "claude_code_cli"`），不是账单实付；`failed` / `aborted` 轮次没有 `usage`（T-INV-13）。`completed` 轮次也可能缺省——用量数据没通过校验时字段不落，并在该轮 `anomalies` 里记 `usage_parse_failed`。 |
+| `usage` | 模型用量（`inputTokens` / `outputTokens` / `totalTokens` 等）。其中 `costUsd` 是 Claude Code CLI **自报的列表价估算**（`costSource === "claude_code_cli"`），不是账单实付；`failed` / `aborted` 轮次没有 `usage`（T-INV-13）。`completed` 轮次也可能缺省——用量数据没通过校验时字段不落，并在该轮 `anomalies` 里记 `usage_parse_failed`。`usage.durationMs` 是**模型 provider 流**的时长（首字节到最后一个 chunk），不含技能安装、交付、快照采集，**不是回合墙钟**；回合计时用 `dispatchedAt` → `completedAt`。`usage.timeToFirstTokenMs` 是同一时钟上到首个正文 chunk 的时间。 |
 | `traceId` | 这一轮的分布式 trace id（`string \| null`），可拼 Octopus trace-explorer 深链定位整条链路（agenthub → control-worker → agent-worker）。 |
 | `memoryRecall.state` | **只在会话首轮出现**——设计如此，不是版本或故障问题：读服务只给首轮投影这个字段（`session-turns-read-service.ts` 的 `core.turnId === enrichment.firstTurnId` 判据），第 2 轮起 `memoryRecall` 恒为 `undefined`，即便服务端是最新版。值是这一轮的**记忆召回状态**枚举，不是召回内容：`selected`（召回并注入了条目）/ `empty`（功能开着、也查了，本轮无可注入记忆）/ `recall_failed`（召回过程失败）/ `unavailable`（回读时没能解出召回快照）/ `legacy`（会话早于记忆机制，无快照）。目前只对外暴露状态，不含召回内容。 |
 
@@ -307,7 +344,9 @@ await agenthub.sessions.create({
 
 ## 错误
 
-API 请求失败都会抛出类型化错误，错误对象带 `status`、`code` 和 `requestId`——但请求被 `AbortSignal` 取消是例外，那条路径抛的是原生 `AbortError`，没有这些字段，需要单独判断：
+API 请求失败都会抛出类型化错误，错误对象带 `status`、`code` 和 `requestId`——但请求被 `AbortSignal` 取消是例外，那条路径抛的是原生 `AbortError`，没有这些字段，需要单独判断。
+
+`code` 的取法：先看响应顶层的 `code`，没有就读嵌套信封 `{ success: false, error: { code, message? } }` 里的 `body.error.code`（1.28.0 起；更早的版本只读顶层，嵌套信封的端点会给你按状态码兜底的 `NOT_FOUND` / `REQUEST_FAILED` / `SERVER_ERROR`）。原始 body 始终留在 `err.body`。
 
 | Class | HTTP |
 | --- | --- |
@@ -417,7 +456,7 @@ SDK 1.13.0 起提供此行为。旧版 1.11.0 / 1.12.0 / 1.12.1 忽略 `call_end
 
 通话可能在两处被拒：接入方后端取票时，和浏览器握手时。
 
-**取票被拒。** 发票接口的错误体是 `{ success: false, error: { code, message?, scope? } }`。SDK 只从响应顶层取码，所以 `createVoiceTicket` 抛出的 `PilotPlatformApiError` 上，`err.code` 只是按 HTTP 状态给的通用值（409 为 `REQUEST_FAILED`，503 为 `SERVER_ERROR`）。实际的码在 `err.body.error.code`，可读原因在 `err.body.error.message`，下表注明哪些码带 `message`。
+**取票被拒。** 发票接口的错误体是 `{ success: false, error: { code, message?, scope? } }`。1.28.0 起 SDK 把**嵌套信封的** `error.code` / `error.message` 提升到 `err.code` / `err.message`（顶层键优先），所以这里 `err.code` 直接就是下表里的码（如 409 `REALTIME_DISABLED`），可读原因在 `err.message`；原始 body 仍整块留在 `err.body`（`err.body.error.code` 同样可读）。1.27.1 及更早只取顶层，`err.code` 是按 HTTP 状态给的通用值（409 `REQUEST_FAILED`、503 `SERVER_ERROR`）——按旧版本写的 `err.body.error.code` 分支在新版本上照样成立。下表注明哪些码带 `message`。
 
 ```ts
 import { PilotPlatformApiError } from "@kanyun-ai-infra/agenthub";
@@ -426,8 +465,9 @@ try {
   return await client.sessions.createVoiceTicket(sessionId);
 } catch (err) {
   if (err instanceof PilotPlatformApiError) {
-    const detail = (err.body?.error ?? {}) as { code?: string; message?: string; scope?: string };
-    // detail.code 例如 "REALTIME_UPSTREAM_NOT_CONFIGURED"；detail.message 可以直接展示给用户
+    // err.code 例如 "REALTIME_UPSTREAM_NOT_CONFIGURED"（1.28.0 起；更早版本读 err.body.error.code）
+    // err.message 可以直接展示给用户
+    // REALTIME_CAPACITY_EXCEEDED 还要看 scope：err.body.error.scope 为 "project" / "global"（见下表）
   }
   throw err;
 }