Skip to content

feat(runtime): add Claude Native driver and Messages configuration - #478

Merged
sda-rob merged 11 commits into
mainfrom
feat/437-claude-native
Sep 14, 2026
Merged

sda-rob merged 11 commits into
mainfrom
feat/437-claude-native

Conversation

@LichKing-2234

@LichKing-2234 LichKing-2234 commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

Pull Request

Closes #437

变更摘要

Claude 模板此前缺少真实 Native Driver,既有模型配置链路只支持 Responses。本 PR 接入固定版本的官方 Claude Agent SDK,实现独立 Conversation Session、持久请求去重、事件恢复、停止与隔离;ModelCatalog → Worker → Host 通过可信模板绑定消费 Messages V3 配置。

  • 采用 Paseo 的 create/resume 与 Query 退役方式,固定上游 d1b705a0cd91617a5707fae25d80cb0be3057950,保留 Apache-2.0 声明。SDK 0.3.246、Native 2.1.246 固定并校验实际文件哈希。
  • endpoint、credential 或 reasoning 改变时,在 Turn 边界退役旧 Query 并恢复原 Session。真实凭证只进入每个 Query 的固定本地传输,不进入原生进程或会话文件。
  • Query 退役要求直接 child close 且整个进程组探测为 ESRCH;TERM、KILL 各等待最多 2 秒,无法证明退出时返回脱敏错误。补齐 leader 退出后遗留子孙进程、KILL 拒绝及不退出回归。
  • 使用官方 SDK 全量读取 Session 历史,去掉 10,000 条首窗截断,保留资源上限与连续性验证。新增超过 10,000 条的真实 Native transcript 回归。
  • Messages 预检补齐固定 Native 的 fallback-credit-2026-06-01 beta。templateModelBindings 必填,缺失时在打开 Store 前拒绝启动;部署包升级要求见 deploy/README.md
  • 工程 Spec、Runtime HLD 与 ADR-0009 对齐 Messages V3,保留 Responses V2 指纹、每选项 Secret、候选失败回滚及 Codex 行为。当前版本要求 count_tokens 成功。
  • supplement、文件和 Connection capability 保持关闭;本 PR 交付 Claude 核心 Driver,不代表完整模板或 M1 上线。
  • 已合入 test(runtime): add native Codex isolation acceptance probes #413,保留 Codex §10.9 / ADR 0008;Claude 章节顺延为 §10.10 / ADR 0009,并同步引用。
  • thinking 初始 signature 纳入既有分片凭证检查;合法签名正向及跨帧凭证负向回归通过。
  • V3 生成源、JSON Schema 和工程 Spec 明确结构校验与语义准入的边界;选项唯一性及默认关联继续由 Worker、Host 消费同一共享 Schema 校验。
  • Messages 预检补齐 Runtime 所需首帧字段校验,完整合法 fixture 与 10 个新增负向用例通过,避免畸形响应通过候选准入。

验收标准

以下 pass 表示当前提交的技术验收证据已齐备;人工验证确认与 CODEOWNER Review 仍需按流程完成。

AC Status Evidence
AC-1 pass 固定 Claude Driver、Host 静态装配与共享 conformance;SDK/Native 类型不进入公共 wire contract。
AC-2 pass 准确模型/reasoning、失效选择拒绝和 Query 退役回归通过。实际 Linux 镜像三轮 direct→HTTPS relay→direct、medium→high→medium 完成;独立凭证、实际路由与原 Session/context 连续。
AC-3 pass 持久重放/冲突、unknown/busy、stop 竞态、取消恢复及旧 Query 退役回归通过;Pod 重启后重复 submit 保持同一结果身份,不增加 Driver Turn 记录。可选 supplement 未启用。
AC-4 pass 实际镜像第一次 Pod 重建后恢复原 Session、状态及游标,全量/游标重放精确匹配。第二次重建验证损坏会话 status=unavailable、新 submit 503,原文件/历史不变、不建替代 Session,另一个用户继续原 Session。
AC-5 pass 事件排序/去重/终态、原生历史恢复和传输脱敏回归通过;真实 Pod 的 16 个运行时文件和 Host 日志、镜像入口切换的 6 个 Native 文件未检出模型凭证。
AC-6 pass 自动跨 Agent/Conversation/generation/fence/引用负向回归通过。实际镜像双用户并行写读自身文件与记忆,重启后逐项关联 SDK 实际 Read/tool-result:各自正向成功,指向对方文件/记忆的 symlink 读取均拒绝,上下文保持独立。
AC-7 pass 干净源码构建的不可变镜像,OCI index/manifest/config 和 layers 回读一致;实际 Pod non-root、只读根、明确可写挂载、无提权。当前镜像按仓库漏洞政策检查通过,无例外。
AC-8 pass 公共/专属 conformance 及真实文本、模型切换、Pod 恢复和隔离通过。下列实际镜像证据绑定 source SHA、Digest、配置版本、Native 版本/哈希和模型;文件与 Connection 产品入口不可用。
AC-9 pass 正式契约及双轴评审完成;真实 count_tokens、medium/high Messages 与工具 SSE 预检、共享 projection→V3 injection→Host reader→Native 消费通过。错误协议/认证/能力、候选回滚、Codex/Responses 和每选项 Secret 回归通过。

自动验证

  • Head:b1c1492a571a7b7b80a1d1a4e24dc34cd6d5e517;Standards 与 Spec 独立评审覆盖 tree 6ea0b6fd436e81b4dde1a3500349ca73e62a2ccd,各 0 个剩余发现;下述新镜像及真实环境证据已由两位评审分别复核。
  • 当前提交 CI:通过。Runtime 542 passed / 16 skipped,固定 Linux 镜像 Claude 原生测试 60 passed;Kubernetes、Web、构建、smoke、全部部署镜像、Markdown 与 workflow 检查通过。
  • CI 依赖及五个部署镜像漏洞政策通过,0 blocking findings / 0 errors、无例外。上传后下载并校验通过,本地再次下载运行仓库 verifier 亦通过;source、run/attempt、lockfile、构建镜像及报告哈希一致。artifactvulnerability-b1c1492a571a7b7b80a1d1a4e24dc34cd6d5e517-34737955584-1;verdict SHA-256 d667d781532047811882991503bb08c56b5e55c007a0a4b85cb10bfa2aeefd8c
  • Automated Review Coverage 通过。有效发现已修复;不适用建议已按固定 SDK、validator 抛错契约、路径归属边界、同步启动与异步准入时序及 JSON Schema 具名定义消费方式回复,所有评审线程均已 resolve。
  • 本地 frozen install、check、types、全量 test、build、smoke、Markdown/链接、workflow/actionlint 与 diff 检查通过;types/test 使用 --concurrency=1。针对实际 Native 进程启动/历史读取超过外层 5 秒的 CI 超时,在共享 Claude 模型切换用例及 Claude Native 集成测试文件使用 30 秒测试期限,断言、fixture 等待和产品退出期限保持不变。合并后的首次本地全量测试曾命中未修改的 Codex fixture 的 5 秒超时,原样重跑通过;最终增量的完整本地验证序列通过。
  • 本地全量 pnpm docker:build 因 npm 下载超时失败;当前提交 CI 的全部镜像构建通过,以下实际 ARM64 Runtime 镜像也已独立构建、扫描与验收。

当前实际镜像与真实模型证据

全部使用 claude-opus-5、SDK 0.3.246 / Native 2.1.246,绑定干净 source b1c1492a571a7b7b80a1d1a4e24dc34cd6d5e517。镜像从该提交的 git archive 按原 Dockerfile 构建。

证据 绑定与结果
镜像 OCI index/image ID sha256:3f3d650ba02dacb69997c20c6ebed231465ba9d8522103cb4a52b89b5720187a;ARM64 manifest sha256:582bf2d22af7a1596e86a99053009971732c6c119451379030dc8666dcdcad28;config sha256:aab6efc2b16142c16afc937ea02ec709a01ad6b7a1cc0c6b63f242e52af5fe10。registry bytes、layers、source label 回读一致。provenance 报告 SHA-256 6805cb99c606716c38d21e0054b1d5c33c89bfeedc0d617fd171d5aac5ff2b0f
实际 Native Linux ARM64 可执行文件 SHA-256 8f7d77a91b95dbeda31393463b2ac7d2b490c577486829b732ce1ac41a747034;Pod 与入口切换容器相同。
Pod 验收 20/20 pass,两次实际 Pod UID 更换、同 Digest、原 Session 恢复、精确事件重放/游标/去重、双用户实际 Read 隔离、损坏会话保留历史与 peer 可用。配置 configuration-1-0478cad2f265a472a15b96a18539d57de7011f2254e4039bd87e6d52202b5cff;报告 SHA-256 665fc84e3ca4c430ec3ce09f4943085db37f51ffbd7a9e6db0d5b077b928241e,harness SHA-256 8b389a29dd8e193ea4b279fc945898f53e6e37a606ad0a2da3cc532fbb4ff311
镜像内入口切换 3/3 completed,direct→relay→direct;同 modelId,medium→high→medium,独立凭证、正常 TLS、错误 relay 凭证在上游调用前 401,实际 relay 路由与 high effort 匹配。原 ref/Native Session/context 连续,唯一 Session 目录与绑定,凭证未持久化。配置 container-endpoint-7c604126-4768-453f-a818-5657c66a5f34;报告 SHA-256 9e9ded0ed5622539a11af4912e71d9a5a51a7783fd0714317f70382780227685,harness SHA-256 e8f3ad371168bdb72c1e96edb4ca5e175a4f2041053f808ba87217897712f2cd
补充 ARM64 镜像扫描 checksum 校验的 Trivy 0.74.0、有效数据库、完整 OS/应用 inventory,复用仓库扫描策略,无例外:0 blocking / 0 errors;仍有 5 项 MEDIUM。verdict SHA-256 8ac4d48b3ed2453c9626c9c665e4bd4096f057ef69ed03cc3fc7951a31ad7d9f
  • 第二入口是获准自建的认证 HTTPS relay,转发到同一真实上游,未合成模型响应;证明不同 endpoint/credential 切换,不代表两个独立 provider。临时 CA 仅在测试进程中受信,未关闭 TLS 校验。
  • 共享 Messages 配置链路另经真实本机预检/投影/Host 读取验证,包含完整 Native beta、两种 reasoning 和工具 SSE;报告 SHA-256 7da5fa37d5b15ac74f6beeea0bc898d93264a1e2bf2da091724ac9b73dffd223。该本机报告 imageDigest=null;实际 Linux 切换由上表独立证明。
  • 隔离环境为本地 Colima,使用合成签名身份和模板准入装配;真实模型、当前 RuntimeHost HTTP/SSE 和当前镜像均参与测试。不宣称正式模板准入、生产激活或完整产品流程。
  • 双用户负向向量为 symlink-escape,用 SDK 历史逐项关联实际 Read 与结果;任何越界成功或 canary 泄漏均使测试失败。直接路径拒绝另有同版本 Native CLI + 合成模型的重启前后回归。
  • 模型凭证仅通过获准本机配置/stdin、测试内存及临时本地 Kubernetes Secret 使用,未写入仓库、报告、CI 或个人配置。测试 namespace(含 Secret/PVC)与切换容器已删除并回读确认;保留脱敏报告供人工复核。

人工验证

结论:需要人工确认,保留 ready-for-human

  • 对当前 head 复核上述实际镜像、真实模型切换、Pod 恢复与双用户隔离证据及其范围。
  • 按开发工作流 §7.4,由 CODEOWNERS Team 非 Bot 成员完成验证后移除 ready-for-human;CODEOWNER Approve 独立完成。技术验收 pass 不代替这两项人工动作。

风险与回退

  • 模型选项仍须逐项通过实际 Messages 预检;一个凭证成功不能替代其他候选验证。
  • Native 协议与恢复依赖固定版本,升级须重跑共享/专属 conformance 和真实隔离验收。
  • 升级 Worker 部署包时必须提供可信 templateModelBindings,custom-only 装配显式传 []
  • 回退到上一已验证模板镜像和 active 配置修订;保留 PVC 历史,不静默替换不可恢复 Session。

@LichKing-2234 LichKing-2234 added the ready-for-human Human implementation on an Issue or pending human validation on a PR label Sep 12, 2026
@LichKing-2234
LichKing-2234 marked this pull request as ready for review September 13, 2026 01:46
@LichKing-2234
LichKing-2234 requested a review from a team as a code owner September 13, 2026 01:46
@sda-rob
sda-rob enabled auto-merge (squash) September 13, 2026 01:46

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR-Agent Review

Commit: d30757960f7746b907332ec7a449ef6cfab444d1

5 finding(s) published as review threads.

Comment thread packages/model-catalog/src/messages-access.ts
Comment thread apps/platform-worker/src/workload-runtime.ts
Comment thread packages/agent-runtime/src/claude-runtime-driver.ts
Comment thread packages/agent-runtime/src/claude-query.ts Outdated
Comment thread packages/agent-runtime/src/claude-query.ts Outdated
Comment thread packages/agent-runtime/src/claude-runtime-driver.ts

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR-Agent Review

Commit: fbe1b091b464fa3a0d59b46113aa3931f705870f

1 finding(s) published as review threads.

Comment thread deploy/runtime/claude-conformance.mjs
Comment thread packages/agent-runtime/src/claude-runtime-driver.ts
@sda-rob sda-rob removed the ready-for-human Human implementation on an Issue or pending human validation on a PR label Sep 13, 2026
sda-rob
sda-rob previously approved these changes Sep 13, 2026
@github-actions github-actions Bot added the ready-for-human Human implementation on an Issue or pending human validation on a PR label Sep 13, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR-Agent Review

Commit: 1cb102ca6078a9c531e19a1a3de5155ff5108916

2 finding(s) published as review threads.

Comment thread packages/agent-runtime/src/claude-runtime-driver.ts
Comment thread packages/agent-runtime/src/claude-messages-stream.ts
Comment thread packages/agent-runtime/src/claude-runtime-driver.ts

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR-Agent Review

Commit: 3c2acbdf0029429fd7bd6dcfc12d409fa4702366

1 finding(s) published as review threads.

Comment thread packages/contracts/src/generate.mjs
Comment thread packages/agent-runtime/src/claude-runtime-driver.ts
Comment thread packages/agent-runtime/src/claude-runtime-driver.ts
Comment thread packages/model-catalog/src/messages-access.ts

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR-Agent Review

Commit: b1c1492a571a7b7b80a1d1a4e24dc34cd6d5e517

1 finding(s) published as review threads.

Comment thread packages/agent-runtime/src/claude-runtime-driver.ts
Comment thread packages/agent-runtime/src/claude-workspace.ts
Comment thread packages/agent-runtime/src/claude-runtime-driver.ts
@sda-rob sda-rob removed the ready-for-human Human implementation on an Issue or pending human validation on a PR label Sep 14, 2026
@sda-rob
sda-rob merged commit 976fb74 into main Sep 14, 2026
75 of 76 checks passed
@sda-rob
sda-rob deleted the feat/437-claude-native branch September 14, 2026 02:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants