pikasTech-agentrun/docs/reference/spec-v01-backend-codex.md

# v0.1 Codex Backend 规格

Codex backend 是 AgentRun `v0.1` 的第一真实 Code Agent backend 候选。它用于证明 runner、backend adapter、Kubernetes Secret projection、真实 provider 调用、event normalization 和 terminal status 的完整闭环。

## 在系统中的职责划分

- 作为 `backendProfile=codex` 的具体实现。
- 使用真实 Codex/Codex-compatible 配置执行最短 turn，不使用 fake provider 作为综合联调通过证据。
- 消费 Kubernetes Secret projection 提供的 Codex 凭据文件。
- 把 Codex 输出归一化为 AgentRun 标准 events 和 terminal status。
- 将 provider/auth/protocol/timeout/cancel 错误映射为 [spec-v01-backend-adapter.md](spec-v01-backend-adapter.md) 定义的 failureKind。

## 协议选型与实现参考

`v0.1` Codex backend 的协议固定为 Codex CLI app-server JSON-RPC over stdio。Backend adapter 必须启动受控子进程：

```bash
codex app-server --listen stdio://
```

Adapter 通过 stdin 写入换行分隔 JSON-RPC 请求，通过 stdout 逐行读取 JSON-RPC response 和 notification，stderr 只作为有界诊断日志。最小请求序列是 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`；response 中必须提取 thread/turn identity，notification 和后续输出必须归一化为 `backend_status`、`assistant_message`、`tool_call`、`command_output`、`error` 和 `terminal_status` events。

不得把以下路径作为 `v0.1` Codex backend 的正式实现或综合联调通过证据：直接 Responses HTTP 代理、OpenAI SDK wrapper、`codex exec` 一次性命令输出、fake provider、固定文本回复、只读 shortcut 或本地 shell 模拟。裸 HTTP 或 `codex exec --json` 可以作为 provider/upstream 诊断，但最终通过必须来自 app-server stdio turn。

实现必须参考成熟代码：

| 参考 | 需要吸收的经验 |
| --- | --- |
| UniDesk `src/components/microservices/code-queue/src/code-agent/codex.ts` | Bun/TS 中 spawn `codex app-server --listen stdio://`、JSON-RPC request/response、thread start/resume、turn start、stderr 有界采集、exit/failure 分类。 |
| UniDesk `src/components/microservices/code-queue/src/code-agent/common.ts` | backend port/capability、model/profile 边界、文本 input shape、Git/proxy env 处理和 provider 端口归一化。 |
| HWLAB `internal/cloud/codex-stdio-session.mjs` | long-lived stdio session readiness、Codex home/workspace/protocol gate、child env redaction、trace recorder、cancel/timeout/failure kind。 |
| HWLAB `scripts/code-agent-chat-smoke.mjs` | fake app-server 自测试方式、`thread/start` + `turn/start` 调用顺序、session reuse、tool trace 和 Secret 不泄露断言。 |

这些参考用于协议和质量标准，不复制 UniDesk/HWLAB 的业务 prompt、硬件路径、tenant policy、hostPath Secret 做法或任何明文密钥。

## 测试凭据来源

`v0.1` 综合联调用的 Codex 测试凭据源固定为 operator 环境中的以下两个文件：

```text
~/.codex/auth.json
~/.codex/config.toml
```

这两个文件只能作为 Kubernetes Secret 创建或轮换的输入源，不能通过 hostPath 挂载进 Pod，不能复制进镜像，不能提交到 source branch、GitOps branch、artifact catalog、issue、PR、event、trace、日志或 CLI 输出。

`v0.1` 默认 Kubernetes Secret：

| 对象 | v0.1 规格 |
| --- | --- |
| Namespace | `agentrun-v01` |
| Secret name | `agentrun-v01-provider-codex` |
| Secret key | `auth.json`，来自 `~/.codex/auth.json` |
| Secret key | `config.toml`，来自 `~/.codex/config.toml` |
| Consumer | runner 或 backend adapter Pod |
| Projection target | 容器用户的 `~/.codex/auth.json` 和 `~/.codex/config.toml` |
| File mode | 只读，建议 `0400` 或等价最小权限 |

Kubernetes Secret 的创建、轮换和权限控制属于集群密钥管理流程；source branch 只声明 SecretRef 名称、key 和 mount intent。`deploy/deploy.json` 和 rendered GitOps manifest 不得包含 Secret data。

## Runtime 行为

- Adapter 必须在调用 Codex 前验证 `auth.json` 和 `config.toml` 均存在且可读；缺失时返回 `secret-unavailable`。
- Codex 运行时必须使用被投影的 `.codex` 目录；不得 fallback 到镜像内默认凭据或节点宿主机 `~/.codex`。
- 若 `config.toml` 指向 hyueapi 或其他 OpenAI-compatible upstream，runner/backend Pod 的 proxy 与 `NO_PROXY` 必须保持该配置可用；不得在日志中打印完整 auth/config 内容。
- 模型名、provider profile、upstream host 可以作为 redacted metadata 输出；provider credential、token、Authorization header 和文件内容不得输出。
- 一个最短 turn 至少要产生 `backend_status`、一个 assistant 或 error event、以及 `terminal_status`。

## 与 Secret 分发规格的关系

[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 是 SecretRef、Kubernetes projection、redaction 和 missing secret failure 的权威。本文件只定义 Codex backend 对测试凭据文件的消费方式。

Run 的 `executionPolicy.secretScope` 应引用 `agentrun-v01-provider-codex` 的 `auth.json` 和 `config.toml`，而不是携带 provider credential 或文件内容。

## 测试规格

### T1 Codex Secret projection

阅读 `AGENTS.md`、本文和 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)，然后在 `agentrun-v01` 中通过 Kubernetes Secret 管理把 operator 的 `~/.codex/auth.json` 与 `~/.codex/config.toml` 注入为 `agentrun-v01-provider-codex`。确认 runner/backend Pod 只能看到投影后的 `~/.codex/auth.json` 和 `~/.codex/config.toml`，没有 hostPath，日志和 event 不显示文件内容。

### T2 真实 Codex 最短 turn

阅读本文和 [spec-v01-validation.md](spec-v01-validation.md)，然后用 `backendProfile=codex` 创建真实 run 并提交一个最短 `turn` command。确认 runner 调用真实 Codex provider，manager 可查询 backend_status、assistant 或 error event、terminal_status，且 Secret value 未泄露。

### T3 Missing auth/config failure

阅读本文，然后分别移除或改名 Secret 中的 `auth.json`、`config.toml` key，启动真实 run。确认 adapter 在调用 provider 前失败为 `secret-unavailable`，failure response 为 JSON，日志不包含 Secret value。

### T4 Provider auth failure

阅读本文，然后使用无效的 Codex Secret 创建 run。确认 backend 返回 `provider-auth-failed` 或等价 failureKind，记录上游状态分类和 trace correlation，但不打印 Authorization header、token 或 auth/config 文件内容。

### T5 Provider availability failure

阅读本文，然后用 mock/fake Codex app-server 自测试 HTTP 503 `Service Unavailable`、携带 5xx 的 `responseStreamDisconnected` 或明确 temporary/provider unavailable 文案。确认 Codex adapter 返回 `provider-unavailable`，不会落到 `backend-failed`；综合联调若真实 provider 返回同类错误，应记录为外部 provider blocker，而不是本地 runner/backend 执行面 blocker。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| Codex backend 规格 | 已定义 | 本文为 v0.1 第一真实 backend 权威。 |
| Codex Secret projection | 未实现 | 需要后续 Kubernetes Secret 和 runner/backend manifest。 |
| Codex adapter | 已部分实现 | 当前代码已实现受控 `codex app-server --listen stdio://`、`initialize`/`thread/start`/`thread/resume`/`turn/start` response 校验、stderr 有界诊断、spawn/JSON parse/response invalid/timeout/provider 5xx availability failureKind 和 fake app-server 自测试。 |
| 错误可观测与脱敏 | 已部分实现 | child env、cwd、workspace 和 Codex home 只输出摘要；stderr tail 有界且标记截断；事件和 failure 统一走 redaction。 |
| 真实 provider turn | 未实现 | 综合联调必须真实完成后才能发布通过。 |
| hostPath `~/.codex` | 不采用 | 只能通过 Kubernetes Secret projection 注入。 |