@khanglvm/ai-router 1.0.2 → 1.0.4

package/README.md

@@ -32,11 +32,10 @@ ai-router setup
 ```
 
 This command:
-- asks for provider name/base URL/API key
+- asks for provider name + API key, then endpoint candidates + model list
 - requires a provider id (slug/camelCase, e.g. `openrouter` or `myProvider`)
-- probes the provider with live requests
-- auto-detects supported format(s): `openai` and/or `claude`
-- tries to discover model list
+- probes endpoint(s) x model(s) with live requests
+- auto-detects supported format(s) per endpoint and model support per format
 - saves config to `~/.ai-router.json`
 
 ### Non-interactive setup
@@ -46,12 +45,14 @@ npx ai-router-proxy setup \
   --operation=upsert-provider \
   --provider-id=openrouter \
   --name=OpenRouter \
-  --base-url=https://openrouter.ai/api/v1 \
   --api-key=sk-... \
+  --endpoints=https://openrouter.ai/api/v1 \
   --models=gpt-4o,claude-3-5-sonnet-latest \
   --headers='{"User-Agent":"Mozilla/5.0"}'
 ```
 
+If `--headers` is omitted, setup saves a default `User-Agent` header to reduce provider compatibility issues. To remove it explicitly, set `--headers='{\"User-Agent\":null}'`.
+
 ### Start local proxy (default command)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/ai-router",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Generic AI Router Proxy (local + Cloudflare Worker)",
   "type": "module",
   "main": "src/index.js",

package/src/cli/router-module.js

@@ -14,11 +14,12 @@ import {
   removeProvider,
   writeConfigFile
 } from "../node/config-store.js";
-import { probeProvider } from "../node/provider-probe.js";
+import { probeProvider, probeProviderEndpointMatrix } from "../node/provider-probe.js";
 import { runStartCommand } from "../node/start-command.js";
 import { installStartup, startupStatus, uninstallStartup } from "../node/startup-manager.js";
 import {
   configHasProvider,
+  DEFAULT_PROVIDER_USER_AGENT,
   maskSecret,
   PROVIDER_ID_PATTERN,
   sanitizeConfigForDisplay
@@ -68,6 +69,85 @@ function parseJsonObjectArg(value, fieldName) {
   }
 }
 
+function hasHeaderName(headers, name) {
+  const lower = String(name).toLowerCase();
+  return Object.keys(headers || {}).some((key) => key.toLowerCase() === lower);
+}
+
+function applyDefaultHeaders(headers, { force = true } = {}) {
+  const source = headers && typeof headers === "object" && !Array.isArray(headers) ? headers : {};
+  const next = { ...source };
+  if (force && !hasHeaderName(next, "user-agent")) {
+    next["User-Agent"] = DEFAULT_PROVIDER_USER_AGENT;
+  }
+  return next;
+}
+
+function providerEndpointsFromConfig(provider) {
+  const values = [
+    provider?.baseUrlByFormat?.openai,
+    provider?.baseUrlByFormat?.claude,
+    provider?.baseUrl
+  ];
+  return parseModelListInput(values.filter(Boolean).join(","));
+}
+
+function probeProgressReporter(context) {
+  const line = typeof context?.terminal?.line === "function" ? context.terminal.line.bind(context.terminal) : null;
+  if (!line) return () => {};
+
+  let lastProgressPrinted = -1;
+  return (event) => {
+    if (!event || typeof event !== "object") return;
+    const phase = String(event.phase || "");
+
+    if (phase === "matrix-start") {
+      line(`Auto-discovery started: ${event.endpointCount || 0} endpoint(s) x ${event.modelCount || 0} model(s).`);
+      return;
+    }
+    if (phase === "endpoint-start") {
+      line(`[discover] Endpoint ${event.endpointIndex || "?"}/${event.endpointCount || "?"}: ${event.endpoint}`);
+      return;
+    }
+    if (phase === "endpoint-formats") {
+      const formats = Array.isArray(event.formatsToTest) && event.formatsToTest.length > 0
+        ? event.formatsToTest.join(", ")
+        : "(none)";
+      line(`[discover] Testing formats for ${event.endpoint}: ${formats}`);
+      return;
+    }
+    if (phase === "format-start") {
+      line(`[discover] ${event.endpoint} -> ${event.format} (${event.modelCount || 0} model checks)`);
+      return;
+    }
+    if (phase === "model-check") {
+      const completed = Number(event.completedChecks || 0);
+      const total = Number(event.totalChecks || 0);
+      if (completed <= 0 || total <= 0) return;
+      if (completed === total || completed - lastProgressPrinted >= 3) {
+        lastProgressPrinted = completed;
+        line(`[discover] Progress ${completed}/${total} - ${event.model} on ${event.format} @ ${event.endpoint}: ${event.supported ? "ok" : "skip"}`);
+      }
+      return;
+    }
+    if (phase === "endpoint-done") {
+      const formats = Array.isArray(event.workingFormats) && event.workingFormats.length > 0
+        ? event.workingFormats.join(", ")
+        : "(none)";
+      line(`[discover] Endpoint done: ${event.endpoint} working formats=${formats}`);
+      return;
+    }
+    if (phase === "matrix-done") {
+      const openaiBase = event.baseUrlByFormat?.openai || "(none)";
+      const claudeBase = event.baseUrlByFormat?.claude || "(none)";
+      const formats = Array.isArray(event.workingFormats) && event.workingFormats.length > 0
+        ? event.workingFormats.join(", ")
+        : "(none)";
+      line(`Auto-discovery completed: working formats=${formats}, models=${event.supportedModelCount || 0}, openaiBase=${openaiBase}, claudeBase=${claudeBase}`);
+    }
+  };
+}
+
 async function promptProviderFormat(context, {
   message = "Primary provider format",
   initialFormat = ""
@@ -215,6 +295,11 @@ async function resolveUpsertInput(context, existingConfig) {
   const baseProviderId = argProviderId || selectedExisting?.id || "";
   const baseName = String(readArg(args, ["name"], selectedExisting?.name || "") || "");
   const baseUrl = String(readArg(args, ["base-url", "baseUrl"], selectedExisting?.baseUrl || "") || "");
+  const baseEndpoints = parseModelListInput(readArg(
+    args,
+    ["endpoints"],
+    providerEndpointsFromConfig(selectedExisting).join(",")
+  ));
   const baseOpenAIBaseUrl = String(readArg(
     args,
     ["openai-base-url", "openaiBaseUrl"],
@@ -229,11 +314,15 @@ async function resolveUpsertInput(context, existingConfig) {
   const baseModels = String(readArg(args, ["models"], (selectedExisting?.models || []).map((m) => m.id).join(",")) || "");
   const baseFormat = String(readArg(args, ["format"], selectedExisting?.format || "") || "");
   const baseFormats = parseModelListInput(readArg(args, ["formats"], (selectedExisting?.formats || []).join(",")));
+  const hasHeadersArg = args.headers !== undefined;
   const baseHeaders = readArg(args, ["headers"], selectedExisting?.headers ? JSON.stringify(selectedExisting.headers) : "");
   const shouldProbe = !toBoolean(readArg(args, ["skip-probe", "skipProbe"], false), false);
   const setMasterKeyFlag = toBoolean(readArg(args, ["set-master-key", "setMasterKey"], false), false);
   const providedMasterKey = String(readArg(args, ["master-key", "masterKey"], "") || "");
-  const parsedHeaders = parseJsonObjectArg(baseHeaders, "--headers");
+  const parsedHeaders = applyDefaultHeaders(
+    parseJsonObjectArg(baseHeaders, "--headers"),
+    { force: !hasHeadersArg }
+  );
 
   if (!canPrompt()) {
     return {
@@ -241,6 +330,7 @@ async function resolveUpsertInput(context, existingConfig) {
       providerId: baseProviderId || slugifyId(baseName || "provider"),
       name: baseName,
       baseUrl,
+      endpoints: baseEndpoints,
       openaiBaseUrl: baseOpenAIBaseUrl,
       claudeBaseUrl: baseClaudeBaseUrl,
       apiKey: baseApiKey || selectedExisting?.apiKey || "",
@@ -266,22 +356,6 @@ async function resolveUpsertInput(context, existingConfig) {
     initialValue: slugifyId(name)
   });
 
-  const url = baseUrl || await context.prompts.text({
-    message: "Provider base URL (shared fallback, optional)",
-    required: false,
-    placeholder: "https://api.example.com/v1"
-  });
-
-  const openaiBaseUrl = String(await context.prompts.text({
-    message: "OpenAI base URL override (optional)",
-    initialValue: baseOpenAIBaseUrl
-  }) || "");
-
-  const claudeBaseUrl = String(await context.prompts.text({
-    message: "Anthropic/Claude base URL override (optional)",
-    initialValue: baseClaudeBaseUrl
-  }) || "");
-
   const askReplaceKey = selectedExisting?.apiKey ? await context.prompts.confirm({
     message: "Replace saved API key?",
     initialValue: false
@@ -292,14 +366,30 @@ async function resolveUpsertInput(context, existingConfig) {
     required: true
   });
 
+  const endpointsInput = await context.prompts.text({
+    message: "Provider endpoints (comma separated)",
+    required: true,
+    initialValue: baseEndpoints.join(",")
+  });
+  const endpoints = parseModelListInput(endpointsInput);
+
+  const modelsInput = await context.prompts.text({
+    message: "Provider models (comma separated)",
+    required: true,
+    initialValue: baseModels
+  });
+
   const headersInput = await context.prompts.text({
-    message: "Custom headers JSON (optional)",
-    initialValue: String(baseHeaders || "")
+    message: "Custom headers JSON (optional; default User-Agent included)",
+    initialValue: JSON.stringify(applyDefaultHeaders(
+      parseJsonObjectArg(baseHeaders, "Custom headers"),
+      { force: true }
+    ))
   });
   const interactiveHeaders = parseJsonObjectArg(headersInput, "Custom headers");
 
   const probe = await context.prompts.confirm({
-    message: "Auto-detect format and models via live probe?",
+    message: "Auto-detect endpoint formats and model support via live probe?",
     initialValue: shouldProbe
   });
 
@@ -311,11 +401,6 @@ async function resolveUpsertInput(context, existingConfig) {
     });
   }
 
-  const modelsInput = await context.prompts.text({
-    message: "Model list (comma separated, leave empty to use probe discovery)",
-    initialValue: baseModels
-  });
-
   const setMasterKey = setMasterKeyFlag || await context.prompts.confirm({
     message: "Set/update worker master key?",
     initialValue: false
@@ -332,9 +417,10 @@ async function resolveUpsertInput(context, existingConfig) {
     configPath,
     providerId,
     name,
-    baseUrl: url,
-    openaiBaseUrl,
-    claudeBaseUrl,
+    baseUrl,
+    endpoints,
+    openaiBaseUrl: baseOpenAIBaseUrl,
+    claudeBaseUrl: baseClaudeBaseUrl,
     apiKey,
     models: parseModelListInput(modelsInput),
     format: probe ? "" : manualFormat,
@@ -351,13 +437,19 @@ async function doUpsertProvider(context) {
   const existingConfig = await readConfigFile(configPath);
   const input = await resolveUpsertInput(context, existingConfig);
 
-  const hasAnyEndpoint = Boolean(input.baseUrl || input.openaiBaseUrl || input.claudeBaseUrl);
+  const endpointCandidates = parseModelListInput([
+    ...(input.endpoints || []),
+    input.openaiBaseUrl,
+    input.claudeBaseUrl,
+    input.baseUrl
+  ].filter(Boolean).join(","));
+  const hasAnyEndpoint = endpointCandidates.length > 0;
   if (!input.name || !hasAnyEndpoint || !input.apiKey) {
     return {
       ok: false,
       mode: context.mode,
       exitCode: EXIT_VALIDATION,
-      errorMessage: "Missing provider inputs: provider-id, name, api-key, and at least one endpoint (base-url/openai-base-url/claude-base-url)."
+      errorMessage: "Missing provider inputs: provider-id, name, api-key, and at least one endpoint."
     };
   }
 
@@ -372,21 +464,68 @@ async function doUpsertProvider(context) {
 
   let probe = null;
   let selectedFormat = String(input.format || "").trim();
+  let effectiveBaseUrl = String(input.baseUrl || "").trim();
+  let effectiveOpenAIBaseUrl = String(input.openaiBaseUrl || "").trim();
+  let effectiveClaudeBaseUrl = String(input.claudeBaseUrl || "").trim();
+  let effectiveModels = [...(input.models || [])];
+
+  if (input.shouldProbe && endpointCandidates.length > 0 && effectiveModels.length === 0) {
+    return {
+      ok: false,
+      mode: context.mode,
+      exitCode: EXIT_VALIDATION,
+      errorMessage: "Model list is required for endpoint-model probe. Provide --models=modelA,modelB."
+    };
+  }
+
   if (input.shouldProbe) {
-    const probeBaseUrlByFormat = {};
-    if (input.openaiBaseUrl) probeBaseUrlByFormat.openai = input.openaiBaseUrl;
-    if (input.claudeBaseUrl) probeBaseUrlByFormat.claude = input.claudeBaseUrl;
-
-    probe = await probeProvider({
-      baseUrl: input.baseUrl,
-      baseUrlByFormat: Object.keys(probeBaseUrlByFormat).length > 0 ? probeBaseUrlByFormat : undefined,
-      apiKey: input.apiKey,
-      headers: input.headers
-    });
+    const startedAt = Date.now();
+    const reportProgress = probeProgressReporter(context);
+    const canRunMatrixProbe = endpointCandidates.length > 0 && effectiveModels.length > 0;
+    if (canRunMatrixProbe) {
+      probe = await probeProviderEndpointMatrix({
+        endpoints: endpointCandidates,
+        models: effectiveModels,
+        apiKey: input.apiKey,
+        headers: input.headers,
+        onProgress: reportProgress
+      });
+      effectiveOpenAIBaseUrl = probe.baseUrlByFormat?.openai || effectiveOpenAIBaseUrl;
+      effectiveClaudeBaseUrl = probe.baseUrlByFormat?.claude || effectiveClaudeBaseUrl;
+      effectiveBaseUrl =
+        (probe.preferredFormat && probe.baseUrlByFormat?.[probe.preferredFormat]) ||
+        effectiveOpenAIBaseUrl ||
+        effectiveClaudeBaseUrl ||
+        endpointCandidates[0] ||
+        effectiveBaseUrl;
+      if ((probe.models || []).length > 0) {
+        effectiveModels = effectiveModels.length > 0
+          ? effectiveModels.filter((model) => (probe.models || []).includes(model))
+          : [...probe.models];
+      }
+    } else {
+      const probeBaseUrlByFormat = {};
+      if (effectiveOpenAIBaseUrl) probeBaseUrlByFormat.openai = effectiveOpenAIBaseUrl;
+      if (effectiveClaudeBaseUrl) probeBaseUrlByFormat.claude = effectiveClaudeBaseUrl;
+
+      probe = await probeProvider({
+        baseUrl: effectiveBaseUrl || endpointCandidates[0],
+        baseUrlByFormat: Object.keys(probeBaseUrlByFormat).length > 0 ? probeBaseUrlByFormat : undefined,
+        apiKey: input.apiKey,
+        headers: input.headers,
+        onProgress: reportProgress
+      });
+    }
+    const line = typeof context?.terminal?.line === "function" ? context.terminal.line.bind(context.terminal) : null;
+    if (line) {
+      const tookMs = Date.now() - startedAt;
+      line(`Auto-discovery finished in ${(tookMs / 1000).toFixed(1)}s.`);
+    }
+
     if (!probe.ok) {
       if (canPrompt()) {
         const continueWithoutProbe = await context.prompts.confirm({
-          message: "Probe failed to confirm a working format. Save provider anyway?",
+          message: "Probe failed to confirm working endpoint/model support. Save provider anyway?",
           initialValue: false
         });
         if (!continueWithoutProbe) {
@@ -407,7 +546,7 @@ async function doUpsertProvider(context) {
           ok: false,
           mode: context.mode,
           exitCode: EXIT_FAILURE,
-          errorMessage: "Provider probe failed. Use --skip-probe=true to force save."
+          errorMessage: "Provider probe failed. Provide valid endpoints/models or use --skip-probe=true to force save."
         };
       }
     } else {
@@ -415,16 +554,34 @@ async function doUpsertProvider(context) {
     }
   }
 
+  if (!input.shouldProbe) {
+    if (!effectiveBaseUrl && endpointCandidates.length > 0) {
+      effectiveBaseUrl = endpointCandidates[0];
+    }
+    if (!effectiveOpenAIBaseUrl && !effectiveClaudeBaseUrl && endpointCandidates.length === 1 && selectedFormat) {
+      if (selectedFormat === "openai") effectiveOpenAIBaseUrl = endpointCandidates[0];
+      if (selectedFormat === "claude") effectiveClaudeBaseUrl = endpointCandidates[0];
+    }
+    if (!effectiveOpenAIBaseUrl && !effectiveClaudeBaseUrl && endpointCandidates.length > 1) {
+      return {
+        ok: false,
+        mode: context.mode,
+        exitCode: EXIT_VALIDATION,
+        errorMessage: "Multiple endpoints require probe mode (recommended) or explicit --openai-base-url/--claude-base-url."
+      };
+    }
+  }
+
   const effectiveFormat = selectedFormat || (input.shouldProbe ? "" : "openai");
 
   const provider = buildProviderFromSetupInput({
     providerId: input.providerId,
     name: input.name,
-    baseUrl: input.baseUrl,
-    openaiBaseUrl: input.openaiBaseUrl,
-    claudeBaseUrl: input.claudeBaseUrl,
+    baseUrl: effectiveBaseUrl,
+    openaiBaseUrl: effectiveOpenAIBaseUrl,
+    claudeBaseUrl: effectiveClaudeBaseUrl,
     apiKey: input.apiKey,
-    models: input.models,
+    models: effectiveModels,
     format: effectiveFormat,
     formats: input.formats,
     headers: input.headers,
@@ -456,8 +613,10 @@ async function doUpsertProvider(context) {
       probe
         ? `probe preferred=${probe.preferredFormat || "(none)"} working=${(probe.workingFormats || []).join(",") || "(none)"}`
         : "probe=skipped",
+      provider.baseUrlByFormat?.openai ? `openaiBaseUrl=${provider.baseUrlByFormat.openai}` : "",
+      provider.baseUrlByFormat?.claude ? `claudeBaseUrl=${provider.baseUrlByFormat.claude}` : "",
       `formats=${(provider.formats || []).join(", ") || provider.format || "unknown"}`,
-      `models=${provider.models.map((m) => m.id).join(", ")}`,
+      `models=${provider.models.map((m) => `${m.id}${m.formats?.length ? `[${m.formats.join("|")}]` : ""}`).join(", ")}`,
       `masterKey=${nextConfig.masterKey ? maskSecret(nextConfig.masterKey) : "(not set)"}`
     ].join("\n")
   };
@@ -1076,6 +1235,7 @@ const routerModule = {
           "config",
           "provider-id",
           "name",
+          "endpoints",
           "base-url",
           "openai-base-url",
           "claude-base-url",
@@ -1102,6 +1262,7 @@ const routerModule = {
           { name: "operation", required: false, description: "Setup operation (optional; prompts if omitted).", example: "--operation=upsert-provider" },
           { name: "provider-id", required: false, description: "Provider id (slug/camelCase).", example: "--provider-id=openrouter" },
           { name: "name", required: false, description: "Provider display name.", example: "--name=OpenRouter" },
+          { name: "endpoints", required: false, description: "Comma-separated provider endpoint candidates for auto-probe.", example: "--endpoints=https://ramclouds.me,https://ramclouds.me/v1" },
           { name: "base-url", required: false, description: "Provider base URL.", example: "--base-url=https://openrouter.ai/api/v1" },
           { name: "openai-base-url", required: false, description: "OpenAI endpoint base URL (format-specific override).", example: "--openai-base-url=https://ramclouds.me/v1" },
           { name: "claude-base-url", required: false, description: "Anthropic endpoint base URL (format-specific override).", example: "--claude-base-url=https://ramclouds.me" },
@@ -1109,8 +1270,8 @@ const routerModule = {
           { name: "models", required: false, description: "Comma-separated model list.", example: "--models=gpt-4o,claude-3-5-sonnet-latest" },
           { name: "model", required: false, description: "Single model id (used by remove-model).", example: "--model=gpt-4o" },
           { name: "format", required: false, description: "Manual format if probe is skipped.", example: "--format=openai" },
-          { name: "headers", required: false, description: "Custom provider headers as JSON object.", example: "--headers={\"User-Agent\":\"Mozilla/5.0\"}" },
-          { name: "skip-probe", required: false, description: "Skip live provider probe.", example: "--skip-probe=true" },
+          { name: "headers", required: false, description: "Custom provider headers as JSON object (default User-Agent applied when omitted).", example: "--headers={\"User-Agent\":\"Mozilla/5.0\"}" },
+          { name: "skip-probe", required: false, description: "Skip live endpoint/model probe.", example: "--skip-probe=true" },
           { name: "master-key", required: false, description: "Worker auth token.", example: "--master-key=my-token" },
           { name: "watch-binary", required: false, description: "For startup-install: detect ai-router upgrades and auto-relaunch under OS startup.", example: "--watch-binary=true" },
           { name: "require-auth", required: false, description: "Require masterKey auth for local start/startup-install.", example: "--require-auth=true" },
@@ -1118,7 +1279,7 @@ const routerModule = {
         ],
         examples: [
           "ai-router setup",
-          "ai-router setup --operation=upsert-provider --provider-id=openrouter --name=OpenRouter --base-url=https://openrouter.ai/api/v1 --api-key=sk-...",
+          "ai-router setup --operation=upsert-provider --provider-id=ramclouds --name=RamClouds --api-key=sk-... --endpoints=https://ramclouds.me,https://ramclouds.me/v1 --models=claude-opus-4-6-thinking,gpt-5.3-codex",
           "ai-router setup --operation=remove-model --provider-id=openrouter --model=gpt-4o",
           "ai-router setup --operation=startup-install"
         ],

package/src/node/config-workflows.js

@@ -41,14 +41,59 @@ export function parseModelListInput(raw) {
 }
 
 function normalizeModelArray(models) {
-  return dedupe(models).map((id) => ({ id }));
+  const rows = Array.isArray(models) ? models : dedupe(models).map((id) => ({ id }));
+  return rows
+    .map((entry) => {
+      if (typeof entry === "string") return { id: entry };
+      if (!entry || typeof entry !== "object") return null;
+      const id = String(entry.id || entry.name || "").trim();
+      if (!id) return null;
+      const formats = dedupe(entry.formats || entry.format || []).filter((value) => value === "openai" || value === "claude");
+      return {
+        id,
+        ...(formats.length > 0 ? { formats } : {})
+      };
+    })
+    .filter(Boolean);
+}
+
+function buildModelsWithPreferredFormat(modelIds, modelSupport = {}, modelPreferredFormat = {}) {
+  return normalizeModelArray(modelIds.map((id) => {
+    const preferred = modelPreferredFormat[id];
+    if (preferred) {
+      return { id, formats: [preferred] };
+    }
+    return { id, formats: modelSupport[id] || [] };
+  }));
+}
+
+function summarizeEndpointMatrix(endpointMatrix) {
+  if (!Array.isArray(endpointMatrix)) return undefined;
+  return endpointMatrix.map((row) => ({
+    endpoint: row.endpoint,
+    supportedFormats: row.supportedFormats || [],
+    workingFormats: row.workingFormats || [],
+    modelsByFormat: row.modelsByFormat || {},
+    authByFormat: row.authByFormat || {}
+  }));
 }
 
 export function buildProviderFromSetupInput(input) {
   const providerId = input.providerId || input.id || input.name;
   const baseUrlByFormat = normalizeBaseUrlByFormatInput(input);
-  const explicitModels = normalizeModelArray(parseModelListInput(input.models));
-  const probeModels = normalizeModelArray(input.probe?.models || []);
+  const explicitModelIds = parseModelListInput(input.models);
+  const probeModelSupport = input.probe?.modelSupport && typeof input.probe.modelSupport === "object"
+    ? input.probe.modelSupport
+    : {};
+  const probeModelPreferredFormat = input.probe?.modelPreferredFormat && typeof input.probe.modelPreferredFormat === "object"
+    ? input.probe.modelPreferredFormat
+    : {};
+  const explicitModels = explicitModelIds.length > 0
+    ? buildModelsWithPreferredFormat(explicitModelIds, probeModelSupport, probeModelPreferredFormat)
+    : [];
+  const probeModels = input.probe?.models?.length
+    ? buildModelsWithPreferredFormat(input.probe.models, probeModelSupport, probeModelPreferredFormat)
+    : [];
   const mergedModels = explicitModels.length > 0 ? explicitModels : probeModels;
   const endpointFormats = baseUrlByFormat ? Object.keys(baseUrlByFormat) : [];
 
@@ -86,7 +131,11 @@ export function buildProviderFromSetupInput(input) {
             at: new Date().toISOString(),
             formats: input.probe.formats || [],
             workingFormats: input.probe.workingFormats || [],
-            models: input.probe.models || []
+            models: input.probe.models || [],
+            modelSupport: input.probe.modelSupport || undefined,
+            modelPreferredFormat: input.probe.modelPreferredFormat || undefined,
+            endpointMatrix: summarizeEndpointMatrix(input.probe.endpointMatrix),
+            warnings: input.probe.warnings || undefined
           }
         : undefined
     }]

package/src/node/provider-probe.js

@@ -32,6 +32,17 @@ function cloneHeaders(headers) {
   return { ...(headers || {}) };
 }
 
+function makeProgressEmitter(callback) {
+  if (typeof callback !== "function") return () => {};
+  return (event) => {
+    try {
+      callback(event);
+    } catch {
+      // ignore probe progress callback failures
+    }
+  };
+}
+
 function makeAuthVariants(format, apiKey) {
   if (!apiKey) return [];
 
@@ -171,6 +182,156 @@ function extractModelIds(result) {
   return [...new Set(ids)];
 }
 
+function dedupeStrings(values) {
+  return [...new Set((values || []).filter(Boolean).map((value) => String(value).trim()).filter(Boolean))];
+}
+
+function normalizeUrlPathForScoring(endpoint) {
+  try {
+    return new URL(String(endpoint)).pathname.replace(/\/+$/, "") || "/";
+  } catch {
+    return String(endpoint || "").trim().replace(/^https?:\/\/[^/]+/i, "").replace(/\/+$/, "") || "/";
+  }
+}
+
+function orderAuthVariants(authVariants, preferredAuth) {
+  if (!preferredAuth || !Array.isArray(authVariants) || authVariants.length <= 1) return authVariants;
+  const normalized = String(preferredAuth).trim().toLowerCase();
+  const preferred = authVariants.find((item) => item.type === normalized);
+  if (!preferred) return authVariants;
+  return [preferred, ...authVariants.filter((item) => item !== preferred)];
+}
+
+function getResultMessage(result) {
+  return String(getErrorMessage(result.json, result.text) || "").trim();
+}
+
+function truncateMessage(value, max = 220) {
+  const text = String(value || "").trim();
+  if (!text) return "";
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 3)}...`;
+}
+
+function isUnsupportedModelMessage(message) {
+  const text = String(message || "").toLowerCase();
+  if (!text) return false;
+  const patterns = [
+    /model .*not found/,
+    /unknown model/,
+    /unsupported model/,
+    /invalid model/,
+    /no such model/,
+    /model .*does not exist/,
+    /model .*not available/,
+    /unrecognized model/
+  ];
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+function looksExpectedFormat(format, result) {
+  if (format === FORMATS.CLAUDE) return looksClaude(result);
+  return looksOpenAI(result);
+}
+
+function buildProbeRequest(format, modelId) {
+  if (format === FORMATS.CLAUDE) {
+    return {
+      model: modelId,
+      max_tokens: 1,
+      stream: false,
+      messages: [{ role: "user", content: "ping" }]
+    };
+  }
+
+  return {
+    model: modelId,
+    messages: [{ role: "user", content: "ping" }],
+    max_tokens: 1,
+    stream: false
+  };
+}
+
+function makeProbeHeaders(format, extraHeaders, authHeaders = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    ...extraHeaders,
+    ...authHeaders
+  };
+  if (format === FORMATS.CLAUDE) {
+    if (!headers["anthropic-version"] && !headers["Anthropic-Version"]) {
+      headers["anthropic-version"] = "2023-06-01";
+    }
+  }
+  return headers;
+}
+
+function modelLooksSupported(format, result) {
+  if (result.ok) return true;
+  if (!looksExpectedFormat(format, result)) return false;
+  if (!authLooksValid(result)) return false;
+
+  const message = getResultMessage(result);
+  if (isUnsupportedModelMessage(message)) return false;
+  return true;
+}
+
+async function probeModelForFormat({
+  baseUrl,
+  format,
+  apiKey,
+  modelId,
+  timeoutMs,
+  extraHeaders,
+  preferredAuthType
+}) {
+  const url = resolveProviderUrl(makeProviderShell(baseUrl), format);
+  const authVariants = orderAuthVariants(makeAuthVariants(format, apiKey), preferredAuthType);
+
+  for (const variant of authVariants) {
+    const headers = makeProbeHeaders(format, extraHeaders, variant.headers);
+    const result = await safeFetchJson(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(buildProbeRequest(format, modelId))
+    }, timeoutMs);
+
+    if (modelLooksSupported(format, result)) {
+      return {
+        supported: true,
+        authType: variant.type,
+        status: result.status,
+        message: result.ok ? "ok" : truncateMessage(getResultMessage(result)),
+        error: result.error || null
+      };
+    }
+
+    if (!authLooksValid(result)) {
+      continue;
+    }
+
+    // Endpoint/format looks valid and auth seems valid, model is likely not available here.
+    const msg = getResultMessage(result);
+    if (isUnsupportedModelMessage(msg)) {
+      return {
+        supported: false,
+        authType: variant.type,
+        status: result.status,
+        message: truncateMessage(msg || "Model is not supported on this endpoint."),
+        error: result.error || null
+      };
+    }
+  }
+
+  return {
+    supported: false,
+    authType: null,
+    status: 0,
+    message: "Could not validate model support for this endpoint/format.",
+    error: null
+  };
+}
+
 async function probeOpenAI(baseUrl, apiKey, timeoutMs, extraHeaders = {}) {
   const authVariants = makeAuthVariants(FORMATS.OPENAI, apiKey);
   const modelsUrl = resolveModelsUrl(baseUrl, FORMATS.OPENAI);
@@ -278,6 +439,7 @@ async function probeClaude(baseUrl, apiKey, timeoutMs, extraHeaders = {}) {
 }
 
 export async function probeProvider(options) {
+  const emitProgress = makeProgressEmitter(options?.onProgress);
   const baseUrl = String(options?.baseUrl || "").trim();
   const baseUrlByFormat = normalizeProbeBaseUrlByFormat(options?.baseUrlByFormat);
   const apiKey = String(options?.apiKey || "").trim();
@@ -295,6 +457,8 @@ export async function probeProvider(options) {
     throw new Error("Provider apiKey is required for probing.");
   }
 
+  emitProgress({ phase: "provider-probe-start", baseUrl: baseUrl || openaiProbeBaseUrl || claudeProbeBaseUrl });
+
   const [openai, claude] = await Promise.all([
     openaiProbeBaseUrl
       ? probeOpenAI(openaiProbeBaseUrl, apiKey, timeoutMs, extraHeaders)
@@ -325,6 +489,13 @@ export async function probeProvider(options) {
 
   const models = [...new Set([...(claude.models || []), ...(openai.models || [])])];
 
+  emitProgress({
+    phase: "provider-probe-done",
+    baseUrl: baseUrl || openaiProbeBaseUrl || claudeProbeBaseUrl,
+    supportedFormats,
+    workingFormats
+  });
+
   return {
     ok: workingFormats.length > 0,
     baseUrl: baseUrl || openaiProbeBaseUrl || claudeProbeBaseUrl,
@@ -341,3 +512,297 @@ export async function probeProvider(options) {
     }
   };
 }
+
+function normalizeEndpointList(rawEndpoints, fallbackBaseUrl = "") {
+  const values = [];
+  if (Array.isArray(rawEndpoints)) {
+    values.push(...rawEndpoints);
+  } else if (typeof rawEndpoints === "string") {
+    values.push(...rawEndpoints.split(/[,\n]/g));
+  }
+  if (fallbackBaseUrl) values.push(fallbackBaseUrl);
+  return dedupeStrings(values);
+}
+
+function pickBestEndpointForFormat(endpointRows, format) {
+  const endpointPreferenceScore = (endpoint) => {
+    const path = normalizeUrlPathForScoring(endpoint);
+    const looksVersioned = /\/v\d+(?:\.\d+)?$/i.test(path);
+    const hasOpenAIHint = /\/openai(?:\/|$)/i.test(path);
+    const hasAnthropicHint = /\/anthropic(?:\/|$)|\/claude(?:\/|$)/i.test(path);
+
+    if (format === FORMATS.OPENAI) {
+      if (hasOpenAIHint) return 100;
+      if (looksVersioned) return 90;
+      if (path === "/" || path === "") return 10;
+      return 50;
+    }
+    if (format === FORMATS.CLAUDE) {
+      if (hasAnthropicHint) return 100;
+      if (path === "/" || path === "") return 90;
+      if (looksVersioned) return 10;
+      return 50;
+    }
+    return 0;
+  };
+
+  const candidates = endpointRows
+    .filter((row) => (row.workingFormats || []).includes(format))
+    .map((row) => ({
+      row,
+      score: (row.modelsByFormat?.[format] || []).length,
+      pref: endpointPreferenceScore(row.endpoint)
+    }))
+    .sort((a, b) => {
+      if (b.pref !== a.pref) return b.pref - a.pref;
+      if (b.score !== a.score) return b.score - a.score;
+      return 0;
+    });
+  return candidates[0]?.row || null;
+}
+
+function guessNativeModelFormat(modelId) {
+  const id = String(modelId || "").trim().toLowerCase();
+  if (!id) return null;
+
+  // High-confidence Anthropic family.
+  if (id.startsWith("claude")) return FORMATS.CLAUDE;
+
+  // Default most aggregator/coding endpoints expose native OpenAI-compatible format
+  // for many model families (gpt, gemini, glm, qwen, deepseek, etc).
+  return FORMATS.OPENAI;
+}
+
+function pickPreferredFormatForModel(modelId, formats, { providerPreferredFormat } = {}) {
+  const supported = dedupeStrings(formats).filter((value) => value === FORMATS.OPENAI || value === FORMATS.CLAUDE);
+  if (supported.length === 0) return null;
+  if (supported.length === 1) return supported[0];
+
+  const guessed = guessNativeModelFormat(modelId);
+  if (guessed && supported.includes(guessed)) return guessed;
+  if (providerPreferredFormat && supported.includes(providerPreferredFormat)) return providerPreferredFormat;
+  if (supported.includes(FORMATS.OPENAI)) return FORMATS.OPENAI;
+  return supported[0];
+}
+
+export async function probeProviderEndpointMatrix(options) {
+  const emitProgress = makeProgressEmitter(options?.onProgress);
+  const apiKey = String(options?.apiKey || "").trim();
+  const timeoutMs = Number.isFinite(options?.timeoutMs) ? Number(options.timeoutMs) : DEFAULT_TIMEOUT_MS;
+  const extraHeaders = options?.headers && typeof options.headers === "object" && !Array.isArray(options.headers)
+    ? options.headers
+    : {};
+  const endpoints = normalizeEndpointList(options?.endpoints, options?.baseUrl);
+  const models = dedupeStrings(options?.models || []);
+
+  if (!apiKey) throw new Error("Provider apiKey is required for probing.");
+  if (endpoints.length === 0) throw new Error("At least one endpoint is required for probing.");
+  if (models.length === 0) throw new Error("At least one model is required for endpoint-model probing.");
+
+  emitProgress({
+    phase: "matrix-start",
+    endpointCount: endpoints.length,
+    modelCount: models.length
+  });
+
+  const endpointRows = [];
+  const modelFormatsMap = {};
+  const warnings = [];
+
+  let completedChecks = 0;
+  let totalChecks = 0;
+  for (const endpoint of endpoints) {
+    totalChecks += 2 * models.length;
+  }
+
+  for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex += 1) {
+    const endpoint = endpoints[endpointIndex];
+    emitProgress({
+      phase: "endpoint-start",
+      endpoint,
+      endpointIndex: endpointIndex + 1,
+      endpointCount: endpoints.length
+    });
+
+    const endpointProbe = await probeProvider({
+      baseUrl: endpoint,
+      apiKey,
+      timeoutMs,
+      headers: extraHeaders,
+      onProgress: (event) => emitProgress({
+        ...event,
+        endpoint,
+        endpointIndex: endpointIndex + 1,
+        endpointCount: endpoints.length
+      })
+    });
+    const rowAuthByFormat = { ...(endpointProbe.authByFormat || {}) };
+    const initialWorkingFormats = endpointProbe.workingFormats || [];
+    const initialSupportedFormats = endpointProbe.formats || [];
+    const formatsToTest = dedupeStrings([
+      FORMATS.OPENAI,
+      FORMATS.CLAUDE,
+      ...initialWorkingFormats,
+      ...initialSupportedFormats
+    ]).filter((value) => value === FORMATS.OPENAI || value === FORMATS.CLAUDE);
+    const modelsByFormat = {};
+    const modelChecks = [];
+
+    if (formatsToTest.length === 0) {
+      warnings.push(`No supported format detected for endpoint ${endpoint}.`);
+    }
+    emitProgress({
+      phase: "endpoint-formats",
+      endpoint,
+      endpointIndex: endpointIndex + 1,
+      endpointCount: endpoints.length,
+      formatsToTest
+    });
+
+    for (const format of formatsToTest) {
+      const workingModels = [];
+      modelsByFormat[format] = workingModels;
+      const preferredAuthType = endpointProbe.authByFormat?.[format]?.type;
+
+      emitProgress({
+        phase: "format-start",
+        endpoint,
+        format,
+        endpointIndex: endpointIndex + 1,
+        endpointCount: endpoints.length,
+        modelCount: models.length
+      });
+
+      for (const modelId of models) {
+        const check = await probeModelForFormat({
+          baseUrl: endpoint,
+          format,
+          apiKey,
+          modelId,
+          timeoutMs,
+          extraHeaders,
+          preferredAuthType
+        });
+        modelChecks.push({
+          endpoint,
+          format,
+          model: modelId,
+          supported: check.supported,
+          status: check.status,
+          authType: check.authType,
+          message: check.message,
+          error: check.error
+        });
+        completedChecks += 1;
+        emitProgress({
+          phase: "model-check",
+          endpoint,
+          format,
+          model: modelId,
+          supported: check.supported,
+          status: check.status,
+          completedChecks,
+          totalChecks
+        });
+
+        if (!check.supported) continue;
+        workingModels.push(modelId);
+        if (!rowAuthByFormat[format] && check.authType) {
+          rowAuthByFormat[format] = { type: check.authType === "x-api-key" ? "x-api-key" : "bearer" };
+        }
+        if (!modelFormatsMap[modelId]) modelFormatsMap[modelId] = new Set();
+        modelFormatsMap[modelId].add(format);
+      }
+    }
+
+    const inferredWorkingFormats = dedupeStrings(formatsToTest.filter((format) => (modelsByFormat[format] || []).length > 0));
+    const inferredSupportedFormats = dedupeStrings([
+      ...initialSupportedFormats,
+      ...inferredWorkingFormats
+    ]);
+
+    endpointRows.push({
+      endpoint,
+      supportedFormats: inferredSupportedFormats,
+      workingFormats: inferredWorkingFormats,
+      preferredFormat: endpointProbe.preferredFormat,
+      authByFormat: rowAuthByFormat,
+      modelsByFormat,
+      modelChecks,
+      details: endpointProbe.details
+    });
+
+    emitProgress({
+      phase: "endpoint-done",
+      endpoint,
+      endpointIndex: endpointIndex + 1,
+      endpointCount: endpoints.length,
+      workingFormats: inferredWorkingFormats,
+      modelsByFormat
+    });
+  }
+
+  const openaiEndpoint = pickBestEndpointForFormat(endpointRows, FORMATS.OPENAI);
+  const claudeEndpoint = pickBestEndpointForFormat(endpointRows, FORMATS.CLAUDE);
+
+  const baseUrlByFormat = {};
+  if (openaiEndpoint) baseUrlByFormat[FORMATS.OPENAI] = openaiEndpoint.endpoint;
+  if (claudeEndpoint) baseUrlByFormat[FORMATS.CLAUDE] = claudeEndpoint.endpoint;
+
+  const authByFormat = {};
+  if (openaiEndpoint?.authByFormat?.[FORMATS.OPENAI]) {
+    authByFormat[FORMATS.OPENAI] = openaiEndpoint.authByFormat[FORMATS.OPENAI];
+  }
+  if (claudeEndpoint?.authByFormat?.[FORMATS.CLAUDE]) {
+    authByFormat[FORMATS.CLAUDE] = claudeEndpoint.authByFormat[FORMATS.CLAUDE];
+  }
+
+  const workingFormats = Object.keys(baseUrlByFormat);
+  const formats = dedupeStrings(endpointRows.flatMap((row) => row.supportedFormats || []));
+  const modelSupport = Object.fromEntries(
+    Object.entries(modelFormatsMap).map(([model, formatsSet]) => [model, [...formatsSet]])
+  );
+  const preferredFormat =
+    (workingFormats.includes(FORMATS.CLAUDE) && FORMATS.CLAUDE) ||
+    (workingFormats.includes(FORMATS.OPENAI) && FORMATS.OPENAI) ||
+    null;
+  const modelPreferredFormat = Object.fromEntries(
+    Object.entries(modelSupport)
+      .map(([modelId, supportedFormats]) => [
+        modelId,
+        pickPreferredFormatForModel(modelId, supportedFormats, { providerPreferredFormat: preferredFormat })
+      ])
+      .filter(([, preferred]) => Boolean(preferred))
+  );
+  const supportedModels = dedupeStrings(Object.keys(modelSupport));
+
+  if (workingFormats.length === 0) {
+    warnings.push("No working endpoint format detected with provided API key.");
+  }
+  if (supportedModels.length === 0) {
+    warnings.push("No provided model was confirmed as working on the detected endpoints.");
+  }
+
+  emitProgress({
+    phase: "matrix-done",
+    workingFormats,
+    baseUrlByFormat,
+    supportedModelCount: supportedModels.length
+  });
+
+  return {
+    ok: workingFormats.length > 0 && supportedModels.length > 0,
+    endpoints,
+    formats,
+    workingFormats,
+    preferredFormat,
+    baseUrlByFormat,
+    authByFormat,
+    auth: preferredFormat ? authByFormat[preferredFormat] || null : null,
+    models: supportedModels,
+    modelSupport,
+    modelPreferredFormat,
+    endpointMatrix: endpointRows,
+    warnings
+  };
+}

package/src/runtime/config.js

@@ -7,6 +7,7 @@ import { FORMATS } from "../translator/index.js";
 
 export const CONFIG_VERSION = 1;
 export const PROVIDER_ID_PATTERN = /^[a-z][a-zA-Z0-9-]*$/;
+export const DEFAULT_PROVIDER_USER_AGENT = "ai-router (+https://github.com/khanglvm/ai-router)";
 
 const DEFAULT_ANTHROPIC_VERSION = "2023-06-01";
 let runtimeEnvCache = null;
@@ -61,6 +62,8 @@ function normalizeModelEntry(model) {
   return {
     id,
     aliases: dedupeStrings(model.aliases || model.alias || []),
+    formats: dedupeStrings(model.formats || model.format || [])
+      .filter((value) => value === FORMATS.OPENAI || value === FORMATS.CLAUDE),
     enabled: model.enabled !== false,
     contextWindow: Number.isFinite(model.contextWindow) ? Number(model.contextWindow) : undefined,
     cost: model.cost,
@@ -263,13 +266,52 @@ function pickProviderAuth(provider, targetFormat) {
   return { type: "bearer" };
 }
 
+function hasHeaderName(headers, name) {
+  const lower = String(name).toLowerCase();
+  return Object.keys(headers || {}).some((key) => key.toLowerCase() === lower);
+}
+
+function normalizeCustomHeaders(rawHeaders) {
+  const out = {};
+  let userAgentExplicitlyDisabled = false;
+
+  if (!rawHeaders || typeof rawHeaders !== "object" || Array.isArray(rawHeaders)) {
+    return { headers: out, userAgentExplicitlyDisabled };
+  }
+
+  for (const [name, value] of Object.entries(rawHeaders)) {
+    const lower = name.toLowerCase();
+    const isUserAgent = lower === "user-agent";
+
+    if (value === undefined || value === null || value === false) {
+      if (isUserAgent) userAgentExplicitlyDisabled = true;
+      continue;
+    }
+
+    const text = String(value);
+    if (!text && isUserAgent) {
+      userAgentExplicitlyDisabled = true;
+      continue;
+    }
+    if (!text) continue;
+    out[name] = text;
+  }
+
+  return { headers: out, userAgentExplicitlyDisabled };
+}
+
 export function buildProviderHeaders(provider, env = undefined, targetFormat = undefined) {
   const format = targetFormat || resolveProviderFormat(provider);
+  const { headers: customHeaders, userAgentExplicitlyDisabled } = normalizeCustomHeaders(provider?.headers);
   const headers = {
     "Content-Type": "application/json",
-    ...(provider?.headers || {})
+    ...customHeaders
   };
 
+  if (!userAgentExplicitlyDisabled && !hasHeaderName(headers, "user-agent")) {
+    headers["User-Agent"] = DEFAULT_PROVIDER_USER_AGENT;
+  }
+
   const apiKey = resolveProviderApiKey(provider, env);
   const auth = pickProviderAuth(provider, format);
 
@@ -313,7 +355,32 @@ export function sanitizeConfigForDisplay(config) {
 }
 
 function buildTargetCandidate(provider, model, sourceFormat) {
-  const targetFormat = resolveProviderFormat(provider, sourceFormat);
+  const providerFormats = dedupeStrings([...(provider?.formats || []), provider?.format])
+    .filter((value) => value === FORMATS.OPENAI || value === FORMATS.CLAUDE);
+  const modelFormats = dedupeStrings([...(model?.formats || []), model?.format])
+    .filter((value) => value === FORMATS.OPENAI || value === FORMATS.CLAUDE);
+  const supportedFormats = modelFormats.length > 0
+    ? providerFormats.filter((fmt) => modelFormats.includes(fmt))
+    : providerFormats;
+
+  let targetFormat = sourceFormat && supportedFormats.includes(sourceFormat)
+    ? sourceFormat
+    : undefined;
+
+  if (!targetFormat && supportedFormats.length > 0) {
+    if (sourceFormat === FORMATS.CLAUDE && supportedFormats.includes(FORMATS.CLAUDE)) {
+      targetFormat = FORMATS.CLAUDE;
+    } else if (sourceFormat === FORMATS.OPENAI && supportedFormats.includes(FORMATS.OPENAI)) {
+      targetFormat = FORMATS.OPENAI;
+    } else {
+      targetFormat = supportedFormats[0];
+    }
+  }
+
+  if (!targetFormat) {
+    targetFormat = resolveProviderFormat(provider, sourceFormat);
+  }
+
   return {
     providerId: provider.id,
     providerName: provider.name,
@@ -375,6 +442,20 @@ export function resolveRequestModel(config, requestedModel, sourceFormat = FORMA
     };
   }
 
+  const providerFormats = dedupeStrings([...(provider.formats || []), provider.format])
+    .filter((value) => value === FORMATS.OPENAI || value === FORMATS.CLAUDE);
+  const modelFormats = dedupeStrings([...(model.formats || []), model.format])
+    .filter((value) => value === FORMATS.OPENAI || value === FORMATS.CLAUDE);
+  if (modelFormats.length > 0 && !providerFormats.some((fmt) => modelFormats.includes(fmt))) {
+    return {
+      requestedModel: normalizedRequested,
+      resolvedModel: null,
+      primary: null,
+      fallbacks: [],
+      error: `Model '${modelName}' is configured for unsupported endpoint formats under provider '${providerId}'.`
+    };
+  }
+
   const primary = buildTargetCandidate(provider, model, sourceFormat);
   return {
     requestedModel: normalizedRequested,
@@ -401,12 +482,13 @@ export function listConfiguredModels(config, { endpointFormat } = {}) {
         owned_by: provider.id,
         provider_id: provider.id,
         provider_name: provider.name,
-        formats: provider.formats || [],
+        formats: (model.formats && model.formats.length > 0) ? model.formats : (provider.formats || []),
         endpoint_format_supported: endpointFormat
-          ? (provider.formats || []).includes(endpointFormat)
+          ? ((model.formats && model.formats.length > 0) ? model.formats.includes(endpointFormat) : (provider.formats || []).includes(endpointFormat))
           : undefined,
         context_window: model.contextWindow,
-        cost: model.cost
+        cost: model.cost,
+        model_formats: model.formats || []
       });
     }
   }