helix-assistant-cli 0.2.14 → 0.6.1

package/dist/ui/autocomplete.js

@@ -12,12 +12,15 @@ exports.SLASH_COMMANDS = [
     { command: '/skill', description: 'Listar o inspeccionar skills registradas', usage: '/skill [nombre]' },
     { command: '/mcp', description: 'Listar servidores MCP y sus herramientas', usage: '/mcp [defaults]' },
     { command: '/create-mcp', description: 'Registrar y configurar un nuevo servidor MCP' },
-    { command: '/browser', description: 'Ver estado del navegador web o abrir URLs', usage: '/browser [open <url>]' },
+    { command: '/browser', description: 'Ver estado, abrir URLs o alternar la vista ASCII', usage: '/browser [open <url>|live [on|off]]' },
+    { command: '/subagents', description: 'Ver el panel ASCII o chatear con un subagente', usage: '/subagents [list|chat <id> <mensaje>]' },
     { command: '/config-apikey', description: 'Configurador interactivo de API Keys (OpenAI, Anthropic, Gemini, etc.)' },
     { command: '/show-apikey', description: 'Ver estado y validez de las API Keys configuradas' },
     { command: '/microphone', description: 'Ver o alternar estado del micrófono', usage: '/microphone [enable|disable]' },
     { command: '/tasks', description: 'Ver tareas activas y recientes del agente' },
+    { command: '/model', description: 'Ver o cambiar el modelo activo (free/local/cloud)', usage: '/model [list|set <id>|effort <low|medium|high>]' },
     { command: '/models', description: 'Listar modelos disponibles de proveedores configurados' },
+    { command: '/memory', description: 'Ver estadísticas del harness de aprendizaje adaptativo', usage: '/memory [stats|rules|reset]' },
     { command: '/status', description: 'Mostrar resumen del estado del sistema' },
     { command: '/providers', description: 'Ver proveedores configurados y salud de sus claves' },
     { command: '/capabilities', description: 'Ver capacidades activas: sandbox, subagentes, voz y browser' },
@@ -107,7 +110,19 @@ class Autocompleter {
             const hits = options.filter((o) => o.toLowerCase().startsWith(trimmed.toLowerCase()));
             return [hits.length ? hits : options, line];
         }
-        // 3. Browser sub-arguments
+        // 3. Model sub-arguments
+        if (trimmed.startsWith('/model ')) {
+            const options = ['/model list', '/model set ', '/model effort low', '/model effort medium', '/model effort high'];
+            const hits = options.filter((o) => o.toLowerCase().startsWith(trimmed.toLowerCase()));
+            return [hits.length ? hits : options, line];
+        }
+        // 3b. Memory sub-arguments
+        if (trimmed.startsWith('/memory ')) {
+            const options = ['/memory stats', '/memory rules', '/memory reset'];
+            const hits = options.filter((o) => o.toLowerCase().startsWith(trimmed.toLowerCase()));
+            return [hits.length ? hits : options, line];
+        }
+        // 4. Browser sub-arguments
         if (trimmed.startsWith('/browser ')) {
             const options = ['/browser open https://'];
             return [options, line];

package/dist/ui/browser-ascii.d.ts

@@ -0,0 +1,2 @@
+export declare function grayscaleToAscii(pixels: number[][], width?: number): string;
+export declare function renderJpegAsAscii(base64: string, width?: number): string;

package/dist/ui/browser-ascii.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grayscaleToAscii = grayscaleToAscii;
+exports.renderJpegAsAscii = renderJpegAsAscii;
+const jpeg_js_1 = __importDefault(require("jpeg-js"));
+const ASCII_RAMP = ' .:-=+*#%@';
+const MAX_FRAME_WIDTH = 76;
+const MAX_FRAME_HEIGHT = 34;
+const MAX_JPEG_BYTES = 560_000;
+function grayscaleToAscii(pixels, width = MAX_FRAME_WIDTH) {
+    if (!pixels.length || !pixels[0]?.length) {
+        throw new Error('Browser frame has no pixels to render.');
+    }
+    const boundedWidth = Math.max(1, Math.min(MAX_FRAME_WIDTH, Math.floor(width)));
+    const sourceHeight = pixels.length;
+    const sourceWidth = pixels[0].length;
+    const outputHeight = Math.max(1, Math.min(MAX_FRAME_HEIGHT, Math.round((sourceHeight / sourceWidth) * boundedWidth * 0.5)));
+    const lines = [];
+    for (let y = 0; y < outputHeight; y += 1) {
+        const sourceY = Math.min(sourceHeight - 1, Math.floor((y / outputHeight) * sourceHeight));
+        let line = '';
+        for (let x = 0; x < boundedWidth; x += 1) {
+            const sourceX = Math.min(sourceWidth - 1, Math.floor((x / boundedWidth) * sourceWidth));
+            const value = Math.max(0, Math.min(255, pixels[sourceY][sourceX]));
+            const index = Math.round(((255 - value) / 255) * (ASCII_RAMP.length - 1));
+            line += ASCII_RAMP[index];
+        }
+        lines.push(line);
+    }
+    return lines.join('\n');
+}
+function renderJpegAsAscii(base64, width = MAX_FRAME_WIDTH) {
+    if (typeof base64 !== 'string'
+        || !/^[A-Za-z0-9+/]+={0,2}$/.test(base64)
+        || base64.length > Math.ceil(MAX_JPEG_BYTES * 4 / 3)) {
+        throw new Error('Browser frame is not a valid, bounded Base64 JPEG.');
+    }
+    const bytes = Buffer.from(base64, 'base64');
+    if (bytes.length === 0 || bytes.length > MAX_JPEG_BYTES) {
+        throw new Error('Browser frame exceeds the supported JPEG size.');
+    }
+    const image = jpeg_js_1.default.decode(bytes, {
+        useTArray: true,
+        formatAsRGBA: true,
+        maxResolutionInMP: 4,
+        maxMemoryUsageInMB: 128,
+    });
+    const pixels = [];
+    const outputWidth = Math.min(MAX_FRAME_WIDTH, image.width);
+    const outputHeight = Math.max(1, Math.min(MAX_FRAME_HEIGHT, Math.round((image.height / image.width) * outputWidth * 0.5)));
+    for (let y = 0; y < outputHeight; y += 1) {
+        const row = [];
+        const sourceY = Math.min(image.height - 1, Math.floor((y / outputHeight) * image.height));
+        for (let x = 0; x < outputWidth; x += 1) {
+            const sourceX = Math.min(image.width - 1, Math.floor((x / outputWidth) * image.width));
+            const offset = (sourceY * image.width + sourceX) * 4;
+            row.push(image.data[offset] * 0.299
+                + image.data[offset + 1] * 0.587
+                + image.data[offset + 2] * 0.114);
+        }
+        pixels.push(row);
+    }
+    return grayscaleToAscii(pixels, Math.min(width, outputWidth));
+}

package/dist/ui/repl.d.ts

@@ -17,6 +17,7 @@ export declare class HelixRepl {
     private activeTasksCount;
     private isProcessingPrompt;
     private plain;
+    private browserLiveViewEnabled;
     constructor(options: ReplOptions);
     start(): Promise<void>;
     private _syncSettings;

package/dist/ui/repl.js

@@ -16,8 +16,12 @@ const skills_1 = require("../commands/skills");
 const mcp_1 = require("../commands/mcp");
 const mic_1 = require("../commands/mic");
 const browser_1 = require("../commands/browser");
+const subagents_1 = require("../commands/subagents");
 const markdown_1 = require("./markdown");
 const diagnostics_1 = require("../commands/diagnostics");
+const browser_ascii_1 = require("./browser-ascii");
+const model_1 = require("../commands/model");
+const memory_1 = require("../commands/memory");
 class HelixRepl {
     options;
     rl = null;
@@ -32,6 +36,7 @@ class HelixRepl {
     activeTasksCount = 0;
     isProcessingPrompt = false;
     plain = false;
+    browserLiveViewEnabled = false;
     constructor(options) {
         this.options = options;
         this.conversationId = `cli_conv_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`;
@@ -174,6 +179,23 @@ class HelixRepl {
                 this.activeTaskId = task.task_id || null;
             }
         });
+        this.client.on('browser_frame', (payload) => {
+            if (!this.browserLiveViewEnabled
+                || !payload?.conversation_id?.startsWith('cli_')
+                || payload.mime_type !== 'image/jpeg'
+                || typeof payload.image_base64 !== 'string') {
+                return;
+            }
+            try {
+                process.stdout.write('\r\x1b[K');
+                console.log(`\n${(0, colors_1.CYAN_BOLD)('  HELIX LIVE BROWSER')}`);
+                console.log((0, browser_ascii_1.renderJpegAsAscii)(payload.image_base64));
+                this._promptUser();
+            }
+            catch (error) {
+                console.log((0, colors_1.RED)(`  No se pudo representar el cuadro del navegador: ${error.message}`));
+            }
+        });
     }
     async _handleConfirmationDialog(req) {
         console.log(`\n${(0, colors_1.YELLOW_BOLD)('⚠️   CONFIRMACIÓN DE ACCIÓN REQUERIDA')}`);
@@ -343,15 +365,40 @@ class HelixRepl {
                     this.voiceEnabled = newState;
                     break;
                 }
-                case '/browser':
+                case '/browser': {
+                    const browserArgs = args.trim().split(/\s+/);
+                    if (browserArgs[0]?.toLowerCase() === 'live') {
+                        const requestedState = browserArgs[1]?.toLowerCase();
+                        if (requestedState && !['on', 'off'].includes(requestedState)) {
+                            console.log((0, colors_1.YELLOW)('  Uso: /browser live [on|off]\n'));
+                            break;
+                        }
+                        this.browserLiveViewEnabled = requestedState
+                            ? requestedState === 'on'
+                            : !this.browserLiveViewEnabled;
+                        console.log(this.browserLiveViewEnabled
+                            ? (0, colors_1.GREEN)('  Vista ASCII del navegador activada.\n')
+                            : (0, colors_1.YELLOW)('  Vista ASCII del navegador desactivada.\n'));
+                        break;
+                    }
                     await (0, browser_1.handleBrowserCommand)(this.client, args);
                     break;
+                }
+                case '/subagents':
+                    await (0, subagents_1.handleSubagentsCommand)(this.client, args);
+                    break;
                 case '/tasks':
                     await this._handleListTasks();
                     break;
+                case '/model':
+                    await (0, model_1.handleModelCommand)(this.client, args);
+                    break;
                 case '/models':
                     await this._handleListModels();
                     break;
+                case '/memory':
+                    await (0, memory_1.handleMemoryCommand)(this.client, args);
+                    break;
                 case '/status':
                     await this._handleStatus();
                     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helix-assistant-cli",
-  "version": "0.2.14",
+  "version": "0.6.1",
   "description": "HELIX - Interactive Terminal CLI for Windows AI Desktop Agent",
   "private": false,
   "publishConfig": {
@@ -21,10 +21,12 @@
     "chalk": "^4.1.2",
     "commander": "^12.0.0",
     "dotenv": "^16.4.5",
+    "jpeg-js": "^0.4.4",
     "prompts": "^2.4.2",
     "ws": "^8.16.0"
   },
   "devDependencies": {
+    "@types/jpeg-js": "^0.3.0",
     "@types/node": "^20.11.0",
     "@types/prompts": "^2.4.9",
     "@types/ws": "^8.5.10",

package/src/commands/browser.ts

@@ -14,7 +14,7 @@ export async function handleBrowserCommand(
     console.log(CYAN(`\n  Solicitando al agente abrir en navegador: ${targetUrl}...`));
     client.sendUserText(
       `Por favor abre la siguiente URL en el navegador: ${targetUrl}`,
-      `browser_${Date.now()}`
+      `cli_browser_${Date.now()}`
     );
     console.log(GREEN(`  ✔ Comando enviado al agente.\n`));
     return;
@@ -32,7 +32,8 @@ export async function handleBrowserCommand(
     console.log(`  Dominios:    ${settings.block_untrusted_domains ? YELLOW('Filtrado Estricto') : GRAY('Abierto')}`);
     console.log(`\n  ${DIM('Comandos disponibles:')}`);
     console.log(`    ${CYAN('/browser')}              ${DIM('- Ver estado de navegación')}`);
-    console.log(`    ${CYAN('/browser open <url>')}   ${DIM('- Abrir URL con el agente')}\n`);
+    console.log(`    ${CYAN('/browser open <url>')}   ${DIM('- Abrir URL con el agente')}`);
+    console.log(`    ${CYAN('/browser live [on|off]')} ${DIM('- Alternar la vista ASCII de capturas')}\n`);
   } catch (err) {
     console.log(RED(`  Error al consultar estado del navegador: ${(err as Error).message}\n`));
   }

package/src/commands/memory.ts

@@ -0,0 +1,167 @@
+/**
+ * /memory — CLI command for inspecting the Adaptive Learning Harness.
+ *
+ * Subcommands:
+ *   /memory           — show quick stats summary
+ *   /memory stats     — detailed episode + rule counts
+ *   /memory rules     — list top learned rules
+ *   /memory reset     — run maintenance / pruning cycle
+ */
+import chalk from 'chalk';
+import type { AgentClient } from '../client/agent-client';
+import { GREEN, YELLOW, RED, GRAY, DIM, BOLD, ORANGE_BOLD, CYAN } from '../ui/colors';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+interface LearnedRule {
+  category: string;
+  rule: string;
+  confidence: number;
+  uses: number;
+}
+
+interface LearningStats {
+  episode_count: number;
+  rule_count: number;
+  correction_count: number;
+  skill_count: number;
+  top_rules: LearnedRule[];
+  last_episode_at?: string;
+  user_md_exists: boolean;
+}
+
+// ── Request helper ────────────────────────────────────────────────────────────
+
+type RequestableClient = AgentClient & {
+  request: <T>(type: string, payload: unknown) => Promise<T>;
+};
+
+async function fetchLearningStats(client: AgentClient): Promise<LearningStats | null> {
+  try {
+    return await (client as RequestableClient).request<LearningStats>('GET_LEARNING_STATS', {});
+  } catch {
+    return null;
+  }
+}
+
+// ── Renderers ─────────────────────────────────────────────────────────────────
+
+function renderStats(stats: LearningStats): void {
+  console.log('');
+  console.log(`  ${chalk.hex('#FF8C00').bold('⬡ Sistema de Aprendizaje Adaptativo')}`);
+  console.log(`  ${chalk.gray('─'.repeat(48))}`);
+
+  const ep = stats.episode_count;
+  const ru = stats.rule_count;
+  const co = stats.correction_count;
+  const sk = stats.skill_count;
+
+  console.log(`  ${chalk.gray('Episodios registrados')}   ${chalk.white.bold(ep.toString())}`);
+  console.log(`  ${chalk.gray('Correcciones del usuario')} ${co > 0 ? chalk.yellow.bold(co.toString()) : chalk.white(co.toString())}`);
+  console.log(`  ${chalk.gray('Reglas aprendidas')}       ${chalk.cyan.bold(ru.toString())}`);
+  console.log(`  ${chalk.gray('Skills auto-generadas')}   ${chalk.magenta.bold(sk.toString())}`);
+
+  if (stats.last_episode_at) {
+    const d = new Date(stats.last_episode_at);
+    console.log(`  ${chalk.gray('Último episodio')}         ${DIM(d.toLocaleString())}`);
+  }
+
+  const userMdStatus = stats.user_md_exists
+    ? chalk.green('✔ USER.md activo')
+    : chalk.gray('○ Sin perfil generado aún');
+  console.log(`  ${chalk.gray('Perfil feedforward')}      ${userMdStatus}`);
+  console.log('');
+}
+
+function renderRules(stats: LearningStats): void {
+  if (!stats.top_rules || stats.top_rules.length === 0) {
+    console.log(GRAY('  No hay reglas aprendidas todavía. Interactúa con HELIX para que aprenda tus preferencias.\n'));
+    return;
+  }
+
+  console.log('');
+  console.log(`  ${chalk.hex('#FF8C00').bold(`✦ Top ${stats.top_rules.length} Reglas Aprendidas`)}`);
+  console.log(`  ${chalk.gray('─'.repeat(56))}`);
+
+  for (const rule of stats.top_rules) {
+    const conf = Math.round(rule.confidence * 100);
+    const bar = '█'.repeat(Math.min(10, Math.floor(conf / 10)));
+    const confColor = conf >= 80 ? chalk.green : conf >= 50 ? chalk.yellow : chalk.gray;
+    console.log(`  ${chalk.cyan(`[${rule.category}]`).padEnd(24)} ${chalk.white(rule.rule)}`);
+    console.log(`    ${DIM('Confianza:')} ${confColor(`${conf}%`)} ${chalk.gray(bar)}  ${DIM(`(${rule.uses} usos)`)}`);
+    console.log('');
+  }
+}
+
+// ── Command handlers ──────────────────────────────────────────────────────────
+
+export async function handleMemoryStats(client: AgentClient): Promise<void> {
+  const stats = await fetchLearningStats(client);
+
+  if (!stats) {
+    console.log(YELLOW('  ⚠ El harness de aprendizaje no está disponible (agente desconectado o versión antigua).\n'));
+    return;
+  }
+
+  renderStats(stats);
+  if (stats.top_rules?.length) {
+    console.log(DIM('  Usa /memory rules para ver las reglas detalladas.'));
+    console.log('');
+  }
+}
+
+export async function handleMemoryRules(client: AgentClient): Promise<void> {
+  const stats = await fetchLearningStats(client);
+
+  if (!stats) {
+    console.log(YELLOW('  ⚠ El harness de aprendizaje no está disponible.\n'));
+    return;
+  }
+
+  renderStats(stats);
+  renderRules(stats);
+}
+
+export async function handleMemoryReset(client: AgentClient): Promise<void> {
+  try {
+    const result = await (client as RequestableClient).request<{ pruned_rules_count: number; pruned_skills: string[] }>(
+      'RUN_LEARNING_MAINTENANCE',
+      {},
+    );
+
+    console.log('');
+    console.log(GREEN('  ✔ Mantenimiento del harness completado.'));
+    console.log(`  ${chalk.gray('Reglas podadas:')}  ${chalk.white.bold(String(result.pruned_rules_count ?? 0))}`);
+    const pruned = result.pruned_skills ?? [];
+    if (pruned.length) {
+      console.log(`  ${chalk.gray('Skills podadas:')} ${chalk.white(pruned.join(', '))}`);
+    } else {
+      console.log(`  ${chalk.gray('Skills podadas:')} ${DIM('ninguna')}`);
+    }
+    console.log('');
+  } catch (err) {
+    console.log(RED(`  ✖ Error durante mantenimiento: ${(err as Error).message}\n`));
+  }
+}
+
+/** Top-level dispatcher for /memory <args> */
+export async function handleMemoryCommand(client: AgentClient, args: string): Promise<void> {
+  const sub = args.trim().split(/\s+/)[0]?.toLowerCase() || '';
+
+  switch (sub) {
+    case '':
+    case 'stats':
+      await handleMemoryStats(client);
+      break;
+    case 'rules':
+      await handleMemoryRules(client);
+      break;
+    case 'reset':
+    case 'maintenance':
+    case 'prune':
+      await handleMemoryReset(client);
+      break;
+    default:
+      console.log(YELLOW(`  Subcomando desconocido: "${sub}". Opciones: stats, rules, reset\n`));
+  }
+}

package/src/commands/model.ts

@@ -0,0 +1,237 @@
+/**
+ * /model — CLI command for viewing and switching the active AI model.
+ *
+ * Subcommands:
+ *   /model            — show current model + provider
+ *   /model list       — list all model tiers (Free, Local Ollama, Cloud)
+ *   /model set <id>   — switch to a model by id
+ *   /model effort <low|medium|high> — set effort/quality level
+ */
+import chalk from 'chalk';
+import type { AgentClient } from '../client/agent-client';
+import { CYAN, CYAN_BOLD, GREEN, YELLOW, GRAY, DIM, BOLD, ORANGE_BOLD, RED } from '../ui/colors';
+
+// ── Model catalog (mirrors ModelSelectorDropdown.tsx) ──────────────────────────
+export interface ModelEntry {
+  id: string;
+  label: string;
+  tier: 'free' | 'local' | 'cloud';
+  provider: string;
+  badge?: string;
+}
+
+export const FREE_MODELS: ModelEntry[] = [
+  {
+    id: 'meta-llama/llama-3.2-3b-instruct:free',
+    label: 'Llama 3.2 3B Instruct',
+    tier: 'free',
+    provider: 'free',
+    badge: '0-cost',
+  },
+  {
+    id: 'qwen/qwen-2.5-coder-32b-instruct:free',
+    label: 'Qwen 2.5 Coder 32B',
+    tier: 'free',
+    provider: 'free',
+    badge: '0-cost',
+  },
+  {
+    id: 'deepseek/deepseek-r1:free',
+    label: 'DeepSeek R1',
+    tier: 'free',
+    provider: 'free',
+    badge: '0-cost · razonamiento',
+  },
+  {
+    id: 'google/gemini-flash-1.5:free',
+    label: 'Gemini Flash 1.5',
+    tier: 'free',
+    provider: 'free',
+    badge: '0-cost · rápido',
+  },
+];
+
+export const LOCAL_MODELS: ModelEntry[] = [
+  { id: 'ollama/llama3', label: 'Llama 3 (local)', tier: 'local', provider: 'ollama' },
+  { id: 'ollama/mistral', label: 'Mistral 7B (local)', tier: 'local', provider: 'ollama' },
+  { id: 'ollama/deepseek-coder', label: 'DeepSeek Coder (local)', tier: 'local', provider: 'ollama' },
+  { id: 'ollama/phi3', label: 'Phi-3 Mini (local)', tier: 'local', provider: 'ollama' },
+  { id: 'ollama/qwen2.5-coder', label: 'Qwen 2.5 Coder (local)', tier: 'local', provider: 'ollama' },
+];
+
+export const CLOUD_MODELS: ModelEntry[] = [
+  { id: 'gpt-4o', label: 'GPT-4o', tier: 'cloud', provider: 'openai' },
+  { id: 'gpt-4o-mini', label: 'GPT-4o Mini', tier: 'cloud', provider: 'openai' },
+  { id: 'claude-3-5-sonnet-20241022', label: 'Claude 3.5 Sonnet', tier: 'cloud', provider: 'anthropic' },
+  { id: 'claude-3-haiku-20240307', label: 'Claude 3 Haiku', tier: 'cloud', provider: 'anthropic' },
+  { id: 'gemini-1.5-pro', label: 'Gemini 1.5 Pro', tier: 'cloud', provider: 'gemini' },
+  { id: 'gemini-1.5-flash', label: 'Gemini 1.5 Flash', tier: 'cloud', provider: 'gemini' },
+];
+
+export const ALL_MODELS: ModelEntry[] = [...FREE_MODELS, ...LOCAL_MODELS, ...CLOUD_MODELS];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function providerBadge(entry: ModelEntry): string {
+  if (entry.tier === 'free') return chalk.green.bold('[0-COST]');
+  if (entry.tier === 'local') return chalk.cyan.bold('[LOCAL]');
+  return chalk.yellow.bold('[CLOUD]');
+}
+
+function findModel(id: string): ModelEntry | undefined {
+  return ALL_MODELS.find((m) => m.id === id || m.id.startsWith(id));
+}
+
+// ── Command handlers ──────────────────────────────────────────────────────────
+
+/** /model — show current model */
+export async function handleModelStatus(client: AgentClient): Promise<void> {
+  try {
+    const settings = await client.getSettings();
+    const modelId: string = (settings as Record<string, string>).default_model || '(none)';
+    const provider: string = (settings as Record<string, string>).preferred_provider || '(none)';
+    const entry = findModel(modelId);
+
+    console.log('');
+    console.log(`  ${chalk.hex('#FF8C00').bold('⬡ Modelo Activo')}`);
+    console.log(`  ${chalk.gray('─'.repeat(44))}`);
+    console.log(`  ${chalk.gray('ID')}           ${chalk.white.bold(modelId)}`);
+    console.log(`  ${chalk.gray('Proveedor')}    ${chalk.white(provider)}`);
+    if (entry) {
+      console.log(`  ${chalk.gray('Nombre')}       ${entry.label}`);
+      console.log(`  ${chalk.gray('Nivel')}        ${providerBadge(entry)} ${entry.badge ? DIM(`(${entry.badge})`) : ''}`);
+    }
+    const speed: string = (settings as Record<string, string>).speed_preference || 'balanced';
+    const quality: string = (settings as Record<string, string>).quality_preference || 'balanced';
+    console.log(`  ${chalk.gray('Velocidad')}    ${chalk.cyan(speed)}`);
+    console.log(`  ${chalk.gray('Calidad')}      ${chalk.cyan(quality)}`);
+    console.log('');
+    console.log(DIM('  Usa /model list para ver opciones, /model set <id> para cambiar.'));
+    console.log('');
+  } catch (err) {
+    console.log(RED(`  Error al obtener modelo: ${(err as Error).message}\n`));
+  }
+}
+
+/** /model list — print the full model catalog */
+export function handleModelList(): void {
+  const printSection = (title: string, models: ModelEntry[]): void => {
+    console.log(`\n  ${chalk.hex('#FF8C00').bold(title)}`);
+    console.log(`  ${chalk.gray('─'.repeat(60))}`);
+    for (const m of models) {
+      const badge = providerBadge(m);
+      const extra = m.badge ? DIM(` · ${m.badge}`) : '';
+      console.log(`  ${badge}  ${chalk.white.bold(m.label.padEnd(32))} ${GRAY(m.id)}${extra}`);
+    }
+  };
+
+  console.log('');
+  console.log(`  ${BOLD('🧠 Catálogo de Modelos HELIX')}`);
+  printSection('✦ Nivel 1 — Sin costo (OpenRouter Free)', FREE_MODELS);
+  printSection('✦ Nivel 2 — Local Ollama (sin internet)', LOCAL_MODELS);
+  printSection('✦ Nivel 3 — Nube con API Key propia', CLOUD_MODELS);
+  console.log('');
+  console.log(DIM('  Usa: /model set <model-id>   para activar un modelo'));
+  console.log(DIM('  Usa: /model effort <low|medium|high>   para ajustar esfuerzo'));
+  console.log('');
+}
+
+/** /model set <id> — switch the active model */
+export async function handleModelSet(client: AgentClient, modelId: string): Promise<void> {
+  if (!modelId) {
+    console.log(YELLOW('  Uso: /model set <model-id>\n'));
+    return;
+  }
+
+  const entry = findModel(modelId);
+  const provider = entry?.provider || (modelId.startsWith('ollama/') ? 'ollama' : 'openai');
+
+  try {
+    await client.saveSettings({
+      default_model: entry?.id ?? modelId,
+      preferred_provider: provider,
+    } as Parameters<typeof client.saveSettings>[0]);
+
+    const badge = entry ? providerBadge(entry) : '';
+    console.log('');
+    console.log(GREEN('  ✔ Modelo actualizado correctamente.'));
+    console.log(`  ${chalk.gray('Modelo:')}    ${chalk.white.bold(entry?.id ?? modelId)} ${badge}`);
+    console.log(`  ${chalk.gray('Proveedor:')} ${chalk.white(provider)}`);
+    console.log('');
+  } catch (err) {
+    console.log(RED(`  ✖ Error al cambiar modelo: ${(err as Error).message}\n`));
+  }
+}
+
+/** /model effort <low|medium|high> — set effort/quality level */
+export async function handleModelEffort(client: AgentClient, level: string): Promise<void> {
+  const valid = ['low', 'medium', 'high'];
+  const normalized = level?.toLowerCase();
+  if (!normalized || !valid.includes(normalized)) {
+    console.log(YELLOW('  Uso: /model effort <low|medium|high>\n'));
+    return;
+  }
+
+  const speedMap: Record<string, string> = { low: 'fast', medium: 'balanced', high: 'balanced' };
+  const qualityMap: Record<string, string> = { low: 'fast', medium: 'balanced', high: 'best' };
+
+  try {
+    await client.saveSettings({
+      speed_preference: speedMap[normalized],
+      quality_preference: qualityMap[normalized],
+    } as Parameters<typeof client.saveSettings>[0]);
+
+    console.log('');
+    console.log(GREEN(`  ✔ Nivel de esfuerzo → ${chalk.white.bold(normalized.toUpperCase())}`));
+    console.log(DIM(`  Velocidad: ${speedMap[normalized]}  |  Calidad: ${qualityMap[normalized]}`));
+    console.log('');
+  } catch (err) {
+    console.log(RED(`  ✖ Error al ajustar esfuerzo: ${(err as Error).message}\n`));
+  }
+}
+
+/** /model free-list — list free models fetched from bridge (live) */
+export async function handleFreeModelList(client: AgentClient): Promise<void> {
+  try {
+    const result = await (client as AgentClient & { request: <T>(type: string, payload: unknown) => Promise<T> })
+      .request<{ models: Array<{ id: string; label: string; provider: string }> }>('LIST_FREE_MODELS', {});
+
+    if (!result?.models?.length) {
+      // Fallback to static catalog
+      handleModelList();
+      return;
+    }
+
+    console.log(`\n  ${BOLD('✦ Modelos gratuitos disponibles (live):')} \n`);
+    for (const m of result.models) {
+      console.log(`  ${GREEN('[0-COST]')}  ${chalk.white.bold(m.label)}  ${GRAY(m.id)}`);
+    }
+    console.log('');
+  } catch {
+    // Agent not connected or handler not present — fall back to static
+    handleModelList();
+  }
+}
+
+/** Top-level dispatcher for /model <args> */
+export async function handleModelCommand(client: AgentClient, args: string): Promise<void> {
+  const parts = args.trim().split(/\s+/);
+  const sub = parts[0]?.toLowerCase() || '';
+
+  switch (sub) {
+    case '':
+      await handleModelStatus(client);
+      break;
+    case 'list':
+      handleModelList();
+      break;
+    case 'set':
+      await handleModelSet(client, parts.slice(1).join(' '));
+      break;
+    case 'effort':
+      await handleModelEffort(client, parts[1] || '');
+      break;
+    default:
+      console.log(YELLOW(`  Subcomando desconocido: "${sub}". Opciones: list, set, effort\n`));
+  }
+}