llm-switcher 1.1.11 → 1.2.0

package/catalog.mjs

@@ -0,0 +1,246 @@
+// ============================================================
+// catalog.mjs — dynamic model catalog discovery and slot mapping (Claude Code & Codex)
+//
+// Automatically fetches official model lists from Anthropic / OpenAI or custom
+// upstream endpoints to ensure mapping tables never go stale when providers release
+// new model variants (e.g. gpt-6-sol, claude-opus-5-5).
+// ============================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const OFFICIAL_MODEL_URLS = {
+  claude: 'https://api.anthropic.com/v1/models',
+  codex: 'https://api.openai.com/v1/models'
+};
+
+export const BASELINE_MODELS = {
+  claude: {
+    opus: ['claude-opus-5-5', 'claude-opus-4-6', 'claude-3-opus-20240229'],
+    sonnet: ['claude-sonnet-4', 'claude-3-7-sonnet-20250219', 'claude-3-5-sonnet-20241022'],
+    haiku: ['claude-haiku-4', 'claude-3-5-haiku-20241022'],
+    fable: ['claude-fable-4']
+  },
+  codex: {
+    main: ['gpt-6-sol', 'gpt-5.6-sol', 'gpt-5.2', 'o3', 'gpt-4o'],
+    review: ['gpt-6-terra', 'gpt-5.6-terra', 'o3-mini'],
+    subagent: ['gpt-6-luna', 'gpt-5.6-luna', 'gpt-5.3-codex', 'gpt-5.2-codex']
+  }
+};
+
+/** Classifies a Claude model name into its corresponding tier slot */
+export function classifyClaudeTier(modelId) {
+  const m = String(modelId || '').toLowerCase();
+  if (m.includes('fable')) return 'fable';
+  if (m.includes('opus')) return 'opus';
+  if (m.includes('haiku')) return 'haiku';
+  return 'sonnet';
+}
+
+/** Classifies a Codex model name into its corresponding role slot */
+export function classifyCodexRole(modelId) {
+  const m = String(modelId || '').toLowerCase();
+  if (m.includes('terra') || m.includes('review')) return 'review';
+  if (m.includes('luna') || m.includes('subagent')) return 'subagent';
+  return 'main';
+}
+
+function catalogCachePath(stateDir) {
+  return path.join(stateDir, 'catalog-cache.json');
+}
+
+/** Loads cached catalog from disk, falling back to built-in baseline models */
+export function loadCatalogCache(stateDir) {
+  const p = catalogCachePath(stateDir);
+  try {
+    if (fs.existsSync(p)) {
+      const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (data && typeof data === 'object') return data;
+    }
+  } catch {}
+  return {
+    updatedAt: 0,
+    claude: {
+      models: Object.entries(BASELINE_MODELS.claude).flatMap(([tier, ids]) => ids.map(id => ({ id, tier })))
+    },
+    codex: {
+      models: Object.entries(BASELINE_MODELS.codex).flatMap(([role, ids]) => ids.map(id => ({ id, role })))
+    }
+  };
+}
+
+/** Atomically writes the model catalog cache to disk */
+export function saveCatalogCache(stateDir, catalog) {
+  const p = catalogCachePath(stateDir);
+  const tmp = `${p}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(catalog, null, 2), 'utf8');
+    fs.renameSync(tmp, p);
+    return true;
+  } catch {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    return false;
+  }
+}
+
+/**
+ * Fetches the latest models for a tool from its official endpoint or a custom URL.
+ * Never throws: falls back safely to baseline models if offline or unreachable.
+ */
+export async function fetchToolModels(tool, { url, apiKey, timeout = 3000 } = {}) {
+  const targetUrl = url || OFFICIAL_MODEL_URLS[tool];
+  if (!targetUrl) return { ok: false, error: `Unknown tool: ${tool}`, models: [] };
+
+  const headers = {
+    'user-agent': 'llm-switcher/catalog',
+    'accept': 'application/json'
+  };
+  if (tool === 'claude') {
+    headers['anthropic-version'] = '2023-06-01';
+    if (apiKey) headers['x-api-key'] = apiKey;
+  } else if (apiKey) {
+    headers['authorization'] = `Bearer ${apiKey}`;
+  }
+
+  try {
+    const res = await fetch(targetUrl, {
+      method: 'GET',
+      headers,
+      signal: AbortSignal.timeout(timeout)
+    });
+    if (!res.ok) {
+      return { ok: false, status: res.status, error: `HTTP ${res.status}`, models: [] };
+    }
+    const json = await res.json();
+    const rawList = Array.isArray(json.data) ? json.data : Array.isArray(json.models) ? json.models : [];
+
+    if (tool === 'claude') {
+      const models = rawList
+        .filter(m => m && (m.id || typeof m === 'string'))
+        .map(m => {
+          const id = typeof m === 'string' ? m : m.id;
+          return { id, display_name: m.display_name || id, tier: classifyClaudeTier(id) };
+        });
+      return { ok: true, models };
+    }
+
+    if (tool === 'codex') {
+      const models = rawList
+        .filter(m => m && (m.id || typeof m === 'string'))
+        .map(m => {
+          const id = typeof m === 'string' ? m : m.id;
+          return { id, role: classifyCodexRole(id) };
+        })
+        .filter(m => /^(gpt|o\d|codex)/i.test(m.id));
+      return { ok: true, models };
+    }
+
+    return { ok: true, models: rawList };
+  } catch (err) {
+    return { ok: false, error: err.message, models: [] };
+  }
+}
+
+/**
+ * Refreshes the local catalog cache with models from both official endpoints
+ * and saves to the state directory.
+ */
+export async function refreshCatalog(stateDir, { claudeKey, codexKey } = {}) {
+  const cache = loadCatalogCache(stateDir);
+
+  const [claudeRes, codexRes] = await Promise.all([
+    fetchToolModels('claude', { apiKey: claudeKey }),
+    fetchToolModels('codex', { apiKey: codexKey })
+  ]);
+
+  if (claudeRes.ok && claudeRes.models.length > 0) {
+    const existing = new Set(claudeRes.models.map(m => m.id));
+    // Keep any baseline models that might be absent from the API
+    for (const [tier, ids] of Object.entries(BASELINE_MODELS.claude)) {
+      for (const id of ids) {
+        if (!existing.has(id)) claudeRes.models.push({ id, tier });
+      }
+    }
+    cache.claude = { models: claudeRes.models };
+  }
+
+  if (codexRes.ok && codexRes.models.length > 0) {
+    const existing = new Set(codexRes.models.map(m => m.id));
+    for (const [role, ids] of Object.entries(BASELINE_MODELS.codex)) {
+      for (const id of ids) {
+        if (!existing.has(id)) codexRes.models.push({ id, role });
+      }
+    }
+    cache.codex = { models: codexRes.models };
+  }
+
+  cache.updatedAt = Date.now();
+  saveCatalogCache(stateDir, cache);
+  return cache;
+}
+
+/** Extracts tool version string from client User-Agent or headers */
+export function detectToolVersion(headers = {}, expectedTool) {
+  const ua = headers['user-agent'] || headers['User-Agent'] || '';
+  const first = String(ua || '').split(' ')[0];
+  const slash = first.indexOf('/');
+  if (slash >= 0) {
+    const prefix = first.slice(0, slash).toLowerCase();
+    if (prefix.includes('claude') || prefix.includes('codex') || (expectedTool && prefix.includes(expectedTool))) {
+      const version = first.slice(slash + 1);
+      if (/^\d{1,5}\.\d{1,5}/.test(version)) return version;
+    }
+  }
+  const m = /(?:claude(?:-cli|-code)?|codex(?:-cli)?)[/v\s]+([0-9]+\.[0-9]+(?:\.[0-9]+)?)/i.exec(ua);
+  return m ? m[1] : '';
+}
+
+const refreshingTools = new Set();
+
+/**
+ * Version-triggered auto-poll:
+ * When a request arrives with a new tool version not yet seen in cache,
+ * immediately records the new version and kicks off an asynchronous background refresh.
+ * Subsequent requests with the same version do zero network calls.
+ */
+export function checkVersionAndRefresh(tool, headers, stateDir, apiKey) {
+  const version = detectToolVersion(headers, tool);
+  if (!version) return;
+
+  const cache = loadCatalogCache(stateDir);
+  const toolEntry = cache[tool] || {};
+  const lastVersion = toolEntry.lastSeenVersion || '';
+
+  if (version !== lastVersion) {
+    toolEntry.lastSeenVersion = version;
+    cache[tool] = toolEntry;
+    saveCatalogCache(stateDir, cache);
+
+    if (!refreshingTools.has(tool)) {
+      refreshingTools.add(tool);
+      fetchToolModels(tool, { apiKey })
+        .then(res => {
+          if (res.ok && res.models.length > 0) {
+            const fresh = loadCatalogCache(stateDir);
+            const existing = new Set(res.models.map(m => m.id));
+            const baseline = BASELINE_MODELS[tool] || {};
+            for (const [, ids] of Object.entries(baseline)) {
+              for (const id of ids) {
+                if (!existing.has(id)) {
+                  res.models.push({ id, ...(tool === 'claude' ? { tier: classifyClaudeTier(id) } : { role: classifyCodexRole(id) }) });
+                }
+              }
+            }
+            fresh[tool] = { lastSeenVersion: version, models: res.models };
+            fresh.updatedAt = Date.now();
+            saveCatalogCache(stateDir, fresh);
+            console.log(`[llm-switcher:catalog] Detected ${tool} version update to ${version} -> refreshed model catalog (${res.models.length} models)`);
+          }
+        })
+        .catch(() => {})
+        .finally(() => {
+          refreshingTools.delete(tool);
+        });
+    }
+  }
+}

package/config.example.json

@@ -1,19 +1,19 @@
 {
   "port": 3456,
-  "activeProfile": "9router",
   "activeProfiles": {
-    "anthropic": "9router",
-    "responses": "example-codex-vertex",
-    "openai-chat": "9router",
-    "vertex": "example-codex-vertex"
+    "claude": "claude-default",
+    "codex": "codex-default"
+  },
+  "blindfold": {
+    "port": 3457
   },
   "profiles": {
-    "9router": {
-      "name": "9Router",
+    "claude-default": {
+      "name": "Claude default (Claude client -> router)",
       "mode": "convert",
-      "inFormat": "auto",
+      "tool": "claude",
       "outFormat": "openai-chat",
-      "baseURL": "https://YOUR-9ROUTER-HOST/v1",
+      "baseURL": "https://YOUR-ROUTER-HOST/v1",
       "apiKey": "sk-REPLACE-ME",
       "defaultModels": {
         "opus": "ag/claude-opus-4-6-thinking",
@@ -28,30 +28,10 @@
         "fable": true
       }
     },
-    "example-direct": {
-      "name": "Example Native Anthropic (Direct Forward)",
-      "mode": "direct",
-      "inFormat": "auto",
-      "outFormat": "anthropic",
-      "baseURL": "https://api.anthropic.com/v1",
-      "apiKey": "sk-ant-REPLACE-ME",
-      "defaultModels": {
-        "opus": "claude-opus-4-7",
-        "sonnet": "claude-sonnet-4-6",
-        "haiku": "claude-haiku-4-5-20251001",
-        "fable": "claude-haiku-4-5-20251001"
-      },
-      "model1M": {
-        "opus": false,
-        "sonnet": false,
-        "haiku": false,
-        "fable": false
-      }
-    },
-    "example-codex-vertex": {
-      "name": "Example Codex client -> Vertex upstream",
+    "codex-default": {
+      "name": "Codex default (Codex client -> Vertex upstream)",
       "mode": "convert",
-      "inFormat": "responses",
+      "tool": "codex",
       "outFormat": "vertex",
       "baseURL": "https://YOUR-VERTEX-GATEWAY/v1",
       "apiKey": "REPLACE-ME",
@@ -61,8 +41,6 @@
         "review": "gpt-5.6-terra",
         "subagent": "gpt-5.6-luna"
       },
-      "blindfold": false,
-      "blindfoldPort": 3457,
       "defaultModels": {
         "main": "gemini-3.8-flash",
         "review": "gemini-3.7-flash-medium",

package/docs/TOKEN-OPTIMIZER-INTEROP.md

@@ -1,110 +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.
+# 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

@@ -28,18 +28,25 @@ Blindfold mode does that. Codex keeps its official endpoint. The switcher interc
 
 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:
+The process answers the CONNECT itself. It ends the TLS session with a leaf certificate for the target host. One interceptor serves both tools: what each request reaches is decided by the host of the CONNECT request and by its path, and by nothing else.
 
-| Request | Destination |
+| CONNECT host | Destination |
 | --- | --- |
-| Target host, path under `/backend-api/codex/` | The local gateway |
-| Target host, any other path | The real host, over a new TLS session |
+| `api.anthropic.com`, path `/v1/messages` or under it | The local gateway, path unchanged |
+| `api.anthropic.com`, any other path | `api.anthropic.com`, over a new TLS session |
+| `api.openai.com`, path `/v1/responses` or `/v1/models` (or under them) | The local gateway, path unchanged |
+| `api.openai.com`, any other path | `api.openai.com`, over a new TLS session |
+| `chatgpt.com`, path `/backend-api/codex/` or under it | The local gateway, `/backend-api/codex` rewritten to `/v1` |
+| `chatgpt.com`, any other path | `chatgpt.com`, over a new TLS session |
 | Another public host | A raw tunnel. The process never reads the bytes. |
 | A local or private address | Refused. |
 
+There is no `--host` and no `--prefix` any more: this table is the routing, and it cannot be
+changed from a profile or from the command line.
+
 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.
+Sign-in, token refresh and the usage page keep working, because they do not use a path in the table. A request whose `Host` header names a different host than its CONNECT target gets `421 Misdirected Request` and opens no upstream connection.
 
 ## Why no system change is necessary
 
@@ -81,14 +88,17 @@ CAUTION: Do not build these certificates with `New-SelfSignedCertificate` in Pow
 
 ### 2. Turn on blindfold mode in the profile
 
-Add two keys to the Codex profile in `config.json`:
+Add the interceptor port at the top level of `config.json`, next to `port`:
 
 ```json
-"blindfold": true,
-"blindfoldPort": 3457
+"blindfold": { "port": 3457 }
 ```
 
-`blindfoldPort` is optional. The default is 3457.
+`blindfold.port` is optional. The default is 3457, and it must differ from the gateway port
+in `port`. There is no per-profile `blindfold`, `blindfoldPort`, `blindfoldHost` or
+`blindfoldPrefix` any more: the interceptor runs whenever at least one tool is active, and
+what it routes is the fixed host table in [`cross-platform.md`](cross-platform.md), not a
+profile setting.
 
 ### 3. Activate the profile
 
@@ -98,7 +108,7 @@ 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.
+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 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:
 
@@ -155,13 +165,14 @@ 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:
+Both tools are recorded by the same process, because one interceptor holds the whole
+table. To capture into a directory of your own, pass `--capture` to a second interceptor
+on a port of its own:
 
 ```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
+bash blindfold/make-certs.sh
+node blindfold/blindfold.mjs --port 3458 --gateway-port 3456 \
+  --certs blindfold/certs --capture ~/.llm-switcher/captures
 ```
 
 Use directories that you own. `make-certs.sh` and `--capture` refuse a directory that another
@@ -201,13 +212,13 @@ The switcher writes `LLM_SWITCHER_CODEX_BASE_URL` again, the gateway stops the i
 
 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.
+**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 name constraints: it can sign only for `api.anthropic.com`, `api.openai.com` and `chatgpt.com`. 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`.
+**Exactly three hosts are intercepted.** The leaf names `api.anthropic.com`, `api.openai.com` and `chatgpt.com`, so a Codex that signs in with an API key instead of a ChatGPT account reaches the gateway on `api.openai.com` with no reconfiguration. Any other host is tunneled without being read.
 
 **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.