@alexeiled/claude-router 0.2.2 → 0.4.1

package/lib/store.mjs

@@ -1,7 +1,19 @@
 // Files: user config, per-session memory and the decision log. The only module that touches the filesystem.
-import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import {
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { join } from 'node:path';
 
+export const LOG_LIMIT_BYTES = 20 * 1024 * 1024;
+const SESSION_TTL_MS = 30 * 24 * 3_600_000;
+
 export function readJsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, 'utf8'));
@@ -31,6 +43,33 @@ export function appendLog(dir, entry) {
   appendFileSync(join(dir, 'decisions.jsonl'), `${JSON.stringify(entry)}\n`);
 }
 
+// Keeps one previous generation: `<file>.1`. Only for files written by path, not held open.
+export function rotate(path, limitBytes = LOG_LIMIT_BYTES) {
+  try {
+    if (statSync(path).size > limitBytes) renameSync(path, `${path}.1`);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
+// Bounds the data directory of a long-running gateway: the decision log and a month of session memory.
+// gateway.log is the daemon's open stderr, so the hook that starts the daemon rotates it instead.
+export function housekeeping(dir, now = Date.now()) {
+  rotate(join(dir, 'decisions.jsonl'));
+  const sessions = join(dir, 'sessions');
+  let names;
+  try {
+    names = readdirSync(sessions);
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  for (const name of names) {
+    const path = join(sessions, name);
+    if (now - statSync(path).mtimeMs > SESSION_TTL_MS) rmSync(path, { force: true });
+  }
+}
+
 function memoryPath(dir, sessionId) {
   return join(dir, 'sessions', `${String(sessionId).replace(/[^\w.-]/g, '_')}.json`);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alexeiled/claude-router",
-  "version": "0.2.2",
-  "description": "Claude Code plugin: a local gateway that selects a model and an effort level for each user turn with a TypeSafe Jev Choice.",
+  "version": "0.4.1",
+  "description": "Claude Code plugin: auto-picks the right model and effort for each turn using Jev routing.",
   "license": "MIT",
   "author": "Alexei Ledenev",
   "repository": {

package/scripts/ensure-gateway.mjs

@@ -1,16 +1,30 @@
 #!/usr/bin/env node
-// SessionStart hook: start the gateway daemon when nothing answers on its port. Detached, so it outlives the session.
+// Hook entry (SessionStart, UserPromptSubmit): make sure a gateway of this plugin version or newer answers on the port.
+// Starts one on a free port and replaces an older one; leaves a newer one alone, so a session that still runs an older
+// plugin never downgrades it. Detached, so the gateway outlives the session. After a crash, the next prompt restarts it.
+// `--quiet` prints nothing: UserPromptSubmit output goes into the model's context.
 import { spawn } from 'node:child_process';
 import { mkdirSync, openSync } from 'node:fs';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadRuntime } from '../lib/runtime.mjs';
+import { isOlderVersion, ROUTER_VERSION, STATUS_PATH } from '../lib/status.mjs';
+import { rotate } from '../lib/store.mjs';
+
+const WAIT_STEP_MS = 100;
+const WAIT_STEPS = 20;
+const STATUS_TIMEOUT_MS = 500;
 
 const env = process.env;
+const quiet = process.argv.includes('--quiet');
 const { config, dataDir } = loadRuntime(env);
 const port = config.gateway.port;
 
+function say(message) {
+  if (!quiet) process.stdout.write(`router: ${message}\n`);
+}
+
 function probe() {
   return new Promise((resolve) => {
     const socket = connect({ host: '127.0.0.1', port });
@@ -22,15 +36,56 @@ function probe() {
   });
 }
 
-const configured = (env.ANTHROPIC_BASE_URL ?? '').includes(`127.0.0.1:${port}`);
-if (!configured)
-  process.stdout.write(
-    'router: Claude Code does not use the gateway yet. Run /router:setup, then restart Claude Code.\n',
-  );
+// Waits until the port answers (`true`) or is free (`false`).
+async function waitFor(answering) {
+  for (let i = 0; i < WAIT_STEPS; i += 1) {
+    if ((await probe()) === answering) return true;
+    await new Promise((resolve) => setTimeout(resolve, WAIT_STEP_MS));
+  }
+  return false;
+}
+
+async function runningGateway() {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}${STATUS_PATH}`, {
+      signal: AbortSignal.timeout(STATUS_TIMEOUT_MS),
+    });
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+// SIGTERM: the old gateway releases the port at once and finishes its open streams. Gateways from 0.4.0 on report
+// their pid; older ones cannot be retired from here.
+async function retire(running) {
+  const from = running.version ?? 'before 0.3.0';
+  if (!running.pid) {
+    say(
+      `gateway ${from} runs on port ${port}. Stop it once with \`pkill -f scripts/gateway.mjs\`; the next prompt starts ${ROUTER_VERSION}.`,
+    );
+    return false;
+  }
+  try {
+    process.kill(running.pid, 'SIGTERM');
+  } catch (error) {
+    say(`cannot stop gateway ${from} (pid ${running.pid}): ${error.message}`);
+    return false;
+  }
+  if (await waitFor(false)) return true;
+  say(`gateway ${from} (pid ${running.pid}) did not release port ${port}`);
+  return false;
+}
 
-if (!(await probe())) {
+async function start() {
   mkdirSync(dataDir, { recursive: true });
-  const log = openSync(join(dataDir, 'gateway.log'), 'a');
+  const logPath = join(dataDir, 'gateway.log');
+  try {
+    rotate(logPath);
+  } catch {
+    // Rotation is housekeeping; a gateway that starts matters more.
+  }
+  const log = openSync(logPath, 'a');
   // Claude Code exports the plugin option as CLAUDE_PLUGIN_OPTION_<KEY>; the gateway reads one name only.
   const childEnv = {
     ...env,
@@ -43,13 +98,20 @@ if (!(await probe())) {
   });
   child.unref();
   // Wait for the listener so the session's first request finds it.
-  let up = false;
-  for (let i = 0; i < 20 && !up; i += 1) {
-    await new Promise((r) => setTimeout(r, 100));
-    up = await probe();
-  }
-  process.stdout.write(
-    `router: gateway on 127.0.0.1:${port} ${up ? 'started' : 'not answering yet'} (pid ${child.pid})\n`,
-  );
+  return { pid: child.pid, up: await waitFor(true) };
+}
+
+if (!(env.ANTHROPIC_BASE_URL ?? '').includes(`127.0.0.1:${port}`))
+  say('Claude Code does not use the gateway yet. Run /router:setup, then restart Claude Code.');
+
+const running = await runningGateway();
+if (running && !isOlderVersion(running.version, ROUTER_VERSION)) process.exit(0);
+if (running && !(await retire(running))) process.exit(0);
+if (!running && (await probe())) {
+  say(`port ${port} answers, but not as the router gateway`);
+  process.exit(0);
 }
+const { pid, up } = await start();
+const verb = running ? `replaced ${running.version ?? 'an older gateway'} on` : 'started on';
+say(`gateway ${ROUTER_VERSION} ${up ? verb : 'not answering yet on'} 127.0.0.1:${port} (pid ${pid})`);
 process.exit(0);

package/scripts/gateway.mjs

@@ -1,12 +1,71 @@
 #!/usr/bin/env node
-// Daemon entry: local gateway on 127.0.0.1:<gateway.port>. Started by the SessionStart hook or by hand.
+// Daemon entry: local gateway on 127.0.0.1:<gateway.port>. Started by the plugin hooks or by hand.
 import { createGateway } from '../lib/gateway.mjs';
+import { IdleTracker } from '../lib/idle.mjs';
 import { Router } from '../lib/router.mjs';
 import { loadRuntime } from '../lib/runtime.mjs';
+import { ROUTER_VERSION } from '../lib/status.mjs';
+import { housekeeping } from '../lib/store.mjs';
+
+// On stop the port is released at once; open streams get this long to finish (Claude Code's request timeout).
+const DRAIN_MS = 600_000;
+const HOUSEKEEPING_MS = 3_600_000;
+const IDLE_CHECK_MS = 60_000;
+
+process.stderr.on('error', () => {}); // a full disk must not turn a log line into a crash
+const log = (message) => process.stderr.write(`${new Date().toISOString()} router: ${message}\n`);
+const onError = (error) => log(error.message);
+
+// Every Claude Code session on the machine goes through this process, so a stray exception is logged, not fatal.
+// Request state is per request and per session; the worst case after such an error is one misrouted turn.
+process.on('uncaughtException', (error) => log(`uncaught exception: ${error.stack ?? error.message}`));
+process.on('unhandledRejection', (reason) => log(`unhandled rejection: ${reason?.stack ?? reason}`));
 
 const { config, dataDir } = loadRuntime(process.env);
-const router = new Router({ config, fetchFn: globalThis.fetch, dataDir });
-const server = createGateway({ router, onError: (error) => process.stderr.write(`router: ${error.message}\n`) });
-server.listen(config.gateway.port, '127.0.0.1', () =>
-  process.stdout.write(`router: listening on http://127.0.0.1:${config.gateway.port} as ${config.gateway.alias}\n`),
+const { port, alias, idleShutdownMs } = config.gateway;
+const router = new Router({ config, fetchFn: globalThis.fetch, dataDir, onError });
+const activity = new IdleTracker();
+const server = createGateway({ router, onError, activity });
+
+server.on('error', (error) => {
+  if (error.code === 'EADDRINUSE') {
+    log(`port ${port} is in use, another gateway serves it: exiting`);
+    process.exit(0);
+  }
+  log(`server error: ${error.message}`);
+  process.exit(1);
+});
+
+let stopping = false;
+function stop(reason) {
+  if (stopping) return;
+  stopping = true;
+  log(`${reason}: no new connections, finishing open streams`);
+  server.close(() => process.exit(0));
+  server.closeIdleConnections();
+  setTimeout(() => process.exit(0), DRAIN_MS).unref();
+}
+process.once('SIGTERM', () => stop('SIGTERM'));
+process.once('SIGINT', () => stop('SIGINT'));
+
+if (idleShutdownMs > 0) {
+  const minutes = Math.round(idleShutdownMs / 60_000);
+  const check = () => {
+    if (activity.idle(idleShutdownMs)) stop(`idle for ${minutes} min, no turn waits for a tool`);
+  };
+  setInterval(check, Math.min(idleShutdownMs, IDLE_CHECK_MS)).unref();
+}
+
+function tidy() {
+  try {
+    housekeeping(dataDir);
+  } catch (error) {
+    onError(error);
+  }
+}
+tidy();
+setInterval(tidy, HOUSEKEEPING_MS).unref();
+
+server.listen(port, '127.0.0.1', () =>
+  log(`${ROUTER_VERSION} listening on http://127.0.0.1:${port} as ${alias} (pid ${process.pid})`),
 );

package/skills/setup/SKILL.md

@@ -1,24 +1,29 @@
 ---
 name: setup
-description: Point Claude Code at the router gateway. Adds `model`, `ANTHROPIC_BASE_URL` and the `/model` picker row to the user settings, and offers the status line.
+description: Point Claude Code at the router gateway. Adds `model`, `ANTHROPIC_BASE_URL`, the context window and the `/model` picker row to the user settings, and offers the status line.
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write
 ---
 
-Configure Claude Code for the router gateway. Do these steps:
+Configure Claude Code for the router gateway. This session does not use the gateway until Claude Code restarts. When the file has `model: "router"`, this session can fail its next request. So ask all questions first, write the file once, and write it last.
 
-1. Read `~/.claude/settings.json`. If the file does not exist, start from `{}`.
-2. Set the key `model` to `"router"`.
-3. Set the key `env.ANTHROPIC_BASE_URL` to `"http://127.0.0.1:43170"`. If `~/.claude/router.json` sets `gateway.port`, use that port.
-4. Set these keys in `env`, for the `/model` picker row:
-   - `ANTHROPIC_CUSTOM_MODEL_OPTION`: `"router"`
-   - `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME`: `"Router (auto)"`
-   - `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`: `"Picks Opus 5.5 / Sonnet 4.6 / Haiku 4.5 and the effort for each turn"`
-5. Keep every other key unchanged. Write the file.
-6. The status line can show the model and effort of the last routed turn. The command is `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs`, followed by the current status line command if there is one (for example `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs claude-powerline`). Show the user the current `statusLine` value and the new one, and ask. Change `statusLine.command` only if the user agrees. Keep the other `statusLine` keys.
-7. Tell the user:
-   - Restart Claude Code. Then the router serves each turn, and `/router:status` shows the routes and the last turn.
+1. Read `~/.claude/settings.json`. If the file does not exist, start from `{}`. Read `~/.claude/router.json` if it exists.
+2. The status line can show the model and effort of the last routed turn. The command is `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs`, followed by the current status line command if there is one (for example `node ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.mjs claude-powerline`). Show the user the current `statusLine` value and the new one, and ask. Change `statusLine.command` only if the user agrees. Keep the other `statusLine` keys.
+3. Prepare the new settings object in memory:
+   - `model`: `"router"`.
+   - `env.ANTHROPIC_BASE_URL`: `"http://127.0.0.1:43170"`. If `router.json` sets `gateway.port`, use that port.
+   - `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS`: `"1000000"`. Claude Code does not know the model `router` and assumes a 200K window without this key. If `router.json` changes `routes` or `models`, use the largest `contextWindow` of the models that the routes use. The gateway sends a turn only to a model whose window holds the context.
+   - The `/model` picker row. In `modelPicker.options`, replace the row whose `model` is `"router"`, or append it if there is none:
+     `{ "model": "router", "label": "Router (auto)", "description": "Auto-selects the model and effort for each turn", "behavesAs": "claude-opus-5-5" }`.
+     If `modelPicker` does not exist, set it to `{ "options": [<the row>] }`. Keep the other rows and `replaceBuiltInOptions`. `behavesAs` names a model that Claude Code knows; without it, Claude Code rejects `router` as a model that is not in its catalog. If `router.json` changes the `high` route, use the `id` of its model.
+   - Remove `env.ANTHROPIC_CUSTOM_MODEL_OPTION`, `env.ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` and `env.ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`. Older versions of this setup wrote them; the `modelPicker` row replaces them.
+   - The `statusLine` change from step 2, if the user agreed.
+   - Keep every other key unchanged.
+4. Tell the user, before you write the file:
+   - Restart Claude Code now. Until the restart, this session can show "There's an issue with the selected model (router)", because it still sends requests to Anthropic and not to the gateway.
+   - After the restart, the router serves each turn, and `/router:status` shows the routes and the last turn.
    - The status line path contains the plugin version. After a plugin update, run `/router:setup` again.
-   - To stop the routing, remove `model`, `env.ANTHROPIC_BASE_URL` and the three `ANTHROPIC_CUSTOM_MODEL_OPTION*` keys, and restore the status line command.
+   - To stop the routing, remove `model`, `env.ANTHROPIC_BASE_URL`, `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS` and the `router` row of `modelPicker.options`, and restore the status line command.
+5. Write the whole object to `~/.claude/settings.json` with one Write call. Do not use a sequence of edits. Do nothing after this step.
 
 Do not change any other file.

package/skills/status/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: status
-description: Show the router routes, the Jev key state, and the model and effort of the last routed turn.
+description: Show which model served the last turn, whether Jev routing is active, and the routing config.
 disable-model-invocation: true
 allowed-tools: Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/status.mjs *)
 ---
+
 Router status:
 
 !`node ${CLAUDE_PLUGIN_ROOT}/scripts/status.mjs ${CLAUDE_SESSION_ID}`