llm-switcher 1.2.11 → 1.3.0

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, the Antigravity CLI `agy`, 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>`, `switch codex <profile>` or `switch agy <profile>` instead. The
+  shims in `~/.llm-switcher/bin` inject the gateway variables into the tool process itself and
+  clear anything stale first. For `agy` the variable is `CLOUD_CODE_URL`, not a proxy.
+- `claude`, `codex` and `agy` 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 the Antigravity CLI).
+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

@@ -35,8 +35,8 @@ if (DATA_DIR !== ROOT_DIR) {
 const LEGACY_TARGET_TOOL = { anthropic: 'claude', responses: 'codex' };
 // Migration input only: the pointer keys an unmigrated config may still carry.
 const LEGACY_TARGETS = ['anthropic', 'responses', 'openai-chat', 'vertex'];
-export const TOOLS = ['claude', 'codex'];
-export const COMMAND_WORDS = new Set(['claude', 'codex', 'on', 'off', 'status', 'doctor', 'ui']);
+export const TOOLS = ['claude', 'codex', 'agy'];
+export const COMMAND_WORDS = new Set(['claude', 'codex', 'agy', 'on', 'off', 'status', 'doctor', 'ui']);
 export const DEFAULT_PORT = 3456;
 export const DEFAULT_BLINDFOLD_PORT = 3457;
 // Codex with ChatGPT sign-in calls https://chatgpt.com/backend-api/codex.
@@ -53,6 +53,9 @@ export const CLAUDE_MODEL_SLOTS = ['opus', 'sonnet', 'haiku', 'fable'];
 // - subagent <-> `agents.default_subagent_model` (spawned agents)
 // No fast/fallback in the docs — those are custom keys, read only for backward compatibility.
 export const CODEX_MODEL_SLOTS = ['main', 'review', 'subagent'];
+// The Antigravity CLI (agy) picks its own model per call. One slot names the upstream model of its
+// agent calls; a '*' in the value stands for the model id that agy sent (antigravity/* = Bifrost).
+export const AGY_MODEL_SLOTS = ['main'];
 export const CHAT_MODEL_SLOTS = ['default'];
 export const VERTEX_MODEL_SLOTS = ['default'];
 
@@ -134,10 +137,13 @@ export const paths = {
   envClaudeSh: path.join(STATE_DIR, 'env-claude.sh'),
   envCodexCmd: path.join(STATE_DIR, 'env-codex.cmd'),
   envCodexSh: path.join(STATE_DIR, 'env-codex.sh'),
+  envAgyCmd: path.join(STATE_DIR, 'env-agy.cmd'),
+  envAgySh: path.join(STATE_DIR, 'env-agy.sh'),
   // One line per tool, written with that tool's env file: what the launcher shows the person at
   // launch. Empty exactly when the tool is not routed, so the launcher needs no second condition.
   routeClaude: path.join(STATE_DIR, 'route-claude.txt'),
   routeCodex: path.join(STATE_DIR, 'route-codex.txt'),
+  routeAgy: path.join(STATE_DIR, 'route-agy.txt'),
   // The gateway port of the last switch on. The shim scrubs a stale loopback base URL
   // against it, so a shell opened before a port change still reaches the right gateway.
   gatewayPort: path.join(STATE_DIR, 'gateway.port'),
@@ -447,7 +453,7 @@ function createCodexHalf(p) {
 
 export function validateProfileInput(p) {
   if (!p || typeof p !== 'object' || Array.isArray(p)) return 'Profile must be an object';
-  if (p.inFormat !== undefined) return 'inFormat is not supported; use "tool": "claude" or "tool": "codex"';
+  if (p.inFormat !== undefined) return 'inFormat is not supported; use "tool": "claude", "codex" or "agy"';
   if (p.blindfold !== undefined) return 'blindfold per-profile setting is deprecated';
   if (p.blindfoldPort !== undefined) return 'blindfoldPort per-profile setting is deprecated';
   if (p.blindfoldHost !== undefined) return 'blindfoldHost per-profile setting is deprecated';
@@ -637,9 +643,15 @@ export function migrateConfigInMemory(rawConfig) {
   }
 
   // Step 3: Pointer migration (R7b, Item 2)
+  // A present pointer follows its profile through a Step 1 rename: a profile keyed "agy" became
+  // "agy-profile" when agy turned into a command word, and a pointer left on "agy" would dangle.
+  const presentPointer = (tool) => {
+    const v = rawConfig.activeProfiles[tool];
+    return v ? (renameMap.get(v) || v) : v;
+  };
   const newActiveProfiles = {};
   if (rawConfig.activeProfiles && Object.hasOwn(rawConfig.activeProfiles, 'claude')) {
-    newActiveProfiles.claude = rawConfig.activeProfiles.claude;
+    newActiveProfiles.claude = presentPointer('claude');
   } else {
     let oldClaudeTarget = null;
     if (rawConfig.activeProfiles && Object.hasOwn(rawConfig.activeProfiles, 'anthropic')) {
@@ -664,7 +676,7 @@ export function migrateConfigInMemory(rawConfig) {
   }
 
   if (rawConfig.activeProfiles && Object.hasOwn(rawConfig.activeProfiles, 'codex')) {
-    newActiveProfiles.codex = rawConfig.activeProfiles.codex;
+    newActiveProfiles.codex = presentPointer('codex');
   } else {
     let oldCodexTarget = null;
     if (rawConfig.activeProfiles && Object.hasOwn(rawConfig.activeProfiles, 'responses')) {
@@ -688,6 +700,11 @@ export function migrateConfigInMemory(rawConfig) {
     }
   }
 
+  // agy has no legacy key and no single-pointer fallback: only its own pointer, and only to a
+  // profile made for agy.
+  const agyKey = rawConfig.activeProfiles && Object.hasOwn(rawConfig.activeProfiles, 'agy') ? presentPointer('agy') : null;
+  newActiveProfiles.agy = agyKey && cfg.profiles[agyKey]?.tool === 'agy' ? agyKey : null;
+
   cfg.activeProfiles = newActiveProfiles;
   delete cfg.activeProfile;
 
@@ -993,6 +1010,8 @@ export function findProfileKey(cfg, name) {
 }
 
 export function profileAcceptsTarget(profile, target) {
+  // agy has no legacy spelling and no inFormat: only a profile made for it serves it.
+  if (target === 'agy') return profile?.tool === 'agy';
   if (profile?.tool) {
     if (target === 'claude' || target === 'anthropic') return profile.tool === 'claude';
     if (target === 'codex' || target === 'responses') return profile.tool === 'codex';
@@ -1008,6 +1027,7 @@ export function profileAcceptsTarget(profile, target) {
 export function modelSlotsForProfile(profile) {
   if (profile?.tool === 'claude') return CLAUDE_MODEL_SLOTS;
   if (profile?.tool === 'codex') return CODEX_MODEL_SLOTS;
+  if (profile?.tool === 'agy') return AGY_MODEL_SLOTS;
   return MODEL_SLOTS_BY_FORMAT[profile?.inFormat] || MODEL_SLOTS_BY_FORMAT.auto;
 }
 
@@ -1185,7 +1205,8 @@ export function getActiveMap(cfg) {
       : Object.hasOwn(ap, legacy) ? ap[legacy]
         : cfg?.activeProfile ?? null
   );
-  return { claude: pointer('claude', 'anthropic'), codex: pointer('codex', 'responses') };
+  // agy is newer than the single legacy pointer, so only its own key can turn it on.
+  return { claude: pointer('claude', 'anthropic'), codex: pointer('codex', 'responses'), agy: ap.agy ?? null };
 }
 
 /**
@@ -1325,7 +1346,11 @@ export function computeLaunchState(cfg, port) {
   const pick = (t) => (hasProfile(cfg, map[t]) ? cfg.profiles[map[t]] : null);
   const claude = pick('claude');
   const codex = pick('codex');
-  const active = Boolean(claude || codex);
+  const agy = pick('agy');
+  // The interceptor serves Claude Code and Codex only. agy takes its endpoint from CLOUD_CODE_URL, so
+  // an agy-only switch on writes the launch files and starts no interceptor.
+  const intercepted = Boolean(claude || codex);
+  const active = Boolean(intercepted || agy);
 
   // One interceptor serves both tools (R3) and its port lives at the top level of config.json
   // (R3b). The per-profile port went with the per-profile host and prefix.
@@ -1354,7 +1379,7 @@ export function computeLaunchState(cfg, port) {
     // and the tool set. The tool set travels sorted as one string (Finding 6), which is also what
     // lets a running interceptor be updated in place instead of restarted.
     // null when no tool is active, which is how reconcileBlindfold knows to stop it.
-    blindfold: active
+    blindfold: intercepted
       ? {
         port: bfPort,
         activeTools: deriveActiveTools(cfg).join(','),
@@ -1367,15 +1392,20 @@ export function computeLaunchState(cfg, port) {
     // of the other tool, and a restart cannot leave a stale override behind.
     envClaude: [],
     envCodex: [],
+    envAgy: [],
     // The launcher notice, one line per tool. Empty for a tool that is not routed (A1).
     routeClaude: claude ? routeLine('claude', map.claude, claude) : '',
-    routeCodex: codex ? routeLine('codex', map.codex, codex) : ''
+    routeCodex: codex ? routeLine('codex', map.codex, codex) : '',
+    routeAgy: agy ? routeLine('agy', map.agy, agy) : ''
   };
 
   // NODE_EXTRA_CA_CERTS is deliberately absent from env-claude: the shim decides it at launch,
   // because only then does it know whether the user brought a CA of their own (R2).
   if (claude) state.envClaude = proxyPairs();
   if (codex) state.envCodex = [...proxyPairs(), ['CODEX_CA_CERTIFICATE', paths.blindfoldCA]];
+  // agy reaches the gateway directly over plain http: no proxy and no CA (Go on Windows reads only
+  // the system store). Remote control keeps its own host, so it never crosses the switcher.
+  if (agy) state.envAgy = [['CLOUD_CODE_URL', `http://127.0.0.1:${port}`]];
   return state;
 }
 
@@ -1470,13 +1500,17 @@ function writeToolFiles(pairs, shPath, cmdPath) {
 // tools from activeProfiles, and a colliding config is one this build will not migrate. This empties
 // only the file pair of the tool that was switched off, under the same lock, so the other tool's
 // launcher files are never opened (A13: emptied, never deleted).
+const TOOL_FILES = {
+  claude: () => [paths.envClaudeCmd, paths.envClaudeSh, paths.routeClaude],
+  codex: () => [paths.envCodexCmd, paths.envCodexSh, paths.routeCodex],
+  agy: () => [paths.envAgyCmd, paths.envAgySh, paths.routeAgy]
+};
+
 export function emptyToolEnvFiles(tool) {
   const codex = tool === 'codex';
   const codexRouteChanged = withLaunchLock(() => {
     const before = codex ? readOrEmpty(paths.envCodexSh) : '';
-    writeAtomic(codex ? paths.envCodexCmd : paths.envClaudeCmd, '');
-    writeAtomic(codex ? paths.envCodexSh : paths.envClaudeSh, '');
-    writeAtomic(codex ? paths.routeCodex : paths.routeClaude, '');
+    for (const f of (TOOL_FILES[tool] || TOOL_FILES.claude)()) writeAtomic(f, '');
     return before !== '';
   });
   return { codexRouteChanged, codexDaemon: codexRouteChanged ? restartCodexDaemon([]) : undefined };
@@ -1544,9 +1578,12 @@ function writeLaunchState(cfg, port) {
   try {
     writeToolFiles(st.envClaude, paths.envClaudeSh, paths.envClaudeCmd);
     writeToolFiles(st.envCodex, paths.envCodexSh, paths.envCodexCmd);
+    writeToolFiles(st.envAgy, paths.envAgySh, paths.envAgyCmd);
     writeAtomic(paths.routeClaude, st.routeClaude ? `${st.routeClaude}
 ` : '');
     writeAtomic(paths.routeCodex, st.routeCodex ? `${st.routeCodex}
+` : '');
+    writeAtomic(paths.routeAgy, st.routeAgy ? `${st.routeAgy}
 ` : '');
     st.codexRouteChanged = readOrEmpty(paths.envCodexSh) !== codexBefore;
     // Recorded on switch on so a shell opened while the gateway ran can still recognize its own
@@ -1573,7 +1610,7 @@ export function clearLaunchState(port) {
     writeAtomic(paths.envCmd, STUB_CMD);
     writeAtomic(paths.envSh, STUB_SH);
     for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh,
-      paths.routeClaude, paths.routeCodex]) {
+      paths.envAgyCmd, paths.envAgySh, paths.routeClaude, paths.routeCodex, paths.routeAgy]) {
       writeAtomic(f, '');
     }
     return codexBefore !== '';

package/switch.cmd

@@ -1,2 +1,2 @@
-@echo off
-node "%~dp0switch.mjs" %*
+@echo off
+node "%~dp0switch.mjs" %*