# @xicode/pi-codex-pat

为 Pi 注册独立的 `openai-codex-pat` Provider，使用 OpenAI Codex Personal Access
Token 访问 Codex backend。

插件不会修改 Pi，也不会把 PAT 写入 `~/.pi/agent/auth.json`。认证信息按以下优先级读取：

1. `pi --api-key at-...` 传入的运行时凭据（不落盘）
2. `CODEX_ACCESS_TOKEN`
3. 文件型 `$CODEX_HOME/auth.json`
4. 未设置 `CODEX_HOME` 时的 `~/.codex/auth.json`

显式提供的凭据不会回退到其它来源：`--api-key` 一旦给出，Account ID 就来自这个 token 自己的
whoami，不会混用环境变量或 `auth.json` 里的账号。

系统 Keyring 不在支持范围内。

## 安装

```powershell
pi install npm:@xicode/pi-codex-pat
```

安装后选择 `openai-codex-pat/<model>`。原生 `openai-codex` OAuth Provider 保持不变，
两种认证方式可以同时存在。

## 凭据

PAT 必须匹配 `at-` 前缀加 URL-safe base64 字符集（可带 `=` 填充）。含空格、换行或其它控制
字符的畸形 token 会被直接拒绝，不会进入 HTTP 请求 —— 这类值会让 HTTP 客户端把整条
`Authorization` header 拼进异常信息。

环境变量必须包含以 `at-` 开头的 PAT：

```powershell
$env:CODEX_ACCESS_TOKEN = "at-..."
pi
```

也可以复用 Codex 文件型认证：

```json
{
  "auth_mode": "personalAccessToken",
  "personal_access_token": "at-..."
}
```

为了兼容 Codex 已有行为，`auth_mode` 可以缺失；如果显式设置为其他认证模式，插件不会
读取残留的 `personal_access_token`。

当 `CODEX_ACCESS_TOKEN` 包含非 PAT 凭据时，环境变量被视为显式认证选择，插件不会继续
回退到 `auth.json`。

## 认证行为

- Provider 可用性检查只读取环境变量和本地文件，不访问网络。
- 首次模型请求通过 OpenAI AuthAPI `whoami` 获取 Account ID 和 FedRAMP 信息。
- 元数据只缓存在当前进程内，不写入磁盘。
- PAT 变化或 Pi reload 后重新解析认证。
- PAT、Authorization header 和完整 `auth.json` 不进入日志和错误信息。

## 兼容性

当前 transport 已验证基线：

```text
@earendil-works/pi-coding-agent 0.84.1
@earendil-works/pi-ai 0.84.1
Pi commit 53fa77ccd8a279eb87e92294ef3687b03ff80112
```

该基线是**下限**，不是精确锁：

- 宿主**低于**基线时插件拒绝注册。打包的 transport 是基线版本的补丁副本，更旧的宿主可能
  缺少它调用的 API，加载期失败比请求中途崩溃更容易定位。
- 宿主**等于**基线时正常工作，不提示。
- 宿主**高于**基线时插件照常注册，并在会话开始时给出一次告警。Provider 契约通常能跨越
  patch 和 minor 更新，因此这里只提示风险而不阻断 —— 否则 Pi 每发一个版本，插件就立刻
  不可用。若升级后请求开始失败，先检查是否有更新的 pi-codex-pat。
- 版本探测失败（例如独立 bun 二进制没有可读的 `package.json`）时同样只告警。

升级 Pi 后如果 transport 行为异常，应重新完成协议测试并更新基线。

## 开发

插件的认证和 Provider 代码位于 `src/`。Codex transport 从 `vendor/pi` 的固定提交复制到
构建临时目录，应用 `patches/openai-codex-pat.patch` 后打包：

```powershell
pnpm build
pnpm typecheck
pnpm test
```

构建时同时编入匹配版本的 Codex 模型目录和轻量 lazy-stream helper。运行时不导入宿主
Pi AI 大入口；transport 延迟到首次模型请求才加载，不增加启动阶段的协议模块解析。