ratacode 0.2.5

package/mcp/bin/ratacode-mcp.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * ratacode-mcp — el servidor MCP de RATACODE.
+ *
+ *   ratacode-mcp                 habla MCP por stdio (lo que espera un cliente)
+ *   ratacode-mcp --status        enseña el estado y sale (sin arrancar el motor)
+ *   ratacode-mcp --http          también por Streamable HTTP en 127.0.0.1:<puerto>/mcp/<clave>
+ *   ratacode-mcp --home <ruta>   usa otra casa (por defecto %USERPROFILE%\.ratacode)
+ *   ratacode-mcp --dsh <ruta>    usa otro binario del motor (para pruebas)
+ *
+ * Por stdio, stdout es del protocolo: aquí TODO lo que contamos va a stderr.
+ * Por HTTP, la clave va en la propia URL y se guarda en la casa (nunca en el
+ * repositorio). El puerto por defecto es 3778; el tope de tareas por hora es 30.
+ *
+ * Y CADA TAREA VA ENCERRADA (R25): dentro de las carpetas de `mcp.workspaces`,
+ * sin terminal, sin red, sin subagentes y sin guiones, y con la LECTURA
+ * encerrada por el gancho `PreToolUse` (mira `lib/lectura.js`). Por eso el HTTP
+ * ya NO pide ninguna bandera de aceptación: no hay nada que aceptar.
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { binDelMotor, resolverCasa } from '../lib/casa.js';
+import { aviso, fallo } from '../lib/registro.js';
+import { montarServidor } from '../lib/servidor.js';
+import { iniciarServidorHttp } from '../lib/http.js';
+import { estadoDeLaCasa } from '../lib/tareas.js';
+
+/** Puerto por defecto del transporte HTTP. */
+const PUERTO_HTTP_DEFECTO = 3778;
+/** Tope de tareas por hora por defecto. */
+const TAREAS_POR_HORA_DEFECTO = 30;
+
+/** La línea de órdenes. */
+function uso() {
+  return [
+    'RATACODE-MCP · el servidor MCP de RATACODE',
+    '',
+    '  ratacode-mcp [opciones]',
+    '',
+    '  --home <ruta>        dónde vive la casa de RATACODE (por defecto %USERPROFILE%\\.ratacode)',
+    '  --dsh <ruta>         motor a usar (por defecto, el del paquete instalado)',
+    '  --status             enseña el estado del MCP y sale',
+    '  --http               también por Streamable HTTP en 127.0.0.1:<puerto>/mcp/<clave>',
+    '  --acepto-lectura-total  ya NO hace falta (y no hace nada): la lectura va encerrada',
+    '                       en las carpetas de `mcp.workspaces`. Se acepta por no romper',
+    '                       los guiones antiguos',
+    '  --nueva-clave        estrena una clave HTTP nueva (por defecto se reutiliza la guardada)',
+    '  --port <n>           puerto HTTP (por defecto ' + PUERTO_HTTP_DEFECTO + ')',
+    '  --tareas-por-hora <n> tope de tareas por hora (por defecto ' + TAREAS_POR_HORA_DEFECTO + ')',
+    '  -h, --help           esto',
+    '',
+    'Sin opciones, habla MCP por stdio (lo que espera cualquier cliente MCP local).',
+    'Con --http, habla por los dos a la vez; la clave de la URL se genera y se',
+    'guarda en la casa (en <casa>\\mcp\\http-secret.txt), nunca en el repositorio.',
+    '',
+    'CADA TAREA VA ENCERRADA en las carpetas de `mcp.workspaces`: lee y escribe',
+    'sólo ahí, sin terminal, sin red, sin subagentes y sin guiones. Fuera de esas',
+    'carpetas la herramienta se para y lo dice. El detalle, en lib/lectura.js.',
+    '',
+  ].join('\n');
+}
+
+/** Leer la línea de órdenes. */
+function leerOrdenes(argv) {
+  const ordenes = { casa: undefined, motor: undefined, estado: false, ayuda: false, http: false, aceptoLecturaTotal: false, nuevaClave: false, puerto: PUERTO_HTTP_DEFECTO, tareasPorHora: TAREAS_POR_HORA_DEFECTO };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') ordenes.ayuda = true;
+    else if (a === '--status') ordenes.estado = true;
+    else if (a === '--http') ordenes.http = true;
+    else if (a === '--acepto-lectura-total') ordenes.aceptoLecturaTotal = true; // ya no hace falta; se acepta y se ignora
+    else if (a === '--nueva-clave') ordenes.nuevaClave = true;
+    else if (a === '--port' || a.startsWith('--port=')) {
+      const valor = a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i];
+      const n = Number(valor);
+      if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error('--port debe ser un puerto 1-65535');
+      ordenes.puerto = n;
+    } else if (a === '--tareas-por-hora' || a.startsWith('--tareas-por-hora=')) {
+      const valor = a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i];
+      const n = Number(valor);
+      if (!Number.isInteger(n) || n < 1) throw new Error('--tareas-por-hora debe ser un entero positivo');
+      ordenes.tareasPorHora = n;
+    } else if (a === '--home' || a.startsWith('--home=')) {
+      const valor = a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i];
+      if (!valor) throw new Error('--home necesita una ruta');
+      ordenes.casa = valor;
+    } else if (a === '--dsh' || a.startsWith('--dsh=')) {
+      const valor = a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i];
+      if (!valor) throw new Error('--dsh necesita una ruta');
+      ordenes.motor = valor;
+    } else throw new Error('no entiendo «' + a + '» (mira: ratacode-mcp --help)');
+  }
+  return ordenes;
+}
+
+/**
+ * La clave larga de la URL HTTP. Se guarda en la casa (nunca en el repositorio)
+ * con permisos de sólo-dueño; si ya existe se reutiliza, salvo que se pida una
+ * nueva (`--nueva-clave`, y `tunel.mjs` la estrena al abrir el túnel).
+ * @param {string} casa - la casa de RATACODE.
+ * @param {boolean} nueva - true para estrenar clave aunque ya haya una.
+ * @returns {string} la clave (hex).
+ */
+function claveHttp(casa, nueva = false) {
+  const ruta = join(casa, 'mcp', 'http-secret.txt');
+  if (nueva !== true) {
+    try {
+      const leida = readFileSync(ruta, 'utf8').trim();
+      if (/^[0-9a-f]{16,}$/.test(leida)) return leida;
+    } catch { /* la generamos */ }
+  }
+  const clave = randomBytes(32).toString('hex');
+  escribirSecreto(ruta, clave + '\n');
+  return clave;
+}
+
+/**
+ * Escribir un fichero de secretos con permisos de sólo-dueño. En POSIX el `mode`
+ * de `writeFileSync` no se aplica si el fichero YA existía, así que después se
+ * fuerza con `chmod` (en Windows el modo es casi decorativo, pero se pone igual).
+ */
+function escribirSecreto(ruta, texto) {
+  mkdirSync(dirname(ruta), { recursive: true });
+  writeFileSync(ruta, texto, { mode: 0o600 });
+  try { chmodSync(ruta, 0o600); } catch { /* Windows, o sin permisos: da igual */ }
+}
+
+async function main() {
+  const ordenes = leerOrdenes(process.argv.slice(2));
+  if (ordenes.ayuda) {
+    process.stdout.write(uso());
+    return;
+  }
+  const casa = resolverCasa(ordenes.casa);
+
+  if (ordenes.estado) {
+    process.stdout.write(JSON.stringify(estadoDeLaCasa(casa), null, 2) + '\n');
+    return;
+  }
+
+  // R25 · AQUÍ ESTABA LA PUERTA DE LA LECTURA. Ya no hay puerta que abrir: cada
+  // tarea va encerrada (parche del MCP + gancho `lib/lectura.js`), así que
+  // `--acepto-lectura-total` es un no-op que se acepta por no romper guiones.
+  if (ordenes.aceptoLecturaTotal) {
+    aviso('--acepto-lectura-total ya no hace falta: las tareas leen y escriben sólo dentro de las carpetas autorizadas');
+  }
+
+  const dshBin = binDelMotor(ordenes.motor);
+  const { servidor, tareas, fabricaServidor } = montarServidor({
+    casa,
+    dshBin,
+    cwdPorDefecto: process.cwd(),
+    tareasPorHora: ordenes.tareasPorHora,
+    // En modo HTTP el espacio se aprieta: hacen falta `mcp.workspaces` y no vale
+    // ni la raíz del disco ni la carpeta del usuario (mira `resolverEspacio`).
+    http: ordenes.http,
+  });
+
+  // stdio: siempre (es el transporte de siempre).
+  const transporte = new StdioServerTransport();
+  await servidor.connect(transporte);
+
+  aviso('en marcha · casa: ' + casa);
+  aviso('en marcha · motor: ' + dshBin);
+  aviso('en marcha · herramientas: list_providers, list_models, run_task, get_task_status, get_task_result, cancel_task, ratacode_status');
+  aviso('en marcha · tope de tareas: ' + ordenes.tareasPorHora + '/h');
+  tareas.resumir();
+
+  // HTTP: además del stdio, si se pidió.
+  if (ordenes.http) {
+    const rutaClave = join(casa, 'mcp', 'http-secret.txt');
+    const rutaUrl = join(casa, 'mcp', 'http-url.txt');
+    const clave = claveHttp(casa, ordenes.nuevaClave);
+    /** La URL con la clave, al fichero. Se reescribe si la clave rota. */
+    const guardarUrl = (c) => {
+      try { escribirSecreto(rutaUrl, 'http://127.0.0.1:' + ordenes.puerto + '/mcp/' + c + '\n'); }
+      catch { /* no es crítico */ }
+    };
+    const http = await iniciarServidorHttp({
+      fabricaServidor,
+      puerto: ordenes.puerto,
+      clave,
+      rutaClave,
+      alRotar: guardarUrl,
+      host: '127.0.0.1',
+    });
+    // La clave NO se escribe en stderr: los clientes MCP guardan ese stderr en
+    // sus registros. Se dice dónde está y ya.
+    aviso('en marcha · HTTP en http://127.0.0.1:' + ordenes.puerto + '/mcp/<oculta>');
+    aviso('en marcha · la URL COMPLETA (con la clave) está en ' + rutaUrl);
+    guardarUrl(http.claveActual());
+    http.servidor.on('clientError', () => {});
+  }
+
+  // Al irnos, no dejamos tareas huérfanas trabajando por detrás.
+  const recoger = () => {
+    for (const recibo of tareas.listar()) {
+      if (recibo.estado === 'queued' || recibo.estado === 'running') {
+        try { tareas.cancelar(recibo.task_id); } catch { /* ya no está */ }
+      }
+    }
+  };
+  process.on('SIGINT', () => { recoger(); process.exit(130); });
+  process.on('SIGTERM', () => { recoger(); process.exit(143); });
+  process.on('exit', recoger);
+}
+
+try {
+  await main();
+} catch (e) {
+  fallo('no pude arrancar', e);
+  process.exitCode = 1;
+}

package/mcp/lib/actividad.js

@@ -0,0 +1,49 @@
+/**
+ * actividad — el cuaderno de lo que pasa por el MCP.
+ *
+ * Una línea JSON por tarea, en `<casa>/mcp/actividad.jsonl`. Es lo que luego
+ * enseña el panel (hora, cliente, modelo, proveedor, tarea, duración, tokens,
+ * coste, estado) y es también lo que permite mirar atrás sin pantalla.
+ *
+ * Regla de la casa: aquí se escribe el NOMBRE de la credencial si hace falta,
+ * nunca su valor. Y el prompt se guarda recortado, para que un encargo enorme
+ * no infle el cuaderno.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Cuántos caracteres del encargo se guardan en el cuaderno. */
+const TOPE_TAREA = 120;
+
+/**
+ * Apuntar una tarea terminada.
+ * @param {string} casa - la casa de RATACODE.
+ * @param {object} fila - los campos de la línea.
+ * @returns {void}
+ */
+export function anotar(casa, fila) {
+  const carpeta = join(casa, 'mcp');
+  mkdirSync(carpeta, { recursive: true });
+  const linea = {
+    hora: new Date().toISOString(),
+    cliente: fila.cliente ?? 'MCP',
+    modelo: fila.modelo ?? null,
+    proveedor: fila.proveedor ?? null,
+    tarea: recortar(fila.tarea),
+    duracion_ms: fila.duracion_ms ?? null,
+    tokens_input: fila.tokens_input ?? null,
+    tokens_output: fila.tokens_output ?? null,
+    coste: fila.coste ?? null,
+    estado: fila.estado ?? null,
+    espacio: fila.espacio ?? null,
+    task_id: fila.task_id ?? null,
+  };
+  appendFileSync(join(carpeta, 'actividad.jsonl'), JSON.stringify(linea) + '\n');
+}
+
+/** Recortar un texto a una línea corta. */
+function recortar(texto) {
+  if (typeof texto !== 'string') return null;
+  const plano = texto.replace(/\s+/g, ' ').trim();
+  return plano.length <= TOPE_TAREA ? plano : plano.slice(0, TOPE_TAREA - 1) + '…';
+}

package/mcp/lib/casa.js

@@ -0,0 +1,126 @@
+/**
+ * casa — dónde vive RATACODE y dónde está su motor.
+ *
+ * Se resuelve EXACTAMENTE igual que en `bin/ratacode.js`, para que el MCP mire
+ * la misma casa (mismos proveedores, mismos modelos, mismas claves) que la web.
+ * Si aquí se resolviera distinto, tendríamos dos RATACODE y eso es justo lo que
+ * no queremos.
+ *
+ *   casa  = --home  >  $RATACODE_HOME  >  %USERPROFILE%\.ratacode
+ *   motor = --dsh   >  @deepseek-ai/dsh del paquete (como bin/ratacode.js)
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import yaml from 'js-yaml';
+
+/**
+ * La casa de RATACODE.
+ * @param {string|undefined} indicada - valor de `--home`, si lo hay.
+ * @returns {string} ruta absoluta.
+ */
+export function resolverCasa(indicada) {
+  return resolve(indicada ?? process.env.RATACODE_HOME ?? join(homedir(), '.ratacode'));
+}
+
+/**
+ * El binario del motor DSH. Mismo criterio que `binDelMotor()` de ratacode.js:
+ * se pregunta al paquete instalado, no se adivina una ruta.
+ * @param {string|undefined} indicada - valor de `--dsh`, si lo hay.
+ * @returns {string} ruta absoluta a `lib/bin.js`.
+ */
+export function binDelMotor(indicada) {
+  if (indicada !== undefined && indicada !== null && indicada !== '') {
+    const ruta = resolve(indicada);
+    if (!existsSync(ruta)) throw new Error('no encuentro el motor en ' + ruta);
+    return ruta;
+  }
+  const requerir = createRequire(import.meta.url);
+  const manifiesto = requerir.resolve('@deepseek-ai/dsh/package.json');
+  const pkg = JSON.parse(readFileSync(manifiesto, 'utf8'));
+  const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.dsh;
+  if (rel === undefined || rel === null) throw new Error('el motor no declara su binario (¿instalación a medias?)');
+  const bin = join(dirname(manifiesto), rel);
+  if (!existsSync(bin)) throw new Error('no encuentro el motor en ' + bin);
+  return bin;
+}
+
+/**
+ * Los ajustes de la casa (`settings.yaml`). Es el MISMO documento que lee el
+ * core (dsh-settings-file), así que leerlo aquí no duplica lógica: es leer la
+ * configuración del usuario, que es exactamente lo que hace la web.
+ * @param {string} casa - la casa de RATACODE.
+ * @returns {{documento: object, ruta: string, error: string|null}}
+ */
+export function leerAjustes(casa) {
+  const ruta = join(casa, 'settings.yaml');
+  if (!existsSync(ruta)) return { documento: {}, ruta, error: null };
+  try {
+    const cargado = yaml.load(readFileSync(ruta, 'utf8'));
+    if (cargado === null || cargado === undefined) return { documento: {}, ruta, error: null };
+    if (typeof cargado !== 'object' || Array.isArray(cargado)) {
+      return { documento: {}, ruta, error: 'settings.yaml no es un documento de ajustes (se esperaba un mapa)' };
+    }
+    return { documento: cargado, ruta, error: null };
+  } catch (e) {
+    return { documento: {}, ruta, error: 'no pude leer settings.yaml: ' + (e instanceof Error ? e.message : String(e)) };
+  }
+}
+
+/** Un texto no vacío, o undefined. */
+function texto(valor) {
+  return typeof valor === 'string' && valor.trim() !== '' ? valor : undefined;
+}
+
+/**
+ * La sección `mcp:` de los ajustes, con sus valores por defecto.
+ * Todo lo que limita el daño se lee de aquí, para que el humano lo pueda
+ * cambiar sin tocar código.
+ * @param {string} casa - la casa de RATACODE.
+ * @returns {{workspaces: string[], workspacePorDefecto: string|undefined, permitirPeligroso: boolean, precios: object, timeoutPorDefectoMs: number, timeoutMaximoMs: number, tareasALaVez: number, promptMaxCaracteres: number, avisos: string[]}}
+ */
+export function ajustesMcp(casa) {
+  const { documento, error } = leerAjustes(casa);
+  const avisos = error === null ? [] : [error];
+  const bruto = documento.mcp;
+  const seccion = bruto !== null && typeof bruto === 'object' && !Array.isArray(bruto) ? bruto : {};
+  const listaBruta = Array.isArray(seccion.workspaces) ? seccion.workspaces : [];
+  const workspaces = [];
+  for (const entrada of listaBruta) {
+    const ruta = texto(entrada);
+    if (ruta === undefined) {
+      avisos.push('mcp.workspaces tiene una entrada que no es una ruta de texto; la salto');
+      continue;
+    }
+    workspaces.push(resolve(ruta));
+  }
+  const porDefecto = texto(seccion.workspace_por_defecto);
+  const precios = seccion.precios !== null && typeof seccion.precios === 'object' && !Array.isArray(seccion.precios) ? seccion.precios : {};
+  return {
+    workspaces,
+    workspacePorDefecto: porDefecto === undefined ? undefined : resolve(porDefecto),
+    permitirPeligroso: seccion.permitir_peligroso === true,
+    precios,
+    timeoutPorDefectoMs: enteroPositivo(seccion.timeout_por_defecto_ms, TIMEOUT_POR_DEFECTO_MS),
+    timeoutMaximoMs: enteroPositivo(seccion.timeout_maximo_ms, TIMEOUT_MAXIMO_MS),
+    tareasALaVez: enteroPositivo(seccion.tareas_a_la_vez, TAREAS_A_LA_VEZ),
+    promptMaxCaracteres: enteroPositivo(seccion.prompt_max_caracteres, PROMPT_MAX_CARACTERES),
+    avisos,
+  };
+}
+
+/** Los topes de fábrica del MCP. Se pueden cambiar en `mcp:` de settings.yaml. */
+/** Media hora por tarea si el cliente no dice otra cosa. */
+export const TIMEOUT_POR_DEFECTO_MS = 1_800_000;
+/** Y una hora como techo, aunque el cliente pida más. */
+export const TIMEOUT_MAXIMO_MS = 3_600_000;
+/** Cuántas tareas pueden estar en marcha a la vez. */
+export const TAREAS_A_LA_VEZ = 3;
+/** Tope del encargo (caracteres). Un prompt de verdad no llega ni de lejos. */
+export const PROMPT_MAX_CARACTERES = 100_000;
+
+/** Un entero positivo de los ajustes, o el valor de fábrica. */
+function enteroPositivo(valor, porDefecto) {
+  return typeof valor === 'number' && Number.isInteger(valor) && valor > 0 ? valor : porDefecto;
+}

package/mcp/lib/claves.js

@@ -0,0 +1,148 @@
+/**
+ * claves — ¿está la credencial? Sólo sí o no, y sin leer nunca el valor.
+ *
+ * ── REGLA DE LA CASA (R22, 28-sep) ──────────────────────────────────────────
+ * La ÚNICA fuente de claves de RATACODE es el almacén de la casa
+ * (`<casa>\.credentials.yaml`), que es lo que escribe Ajustes › Models. Este
+ * servidor NO mira el entorno del cliente MCP —daba igual que la clave fuera
+ * vieja o estuviera rotada, el motor la daba por puesta— y tampoco lee ficheros
+ * de claves por su cuenta.
+ *
+ * La pregunta la contesta el MOTOR, con su propio código: se carga su
+ * `LocalCredentialProvider` (el mismo que resuelve las claves cuando corre una
+ * tarea) y se le pregunta `describe(<variable>)` → `configured: sí/no`. De ahí
+ * no sale ningún valor: sólo si está o no está.
+ *
+ * Y el hijo del motor que ejecuta cada tarea arranca SIN esas variables (ver
+ * {@link variablesDeClaves} y `nucleo.js`), para que resuelva las de la casa.
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** Las variables de claves que RATACODE conoce de fábrica. */
+export const VARIABLES_CONOCIDAS = [
+  'B_AI_API_KEY', 'BAI_API_KEY', 'OPENROUTER_API_KEY', 'DEEPSEEK_API_KEY', 'GROQ_API_KEY',
+  'GEMINI_API_KEY', 'NVIDIA_API_KEY', 'SAMBANOVA_API_KEY', 'CLOUDFLARE_API_KEY', 'CLOUDFLARE_API_TOKEN',
+];
+
+/** Cómo detener el hijo: si el paquete del motor no se puede cargar, se dice. */
+let avisoDelMotor = null;
+
+/**
+ * La ruta del `package.json` del motor instalado (la misma que usa `casa.js`).
+ * @returns {string} ruta absoluta.
+ */
+function manifiestoDelMotor() {
+  const requerir = createRequire(import.meta.url);
+  return requerir.resolve('@deepseek-ai/dsh/package.json');
+}
+
+/** El `LocalCredentialProvider` del motor, cargado de SU paquete. Se carga una vez. */
+let proveedorPrometido = null;
+function proveedorDelMotor() {
+  if (proveedorPrometido === null) {
+    proveedorPrometido = (async () => {
+      const manifiesto = manifiestoDelMotor();
+      const requerir = createRequire(manifiesto);
+      const ruta = requerir.resolve('@deepseek-ai/dsh-credentials-local');
+      const modulo = await import(pathToFileURL(ruta).href);
+      return modulo.LocalCredentialProvider;
+    })();
+  }
+  return proveedorPrometido;
+}
+
+/**
+ * Un entorno de arranque VACÍO: el almacén del motor mira primero las variables
+ * del proceso que lo arranca, y aquí lo que queremos es justo lo contrario —
+ * que sólo cuente lo guardado en la casa (Ajustes › Models).
+ */
+const SIN_ENTORNO = {
+  get: () => undefined,
+  getFrom: () => undefined,
+};
+
+/** Lo mínimo que toca el constructor del servicio del motor (no se registra en ningún sitio). */
+const CONTEXTO_SUELTO = {
+  get: (clave) => (clave === 'launchEnvironment' ? SIN_ENTORNO : undefined),
+  reflect: { provide() { /* un servicio suelto: no se registra */ } },
+  logger: { info() {}, warn() {}, error() {} },
+  effect: () => {},
+};
+
+/**
+ * ¿Está esta credencial guardada en la casa? Se lo pregunta al almacén del
+ * motor, con su `describe`: nunca se lee el fichero a mano y nunca sale un valor.
+ * @param {string} casa - la casa de RATACODE.
+ * @param {string} nombre - nombre de la variable (p. ej. `B_AI_API_KEY`).
+ * @returns {Promise<{configurada: boolean, motivo: string|null}>} `motivo` sólo
+ *   cuando NO se ha podido preguntar (y entonces no se puede afirmar nada).
+ */
+export async function describeEnLaCasa(casa, nombre) {
+  if (typeof nombre !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(nombre)) {
+    return { configurada: false, motivo: '«' + String(nombre) + '» no es un nombre de variable' };
+  }
+  try {
+    const Proveedor = await proveedorDelMotor();
+    const proveedor = new Proveedor(CONTEXTO_SUELTO, {
+      path: join(casa, '.credentials.yaml'),
+      watch: false,
+    });
+    await proveedor.loadInitial();
+    const dicho = await proveedor.describe(nombre);
+    return { configurada: dicho?.configured === true, motivo: null };
+  } catch (e) {
+    avisoDelMotor = e instanceof Error ? e.message : String(e);
+    return { configurada: false, motivo: 'no pude preguntar al almacén de la casa: ' + avisoDelMotor };
+  }
+}
+
+/**
+ * El mensaje exacto cuando falta una clave, con el nombre que ve el humano.
+ * @param {string} nombreVisible - el nombre del proveedor («B.AI») o, si no se
+ *   sabe, el de la variable.
+ * @returns {string} p. ej. `Falta la clave de B.AI. Pégala en RATACODE › Ajustes › Models.`
+ */
+export function faltaLaClave(nombreVisible) {
+  return 'Falta la clave de ' + nombreVisible + '. Pégala en RATACODE › Ajustes › Models.';
+}
+
+/**
+ * Las variables de claves que declara ESTA casa (más las conocidas de fábrica):
+ * el hijo del motor que ejecuta una tarea arranca sin ninguna de ellas, para
+ * que resuelva las claves del almacén de la casa y no las del entorno.
+ * @param {string} casa - la casa de RATACODE.
+ * @returns {string[]} nombres de variable (nunca un valor).
+ */
+export function variablesDeClaves(casa) {
+  const nombres = new Set(VARIABLES_CONOCIDAS);
+  try {
+    const texto = readFileSync(join(casa, 'settings.yaml'), 'utf8');
+    for (const linea of texto.split('\n')) {
+      const m = /^\s*apiKeyEnv\s*:\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?\s*$/.exec(linea);
+      if (m !== null) nombres.add(m[1]);
+    }
+  } catch { /* sin settings.yaml: quedan las conocidas */ }
+  return [...nombres];
+}
+
+/**
+ * El entorno de un hijo del motor SIN las variables de claves (se borran por
+ * nombre, en mayúsculas: en Windows no distinguen mayúsculas de minúsculas).
+ * @param {string} casa - la casa de RATACODE.
+ * @param {object} base - el entorno de partida.
+ * @returns {object} una copia sin esas variables.
+ */
+export function entornoDelMotorSinClaves(casa, base) {
+  const fuera = new Set(variablesDeClaves(casa).map((n) => n.toUpperCase()));
+  const entorno = { ...base };
+  for (const nombre of Object.keys(entorno)) {
+    if (fuera.has(nombre.toUpperCase())) delete entorno[nombre];
+  }
+  return entorno;
+}
+
+/** La ruta del manifiesto del motor (para mensajes y para las pruebas). */
+export { manifiestoDelMotor };

package/mcp/lib/espacios.js

@@ -0,0 +1,117 @@
+/**
+ * espacios — que una tarea del MCP SALGA en la barra lateral del panel.
+ *
+ * ── EL PROBLEMA (medido en R12) ─────────────────────────────────────────────
+ * Una tarea del MCP SÍ crea su sesión de motor
+ * (`<casa>\sessions\<espacio>\mcp-<task>\session.v3.jsonl.zstd`, con su
+ * conversación dentro), pero en el panel NO salía: la barra lateral lista las
+ * sesiones que el REGISTRO DE ESPACIOS tiene apuntadas, y nadie apuntaba las del
+ * MCP. El MCP era una caja negra.
+ *
+ * ── LA VÍA (la que usa el propio motor) ─────────────────────────────────────
+ * El registro es `<casa>\storages\workspace.json`, el documento del dominio
+ * `workspace` versión 2 de `dsh-workspace` (`lib/index.js`: spec con
+ * `global.workspaceIds` —el orden de la barra— y la tabla `workspaces` con
+ * `{path, title, sessionIds, createdAt, updatedAt}`; `path` es el `fs.realpath`
+ * del sitio y `sessionIds` es la cuenta de propiedad EN ORDEN DE PANTALLA).
+ * `bin/ratacode.js` ya escribe este mismo fichero para registrar el espacio;
+ * aquí sólo se añade la sesión a la cuenta del espacio que le toca.
+ *
+ * La escritura es atómica (fichero temporal + rename) y NUNCA pisa lo que haya:
+ * si el documento no es el que sabemos leer, se deja como está y se dice por qué.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { basename, dirname, join, resolve } from 'node:path';
+
+/** La ruta canónica de una carpeta (la única canon de identidad del registro). */
+function canonica(ruta) {
+  try {
+    return realpathSync(ruta);
+  } catch {
+    return resolve(ruta).replace(/[\\/]+$/, '');
+  }
+}
+
+/** El fichero del registro de espacios de una casa. */
+export function rutaDelRegistro(casa) {
+  return join(casa, 'storages', 'workspace.json');
+}
+
+/**
+ * Apuntar la sesión de una tarea en el espacio de su carpeta de trabajo.
+ *
+ * @param {string} casa - la casa de RATACODE.
+ * @param {string} espacio - la carpeta de trabajo de la tarea (`cwd` del motor).
+ * @param {string} sessionId - el id de la sesión del motor (aquí, `mcp-<task>`).
+ * @returns {{apuntada: boolean, nueva?: boolean, espacioId?: string, motivo?: string}}
+ */
+export function apuntarSesionEnEspacio(casa, espacio, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId.trim() === '') {
+    return { apuntada: false, motivo: 'sin id de sesión que apuntar' };
+  }
+  if (typeof espacio !== 'string' || espacio.trim() === '') {
+    return { apuntada: false, motivo: 'la tarea no trae carpeta de trabajo' };
+  }
+  const ruta = rutaDelRegistro(casa);
+  let doc = null;
+  if (existsSync(ruta)) {
+    try {
+      doc = JSON.parse(readFileSync(ruta, 'utf8'));
+    } catch {
+      doc = null;
+    }
+  }
+  if (doc !== null && doc?.unit?.name !== 'workspace') doc = null;
+  if (doc !== null && doc.unit.version !== 2) {
+    return {
+      apuntada: false,
+      motivo: 'el registro de espacios de esta casa es versión ' + doc.unit.version
+        + ', y yo sé escribir la 2: no lo toco',
+    };
+  }
+  if (doc === null) {
+    doc = {
+      unit: { name: 'workspace', version: 2 },
+      global: { initialized: true, workspaceIds: [], archivedSessionIds: [] },
+      tables: { workspaces: {} },
+    };
+  }
+  doc.global = doc.global ?? {};
+  if (!Array.isArray(doc.global.workspaceIds)) doc.global.workspaceIds = [];
+  if (!Array.isArray(doc.global.archivedSessionIds)) doc.global.archivedSessionIds = [];
+  doc.tables = doc.tables ?? {};
+  doc.tables.workspaces = doc.tables.workspaces ?? {};
+
+  const canon = canonica(espacio);
+  let espacioId = Object.keys(doc.tables.workspaces)
+    .find((clave) => doc.tables.workspaces[clave]?.path === canon);
+  const ahora = new Date().toISOString();
+  let nuevoEspacio = false;
+  if (espacioId === undefined) {
+    espacioId = randomUUID();
+    doc.tables.workspaces[espacioId] = {
+      path: canon,
+      title: basename(canon) || canon,
+      sessionIds: [],
+      createdAt: ahora,
+      updatedAt: ahora,
+    };
+    doc.global.workspaceIds = [espacioId, ...doc.global.workspaceIds];
+    doc.global.initialized = true;
+    nuevoEspacio = true;
+  }
+  const registro = doc.tables.workspaces[espacioId];
+  if (!Array.isArray(registro.sessionIds)) registro.sessionIds = [];
+  if (registro.sessionIds.includes(sessionId)) {
+    return { apuntada: true, nueva: false, espacioId, nuevoEspacio };
+  }
+  registro.sessionIds = [sessionId, ...registro.sessionIds];
+  registro.updatedAt = ahora;
+
+  mkdirSync(dirname(ruta), { recursive: true });
+  const temporal = ruta + '.' + process.pid + '.tmp';
+  writeFileSync(temporal, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
+  renameSync(temporal, ruta);
+  return { apuntada: true, nueva: true, espacioId, nuevoEspacio };
+}