@khanglvm/llm-router 2.2.7 → 2.3.1

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-03-24
+
+### Added
+- **Factory Droid routing** — one-click routing config for Factory Droid via Web UI, CLI (`set-factory-droid-routing`), and automatic sync. Injects a managed `customModels` entry into `~/.factory/settings.json` with backup/restore support, default model binding, and reasoning effort control (off, none, low, medium, high).
+
 ## [2.2.0] - 2026-03-21
 
 ### Added

package/README.md

@@ -28,7 +28,7 @@ llr ai-help  # agent-oriented setup brief
 - **Unified endpoint** — one local gateway that accepts both OpenAI and Anthropic request formats
 - **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, and AMP
+- **Coding tool routing** — one-click routing config for Codex CLI, Claude Code, Factory Droid, and AMP
 - **Web search** — built-in web search for AMP and other router-managed tools
 - **Deployable** — run locally or deploy to Cloudflare Workers
 - **AI-agent friendly** — full CLI parity with `llr config --operation=...` so agents can configure everything programmatically
@@ -59,6 +59,10 @@ Route Claude Code through the gateway with per-tier model bindings.
 
 ![Claude Code Routing](./assets/screenshots/web-ui-claude-code.png)
 
+### Factory Droid
+
+Route Factory Droid through the gateway via a managed custom model entry with reasoning effort control.
+
 ### Web Search
 
 Configure search providers for AMP and other router-managed tools.

package/package.json

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

package/src/cli/router-module.js

@@ -31,13 +31,17 @@ import {
   patchClaudeCodeEffortLevel,
   patchClaudeCodeSettingsFile,
   patchCodexCliConfigFile,
+  patchFactoryDroidSettingsFile,
   readClaudeCodeRoutingState,
   readCodexCliRoutingState,
+  readFactoryDroidRoutingState,
   resolveClaudeCodeSettingsFilePath,
   resolveCodexCliConfigFilePath,
   resolveCodexCliModelCatalogFilePath,
+  resolveFactoryDroidSettingsFilePath,
   unpatchClaudeCodeSettingsFile,
-  unpatchCodexCliConfigFile
+  unpatchCodexCliConfigFile,
+  unpatchFactoryDroidSettingsFile
 } from "../node/coding-tool-config.js";
 import { installStartup, restartStartup, startupStatus, stopStartup, uninstallStartup } from "../node/startup-manager.js";
 import {
@@ -75,7 +79,8 @@ import {
   CODEX_CLI_INHERIT_MODEL_VALUE,
   isCodexCliInheritModelBinding,
   normalizeClaudeCodeEffortLevel,
-  normalizeCodexCliReasoningEffort
+  normalizeCodexCliReasoningEffort,
+  normalizeFactoryDroidReasoningEffort
 } from "../shared/coding-tool-bindings.js";
 import { FORMATS } from "../translator/index.js";
 import {
@@ -3846,11 +3851,27 @@ async function buildCodingToolRoutingSnapshot({
     routedViaRouter: false,
     error: error instanceof Error ? error.message : String(error)
   }));
+  const factoryDroid = await readFactoryDroidRoutingState({
+    settingsFilePath: readArg(args, ["factory-droid-settings-file", "factoryDroidSettingsFile"], ""),
+    endpointUrl
+  }).catch((error) => ({
+    tool: "factory-droid",
+    settingsFilePath: resolveFactoryDroidSettingsFilePath({}),
+    backupFilePath: "",
+    configuredBaseUrl: "",
+    bindings: {
+      defaultModel: "",
+      reasoningEffort: ""
+    },
+    routedViaRouter: false,
+    error: error instanceof Error ? error.message : String(error)
+  }));
   return {
     endpointUrl,
     ampStates,
     codexCli,
     claudeCode,
+    factoryDroid,
     masterKeyConfigured: Boolean(String(config?.masterKey || "").trim())
   };
 }
@@ -3904,6 +3925,18 @@ function buildClaudeCodeStatusSection(state = {}) {
   ]);
 }
 
+function buildFactoryDroidStatusSection(state = {}) {
+  return renderKeyValueSection("Factory Droid", [
+    ["Routed Via Router", formatYesNo(state.routedViaRouter === true)],
+    ["Settings File", state.settingsFilePath || resolveFactoryDroidSettingsFilePath({})],
+    ["Backup File", state.backupFilePath || "(not created)"],
+    ["Base URL", state.configuredBaseUrl || "(not set)"],
+    ["Default Model", state.bindings?.defaultModel || "(not set)"],
+    ["Reasoning Effort", state.bindings?.reasoningEffort || "(not set)"],
+    ["Error", state.error || "(none)"]
+  ]);
+}
+
 function buildProviderDiagnosticOverview(result = {}) {
   return [
     ["Working Formats", (result.workingFormats || []).join(", ") || "(none)"],
@@ -6234,7 +6267,8 @@ async function doToolStatus(context) {
       [
         buildAmpClientStatusSection(snapshot.ampStates),
         buildCodexCliStatusSection(snapshot.codexCli),
-        buildClaudeCodeStatusSection(snapshot.claudeCode)
+        buildClaudeCodeStatusSection(snapshot.claudeCode),
+        buildFactoryDroidStatusSection(snapshot.factoryDroid)
       ]
     )
   };
@@ -6568,6 +6602,85 @@ async function doSetClaudeCodeEffortLevel(context) {
   };
 }
 
+async function doSetFactoryDroidRouting(context) {
+  const args = context.args || {};
+  const configPath = readArg(args, ["config", "configPath"], getDefaultConfigPath());
+  const config = await readConfigFile(configPath);
+  const endpointUrl = String(readArg(args, ["endpoint-url", "endpointUrl"], LOCAL_ROUTER_ORIGIN) || LOCAL_ROUTER_ORIGIN).trim();
+  const settingsFilePath = String(readArg(args, ["factory-droid-settings-file", "factoryDroidSettingsFile"], "") || "").trim();
+  const enabled = parseOptionalBoolean(readArg(args, ["enabled"], undefined)) !== false;
+
+  if (!enabled) {
+    const unpatchResult = await unpatchFactoryDroidSettingsFile({
+      settingsFilePath
+    });
+    return {
+      ok: true,
+      mode: context.mode,
+      exitCode: EXIT_SUCCESS,
+      data: buildOperationReport(
+        "Factory Droid Routing Disabled",
+        [
+          ["Settings File", unpatchResult.settingsFilePath],
+          ["Backup File", unpatchResult.backupFilePath],
+          ["Backup Restored", formatYesNo(unpatchResult.backupRestored === true)]
+        ]
+      )
+    };
+  }
+
+  const existingState = await readFactoryDroidRoutingState({
+    settingsFilePath,
+    endpointUrl
+  });
+  const apiKey = String(
+    readArg(args, ["master-key", "masterKey", "api-key", "apiKey"], config?.masterKey || "") || ""
+  ).trim();
+  if (!apiKey) {
+    return {
+      ok: false,
+      mode: context.mode,
+      exitCode: EXIT_VALIDATION,
+      errorMessage: `master-key (or config.masterKey) is required before routing Factory Droid through ${APP_NAME}.`
+    };
+  }
+
+  const existingBindings = existingState.bindings || {};
+  const bindings = {
+    defaultModel: String(readArg(args, ["default-model", "defaultModel"], undefined) !== undefined
+      ? readArg(args, ["default-model", "defaultModel"], "")
+      : (existingBindings.defaultModel || pickDefaultManagedRoute(config) || "")).trim(),
+    reasoningEffort: normalizeFactoryDroidReasoningEffort(
+      readArg(args, ["reasoning-effort", "reasoningEffort"], undefined) !== undefined
+        ? readArg(args, ["reasoning-effort", "reasoningEffort"], "")
+        : (existingBindings.reasoningEffort || "")
+    )
+  };
+
+  const patchResult = await patchFactoryDroidSettingsFile({
+    settingsFilePath,
+    endpointUrl,
+    apiKey,
+    bindings,
+    captureBackup: true
+  });
+  return {
+    ok: true,
+    mode: context.mode,
+    exitCode: EXIT_SUCCESS,
+    data: buildOperationReport(
+      "Factory Droid Routing Enabled",
+      [
+        ["Settings File", patchResult.settingsFilePath],
+        ["Backup File", patchResult.backupFilePath],
+        ["Base URL", patchResult.baseUrl],
+        ["Default Model", patchResult.bindings?.defaultModel || "(not set)"],
+        ["Reasoning Effort", patchResult.bindings?.reasoningEffort || "(not set)"]
+      ]
+    )
+  };
+}
+
 async function doDiscoverProviderModels(context) {
   const args = context.args || {};
   let headers;
@@ -8433,6 +8546,9 @@ async function runConfigAction(context) {
       return doSetClaudeCodeRouting(context);
     case "set-claude-code-effort-level":
       return doSetClaudeCodeEffortLevel(context);
+    case "set-factory-droid-routing":
+    case "set-factory-droid":
+      return doSetFactoryDroidRouting(context);
     case "discover-provider-models":
       return doDiscoverProviderModels(context);
     case "test-provider":
@@ -9311,6 +9427,12 @@ async function runAiHelpAction(context) {
     `- disable route: ${CLI_COMMAND} config --operation=set-claude-code-routing --enabled=false`,
     `- standalone effort level (no router needed): ${CLI_COMMAND} config --operation=set-claude-code-effort-level --thinking-level=low|medium|high|max`,
     "",
+    "### Factory Droid",
+    "- required_gate=patch_gate_factory_droid=ready",
+    `- enable/update route: ${CLI_COMMAND} config --operation=set-factory-droid-routing --enabled=true --default-model=<target_model_or_group>`,
+    `- optional reasoning: --reasoning-effort=off|none|low|medium|high`,
+    `- disable route: ${CLI_COMMAND} config --operation=set-factory-droid-routing --enabled=false`,
+    "",
     "### Codex CLI",
     "- required_gate=patch_gate_codex_cli=ready",
     "- hard requirement: Codex uses OpenAI Responses API; /openai/v1/responses must be reachable",
@@ -10578,8 +10700,10 @@ const routerModule = {
           { name: "generate-master-key", required: false, description: "Generate a strong master key automatically (set-master-key flow).", example: "--generate-master-key=true" },
           { name: "master-key-length", required: false, description: "Generated master key length (min 24).", example: "--master-key-length=48" },
           { name: "master-key-prefix", required: false, description: "Generated master key prefix.", example: "--master-key-prefix=gw_" },
-          { name: "default-model", required: false, description: `For set-codex-cli-routing: managed route binding, or ${CODEX_CLI_INHERIT_MODEL_VALUE} to keep Codex's own model selection.`, example: "--default-model=chat.default" },
+          { name: "default-model", required: false, description: `For set-codex-cli-routing / set-factory-droid-routing: managed route binding, or ${CODEX_CLI_INHERIT_MODEL_VALUE} to keep Codex's own model selection.`, example: "--default-model=chat.default" },
           { name: "thinking-level", required: false, description: "For set-codex-cli-routing / set-claude-code-routing / set-claude-code-effort-level: reasoning level.", example: "--thinking-level=medium" },
+          { name: "reasoning-effort", required: false, description: "For set-factory-droid-routing: reasoning effort level (off, none, low, medium, high).", example: "--reasoning-effort=medium" },
+          { name: "factory-droid-settings-file", required: false, description: "Explicit Factory Droid settings.json path for routing/status operations.", example: "--factory-droid-settings-file=~/.factory/settings.json" },
           { name: "primary-model", required: false, description: "For set-claude-code-routing: primary ANTHROPIC_MODEL route.", example: "--primary-model=chat.default" },
           { name: "default-opus-model", required: false, description: "For set-claude-code-routing: ANTHROPIC_DEFAULT_OPUS_MODEL route.", example: "--default-opus-model=chat.deep" },
           { name: "default-sonnet-model", required: false, description: "For set-claude-code-routing: ANTHROPIC_DEFAULT_SONNET_MODEL route.", example: "--default-sonnet-model=chat.default" },
@@ -10651,6 +10775,7 @@ const routerModule = {
           `${CLI_COMMAND} config --operation=set-codex-cli-routing --enabled=true --default-model=chat.default`,
           `${CLI_COMMAND} config --operation=set-claude-code-routing --enabled=true --primary-model=chat.default --default-haiku-model=chat.fast`,
           `${CLI_COMMAND} config --operation=set-claude-code-effort-level --thinking-level=high`,
+          `${CLI_COMMAND} config --operation=set-factory-droid-routing --enabled=true --default-model=chat.default --reasoning-effort=medium`,
           `${CLI_COMMAND} config --operation=set-amp-client-routing --enabled=true --amp-client-settings-scope=workspace`,
           `${CLI_COMMAND} config --operation=set-amp-config --patch-amp-client-config=true --amp-client-settings-scope=workspace --amp-client-url=${LOCAL_ROUTER_ORIGIN} --amp-client-api-key=gw_...`,
           `${CLI_COMMAND} config --operation=list-routing`,

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

@@ -10,7 +10,8 @@ import {
   normalizeClaudeCodeThinkingLevel,
   normalizeClaudeCodeEffortLevel,
   migrateLegacyThinkingTokensToEffortLevel,
-  normalizeCodexCliReasoningEffort
+  normalizeCodexCliReasoningEffort,
+  normalizeFactoryDroidReasoningEffort
 } from "../shared/coding-tool-bindings.js";
 
 const BACKUP_SUFFIX = ".llm_router_backup";
@@ -963,3 +964,217 @@ export async function patchClaudeCodeEffortLevel({
     shellProfileUpdated
   };
 }
+
+const FACTORY_DROID_ROUTER_MARKER = "_llmRouterManaged";
+
+function normalizeFactoryDroidBindings(bindings = {}) {
+  const source = bindings && typeof bindings === "object" && !Array.isArray(bindings) ? bindings : {};
+  return {
+    defaultModel: normalizeModelBinding(source.defaultModel),
+    reasoningEffort: normalizeFactoryDroidReasoningEffort(source.reasoningEffort)
+  };
+}
+
+function buildFactoryDroidBaseUrl(endpointUrl) {
+  const normalized = normalizeHttpUrl(endpointUrl);
+  return normalized ? `${normalized}/openai/v1` : "";
+}
+
+function findRouterManagedCustomModelIndex(customModels) {
+  if (!Array.isArray(customModels)) return -1;
+  return customModels.findIndex(
+    (entry) => entry && typeof entry === "object" && entry[FACTORY_DROID_ROUTER_MARKER] === true
+  );
+}
+
+function captureFactoryDroidBackup(config) {
+  const customModels = Array.isArray(config?.customModels) ? config.customModels : [];
+  const model = String(config?.model || "").trim();
+  const reasoningEffort = String(config?.reasoningEffort || "").trim();
+  return {
+    tool: "factory-droid",
+    version: 1,
+    model: { exists: Boolean(model), value: model },
+    reasoningEffort: { exists: Boolean(reasoningEffort), value: reasoningEffort },
+    hadCustomModels: customModels.length > 0
+  };
+}
+
+function applyFactoryDroidBackup(config, backup = {}) {
+  const next = config && typeof config === "object" && !Array.isArray(config)
+    ? structuredClone(config)
+    : {};
+
+  const customModels = Array.isArray(next.customModels) ? [...next.customModels] : [];
+  const routerIndex = findRouterManagedCustomModelIndex(customModels);
+  if (routerIndex >= 0) customModels.splice(routerIndex, 1);
+  if (customModels.length > 0) next.customModels = customModels;
+  else delete next.customModels;
+
+  if (backup?.model?.exists) next.model = backup.model.value;
+  else delete next.model;
+
+  if (backup?.reasoningEffort?.exists) next.reasoningEffort = backup.reasoningEffort.value;
+  else delete next.reasoningEffort;
+
+  return next;
+}
+
+export function resolveFactoryDroidSettingsFilePath({
+  explicitPath = "",
+  homeDir = os.homedir()
+} = {}) {
+  const direct = String(explicitPath || "").trim();
+  if (direct) return path.resolve(direct);
+  return path.join(homeDir, ".factory", "settings.json");
+}
+
+export async function ensureFactoryDroidSettingsFileExists({
+  settingsFilePath = "",
+  backupFilePath = "",
+  homeDir = os.homedir()
+} = {}) {
+  const resolvedSettingsPath = path.resolve(String(settingsFilePath || resolveFactoryDroidSettingsFilePath({ homeDir })).trim());
+  const resolvedBackupPath = path.resolve(String(backupFilePath || resolveCodingToolBackupFilePath(resolvedSettingsPath)).trim());
+  const settingsState = await readJsonObjectFile(resolvedSettingsPath, `Factory Droid settings file '${resolvedSettingsPath}'`);
+  if (!settingsState.existed) {
+    await writeJsonObjectFile(resolvedSettingsPath, {});
+  }
+  await ensureToolBackupFileExists(resolvedBackupPath);
+  return {
+    settingsFilePath: resolvedSettingsPath,
+    backupFilePath: resolvedBackupPath,
+    settingsCreated: !settingsState.existed
+  };
+}
+
+export async function readFactoryDroidRoutingState({
+  settingsFilePath = "",
+  backupFilePath = "",
+  endpointUrl = "",
+  homeDir = os.homedir()
+} = {}) {
+  const resolvedSettingsPath = path.resolve(String(settingsFilePath || resolveFactoryDroidSettingsFilePath({ homeDir })).trim());
+  const resolvedBackupPath = path.resolve(String(backupFilePath || resolveCodingToolBackupFilePath(resolvedSettingsPath)).trim());
+  const expectedBaseUrl = buildFactoryDroidBaseUrl(endpointUrl);
+  const settingsState = await readJsonObjectFile(resolvedSettingsPath, `Factory Droid settings file '${resolvedSettingsPath}'`);
+  const backupState = await readJsonObjectFile(resolvedBackupPath, `Backup file '${resolvedBackupPath}'`);
+  const customModels = Array.isArray(settingsState.data?.customModels) ? settingsState.data.customModels : [];
+  const routerIndex = findRouterManagedCustomModelIndex(customModels);
+  const routerEntry = routerIndex >= 0 ? customModels[routerIndex] : null;
+  const configuredBaseUrl = routerEntry ? String(routerEntry.baseUrl || "").trim() : "";
+  const routedViaRouter = Boolean(
+    expectedBaseUrl
+      && routerEntry
+      && configuredBaseUrl === expectedBaseUrl
+  );
+
+  return {
+    tool: "factory-droid",
+    settingsFilePath: resolvedSettingsPath,
+    backupFilePath: resolvedBackupPath,
+    settingsExists: settingsState.existed,
+    backupExists: backupState.existed,
+    routedViaRouter,
+    configuredBaseUrl,
+    bindings: normalizeFactoryDroidBindings({
+      defaultModel: routerEntry?.model || settingsState.data?.model || "",
+      reasoningEffort: normalizeFactoryDroidReasoningEffort(settingsState.data?.reasoningEffort)
+    })
+  };
+}
+
+export async function patchFactoryDroidSettingsFile({
+  settingsFilePath = "",
+  backupFilePath = "",
+  endpointUrl = "",
+  apiKey = "",
+  bindings = {},
+  captureBackup = true,
+  homeDir = os.homedir()
+} = {}) {
+  const resolvedSettingsPath = path.resolve(String(settingsFilePath || resolveFactoryDroidSettingsFilePath({ homeDir })).trim());
+  const resolvedBackupPath = path.resolve(String(backupFilePath || resolveCodingToolBackupFilePath(resolvedSettingsPath)).trim());
+  const baseUrl = buildFactoryDroidBaseUrl(endpointUrl);
+  const normalizedApiKey = String(apiKey || "").trim();
+  const normalizedBindings = normalizeFactoryDroidBindings(bindings);
+
+  if (!baseUrl) {
+    throw new Error("Factory Droid endpoint URL must be a valid http:// or https:// URL.");
+  }
+  if (!normalizedApiKey) {
+    throw new Error("Factory Droid API key is required.");
+  }
+
+  const settingsState = await readJsonObjectFile(resolvedSettingsPath, `Factory Droid settings file '${resolvedSettingsPath}'`);
+  const backupState = await ensureToolBackupFileExists(resolvedBackupPath);
+  const existingBackup = sanitizeBackup(backupState.data, "factory-droid");
+  const nextSettings = settingsState.data && typeof settingsState.data === "object" && !Array.isArray(settingsState.data)
+    ? structuredClone(settingsState.data)
+    : {};
+
+  if (captureBackup && !backupHasData(existingBackup)) {
+    const backup = settingsState.existed ? captureFactoryDroidBackup(nextSettings) : {};
+    await writeJsonObjectFile(resolvedBackupPath, backup);
+  }
+
+  const customModels = Array.isArray(nextSettings.customModels) ? [...nextSettings.customModels] : [];
+  const routerIndex = findRouterManagedCustomModelIndex(customModels);
+  const routerEntry = {
+    [FACTORY_DROID_ROUTER_MARKER]: true,
+    model: normalizedBindings.defaultModel || "llm-router",
+    displayName: "LLM Router",
+    baseUrl,
+    apiKey: normalizedApiKey,
+    provider: "openai"
+  };
+
+  if (routerIndex >= 0) {
+    customModels[routerIndex] = routerEntry;
+  } else {
+    customModels.push(routerEntry);
+  }
+  nextSettings.customModels = customModels;
+
+  if (normalizedBindings.defaultModel) {
+    nextSettings.model = normalizedBindings.defaultModel;
+  }
+
+  if (normalizedBindings.reasoningEffort) {
+    nextSettings.reasoningEffort = normalizedBindings.reasoningEffort;
+  } else {
+    delete nextSettings.reasoningEffort;
+  }
+
+  await writeJsonObjectFile(resolvedSettingsPath, nextSettings);
+  return {
+    settingsFilePath: resolvedSettingsPath,
+    backupFilePath: resolvedBackupPath,
+    settingsCreated: !settingsState.existed,
+    baseUrl,
+    bindings: normalizedBindings
+  };
+}
+
+export async function unpatchFactoryDroidSettingsFile({
+  settingsFilePath = "",
+  backupFilePath = "",
+  homeDir = os.homedir()
+} = {}) {
+  const resolvedSettingsPath = path.resolve(String(settingsFilePath || resolveFactoryDroidSettingsFilePath({ homeDir })).trim());
+  const resolvedBackupPath = path.resolve(String(backupFilePath || resolveCodingToolBackupFilePath(resolvedSettingsPath)).trim());
+  const settingsState = await readJsonObjectFile(resolvedSettingsPath, `Factory Droid settings file '${resolvedSettingsPath}'`);
+  const backupState = await readJsonObjectFile(resolvedBackupPath, `Backup file '${resolvedBackupPath}'`);
+  const backup = sanitizeBackup(backupState.data, "factory-droid");
+  const restoredSettings = applyFactoryDroidBackup(settingsState.data, backup);
+
+  await writeJsonObjectFile(resolvedSettingsPath, restoredSettings);
+  await writeJsonObjectFile(resolvedBackupPath, {});
+
+  return {
+    settingsFilePath: resolvedSettingsPath,
+    backupFilePath: resolvedBackupPath,
+    settingsExisted: settingsState.existed,
+    backupRestored: backupHasData(backup)
+  };
+}