fix: support LAN browser UUIDs and document Generic control ownership

[why-tomato]

概要

• 说明当前 Generic 控制链路：Browser 通过现有 Agent Dispatch 进入 LexVoice Generic Agent，由 lex-reflex 发布原始轨道，LexVoice Video Processor 发布 room_video，最终回到 Browser。
• 说明 Orin 上的 Firefox 或 Chromium 如何访问监听于 0.0.0.0:4003 的云侧前端，并提供云侧、Orin、真实静态资源及浏览器手动验收步骤。
• 为普通局域网 HTTP 场景补充最小浏览器兼容修复：当 crypto.randomUUID 不可用时，在 Room hooks 运行前安装一个基于 crypto.getRandomValues 的 RFC 4122 v4 UUID 回退实现；Browser Session ID 也复用同一生成逻辑。
• 该兼容入口同时覆盖浏览器会话/Room ID 创建和 LiveKit 文本发送，保留原有高层 send(message) 发送链路。

运行时变更范围

• components/app/session-provider.tsx：在创建 Room 相关 Provider 前初始化 UUID 兼容逻辑；如果浏览器连安全随机数能力也不具备，则显示明确的兼容性错误。
• lib/browser-room-session.ts：新会话 ID 改用浏览器安全的 UUID 生成函数。
• lib/browser-runtime-compat.ts：在不覆盖浏览器原生实现的前提下安装 randomUUID 回退。
• tests/browser-room-session.test.mjs 和 tests/browser-runtime-compat.test.mjs：覆盖原生实现、回退实现、已有 Session ID 复用、安装失败、Provider 执行顺序及聊天发送链路未改变。
• README.md：记录 Generic 所有权边界和 Orin 访问云侧 UI 的部署与验收方法。

所有权边界

• 本 PR 不新增 heartbeat、Endpoint Lease、Jetson pairing、endpoint readiness 编排或 Edge Media 控制 Token。
• Browser 和 Next.js 不发现、选择、保存、接收或暴露 Jetson IP，也不访问 Jetson 的 8013 端口。
• Jetson 地址仍由 LexVoice Generic 原有环境变量 EDGE_MEDIA_URL 管理。
• lex-reflex 的 /start 和 /stop 调用仍由 LexVoice Generic Agent 负责。
• lex-reflex 发布 room_audio 和 room_video_raw；LexVoice Video Processor 发布 room_video。
• 原有 codex/endpoint-connectivity-probe 分支和 PR feat: orchestrate Generic endpoints through heartbeat leases #23 保持不变，作为技术存档。
• 设备注册、端侧发现和 Endpoint Lease 设计继续推迟到云平台接入后统一处理。

验证结果

• 相对 origin/lex-main 共修改 6 个文件：README.md、3 个运行时文件和 2 个测试文件。
• UUID/Session 定向测试：11 项通过。
• npm run format:check：通过。
• npm run lint：通过。
• npm run test：253 项全部通过。
• npm run build：通过。
• 云侧 production 前端：首页 HTTP 200。
• Orin 到云侧的路由及 TCP 4003：通过。
• Orin 请求首页及本次构建的真实 JavaScript 静态资源：均为 HTTP 200。
• Orin 浏览器手动验收：页面加载、Start、文本 Send 和 End 全部通过。
• 已确认本地 HEAD、远程分支和 PR head 均为 841b0fb261f00db80da8317d3701c5be2cd700d9。

项目的 pnpm 启动器在受限环境中无法校验或下载锁定版本，因此使用现有本地依赖，通过 npm run 执行了相同的 package.json 脚本。

[github-actions]

Claude finished @why-tomato's task in 1m 10s —— View job

---

任务清单

• 获取 PR diff (origin/lex-main...HEAD)
• 审查 README.md 改动
• 输出审查结论

Review 结论

有条件通过

问题及建议

• [P2] README.md:117,145-147,155,166,174：文档中硬编码了具体的内网 IP（10.2.77.108、10.2.2.199）作为示例地址。虽为 RFC1918 私网段，非直接可路由风险，但会在公共/共享仓库中暴露内部网络拓扑（云端与 Orin 设备的真实地址）。建议改用占位符如 <CLOUD_HOST> / <ORIN_HOST>，或在文档中注明这些仅为示例、需替换为实际部署地址。
• [P2] README.md:125：pnpm dev --hostname 0.0.0.0 --port 4003 依赖 pnpm 透传未识别参数给底层 next dev --turbopack，建议明确写作 pnpm dev -- --hostname 0.0.0.0 --port 4003，避免歧义并与团队通用写法保持一致。
• [P2] README.md:98-107：本节反复强调"不做"什么（不暴露 Jetson IP、不加心跳等），信息密度高但偏防御性叙述，可考虑用一个小节标题（如"边界声明"）拆分职责说明与否定式约束，提升可读性；非阻塞项。

未发现会影响合并的代码正确性或 secret 泄露问题——本 PR 仅修改 README.md，不涉及 app/components/hooks/lib 运行时代码，未发现 LiveKit 生命周期、React hook、Next.js 边界、环境变量硬编码等实质性风险。残余风险：文档中示例 IP 属于文档管理范畴，非代码缺陷。

[github-actions]

Claude finished @why-tomato's task in 3m 5s —— View job

---

任务清单

• 获取 PR diff (origin/lex-main...HEAD)
• 审查改动文件（README.md、session-provider.tsx、browser-room-session.ts、browser-runtime-compat.ts、测试文件）
• 输出审查结论

Review 结论

有条件通过

问题及建议

• [P1] PR 描述与实际 diff 不符：标题/Summary/Verification 均声称"仅文档改动"、"不改变 React 或 Next.js 运行时行为"、"Runtime diff across app, components, hooks, lib... -> exit 0"，但本次 origin/lex-main...HEAD 实际包含 3 个运行时文件的修改：components/app/session-provider.tsx、lib/browser-room-session.ts、新增 lib/browser-runtime-compat.ts（对应最新 commit 841b0fb fix: support browser UUIDs over LAN HTTP）。建议更新 PR 描述与验证记录以反映真实改动范围，否则会误导 reviewer 对本次改动风险的判断。
• [P1] components/app/session-provider.tsx:47：ensureBrowserRandomUuid() 直接在组件渲染函数体中调用，其内部会对全局 crypto 对象执行 Object.defineProperty 副作用（见 lib/browser-runtime-compat.ts:24），违反 React 渲染纯函数约定；且未使用 useMemo/useEffect，每次重渲染都会重复执行该检查（虽已幂等但存在不必要开销，且在 SSR/并发渲染下语义不清晰）。建议改为 useMemo(() => ensureBrowserRandomUuid(), []) 或在应用入口做一次性初始化。
• [P2] hooks/useBrowserSourceClient.ts:476 与 lib/connection-room-id.ts:24,36 仍直接调用 window.crypto.randomUUID() / crypto.randomUUID()，而非复用 lib/browser-room-session.ts 中新增的 createBrowserRandomUuid()。这些调用能正常工作依赖于 SessionProvider 已先完成一次渲染安装 polyfill 的隐式时序假设；一旦未来出现在 SessionProvider 挂载前调用 randomUUID 的路径，在不支持原生 API 的浏览器（非安全上下文/LAN HTTP）上会直接抛出异常。建议统一改用 createBrowserRandomUuid()，去除对全局补丁隐式安装顺序的依赖。
• [P2] tests/browser-runtime-compat.test.mjs:60-67：新增测试文件末尾的 AgentControlBar retains the high-level useChat send path 用例与本文件主题（randomUUID 兼容性）无关，且 components/livekit/agent-control-bar/agent-control-bar.tsx 并未被本 PR 修改，属于无关改动，建议移除或迁移到独立测试文件。
• [P2] README.md:125（历史遗留，本轮未修复）：pnpm dev --hostname 0.0.0.0 --port 4003 依赖 pnpm 透传未识别参数给 next dev，建议明确写作 pnpm dev -- --hostname 0.0.0.0 --port 4003。

其他说明

• lib/browser-runtime-compat.ts 中 UUID v4 生成逻辑（version/variant 位设置）正确，测试覆盖了原生 randomUUID 优先、polyfill 安装、以及 Object.preventExtensions 失败路径，质量较好。
• 未发现 secret 泄露或环境变量硬编码问题；README 中的内网 IP 属已知历史项，非本轮新增。

残余风险：P1 项主要影响可维护性和评审可信度，非明确的运行时 bug；P2 项均为非阻塞的健壮性/清理建议。

[github-actions]

Claude finished @why-tomato's task in 2m 19s —— View job

---

任务清单

• 获取 PR diff (origin/lex-main...HEAD)
• 审查改动文件（README.md + 新增运行时改动）
• 输出审查结论

Review 结论

有条件通过

问题及建议

• [P1] PR 描述与实际 diff 不符：PR 正文声称 "Changes documentation only" 且验证部分写的是 git diff --name-only origin/lex-main...HEAD -> README.md，但当前分支在此之上新增了提交 841b0fb fix: support browser UUIDs over LAN HTTP，实际改动了 components/app/session-provider.tsx（+17）、lib/browser-room-session.ts（+22/-1）、新增 lib/browser-runtime-compat.ts（+45）及对应测试文件，属于运行时逻辑变更（LAN HTTP 下 crypto.randomUUID 不可用时的 polyfill）。PR 正文里列出的 lint/test/build/无 Jetson IP 泄露等验证结论均基于旧的纯文档 diff，未覆盖这批新增运行时代码。建议更新 PR 描述以反映真实改动范围，并针对新提交重新跑一遍 lint/test/build。
• [P2] components/app/session-provider.tsx:47：ensureBrowserRandomUuid() 直接在组件渲染函数体中调用，且内部可能通过 Object.defineProperty 修改全局 crypto 对象，属于渲染期副作用（而非 useEffect）。虽然实现是幂等的（已安装则直接短路），当前不会引发明显 bug，但违反 React 渲染纯函数约定，在 StrictMode 双重渲染或并发渲染下存在潜在风险。建议改为模块级一次性执行，或用 useState(() => ensureBrowserRandomUuid()) 惰性初始化。
• [P2] tests/browser-runtime-compat.test.mjs:59-67：测试用例 AgentControlBar retains the high-level useChat send path 与本 PR 主题（浏览器 randomUUID LAN HTTP 兼容性）无关，断言的是 agent-control-bar.tsx 的 useChat 发送路径，且该用例内容与已归档分支 codex/endpoint-connectivity-probe 中的同名测试重复，疑似误合并的遗留代码。建议移除或迁移到独立测试文件，保持本文件聚焦于 browser-runtime-compat 的改动。
• [P2] README.md（延续上一轮审查未变更部分，如 117/145-147/155/166/174 行）：文档中仍硬编码内网 IP（如 10.2.77.108、10.2.2.199）作为示例地址，建议替换为占位符或注明仅为示例。

其余部分（lib/browser-room-session.ts 中 createBrowserRandomUuid/createBrowserRandomUuidFromRandomValues 的 UUIDv4 字节构造、lib/browser-runtime-compat.ts 的 polyfill 安装逻辑及失败回退路径、tests/browser-room-session.test.mjs 新增的三个用例）逻辑正确、测试覆盖到位，未发现功能性 bug 或 secret 泄露问题。

[why-tomato]

Review 处理结论

• 已失效：关于“PR 描述仍声称仅修改文档”的 P1 结论来自 Workflow Run 32965010215（attempt 2） 的旧 synchronize 事件快照。当前 PR 描述已明确列出 3 个运行时文件、2 个测试文件、253 项测试、production build 以及 Orin Start/Send/End 手动验收结果。
• 不阻塞：SessionProvider 中的兼容初始化是幂等操作，当前定向测试、全量测试和真实 Orin 验收均通过。渲染纯度属于后续可优化的 P2 维护性问题，没有发现需要本 PR 继续修改的运行时故障。
• 保留测试：AgentControlBar retains the high-level useChat send path 用于确认本次 UUID 修复没有重新引入自定义聊天发送路径，属于本次兼容修复的回归边界。
• 非浏览器路径：connection-room-id.ts 的实际 API Route 调用注入的是 Node crypto.randomUUID，不依赖浏览器 polyfill。
• 文档取舍：README 中的私网 IP 是当前 Orin 验收地址，明确用于本次部署验证，不代表引入 Jetson pairing、heartbeat 或 Endpoint Lease。

当前没有已确认需要阻塞合并的 P0/P1。PR head 保持 841b0fb261f00db80da8317d3701c5be2cd700d9。

[lanyue-llk]

Review 结论

通过。本轮没有发现新的阻塞问题。

我重新走了 LAN HTTP 下的调用顺序：SessionProvider 在创建 CompatibleSessionProvider 之前安装 crypto.randomUUID 回退，因此 useRoom、浏览器 Session ID 和 useBrowserSourceClient 的媒体 gate 都在兼容初始化之后运行。回退实现生成的 version/variant 位正确，且不会覆盖原生实现。

定向执行 tests/browser-runtime-compat.test.mjs 的 5 项用例均通过。tests/browser-room-session.test.mjs 在独立临时 clone 中因未安装本仓库的 typescript 依赖而未能复跑；PR 当前 CI 检查均为通过。现有评论里关于 PR 正文仍声称“仅文档改动”的结论已经失效，当前正文已列出运行时文件和验证范围。