@kanyun-ai-infra/agenthub 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.14.0
+
+### 随共享契约内联的语音变化
+
+- 回合式语音的 `voice.input.provider` 和 `voice.output.provider` 支持 `dashscope`、`modelgate-chat`，并保留 `modelgate`。`publishVersion` / `publishRevision` 的本地请求校验接受这些值。
+- `voice.input` 和 `voice.output` 各自支持可选的 `modelService`，用于指定该方向使用的项目模型服务名；不填写时沿用主模型服务。显式指定的模型服务无法解析或与 provider 不匹配时拒绝使用，不回落到主模型服务。
+- 随包语音错误码包含 `VOICE_INPUT_FORMAT_UNSUPPORTED`（HTTP 400）：所选语音服务不支持输入音频格式。模型服务不满足语音要求时仍使用 `VOICE_MODEL_SERVICE_UNSUPPORTED`（HTTP 400），模型未获授权时使用 `VOICE_MODEL_NOT_AUTHORIZED`（HTTP 502）。这些是服务端错误，不是本地 schema 校验的错误码。
+
+### 迁移说明
+
+- 使用 `dashscope`、`modelgate-chat` 或语音子段 `modelService` 的接入方须升级到 `@kanyun-ai-infra/agenthub@1.14.0`。1.13.0 的内联请求 schema 会在发送请求前拒绝这些配置并抛出 `ZodError`；仅升级服务端不能更新已安装 SDK 的 schema。
+
 ## 1.13.0
 
 - 浏览器实时语音支持可选 `onEnded({ callId, reason })`：识别通话终态帧 `call_ended` 或关闭码 `4000`，清理采集与播放并停止自动接手；时长上限映射为 `duration_limit`，未知原因映射为 `unknown`。回调每通至多一次，本地 `stop()` 不触发；终态到达后可以手动开始新通话。

package/README.md

@@ -36,6 +36,8 @@ pnpm add @kanyun-ai-infra/agenthub
 
 需要 Node 18+，因为 SDK 使用全局 `fetch`。
 
+回合式语音使用 `dashscope`、`modelgate-chat` provider 或 `voice.input.modelService` / `voice.output.modelService` 时，需要 SDK ≥ 1.14.0。
+
 如果调用方是 Java、Python 或 Shell（curl），请优先看
 <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#multi-language>（Python / Java）
 或 <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#rest-flow>（curl）。
@@ -276,7 +278,7 @@ try {
 
 ## 实时语音（浏览器）
 
-**开发中，暂不支持线上用户接入。**
+通话前，项目要先在门户配好实时语音模型服务和站点来源，见下文「开通前提」。
 
 从 `@kanyun-ai-infra/agenthub/realtime` 导入 `createRealtimeVoiceClient`。浏览器只持有短期通话票；接入方后端调用 `client.sessions.createVoiceTicket(sessionId, options?)` 换票，`options` 可传 `signal: AbortSignal`，返回 `{ ticket, gatewayUrl, expiresAt }`。`getTicket()` 推荐返回整个响应对象，SDK 按票里的 `gatewayUrl` 建连；也可以只返回 `ticket` 字符串，此时连初始化时传入的 `gatewayUrl`。不能把平台 token 放进前端。主入口不加载浏览器代码。转写 `role` 为 `user` 或 `assistant`。
 
@@ -329,3 +331,50 @@ SDK 1.13.0 起提供此行为。旧版 1.11.0 / 1.12.0 / 1.12.1 忽略 `call_end
 `adaptiveConnect` 缺省为 `true`；设为 `false` 时只连初始化地址，首次建连被拒立即报 `CONNECTION_FAILED`，与 1.11.0 一致。
 
 仓库内运行本地浏览器冒烟：`pnpm --filter @kanyun-ai-infra/agenthub run smoke:realtime`。该入口先按依赖顺序构建 SDK 及 contracts，再用本地假网关和无头 Chrome 验证采集、播放、打断、回执与停止；运行前需安装仓库依赖及 Chrome，不需要通话凭据。
+
+### 开通前提
+
+项目要先在门户配好下面两项。SDK 和 API 都没有这两项的入口。
+
+1. **实时语音模型服务。** 项目里要有且只有一个启用中的 GCP 服务账号模型服务（鉴权方式 `gcp_service_account`）。在门户「凭证与集成」→「模型服务」→「新建模型服务」里把用途选为「GCP 实时语音」，粘贴服务账号 JSON，填区域（默认 `us-central1`）。Vertex AI 的费用记在服务账号 JSON 里 `project_id` 所指的 GCP 项目上。`agent.yaml` 不引用这一项：每通通话首次接通时，平台在项目里找到这一行并冻结到这通通话上。live Agent 声明的 `modelService` 是文本模型服务，照常必填，两者互不替代。
+   - 项目里已有一个启用中的 GCP 模型服务时，再建第二个会被拒。更换服务账号或私钥时编辑原来那一行，粘贴完整的新 JSON。
+   - 归档这一行后，项目不能再开新通话；已经接通的通话不受影响，断线接手照常。
+   - 取票时的预检只验证 Google 能为这个服务账号换发访问令牌，不验证它在该 GCP 项目里有没有调用 Vertex AI 的权限。缺权限时取票照常成功，到网关连 Vertex AI 时才失败；网关连上游失败发生在 `ready` 之前时，SDK 报 `GATEWAY_ERROR`。
+2. **站点来源。** 浏览器从接入方自己的站点发起通话时，在门户「配置」→「项目」页的「允许发起实时通话的站点来源」里加上这个站点的来源，即发起连接的页面的 `location.origin`：协议、主机名和可选端口，例如 `https://app.example.com`，不带路径和通配符。比较前只统一大小写、去掉默认端口和末尾斜杠，`https://www.example.com` 与 `https://example.com` 是两个来源。HTTP 只允许 `localhost`、`127.0.0.1` 和 `[::1]`，最多 20 个，只有项目 owner 或管理员能修改。从 AgentHub 门户（`https://agenthub.zhenguanyu.com`、`https://agenthub-test.zhenguanyu.com`）发起的通话不受这份名单限制。
+
+### 拒绝码与处理
+
+通话可能在两处被拒：接入方后端取票时，和浏览器握手时。
+
+**取票被拒。** 发票接口的错误体是 `{ 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`。
+
+```ts
+import { PilotPlatformApiError } from "@kanyun-ai-infra/agenthub";
+
+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 可以直接展示给用户
+  }
+  throw err;
+}
+```
+
+浏览器里 `getTicket()` 抛错时，SDK 只报 `CONNECTION_FAILED`，不转交错误内容。要让用户看到原因，由接入方的取票接口把 `code` 和 `message` 返回给前端，在 `getTicket()` 里自行展示。
+
+| 码 | HTTP | 带 `message` | 含义 | 处理 |
+| --- | --- | --- | --- | --- |
+| `REALTIME_UPSTREAM_NOT_CONFIGURED` | 409 | 是 | 项目没有启用中的 GCP 实时语音模型服务 | 按「开通前提」第 1 项添加 |
+| `REALTIME_UPSTREAM_AMBIGUOUS` | 409 | 是 | 项目里有多个启用中的 GCP 实时语音模型服务 | 归档多余的，只留一个 |
+| `REALTIME_UPSTREAM_CREDENTIAL_INVALID` | 409 | 是 | Google 拒绝为这个服务账号换发访问令牌，或私钥无法使用，例如服务账号被删除或停用、密钥被撤销、JSON 填错 | 在模型服务里重新粘贴服务账号 JSON；重试不会恢复 |
+| `REALTIME_UPSTREAM_CREDENTIAL_UNAVAILABLE` | 503 | 是 | 暂时换不到访问令牌：Google 令牌端点不可达，或返回 5xx、429 | 稍后重试；响应不带 `Retry-After` |
+| `REALTIME_CAPACITY_EXCEEDED` | 409 | 是 | `scope` 为 `"project"`：项目的在线通话数到上限，上限值写在 `message` 里；`scope` 为 `"global"`：平台的在线通话总数到上限 | 项目上限：结束本项目的其他通话后重试；平台上限：稍后重试 |
+| `REALTIME_ADMISSION_UNAVAILABLE` | 503 | 否 | 平台的通话计数服务暂时不可用 | 稍后重试；响应不带 `Retry-After` |
+| `REALTIME_UPSTREAM_TENANT_UNSUPPORTED` | 409 | 是 | 会话所在租户使用独立数据库，这种部署形态还不支持项目自带的实时语音凭据 | 项目侧无法处理，联系平台 |
+| `REALTIME_DISABLED` | 409 | 否 | 平台紧急停用了实时语音 | 项目侧无法处理，等平台恢复 |
+
+会话不是 ready（`SESSION_NOT_READY`）、Revision 未声明 `voice.realtime`（`REALTIME_NOT_DECLARED`）、会话绑定了渠道（`REALTIME_CHANNEL_SESSION`）也是 409，不带 `message`。会话不存在或不属于调用方项目回 404 `SESSION_NOT_FOUND`；平台没配好网关地址回 503 `REALTIME_NOT_CONFIGURED`，票存储不可用回 503 `REALTIME_TICKET_STORE_UNAVAILABLE`，两者都不带 `message`，项目侧无法处理。会话上已有在线通话时，这张票只用于接手那通通话，不做上表里模型服务、凭据、平台上限和租户这几项预检，也不受项目上限限制。
+
+**握手被拒（站点来源）。** 站点来源不在取票时检查。请求没有 `Origin` 头（或超过 2048 个字符）时，网关在兑票前就回 401，票没有用掉。带了 `Origin` 的握手，网关兑票之后交平台判来源：既不是平台门户、也不在项目名单里时回 403 `REALTIME_ORIGIN_FORBIDDEN`，这时票已经用掉。另一个来源码 `REALTIME_ORIGIN_REQUIRED`（claim 没带来源）经平台网关碰不到：网关在没有 `Origin` 时已先回 401。浏览器读不到握手的 HTTP 状态码，SDK 按首次建连被拒处理：报 `CONNECT_RETRYING`，每次重新取票再连，3 次后报 `CONNECTION_FAILED`（`adaptiveConnect: false` 时直接报）。取票一直成功、`start()` 却以 `CONNECTION_FAILED` 结束时，先核对项目的站点来源；网关满额、排空等其他握手拒绝也是同样的表现。断线接手时同样检查来源，通话中途从名单里删掉的来源，接手会失败。不用 SDK、自己建 WebSocket 的接入方，被拒后要重新取票再连，同一张票不能再用。

package/dist/index.cjs

@@ -257,6 +257,8 @@ var import_zod86 = require("zod");
 var import_zod87 = require("zod");
 var import_zod88 = require("zod");
 var import_zod89 = require("zod");
+var import_zod90 = require("zod");
+var import_zod91 = require("zod");
 var MODELGATE_VENDOR_TYPES = [
   "anthropic",
   "openai",
@@ -500,8 +502,10 @@ var EXECUTOR_FORMAT_REGISTRY = {
   },
   pi: {
     descriptor: { kind: "harness", adapterId: "pi", protocolVersion: "1" },
-    // `@ai-sdk/harness-pi`, pinned exactly (#3667 §7, 2026-09-22).
-    adapterVersion: "1.0.120",
+    // `@ai-sdk/harness-pi`, pinned exactly (#3670 owner decision 2026-10-15,
+    // issuecomment-6186259511; supersedes the 2026-09-22 #3667 §7 pin of
+    // 1.0.120 — 1.0.154 dropped the pi-mcp-adapter/pi-ai direct deps).
+    adapterVersion: "1.0.154",
     sectionKey: "pi",
     workerContractKind: "managed_agent",
     // Provisional until #3670 S0: only `structuredOutput: false` is decided
@@ -522,6 +526,13 @@ var ReservedExecutorValueSchema = import_zod5.z.never();
 var RevisionExecutorSchema = ExecutorDescriptorSchema.extend({
   format: ExecutorFormatSchema
 }).strict();
+var RevisionExecutorInputSchema = import_zod5.z.object({
+  format: ExecutorFormatSchema,
+  kind: ExecutorKindSchema.optional(),
+  adapterId: import_zod5.z.string().min(1).max(EXECUTOR_ADAPTER_ID_MAX_LENGTH).optional(),
+  protocolVersion: import_zod5.z.string().min(1).max(EXECUTOR_PROTOCOL_VERSION_MAX_LENGTH).optional()
+}).strict();
+var ProfileExecutorSchema = ExecutorFormatSchema;
 var ImageExecutorCapabilitySchema = import_zod5.z.object({
   format: import_zod5.z.string().min(1).max(EXECUTOR_FORMAT_NAME_MAX_LENGTH),
   protocolVersions: import_zod5.z.array(import_zod5.z.string().min(1).max(EXECUTOR_PROTOCOL_VERSION_MAX_LENGTH)).max(32)
@@ -4134,6 +4145,15 @@ var WorkloadManifestErrorCodeSchema = import_zod4.z.enum([
   "EXECUTOR_NOT_PUBLISHABLE",
   "EXECUTOR_AGENT_OPTIONS_UNSUPPORTED",
   "EXECUTOR_CAPABILITY_UNSUPPORTED",
+  // EXI-L (spec `pilot-v2-executor-identity.md` §2 EXI-L / §4.4): a snapshot
+  // with `agentPackage.format = live` carrying an `executor` key. `live` is an
+  // agent-package form, not an executor — the two keys must not coexist, and
+  // neither may be silently dropped. Thrown by `applyRevisionManifest`'s EXI-3
+  // normalisation (#3668 D7) before `findLiveRevisionViolations` would report
+  // the same field under LIVE_REVISION_UNSUPPORTED. Same HTTP mapping (400,
+  // the `statusForManifestError` default) and additive-widening note as the
+  // four codes above.
+  "EXECUTOR_NOT_APPLICABLE_TO_LIVE",
   // `format: live` publish admission (#4625 PR-1, spec
   // pilot-v2-managed-agent-profile.md §11 MAP-VL3), both thrown by
   // `applyRevisionManifest` and mapped to 400 by the default branch of
@@ -4277,9 +4297,11 @@ var LiveRevisionAgentPackageSchema = AgentPackageSchema.extend({
   format: import_zod4.z.literal("live"),
   source: AgentPackageSourceSchema.optional()
 }).strict();
+var PiRevisionAgentPackageSchema = AgentPackageSchema.omit({ entryCommand: true }).extend({ format: import_zod4.z.literal("pi") }).strict();
 var RevisionAgentPackageSchema = import_zod4.z.discriminatedUnion("format", [
   AgentPackageSchema,
-  LiveRevisionAgentPackageSchema
+  LiveRevisionAgentPackageSchema,
+  PiRevisionAgentPackageSchema
 ]);
 var AGENT_OPTIONS_MAX_TURNS = 200;
 var AGENT_OPTIONS_MAX_THINKING_TOKENS = 6e4;
@@ -4509,12 +4531,14 @@ var WorkloadManifestRealtimeVoiceSchema = import_zod4.z.object({
 var WorkloadManifestVoiceSchema = import_zod4.z.object({
   realtime: WorkloadManifestRealtimeVoiceSchema.optional(),
   input: import_zod4.z.object({
-    provider: import_zod4.z.literal("modelgate"),
+    provider: import_zod4.z.enum(["modelgate", "dashscope", "modelgate-chat"]),
+    modelService: platformEntityNameSchema("modelService", 200).optional(),
     model: import_zod4.z.string().min(1).max(200),
     language: import_zod4.z.string().min(2).max(16).optional()
   }).strict().optional(),
   output: import_zod4.z.object({
-    provider: import_zod4.z.literal("modelgate"),
+    provider: import_zod4.z.enum(["modelgate", "dashscope", "modelgate-chat"]),
+    modelService: platformEntityNameSchema("modelService", 200).optional(),
     model: import_zod4.z.string().min(1).max(200),
     voice: import_zod4.z.string().min(1).max(64),
     format: import_zod4.z.literal("mp3")
@@ -4582,30 +4606,40 @@ var ManagedAgentProfileSnapshotSchema = import_zod4.z.object({
    */
   channels: WorkloadManifestChannelsSchema.optional(),
   /**
-   * Session executor (#3668 D, spec `pilot-v2-executor-identity.md` EXI-2):
-   * the registry descriptor plus the `format` name
-   * (`RevisionExecutorSchema`). Written ONLY for a non-default executor — a
-   * `claude_code` Revision's snapshot MUST NOT carry this key; absence means
-   * `claude_code`. Session executor = this key, never the workload defaults
-   * (EXI-5).
-   *
-   * Reserved: accepts NO value until the publish-time gate (EXP) lands, see
-   * `executor-identity.ts`. The `.strict()` rolling-window caveat in the
-   * `managedMcpBindings` comment above applies unchanged: every reader must
-   * parse a value before any Revision is written with it.
-   */
-  executor: ReservedExecutorValueSchema.optional(),
+   * Session executor (#3668 D, spec `pilot-v2-executor-identity.md` EXI-2 /
+   * EXI-3): the registry descriptor plus the `format` name — written ONLY
+   * for a non-default executor, so a `claude_code` Revision's snapshot
+   * carries no `executor` key and absence means `claude_code`. Session
+   * executor = this key, never the workload defaults (EXI-5).
+   *
+   * Opened to the target shape by #3668 D7 together with the publish gate
+   * (EXP). THIS schema parses the EXI-3 INPUT shape (`format` required,
+   * descriptor fields optional — the file-agent converter sends `format`
+   * only); `applyRevisionManifest` normalises to the stored shape
+   * (registry descriptor, `EXECUTOR_DESCRIPTOR_MISMATCH` on a contradicting
+   * `adapterId` / `kind`, key dropped for the default format) before any
+   * write. The `.strict()` rolling-window caveat in the `managedMcpBindings`
+   * comment above applies unchanged — which is why the gate keeps the
+   * switch default OFF: with it off, no snapshot carrying this key can be
+   * written at all (pi is refused by EXP-1).
+   */
+  executor: RevisionExecutorInputSchema.optional(),
   /**
    * 语音声明（spec pilot-v2-managed-agent-profile.md §11 MAP-VL1）冻结快照。
    *
    * **读者先行**：本 schema 是 `.strict()`，滚动窗口里的旧副本（control-worker /
    * agent-hub 各自打包一份 `@pilot/contracts`）遇到不认识的 `voice` 键会**整份
-   * safeParse 失败**，随后静默回落 workload 默认 model / systemPrompt。所以写侧由
-   * `voice_declarations_enabled` 放开：读快照的全部服务先发布能解析 `voice` 的版本，
-   * 写侧再翻开，保证没有一份含 `voice` 的快照落库时还有旧读者在线（同
-   * `managedMcpBindings` / `executor` 的历史包袱，见下方两条注释）。
+   * safeParse 失败**，随后静默回落 workload 默认 model / systemPrompt。所以当初先让
+   * 读快照的全部服务发布能解析 `voice` 的版本，再由写侧闸
+   * `voice_declarations_enabled` 放开（同 `managedMcpBindings` / `executor` 的历史
+   * 包袱，见下方两条注释）。读者早已全量，那道闸已于 #5069 删除。
    */
   voice: WorkloadManifestVoiceSchema.optional(),
+  /** Project-scoped model service ids resolved when publishing voice declarations. */
+  voiceModelServiceRefs: import_zod4.z.object({
+    input: LlmProviderConfigPublicIdSchema.optional(),
+    output: LlmProviderConfigPublicIdSchema.optional()
+  }).strict().optional(),
   /**
    * promote 门禁档位的冻结值（#4870 G1；字段本体 `PROMOTE_GATE_MODES` 见本文件
    * 上方，agent.yaml 的声明面在 `agenthub-file-agent.ts` 两个 arm）。
@@ -4803,16 +4837,20 @@ var WorkloadManifestDefaultsSchema = import_zod4.z.object({
   memory: WorkloadManifestMemorySchema.optional(),
   /**
    * Workload-level executor selection (#3668 D, spec
-   * `pilot-v2-executor-identity.md` EXI-4): a format name
+   * `pilot-v2-executor-identity.md` EXI-4, opened by D7): a format name
    * (`ProfileExecutorSchema`), omitted for the default (`claude_code`).
    * Frozen into the Revision snapshot's `executor` at publish time; a session
-   * never falls back to this value (EXI-5). To be rejected in repo-bound
-   * projects like `memory` (#1876).
+   * never falls back to this value (EXI-5). Rejected in repo-bound projects
+   * like `memory` (#1876), so a `format: claude_code` file agent cannot be
+   * silently re-executed as pi by console-side defaults.
    *
-   * Reserved: accepts NO value until the publish-time gate (EXP) lands, see
-   * `executor-identity.ts`.
+   * Publishing a Revision whose (merged, normalised) executor format is
+   * outside the publishable set is refused by EXP-1
+   * (`EXECUTOR_NOT_PUBLISHABLE`, `applyRevisionManifest`); storing this key
+   * itself is NOT gated — a dormant `executor: pi` defaults entry only
+   * takes effect when some publish freezes it, and that publish is gated.
    */
-  executor: ReservedExecutorValueSchema.optional()
+  executor: ProfileExecutorSchema.optional()
 }).strict().superRefine(assertMcpBindingFieldsExclusive);
 var WORKLOAD_MANIFEST_UI_DISPLAY_NAME_MAX_LENGTH = 255;
 var WORKLOAD_MANIFEST_UI_PROMPT_PLACEHOLDER_MAX_LENGTH = 500;
@@ -9041,16 +9079,19 @@ var ManagedAgentProfileV1RuntimeSchema = import_zod60.z.object({
   setupScript: WorkloadManifestSetupScriptSchema.optional(),
   resources: SessionResourcesSchema.optional(),
   agentPackage: AgentPackageSchema.optional(),
-  // Executor selection (#3668 D, spec `pilot-v2-executor-identity.md` EXI-4):
-  // a format name (`ProfileExecutorSchema`), omitted for the default; to be
-  // projected into `WorkloadManifestDefaults.executor` only when non-default.
-  // Here in the strict `runtime` group rather than the passthrough `spec` top
-  // level: a server that does not know the key rejects the profile instead
-  // of dropping the selection (why: `.agents/notes/proposed/architecture/
+  // Executor selection (#3668 D, spec `pilot-v2-executor-identity.md` EXI-4,
+  // opened by D7): a format name (`ProfileExecutorSchema`), omitted for the
+  // default; projected into `WorkloadManifestDefaults.executor` only when
+  // non-default. Here in the strict `runtime` group rather than the
+  // passthrough `spec` top level: a server that does not know the key
+  // rejects the profile instead of dropping the selection (why:
+  // `.agents/notes/proposed/architecture/
   // 2026-09-28-executor-keys-reserved-until-gates.md`).
-  // Reserved: accepts NO value until the publish-time gate (EXP) lands, see
-  // `executor-identity.ts`; nothing projects it yet.
-  executor: ReservedExecutorValueSchema.optional()
+  // The profile→defaults projection and the form selector are #3843; the
+  // publish-side gate (EXP) judging the frozen executor is already live in
+  // `applyRevisionManifest`, so a pi selection cannot reach a Revision while
+  // its publishable switch is off.
+  executor: ProfileExecutorSchema.optional()
 }).strict().superRefine((runtime, ctx) => {
   if (!runtime.templateRef && !runtime.environmentRef) {
     ctx.addIssue({
@@ -9632,14 +9673,32 @@ var VOICE_ERROR_CODES = {
   REALTIME_UPSTREAM_CREDENTIAL_UNAVAILABLE: 503,
   /** A project-credential call reached a gateway that did not declare `project-credential`. */
   REALTIME_GATEWAY_INCAPABLE: 409,
-  /** Project credentials are enabled but the project has no active GCP service-account model service. */
+  /** The project has no active GCP service-account model service. */
   REALTIME_UPSTREAM_NOT_CONFIGURED: 409,
+  /** More than one active GCP service-account model service; the project must archive the extras. */
+  REALTIME_UPSTREAM_AMBIGUOUS: 409,
+  /** Ticket preflight: Google refused the project's service account or its key cannot sign. */
+  REALTIME_UPSTREAM_CREDENTIAL_INVALID: 409,
+  /** The session's tenant database is not the catalog database holding the model service rows. */
+  REALTIME_UPSTREAM_TENANT_UNSUPPORTED: 409,
+  /** An unfinished call frozen before #4883 M6 (no model service): never served or re-resolved. */
+  REALTIME_LEGACY_CALL_UNSUPPORTED: 409,
+  /** The claim carried no browser origin. */
+  REALTIME_ORIGIN_REQUIRED: 403,
+  /** The origin is neither a platform portal origin nor configured by the project. */
+  REALTIME_ORIGIN_FORBIDDEN: 403,
+  /** Project or platform concurrent-call limit reached; the envelope's `scope` says which. */
+  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: 400,
   /** 语音附件时长 >60 秒或大小 >2MB（VA-3，上限只在语音路径）。 */
   VOICE_INPUT_TOO_LONG: 400,
   /** 语音附件字节无法解析出时长（格式损坏 / 不识别）。与「超时长」分开，前端据此提示「录音格式无法识别」。 */
   VOICE_AUDIO_UNREADABLE: 400,
+  /** 所选语音服务不支持此输入音频格式。 */
+  VOICE_INPUT_FORMAT_UNSUPPORTED: 400,
   /** 转写调用上游（ModelGate）失败。 */
   VOICE_TRANSCRIPTION_FAILED: 502,
   /** 转写成功但产出的文本为空，无处派发。 */
@@ -11121,9 +11180,29 @@ var FileAgentLiveDefinitionSchema = import_zod77.z.object({
   /** promote 门禁档位 —— 与 claude_code 臂同义同形（#4870 G1），理由见那一处注释。 */
   promoteGate: PromoteGateModeSchema.optional()
 }).strict();
+var FileAgentPiDefinitionSchema = import_zod77.z.object({
+  apiVersion: import_zod77.z.literal(FILE_AGENT_API_VERSION),
+  format: import_zod77.z.literal("pi"),
+  model: WorkloadManifestModelSchema.optional(),
+  /**
+   * 自定义模型服务（D21 同款语义：平台注册名，join 解析成 `llmp_*` 冻进
+   * `snapshot.llmProviderRef`）。它是执行器正交的**模型配置**字段——pi 是沙箱
+   * agent，会话同样要求冻结一个模型服务（#3077 无回落通道），臂上没有它的
+   * pi 文件 agent 除非 workload defaults 恰好有默认，否则结构性建不了会话。
+   * CI 红过一次后补上（agenthub-cli `check --refs` 按三臂共面读该键）。
+   */
+  modelService: FileAgentModelServiceNameSchema.optional(),
+  memory: FileAgentMemorySchema.optional(),
+  channels: WorkloadManifestChannelsSchema.optional(),
+  pi: import_zod77.z.object({}).strict().optional(),
+  voice: WorkloadManifestVoiceSchema.optional(),
+  /** promote 门禁档位 —— 与其它臂同义同形（#4870 G1，门禁与执行器正交）。 */
+  promoteGate: PromoteGateModeSchema.optional()
+}).strict();
 var FileAgentDefinitionSchema = import_zod77.z.discriminatedUnion("format", [
   FileAgentClaudeCodeDefinitionSchema,
-  FileAgentLiveDefinitionSchema
+  FileAgentLiveDefinitionSchema,
+  FileAgentPiDefinitionSchema
 ]).superRefine((definition, ctx) => {
   for (const violation of findRealtimeVoiceViolations(definition)) {
     ctx.addIssue(__spreadValues({ code: import_zod77.z.ZodIssueCode.custom }, violation));
@@ -13083,7 +13162,7 @@ var EvalOnlineScoreRowSchema = import_zod83.z.object({
   turnId: import_zod83.z.string().uuid().nullable(),
   /**
    * 会话级被评单元的生命周期 transition（进入回收流程那一次）——会话级幂等键
-   * `(session_id, lifecycle_transition_id, config_version, grader_key)` 的成分：
+   * `(session_id, lifecycle_transition_id, grader_key)` 的成分（v2.22 起不含 config_version）：
    * 复活再回收产生新 transition，可再判一次而不被唯一索引挡掉（note §4.1 v2.13）。
    * 轮级行为 NULL。
    */
@@ -13092,7 +13171,6 @@ var EvalOnlineScoreRowSchema = import_zod83.z.object({
   agentRevisionId: import_zod83.z.string().uuid(),
   graderRevisionId: import_zod83.z.string().uuid(),
   graderSetDigest: import_zod83.z.string().min(1),
-  configVersion: import_zod83.z.number().int(),
   /** `<providerConfigId>:<judgeModel>` 复合（#4862 形态；worker 领任务时解析冻结）。非 llm 行为 NULL。 */
   judgeIdentity: import_zod83.z.string().nullable(),
   graderKey: import_zod83.z.string(),
@@ -13611,7 +13689,10 @@ var RealtimeCallClaimsSchema = import_zod87.z.object({
 var RealtimeClaimRequestSchema = import_zod87.z.object({
   ticket: VoiceTicketSchema,
   callId: import_zod87.z.string().uuid().optional(),
-  /** Browser Origin seen at WebSocket upgrade; sent only after the control plane declares `claim-origin`. */
+  /**
+   * Browser Origin seen at WebSocket upgrade. K4 gateways always send it: a control plane that
+   * enforces origin refuses claims without it, and #4883 §8 keeps them paired with M4a+ planes.
+   */
   origin: import_zod87.z.string().max(2048).optional()
 }).strict();
 var RealtimeCallRequestSchema = import_zod87.z.object({
@@ -13887,6 +13968,30 @@ var REALTIME_RECOVERY_REASONS = Object.freeze([
   "response_incomplete",
   "connection_interrupted"
 ]);
+var PILOT_PERMISSION_MODES = ["manual", "auto", "accept_edits", "bypass"];
+var PilotPermissionModeSchema = import_zod90.z.enum(PILOT_PERMISSION_MODES);
+var PilotPlanSegmentJobSchema = import_zod91.z.object({ tenantId: import_zod91.z.string().min(1), planId: import_zod91.z.string().uuid() }).strict();
+var PILOT_APPROVAL_TTL_MS = 10 * 60 * 1e3;
+var responseTarget = {
+  messageId: import_zod91.z.string().min(1).max(128),
+  toolCallId: import_zod91.z.string().min(1).max(128)
+};
+var PilotPlanResponseSchema = import_zod91.z.discriminatedUnion("kind", [
+  import_zod91.z.object(__spreadProps(__spreadValues({}, responseTarget), {
+    kind: import_zod91.z.literal("approval"),
+    approved: import_zod91.z.boolean(),
+    reason: import_zod91.z.string().optional()
+  })).strict(),
+  import_zod91.z.object(__spreadProps(__spreadValues({}, responseTarget), {
+    kind: import_zod91.z.literal("user_answer"),
+    output: import_zod91.z.union([
+      import_zod91.z.object({ skipped: import_zod91.z.literal(true) }).strict(),
+      import_zod91.z.object({
+        answers: import_zod91.z.array(import_zod91.z.object({ text: import_zod91.z.string(), value: import_zod91.z.string() }).strict()).min(1).max(3)
+      }).strict()
+    ])
+  })).strict()
+]);
 
 // src/errors.ts
 var PilotPlatformApiError = class extends Error {
@@ -14016,7 +14121,7 @@ var BindingsResource = class {
 };
 
 // src/resources/environments.ts
-var import_zod90 = require("zod");
+var import_zod92 = require("zod");
 
 // src/agent-vocab.ts
 function resolveExclusiveAlias(canonicalKey, canonicalValue, aliasKey, aliasValue) {
@@ -14040,24 +14145,24 @@ function attachAgentAliases(data) {
 }
 
 // src/resources/environments.ts
-var EnvironmentVersionHistorySchema = import_zod90.z.object({
-  versions: import_zod90.z.array(EnvironmentVersionSchema),
-  repoints: import_zod90.z.array(EnvironmentRepointRecordSchema)
+var EnvironmentVersionHistorySchema = import_zod92.z.object({
+  versions: import_zod92.z.array(EnvironmentVersionSchema),
+  repoints: import_zod92.z.array(EnvironmentRepointRecordSchema)
 }).strict();
-var RepointedSlotResultSchema = import_zod90.z.object({
-  workloadId: import_zod90.z.string().uuid(),
+var RepointedSlotResultSchema = import_zod92.z.object({
+  workloadId: import_zod92.z.string().uuid(),
   stage: StageSchema,
-  fromVersion: import_zod90.z.number().int().positive().nullable()
+  fromVersion: import_zod92.z.number().int().positive().nullable()
 }).strict();
-var RepointEnvironmentResultSchema = import_zod90.z.object({
-  toVersion: import_zod90.z.number().int().positive(),
-  repointedSlotCount: import_zod90.z.number().int().nonnegative(),
-  repointedSlots: import_zod90.z.array(RepointedSlotResultSchema)
+var RepointEnvironmentResultSchema = import_zod92.z.object({
+  toVersion: import_zod92.z.number().int().positive(),
+  repointedSlotCount: import_zod92.z.number().int().nonnegative(),
+  repointedSlots: import_zod92.z.array(RepointedSlotResultSchema)
 }).strict();
-var UpdateEnvironmentResultSchema = import_zod90.z.object({
+var UpdateEnvironmentResultSchema = import_zod92.z.object({
   environment: EnvironmentSchema,
-  createdVersion: import_zod90.z.number().int().positive().nullable(),
-  repointedSlotCount: import_zod90.z.number().int().nonnegative()
+  createdVersion: import_zod92.z.number().int().positive().nullable(),
+  repointedSlotCount: import_zod92.z.number().int().nonnegative()
 }).strict();
 function attachAgentAliasesToEach(items) {
   return items.map((item) => attachAgentAliases(item));
@@ -14455,14 +14560,14 @@ var McpDevTicketsResource = class {
 };
 
 // src/resources/memories.ts
-var import_zod91 = require("zod");
+var import_zod93 = require("zod");
 var ListedMemorySchema = AgentMemorySchema.extend({
-  createdAt: import_zod91.z.string(),
-  updatedAt: import_zod91.z.string()
+  createdAt: import_zod93.z.string(),
+  updatedAt: import_zod93.z.string()
 });
-var ListMemoriesResponseSchema = import_zod91.z.object({
-  items: import_zod91.z.array(ListedMemorySchema),
-  nextCursor: import_zod91.z.string().nullish()
+var ListMemoriesResponseSchema = import_zod93.z.object({
+  items: import_zod93.z.array(ListedMemorySchema),
+  nextCursor: import_zod93.z.string().nullish()
 });
 function parseEnvelopeData2(envelope, routeLabel, schema) {
   if (envelope?.data === void 0) {
@@ -14956,7 +15061,7 @@ var ProjectsResource = class {
 };
 
 // src/resources/sessions.ts
-var import_zod92 = require("zod");
+var import_zod94 = require("zod");
 function normalizeSessionRequest(request) {
   const { agentId, versionId, ...rest } = request;
   const workloadId = resolveExclusiveAlias("workloadId", rest.workloadId, "agentId", agentId);
@@ -14981,48 +15086,48 @@ function normalizeSessionRequest(request) {
     ...revisionId !== void 0 ? { revisionId } : {}
   };
 }
-var ListSessionEventsEnvelopeSchema = import_zod92.z.object({
-  data: import_zod92.z.object({
-    events: import_zod92.z.array(SessionEventSchema),
+var ListSessionEventsEnvelopeSchema = import_zod94.z.object({
+  data: import_zod94.z.object({
+    events: import_zod94.z.array(SessionEventSchema),
     // Optional so a pre-P1 server's `{ events }` body still parses.
-    hasMore: import_zod92.z.boolean().optional(),
-    cursorReset: import_zod92.z.boolean().optional()
+    hasMore: import_zod94.z.boolean().optional(),
+    cursorReset: import_zod94.z.boolean().optional()
   })
 });
-var TurnListEnvelopeSchema = import_zod92.z.object({ data: TurnListResponseDataSchema });
-var TurnEnvelopeSchema = import_zod92.z.object({ data: TurnSchema });
-var TurnRecordingEnvelopeSchema = import_zod92.z.object({ data: TurnRecordingResponseSchema });
-var TurnAudioEnvelopeSchema = import_zod92.z.object({ data: TurnAudioResponseSchema });
-var DispatchOutcomeEnvelopeSchema = import_zod92.z.object({
-  data: import_zod92.z.object({ outcome: DispatchOutcomeSchema })
+var TurnListEnvelopeSchema = import_zod94.z.object({ data: TurnListResponseDataSchema });
+var TurnEnvelopeSchema = import_zod94.z.object({ data: TurnSchema });
+var TurnRecordingEnvelopeSchema = import_zod94.z.object({ data: TurnRecordingResponseSchema });
+var TurnAudioEnvelopeSchema = import_zod94.z.object({ data: TurnAudioResponseSchema });
+var DispatchOutcomeEnvelopeSchema = import_zod94.z.object({
+  data: import_zod94.z.object({ outcome: DispatchOutcomeSchema })
 });
-var SendTurnTurnRefEnvelopeSchema = import_zod92.z.object({
-  data: import_zod92.z.object({
-    turn: import_zod92.z.object({ turnId: import_zod92.z.string(), status: TurnStatusSchema }).optional()
+var SendTurnTurnRefEnvelopeSchema = import_zod94.z.object({
+  data: import_zod94.z.object({
+    turn: import_zod94.z.object({ turnId: import_zod94.z.string(), status: TurnStatusSchema }).optional()
   })
 });
-var SessionRuntimeBindingEnvelopeSchema = import_zod92.z.object({
-  runtimeBinding: import_zod92.z.object({ id: import_zod92.z.string().min(1) }).nullish()
-});
-var DeliveryResultEnvelopeSchema = import_zod92.z.object({
-  data: import_zod92.z.object({ delivery: SessionDeliveryEnvelopeSchema.nullable() })
-});
-var SessionArtifactsListEnvelopeSchema = import_zod92.z.object({
-  data: import_zod92.z.object({
-    items: import_zod92.z.array(
-      import_zod92.z.object({
-        id: import_zod92.z.string(),
-        artifactId: import_zod92.z.string().optional(),
-        filename: import_zod92.z.string(),
-        path: import_zod92.z.string(),
-        contentType: import_zod92.z.string(),
-        size: import_zod92.z.number(),
-        turnId: import_zod92.z.string().optional(),
-        messageId: import_zod92.z.string().optional()
+var SessionRuntimeBindingEnvelopeSchema = import_zod94.z.object({
+  runtimeBinding: import_zod94.z.object({ id: import_zod94.z.string().min(1) }).nullish()
+});
+var DeliveryResultEnvelopeSchema = import_zod94.z.object({
+  data: import_zod94.z.object({ delivery: SessionDeliveryEnvelopeSchema.nullable() })
+});
+var SessionArtifactsListEnvelopeSchema = import_zod94.z.object({
+  data: import_zod94.z.object({
+    items: import_zod94.z.array(
+      import_zod94.z.object({
+        id: import_zod94.z.string(),
+        artifactId: import_zod94.z.string().optional(),
+        filename: import_zod94.z.string(),
+        path: import_zod94.z.string(),
+        contentType: import_zod94.z.string(),
+        size: import_zod94.z.number(),
+        turnId: import_zod94.z.string().optional(),
+        messageId: import_zod94.z.string().optional()
       })
     ),
-    partial: import_zod92.z.boolean().optional(),
-    skippedBundles: import_zod92.z.array(import_zod92.z.object({ artifactId: import_zod92.z.string(), reason: import_zod92.z.string() })).optional()
+    partial: import_zod94.z.boolean().optional(),
+    skippedBundles: import_zod94.z.array(import_zod94.z.object({ artifactId: import_zod94.z.string(), reason: import_zod94.z.string() })).optional()
   })
 });
 var SessionTurnsResource = class {
@@ -16034,9 +16139,9 @@ function isTurnAudioNotFound(error) {
   return error instanceof PilotPlatformApiError && error.code === "TURN_AUDIO_NOT_FOUND";
 }
 var TURN_AUDIO_VISIBILITY_GRACE_MS = 3e4;
-var SessionRevivalStateSchema = import_zod92.z.object({
-  pendingRevival: import_zod92.z.object({ attemptId: import_zod92.z.string() }).nullish(),
-  session: import_zod92.z.object({ lifecyclePhase: import_zod92.z.string().nullish() }).loose().optional()
+var SessionRevivalStateSchema = import_zod94.z.object({
+  pendingRevival: import_zod94.z.object({ attemptId: import_zod94.z.string() }).nullish(),
+  session: import_zod94.z.object({ lifecyclePhase: import_zod94.z.string().nullish() }).loose().optional()
 });
 async function isRevivalPending(sessions, sessionId, signal) {
   let snapshot;
@@ -16115,11 +16220,11 @@ function sleep(ms, signal) {
 }
 
 // src/resources/workloads.ts
-var import_zod93 = require("zod");
-var CanaryPromoteResponseSchema = import_zod93.z.object({
+var import_zod95 = require("zod");
+var CanaryPromoteResponseSchema = import_zod95.z.object({
   slot: StageSlotViewSchema,
-  fromRevisionId: import_zod93.z.string().uuid(),
-  toRevisionId: import_zod93.z.string().uuid()
+  fromRevisionId: import_zod95.z.string().uuid(),
+  toRevisionId: import_zod95.z.string().uuid()
 }).strict();
 var WorkloadStageCanaryResource = class {
   constructor(client) {