llm-switcher 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — LLM Switcher
 
+## Release 1.2.2
+
+- **Structured output reaches every upstream:** A request that asks for JSON that matches a schema now keeps that schema. Before this release, the gateway did not read `output_config.format` (Claude Code) or `text.format` (Codex), so the provider got a free-text request. The schema now goes to the provider as `response_format` (OpenAI Chat), `output_config.format` (Anthropic), or `responseMimeType` with `responseSchema` (Gemini and Vertex). A request for JSON without a schema reaches Anthropic as plain text, because Anthropic has no JSON mode without a schema.
+
+## Release 1.2.1
+
+- **Intact Visual Architecture & Hash Routing:** Fully restructured dashboard using Intact design system, pure CSS tokens, and hash-based client routing (`#/routes`, `#/models`, `#/logs`, `#/doctor`).
+- **Official Brand Icon Assets:** Integrated official brand icons for Anthropic Claude, OpenAI Codex, Google Gemini, Intact, OpenRouter, and Ollama, served statically under `/icons/*` with immutable caching and PNG/SVG whitelisting.
+- **Prefetched Navigation Counters:** Navigation badges prefetch model discovery and request inspector counts immediately on page load, eliminating the delay where badges showed zero until the tab was selected.
+- **Hardened Profile Slot Mapping:** Synchronized Claude model tiers (`sonnet`, `opus`, `haiku`, `fable`) and Codex model roles (`main`, `review`, `subagent`), ensuring slot persistence when editing profiles and removing redundant role tabs for Claude-targeted profiles.
+- **CORS & Endpoint Fixes:** Added `x-llm-switcher-token` to preflight `Access-Control-Allow-Headers` and resolved routing precedence for `GET /api/catalog`.
+
 ## Release 1.2.0
 
 - **Zero-Mutation Interceptor Invariant:** The gateway now operates strictly in the network path via the blindfold interceptor, never modifying user configuration files like `~/.claude/settings.json` or `~/.codex/config.toml`. Loopback base URLs (`ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL`) are scrubbed by shims so traffic routes through `HTTPS_PROXY` cleanly.

package/classifier.mjs

@@ -0,0 +1,238 @@
+/**
+ * Jev-powered Semantic Classifier & Router for llm-switcher
+ * Evaluates prompt complexity using TypeSafe System One (Jev) models
+ * and maps intent to optimal model tier (haiku, sonnet, opus).
+ */
+
+export const DEFAULT_JEV_URL = 'https://api.typesafe.ai/v1/systemone';
+export const DEFAULT_JEV_MODEL = 'jev-latest';
+export const OPENROUTER_JEV_URL = 'https://openrouter.ai/api/alpha/decisions';
+export const OPENROUTER_JEV_MODEL = 'typesafe/jev-1.13';
+
+export const TIER_CRITERIA = {
+  haiku: 'Mechanical task, template fill, single fact lookup, extraction, binary decision, short formatting',
+  sonnet: 'Multi-step coding, refactor, search across files, general programming, document drafting',
+  opus: 'Architecture design, security analysis, deep reasoning, race conditions, migration plans, complex synthesis',
+};
+
+/**
+ * Fast synchronous heuristic fallback when offline or no API key is set.
+ */
+export function heuristicClassify(prompt = '') {
+  const text = String(prompt || '').toLowerCase();
+
+  // Heavy reasoning or safety critical indicators -> opus
+  const opusKeywords = [
+    'architecture', 'security audit', 'race condition', 'deadlock', 'concurrency',
+    'threat model', 'penetration', 'migration plan', 'adversarial', 'formal verification'
+  ];
+  if (opusKeywords.some((kw) => text.includes(kw))) {
+    return 'opus';
+  }
+
+  // Trivial or mechanical indicators -> haiku
+  const haikuKeywords = [
+    'translate', 'format json', 'extract', 'regex', 'rename', 'single word',
+    'yes or no', 'spell check', 'fix typo', 'convert to csv'
+  ];
+  if (text.length < 120 && haikuKeywords.some((kw) => text.includes(kw))) {
+    return 'haiku';
+  }
+
+  // Default balanced tier
+  return 'sonnet';
+}
+
+/**
+ * Resolves Jev API key from environment.
+ */
+export function findJevKey(env = process.env) {
+  if (typeof env?.TYPESAFE_API_KEY === 'string' && env.TYPESAFE_API_KEY.trim().length > 0) {
+    return { key: env.TYPESAFE_API_KEY.trim(), source: 'typesafe' };
+  }
+  if (typeof env?.JEV_API_KEY === 'string' && env.JEV_API_KEY.trim().length > 0) {
+    return { key: env.JEV_API_KEY.trim(), source: 'openrouter' };
+  }
+  return null;
+}
+
+/**
+ * Classifies prompt into optimal model tier using TypeSafe Jev.
+ * Falls back safely to heuristic on missing key, timeout, or network error.
+ */
+export async function classifyPrompt({
+  prompt,
+  apiKey,
+  url,
+  model,
+  timeoutMs = 5000,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const fallbackTier = heuristicClassify(prompt);
+
+  const keyInfo = apiKey ? { key: apiKey, source: 'custom' } : findJevKey(env);
+  if (!keyInfo) {
+    return {
+      tier: fallbackTier,
+      confidence: 0.5,
+      source: 'heuristic',
+      reason: 'no-key',
+    };
+  }
+
+  const endpointUrl = url || (keyInfo.source === 'openrouter' ? OPENROUTER_JEV_URL : DEFAULT_JEV_URL);
+  const modelName = model || (keyInfo.source === 'openrouter' ? OPENROUTER_JEV_MODEL : DEFAULT_JEV_MODEL);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const payload = {
+      state: String(prompt || ''),
+      model: modelName,
+      questions: {
+        recommended_tier: {
+          type: 'choice',
+          instructions: 'Determine the optimal model tier for this task according to complexity and reasoning depth required.',
+          criteria: TIER_CRITERIA,
+        },
+      },
+    };
+
+    const res = await fetchImpl(endpointUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${keyInfo.key}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      return {
+        tier: fallbackTier,
+        confidence: 0.5,
+        source: 'heuristic',
+        reason: `http-${res.status}`,
+      };
+    }
+
+    const data = await res.json();
+    const ans = data?.answers?.recommended_tier;
+    if (!ans || typeof ans.choice !== 'string') {
+      return {
+        tier: fallbackTier,
+        confidence: 0.5,
+        source: 'heuristic',
+        reason: 'bad-response',
+      };
+    }
+
+    const tier = ['haiku', 'sonnet', 'opus'].includes(ans.choice) ? ans.choice : fallbackTier;
+    const confidence = typeof ans.confidence === 'number' ? Number(ans.confidence.toFixed(3)) : 0.8;
+
+    return {
+      tier,
+      confidence,
+      distribution: ans.distribution || null,
+      source: 'jev',
+      model: data.model || modelName,
+    };
+  } catch (err) {
+    clearTimeout(timer);
+    const reason = err?.name === 'AbortError' ? 'timeout' : 'network';
+    return {
+      tier: fallbackTier,
+      confidence: 0.5,
+      source: 'heuristic',
+      reason,
+    };
+  }
+}
+
+/**
+ * Checks semantic equivalence between candidate text and cached target using Jev Noul.
+ * Optional gate: returns false immediately if Jev is not configured or unavailable.
+ */
+export async function checkSemanticEquivalence({
+  candidate,
+  target,
+  apiKey,
+  url,
+  model,
+  timeoutMs = 3000,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (!candidate || !target) return { equivalent: false, confidence: 0, reason: 'empty-input' };
+  if (candidate.trim() === target.trim()) {
+    return { equivalent: true, confidence: 1.0, reason: 'exact-match' };
+  }
+
+  const keyInfo = apiKey ? { key: apiKey, source: 'custom' } : findJevKey(env);
+  if (!keyInfo) {
+    return { equivalent: false, confidence: 0, reason: 'no-key-fallback-bypass' };
+  }
+
+  const endpointUrl = url || (keyInfo.source === 'openrouter' ? OPENROUTER_JEV_URL : DEFAULT_JEV_URL);
+  const modelName = model || (keyInfo.source === 'openrouter' ? OPENROUTER_JEV_MODEL : DEFAULT_JEV_MODEL);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const payload = {
+      state: `REQUEST_A:\n${candidate}\n\nREQUEST_B:\n${target}`,
+      model: modelName,
+      questions: {
+        is_equivalent: {
+          type: 'noul',
+          instructions: 'Do REQUEST_A and REQUEST_B ask for the exact same semantic task or answer, such that the response to B fully satisfies A?',
+        },
+      },
+    };
+
+    const res = await fetchImpl(endpointUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${keyInfo.key}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timer);
+    if (!res.ok) {
+      return { equivalent: false, confidence: 0, reason: `http-${res.status}` };
+    }
+
+    const data = await res.json();
+    const ans = data?.answers?.is_equivalent;
+    if (ans == null) {
+      return { equivalent: false, confidence: 0, reason: 'bad-response' };
+    }
+
+    // Noul returns either probability number directly or object with probability
+    const prob = typeof ans === 'number' ? ans : (typeof ans?.probability === 'number' ? ans.probability : 0);
+    const equivalent = prob >= 0.85;
+
+    return {
+      equivalent,
+      confidence: Number(prob.toFixed(3)),
+      reason: equivalent ? 'jev-confirmed' : 'below-threshold',
+      model: data.model || modelName,
+    };
+  } catch (err) {
+    clearTimeout(timer);
+    return {
+      equivalent: false,
+      confidence: 0,
+      reason: err?.name === 'AbortError' ? 'timeout' : 'network-error',
+    };
+  }
+}

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.