llm-switcher 1.3.1 → 1.3.3

package/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+# The shims and the blindfold certificates have one code path per platform, and a test for a
+# platform skips itself everywhere else. Only a run on each platform proves all of them.
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Node ${{ matrix.node }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    # A local run takes about 2 minutes. A hang must fail the job, not hold it for 6 hours.
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node: [22]
+        include:
+          # The lowest version that package.json accepts.
+          - os: ubuntu-latest
+            node: 18
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node }}
+          package-manager-cache: false
+      - run: npm test

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog — LLM Switcher
 
+## Release 1.3.3
+
+- **agy runs behind a relay:** A routed agy no longer gets the gateway port. The shim starts it behind `agy-relay.mjs`, which holds its own loopback port for as long as agy runs. For each connection, the relay asks the gateway for its identity proof on the same socket and sends agy's request only after the proof holds. Before, the shim checked the gateway only at launch, so a gateway that stopped during an agy session left its port free for another program to take, with agy's Google token sent to it. If the proof fails now, agy gets a 502 and the token stays in the relay.
+- **A relay key that no page serves:** The relay accepts only `relayProof`, an HMAC keyed by `gateway.secret`, a random file next to `admin.token`. The gateway makes it at startup and keeps no copy. The dashboard page carries `admin.token`, so a proof keyed by it could be made by any program that loads the page. A gateway older than the relay gets a 502 that says to restart it.
+- **A `.cmd` agy gets its arguments unchanged:** The relay starts a `.cmd` or `.bat` agy through `%SystemRoot%\System32\cmd.exe /e:ON /v:OFF /d /c` with the quoting of the Rust standard library since CVE-2024-24576. `%` cannot expand a variable, and `&` or `|` cannot start a second command. A line break, or a command line over 8191 characters, stops the relay before agy starts, with a hint to pipe the prompt on stdin.
+- **`switch off` and `switch port` leave another instance alone:** They stopped or rewrote the installed service even when it ran the gateway of another port. A second instance (`LLM_SWITCHER_PORT`) then stopped the first one. The service now counts only for the port its definition names. The test suite triggered the same fault and stopped the real gateway of the machine.
+
+## Release 1.3.2
+
+- **Codex over WebSocket crosses Bifrost:** Codex uses its WebSocket transport by default. The gateway now sends each WebSocket turn to intact `/v1/responses` as one HTTP request with the whole conversation, and sends each event back as one frame. Before, these turns took the convert route. A stream that stops before `response.completed` ends the turn with `response.failed`.
+- **All Codex clients cross Bifrost:** `codex exec` sends `codex_exec/` in its `User-Agent`, not `codex_cli_rs/`. The gateway takes `codex_cli_rs`, `codex_exec`, `codex_vscode` and `codex_sdk_ts` as one client. Before, `codex exec` never crossed Bifrost.
+- **`make-certs.sh` and a Windows path:** The script read a lone argument such as `C:\Users\me\certs` as a host name and ignored it, so it rebuilt the certificates of the checkout instead. A running interceptor then served a leaf from the old CA, and Codex failed with `workspace routing discovery failed`. A backslash now marks a path.
+- **Tests:** `npm test` no longer rebuilds the certificates of the checkout. The suite runs on Linux, macOS and Windows in CI, and on Node 18.
+
 ## Release 1.3.1
 
 - **agy note:** `switch plugin status` now names agy 1.2.14. This release of agy also loads `~/.gemini/antigravity-cli/hooks.json` but does not run its hooks (measured 2026-10-03), so the shim toast is still the notice for agy.

package/README.md

@@ -337,6 +337,19 @@ gateway for its identity proof before it gives agy the variable. If the port doe
 the proof of this install within 3 seconds, the shim removes the variable, prints one line, and agy
 uses its official endpoint.
 
+The gateway can also stop while agy runs (`switch off`, a crash, an update). Its port is then free,
+and another program can take it. So a routed agy never talks to the gateway port directly. The shim
+starts agy behind a relay (`agy-relay.mjs`) that holds its own loopback port for as long as agy
+runs. For each connection from agy, the relay asks the gateway for its identity proof on the same
+socket, and sends the request on that socket only after the proof holds. If the proof fails, agy
+gets a 502, and its token stays in the relay.
+
+The relay accepts only a proof keyed by `gateway.secret`, a random key next to `admin.token`. No
+page and no route of the gateway serves this key. The dashboard page carries `admin.token`, so a
+proof keyed by `admin.token` could be made by any program that loads the page. If the running
+gateway is older than the relay, agy gets a 502 that says to restart it (`switch off`, then
+`switch on`).
+
 ### Blindfold mode (optional)
 
 A base URL override makes Codex print one line on its own `/model` screen:
@@ -480,11 +493,17 @@ Bifrost has no setting. The gateway turns it on for each request when two condit
 | Tool | `bifrost_ua` | Path on intact |
 | --- | --- | --- |
 | Claude Code | `claude-cli/` | `/v1/messages` |
-| Codex (HTTP) | `codex_cli_rs/` | `/v1/responses` |
+| Codex (HTTP and WebSocket) | `codex_cli_rs/` | `/v1/responses` |
 | Antigravity CLI | `antigravity/cli/` | `/v1/v1internal:streamGenerateContent`, `/v1/v1internal:generateContent` |
 
-For agy, intact also writes the project of the chosen account into the request. Codex over its
-WebSocket transport still uses the normal route.
+For agy, intact also writes the project of the chosen account into the request.
+
+Codex names its client in the `User-Agent`: `codex_cli_rs` for the terminal UI, `codex_exec` for
+`codex exec`, `codex_vscode` and `codex_sdk_ts`. The gateway takes all four as the Codex client.
+
+Codex over its WebSocket transport crosses Bifrost too. intact keeps no WebSocket state, so the
+gateway sends each turn to `/v1/responses` as one HTTP request with the whole conversation. Each
+event of the answer goes back to Codex as one WebSocket frame, unchanged.
 
 The gateway keeps the answer from intact for 10 minutes for each model. Only a 2xx answer is kept that long. If intact does not answer, or answers with an error (a 404 too), the gateway uses the normal route. It asks again after 30 seconds (`LLM_SWITCHER_BIFROST_RETRY_MS`), and it prints one line for each series of failures.
 

package/README.vi.md

@@ -337,6 +337,18 @@ agy gửi token này dạng rõ tới `CLOUD_CODE_URL`. Vì vậy shim `agy` h
 trước khi giao biến này cho agy. Nếu cổng không trả lời đúng bằng chứng của bản cài này trong 3 giây,
 shim gỡ biến, in một dòng thông báo, và agy dùng endpoint chính thức.
 
+Gateway cũng có thể dừng trong lúc agy đang chạy (`switch off`, crash, cập nhật). Khi đó cổng của nó
+bỏ trống, và một chương trình khác có thể chiếm cổng. Vì vậy agy đã route không bao giờ nói chuyện
+trực tiếp với cổng gateway. Shim chạy agy sau một relay (`agy-relay.mjs`) giữ cổng loopback riêng
+suốt thời gian agy chạy. Với mỗi kết nối của agy, relay hỏi gateway bằng chứng danh tính trên chính
+socket đó, và chỉ gửi request trên socket ấy khi bằng chứng đúng. Nếu sai, agy nhận 502, và token
+vẫn nằm lại trong relay.
+
+Relay chỉ chấp nhận bằng chứng ký bằng `gateway.secret`, một khóa ngẫu nhiên nằm cạnh `admin.token`.
+Không trang và không route nào của gateway trả về khóa này. Trang dashboard chứa `admin.token`, nên
+bằng chứng ký bằng `admin.token` thì chương trình nào tải trang cũng làm giả được. Nếu gateway đang
+chạy cũ hơn relay, agy nhận 502 kèm hướng dẫn khởi động lại (`switch off`, rồi `switch on`).
+
 ### Chế độ blindfold (tùy chọn)
 
 Khi có override base URL, Codex in một dòng ngay trên màn `/model` của nó:
@@ -475,11 +487,17 @@ Bifrost không có cấu hình. Gateway tự bật Bifrost cho từng request kh
 | Công cụ | `bifrost_ua` | Path trên intact |
 | --- | --- | --- |
 | Claude Code | `claude-cli/` | `/v1/messages` |
-| Codex (HTTP) | `codex_cli_rs/` | `/v1/responses` |
+| Codex (HTTP và WebSocket) | `codex_cli_rs/` | `/v1/responses` |
 | Antigravity CLI | `antigravity/cli/` | `/v1/v1internal:streamGenerateContent`, `/v1/v1internal:generateContent` |
 
-Với agy, intact ghi thêm project của tài khoản được chọn vào request. Codex qua WebSocket vẫn đi
-đường thường.
+Với agy, intact ghi thêm project của tài khoản được chọn vào request.
+
+Codex ghi tên client của nó trong `User-Agent`: `codex_cli_rs` cho giao diện terminal, `codex_exec`
+cho `codex exec`, `codex_vscode` và `codex_sdk_ts`. Gateway coi cả bốn là client Codex.
+
+Codex qua WebSocket cũng đi Bifrost. intact không giữ trạng thái WebSocket, nên gateway gửi mỗi lượt
+tới `/v1/responses` thành một request HTTP chứa toàn bộ hội thoại. Mỗi event của câu trả lời quay về
+Codex thành một frame WebSocket, giữ nguyên.
 
 Gateway giữ câu trả lời của intact 10 phút cho mỗi model. Chỉ câu trả lời 2xx được giữ lâu như vậy. Nếu intact không trả lời, hoặc trả lỗi (kể cả 404), gateway dùng đường thường. Gateway hỏi lại sau 30 giây (`LLM_SWITCHER_BIFROST_RETRY_MS`) và in một dòng cho mỗi chuỗi lỗi.
 

package/agy-relay-lib.mjs

@@ -0,0 +1,86 @@
+// Pure helpers of agy-relay.mjs, kept apart so tests can import them without starting a relay.
+
+// The switcher writes 127.0.0.1 only. localhost can resolve to ::1, which no proof covers.
+export function gatewayPort(raw) {
+  let u;
+  try { u = new URL(raw); } catch { return 0; }
+  if (u.protocol !== 'http:' || u.hostname !== '127.0.0.1') return 0;
+  const port = Number(u.port);
+  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 0;
+}
+
+// One complete HTTP/1.1 answer at the start of `buf`: { status, text, rest }, or null while it is
+// still incomplete. An answer with no length cannot share its socket, so it counts as a failure.
+export function readAnswer(buf) {
+  const end = buf.indexOf('\r\n\r\n');
+  if (end < 0) return null;
+  const lines = buf.subarray(0, end).toString('latin1').split('\r\n');
+  const status = Number(lines[0].split(' ')[1]);
+  const headers = {};
+  for (const line of lines.slice(1)) {
+    const i = line.indexOf(':');
+    if (i > 0) headers[line.slice(0, i).trim().toLowerCase()] = line.slice(i + 1).trim();
+  }
+  const rest = buf.subarray(end + 4);
+  if (/close/i.test(headers.connection || '')) return { status: 0, text: '', rest };
+  if (headers['content-length'] !== undefined) {
+    const n = Number(headers['content-length']);
+    if (!Number.isInteger(n) || n < 0) return { status: 0, text: '', rest };
+    if (rest.length < n) return null;
+    return { status, text: rest.subarray(0, n).toString('utf8'), rest: rest.subarray(n) };
+  }
+  if (/chunked/i.test(headers['transfer-encoding'] || '')) {
+    const parts = [];
+    let off = 0;
+    for (;;) {
+      const lineEnd = rest.indexOf('\r\n', off);
+      if (lineEnd < 0) return null;
+      const size = parseInt(rest.subarray(off, lineEnd).toString('latin1'), 16);
+      if (!Number.isInteger(size) || size < 0) return { status: 0, text: '', rest };
+      if (size === 0) {
+        if (rest.length < lineEnd + 4) return null;
+        return { status, text: Buffer.concat(parts).toString('utf8'), rest: rest.subarray(lineEnd + 4) };
+      }
+      if (rest.length < lineEnd + 2 + size + 2) return null;
+      parts.push(rest.subarray(lineEnd + 2, lineEnd + 2 + size));
+      off = lineEnd + 2 + size + 2;
+    }
+  }
+  return { status: 0, text: '', rest };
+}
+
+// The longest string cmd.exe takes after /c.
+export const CMD_LIMIT = 8191;
+const SAFE = /^[A-Za-z0-9#$*+\-./:?@\\_]$/;
+
+// One argument for a batch file, as the Rust standard library builds it since CVE-2024-24576
+// (make_bat_command_line): `"` becomes `""`, and `%` becomes `%%cd:~,%`, which expands to `%`, so
+// cmd.exe never expands a %name% or %name:x=y% that came from the argument.
+function batArg(arg) {
+  const quote = arg === '' || arg.endsWith('\\') || [...arg].some(c => !SAFE.test(c));
+  let out = quote ? '"' : '';
+  let backslashes = 0;
+  for (const c of arg) {
+    if (c === '\\') {
+      backslashes++;
+    } else {
+      if (c === '"') out += `${'\\'.repeat(backslashes)}"`;
+      else if (c === '%') out += '%%cd:~,';
+      backslashes = 0;
+    }
+    out += c;
+  }
+  if (quote) out += `${'\\'.repeat(backslashes)}"`;
+  return out;
+}
+
+// The cmd.exe arguments that run a .cmd/.bat with `args` unchanged: { args } or { error }.
+export function batCommandLine(script, args) {
+  if (script.includes('"') || script.endsWith('\\')) return { error: `the path of agy (${script}) cannot hold " or end with \\` };
+  for (const a of args) {
+    if (/[\r\n]/.test(a)) return { error: 'an argument holds a line break, which a .cmd or .bat agy cannot receive. Pipe the prompt on stdin instead.' };
+  }
+  const inner = `"${[`"${script.replace(/%/g, '%%cd:~,%')}"`, ...args.map(batArg)].join(' ')}"`;
+  if (inner.length > CMD_LIMIT) return { error: `the command line is longer than ${CMD_LIMIT} characters, the limit of cmd.exe. Pipe the prompt on stdin instead.` };
+  return { args: ['/e:ON', '/v:OFF', '/d', '/c', inner] };
+}

package/agy-relay.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// Runs agy behind a relay that holds its own loopback port for exactly as long as agy runs.
+//
+// agy sends its Google token in clear text to CLOUD_CODE_URL. The shim checks the gateway once,
+// at launch. A gateway that stops later frees its port, and another program can take it. So agy
+// talks only to this relay: for each connection it asks the gateway for its relay proof on the
+// socket it will use, and sends agy's bytes only after that proof holds.
+//
+// Usage: node agy-relay.mjs <gateway-url> <agy> [args...]
+import net from 'node:net';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { relayProof } from './state.mjs';
+import { gatewayPort, readAnswer, batCommandLine } from './agy-relay-lib.mjs';
+
+// The proof of a live gateway takes milliseconds; a squatter gains nothing from a longer wait.
+const PROOF_MS = 3000;
+const MAX_PROBE_ANSWER = 64 * 1024;
+
+// The gateway on a new socket: { sock } when it proved itself with the relay key (state.mjs),
+// otherwise { old: true } for a gateway built before relayProof, or {} for anything else. Only the
+// first case gets agy's bytes, on this same socket, so no other process can answer them.
+function provenSocket(port) {
+  return new Promise((resolve) => {
+    const nonce = crypto.randomBytes(16).toString('hex');
+    const sock = net.connect(port, '127.0.0.1');
+    let buf = Buffer.alloc(0);
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.off('data', onData);
+      sock.off('error', onFail);
+      sock.off('close', onFail);
+      if (result.sock) return resolve(result);
+      sock.destroy();
+      resolve(result);
+    };
+    const onFail = () => finish({});
+    const onData = (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      if (buf.length > MAX_PROBE_ANSWER) return finish({});
+      const answer = readAnswer(buf);
+      if (!answer) return;
+      // Nothing may follow the probe answer: those bytes would reach agy as its own answer.
+      if (answer.status !== 200 || answer.rest.length) return finish({});
+      let body;
+      try { body = JSON.parse(answer.text); } catch { return finish({}); }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) return finish({});
+      if (body.proxy !== 'llm-switcher' || body.port !== port) return finish({});
+      // An absent field, never a falsy one: relayProof '' must still fail the check below.
+      if (!Object.hasOwn(body, 'relayProof')) return finish({ old: true });
+      const expected = relayProof(nonce, { port, pid: body.pid });
+      finish(Boolean(expected) && body.relayProof === expected ? { sock } : {});
+    };
+    const timer = setTimeout(onFail, PROOF_MS);
+    sock.on('data', onData);
+    sock.on('error', onFail);
+    sock.on('close', onFail);
+    sock.write(`GET /health?challenge=${nonce} HTTP/1.1\r\nHost: 127.0.0.1:${port}\r\nConnection: keep-alive\r\n\r\n`);
+  });
+}
+
+// agy shows a Code Assist error, and its request stays in this process.
+function refusal(message) {
+  const body = JSON.stringify({ error: { code: 502, status: 'UNAVAILABLE', message } });
+  return `HTTP/1.1 502 Bad Gateway\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`;
+}
+const NOT_PROVED = 'LLM Switcher: the gateway did not prove its identity, so this request was not sent. Run `switch on`, or `switch off agy`.';
+const OLD_GATEWAY = 'LLM Switcher: the running gateway is older than this relay. Restart it: `switch off`, then `switch on`.';
+
+function startRelay(port) {
+  // pauseOnConnect: agy's bytes stay unread until the gateway on this connection has proved itself.
+  const server = net.createServer({ pauseOnConnect: true }, async (client) => {
+    client.on('error', () => client.destroy());
+    const { sock: up, old } = await provenSocket(port);
+    if (client.destroyed) return up?.destroy();
+    if (!up) {
+      client.end(refusal(old ? OLD_GATEWAY : NOT_PROVED));
+      client.resume(); // read and drop the request; nothing of it leaves this process
+      return;
+    }
+    up.on('error', () => client.destroy());
+    client.on('close', () => up.destroy());
+    up.on('close', () => client.destroy());
+    client.pipe(up);
+    up.pipe(client);
+    client.resume();
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+// A .cmd/.bat cannot start without cmd.exe. It is always the one in System32: a bare name would be
+// looked up in the current directory first.
+function launch(file, args, env) {
+  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(file)) {
+    const line = batCommandLine(file, args);
+    if (line.error) {
+      console.error(`[llm-switcher] cannot start agy: ${line.error}`);
+      process.exit(2);
+    }
+    const cmd = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe');
+    return spawn(cmd, line.args, { stdio: 'inherit', env, windowsVerbatimArguments: true });
+  }
+  return spawn(file, args, { stdio: 'inherit', env });
+}
+
+const [gatewayUrl, agy, ...args] = process.argv.slice(2);
+if (!agy) {
+  console.error('Usage: node agy-relay.mjs <gateway-url> <agy> [args...]');
+  process.exit(2);
+}
+if (args.some(a => a.includes('\0'))) {
+  console.error('[llm-switcher] cannot start agy: an argument holds a NUL character.');
+  process.exit(2);
+}
+
+const env = { ...process.env };
+delete env.CLOUD_CODE_URL;
+const port = gatewayPort(gatewayUrl);
+if (port) {
+  const server = await startRelay(port);
+  env.CLOUD_CODE_URL = `http://127.0.0.1:${server.address().port}`;
+} else {
+  console.error(`[llm-switcher] ${String(gatewayUrl)} is not the address of this switcher's gateway; agy uses its official endpoint.`);
+}
+
+const child = launch(agy, args, env);
+// Ctrl+C reaches agy and this relay together. agy decides what it means; the relay ends with agy.
+process.on('SIGINT', () => {});
+if (process.platform === 'win32') process.on('SIGBREAK', () => {});
+process.on('SIGTERM', () => child.kill());
+child.on('error', (err) => {
+  console.error(`[llm-switcher] cannot start agy (${agy}): ${err.message}`);
+  process.exit(127);
+});
+child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));

package/blindfold/make-certs.sh

@@ -35,10 +35,11 @@ elif [ -d "$ROOT/.git" ]; then DEFAULT_OUT="$ROOT/blindfold/certs"
 else DEFAULT_OUT="$HOME/.llm-switcher/blindfold/certs"; fi
 # Older commands read `make-certs.sh <host> <out-dir>`. The host list is fixed now, so the host is
 # ignored; two arguments keep those commands working. A lone path-like argument is the directory.
+# A Windows path (C:\...\certs) has no forward slash, so a backslash also marks a path.
 OUT_ARG=""
 if [ "$#" -ge 2 ]; then OUT_ARG="$2"
 elif [ "$#" -eq 1 ]; then
-  case "$1" in */*|.*) OUT_ARG="$1" ;; *) : ;; esac
+  case "$1" in */*|*\\*|.*) OUT_ARG="$1" ;; *) : ;; esac
 fi
 OUT_DIR="${OUT_ARG:-$DEFAULT_OUT}"
 CA_DAYS=3650

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code and Codex, with OpenAI-compatible, Anthropic and Vertex upstreams",
   "keywords": [
     "llm",

package/proxy.mjs

@@ -22,7 +22,7 @@ import {
   getActiveMap, setTargetProfile, activateProfile, deactivateProfile, deactivateAll, deleteProfile,
   isProfileActive, profileAcceptsTarget, applyLaunchState, readLaunchFlags, redactConfig, MASKED_KEY,
   modelForSlot, primaryModel, codexPublicModel, isSafeModelName, parsePort, CODEX_MODEL_SLOTS,
-  ensureAdminToken, identityProof, reconcileBlindfold, checkBlindfoldTarget,
+  ensureAdminToken, ensureGatewaySecret, relayProof, identityProof, reconcileBlindfold, checkBlindfoldTarget,
   codexModelEntry, smallestWindows, publicModelWindows, model1MForSlot,
   contractLabSettings, STATE_DIR, stopRecordedBlindfold
 } from './state.mjs';
@@ -116,6 +116,8 @@ function checkRequestOrigin(req) {
 // The Host/Origin guard stops browser pages only. A local process that is not the owner must
 // also present the token from admin.token (mode 0600) to use /api/*.
 const ADMIN_TOKEN = Buffer.from(ensureAdminToken());
+// The relay key. The gateway keeps no copy: relayProof() reads the file for each proof.
+ensureGatewaySecret();
 
 // `switch contract-probe` names the trace id of the exchange it drives, so it can print the id
 // before intact holds it. Only a process that can read admin.token is believed, and the marker
@@ -548,11 +550,17 @@ async function bifrostUAFor(profile, model) {
   return ua;
 }
 
+// Codex names its originator in the User-Agent: codex_cli_rs (TUI), codex_exec (`codex exec`),
+// codex_vscode, codex_sdk_ts. intact names one of them; each one is the same client.
+const BIFROST_UA_FAMILIES = [['codex_cli_rs/', 'codex_exec/', 'codex_vscode/', 'codex_sdk_ts/']];
+
 async function crossesBifrost(req, profile, model) {
   const clientUA = String(req.headers['user-agent'] || '');
   if (!clientUA) return false;
   const ua = await bifrostUAFor(profile, model);
-  return Boolean(ua) && clientUA.startsWith(ua);
+  if (!ua) return false;
+  const family = BIFROST_UA_FAMILIES.find(f => f.includes(ua)) || [ua];
+  return family.some(prefix => clientUA.startsWith(prefix));
 }
 
 // Every client header except its own credentials, the switcher's control headers and hop-by-hop.
@@ -1309,7 +1317,9 @@ async function route(req, res) {
       proxy: 'llm-switcher',
       ...(challenge ? {
         pid: process.pid,
-        proof: identityProof(challenge, { role: 'gateway', port: PORT, pid: process.pid }, ADMIN_TOKEN.toString())
+        proof: identityProof(challenge, { role: 'gateway', port: PORT, pid: process.pid }, ADMIN_TOKEN.toString()),
+        // The only proof agy-relay.mjs accepts: its key is not on the dashboard page.
+        relayProof: relayProof(challenge, { port: PORT, pid: process.pid })
       } : {}),
       port: PORT,
       configLoaded: Boolean(loadConfig()),
@@ -1848,6 +1858,88 @@ function geminiSafeTools(tools) {
   });
 }
 
+// Bifrost on the WS transport. intact speaks HTTP and keeps no WS state, so the turn goes to
+// /responses as one streamed request with the whole conversation, and each SSE event goes back to
+// Codex as one text frame, unchanged.
+async function wsBifrostTurn({ socket, payload, req, ac, history, input, profile, profileKey, mappedModel }) {
+  const started = Date.now();
+  const log = (extra) => logInspection({
+    clientFormat: 'responses-ws', outFormat: 'bifrost', profile: profileKey, model: mappedModel, stream: true,
+    requestPreview: '(bifrost)', duration: Date.now() - started, tokens: { prompt: 0, completion: 0 }, ...extra
+  });
+  const headers = bifrostHeaders(req, profile);
+  for (const h of Object.keys(headers)) if (h === 'upgrade' || h.startsWith('sec-websocket-')) delete headers[h];
+  headers['content-type'] = 'application/json';
+  headers.accept = 'text/event-stream';
+  // `type` names the WS frame (response.create); it is not a field of a Responses request.
+  const { type: _type, ...body } = payload;
+
+  let upstreamRes;
+  try {
+    upstreamRes = await fetch(bifrostURL(profile, 'responses', req), {
+      method: 'POST', headers, body: JSON.stringify({ ...body, model: mappedModel, stream: true }), signal: ac.signal
+    });
+  } catch (err) {
+    if (ac.signal.aborted) return log({ status: 499, error: 'client disconnected' });
+    sendWsFailed(socket, mappedModel, `Bifrost forward error: ${err.cause?.message || err.message}`, 502);
+    return log({ status: 502, error: err.message });
+  }
+  if (!upstreamRes.ok) {
+    const errText = await upstreamRes.text().catch(() => '');
+    sendWsFailed(socket, mappedModel, extractUpstreamMessage(errText) || `Upstream HTTP ${upstreamRes.status}`, upstreamRes.status);
+    return log({ status: upstreamRes.status, error: errText.slice(0, 300) });
+  }
+
+  let completed = null;
+  // With store:false the backend sends response.completed with an empty output; the items of the
+  // turn come only in response.output_item.done, and the next turn must replay them.
+  const items = [];
+  let ended = false; // a response.completed or response.failed reached Codex
+  let streamError = null;
+  const decoder = new TextDecoder();
+  let pending = '';
+  const reader = upstreamRes.body.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      pending += decoder.decode(value, { stream: true }).replace(/\r\n/g, '\n');
+      let cut;
+      while ((cut = pending.indexOf('\n\n')) >= 0) {
+        const data = pending.slice(0, cut).split('\n').filter(l => l.startsWith('data:')).map(l => l.slice(5).trimStart()).join('\n');
+        pending = pending.slice(cut + 2);
+        if (!data || data === '[DONE]') continue;
+        let event;
+        try { event = JSON.parse(data); } catch { continue; }
+        if (event.type === 'response.output_item.done' && event.item) items.push(event.item);
+        if (event.type === 'response.completed') completed = event.response;
+        if (event.type === 'response.completed' || event.type === 'response.failed') ended = true;
+        if (!socket.writable) continue;
+        socket.write(encodeWsFrame(data));
+        await drained(socket, ac.signal);
+      }
+    }
+  } catch (err) {
+    if (!ac.signal.aborted) streamError = `stream interrupted: ${err.cause?.message || err.message}`;
+  }
+  if (ac.signal.aborted) return log({ status: 499, error: 'client disconnected mid-stream' });
+  // Codex ends a turn only on a terminal event: a stream cut before one must still end the turn.
+  if (!ended) {
+    streamError ||= 'the Bifrost stream ended before response.completed';
+    sendWsFailed(socket, mappedModel, streamError, 502);
+  }
+  if (completed) {
+    const output = Array.isArray(completed.output) && completed.output.length ? completed.output : items;
+    rememberWsTurn(history, { ...completed, output }, input);
+  }
+  const usage = completed?.usage || {};
+  log({
+    status: streamError ? 502 : 200,
+    tokens: { prompt: usage.input_tokens || 0, completion: usage.output_tokens || 0 },
+    ...(streamError ? { error: streamError } : {})
+  });
+}
+
 // One turn of the Codex WS transport. The socket loop runs turns one at a time and owns `ac`.
 async function handleWsResponseCreate(socket, payload, req, ac, history = null) {
   const clientFormat = 'responses';
@@ -1877,6 +1969,11 @@ async function handleWsResponseCreate(socket, payload, req, ac, history = null)
   const { previous_response_id: _prev, ...rest } = payload;
   payload = { ...rest, input };
 
+  const bifrostModel = mapModel(payload.model || '', profile, clientFormat);
+  if (await crossesBifrost(req, profile, bifrostModel)) {
+    return wsBifrostTurn({ socket, payload, req, ac, history, input, profile, profileKey, mappedModel: bifrostModel });
+  }
+
   let ir;
   try {
     ir = parseToIR('responses', payload);

package/shim.mjs

@@ -40,6 +40,9 @@ const ROUTE_NOTIFIER = path.join(path.dirname(fileURLToPath(import.meta.url)), '
 // agy sends its Google token in clear text to CLOUD_CODE_URL. Its shim asks this helper for the
 // gateway's identity proof first, so a process that took the port never receives the token.
 const GATEWAY_CHECK = path.join(path.dirname(fileURLToPath(import.meta.url)), 'verify-gateway.mjs');
+// The launch check covers the start only. A routed agy then runs behind this relay, which proves
+// the gateway on every connection, so a port freed later never receives the token.
+const AGY_RELAY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'agy-relay.mjs');
 
 // CLIs to wrap. `claude` is the most important case (--resume); codex and agy have their own files.
 export const SHIMMED = ['claude', 'codex', 'agy'];
@@ -191,6 +194,13 @@ if [ -z "$REAL" ]; then
   exit 127
 fi
 
+${name !== 'agy' ? '' : `# A routed agy talks only to its relay, which lives as long as agy (agy-relay.mjs).
+if [ "$TOOL_ACTIVE" = "1" ] && [ -n "\${CLOUD_CODE_URL:-}" ]; then
+  GATEWAY_URL="$CLOUD_CODE_URL"
+  unset CLOUD_CODE_URL
+  exec node "${AGY_RELAY}" "$GATEWAY_URL" "$REAL" "$@"
+fi
+`}
 # No override of any kind: the tool keeps its own configuration and its own model names (F3, R1).
 exec "$REAL" "$@"
 `;
@@ -266,14 +276,26 @@ for /f "tokens=1 delims==" %%V in ('set LLM_SWITCHER_CODEX_ 2^>nul ^| findstr /b
 ${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 (
+${name === 'agy' ? `set "REAL_BIN="
+for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do if not defined REAL_BIN set "REAL_BIN=%%i"
+if not defined REAL_BIN for /f "delims=" %%i in ('where ${name}.exe 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do if not defined REAL_BIN set "REAL_BIN=%%i"
+if not defined REAL_BIN goto :NOT_FOUND
+REM A routed agy talks only to its relay, which lives as long as agy (agy-relay.mjs).
+if not "%TOOL_ACTIVE%"=="1" goto :RUN_PLAIN
+if not defined CLOUD_CODE_URL goto :RUN_PLAIN
+node "${AGY_RELAY}" "%CLOUD_CODE_URL%" "%REAL_BIN%" %*
+exit /b
+:RUN_PLAIN
+call "%REAL_BIN%" %*
+exit /b
+:NOT_FOUND` : `for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
   call "%%i" %*
   exit /b
 )
 for /f "delims=" %%i in ('where ${name}.exe 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
   call "%%i" %*
   exit /b
-)
+)`}
 echo [llm-switcher] cannot find the real '${name}' on PATH.>&2
 exit /b 127
 

package/state.mjs

@@ -107,6 +107,38 @@ export function ensureAdminToken() {
   return token;
 }
 
+// The key of the proof that agy-relay.mjs checks. Random, never derived from admin.token: the
+// dashboard page carries admin.token, so a proof keyed by it can be made by anyone who loads /ui.
+export const gatewaySecretPath = path.join(path.dirname(configPath), 'gateway.secret');
+
+export function readGatewaySecret() {
+  try {
+    return fs.readFileSync(gatewaySecretPath, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// A good secret is kept. A missing, empty or blank file is replaced through a rename, so a damaged
+// file never leaves agy without a key. Throws when it cannot write; never leaves a temporary file.
+export function ensureGatewaySecret() {
+  if (readGatewaySecret()) return;
+  const tmp = `${gatewaySecretPath}.${process.pid}.tmp`;
+  try {
+    fs.rmSync(tmp, { force: true });
+    fs.writeFileSync(tmp, crypto.randomBytes(32).toString('hex'), { mode: 0o600, flag: 'wx' });
+    fs.renameSync(tmp, gatewaySecretPath);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    throw err;
+  }
+}
+
+export function relayProof(nonce, { port, pid }, secret = readGatewaySecret()) {
+  if (!secret) return '';
+  return crypto.createHmac('sha256', secret).update(['relay', port, pid, nonce].join('|')).digest('hex');
+}
+
 // `switch ui` must not put the token on a command line: /proc/<pid>/cmdline is readable by every
 // account. It opens this private file instead, which redirects to the dashboard with the token.
 export function writeDashboardLauncher(url) {