@khanglvm/llm-router 1.3.1 → 2.0.0-beta.0

package/src/node/config-store.js

@@ -11,6 +11,7 @@ import {
   migrateRuntimeConfig,
   normalizeRuntimeConfig
 } from "../runtime/config.js";
+import { sanitizePersistedLocalServerConfig } from "./local-server-settings.js";
 
 export const DEFAULT_CONFIG_FILENAME = ".llm-router.json";
 
@@ -18,40 +19,70 @@ export function getDefaultConfigPath() {
   return path.join(os.homedir(), DEFAULT_CONFIG_FILENAME);
 }
 
-export async function readConfigFile(filePath = getDefaultConfigPath(), options = {}) {
+function normalizePersistedConfig(config, normalizeOptions = undefined) {
+  return sanitizePersistedLocalServerConfig(
+    normalizeRuntimeConfig(config, normalizeOptions)
+  );
+}
+
+export async function readConfigFileState(filePath = getDefaultConfigPath(), options = {}) {
   const autoMigrate = options.autoMigrate !== false;
   const persistMigrated = options.persistMigrated !== false;
   const migrateToVersion = options && Object.prototype.hasOwnProperty.call(options, "migrateToVersion")
     ? options.migrateToVersion
     : CONFIG_VERSION;
+  const normalizeOptions = autoMigrate ? { migrateToVersion } : undefined;
+
   try {
     const raw = await fs.readFile(filePath, "utf8");
     const parsedRaw = raw.trim() ? JSON.parse(raw) : {};
-    const normalizeOptions = autoMigrate ? { migrateToVersion } : undefined;
-    const normalized = normalizeRuntimeConfig(parsedRaw, normalizeOptions);
-
-    if (autoMigrate && persistMigrated) {
-      const payload = `${JSON.stringify(normalized, null, 2)}\n`;
-      if (payload !== raw) {
-        try {
-          await fs.writeFile(filePath, payload, { encoding: "utf8", mode: 0o600 });
-          await fs.chmod(filePath, 0o600);
-        } catch {
-          // Silent best-effort persistence: keep migrated config in memory even if disk write fails.
-        }
+    const normalized = normalizePersistedConfig(parsedRaw, normalizeOptions);
+    const payload = `${JSON.stringify(normalized, null, 2)}\n`;
+    const changed = payload !== raw;
+    let persisted = false;
+    let persistError;
+
+    if (autoMigrate && persistMigrated && changed) {
+      try {
+        await fs.writeFile(filePath, payload, { encoding: "utf8", mode: 0o600 });
+        await fs.chmod(filePath, 0o600);
+        persisted = true;
+      } catch (error) {
+        persistError = error;
       }
     }
 
-    return normalized;
+    return {
+      config: normalized,
+      exists: true,
+      changed,
+      persisted,
+      persistError,
+      beforeVersion: detectRuntimeConfigVersion(parsedRaw),
+      afterVersion: normalized.version
+    };
   } catch (error) {
     if (error && typeof error === "object" && error.code === "ENOENT") {
-      const normalizeOptions = autoMigrate ? { migrateToVersion } : undefined;
-      return normalizeRuntimeConfig({}, normalizeOptions);
+      const normalized = normalizePersistedConfig({}, normalizeOptions);
+      return {
+        config: normalized,
+        exists: false,
+        changed: false,
+        persisted: false,
+        persistError: undefined,
+        beforeVersion: undefined,
+        afterVersion: normalized.version
+      };
     }
     throw error;
   }
 }
 
+export async function readConfigFile(filePath = getDefaultConfigPath(), options = {}) {
+  const result = await readConfigFileState(filePath, options);
+  return result.config;
+}
+
 export async function configFileExists(filePath = getDefaultConfigPath()) {
   try {
     await fs.access(filePath);
@@ -68,7 +99,7 @@ export async function writeConfigFile(config, filePath = getDefaultConfigPath(),
   const normalizeOptions = options && Object.prototype.hasOwnProperty.call(options, "migrateToVersion")
     ? { migrateToVersion: options.migrateToVersion }
     : undefined;
-  const normalized = normalizeRuntimeConfig(config, normalizeOptions);
+  const normalized = normalizePersistedConfig(config, normalizeOptions);
   const folder = path.dirname(filePath);
   await fs.mkdir(folder, { recursive: true });
   const payload = `${JSON.stringify(normalized, null, 2)}\n`;
@@ -90,7 +121,7 @@ export async function migrateConfigFile(filePath = getDefaultConfigPath(), {
   const rawConfig = rawText.trim() ? JSON.parse(rawText) : {};
   const beforeVersion = detectRuntimeConfigVersion(rawConfig);
   const migratedRaw = migrateRuntimeConfig(rawConfig, { targetVersion });
-  const normalized = normalizeRuntimeConfig(migratedRaw, { migrateToVersion: targetVersion });
+  const normalized = normalizePersistedConfig(migratedRaw, { migrateToVersion: targetVersion });
   const payload = `${JSON.stringify(normalized, null, 2)}\n`;
   const changed = payload !== rawText;
 

package/src/node/instance-state.js

@@ -2,8 +2,10 @@ import os from "node:os";
 import path from "node:path";
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
+import { FIXED_LOCAL_ROUTER_HOST, FIXED_LOCAL_ROUTER_PORT } from "./local-server-settings.js";
 
 const DEFAULT_INSTANCE_STATE_FILENAME = ".llm-router.runtime.json";
+const MAX_START_OUTPUT_CHARS = 4000;
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -25,8 +27,8 @@ function normalizeRuntimeState(raw) {
 
   return {
     pid,
-    host: String(raw.host || "127.0.0.1"),
-    port: Number.isFinite(Number(raw.port)) ? Number(raw.port) : 8787,
+    host: String(raw.host || FIXED_LOCAL_ROUTER_HOST),
+    port: Number.isFinite(Number(raw.port)) ? Number(raw.port) : FIXED_LOCAL_ROUTER_PORT,
     configPath: String(raw.configPath || ""),
     watchConfig: normalizeBoolean(raw.watchConfig, true),
     watchBinary: normalizeBoolean(raw.watchBinary, true),
@@ -38,6 +40,46 @@ function normalizeRuntimeState(raw) {
   };
 }
 
+function normalizeHost(value, fallback = FIXED_LOCAL_ROUTER_HOST) {
+  return String(value || fallback).trim() || fallback;
+}
+
+function normalizeCliPath(value) {
+  const target = String(value || "").trim();
+  if (!target) return "";
+  return path.isAbsolute(target) ? target : path.resolve(target);
+}
+
+function appendRecentOutput(current, chunk, maxChars = MAX_START_OUTPUT_CHARS) {
+  if (!chunk) return current;
+  const combined = `${current}${chunk}`;
+  return combined.length > maxChars ? combined.slice(-maxChars) : combined;
+}
+
+function formatStartFailureMessage(baseMessage, { stderr = "", stdout = "" } = {}) {
+  const detail = String(stderr || "").trim() || String(stdout || "").trim();
+  return detail ? `${baseMessage}\n${detail}` : baseMessage;
+}
+
+function runtimeMatchesStartOptions(runtime, {
+  configPath,
+  host = FIXED_LOCAL_ROUTER_HOST,
+  port = FIXED_LOCAL_ROUTER_PORT,
+  watchConfig = true,
+  watchBinary = true,
+  requireAuth = false
+} = {}) {
+  const normalized = normalizeRuntimeState(runtime);
+  if (!normalized) return false;
+
+  return normalizeHost(normalized.host) === normalizeHost(host)
+    && Number(normalized.port) === Number(port)
+    && String(normalized.configPath || "").trim() === String(configPath || "").trim()
+    && normalized.watchConfig === normalizeBoolean(watchConfig, true)
+    && normalized.watchBinary === normalizeBoolean(watchBinary, true)
+    && normalized.requireAuth === normalizeBoolean(requireAuth, false);
+}
+
 export function getRuntimeStatePath() {
   return path.join(os.homedir(), DEFAULT_INSTANCE_STATE_FILENAME);
 }
@@ -154,8 +196,8 @@ export function buildStartArgsFromState(state) {
   if (!target) {
     return {
       configPath: "",
-      host: "127.0.0.1",
-      port: 8787,
+      host: FIXED_LOCAL_ROUTER_HOST,
+      port: FIXED_LOCAL_ROUTER_PORT,
       watchConfig: true,
       watchBinary: true,
       requireAuth: false
@@ -171,16 +213,42 @@ export function buildStartArgsFromState(state) {
   };
 }
 
-export function spawnDetachedStart({
+export async function waitForRuntimeMatch(options = {}, deps = {}) {
+  const getActiveRuntimeStateFn = typeof deps.getActiveRuntimeState === "function"
+    ? deps.getActiveRuntimeState
+    : getActiveRuntimeState;
+  const timeoutMs = Number.isFinite(Number(deps.timeoutMs)) ? Math.max(250, Number(deps.timeoutMs)) : 8000;
+  const pollIntervalMs = Number.isFinite(Number(deps.pollIntervalMs)) ? Math.max(50, Number(deps.pollIntervalMs)) : 125;
+  const requireManagedByStartup = deps.requireManagedByStartup === true;
+
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    const runtime = await getActiveRuntimeStateFn().catch(() => null);
+    if (runtimeMatchesStartOptions(runtime, options)
+      && (!requireManagedByStartup || runtime?.managedByStartup)) {
+      return runtime;
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  return null;
+}
+
+export function spawnStartProcess({
   cliPath,
   configPath,
-  host = "127.0.0.1",
-  port = 8787,
+  host = FIXED_LOCAL_ROUTER_HOST,
+  port = FIXED_LOCAL_ROUTER_PORT,
   watchConfig = true,
   watchBinary = true,
   requireAuth = false
-}) {
-  const finalCliPath = String(cliPath || process.env.LLM_ROUTER_CLI_PATH || process.argv[1] || "").trim();
+}, {
+  detached = true,
+  stdio = "ignore",
+  unref = false,
+  env = process.env
+} = {}) {
+  const finalCliPath = normalizeCliPath(cliPath || env.LLM_ROUTER_CLI_PATH || process.argv[1] || "");
   if (!finalCliPath) throw new Error("Cannot spawn llm-router start: CLI path is unknown.");
 
   const args = [
@@ -193,14 +261,147 @@ export function spawnDetachedStart({
     `--watch-binary=${watchBinary ? "true" : "false"}`,
     `--require-auth=${requireAuth ? "true" : "false"}`
   ];
+
   const child = spawn(process.execPath, args, {
-    detached: true,
-    stdio: "ignore",
+    detached,
+    stdio,
     env: {
-      ...process.env,
+      ...env,
       LLM_ROUTER_CLI_PATH: finalCliPath
     }
   });
+
+  if (unref) child.unref();
+  return child;
+}
+
+export async function startDetachedRouterService(options = {}, deps = {}) {
+  const getActiveRuntimeStateFn = typeof deps.getActiveRuntimeState === "function"
+    ? deps.getActiveRuntimeState
+    : getActiveRuntimeState;
+  const spawnStartProcessFn = typeof deps.spawnStartProcess === "function"
+    ? deps.spawnStartProcess
+    : spawnStartProcess;
+  const timeoutMs = Number.isFinite(Number(deps.timeoutMs)) ? Math.max(250, Number(deps.timeoutMs)) : 8000;
+  const pollIntervalMs = Number.isFinite(Number(deps.pollIntervalMs)) ? Math.max(50, Number(deps.pollIntervalMs)) : 125;
+
+  let child;
+  try {
+    child = spawnStartProcessFn(options, {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      unref: false,
+      env: deps.env || process.env
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      errorMessage: error instanceof Error ? error.message : String(error)
+    };
+  }
+
+  let childError = null;
+  let childExit = null;
+  let stdout = "";
+  let stderr = "";
+  const onStdout = (chunk) => {
+    stdout = appendRecentOutput(stdout, chunk);
+  };
+  const onStderr = (chunk) => {
+    stderr = appendRecentOutput(stderr, chunk);
+  };
+  child.stdout?.setEncoding?.("utf8");
+  child.stderr?.setEncoding?.("utf8");
+  child.stdout?.on?.("data", onStdout);
+  child.stderr?.on?.("data", onStderr);
+  child.once("error", (error) => {
+    childError = error;
+  });
+  child.once("exit", (code, signal) => {
+    childExit = { code, signal };
+  });
+
+  const cleanupChildIo = () => {
+    child.stdout?.off?.("data", onStdout);
+    child.stderr?.off?.("data", onStderr);
+    child.stdout?.destroy?.();
+    child.stderr?.destroy?.();
+  };
+
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    const runtime = await getActiveRuntimeStateFn().catch(() => null);
+    if (runtimeMatchesStartOptions(runtime, options)) {
+      cleanupChildIo();
+      child.unref();
+      return {
+        ok: true,
+        pid: child.pid,
+        runtime
+      };
+    }
+
+    if (childError) {
+      cleanupChildIo();
+      return {
+        ok: false,
+        errorMessage: formatStartFailureMessage(
+          childError instanceof Error ? childError.message : String(childError),
+          { stderr, stdout }
+        )
+      };
+    }
+
+    if (childExit) {
+      cleanupChildIo();
+      return {
+        ok: false,
+        errorMessage: formatStartFailureMessage(
+          `llm-router exited before becoming ready (${childExit.signal || childExit.code || "unknown"}).`,
+          { stderr, stdout }
+        ),
+        exitCode: childExit.code,
+        signal: childExit.signal || ""
+      };
+    }
+
+    await sleep(pollIntervalMs);
+  }
+
+  cleanupChildIo();
   child.unref();
+  return {
+    ok: false,
+    errorMessage: formatStartFailureMessage(
+      `Timed out waiting for llm-router to start on http://${normalizeHost(options.host)}:${Number(options.port || FIXED_LOCAL_ROUTER_PORT)}.`,
+      { stderr, stdout }
+    ),
+    pid: child.pid
+  };
+}
+
+export function spawnDetachedStart({
+  cliPath,
+  configPath,
+  host = FIXED_LOCAL_ROUTER_HOST,
+  port = FIXED_LOCAL_ROUTER_PORT,
+  watchConfig = true,
+  watchBinary = true,
+  requireAuth = false
+}) {
+  const child = spawnStartProcess({
+    cliPath,
+    configPath,
+    host,
+    port,
+    watchConfig,
+    watchBinary,
+    requireAuth
+  }, {
+    detached: true,
+    stdio: "ignore",
+    unref: true,
+    env: process.env
+  });
   return child.pid;
 }

package/src/node/listen-port.js

@@ -1,43 +1,11 @@
-const DEFAULT_LISTEN_PORT = 8787;
-const MIN_LISTEN_PORT = 1;
-const MAX_LISTEN_PORT = 65535;
+import { FIXED_LOCAL_ROUTER_PORT } from "./local-server-settings.js";
 
-function parsePortValue(value) {
-  if (value === undefined || value === null || value === "") return null;
-  const normalized = String(value).trim();
-  if (!/^\d+$/.test(normalized)) return null;
-
-  const parsed = Number.parseInt(normalized, 10);
-  if (!Number.isInteger(parsed)) return null;
-  if (parsed < MIN_LISTEN_PORT || parsed > MAX_LISTEN_PORT) return null;
-  return parsed;
-}
+const DEFAULT_LISTEN_PORT = FIXED_LOCAL_ROUTER_PORT;
 
 /**
- * Resolve the local listen port using this precedence:
- * 1) explicit CLI/API input
- * 2) LLM_ROUTER_PORT env
- * 3) PORT env (for generic hosting environments)
- * 4) fallback (default 8787)
+ * Resolve the local router listen port.
+ * The router port is currently fixed and user overrides are ignored.
  */
-export function resolveListenPort({
-  explicitPort,
-  env = process.env,
-  fallbackPort = DEFAULT_LISTEN_PORT
-} = {}) {
-  const candidates = [
-    explicitPort,
-    env?.LLM_ROUTER_PORT,
-    env?.PORT,
-    fallbackPort,
-    DEFAULT_LISTEN_PORT
-  ];
-
-  for (const candidate of candidates) {
-    const parsed = parsePortValue(candidate);
-    if (parsed !== null) return parsed;
-  }
-
+export function resolveListenPort() {
   return DEFAULT_LISTEN_PORT;
 }
-

package/src/node/local-server-settings.js

@@ -0,0 +1,122 @@
+import {
+  LOCAL_ROUTER_HOST as FIXED_LOCAL_ROUTER_HOST,
+  LOCAL_ROUTER_PORT as FIXED_LOCAL_ROUTER_PORT,
+  LOCAL_ROUTER_ORIGIN,
+  buildLocalRouterSettings,
+  buildPersistedLocalServerMetadata
+} from "../shared/local-router-defaults.js";
+
+export { FIXED_LOCAL_ROUTER_HOST, FIXED_LOCAL_ROUTER_PORT };
+
+const DEFAULT_LOCAL_SERVER_SETTINGS = Object.freeze(buildLocalRouterSettings());
+
+export function getDefaultLocalServerSettings() {
+  return { ...DEFAULT_LOCAL_SERVER_SETTINGS };
+}
+
+export function getFixedLocalRouterOrigin() {
+  return LOCAL_ROUTER_ORIGIN;
+}
+
+export function readLocalServerSettings(config, fallback = DEFAULT_LOCAL_SERVER_SETTINGS) {
+  return buildLocalRouterSettings(config?.metadata?.localServer, fallback);
+}
+
+export function applyLocalServerSettings(config, settings) {
+  const next = config && typeof config === "object" && !Array.isArray(config)
+    ? JSON.parse(JSON.stringify(config))
+    : {};
+  const resolved = readLocalServerSettings({ metadata: { localServer: settings } }, DEFAULT_LOCAL_SERVER_SETTINGS);
+  const persisted = buildPersistedLocalServerMetadata(resolved);
+  const metadata = next.metadata && typeof next.metadata === "object" && !Array.isArray(next.metadata)
+    ? { ...next.metadata }
+    : {};
+
+  if (Object.keys(persisted).length > 0) {
+    next.metadata = {
+      ...metadata,
+      localServer: persisted
+    };
+  } else if (Object.prototype.hasOwnProperty.call(metadata, "localServer")) {
+    delete metadata.localServer;
+    if (Object.keys(metadata).length > 0) {
+      next.metadata = metadata;
+    } else {
+      delete next.metadata;
+    }
+  }
+
+  return next;
+}
+
+export function sanitizePersistedLocalServerConfig(config) {
+  const next = config && typeof config === "object" && !Array.isArray(config)
+    ? JSON.parse(JSON.stringify(config))
+    : {};
+  const metadata = next.metadata;
+
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return next;
+  }
+
+  const normalizedLocalServer = buildPersistedLocalServerMetadata(metadata.localServer);
+  const nextMetadata = { ...metadata };
+
+  if (Object.keys(normalizedLocalServer).length > 0) {
+    nextMetadata.localServer = normalizedLocalServer;
+  } else {
+    delete nextMetadata.localServer;
+  }
+
+  if (Object.keys(nextMetadata).length > 0) {
+    next.metadata = nextMetadata;
+  } else {
+    delete next.metadata;
+  }
+
+  return next;
+}
+
+export function areLocalServerSettingsEqual(left, right) {
+  const a = readLocalServerSettings({ metadata: { localServer: left } }, DEFAULT_LOCAL_SERVER_SETTINGS);
+  const b = readLocalServerSettings({ metadata: { localServer: right } }, DEFAULT_LOCAL_SERVER_SETTINGS);
+  return a.host === b.host
+    && a.port === b.port
+    && a.watchConfig === b.watchConfig
+    && a.watchBinary === b.watchBinary
+    && a.requireAuth === b.requireAuth;
+}
+
+export function formatStartupLabel(startup = {}) {
+  const managerMap = {
+    launchd: "LaunchAgent",
+    "systemd-user": "Systemd User",
+    unknown: "Startup service",
+    unsupported: "Startup service"
+  };
+  const manager = managerMap[startup.manager] || startup.manager || "Startup service";
+  if (!startup.installed) return `${manager} not installed`;
+  return startup.running ? `${manager} is running` : `${manager} is installed`;
+}
+
+export function formatStartupDetail(startup = {}) {
+  const managerMap = {
+    launchd: "Managed by launchd",
+    "systemd-user": "Managed by systemd --user",
+    unknown: "Managed by startup service",
+    unsupported: "Startup not supported"
+  };
+
+  if (startup.detail && typeof startup.detail === "string") {
+    const text = startup.detail.trim();
+    if (text) {
+      if (text.includes("Could not find service") || text.includes("service could not be found")) {
+        return "No installed startup service was found.";
+      }
+      const compact = text.replace(/\s+/g, " ").trim();
+      if (compact.length <= 140) return compact;
+    }
+  }
+
+  return managerMap[startup.manager] || "Startup service status unavailable";
+}

package/src/node/local-server.js

@@ -8,6 +8,7 @@ import { watch as fsWatch } from "node:fs";
 import { Readable } from "node:stream";
 import { createFetchHandler } from "../runtime/handler.js";
 import { readConfigFile, getDefaultConfigPath } from "./config-store.js";
+import { FIXED_LOCAL_ROUTER_HOST, FIXED_LOCAL_ROUTER_PORT } from "./local-server-settings.js";
 
 const DEFAULT_CONFIG_RELOAD_DEBOUNCE_MS = 300;
 const MAX_CONFIG_RELOAD_DEBOUNCE_MS = 5000;
@@ -233,8 +234,8 @@ async function writeFetchResponseToNode(res, response) {
 }
 
 export async function startLocalRouteServer({
-  port = 8787,
-  host = "127.0.0.1",
+  port = FIXED_LOCAL_ROUTER_PORT,
+  host = FIXED_LOCAL_ROUTER_HOST,
   configPath = getDefaultConfigPath(),
   watchConfig = true,
   configReloadDebounceMs = process.env.LLM_ROUTER_CONFIG_RELOAD_DEBOUNCE_MS,

package/src/node/provider-probe.js

@@ -1039,6 +1039,19 @@ export async function probeProviderEndpointMatrix(options) {
       unresolvedModelSet.delete(modelId);
       break;
     }
+
+    const resolvedFormats = modelFormatsMap[modelId] ? [...modelFormatsMap[modelId]] : [];
+    const resolvedOwner = modelOwnerById.get(modelId) || null;
+    emitProgress({
+      phase: "model-done",
+      model: modelId,
+      confirmed: resolvedFormats.length > 0,
+      formats: resolvedFormats,
+      endpoint: resolvedOwner?.endpoint || null,
+      format: resolvedOwner?.format || null,
+      completedModels: models.length - unresolvedModelSet.size,
+      totalModels: models.length
+    });
   }
 
   for (const row of endpointRows) {