@minniexcode/codex-switch 0.1.0 → 0.1.2

package/docs/Design/codex-switch-v0.1.0-design.md

@@ -1,152 +1,32 @@
-# codex-switch `0.1.0` Design
-
-## 文档信息
-
-- 文档类型：实现约束设计文档
-- 适用版本：`0.1.0`
-- 当前定位：release-hardening only
-- 关联 PRD：[`../PRD/codex-switch-prd-v0.1.0.md`](../PRD/codex-switch-prd-v0.1.0.md)
-- 关联 beta 设计：[`./codex-switch-v0.0.12-design.md`](./codex-switch-v0.0.12-design.md)
-
-## 1. 设计原则
-
-`0.1.0` 的实现只做 release-hardening，不新增命令面，不改 JSON envelope，不引入兼容层，也不把历史草案继续扩成平台设想。
-
-这个版本的实现目标是收口，不是扩张：
-
-- 把用户看见的主路径讲清楚。
-- 把 `list`、`status`、`doctor` 的可读语义讲清楚。
-- 把 `migrate` 和 `setup` 的产品定位讲清楚。
-- 把文档、help、输出、测试和包内容收口成同一套事实。
-
-## 2. 当前阻塞项
-
-实现收口前必须先正视以下阻塞项：
-
-1. `tests/` 仍被忽略，导致回归测试无法稳定版本化。
-2. README 仍引用不存在的 `docs/Tests/testing.md`，说明文档入口还未收口。
-3. 版本叙事仍以 `0.0.12` 为中心，`0.1.0` 还没有被写成稳定发布线。
-4. 主工作流、`migrate` 定位、`setup` 定位和真实实现状态还没有完全对齐。
-
-只要这些阻塞项还存在，就不应把当前实现视为 `0.1.0` ready。
-
-## 3. 收口矩阵
-
-以下子系统必须完成对应收口。
-
-| 子系统 | 必须稳定的内容 | 约束 |
-| --- | --- | --- |
-| 文档 | PRD、design、README、CLI usage、product overview、changelog、testing guide | 所有面向用户的文档必须与 `0.1.0` 事实一致 |
-| 帮助 | 顶层 help、命令 help、示例顺序 | direct/Copilot 主路径优先，`migrate` 降级，`setup` 仅保留 deprecated 语义 |
-| 输出 | `init`、`list`、`status`、`doctor`、`login` 的 human-readable 文案 | 只收口语义，不改 JSON envelope |
-| 读路径 | tool home / runtime separation、dual-path model、ambiguous active profile 处理 | 不新增兼容层，不伪造 current 状态 |
-| 测试 | release gate、回归测试、fixture 检查 | 回归测试必须落仓库，不能继续停留在忽略状态 |
-
-## 4. 必须稳定的用户可见语义
-
-### 4.1 `list`
-
-`list` 必须能让用户直接看出：
-
-- provider 属于 `direct` 还是 `copilot`
-- 哪个 provider 是 current
-- 当前 active profile 是否可唯一解析
-
-如果当前 active profile 对应多个 provider，就必须显式表现为 ambiguous，而不是把任何一个 provider 假装成 current。
-
-`list --json` 仍然使用既有 envelope，只允许追加字段，不允许改顶层契约。
-
-### 4.2 `status`
-
-`status` 必须把以下内容讲清楚：
-
-- tool home 是什么
-- target runtime 是什么
-- 当前 active provider 是什么
-- 当前路径是 direct 还是 Copilot
-- 下一步应该做什么
-
-`status` 是摘要，不是字段堆叠。输出顺序必须围绕“当前状态 -> 影响 -> 下一步”组织。
-
-### 4.3 `doctor`
-
-`doctor` 必须先给整体健康结论，再列 issue，再给修复建议。
-
-每条 issue 至少要表达：
-
-- 问题是什么
-- 为什么重要
-- 下一步怎么修
-
-`doctor` 的目标不是罗列内部数据结构，而是把用户推到下一步修复动作。
-
-### 4.4 provider picker
-
-list 和 provider picker 必须一致处理 ambiguous active profile。
-
-选择器提示至少要包含：
-
-- `profile`
-- `providerType`
-- `current` 标记，仅在唯一解析时出现
-
-### 4.5 命令定位
-
-`0.1.0` 还必须稳定以下产品定位：
-
-- 稳定命令面以 `init`、`login`、`list`、`show`、`current`、`status`、`doctor`、`config`、`add`、`edit`、`switch`、`remove`、`import`、`export`、`bridge`、`backups`、`rollback` 为准。
-- `migrate` 只能被表述为高级 adopt helper。
-- `setup` 只能被表述为 deprecated entry。
-- `--json` 顶层 envelope 继续固定为 `ok / command / data / warnings / error`。
-
-## 5. 文档同步要求
-
-以下面向用户的文档必须与 `0.1.0` 事实一致：
-
-- `README.md`
-- `README.CN.md`
-- `README.AI.md`
-- `docs/cli-usage.md`
-- `docs/codex-switch-product-overview.md`
-- `docs/PRD/codex-switch-prd-v0.1.0.md`
-- `docs/Design/codex-switch-v0.1.0-design.md`
-- `CHANGELOG.md`
-- `docs/Tests/testing.md`
-
-历史大文档不需要在本版全文重写，但必须明确它们只是历史参考，不是当前 release contract。
-
-## 6. 最小测试计划
-
-`0.1.0` 的最小测试计划必须包含以下内容：
-
-1. `npm run build`
-2. `npm test`
-3. `npx tsc --noEmit`
-4. `npm pack --dry-run`
-5. built CLI `--help`
-6. built CLI `--version`
-7. fresh direct provider flow
-8. fresh Copilot provider flow
-9. `list/status/doctor` 输出语义检查
-10. `migrate` 高级 adopt helper 检查
-11. `setup` deprecated entry 检查
-
-测试结论必须落在仓库中的正式测试内容里，不能继续依赖忽略目录或口头约定。
-
-## 7. 明确不做
-
-本版不做以下事情：
-
-- 新 upstream
-- GUI / TUI
-- daemon
-- plugin system
-- auto migration
-- 兼容层
-- dual-read / dual-write
-- 重新设计公开 JSON envelope
-- 重新扩张命令面
-
-## 8. 结论
-
-`0.1.0` 设计的核心不是“再造一个版本叙事”，而是把已存在的实现收口成稳定合同。实现只要偏离这条线，就不应被视为 `0.1.0` 的合理内容。
+# codex-switch v0.1.0 Design
+
+## Purpose
+
+`0.1.0` freezes the stable CLI shape and documents the current architecture instead of introducing a new runtime model.
+
+## Architecture
+
+- `src/commands/` parses and dispatches public commands.
+- `src/app/` owns use cases such as add, switch, status, doctor, bridge, and rollback.
+- `src/domain/` owns provider, config, setup, and error contracts.
+- `src/storage/` owns filesystem persistence for tool home and target Codex state.
+- `src/runtime/` owns Codex CLI and optional Copilot runtime integrations.
+
+## State Separation
+
+The tool home stores managed state and backups. The target Codex home receives runtime projections. This keeps provider registry edits transactional and makes rollback meaningful without claiming ownership of unrelated Codex files.
+
+## Projection
+
+Switching a provider projects:
+
+- top-level `model`
+- top-level `model_provider`
+- `[model_providers.<id>]`
+- `auth.json` with `OPENAI_API_KEY`
+
+Direct providers project the provider API key. Copilot providers project only the local bridge bearer secret; upstream GitHub/Copilot auth remains in the official runtime.
+
+## Error Model
+
+Command errors use stable CLI error codes and optional `details`. Command-specific errors may remain close to the command implementation when that keeps the public contract clearer than forcing every case into a shared diagnostic taxonomy.

package/docs/Design/codex-switch-v0.1.1-design.md

@@ -0,0 +1,22 @@
+# codex-switch v0.1.1 Design
+
+## Purpose
+
+`0.1.1` is a documentation alignment release. The design work is to make the active docs tree match the stable implementation and remove obsolete development-version transition docs from the current fact surface.
+
+## Documentation Structure
+
+- `README.md`, `README.CN.md`, and `README.AI.md` describe the user-facing product.
+- `docs/cli-usage.md` is the command reference.
+- `docs/codex-switch-product-overview.md` is the product-level summary.
+- `docs/codex-switch-technical-architecture.md` is the implementation map.
+- `docs/PRD/` contains active version fact sources for `0.1.0`, `0.1.1`, and planned `0.1.2`.
+- `docs/Design/` contains matching design fact sources.
+- `docs/Reference/` keeps Codex configuration references.
+- `docs/Tests/testing.md` keeps the current verification contract.
+
+## Rules
+
+- Public links should not point to removed `0.0.x` development documents.
+- The active documentation set should describe current behavior, not historical migration intent.
+- Copilot documentation should explicitly mark the bridge as local, bearer-protected, and backed by official GitHub Copilot runtime state.

package/docs/Design/codex-switch-v0.1.2-design.md

@@ -0,0 +1,65 @@
+# codex-switch v0.1.2 Design
+
+## Purpose
+
+`0.1.2` repairs the Copilot runtime integration while keeping direct-provider support unchanged.
+
+## SDK Runtime
+
+- The managed installer installs `@github/copilot-sdk@1.0.2`.
+- `loadCopilotSdk()` resolves `@github/copilot-sdk` from the managed runtime package using `createRequire()`.
+- Copilot-specific paths call a Node gate before mutation or bridge startup. Node.js `<20` fails with `COPILOT_RUNTIME_NODE_UNSUPPORTED`.
+- `probeCopilotSdkRuntime()` classifies missing installs, unsupported versions, and prerelease installs before runtime use.
+- SDK API-shape validation happens later when creating the client or session.
+
+## SDK API Contract
+
+The supported runtime/session shape is:
+
+- `CopilotClient`
+- `CopilotClient.getAuthStatus()`
+- `CopilotClient.createSession()`
+- `CopilotSession.sendAndWait()` when present, otherwise `CopilotSession.send()`
+- `CopilotSession.abort()`
+- `CopilotSession.disconnect()` only as best-effort cleanup
+- SDK `approveAll` or compatible permission handler
+
+Auth readiness uses `getAuthStatus()` and does not create a session just to test login state. `abort()` is a required compatibility surface; `disconnect()` is not a required compatibility gate.
+
+## Bridge Worker
+
+The parent process passes both runtime state and SDK runtime directories into the worker. The worker creates one long-lived `CopilotClient`, starts it once, and serializes incoming requests through a promise queue. Each request gets its own session, uses `abort()` for timeout and cancellation control, and attempts `disconnect()` after completion as best-effort cleanup.
+
+## Request Mapping
+
+The bridge remains a minimal OpenAI-compatible adapter:
+
+- `/v1/chat/completions` maps messages to a text prompt.
+- `/v1/responses` accepts string input, message arrays, or typed top-level content-item arrays and maps those text-oriented shapes to the same prompt path.
+- `model` is passed to `createSession({ model })`.
+- Mixed top-level arrays are rejected as unsupported input.
+- `sendAndWait()` receives `{ prompt }` and the request timeout when available; otherwise the bridge falls back to `send()`.
+
+Non-text Responses content is represented as readable placeholders. Complex tool-call round trips are outside the `0.1.2` guarantee.
+
+## Streaming
+
+Streaming Responses requests emit `response.created`, `response.in_progress`, output item/content part setup events, text deltas, done events, and `response.completed`. The bridge writes initial SSE bytes before the upstream response completes and emits comment heartbeats every 15 seconds while waiting.
+
+## Error Mapping
+
+- Unsupported request shapes return `400`.
+- Auth-required failures return `401`.
+- Upstream timeouts return `504`.
+- Other bridge runtime failures return `500`.
+
+## Config Projection
+
+Copilot provider projection includes:
+
+```toml
+wire_api = "responses"
+stream_idle_timeout_ms = 300000
+```
+
+Direct provider projection does not add `stream_idle_timeout_ms`.

package/docs/PRD/codex-switch-prd-v0.1.0.md

@@ -1,217 +1,65 @@
-# codex-switch `0.1.0` Release Gate PRD
-
-## 文档信息
-
-- 状态：Release Gate
-- 产品名：`codex-switch`
-- CLI 命令名：`codexs`
-- 当前稳定基线：`0.0.12`
-- 目标版本：`0.1.0`
-- 文档定位：定义 `codex-switch` 第一次稳定发布前必须满足的门槛
-- 关联 beta PRD：[`./codex-switch-prd-v0.0.12.md`](./codex-switch-prd-v0.0.12.md)
-- 关联实现约束设计：[`../Design/codex-switch-v0.1.0-design.md`](../Design/codex-switch-v0.1.0-design.md)
-- 关联长期演进稿：[`./codex-switch-prd-v0.0.5-to-v0.1.0.md`](./codex-switch-prd-v0.0.5-to-v0.1.0.md)
-
-## 1. 定位
-
-`0.1.0` 是 `codex-switch` 的第一条稳定发布线，不是继续扩 feature surface 的版本，也不是把 `0.0.12` 再包装一次。
-
-这个版本的判断标准只有一个：当前仓库已经足够稳定，能把命令面、输出契约、主工作流、诊断语义和文档事实对外固定下来，并且不需要再依赖开发期解释来“补全理解”。
-
-## 2. 当前阻塞项
-
-以下问题仍然阻止 `0.1.0` 成为真正可发布的稳定版本：
-
-1. `tests/` 被忽略，导致测试无法被版本化和审阅。
-2. README 里仍有失效的 `docs/Tests/testing.md` 链接，用户会直接遇到死链。
-3. 版本叙事仍停留在 `0.0.12`，对外材料没有把 `0.1.0` 讲成稳定发布线。
-4. 发布故事和实现状态还没有完全对齐，尤其是主工作流、`migrate` 定位和 `setup` 定位。
-
-这些阻塞项必须先被收口，`0.1.0` 才能成立。
-
-## 3. `0.1.0` 的稳定合同
-
-`0.1.0` 必须把以下内容视为稳定合同，不再当作可随意重写的草案。
-
-### 3.1 命令面
-
-稳定命令面包括：
-
-- `init`
-- `login`
-- `list`
-- `show`
-- `current`
-- `status`
-- `doctor`
-- `config show`
-- `config list-profiles`
-- `add`
-- `edit`
-- `switch`
-- `remove`
-- `import`
-- `export`
-- `bridge start`
-- `bridge status`
-- `bridge stop`
-- `backups list`
-- `rollback`
-
-其中：
-
-- `migrate` 只能是高级 adopt helper。
-- `setup` 只能是 deprecated entry。
-
-### 3.2 `--json` envelope
-
-`--json` 的顶层 envelope 必须保持不变：
-
-```json
-{
-  "ok": true,
-  "command": "list",
-  "data": {},
-  "warnings": [],
-  "error": null
-}
-```
-
-约束如下：
-
-- 顶层字段名不变。
-- 顶层字段顺序和 shape 不变。
-- 新信息只能继续追加到 `data`、`warnings` 或 `error.details`。
-
-### 3.3 dual-path model
-
-`0.1.0` 必须把以下分层固定为正式合同：
-
-- tool home：
-  - `codex-switch.json`
-  - `providers.json`
-  - `backups/`
-  - `runtime/`
-  - `runtimes/`
-- target Codex runtime：
-  - `config.toml`
-  - `auth.json`
-
-含义必须稳定：
-
-- `providers.json` 是管理态 SSOT。
-- `config.toml` 是受管 runtime routing 文件。
-- `auth.json` 是受管 auth projection 文件。
-
-### 3.4 主工作流
-
-Direct provider 主路径：
-
-```bash
-codexs init
-codexs add <provider> --profile <name> --api-key <key>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Copilot provider 主路径：
-
-```bash
-codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <name>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-`migrate` 的定位必须明确为：
-
-- 面向已有 runtime state 的高级 adopt helper。
-- 不应与 fresh install 主路径混淆。
-- 不应被写成所有新用户都应先执行的默认步骤。
-
-## 4. Release Gate
-
-只有以下条件全部满足，才允许发布 `0.1.0`。
-
-### 4.1 工作流
-
-- fresh tool home 下 direct provider 主路径可稳定走通。
-- fresh tool home 下 Copilot 主路径可稳定走通。
-- `switch` 的成功语义仍然等于 config 和 auth projection 都正确。
-- `rollback` 对受管写操作仍然可信。
-
-### 4.2 输出与语义
-
-- `--json` 读命令输出稳定。
-- 非交互模式不会意外触发 prompt。
-- 错误码和 issue code 对常见失败场景足够稳定。
-- `status` 与 `doctor` 能清楚说明下一步修复动作。
-- `list`、`status`、`doctor` 的人类可读输出和交互提示一致。
-
-### 4.3 文档
-
-- README、README.CN、README.AI、CLI usage、product overview、PRD、design 和 changelog 与实际行为一致。
-- `docs/Tests/testing.md` 不能继续停留在忽略状态，测试回归必须落仓库并可版本化。
-- 主路径在所有面向用户的文档中必须一致。
-- `0.1.0` 的定位必须压过旧的 `0.0.12` 叙事。
-
-### 4.4 包内容
-
-- `npm pack --dry-run` 结果合理。
-- tarball 中包含正确的 README、LICENSE、docs、dist。
-- `codexs --help`、`codexs --version`、安装指引与 npm 包元数据一致。
-
-### 4.5 结构
-
-- 不再保留明显误导性的历史目录语义。
-- 稳定模块的边界说明足够清楚。
-- 新问题不再需要反复回到超大入口文件修补。
-
-## 5. 可执行验证清单
-
-`0.1.0` 的发布前验证必须至少覆盖以下项目：
-
-```bash
-npm run build
-npm test
-npx tsc --noEmit
-npm pack --dry-run
-node dist/cli.js --help
-node dist/cli.js --version
-```
-
-同时必须做以下行为验证：
-
-- fresh direct provider flow。
-- fresh Copilot provider flow。
-- `list/status/doctor` 语义检查。
-- `--json` 输出检查。
-- `migrate` 作为高级 adopt helper 的检查。
-- `setup` 作为 deprecated entry 的检查。
-
-## 6. 明确不在范围内
-
-`0.1.0` 不要求完成以下内容：
-
-- 新 upstream。
-- GUI / TUI。
-- daemon。
-- plugin system。
-- auto migration。
-- 兼容层。
-- dual-read / dual-write。
-- `migrate` 的完整非交互产品化。
-- 旧状态的自动升级保留逻辑。
-
-## 7. 若 Gate 未通过
-
-如果任何阻塞项仍然存在，就不要强行发布 `0.1.0`。
-
-此时应继续发布 beta 或 rc 版本，而不是为了版本号好看提前进入稳定线。
-
-## 8. 结论
-
-`0.1.0` 的本质不是“功能更多”，而是“承诺更稳”。当命令面、输出契约、主工作流、诊断语义、包内容和文档事实完全一致时，这个版本号才成立。
+# codex-switch v0.1.0 PRD
+
+## Status
+
+- Version line: `0.1.0`
+- Role: first stable documentation baseline
+- Scope: summarize the stable public contract already reached by the CLI
+
+## Product Contract
+
+`codex-switch` is a local-first CLI named `codexs` for managing Codex model-provider routes. It keeps tool-owned provider state separate from the target Codex runtime while projecting the selected provider into Codex-compatible `config.toml` and `auth.json` files.
+
+Stable user workflows:
+
+```bash
+codexs init
+codexs add <provider> --profile <model-provider-id> --api-key <key> --base-url <url> --model <model>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+```bash
+codexs init
+codexs login copilot
+codexs add <provider> --copilot --profile <model-provider-id> --model <model>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+## Stable Boundaries
+
+- Tool home owns `codex-switch.json`, `providers.json`, `backups/`, `runtime/`, and `runtimes/`.
+- Target Codex home owns the active `config.toml` and `auth.json` projection.
+- `providers.json` is the provider registry source of truth.
+- `config.toml` uses top-level `model` / `model_provider` plus `[model_providers.*]` sections.
+- `auth.json` receives the active Codex-facing bearer value as `OPENAI_API_KEY`.
+- Copilot upstream GitHub credentials are not stored in `providers.json` or target `auth.json`.
+
+## Stable Commands
+
+Stable command families include `init`, `login copilot`, `add`, `edit`, `switch`, `remove`, `list`, `show`, `current`, `status`, `doctor`, `config show`, `config list-profiles`, `import`, `export`, `bridge start`, `bridge status`, `bridge stop`, `backups list`, and `rollback`.
+
+`migrate` remains an advanced adopt helper for existing Codex state. `setup` is a deprecated compatibility entry that points users to `init` and `migrate`.
+
+## Output Contract
+
+JSON output keeps the top-level envelope:
+
+```json
+{
+  "ok": true,
+  "command": "status",
+  "data": {},
+  "warnings": [],
+  "error": null
+}
+```
+
+New information should be added under `data`, `warnings`, or `error.details` without changing the envelope.
+
+## Non-Goals
+
+`0.1.0` does not introduce automatic migration shims, a daemon, GUI/TUI, plugin system, new upstream families, or backward-compatibility dual-read paths for old development state.

package/docs/PRD/codex-switch-prd-v0.1.1.md

@@ -0,0 +1,26 @@
+# codex-switch v0.1.1 PRD
+
+## Status
+
+- Version line: `0.1.1`
+- Role: documentation and fact-source completion release
+- Current package version: `0.1.1`
+
+## Goal
+
+`0.1.1` closes documentation gaps after the first stable line. It does not change the primary command surface. Its purpose is to make README, CLI usage, product overview, technical architecture, PRD, design, and changelog agree on the same current facts.
+
+## Requirements
+
+- Keep `0.1.0` as the stable product contract summary.
+- Add explicit `0.1.1` PRD and design fact sources so links from overview and architecture resolve.
+- Remove obsolete `0.0.x` transition docs from the active docs tree.
+- Keep Copilot described as a managed local bridge backed by the official GitHub Copilot runtime.
+- Clarify that direct providers remain the stable, generic path and that Copilot has additional runtime prerequisites.
+- Keep the development-version policy: no automatic migration or backward-compatibility shims unless a later task explicitly asks for them.
+
+## Acceptance
+
+- Public docs link only to current `0.1.0`, `0.1.1`, or planned `0.1.2` fact sources.
+- No public page points to removed `0.0.x` transition documents.
+- `npm test` and `npx tsc --noEmit` continue to pass.

package/docs/PRD/codex-switch-prd-v0.1.2.md

@@ -0,0 +1,41 @@
+# codex-switch v0.1.2 PRD
+
+## Status
+
+- Version line: `0.1.2`
+- Status: release candidate
+- Current repository package version: `0.1.2`
+- Role: next Copilot runtime repair line
+- Scope: make the experimental Copilot bridge diagnosable and usable for simple text-oriented turns against the currently verified Codex runtime boundary, with `0.140.x` treated as a planning and verification target rather than a blanket compatibility guarantee
+
+## Problem
+
+The existing Copilot path treated `@github/copilot-sdk` as a simple chat/session SDK. The package is an official JSON-RPC control surface for GitHub Copilot CLI and has a stricter runtime contract than the previous integration assumed. It also requires Node.js `>=20`, while direct providers should continue to support Node.js `>=18`.
+
+## Requirements
+
+- Default the managed installer to `@github/copilot-sdk@1.0.2` instead of `latest`.
+- Keep package-level `engines.node >=18`, but fail Copilot-only paths early under Node.js `<20` with `COPILOT_RUNTIME_NODE_UNSUPPORTED`.
+- Load the SDK from the managed runtime install directory using `createRequire()`.
+- Probe auth through `CopilotClient.getAuthStatus()` rather than by creating a session.
+- Treat unsupported SDK versions and prerelease installs as explicit runtime failures before bridge use, with API-shape validation reported separately as `COPILOT_SDK_API_UNSUPPORTED` when the client or session is actually used.
+- Start the bridge worker with the same `runtimesDir` that passed parent readiness checks.
+- Keep one long-lived `CopilotClient` in the worker, create one session per request, require `abort()`, and attempt `disconnect()` as best-effort cleanup after the request.
+- Serialize bridge requests to avoid session event interleaving.
+- Normalize `/v1/chat/completions` and `/v1/responses` text-oriented turns to SDK `prompt` messages and pass the model through `createSession({ model })`.
+- Stream Responses API events before upstream completion and emit heartbeat comments while waiting.
+- Return explicit bridge errors for unsupported requests, auth-required failures, SDK/runtime failures, and upstream timeouts.
+- Project Copilot model providers with `wire_api = "responses"` and `stream_idle_timeout_ms = 300000`.
+
+## Non-Goals
+
+`0.1.2` does not claim the Copilot bridge is a complete OpenAI Responses API backend. Complex tool-call round trips remain experimental unless verified separately.
+
+## Acceptance
+
+- `/v1/responses` request normalization accepts string input, message arrays, or typed top-level content-item arrays; mixed arrays are rejected; non-text items become readable placeholders.
+- Unsupported requests map to `400`, auth-required failures map to `401`, upstream timeouts map to `504`, and other bridge runtime failures map to `500`.
+- Streaming Responses requests emit the expected event shape, including initial lifecycle events before upstream completion, text deltas, and final completion events.
+- Copilot config projection writes `wire_api = "responses"` and `stream_idle_timeout_ms = 300000`.
+- Simple non-stream and stream bridge requests work against the fake SDK contract.
+- Node `<20` Copilot commands fail before mutating provider or Codex state.