@tiledesk/tiledesk-server 2.24.2 → 2.25.0

package/CHANGELOG.md

@@ -5,6 +5,11 @@
 🚀        IN PRODUCTION                        🚀
 (https://www.npmjs.com/package/@tiledesk/tiledesk-server/v/2.3.77) 
 
+# 2.25.0
+- Added support for OpenRouter
+- Added support for Gemini Agent Platform
+- Updated tybot-connector to 2.1.15
+
 # 2.24.2
 - Fixed bug recalling webhooks
 

package/config/kb/situatedContext.js

@@ -1,6 +1,41 @@
+const winston = require('../winston');
+
+/**
+ * Provider routing for contextual retrieval, used only when the provider is
+ * openrouter. Unlike the chat path, the provider here is operator-wide rather
+ * than per project, so the routing comes from the environment too:
+ *
+ *   SITUATED_CONTEXT_PROVIDER=openrouter
+ *   SITUATED_CONTEXT_PROVIDER_ROUTING={"order":["azure","openai"],"sort":"price"}
+ *
+ * Invalid JSON is ignored rather than fatal: a malformed variable must not stop
+ * indexing, it just falls back to OpenRouter's own routing.
+ */
+function parseProviderRouting() {
+    const raw = process.env.SITUATED_CONTEXT_PROVIDER_ROUTING;
+    if (!raw) {
+        return undefined;
+    }
+
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            winston.warn("SITUATED_CONTEXT_PROVIDER_ROUTING is not a JSON object, ignoring it");
+            return undefined;
+        }
+        return parsed;
+    } catch (err) {
+        winston.warn("SITUATED_CONTEXT_PROVIDER_ROUTING is not valid JSON, ignoring it: " + err.message);
+        return undefined;
+    }
+}
+
+const provider_routing = parseProviderRouting();
+
 module.exports = {
     enable: process.env.SITUATED_CONTEXT_ENABLE === "true",
     provider: process.env.SITUATED_CONTEXT_PROVIDER || "openai",
     model: process.env.SITUATED_CONTEXT_MODEL || "gpt-5.4-nano",
-    api_key: ""
-}
+    api_key: "",
+    ...(provider_routing && { provider_routing })
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiledesk/tiledesk-server",
   "description": "The Tiledesk server module",
-  "version": "2.24.2",
+  "version": "2.25.0",
   "scripts": {
     "start": "node ./bin/www",
     "pretest": "mongodb-runner start",
@@ -49,7 +49,7 @@
     "@tiledesk/tiledesk-rasa-connector": "^1.0.10",
     "@tiledesk/tiledesk-sms-connector": "^0.1.13",
     "@tiledesk/tiledesk-telegram-connector": "^0.1.14",
-    "@tiledesk/tiledesk-tybot-connector": "^2.1.11",
+    "@tiledesk/tiledesk-tybot-connector": "^2.1.15",
     "@tiledesk/tiledesk-voice-twilio-connector": "^0.3.2",
     "@tiledesk/tiledesk-vxml-connector": "^0.1.91",
     "@tiledesk/tiledesk-whatsapp-connector": "1.0.26",

package/routes/kb.js

@@ -388,7 +388,7 @@ router.post('/qa', async (req, res) => {
 
   let model;
   try {
-    model = await aiManager.resolveLLMConfig(id_project, data.llm, data.model, data.vllmServer);
+    model = await aiManager.resolveLLMConfig(id_project, data.llm, data.model, data.llmServer || data.vllmServer);
   } catch (err) {
     let errorCode = err?.code ?? 500;
     return res.status(errorCode).send({ success: false, error: err.error });
@@ -424,6 +424,10 @@ router.post('/qa', async (req, res) => {
   data.engine = namespace.engine || default_engine;
   data.embedding = aiManager.normalizeEmbedding(namespace.embedding);
 
+  if (data.llm === 'agentplatform') {
+    data.llm = "google";
+  }
+
   if (namespace.hybrid === true) {
     data.search_type = 'hybrid';
 

package/routes/llm.js

@@ -27,16 +27,25 @@ router.post('/preview', async (req, res) => {
     let key;
     let publicKey = false;
     let integration;
-    let vllmConfig;
+    let llmConfig;
+    let openrouterConfig;
+    const multiServerProviders = ['vllm', 'agentplatform'];
 
     if (!body.llm) {
         return res.status(400).send({ success: false, error: "Missing required parameter 'llm'" });
     }
 
-    if (body.llm === 'vllm') {
+    if (multiServerProviders.includes(body.llm)) {
         try {
-            vllmConfig = await aiManager.resolveLLMConfig(id_project, body.llm, body.model, body.vllmServer);
-            key = vllmConfig.api_key;
+            llmConfig = await aiManager.resolveLLMConfig(id_project, body.llm, body.model, body.llmServer || body.vllmServer);
+            key = llmConfig.api_key;
+        } catch (err) {
+            return res.status(err.code ?? 500).send({ success: false, error: err.error });
+        }
+    } else if (body.llm === 'openrouter') {
+        try {
+            openrouterConfig = await aiManager.resolveLLMConfig(id_project, body.llm, body.model);
+            key = openrouterConfig.api_key;
         } catch (err) {
             return res.status(err.code ?? 500).send({ success: false, error: err.error });
         }
@@ -102,14 +111,21 @@ router.post('/preview', async (req, res) => {
         json.stream = false;
     }
 
-    if (body.llm === 'vllm') {
+    if (multiServerProviders.includes(body.llm)) {
         json.llm_key = key || "";
-        json.model = {
-            name: body.model,
-            url: vllmConfig.url,
-            api_key: key || "",
-            provider: 'vllm'
-        };
+        json.model = llmConfig;
+        json.stream = false;
+    }
+
+    if (body.llm === 'agentplatform') {
+        json.llm = "google";
+    }
+    
+    if (body.llm === 'openrouter') {
+        // The object form carries provider_routing, which decides the upstream
+        // provider; sending the bare model name would silently drop it.
+        json.llm_key = key || "";
+        json.model = openrouterConfig;
         json.stream = false;
     }
 

package/services/aiManager.js

@@ -20,6 +20,7 @@ const default_engine = require('../config/kb/engine');
 const default_engine_hybrid = require('../config/kb/engine.hybrid');
 const default_embedding = require('../config/kb/embedding');
 const integrationService = require('./integrationService');
+const { buildOpenRouterModel } = require('../utils/openrouterUtils');
 const situatedContext = require('../config/kb/situatedContext');
 const { MODELS_MULTIPLIER } = require('../utils/aiUtils');
 
@@ -251,33 +252,29 @@ class AiManager {
     })
   }
 
-  async resolveLLMConfig(id_project, provider = 'openai', model, vllmServer = undefined) {
+  async resolveLLMConfig(id_project, provider = 'openai', model, llmServer = undefined) {
+    const selfHostedProviders = ['ollama', 'vllm', 'agentplatform'];
 
-    if (provider === 'ollama' || provider === 'vllm') {
+    if (provider === 'openrouter') {
+      const integration = await integrationService.getIntegration(id_project, provider);
+      if (!integration?.value?.apikey) {
+        throw { code: 422, error: "The key provided for openrouter is not valid or undefined" };
+      }
+      
+      return buildOpenRouterModel(integration.value, model);
+    }
+    
+    if (selfHostedProviders.includes(provider)) {
       const integration = await integrationService.getIntegration(id_project, provider);
       if (!integration?.value) {
         throw { code: 422, error: `${provider} integration not found` };
       }
 
       const value = integration.value;
+      const usesServerList = provider === 'agentplatform' || (provider === 'vllm' && Array.isArray(value.servers));
 
-      if (provider === 'vllm' && Array.isArray(value.servers)) {
-        if (!vllmServer) {
-          throw { code: 422, error: "vllmServer attribute is undefined" };
-        }
-        const server = value.servers.find(s => s.name === vllmServer);
-        if (!server) {
-          throw { code: 422, error: `vllm server '${vllmServer}' not found` };
-        }
-        if (!server.url) {
-          throw { code: 422, error: "Server url for vllm is empty or invalid" };
-        }
-        return {
-          provider,
-          name: model,
-          url: server.url,
-          api_key: server.apikey || ""
-        };
+      if (usesServerList) {
+        return this._resolveMultiServerConfig(provider, model, value, llmServer);
       }
 
       if (!value.url) {
@@ -301,6 +298,47 @@ class AiManager {
     };
   }
 
+  _resolveMultiServerConfig(provider, model, value, llmServer) {
+    if (!llmServer) {
+      throw { code: 422, error: "llmServer attribute is undefined" };
+    }
+    if (!Array.isArray(value.servers)) {
+      throw { code: 422, error: `${provider} servers list is missing or invalid` };
+    }
+
+    const server = value.servers.find(s => s.name === llmServer);
+    if (!server) {
+      throw { code: 422, error: `${provider} server '${llmServer}' not found` };
+    }
+
+    if (provider === 'agentplatform') {
+      if (!server.project) {
+        throw { code: 422, error: "Project for agentplatform is empty or invalid" };
+      }
+      if (!server.location) {
+        throw { code: 422, error: "Location for agentplatform is empty or invalid" };
+      }
+      return {
+        provider: 'google',
+        name: model,
+        api_key: server.apikey || "",
+        project: server.project,
+        location: server.location
+      };
+    }
+
+    if (!server.url) {
+      throw { code: 422, error: `Server url for ${provider} is empty or invalid` };
+    }
+
+    return {
+      provider,
+      name: model,
+      url: server.url,
+      api_key: server.apikey || ""
+    };
+  }
+
   async checkQuotaAvailability(quoteManager, project, ncontents) {
 
     return new Promise( async (resolve, reject) => {

package/test/aiManager.test.js

@@ -0,0 +1,189 @@
+process.env.NODE_ENV = 'test';
+process.env.LOG_LEVEL = 'critical';
+
+const { expect } = require('chai');
+const aiManager = require('../services/aiManager');
+const integrationService = require('../services/integrationService');
+
+describe('AiManager.resolveLLMConfig - agentplatform', function () {
+
+  const projectId = 'agentplatform-test-project';
+  const originalGetIntegration = integrationService.getIntegration.bind(integrationService);
+
+  const validServer = {
+    name: 'prod-vertex',
+    apikey: 'AQ.Ab8R-testkey',
+    project: 'poc-tiledesk-496310',
+    location: 'europe-west8'
+  };
+
+  afterEach(function () {
+    integrationService.getIntegration = originalGetIntegration;
+  });
+
+  function stubIntegration(value) {
+    integrationService.getIntegration = async function () {
+      if (value === null) {
+        throw { code: 404, error: `Integration agentplatform not found for project ${projectId}` };
+      }
+      return { id_project: projectId, name: 'agentplatform', value };
+    };
+  }
+
+  it('returns google provider config from the named server', async function () {
+    stubIntegration({ servers: [validServer] });
+
+    const llmConfig = await aiManager.resolveLLMConfig(
+      projectId,
+      'agentplatform',
+      'google/gemini-2.5-flash-lite',
+      'prod-vertex'
+    );
+
+    expect(llmConfig).to.deep.equal({
+      provider: 'google',
+      name: 'google/gemini-2.5-flash-lite',
+      api_key: 'AQ.Ab8R-testkey',
+      project: 'poc-tiledesk-496310',
+      location: 'europe-west8'
+    });
+    expect(llmConfig).to.not.have.property('url');
+  });
+
+  it('maps agentplatform provider to google', async function () {
+    stubIntegration({ servers: [validServer] });
+
+    const llmConfig = await aiManager.resolveLLMConfig(
+      projectId,
+      'agentplatform',
+      'google/gemini-2.5-flash-lite',
+      'prod-vertex'
+    );
+
+    expect(llmConfig.provider).to.equal('google');
+    expect(llmConfig.provider).to.not.equal('agentplatform');
+  });
+
+  it('uses an empty api_key when the server has no apikey', async function () {
+    stubIntegration({
+      servers: [{
+        name: 'no-apikey',
+        project: 'poc-tiledesk-496310',
+        location: 'europe-west8'
+      }]
+    });
+
+    const llmConfig = await aiManager.resolveLLMConfig(
+      projectId,
+      'agentplatform',
+      'google/gemini-2.5-flash-lite',
+      'no-apikey'
+    );
+
+    expect(llmConfig.api_key).to.equal('');
+    expect(llmConfig.project).to.equal('poc-tiledesk-496310');
+    expect(llmConfig.location).to.equal('europe-west8');
+  });
+
+  it('throws 422 when llmServer is missing', async function () {
+    stubIntegration({ servers: [validServer] });
+
+    let thrown;
+    try {
+      await aiManager.resolveLLMConfig(projectId, 'agentplatform', 'google/gemini-2.5-flash-lite');
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).to.exist;
+    expect(thrown.code).to.equal(422);
+    expect(thrown.error).to.equal('llmServer attribute is undefined');
+  });
+
+  it('throws 422 when the named server is not found', async function () {
+    stubIntegration({ servers: [validServer] });
+
+    let thrown;
+    try {
+      await aiManager.resolveLLMConfig(projectId, 'agentplatform', 'google/gemini-2.5-flash-lite', 'unknown-server');
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).to.exist;
+    expect(thrown.code).to.equal(422);
+    expect(thrown.error).to.equal("agentplatform server 'unknown-server' not found");
+  });
+
+  it('throws 422 when the server project is missing', async function () {
+    stubIntegration({
+      servers: [{
+        name: 'no-project',
+        apikey: 'AQ.Ab8R-noproject',
+        location: 'europe-west8'
+      }]
+    });
+
+    let thrown;
+    try {
+      await aiManager.resolveLLMConfig(projectId, 'agentplatform', 'google/gemini-2.5-flash-lite', 'no-project');
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).to.exist;
+    expect(thrown.code).to.equal(422);
+    expect(thrown.error).to.equal('Project for agentplatform is empty or invalid');
+  });
+
+  it('throws 422 when the server location is missing', async function () {
+    stubIntegration({
+      servers: [{
+        name: 'no-location',
+        apikey: 'AQ.Ab8R-nolocation',
+        project: 'poc-tiledesk-496310'
+      }]
+    });
+
+    let thrown;
+    try {
+      await aiManager.resolveLLMConfig(projectId, 'agentplatform', 'google/gemini-2.5-flash-lite', 'no-location');
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).to.exist;
+    expect(thrown.code).to.equal(422);
+    expect(thrown.error).to.equal('Location for agentplatform is empty or invalid');
+  });
+
+  it('throws 422 when the servers list is missing', async function () {
+    stubIntegration({});
+
+    let thrown;
+    try {
+      await aiManager.resolveLLMConfig(projectId, 'agentplatform', 'google/gemini-2.5-flash-lite', 'prod-vertex');
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).to.exist;
+    expect(thrown.code).to.equal(422);
+    expect(thrown.error).to.equal('agentplatform servers list is missing or invalid');
+  });
+
+  it('throws when the agentplatform integration does not exist', async function () {
+    stubIntegration(null);
+
+    let thrown;
+    try {
+      await aiManager.resolveLLMConfig(projectId, 'agentplatform', 'google/gemini-2.5-flash-lite', 'prod-vertex');
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).to.exist;
+    expect(thrown.code).to.equal(404);
+    expect(thrown.error).to.include('agentplatform');
+  });
+});

package/test/kbRoute.js

@@ -31,6 +31,7 @@ const nock = require('nock');
 const faq = require('../models/faq');
 const { Namespace } = require('../models/kb_setting');
 const default_engine = require('../config/kb/engine');
+const Integration = require('../models/integrations');
 
 
 // chai.config.includeStack = true;
@@ -1800,6 +1801,186 @@ describe('KbRoute', () => {
             })
         }).timeout(10000)
 
+        it('askkb-agentplatform-success', (done) => {
+
+            var email = "test-signup-" + Date.now() + "@email.com";
+            var pwd = "pwd";
+
+            userService.signup(email, pwd, "Test Firstname", "Test Lastname").then((savedUser) => {
+                projectService.create("test-kb-qa-agentplatform", savedUser._id).then((savedProject) => {
+
+                    Integration.create({
+                        id_project: savedProject._id.toString(),
+                        name: 'agentplatform',
+                        value: {
+                            servers: [{
+                                name: 'prod-vertex',
+                                apikey: 'AQ.Ab8R-testkey',
+                                project: 'poc-tiledesk-496310',
+                                location: 'europe-west8'
+                            }]
+                        }
+                    }).then(() => {
+
+                        chai.request(server)
+                            .get('/' + savedProject._id + '/kb/namespace/all')
+                            .auth(email, pwd)
+                            .end((err, res) => {
+
+                                if (err) { console.error("err: ", err); }
+                                if (log) { console.log("get all namespaces res.body: ", res.body); }
+
+                                res.should.have.status(200);
+
+                                chai.request(server)
+                                    .post('/' + savedProject._id + "/kb/qa")
+                                    .auth(email, pwd)
+                                    .send({
+                                        llm: "agentplatform",
+                                        model: "google/gemini-2.5-flash-lite",
+                                        llmServer: "prod-vertex",
+                                        namespace: savedProject._id,
+                                        question: "sample question",
+                                        advancedPrompt: true
+                                    })
+                                    .end((err, res) => {
+
+                                        if (err) { console.error("err: ", err) };
+                                        if (log) { console.log("res.body: ", res.body) };
+
+                                        res.should.have.status(200);
+                                        expect(res.body.success).to.equal(true);
+                                        expect(res.body.message).to.equal("Question skipped in test environment");
+                                        res.body.data.model.should.be.a('object');
+                                        expect(res.body.data.model.provider).to.equal("google");
+                                        expect(res.body.data.model.name).to.equal("google/gemini-2.5-flash-lite");
+                                        expect(res.body.data.model.api_key).to.equal("AQ.Ab8R-testkey");
+                                        expect(res.body.data.model.project).to.equal("poc-tiledesk-496310");
+                                        expect(res.body.data.model.location).to.equal("europe-west8");
+                                        should.not.exist(res.body.data.model.url);
+
+                                        done();
+                                    })
+                            })
+                    })
+                })
+            })
+        }).timeout(10000)
+
+        it('askkb-agentplatform-vllmServer-fallback', (done) => {
+
+            var email = "test-signup-" + Date.now() + "@email.com";
+            var pwd = "pwd";
+
+            userService.signup(email, pwd, "Test Firstname", "Test Lastname").then((savedUser) => {
+                projectService.create("test-kb-qa-agentplatform", savedUser._id).then((savedProject) => {
+
+                    Integration.create({
+                        id_project: savedProject._id.toString(),
+                        name: 'agentplatform',
+                        value: {
+                            servers: [{
+                                name: 'prod-vertex',
+                                apikey: 'AQ.Ab8R-testkey',
+                                project: 'poc-tiledesk-496310',
+                                location: 'europe-west8'
+                            }]
+                        }
+                    }).then(() => {
+
+                        chai.request(server)
+                            .get('/' + savedProject._id + '/kb/namespace/all')
+                            .auth(email, pwd)
+                            .end((err, res) => {
+
+                                if (err) { console.error("err: ", err); }
+
+                                res.should.have.status(200);
+
+                                chai.request(server)
+                                    .post('/' + savedProject._id + "/kb/qa")
+                                    .auth(email, pwd)
+                                    .send({
+                                        llm: "agentplatform",
+                                        model: "google/gemini-2.5-flash-lite",
+                                        vllmServer: "prod-vertex",
+                                        namespace: savedProject._id,
+                                        question: "sample question",
+                                        advancedPrompt: true
+                                    })
+                                    .end((err, res) => {
+
+                                        if (err) { console.error("err: ", err) };
+
+                                        res.should.have.status(200);
+                                        expect(res.body.data.model.provider).to.equal("google");
+                                        expect(res.body.data.model.project).to.equal("poc-tiledesk-496310");
+                                        expect(res.body.data.model.location).to.equal("europe-west8");
+
+                                        done();
+                                    })
+                            })
+                    })
+                })
+            })
+        }).timeout(10000)
+
+        it('askkb-agentplatform-missing-llmServer', (done) => {
+
+            var email = "test-signup-" + Date.now() + "@email.com";
+            var pwd = "pwd";
+
+            userService.signup(email, pwd, "Test Firstname", "Test Lastname").then((savedUser) => {
+                projectService.create("test-kb-qa-agentplatform", savedUser._id).then((savedProject) => {
+
+                    Integration.create({
+                        id_project: savedProject._id.toString(),
+                        name: 'agentplatform',
+                        value: {
+                            servers: [{
+                                name: 'prod-vertex',
+                                apikey: 'AQ.Ab8R-testkey',
+                                project: 'poc-tiledesk-496310',
+                                location: 'europe-west8'
+                            }]
+                        }
+                    }).then(() => {
+
+                        chai.request(server)
+                            .get('/' + savedProject._id + '/kb/namespace/all')
+                            .auth(email, pwd)
+                            .end((err, res) => {
+
+                                if (err) { console.error("err: ", err); }
+
+                                res.should.have.status(200);
+
+                                chai.request(server)
+                                    .post('/' + savedProject._id + "/kb/qa")
+                                    .auth(email, pwd)
+                                    .send({
+                                        llm: "agentplatform",
+                                        model: "google/gemini-2.5-flash-lite",
+                                        namespace: savedProject._id,
+                                        question: "sample question",
+                                        advancedPrompt: true
+                                    })
+                                    .end((err, res) => {
+
+                                        if (err) { console.error("err: ", err) };
+
+                                        res.should.have.status(422);
+                                        expect(res.body.success).to.equal(false);
+                                        expect(res.body.error).to.equal("llmServer attribute is undefined");
+
+                                        done();
+                                    })
+                            })
+                    })
+                })
+            })
+        }).timeout(10000)
+
         it('webhook', (done) => {
 
             var email = "test-signup-" + Date.now() + "@email.com";

package/test/openrouterUtils.test.js

@@ -0,0 +1,139 @@
+const { expect } = require('chai');
+const {
+    OPENROUTER_BASE_URL,
+    findModelConfig,
+    buildProviderRouting,
+    buildOpenRouterModel
+} = require('../utils/openrouterUtils');
+const { mergeIntegrationValue, maskIntegrationValue } = require('../utils/maskIntegrationSecrets');
+
+const value = {
+    apikey: 'sk-or-secret-key',
+    models: [
+        {
+            id: 'openai/gpt-4o',
+            name: 'GPT-4o',
+            providers: ['azure', 'openai'],
+            allow_fallbacks: false,
+            sort: 'price'
+        },
+        {
+            id: 'meta-llama/llama-3.3-70b',
+            name: 'Llama 3.3 70B',
+            providers: [],
+            allow_fallbacks: true,
+            sort: null
+        }
+    ]
+};
+
+describe('openrouterUtils', () => {
+
+    describe('findModelConfig', () => {
+
+        it('finds the entry for a model id', () => {
+            expect(findModelConfig(value, 'openai/gpt-4o').name).to.equal('GPT-4o');
+        })
+
+        it('returns undefined for an unknown model', () => {
+            expect(findModelConfig(value, 'anthropic/claude-opus-5')).to.be.undefined;
+        })
+
+        it('returns undefined when the integration has no models', () => {
+            expect(findModelConfig({ apikey: 'sk-or-x' }, 'openai/gpt-4o')).to.be.undefined;
+            expect(findModelConfig(undefined, 'openai/gpt-4o')).to.be.undefined;
+        })
+
+        it('returns undefined for an empty model id', () => {
+            expect(findModelConfig(value, '')).to.be.undefined;
+        })
+    })
+
+    describe('buildProviderRouting', () => {
+
+        it('carries the ordered providers, the restriction and the sort', () => {
+            expect(buildProviderRouting(value, 'openai/gpt-4o')).to.deep.equal({
+                order: ['azure', 'openai'],
+                allow_fallbacks: false,
+                sort: 'price'
+            });
+        })
+
+        it('returns undefined when a configured model has nothing to route', () => {
+            // allow_fallbacks true is OpenRouter's own default, so it says nothing.
+            expect(buildProviderRouting(value, 'meta-llama/llama-3.3-70b')).to.be.undefined;
+        })
+
+        it('returns undefined for a model that was never configured', () => {
+            expect(buildProviderRouting(value, 'anthropic/claude-opus-5')).to.be.undefined;
+        })
+
+        it('drops blank provider slugs', () => {
+            const v = { models: [{ id: 'm', providers: ['  ', 'fireworks', ''] }] };
+            expect(buildProviderRouting(v, 'm')).to.deep.equal({ order: ['fireworks'] });
+        })
+
+        it('drops an unrecognised sort', () => {
+            const v = { models: [{ id: 'm', providers: ['a'], sort: 'cheapest' }] };
+            expect(buildProviderRouting(v, 'm')).to.deep.equal({ order: ['a'] });
+        })
+
+        it('normalises the sort case', () => {
+            const v = { models: [{ id: 'm', sort: 'Latency' }] };
+            expect(buildProviderRouting(v, 'm')).to.deep.equal({ sort: 'latency' });
+        })
+    })
+
+    describe('buildOpenRouterModel', () => {
+
+        it('builds the model object the LLM microservice expects', () => {
+            expect(buildOpenRouterModel(value, 'openai/gpt-4o')).to.deep.equal({
+                provider: 'openrouter',
+                name: 'openai/gpt-4o',
+                url: OPENROUTER_BASE_URL,
+                api_key: 'sk-or-secret-key',
+                provider_routing: {
+                    order: ['azure', 'openai'],
+                    allow_fallbacks: false,
+                    sort: 'price'
+                }
+            });
+        })
+
+        it('omits provider_routing entirely for an unrouted model', () => {
+            const model = buildOpenRouterModel(value, 'anthropic/claude-opus-5');
+            expect(model).to.not.have.property('provider_routing');
+            expect(model.name).to.equal('anthropic/claude-opus-5');
+            expect(model.url).to.equal(OPENROUTER_BASE_URL);
+        })
+    })
+
+    describe('integration secret handling', () => {
+
+        it('masks the key without touching the model list', () => {
+            const masked = maskIntegrationValue(value);
+            const stars = '*'.repeat(value.apikey.length - 7);
+
+            expect(masked.apikey).to.equal('sk-' + stars + '-key');
+            expect(masked.models).to.deep.equal(value.models);
+        })
+
+        it('replaces the model list wholesale while keeping the stored key', () => {
+            const incoming = {
+                apikey: 'sk-***********-key', // masked: the dashboard echoes it back
+                models: [{ id: 'openai/gpt-4o', name: 'GPT-4o', providers: ['openai'] }]
+            };
+
+            const merged = mergeIntegrationValue(incoming, value);
+
+            expect(merged.apikey).to.equal('sk-or-secret-key');
+            expect(merged.models).to.have.lengthOf(1);
+            expect(merged.models[0].providers).to.deep.equal(['openai']);
+        })
+
+        it('lets the last model be removed', () => {
+            const merged = mergeIntegrationValue({ apikey: 'sk-***********-key', models: [] }, value);
+            expect(merged.models).to.deep.equal([]);
+        })
+    })
+})

package/utils/openrouterUtils.js

@@ -0,0 +1,89 @@
+/**
+ * OpenRouter provider routing.
+ *
+ * The dashboard stores, per model, which upstream providers may serve it and
+ * in what order:
+ *
+ *   integration.value = {
+ *     apikey: "sk-or-...",
+ *     models: [
+ *       { id: "openai/gpt-4o", name: "GPT-4o",
+ *         providers: ["azure", "openai"], allow_fallbacks: true, sort: "price" }
+ *     ]
+ *   }
+ *
+ * This turns one of those entries into the routing object the LLM microservice
+ * forwards to OpenRouter as the request's "provider" block.
+ */
+
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+
+const SORT_VALUES = ['price', 'throughput', 'latency'];
+
+/** The stored configuration for one model id, or undefined when it has none. */
+function findModelConfig(value, model) {
+    const models = value && Array.isArray(value.models) ? value.models : [];
+    const wanted = String(model || '').trim();
+    if (!wanted) {
+        return undefined;
+    }
+    return models.find((entry) => entry && String(entry.id || '').trim() === wanted);
+}
+
+/**
+ * Build the routing block for a model.
+ *
+ * Returns undefined when the model carries nothing worth routing, so an
+ * unconfigured model behaves exactly like any other OpenAI-compatible
+ * provider instead of being pinned to an empty provider list.
+ */
+function buildProviderRouting(value, model) {
+    const config = findModelConfig(value, model);
+    if (!config) {
+        return undefined;
+    }
+
+    const routing = {};
+
+    const order = (Array.isArray(config.providers) ? config.providers : [])
+        .map((provider) => String(provider || '').trim())
+        .filter((provider) => !!provider);
+    if (order.length > 0) {
+        routing.order = order;
+    }
+
+    // true is OpenRouter's own default, so only the restrictive choice is worth sending.
+    if (config.allow_fallbacks === false) {
+        routing.allow_fallbacks = false;
+    }
+
+    const sort = String(config.sort || '').trim().toLowerCase();
+    if (SORT_VALUES.includes(sort)) {
+        routing.sort = sort;
+    }
+
+    return Object.keys(routing).length > 0 ? routing : undefined;
+}
+
+/**
+ * The model object the LLM microservice expects for an OpenRouter call.
+ * `provider_routing` is omitted entirely when there is nothing to route.
+ */
+function buildOpenRouterModel(value, model) {
+    const routing = buildProviderRouting(value, model);
+
+    return {
+        provider: 'openrouter',
+        name: model,
+        url: OPENROUTER_BASE_URL,
+        api_key: (value && value.apikey) || '',
+        ...(routing && { provider_routing: routing })
+    };
+}
+
+module.exports = {
+    OPENROUTER_BASE_URL,
+    findModelConfig,
+    buildProviderRouting,
+    buildOpenRouterModel
+};