AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(runtime): implement Pi RPC and Pi core conformance
- Langage dominant
- TypeScript
- Étoiles
- 0
- Forks
- 0
- Merge moyen
- 8 h 51 min
- PR mergées (30 j)
- 99
Description
> 由 #150 毕业的后续实施票,不进入 #144 本轮冻结执行 snapshot;本次仅建档,不启动实现。DRI 容量、真实资源与评审窗口尚未确定,Start/Target 留空。
## Problem
M1 要求 Pi 标准模板。当前公共 RuntimeHost/RuntimeDriver、Fake 与 Codex 实现不能证明 Pi 的真实模型选择、Session/Turn 恢复、事件规范化和多用户隔离。#436/#471 当前仅提供 Codex/Responses 配置链路,尚未证明本模板实际模型协议与原生配置可用。本票交付 Pi RPC 核心 Driver 与真实文本/模型/恢复 conformance,为完整模板整装提供独立可验收的基础。
## Scope
- 在 `packages/agent-runtime` 实现固定的 Pi RPC Driver,复用现有 `RuntimeDriver`;`apps/agent-runtime-host` 只负责进程启动、装配与 HTTP/SSE。按 Pi 实际 RPC 生命周期完成请求/通知关联与状态查询;将上游客户端类型和原生对象封装在 Driver 内,不要求未经验证的特定 SDK API。
- 按 #150 的复用约定,优先采用下列固定上游模块与回归场景;记录最终版本、文件/函数、采用方式、许可证/必要声明及本仓差异。静态绑定模板与 Driver、固定镜像 Digest,不增加插件发现或通用协议框架。
- 映射 submit、supplement、stop、status、lookup、replay、subscription 和 capability。原生 Session/Turn/request ID、协议帧与 vendor 类型不得越过 RuntimeHost。
- 消费 #436 及 #437 扩展后的 active 每选项配置;本票负责 Pi 实际 provider/profile 的访问验证和原生模型/thinking 映射,沿用共同 Schema/投影/候选激活流程。精确应用 submit V2 的 `modelOptionId`/`reasoningLevel`,不在 Driver 重查目录、SecretRef 或 Platform 默认值,不静默换模型,保留 V1 兼容。
- 在 Agent PVC 持久保存必要的 Session/Turn、请求去重和事件游标映射。重启恢复原 Session;恢复失败只隔离对应 Conversation,不静默新建 Session。
- 将文本、状态、工具摘要、完成和错误规范化为既有 Schema;原生文件引用可做协议映射,但公共 ObjectStorage 和端到端文件传输不属于本票。日志与错误不记录凭证、敏感 endpoint、原生帧、供应商响应正文或普通会话正文。
- 复用现有公共 conformance 的断言和 fixture 工厂,按需做最小抽取,不复制三份 Codex 测试或新建测试框架;协议特有回归优先采用上游场景。覆盖重复/冲突命令、接受结果不确定、繁忙、停止竞态、重放和进程退出;真实原生验证不能由 Fake 或旧版本报告替代。
- 核心必需操作不能用 unsupported 代替交付。补充指令等可选能力仅在 Registry 声明和 conformance 均通过时启用。文件与 Connection 对产品入口保持不可用,待 #150 后续完整整装票验收;不削减正式 M1 必交能力。
### 实施起点与 Pi 差异
- 优先复用 Paseo [PiCliRuntime/PiCliRuntimeSession](https://github.com/getpaseo/paseo/blob/d1b705a0cd91617a5707fae25d80cb0be3057950/packages/server/src/server/agent/providers/pi/cli-runtime.ts)、[buildPiLaunch](https://github.com/getpaseo/paseo/blob/d1b705a0cd91617a5707fae25d80cb0be3057950/packages/server/src/server/agent/providers/pi/runtime.ts) 的持续 RPC、请求关联、进程清理和会话恢复;Open Design [mapPiRpcEvent](https://github.com/nexu-io/open-design/blob/ad9078b87c2d08e537ca3e041c46c124e7380c9c/apps/daemon/src/agent-protocol/pi-rpc/events.ts) 作为纯事件映射起点。先核对可直接依赖的实际客户端/export;不可独立导入时移植所需叶子模块,不强绑未经验证的 SDK API。
- 保持持久 RPC 会话,区分 `prompt` ACK 与执行终态,以 `get_state`/`get_messages` 和已持久化映射核验实际状态;记录请求去重、事件游标与确定的 session file 所属关系。按原文件恢复原 Session,不能按最近修改文件猜测归属,或用 `new_session(parentSession)` 替代精确恢复。
- 在无活跃 Turn 的边界应用每选项 endpoint/credential、provider/model 与 thinking 映射并复验;映射 `abort` 与可选 `steer`,不能把 ACK、abort 发出或状态查询成功当作完成/停止确认。接受不确定时沿用 Host unknown 契约,不盲重投。
- 不移植上游自动 confirm=true、自动选第一项答案或产品默认权限;工具交互按本仓已批准策略处理。supplement/steer 仍须通过声明、持久去重和停止竞态 conformance 才启用。
## Acceptance criteria
- [ ] **AC-1:** 固定版本的 Pi RPC 实现既有 Driver 核心操作与静态模板装配;原生 ID、对象、协议帧和客户端类型不暴露给 Worker、Web 或公共 wire contract。
- [ ] **AC-2:** submit V2 在每次原生执行入口应用准确的 active model option/reasoning;缺失、失效、不支持或冲突的选择在 Turn 副作用前稳定拒绝,不使用其他选项或进程默认值。获准的有效选择必须真实成功。provider/model/thinking 与实际 endpoint/credential 绑定一致,连续 Turn 切换有效选项保持原 Session。
- [ ] **AC-3:** 相同请求重放一个持久结果,变更请求稳定冲突;accepted/unknown/busy/stop 均有明确状态,不重复启动 Turn。可选补充指令未通过持久去重 conformance 时不启用。Pi prompt ACK 与 terminal event 分开判断,持久结果不把 ACK 当作终态;abort/steer 竞态不得误报完成或停止。
- [ ] **AC-4:** Host/原生进程和 Pod 重启后恢复原 Session、Turn 状态与事件游标;损坏或不可恢复状态只使该 Conversation 不可用,保留历史且不静默替换 Session;其他 Conversation 继续工作。session file 归属可确定回读,不用文件时间猜测或新建子 Session 替代。
- [ ] **AC-5:** 规范化事件保持稳定排序、去重、重放与终态;未知、畸形和迟到消息按既有契约处理。日志、错误、审计和证据均不暴露原始凭证、敏感 endpoint、供应商正文或普通会话正文。
- [ ] **AC-6:** 自动化负向测试覆盖跨 Agent/Conversation/generation、旧 fence 和伪造原生引用;真实原生双用户验证包含各自有效正向对照、会话/工作区/个人记忆/上下文隔离、并行使用和重启后隔离,不能只凭 Host 拒绝或未观察到泄漏判断通过。
- [ ] **AC-7:** 固定模板镜像采用不可变来源和 Digest,以 non-root、只读根文件系统及明确可写挂载运行;通过 #405 的依赖与镜像政策,不降低门禁或自批例外。
- [ ] **AC-8:** 公共及专属 conformance、真实 Pi 文本/模型/恢复/隔离测试通过,证据绑定干净 source SHA、实际镜像 Digest、配置版本、原生版本与实际模型。文件和 Connection 明确未验收且产品入口不可用,不宣称完整模板上线。
## Validation
- 运行协议 framing/correlation、模型选择、状态/lookup、replay/subscription、停止、崩溃窗口、畸形/迟到通知、脱敏和跨绑定负向测试。
- 对真实 Driver 运行现有共享 conformance;分别验证核心操作、可选能力和 V1/V2 兼容,不按协议名称推断能力。
- 构建并检查固定镜像、权限、挂载与扫描报告;在获准隔离环境用真实原生 Runtime、获准模型和当前镜像完成 AC-4/AC-6/AC-8。资源未提供时保持未验收,不以合成结果替代。
- 执行 `AGENTS.md` 完整仓库验证序列与 current-head Standards/Spec Review;只保留脱敏版本、命令、结果和证据引用。
- 增加 prompt ACK/terminal 分离、get_state/get_messages 与持久结果核对、确定 session file 恢复、模型/thinking 切换、abort/steer 竞态及进程退出回归;真实模型调用与协议模拟各自记录结果。
## Blocked by
- #405
- #436
- #437
## Authority
- Agent Platform PRD §§4、7、8、12、14;工程 Spec §§10.7、11、17、19;Runtime HLD §§3–8、11。正式依据为 `main@f0e8aa58ca90dec2583459818c1167781979235f`。
- #181 的公共 RuntimeHost/Driver、#376 的 submit V2 与 #436 的已交付配置基础保持唯一归属;#437 负责 HLD 复用条款和首个非 Responses 共享配置扩展,本票在其共同契约上接入实际原生协议。
- #165 只将文件从首个 Pilot 延后,完整 M1 文件能力仍必交;#432 对齐前不实施 Connection 路线。#150 继续拥有文件、Connection 和完整模板整装验收的毕业责任。本票完成不等于完整模板或 M1 上线。
Guide de contribution
Aucun guide de contribution indexé pour ce dépôt
Évaluation
Cette issue n'a pas encore été évaluée.