@kanyun-ai-infra/agenthub 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -2,6 +2,96 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## Unreleased
+
+## 1.29.0
+
+本版带上 1.28.0 之后合入 main 的公开面变化：凭据录入票据 `credentialEntryTickets`（#6007）、
+统一凭据管理入口 `credentials.revoke`（#6008）、`evals.createRun` 与 `duration` / `usage`
+grader（#5979）、回合耗时与价目成本读面及 `usage-update` 进度帧（#5978），以及候选构建读回的
+随包文档（#5976）。全部为新增或文档，没有行为变化，也没有需要迁移的改动。
+
+### 新增（主入口）
+
+- `credentials.revoke(credentialRef, { mode?, reason? }, { signal? })`：项目密钥（`sec_*`）、
+  vault 凭据（`vcrd_*`）与模型服务（`llmp_*`）的统一管理入口，按引用前缀分发到各类既有归档
+  路径。`mode` 取 `"retire"`（退役）或 `"revoke"`（彻底撤销）。
+  - `mode: "retire"` 沿用各类既有行为，需要该类型原有的 write scope：`sec_*` 用
+    `secrets:write`，`llmp_*` 用 `model-services:write`，`vcrd_*` 的 remote / stdio 用
+    `managed-mcps:write`，net / git 用 `vaults:write`。另需项目访问权限，普通 vault 还要求
+    actor 所有权（项目默认托管 vault 按项目权限）。scope 之间没有蕴含关系，不能跨类型使用。
+  - retire 的效果：模型服务与托管 MCP 保留存量会话的解析；项目密钥、网络凭据与 git token 在
+    下次取用时失效。既有归档护栏与阶段引用护栏继续生效。
+  - **缺省 `mode` 是 `"revoke"`**，该模式尚未开放：它要求预留的 `vaults:admin`，当前签发的
+    平台 token 拿不到这个 scope，缺省调用返回 403 `CREDENTIAL_FORBIDDEN`；授权保留调用方通过
+    项目、actor 与类型校验后返回 501 `CREDENTIAL_REVOKE_NOT_ENABLED`，不修改任何凭据
+    （服务端尚未开放撤销）。
+  - 响应只有 `{ credentialRef, mode }`，不含凭据值。`reason` 是最长 1000 字符的可选请求上下文，
+    不持久化。
+  - 错误：400 `CREDENTIAL_REF_INVALID` / `CREDENTIAL_REQUEST_INVALID` /
+    `CREDENTIAL_TYPE_UNSUPPORTED`（该 vault 凭据类型不支持此操作），404 `CREDENTIAL_NOT_FOUND`
+    （不存在与不在权限范围同形），403 `CREDENTIAL_FORBIDDEN`，501
+    `CREDENTIAL_REVOKE_NOT_ENABLED`。
+  - 既有各资源面的 archive / retire 方法保留，本方法只是统一入口。
+- 新增 `credentialEntryTickets.create/get/revoke`：按目标写 scope 签发短期录入链接、查询状态和撤销。SDK 不提供填值方法。
+- 建票支持 `Idempotency-Key`：pending 恢复同一 URL；异体 409；终态或过期同 key 返回 410，不重发 URL，24 小时内保留无能力 tombstone。
+- 建票结果的 `url` 通过显式属性读取；JSON 与 Node inspect 隐去 URL，票据资源错误只保留安全代码。
+- `evals.createRun({ projectId, agent, suiteRef, strict? })`：手动触发一次 test 槽的 suite run，
+  scope **`eval:trigger`**。`POST /api/eval-runs` 以 202 返回 `{ runId }`，只建 run head 并入队；
+  `trigger` 固定 `cli`，没有可挂的 pipeline run，因此不产生 gate-visible conclusion，不参与
+  槽位晋级判定。`agent` 传 slug；未知 slug 404 `AGENT_NOT_FOUND`、test 槽未部署 400
+  `STAGE_NOT_DEPLOYED`、suite 不合法 400 `INVALID_SUITE` / `SUITE_PARSE_ERROR`。`caseIds` 不上
+  wire（服务端 400 `CASE_IDS_NOT_SUPPORTED`），一次 run 总是执行整个 suite。
+- suite 可声明两种新 grader 类型（#5979）：`duration`（`maxTurnMs` 逐回合，或用 `turn` 收窄
+  单轮；`maxTotalMs` 求和；`maxTimeToFirstTokenMs` 逐回合）与 `usage`（`maxInputTokens` /
+  `maxOutputTokens` / `maxTotalTokens` / `maxCacheReadInputTokens` /
+  `maxCacheWriteInputTokens` / `maxCostUsd`，case 全回合求和）。无终态事件、非 completed 终态、
+  `usageSource: "missing"`、或声明了某预算而读数缺席时判 `errored`；`errored` 不计 `failed`，
+  不直接挡晋级闸。
+- 回合读面（#5978，均为新增键，旧读方剥掉而不拒收）：
+  - `usage-update` chunk：仅带 `maxCostUsd` 的回合产出，读数是累计值，只在读数变化时追加一帧
+    （长工具调用不刷屏）。SDK 导出 `isUsageUpdateChunk` guard 与 `UsageUpdateChunk` 类型；
+    `streamEvents` 直接可读，轮询用 `listEvents({ chunkTypes: ["usage-update"] })`。
+  - `TurnUsage.toolDurationMs`：本回合工具执行墙钟时间的并集（并行调用重叠只计一次），恒为
+    `durationMs` 的子集；`tool-output-available` / `tool-output-error` chunk 与
+    `TurnAssistantToolPart` 同时带逐工具的 `durationMs`。
+  - completed 终态的 `usage.pricebookCost`（`amountUsd` / `priceTableVersion` /
+    `unpricedModelEstimated`）：按派发时冻结的价目表估算，只有带 `maxCostUsd` 的回合有；与
+    执行器自报的 `usage.costUsd` 是两个来源，不参与计费。
+
+### 随包文档
+
+- `SKILL.md`：候选构建读回（#5976）——候选 run 终态后 `getRun(runId, { includeCandidates: true })`
+  的 `workloads[].revisionId` 即候选 Revision，可直接作为 `sessions.create` 的 `revisionId`
+  钉进会话（不走槽位解析）；`credentials.revoke` 与 `credentialEntryTickets` 的用法、scope
+  与错误面；`evals.createRun` 的手动触发口径。随包 skill 版本 0.37.0 → 0.39.0（#6007 / #6008
+  各自 bump）。
+- `README.md`：`credentials.revoke` 与 `credentialEntryTickets` 小节。
+
+### 导出面核对
+
+把 npm 上的 `@kanyun-ai-infra/agenthub@1.28.0` 解包后的 `dist/index.d.ts` 与本分支构建产物
+对比，去掉注释后**没有任何删除行**。新增：
+
+- 客户端字段：`PilotPlatformClient.credentials`、`PilotPlatformClient.credentialEntryTickets`；
+- 方法：`CredentialsResource.revoke`、`CredentialEntryTicketsResource.create` / `get` /
+  `revoke`、`EvalsResource.createRun`；
+- 值导出：`isUsageUpdateChunk`、`CreateEvalRunRequestSchema`、`CreateEvalRunResponseSchema`；
+- 类型：`CredentialRef`、`CredentialRevocationMode`、`CredentialRevocationErrorCode`、
+  `RevokeCredentialRequest`、`RevokeCredentialResult`、`CredentialEntryTarget`、
+  `CredentialEntryTicketView`、`CreateCredentialEntryTicketRequest`、
+  `CreatedCredentialEntryTicket`、`CreateEvalRunRequest`、`CreateEvalRunResponse`、
+  `UsageUpdateChunk`；
+- 既有类型新增可选键：`TurnUsage.toolDurationMs` / `TurnUsage.pricebookCost`、工具输出 chunk
+  与 `TurnAssistantToolPart` 的 `durationMs`、`usage-update` chunk 的 `observedUsd` /
+  `limitUsd` / `priceTableVersion` / `unpricedModelEstimated` / `callCount`。
+
+`dist/realtime.d.ts` 无非注释差异。
+
+### 迁移说明
+
+没有破坏性变化；不用新方法、新入参时行为与 1.28.0 相同。
+
 ## 1.28.0
 
 本版带上 1.27.1 之后合入 main 的公开面变化：`sessions.sendTurn` 的单回合预算 `maxCostUsd`

package/README.md

@@ -504,3 +504,27 @@ try {
 调用方必须实现 `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 秒，允许降低，不允许增加。
+
+### 统一凭据管理
+
+```ts
+await agenthub.credentials.revoke(credentialRef, { mode: "retire" });
+```
+
+接受 `sec_*`、`vcrd_*`、`llmp_*`。需要对应类型的原有 write scope：项目密钥 `secrets:write`、模型服务 `model-services:write`、托管 MCP `managed-mcps:write`、网络 / git 凭据 `vaults:write`；另校验项目权限和普通 vault 的 actor 所有权。返回 `{ credentialRef, mode }`，不含凭据值。retire 沿用各类现有行为：模型服务与托管 MCP 保留存量会话解析；项目密钥、网络凭据与 git token 在下次取用时失效。既有归档和引用护栏继续生效。缺省 `mode` 为 `revoke`，需预留的 `vaults:admin`（当前不可对平台 token 签发），当前签发的平台 token 因缺少该 scope 返回 403 `CREDENTIAL_FORBIDDEN`；501 `CREDENTIAL_REVOKE_NOT_ENABLED` 仅是授权保留调用方通过校验后的语义，不修改凭据。可选 `reason` 只作为请求上下文，不持久化。
+
+维护者验收（仅限源码仓库）：npm 包不包含探针脚本。release 从 [Pilot 源码中的验收脚本](https://github.com/kanyun-ai-explore/pilot/blob/main/packages/agenthub-sdk/scripts/probe-credential-retire.mjs) 取用，使用隔离 testing 凭据，通过 agentcred 注入 `AGENTHUB_PLATFORM_TOKEN`，在仓库根目录执行：
+
+```bash
+node packages/agenthub-sdk/scripts/probe-credential-retire.mjs --url "$B1_TEST_PLANE_URL" --ref "$B1_TEST_SECRET_REF" --mode retire --expect 200
+```
+
+该命令会执行既有退场 / 归档动作；只使用专用验收凭据。探针不重试，输出状态、错误码和身份，不输出凭据值。
+
+## Credential entry tickets
+
+Use `client.credentialEntryTickets.create(projectId, { target, returnUrl, ttlSeconds? }, { idempotencyKey? })` to get a short-lived administrator entry link. `target` is `{secretId}` (independent `env_jit`, `secrets:write`) or `{managedMcpId, field: "accessToken" | "secretValues.<KEY>"}` (`managed-mcps:write`). The callback requires controlled registration for the authenticated subject and tenant. TTL is an integer from 1 to 900 seconds, default 900.
+
+Read `result.url` explicitly to hand it to an administrator; JSON serialization and Node inspect hide it. Never log the link or HTTP body. Filling still requires portal CAS login and project management permission; this resource has no fill method. `get(projectId, ticketId)` and `revoke(projectId, ticketId)` return `{ticketId, status, expiresAt}` and require the issuer's current write scope and project access.
+
+With an idempotency key, pending retries return the same ID, URL and expiry; different request bytes return 409. Terminal or expired retries return 410 without a URL. The key is retained as a capability-free tombstone for 24 hours from creation; use a new key to issue a new ticket. Package publication is coordinated separately from the workspace API.