@khanglvm/llm-router 2.5.1 → 2.5.2

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.2] - 2026-04-23
+
+### Fixed
+- `yarn dev` now force-reclaims stale dev web-console listeners on startup and restarts matching stale dev routers so the next dev session takes over the sandbox cleanly instead of inheriting the old process.
+
 ## [2.5.1] - 2026-04-23
 
 ### Fixed

package/README.md

@@ -29,7 +29,7 @@ llr ai-help  # agent-oriented setup brief
 - **Model aliases with routing** — group models into stable alias names with weighted round-robin, quota-aware balancing, and automatic fallback
 - **Rate limiting** — set request caps per model or across all models over configurable time windows
 - **Coding tool routing** — one-click routing config for Codex CLI, Claude Code, Factory Droid, and AMP
-- **Dev sandbox** — `yarn dev` runs the console against a dedicated dev config/router port, highlights dev mode in terminal + UI, and can clone the production config into the sandbox for quick iteration
+- **Dev sandbox** — `yarn dev` runs the console against a dedicated dev config/router port, highlights dev mode in terminal + UI, can clone the production config into the sandbox for quick iteration, and automatically reclaims stale dev listeners before the next session starts
 - **Claude native web tools** — local handling for Claude web search and page fetch requests, with selectable Claude Code web-search providers from the shared Web Search config
 - **Seamless local updates** — `llr update` keeps the fixed local router endpoint online, drains in-flight requests, and automatically retries through backend restart windows
 - **Web search** — built-in web search for AMP and other router-managed tools
@@ -60,7 +60,7 @@ That means `llr update` can install a new package version and gracefully swap th
 yarn dev
 ```
 
-Development mode uses the dedicated `~/.llm-router-dev.json` config and its own local router port so it can run alongside a startup-managed or manually started production router. The terminal and Web UI both show a dev-mode indicator, and the dev Web UI includes a one-click sync action to copy the current production config into the sandbox without changing the dev router binding.
+Development mode uses the dedicated `~/.llm-router-dev.json` config and its own local router port so it can run alongside a startup-managed or manually started production router. The terminal and Web UI both show a dev-mode indicator, the dev Web UI includes a one-click sync action to copy the current production config into the sandbox without changing the dev router binding, and each new `yarn dev` run automatically takes over any stale dev web-console/router listeners from a prior session.
 
 ## Web UI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/llm-router",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "LLM Router: single gateway endpoint for multi-provider LLMs with unified OpenAI+Anthropic format and seamless fallback",
   "keywords": [
     "llm-router",

package/src/node/dev-command.js

@@ -0,0 +1,114 @@
+import { getActiveRuntimeState } from "./instance-state.js";
+import { reclaimPort } from "./port-reclaim.js";
+import { startWebConsoleServer } from "./web-console-server.js";
+
+const DEV_ROUTER_STOP_REASON = "Stopping the dev router because the dev web console exited.";
+
+function normalizeHost(value) {
+  return String(value || "127.0.0.1").trim() || "127.0.0.1";
+}
+
+function shouldRestartStaleDevRouter(runtimeBeforeStart, runtimeAfterStart, snapshot) {
+  if (!runtimeBeforeStart || !runtimeAfterStart || !snapshot?.router?.running) return false;
+  if (Number(runtimeBeforeStart.pid) !== Number(runtimeAfterStart.pid)) return false;
+  if (snapshot?.config?.parseError) return false;
+  if (!Number(snapshot?.config?.providerCount)) return false;
+
+  const localServer = snapshot?.config?.localServer || {};
+  return Number(runtimeAfterStart.port) === Number(localServer.port)
+    && normalizeHost(runtimeAfterStart.host) === normalizeHost(localServer.host);
+}
+
+async function stopDevRouterAfterExit(server, onError) {
+  if (!server || typeof server.stopRouter !== "function") return;
+
+  try {
+    await server.stopRouter({
+      reason: DEV_ROUTER_STOP_REASON,
+      reclaimPortIfStopped: true
+    });
+  } catch (error) {
+    onError(`Failed stopping the dev router during shutdown: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export async function startManagedDevWebConsole(options = {}, deps = {}) {
+  const line = typeof deps.line === "function" ? deps.line : console.log;
+  const error = typeof deps.error === "function" ? deps.error : console.error;
+  const startWebConsoleServerFn = typeof deps.startWebConsoleServer === "function"
+    ? deps.startWebConsoleServer
+    : startWebConsoleServer;
+  const getActiveRuntimeStateFn = typeof deps.getActiveRuntimeState === "function"
+    ? deps.getActiveRuntimeState
+    : getActiveRuntimeState;
+  const reclaimPortFn = typeof deps.reclaimPort === "function"
+    ? deps.reclaimPort
+    : (args) => reclaimPort(args, deps);
+  const serverOptions = {
+    ...options,
+    devMode: true
+  };
+  const runtimeBeforeStart = await getActiveRuntimeStateFn().catch(() => null);
+
+  let server;
+  try {
+    server = await startWebConsoleServerFn(serverOptions);
+  } catch (startError) {
+    if (startError?.code !== "EADDRINUSE") throw startError;
+
+    const reclaimed = await reclaimPortFn({
+      port: serverOptions.port,
+      line,
+      error
+    });
+    if (!reclaimed?.ok) {
+      throw new Error(reclaimed?.errorMessage || `Failed to reclaim port ${serverOptions.port}.`);
+    }
+
+    line(`Port ${serverOptions.port} reclaimed successfully.`);
+    server = await startWebConsoleServerFn(serverOptions);
+  }
+
+  const startupSnapshot = typeof server.getSnapshot === "function"
+    ? await server.getSnapshot().catch(() => null)
+    : null;
+  const runtimeAfterStart = await getActiveRuntimeStateFn().catch(() => null);
+  if (shouldRestartStaleDevRouter(runtimeBeforeStart, runtimeAfterStart, startupSnapshot)
+    && typeof server.restartRouter === "function") {
+    await server.restartRouter(startupSnapshot.config.localServer);
+  }
+
+  let stopRouterPromise = null;
+  const ensureDevRouterStopped = () => {
+    if (stopRouterPromise) return stopRouterPromise;
+    stopRouterPromise = stopDevRouterAfterExit(server, error);
+    return stopRouterPromise;
+  };
+
+  const done = (async () => {
+    let result;
+    try {
+      result = await server.done;
+    } finally {
+      await ensureDevRouterStopped();
+    }
+    return result;
+  })();
+
+  let shutdownPromise = null;
+  const shutdown = async (reason = "dev-console-closed") => {
+    if (shutdownPromise) return shutdownPromise;
+    shutdownPromise = (async () => {
+      await ensureDevRouterStopped();
+      await server.close(reason);
+      return done;
+    })();
+    return shutdownPromise;
+  };
+
+  return {
+    ...server,
+    done,
+    shutdown
+  };
+}