@minniexcode/codex-switch 0.1.3 → 0.1.5

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

@@ -0,0 +1,18 @@
+# codex-switch v0.1.4 Design
+
+`0.1.4` is a bridge reliability and observability repair release.
+
+## Design Notes
+
+- Bridge reuse probing is refactored into a structured probe helper that distinguishes transient transport failures from deterministic mismatches.
+- Health and auth reuse probes use 2 attempts, a 2500 ms per-request timeout, and a 250 ms delay between attempts.
+- Existing bridge workers are retried before replacement only for transient timeout and transport failures. Deterministic mismatches still replace immediately: different provider, different base URL, stale worker build, or explicit `401`/`403` auth rejection.
+- Bridge worker stdout/stderr are appended to a persisted runtime log file under the managed runtime-state directory, and that log path is surfaced in bridge results and bridge-related errors.
+- Parent-side lifecycle logging records probe attempts, transient failures, replacement reasons, worker start, startup timeout, startup failure, and startup success without logging secrets.
+- Worker-side stderr logging records startup, shutdown, uncaught exception, and unhandled rejection.
+- The shared test runner discovers `tests/*.spec.js` in sorted order, excludes helper files, and supports both suite export styles already present in the repository: `{ run }` and `{ name, tests: [...] }`.
+- Interactive provider selection uses the structured config once and resolves the visible current hint in this order:
+  1. unique managed mapping from top-level `model_provider`
+  2. fallback to legacy top-level `profile` when top-level `model_provider` is missing or unresolved and the legacy value exactly matches one provider name
+  3. ambiguous marker when multiple providers share the active `model_provider`
+  4. no marker otherwise

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

@@ -0,0 +1,17 @@
+# codex-switch v0.1.5 Design
+
+`0.1.5` is a Copilot Bridge process-visibility and redaction patch release.
+
+## Design Notes
+
+- `CopilotBridgeRuntimeEvent` is the stable internal boundary between Copilot SDK session events and the OpenAI-compatible bridge surface.
+- Copilot sessions are created with `streaming: true` and register the generic `session.on("event", handler)` listener alongside the existing `data`, `message`, and `delta` text compatibility listeners.
+- The adapter maps known SDK event names into bridge runtime events for assistant intent, assistant message deltas, assistant reasoning deltas, tool lifecycle, permission lifecycle, user-input requests, exit-plan-mode requests, session idle, and session errors.
+- `assistant.message_delta` is also forwarded as a normal text delta so final response streaming remains compatible with existing Chat Completions and Responses text paths.
+- The bridge worker forwards adapter runtime events through `onRuntimeEvent`, separate from `onTextDelta` and `onTextDone`.
+- Responses streaming projects non-text runtime process events as completed assistant message items with `phase: "commentary"`.
+- Reasoning deltas project as `response.reasoning_summary_part.added` followed by `response.reasoning_summary_text.delta`.
+- Unknown SDK events become `session.unknown`, are omitted from the UI projection path, and are logged with bounded summaries.
+- Unknown summaries redact sensitive key names and obvious token/API-key-like values before truncation.
+- Chat Completions streaming only wires text deltas, so Responses-only commentary events stay out of Chat Completions streams.
+- Internal Copilot tool lifecycle events remain process visibility signals only; they are not emitted as Codex/OpenAI function calls or tool calls.

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

@@ -0,0 +1,37 @@
+# codex-switch v0.1.4 PRD
+
+## Version
+
+- Version line: `0.1.4`
+- Target repository package version: `0.1.4`
+
+## Summary
+
+`0.1.4` is a bridge stability and observability release. It is a narrow reliability bridge between the existing Copilot bridge experiment and a stricter release gate, with no new provider families or migration behavior.
+
+## Required Outcome
+
+- Copilot bridge reuse must survive one transient health or auth probe failure before the existing worker is replaced.
+- Bridge failures must expose actionable evidence, including the persisted runtime log path and the restart reason when an old worker is recycled.
+- `npm test` must become the widened real release gate by discovering and running the broader repository suite set already present under `tests/`.
+- Interactive provider selection must restore the visible `current` hint for legacy state where only the top-level `profile` is present and `model_provider` is absent.
+
+## Release Scope
+
+- Bridge reuse probe hardening for transient transport and timeout failures.
+- Bridge log persistence and surfaced restart metadata across command results and diagnostics.
+- Widened test-runner coverage plus any pre-existing red paths that block the widened suite from becoming the real ship gate.
+- Interactive current-marker repair for legacy top-level `profile` fallback.
+
+## Non-Goals
+
+- No new provider families.
+- No migration or backward-compatibility shims beyond the prompt-only legacy `profile` hint fallback.
+- No command-surface expansion outside the new bridge diagnostics and status fields.
+
+## Release Acceptance
+
+- `switch` no longer flaps on one transient bridge probe failure.
+- Bridge startup or reuse failures surface the log path and the worker replacement reason when applicable.
+- `npm test` executes the widened deterministic suite set and passes.
+- Interactive provider selection correctly marks the current provider from legacy top-level `profile` state when top-level `model_provider` is absent or unresolved.

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

@@ -0,0 +1,42 @@
+# codex-switch v0.1.5 PRD
+
+## Version
+
+- Version line: `0.1.5`
+- Target repository package version: `0.1.5`
+
+## Summary
+
+`0.1.5` is a Copilot Bridge process-visibility and redaction patch release. It surfaces assistant progress, reasoning summaries, tool lifecycle, permission, user-input, and exit-plan-mode signals through the existing bridge stream while keeping the provider command surface unchanged.
+
+## Required Outcome
+
+- Copilot SDK streaming sessions must subscribe to the generic session event channel and preserve existing text-delta compatibility listeners.
+- Known SDK process events must map into a stable bridge runtime-event contract instead of leaking SDK-specific shapes.
+- Responses streaming must surface process/status updates as commentary items and reasoning/progress updates as reasoning summary events.
+- Chat Completions streaming must continue to receive text only and must not receive Responses-only commentary events.
+- Unknown SDK events must be ignored by the UI projection path while logging bounded, redacted summaries for diagnostics.
+- Adapter-level tests must cover raw SDK session event normalization, not only bridge-server projection of already-normalized events.
+
+## Release Scope
+
+- Copilot adapter runtime event contract and SDK event normalization.
+- Bridge worker forwarding of adapter runtime events into request handlers.
+- Responses streaming projection for commentary and reasoning summary events.
+- Unknown-event truncation and redaction hardening.
+- Focused regression coverage for raw SDK event mapping and bridge stream projection.
+
+## Non-Goals
+
+- No new provider families.
+- No migration or backward-compatibility shims.
+- No expansion of direct-provider workflows.
+- No conversion of internal Copilot tool lifecycle events into Codex/OpenAI function-call or tool-call payloads.
+
+## Release Acceptance
+
+- `npm test` passes with adapter-level raw event normalization coverage.
+- Responses streaming includes commentary and reasoning summary process events.
+- Final assistant text still streams normally.
+- Unknown events are redacted, truncated, logged for diagnostics, and ignored by the UI projection path.
+- Chat Completions streaming does not emit Responses-only commentary events.

package/docs/Tests/testing.md

@@ -1,6 +1,8 @@
 # codex-switch Testing Guide
 
 This guide records the current `0.1.x` verification contract for release and review work.
+
+The current repository line is `0.1.5` and remains an unreleased development line until an explicit release task says otherwise.
 
 ## Required checks
 
@@ -22,7 +24,8 @@ node dist/cli.js --version
 - Ambiguous active profile: `list`, `status`, and provider pickers must surface ambiguity instead of inventing a unique current provider
 - `--json` envelope: top-level `ok`, `command`, `data`, `warnings`, and `error` must remain stable
 - `migrate`: advanced adopt helper only
-- `setup`: deprecated entry only
+- `setup`: deprecated entry only
+- Release hygiene: `package.json`, `package-lock.json`, current-line docs, changelog top entry, and current PRD/Design fact sources must agree on the `0.1.5` development line
 
 ## Fixture guidance
 

package/docs/cli-usage.md

@@ -1,6 +1,6 @@
 # codex-switch CLI Usage
 
-This document describes the current `0.1.3` CLI contract for `@minniexcode/codex-switch`, including the Copilot login hotfix boundary.
+This document describes the current `0.1.5` repository development-line CLI contract for `@minniexcode/codex-switch`, including the Copilot Bridge process-visibility boundary.
 
 Executable command name:
 
@@ -10,9 +10,9 @@ codexs
 
 ## 1. Version Context
 
-The current package version in this repository is `0.1.3`.
+The current package version in this repository is `0.1.5`.
 
-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.
+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. The current `0.1.5` development line adds Copilot Bridge process visibility, defensive SDK-event normalization, and unknown-event redaction hardening without expanding the provider command surface.
 
 ## 2. Primary Workflows
 
@@ -20,7 +20,7 @@ This release line targets Codex `0.134.0+`. The public contract assumes runtime
 
 ```bash
 codexs init
-codexs add <provider> --model <model> --api-key <key> [--base-url <url>]
+codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> [--base-url <url>]
 codexs switch <provider>
 codexs status
 codexs doctor
@@ -30,6 +30,7 @@ Intent:
 
 - `init` prepares the `codex-switch` tool home.
 - `add` creates a managed provider record with a target model and provider route identity.
+- Non-interactive runs should pass `--profile` explicitly; TTY mode can prompt for missing required fields.
 - `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.
@@ -39,7 +40,7 @@ Intent:
 ```bash
 codexs init
 codexs login copilot
-codexs add <provider> --copilot --model <model>
+codexs add <provider> --copilot --profile <model-provider-id> --model <model>
 codexs switch <provider>
 codexs status
 codexs doctor
@@ -51,6 +52,7 @@ Important notes:
 - 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.
+- Non-interactive Copilot adds should also pass `--profile` explicitly; TTY mode can still collect missing required fields.
 - 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.
 
@@ -82,6 +84,7 @@ Copilot bridge projection also writes:
 Compatibility notes:
 
 - `--profile` is accepted as an alias for the managed `model_provider` id.
+- automation should still pass `--profile` explicitly instead of relying on prompts
 - 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
@@ -262,6 +265,7 @@ codexs rollback [backup-id]
 
 - Create or update managed provider records rather than editing runtime files directly.
 - Treat `--profile` only as an alias for the managed `model_provider` id.
+- Require explicit `--profile` in non-interactive usage; allow TTY prompts to fill it when omitted.
 - Clean old `env_key` and `env_key_instructions` fields from managed projection during subsequent switching.
 
 ### `migrate`
@@ -288,5 +292,7 @@ codexs rollback [backup-id]
 - [PRD 0.1.1](./PRD/codex-switch-prd-v0.1.1.md)
 - [PRD 0.1.2](./PRD/codex-switch-prd-v0.1.2.md)
 - [PRD 0.1.3](./PRD/codex-switch-prd-v0.1.3.md)
+- [PRD 0.1.5](./PRD/codex-switch-prd-v0.1.5.md)
 - [Design 0.1.2](./Design/codex-switch-v0.1.2-design.md)
 - [Design 0.1.3](./Design/codex-switch-v0.1.3-design.md)
+- [Design 0.1.5](./Design/codex-switch-v0.1.5-design.md)

package/docs/codex-switch-product-overview.md

@@ -4,17 +4,21 @@
 
 这份文档介绍当前活跃产品事实源下的 `codex-switch` 产品定位。
 
-当前稳定 release contract 以这些文档为准：
-
-- [`cli-usage.md`](./cli-usage.md)
-- [`PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)
-- [`PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)
-- [`PRD/codex-switch-prd-v0.1.2.md`](./PRD/codex-switch-prd-v0.1.2.md)（规划中）
-- [`Design/codex-switch-v0.1.2-design.md`](./Design/codex-switch-v0.1.2-design.md)（规划中）
+当前仓库开发线 fact source 以这些文档为准：
+
+- [`cli-usage.md`](./cli-usage.md)
+- [`PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)
+- [`PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)
+- [`PRD/codex-switch-prd-v0.1.2.md`](./PRD/codex-switch-prd-v0.1.2.md)
+- [`PRD/codex-switch-prd-v0.1.3.md`](./PRD/codex-switch-prd-v0.1.3.md)
+- [`PRD/codex-switch-prd-v0.1.5.md`](./PRD/codex-switch-prd-v0.1.5.md)
+- [`Design/codex-switch-v0.1.2-design.md`](./Design/codex-switch-v0.1.2-design.md)
+- [`Design/codex-switch-v0.1.3-design.md`](./Design/codex-switch-v0.1.3-design.md)
+- [`Design/codex-switch-v0.1.5-design.md`](./Design/codex-switch-v0.1.5-design.md)
 
 ## 产品概述
 
-`codex-switch` 是一个本地 provider 管理 CLI，用于管理和切换目标 Codex runtime 的 provider/model-provider 路由配置，同时把工具自己的管理态保存在独立 tool home 下。
+`codex-switch` 是一个本地 provider 管理 CLI，用于管理和切换目标 Codex runtime 的 provider/model-provider 路由配置，同时把工具自己的管理态保存在独立 tool home 下。
 
 它不是旧 `setup` 小工具，也不是围绕单目录 `~/.codex` 组织全部状态的脚本集合。
 
@@ -50,11 +54,11 @@ target Codex runtime：
 
 ## 核心使用流程
 
-Direct 主路径：
+Direct 主路径：
 
 ```bash
 codexs init
-codexs add <provider> --model <model> --api-key <key> [--base-url <url>]
+codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> [--base-url <url>]
 codexs switch <provider>
 codexs status
 codexs doctor
@@ -65,7 +69,7 @@ Copilot 主路径：
 ```bash
 codexs init
 codexs login copilot
-codexs add <provider> --copilot --model <model>
+codexs add <provider> --copilot --profile <model-provider-id> --model <model>
 codexs switch <provider>
 codexs status
 codexs doctor
@@ -80,12 +84,13 @@ codexs migrate
 
 ## 当前产品判断
 
-`0.1.1` 的重点不是再加新命令，而是让用户在 README、help 和输出第一屏就能理解：
+`0.1.1` 的重点不是再加新命令，而是让用户在 README、help 和输出第一屏就能理解：
+
+- fresh install 应先走什么
+- Copilot 路径和 direct 路径有什么区别
+- 非交互命令为什么应显式传 `--profile`，以及 TTY 模式下哪些缺失项可以补问
+- `migrate` 何时才该使用
+- `status` / `doctor` 如何帮助定位下一步
+- 当前运行态是用顶层 `model` 与 `model_provider` 选择活动路由
 
-- fresh install 应先走什么
-- Copilot 路径和 direct 路径有什么区别
-- `migrate` 何时才该使用
-- `status` / `doctor` 如何帮助定位下一步
-- 当前运行态是用顶层 `model` 与 `model_provider` 选择活动路由
-
-`0.1.3` 是当前已发布的 Copilot login hotfix 线。当前实现边界是：Copilot 路径要求 Node.js `>=20`，受管安装默认固定到 `@github/copilot-sdk@1.0.2`，运行时会额外拒绝过旧版本和 prerelease 版本，并通过显式 `RuntimeConnection.forStdio({ path })` 把官方 SDK 连接到受管安装中的 Copilot runtime loader；本地 bridge 仍然只是面向 simple text-oriented turns 的 experimental bridge。Direct provider 路径继续支持 Node.js `>=18`。
+`0.1.5` 是当前仓库开发线，重点不是扩展 provider 面，而是让已有 Copilot bridge 实验路径具备过程可见性：SDK 事件被归一化为稳定运行态事件，Responses 流可以显示 commentary/reasoning 信号，未知事件摘要会被脱敏和截断。当前实现边界仍然是：Copilot 路径要求 Node.js `>=20`，受管安装默认固定到 `@github/copilot-sdk@1.0.2`，本地 bridge 仍然只是面向 simple text-oriented turns 的 experimental bridge；Direct provider 路径继续支持 Node.js `>=18`。

package/docs/codex-switch-technical-architecture.md

@@ -7,10 +7,12 @@
 - [`PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)
 - [`PRD/codex-switch-prd-v0.1.2.md`](./PRD/codex-switch-prd-v0.1.2.md)
 - [`PRD/codex-switch-prd-v0.1.3.md`](./PRD/codex-switch-prd-v0.1.3.md)
+- [`PRD/codex-switch-prd-v0.1.5.md`](./PRD/codex-switch-prd-v0.1.5.md)
 - [`Design/codex-switch-v0.1.0-design.md`](./Design/codex-switch-v0.1.0-design.md)
 - [`Design/codex-switch-v0.1.1-design.md`](./Design/codex-switch-v0.1.1-design.md)
 - [`Design/codex-switch-v0.1.2-design.md`](./Design/codex-switch-v0.1.2-design.md)
 - [`Design/codex-switch-v0.1.3-design.md`](./Design/codex-switch-v0.1.3-design.md)
+- [`Design/codex-switch-v0.1.5-design.md`](./Design/codex-switch-v0.1.5-design.md)
 
 ## Layers
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@minniexcode/codex-switch",
-  "version": "0.1.3",
-  "description": "Local-first CLI for managing and switching Codex provider/model-provider routing.",
+  "version": "0.1.5",
+  "description": "Local-first CLI for managing and switching Codex provider/model-provider routing.",
   "license": "MIT",
   "type": "commonjs",
   "bin": {