@khanglvm/llm-router 2.0.0-beta.1 → 2.0.0

package/src/cli-entry.js

@@ -55,53 +55,6 @@ function parseBoolean(value, fallback = true) {
   return fallback;
 }
 
-function isBooleanLikeToken(value) {
-  if (value === undefined || value === null) return false;
-  return /^(?:1|0|true|false|yes|no|y|n|on|off)$/i.test(String(value).trim());
-}
-
-function readRawFlagValue(argv, flagName) {
-  const prefix = `--${flagName}`;
-
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === prefix) {
-      const next = argv[index + 1];
-      if (isBooleanLikeToken(next)) {
-        return next;
-      }
-      return true;
-    }
-    if (token.startsWith(`${prefix}=`)) {
-      return token.slice(prefix.length + 1);
-    }
-  }
-
-  return undefined;
-}
-
-function stripFlagFromArgv(argv, flagName) {
-  const prefix = `--${flagName}`;
-  const nextArgv = [];
-
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === prefix) {
-      const next = argv[index + 1];
-      if (isBooleanLikeToken(next)) {
-        index += 1;
-      }
-      continue;
-    }
-    if (token.startsWith(`${prefix}=`)) {
-      continue;
-    }
-    nextArgv.push(token);
-  }
-
-  return nextArgv;
-}
-
 function hasExplicitConfigOperation(args = {}) {
   return Boolean(String(args.operation || args.op || "").trim());
 }
@@ -142,7 +95,7 @@ async function promptStartupConflictResolution({ port }) {
 
   const lines = [
     "",
-    `Port ${port} is already used by the llm-router startup service.`,
+    `Port ${port} is already used by the LLM Router startup service.`,
     "Choose an action:",
     "1. Restart service",
     "2. Run here instead",
@@ -184,34 +137,6 @@ async function runStartFastPath(args) {
   return result.exitCode ?? (result.ok ? 0 : 1);
 }
 
-export function shouldExitTuiOnKeypress(character, key = {}) {
-  const sequence = typeof key?.sequence === "string" && key.sequence
-    ? key.sequence
-    : (typeof character === "string" ? character : "");
-  return sequence === "" || (key?.ctrl === true && String(key?.name || "").toLowerCase() === "c");
-}
-
-export function installTuiSigintExitHandler({
-  input = process.stdin,
-  isTTY = Boolean(process.stdout.isTTY && process.stdin?.isTTY),
-  exit = (code) => process.exit(code)
-} = {}) {
-  if (!isTTY || !input || typeof input.on !== "function" || typeof input.off !== "function") {
-    return () => {};
-  }
-
-  const onKeypress = (character, key) => {
-    if (shouldExitTuiOnKeypress(character, key)) {
-      exit(130);
-    }
-  };
-
-  input.on("keypress", onKeypress);
-  return () => {
-    input.off("keypress", onKeypress);
-  };
-}
-
 async function runSnapCli(argv, isTTY) {
   const [{ createRegistry, runSingleModuleCli }, { default: routerModule }] = await Promise.all([
     import("@levu/snap/dist/index.js"),
@@ -219,67 +144,71 @@ async function runSnapCli(argv, isTTY) {
   ]);
 
   const registry = createRegistry([routerModule]);
-  const disposeSigintHandler = installTuiSigintExitHandler({ isTTY });
-  try {
-    return await runSingleModuleCli({
-      registry,
-      argv,
-      moduleId: "router",
-      defaultActionId: "config",
-      helpDefaultTarget: "module",
-      isTTY
-    });
-  } finally {
-    disposeSigintHandler();
-  }
+  return runSingleModuleCli({
+    registry,
+    argv,
+    moduleId: "router",
+    defaultActionId: "config",
+    helpDefaultTarget: "module",
+    isTTY
+  });
 }
 
 export async function runCli(argv = process.argv.slice(2), isTTY = undefined, overrides = {}) {
   const runSnapCliImpl = overrides.runSnapCli || runSnapCli;
   const runStartFastPathImpl = overrides.runStartFastPath || runStartFastPath;
   const runWebCommandImpl = overrides.runWebCommand || runWebCommand;
-  const tuiRequested = parseBoolean(readRawFlagValue(argv, "tui"), false);
-  const normalizedArgv = stripFlagFromArgv(argv, "tui");
-  const parsed = parseSimpleArgs(normalizedArgv);
+  const errorImpl = overrides.error || ((message) => console.error(message));
+  const parsed = parseSimpleArgs(argv);
   const first = parsed.positional[0];
   const firstIsStart = first === "start";
   const firstIsWeb = first === "web";
   const firstIsConfig = first === "config";
+  const firstIsSetup = first === "setup";
   const explicitConfigOperation = hasExplicitConfigOperation(parsed.args);
 
+  if (Object.hasOwn(parsed.args, "tui")) {
+    errorImpl("The TUI flow has been removed. Use `llr` or `llr config` for the web console, or `llr config --operation=...` for direct CLI workflows.");
+    return 1;
+  }
+
   // Bare invocation opens the browser-based console by default.
   if (!first && !parsed.wantsHelp) {
-    if (tuiRequested || explicitConfigOperation) {
-      return runSnapCliImpl(["config", ...normalizedArgv], isTTY);
+    if (explicitConfigOperation) {
+      return runSnapCliImpl(["config", ...argv], isTTY);
     }
     return runWebFastPath(parsed.args, runWebCommandImpl);
   }
 
   // Fast-path explicit local start without loading Snap to minimize startup overhead.
   if (firstIsStart && !parsed.wantsHelp) {
-    const startArgs = normalizedArgv.slice(1);
+    const startArgs = argv.slice(1);
     const parsedStart = parseSimpleArgs(startArgs);
     return runStartFastPathImpl(parsedStart.args);
   }
 
   if (firstIsWeb && !parsed.wantsHelp) {
-    const webArgs = normalizedArgv.slice(1);
+    const webArgs = argv.slice(1);
     const parsedWeb = parseSimpleArgs(webArgs);
     return runWebFastPath(parsedWeb.args, runWebCommandImpl);
   }
 
   if (firstIsConfig && !parsed.wantsHelp && !explicitConfigOperation) {
-    if (tuiRequested) {
-      return runSnapCliImpl(normalizedArgv, isTTY);
-    }
-
-    const configArgs = parseSimpleArgs(normalizedArgv.slice(1));
+    const configArgs = parseSimpleArgs(argv.slice(1));
     return runWebFastPath(configArgs.args, runWebCommandImpl);
   }
 
-  const normalized = [...normalizedArgv];
+  if (firstIsSetup && !parsed.wantsHelp) {
+    const setupArgs = argv.slice(1);
+    const parsedSetup = parseSimpleArgs(setupArgs);
+    if (hasExplicitConfigOperation(parsedSetup.args)) {
+      return runSnapCliImpl(["config", ...setupArgs], isTTY);
+    }
+    return runWebFastPath(parsedSetup.args, runWebCommandImpl);
+  }
+
+  const normalized = [...argv];
   if (normalized[0] === "help") normalized[0] = "--help";
-  if (normalized[0] === "setup") normalized[0] = "config";
   return runSnapCliImpl(normalized, isTTY);
 }
 

package/src/node/activity-log.js

@@ -0,0 +1,119 @@
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+
+export const DEFAULT_ACTIVITY_LOG_FILENAME = ".llm-router.activity.jsonl";
+export const ACTIVITY_LOG_CATEGORIES = Object.freeze({
+  USAGE: "usage",
+  ROUTER: "router"
+});
+
+function normalizeLevel(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (["info", "success", "warn", "error"].includes(normalized)) return normalized;
+  return "info";
+}
+
+function normalizeText(value, fallback = "") {
+  const text = String(value ?? fallback).trim();
+  return text || fallback;
+}
+
+function normalizeCategory(value, source = "", kind = "") {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (normalized === ACTIVITY_LOG_CATEGORIES.USAGE || normalized === ACTIVITY_LOG_CATEGORIES.ROUTER) {
+    return normalized;
+  }
+
+  const normalizedSource = String(source || "").trim().toLowerCase();
+  const normalizedKind = String(kind || "").trim().toLowerCase();
+  if (normalizedSource === "runtime" || normalizedKind.startsWith("request") || normalizedKind.startsWith("fallback")) {
+    return ACTIVITY_LOG_CATEGORIES.USAGE;
+  }
+  return ACTIVITY_LOG_CATEGORIES.ROUTER;
+}
+
+export function resolveActivityLogPath(configPath = "", explicitPath = "") {
+  const override = String(explicitPath || "").trim();
+  if (override) return path.resolve(override);
+
+  const resolvedConfigPath = String(configPath || "").trim();
+  if (resolvedConfigPath) {
+    const absoluteConfigPath = path.resolve(resolvedConfigPath);
+    const configDir = path.dirname(absoluteConfigPath);
+    const configName = path.basename(absoluteConfigPath);
+    const stem = configName
+      .replace(/\.[^.]+$/, "")
+      .replace(/[^A-Za-z0-9._-]+/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-+|-+$/g, "");
+    return path.join(configDir, `.${stem || "llm-router"}.activity.jsonl`);
+  }
+
+  return path.join(os.homedir(), DEFAULT_ACTIVITY_LOG_FILENAME);
+}
+
+export function createActivityLogEntry({
+  id = "",
+  time = "",
+  level = "info",
+  message = "",
+  detail = "",
+  source = "web-console",
+  kind = "",
+  category = ""
+} = {}) {
+  const entryId = normalizeText(id) || `${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+  const entryTime = normalizeText(time) || new Date().toISOString();
+  const normalizedSource = normalizeText(source, "web-console");
+  const normalizedKind = normalizeText(kind);
+
+  return {
+    id: entryId,
+    time: entryTime,
+    level: normalizeLevel(level),
+    message: normalizeText(message),
+    detail: normalizeText(detail),
+    source: normalizedSource,
+    kind: normalizedKind,
+    category: normalizeCategory(category, normalizedSource, normalizedKind)
+  };
+}
+
+export async function appendActivityLogEntry(filePath, entry) {
+  const targetPath = resolveActivityLogPath("", filePath);
+  const normalized = createActivityLogEntry(entry);
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.appendFile(targetPath, `${JSON.stringify(normalized)}\n`, { encoding: "utf8", mode: 0o600 });
+  return normalized;
+}
+
+export async function readActivityLogEntries(filePath, { limit = 150 } = {}) {
+  const targetPath = resolveActivityLogPath("", filePath);
+  try {
+    const raw = await fs.readFile(targetPath, "utf8");
+    const entries = raw
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return createActivityLogEntry(JSON.parse(line));
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+    return entries.slice(-Math.max(1, limit)).reverse();
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+
+export async function clearActivityLogFile(filePath) {
+  const targetPath = resolveActivityLogPath("", filePath);
+  await fs.rm(targetPath, { force: true });
+}

package/src/node/coding-tool-config.js

@@ -1,6 +1,14 @@
 import os from "node:os";
 import path from "node:path";
 import { promises as fs } from "node:fs";
+import {
+  CODEX_CLI_INHERIT_MODEL_VALUE,
+  isCodexCliInheritModelBinding,
+  mapClaudeCodeThinkingLevelToTokens,
+  mapClaudeCodeThinkingTokensToLevel,
+  normalizeClaudeCodeThinkingLevel,
+  normalizeCodexCliReasoningEffort
+} from "../shared/coding-tool-bindings.js";
 
 const BACKUP_SUFFIX = ".llm_router_backup";
 const CODEX_PROVIDER_ID = "llm-router";
@@ -12,7 +20,8 @@ const CLAUDE_MANAGED_ENV_KEYS = Object.freeze([
   "ANTHROPIC_DEFAULT_OPUS_MODEL",
   "ANTHROPIC_DEFAULT_SONNET_MODEL",
   "ANTHROPIC_DEFAULT_HAIKU_MODEL",
-  "CLAUDE_CODE_SUBAGENT_MODEL"
+  "CLAUDE_CODE_SUBAGENT_MODEL",
+  "MAX_THINKING_TOKENS"
 ]);
 const CLAUDE_BACKUP_ENV_KEYS = Object.freeze([
   ...CLAUDE_MANAGED_ENV_KEYS,
@@ -66,6 +75,13 @@ function normalizeModelBinding(value) {
   return String(value || "").trim();
 }
 
+function areResolvedFilePathsEqual(left, right) {
+  const leftText = String(left || "").trim();
+  const rightText = String(right || "").trim();
+  if (!leftText || !rightText) return false;
+  return path.resolve(leftText) === path.resolve(rightText);
+}
+
 function backupHasData(backup) {
   return Boolean(backup && typeof backup === "object" && !Array.isArray(backup) && Object.keys(backup).length > 0);
 }
@@ -321,14 +337,19 @@ function normalizeClaudeBindings(bindings = {}) {
     defaultOpusModel: normalizeModelBinding(source.defaultOpusModel),
     defaultSonnetModel: normalizeModelBinding(source.defaultSonnetModel),
     defaultHaikuModel: normalizeModelBinding(source.defaultHaikuModel),
-    subagentModel: normalizeModelBinding(source.subagentModel)
+    subagentModel: normalizeModelBinding(source.subagentModel),
+    thinkingLevel: normalizeClaudeCodeThinkingLevel(source.thinkingLevel)
   };
 }
 
 function normalizeCodexBindings(bindings = {}) {
   const source = bindings && typeof bindings === "object" && !Array.isArray(bindings) ? bindings : {};
+  const defaultModel = normalizeModelBinding(source.defaultModel);
   return {
-    defaultModel: normalizeModelBinding(source.defaultModel)
+    defaultModel: isCodexCliInheritModelBinding(defaultModel)
+      ? CODEX_CLI_INHERIT_MODEL_VALUE
+      : defaultModel,
+    thinkingLevel: normalizeCodexCliReasoningEffort(source.thinkingLevel)
   };
 }
 
@@ -339,6 +360,7 @@ function captureCodexBackup(document) {
     version: 1,
     modelProvider: getTopLevelTomlStringField(document, "model_provider"),
     model: getTopLevelTomlStringField(document, "model"),
+    modelReasoningEffort: getTopLevelTomlStringField(document, "model_reasoning_effort"),
     modelCatalogJson: getTopLevelTomlStringField(document, "model_catalog_json"),
     providerSection: {
       exists: Boolean(providerSection),
@@ -354,6 +376,9 @@ function applyCodexBackup(document, backup = {}) {
   if (backup?.model?.exists) setTopLevelTomlStringField(document, "model", backup.model.value);
   else deleteTopLevelTomlField(document, "model");
 
+  if (backup?.modelReasoningEffort?.exists) setTopLevelTomlStringField(document, "model_reasoning_effort", backup.modelReasoningEffort.value);
+  else deleteTopLevelTomlField(document, "model_reasoning_effort");
+
   if (backup?.modelCatalogJson?.exists) setTopLevelTomlStringField(document, "model_catalog_json", backup.modelCatalogJson.value);
   else deleteTopLevelTomlField(document, "model_catalog_json");
 
@@ -415,7 +440,10 @@ function sanitizeBackup(backup, tool) {
 }
 
 export function resolveCodingToolBackupFilePath(configFilePath = "") {
-  return `${path.resolve(String(configFilePath || "").trim())}${BACKUP_SUFFIX}`;
+  const resolvedPath = path.resolve(String(configFilePath || "").trim());
+  const parsed = path.parse(resolvedPath);
+  if (!parsed.ext) return `${resolvedPath}${BACKUP_SUFFIX}`;
+  return path.join(parsed.dir, `${parsed.name}${BACKUP_SUFFIX}${parsed.ext}`);
 }
 
 export function resolveCodexCliConfigFilePath({
@@ -504,6 +532,8 @@ export async function readCodexCliRoutingState({
   const document = splitTomlDocument(configState.text);
   const modelProvider = getTopLevelTomlStringField(document, "model_provider");
   const model = getTopLevelTomlStringField(document, "model");
+  const modelReasoningEffort = getTopLevelTomlStringField(document, "model_reasoning_effort");
+  const modelCatalogJson = getTopLevelTomlStringField(document, "model_catalog_json");
   const providerSection = parseTomlSectionKeyValues(getTomlSection(document, `model_providers.${CODEX_PROVIDER_ID}`));
   const configuredBaseUrl = String(providerSection.base_url || "").trim();
   const configuredBearerToken = String(providerSection.experimental_bearer_token || "").trim();
@@ -512,6 +542,12 @@ export async function readCodexCliRoutingState({
       && modelProvider.value === CODEX_PROVIDER_ID
       && configuredBaseUrl === expectedBaseUrl
   );
+  const routerCatalogPath = resolveCodexCliModelCatalogFilePath({
+    configFilePath: resolvedConfigPath,
+    env,
+    homeDir
+  });
+  const usingRouterManagedCatalog = areResolvedFilePathsEqual(modelCatalogJson.value, routerCatalogPath);
 
   return {
     tool: "codex-cli",
@@ -522,8 +558,15 @@ export async function readCodexCliRoutingState({
     routedViaRouter,
     configuredBaseUrl,
     modelProvider: modelProvider.value,
+    configuredModel: model.value,
+    configuredThinkingLevel: modelReasoningEffort.value,
+    configuredModelCatalogJson: modelCatalogJson.value,
+    inheritCliModel: routedViaRouter && !usingRouterManagedCatalog,
     bindings: {
-      defaultModel: model.value
+      defaultModel: routedViaRouter && !usingRouterManagedCatalog
+        ? CODEX_CLI_INHERIT_MODEL_VALUE
+        : model.value,
+      thinkingLevel: modelReasoningEffort.value
     }
   };
 }
@@ -563,6 +606,8 @@ export async function patchCodexCliConfigFile({
   const document = splitTomlDocument(configState.text);
   const backupState = await ensureToolBackupFileExists(resolvedBackupPath);
   const existingBackup = sanitizeBackup(backupState.data, "codex-cli");
+  const currentModelCatalogJson = getTopLevelTomlStringField(document, "model_catalog_json");
+  const currentlyUsingRouterManagedCatalog = areResolvedFilePathsEqual(currentModelCatalogJson.value, resolvedCatalogPath);
 
   if (captureBackup && !backupHasData(existingBackup)) {
     const backup = configState.existed ? captureCodexBackup(document) : {};
@@ -570,26 +615,50 @@ export async function patchCodexCliConfigFile({
   }
 
   setTopLevelTomlStringField(document, "model_provider", CODEX_PROVIDER_ID);
-  if (normalizedBindings.defaultModel) setTopLevelTomlStringField(document, "model", normalizedBindings.defaultModel);
+  if (isCodexCliInheritModelBinding(normalizedBindings.defaultModel)) {
+    if (currentlyUsingRouterManagedCatalog) {
+      if (existingBackup?.model?.exists) setTopLevelTomlStringField(document, "model", existingBackup.model.value);
+      else deleteTopLevelTomlField(document, "model");
+
+      if (existingBackup?.modelCatalogJson?.exists) {
+        setTopLevelTomlStringField(document, "model_catalog_json", existingBackup.modelCatalogJson.value);
+      } else {
+        deleteTopLevelTomlField(document, "model_catalog_json");
+      }
+    }
+  } else if (normalizedBindings.defaultModel) {
+    setTopLevelTomlStringField(document, "model", normalizedBindings.defaultModel);
+  } else {
+    deleteTopLevelTomlField(document, "model");
+  }
+  if (normalizedBindings.thinkingLevel) {
+    setTopLevelTomlStringField(document, "model_reasoning_effort", normalizedBindings.thinkingLevel);
+  } else {
+    deleteTopLevelTomlField(document, "model_reasoning_effort");
+  }
   setTomlSection(document, `model_providers.${CODEX_PROVIDER_ID}`, createCodexProviderSection({
     baseUrl,
     apiKey: normalizedApiKey
   }));
-  if (normalizedModelCatalog) {
-    if (normalizedModelCatalog.models.length > 0) {
+  if (!isCodexCliInheritModelBinding(normalizedBindings.defaultModel)) {
+    if (normalizedModelCatalog?.models?.length > 0) {
       await writeJsonObjectFile(resolvedCatalogPath, normalizedModelCatalog);
       setTopLevelTomlStringField(document, "model_catalog_json", resolvedCatalogPath);
     } else {
       deleteTopLevelTomlField(document, "model_catalog_json");
-      await fs.rm(resolvedCatalogPath, { force: true });
     }
   }
 
   await writeTextFile(resolvedConfigPath, serializeTomlDocument(document));
+  const finalModelCatalogJson = getTopLevelTomlStringField(document, "model_catalog_json");
+  const usingRouterManagedCatalog = areResolvedFilePathsEqual(finalModelCatalogJson.value, resolvedCatalogPath);
+  if (!usingRouterManagedCatalog) {
+    await fs.rm(resolvedCatalogPath, { force: true });
+  }
   return {
     configFilePath: resolvedConfigPath,
     backupFilePath: resolvedBackupPath,
-    modelCatalogFilePath: normalizedModelCatalog?.models?.length > 0 ? resolvedCatalogPath : "",
+    modelCatalogFilePath: usingRouterManagedCatalog ? resolvedCatalogPath : "",
     configCreated: !configState.existed,
     baseUrl,
     bindings: normalizedBindings
@@ -663,7 +732,8 @@ export async function readClaudeCodeRoutingState({
       defaultOpusModel: envConfig.ANTHROPIC_DEFAULT_OPUS_MODEL,
       defaultSonnetModel: envConfig.ANTHROPIC_DEFAULT_SONNET_MODEL,
       defaultHaikuModel: envConfig.ANTHROPIC_DEFAULT_HAIKU_MODEL,
-      subagentModel: envConfig.CLAUDE_CODE_SUBAGENT_MODEL
+      subagentModel: envConfig.CLAUDE_CODE_SUBAGENT_MODEL,
+      thinkingLevel: mapClaudeCodeThinkingTokensToLevel(envConfig.MAX_THINKING_TOKENS)
     })
   };
 }
@@ -728,6 +798,10 @@ export async function patchClaudeCodeSettingsFile({
   if (normalizedBindings.subagentModel) nextSettings.env.CLAUDE_CODE_SUBAGENT_MODEL = normalizedBindings.subagentModel;
   else delete nextSettings.env.CLAUDE_CODE_SUBAGENT_MODEL;
 
+  const maxThinkingTokens = mapClaudeCodeThinkingLevelToTokens(normalizedBindings.thinkingLevel);
+  if (maxThinkingTokens) nextSettings.env.MAX_THINKING_TOKENS = maxThinkingTokens;
+  else delete nextSettings.env.MAX_THINKING_TOKENS;
+
   await writeJsonObjectFile(resolvedSettingsPath, nextSettings);
   return {
     settingsFilePath: resolvedSettingsPath,

package/src/node/config-workflows.js

@@ -12,6 +12,11 @@ function dedupe(values) {
   return [...new Set((values || []).filter(Boolean).map((value) => String(value).trim()).filter(Boolean))];
 }
 
+function normalizePositiveInteger(value) {
+  const parsed = Number.parseInt(String(value ?? "").trim(), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
 function normalizeProviderType(value) {
   const normalized = String(value || "").trim().toLowerCase();
   return normalized === PROVIDER_TYPE_SUBSCRIPTION ? PROVIDER_TYPE_SUBSCRIPTION : undefined;
@@ -67,22 +72,47 @@ function normalizeModelArray(models) {
       if (!id) return null;
       const formats = dedupe(entry.formats || entry.format || []).filter((value) => value === "openai" || value === "claude");
       const variant = typeof entry.variant === "string" ? entry.variant.trim() : "";
+      const contextWindow = normalizePositiveInteger(
+        entry.contextWindow
+        ?? entry.context_window
+        ?? entry.contextLimit
+        ?? entry.context_limit
+      );
       return {
         id,
         ...(formats.length > 0 ? { formats } : {}),
-        ...(variant ? { variant } : {})
+        ...(variant ? { variant } : {}),
+        ...(contextWindow ? { contextWindow } : {})
       };
     })
     .filter(Boolean);
 }
 
-function buildModelsWithPreferredFormat(modelIds, modelSupport = {}, modelPreferredFormat = {}) {
+function normalizeModelContextWindows(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+  return Object.fromEntries(
+    Object.entries(input)
+      .map(([modelId, value]) => [String(modelId || "").trim(), normalizePositiveInteger(value)])
+      .filter(([modelId, contextWindow]) => Boolean(modelId && contextWindow))
+  );
+}
+
+function buildModelsWithPreferredFormat(modelIds, modelSupport = {}, modelPreferredFormat = {}, modelContextWindows = {}) {
   return normalizeModelArray(modelIds.map((id) => {
     const preferred = modelPreferredFormat[id];
+    const contextWindow = normalizePositiveInteger(modelContextWindows[id]);
     if (preferred) {
-      return { id, formats: [preferred] };
+      return {
+        id,
+        formats: [preferred],
+        ...(contextWindow ? { contextWindow } : {})
+      };
     }
-    return { id, formats: modelSupport[id] || [] };
+    return {
+      id,
+      formats: modelSupport[id] || [],
+      ...(contextWindow ? { contextWindow } : {})
+    };
   }));
 }
 
@@ -107,6 +137,10 @@ export function buildProviderFromConfigInput(input) {
   ).trim() || "default";
   const baseUrlByFormat = normalizeBaseUrlByFormatInput(input);
   const explicitModelIds = parseModelListInput(input.models);
+  const modelContextWindows = normalizeModelContextWindows(
+    input.modelContextWindows
+    || input["model-context-windows"]
+  );
   const probeModelSupport = input.probe?.modelSupport && typeof input.probe.modelSupport === "object"
     ? input.probe.modelSupport
     : {};
@@ -114,10 +148,10 @@ export function buildProviderFromConfigInput(input) {
     ? input.probe.modelPreferredFormat
     : {};
   const explicitModels = explicitModelIds.length > 0
-    ? buildModelsWithPreferredFormat(explicitModelIds, probeModelSupport, probeModelPreferredFormat)
+    ? buildModelsWithPreferredFormat(explicitModelIds, probeModelSupport, probeModelPreferredFormat, modelContextWindows)
     : [];
   const probeModels = input.probe?.models?.length
-    ? buildModelsWithPreferredFormat(input.probe.models, probeModelSupport, probeModelPreferredFormat)
+    ? buildModelsWithPreferredFormat(input.probe.models, probeModelSupport, probeModelPreferredFormat, modelContextWindows)
     : [];
   const mergedModels = explicitModels.length > 0 ? explicitModels : probeModels;
   const endpointFormats = baseUrlByFormat ? Object.keys(baseUrlByFormat) : [];
@@ -185,12 +219,17 @@ function mergeProviderModelsWithExistingFallbacks(existingProvider, incomingProv
   const mergedModels = (incomingProvider?.models || []).map((model) => {
     const previous = existingModelById.get(model.id);
     const hasExplicitFallbacks = Object.prototype.hasOwnProperty.call(model, "fallbackModels");
-    if (hasExplicitFallbacks || !previous) return model;
-    if (!Object.prototype.hasOwnProperty.call(previous, "fallbackModels")) return model;
-    return {
-      ...model,
-      fallbackModels: previous.fallbackModels || []
-    };
+    const hasExplicitContextWindow = Object.prototype.hasOwnProperty.call(model, "contextWindow");
+    if (!previous) return model;
+
+    const nextModel = { ...model };
+    if (!hasExplicitFallbacks && Object.prototype.hasOwnProperty.call(previous, "fallbackModels")) {
+      nextModel.fallbackModels = previous.fallbackModels || [];
+    }
+    if (!hasExplicitContextWindow && Number.isFinite(Number(previous?.contextWindow))) {
+      nextModel.contextWindow = Number(previous.contextWindow);
+    }
+    return nextModel;
   });
 
   return {

package/src/node/instance-state.js

@@ -249,7 +249,7 @@ export function spawnStartProcess({
   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.");
+  if (!finalCliPath) throw new Error("Cannot spawn LLM Router start: CLI path is unknown.");
 
   const args = [
     finalCliPath,