llm-switcher 1.1.0

package/docs/LLM-RESPONSE-MATRIX.md

@@ -0,0 +1,165 @@
+# LLM Provider Response Matrix
+
+How different LLM APIs shape their responses — and how `llm-switcher`
+normalizes them. Companion machine-readable file: [`response-matrix.json`](response-matrix.json).
+
+## Method
+
+- **Live-sampled (primary):** 48 responses from an OpenAI-compatible gateway
+  (9Router, 2026-09-12): **8 backend families × 6 variants**
+  (`base-stream`, `think-stream`, `think-nostream`, `tool-stream`,
+  `trunc-stream` with `max_tokens: 40`, `effort-stream` with
+  `reasoning_effort: high`). Reasoning prompts were used on purpose —
+  trivial prompts (e.g. "pong") often produce **no** thinking trace at all.
+- **Doc-based (secondary):** OpenRouter reasoning docs, Vertex AI
+  `generateContent` REST shape, OpenAI/Anthropic API references — used to
+  cover field names this gateway never emits (e.g. `reasoning_details[]`,
+  Vertex `thought` parts, `thoughtSignature`).
+
+No credentials or personal data appear in the samples.
+
+## TL;DR
+
+| # | Finding |
+|---|---|
+| 1 | Same gateway, different field names per backend: `reasoning_content` (claude/openai/nvidia/gemini-stream), `reasoning` + `reasoning_content` **duplicated** (zai), nothing at all (qwen/plain). |
+| 2 | **Non-streaming drops hidden thinking** on most backends — only `content` (+ token counters) comes back. Streaming is the only reliable way to get thinking blocks. |
+| 3 | Usage shapes differ: single total chunk (OpenAI-style), per-token deltas (Cloudflare-style `qwen`/`zai` with `neurons`), or **absent in stream** (`gpt-oss` family) — count deltas manually as fallback. |
+| 4 | `finish_reason` may arrive in the **first** chunk (qwen) or repeat per chunk; always take the **last** non-null value. |
+| 5 | Tool calls may stream split across chunks (qwen: 6 chunks) or whole; args may be `string` (OpenAI) or `object` (Vertex `functionCall.args`). |
+| 6 | Request-side: thinking budgets `< 1024` are rejected (400); `reasoning_effort` is rejected by some backends (503 `INVALID_ARGUMENT` on `gpt-oss`); gateways cool down after bad requests (`reset after Ns`). |
+
+## 1. Envelopes
+
+### 1.1 OpenAI Chat Completions (most common)
+
+Non-stream:
+```json
+{"id":"chatcmpl-...","object":"chat.completion","created":1789184460,"model":"...claude-opus-4-6-thinking",
+ "choices":[{"index":0,"message":{"role":"assistant","content":"pong"},"finish_reason":"stop"}],
+ "usage":{"prompt_tokens":2043,"completion_tokens":15,"total_tokens":2058}}
+```
+
+Stream (`data:` lines, terminal `[DONE]`):
+```
+data: {"...","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
+data: {"...","choices":[{"index":0,"delta":{"reasoning_content":"p"},"finish_reason":null}]}
+data: {"...","choices":[{"index":0,"delta":{"content":"p"},"finish_reason":null}]}
+data: {"...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{...}}
+data: [DONE]
+```
+
+### 1.2 Vertex `generateContent` (native)
+
+Non-stream:
+```json
+{"candidates":[{"content":{"role":"model","parts":[
+   {"text":"plan...","thought":true,"thoughtSignature":"..."},
+   {"text":"answer"},
+   {"functionCall":{"name":"calc","args":{"expr":"2+2"}}}]},
+  "finishReason":"STOP"}],
+ "usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":20,"totalTokenCount":30}}
+```
+Stream (`:streamGenerateContent?alt=sse`): same objects as `data:` lines, incremental parts.
+
+### 1.3 Anthropic Messages (native target)
+
+```json
+{"id":"msg_...","type":"message","role":"assistant","model":"...",
+ "content":[{"type":"thinking","thinking":"...","signature":"..."},
+            {"type":"text","text":"..."},
+            {"type":"tool_use","id":"...","name":"...","input":{}}],
+ "stop_reason":"end_turn",
+ "usage":{"input_tokens":0,"output_tokens":0}}
+```
+
+### 1.4 OpenRouter extensions (doc-based)
+
+- `message.reasoning` / `delta.reasoning` (plain string; `reasoning_content` is an accepted alias).
+- `message.reasoning_details[]` / `delta.reasoning_details[]` with typed items:
+  `reasoning.text {text, signature}`, `reasoning.summary {summary}`,
+  `reasoning.encrypted {data}` (+ `id`, `format`, `index`).
+- Request: unified `reasoning: {effort | max_tokens, exclude, enabled}`;
+  Anthropic minimum budget **1024**; Gemini 3 uses `thinkingLevel`
+  (`minimal|low|medium|high`) instead of token budgets.
+
+## 2. Reasoning / thinking — where it actually appears (live)
+
+`R` = `reasoning_content`, `r` = `reasoning`, `–` = absent.
+
+| Backend | base-stream | think-stream | think-nostream | tool-stream | trunc-stream |
+|---|---|---|---|---|---|
+| claude-budget (opus-4-6-thinking) | R | R | – (content only!) | R + tools | R |
+| claude-adaptive (sonnet-4-6) | – | – | – | tools, no R | – |
+| gemini (3.8-flash-high) | R (hard tasks only) | R | – (+`reasoning_tokens` counter) | tools, no R | R |
+| openai (gpt-oss-120b) | R | R | – | R + tools | R, no content |
+| qwen (qwq-32b) | – (CoT leaks into `content`) | – | – (long CoT as content) | tools split ×6 chunks | – |
+| zai (glm-4.7-flash) | R **and** r (same text twice!) | R + r | R + r, `content: null` | R + r + tools | R + r |
+| nvidia (nemotron) | R (no usage in stream!) | R | – | R + tools | R |
+| plain (gpt-4o-mini) | – | – | – (+`padding` junk field) | tools | – |
+
+Notes:
+- Gemini emits `R` as **one big chunk** (not token-split); others stream it token by token.
+- Easy prompts may yield zero thinking even on thinking-capable models, while
+  `reasoning_tokens` in usage still counts hidden work.
+- `zai` duplicates every reasoning delta under both keys — parsers must take the
+  **first** match, never concatenate.
+
+## 3. Tool calls (live)
+
+| Backend | Shape |
+|---|---|
+| OpenAI-style | `tool_calls: [{id, type:"function", function:{name, arguments:"{...}"}}]`, whole or split across chunks |
+| qwen | same shape, but split across ~6 delta chunks; `finish_reason:"stop"` repeats per chunk |
+| zai | same shape + duplicated reasoning alongside |
+| Vertex native | `parts: [{functionCall:{name, args:{...}}}]` (args is an **object**), no id |
+| plain (gh) | same shape; stream interleaves `content:null` chunks |
+
+Missing ids are synthesized as `call_<24 random chars>` (Vertex: `call_vtx_<n>_<name>`, healer: `call_heal_<n>`); args objects are stringified
+for OpenAI-shaped outputs and parsed back to objects for Anthropic/Vertex outputs.
+
+## 4. Usage accounting (live)
+
+| Backend | Stream usage | Keys |
+|---|---|---|
+| claude/adaptive/gemini/plain | one final chunk | `prompt_tokens, completion_tokens, total_tokens` (+ `completion_tokens_details.reasoning_tokens` on gemini, `prompt_tokens_details.cached_tokens` where cached) |
+| qwen/zai (Cloudflare) | **every** chunk | per-token deltas (`completion_tokens: 1` × N) + `neurons`, sometimes `estimated`; prompt total only on first chunk |
+| nvidia | `usage: null` per chunk, one real total at end (`estimated` flag) | same keys as OpenAI-style |
+| openai (gpt-oss) | **none in stream** | count deltas manually |
+
+Rule used by the proxy: `prompt = MAX(seen)`. For per-chunk deltas, `completion = SUM(deltas)`.
+For cumulative usage, `completion = LAST`. The shape is detected per stream. When upstream sends
+nothing, the proxy counts the deltas itself. Gemini counts thoughts apart from candidates, so its
+completion is `candidatesTokenCount + thoughtsTokenCount`.
+
+## 5. Finish reasons, ids, errors (live)
+
+- Observed `finish_reason`: `stop`, `tool_calls`, `length` (also `STOP`/`MAX_TOKENS`/`SAFETY…` on Vertex-native). Mapping: `stop→end_turn`, `length→max_tokens`, `tool_calls→tool_use` (Anthropic); `STOP/MAX_TOKENS/SAFETY` (Vertex output).
+- If any tool call was seen, the final stop is forced to `tool_use` regardless.
+- Id prefixes vary (`chatcmpl-`, `chatcmpl-msg_`, `chatcmpl-req_`, `id-…`); outputs are normalized to `msg_` / `chatcmpl-` / `resp_` per client protocol.
+- Error envelope: `{"error":{"message":"[backend/model] [400]: {...} (reset after Ns)"}}` — note the cooldown hint; back off instead of retrying hot.
+- Junk to ignore: `padding`, `copilot_usage`, `service_tier`, `system_fingerprint`, `logprobs`, `neurons`, `estimated`, `refusal`, `annotations`, `audio`, `token_ids`, empty `choices: []` chunks, doubled `[DONE]`.
+
+## 6. Request-side gotchas (live)
+
+- `thinking: {type:"enabled", budget_tokens:<1024}` → HTTP 400. Clamp to ≥ 1024.
+- `reasoning_effort: "high"` → HTTP 503 `INVALID_ARGUMENT` on `gpt-oss`-class backends. Only send effort levels the backend accepts.
+- `include_reasoning: true` (legacy) is accepted but changes nothing observable.
+- Omitting `stream` defaults to **streaming** on some gateways — always send it explicitly.
+- `stream_options: {include_usage:true}` is required by spec for stream usage, though some gateways send usage anyway.
+
+## 7. How the proxy maps this (`formats.mjs`)
+
+- `smartReasoning / smartText / smartToolCalls / smartUsage / smartFinish` — accept every field name above, first-match wins (no double-count).
+- `normalizeUpstream(parsed, outFormat)` — one SSE chunk **or** one full JSON → canonical events `{think, text, tools, finish, usage}`; also walks native Anthropic event types and Vertex `candidates`.
+- Renderers emit the client protocol: `createAnthropicStream` (thinking+signature → `thinking_delta`, `<think>`-tag fallback with split-tag buffering), `createChatStream` (`reasoning_content` extension), `createResponsesStream` (Codex reasoning summary + deltas), `createVertexStream` (`thought` parts + `thoughtSignature` passthrough when genuine).
+- Known non-goals: hidden thinking that the backend never returns (gemini non-stream counters, qwen CoT-in-content) cannot be recovered; encrypted `reasoning.encrypted.data` blobs are skipped as thinking text.
+
+## 8. Reproduce
+
+Send the same prompt matrix (`base/think/nostream/tool/trunc/effort` × `stream on/off`)
+against any OpenAI-compatible `/chat/completions` endpoint and record, per chunk,
+`delta` key sets, reasoning/text presence, `finish_reason` sequence, usage key
+sets, and id prefixes. A reasoning-heavy prompt is required — trivial prompts
+often yield no thinking trace. Never commit keys; keep sampler scripts out of
+the repo.

package/docs/TOKEN-OPTIMIZER-INTEROP.md

@@ -0,0 +1,110 @@
+# Token Optimizer Interoperability & Failure Mode Report
+
+**How LLM Switcher acts as the protective outermost edge gateway for aggressive prompt/token optimizers (Headroom, RTK, Ponytail).**
+
+---
+
+## Executive Summary
+
+Third-party prompt optimizers and token compressors — such as **Headroom**, **RTK (Rust Token Killer)**, and **Ponytail** — attempt to reduce LLM input tokens by aggressively pruning message history, truncating command stdout, or forcing extreme prompt brevity.
+
+While these tools can reduce raw token counts in simple scenarios, **they frequently break complex agentic coding workflows** by corrupting message graphs, orphaning tool calls, and stripping reasoning parameters. When these pruned payloads hit upstream APIs directly (such as Anthropic, OpenAI, or 9Router), the provider immediately throws fatal `HTTP 400 Bad Request` errors or severely degrades reasoning depth.
+
+**LLM Switcher solves this by acting as the outermost edge gatekeeper (`127.0.0.1:3456`).** It intercepts the pruned payload before it leaves your machine, runs its built-in **Healer Engine** to repair message graphs and restore reasoning parameters, unlocks 1M context windows, and safely converts the protocol to your upstream provider.
+
+---
+
+## Tool Breakdown: What They Do & How They Break Payloads
+
+### 1. Headroom (`headroomlabs-ai/headroom`)
+- **Mechanism:** Runs as a local proxy on `:8787` (or wraps CLI agents). Compresses conversation history, RAG chunks, and tool outputs using SmartCrusher (JSON), CodeCompressor (AST), and Kompress-v2-base. Also attempts "effort routing" to dial down thinking budgets.
+- **Critical Failure Points:**
+  - **Orphaned `tool_result` blocks:** When pruning historical turns, Headroom often discards the `assistant` turn containing a `tool_use`, while retaining the subsequent `user` turn containing the `tool_result`. Anthropic's API strictly validates tool use IDs and crashes with:
+    ```
+    HTTP 400 invalid_request_error: "tool_use_id 'xxx' does not correspond to any tool_use"
+    ```
+  - **Consecutive `user` turns:** Dropping intermediary assistant turns causes multiple user messages to sit adjacent to each other. Anthropic strictly throws:
+    ```
+    HTTP 400 invalid_request_error: "roles must alternate between 'user' and 'assistant'"
+    ```
+  - **Reasoning Suppression:** Its "effort routing" dials down `thinking.budget_tokens` on routine tool turns. On complex models (Claude Opus, Gemini Flash), this prevents the model from formulating multi-step reasoning before acting.
+
+### 2. RTK (`rtk-ai/rtk` - Rust Token Killer)
+- **Mechanism:** A single Rust binary that hooks into shell tool execution (e.g. `PreToolUse` in Claude Code / Cursor) and rewrites CLI commands (`git`, `ls`, `cat`, `grep`, `pytest`) to filter out noise, truncate lines, and inject recall tokens (`[full output: rtk recall xxx]`).
+- **Critical Failure Points:**
+  - **Corrupted Structural Data:** When an agent invokes a tool expecting machine-readable JSON or exact AST formatting, RTK's heuristic summaries can alter structural delimiters, causing downstream tool call parsing errors.
+  - **Custom Tracking Headers:** RTK and associated tracing proxies inject headers (`x-rtk-*`, `traceparent`, `x-optimizer-id`) that some strict upstream endpoints reject if not cleanly forwarded.
+
+### 3. Ponytail (`DietrichGebert/ponytail`)
+- **Mechanism:** A behavioral prompt engineering plugin/ruleset that injects extreme conciseness instructions ("write one line, it works, YAGNI") into agent system prompts across 20+ coding tools.
+- **Critical Failure Points:**
+  - **Premature Execution without Reasoning:** By commanding the model to be maximally brief and avoid planning, reasoning models are discouraged from spending thinking tokens. The model outputs untested single-liners that often fail type checks and test suites.
+  - **System Prompt Prefix Invalidation:** Injected rules alter the leading system prompt bytes, busting provider prompt caches unless carefully aligned.
+
+---
+
+## The Healer Engine: How LLM Switcher Protects the Workflow
+
+LLM Switcher sits between the optimizer tool and the upstream LLM:
+
+```
+[CLI Agent] ──> [Optimizer: Headroom / RTK] ──> [LLM Switcher :3456] ──> [Upstream / 9Router]
+                                                 │
+                                                 ├── 1. Heal Orphaned tool_results
+                                                 ├── 2. Merge Consecutive Turns
+                                                 ├── 3. Restore Stripped Thinking
+                                                 └── 4. Enforce 1M Context
+```
+
+### Protection Matrix: Before vs. After
+
+| Scenario | Direct to Upstream (Without Switcher) | Through LLM Switcher (Healer Engine) |
+|---|---|---|
+| **Orphaned `tool_result` turn** | ❌ **HTTP 400 Crash**: `tool_use_id does not correspond to any tool_use` | ✅ **HTTP 200 OK**: Heals orphaned result into contextual text block `[Tool Result (id)]: ...` |
+| **Consecutive `user` turns** | ❌ **HTTP 400 Crash**: `roles must alternate` | ✅ **HTTP 200 OK**: Merges consecutive turns into a single valid turn seamlessly |
+| **Stripped `thinking` parameters** | ⚠️ **Degraded AI**: Reasoning disabled, model outputs shallow single-liners | ✅ **HTTP 200 OK**: Detects reasoning models and automatically restores safe thinking budget |
+| **Orphaned `tool` role in Chat API** | ❌ **HTTP 400 Crash**: `tool role must respond to tool_calls` | ✅ **HTTP 200 OK**: Converts orphaned tool message into user context |
+| **Custom tracking headers** | ⚠️ Connection dropped / unrecognized header warnings | ✅ **HTTP 200 OK**: Cleanly passes through `traceparent`, `x-request-id`, `x-rtk-*` |
+
+---
+
+## Test Methodology & Verification Suite
+
+We created an automated verification suite in [`tests/live-optimizer-interop.mjs`](../tests/live-optimizer-interop.mjs) that systematically replicates the failure modes of each tool:
+
+### Running the Test Suite
+```bash
+node tests/live-optimizer-interop.mjs
+```
+
+### Live Test Results
+```text
+================================================================
+  LLM SWITCHER — TOKEN OPTIMIZER INTEROPERABILITY TEST SUITE   
+  Simulating failure modes from Headroom, RTK, and Ponytail    
+================================================================
+
+[TEST] Headroom Simulation: Orphaned tool_result turn... PASS (8840ms)
+       ↳ Healed orphaned tool_result. Response HTTP 200: "It looks like you've shared a fragment of context ..."
+[TEST] Headroom Simulation: Consecutive User turns (Role alternation violation)... PASS (2683ms)
+       ↳ Merged consecutive turns seamlessly. Stop reason: end_turn
+[TEST] Thinking Guard: Restoring stripped thinking parameter on reasoning models... PASS (5372ms)
+       ↳ Automatically restored thinking: thinking_delta=true, signature_delta=true, text_delta=true
+[TEST] RTK Intermediary: Custom headers and traceparent passthrough... PASS (2453ms)
+       ↳ Headers accepted cleanly with HTTP 200 OK
+[TEST] OpenAI Chat Healer: Orphaned role tool without preceding assistant tool_calls... PASS (1561ms)
+       ↳ Chat Healer rescued orphaned tool role. Stop reason: length
+
+================================================================
+  TEST RESULTS: 5 PASSED / 0 FAILED               
+================================================================
+```
+
+---
+
+## Recommended User Setup
+
+For developers using prompt optimization tools:
+1. Keep the optimizer installed in your CLI tool as usual.
+2. In the optimizer's configuration (e.g. `headroom.yaml` or RTK upstream settings), set the upstream target URL to **LLM Switcher** (`http://127.0.0.1:3456`).
+3. Enjoy prompt compression savings without worrying about broken conversation graphs, HTTP 400 crashes, or lost reasoning depth.

package/docs/codex-blindfold.md

@@ -0,0 +1,214 @@
+# Hide the gateway from the Codex CLI
+
+## Diagrams
+
+Open these next to the text. Each one is a standalone HTML page.
+
+| Diagram | Shows |
+| --- | --- |
+| [Request routing](diagrams/blindfold-request-routing.html) | One Codex request, from CONNECT to the provider |
+| [Model name resolution](diagrams/codex-model-name-resolution.html) | Which name the CLI sees, and where it resolves |
+| [Lifecycle under switch](diagrams/blindfold-switch-lifecycle.html) | Activation, refusal, and shutdown |
+
+The JSON source of each diagram sits beside its HTML file. Edit the JSON and rebuild with the `archify` tool; do not edit the HTML.
+
+## What this does
+
+The normal route sends Codex to the gateway with `--config openai_base_url=...`. That works, but the CLI then prints one line on its own `/model` screen:
+
+```
+base URL is overridden to http://127.0.0.1:3456/v1. Selecting models may not be supported or work properly.
+```
+
+No configuration key removes that line. The line exists to report an overridden base URL, so the only way to remove it is to stop overriding the base URL.
+
+Blindfold mode does that. Codex keeps its official endpoint. The switcher intercepts one layer lower, at the network hop. The configuration file of Codex stays unchanged.
+
+## How it works
+
+Codex reads the `HTTPS_PROXY` variable. In blindfold mode the switcher points that variable at `blindfold/blindfold.mjs`. Codex then sends `CONNECT chatgpt.com:443` to that process.
+
+The process answers the CONNECT itself. It ends the TLS session with a leaf certificate for the target host, and it forwards the Codex API calls to the gateway. Three rules decide where each request goes:
+
+| Request | Destination |
+| --- | --- |
+| Target host, path under `/backend-api/codex/` | The local gateway |
+| Target host, any other path | The real host, over a new TLS session |
+| Another public host | A raw tunnel. The process never reads the bytes. |
+| A local or private address | Refused. |
+
+The routing decision reads the **normalized** path, not the text the client sent. Node hands over the request target exactly as written, but the gateway resolves it with `new URL(...)`. A raw-text test would therefore accept a string that the gateway later reads as a different path: `/backend-api/codex/%2e%2e/api/logs` becomes `/api/logs`, which is the gateway's admin API. The decision also requires a segment boundary, so `/backend-api/codex-usage` stays with the host it belongs to.
+
+Sign-in, token refresh and the usage page keep working, because they do not use the Codex API path.
+
+## Why no system change is necessary
+
+Codex reads a custom certificate authority from the `CODEX_CA_CERTIFICATE` variable. The private CA stays in the repository. Three things that other interception guides ask for are not necessary here:
+
+- No certificate in the Windows or macOS trust store.
+- No line in the `hosts` file, so no administrator rights.
+- No change to `~/.codex/config.toml`.
+
+To stop the interception, run `switch off`. It stops the interceptor and removes the launch files (`active.flag`, the `env*` files and the model catalog). These items stay until you remove them:
+
+- The certificates in `blindfold/certs/`, including `ca.key`. Delete the directory when you do not use blindfold mode again.
+- `blindfold.log` and `proxy.log`. Delete them by hand.
+- The shims in `~/.llm-switcher/bin`. Run `switch shim uninstall` to remove them.
+
+## Before you start
+
+You need:
+
+- Node.js 18.17 or later.
+- `openssl`. Windows users have it with Git for Windows. Run the script from Git Bash.
+- A gateway profile for Codex that already works in the normal route.
+
+## Procedure
+
+### 1. Build the certificates
+
+Run this command in the repository root:
+
+```bash
+bash blindfold/make-certs.sh chatgpt.com
+```
+
+The script writes `blindfold/certs/ca.pem` and `blindfold/certs/leaf.pem`. It prints the extended key usage and the subject alternative name of the leaf. Make sure that the output contains `TLS Web Server Authentication`.
+
+CAUTION: Do not build these certificates with `New-SelfSignedCertificate` in PowerShell. That command writes a leaf without the `serverAuth` extended key usage, and a strict client refuses it with `unsuitable certificate purpose`.
+
+`blindfold/certs/` is in `.gitignore`. The private keys never enter the repository history.
+
+### 2. Turn on blindfold mode in the profile
+
+Add two keys to the Codex profile in `config.json`:
+
+```json
+"blindfold": true,
+"blindfoldPort": 3457
+```
+
+`blindfoldPort` is optional. The default is 3457.
+
+### 3. Activate the profile
+
+```bash
+switch codex <your-profile>
+```
+
+This one command starts the gateway and writes the environment files. The gateway then starts the interceptor on the configured port. `switch off` stops both and removes the generated files.
+
+The gateway owns the interceptor. It brings the interceptor in line with `config.json` when it starts, after every change in the dashboard, and after every `switch` command. A service start, a `switch port`, and a change of host, prefix or port in the dashboard therefore never leave `HTTPS_PROXY` pointing at a port where nothing listens. When blindfold mode is turned off for the Codex target, the gateway stops the interceptor, and a running Codex session must be restarted.
+
+`switch` refuses the activation and writes no file in these cases:
+
+- The CA, the leaf certificate or the leaf key is missing, or the leaf does not cover the host.
+- The leaf was not signed by the CA, or the leaf key does not match the leaf. This occurs when the files come from two different builds.
+- Another process holds the interceptor port or the gateway port.
+
+That refusal is deliberate: blindfold mode replaces the base URL override with `HTTPS_PROXY`, so a half-applied state would point Codex at a port where nothing listens, and Codex would then reach no host at all. If the interceptor fails to start after these checks pass, `switch` restores the previous `config.json` and launcher files and exits with an error.
+
+The switcher trusts a port only after the process on it proves its identity with the token in `admin.token`. A process that only answers on the port, or replays an earlier answer, is treated as foreign.
+
+The environment now holds `HTTPS_PROXY`, `NO_PROXY` and `CODEX_CA_CERTIFICATE` in `env-codex.cmd` and `env-codex.sh`. Only the Codex shim loads those two files. They are separate from `env.cmd` and `env.sh` on purpose: the `claude` shim loads the shared files, and a Codex-only proxy would otherwise capture every `claude` HTTPS call.
+
+The shared files no longer hold `LLM_SWITCHER_CODEX_BASE_URL`, so the shim adds no base URL override.
+
+### 4. Verify the route
+
+Run Codex and open `/model`. The screen shows the official model names, and the override line is gone.
+
+To test without Codex, ask the gateway for its model list through the proxy:
+
+```bash
+node -e "
+const http=require('http'),tls=require('tls'),fs=require('fs');
+const ca=fs.readFileSync('blindfold/certs/ca.pem');
+const r=http.request({host:'127.0.0.1',port:3457,method:'CONNECT',path:'chatgpt.com:443'});
+r.end();
+r.on('connect',(res,socket)=>{
+  const s=tls.connect({socket,servername:'chatgpt.com',ca},()=>{
+    s.write('GET /backend-api/codex/models HTTP/1.1\r\nHost: chatgpt.com\r\nConnection: close\r\n\r\n');
+  });
+  s.on('data',d=>process.stdout.write(d));
+});
+"
+```
+
+The answer is the model list of the gateway. Change the path to `/backend-api/codex/%2e%2e/api/logs` and the answer comes from chatgpt.com instead, which proves the normalization.
+
+NOTE: On Windows, `curl` uses the Schannel TLS backend. Schannel ignores `--cacert` for this test and reports error 60. Use the Node command above instead.
+
+## Record what a client sends
+
+Add `--capture <dir>` to write one JSON file per intercepted exchange:
+
+```bash
+node blindfold/blindfold.mjs --capture ./captures
+```
+
+Each file holds the method, the URL, both header sets and both bodies, truncated
+at 200000 characters. Use it to learn what a genuine CLI or IDE puts on the wire.
+
+Both routes are recorded: the calls that go to the gateway, and the calls that are
+re-originated to the real host. A compressed body is decoded first, because a
+client asks for `gzip` and the bytes on the wire are not readable text. The
+forwarded response keeps its original bytes; only the copy in the file is decoded.
+
+To record a different tool, point the proxy at that tool's host and give it a
+prefix that no path can match, so every request is re-originated and recorded:
+
+```bash
+bash blindfold/make-certs.sh api.anthropic.com ~/.llm-switcher/anthropic/certs
+node blindfold/blindfold.mjs --host api.anthropic.com --prefix /no-gateway \
+  --port 3458 --certs ~/.llm-switcher/anthropic/certs --capture ~/.llm-switcher/anthropic/captures
+```
+
+Use directories that you own. `make-certs.sh` and `--capture` refuse a directory that another
+account owns, because that account could read the key or the captures.
+
+Then start the tool with `HTTPS_PROXY=http://127.0.0.1:3458` and the CA in the
+variable that the tool reads. A Node client reads `NODE_EXTRA_CA_CERTS`. Set both
+variables for that process only; a variable set for one process does not change a
+process that already runs.
+
+Credential headers never reach the file. `authorization`, `proxy-authorization`,
+`cookie`, `set-cookie`, `x-api-key` and `api-key` are replaced with `<redacted>`,
+and so are the account identifiers `chatgpt-account-id`, `openai-organization` and
+`x-goog-user-project`. The header names stay, so the shape of the request is still
+readable.
+
+CAUTION: The redaction covers headers only. Both bodies are written as they
+travelled, so a capture holds your prompts, your source code and the answers of
+the model. A body can also hold a secret, for example a token that a tool printed.
+`captures/` is in `.gitignore`. If you capture somewhere else, add that
+path to `.gitignore` before you commit. Delete a capture when you do not need it.
+
+The proxy creates the capture directory with mode 0700 and each file with mode 0600.
+
+NOTE: WebSocket sessions are recorded too. Each session gives one file, with every
+message in order, and the proxy updates the file while the session runs. Codex sends
+its completions over a WebSocket, so these files hold the full conversation.
+
+## How to go back
+
+1. Set `"blindfold": false` in the profile.
+2. Run `switch codex <your-profile>` again.
+
+The switcher writes `LLM_SWITCHER_CODEX_BASE_URL` again, the gateway stops the interceptor, and Codex returns to the normal route.
+
+## Limits
+
+Read this section before you turn blindfold mode on.
+
+**The CA is trusted for every host that Codex contacts.** `CODEX_CA_CERTIFICATE` adds this authority to the trust store that Codex uses for all of its HTTPS calls. A CA that `make-certs.sh` builds now carries a name constraint: it can sign only for the target host and its subdomains. A client that obeys name constraints refuses any other certificate from this CA. OpenSSL, rustls and the macOS and Windows verifiers obey them. A CA that an older version built has no constraint. Anybody who can read its `ca.key` can forge a certificate for any host. Run `make-certs.sh` again to replace it, and keep `blindfold/certs/` private in both cases.
+
+**All traffic to the intercepted host is decrypted by this process.** That includes sign-in and token refresh, because the CONNECT for the whole host is terminated locally. Requests outside the Codex API path are re-originated to the real host over a new TLS session; they are forwarded, not tunneled. The `--verbose` flag prints the method and path of every such request.
+
+**Directory permissions are weaker on Windows.** `make-certs.sh` calls `chmod` on the certificate directory, and that call does nothing under Git Bash for Windows. On that platform the keys are protected only by the account that owns the directory.
+
+**Only one host is intercepted.** If your Codex uses API key authentication instead of ChatGPT authentication, the host is `api.openai.com`. Build the leaf for that host, and start the process with `--host api.openai.com --prefix /v1`.
+
+**The interceptor is a proxy.** It binds to loopback, so a remote machine cannot use it, but every process on this machine can. It refuses a CONNECT to a local or private address, so it cannot be used to reach a service that listens only on this machine. The interceptor resolves the name first and checks every address in the answer, so a spelling such as `2130706433` or a name that resolves to `127.0.0.1` is also refused. It then connects to the address that it checked. It prints each refused target once, without `--verbose`. A VPN or split DNS can resolve a public name to a private address, and that message shows the cause.
+
+**Some `--config` keys still travel.** Blindfold mode removes the base URL override only. The switcher still passes `model_catalog_json`, the three role names (`model`, `review_model`, `agents.default_subagent_model`) and the two context window keys, because those carry no address and no internal name.

package/docs/cross-platform.md

@@ -0,0 +1,136 @@
+# Run this repository on Linux, macOS and Windows
+
+The gateway is plain Node.js with no dependencies. Nothing in the source holds an
+absolute Windows path. Every command that differs between platforms has a branch for
+each one. This guide states what to install, what changes per platform, and which two
+features are not available everywhere.
+
+## What you need
+
+| Item | Why |
+| --- | --- |
+| Node.js 18.17 or later | The gateway, the launcher and the interceptor |
+| `bash` and `openssl` | Only for blindfold mode, to build the certificates |
+| Nothing else | `npm install` is not necessary. The package has no dependencies. |
+
+Linux and macOS have `bash` and `openssl` already. On Windows both arrive with Git for
+Windows, inside Git Bash.
+
+## Install
+
+The steps are the same on all three platforms.
+
+```bash
+git clone https://github.com/louisphamdev/llm-switcher.git
+cd llm-switcher
+cp config.example.json config.json
+```
+
+Edit `config.json`, then start the gateway:
+
+```bash
+node switch.mjs on
+```
+
+## Put `switch` on PATH
+
+The repository holds two launchers. Both run the same `switch.mjs`.
+
+| Platform | File | How to reach it |
+| --- | --- | --- |
+| Linux, macOS | `switch` | `export PATH="/path/to/llm-switcher:$PATH"` in `~/.bashrc` or `~/.zshrc` |
+| Windows | `switch.cmd` | Add the repository directory to the user PATH |
+
+After that, `switch status`, `switch codex <profile>` and `switch off` behave the same
+everywhere. If you prefer not to change PATH, run `node switch.mjs <command>` instead.
+
+If `switch` reports "permission denied" on Linux or macOS, the executable bit was lost
+in transfer. Restore it:
+
+```bash
+chmod +x switch
+```
+
+## What the switcher writes for each platform
+
+`switch` writes both forms every time, so the same working copy serves a shell and a
+command prompt:
+
+| File | Read by |
+| --- | --- |
+| `env.sh`, `env-codex.sh` | The POSIX shims and any shell |
+| `env.cmd`, `env-codex.cmd` | The Windows shims, Command Prompt and PowerShell |
+
+The CLI shims follow the same rule. `switch shim install` writes
+`~/.llm-switcher/bin/claude` and `~/.llm-switcher/bin/codex` on Linux and macOS, with
+the executable bit set. On Windows it writes `claude.cmd` and `codex.cmd` in the same
+directory. Put that directory before the real CLI in PATH:
+
+```bash
+export PATH="$HOME/.llm-switcher/bin:$PATH"     # Linux, macOS
+```
+
+```
+%USERPROFILE%\.llm-switcher\bin                 # Windows: add before the Codex directory
+```
+
+## Commands that differ inside the code
+
+You do not call these yourself. They are listed so that a reader knows the platform
+work is already done.
+
+| Task | Linux, macOS | Windows |
+| --- | --- | --- |
+| Find the process on a port | `lsof` | `netstat -ano` |
+| Stop a process | `process.kill` | `taskkill /F /PID` |
+| Open the dashboard | `xdg-open`, `open` | `cmd /c start` |
+
+## Two features are not available everywhere
+
+**`switch doctor` cannot inspect running CLI sessions on Windows.** That check reads the
+environment of a live process with `pgrep` and `ps`, which exist only on Linux and
+macOS. On Windows the rest of `switch doctor` still runs, and this one section reports
+that it is not supported. A Windows user who wants the same answer must close the CLI
+and start it again from a shell where the shim is on PATH.
+
+**`make-certs.sh` cannot protect the key directory on Windows.** The script calls
+`chmod 700` on `blindfold/certs/`, and that call does nothing under Git Bash for
+Windows. On that platform the private keys are protected only by the permissions of the
+account that owns the directory. Keep the repository in a user-owned location.
+
+Four tests in `tests/shim.test.mjs` run the generated POSIX shim as a real program, so
+they skip on Windows. The suite reports them as skipped, not as failures.
+
+## Blindfold mode on each platform
+
+Blindfold mode works on all three platforms, because it needs no administrator rights,
+no `hosts` file change and no certificate in a system trust store. See
+[`codex-blindfold.md`](codex-blindfold.md) for what it does.
+
+Build the certificates once. On Windows, run this line in Git Bash, not in PowerShell:
+
+```bash
+bash blindfold/make-certs.sh chatgpt.com
+```
+
+The subject of the certificate must match the host your Codex account calls:
+
+| Codex sign-in | Host | Profile keys |
+| --- | --- | --- |
+| ChatGPT account | `chatgpt.com` | The defaults. Add nothing. |
+| API key | `api.openai.com` | `"blindfoldHost": "api.openai.com"`, `"blindfoldPrefix": "/v1"` |
+
+`switch` compares the host in the profile against the subject alternative names of the
+leaf certificate. If they differ it refuses the activation, names the host, and prints
+the command that rebuilds the certificate. No file is written on that path.
+
+## Check that the platform work succeeded
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+On Linux and macOS every test runs. On Windows four shim tests skip. A failure on any
+platform is a real defect; report it with the platform name and the Node version.