llm-switcher 1.1.11 → 1.2.0

package/shim.mjs

@@ -26,33 +26,121 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { paths, STATE_DIR } from './state.mjs';
 
 export const SHIM_DIR = path.join(os.homedir(), '.llm-switcher', 'bin');
 
-// Local model catalog: generated by applyLaunchState from the active profile's
-// publicModels, so it holds official OpenAI slugs only. It gives Codex the metadata
-// for the names it requests (otherwise the CLI falls back to full-context mode) and
-// it is what the /model picker renders — the picker never calls /v1/models.
-// Forward slashes for the TOML value. The Windows `if exist` test uses the native path instead.
-export const CODE_X_CATALOG_PATH = paths.codexCatalog.replace(/\\/g, '/');
+// The shims hand the CA work to Node: reading files, comparing content and renaming atomically
+// has no place in a shell script, and none at all in cmd.exe. It is a FILE rather than
+// `node -e`, so neither cmd.exe quoting nor URL encoding can corrupt it: pathToFileURL turns a
+// space in the checkout into %20, which cmd.exe then reads as the (undefined) argument %2.
+const STATE_HELPER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'ensure-ca-bundle.mjs');
 
 // CLIs to wrap. `claude` is the most important case (--resume), codex included for completeness.
 export const SHIMMED = ['claude', 'codex'];
 
-const POSIX_TEMPLATE = (name) => `#!/usr/bin/env bash
+// One tool, one env file. Sourcing the shared one is how one tool used to capture the other.
+const envFileOf = (name) => (name === 'codex' ? 'env-codex.sh' : 'env-claude.sh');
+
+const POSIX_TEMPLATE = (name) => {
+  const envFile = envFileOf(name);
+  const caBlock = name === 'codex' ? '' : `
+# R2: one bundle holds the user's own CA and the switcher CA, so trusting the interceptor never
+# costs a certificate the user already had. Decided here, at launch, because only now is it known
+# whether the user brought one — and never while this tool is off.
+if [ "$TOOL_ACTIVE" = "1" ]; then
+  if [ -z "$INHERITED_CA" ]; then
+    if [ -f "$SWITCHER_DIR/blindfold/certs/ca.pem" ]; then
+      export NODE_EXTRA_CA_CERTS="$SWITCHER_DIR/blindfold/certs/ca.pem"
+    else
+      echo "[llm-switcher] $SWITCHER_DIR/blindfold/certs/ca.pem not found; NODE_EXTRA_CA_CERTS kept as inherited." >&2
+    fi
+  else
+    CA_BUNDLE="$(node "$STATE_HELPER" "$INHERITED_CA" "$SWITCHER_DIR/blindfold/certs/ca.pem" "$SWITCHER_DIR")" || CA_BUNDLE=""
+    if [ -n "$CA_BUNDLE" ] && [ -f "$CA_BUNDLE" ]; then
+      export NODE_EXTRA_CA_CERTS="$CA_BUNDLE"
+    fi
+  fi
+fi`;
+  return `#!/usr/bin/env bash
 # Auto-generated by LLM Switcher — DO NOT EDIT.
-# Load the gateway env then run the real "${name}", even when the shell hasn't sourced env.sh
-# (e.g.: claude --resume reopening an old session in a clean terminal).
+# Hand THIS tool its own gateway env, scrub what an older switcher left behind, then run the real
+# "${name}", from any shell — including one that never sourced anything (claude --resume).
 SWITCHER_DIR="${STATE_DIR}"
+STATE_HELPER="${STATE_HELPER}"
 SHIM_DIR="\${BASH_SOURCE%/*}"
 
-# Only load env when the gateway is on; when off, let the CLI run as-is. The shim runs what env.sh says,
-# so the directory and the file must belong to this account: another one could have created them.
-if [ -O "$SWITCHER_DIR" ] && [ -O "$SWITCHER_DIR/env.sh" ] && [ -f "$SWITCHER_DIR/active.flag" ]; then
-  . "$SWITCHER_DIR/env.sh"
+# Captured BEFORE the tool's env file is sourced: the CA decision must see the value this shell
+# already had, not one this run is about to write.
+INHERITED_CA="\${NODE_EXTRA_CA_CERTS:-}"
+
+# Only this tool's own file, only while the gateway is on, and only files this account owns:
+# another account could have created the directory or the file. Non-empty means the tool runs;
+# an empty file means it is off, and then nothing is sourced at all.
+if [ -O "$SWITCHER_DIR" ] && [ -O "$SWITCHER_DIR/${envFile}" ] && [ -f "$SWITCHER_DIR/active.flag" ] && [ -s "$SWITCHER_DIR/${envFile}" ]; then
+  . "$SWITCHER_DIR/${envFile}"
+  TOOL_ACTIVE=1
+else
+  TOOL_ACTIVE=0
+fi
+
+# R8: a variable is removed ONLY when its value is one an older switcher wrote. The user's own
+# proxy, base URL, model or LLM_SWITCHER_* setting is theirs and is kept.
+GW_PORT="$( { [ -O "$SWITCHER_DIR/gateway.port" ] && tr -d '[:space:]' < "$SWITCHER_DIR/gateway.port"; } 2>/dev/null )"
+case "$GW_PORT" in ''|*[!0-9]*) GW_PORT=3456 ;; esac
+PORTS="$GW_PORT 3456"
+[ -n "$LLM_SWITCHER_PORT" ] && PORTS="$PORTS $LLM_SWITCHER_PORT"
+
+# Every loopback shape the switcher ever wrote: host, optional /v1, optional trailing slash.
+SWITCHER_URLS=""
+for _p in $PORTS; do
+  for _h in 127.0.0.1 localhost '[::1]'; do
+    SWITCHER_URLS="$SWITCHER_URLS $_h:$_p $_h:$_p/ $_h:$_p/v1 $_h:$_p/v1/"
+  done
+done
+
+_u="\${ANTHROPIC_BASE_URL:-}"
+if [ -n "$_u" ]; then
+  case " $SWITCHER_URLS " in
+    *" \${_u#http://} "*) unset ANTHROPIC_BASE_URL ;;
+  esac
+fi
+_u="\${OPENAI_BASE_URL:-}"
+if [ -n "$_u" ]; then
+  case " $SWITCHER_URLS " in
+    *" \${_u#http://} "*) unset OPENAI_BASE_URL ;;
+  esac
 fi
 
+# The suffix the old switcher forced on every tier. Nothing else matches: the user's own
+# ANTHROPIC_MODEL=opus, or a real model id, is theirs.
+case "\${ANTHROPIC_MODEL:-}" in
+  opus\\[1m\\]|sonnet\\[1m\\]|haiku\\[1m\\]|fable\\[1m\\]) unset ANTHROPIC_MODEL ;;
+esac
+tier_is_stale() {
+  [ -n "$1" ] || return 1
+  case "$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" in
+    "$2"\\[1m\\]) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+if tier_is_stale "$ANTHROPIC_DEFAULT_OPUS_MODEL" opus; then unset ANTHROPIC_DEFAULT_OPUS_MODEL; fi
+if tier_is_stale "$ANTHROPIC_DEFAULT_SONNET_MODEL" sonnet; then unset ANTHROPIC_DEFAULT_SONNET_MODEL; fi
+if tier_is_stale "$ANTHROPIC_DEFAULT_HAIKU_MODEL" haiku; then unset ANTHROPIC_DEFAULT_HAIKU_MODEL; fi
+if tier_is_stale "$ANTHROPIC_DEFAULT_FABLE_MODEL" fable; then unset ANTHROPIC_DEFAULT_FABLE_MODEL; fi
+
+[ "\${CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT:-}" = "1" ] && unset CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT
+[ "\${CLAUDE_CODE_AUTO_COMPACT_WINDOW:-}" = "900000" ] && unset CLAUDE_CODE_AUTO_COMPACT_WINDOW
+[ "\${OPENAI_MAX_CONTEXT_TOKENS:-}" = "1000000" ] && unset OPENAI_MAX_CONTEXT_TOKENS
+
+# LLM_SWITCHER_CODEX_* was always a shim input, never the user's. Every OTHER LLM_SWITCHER_*
+# name is a user setting and is kept.
+for _v in $(compgen -v LLM_SWITCHER_CODEX_ 2>/dev/null); do
+  unset "$_v"
+done
+${caBlock}
+
 # Find the real binary: drop the shim directory from PATH so it doesn't call itself.
 CLEAN_PATH=""
 IFS=':'
@@ -72,65 +160,120 @@ if [ -z "$REAL" ]; then
   exit 127
 fi
 
-${name === 'codex' ? `# Codex-only variables (blindfold proxy + CA). The claude shim must not load these.
-if [ -O "$SWITCHER_DIR" ] && [ -O "$SWITCHER_DIR/env-codex.sh" ] && [ -f "$SWITCHER_DIR/active.flag" ]; then
-  . "$SWITCHER_DIR/env-codex.sh"
-fi
-
-CODEX_SWITCHER_ARGS=()
-if [ -n "\${LLM_SWITCHER_CODEX_BASE_URL:-}" ]; then
-  CODEX_SWITCHER_ARGS+=(--config "openai_base_url=\${LLM_SWITCHER_CODEX_BASE_URL}")
-fi
-if [ -O "${CODE_X_CATALOG_PATH}" ]; then
-  CODEX_SWITCHER_ARGS+=(--config "model_catalog_json=${CODE_X_CATALOG_PATH}")
-fi
-if [ -n "\${LLM_SWITCHER_CODEX_MAIN_MODEL:-}" ]; then
-  CODEX_SWITCHER_ARGS+=(--config "model=\\"\${LLM_SWITCHER_CODEX_MAIN_MODEL}\\"")
-fi
-if [ -n "\${LLM_SWITCHER_CODEX_REVIEW_MODEL:-}" ]; then
-  CODEX_SWITCHER_ARGS+=(--config "review_model=\\"\${LLM_SWITCHER_CODEX_REVIEW_MODEL}\\"")
-fi
-if [ -n "\${LLM_SWITCHER_CODEX_SUBAGENT_MODEL:-}" ]; then
-  CODEX_SWITCHER_ARGS+=(--config "agents.default_subagent_model=\\"\${LLM_SWITCHER_CODEX_SUBAGENT_MODEL}\\"")
-fi
-if [ -n "\${LLM_SWITCHER_CODEX_CONTEXT_WINDOW:-}" ]; then
-  CODEX_SWITCHER_ARGS+=(--config "model_context_window=\${LLM_SWITCHER_CODEX_CONTEXT_WINDOW}")
-fi
-if [ -n "\${LLM_SWITCHER_CODEX_AUTO_COMPACT_LIMIT:-}" ]; then
-  CODEX_SWITCHER_ARGS+=(--config "model_auto_compact_token_limit=\${LLM_SWITCHER_CODEX_AUTO_COMPACT_LIMIT}")
-fi
-
-exec "$REAL" "\${CODEX_SWITCHER_ARGS[@]}" "$@"` : `exec "$REAL" "$@"`}
+# No override of any kind: the tool keeps its own configuration and its own model names (F3, R1).
+exec "$REAL" "$@"
 `;
+};
 
-const WINDOWS_TEMPLATE = (name) => `@echo off
+const WINDOWS_TEMPLATE = (name) => {
+  const envFile = envFileOf(name).replace(/\.sh$/, '.cmd');
+  const caBlock = name === 'codex' ? '' : `
+REM R2: one bundle holds the user's own CA and the switcher CA, so trusting the interceptor
+REM never costs a certificate the user already had. Decided here, at launch, because only now
+REM is it known whether the user brought one - and never while this tool is off.
+if not "%TOOL_ACTIVE%"=="1" goto :CA_DONE
+if defined INHERITED_CA goto :CA_BUNDLE
+if exist "%SWITCHER_DIR%\\blindfold\\certs\\ca.pem" set "NODE_EXTRA_CA_CERTS=%SWITCHER_DIR%\\blindfold\\certs\\ca.pem"
+if not exist "%SWITCHER_DIR%\\blindfold\\certs\\ca.pem" echo [llm-switcher] %SWITCHER_DIR%\\blindfold\\certs\\ca.pem not found; NODE_EXTRA_CA_CERTS kept as inherited. 1>&2
+goto :CA_DONE
+:CA_BUNDLE
+set "CA_BUNDLE="
+for /f "delims=" %%B in ('node "%STATE_HELPER%" "%INHERITED_CA%" "%SWITCHER_DIR%\\blindfold\\certs\\ca.pem" "%SWITCHER_DIR%" 2^>nul') do set "CA_BUNDLE=%%B"
+if not defined CA_BUNDLE goto :CA_DONE
+if not exist "%CA_BUNDLE%" goto :CA_DONE
+set "NODE_EXTRA_CA_CERTS=%CA_BUNDLE%"
+:CA_DONE`;
+  return `@echo off
 REM Auto-generated by LLM Switcher - DO NOT EDIT.
+setlocal
 set "SWITCHER_DIR=${STATE_DIR}"
-if exist "%SWITCHER_DIR%\\active.flag" if exist "%SWITCHER_DIR%\\env.cmd" call "%SWITCHER_DIR%\\env.cmd"
-${name === 'codex' ? `REM Codex-only variables (blindfold proxy + CA). The claude shim must not load these.
-if exist "%SWITCHER_DIR%\\active.flag" if exist "%SWITCHER_DIR%\\env-codex.cmd" call "%SWITCHER_DIR%\\env-codex.cmd"
-set "CODEX_SWITCHER_ARGS="
-if defined LLM_SWITCHER_CODEX_BASE_URL set "CODEX_SWITCHER_ARGS=%CODEX_SWITCHER_ARGS% --config openai_base_url=%LLM_SWITCHER_CODEX_BASE_URL%"
-if exist "%SWITCHER_DIR%\\model-catalog.json" set "CODEX_SWITCHER_ARGS=%CODEX_SWITCHER_ARGS% --config model_catalog_json=${CODE_X_CATALOG_PATH}"
-if defined LLM_SWITCHER_CODEX_MAIN_MODEL set "CODEX_SWITCHER_ARGS=%CODEX_SWITCHER_ARGS% --config model=%LLM_SWITCHER_CODEX_MAIN_MODEL%"
-if defined LLM_SWITCHER_CODEX_REVIEW_MODEL set "CODEX_SWITCHER_ARGS=%CODEX_SWITCHER_ARGS% --config review_model=%LLM_SWITCHER_CODEX_REVIEW_MODEL%"
-if defined LLM_SWITCHER_CODEX_SUBAGENT_MODEL set "CODEX_SWITCHER_ARGS=%CODEX_SWITCHER_ARGS% --config agents.default_subagent_model=%LLM_SWITCHER_CODEX_SUBAGENT_MODEL%"
-if defined LLM_SWITCHER_CODEX_CONTEXT_WINDOW set "CODEX_SWITCHER_ARGS=%CODEX_SWITCHER_ARGS% --config model_context_window=%LLM_SWITCHER_CODEX_CONTEXT_WINDOW%"
-if defined LLM_SWITCHER_CODEX_AUTO_COMPACT_LIMIT set "CODEX_SWITCHER_ARGS=%CODEX_SWITCHER_ARGS% --config model_auto_compact_token_limit=%LLM_SWITCHER_CODEX_AUTO_COMPACT_LIMIT%"` : ''}
+${name === 'codex' ? '' : `set "STATE_HELPER=${STATE_HELPER}"
+
+REM Captured BEFORE the tool's env file runs: the CA decision must see the value this shell
+REM already had, not one this run is about to write.
+set "INHERITED_CA=%NODE_EXTRA_CA_CERTS%"
+`}
+
+REM Only this tool's own file, only while the gateway is on, and only a non-empty one: an empty
+REM file means this tool is off. The shared env.cmd is never called (F5).
+set "TOOL_ACTIVE=0"
+if exist "%SWITCHER_DIR%\\active.flag" if exist "%SWITCHER_DIR%\\${envFile}" (
+  for %%A in ("%SWITCHER_DIR%\\${envFile}") do if %%~zA GTR 0 set "TOOL_ACTIVE=1"
+)
+if "%TOOL_ACTIVE%"=="1" call "%SWITCHER_DIR%\\${envFile}"
+
+REM R8: a variable is removed ONLY when its value is one an older switcher wrote. The user's own
+REM proxy, base URL, model or LLM_SWITCHER_* setting is theirs and is kept.
+set "_GWPORT="
+if exist "%SWITCHER_DIR%\\gateway.port" for /f "usebackq delims=" %%P in ("%SWITCHER_DIR%\\gateway.port") do set "_GWPORT=%%P"
+if not defined _GWPORT set "_GWPORT=3456"
+if defined ANTHROPIC_BASE_URL call :SCRUB_URL ANTHROPIC_BASE_URL "%ANTHROPIC_BASE_URL%"
+if defined OPENAI_BASE_URL call :SCRUB_URL OPENAI_BASE_URL "%OPENAI_BASE_URL%"
+if /i "%ANTHROPIC_MODEL%"=="opus[1m]" set "ANTHROPIC_MODEL="
+if /i "%ANTHROPIC_MODEL%"=="sonnet[1m]" set "ANTHROPIC_MODEL="
+if /i "%ANTHROPIC_MODEL%"=="haiku[1m]" set "ANTHROPIC_MODEL="
+if /i "%ANTHROPIC_MODEL%"=="fable[1m]" set "ANTHROPIC_MODEL="
+if defined ANTHROPIC_DEFAULT_OPUS_MODEL call :SCRUB_TIER ANTHROPIC_DEFAULT_OPUS_MODEL "%ANTHROPIC_DEFAULT_OPUS_MODEL%" opus
+if defined ANTHROPIC_DEFAULT_SONNET_MODEL call :SCRUB_TIER ANTHROPIC_DEFAULT_SONNET_MODEL "%ANTHROPIC_DEFAULT_SONNET_MODEL%" sonnet
+if defined ANTHROPIC_DEFAULT_HAIKU_MODEL call :SCRUB_TIER ANTHROPIC_DEFAULT_HAIKU_MODEL "%ANTHROPIC_DEFAULT_HAIKU_MODEL%" haiku
+if defined ANTHROPIC_DEFAULT_FABLE_MODEL call :SCRUB_TIER ANTHROPIC_DEFAULT_FABLE_MODEL "%ANTHROPIC_DEFAULT_FABLE_MODEL%" fable
+if "%CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT%"=="1" set "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT="
+if "%CLAUDE_CODE_AUTO_COMPACT_WINDOW%"=="900000" set "CLAUDE_CODE_AUTO_COMPACT_WINDOW="
+if "%OPENAI_MAX_CONTEXT_TOKENS%"=="1000000" set "OPENAI_MAX_CONTEXT_TOKENS="
+for /f "tokens=1 delims==" %%V in ('set LLM_SWITCHER_CODEX_ 2^>nul ^| findstr /b /c:"LLM_SWITCHER_CODEX_"') do set "%%V="
+${caBlock}
+
+REM Find the real binary: drop this shim's own directory so it never calls itself.
 for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
-  call "%%i" ${name === 'codex' ? '%CODEX_SWITCHER_ARGS% ' : ''}%*
+  call "%%i" %*
   exit /b
 )
 for /f "delims=" %%i in ('where ${name}.exe 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
-  call "%%i" ${name === 'codex' ? '%CODEX_SWITCHER_ARGS% ' : ''}%*
+  call "%%i" %*
   exit /b
 )
 echo [llm-switcher] cannot find the real '${name}' on PATH.>&2
 exit /b 127
+
+REM ---- R8 subroutines ----------------------------------------------------
+
+REM %1 = variable name, %2 = its value. Unsets %1 only for a loopback gateway URL on a port this
+REM switcher has used: the recorded one, the default 3456, or LLM_SWITCHER_PORT.
+:SCRUB_URL
+set "_T=%~2"
+if /i "%_T:~0,7%"=="http://" set "_T=%_T:~7%"
+set "_R="
+if /i "%_T:~0,10%"=="127.0.0.1:" set "_R=%_T:~10%"
+if /i "%_T:~0,10%"=="localhost:" set "_R=%_T:~10%"
+if /i "%_T:~0,6%"=="[::1]:" set "_R=%_T:~6%"
+if not defined _R goto :eof
+if /i "%_R:~-4%"=="/v1/" set "_R=%_R:~0,-4%"
+if /i "%_R:~-3%"=="/v1" set "_R=%_R:~0,-3%"
+if "%_R:~-1%"=="/" set "_R=%_R:~0,-1%"
+if not defined _R goto :eof
+if not "%_R%"=="" for /f "delims=0123456789" %%X in ("%_R%") do goto :eof
+if "%_R%"=="%_GWPORT%" goto :DROP_URL
+if "%_R%"=="3456" goto :DROP_URL
+if defined LLM_SWITCHER_PORT if "%_R%"=="%LLM_SWITCHER_PORT%" goto :DROP_URL
+goto :eof
+:DROP_URL
+set "%~1="
+goto :eof
+
+REM %1 = variable name, %2 = its value, %3 = the lowercase tier it must still match. A value of
+REM another tier (ANTHROPIC_DEFAULT_OPUS_MODEL=sonnet[1m]) is not the switcher's and is kept.
+:SCRUB_TIER
+if /i "%~2"=="%~3[1m]" set "%~1="
+goto :eof
 `;
+};
 
 export function renderShim(name, platform = process.platform) {
-  return platform === 'win32' ? WINDOWS_TEMPLATE(name) : POSIX_TEMPLATE(name);
+  if (platform !== 'win32') return POSIX_TEMPLATE(name);
+  // cmd.exe finds a subroutine by scanning line starts, and on a file written with bare LF
+  // it drifts: a label near the end is reported as "cannot find the batch label". CRLF is
+  // what every .cmd on disk already is, and it is what cmd.exe expects.
+  return WINDOWS_TEMPLATE(name).replace(/\r?\n/g, '\r\n');
 }
 
 function shimPath(name) {

package/skills/llm-switcher/SKILL.md

@@ -1,88 +1,93 @@
----
-name: llm-switcher
-description: Mandatory guidance for AI coding agents and token compression tools (Headroom, RTK, Ponytail, Repomix). Enforces routing all LLM traffic through the local LLM Switcher edge gateway (http://127.0.0.1:3456) instead of directly calling provider endpoints.
----
-
-# LLM Switcher Edge Gateway Skill
-
-This skill governs how AI coding agents (Claude Code, Codex, Cursor, Windsurf, Opencode) and prompt optimization/compression tools (Headroom, RTK, Ponytail, Repomix) must interact with LLM providers on this workstation.
-
-## 1. The Core Directive
-
-> **ALL OUTBOUND LLM REQUESTS MUST ROUTE THROUGH LLM SWITCHER (`http://127.0.0.1:3456`).**
-> 
-> Never configure any tool, script, sub-agent, or token compression proxy to call external provider endpoints directly (such as `https://api.anthropic.com`, `https://api.openai.com`, or `https://generativelanguage.googleapis.com`).
->
-> If a token compression tool (Headroom, RTK, Ponytail) is used, it MUST be positioned as an **inner processing layer**, and its **upstream destination MUST be configured to point to LLM Switcher** at `http://127.0.0.1:3456`.
-
-```
-[Client CLI / Agent]
-         │
-         ▼
-[Token Compressor: RTK / Headroom / Ponytail]  <-- Inner Layer
-         │
-         ▼ (MANDATORY: Upstream MUST point to http://127.0.0.1:3456)
-[LLM Switcher Edge Gateway (:3456)]            <-- Outermost Gatekeeper
-         │
-         ▼ (Heals schemas, maps 1M context, extracts thinking, converts protocol)
-[Internet / 9Router / Upstream LLM]
-```
-
-## 2. Why This is Mandatory
-
-Direct outbound calls from token compressors will break the developer environment for several reasons:
-
-1. **Schema Breakage & The Healer Engine:**
-   Token optimizers frequently prune conversation history to save tokens. In doing so, they often delete an `assistant` turn containing a `tool_use`, while leaving the subsequent `user` turn containing a `tool_result`.
-   - Anthropic and OpenAI APIs strictly reject this with `HTTP 400 (orphaned tool_use_id)`.
-   - **LLM Switcher** intercepts these malformed requests and runs its **Healer Engine**, automatically converting orphaned results into safe context text blocks and merging consecutive same-role turns so upstream providers accept the payload cleanly.
-2. **Thinking / Reasoning Protection:**
-   Many token compressors naively strip `thinking` parameters or reasoning budgets to reduce token count.
-   - When routed through LLM Switcher, the gateway detects reasoning models (such as `ag/claude-opus-4-6-thinking` or `ag/gemini-3.8-flash`) and **automatically restores thinking parameters**, ensuring the model retains its full reasoning capabilities.
-3. **1M Context Window Unlocking:**
-   LLM Switcher dynamically injects `ANTHROPIC_DEFAULT_<TIER>_MODEL=<tier>[1m]` for every tier the profile marks 1M and calculates auto-compact thresholds (`900,000` tokens) without mutating permanent settings.
-4. **Centralized Gateway Connection (9Router):**
-   LLM Switcher connects directly to server-side gateways like **9Router**, which manage multi-account pooling, quota tracking, load balancing, and rate-limit retries far better than any local tool.
-
-## 3. Configuring Token Compression Tools
-
-When setting up or assisting the user with token compression tools, apply these exact configurations:
-
-### A. Headroom (Prompt Compression Proxy)
-When configuring Headroom's upstream endpoint:
-- In Headroom config (`headroom.yaml` or environment variables):
-  ```bash
-  ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
-  OPENAI_BASE_URL="http://127.0.0.1:3456/v1"
-  ```
-- Point your CLI to Headroom's listening port (e.g. `http://127.0.0.1:8787`). Headroom compresses the prompt and forwards it to LLM Switcher on port `3456`.
-
-### B. RTK (Rust Token Killer / Repomix)
-- In RTK configuration or execution flags:
-  ```bash
-  # Ensure RTK's target upstream proxy is LLM Switcher
-  export UPSTREAM_URL="http://127.0.0.1:3456"
-  ```
-
-### C. Ponytail / Custom Proxies
-- Always set the proxy's upstream host to:
-  `http://127.0.0.1:3456` (or `http://127.0.0.1:3456/v1` for OpenAI-compatible tools).
-
-### D. Sub-Agents & Spawned Terminal Commands
-When an agent spawns sub-processes via `bash` or terminal execution that call LLM CLIs:
-- **On Windows:** Always run `call "path\to\llm-switcher\env.cmd"` first.
-- **On macOS / Linux:** Always run `source "path/to/llm-switcher/env.sh"` first.
-- This prevents sub-agents from leaking calls directly to expensive official APIs.
-
-## 4. Operational Rules for AI Agents
-
-1. **NEVER edit `~/.claude/settings.json` directly.**
-   LLM Switcher uses zero-mutation launcher flags (`active.flag`, `1m.flag`). Writing custom base URLs or auth tokens into `settings.json` triggers warning banners in Claude Code and risks breaking the user's official subscription. Use `switch` CLI commands instead.
-2. **Check Gateway Health Before Complex Operations:**
-   Run `switch status` or call the `switcher_audit` MCP tool to confirm:
-   - LLM Switcher is active on port `3456`.
-   - The active profile matches the intended CLI target (Claude Code, Codex, or OpenAI).
-3. **Verify Routing When Errors Occur:**
-   If a tool fails with `HTTP 400`, `HTTP 502`, or connection errors:
-   - Run `switch doctor` to audit port collisions and environment variables.
-   - Inspect recent request logs via `http://127.0.0.1:3456/ui` (Tab 4: Live Inspector) to see if an intermediary tool mangled the payload.
+---
+name: llm-switcher
+description: Mandatory guidance for AI coding agents and token compression tools (Headroom, RTK, Ponytail, Repomix). Enforces routing all LLM traffic through the local LLM Switcher edge gateway (http://127.0.0.1:3456) instead of directly calling provider endpoints.
+---
+
+# LLM Switcher Edge Gateway Skill
+
+This skill governs how AI coding agents (Claude Code, Codex, Cursor, Windsurf, Opencode) and prompt optimization/compression tools (Headroom, RTK, Ponytail, Repomix) must interact with LLM providers on this workstation.
+
+## 1. The Core Directive
+
+> **ALL OUTBOUND LLM REQUESTS MUST ROUTE THROUGH LLM SWITCHER (`http://127.0.0.1:3456`).**
+> 
+> Never configure any tool, script, sub-agent, or token compression proxy to call external provider endpoints directly (such as `https://api.anthropic.com`, `https://api.openai.com`, or `https://generativelanguage.googleapis.com`).
+>
+> If a token compression tool (Headroom, RTK, Ponytail) is used, it MUST be positioned as an **inner processing layer**, and its **upstream destination MUST be configured to point to LLM Switcher** at `http://127.0.0.1:3456`.
+
+```
+[Client CLI / Agent]
+         │
+         ▼
+[Token Compressor: RTK / Headroom / Ponytail]  <-- Inner Layer
+         │
+         ▼ (MANDATORY: Upstream MUST point to http://127.0.0.1:3456)
+[LLM Switcher Edge Gateway (:3456)]            <-- Outermost Gatekeeper
+         │
+         ▼ (Heals schemas, maps 1M context, extracts thinking, converts protocol)
+[Internet / intact (Recommended) / 9Router / Upstream LLM]
+```
+
+## 2. Why This is Mandatory
+
+Direct outbound calls from token compressors will break the developer environment for several reasons:
+
+1. **Schema Breakage & The Healer Engine:**
+   Token optimizers frequently prune conversation history to save tokens. In doing so, they often delete an `assistant` turn containing a `tool_use`, while leaving the subsequent `user` turn containing a `tool_result`.
+   - Anthropic and OpenAI APIs strictly reject this with `HTTP 400 (orphaned tool_use_id)`.
+   - **LLM Switcher** intercepts these malformed requests and runs its **Healer Engine**, automatically converting orphaned results into safe context text blocks and merging consecutive same-role turns so upstream providers accept the payload cleanly.
+2. **Thinking / Reasoning Protection:**
+   Many token compressors naively strip `thinking` parameters or reasoning budgets to reduce token count.
+   - When routed through LLM Switcher, the gateway detects reasoning models (such as `ag/claude-opus-4-6-thinking` or `ag/gemini-3.8-flash`) and **automatically restores thinking parameters**, ensuring the model retains its full reasoning capabilities.
+3. **Official Context Windows & Dynamic Model Discovery:**
+   Context windows follow the model you select without mutating permanent settings. The gateway auto-discovers official models from Anthropic and OpenAI, refreshing mappings on tool version upgrades (`switch models`).
+4. **Server Gateway Synergy (intact / 9Router):**
+   LLM Switcher pairs directly with server-side gateways like **intact** (strongly recommended for credential proxying, account pooling, and contract lab self-healing) or 9Router, handling retries and quotas far better than any local tool.
+
+## 3. Configuring Token Compression Tools
+
+When setting up or assisting the user with token compression tools, apply these exact configurations:
+
+### A. Headroom (Prompt Compression Proxy)
+When configuring Headroom's upstream endpoint:
+- In Headroom config (`headroom.yaml` or environment variables):
+  ```bash
+  ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
+  OPENAI_BASE_URL="http://127.0.0.1:3456/v1"
+  ```
+- Point your CLI to Headroom's listening port (e.g. `http://127.0.0.1:8787`). Headroom compresses the prompt and forwards it to LLM Switcher on port `3456`.
+
+### B. RTK (Rust Token Killer / Repomix)
+- In RTK configuration or execution flags:
+  ```bash
+  # Ensure RTK's target upstream proxy is LLM Switcher
+  export UPSTREAM_URL="http://127.0.0.1:3456"
+  ```
+
+### C. Ponytail / Custom Proxies
+- Always set the proxy's upstream host to:
+  `http://127.0.0.1:3456` (or `http://127.0.0.1:3456/v1` for OpenAI-compatible tools).
+
+### D. Sub-Agents & Spawned Terminal Commands
+When an agent spawns sub-processes that call LLM CLIs:
+- **Never advise sourcing `env.sh` or `env.cmd`.** Those files carry no proxy variables any
+  more, so sourcing one changes nothing — and a stale variable an older version once wrote
+  would still point the tool at a port where nothing listens.
+- Run `switch claude <profile>` or `switch codex <profile>` instead. The shims in
+  `~/.llm-switcher/bin` inject the proxy variables into the tool process itself and clear
+  anything stale first.
+- `claude` and `codex` on `PATH` already are those shims: invoke them normally, and never
+  wrap them in another script.
+
+## 4. Operational Rules for AI Agents
+
+1. **NEVER edit `~/.claude/settings.json` directly.**
+   LLM Switcher uses zero-mutation launcher flags (`active.flag`). Writing custom base URLs or auth tokens into `settings.json` triggers warning banners in Claude Code and risks breaking the user's official subscription. Use `switch` CLI commands instead.
+2. **Check Gateway Health Before Complex Operations:**
+   Run `switch status` or call the `switcher_audit` MCP tool to confirm:
+   - LLM Switcher is active on port `3456`.
+   - The active profile matches the intended CLI target (Claude Code, Codex, or OpenAI).
+3. **Verify Routing When Errors Occur:**
+   If a tool fails with `HTTP 400`, `HTTP 502`, or connection errors:
+   - Run `switch doctor` to audit port collisions and environment variables.
+   - Inspect recent request logs via `http://127.0.0.1:3456/ui` (Tab 4: Live Inspector) to see if an intermediary tool mangled the payload.