@kanyun-ai-infra/agenthub 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.17.0
+
+浏览器实时语音入口 `@kanyun-ai-infra/agenthub/realtime`：终止错误带上网关终止码，新增默认关闭的自动重开，以及拉取式的音量电平。主入口的方法没有变化。
+
+### 新增（`@kanyun-ai-infra/agenthub/realtime`）
+
+- `onError` 的 `RealtimeVoiceError` 新增可选 `gatewayCode`：网关终止通话时给出的码，只在 `GATEWAY_ERROR` 出口与 `REOPENING` 通知上出现。取值为 11 个终止码的闭集：`write_queue_full`、`control_timeout`、`control_rejected`、`generation_expired`、`upstream_unavailable`、`resume_store_unavailable`、`renew_rejected`、`execution_expired`、`no_response`、`renew_abandoned`、`realtime_turn_lost`；未知码不带该字段。`code` 仍是 `GATEWAY_ERROR`，按旧码分支的页面不用改。`retryable: true` 且已有通话 ID 的错误仍走自动接手，不落到这里；`no_response` 的可重试提示仍以 `NO_RESPONSE` 上报，不带 `gatewayCode`。
+- 新选项 `reopenOnce`（默认 `false`）：开启后，SDK 对「新通话还有机会」的终止错误自动重开一次——新票、新 WebSocket、新通话 ID，复用麦克风与 `AudioContext`，每次 `start()` 最多一次。重开前发一次 `onError({ code: "REOPENING", retryable: true, gatewayCode })`；重开后的通话再次终态按普通终态处理，不再重开。
+  - 可重开：`no_response`、`renew_abandoned`、`realtime_turn_lost`，以及 `ready` 之前到达的可重试 `upstream_unavailable`、`resume_store_unavailable`、`write_queue_full`、`control_timeout`、`control_rejected`。
+  - 不重开：`generation_expired`、`renew_rejected`、`execution_expired`（通话已被接管或执行许可到期）、`call_ended`、本地 `stop()`、未知码。
+- 新方法 `audioLevels()`：返回 `RealtimeVoiceLevels { input, output }`，两侧都是最近 2048 个采样（48 kHz 下约 42.7 ms，采样率不同时时长随之变化）的线性 RMS，范围 [0, 1]，不做平滑。`input` 是麦克风信号，`output` 是 SDK 播放出的信号，在 `outputNode` 之前取样：不传 `outputNode` 时即用户听到的声音；页面经 `outputNode` 再做增益或处理时，读数不含这部分处理。拉取式接口，页面在自己的 `requestAnimationFrame` 里调用，SDK 不新增定时器或回调。通话外与 `stop()` 之后返回 `undefined`；`ready` 之前与断线接手期间采集暂停，`input` 为 0。
+- 新导出类型 `RealtimeVoiceLevels`。
+- 电平分析节点串联在音频链路上：`source → 输入分析器 → worklet → 输出分析器 → outputNode/destination`。两个分析节点都是直通，送往网关的 PCM 与播放音频不变。
+
+### 随共享契约内联的变化
+
+- 工作台与发布板读模型新增可选的 Revision 序号与版本串：`WorkbenchRecentChange` 的 `revisionVersion` / `revisionSequence`，槽位摘要（含灰度摘要）的 `revisionSequence`，以及 `ReleaseBoardRow.defaultRevision` / `latestRevision` 的 `sequence`。旧服务端的响应缺这些字段，解析行为不变。
+- `Environment` 的 `envVars` 新增拒绝 `PILOT_WORKLOAD_SLUG` 的大小写变体（如 `pilot_workload_slug`），在 SDK 客户端校验时就报错；大写形式此前已被 `PILOT_` 前缀规则拒绝。会话配置值与 secret `envKey` 不受影响。
+
+### 随包文档
+
+- `SKILL.md` 实时段补充音量电平、网关终止码与 `reopenOnce`。
+
+### 迁移说明
+
+- **类型破坏**：`RealtimeVoiceClient` 新增了必选方法 `audioLevels()`。自己实现或 mock 这个接口的代码升级后会报类型错误，要补上该方法；通过 `createRealtimeVoiceClient` 工厂拿到的客户端不受影响。
+- **音频接线变化**：麦克风源不再直接接 worklet，中间多了一个直通的分析节点。页面如果通过拦截 `AudioNode.prototype.connect`、按 `source → worklet` 这条连线识别上行的分接写法，升级后上行（麦克风）拿不到，下行照旧。正路是改用 `audioLevels()`。
+- `reopenOnce` 默认关闭时，终止行为与 1.16.0 一致，只多一个 `gatewayCode` 字段。
+
 ## 1.16.0
 
 Revision 读面改为宽容读者：服务端给 `workloads.get` / `getRevision` / `getVersion` 的响应新增字段时，已发布的客户端不再报错。这一版同时接受可选的 `sequence`，服务端读面带出后即可读取，无需再次升级 SDK。

package/dist/index.cjs

@@ -1557,7 +1557,16 @@ var ModelCallsPullResponseSchema = import_zod16.z.object({
   activeCalls: count(),
   sessionActiveCalls: count(),
   droppedRecords: count(),
-  truncated: import_zod16.z.boolean().optional()
+  truncated: import_zod16.z.boolean().optional(),
+  /**
+   * Metering faults the pod-agent INSTANCE has swallowed so far (not scoped to
+   * the session or query: pre-warm and earlier sessions count too).
+   * `observer` = the store's own guard caught a throw; `hook` = the
+   * forwarder's fail-open wrapper caught one (at most one per call). pod-agent
+   * console logs never reach Octopus, so the host's sweep turns an increase
+   * into a worker-side warn. Absent from an older pod-agent.
+   */
+  meteringFaults: import_zod16.z.object({ observer: count(), hook: count() }).optional()
 });
 var ModelCallsBlockSchema = import_zod16.z.object({
   accounting: label(),
@@ -3027,6 +3036,7 @@ var PROTECTED_WORKER_ENV_KEYS = /* @__PURE__ */ new Set([
   "PILOT_RUNTIME_BINDING_ID",
   "PILOT_STAGE",
   "PILOT_WORKLOAD_ID",
+  "PILOT_WORKLOAD_SLUG",
   "PILOT_WORKSPACE_SNAPSHOT",
   // Managed-agent prewarming — seed toolbox, projected via the typed startWorker
   // request, never via business env.
@@ -3480,7 +3490,18 @@ var PodAgentStartWorkerRequestSchema = import_zod10.z.object({
    * Strict `z.string().uuid()` rejects it (version nibble 0) and rejected every
    * such start request at the pre-flight check in control-worker.
    */
-  projectId: import_zod10.z.union([import_zod10.z.string().uuid(), import_zod10.z.literal(PLATFORM_DEFAULT_PROJECT_ID)]).optional()
+  projectId: import_zod10.z.union([import_zod10.z.string().uuid(), import_zod10.z.literal(PLATFORM_DEFAULT_PROJECT_ID)]).optional(),
+  /**
+   * Observability provenance (obs sandbox inject) — the workload's human-readable
+   * slug (`workloads.slug`, unique within the owner project), forwarded into the
+   * spawned child as `PILOT_WORKLOAD_SLUG` for the `pilot.workload_slug` OTel
+   * resource attribute (Octopus LLM-dashboard agent dimension). control-plane
+   * resolves it from the `workloads` catalog at `startWorker` time, alongside
+   * `projectId`. Optional — omitted → pod-agent omits the env var. Injected ONLY
+   * via this typed field, never via user `env` (guarded by
+   * `PROTECTED_WORKER_ENV_KEYS` → `PILOT_WORKLOAD_SLUG`).
+   */
+  agentSlug: import_zod10.z.string().min(1).max(100).optional()
   // NOTE: `agentWorkerBundleUrl` (v2 hot-deploy) was REMOVED here — #1070 P2
   // retired the OSS bundle path; agent-worker is now baked into the sandbox
   // image and pod-agent always spawns the baked dist. This schema keeps zod's
@@ -9217,8 +9238,7 @@ var ManagedAgentProfileV1RuntimeSchema = import_zod60.z.object({
   // rejects the profile instead of dropping the selection (why:
   // `.agents/notes/proposed/architecture/
   // 2026-09-28-executor-keys-reserved-until-gates.md`).
-  // The profile→defaults projection and the form selector are #3843; the
-  // publish-side gate (EXP) judging the frozen executor is already live in
+  // The publish-side gate (EXP) judging the frozen executor lives in
   // `applyRevisionManifest`, so a pi selection cannot reach a Revision while
   // its publishable switch is off.
   executor: ProfileExecutorSchema.optional()
@@ -10766,6 +10786,11 @@ var SlotCanarySummarySchema = import_zod75.z.object({
   revisionId: import_zod75.z.string(),
   /** canary revision 的人可读版本短名;revision 行缺失时 null(降级显示 id 前缀)。 */
   revisionLabel: import_zod75.z.string().nullable(),
+  /**
+   * canary 版本在该 Agent 内的落库序号（#5057 PR-B）。主显 `#n`、原串进
+   * `title`。optional = 旧服务端响应没有它（滚动发版兼容）。
+   */
+  revisionSequence: import_zod75.z.number().int().nullable().optional(),
   /** 0..99;0 = 冻结观察态(仅名单命中仍入 canary)。 */
   percentage: import_zod75.z.number().int(),
   /** ldap 名单人数(徽章"名单 N 人";0 = 无名单)。 */
@@ -10777,6 +10802,12 @@ var SlotSummarySchema = import_zod75.z.object({
   revisionId: import_zod75.z.string().nullable(),
   /** 人可读的版本标识(revision name/number);无部署时 null。 */
   revisionLabel: import_zod75.z.string().nullable(),
+  /**
+   * 槽位所指 Revision 在该 Agent 内的落库序号（#5057 PR-B）。UI 主显 `#n`、
+   * `revisionLabel` 留在 `title` 与复制按钮。optional = 旧服务端 / 未报告的
+   * 生产方（滚动发版兼容）。
+   */
+  revisionSequence: import_zod75.z.number().int().nullable().optional(),
   environmentId: import_zod75.z.string().nullable(),
   environmentName: import_zod75.z.string().nullable(),
   environmentVersion: import_zod75.z.number().int().nullable(),
@@ -10796,6 +10827,34 @@ var SlotSummarySchema = import_zod75.z.object({
    */
   canary: SlotCanarySummarySchema.nullable().optional()
 });
+var AttentionReasonKindSchema = import_zod75.z.enum([
+  "startup_failed",
+  "required_gate_failed",
+  "repeated_revision_failure",
+  "runtime_failed",
+  "unhealthy_instance",
+  "warm_pool_underfilled"
+]);
+var AttentionReasonBasisSchema = import_zod75.z.enum(["window", "current"]);
+var AttentionReasonSchema = import_zod75.z.object({
+  kind: AttentionReasonKindSchema,
+  count: import_zod75.z.number().int().nonnegative(),
+  basis: AttentionReasonBasisSchema
+});
+var AttentionSeveritySchema = import_zod75.z.enum(["ok", "info", "warn", "critical"]);
+var WorkloadAttentionSchema = import_zod75.z.object({
+  workloadId: import_zod75.z.string(),
+  workloadSlug: import_zod75.z.string(),
+  workloadDisplayName: import_zod75.z.string(),
+  severity: AttentionSeveritySchema,
+  score: import_zod75.z.number(),
+  reasonDetails: import_zod75.z.array(AttentionReasonSchema)
+});
+var ProjectAttentionSummarySchema = import_zod75.z.object({
+  severity: AttentionSeveritySchema,
+  workloadCount: import_zod75.z.number().int().nonnegative(),
+  reasonDetails: import_zod75.z.array(AttentionReasonSchema)
+});
 var WorkbenchStageDriftKindSchema = import_zod75.z.enum([
   /** test 指向新于 production(待晋级)。 */
   "test_ahead",
@@ -10851,8 +10910,15 @@ var WorkbenchRecentChangeSchema = import_zod75.z.object({
    * 降级为无 slug,而不是整个 DTO 校验失败。
    */
   subjectSlug: import_zod75.z.string().nullable().optional(),
-  /** 一句话变更描述(如 "production → rev-12" / "环境 v3 创建")。 */
+  /** 一句话变更描述(如 "production → #12" / "环境 v3 创建")。 */
   detail: import_zod75.z.string(),
+  /**
+   * workload 类变更指到的 Revision 原版本串与序号（#5057 PR-B）。环境类变更、
+   * 以及旧服务端都缺席；`detail` 已按可读序号拼好，这两个字段供 UI 把 `#n`
+   * 主显、把原版本串放进 `title`。optional = 滚动发版兼容（同 subjectSlug）。
+   */
+  revisionVersion: import_zod75.z.string().nullable().optional(),
+  revisionSequence: import_zod75.z.number().int().nullable().optional(),
   occurredAt: import_zod75.z.string()
 });
 var WorkbenchSessionStatsSchema = import_zod75.z.object({
@@ -10946,7 +11012,13 @@ var ReleaseBoardRowSchema = import_zod75.z.object({
    * 新消费方一律读 `latestRevision`(前端回退链 latestRevision ?? defaultRevision
    * 只为兼容旧服务端缺字段,不表示两者同义)。
    */
-  defaultRevision: import_zod75.z.object({ id: import_zod75.z.string(), version: import_zod75.z.string(), createdAt: import_zod75.z.string() }).nullable(),
+  defaultRevision: import_zod75.z.object({
+    id: import_zod75.z.string(),
+    version: import_zod75.z.string(),
+    /** 落库序号（#5057 PR-B）；optional = 旧服务端。 */
+    sequence: import_zod75.z.number().int().nullable().optional(),
+    createdAt: import_zod75.z.string()
+  }).nullable(),
   /**
    * Workload 最近发布的 Revision(createdAt 最新;并列时 id 大者,保证确定性)。
    * 发布板用它判断"有新版本尚未部署到 test"(latestRevision.id ≠
@@ -10962,6 +11034,8 @@ var ReleaseBoardRowSchema = import_zod75.z.object({
   latestRevision: import_zod75.z.object({
     id: import_zod75.z.string(),
     version: import_zod75.z.string(),
+    /** 落库序号（#5057 PR-B）；optional = 旧服务端。 */
+    sequence: import_zod75.z.number().int().nullable().optional(),
     createdAt: import_zod75.z.string(),
     /** 真实发布时间；optional 仅用于新旧服务端滚动窗口兼容。 */
     publishedAt: import_zod75.z.string().optional()
@@ -13429,6 +13503,85 @@ var SessionWorkspaceSnapshotRecordSchema = import_zod83.z.object({
   path: ["capturedAtTurn"],
   message: "capturedAtTurn must equal envelope.capturedAtTurn (the row key is the envelope's own cursor)"
 });
+var OnlineGraderSummaryItemSchema = import_zod83.z.object({
+  key: import_zod83.z.string(),
+  type: import_zod83.z.string(),
+  level: import_zod83.z.enum(["turn", "session"]),
+  threshold: import_zod83.z.number().nullable()
+}).strict();
+var OnlineSetInspectionSchema = import_zod83.z.object({
+  kind: import_zod83.z.enum(["absent", "invalid", "unreadable", "ok"]),
+  graderSummary: import_zod83.z.array(OnlineGraderSummaryItemSchema),
+  digest: import_zod83.z.string().nullable(),
+  error: import_zod83.z.string().nullable()
+}).strict();
+var OnlineConfigViewSchema = import_zod83.z.object({
+  agentId: import_zod83.z.string().uuid(),
+  stage: import_zod83.z.string(),
+  enabled: import_zod83.z.boolean(),
+  tier1Rate: import_zod83.z.number(),
+  alertEnabled: import_zod83.z.boolean(),
+  alertWindowHours: import_zod83.z.number().int(),
+  alertMinSamples: import_zod83.z.number().int(),
+  dailyCandidateCap: import_zod83.z.number().int(),
+  updatedAt: import_zod83.z.string(),
+  last7dScoreRows: import_zod83.z.number().int(),
+  lastGradedAt: import_zod83.z.string().nullable()
+}).strict();
+var OnlineStatusDotSchema = import_zod83.z.object({
+  lit: import_zod83.z.boolean(),
+  mismatch: import_zod83.z.array(
+    import_zod83.z.object({
+      agentId: import_zod83.z.string().uuid(),
+      stage: import_zod83.z.string(),
+      kind: import_zod83.z.enum(["absent", "invalid"]),
+      error: import_zod83.z.string().nullable()
+    }).strict()
+  ),
+  alerts: import_zod83.z.array(
+    import_zod83.z.object({
+      agentId: import_zod83.z.string().uuid(),
+      stage: import_zod83.z.string(),
+      graderKey: import_zod83.z.string(),
+      metric: import_zod83.z.number(),
+      threshold: import_zod83.z.number(),
+      samples: import_zod83.z.number().int()
+    }).strict()
+  )
+}).strict();
+var EvalOnlineOverviewResponseSchema = import_zod83.z.object({
+  configs: import_zod83.z.array(OnlineConfigViewSchema),
+  statusDot: OnlineStatusDotSchema
+}).strict();
+var EvalOnlineConfigDetailResponseSchema = import_zod83.z.object({
+  config: OnlineConfigViewSchema.nullable(),
+  inspection: OnlineSetInspectionSchema
+}).strict();
+var EvalOnlineConfigUpsertResponseSchema = import_zod83.z.object({
+  ok: import_zod83.z.literal(true),
+  graderSummary: import_zod83.z.array(OnlineGraderSummaryItemSchema).nullable()
+}).strict();
+var EvalOnlineTrendResponseSchema = import_zod83.z.object({
+  rangeDays: import_zod83.z.number().int(),
+  dailyFromDay: import_zod83.z.string(),
+  graders: import_zod83.z.array(
+    import_zod83.z.object({
+      graderKey: import_zod83.z.string(),
+      graderType: import_zod83.z.string(),
+      level: import_zod83.z.enum(["turn", "session"]),
+      points: import_zod83.z.object({
+        day: import_zod83.z.string(),
+        metric: import_zod83.z.number(),
+        judged: import_zod83.z.number().int()
+      }).strict().array(),
+      switches: import_zod83.z.object({
+        day: import_zod83.z.string(),
+        graderRevisionId: import_zod83.z.string().uuid(),
+        graderSetDigest: import_zod83.z.string()
+      }).strict().array()
+    }).strict()
+  )
+}).strict();
 var PIPELINE_COMMIT_SHA_RE = /^[0-9a-f]{7,64}$/i;
 var CommitShaSchema = import_zod84.z.string().regex(PIPELINE_COMMIT_SHA_RE, {
   message: "commitSha must be 7-64 hexadecimal characters"
@@ -14146,6 +14299,19 @@ var REALTIME_RECOVERY_REASONS = Object.freeze([
   "response_incomplete",
   "connection_interrupted"
 ]);
+var REALTIME_TERMINAL_ERROR_CODES = Object.freeze([
+  "write_queue_full",
+  "control_timeout",
+  "control_rejected",
+  "generation_expired",
+  "upstream_unavailable",
+  "resume_store_unavailable",
+  "renew_rejected",
+  "execution_expired",
+  "no_response",
+  "renew_abandoned",
+  "realtime_turn_lost"
+]);
 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();