@kanyun-ai-infra/agenthub 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.15.0
+
+浏览器实时语音入口新增播放对齐、页面工具执行与播放输出节点；其余为随共享契约内联的变化。
+
+### 新增（`@kanyun-ai-infra/agenthub/realtime`）
+
+- `onTranscriptPlayed(transcript)`：assistant 转写片段在音频实际播放到该片段时逐段触发，载荷带墙钟 `playedAt`。依赖网关在转写帧上带 `audioOffsetMs`；没有偏移的旧网关不触发此回调，被用户打断清空的片段也不触发。
+- `onPlaybackState(state)`：`speaking` / `listening`，按实际可闻的播放状态触发，与按模型生成进度的 `onState` 区分。队列播干、播放被打断或通话停止时回到 `listening`。
+- `onTranscript` 的 assistant 帧新增可选 `audioOffsetMs`：该片段在本轮音频中的起始毫秒数，用于把字幕或画面切到正在播放的位置。
+- `onToolCall(call)`：执行 `voice.realtime.tools` 声明的模型工具调用；`call` 含 `callId`、`name`、`args`，可选 `turnSeq`。返回值作为工具结果回传（JSON，至多 32 KiB）。未提供处理函数回 `tool_unavailable`，处理函数抛错回 `tool_failed`，结果超限回 `tool_result_too_large`；页面不答时网关 10 秒后自行以 `tool_timeout` 答复，不会把模型卡死。
+- `outputNode(context)`：把播放输出接到页面自建的音频节点（如变调等后处理），由页面继续接到 `context.destination`。缺省直连输出。
+- 新导出类型：`RealtimeTranscriptPlayed`、`RealtimePlaybackState`、`RealtimeToolCall`。
+
+### 随共享契约内联的变化
+
+- agent 定义的 `voice.realtime` 新增可选 `tools`（1–16 个）：每项含 `name`（匹配 `^[A-Za-z_][A-Za-z0-9_]{0,63}$`，重名拒绝）、`description`（1–1024 字符）与可选 `parameters`（JSON Schema 子集，嵌套至多 6 层、节点至多 128、序列化至多 8 KiB）。`publishVersion` / `applyManifest` 的本地校验接受该字段；不声明时行为不变。
+- `voice.realtime` 新增可选 `greetOnConnect`：开启时网关在首通建立上游会话后替 agent 发一次初始文本回合，模型按 system prompt 主动开口；缺省或 `false` 关闭，只对首通生效，重连与接手不重发。
+
+### 会话
+
+- `sessions.create` 带 `memorySubjects` 的请求现在可以领取预热池：声明的业务主体替换池模板铸出的主体；`idempotencyScope` / `idempotencyKey` 与 `memorySubjects` 不再使请求失去领取资格。本次只有注释与文档变化，领取行为由服务端决定；服务端未升级时请求仍照旧冷启。
+
+### 其他
+
+- 语音开关的文档措辞改为 kill switch `voice_turns_disabled`（及同类 `*_DISABLED`），公开方法签名不变。
+- 随包 `SKILL.md` 补充实时语音接入走查。
+
+### 迁移说明
+
+- 使用 `onTranscriptPlayed`、`onPlaybackState`、`onToolCall` 或 `outputNode` 的接入方须升级到 `@kanyun-ai-infra/agenthub@1.15.0`。1.14.0 没有这些回调；旧 SDK 在声明工具的 agent 上会忽略 `tool_call`，模型要等网关 10 秒超时答复后才继续。
+
 ## 1.14.0
 
 ### 随共享契约内联的语音变化

package/dist/index.cjs

@@ -3576,6 +3576,9 @@ var CreateSessionRequestSchema = import_zod10.z.object({
    *
    * 解析只发生一次、在会话创建事务内，结果冻结进 `sessions.memory_subjects`；写侧
    * （抽取写回）与读侧（召回）之后都只读那一列（I7 写读同源）。
+   *
+   * 带它的请求**照样能领预热池**：领取收尾在同一条 UPDATE 里按这份声明重算冻结列（替换池模板
+   * 铸的业务主体，`[]` = 只剩 agent 主体）；绑不进去就退冷启，不会交出没有声明主体的会话。
    */
   memorySubjects: import_zod10.z.array(SessionMemorySubjectDeclarationSchema).max(MAX_SESSION_MEMORY_SUBJECTS).optional(),
   /**
@@ -3596,8 +3599,9 @@ var CreateSessionRequestSchema = import_zod10.z.object({
    * `PILOT_END_USER_ID`、记忆主体（见下）、create 响应 `data.session.user`。
    *
    * **带它不吃池**：请求携带本字段即退出预热领用资格
-   * （`canServeFromPrewarmPool`），与 `memorySubjects` 同一条规则——池里暖好的会话
-   * 在调用方出现之前就冻结了身份，领用时换不掉。已知访客换 agent 应冷启带既有 id。
+   * （`canServeFromPrewarmPool`）——池里暖好的会话在调用方出现之前就冻结了身份，领用时
+   * 换不掉。已知访客换 agent 应冷启带既有 id。（`memorySubjects` 不受这条限制：它在领取
+   * 收尾时绑定，见该字段。）
    *
    * **不隐含记忆声明**：本字段本身不使这个 id 成为任何记忆主体；要让记忆落到它
    * 名下，冷启路径须同时在 `memorySubjects` 里声明它（池路径由
@@ -4160,7 +4164,8 @@ var WorkloadManifestErrorCodeSchema = import_zod4.z.enum([
   // `statusForManifestError`. Additive widening = patch (see
   // `WORKLOAD_SLUG_TAKEN` above).
   // - `LIVE_AGENTS_DISABLED` — the Revision's snapshot is `format: live` while
-  //   `live_agents_enabled` is off. Same criterion as before; it used to throw
+  //   the kill switch `live_agents_disabled` is on (before #5069: `live_agents_enabled`
+  //   off). Same criterion as before; it used to throw
   //   the generic `MANIFEST_VALIDATION_ERROR`. Pipeline join reports the same
   //   condition earlier as `FILE_AGENT_LIVE_DISABLED`.
   // - `LIVE_REVISION_UNSUPPORTED` — the merged, frozen live snapshot carries a
@@ -4515,7 +4520,79 @@ var RealtimeVoiceNameSchema = import_zod4.z.enum([
   "Sadaltager",
   "Sulafat"
 ]);
-var WorkloadManifestRealtimeVoiceSchema = import_zod4.z.object({
+var RealtimeToolParameterSchema = import_zod4.z.lazy(
+  () => import_zod4.z.object({
+    type: import_zod4.z.enum(["string", "number", "integer", "boolean", "array", "object"]).optional(),
+    description: import_zod4.z.string().max(1024).optional(),
+    enum: import_zod4.z.array(import_zod4.z.string().max(256)).max(64).optional(),
+    nullable: import_zod4.z.boolean().optional(),
+    items: RealtimeToolParameterSchema.optional(),
+    properties: import_zod4.z.record(import_zod4.z.string().max(64), RealtimeToolParameterSchema).optional(),
+    required: import_zod4.z.array(import_zod4.z.string().max(64)).max(32).optional()
+  }).strict()
+);
+function toolParameterProblem(parameters) {
+  if (parameters === void 0) return void 0;
+  let nodes = 0;
+  let problem;
+  const visit = (node, depth) => {
+    var _a, _b;
+    if (problem !== void 0) return;
+    nodes += 1;
+    if (depth > 6) {
+      problem = "tool parameters nest deeper than 6 levels";
+      return;
+    }
+    if (nodes > 128) {
+      problem = "tool parameters contain more than 128 nodes";
+      return;
+    }
+    if (node.type === "array" && node.items === void 0) {
+      problem = "an array parameter must declare items";
+      return;
+    }
+    if (node.required !== void 0) {
+      const declared = new Set(Object.keys((_a = node.properties) != null ? _a : {}));
+      const missing = node.required.find((name) => !declared.has(name));
+      if (missing !== void 0) {
+        problem = `required parameter ${missing} is not declared in properties`;
+        return;
+      }
+    }
+    for (const child of Object.values((_b = node.properties) != null ? _b : {})) visit(child, depth + 1);
+    if (node.items !== void 0) visit(node.items, depth + 1);
+  };
+  visit(parameters, 1);
+  if (problem !== void 0) return problem;
+  if (new TextEncoder().encode(JSON.stringify(parameters)).length > 8192)
+    return "tool parameters exceed 8192 bytes";
+  return void 0;
+}
+var WORKLOAD_MANIFEST_REALTIME_TOOLS_MAX_LENGTH = 16;
+var WorkloadManifestRealtimeToolSchema = import_zod4.z.object({
+  name: import_zod4.z.string().regex(
+    /^[A-Za-z_][A-Za-z0-9_]{0,63}$/,
+    "tool name must be an identifier of at most 64 chars"
+  ),
+  description: import_zod4.z.string().min(1).max(1024),
+  parameters: RealtimeToolParameterSchema.optional()
+}).strict();
+var WorkloadManifestRealtimeToolListSchema = import_zod4.z.array(WorkloadManifestRealtimeToolSchema).min(1).max(WORKLOAD_MANIFEST_REALTIME_TOOLS_MAX_LENGTH).superRefine((tools, ctx) => {
+  const names = /* @__PURE__ */ new Set();
+  for (const [index, tool] of tools.entries()) {
+    if (names.has(tool.name))
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "name"],
+        message: "tool names must be unique"
+      });
+    names.add(tool.name);
+    const problem = toolParameterProblem(tool.parameters);
+    if (problem !== void 0)
+      ctx.addIssue({ code: "custom", path: [index, "parameters"], message: problem });
+  }
+});
+var RealtimeVoiceWireSchema = import_zod4.z.object({
   provider: import_zod4.z.literal("vertex-gemini-live"),
   model: import_zod4.z.enum(["gemini-3.8-live", "gemini-live-2.5-flash-native-audio"]),
   voice: RealtimeVoiceNameSchema,
@@ -4526,7 +4603,20 @@ var WorkloadManifestRealtimeVoiceSchema = import_zod4.z.object({
       return false;
     }
   }, "language must be a BCP-47 language tag").optional(),
-  turnDetection: import_zod4.z.object({ silenceMs: import_zod4.z.number().int().positive() }).strict().optional()
+  turnDetection: import_zod4.z.object({ silenceMs: import_zod4.z.number().int().positive() }).strict().optional(),
+  /**
+   * 接通即开讲（#5221）：开启时网关在通话首次建立上游会话后替 agent 发一次初始文本回合，
+   * 模型按 system prompt 主动开口。缺省 / `false` 关闭，行为与声明前一致。只对首通生效：
+   * 上游重连与带原 callId 的接手不重发。
+   */
+  greetOnConnect: import_zod4.z.boolean().optional()
+}).strict();
+var WorkloadManifestRealtimeVoiceSchema = RealtimeVoiceWireSchema.extend({
+  /**
+   * Declared client tools. Optional and absent by default: an agent without it behaves exactly
+   * as before, and the claim to an older gateway carries no tools key at all.
+   */
+  tools: WorkloadManifestRealtimeToolListSchema.optional()
 }).strict();
 var WorkloadManifestVoiceSchema = import_zod4.z.object({
   realtime: WorkloadManifestRealtimeVoiceSchema.optional(),
@@ -8884,6 +8974,20 @@ var EnvironmentRepointRecordSchema = import_zod59.z.object({
   actor: import_zod59.z.string().nullable(),
   createdAt: import_zod59.z.coerce.date()
 }).strict();
+var EnvironmentExecutorWarningRevisionSchema = import_zod59.z.object({
+  revisionId: import_zod59.z.string().uuid(),
+  /** Which pointer of the slot carries the Revision. */
+  arm: import_zod59.z.enum(["stable", "canary"]),
+  format: import_zod59.z.string(),
+  protocolVersion: import_zod59.z.string(),
+  /** `absent` = judged as ENVCAP-3 (no readable declaration for the image). */
+  declaration: import_zod59.z.enum(["absent", "present"]),
+  /** Where the judged image came from; `kind` discriminates the remaining keys. */
+  capabilitySource: import_zod59.z.object({ kind: import_zod59.z.string() }).passthrough()
+}).strict();
+var EnvironmentExecutorWarningSchema = import_zod59.z.object({
+  revisions: import_zod59.z.array(EnvironmentExecutorWarningRevisionSchema).min(1)
+}).strict();
 var EnvironmentReferenceSchema = import_zod59.z.object({
   workloadId: import_zod59.z.string().uuid(),
   workloadSlug: import_zod59.z.string(),
@@ -9691,7 +9795,7 @@ var VOICE_ERROR_CODES = {
   REALTIME_CAPACITY_EXCEEDED: 409,
   /** The platform concurrency store (realtime Redis) is unavailable; retry. */
   REALTIME_ADMISSION_UNAVAILABLE: 503,
-  /** `voice_turns_enabled` 关态时任何语音回合派发被拒（紧急停止；VT-1）。 */
+  /** 紧急关闭 `voice_turns_disabled` 打开时任何语音回合派发被拒（VT-1）。 */
   VOICE_TURNS_DISABLED: 400,
   /** 语音附件时长 >60 秒或大小 >2MB（VA-3，上限只在语音路径）。 */
   VOICE_INPUT_TOO_LONG: 400,
@@ -11617,8 +11721,10 @@ var EvalTriggerSchema = import_zod82.z.enum([
 ]);
 var EvalSeveritySchema = import_zod82.z.enum(["gate", "soft"]);
 var EvalGraderTypeSchema = import_zod82.z.enum(["transcript", "file", "llm", "script", "reply"]);
+var EvalLlmToolsSchema = import_zod82.z.enum(["full", "calls", "none"]);
 var EvalPassPolicySchema = import_zod82.z.enum(["all", "any"]);
 var EvalSuitePurposeSchema = import_zod82.z.enum(["regression", "capability"]);
+var EvalSuiteGateDowngradeSchema = import_zod82.z.enum(["allow", "never"]);
 var EVAL_SKIP_REASON_MAX = 2048;
 var EvalSuiteSkipSchema = import_zod82.z.object({ reason: import_zod82.z.string().min(1).max(EVAL_SKIP_REASON_MAX) }).strict();
 var EvalSkippedSuiteSchema = import_zod82.z.object({ path: import_zod82.z.string().min(1), reason: import_zod82.z.string().min(1) }).strict();
@@ -11687,6 +11793,10 @@ var EvalFileShorthandExpectSchema = import_zod82.z.object({
   matches: import_zod82.z.string().optional()
   // 正则字符串
 }).strict();
+var EvalFileToolSourceSchema = import_zod82.z.object({
+  name: import_zod82.z.string().min(1),
+  part: import_zod82.z.enum(["input", "output", "both"]).optional()
+}).strict();
 var EvalFileGraderSchema = import_zod82.z.object({
   type: import_zod82.z.literal("file"),
   label: EvalGraderLabelSchema,
@@ -11696,7 +11806,12 @@ var EvalFileGraderSchema = import_zod82.z.object({
   files: import_zod82.z.array(EvalFileEntrySchema).min(1).optional(),
   // 简写形式
   path: EvalRelativePathSchema.optional(),
-  expect: EvalFileShorthandExpectSchema.optional()
+  expect: EvalFileShorthandExpectSchema.optional(),
+  /**
+   * #5215：内容来源 = 工具产物而非工作区文件。与 `path` / `files` 恰用其一，
+   * 且必须搭配 `expect`（suite 级 superRefine 校验）。
+   */
+  tool: EvalFileToolSourceSchema.optional()
 }).strict();
 var EvalLlmGraderSchema = import_zod82.z.object({
   type: import_zod82.z.literal("llm"),
@@ -11708,6 +11823,14 @@ var EvalLlmGraderSchema = import_zod82.z.object({
   }),
   dimensions: import_zod82.z.array(import_zod82.z.string().min(1)).optional(),
   threshold: import_zod82.z.number().min(0).max(1),
+  /**
+   * #5215：判官材料是否带工具调用。缺省 `none`（只判回复文本，与既有 suite 的
+   * 判分材料逐字节一致）。optional 字段叠加为增量变更、不升 apiVersion；老
+   * worker 会以 `Unrecognized key` strict 拒（发布次序 = control-worker 先行）。
+   * 工具段改变判分输入，但声明值在 case 对象里、进 `case_definition_digest`，
+   * 因此不升 `engineVersion`（换值即换基线桶，不靠 engineVersion 区分）。
+   */
+  tools: EvalLlmToolsSchema.optional(),
   // 上界对齐 eval_grader_results.grader_version（PG int4，B1 硬列）：graderVersion
   // 是**作者可写**的单调整数，时间戳当版本号（Date.now() ≈ 1.7e12）一次就越界——
   // 越界在解析期 400 告知作者，而不是等写明细行时 22003 连累父行回滚、整个 run
@@ -11754,12 +11877,17 @@ var EvalScriptGraderSchema = import_zod82.z.object({
   expect: EvalScriptExpectSchema.optional()
 }).strict();
 var EvalReplyExpectSchema = import_zod82.z.object({
+  /** 字面子串，不是正则。 */
   includes: import_zod82.z.string().min(1).optional(),
+  /** 字面子串，不是正则；「不许出现某段话」的确定写法见 `notMatches`。 */
   excludes: import_zod82.z.string().min(1).optional(),
   equals: import_zod82.z.string().optional(),
   // 正则字符串；无效正则不在 schema 层拒——按 file grader 的 safeRegex 姿势在
   // 判分侧判"不匹配"，交给断言侧报 failed（不 errored）。
-  matches: import_zod82.z.string().min(1).optional()
+  matches: import_zod82.z.string().min(1).optional(),
+  // 正则字符串，不允许匹配（`excludes` 的正则版）。无效正则**判 failed**而不是
+  // passed：编译不出来时「没有匹配」是假的，绝不能因此绿灯（#5209）。
+  notMatches: import_zod82.z.string().min(1).optional()
 }).strict();
 var EvalReplyGraderSchema = import_zod82.z.object({
   type: import_zod82.z.literal("reply"),
@@ -12003,12 +12131,28 @@ var EvalSuiteSchema = import_zod82.z.object({
   kind: import_zod82.z.literal(EVAL_SUITE_KIND),
   purpose: EvalSuitePurposeSchema.optional(),
   // U2，默认 regression
+  gateDowngrade: EvalSuiteGateDowngradeSchema.optional(),
+  // #5216，默认 allow
   skip: EvalSuiteSkipSchema.optional(),
   // §4 声明跳过（带必填理由）
+  /**
+   * #5215：pipeline 面按 **advisory** 跑——照常建 eval run 并后台执行，但不进
+   * eval step 的等待、不进 conclusion 折叠，**不挡门禁**。结果仍挂在结论的
+   * `evalRunIds` 下，流水线详情可见。缺省 false。与 `skip` 互斥（拒绝组合：
+   * 一个说「不跑」一个说「跑但不判」，语义冲突）。
+   */
+  advisory: import_zod82.z.boolean().optional(),
   defaults: EvalSuiteDefaultsSchema.optional(),
   cases: import_zod82.z.array(EvalCaseSchema).min(1)
 }).strict().superRefine((suite, ctx) => {
   var _a, _b;
+  if (suite.advisory === true && suite.skip != null) {
+    ctx.addIssue({
+      code: import_zod82.z.ZodIssueCode.custom,
+      path: ["advisory"],
+      message: "`advisory: true` and `skip` are mutually exclusive \u2014 skip means the suite does not run in the pipeline at all; advisory means it runs but is excluded from the gate"
+    });
+  }
   const seen = /* @__PURE__ */ new Set();
   suite.cases.forEach((c, ci) => {
     var _a2, _b2, _c, _d, _e;
@@ -12131,11 +12275,15 @@ var EvalSuiteSchema = import_zod82.z.object({
       if (g.type === "file") {
         const hasFiles = g.files != null;
         const hasShorthand = g.path != null && g.expect != null;
-        if (hasFiles === hasShorthand) {
+        const hasTool = g.tool != null && g.expect != null;
+        const sourceCount = [hasFiles, hasShorthand, hasTool].filter(Boolean).length;
+        const strayPath = g.path != null && g.expect == null;
+        const strayTool = g.tool != null && g.expect == null;
+        if (sourceCount !== 1 || strayTool || strayPath && !hasFiles) {
           ctx.addIssue({
             code: import_zod82.z.ZodIssueCode.custom,
             path: ["cases", ci, "graders", gi],
-            message: "file grader must use either `files[]` or `{path, expect}`, not both/neither"
+            message: "file grader must use exactly one of `files[]`, `{path, expect}` or `{tool, expect}` (tool = assert on a tool call's input/output instead of a workspace file); a bare `path` without `expect` is ignored only when `files[]` is present (legacy tolerance)"
           });
         }
       }
@@ -12173,12 +12321,12 @@ var EvalSuiteSchema = import_zod82.z.object({
         }
         const e = g.expect;
         const hasEquals = e.equals != null;
-        const hasOthers = e.includes != null || e.excludes != null || e.matches != null;
+        const hasOthers = e.includes != null || e.excludes != null || e.matches != null || e.notMatches != null;
         if (hasEquals && hasOthers) {
           ctx.addIssue({
             code: import_zod82.z.ZodIssueCode.custom,
             path: ["cases", ci, "graders", gi, "expect"],
-            message: "reply grader `expect.equals` is mutually exclusive with includes/excludes/matches"
+            message: "reply grader `expect.equals` is mutually exclusive with includes/excludes/matches/notMatches"
           });
         }
         if (!hasEquals && !hasOthers) {
@@ -13021,7 +13169,7 @@ var OnlineReplyGraderSchema = EvalReplyGraderSchema.pick({ type: true, label: tr
   threshold: forbiddenThreshold,
   expect: EvalReplyExpectSchema.pick({ excludes: true, matches: true })
 }).strict();
-var OnlineLlmToolsSchema = import_zod83.z.enum(["full", "calls", "none"]);
+var OnlineLlmToolsSchema = EvalLlmToolsSchema;
 var onlineLlmFields = EvalLlmGraderSchema.pick({
   type: true,
   label: true,
@@ -13727,7 +13875,12 @@ var RealtimeClaimResponseSchema = import_zod87.z.object({
   credentialSource: import_zod87.z.enum(REALTIME_CREDENTIAL_SOURCES).optional(),
   config: import_zod87.z.object({
     systemPrompt: import_zod87.z.string(),
-    voice: WorkloadManifestRealtimeVoiceSchema,
+    voice: RealtimeVoiceWireSchema,
+    /**
+     * Client-executed tools frozen with the call. Stripped by readers that do not know it, which
+     * is the intended rolling-deploy story: an older gateway answers the call without tools.
+     */
+    tools: WorkloadManifestRealtimeToolListSchema.optional(),
     recording: import_zod87.z.boolean().default(false),
     upstream: RealtimeUpstreamCredentialSchema.optional()
   })
@@ -15464,13 +15617,13 @@ var SessionsResource = class {
    * The codes and their statuses are the server's voice error-code table.
    *
    * **`VOICE_TURNS_DISABLED` is NOT one of them on this path**, despite being
-   * in that table: it answers a NON-empty-text turn while `voice_turns_enabled`
-   * is off, and this method always sends `text: ""`. The switch being off is
+   * in that table: it answers a NON-empty-text turn while the kill switch
+   * `voice_turns_disabled` is on, and this method always sends `text: ""`. The switch being on is
    * refused one step earlier as the ordinary empty-text `400`
    * `VALIDATION_ERROR` (issue path `["text"]`).
    *
    * **Four different causes produce that one 400, and the body does not
-   * distinguish them**: the switch off; the agent not declaring `voice.input`;
+   * distinguish them**: the switch on; the agent not declaring `voice.input`;
    * an extension outside the voice set; and an attachment that never looks like
    * audio at all — raw bytes passed without `contentType` upload as
    * `application/octet-stream` and fail the empty-text rule in