@yujinapp/yuemail 0.4.1 → 0.6.1

package/server-dist/brain/catalog.js

@@ -0,0 +1,69 @@
+/**
+ * Brain command catalog -- the set of Yuemail commands the AI router may
+ * choose from (the "NAC3 tools" exposed to the brain). One entry per
+ * action, grouped by the UI context where it is reachable.
+ *
+ * The command ids here MUST stay a subset of VoiceCommandType in
+ * src/voice/commands.ts. tests/brain/catalog-symmetry.test.ts enforces it
+ * in both directions so the brain can never pick a command the client
+ * cannot execute, and a new global command is never silently unreachable
+ * by voice (producer/consumer symmetry, SQ 14).
+ *
+ * ASCII-only.
+ */
+/** Global commands -- reachable with no modal open. This is the main
+ *  camino-1 surface. */
+export const GLOBAL_COMMANDS = [
+    { type: 'NUEVO_DOCUMENTO', description: 'Vaciar el editor y empezar un documento nuevo.', examples: ['nuevo documento', 'arranquemos uno nuevo', 'borra todo y empezamos de cero', 'quiero escribir una carta nueva'] },
+    { type: 'ABRIR_DOCUMENTO', description: 'Abrir un documento guardado; opcionalmente por nombre.', examples: ['abrir documento', 'abri el informe', 'carga el ultimo que escribi', 'mostrame el documento del banco'], payload: 'name' },
+    { type: 'GUARDAR_FIRMA', description: 'Abrir el pad para crear o guardar la firma.', examples: ['guardar firma', 'quiero hacer mi firma', 'abri donde se dibuja la firma'] },
+    { type: 'FIRMAR', description: 'Insertar la firma ya guardada en el documento.', examples: ['firmar', 'firma el documento', 'pone mi firma aca', 'agrega la firma al final'] },
+    { type: 'INICIAR_DICTADO', description: 'Empezar a transcribir lo que la persona dicta al cuerpo del documento.', examples: ['iniciar dictado', 'voy a dictar', 'empeza a escribir lo que digo', 'tomame nota'] },
+    { type: 'FIN_DICTADO', description: 'Dejar de transcribir el dictado.', examples: ['fin dictado', 'listo, pare de escribir', 'termine de dictar'] },
+    { type: 'ENVIAR', description: 'Abrir el dialogo para enviar el documento por correo; opcionalmente a un email dicho.', examples: ['enviar', 'mandaselo a ana arroba ejemplo punto com', 'quiero mandar este correo', 'envialo a mi hijo'], payload: 'email' },
+    { type: 'LEER_BANDEJA', description: 'Listar y leer los correos recibidos en la bandeja.', examples: ['leer bandeja', 'que correos tengo', 'fijate si llego algo', 'lee mis mensajes'] },
+    { type: 'ABRIR_CONFIGURACION', description: 'Abrir la configuracion de la cuenta de correo.', examples: ['abrir configuracion', 'ajustes', 'quiero configurar mi correo', 'donde pongo mi clave'] },
+    { type: 'ENCENDER_MICROFONO', description: 'Encender el microfono.', examples: ['encender microfono', 'prende el microfono', 'activa la voz'] },
+    { type: 'APAGAR_MICROFONO', description: 'Apagar el microfono.', examples: ['apagar microfono', 'apaga el microfono'] },
+    { type: 'DETENER_VOZ', description: 'Silenciar / detener la voz.', examples: ['detener voz', 'silencio', 'calla', 'basta'] },
+];
+export const SEND_DIALOG_COMMANDS = [
+    { type: 'CONFIRMAR_ENVIO', description: 'Confirmar y enviar el correo.', examples: ['confirmar', 'enviar ya', 'mandalo', 'dale, envialo'] },
+    { type: 'CANCELAR', description: 'Cerrar el dialogo sin enviar.', examples: ['cancelar', 'cerra', 'no, no lo mandes', 'volver'] },
+    { type: 'ENFOCAR_CAMPO', description: 'Enfocar un campo del envio para dictarlo (destinatario, asunto, cuerpo, adjuntar).', examples: ['campo destinatario', 'el asunto', 'quiero dictar el cuerpo', 'poner para quien es'], payload: 'field' },
+    { type: 'BORRAR_CAMPO', description: 'Vaciar el campo enfocado para dictarlo de nuevo.', examples: ['borrar campo', 'borralo y lo digo otra vez'] },
+    { type: 'FIN_CAMPO', description: 'Soltar el campo enfocado y recuperar los comandos del dialogo.', examples: ['fin campo', 'listo el campo'] },
+];
+export const SIGNATURE_PAD_COMMANDS = [
+    { type: 'GUARDAR_FIRMA_PAD', description: 'Guardar la firma dibujada.', examples: ['guardar', 'listo', 'guarda esta firma'] },
+    { type: 'BORRAR_FIRMA', description: 'Limpiar el lienzo de firma.', examples: ['borrar', 'limpiar', 'empezar la firma de nuevo'] },
+    { type: 'GENERAR_FIRMA', description: 'Generar la firma cursiva a partir del nombre escrito.', examples: ['generar', 'hacela en cursiva', 'genera la firma'] },
+    { type: 'CANCELAR', description: 'Cerrar el pad sin guardar.', examples: ['cancelar', 'cerra', 'salir'] },
+    { type: 'ENFOCAR_CAMPO', description: 'Enfocar el nombre para dictarlo y generar la firma cursiva.', examples: ['campo nombre', 'quiero poner mi nombre'], payload: 'field' },
+    { type: 'BORRAR_CAMPO', description: 'Vaciar el nombre para dictarlo de nuevo.', examples: ['borrar campo'] },
+    { type: 'FIN_CAMPO', description: 'Soltar el campo.', examples: ['fin campo'] },
+];
+export const SETTINGS_DIALOG_COMMANDS = [
+    { type: 'DETECTAR_SERVIDORES', description: 'Autocompletar los servidores a partir de la direccion de correo.', examples: ['detectar', 'autodetectar servidores', 'completalo automatico'] },
+    { type: 'PROBAR_CONEXION', description: 'Probar la conexion IMAP y SMTP en vivo.', examples: ['probar', 'verificar conexion', 'fijate si funciona'] },
+    { type: 'GUARDAR_CONFIG', description: 'Guardar la configuracion en la boveda cifrada.', examples: ['guardar', 'listo, guardalo'] },
+    { type: 'CANCELAR', description: 'Cerrar la configuracion sin guardar.', examples: ['cancelar', 'cerra', 'salir'] },
+    { type: 'ENFOCAR_CAMPO', description: 'Enfocar un campo de la configuracion para dictarlo (nombre, correo, contrasena, servidores, puertos, ssl).', examples: ['campo correo', 'la contrasena', 'servidor de entrada', 'quiero poner mi mail'], payload: 'field' },
+    { type: 'BORRAR_CAMPO', description: 'Vaciar el campo enfocado.', examples: ['borrar campo'] },
+    { type: 'FIN_CAMPO', description: 'Soltar el campo enfocado.', examples: ['fin campo'] },
+];
+export const COMMANDS_BY_CONTEXT = {
+    global: GLOBAL_COMMANDS,
+    send_dialog: SEND_DIALOG_COMMANDS,
+    signature_pad: SIGNATURE_PAD_COMMANDS,
+    settings_dialog: SETTINGS_DIALOG_COMMANDS,
+};
+/** Every command type the brain may ever return, across all contexts. */
+export function allBrainCommandTypes() {
+    const s = new Set();
+    for (const ctx of Object.keys(COMMANDS_BY_CONTEXT)) {
+        for (const c of COMMANDS_BY_CONTEXT[ctx])
+            s.add(c.type);
+    }
+    return s;
+}

package/server-dist/brain/config.js

@@ -0,0 +1,112 @@
+/**
+ * Brain config -- which provider + model resolves a spoken request into a
+ * Yuemail command (v0.5.0). Replicates the Yujin-Forge brain_config pattern
+ * (single config, every provider, one default model) trimmed to Yuemail's
+ * single-user, server-side, BYOK shape.
+ *
+ * Storage:
+ *   ~/.yuemail/brain.json   (honours YUEMAIL_HOME like the vault).
+ *
+ * The provider API keys themselves live in the SAME encrypted vault as the
+ * mail credentials (slot 'brain.<provider>'), so a key never reaches the
+ * browser: the router runs in this process and reads the vault directly.
+ *
+ * Camino 1 (default): the Brain resolves every utterance. The fixed-phrase
+ * matcher stays as camino 2 (safety net) when the Brain is disabled, has no
+ * key, the network is down, or it answers below min_confidence -- a person
+ * who depends on this app must never be left without it.
+ *
+ * ASCII-only.
+ */
+import { promises as fs, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const ALL_BRAIN_PROVIDERS = [
+    'google_ai', 'anthropic', 'openai', 'deepseek', 'xai', 'mistral', 'qwen', 'zai', 'ollama',
+];
+/** Vault slot a provider stores its key under. Ollama is local + keyless;
+ *  the slot exists only for an exhaustive map and getKey() returns nothing. */
+export function vaultSlotForProvider(p) {
+    return 'brain.' + p;
+}
+/* The user asked for Gemini Flash Lite as the default brain. The exact id
+ * resolves against the provider's live model list once a key is present
+ * (see provider_models). If this id 404s the router fails closed and the
+ * phrase matcher takes over -- the app keeps working either way. */
+export const DEFAULT_MODEL = 'gemini-3.1-flash-lite';
+export function defaultBrainConfig() {
+    return {
+        version: 1,
+        enabled: true,
+        provider: 'google_ai',
+        model: DEFAULT_MODEL,
+        min_confidence: 0.5,
+        timeout_ms: 4000,
+    };
+}
+function homeDir() {
+    const env = process.env['YUEMAIL_HOME'];
+    return env ? path.resolve(env) : path.join(os.homedir(), '.yuemail');
+}
+function brainConfigPath() { return path.join(homeDir(), 'brain.json'); }
+function ensureHomeDir() {
+    if (!existsSync(homeDir()))
+        mkdirSync(homeDir(), { recursive: true, mode: 0o700 });
+}
+function normaliseProvider(v) {
+    if (typeof v !== 'string')
+        return null;
+    const lc = v.toLowerCase().trim();
+    return ALL_BRAIN_PROVIDERS.includes(lc) ? lc : null;
+}
+function clampConfidence(v, fallback) {
+    if (typeof v !== 'number' || Number.isNaN(v))
+        return fallback;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+export async function readBrainConfig() {
+    const def = defaultBrainConfig();
+    try {
+        const raw = await fs.readFile(brainConfigPath(), 'utf-8');
+        const j = JSON.parse(raw);
+        return {
+            version: 1,
+            enabled: j.enabled !== false,
+            provider: normaliseProvider(j.provider) ?? def.provider,
+            model: typeof j.model === 'string' && j.model.trim() !== '' ? j.model.trim() : def.model,
+            min_confidence: clampConfidence(j.min_confidence, def.min_confidence),
+            timeout_ms: typeof j.timeout_ms === 'number' && j.timeout_ms > 0 ? Math.min(j.timeout_ms, 30000) : def.timeout_ms,
+        };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return def;
+        return def;
+    }
+}
+export async function writeBrainConfig(cfg) {
+    ensureHomeDir();
+    const p = brainConfigPath();
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    await fs.rename(tmp, p);
+}
+/** Merge a partial patch onto the stored config + persist. Unknown fields
+ *  are ignored; invalid values fall back to the current value. */
+export async function patchBrainConfig(patch) {
+    const cur = await readBrainConfig();
+    const next = {
+        version: 1,
+        enabled: typeof patch.enabled === 'boolean' ? patch.enabled : cur.enabled,
+        provider: normaliseProvider(patch.provider) ?? cur.provider,
+        model: typeof patch.model === 'string' && patch.model.trim() !== '' ? patch.model.trim() : cur.model,
+        min_confidence: patch.min_confidence === undefined ? cur.min_confidence : clampConfidence(patch.min_confidence, cur.min_confidence),
+        timeout_ms: typeof patch.timeout_ms === 'number' && patch.timeout_ms > 0 ? Math.min(patch.timeout_ms, 30000) : cur.timeout_ms,
+    };
+    await writeBrainConfig(next);
+    return next;
+}

package/server-dist/brain/provider_models.js

@@ -0,0 +1,95 @@
+/* Static fallback -- stable ids known at build time. The user's default
+ * (Gemini Flash Lite) leads the google_ai list. */
+const STATIC_MODELS = {
+    google_ai: [
+        { id: 'gemini-3.1-flash-lite', display_name: 'Gemini 3.1 Flash Lite (default)' },
+        { id: 'gemini-2.5-flash-lite', display_name: 'Gemini 2.5 Flash Lite' },
+        { id: 'gemini-2.5-flash', display_name: 'Gemini 2.5 Flash' },
+        { id: 'gemini-2.5-pro', display_name: 'Gemini 2.5 Pro' },
+    ],
+    anthropic: [
+        { id: 'claude-haiku-4-5-20251001', display_name: 'Claude Haiku 4.5' },
+        { id: 'claude-sonnet-4-6', display_name: 'Claude Sonnet 4.6' },
+        { id: 'claude-opus-4-8', display_name: 'Claude Opus 4.8' },
+    ],
+    openai: [
+        { id: 'gpt-4o-mini', display_name: 'GPT-4o mini' },
+        { id: 'gpt-4o', display_name: 'GPT-4o' },
+    ],
+    deepseek: [
+        { id: 'deepseek-chat', display_name: 'DeepSeek Chat' },
+        { id: 'deepseek-reasoner', display_name: 'DeepSeek Reasoner' },
+    ],
+    xai: [
+        { id: 'grok-3', display_name: 'Grok 3' },
+    ],
+    mistral: [
+        { id: 'mistral-small-latest', display_name: 'Mistral Small' },
+        { id: 'mistral-large-latest', display_name: 'Mistral Large' },
+    ],
+    qwen: [
+        { id: 'qwen-plus', display_name: 'Qwen Plus' },
+        { id: 'qwen-max', display_name: 'Qwen Max' },
+    ],
+    zai: [
+        { id: 'glm-4.6', display_name: 'GLM-4.6' },
+        { id: 'glm-4.5-air', display_name: 'GLM-4.5 Air' },
+    ],
+    ollama: [
+        { id: 'llama3.1', display_name: 'Llama 3.1 (8B, local)' },
+        { id: 'qwen2.5', display_name: 'Qwen 2.5 (local)' },
+    ],
+};
+function staticResult(provider, error) {
+    const r = { provider, models: STATIC_MODELS[provider] ?? [], source: 'static' };
+    if (error)
+        r.error = error.slice(0, 120);
+    return r;
+}
+async function fetchJson(url, headers, fetchImpl, timeoutMs) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const r = await fetchImpl(url, { headers, signal: controller.signal });
+        if (!r.ok)
+            throw new Error('http ' + r.status);
+        return await r.json();
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+/** List models for a provider. Never throws -- degrades to the static list. */
+export async function listProviderModels(provider, opts = {}) {
+    const key = opts.apiKey ?? null;
+    if (!key)
+        return staticResult(provider);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 4000;
+    try {
+        let models;
+        if (provider === 'google_ai') {
+            const j = await fetchJson('https://generativelanguage.googleapis.com/v1beta/models?pageSize=100', { 'x-goog-api-key': key }, fetchImpl, timeoutMs);
+            models = (j.models ?? [])
+                .filter((m) => typeof m.name === 'string' && (m.supportedGenerationMethods ?? []).includes('generateContent'))
+                .map((m) => ({ id: m.name.replace(/^models\//, ''), display_name: m.displayName || m.name.replace(/^models\//, '') }));
+        }
+        else if (provider === 'anthropic') {
+            const j = await fetchJson('https://api.anthropic.com/v1/models?limit=50', { 'x-api-key': key, 'anthropic-version': '2023-06-01' }, fetchImpl, timeoutMs);
+            models = (j.data ?? []).filter((m) => typeof m.id === 'string').map((m) => ({ id: m.id, display_name: m.display_name || m.id }));
+        }
+        else if (provider === 'openai') {
+            const j = await fetchJson('https://api.openai.com/v1/models', { 'authorization': 'Bearer ' + key }, fetchImpl, timeoutMs);
+            models = (j.data ?? []).filter((m) => typeof m.id === 'string' && /^(gpt|o[0-9])/.test(m.id)).map((m) => ({ id: m.id, display_name: m.id }));
+        }
+        else {
+            return staticResult(provider);
+        }
+        if (models.length === 0)
+            return staticResult(provider, 'empty model list');
+        return { provider, models, source: 'live' };
+    }
+    catch (err) {
+        return staticResult(provider, err instanceof Error ? err.message : String(err));
+    }
+}

package/server-dist/brain/providers.js

@@ -0,0 +1,125 @@
+/** OpenAI-compatible base URLs (no trailing slash; '/chat/completions' is
+ *  appended). Ollama is local; override with YUEMAIL_OLLAMA_BASE_URL. */
+function openAiCompatBase(provider) {
+    switch (provider) {
+        case 'openai': return 'https://api.openai.com/v1';
+        case 'deepseek': return 'https://api.deepseek.com/v1';
+        case 'xai': return 'https://api.x.ai/v1';
+        case 'mistral': return 'https://api.mistral.ai/v1';
+        case 'qwen': return 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
+        case 'zai': return 'https://open.bigmodel.cn/api/paas/v4';
+        case 'ollama': return process.env['YUEMAIL_OLLAMA_BASE_URL'] || 'http://localhost:11434/v1';
+        default: return '';
+    }
+}
+function isOpenAiCompatible(p) {
+    return p === 'openai' || p === 'deepseek' || p === 'xai' || p === 'mistral'
+        || p === 'qwen' || p === 'zai' || p === 'ollama';
+}
+/** Some providers need a key; ollama is keyless (local). */
+export function providerNeedsKey(p) {
+    return p !== 'ollama';
+}
+async function withTimeout(timeoutMs, run) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await run(controller.signal);
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+async function httpJson(url, init, fetchImpl, signal) {
+    const r = await fetchImpl(url, { ...init, signal });
+    if (!r.ok) {
+        let detail = '';
+        try {
+            detail = (await r.text()).slice(0, 120).replace(/\s+/g, ' ');
+        }
+        catch { /* ignore */ }
+        throw new Error('http ' + r.status + (detail ? ' ' + detail : ''));
+    }
+    return await r.json();
+}
+async function completeGemini(o, fetchImpl) {
+    const url = 'https://generativelanguage.googleapis.com/v1beta/models/'
+        + encodeURIComponent(o.model) + ':generateContent';
+    const body = {
+        /* Gemini folds the system prompt into systemInstruction. */
+        systemInstruction: { parts: [{ text: o.system }] },
+        contents: [{ role: 'user', parts: [{ text: o.user }] }],
+        generationConfig: { temperature: 0, responseMimeType: 'application/json' },
+    };
+    return withTimeout(o.timeoutMs, async (signal) => {
+        const j = await httpJson(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-goog-api-key': o.apiKey ?? '' },
+            body: JSON.stringify(body),
+        }, fetchImpl, signal);
+        const parts = j.candidates?.[0]?.content?.parts ?? [];
+        return parts.map((p) => p.text ?? '').join('').trim();
+    });
+}
+async function completeAnthropic(o, fetchImpl) {
+    const body = {
+        model: o.model,
+        max_tokens: 512,
+        temperature: 0,
+        system: o.system,
+        messages: [{ role: 'user', content: o.user }],
+    };
+    return withTimeout(o.timeoutMs, async (signal) => {
+        const j = await httpJson('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': o.apiKey ?? '',
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify(body),
+        }, fetchImpl, signal);
+        return (j.content ?? []).map((c) => c.text ?? '').join('').trim();
+    });
+}
+async function completeOpenAiCompatible(o, fetchImpl) {
+    const base = openAiCompatBase(o.provider);
+    const body = {
+        model: o.model,
+        temperature: 0,
+        messages: [
+            { role: 'system', content: o.system },
+            { role: 'user', content: o.user },
+        ],
+    };
+    /* Ask for a JSON object where the API supports it (OpenAI proper). The
+     * prompt also demands JSON, so providers that ignore this still comply. */
+    if (o.provider === 'openai')
+        body['response_format'] = { type: 'json_object' };
+    const headers = { 'content-type': 'application/json' };
+    if (o.apiKey)
+        headers['authorization'] = 'Bearer ' + o.apiKey;
+    return withTimeout(o.timeoutMs, async (signal) => {
+        const j = await httpJson(base + '/chat/completions', {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        }, fetchImpl, signal);
+        return (j.choices?.[0]?.message?.content ?? '').trim();
+    });
+}
+/**
+ * One round-trip to the configured brain. Returns the raw model text
+ * (expected to be JSON; the router parses it). Throws on transport error,
+ * non-2xx, or timeout so the caller can fall back to the phrase matcher.
+ */
+export async function complete(o) {
+    const fetchImpl = o.fetchImpl ?? fetch;
+    if (o.provider === 'google_ai')
+        return completeGemini(o, fetchImpl);
+    if (o.provider === 'anthropic')
+        return completeAnthropic(o, fetchImpl);
+    if (isOpenAiCompatible(o.provider))
+        return completeOpenAiCompatible(o, fetchImpl);
+    throw new Error('unknown provider: ' + o.provider);
+}

package/server-dist/brain/router.js

@@ -0,0 +1,141 @@
+/**
+ * Brain router -- turns a free-spoken request into a Yuemail command.
+ *
+ * This is camino 1. Flow:
+ *   1. Read brain config. If disabled -> { ok:false, reason:'disabled' }.
+ *   2. Read the provider key from the vault (none + key required ->
+ *      { ok:false, reason:'no_key' }).
+ *   3. Ask the model to classify the utterance against the context's
+ *      command catalog and return strict JSON {type, payload, confidence}.
+ *   4. Validate: type must exist in the context catalog; confidence must
+ *      clear min_confidence. Otherwise { ok:false, reason:'low_confidence'|
+ *      'unparseable'|'not_in_catalog' }.
+ *
+ * Any { ok:false } (including a thrown transport/timeout error, caught
+ * here) tells the caller to fall back to the fixed-phrase matcher. The
+ * payload is returned raw -- the client normalises it (email extraction,
+ * field-key resolution) where the field specs already live.
+ *
+ * ASCII-only.
+ */
+import { readBrainConfig } from './config.js';
+import { vaultSlotForProvider } from './config.js';
+import { complete, providerNeedsKey } from './providers.js';
+import { COMMANDS_BY_CONTEXT } from './catalog.js';
+import { getKey } from '../vault.js';
+function buildSystemPrompt(context, commands) {
+    const lines = [];
+    lines.push('Sos el cerebro de Yuemail, un cliente de correo por voz para personas con discapacidad.');
+    lines.push('Tu unica tarea: leer lo que la persona dijo y elegir EXACTAMENTE UNO de los comandos de la lista.');
+    lines.push('Contexto actual de la pantalla: ' + context + '.');
+    lines.push('');
+    lines.push('Comandos disponibles (elegi el id tal cual):');
+    for (const c of commands) {
+        const ex = c.examples.slice(0, 3).join(' | ');
+        const pay = c.payload ? ' [payload: ' + c.payload + ']' : '';
+        lines.push('- ' + c.type + pay + ': ' + c.description + ' Ej: ' + ex);
+    }
+    lines.push('');
+    lines.push('Reglas:');
+    lines.push('- Responde SOLO con un objeto JSON, sin texto extra, sin markdown.');
+    lines.push('- Forma: {"type": "<ID>", "payload": "<texto o vacio>", "confidence": <0 a 1>}.');
+    lines.push('- "type" debe ser uno de los ids de arriba, en mayusculas, identico.');
+    lines.push('- Para payload "email": devolve el correo normalizado (ej. "ana@ejemplo.com").');
+    lines.push('- Para payload "name": devolve el nombre del documento mencionado.');
+    lines.push('- Para payload "field": devolve el nombre del campo mencionado (ej. "correo", "asunto").');
+    lines.push('- Si no hay payload, usa "".');
+    lines.push('');
+    lines.push('Cuando NO debes elegir comando, responde {"type": "NINGUNO", "payload": "", "confidence": 0}:');
+    lines.push('- Si la persona NIEGA o pospone la accion ("no lo mandes", "todavia no borres", "no abras"). Una negacion NUNCA dispara el comando negado.');
+    lines.push('- Si es una pregunta, un saludo, un agradecimiento o charla que no pide ninguna accion de la lista.');
+    lines.push('- Si el pedido se parece a una accion que NO figura en la lista de arriba: NO elijas la mas parecida, responde NINGUNO.');
+    lines.push('- Ante la duda, NINGUNO. Para una persona que depende de esta app, no hacer nada es mejor que ejecutar el comando equivocado.');
+    lines.push('Elegi un comando de la lista SOLO si la persona pide hacer esa accion concreta, ahora y en forma afirmativa.');
+    return lines.join('\n');
+}
+/** Pull the first JSON object out of a model reply (handles stray prose or
+ *  ```json fences a provider may add despite instructions). */
+function extractJsonObject(text) {
+    const trimmed = text.trim().replace(/^```(?:json)?/i, '').replace(/```$/i, '').trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch { /* try to locate a brace span */ }
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start >= 0 && end > start) {
+        try {
+            return JSON.parse(trimmed.slice(start, end + 1));
+        }
+        catch { /* give up */ }
+    }
+    return null;
+}
+/** Parse + validate a raw model reply against the context catalog. Exported
+ *  for unit testing without a network round-trip. */
+export function parseBrainReply(raw, context, minConfidence, model) {
+    const obj = extractJsonObject(raw);
+    if (!obj || typeof obj !== 'object')
+        return { ok: false, reason: 'unparseable' };
+    const rec = obj;
+    const type = typeof rec['type'] === 'string' ? rec['type'].trim().toUpperCase() : '';
+    /* Explicit decline sentinel: the model judged no command applies (negation,
+     * question, chit-chat, or an action outside this context's catalog). Treat
+     * it as a clean low-confidence miss so the caller falls back, rather than a
+     * hallucinated-command miss. */
+    if (type === 'NINGUNO' || type === 'NADA')
+        return { ok: false, reason: 'low_confidence', detail: 'ninguno' };
+    const known = new Set(COMMANDS_BY_CONTEXT[context].map((c) => c.type));
+    if (!type || !known.has(type))
+        return { ok: false, reason: 'not_in_catalog', detail: type };
+    let confidence = typeof rec['confidence'] === 'number' ? rec['confidence'] : 0;
+    if (Number.isNaN(confidence))
+        confidence = 0;
+    if (confidence < 0)
+        confidence = 0;
+    if (confidence > 1)
+        confidence = 1;
+    if (confidence < minConfidence)
+        return { ok: false, reason: 'low_confidence', detail: String(confidence) };
+    const result = { ok: true, type, confidence, source: 'brain', model };
+    const payload = rec['payload'];
+    if (typeof payload === 'string' && payload.trim().length > 0)
+        result.payload = payload.trim();
+    return result;
+}
+export async function resolveUtterance(utterance, context = 'global', opts = {}) {
+    const text = (utterance ?? '').trim();
+    if (text.length === 0)
+        return { ok: false, reason: 'unparseable' };
+    const cfg = await readBrainConfig();
+    if (!cfg.enabled)
+        return { ok: false, reason: 'disabled' };
+    let apiKey = opts.apiKeyOverride ?? null;
+    if (apiKey === null && opts.apiKeyOverride === undefined) {
+        try {
+            apiKey = (await getKey(vaultSlotForProvider(cfg.provider))) ?? null;
+        }
+        catch {
+            apiKey = null;
+        }
+    }
+    if (providerNeedsKey(cfg.provider) && !apiKey)
+        return { ok: false, reason: 'no_key' };
+    const commands = COMMANDS_BY_CONTEXT[context];
+    const system = buildSystemPrompt(context, commands);
+    try {
+        const raw = await complete({
+            provider: cfg.provider,
+            model: cfg.model,
+            apiKey,
+            system,
+            user: text,
+            timeoutMs: cfg.timeout_ms,
+            fetchImpl: opts.fetchImpl,
+        });
+        return parseBrainReply(raw, context, cfg.min_confidence, cfg.model);
+    }
+    catch (err) {
+        return { ok: false, reason: 'error', detail: err instanceof Error ? err.message.slice(0, 120) : String(err) };
+    }
+}

package/server-dist/index.js

@@ -25,6 +25,8 @@ import { registerSignatureRoutes } from './routes/signature.js';
 import { registerEmailRoutes } from './routes/email.js';
 import { registerInboxRoutes } from './routes/inbox.js';
 import { registerSettingsRoutes } from './routes/settings.js';
+import { registerBrainRoutes } from './routes/brain.js';
+import { registerVoiceRoutes } from './routes/voice.js';
 export const HOST = '127.0.0.1';
 export const PORT = 5180;
 const __filename = fileURLToPath(import.meta.url);
@@ -59,6 +61,8 @@ export function buildApp(opts = {}) {
     registerEmailRoutes(app);
     registerInboxRoutes(app);
     registerSettingsRoutes(app);
+    registerBrainRoutes(app);
+    registerVoiceRoutes(app);
     /* Static SPA -- present in production builds, absent in dev. */
     const staticRoot = opts.staticRoot ?? path.resolve(__dirname, '..', 'dist');
     if (existsSync(staticRoot)) {

package/server-dist/routes/brain.js

@@ -0,0 +1,80 @@
+import { readBrainConfig, patchBrainConfig, vaultSlotForProvider, ALL_BRAIN_PROVIDERS, } from '../brain/config.js';
+import { providerNeedsKey } from '../brain/providers.js';
+import { listProviderModels } from '../brain/provider_models.js';
+import { resolveUtterance } from '../brain/router.js';
+import { getKey } from '../vault.js';
+function isProvider(v) {
+    return typeof v === 'string' && ALL_BRAIN_PROVIDERS.includes(v);
+}
+async function hasKeyFor(provider) {
+    if (!providerNeedsKey(provider))
+        return true; /* ollama is keyless */
+    try {
+        const k = await getKey(vaultSlotForProvider(provider));
+        return typeof k === 'string' && k.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function publicConfig(cfg) {
+    return {
+        enabled: cfg.enabled,
+        provider: cfg.provider,
+        model: cfg.model,
+        min_confidence: cfg.min_confidence,
+        timeout_ms: cfg.timeout_ms,
+        all_providers: ALL_BRAIN_PROVIDERS,
+    };
+}
+export function registerBrainRoutes(app) {
+    app.get('/api/brain/config', async (_req, res) => {
+        const cfg = await readBrainConfig();
+        res.json({ ok: true, config: publicConfig(cfg), has_key: await hasKeyFor(cfg.provider) });
+    });
+    app.put('/api/brain/config', async (req, res) => {
+        const body = (req.body ?? {});
+        const patch = {};
+        if (typeof body['enabled'] === 'boolean')
+            patch.enabled = body['enabled'];
+        if (isProvider(body['provider']))
+            patch.provider = body['provider'];
+        if (typeof body['model'] === 'string')
+            patch.model = body['model'];
+        if (typeof body['min_confidence'] === 'number')
+            patch.min_confidence = body['min_confidence'];
+        if (typeof body['timeout_ms'] === 'number')
+            patch.timeout_ms = body['timeout_ms'];
+        const cfg = await patchBrainConfig(patch);
+        res.json({ ok: true, config: publicConfig(cfg), has_key: await hasKeyFor(cfg.provider) });
+    });
+    app.get('/api/brain/models', async (req, res) => {
+        const provider = req.query['provider'];
+        if (!isProvider(provider)) {
+            res.status(400).json({ ok: false, error: 'unknown provider' });
+            return;
+        }
+        let apiKey = null;
+        try {
+            apiKey = (await getKey(vaultSlotForProvider(provider))) ?? null;
+        }
+        catch {
+            apiKey = null;
+        }
+        const result = await listProviderModels(provider, { apiKey });
+        res.json({ ok: true, ...result });
+    });
+    app.post('/api/brain/resolve', async (req, res) => {
+        const body = (req.body ?? {});
+        const utterance = typeof body.utterance === 'string' ? body.utterance : '';
+        const ctxRaw = typeof body.context === 'string' ? body.context : 'global';
+        const context = (['global', 'send_dialog', 'signature_pad', 'settings_dialog'].includes(ctxRaw)
+            ? ctxRaw : 'global');
+        if (utterance.trim().length === 0) {
+            res.status(400).json({ ok: false, reason: 'unparseable' });
+            return;
+        }
+        const result = await resolveUtterance(utterance, context);
+        res.json(result);
+    });
+}