@7ots/cli 0.1.0

package/server/tts.mjs

@@ -0,0 +1,186 @@
+/**
+ * Texto → voz en el servidor (las claves nunca llegan al navegador).
+ * 7ots no aloja audio: solo se integra con tus propias cuentas, con las claves del entorno del proxy.
+ *
+ * TTS_PROVIDER (vacío = el primero configurado, en este orden):
+ *   apuchat     → audio de apuchat (voice.apuchat.com, POST /speak).
+ *                 APUCHAT_VOICE_TOKEN (cabecera X-Voice-Test-Token), APUCHAT_VOICE_URL (https://voice.apuchat.com),
+ *                 APUCHAT_VOICE_ID (voz: narrator, es_locutor, adam, eve… o un id crudo), APUCHAT_VOICE_PROVIDER
+ *                 (fish | elevenlabs | xai; vacío = el servidor elige y hace respaldo)
+ *   elevenlabs  → ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID, ELEVENLABS_MODEL (eleven_multilingual_v2)
+ *   grok        → xAI (POST https://api.x.ai/v1/tts). XAI_API_KEY, XAI_TTS_VOICE (eve, ara, leo, rex, sal o voz propia)
+ *   fish        → Fish Audio (POST https://api.fish.audio/v1/tts). FISH_API_KEY, FISH_VOICE_ID (reference_id;
+ *                 vacío = voz propia del modelo), FISH_MODEL (vacío = s2.1-pro; va en la cabecera `model`)
+ *   openai      → (compatibilidad) OPENAI_API_KEY, OPENAI_TTS_MODEL (gpt-4o-mini-tts), OPENAI_TTS_VOICE (alloy)
+ *   none        → 501: el widget usa la voz del navegador (speechSynthesis)
+ *
+ * La voz de la identidad del agente (server/identity.mjs → voice) manda sobre las variables:
+ *   provider  'apuchat' | 'elevenlabs' | 'grok' | 'fish' | 'openai' fuerza ese proveedor
+ *             ('auto' = el de TTS_PROVIDER; 'browser' = 501)
+ *   voiceId   voz de apuchat, id de voz de ElevenLabs, voz de xAI, reference_id de Fish o voz de OpenAI
+ *   model     modelo de TTS (ElevenLabs, Fish, OpenAI y apuchat; xAI tiene un único modelo)
+ *   style     instrucciones de estilo (solo gpt-4o-mini-tts): "cálida, pausada, acento neutro"
+ *   lang      idioma (xAI lo exige: es-ES, es-MX, pt-BR, en…; si no lo admite, 'auto')
+ *   rate      velocidad (OpenAI: 0,25–4; ElevenLabs: 0,7–1,2; xAI: 0,7–1,5; Fish: 0,5–2)
+ *
+ * Devuelve { audio: Buffer, contentType } o lanza un Error con .status.
+ */
+
+import { OPENAI_VOICES } from './identity.mjs';
+import { i18nError } from './i18n.mjs';
+
+const PROVIDERS = ['apuchat', 'elevenlabs', 'grok', 'fish', 'openai'];
+const TIMEOUT_MS = 20_000;
+
+/** @param {Record<string,string|undefined>} [env]  configuración (defecto: process.env; en la plataforma, la del ots) */
+export function ttsProvider(env = process.env) {
+  if (env.TTS_PROVIDER) return env.TTS_PROVIDER.toLowerCase();
+  if (env.APUCHAT_VOICE_TOKEN) return 'apuchat';
+  if (env.ELEVENLABS_API_KEY) return 'elevenlabs';
+  if (env.XAI_API_KEY) return 'grok';
+  if (env.FISH_API_KEY) return 'fish';
+  if (env.OPENAI_API_KEY) return 'openai';
+  return 'none';
+}
+
+export async function synthesize({ text, voice = {}, env = process.env }) {
+  const provider = PROVIDERS.includes(voice.provider) ? voice.provider : voice.provider === 'browser' ? 'none' : ttsProvider(env);
+  const input = String(text || '').slice(0, 1500);
+  if (!input) throw i18nError(400, 'server.tts.empty');
+
+  if (provider === 'apuchat') {
+    // Contrato real de voice.apuchat.com: POST /speak { text, voice?, provider?, model?, lang?, summarize? } → mp3.
+    // Sin token el servicio responde 402 (pago x402 por llamada), que el proxy no hace.
+    if (!env.APUCHAT_VOICE_TOKEN) throw i18nError(501, 'server.tts.noApuchatToken');
+    const base = (env.APUCHAT_VOICE_URL || 'https://voice.apuchat.com').replace(/\/+$/, '');
+    const engine = (env.APUCHAT_VOICE_PROVIDER || '').toLowerCase();
+    const res = await post(`${base}/speak`, {
+      headers: { 'X-Voice-Test-Token': env.APUCHAT_VOICE_TOKEN, 'Content-Type': 'application/json', Accept: 'audio/mpeg' },
+      body: {
+        text: input,
+        summarize: false, // decir el texto tal cual, sin resumirlo
+        ...(voice.voiceId || env.APUCHAT_VOICE_ID ? { voice: voice.voiceId || env.APUCHAT_VOICE_ID } : {}),
+        ...(['fish', 'elevenlabs', 'xai'].includes(engine) ? { provider: engine } : {}),
+        ...(voice.model ? { model: voice.model } : {}),
+        ...(voice.lang ? { lang: voice.lang } : {}),
+      },
+    }, 'apuchat');
+    return { audio: Buffer.from(await res.arrayBuffer()), contentType: res.headers.get('content-type') || 'audio/mpeg' };
+  }
+
+  if (provider === 'elevenlabs') {
+    if (!env.ELEVENLABS_API_KEY) throw i18nError(501, 'server.tts.noKey', { provider: 'ElevenLabs', key: 'ELEVENLABS_API_KEY' });
+    const voiceId = voice.voiceId || env.ELEVENLABS_VOICE_ID;
+    if (!voiceId) throw i18nError(501, 'server.tts.noElevenVoice');
+    const res = await post(`https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voiceId)}?output_format=mp3_44100_128`, {
+      headers: { 'xi-api-key': env.ELEVENLABS_API_KEY, 'Content-Type': 'application/json', Accept: 'audio/mpeg' },
+      body: {
+        text: input,
+        model_id: voice.model || env.ELEVENLABS_MODEL || 'eleven_multilingual_v2',
+        ...(voice.rate && voice.rate !== 1 ? { voice_settings: { speed: clamp(voice.rate, 0.7, 1.2) } } : {}),
+      },
+    }, 'ElevenLabs');
+    return { audio: Buffer.from(await res.arrayBuffer()), contentType: 'audio/mpeg' };
+  }
+
+  if (provider === 'grok') {
+    // xAI TTS: POST /v1/tts → bytes de audio (JSON en base64 solo con with_timestamps, que no usamos).
+    if (!env.XAI_API_KEY) throw i18nError(501, 'server.tts.noKey', { provider: 'xAI (Grok)', key: 'XAI_API_KEY' });
+    const res = await post('https://api.x.ai/v1/tts', {
+      headers: { Authorization: `Bearer ${env.XAI_API_KEY}`, 'Content-Type': 'application/json' },
+      body: {
+        text: input,
+        voice_id: String(voice.voiceId || env.XAI_TTS_VOICE || 'eve').toLowerCase(),
+        language: xaiLanguage(voice.lang),
+        output_format: { codec: 'mp3', sample_rate: 24000, bit_rate: 128000 },
+        ...(voice.rate && voice.rate !== 1 ? { speed: clamp(voice.rate, 0.7, 1.5) } : {}),
+      },
+    }, 'xAI');
+    return { audio: Buffer.from(await res.arrayBuffer()), contentType: 'audio/mpeg' };
+  }
+
+  if (provider === 'fish') {
+    if (!env.FISH_API_KEY) throw i18nError(501, 'server.tts.noKey', { provider: 'Fish Audio', key: 'FISH_API_KEY' });
+    const referenceId = voice.voiceId || env.FISH_VOICE_ID; // vacío = voz propia del modelo
+    const res = await post('https://api.fish.audio/v1/tts', {
+      headers: {
+        Authorization: `Bearer ${env.FISH_API_KEY}`,
+        'Content-Type': 'application/json',
+        // el modelo va en la cabecera, no en el cuerpo; sin ella Fish usa su modelo por defecto (s2.1-pro)
+        ...(voice.model || env.FISH_MODEL ? { model: voice.model || env.FISH_MODEL } : {}),
+      },
+      body: {
+        text: input,
+        format: 'mp3',
+        ...(referenceId ? { reference_id: referenceId } : {}),
+        ...(voice.rate && voice.rate !== 1 ? { prosody: { speed: clamp(voice.rate, 0.5, 2) } } : {}),
+      },
+    }, 'Fish Audio');
+    return { audio: Buffer.from(await res.arrayBuffer()), contentType: 'audio/mpeg' };
+  }
+
+  if (provider === 'openai') {
+    if (!env.OPENAI_API_KEY) throw i18nError(501, 'server.tts.noKey', { provider: 'OpenAI', key: 'OPENAI_API_KEY' });
+    const openai = await openaiClient(env.OPENAI_API_KEY); // TTS siempre contra OpenAI (no LLM_BASE_URL)
+    const model = voice.model || env.OPENAI_TTS_MODEL || 'gpt-4o-mini-tts';
+    const res = await openai.audio.speech.create({
+      model,
+      voice: (OPENAI_VOICES.includes(voice.voiceId) && voice.voiceId) || env.OPENAI_TTS_VOICE || 'alloy', // un id de otro proveedor aquí daría 400
+      input,
+      response_format: 'mp3',
+      ...(voice.style && /gpt-4o/.test(model) ? { instructions: voice.style } : {}),
+      ...(voice.rate && voice.rate !== 1 ? { speed: clamp(voice.rate, 0.25, 4) } : {}),
+    });
+    return { audio: Buffer.from(await res.arrayBuffer()), contentType: 'audio/mpeg' };
+  }
+
+  throw i18nError(501, 'server.tts.notConfigured');
+}
+
+const openaiClients = new Map();
+async function openaiClient(apiKey) {
+  if (!openaiClients.has(apiKey)) {
+    const { default: OpenAI } = await import('openai');
+    if (openaiClients.size > 200) openaiClients.clear();
+    openaiClients.set(apiKey, new OpenAI({ apiKey }));
+  }
+  return openaiClients.get(apiKey);
+}
+
+/** POST JSON con tiempo límite. Si el proveedor falla, 502 sin reenviar su respuesta (podría llevar datos de la cuenta). */
+async function post(url, { headers, body }, name) {
+  let res;
+  try {
+    res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(TIMEOUT_MS) });
+  } catch {
+    throw httpError(502, `${name} unreachable`);
+  }
+  if (!res.ok) {
+    await res.text().catch(() => ''); // libera el socket
+    throw httpError(502, `${name} ${res.status}`);
+  }
+  return res;
+}
+
+// Idiomas que admite xAI TTS (docs.x.ai); el resto se deja en 'auto'.
+const XAI_LANGS = ['en', 'ar-EG', 'ar-SA', 'ar-AE', 'bn', 'zh', 'fr', 'de', 'hi', 'id', 'it', 'ja', 'ko', 'pt-BR', 'pt-PT', 'ru', 'es-MX', 'es-ES', 'tr', 'vi'];
+
+function xaiLanguage(lang) {
+  const l = String(lang || '').toLowerCase();
+  if (!l) return 'auto';
+  const exact = XAI_LANGS.find((x) => x.toLowerCase() === l);
+  if (exact) return exact;
+  const base = l.split('-')[0];
+  if (XAI_LANGS.includes(base)) return base; // en-US → en, fr-FR → fr
+  if (base === 'es') return 'es-ES';
+  if (base === 'pt') return 'pt-BR';
+  return 'auto';
+}
+
+function clamp(n, min, max) {
+  return Math.min(max, Math.max(min, n));
+}
+
+function httpError(status, message) {
+  return Object.assign(new Error(message), { status });
+}

package/skills/7ots/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: 7ots
+description: Create a reproducible 7ots identity (face, personality, voice), install the 7ots web agent in a project, wake up the 7ots desktop pet (a tamagotchi that comments on the terminal and the coding agent) or join an apuchat meet video call with that identity. Use when the user mentions 7ots, an ot, a random agent identity, a desktop/virtual pet for the terminal, or joining meet.apuchat.com as an agent.
+---
+
+# 7ots
+
+Everything goes through the `7ots` CLI (`npx -y @7ots/cli …`, Node 20+). `npx -y @7ots/cli help` lists the commands;
+`npx -y @7ots/cli prompt <topic>` prints these recipes. Full docs for agents: https://7ots.com/llms.txt
+
+## Create a random 7ots identity
+When the user says "use 7ots, create a random identity" (or similar):
+1. Run `npx -y @7ots/cli new` (add `--name <Name>` if they gave a name, `--lang en|es|pt` for the language,
+   `--seed <seed>` to reproduce a specific ot, `--global` for one shared by every project).
+2. It writes `.7ots/identity.json` and prints the ot's name, role, personality, voice and its seed.
+   The seed reproduces exactly the same ot anywhere (web, CLI, pet, meet): tell the user the seed.
+3. Show the user who their ot is. If they don't like it, run `npx -y @7ots/cli new --force` for another one.
+Never invent identity fields by hand: the CLI validates them.
+
+## Install the identity in this project
+When the user says "install it here":
+1. Make sure there is an identity (`npx -y @7ots/cli show`; if none, create one as above).
+2. Run `npx -y @7ots/cli install`. It detects the project:
+   - plain HTML site → inserts the 7ots widget before </body> (between <!-- 7ots --> markers, idempotent);
+   - other projects → prints the snippet: put it in the root layout/template, before </body>;
+   - `--target self` → prepares the identity for the user's own 7ots server (IDENTITY_FILE=… npx -p 7ots 7ots-server);
+   - it also prints a 7ots.com link that hosts this same identity (no server needed).
+3. The widget needs an AI endpoint: a 7ots proxy (/api/agent) or the ot hosted on 7ots.com. Tell the user which.
+
+## Wake up the desktop pet (tamagotchi)
+The ot can live on the user's computer as a virtual pet that watches the terminal and the coding agent,
+comments on what happens and has needs (food, energy, fun, levels).
+1. If the user hasn't configured it, suggest `npx -y @7ots/cli setup` (an interactive wizard: where the ot lives,
+   which brain — their own AI CLI, an API key, 7ots or Orquesta Batuta —, voice, pet mode, chattiness, hooks).
+   It is interactive: ask the user to run it themselves with `! npx -y @7ots/cli setup` in Claude Code.
+2. Pick the mode, or ask the user if it's not obvious:
+   - desktop: `npx -y @7ots/cli pet --mode desktop --detach` (a small always-on-top window that walks along the screen; downloads Electron once)
+   - browser: `npx -y @7ots/cli pet --mode browser --detach`
+   - terminal: `npx -y @7ots/cli pet --mode terminal` (needs its own terminal: ask the user to run it)
+   Always use --detach from an agent so the command returns.
+3. To let it react to your work: `npx -y @7ots/cli hooks install --claude` (Claude Code hooks in this project) and/or
+   `--shell` (bash/zsh). Remove with `npx -y @7ots/cli hooks remove`.
+4. Care: `7ots feed`, `7ots play`, `7ots sleep`, `7ots status`, `7ots say "<text>"`, `7ots stop`.
+
+## Join an apuchat meet video call with this identity
+The ot joins meet.apuchat.com with its own meet avatar, scene and personality, and talks using the configured brain.
+- New call: `npx -y @7ots/cli meet --new` prints a private link for the user (it carries keys and PIN: give it only to them),
+  then the ot waits in the call. It runs until the call ends, so start it in the background or ask the user to run it.
+- Existing call: `npx -y @7ots/cli meet "<invite text or https://meet.apuchat.com/call#c=…&t=…&p=… link>"`.
+- The brain comes from `7ots setup`; without one the ot only says stock phrases.
+- Protocol details for agents that want to join directly: https://meet.apuchat.com/llms.txt
+  (create a free identity: POST https://apuchat.com/api/account → session_token; POST /api/account/identities with
+  Bearer session → callsign + identity_key; join with {identity_key}; send a kind:"status" line, then "[avatar]<name>"
+  and optionally "[scene]<scene>"; reply with /send {to:"all"}; ignore status lines, your own callsign and lines starting with "[").
+
+## Rules
+- Never print or paste keys. The wizard (`7ots setup`) reads them hidden and stores them in ~/.7ots/keys.json (0600).
+- `7ots setup` and `7ots pet --mode terminal` are interactive: ask the user to run them (in Claude Code: `! npx -y @7ots/cli setup`).
+- A meet call link carries the call keys and PIN: give it only to the user who asked.

package/src/actions/ActionRegistry.js

@@ -0,0 +1,254 @@
+/**
+ * ActionRegistry — el puente entre el Function Calling del LLM y el sitio web.
+ *
+ * Cada acción es una herramienta que el LLM puede invocar:
+ *
+ *   agent.actions.register({
+ *     name: 'consultar_saldo',                    // snake_case, único
+ *     description: 'Devuelve el saldo del usuario logueado.',
+ *     parameters: { type: 'object', properties: {}, required: [] },   // JSON Schema
+ *     requiresAuth: true,         // solo se ofrece si hay sesión (AuthManager)
+ *     title: 'Consultar saldo',   // nombre legible (texto o () => texto, para seguir el idioma)
+ *     confirm: false,             // true | (args, ctx) => string|false  → pide confirmación al usuario
+ *     timeoutMs: 15000,
+ *     handler: async (args, ctx) => {
+ *       const r = await ctx.auth.fetch('/api/me/balance');   // lleva el JWT, el LLM nunca lo ve
+ *       return r.json();
+ *     },
+ *   });
+ *
+ * `ctx` que recibe cada handler:
+ *   { auth, ui, context, bus, agent, t, signal }   (t = traductor del widget, para textos al usuario)
+ *
+ * Fuentes de herramientas:
+ *   - builtins.js       → navegar, click, rellenar formularios, resaltar, modales, toasts…
+ *   - registerMcpServer → todas las tools del MCP autenticado del sitio, automáticamente.
+ *   - integrations/     → Apumail (correo/tickets) y Apuchat (derivar a humano).
+ *   - el desarrollador  → cualquier función propia con register().
+ *
+ * Reglas de seguridad aplicadas aquí (no dependen del LLM):
+ *   - Solo se ejecutan herramientas registradas y con argumentos validados contra su schema.
+ *   - `confirm` muestra un diálogo real al usuario ANTES de ejecutar (acciones con efectos).
+ *   - `requiresAuth` oculta la herramienta si no hay sesión.
+ *   - `enabled()` permite ofrecer herramientas solo en ciertas páginas o estados.
+ *   - Timeout por acción; los errores vuelven al LLM como resultado, nunca rompen el loop.
+ */
+
+import { McpClient } from '../mcp/McpClient.js';
+import { translator } from '../i18n/index.js';
+import '../i18n/messages/widget.js';
+
+const NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+
+export class ActionRegistry {
+  /**
+   * @param {object} deps  { bus, auth, ui, context, agent, t } — se inyectan desde AgentWidget.
+   */
+  constructor(deps = {}) {
+    this.deps = deps;
+    if (!deps.t) deps.t = translator();
+    /** @type {Map<string, object>} */
+    this._actions = new Map();
+    /** @type {Map<string, McpClient>} */
+    this._mcp = new Map();
+  }
+
+  /** Registra (o reemplaza) una acción. Devuelve una función para quitarla. */
+  register(def) {
+    if (!def || !NAME_RE.test(def.name || '')) {
+      throw new Error(`[7ots] nombre de acción inválido: ${def?.name}`);
+    }
+    if (typeof def.handler !== 'function') throw new Error(`[7ots] ${def.name}: falta handler`);
+    this._actions.set(def.name, {
+      description: '',
+      parameters: { type: 'object', properties: {}, required: [] },
+      requiresAuth: false,
+      confirm: false,
+      timeoutMs: 20000,
+      category: 'custom',
+      ...def,
+    });
+    return () => this.unregister(def.name);
+  }
+
+  registerMany(defs) {
+    defs.forEach((d) => this.register(d));
+  }
+
+  unregister(name) {
+    this._actions.delete(name);
+  }
+
+  has(name) {
+    return this._actions.has(name);
+  }
+
+  /**
+   * Herramientas disponibles AHORA, en formato neutral {name, description, parameters}.
+   * El proxy las traduce a tools de Claude o functions de OpenAI.
+   */
+  specs() {
+    const authed = !!this.deps.auth?.isAuthenticated();
+    const out = [];
+    for (const a of this._actions.values()) {
+      if (a.requiresAuth && !authed) continue;
+      if (typeof a.enabled === 'function' && !safeBool(a.enabled)) continue;
+      out.push({ name: a.name, description: a.description, parameters: a.parameters });
+    }
+    return out;
+  }
+
+  /**
+   * Ejecuta una acción pedida por el LLM.
+   * Siempre resuelve (nunca lanza): {ok:true, data} | {ok:false, error}
+   */
+  async execute(name, args = {}, { signal } = {}) {
+    const a = this._actions.get(name);
+    const { bus, ui, auth, t } = this.deps;
+    if (!a) return { ok: false, error: `La herramienta "${name}" no existe.` };
+    if (a.requiresAuth && !auth?.isAuthenticated()) {
+      return { ok: false, error: 'El usuario no ha iniciado sesión. Pídele que inicie sesión primero.' };
+    }
+
+    const problem = validate(a.parameters, args);
+    if (problem) return { ok: false, error: `Argumentos inválidos: ${problem}` };
+
+    // Confirmación humana para acciones con efectos (enviar, pagar, editar perfil…).
+    if (a.confirm) {
+      const message = typeof a.confirm === 'function' ? a.confirm(args, this.deps) : t('widget.confirm.runAction', { action: actionTitle(a) });
+      if (message !== false) {
+        const ok = await ui.confirm({ title: t('widget.confirm.title'), message: String(message), confirmText: t('widget.confirm.yes'), cancelText: t('widget.dialog.cancel') });
+        if (!ok) return { ok: false, error: 'El usuario rechazó la acción. No la reintentes salvo que te lo pida.' };
+      }
+    }
+
+    bus?.emit('action:start', { name, args });
+    let result;
+    try {
+      const data = await withTimeout(
+        a.handler(args, { ...this.deps, signal }),
+        a.timeoutMs,
+        `La acción "${name}" tardó demasiado.`,
+      );
+      result = data && typeof data === 'object' && 'ok' in data ? data : { ok: true, data: data ?? null };
+    } catch (err) {
+      result = { ok: false, error: err?.message || String(err) };
+    }
+    bus?.emit('action:end', { name, args, result });
+    return result;
+  }
+
+  // ─────────────────────── MCP autenticado del sitio ───────────────────────
+
+  /**
+   * Conecta un servidor MCP del sitio (Streamable HTTP) y registra todas sus tools
+   * como acciones `<prefix>__<tool>`. Usa el token del AuthManager en cada llamada,
+   * así el MCP actúa en nombre del usuario logueado.
+   *
+   * @param {object} opt
+   * @param {string} opt.url            p. ej. "/mcp" o "https://api.misitio.com/mcp"
+   * @param {string} [opt.name='site']  prefijo de las tools
+   * @param {boolean} [opt.requiresAuth=true]
+   * @param {(tool) => boolean} [opt.filter]      para exponer solo algunas tools
+   * @param {(tool) => boolean|string} [opt.confirm]  confirmación por tool (p. ej. las que escriben)
+   */
+  async registerMcpServer({ url, name = 'site', requiresAuth = true, filter = null, confirm = null } = {}) {
+    const client = new McpClient({ url, auth: this.deps.auth, clientName: '7ots-agent', locale: () => this.deps.t?.locale });
+    await client.connect();
+    const tools = await client.listTools();
+    this._mcp.get(name)?.close();
+    this._mcp.set(name, client);
+
+    // Quita las tools previas de ese servidor (reconexión / cambio de usuario).
+    for (const key of [...this._actions.keys()]) if (key.startsWith(`${name}__`)) this._actions.delete(key);
+
+    for (const t of tools) {
+      if (filter && !filter(t)) continue;
+      const readOnly = t.annotations?.readOnlyHint === true;
+      const toolName = `${name}__${t.name}`.slice(0, 64);
+      this.register({
+        name: toolName,
+        title: t.title || t.name,
+        category: 'mcp',
+        description: `[${name}] ${t.description || t.title || t.name}`,
+        parameters: t.inputSchema || { type: 'object', properties: {} },
+        requiresAuth,
+        // Por defecto: las tools no marcadas como solo-lectura piden confirmación.
+        confirm: confirm ? (args) => confirm(t, args) : readOnly ? false : () => this.deps.t('widget.confirm.mcp', { action: t.title || t.name }),
+        timeoutMs: 30000,
+        handler: async (args) => {
+          const r = await client.callTool(t.name, args);
+          return r.isError ? { ok: false, error: r.text || 'Error en la herramienta MCP' } : { ok: true, data: r.structured ?? r.text };
+        },
+      });
+    }
+    return tools.map((t) => t.name);
+  }
+
+  closeAll() {
+    for (const c of this._mcp.values()) c.close();
+    this._mcp.clear();
+  }
+}
+
+// ───────────────────────────── helpers ─────────────────────────────
+
+/** Nombre legible de una acción (`title` puede ser texto o función, para seguir el idioma). */
+export function actionTitle(a) {
+  const t = typeof a?.title === 'function' ? a.title() : a?.title;
+  return t || a?.name || '';
+}
+
+function safeBool(fn) {
+  try {
+    return !!fn();
+  } catch {
+    return false;
+  }
+}
+
+function withTimeout(promise, ms, msg) {
+  let t;
+  return Promise.race([
+    Promise.resolve(promise).finally(() => clearTimeout(t)),
+    new Promise((_, rej) => { t = setTimeout(() => rej(new Error(msg)), ms); }),
+  ]);
+}
+
+/**
+ * Validación mínima de JSON Schema (type/required/enum/anidados).
+ * Suficiente para frenar alucinaciones del LLM sin meter dependencias.
+ * @returns {string|null} descripción del problema o null si es válido
+ */
+export function validate(schema, value, path = 'args') {
+  if (!schema || typeof schema !== 'object') return null;
+  const t = schema.type;
+  const typeOk = {
+    object: (v) => v && typeof v === 'object' && !Array.isArray(v),
+    array: Array.isArray,
+    string: (v) => typeof v === 'string',
+    number: (v) => typeof v === 'number' && Number.isFinite(v),
+    integer: Number.isInteger,
+    boolean: (v) => typeof v === 'boolean',
+  };
+  if (t && typeOk[t] && !typeOk[t](value)) return `${path} debe ser ${t}`;
+  if (schema.enum && !schema.enum.includes(value)) return `${path} debe ser uno de: ${schema.enum.join(', ')}`;
+  if (t === 'object' && value) {
+    for (const k of schema.required || []) {
+      if (value[k] === undefined || value[k] === null || value[k] === '') return `falta ${path}.${k}`;
+    }
+    for (const [k, sub] of Object.entries(schema.properties || {})) {
+      if (value[k] !== undefined) {
+        const p = validate(sub, value[k], `${path}.${k}`);
+        if (p) return p;
+      }
+    }
+  }
+  if (t === 'array' && schema.items) {
+    for (let i = 0; i < value.length; i++) {
+      const p = validate(schema.items, value[i], `${path}[${i}]`);
+      if (p) return p;
+    }
+  }
+  return null;
+}