AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(runtime): implement Claude Native and Claude core conformance
- Lingua principale
- TypeScript
- Stelle
- 0
- Fork
- 0
- Merge medio
- 8h 51m
- PR unite (30g)
- 99
Descrizione
> 由 #150 毕业的后续实施票,不进入 #144 本轮冻结执行 snapshot;本次仅建档,不启动实现。DRI 容量、真实资源与评审窗口尚未确定,Start/Target 留空。
## Problem
M1 要求 Claude 标准模板。当前公共 RuntimeHost/RuntimeDriver、Fake 与 Codex 实现不能证明 Claude 的真实模型选择、Session/Turn 恢复、事件规范化和多用户隔离。#436/#471 当前仅提供 Codex/Responses 配置链路,尚未证明本模板实际模型协议与原生配置可用。本票交付 Claude Native 核心 Driver 与真实文本/模型/恢复 conformance,为完整模板整装提供独立可验收的基础。
## Scope
- 在 `packages/agent-runtime` 实现固定的 Claude Native Driver,复用现有 `RuntimeDriver`;`apps/agent-runtime-host` 只负责进程启动、装配与 HTTP/SSE。按 Claude 实际原生协议映射请求、通知、状态查询与进程生命周期,不复用 Codex 原生语义。
- 按 #150 的复用约定,优先采用下列固定上游模块与回归场景;记录最终版本、文件/函数、采用方式、许可证/必要声明及本仓差异。静态绑定模板与 Driver、固定镜像 Digest,不增加插件发现或通用协议框架。
- 映射 submit、supplement、stop、status、lookup、replay、subscription 和 capability。原生 Session/Turn/request ID、协议帧与 vendor 类型不得越过 RuntimeHost。
- 本票负责 #436 之后首个非 Responses 消费方所需的共享扩展:在既有 ModelCatalog、访问验证、Worker 投影与 Host 配置中明确 profile 的可信绑定/传递,并接通 Claude Messages。保留修订、每选项 Secret 绑定、候选失败回滚及 Codex 路径;只增加当前真实消费者需要的字段与验证,不引入模型代理、路由或通用协议转换框架。
- Driver 只消费经过上述链路验证的 active 每选项配置,在原生 Turn 边界精确应用 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 必交能力。
### 实施起点与 Claude 差异
- 采用官方 Claude Agent SDK;优先移植 Paseo 的 [claudeQuery](https://github.com/getpaseo/paseo/blob/d1b705a0cd91617a5707fae25d80cb0be3057950/packages/server/src/server/agent/providers/claude/query.ts) 与 [ClaudeAgentSession](https://github.com/getpaseo/paseo/blob/d1b705a0cd91617a5707fae25d80cb0be3057950/packages/server/src/server/agent/providers/claude/agent.ts) 中 create/resume、Query 退役、进程退出及事件映射。保持本仓 Host 的身份、fence、持久请求和事件规则,不继承上游产品 Session、权限默认值或用户 HOME 配置。
- 实施前在本票内完成 Runtime HLD §13 的复用条款修订及共享模型配置对应 HLD/工程 Spec/必要 ADR 对齐,完成适用消费方评审;#438/#439 消费这份共同契约。Issue 文字不直接覆盖现行禁止复制条款。
- 根据 [Claude Gateway 契约](https://code.claude.com/docs/en/llm-gateway) 验证实际 Messages 路径与认证配置,覆盖 `/v1/messages` 及 Runtime 所需的 `/v1/messages/count_tokens`;Responses 探测成功不能替代该验证。
- `setModel()` 只改模型名,不证明 endpoint/credential 已切换。先验证 SDK 的实际重配能力;必要时在无活跃 Turn 的边界退役旧 Query/进程,并带新选项配置恢复原 native Session。不得并行创建替代 Session,必须证明旧执行已停止、凭证未串用及会话连续。
- 可选 supplement/steer 优先复用 [interrupt/restart 回归](https://github.com/getpaseo/paseo/blob/d1b705a0cd91617a5707fae25d80cb0be3057950/packages/server/src/server/agent/providers/claude/agent.interrupt-restart-regression.test.ts);`discardQueuedSteers` 使用的可选 `cancelAsyncMessage` 不在 SDK 公共 Query 类型中,必须绑定所选 SDK 实测。未证明队列清理和持久去重前保持能力关闭。
## Acceptance criteria
- [ ] **AC-1:** 固定版本的 Claude Native 实现既有 Driver 核心操作与静态模板装配;原生 ID、对象、协议帧和客户端类型不暴露给 Worker、Web 或公共 wire contract。
- [ ] **AC-2:** submit V2 在每次原生执行入口应用准确的 active model option/reasoning;缺失、失效、不支持或冲突的选择在 Turn 副作用前稳定拒绝,不使用其他选项或进程默认值。获准的有效选择必须真实成功。同一 Conversation 下一条消息可切换不同 endpoint/credential 的有效选项;即使 modelId 相同也不串用凭证,必要的 Query 重建仍恢复原 Session。
- [ ] **AC-3:** 相同请求重放一个持久结果,变更请求稳定冲突;accepted/unknown/busy/stop 均有明确状态,不重复启动 Turn。可选补充指令未通过持久去重 conformance 时不启用。
- [ ] **AC-4:** Host/原生进程和 Pod 重启后恢复原 Session、Turn 状态与事件游标;损坏或不可恢复状态只使该 Conversation 不可用,保留历史且不静默替换 Session;其他 Conversation 继续工作。
- [ ] **AC-5:** 规范化事件保持稳定排序、去重、重放与终态;未知、畸形和迟到消息按既有契约处理。日志、错误、审计和证据均不暴露原始凭证、敏感 endpoint、供应商正文或普通会话正文。
- [ ] **AC-6:** 自动化负向测试覆盖跨 Agent/Conversation/generation、旧 fence 和伪造原生引用;真实原生双用户验证包含各自有效正向对照、会话/工作区/个人记忆/上下文隔离、并行使用和重启后隔离,不能只凭 Host 拒绝或未观察到泄漏判断通过。
- [ ] **AC-7:** 固定模板镜像采用不可变来源和 Digest,以 non-root、只读根文件系统及明确可写挂载运行;通过 #405 的依赖与镜像政策,不降低门禁或自批例外。
- [ ] **AC-8:** 公共及专属 conformance、真实 Claude 文本/模型/恢复/隔离测试通过,证据绑定干净 source SHA、实际镜像 Digest、配置版本、原生版本与实际模型。文件和 Connection 明确未验收且产品入口不可用,不宣称完整模板上线。
- [ ] **AC-9:** 复用条款及共享配置契约完成正式对齐和适用评审;Messages 的实际访问验证、profile 投影与 Host 原生消费通过,错误协议/认证/能力在候选激活前拒绝并保留上一 active 修订。Codex/Responses 及每选项 Secret/回滚回归保持通过,#438/#439 可消费同一共同配置契约。
## Validation
- 运行协议 framing/correlation、模型选择、状态/lookup、replay/subscription、停止、崩溃窗口、畸形/迟到通知、脱敏和跨绑定负向测试。
- 对真实 Driver 运行现有共享 conformance;分别验证核心操作、可选能力和 V1/V2 兼容,不按协议名称推断能力。
- 构建并检查固定镜像、权限、挂载与扫描报告;在获准隔离环境用真实原生 Runtime、获准模型和当前镜像完成 AC-4/AC-6/AC-8。资源未提供时保持未验收,不以合成结果替代。
- 执行 `AGENTS.md` 完整仓库验证序列与 current-head Standards/Spec Review;只保留脱敏版本、命令、结果和证据引用。
- 增加 Messages 正负 preflight、不同 endpoint/credential 的连续 Turn 切换及旧 Query 清理测试;复用 [runtime-exit 场景](https://github.com/getpaseo/paseo/blob/d1b705a0cd91617a5707fae25d80cb0be3057950/packages/server/src/server/agent/providers/claude/agent.runtime-exit.test.ts),验证旧 Query 迟到退出不污染新 Turn、恢复失败清理进程。可选队列取消按固定 SDK 版本单独验收。
## Blocked by
- #405
- #436
## 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 的已交付配置基础保持唯一归属;本票承担后续最小共享扩展,不重开或重写上述基础。
- #165 只将文件从首个 Pilot 延后,完整 M1 文件能力仍必交;#432 对齐前不实施 Connection 路线。#150 继续拥有文件、Connection 和完整模板整装验收的毕业责任。本票完成不等于完整模板或 M1 上线。
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.