fix: Wait for managed input before activating sessions

[lanyue-llk]

Summary

修复 managed room input 会话在 Agent 和音频输入尚未就绪时过早进入可交互界面的竞态。

Changes

1. 等待完整输入就绪合同

• managed input dispatch 要求 Agent session-ready 属性与 room input participants 同时就绪。
• 需要视觉输入的场景继续额外等待 video input ready。

2. 在 dispatch 完成后再展示会话界面

• 启动过程保持 Starting...，直到请求的就绪条件全部满足。
• 启动失败仍沿用现有的房间与输入清理路径。

Impact

• Xunfei、Browser 以及其它 managed input 不再暴露“界面已可说话，Agent 尚未收到输入”的启动窗口。
• 不引入固定等待时间；就绪时间由实际 Agent 和媒体状态决定。

Verification

• pnpm test

  ✅ passed: 245 tests

• pnpm build

  ✅ passed: production build completed

• pnpm exec prettier --check ... and targeted ESLint

  ✅ passed

[github-actions]

Claude finished @lanyue-llk's task in 1m 58s —— View job

---

任务清单

• 获取 PR diff 与相关文件
• 阅读仓库约定（无根级 CLAUDE.md）
• 审查 LiveKit room/track 生命周期、React hook 清理等
• 输出 review 结论

---

Review 结论

有条件通过

问题及建议

• [P1] hooks/useRoom.ts:222-224 + lib/session-dispatch-readiness.ts:47-58：requireRoomInputParticipantsReady 直接绑定到 usesManagedRoomInput（即 appConfig.usesServerRoomInput），但 usesServerRoomInput 在 inputSource: 'mixed' 场景下只要音频或视觉任一使用 server room input 就为 true（见 app-config.ts:123-125）。而 hasReadyRoomInputParticipants（lib/session-dispatch-readiness.ts:111-114）无条件要求 room_audio_input 与 room_video_input 两个参与者同时就绪。当 mixed 模式下 audio 使用 xunfei/generic（server room input）而 vision 使用 browser（本地摄像头，非 server room input，requiresRoomVideoInputReady 为 false）时，room_video_input 参与者永远不会加入房间，findReusableAgentParticipant 会一直返回 null，导致 dispatch 卡在 "Starting..." 直至超时失败。建议：requireRoomInputParticipantsReady 的判定应像 requiresRoomVideoInputReady 一样按实际使用的 audio/vision 设备分别判断，或者让 hasReadyRoomInputParticipants 接受"仅要求实际启用的输入侧就绪"的选项。

• [P2] hooks/useRoom.ts:214：setIsSessionActive(true) 被移到 try 块末尾（第 314 行），但在 usesSandboxConcurrentStartup 分支中，dispatchAgentSession() 已经在 Promise.allSettled 内被 await 过；后续未见对该并发路径下"部分就绪"竞态的专门测试（仅测试了非并发路径的顺序断言）。建议为 usesSandboxConcurrentStartup === true 路径补充一个类似的时序断言，避免未来重构改变并发分支时静默倒退。

• [P2] 测试覆盖：tests/session-start-dispatch.test.mjs 通过字符串匹配 (assert.match(useRoomSource, ...)) 校验新增字段传递，未对 mixed 音视频分离场景（P1 提到的组合）做行为级用例（类似 session-dispatch-readiness.test.mjs 里对 hasReadyRoomInputParticipants 的组合测试）。建议补一条覆盖"audio=server room input, vision=browser"组合的用例，能直接暴露上面的 P1 问题。

未发现 secret 泄露、Next.js 客户端/服务端边界或类型问题。

Branch: fix/session-input-readiness

[github-actions]

Claude finished @lanyue-llk's task in 1m 56s —— View job

---

任务清单

• 获取 PR diff 与相关文件
• 阅读仓库约定
• 审查 LiveKit room/track 生命周期、React hook 清理等
• 输出 review 结论

---

Review 结论

有条件通过

新提交 deda8fa（fix: wait for configured session inputs）已修复上一轮 review 指出的 P1 问题：hooks/useRoom.ts:226 现通过 usesBothServerRoomInputParticipants(appConfig.audioInputDevice, appConfig.visionInputDevice) 按实际启用的音频/视觉设备分别判断是否需要等待 room_audio_input/room_video_input 参与者，不再直接绑定到笼统的 usesServerRoomInput；tests/local-dispatch-config.test.mjs:141-146 已补充 mixed（audio=server, vision=browser）组合用例，覆盖此前风险场景。上一轮 P2（并发路径时序断言）也已通过 tests/session-start-dispatch.test.mjs:224-230 的 lastIndexOf 顺序断言补齐。

问题及建议

• [P2] app/api/session/session-dispatch-service.ts:304-305：prewarmRoomSession 中仍无条件设置 requireRoomInputParticipantsReady: true（未按 audioInputDevice/visionInputDevice 拆分），若 mixed 场景（如 audio=xunfei/generic、vision=browser）走预热路径，room_video_input 参与者永远不会入会，可能导致预热在 45s 超时前一直等待。该代码不在本次 diff 改动范围内，但与本 PR 修复的问题同源，建议后续跟进对齐。
• [P2] app/api/session/session-dispatch-service.ts:78：DEFAULT_AGENT_DISPATCH_TIMEOUT_MS 从 8s 提升到 30s，属合理调整（新增等待 agent/room 输入就绪后耗时变长),但未见 PR 描述中说明该改动动机，建议在 PR 描述中补充一句说明，便于后续排查超时相关问题时追溯。

未发现会阻塞合并的问题。残余风险：上述两条均为 P2，可在后续 PR 中处理。

[github-actions]

任务清单

• 获取 PR diff 与相关文件
• 阅读仓库约定
• 审查 LiveKit room/track 生命周期、React hook 清理等
• 输出 review 结论

[github-actions]

Claude finished @lanyue-llk's task in 2m 19s —— View job

---

任务清单

• 获取 PR diff 与相关文件
• 阅读仓库约定
• 审查 LiveKit room/track 生命周期、React hook 清理等
• 输出 review 结论

---

Review 结论

有条件通过

新提交 18db439（fix: keep video readiness out of voice startup）将就绪判定简化为单一 requireAgentSessionReady（hooks/useRoom.ts:210-217、app/api/session/dispatch/route.ts:23-24,60-61），不再依赖 room_audio_input/room_video_input 参与者组合判断。此前 review 指出的 P1（mixed 音视频设备场景下 dispatch 卡死）已通过此重构从根本消除——因为新的就绪门槛完全交由 agent 自身的 liveavatar.agent.session_ready 属性决定，不再依赖前端猜测应等待哪个 room-input identity。setIsSessionActive(true)（hooks/useRoom.ts:305）在并发与非并发两条启动路径下均保持在 dispatch 完成之后，测试 tests/session-start-dispatch.test.mjs:212-216 用 lastIndexOf 顺序断言覆盖了这一点。

问题及建议

• [P2] app/api/session/session-dispatch-service.ts:304-305：prewarmRoomSession 仍无条件设置 requireRoomInputParticipantsReady: true（未按实际启用的 audio/vision 设备拆分）。若 mixed 场景（如 audio=xunfei/generic、vision=browser）走预热路径，room_video_input 参与者永远不会入会，预热可能一直等到 45s 超时。与本 PR 修复的问题同源，建议后续对齐（不阻塞本次合并）。
• [P2] tests/session-prewarm.test.mjs:334：测试名 'regular dispatch keeps its 8s timeout ...' 与本次改动后的断言值 30_000（app/api/session/session-dispatch-service.ts:78）不一致，建议同步更新测试描述文案，避免误导后续读者。
• [P2] DEFAULT_AGENT_DISPATCH_TIMEOUT_MS 由 8s 提升到 30s（app/api/session/session-dispatch-service.ts:78）是合理调整（等待 agent session ready 后耗时变长），但 PR 描述中仍未说明该改动动机，建议补充一句，便于后续排查超时问题时追溯。

未发现会阻塞合并的问题。残余风险：上述三条均为 P2，可在后续处理。

[github-actions]

Claude finished @lanyue-llk's task in 1m 0s —— View job

---

任务清单

• 获取 PR diff 与相关文件
• 阅读仓库约定
• 审查 LiveKit room/track 生命周期、React hook 清理等
• 输出 review 结论

---

Review 结论

有条件通过

新提交 5ac7bad（fix: recognize server serialized readiness attributes）仅改动 lib/session-dispatch-readiness.ts 与其测试，为 isAgentSessionReady（lib/session-dispatch-readiness.ts:130-136）增加了对 camelCase 属性 liveavatarAgentSessionReady 的兼容判断，逻辑本身正确且有配套测试（tests/session-dispatch-readiness.test.mjs:65-81）覆盖。

问题及建议

• [P2] lib/session-dispatch-readiness.ts:18-19：新增第二个就绪属性 key liveavatarAgentSessionReady 缺少注释说明来源（例如某个 LiveKit server SDK 版本会把点号 key 序列化为 camelCase），建议补一行注释，避免后续开发者误以为是冗余/遗留代码而删除。
• [P2] app/api/session/session-dispatch-service.ts:304-305：prewarmRoomSession 仍无条件设置 requireRoomInputParticipantsReady: true，未按实际启用的 audio/vision 设备拆分（同 P1 已在主流程通过 requireAgentSessionReady 重构规避，但预热路径未跟进）。mixed 场景下预热可能一直等到超时，建议后续对齐。
• [P2] tests/session-prewarm.test.mjs:334：测试名 'regular dispatch keeps its 8s timeout ...' 与实际断言值 30_000（app/api/session/session-dispatch-service.ts:78）不一致，建议同步更新描述文案。

未发现会阻塞合并的新增问题。上述均为既有 P2 遗留项，可在后续 PR 处理。

[github-actions]

Claude finished @lanyue-llk's task in 1m 21s —— View job

---

任务清单

• 获取 PR diff 与相关文件
• 阅读仓库约定
• 审查 LiveKit room/track 生命周期、React hook 清理等
• 输出 review 结论

---

Review 结论

有条件通过

新提交 5e4c87c（fix: gate prewarm on authoritative session readiness）已修复上一轮 review 指出的 P2：app/api/session/session-dispatch-service.ts:303-305 的 prewarmRoomSession 现在只设置 requireAgentSessionReady: true，不再无条件附加 requireRoomInputParticipantsReady: true，与主 dispatch 路径（hooks/useRoom.ts:215、app/api/session/dispatch/route.ts:60-61）保持一致，mixed audio/vision 设备组合下预热不会再卡到超时。配套测试 tests/session-prewarm.test.mjs:334,387,1395-1398 已同步更新断言（30s 超时、visionParticipantReady: false）。lib/session-dispatch-readiness.ts:18-20 的 camelCase 属性兼容也补了来源注释，回应了上一轮建议。

问题及建议

• [P2] lib/session-dispatch-readiness.ts:14-15,40-60 + app/api/session/session-dispatch-service.ts:190-191：requireRoomVideoInputReady/requireRoomInputParticipantsReady 及其对应的 hasReadyRoomVideoInput/hasReadyRoomInputParticipants 分支现在已无任何生产调用方（dispatch/route.ts 与 prewarmRoomSession 均已全部切换为 requireAgentSessionReady），仅剩测试在直接调用 findReusableAgentParticipant/waitForRequestedRoomSessionReadiness 时使用。建议后续 PR 清理这部分死代码，避免以后误用旧的、已被证明有竞态风险的就绪判定路径。
• [P2] app/api/session/session-dispatch-service.ts:78：DEFAULT_AGENT_DISPATCH_TIMEOUT_MS 由 8s 提升到 30s 的动机（等待 agent session ready 后单次 dispatch 耗时变长）仍未体现在 PR 描述中，建议补一句说明便于后续排查超时问题。

未发现会阻塞合并的问题。残余风险：上述均为 P2，可在后续 PR 处理。