@kanyun-ai-infra/agenthub 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 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/dist/index.cjs

@@ -564,9 +564,10 @@ var EXECUTOR_FORMAT_REGISTRY = {
       toolFiltering: false,
       approvals: false
     },
-    // Empty until every PI-P1 entry condition holds (pi spec PI-M1 / PI-P2):
-    // no model is offered, so no pi Revision can be published.
-    allowedModels: { kind: "exactIds", ids: [] },
+    // Shape only (pi spec PI-M1): the worker registers the chosen id at run
+    // time (PI-M3), so any id the bound model service serves can run. Not a
+    // reachability guard; PI-P2's three guards keep pi unreachable.
+    allowedModels: { kind: "wellFormedId" },
     // Pi's MCP goes through managed MCP only (owner 2026-09-28): no rush
     // direct references, no self-loaded MCP client extension.
     mcpMode: "bridge",
@@ -2731,6 +2732,7 @@ var STANDARD_EVENT_TYPES = Object.keys(
 );
 var StandardEventTypeSchema = import_zod16.z.enum(STANDARD_EVENT_TYPES);
 var PUSH_BACK_PATTERNS_MAX = 50;
+var COMMIT_AUTHOR_LDAP_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
 var BRANCH_CHARS_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 function isPushBackBranchName(branch) {
   if (branch.length > 255 || !BRANCH_CHARS_RE.test(branch)) return false;
@@ -2745,7 +2747,7 @@ var PushBackPolicySchema = import_zod24.z.object({
   projectId: import_zod24.z.string(),
   branchPatterns: import_zod24.z.array(import_zod24.z.string())
 });
-var PodAgentPushPolicySchema = import_zod24.z.object({
+var PodAgentPushBackPolicySchema = import_zod24.z.object({
   mode: import_zod24.z.literal("push_back"),
   /** The repo's default branch; pushing to it is refused. */
   defaultBranch: import_zod24.z.string().min(1).optional(),
@@ -2756,6 +2758,26 @@ var PodAgentPushPolicySchema = import_zod24.z.object({
   /** PB-11: the session's frozen commit author email. */
   authorEmail: import_zod24.z.string().min(1).optional()
 }).strict();
+var PodAgentRondoPushPolicySchema = import_zod24.z.object({
+  mode: import_zod24.z.literal("rondo"),
+  /** The session's `repoUrl`; clone of any other repo is refused. */
+  repoUrl: import_zod24.z.string().min(1).optional(),
+  /** The session's `repoRef`: the only branch clone checks out and push targets. */
+  branch: import_zod24.z.string().min(1).optional(),
+  /** The remote default branch frozen at creation (sync base, path-guard tip). */
+  defaultBranch: import_zod24.z.string().min(1).optional(),
+  /** The session's frozen `pushBackPaths` (RS-2 globs). */
+  paths: import_zod24.z.array(import_zod24.z.string().min(1)).optional(),
+  /** PB-11: the session's frozen commit author email. */
+  authorEmail: import_zod24.z.string().min(1).optional()
+}).strict();
+var PodAgentPushPolicySchema = import_zod24.z.discriminatedUnion("mode", [
+  PodAgentPushBackPolicySchema,
+  PodAgentRondoPushPolicySchema
+]);
+var PUSH_BACK_PATHS_MAX = 50;
+var PUSH_BACK_PATH_MAX_LENGTH = 255;
+var REQUESTED_BY_MAX = 20;
 var POD_AGENT_ENDPOINT_PORT = 8790;
 var AgentPortSpecSchema = import_zod25.z.object({
   name: import_zod25.z.string().min(1).max(63),
@@ -2966,7 +2988,12 @@ var FailureReasonCodeSchema = import_zod13.z.enum([
    * delivery pipeline PB-3：`push_back` 会话复活重放的那一轮被拒（开关关、或分支已不再通过项目
    * 推回策略）。什么都不发、不回落 MR；`source: control_plane`。
    */
-  "PUSH_BACK_DELIVERY_REJECTED"
+  "PUSH_BACK_DELIVERY_REJECTED",
+  /**
+   * delivery pipeline RS-6：Rondo 会话复活重放的那一轮读不到 GitLab（超时 / 5xx / 401 / 403），不发；
+   * 会话按 REV-EX-F 回到终止态但不记仓库复核的终止理由，下一轮照常复活重试。`source: control_plane`。
+   */
+  "RONDO_REPO_CHECK_UNAVAILABLE"
 ]);
 var WorkerHealthStateSchema = import_zod13.z.enum(["heartbeat", "ready", "failed"]);
 var WorkerHealthReasonCodeSchema = import_zod13.z.enum([
@@ -3641,7 +3668,6 @@ var PodAgentStartWorkerResponseSchema = import_zod13.z.discriminatedUnion("kind"
   })
 ]);
 var SessionDeliveryModeSchema = import_zod13.z.enum(["merge_request", "direct_push", "push_back"]);
-var COMMIT_AUTHOR_LDAP_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
 var CreateSessionRequestSchema = import_zod13.z.object({
   /**
    * P4 Phase 1.5 — optional caller-supplied resource id. When present, the
@@ -3873,7 +3899,14 @@ var CreateSessionRequestSchema = import_zod13.z.object({
    * 交付 commit 的作者是 `<ldap>@<AGENTHUB_COMMIT_EMAIL_DOMAIN>`，建会话时算好冻结。
    * `ldap` 须是项目成员；省略 = 取会话发起人。只对 `push_back` 有意义，别的模式带它 → 400。
    */
-  commitAuthor: import_zod13.z.object({ ldap: import_zod13.z.string().regex(COMMIT_AUTHOR_LDAP_PATTERN) }).strict().optional()
+  commitAuthor: import_zod13.z.object({ ldap: import_zod13.z.string().regex(COMMIT_AUTHOR_LDAP_PATTERN) }).strict().optional(),
+  /**
+   * Rondo 会话（delivery pipeline RS-1 / RS-2）：带这个键 = 在 band 项目之外的目标仓库上推回，
+   * 只许改命中这些 glob 的路径。schema 只挡离谱的体积；1–50 条、每条的形状由 control-plane
+   * 在 RS-1 的开关与身份门之后判，答 400 `PUSH_BACK_PATHS_INVALID`（不让一个不该开 Rondo 会话的
+   * 调用方先拿到路径语法的反馈）。
+   */
+  pushBackPaths: import_zod13.z.array(import_zod13.z.string().max(PUSH_BACK_PATH_MAX_LENGTH * 4)).max(PUSH_BACK_PATHS_MAX * 10).optional()
 }).strict().refine(
   (data) => {
     if (!data.vault_ids) return true;
@@ -7565,6 +7598,7 @@ var SandboxStatusSchema = import_zod35.z.enum([
   "creating",
   "running",
   "idle",
+  "paused",
   "destroying",
   "destroyed",
   "error"
@@ -8106,6 +8140,12 @@ var PilotCoderRunConfigV1Schema = import_zod38.z.object({
     requestedBy: import_zod38.z.string().min(1).max(255),
     submittedBy: import_zod38.z.string().min(1).max(255)
   }).strict().optional(),
+  /**
+   * delivery pipeline RS-10：Rondo 会话冻结的 `pushBackPaths`，只随 `pushBackBranch` 出现。worker
+   * 交付 commit 前用它检查待提交路径，有越界的就以 `push:policy_violation` 失败、零 push；权威
+   * 判定在 pod-agent 的路径守卫（RS-9）。WC-1 版本 3 的必需字段：低版本 Pod 拒发、不裁剪。
+   */
+  pushBackPaths: import_zod38.z.array(import_zod38.z.string().min(1).max(PUSH_BACK_PATH_MAX_LENGTH)).min(1).max(PUSH_BACK_PATHS_MAX).optional(),
   /**
    * AgentHub eval (T6/闸2b) — hard-off switch for ALL delivery side effects.
    * When true, agent-worker skips the delivery loop entirely (no git push, no
@@ -8187,6 +8227,8 @@ var RUN_CONFIG_FIELD_MIN_CONTRACT_VERSION = {
   pushBackBranch: 2,
   commitAuthor: 2,
   commitTrailers: 2,
+  // Rondo sessions (delivery pipeline RS-10): required, its readers also prove pod-agent knows RS-9.
+  pushBackPaths: 3,
   deliveryDisabled: 0,
   fixturesRepoUrl: 0,
   fixturesRef: 0,
@@ -8744,7 +8786,13 @@ var PlatformScopeSchema = import_zod46.z.enum([
    * 不经签发入口，由校验时的主体清单兜底）。所以它**不进**
    * `ADMIN_ONLY_SCOPE_VALUES`——那张表的语义是「admin 可以签」，而这里 admin 也不行。
    */
-  "actor:delegate"
+  "actor:delegate",
+  /**
+   * 建 Rondo 会话（delivery pipeline RS-1：带 `pushBackPaths` 的 `POST /api/sessions`）。持有者
+   * 能让 Rondo 的 GitLab 账号在它有成员资格的任何仓库上推送，量级与 `actor:delegate` 同：
+   * **仅系统签发**，token 主人还要在 `FIRST_PARTY_RONDO_PRINCIPALS` 里。
+   */
+  "rondo-sessions:create"
 ]);
 var X_PILOT_ACT_AS_HEADER = "x-pilot-act-as";
 var ScopeTemplateSchema = import_zod46.z.enum([
@@ -8794,13 +8842,16 @@ var NEVER_IN_PRESET_SCOPE_VALUES = [
   "templates:promote",
   // 代表声明的准入条件：仅系统签发（见 SYSTEM_ISSUED_ONLY_SCOPE_VALUES），预设里出现它 =
   // 每张预设 token 都离「代表任意用户」只差一个主体条件。
-  "actor:delegate"
+  "actor:delegate",
+  // 建 Rondo 会话：仅系统签发（RS-1）。
+  "rondo-sessions:create"
 ];
 var NEVER_IN_PRESET_SCOPES = new Set(
   NEVER_IN_PRESET_SCOPE_VALUES
 );
 var SYSTEM_ISSUED_ONLY_SCOPE_VALUES = [
-  "actor:delegate"
+  "actor:delegate",
+  "rondo-sessions:create"
 ];
 var SYSTEM_ISSUED_ONLY_SCOPES = new Set(
   SYSTEM_ISSUED_ONLY_SCOPE_VALUES
@@ -12353,7 +12404,14 @@ var SessionTurnRequestSchema = import_zod73.z.object({
    * splices the URLs into `promptText` as a trailing context block; the
    * worker (LLM) treats them as references it can fetch.
    */
-  attachments: import_zod73.z.array(AttachmentMetaSchema).max(20).optional()
+  attachments: import_zod73.z.array(AttachmentMetaSchema).max(20).optional(),
+  /**
+   * delivery pipeline RS-7: who asked for this turn (1–20 ldaps). Only a Rondo
+   * session accepts it (other sessions answer 400 `REQUESTED_BY_NOT_ALLOWED`);
+   * it becomes this turn's `Requested-by` trailer, the commit author stays the
+   * session's frozen one.
+   */
+  requestedBy: import_zod73.z.array(import_zod73.z.string().regex(COMMIT_AUTHOR_LDAP_PATTERN)).min(1).max(REQUESTED_BY_MAX).optional()
 }).strict().superRefine((value, ctx) => {
   var _a;
   if (value.text.length > 0) return;
@@ -13607,6 +13665,11 @@ var FileAgentPiDefinitionSchema = import_zod83.z.object({
    * CI 红过一次后补上（agenthub-cli `check --refs` 按三臂共面读该键）。
    */
   modelService: FileAgentModelServiceNameSchema.optional(),
+  environment: FileAgentEnvironmentNameSchema.optional(),
+  mcpServers: FileAgentMcpServerListSchema.optional(),
+  setupScript: WorkloadManifestSetupScriptSchema.optional(),
+  setupScriptFile: FileAgentSetupScriptFileSchema.optional(),
+  env: SessionConfigValuesSchema.optional(),
   memory: FileAgentMemorySchema.optional(),
   channels: WorkloadManifestChannelsSchema.optional(),
   pi: import_zod83.z.object({}).strict().optional(),
@@ -13614,6 +13677,9 @@ var FileAgentPiDefinitionSchema = import_zod83.z.object({
   /** promote 门禁档位 —— 与其它臂同义同形（#4870 G1，门禁与执行器正交）。 */
   promoteGate: PromoteGateModeSchema.optional()
 }).strict();
+function isFileAgentSandboxDefinition(definition) {
+  return definition.format === "claude_code" || definition.format === "pi";
+}
 var FileAgentDefinitionSchema = import_zod83.z.discriminatedUnion("format", [
   FileAgentClaudeCodeDefinitionSchema,
   FileAgentLiveDefinitionSchema,
@@ -13622,8 +13688,8 @@ var FileAgentDefinitionSchema = import_zod83.z.discriminatedUnion("format", [
   for (const violation of findRealtimeVoiceViolations(definition)) {
     ctx.addIssue(__spreadValues({ code: import_zod83.z.ZodIssueCode.custom }, violation));
   }
-  if (definition.format !== "claude_code") return;
-  if (definition.systemPrompt !== void 0 && definition.systemPromptFile !== void 0) {
+  if (!isFileAgentSandboxDefinition(definition)) return;
+  if (definition.format === "claude_code" && definition.systemPrompt !== void 0 && definition.systemPromptFile !== void 0) {
     ctx.addIssue({
       code: import_zod83.z.ZodIssueCode.custom,
       path: ["systemPromptFile"],
@@ -13752,6 +13818,11 @@ var CLAUDE_CODE_ONLY_SECTION_KEYS = new Set(
     (key) => !(key in FileAgentLiveDefinitionSchema.shape)
   )
 );
+var CLAUDE_CODE_ONLY_KEYS_ON_PI = new Set(
+  Object.keys(FileAgentClaudeCodeDefinitionSchema.shape).filter(
+    (key) => !(key in FileAgentPiDefinitionSchema.shape)
+  )
+);
 var WECOM_FOREIGN_INBOUND_KEYS = Object.keys(SlackChannelInboundSchema.shape).filter(
   (key) => !(key in ChannelInboundSchema.shape)
 );
@@ -14306,8 +14377,9 @@ var ProjectBillingResponseSchema = import_zod90.z.object({
     tokens: ProjectBillingTokenTotalsSchema,
     /**
      * CLI 自报成本参考值（§3：`cost_usd` 照旧落库，读面可作参考值展示且
-     * **必须标注非平台计价**——标注即 `source`/`note` 两字段）。null =
-     * 区间内无任何上报。
+     * **必须标注非平台计价**——标注即 `source`/`note` 两字段）。只合计
+     * `cost_source = claude_code_cli` 的轮，其它来源不计入（§7-1）。null =
+     * 区间内没有该来源的成本上报。
      */
     costUsdReference: import_zod90.z.object({
       amountUsd: import_zod90.z.number().nonnegative(),