@alexeiled/claude-router 0.2.2 → 0.4.0

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.0",
+  "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,6 +1,6 @@
 ---
 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
 ---
@@ -13,12 +13,13 @@ Configure Claude Code for the router gateway. Do these steps:
 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:
+   - `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`: `"Auto-selects the model and effort for each turn"`
+5. Set the key `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS` to `"1000000"`. Claude Code does not know the model `router` and assumes a 200K window without this key. If `~/.claude/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.
+6. Keep every other key unchanged. Write the file.
+7. 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.
+8. Tell the user:
    - Restart Claude Code. Then 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 three `ANTHROPIC_CUSTOM_MODEL_OPTION*` keys, and restore the status line command.
 
 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}`