@khanglvm/llm-router 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -10,6 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Raised the default inbound JSON body limit for OpenAI `/responses` requests from `1 MiB` to `8 MiB` while keeping other JSON routes at `1 MiB`. This prevents local `413 Request body too large` failures for Codex CLI and other Responses API clients carrying larger conversation state.
 
+## [2.0.1] - 2026-03-15
+
+### Fixed
+- Fixed alias-route failover after transient upstream failures. When every candidate on a route was only in cooldown, the balancer now retries the earliest-recovering candidate instead of returning `No eligible providers remain for route ...`.
+
 ## [2.0.0] - 2026-03-15
 
 ### Changed

package/README.md

@@ -14,7 +14,7 @@ The primary CLI command is now:
 llr
 ```
 
-`2.0.0` is the current public release. It includes the Web UI, AMP routing, and coding-tool integrations introduced in the 2.x line.
+`2.0.1` is the current public release. It includes the Web UI, AMP routing, and coding-tool integrations introduced in the 2.x line.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/llm-router",
-  "version": "2.0.0",
+  "version": "2.0.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/startup-manager.js

@@ -11,6 +11,20 @@ import { FIXED_LOCAL_ROUTER_HOST, FIXED_LOCAL_ROUTER_PORT } from "./local-server
 
 const SERVICE_NAME = "llm-router";
 const LAUNCH_AGENT_ID = "dev.llm-router";
+const STARTUP_ENV_PASSTHROUGH_KEYS = [
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "all_proxy",
+  "no_proxy",
+  "npm_config_cafile"
+];
 
 function resolveDarwinDomain() {
   const uid = process.getuid?.();
@@ -83,13 +97,48 @@ function isMissingServiceMessage(value) {
     || text.includes("unit llm-router.service could not be found");
 }
 
+function escapeXml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+export function buildStartupEnvironment(env = process.env) {
+  const configuredCliPath = String(env?.LLM_ROUTER_CLI_PATH || "").trim();
+  const startupEnv = {
+    LLM_ROUTER_MANAGED_BY_STARTUP: "1",
+    LLM_ROUTER_CLI_PATH: configuredCliPath || String(resolveStartupCliEntryPath({ env }) || "").trim()
+  };
+
+  for (const key of STARTUP_ENV_PASSTHROUGH_KEYS) {
+    const value = String(env?.[key] || "").trim();
+    if (!value) continue;
+    startupEnv[key] = value;
+  }
+
+  return startupEnv;
+}
+
 function buildLaunchAgentPlist({ nodePath, cliPath, configPath, host, port, watchConfig, watchBinary, requireAuth }) {
   const logDir = path.join(os.homedir(), "Library", "Logs");
   const stdoutPath = path.join(logDir, "llm-router.out.log");
   const stderrPath = path.join(logDir, "llm-router.err.log");
   const args = [nodePath, cliPath, ...makeExecArgs({ configPath, host, port, watchConfig, watchBinary, requireAuth })];
+  const environment = {
+    ...buildStartupEnvironment({
+      ...process.env,
+      LLM_ROUTER_CLI_PATH: cliPath
+    }),
+    LLM_ROUTER_CLI_PATH: cliPath
+  };
 
-  const xmlArgs = args.map((arg) => `    <string>${arg}</string>`).join("\n");
+  const xmlArgs = args.map((arg) => `    <string>${escapeXml(arg)}</string>`).join("\n");
+  const xmlEnvironment = Object.entries(environment)
+    .map(([key, value]) => `      <key>${escapeXml(key)}</key>\n      <string>${escapeXml(value)}</string>`)
+    .join("\n");
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -107,17 +156,14 @@ ${xmlArgs}
     <true/>
     <key>EnvironmentVariables</key>
     <dict>
-      <key>LLM_ROUTER_MANAGED_BY_STARTUP</key>
-      <string>1</string>
-      <key>LLM_ROUTER_CLI_PATH</key>
-      <string>${cliPath}</string>
+${xmlEnvironment}
     </dict>
     <key>StandardOutPath</key>
-    <string>${stdoutPath}</string>
+    <string>${escapeXml(stdoutPath)}</string>
     <key>StandardErrorPath</key>
-    <string>${stderrPath}</string>
+    <string>${escapeXml(stderrPath)}</string>
     <key>WorkingDirectory</key>
-    <string>${process.cwd()}</string>
+    <string>${escapeXml(process.cwd())}</string>
   </dict>
 </plist>
 `;
@@ -126,6 +172,17 @@ ${xmlArgs}
 function buildSystemdService({ nodePath, cliPath, configPath, host, port, watchConfig, watchBinary, requireAuth }) {
   const execArgs = makeExecArgs({ configPath, host, port, watchConfig, watchBinary, requireAuth }).map(quoteArg).join(" ");
   const execStart = `${quoteArg(nodePath)} ${quoteArg(cliPath)} ${execArgs}`;
+  const environment = {
+    ...buildStartupEnvironment({
+      ...process.env,
+      LLM_ROUTER_CLI_PATH: cliPath
+    }),
+    LLM_ROUTER_CLI_PATH: cliPath,
+    NODE_ENV: "production"
+  };
+  const systemdEnvironment = Object.entries(environment)
+    .map(([key, value]) => `Environment=${key}=${value}`)
+    .join("\n");
 
   return `[Unit]
 Description=LLM Router local route
@@ -136,9 +193,7 @@ Type=simple
 ExecStart=${execStart}
 Restart=always
 RestartSec=2
-Environment=NODE_ENV=production
-Environment=LLM_ROUTER_MANAGED_BY_STARTUP=1
-Environment=LLM_ROUTER_CLI_PATH=${cliPath}
+${systemdEnvironment}
 WorkingDirectory=${process.cwd()}
 
 [Install]

package/src/runtime/balancer.js

@@ -186,6 +186,19 @@ function sortEntriesByOriginalOrder(left, right) {
   return left.originalIndex - right.originalIndex;
 }
 
+function sortCooldownEntries(left, right) {
+  if (left.openUntil !== right.openUntil) {
+    return left.openUntil - right.openUntil;
+  }
+  return sortEntriesByOriginalOrder(left, right);
+}
+
+function isCooldownOnlyEntry(entry) {
+  if (!entry || entry.eligible) return false;
+  const reasons = Array.isArray(entry.skipReasons) ? entry.skipReasons : [];
+  return reasons.length > 0 && reasons.every((reason) => reason === "cooldown");
+}
+
 async function buildCandidateEntries({
   candidates,
   stateStore,
@@ -315,6 +328,19 @@ export async function rankRouteCandidates({
   const ineligibleEntries = entries
     .filter((entry) => !entry.eligible)
     .sort(sortEntriesByOriginalOrder);
+  const fallbackCooldownEntries = eligibleEntries.length === 0
+    ? ineligibleEntries
+      .filter((entry) => isCooldownOnlyEntry(entry))
+      .sort(sortCooldownEntries)
+      .map((entry) => ({
+        ...entry,
+        eligible: true,
+        skipReasons: [...entry.skipReasons, "cooldown-overridden"]
+      }))
+    : [];
+  const skippedIneligibleEntries = fallbackCooldownEntries.length > 0
+    ? ineligibleEntries.filter((entry) => !isCooldownOnlyEntry(entry))
+    : ineligibleEntries;
   const estimatedRequiredTokens = normalizeNonNegativeInteger(
     requestContext?.estimatedRequiredTokens ??
     requestContext?.requiredTokens ??
@@ -324,10 +350,13 @@ export async function rankRouteCandidates({
   const routeCursor = stateStore
     ? await stateStore.getRouteCursor(resolvedRouteKey)
     : 0;
+  const rankableEntries = fallbackCooldownEntries.length > 0
+    ? fallbackCooldownEntries
+    : eligibleEntries;
   const contextAwareGroups = shouldApplyContextAwareOrdering(route, estimatedRequiredTokens)
-    ? partitionEligibleEntriesByContextWindow(eligibleEntries, estimatedRequiredTokens)
+    ? partitionEligibleEntriesByContextWindow(rankableEntries, estimatedRequiredTokens)
     : {
-        prioritizedEntries: eligibleEntries,
+        prioritizedEntries: rankableEntries,
         deferredEntries: []
       };
   const ranking = rankEligibleEntries(
@@ -339,7 +368,7 @@ export async function rankRouteCandidates({
   const rankedEntries = [
     ...ranking.orderedEligible,
     ...contextAwareGroups.deferredEntries,
-    ...ineligibleEntries
+    ...skippedIneligibleEntries
   ];
 
   return {
@@ -351,7 +380,7 @@ export async function rankRouteCandidates({
     shouldAdvanceCursor: ranking.shouldAdvanceCursor,
     entries: rankedEntries,
     selectedEntry: ranking.orderedEligible[0] || null,
-    skippedEntries: ineligibleEntries,
+    skippedEntries: skippedIneligibleEntries,
     rankedCandidates: rankedEntries.map((entry) => entry.candidate)
   };
 }