@minniexcode/codex-switch 0.1.0 → 0.1.2

package/docs/Reference/codex-config-reference.md

@@ -137,6 +137,12 @@ model_reasoning_effort = "high"
 approval_policy = "never"
 ```
 
+Important `codex-switch` note:
+
+- official Codex still supports profiles
+- `codex-switch` `0.1.1` does not treat top-level `profile` as the recommended managed runtime selector
+- in `codex-switch`, legacy `profile` and `[profiles.*]` are mainly inspect-and-adopt inputs for `migrate`, `doctor`, and `config` inspection flows
+
 ## 4. `config.toml` by topic
 
 ### 4.1 Model, reasoning, and response style
@@ -194,6 +200,8 @@ Core keys:
 - `model_providers.<id>.env_http_headers`
 - `model_providers.<id>.query_params`
 - `model_providers.<id>.request_max_retries`
+- `model_providers.<id>.wire_api`
+- `model_providers.<id>.requires_openai_auth`
 
 Authentication options for custom providers include:
 
@@ -214,6 +222,22 @@ Related Bedrock keys:
 - `model_providers.amazon-bedrock.aws.profile`
 - `model_providers.amazon-bedrock.aws.region`
 
+#### `codex-switch` 0.1.1 managed projection
+
+When `codex-switch` manages a direct OpenAI-compatible route for Codex `0.134.0+`, it intentionally projects a narrower runtime shape than the full official provider schema:
+
+- top-level `model` is the active model selector
+- top-level `model_provider` is the active route selector
+- projected `[model_providers.<id>]` keeps `base_url`
+- projected `[model_providers.<id>]` fixes `wire_api = "responses"`
+- projected `[model_providers.<id>]` fixes `requires_openai_auth = true`
+- projected runtime config does not keep `env_key`
+- projected runtime config does not keep `env_key_instructions`
+
+Authentication is projected through `auth.json` with `OPENAI_API_KEY`, not through `env_key` in the managed runtime config.
+
+That is a `codex-switch` product decision, not a limitation of Codex itself. If you hand-write or independently manage Codex config, `env_key` remains a valid official mechanism.
+
 ### 4.3.1 `openai_base_url` vs custom providers
 
 If you only want to point the built-in OpenAI provider to a proxy, router, or residency-specific endpoint, use:
@@ -539,6 +563,23 @@ env_key = "OPENAI_API_KEY"
 http_headers = { "X-Team" = "platform" }
 ```
 
+This is an official Codex-style custom provider example.
+
+If you are using `codex-switch` managed direct-provider projection instead, the runtime projection is intentionally narrower:
+
+```toml
+model = "gpt-5.4"
+model_provider = "proxy"
+
+[model_providers.proxy]
+name = "proxy"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+In that managed projection, `OPENAI_API_KEY` is expected in `auth.json` rather than through `env_key` in `config.toml`.
+
 ### 6.4 Locked-down shell environment
 
 ```toml

package/docs/Reference/codex-config-reference.zh-CN.md

@@ -149,6 +149,12 @@ model_reasoning_effort = "high"
 approval_policy = "never"
 ```
 
+对 `codex-switch` 0.1.1 的补充说明：
+
+- 官方 Codex 仍然支持 profiles
+- `codex-switch` 不再把顶层 `profile` 视为推荐的受管 runtime selector
+- 在 `codex-switch` 里，legacy `profile` 和 `[profiles.*]` 主要用于 `migrate`、`doctor` 和 `config` 检视的 adopt / inspect 场景
+
 ## 4. `config.toml` 主题整理
 
 ### 4.1 模型、推理强度与输出风格
@@ -206,6 +212,8 @@ Codex 把“当前使用哪个 provider”和“provider 怎么定义”拆开
 - `model_providers.<id>.env_http_headers`
 - `model_providers.<id>.query_params`
 - `model_providers.<id>.request_max_retries`
+- `model_providers.<id>.wire_api`
+- `model_providers.<id>.requires_openai_auth`
 
 自定义 provider 的认证方式包括：
 
@@ -229,6 +237,22 @@ Bedrock 相关 key：
 - `model_providers.amazon-bedrock.aws.profile`
 - `model_providers.amazon-bedrock.aws.region`
 
+#### `codex-switch` 0.1.1 的受管投影
+
+当 `codex-switch` 为 Codex `0.134.0+` 管理一个 direct OpenAI-compatible route 时，它会有意把运行态投影限制在一组更窄的字段上：
+
+- 顶层 `model` 是活动模型选择器
+- 顶层 `model_provider` 是活动路由选择器
+- 投影后的 `[model_providers.<id>]` 保留 `base_url`
+- 投影后的 `[model_providers.<id>]` 固定写 `wire_api = "responses"`
+- 投影后的 `[model_providers.<id>]` 固定写 `requires_openai_auth = true`
+- 受管运行态投影不会保留 `env_key`
+- 受管运行态投影不会保留 `env_key_instructions`
+
+认证信息会通过 `auth.json` 里的 `OPENAI_API_KEY` 投影，而不是通过运行态 `config.toml` 中的 `env_key`。
+
+这属于 `codex-switch` 的产品约束，不是 Codex 官方能力限制。如果你是手工维护或独立维护 Codex config，`env_key` 仍然是官方支持的方式。
+
 ### 4.3.1 `openai_base_url` 和自定义 provider 的区别
 
 如果你只是想把内置 `openai` provider 指向公司网关、路由层或者某个数据驻留 endpoint，官方建议直接用：
@@ -568,6 +592,23 @@ env_key = "OPENAI_API_KEY"
 http_headers = { "X-Team" = "platform" }
 ```
 
+这段是官方 Codex 风格的自定义 provider 示例。
+
+如果你走的是 `codex-switch` 的受管 direct-provider 投影，运行态会被有意收窄为：
+
+```toml
+model = "gpt-5.4"
+model_provider = "proxy"
+
+[model_providers.proxy]
+name = "proxy"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+在这种受管投影下，`OPENAI_API_KEY` 预期写在 `auth.json`，而不是通过 `config.toml` 里的 `env_key` 暴露。
+
 ### 6.4 最小暴露的 shell 环境策略
 
 ```toml

package/docs/Tests/testing.md

@@ -1,6 +1,6 @@
 # codex-switch Testing Guide
 
-This guide records the release gate for `0.1.0`.
+This guide records the current `0.1.x` verification contract for release and review work.
 
 ## Required checks
 

package/docs/cli-usage.md

@@ -1,223 +1,290 @@
-# codex-switch CLI Usage
-
-This document describes the current CLI contract for `@minniexcode/codex-switch` at version `0.1.0`.
-
-Executable command name:
-
-```bash
-codexs
-```
-
-## 1. Version Context
-
-The current package version in this repository is `0.1.0`.
-
-This is the first stable release line. The command surface already exists, and this version focuses on keeping workflow guidance, help text, and implementation behavior aligned.
-
-## 2. Primary Workflows
-
-### 2.1 Direct Providers
-
-```bash
-codexs init
-codexs add <provider> --profile <name> --api-key <key>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Intent:
-
-- `init` prepares the `codex-switch` tool home.
-- `add` creates a managed provider record.
-- `switch` projects the selected provider into the target Codex runtime.
-- `status` summarizes tool-home, runtime, provider, and health state.
-- `doctor` gives deeper repair-oriented diagnostics.
-
-### 2.2 GitHub Copilot
-
-```bash
-codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <name>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Important notes:
-
-- `login copilot` is the upstream onboarding command.
-- The current implementation prefers the bundled Copilot CLI from the managed runtime and falls back to `PATH` when needed.
-- `login copilot` succeeds only after auth readiness is rechecked.
-- `add --copilot` does not install or log in to Copilot for you.
-
-## 3. Advanced Adopt Workflow
-
-Use `migrate` only when you already have Codex runtime state that should be adopted into managed `providers.json` state.
-
-```bash
-codexs init
-codexs migrate
-```
-
-`migrate` is an advanced adopt helper. It is not the default first step for fresh installs.
-
-Current behavior:
-
-- It reads `config.toml` profiles from the target Codex runtime.
-- It can collect missing provider details in TTY mode.
-- It can merge into or overwrite existing managed provider state.
-- It still fails fast in non-TTY and `--json` runs when interactive input would be required.
-
-## 4. Deprecated Entry
-
-```bash
-codexs setup
-```
-
-`setup` is deprecated. It is kept only to direct callers toward `init` or `migrate`, and it no longer performs initialization or migration work.
-
-## 5. Global Contract
-
-### 5.1 Global Flags
-
-```bash
---json
---codex-dir <path>
---help
---version
-```
-
-### 5.2 Environment Variables
-
-```bash
-CODEXS_HOME
-CODEXS_CODEX_DIR
-```
-
-### 5.3 Runtime Model
-
-Tool home:
-
-```text
-~/.config/codex-switch/
-  codex-switch.json
-  providers.json
-  backups/
-  runtime/
-  runtimes/
-```
-
-Target Codex runtime:
-
-```text
-~/.codex/
-  config.toml
-  auth.json
-```
-
-Meaning:
-
-- `providers.json` is the managed provider registry.
-- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`.
-- `config.toml` remains the active runtime routing file.
-- `auth.json` remains the active auth projection file.
-
-## 6. Command Categories
-
-Read commands:
-
-```bash
-codexs list
-codexs show <provider>
-codexs current
-codexs status
-codexs config show [profile]
-codexs config list-profiles
-codexs bridge status [provider]
-codexs backups list
-codexs doctor
-```
-
-Change commands:
-
-```bash
-codexs init
-codexs login copilot
-codexs migrate
-codexs add <provider>
-codexs edit <provider>
-codexs switch <provider>
-codexs remove <provider>
-codexs import <file>
-codexs export <file>
-codexs bridge start [provider]
-codexs bridge stop [provider]
-codexs rollback [backup-id]
-```
-
-## 7. Selected Command Semantics
-
-### `init`
-
-- Creates `codex-switch.json` and `providers.json` under the tool home when they do not exist yet.
-- Does not create or validate `config.toml`, `auth.json`, or the target Codex directory.
-- When `--codex-dir` is passed explicitly during first-time initialization, it can persist `defaultCodexDir`.
-
-### `login copilot`
-
-- Supports `copilot` and `github-copilot` as the current upstream name.
-- Installs the local Copilot SDK under the tool home when needed.
-- Invokes the official Copilot CLI for login when readiness is not already present.
-- Requires a real TTY and does not support `--json`.
-
-### `status`
-
-- Reports the target Codex runtime and the tool-home root.
-- Reports the current profile and whether it maps to a managed provider.
-- Adds bridge, Copilot SDK, and upstream auth signals when the active provider uses a local runtime bridge.
-- Does not mutate any files.
-
-### `list`
-
-- Lists managed providers together with their linked profile.
-- Distinguishes provider type using the public values `direct` and `copilot`.
-- Marks the current provider only when the active runtime can be mapped back to one unique managed provider.
-- When the active profile is shared by multiple providers, it does not invent a single current provider and should instead surface the ambiguity.
-- TTY provider pickers used by commands such as `switch` and `show` follow the same visibility rules for profile, provider type, and current-state hints.
-
-### `doctor`
-
-- Checks expected config files, provider/profile consistency, and Codex CLI availability.
-- Adds bridge and Copilot dependency diagnostics for Copilot-backed providers.
-- Returns repair-oriented issues intended for both human users and AI agents.
-
-### `switch`
-
-- Direct providers rewrite `auth.json` as an API-key projection and update the active runtime profile.
-- Copilot bridge providers also project the local bridge secret into the runtime while managing bridge routing.
-- Managed writes are backed up and rolled back on failure.
-- When `<provider>` is omitted in a TTY, the interactive provider selector should show profile, provider type, and current-state hints using the same rules as `list`.
-
-### `migrate`
-
-- Adopts unmanaged runtime profiles into managed `providers.json` state.
-- Still relies on interactive profile selection and provider-detail collection in this release.
-- Should be treated as an advanced adopt tool, not as the normal onboarding path.
-
-## 8. Automation Boundaries
-
-- Progressive prompts run only in a real TTY and never under `--json`.
-- Human write commands may prompt for missing inputs or dangerous-action confirmation.
-- Automation should pass explicit arguments and prefer `--json`.
-- `login copilot` is TTY-only.
-- `migrate` is not yet a complete non-interactive workflow.
-
-## 9. Related Docs
-
-- [README](../README.md)
-- [Chinese README](../README.CN.md)
-- [AI README](../README.AI.md)
-- [Product Overview](./codex-switch-product-overview.md)
-- [Release PRD 0.1.0](./PRD/codex-switch-prd-v0.1.0.md)
+# codex-switch CLI Usage
+
+This document describes the current `0.1.2` CLI contract for `@minniexcode/codex-switch`, including the Copilot runtime repair boundary.
+
+Executable command name:
+
+```bash
+codexs
+```
+
+## 1. Version Context
+
+The current package version in this repository is `0.1.2`.
+
+This release line targets Codex `0.134.0+`. The public contract assumes runtime routing is selected by top-level `model` plus `model_provider`, while legacy `profile` and `[profiles.*]` remain inspect-and-adopt inputs instead of the recommended runtime path.
+
+## 2. Primary Workflows
+
+### 2.1 Direct Providers
+
+```bash
+codexs init
+codexs add <provider> --model <model> --api-key <key> [--base-url <url>]
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+Intent:
+
+- `init` prepares the `codex-switch` tool home.
+- `add` creates a managed provider record with a target model and provider route identity.
+- `switch` projects the selected provider into the target Codex runtime.
+- `status` summarizes tool-home, runtime, provider, and health state.
+- `doctor` gives deeper repair-oriented diagnostics.
+
+### 2.2 GitHub Copilot
+
+```bash
+codexs init
+codexs login copilot
+codexs add <provider> --copilot --model <model>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+Important notes:
+
+- `login copilot` is the upstream onboarding command.
+- The current implementation prefers the bundled Copilot CLI from the managed runtime and falls back to `PATH` when needed.
+- `login copilot` succeeds only after auth readiness is rechecked.
+- `add --copilot` does not install or log in to Copilot for you.
+- Copilot runtime paths require Node.js `>=20`; direct providers remain supported on Node.js `>=18`.
+- The Copilot bridge is experimental and targets simple text-oriented turns through the local OpenAI-compatible bridge.
+
+## 3. Runtime Route Contract
+
+For Codex `0.134.0+`, the active runtime route is selected through top-level `model` and `model_provider` in `config.toml`.
+
+`codex-switch` writes that route as its primary runtime projection:
+
+- top-level `model`
+- top-level `model_provider`
+- `[model_providers.<id>]`
+- `auth.json` when direct auth projection is required
+
+Managed provider projection intentionally avoids these legacy fields:
+
+- `model_providers.<id>.env_key`
+- `model_providers.<id>.env_key_instructions`
+
+Managed provider projection fixes these fields for OpenAI-compatible direct routes:
+
+- `wire_api = "responses"`
+- `requires_openai_auth = true`
+
+Copilot bridge projection also writes:
+
+- `stream_idle_timeout_ms = 300000`
+
+Compatibility notes:
+
+- `--profile` is accepted as an alias for the managed `model_provider` id.
+- legacy top-level `profile` and `[profiles.*]` may still appear in existing runtime state
+- `migrate`, `config show`, `config list-profiles`, and `doctor` can still inspect those legacy structures
+- new managed runtime projection should be described as route-first, not profile-first
+
+Example managed direct-provider projection:
+
+```toml
+model = "gpt-5.5"
+model_provider = "proxy"
+
+[model_providers.proxy]
+name = "proxy"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+Authentication projection for the direct path remains:
+
+```json
+{
+  "OPENAI_API_KEY": "sk-xxx"
+}
+```
+
+## 4. Advanced Adopt Workflow
+
+Use `migrate` only when you already have Codex runtime state that should be adopted into managed `providers.json` state.
+
+```bash
+codexs init
+codexs migrate
+```
+
+`migrate` is an advanced adopt helper. It is not the default first step for fresh installs.
+
+Current behavior:
+
+- It can inspect legacy runtime `profile` and `[profiles.*]` state from the target Codex runtime.
+- It can collect missing provider details in TTY mode.
+- It can merge into or overwrite existing managed provider state.
+- It still fails fast in non-TTY and `--json` runs when interactive input would be required.
+
+## 5. Deprecated Entry
+
+```bash
+codexs setup
+```
+
+`setup` is deprecated. It is kept only to direct callers toward `init` or `migrate`, and it no longer performs initialization or migration work.
+
+## 6. Global Contract
+
+### 6.1 Global Flags
+
+```bash
+--json
+--codex-dir <path>
+--help
+--version
+```
+
+### 6.2 Environment Variables
+
+```bash
+CODEXS_HOME
+CODEXS_CODEX_DIR
+```
+
+### 6.3 Runtime Model
+
+Tool home:
+
+```text
+~/.config/codex-switch/
+  codex-switch.json
+  providers.json
+  backups/
+  runtime/
+  runtimes/
+```
+
+Target Codex runtime:
+
+```text
+~/.codex/
+  config.toml
+  auth.json
+```
+
+Meaning:
+
+- `providers.json` is the managed provider registry.
+- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`.
+- `config.toml` remains the active runtime routing file.
+- `auth.json` remains the active auth projection file.
+
+## 7. Command Categories
+
+Read commands:
+
+```bash
+codexs list
+codexs show <provider>
+codexs current
+codexs status
+codexs config show [profile]
+codexs config list-profiles
+codexs bridge status [provider]
+codexs backups list
+codexs doctor
+```
+
+Change commands:
+
+```bash
+codexs init
+codexs login copilot
+codexs migrate
+codexs add <provider>
+codexs edit <provider>
+codexs switch <provider>
+codexs remove <provider>
+codexs import <file>
+codexs export <file>
+codexs bridge start [provider]
+codexs bridge stop [provider]
+codexs rollback [backup-id]
+```
+
+## 8. Selected Command Semantics
+
+### `init`
+
+- Creates `codex-switch.json` and `providers.json` under the tool home when they do not exist yet.
+- Does not create or validate `config.toml`, `auth.json`, or the target Codex directory.
+- When `--codex-dir` is passed explicitly during first-time initialization, it can persist `defaultCodexDir`.
+
+### `login copilot`
+
+- Supports `copilot` and `github-copilot` as the current upstream name.
+- Installs the local Copilot SDK under the tool home when needed.
+- Invokes the official Copilot CLI for login when readiness is not already present.
+- Requires a real TTY and does not support `--json`.
+
+### `status`
+
+- Reports the target Codex runtime and the tool-home root.
+- Reports the active model and active `model_provider` route.
+- Can still surface legacy profile-derived observations when inspecting older runtime state.
+- Adds bridge, Copilot SDK, and upstream auth signals when the active provider uses a local runtime bridge.
+- Does not mutate any files.
+
+### `list`
+
+- Lists managed providers together with their linked route identity.
+- Distinguishes provider type using the public values `direct` and `copilot`.
+- Marks the current provider only when the active runtime can be mapped back to one unique managed provider.
+- When the active route is shared by multiple providers, it does not invent a single current provider and should instead surface the ambiguity.
+- TTY provider pickers used by commands such as `switch` and `show` follow the same visibility rules for route, provider type, and current-state hints.
+
+### `doctor`
+
+- Checks expected config files, managed-provider consistency, and Codex CLI availability.
+- Inspects both route-first runtime state and legacy profile state when needed.
+- Adds bridge and Copilot dependency diagnostics for Copilot-backed providers.
+- Returns repair-oriented issues intended for both human users and AI agents.
+
+### `switch`
+
+- Projects direct providers by rewriting top-level `model`, top-level `model_provider`, the managed `[model_providers.<id>]` block, and `auth.json`.
+- Cleans legacy projected `env_key` and `env_key_instructions` fields before writing the managed provider route.
+- Copilot bridge providers also project the local bridge secret into the runtime while managing bridge routing.
+- Managed writes are backed up and rolled back on failure.
+- When `<provider>` is omitted in a TTY, the interactive provider selector should show route, provider type, and current-state hints using the same rules as `list`.
+
+### `add` and `edit`
+
+- Create or update managed provider records rather than editing runtime files directly.
+- Treat `--profile` only as an alias for the managed `model_provider` id.
+- Clean old `env_key` and `env_key_instructions` fields from managed projection during subsequent switching.
+
+### `migrate`
+
+- Adopts unmanaged runtime route or legacy profile state into managed `providers.json` state.
+- Still relies on interactive route/profile selection and provider-detail collection in this release.
+- Should be treated as an advanced adopt tool, not as the normal onboarding path.
+
+## 9. Automation Boundaries
+
+- Progressive prompts run only in a real TTY and never under `--json`.
+- Human write commands may prompt for missing inputs or dangerous-action confirmation.
+- Automation should pass explicit arguments and prefer `--json`.
+- `login copilot` is TTY-only.
+- `migrate` is not yet a complete non-interactive workflow.
+
+## 10. Related Docs
+
+- [README](../README.md)
+- [Chinese README](../README.CN.md)
+- [AI README](../README.AI.md)
+- [Product Overview](./codex-switch-product-overview.md)
+- [PRD 0.1.0](./PRD/codex-switch-prd-v0.1.0.md)
+- [PRD 0.1.1](./PRD/codex-switch-prd-v0.1.1.md)
+- [PRD 0.1.2](./PRD/codex-switch-prd-v0.1.2.md)
+- [Design 0.1.2](./Design/codex-switch-v0.1.2-design.md)