llm-switcher 1.2.0 → 1.2.3

package/formats.mjs

@@ -19,6 +19,7 @@
 //   params: { maxTokens, temperature, topP, topK, stop[],
 //             presencePenalty?, frequencyPenalty? },
 //   thinking: { type:'enabled'|'disabled'|'adaptive', budget?, effort? } | null,
+//   responseFormat: { type:'json_object' } | { type:'json_schema', name?, schema, strict? } | null,
 //   stream: bool
 // }
 // ============================================================
@@ -327,10 +328,23 @@ function baseIR() {
   return {
     model: '', system: '', messages: [], tools: [], toolChoice: null,
     params: { maxTokens: null, temperature: null, topP: null, topK: null, stop: [] },
-    thinking: null, stream: false
+    thinking: null, responseFormat: null, stream: false
   };
 }
 
+// Structured output (Anthropic output_config.format, Responses text.format) -> IR responseFormat.
+// `text` asks for nothing.
+function responseFormatIR(f) {
+  if (!f || typeof f !== 'object') return null;
+  if (f.type === 'json_object') return { type: 'json_object' };
+  if (f.type !== 'json_schema') return null;
+  if (!f.schema || typeof f.schema !== 'object') return { type: 'json_object' };
+  const out = { type: 'json_schema', schema: f.schema };
+  if (typeof f.name === 'string' && f.name) out.name = f.name;
+  if (typeof f.strict === 'boolean') out.strict = f.strict;
+  return out;
+}
+
 // Anthropic Messages API -> IR (logic ported from the old transformAnthropicToOpenAI).
 function anthropicToIR(payload) {
   const ir = baseIR();
@@ -423,6 +437,7 @@ function anthropicToIR(payload) {
   if (Array.isArray(payload.stop_sequences)) ir.params.stop = stopList(payload.stop_sequences);
 
   ir.thinking = thinkingFromAnthropicParam(payload.thinking, payload.output_config?.effort);
+  ir.responseFormat = responseFormatIR(payload.output_config?.format || payload.output_format);
   return ir;
 }
 
@@ -644,6 +659,7 @@ function responsesToIR(payload) {
   if (payload.reasoning && typeof payload.reasoning === 'object') {
     ir.thinking = thinkingFromReasoningParam(payload.reasoning);
   }
+  ir.responseFormat = responseFormatIR(payload.text?.format);
   return ir;
 }
 
@@ -822,6 +838,13 @@ function irToChatBody(ir, model, opts = {}) {
   if (typeof ir.params.frequencyPenalty === 'number') body.frequency_penalty = ir.params.frequencyPenalty;
   if (ir.params.stop.length) body.stop = ir.params.stop;
   if (ir.params.parallelToolCalls === false && body.tools) body.parallel_tool_calls = false;
+  if (ir.responseFormat?.type === 'json_schema') {
+    const js = { name: ir.responseFormat.name || 'response', schema: ir.responseFormat.schema };
+    if (typeof ir.responseFormat.strict === 'boolean') js.strict = ir.responseFormat.strict;
+    body.response_format = { type: 'json_schema', json_schema: js };
+  } else if (ir.responseFormat?.type === 'json_object') {
+    body.response_format = { type: 'json_object' };
+  }
 
   if (wantsThinking && mode === 'native') {
     body.reasoning_effort = ir.thinking?.effort && !['max', 'xhigh'].includes(ir.thinking.effort)
@@ -941,6 +964,8 @@ function irToAnthropicBody(ir, model) {
   if (typeof ir.params.topP === 'number') body.top_p = ir.params.topP;
   if (typeof ir.params.topK === 'number') body.top_k = ir.params.topK;
   if (ir.params.stop.length) body.stop_sequences = ir.params.stop;
+  // Anthropic has no JSON mode without a schema.
+  if (ir.responseFormat?.type === 'json_schema') body.output_config = { format: { type: 'json_schema', schema: ir.responseFormat.schema } };
   if (ir.thinking && ir.thinking.type === 'adaptive') {
     body.thinking = { type: 'adaptive' };
   } else if (ir.thinking && ir.thinking.type !== 'disabled' && body.max_tokens > 1024) {
@@ -1062,6 +1087,10 @@ function irToVertexBody(ir, model) {
       gc.thinkingConfig.thinkingBudget = clampBudget(ir.thinking.budget ?? (ir.thinking.effort ? effortToBudget(ir.thinking.effort) : 2048));
     }
   }
+  if (ir.responseFormat) {
+    gc.responseMimeType = 'application/json';
+    if (ir.responseFormat.type === 'json_schema') gc.responseSchema = toGeminiSchema(ir.responseFormat.schema);
+  }
   if (Object.keys(gc).length) body.generationConfig = gc;
   return body;
 }

package/icons/intact.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><defs><linearGradient id="lg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#7c6cf6"/><stop offset="1" stop-color="#2dd4bf"/></linearGradient></defs><rect width="32" height="32" rx="9" fill="url(#lg)"/><path d="M16 6.5 24 9.6v6.1c0 5-3.4 8.6-8 10-4.6-1.4-8-5-8-10V9.6Z" fill="none" stroke="#fff" stroke-width="2.2" stroke-linejoin="round"/><path d="m12.4 16.2 2.6 2.6 4.8-5" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/mcp.mjs

@@ -143,11 +143,11 @@ async function handleToolCall(name, args) {
   const port = getMcpPort();
 
   if (name === 'switcher_models') {
-    const { loadCatalogCache, refreshCatalog } = await import('./catalog.mjs');
+    const { syncLocalCatalog, refreshCatalog } = await import('./catalog.mjs');
     if (args?.refresh) {
       await refreshCatalog(STATE_DIR);
     }
-    const cache = loadCatalogCache(STATE_DIR);
+    const cache = syncLocalCatalog(STATE_DIR);
     const t = args?.tool?.toLowerCase();
     const res = {};
     if (!t || t === 'claude') res.claude = cache.claude;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.2.0",
+  "version": "1.2.3",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code, Codex, OpenAI and Gemini clients",
   "keywords": [
     "llm",

package/proxy.mjs

@@ -23,7 +23,8 @@ import {
   codexModelEntry, smallestWindows, publicModelWindows, model1MForSlot,
   contractLabSettings, STATE_DIR
 } from './state.mjs';
-import { classifyCodexRole, classifyClaudeTier, loadCatalogCache, refreshCatalog, checkVersionAndRefresh } from './catalog.mjs';
+import { classifyCodexRole, classifyClaudeTier, syncLocalCatalog, refreshCatalog, checkVersionAndRefresh } from './catalog.mjs';
+import { checkForUpdate } from './version.mjs';
 import { createContractLab, createHalfTap, tapClientWrites, capText, capJson, toolVersionFromUA, finishHalf, PROBE_HEADER, TRACE_ID_RE } from './contract.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -1018,15 +1019,6 @@ function validateProfileInput(p) {
       if (name !== '' && !isSafeModelName(name)) return `Invalid codexRoles.${slot} value "${name}"`;
     }
   }
-  if (p.blindfoldPort !== undefined && p.blindfoldPort !== '' && !parsePort(p.blindfoldPort)) {
-    return `Invalid blindfoldPort "${p.blindfoldPort}"`;
-  }
-  if (p.blindfoldHost !== undefined && p.blindfoldHost !== '' && !/^[A-Za-z0-9.-]{1,253}$/.test(p.blindfoldHost)) {
-    return `Invalid blindfoldHost "${p.blindfoldHost}"`;
-  }
-  if (p.blindfoldPrefix !== undefined && p.blindfoldPrefix !== '' && !/^\/[A-Za-z0-9._~/-]{0,200}$/.test(p.blindfoldPrefix)) {
-    return `Invalid blindfoldPrefix "${p.blindfoldPrefix}"`;
-  }
   return null;
 }
 
@@ -1118,11 +1110,32 @@ async function route(req, res) {
     res.writeHead(204, {
       'Access-Control-Allow-Origin': req.headers.origin || `http://127.0.0.1:${PORT}`,
       'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-      'Access-Control-Allow-Headers': 'Content-Type, Authorization'
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-llm-switcher-token'
     });
     return res.end();
   }
 
+  // Serve static tool icons (cached, immutable, strictly image/png and image/svg+xml)
+  if (method === 'GET' && pathname.startsWith('/icons/')) {
+    const iconName = path.basename(pathname);
+    if (!/\.(png|svg)$/i.test(iconName)) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      return res.end('Icon not found');
+    }
+    const iconPath = path.join(__dirname, 'icons', iconName);
+    if (fs.existsSync(iconPath)) {
+      const ext = path.extname(iconName).toLowerCase();
+      const contentType = ext === '.svg' ? 'image/svg+xml' : 'image/png';
+      res.writeHead(200, {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=604800, immutable'
+      });
+      return fs.createReadStream(iconPath).pipe(res);
+    }
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    return res.end('Icon not found');
+  }
+
   // Serve Web UI (no-cache: always serve the latest version after file edits)
   if (method === 'GET' && (pathname === '/' || pathname === '/ui')) {
     if (fs.existsSync(uiHtmlPath)) {
@@ -1275,6 +1288,15 @@ async function routeApi(req, res, method, pathname) {
     return sendJson(res, 200, { logs: requestLogs.slice().reverse() });
   }
 
+  if (method === 'GET' && pathname === '/api/version') {
+    return sendJson(res, 200, await checkForUpdate({ stateDir: STATE_DIR }));
+  }
+
+  // GET /api/catalog (Dynamic Model Discovery)
+  if (method === 'GET' && pathname === '/api/catalog') {
+    return sendJson(res, 200, syncLocalCatalog(STATE_DIR));
+  }
+
   if (method !== 'POST') {
     req.resume();
     return sendJson(res, 404, { error: `Not found: ${method} ${pathname}` });
@@ -1287,21 +1309,13 @@ async function routeApi(req, res, method, pathname) {
     return sendJson(res, err.status || 400, { error: err.message });
   }
 
-  // GET /api/catalog
-  if (method === 'GET' && pathname === '/api/catalog') {
-    return sendJson(res, 200, loadCatalogCache(STATE_DIR));
-  }
-
   // POST /api/catalog/refresh
   if (method === 'POST' && pathname === '/api/catalog/refresh') {
     const active = getActiveMap(requireConfig(res) || {});
     const cfg = requireConfig(res) || {};
     const claudeProfile = active.claude ? cfg.profiles?.[active.claude] : null;
     const codexProfile = active.codex ? cfg.profiles?.[active.codex] : null;
-    const updated = await refreshCatalog(STATE_DIR, {
-      claudeKey: claudeProfile?.apiKey,
-      codexKey: codexProfile?.apiKey
-    });
+    const updated = await refreshCatalog(STATE_DIR, { claudeProfile, codexProfile });
     return sendJson(res, 200, { success: true, catalog: updated });
   }
 

package/scripts/run-tests.mjs

@@ -15,5 +15,7 @@ const files = [];
   }
 })(path.join(root, 'tests'));
 
-const r = spawnSync(process.execPath, ['--test', ...process.argv.slice(2), ...files], { cwd: root, stdio: 'inherit' });
+// A version check must never reach the real npm registry.
+const env = { ...process.env, LLM_SWITCHER_REGISTRY_URL: 'http://127.0.0.1:9/' };
+const r = spawnSync(process.execPath, ['--test', ...process.argv.slice(2), ...files], { cwd: root, stdio: 'inherit', env });
 process.exit(r.status ?? 1);

package/skills/llm-switcher/SKILL.md

@@ -1,93 +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 / 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.
+---
+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.

package/state.mjs

@@ -1441,26 +1441,78 @@ function writeToolFiles(pairs, shPath, cmdPath) {
 // launcher files are never opened (A13: emptied, never deleted).
 export function emptyToolEnvFiles(tool) {
   const codex = tool === 'codex';
-  withLaunchLock(() => {
+  const codexRouteChanged = withLaunchLock(() => {
+    const before = codex ? readOrEmpty(paths.envCodexSh) : '';
     writeAtomic(codex ? paths.envCodexCmd : paths.envClaudeCmd, '');
     writeAtomic(codex ? paths.envCodexSh : paths.envClaudeSh, '');
+    return before !== '';
   });
+  return { codexRouteChanged, codexDaemon: codexRouteChanged ? restartCodexDaemon([]) : undefined };
 }
 
 // Write the per-tool env files from activeProfiles. settings.json is never touched here: it
 // belongs to the coding tool (R1), and model-catalog.json is no longer written (R9).
 export function applyLaunchState(cfg, port, opts = {}) {
-  return withLaunchLock(() => writeLaunchState(cfg, port, opts));
+  const st = withLaunchLock(() => writeLaunchState(cfg, port, opts));
+  if (st.codexRouteChanged) st.codexDaemon = restartCodexDaemon(st.envCodex);
+  return st;
+}
+
+const LOOPBACK_URL = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?\/?$/i;
+
+/**
+ * The interactive Codex TUI talks to a shared `codex app-server` daemon, and the daemon keeps the
+ * environment it started with. A new route reaches it only through a restart. Only the launch files
+ * that the installed codex shim reads can route that daemon, so any other state dir (tests) is a no-op.
+ */
+export function restartCodexDaemon(pairs, {
+  home = os.homedir(),
+  codexHome = process.env.CODEX_HOME || path.join(home, '.codex'),
+  stateDir = STATE_DIR,
+  baseEnv = process.env,
+  ca = paths.blindfoldCA,
+  spawnFn = spawn
+} = {}) {
+  let shim = '';
+  try { shim = fs.readFileSync(path.join(home, '.llm-switcher', 'bin', 'codex'), 'utf8'); } catch {}
+  if (!shim.includes(`SWITCHER_DIR="${stateDir}"`)) return { restarted: false, reason: 'the codex shim does not read this state dir' };
+  const bin = path.join(codexHome, 'packages', 'app-server-daemon', 'current', 'bin', 'codex');
+  // The socket is a link to the running daemon; it no longer resolves once the daemon stopped.
+  if (!fs.existsSync(bin) || !fs.existsSync(path.join(codexHome, 'app-server-control', 'app-server-control.sock'))) {
+    return { restarted: false, reason: 'no Codex daemon runs' };
+  }
+
+  // Remove only the values this switcher writes (R8); a proxy or CA the user set stays.
+  const env = { ...baseEnv };
+  for (const k of ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']) if (LOOPBACK_URL.test(env[k] || '')) delete env[k];
+  for (const k of ['NO_PROXY', 'no_proxy']) if (env[k] === '127.0.0.1,localhost') delete env[k];
+  if (env.CODEX_CA_CERTIFICATE === ca) delete env.CODEX_CA_CERTIFICATE;
+  for (const [k, v] of pairs) env[k] = v;
+
+  try {
+    const child = spawnFn(bin, ['app-server', 'daemon', 'restart'], { env, stdio: 'ignore', detached: true });
+    child.on?.('error', () => {});
+    child.unref?.();
+    return { restarted: true };
+  } catch (err) {
+    return { restarted: false, reason: err.message };
+  }
+}
+
+function readOrEmpty(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return ''; }
 }
 
 function writeLaunchState(cfg, port) {
   const st = computeLaunchState(cfg, port);
+  const codexBefore = readOrEmpty(paths.envCodexSh);
 
   // Env files first, the flag last: a flag that says "active" while a file is missing or stale
   // makes the launcher route with the wrong variables. A failed write leaves the flag as it was.
   try {
     writeToolFiles(st.envClaude, paths.envClaudeSh, paths.envClaudeCmd);
     writeToolFiles(st.envCodex, paths.envCodexSh, paths.envCodexCmd);
+    st.codexRouteChanged = readOrEmpty(paths.envCodexSh) !== codexBefore;
     // Recorded on switch on so a shell opened while the gateway ran can still recognize its own
     // stale loopback URL later, after the port changed (R8).
     if (st.active) writeAtomic(paths.gatewayPort, `${port}\n`);
@@ -1476,7 +1528,8 @@ function writeLaunchState(cfg, port) {
 }
 
 export function clearLaunchState(port) {
-  withLaunchLock(() => {
+  const codexRouteChanged = withLaunchLock(() => {
+    const codexBefore = readOrEmpty(paths.envCodexSh);
     writeOrRemove(paths.activeFlag, null);
     // Stubs rather than deletions, and the tool files emptied rather than removed (R8, A13):
     // `switch off claude` must leave an empty claude file behind, and bare `switch off` must
@@ -1486,9 +1539,10 @@ export function clearLaunchState(port) {
     for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh]) {
       writeAtomic(f, '');
     }
+    return codexBefore !== '';
   });
   // settings.json belongs to the coding tool: the switcher neither reads nor writes it (R1).
-  return { changed: false, removed: [] };
+  return { changed: false, removed: [], codexRouteChanged, codexDaemon: codexRouteChanged ? restartCodexDaemon([]) : undefined };
 }
 
 export function readLaunchFlags() {

package/switch.mjs

@@ -26,6 +26,12 @@ const proxyScript = path.join(ROOT_DIR, 'proxy.mjs');
 const proxyLogPath = paths.proxyLog;
 const userProfile = os.homedir();
 
+// The version needs no config.json: it must also answer before the first setup.
+if (['version', '--version', '-v'].includes(String(process.argv[2] || '').toLowerCase())) {
+  await showVersion();
+  process.exit(0);
+}
+
 const config = loadConfig();
 if (!config) {
   const err = getConfigLoadError();
@@ -415,6 +421,7 @@ async function turnOn(profileName, cliTarget) {
   const savedBytes = fs.readFileSync(configPath);
   const st = applyLaunchState(planned, port);
   reportSettings(st.settings);
+  reportCodexDaemon(st);
   const bf = await requestBlindfoldSync(port);
   if (!bf.ok) {
     console.error(`[Error] ${bf.error}`);
@@ -520,7 +527,7 @@ async function turnOff(targetArg) {
       // The order is fixed by R7b: the CAS write, then this tool's env files, then the active-tools
       // update. If the CAS write cannot land, the env file and the interceptor stay untouched.
       const saved = casOff([target]);
-      emptyToolEnvFiles(target);
+      reportCodexDaemon(emptyToolEnvFiles(target));
       const bf = await syncOrStopBlindfold(port, config);
       if (!bf.ok) {
         console.error(`[Error] ${target} is switched back, but the interceptor is not in line: ${bf.error}`);
@@ -534,6 +541,7 @@ async function turnOff(targetArg) {
     saveConfig(config);
     const st = applyLaunchState(config, port);
     reportSettings(st.settings);
+    reportCodexDaemon(st);
     const bf = await syncOrStopBlindfold(port, config);
     if (!bf.ok) {
       console.error(`[Error] ${target} is switched back, but the blindfold interceptor is not in line: ${bf.error}`);
@@ -581,6 +589,12 @@ function auditActiveClis() {
 function reportSettings(result) {
   if (result?.removed?.length) console.log(`[settings.json] Removed switcher-written values: ${result.removed.join(', ')}`);
   if (result?.error) console.warn(`[settings.json] Not cleaned: ${result.error}`);
+  reportCodexDaemon(result);
+}
+
+// The interactive Codex TUI keeps using its shared daemon, so a new route needs that daemon restarted.
+function reportCodexDaemon(st) {
+  if (st?.codexDaemon?.restarted) console.log('[Codex] Restarted the codex app-server daemon: open Codex sessions reconnect with the new route.');
 }
 
 async function showStatus() {
@@ -848,7 +862,7 @@ async function runDoctor() {
     const p = config.profiles[key];
     if (!p) warn(`[WARN] Target ${t} points to missing profile "${show(key)}".`);
     else if (!p.baseURL || /YOUR-|REPLACE-ME/i.test(`${p.baseURL} ${p.apiKey}`)) warn(`[WARN] Profile "${show(key)}" (${t}) still has placeholder baseURL/apiKey.`);
-    if (p && t === 'responses') {
+    if (p && t === 'codex') {
       const codexWarning = codexPublicModelsWarning(show(key), p);
       if (codexWarning) warn(`[WARN] ${codexWarning}`);
     }
@@ -1036,13 +1050,22 @@ async function runContractCheck() {
   }
 }
 
+async function showVersion() {
+  const { checkForUpdate } = await import('./version.mjs');
+  const v = await checkForUpdate({ stateDir: STATE_DIR });
+  console.log(`llm-switcher ${v.current}`);
+  if (v.updateAvailable) console.log(`A new version is available: ${v.latest}. Update with: ${v.updateCommand}`);
+  else if (!v.latest) console.log('Could not check the npm registry for a newer version.');
+  else console.log('This is the latest version.');
+}
+
 async function showModels(target) {
-  const { loadCatalogCache, refreshCatalog } = await import('./catalog.mjs');
+  const { syncLocalCatalog, refreshCatalog } = await import('./catalog.mjs');
   if (optionValue('--refresh') || process.argv.includes('--refresh')) {
     console.log('Refreshing models catalog from official endpoints...');
     await refreshCatalog(STATE_DIR);
   }
-  const cache = loadCatalogCache(STATE_DIR);
+  const cache = syncLocalCatalog(STATE_DIR);
   console.log('=== LLM Switcher Discovered Models Catalog ===\n');
   const t = target ? target.toLowerCase() : '';
   if (!t || t === 'claude') {
@@ -1105,6 +1128,7 @@ if (cmd === 'off' || cmd === 'stop') {
   console.log('Usage:');
   console.log('  switch ui                      # Open Web UI dashboard');
   console.log('  switch status                  # Show multi-CLI active status');
+  console.log('  switch version                 # Show the version and check for a newer one');
   console.log('  switch doctor                  # Audit environment, settings & routing');
   console.log('  switch on [profile]            # Start gateway & activate profile for all compatible targets');
   console.log('  switch <profile>               # Activate profile for all compatible targets');