llm-switcher 1.1.0

package/service.mjs

@@ -0,0 +1,132 @@
+// The text of each OS service definition that `switch service install` writes, and how the CLI
+// reads the port back. Pure functions, apart from writeServiceFile, so each one is testable here.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// A service does not inherit the installing shell. Without these it would read another config.json
+// or clean another settings.json than the shell that installed it.
+const SERVICE_ENV_KEYS = ['CLAUDE_CONFIG_DIR', 'LLM_SWITCHER_CONFIG', 'LLM_SWITCHER_STATE_DIR', 'LLM_SWITCHER_BLINDFOLD_CERTS'];
+
+export function serviceEnv(env = process.env) {
+  return SERVICE_ENV_KEYS.filter(k => env[k]).map(k => [k, env[k]]);
+}
+
+const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const systemdQuote = (s) => `"${String(s).replace(/(["\\])/g, '\\$1')}"`;
+
+export function systemdUnit({ nodeBin, script, port, env = [] }) {
+  return `[Unit]
+Description=LLM Switcher Local Gateway
+After=network.target
+
+[Service]
+ExecStart=${systemdQuote(nodeBin)} ${systemdQuote(script)} --port ${port}
+${env.map(([k, v]) => `Environment=${systemdQuote(`${k}=${v}`)}\n`).join('')}Restart=always
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function launchdPlist({ nodeBin, script, port, logPath, env = [] }) {
+  const envBlock = env.length
+    ? `  <key>EnvironmentVariables</key>
+  <dict>
+${env.map(([k, v]) => `    <key>${xmlEscape(k)}</key>\n    <string>${xmlEscape(v)}</string>`).join('\n')}
+  </dict>
+`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.llmswitcher.gateway</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(nodeBin)}</string>
+    <string>${xmlEscape(script)}</string>
+    <string>--port</string>
+    <string>${port}</string>
+  </array>
+${envBlock}  <key>StandardOutPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+
+// Task Scheduler reads the command and its arguments from two elements, so no path goes through
+// the quoting rules of a /TR command line. A task made with /TR also stops after 72 hours by
+// default; PT0S removes that limit.
+export function scheduledTaskXml({ nodeBin, script, port, userId }) {
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>LLM Switcher Local Gateway</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${xmlEscape(userId)}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${xmlEscape(userId)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xmlEscape(nodeBin)}</Command>
+      <Arguments>${xmlEscape(`"${script}" --port ${port}`)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+// schtasks prints /Query /XML as UTF-16 when its output is a pipe.
+export function decodeConsoleText(buf) {
+  if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) return buf.subarray(2).toString('utf16le');
+  if (buf.length >= 2 && buf[1] === 0x00) return buf.toString('utf16le');
+  return buf.toString('utf8');
+}
+
+/** The port on a service definition's command line, or null. */
+export function portFromServiceText(text) {
+  const flat = String(text).replace(/<\/?string>\s*/g, ' ');
+  const n = parseInt(/--port\s+(\d+)/.exec(flat)?.[1], 10);
+  return Number.isInteger(n) && n > 0 && n <= 65535 ? n : null;
+}
+
+/** Writes a service definition. Returns the backup path when it replaced different content. */
+export function writeServiceFile(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let backup = null;
+  try {
+    if (fs.readFileSync(file, 'utf8') !== content) {
+      backup = `${file}.bak`;
+      fs.copyFileSync(file, backup);
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  fs.writeFileSync(file, content, 'utf8');
+  return backup;
+}

package/shim.mjs

@@ -0,0 +1,292 @@
+// ============================================================
+// shim.mjs — auto-inject gateway env for CLIs launched outside the wrapper
+//
+// PROBLEM
+//   `switch on` writes env.sh and cleans ~/.claude/settings.json (so Claude Code doesn't
+//   show the "custom API" banner). Consequence: a `claude` session started from a shell
+//   that has NOT sourced env.sh will lack ANTHROPIC_BASE_URL and call
+//   api.anthropic.com directly — bypassing the gateway (loses Healer, 1M, pooled quota).
+//   Exactly the case of `claude --resume` reopening an old session in a clean shell.
+//
+// FIX
+//   Install executable shims into ~/.llm-switcher/bin/ (placed BEFORE the real binary
+//   in PATH). The shim sources env.sh then execs the real binary, so EVERY `claude`
+//   /`codex` invocation — including --resume, including from shells without env — goes
+//   through the gateway. Doesn't touch settings.json => no banner.
+//
+// SAFETY
+//   - The shim finds the real binary by removing the shim directory itself from PATH,
+//     so it never calls itself recursively.
+//   - If the gateway is OFF (no active.flag) the shim runs the real binary
+//     as-is — no forced routing, no blocking the user.
+//   - If the real binary isn't found, the shim reports a clear error instead of staying silent.
+// ============================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+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, '/');
+
+// 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
+# 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).
+SWITCHER_DIR="${STATE_DIR}"
+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"
+fi
+
+# Find the real binary: drop the shim directory from PATH so it doesn't call itself.
+CLEAN_PATH=""
+IFS=':'
+for p in $PATH; do
+  case "$p" in
+    "$SHIM_DIR"|"$SHIM_DIR"/) continue ;;
+  esac
+  [ -z "$p" ] && continue
+  if [ -z "$CLEAN_PATH" ]; then CLEAN_PATH="$p"; else CLEAN_PATH="$CLEAN_PATH:$p"; fi
+done
+unset IFS
+
+REAL="$(PATH="$CLEAN_PATH" command -v ${name} 2>/dev/null)"
+if [ -z "$REAL" ]; then
+  echo "[llm-switcher] cannot find the real '${name}' on PATH (\\$SHIM_DIR excluded)." >&2
+  echo "[llm-switcher] go shim: switch shim uninstall" >&2
+  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" "$@"`}
+`;
+
+const WINDOWS_TEMPLATE = (name) => `@echo off
+REM Auto-generated by LLM Switcher - DO NOT EDIT.
+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%"` : ''}
+for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
+  call "%%i" ${name === 'codex' ? '%CODEX_SWITCHER_ARGS% ' : ''}%*
+  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% ' : ''}%*
+  exit /b
+)
+echo [llm-switcher] cannot find the real '${name}' on PATH.>&2
+exit /b 127
+`;
+
+export function renderShim(name, platform = process.platform) {
+  return platform === 'win32' ? WINDOWS_TEMPLATE(name) : POSIX_TEMPLATE(name);
+}
+
+function shimPath(name) {
+  return path.join(SHIM_DIR, process.platform === 'win32' ? `${name}.cmd` : name);
+}
+
+/** Install shims for the CLIs. Returns {installed:[], skipped:[], error?} */
+export function installShims(names = SHIMMED) {
+  try {
+    fs.mkdirSync(SHIM_DIR, { recursive: true });
+  } catch (err) {
+    return { installed: [], skipped: [], error: `cannot create ${SHIM_DIR}: ${err.message}` };
+  }
+
+  const installed = [];
+  const skipped = [];
+  for (const name of names) {
+    const target = shimPath(name);
+    const body = renderShim(name);
+    try {
+      // Don't overwrite unfamiliar files created by the user.
+      if (fs.existsSync(target)) {
+        const cur = fs.readFileSync(target, 'utf8');
+        if (!cur.includes('Auto-generated by LLM Switcher')) {
+          skipped.push({ name, reason: 'a file that is not a switcher shim already exists there' });
+          continue;
+        }
+      }
+      fs.writeFileSync(target, body, 'utf8');
+      if (process.platform !== 'win32') fs.chmodSync(target, 0o755);
+      installed.push(name);
+    } catch (err) {
+      skipped.push({ name, reason: err.message });
+    }
+  }
+  return { installed, skipped };
+}
+
+export function uninstallShims(names = SHIMMED) {
+  const removed = [];
+  const failed = [];
+  for (const name of names) {
+    const target = shimPath(name);
+    try {
+      if (!fs.existsSync(target)) continue;
+      const cur = fs.readFileSync(target, 'utf8');
+      if (!cur.includes('Auto-generated by LLM Switcher')) continue;
+      fs.unlinkSync(target);
+      removed.push(name);
+    } catch (err) {
+      failed.push({ name, reason: err.message });
+    }
+  }
+  return { removed, failed };
+}
+
+/** Is SHIM_DIR already ahead of the real binary in PATH? */
+export function shimStatus(names = SHIMMED) {
+  const entries = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const idx = entries.findIndex(p => path.resolve(p) === path.resolve(SHIM_DIR));
+  const out = { dir: SHIM_DIR, onPath: idx !== -1, position: idx, shims: [] };
+
+  for (const name of names) {
+    const target = shimPath(name);
+    const exists = fs.existsSync(target);
+    let effective = null;   // which binary will run when the command name is typed
+    for (const p of entries) {
+      const cand = path.join(p, process.platform === 'win32' ? `${name}.cmd` : name);
+      const candExe = path.join(p, name);
+      if (fs.existsSync(cand)) { effective = cand; break; }
+      if (fs.existsSync(candExe)) { effective = candExe; break; }
+    }
+    out.shims.push({
+      name,
+      installed: exists,
+      effective,
+      active: exists && effective !== null && path.resolve(effective) === path.resolve(target)
+    });
+  }
+  return out;
+}
+
+/** Line to add to the shell rc so the shim comes before the real binary. */
+// Windows: setx truncates at 1024 characters and would copy the merged system+user PATH into the
+// user key, and PowerShell does not expand %PATH%. Prepend to the User-scope Path only.
+export function pathExportLine(platform = process.platform) {
+  if (platform === 'win32') {
+    return `powershell -NoProfile -Command "[Environment]::SetEnvironmentVariable('Path', '${SHIM_DIR};' + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')"`;
+  }
+  return `export PATH="${SHIM_DIR}:$PATH"`;
+}
+
+/** Which rc file to edit, based on the current shell. Windows has none: the command above is run once. */
+export function suggestedRcFiles(platform = process.platform) {
+  if (platform === 'win32') return [];
+  const home = os.homedir();
+  const shell = path.basename(process.env.SHELL || '');
+  if (shell === 'zsh') return [path.join(home, '.zshrc'), path.join(home, '.zprofile')];
+  if (shell === 'bash') return [path.join(home, '.bashrc'), path.join(home, '.bash_profile')];
+  return [path.join(home, '.profile')];
+}
+
+/**
+ * Check whether running CLI processes have the gateway env.
+ * This is the hardest failure to spot: a `claude` session opened BEFORE the gateway
+ * was enabled (or from a shell that hasn't sourced env.sh) will call api.anthropic.com
+ * directly. The shim intercepts NEW sessions, but live processes must be detected and reported so they can be restarted.
+ */
+// What in a process's command line and environment shows that it goes through the gateway.
+// Codex takes the gateway URL as a --config override, or the interceptor as HTTPS_PROXY.
+const ROUTE_EVIDENCE = {
+  claude: /(^|\s)ANTHROPIC_BASE_URL=/,
+  codex: /(^|\s)(LLM_SWITCHER_CODEX_BASE_URL=|https?_proxy=http:\/\/(127\.0\.0\.1|localhost)[:/]|openai_base_url=http:\/\/(127\.0\.0\.1|localhost)[:/])/i
+};
+
+/** true | false, or null when the dump holds no environment (macOS ps for most processes). */
+export function routeEvidence(name, envDump) {
+  // The shim's own `--config key=value` arguments look like variables; only the rest can be environment.
+  if (ROUTE_EVIDENCE[name].test(envDump)) return true;
+  const rest = envDump.replace(/(^|\s)(--config|-c)\s+\S+/g, ' ');
+  return /\s[A-Za-z_][A-Za-z0-9_]*=/.test(rest) ? false : null;
+}
+
+// `names` are the CLIs whose target is active: a CLI whose target is off uses the official endpoint
+// on purpose, so a missing gateway variable there is not a bypass.
+export function auditRunningProcesses(names = SHIMMED) {
+  if (process.platform === 'win32') return { supported: false, procs: [] };
+  const procs = [];
+  try {
+    // Get pid + command of the CLIs of interest (excluding the pgrep/grep command itself).
+    const pattern = names.join('|');
+    const listed = execFileSync('pgrep', ['-f', `(${pattern})`], { encoding: 'utf8' })
+      .split('\n').map(s => s.trim()).filter(Boolean);
+
+    for (const pid of listed) {
+      let cmd = '';
+      try {
+        cmd = execFileSync('ps', ['-p', pid, '-o', 'command='], { encoding: 'utf8' }).trim();
+      } catch { continue; }
+      if (!cmd) continue;
+      // Keep only processes that are actually the CLI under check, skip helper processes.
+      if (!names.some(n => new RegExp(`(^|/|\\s)${n}(\\s|$)`).test(cmd))) continue;
+      if (/pgrep|llm-switcher\/(switch|proxy)\.mjs/.test(cmd)) continue;
+
+      const name = names.find(n => new RegExp(`(^|/|\\s)${n}(\\s|$)`).test(cmd));
+      let hasEnv = null;  // null = cannot read that process's env
+      try {
+        // `ps eww` appends the environment, but only for processes this account may read.
+        hasEnv = routeEvidence(name, execFileSync('ps', ['eww', '-p', pid, '-o', 'command='], { encoding: 'utf8' }));
+      } catch {}
+      procs.push({ pid, name, cmd: cmd.slice(0, 90), hasEnv });
+    }
+  } catch {
+    // pgrep returns a non-zero exit code when there are no processes — not an error.
+  }
+  return { supported: true, procs };
+}
+
+export { paths };

package/skills/llm-switcher/SKILL.md

@@ -0,0 +1,88 @@
+---
+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.