# Code Agent Chat Readiness Runbook

本文定义 Cloud Workbench `POST /v1/agent/chat` 的 readiness 判定。它只处理
Code Agent 回复链路是否具备复测条件，不修复、不读取、不打印、不创建也不修改任何
Secret 或 token。

## 运行边界

- DEV Cloud Web 入口是 `http://74.48.78.17:16666/`，同源代理到
  `/v1/agent/chat`。
- DEV API/edge 入口是 `http://74.48.78.17:16667/`；它不能替代 Workbench
  同源聊天入口的真实回复证据。
- `internal/cloud/code-agent-chat.mjs` 是 `/v1/agent/chat` 的后端处理入口。
- `scripts/code-agent-chat-smoke.mjs` 是 Code Agent chat schema 与 readiness
  gate。
- `scripts/dev-cloud-workbench-smoke.mjs --static` 只验证 Workbench 源码合同和
  `/v1/agent/chat` 前端接线；它不是 DEV-LIVE 回复证明。

## Provider 前置条件

当前 DEV 部署合同中 `hwlab-cloud-api` 的 Code Agent provider 是
`HWLAB_CODE_AGENT_PROVIDER=codex-stdio`。运行时必须具备 repo-owned Codex MCP
stdio session supervisor，并证明 `/workspace/hwlab` 可读写、`CODEX_HOME=/codex-home`
可写、`/app/node_modules/.bin/codex --version` 可执行、`codex mcp-server`
可通过 MCP initialize/tools/list 观测到 `codex` 与 `codex-reply`。

Codex token boundary 仍由授权路径把 `OPENAI_API_KEY` 注入到 DEV runtime。DEV Pod
必须使用 `HWLAB_CODE_AGENT_OPENAI_BASE_URL` 指向受控 DEV egress/proxy 路径
`http://172.26.26.227:17680/v1/responses`，不能直接指向 public `api.openai.com`。

Runner 不得尝试修补、读取、回显或替换该 Secret。若 DEV runtime 缺少该授权凭证注入，
`provider_unavailable` 且 `error.missingEnv` 包含 `OPENAI_API_KEY` 必须判为
`BLOCKED/credential`。

部署前和部署后的自动化只允许证明 env 名称、`secretKeyRef` 的 Secret 名和 key 名、以及
DEV egress/base-url 合同是否声明和保留；不得读取 Secret data，也不得把 Secret 值写入
report、issue、PR 或截图。

## 判定标准

| 观测结果 | readiness |
| --- | --- |
| `status: "failed"`，`error.code: "provider_unavailable"`，且 `error.missingEnv` 包含 `OPENAI_API_KEY` | `BLOCKED/credential`；provider 凭证缺失，不能标真实回复通过。 |
| `provider: "codex-readonly-runner"` 且 `sessionMode: "controlled-readonly-session-registry"`、`capabilityLevel: "read-only-session-tools"`、`session.status` 为 `idle/ready/busy`、`session.idleTimeoutMs` 和 `session.lastTraceId` 存在、`session.longLivedSession: true`、`longLivedSessionGate.status: "blocked"`、`runnerLimitations` 包含 `not-codex-stdio` / `not-write-capable` / `process-local-session-registry` | 可标为 #317 read-only long-lived session registry pass；不能关闭 full Codex stdio/session capability blocker。 |
| `codexStdioFeasibility.status: "blocked"`，或 blocker 包含 `codex_cli_binary_missing`、`codex_cli_not_executable`、`codex_cli_native_dependency_missing`、`runner_lifecycle_missing`、`stdio_protocol_not_wired`、`workspace_mount_missing`、`workspace_write_boundary_blocked`、`codex_home_missing`、`codex_home_write_blocked`、`provider_token_boundary` | 真实 Codex stdio / 等价 long-lived runner 未具备；必须按 blocker 处理，不能表述为完整 Codex session。 |
| `status: "completed"`，但来自 mock、fixture、本地 stub、source-only smoke、浏览器本地回显或人工拼接 | 不是 DEV-LIVE reply pass。 |
| 真实 DEV `POST /v1/agent/chat` 返回 `status: "completed"`，且 `reply.content` 是非空 assistant 回复 | 可标 DEV-LIVE reply pass。 |
| 传输失败、schema 不完整、HTTP 非预期、`reply.content` 为空或缺失 | `BLOCKED`，按 runtime/schema/transport 分析。 |

只有“真实 DEV 路由 + `completed` + 非空 assistant reply”能作为 DEV-LIVE 回复通过依据。
不得把 mock、fixture、本地 echo、source report、静态检查或前端状态当作通过。

## Runner 能力边界

`/v1/agent/chat` 可以先落地受控只读能力，但必须诚实区分：

- `controlled-readonly-session-registry`：由 cloud-api 进程内 registry 保存
  `conversationId/sessionId` 映射、`status`、workspace、sandbox、`createdAt`、`updatedAt`、
  `idleTimeoutMs`、`lastTraceId`、`turn` 计数与只读工具 trace。它可以覆盖 `pwd`、
  `skills.discover`、`ls`、`rg --files` 和 bounded `cat`，输出必须限长和脱敏。该模式是
  read-only long-lived session，但 `longLivedSessionGate` 必须保持 `blocked`，直到 Codex
  stdio 或等价 full Code Agent 协议通道真实接通。
- 该模式必须同时标记 `not-codex-stdio`、`not-write-capable`、`process-local-session-registry`。它不是
  Codex stdio / workspace-write session，不提供写文件、任意 shell、硬件写、Secret/kubeconfig/DB URL
  读取，也不证明 M3/M4/M5 trusted green。
- OpenAI Responses fallback 只能标记为 `openai-responses-fallback` /
  `text-chat-only`，不得满足 Codex runner capability gate。默认路径不得用 fallback
  冒充完整 Code Agent；仅明确允许 fallback 时才可作为普通文本备用通道返回。

当前 DEV/runtime 若要升级为完整 #275 runner，至少需要 repo-owned 的 Codex CLI/stdio 或等价
runner 二进制/协议适配、session supervisor 生命周期、workspace mount 与 sandbox 合同、token/Secret
注入边界、trace/cancel/reap 机制，以及与 cloud-api/workbench 的持久 session 映射。缺任一项时，必须
在 `codexStdioFeasibility` 中报告 blocker。

## Smoke Gate

本地合同检查：

```sh
node scripts/code-agent-chat-smoke.mjs
```

该命令验证 schema、`provider_unavailable` provider gap、`OPENAI_API_KEY`
missing-env 分类，以及本地 stub completion 不能升级为 DEV-LIVE pass。

Workbench 静态接线检查：

```sh
node scripts/dev-cloud-workbench-smoke.mjs --static
node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:16666/
```

该命令验证 Workbench 默认页、同源只读边界和 `/v1/agent/chat` 前端主流程接线。它只产出
`SOURCE` 级证据。`--dom-only` 会保留部署 runtime/web-asset identity preflight，
但只做真实 DEV DOM/help 只读观察；它不会发送 `/v1/agent/chat`，Code Agent journey
必须记录为 `not_applicable`，不能冒充真实 DEV-LIVE reply。

授权凭证注入后的真实 DEV 复测：

```sh
node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:16666/
```

`--live` 会向真实 DEV `/v1/agent/chat` 发送一条最小聊天请求。输出只包含
readiness、provider/model/backend、assistant 回复是否非空和长度、错误分类等摘要；不打印
assistant 回复正文，不读取或打印任何 Secret 值。

## 复测结果解释

- 若输出 `readiness.level: "BLOCKED/credential"`，后续动作是由授权路径注入
  `hwlab-code-agent-provider/openai-api-key`，不是由 runner 临时补 Secret。
- 若输出 `readiness.level: "#143 DEV-LIVE reply pass"`，只说明真实回复链路通过；
  它不自动证明 M3、M4、M5 或硬件闭环通过。
- 若 `scripts/dev-cloud-workbench-smoke.mjs --static` 通过，而 `--live` 未通过，结论是
  Workbench 接线和源合同通过，但真实 provider readiness 仍 blocked。

## 稳定来源

- [docs/reference/cloud-workbench.md](cloud-workbench.md)：Cloud Workbench 默认页和同源边界。
- [docs/reference/dev-runtime-boundary.md](dev-runtime-boundary.md)：DEV 端口、k3s 与运行态边界。
- [docs/reference/architecture.md](architecture.md)：`SOURCE`、`LOCAL`、`DRY-RUN`、
  `DEV-LIVE`、`BLOCKED` 证据分级。