AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(runtime): implement Claude Native and Claude core conformance

Aberta
#437 3 comentários 0 reações 1 responsável Reivindicada por @LichKing-2234 Ver no GitHub
Linguagem predominante
TypeScript
Estrelas
0
Forks
0
Merge médio
8h 51min
PRs com merge (30d)
99

Descrição

> 由 #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 上线。

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.