@kanyun-ai-infra/agenthub 1.24.0 → 1.25.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 本文件从 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）。均不破坏编译。

package/dist/index.cjs

@@ -1074,6 +1074,7 @@ var ManagedMcpStdioEnvDeclSchema = import_zod7.z.discriminatedUnion("kind", [
 ]);
 var MANAGED_MCP_ENV_VAR_MAX_LENGTH = 48;
 var ManagedMcpEnvVarNameSchema = import_zod7.z.string().min(1).max(MANAGED_MCP_ENV_VAR_MAX_LENGTH).regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "env var name must match ^[A-Za-z_][A-Za-z0-9_]*$");
+var MANAGED_MCP_ACCESS_TOKEN_FIELD = "accessToken";
 var ManagedMcpCredentialFieldSchema = import_zod7.z.string().max(MANAGED_MCP_ENV_VAR_MAX_LENGTH + "secretValues.".length).regex(
   /^(?:accessToken|secretValues\.[A-Za-z_][A-Za-z0-9_]*)$/,
   "credential field must be accessToken or secretValues.<KEY>"
@@ -1269,6 +1270,26 @@ var CreateManagedMcpRequestSchema = import_zod7.z.discriminatedUnion("kind", [
   CreateManagedMcpRemoteSchema,
   CreateManagedMcpStdioSchema
 ]);
+var CreatePendingManagedMcpRemoteSchema = CreateManagedMcpRemoteSchema.omit({
+  accessToken: true,
+  customHeaders: true
+}).extend({
+  credentialState: import_zod7.z.literal("pending"),
+  requiredCredentialFields: import_zod7.z.tuple([import_zod7.z.literal(MANAGED_MCP_ACCESS_TOKEN_FIELD)])
+});
+var CreatePendingManagedMcpStdioSchema = CreateManagedMcpStdioSchema.omit({
+  secretValues: true
+}).extend({ credentialState: import_zod7.z.literal("pending") }).refine((v) => {
+  var _a;
+  return Object.values((_a = v.stdioConfig.env) != null ? _a : {}).some((decl) => decl.kind === "secret");
+}, {
+  message: "pending stdio MCP must declare at least one secret env variable",
+  path: ["stdioConfig", "env"]
+});
+var CreatePendingManagedMcpRequestSchema = import_zod7.z.union([
+  CreatePendingManagedMcpRemoteSchema,
+  CreatePendingManagedMcpStdioSchema
+]);
 var UpdateManagedMcpRequestSchema = import_zod7.z.object({
   displayName: import_zod7.z.string().min(1).max(200).optional(),
   /** remote：轮换 access token。 */
@@ -1504,7 +1525,9 @@ var MANAGED_MCP_ERROR_CODES = [
   "managed_mcp_session_identity_requires_gateway",
   "managed_mcp_session_identity_requires_manager",
   /** 写入或替换凭据字段（accessToken / secretValues / customHeaders）要项目管理权（canManage）。 */
-  "managed_mcp_credential_requires_manager"
+  "managed_mcp_credential_requires_manager",
+  /** 值待填的壳不能退场 / 重建（没有值可带）；填完或归档后重来（#5503 第 7 条）。 */
+  "managed_mcp_pending_credential"
 ];
 var ManagedMcpErrorCodeSchema = import_zod7.z.enum(MANAGED_MCP_ERROR_CODES);
 var McpStdioConfigSchema = import_zod11.z.object({
@@ -4148,6 +4171,19 @@ var CreateSessionRequestSchema = import_zod15.z.object({
    * unchanged (STG-R2-3).
    */
   stage: StageSchema.optional(),
+  /**
+   * #5764 / F6 — 钉 `revisionId` 起会话时显式指定 environment（`runtime_templates`
+   * 行 id）。不传 = 现行为（pin 路径 environment 为 null，用 revision 快照的模板）。
+   * 只在带 `revisionId` 时接受（refine `ENVIRONMENT_REQUIRES_REVISION_PIN`）；与 `stage`
+   * 同传仍被拒——stage 路径的环境来自槽位绑定。服务端按建会话的新引用重做可引用性
+   * 校验（同项目或平台共享、未归档），读不到的环境拒绝。
+   */
+  environmentId: import_zod15.z.string().uuid().optional(),
+  /**
+   * 与 {@link environmentId} 配对的版本号。不传 = 解析时该环境的当前可服务版本，
+   * 实际版本冻进会话（与槽位路径同）。传了而不存在 / 不可服务 → 拒绝，不退到 tip。
+   */
+  environmentVersion: import_zod15.z.number().int().positive().optional(),
   /**
    * `.max(255)` 与落库列宽同源（#2876）：`pilot_v2_sessions.idempotency_scope` /
    * `idempotency_key` 都是 `varchar(255)`。这里不设上限时，>255 的值一路穿到 PG 才被
@@ -4400,6 +4436,12 @@ var CreateSessionRequestSchema = import_zod15.z.object({
 ).refine((data) => data.stage === void 0 || data.revisionId === void 0, {
   message: "STAGE_REVISION_MUTEX: stage and revisionId are mutually exclusive \u2014 provide at most one",
   path: ["stage"]
+}).refine((data) => data.environmentId === void 0 || data.revisionId !== void 0, {
+  message: "ENVIRONMENT_REQUIRES_REVISION_PIN: environmentId is only accepted together with revisionId",
+  path: ["environmentId"]
+}).refine((data) => data.environmentVersion === void 0 || data.environmentId !== void 0, {
+  message: "environmentVersion requires environmentId",
+  path: ["environmentVersion"]
 }).refine((data) => data.deliveryMode !== "direct_push" || data.repoUrl !== void 0, {
   message: "DELIVERY_MODE_REQUIRES_REPO_URL: deliveryMode 'direct_push' requires repoUrl \u2014 there is no delivery without a repo",
   path: ["deliveryMode"]
@@ -10972,6 +11014,12 @@ var CreateSecretRequestSchema = import_zod67.z.discriminatedUnion("delivery", [
     value: import_zod67.z.string().min(1).max(SECRET_VALUE_MAX_LENGTH)
   }).strict()
 ]);
+var CreatePendingSecretRequestSchema = import_zod67.z.object({
+  delivery: import_zod67.z.literal("env_jit"),
+  displayName: import_zod67.z.string().min(1).max(SECRET_DISPLAY_NAME_MAX_LENGTH),
+  envKey: SecretEnvKeySchema,
+  credentialState: import_zod67.z.literal("pending")
+}).strict();
 var RotateSecretRequestSchema = import_zod67.z.object({
   value: import_zod67.z.string().min(1).max(SECRET_VALUE_MAX_LENGTH)
 }).strict();
@@ -19921,7 +19969,7 @@ function unwrapEnvelope(envelope, routeLabel, requiredKeys) {
 }
 
 // src/client.ts
-var AGENTHUB_SDK_USER_AGENT = `@kanyun-ai-infra/agenthub/${true ? "1.24.0" : "0.0.0-dev"}`;
+var AGENTHUB_SDK_USER_AGENT = `@kanyun-ai-infra/agenthub/${true ? "1.25.0" : "0.0.0-dev"}`;
 var DEFAULT_CONTROL_PLANE_URL = "https://agenthub-plane.zhenguanyu.com";
 var NON_JSON_ERROR_BODY_MAX_CHARS = 200;
 var clientDefaultSignals = /* @__PURE__ */ new WeakMap();