ratacode 0.2.5

package/mcp/lib/http.js

@@ -0,0 +1,184 @@
+/**
+ * http — transporte Streamable HTTP para RATACODE-MCP.
+ *
+ * El MISMO servidor de herramientas que habla por stdio, ahora también por
+ * HTTP en `127.0.0.1:<puerto>/mcp/<clave>`. La clave va en la propia URL
+ * (nunca en el repositorio: se genera y se guarda en la casa). Cada petición
+ * se atiende con un `McpServer` nuevo que COMPARTE el registro de tareas, así
+ * `get_task_result` ve las tareas de otras sesiones y el tope por hora es
+ * global. Modo sin estado (stateless): cada POST es independiente, que es justo
+ * lo que necesitan estas siete herramientas.
+ *
+ * Sólo escucha en loopback. La exposición a Internet es cosa del túnel
+ * (tunel.mjs), que lo decide el usuario. Y lo que se expone va encerrado: cada
+ * tarea lee y escribe sólo dentro de las carpetas autorizadas, sin terminal y
+ * sin red (mira `lib/lectura.js`), así que aquí no hay nada que aceptar.
+ *
+ * Cuatro reglas que se cumplen aquí, y todas se prueban:
+ *   1 · LA CLAVE NO SE REGISTRA. Ni en los avisos ni en los errores: en el
+ *       registro la ruta sale como `/mcp/<oculta>`. (Antes, un error escribía
+ *       `req.url` con la clave dentro, y los clientes MCP guardan ese stderr.)
+ *   2 · LA CLAVE SE COMPARA EN TIEMPO CONSTANTE (`crypto.timingSafeEqual`).
+ *   3 · EL CUERPO TIENE TOPE, Y AL PASARSE SE CONTESTA 413 (no se mata el
+ *       socket antes de contestar: el cliente se merece una respuesta).
+ *   4 · HAY TOPE DE PETICIONES A LA VEZ: cada POST autenticado crea un servidor
+ *       MCP y un transporte; sin tope, la URL abierta es una fábrica de ellos.
+ *
+ * Y una quinta, para poder rotar la clave SIN reiniciar: si se le da la ruta
+ * del fichero de la clave, este módulo la relee cada pocos segundos y adopta la
+ * nueva. Así `tunel.mjs` puede estrenar clave al abrir el túnel y el servidor
+ * que ya está en marcha la acepta.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { aviso } from './registro.js';
+
+/** Tope del cuerpo de una petición (5 MB: ningún prompt legítimo se acerca). */
+const TOPE_CUERPO = 5_000_000;
+/** Tope por defecto de peticiones atendidas a la vez. */
+const SIMULTANEAS_DEFECTO = 8;
+/** Cada cuánto se mira si la clave del fichero ha cambiado. */
+const MS_REVISION_CLAVE = 2000;
+
+/** Leer el cuerpo JSON de una petición, con tope. */
+function leerCuerpo(req) {
+  return new Promise((listo, rechaza) => {
+    const trozos = [];
+    let total = 0;
+    let pasado = false;
+    req.on('data', (t) => {
+      if (pasado) return;
+      total += t.length;
+      if (total > TOPE_CUERPO) {
+        pasado = true;
+        trozos.length = 0;
+        const error = new Error('cuerpo demasiado grande');
+        error.codigo = 413;
+        rechaza(error);
+        return;
+      }
+      trozos.push(t);
+    });
+    req.on('end', () => {
+      if (pasado) return;
+      const texto = Buffer.concat(trozos).toString('utf8').trim();
+      if (texto === '') return listo(undefined);
+      try { listo(JSON.parse(texto)); } catch { rechaza(new Error('cuerpo JSON inválido')); }
+    });
+    req.on('error', rechaza);
+  });
+}
+
+/** ¿Es esta la clave buena? En tiempo constante, y sin decir por qué falla. */
+function claveValida(recibida, buena) {
+  if (typeof recibida !== 'string' || typeof buena !== 'string' || buena === '') return false;
+  const a = Buffer.from(recibida, 'utf8');
+  const b = Buffer.from(buena, 'utf8');
+  // Longitudes distintas: no se puede comparar en tiempo constante, y una clave
+  // con otra longitud no es la clave. (La nuestra es hex de 64: no filtra nada.)
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Arrancar el servidor HTTP.
+ * @param {{fabricaServidor: () => import('@modelcontextprotocol/sdk/server/mcp.js').McpServer, puerto: number, clave: string, rutaClave?: string, alRotar?: (nueva: string) => void, host?: string, simultaneas?: number}} opciones
+ * @returns {Promise<{servidor: import('node:http').Server, claveActual: () => string, parar: () => void}>} ya escuchando.
+ */
+export function iniciarServidorHttp({ fabricaServidor, puerto, clave, rutaClave, alRotar, host = '127.0.0.1', simultaneas = SIMULTANEAS_DEFECTO }) {
+  /** La clave viva: puede cambiar si `tunel.mjs` estrena una. */
+  let claveViva = clave;
+  let atendiendose = 0;
+  let temporizadorClave;
+
+  if (typeof rutaClave === 'string' && rutaClave !== '') {
+    temporizadorClave = setInterval(() => {
+      try {
+        const leida = readFileSync(rutaClave, 'utf8').trim();
+        if (leida !== '' && leida !== claveViva) {
+          claveViva = leida;
+          aviso('http: clave rotada (la nueva está en ' + rutaClave + '); la URL ha cambiado');
+          if (typeof alRotar === 'function') alRotar(leida);
+        }
+      } catch { /* sin fichero legible se sigue con la que había */ }
+    }, MS_REVISION_CLAVE);
+    if (typeof temporizadorClave.unref === 'function') temporizadorClave.unref();
+  }
+
+  const server = createServer((req, res) => {
+    manejar(req, res).catch((e) => {
+      // NUNCA `req.url`: lleva la clave. Y nunca el valor de la clave.
+      aviso('http: error manejando ' + req.method + ' /mcp/<oculta>: ' + (e?.message ?? e));
+      if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' }).end('Error interno');
+      else res.end();
+    });
+  });
+
+  async function manejar(req, res) {
+    const url = new URL(req.url ?? '/', 'http://' + (req.headers.host ?? 'localhost'));
+    const partes = url.pathname.split('/').filter(Boolean); // ['mcp', '<clave>']
+    if (partes[0] !== 'mcp' || !claveValida(partes[1], claveViva)) {
+      res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('Not found');
+      return;
+    }
+
+    if (req.method === 'POST') {
+      if (atendiendose >= simultaneas) {
+        res.writeHead(503, { 'content-type': 'text/plain; charset=utf-8', 'retry-after': '5' })
+          .end('Demasiadas peticiones a la vez (máximo ' + simultaneas + '). Prueba dentro de un momento.');
+        return;
+      }
+      let cuerpo;
+      try {
+        cuerpo = await leerCuerpo(req);
+      } catch (e) {
+        const codigo = e?.codigo === 413 ? 413 : 400;
+        res.writeHead(codigo, { 'content-type': 'text/plain; charset=utf-8', connection: 'close' })
+          .end(codigo === 413 ? 'Cuerpo demasiado grande (máximo 5 MB)' : 'Bad request');
+        // Se contesta PRIMERO y se cierra DESPUÉS: matar el socket antes deja al
+        // cliente sin respuesta (medido: `curl` terminaba en exit 56 sin HTTP).
+        res.on('finish', () => req.destroy());
+        return;
+      }
+      atendiendose += 1;
+      try {
+        const transporte = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        const servidor = fabricaServidor();
+        await servidor.connect(transporte);
+        res.on('close', () => { servidor.close().catch(() => {}); transporte.close().catch(() => {}); });
+        await transporte.handleRequest(req, res, cuerpo);
+      } finally {
+        atendiendose -= 1;
+      }
+      return;
+    }
+
+    if (req.method === 'GET' || req.method === 'DELETE') {
+      // Sin estado: no hay sesiones que mantener ni stream SSE persistente.
+      res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8' })
+        .end('Método no permitido en modo sin estado (usa POST)');
+      return;
+    }
+
+    res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8' }).end('Método no permitido');
+  }
+
+  const escuchando = new Promise((listo, rechaza) => {
+    server.once('error', rechaza);
+    server.listen(puerto, host, () => {
+      server.removeListener('error', rechaza);
+      listo(server);
+    });
+  });
+
+  return escuchando.then(() => ({
+    servidor: server,
+    claveActual: () => claveViva,
+    parar: () => {
+      if (temporizadorClave !== undefined) clearInterval(temporizadorClave);
+      server.close();
+    },
+  }));
+}

package/mcp/lib/lectura.js

@@ -0,0 +1,210 @@
+/**
+ * lectura — LA LECTURA, ENCERRADA DE VERDAD (R25).
+ *
+ * ── LO QUE DICE EL MOTOR (medido, con el código delante) ───────────────────
+ *   · `dsh-fs-sandbox/lib/types/index.d.ts:7-8` — «Reads pass through
+ *     untouched: every mode permits reading.»
+ *   · `dsh-sandbox/lib/types/roots.d.ts:28-36` — la ÚNICA lista de raíces que
+ *     el motor sabe derivar es la de ESCRITURA (`writableRoots`).
+ *   · `dsh-sandbox-windows-acl/lib/types/index.d.ts:24-25` — «writes are
+ *     restricted; reads, network, and process visibility are NOT».
+ *   · El vocabulario de modos (`read-only | workspace-write |
+ *     danger-full-access`) es un eje de EFECTOS SOBRE FICHEROS: `read-only`
+ *     deniega toda MUTACIÓN, no toda lectura.
+ *
+ * O sea: NO hay modo, ni ajuste, ni plugin del motor que encierre la LECTURA.
+ * Lo que SÍ hay es un gancho de permiso POR HERRAMIENTA: `tools/pre-execute`
+ * (`dsh-tools/lib/types/index.d.ts:29-38`), que ve cada llamada antes de
+ * ejecutarse y puede contestar `{kind:'deny', reason}` (`dsh-tools/lib/index.js:3116-3135`).
+ *
+ * ── ESTE FICHERO ES DOS COSAS A LA VEZ ─────────────────────────────────────
+ *   1 · las funciones PURAS que deciden si una ruta está dentro de las
+ *       carpetas autorizadas, normalizando de verdad: rutas relativas, `..`,
+ *       mayúsculas/minúsculas de Windows, enlaces y uniones (realpath del trozo
+ *       que existe), UNC (`\\servidor\recurso`) y el prefijo de rutas largas
+ *       (`\\?\C:\…`, `\\?\UNC\…`);
+ *   2 · el PLUGIN DE CORDIS que el motor monta en cada tarea del MCP: se
+ *       inserta por parche y engancha `tools/pre-execute`. Deniega con UNA
+ *       línea: «Fuera de la carpeta autorizada: <ruta>».
+ *
+ * El MCP copia este fichero junto al parche (`<casa>\mcp\tmp\lectura.js`) y el
+ * parche lo inserta por su nombre relativo: el motor resuelve `./lectura.js`
+ * desde la CARPETA DEL PARCHE (`cordis-plugin-loader/lib/index.js:273-278`),
+ * medido. Por eso el fichero es autosuficiente: sólo usa módulos de Node.
+ */
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+
+/** ¿Es Windows? (allí las rutas no distinguen mayúsculas) */
+const ES_WINDOWS = process.platform === 'win32';
+
+/** La línea que ve el agente cuando la herramienta se para. Una, y con la ruta. */
+export function motivoFuera(ruta) {
+  return 'Fuera de la carpeta autorizada: ' + ruta;
+}
+
+/**
+ * Las claves de los argumentos que llevan una ruta, medidas en las herramientas
+ * del motor: `file_path` (dsh-tool-fs: read, read_image, write, edit), `path`
+ * (dsh-tool-fs-search: glob, grep) y `files[].path` (dsh-tool-present).
+ * Un nombre que NO esté aquí no se mira: el cuerpo de un texto (`old_string`,
+ * `content`, un encargo) no es una ruta y no se toca.
+ */
+export const CLAVES_DE_RUTA = [
+  'file_path', 'path', 'dir', 'directory', 'cwd', 'working_directory',
+  'root', 'workspace', 'files', 'paths',
+];
+
+/**
+ * La forma canónica de una ruta:
+ *   · quita el prefijo de rutas largas de Windows (`\\?\`, `\\?\UNC\`);
+ *   · resuelve lo relativo contra `cwd` (el espacio de la tarea);
+ *   · resuelve `..`, barras repetidas y barras al revés (lo hace `resolve`);
+ *   · sigue los enlaces/uniones del trozo que EXISTE (realpath), y deja el
+ *     resto tal cual: una ruta que aún no existe (un `write`) también se juzga,
+ *     y se juzga por dónde va a caer de verdad.
+ * @param {string} ruta - lo que pidió la herramienta.
+ * @param {string} [cwd] - desde dónde se resuelve lo relativo.
+ * @returns {string} la ruta canónica.
+ */
+export function canonica(ruta, cwd = process.cwd()) {
+  let texto = String(ruta ?? '').trim();
+  if (texto === '') return '';
+  // \\?\UNC\servidor\recurso\… → \\servidor\recurso\…
+  if (/^\\\\\?\\UNC\\/i.test(texto)) texto = '\\\\' + texto.slice(8);
+  // \\?\C:\… → C:\…
+  else if (/^\\\\\?\\/.test(texto)) texto = texto.slice(4);
+  // Y lo mismo con barras normales (una ruta copiada de un chat).
+  if (/^\/\/\?\/UNC\//i.test(texto)) texto = '\\\\' + texto.slice(8);
+  else if (/^\/\/\?\//.test(texto)) texto = texto.slice(4);
+  return realDe(resolve(cwd, texto));
+}
+
+/** Un alias del nombre que usa `seguridad.js` para lo mismo. */
+export const normalizarRuta = canonica;
+
+/**
+ * `realpath` del trozo que existe. Si `C:\a\enlace\no-existe.txt` tiene el
+ * enlace en medio, lo que importa es dónde acaba el enlace, no el nombre.
+ * @param {string} absoluta - ruta absoluta ya resuelta.
+ * @returns {string} la ruta con los enlaces resueltos.
+ */
+function realDe(absoluta) {
+  let actual = absoluta;
+  const cola = [];
+  for (;;) {
+    try {
+      const real = realpathSync.native(actual);
+      return cola.length === 0 ? real : join(real, ...cola.reverse());
+    } catch {
+      const padre = dirname(actual);
+      // Se llegó a la raíz (o a algo que no se puede mirar): se devuelve la ruta
+      // resuelta tal cual, que ya no tiene `..` ni prefijos raros.
+      if (padre === actual) return absoluta;
+      cola.push(basename(actual));
+      actual = padre;
+    }
+  }
+}
+
+/** La forma comparable de una ruta (en Windows, sin distinguir mayúsculas). */
+export function comparable(ruta) {
+  const limpia = ruta.endsWith(sep) && ruta.length > 1 ? ruta.slice(0, -1) : ruta;
+  return ES_WINDOWS ? limpia.toLowerCase() : limpia;
+}
+
+/**
+ * ¿`hijo` está dentro de `raiz` (o es `raiz`)? Las dos, ya normalizadas.
+ * @param {string} hijo - ruta normalizada.
+ * @param {string} raiz - ruta normalizada.
+ * @returns {boolean}
+ */
+export function estaDentro(hijo, raiz) {
+  const a = comparable(hijo);
+  const b = comparable(raiz);
+  if (a === b) return true;
+  return a.startsWith(b.endsWith(sep) ? b : b + sep);
+}
+
+/**
+ * ¿La ruta cae dentro de ALGUNA de las raíces autorizadas?
+ * @param {string} ruta - la ruta pedida (cruda).
+ * @param {string[]} raices - las carpetas autorizadas (crudas).
+ * @param {string} [cwd] - desde dónde se resuelve lo relativo.
+ * @returns {{dentro: boolean, canonica: string}}
+ */
+export function dentroDeAlguna(ruta, raices, cwd) {
+  const suya = canonica(ruta, cwd);
+  if (suya === '') return { dentro: true, canonica: suya };
+  for (const raiz of raices ?? []) {
+    const canonRaiz = canonica(raiz, cwd);
+    if (canonRaiz === '') continue;
+    if (estaDentro(suya, canonRaiz)) return { dentro: true, canonica: suya };
+  }
+  return { dentro: false, canonica: suya };
+}
+
+/**
+ * Las rutas que lleva una llamada a herramienta. Se miran las claves conocidas
+ * ({@link CLAVES_DE_RUTA}) en el primer nivel y en los objetos de dentro
+ * (`files: [{path: …}]`), nunca el texto libre.
+ * @param {object} entrada - los argumentos de la herramienta.
+ * @param {number} [profundidad] - cuántos niveles de objeto se miran.
+ * @returns {string[]} las rutas encontradas, tal cual venían.
+ */
+export function rutasDe(entrada, profundidad = 2) {
+  const salida = [];
+  if (entrada === null || typeof entrada !== 'object' || profundidad < 0) return salida;
+  for (const [clave, valor] of Object.entries(entrada)) {
+    if (CLAVES_DE_RUTA.includes(clave)) {
+      if (typeof valor === 'string') {
+        if (valor.trim() !== '') salida.push(valor);
+      } else if (Array.isArray(valor)) {
+        for (const uno of valor) {
+          if (typeof uno === 'string' && uno.trim() !== '') salida.push(uno);
+          else if (uno !== null && typeof uno === 'object' && typeof uno.path === 'string' && uno.path.trim() !== '') salida.push(uno.path);
+        }
+      }
+      continue;
+    }
+    if (valor !== null && typeof valor === 'object') salida.push(...rutasDe(valor, profundidad - 1));
+  }
+  return salida;
+}
+
+/**
+ * La decisión del cerco para UNA llamada.
+ * @param {{entrada: object, raices: string[], cwd?: string}} opciones
+ * @returns {{fuera: string}|null} la ruta que se sale, o null si todo está dentro.
+ */
+export function decidir({ entrada, raices, cwd }) {
+  if (!Array.isArray(raices) || raices.length === 0) return { fuera: '(sin carpetas autorizadas)' };
+  for (const ruta of rutasDe(entrada)) {
+    const juicio = dentroDeAlguna(ruta, raices, cwd);
+    if (!juicio.dentro) return { fuera: ruta };
+  }
+  return null;
+}
+
+// ── EL PLUGIN ──────────────────────────────────────────────────────────────
+// Esto es lo que el motor monta: una fila insertada por el parche del MCP.
+
+/** El nombre del plugin en la composición del motor. */
+export const name = 'ratacode-cerco';
+
+/**
+ * Engancha `tools/pre-execute` y deniega la herramienta que lleve una ruta
+ * fuera de las carpetas autorizadas. Sin raíces NO deja pasar nada (falla
+ * cerrado): una tarea del MCP siempre las trae.
+ * @param {object} ctx - el contexto de cordis.
+ * @param {{raices?: string[]}} [config] - las carpetas autorizadas, del parche.
+ */
+export function apply(ctx, config) {
+  const raices = Array.isArray(config?.raices) ? config.raices.filter((r) => typeof r === 'string' && r.trim() !== '') : [];
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    const cwd = exec?.agent?.session?.header?.cwd ?? process.cwd();
+    const juicio = decidir({ entrada: exec?.arguments ?? {}, raices, cwd });
+    if (juicio === null) return next();
+    return { kind: 'deny', reason: motivoFuera(juicio.fuera) };
+  });
+}

package/mcp/lib/modelos.js

@@ -0,0 +1,235 @@
+/**
+ * modelos — el catálogo de proveedores y modelos de la casa.
+ *
+ * De dónde sale, y por qué así: el core monta el adaptador `llm-pi-ai` DORMIDO
+ * (cero rutas) hasta que `settings.yaml` trae una sección `llm-pi-ai:`
+ * (`dsh-base/cordis.patch.yml:100-108`). O sea: el catálogo de proveedores y
+ * modelos del usuario ES ese documento. Leerlo aquí no duplica la lógica del
+ * core — es leer la misma configuración que el core lee, igual que hace la web.
+ *
+ * Lo que este módulo NO hace: llamar a la red, adivinar modelos, ni inventarse
+ * precios. Si un dato no está, se devuelve `null` y se dice.
+ */
+import { ajustesMcp, leerAjustes } from './casa.js';
+import { describeEnLaCasa, faltaLaClave } from './claves.js';
+
+/** El id de la ruta nativa de DeepSeek en el core (medido en `dsh-sdk-jsonrpc-server/lib/index.js:118`). */
+export const PROVEEDOR_NATIVO = 'deepseek-official';
+/** Lo que la ruta nativa resuelve por defecto si el usuario no dice otra cosa. */
+const CLAVE_NATIVA_POR_DEFECTO = 'DEEPSEEK_API_KEY';
+
+/** Un objeto-mapa, o {}. */
+function mapa(valor) {
+  return valor !== null && typeof valor === 'object' && !Array.isArray(valor) ? valor : {};
+}
+
+/** Número finito, o null. */
+function numero(valor) {
+  return typeof valor === 'number' && Number.isFinite(valor) ? valor : null;
+}
+
+/** Texto no vacío, o null. */
+function texto(valor) {
+  return typeof valor === 'string' && valor.trim() !== '' ? valor : null;
+}
+
+/**
+ * El catálogo completo de la casa. Las claves NO se miran en el entorno: se le
+ * pregunta al almacén de la casa (Ajustes › Models) por la vía del motor, que
+ * contesta configurada sí/no y nunca un valor.
+ * @param {string} casa - la casa de RATACODE.
+ * @returns {Promise<{proveedores: object[], modelos: object[], porDefecto: {provider: string|null, model: string|null}, avisos: string[]}>}
+ */
+export async function catalogo(casa) {
+  const { documento, error } = leerAjustes(casa);
+  const ajustes = ajustesMcp(casa);
+  const avisos = [];
+  if (error !== null) avisos.push(error);
+  avisos.push(...ajustes.avisos);
+
+  // Una sola pregunta por variable, aunque la nombren varias rutas.
+  const preguntas = new Map();
+  const describe = async (nombre) => {
+    if (nombre === null) return null;
+    if (!preguntas.has(nombre)) preguntas.set(nombre, await describeEnLaCasa(casa, nombre));
+    return preguntas.get(nombre);
+  };
+
+  const proveedores = [];
+  const modelos = [];
+
+  // ── las rutas que declara el usuario (llm-pi-ai.providers) ────────────────
+  const piAi = mapa(documento['llm-pi-ai']);
+  const declarados = mapa(piAi.providers);
+  for (const [id, perfilBruto] of Object.entries(declarados)) {
+    const perfil = mapa(perfilBruto);
+    const apiKeyEnv = texto(perfil.apiKeyEnv);
+    const nombre = texto(perfil.displayName) ?? id;
+    const cred = await describe(apiKeyEnv);
+    const tiene = cred !== null && cred.configurada === true;
+    proveedores.push({
+      id,
+      nombre,
+      api: texto(perfil.api),
+      base_url: texto(perfil.baseURL),
+      credencial: apiKeyEnv,
+      tiene_clave: tiene,
+      falta: apiKeyEnv === null || cred === null || cred.motivo !== null || tiene ? null : faltaLaClave(nombre),
+      declarado_por_el_usuario: true,
+    });
+    const lista = Array.isArray(perfil.models) ? perfil.models : [];
+    for (const modeloBruto of lista) {
+      const modelo = mapa(modeloBruto);
+      const modelId = texto(modelo.id);
+      if (modelId === null) {
+        avisos.push('el proveedor «' + id + '» tiene un modelo sin id; lo salto');
+        continue;
+      }
+      modelos.push(fichaModelo({ casa, ajustes, provider: id, modelo, modelId, tieneClave: tiene }));
+    }
+  }
+
+  // ── la ruta nativa de DeepSeek (siempre montada en el core) ───────────────
+  const nativo = mapa(documento['llm-deepseek']);
+  const claveNativa = texto(nativo.apiKeyEnv) ?? CLAVE_NATIVA_POR_DEFECTO;
+  const credNativa = await describe(claveNativa);
+  const estaNativa = credNativa !== null && credNativa.configurada === true;
+  const nombreNativo = texto(nativo.displayName) ?? 'DeepSeek (nativo)';
+  proveedores.push({
+    id: PROVEEDOR_NATIVO,
+    nombre: nombreNativo,
+    api: texto(nativo.api),
+    base_url: texto(nativo.baseURL),
+    credencial: claveNativa,
+    tiene_clave: estaNativa,
+    falta: estaNativa || credNativa === null || credNativa.motivo !== null ? null : faltaLaClave(nombreNativo),
+    declarado_por_el_usuario: Object.keys(nativo).length > 0,
+  });
+  const modelosNativos = Array.isArray(nativo.models) ? nativo.models : [];
+  for (const modeloBruto of modelosNativos) {
+    const modelo = mapa(modeloBruto);
+    const modelId = texto(modelo.id);
+    if (modelId === null) continue;
+    modelos.push(fichaModelo({ casa, ajustes, provider: PROVEEDOR_NATIVO, modelo, modelId, tieneClave: estaNativa }));
+  }
+
+  // ── el modelo por defecto de la casa ─────────────────────────────────────
+  const porDefecto = modeloPorDefecto(casa);
+  if (porDefecto.provider !== null && porDefecto.model !== null) {
+    for (const ficha of modelos) {
+      ficha.es_por_defecto = ficha.provider === porDefecto.provider && ficha.model_id === porDefecto.model;
+    }
+  } else {
+    avisos.push('la casa no tiene `agent-default-model`: habrá que decir proveedor y modelo en cada tarea');
+  }
+
+  return { proveedores, modelos, porDefecto, avisos };
+}
+
+/**
+ * El modelo por defecto de la casa (`agent-default-model`). Sólo lee los
+ * ajustes: aquí no hay ninguna credencial de por medio.
+ * @param {string} casa - la casa de RATACODE.
+ * @returns {{provider: string|null, model: string|null}}
+ */
+export function modeloPorDefecto(casa) {
+  const { documento } = leerAjustes(casa);
+  const bruto = mapa(documento['agent-default-model']);
+  return { provider: texto(bruto.provider), model: texto(bruto.model) };
+}
+
+/** Una ficha de modelo, con lo que se sabe y con null en lo que no. */
+function fichaModelo({ casa, ajustes, provider, modelo, modelId, tieneClave }) {
+  const capacidades = Array.isArray(modelo.input) ? modelo.input.filter((m) => typeof m === 'string') : null;
+  return {
+    name: texto(modelo.name) ?? modelId,
+    provider,
+    model_id: modelId,
+    contexto: numero(modelo.contextWindow),
+    max_tokens: numero(modelo.maxTokens),
+    capacidades,
+    coste: precioDe(ajustes.precios, provider, modelId),
+    // `disponible` = la clave está guardada en la casa (Ajustes › Models); si
+    // no, el motor no tendrá con qué y la tarea no llega a salir.
+    estado: tieneClave ? 'disponible' : 'sin_clave',
+    es_por_defecto: false,
+    descripcion: texto(modelo.description),
+  };
+}
+
+/**
+ * El precio declarado a mano en `mcp.precios`, si el humano lo puso.
+ * El core no trae precios de texto (medido: `dsh-llm` sólo tiene precios de
+ * imagen), así que o está aquí o se devuelve null. No se inventa nada.
+ * @param {object} precios - la sección `mcp.precios`.
+ * @param {string} provider - ruta del proveedor.
+ * @param {string} modelId - id del modelo.
+ * @returns {object|null} el precio tal cual lo declaró el humano, o null.
+ */
+function precioDe(precios, provider, modelId) {
+  const porProveedor = precios[provider];
+  if (porProveedor === null || typeof porProveedor !== 'object') return null;
+  const entrada = porProveedor[modelId];
+  if (entrada === null || typeof entrada !== 'object') return null;
+  return { ...entrada, moneda: typeof entrada.moneda === 'string' ? entrada.moneda : 'EUR', origen: 'mcp.precios' };
+}
+
+/**
+ * La credencial que necesita una ruta, y si la casa la tiene guardada. Sirve
+ * para PARAR ANTES de arrancar nada cuando no hay clave por ningún lado, en vez
+ * de dejar que el motor falle nueve segundos después con un error más oscuro.
+ * La respuesta la da el almacén de la casa (Ajustes › Models) por la vía del
+ * motor: aquí no se lee ningún fichero de claves ni se mira el entorno.
+ * @param {string} casa - la casa de RATACODE.
+ * @param {string} provider - la ruta del proveedor.
+ * @returns {Promise<{nombre: string, nombreVisible: string, configurada: boolean, motivo: string|null}|null>}
+ *   null si la ruta no declara credencial (Ollama y LM Studio: no piden clave).
+ */
+export async function credencialDeProveedor(casa, provider) {
+  const { documento } = leerAjustes(casa);
+  if (provider === PROVEEDOR_NATIVO) {
+    const nativo = mapa(documento['llm-deepseek']);
+    const nombre = texto(nativo.apiKeyEnv) ?? CLAVE_NATIVA_POR_DEFECTO;
+    const dicho = await describeEnLaCasa(casa, nombre);
+    return { nombre, nombreVisible: texto(nativo.displayName) ?? 'DeepSeek', ...dicho };
+  }
+  const perfil = mapa(mapa(documento['llm-pi-ai']).providers)[provider];
+  if (perfil === null || typeof perfil !== 'object') return null;
+  const nombre = texto(mapa(perfil).apiKeyEnv);
+  if (nombre === null) return null;
+  const dicho = await describeEnLaCasa(casa, nombre);
+  return { nombre, nombreVisible: texto(mapa(perfil).displayName) ?? provider, ...dicho };
+}
+
+/**
+ * La ruta que se usará si el cliente no dice nada, y si se puede usar.
+ * Sin routing oculto: esto sólo lee el modelo por defecto de la casa.
+ * @param {string} casa - la casa de RATACODE.
+ * @param {string|undefined} provider - lo que pidió el cliente.
+ * @param {string|undefined} model - lo que pidió el cliente.
+ * @returns {{provider: string, model: string, origen: 'peticion'|'por_defecto'}}
+ */
+export function resolverRuta(casa, provider, model) {
+  const pedidoProvider = texto(provider);
+  const pedidoModel = texto(model);
+  if (pedidoProvider !== null && pedidoModel !== null) {
+    return { provider: pedidoProvider, model: pedidoModel, origen: 'peticion' };
+  }
+  const porDefecto = modeloPorDefecto(casa);
+  if (pedidoProvider !== null && pedidoModel === null) {
+    if (porDefecto.provider === pedidoProvider && porDefecto.model !== null) {
+      return { provider: pedidoProvider, model: porDefecto.model, origen: 'por_defecto' };
+    }
+    throw new Error('me diste el proveedor «' + pedidoProvider + '» pero no el modelo, y el modelo por defecto de la casa es de otra ruta. Dime el modelo (mira list_models).');
+  }
+  if (pedidoProvider === null && pedidoModel !== null) {
+    if (porDefecto.model === pedidoModel && porDefecto.provider !== null) {
+      return { provider: porDefecto.provider, model: pedidoModel, origen: 'por_defecto' };
+    }
+    throw new Error('me diste el modelo «' + pedidoModel + '» pero no el proveedor, y el modelo por defecto de la casa es otro. Dime el proveedor (mira list_models).');
+  }
+  if (porDefecto.provider === null || porDefecto.model === null) {
+    throw new Error('no me has dicho proveedor ni modelo, y la casa no tiene `agent-default-model`. Dime los dos (mira list_models).');
+  }
+  return { provider: porDefecto.provider, model: porDefecto.model, origen: 'por_defecto' };
+}